@gtrabanco/pi-agentic-workflow 0.2.0 → 0.4.0

package/skills/review-change/references/REVIEW_PROCESS.md

@@ -10,6 +10,17 @@
    check, run `git rev-parse HEAD` once and retain its 40-hex output as the
    **reviewed head SHA**. The final PR receipt may be written only for that exact
    commit; a PR whose head changes during the review requires a fresh review.
+   **Read the unit's fold ledger (`review-findings.md`) before any pass — it is
+   the review's memory — and state the cycle number** in the report (`Cycle: <n>`,
+   completed `REVIEW-RAN` marks + 1). From cycle 2 on, **every `folded: yes` row
+   is re-verified at its cited location** before anything else: defect gone →
+   pass; defect still present → one new row marked `regression of <id>` (that is
+   the only legitimate bypass of the `file:line`+axis dedupe, and it is folded
+   with the same evidence bar as any finding); reviewer disagreement with a
+   user-approved amendment → `DISPUTED`, never a fresh row re-litigating the
+   same location. A cycle ≥ 2 that produces any new fix-now row appends the
+   `CONVERGENCE-ANOMALY` block (`pre-execution-review/references/POLICY.md` §4)
+   to the report.
 2. **Frozen acceptance + SPEC drift check (structural).** Locate sibling
    `ACCEPTANCE.md`, recompute its blob, and require an exact match with the
    execution receipt before assessing the candidate. Missing/mismatch is a
@@ -34,14 +45,27 @@
    commits follow `<type>(<scope>): <summary>`; phase labels in touched
    planning docs are `P1, P2, …` (never `S1`/"Steps"); the phase's per-phase
    docs were updated (TASKS ticks, progress entry); no commit landed on the
-   default branch; artifacts are in the project's declared docs language;
-   **the tree is clean and the remote current** — run `git status --porcelain`
-   (any tracked modification, code or docs, = a `workflow` finding: work is
-   sitting outside the commits under review) and, when the branch has an open
-   PR, `git fetch` + `git status -sb` (commits ahead of the remote = a
-   `workflow` finding: the PR and CI are judging a stale branch). Both are
-   **fix-now** — a review verdict on a branch whose real state isn't pushed
-   is worthless. Run the greps/`git log`/`git status` — don't infer compliance.
+   default branch; artifacts are in the project's declared docs language.
+   **Workspace state is a precondition, not a finding.** Run
+   `git status --porcelain`, and when the branch has an open PR `git fetch` +
+   `git status -sb`. Any tracked modification, or being ahead of/behind the
+   remote, stops the review **before any pass runs** — no findings table, no
+   ledger write, no verdict, and never a `workflow` finding persisted for it
+   (a review that filed its own dirty tree would hand the next review the
+   same finding, forever):
+
+   ```text
+   REVIEW BLOCKED — workspace state
+   - `git status --porcelain`: <lines, or `clean`>
+   - `git status -sb`: <line, or n/a: no open PR>
+   → Next: commit or stash the listed files, then re-run /review-change.
+     Untracked, non-ignored harness/toolstate nobody authored for this unit
+     (.engram/, .pi/, .serena/, session files) is committed once or added to
+     .gitignore — named here, never reviewed. A verdict on a workspace whose
+     state the forge cannot see is withheld, not filed.
+   ```
+
+   Run the greps/`git log`/`git status` — don't infer compliance.
 4. **Applicable pack passes (the finders).** For each axis the matrix +
    footprint mark as relevant, run the workflow's own internal skill for it
    (`review-code`, `review-security`, `review-verify`, `review-design`,
@@ -54,14 +78,30 @@
    (stack-specific linters, framework skills) and they are installed, run them
    **in addition** — their findings merge into the same table. Never treat an
    absent extra as a gap; the pack already covered the axis.
-6. **Synthesize.** Fuse all findings into **one** findings table, deduped by
+6. **Verify, then synthesize.** Before fusing anything, every candidate finding
+   is **verified in an isolated context against the reviewed head's bytes** (the
+   SHA frozen in step 1) and marked `confirmed` or `refuted`. The recheck method
+   follows the finding's axis:
+   - a **code / behavioral** claim confirms only with a **failing reproducer** —
+     a red test written first and run against **unchanged code**, or
+     **reproducible command output**;
+   - a **documentation / wording** claim confirms by **direct read** of the
+     cited text (typos and wording are corrected without ceremony, no test);
+   - a **missing-documentation** claim confirms the named user path is
+     undocumented.
+   Only **confirmed** candidates flow to synthesis; a **refuted** candidate is
+   reported with its counter-evidence in the same report and never becomes a
+   row, a fold task, or a re-review trigger. The per-finding durable mark is
+   `finding-mark@1` (contract in `pre-execution-review/references/LEDGERS.md`).
+
+7. **Synthesize.** Fuse all findings into **one** findings table, deduped by
    `file:line` + axis, per the synthesis contract (the same fusion rules apply
    in the default single-reviewer case). Columns: `# | Finding | Axis | Sev |
    Evidence | Suggested fix` — **unclassified**. Overlapping signals on the same
    defect collapse into one row. Add a **`Reviewers n/N`** column when running
    in `--adversarial N` mode (omitted entirely in the default single-reviewer
    case).
