@antoneeo/kb-agentic-skill 1.4.8 → 1.5.1

package/CHANGELOG.md

@@ -2,6 +2,77 @@
 
 Every significant change to this skill is recorded here.
 
+## [1.5.1] - 2026-08-25
+
+### Fixed
+- **The three README front pages did not mention the hook wiring that 1.27.0 added.**
+  `init` now changes what every project gets, and the README *is* the npm page, so two
+  of the three said nothing about it and the third barely did. Each now describes the
+  wiring, the settings.json / settings.local.json split and why it exists, and the
+  broken-hook report. `GUIDE_release.md` step 2 already made this a release duty; it was
+  skipped in 1.27.0 and this is the catch-up.
+- **`publish_all.bat`'s verify block reported the previous version after a successful
+  publish — twice.** `--prefer-online` (added in kb 1.4.8) forces revalidation but cannot
+  outrun CDN propagation of the `latest` tag in the seconds after publishing, so the
+  1.27.0 run printed mkt `0.4.7` when `0.5.0` had in fact landed. The flag alone was the
+  wrong fix and the note claiming otherwise is corrected: the block now **polls** each
+  package until the registry agrees with the local version, and prints both when it does
+  not, so "did it publish?" is answerable from the run instead of a manual `npm view`.
+
+## [1.5.0] - 2026-08-25
+
+F-036 — the orientation hook installs itself.
+
+### Fixed
+- **`ENFORCEMENT.md` 4 said "wire it on every project" and nothing ever did.** The
+  SessionStart orientation hook was real, tested and fail-open, but installing it was a
+  manual step, so it was skipped — and a session that never enters Phase 1 explicitly
+  then never meets the guide router at all. Field result: an agent worked a governed
+  project without invoking the process. `init` now wires the hook itself.
+- **The invariant that looked like it guarded this guarded only prose** — it asserted
+  the documentation section exists (`assertIn("## 4. SessionStart hook", t)`) and that
+  `orient` runs. It gains a companion asserting the shipped installer actually CALLS the
+  writer. Mutation-tested: the first draft asserted the bare symbol and passed on a file
+  that imports the writer without invoking it, which is exactly the disabled-installer
+  case it exists to catch.
+
+### Fixed (also)
+- **ENFORCEMENT 4/2's own worked hook examples named a skill directory that two of
+  the three lenses do not install.** kb and mkt both printed
+  `.claude/skills/agentic-sdlc/scripts/...`; kb installs under `kb-agentic` and mkt
+  under `mkt-agentic-sdlc`, so anyone who copied the snippet got a hook that runs,
+  prints `can't open file`, and emits nothing — the wired-and-dead defect this release
+  detects, sitting in the instructions that produce it. Four paths corrected, and a new
+  invariant derives the expected directory and validator from what the distribution
+  actually ships and fails if an example names anything else. Mutation-tested.
+
+### Added
+- **A portability rule the doctrine did not have.** The hook command names a validator,
+  and where that validator lives decides which settings file may carry it: a repo that
+  vendors the validator gets a repo-relative command in the shared, committed
+  `.claude/settings.json`; a normal project gets an absolute path, which goes to the
+  git-ignored `.claude/settings.local.json` instead — committing it would hand every
+  teammate a hook naming a directory they do not have. `init` picks the file and adds
+  the local one to `.gitignore`. ENFORCEMENT 4's own worked example showed an absolute
+  path and did not mention the distinction; it now does.
+- **A wired-but-dead hook is detected and reported instead of counted as done.** Found
+  in the field: a repository whose hook named a sibling lens's path, so it ran every
+  session, printed `can't open file`, and emitted nothing. A bare "is a hook present?"
+  check answers "already wired" to that and makes the silence permanent, so the existing
+  command's validator path is checked on disk. Never rewritten — it may be hand-tuned —
+  but never passed off as working either.
+
+### Notes
+- `init` declines rather than guessing: no Python, skill not installed, a settings file
+  that is not valid JSON (never rewritten — a merge would discard what is in it), or a
+  skill path containing a double quote. Each case prints the snippet to paste.
+- Only Claude Code's hook shape is wired. Codex and Gemini keep the manual snippet: this
+  repository has no fixture pinning their schema, and writing a hook file in a shape
+  nobody has verified is how the wired-but-dead defect above was born.
+- A blocking `PreToolUse` gate would be real enforcement rather than a nudge, and it is
+  refused by the Vision's no-ceremony-ratchet Non-Goal. Recorded in the analysis so the
+  next person to have the idea finds the ruling instead of re-deriving it.
+
 ## [1.4.8] - 2026-08-25
 
 F-035 — second field report from the F-029 practitioner. Three defects in the corpus

