@antoneeo/agentic-sdlc-skill 1.19.0 → 1.20.3

package/scripts/init.js

@@ -1,156 +1,217 @@
-#!/usr/bin/env node
-
-const fs = require('fs');
-const path = require('path');
-const { execSync } = require('child_process');
-const { SKILL_SOURCE, CLIENTS, clientDetected, loadTemplates, templateFor } = require('./lib');
-
-const cwd = process.cwd();
-
-// 1. Directory layout (canonical ai_docs structure, including reference/)
-const directories = [
-  'ai_docs',
-  'ai_docs/vision',
-  'ai_docs/vision/features',
-  'ai_docs/reference',
-  'ai_docs/strategic',
-  'ai_docs/audit',
-  'ai_docs/solutions',
-].map((d) => path.join(cwd, d));
-
-// 2. Project protocol (thin pointer — the operating contract is the skill).
-// Deliberately short: duplicating the skill's rules here made them drift.
-const protocolContent = `# Agentic SDLC — Project Protocol (pointer)
-
-This project follows the Agentic SDLC Documentation-First process. The full
-operating contract is the \`agentic-sdlc\` skill (installed in your agent's
-skills directory); this file is only the minimal always-on pointer.
-
-## Rule Zero — Triage every request
-- L1 Trivial: ~10 lines, 1-2 files, no API/dependency/behavior change. Implement + run existing tests; no docs.
-- L2 Small: clear root cause, at most 3 files, low risk. Mini-analysis in the reply; tests mandatory.
-- L3 Significant: >3 files, APIs/contracts, new dependency, user-visible behavior, security-sensitive area, or architectural change. Full workflow via the skill: Vision Gate -> ANALYSIS -> plan -> implement -> test -> closure.
-- Spike: time-boxed exploration; outcome in \`ai_docs/solutions/SPIKE_[topic].md\`; reclassify for production.
-- Security-sensitive areas (external input parsing, authN/authZ, crypto, network, personal data, filesystem) are never L1.
-- When in doubt, pick the higher level. Declare the chosen level when starting.
-
-## Where things live
-- Vision (gate for L3): \`ai_docs/vision/\` — \`Status: DRAFT\` informs, \`Status: APPROVED\` binds.
-- Feature analyses: \`ai_docs/solutions/ANALYSIS_[feature].md\` (frontmatter = feature state).
-- Must-reads: \`ai_docs/README.md\`; full generated manifest: \`ai_docs/INDEX.md\`.
-- If devPNT is available for this project, its M-VISION / plans / governed artifacts take over (Hybrid mode — see the skill).
-
-## Closure gate
-Docs travel in the same commit/PR as the code they describe. If the project
-adopts the validator, \`python <skill_dir>/scripts/sdlc_check.py check\` must be
-CLEAN before declaring work done.
-
-If the agentic-sdlc skill is not available in this client, ask the user to install it:
-\`npm i -g @antoneeo/agentic-sdlc-skill && agentic-sdlc-install-skill\`
-`;
-
-console.log('🚀 Initializing Agentic SDLC workflow...');
-
-// 3. Load templates from the single source (skill's templates.md)
-let sections;
-try {
-  sections = loadTemplates();
-} catch (err) {
-  console.error(`❌ Cannot load templates: ${err.message}`);
-  process.exit(1);
-}
-
-// audit_plan: the template block carries illustrative rows; a fresh project
-// starts from a single root PENDING row instead.
-function initialAuditPlan() {
-  const tpl = templateFor(sections, 'audit_plan.md');
-  const lines = tpl.split('\n');
-  const sepIdx = lines.findIndex((l) => /^\|[-\s|:]+\|$/.test(l.trim()));
-  if (sepIdx === -1) return tpl; // unexpected shape: keep the template as-is
-  // '.' (the project root), never '/': an absolute row makes `stale` walk the
-  // whole drive once the area is marked ANALYZED.
-  return lines.slice(0, sepIdx + 1).join('\n') + '\n| . | PENDING | - | Initial analysis |\n';
-}
-
-let seedFiles;
-try {
-  seedFiles = [
-    ['ai_docs/README.md', templateFor(sections, 'ai_docs/README.md')],
-    ['ai_docs/vision/project_vision.md', templateFor(sections, 'project_vision.md')],
-    ['ai_docs/vision/roadmap.md', templateFor(sections, 'vision/roadmap.md')],
-    ['ai_docs/vision/principles.md', templateFor(sections, 'principles.md')],
-    ['ai_docs/strategic/architecture.md', templateFor(sections, 'architecture.md and existing_features.md', 0)],
-    ['ai_docs/strategic/existing_features.md', templateFor(sections, 'architecture.md and existing_features.md', 1)],
-    ['ai_docs/audit/audit_plan.md', initialAuditPlan()],
-    // NOTE: features_history.md and INDEX.md are NOT seeded — they are
-    // generated by `sdlc_check.py index` and would immediately fail validate.
-  ];
-} catch (err) {
-  console.error(`❌ ${err.message}`);
-  process.exit(1);
-}
-
-// 4. Create directories
-directories.forEach((dir) => {
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
-    console.log(`📁 Created directory: ${path.relative(cwd, dir)}`);
-  }
-});
-
-// 5. Write seed files (never overwrite)
-const writeIfNotExists = (relPath, content, description) => {
-  const filePath = path.join(cwd, relPath);
-  if (!fs.existsSync(filePath)) {
-    fs.writeFileSync(filePath, content, 'utf8');
-    console.log(`📄 Created file: ${relPath}${description ? ` (${description})` : ''}`);
-    return true;
-  }
-  console.log(`⏭️  Skipped: ${relPath} already exists.`);
-  return false;
-};
-
-seedFiles.forEach(([relPath, content]) => writeIfNotExists(relPath, content));
-
-// 6. Client discovery and protocol pointers
-console.log('\n--- Environment Analysis ---');
-
-const protocolFiles = {
-  claude: 'CLAUDE.md',
-  gemini: 'GEMINI.md',
-  codex: 'AGENTS.md',
-  antigravity: 'AGENTS.md', // Antigravity CLI reads AGENTS.md; single protocolContent reused.
-};
-
-for (const client of CLIENTS) {
-  if (clientDetected(client)) {
-    console.log(`✅ ${client.label} detected.`);
-    writeIfNotExists(protocolFiles[client.key], protocolContent, `${client.label} protocol pointer`);
-  }
-}
-
-// Cursor/Windsurf (always recommended)
-writeIfNotExists('.cursorrules', protocolContent, 'Cursor/Windsurf rules');
-
-// 7. Generate ai_docs/INDEX.md so the very first `validate` is already clean.
-// The manifest is generated, never seeded: delegate to the validator if Python is available.
-const validator = path.join(SKILL_SOURCE, 'scripts', 'sdlc_check.py');
-let indexed = false;
-for (const py of ['python', 'python3', 'py']) {
-  try {
-    execSync(`${py} "${validator}" index --root "${cwd}"`, { stdio: 'ignore' });
-    console.log('📇 Generated ai_docs/INDEX.md (document manifest).');
-    indexed = true;
-    break;
-  } catch (e) { /* try the next interpreter */ }
-}
-if (!indexed) {
-  console.log('ℹ️  Python not found: generate the manifest later with '
-    + '"python <skill_dir>/scripts/sdlc_check.py index" (validate reports it until then).');
-}
-
-console.log('\n✅ Setup completed successfully!');
-console.log('💡 Next steps:');
-console.log('   1. Make sure the agentic-sdlc skill is installed (agentic-sdlc-install-skill).');
-console.log('   2. Restart/open the project in your AI client so it reads the protocol pointer.');
-console.log('   3. Start with an audit following ai_docs/audit/audit_plan.md.');
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const { SKILL_SOURCE, INSTALLED_SKILL_NAME, SELF_LENS, SIBLING_LENSES, CLIENTS, clientDetected, skillTarget, loadTemplates, templateFor } = require('./lib');
+
+const cwd = process.cwd();
+
+// 1. Directory layout (canonical ai_docs structure, including reference/)
+const directories = [
+  'ai_docs',
+  'ai_docs/vision',
+  'ai_docs/vision/features',
+  'ai_docs/reference',
+  'ai_docs/strategic',
+  'ai_docs/audit',
+  'ai_docs/solutions',
+].map((d) => path.join(cwd, d));
+
+// 2. Project protocol (thin pointer — the operating contract is the skill).
+// Deliberately short: duplicating the skill's rules here made them drift.
+const protocolContent = `# Agentic SDLC — Project Protocol (pointer)
+
+This project follows the Agentic SDLC Documentation-First process. The full
+operating contract is the \`agentic-sdlc\` skill (installed in your agent's
+skills directory); this file is only the minimal always-on pointer.
+
+## Rule Zero — Triage every request
+- L1 Trivial: ~10 lines, 1-2 files, no API/dependency/behavior change. Implement + run existing tests; no docs.
+- L2 Small: clear root cause, at most 3 files, low risk. Mini-analysis in the reply; tests mandatory.
+- L3 Significant: >3 files, APIs/contracts, new dependency, user-visible behavior, security-sensitive area, or architectural change. Full workflow via the skill: Vision Gate -> ANALYSIS -> plan -> implement -> test -> closure.
+- Spike: time-boxed exploration; outcome in \`ai_docs/solutions/SPIKE_[topic].md\`; reclassify for production.
+- Security-sensitive areas (external input parsing, authN/authZ, crypto, network, personal data, filesystem) are never L1.
+- When in doubt, pick the higher level. Declare the chosen level when starting.
+
+## Where things live
+- Vision (gate for L3): \`ai_docs/vision/\` — \`Status: DRAFT\` informs, \`Status: APPROVED\` binds.
+- Feature analyses: \`ai_docs/solutions/ANALYSIS_[feature].md\` (frontmatter = feature state).
+- Must-reads: \`ai_docs/README.md\`; full generated manifest: \`ai_docs/INDEX.md\`.
+- If devPNT is available for this project, its M-VISION / plans / governed artifacts take over (Hybrid mode — see the skill).
+
+## Closure gate
+Docs travel in the same commit/PR as the code they describe. If the project
+adopts the validator, \`python <skill_dir>/scripts/sdlc_check.py check\` must be
+CLEAN before declaring work done.
+
+If the agentic-sdlc skill is not available in this client, ask the user to install it:
+\`npm i -g @antoneeo/agentic-sdlc-skill && agentic-sdlc-install-skill\`
+`;
+
+console.log('🚀 Initializing Agentic SDLC workflow...');
+
+// 3. Load templates from the single source (skill's templates.md)
+let sections;
+try {
+  sections = loadTemplates();
+} catch (err) {
+  console.error(`❌ Cannot load templates: ${err.message}`);
+  process.exit(1);
+}
+
+// audit_plan: the template block carries illustrative rows; a fresh project
+// starts from a single root PENDING row instead.
+function initialAuditPlan() {
+  const tpl = templateFor(sections, 'audit_plan.md');
+  const lines = tpl.split('\n');
+  const sepIdx = lines.findIndex((l) => /^\|[-\s|:]+\|$/.test(l.trim()));
+  if (sepIdx === -1) return tpl; // unexpected shape: keep the template as-is
+  // '.' (the project root), never '/': an absolute row makes `stale` walk the
+  // whole drive once the area is marked ANALYZED.
+  return lines.slice(0, sepIdx + 1).join('\n') + '\n| . | PENDING | - | Initial analysis |\n';
+}
+
+let seedFiles;
+try {
+  seedFiles = [
+    ['ai_docs/README.md', templateFor(sections, 'ai_docs/README.md')],
+    ['ai_docs/vision/project_vision.md', templateFor(sections, 'project_vision.md')],
+    ['ai_docs/vision/roadmap.md', templateFor(sections, 'vision/roadmap.md')],
+    ['ai_docs/vision/principles.md', templateFor(sections, 'principles.md')],
+    ['ai_docs/strategic/architecture.md', templateFor(sections, 'architecture.md and existing_features.md', 0)],
+    ['ai_docs/strategic/existing_features.md', templateFor(sections, 'architecture.md and existing_features.md', 1)],
+    ['ai_docs/audit/audit_plan.md', initialAuditPlan()],
+    // NOTE: features_history.md and INDEX.md are NOT seeded — they are
+    // generated by `sdlc_check.py index` and would immediately fail validate.
+  ];
+} catch (err) {
+  console.error(`❌ ${err.message}`);
+  process.exit(1);
+}
+
+// 4. Create directories
+directories.forEach((dir) => {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+    console.log(`📁 Created directory: ${path.relative(cwd, dir)}`);
+  }
+});
+
+// 5. Write seed files (never overwrite)
+const writeIfNotExists = (relPath, content, description) => {
+  const filePath = path.join(cwd, relPath);
+  if (!fs.existsSync(filePath)) {
+    fs.writeFileSync(filePath, content, 'utf8');
+    console.log(`📄 Created file: ${relPath}${description ? ` (${description})` : ''}`);
+    return true;
+  }
+  console.log(`⏭️  Skipped: ${relPath} already exists.`);
+  return false;
+};
+
+seedFiles.forEach(([relPath, content]) => writeIfNotExists(relPath, content));
+
+// 6. Client discovery and protocol pointers
+console.log('\n--- Environment Analysis ---');
+
+const protocolFiles = {
+  claude: 'CLAUDE.md',
+  gemini: 'GEMINI.md',
+  codex: 'AGENTS.md',
+  antigravity: 'AGENTS.md', // Antigravity CLI reads AGENTS.md; single protocolContent reused.
+};
+
+// A protocol pointer that ALREADY existed was written by someone else — typically a
+// sibling lens's init, which seeded the project with its own triage ladder. This init
+// must not overwrite it (create-only is the T1 guarantee), so the second ladder is
+// written aside and merged by hand.
+let protocolPreexisting = false;
+
+for (const client of CLIENTS) {
+  if (clientDetected(client)) {
+    console.log(`✅ ${client.label} detected.`);
+    const created = writeIfNotExists(protocolFiles[client.key], protocolContent, `${client.label} protocol pointer`);
+    if (!created) protocolPreexisting = true;
+  }
+}
+
+// Cursor/Windsurf (always recommended)
+writeIfNotExists('.cursorrules', protocolContent, 'Cursor/Windsurf rules');
+
+// 6b. Sibling lenses: additive only. Never edits a user-authored root file.
+function installedSiblingLenses() {
+  const found = new Map();
+  for (const client of CLIENTS) {
+    if (!clientDetected(client)) continue;
+    const skillsDir = path.dirname(skillTarget(client));
+    for (const [dirName, lens] of Object.entries(SIBLING_LENSES)) {
+      if (fs.existsSync(path.join(skillsDir, dirName))) found.set(dirName, lens);
+    }
+  }
+  return found;
+}
+
+const siblings = installedSiblingLenses();
+if (siblings.size > 0) {
+  const list = [...siblings].map(([dir, lens]) => `- \`${dir}\` — the **${lens}** lens`).join('\n');
+  console.log(`\n🔀 Sibling lens detected: ${[...siblings.keys()].join(', ')}.`);
+  const wrote = writeIfNotExists('AGENTIC_MULTI_LENS.md', `# Multi-lens project — routing note (additive)
+
+This project has more than one lens of the Agentic SDLC family installed:
+
+${list}
+- \`${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
+in the skill's \`routing.md\`: it decides which lens's method and validation rules govern
+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.
+
+${protocolPreexisting ? `**Merge step owed.** The always-on protocol pointer of this project (\`CLAUDE.md\` /
+\`GEMINI.md\` / \`AGENTS.md\` / \`.cursorrules\`) was written by another lens's init and
+carries ITS triage ladder. This init did not overwrite it. Add the code lens's ladder
+to that file by hand — the pointer below — so both are always loaded.
+
+## Rule Zero — Triage every request (code lens)
+- L1 Trivial: ~10 lines, 1-2 files, no API/dependency/behavior change.
+- L2 Small: clear root cause, at most 3 files, low risk. Tests mandatory.
+- L3 Significant: >3 files, APIs/contracts, new dependency, user-visible behavior,
+  security-sensitive area, or architectural change. Full workflow via the skill.
+- Spike: time-boxed exploration; outcome in \`ai_docs/solutions/SPIKE_[topic].md\`.
+` : `The always-on protocol pointer for the code lens was created by this init. When you
+install another lens over this project, its init will leave its own ladder here for you
+to merge.
+`}
+This file is NOT auto-loaded by any client: it is a note for you, deliberately additive.
+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 ${SELF_LENS}-lens ladder from AGENTIC_MULTI_LENS.md into it by hand.`);
+  }
+}
+
+// 7. Generate ai_docs/INDEX.md so the very first `validate` is already clean.
+// The manifest is generated, never seeded: delegate to the validator if Python is available.
+const validator = path.join(SKILL_SOURCE, 'scripts', 'sdlc_check.py');
+let indexed = false;
+for (const py of ['python', 'python3', 'py']) {
+  try {
+    execSync(`${py} "${validator}" index --root "${cwd}"`, { stdio: 'ignore' });
+    console.log('📇 Generated ai_docs/INDEX.md (document manifest).');
+    indexed = true;
+    break;
+  } catch (e) { /* try the next interpreter */ }
+}
+if (!indexed) {
+  console.log('ℹ️  Python not found: generate the manifest later with '
+    + '"python <skill_dir>/scripts/sdlc_check.py index" (validate reports it until then).');
+}
+
+console.log('\n✅ Setup completed successfully!');
+console.log('💡 Next steps:');
+console.log('   1. Make sure the agentic-sdlc skill is installed (agentic-sdlc-install-skill).');
+console.log('   2. Restart/open the project in your AI client so it reads the protocol pointer.');
+console.log('   3. Start with an audit following ai_docs/audit/audit_plan.md.');

package/scripts/lib.js

@@ -10,6 +10,59 @@ 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];
+})();
+
+// The family's lens table, read from the shared `routing.md` rather than restated
+// here. Same reason as INSTALLED_SKILL_NAME above, and the same failure it prevents:
+// BOTH the row for this lens and the rows for its siblings used to be literals copied
+// between distributions, so kb and mkt wrote a multi-lens note announcing themselves
+// as the code lens. routing.md is one of the byte-identical shared files, so this
+// lookup cannot drift between distributions.
+// Lazy on purpose: preuninstall.js needs INSTALLED_SKILL_NAME and nothing else, and
+// must keep working on an installation damaged badly enough to have lost routing.md.
+function lensTable() {
+  const routing = path.join(SKILL_SOURCE, 'routing.md');
+  if (!fs.existsSync(routing)) throw new Error(`routing.md missing from the skill: ${SKILL_SOURCE}`);
+  // Parsed as a table, not matched with a regex: a mis-escaped pattern matches the
+  // empty string and yields undefined instead of throwing, which is how this lookup
+  // failed the first time it was written.
+  const table = new Map();
+  for (const line of fs.readFileSync(routing, 'utf8').split(/\r?\n/)) {
+    const cells = line.split('|').map((cell) => cell.trim());
+    if (cells.length < 4) continue;
+    const [, lens, skill] = cells;
+    if (!/^[a-z]+$/.test(lens) || !/^`[a-z0-9-]+`$/.test(skill)) continue;
+    const name = skill.slice(1, -1);
+    // A duplicate row would otherwise be won silently by whichever came first, and a
+    // wrong routing.md propagates byte-identically to every distribution.
+    if (table.has(name)) throw new Error(`routing.md lists '${name}' more than once`);
+    table.set(name, lens);
+  }
+  if (!table.size) throw new Error(`routing.md carries no lens table: ${routing}`);
+  return table;
+}
+
+function selfLens() {
+  const lens = lensTable().get(INSTALLED_SKILL_NAME);
+  if (!lens) throw new Error(`routing.md has no lens row for '${INSTALLED_SKILL_NAME}'`);
+  return lens;
+}
+
+// Sibling lenses of the same family: one shared core, one docs tree, a different
+// fidelity discipline each. Keyed by the installed skill directory name.
+function siblingLenses() {
+  const table = lensTable();
+  selfLens();                       // this lens must be in the table too
+  table.delete(INSTALLED_SKILL_NAME);
+  return Object.fromEntries(table);
+}
 
 // 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
@@ -87,7 +140,7 @@ function skillTarget(client) {
   // (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');
+  return path.join(client.home, ...subdir, INSTALLED_SKILL_NAME);
 }
 
 function copyRecursive(src, dest) {
@@ -157,6 +210,7 @@ function templateFor(sections, needle, index = 0) {
 module.exports = {
   PACKAGE_ROOT,
   SKILL_SOURCE,
+  INSTALLED_SKILL_NAME,
   TEMPLATES_PATH,
   CLIENTS,
   commandExists,
@@ -166,3 +220,8 @@ module.exports = {
   loadTemplates,
   templateFor,
 };
+
+// Lazy: reading routing.md is deferred to the consumer that actually asks.
+Object.defineProperty(module.exports, 'SELF_LENS', { enumerable: true, get: selfLens });
+Object.defineProperty(module.exports, 'SIBLING_LENSES', { enumerable: true, get: siblingLenses });
+

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