-7. **Classify (once).** Run `review-implementation` over the synthesized table
+8. **Classify (once).** Run `review-implementation` over the synthesized table
    (isolated, per the *Isolation rule*) — the single classification engine
    (D5). It verifies axis coverage (every applicable axis represented; a
    missing axis is a `coverage` finding) and applies the current-unit contract:
@@ -70,17 +110,37 @@
    → the **classified decision table** (Sev, Class, WHY, impl risk, long-term
    impact, premature-opt?, Route). No per-pass or per-reviewer classification,
    no re-litigation.
-8. **Debt transform.** Run `review-debt` over the classified table — it
+9. **Debt transform.** Run `review-debt` over the classified table — it
    transforms debt-shaped findings into explicit TRIGGER-carrying debt items;
    it does not rescan the diff (SPEC contract).
-9. **Manual-verification checklist.** List what automated review **cannot** confirm
+10. **Manual-verification checklist.** List what automated review **cannot** confirm
    and a human must check — visual correctness, real-device/locale behavior, UX
    feel, perf under load, anything marked *verify*. Be explicit so the dev has zero
    doubt about what to eyeball.
-10. **Route the outcomes.** fix-now findings fold into the current unit (or gain
+11. **Route the outcomes.** fix-now findings fold into the current unit (or gain
     user-confirmed phases via replan-in-unit); decision-required stops for the
     user's decision; genuinely independent future capabilities become
     **non-blocking proposals** — batched in the report with a trigger, and
     **never** sent to `triage-issue` automatically (D3). `review-change` creates
     no backlog work. No non-fix-now finding may end without a destination — none
     silently lost.
+
+## Two-cycle cap
+
+The review→fold loop runs at most **two** review→fold cycles per unit, counted
+unit-level and family-agnostic from the ledger's `REVIEW-RAN` marks and forge
+receipts — new finding families do not reset the count. After two cycles without
+convergence, the review prints
+
+```text
+LOOP CAP REACHED — <unit>
+- Finding ids: <every open id>
+- Cycles: 2 (REVIEW-RAN marks + forge receipts)
+- Route: /triage-issue --prioritize-now <unit> F<k> … (or the programmatic outer driver)
+```
+
+A **third cycle never starts** unless the user explicitly instructs it — it is
+the user's escape, never a reviewer election. The residue routes to
+`triage-issue --prioritize-now` (or the programmatic outer driver), and a unit
+that needs a third cycle has a planning or root-cause defect, not a review
+deficit.

package/skills/review-code/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: review-code
 user-invocable: false
-version: 1.0.1
+version: 1.2.0
 author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
@@ -41,9 +41,20 @@ default branch. State the scope at the top of the returned table.
 ✓ No new dependency not justified in the SPEC
 ✓ Simplification: any changed block that can lose lines without losing
   behavior (cite before/after)
+✓ Reference trace: every changed symbol/API got a reference search —
+  un-updated callers are findings
 ✓ Edge cases the SPEC's dev scenarios name are actually handled in code, not
   just in tests
 
+## Materiality bar
+
+Report a row only when a competent user's outcome changes or a rule the project
+explicitly declares is violated — cite the rule it violates beside the evidence.
+Not findings: comment/punctuation typos, formatting-only drift, style preference
+with no cited rule, hypothetical robustness beyond the SPEC's named scenarios.
+An empty table with `Decision: PASS` is the expected result for a well-formed
+change — never pad the table.
+
 ## Return exactly
 
 ```

package/skills/review-design/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: review-design
 user-invocable: false
-version: 1.0.1
+version: 1.1.0
 author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
@@ -35,6 +35,15 @@ default branch. State the scope at the top of the returned table.
 ✓ Destructive actions require confirmation and are visually distinct
 ✓ Feedback on every user action (submit, save, fail) — no silent operations
 
+## Materiality bar
+
+Report a row only when a competent user's outcome changes or a rule the project
+explicitly declares is violated — cite the rule it violates beside the evidence.
+Not findings: comment/punctuation typos, formatting-only drift, style preference
+with no cited rule, hypothetical robustness beyond the SPEC's named scenarios.
+An empty table with `Decision: PASS` is the expected result for a well-formed
+change — never pad the table.
+
 ## Return exactly
 
 ```

package/skills/review-implementation/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: review-implementation
 user-invocable: false
-version: 1.5.0
+version: 1.7.0
 argument-hint: <path-or-glob>
 allowed-tools: Read, Grep, Glob, Bash, WebFetch
 author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"

package/skills/review-implementation/references/CLASSIFY.md

@@ -15,6 +15,14 @@ only with a rationale.
 
 ### Step 2 — Is it current-unit work? (only blocking outcomes)
 
+**Severity floor first.** A `low` finding (taste, cosmetics, micro-optimization
+without a measured need) is **never persisted and never blocks**: it is carried
+as a report note with its evidence, and the fold ledger never sees it. But a
+real defect mislabeled `low` stays real: when the evidence shows a correctness,
+security, behavioral, or data-integrity defect, classify it at `med` minimum —
+deflating a real defect to `low` to unblock a review is itself a review defect.
+Only `high` and `med` findings run through the current-unit gate below.
+
 A finding belongs to the **current unit** when it maps to the governing SPEC, a
 phase, a documented invariant, correctness, security, accessibility, a required
 UX/error state, or an expectation necessary for a competent user to consider an
@@ -105,7 +113,7 @@ finding in its `Route` cell.
 
 | Owning stage | Hand-off | Never |
 |---|---|---|
-| `source` | fold locally: `/loop-review-fold` → `/fold-findings` → re-review the changed HEAD | — |
+| `source` | fold locally: `/fold-findings`, then re-run `/review-change` on the changed HEAD | — |
 | `plan` | the planning author re-cuts the artifact (SPEC `## Phases`, an obligation row, an acceptance mapping, a ledger) on the same branch with the user's confirmation, then a **fresh `/review-plan <unit>`** precedes `execute-phase` | fold it in code and leave the plan describing the old build |
 | `product` | `/design-feature <unit>` repairs the half, then `/review-spec <unit>` re-judges it | patch the product claim into agreement in code |
 | `environment` / `runtime` | the existing retry/`BLOCKED` paths | translate into a PASS, or an issue |

package/skills/review-perf/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: review-perf
 user-invocable: false
-version: 1.1.0
+version: 1.2.0
 author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
@@ -54,6 +54,15 @@ default branch. State the scope at the top of the returned table.
   add a **minor** finding recommending the project adopt the tooling via
   `init-workspace`'s Performance tooling round.
 
+## Materiality bar
+
+Report a row only when a competent user's outcome changes or a rule the project
+explicitly declares is violated — cite the rule it violates beside the evidence.
+Not findings: comment/punctuation typos, formatting-only drift, style preference
+with no cited rule, hypothetical robustness beyond the SPEC's named scenarios.
+An empty table with `Decision: PASS` is the expected result for a well-formed
+change — never pad the table.
+
 ## Return exactly
 
 ```

package/skills/review-plan/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: review-plan
 user-invocable: true
-version: 1.3.1
+version: 1.5.0
 argument-hint: <NN-slug | fix-N | path/to/SPEC.md> [--adversarial N]
 author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
 license: MIT

package/skills/review-plan/references/OUTPUT.md

@@ -89,6 +89,15 @@ stage.
 
 ### Routes
 
+**Resolution map — the finding's `class` cell names its resolver, and only that
+resolver:** class `plan` → `plan-feature` / `plan-fix` (the author re-cuts, then
+`/review-plan` re-judges) · class `product` → `design-feature` repairs the
+Product half (then `/review-spec`, then the plan re-derives) · class `source` |
+`environment` | `runtime` → the executor's fold path (`/fold-findings`, then re-run
+`/review-change`), never by editing the plan to hide the row.
+**`fold-findings` never repairs a planning artifact** — folding repairs source,
+not authority.
+
 | Verdict / class | Who acts | What happens next |
 |---|---|---|
 | `PLAN-REVIEW-PASS` | nobody | `/execute-phase <NN>` binds this receipt + exact snapshot digest |

package/skills/review-security/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: review-security
 user-invocable: false
-version: 1.0.1
+version: 1.1.0
 author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
@@ -40,6 +40,15 @@ default branch. State the scope at the top of the returned table.
 ✓ Error responses don't leak stack traces or internal paths
 ✓ Unsafe deserialization / dynamic evaluation of untrusted data absent
 
+## Materiality bar
+
+Report a row only when a competent user's outcome changes or a rule the project
+explicitly declares is violated — cite the rule it violates beside the evidence.
+Not findings: comment/punctuation typos, formatting-only drift, style preference
+with no cited rule, hypothetical robustness beyond the SPEC's named scenarios.
+An empty table with `Decision: PASS` is the expected result for a well-formed
+change — never pad the table.
+
 ## Return exactly
 
 ```

package/skills/review-seo/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: review-seo
 user-invocable: false
-version: 1.0.1
+version: 1.1.0
 author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
@@ -40,6 +40,15 @@ default branch. State the scope at the top of the returned table.
 - ✓ No render-blocking regression for primary content (content present without
   JS where the project declares SSR/SSG)
 
+## Materiality bar
+
+Report a row only when a competent user's outcome changes or a rule the project
+explicitly declares is violated — cite the rule it violates beside the evidence.
+Not findings: comment/punctuation typos, formatting-only drift, style preference
+with no cited rule, hypothetical robustness beyond the SPEC's named scenarios.
+An empty table with `Decision: PASS` is the expected result for a well-formed
+change — never pad the table.
+
 ## Return exactly
 
 ```

package/skills/review-spec/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: review-spec
 user-invocable: true
-version: 1.3.2
+version: 1.5.0
 argument-hint: <NN-slug | path/to/SPEC.md>
 author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
 license: MIT

package/skills/review-spec/references/OUTPUT.md

@@ -76,6 +76,15 @@ fourth verdict.
 
 ### Routes
 
+**Resolution map — the finding's `class` cell names its resolver, and only that
+resolver:** class `product` → `design-feature` (then `/review-spec` re-judges the
+new revision) · class `plan` → `plan-feature` / `plan-fix` re-cuts the plan (then
+`/review-plan` re-judges) · class `source` | `environment` | `runtime` → the
+executor's fold path (`/fold-findings`, then re-run `/review-change`).
+**`fold-findings` never repairs a planning artifact**, and a planning finding is
+never resolved by patching the artifact during review — folding repairs source,
+not authority.
+
 | Verdict | Who repairs | What happens next |
 |---|---|---|
 | `SPEC-REVIEW-PASS` | nobody | `/plan-feature <NN-slug>` binds this receipt + exact snapshot digest |

package/skills/review-verify/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: review-verify
 user-invocable: false
-version: 1.0.1
+version: 1.1.0
 author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
@@ -40,6 +40,15 @@ default branch. State the scope at the top of the returned table.
 ✓ Anything that can only be confirmed by a human (visual, device, locale,
   load) is listed explicitly under "Manual" — never silently dropped
 
+## Materiality bar
+
+Report a row only when a competent user's outcome changes or a rule the project
+explicitly declares is violated — cite the rule it violates beside the evidence.
+Not findings: comment/punctuation typos, formatting-only drift, style preference
+with no cited rule, hypothetical robustness beyond the SPEC's named scenarios.
+An empty table with `Decision: PASS` is the expected result for a well-formed
+change — never pad the table.
+
 ## Return exactly
 
 ```

package/skills/ship-roadmap/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ship-roadmap
 user-invocable: true
-version: 5.0.0
+version: 5.1.0
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 argument-hint: "[--fullauto] | --continue [--fullauto]"
@@ -102,7 +102,7 @@ fallback only when a primitive is unavailable; keep stage order and safety floor
 
 | Relation | Skills/policy |
 |---|---|
-| Compose (same/lower tier) | `init-workspace`; JIT `design-feature` + `plan-feature-scaffold`; `plan-feature`; `loop-review-fold`; verdict-only `audit-pr`; `audit-docs`. |
+| Compose (same/lower tier) | `init-workspace`; JIT `design-feature` + `plan-feature-scaffold`; `plan-feature`; the review→fold manual path (`/fold-findings` → re-run `/review-change`); verdict-only `audit-pr`; `audit-docs`. |
 | Cheap workers | `execute-phase` (fresh context/phase), mechanical folds, audit-blocker fixes; use the validated worker model. |
 | Human hand-off | Default merges, `product-audit` (higher effort), and report issue batches via `triage-issue`. |
 | Sibling | `workflow-status` supplies the strict sensor result; worker skills use the package-owned output profiles, while the conductor keeps its native `SHIP:` turn contract. |

package/skills/ship-roadmap/references/ADVANCE.md

@@ -70,11 +70,12 @@
      when the PR opens; any flips left at run end ride the report commit).
      Stop before the literal final `Hardening & PR` phase: PR owns that explicit
      phase so close-out has one owner. Never bundle phases into one worker.