package/README.md

@@ -67,6 +67,19 @@ kb-agentic-init
 
 Run it inside a project to create `ai_docs/`, Vision documents, strategic docs, audit plan, and agent protocol files (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursorrules`).
 
+It also **wires the SessionStart orientation hook** into `.claude/`, so an agent opening
+the project is handed the reading guide, the generated manifest, the guide router and the
+last handoff before it does anything — instead of only when it remembers to look. That
+wiring used to be a manual step documented in `ENFORCEMENT.md`; being manual, it was
+skipped, and a project could run fully governed with an agent that never met the process.
+
+The hook command names a validator, so where that validator lives decides which file gets
+it: a repo that vendors it gets a repo-relative command in the shared `.claude/settings.json`
+(portable — commit it); otherwise the path is machine-specific and goes to the git-ignored
+`.claude/settings.local.json`, and each teammate runs `init` once. Re-running `init` never
+duplicates the hook, and a hook whose validator no longer resolves is reported as **broken**
+with the correction rather than counted as installed.
+
 ## The family: three lenses, one spine
 
 | Package | Faithful to | Unit of work |

package/gemini-extension.json

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

package/package.json

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

package/scripts/init.js

@@ -3,7 +3,7 @@
 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 { SKILL_SOURCE, INSTALLED_SKILL_NAME, SELF_LENS, SIBLING_LENSES, CLIENTS, clientDetected, skillTarget, wireOrientHook, loadTemplates, templateFor } = require('./lib');
 
 const cwd = process.cwd();
 
@@ -149,8 +149,22 @@ const protocolFiles = {
 // written aside and merged by hand.
 let protocolPreexisting = false;
 
-for (const client of CLIENTS) {
-  if (clientDetected(client)) {
+// Probed ONCE and reused by section 6c: re-filtering CLIENTS there would
+// run every client's detection a second time.
+const detectedClients = CLIENTS.filter(clientDetected);
+const PYTHON_CANDIDATES = ['python', 'python3', 'py'];
+const detectedPython = (() => {
+  for (const py of PYTHON_CANDIDATES) {
+    try {
+      execSync(`${py} --version`, { stdio: 'ignore' });
+      return py;
+    } catch (e) { /* try the next interpreter */ }
+  }
+  return null;
+})();
+
+for (const client of detectedClients) {
+  {
     console.log(`✅ ${client.label} detected.`);
     const created = writeIfNotExists(protocolFiles[client.key], protocolContent, `${client.label} protocol pointer`);
     if (!created) protocolPreexisting = true;
@@ -214,15 +228,118 @@ Delete it once the merge is done.
   }
 }
 
+
+// 6c. SessionStart orientation hook (F-036).
+// ENFORCEMENT.md §4 asks for this on every project with a docs root and Python.
+// It was a manual step until now, so it was skipped -- and a session that never
+// enters Phase 1 explicitly then never meets the guide router at all.
+
+// devPNT projects want `--hybrid`: without it the hook reports audit-plan
+// staleness that devPNT/KL owns, and noise at every session start is how a
+// session-start message stops being read.
+const hybridProject = fs.existsSync(path.join(cwd, '.devpnt'));
+
+// Only touch .gitignore when the wiring landed in the machine-specific file:
+// if that file is not ignored, the absolute path reaches teammates anyway and
+// the whole reason for choosing it is undone. Append-only and marker-guarded,
+// exactly like gitattributes() above. Wrapped, because the installer has already
+// written the seed files and must not die here.
+const ignoreLocalSettings = () => {
+  const marker = '.claude/settings.local.json';
+  if (!fs.existsSync(path.join(cwd, '.git'))) return;
+  const filePath = path.join(cwd, '.gitignore');
+  try {
+    const current = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
+    // Line-wise, not substring: a `!.claude/settings.local.json` un-ignore would
+    // satisfy `includes()` and leave the machine-specific path committed.
+    if (current.split(/\r?\n/).some((l) => l.trim() === marker)) return;
+    fs.writeFileSync(filePath, current + [
+      '',
+      '# agentic-sdlc: the orientation hook here names a path on THIS machine.',
+      marker,
+      '',
+    ].join(EOL), 'utf8');
+    console.log(`OK    .gitignore: ${marker} ignored (it names a machine-specific path).`);
+    console.log('      If it is already tracked, run: git rm --cached ' + marker);
+  } catch (e) {
+    console.log(`⚠️  Could not update .gitignore (${e.message}). Add "${marker}" by hand.`);
+  }
+};
+
+const claudeClient = detectedClients.find((c) => c.key === 'claude');
+const otherClients = detectedClients.filter((c) => c.key !== 'claude');
+if (!claudeClient) {
+  console.log('ℹ️  Claude Code not detected: SessionStart orientation hook not wired.');
+} else {
+  const r = wireOrientHook({
+    cwd, client: claudeClient, python: detectedPython,
+    hybrid: hybridProject, docsLabel: 'ai_docs',
+  });
+  switch (r.code) {
+    case 'wired':
+      console.log(`🪝 Wired the SessionStart orientation hook in .claude/${r.file}.`);
+      if (r.local) {
+        console.log('   It names a path on THIS machine, so it went to the git-ignored');
+        console.log('   file: each teammate runs init once to get their own.');
+        ignoreLocalSettings();
+      }
+      break;
+    case 'already':
+      console.log(`⏭️  SessionStart orientation hook already wired (.claude/${r.file}).`);
+      if (r.file === 'settings.local.json') ignoreLocalSettings();
+      break;
+    case 'broken':
+      console.log(`⚠️  The SessionStart orientation hook in .claude/${r.file} is BROKEN —`);
+      console.log('   its validator does not resolve, so it has been emitting nothing:');
+      console.log(`     ${r.existing}`);
+      console.log('   Not overwritten (it may be hand-tuned). Correct it to:');
+      console.log(`     ${r.command}`);
+      break;
+    case 'unverifiable':
+      console.log(`ℹ️  A SessionStart orientation hook exists in .claude/${r.file} but names`);
+      console.log('   no validator this installer recognises, so it was left alone:');
+      console.log(`     ${r.existing}`);
+      break;
+    case 'malformed':
+      console.log(`⚠️  .claude/${r.file} has a shape this installer will not rewrite`);
+      console.log(`   (${r.why}): left untouched. Add the hook by hand — command:`);
+      console.log(`     ${JSON.stringify(r.command)}`);
+      break;
+    case 'write-failed':
+      console.log(`⚠️  Could not write .claude/${r.file} (${r.error}). Add by hand:`);
+      console.log(`     ${JSON.stringify(r.command)}`);
+      break;
+    case 'no-python':
+      console.log('ℹ️  Python not found: SessionStart orientation hook not wired.');
+      break;
+    case 'no-validator':
+      console.log('ℹ️  Skill not installed yet: orientation hook not wired. Install it');
+      console.log('   (below), then re-run init.');
+      break;
+    case 'unsafe-path':
+      console.log('⚠️  The validator path contains a character that cannot be placed in a');
+      console.log(`   hook command safely: ${r.validator}`);
+      console.log('   Refusing to build one. Wire it by hand (ENFORCEMENT.md §4).');
+      break;
+  }
+}
+for (const c of otherClients) {
+  // Said out loud rather than skipped in silence: ENFORCEMENT.md §4's manual
+  // snippet is these clients' only route, and a silent skip is what let the
+  // "documented default nobody installs" defect live in the first place.
+  console.log(`ℹ️  ${c.label}: hook not wired (only Claude Code's shape is verified) —`);
+  console.log('   wire it by hand from ENFORCEMENT.md §4 if that client supports it.');
+}
+
 // 7. Generate ai_docs/INDEX.md
 const validator = path.join(SKILL_SOURCE, 'scripts', 'sdlc_check.py');
 let indexed = false;
-for (const py of ['python', 'python3', 'py']) {
+// detectedPython is probed once, above: one answer for the hook and for this.
+if (detectedPython) {
   try {
-    execSync(`${py} "${validator}" index --root "${cwd}"`, { stdio: 'ignore' });
+    execSync(`${detectedPython} "${validator}" index --root "${cwd}"`, { stdio: 'ignore' });
     console.log('📇 Generated ai_docs/INDEX.md (document manifest).');
     indexed = true;
-    break;
   } catch (e) { /* try next */ }
 }
 if (!indexed) {

package/scripts/lib.js

@@ -1,202 +1,409 @@
-// Shared helpers for the KB Agentic npm scripts (init / postinstall / preuninstall).
-// Single source for client detection and skill-target paths.
-
-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', 'kb-agentic-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
-// 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 "kb-agentic".',
-  },
-  {
-    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 "$kb-agentic" or by asking for KB Agentic.',
-  },
-  {
-    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 KB Agentic.',
-  },
-];
-
-function commandExists(cmd) {
-  try {
-    execSync(`${cmd} --version`, { stdio: 'ignore' });
-    return true;
-  } catch (e) {
-    return false;
-  }
-}
-
-function clientDetected(client) {
-  const homePathToCheck = client.homeMarker || client.home;
-  return commandExists(client.cmd)
-    || Boolean(process.env[client.envVar])
-    || fs.existsSync(homePathToCheck);
-}
-
-function skillTarget(client) {
-  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;
-  }
-  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);
-  }
-}
-
-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;
-}
-
-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,
-};
-
-// 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 });
-
+// Shared helpers for the KB Agentic npm scripts (init / postinstall / preuninstall).
+// Single source for client detection and skill-target paths.
+
+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', 'kb-agentic-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
+// 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 "kb-agentic".',
+  },
+  {
+    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 "$kb-agentic" or by asking for KB Agentic.',
+  },
+  {
+    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 KB Agentic.',
+  },
+];
+
+function commandExists(cmd) {
+  try {
+    execSync(`${cmd} --version`, { stdio: 'ignore' });
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+function clientDetected(client) {
+  const homePathToCheck = client.homeMarker || client.home;
+  return commandExists(client.cmd)
+    || Boolean(process.env[client.envVar])
+    || fs.existsSync(homePathToCheck);
+}
+
+function skillTarget(client) {
+  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;
+  }
+  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);
+  }
+}
+
+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;
+}
+
+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];
+}
+
+// --- SessionStart orientation hook (F-036) ---------------------------------
+// ENFORCEMENT.md §4 says to wire this on every project that has a docs root and
+// a Python interpreter. Until F-036 nothing did: it was a manual step, so it was
+// skipped, and the guide router reached no agent that did not already know to
+// look for it. The hook only INJECTS orientation -- it cannot force a skill
+// invocation, and the mechanism that could (a blocking PreToolUse gate) is
+// refused by the Vision's no-ceremony-ratchet Non-Goal.
+
+const ORIENT_HOOK_TIMEOUT = 10;
+
+// The validator's filename is DERIVED, never written here: the marketing lens
+// ships `mkt_check.py` where the others ship `sdlc_check.py`, and this block is
+// copied verbatim into all three distributions. A literal would make two of the
+// three look for an entry point that does not exist.
+const ORIENT_ENTRY_POINTS = ['sdlc_check.py', 'mkt_check.py'];
+const ORIENT_ENTRY_POINT = (() => {
+  for (const name of ORIENT_ENTRY_POINTS) {
+    if (fs.existsSync(path.join(SKILL_SOURCE, 'scripts', name))) return name;
+  }
+  return ORIENT_ENTRY_POINTS[0];
+})();
+
+// Both settings layers are ALWAYS inspected for an existing hook, whichever one
+// we would write to. Scanning only the target file left two holes: a project
+// that starts un-vendored and later vendors flips the target from the local file
+// to the shared one, finds nothing there, and appends a second hook; and a dead
+// hook in the layer we are not writing stays invisible.
+const ORIENT_SETTINGS_FILES = ['settings.json', 'settings.local.json'];
+
+// A vendored path is built from a directory name read out of the TARGET
+// repository, and the result is executed by the client as a shell command. That
+// is repo-controlled input reaching a command line, so each segment must match
+// this exactly -- `$(...)`, backticks and newlines are not "unusual names", they
+// are the payload. The absolute branch cannot reach this input (it is built from
+// os.homedir() and the client roster) but is filtered too, below.
+const ORIENT_SAFE_SEGMENT = /^[A-Za-z0-9._-]+$/;
+// Refused anywhere in a command path. NOT backslash: a Windows path is full of
+// them and the shape this project already commits uses them.
+const ORIENT_UNSAFE_IN_PATH = /["$`\r\n]/;
+
+// Where a repo may legitimately vendor the validator. ENFORCEMENT §2 tells users
+// to copy it next to their CI config (`tools/`), and a skill-authoring repo
+// carries it under `skills/<lens>/scripts/`. Both are checked; the lens matching
+// this distribution wins, so a monorepo vendoring several lenses cannot wire a
+// sibling's validator against this lens's docs root.
+function vendoredValidator(cwd) {
+  const direct = [];
+  for (const dir of ['tools', 'scripts']) {
+    direct.push([dir, ORIENT_ENTRY_POINT].join('/'));
+  }
+  const skillDirs = (() => {
+    let entries;
+    try {
+      entries = fs.readdirSync(path.join(cwd, 'skills'), { withFileTypes: true });
+    } catch (e) {
+      return [];                        // no skills/ here, or it is not a directory
+    }
+    const names = entries.filter((e) => e.isDirectory()).map((e) => e.name)
+      .filter((n) => ORIENT_SAFE_SEGMENT.test(n));
+    // This lens first: readdir order must not decide which lens we orient.
+    names.sort((a, b) => (a === INSTALLED_SKILL_NAME ? -1 : 0)
+      - (b === INSTALLED_SKILL_NAME ? -1 : 0));
+    return names.map((n) => ['skills', n, 'scripts', ORIENT_ENTRY_POINT].join('/'));
+  })();
+  for (const rel of direct.concat(skillDirs)) {
+    if (fs.existsSync(path.join(cwd, rel))) return rel;
+  }
+  return null;
+}
+
+function orientHookCommand(python, validator, hybrid) {
+  return python + ' "' + validator + '" orient' + (hybrid ? ' --hybrid' : '');
+}
+
+// The token in an EXISTING command that names a validator -- quoted or bare, and
+// NOT simply "the first quoted thing". That naive rule failed both ways: a
+// command that quotes the interpreter (`"C:\Py\python.exe" "...sdlc_check.py"`)
+// returned the interpreter, which exists, so a DEAD hook reported as healthy;
+// and a command with no quotes at all returned nothing, so a WORKING hook was
+// reported broken. Returns null when no token names a validator: the caller must
+// then say it cannot tell, never that the hook is broken.
+function orientHookValidator(command) {
+  const cmd = String(command || '');
+  const re = /"([^"]*)"|(\S+)/g;
+  let m;
+  while ((m = re.exec(cmd)) !== null) {
+    const token = m[1] !== undefined ? m[1] : m[2];
+    if (ORIENT_ENTRY_POINTS.some((n) => token.endsWith(n))) return token;
+  }
+  return null;
+}
+
+// Accepts both shapes seen in the wild: the documented groups
+// (`SessionStart: [{ hooks: [...] }]`) and hook objects placed directly in the
+// array. Anything else is reported by the caller rather than silently replaced.
+function findOrientHook(settings) {
+  const groups = settings && settings.hooks && settings.hooks.SessionStart;
+  if (!Array.isArray(groups)) return null;
+  for (const group of groups) {
+    if (!group || typeof group !== 'object') continue;
+    const inner = Array.isArray(group.hooks) ? group.hooks : [group];
+    for (const h of inner) {
+      const cmd = h && typeof h.command === 'string' ? h.command : '';
+      if (ORIENT_ENTRY_POINTS.some((n) => cmd.includes(n)) && / orient(\s|$)/.test(cmd)) {
+        return cmd;
+      }
+    }
+  }
+  return null;
+}
+
+// A settings object we can safely merge into: absent, or carrying the shapes we
+// know. "I do not recognise this" must mean "write nothing", never "treat it as
+// empty" -- the second is how a hand-written hook disappears.
+function orientSettingsState(target) {
+  if (!fs.existsSync(target)) return { ok: true, settings: {} };
+  let settings;
+  try {
+    settings = JSON.parse(fs.readFileSync(target, 'utf8'));
+  } catch (e) {
+    return { ok: false, why: 'unreadable' };
+  }
+  if (!settings || typeof settings !== 'object' || Array.isArray(settings)) {
+    return { ok: false, why: 'not-an-object' };
+  }
+  const hooks = settings.hooks;
+  if (hooks !== undefined
+      && (!hooks || typeof hooks !== 'object' || Array.isArray(hooks))) {
+    return { ok: false, why: 'unexpected-hooks' };
+  }
+  if (hooks && hooks.SessionStart !== undefined && !Array.isArray(hooks.SessionStart)) {
+    return { ok: false, why: 'unexpected-hooks' };
+  }
+  return { ok: true, settings };
+}
+
+// Returns a RESULT CODE, never printed text: the caller owns the wording and the
+// battery asserts on the code. Codes:
+//   wired | already | broken | unverifiable | malformed
+//   no-validator | no-python | unsafe-path | write-failed
+function wireOrientHook(options) {
+  const cwd = options.cwd;
+  const client = options.client;
+  const python = options.python;
+  const hybrid = !!options.hybrid;
+  const docsLabel = options.docsLabel || 'project';
+
+  const vendored = vendoredValidator(cwd);
+  const absolute = path.join(skillTarget(client), 'scripts', ORIENT_ENTRY_POINT);
+  const validator = vendored || absolute;
+  if (!vendored && !fs.existsSync(absolute)) return { code: 'no-validator', validator };
+  if (!python) return { code: 'no-python', validator };
+  if (ORIENT_UNSAFE_IN_PATH.test(validator)) return { code: 'unsafe-path', validator };
+
+  const command = orientHookCommand(python, validator, hybrid);
+
+  // Inspect BOTH layers before deciding to write anything.
+  for (const name of ORIENT_SETTINGS_FILES) {
+    const p = path.join(cwd, '.claude', name);
+    const state = orientSettingsState(p);
+    if (!state.ok) {
+      if (fs.existsSync(p)) return { code: 'malformed', file: name, target: p, why: state.why, command };
+      continue;
+    }
+    const existing = findOrientHook(state.settings);
+    if (!existing) continue;
+    const found = orientHookValidator(existing);
+    if (found === null) {
+      return { code: 'unverifiable', file: name, target: p, existing, command };
+    }
+    const resolves = fs.existsSync(path.isAbsolute(found) ? found : path.join(cwd, found));
+    return resolves
+      ? { code: 'already', file: name, target: p, command: existing }
+      : { code: 'broken', file: name, target: p, existing, command };
+  }
+
+  // A machine-specific command must not reach the shared, committed file.
+  const file = vendored ? 'settings.json' : 'settings.local.json';
+  const target = path.join(cwd, '.claude', file);
+  const state = orientSettingsState(target);
+  if (!state.ok) return { code: 'malformed', file, target, why: state.why, command };
+  const settings = state.settings;
+
+  if (!settings.hooks) settings.hooks = {};
+  if (!Array.isArray(settings.hooks.SessionStart)) settings.hooks.SessionStart = [];
+  settings.hooks.SessionStart.push({
+    hooks: [{
+      type: 'command',
+      command,
+      timeout: ORIENT_HOOK_TIMEOUT,
+      statusMessage: 'Loading ' + docsLabel + ' orientation...',
+    }],
+  });
+
+  // The installer has already written seed files by this point; an unwritable
+  // settings file must not take the whole run down with a stack trace.
+  try {
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, JSON.stringify(settings, null, 2) + String.fromCharCode(10), 'utf8');
+  } catch (e) {
+    return { code: 'write-failed', file, target, command, error: e.message };
+  }
+  return { code: 'wired', file, target, command, local: !vendored };
+}
+
+module.exports = {
+  PACKAGE_ROOT,
+  SKILL_SOURCE,
+  INSTALLED_SKILL_NAME,
+  TEMPLATES_PATH,
+  CLIENTS,
+  commandExists,
+  clientDetected,
+  skillTarget,
+  wireOrientHook,
+  orientHookCommand,
+  copyRecursive,
+  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/kb-agentic-skill/ENFORCEMENT.md

@@ -48,7 +48,7 @@ Blocks Edit/Write on protected paths when no `ANALYSIS_*.md` is `IN_PROGRESS`. I
         "hooks": [
           {
             "type": "command",
-            "command": "python \"C:\\Users\\<user>\\.claude\\skills\\agentic-sdlc\\scripts\\sdlc_check.py\" gate --hook --protected \"src/auth;src/crypto\""
+            "command": "python \"C:\\Users\\<user>\\.claude\\skills\\kb-agentic\\scripts\\sdlc_check.py\" gate --hook --protected \"src/auth;src/crypto\""
           }
         ]
       }
