pan-wizard 3.25.0 → 3.26.0

package/pan-wizard-core/learnings/internal/experiment-runner.md

@@ -1,81 +0,0 @@
----
-topic: experiment-runner
-last_updated: 2026-05-03T03:30:13.038Z
-patterns:
-  - id: P-EXP-001
-    summary: new-project --auto can finish all artifacts but never commit if the run ends before the workflow's commit step (1 of 5 experiments hit this)
-    promoted_at: 2026-05-02T14:35:52.700Z
-    source_experiments: [whoocache]
-  - id: P-EXP-002
-    summary: claude -p exits at phase boundaries despite --auto and prose-based DO NOT exit (v3.7.6 cross-phase YOLO continuation fix), so multi-phase autonomous runs need one invocation per phase
-    promoted_at: 2026-05-02T14:35:59.399Z
-    source_experiments: [whoolog, whoocache, whooflow, whooschema, whoodb]
-  - id: P-EXP-003
-    summary: state.md YAML frontmatter is the authoritative truth; body prose may lag after phase completion
-    promoted_at: 2026-05-02T14:36:04.863Z
-    source_experiments: [whooschema, whoolog, whoocache]
-  - id: P-EXP-004
-    summary: 30-min DEFAULT_TIMEOUT_MS is too short for typical 3-plan phases; recommend 60+ min default
-    promoted_at: 2026-05-02T14:36:15.357Z
-    source_experiments: [whoolog]
-  - id: P-EXP-005
-    summary: 4 concurrent claude -p experiment sessions run cleanly on a single machine; no TTY contention or rate-limit issues
-    promoted_at: 2026-05-02T14:36:22.170Z
-    source_experiments: [whoolog, whoocache, whooflow, whooschema, whoodb]
-  - id: P-NPRS-005
-    summary: Single experiment can ship a 24-plan / 5-phase / 346-test / 1.46MB binary milestone in ~6h cumulative agent runtime when the planner emits decision-trace + the executor honors per-plan file ownership
-    promoted_at: 2026-05-03T03:30:13.038Z
-    source_experiments: [notepadrs]
----
-
-# Experiment Runner (AI-derived)
-
-> Auto-maintained by `pan-tools learn promote`. Each pattern was extracted from one or more experiment runs (see source_experiments). Patterns are **advisory** — orchestrators should weight them against current context.
-
-## P-EXP-001 — Missing git identity in fresh experiment folder causes silent commit failures (whoocache root cause)
-
-**Evidence:** whoocache: 24 min of work produced project.md, requirements.md, roadmap.md, src/{cache,atomic-write,lock,...}.js — but git log empty. **Root cause** found in summary.md: "Git identity was not configured in this environment; per environment_notes the commits returned `committed: false` with `reason: 'commit_failed'`. File outputs landed on disk (the contract). Commits can be re-run later by the user once `git config user.email / user.name` are set." `pan-tools commit` returns exit-0 with `{committed: false, reason: 'commit_failed'}` — the autonomous loop sees no error and keeps going. State.md showed Phase 1 ready. Resumed phase commands committed normally from then on, after identity was set.
-
-**Rule:** experiment scaffolding (`pan-tools experiment new`) MUST `git init` the folder AND configure `user.email` / `user.name` (inherited from PAN source repo, falling back to placeholders) so the autonomous loop's commits don't silently fail. Fixed in `experiment.cjs initExperimentGit()` v3.7.9. As a defensive layer, `new-project.md` section 8.9 also adds an end-of-workflow safety-net commit. As a hardening item, consider making `pan-tools commit` exit non-zero on `commit_failed` so callers detect the failure mode.
-
-**Applies in:** experiment.cjs scaffolder, new-project workflow, any tooling that wraps `pan-tools commit` in a fresh git environment
-
-## P-EXP-002 — claude -p exits at phase boundaries despite --auto and prose-based DO NOT exit (v3.7.6 cross-phase YOLO continuation fix), so multi-phase autonomous runs need one invocation per phase
-
-**Evidence:** All 5 experiments (whoolog, whoocache, whooflow, whooschema, whoodb) exited cleanly with exit_code=0 status=incomplete at every Phase N -> Phase N+1 boundary. Each phase needed a separate experiment run --prompt invocation. Even though state.md shows current_phase advanced and last_activity says transitioned to Phase N+1, the spawned claude session ends.
-
-**Rule:** Treat the autonomous cross-phase chain as best-effort, not guaranteed. Scripts/CI/runners should plan for one /pan:plan-phase N --auto invocation per phase. Single-invocation multi-phase runs are a stretch goal, not the contract.
-
-**Applies in:** any autonomous multi-phase run via claude -p, codex exec, gemini -p, opencode
-
-## P-EXP-003 — state.md YAML frontmatter is the authoritative truth; body prose may lag after phase completion
-
-**Evidence:** whooschema after Phase 3 completion: frontmatter showed completed_phases=3 status=completed, but body still showed Current phase 1 - Foundation, Phase 1 Executed. Same pattern observed in whoolog and whoocache to lesser degree.
-
-**Rule:** When reading state.md programmatically (from runner.cjs, status checks, harvest scripts), parse the YAML frontmatter fields (completed_phases, current_phase, status). The body's Current Position / Phase Status sections sometimes do not re-render after phase completion. Prefer frontmatter parsers over markdown text scans.
-
-**Applies in:** runner.cjs status checks, state.md consumers, anything reading state programmatically
-
-## P-EXP-004 — 30-min DEFAULT_TIMEOUT_MS is too short for typical 3-plan phases; recommend 60+ min default
-
-**Evidence:** whoolog Phase 1 first run: timed out at 30:00 after Phase 1 research only (9 commits). Resumed with 90-min timeout and finished Phase 1 fully in 26 minutes. Same pattern would have killed whooflow new-project (~60 min) if that timeout had been the default.
-
-**Rule:** DEFAULT_TIMEOUT_MS in runner.cjs should be raised from 30 min to 60 min, OR the experiment new command should set a per-experiment timeout based on roadmap.phase_count * 8 min after the new-project run. Phase 1 of whoolog (3 plans) took 26 min; whooflow (5 plans per phase) was at 35 min when killed by 30-min cap on first run. The default cuts off real work mid-phase.
-
-**Applies in:** runner.cjs DEFAULT_TIMEOUT_MS, experiment run --timeout default
-
-## P-EXP-005 — 4 concurrent claude -p experiment sessions run cleanly on a single machine; no TTY contention or rate-limit issues
-
-**Evidence:** Ran whoolog Phase 2 + whoocache Phase 1 + whooflow new-project + whooschema new-project + whoodb new-project all in parallel for ~60 minutes. All 4 concurrent sessions made independent progress, no failures, no missed commits attributable to concurrency. Wall-clock time for full 5-experiment run: ~3 hours (vs ~9 hours sequential).
-
-**Rule:** The experiment runner can safely fan out to N=4 concurrent autonomous experiments on a single workstation. The runner's stdio ['inherit', 'pipe', 'pipe'] design holds up because claude -p does not actually CONSUME stdin (only probes for TTY). API rate limits at this concurrency are not hit on Anthropic Claude Opus 4.7. Beyond N=4, untested.
-
-**Applies in:** experiment runner, automated multi-experiment campaigns, CI
-
-## P-NPRS-005 — Single experiment can ship a 24-plan / 5-phase / 346-test / 1.46MB binary milestone in ~6h cumulative agent runtime when the planner emits decision-trace + the executor honors per-plan file ownership
-
-**Evidence:** notepadrs experiment 2026-05-02→03: Phase 1 (4 plans, 18 tests) ran clean; Phase 2 (4 plans, 109 tests cumulative) ran clean; Phase 3 (5 plans, multi-tab + find/replace + worker thread + epoch cancellation) timed out at 90 min on first attempt at 77% — resumed cleanly with /pan:exec-phase 3 --auto and finished in 45 min; Phase 4 (5 plans split mid-run from 4 to handle wave-2 collision) took 50 min; Phase 5 (5 plans + dogfood + ship gate) took 55 min plan + 7 min finish wrap. Total cumulative: ~6h agent time including 1 timeout. Final binary: 1.46 MB (6.86× under the 10MB ship gate); 346 tests (11.5× the 30-test floor). Plan-checker iteration revisions caught wave-2 file collisions BEFORE execution; reasoning-trace handoff via Plan Decisions / Implementation Decisions sections kept context coherent across plan-checker → executor → verifier.
-
-**Rule:** Auto-mode multi-phase experiments DO complete v1-shippable software in roughly 1 hour per phase IF: (a) phase plan-phase produces explicit per-plan files_modified ownership AND a decisions buckets section; (b) plan-checker is allowed to iterate (split plans, revise files_modified) BEFORE execution starts; (c) timeouts are 90 min per command, not 60 min; (d) when a phase times out at >70% complete, resume with /pan:exec-phase N --auto rather than restarting plan-phase; (e) final phase wrap (write missing summary.md + verification.md, advance state) sometimes needs a separate short prompt because the auto-runner exits when state.md says 'verifying'. The 'incomplete' status with exit_code 0 means the agent left work mid-state, not that anything failed.
-
-**Applies in:** PAN experiment-runner orchestration; the experiment.cjs runner; auto-mode workflow guidance; planner/executor handoff design

