pan-wizard 3.25.0 → 3.27.0

package/scripts/deprecate-old-versions.js

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+/**
+ * Deprecate published versions that have fallen far enough behind.
+ *
+ * WHY. Old releases stay installable forever, and `npm install pan-wizard@3.20.0`
+ * silently gives someone a build from several cycles ago with none of the fixes
+ * since. Deprecation is the honest signal: the version keeps working, keeps
+ * resolving, and anyone installing it sees a warning telling them what to move to.
+ *
+ * WHY DEPRECATE AND NEVER UNPUBLISH. Unpublishing removes a tarball other people
+ * may depend on and is refused by npm outside a 72-hour window anyway. Deprecation
+ * is additive, reversible (`npm deprecate <pkg>@<ver> ""` clears it), and breaks
+ * nobody. **This script must never gain an unpublish path.**
+ *
+ * THE RULE. Keep the newest N stable releases (default 3 — the one just published
+ * plus the two behind it) and deprecate every stable release older than those.
+ * Prereleases are never counted as "kept": once a stable release exists that
+ * supersedes them they are deprecated too, since an rc is not something anyone
+ * should be installing after the real release shipped.
+ *
+ * SAFETY, in the order it matters:
+ *   - DRY RUN BY DEFAULT. `--apply` is required to change anything.
+ *   - The version being released is never deprecated, even if the arithmetic
+ *     somehow selects it — an explicit guard, not a consequence.
+ *   - Already-deprecated versions are skipped, so re-running is a no-op.
+ *   - A failure to deprecate NEVER fails the build. By the time this runs the
+ *     publish has already succeeded; turning a housekeeping failure into a red
+ *     release would be strictly worse than leaving an old version undeprecated.
+ *
+ * Usage:
+ *   node scripts/deprecate-old-versions.js                 # dry run, keep 3
+ *   node scripts/deprecate-old-versions.js --apply         # actually deprecate
+ *   node scripts/deprecate-old-versions.js --keep 5 --apply
+ */
+
+'use strict';
+
+const { execFileSync } = require('child_process');
+
+const PKG = 'pan-wizard';
+const DEFAULT_KEEP = 3;
+
+/**
+ * Parse a semver string into comparable parts. Returns null for anything that is
+ * not `major.minor.patch[-prerelease]`, so junk sorts out rather than throwing.
+ */
+function parse(v) {
+  const m = /^(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/.exec(String(v || '').trim());
+  if (!m) return null;
+  return {
+    version: v,
+    nums: [Number(m[1]), Number(m[2]), Number(m[3])],
+    pre: m[4] || null,
+  };
+}
+
+/**
+ * Compare two parsed versions, ascending. Prerelease-aware: 3.26.0-rc.1 sorts
+ * BELOW 3.26.0, which the update-check hook's comparator deliberately does not do
+ * (it ignores the suffix). Getting this backwards would deprecate a real release
+ * in favour of its own release candidate, so it is implemented here rather than
+ * reused.
+ */
+function compare(a, b) {
+  for (let i = 0; i < 3; i++) {
+    if (a.nums[i] !== b.nums[i]) return a.nums[i] - b.nums[i];
+  }
+  if (a.pre === b.pre) return 0;
+  if (a.pre === null) return 1;   // release > prerelease
+  if (b.pre === null) return -1;
+  return a.pre < b.pre ? -1 : 1;  // lexical is good enough for rc.1 < rc.2
+}
+
+/**
+ * Decide what to deprecate. PURE — no network, no process — so the rule is
+ * testable without touching a registry.
+ *
+ * @param {string[]} published   every version on the registry
+ * @param {string} current       the version just released (never deprecated)
+ * @param {number} keep          how many newest STABLE releases to leave alone
+ * @param {string[]} [already]   versions already carrying a deprecation message
+ * @returns {{deprecate:string[], keep:string[], reason:Object<string,string>}}
+ */
+function selectVersionsToDeprecate(published, current, keep = DEFAULT_KEEP, already = []) {
+  const parsed = (published || []).map(parse).filter(Boolean).sort(compare);
+  const skip = new Set(already || []);
+  const stable = parsed.filter((p) => !p.pre);
+  // The newest `keep` stable releases are protected.
+  const kept = new Set(stable.slice(-keep).map((p) => p.version));
+  // The current release is protected regardless of where the arithmetic lands it.
+  kept.add(current);
+
+  const reason = {};
+  const deprecate = [];
+  for (const p of parsed) {
+    if (kept.has(p.version)) continue;
+    if (skip.has(p.version)) continue;
+    reason[p.version] = p.pre
+      ? `prerelease superseded by ${current}`
+      : `more than ${keep - 1} releases behind ${current}`;
+    deprecate.push(p.version);
+  }
+  return { deprecate, keep: [...kept].sort(), reason };
+}
+
+/** Message a deprecated version carries. Points at what to install instead. */
+function buildMessage(current) {
+  return `No longer maintained — install pan-wizard@${current} or later (npm i pan-wizard@latest).`;
+}
+
+// ─── IO layer ───────────────────────────────────────────────────────────────
+
+/**
+ * Run npm.
+ *
+ * WINDOWS: `npm` is a `.cmd` shim, so `execFileSync('npm', …)` fails ENOENT and
+ * `'npm.cmd'` fails EINVAL — the shim can only be launched through a shell. This
+ * is the same scar `runner.cjs` carries as its `shell: 'win32'` opt-in, and the
+ * first version of this script reproduced the bug: a local dry run reported
+ * "could not read the registry" and returned, so the fail-open path made a real
+ * platform bug look like a benign skip.
+ *
+ * QUOTING: with `shell: true` node CONCATENATES arguments rather than escaping
+ * them, so anything containing a space must be quoted or it arrives as several
+ * arguments — which matters here because the deprecation message is a sentence.
+ * Every argument is program-controlled (package name, versions read from the
+ * registry, our own message), so this is a correctness problem rather than an
+ * injection one, but it still has to be right. `assertQuotable` refuses a value
+ * carrying a double quote instead of emitting a broken command line.
+ */
+function assertQuotable(a) {
+  if (String(a).includes('"')) {
+    throw new Error(`refusing to shell-quote an argument containing a double quote: ${a}`);
+  }
+  return a;
+}
+
+function runNpm(args, opts = {}) {
+  const win = process.platform === 'win32';
+  const argv = win ? args.map((a) => (/\s/.test(a) ? `"${assertQuotable(a)}"` : a)) : args;
+  return execFileSync('npm', argv, {
+    encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], shell: win, ...opts,
+  });
+}
+
+/**
+ * `npm view <pkg> <field> --json` prints NOTHING when the field is unset across
+ * every version — which is exactly the healthy starting state for `deprecated`
+ * (nothing deprecated yet). `JSON.parse('')` throws, and the fail-open handler
+ * then reported "could not read the registry", turning the normal case into an
+ * apparent failure. Empty means absent, not broken.
+ */
+function npmJson(args, fallback = null) {
+  const out = runNpm(args);
+  if (!out || !out.trim()) return fallback;
+  return JSON.parse(out);
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const apply = args.includes('--apply');
+  const keepIdx = args.indexOf('--keep');
+  const keep = keepIdx > -1 ? Number(args[keepIdx + 1]) : DEFAULT_KEEP;
+  const current = require('../package.json').version;
+
+  if (!Number.isInteger(keep) || keep < 1) {
+    console.error(`deprecate: --keep must be a positive integer, got ${keep}`);
+    process.exit(1);
+  }
+
+  // A prerelease must never trigger a deprecation sweep: it is not the thing
+  // users are being pointed at, and treating it as "the new release" would
+  // deprecate the current stable one.
+  if (parse(current) && parse(current).pre) {
+    console.log(`deprecate: ${current} is a prerelease — skipping (sweeps run for stable releases only).`);
+    return;
+  }
+
+  let published = [];
+  let deprecatedAlready = [];
+  try {
+    published = npmJson(['view', PKG, 'versions', '--json'], []);
+    if (!Array.isArray(published)) published = [published];
+    const map = npmJson(['view', PKG, 'deprecated', '--json'], {});
+    // npm returns a bare string for a single version, or {version: message}.
+    deprecatedAlready = (map && typeof map === 'object') ? Object.keys(map) : [];
+  } catch (e) {
+    console.error(`deprecate: could not read the registry (${String(e.message).split('\n')[0]}). Nothing changed.`);
+    return; // never fail the build over housekeeping
+  }
+
+  const { deprecate, keep: kept, reason } = selectVersionsToDeprecate(published, current, keep, deprecatedAlready);
+  const message = buildMessage(current);
+
+  console.log(`deprecate: current=${current} keep=${keep}`);
+  console.log(`  protected: ${kept.join(', ')}`);
+  if (deprecate.length === 0) {
+    console.log('  nothing to deprecate.');
+    return;
+  }
+  console.log(`  ${apply ? 'deprecating' : 'WOULD deprecate (dry run — pass --apply)'}: ${deprecate.length}`);
+  for (const v of deprecate) console.log(`    ${v}  — ${reason[v]}`);
+
+  if (!apply) return;
+
+  let failed = 0;
+  for (const v of deprecate) {
+    try {
+      runNpm(['deprecate', `${PKG}@${v}`, message]);
+      console.log(`  ✓ ${v}`);
+    } catch (e) {
+      failed++;
+      console.error(`  ✗ ${v}: ${String(e.stderr || e.message).split('\n')[0]}`);
+    }
+  }
+  if (failed) {
+    // Reported, not fatal. The publish already succeeded; a red build here would
+    // imply the release failed, which is false and worse than the omission.
+    console.error(`deprecate: ${failed} of ${deprecate.length} failed — release is unaffected.`);
+  }
+}
+
+if (require.main === module) main();
+
+module.exports = { selectVersionsToDeprecate, buildMessage, parse, compare, assertQuotable };

