feat(pipeline): consolidate cycle recon, add fieldtest probe tier, enforce assumption economy

Implements the three efficiency findings from the #310 pipeline
measurement (refs #35): ~691k subagent tokens / ~3.5 h for a
deliberately small cycle, with recon duplication as the single
biggest obligatory per-cycle cost.

1. Cycle recon (pipeline.md § Cycle recon; specify, planner,
   brainstorm, boss, plan-recon): recon fan-out is budgeted per
   cycle, not per phase. One full plan-recon dispatch — normally
   specify Step 1, in a new pre-spec sources/recon_scope carrier
   form — serves both the spec's concrete code shapes and the
   plan's file-map. planner Step 2 becomes reuse-first (freshness /
   quotability / coverage conditions) with narrowly-bounded delta
   dispatches (new Delta dispatch contract in plan-recon.md);
   broad Explore-type grounding sweeps are banned in every mode.
   Field evidence: 151k (Explore) + 99k (plan-recon) with ~40 %
   overlap in one bounded cycle.

2. Fieldtest probe tier (fieldtest, fieldtester, pipeline.md,
   agent-template.md § model rule 2): a cycle whose user-visible
   delta is a single narrow axis dispatches the per-cycle
   fieldtest at tier: probe — 1-2 examples on exactly that axis,
   ~200-word report, explicit model:sonnet dispatch override (no
   dispatch-level effort override exists; frontmatter effort
   applies). Probe is a tier, not a skip; the milestone fieldtest
   always runs full tier on the frontmatter model, keeping the
   milestone-close gate's >=2-example floor unconditional.

