@antoneeo/agentic-sdlc-skill 1.42.0 → 1.43.1

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 Tutte le modifiche significative a questa skill saranno documentate in questo file.
 
+## [1.43.1] - 2026-10-18
+
+### Fixed
+- F-072 (field run): the `SKILL.md` line that announces the docs site now reads `scripts/docs_site.py --root <project> --open` and says to use it to show the project state. Asked for the state, an agent had opened the site in its own client pane, where it renders blank, and improvised a local server; `--open` opens it in the user's browser, where it works offline.
+
+## [1.43.0] - 2026-10-18
+
+### Added
+- F-074: every Vision is born from an owner interview. Before any Vision text is written (project, feature, lens, and the devPNT M-VISION), the agent asks the owner six questions in order, re-asking an answer that has the wrong form: the problem as one concrete case, the benefit as a result for someone, the actors including who takes the initiative, a success signal with its starting value, the boundaries, and the known constraints with where each comes from. Then the owner approves a one- or two-sentence north star in their own words; without it no Vision is written, not even a draft. The blind check still tests that the rules hold; the approved north star shows they are the owner's. `vision.md` §The owner interview.
+
+### Changed
+- `elicitation.md`: the skip path never covers a Vision; one sentence plus a spike is not a complete spec.
+- Bootstrap no longer writes a Vision reconstructed by the agent: `agentic-sdlc-init` seeds `ai_docs/vision/project_vision.md` as a stub awaiting the interview (an existing file is never overwritten).
+- A Non-Goal now bounds scope. It rejects a proposal that pursues what it names; it is not a ban on behaviour that already exists and creates no obligation. A behaviour that must never happen is an Invariant or a constraint with its source.
+- Vision templates ask for the north star in the owner's words with its approval, the problem as a case, the actor with the initiative, signals with starting values, and the source of every rule. Regression: `evals/scenarios/vision_needs_owner_interview.md`.
+
 ## [1.42.0] - 2026-10-18
 
 ### Added

package/README.md

@@ -21,7 +21,7 @@ Vendoring requires all three files: the entry point, `sdlc_core.py`, `knowledge.
 ## Key Features
 
 - **Risk-proportional workflow**: L1/L2/L3/Spike triage avoids heavyweight process for trivial work, with a symmetric **Write Triggers** table mapping each event to the document it produces (one event, one destination).
-- **Vision-guided governance**: Standalone projects use `ai_docs/vision/`; Hybrid projects use devPNT `M-VISION` as the milestone north star. The Vision names its **Actors** — the cast a feature serves, one light line each — so UX is designed for concrete roles, not an implicit "user".
+- **Vision-guided governance**: Standalone projects use `ai_docs/vision/`; Hybrid projects use devPNT `M-VISION` as the milestone north star. The Vision names its **Actors** — the cast a feature serves, one light line each — so UX is designed for concrete roles, not an implicit "user". Every Vision, the M-VISION included, is written only after a six-question **owner interview** and your explicit approval of a one- or two-sentence north star in your own words — the agent never writes one alone.
 - **Architect pass — capabilities before files**: at L3, before listing what changes, the feature is stated as the *capabilities* it needs and each is ruled against the platform (EXISTS / INADEQUATE / MISSING); what is missing is designed as a component with its own contract, of which the feature is one consumer — never inlined into the feature's code path. A `## Component Map` in `strategic/architecture.md` is the durable inventory the pass reads, so the platform is not re-derived from source every session. On a codebase the methodology arrives in late, the map's silence is treated as **unread, not empty**: it can never ground a MISSING verdict.
 - **Execution disciplines**: explicit TDD (RED/GREEN/REFACTOR), evidence-first debugging with hypotheses ranked by likelihood and verification cost, supported causal questioning and clean Poka-Yoke correction with regression checks; an L3 spec-elicitation round and a single code-review definition wired into the workflow phases.
 - **Operative + comprehension guides + agent-global KB**: distil user-provided indications into source-faithful operative `GUIDE_*.md` (`source_kind: document`), and let the agent autonomously author **code-comprehension guides** (`source_kind: code`) for complex components — a source-faithful mental-model map that survives across sessions, so the next session doesn't re-derive and break the component from partial understanding. Consulted before work; shared cross-project via `~/.agentic-sdlc`.
