pan-wizard 3.35.0 → 3.37.0

package/docs/specs/deployment_audit_findings_featureai.md

@@ -0,0 +1,243 @@
+# Deployment Integrity & Post-Install Validation — Feature Specification
+
+**Generated:** 2026-03-09
+**Version:** 1.0
+**Status:** Proposed
+**Source:** Deployment audit of d:\pantesting (PAN v2.8.0, Claude Code runtime)
+
+---
+
+## Problem Statement
+
+A real-world deployment audit of PAN Wizard v2.8.0 revealed gaps in installation integrity tracking, post-install guidance, and self-validation tooling. Specifically:
+
+1. **Hook files are not tracked in the manifest.** The 3 hook scripts (`pan-check-update.js`, `pan-context-monitor.js`, `pan-statusline.js`) exist on disk but are absent from `pan-file-manifest.json`. This means user modifications to hooks are invisible during upgrades — `saveLocalPatches()` cannot detect or preserve them, and the update process silently overwrites customized hooks.
+
+2. **No post-install self-validation.** After installation the user gets "Done! Run /pan:new-project" but there is no programmatic way to verify the installation succeeded. If a file copy failed silently, anti-virus quarantined a `.cjs` file, or a partial install occurred, the user discovers it only when a command crashes at runtime.
+
+3. **No built-in deployment audit.** The `/pan:health` command validates `.planning/` state but has zero coverage of the installation itself — core modules, settings.json hook wiring, manifest integrity, and agent/command completeness are never checked. Users who modify PAN files, run partial upgrades, or experience filesystem issues have no diagnostic tool.
+
+4. **`audit-deployment` command has no backing workflow or CLI route.** The new command we created is prompt-only — it relies on the AI reading instructions and executing steps manually. Unlike `/pan:health` which calls `pan-tools.cjs validate health`, there is no `pan-tools.cjs validate deployment` route, making the audit non-deterministic and unrepeatable.
+
+## Demand Evidence
+
+| Evidence Type | Source | Finding |
+|---|---|---|
+| Deployment audit | d:\pantesting | 3 hook files orphaned from manifest — untracked modifications |
+| Deployment audit | d:\pantesting | Fresh install has no self-test mechanism |
+| Code review | install-lib.cjs | `generateManifest()` skips `hooks/` directory entirely |
+| Code review | pan-tools.cjs | `validate health` route exists but no `validate deployment` route |
+| Code review | settings.json | Hook paths are hardcoded strings — no validation they resolve to real files |
+| User workflow | Post-install | Users must manually verify installation by running commands and hoping they work |
+| Upgrade flow | saveLocalPatches() | Hook modifications are silently lost on upgrade since they aren't in the manifest |
+
+## Success Criteria
+
+```
+SC-1: All installed files including hooks are tracked in pan-file-manifest.json with SHA256 hashes
+SC-2: `pan-tools.cjs validate deployment` returns structured JSON with pass/fail for every installation component
+SC-3: Post-install automatically runs a lightweight self-check and reports issues before the "Done!" message
+SC-4: Settings.json hook paths are validated against actual file existence during install and health checks
+SC-5: No regression in existing 1622+ tests
+SC-6: Works across all 5 runtimes (Claude, Gemini, OpenCode, Codex, Copilot)
+SC-7: Audit results are deterministic and reproducible (CLI-driven, not prompt-dependent)
+```
+
+## Competitive Landscape
+
+No competing tool (Aider, Cursor, Cline, Windsurf) has post-install self-validation or deployment auditing. This is brownfield territory.
+
+| Tool | Install Validation | Manifest Tracking | Deployment Audit |
+|---|---|---|---|
+| **PAN Wizard** | None | Partial (no hooks) | None (prompt-only) |
+| **Aider** | pip install + import check | None | None |
+| **Cursor** | Extension marketplace | None | None |
+| **Cline** | Extension marketplace | None | None |
+| **Windsurf** | N/A (SaaS) | N/A | N/A |
+
+## Design
+
+### Architecture
+
+```
+install.js (existing)
+  └─ NEW: runPostInstallValidation(configDir, runtime)
+       ├─ verifyAllManifestFiles(configDir)
+       ├─ verifySettingsHookPaths(configDir, runtime)
+       └─ output summary or warnings
+
+pan-tools.cjs → 'validate' → 'deployment' case (NEW)
+  └─ verify.cjs: cmdValidateDeployment(cwd, raw, args)
+       ├─ loadManifest(configDir)
+       ├─ verifyAllHashes(configDir, manifest)
+       ├─ findOrphanedFiles(configDir, manifest)
+       ├─ verifySettingsIntegrity(configDir, runtime)
+       ├─ verifyAgentCompleteness(configDir)
+       ├─ verifyCommandCompleteness(configDir, runtime)
+       └─ output(result, raw, summary)
+
+generateManifest() (existing, modified)
+  └─ CHANGE: Include hooks/ directory in file manifest
+```
+
+### Command Interface
+
+```
+pan-tools.cjs validate deployment [--fix]
+
+Output (JSON):
+{
+  "status": "healthy" | "degraded" | "broken",
+  "version": "2.8.0",
+  "runtime": "claude",
+  "checks": {
+    "manifest_files": { "total": 157, "present": 157, "missing": 0 },
+    "hash_integrity": { "verified": 157, "modified": 0, "files": [] },
+    "orphaned_files": { "count": 0, "files": [] },
+    "hooks": { "registered": 3, "files_exist": 3, "paths_valid": true },
+    "agents": { "expected": 12, "found": 12 },
+    "commands": { "expected": 40, "found": 40 },
+    "core_modules": { "expected": 16, "found": 16 },
+    "workflows": { "min": 25, "found": 31 },
+    "templates": { "min": 20, "found": 27 },
+    "references": { "min": 10, "found": 13 }
+  },
+  "errors": [],
+  "warnings": [],
+  "fixable_count": 0,
+  "summary": "deployment: healthy — 157 files verified, 0 issues"
+}
+```
+
+### Post-Install Self-Check
+
+Added to `install.js` after the "Done!" message:
+
+```javascript
+// Lightweight self-check (< 100ms)
+const selfCheck = verifyInstallation(configDir, runtime);
+if (selfCheck.errors.length > 0) {
+  console.log(`\n  ⚠ ${selfCheck.errors.length} issue(s) detected:`);
+  selfCheck.errors.forEach(e => console.log(`    • ${e}`));
+  console.log(`\n  Run: node ${configDir}/pan-wizard-core/bin/pan-tools.cjs validate deployment`);
+}
+```
+
+### Error Handling
+
+| Condition | Behavior |
+|---|---|
+| No manifest file | Return "broken" with instruction to reinstall |
+| Corrupt manifest JSON | Return "broken" with instruction to reinstall |
+| Missing hook files | Return "degraded" with list + fix instructions |
+| Modified PAN files | Return "healthy" with info about modifications |
+| Wrong runtime detected | Try all runtimes, report whichever matches |
+
+## Feature Ladder
+
+| Version | Scope | Value | Effort |
+|---|---|---|---|
+| **v0 (MVP)** | Include hooks in manifest + `validate deployment` CLI + post-install self-check | Deterministic deployment validation | S-M (14 pts) |
+| **v1** | Settings.json deep validation + cross-runtime audit + `--fix` flag | Self-healing deployments | M (12 pts) |
+| **v2** | Deployment health dashboard in statusline + scheduled re-validation hook | Continuous deployment health | M (10 pts) |
+
+## Implementation Tasks
+
+| # | ID | Title | Files | Effort | Pts | Priority |
+|---|---|---|---|---|---|---|
+| 1 | A.1 | Include hooks in generateManifest | install-lib.cjs, install.js | XS | 1 | P1 |
+| 2 | A.2 | cmdValidateDeployment function | pan-wizard-core/bin/lib/verify.cjs | M | 4 | P1 |
+| 3 | A.3 | Route validate deployment in dispatcher | pan-wizard-core/bin/pan-tools.cjs | XS | 1 | P1 |
+| 4 | A.4 | Post-install self-check in installer | bin/install.js | S | 2 | P1 |
+| 5 | A.5 | Settings.json hook path validation | pan-wizard-core/bin/lib/verify.cjs | S | 2 | P2 |
+| 6 | A.6 | Agent/command completeness checks | pan-wizard-core/bin/lib/verify.cjs | S | 2 | P2 |
+| 7 | A.7 | Audit-deployment workflow (backing) | pan-wizard-core/workflows/audit-deployment.md | S | 2 | P2 |
+| 8 | A.8 | Test suite (25+ tests) | tests/deployment-audit.test.cjs | M | 4 | P1 |
+| 9 | A.9 | Cross-runtime audit support | pan-wizard-core/bin/lib/verify.cjs | M | 3 | P3 |
+| 10 | A.10 | Documentation | README, USER-GUIDE, CLI-REFERENCE, CHANGELOG | S | 2 | P3 |
+
+**Total: 23 points (v0+v1 MVP)**
+
+### Dependency Graph
+
+```
+A.1 (Manifest hooks) ──> A.2 (Validate cmd) ──> A.3 (Dispatcher route)
+                                    │
+                                    ├──> A.5 (Settings validation)
+                                    ├──> A.6 (Completeness checks)
+                                    └──> A.8 (Tests)
+
+A.4 (Post-install check) ── standalone, uses A.2 internally
+
+A.7 (Workflow) ── standalone, wraps A.3
+
+A.9 (Cross-runtime) ──> depends on A.2 + A.6
+A.10 (Docs) ──> after A.2, A.3, A.4
+```
+
+## Test Plan
+
+### Test Pyramid
+
+| Level | Count | What It Catches |
+|---|---|---|
+| Unit | 12+ | Manifest generation with hooks, hash verification, orphan detection, settings validation |
+| Integration | 8+ | Full validate deployment JSON output, --fix flag, missing files, corrupt manifest |
+| E2E | 5+ | Real install → validate → modify → re-validate → fix cycle |
+
+### Key Test Cases
+
+1. generateManifest includes hooks/ directory files
+2. generateManifest hook hashes match actual file content
+3. cmdValidateDeployment: clean install → "healthy"
+4. cmdValidateDeployment: missing core module → "broken"
+5. cmdValidateDeployment: missing hook → "degraded"
+6. cmdValidateDeployment: hash mismatch → reported as "modified"
+7. cmdValidateDeployment: orphaned files detected
+8. cmdValidateDeployment: corrupt manifest → "broken"
+9. cmdValidateDeployment: no manifest → "broken" with reinstall instruction
+10. cmdValidateDeployment: settings.json missing hook entry → warning
+11. cmdValidateDeployment: settings.json hook path points to nonexistent file → error
+12. cmdValidateDeployment: agent count < 12 → warning
+13. cmdValidateDeployment: command count < expected → warning
+14. Post-install self-check: clean install → no warnings
+15. Post-install self-check: simulated missing file → warning printed
+16. --fix flag: regenerates missing settings.json
+17. --fix flag: does NOT regenerate missing core modules (reinstall required)
+18. Cross-runtime: Claude config dir detection
+19. Cross-runtime: Gemini config dir detection
+20. Raw JSON output format matches schema
+21. Summary string format is correct
+22. Exit code 0 for healthy, 1 for broken
+23. Binary/large files skipped in hash verification
+24. CRLF vs LF handling in hash comparison
+25. Partial install recovery path
+
+## Security
+
+- **Attack surface:** Read-only analysis of local files. No network calls. No code execution beyond Node.js.
+- **Path safety:** All paths resolved relative to configDir with `path.resolve()` + containment check.
+- **No eval/Function:** Pure file reads and hash comparisons.
+- **Manifest tampering:** If manifest is tampered, hash mismatches are detected. If manifest is deleted, reported as "broken".
+
+## Risk Register
+
+| Risk | Probability | Impact | Mitigation |
+|---|---|---|---|
+| Hook hashes differ across platforms (CRLF) | Medium | Low | Normalize line endings before hashing or use git-style normalization |
+| Manifest size growth with hooks | Low | Low | 3 additional entries — negligible |
+| Post-install self-check slows install | Low | Low | < 100ms budget enforced via async file stats |
+| False positives from AV-quarantined files | Medium | Medium | Clear error message: "file missing, check antivirus quarantine" |
+| Breaking change to manifest format | Low | High | Version field in manifest already exists, add migration path |
+
+## Sources
+
+- PAN Wizard deployment audit of d:\pantesting (2026-03-09)
+- install-lib.cjs `generateManifest()` code review
+- pan-tools.cjs dispatcher code review
+- settings.json hook configuration analysis
+- install.js post-install flow analysis
+
+---
+
+*Generated by /pan:audit-deployment — 2026-03-09*

