pan-wizard 3.7.10 → 3.8.0

package/README.md

@@ -451,6 +451,24 @@ The orchestrator never does heavy lifting. It spawns agents, waits, integrates r
 
 **The result:** You can run an entire phase — deep research, multiple plans created and verified, thousands of lines of code written across parallel executors, automated verification against goals — and your main context window stays at 30-40%. The work happens in fresh subagent contexts. Your session stays fast and responsive.
 
+### Reasoning-Trace Handoff
+
+When agents hand work off via files, only OUTPUTS get passed by default — not the reasoning that produced them. Per Cognition's "Don't build multi-agents" research (June 2025), silent decisions force downstream agents to reconcile contradictions blindly. PAN passes the reasoning explicitly:
+
+- Plans carry a `## Plan Decisions` section (Locked / Open / Considered+rejected buckets) — the executor reads it before coding so it doesn't re-argue settled choices.
+- Summaries carry an `## Implementation Decisions` section — the verifier reads it to understand WHY the executor deviated from the plan, not just THAT it did.
+
+The plan-checker enforces this with two dedicated dimensions (Spec Sufficiency for Handoff, Decision Trace Completeness). Schema lives in `pan-wizard-core/references/handoff-decisions.md`.
+
+### Self-Improving Learnings
+
+PAN runs autonomous experiments in isolated folders, harvests the resulting telemetry, and promotes generalizable findings into a shipped patterns store at `pan-wizard-core/learnings/`:
+
+- `learnings/universal/<topic>.md` — patterns that ship to every install (atomic-state, concurrency, idempotency, secret-handling, test-patterns, …). Loaded by planner / executor / verifier agents during their work.
+- `learnings/internal/<topic>.md` — PAN-development patterns; source-only (stripped at install).
+- `learnings/index.json` — topic→agent-relevance map. Workflows call `pan-tools learn topics-for --agent <role> --token-budget N` to load only relevant patterns instead of skim-everything (avoids the distractor-density anti-pattern).
+- `pan-tools learn lint` — integrity check (duplicate IDs, dangling refs, scope leaks). Wired into `/check`.
+
 ### Atomic Git Commits
 
 Each task gets its own commit immediately after completion:
@@ -553,7 +571,8 @@ PAN is not a replacement for your IDE or AI agent — it's the orchestration lay
 | `/pan:todo-check` | List pending todos |
 | `/pan:debug [desc]` | Systematic debugging with persistent state |
 | `/pan:quick [--full]` | Execute ad-hoc task with PAN guarantees (`--full` adds plan-checking and verification) |
-| `/pan:health [--repair] [--standards]` | Validate `.planning/` directory integrity, auto-repair with `--repair`, standards compliance with `--standards` |
+| `/pan:health [--repair] [--standards] [--full] [--drift] [--links]` | Validate `.planning/` directory integrity. `--repair` auto-fixes; `--standards` checks compliance; `--full` runs tests + build; `--drift` runs convention drift; `--links` attaches doc-code link-graph summary |
+| `/pan:links [--strict]` | Validate the doc-code link graph: inline `[[<id>]]` refs, `// @pan:` source anchors, `require-code-mention` contracts (ADR-0027, v3.8.0+) |
 | `/pan:phase-tests [N]` | Generate tests for a completed phase based on UAT criteria |
 | `/pan:milestone-cleanup` | Archive accumulated phase directories from completed milestones |
 | `/pan:retro` | Milestone retrospective — estimation accuracy, verification patterns, gap analysis |

package/commands/pan/links.md