@@ -71,7 +71,7 @@ The global package also exposes:
 agentic-sdlc-init
 ```
 
-Run it inside a project to create `ai_docs/`, Vision documents, strategic docs, audit plan, and agent protocol files (`AGENTS.md` — also the Antigravity CLI surface, `CLAUDE.md`, `GEMINI.md`, `.cursorrules`).
+Run it inside a project to create `ai_docs/`, Vision stubs awaiting your interview, strategic docs, audit plan, and agent protocol files (`AGENTS.md` — also the Antigravity CLI surface, `CLAUDE.md`, `GEMINI.md`, `.cursorrules`).
 
 It also **wires the SessionStart orientation hook** into `.claude/`, so an agent opening
 the project is handed the reading guide, the generated manifest, the guide router and the

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-sdlc-skill",
-  "version": "1.42.0",
+  "version": "1.43.1",
   "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.42.0",
+  "version": "1.43.1",
   "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",

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

@@ -1,6 +1,6 @@
 ---
 name: agentic-sdlc
-version: 1.42.0
+version: 1.43.1
 description: Documentation-First SDLC protocol with risk-proportional triage, Vision as a guide, a complete Standalone mode and optional symbiosis with devPNT. Use for features, significant bugs, refactors, audits and documented maintenance.
 author: Antonio Pinto (https://github.com/Antoneeo)
 copyright: (c) 2026 Antonio Pinto
@@ -21,7 +21,7 @@ Support files in the skill directory:
 - `hybrid.md`: the devPNT seam — the authoritative hierarchy, the ownership matrix (who owns what when both authorities are live), the triage equivalence, the feature-state mapping and the shadow discipline. Read it when the `devpnt_*` tools point at this project; a Standalone session never needs it.
 - `routing.md`: which lens owns this unit of work. Read ONLY when a sibling lens skill is installed alongside this one; a single-lens install never reads it.
 - `scripts/sdlc_check.py` + `scripts/sdlc_core.py`: the mechanical validator for the docs root (`check`, `validate`, `index`, `stale`, `mark`, `benefit`, `gate`, `plan`, `orient`, `migrate`).  Keep the entry point, `scripts/sdlc_core.py` and `scripts/knowledge.py` together; the last supplies common memory and KB integrity.
-- `scripts/docs_site.py --root <project>`: writes an offline, read-only site of what the agent reads here, for the user to browse.
+- `scripts/docs_site.py --root <project> --open`: opens in the user's browser a read-only site of what the agent reads; use it to show the project state.
 - `ENFORCEMENT.md`: optional setup for CI and hooks.
 
 Read these files only when needed. `SKILL.md` is the operating contract; the support files are progressive resources.
@@ -89,7 +89,7 @@ Triage decides IF documentation is due; this table decides WHICH document each e
 | `solutions/SPIKE_[topic].md` | Closing any Spike — including a failed one (a negative outcome is still an outcome). | — |
 | `solutions/E2E_TEST_[feature].md` | Every L3, before the closure review (it is part of the reviewed diff): the human tester's post-merge script — new-behavior scenarios when behavior changed, regression scenarios always (`templates.md`). | 5 |
 | `solutions/MERGE_REVIEW_[feature].md` | Every L3, after the closure review: the integrator's brief — what to review (`sdlc_check.py review-map`), what was verified by which gate, what only a human can judge (`templates.md`). The PR description links it. | 5 |
-| `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 |
+| `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. Either way it is written after the owner interview (`vision.md` §The owner interview). | 3 |
 | `audit/handoff.md` (workstream registry) | **Never by hand — generated by `sdlc_check.py index` from the `HANDOFF_*.md` sources**, and `validate` errors when the two disagree. Regenerate at every L3 closure and at session end; the `Date:` header is derived, so no writer touches it. It is an inventory for lookup, not a work board: no assignment, no due dates, no ordering, no holder. | 5 / session end |
 | `audit/HANDOFF_[feature].md` | **One per OPEN workstream, with or without volatile state** — it is the authored home of that workstream's registry row (frontmatter `workstream`/`level`/`branch`/`status`/`since`/`next`/`details`/`updated`), so no file means no row. Its `next:` is the next concrete step in one sentence; what happened, and the state of the work, go to the Diary as a dated entry. Also carries the resume logistics; **the ANALYSIS Diary keeps the durable narrative (DRY)**, and this file is DELETED at closure — deleting it *is* removing the row. | 4 / 5 / session end |
 | `audit/project_notes.md` | A note true for the whole project rather than for one workstream (release pending, environment quirk). Appended verbatim to the generated registry; it exists so regenerating cannot destroy notes that belong to no workstream. | 5 / session end |
@@ -101,7 +101,7 @@ Triage decides IF documentation is due; this table decides WHICH document each e
 | 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 |
 | `strategic/architecture.md` — `## Component Map` | A component was BORN, its contract changed, **or the pass DISCOVERED an existing one while searching an unmapped area** — the same closure adds or corrects its row (`architect.md`). Keyed on the component, not on the stack: a new component is not a stack change, and a discovered one is how an area gets marked ANALYZED while the map stays silent about what lives there — after which the next feature may lawfully rule it MISSING and build it twice. | 5 |
