m5 follow-up: close F-18 + F-19; README polish for v0.1.0

[oubiwann]

What

Two pieces of post-merge work for M5, bundled in one small PR:

1. F-18 + F-19 closing evidence — closes the two formally-deferred ledger rows from M5 PR m5: CLI + main wiring (internal/cli + cmd/cascade) #10. Both required a merged commit on main to verify; that prerequisite is now satisfied (M5 merged at 78cc7ae).
2. README polish for v0.1.0 — clean-up pass on the README before any tagged release: typo + sentence rewrite in the Why section, drop a "as of this writing" dev-status hedge, sync the Library example to the M4 v1.1 functional-option signature, add the actual --version output format, clarify the I/O-edges claim.

Where

• docs/dev/0012-implementation-retrospective-m5-cli-main-wiring.md — gains a §"F-18 / F-19 post-merge follow-up evidence" section with the closing evidence + an updated closure summary (22/22 done).
• README.md — five small fixes (described below); Status and Milestones sections were also removed (separate commits) since the v0.1.0 work is done.

F-18 evidence (proxy install)

$ GOBIN=$tmp GOPROXY=https://proxy.golang.org,direct \
    go install github.com/geomyidia/cascade/cmd/cascade@78cc7ae
go: downloading github.com/geomyidia/cascade v0.0.0-20260507180335-78cc7ae2dac9
$ $tmp/cascade --version
cascade 0.1.0 (build @78cc7ae, 2026-05-07T18:03:35Z)
$ $tmp/cascade --help | head -8
cascade — reverse-transitive closure of a Go change-set under the imports relation
[...]

proxy.golang.org indexed the merge SHA cleanly; pseudo-version-extraction logic from M1.5 thread the commit + build date through into --version output (Branch is empty for proxy installs — proxy doesn't carry branch metadata, same as M1's F-12).

F-19 evidence (cascade-against-cascade real-codebase smoke)

Six cases against the merged-to-main cascade repo; every observed affected-set matched the hand-derived prediction:

#	Change-set	Expected	Observed
1	pkg/golist/golist.go (root)	5 packages (golist + depgraph + changeset + internal/cli + cmd/cascade)	match
2	pkg/changeset/changeset.go (mid)	3 packages	match
3	cmd/cascade/main.go (leaf)	1 package	match
4	internal/cli/cli.go (mid)	2 packages (cli + cmd/cascade)	match
5	empty stdin	empty stdout, exit 0	match
6	real --base/--head git diff	empty (mostly docs commits)	match — 134ms wall-clock end-to-end

The 134ms case 6 number measures the full pipeline (git diff subprocess + go list subprocess + depgraph + changeset + RevDepClosure) on the cascade repo's small package set. Generic-framing note in the retro: cascade-against-cascade is the public-PR-safe substitute for the M2 F-18 private-codebase scale evidence.

M5 ledger now sits at 22/22 done.

README polish (5 fixes)

1. Why section, line 19 sentence rewrite. Was: Do the the Go language's tendency to swap out libraries for changes in tooling, treating the tool as "the API" is often the safer, more stable approach. Typo + awkward parsing. Now: Go's helper libraries — especially golang.org/x/tools/go/packages — evolve faster than the go command itself; depending on the CLI tool is the more stable bet. Same intent, clearer prose.
2. Install section "as of this writing" hedge dropped. Now: CI tests against the floor and the latest currently-supported Go major; the matrix advances with each Go release. No timestamp to decay.
3. --version flag description shows actual output format. Was a list of injected fields; now cascade <Version> (build <Branch>@<Commit>, <BuildDate>) with note about empty-Branch on proxy installs.
4. Library example uses M4 v1.1 functional-option signature. Was changeset.Resolve(changedFiles, pkgs) (variadic-empty; relied on os.Getwd fallback); now changeset.Resolve(changedFiles, pkgs, changeset.WithModuleRoot(repoRoot)) with a comment about typical caller usage.
5. "Have no io between them" claim clarified. Now names the two real I/O edges (golist.Run's go list invocation; changeset.Resolve's optional os.Getwd fallback) so the prose matches the actual io-edge inventory. Subsequent commit also normalised "io" → "I/O" capitalisation throughout.

F-20 verify (grep -c 'exit code' README.md) still returns 1; no other dev-status hedges or development-status framings remain in the README.

How to verify

# F-18 install path (clean GOBIN):
tmp=$(mktemp -d); GOBIN=$tmp go install github.com/geomyidia/cascade/cmd/cascade@<merge-sha>
$tmp/cascade --version
$tmp/cascade --help | head -10

# F-19 cascade-against-cascade (built binary):
echo "pkg/golist/golist.go" | $tmp/cascade --changed-files=- --root=/path/to/cascade

# Local smoke for README accuracy:
grep -c 'exit code' README.md   # should return 1
grep -i 'as of this writing\|under active development\|TODO' README.md   # should return nothing

Checklist

• make check passes locally (no code changes; doc-only PR)
• F-20 verify (grep -c 'exit code' README.md) returns 1 (preserved through edits)
• No public-API breakage (this is a doc-only PR)
• Retro's deferral pattern (F-18 + F-19 with explicit re-entry conditions) closed cleanly per LEDGER_DISCIPLINE.md

Breaking change?

No. Doc-only PR; no code changes; CLI behaviour and library API unchanged.

🤖 Generated with Claude Code