@antoneeo/agentic-sdlc-skill 1.20.2 → 1.21.0

package/CHANGELOG.md

@@ -2,6 +2,259 @@
 
 Tutte le modifiche significative a questa skill saranno documentate in questo file.
 
+## [1.21.0 / kb 1.4.0 / mkt 0.4.0] - 2026-08-03
+
+F-028 — several people on one project. `templates.md` had claimed the workstream
+registry was "Parallel-safe by construction" since F-019, and nothing had ever exercised
+it. Two workstreams opened from one base conflict **twice in one file**: on the row
+insert, and on the file-global `Date:` header. Row-level ownership cannot save a file
+that has a file-level field.
+
+### Changed
+- **`audit/handoff.md` is now GENERATED** from one `HANDOFF_[unit].md` per open
+  workstream, whose frontmatter IS the row. Two writers on two workstreams touch two
+  different files, and the `Date:` header is derived — from the newest `updated:` VALUE
+  in the sources, never a filesystem timestamp (git does not preserve mtimes, and an
+  mtime-derived header would make the file regenerate differently in every fresh clone).
+- **`HANDOFF_[unit].md` is now written for every OPEN workstream**, with or without
+  volatile state — no file, no row. It still carries the resume logistics, and deleting
+  it at closure *is* what removes the row. The DRY boundary against the ANALYSIS Diary
+  is restated in the template, because what used to keep narrative out of that file was
+  its rarity, and the rarity is gone.
+- Project-wide notes move to their own source, `audit/project_notes.md`, so generating
+  the registry cannot destroy notes that belong to no workstream.
+
+### Added
+- **`validate` errors when the registry disagrees with its sources** — which is what
+  turns a merge resolved carelessly from permanent into loud. Resolution is mechanical:
+  re-run `index`. The generated view can still conflict; the authored truth does not.
+- **`index` refuses to write while anything in the file is unaccounted for**, and names
+  it. Converting one row at a time is the state that loses the others, so conversion is
+  per project. A project with no sources is untouched and sees no new finding.
+- **`init` writes a `.gitattributes` stanza** giving the append-only review log
+  `merge=union` — a **built-in** driver, unlike `merge=ours`, which silently does
+  nothing until every clone runs `git config` and leaves the file wrong even then.
+  Create-only; a user's own `.gitattributes` is never clobbered.
+- `scripts/test_merge_safety.py` (shared, ×3): the experiment that found the defect,
+  kept as a regression test — two workstreams from one base, merged, with the assertion
+  that only the generated view may conflict and that regenerating loses no state. Plus
+  the mixed-state, fresh-mtime, ordering, cap and duplicate-id guards, each
+  mutation-verified.
+- A warning when two files claim the same workstream: the collision this design does
+  **not** fix (two people opening the same work under two names) must not pass as two
+  ordinary rows.
+
+The mechanism is files and a generator: **it works with no VCS at all.** The
+`.gitattributes` stanza is defence in depth — without it the outcome is today's, one
+conflict resolved by hand, never a lost row.
+
+### Upgrading
+Nothing happens until you convert: with no `HANDOFF_*.md` sources, `index` and
+`validate` behave exactly as before. When you convert, convert the whole registry at
+once — `index` will tell you what is still unaccounted for.
+
+## [kb 1.3.0] - 2026-08-03
+
+F-031 — from the field: *"the ingestion agent takes shortcuts, and a lot of information
+is lost. The graph works only if all of a file's information is poured into it."* An
+agent handed a 200-page manual emitted a few dozen claims and reported done. Nothing it
+did broke a rule — and that is the finding. `distillation.md` carried a floor ("the
+extractor invents nothing") and no target, so an agent optimizing against it stops the
+moment nothing it wrote is false. **Nothing the field agent emitted was wrong.** Third
+appearance of one class: a rule that describes a good output and never says which
+outputs must exist.
+
+### Added
+- **A north star at the top of `distillation.md`**, above the rules rather than beside
+  them: *not one assertion the source makes may be lost, and not one it does not make
+  may appear.* One sentence, deliberately — two rules a paragraph apart get optimized
+  whichever was read last. The unit is the **assertion**, not the byte: layout and page
+  furniture are not assertions, exhaustive means **read** and never *a row per page*.
+- **`extracted_through:`** on the artifact's own sidecar (`p=<n>`, `L<n>`, `complete`) —
+  required once any claim cites it. It is what makes "I am finished" falsifiable, and it
+  makes the rows and the field check each other: claims with no coverage recorded error;
+  a claim addressing past the declared coverage, or coverage past the end of the stored
+  bytes, is a contradiction and errors; coverage short of the end warns, because partial
+  work is legal mid-ingestion. An artifact nobody has extracted from owes nothing.
+- **Bounded reading windows** — 30 pages by default, *the plan states the window used*
+  (a hard number baked into doctrine ages badly across models and page densities). One
+  plan task per window: the existing `PLAN_[topic].md` ledger is the register an
+  ingestion resumes from across sessions, so **no second register was built** — one
+  would have been the work board this method refuses.
+- **A coverage cell in `corpus/INDEX.md`**, printed for **every** artifact including the
+  finished ones. A list of only what is behind is the dashboard the Vision rejects, and
+  a test fails the suite if the report ever becomes one.
+- Cold-run scenario `long_source_is_exhausted_not_sampled.md`: sampling a long source and
+  reporting it ingested is the FAIL — and so is manufacturing a row per page.
+
+The limit is stated wherever the field is written, as with `original_sha256`: **nothing
+proves a page was read.** A field advanced without extracting is invisible to any
+checker, precisely because a page that asserts nothing legitimately yields no rows — that
+direction belongs to the ingestion review. What changed is that the shortcut must now be
+written down to pass, and a written claim can be reopened by anyone who cares to.
+
+### Upgrading an existing corpus
+`check` will error on every `corpus/given/` artifact that has claims and no
+`extracted_through:`. That is the migration, and it is the point: state how far each
+source was actually read (`complete` if it was finished). The message names the artifact,
+the first row citing it, and the three accepted forms. `corpus/INDEX.md` gains the
+coverage cell, so run `sdlc_check.py index` once — until then `validate` reports it
+out of alignment, as it does for any generated index.
+
+## [kb 1.2.0] - 2026-08-03
+
+F-030 — knowledge built in one project could not leave it. A practitioner who grounded
+82 claims against a vendor's manuals started the next project with nothing and paid the
+whole ingestion again from the same sources. The Core Problem this methodology exists
+against is that understanding evaporates; it was evaporating at the **project boundary**.
+
+### Added
+- **`export --out <dir>`** bundles a subgraph together with **the bytes its claims
+  cite** — a closure, not a selection. A claim whose source cannot be reopened is model
+  knowledge arriving by another route, so the artifacts, sidecars and extractions travel
+  with it. The closure also pulls in the other half of any `CONTESTED` set, because the
+  symmetry check refuses a set that lost members — and says which topics it added, never
+  silently.
+- **`import <dir>`** merges a bundle **additively**: never overwrites a node, never
+  deletes, and computes the whole plan before writing a byte (an import that half-applies
+  leaves a tree whose checks fail and whose owner cannot tell what landed). Refuses on a
+  path escaping the docs root, an artifact whose name matches an existing one with
+  different bytes, a directory carrying no `MANIFEST.md`, and a broken conflict set.
+  Placing an incoming concept stays the placement pass's job (`taxonomy.md`) — the import
+  reports the skipped node and decides nothing.
+- **`prov: IMPORTED`** (owner ruling, 2026-08-03). Knowledge crosses a project boundary;
+  authority does not. A ruling from another project keeps its text, span and original
+  `basis:` verbatim, must declare `imported_from:`, and **cannot supersede a local row**
+  — the validator errors on it. Re-ratification is one honest act: your own note, your
+  own basis, `prov: RULING`. Relabelling it `DERIVED` was rejected because the row would
+  then lie about where it came from.
+- **`portability.md`**, the doctrine the two commands cite.
+
+The feature is small because of one property it did not have to build: `kb_claim_id`
+hashes `path#locator#qty` with the **text excluded**, so the same artifact cited at the
+same span mints the same id in every project. Cross-project de-duplication is therefore
+mechanical rather than a judgement call, and importing the same bundle twice is a
+provable no-op.
+
+## [kb 1.1.1] - 2026-08-03
+
+Three inconsistencies the same field practitioner found by reading 1.1.0 against
+their own corpus — all of the class 1.1.0 exists to remove: the doctrine and the
+machinery disagreeing, where an agent reads one and the checker obeys the other.
+
+### Fixed
+- **`SKILL.md` never named `anchor`.** The command shipped working and listed in
+  `--help`, while the support-file line still said "the knowledge overlay: `graph`,
+  `corpus`, `claim-id`" — so an agent reading only the doctrine never learned it
+  exists, which is how the practitioner found it (from the prose, by accident). New
+  kb invariant derives the expected list from `INTERCEPTED` and fails when SKILL.md
+  omits any of it; deriving is the point, a second hand-maintained list would be the
+  same defect again.
+- **Two rules gave opposite outcomes on a binary corpus.** The Write Triggers row for
+  `corpus/given/*` still read "verbatim copy … non-text originals **also** get their
+  stored canonical extraction", contradicting the extraction-as-artifact rule added to
+  `distillation.md` §1 in 1.1.0. The row now states both forms and names §1 as the
+  owner of the rule.
+- **`anchor` only worked from inside the docs root**, an asymmetry with `graph`,
+  `corpus` and `check`, which take `--root`. Those scan a tree and this one takes a
+  path, so the fix is to make the path resolve rather than to document where to stand:
+  a path that does not resolve from the current directory is retried under the docs
+  root, which means it can be given exactly as a claim's `source` cell carries it.
+
+## [kb 1.1.0] - 2026-08-03
+
+Scoped to `@antoneeo/kb-agentic-skill`. `agentic-sdlc-skill` (1.20.3) and
+`mkt-agentic-sdlc` (0.3.1) are unchanged in what they ship: the shared invariant
+added here lives in `test_skill_invariants.py`, which no distribution packages.
+
+F-029 — six defects from the first full field application of `kb-agentic` by a
+practitioner other than its author (233 MB of manuals, 51 corpus artifacts, 22 topic
+nodes, 82 offset-verified claims). **None was an adherence failure**: in every one the
+agent did what it was told and was wrong anyway, which makes them agent-UX defects.
+Analysis: `ai_docs/solutions/ANALYSIS_kb_field_report.md`.
+
+### Fixed
+- **kb's triage levels were undecidable.** L1 and L2 carried the *identical* bound
+  ("at most 1-2 files"), so no request could be classified L2 and anything touching
+  three files fell to L3 by "when in doubt, go higher". Root cause: kb never performed
+  the restatement the Vision requires of every sibling — the file counts were the code
+  lens's units, and they contradicted the escalation triggers two lines below them.
+  Restated in knowledge units by owner ruling (2026-08-02): one claim row → propagation
+  of an already-settled fact → a new knowledge unit. The one limit: propagation that
+  changes what a claim *asserts* is not propagation. New shared invariant asserts no two
+  graded levels state the same criteria, lens-agnostically (`L1..L3` here, `E1..E3` in
+  marketing) — mutation-tested RED before the fix.
+- **The claim model recorded powers and skipped gates**, making every ledger
+  systematically optimistic on a corpus whose purpose is to deflate over-promising. A
+  query returned three verified rows saying "yes, supported" while omitting that the
+  feature ships disabled and needs a second construct — true, and a plan that fails on
+  site. `distillation.md` §3 now requires the gates alongside the powers, with the guard
+  that keeps it from becoming fabrication: the rule is *ask*, never *produce*.
+- **`--help` hid the knowledge overlay.** Forward-by-default handed `--help` to the
+  spine, whose usage lists nine commands and none of kb's, so a user concluded the
+  overlay was not installed. Intercepted at `argv[0]` only, and the spine's own usage is
+  still rendered — forward-by-default is intact, with a regression test that proves a
+  non-intercepted command still reaches the spine.
+- **kb's eval battery tested the wrong skill.** Six scenarios, none covering kb's own
+  method, two byte-identical to the code lens's and exercising an architect pass kb does
+  not ship — while extraction, placement, reconciliation, the corpus letter and locators
+  had no cold-run coverage at all. Rewritten in kb's units, three new scenarios added,
+  and a new invariant refuses any scenario citing a support file its distribution lacks.
+  The ANALYSIS template's example rows were the code lens's verbatim (Python paths in a
+  knowledge template); replaced with topic-graph rows.
+
+### Added
+- **`sdlc_check.py anchor <path> <phrase>`** — the half `claim-id` never had: it turns a
+  prose citation into a *verified* span. The check has always demanded resolved locators
+  and nothing produced them, so every one was hand-authored against a machine verifier.
+  Whitespace in the phrase matches as `\s+`, because a PDF extraction breaks phrases
+  mid-line and a probe that pretty-prints collapsed whitespace shows the phrase intact
+  while the checker sees the break. Refuses ambiguity and refuses what it cannot anchor,
+  and re-verifies every locator with `kb_check_locator` before emitting it — the tool can
+  never produce a span its own validator would reject.
+- **Extraction-as-artifact** for large binary corpora (`distillation.md` §1): the stored
+  extraction may be the corpus artifact on its own, `sha256:` covering it, with the
+  original recorded as `original_path:` + `original_sha256:` instead of copied in. The
+  code already allowed this; the doctrine said the extraction came "additionally", so a
+  faithful reader copied gigabytes for nothing. The recorded fields state their limit
+  where they are defined: `original_sha256` is never checked.
+
+## [1.20.3] - 2026-08-02
+
+Three defects found by a field test in which cold agents operated the three published
+skills on real fixtures — a brownfield API, three infrastructure documents, a business
+brief. None of them had been found by any static pass.
+
+### Fixed
+- **The multi-lens routing note named the wrong lens** (shipped in kb 1.0.0 and mkt
+  0.3.0; invisible in the code package, where the literal happened to be right). The row
+  for the CURRENT lens was hardcoded as `` `agentic-sdlc` — the **code** lens `` and
+  copied verbatim into every distribution, so a kb project listed the code lens twice
+  and never named kb. Both the self row AND the sibling table are now derived from the
+  `routing.md` lens table — the same authoritative, drift-guarded file the domain router
+  reads — so no lens word is restated by hand anywhere. The lookup is lazy: `preuninstall`
+  keeps working on an installation that lost `routing.md`, a duplicate row is refused
+  instead of silently winning, and a missing row throws.
+- **`FACT` was the way past the URL rule** (marketing lens). `BENCHMARK` owes a source
+  URL and `ASSUMPTION` a range, but `FACT` — "user input or primary data" — owed nothing,
+  so a researched observation classed FACT with source "see research/VOC.md" entered the
+  ledger unsourced. `mkt_check.py` now errors on a FACT with no source, or one pointing at
+  a document of the engagement, while exempting a cell that names the client as origin
+  (their own primary data may well be a file they handed over). `research.md` states the
+  two legal origins.
+- **A review verdict could be delivered nowhere.** `review.md` (all three copies) now says
+  the verdict travels as the reviewer's final output, and says it on both sides — the
+  requester's and the reviewer's. A reviewer that messages the requester mid-run depends
+  on a channel it cannot verify and which fails silently; a requester waiting for that
+  message stalls holding a verdict that already exists.
+
+### Changed
+- The guarding test for the routing note asserted that it named the detected SIBLING,
+  never itself — which is why the bug shipped. It now asserts this lens is named, with
+  its own lens word and no duplicates, and is mutation-tested against the original
+  defect. `A_SIBLING` is derived from the lens table rather than parsed out of the file
+  under test.
+
 ## [1.20.2] - 2026-08-01
 
 ### Fixed

package/README.md

@@ -9,6 +9,7 @@
 - **Architect pass — capabilities before files**: at L3, before listing what changes, the feature is stated as the *capabilities* it needs and each is ruled against the platform (EXISTS / INADEQUATE / MISSING); what is missing is designed as a component with its own contract, of which the feature is one consumer — never inlined into the feature's code path. A `## Component Map` in `strategic/architecture.md` is the durable inventory the pass reads, so the platform is not re-derived from source every session. On a codebase the methodology arrives in late, the map's silence is treated as **unread, not empty**: it can never ground a MISSING verdict.
 - **Execution disciplines**: explicit TDD (RED/GREEN/REFACTOR), systematic debugging, an L3 spec-elicitation round, and a single code-review definition wired into the workflow phases.
 - **Operative + comprehension guides + agent-global KB**: distil user-provided indications into source-faithful operative `GUIDE_*.md` (`source_kind: document`), and let the agent autonomously author **code-comprehension guides** (`source_kind: code`) for complex components — a source-faithful mental-model map that survives across sessions, so the next session doesn't re-derive and break the component from partial understanding. Consulted before work; shared cross-project via `~/.agentic-sdlc`.
+- **Several people, one project**: the workstream registry (`audit/handoff.md`) is **generated** from one file per open workstream, so two people opening or closing two workstreams on two branches edit two different files and their merge is clean. Row-per-workstream alone was not enough — a file-global `Date:` header defeats row-level ownership — so the header is derived from the sources and no writer touches it. The generated view can still conflict; that conflict is resolved by re-running `index`, never by hand, and `validate` refuses CLEAN until the file matches its sources. The append-only review log gets `merge=union` (a built-in driver, no per-clone configuration). It all works with no VCS at all: it is files and a generator.
 - **Opt-in subagent execution**: an approved design projects into a validated executable plan an orchestrator can drive through subagents.
 - **Self-activating**: a SessionStart hook emits repo-sourced orientation; a deterministic self-eval battery guards the skill's own doctrine as the release gate.
 - **Standalone complete**: works fully with local `ai_docs/` without requiring devPNT.

package/gemini-extension.json

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

package/package.json

@@ -1,50 +1,50 @@
-{
-  "name": "@antoneeo/agentic-sdlc-skill",
-  "version": "1.20.2",
-  "description": "Documentation-First SDLC protocol for Claude Code, Gemini CLI, Google Antigravity and Codex with risk triage, Vision governance, installed support files and optional devPNT integration.",
-  "keywords": [
-    "claude-code",
-    "claude-skill",
-    "gemini-cli",
-    "skill",
-    "sdlc",
-    "documentation",
-    "ai-agent"
-  ],
-  "author": "Antonio Pinto (https://github.com/Antoneeo)",
-  "license": "MIT",
-  "publishConfig": {
-    "access": "public"
-  },
-  "bin": {
-    "agentic-sdlc-init": "scripts/init.js",
-    "agentic-sdlc-install-skill": "scripts/postinstall.js"
-  },
-  "scripts": {
-    "postinstall": "node scripts/postinstall.js",
-    "preuninstall": "node scripts/preuninstall.js"
-  },
-  "files": [
-    "skills/agentic-sdlc-skill/SKILL.md",
-    "skills/agentic-sdlc-skill/templates.md",
-    "skills/agentic-sdlc-skill/architect.md",
-    "skills/agentic-sdlc-skill/guides.md",
-    "skills/agentic-sdlc-skill/vision.md",
-    "skills/agentic-sdlc-skill/tdd.md",
-    "skills/agentic-sdlc-skill/debugging.md",
-    "skills/agentic-sdlc-skill/elicitation.md",
-    "skills/agentic-sdlc-skill/review.md",
-    "skills/agentic-sdlc-skill/dispatch.md",
-    "skills/agentic-sdlc-skill/routing.md",
-    "skills/agentic-sdlc-skill/ENFORCEMENT.md",
-    "skills/agentic-sdlc-skill/scripts/sdlc_check.py",
-    "skills/agentic-sdlc-skill/scripts/sdlc_core.py",
-    "gemini-extension.json",
-    "README.md",
-    "CHANGELOG.md",
-    "scripts/lib.js",
-    "scripts/init.js",
-    "scripts/postinstall.js",
-    "scripts/preuninstall.js"
-  ]
-}
+{
+  "name": "@antoneeo/agentic-sdlc-skill",
+  "version": "1.21.0",
+  "description": "Documentation-First SDLC protocol for Claude Code, Gemini CLI, Google Antigravity and Codex with risk triage, Vision governance, installed support files and optional devPNT integration.",
+  "keywords": [
+    "claude-code",
+    "claude-skill",
+    "gemini-cli",
+    "skill",
+    "sdlc",
+    "documentation",
+    "ai-agent"
+  ],
+  "author": "Antonio Pinto (https://github.com/Antoneeo)",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "agentic-sdlc-init": "scripts/init.js",
+    "agentic-sdlc-install-skill": "scripts/postinstall.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js",
+    "preuninstall": "node scripts/preuninstall.js"
+  },
+  "files": [
+    "skills/agentic-sdlc-skill/SKILL.md",
+    "skills/agentic-sdlc-skill/templates.md",
+    "skills/agentic-sdlc-skill/architect.md",
+    "skills/agentic-sdlc-skill/guides.md",
+    "skills/agentic-sdlc-skill/vision.md",
+    "skills/agentic-sdlc-skill/tdd.md",
+    "skills/agentic-sdlc-skill/debugging.md",
+    "skills/agentic-sdlc-skill/elicitation.md",
+    "skills/agentic-sdlc-skill/review.md",
+    "skills/agentic-sdlc-skill/dispatch.md",
+    "skills/agentic-sdlc-skill/routing.md",
+    "skills/agentic-sdlc-skill/ENFORCEMENT.md",
+    "skills/agentic-sdlc-skill/scripts/sdlc_check.py",
+    "skills/agentic-sdlc-skill/scripts/sdlc_core.py",
+    "gemini-extension.json",
+    "README.md",
+    "CHANGELOG.md",
+    "scripts/lib.js",
+    "scripts/init.js",
+    "scripts/postinstall.js",
+    "scripts/preuninstall.js"
+  ]
+}

