Commit 83bf2e6
committed
docs(plan): v4 — agent-journey audit + bundled recipe shelf (D13)
Walked every D / OOS / tracer item against "fully capable + agent
first-class + no half-baked APIs". Found three half-baked surfaces:
1. **D2 deferral leaks "compose GROUP BY yourself" onto the agent.**
Deferring the `file_coverage` table is correct (no benchmark proves
it's needed) — but the agent-facing answer for "rank files by
coverage" was missing. Fix: keep table deferral, ship a bundled
`files-by-coverage.{sql,md}` recipe so the GROUP BY view IS
first-class.
2. **D11 name-collision lossiness was acknowledged but unmitigated.**
The killer recipe's `callee_name = s.name` cross-file lossiness
was documented in the recipe SQL comment, but the recipe `.md`
didn't give the agent any narrowing pattern. Now D11 ships three
concrete narrowing patterns in the `.md` (file_path scope, default-
export filter, exported-only restriction) so the agent has
workable mitigations on day one.
3. **Missing recipe shelf for common agent questions.** Walking the
journey: only "What's structurally dead AND untested?" had a recipe;
"Rank files by coverage" and "Worst-covered exported symbols" forced
ad-hoc SQL. Three recipes fully cover the agent journey end-to-end.
New D13 codifies the bundled-recipe principle: every common agent
question gets a `--recipe` verb. Three v1 recipes:
- `untested-and-dead.{sql,md}` (killer, with name-collision mitigations)
- `files-by-coverage.{sql,md}` (replaces D2's table deferral)
- `worst-covered-exports.{sql,md}` (top-N agent ask)
Each `.md` carries a frontmatter `actions` block (per PR #26) so agents
get per-row follow-up hints. All three appear in `--recipes-json`
automatically — agents discover them at session start.
New "Agent journey" section makes the principle visible: a table mapping
every common agent question to the v1 verb that answers it. If a row
ever shows "compose SQL yourself" without a recipe, the surface is
half-baked and needs a recipe before tracer 1 ships.
Tracer 4 expanded: ships all three recipes + five golden snapshots
(adds files-by-coverage.json + worst-covered-exports.json on top of the
three existing). Tracer 5 expanded: glossary + agent rule trigger
table gain three new rows.
Plan now passes the principle audit end-to-end.1 parent 9e52ffa commit 83bf2e6
1 file changed
Lines changed: 39 additions & 22 deletions
0 commit comments