-   - **REVIEW** — compose `loop-review-fold` in-turn (equal tier) once, over
-     the complete PR candidate. It reuses a current exact-SHA receipt or runs
-     `review-change` context-clean, batches compatible fixes through
-     `fold-findings`, and re-reviews only changed HEADs. Default correction
-     budget is two; unchanged evidence stops NO-PROGRESS. L/sensitive features
+   - **REVIEW** — compose the manual review→fold path in-turn (equal tier) once,
+     `/fold-findings`, then re-run `/review-change`, over the complete PR
+     candidate. It reuses a current exact-SHA receipt or runs `review-change`
+     context-clean, batches compatible fixes through `fold-findings`, and
+     re-reviews only changed HEADs. Default correction budget is two; unchanged
+     evidence stops NO-PROGRESS. L/sensitive features
      forward `--adversarial 2` (security/auth: `3`) as the unattended floor;
      other units use one final reviewer. There are no intermediate phase
      reviews in autopilot: phase gates + frozen acceptance guard execution,

package/skills/ship-roadmap/references/MODEL_ROUTING.md

@@ -9,7 +9,7 @@
 | Product review (REVIEW-SPEC) | opus/high | `review-spec` in a **clean context** (fresh subagent or outside headless call) — never the turn that wrote the product half; tier equals or exceeds the author's, so the ≥ rule holds |
 | Plan review (REVIEW-PLAN) | opus/high | `review-plan` in a **clean context**, same rule; it judges the plan the previous stage froze |
 | Phase execution, single-pass, fixes | **cheap worker** | fresh context per phase following `execute-phase`; Claude branch maps this role to `sonnet`, portable drivers use their validated worker tier |
