@garygentry/feature-forge 0.3.6 → 0.3.8

package/adapters/codex/skills/forge-verify/references/verification-checklists/epic.md

@@ -12,7 +12,7 @@ reading the manifest, EPIC.md, completed members' specs, and (for E10) sibling m
 committed tests.
 
 ```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/epic-manifest.py" validate "{epic}" --specs-dir "{specsDir}" --json
 ```
@@ -50,7 +50,7 @@ python3 "$R/scripts/epic-manifest.py" validate "{epic}" --specs-dir "{specsDir}"
   exits interpose reconcile-first on it, and specs written now would build on a soon-invalid
   premise), a **non-blocking** request → `improvement` (a peer/downstream change to reconcile
   when convenient). Name the request's `kind`, `target`,
-  and `rationale`, and point at `/feature-forge:forge-0-epic {epic}` to reconcile. **Report, do
+  and `rationale`, and point at `forge-0-epic {epic}` to reconcile. **Report, do
   not repair** (same posture as CHECK-E07). Which members have open requests comes from the
   same `render-status --json` counts the navigator uses (`features[].openEpicChangeRequests` /
   `.blockingEpicChangeRequests`); the per-request `kind`/`target`/`rationale` detail is read

package/adapters/codex/skills/forge-verify/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/codex/skills/forge-verify/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/codex/skills/forge-verify/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/codex/skills/forge-verify/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/codex/skills/forge-verify/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/codex/skills/forge-verify/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/codex/skills/forge-verify/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/codex/skills/forge-verify/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/codex/skills/forge-verify/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/codex/skills/forge-verify/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/codex/skills/forge-verify/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/codex/skills/forge-verify/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/codex/skills/forge-verify/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.

package/adapters/codex/skills/forge-verify/references/verifier-patterns/pattern_spec_literals_are_claims.md