-| `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 |
+| `vision/project_vision.md`, `roadmap.md`, `principles.md` | Bootstrap writes each as a **stub** (`Status: DRAFT`, body: awaiting the owner interview) — never a Vision reconstructed by the agent; what it observed goes to `strategic/`. The Vision itself is written only after the owner interview and its approved north star (`vision.md` §The owner interview), against `vision.md` §1–§4; 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. | 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
@@ -142,7 +142,7 @@ devPNT is not there, work Standalone and nothing is lost.
 - 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. It is generated from the `HANDOFF_*.md` files, so it is read here and never edited here. 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` (its row plus the resume logistics) AND its ANALYSIS Diary (the durable narrative) — the registry row points at both. A hand-written or pre-1.17 narrative handoff still works and is converted 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. On a project with no guides yet it exists as an empty stub (`sdlc_check.py index` writes it precisely so the mandatory read has something to read) — the honest verdict there is `router: no match`, and if the file is genuinely absent, say `router: absent (no router file)` and regenerate it rather than inventing a match. `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).
+- 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 as stubs awaiting the owner interview (`Status: DRAFT`; the agent never reconstructs a Vision — Write Triggers), `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).
 - **Arriving in a project that was never curated** (the usual case — you arrive with a task, not with a bootstrap): write `audit/audit_plan.md` FIRST. It is the scope ledger the rest is built on — one row per area, all PENDING, `SKIPPED` for what genuinely does not merit reading (vendored, generated). Then the other bootstrap documents describe what you have actually analyzed, and the `## Component Map` in `strategic/architecture.md` starts at whatever the first task made you understand. **No full-codebase sweep is required before the first feature**: the map grows feature by feature, each one marking the areas it covered (`sdlc_check.py mark`). What is NOT deferred is comprehension of what the change touches or depends on — that is understood now, at full standard, mapped or not. The licence is about writing the inventory, never about designing on a guess (`architect.md` §2: unmapped is *unread*, not *empty*, and can never ground a MISSING verdict).
 - 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.
@@ -153,13 +153,13 @@ devPNT is not there, work Standalone and nothing is lost.
 Standalone:
 - Read `project_vision.md`, `roadmap.md`, `principles.md`.
 - Compare them with the request as recorded in `audit/requests/REQUEST_[feature].md`, not with a paraphrase of it.
-- If a document declares `Status: DRAFT`, treat it as a hypothesis: flag conflicts, but do not block an explicit user request.
+- If a document declares `Status: DRAFT`, treat it as a hypothesis: flag conflicts, but do not block an explicit user request. A stub awaiting the owner interview is no Vision at all: an L3 that needs one opens the interview.
 - 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.
+- **Writing or amending a Vision is its own discipline — follow `vision.md`.** It starts with the **owner interview** (`vision.md` §The owner interview): six questions in order, then the north star in the owner's words, explicitly approved, before any Vision text exists — there is no skip path, and a one-line request plus a spike is not a spec. Then 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.
+- Read the milestone's M-VISION, or ask for/create the step required by the devPNT protocol. A new or amended M-VISION is born from the owner interview (`vision.md` §The owner interview) exactly like a local Vision: north star approved before the draft, answers in the request record.
 - 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.

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

@@ -11,7 +11,16 @@ requirements or an earlier reply already answer goal, scope, and constraints, an
 any remainder is settled as §When a doubt emerges allows — skip the round and add
 a one-line note in the analysis stating why it was skipped and naming the
 sources. Do not run the round as a formality when the answers are already on
-record.
+record. The skip path never covers a Vision (next paragraph).
+
+Vision path: when the unit writes or amends a Vision — any kind, the M-VISION
+included — the owner interview in `vision.md` §The owner interview runs instead
+of this round for the Vision's own content, and it has **no skip path**: one
+sentence from the user plus a spike never makes a Vision's spec complete. The
+round then covers only what the interview did not (the unit's own scope and
+acceptance), deriving from the interview's answers. The interview is a planned
+occasion like the round (§Ask before the write): its questions go in one numbered
+set, and only an answer in the wrong form is asked again.
 
 Unattended path: when the user is not reachable (a scheduled or autonomous run)
 and a real doubt remains, do not stall and do not invent consensus. Write it as a

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

