@antoneeo/kb-agentic-skill 1.4.7 → 1.5.0

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"
           }
         ]
       }