@@ -0,0 +1,45 @@
+---
+name: pattern-spec-literals-are-claims
+description: Every module id, file path, constant and signature written into a spec is a checkable claim about the repo — verify them mechanically, they survive multiple verify rounds otherwise
+metadata:
+  type: reference
+---
+
+Treat every literal a spec writes down as an assertion about the current repository and
+check it against the filesystem, not against the spec's own prose.
+
+**Why:** specs quote "exact existing signatures" and author code constants (allow-lists,
+fixture inventories, helper additions) inline. These read as authoritative and reviewers
+pattern-match them as correct, so a phantom id or a dropped member survives round after
+round untouched. The failure is silent: nothing executes a spec's prose.
+
+**How to apply** (cheap, mechanical, do it every round):
+
+- Module/skill ids in a spec constant → list the real directory and diff the sets both
+  directions. Missing-from-spec and absent-from-repo are different bugs; report both.
+- Quoted "exact current signature" blocks → `grep -n -A12 'def <name>' <file>` for each.
+  When these are usually accurate in a repo, a mismatch is high-signal.
+- Cited file paths (fixtures, tests, references, data) → loop them through `[ -e "$p" ]`.
+  Fast, and it catches placeholder paths a fix pass left behind.
+- Cross-document `<file> §N` citations → script it: build a heading index per file, regex
+  the citations, report misses. Never eyeball, especially after a section was deleted or
+  renumbered.
+- Requirement-id tokens in a coverage table → diff the families against the source doc.
+  Range citations (`REQ-EXIT-01..07`) and pseudo-rows are where phantom and dropped IDs
+  hide.
+- Prose claims about existing behavior ("the field is a single string", "the file is 302
+  lines") → verify. When they are usually correct, the occasional wrong one gets waved
+  through — which is exactly why to check.
+- **A spec's *correction* of an upstream figure is itself an unverified claim — re-derive
+  it, do not credit it.** A supersession arrives framed as research ("exhaustive search
+  found N"), and that framing buys it a pass. Re-derive each superseding number from the
+  files; the correct ones cost seconds and a wrong one is blocking.
+- **Cited *line ranges* into another file drift as a set, not as a number.** "Amend the
+  bullets (lines 43–48)" plus an enumeration of three constructs is two claims; the range
+  is usually copied verbatim from the finding that proposed it, so a wrong range
+  propagates report → spec → implementer. `grep -n` the first token of each named
+  construct and confirm the span contains all of them.
+- **Line-count claims: know what the checker counts.** A body-size gate that measures
+  lines *after* frontmatter disagrees with a raw `wc -l` by the frontmatter block. When a
+  spec's size claim and a passing gate disagree, go read the checker's measurement
+  function before believing either.

package/adapters/codex/skills/forge-verify/references/verifier-patterns/pattern_stale_counts_after_split.md

@@ -0,0 +1,36 @@
+---
+name: pattern-stale-counts-after-split
+description: Splitting a construct N ways leaves the old number words ("two", "three", "both") scattered through banners, docstrings and prose — grep the number words after any arity change
+metadata:
+  type: reference
+---
+
+When a construct is split — one function into three, two checks into five, "both callers"
+into "all three" — the code is updated and the **number words describing it are not**. They
+survive in module banners, docstrings, comment headers, error messages, and prose that
+narrates the old shape. Nothing fails: the count is not executable, so no test observes it,
+and the reader is told the wrong arity by a file that otherwise looks authoritative.
+
+**Why it survives review:** a diff shows the new Nth item being *added* and gives no signal
+about the sentences elsewhere that quantified the old set. The reviewer checks the new
+member is correct — which it is. The stale count sits in a file the diff never touches.
+
+**How to apply.** After any arity change:
+
+1. **Grep the number words, not the identifiers:**
+   `\b(one|two|three|four|five|both|either|neither)\b` across the changed construct's own
+   file *and* every file that cites it. `both` and `neither` are the highest-yield needles
+   — they are only correct at exactly two and break silently at three.
+2. **Include the prose surfaces a code grep misses:** module docstrings, comment
+   annotations, assertion messages, reference markdown, skill bodies, and changelog entries
+   that described the old shape.
+3. **Re-read the sentence, do not pattern-match it.** "The two callers" may have become
+   "the two callers and the initializer", which is grammatical, cites three things, and
+   still says two.
+4. A count in an **error message** is worse than one in a docstring: it is read at the
+   moment someone is already confused, and it is quoted into issues.
+
+**Sibling shapes:** [[pattern-sibling-docstring-sweep]] (mirroring a rule into N places
+amends exactly one docstring) and [[pattern-test-count-units]] (a "N tests" claim means
+pytest-collected, not `def` count). All three are the same failure: a number that
+describes code, written in prose, with nothing to keep the two in step.

package/adapters/codex/skills/forge-verify/references/verifier-patterns/pattern_test_count_units.md

@@ -0,0 +1,20 @@
+---
+name: pattern-test-count-units
+description: A spec's "N tests" claim means pytest-COLLECTED tests, not def count — always --collect-only before calling it wrong
+metadata:
+  type: reference
+---
+
+When an artifact claims a test-file size ("43 tests, 651 lines", "67 mutation
+controls"), resolve the unit with `pytest <file> --collect-only -q` before filing an
+accuracy finding. Parameterization makes `grep -c "def test_"` wildly lower than the
+collected count — a single `@pytest.mark.parametrize` function can collect dozens.
+
+**Why:** grep count and collected count are different units, and a spec that is exactly
+right in the collected unit looks wrong under a naive `def` grep. Filing that is a pure
+false positive, and it burns a fix round on churn the artifact never needed.
+
+**How to apply:** If a spec states a baseline in one unit and a *target* in the other
+("43 tests" → "at most 5 tests"), that unit ambiguity is itself the finding — file it as
+an `improvement` asking for the counting unit to be named, not as a factual `error`.
+See [[pattern-spec-literals-are-claims]].