-| Final review/correction loop | opus/high | compose `loop-review-fold`; it selects review or fold from persisted evidence and routes unresolved findings to `triage-issue --prioritize-now` |
+| Final review/correction loop | opus/high | compose the manual path `/fold-findings`, then re-run `/review-change`; it reuses a current exact-SHA receipt or reviews context-clean, and routes unresolved findings to `triage-issue --prioritize-now` |
 | Merge gate | opus/high | compose `audit-pr` in-turn (the highest-stakes automated verdict; must share one turn with the floor checks) |
 | Forge/git mechanics | — | Bash tool calls; no model judgment involved |
 | Final-report evidence gathering | haiku (optional) | fan-out subagents for grep-shaped per-feature log collection when ultracode is on; synthesis stays opus |

package/skills/triage-issue/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: triage-issue
 user-invocable: true
-version: 2.6.0
+version: 2.7.0
 argument-hint: <issue-number> [more issue numbers…] | <audit-id> F<k> [F<j>…] | --prioritize-now <unit> F<k> [F<j>…]
 author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
 license: MIT

package/skills/triage-issue/references/REVIEW_FINDING_PROCESS.md

@@ -25,7 +25,7 @@ after `/fold-findings` leaves rows unresolved.
 
 4. Never implement the new phases in this triage turn. After a replan, ask the
    user to continue manually with `/execute-phase <unit> P<n>` (or the fix
-   equivalent), then re-run `/loop-review-fold` on the resulting HEAD.
+   equivalent), then re-run `/review-change` on the resulting HEAD (the manual path).
 
 Return exactly one block per finding:
 

