pan-wizard 3.19.0 → 3.21.0

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/campaign.cjs

@@ -13,7 +13,7 @@
 const fs = require('fs');
 const path = require('path');
 const { output, error } = require('./core.cjs');
-const { PLANNING_DIR } = require('./constants.cjs');
+const { PLANNING_DIR, VERIFY_RESERVE_FRACTION } = require('./constants.cjs');
 
 const ORCH_DIR = 'orchestration';
 const SCHEDULE_FILE = 'schedule.json';
@@ -169,12 +169,19 @@ function cmdCampaignStatus(cwd, raw) {
   if (!schedule) return output({ scheduled: false }, raw, 'No campaign scheduled');
   const at = new Date();
   const d = isRunDue(schedule, at);
+  // Advisory verify-reserve indicators (status only — does not move the isRunDue
+  // trip threshold): how much of the daily budget is held back for re-verification
+  // and whether today's spend has crossed into it.
+  const fraction = typeof schedule.verify_reserve === 'number' ? schedule.verify_reserve : VERIFY_RESERVE_FRACTION;
+  const verifyReserve = schedule.daily_budget != null && fraction > 0 ? Math.ceil(schedule.daily_budget * fraction) : 0;
+  const intoReserve = verifyReserve > 0 && schedule.daily_budget != null && d.spent_today >= schedule.daily_budget - verifyReserve;
   const result = {
     scheduled: true, enabled: schedule.enabled, paused: schedule.paused,
     cadence: schedule.cadence, daily_budget: schedule.daily_budget,
     next_due: schedule.next_due, last_run: schedule.last_run,
     spent_today: d.spent_today, runs: (schedule.history || []).length,
     due: d.due, reason: d.reason,
+    verify_reserve: verifyReserve, into_verify_reserve: intoReserve,
   };
   const human = `Campaign ${schedule.enabled ? (schedule.paused ? 'paused' : 'active') : 'disabled'} · ${schedule.cadence} · spent ${d.spent_today}/${schedule.daily_budget} today · next ${schedule.next_due} · ${d.due ? 'DUE NOW' : d.reason}`;
   output(result, raw, human);

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

@@ -66,6 +66,9 @@ function buildConfigDefaults(hasBraveSearch, userDefaults) {
       // (HUD, telemetry) but never STOP a run. Set enforce:true (or pass
       // --enforce-budget) to make the cap a hard stop again.
       enforce: false,
+      // Fraction of the spawn budget held back for re-verification (0..0.5).
+      // Surfaced as an indicator always; a hard early stop only under enforce.
+      verify_reserve: 0.15,
     },
     commit: {
       safety_checks: true,

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

@@ -183,6 +183,12 @@ const DEFAULT_MAX_CYCLES = 10;
 
 /** Default cumulative budget cap for auto-runner */
 const DEFAULT_TOTAL_BUDGET = 500;
+// Fraction of the spawn budget held back for re-verification so a run can't
+// exhaust its points on Build/Execute before the quality gate re-checks the
+// work. Advisory by default (an indicator); a hard early stop only under
+// --enforce-budget. FLOOR guards tiny budgets from a zero reserve.
+const VERIFY_RESERVE_FRACTION = 0.15;
+const VERIFY_RESERVE_FLOOR = 1;
 
 // ─── Standards ──────────────────────────────────────────────────────────────
 
@@ -717,6 +723,8 @@ module.exports = {
   CATEGORY_DEFAULTS,
   DEFAULT_MAX_CYCLES,
   DEFAULT_TOTAL_BUDGET,
+  VERIFY_RESERVE_FRACTION,
+  VERIFY_RESERVE_FLOOR,
   // Standards
   STANDARDS_FILE,
   STANDARDS_CATEGORIES,

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

@@ -296,6 +296,9 @@ function loadConfig(cwd) {
       model_overrides: parsed.model_overrides || {},
       effort_overrides: parsed.effort_overrides || {},
       routing: parsed.routing || { strategy: 'static', provider: 'auto' },
+      // Cost dashboard config: `cost.rates` per-model overrides (surfaced so the
+      // documented override actually reaches cost.cjs — it was dropped before).
+      cost: parsed.cost || {},
       // ADR-0031: project build/verification commands. null = not configured
       // (focus-auto --clean-seal then asks or skips rather than guessing).
       build: parsed.build || null,
@@ -312,6 +315,7 @@ function loadConfig(cwd) {
       model_overrides: {},
       effort_overrides: {},
       routing: { strategy: 'static', provider: 'auto' },
+      cost: {},
       build: null,
       verification: null,
       concurrency: { serial_build: false },

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

@@ -148,10 +148,13 @@ function appendRecord(cwd, rec) {
     phase: rec.phase || null,
     session: rec.session || null,
   };
-  // Allow caller-supplied cost override; otherwise compute.
+  // Allow caller-supplied cost override; otherwise compute at the user's
+  // configured rates (config.cost.rates) — without this, CLI-appended rows froze
+  // at DEFAULT_RATES while hook rows (cost_usd:null) got config rates at read
+  // time, so the two producers priced identical tokens differently.
   normalized.cost_usd = typeof rec.cost_usd === 'number'
     ? rec.cost_usd
-    : computeCost(normalized);
+    : computeCost(normalized, loadConfig(cwd)?.cost?.rates);
 
   try {
     fs.mkdirSync(metricsDir(cwd), { recursive: true });
@@ -167,7 +170,16 @@ function appendRecord(cwd, rec) {
  * @param {string} cwd
  * @returns {Array<Object>}
  */
+// Count of malformed (unparseable) rows dropped by the most recent readRecords
+// call. A crash mid-append or interleaved concurrent appends can leave a torn
+// row; surfacing the count (rather than swallowing it) mirrors the existing
+// suspect_excluded contract. Module-level so aggregate() can read it without a
+// breaking change to readRecords' bare-array return (consumed as an array by
+// aggregate, memory.cjs, and hygiene.cjs).
+let _lastReadMalformed = 0;
+
 function readRecords(cwd) {
+  _lastReadMalformed = 0;
   const raw = safeReadFile(tokensFile(cwd));
   if (!raw) return [];
   const records = [];
@@ -175,7 +187,7 @@ function readRecords(cwd) {
     if (!line.trim()) continue;
     try {
       records.push(JSON.parse(line));
-    } catch { /* skip malformed line */ }
+    } catch { _lastReadMalformed += 1; }
   }
   return records;
 }
@@ -207,6 +219,7 @@ function isSuspectRecord(r) {
 
 function aggregate(cwd, opts) {
   const records = readRecords(cwd);
+  const malformedSkipped = _lastReadMalformed; // captured before any later read
   const since = opts?.since ? new Date(opts.since).getTime() : null;
   const until = opts?.until ? new Date(opts.until).getTime() : null;
   const config = loadConfig(cwd);
@@ -229,6 +242,7 @@ function aggregate(cwd, opts) {
     cost_usd: 0,
     cost_unknown: 0,
     suspect_excluded: 0,
+    malformed_skipped: malformedSkipped,
   };
 
   const byAgent = {};
@@ -305,7 +319,7 @@ function renderTable(agg) {
   lines.push(window);
   lines.push('');
   lines.push('Totals');
-  lines.push(`  Calls              : ${agg.totals.calls}`);
+  lines.push(`  Calls              : ${agg.totals.calls}${agg.totals.malformed_skipped > 0 ? ` (+${agg.totals.malformed_skipped} malformed)` : ''}`);
   lines.push(`  Input tokens       : ${agg.totals.input_tokens.toLocaleString()}`);
   lines.push(`  Output tokens      : ${agg.totals.output_tokens.toLocaleString()}`);
   lines.push(`  Cache read         : ${agg.totals.cache_read_tokens.toLocaleString()}`);

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

@@ -15,7 +15,7 @@ const {
   BUDGET_LIMIT_BUGFIX, BUDGET_LIMIT_FULL, STABILITY_RATIO, FEATURE_RATIO,
   DIMINISHING_RETURNS_THRESHOLD,
   AUTO_RUN_FILE, FOCUS_CATEGORIES, FOCUS_SOURCES, CATEGORY_PRIORITY_RANGE, CATEGORY_DEFAULTS,
-  DEFAULT_MAX_CYCLES, DEFAULT_TOTAL_BUDGET,
+  DEFAULT_MAX_CYCLES, DEFAULT_TOTAL_BUDGET, VERIFY_RESERVE_FRACTION, VERIFY_RESERVE_FLOOR,
   BUDGET_MIN, BUDGET_MAX, MAX_CYCLES_MIN, MAX_CYCLES_MAX, TOTAL_BUDGET_MIN, TOTAL_BUDGET_MAX,
   AUTORUN_STATUSES, DOC_SYNC_FILES, COMMAND_RENAME_MAP,
 } = require('./constants.cjs');
@@ -693,12 +693,28 @@ function generateRunId(cwd) {
  * @param {boolean} raw - Raw output mode
  * @param {...string} args - CLI arguments
  */
+/**
+ * Advisory budget indicators for a run: raw remaining, the verify reserve, the
+ * remaining budget for NEW work (excludes the reserve), and whether spend has
+ * crossed into the reserved headroom. Pure — no behavior change; surfaced so the
+ * human/HUD can see the reserve even when it isn't being enforced.
+ */
+function budgetIndicators(run) {
+  const used = run.totals ? run.totals.points_used : 0;
+  const reserve = run.verify_reserve || 0;
+  return {
+    budget_remaining: run.total_budget - used,
+    verify_reserve: reserve,
+    new_work_budget_remaining: run.total_budget - reserve - used,
+    into_verify_reserve: reserve > 0 && used >= run.total_budget - reserve,
+  };
+}
+
 function focusAutoStatus(cwd, raw) {
   const run = readAutoRun(cwd);
   if (!run) return error('No auto-run found. Start with: focus auto --category <name>');
-  const budgetRemaining = run.total_budget - (run.totals ? run.totals.points_used : 0);
   const cyclesRemaining = run.max_cycles - (run.totals ? run.totals.cycles_completed : 0);
-  return output({ ...run, budget_remaining: budgetRemaining, cycles_remaining: cyclesRemaining }, raw);
+  return output({ ...run, ...budgetIndicators(run), cycles_remaining: cyclesRemaining }, raw);
 }
 
 function focusAutoStop(cwd, raw) {
@@ -781,6 +797,30 @@ function focusAutoUpdate(cwd, raw, getVal) {
   cycle.tests_verified = tv.verified;
 
   if (!run.cycles) run.cycles = [];
+
+  // Attribution: anchor this cycle to a start, measure its wall-clock duration,
+  // name the driving command, and JOIN to the authoritative cost ledger so the
+  // cycle carries the agents + dollars behind its item counts (not just a
+  // self-reported points estimate). windowStart = the prior cycle's end, or the
+  // run start for cycle 1. Server-side join — no fakeable CLI arg.
+  const windowStart = run.cycles.length ? run.cycles[run.cycles.length - 1].timestamp : run.started_at;
+  cycle.started_at = windowStart || null;
+  const durMs = windowStart ? (new Date(cycle.timestamp) - new Date(windowStart)) : NaN;
+  cycle.duration_ms = Number.isFinite(durMs) ? durMs : null;
+  cycle.command = getVal('--command', run.category || run.source || null);
+  cycle.cost_usd = null;
+  cycle.tokens = null;
+  cycle.agents = [];
+  if (windowStart) {
+    try {
+      const agg = require('./cost.cjs').aggregate(cwd, { since: windowStart, until: cycle.timestamp });
+      if (agg && agg.totals) {
+        cycle.cost_usd = agg.totals.calls > 0 ? agg.totals.cost_usd : null;
+        cycle.tokens = { input: agg.totals.input_tokens, output: agg.totals.output_tokens, cache_read: agg.totals.cache_read_tokens };
+        cycle.agents = agg.by_agent ? Object.keys(agg.by_agent) : [];
+      }
+    } catch { /* cost is observability, never the critical path */ }
+  }
   run.cycles.push(cycle);
 
   if (!run.totals) {
@@ -848,6 +888,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);
@@ -865,7 +908,13 @@ function determineStopReason(cycle, run) {
   if (cycle.tests_after < cycle.tests_before) return 'regression';
   // Budget is advisory by default — it only STOPS the run when explicitly enforced.
   // Otherwise the overage is tracked/surfaced (indication) and the loop continues.
+  // Hard cap (full budget) is evaluated FIRST so it remains the absolute boundary;
+  // the softer verify-reserve stop only fires in the band below it.
   if (run.budget_enforce && run.totals.points_used >= run.total_budget) return 'budget_cap';
+  // Verify-reserve: under enforcement, stop once new-work spend crosses into the
+  // reserved headroom so re-verification still has points. Advisory mode never trips.
+  const reserve = run.verify_reserve || 0;
+  if (run.budget_enforce && reserve > 0 && run.totals.points_used >= run.total_budget - reserve) return 'budget_reserve_reached';
   if (run.totals.cycles_completed >= run.max_cycles) return 'max_cycles';
   if (cycle.items_completed === 0) {
     // Security category gets a descriptive stop reason rather than generic zero_completed
@@ -902,9 +951,8 @@ function focusAutoContinue(cwd, raw) {
   run.status = run.totals && run.totals.cycles_completed > 0 ? AUTORUN_STATUSES.IN_PROGRESS : AUTORUN_STATUSES.INITIALIZED;
   run.stop_reason = null;
   writeAutoRun(cwd, run);
-  const budgetRemaining = run.total_budget - (run.totals ? run.totals.points_used : 0);
   const cyclesRemaining = run.max_cycles - (run.totals ? run.totals.cycles_completed : 0);
-  return output({ ...run, budget_remaining: budgetRemaining, cycles_remaining: cyclesRemaining }, raw);
+  return output({ ...run, ...budgetIndicators(run), cycles_remaining: cyclesRemaining }, raw);
 }
 
 function focusAutoInit(cwd, raw, getVal, hasFlag) {
@@ -935,6 +983,15 @@ function focusAutoInit(cwd, raw, getVal, hasFlag) {
   // only when the user opts in via config `budget.enforce` or `--enforce-budget`.
   const budgetConfig = loadConfig(cwd).budget || {};
   const budgetEnforce = hasFlag('--enforce-budget') || budgetConfig.enforce === true;
+  // Verify-reserve: hold back a fraction of the spawn budget so re-verification
+  // isn't starved of points. Advisory by default (surfaced as an indicator);
+  // only a hard early stop under --enforce-budget. Clamp the fraction to 0..0.5.
+  const reserveRaw = getVal('--verify-reserve', null);
+  let reserveFraction = reserveRaw != null ? Number(reserveRaw)
+    : (typeof budgetConfig.verify_reserve === 'number' ? budgetConfig.verify_reserve : VERIFY_RESERVE_FRACTION);
+  if (!Number.isFinite(reserveFraction) || reserveFraction < 0) reserveFraction = 0;
+  if (reserveFraction > 0.5) reserveFraction = 0.5;
+  const verifyReserve = reserveFraction > 0 ? Math.max(VERIFY_RESERVE_FLOOR, Math.ceil(totalBudget * reserveFraction)) : 0;
 
   if (!FOCUS_MODES.includes(mode)) return error(`Mode must be one of: ${FOCUS_MODES.join(', ')}`);
   if (budget < BUDGET_MIN || budget > BUDGET_MAX) return error(`Budget must be between ${BUDGET_MIN} and ${BUDGET_MAX}`);
@@ -944,6 +1001,7 @@ function focusAutoInit(cwd, raw, getVal, hasFlag) {
   const runData = {
     run_id: generateRunId(cwd),
     status: AUTORUN_STATUSES.INITIALIZED,
+    started_at: new Date().toISOString(),
     source: source,
     category: category,
     mode: mode,
@@ -954,6 +1012,7 @@ function focusAutoInit(cwd, raw, getVal, hasFlag) {
     max_cycles: maxCycles,
     total_budget: totalBudget,
     budget_enforce: budgetEnforce,
+    verify_reserve: verifyReserve,
     priority_range: category ? CATEGORY_PRIORITY_RANGE[category] : { min: 0, max: 6 },
     deep_review_enabled: hasFlag('--deep-review'),
     tests_baseline: null,

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,
+};