package/docs/specs/doc_code_link_graph_featureai.md

@@ -0,0 +1,253 @@
+---
+spec: doc-code-link-graph
+adr: ADR-0027
+status: accepted
+created: 2026-05-03
+---
+
+# Spec: Doc–Code Link Graph
+
+This spec is the W0 gate for [ADR-0027](../decisions/ADR-0027-doc-code-link-graph.md). It defines the on-disk grammars, the scanner contracts, the lint passes, the output schema, and the failure modes that the W1–W3 implementation must satisfy. Where this spec and the ADR diverge, the spec is authoritative for behavior; the ADR is authoritative for rationale.
+
+## 1. Surfaces
+
+The link graph spans **two surfaces**:
+
+| Surface | Files | What it carries |
+|---|---|---|
+| Docs | `docs/`, `pan-wizard-core/{workflows,templates,references,learnings}/`, `commands/`, `agents/`, `CLAUDE.md`, `README.md` | Inline `[[<id>]]` body refs, `must_haves.key_links` frontmatter, `require-code-mention: true` frontmatter |
+| Code | `pan-wizard-core/`, `bin/`, `hooks/`, `scripts/` | `@pan: <id>` source-comment anchors |
+
+Source roots are configurable via `--source-root` and `--doc-root` flags (repeatable); defaults match the table above.
+
+## 2. Doc-side grammars
+
+### 2.1 Inline link `[[<id>]]`
+
+Body-text reference. Forms:
+
+```
+[[ADR-0021]]                      → resolves to docs/decisions/ADR-0021-*.md
+[[docs/specs/example.md]]         → resolves to that exact path
+[[learnings/universal/test-iso]]  → resolves to pan-wizard-core/learnings/universal/test-iso.md
+[[ADR-0021#Decision]]             → file + section anchor
+```
+
+Recognition regex: `\[\[([^\[\]\s|][^\[\]]*?)\]\]` (anchored to non-bracket, non-leading-pipe to keep markdown table cells safe).
+
+### 2.2 Frontmatter `must_haves.key_links`
+
+Existing mechanism, unchanged. Continues to be verified by [verify.cjs:cmdVerifyKeyLinks](../../pan-wizard-core/bin/lib/verify.cjs). The link-graph forward pass treats each `key_links` entry as one forward link with a regex-backed assertion; integration is read-only — `links validate` never rewrites `key_links` blocks.
+
+### 2.3 Frontmatter `require-code-mention: true`
+
+Optional. When set, the doc declares that at least one source-anchor (`@pan:`) under the configured source roots must resolve to it. Default is `false`/absent (advisory). Authors opt docs in; the tool does not.
+
+## 3. Code-side grammar: `@pan: <id>`
+
+A source comment of the form:
+
+```
+<comment-leader>[whitespace]@pan:[whitespace]<id>
+```
+
+`<comment-leader>` is one of:
+
+| Leader | Used by | Languages |
+|---|---|---|
+| `//` | JS, TS, CJS | `*.cjs`, `*.js`, `*.ts`, `*.mjs` |
+| `#` | Shell, Python | `*.sh`, `*.py`, `*.ps1` |
+| `<!--` | HTML / Markdown | `*.md`, `*.html` (closing `-->` is permitted on the same line and ignored) |
+
+`<id>` matches one of the doc-id forms in §4.
+
+Recognition regex (per leader, line-anchored, leading whitespace permitted):
+
+- JS/TS:   `^\s*//\s*@pan:\s*([^\s].*?)\s*$`
+- Shell:   `^\s*#\s*@pan:\s*([^\s].*?)\s*$`
+- HTML:    `^\s*<!--\s*@pan:\s*([^\s].*?)\s*(?:-->)?\s*$`
+
+Anchors are line-scoped — multi-line block comments are not parsed. Anchors found inside string literals are out of scope; the line-anchor regex avoids most false positives because string literals on a line do not begin with the comment leader.
+
+A file may carry multiple anchors. Convention: cluster anchors at the top of the file under a single banner comment.
+
+## 4. Doc-id resolution
+
+Input form → resolution order (first match wins):
+
+1. **`ADR-NNNN`** (case-insensitive `ADR-` prefix, exactly 4 digits) → glob `docs/decisions/ADR-NNNN-*.md`. Zero or many matches → unresolved.
+2. **`<path>` ending in `.md`** → exact relative-to-repo-root path.
+3. **`<path>` not ending in `.md`** → try `<path>.md` first, else `<path>/README.md`. Used by `learnings/universal/<topic>` shorthand.
+4. **`<doc>#<section>`** → split on `#`; resolve `<doc>` per (1)–(3); then verify a markdown heading whose flattened slug matches `<section>`. Slug = lowercase + spaces→`-` + remove non-`[a-z0-9-]`.
+
+Doc-ids are stored canonically as POSIX-style paths. The resolver returns `{ resolved: boolean, path?: string, section?: string, reason?: string }`.
+
+## 5. Lint passes
+
+`pan-tools links validate [--strict] [--json] [--source-root <p>...] [--doc-root <p>...] [--root <p>]`
+
+Three sequential passes; all findings collected into one report.
+
+### 5.1 Forward-link resolution (`F-001` through `F-099`)
+
+For each markdown file under doc roots:
+
+| Code | Severity | Trigger |
+|---|---|---|
+| F-001 | error | `[[<id>]]` does not resolve to a file |
+| F-002 | error | `[[<doc>#<section>]]` resolves a file but the named section is missing |
+| F-003 | warning | `must_haves.key_links` entry's `from` or `to` path does not exist |
+| F-004 | warning | `must_haves.key_links` entry's `pattern` is not a valid regex |
+
+`F-003` and `F-004` are the existing `cmdVerifyKeyLinks` checks reframed as graph findings. The original command keeps working in parallel; calling it from the new lint is left to a follow-up to avoid double-walks.
+
+### 5.2 Backlink contract (`B-001` through `B-099`)
+
+For each doc with `require-code-mention: true` in frontmatter:
+
+| Code | Severity | Trigger |
+|---|---|---|
+| B-001 | error | Zero `@pan:` anchors under source roots resolve to this doc |
+| B-002 | warning | All resolving anchors are in the same single source file (single-point-of-truth signal — informational) |
+
+`B-001` is the load-bearing check. `B-002` is informational and does not flip the report status under `--strict`.
+
+### 5.3 Anchor-target existence (`A-001` through `A-099`)
+
+For each `@pan: <id>` anchor under source roots:
+
+| Code | Severity | Trigger |
+|---|---|---|
+| A-001 | error | `<id>` does not resolve to a file under doc roots |
+| A-002 | warning | `<id>` includes a `#section` that doesn't match any heading in the resolved file |
+| A-003 | warning | Anchor uses a deprecated form (reserved for future migrations; no triggers in v1) |
+
+## 6. Output schema
+
+Both `--json` and human modes share the same underlying object; human mode adds a flat-text summary line via `output()`.
+
+```json
+{
+  "ok": false,
+  "summary": {
+    "total_findings": 3,
+    "errors": 2,
+    "warnings": 1,
+    "status": "fail",
+    "doc_files_scanned": 142,
+    "source_files_scanned": 38,
+    "anchors_found": 7,
+    "forward_links_found": 51,
+    "backlink_contracts_checked": 3
+  },
+  "findings": [
+    {
+      "code": "F-001",
+      "severity": "error",
+      "source": "docs/USER-GUIDE.md",
+      "source_line": 87,
+      "target": "ADR-9999",
+      "detail": "ADR-9999 did not match any file under docs/decisions/"
+    },
+    {
+      "code": "B-001",
+      "severity": "error",
+      "source": "docs/decisions/ADR-0026-self-improvement-loop.md",
+      "target": null,
+      "detail": "require-code-mention is true but no @pan: anchors resolve to this doc"
+    },
+    {
+      "code": "A-002",
+      "severity": "warning",
+      "source": "pan-wizard-core/bin/lib/experiment.cjs",
+      "source_line": 3,
+      "target": "ADR-0026#NonexistentSection",
+      "detail": "Section anchor not found in resolved file"
+    }
+  ]
+}
+```
+
+`status` is `pass` when `errors === 0` and (without `--strict`) is also `pass` when only warnings are present. `--strict` flips status to `fail` if any finding exists. Process exit code is `0` for `pass`, `1` for `fail`.
+
+## 7. Module API surface
+
+`pan-wizard-core/bin/lib/links.cjs` exports:
+
+```
+validateAll(rootDir, opts)         → { ok, summary, findings }
+scanForwardLinks(docRoots, cwd)    → [{ source, sourceLine, rawId, resolved, ... }]
+scanAnchors(sourceRoots, cwd)      → [{ source, sourceLine, rawId, resolved, ... }]
+resolveDocId(rawId, cwd)           → { resolved, path?, section?, reason? }
+parseAnchorLine(line, leader)      → string|null  (returns the rawId or null)
+parseInlineLinks(text)             → [{ rawId, line }]
+cmdLinksValidate(cwd, opts)        → void  (writes to stdout via output())
+```
+
+`opts` shape:
+
+```
+{
+  sourceRoots: string[]?,   // defaults to ['pan-wizard-core', 'bin', 'hooks', 'scripts']
+  docRoots:    string[]?,   // defaults to ['docs', 'pan-wizard-core/workflows',
+                            //                'pan-wizard-core/templates',
+                            //                'pan-wizard-core/references',
+                            //                'pan-wizard-core/learnings',
+                            //                'commands', 'agents']
+  strict:      boolean,     // default false
+  raw:         boolean,     // for output() — passed through
+}
+```
+
+## 8. Reuse contracts
+
+The implementation MUST reuse the following existing modules; no parallel walkers, no parallel parsers.
+
+| Concern | Module | Function |
+|---|---|---|
+| Recursive markdown walk | [doc-lint/walk.js](../../pan-wizard-core/bin/lib/doc-lint/walk.js) | `walkMarkdownFiles(dir, {exclude})` |
+| Frontmatter parse | [frontmatter.cjs](../../pan-wizard-core/bin/lib/frontmatter.cjs) | `extractFrontmatter(content)` |
+| `key_links` block parse | [frontmatter.cjs](../../pan-wizard-core/bin/lib/frontmatter.cjs) | `parseMustHavesBlock(content, 'key_links')` |
+| File reads + path normalization | [core.cjs](../../pan-wizard-core/bin/lib/core.cjs) | `safeReadFile`, `toPosix` |
+| Output framing | [core.cjs](../../pan-wizard-core/bin/lib/core.cjs) | `output(obj, raw, humanLine?)` |
+
+For source-side scanning the implementation walks file extensions directly via `fs.readdirSync` recursion — no dependency on the `walkMarkdownFiles` walker (which is markdown-only).
+
+## 9. Failure modes
+
+| Mode | Behavior |
+|---|---|
+| Doc root does not exist | Skip silently; record skipped roots in summary as informational |
+| Source root does not exist | Skip silently; record skipped roots in summary as informational |
+| File read error mid-walk | Emit a finding with code `F-005` or `A-005` (severity warning) — do not abort |
+| Frontmatter parse error | Treat doc as having no frontmatter for that file's contract checks; not a finding |
+| Regex pattern in `key_links` is invalid | Emit `F-004`; do not abort |
+| Anchor with empty id (`@pan:` followed by nothing) | Emit `A-004` warning; skip resolution |
+
+`links validate` MUST NOT throw under any normal repo state. All errors are findings.
+
+## 10. Cross-platform requirements
+
+- All path output uses POSIX-style forward slashes via `toPosix()`.
+- All path comparisons normalize via `toPosix()` before equality.
+- Doc-ids that are ADR shortcuts are case-insensitive on the `ADR-` prefix only (the `NNNN-<slug>` portion preserves case as on disk).
+- The walker must not follow symlinks (matches existing `walkMarkdownFiles` behavior).
+
+## 11. Acceptance criteria
+
+The W1–W3 implementation is acceptance-complete when:
+
+1. **W1**: `node pan-wizard-core/bin/pan-tools.cjs links validate --json` runs against a hand-crafted fixture project (under `tests/fixtures/links-graph/`) and emits the schema in §6 with correct findings for: a deliberately broken `[[<id>]]`, a deliberately stale `@pan:` anchor, a doc with `require-code-mention` and zero anchors, and a clean control case. Unit tests in `tests/links.test.cjs` assert all four findings.
+2. **W2**: Running against the source repo of PAN itself (the real `docs/` + source tree) returns `status: pass` in advisory mode (warnings allowed), excluding `require-code-mention` opt-ins (none yet at W2).
+3. **W3**: After opting three canary ADRs into `require-code-mention: true` and placing the corresponding `@pan:` anchors in their primary implementation files, `pan-tools links validate --strict` returns `status: pass`. `pan-tools validate health` shows a `link_graph` summary line.
+
+## 12. Out of scope (explicit deferrals)
+
+These are listed in [ADR-0027](../decisions/ADR-0027-doc-code-link-graph.md#future-scope) and intentionally not specified here:
+
+- `pan-tools links refs <doc>` (reverse query)
+- `pan-tools links expand <file>` (inline expansion into prompts)
+- Auto-anchor suggestion path inside `pan-optimizer`
+- Migration of `must_haves.key_links` to inline `[[<id>]]`
+- Commit-time hook gating
+- AST-based code parsing

package/docs/specs/documentation_alignment_cleanup_featureai.md

@@ -0,0 +1,69 @@
+# Documentation Alignment & Cleanup — Feature AI Specification
+
+**Mode:** `--spike` (internal cleanup, no competitive research needed)
+**Date:** 2026-03-02
+
+---
+
+## Phase 0: Problem Statement & Scope
+
+PAN Wizard v1.0.0 has accumulated stale counts and orphaned artifacts across 21 development sessions. Documentation references 33 workflows (actual: 30), 1012 tests (actual: 1065), and 875 tests in the ship spec (actual: 1065). Three runtime installation directories (.codex/, .gemini/, .opencode/) are untracked 5MB of clutter. Two completed batch files should be archived. FAQ.md is missing Copilot CLI from the runtime table.
+
+### Scope
+
+| In Scope | Out of Scope |
+|----------|-------------|
+| Fix stale counts in DEVELOPMENT.md | Rewriting spec content (historical docs) |
+| Fix FAQ.md missing Copilot CLI | Adding new documentation |
+| Archive completed batch files | Changing any code |
+| Add runtime dirs to .gitignore | Modifying the installer |
+| Update production_readiness spec counts | CI/CD changes |
+| Fix ADR-0009 workflow count reference | |
+
+---
+
+## Phase 4: Design — Task List
+
+### CRITICAL (P1)
+
+**Task 1: Fix DEVELOPMENT.md stale counts**
+- Line 33: workflow count 33 → 30
+- Line 45: test count "1012 tests, 206 suites" → "1065 tests, 218 suites"
+- Line 56: "Run all 1012 tests" → "Run all 1065 tests"
+Files: docs/DEVELOPMENT.md
+
+**Task 2: Fix FAQ.md missing Copilot CLI**
+- Add Copilot CLI row to runtime table
+Files: docs/FAQ.md
+
+### HIGH (P2)
+
+**Task 3: Fix production_readiness_ship_v1 spec stale counts**
+- Replace "33 test files, 875 tests" with "37 test files, 1065 tests" (4 locations)
+Files: docs/specs/production_readiness_ship_v1_featureai.md
+
+**Task 4: Fix ADR-0009 workflow count**
+- "33 workflows when 31 exist" → "33 workflows when 30 exist"
+Files: docs/decisions/ADR-0009-production-deployment-checklist.md
+
+### MEDIUM (P3)
+
+**Task 5: Add runtime install dirs to .gitignore**
+- Add .codex/, .gemini/, .opencode/ to .gitignore
+Files: .gitignore
+
+**Task 6: Archive completed batch files**
+- Move batch-2026-03-01-c.json to .planning/focus/archive/
+- Move batch-2026-03-02.json to .planning/focus/archive/
+Files: .planning/focus/
+
+### LOW (P6)
+
+**Task 7: Fix stale counts in historical specs (optional)**
+- copilot_cli_runtime_featureai.md: "32 workflow commands" → updated to 37
+- industry_comparison_and_feature_gaps_featureai.md: "4 runtimes" → updated to 5
+Files: docs/specs/
+
+---
+
+## Total: 7 tasks, all XS size, ~10 minutes