package/skills/verification-contract/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: verification-contract
 user-invocable: false
-version: 1.0.1
+version: 1.2.1
 author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Internal contract: one compact frozen ACCEPTANCE.md per delivery unit, its
   validation ladder, anti-weakening rules, and blob-bound execution receipt.
-  Consumed by planners, execute-phase, review-change, and loop-review-fold.
+  Consumed by planners, execute-phase, and review-change.
 ---
 
 # Verification Contract (internal)
@@ -24,6 +24,15 @@ commands. Prefer commands, otherwise use `read-verified: <evidence>` or
 `manual: <exact observation>`. Unlabelled prose is invalid. A planned test may
 name its future project runner; it cannot substitute a narrower runner later.
 
+**Validator stability.** A validator must never gate on a surface other workflow
+actors mutate — the branch diff as a whole, the session log, progress entries,
+review ledgers, or forge state — because any out-of-unit commit (a session-log
+append, another unit's fold) then re-fails a frozen criterion on a finished unit
+and re-opens its review loop. Grep the unit's own files and outputs; a
+diff-based validator enumerates the unit's paths or excludes the
+workflow-mutated surfaces explicitly (docs/LOGS.md, the unit's own docs
+directory, harness/toolstate).
+
 ## Freeze and receipt
 
 At first execution run `git hash-object <unit>/ACCEPTANCE.md` and append to the
@@ -71,6 +80,17 @@ stub, hard-coded answer, or no-op fix used to manufacture green. A command canno
 prove an untested read/manual row. Stronger regression tests are allowed. Repair
 test setup only when assertions stay at least as strong and the reason is logged.
 
+## Test immutability
+
+A test, once written, is **immutable**. The executor fixes code until green,
+never the test — editing an expectation to match behaviour is not a fix, it is
+a cover-up. The sole legitimate amendment is a **proven mis-encoding of external semantics**: the test's expectation contradicts the actual
+documented semantics of the platform/library/language, cited from authoritative documentation — not a product decision change. Even that surfaces as a
+**finding plus a SPEC amendment**, never a silent edit to go green.
+
+Prevention rides the research gate (**research-before-encode**): platform
+semantics are verified against authoritative documentation **before a test encodes them**, so **adding stronger tests stays allowed**; **editing expectations never** (except the proven-mis-encoding path above).
+
 ## Done when
 
 Frozen manifest + current blob receipt + named validators + literal quality