pan-wizard 3.19.0 → 3.20.0

package/bin/install-lib.cjs

@@ -1324,105 +1324,21 @@ return { areas_mapped: maps.filter(Boolean).length, synthesis }
 
 // ─── AGENTS.md universal rules layer (ADR-0028 Phase 3) ─────────────────────
 //
-// AGENTS.md is the cross-runtime project-instructions standard; every PAN
-// target runtime (and Antigravity CLI) reads it natively. PAN contributes one
-// marker-fenced section so agents in any runtime understand the PAN context
-// when reading the repo. User content outside the markers is never touched.
+// The builders + markers live under pan-wizard-core/ (the single source of
+// truth, shipped into every install) so the installer and the installed
+// `pan-tools memory rebuild` regenerate byte-identical content. They are
+// re-exported here so all existing installer callers and tests keep importing
+// them from install-lib unchanged.
 
-const PAN_AGENTS_BEGIN = '<!-- BEGIN PAN WIZARD -->';
-const PAN_AGENTS_END = '<!-- END PAN WIZARD -->';
-
-/**
- * Build the PAN section for AGENTS.md (marker-fenced, runtime-neutral).
- * @returns {string} The fenced section, no leading/trailing blank lines.
- */
-function buildAgentsMdSection() {
-  return [
-    PAN_AGENTS_BEGIN,
-    '## PAN Wizard',
-    '',
-    'This project uses PAN Wizard for structured, phase-based planning and execution.',
-    '',
-    '- `.planning/` is PAN\'s state directory (state.md, roadmap.md, phase directories). Treat it as the source of truth for planning state and modify it through PAN commands, not by hand.',
-    '- PAN commands install as `pan-*` skills/commands (for example `/pan-help`, `/pan-new-project`, `/pan-exec-phase`). Start with `/pan-help`.',
-    '- The `pan-tools` dispatcher backs every command; it lives under `pan-wizard-core/` inside the runtime\'s config directory (or `.agents/` for unified installs).',
-    PAN_AGENTS_END,
-  ].join('\n');
-}
-
-/**
- * Insert or replace the PAN section in AGENTS.md content.
- * - No existing content (null/empty) → just the section.
- * - Markers present → replace exactly the fenced block, preserving everything
- *   around it.
- * - Markers absent → append with a separating blank line.
- * @param {string|null} existing - Current AGENTS.md content, or null if absent
- * @param {string} section - Output of buildAgentsMdSection()
- * @returns {string} New file content (always newline-terminated)
- */
-function upsertAgentsMdSection(existing, section) {
-  if (!existing || !existing.trim()) {
-    return section + '\n';
-  }
-  const beginIdx = existing.indexOf(PAN_AGENTS_BEGIN);
-  const endIdx = existing.indexOf(PAN_AGENTS_END);
-  if (beginIdx !== -1 && endIdx !== -1 && endIdx > beginIdx) {
-    const before = existing.slice(0, beginIdx);
-    const after = existing.slice(endIdx + PAN_AGENTS_END.length);
-    return before + section + after;
-  }
-  return existing.trimEnd() + '\n\n' + section + '\n';
-}
-
-/**
- * Remove the PAN section from AGENTS.md content.
- * @param {string} existing - Current AGENTS.md content
- * @returns {string|null} Content without the PAN block, or null when nothing
- *   meaningful remains (caller should delete the file).
- */
-function removeAgentsMdSection(existing) {
-  if (!existing) return null;
-  const beginIdx = existing.indexOf(PAN_AGENTS_BEGIN);
-  const endIdx = existing.indexOf(PAN_AGENTS_END);
-  if (beginIdx === -1 || endIdx === -1 || endIdx < beginIdx) {
-    return existing; // no PAN block — leave untouched
-  }
-  const before = existing.slice(0, beginIdx);
-  const after = existing.slice(endIdx + PAN_AGENTS_END.length);
-  const remaining = (before.trimEnd() + '\n\n' + after.trimStart()).trim();
-  return remaining ? remaining + '\n' : null;
-}
-
-/**
- * Ensure CLAUDE.md bridges to AGENTS.md via a marker-fenced @AGENTS.md import
- * (Claude Code's documented pattern for adopting the universal rules file).
- * Idempotent; preserves all user content.
- * @param {string|null} existing - Current CLAUDE.md content, or null if absent
- * @returns {string} New file content
- */
-function ensureClaudeMdImport(existing) {
-  const block = `${PAN_AGENTS_BEGIN}\n@AGENTS.md\n${PAN_AGENTS_END}`;
-  if (!existing || !existing.trim()) {
-    return block + '\n';
-  }
-  if (existing.includes(PAN_AGENTS_BEGIN)) {
-    return existing; // bridge (or another PAN block) already present
-  }
-  if (/^@AGENTS\.md\s*$/m.test(existing)) {
-    return existing; // user already imports AGENTS.md themselves
-  }
-  return existing.trimEnd() + '\n\n' + block + '\n';
-}
-
-/**
- * Remove the PAN bridge block from CLAUDE.md content.
- * @param {string} existing - Current CLAUDE.md content
- * @returns {string|null} Content without the bridge, or null when nothing
- *   meaningful remains (caller should delete the file).
- */
-function removeClaudeMdImport(existing) {
-  return removeAgentsMdSection(existing);
-}
+const {
+  PAN_AGENTS_BEGIN,
+  PAN_AGENTS_END,
+  buildAgentsMdSection,
+  upsertAgentsMdSection,
+  removeAgentsMdSection,
+  ensureClaudeMdImport,
+  removeClaudeMdImport,
+} = require('../pan-wizard-core/bin/lib/agents-md.cjs');
 
 // ─── Exports ────────────────────────────────────────────────────────────────
 

