@garygentry/feature-forge 0.3.6 → 0.3.8

package/adapters/gemini/references/stage-exit-protocol.md

@@ -90,7 +90,7 @@ resolves before running the command, exactly as elsewhere.
 **Close this stage with the Scripted Stage Exit** (contract: `references/stage-exit-protocol.md`; do not improvise a "Next steps" list). Run:
 
 ```bash
-R="$(bash -c 'for d in "${FEATURE_FORGE_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
+R="$(bash -c '[ -z "${FEATURE_FORGE_ROOT:-}" ] || [ -x "$FEATURE_FORGE_ROOT/scripts/forge-root.sh" ] || { echo "feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts/forge-root.sh" >&2; exit 2; }; for d in "${FEATURE_FORGE_ROOT:-}" "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
 [ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
 python3 "$R/scripts/forge-session.py" stage-exit {stage-exit-args} --specs-dir "{specsDir}" --host generic --verify-capability "{verify-capability}"
 ```
@@ -116,10 +116,15 @@ prose). Nothing else.
 
 **`--verify-capability interactive`** is passed only when **both** of these hold:
 
-- **(a)** a question mechanism equivalent to the host's question mechanism is available, **and**
+- **(a)** a question mechanism equivalent to host's question mechanism is available, **and**
 - **(b)** a clean-room `forge-verifier` subagent can be dispatched.
 
-If either is absent, or capability cannot be established, pass `manual`.
+If either is absent, or capability cannot be established, pass `manual`. **(a) is rung 1 or
+rung 2** of the Interaction Capability Ladder (`references/shared-conventions.md`); at
+rung 3, (a) is false by definition, so `--verify-capability manual` follows without
+further deliberation — the ladder's "verify-capability determination" class states this
+rung-3 default once
+so it is never re-derived per stage.
 
 **(b) tests PERMISSION, not tool presence.** The question is not "is a subagent-dispatch
 tool listed in my tool surface" but "**may I dispatch `forge-verifier` right now**". A
@@ -192,7 +197,7 @@ The dispatching caller states ownership in its invocation prompt using a literal
   terminal block.
 
 **Absent the token, the skill treats itself as `direct`.** A user-typed
-`/feature-forge:forge-verify` or `/feature-forge:forge-fix` is the only path that carries
+`forge-verify` or `forge-fix` is the only path that carries
 no dispatcher, so "no token" and "no dispatcher" are the same condition. The skill passes
 the resolved value straight through as `--owner direct|nested`.
 
@@ -391,7 +396,7 @@ features. The script has already folded the routing into the NEXT-STEPS block, s
 directive is informational — you do **not** re-derive the wording:
 
 - `required: true` (at least one `blocksCurrent: true` request) — the reconcile command
