@antoneeo/kb-agentic-skill 1.33.0 → 1.34.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 Every significant change to this skill is recorded here.
 
+## [1.34.0] - 2026-10-31
+
+### What's new
+
+**Decisions taken on your behalf are labelled.** In the request record, a decision a session took under a delegation you gave it, and words you gave one session for work another session records, now carry their own heading. They are never read later as something you said yourself, and a delegated decision never overrides one of yours: a choice that would change it comes back to you as a question.
+
+#### What to do
+
+**1. Update (everyone).** The changes arrive only with the update.
+1. Run `npm install -g @antoneeo/kb-agentic-skill@latest`, then `kb-agentic-install-skill`.
+2. Close and reopen your agent sessions: the new version loads only at startup.
+
+To check: `npm ls -g @antoneeo/kb-agentic-skill` shows 1.34.0.
+
+### Changed
+- Request record (`templates.md`, F-088): labelled entries `decided under delegation R<m>` and `received for <unit>`; `review.md` and `elicitation.md` treat them as the deciding session's choice or relayed words, never an owner statement.
+
 ## [1.33.0] - 2026-10-31
 
 ### What's new

package/README.md

@@ -6,17 +6,9 @@ The sibling of [`@antoneeo/agentic-sdlc-skill`](https://www.npmjs.com/package/@a
 
 <!-- whats-new:begin -->
 <!-- generated by scripts/whats_new.js from distributions/kb-agentic-skill/CHANGELOG.md: edit the CHANGELOG, then run node scripts/whats_new.js --write -->
-## What's new in 1.33.0
+## What's new in 1.34.0
 
-**You approve the design before any drafting.** On significant work, once the independent design review passes, the agent stops and shows you a short summary of the design: what it will produce, for whom, what it touches, the risks and how they are handled, and what the review found. Drafting starts only after your yes, which the agent records in the unit's request record. A "go ahead" given before you saw the design does not count, and in a session with nobody to answer the unit waits for you.
-
-**The npm page tells you what is new.** This section, at the top of the package page, now summarizes each version for the people who install it.
-
-**From 1.32.0, published without notes:**
-- **You know what the knowledge base has not read yet.** It tells you how much of the project remains to be examined, and before answering "no information" it checks where the answer could be.
-- **What you told others stays a statement.** What you wrote to a client or a partner does not become a fact about the product. If it contradicts what the knowledge base holds, it is flagged.
-- **Decisions from other projects no longer apply by themselves.** Importing a topic from another project brings the knowledge whole, but the decisions taken there stay pending until one of you approves them.
-- **The process checks can no longer be bypassed by accident.** Quoting a work level inside a sentence no longer counts as declaring it, and protected parts of the project stay protected when the agent changes folder.
+**Decisions taken on your behalf are labelled.** In the request record, a decision a session took under a delegation you gave it, and words you gave one session for work another session records, now carry their own heading. They are never read later as something you said yourself, and a delegated decision never overrides one of yours: a choice that would change it comes back to you as a question.
 
 #### What to do
 
@@ -24,24 +16,7 @@ The sibling of [`@antoneeo/agentic-sdlc-skill`](https://www.npmjs.com/package/@a
 1. Run `npm install -g @antoneeo/kb-agentic-skill@latest`, then `kb-agentic-install-skill`.
 2. Close and reopen your agent sessions: the new version loads only at startup.
 
-To check: `npm ls -g @antoneeo/kb-agentic-skill` shows 1.33.0.
-
-**2. Approving the design (significant units).**
-- **This concerns you if** you use the skill for significant (L3) work. Nothing to configure: after the design review passes, the agent asks whether to proceed. Answer yes to start the drafting, or say what to change; the design is then revised and, where the change touches what the review judged, reviewed again before you are asked again.
-- **A unit already in progress.** Units started before 2026-10-31 are not affected. If a unit started on or after 2026-10-31 with an earlier version is already in progress or finished, `sdlc_check.py validate` shows a `[note]` saying it has `no design approval in its request record`. Why: the earlier version never asked you. To clear it, tell the agent that you approve the design as it was implemented; it records your words under a label that begins `design approved` (for example `design approved after implementation`). The note never fails a check, so you can also leave it.
-- **To check:** on your next significant unit, the agent stops after the design review and asks you before any drafting starts.
-
-**3. Decisions imported from another project (only if you used `import` before 1.32.0).**
-- **This concerns you if** you used the knowledge base's `import` command to bring topics from another project with version 1.31.0 or earlier. If you never did, skip this point.
-- **Why:** the knowledge base leaves open the questions on which sources disagree, and only a reasoned decision of yours closes them. The earlier version brought another project's decisions in already in force. For example, if someone in project A had settled "the right price is 49 €", importing into B made that price the truth in B too, without anyone in B deciding it. The update corrects future imports only; past ones stay as they are.
-- **Steps:** the simplest way is to ask the agent: "convert the imported decisions as described in portability.md §4". Or by hand: delete the imported topic together with the files that came with it, then run `import` again on the same bundle with the new version; you can try it first with `--dry-run`.
-- **To check:** `sdlc_check.py check` is clean; the other project's decisions appear as imported, and the questions they closed are open again. To make one yours, write your own decision with your own reasoning.
-
-**4. Protected folders in a repository with several `ai_docs/` (only if you use them; from 1.32.0).**
-- **This concerns you if** your agent settings contain `gate --hook --protected` and the repository has more than one `ai_docs/` folder, for example a package with its own.
-- **Why:** protected paths are now read from the `ai_docs/` nearest to the edited file. A path written from the repository root, such as `packages/api/src/auth`, no longer matches the files inside `packages/api`, so the agent could change them without an analysis.
-- **Steps:** rewrite those paths from the package: `packages/api/src/auth` becomes `src/auth`. Note that `src/auth` then protects the folder with that name in every project that has its own `ai_docs/`.
-- **To check:** in a session with no open analysis, ask the agent for a small change to a protected file. It must be refused.
+To check: `npm ls -g @antoneeo/kb-agentic-skill` shows 1.34.0.
 
 Full history: [CHANGELOG](https://github.com/Antoneeo/agentic-sdlc-skill/blob/main/distributions/kb-agentic-skill/CHANGELOG.md)
 <!-- whats-new:end -->

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "kb-agentic-skill",
-  "version": "1.33.0",
+  "version": "1.34.0",
   "description": "Knowledge-Base & Document-First protocol with risk triage, Vision governance, signal distillation and optional devPNT integration.",
   "author": "Antonio Pinto (https://github.com/Antoneeo)"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antoneeo/kb-agentic-skill",
-  "version": "1.33.0",
+  "version": "1.34.0",
   "description": "Knowledge-Base & Document-First protocol for Claude Code, Gemini CLI, Google Antigravity and Codex with risk triage, Vision governance, signal distillation and optional devPNT integration.",
   "keywords": [
     "claude-code",

package/scripts/init.js

@@ -196,16 +196,16 @@ in the skill's \`routing.md\`: it decides which lens's method and validation rul
 that unit. L1 never reaches it. Never refer to a document whose meaning differs by lens
 ("threat model", "vision", \`principles.md\`, \`handoff.md\`) by its bare name.
 
-Select the owning lens by the unit's purpose, then apply only its risk scale.
-The project's always-on pointer stays intact: consult the selected skill rather than
-merging multiple mandatory ladders. All lenses already carry shared project memory
-(\`memory.md\`); another installation is not needed for cross-domain recall.
+Select the owning lens by the unit's purpose, then apply only its risk scale.
+The project's always-on pointer stays intact: consult the selected skill rather than
+merging multiple mandatory ladders. All lenses already carry shared project memory
+(\`memory.md\`); another installation is not needed for cross-domain recall.
 This file is NOT auto-loaded by any client: it is a note for you, deliberately additive.
-Delete this note once the routing pointer is integrated.
+Delete this note once the routing pointer is integrated.
 `, 'multi-lens routing note');
   if (wrote && protocolPreexisting) {
     console.log('   ⚠️  A protocol pointer already existed and was NOT overwritten.');
-    console.log('       Integrate the routing pointer from AGENTIC_MULTI_LENS.md; keep one risk scale per unit.');
+    console.log('       Integrate the routing pointer from AGENTIC_MULTI_LENS.md; keep one risk scale per unit.');
   }
 }
 

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

@@ -1,6 +1,6 @@
 ---
 name: kb-agentic
-version: 1.33.0
+version: 1.34.0
 description: Knowledge-Base & Document-First protocol with risk-proportional triage, Vision as a guide, Signal Distillation, a complete Standalone mode and optional symbiosis with devPNT. Use for user documentation, knowledge extraction, SOPs, research notes, decision logs, knowledge management — and for answering project questions from the claim ledger and topic graph.
 author: Antonio Pinto (https://github.com/Antoneeo)
 copyright: (c) 2026 Antonio Pinto

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

@@ -89,7 +89,9 @@ intent choice with neither a source nor a weighing is a finding (`review.md`
 - **Unattended** — the practitioner is not reachable (the Unattended path above).
 - **Delegated** — their own words handed you this choice; cite their entry in the
   request record, or quote them where the unit has none (below L3). A general
-  "go ahead" is not a delegation.
+  "go ahead" is not a delegation. A choice you make under it goes, where the
+  unit has a request record, into it as a delegated entry (`templates.md` §REQUEST) and the artifact
+  cites that entry; it never changes an earlier decision of theirs — ask instead.
 
 Each states **what it is taken from** and **the alternative it excludes**, and is
 listed where the practitioner will read it — an assumption nobody is shown is a

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

@@ -467,7 +467,9 @@ When you are the reviewer:
   the artifact relies on — an answer, an approval, a cost acceptance, a ruling, a
   delegation — that resolves to no entry of the unit's request record, or that the
   record contradicts, is a finding; so is a quotation in the record carrying what
-  its template says to redact. What makes a ground
+  its template says to redact, a delegated entry citing no delegation or changing
+  an earlier owner decision, and an artifact of a shared unit citing a received
+  entry instead of the shared record (`templates.md` §REQUEST, labelled entries). What makes a ground
   or an assumption legal is each lens's `elicitation.md` §The question discipline —
   cite it, never restate it. The fix is the question, not a better justification.
 - **Restated facts (cite, never copy).** Every governance slot has ONE owning document

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

@@ -289,6 +289,14 @@ Context (agent): "the question it answered, quoted"
   entered only as `[NOT VERBATIM — from <source>]`, never as a quote.
 - **Unattended**: R1 quotes the trigger that started the unit, labelled as such.
   Declared assumptions are not owner statements and never enter the record.
+- **Labelled entries** (r41): a decision taken under the owner's delegation is
+  `### R<n> — YYYY-MM-DD — decided under delegation R<m> — <what it settles>`, citing
+  the delegation entry (in Hybrid also the devPNT proposal it accepted); it is the
+  deciding session's choice, never an owner statement, and never changes an earlier
+  owner decision — that goes to the owner as a question. Owner words received for a
+  unit whose record another session writes are
+  `### R<n> — YYYY-MM-DD — received for <unit> — <what it settles>`, then sent to that
+  record's writer, who enters them verbatim citing this entry.
 - **Design approval** (L3): the owner's approval of the design is an entry whose
   label begins `design approved`; a no or a correction takes its own label
   (`review.md` §When a review is due).

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

@@ -1,308 +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 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.
+# 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.