pan-wizard 3.31.0 → 3.32.0

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

@@ -541,6 +541,15 @@ const HEALTH_STATUS = { HEALTHY: 'healthy', DEGRADED: 'degraded', BROKEN: 'broke
 /** Max JSON payload size before writing to tmpfile (bytes) */
 const MAX_JSON_SIZE = 50000;
 
+/**
+ * Shape version of the machine-readable state JSON: `state` (load), `state json`,
+ * `progress` (json) and the MCP resources that wrap them (market item M17).
+ * Additive rule: fields may be added within a major version and are never renamed
+ * or removed; readers accept any 1.x and ignore fields they do not know. A rename
+ * or removal is a major bump ("2.0").
+ */
+const STATE_CONTRACT = '1.0';
+
 /** Width of progress bar in status display (character count) */
 const PROGRESS_BAR_WIDTH = 10;
 
@@ -724,6 +733,24 @@ const FOREIGN_PLANNING_MARKERS = Object.freeze({
       'graphify.enabled', 'intel.enabled', 'hooks.workflow_guard', 'dynamic_routing', 'resolve_model_ids',
     ]),
   }),
+  // planning-with-files (OthmanAdi/planning-with-files README, read 2026-09-28 at
+  // v3.21.0; market item M3 / MI-028). It writes INTO .planning/ beside whatever else
+  // lives there: `.active_plan`, `.attestation`, `sessions/`, `ledger-<agent>.jsonl`, and
+  // one `YYYY-MM-DD-slug/` directory per task holding task_plan.md / findings.md /
+  // progress.md. PAN writes none of those names. `coexists`: unlike gsd-core, a match
+  // means the tree is SHARED, not owned. PAN keeps working in it and says so, rather
+  // than refusing. planning-with-files gitignores .planning/ by default, which is what
+  // the I005 health check exists for.
+  planning_with_files: Object.freeze({
+    tool: 'planning-with-files',
+    coexists: true,
+    files: Object.freeze(['.active_plan', '.attestation']),
+    filePatterns: Object.freeze([/^ledger-[A-Za-z0-9._-]+\.jsonl$/]),
+    dirs: Object.freeze(['sessions']),
+    // A dated task directory is strong evidence only with the tool's plan file in it.
+    dirPatterns: Object.freeze([{ re: /^\d{4}-\d{2}-\d{2}-[A-Za-z0-9][A-Za-z0-9._-]*$/, requires: 'task_plan.md' }]),
+    configKeys: Object.freeze([]),
+  }),
 });
 
 module.exports = {
@@ -806,6 +833,7 @@ module.exports = {
   HEALTH_STATUS,
   FOREIGN_PLANNING_MARKERS,
   MAX_JSON_SIZE,
+  STATE_CONTRACT,
   PROGRESS_BAR_WIDTH,
   MAX_SLUG_LENGTH,
   FILLED_BLOCK,

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

@@ -59,7 +59,7 @@ const DEFAULT_RATES = {
   // Anthropic — platform.claude.com/docs/en/about-claude/pricing, every row read
   // 2026-09-23. Opus 4.6+/Opus 5 are $5/$25 (the old $15/$75 Opus pricing ended with
   // the 4.5 generation). cache_write is the 5-minute write rate (1.25× input; the
-  // 1-hour write bills 2×, which the ledger does not split yet). Cache reads follow
+  // 1-hour write bills 2× and is priced from cache_write_1h, see above). Cache reads follow
   // the 0.1× convention EXCEPT on three models the page footnotes: Fable 5.1 and
   // Mythos 5.1 at 0.025× input, Opus 5.5 at 0.05×. Each needs its own row, because
   // the family-prefix fallback would otherwise price it at its predecessor's reads.
@@ -469,8 +469,8 @@ function readRecords(cwd) {
  */
 // No single subagent runs for six hours — the longest native-workflow phase runs
 // measured in the harness finish inside an hour — while a parent-transcript slice
-// that spans a working day, or the idle night between two stops, does. Mirrored by
-// the hooks' SLICE_MAX_DURATION_MS, which nulls the span on write. Calibrated on
+// that spans a working day, or the idle night between two stops, does. The hooks
+// write the span as measured; only this reader applies the rule. Calibrated on
 // eleven field ledgers (2026-09): of the timed rows the old ratio rule flagged,
 // 55 spanned under three hours and 12 spanned six to twenty-four — the latter all
 // parent slices booked to a `general-purpose` or workflow subagent.

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

@@ -0,0 +1,381 @@
+'use strict';
+/**
+ * Findings ledger — what PAN's judges found, and what was done about it
+ * (evidence loop, docs/specs/evidence_loop_featureai.md §3.4; ADR-0049).
+ *
+ * `.planning/findings.jsonl` is append-only, like the cost and trace ledgers, so
+ * parallel writers and interrupted runs never lose an update. Three row kinds:
+ *
+ *   verdict      one recorded judge report (agent, phase, outcome, attempt, the ids it listed)
+ *   finding      one finding, written the first time its id is seen
+ *   disposition  fixed | deferred | dismissed | decision, with a reason
+ *
+ * Status is FOLDED on read, never stored (D6):
+ *   - the latest disposition wins;
+ *   - except `fixed`, which gives way to `open` when a newer verdict reports the id
+ *     again (a regression);
+ *   - with no disposition, a finding is `open`.
+ *
+ * Two rules are applied when a verdict is recorded:
+ *   - AUTO-FIX: the same agent's earlier open findings on the phase that the new
+ *     verdict does not report become `fixed`. That is how a gap-closure round
+ *     closes its gaps. `human` and `unrequested` are exempt, because a re-run does
+ *     not re-check them.
+ *   - IDEMPOTENCY: recording the same artifact twice is a no-op that returns the
+ *     first verdict (record_sig). That is why exec-phase and verify-phase may both
+ *     record one verification.md.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { output, toPosix, normalizePhaseName, findPhaseInternal, getMilestoneInfo } = require('./core.cjs');
+const { planningPath, planningRel } = require('./utils.cjs');
+const V = require('./verdict.cjs');
+
+const FINDINGS_FILE = 'findings.jsonl';
+const LEDGER_V = 1;
+const REASON_MAX = 300;
+const FINDING_ID_RE = /^f_[0-9a-f]{10}$/;
+const STATUSES = Object.freeze(['open', ...V.DISPOSITIONS]);
+
+function ledgerPath(cwd) {
+  return planningPath(cwd, FINDINGS_FILE);
+}
+
+function sha(s) {
+  return crypto.createHash('sha256').update(s, 'utf8').digest('hex');
+}
+
+/** Ledger rows in file order; malformed lines are counted, never fatal. */
+function readLedger(cwd) {
+  let raw = '';
+  try { raw = fs.readFileSync(ledgerPath(cwd), 'utf-8'); } catch { return { rows: [], malformed: 0 }; }
+  const rows = [];
+  let malformed = 0;
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const r = JSON.parse(line);
+      if (r && typeof r === 'object' && typeof r.kind === 'string') rows.push(r);
+      else malformed++;
+    } catch { malformed++; }
+  }
+  return { rows, malformed };
+}
+
+/**
+ * Fold the ledger into verdicts and findings with their derived status.
+ * Row order (sequence), not timestamps, decides "newer": clocks can disagree,
+ * an append-only file cannot.
+ */
+function foldFindings(rows) {
+  const verdicts = [];
+  const findings = new Map();
+  rows.forEach((r, seq) => {
+    if (r.kind === 'finding' && typeof r.id === 'string' && !findings.has(r.id)) {
+      findings.set(r.id, {
+        id: r.id, phase: r.phase, milestone: r.milestone || null, agent: r.agent, class: r.class,
+        severity: r.severity, where: r.where || null, summary: r.summary, first_seen: r.ts,
+        first_verdict_id: r.verdict_id || null, reports: 0, last_reported: null, _reportedSeq: -1,
+        disposition: null, reason: null, disposed_at: null, auto: false, _disposedSeq: -1,
+      });
+    } else if (r.kind === 'verdict') {
+      verdicts.push({ ...r, _seq: seq });
+      for (const id of Array.isArray(r.finding_ids) ? r.finding_ids : []) {
+        const f = findings.get(id);
+        if (!f) continue;
+        f.reports++;
+        f.last_reported = r.ts;
+        f._reportedSeq = seq;
+      }
+    } else if (r.kind === 'disposition' && typeof r.id === 'string') {
+      const f = findings.get(r.id);
+      if (!f || !V.DISPOSITIONS.includes(r.disposition)) return;
+      f.disposition = r.disposition;
+      f.reason = r.reason || null;
+      f.disposed_at = r.ts;
+      f.auto = r.auto === true;
+      f._disposedSeq = seq;
+    }
+  });
+  for (const f of findings.values()) {
+    if (!f.disposition) f.status = 'open';
+    else if (f.disposition === 'fixed' && f._reportedSeq > f._disposedSeq) f.status = 'open';
+    else f.status = f.disposition;
+  }
+  return { verdicts, findings };
+}
+
+/** A finding as the CLI shows it (internal sequence fields removed). */
+function publicFinding(f) {
+  const { _reportedSeq, _disposedSeq, ...rest } = f;
+  return rest;
+}
+
+function countBy(list, key) {
+  const out = {};
+  for (const x of list) out[x[key]] = (out[x[key]] || 0) + 1;
+  return out;
+}
+
+function samePhase(a, b) {
+  return V.comparablePhase(a) === V.comparablePhase(b);
+}
+
+/** `.planning/` must exist: the ledger fills a planning tree, it never creates one. */
+function requirePlanningTree(cwd) {
+  try { return fs.statSync(planningPath(cwd)).isDirectory(); } catch { return false; }
+}
+
+function appendRows(cwd, rows) {
+  if (!rows.length) return;
+  fs.appendFileSync(ledgerPath(cwd), rows.map((r) => JSON.stringify(r)).join('\n') + '\n', 'utf-8');
+}
+
+/** Log a trace event through optimize.cjs; best effort, never fails a record. */
+function traceEvent(cwd, event) {
+  try { require('./optimize.cjs').logTraceEvent(cwd, event); } catch { /* telemetry is best effort */ }
+}
+
+/**
+ * Record a judge's verdict from an artifact's text.
+ * @param {string} cwd
+ * @param {{phase: string, text: string, source?: string, agent?: string}} input
+ * @returns {Object} the record result, or `{error, reason}`
+ */
+function recordVerdict(cwd, input) {
+  if (!requirePlanningTree(cwd)) return { error: 'not_a_pan_project', reason: 'no .planning/ directory here' };
+  if (!input.phase) return { error: 'phase_required', reason: 'findings record needs --phase <N>' };
+  const phaseInfo = findPhaseInternal(cwd, input.phase);
+  if (!phaseInfo) return { error: 'phase_not_found', reason: `no phase directory for phase ${input.phase}` };
+  const phase = normalizePhaseName(phaseInfo.phase_number || input.phase);
+  const text = typeof input.text === 'string' ? input.text : '';
+  if (!text.trim()) return { error: 'empty_input', reason: 'nothing to record' };
+
+  const parsed = V.parseVerdictText(text, { agent: input.agent, phase });
+  if (!parsed.ok) return { error: parsed.error, reason: parsed.reason };
+  const verdict = parsed.verdict;
+  const agent = verdict.agent;
+  const recordSig = V.recordSig(text);
+
+  const { rows } = readLedger(cwd);
+  const fold = foldFindings(rows);
+  const base = { contract: V.VERDICT_CONTRACT, agent, verdict: verdict.verdict, outcome: verdict.outcome, source_kind: parsed.source_kind, warnings: parsed.warnings };
+
+  const dup = fold.verdicts.find((r) => r.record_sig === recordSig && r.agent === agent && samePhase(r.phase, phase));
+  if (dup) {
+    return { ...base, recorded: false, duplicate: true, verdict_id: dup.verdict_id, attempt: dup.attempt, phase, findings: (dup.finding_ids || []).length, new: 0, auto_fixed: 0, reopened: 0 };
+  }
+
+  const prior = fold.verdicts.filter((r) => r.agent === agent && samePhase(r.phase, phase));
+  const attempt = prior.length + 1;
+  const previous = prior.length ? prior[prior.length - 1] : null;
+  const ts = new Date().toISOString();
+  const milestone = getMilestoneInfo(cwd).version || null;
+  const verdictId = 'v_' + sha([recordSig, phase, agent, rows.length].join('\u0000')).slice(0, 10);
+
+  const ids = [];
+  const newRows = [];
+  const findingRows = [];
+  for (const f of verdict.findings) {
+    const id = V.findingId(phase, agent, f);
+    if (ids.includes(id)) continue; // the same finding twice in one report is one finding
+    ids.push(id);
+    if (!fold.findings.has(id)) {
+      findingRows.push({ v: LEDGER_V, kind: 'finding', ts, id, verdict_id: verdictId, phase, milestone, agent, class: f.class, severity: f.severity, where: f.where, summary: f.summary });
+    }
+  }
+  const reopened = ids.filter((id) => fold.findings.has(id) && fold.findings.get(id).status === 'fixed').length;
+  const autoFixRows = [];
+  for (const f of fold.findings.values()) {
+    if (f.agent !== agent || !samePhase(f.phase, phase) || f.status !== 'open') continue;
+    if (ids.includes(f.id) || V.AUTO_FIX_EXEMPT.includes(f.class)) continue;
+    autoFixRows.push({ v: LEDGER_V, kind: 'disposition', ts, id: f.id, disposition: 'fixed', reason: `not reported by ${agent} at attempt ${attempt}`, auto: true, verdict_id: verdictId });
+  }
+
+  const bySeverity = countBy(verdict.findings, 'severity');
+  const byClass = countBy(verdict.findings, 'class');
+  let source = '(text)';
+  if (input.source) {
+    const rel = path.relative(path.resolve(cwd), path.resolve(cwd, input.source));
+    source = rel && !rel.startsWith('..') && !path.isAbsolute(rel) ? toPosix(rel) : '(external file)';
+  }
+  newRows.push({
+    v: LEDGER_V, kind: 'verdict', ts, verdict_id: verdictId, record_sig: recordSig, phase, milestone, agent,
+    verdict: verdict.verdict, outcome: verdict.outcome, attempt, source, finding_ids: ids,
+    by_severity: bySeverity, by_class: byClass, warnings: parsed.warnings,
+  });
+  appendRows(cwd, [...findingRows, ...newRows, ...autoFixRows]);
+
+  const category = { pass: 'verdict_passed', fail: 'verdict_failed', needs_human: 'verdict_needs_human' }[verdict.outcome];
+  const serious = (bySeverity.critical || 0) + (bySeverity.high || 0) > 0;
+  traceEvent(cwd, {
+    type: verdict.outcome === 'fail' ? 'error' : 'decision',
+    category,
+    agent,
+    phase,
+    description: `${agent} ${verdict.verdict || verdict.outcome} on phase ${phase} (attempt ${attempt}, ${ids.length} finding${ids.length === 1 ? '' : 's'})`,
+    impact: verdict.outcome === 'fail' ? (serious ? 'major' : 'minor') : 'minor',
+    context: { agent, phase, verdict: verdict.verdict, attempt, findings: ids.length, by_severity: bySeverity, by_class: byClass, verdict_id: verdictId },
+  });
+  if (previous && previous.outcome === 'fail') {
+    traceEvent(cwd, {
+      type: 'correction',
+      category: 'verdict_retry',
+      agent,
+      phase,
+      description: `${agent} judged phase ${phase} again (attempt ${attempt}): ${previous.outcome} → ${verdict.outcome}, ${autoFixRows.length} earlier finding(s) no longer reported`,
+      impact: 'minor',
+      context: { agent, phase, attempt, previous_outcome: previous.outcome, outcome: verdict.outcome, auto_fixed: autoFixRows.length, reopened, verdict_id: verdictId },
+    });
+  }
+
+  return { ...base, recorded: true, duplicate: false, verdict_id: verdictId, attempt, phase, findings: ids.length, new: findingRows.length, auto_fixed: autoFixRows.length, reopened, ledger: planningRel(FINDINGS_FILE) };
+}
+
+/**
+ * Record a disposition for findings, by id or in bulk (`--phase N [--agent A] --open`).
+ * @param {{ids?: string[], phase?: string, agent?: string, open?: boolean, as: string, reason?: string}} input
+ */
+function disposeFindings(cwd, input) {
+  if (!requirePlanningTree(cwd)) return { error: 'not_a_pan_project', reason: 'no .planning/ directory here' };
+  const as = String(input.as || '').trim().toLowerCase();
+  if (!V.DISPOSITIONS.includes(as)) return { error: 'invalid_disposition', reason: `--as must be one of ${V.DISPOSITIONS.join(', ')}` };
+  const reason = input.reason == null ? '' : String(input.reason).replace(/\s+/g, ' ').trim().slice(0, REASON_MAX);
+  if (V.REASON_REQUIRED.includes(as) && !reason) {
+    return { error: 'reason_required', reason: `a ${as} disposition needs --reason "<why>" (MI-031: never dispose silently)` };
+  }
+  const { rows } = readLedger(cwd);
+  const fold = foldFindings(rows);
+  let targets;
+  if (Array.isArray(input.ids) && input.ids.length) {
+    targets = input.ids;
+  } else if (input.open && input.phase) {
+    targets = [...fold.findings.values()]
+      .filter((f) => f.status === 'open' && samePhase(f.phase, input.phase) && (!input.agent || f.agent === input.agent))
+      .map((f) => f.id);
+  } else {
+    return { error: 'no_targets', reason: 'name finding ids, or --phase <N> --open [--agent <name>]' };
+  }
+  const ts = new Date().toISOString();
+  const disposed = [];
+  const skipped = [];
+  const out = [];
+  for (const id of targets) {
+    const f = fold.findings.get(id);
+    if (!f) { skipped.push({ id, why: 'unknown id' }); continue; }
+    if (f.status === as) { skipped.push({ id, why: `already ${as}` }); continue; }
+    out.push({ v: LEDGER_V, kind: 'disposition', ts, id, disposition: as, reason: reason || null, auto: false });
+    disposed.push(id);
+  }
+  appendRows(cwd, out);
+  return { contract: V.VERDICT_CONTRACT, disposition: as, disposed, skipped };
+}
+
+/** Findings with their folded status, filtered. */
+function listFindings(cwd, filters = {}) {
+  const { rows, malformed } = readLedger(cwd);
+  const fold = foldFindings(rows);
+  let list = [...fold.findings.values()];
+  if (filters.phase) list = list.filter((f) => samePhase(f.phase, filters.phase));
+  if (filters.agent) list = list.filter((f) => f.agent === filters.agent);
+  if (filters.status) list = list.filter((f) => f.status === filters.status);
+  if (filters.class) list = list.filter((f) => f.class === filters.class);
+  if (filters.milestone) list = list.filter((f) => f.milestone === filters.milestone);
+  const findings = list.map(publicFinding);
+  return {
+    contract: V.VERDICT_CONTRACT,
+    findings,
+    counts: { total: findings.length, by_status: countBy(findings, 'status'), by_class: countBy(findings, 'class'), by_severity: countBy(findings, 'severity') },
+    verdicts: fold.verdicts.length,
+    malformed_rows: malformed,
+  };
+}
+
+/**
+ * Tech debt for a milestone audit: deferred findings (with the reason recorded at
+ * the time) and findings nobody disposed, grouped by phase.
+ */
+function findingsDebt(cwd, opts = {}) {
+  const milestone = opts.milestone || getMilestoneInfo(cwd).version || null;
+  const { rows } = readLedger(cwd);
+  const fold = foldFindings(rows);
+  const byPhase = new Map();
+  for (const f of fold.findings.values()) {
+    if (milestone && f.milestone !== milestone) continue;
+    if (f.status !== 'deferred' && f.status !== 'open') continue;
+    const key = V.comparablePhase(f.phase);
+    if (!byPhase.has(key)) byPhase.set(key, { phase: f.phase, deferred: [], open: [] });
+    byPhase.get(key)[f.status === 'deferred' ? 'deferred' : 'open'].push(publicFinding(f));
+  }
+  const phases = [...byPhase.values()].sort((a, b) => String(a.phase).localeCompare(String(b.phase), undefined, { numeric: true }));
+  return {
+    contract: V.VERDICT_CONTRACT,
+    milestone,
+    phases,
+    deferred_count: phases.reduce((n, p) => n + p.deferred.length, 0),
+    open_count: phases.reduce((n, p) => n + p.open.length, 0),
+  };
+}
+
+// ─── CLI ─────────────────────────────────────────────────────────────────────
+
+function cmdFindingsRecord(cwd, opts, raw) {
+  let text = null;
+  let source = null;
+  const inputs = [opts.file != null, opts.text != null, !!opts.stdin].filter(Boolean).length;
+  if (inputs !== 1) { output({ error: 'one_input', reason: 'give exactly one of --file <path>, --text <string>, --stdin' }, raw); return; }
+  if (opts.file != null) {
+    try { text = fs.readFileSync(path.resolve(cwd, opts.file), 'utf-8'); } catch (e) {
+      output({ error: 'unreadable_file', reason: `cannot read ${opts.file}: ${e.code || e.message}` }, raw);
+      return;
+    }
+    source = opts.file;
+  } else if (opts.text != null) {
+    text = String(opts.text);
+  } else {
+    try { text = fs.readFileSync(0, 'utf-8'); } catch { text = ''; }
+    source = null;
+  }
+  const r = recordVerdict(cwd, { phase: opts.phase, text, source, agent: opts.agent });
+  // --raw prints the judge's own verdict word (the word the workflow branches on),
+  // or the outcome when the report gave none. A failed verdict is data: exit 0.
+  output(r, raw, r.error ? undefined : (r.verdict || r.outcome));
+}
+
+function cmdFindingsDispose(cwd, opts, raw) {
+  output(disposeFindings(cwd, opts), raw);
+}
+
+function cmdFindingsList(cwd, opts, raw) {
+  if (opts.status && !STATUSES.includes(opts.status)) { output({ error: 'invalid_status', reason: `--status must be one of ${STATUSES.join(', ')}` }, raw); return; }
+  if (opts.class && !V.FINDING_CLASSES.includes(opts.class)) { output({ error: 'invalid_class', reason: `--class must be one of ${V.FINDING_CLASSES.join(', ')}` }, raw); return; }
+  const r = listFindings(cwd, opts);
+  output(r, raw, String(r.counts.total));
+}
+
+function cmdFindingsDebt(cwd, opts, raw) {
+  const r = findingsDebt(cwd, opts);
+  output(r, raw, `${r.deferred_count} deferred, ${r.open_count} open`);
+}
+
+/** Positional finding ids in an argv slice. */
+function findingIdsIn(args) {
+  return args.filter((a) => FINDING_ID_RE.test(a));
+}
+
+module.exports = {
+  FINDINGS_FILE,
+  STATUSES,
+  readLedger,
+  foldFindings,
+  recordVerdict,
+  disposeFindings,
+  listFindings,
+  findingsDebt,
+  findingIdsIn,
+  cmdFindingsRecord,
+  cmdFindingsDispose,
+  cmdFindingsList,
+  cmdFindingsDebt,
+};

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

@@ -566,30 +566,76 @@ function cmdFocusSync(cwd, raw, ...args) {
 
 // ─── Exec helpers ───────────────────────────────────────────────────────────
 
+const BATCH_DATE_RE = /^batch-(\d{4}-\d{2}-\d{2})/;
+
 /**
- * Read the oldest open batch file from .planning/focus/.
- * Batches are named batch-YYYY-MM-DD.json; lexical sort == chronological.
- * Oldest-first ensures older unfinished batches get executed before newer ones.
+ * The batch files in .planning/focus/, oldest first; the last one is the batch to run.
+ * Order: the date in the name, then the modification time for batches planned the same
+ * day, then the name. `focus plan` writes batch-YYYY-MM-DD.json; `/pan:focus-auto` and
+ * hand-planned batches add a slug after the date, which a plain name sort would rank
+ * below the same day's plain file whatever order they were written in. This is the one
+ * ordering every reader uses: `focus exec`, `focus classify-stages` and `preflight
+ * batch` each used to choose a batch its own way.
  * @param {string} cwd - Project root
- * @returns {Object|null} Parsed batch data or null
+ * @returns {string[]} File names, oldest first
  */
-function readLatestBatch(cwd) {
+function listBatchFiles(cwd) {
   const focusDir = planningPath(cwd, FOCUS_DIR);
-  let files;
+  let names;
   try {
-    files = fs.readdirSync(focusDir).filter(f => f.startsWith('batch-') && f.endsWith('.json'));
+    names = fs.readdirSync(focusDir).filter(f => f.startsWith('batch-') && f.endsWith('.json'));
   } catch {
-    return null;
+    return [];
   }
+  const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+  return names
+    .map((name) => {
+      const m = BATCH_DATE_RE.exec(name);
+      let mtime = 0;
+      try { mtime = fs.statSync(path.join(focusDir, name)).mtimeMs; } catch { /* removed meanwhile */ }
+      return { name, date: m ? m[1] : '', mtime };
+    })
+    .sort((a, b) => cmp(a.date, b.date) || a.mtime - b.mtime || cmp(a.name, b.name))
+    .map((e) => e.name);
+}
+
+/**
+ * Read the newest batch in .planning/focus/, with its items as an array.
+ *
+ * Newest, not oldest. v2.10.0 (E-12) sorted ascending so "older unfinished batches
+ * execute before newer ones", but nothing ever marks a batch finished, so it returned
+ * the first batch a project planned, every time. `/pan:focus-exec` executes the newest
+ * batch, so its `classify-stages` step was classifying a different batch from the one it
+ * ran. A batch is a snapshot of the backlog: a newer plan already carries whatever an
+ * older one left undone.
+ *
+ * Items: `focus plan` writes them under `batch`. `/pan:focus-auto` documents `items`, and
+ * batches agents write put the list under `items`, often with `batch` holding the batch's
+ * NAME (measured 2026-09-29, structure only: 1 of 102 batch files in four projects had a
+ * `batch` array). Either way the list comes back as `.batch`, with the key it came from
+ * in `.items_key`, a string `batch` kept as `.batch_name`, and the file name in `.file`.
+ *
+ * @param {string} cwd - Project root
+ * @returns {Object|null} null when there is no batch file. When the newest file cannot be
+ *   used: `{ file, error, batch: [], items_key: null }`. An older batch never stands in.
+ */
+function readLatestBatch(cwd) {
+  const files = listBatchFiles(cwd);
   if (files.length === 0) return null;
-  files.sort();
-  const content = safeReadFile(path.join(focusDir, files[0]));
-  if (!content) return null;
+  const file = files[files.length - 1];
+  const unusable = (why) => ({ file, error: `${file} ${why}`, batch: [], items_key: null });
+  let data;
   try {
-    return JSON.parse(content);
+    data = JSON.parse(safeReadFile(path.join(planningPath(cwd, FOCUS_DIR), file)));
   } catch {
-    return null;
+    return unusable('is not valid JSON');
   }
+  if (!data || typeof data !== 'object' || Array.isArray(data)) return unusable('is not a batch object');
+  const itemsKey = Array.isArray(data.batch) ? 'batch' : Array.isArray(data.items) ? 'items' : null;
+  if (!itemsKey) return unusable('has no item list (expected a "batch" or "items" array)');
+  const out = { ...data, batch: data[itemsKey], items_key: itemsKey, file };
+  if (typeof data.batch === 'string') out.batch_name = data.batch;
+  return out;
 }
 
 /**
@@ -619,16 +665,22 @@ function cmdFocusExec(cwd, raw, ...args) {
     output({ error: 'No batch file found. Run focus plan first.' }, raw);
     return;
   }
+  const batchFile = planningRel(FOCUS_DIR, batch.file);
+  if (batch.error) {
+    output({ error: batch.error, batch_file: batchFile }, raw);
+    return;
+  }
 
   if (batch.batch.length === 0) {
-    output({ error: 'Batch is empty. Run focus plan with items.' }, raw);
+    output({ error: 'Batch is empty. Run focus plan with items.', batch_file: batchFile }, raw);
     return;
   }
 
-  // Classify items by tier
-  const micro = batch.batch.filter(i => i.tier === FOCUS_TIERS.MICRO);
-  const standard = batch.batch.filter(i => i.tier === FOCUS_TIERS.STANDARD);
-  const full = batch.batch.filter(i => i.tier === FOCUS_TIERS.FULL);
+  // Classify items by tier (agent-written batches can hold non-object entries)
+  const tierOf = (i) => (i && typeof i === 'object' ? i.tier : undefined);
+  const micro = batch.batch.filter(i => tierOf(i) === FOCUS_TIERS.MICRO);
+  const standard = batch.batch.filter(i => tierOf(i) === FOCUS_TIERS.STANDARD);
+  const full = batch.batch.filter(i => tierOf(i) === FOCUS_TIERS.FULL);
 
   const result = {
     dry_run: dryRun,
@@ -642,7 +694,7 @@ function cmdFocusExec(cwd, raw, ...args) {
       full: full.length,
     },
     items: batch.batch,
-    batch_file: planningRel(FOCUS_DIR, `batch-${batch.date}.json`),
+    batch_file: batchFile,
   };
 
   output(result, raw);
@@ -1192,6 +1244,7 @@ module.exports = {
   checkVersionCrossRef,
   // Exec
   cmdFocusExec,
+  listBatchFiles,
   readLatestBatch,
   // Auto
   categoryFilter,

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

@@ -11,10 +11,14 @@
  * tool? — from POSITIVE markers PAN never writes (FOREIGN_PLANNING_MARKERS in
  * constants.cjs, sourced from gsd-core's docs/USER-GUIDE.md, read 2026-09-10).
  *
- * Rule: foreign when any marker FILE exists, or at least two marker DIRECTORIES exist,
- * or config.json carries any of the tool's flat dotted keys (PAN nests `workflow: {}`;
- * gsd-core writes `"workflow.discuss_mode"`). An unreadable config.json is not evidence.
- * Returns { tool, key, evidence[] } or null. Never throws.
+ * Rule: foreign when any marker FILE exists (a name, or a name pattern), or at least
+ * two marker DIRECTORIES exist, or config.json carries any of the tool's flat dotted
+ * keys (PAN nests `workflow: {}`; gsd-core writes `"workflow.discuss_mode"`). A pattern
+ * directory holding the file it `requires` counts as file-strength evidence; without
+ * that file it is one directory. An unreadable config.json is not evidence.
+ * Returns { tool, key, evidence[], coexists } or null. Never throws. `coexists` marks
+ * a tool that SHARES the tree (planning-with-files): callers keep working and report
+ * it, instead of refusing the tree as another tool's.
  */
 const fs = require('fs');
 const path = require('path');
@@ -35,13 +39,27 @@ function detectForeignPlanningTree(planningDir) {
   }
   for (const [key, m] of Object.entries(FOREIGN_PLANNING_MARKERS)) {
     const fileHits = m.files.filter(f => names.has(f));
+    for (const re of m.filePatterns || []) {
+      for (const e of entries) if (!e.isDirectory() && re.test(e.name)) fileHits.push(e.name);
+    }
     const dirHits = m.dirs.filter(d => dirs.has(d));
+    const strongDirs = [];
+    for (const { re, requires } of m.dirPatterns || []) {
+      for (const d of [...dirs].sort()) {
+        if (!re.test(d)) continue;
+        let holds = false;
+        try { holds = fs.existsSync(path.join(planningDir, d, requires)); } catch { holds = false; }
+        if (holds) strongDirs.push(d);
+        else dirHits.push(d);
+      }
+    }
     const configHits = cfg ? m.configKeys.filter(k => Object.prototype.hasOwnProperty.call(cfg, k)) : [];
-    if (fileHits.length > 0 || dirHits.length >= 2 || configHits.length > 0) {
+    if (fileHits.length > 0 || strongDirs.length > 0 || dirHits.length >= 2 || configHits.length > 0) {
       return {
         tool: m.tool,
         key,
-        evidence: [...fileHits, ...dirHits.map(d => d + '/'), ...configHits.map(k => 'config.json:' + k)],
+        evidence: [...fileHits, ...strongDirs.map(d => d + '/'), ...dirHits.map(d => d + '/'), ...configHits.map(k => 'config.json:' + k)],
+        coexists: m.coexists === true,
       };
     }
   }

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

@@ -534,7 +534,15 @@ function scanOneRoot(cwd, root, opts) {
     // rename would rename its state files. One warn finding, nothing fixable, and
     // none of the per-tree checks run on it. Reality check R15.
     const foreign = detectForeignPlanningTree(planningPath(cwd));
-    if (foreign) {
+    // A tool that SHARES the tree (planning-with-files) owns only its own names;
+    // PAN's checks still apply to PAN's files. One info finding says so.
+    const shared = foreign && foreign.coexists
+      ? mkFinding('shared-planning-tree', 'info', planningRel(),
+        `${foreign.tool} also writes into this planning tree (${foreign.evidence.join(', ')}) — PAN leaves its files alone and checks only its own`,
+        null)
+      : null;
+    if (shared) shared.track = root.name;
+    if (foreign && !foreign.coexists) {
       const f = mkFinding('foreign-planning-tree', 'warn', planningRel(),
         `planning tree belongs to ${foreign.tool} (${foreign.evidence.join(', ')}) — PAN will not rename or repair its files; run PAN with --planning-dir to give it a tree of its own (ADR-0043)`,
         null);
@@ -543,6 +551,7 @@ function scanOneRoot(cwd, root, opts) {
     }
     const fragment = checkPlanningFragment(cwd);
     const findings = [
+      ...(shared ? [shared] : []),
       ...fragment.findings,
       ...checkLegacyUppercase(cwd).findings,
       ...checkTmpOrphans(cwd).findings,
@@ -621,7 +630,8 @@ function applyFix(cwd, finding) {
         // Defence in depth for R15: the scan never emits this fix for a foreign tree,
         // but a stale findings list or a hand-built one must not rename another
         // tool's files either.
-        if (detectForeignPlanningTree(path.dirname(abs))) {
+        const owner = detectForeignPlanningTree(path.dirname(abs));
+        if (owner && !owner.coexists) {
           return { applied: false, detail: 'refused: this planning tree belongs to another tool (see the foreign-planning-tree finding)' };
         }
         // Two-step rename: Windows treats case-only renames inconsistently