pan-wizard 3.36.0 → 3.37.0

package/docs/decisions/ADR-0026-self-improvement-loop.md

@@ -0,0 +1,171 @@
+---
+require-code-mention: true
+---
+
+# ADR-0026: Self-Improvement Loop — Idea → External Build → Harvest → Promote → Ship
+
+## Status
+Accepted (shipped 2026-04-27 across waves W1-W4 as v3.7.0)
+
+## Context
+
+PAN Wizard v3.5+ shipped a complete intra-project learning loop: `pan-trace-logger` captures every agent spawn, `/pan:learn` invokes `pan-optimizer` to analyze the session, `/pan:optimize apply` writes findings to `.planning/memory/`. Each user project's PAN install learns about its own codebase over time.
+
+What was missing: the **PAN tool itself** did not learn. Every release shipped frozen behavioral rules (`references/`, workflows, agent prose). Real-world session data — the gold mine of "what shortcuts AI agents take, where verification fails, which guardrails fire" — stayed trapped in user projects' `.planning/optimization/` directories. The next release of PAN had no idea what the previous release's sessions discovered.
+
+The MEMORY.md note "Cross-Session Learning (PATTERNS.md auto-capture)" was deferred for exactly this reason — it needed a design spec. Spec was written 2026-04-27 (`docs/specs/self_improvement_loop_featureai.md`). This ADR records the decisions made implementing it.
+
+## Decision
+
+Ship a **cross-project meta-learning loop** as v3.7.0 across four additive waves. The loop:
+
+```
+1. /pan:experiment new <slug> --idea idea.md   →  scaffold isolated project outside source repo
+2. /pan:experiment run <slug>                  →  spawn external AI session, observe
+3. /pan:experiment harvest <slug>              →  copy telemetry back to <source>/experiments/<slug>/
+4. /pan:learn --experiment <slug>              →  run pan-optimizer over harvested data
+5. pan-tools learn promote --pattern <id>      →  write findings to pan-wizard-core/learnings/{universal,internal}/
+6. ship as next release                        →  patterns auto-load via workflow cross-references
+```
+
+### Architecture decisions recorded here
+
+**1. Two-tier learnings layout (`universal/` ships, `internal/` does not).**
+
+`pan-wizard-core/learnings/universal/` ships to all 5 runtime install dirs alongside `references/`. `pan-wizard-core/learnings/internal/` stays source-only. The installer (`bin/install.js`) explicitly strips `learnings/internal/` after the recursive copy. Rationale: PAN-development-specific patterns ("always commit individually because of the source repo's hooks") must NOT leak into user installs as universal advice. A negative test in `tests/scenarios/learnings-installed.test.cjs` enforces this.
+
+**2. Manual promote gate (no auto-promote in v3.7).**
+
+`pan-tools learn promote` requires explicit `--pattern <id> --scope <s> --topic <t>` flags. The human picks scope and topic. Auto-promote (rules-based confidence threshold) is deferred to v3.8+ once 10+ manual promotes inform the filter design. Risk of bad auto-promote: a single misclassified PAN-internal pattern shipping as universal advice would silently pollute every user install. Manual gate eliminates this for v3.7.
+
+**3. Subprocess runner, not VSCode UI automation.**
+
+`runner.cjs` uses Node's `spawnSync` to invoke external runtimes headlessly (`claude -p`, `codex exec`, `gemini -p`, `opencode <prompt>`). Initial design considered driving a separate VSCode window via Playwright (Session 33 added the infrastructure), but: (a) GUI dependency adds cross-platform display setup, (b) headless display drivers are flaky, (c) CLI subprocess is sufficient for autonomous runs. Playwright stays for testing PAN inside VSCode, not for the experiment runner. GitHub Copilot CLI is **opt-out** — no documented headless prompt mode known.
+
+**4. Observation-only watchdog agent.**
+
+`pan-experiment-runner` agent has tools `[Read, Bash, Glob, Grep]` only — explicitly NO `Edit` or `Write`. The agent watches the experiment's `.planning/run-state.json`, decides when stop conditions fire, and reports back. It does NOT inject prompts mid-flight or fix problems in the experiment. Cleaner failure semantics: if the external session gets stuck, the timeout/circuit-breaker fires; PAN doesn't try to "save" it. Every intervention path would be a new bug surface.
+
+**5. Experiments live outside the source repo.**
+
+`PAN_EXPERIMENTS_ROOT_DEFAULT` is `~/pan-experiments/` (configurable via `--root`). `experiment.cjs newExperiment` refuses to scaffold inside `PAN_SOURCE_ROOT`. Mirror of the existing installer guard — the experiment folder gets a fresh PAN install, and that install would conflict with the source repo's own files.
+
+**6. spawnSync over async spawn.**
+
+Initial implementation used `child_process.spawn` with a custom poll-loop using `Atomics.wait`. This blocked the main thread, preventing the child's `exit` event from firing (event loop starved). Switched to `spawnSync` which has native timeout support and exits cleanly across platforms. Trade-off: real-time progress streaming is impossible in synchronous mode — `onProgress` callback fires once after exit with the full captured stdout/stderr. Documented as W3-or-later work to migrate to async/Promise mode if real-time streaming becomes load-bearing.
+
+**7. Harvest writes inside the source repo.**
+
+`harvestExperiment` copies telemetry to `<source-repo>/experiments/<slug>/`. This is INSIDE the source repo intentionally — harvested data becomes part of the source's git history alongside the spec/ADR/code that drove the promote decision. The PAN_SOURCE_ROOT guard (which prohibits writing the experiment ITSELF inside source) does not apply to harvest — different operation, different rules. The `experiments/` directory is intentionally not gitignored; small harvests are committed; large raw traces (`optimization/traces/sess_*/trace.jsonl`) may be gitignored selectively in the future if size becomes an issue.
+
+**8. Streaming progress deferred.**
+
+Original spec called for real-time `onProgress` callback during `runExperiment`. Synchronous spawnSync semantics don't support real-time streams. For W2-W4, output is captured-and-emitted-once. Real-time streaming becomes a v3.7.x or v3.8 follow-up if the autonomous loop produces sessions long enough that progress visibility matters more than synchronous CLI shape.
+
+### Explicit deferrals (documented, not shipped)
+
+- **Auto-promote** (rules-based confidence threshold filter) — v3.8+
+- **Cross-experiment aggregation** (promote a pattern based on N experiments instead of 1) — v3.8+
+- **VSCode UI automation as runner path** — keep CLI; Playwright stays for tests only
+- **Bidirectional control mid-experiment** — observation-only by design
+- **GitHub Copilot CLI runner** — no headless prompt mode known; document limitation
+- **Container-isolated experiments** — process isolation via separate folder is sufficient for v3.7
+- **Real-time progress streaming** — captured-and-emitted-once is sufficient
+- **Experiment replay from a specific phase** — needs idempotency design
+- **Promoting from a parsed report file** — v3.7 takes pattern data inline via flags; report-parser is v3.7.x
+
+## Consequences
+
+### Positive
+
+- **PAN ships smarter every release.** Findings from real builds become part of the next product version.
+- **Two-tier delivery** keeps PAN-internal patterns out of user installs without manual judgment per file.
+- **Zero regressions.** All v3.6.0 behavioral guardrails still work; v3.7.0 is purely additive.
+- **Test coverage:** 2627 → 2670+ across waves, with negative tests on the universal/internal split (one of the highest-stakes invariants).
+- **Existing infrastructure reused:** `optimize.cjs` analysis, `pan-optimizer` agent, `references/` delivery channel, `createScenarioRunner` for tests, `focus.cjs` budget+circuit-breaker pattern.
+- **Manual promote gate** keeps the human in the loop for the highest-leverage step.
+
+### Negative
+
+- **Module count grew from 27 to 29.** Surface expansion. Mitigation: `experiment.cjs` and `runner.cjs` have clear single responsibilities; both are documented in `ARCHITECTURE.md`.
+- **`spawnSync` is synchronous and blocks pan-tools.cjs during a real run.** Real-time progress visibility is degraded. Mitigation: `runner.runExperiment` is invoked manually by the user; nothing else is competing for the main thread during a deliberate experiment run.
+- **Harvest data may grow unbounded.** A trace.jsonl from a large experiment can be MB-sized. v3.7 commits it whole; v3.8+ may add gitignore rules or compression.
+- **Topic-file frontmatter format is bespoke** (not standard YAML). Reason: zero-runtime-deps constraint. The parser is a 30-line minimal implementation. If a topic file is hand-edited and breaks the format, `listPromotedPatterns` skips it silently. Mitigation: `learnings/README.md` documents that topic files are AI-managed.
+- **Auto-promote deferred to v3.8.** Manual gate is friction. Rationale: bad auto-promotes ship to all users; better to be slow than wrong.
+- **GitHub Copilot CLI is excluded from the runner path.** Documented limitation. Copilot users can still scaffold experiments and consume promoted learnings, just not drive the runner.
+
+### Neutral / Tradeoffs considered
+
+- **Why not use a YAML library?** Zero-deps constraint. The frontmatter parser is 30 lines; a YAML library would be the first runtime dep ever shipped by PAN.
+- **Why a single-pattern per promote command?** Multi-pattern batch would couple unrelated decisions. Each pattern gets a deliberate human review.
+- **Why ship the `pan-experiment-runner` agent in W2 instead of bundling agent + module in W4?** The agent is the natural orchestrator for the runner. Shipping them together keeps the user-facing surface coherent.
+
+## Implementation Notes
+
+### Files added (W1-W4 cumulative)
+
+| File | Wave | Purpose |
+|------|------|---------|
+| `pan-wizard-core/bin/lib/experiment.cjs` | W1 (extended W3) | 28th core module |
+| `pan-wizard-core/bin/lib/runner.cjs` | W2 | 29th core module |
+| `pan-wizard-core/templates/idea.md` | W1 | 27th template |
+| `pan-wizard-core/learnings/README.md` | W1 | tier explainer |
+| `pan-wizard-core/learnings/{universal,internal}/.gitkeep` | W1 | dir placeholders |
+| `commands/pan/experiment.md` | W1 (extended W2-W3) | 52nd command |
+| `agents/pan-experiment-runner.md` | W2 | 21st agent |
+| `tests/experiment.test.cjs` | W1 (extended W3) | 21 unit tests |
+| `tests/runner.test.cjs` | W2 | 12 unit tests |
+| `tests/learn-promote.test.cjs` | W4 | 13 unit tests |
+| `tests/scenarios/experiment-lifecycle.test.cjs` | W3 | 6 scenario tests |
+| `tests/scenarios/learnings-installed.test.cjs` | W4 | 15 scenario tests (3×5 runtimes) |
+| `docs/decisions/ADR-0026-self-improvement-loop.md` | W4 | this ADR |
+| `docs/specs/self_improvement_loop_featureai.md` | W1 (commit `6a96c21`) | spec |
+
+### Files modified
+
+- `pan-wizard-core/bin/lib/optimize.cjs` — added promote/list-promoted/unpromote
+- `pan-wizard-core/bin/pan-tools.cjs` — registered experiment + learn promote subcommands
+- `commands/pan/learn.md` — added `--experiment <slug>` flag docs
+- `pan-wizard-core/workflows/{exec-phase,plan-phase,verify-phase,execute-plan}.md` — reference `learnings/universal/`
+- `bin/install.js` — two-tier guard strips `learnings/internal/` from installs
+- `package.json` — version bump to 3.7.0
+- `CHANGELOG.md`, `docs/USER-GUIDE.md`, `docs/ARCHITECTURE.md`, `MEMORY.md` — documentation
+
+### Cumulative deltas (v3.6.0 → v3.7.0)
+
+- Tests: 2588 → ~2670+ (+82+)
+- Core modules: 27 → 29 (+2)
+- Agents: 20 → 21 (+1)
+- Commands: 51 → 52 (+1)
+- Templates: 26 → 27 (+1)
+- New top-level dir under pan-wizard-core: `learnings/{universal,internal}/`
+
+### Rollback plan
+
+The layer is entirely additive. Rollback steps if telemetry reveals a regression:
+
+- Remove `pan-wizard-core/bin/lib/{experiment,runner}.cjs` — dispatcher commands degrade to "command not found"
+- Remove `agents/pan-experiment-runner.md` — agent unavailable; users fall back to manual experiment runs
+- Remove `pan-wizard-core/learnings/` — no shipped patterns; workflow cross-references resolve to "directory not found" but workflows continue
+- Remove the `learnings/internal/` strip from `bin/install.js` — restores pre-v3.7 install behavior
+- Revert workflow cross-references — workflows function identically without the new line
+- Revert `optimize.cjs` extensions — `pan-tools learn promote/unpromote/list-promoted` become "command not found"
+
+No schema changes, no manifest format changes. Rollback is a commit-level revert.
+
+### References
+
+- Source spec: `docs/specs/self_improvement_loop_featureai.md` (created 2026-04-27)
+- Predecessor: ADR-0025 (v3.6.0 behavioral guardrails layer — proved `references/` delivery channel)
+- Predecessor: Session 31 — circular optimization loop (proved trace + analyze + apply pattern)
+- Test infrastructure: `tests/helpers.cjs createScenarioRunner` (Session 18)
+- Budget+circuit-breaker pattern: `pan-wizard-core/bin/lib/focus.cjs` (Session 26 / ADR-0015)
+
+## Future scope
+
+- **v3.8.0**: auto-promote (rules-based filter, AI-confidence threshold) once 10+ manual promotes inform the design
+- **v3.8.0**: cross-experiment aggregation — promote a pattern based on N experiments
+- **v3.8+**: real-time progress streaming via async/Promise mode if needed
+- **v3.9+**: container-isolated experiments if process isolation proves insufficient
+- **v3.9+**: experiment-replay-from-phase if idempotency story is solved
+- **v3.7.x**: report-file parser for promote (extract pattern from `experiments/<slug>/learnings/report-*.md` instead of inline flags)

