agent-harness-kit 0.6.0 → 0.8.0

package/.claude-plugin/marketplace.json

@@ -11,9 +11,9 @@
       "source": {
         "source": "github",
         "repo": "tuanle96/agent-harness-kit",
-        "ref": "v0.6.0"
+        "ref": "v0.8.0"
       },
-      "version": "0.6.0",
+      "version": "0.8.0",
       "description": "Solo-dev harness engineering kit — layered architecture, GC ritual, structural tests, review subagents.",
       "category": "development",
       "keywords": [

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-harness-kit",
-  "version": "0.3.0",
+  "version": "0.8.0",
   "description": "Solo-dev harness engineering kit — layered architecture, garbage-collection ritual, structural tests, review subagents. Optimized for Claude Code 2.1+.",
   "author": {
     "name": "Tuan Le"

package/README.md

@@ -191,6 +191,35 @@ developer. The `eval-runner` skill enforces a per-run budget set in
 | Flask                          | python       | `flask`     | `flask --app app run --debug`          | v0.1   |
 | Go / Rust                      | core only    | none        | (manual)                               | v0.4   |
 
+## CI: real-claude E2E test (v0.7+)
+
+The kit ships a CI job that spawns the real `claude` binary against a fresh
+init of itself and asserts that the SessionStart hook actually fires (with
+the expected `additionalContext` payload). This catches the class of bug
+that v0.6's silent-no-op hooks fell into — every synthetic test passed for
+seven releases while not a single hook ever triggered inside a real Claude
+Code session.
+
+**Behavior:**
+
+- Locally: `npm test` skips the E2E case cleanly when no `ANTHROPIC_API_KEY`
+  is set (1 skip, 0 fail).
+- CI with secret: the `e2e-claude` job runs the driver, installs
+  `@anthropic-ai/claude-code` globally, and exercises one claude turn
+  (~$0.01–0.05). Failure means a hook system regression.
+- CI without secret (fork PRs): emits a GitHub Actions warning and exits 0
+  so the PR can still merge — but you lose the v0.6-class bug guard for
+  that run.
+
+To enable on your own fork: configure the `ANTHROPIC_API_KEY` repository
+secret in GitHub Actions settings.
+
+Local run (uses whatever auth the `claude` binary already has):
+
+```bash
+AHK_E2E_USE_LOCAL_AUTH=1 node scripts/e2e-claude-cli.mjs
+```
+
 ## License
 
 MIT.

package/bin/cli.mjs

@@ -43,6 +43,15 @@ program
     "force init for languages without a structural-test adapter yet (go, rust, swift, kotlin)",
     false,
   )
+  .option(
+    "--lang <code>",
+    "human language for the CLAUDE.md template (en, vi)",
+    "en",
+  )
+  .option(
+    "--model <id>",
+    "Claude model to pin in .claude/settings.json (e.g. claude-opus-4-7, claude-sonnet-4-6, claude-haiku-4-5)",
+  )
   .action(async (opts) => {
     const cwd = opts.cwd ? resolve(opts.cwd) : process.cwd();
     console.log(pc.bold(pc.cyan(`\nagent-harness-kit v${pkg.version}\n`)));
@@ -104,7 +113,10 @@ program
     // initing at the root of a Go/Rust/Swift/Kotlin project produces a
     // half-broken harness (structural test missing, ts-morph engine pinned).
     // Skills + reviewers still work, but the user should opt in explicitly.
-    const UNSUPPORTED = new Set(["go", "rust", "swift", "kotlin"]);
+    // Swift + Kotlin shipped regex-based adapters in v0.7; Go + Rust earlier.
+    // No language is "unsupported" today — the set is empty, kept as a hook
+    // for future languages that don't yet have an adapter.
+    const UNSUPPORTED = new Set([]);
     if (UNSUPPORTED.has(stack.language) && !opts.allowUnsupported) {
       console.log(
         pc.yellow(
@@ -187,6 +199,8 @@ program
       installHooks,
       installCi,
       kitVersion: pkg.version,
+      humanLanguage: opts.lang || "en",
+      model: opts.model,
     });
 
     console.log("");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-harness-kit",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Solo-dev harness engineering kit for Claude Code. Layered architecture, structural tests, garbage-collection ritual, review subagents — without the enterprise overhead.",
   "type": "module",
   "bin": {

package/src/core/detect-stack.mjs

@@ -157,6 +157,22 @@ export async function detectStack(cwd) {
     return result;
   }
 
+  // Swift / Kotlin — regex-based adapters (added in v0.7).
+  if (await exists(resolve(cwd, "Package.swift"))) {
+    result.language = "swift";
+    result.packageManager = "swift";
+    return result;
+  }
+  if (
+    (await exists(resolve(cwd, "build.gradle.kts"))) ||
+    (await exists(resolve(cwd, "settings.gradle.kts"))) ||
+    (await exists(resolve(cwd, "build.gradle")))
+  ) {
+    result.language = "kotlin";
+    result.packageManager = "gradle";
+    return result;
+  }
+
   return result;
 }
 

package/src/core/doctor.mjs

@@ -6,6 +6,7 @@ import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { execSync } from "node:child_process";
 import pc from "picocolors";
+import { SUPPORTED_MODELS } from "./render-templates.mjs";
 
 function check(name, ok, info = "") {
   const mark = ok ? pc.green("✓") : pc.red("✗");
@@ -99,6 +100,28 @@ export async function doctor({ cwd, kitVersion }) {
     }
   }
 
+  // 5. Model pin in .claude/settings.json (B4). Catches obvious typos
+  // that would silently no-op in Claude Code.
+  const settingsPath = resolve(cwd, ".claude/settings.json");
+  if (existsSync(settingsPath)) {
+    try {
+      const s = JSON.parse(await readFile(settingsPath, "utf8"));
+      if (typeof s.model === "string" && s.model.length > 0) {
+        if (SUPPORTED_MODELS.has(s.model)) {
+          check(`model pin (${s.model})`, true);
+        } else {
+          allOk = false;
+          console.log(
+            pc.red(`  ✗ model pin in .claude/settings.json — "${s.model}" not recognized.`),
+          );
+          console.log(
+            pc.dim(`    Known: ${[...SUPPORTED_MODELS].join(", ")}. Re-run \`agent-harness-kit init --model <id>\`.`),
+          );
+        }
+      }
+    } catch { /* covered by settings parse check elsewhere */ }
+  }
+
   console.log("");
   if (!allOk) {
     process.exit(1);

package/src/core/render-templates.mjs

@@ -23,7 +23,7 @@ const TEMPLATES_ROOT = resolve(__dirname, "..", "templates");
 // Files that the user is expected to edit — they win every time, even on
 // fresh init we won't overwrite if they exist. This list is hard-coded
 // because it's tiny and security-sensitive.
-const USER_OWNED_FILES = new Set([
+export const USER_OWNED_FILES = new Set([
   "CLAUDE.md",
   "AGENTS.md",
   "docs/architecture.md",
@@ -35,7 +35,7 @@ const USER_OWNED_FILES = new Set([
 ]);
 
 // Paths that should be made executable after rendering.
-const EXEC_BITS = new Set([
+export const EXEC_BITS = new Set([
   "scripts/dev-up.sh",
   "scripts/pre-push.sh",
   "scripts/install-git-hooks.sh",
@@ -43,6 +43,11 @@ const EXEC_BITS = new Set([
   "scripts/precompletion-checklist.sh",
   "scripts/telemetry-on-skill.sh",
   "scripts/harness-report.mjs",
+  // v0.7 hook expansion — SessionStart / PreToolUse / PreCompact / SessionEnd.
+  "scripts/session-start.sh",
+  "scripts/pretooluse-bash-guard.sh",
+  "scripts/pre-compact.sh",
+  "scripts/session-end.sh",
 ]);
 
 export function registerHelpers() {
@@ -86,11 +91,33 @@ async function* walk(dir) {
   }
 }
 
-function buildContext({ projectName, preset, layers, stack, kitVersion }) {
+// SUPPORTED_LANGS — human-language variants the kit ships for CLAUDE.md.
+// Adding a new locale: drop `CLAUDE.md.<code>.hbs` alongside the English
+// CLAUDE.md.hbs, add the code here, and the picker in pathForStack()
+// will route it. Default is "en" → uses the suffix-less CLAUDE.md.hbs.
+export const SUPPORTED_HUMAN_LANGS = new Set(["en", "vi"]);
+
+// SUPPORTED_MODELS — IDs the kit accepts via `--model` and writes verbatim
+// into `.claude/settings.json#model`. The kit does NOT try to be a model
+// registry — it just rejects obvious typos before they silently no-op in
+// Claude Code (which falls back to the org default on unknown IDs).
+export const SUPPORTED_MODELS = new Set([
+  "claude-opus-4-7",
+  "claude-sonnet-4-6",
+  "claude-haiku-4-5",
+  // Legacy IDs we still accept on upgrade paths.
+  "claude-sonnet-4-5",
+  "claude-haiku-3-5",
+]);
+export const DEFAULT_MODEL = "claude-sonnet-4-6";
+
+export function buildContext({ projectName, preset, layers, stack, kitVersion, humanLanguage, model }) {
   const installCmd = (() => {
     if (stack.language === "python") return "pip install -e '.[dev]'";
     if (stack.language === "go") return "go mod download";
     if (stack.language === "rust") return "cargo build";
+    if (stack.language === "swift") return "swift package resolve";
+    if (stack.language === "kotlin") return "./gradlew build --refresh-dependencies";
     if (stack.packageManager === "pnpm") return "pnpm install";
     if (stack.packageManager === "yarn") return "yarn";
     if (stack.packageManager === "bun") return "bun install";
@@ -109,6 +136,8 @@ function buildContext({ projectName, preset, layers, stack, kitVersion }) {
         if (stack.language === "python") return "python -m app";
         if (stack.language === "go") return "go run ./cmd/...";
         if (stack.language === "rust") return "cargo run";
+        if (stack.language === "swift") return "swift run";
+        if (stack.language === "kotlin") return "./gradlew run";
         return "npm run dev";
     }
   })();
@@ -119,6 +148,8 @@ function buildContext({ projectName, preset, layers, stack, kitVersion }) {
         if (stack.language === "python") return "pytest -x";
         if (stack.language === "go") return "go test ./...";
         if (stack.language === "rust") return "cargo test";
+        if (stack.language === "swift") return "swift test";
+        if (stack.language === "kotlin") return "./gradlew test";
         return "npm test";
     }
   })();
@@ -126,6 +157,8 @@ function buildContext({ projectName, preset, layers, stack, kitVersion }) {
     if (stack.language === "python") return "ruff check .";
     if (stack.language === "go") return "go vet ./...";
     if (stack.language === "rust") return "cargo clippy --all-targets -- -D warnings";
+    if (stack.language === "swift") return "swift build --warnings-as-errors";
+    if (stack.language === "kotlin") return "./gradlew detekt || ./gradlew lint";
     return "npm run lint";
   })();
 
@@ -144,10 +177,14 @@ function buildContext({ projectName, preset, layers, stack, kitVersion }) {
     testCmd,
     lintCmd,
     kitVersion,
+    humanLanguage: humanLanguage || "en",
+    model: model || DEFAULT_MODEL,
     isTypescript: stack.language === "typescript",
     isPython: stack.language === "python",
     isGo: stack.language === "go",
     isRust: stack.language === "rust",
+    isSwift: stack.language === "swift",
+    isKotlin: stack.language === "kotlin",
     isNextjs: stack.framework === "nextjs",
     isFastapi: stack.framework === "fastapi",
     isExpress: stack.framework === "express",
@@ -161,7 +198,18 @@ function buildContext({ projectName, preset, layers, stack, kitVersion }) {
 // Decide whether a template path should be rendered for this stack/preset.
 // Adapter-specific files live under templates/_adapter-<id>/ and are merged
 // into the root.
-function pathForStack(rel, stack) {
+export function pathForStack(rel, stack, humanLanguage = "en") {
+  // CLAUDE.md locale routing. `CLAUDE.md.hbs` (no language suffix) is the
+  // English default. `CLAUDE.md.<lang>.hbs` is rendered into the same
+  // target path (`CLAUDE.md`) when the user picks that locale. The
+  // suffixed file is skipped otherwise — and so is the unsuffixed file
+  // when a non-default locale is active, so only one variant lands.
+  if (/^CLAUDE\.md(?:\.[a-z]{2,5})?\.hbs$/.test(rel)) {
+    const m = rel.match(/^CLAUDE\.md(?:\.([a-z]{2,5}))?\.hbs$/);
+    const fileLang = m[1] || "en";
+    if (fileLang !== humanLanguage) return null;
+    return "CLAUDE.md.hbs"; // canonical target — strip locale suffix
+  }
   if (rel.startsWith("_adapter-typescript/")) {
     const stripped = rel.slice("_adapter-typescript/".length);
     if (stack.language === "typescript") return stripped;
@@ -184,6 +232,16 @@ function pathForStack(rel, stack) {
   if (rel.startsWith("_adapter-rust/")) {
     return stack.language === "rust" ? rel.slice("_adapter-rust/".length) : null;
   }
+  if (rel.startsWith("_adapter-swift/")) {
+    const stripped = rel.slice("_adapter-swift/".length);
+    if (stack.language === "swift") return stripped;
+    return null;
+  }
+  if (rel.startsWith("_adapter-kotlin/")) {
+    const stripped = rel.slice("_adapter-kotlin/".length);
+    if (stack.language === "kotlin") return stripped;
+    return null;
+  }
   if (rel.startsWith("_preset-nextjs/")) {
     return stack.framework === "nextjs" ? rel.slice("_preset-nextjs/".length) : null;
   }
@@ -200,6 +258,101 @@ function sha256(buf) {
   return createHash("sha256").update(buf).digest("hex");
 }
 
+// Inject a statusLine block into .claude/settings.json. Idempotent: if the
+// existing statusLine already references the kit's script, leave it; otherwise
+// set it to invoke scripts/statusline.mjs via node. Doesn't clobber a
+// user-customised type:"command" entry that points at a different command.
+//
+// Returns {changed, rawContent} for the lockfile bookkeeping (mirrors the
+// mergeHooksIntoSettings contract).
+export async function mergeStatusLineIntoSettings(cwd) {
+  const settingsPath = resolve(cwd, ".claude/settings.json");
+  const scriptPath = resolve(cwd, "scripts/statusline.mjs");
+  if (!existsSync(scriptPath)) return { changed: false, rawContent: "" };
+  let settings = {};
+  let raw = "";
+  if (existsSync(settingsPath)) {
+    raw = await readFile(settingsPath, "utf8");
+    try {
+      settings = JSON.parse(raw);
+    } catch {
+      throw new Error(
+        `mergeStatusLineIntoSettings: ${settingsPath} is not valid JSON`,
+      );
+    }
+  }
+  const desired = {
+    type: "command",
+    command: "node scripts/statusline.mjs",
+  };
+  // Preserve a user-customised entry if it already points elsewhere. We only
+  // inject when statusLine is absent OR explicitly references our script.
+  const cur = settings.statusLine;
+  if (
+    cur &&
+    typeof cur === "object" &&
+    cur.type === "command" &&
+    typeof cur.command === "string" &&
+    !/statusline\.mjs/.test(cur.command)
+  ) {
+    return { changed: false, rawContent: Buffer.from(raw) };
+  }
+  if (
+    cur &&
+    typeof cur === "object" &&
+    cur.type === desired.type &&
+    cur.command === desired.command
+  ) {
+    return { changed: false, rawContent: Buffer.from(raw) };
+  }
+  settings.statusLine = desired;
+  const out = JSON.stringify(settings, null, 2) + "\n";
+  await writeFile(settingsPath, out);
+  return { changed: true, rawContent: Buffer.from(out) };
+}
+
+// Merge .claude/hooks/hooks.json#hooks into .claude/settings.json#hooks.
+// Claude Code only reads hooks from settings.json — a free-standing
+// hooks.json is ignored by the runtime. Kept as a file because the plugin
+// install path references it via .claude-plugin/plugin.json. Idempotent:
+// re-running produces the same settings.json bytes when source hasn't
+// changed. Returns {changed, rawContent} for the lockfile.
+export async function mergeHooksIntoSettings(cwd) {
+  const settingsPath = resolve(cwd, ".claude/settings.json");
+  const hooksPath = resolve(cwd, ".claude/hooks/hooks.json");
+  const hooksRaw = await readFile(hooksPath, "utf8");
+  let hooksJson;
+  try {
+    hooksJson = JSON.parse(hooksRaw);
+  } catch (e) {
+    throw new Error(`mergeHooksIntoSettings: invalid JSON in ${hooksPath}: ${e.message}`);
+  }
+  if (!hooksJson.hooks || typeof hooksJson.hooks !== "object") {
+    return { changed: false, rawContent: "" };
+  }
+  let settings = {};
+  if (existsSync(settingsPath)) {
+    const raw = await readFile(settingsPath, "utf8");
+    try {
+      settings = JSON.parse(raw);
+    } catch {
+      // Corrupt settings.json — refuse to clobber user edits. Surface clearly.
+      throw new Error(`mergeHooksIntoSettings: ${settingsPath} is not valid JSON`);
+    }
+    // Idempotency: if hooks key already matches source verbatim, nothing to do.
+    if (
+      settings.hooks &&
+      JSON.stringify(settings.hooks) === JSON.stringify(hooksJson.hooks)
+    ) {
+      return { changed: false, rawContent: Buffer.from(raw) };
+    }
+  }
+  settings.hooks = hooksJson.hooks;
+  const out = JSON.stringify(settings, null, 2) + "\n";
+  await writeFile(settingsPath, out);
+  return { changed: true, rawContent: Buffer.from(out) };
+}
+
 export async function renderAll({
   cwd,
   projectName,
@@ -209,9 +362,21 @@ export async function renderAll({
   installHooks,
   installCi,
   kitVersion,
+  humanLanguage = "en",
+  model,
 }) {
   registerHelpers();
-  const ctx = buildContext({ projectName, preset, layers, stack, kitVersion });
+  if (!SUPPORTED_HUMAN_LANGS.has(humanLanguage)) {
+    throw new Error(
+      `Unsupported humanLanguage "${humanLanguage}". Supported: ${[...SUPPORTED_HUMAN_LANGS].join(", ")}`,
+    );
+  }
+  if (model && !SUPPORTED_MODELS.has(model)) {
+    throw new Error(
+      `Unsupported model "${model}". Supported: ${[...SUPPORTED_MODELS].join(", ")}`,
+    );
+  }
+  const ctx = buildContext({ projectName, preset, layers, stack, kitVersion, humanLanguage, model });
 
   const written = [];
   const skipped = [];
@@ -219,7 +384,7 @@ export async function renderAll({
 
   for await (const abs of walk(TEMPLATES_ROOT)) {
     const relFromTemplates = relative(TEMPLATES_ROOT, abs).split("\\").join("/");
-    const stackRel = pathForStack(relFromTemplates, stack);
+    const stackRel = pathForStack(relFromTemplates, stack, humanLanguage);
     if (stackRel === null) continue;
     if (relFromTemplates.startsWith("_ci/") && !installCi) continue;
     if (relFromTemplates.includes("hooks.json") && !installHooks) continue;
@@ -258,6 +423,33 @@ export async function renderAll({
     written.push(targetRel);
   }
 
+  // Critical fix (v0.7): merge .claude/hooks/hooks.json into
+  // .claude/settings.json#hooks. Claude Code ONLY reads hooks from
+  // settings.json — a free-standing .claude/hooks/hooks.json is ignored.
+  // Pre-v0.7 the kit silently no-op'd every hook on the scaffold path
+  // because it shipped only the free-standing file. Plugin install path
+  // continues to read .claude/hooks/hooks.json (per plugin.json manifest)
+  // so the file is kept; we just additionally inject it where Claude Code
+  // actually looks.
+  if (installHooks && existsSync(resolve(cwd, ".claude/hooks/hooks.json"))) {
+    const merged = await mergeHooksIntoSettings(cwd);
+    if (merged.changed) {
+      lockfile.files[".claude/settings.json"] = sha256(merged.rawContent);
+      written.push(".claude/settings.json (merged hooks)");
+    }
+  }
+
+  // v0.8 — statusLine injection. Runs after hook merge so the lockfile
+  // captures the final settings.json bytes. Idempotent; never clobbers a
+  // user-customised entry that points elsewhere.
+  if (existsSync(resolve(cwd, "scripts/statusline.mjs"))) {
+    const stat = await mergeStatusLineIntoSettings(cwd);
+    if (stat.changed) {
+      lockfile.files[".claude/settings.json"] = sha256(stat.rawContent);
+      written.push(".claude/settings.json (statusLine)");
+    }
+  }
+
   // Write the lockfile last (after we know the full set of files).
   const lockTarget = resolve(cwd, ".harness/installed.json");
   await mkdir(dirname(lockTarget), { recursive: true });

package/src/templates/.claude/hooks/hooks.json

@@ -0,0 +1,111 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-hooks.json",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash scripts/session-start.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash scripts/userprompt-guard.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash scripts/pretooluse-bash-guard.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Notification": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash scripts/notify-on-block.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash scripts/structural-test-on-edit.sh",
+            "timeout": 30
+          }
+        ]
+      },
+      {
+        "matcher": "Skill",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash scripts/telemetry-on-skill.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash scripts/pre-compact.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash scripts/precompletion-checklist.sh",
+            "timeout": 20
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash scripts/session-end.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/src/templates/.claude/settings.json.hbs

@@ -21,7 +21,7 @@
       "Bash(command -v:*)"
     ]
   },
-  "model": "{{#if isPython}}claude-sonnet-4-6{{else}}claude-sonnet-4-6{{/if}}",
+  "model": "{{model}}",
   "env": {
     "AGENT_HARNESS_KIT_VERSION": "{{kitVersion}}"
   }

package/src/templates/.claude/skills/doc-drift-scan/SKILL.md

@@ -1,20 +1,25 @@
 ---
 name: doc-drift-scan
 description: Use this skill weekly, before releases, or when the user mentions "stale docs", "doc drift", "docs are wrong", or "the README is out of date". Cross-checks every code path, file path, and command referenced in `docs/` and `CLAUDE.md` against the current repo state and produces a list of stale references — the doc-gardening agent pattern.
-allowed-tools: Read, Glob, Grep, Bash(test -e:*), Bash(command -v:*)
-suggested-turns: 12
+allowed-tools: Read, Glob, Grep, Bash(test -e:*), Bash(command -v:*), Bash(node .claude/skills/doc-drift-scan/scripts/scan-paths.mjs:*)
+suggested-turns: 8
 ---
 
 ## Steps
 
-1. **Extract references.** From `docs/**/*.md` and `CLAUDE.md`, extract:
-   - Backtick paths matching `[a-z0-9_/.\\-]+\\.(md|ts|tsx|js|py|json|yml|yaml|sh)`
-   - Backtick commands (first token after a backtick).
-   - Markdown links to local files (`./...` or `../...`).
-2. **Validate each.**
-   - Paths: `test -e <path>`. If missing, mark as drift.
-   - Commands: `command -v <cmd>`. If not on PATH, mark as drift (but allow
-     a configured allowlist for known optional tools).
+1. **Extract references + validate (deterministic).** Run the side-car
+   script — walks `docs/**/*.md` + `CLAUDE.md`, extracts every backtick-path
+   containing a slash, checks `existsSync` per ref:
+
+   ```bash
+   node .claude/skills/doc-drift-scan/scripts/scan-paths.mjs
+   ```
+
+   Read the JSON: `{ stats: { docs_scanned, refs_found, refs_missing },
+   drift: [{ doc, ref }] }`. Replaces three LLM grep turns.
+2. **Validate commands (LLM judgment, narrow).** Optional second pass for
+   backtick-commands the side-car doesn't classify (no slash → not a path).
+   Use `command -v <cmd>` and allow a small allowlist (`jq`, `gh`, `rg`).
 3. **Group findings.**
    - `missing-paths`: file moved or deleted.
    - `wrong-layer-claim`: doc says module is in layer X, structural test