@antoneeo/agentic-sdlc-skill 1.15.0 → 1.19.0

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
@@ -179,8 +238,27 @@ end_date:
      use-case = what they do. Derived from the elicitation round; the Impact below
      must cover each, and the closure review checks coverage + actor UX fit. -->
 
+## Capability Ledger
+<!-- the architect pass (`architect.md`), run BEFORE the Impact below. One row per
+     capability the feature requires the system to be able to DO — a verb over a
+     domain noun, naming no file. Verdict EXISTS (name the component and where) /
+     INADEQUATE (same, plus the gap) / MISSING (say what you searched). Every
+     INADEQUATE or MISSING row becomes a component with its own contract, stated
+     without naming this feature, and lands in the Impact below. Evidence is what
+     makes a verdict falsifiable: for EXISTS/INADEQUATE the one guarantee you
+     re-read to confirm it; for MISSING the terms, the tool and the areas searched
+     (and say "provisional" when the area is still PENDING in the audit plan).
+     A question, not a form: when every capability plainly exists, one line under
+     this heading answers it — still naming the component and where it lives. -->
+
+| Capability | Verdict | Component / gap | Evidence |
+|---|---|---|---|
+| persist an order | EXISTS | `path/to/store.py#OrderStore` | re-read `save()`: durable, returns the id |
+| notify the customer | MISSING | — | grep notify/alert/dispatch + send, over src/ and legacy/; no owner |
+
 ## Impact
-<!-- existing files touched, APIs/contracts, performance, new dependencies -->
+<!-- existing files touched, APIs/contracts, performance, new dependencies.
+     Derived from the ledger above: every INADEQUATE/MISSING row appears here. -->
 
 ## Security and Threat Model
 <!-- ALWAYS mandatory, also in Standalone.
@@ -277,26 +355,94 @@ 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
 
-Just a pointer, ≤ 20 lines. The detail lives in the Diary of each ANALYSIS.
+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.
 
-Written at every L3 closure AND at session end with work still IN_PROGRESS (see SKILL.md, Write Triggers).
+Updated at every L3 closure (row removed) AND at session end with work still
+IN_PROGRESS (row refreshed) — see 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 -->
+```
 
-## Next step
-<!-- one line -->
+## ai_docs/audit/reviews/REVIEW_LOG.md
 
-## Session notes
-<!-- visions read this session? drafts to have validated? -->
+One row per completed review (`review.md` §When a review is due). Append-only; it
+is the record that the gate ran and what it was worth. **One schema for both
+modes** — a Hybrid project's devPNT gates write to this same file, so Standalone
+adds values to the existing columns rather than a second table.
+
+```markdown
+# Independent Review Log
+
+| date | doc_key | tier | reviewer | findings_raised | findings_real | verdict | revise_rounds |
+|---|---|---|---|---|---|---|---|
+| 2026-06-11 | ANALYSIS_login_sso.md | design | subagent (opus, fresh ctx) | 4 | 3 | PASS | 2 |
+| 2026-06-12 | diff feature/sso-login | closure | self-pass (declared; no subagent facility) | 2 | 2 | PASS | 1 |
+
+## Notes
+<!-- One short paragraph per review that found something worth remembering: what
+     the findings actually were, and what changed because of them. The table
+     answers "was it reviewed and by what"; this answers "what did it find" —
+     which is where `review.md`'s per-finding outcomes live. Omit for a clean
+     review; a row with 0 findings needs no note. -->
+```
+
+`tier` is the moment plus, in Hybrid, the reviewer weight: `design`, `design (late)`
+and `closure` (Standalone); `deep`, `light`, `code`, `guide`, `vision` (devPNT gates
+and the Vision blind check). The validator reads this column by its header name, so
+extra or reordered columns are fine — but the header must say `tier`. `reviewer`
+records the realization actually used — fresh subagent, one-shot client run, or a
+**declared** self-pass. Writing `self-pass` where independence was unavailable is
+honest; writing nothing, or implying independence you did not have, is the failure
+this column exists to prevent. `findings_real` is how many raised findings survived
+triage: over time it is the only evidence of whether the gate earns its cost.
+
+## 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 command
+<!-- the literal next thing to run or edit -->
+
+## Watch out
+<!-- traps discovered this session that bite on resume (locks, CRLF, flaky test) -->
 ```
 
 ## ai_docs/strategic/architecture.md and existing_features.md
@@ -305,12 +451,39 @@ Canonical docs: they open with the header (`description:`/`status:`) so they ent
 
 ```markdown
 ---
-description: Stack, directory structure and architectural patterns of the project.
+description: Stack, directory structure, component map and architectural patterns of the project.
 status: CURRENT
 ---
 # Project Architecture
 ## Technology Stack
 ## Directory Structure
+## Component Map
+<!-- The inventory the architect pass reads BEFORE searching the code
+     (`architect.md` §2). One row per component that OWNS a capability:
+     Capability = what it lets the system DO (a verb over a domain noun, naming
+     no file). Contract = what it guarantees its consumers, in one line, stated
+     without naming any single consumer. Where = a path, or `path#symbol` when
+     the component is smaller than its file.
+     Seeded at bootstrap; a row is added or corrected in the SAME closure that
+     builds — or merely discovers — a component, and the area is marked ANALYZED.
+     A directory is not a component: rows name what owns a capability, not where
+     files sit (that is ## Directory Structure above). An absent or stale map is
+     why the next feature rules the same capability MISSING a second time and
+     builds it again. -->
+
+Coverage: whatever `audit/audit_plan.md` marks ANALYZED — **read it, do not trust a
+list restated here** (a hand-copied list is a cache with no invalidation). Outside
+those areas this map is **unread, not empty**: it can never ground a MISSING
+verdict, and the code is searched instead (`architect.md` §2).
+
+| Component | Capability it owns | Contract | Where |
+|---|---|---|---|
+| ... | ... | ... | ... |
+
+<!-- Where is `path/to/file.py#Symbol`. Leave the placeholder row untouched until
+     the map has a real component: the validator skips an all-`...` row, so a
+     freshly seeded project is never nagged about a table nobody has filled in. -->
+
 ## Architectural Patterns
 ```
 

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.