-  (`/feature-forge:forge-0-epic {epic}`) is promoted ahead of the ordinary production
+  (`forge-0-epic {epic}`) is promoted ahead of the ordinary production
   successor, and that successor is demoted to a follow-up line ("After reconciling,
   continue the pipeline with …"). This is *reconcile-before-specs*: proceeding would author
   artifacts against a decomposition that is about to change. It is strongest when exiting
@@ -420,7 +425,7 @@ a `deferredDecisions[]` entry on this feature's `.pipeline-state.json` by runnin
 epic member — required, per the Pipeline State Protocol in `references/shared-conventions.md`:
 
 ```bash
-R="$(bash -c 'for d in "${FEATURE_FORGE_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
+R="$(bash -c '[ -z "${FEATURE_FORGE_ROOT:-}" ] || [ -x "$FEATURE_FORGE_ROOT/scripts/forge-root.sh" ] || { echo "feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts/forge-root.sh" >&2; exit 2; }; for d in "${FEATURE_FORGE_ROOT:-}" "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
 [ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
 python3 "$R/scripts/forge-session.py" state-decision \
   --feature "{feature}" --question "<phrased for the target stage>" \
@@ -440,7 +445,17 @@ sentinel `─ forge: end of stage ─`, as the **final line** of `nextSteps`. Pr
 **verbatim as your absolute last output**. Nothing follows the sentinel — no summary, no
 sign-off, no warning, no command result, no acceptance text, no caveat. The block already
 carries the fresh-session recommendation (host-aware wording via `--host`) and the exact
-next command, so trailing prose can only push the user's next action out of view.
+next command — or, at the one terminal state below, the statement that there is none — so
+trailing prose can only push the user's next action out of view.
+
+**A finished epic ends the pipeline, and its block fences nothing.** When
+`primaryCommand` is `null` (`nextCommand` and `nextStage` are `null` too), the epic is
+complete — every member done, or the manifest set to `status: "complete"` — and there is no
+next command at all. Print the block exactly as you would any other; do **not** substitute a
+command, promote `nextCommand`, or append your own "you could now run…" list. The block's own
+prose already names the optional follow-ons (start a new feature, re-open the dashboard to
+inspect state) as inline offers rather than instructions. Re-fencing the epic dashboard here
+is the specific defect this state exists to prevent: running it lands back on this same exit.
 
 **A nested payload** (`terminalOwnedBy: "outer"`) carries `nextSteps: null` and
 `sentinel: null`. It prints **no terminal block at all** — not even an empty one. Return

package/adapters/gemini/references/templates/root-hygiene/AGENTS.md

@@ -0,0 +1,14 @@
+# Agent Instructions
+
+## Tooling feedback (feature-forge / rauf)
+
+This project is driven by the feature-forge pipeline and the rauf loop. Help improve those tools by capturing friction as you hit it — papercuts included, not just outright bugs.
+
+- **When to flag:** any forge/rauf command, skill, agent, or prompt that is confusing, buggy, missing a capability, forces a workaround, or produces a surprising result.
+- **Where to file** — route by which tool the friction is with:
+  - feature-forge (pipeline stages, forge skills/agents): https://github.com/garygentry/feature-forge/issues
+  - rauf (the autonomous loop runner, `rauf` CLI): https://github.com/garygentry/rauf/issues
+- **How:** capture it while fresh — *what you ran / what you expected / what actually happened / a fix idea* — then propose a titled issue and file it with `gh issue create` **on the human's go-ahead, not silently.**
+- **In an autonomous rauf iteration:** do **not** open issues mid-loop. Note the friction in `progress.md` for the human to triage later.
+
+This file was generated by feature-forge. Edit or remove it to suit your project.

package/adapters/gemini/references/templates/root-hygiene/CLAUDE.md

@@ -0,0 +1,14 @@
+# Claude Instructions
+
+## Tooling feedback (feature-forge / rauf)
+
+I'm driving this project with the feature-forge pipeline and the rauf loop, and I want to keep improving them. When you hit friction with either tool, help me capture it — papercuts included, not just outright bugs.
+
+- **When to flag:** any forge/rauf command, skill, agent, or prompt that is confusing, buggy, missing a capability, forces a workaround, or produces a surprising result.
+- **Where to file** — route by which tool the friction is with:
+  - feature-forge (pipeline stages, `forge-*` skills, forge skills/agents): https://github.com/garygentry/feature-forge/issues
+  - rauf (the autonomous loop runner, `rauf` CLI): https://github.com/garygentry/rauf/issues
+- **How:** capture it while fresh — *what you ran / what you expected / what actually happened / a fix idea* — then propose a titled issue and file it with `gh issue create` **once I give the go-ahead, not silently.**
+- **In an autonomous rauf iteration:** don't open issues mid-loop. Note the friction in `progress.md` for me to triage later.
+
+This file was generated by feature-forge. Edit or remove it to suit your project.

package/adapters/gemini/references/templates/specs-hygiene/AGENTS.md

@@ -26,7 +26,9 @@ Friction with the feature-forge pipeline or the rauf loop — anything confusing
 missing? Capture it while fresh and file it (feature-forge →
 https://github.com/garygentry/feature-forge/issues, rauf →
 https://github.com/garygentry/rauf/issues). See the project-root `AGENTS.md` "Tooling
-feedback" section for the full flow. In an autonomous rauf iteration, note it in
+feedback" section for the full flow (written by forge-init or forge-bootstrap). If it is
+absent, run the feature-forge `forge-init` skill however this host invokes skills, or copy the
+section from another forge project. In an autonomous rauf iteration, note it in
 `progress.md` instead of opening an issue mid-loop.
 
 This file was generated by feature-forge. Edit or remove it to suit your project.

package/adapters/gemini/references/templates/specs-hygiene/CLAUDE.md

@@ -25,7 +25,8 @@ Friction with the feature-forge pipeline or the rauf loop — anything confusing
 missing? Help me capture it while fresh and file it (feature-forge →
 https://github.com/garygentry/feature-forge/issues, rauf →
 https://github.com/garygentry/rauf/issues). See the project-root `CLAUDE.md` "Tooling
-feedback" section for the full flow. In an autonomous rauf iteration, note it in
+feedback" section for the full flow (written by forge-init or forge-bootstrap; if absent,
+run `forge-init`). In an autonomous rauf iteration, note it in
 `progress.md` instead of opening an issue mid-loop.
 
 This file was generated by feature-forge. Edit or remove it to suit your project.

package/adapters/gemini/references/verifier-patterns/MEMORY.md

@@ -0,0 +1,35 @@
+# Verifier Patterns — Index
+
+Shipped, reviewed verification heuristics for the forge verifier — general craft that
+transfers to any project the pipeline runs in. This is the **versioned, reviewed** layer;
+it is distinct from the verifier's per-project `memory:` store, which accumulates
+repo-specific observations locally. Read this index on start and open the patterns a given
+mode makes relevant.
+
+## Claim-checking
+
+- [Spec Literals Are Filesystem Claims](pattern_spec_literals_are_claims.md) — every id, path, constant and signature a spec writes down is an assertion about the repo; verify them mechanically, they survive multiple rounds otherwise
+- ["X does not exist" claims](pattern_absence_claims.md) — the one finding shape whose fix DELETES correct content; search the identifier, not the prose word
+- ["Extend the existing X" / "X does NOT do Y"](pattern_extend_the_existing.md) — the two tech-spec claim shapes that are wrong often enough to check every time; open the function, not the comment
+- [Test-Count Units](pattern_test_count_units.md) — a spec's "N tests" means pytest-COLLECTED, not `def` count; `--collect-only -q` before filing any size-claim error
+- [Enum/Count Vocabulary Ripple](pattern_enum_vocabulary_ripple.md) — "one new enum value, rest derives" always under-lists surfaces; grep the OLD value across the whole tree, not the spec's file list
+
+## Guard / mutation verification
+
+- [Proximity-Window Drift Guards](pattern_proximity_window_guards.md) — never trust a "token near call site" guard on baseline-green; delete each token line one at a time and report every miss
+- [Guard Substitutions: Measure Detection](pattern_guard_substitution_detection.md) — "structural beats tuned" is a maintainability claim; run the own-mandate mutation census and replay the deleted constant's recorded incident
+- [Self-Referential Mutation Controls](pattern_self_referential_control.md) — a control whose mutation span comes from the function under test stays green under the very degradation it bounds; execute every "must FAIL when X degrades" checkbox
+- [Vacuous Self-Reading Tests](pattern_vacuous_self_reading_tests.md) — `read(Path(__file__))` + positive substring is vacuous; demand the failing assertion's LINE NUMBER, mutate one property at a time
+- [Scratch-Root Probes](pattern_scratch_root_probes.md) — symlinked `tests/` resolves back to the real repo and reads false GREEN; real-copy what you mutate, check `df`, always add an effectiveness control
+
+## Re-verifying an applied fix
+
+- [Post-Fix Re-Verify Shapes](pattern_postfix_reverify.md) — fixes introduce new defects; `ls` any claimed deletion (a gitignored file leaves `git status` clean and the fix believes it worked)
+- [Judging Deliberate Deviations](pattern_deviation_judgment.md) — reproduce the fix pass's stated justification first, then attack the deviation on its own terms; prescribed fixes are sometimes worse
+- [Mechanical Rewrite Damage](pattern_mechanical_rewrite_damage.md) — a bulk-edit fix pass measures itself with its own regex; re-derive with a looser pattern, scan for column-0 punctuation, word-diff every hunk
+- [Carve-Out Sibling Semantics](pattern_carveout_sibling_semantics.md) — when a fix carves ONE form out of a blanket claim, re-probe every sibling that shares the property
+
+## Count / arity drift
+
+- [Stale Counts After a Split](pattern_stale_counts_after_split.md) — splitting a construct N ways leaves "two/three/both" scattered in banners and docstrings; grep the number words after any arity change
+- [Sibling Docstring Sweep](pattern_sibling_docstring_sweep.md) — a mirrored guard updates exactly one of N docstrings; grep the *superseded* rationale the amended one disclaims

package/adapters/gemini/references/verifier-patterns/pattern_absence_claims.md

@@ -0,0 +1,36 @@
+---
+name: pattern-absence-claims
+description: "\"X does not exist\" is the highest-cost finding shape a verifier can get wrong — it induces a fix that DELETES correct content; prove absence with identifier-aware search, never a prose-word grep"
+metadata:
+  type: reference
+---
+
+Before filing any finding whose claim is **"the named thing does not exist"**, prove the
+absence with a search that matches the way the thing would actually be spelled in code —
+not the way the spec spells it in prose.
+
+**Why:** a false-positive absence claim is uniquely expensive. Every other bad finding
+adds noise; this one induces a fix that *removes* correct content, and the loss is
+invisible afterwards. The classic miss: a spec quotes a test "the 'exactly the five'
+test", the verifier greps the standalone word `five`, finds nothing, and declares the
+test absent — but the word lived inside a snake_case identifier
+(`test_accepts_exactly_the_five_outcomes`), which a word-boundary grep never sees. The
+fix pass believes the finding and deletes the correct sentence.
+
+**How to apply:**
+
+- Grep the token **unanchored and case-folded**, then again split on `_`/`-`/camel
+  boundaries: `grep -rin 'five' tests/` before concluding, not `grep -n '\bfive\b'`.
+  Prose words routinely live inside identifiers.
+- Prefer searching for the **structure** over the phrase: for "a test that enumerates the
+  outcomes", grep the symbol the test must consume (the enum/constant name) and read every
+  hit. That usually finds it in one call.
+- A spec phrase in quotes ("exactly the five") is usually a *paraphrase of an identifier*,
+  not a literal string in the file. Convert it to snake_case and search that too.
+- If you still cannot find it, say **"I could not locate it; confirm before deleting"**
+  and file at `improvement`, never a confident `inconsistency`/`error` whose fix is a
+  deletion. Absence findings should carry the search you ran, so the fixer can re-run it.
+
+**Re-verify corollary:** when a prior round's finding said "does not exist" and the fix
+removed prose, re-run the absence search yourself first. That is the single highest-yield
+check on a re-verify — see [[pattern-postfix-reverify]].

package/adapters/gemini/references/verifier-patterns/pattern_carveout_sibling_semantics.md

@@ -0,0 +1,34 @@
+---
+name: pattern-carveout-sibling-semantics
+description: When a fix carves ONE enumerated form out of a blanket claim for a semantic property, every sibling form sharing that property must be re-checked
+metadata:
+  type: reference
+---
+
+When a fix pass carves ONE member out of an enumerated "these forms all do X" list because
+that member actually does something else, EVERY other member of the list is a suspect for
+the same defect.
+
+**Why:** a blanket claim ("each of these binding forms was probed and confirmed to leave
+the roster displaced") gets sharpened by carving out the one member that unbinds instead —
+but sibling forms sharing the same semantics stay wrongly inside the set. A concrete
+Python example: a set of "these all displace the module-scope roster" left in both
+`except … as NAME` (Python 3 / PEP 3110 implicitly `del`s the exception target at end of
+block → NameError on a later read — `del`'s exact twin) and a comprehension target (Python
+3 comprehensions have their own scope; the loop variable does NOT leak to module scope → the
+roster is left INTACT, never displaced). The sharpened blanket was still false for two of
+the listed forms.
+
+**How to apply:** the moment a fix carves out member M for property P, run the SAME probe
+over every remaining member. For roster/binding decoys specifically: `except…as` unbinds
+like `del`; list/set/dict-comprehension targets don't leak in py3 (probe with a subsequent
+module-scope READ, not just a namespace `.get`, which masks unbound-vs-None); `import…as`
+binds a module/non-iterable unless a `from … import x as` names the right type. Also
+cross-check the fix's acceptance matrix: if it re-probed only K of N listed forms, the
+un-probed forms are exactly where the residue hides.
+
+When a carve-out is applied as an explicit **partition** of the forms by their semantics
+(displaced decoys / scope-local no-leak / unbinds-or-non-iterable), that partition is the
+confirmed-correct shape — if a future round touches it, preserve the partition rather than
+re-collapsing to a blanket. Related: [[pattern-sibling-docstring-sweep]],
+[[pattern-postfix-reverify]].

package/adapters/gemini/references/verifier-patterns/pattern_deviation_judgment.md

@@ -0,0 +1,36 @@
+---
+name: pattern-deviation-judgment
+description: How to judge a fix pass's deliberate deviation from a prescribed fix — reproduce its stated justification first, then attack the deviation on its own terms
+metadata:
+  type: reference
+---
+
+When a fix pass records a deliberate deviation from a finding's prescribed fix, judge it
+on the merits, not on conformance — and in this order.
+
+**Why:** a prescribed fix is sometimes actively worse than what shipped (a prescribed
+merged clause that does not catch its own stated mutation). A verifier that graded
+deviations as non-compliance would force a regression. Conversely, blanket trust misses
+that the *unchanged* half of the same guard still carries the defect.
+
+**How to apply:**
+
+1. **Reproduce the stated justification with your own instrument.** If a justification
+   does not reproduce, the deviation is a finding regardless of how reasonable it sounds.
+2. **Ask what the finding's argument actually rested on**, not what its code snippet said.
+   If the finding argued from an internal inconsistency and the applied half closed exactly
+   that inconsistency, the withheld half was cost without benefit.
+3. **Then attack the deviation on its own terms.** For an added guard fragment, the
+   discriminating questions are: does it occur only inside the scoped region? does the
+   *natural* misreading delete it? is the attack that beats it one that beats every
+   fragment equally (then it does not distinguish)? A contrived double-negation defeats
+   any substring guard and proves nothing.
+4. Report a per-deviation **verdict** section, separate from findings, so a reader can see
+   the deviation was adjudicated rather than silently accepted.
+
+**A deviation that NARROWS the finding's cited scope is often the finding being
+corrected.** When a finding quotes a WARNING naming decorators "in §3.2, §6.2 and §7.2"
+and the fix names only two of the three, grep the document: the finding may have inherited
+a mis-citation from the very WARNING it was retiring. **Never grade a narrowing against the
+finding's section list; grade it against the artifact.** Count the construct the list
+claims to enumerate.

package/adapters/gemini/references/verifier-patterns/pattern_enum_vocabulary_ripple.md

@@ -0,0 +1,43 @@
+---
+name: pattern-enum-vocabulary-ripple
+description: A spec adding one value to a shared enum (or one item to a counted set) always under-lists the ripple surfaces; enumerate them from the repo, never from the spec's file list
+metadata:
+  type: reference
+---
+
+When a tech-spec says "one new enum value, the rest derives automatically", treat the
+module-structure file list as a *hypothesis* and re-derive the ripple set yourself. A
+single enum addition routinely touches far more than the definition site and one test:
+
+- the `Literal`/type declaration **and** any lookup tables keyed on it;
+- **contract/reference docs** that carry a table of the enum's domain — routinely omitted
+  from spec file lists;
+- the owning skill's **body**, which often carries a *duplicate copy* of the domain. Where
+  a test derives the domain from canon and asserts each value's literal appears in the
+  skill's exit surface, "pointer-only body edits" is provably false for any enum addition;
+- **mirrored copies in the tests** (a second dict of the same enum, plus derivations off
+  it);
+- shipped **docs** (a rendered table of the domain).
+
+Same shape for **counts**, not just enums: a new checklist entry must update *every* count
+string that names the total (a dispatch-table count AND a totals-line count are two
+literals), plus any test that asserts those literals.
+
+Two surfaces spec file-lists reliably miss:
+
+- **A new helper script a skill invokes at runtime must be registered wherever the adapter
+  build enumerates runtime helpers** — otherwise a generated bundle ships a skill calling a
+  script that isn't there, and a test that hard-pins the helper count goes red for whoever
+  implements it.
+- **A new check section in a large mode's checklist needs a home in the parallel fan-out
+  dimension groups.** A spec that says "numeric totals only" leaves the new checks owned by
+  no dimension, so a fan-out dispatch silently never executes them.
+
+**Why:** specs repeatedly list only the definition site and one test file, leaving the
+verification suite red for whoever implements it.
+
+**How to apply:** in tech mode, for every "new value / new check / new probe", grep the
+*old* value across the source, reference, test, eval, and doc trees (excluding generated
+mirrors) and diff the hit list against the spec's module-structure section. Every unlisted
+hit is a `gap`. Where a test asserts **exact list equality** of a set (e.g. the probes a
+dispatcher fans out to), that is another pinned surface the addition must update.

package/adapters/gemini/references/verifier-patterns/pattern_extend_the_existing.md

@@ -0,0 +1,31 @@
+---
+name: pattern-extend-the-existing
+description: "…the existing X is extended" and "X does NOT do Y" are the two tech-spec claim shapes that are wrong often enough to check every time; open the function, not the comment
+metadata:
+  type: reference
+---
+
+Two claim shapes in tech-specs that are wrong often enough to check every time:
+
+1. **"the existing <check/step> is extended (one-line pointer)"** — verify the check
+   actually exists *on the side the spec proposes to edit*. A recurring miss: a spec claims
+   a skill has "an existing pre-flight dirty-tree check", when what exists is another
+   process's own launch refusal, merely *narrated* by the skill. The skill cannot rewrite a
+   message another process emits, so the requirement needs a NEW step and real body lines —
+   not a pointer. Grep the skill's own step list (`### N. …`) before accepting the claim.
+
+2. **"<existing command> does NOT do Y"** — a negative capability claim used to justify
+   building a replacement. Open the implementation. A negative claim ("the subcommand does
+   NOT clear the flag", used to justify a whole new subcommand + version floor) is exactly
+   the kind nobody re-checks — and the function may already do Y in *both* its branches and
+   say so in its header comment.
+
+**Why:** both shapes shrink the apparent cost of a change, so they slip past review — and
+both land in the *decision* rationale, not just prose, so they are `error`-severity, not
+cosmetic.
+
+**How to apply:** for shape 1, list the skill's actual steps; for shape 2, read the
+function body AND the sibling "all items" branch (the single-item branch alone is not the
+contract). Cross-check against any "prefer existing surfaces" list in the PRD — an
+unevaluated named surface is part of the same finding. Related:
+[[pattern-spec-literals-are-claims]].

package/adapters/gemini/references/verifier-patterns/pattern_guard_substitution_detection.md

@@ -0,0 +1,34 @@
+---
+name: pattern-guard-substitution-detection
+description: When a spec replaces a tuned-window guard with a "structural" one, measure DETECTION power by mutation — maintainability arguments hide strict losses
+metadata:
+  type: reference
+---
+
+When a spec replaces a guard mechanism (proximity window, line offsets, tuned constants)
+with a "structural" or "principled" alternative, the spec will argue the substitution on
+**maintainability** ("nothing to tune", "moves with the text"). That argument is usually
+true and completely beside the point. **Measure detection power separately, by mutation.**
+
+**Why:** a heading-bounded block scan that replaces a lookbehind/lookahead window can have
+an identical baseline (all tests pass on both) and still go blind at most sites — a
+neighbour's mandate in the same section keeps the region green. Worse, the constant being
+deleted often carried a docstring recording the *exact* historical incident that narrowed
+it; the substitution reopens that precise hole, and the spec never mentions it.
+
+**How to apply:**
+
+1. Baseline-green is not evidence. Both mechanisms passing today says nothing.
+2. Run the **own-mandate mutation census**: for each protected site, strip the token that
+   belongs to *that site* (use the old mechanism's window as the definition of "belongs"),
+   then ask whether the new mechanism still passes. Report `N blind / M`.
+3. **Read the deleted constant's docstring for recorded incidents.** A tuned constant that
+   was narrowed is a bug report. Replay it against the replacement.
+4. Check whether the spec also deletes the test that *bounds* the old mechanism's width.
+   Removing the machinery legitimately removes its tuning tests — but if nothing replaces
+   the *protection* those tests conferred, that is a gap regardless of the requirement
+   authorizing the deletion.
+5. A widened region is a **silent** failure: guards do not fail when they stop
+   discriminating. This is why it must be probed, never reviewed.
+
+Related: [[pattern-proximity-window-guards]], [[pattern-spec-literals-are-claims]].

package/adapters/gemini/references/verifier-patterns/pattern_mechanical_rewrite_damage.md

@@ -0,0 +1,30 @@
+---
+name: pattern-mechanical-rewrite-damage
+description: When a fix pass reports "N mechanical edits", re-derive the count with a wider regex and scan the touched text tokens for column-0 punctuation and collapsed whitespace — the strip script's own pattern is never the audit
+metadata:
+  type: reference
+---
+
+A fix pass that reports a bulk mechanical edit ("192 parentheticals removed, 0 remaining")
+is reporting **its own script's** measurement. Two failure modes recur, and neither is
+visible to a linter, the test suite, or a drift check, because the damage lands inside
+docstrings and comments where the language does not care.
+
+**Why:** a line-by-line strip regex eats the wrong whitespace and produces column-0
+docstring corruptions (a bare `.`, `, never by the successor table:`) or word merges
+(`from .config.json` → `from.config.json`), while the "0 remaining" is measured with the
+finding's own grep — which required a literal space and never saw the surviving backticked
+variants. All of it then propagates verbatim into every generated mirror, and the full
+gate stays green.
+
+**How to apply:** for any bulk-rewrite step, do three things before believing the count.
+
+1. **Re-run the detection regex in a *looser* form than the fix used** — vary quoting,
+   backticks, and separators — and diff the counts against the base commit, not against
+   zero.
+2. **Tokenize the edited files** (`tokenize` for STRING/COMMENT) and grep those lines for
+   `^\s*[.,;:]`, collapsed `\w\.\w`, empty parens, and orphan section signs.
+3. **Do a whitespace-normalized *word-level* `difflib` diff** of old vs new and read every
+   non-equal opcode. That is what proves "delete the parenthetical, keep the sentence" was
+   honored, and it is also the cheapest way to prove a re-wrap (reclaiming lines against a
+   line cap) dropped nothing. Trust the word diff, not the fix note.

package/adapters/gemini/references/verifier-patterns/pattern_postfix_reverify.md

@@ -0,0 +1,82 @@
+---
+name: pattern-postfix-reverify
+description: Re-verifying an applied fix pass — the defect shapes fixes reliably introduce, plus what to check when a fix REMOVES scope instead of adding it
+metadata:
+  type: reference
+---
+
+When re-verifying a feature whose findings were just fixed, the findings are rarely "the
+fix didn't happen" — they are new defects the fix introduced.
+
+**Why:** the fixer works document-by-document from a fix plan and has no cross-document
+budget left to re-check the claims its new prose makes. A round that opens with 6 findings
+routinely closes with 10, most of them fix-induced.
+
+**Recurring fix-induced shapes:**
+
+1. *Field-comment fixes invent wrong value domains.* A comment describing the right field
+   with the wrong **enum values** survives review — cross-check every documented value
+   against the source `Literal`, the argparse `choices`, and any JSON example.
+2. *New "Public API / Internal Surface" sections drift from their own citations.* They
+   abbreviate a flag list and drop a value, or cite a section for a rule that section does
+   not state. Re-read every `§N` such a section cites.
+3. *A "new design" fix is the highest-yield target* — and the right outcome is often to
+   delete it. See [[pattern-proximity-window-guards]].
+
+**When the fix REMOVES scope (a section deleted, a mechanism withdrawn):**
+
+- The excision itself is usually clean and cheap to prove: grep the removed identifiers
+  word-boundary, then script-verify every `<file> §N` citation against actual headings.
+- The real defect is in the **replacement requirement**. A withdrawn mechanism gets
+  replaced by a one-line requirement, wired into the owning docs — then forgotten in the
+  testing spec. A traceability check that only asserts an ID appears in *some* file cannot
+  catch this. Diff the requirement families in the testing spec's own coverage table
+  against the source, and check whether the acceptance criterion is scoped to "every
+  requirement in this document's table".
+
+**Self-narrated round history is unverifiable-by-tooling and drifts.** A fix pass that
+adds an "implementation warning" summarizing what prior rounds found writes that history
+from memory, not from the reports, and the *count* is usually wrong even when the
+operative instruction is right. Diff any such claim against the actual locations of every
+prior report. Caps at `inconsistency`.
+
+**A "deleted the file" claim verified by `git status` is worthless when the file is
+gitignored.** A gitignored artifact leaves the tree clean before and after, so the fixer
+believes a deletion that never happened. For any finding whose remedy is a deletion, `ls`
+the literal path — never infer it from a clean tree or the absence of a `D ` line.
+`git status --porcelain --ignored <dir>` surfaces the class in one call.
+
+**A retraction orphans the prose that announced the thing being retracted.** Whenever a
+fix pass *removes* something a prior pass *added*, grep the removed token across `*.md`
+and re-read every hit — the announcement almost always outlives the thing. Grep the
+literal token, not the finding's phrasing, and grep the specific file directly rather than
+trusting one repo-wide `grep -r … | head`, which can silently truncate the hit.
+
+**A fix that widens a §3 decision leaves the §1 overview summary behind.** The overview's
+"key decisions" sentence and the file table are written once at authoring time and are
+never in the fix plan's file list. After confirming each fix in its subsection, re-read §1
+and §2 and diff them against the new body — cheap, and the single most reliable
+fix-induced finding in tech mode. Caps at `inconsistency`.
+
+**Check each fixed section against the decision text, not just the finding.** Where fixes
+overshoot is *scope beyond the recorded decision* — a fixed section gains a clause nothing
+in the data model or tests backs.
+
+**A suggested fix can prescribe a claim its own remedy doesn't earn.** When a suggested
+fix pairs *N concrete items* with a *summary claim over M*, count N against M yourself
+before marking resolved — a faithfully-applied fix can land a false exhaustiveness
+sentence with the verifier's own authority behind it. Treat the summary sentence, not the
+missing item, as the finding.
+
+**A clean re-verify is possible and worth naming as the bar.** The fix passes that come
+back clean share one tell: they **re-measured** every literal they wrote (line counts,
+word counts, pinned tuple lengths reproduce exactly under the checker's own algorithm) and
+they **executed** their own claims before editing (reproduced the defective control
+against live canon, then re-ran the replacement) instead of copying the finding's number.
+When a fix log reads like that, the re-verify's job is to re-run the same executions
+independently, not to hunt. Expect single-artifact modes (prd, tech) to run cleaner than
+specs/impl, where cross-document budget exhaustion drives the fix-induced defects — spend
+those rounds on filesystem-claim re-measurement instead.
+
+Related: [[pattern-absence-claims]], [[pattern-spec-literals-are-claims]],
+[[pattern-mechanical-rewrite-damage]].

package/adapters/gemini/references/verifier-patterns/pattern_proximity_window_guards.md

@@ -0,0 +1,26 @@
+---
+name: pattern-proximity-window-guards
+description: Verifying an "instruction X appears near call site Y" drift guard requires adversarially deleting each X one at a time — a generous window silently borrows a neighbour's X
+metadata:
+  type: reference
+---
+
+When re-verifying a drift guard that asserts *proximity* (e.g. "token T appears within N
+lines of every call site"), never accept "baseline green + non-vacuity floor" as evidence
+that the guard bites.
+
+**Why:** a proximity window wider than the real maximum distance lets one call site's
+mandate be satisfied by an *unrelated neighbouring block's* mandate. The guard then stays
+green through exactly the deletion it exists to catch. A window of 20 against a real max
+distance of 10 means deleting one site's mandate leaves the guard green, covered by a
+neighbour's mandate 17 lines up.
+
+**How to apply:** run this adversarial sweep yourself, in memory, over a copy — for every
+line containing the asserted token, delete just that line and re-evaluate the guard.
+Report every deletion the guard fails to catch. Then compute the observed max distance and
+compare it to the configured window; recommend tightening to `max_observed + small
+margin`. Also check whether the guard protects the *normative sentence* stating the rule,
+not only its mechanical instances — those are separate assertions.
+
+The same technique applies to regex-extracted constant-parity guards: mutate the source
+text in memory and confirm each mutation goes RED rather than parsing to an equal value.

package/adapters/gemini/references/verifier-patterns/pattern_scratch_root_probes.md

@@ -0,0 +1,40 @@
+---
+name: pattern-scratch-root-probes
+description: How to build mutation-probe scratch roots without dirtying the tree or reading false GREENs from symlink resolution
+metadata:
+  type: reference
+---
+
+A mutation probe needs a scratch root. Two traps, both of which produce false readings.
+
+**Trap 1 — a symlinked `tests/` silently defeats the probe.** Test bootstraps commonly set
+`REPO_ROOT = Path(__file__).resolve().parent.parent`, and `resolve()` follows a symlink
+back to the *real* repository. So a scratch root whose `tests/` are symlinks runs the
+**unmutated** code under test and reports GREEN. The same mutation with real-file copies
+reads a genuine failure.
+
+- Mutating something under `tests/` only → a symlinked root is fine, but the mutated module
+  itself must be a **real file** (its own `Path(__file__).resolve()` must land in the root).
+- Mutating anything under the source tree → both `tests/` and the source dir must be real
+  copies (`shutil.copytree`).
+
+**Trap 2 — disk.** A large repo can fill the root mid-probe, which reads exactly like a
+real regression (a burst of "could not create numbered dir" plus an `Errno 28`). Check
+`df -h /` for headroom before gating. Never `copytree` the whole repo; symlink the large
+read-only trees and copy only what you mutate.
+
+**Why:** when most verification rounds turn on a measurement being wrong rather than the
+code being wrong, a probe that silently measures the wrong file is worse than no probe.
+
+**How to apply:** always run probes with `PYTHONDONTWRITEBYTECODE=1`, `-p no:cacheprovider`,
+and `__pycache__` purged between runs (same-size constant edits within one second reuse
+stale bytecode). Always include an *effectiveness* control — e.g. a hand-kept roster with
+the same entries in **reversed** order — so "the guard caught it" is distinguishable from
+"the mutation was a no-op". See [[pattern-vacuous-self-reading-tests]] and
+[[pattern-proximity-window-guards]].
+
+**Baselines.** `git archive` is unusable when `.gitattributes` marks `tests/` / `specs/` /
+`eval/` `export-ignore` — an archive baseline collects zero tests. `git worktree` writes
+under `.git/worktrees` and needs a mutating `worktree remove`, which a read-only pass may
+not run. Restore the changed files from `git show <base>:<path>` into a real-file root
+instead.

package/adapters/gemini/references/verifier-patterns/pattern_self_referential_control.md

@@ -0,0 +1,26 @@
+---
+name: pattern-self-referential-control
+description: A mutation control that sizes its mutation from the function under test cannot detect that function degrading — execute the control, don't read it
+metadata:
+  type: reference
+---
+
+When a spec replaces a deleted bound with a "mutation control", check what the control's
+**mutation span** is computed from. If it is derived from the same function whose widening
+the control exists to catch, the span widens in lockstep and the control stays green under
+exactly the degradation it documents.
+
+**Why:** a control that takes its strike span from a `bounds` helper degrades with that
+helper — degrading the helper to heading-only makes the control delete the *neighbour's*
+mandate too, so the probe still reports and the control still passes. The spec's own
+acceptance criterion is the tell: a verification checkbox of the form "this control FAILS
+when X is degraded" is directly executable — run it.
+
+**How to apply:** for every specified control, (1) implement the specified functions against
+live inputs, (2) run the control under the *degraded* variant the spec names, not only the
+adopted one, (3) if it passes under degradation, the control is self-referential. Then
+construct and **empirically verify the replacement** before proposing it, so the fix is
+trustworthy. In the same pass, re-derive detection / false-failure censuses too — "N false
+failures under the naive variant" often does not reproduce once the adopted bound is
+block-based rather than line-based. Related: [[pattern-proximity-window-guards]],
+[[pattern-vacuous-self-reading-tests]], [[pattern-guard-substitution-detection]].

package/adapters/gemini/references/verifier-patterns/pattern_sibling_docstring_sweep.md

@@ -0,0 +1,28 @@
+---
+name: pattern-sibling-docstring-sweep
+description: When a fix mirrors one guard into N places, exactly one of the N docstrings gets updated — grep for the superseded rationale, not the new one
+metadata:
+  type: reference
+---
+
+When a fix pass mirrors a rule into several implementations, it reliably amends **one**
+docstring and leaves the siblings stating the superseded rationale. The function the
+finding was filed against is not always the one whose docstring got fixed — a mirrored
+guard can land in three functions with only the *unnamed* one amended, leaving the target
+function still asserting the opposite in two separate sentences.
+
+**Why:** the amended docstring *names* the old rationale in order to disclaim it, which
+makes it the perfect grep needle for finding the unamended ones. Behaviour is correct
+either way, so no test can see the drift; a reader of the stale docstring draws exactly the
+false inference the fix existed to kill.
+
+**How to apply:** after any "mirror the guard into N places" fix —
+
+1. Grep for the *superseded* rationale (the phrase the one amended docstring disclaims),
+   not for the new rule. The updated site will not match; the stale ones will.
+2. Read the N docstrings **side by side** and check none states a rule another contradicts.
+3. The same shape hits number words after an arity change — see
+   [[pattern-stale-counts-after-split]] — and false specifics in "measured twice"-style
+   claims, where the conclusion is true but the named instrument is wrong on most of the
+   surfaces it claims to cover. Verify *which* fragment matched *per surface*, not just that
+   the aggregate claim holds.