package/hooks/dist/pan-cost-logger.js

@@ -56,41 +56,41 @@ function buildCostRecord(data, cwd) {
   // Only log actual subagent stops; ignore other Stop variants.
   if (data.hook_event_name && data.hook_event_name !== 'SubagentStop') return null;
 
-  // P-1805 (v3.7.8): if data.usage is missing/empty (Claude Code headless mode
-  // doesn't include it in the SubagentStop payload), fall back to reading the
-  // transcript_path JSONL and summing usage across the subagent's messages.
-  // Same approach as pan-trace-logger.js for consistency.
-  //
-  // 2026-06: the SubagentStop payload carries no model id either, which left
-  // every hook record with model:null and /pan:cost unable to price it. The
-  // transcript's assistant messages carry message.model right next to the
-  // usage we already read — capture it whenever data.model is absent.
-  let inputTokens = extractNumber(data.usage, 'input_tokens');
-  let outputTokens = extractNumber(data.usage, 'output_tokens');
-  let cacheRead = extractNumber(data.usage, 'cache_read_input_tokens');
-  let cacheWrite = extractNumber(data.usage, 'cache_creation_input_tokens');
+  // Per-call token counts come from the transcript SLICE — the records since
+  // this transcript's previous SubagentStop cursor. The SubagentStop `data.usage`,
+  // when Claude Code supplies it, is a CUMULATIVE session counter, NOT this
+  // subagent's delta, so logging it verbatim stamped impossible per-row magnitudes
+  // (tens of millions of output tokens, billions of cache-read) onto every record
+  // and made /pan:cost and the optimizer unusable (field reports 2026-06 / 2026-07).
+  // The transcript slice is the authoritative per-invocation delta; `data.usage`
+  // is a guarded fallback used only when no transcript is available.
   let model = typeof data.model === 'string' && data.model ? data.model : null;
-  const needUsage = (inputTokens + outputTokens + cacheRead + cacheWrite) === 0;
-  if ((needUsage || !model) && data.transcript_path) {
-    // Attribute only the transcript slice since the previous SubagentStop for
-    // this transcript, so a shared-session transcript is never re-summed on
-    // every event (field report 2026-06 — the billion-token cache-read bug).
+  let inputTokens = 0;
+  let outputTokens = 0;
+  let cacheRead = 0;
+  let cacheWrite = 0;
+  if (data.transcript_path) {
     const cursor = readCursor(cwd);
     const since = cursor[data.transcript_path] || 0;
     const fromTranscript = readUsageFromTranscript(data.transcript_path, data.session_id, since);
-    if (needUsage) {
-      inputTokens = fromTranscript.input_tokens;
-      outputTokens = fromTranscript.output_tokens;
-      cacheRead = fromTranscript.cache_read_input_tokens;
-      cacheWrite = fromTranscript.cache_creation_input_tokens;
-    }
+    inputTokens = fromTranscript.input_tokens;
+    outputTokens = fromTranscript.output_tokens;
+    cacheRead = fromTranscript.cache_read_input_tokens;
+    cacheWrite = fromTranscript.cache_creation_input_tokens;
     if (!model) model = fromTranscript.model;
-    // Advance the cursor to the end of the transcript so the next subagent's
-    // record starts fresh (these slices partition the transcript — no overlap).
+    // Advance the cursor so the next subagent's record starts fresh — the slices
+    // partition the transcript, so it is never re-summed on every event.
     if (fromTranscript.lineCount > since) {
       cursor[data.transcript_path] = fromTranscript.lineCount;
       writeCursor(cwd, cursor);
     }
+  } else {
+    // No transcript to slice — best-effort from data.usage, plausibility-guarded
+    // so a cumulative counter can never slip through as a per-call value.
+    inputTokens = clampPlausible(extractNumber(data.usage, 'input_tokens'));
+    outputTokens = clampPlausible(extractNumber(data.usage, 'output_tokens'));
+    cacheRead = clampPlausible(extractNumber(data.usage, 'cache_read_input_tokens'));
+    cacheWrite = clampPlausible(extractNumber(data.usage, 'cache_creation_input_tokens'));
   }
 
   const record = {
@@ -118,6 +118,15 @@ function extractNumber(obj, key) {
   return typeof v === 'number' ? v : 0;
 }
 
+// A single subagent call's token counts never realistically exceed this; a value
+// above it is a cumulative session counter that leaked in, so we drop it to 0
+// rather than poison the ledger. Generous vs. any real call, tiny vs. the
+// billions/tens-of-millions the cumulative bug produced.
+const PLAUSIBLE_MAX = 20000000;
+function clampPlausible(n) {
+  return typeof n === 'number' && n >= 0 && n <= PLAUSIBLE_MAX ? n : 0;
+}
+
 /**
  * P-1805 (v3.7.8): read transcript JSONL and sum usage across assistant messages.
  *
@@ -184,13 +193,34 @@ function appendRecord(cwd, record) {
   try {
     const dir = path.join(cwd, '.planning', METRICS_DIR);
     fs.mkdirSync(dir, { recursive: true });
-    fs.appendFileSync(path.join(dir, TOKENS_FILE), JSON.stringify(record) + '\n', 'utf-8');
+    const file = path.join(dir, TOKENS_FILE);
+    // Idempotency guard: a re-fired SubagentStop must not double-log. Skip the
+    // append when this record is identical (every field but the timestamp) to
+    // the immediately-preceding row — the source of ~57% duplicate rows in the
+    // field (2026-07). Best-effort: any read error just proceeds with the append.
+    if (isDuplicateOfLastRecord(file, record)) return false;
+    fs.appendFileSync(file, JSON.stringify(record) + '\n', 'utf-8');
     return true;
   } catch {
     return false;
   }
 }
 
+/** True when `record` equals the last JSONL row of `file`, ignoring `ts`. */
+function isDuplicateOfLastRecord(file, record) {
+  let prev;
+  try {
+    const raw = fs.readFileSync(file, 'utf-8');
+    const lines = raw.split('\n').filter(Boolean);
+    if (!lines.length) return false;
+    prev = JSON.parse(lines[lines.length - 1]);
+  } catch {
+    return false; // no file / unreadable / bad JSON → not a duplicate
+  }
+  const strip = (r) => { const { ts, ...rest } = r; return JSON.stringify(rest); };
+  return strip(prev) === strip(record);
+}
+
 // ─── Stdin driver ───────────────────────────────────────────────────────────
 
 if (require.main === module) {

package/hooks/dist/pan-trace-logger.js

@@ -98,6 +98,14 @@ function extractNumber(obj, key) {
   return typeof v === 'number' ? v : 0;
 }
 
+// Drop implausibly large per-call token counts (a cumulative counter that leaked
+// through the no-transcript fallback) to 0 rather than record them. Mirrors
+// pan-cost-logger's guard.
+const PLAUSIBLE_MAX = 20000000;
+function clampPlausible(n) {
+  return typeof n === 'number' && n >= 0 && n <= PLAUSIBLE_MAX ? n : 0;
+}
+
 /**
  * P-1805 (v3.7.8): extract usage totals by reading the SubagentStop transcript.
  * The hook payload from Claude Code in headless mode does NOT include
@@ -183,13 +191,15 @@ function buildTraceEvents(data, sessionId, cwd) {
   const ts = new Date().toISOString();
   const agent = data.agent_type || data.subagent_type || 'unknown';
 
-  // P-1805: prefer usage from data.usage when present (interactive Claude Code path).
-  // Fall back to reading the transcript file (headless `claude -p` path — usage
-  // not in payload but discoverable via transcript_path).
-  let inputTokens = extractNumber(data.usage, 'input_tokens');
-  let outputTokens = extractNumber(data.usage, 'output_tokens');
-  let cacheRead = extractNumber(data.usage, 'cache_read_input_tokens');
-  if ((inputTokens + outputTokens + cacheRead) === 0 && data.transcript_path) {
+  // Per-call tokens come from the transcript SLICE. The SubagentStop `data.usage`,
+  // when present, is a CUMULATIVE session counter — not this subagent's delta — so
+  // logging it verbatim produced impossible per-row magnitudes (see pan-cost-logger
+  // for the full rationale). The slice is authoritative; data.usage is only a
+  // plausibility-guarded fallback when no transcript is available.
+  let inputTokens = 0;
+  let outputTokens = 0;
+  let cacheRead = 0;
+  if (data.transcript_path) {
     const cursor = readTraceCursor(cwd);
     const since = cursor[data.transcript_path] || 0;
     const fromTranscript = readUsageFromTranscript(data.transcript_path, data.session_id, since);
@@ -200,6 +210,10 @@ function buildTraceEvents(data, sessionId, cwd) {
       cursor[data.transcript_path] = fromTranscript.lineCount;
       writeTraceCursor(cwd, cursor);
     }
+  } else {
+    inputTokens = clampPlausible(extractNumber(data.usage, 'input_tokens'));
+    outputTokens = clampPlausible(extractNumber(data.usage, 'output_tokens'));
+    cacheRead = clampPlausible(extractNumber(data.usage, 'cache_read_input_tokens'));
   }
   const totalTokens = inputTokens + outputTokens;
 
@@ -261,14 +275,39 @@ function appendTraceEvents(cwd, events, sessionId) {
   try {
     const sessionDir = path.join(getTracesDir(cwd), sessionId);
     fs.mkdirSync(sessionDir, { recursive: true });
+    const file = path.join(sessionDir, TRACE_EVENT_FILE);
+    // Idempotency guard: a re-fired SubagentStop must not double-log. If this
+    // batch's completion event duplicates the last agent_completion already in
+    // the file (every field but ts), skip the whole batch — the source of the
+    // ~57% duplicate completion rows in the field (2026-07).
+    const completion = events.find(e => e && e.category === 'agent_completion');
+    if (completion && isDuplicateCompletion(file, completion)) return false;
     const lines = events.map(e => JSON.stringify(e)).join('\n') + '\n';
-    fs.appendFileSync(path.join(sessionDir, TRACE_EVENT_FILE), lines, 'utf-8');
+    fs.appendFileSync(file, lines, 'utf-8');
     return true;
   } catch {
     return false;
   }
 }
 
+/** True when `completion` matches the file's last agent_completion row, ignoring ts. */
+function isDuplicateCompletion(file, completion) {
+  let last;
+  try {
+    const raw = fs.readFileSync(file, 'utf-8');
+    for (const line of raw.split('\n')) {
+      if (!line) continue;
+      let e; try { e = JSON.parse(line); } catch { continue; }
+      if (e && e.category === 'agent_completion') last = e;
+    }
+  } catch {
+    return false;
+  }
+  if (!last) return false;
+  const strip = (e) => { const { ts, ...rest } = e; return JSON.stringify(rest); };
+  return strip(last) === strip(completion);
+}
+
 // ─── Stdin driver ────────────────────────────────────────────────────────────
 
 if (require.main === module) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pan-wizard",
-  "version": "3.19.0",
+  "version": "3.20.0",
   "description": "Command a bot army for your codebase: an Opus Mission Control delegates whole-project goals to specialist squads and ships behind a human merge gate. Five AI CLIs, zero context rot.",
   "bin": {
     "pan-wizard": "bin/install.js"

package/pan-wizard-core/bin/lib/agents-md.cjs

@@ -0,0 +1,119 @@
+'use strict';
+
+// ─── AGENTS.md universal rules layer (ADR-0028 Phase 3) ─────────────────────
+//
+// AGENTS.md is the cross-runtime project-instructions standard; every PAN
+// target runtime (and Antigravity CLI) reads it natively. PAN contributes one
+// marker-fenced section so agents in any runtime understand the PAN context
+// when reading the repo. User content outside the markers is never touched.
+//
+// SSOT NOTE: these builders are the single source of truth for the AGENTS.md
+// PAN section and the CLAUDE.md @AGENTS.md bridge. They live under
+// pan-wizard-core/ (shipped into every install) so the installer AND the
+// installed `pan-tools memory rebuild` regenerate byte-identical content.
+// bin/install-lib.cjs re-exports these names for backward compatibility.
+
+const PAN_AGENTS_BEGIN = '<!-- BEGIN PAN WIZARD -->';
+const PAN_AGENTS_END = '<!-- END PAN WIZARD -->';
+
+/**
+ * Build the PAN section for AGENTS.md (marker-fenced, runtime-neutral).
+ * @returns {string} The fenced section, no leading/trailing blank lines.
+ */
+function buildAgentsMdSection() {
+  return [
+    PAN_AGENTS_BEGIN,
+    '## PAN Wizard',
+    '',
+    'This project uses PAN Wizard for structured, phase-based planning and execution.',
+    '',
+    '- `.planning/` is PAN\'s state directory (state.md, roadmap.md, phase directories). Treat it as the source of truth for planning state and modify it through PAN commands, not by hand.',
+    '- PAN commands install as `pan-*` skills/commands (for example `/pan-help`, `/pan-new-project`, `/pan-exec-phase`). Start with `/pan-help`.',
+    '- The `pan-tools` dispatcher backs every command; it lives under `pan-wizard-core/` inside the runtime\'s config directory (or `.agents/` for unified installs).',
+    PAN_AGENTS_END,
+  ].join('\n');
+}
+
+/**
+ * Insert or replace the PAN section in AGENTS.md content.
+ * - No existing content (null/empty) → just the section.
+ * - Markers present → replace exactly the fenced block, preserving everything
+ *   around it.
+ * - Markers absent → append with a separating blank line.
+ * @param {string|null} existing - Current AGENTS.md content, or null if absent
+ * @param {string} section - Output of buildAgentsMdSection()
+ * @returns {string} New file content (always newline-terminated)
+ */
+function upsertAgentsMdSection(existing, section) {
+  if (!existing || !existing.trim()) {
+    return section + '\n';
+  }
+  const beginIdx = existing.indexOf(PAN_AGENTS_BEGIN);
+  const endIdx = existing.indexOf(PAN_AGENTS_END);
+  if (beginIdx !== -1 && endIdx !== -1 && endIdx > beginIdx) {
+    const before = existing.slice(0, beginIdx);
+    const after = existing.slice(endIdx + PAN_AGENTS_END.length);
+    return before + section + after;
+  }
+  return existing.trimEnd() + '\n\n' + section + '\n';
+}
+
+/**
+ * Remove the PAN section from AGENTS.md content.
+ * @param {string} existing - Current AGENTS.md content
+ * @returns {string|null} Content without the PAN block, or null when nothing
+ *   meaningful remains (caller should delete the file).
+ */
+function removeAgentsMdSection(existing) {
+  if (!existing) return null;
+  const beginIdx = existing.indexOf(PAN_AGENTS_BEGIN);
+  const endIdx = existing.indexOf(PAN_AGENTS_END);
+  if (beginIdx === -1 || endIdx === -1 || endIdx < beginIdx) {
+    return existing; // no PAN block — leave untouched
+  }
+  const before = existing.slice(0, beginIdx);
+  const after = existing.slice(endIdx + PAN_AGENTS_END.length);
+  const remaining = (before.trimEnd() + '\n\n' + after.trimStart()).trim();
+  return remaining ? remaining + '\n' : null;
+}
+
+/**
+ * Ensure CLAUDE.md bridges to AGENTS.md via a marker-fenced @AGENTS.md import
+ * (Claude Code's documented pattern for adopting the universal rules file).
+ * Idempotent; preserves all user content.
+ * @param {string|null} existing - Current CLAUDE.md content, or null if absent
+ * @returns {string} New file content
+ */
+function ensureClaudeMdImport(existing) {
+  const block = `${PAN_AGENTS_BEGIN}\n@AGENTS.md\n${PAN_AGENTS_END}`;
+  if (!existing || !existing.trim()) {
+    return block + '\n';
+  }
+  if (existing.includes(PAN_AGENTS_BEGIN)) {
+    return existing; // bridge (or another PAN block) already present
+  }
+  if (/^@AGENTS\.md\s*$/m.test(existing)) {
+    return existing; // user already imports AGENTS.md themselves
+  }
+  return existing.trimEnd() + '\n\n' + block + '\n';
+}
+
+/**
+ * Remove the PAN bridge block from CLAUDE.md content.
+ * @param {string} existing - Current CLAUDE.md content
+ * @returns {string|null} Content without the bridge, or null when nothing
+ *   meaningful remains (caller should delete the file).
+ */
+function removeClaudeMdImport(existing) {
+  return removeAgentsMdSection(existing);
+}
+
+module.exports = {
+  PAN_AGENTS_BEGIN,
+  PAN_AGENTS_END,
+  buildAgentsMdSection,
+  upsertAgentsMdSection,
+  removeAgentsMdSection,
+  ensureClaudeMdImport,
+  removeClaudeMdImport,
+};

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

@@ -848,6 +848,9 @@ function focusAutoCheckpointCommit(cwd, cycle, run) {
   // is a planning-doc committer, so honor it. commit_docs=false → hands the .planning
   // commit (and any report regeneration) back to the user.
   if (config.commit_docs === false) return null;
+  // Reconcile the always-loaded project memory before staging so the committed
+  // .planning/ snapshot carries the trimmed state.md (no-op when already lean).
+  try { require('./memory-optimize.cjs').maybeAutoOptimizeMemory(cwd); } catch { /* never block the checkpoint */ }
   // Enabled projects: refresh the HTML reports before staging so the committed
   // .planning/ snapshot reflects this cycle.
   maybeRenderPhaseReports(cwd);

package/pan-wizard-core/bin/lib/memory-optimize.cjs

@@ -0,0 +1,253 @@
+'use strict';
+
+/**
+ * PAN memory optimize (A1) — trim the append-heavy tiers so the always-loaded
+ * project memory stays small, per the memory-management research:
+ *   - reconcile on write (dedupe / invalidate / consolidate), NEVER blind-append
+ *   - retain by importance, not FIFO (never drop the tail blindly)
+ *   - reversible: overflow is ARCHIVED (dated), never hard-deleted; git keeps the trace
+ *   - idempotent: re-running an already-lean file is a no-op (zero git churn)
+ *
+ * SAFETY: this only touches TOP-LEVEL BULLET LISTS inside recognized append-heavy
+ * sections (Decisions / Blockers / Concerns / Todos / Session Continuity). Tables,
+ * prose, sub-bullets, frontmatter, and every other section are preserved byte-for-byte.
+ * The command is dry-run by default (`--apply` to write). `optimizeStateContent` is a
+ * pure function of the content, so the whole reconcile is unit-testable in isolation.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { output, safeReadFile } = require('./core.cjs');
+const { planningPath } = require('./utils.cjs');
+const { writeStateMd } = require('./state.cjs');
+const { readMemory, parseEntries, listMemoryAgents, compactMemory, DEFAULT_MAX_ENTRIES, MEMORY_DIR } = require('./memory.cjs');
+
+const DEFAULT_KEEP = 12;            // recent bullets kept inline per section
+const STATE_ARCHIVE_FILE = 'state-archive.md';
+
+// Sections whose bullet lists grow unbounded and are safe to reconcile.
+const APPEND_HEAVY = /\b(decisions|blockers|concerns|pending todos|todos|session continuity|accumulated context|recent activity)\b/i;
+// A bullet that is just a placeholder — dropped once real entries exist.
+const PLACEHOLDER = /^-\s*(none(\s+yet)?|n\/a|tbd|todo|—|-)\.?\s*$/i;
+
+const isHeading = (l) => /^#{1,6}\s+\S/.test(l);
+const headingText = (l) => (l.match(/^#{1,6}\s+(.*)$/) || [, ''])[1];
+const isBullet = (l) => /^-\s+\S/.test(l);
+const isIndented = (l) => /^\s+\S/.test(l);
+
+/** Split content into ordered blocks: an optional heading + the lines under it. */
+function parseSections(content) {
+  const sections = [];
+  let cur = { heading: null, lines: [] };
+  for (const line of content.split('\n')) {
+    if (isHeading(line)) {
+      sections.push(cur);
+      cur = { heading: line, lines: [] };
+    } else {
+      cur.lines.push(line);
+    }
+  }
+  sections.push(cur);
+  return sections;
+}
+
+/** Reassemble sections into content byte-for-byte when nothing changed. */
+function joinSections(sections) {
+  return sections
+    .flatMap((s) => (s.heading !== null ? [s.heading, ...s.lines] : s.lines))
+    .join('\n');
+}
+
+/**
+ * Reconcile the bullet list inside one section body: dedupe, strip placeholders,
+ * and cap to the last `keepN` entries. An "entry" is a top-level `- ` bullet plus
+ * its indented continuation lines, so a bullet is never orphaned from its detail.
+ * Overflow entries are pushed to `archived`. Returns { lines, changed }.
+ */
+function reconcileBullets(lines, keepN, archived) {
+  const firstB = lines.findIndex(isBullet);
+  if (firstB === -1) return { lines, changed: false };
+
+  const pre = lines.slice(0, firstB);
+  const rest = lines.slice(firstB);
+  const entries = [];
+  let i = 0;
+  for (; i < rest.length; ) {
+    const l = rest[i];
+    if (isBullet(l)) {
+      const eLines = [l];
+      i++;
+      while (i < rest.length && isIndented(rest[i])) { eLines.push(rest[i]); i++; }
+      entries.push({ key: eLines.join('\n').trim(), lines: eLines });
+    } else if (l.trim() === '') {
+      i++; // blank between bullets — normalized away
+    } else {
+      break; // trailer prose begins — stop grouping
+    }
+  }
+  const trailer = rest.slice(i);
+
+  // 1. dedupe (keep first occurrence)
+  const seen = new Set();
+  const deduped = entries.filter((e) => (seen.has(e.key) ? false : (seen.add(e.key), true)));
+  // 2. strip placeholders once real entries exist
+  const real = deduped.filter((e) => !PLACEHOLDER.test(e.key));
+  const kept0 = real.length ? real : deduped;
+  // 3. cap to the most-recent keepN (bullets are appended, so the tail is newest)
+  let kept = kept0;
+  const dropped = [];
+  if (kept0.length > keepN) {
+    dropped.push(...kept0.slice(0, kept0.length - keepN));
+    kept = kept0.slice(-keepN);
+  }
+  for (const d of dropped) archived.push(d.lines.join('\n'));
+
+  const changed = deduped.length !== entries.length || kept0.length !== deduped.length || dropped.length > 0;
+  const newLines = [...pre, ...kept.flatMap((e) => e.lines), ...trailer];
+  // Preserve the section's trailing blank line (the blank that separates it from
+  // the next heading) so reconciling never collapses two sections together.
+  const endsBlank = lines.length > 0 && lines[lines.length - 1].trim() === '';
+  if (endsBlank && (newLines.length === 0 || newLines[newLines.length - 1].trim() !== '')) newLines.push('');
+  return { lines: newLines, changed };
+}
+
+/**
+ * Pure reconcile of state.md content.
+ * @returns {{content:string, changed:boolean, archived:string[], sectionsTouched:string[]}}
+ */
+function optimizeStateContent(content, opts = {}) {
+  const keepN = Number.isFinite(opts.keep) && opts.keep > 0 ? opts.keep : DEFAULT_KEEP;
+  const sections = parseSections(content);
+  const archived = [];
+  const sectionsTouched = [];
+  let changed = false;
+
+  for (const s of sections) {
+    if (s.heading === null) continue;
+    if (!APPEND_HEAVY.test(headingText(s.heading))) continue;
+    const before = archived.length;
+    const r = reconcileBullets(s.lines, keepN, archived);
+    if (r.changed) {
+      s.lines = r.lines;
+      changed = true;
+      sectionsTouched.push(headingText(s.heading).trim());
+    }
+    void before;
+  }
+
+  return { content: changed ? joinSections(sections) : content, changed, archived, sectionsTouched };
+}
+
+// ─── Command ────────────────────────────────────────────────────────────────
+
+function archivePath(cwd) {
+  return path.join(planningPath(cwd), MEMORY_DIR, STATE_ARCHIVE_FILE);
+}
+
+/** Append trimmed entries to the dated, append-only state archive (reversible). */
+function appendArchive(cwd, entries, now) {
+  if (!entries.length) return;
+  const p = archivePath(cwd);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  const stamp = now || '(undated)';
+  const block = `\n## Archived ${stamp}\n\n${entries.map((e) => e).join('\n')}\n`;
+  fs.appendFileSync(p, block, 'utf-8');
+}
+
+/**
+ * `memory optimize [--apply] [--keep N]` — reconcile state.md + consolidate
+ * over-budget agent logs. Dry-run by default: reports what WOULD change.
+ */
+function cmdMemoryOptimize(cwd, opts = {}, raw) {
+  const apply = !!opts.apply;
+  const keep = opts.keep;
+  const statePath = path.join(planningPath(cwd), 'state.md');
+  const before = safeReadFile(statePath);
+
+  const result = { apply, state: { changed: false }, agents: [], archived: 0 };
+
+  if (before != null) {
+    const opt = optimizeStateContent(before, { keep });
+    result.state = {
+      changed: opt.changed,
+      sections_touched: opt.sectionsTouched,
+      archived_entries: opt.archived.length,
+      before_bytes: Buffer.byteLength(before),
+      after_bytes: Buffer.byteLength(opt.content),
+    };
+    result.archived = opt.archived.length;
+    if (apply && opt.changed) {
+      appendArchive(cwd, opt.archived, opts.now);
+      writeStateMd(statePath, opt.content, cwd);
+    }
+  } else {
+    result.state = { changed: false, reason: 'no_state_md' };
+  }
+
+  // Consolidate any per-agent log over the entry cap (reuses compactMemory, which
+  // no-ops under the cap). Dry-run counts entries without writing.
+  try {
+    for (const a of listMemoryAgents(cwd)) {
+      const rawMem = readMemory(cwd, a);
+      if (rawMem == null) continue;
+      const count = parseEntries(rawMem).length;
+      if (count > DEFAULT_MAX_ENTRIES) {
+        let removed = 0;
+        if (apply) { const r = compactMemory(cwd, a, DEFAULT_MAX_ENTRIES); removed = (r && r.removed) || 0; }
+        result.agents.push({ agent: a, entries: count, over_cap: true, compacted: apply, removed });
+      }
+    }
+  } catch { /* agent sweep is best-effort */ }
+
+  const summary = result.state.changed
+    ? `${apply ? 'optimized' : 'would optimize'} state.md (${result.state.sections_touched.join(', ')}); ${result.archived} entr${result.archived === 1 ? 'y' : 'ies'} archived${result.agents.length ? `; ${result.agents.length} agent log(s)` : ''}`
+    : `state.md already lean${result.agents.length ? `; ${result.agents.length} agent log(s) over budget` : ''} — nothing to do`;
+  output(result, raw, summary);
+}
+
+// ─── Auto-optimize (A3) — flow-embedded reconcile ────────────────────────────
+
+/**
+ * Whether auto-optimize is enabled for this project. Reads config.json directly
+ * (loadConfig doesn't surface the memory block) and defaults to ON — the point
+ * of the feature is that reconcile happens automatically, not by hand. Set
+ * `memory.auto_optimize: false` in .planning/config.json to opt out. Absent or
+ * malformed config → enabled.
+ */
+function autoOptimizeEnabled(cwd) {
+  try {
+    const raw = JSON.parse(fs.readFileSync(path.join(planningPath(cwd), 'config.json'), 'utf-8'));
+    return !(raw.memory && raw.memory.auto_optimize === false);
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * Reconcile state.md as an embedded step of a flow (focus checkpoint, normal
+ * session record). Best-effort and side-effect-light: honors the config gate,
+ * is a true no-op when state.md is already lean (zero git churn), archives any
+ * overflow, and NEVER throws into the calling flow. Returns a small status.
+ * @returns {{optimized:boolean, reason?:string, sections?:string[], archived?:number}}
+ */
+function maybeAutoOptimizeMemory(cwd, opts = {}) {
+  try {
+    if (!autoOptimizeEnabled(cwd)) return { optimized: false, reason: 'disabled' };
+    const statePath = path.join(planningPath(cwd), 'state.md');
+    const before = safeReadFile(statePath);
+    if (before == null) return { optimized: false, reason: 'no_state_md' };
+    const opt = optimizeStateContent(before, { keep: opts.keep });
+    if (!opt.changed) return { optimized: false, reason: 'clean' };
+    appendArchive(cwd, opt.archived, opts.now);
+    writeStateMd(statePath, opt.content, cwd);
+    return { optimized: true, sections: opt.sectionsTouched, archived: opt.archived.length };
+  } catch {
+    return { optimized: false, reason: 'error' };
+  }
+}
+
+module.exports = {
+  optimizeStateContent, reconcileBullets, parseSections, joinSections, cmdMemoryOptimize,
+  maybeAutoOptimizeMemory, autoOptimizeEnabled,
+  APPEND_HEAVY, PLACEHOLDER, DEFAULT_KEEP, STATE_ARCHIVE_FILE,
+};

package/pan-wizard-core/bin/lib/memory-rebuild.cjs

@@ -0,0 +1,156 @@
+'use strict';
+
+/**
+ * PAN memory rebuild (A2) — regenerate DERIVED memory from source, idempotently.
+ *
+ * "Rebuild" is a projection, not a mutation: it re-emits only the regions PAN
+ * owns and can reproduce from source, and leaves everything the user wrote
+ * alone. Per the memory-management research, a rebuild must be an idempotent
+ * projection touching only derived regions — running it twice changes nothing.
+ *
+ * Three derived targets:
+ *   1. AGENTS.md — the universal, cross-runtime tools memory. PAN owns exactly
+ *      the marker-fenced `<!-- BEGIN/END PAN WIZARD -->` section (every runtime,
+ *      including Copilot/.github, reads AGENTS.md natively). User content
+ *      outside the markers is preserved byte-for-byte.
+ *   2. CLAUDE.md — the Claude bridge (`@AGENTS.md` import), regenerated only
+ *      when the Claude runtime is installed here.
+ *   3. state.md — its YAML frontmatter is re-derived from the body (phase
+ *      progress, status). The body prose is never touched.
+ *
+ * Dry-run by default (`--apply` to write). Refuses to run inside the PAN source
+ * repository, mirroring the installer and experiment guards.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { output, safeReadFile } = require('./core.cjs');
+const { planningPath } = require('./utils.cjs');
+const { syncStateFrontmatter } = require('./state.cjs');
+const {
+  buildAgentsMdSection,
+  upsertAgentsMdSection,
+  ensureClaudeMdImport,
+} = require('./agents-md.cjs');
+
+// Source repo root — mirrors experiment.cjs / install.js. __dirname is
+// .../pan-wizard-core/bin/lib, so three levels up is the repo (or install) root.
+const PAN_SOURCE_ROOT = path.resolve(__dirname, '..', '..', '..');
+
+// Runtime → config directory. A runtime is "installed here" when its dir exists
+// in the project. AGENTS.md is shared by all; only Claude gets a bridge file.
+const RUNTIME_DIRS = {
+  claude: '.claude',
+  codex: '.codex',
+  gemini: '.gemini',
+  opencode: '.opencode',
+  copilot: '.github',
+};
+
+function normPath(p) {
+  return process.platform === 'win32' ? p.toLowerCase() : p;
+}
+
+/**
+ * True only when `cwd` is the genuine PAN source repository — inside
+ * PAN_SOURCE_ROOT *and* that root actually looks like the source checkout
+ * (has bin/install.js). In an install layout PAN_SOURCE_ROOT resolves to the
+ * runtime config dir, which has no bin/install.js, so this stays false.
+ */
+function isInsideSourceRepo(cwd) {
+  const abs = normPath(path.resolve(cwd));
+  const src = normPath(PAN_SOURCE_ROOT);
+  const inside = abs === src || abs.startsWith(src + path.sep) || abs.startsWith(src + '/');
+  if (!inside) return false;
+  return fs.existsSync(path.join(PAN_SOURCE_ROOT, 'bin', 'install.js')) &&
+    fs.existsSync(path.join(PAN_SOURCE_ROOT, 'pan-wizard-core'));
+}
+
+/** Which PAN runtimes are installed in this project (by config-dir presence). */
+function detectRuntimes(cwd) {
+  return Object.entries(RUNTIME_DIRS)
+    .filter(([, dir]) => {
+      try { return fs.statSync(path.join(cwd, dir)).isDirectory(); }
+      catch { return false; }
+    })
+    .map(([name]) => name);
+}
+
+/**
+ * Rebuild one file: compute the desired content from `existing`, compare, and
+ * (on apply) write only when it differs. Returns a per-target status.
+ */
+function rebuildFile(filePath, existing, desired, apply) {
+  const absent = existing == null;
+  if (existing === desired) return { action: 'unchanged', wrote: false };
+  const action = absent ? 'create' : 'update';
+  if (apply) fs.writeFileSync(filePath, desired, 'utf-8');
+  return { action, wrote: apply };
+}
+
+/**
+ * `memory rebuild [--apply]` — regenerate derived tools-memory + state.md
+ * frontmatter. Dry-run by default: reports what WOULD change.
+ */
+function cmdMemoryRebuild(cwd, opts = {}, raw) {
+  const apply = !!opts.apply;
+
+  if (isInsideSourceRepo(cwd)) {
+    output(
+      { error: 'source_repo', rebuilt: [] },
+      raw,
+      `refusing to rebuild memory inside the PAN source repository (${PAN_SOURCE_ROOT})`,
+    );
+    return;
+  }
+
+  const runtimes = detectRuntimes(cwd);
+  const targets = [];
+
+  // 1. AGENTS.md — universal PAN section (all runtimes read it natively).
+  {
+    const p = path.join(cwd, 'AGENTS.md');
+    const existing = safeReadFile(p);
+    const desired = upsertAgentsMdSection(existing, buildAgentsMdSection());
+    targets.push({ file: 'AGENTS.md', ...rebuildFile(p, existing, desired, apply) });
+  }
+
+  // 2. CLAUDE.md — Claude bridge, only when the Claude runtime is installed.
+  if (runtimes.includes('claude')) {
+    const p = path.join(cwd, 'CLAUDE.md');
+    const existing = safeReadFile(p);
+    const desired = ensureClaudeMdImport(existing);
+    targets.push({ file: 'CLAUDE.md', ...rebuildFile(p, existing, desired, apply) });
+  }
+
+  // 3. state.md — re-derive YAML frontmatter from the body (progress/status).
+  {
+    const p = path.join(planningPath(cwd), 'state.md');
+    const existing = safeReadFile(p);
+    if (existing != null) {
+      const desired = syncStateFrontmatter(existing, cwd);
+      targets.push({ file: '.planning/state.md', ...rebuildFile(p, existing, desired, apply) });
+    }
+  }
+
+  const changed = targets.filter((t) => t.action !== 'unchanged');
+  const result = {
+    apply,
+    runtimes,
+    rebuilt: targets,
+    changed_count: changed.length,
+  };
+  const summary = changed.length === 0
+    ? `tools memory already current (${targets.map((t) => t.file).join(', ')}) — nothing to do`
+    : `${apply ? 'rebuilt' : 'would rebuild'} ${changed.map((t) => `${t.file} (${t.action})`).join(', ')}`;
+  output(result, raw, summary);
+}
+
+module.exports = {
+  cmdMemoryRebuild,
+  detectRuntimes,
+  isInsideSourceRepo,
+  rebuildFile,
+  PAN_SOURCE_ROOT,
+  RUNTIME_DIRS,
+};

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

@@ -505,6 +505,9 @@ function cmdStateRecordSession(cwd, options, raw) {
 
   if (updated.length > 0) {
     writeStateMd(statePath, content, cwd);
+    // Normal-flow checkpoint: reconcile the always-loaded project memory once
+    // the session is recorded (no-op when already lean; never throws).
+    try { require('./memory-optimize.cjs').maybeAutoOptimizeMemory(cwd); } catch { /* best-effort */ }
     output({ recorded: true, updated }, raw, 'true');
   } else {
     output({ recorded: false, reason: 'No session fields found in state.md' }, raw, 'false');
@@ -1021,6 +1024,7 @@ module.exports = {
   stateExtractField,
   stateReplaceField,
   writeStateMd,
+  syncStateFrontmatter,
   cmdStateLoad,
   cmdStateGet,
   cmdStatePatch,

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

@@ -951,8 +951,18 @@ async function main() {
         }, raw);
       } else if (subcommand === 'budget') {
         memory.cmdMemoryBudget(cwd, raw);
+      } else if (subcommand === 'optimize') {
+        const keepArg = getArgValue(args, '--keep');
+        require('./lib/memory-optimize.cjs').cmdMemoryOptimize(cwd, {
+          apply: args.includes('--apply'),
+          keep: keepArg ? Number(keepArg) : undefined,
+        }, raw);
+      } else if (subcommand === 'rebuild') {
+        require('./lib/memory-rebuild.cjs').cmdMemoryRebuild(cwd, {
+          apply: args.includes('--apply'),
+        }, raw);
       } else {
-        error('Unknown memory subcommand. Available: read, append, list, compact, select, budget');
+        error('Unknown memory subcommand. Available: read, append, list, compact, select, budget, optimize, rebuild');
       }
       break;
     }