package/docs/decisions/ADR-0027-doc-code-link-graph.md

@@ -0,0 +1,164 @@
+---
+require-code-mention: true
+---
+
+# ADR-0027: Doc–Code Link Graph — `@pan:` Source Anchors & `links validate` Lint
+
+## Status
+Accepted — 2026-05-03. Ships in v3.8.0. Implemented in `pan-wizard-core/bin/lib/links.cjs` (`links validate`; also wired into `pan-tools validate health --links`). Spec: `docs/specs/doc_code_link_graph_featureai.md`.
+
+## Context
+
+PAN's planning surface is a graph in everything but enforcement. ADRs reference specs, specs reference phases, phases reference modules, learnings reference workflows. The relationships exist; the integrity does not. When a module is renamed, a phase archived, or an ADR superseded, no tooling notices the dangling references — they surface as agent confusion ("I cannot find the file referenced in the plan") during exec, which is the worst possible time.
+
+We have one partial mechanism today: `must_haves.key_links` in plan-file frontmatter, verified by `cmdVerifyKeyLinks` in [verify.cjs:376](../../pan-wizard-core/bin/lib/verify.cjs#L376). It checks that a regex pattern occurs in a target file. Its scope is narrow:
+
+- Per-plan-file declaration only — ADRs, specs, learnings, references, and workflows have no link contract.
+- Frontmatter-only — body-text references like "see ADR-0021" are not validated.
+- One-directional — docs declare what they reference; **code does not declare which docs anchor it**. Renaming a module silently strands its ADR.
+- No reverse query — "what depends on this ADR?" requires `grep`.
+
+The recently-surveyed external project [`1st1/lat.md`](https://github.com/1st1/lat.md) demonstrates the missing half: `// @lat: [[section-id]]` source comments tie code to its documentation, and a single lint walks the whole graph. lat.md's full feature set (semantic search, MCP server, libsql, tree-sitter, TypeScript) is incompatible with PAN's zero-runtime-deps + CJS posture, but the **annotation convention and graph-lint pattern translate cleanly** and require no dependencies.
+
+This ADR records the smallest valuable slice: an annotation convention for source files, a frontmatter assertion for docs that require a code backlink, and a single lint that walks both sides.
+
+## Decision
+
+Add a doc–code link graph as an additive extension to existing PAN doc/lint infrastructure. **Three** elements ship together; everything else is deferred.
+
+### 1. Source-code annotation convention: `// @pan: <doc-id>`
+
+Source files in `pan-wizard-core/`, `bin/`, `hooks/`, `commands/`, and `agents/` may carry one or more anchor comments:
+
+```js
+// @pan: ADR-0026
+// @pan: docs/specs/self_improvement_loop_featureai.md
+// @pan: learnings/universal/test-isolation
+```
+
+Rules:
+
+- **Comment style is host-language idiomatic.** `//` for `.cjs`/`.js`, `#` for shell/Python, HTML comments for `.md`. The scanner accepts any of these so long as the literal token `@pan:` appears.
+- **Doc IDs are paths or known short forms.** `ADR-NNNN` resolves to `docs/decisions/ADR-NNNN-*.md`; everything else is a repo-relative path.
+- **An anchor is a claim**: "this file is a load-bearing implementation of that doc." Annotations are not required everywhere; they are required only where the *doc* asserts it (see element 3).
+- **The convention is documentation, not gating.** Missing or incorrect anchors are lint findings, not commit blockers, until the team opts a doc into `require-code-mention`.
+
+### 2. Doc-side frontmatter: `require-code-mention: true`
+
+Any markdown doc — ADR, spec, learning, reference — may add a frontmatter field:
+
+```yaml
+---
+require-code-mention: true
+---
+```
+
+The lint then asserts that **at least one** source file under the scanned roots carries an `@pan:` anchor resolving to this doc. Docs without the field are treated as advisory; the absence of code mentions is silent.
+
+This mirrors lat.md's `require-code-mention: true` semantics one-for-one. The choice of which docs opt in is the user's, not the tool's. Initial defaults (suggested, not enforced): all `docs/decisions/ADR-*.md` for accepted ADRs; specs are opt-in.
+
+### 3. New CLI: `pan-tools links validate`
+
+A single command produces a graph-integrity report. It runs three passes:
+
+1. **Forward link resolution.** Walks `docs/`, `pan-wizard-core/{workflows,templates,references,learnings}/`, `commands/`, `agents/` for inline `[[<id>]]` references and frontmatter `must_haves.key_links` entries. Each link must resolve to a real file (and section, when supplied).
+2. **Backlink contract.** For every doc with `require-code-mention: true`, scan source roots for `@pan:` anchors resolving to that doc. Zero matches → finding.
+3. **Anchor target existence.** For every `@pan:` anchor, the resolved target must exist. A renamed ADR with a stale anchor → finding.
+
+Output shape mirrors existing `validate health` JSON: `{ ok, findings: [{ type, severity, source, target, detail }] }`. Subcommands: `validate` (default), `--strict` (exit 1 on any finding), `--json` (machine output for hooks).
+
+Implementation slot: a new `links.cjs` module under `pan-wizard-core/bin/lib/`, registered in `pan-wizard-core/bin/pan-tools.cjs`. The forward-link walker reuses the doc-lint walker in [pan-wizard-core/bin/lib/doc-lint/walk.js](../../pan-wizard-core/bin/lib/doc-lint/walk.js); the frontmatter parser reuses [frontmatter.cjs](../../pan-wizard-core/bin/lib/frontmatter.cjs); the source scanner is a 30-line regex over the source roots. No new runtime dependencies.
+
+### What this ADR explicitly does NOT add
+
+- **Inline `[[wiki-link]]` rendering or rewriting.** The lint *checks* such links; nothing transforms them.
+- **`pan-tools links refs <doc>` (reverse-index query).** Implementable on top of the same scanner; deferred to a follow-up phase to keep this ADR small.
+- **`pan-tools links expand <file>` (inline ref content into a prompt).** Belongs near `context-budget.cjs` and needs a budget contract; deferred.
+- **Semantic search, embeddings, MCP server, vector DB.** Out of scope — violates zero-deps and overlaps with Claude Code's own MCP plumbing.
+- **Tree-sitter / AST parsing.** Regex over comment lines is sufficient and stays consistent with [codebase.cjs](../../pan-wizard-core/bin/lib/codebase.cjs)'s regex-not-AST stance (per ADR-0021).
+- **Auto-creation of anchors.** Humans place `@pan:` anchors; the tool does not infer them.
+- **Pre-commit hook integration.** Runs on demand and inside `validate health`; commit-time enforcement is opt-in via `--strict` in user CI, not bundled.
+
+## Consequences
+
+### Positive
+
+- **One name for one concept.** "Link graph" supersedes the ad-hoc mix of `key_links`, body-text refs, and unwritten conventions.
+- **Renames stop being silent breakages.** Moving an ADR or renaming a `.cjs` module produces a finding the next time `validate links` runs.
+- **Bidirectional traceability.** `@pan:` anchors make the implementation-of-an-ADR question answerable from the code side, not only the doc side.
+- **Drop-in for existing infrastructure.** `key_links` keeps working; new lint subsumes it as a special case (frontmatter-declared link is just one shape of forward link).
+- **Zero new runtime dependencies.** Pure CJS + regex + existing walkers.
+- **Composable with `validate health`.** The umbrella health check can call `links validate` once `--full`-style cost is acceptable; intermediate solution is a separate top-level command.
+
+### Negative
+
+- **One more lint to keep green.** Docs with `require-code-mention: true` will fail the lint if their anchor module is deleted; someone must intervene.
+- **Anchors are noise in source files.** A `.cjs` module implementing two ADRs and a spec carries three comment lines. Mitigation: anchors cluster at the top of the file under a single banner; convention documented.
+- **The convention is human-enforced.** Nothing makes contributors place `@pan:` anchors; only the *doc-side* `require-code-mention` flag is enforced. This is deliberate — an over-eager rule ("every module must declare an anchor") would generate noise without improving the graph.
+- **Two link styles coexist for one release.** Existing `must_haves.key_links` regex-based entries and new `[[<id>]]` inline references both pass `validate links`. Migration is opt-in, not forced. Authors of new docs should prefer inline refs; legacy `key_links` continue to work.
+- **Doc-lint coverage expands.** `doc-lint.cjs` and `links.cjs` will overlap. Mitigation: `doc-lint.cjs` continues to handle prose/style; `links.cjs` owns reference integrity. Boundary is "is this about *this file's* shape, or about *cross-file* relationships?"
+
+### Neutral / Tradeoffs considered
+
+- **Why a new module, not an extension of `verify.cjs`?** `verify.cjs` is plan-file-centric (`cmdVerifyKeyLinks`, `cmdVerifyPlanStructure`); the link graph spans all docs and code. A focused module keeps both clean.
+- **Why not a single `[[wiki]]` syntax to replace `key_links`?** `key_links` carries an extra field — a regex pattern — that asserts not just "the file exists" but "the file contains this token." Inline `[[wiki]]` is reference-only. They serve different needs; both stay.
+- **Why `@pan:` and not a runtime-prefixed token (`@pan-claude:`)?** PAN ships into 5 runtimes from one source; the anchor describes a relationship in *PAN-the-tool*'s graph, independent of which runtime the reader is using.
+- **Why opt-in `require-code-mention` rather than scan-everything?** Some docs are aspirational (future ADRs, design notes). Forcing a code mention for every doc in `docs/` would either be spammed with anchors-of-convenience or hold ADRs hostage to implementation status.
+
+## Implementation Notes
+
+### Files added
+
+| File | Purpose |
+|------|---------|
+| `pan-wizard-core/bin/lib/links.cjs` | New core module — graph walker + lint |
+| `commands/pan/links.md` | New command — exposes `links validate` |
+| `tests/links.test.cjs` | Unit tests for forward/backlink/anchor passes |
+| `tests/scenarios/links-graph.test.cjs` | Scenario test — full repo against the lint |
+| `docs/specs/doc_code_link_graph_featureai.md` | Spec (W0 prerequisite) |
+
+### Files modified
+
+- `pan-wizard-core/bin/pan-tools.cjs` — register `links` subcommand.
+- `pan-wizard-core/bin/lib/verify.cjs` — `cmdValidateConsistency` calls into `links.validateAll()` for a graph summary line in `validate health` output (advisory, not blocking).
+- `pan-wizard-core/bin/lib/frontmatter.cjs` — recognize `require-code-mention` as a known field (no parser changes; it's already preserved).
+- `docs/USER-GUIDE.md`, `docs/CLI-REFERENCE.md`, `docs/ARCHITECTURE.md` — document the convention and command.
+- `CLAUDE.md` counts table — module count and command count update on ship.
+
+### Rollout phases
+
+| Phase | Scope | Gate |
+|-------|-------|------|
+| W0 | Spec at `docs/specs/doc_code_link_graph_featureai.md` | Reviewed |
+| W1 | `links.cjs` + dispatcher + unit tests for forward-link & anchor-target passes | All tests green |
+| W2 | Backlink-contract pass + `require-code-mention` opt-in + scenario test | `validate links` green against current repo |
+| W3 | Wire summary line into `validate health` + docs + opt three accepted ADRs into `require-code-mention: true` as the canary | `validate health` shows graph row; canary ADRs have anchors |
+
+`refs` and `expand` follow as separate ADRs (or as v3.8 phases) once the graph itself is trustworthy.
+
+### Rollback plan
+
+Entirely additive. Steps:
+
+- Remove `pan-wizard-core/bin/lib/links.cjs` — `pan-tools links validate` becomes "command not found".
+- Remove the `links.validateAll()` call from `cmdValidateConsistency` — `validate health` returns to its pre-W3 shape.
+- Strip `require-code-mention: true` from the canary ADRs (or leave them; the field is harmless when no lint reads it).
+- `@pan:` comments are valid host-language comments and harmless if the lint is removed.
+
+No schema changes, no manifest changes. Rollback is a commit-level revert.
+
+### References
+
+- Predecessor: `cmdVerifyKeyLinks` in [verify.cjs](../../pan-wizard-core/bin/lib/verify.cjs#L376) — frontmatter-declared link verification (the link graph's first slice)
+- Predecessor: ADR-0021 (Codebase Mapper v2) — established regex-not-AST as the codebase-analysis stance
+- Predecessor: ADR-0026 (Self-Improvement Loop) — established the `learnings/{universal,internal}/` two-tier delivery; its docs become natural opt-in candidates for `require-code-mention`
+- External inspiration: [`1st1/lat.md`](https://github.com/1st1/lat.md) — `// @lat:` annotation convention and `lat check` graph lint. The full project (TS, libsql, tree-sitter, MCP server, embeddings) is rejected; the convention and the lint pattern are adopted.
+- Related infrastructure: [doc-lint.cjs](../../pan-wizard-core/bin/lib/doc-lint.cjs) and the walker in [doc-lint/walk.js](../../pan-wizard-core/bin/lib/doc-lint/walk.js) — reused, not duplicated
+
+## Future scope
+
+- **`pan-tools links refs <doc>`** — reverse query: "what files anchor or reference this doc?" Cheap once the scanner exists; separate ADR or v3.8 phase.
+- **`pan-tools links expand <file>`** — inline `[[<id>]]` content into a prompt before sending to an agent, gated by [context-budget.cjs](../../pan-wizard-core/bin/lib/context-budget.cjs). Replaces a class of "the agent didn't have the ADR loaded" failures.
+- **Auto-anchor suggestion in `pan-optimizer`** — when the optimizer harvests a session that touches `<file>` and a recently-modified ADR, propose an `@pan:` anchor as a learning. Only after the manual graph is stable.
+- **Promote `key_links` to a special-cased forward link** — eventual unification, contingent on a low-friction migration story for existing plan files.
+- **Commit-hook gate** — opt-in via repo-local hooks once the graph has been green for two release cycles.

package/docs/decisions/ADR-0028-unified-agents-skills-target.md

@@ -0,0 +1,46 @@
+# ADR-0028: Unified `.agents/skills/` Build Target
+
+## Status
+Accepted — Phase 1 shipped 2026-06-10 (`--unified-skills` opt-in: runtime-neutral compiler `convertClaudeCommandToUnifiedSkill()`, all five runtimes wired, proprietary-surface sweep, manifest + uninstall integration). Phase 2 substantially shipped same day: shared runtime-neutral core at `.agents/pan-wizard-core/` (skills no longer depend on which runtime installed last) and ref-counted shared-tree uninstall (last tracker removes and prunes). Agent-ref canonicalization shipped 2026-06-11: shared content references canonical agent-definition copies at `.agents/pan-wizard-core/agents/` instead of the installing runtime's agents dir — shared-tree content is now runtime-neutral end to end. Still open before default-on: per-runtime live discovery gates. Phase 3 first half (AGENTS.md universal rules layer) shipped 2026-06-11: local installs contribute a marker-fenced PAN section to the project's AGENTS.md with a CLAUDE.md `@AGENTS.md` bridge and ref-counted uninstall; plugin/marketplace packaging remains. (Promotes item 10 of `docs/ECOSYSTEM-REVIEW-2026-06.md` §4 out of proposal status; supersedes the per-runtime command-tree strategy for command-shaped content.)
+
+## Context
+
+PAN Wizard ships the same command/workflow/reference content to five runtimes by converting it five times into five proprietary layouts (`.claude/commands/`, `.codex/`, `.gemini/`, `.opencode/commands/`, `.github/skills/`). The installer carries a converter, a sweep path, and a manifest section per runtime, and every runtime format change (three of which landed in v3.9.0 alone — Codex, Copilot, OpenCode) is a PAN maintenance event.
+
+Between January and June 2026 the ecosystem converged on the **Agent Skills standard**: a `SKILL.md`-per-directory tree under `.agents/skills/` (project) or `~/.agents/skills/` (user), read natively by all five PAN target runtimes. Two additional facts sharpen the opportunity:
+
+- **PAN already writes the tree.** The v3.9.0 Codex migration (ecosystem review item 7) moved Codex skills to `.agents/skills/` after live verification that the old `$CODEX_HOME/skills` location was dead. The compile-to-skills path exists and is tested; it is simply only wired to one runtime.
+- **Antigravity CLI** (Gemini CLI's successor for individual accounts, effective 2026-06-18) reads `.agents/skills/` natively. The recorded decision (review item 1, 2026-06-10) is to serve Antigravity through this tree rather than build a bespoke sixth runtime — which makes the unified target the *only* planned delivery path for an entire user population, not merely a simplification.
+
+The cost of the status quo is structural: five copies of identical content drift independently, the installer is the largest unfactored surface in the codebase, and each new runtime (Antigravity will not be the last) multiplies the work instead of adding a consumer.
+
+## Decision
+
+Compile command-shaped content — `commands/pan/*.md`, workflow protocols, and agent-loaded references — **once**, into a standard `.agents/skills/` tree, and make that tree the canonical install surface for every runtime. Keep per-runtime conversion only for artifacts that are genuinely runtime-specific:
+
+| Artifact | Strategy |
+|---|---|
+| Commands / workflows / references | **Unified:** one compile pass → `.agents/skills/pan-*/SKILL.md` (project root for `--local`, `~/.agents/skills/` for global) |
+| Agents (subagent definitions) | Per-runtime (formats genuinely differ: Claude markdown, Codex TOML, Copilot `.agent.md`, OpenCode `permission` maps) |
+| Hooks | Per-runtime (event names and schemas differ; see review item 13 for the mapping-table follow-up) |
+| Settings / config / statusline | Per-runtime (documented read paths differ) |
+
+### Rollout gates
+
+1. **Per-runtime verification gate.** A runtime flips from its proprietary command tree to the shared tree only after a live discovery smoke test on that runtime (the standard's adoption claims were corroborated during the June 2026 review, but PAN verifies before building — the Codex migration caught a dead install location exactly this way).
+2. **Opt-in first.** Phase 1 ships behind `--unified-skills`; fresh installs default to it only once all five runtimes pass the gate. Upgrades sweep the legacy per-runtime trees the same way the v3.9.0 Codex migration swept `.codex/skills/pan-*`.
+3. **Frontmatter adapter, not lowest common denominator.** Runtime-specific frontmatter (e.g. Claude's `context: fork`, `allowed-tools`) is emitted into SKILL.md and relied on being ignored by runtimes that don't consume it; anything that *breaks* a runtime's parser is handled by the compile pass, not by forking the content.
+
+### Phasing
+
+- **Phase 1 (v4.0-alpha):** extract the Codex skills-compile path into a runtime-neutral compiler (pure functions, unit-tested); wire all runtimes behind `--unified-skills`; per-runtime live gates.
+- **Phase 2 (v4.0):** default-on for fresh installs; upgrade sweep; manifest consolidation (single `../.agents/skills/` key space — the out-of-tree manifest convention from the Codex migration generalizes).
+- **Phase 3 (v4.x):** the tree becomes the substrate for plugin/marketplace packaging (review item 11) and the `AGENTS.md` universal rules layer (item 14).
+
+## Consequences
+
+**Positive.** One source of truth for command content ends the five-way drift class permanently. The installer's largest conversion surface collapses into one compiler plus thin per-runtime adapters. New runtimes (Antigravity first) become consumers of an existing tree — near-zero marginal cost. Gemini-individual users displaced on 2026-06-18 get full PAN command coverage without a sixth runtime.
+
+**Negative / risks.** A shared tree is a shared failure domain: a compiler bug ships to every runtime at once (mitigated by the per-runtime live gates and the existing scenario-test matrix). Discovery semantics may differ subtly between runtimes (precedence vs. proprietary trees during the transition; the sweep ordering matters). Users who hand-edited installed command files lose those edits in the sweep (same trade accepted in the v3.9.0 Codex migration; patch-backup machinery already skips out-of-tree keys by design and needs extension rather than invention).
+
+**Explicitly out of scope.** Hooks unification (item 13), agent-format unification (no standard exists), MCP-server delivery (item 16).

package/docs/decisions/ADR-0029-experiment-evaluator.md

@@ -0,0 +1,76 @@
+# ADR-0029: Optional LLM Evaluator for the Self-Improvement Runner
+
+## Status
+Proposed — design spike only (IMPROVEMENT-TODO P2). Per its acceptance criteria, **no implementation until this ADR is reviewed and accepted by the maintainer.**
+
+## Context
+
+The v3.7.0 self-improvement loop (`runner.cjs`, `experiment.cjs`, ADR-0026) stops experiments on deterministic signals: process exit, a wall-clock timeout, a circuit breaker, and milestone-completion detection that reads `status:` out of the experiment's `state.md` (`STOP_REASONS`: success / error / timeout / circuit_breaker / manual / incomplete). For experiments whose goal is structural — "does this workflow reach milestone completion?" — this is exactly right.
+
+It is blunt for experiments whose success criterion is genuinely qualitative: *did prompt variant B produce a better plan than variant A? Is the generated summary actually faithful to the diff?* Today those experiments stop on iteration count or timeout, and a human reads the transcripts. Claude Code's `/goal` command demonstrated the worker/evaluator split — a separate small model judging completion after every turn — but it is Claude-only and outside PAN's surface.
+
+The temptation to resist: PAN has spent multiple releases (v3.6 guardrails, the verify/preflight/health work) moving the *planning* lifecycle toward deterministic gates. Reintroducing LLM-as-judge into phase, focus, verify, or retro would be a regression dressed as a feature. The experiment runner is the one subsystem where the work being evaluated is itself probabilistic, so probabilistic judgment is category-appropriate there — and only there.
+
+## Decision
+
+Add an **opt-in, pluggable evaluator** to `runner.cjs`, off by default, with the host runtime's own CLI as the only shipped backend.
+
+### 1. Scope fence
+
+The evaluator is consumed by `runner.cjs` only. `phase`, `focus`, `verify`, `retro`, and every other lifecycle path keep their deterministic gates untouched — this ADR explicitly does not create a precedent. Growing the scope requires a new ADR carrying evidence that a specific deterministic gate demonstrably cannot express the needed check.
+
+### 2. Evaluator contract
+
+```
+evaluate({ transcript, goal }) → { done: boolean, reason: string }
+```
+
+- `transcript`: tail of the experiment transcript (size-capped; newest content wins).
+- `goal`: the experiment's goal condition string, authored in the experiment's `idea.md` frontmatter (`evaluator_goal:`).
+- The verdict and reason are appended to the experiment's run log as `evaluator` events, alongside the existing metrics records — auditable after the fact, consumed by `/pan:learn` like any other signal.
+- A `done: true` verdict stops the run with a new stop reason `evaluator_done`; `done: false` lets it continue. The evaluator can only ever *stop earlier* than the deterministic bounds — the iteration cap and timeout remain the hard ceiling, so a broken evaluator can never extend a run.
+
+### 3. Model access — zero-runtime-dependency posture
+
+Three options were evaluated:
+
+| Option | Verdict |
+|---|---|
+| Anthropic SDK behind a config flag | Rejected — introduces the project's first runtime dependency (even optional, it lands in `package.json` and the supply chain); duplicates auth the host CLI already has. |
+| Shell to the host runtime's CLI | **Adopted.** `runner.cjs` already spawns `claude -p` (and other runtimes via its adapter table) with `spawnSync`; the evaluator reuses the same mechanism, auth, and `billing_pool: "agent_sdk"` tagging. Zero new dependencies. |
+| Pluggable interface, no default backend | Adopted as the shape: the CLI backend is just the default plug. `experiment.evaluator.command` accepts any executable honoring the contract (prompt on argv/stdin, JSON verdict on stdout), so non-Claude hosts or air-gapped users can supply their own. |
+
+Configuration (all under `.planning/config.json` → `experiment.evaluator`):
+
+- `enabled`: `false` (default). Nothing changes for anyone who doesn't opt in.
+- `command`: defaults to the host runtime's CLI in print mode with a small fast model (Haiku-class) — evaluation is a cheap classification call, not reasoning work.
+- `interval`: evaluate every N iterations (default 1), capped by `max_checks` (default = the experiment's iteration cap) so evaluator spend is bounded and predictable.
+- `timeout_ms`: per-call timeout (default 60 000).
+
+### 4. Which experiment shapes qualify
+
+- **Benefit:** prompt-variant comparison, output-quality judgment, "did the agent's answer satisfy this rubric" — anything where the goal lives in natural language and no file/exit-code encodes it.
+- **Must remain deterministic:** any experiment whose success is wired to phase or verify state (milestone completion, plan counts, test results). The runner refuses the evaluator (`config error`) when the experiment also declares a milestone-based success condition — one experiment, one stop authority.
+
+### 5. Failure modes
+
+| Failure | Behavior |
+|---|---|
+| `enabled` but CLI/credentials missing | Warn once at run start, disable for the run, fall back to deterministic stops. The experiment proceeds. |
+| Evaluator call timeout | Log an `evaluator_timeout` event, count it as "not done", continue. |
+| Ambiguous/unparseable response | Treat as "not done", log `evaluator_ambiguous`; after 3 consecutive ambiguous responses, disable for the run with a warning (a misconfigured judge must not silently burn the budget). |
+| Evaluator says done but milestone state disagrees | Not possible by construction — see §4: milestone-governed experiments cannot enable the evaluator. |
+
+Every failure degrades to today's behavior. The evaluator can reduce wasted iterations; it can never make a run less safe than the deterministic bounds.
+
+### 6. Cross-runtime behavior
+
+The runner is the only consumer. With `enabled: false` (the default), non-Claude runtimes see zero change. With it enabled, the `command` is host-agnostic — any CLI honoring the contract works; the Claude default is convenience, not coupling.
+
+## Consequences
+
+**Positive.** Qualitative experiments get a stop condition that matches their nature, bounded by the existing deterministic ceiling. Evaluator verdicts become auditable log events that `/pan:learn` can mine. No new dependencies; no new auth surface; spend rides the already-tagged Agent SDK pool.
+
+**Negative / risks.** An LLM judge is itself probabilistic — verdicts will sometimes be wrong; the mitigation is that wrong verdicts only ever end runs early, never extend them, and the transcript+reason trail makes bad judgments visible. Config surface grows by one section. The "one stop authority" rule (§4) must be enforced in code, not docs, or scope creep starts here.
+
+**Acceptance criteria for implementation (unchanged from IMPROVEMENT-TODO):** behind `experiment.evaluator.enabled`, off by default; no change to phase/focus/verify/retro code paths; documented in `commands/pan/experiment.md` and workflows only after this ADR is accepted.

package/docs/decisions/ADR-0030-planning-concurrency.md

@@ -0,0 +1,37 @@
+# ADR-0030: `.planning/` Concurrency Hardening — Advisory Locks + Atomic Writes
+
+## Status
+Accepted — v1 (best-effort) shipped 2026-06-11: `lock.cjs` primitive (`withFileLock`, `writeFileAtomic`) wired into `writeStateMd()`. Wider adoption and strict mode are the documented escalation path below.
+
+## Context
+
+PAN was designed for one agent driving one project. The fleet/agent-teams era breaks that assumption: parallel exec waves, hierarchical orchestration (`pan-conductor`), and background loops can all touch `.planning/` concurrently. The exposure classes:
+
+1. **Lost updates** — `state.md`, `roadmap.md`, `requirements.md` are read-modify-write: two agents read, both write, one update vanishes. `state.md` is the hottest (every phase/plan transition).
+2. **Torn reads** — a reader catches a half-written file. PAN already hardened readers (`readStateSafe`, null-checked parses), but the write side could still produce the torn state being defended against.
+3. **Append races** — `tokens.jsonl`, bus channels. Single `appendFileSync` calls of one line are effectively atomic on local filesystems; lowest risk, no change needed now.
+
+Constraints: zero runtime dependencies, synchronous CJS call sites, cross-platform (Windows/NTFS + POSIX), and — critically — **no new failure mode for the single-agent majority**.
+
+## Decision
+
+Ship `lock.cjs` with two primitives, applied incrementally:
+
+1. **`writeFileAtomic(path, content)`** — temp file + rename, same directory. Readers never observe a partial file. (Windows rename-over-open-handle refusal falls back to a direct write, preserving today's semantics at worst.)
+2. **`withFileLock(path, fn, opts)`** — advisory `<path>.lock` via atomic exclusive-create (`wx` flag), bounded retry with synchronous sleep (`Atomics.wait` — no busy-wait), and stale-lock stealing (default 10 s — a crashed holder must not deadlock the project).
+
+**v1 semantics are best-effort:** when the lock cannot be acquired within the retry budget (default ~1 s), the critical section runs *unlocked* — exactly today's behavior. Concurrent fleets get lost-update protection in the overwhelmingly common case; single-agent users see zero behavioral change and zero new errors. The return value reports `locked: false` so future callers can escalate.
+
+**First adopter:** `writeStateMd()` — every state.md write now serializes behind `state.md.lock` and lands atomically.
+
+### Escalation path (not yet scheduled)
+
+- Adopt the lock in the other RMW writers (roadmap, requirements, milestone files) — mechanical now that the primitive exists.
+- **Strict mode** behind `.planning/config.json → concurrency.strict`: lock timeout returns `{error: 'lock_timeout'}` instead of falling back, for fleets that prefer failing loudly to last-write-wins.
+- Merge semantics (CRDT-ish section merging) were considered and rejected for now: PAN's files are human-readable markdown with section structure, and a wrong automatic merge is worse than a lost update that `validate consistency` can detect. Revisit only with evidence of real-world contention that locking doesn't solve.
+
+## Consequences
+
+**Positive.** Lost-update and torn-write protection for the hottest file with zero dependencies and zero behavior change for existing users; a reusable primitive the remaining writers can adopt mechanically; stale-steal means crashed agents never wedge a project.
+
+**Negative / risks.** Advisory locks only bind cooperating writers — direct `fs.writeFileSync` calls bypass them (the module-decomposition work makes such sites easy to find). Best-effort fallback means a pathological 40-writer pileup can still lose an update; that is the strict-mode trade, deliberately deferred. Lock files in `.planning/` are transient litter if a process is SIGKILLed mid-hold — bounded by the 10 s stale steal.

package/docs/decisions/ADR-0031-focus-auto-backlog-source.md

@@ -0,0 +1,47 @@
+# ADR-0031: Backlog Source + Parallel-Research/Serial-Build/Parallel-Verify for `/pan:focus-auto`
+
+## Status
+Accepted — 2026-06-12. Folds the genuinely-new ideas from a project-local `/focus-loop` campaign command (built in the MontyHall compiler project) into the existing `/pan:focus-auto` runner, generalized and opt-in.
+
+## Context
+
+`/pan:focus-auto` (ADR-0015) runs continuous improvement campaigns by **scanning the codebase by category** (cleanup / tests / security / …), then looping scan → plan → exec → commit with a 5-layer safety harness and budget/context stops.
+
+A downstream project built its own loop command, `/focus-loop`, that solved three problems focus-auto doesn't:
+
+1. **Work selection from a curated roadmap, not a code scan.** Some campaigns work a human-prioritized backlog (an OUTSTANDING tracker, a roadmap with ranked items) rather than whatever grep finds. Scan-driven selection can't express "do the next-best item from my roadmap."
+2. **Parallelized research/verify around a serial build.** The proven shape is *parallel read-only research → exactly one serial implementer/builder → parallel read-only adversarial verify*. focus-auto runs these sequentially; the Workflow tool now makes the fan-out cheap.
+3. **End-of-loop integrity gate.** Per-item incremental commits can leave cross-item orphans (a symbol defined only in an uncommitted file; a combined state that doesn't build clean). A single clean-build seal at loop end, plus staging-miss and orphan audits at commit time, catch this class.
+
+That command was **~70% identical to focus-auto** and **deeply project-specific** in its content — hardcoded item IDs, test counts, build scripts, dual-platform Windows/Linux build trees, and a "builds must be serial because two corrupt the shared tree" premise that is a property of *that* project, not a universal one. Shipping it verbatim would have been the worst runtime-agnosticism violation in PAN's command set, and a near-duplicate of an existing command.
+
+## Decision
+
+Adopt the three ideas as **generalized, opt-in extensions to `/pan:focus-auto`** — not a second loop command.
+
+### 1. `--source scan|backlog` (default `scan`)
+
+- `scan` — today's behavior: category-scoped code scan via `focus scan`.
+- `backlog` — rank actionable items from PAN's existing planning surface (`roadmap.md` phase/item checkboxes, `requirements.md` REQ rows) by `(UserValue + TimeCriticality + RiskReduction) / Effort`, derived from the *current* document so the order never goes stale. No project-specific item-ID lists are ever hardcoded; the ranking reads whatever the roadmap contains.
+
+`source` is stored in the auto-run state (`.planning/focus/auto-run.json`) and validated against `FOCUS_SOURCES`.
+
+### 2. Optional Workflow-parallel research/verify (opt-in)
+
+- `--parallel-research` / `--parallel-verify` — when set, the per-item research and verify stages fan out via the Workflow tool (read-only agents); the implement/exec stage stays a single agent. Default off → today's sequential behavior, so nothing changes for existing users.
+- The **serial-build invariant** (at most one builder at a time) is honored only when the project declares a shared-build-tree constraint in `.planning/config.json` (`concurrency.serial_build: true`). It is **off by default** — most projects build in parallel safely. This is the key generalization: the MontyHall command treated serial-build as a universal law; PAN treats it as a per-project opt-in.
+
+### 3. Opt-in integrity gates
+
+- `--clean-seal` — after the loop's last item, run one clean build + full verification (commands come from `config.json → verification`/`build`, never hardcoded) to catch cross-item orphans. Off by default.
+- **Staging-miss guard** and **orphan audit** at commit time — generalizable commit-quality checks (no implementer-touched file left unstaged; HEAD references no symbol defined only in an uncommitted file). These are advisory checks the runner already has the information to perform.
+
+### What is explicitly NOT adopted
+
+Everything project-specific from `/focus-loop`: hardcoded ADR/item IDs, test counts, build/factory scripts, dual-platform assumptions, hardcoded attribution (PAN uses `processAttribution`), and the "serial-build is mandatory" premise. The MontyHall `/focus-loop` stays a correct, project-local command — that is the right home for content that specific.
+
+## Consequences
+
+**Positive.** One runner gains backlog-driven campaigns and an optional parallel pipeline without a duplicate command; the new commit/seal gates improve commit quality for any project; the serial-build constraint is available to projects that need it (declared, not assumed). The pattern itself is promoted as a universal learning (`learnings/universal/`) so it informs planning even where the flags aren't used.
+
+**Negative / risks.** focus-auto's command doc grows; the backlog ranker depends on roadmap/requirements being maintained (degrades to "no actionable items" when they aren't, which is a correct stop condition). Parallel research/verify only helps when the host runtime has the Workflow tool — it's a no-op fallback to sequential elsewhere.