@antoneeo/agentic-sdlc-skill 1.15.0 → 1.17.0

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 Tutte le modifiche significative a questa skill saranno documentate in questo file.
 
+## [1.17.0] - 2026-07-27 (Parallel Handoff)
+### Changed
+- **`audit/handoff.md` becomes a workstream registry (F-019)** — the single narrative handoff was session-scoped: with milestones in parallel, the last session to close overwrote everyone else's resume point (observed live: two 2026-07-27 sessions clobbered each other's handoff). Now: **one row per open workstream** (feature, level, branch, status, since, next step, pointers) — closing one milestone removes one row and never touches another's; whoever opens the project sees at a glance what is in PROGRESS, on which branch, since when. Volatile resume logistics (branch/worktree, uncommitted state, environment notes, next command) move to **`audit/HANDOFF_[feature].md`** — ephemeral by design, **deleted at that feature's closure**: the ANALYSIS Diary keeps the durable narrative (DRY — anything in the HANDOFF file worth keeping was in the wrong file). The registry is an inventory for lookup, not a work board: no assignment, no due dates, no execution ordering (the Vision's work-management Non-Goal is the binding constraint, checked in the ANALYSIS). `ORIENT_DOCS` path unchanged — the registry flows through the SessionStart hook with no validator change. Touches `SKILL.md` (Write Triggers row split, Phase 1, Phase 5), `templates.md` (registry + per-feature templates with the Diary/logistics boundary), new invariant `test_parallel_handoff_wired`. Governed by `ai_docs/solutions/ANALYSIS_parallel_handoff.md`.
+- **Upgrading from ≤1.16 costs nothing and requires nothing.** A legacy narrative handoff keeps working: the validator checks only its `Date:` header and age, the orientation hook reads the same path verbatim, and installing the skill never touches a consumer's `ai_docs/`. It reads as a one-row registry; **convert it lazily, the next time the write trigger fires** — `## Active features` bullets become rows, `## Next step` becomes that row's next step, `## Session notes` becomes `## Project-wide notes`. No migration sweep, no script, and deliberately **no validator warning** for the old form: nagging every existing project about a file that works is exactly the ceremony the Vision forbids. The invariant now asserts the migration clause is present — shipping a format change that strands existing projects is a caught regression.
+
+## [1.16.0] - 2026-07-27 (Guide Activation + Verifiable Vision)
+### Changed
+- **Rule Zero declares the router verdict** — the triage level is declared together with the guide-router lookup result, as one line (`Level: L2 · router: no match` / `Level: L3 · router: GUIDE_x.md → read`). L1 stays exempt. Rationale: the consult trigger already existed in three places (Phase 4 bullet, `## Operative Guides`, `guides.md` §0) and still did not fire — none of them sits on a path every request executes. Making the lookup a **declared output** is what closes it: an undeclared lookup is indistinguishable from a skipped one, so `no match` is the expected, correct output on a repo with no matching guide. Field report that triggered this: guides were written and then never consulted unless the user asked by hand.
+- **Phase 1 reads the guide router** — `ai_docs/reference/INDEX.md` joins `README.md` + `INDEX.md` as a mandatory orientation read: it is the only step that tells you a guide already governs the work you are about to do. The `templates.md` README template and this repo's own `ai_docs/README.md` list it first, so new projects inherit the fix.
+- **SessionStart `orient` hook promoted from optional to recommended default** (`ENFORCEMENT.md` §4) and wired in this repo (`.claude/settings.json`). It already emitted the router (`ORIENT_DOCS`); it was simply off by default. Prompt placement carries the process, the hook is the backstop that survives long contexts and compaction. `sdlc_check.py` unchanged.
+- **`source_kind: code` write trigger gets a real phase** — the Write-Triggers row moves from phase `any` (nobody's phase) to `4 / 5`, and Phase 5 gains a **Comprehension checkpoint** that asks the question out loud before closure: did this session force me to build a model of a high-complexity component no CURRENT guide covers? The duty still fires the moment the signal is recognized; the checkpoint is a backstop, not a deferral.
+- **`guides.md` §0** gains the declare-the-verdict rule and its anti-theater twin (never fake a verdict; a verdict listing several guides means the match was not targeted, T7). **`dispatch.md`** pins verdict ownership: the orchestrator declares once at plan-authoring; a dispatched subagent does not.
+
+### Added
+- **`vision.md` — the drafting discipline that makes a Vision verifiable by a cold reviewer (F-018).** A Vision is a gate: a reader with no other context must rule ACCEPT or REJECT on a proposed change, quoting one line. Most cannot, and the gap is invisible from the inside. This file is the *why it works*, derived empirically from six blind adversarial rounds (reviewers with no repository access, ~25 attack proposals) by comparing the rules that survived every attack against the rules that fell. It carries: the **nine properties of a rule that holds** (key it to an observable property of the artifact, never to intent — *a rule whose predicate is a promise is satisfied by making the opposite promise*; both branches of the decision question answered; counterfactual phrasing; near-miss verbs enumerated; terms defined by effect with a closure rule; forms rather than instances; a checkable subject predicate; an IN/OUT pair on one axis; the anticipated re-descriptions named inside the rule's own sentence); the **five structural clauses** around them (supremacy, exceptions attached affirmatively, anti-abuse on every exemption, stated defaults per path, precedence); the **reject/admit asymmetry** — *only prohibitions reject, only positives admit*, so a Goal cannot stop anything and a criterion phrased as an already-true state cannot be advanced; the **minimum operable sections**; the **five failure classes no wording fixes** (each mapped to a mechanism, not better prose); and the **blind-check procedure** — text pasted not linked, fresh context, a battery with an accept side because *a gate that can only reject is half a gate*, and the demand for the mechanism behind each ruling. Wired from the Vision Gate (Standalone and Hybrid/M-VISION), the Write-Triggers Vision row and the `templates.md` Vision template, which is restructured to the operable sections with each marked `[gate]` or orientation. Shipped in the package allowlist. New invariant `test_vision_discipline_wired`; battery 57/57. Anchored by the owner's definition (`## What a Vision IS`): *a Vision states the benefit to be obtained while leaving the most degrees of freedom possible — it binds nothing that does not obstruct that benefit.* Operationalized as: benefit-not-mechanism (the test a North Star must pass), the **deletion test** as the generative rule for every constraint (remove the rule — benefit still reachable? delete it) and its stop rule, constraints that accumulate as work reveals obstacles (an almost-empty first draft is correct: DRAFT informs, APPROVED binds), and the invariant that a constraint never obstructs the Vision — a conflict is an amendment, owner-owned. The deletion test decides WHICH rules exist; the nine properties decide HOW to write one that holds. `elicitation.md` aligned: a mechanism is not an acceptable answer to the benefit question.
+
+### Repository (this project's own `ai_docs/`, not shipped in the package)
+- **Vision rewritten after a blind-reviewer clarity check (F-017)** — three reviewers with fresh context and **no repository access** read `ai_docs/vision/project_vision.md` cold: verdict FAIL, 10 convergent findings. Decisive one: the proposal *"cap how many operative guides a free user may create per month"* was **admissible on the literal text** — no Non-Goal covered metering, and every anti-paywall constraint was bound to the proper noun `devPNT` rather than to paywalling as a class, so the same proposal under another name passed untouched. The Vision was also undecidable in general: its only affirmative admission test was that a change "inherits `ai_docs/` frontmatter, manifest and lifecycle" — a test of form, not substance. Rewritten as `Status: DRAFT` (pending owner promotion): the product is stated in its own terms with no competitor in the North Star, a `## Core Problem` names myopia, Non-Goals are rules over classes (metering/paywall/account-gating; required network or off-repo storage; code or release coupling), a new `## The admission test` requires a change to advance a Success Signal and not merely be well-formed, and the six Success Signals are each checkable against a named artifact or command. The A/B/C/D layer map moved to its real home `strategic/capabilities_and_positioning.md`, declared a dated snapshot. Evidence: `audit/reviews/BLIND_VISION_REVIEW_2026-07-27.md`; finding-by-finding disposition: `solutions/ANALYSIS_vision_clarity.md`. **No skill file changed** — this is the project's own governance, and the improvement is asserted until the blind lenses are re-run against the promoted text.
+
+### Process note
+Doc-only + tests: no `sdlc_check.py` or packaging change. Standalone L3 (devPNT off this session). Governed by `ai_docs/solutions/ANALYSIS_guide_activation.md` (F-016). Four new static invariants (Rule-Zero verdict, Phase-1 router read, code-guide phase, hook promotion) — battery 56/56 green; `validate` 0 errors. New behavioral scenario `verdict_declared_on_no_match.md` proves the "looked, nothing fitted" case; `consult_fires_on_match.md` now also asserts the verdict and that the consult fires unprompted.
+
 ## [1.15.0] - 2026-07-19 (Write Triggers + Code-Comprehension Guides)
 ### Added
 - **Code-comprehension guides (`source_kind: code`)** — a new guide kind the agent writes **autonomously** (a duty, no proposal) when it recognizes a high-complexity component / feature / abstraction layer with no CURRENT guide: a source-faithful map of how the thing works, so the next session starts with the model instead of re-deriving it and breaking the component from partial understanding. Reuses the ENTIRE guide machinery (snapshot + `source_hash` + `stale` + router + fidelity markers) — the source is verbatim CODE EXCERPTS in `.sources/` instead of a handed document; `sdlc_check.py` is unchanged. The skill-wide "propose, never a silent write" rule is relaxed for THIS kind only (additive, code-anchored, reversible); the anti-hallucination floor holds — every claim traces to a code excerpt. Triggered by concrete signals (high comprehension cost, high fan-in, non-obvious flow, prior / repeated-across-sessions breakage from partial understanding, non-local rationale) and by **chronic fragility** (a component breaking repeatedly across sessions → write the guide AND escalate a refactor as its own L3; stop patching). Touches `guides.md` §1–§6, `SKILL.md` (4th "Comprehend" moment + Write-Triggers `code` row + consult wording), `templates.md` (`source_kind` + comprehension repertoire), `debugging.md` (capture-the-model + chronic-fragility). Positioned under Vision **Layer A** (Documentation-First lifecycle applied to code understanding), distinct from Layer D's user-indication operative guides.

package/README.md

@@ -12,7 +12,7 @@
 - **Self-activating**: a SessionStart hook emits repo-sourced orientation; a deterministic self-eval battery guards the skill's own doctrine as the release gate.
 - **Standalone complete**: works fully with local `ai_docs/` without requiring devPNT.
 - **devPNT symbiosis**: when devPNT is available, Master Plan, Action Plan, M-VISION, and governed artifacts become the authoritative planning layer, with independent fresh-context reviews of technical artifacts and diffs.
-- **Installed support files**: Claude, Codex, Gemini, and Google Antigravity receive the full skill folder, including `templates.md`, `guides.md`, `tdd.md`, `debugging.md`, `elicitation.md`, `review.md`, `dispatch.md`, `ENFORCEMENT.md`, and `scripts/sdlc_check.py`.
+- **Installed support files**: Claude, Codex, Gemini, and Google Antigravity receive the full skill folder, including `templates.md`, `guides.md`, `vision.md`, `tdd.md`, `debugging.md`, `elicitation.md`, `review.md`, `dispatch.md`, `ENFORCEMENT.md`, and `scripts/sdlc_check.py`.
 - **Mechanical checks**: optional validator for document structure, generated feature history, stale audit areas, and protected-path gates.
 
 ## Installation
@@ -50,6 +50,7 @@ skills/agentic-sdlc-skill/
 ├── SKILL.md
 ├── templates.md
 ├── guides.md
+├── vision.md
 ├── tdd.md
 ├── debugging.md
 ├── elicitation.md

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-sdlc-skill",
-  "version": "1.15.0",
+  "version": "1.17.0",
   "description": "Documentation-First SDLC protocol with triage, Vision governance and optional devPNT integration.",
   "author": "Antonio Pinto (https://github.com/Antoneeo)"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antoneeo/agentic-sdlc-skill",
-  "version": "1.15.0",
+  "version": "1.17.0",
   "description": "Documentation-First SDLC protocol for Claude Code, Gemini CLI, Google Antigravity and Codex with risk triage, Vision governance, installed support files and optional devPNT integration.",
   "keywords": [
     "claude-code",
@@ -28,6 +28,7 @@
     "skills/agentic-sdlc-skill/SKILL.md",
     "skills/agentic-sdlc-skill/templates.md",
     "skills/agentic-sdlc-skill/guides.md",
+    "skills/agentic-sdlc-skill/vision.md",
     "skills/agentic-sdlc-skill/tdd.md",
     "skills/agentic-sdlc-skill/debugging.md",
     "skills/agentic-sdlc-skill/elicitation.md",

package/skills/agentic-sdlc-skill/ENFORCEMENT.md

@@ -55,9 +55,11 @@ Semantics: exit code 2 + message on stderr ⇒ the write is blocked and the mess
 - The hook assumes the working directory is the project root (standard behavior of Claude Code hooks).
 - **Hybrid/devPNT projects**: add `--hybrid` to the gate command. Governed designs live in the devPNT DB, so the gate also unlocks when an approved E-TDD shadow (`ai_docs/solutions/SHADOW_*tdd*.md`, exported before implementation — see the SKILL.md shadow discipline) is present. Without the flag the gate would block legitimate governed work. The flag is deliberately explicit: never auto-detected.
 
-## 4. SessionStart hook (orientation, optional)
+## 4. SessionStart hook (orientation, recommended default)
 
-Emits the `ai_docs/` orientation — reading guide (`README.md`), manifest (`INDEX.md`), guide router (`reference/INDEX.md`) and last `handoff.md` — plus the Rule-Zero triage reminder to stdout at session start, so the agent begins already oriented instead of reading them only if it remembers to. It is **fail-open**: a missing, unreadable or oversized doc is skipped, the output is size-capped, and it always exits 0 — a broken or empty `ai_docs/` never blocks the session. It is **zero-execution** (it reads and prints, never runs anything) and opt-in.
+Emits the `ai_docs/` orientation — reading guide (`README.md`), manifest (`INDEX.md`), guide router (`reference/INDEX.md`) and last `handoff.md` — plus the Rule-Zero triage reminder to stdout at session start, so the agent begins already oriented instead of reading them only if it remembers to. It is **fail-open**: a missing, unreadable or oversized doc is skipped, the output is size-capped, and it always exits 0 — a broken or empty `ai_docs/` never blocks the session. It is **zero-execution** (it reads and prints, never runs anything).
+
+**Wire it on every project that has `ai_docs/` and a Python interpreter.** It was opt-in until v1.16.0 and the field result was the defect this level exists to prevent: the guide router stayed unread unless the user asked for it by hand, so guides were written and never consulted. Prompt-level placement (Rule Zero declares the router verdict; Phase 1 reads the router) carries the process on its own — this hook is the backstop that survives long contexts, compaction and a session that never enters Phase 1 explicitly. Skip it only where Python is unavailable, and know what you are trading.
 
 Wire it via each client's SessionStart mechanism — the same command everywhere (add `--hybrid` on devPNT/Hybrid projects):
 

package/skills/agentic-sdlc-skill/SKILL.md

@@ -14,6 +14,7 @@ This skill guides software development with a Documentation-First process propor
 Support files in the skill directory:
 - `templates.md`: templates for Vision, ANALYSIS, Spike, audit plan and handoff.
 - `guides.md`: pipeline for distilling user-provided indications into `ai_docs/reference/GUIDE_[topic].md`.
+- `vision.md`: how to write a Vision a cold reviewer can actually apply — the properties that make a rule hold, the minimum operable sections, and the blind check run before promoting one to APPROVED.
 - `scripts/sdlc_check.py`: mechanical validator for `ai_docs/` (`check`, `validate`, `index`, `stale`, `mark`, `gate`).
 - `ENFORCEMENT.md`: optional setup for CI and hooks.
 
@@ -35,6 +36,8 @@ If a patch looks easy but you do not understand why the current code is shaped t
 
 Always classify the request before choosing the process. Declare the chosen level to the user when you start operational work.
 
+**Declare the level WITH the router verdict** (one line, for L2, L3 and Spike — L1 declares the level alone): the result of the guide-router lookup described under `## Operative Guides`, i.e. `Level: L2 · router: no match` or `Level: L3 · router: GUIDE_release.md → read`. The lookup is the consult trigger; making its result a declared output is what keeps it from being skipped — a level declared without a verdict makes "did not look" indistinguishable from "looked, nothing matched". Name the guide you matched, or `no match`; name a second one only when it covers a genuinely distinct concern (typically one operative guide plus the comprehension map of the component you are touching). The verdict is never a listing of the catalogue, and never an excuse to read every guide.
+
 | Level | Criteria | Required process |
 |---|---|---|
 | **L1 - Trivial** | About 10 lines in 1-2 files; no API, dependency or new-behavior change; typos or fixes restoring already-expected behavior | Implement. Run relevant existing tests. No new documents. |
@@ -57,13 +60,15 @@ Triage decides IF documentation is due; this table decides WHICH document each e
 | `solutions/ANALYSIS_[feature].md` | Every L3, after elicitation and before any code. On topic match with an existing analysis, update that one instead of a new file. | 3 |
 | `solutions/SPIKE_[topic].md` | Closing any Spike — including a failed one (a negative outcome is still an outcome). | — |
 | `vision/features/VISION_[feature].md` | Feature known multi-milestone at analysis time, OR the retroactive trigger: you are about to create the SECOND `ANALYSIS_*` on the same theme — extract the shared feature vision first, then let both analyses reference it. | 3 |
-| `audit/handoff.md` | Mandatory at every L3 closure, and at session end when an ANALYSIS is still IN_PROGRESS (even without closure); discretionary after an L2 when useful. Refresh Date / Branch / active features / next step; ≤ 20 lines. | 5 / session end |
+| `audit/handoff.md` (workstream registry) | One row per OPEN workstream (feature, level, branch, status, since, next step, pointer to its Diary/HANDOFF file) — parallel-safe: closing one milestone touches one row, never another's resume point. Refresh the row at every L3 closure (remove it) and at session end when that ANALYSIS is IN_PROGRESS; discretionary after an L2. ≤ 20 lines. | 5 / session end |
+| `audit/handoff.md` — legacy narrative form (pre-1.17 projects) | **Convert lazily, on first write, never as a migration sweep.** A narrative handoff still works: read it as a single-row registry (`## Active features` bullets = the rows, `## Next step` = that row's next step). The first time the Write Trigger above fires, write it in registry form; until then, leave it. Nothing breaks in the meantime — the validator checks only the `Date:` header and its age, and the `orient` hook reads the file verbatim at the same path. | 5 / session end |
+| `audit/HANDOFF_[feature].md` | Session ends with that feature unfinished AND there is volatile resume state (branch/worktree, uncommitted work, environment notes, next command). **Resume logistics only — the ANALYSIS Diary keeps the durable narrative (DRY)**; the file is ephemeral and is DELETED at that feature's closure, same step that flips the ANALYSIS to COMPLETED. | 4 / 5 / session end |
 | `audit/audit_plan.md` (Standalone) | Bootstrap, and whenever a mapped area changes state (`sdlc_check.py mark` records the reference — git hash, else UTC timestamp). | 1 |
 | `reference/GUIDE_[topic].md` (`source_kind: document`) | Origin+purpose test (`guides.md`), or a proactive proposal the user accepted. Propose, never a silent write, never from model knowledge. | 4 / 5 |
-| `reference/GUIDE_[topic].md` (`source_kind: code`) | Recognized high-complexity component/feature/layer with no CURRENT guide — including one that breaks repeatedly across sessions → **duty to write autonomously** (no proposal; additive, code-anchored, reversible). Fidelity floor: every claim traces to a code excerpt. Signals + guard-rails: `guides.md` §1. | any |
+| `reference/GUIDE_[topic].md` (`source_kind: code`) | Recognized high-complexity component/feature/layer with no CURRENT guide — including one that breaks repeatedly across sessions → **duty to write autonomously** (no proposal; additive, code-anchored, reversible). Fidelity floor: every claim traces to a code excerpt. Signals + guard-rails: `guides.md` §1. Write it as soon as you recognize the signal; the Phase-5 Comprehension checkpoint is the backstop that asks the question, never the only moment it may fire. | 4 / 5 |
 | ADR — `architecture/` (Standalone) or devPNT DB (Hybrid) | An architectural decision was taken (new pattern, layer or contract change, structural dependency): record it at closure, before DONE. No decision, no ADR. | 5 |
 | `strategic/architecture.md`, `strategic/existing_features.md` | Bootstrap; update at closure when the stack or the feature catalog actually changed. | 1 / 5 |
-| `vision/project_vision.md`, `roadmap.md`, `principles.md` | Bootstrap, as `Status: DRAFT`; promoted to APPROVED only by explicit user confirmation. | 1 / 2 |
+| `vision/project_vision.md`, `roadmap.md`, `principles.md` | Bootstrap, as `Status: DRAFT`; promoted to APPROVED only by explicit user confirmation, and only after the blind check (`vision.md` §6) — which also gates any amendment of an APPROVED Vision. Write it against `vision.md` §1–§4 from the first draft. | 1 / 2 |
 | `INDEX.md`, `reference/INDEX.md`, `strategic/features_history.md` | Never by hand: regenerated by `sdlc_check.py index` at closure when canonical docs or guides changed (prose discipline where the validator is not adopted). | 5 |
 
 ## Operating Modes
@@ -174,9 +179,9 @@ gate) instead of requiring an IN_PROGRESS ANALYSIS.
 
 ### 1. Audit and Alignment
 
-- Read `ai_docs/audit/handoff.md` if it exists; if its Date/Branch are inconsistent, treat it as history.
-- Read `ai_docs/README.md` (curated must-reads) and `ai_docs/INDEX.md` (generated manifest of all canonical docs) to know what exists before exploring the code. `solutions/` and `audit/` are not indexed per file: search them with glob/grep.
-- Optional: a SessionStart hook (`ENFORCEMENT.md` §4) can emit this orientation automatically at session start (README + INDEX + guide router + handoff + triage reminder); when it is not wired, do these reads manually as above. The hook is a convenience, never a requirement — it introduces no Python dependency for the process itself and fails open (a missing/empty `ai_docs/` never blocks the session).
+- Read `ai_docs/audit/handoff.md` if it exists — the **workstream registry**: one row per open workstream, so you see at a glance what is in PROGRESS, on which branch, since when, before touching anything. If a row's Date/Branch are inconsistent with reality, treat that row as history. When resuming a specific workstream, read its `audit/HANDOFF_[feature].md` (volatile resume logistics) AND its ANALYSIS Diary (durable narrative) — the registry row points at both. A **narrative handoff from a pre-1.17 project** reads as a single-row registry; convert it when you next write it, not now (Write Triggers).
+- Read `ai_docs/README.md` (curated must-reads), `ai_docs/INDEX.md` (generated manifest of all canonical docs) and `ai_docs/reference/INDEX.md` (the guide router) to know what exists before exploring the code. The router is a mandatory read, not an optional one: it is the only orientation step that tells you a guide already governs the work you are about to do. `solutions/` and `audit/` are not indexed per file: search them with glob/grep.
+- Recommended default: a SessionStart hook (`ENFORCEMENT.md` §4) emits this orientation automatically at session start (README + INDEX + guide router + handoff + triage reminder), so the router reaches the context even in a session that never opens Phase 1 explicitly. Wire it wherever Python is available; when it is not wired, do these reads manually as above — the process never depends on it, and it fails open (a missing/empty `ai_docs/` never blocks the session).
 - If `ai_docs/` is missing or incomplete, create the structure and the **bootstrap set** by analyzing the project in batches: `README.md`, the three `vision/` docs (`Status: DRAFT`), `strategic/architecture.md`, `strategic/existing_features.md` and — Standalone — `audit/audit_plan.md`; then regenerate `INDEX.md`. Nothing else is mandatory at bootstrap (per-document triggers: Write Triggers).
 - In Standalone use `ai_docs/audit/audit_plan.md` for mapping and state.
 - In Hybrid prefer the devPNT/KL mapping when available; do not duplicate plan governance.
@@ -189,11 +194,13 @@ Standalone:
 - If a document declares `Status: DRAFT`, treat it as a hypothesis: flag conflicts, but do not block an explicit user request.
 - If it declares `Status: APPROVED` and the request conflicts, stop and ask for a choice: update the Vision or modify/reject the request.
 - Never promote a Vision to `APPROVED` without the user's confirmation.
+- **Writing or amending a Vision is its own discipline — follow `vision.md`.** Draft against its §1–§4 (the properties that make a rule survive a motivated reader, and the minimum sections a gate needs), then run the **blind check** (§6) before promotion to APPROVED and before any amendment of an approved Vision. A Vision that has never been read cold by someone with no other context has not been tested at the only thing it exists to do.
 
 Hybrid:
 - Read the milestone's M-VISION, or ask for/create the step required by the devPNT protocol.
 - Verify that the request serves a benefit or success signal of the M-VISION.
 - If the request adds unauthorized scope, treat it as a Vision divergence.
+- The M-VISION is a Vision: `vision.md` applies to it too. The gate lens of the blind check (§6) is the proportional subset for a milestone-scope document.
 
 ### 3. Request Analysis
 
@@ -219,7 +226,7 @@ Hybrid L3:
 - Isolate the work: run an L3 change on its own branch. In Hybrid, prefer a git worktree from the start — a running devPNT server locks `.devpnt/*.db` and blocks in-place branch switches/merges in the primary worktree.
 - Modify surgically, consistently with the plan.
 - Implementation work follows the TDD discipline in `tdd.md` (RED/GREEN/REFACTOR — the L2/L3 default; record the reason when it does not apply).
-- Before implementing (L2/L3; L1 exempt), **consult the guide router** for a guide covering the task — operative, or a comprehension map of the component you are about to touch — and read it first (the consult trigger, `guides.md` §0, summarized under `## Operative Guides`). A targeted description match, not a blanket read.
+- Before implementing (L2/L3; L1 exempt), **consult the guide router** for a guide covering the task — operative, or a comprehension map of the component you are about to touch — and read it first (the consult trigger, `guides.md` §0, summarized under `## Operative Guides`). A targeted description match, not a blanket read. Its result is the router verdict already declared with the triage level (Rule Zero); re-run the lookup here only if the work has moved to a topic the first lookup did not cover, and say so if the verdict changes.
 - If the environment does not allow automated tests, declare the alternative verification and the reason.
 - For bugs (L2/L3), follow the systematic debugging method in `debugging.md`.
 - Circuit breaker: after 3 consecutive runs without progress on the tests, stop, switch to the systematic method in `debugging.md`, and ask for instructions if still stuck. `debugging.md` also covers **chronic fragility** — a component that breaks repeatedly across sessions is a comprehension + complexity signal (write the `source_kind: code` guide AND escalate a refactor), not a fourth patch.
@@ -232,8 +239,9 @@ Hybrid L3:
 - For the review itself follow `review.md` (requesting and receiving findings) — the single definition, intended for reuse by the Hybrid review gates (devPNT-side wiring out of this unit's scope).
 - Verify alignment with the local Vision or the devPNT M-VISION.
 - If the work was governed by user-provided indications and is reusable, **PROPOSE distilling a guide** (proactive trigger, `guides.md` §1) — a proposal for the user, never a silent write, never from model knowledge.
+- **Comprehension checkpoint**: ask explicitly — *did this session force me to build a model of a high-complexity component that no CURRENT guide covers?* If yes, WRITE the `source_kind: code` guide now (a duty, not a proposal — `guides.md` §1) and say so in the closure. The knowledge you paid to build is at its most complete right here; one closure later it is gone, and the next session re-derives it or breaks the component from partial understanding.
 - Update only the documents actually impacted.
-- **Update `audit/handoff.md`** — mandatory at every L3 closure (Date, Branch, active features, next step; ≤ 20 lines). The session-end rule and the L2 case: Write Triggers.
+- **Update the workstream registry (`audit/handoff.md`)** — mandatory at every L3 closure: REMOVE the closed workstream's row and DELETE its `audit/HANDOFF_[feature].md` (history lives in git and in the Diary); leave every other row untouched — that is the parallel-safety the registry exists for. ≤ 20 lines. The session-end rule and the L2 case: Write Triggers.
 - **Aligned indexes (Poka-Yoke)**: if you created, moved or removed canonical documents (`vision/`, `reference/`, `architecture/`, `functional/`, `strategic/`):
   - regenerate the manifest with `sdlc_check.py index` (writes `ai_docs/INDEX.md`) — never write it by hand;
   - if the document is a must-read, add/update its line in the curated `README.md`;
@@ -274,7 +282,7 @@ Legacy note: the validator also accepts the deprecated Italian frontmatter keys
 ## Operative Guides
 
 Guides are **consulted, created, proposed, and (for code) authored for comprehension** — four moments; the mechanics live once in `guides.md`. Two source kinds: `document` (user indications, operative) and `code` (a comprehension map of a complex component):
-- **Consult (before acting):** before operative L2/L3 work (L1 exempt), check the guide router for a guide covering the task and read the match first — a targeted description match, never a blanket read. → `guides.md` §0.
+- **Consult (before acting):** before operative L2/L3 work (L1 exempt), check the guide router for a guide covering the task and read the match first — a targeted description match, never a blanket read. **Declare the verdict** on the same line as the triage level (Rule Zero): the lookup is only reliable when its result is visible. → `guides.md` §0.
 - **Create (from user indications):** the origin+purpose test below (`source_kind: document`).
 - **Propose proactively (after success):** after reusable, user-indication-governed work, PROPOSE distilling a guide — a proposal, never a silent write, never from model knowledge. → `guides.md` §1.
 - **Comprehend (code, autonomous):** when a component/feature/layer is high-complexity and no CURRENT guide covers it, it is your DUTY to WRITE a `source_kind: code` comprehension guide autonomously — no proposal (additive, code-anchored, reversible); every claim traces to a code excerpt. Signals + guard-rails: `guides.md` §1.

package/skills/agentic-sdlc-skill/dispatch.md

@@ -38,7 +38,9 @@ consult trigger (`guides.md` §0) applied at plan-authoring time: the orchestrat
 runs the router lookup (project router `ai_docs/reference/INDEX.md` + the agent-KB
 router) when populating `guides`. A dispatched context-free subagent does **NOT**
 run its own router consult — it reads the guide pointers handed to it in the
-brief. (Proactive guide-creation stays at closure — the same broad final pass
+brief. The router verdict (Rule Zero) is therefore declared ONCE, by the
+orchestrator, when it authors the plan; a dispatched subagent does not declare
+one. (Proactive guide-creation stays at closure — the same broad final pass
 below — so it needs no separate dispatch hook.)
 
 ## Model tiers (client-relative, no provider names)

package/skills/agentic-sdlc-skill/elicitation.md

@@ -14,7 +14,11 @@ Ask ONE structured set of questions, not a drip of follow-ups. Keep each
 question short and numbered; offer concrete options where a real choice
 exists (this narrows the reply and speeds up the round). Cover:
 
-1. **Goal / benefit** — what problem this closes and why now.
+1. **Goal / benefit** — what problem this closes and why now. The answer must
+   name what the actor *obtains*, not a mechanism: "a dashboard" is not an
+   answer to "never lose the thread" — ask again until it is a benefit
+   (`vision.md`: the Vision is the distilled benefit; solutions and preferences
+   are what gets filtered out).
 2. **Actors** — who interacts with this: their role, primary goal, and what
    "good UX" means to them. These become the Vision's `## Actors`; each
    use-case below attaches to one (actor = who they are, use-case = what

package/skills/agentic-sdlc-skill/guides.md

@@ -40,6 +40,18 @@ already cover how to do this well?*
   the task — never load every guide, which would reintroduce the exact token
   cost the "point to them" model exists to avoid. The two-level model (compact
   synthesis / verbatim snapshot) already bounds a single guide's cost.
+- **Declare the router verdict.** The lookup result travels with the triage
+  level (`SKILL.md` Rule Zero) as one line — `router: no match`, or
+  `router: GUIDE_x.md → read`. This is what makes the consult reliable: an
+  undeclared lookup is indistinguishable from a skipped one, to the user, to a
+  later reviewer, and to you in the next session. Declaring `no match` on a repo
+  with no matching guide is the correct, expected output — not noise.
+- **Never fake the verdict.** `no match` means the router was read and nothing
+  fitted. A verdict that is always `no match` certifies a lookup that did not
+  happen and is worse than silence; a verdict listing the catalogue means the
+  match was not targeted (T7). Two guides are legitimate only when they cover
+  distinct concerns — typically an operative guide plus the comprehension map of
+  the component being touched; three is a smell, not a thorough lookup.
 - **Under subagent dispatch** the consult happens at plan-authoring time (the
   orchestrator populates each task's `guides` field); a context-free subagent
   reads the pointers it was handed and does not run its own router lookup. See
@@ -103,6 +115,11 @@ the component from partial understanding.
   guide per topic, both routers). Honor the fidelity floor (§3). RECOMMEND the
   independent guide-vs-source review (§5) — it matters more here, since no human gated
   creation. Announce the autonomous write in the closure / handoff so it is visible.
+- **When it fires.** As soon as you recognize the signal, during the work. The
+  Phase-5 **Comprehension checkpoint** (`SKILL.md` §5) is the backstop that asks the
+  question out loud before closure — a safety net for a signal you noticed and did not
+  act on, never a licence to defer. Writing it at closure is still far better than not
+  writing it: the model you built is complete now and gone next session.
 
 ## 2. Pipeline
 

package/skills/agentic-sdlc-skill/review.md

@@ -22,6 +22,14 @@ When you hand work to a reviewer (human or agent), give them:
   (Hybrid: `P-TM`; Standalone: the ANALYSIS `## Security and Threat Model`). Hand these
   *in addition to* the design artifact — the reviewer checks the artifact **against**
   them, not only for internal consistency.
+- **For a design review, the threat model too** (same sources as above). Why this
+  one and not the whole set: file coverage crosses the impact-analysis→design hop on
+  a mechanical gate (every impacted file needs a design block), so a dropped file is
+  caught; **threats have no such gate** — a threat answered in the impact analysis
+  can silently fail to become a security requirement in the design, and the later
+  code review only verifies the requirements that are there, never the ones that
+  should have been. The design reviewer checks that every threat surface the change
+  touches has a matching security requirement.
 
 Never ask a reviewer to "review my session" or "review what I just did"
 without the artifacts above — that forces them to reconstruct scope from

package/skills/agentic-sdlc-skill/templates.md

@@ -77,9 +77,10 @@ Curated must-read index, by hand (it is NOT the generated manifest). Created at
 Must-reads for this project, in order. The full manifest of canonical docs is
 `INDEX.md` (generated — regenerate with `sdlc_check.py index`, never edit by hand).
 
-1. `vision/project_vision.md` — why the project exists (check its Status first).
-2. `strategic/architecture.md` — how it is built.
-3. `audit/handoff.md` — where work stopped last session (if present).
+1. `reference/INDEX.md` — the guide router: which guide already governs the work you are about to do (generated).
+2. `vision/project_vision.md` — why the project exists (check its Status first).
+3. `strategic/architecture.md` — how it is built.
+4. `audit/handoff.md` — where work stopped last session (if present).
 
 Directory purposes: `vision/` (project direction), `strategic/` (architecture and
 feature catalog), `reference/` (operative guides), `solutions/` (per-feature
@@ -88,23 +89,81 @@ analyses, discovery-by-grep), `audit/` (audit plan and handoff).
 
 ## ai_docs/vision/project_vision.md
 
+A Vision states **the benefit to be obtained while leaving the most degrees of
+freedom possible** — it binds nothing that does not obstruct that benefit (the
+deletion test, `vision.md` §What-a-Vision-IS). It is *applied* as a **gate**: a
+cold reader must be able to rule ACCEPT or REJECT on a proposed change, quoting
+one line, without asking anyone anything. Write it against `vision.md` §1–§4 from
+the first draft — the properties that make a rule survive a motivated reader are
+cheap to apply while writing and expensive to retrofit. `vision.md` §6 is the
+blind check that gates promotion to APPROVED.
+
+Sections below marked **[gate]** are load-bearing for that ruling; the others are
+orientation for humans. Keep the human ones — just know which is which.
+
 ```markdown
 # Project Vision
 Status: DRAFT
 <!-- Status: DRAFT (reconstructed by the agent, NOT a gating authority)
-     or APPROVED (by <who>, <date>) — only after the user's explicit confirmation -->
+     or APPROVED (by <who>, <date>) — only after the user's explicit confirmation
+     AND the blind check in vision.md §6. -->
 
 ## North Star
+<!-- [gate, partly] The BENEFIT to be obtained — what the actor gets, never the
+     mechanism, and never by comparison to another product (a comparative
+     definition rots silently when the comparison target moves). Concrete enough
+     that an obstacle to it is recognizable: that is what makes every Non-Goal
+     below derivable and refutable. Also restate here any boundary a ruling
+     depends on but that is defined elsewhere: risk tiers, lifecycle states,
+     scale levels. Routing the reader to another file breaks the cold-read
+     premise. -->
+## Core Problem
+<!-- Human orientation: what goes wrong without this product. Carries no gate
+     weight unless the admission test names it. -->
 ## Actors
-<!-- the cast this product serves. One light line per actor:
+<!-- [gate] the cast this product serves. One light line per actor:
      **Role** — primary goal; good UX = what a good experience means to them.
-     Define each actor ONCE here; use-cases (Standalone) / D-UC (Hybrid) reference
-     them by role and never re-describe who they are (anti-DRY). Actors characterize
-     the intended UX; keep it proportional — a role list, not persona research. -->
-## Core Problem
+     The "good UX =" clauses are admissible work, not decoration — say so in the
+     admission test. Define each actor ONCE here; use-cases (Standalone) / D-UC
+     (Hybrid) reference them by role and never re-describe them (anti-DRY).
+     Proportional: a role list, not persona research. -->
 ## Goals
+<!-- [gate — the ACCEPT side] Each with a baseline and headroom, so "advances this"
+     has meaning. A goal phrased as an already-true state cannot be advanced.
+     Include the recurring legitimate work explicitly (packaging and installation,
+     the product's own tests, reducing what the agent must read, one more client) —
+     otherwise your own test rejects the maintenance the product needs. -->
+## Invariants
+<!-- [gate] The promises that outrank everything: what the user is guaranteed, what
+     the architecture must always be true of. State each as ONE decision question
+     with BOTH branches answered, plus an anti-laundering clause naming the
+     re-descriptions you expect. Omit the section if the product has none. -->
 ## Non-Goals
+<!-- [gate — the REJECT side; this is your ENTIRE rejection surface]
+     Derive every rule by the deletion test: remove it — if the benefit is still
+     reachable, the rule does not belong (it spends a degree of freedom on
+     nothing); if not, keep it and name the obstacle it removes. Constraints
+     accumulate as work reveals obstacles — an almost-empty first draft is
+     correct, not incomplete.
+     Open with a supremacy clause: what these bind (all layers, tiers, paid
+     components, future components), and that packaging or naming is irrelevant.
+     Each rule: an observable property of the artifact (never intent or a promise),
+     a closed enumeration with a closure rule, the near-miss verbs, an IN and an OUT
+     example on the same axis, and its exception attached in the same bullet.
+     Nothing here that cannot be violated by a proposed change — a rule about this
+     document's own prose can never fire, and wastes a slot. -->
+## The admission test
+<!-- [gate] One sentence naming EXACTLY which sections are positive sources and
+     EXACTLY which are prohibitions. State what the test does NOT govern (defect
+     fixes, performance, maintenance) and give that exemption its own anti-abuse
+     clause. State the default for anything unreached, per path. -->
 ## Success Signals
+<!-- [gate] Each checkable against a NAMED artifact or command by someone who was
+     not here. Not "we are the best" — a file, a command, a battery, and what the
+     result must be. -->
+## Where the rest lives
+<!-- Pointers, so an absence reads as intentional rather than as a gap. Competitive
+     positioning goes here as a dated snapshot, never in the Vision body. -->
 ```
 
 ## ai_docs/vision/roadmap.md
@@ -277,26 +336,61 @@ States: PENDING (to analyze) | ANALYZED (analyzed, with reference) | SKIPPED (wi
 | vendor/ | SKIPPED | - | vendored code |
 ```
 
-## ai_docs/audit/handoff.md
+## ai_docs/audit/handoff.md — the workstream registry
+
+One row per OPEN workstream, ≤ 20 lines. **Parallel-safe by construction**: closing
+one milestone removes one row and never touches another's resume point — the defect
+this replaces was a single narrative slot where the last session to close overwrote
+everyone else's handoff. It is an **inventory for lookup** (like the generated
+manifest), not a work board: no assignment, no due dates, no execution ordering.
 
-Just a pointer, ≤ 20 lines. The detail lives in the Diary of each ANALYSIS.
+Updated at every L3 closure (row removed) AND at session end with work still
+IN_PROGRESS (row refreshed) — see Write Triggers.
 
-Written at every L3 closure AND at session end with work still IN_PROGRESS (see SKILL.md, Write Triggers).
+**Coming from a pre-1.17 project** (narrative handoff with `## Active features` /
+`## Next step` / `## Session notes`): nothing is broken and nothing is urgent — the
+validator only checks the `Date:` header and its age, and the orientation hook reads
+the file verbatim. Read it as a one-row registry, and convert it the next time the
+write trigger fires: each `## Active features` bullet becomes a row, `## Next step`
+becomes that row's next step, `## Session notes` becomes `## Project-wide notes`.
+Migrating a repository that is not being worked on buys nothing.
 
 ```markdown
-# Handoff
+# Handoff — workstream registry
 Date: 2026-06-11 (UTC)
-Branch: feature/sso-login
-Agent: Claude
 
-## Active features
-- F-001 — see solutions/ANALYSIS_login_sso.md (Diary section)
+| Workstream | Level | Branch | Status | Since | Next step | Details |
+|---|---|---|---|---|---|---|
+| F-001 SSO login | L3 | feature/sso-login | PROGRESS | 2026-06-10 | wire callback tests | HANDOFF_login_sso.md · ANALYSIS_login_sso.md |
+| F-002 Audit refresh | L3 | feature/audit | PAUSED | 2026-06-02 | resume at Phase 4 | ANALYSIS_audit_refresh.md (no volatile state) |
+
+## Project-wide notes
+<!-- one or two lines: release pending, environment quirks that affect everyone -->
+```
+
+## ai_docs/audit/HANDOFF_[feature].md — volatile resume logistics (ephemeral)
+
+**Resume logistics ONLY; the ANALYSIS Diary keeps the durable narrative (DRY).**
+The boundary: Diary = what happened and why (decisions, state of the work — survives
+forever); this file = how to pick the work back up (branch/worktree, uncommitted
+state, environment notes, the next concrete command — worthless once resumed).
+Created only when a session pauses the feature WITH volatile state to record;
+**DELETED at the feature's closure**, in the same step that flips the ANALYSIS to
+COMPLETED — anything in it worth keeping was in the wrong file.
+
+```markdown
+# HANDOFF: [feature] (ephemeral — deleted at closure)
+Updated: 2026-06-11 (UTC)
+Branch: feature/sso-login (worktree ../wt-sso)
+
+## Resume state
+<!-- uncommitted files, half-run migrations, env vars, running services -->
 
-## Next step
-<!-- one line -->
+## Next command
+<!-- the literal next thing to run or edit -->
 
-## Session notes
-<!-- visions read this session? drafts to have validated? -->
+## Watch out
+<!-- traps discovered this session that bite on resume (locks, CRLF, flaky test) -->
 ```
 
 ## ai_docs/strategic/architecture.md and existing_features.md

package/skills/agentic-sdlc-skill/vision.md

@@ -0,0 +1,245 @@
+# Writing a Vision that a cold reviewer can actually apply
+
+Support file for `ai_docs/vision/project_vision.md`, `vision/features/VISION_*.md`
+and (Hybrid) the devPNT M-VISION. Read it when writing or amending any of them.
+The template lives in `templates.md`; this file is the *why it works*.
+
+**The problem this solves.** A Vision's job is to be read cold — by a later
+session, by a reviewer, by another agent — and to produce a ruling on a proposed
+change. Most Visions cannot do that: they read as intent to whoever wrote them and
+as ambiguity to everyone else, and the gap is invisible until something wrong gets
+through. Writing one and then discovering the holes by adversarial rounds works,
+but it costs several rewrites. The checklist below exists so a Vision is
+verifiable on the **first** draft.
+
+Everything here was derived empirically: six blind adversarial rounds against one
+real Vision, reviewers with no repository access, ~25 attack proposals. Rules that
+survived every attack and rules that fell were compared for structure. What
+follows is that difference.
+
+## What a Vision IS
+
+A Vision states **what is to be obtained — the benefit — while leaving the most
+degrees of freedom possible. It binds nothing that does not obstruct that
+benefit.**
+
+Four consequences, each operational:
+
+- **State the benefit, not the mechanism.** What the actor *obtains*, never how —
+  and concrete enough that an obstacle to it is *recognizable*. This is the test a
+  North Star must pass: from "best-in-class" no constraint is derivable and none
+  is refutable, because nothing recognizably obstructs it. From "everything the
+  methodology produces stays usable in full without paying", a metering ban
+  follows and can be checked.
+- **The deletion test — the generative rule for every constraint.** Remove the
+  rule: is the benefit still reachable? If **yes**, delete the rule — it was
+  spending a degree of freedom on nothing. If **no**, keep it, and its sentence
+  must name the obstacle it removes. This is also the stop rule: when nothing on
+  the table would obstruct the benefit, the Vision needs no new rule.
+- **Constraints accumulate as the work reveals obstacles.** The first draft is the
+  benefit plus the few constraints already known — usually almost none, and that
+  is correct (`DRAFT` informs, `APPROVED` binds). Each constraint added later
+  *sharpens* the Vision without shrinking it more than the obstacle requires.
+- **A constraint never obstructs the Vision.** A proposed rule that conflicts with
+  the benefit is not a constraint to negotiate in place — it is a Vision
+  **amendment**, and amending is the owner's decision, never a side effect of a
+  downstream edit.
+
+Extracting the benefit from a discussion is real work: a discourse arrives with
+solutions, preferences and constraints tangled together, and the Vision is the
+distilled benefit only. The elicitation round (`elicitation.md`) asks for it first
+— and a mechanism ("a dashboard") is not an acceptable answer to a benefit
+question ("never lose the thread"); ask again until the answer names what the
+actor obtains.
+
+The deletion test decides **which** rules exist. Everything below decides **how**
+to write a rule so it holds once you know it must exist.
+
+## 0. The one-line test
+
+> Could a reader who has never seen this project rule ACCEPT or REJECT on a
+> proposed change, quoting one line of this document, without asking anyone
+> anything?
+
+If a section cannot contribute to that, it is background — keep it if it helps a
+human, but know it carries no gate weight.
+
+## 1. The nine properties of a rule that holds
+
+Each is stated as a drafting action, with the attack it defeats.
+
+1. **Key the rule to a property observable in the artifact — never to intent,
+   commitment, plan or purpose.** Test while drafting: *could I verify compliance
+   by reading the diff, without asking the author what they meant?*
+   → Defeats: the proposer simply promises the opposite. A rule that forbids
+   "committing to track someone's format" is satisfied by saying "we commit to
+   nothing"; a rule that forbids "code in this repo that parses a format we do
+   not define" is not.
+2. **Write it as one yes/no question with BOTH branches answered.**
+   → Defeats: a gate that can only reject. A prohibition-only Vision rejects the
+   work it wants (new client support, packaging, bug fixes) and is abandoned.
+3. **Phrase the question counterfactually about capability, not about the status
+   quo** — "could the user obtain this…", not "does the product currently do it".
+   → Defeats: "we never shipped it, so nothing is being taken away."
+4. **Enumerate the near-miss verbs, not just the headline one** — charge / count /
+   cap / condition / gate / degrade / delay / require-signup.
+   → Defeats: the soft form. A generous cap, a free-but-registered tier, a
+   zero-cost counter — all are the same harm and none is the headline verb.
+5. **Define every term the rule turns on by EFFECT, and close the list.** A
+   definition that enumerates mechanisms is a list of the ways you already thought
+   of; end it with "…and anything else the user must give, accept or obtain from
+   us."
+   → Defeats: the third mechanism. "Charge = payment or account" is walked past by
+   "requires opting into telemetry".
+6. **Enumerate the FORMS a violation can take, then state a closure rule** —
+   "anything not named here is out unless it is X".
+   → Defeats: the unnamed variant. "A step, a required field, a check, or a cost
+   that varies but is never zero" kills "auto-filled, zero human input", because
+   the form is still a required field.
+7. **State the subject predicate of any enumerated test in checkable terms.** If
+   the test applies to "a record of work", say what makes something one.
+   → Defeats: denying the subject. The proposer agrees with every item on your
+   list and asserts the list does not apply.
+8. **Give one IN and one OUT example on the same axis, differing in a single
+   variable.** The pair carries the discriminator; without it the reader invents
+   one.
+   → Defeats: the borderline case, which is where every real argument happens.
+9. **Name the re-descriptions you expect, inside the rule's own sentence** —
+   "in any presentation", "however the code got here", "not by a component that
+   does not exist yet", "storing it as Markdown changes nothing".
+   → Defeats: relabeling. A board called a "view" is still a board.
+
+## 2. The five clauses a Vision needs around its rules
+
+Rules do not hold alone. These structural clauses were the difference between a
+rule that survived and the same rule leaking.
+
+- **Supremacy clause** — on any rule a second layer, product, tier or future
+  component could route around: *"these bind the product as a whole; shipping a
+  forbidden thing in the paid layer does not put it out of reach."*
+- **Exceptions attached to the rule they limit, in the same bullet, phrased
+  affirmatively.** An exception in another section is a leak; an exception phrased
+  only as a negation produces CANNOT DECIDE. *"This rule does not reach X;
+  supporting one more X is squarely wanted."*
+- **Anti-abuse clause on every exemption, naming the only permitted outcomes.**
+  A maintenance exemption without one lets any forbidden thing that already
+  shipped be maintained forever, and any new one be framed as a fix to it:
+  *"work framed as a fix to something that should never have shipped is not
+  exempt — it is the removal of that thing, or it is out."*
+- **Stated defaults, per path including the exempt path** — "anything unreached is
+  out"; "an exempt fix that preserves a forbidden thing is out". A test that says
+  "admitted only if" gives new capability a default; exempt work has none unless
+  you write one.
+- **Precedence, when two sentences can both apply.** Two adjacent statements
+  pointing opposite ways are decided by whichever the reader reaches first.
+
+## 3. Only prohibitions can reject; only positives can admit
+
+This is the most common structural failure and it is invisible from the inside.
+
+- **A Goal cannot reject anything.** If the admission test says "advances a Goal
+  and violates no Non-Goal", then rejection power lives *only* in the Non-Goals.
+  A Goal that says "scale cost to risk in both directions" cannot stop cost
+  inflation — you need a prohibition for that.
+- **A prohibition scoped to one rung of your own scale protects only that rung.**
+  Banning ceremony on trivial edits invites the same ceremony one level up.
+- **A criterion phrased as an already-true state cannot be advanced.** "The check
+  is CLEAN at every closure" is a state, so "advances this signal" is meaningless
+  and any proposal citing it is undecidable. Give every positive criterion a
+  **baseline with headroom**: a current value and date, or an explicit list of
+  improvement categories that count.
+- **Give recurring legitimate work an explicit authorization clause**, or it will
+  be rejected by your own test: packaging and installation, the product's own
+  tests, reducing what the agent must read, supporting one more client. Each needs
+  a home in the positive sources — otherwise "moves nothing this document commits
+  to" fires on exactly the maintenance the product needs.
+
+## 4. Minimum operable sections
+
+A Vision is a gate. These are the load-bearing parts; anything else is
+orientation for humans and should be recognized as such.
+
+| Section | Must contain | Enables |
+|---|---|---|
+| Authority & scope | what it binds (all layers, tiers, future components), that packaging is irrelevant, precedence among its own sections, the approval line | both |
+| Defaults | the default ruling for anything unreached, stated per path | both |
+| Admission test | one sentence naming *exactly which* sections are positive sources and *exactly which* are prohibitions | ACCEPT |
+| Positive sources | Goals / Actor commitments / Success Signals — each with a baseline and headroom, checkable against a named artifact | ACCEPT |
+| Prohibitions | property-based, closed enumerations, named re-descriptions, in/out pairs | REJECT |
+| Invariants | the decision question with both branches answered, plus an anti-laundering clause | both |
+| Exemptions | each with its anti-abuse clause | prevents laundering |
+| Definitions & imported facts | terms defined by effect; **any fact from another document a ruling depends on, restated here** with the reason | standalone use |
+| Pointers | what deliberately lives elsewhere, so an absence reads as intentional | prevents false CANNOT DECIDE |
+
+**Imported facts matter more than they look.** If a ruling needs your triage
+levels, your risk tiers or your lifecycle states, restate the boundaries in the
+Vision — routing the reader to another file breaks the cold-read premise the
+whole gate rests on. Keep the procedure elsewhere; bring the boundaries here.
+
+**Keep competitive positioning OUT.** A Vision defined by comparison to another
+product rots silently: the comparison target moves and no one edits your document.
+Put it in a dated snapshot elsewhere and point to it.
+
+## 5. What no wording can fix — use a mechanism instead
+
+Five failure classes are structural. Prose cannot close them; do not try.
+
+| Failure | Mechanism |
+|---|---|
+| "Advances a Goal" is a claim about the world, not the text | Measure it: run the ruling battery before and after, admit on measured improvement |
+| **Cumulative ratchet** — each addition defensible, the sum is the ceremony the Vision forbids | A measured budget: steps per level, tokens the agent loads, artifacts per change; add-one-remove-one |
+| Facts the proposal never states ("a quota of *what*?") | A proposal template that demands them, and a stated rule that omission resolves against the proposal |
+| Structural compliance without truth — every rule satisfied, the artifact still wrong | Independent review; a Vision cannot detect this |
+| An accepted change silently falsifying the Vision | Require the amendment in the same change; check cross-document facts mechanically |
+
+And the sixth, which is why this file exists:
+
+**Adversarial re-description is unbounded.** Every patch names the evasions seen so
+far; a new one always exists. Patch-after-defeat is a treadmill. The only thing
+that converts it into a ratchet is a **standing battery**: keep every attack
+proposal that ever worked as a fixture and re-run the whole set against every
+Vision edit. A Vision without a battery decays the moment someone motivated reads
+it.
+
+## 6. The blind check (procedure)
+
+Run this **before promoting any Vision to APPROVED, and before any amendment of an
+approved one**. Not for DRAFT edits — promotion is when authority is granted, and
+it is rare, so the cost lands where it buys most.
+
+1. **Give the reviewer the document text and nothing else.** Not a path — the
+   text, pasted. Forbid opening files, searching, and web access explicitly. A
+   term the reviewer cannot resolve is then a property of the document, not of
+   their tooling.
+2. **Fresh context, and a different model from the author where the client allows
+   it.** Author self-review is structurally blind to its own omissions.
+3. **Hand them a battery, not an open question.** Concrete proposals to rule on:
+   - the standing fixtures (every attack that ever worked — see §5);
+   - **reject-side** proposals aimed at each prohibition;
+   - **accept-side** proposals the document plainly wants (a bug fix, packaging
+     work, supporting one more client, a documentation improvement). *A gate that
+     can only reject is half a gate, and the accept side is where most Visions
+     fail without anyone noticing.*
+4. **Ask for the mechanism, not just the verdict.** For each ruling: the exact
+   quoted line, or precisely what the document fails to say. Then: *which rules
+   could you not get around, and what structural property defeated you?* That
+   answer is worth more than the findings.
+5. **Ask for rewords.** "Slip a bad proposal past this document, including one
+   dressed in its own approving vocabulary." A rule nobody can reword is done; a
+   rule that falls to the first attempt was never a rule.
+6. **Every finding is answered — fixed, or refused with reasoning** (`review.md`
+   §Receiving). Add every successful reword to the standing battery, whether or
+   not you fix it this round.
+
+Three lenses are worth running for a product-level Vision: **comprehension** (what
+is this, what could you not resolve), **gate operability** (the battery above),
+**durability** (what rots, what is unfalsifiable, what is a time bomb). For a
+feature-level Vision or an M-VISION, the gate lens alone is usually enough.
+
+## 7. Cost, honestly
+
+A first draft written against §1–§4 will still have findings — the checklist
+removes the structural classes, not judgement errors. Expect one blind round to
+find real things and a second to confirm. What it should NOT take is five rounds
+of discovering the same class of defect in a new disguise; that is the specific
+waste this file exists to prevent.