@@ -72,6 +72,37 @@ Emits the `ai_docs/` orientation — reading guide (`README.md`), manifest (`IND
 
 **Wire it on every project that has `ai_docs/` and a Python interpreter.** It was opt-in until v1.16.0 and the field result was the defect this level exists to prevent: the guide router stayed unread unless the user asked for it by hand, so guides were written and never consulted. Prompt-level placement (Rule Zero declares the router verdict; Phase 1 reads the router) carries the process on its own — this hook is the backstop that survives long contexts, compaction and a session that never enters Phase 1 explicitly. Skip it only where Python is unavailable, and know what you are trading.
 
+**`init` wires it for you (F-036).** Running `init` on a project that has a docs root
+and a Python interpreter now installs this hook itself — it was a manual step until
+2026-08-25, and the field result was exactly the defect this level exists to prevent: an
+agent worked a governed project without ever meeting the router. The snippet below is
+the fallback for the cases init declines, and the list is exhaustive: **any client
+other than Claude Code** (Codex and Gemini keep the manual snippet — no fixture in the
+repository pins their hook schema, and writing one in an unverified shape is how a
+wired-but-dead hook is born), no Python, the skill not installed yet, a settings file
+that is not valid JSON or carries a `hooks`/`SessionStart` shape the writer does not
+recognise (it never rewrites one it cannot read), a validator path holding a character
+that cannot be placed in a command safely, or a settings file it cannot write. `init`
+prints which case applied, per client — a silent skip is what let "documented default
+that nobody installs" survive in the first place.
+
+**Which settings file, and why it is not always the shared one.** The command names a
+validator, and where that validator lives decides where the hook may be written:
+
+| Case | Command | File |
+|---|---|---|
+| The repo vendors the validator (§2) | repo-relative | `.claude/settings.json` — portable, commit it |
+| The validator is only in your skills directory (the normal case) | absolute | `.claude/settings.local.json` — machine-specific, git-ignored; each teammate runs `init` once |
+
+Committing an absolute `C:\Users\<you>\...` path into the shared file hands every teammate a hook naming
+a directory they do not have. `init` picks the file for you, and adds
+`.claude/settings.local.json` to `.gitignore` when it uses the local one.
+
+**A hook that is wired and DEAD is the worst of the three states**: it emits nothing at
+every session AND it looks installed. `init` checks that an existing hook's validator
+still resolves and reports it as BROKEN with the corrected command, rather than
+reporting "already wired". It never rewrites the entry — it may be hand-tuned.
+
 Wire it via each client's SessionStart mechanism — the same command everywhere (add `--hybrid` on devPNT/Hybrid projects):
 
 Claude Code — in the project's `.claude/settings.json`:
@@ -84,7 +115,7 @@ Claude Code — in the project's `.claude/settings.json`:
         "hooks": [
           {
             "type": "command",
-            "command": "python \"C:\\Users\\<user>\\.claude\\skills\\agentic-sdlc\\scripts\\sdlc_check.py\" orient"
+            "command": "python \"C:\\Users\\<user>\\.claude\\skills\\kb-agentic\\scripts\\sdlc_check.py\" orient"
           }
         ]
       }

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

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