@@ -0,0 +1,102 @@
+---
+name: pan:links
+group: Validation
+description: Validate the doc-code link graph — inline wiki-style refs, source-comment anchors, and require-code-mention contracts (ADR-0027, v3.8.0+)
+allowed-tools:
+  - Bash
+  - Read
+  - Grep
+---
+
+# /pan:links
+
+Validate the doc-code link graph. Walks `docs/`, `pan-wizard-core/`, `commands/`, and `agents/` for inline `[[<id>]]` references and `// @pan: <id>` source-comment anchors. Reports broken refs, stale anchors, and uncovered backlink contracts.
+
+**Usage:**
+```
+/pan:links
+/pan:links --strict
+/pan:links --doc-root <path> [--doc-root <path>...]
+/pan:links --source-root <path> [--source-root <path>...]
+```
+
+**Flags:**
+- `--strict` — fail (exit 1) on warnings, not only errors. Default is advisory: warnings do not flip status.
+- `--doc-root <path>` — override default doc roots. Repeatable.
+- `--source-root <path>` — override default source roots. Repeatable.
+- `--raw` — human-readable output instead of JSON.
+
+**What it does:**
+
+Three sequential passes share one walk pair:
+
+1. **Forward links** — every `[[<id>]]` in body text and every `must_haves.key_links` entry must resolve. Section anchors (`[[ADR-0021#Decision]]`) check that the named heading exists.
+2. **Backlink contract** — docs with `require-code-mention: true` in frontmatter must have at least one `@pan:` source anchor that resolves to them.
+3. **Anchor-target existence** — every `// @pan: <id>` comment must point to a real doc.
+
+**Doc-id forms accepted:**
+
+- `ADR-NNNN` — resolves via glob to `docs/decisions/ADR-NNNN-*.md`
+- `<path>.md` — exact path relative to repo root
+- `<path>` (no extension) — tries `<path>.md` then `<path>/README.md`
+- Any of the above with `#section` — verifies a heading whose slug matches
+
+**Source-anchor grammar:**
+
+```
+// @pan: ADR-0027         (JS / TS / CJS)
+# @pan: ADR-0027          (Python / shell)
+<!-- @pan: ADR-0027 -->   (Markdown / HTML)
+```
+
+Anchors cluster at the top of a file under a single banner; comment leader must be the line's first non-whitespace token.
+
+**Exit codes:**
+
+- `0` — pass
+- `1` — fail (errors present, or warnings present under `--strict`)
+
+**Output (JSON):**
+
+```json
+{
+  "ok": true,
+  "summary": {
+    "total_findings": 0,
+    "errors": 0,
+    "warnings": 0,
+    "status": "pass",
+    "doc_files_scanned": 280,
+    "source_files_scanned": 170,
+    "anchors_found": 4,
+    "forward_links_found": 12,
+    "backlink_contracts_checked": 3
+  },
+  "findings": []
+}
+```
+
+**Finding codes:**
+
+| Code | Severity | Meaning |
+|---|---|---|
+| F-001 | error | Inline `[[<id>]]` does not resolve |
+| F-002 | error | `[[<doc>#<section>]]` resolves the file but the section is missing |
+| F-003 | warning | `must_haves.key_links` entry's `from` or `to` does not exist |
+| F-004 | warning | `must_haves.key_links` regex pattern is invalid |
+| B-001 | error | Doc has `require-code-mention: true` but no `@pan:` anchors resolve to it |
+| B-002 | warning | Doc is anchored by exactly one source file (single-source informational) |
+| A-001 | error | `@pan:` anchor target does not resolve |
+| A-002 | warning | `@pan:` anchor section is missing in the resolved file |
+| A-004 | warning | `@pan:` anchor has empty id |
+
+**Composing with `validate health`:**
+
+`validate health --links` includes the link-graph summary as a `link_graph` field in the health report. Used as a pre-flight check before release. Errors degrade the health report to a warning-level issue (`LINKS_ERR`); non-blocking unless `--strict` is added to a separate `links validate` invocation.
+
+**See also:**
+
+- ADR-0027 — Doc–Code Link Graph
+- `docs/specs/doc_code_link_graph_featureai.md` — wire-level spec
+- `pan-tools doc-lint` — frontmatter schema validator (orthogonal concern)
+- `pan-tools verify-key-links` — legacy frontmatter-only link verifier (subsumed; both still ship)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pan-wizard",
-  "version": "3.7.10",
+  "version": "3.8.0",
   "description": "A lightweight workflow automation and context engineering system for Claude Code, OpenCode, Gemini CLI, Codex, and Copilot CLI.",
   "bin": {
     "pan-wizard": "bin/install.js"
@@ -51,7 +51,7 @@
   "devDependencies": {
     "@playwright/test": "^1.58.2",
     "@vscode/test-electron": "^2.5.2",
-    "esbuild": "^0.24.0"
+    "esbuild": "^0.28.0"
   },
   "scripts": {
     "build:hooks": "node scripts/build-hooks.js",

package/pan-wizard-core/bin/lib/codebase.cjs

@@ -5,6 +5,8 @@
  * Supports JS/TS (v0), with extensible language registry for Python/Go/Rust/Java/C# (v1).
  */
 
+// @pan: ADR-0021
+
 const fs = require('fs');
 const path = require('path');
 const { CODEBASE_DIR, DRIFT_MAX_FILE_SIZE } = require('./constants.cjs');

package/pan-wizard-core/bin/lib/experiment.cjs

@@ -1,4 +1,5 @@
 'use strict';
+// @pan: ADR-0026
 /**
  * experiment.cjs — Self-improvement loop W1: experiment scaffolding.
  *

package/pan-wizard-core/bin/lib/links.cjs

@@ -0,0 +1,549 @@
+'use strict';
+// @pan: ADR-0027
+/**
+ * Links — Doc–Code link graph scanner and lint.
+ *
+ * Implements ADR-0027 (Doc–Code Link Graph).
+ * Spec: docs/specs/doc_code_link_graph_featureai.md
+ *
+ * Three lint passes share one walk pair:
+ *   - Forward links: inline [[<id>]] in body + must_haves.key_links in frontmatter.
+ *   - Backlink contract: docs with `require-code-mention: true` must have at
+ *     least one resolving @pan: anchor.
+ *   - Anchor-target existence: every @pan: anchor must resolve to a real doc.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { safeReadFile, toPosix, output } = require('./core.cjs');
+const { extractFrontmatter, parseMustHavesBlock } = require('./frontmatter.cjs');
+const { walkMarkdownFiles } = require('./doc-lint/walk.js');
+
+const DEFAULT_DOC_ROOTS = [
+  'docs',
+  'pan-wizard-core/workflows',
+  'pan-wizard-core/templates',
+  'pan-wizard-core/references',
+  'pan-wizard-core/learnings',
+  'commands',
+  'agents',
+];
+
+const DEFAULT_SOURCE_ROOTS = [
+  'pan-wizard-core',
+  'bin',
+  'hooks',
+  'scripts',
+];
+
+const SOURCE_EXT_TO_LEADER = {
+  '.cjs':  '//',
+  '.js':   '//',
+  '.mjs':  '//',
+  '.ts':   '//',
+  '.sh':   '#',
+  '.py':   '#',
+  '.ps1':  '#',
+  '.md':   '<!--',
+  '.html': '<!--',
+};
+
+const ANCHOR_RES = {
+  '//':   /^\s*\/\/\s*@pan:\s*([^\s].*?)\s*$/,
+  '#':    /^\s*#\s*@pan:\s*([^\s].*?)\s*$/,
+  '<!--': /^\s*<!--\s*@pan:\s*([^\s].*?)\s*(?:-->)?\s*$/,
+};
+
+const INLINE_LINK_RE = /\[\[([^\[\]\s|][^\[\]]*?)\]\]/g;
+const ADR_SHORT_RE = /^ADR-(\d{4})$/i;
+
+const SKIP_DIR_NAMES = new Set(['node_modules', '.git', 'dist', '.cache', 'coverage']);
+
+// ─── Doc-id resolver ─────────────────────────────────────────────────────────
+
+function slugify(s) {
+  return String(s).toLowerCase().replace(/\s+/g, '-').replace(/[^a-z0-9-]/g, '');
+}
+
+function fileHasSection(filePath, section) {
+  const content = safeReadFile(filePath);
+  if (!content) return false;
+  const target = slugify(section);
+  const lines = content.split('\n');
+  for (const line of lines) {
+    const m = line.match(/^#{1,6}\s+(.+?)\s*$/);
+    if (m && slugify(m[1]) === target) return true;
+  }
+  return false;
+}
+
+function resolveDocId(rawId, cwd) {
+  if (!rawId || !rawId.trim()) return { resolved: false, reason: 'empty id' };
+  let id = rawId.trim();
+  let section = null;
+  const hashIdx = id.indexOf('#');
+  if (hashIdx !== -1) {
+    section = id.slice(hashIdx + 1).trim();
+    id = id.slice(0, hashIdx).trim();
+  }
+
+  // ADR-NNNN shortcut → glob docs/decisions/ADR-NNNN-*.md
+  const adrMatch = id.match(ADR_SHORT_RE);
+  if (adrMatch) {
+    const num = adrMatch[1];
+    const decisionsDir = path.join(cwd, 'docs', 'decisions');
+    let entries = [];
+    try {
+      entries = fs.readdirSync(decisionsDir);
+    } catch {
+      return { resolved: false, reason: 'docs/decisions/ not found' };
+    }
+    const candidates = entries.filter(f =>
+      f.toLowerCase().startsWith(`adr-${num}-`) && f.endsWith('.md')
+    );
+    if (candidates.length === 0) {
+      return { resolved: false, reason: `no ADR-${num}-*.md found` };
+    }
+    if (candidates.length > 1) {
+      return { resolved: false, reason: `ambiguous ADR-${num}: ${candidates.join(', ')}` };
+    }
+    const relPath = toPosix(path.join('docs', 'decisions', candidates[0]));
+    if (section) {
+      const fullPath = path.join(cwd, 'docs', 'decisions', candidates[0]);
+      if (fileHasSection(fullPath, section)) {
+        return { resolved: true, path: relPath, section };
+      }
+      return { resolved: true, path: relPath, section, sectionMissing: true };
+    }
+    return { resolved: true, path: relPath };
+  }
+
+  // Direct .md path
+  if (id.endsWith('.md')) {
+    const fullPath = path.join(cwd, id);
+    try { fs.accessSync(fullPath); }
+    catch { return { resolved: false, reason: `${id} not found` }; }
+    if (section) {
+      if (fileHasSection(fullPath, section)) {
+        return { resolved: true, path: toPosix(id), section };
+      }
+      return { resolved: true, path: toPosix(id), section, sectionMissing: true };
+    }
+    return { resolved: true, path: toPosix(id) };
+  }
+
+  // Try <id>.md, then <id>/README.md
+  const candidates = [`${id}.md`, path.join(id, 'README.md')];
+  for (const cand of candidates) {
+    const fullPath = path.join(cwd, cand);
+    try {
+      fs.accessSync(fullPath);
+      const relCand = toPosix(cand);
+      if (section) {
+        if (fileHasSection(fullPath, section)) {
+          return { resolved: true, path: relCand, section };
+        }
+        return { resolved: true, path: relCand, section, sectionMissing: true };
+      }
+      return { resolved: true, path: relCand };
+    } catch { /* try next */ }
+  }
+  return { resolved: false, reason: `${id} (tried ${id}.md and ${id}/README.md)` };
+}
+
+// ─── Forward-link scanner ────────────────────────────────────────────────────
+
+function stripInlineCodeSpans(line) {
+  // Replace `...` spans (and ``...`` etc.) with placeholders so [[...]] inside
+  // backticks is not picked up as a real link.
+  return line.replace(/(`+)([^`]|(?!\1)`)*?\1/g, m => ' '.repeat(m.length));
+}
+
+function parseInlineLinks(text) {
+  const out = [];
+  const lines = text.split('\n');
+  let inFence = false;
+  let fenceMarker = '';
+  let inFrontmatter = false;
+  let frontmatterDone = false;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    // Skip leading YAML frontmatter (--- on line 1, then content, then closing ---).
+    // Only the leading block; subsequent --- in body is unaffected.
+    if (i === 0 && line.trim() === '---') { inFrontmatter = true; continue; }
+    if (inFrontmatter && !frontmatterDone) {
+      if (line.trim() === '---') { inFrontmatter = false; frontmatterDone = true; }
+      continue;
+    }
+    // Toggle fenced-code-block state on lines opening/closing ``` or ~~~
+    const fenceMatch = line.match(/^(\s{0,3})(```+|~~~+)(.*)$/);
+    if (fenceMatch) {
+      const marker = fenceMatch[2];
+      if (!inFence) { inFence = true; fenceMarker = marker[0]; continue; }
+      if (marker[0] === fenceMarker) { inFence = false; fenceMarker = ''; continue; }
+    }
+    if (inFence) continue;
+    const stripped = stripInlineCodeSpans(line);
+    INLINE_LINK_RE.lastIndex = 0;
+    let m;
+    while ((m = INLINE_LINK_RE.exec(stripped)) !== null) {
+      out.push({ rawId: m[1].trim(), line: i + 1 });
+    }
+  }
+  return out;
+}
+
+function safeWalkDocs(rootAbs) {
+  try {
+    return walkMarkdownFiles(rootAbs, { exclude: ['**/node_modules/**'] });
+  } catch {
+    return null;
+  }
+}
+
+function scanForwardLinks(docRoots, cwd) {
+  const out = [];
+  for (const root of docRoots) {
+    const fullDir = path.isAbsolute(root) ? root : path.join(cwd, root);
+    const files = safeWalkDocs(fullDir);
+    if (!files) continue;
+    for (const file of files) {
+      if (file.readError) continue;
+      const relPath = toPosix(path.relative(cwd, file.path));
+      for (const link of parseInlineLinks(file.content)) {
+        out.push({
+          source: relPath,
+          sourceLine: link.line,
+          rawId: link.rawId,
+          via: 'inline',
+        });
+      }
+      try {
+        const keyLinks = parseMustHavesBlock(file.content, 'key_links');
+        for (const link of keyLinks) {
+          if (typeof link === 'string') continue;
+          out.push({
+            source: relPath,
+            sourceLine: 0,
+            rawId: link.to || '',
+            via: 'key_links',
+            from: link.from || '',
+            pattern: link.pattern || '',
+          });
+        }
+      } catch { /* malformed frontmatter — skip */ }
+    }
+  }
+  return out;
+}
+
+// ─── Source-anchor scanner ───────────────────────────────────────────────────
+
+function leaderForFile(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  return SOURCE_EXT_TO_LEADER[ext] || null;
+}
+
+function parseAnchorLine(line, leader) {
+  const re = ANCHOR_RES[leader];
+  if (!re) return null;
+  const m = line.match(re);
+  return m ? m[1].trim() : null;
+}
+
+function walkSourceFiles(rootDir, out) {
+  let entries;
+  try {
+    entries = fs.readdirSync(rootDir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      if (SKIP_DIR_NAMES.has(entry.name)) continue;
+      walkSourceFiles(path.join(rootDir, entry.name), out);
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    const leader = leaderForFile(entry.name);
+    if (!leader) continue;
+    out.push({ path: path.join(rootDir, entry.name), leader });
+  }
+}
+
+function scanAnchors(sourceRoots, cwd) {
+  const out = [];
+  const files = [];
+  for (const root of sourceRoots) {
+    const fullDir = path.isAbsolute(root) ? root : path.join(cwd, root);
+    walkSourceFiles(fullDir, files);
+  }
+  for (const { path: fp, leader } of files) {
+    const content = safeReadFile(fp);
+    if (!content) continue;
+    const lines = content.split('\n');
+    const relPath = toPosix(path.relative(cwd, fp));
+    for (let i = 0; i < lines.length; i++) {
+      const id = parseAnchorLine(lines[i], leader);
+      if (id !== null) {
+        out.push({ source: relPath, sourceLine: i + 1, rawId: id, leader });
+      }
+    }
+  }
+  return out;
+}
+
+// ─── Lint passes ─────────────────────────────────────────────────────────────
+
+function runForwardPass(forwardLinks, cwd) {
+  const findings = [];
+  for (const link of forwardLinks) {
+    if (link.via === 'inline') {
+      const r = resolveDocId(link.rawId, cwd);
+      if (!r.resolved) {
+        findings.push({
+          code: 'F-001',
+          severity: 'error',
+          source: link.source,
+          source_line: link.sourceLine,
+          target: link.rawId,
+          detail: r.reason || 'unresolved',
+        });
+      } else if (r.sectionMissing) {
+        findings.push({
+          code: 'F-002',
+          severity: 'error',
+          source: link.source,
+          source_line: link.sourceLine,
+          target: link.rawId,
+          detail: `Section "#${r.section}" not found in ${r.path}`,
+        });
+      }
+      continue;
+    }
+    if (link.via === 'key_links') {
+      if (link.from) {
+        try { fs.accessSync(path.join(cwd, link.from)); }
+        catch {
+          findings.push({
+            code: 'F-003', severity: 'warning',
+            source: link.source, source_line: 0, target: link.from,
+            detail: `key_links.from path does not exist: ${link.from}`,
+          });
+        }
+      }
+      if (link.rawId) {
+        try { fs.accessSync(path.join(cwd, link.rawId)); }
+        catch {
+          findings.push({
+            code: 'F-003', severity: 'warning',
+            source: link.source, source_line: 0, target: link.rawId,
+            detail: `key_links.to path does not exist: ${link.rawId}`,
+          });
+        }
+      }
+      if (link.pattern) {
+        try { new RegExp(link.pattern); }
+        catch (e) {
+          findings.push({
+            code: 'F-004', severity: 'warning',
+            source: link.source, source_line: 0, target: link.rawId,
+            detail: `Invalid regex in key_links.pattern: ${e.message}`,
+          });
+        }
+      }
+    }
+  }
+  return findings;
+}
+
+function runBacklinkPass(docRoots, anchors, cwd) {
+  const findings = [];
+
+  // Index: resolved doc path → array of anchor source files
+  const anchorIdx = new Map();
+  for (const a of anchors) {
+    const r = resolveDocId(a.rawId, cwd);
+    if (!r.resolved) continue;
+    if (!anchorIdx.has(r.path)) anchorIdx.set(r.path, []);
+    anchorIdx.get(r.path).push(a.source);
+  }
+
+  for (const root of docRoots) {
+    const fullDir = path.isAbsolute(root) ? root : path.join(cwd, root);
+    const files = safeWalkDocs(fullDir);
+    if (!files) continue;
+    for (const file of files) {
+      if (file.readError) continue;
+      const fm = extractFrontmatter(file.content);
+      const requireMention = fm['require-code-mention'];
+      if (requireMention !== true && requireMention !== 'true') continue;
+      const relPath = toPosix(path.relative(cwd, file.path));
+      const sources = anchorIdx.get(relPath) || [];
+      if (sources.length === 0) {
+        findings.push({
+          code: 'B-001', severity: 'error',
+          source: relPath, source_line: 0, target: null,
+          detail: 'require-code-mention is true but no @pan: anchors resolve to this doc',
+        });
+        continue;
+      }
+      const unique = new Set(sources);
+      if (unique.size === 1) {
+        findings.push({
+          code: 'B-002', severity: 'warning',
+          source: relPath, source_line: 0, target: [...unique][0],
+          detail: `Only one source file anchors this doc (${[...unique][0]})`,
+        });
+      }
+    }
+  }
+  return findings;
+}
+
+function runAnchorTargetPass(anchors, cwd) {
+  const findings = [];
+  for (const a of anchors) {
+    if (!a.rawId) {
+      findings.push({
+        code: 'A-004', severity: 'warning',
+        source: a.source, source_line: a.sourceLine,
+        target: null, detail: '@pan: anchor has empty id',
+      });
+      continue;
+    }
+    const r = resolveDocId(a.rawId, cwd);
+    if (!r.resolved) {
+      findings.push({
+        code: 'A-001', severity: 'error',
+        source: a.source, source_line: a.sourceLine,
+        target: a.rawId, detail: r.reason || 'unresolved',
+      });
+    } else if (r.sectionMissing) {
+      findings.push({
+        code: 'A-002', severity: 'warning',
+        source: a.source, source_line: a.sourceLine,
+        target: a.rawId,
+        detail: `Section "#${r.section}" not found in ${r.path}`,
+      });
+    }
+  }
+  return findings;
+}
+
+function countBacklinkContracts(docRoots, cwd) {
+  let n = 0;
+  for (const root of docRoots) {
+    const fullDir = path.isAbsolute(root) ? root : path.join(cwd, root);
+    const files = safeWalkDocs(fullDir);
+    if (!files) continue;
+    for (const file of files) {
+      if (file.readError) continue;
+      const fm = extractFrontmatter(file.content);
+      const v = fm['require-code-mention'];
+      if (v === true || v === 'true') n++;
+    }
+  }
+  return n;
+}
+
+function countDocFiles(docRoots, cwd) {
+  let n = 0;
+  for (const root of docRoots) {
+    const fullDir = path.isAbsolute(root) ? root : path.join(cwd, root);
+    const files = safeWalkDocs(fullDir);
+    if (files) n += files.length;
+  }
+  return n;
+}
+
+function countSourceFiles(sourceRoots, cwd) {
+  const acc = [];
+  for (const root of sourceRoots) {
+    const fullDir = path.isAbsolute(root) ? root : path.join(cwd, root);
+    walkSourceFiles(fullDir, acc);
+  }
+  return acc.length;
+}
+
+// ─── Top-level validateAll ───────────────────────────────────────────────────
+
+function validateAll(cwd, opts = {}) {
+  const docRoots = opts.docRoots || DEFAULT_DOC_ROOTS;
+  const sourceRoots = opts.sourceRoots || DEFAULT_SOURCE_ROOTS;
+  const strict = !!opts.strict;
+
+  const forwardLinks = scanForwardLinks(docRoots, cwd);
+  const anchors = scanAnchors(sourceRoots, cwd);
+
+  const findings = [];
+  findings.push(...runForwardPass(forwardLinks, cwd));
+  findings.push(...runBacklinkPass(docRoots, anchors, cwd));
+  findings.push(...runAnchorTargetPass(anchors, cwd));
+
+  const errors = findings.filter(f => f.severity === 'error').length;
+  const warnings = findings.filter(f => f.severity === 'warning').length;
+  // Per spec §5.2: B-002 is informational and does not flip status under --strict.
+  const strictWarnings = findings.filter(f => f.severity === 'warning' && f.code !== 'B-002').length;
+  let status;
+  if (errors > 0) status = 'fail';
+  else if (strict && strictWarnings > 0) status = 'fail';
+  else status = 'pass';
+
+  return {
+    ok: status === 'pass',
+    summary: {
+      total_findings: findings.length,
+      errors,
+      warnings,
+      status,
+      doc_files_scanned: countDocFiles(docRoots, cwd),
+      source_files_scanned: countSourceFiles(sourceRoots, cwd),
+      anchors_found: anchors.length,
+      forward_links_found: forwardLinks.length,
+      backlink_contracts_checked: countBacklinkContracts(docRoots, cwd),
+    },
+    findings,
+  };
+}
+
+function cmdLinksValidate(cwd, opts = {}) {
+  const result = validateAll(cwd, opts);
+  // Bypass core.output() because it unconditionally exits 0; we need exit 1
+  // when status is "fail" so CI / hooks can detect violations.
+  if (opts.raw) {
+    const lines = [
+      `Links: ${result.summary.status.toUpperCase()}`,
+      ``,
+      `Doc files scanned:    ${result.summary.doc_files_scanned}`,
+      `Source files scanned: ${result.summary.source_files_scanned}`,
+      `Forward links:        ${result.summary.forward_links_found}`,
+      `Anchors:              ${result.summary.anchors_found}`,
+      `Backlink contracts:   ${result.summary.backlink_contracts_checked}`,
+      ``,
+      `Errors:   ${result.summary.errors}`,
+      `Warnings: ${result.summary.warnings}`,
+      ``,
+    ];
+    for (const f of result.findings) {
+      const where = f.source_line ? `${f.source}:${f.source_line}` : f.source;
+      lines.push(`[${f.severity.toUpperCase()}] ${f.code} ${where}: ${f.detail}`);
+    }
+    process.stdout.write(lines.join('\n'));
+  } else {
+    process.stdout.write(JSON.stringify(result, null, 2));
+  }
+  process.exit(result.summary.status === 'fail' ? 1 : 0);
+}
+
+module.exports = {
+  validateAll,
+  cmdLinksValidate,
+  scanForwardLinks,
+  scanAnchors,
+  resolveDocId,
+  parseAnchorLine,
+  parseInlineLinks,
+  DEFAULT_DOC_ROOTS,
+  DEFAULT_SOURCE_ROOTS,
+};

package/pan-wizard-core/bin/lib/runner.cjs

@@ -1,4 +1,5 @@
 'use strict';
+// @pan: ADR-0026
 /**
  * runner.cjs — Self-improvement loop W2: external agent runner.
  *

package/pan-wizard-core/bin/lib/verify.cjs

@@ -1215,6 +1215,26 @@ function cmdValidateHealth(cwd, options, raw) {
     }
   }
 
+  // Check 12 (optional): doc-code link graph (ADR-0027)
+  let linkGraphResult;
+  if (options.links) {
+    const links = require('./links.cjs');
+    const r = links.validateAll(cwd);
+    linkGraphResult = {
+      status: r.summary.status,
+      errors: r.summary.errors,
+      warnings: r.summary.warnings,
+      doc_files_scanned: r.summary.doc_files_scanned,
+      source_files_scanned: r.summary.source_files_scanned,
+      anchors_found: r.summary.anchors_found,
+      forward_links_found: r.summary.forward_links_found,
+      backlink_contracts_checked: r.summary.backlink_contracts_checked,
+    };
+    if (r.summary.errors > 0) {
+      addIssue('warning', 'LINKS_ERR', `Link graph has ${r.summary.errors} errors (broken refs or uncovered backlink contracts)`, 'Run pan-tools links validate for details');
+    }
+  }
+
   const result = {
     status,
     errors,
@@ -1230,6 +1250,9 @@ function cmdValidateHealth(cwd, options, raw) {
   if (options.drift) {
     result.drift_status = driftResult;
   }
+  if (options.links) {
+    result.link_graph = linkGraphResult;
+  }
 
   output(result, raw);
 }

package/pan-wizard-core/bin/pan-tools.cjs

@@ -214,6 +214,7 @@ const runner = require('./lib/runner.cjs');
 const docLint = require('./lib/doc-lint.cjs');
 const learnLint = require('./lib/learn-lint.cjs');
 const learnIndex = require('./lib/learn-index.cjs');
+const links = require('./lib/links.cjs');
 
 /**
  * Get the value following a flag in the args array.
@@ -663,7 +664,8 @@ async function main() {
         const standardsFlag = args.includes('--standards');
         const fullFlag = args.includes('--full');
         const driftFlag = args.includes('--drift');
-        verify.cmdValidateHealth(cwd, { repair: repairFlag, standards: standardsFlag, full: fullFlag, drift: driftFlag }, raw);
+        const linksFlag = args.includes('--links');
+        verify.cmdValidateHealth(cwd, { repair: repairFlag, standards: standardsFlag, full: fullFlag, drift: driftFlag, links: linksFlag }, raw);
       } else if (subcommand === 'deployment') {
         verify.cmdValidateDeployment(cwd, raw);
       } else {
@@ -1307,6 +1309,28 @@ async function main() {
       break;
     }
 
+    case 'links': {
+      const subcommand = args[1];
+      if (subcommand === 'validate' || !subcommand) {
+        const collectMulti = (flag) => {
+          const vals = [];
+          for (let i = 0; i < args.length; i++) {
+            if (args[i] === flag && i + 1 < args.length) vals.push(args[i + 1]);
+          }
+          return vals.length ? vals : null;
+        };
+        const opts = {
+          docRoots: collectMulti('--doc-root'),
+          sourceRoots: collectMulti('--source-root'),
+          strict: args.includes('--strict'),
+          raw,
+        };
+        links.cmdLinksValidate(cwd, opts);
+        break;
+      }
+      error(`Unknown links subcommand: ${subcommand}. Available: validate`);
+    }
+
     default:
       error(`Unknown command: ${command}. Run pan-tools without arguments to see available commands.`);
   }

package/scripts/git-hooks/pre-commit

@@ -0,0 +1,40 @@
+#!/bin/sh
+# PAN Wizard pre-commit hook.
+#
+# Runs `gitleaks protect` against staged changes. Blocks the commit if a
+# secret is detected. The PAN allowlists in .gitleaks.toml are honoured.
+#
+# Install once per clone:
+#   cp scripts/git-hooks/pre-commit .git/hooks/pre-commit
+#   chmod +x .git/hooks/pre-commit
+# Or with a symlink (Unix / Git Bash):
+#   ln -sf ../../scripts/git-hooks/pre-commit .git/hooks/pre-commit
+#
+# Bypass for an emergency (creates a paper trail in the commit log):
+#   SKIP_GITLEAKS=1 git commit -m "..."
+#
+# Exit codes:
+#   0  ok — no secrets detected (or gitleaks not installed; we don't block).
+#   1  gitleaks found something — fix the staged change before committing.
+
+set -e
+
+if [ "${SKIP_GITLEAKS:-}" = "1" ]; then
+  echo "[pre-commit] SKIP_GITLEAKS=1 — gitleaks bypassed."
+  exit 0
+fi
+
+if ! command -v gitleaks >/dev/null 2>&1; then
+  echo "[pre-commit] gitleaks not installed — skipping secret scan." >&2
+  echo "[pre-commit] Install with: winget install gitleaks.gitleaks" >&2
+  exit 0
+fi
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+CONFIG="$REPO_ROOT/.gitleaks.toml"
+
+if [ -f "$CONFIG" ]; then
+  exec gitleaks protect --staged --no-banner --redact --config "$CONFIG"
+else
+  exec gitleaks protect --staged --no-banner --redact
+fi