package/pan-wizard-core/learnings/internal/external-research.md

@@ -1,105 +0,0 @@
----
-topic: external-research
-last_updated: 2026-07-09T14:04:40.520Z
-patterns:
-  - id: P-RES-001
-    summary: ACE (Zhang et al, arXiv:2510.04618, Oct 2025): summary-based context chains have brevity bias and context collapse. Treat memory as append-and-curate playbook, not paraphrase chain
-    promoted_at: 2026-05-02T18:15:25.976Z
-    source_experiments: [external]
-  - id: P-RES-002
-    summary: Chroma context-rot (July 2025): a single semantically-similar-but-irrelevant distractor degrades performance even at modest context sizes. Distractor density matters more than token count
-    promoted_at: 2026-05-02T18:15:32.003Z
-    source_experiments: [external]
-  - id: P-RES-003
-    summary: Cognition (June 2025) anti-multi-agent argument: parallel sub-agents fail because every action carries unstated decisions; downstream agents reconcile contradictions blindly when they only see artifacts
-    promoted_at: 2026-05-02T18:15:39.391Z
-    source_experiments: [external]
-  - id: P-RES-004
-    summary: Specification Gap paper (arXiv:2603.24284, early 2026): two-agent integration accuracy collapses 58 to 25 percent as spec detail is removed; coordination is quadratically sensitive to spec completeness
-    promoted_at: 2026-05-02T18:15:50.213Z
-    source_experiments: [external]
-  - id: P-RES-005
-    summary: GitHub PR audit (arXiv:2601.15195, Jan 2026): agent PRs fail mostly from spec/intent mismatch, design fit, and repo-norm violation — not buggy code. Code that compiles and tests still gets rejected
-    promoted_at: 2026-05-02T18:15:58.959Z
-    source_experiments: [external]
-  - id: P-RES-006
-    summary: S2R / RLVR (ACL 2025): naive self-critique is largely ineffective; verification gains come from FRESH-CONTEXT RESTART and FILE-MEDIATED STRUCTURE forcing re-reading, not from the judging itself. Verbose self-review can hurt via overthinking
-    promoted_at: 2026-05-02T18:16:09.893Z
-    source_experiments: [external]
-  - id: P-RES-007
-    summary: Sakana DGM (2025): in self-improvement loops, AGENT-DESIGN changes generalize across models and languages; PROMPT-FRAGMENT tweaks do not. Promote structural changes, not phrasing tweaks
-    promoted_at: 2026-05-02T18:16:19.459Z
-    source_experiments: [external]
-  - id: P-RES-008
-    summary: Enterprise "train on our data" asks are retrieval problems, not fine-tuning problems: schema/context LINKING is the bottleneck (BEAVER: SOTA ~10.8% on real enterprise schemas vs 80%+ on public benchmarks, ~68% of failures are schema-linking), and plain BM25 RAG beats fine-tuning alone (Tencent 160k-file study: 53.8% vs 44.2% EM; FT alone caused catastrophic forgetting; FT+RAG best at 57.4%)
-    promoted_at: 2026-07-09T14:04:40.520Z
-    source_experiments: [spec-factory]
----
-
-# External Research (AI-derived)
-
-> Auto-maintained by `pan-tools learn promote`. Each pattern was extracted from one or more experiment runs (see source_experiments). Patterns are **advisory** — orchestrators should weight them against current context.
-
-## P-RES-001 — ACE (Zhang et al, arXiv:2510.04618, Oct 2025): summary-based context chains have brevity bias and context collapse. Treat memory as append-and-curate playbook, not paraphrase chain
-
-**Evidence:** https://arxiv.org/abs/2510.04618 — ACE: Agentic Context Engineering. Empirical: iterative summarization monotonically loses detail on agent and finance benchmarks; structured playbook curation outperforms across runs.
-
-**Rule:** Reframe memory/<agent>.md and per-phase summary.md as a structured DELTA-LOG (curated by an explicit reviewer step) rather than a paraphrase of the prior phase. Each entry is an addition or amendment to a structured field, not a fresh re-summarization. Curation is its own step, distinct from generation. The pan-optimizer's accrual model should be re-examined under this lens — does it append signal, or summarize away signal?
-
-**Applies in:** pan-optimizer accrual loop, memory.cjs, summary.md template design, retro --write-memory
-
-## P-RES-002 — Chroma context-rot (July 2025): a single semantically-similar-but-irrelevant distractor degrades performance even at modest context sizes. Distractor density matters more than token count
-
-**Evidence:** https://www.trychroma.com/research/context-rot — Hong & Huber, July 2025. Single-distractor experiments showed degradation begins well before 200K, and is non-linear with arrangement and similarity.
-
-**Rule:** Per-phase context budgets currently track tokens. Add a notion of distractor density: how much of context.md / research.md is plausibly-related-but-off-topic. Codebase mapper and phase researcher should optimize for relevance ratio, not coverage. The phase-budget command should warn when the relevance ratio is low even if token count is healthy.
-
-**Applies in:** phase-budget, codebase scan filtering, research agent guidance
-
-## P-RES-003 — Cognition (June 2025) anti-multi-agent argument: parallel sub-agents fail because every action carries unstated decisions; downstream agents reconcile contradictions blindly when they only see artifacts
-
-**Evidence:** https://cognition.ai/blog/dont-build-multi-agents — Walden Yan, Cognition. Contrast https://www.anthropic.com/engineering/multi-agent-research-system which argues breadth-first reads parallelize fine but writes/decisions need a single coherent trace.
-
-**Rule:** PAN's serial pipeline (planner -> researcher -> executor -> verifier) is what Cognition endorses, but file-mediated handoff passes only OUTPUTS, not reasoning traces. Consider: should plan.md include an explicit decisions-and-rationale section that the executor reads, beyond just the task list? Should summary.md include a deviations log that the verifier reads? The signal is: when an agent is briefed for a downstream phase, the upstream agent's reasoning trace should be available, not just the artifacts.
-
-**Applies in:** plan.md template, summary.md template, executor briefing, conductor briefing
-
-## P-RES-004 — Specification Gap paper (arXiv:2603.24284, early 2026): two-agent integration accuracy collapses 58 to 25 percent as spec detail is removed; coordination is quadratically sensitive to spec completeness
-
-**Evidence:** https://arxiv.org/abs/2603.24284v1 — The Specification Gap. Two-agent integration: 58 percent accuracy with full spec, 25 percent with stripped spec. Single-agent baseline: 89 to 56 percent. Coordination cost of incomplete specs is quadratic.
-
-**Rule:** pan-plan-checker currently verifies plan COHERENCE across 8 dimensions. Add a 9th: spec-sufficiency-for-handoff. Question to answer: does this plan contain enough detail that the executor cannot make a divergent decision in the implicit space the plan does not constrain. The check is not is-the-plan-good but is-the-plan-complete-enough-to-survive-the-context-boundary. Specifically: every task has explicit Files, explicit Action, explicit Verify, explicit Done; every architectural choice is locked vs flexible; every assumption is named.
-
-**Applies in:** agents/pan-plan-checker.md (existing 8 verification dimensions), plan.md template (forcing locked-vs-flexible markers)
-
-## P-RES-005 — GitHub PR audit (arXiv:2601.15195, Jan 2026): agent PRs fail mostly from spec/intent mismatch, design fit, and repo-norm violation — not buggy code. Code that compiles and tests still gets rejected
-
-**Evidence:** https://arxiv.org/abs/2601.15195 — Where Do AI Coding Agents Fail. 33K-PR audit. Primary failure modes: spec/intent mismatch (32 percent), design fit (24 percent), repo-norm violation (19 percent). Buggy code is a minority cause of rejection.
-
-**Rule:** pan-verifier currently checks code-against-plan. The dominant external-world failure is fit-against-repo-norms (style, naming, prior-PR conventions, framework idioms). Verifier should treat codebase/CONVENTIONS.md and codebase/STRUCTURE.md (when they exist from /pan:map-codebase) as first-class verification inputs, not advisory context. project.md and requirements.md may need a Norms section the verifier explicitly tests against. The verification dimensions should add: does this code follow the conventions evident in adjacent files.
-
-**Applies in:** agents/pan-verifier.md, agents/pan-reviewer.md, codebase/CONVENTIONS.md consumption, project.md template
-
-## P-RES-006 — S2R / RLVR (ACL 2025): naive self-critique is largely ineffective; verification gains come from FRESH-CONTEXT RESTART and FILE-MEDIATED STRUCTURE forcing re-reading, not from the judging itself. Verbose self-review can hurt via overthinking
-
-**Evidence:** https://aclanthology.org/2025.acl-long.1104.pdf — S2R. https://magazine.sebastianraschka.com/p/state-of-llms-2025 — Raschka summary. Untrained self-critique provides little gain on reasoning; verification helps when verifier has training or runs against verifiable rewards.
-
-**Rule:** PAN has multiple judgment-style verification roles: pan-plan-checker (judges plan coherence), pan-meta-reviewer (judges other reviewers), pan-hardener (judges security risk by inspection). The S2R finding suggests these roles' value is mostly the FRESH-CONTEXT structural reset, not the judgment per se. Implication: lean these agents harder on VERIFIABLE signals (test cmd, lint cmd, schema check, type check, dep cycle scan, regex anti-pattern detection) and reduce prose-only verdicts. Where a verifiable check exists, use it instead of prose review. Where one doesn't, ask whether the role earns its compute.
-
-**Applies in:** agents/pan-plan-checker.md, agents/pan-verifier.md, agents/pan-reviewer.md, agents/pan-meta-reviewer.md, agents/pan-hardener.md, references/verification-patterns.md
-
-## P-RES-007 — Sakana DGM (2025): in self-improvement loops, AGENT-DESIGN changes generalize across models and languages; PROMPT-FRAGMENT tweaks do not. Promote structural changes, not phrasing tweaks
-
-**Evidence:** https://sakana.ai/dgm/ — Darwin Godel Machine. Population-based self-improvement showed structural changes transferred across models; specific prompt tweaks did not. The same generalization curve likely holds for human-mediated promote gates.
-
-**Rule:** When pan-tools learn promote runs (manual gate today, possibly auto-promote in v3.8+), the promote criterion should distinguish: 1) STRUCTURAL pattern (a new agent role, a new file in .planning/, a new verification gate, a new tool-use idiom, an architectural decision) vs 2) PROMPT-FRAGMENT (specific phrasing, a worded instruction, a stylistic preference). Universal scope should be reserved for structural patterns. Prompt fragments belong in internal scope at most — they don't generalize across models or languages, so shipping them to all 5 runtimes is a bet that won't pay.
-
-**Applies in:** pan-tools learn promote --scope universal gate, optimize.cjs promotePattern criteria, future auto-promote rules
-
-## P-RES-008 — Enterprise "train on our data" asks are retrieval problems, not fine-tuning problems: schema/context LINKING is the bottleneck (BEAVER: SOTA ~10.8% on real enterprise schemas vs 80%+ on public benchmarks, ~68% of failures are schema-linking), and plain BM25 RAG beats fine-tuning alone (Tencent 160k-file study: 53.8% vs 44.2% EM; FT alone caused catastrophic forgetting; FT+RAG best at 57.4%)
-
-**Evidence:** The the tech-spec factory tech-spec factory research roadmap (adversarially verified, with citations) synthesized: on BEAVER (real enterprise schemas) SOTA agents collapse to ~10.8%; roughly 68% of failures are schema-linking, not generation. The Tencent 160k-file study showed plain BM25 retrieval beating fine-tuning alone (53.8 vs 44.2 EM) with fine-tuning alone causing catastrophic forgetting. Design consequence adopted there: never dump a full schema into context — decompose into semantic units, hybrid-retrieve a small candidate set (~50), then resolve to physical names.
-
-**Rule:** When a project asks to "train the model on our data/schema": default to retrieval-first (decompose corpus into semantic units, hybrid lexical+semantic retrieval of a small candidate set, then resolve). Treat fine-tuning as an additive step at most, never the substitute. Size context by retrieved candidates, not by dumping the schema. Expect public-benchmark performance claims to overstate enterprise reality by up to an order of magnitude.
-
-**Applies in:** Research/planning phases for RAG or fine-tune decisions, enterprise schema tooling, context-budget design.

