@antoneeo/mkt-agentic-sdlc-skill 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [0.18.0] - 2026-10-17
+
+### Changed
+- F1: closing the last open workstream now empties the generated registry `audit/handoff.md` instead of leaving its stale row behind: with zero `HANDOFF_*.md` sources `index` rewrites it empty (keeping `project_notes.md`), and `validate` reports a generated registry that still has rows but no sources as an error.
+- F-069: `graph`, `check`, `stale` and the session-start count are faster on a mature knowledge base, with byte-identical output. Citations of superseded claim ids are found with one pass per living document instead of one scan per (document, id) pair, and one check run reads and resolves each cited extraction once instead of once per claim row. On a synthetic ledger of 2183 rows and 1000 living documents, `graph` drops from 14 s to 4 s. No new flag.
+
 ## [0.17.0] - 2026-10-13
 
 ### Changed

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "mkt-agentic-sdlc",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Evidence-First marketing planning protocol with engagement triage, SOSTAC workflow, evidence ledger and optional devPNT integration.",
   "author": "Antonio Pinto (https://github.com/Antoneeo)"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antoneeo/mkt-agentic-sdlc-skill",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Evidence-First marketing planning protocol for Claude Code, Gemini CLI, Google Antigravity and Codex: engagement triage, SOSTAC workflow, evidence ledger, mechanical validator and optional devPNT integration.",
   "keywords": [
     "claude-code",

package/scripts/init.js

@@ -194,16 +194,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/mkt-agentic-sdlc/ENFORCEMENT.md

@@ -14,17 +14,17 @@ python "<skill_dir>/scripts/mkt_check.py" check
 
 ## 2. Check in CI (recommended for teams)
 
-Copy all three validator files into the repository: `scripts/mkt_check.py`, `scripts/sdlc_core.py`, and `scripts/knowledge.py`, keeping them side by side. Then add to the pipeline:
+Copy all three validator files into the repository: `scripts/mkt_check.py`, `scripts/sdlc_core.py`, and `scripts/knowledge.py`, keeping them side by side. Then add to the pipeline:
 
 ```
 python tools/mkt_check.py validate --strict
 ```
 
-The validator ships as **three files**: the domain entry point, `sdlc_core.py` and `knowledge.py`. Keep all three together. The core alone still runs but omits shared-memory/KB checks and domain-specific overlays; it is not an equivalent CI gate. `check` includes the knowledge surface when present.
+The validator ships as **three files**: the domain entry point, `sdlc_core.py` and `knowledge.py`. Keep all three together. The core alone still runs but omits shared-memory/KB checks and domain-specific overlays; it is not an equivalent CI gate. `check` includes the knowledge surface when present.
 
 Effect: an unregenerated index, invalid frontmatter, a missing security section or incoherent states **block the pipeline** instead of relying on the agent's memory. `--strict` also fails on warnings and on a missing `ai_docs/`, so a wrong working directory cannot produce a green pipeline. This works because documents travel in the same PR as the code (Phase 5 rule).
 
-Note: the copy in the repo is the authoritative one for CI; update it when you update the skill — all three files, together.
+Note: the copy in the repo is the authoritative one for CI; update it when you update the skill — all three files, together.
 
 **Projects whose docs root is not `ai_docs/`.** Pass `--docs-dir <name>` (e.g. `--docs-dir mkt_docs`) on any subcommand, or set `AGENTIC_SDLC_DOCS_DIR`. Without either, the validator walks up from the working directory and takes the nearest root it recognizes. If it finds two side by side — the shape of a half-finished migration — it refuses and names both rather than validating half a project and printing a verdict. `ai_docs/` remains the default and the recommended root: the parameter exists so a legacy tree can be read and migrated, not so a second one can be kept.
 
@@ -155,7 +155,7 @@ Gemini CLI — wire the same command into its startup-hook mechanism if present;
 **Usage notes:**
 - The hook assumes the working directory is the project root (standard Claude Code hook behavior); it also accepts `--root <path>`.
 - **Hybrid/devPNT projects**: add `--hybrid` — the hook then appends a one-line pointer to run `devpnt_mcp_get_bootstrap` for the Master Plan / Knowledge Layer and does not replicate them; the filesystem orientation (router + handoff + README) still emits.
-- Like the CI gate (§2), if you copied the validator into the repo, the hook references that copy — keep all three files current when you update the skill.
+- Like the CI gate (§2), if you copied the validator into the repo, the hook references that copy — keep all three files current when you update the skill.
 
 ### Per-turn reminder: `remind` (UserPromptSubmit -- wired by default)
 
@@ -215,7 +215,7 @@ It aggregates the test files (`test_plan.py` + `test_session_start.py` + `test_s
 
 **Optional CI** (same shape as §2, not mandatory): add a `run:` step invoking the `unittest discover` command above.
 
-**T10 note:** if you copied the validator (all three files) and the `test_*.py` battery into the repo for CI, that copy is authoritative — keep it current when you update the skill.
+**T10 note:** if you copied the validator (all three files) and the `test_*.py` battery into the repo for CI, that copy is authoritative — keep it current when you update the skill.
 
 ## `benefit` is a report, never a CI gate
 

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

@@ -1,6 +1,6 @@
 ---
 name: mkt-agentic-sdlc
-version: 0.17.0
+version: 0.18.0
 description: Evidence-First marketing planning protocol with engagement triage, SOSTAC workflow, evidence ledger, adversarial CMO review, a complete Standalone mode and optional symbiosis with devPNT. Use for marketing plans, go-to-market strategy, campaign planning and market research.
 author: Antonio Pinto (https://github.com/Antoneeo)
 copyright: (c) 2026 Antonio Pinto

package/skills/mkt-agentic-sdlc/scripts/knowledge.py

@@ -336,6 +336,17 @@ def kb_check_claims(root):
         if rel not in fm_cache:
             fm_cache[rel] = _note_frontmatter(root, rel)
         return fm_cache[rel]
+    # F-069: the same per-run memo for the source paths themselves -- each
+    # distinct path is resolved and stat'ed once, and each cited extraction
+    # read once (loc_cache, owned here, dropped when this call returns).
+    src_cache = {}
+    loc_cache = {}
+
+    def _resolved(path_s):
+        if path_s not in src_cache:
+            t = sdlc_core.confine_under(root, path_s)
+            src_cache[path_s] = (t, t is not None and t.is_file())
+        return src_cache[path_s]
     per_file_rows = []
     for p in sorted(topics.glob("*.md")):
         rel = "topics/" + p.name
@@ -357,16 +368,16 @@ def kb_check_claims(root):
                     errors.append("%s: source %r has no locator" % (where, src))
                     continue
                 path_s, loc = src.rsplit("#", 1)
-                target = sdlc_core.confine_under(root, path_s)
+                target, is_file = _resolved(path_s)
                 if target is None:
                     errors.append("%s: source %r escapes the docs root" % (where, src))
                     continue
-                if not target.is_file():
+                if not is_file:
                     errors.append("%s: source %r does not resolve — a claim whose "
                                   "origin cannot be reopened is model knowledge"
                                   % (where, src))
                     continue
-                kb_check_locator(target, loc, where, errors)
+                kb_check_locator(target, loc, where, errors, loc_cache)
             # --- provenance ---
             prov = row["prov"]
             # Resolved ONCE, for every provenance: the non-GIVEN classes read it
@@ -556,8 +567,14 @@ def kb_check_claims(root):
     return errors, warnings, notes
 
 
-def kb_check_locator(target, loc, where, errors):
-    """A locator must address an existing span of the stored bytes."""
+def kb_check_locator(target, loc, where, errors, cache=None):
+    """A locator must address an existing span of the stored bytes.
+
+    `cache` is an optional dict the CALLER owns for one run (F-069): keyed by
+    the path actually read, it holds only what the checks compare against --
+    page lengths, a line count, or False for a missing extraction -- never the
+    text. Findings are still appended per call, so per row. Without it, every
+    call reads the file, as before."""
     m = LOC_PAGE_RE.match(loc)
     if m:
         page, a, b = int(m.group(1)), int(m.group(2)), int(m.group(3))
@@ -566,17 +583,24 @@ def kb_check_locator(target, loc, where, errors):
             return
         # offsets address the stored extraction (<stem>.txt beside the original)
         ext = target if target.suffix == ".txt" else target.with_suffix(".txt")
-        if not ext.is_file():
+        key = ("p", ext)
+        if cache is None or key not in cache:
+            lengths = ([len(pg) for pg in sdlc_core.read_text(ext).split("\f")]
+                       if ext.is_file() else False)
+            if cache is not None:
+                cache[key] = lengths
+        else:
+            lengths = cache[key]
+        if lengths is False:
             errors.append("%s: no stored extraction %s for locator %r — offsets "
                           "must address kept bytes" % (where, ext.name, loc))
             return
-        pages = sdlc_core.read_text(ext).split("\f")
-        if page < 1 or page > len(pages):
+        if page < 1 or page > len(lengths):
             errors.append("%s: locator %r addresses page %d of %d" %
-                          (where, loc, page, len(pages)))
-        elif b > len(pages[page - 1]):
+                          (where, loc, page, len(lengths)))
+        elif b > lengths[page - 1]:
             errors.append("%s: locator %r spans past the end of page %d "
-                          "(%d chars)" % (where, loc, page, len(pages[page - 1])))
+                          "(%d chars)" % (where, loc, page, lengths[page - 1]))
         return
     m = LOC_LINE_RE.match(loc)
     if m:
@@ -584,7 +608,13 @@ def kb_check_locator(target, loc, where, errors):
         if a > b or a < 1:
             errors.append("%s: locator %r has an invalid line range" % (where, loc))
             return
-        n = sdlc_core.read_text(target).count("\n") + 1
+        key = ("L", target)
+        if cache is None or key not in cache:
+            n = sdlc_core.read_text(target).count("\n") + 1
+            if cache is not None:
+                cache[key] = n
+        else:
+            n = cache[key]
         if b > n:
             errors.append("%s: locator %r spans past line %d" % (where, loc, n))
         return
@@ -1085,12 +1115,18 @@ KB_GENERATED_RE = re.compile(r"GENERATED by \S+ index - do not edit by hand")
 KB_HEX12_RE = re.compile(r"^[0-9a-f]{12}$")
 
 
-def _kb_hex_bounded(text, cid):
-    """True when cid appears NOT embedded in a longer hex run: a git hash
-    sharing a substring must never count as a citation (either side, either
-    case). cid is pre-validated 12-hex, so it is regex-safe by construction."""
-    return re.search(r"(?<![0-9a-fA-F])%s(?![0-9a-fA-F])" % cid,
-                     text) is not None
+# A citation of a claim id is a run of exactly its 12 lowercase hex characters
+# NOT embedded in a longer hex run: a git hash sharing a substring must never
+# count as a citation (either side, either case). Two such bounded runs cannot
+# overlap, so findall returns every one of them.
+KB_HEX_TOKEN_RE = re.compile(r"(?<![0-9a-fA-F])[0-9a-f]{12}(?![0-9a-fA-F])")
+
+
+def _kb_hex_tokens(text):
+    """The ids a text cites, extracted in one pass (F-069). Callers test
+    membership instead of scanning the text once per id: that per-(document,
+    id) scan made the time cycle grow with superseded ids x living documents."""
+    return frozenset(KB_HEX_TOKEN_RE.findall(text))
 
 
 def _kb_df_entries(value):
@@ -1172,19 +1208,23 @@ def kb_time_cycle(docs):
         if (meta.get("status") or "").strip() == "SUPERSEDED":
             continue
         living.append((rel, text))
-    for rel, text in living:
-        for old in sorted(superseded):
-            if _kb_hex_bounded(text, old):
-                succs = superseded[old]
-                missing = tuple(x for x in succs
-                                if not _kb_hex_bounded(text, x))
-                if missing:
-                    cited.append((rel, old, missing, succs))
+    # One token pass per living document, and none at all on a KB with no
+    # supersession and no validity window (the orient line runs this at every
+    # session start).
+    tokens = ({rel: _kb_hex_tokens(text) for rel, text in living}
+              if superseded or windows else {})
+    for rel, _text in living:
+        cites = tokens[rel] if tokens else frozenset()
+        for old in cites.intersection(superseded):
+            succs = superseded[old]
+            missing = tuple(x for x in succs if x not in cites)
+            if missing:
+                cited.append((rel, old, missing, succs))
     today = _dt.date.today().isoformat()
     for topic_rel, rid, until in sorted(windows):
         if until <= today:
-            by = tuple(rel for rel, text in living
-                       if rel != topic_rel and _kb_hex_bounded(text, rid))
+            by = tuple(rel for rel, _text in living
+                       if rel != topic_rel and rid in tokens[rel])
             expired.append((topic_rel, rid, until, by))
     rev = {}
     node_meta = {}

package/skills/mkt-agentic-sdlc/scripts/sdlc_core.py

@@ -834,6 +834,10 @@ def build_registry(root):
         return ""
     stamp = max(str(m.get("updated") or m.get("since") or "").strip() or "0000-00-00"
                 for _p, m in rows)
+    return _render_registry(root, rows, stamp)
+
+
+def _render_registry(root, rows, stamp):
     lines = ["# Handoff — workstream registry",
              f"Date: {stamp} (UTC)",
              "",
@@ -867,6 +871,35 @@ def parse_registry_rows(text):
     return ids
 
 
+def is_generated_registry(text):
+    # "Ours" = written by ANY family entry point: the header is WRITTEN with
+    # entry_script(), so recognition must not hard-code one distribution's
+    # script name (a registry generated by mkt_check.py is just as generated).
+    return bool(re.search(r"GENERATED by \S+ index - do not edit by hand", text))
+
+
+def generated_registry_rows(text):
+    """Workstream rows of a generated registry, ignoring the project notes
+    (free text that may carry tables of its own)."""
+    return parse_registry_rows(text.split("\n## Project-wide notes", 1)[0])
+
+
+def build_empty_registry(root, existing):
+    """The generated registry once the last source is gone (F1, found by F-068).
+
+    Only for a registry that is already ours: a hand-written handoff with no
+    sources is a project that never converted, and stays untouched. The Date is
+    kept while the view is already empty -- re-running index on a clean tree
+    must not change it -- and becomes today's when rows are being dropped:
+    there is no source left whose `updated:` could date the closure."""
+    m = re.search(r"Date:\s*(\d{4}-\d{2}-\d{2})", existing)
+    if m and not generated_registry_rows(existing):
+        stamp = m.group(1)
+    else:
+        stamp = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+    return _render_registry(root, [], stamp)
+
+
 def registry_conversion_blockers(root):
     """What stops `index` from writing over a hand-written handoff.md.
 
@@ -879,10 +912,7 @@ def registry_conversion_blockers(root):
     if not hand.is_file():
         return []
     text = read_text(hand)
-    # "Already ours" = written by ANY family entry point: the header is WRITTEN
-    # with entry_script(), so recognition must not hard-code one distribution's
-    # script name (a registry generated by mkt_check.py is just as generated).
-    if re.search(r"GENERATED by \S+ index - do not edit by hand", text):
+    if is_generated_registry(text):
         return []
     blockers = []
     known = {str(m.get("workstream")).strip() for _p, m in list_workstreams(root)}
@@ -1015,10 +1045,21 @@ def cmd_index(root):
 def rc_registry(root):
     """Write the generated workstream registry, or refuse and say why (F-028)."""
     ws = list_workstreams(root)
+    hand = ai_path(root, "audit", "handoff.md")
     if not ws:
-        return 0                # no sources: a hand-written handoff is untouched
+        # No sources: a hand-written handoff is untouched; a generated one is
+        # emptied, or the last closed workstream would stay listed forever.
+        if not hand.is_file():
+            return 0
+        existing = read_text(hand)
+        if not is_generated_registry(existing):
+            return 0
+        empty = build_empty_registry(root, existing)
+        if norm_text(existing) != norm_text(empty):
+            hand.write_text(empty, encoding="utf-8")
+            print(f"[ok] workstream registry emptied (no open workstreams): {hand}")
+        return 0
     blockers = registry_conversion_blockers(root)
-    hand = ai_path(root, "audit", "handoff.md")
     if blockers:
         print(f"[ERROR] {docs_dir()}/audit/handoff.md NOT regenerated -- it still holds "
               "state no source accounts for:")
@@ -1496,6 +1537,12 @@ def cmd_validate(root, strict=False, hybrid=False):
                                 "workstream — decide which file owns it")
             else:
                 seen[wid] = p.name
+    elif hand.is_file():
+        text = read_text(hand)
+        if is_generated_registry(text) and generated_registry_rows(text):
+            errors.append(f"{docs_dir()}/audit/handoff.md lists workstreams no HANDOFF_*.md "
+                          "source exists for any more: run 'sdlc_check.py index' to drop "
+                          "the closed rows")
     if hand.is_file():
         m = re.search(r"(?:Date|Data):\s*(\d{4}-\d{2}-\d{2})", read_text(hand))
         if not m:

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

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