package/scripts/init.js

@@ -3,14 +3,7 @@
 const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
-const { SKILL_SOURCE, CLIENTS, clientDetected, skillTarget, loadTemplates, templateFor } = require('./lib');
-
-// Sibling lenses of the same family: one shared core, one `ai_docs/` tree, a different
-// fidelity discipline each. Keyed by the installed skill directory name.
-const SIBLING_LENSES = {
-  'kb-agentic': 'knowledge',
-  'mkt-agentic-sdlc': 'marketing',
-};
+const { SKILL_SOURCE, INSTALLED_SKILL_NAME, SELF_LENS, SIBLING_LENSES, CLIENTS, clientDetected, skillTarget, loadTemplates, templateFor } = require('./lib');
 
 const cwd = process.cwd();
 
@@ -119,6 +112,34 @@ const writeIfNotExists = (relPath, content, description) => {
 
 seedFiles.forEach(([relPath, content]) => writeIfNotExists(relPath, content));
 
+const EOL = String.fromCharCode(10);
+// 5b. Merge hygiene for the append-only review log (F-028, defence in depth).
+// `merge=union` is a BUILT-IN driver: no per-clone `git config`, unlike
+// `merge=ours`, which silently does nothing until every clone configures it.
+// Rows are date-stamped, so interleaving them loses no information and their
+// order carries none. Create-only, and appended rather than rewritten: a user's
+// own .gitattributes is never clobbered.
+const gitattributes = () => {
+  const marker = 'ai_docs/audit/reviews/REVIEW_LOG.md';
+  const stanza = [
+    '',
+    '# agentic-sdlc: the review log is append-only and its rows are date-stamped,',
+    '# so a union merge keeps both sides instead of asking a human to pick one.',
+    marker + ' merge=union',
+    '',
+  ].join(EOL);
+  const filePath = path.join(cwd, '.gitattributes');
+  if (!fs.existsSync(path.join(cwd, '.git'))) return;   // not a git repo: nothing to do
+  const current = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
+  if (current.includes(marker)) {
+    console.log('SKIP  .gitattributes already covers the review log.');
+    return;
+  }
+  fs.writeFileSync(filePath, current + stanza, 'utf8');
+  console.log('OK    .gitattributes: review log set to merge=union (concurrent reviews merge cleanly).');
+};
+gitattributes();
+
 // 6. Client discovery and protocol pointers
 console.log('\n--- Environment Analysis ---');
 
@@ -168,7 +189,7 @@ if (siblings.size > 0) {
 This project has more than one lens of the Agentic SDLC family installed:
 
 ${list}
-- \`agentic-sdlc\` — the **code** lens
+- \`${INSTALLED_SKILL_NAME}\` — the **${SELF_LENS}** lens
 
 One \`ai_docs/\` tree, one project default (\`default_domain:\` in \`ai_docs/README.md\`),
 one lens per unit of work. Before acting on any L2, L3 or Spike, run the domain router
@@ -196,7 +217,7 @@ Delete it once the merge is done.
 `, 'multi-lens routing note');
   if (wrote && protocolPreexisting) {
     console.log('   ⚠️  A protocol pointer already existed and was NOT overwritten.');
-    console.log('       Merge the code-lens ladder from AGENTIC_MULTI_LENS.md into it by hand.');
+    console.log(`       Merge the ${SELF_LENS}-lens ladder from AGENTIC_MULTI_LENS.md into it by hand.`);
   }
 }