package/scripts/plugin-path.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+/**
+ * Print the absolute path of the built PAN plugin directory — the contract a
+ * Claude Code plugin-marketplace `command` source requires (v2.1.229+).
+ *
+ * WHY THIS EXISTS. PAN builds a plugin (`npm run build:plugin`) and has shipped
+ * it nowhere, because marketplace publishing is gated on one unverified
+ * question: does `${CLAUDE_PLUGIN_ROOT}` expand inside *command markdown*? It is
+ * documented as substituted in hook and MCP configs, not in content. A `command`
+ * source needs no hosting, so it turns that question into a local experiment —
+ * install the plugin from this script's output and run `/pan-plugin-selftest`.
+ *
+ * THE CONTRACT, verbatim from code.claude.com/docs/en/plugin-marketplaces:
+ *   - Claude Code runs the command "through the platform shell, `sh` on macOS and
+ *     Linux or `cmd.exe` on Windows, from the user's home directory". So NOTHING
+ *     here may depend on the working directory; every path is derived from
+ *     __dirname.
+ *   - "The command must print exactly one line on stdout and exit with code 0."
+ *     The plugin build is chatty, so its stdout is relayed to STDERR and only the
+ *     path reaches stdout. A stray console.log here breaks the install.
+ *   - The printed directory must hold plugin content at its top level, must not
+ *     be the directory Claude Code started in or one of its parents, and on
+ *     Windows must not be a UNC path.
+ *
+ * Rebuilding on every run is deliberate: Claude Code re-runs the command once per
+ * session in the background, so a source edit is picked up without reinstalling.
+ * In `copy` mode the version is a hash of the directory contents, so an unchanged
+ * build counts as up to date.
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const { execFileSync } = require('child_process');
+
+const ROOT = path.join(__dirname, '..');
+const PLUGIN_DIR = path.join(ROOT, 'dist', 'pan-wizard-plugin');
+
+// Top-level markers Claude Code accepts as proof of plugin content.
+const PLUGIN_MARKERS = ['.claude-plugin', 'skills', 'commands', 'agents', 'hooks'];
+
+function fail(message) {
+  // stderr only — stdout is reserved for the single path line.
+  process.stderr.write(`plugin-path: ${message}\n`);
+  process.exit(1);
+}
+
+function build() {
+  try {
+    // Relay the builder's stdout to stderr so stdout stays single-line.
+    const out = execFileSync(process.execPath, [path.join(ROOT, 'scripts', 'build-plugin.js')], {
+      cwd: ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    if (out) process.stderr.write(out);
+  } catch (err) {
+    const detail = (err.stderr || err.stdout || err.message || '').toString().trim();
+    fail(`plugin build failed: ${detail.split('\n').slice(-3).join(' | ')}`);
+  }
+}
+
+function main() {
+  build();
+
+  if (!fs.existsSync(PLUGIN_DIR)) fail(`build produced no directory at ${PLUGIN_DIR}`);
+
+  const top = fs.readdirSync(PLUGIN_DIR);
+  if (!PLUGIN_MARKERS.some((m) => top.includes(m))) {
+    fail(`no plugin content at the top level of ${PLUGIN_DIR} (need one of ${PLUGIN_MARKERS.join(', ')})`);
+  }
+
+  const resolved = path.resolve(PLUGIN_DIR);
+
+  // Windows UNC paths are refused by Claude Code; catch it here with a clear
+  // message rather than letting the install fail opaquely.
+  if (process.platform === 'win32' && /^\\\\/.test(resolved)) {
+    fail(`refusing a UNC path (Claude Code rejects it): ${resolved}`);
+  }
+
+  // Exactly one line, nothing else.
+  process.stdout.write(`${resolved}\n`);
+}
+
+main();

package/pan-wizard-core/learnings/internal/.gitkeep

@@ -1,2 +0,0 @@
-# Placeholder so git tracks the empty directory.
-# This tier is NOT shipped to user installs — see ../README.md.

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