3. Assumption economy (specify Step 3 + self-review item 6):
   grounding-check cost scales with the spec's assumption count,
   so specs state current-behaviour claims only where the change
   relies on them (the gate's own falsity test), demote
   context-only mentions to ledger citations, and keep iteration
   scope tight — fewer restatements, never fewer reliances. The
   gate itself is unchanged.

Design reviewed pre-implementation (opus plan review); diff
adversarially verified by a 3-lens review workflow (consistency,
operability, cross-reference), confirmed findings folded in.

refs #35
This commit is contained in:
2026-07-25 13:52:04 +02:00
parent b2c92db725
commit fe5ca8f8c0
9 changed files with 353 additions and 67 deletions
+58 -4
View File
@@ -113,6 +113,26 @@ Before producing anything, establish what the sources actually say:
walk to the contracts the work touches. Note any `status:
aspirational` source: its code is a target, not verified fact.
**Grounding fan-out — the cycle recon.** When the work enters code
territory the orchestrator has not recently read, dispatch
`../planner/agents/plan-recon.md` **once**, in its pre-spec form —
carrier fields (`sources`, `recon_scope`, optional `focus_hint`)
defined authoritatively under its **Pre-spec dispatch (cycle
recon)** heading. When the sources already settle the change shape
(a signature change, a variant add / remove, a symbol removal, a
content-pin perturbation), name it in `recon_scope`: that arms the
compile-driven enumeration inside the cycle recon and saves
`planner` a mandatory delta later. The returned file-map grounds
Step 2's criterion evidence and Step 3's `## Concrete code
shapes`, and is reused downstream by `planner` — budget, reuse
conditions, and delta triggers are defined once in
`../docs/pipeline.md` § Cycle recon. A `brainstorm`-fired dispatch
that meets that section's coverage condition IS the cycle recon —
do not dispatch again. Do NOT ground a spec with a broad
Explore-type sweep (§ Cycle recon's ban; field evidence on issue
#35: a 151k-token Explore sweep here, ~40 % duplicated by the
later plan-recon).
### Step 1.5 — Precondition gate (bounce-back)
Enumerate the **load-bearing design decisions** the spec must encode
@@ -312,6 +332,24 @@ follows as an explicitly secondary subsection, never first. Prose may
*explain* code, never *replace* it. Exact bytes / line-numbers remain
the planner's job — the spec owns the *shape*, shown.
**Assumption economy — fewer restatements, never fewer reliances.**
Every assertion the spec makes about *current* codebase behaviour is
a load-bearing-assumption candidate the Step-5 `grounding-check`
must extract and ratify — the gate's cost scales with the count, and
it BLOCKs an over-broad spec outright (`agents/grounding-check.md`).
So: state a current-behaviour claim only where the change actually
relies on it (the gate's test: its falsity would make the change
fail or cost additional work), and render context-only mentions of
existing mechanisms as a design-ledger contract citation instead of
restating their behaviour. This trims *restatements*, never *reliances*: a
mechanism the change builds on remains an assumption — explicit, or
the implicit form the gate extracts anyway — and writing it as a
bare citation does not exempt it; hiding a reliance is exactly the
failure the gate exists to catch. The same economy applies to scope:
a tightly-cut iteration makes fewer claims than a sprawling one
(field evidence on issue #35: gate cost tracks the spec's assumption
count near-linearly).
### Step 4 — Self-review
Inline checklist (not a subagent dispatch):
@@ -328,6 +366,16 @@ Inline checklist (not a subagent dispatch):
carry before → after code for every load-bearing change (plus the
worked user-facing example for a surface cycle)? A load-bearing
change described only in prose is a self-review failure to fix.
6. **Assumption economy:** scan every claim about current codebase
behaviour. The gate's own criterion decides which stay: a claim
is a *reliance* iff its being false would make the proposed
change fail or require additional work
(`agents/grounding-check.md` § What "load-bearing assumption"
means). Non-reliances are gate cost with no return — delete
them, or demote them to a citation that carries no behaviour
claim. Never demote a reliance: a bare citation does not ratify
it, and the gate BLOCKs on it unratified (Step 3's
restatements-vs-reliances line).
Fix issues inline.
@@ -497,6 +545,7 @@ is narrow by design: only the user's-call forks bounce, not every fork.
|-----------|---------|
| user / issue (design settled) → `specify` | the sources: issue body, in-context design discussion, design docs |
| `brainstorm``specify` | ratified design narrative (approaches chosen, constraints, sections approved) — in-context; brainstorm writes no spec file |
| `specify``plan-recon` (Step 1, the cycle recon — skipped when a brainstorm-fired dispatch meets the coverage condition) | `sources` + `recon_scope` + optional `focus_hint`; defined authoritatively under **Pre-spec dispatch (cycle recon)** in `../planner/agents/plan-recon.md` |
| `specify``grounding-check` (Step 5) | `spec_path` (absolute) + `iteration_scope` |
| `specify``spec-skeptic` bias-breaker (Step 1.5, optional, orchestrator's call) | `spec_path` (absolute) + `iteration_scope` + one `lens` + `seeding_issue` (or `none`); dispatched ad hoc for a fork the orchestrator is deciding, never as a gate |
| `specify` → reference issue (Step 1.5) | a derived-decision comment (rationale) or user-decision comment (provenance); a freshly created seeding issue if the cycle had none |
@@ -515,6 +564,7 @@ is narrow by design: only the user's-call forks bounce, not every fork.
| "The shape is clear from the prose, I don't need to paste the code" | If it's clear, pasting it is free; if pasting it is hard, it wasn't clear. The acceptance criterion is unjudgeable without the worked code. |
| "Just polishing a wording after PASS, no need to re-dispatch" | The grounding-check report attests to specific bytes. A polish edit changes the bytes; the attestation no longer covers them. Re-dispatch is cheap. |
| "It's in a model doc / the design ledger, so it's canonical" | A `models` / RFC / proposal doc holds aspirational code — a target, not verified fact. Flag code lifted from a `status: aspirational` source as such; it is not ratified contract. |
| "Fewer assumptions = a cheaper grounding-check, so I'll phrase the reliances as vague citations" | Economy cuts *restatements*, not *reliances*. A mechanism the change builds on stays a claim — vague phrasing merely converts it to the implicit form the gate extracts anyway, or worse, hides a false premise until a downstream iteration BLOCKs on it. Trim what the change does not rest on; never what it does. |
| "In `/boss` this spec looks solid — I'll sign and move on" | Your sense that it looks solid is not the signature. Under `/boss` the signature is the Step-5 `grounding-check` `PASS` — an independent agent's verdict, not your confidence. Run the grounding-check; a no-override `BLOCK` routes to the human, never auto-signed over. |
| "A grounding `BLOCK` looks like a false alarm — I'll sign over it" | With no human in the loop there is no override. A no-override grounding `BLOCK` is the one objective denial of an autonomous sign; it routes to the human sign-off pause. The whole point of trusting grounding-PASS as the signature is that you also honour its `BLOCK`. |
@@ -543,6 +593,9 @@ is narrow by design: only the user's-call forks bounce, not every fork.
- Jumping straight from spec to `implement` (must go via `planner`)
- Running an interview here (that is `brainstorm`'s job — if the work
needs one, bounce)
- Grounding the spec with a broad Explore-type sweep — or a second
full recon dispatch when a cycle recon already exists
(`../docs/pipeline.md` § Cycle recon)
## Cross-references
@@ -566,9 +619,10 @@ is narrow by design: only the user's-call forks bounce, not every fork.
unanimous five-lens auto-sign panel is retired (baseline tag
`pre-autosign-rework`); the autonomous signature is now the Step-5
`grounding-check` `PASS`.
- **Ad-hoc dispatch.** The orchestrator MAY also ad-hoc dispatch
`../planner/agents/plan-recon.md` during Step 1 when the work enters
code territory not recently read; discretionary, not part of the
standard process.
- **Cycle recon (Step 1).** `../planner/agents/plan-recon.md` in its
pre-spec form is the cycle's ONE full recon dispatch when the work
enters code territory not recently read; its report also serves
`planner` downstream. Budget, reuse conditions, and delta triggers:
`../docs/pipeline.md` § Cycle recon.
- **Project feature-acceptance criterion:** declared in the project's
`CLAUDE.md`. Applied prospectively in Step 2.