package/pan-wizard-core/learnings/internal/loop-design.md

@@ -1,33 +0,0 @@
----
-topic: loop-design
-last_updated: 2026-05-03T05:00:00.000Z
-patterns:
-  - id: P-1303
-    summary: Exercising PAN's actual surfaces (autonomous run) produces orders-of-magnitude more PAN-relevant signal than building parallel tools — even when shorter
-    promoted_at: 2026-04-27T11:21:36.814Z
-    source_experiments: [panloop]
-  - id: P-1403
-    summary: Track wall-clock-per-commit and tokens-per-commit as autonomous-overhead metrics
-    promoted_at: 2026-04-27T12:01:14.269Z
-    source_experiments: [panloop]
----
-
-# Loop Design (PAN-internal)
-
-> Auto-maintained by `pan-tools learn promote`. Each pattern was extracted from one or more experiment runs (see source_experiments). Internal-scope patterns are PAN-specific and stay in the source repo (stripped at install). Patterns are **advisory** — orchestrators should weight them against current context.
-
-## P-1303 — Exercising PAN's actual surfaces (autonomous run) produces orders-of-magnitude more PAN-relevant signal than building parallel tools — even when shorter
-
-**Evidence:** Single 25-second autonomous run (panloop) surfaced 2 critical real PAN bugs (P-1301 AskUserQuestion gap, P-1302 runner permissions gap). Compare: 8 prior hand-built mock experiments (whoocsv, whoojson, whooemoji, whoocron, whoohash, whoouuid, whoodag, whoofreq) totaling many hours produced 0 PAN-internal findings — only generic engineering patterns. The autonomous loop validates its own design hypothesis: hitting real surfaces > simulating them.
-
-**Rule:** When designing self-improvement loops or eval frameworks, the experiments must EXERCISE the system being optimized, not BUILD PARALLEL artifacts. A 25-second real run beats hours of mock work for surfacing system-internal bugs. For PAN specifically: future experiments should run /pan:new-project, /pan:plan-phase, /pan:exec-phase, /pan:focus-* against fresh test projects via the runner, not build standalone CLIs alongside. The mock builds have value for promoting GENERIC patterns; only autonomous runs surface PAN-INTERNAL ones.
-
-**Applies in:** self-improvement loop design (ADR-0026 update); v3.8+ planning; promote-step heuristics
-
-## P-1403 — Track wall-clock-per-commit and tokens-per-commit as autonomous-overhead metrics
-
-**Evidence:** panloop: 25 commits in 29 min = 1.16 min/commit. Cost $12.84 / 25 commits = $0.51/commit. Useful baseline for future optimization.
-
-**Rule:** PAN's /pan:learn report should compute and surface (a) commits_per_minute, (b) cost_usd_per_commit, (c) cost_usd_per_phase, (d) cost_usd_per_test, by reading harvest.json + git log + harvested cost data. Trend over experiments shows whether autonomous overhead is improving as patterns saturate.
-
-**Applies in:** v3.8+ pan-optimizer agent prompt; harvest.json schema extension