@@ -106,18 +106,31 @@ the first draft — the properties that make a rule survive a motivated reader a
 cheap to apply while writing and expensive to retrofit. `vision.md` §6 is the
 blind check that gates promotion to APPROVED.
 
+**No section below is written before the owner interview** (`vision.md` §The owner
+interview) and its approved north star. Until then — at bootstrap, or for an owner
+not yet reached — the file is this stub, and nothing traces to it:
+
+```markdown
+# Project Vision
+Status: DRAFT
+<!-- STUB: awaiting the owner interview (vision.md §The owner interview). Not a
+     Vision: no artifact traces to it. What the agent observed is in strategic/. -->
+```
+
 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)
+<!-- Status: DRAFT (written from the owner interview, NOT yet a gating authority)
      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
+<!-- [gate, partly] One or two sentences IN THE OWNER'S WORDS, explicitly approved
+     before any other section was written (Gate 1) — cite the approval:
+     (approved: REQUEST_[unit].md#R<n>). 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
@@ -126,11 +139,15 @@ Status: DRAFT
      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. -->
+<!-- Interview question 1: ONE concrete case that today does not get the expected
+     result, with its example — never a missing feature. Cite the answer
+     (REQUEST_[unit].md#R<n>). Human orientation: carries no gate weight unless
+     the admission test names it. -->
 ## Actors
 <!-- [gate] the cast this product serves. One light line per actor:
      **Role** — primary goal; good UX = what a good experience means to them.
+     Interview question 3: who receives the benefit, who acts, and who has the
+     INITIATIVE — an actor that acts unprompted is named here, or it goes missing.
      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).
@@ -147,7 +164,14 @@ Status: DRAFT
      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]
