docs: refresh README, design.md, project-plan.md for the 0.x surface

[erain]

Summary

The project-level docs were last truthful when the harness shipped P0. Since then P1 + P2 + the agent-ergonomics wishlist (#88–#94) all landed, but the docs still claimed "P0 is complete" with a Roadmap that treated P2 features as upcoming work. Refresh in place.

• README.md — Tagline lists all three providers; Status section enumerates what actually shipped (typed NewTool, WithFailover, WithStreamWriter/WithToolLogger, StopReasonMaxTurns, prompts.NewCatalog, cli.RegisterStandardFlags, tools/fs + tools/git); subpackage list includes the new packages; agents/glue-review reference bumped to v1.1.0; Roadmap rewritten — P0–P2 shipped, current focus pointed at docs/flue-gap-analysis.md.
• docs/design.md — Non-Goals retitled (was "For P0/P1") and rewritten so shipped features read as shipped-but-opt-in. Broken compactor.go link fixed (../compactor.go).
• docs/project-plan.md — Current Status replaced with an accurate P0/P1/P2 ledger plus a "beyond plan" subsection for the agent-ergonomics work and extra providers.

Stacked on #95–#101 (the seven issue PRs). Docs-only — no runtime behavior touched.

Test plan

• go build ./...
• go vet ./...

🤖 Generated with Claude Code

[github-actions]

Summary

This is a large documentation-and-feature branch that lands multiple 0.x agent-ergonomics improvements: typed NewTool[T] + TextResult/ErrorResult helpers, provider registry + WithFailover, event stream helpers (WithStreamWriter, WithToolLogger), StopReasonMaxTurns, a versioned-prompt catalog (prompts.NewCatalog), standard CLI flags (cli.RegisterStandardFlags), and shared extension packages for filesystem and git tools (tools/fs, tools/git). It also refreshes all project docs (README, design.md, project-plan.md, ADRs) to reflect the shipped surface.

Issues

• [major] failover.go:94 — Potential goroutine leak: the goroutine forwarding ch to out in failoverProvider.Stream will block forever if out is never fully consumed by the consumer (e.g. consumer exits early). The goroutine holds a reference to the source channel ch and never has a cancellation signal. Fix: wrap the forwarding goroutine with a select on ctx.Done() and close both out and drain ch on cancellation.

• [major] event_helpers.go:10 — WithStreamWriter wraps an io.Writer with no synchronization. Since events may be delivered concurrently from the loop (or from multiple goroutines downstream), writing to the same io.Writer from multiple goroutines without synchronization can cause interleaved output or data races. Fix: document that the caller must provide a synchronized io.Writer (e.g. os.Stdout which is already OS-synchronized), or wrap the writes with a sync.Mutex inside WithStreamWriter and WithToolLogger.

• [major] event_helpers.go:45 — WithToolLogger has the same unsynchronized io.Writer access issue as WithStreamWriter. Fix: apply the same fix as for WithStreamWriter — either document the synchronization requirement or add internal locking.

• [minor] loop/run.go:141 — The lastAssistantMsg and lastAssistantNew indices are tracked across the loop, but if maxTurns == 0 (meaning the loop body never executes), these remain -1 and the budget-exhaustion tagging is skipped. While this is a degenerate case, it leaves callers without StopReasonMaxTurns when they might expect it. Fix: add an explicit check before the loop: if maxTurns <= 0, return immediately with a clear error, or document that MaxTurns <= 0 is invalid. The current code returns fail(fmt.Errorf("loop: maximum turns exceeded (%d)", maxTurns)) without tagging because the loop never enters.

Suggestions

• [minor] failover.go:62 — failoverProvider.Stream creates a goroutine per successful provider, but there's no way to cancel that goroutine from outside. If a caller calls Stream but never reads from the returned channel, the goroutine leaks indefinitely. The context parameter isn't used for cancellation of the goroutine. Fix: change the forwarding loop to select on ctx.Done() and ch, closing out and draining ch when context is cancelled.

• [minor] prompts/catalog.go:90 — Get performs strings.TrimRight(string(data), "\n"), which will trim all trailing newlines. If a prompt file legitimately ends with multiple blank lines for formatting, they are all collapsed. The doc comment says "trimmed of trailing newlines and re-suffixed with a single newline" — consider trimming only a single trailing newline, or documenting that multiple trailing newlines are intentionally collapsed. Fix: in prompts/catalog.go, change strings.TrimRight(string(data), "\n") to strings.TrimSuffix(string(data), "\n") to remove only the final newline, preserving intermediate blank lines.

• [minor] tools/fs/read_test.go:44 — TestReadFileTool_ReadsAndTruncates uses MaxBytes: 50 but then asserts len(got) != 50. This is testing the implementation of Truncate via ReadFileTool, but Truncate already has dedicated tests in fs_test.go. This makes the read test brittle if Truncate's marker length changes. Fix: keep the test focused on "tool returns non-error result with truncation marker" rather than asserting exact length; remove the len(got) != 50 assertion or replace it with a looser check.

• [minor] providers/registry.go:19 — factories is a package-level map protected by a sync.RWMutex, but Register is meant to be called from init() functions. In Go, init() order within a package is deterministic but across packages it is not. If two provider packages are imported in the same binary, their init() calls race on Register. The sync.RWMutex protects against concurrent goroutine access but does not prevent issues if Register reads the map while another init() writes — though Go's init ordering makes this unlikely in practice, it's still a latent issue if registration ever moves outside init(). Fix: no code change needed, but add a comment in providers/registry.go near var factories documenting that Register is designed for invoked from init() only to set clear expectations.

• [minor] agents/glue-review/tools.go:72 — The agent's readFileTool no longer uses the tools/fs package's ReadFileTool despite it being available in this branch. The commit message for b1e1397 says "Migrating agents/glue-review to use these packages is filed as a follow-up" — this is fine, but the agent's readFileTool still manually implements what fs.ReadFileTool does, including its own blocklist and safe join. Fix: add a TODO comment in agents/glue-review/tools.go above the hand-rolled tool definitions referencing the follow-up migration to tools/fs and tools/git.

Looks good

• Nice use of go test ./... and go vet ./... verification for every commit — this is a good discipline.
• The typed NewTool[T] helper eliminates exactly the right amount of boilerplate without overreaching into schema generation.
• WithFailover's commit-after-first-event semantics are well-documented and preserve the "no half-streamed transcripts" invariant correctly.
• The providers registry design (factory functions, not instantiated providers) keeps registration cheap and side-effect-free.
• tools/fs and tools/git being split out into extension packages per ADR 0003 is a clean boundary.

Open questions

• Do any of the new event helpers (WithStreamWriter, WithToolLogger) need to be registered as session-scoped subscribers via Session.Subscribe, or are they strictly per-prompt? The current implementation adds them to promptConfig.auxEmits which is per-prompt only — this seems intentional but worth confirming.
• Is there a plan for how the agents/glue-review migration to tools/fs and tools/git will be tracked? The commit messages mention follow-ups but there's no linked issue in the branch.

---

🤖 Posted by glue-review.

[github-actions]

[major] Potential goroutine leak: the goroutine forwarding ch to out in failoverProvider.Stream will block forever if out is never fully consumed by the consumer (e.g. consumer exits early). The goroutine holds a reference to the source channel ch and never has a cancellation signal

💡 AI prompt to fix

wrap the forwarding goroutine with a `select` on `ctx.Done()` and close both `out` and drain `ch` on cancellation.

[github-actions]

[major] WithStreamWriter wraps an io.Writer with no synchronization. Since events may be delivered concurrently from the loop (or from multiple goroutines downstream), writing to the same io.Writer from multiple goroutines without synchronization can cause interleaved output or data races

💡 AI prompt to fix

document that the caller must provide a synchronized `io.Writer` (e.g. `os.Stdout` which is already OS-synchronized), or wrap the writes with a `sync.Mutex` inside `WithStreamWriter` and `WithToolLogger`.

[github-actions]

[major] WithToolLogger has the same unsynchronized io.Writer access issue as WithStreamWriter

💡 AI prompt to fix

apply the same fix as for `WithStreamWriter` — either document the synchronization requirement or add internal locking.

[github-actions]

[minor] failoverProvider.Stream creates a goroutine per successful provider, but there's no way to cancel that goroutine from outside. If a caller calls Stream but never reads from the returned channel, the goroutine leaks indefinitely. The context parameter isn't used for cancellation of the goroutine

💡 AI prompt to fix

change the forwarding loop to `select` on `ctx.Done()` and `ch`, closing `out` and draining `ch` when context is cancelled.

[github-actions]

[minor] Get performs strings.TrimRight(string(data), "\n"), which will trim all trailing newlines. If a prompt file legitimately ends with multiple blank lines for formatting, they are all collapsed. The doc comment says "trimmed of trailing newlines and re-suffixed with a single newline" — consider trimming only a single trailing newline, or documenting that multiple trailing newlines are intentionally collapsed

💡 AI prompt to fix

in prompts/catalog.go, change `strings.TrimRight(string(data), "\n")` to `strings.TrimSuffix(string(data), "\n")` to remove only the final newline, preserving intermediate blank lines.

[github-actions]

[minor] TestReadFileTool_ReadsAndTruncates uses MaxBytes: 50 but then asserts len(got) != 50. This is testing the implementation of Truncate via ReadFileTool, but Truncate already has dedicated tests in fs_test.go. This makes the read test brittle if Truncate's marker length changes

💡 AI prompt to fix

keep the test focused on "tool returns non-error result with truncation marker" rather than asserting exact length; remove the `len(got) != 50` assertion or replace it with a looser check.

[github-actions]

[minor] factories is a package-level map protected by a sync.RWMutex, but Register is meant to be called from init() functions. In Go, init() order within a package is deterministic but across packages it is not. If two provider packages are imported in the same binary, their init() calls race on Register. The sync.RWMutex protects against concurrent goroutine access but does not prevent issues if Register reads the map while another init() writes — though Go's init ordering makes this unlikely in practice, it's still a latent issue if registration ever moves outside init()

💡 AI prompt to fix

no code change needed, but add a comment in providers/registry.go near `var factories` documenting that `Register` is designed for `invoked from init() only` to set clear expectations.