@antoneeo/agentic-sdlc-skill 1.19.0 → 1.20.2

package/scripts/lib.js

@@ -1,168 +1,177 @@
-// Shared helpers for the Agentic SDLC npm scripts (init / postinstall / preuninstall).
-// Single source for client detection and skill-target paths: init and postinstall
-// must never disagree on what "Claude Code is installed" means.
-
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-const { execSync } = require('child_process');
-
-const PACKAGE_ROOT = path.resolve(__dirname, '..');
-const SKILL_SOURCE = path.join(PACKAGE_ROOT, 'skills', 'agentic-sdlc-skill');
-const TEMPLATES_PATH = path.join(SKILL_SOURCE, 'templates.md');
-
-// One entry per supported AI client. `home` may be overridden by an env var
-// (Claude Desktop / portable installs); presence of the home dir counts as
-// detection even when the CLI is not on PATH.
-const CLIENTS = [
-  {
-    key: 'claude',
-    label: 'Claude Code',
-    cmd: 'claude',
-    home: process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude'),
-    envVar: 'CLAUDE_CONFIG_DIR',
-    reload: 'Restart Claude Code to load it. Invoke via Skill tool as "agentic-sdlc".',
-  },
-  {
-    key: 'gemini',
-    label: 'Gemini CLI',
-    cmd: 'gemini',
-    home: process.env.GEMINI_HOME || path.join(os.homedir(), '.gemini'),
-    envVar: 'GEMINI_HOME',
-    reload: 'Run "gemini skills reload" or restart Gemini CLI to load it.',
-  },
-  {
-    key: 'codex',
-    label: 'Codex AI',
-    cmd: 'codex',
-    home: process.env.CODEX_HOME || path.join(os.homedir(), '.codex'),
-    envVar: 'CODEX_HOME',
-    reload: 'Restart Codex to load it. Invoke it as "$agentic-sdlc" or by asking for Agentic SDLC.',
-  },
-  {
-    // Google Antigravity 2.0 discovers global agent skills under
-    // ~/.gemini/config/skills/ -- the SAME home the legacy Gemini CLI claims.
-    // To avoid a shared-home double-install (P-TM T1), this entry sets:
-    //  - skillsSubdir 'config/skills': distinct target from gemini's ~/.gemini/skills
-    //  - homeMarker on ~/.gemini/config/skills: detection never fires on bare
-    //    ~/.gemini (which every Antigravity user has); only the Antigravity skills
-    //    dir, the `agy` CLI, or ANTIGRAVITY_HOME count as "Antigravity installed".
-    key: 'antigravity',
-    label: 'Google Antigravity',
-    cmd: 'agy',
-    home: process.env.ANTIGRAVITY_HOME || path.join(os.homedir(), '.gemini'),
-    envVar: 'ANTIGRAVITY_HOME',
-    skillsSubdir: 'config/skills',
-    homeMarker: path.join(
-      process.env.ANTIGRAVITY_HOME || path.join(os.homedir(), '.gemini'),
-      'config',
-      'skills',
-    ),
-    reload: 'Restart Antigravity, or run "agy skills reload", to load it. Invoke by asking for Agentic SDLC.',
-  },
-];
-
-function commandExists(cmd) {
-  try {
-    execSync(`${cmd} --version`, { stdio: 'ignore' });
-    return true;
-  } catch (e) {
-    return false;
-  }
-}
-
-function clientDetected(client) {
-  // An entry may override the fs-existence probe with a `homeMarker` (a more
-  // specific path than the bare home) so two clients sharing a home dir do not
-  // both fire on its mere existence. Entries without a marker check `home`
-  // exactly as before (backward-compatible).
-  const homePathToCheck = client.homeMarker || client.home;
-  return commandExists(client.cmd)
-    || Boolean(process.env[client.envVar])
-    || fs.existsSync(homePathToCheck);
-}
-
-function skillTarget(client) {
-  // An entry may override the default `skills` sub-path with `skillsSubdir`
-  // (split on '/' to keep cross-platform path.join correctness). Entries
-  // without it resolve to <home>/skills/agentic-sdlc exactly as before.
-  const subdir = client.skillsSubdir ? client.skillsSubdir.split('/') : ['skills'];
-  return path.join(client.home, ...subdir, 'agentic-sdlc');
-}
-
-function copyRecursive(src, dest) {
-  if (typeof fs.cpSync === 'function') {
-    fs.cpSync(src, dest, { recursive: true, force: true });
-    return;
-  }
-  // Fallback for Node < 16.7
-  if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
-  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
-    const s = path.join(src, entry.name);
-    const d = path.join(dest, entry.name);
-    if (entry.isDirectory()) copyRecursive(s, d);
-    else fs.copyFileSync(s, d);
-  }
-}
-
-/**
- * Parse templates.md into { headingText: [fencedBlock, ...] }.
- * Templates are single-sourced there: the init script must extract them
- * instead of carrying its own inline copies (which historically drifted).
- */
-function loadTemplates() {
-  const text = fs.readFileSync(TEMPLATES_PATH, 'utf8');
-  const lines = text.split(/\r?\n/);
-  const sections = {};
-  let heading = null;
-  let block = null;
-  for (const line of lines) {
-    const h = line.match(/^##\s+(.*)$/);
-    if (h && block === null) {
-      heading = h[1].trim();
-      sections[heading] = sections[heading] || [];
-      continue;
-    }
-    if (/^```/.test(line)) {
-      if (block === null) {
-        block = [];
-      } else {
-        if (heading) sections[heading].push(block.join('\n') + '\n');
-        block = null;
-      }
-      continue;
-    }
-    if (block !== null) block.push(line);
-  }
-  return sections;
-}
-
-/**
- * Return the Nth fenced block of the section whose heading contains `needle`.
- * Throws with a clear message when missing: writing a wrong or empty
- * boilerplate silently would be worse than failing the init.
- */
-function templateFor(sections, needle, index = 0) {
-  const heading = Object.keys(sections).find((h) => h.includes(needle));
-  const blocks = heading ? sections[heading] : undefined;
-  if (!blocks || !blocks[index]) {
-    throw new Error(
-      `Template section containing "${needle}" (block ${index}) not found in ${TEMPLATES_PATH}. ` +
-      'The package is corrupted or templates.md was restructured: fix templates.md, do not improvise content.'
-    );
-  }
-  return blocks[index];
-}
-
-module.exports = {
-  PACKAGE_ROOT,
-  SKILL_SOURCE,
-  TEMPLATES_PATH,
-  CLIENTS,
-  commandExists,
-  clientDetected,
-  skillTarget,
-  copyRecursive,
-  loadTemplates,
-  templateFor,
-};
+// Shared helpers for the Agentic SDLC npm scripts (init / postinstall / preuninstall).
+// Single source for client detection and skill-target paths: init and postinstall
+// must never disagree on what "Claude Code is installed" means.
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync } = require('child_process');
+
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+const SKILL_SOURCE = path.join(PACKAGE_ROOT, 'skills', 'agentic-sdlc-skill');
+const TEMPLATES_PATH = path.join(SKILL_SOURCE, 'templates.md');
+// The directory name each client loads the skill from. Derived from the manifest,
+// never hard-coded by a consumer: three distributions share these scripts, and a
+// literal here is how a copy-fork starts installing under its sibling's name.
+const INSTALLED_SKILL_NAME = (() => {
+  const m = fs.readFileSync(path.join(SKILL_SOURCE, 'SKILL.md'), 'utf8').match(/^name:\s*(\S+)/m);
+  if (!m) throw new Error(`SKILL.md carries no 'name:' field: ${SKILL_SOURCE}`);
+  return m[1];
+})();
+
+// One entry per supported AI client. `home` may be overridden by an env var
+// (Claude Desktop / portable installs); presence of the home dir counts as
+// detection even when the CLI is not on PATH.
+const CLIENTS = [
+  {
+    key: 'claude',
+    label: 'Claude Code',
+    cmd: 'claude',
+    home: process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude'),
+    envVar: 'CLAUDE_CONFIG_DIR',
+    reload: 'Restart Claude Code to load it. Invoke via Skill tool as "agentic-sdlc".',
+  },
+  {
+    key: 'gemini',
+    label: 'Gemini CLI',
+    cmd: 'gemini',
+    home: process.env.GEMINI_HOME || path.join(os.homedir(), '.gemini'),
+    envVar: 'GEMINI_HOME',
+    reload: 'Run "gemini skills reload" or restart Gemini CLI to load it.',
+  },
+  {
+    key: 'codex',
+    label: 'Codex AI',
+    cmd: 'codex',
+    home: process.env.CODEX_HOME || path.join(os.homedir(), '.codex'),
+    envVar: 'CODEX_HOME',
+    reload: 'Restart Codex to load it. Invoke it as "$agentic-sdlc" or by asking for Agentic SDLC.',
+  },
+  {
+    // Google Antigravity 2.0 discovers global agent skills under
+    // ~/.gemini/config/skills/ -- the SAME home the legacy Gemini CLI claims.
+    // To avoid a shared-home double-install (P-TM T1), this entry sets:
+    //  - skillsSubdir 'config/skills': distinct target from gemini's ~/.gemini/skills
+    //  - homeMarker on ~/.gemini/config/skills: detection never fires on bare
+    //    ~/.gemini (which every Antigravity user has); only the Antigravity skills
+    //    dir, the `agy` CLI, or ANTIGRAVITY_HOME count as "Antigravity installed".
+    key: 'antigravity',
+    label: 'Google Antigravity',
+    cmd: 'agy',
+    home: process.env.ANTIGRAVITY_HOME || path.join(os.homedir(), '.gemini'),
+    envVar: 'ANTIGRAVITY_HOME',
+    skillsSubdir: 'config/skills',
+    homeMarker: path.join(
+      process.env.ANTIGRAVITY_HOME || path.join(os.homedir(), '.gemini'),
+      'config',
+      'skills',
+    ),
+    reload: 'Restart Antigravity, or run "agy skills reload", to load it. Invoke by asking for Agentic SDLC.',
+  },
+];
+
+function commandExists(cmd) {
+  try {
+    execSync(`${cmd} --version`, { stdio: 'ignore' });
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+function clientDetected(client) {
+  // An entry may override the fs-existence probe with a `homeMarker` (a more
+  // specific path than the bare home) so two clients sharing a home dir do not
+  // both fire on its mere existence. Entries without a marker check `home`
+  // exactly as before (backward-compatible).
+  const homePathToCheck = client.homeMarker || client.home;
+  return commandExists(client.cmd)
+    || Boolean(process.env[client.envVar])
+    || fs.existsSync(homePathToCheck);
+}
+
+function skillTarget(client) {
+  // An entry may override the default `skills` sub-path with `skillsSubdir`
+  // (split on '/' to keep cross-platform path.join correctness). Entries
+  // without it resolve to <home>/skills/agentic-sdlc exactly as before.
+  const subdir = client.skillsSubdir ? client.skillsSubdir.split('/') : ['skills'];
+  return path.join(client.home, ...subdir, INSTALLED_SKILL_NAME);
+}
+
+function copyRecursive(src, dest) {
+  if (typeof fs.cpSync === 'function') {
+    fs.cpSync(src, dest, { recursive: true, force: true });
+    return;
+  }
+  // Fallback for Node < 16.7
+  if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name);
+    const d = path.join(dest, entry.name);
+    if (entry.isDirectory()) copyRecursive(s, d);
+    else fs.copyFileSync(s, d);
+  }
+}
+
+/**
+ * Parse templates.md into { headingText: [fencedBlock, ...] }.
+ * Templates are single-sourced there: the init script must extract them
+ * instead of carrying its own inline copies (which historically drifted).
+ */
+function loadTemplates() {
+  const text = fs.readFileSync(TEMPLATES_PATH, 'utf8');
+  const lines = text.split(/\r?\n/);
+  const sections = {};
+  let heading = null;
+  let block = null;
+  for (const line of lines) {
+    const h = line.match(/^##\s+(.*)$/);
+    if (h && block === null) {
+      heading = h[1].trim();
+      sections[heading] = sections[heading] || [];
+      continue;
+    }
+    if (/^```/.test(line)) {
+      if (block === null) {
+        block = [];
+      } else {
+        if (heading) sections[heading].push(block.join('\n') + '\n');
+        block = null;
+      }
+      continue;
+    }
+    if (block !== null) block.push(line);
+  }
+  return sections;
+}
+
+/**
+ * Return the Nth fenced block of the section whose heading contains `needle`.
+ * Throws with a clear message when missing: writing a wrong or empty
+ * boilerplate silently would be worse than failing the init.
+ */
+function templateFor(sections, needle, index = 0) {
+  const heading = Object.keys(sections).find((h) => h.includes(needle));
+  const blocks = heading ? sections[heading] : undefined;
+  if (!blocks || !blocks[index]) {
+    throw new Error(
+      `Template section containing "${needle}" (block ${index}) not found in ${TEMPLATES_PATH}. ` +
+      'The package is corrupted or templates.md was restructured: fix templates.md, do not improvise content.'
+    );
+  }
+  return blocks[index];
+}
+
+module.exports = {
+  PACKAGE_ROOT,
+  SKILL_SOURCE,
+  INSTALLED_SKILL_NAME,
+  TEMPLATES_PATH,
+  CLIENTS,
+  commandExists,
+  clientDetected,
+  skillTarget,
+  copyRecursive,
+  loadTemplates,
+  templateFor,
+};

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

@@ -14,15 +14,19 @@ python "<skill_dir>/scripts/sdlc_check.py" check
 
 ## 2. Check in CI (recommended for teams)
 
-Copy `scripts/sdlc_check.py` into the repository (e.g. `tools/sdlc_check.py`) and add to the pipeline:
+Copy **both** validator files into the repository — `scripts/sdlc_check.py` (the entry point) **and** `scripts/sdlc_core.py` (the shared core it imports) — keeping them side by side, e.g. `tools/sdlc_check.py` + `tools/sdlc_core.py`. Then add to the pipeline:
 
 ```
 python tools/sdlc_check.py validate --strict
 ```
 
+The validator ships as two files: the core carries the behaviour and is identical in every distribution of the family, the entry point names the domain. Copying only `sdlc_check.py` fails immediately with a message saying so — loudly, never as a silently green pipeline. (Copying `sdlc_core.py` alone also works: `python tools/sdlc_core.py validate --strict` behaves identically, defaulting to the code domain.)
+
 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.
+Note: the copy in the repo is the authoritative one for CI; update it when you update the skill — both 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.
 
 ## 3. PreToolUse hook (gate on writes)
 
@@ -89,11 +93,11 @@ 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 `sdlc_check.py` into the repo, the hook references that copy — keep it 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 both files current when you update the skill.
 
 ## 5. Skill eval battery (release gate)
 
-**Skill development only.** `test_*.py` and `evals/` are deliberately absent from the npm `files` allowlist — they never reach an installed consumer, so this section applies to whoever builds the skill, not to a project that uses it. (Consumers get `sdlc_check.py`; §1–§4 are theirs.)
+**Skill development only.** `test_*.py` and `evals/` are deliberately absent from the npm `files` allowlist — they never reach an installed consumer, so this section applies to whoever builds the skill, not to a project that uses it. (Consumers get `sdlc_check.py` + `sdlc_core.py`; §1–§4 are theirs.)
 
 The skill self-tests its own doctrine invariants. Two layers over one scenario corpus:
 
@@ -103,10 +107,10 @@ The skill self-tests its own doctrine invariants. Two layers over one scenario c
 python -m unittest discover -s skills/agentic-sdlc-skill/scripts -p "test_*.py"
 ```
 
-It aggregates the three test files (`test_plan.py` + `test_session_start.py` + `test_skill_invariants.py`) and asserts the skill's invariants: the M4 triggers/hook/worktree doctrine is present and wired, support-file pointers resolve, and the generated indexes are idempotent. A non-zero exit **blocks the release** — a failing eval is always a real regression, never flakiness: the battery is stdlib-only, makes no model/network/subprocess call (deterministic by construction). If `test_indexes_idempotent` fails, run `sdlc_check.py index` and re-run.
+It aggregates the test files (`test_plan.py` + `test_session_start.py` + `test_skill_invariants.py` + `test_domain_rules.py` + `test_golden_regression.py`) and asserts the skill's invariants: the M4 triggers/hook/worktree doctrine is present and wired, support-file pointers resolve, and the generated indexes are idempotent. A non-zero exit **blocks the release** — a failing eval is always a real regression, never flakiness: the battery is stdlib-only and makes no model or network call. One test does spawn a subprocess — `test_golden_regression.py` runs the shipped validator over a frozen corpus, which is the only way to compare what a user actually sees; it is local, offline and deterministic. If `test_indexes_idempotent` fails, run `sdlc_check.py index` and re-run. If `test_golden_regression` fails, the validator's behaviour on an unchanged project changed: treat that as a regression until someone declares it intended.
 
 **Behavioral corpus — opt-in, non-CI.** `evals/scenarios/*.md` (declarative, model-neutral) + `evals/run_behavioral.py` seed a fixture and print a prompt + pass criteria for a human/agent to run and self-assess. Because live adherence is nondeterministic, this layer **never gates** — it is the reproducible way to check that, e.g., the consult trigger actually fires on a seeded repo (the "demonstrably" artifact).
 
 **Optional CI** (same shape as §2, not mandatory): add a `run:` step invoking the `unittest discover` command above.
 
-**T10 note:** if you copied `sdlc_check.py` 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 (both files) and the `test_*.py` battery into the repo for CI, that copy is authoritative — keep it current when you update the skill.

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

@@ -16,7 +16,8 @@ Support files in the skill directory:
 - `architect.md`: the architect pass — do the components and services this feature needs already exist? Run at L3 before drafting the Impact.
 - `guides.md`: pipeline for distilling user-provided indications into `ai_docs/reference/GUIDE_[topic].md`.
 - `vision.md`: how to write a Vision a cold reviewer can actually apply — the properties that make a rule hold, the minimum operable sections, and the blind check run before promoting one to APPROVED.
-- `scripts/sdlc_check.py`: mechanical validator for `ai_docs/` (`check`, `validate`, `index`, `stale`, `mark`, `gate`, `plan`, `orient`).
+- `routing.md`: which lens owns this unit of work. Read ONLY when a sibling lens skill is installed alongside this one; a single-lens install never reads it.
+- `scripts/sdlc_check.py` + `scripts/sdlc_core.py`: the mechanical validator for the docs root (`check`, `validate`, `index`, `stale`, `mark`, `gate`, `plan`, `orient`, `migrate`). Two files: the core is the family's shared spine, the entry point names this domain. Copy both, or neither.
 - `ENFORCEMENT.md`: optional setup for CI and hooks.
 
 Read these files only when needed. `SKILL.md` is the operating contract; the support files are progressive resources.
@@ -47,9 +48,11 @@ Always classify the request before choosing the process. Declare the chosen leve
 | **Spike** | Time-boxed exploration to reduce uncertainty | Code not mergeable into main. Outcome in `ai_docs/solutions/SPIKE_[topic].md`. For production, reclassify as L2 or L3. |
 
 Cross-cutting rules:
+- **Domain routing (multi-lens installs only).** After the level is set, and only when a sibling lens skill of this family is installed (`kb-agentic`, `mkt-agentic-sdlc`), run the router in `routing.md` for every L2, L3 and Spike: it decides which lens's method and validation rules govern this unit of work. L1 never reaches it, and a single-lens install never reads the file — detection fails open. In such a project, never refer to a document whose meaning differs by lens ("threat model", "vision", `principles.md`, `handoff.md`) by its bare name: qualify it with its domain, or name its path.
 - Parsing of external input, authN/authZ, cryptography, networking, personal data and filesystem access are security-sensitive: never L1.
 - If a bigger impact emerges during L1/L2 work, stop, reclassify and declare it.
 - When in doubt, pick the higher level.
+- **Before asking the user anything — any phase, any level — the question must pass the legality test: search first and name the search with its result; name the decision or fact blocked without the answer.** Blocking the work is the exception, not the default. `elicitation.md` §The question discipline owns the rule and is the only place it is stated — read it before you ask, and do not work from a summary of it.
 - The full audit does not start for L1/L2 unless explicitly requested.
 
 ## Write Triggers

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

@@ -1,22 +1,130 @@
 # Spec Elicitation
 
-Applies when an L3 request enters phase 3 (Request Analysis), BEFORE
-drafting the ANALYSIS document (Standalone) or the D-UC/E-ISP (Hybrid).
+`## The question discipline` below governs EVERY question to the user — any
+phase, any level, inside or outside the round. The rest of the file is the spec
+elicitation round: it applies when an L3 request enters phase 3 (Request
+Analysis), BEFORE drafting the ANALYSIS document (Standalone) or the D-UC/E-ISP
+(Hybrid).
 
-Skip path: if the spec is already complete — an approved Vision or explicit
-user requirements already answer goal, scope, and constraints — skip the
-round and add a one-line note in the analysis stating why it was skipped.
-Do not run the round as a formality when the answers are already on record.
+Skip path: if the spec is already complete — an approved Vision or explicit user
+requirements already answer goal, scope, and constraints, or the remainder is
+derivable from the repo, `ai_docs/` and the conversation — skip the round and add
+a one-line note in the analysis stating why it was skipped and naming the
+sources. Do not run the round as a formality when the answers are already on
+record.
 
-Unattended path: when the user is not reachable (a scheduled or autonomous run,
-and a bootstrap Vision is `DRAFT` by mandate, so the skip path above cannot
-apply on a project's first L3), do not stall and do not invent consensus. Write
-the six answers as **declared assumptions** in `## Objective`, mark the ANALYSIS
-`BLOCKED on the user`, and stop before implementation. An assumption on the
-record is reviewable; a guess folded silently into a design is not.
+Unattended path: when the user is not reachable (a scheduled or autonomous run)
+and the skip path does not answer all six, do not stall and do not invent
+consensus. Write the missing answers as **declared assumptions** in
+`## Objective`, mark the ANALYSIS `BLOCKED on the user`, and stop before
+implementation. An assumption on the record is reviewable; a guess folded
+silently into a design is not.
+
+## The question discipline
+
+A question to the user spends their attention and stalls the work; the round
+below is the only place the process *plans* that cost. Everywhere, a question is
+legal only when BOTH hold:
+
+1. **Searched first, and the search is named — with its result.** The answer is
+   not on record and not derivable from the repo, `ai_docs/`, the Vision or the
+   conversation — and the question states the terms, tools and areas you searched
+   **and what they returned**. Same standard as a router verdict or an
+   architect-pass MISSING, and it carries their floors, not only their vocabulary
+   (`architect.md`, `guides.md`): a search whose scope does not cover the question
+   is not a search; a hit you did not open does not narrow anything; and **never
+   fake the search** — "I looked and found nothing" that names no terms and no
+   areas is a search not run. A question the repo can answer is a search
+   outsourced to the user.
+2. **It names what is blocked.** The question states the specific decision or
+   fact that cannot be resolved without the reply — what you will do differently
+   depending on the answer. If nothing downstream changes with the answer, there
+   is no question.
+
+Never legal:
+
+- **Generic confirmation** — "shall I proceed?", "is this OK?". The process
+  authorizes proceeding; if a real risk motivates the ask, name the risk and the
+  fork — that is a blocking question and carries the form below.
+- **Preference-fishing** — asking the user to pick among options that are
+  equivalent **in their effect on the benefit** and already decided by the
+  project's conventions. Cheapness to undo is NOT the test: nearly everything is
+  reversible under version control, and "it is reversible" as a licence to stop
+  asking is the silence-side evasion this clause must not fund.
+- **Re-asking the record** — goal, scope or constraints that an APPROVED Vision,
+  an earlier reply, or the request itself already states.
+
+What questions are FOR — what the user uniquely owns: the benefit, priorities
+between conflicting goods, non-goals, acceptance, and the approvals doctrine
+reserves to them (Vision promotion and amendment, scope changes, proposal
+acceptance, merge decisions). Facts about intent come from the user; facts about
+the system come from search. (The marketing sibling states the same rule as "ask
+only what the user uniquely owns"; this is its code-domain form.)
+
+**Precedence, because both halves can fire at once:** this paragraph wins over
+the "never legal" list above it. A choice the user uniquely owns is never
+preference-fishing, however cheap it is to undo; the list reaches choices that
+are *not* theirs.
+
+**Default non-blocking.** An unknown on which no fork of the work depends: write
+it as a **declared assumption** in the artifact it touches — the same mechanism
+the unattended path uses — proceed, and present the open points **batched**, with
+the round for spec questions or with the deliverable otherwise, answered by
+exception.
+
+This is the path most work takes, so it carries the SAME evidence duty as a
+question, not a lighter one — otherwise "assume it" becomes the way to skip the
+standard. Each declared assumption states **what it is taken from** ("I take X
+from Y" — the same shape the round uses) and **the alternative it excludes**, and
+**every declared assumption reaches the batch**: an assumption nobody is shown is
+not an open point, it is a silent decision. That pairing is what the kb family's
+escalation rule actually does — keep BOTH sides with their sources and surface
+them, never silently pick one — and this branch, not the blocking one, is where
+it structurally belongs. An assumption recorded with its source and its rejected
+alternative is reviewable; one recorded alone is a decision wearing an
+assumption's clothes, and a session stalled on a question that could have been
+an assumption is the waste this section exists to prevent.
+
+**Blocking is reserved** for three cases: proceeding under ANY assumption would
+waste the work (the forks diverge at once, and the wrong branch is rework of the
+whole unit); the doctrine reserves the decision to the user (the approvals
+above); or the doctrine itself mandates the stop — and a mandated stop is legal
+by mandate, never re-argued here.
+
+**Exactly two mandating files prescribe their own hand-over, and there the form
+below does not apply** (two forms over one moment is the duplicate `review.md`
+§Reviewing forbids): `debugging.md`'s circuit breaker — the minimal reproduction,
+what was ruled out, the current best hypothesis; and `review.md`'s round cap —
+the artifact plus the open findings. That list is closed. **Every other mandated
+stop carries the form**, including one that names only its options and not its
+evidence (`SKILL.md`'s Vision-Gate conflict names the two choices — the evidence
+is still owed, and for a Vision conflict the quoted line IS the substance) and
+one that prescribes nothing (`guides.md`'s guide proposal and its ingestion
+bound). "The file mentions the moment" is not a prescription; only a stated
+hand-over is.
+
+A blocking question carries a mandatory form — surface both sides with their
+evidence, never silently pick one:
+
+- the fork: the concrete options and what each implies for the work;
+- the evidence: what you searched, read or tried, and what it leaves undecided;
+- why no assumption survives — what work is discarded if you assume and are
+  wrong. This is what makes case (a) falsifiable: without it, "this is a fork"
+  is an agent's assertion about its own convenience, and case (a) becomes the
+  licence for exactly the question this section forbids. Cases (b) and (c) answer
+  it by citing the approval or the mandate instead;
+- why it is the user's call — what makes the remainder intent, priority or
+  approval rather than a derivable fact;
+- what stays blocked until answered.
 
 ## The round
 
+**Derive before asking.** Answer each of the six from the record first — the
+Vision, `ai_docs/`, the conversation, the code. Ask only the residue, and carry
+the derived answers into the round as declared assumptions corrected by
+exception ("I take X from Y; the questions below are what no source answers"),
+not re-confirmed one by one.
+
 Ask ONE structured set of questions, not a drip of follow-ups. Keep each
 question short and numbered; offer concrete options where a real choice
 exists (this narrows the reply and speeds up the round). Cover:
@@ -53,8 +161,9 @@ run a second round to double-check answers that were already clear.
 
 - **Interrogation**: an endless list of questions, or drip-feeding one
   question at a time across many turns instead of one structured round.
-- **Asking what the approved vision already answers**: re-asking goal or
-  non-goals that a `Status: APPROVED` Vision or M-VISION already states.
 - **Collecting answers without folding them in**: getting replies in chat
   and proceeding to design without writing them into the analysis document —
   the next reader has no record of why the scope is what it is.
+
+(The illegal question forms — generic confirmation, preference-fishing,
+re-asking the record — are defined once, in `## The question discipline`.)

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

@@ -125,20 +125,30 @@ When you are the reviewer:
   statement is the proof the check ran; an unfalsifiable "I checked" is the review
   theater this discipline exists to prevent (the reviewer-side twin of §Receiving's
   silent-drop rule). Plain code reviews stay findings-only.
+- **Restated facts (cite, never copy).** Every governance slot has ONE owning document
+  per project. A fact restated in the artifact under review when another document owns
+  it is a **finding**: the fix is a citation naming the owner, not a better copy. This
+  binds the conformance statement too — where a constraint is satisfied by another
+  document, name that document as the evidence instead of repeating what it says. Two
+  copies of one fact diverge at the first edit, and the reader then has no way to tell
+  which one is current. The rule bites hardest across domains, where the same slot
+  ("threat model", "vision", "handoff") carries a different meaning under each lens and
+  a copy looks like an independent second source.
 - **Capability Ledger (same reviews).** **An L3 impact/solution analysis or design
-  that carries NO Capability Ledger is itself a finding** — the architect pass left
+  that carries NO Capability Ledger is itself a finding** — the lens's capability
+  pass (`architect.md` in the code lens, `taxonomy.md` in the knowledge lens) left
   no record, and "the artifact does not have one" is what a skipped pass looks like,
   not a reason to skip the check. (This half is load-bearing in Hybrid, where the
   validator backstop reads Standalone ANALYSIS files only and this clause is the
   sole check that the pass ran.) When the ledger is there, map each
   ledger row to where the design or diff realizes it. Three findings live here and
-  nowhere else (`architect.md`): a capability ruled MISSING but implemented inside
+  nowhere else (the capability-pass file named above): a capability ruled MISSING but implemented inside
   the feature's code path, with no component owning it; a component whose contract
   names the feature (a second consumer would force it open); and a capability ruled
   MISSING, not built, and absorbed by quietly reshaping the feature — that is a
   scope change owed to the user, not a design detail. An EXISTS row with no named
   path or symbol is itself a finding. A capability built in this change and absent
-  from the `## Component Map` (`strategic/architecture.md`) is a finding too — and
+  from the `## Component Map` (`strategic/architecture.md`, where the lens keeps one) is a finding too — and
   so is **a component the pass merely DISCOVERED and did not write**, especially
   when the change marks that area ANALYZED: the area now looks read, the map is
   still silent, and the next feature may lawfully rule the capability MISSING and