+<!-- [gate — the REJECT side, with the Invariants]
+     A Non-Goal bounds SCOPE: it rejects a proposal that pursues what it names; it
+     never bans a behaviour the product already has and never creates an
+     obligation (obligations come from the North Star and the Success Signals). A
+     behaviour that must never happen is an Invariant, with its provenance.
+     PROVENANCE on every rule, at the end of its bullet: (source: owner
+     REQUEST_[unit].md#R<n> | higher Vision: "quoted line" | inference confirmed
+     REQUEST_[unit].md#R<n>). An unconfirmed author inference is not a rule.
      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
@@ -167,7 +191,7 @@ Status: DRAFT
      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
+     not here, with its STARTING VALUE (interview question 4). 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
@@ -200,16 +224,33 @@ Only for features spanning multiple ANALYSIS documents or multiple milestones: o
 ```markdown
 # Feature Vision: [Name]
 
+<!-- Written only after the owner interview (vision.md §The owner interview); the
+     same applies to a devPNT M-VISION. Each section cites the answer it comes
+     from: REQUEST_[feature].md#R<n>. -->
+## North Star
+<!-- One or two sentences in the owner's words, explicitly approved before any
+     other section (Gate 1): (approved: REQUEST_[feature].md#R<n>). -->
 ## Problem
+<!-- One concrete case that today does not get the expected result, with its
+     example — not a missing feature. -->
 ## Expected Benefit
+<!-- What who obtains once solved: a result, not a function. -->
 ## Actors
 <!-- the cast this feature serves — usually a subset/refinement of the project
      Actors, or a distinct feature-local cast for internal-tooling work. One light
      line each: **Role** — primary goal; good UX = what good feels like.
+     Name who receives the benefit, who acts, and who has the initiative.
      Referenced by the use-cases, not re-described in them. -->
 ## Success Signals
+<!-- Observable, each with its starting value. -->
 ## Non-Goals / Out of Scope
+<!-- Scope this feature does not pursue. Not a ban on existing behaviour, and no
+     obligation: those come from the Benefit and the Signals. -->
 ## Related Constraints and Principles
+<!-- Each with its provenance: (source: owner REQUEST_[feature].md#R<n> | higher
+     Vision: "quoted line" | inference confirmed REQUEST_[feature].md#R<n>). A
+     constraint imported from a higher Vision is asked about, never assumed to
+     apply here. -->
 ```
 
 ## ai_docs/solutions/ANALYSIS_[feature_name].md
@@ -241,7 +282,9 @@ checks: [marketing.funnel]      # optional — extra portable checks to run on t
      or point to the project Vision's ## Actors — do not re-describe them here).
      This is the single home of the feature vision: the separate file
      VISION_[feature].md is created only if the feature spans multiple
-     ANALYSIS documents or multiple milestones. -->
+     ANALYSIS documents or multiple milestones. A benefit that no existing
+     Vision names makes this section a Vision: write it after the owner
+     interview (vision.md §The owner interview). -->
 
 ## Use Cases / User Needs
 <!-- who needs this and why: the concrete use-cases / user-needs the change serves

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

@@ -1,245 +1,308 @@
-# 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.
+# 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 owner interview below asks for it — 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.
+
+## The owner interview (before any Vision text)
+
+A Vision is the **owner's** statement of what is to be obtained. Nothing in this
+file after this section can detect a Vision the author wrote alone: the blind
+check (§6) tests whether the rules survive a hostile reader, never whether they
+are the owner's. So every Vision is born from an interview of the owner, and its
+north star is approved **before** a line of it is drafted.
+
+**Scope — every Vision, in every mode:** `project_vision.md`, a feature
+`VISION_*.md`, a lens Vision (course, marketing), and the devPNT M-VISION in
+Hybrid; also an ANALYSIS `## Feature Vision` that states a benefit no existing
+Vision names (one that cites an approved Vision's benefit is alignment, not a
+Vision). An amendment re-runs the questions whose answers it changes, and Gate 1
+again when the north star changes. **There is no skip path**: one sentence from
+the user plus a spike is not a complete spec — that exact shortcut produced a
+Vision with an imported prohibition, no north star and a missing actor, and four
+downstream artifacts built on it (field case, 2026-10). A reply already on record
+in the owner's words is read back for confirmation, never re-asked as an open
+question; an answer the author derived (from a spike, the code, another Vision)
+is never an answer — it is a proposal the owner confirms or rejects.
+
+**The questions, in this order.** Each is repeated until its answer has the form
+stated; the wrong form is named so it can be recognized and asked again.
+
+| # | Question | Right form | Wrong form — ask again |
+|---|---|---|---|
+| 1 | **Problem** — which concrete case today does not get the expected result? | one real case, with an example | a missing feature ("there is no drawing tool") |
+| 2 | **Benefit** — once solved, who obtains what? | a result for a named actor | a function or mechanism ("a renderer") |
+| 3 | **Actors** — who receives the benefit, who acts, who has the initiative? | all three named, initiative included | only the one who asks — the actor who acts unprompted goes missing |
+| 4 | **Success** — what observable signal shows the benefit arrived? | a signal with its starting value | a feeling, or a signal with no baseline |
+| 5 | **Boundaries** — what does this NOT pursue? | scope excluded from this work | a ban on behaviour ("X must never happen") — that is a constraint (6) or an obligation (2, 4) |
+| 6 | **Known constraints** — each with its provenance: owner, a quoted line of a higher Vision, or author inference | every constraint sourced; every inference asked here | a constraint written in silently, or imported from a higher Vision without asking whether it applies here |
+
+A **Non-Goal bounds scope**: it rejects a proposal that pursues what it names; it
+is not a ban on behaviour that already exists, and it creates no obligation.
+Obligations come from the Benefit and the Success Signals.
+
+**Gate 1 — north star.** One or two sentences, in the owner's words, explicitly
+approved by the owner. The author may compose a wording from the answers; the
+approval is of that exact text, recorded verbatim in the request record
+(`audit/requests/REQUEST_[unit].md`; a Vision written outside any unit, such as
+the project Vision after bootstrap, records its interview in
+`audit/requests/REQUEST_project_vision.md`). **Without it no Vision text is written** —
+not a DRAFT, not a reconstruction: bootstrap writes a stub awaiting the
+interview, and what the agent observed goes to `strategic/`.
+Unattended, the unit is `BLOCKED on the user` (`elicitation.md` Unattended path).
+
+**Gate 2 — the full Vision**, written from the answers. Every section traces to
+an answer or a stated provenance (`REQUEST_[unit].md#R<n>`); every rule carries
+its provenance; an author inference the owner did not confirm is not in it. The
+blind check (§6) verifies that it holds; the approved north star verifies that it
+is the owner's. Promotion to APPROVED still needs the owner's explicit
+confirmation — Gate 2 is that confirmation, given on the written text.
+
+## 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
+  (and the Invariants, where the Vision has them).
+- **A Non-Goal rejects scope, not behaviour.** It turns away a proposal that
+  pursues what it names; it never forbids a behaviour the product already has, and
+  it never creates an obligation — obligations come from the Benefit and the
+  Success Signals. A behaviour the product must never have is an Invariant, or a
+  constraint with its provenance (§The owner interview, question 6). Written as a
+  Non-Goal, it reads as a ban the owner never stated.
+  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**. It runs on a Vision that already passed Gate 1 (§The owner
+interview): it tests whether the rules hold against a hostile reader, and it
+cannot see whether they are the owner's — a Vision the author wrote alone passes
+it cleanly. 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.