package/pan-wizard-core/learnings/internal/pan-dev-bugs.md

@@ -1,181 +0,0 @@
----
-topic: pan-dev-bugs
-last_updated: 2026-04-27T14:36:56.341Z
-patterns:
-  - id: P-101
-    summary: experiment.cjs newExperiment does not persist status='ready' update after installer success
-    promoted_at: 2026-04-27T09:26:39.526Z
-    source_experiments: [whooo]
-  - id: P-102
-    summary: runner.cjs spawnSync fails on Windows for CLI tools without explicit .cmd resolution
-    promoted_at: 2026-04-27T09:26:39.618Z
-    source_experiments: [whooo]
-  - id: P-301
-    summary: PAN's commands/pan/*.md has 9 real frontmatter consistency bugs surfaced by the whooo dogfood gate
-    promoted_at: 2026-04-27T09:49:20.847Z
-    source_experiments: [whooo]
-  - id: P-1301
-    summary: /pan:new-project --auto workflow invokes AskUserQuestion for depth/execution/git-tracking despite --auto, blocking autonomous runs
-    promoted_at: 2026-04-27T11:21:36.615Z
-    source_experiments: [panloop]
-  - id: P-1302
-    summary: runner.cjs claude adapter must include --dangerously-skip-permissions for autonomous runs
-    promoted_at: 2026-04-27T11:21:36.712Z
-    source_experiments: [panloop]
-  - id: P-1304
-    summary: runner.cjs spawnSync with shell:true on Windows doesn't quote multi-word args; cmd.exe re-splits them
-    promoted_at: 2026-04-27T11:38:25.897Z
-    source_experiments: [panloop]
-  - id: P-1401
-    summary: Lightweight phases (scaffolding-only, single plan) over-ceremonialize: 5 commits + 5-7 min for trivial work
-    promoted_at: 2026-04-27T12:01:14.083Z
-    source_experiments: [panloop]
-  - id: P-1402
-    summary: Per-phase researcher re-derives material already covered by project-level research
-    promoted_at: 2026-04-27T12:01:14.179Z
-    source_experiments: [panloop]
-  - id: P-1404
-    summary: Auto-trace SubagentStop hook covers only some agents — pan-roadmapper logged but pan-planner/executor/verifier did not
-    promoted_at: 2026-04-27T12:01:14.367Z
-    source_experiments: [panloop]
-  - id: P-1501
-    summary: claude -p autonomous session exits after Phase 0 setup; multi-step workflows don't drive headless mode forward without explicit tool calls
-    promoted_at: 2026-04-27T12:11:40.314Z
-    source_experiments: [panloop2]
-    superseded_by: P-1501-r3
-    supersession_note: Original P-1501 hypothesis (workflows don't drive headless forward) was refined by P-1501-r2 (no-TTY root cause) and again by P-1501-r3 (TTY chain inheritance, stdio:'inherit' insufficient). Latest current rule lives at P-1501-r3.
-  - id: P-1502
-    summary: runner.cjs exit_code=0 is too coarse — should validate milestone-completion before declaring success
-    promoted_at: 2026-04-27T12:11:40.408Z
-    source_experiments: [panloop2]
-  - id: P-1701
-    summary: Multi-phase (3+) autonomous workflows exit at phase boundaries with /clear-and-rerun instructions; loop is autonomous WITHIN a phase, not across phases
-    promoted_at: 2026-04-27T12:43:48.397Z
-    source_experiments: [panmd2]
-  - id: P-1501-r2
-    summary: P-1501 root cause refined: runner.cjs spawnSync({stdio:[ignore,pipe,pipe]}) lacks TTY; manual bash invocation has TTY; claude -p detects no-TTY and exits after first response loop
-    promoted_at: 2026-04-27T12:43:48.469Z
-    source_experiments: [panmd2]
-    superseded_by: P-1501-r3
-    supersession_note: stdio:'inherit' fix proposed here turned out to be insufficient when the grandparent itself lacks TTY — see P-1501-r3.
-  - id: P-1501-r3
-    summary: P-1501 stdio:'inherit' fix is INSUFFICIENT when the grandparent (script/CI/tool) has no TTY itself
-    promoted_at: 2026-04-27T14:36:56.341Z
-    source_experiments: [panmd3]
----
-
-# Pan Dev Bugs (AI-derived)
-
-> Auto-maintained by `pan-tools learn promote`. Each pattern was extracted from one or more experiment runs (see source_experiments). Patterns are **advisory** — orchestrators should weight them against current context.
-
-## P-101 — experiment.cjs newExperiment does not persist status='ready' update after installer success
-
-**Evidence:** whooo experiment: after successful installer run, in-memory manifest had status='ready' but the file write in newExperiment skipped the persistence. On-disk experiment.json shows status='scaffolded'.
-
-**Rule:** In experiment.cjs newExperiment: after manifest.status='ready' assignment (line ~155 in v3.7.0), add fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2)) to persist the success status. 3-line fix; ship as v3.7.1.
-
-**Applies in:** experiment.cjs maintenance, v3.7.x patches
-
-## P-102 — runner.cjs spawnSync fails on Windows for CLI tools without explicit .cmd resolution
-
-**Evidence:** whooo experiment: tried to spawn node via runtime-override; got ENOENT on Windows because spawnSync with shell:false doesn't resolve .cmd shims. Forced fallback to direct build instead of subprocess invocation.
-
-**Rule:** In runner.cjs runExperiment: on Windows, either set shell:true OR resolve adapter.bin to its .cmd/.exe equivalent before spawnSync. Currently the runner is unusable on Windows for any CLI tool that ships only as .cmd (claude, gemini, codex via npx, etc.).
-
-**Applies in:** runner.cjs cross-platform fix; v3.7.x patches
-
-## P-301 — PAN's commands/pan/*.md has 9 real frontmatter consistency bugs surfaced by the whooo dogfood gate
-
-**Evidence:** whooo dogfood final report (51ms across 52 files): optimize.md missing frontmatter; patches.md missing name field plus description as array; phase-tests.md uses multi-line block-scalar values; todo-add.md and todo-check.md have description as array (should be string). Reproducible via: node bin/whooo.js lint --dir d:/PanWizard/commands/pan --schema test/fixtures/pan-cmd.schema.yml
-
-**Rule:** Ship a v3.7.x patch fixing the 9 known consistency issues in PAN's commands/pan/. Vendor whooo (or write equivalent) and add pan-tools doc-lint to the /pan:check flow so future drift is caught at author time, not by users at install.
-
-**Applies in:** v3.7.x patch planning; /pan:check workflow extension; commands/pan/ maintenance
-
-## P-1301 — /pan:new-project --auto workflow invokes AskUserQuestion for depth/execution/git-tracking despite --auto, blocking autonomous runs
-
-**Evidence:** panloop sess-real-loop-2026-04-27 11:17:45Z error (critical): claude -p result includes permission_denials with tool_name=AskUserQuestion + 3 questions (Depth, Execution, Git Tracking). Workflow stalled after 5 turns / 910 output tokens / $0.33. The first real autonomous loop run (the loop's own design hypothesis) is blocked by this.
-
-**Rule:** Audit pan-wizard-core/workflows/new-project.md auto-mode handling. When --auto is set, AskUserQuestion calls must be replaced with: (a) defaults from config.json, (b) overrides from idea.md frontmatter (e.g. planning_depth: quick), or (c) inferred values from idea content. Same audit applies to any other PAN workflow with an --auto/--yes/--non-interactive flag (plan-phase, milestone-new, etc.). Ship as v3.7.2 patch — this blocks the v3.7.0 self-improvement loop's own design intent.
-
-**Applies in:** pan-wizard-core/workflows/new-project.md auto-mode block; v3.7.2 patch planning; audit of all --auto-flagged workflows
-
-## P-1302 — runner.cjs claude adapter must include --dangerously-skip-permissions for autonomous runs
-
-**Evidence:** panloop sess-real-loop-2026-04-27: claude -p WITHOUT this flag prompts for tool permissions, can't be answered in headless mode, exits 1 silently. Manual reproduction with the flag added: workflow proceeds to AskUserQuestion (separate finding P-1301)
-
-**Rule:** In pan-wizard-core/bin/lib/runner.cjs RUNTIME_RUNNERS, add extraArgs: ['--dangerously-skip-permissions'] to the claude adapter (and equivalent flags for codex/gemini/opencode). The runner's purpose is autonomous execution — defaulting to interactive permission prompts contradicts the runner's design. Optionally gate behind opts.skipPermissions=true for paranoid users, but default ON for headless production. Document trade-off in adapter comment + ADR-0026 update.
-
-**Applies in:** v3.7.2 patch — runner.cjs adapters
-
-## P-1304 — runner.cjs spawnSync with shell:true on Windows doesn't quote multi-word args; cmd.exe re-splits them
-
-**Evidence:** panloop second autonomous run (post-P-1302 fix): claude -p exited 1 in 538ms because the prompt /pan:new-project --auto @.planning/idea.md was passed as 4 args but Node joined them with spaces under shell:true without quoting, so cmd.exe re-split it into 6 args. Manual reproduction with the prompt quoted worked fine (10+ min real autonomous workflow ran).
-
-**Rule:** When passing args to spawnSync({shell:true}), Node joins them with spaces and the shell re-parses. Multi-word args (prompts, paths with spaces) MUST be quoted by the caller. Fix in runner.cjs: when useShell is true, wrap any arg containing whitespace in double-quotes and double any embedded double-quote (cmd.exe convention). Apply same fix in any other place pan-wizard-core uses spawnSync({shell:true}).
-
-**Applies in:** v3.7.2 patch — runner.cjs runExperiment, audit other shell:true call sites
-
-## P-1401 — Lightweight phases (scaffolding-only, single plan) over-ceremonialize: 5 commits + 5-7 min for trivial work
-
-**Evidence:** panloop run: Phase 1 (project setup — package.json + dirs + CLI stub, ~10 LOC of work) went through full context+research+plan+execute+summary+close. 5 commits, ~5-7 min wall clock.
-
-**Rule:** PAN should detect 'phase has 1 plan with simple feat/chore-class work' and skip per-phase research + plan-checker stages, deferring directly from context to execute. Save ~3 commits and ~5 min per trivial phase. Heuristic: if plan count == 1 AND plan tasks count <= 3 AND no architectural changes mentioned in idea, treat as lightweight.
-
-**Applies in:** v3.7.x patch — workflows/exec-phase.md, workflows/plan-phase.md
-
-## P-1402 — Per-phase researcher re-derives material already covered by project-level research
-
-**Evidence:** panloop: phase 1 research and phase 2 research both touched ESM scaffolding territory already covered by project-level research/architecture.md, features.md, stack.md. Wasted tokens.
-
-**Rule:** pan-phase-researcher agent prompt should require reading research/architecture.md, features.md, stack.md as context, AND emit only deltas/specifics not in project-level research. Audit agents/pan-phase-researcher.md.
-
-**Applies in:** v3.7.x patch — agents/pan-phase-researcher.md prompt
-
-## P-1404 — Auto-trace SubagentStop hook covers only some agents — pan-roadmapper logged but pan-planner/executor/verifier did not
-
-**Evidence:** panloop run had ~25 agent invocations across the lifecycle (researcher×2, roadmapper, context, planner×2, executor×3, verifier×2, etc.). Only 14 trace events captured across 4 sub-sessions. Hook coverage gap means /pan:learn analysis is working from incomplete data.
-
-**Rule:** Audit hooks/pan-trace-logger.js to verify SubagentStop fires for ALL Task-spawned agent types, not just a known list. Either: (a) regex-match agent names broadly, (b) document expected agents and warn if hook payloads come from unknown ones, (c) add a 'fallback' trace event when an agent commits but no trace was captured (would require git-hook integration).
-
-**Applies in:** v3.7.x patch — hooks/pan-trace-logger.js audit
-
-## P-1501 — claude -p autonomous session exits after Phase 0 setup; multi-step workflows don't drive headless mode forward without explicit tool calls
-
-**Evidence:** panloop2 v3.7.3 validation run via patched runner.cjs: status=done, exit_code=0, elapsed=48s, BUT only config.json was written. No project.md, no roadmap, no research, no subagent spawns. The auto-mode workflow block applies defaults then says 'proceed' — model interprets that as completion and exits. Original panloop 29-min success was via MANUAL interactive claude -p, not via runner-spawned.
-
-**Rule:** Workflow auto-mode blocks must END with an explicit tool call that drives the next step (e.g., Write call to create project.md, or Task call to spawn pan-discusser). 'Proceed' as text instruction is insufficient in headless mode — claude -p exits when the assistant's text response has no pending tool calls. Audit all --auto-flagged workflow paths for this gap. Possible v3.7.4 patch: auto-mode workflow steps explicitly chain via tool invocation, not prose continuation.
-
-**Applies in:** v3.7.4+ patch — workflows/new-project.md auto-mode chain audit
-
-## P-1502 — runner.cjs exit_code=0 is too coarse — should validate milestone-completion before declaring success
-
-**Evidence:** panloop2: runner returned status=done, stop_reason=success, exit_code=0 even though only config.json was written and the workflow halted at Phase 0. Exit code only reflects 'claude -p exited cleanly' — not 'autonomous build completed'.
-
-**Rule:** After spawnSync returns exit_code=0, runner.cjs runExperiment should also check whether <experiment>/.planning/state.md status field is 'completed' (or whether milestone summary exists). If the workflow never reached milestone-done, set stop_reason='incomplete' or 'partial' even with clean exit. Caller can then act differently (e.g., mark for re-run, alert).
-
-**Applies in:** v3.7.4 — runner.cjs runExperiment success criteria audit
-
-## P-1701 — Multi-phase (3+) autonomous workflows exit at phase boundaries with /clear-and-rerun instructions; loop is autonomous WITHIN a phase, not across phases
-
-**Evidence:** panmd2 manual claude -p run on a 5-phase project: completed Phase 1 with 13 commits + 20/20 tests passing, then exited cleanly with final assistant message: 'Next Up: Phase 2: Rule Infrastructure — /pan:discuss-phase 2 --auto. /clear first → fresh context window'. Compare panloop (2 phases) which auto-chained both phases without exit. The auto-mode workflow has phase-handoff logic that emits a /clear instruction between phases for context-budget reasons.
-
-**Rule:** Audit pan-wizard-core/workflows/new-project.md and exec-phase.md for phase-handoff logic. The 'between phases /clear' approach prevents true multi-phase autonomous runs. v3.7.4+ options: (a) detect 'this is the last phase' and skip /clear instruction, (b) provide a '--multi-phase' mode that chains all phases in one session (high token cost, large context), (c) have the runner DETECT 'next up' style exits and auto-spawn next phase via /pan:plan-phase --auto. (c) is most scalable.
-
-**Applies in:** v3.7.4+ — workflows/new-project.md phase-handoff, runner.cjs continuation logic
-
-## P-1501-r2 — P-1501 root cause refined: runner.cjs spawnSync({stdio:[ignore,pipe,pipe]}) lacks TTY; manual bash invocation has TTY; claude -p detects no-TTY and exits after first response loop
-
-**Evidence:** Isolation tests: (1) Manual bash invocation 'claude -p --dangerously-skip-permissions <prompt>' (NO --output-format json, exact same flags as runner) → 13 commits, Phase 1 complete, exit 0. (2) Runner-spawned 'claude -p --dangerously-skip-permissions <prompt>' via spawnSync({stdio:[ignore,pipe,pipe], shell:'win32'}) → 0 commits, only config.json written, exit 0 in ~45s. The ONLY difference is the spawn environment. claude -p likely detects isatty(stdin)=false and exits after first complete response, treating the absence of TTY as 'scripted single-shot' instead of 'autonomous loop'.
-
-**Rule:** Fix in runner.cjs: either (a) allocate a pseudo-tty using node-pty (requires runtime dep), (b) pipe a 'continue' prompt to keep claude alive across iterations, or (c) wrap claude -p in a script that allocates a TTY (e.g., via 'script -q' on Unix, ConPTY on Windows). Document the environment requirement in runner adapter comment.
-
-**Applies in:** v3.7.4 — runner.cjs spawn environment fix
-
-## P-1501-r3 — P-1501 stdio:'inherit' fix is INSUFFICIENT when the grandparent (script/CI/tool) has no TTY itself
-
-**Evidence:** panmd3 v3.7.4 validation run via patched runner with stdio:[inherit, pipe, pipe]: still 48s, 0 commits, status=incomplete (P-1502 caught the regression honestly). Root cause: 'inherit' inherits from parent (node), which inherits from Bash tool wrapper, which has no TTY. Chain: no-TTY-grandparent → no-TTY-parent → claude sees no-TTY → exits early.
-
-**Rule:** Real fix for P-1501 requires either: (a) explicit pty allocation via node-pty (would be PAN's first runtime dependency — meaningful trade-off), (b) wrap claude invocation in a TTY-allocating tool (Windows: winpty/ConPTY API, Unix: script -q). Document the current limitation: pan-tools experiment run autonomous claude path WORKS only when invoked from a real terminal (where the entire ancestry chain has a TTY). When invoked from Bash-tool/CI/script wrappers, the run will return status=incomplete (P-1502 reports honestly). For v3.7.4: ship with this limitation documented; v3.8 may bring node-pty integration.
-
-**Applies in:** v3.8 — runner.cjs pty allocation; v3.7.4 — documentation in commands/pan/experiment.md

package/pan-zcode/mcp/native-tools.cjs

@@ -1,63 +0,0 @@
-'use strict';
-
-/**
- * PAN-Z M2 — native MCP tools whose logic lives in-process (not a pan-tools spawn).
- *
- * These are the deterministic grafts the review demanded: the orchestrator's
- * `next-action` state machine and the two-step merge gate. A native tool declares a
- * `handler({ cwd, input, env, gitImpl }) -> { json | text, isError? }` instead of a
- * `verb`; a thrown Error is surfaced as JSON-RPC -32602 (invalid params) by the server.
- */
-
-const mergeGate = require('./merge-gate.cjs');
-const orchestrator = require('./orchestrator.cjs');
-
-const NATIVE_TOOLS = [
-  {
-    name: 'pan_next_action',
-    title: 'Next deterministic action',
-    description: 'Given the current phase/run snapshot, return the next step the primary agent should take (plan/execute/verify/request_merge/await_approval/stop). Enforces the safety caps and the regression circuit-breaker.',
-    readOnly: true, destructive: false,
-    inputSchema: {
-      type: 'object', additionalProperties: false, required: ['state'],
-      properties: { state: { type: 'object' }, caps: { type: 'object' } },
-    },
-    handler: ({ input }) => {
-      if (!input.state || typeof input.state !== 'object') throw new Error('Invalid "state": an object snapshot is required');
-      return { json: orchestrator.nextAction(input.state, input.caps) };
-    },
-  },
-  {
-    name: 'pan_request_merge',
-    title: 'Request a gated merge',
-    description: 'Stage a squash-merge request for a branch and mark it awaiting human approval. Records intent only — does NOT merge.',
-    readOnly: false, destructive: false,
-    inputSchema: {
-      type: 'object', additionalProperties: false, required: ['branch'],
-      properties: { branch: { type: 'string' }, ci_green: { type: 'boolean' }, verify_pass: { type: 'boolean' } },
-    },
-    handler: ({ cwd, input }) => ({
-      json: mergeGate.requestMerge(cwd, { branch: input.branch, ci_green: input.ci_green, verify_pass: input.verify_pass }),
-    }),
-  },
-  {
-    name: 'pan_confirm_merge',
-    title: 'Confirm a human-approved merge',
-    description: 'Perform a squash-merge ONLY if CI is green, verify passed, and a human-origin approval token (env PAN_MERGE_APPROVAL equal to the request\'s approval_token) is present. Any agent-supplied approval is ignored; never force-pushes or rewrites history.',
-    readOnly: false, destructive: true,
-    inputSchema: {
-      type: 'object', additionalProperties: false, required: ['branch'],
-      properties: { branch: { type: 'string' } },
-    },
-    handler: ({ cwd, input, env, gitImpl }) => {
-      const res = mergeGate.confirmMerge(cwd, { branch: input.branch }, env, gitImpl);
-      // A refused gate (missing approval / CI / verify) is a normal, non-error result the
-      // agent should read; only a real git failure is flagged isError.
-      const gitFailed = !res.merged && Array.isArray(res.reasons)
-        && res.reasons.some((r) => r === 'git_merge_failed' || r === 'git_commit_failed');
-      return { json: res, isError: gitFailed };
-    },
-  },
-];
-
-module.exports = { NATIVE_TOOLS };

package/pan-zcode/mcp/orchestrator.cjs

@@ -1,66 +0,0 @@
-'use strict';
-
-/**
- * PAN-Z M2 — the deterministic orchestrator ("next-action" state machine).
- *
- * ZCode has no workflow engine and cannot machine-intercept a subagent spawn, so
- * PAN's sequencing + safety harness (waves, regression circuit-breaker, spawn/budget
- * caps, the human merge gate) cannot live in agent prose or a pre-spawn hook. The
- * review's fix: relocate the state machine here and expose ONE `next-action` tool the
- * primary Agent polls before each step. Enforcement then happens at the (gateable)
- * MCP-tool-call boundary, not at the (un-gateable) spawn event.
- *
- * `nextAction` is a PURE function of a snapshot the caller assembles from PAN's own
- * state (via the pan-mcp resources) — so it is fully unit-testable and its decisions
- * are reproducible.
- */
-
-// Budget is advisory by default (enforceBudget:false) — it never stops the loop
-// unless the caller opts in. maxCycles remains a hard safety stop.
-const DEFAULT_CAPS = { maxCycles: 25, budget: Infinity, enforceBudget: false };
-const PHASE_NEXT = {
-  none: 'plan',
-  researched: 'plan',
-  planned: 'execute',
-  executed: 'verify',
-  verified: 'request_merge',
-};
-
-/**
- * Decide the next deterministic action.
- * @param {Object} state snapshot:
- *   { phases:[{number,status}], cycles?, points_used?, tests_before?, tests_after?,
- *     awaiting_approval?:boolean, aborted?:boolean }
- * @param {Object} [caps] { maxCycles, budget }
- * @returns {{action:string, args?:Object, reason:string, done:boolean}}
- *   action ∈ plan | execute | verify | request_merge | await_approval | stop
- */
-function nextAction(state, caps) {
-  const c = Object.assign({}, DEFAULT_CAPS, caps || {});
-  state = state || {};
-
-  // Hard stops first — safety caps and the circuit-breaker outrank all progress.
-  if (state.aborted) return { action: 'stop', reason: 'aborted', done: true };
-  if (
-    typeof state.tests_before === 'number' &&
-    typeof state.tests_after === 'number' &&
-    state.tests_after < state.tests_before
-  ) {
-    return { action: 'stop', reason: 'regression', done: true };
-  }
-  if ((state.cycles || 0) >= c.maxCycles) return { action: 'stop', reason: 'max_cycles', done: true };
-  if (c.enforceBudget && (state.points_used || 0) >= c.budget) return { action: 'stop', reason: 'budget_cap', done: true };
-
-  // The human merge gate is a barrier: while a merge awaits approval, do nothing else.
-  if (state.awaiting_approval) return { action: 'await_approval', reason: 'human_gate', done: false };
-
-  // Advance the first phase that isn't complete.
-  const phases = Array.isArray(state.phases) ? state.phases : [];
-  const phase = phases.find((p) => p && p.status !== 'complete');
-  if (!phase) return { action: 'stop', reason: 'all_complete', done: true };
-
-  const action = PHASE_NEXT[phase.status] || 'plan';
-  return { action, args: { phase: phase.number }, reason: `phase_${phase.status}`, done: false };
-}
-
-module.exports = { nextAction, DEFAULT_CAPS, PHASE_NEXT };