@antoneeo/kb-agentic-skill 1.0.0

package/scripts/init.js

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const { SKILL_SOURCE, CLIENTS, clientDetected, skillTarget, loadTemplates, templateFor } = require('./lib');
+
+// Sibling lenses of the same family: one shared core, one `ai_docs/` tree, a different
+// fidelity discipline each. Keyed by the installed skill directory name.
+const SIBLING_LENSES = {
+  'agentic-sdlc': 'code',
+  'mkt-agentic-sdlc': 'marketing',
+};
+
+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).
+const protocolContent = `# KB Agentic — Project Protocol (pointer)
+
+This project follows the KB Agentic Knowledge-Base & Document-First process. The full
+operating contract is the \`kb-agentic\` skill (installed in your agent's
+skills directory); this file is only the minimal always-on pointer.
+
+## Rule Zero — Triage every request
+- L1 Quick Fact / Snippet: small edit in existing note/doc; no new docs.
+- L2 Local Note / SOP Update: specific SOP update, local research note (1-2 files). Mini-analysis in reply.
+- L3 Major Knowledge Unit / Corpus: >3 files, multi-part guide creation, corpus ingestion, or KB restructuring. Full workflow via skill: Vision Gate -> Spec Elicitation -> Taxonomy Pass -> Knowledge Analysis -> Distillation -> Review -> Indexing.
+- Spike: time-boxed exploration; outcome in \`ai_docs/solutions/SPIKE_[topic].md\`.
+- High-risk areas (personal data, credentials, authN/authZ, security specs) 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.
+- Knowledge analyses: \`ai_docs/solutions/ANALYSIS_[topic].md\` (frontmatter = topic 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 text 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 kb-agentic skill is not available in this client, ask the user to install it:
+\`npm i -g @antoneeo/kb-agentic-skill && kb-agentic-install-skill\`
+`;
+
+console.log('🚀 Initializing KB Agentic 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);
+}
+
+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;
+  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()],
+  ];
+} 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',
+};
+
+// 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}
+- \`agentic-sdlc\` — the **code** 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 knowledge lens's ladder
+to that file by hand — the pointer below — so both are always loaded.
+
+## Rule Zero — Triage every request (knowledge lens)
+- L1 Quick fact: a small update to an existing note, 1-2 files.
+- L2 Local note / SOP update: at most 1-2 files, low risk, sources named.
+- L3 Major knowledge unit: large document sets, multi-topic research, corpus
+  restructuring. Full workflow via the skill.
+- Spike: time-boxed exploration; outcome in \`ai_docs/solutions/SPIKE_[topic].md\`.
+` : `The always-on protocol pointer for the knowledge 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 code-lens ladder from AGENTIC_MULTI_LENS.md into it by hand.');
+  }
+}
+
+// 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']) {
+  try {
+    execSync(`${py} "${validator}" index --root "${cwd}"`, { stdio: 'ignore' });
+    console.log('📇 Generated ai_docs/INDEX.md (document manifest).');
+    indexed = true;
+    break;
+  } catch (e) { /* try next */ }
+}
+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 kb-agentic skill is installed (kb-agentic-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

@@ -0,0 +1,152 @@
+// 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];
+})();
+
+// 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,
+};

package/scripts/postinstall.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const { SKILL_SOURCE, CLIENTS, clientDetected, skillTarget, copyRecursive } = require('./lib');
+
+function installSkill(client) {
+  if (!fs.existsSync(SKILL_SOURCE)) {
+    console.log(`⚠️  Skill source not found at ${SKILL_SOURCE}; skipping ${client.label} install.`);
+    return false;
+  }
+  const target = skillTarget(client);
+  try {
+    fs.mkdirSync(target, { recursive: true });
+    copyRecursive(SKILL_SOURCE, target);
+    console.log(`📦 Installed ${client.label} skill at: ${target}`);
+    console.log(`   ${client.reload}`);
+    return true;
+  } catch (err) {
+    console.log(`⚠️  Failed to install ${client.label} skill: ${err.message}`);
+    console.log(`   Manual install: copy "${SKILL_SOURCE}" to "${target}".`);
+    return false;
+  }
+}
+
+console.log('\n--- KB Agentic Skill Discovery ---');
+
+let detected = false;
+for (const client of CLIENTS) {
+  if (clientDetected(client)) {
+    console.log(`✅ Detected: ${client.label}`);
+    detected = true;
+    installSkill(client);
+  }
+}
+
+if (!detected) {
+  console.log('ℹ️  No specific AI CLI detected globally, but you can still use the skill.');
+}
+
+console.log('\nTo initialize a project with the KB Agentic protocol, run:');
+console.log('👉 npx kb-agentic-init');
+console.log('------------------------------------\n');

package/scripts/preuninstall.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const { CLIENTS, skillTarget } = require('./lib');
+
+function removeSkill(client) {
+  const target = skillTarget(client);
+  if (!fs.existsSync(target)) return;
+  try {
+    fs.rmSync(target, { recursive: true, force: true });
+    console.log(`🧹 Removed ${client.label} skill at: ${target}`);
+  } catch (err) {
+    console.log(`⚠️  Could not remove ${target}: ${err.message}`);
+  }
+}
+
+CLIENTS.forEach(removeSkill);

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

@@ -0,0 +1,123 @@
+# Mechanical enforcement (optional, recommended for teams)
+
+Prompt-level rules depend on the model's discipline and degrade with long contexts, compaction and competing instructions. Three levels of increasing guarantee:
+
+## 1. Interactive validation (default, no setup)
+
+The agent runs a single gate at closure (Phase 5):
+
+```
+python "<skill_dir>/scripts/sdlc_check.py" check
+```
+
+(`check` = validate + stale in one command.) Exit code ≠ 0 ⇒ the feature is not declared closed. This is the minimum level the skill expects.
+
+## 2. Check in CI (recommended for teams)
+
+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 family's shared behaviour and is identical in every distribution; the entry point IS the knowledge overlay — since F-024/F-025 it carries the claim ledger and the topic-graph checks. Copying only `sdlc_check.py` fails immediately with a message saying so — loudly, never as a silently green pipeline. Copying `sdlc_core.py` alone still runs, but **no longer behaves identically for kb**: it validates the family surface and runs NONE of the claim or graph checks (`graph`, `corpus`, the claim-table integrity inside `check`), so a kb project whose CI copies one file is green while its knowledge surface is unchecked. Copy both. For a kb project, add the graph step to CI:
+
+```
+python tools/sdlc_check.py graph --root .
+python tools/sdlc_check.py corpus --root .
+```
+
+(Both are no-ops printing `nothing to check` on a tree without `topics/`/`corpus/`, so the step is safe to add unconditionally; `check` already includes them.)
+
+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 — 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)
+
+Blocks Edit/Write on protected paths when no `ANALYSIS_*.md` is `IN_PROGRESS`. In the project's `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python \"C:\\Users\\<user>\\.claude\\skills\\agentic-sdlc\\scripts\\sdlc_check.py\" gate --hook --protected \"src/auth;src/crypto\""
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Semantics: exit code 2 + message on stderr ⇒ the write is blocked and the message is shown to the agent, which must create the ANALYSIS (Phase 3) before retrying.
+
+**Usage warnings:**
+- The gate is deliberately coarse: applied to all of `src/` it would also block the legitimate L1/L2 tasks foreseen by the Triage. Use it **only on security-critical directories** (`--protected "src/auth;src/crypto"`), where "never without analysis" is the desired policy.
+- The paths in `--protected` are prefixes relative to the project root, separated by `;`.
+- `ai_docs/`, `tests/` and `test/` are always excluded from blocking.
+- The hook assumes the working directory is the project root (standard behavior of Claude Code hooks).
+- **Hybrid/devPNT projects**: add `--hybrid` to the gate command. Governed designs live in the devPNT DB, so the gate also unlocks when an approved E-TDD shadow (`ai_docs/solutions/SHADOW_*tdd*.md`, exported before implementation — see the SKILL.md shadow discipline) is present. Without the flag the gate would block legitimate governed work. The flag is deliberately explicit: never auto-detected.
+
+## 4. SessionStart hook (orientation, recommended default)
+
+Emits the `ai_docs/` orientation — reading guide (`README.md`), manifest (`INDEX.md`), guide router (`reference/INDEX.md`) and last `handoff.md` — plus the Rule-Zero triage reminder to stdout at session start, so the agent begins already oriented instead of reading them only if it remembers to. It is **fail-open**: a missing, unreadable or oversized doc is skipped, the output is size-capped, and it always exits 0 — a broken or empty `ai_docs/` never blocks the session. It is **zero-execution** (it reads and prints, never runs anything).
+
+**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.
+
+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`:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python \"C:\\Users\\<user>\\.claude\\skills\\agentic-sdlc\\scripts\\sdlc_check.py\" orient"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Codex — in `.codex/hooks.json`, the same `SessionStart` → `{"type":"command","command":"… orient"}` shape (this replaces the legacy static-echo protocol some fixtures still carry).
+
+Gemini CLI — wire the same command into its startup-hook mechanism if present; otherwise the step simply degrades to the manual Phase-1 reads (no capability lost).
+
+**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.
+
+## 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.)
+
+The skill self-tests its own doctrine invariants. Two layers over one scenario corpus:
+
+**Static battery — the deterministic release gate.** Run before any publish:
+
+```
+python -m unittest discover -s skills/kb-agentic-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.
+
+**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.