pan-wizard 3.36.0 → 3.37.0

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

@@ -0,0 +1,356 @@
+'use strict';
+/**
+ * Right-sized ceremony: decide in code how much process a piece of work gets.
+ *
+ * Measured 2026-10-24 (docs/specs/right-sized-ceremony.md): on precisely specified work
+ * PAN spent about 70% of its cost and time on planning ceremony (research, a planner and
+ * a plan-checker revising each other three or four times), all of it on the launch model,
+ * against a bare host that finished the same tasks correctly for about a thirtieth of the
+ * cost. A small, well-specified piece of work does not need that: the spec is the plan.
+ *
+ *   lean  the executor works from the spec; the engine's deterministic plan checks and
+ *         test gate check it; an LLM checker or verifier runs only when those cannot decide
+ *   full  today's path: research, planner, plan-checker loop, verifier, reviewers
+ *
+ * The mode: `full` everywhere when the profile is `quality` (the old behaviour, chosen at
+ * new-project or settings), when `workflow.ceremony` is `full`, or when a run passes
+ * `--quality`; otherwise `auto`, which sizes each piece of work. Pure apart from reads.
+ */
+
+const fs = require('fs');
+const { loadConfig } = require('./core.cjs');
+const { roadmapRequirementIds } = require('./roadmap.cjs');
+const { ROADMAP_FILE, REQUIREMENTS_FILE } = require('./constants.cjs');
+const { planningPath } = require('./utils.cjs');
+
+const DEFAULT_LEAN_MAX_REQUIREMENTS = 5;
+/** A lean phase holds at most this many times lean_max_requirements; above it the planner runs. */
+const LEAN_CEILING_FACTOR = 3;
+const isValidationRule = (c) => require('./verify-plan-set.cjs').isValidationRule(c);
+
+// loadConfig flattens the workflow section away; the ceremony keys are read from the raw file.
+function ceremonyConfig(cwd) {
+  const workflow = require('./test-gate.cjs').rawConfig(cwd).workflow || {};
+  return { ...loadConfig(cwd), workflow };
+}
+
+/** 'full' or 'auto' for this project and run. `config`: ceremonyConfig's. */
+function ceremonyMode(config, opts = {}) {
+  if (opts.quality) return { mode: 'full', why: '--quality was passed for this run' };
+  const wf = (config && config.workflow) || {};
+  if (wf.ceremony === 'full') return { mode: 'full', why: 'workflow.ceremony is full' };
+  if (config && config.model_profile === 'quality') return { mode: 'full', why: 'the quality profile keeps the full ceremony' };
+  return { mode: 'auto', why: null };
+}
+
+const words = (t) => String(t || '').trim().split(/\s+/).filter(Boolean).length;
+// A concrete artifact: a backticked token, a file with an extension, or a call `name(`.
+const ARTIFACT = /`[^`\n]+`|\b[\w./-]+\.(?:c?js|mjs|tsx?|jsx|py|json|md|go|rs|java|rb|cs|php|sh|ya?ml|toml|sql|html|css)\b|\b[a-zA-Z_][\w]*\([^)\n]*\)/;
+
+/** Whether a requirement says precisely what to build. Pure. */
+function requirementSpecified(req) {
+  if (req && Array.isArray(req.criteria) && req.criteria.length) return true;
+  const t = String((req && req.text) || '');
+  return ARTIFACT.test(t) && words(t) >= 12;
+}
+
+/** Whether a quick task's description says precisely what to build. Pure. */
+function taskSpecified(text) {
+  const t = String(text || '');
+  const reasons = [];
+  if (!ARTIFACT.test(t)) reasons.push('names no file, function or other concrete artifact');
+  if (words(t) < 15) reasons.push('is too short to specify the work (under 15 words)');
+  return { specified: reasons.length === 0, reasons };
+}
+
+/** The ceremony for a quick task. */
+function sizeTask(cwd, text, opts = {}) {
+  const config = ceremonyConfig(cwd);
+  const m = ceremonyMode(config, opts);
+  if (m.mode === 'full') return { path: 'full', mode: m.mode, reasons: [m.why] };
+  if (opts.full) return { path: 'full', mode: m.mode, reasons: ['--full was passed'] };
+  const s = taskSpecified(text);
+  return s.specified
+    ? { path: 'lean', mode: m.mode, reasons: ['the description names what to build and how to check it'] }
+    : { path: 'full', mode: m.mode, reasons: s.reasons.map((r) => `the description ${r}`) };
+}
+
+/** The ceremony for a roadmap phase. */
+function sizePhase(cwd, phase, opts = {}) {
+  const config = ceremonyConfig(cwd);
+  const m = ceremonyMode(config, opts);
+  const max = Number(((config && config.workflow) || {}).lean_max_requirements) || DEFAULT_LEAN_MAX_REQUIREMENTS;
+  let roadmap = '';
+  let reqText = '';
+  try { roadmap = fs.readFileSync(planningPath(cwd, ROADMAP_FILE), 'utf8'); } catch { /* no roadmap */ }
+  try { reqText = fs.readFileSync(planningPath(cwd, REQUIREMENTS_FILE), 'utf8'); } catch { /* no requirements */ }
+  const ids = roadmapRequirementIds(roadmap, String(phase));
+  const all = require('./requirements-lint.cjs').parseRequirements(reqText);
+  const byId = new Map(all.map((r) => [String(r.id).toUpperCase(), r]));
+  const reqs = ids.map((id) => byId.get(String(id).toUpperCase()) || { id, text: '', criteria: [] });
+  const unspecified = reqs.filter((r) => !requirementSpecified(r)).map((r) => r.id);
+  const metrics = { requirements: reqs.length, unspecified, lean_max_requirements: max };
+  if (m.mode === 'full') return { phase: String(phase), path: 'full', mode: m.mode, reasons: [m.why], metrics };
+  if (opts.full) return { phase: String(phase), path: 'full', mode: m.mode, reasons: ['--full was passed'], metrics };
+  const reasons = [];
+  if (!reqs.length) reasons.push('the roadmap maps no requirements to this phase, so nothing pins down the work');
+  if (unspecified.length) reasons.push(`not precisely specified: ${unspecified.join(', ')} (no acceptance criterion and no named artifact)`);
+  // One session holds a lean phase, and one session loses the thread on too much work, which
+  // is what PAN exists to prevent. Above the ceiling the planner designs the phase (2026-10-25).
+  if (reqs.length > max * LEAN_CEILING_FACTOR) reasons.push(`${reqs.length} requirements is more than one session should hold (over ${max * LEAN_CEILING_FACTOR}, ${LEAN_CEILING_FACTOR} x workflow.lean_max_requirements); the planner designs it`);
+  return reasons.length
+    ? { phase: String(phase), path: 'full', mode: m.mode, reasons, metrics }
+    : { phase: String(phase), path: 'lean', mode: m.mode, reasons: [`${reqs.length} requirement(s), each naming what to build${reqs.length > max ? `; split into plans of at most ${max} (workflow.lean_max_requirements)` : ''}`], metrics };
+}
+
+/**
+ * The lean path's plan check, in code: the plan set (requirement coverage, waves,
+ * dependencies), every plan's structure, and the plans' own grep gates. When all pass it
+ * records a plan-check verdict from the engine, bound to the plans' hash like the
+ * plan-checker agent's, so exec-phase's plan-check gate holds. When any fails, nothing is
+ * recorded and the workflow falls back to the plan-checker agent.
+ */
+function engineCheckPlans(cwd, phase) {
+  const VPS = require('./verify-plan-set.cjs');
+  const set = VPS.checkPlanSet(cwd, phase);
+  if (set.error) return { ok: false, error: set.error, reason: set.reason };
+  const pf = VPS.phaseFiles(cwd, phase);
+  const { planStructure } = require('./verify.cjs');
+  const path = require('path');
+  const structure = pf.planFiles.map((f) => ({ plan: f, ...planStructure(fs.readFileSync(path.join(pf.dir, f), 'utf8')) }));
+  const gates = require('./plan-lint.cjs').checkGates(cwd, phase);
+  const errors = [
+    ...(set.errors || []).map((e) => (typeof e === 'string' ? e : e.message || e.code || JSON.stringify(e))),
+    ...structure.flatMap((s) => s.errors.map((e) => `${s.plan}: ${e}`)),
+    ...((gates && gates.errors) || []).map((e) => (typeof e === 'string' ? e : `${e.plan || ''} ${e.code || ''} ${e.command || ''}`.trim())),
+  ];
+  return { ok: errors.length === 0, errors, plans: pf.planFiles.length };
+}
+
+/** Record the engine's passing plan check as the phase's plan-check verdict. */
+function recordEngineCheck(cwd, phase, result) {
+  const F = require('./findings.cjs');
+  const block = '```pan-verdict\n' + JSON.stringify({ contract: '1.0', agent: 'pan-plan-checker', phase: String(phase), outcome: 'pass', verdict: 'PASSED', findings: [] }) + '\n```\n';
+  // The plans' hash makes each checked plan set its own record: an identical text is a
+  // duplicate verdict, so a re-check after a revision would never be recorded.
+  const sha = require('./verify-plan-set.cjs').plansShaFor(cwd, phase);
+  const text = `Plan check by the engine (lean path): plan set, plan structure and grep gates all pass for ${result.plans} plan(s) (plans ${sha}).\n\n${block}`;
+  return F.recordVerdict(cwd, { phase: String(phase), agent: 'pan-plan-checker', text, source: 'engine:lean-plan-check' });
+}
+
+/**
+ * The one-task plan for a lean quick task, written by the engine instead of a planner
+ * session: the description is the plan. Files are the ones the description names; the
+ * verify command is the project's test command. Pure apart from the test-command read.
+ */
+function leanQuickPlan(cwd, description, num) {
+  const desc = String(description || '').trim();
+  const files = [...new Set((desc.match(/\b[\w./-]+\.(?:c?js|mjs|tsx?|jsx|py|json|md|go|rs|java|rb|cs|php|sh|ya?ml|toml|sql|html|css)\b/g) || []))].filter((f) => !/^\d/.test(f));
+  const test = require('./test-gate.cjs').detectTestCommand(cwd);
+  const verify = (test && test.command) || 'the project\'s tests';
+  const esc = (t) => t.replace(/</g, '&lt;');
+  return [
+    '---', 'phase: quick', `plan: ${String(num || 1).padStart(2, '0')}`, 'type: execute', 'wave: 1', 'depends_on: []',
+    `files_modified: [${files.join(', ')}]`, 'autonomous: true', 'tier: micro', 'must_haves:', '  truths:', `    - ${JSON.stringify(desc.slice(0, 300))}`,
+    '---', '', '<objective>', esc(desc), '', 'Written by the engine (lean path): the task description is precise enough to be the plan.', '</objective>', '',
+    '<tasks>', '', '<task type="auto">', `  <name>${esc(desc.split(/\.\s|\n/)[0].slice(0, 80))}</name>`, `  <files>${files.join(', ') || 'the files the description names'}</files>`,
+    `  <action>Do exactly what the objective says, with tests for each rule it states. The objective is the specification: do not widen it.</action>`,
+    `  <verify>${verify}</verify>`, '  <done>Every rule in the objective holds and is covered by a test; the tests pass.</done>', '</task>', '', '</tasks>', '',
+  ].join('\n');
+}
+
+const FILE_RE = /\b[\w./-]+\.(?:c?js|mjs|tsx?|jsx|py|json|md|go|rs|java|rb|cs|php|sh|ya?ml|toml|sql|html|css)\b/g;
+
+/**
+ * Write a lean phase's plans from its requirements (autodev step 2): one task per
+ * requirement, at most lean_max_requirements tasks a plan, each task's action the requirement's own text. The requirements already say
+ * what to build, so a planner session would only restate them. Refuses a phase that is not
+ * lean, or that already has plans. Creates the phase directory when it is missing.
+ * @returns {{written, path, plan_dir, requirements}|{error, reason}}
+ */
+function writeLeanPhasePlan(cwd, phase, opts = {}) {
+  const path = require('path');
+  const C = require('./core.cjs');
+  const size = sizePhase(cwd, phase, opts);
+  if (size.path !== 'lean') return { error: 'not_lean', reason: size.reasons.join('; ') };
+  const rp = C.getRoadmapPhaseInternal(cwd, String(phase));
+  if (!rp || !rp.found) return { error: 'phase_not_found', reason: `phase ${phase} is not in roadmap.md` };
+  const padded = C.normalizePhaseName(String(phase));
+  let info = C.findPhaseInternal(cwd, String(phase));
+  let dir;
+  let createdDir = false;
+  if (info && info.found) dir = path.join(cwd, info.directory);
+  else {
+    createdDir = true;
+    dir = path.join(planningPath(cwd, 'phases'), `${padded}-${C.generateSlugInternal(rp.phase_name || 'phase')}`);
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  if (fs.readdirSync(dir).some((f) => /-plan\.md$/i.test(f))) return { error: 'has_plans', reason: `phase ${phase} already has plans` };
+  let reqText = '';
+  try { reqText = fs.readFileSync(planningPath(cwd, REQUIREMENTS_FILE), 'utf8'); } catch { /* sized lean, so present */ }
+  const all = require('./requirements-lint.cjs').parseRequirements(reqText);
+  const ids = roadmapRequirementIds(fs.readFileSync(planningPath(cwd, ROADMAP_FILE), 'utf8'), String(phase));
+  const reqs = ids.map((id) => all.find((r) => String(r.id).toUpperCase() === String(id).toUpperCase()) || { id, text: '', criteria: [] });
+  const one = (t) => String(t || '').replace(/\s+/g, ' ').trim().replace(/^[—–:-]+\s*/, '');
+  const filesOf = (t) => [...new Set((String(t).match(FILE_RE) || []).filter((f) => !/^\d/.test(f)))];
+  const files = [...new Set(reqs.flatMap((r) => filesOf(r.text)))];
+  // A requirement that changes behaviour earlier phases built (a migration, a new format, a
+  // rename) supersedes the tests that pin the old behaviour. Declare them, so the executor
+  // updates their expectations with a recorded deviation instead of stopping on a "spec
+  // conflict" (2026-10-24: autodev --quality halted at a format-change phase on its own
+  // earlier tests).
+  const changing = reqs.filter((r) => CHANGE_RE.test(String(r.text || '')));
+  // A changing requirement often names the function that holds the old behaviour (`openLedger`)
+  // and not its file, so its tests are looked for there too (2026-10-25: a live phase 5 stopped
+  // on tests/ledger.test.js, which no requirement's named file reached).
+  const superseded = changing.length ? testsCovering(cwd, [...new Set([...files, ...definingFiles(cwd, changing.flatMap((r) => identifiersOf(r.text)))])]) : [];
+  const declared = [...new Set([...files, ...superseded])];
+  const test = require('./test-gate.cjs').detectTestCommand(cwd);
+  const verify = (test && test.command) || 'the project\'s tests';
+  const head = C.execGit(cwd, ['rev-parse', 'HEAD']);
+  const slug = path.basename(dir).replace(/^\d+(?:\.\d+)*-/, '');
+  const esc = (t) => t.replace(/</g, '&lt;');
+  const tasks = reqs.map((r) => {
+    const own = filesOf(r.text);
+    const criteria = (r.criteria || []).map((c) => `\n    - ${esc(one(c))}`).join('');
+    const supersedes = superseded.length && changing.includes(r)
+      ? ` This requirement changes behaviour earlier phases built: where ${superseded.join(', ')} assert the old behaviour, update those expectations to what ${r.id} requires and record each change as a deviation in the summary. Do not delete, skip or weaken a test.`
+      : '';
+    const taskFiles = [...new Set([...(own.length ? own : files), ...(supersedes ? superseded : [])])];
+    // A requirement that states a validation rule (IF ... THEN, a claim over every input, a
+    // "never") needs a property-test task, as the plan check requires (V10): one example
+    // test cannot show a rule over many inputs (2026-10-25: the engine's plan failed its own
+    // check here and the phase never ran).
+    const rule = (r.criteria || []).some(isValidationRule);
+    const property = rule ? ' Add a property-based test that checks the rule over generated inputs, with the project\'s own property helper or a seeded loop and no new dependency.' : '';
+    const text = [rule ? '<task type="auto" property="true">' : '<task type="auto">', `  <name>${r.id}: ${esc(one(r.text).slice(0, 70))}</name>`, `  <files>${taskFiles.join(', ') || 'the files the requirement names'}</files>`,
+      `  <action>Implement ${r.id} exactly as requirements.md states it, with a test for each rule in it: ${esc(one(r.text))}${criteria}${supersedes}${property}</action>`,
+      `  <verify>${verify}</verify>`, `  <done>${r.id} holds and a test covers each rule in it; the tests pass.</done>`, '</task>'].join('\n');
+    return { r, text, files: taskFiles, supersedes: Boolean(supersedes) };
+  });
+  // A large phase of precise requirements is split into plans of at most
+  // lean_max_requirements tasks, each in its own wave after the one before, so the one
+  // execute session takes them in order and commits a summary between them (2026-10-25:
+  // the brief's 9- and 13-requirement phases went to the full ceremony on their size alone,
+  // a planner and a plan-checker twice each, about $3 and 13 minutes a phase).
+  const per = Math.max(1, Number(size.metrics.lean_max_requirements) || DEFAULT_LEAN_MAX_REQUIREMENTS);
+  const chunks = [];
+  for (let i = 0; i < tasks.length; i += per) chunks.push(tasks.slice(i, i + per));
+  const written = [];
+  chunks.forEach((chunk, i) => {
+    const nn = String(i + 1).padStart(2, '0');
+    const ids = chunk.map((t) => t.r.id);
+    const own = [...new Set(chunk.flatMap((t) => t.files))];
+    const sup = chunk.some((t) => t.supersedes);
+    const text = [
+      '---', `phase: ${padded}-${slug}`, `plan: ${nn}`, 'type: execute', `wave: ${i + 1}`, `depends_on: [${i ? `${padded}-${String(i).padStart(2, '0')}` : ''}]`, `files_modified: [${(own.length ? own : declared).join(', ')}]`, 'autonomous: true',
+      `requirements: [${ids.join(', ')}]`, ...(head.exitCode === 0 ? [`planned_commit: ${head.stdout.trim()}`] : []),
+      ...(sup ? [`supersedes_tests: [${superseded.join(', ')}]`, `supersedes_requirements: [${chunk.filter((t) => t.supersedes).map((t) => t.r.id).join(', ')}]`] : []),
+      'must_haves:', '  truths:', ...chunk.map((t) => `    - ${JSON.stringify(`${t.r.id}: ${one(t.r.text).slice(0, 240)}`)}`),
+      '---', '', '<objective>', esc(one(rp.goal || '')), '', `Written by the engine (lean path): the phase's requirements say precisely what to build, so each is one task${chunks.length > 1 ? `; this is plan ${i + 1} of ${chunks.length} (${ids.join(', ')})` : ''}. The requirements are the specification: do not widen them.`, '</objective>', '',
+      '<tasks>', '', chunk.map((t) => t.text).join('\n\n'), '', '</tasks>', '',
+    ].join('\n');
+    const file = path.join(dir, `${padded}-${nn}-plan.md`);
+    fs.writeFileSync(file, text);
+    written.push(file);
+  });
+  const rels = written.map((f) => C.toPosix(path.relative(cwd, f)));
+  return { written: true, path: rels[0], paths: rels, abs: written[0], abs_all: written, created_dir: createdDir ? dir : null, plan_dir: C.toPosix(path.relative(cwd, dir)), requirements: reqs.map((r) => r.id), ...(superseded.length ? { supersedes_tests: superseded } : {}) };
+}
+
+// Wording that marks a requirement as changing behaviour already built.
+const CHANGE_RE = /\b(migrat\w*|format change|new format|version \d+|v\d+ format|replac\w*|instead of|no longer|renam\w*|deprecat\w*|breaking)\b/i;
+
+/**
+ * The existing test files that exercise any of `files`: a test file under the project
+ * (outside node_modules, .git and the planning tree) whose text names one of the files'
+ * module names. Pure apart from reads; sorted.
+ */
+/** The code identifiers a requirement names in backticks (`openLedger`, `importCSV`). */
+function identifiersOf(text) {
+  return [...new Set([...String(text || '').matchAll(/`([A-Za-z_$][\w$]{3,})`/g)].map((m) => m[1]))];
+}
+
+/** The project's source files (not tests) that define any of `names` as a function, method or binding. */
+function definingFiles(cwd, names) {
+  const path = require('path');
+  if (!names.length) return [];
+  const esc = (n) => n.replace(/[$]/g, '\\$&');
+  const def = new RegExp(`(?:function\\s*\\*?\\s*|def\\s+|func\\s+|fn\\s+|(?:const|let|var)\\s+)(?:${names.map(esc).join('|')})\\b|\\b(?:${names.map(esc).join('|')})\\s*(?:[:=]\\s*(?:async\\s*)?(?:function|\\()|\\([^)]*\\)\\s*\\{)`);
+  const isTest = (rel) => /(^|\/)(tests?|__tests__|spec)\//.test(rel) || /\.(test|spec)\.[^.]+$/.test(rel);
+  const out = [];
+  const walk = (dir, depth) => {
+    if (depth > 6) return;
+    let entries = [];
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (['node_modules', '.git', '.planning', '.claude', '.codex', '.gemini', '.opencode', '.github', '.agents', 'dist', 'coverage'].includes(e.name)) continue;
+      const abs = path.join(dir, e.name);
+      if (e.isDirectory()) { walk(abs, depth + 1); continue; }
+      const rel = path.relative(cwd, abs).split(path.sep).join('/');
+      if (isTest(rel) || !/\.(c?js|mjs|tsx?|jsx|py|go|rs|java|rb|cs)$/.test(rel)) continue;
+      let text = '';
+      try { text = fs.readFileSync(abs, 'utf8'); } catch { continue; }
+      if (def.test(text)) out.push(rel);
+    }
+  };
+  walk(cwd, 0);
+  return out.sort();
+}
+
+function testsCovering(cwd, files) {
+  const path = require('path');
+  const names = [...new Set(files.map((f) => path.basename(f).replace(/\.[^.]+$/, '')).filter((n) => n.length > 2))];
+  if (!names.length) return [];
+  const isTest = (rel) => /(^|\/)(tests?|__tests__|spec)\//.test(rel) || /\.(test|spec)\.[^.]+$/.test(rel);
+  const out = [];
+  const walk = (dir, depth) => {
+    if (depth > 6) return;
+    let entries = [];
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (['node_modules', '.git', '.planning', '.claude', '.codex', '.gemini', '.opencode', '.github', '.agents', 'dist', 'coverage'].includes(e.name)) continue;
+      const abs = path.join(dir, e.name);
+      if (e.isDirectory()) { walk(abs, depth + 1); continue; }
+      const rel = path.relative(cwd, abs).split(path.sep).join('/');
+      if (!isTest(rel) || !/\.(c?js|mjs|tsx?|jsx|py|go|rs|java|rb|cs)$/.test(rel) || files.includes(rel)) continue;
+      let text = '';
+      try { text = fs.readFileSync(abs, 'utf8'); } catch { continue; }
+      if (names.some((n) => new RegExp(`\\b${n.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`).test(text))) out.push(rel);
+    }
+  };
+  walk(cwd, 0);
+  return out.sort();
+}
+
+/**
+ * The lean phase's whole planning step, in code: write the plan, check it, record the plan
+ * check, and commit the plan when commit_docs is on. No model session.
+ */
+function planLeanPhase(cwd, phase, opts = {}) {
+  const w = writeLeanPhasePlan(cwd, phase, opts);
+  if (w.error) return w;
+  const check = engineCheckPlans(cwd, phase);
+  if (!check.ok) {
+    // Decline writes nothing: a failed plan left on disk was picked up by the next session.
+    for (const f of w.abs_all) { try { fs.unlinkSync(f); } catch { /* already gone */ } }
+    if (w.created_dir) { try { fs.rmdirSync(w.created_dir); } catch { /* not empty */ } }
+    return { phase: String(phase), ok: false, error: 'check_failed', errors: check.errors };
+  }
+  const rec = recordEngineCheck(cwd, phase, check);
+  if (rec.error) return { ...w, ok: false, errors: [rec.reason || rec.error] };
+  const config = loadConfig(cwd);
+  let commit = null;
+  if (config.commit_docs !== false) {
+    const C = require('./core.cjs');
+    const add = C.execGit(cwd, ['add', '--', ...w.paths]);
+    const msg = `docs(${C.normalizePhaseName(String(phase))}): lean plan written by the engine`;
+    const c = add.exitCode === 0 ? C.execGit(cwd, ['commit', '-q', '-m', msg, '--', ...w.paths]) : add;
+    commit = c.exitCode === 0 ? (C.execGit(cwd, ['rev-parse', '--short', 'HEAD']).stdout || '').trim() : null;
+    // The plan stands without its commit (exec-phase commits as it goes); say why it is missing.
+    if (!commit) return { ...w, ok: true, plan_check: 'recorded', commit: null, commit_error: String(c.stderr || c.stdout || 'git commit failed').trim().slice(0, 300) };
+  }
+  return { ...w, ok: true, plan_check: 'recorded', commit };
+}
+
+module.exports = { LEAN_CEILING_FACTOR, writeLeanPhasePlan, planLeanPhase, leanQuickPlan, ceremonyMode, requirementSpecified, taskSpecified, sizeTask, sizePhase, engineCheckPlans, recordEngineCheck, DEFAULT_LEAN_MAX_REQUIREMENTS };

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

@@ -73,7 +73,7 @@ const SQUADS = Object.freeze({
     summary: 'Designs the system before code — contract-first.',
     agents: Object.freeze([
       'pan-roadmapper', 'pan-planner', 'pan-designer', 'pan-plan-checker', 'pan-design-checker',
-      'pan-project-researcher', 'pan-phase-researcher', 'pan-research-synthesizer',
+      'pan-project-researcher', 'pan-phase-researcher',
     ]),
   }),
   build: Object.freeze({

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

@@ -0,0 +1,247 @@
+'use strict';
+/**
+ * The verbs that write state.md wholesale or by section (program A7b).
+ *
+ * Agents used to Write or Edit state.md themselves: the roadmapper and new-project
+ * composed it, milestone-new reset it, add-phase and insert-phase appended to it, quick
+ * added rows, transition batched five edits into one. Every write now goes through
+ * pan-tools and writeStateMd, which keeps the frontmatter in sync and writes atomically
+ * under the lock, so the pre-tool guard's `enforce` can deny a direct write.
+ *
+ *   state init         a fresh state.md from the template's sections
+ *   state section      append to or set one section, creating it when missing
+ *   state quick-task   one row in the Quick Tasks Completed table
+ *   state apply        bold fields and sections in one write (transition's batch)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { output, escapeRegex } = require('./core.cjs');
+const { planningPath } = require('./utils.cjs');
+const { writeStateMd } = require('./state.cjs');
+
+const statePathOf = (cwd) => planningPath(cwd, 'state.md');
+const today = () => new Date().toISOString().slice(0, 10);
+
+function readBody(cwd) {
+  try { return fs.readFileSync(statePathOf(cwd), 'utf8').replace(/\r\n/g, '\n'); } catch { return null; }
+}
+
+/** The body without its frontmatter (writeStateMd rebuilds the frontmatter). */
+function stripFrontmatter(text) {
+  return text.replace(/^---\n[\s\S]*?\n---\n+/, '');
+}
+
+/** [start, end) of a section's body: the lines after its heading up to the next heading of its level or higher. */
+function findSection(text, name) {
+  const lines = text.split('\n');
+  let offset = 0;
+  let start = -1;
+  let level = 0;
+  let bodyStart = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^(#{2,3}) (.*?)[ \t]*$/);
+    if (start < 0 && m && m[2] === name) { start = offset; level = m[1].length; bodyStart = offset + lines[i].length + 1; }
+    else if (start >= 0) {
+      const h = lines[i].match(/^(#+) /);
+      if (h && h[1].length <= level) return { level, headingStart: start, bodyStart, bodyEnd: offset };
+    }
+    offset += lines[i].length + 1;
+  }
+  return start < 0 ? null : { level, headingStart: start, bodyStart: Math.min(bodyStart, text.length), bodyEnd: text.length };
+}
+
+const PLACEHOLDER_RE = /^(None yet\.|None\.?|\[.*\])\s*$/;
+
+function editSection(text, name, op, under) {
+  under = under || 'Accumulated Context';
+  // The CLI's absent flags arrive as null.
+  op = { append: op.append == null ? undefined : op.append, set: op.set == null ? undefined : op.set };
+  let s = findSection(text, name);
+  if (!s) {
+    // Create it as an ### section at the end of `under`, else at the end of the file.
+    const parent = findSection(text, under);
+    const insertAt = parent ? parent.bodyEnd : text.length;
+    const before = text.slice(0, insertAt).replace(/\n*$/, '\n\n');
+    text = `${before}### ${name}\n\n${text.slice(insertAt).replace(/^\n*/, text.slice(insertAt) ? '\n' : '')}`;
+    s = findSection(text, name);
+  }
+  const body = text.slice(s.bodyStart, s.bodyEnd);
+  let lines = body.replace(/^\n+/, '').replace(/\n+$/, '').split('\n').filter((l, i, all) => !(all.length === 1 && l === ''));
+  if (op.set !== undefined) {
+    lines = String(op.set).split('\n');
+  } else {
+    const keep = lines.filter((l) => !PLACEHOLDER_RE.test(l.trim()));
+    // Leading prose of the template ("[From .planning/todos/...]") is a placeholder too.
+    lines = keep.concat([].concat(op.append || []));
+  }
+  const tail = s.bodyEnd < text.length ? '\n' : '';
+  return `${text.slice(0, s.bodyStart)}\n${lines.join('\n')}\n${tail}${text.slice(s.bodyEnd)}`;
+}
+
+function setField(text, field, value) {
+  const re = new RegExp(`(\\*\\*${escapeRegex(field)}:\\*\\*[ \\t]*)(.*)`, 'i');
+  if (!re.test(text)) return null;
+  return text.replace(re, (_m, prefix) => `${prefix}${value}`);
+}
+
+function renderInit(o) {
+  const v = (x, d) => (x === undefined || x === null || x === '' ? d : x);
+  return `# Project State
+
+## Project Reference
+
+See: .planning/project.md (updated ${today()})
+
+**Core value:** ${v(o.coreValue, '[One-liner from project.md Core Value section]')}
+**Current focus:** ${v(o.focus, v(o.phaseName, 'Not started'))}
+
+## Current Position
+
+**Current Phase:** ${v(o.phase, '1')}
+**Current Phase Name:** ${v(o.phaseName, v(o.focus, '—'))}
+**Current Plan:** —
+**Total Plans in Phase:** 0
+**Total Phases:** ${v(o.totalPhases, '0')}
+**Status:** ${v(o.status, 'Ready to plan')}
+**Last Activity:** ${today()}
+**Last Activity Description:** ${v(o.activity, 'State initialized')}
+**Progress:** [░░░░░░░░░░] 0%
+
+## Performance Metrics
+
+**Velocity:**
+- Total plans completed: 0
+- Average duration: —
+- Total execution time: 0.0 hours
+
+**By Plan:** (one row per plan, written by \`state record-metric\`)
+
+| Plan | Duration | Tasks | Files |
+|------|----------|-------|-------|
+| - | - | - | - |
+
+*Updated after each plan completion*
+
+## Accumulated Context
+
+### Decisions
+
+Decisions are logged in project.md Key Decisions table.
+
+None yet.
+
+### Pending Todos
+
+None yet.
+
+### Blockers/Concerns
+
+None yet.
+
+## Session Continuity
+
+**Last session:** ${new Date().toISOString().slice(0, 16).replace('T', ' ')}
+**Stopped At:** ${v(o.activity, 'State initialized')}
+**Resume File:** None
+`;
+}
+
+function stateInit(cwd, o = {}) {
+  const p = statePathOf(cwd);
+  const existing = readBody(cwd);
+  if (existing !== null && !o.force) return { error: 'state_exists', reason: 'state.md exists; pass --force to replace it (a backup is kept)' };
+  let body = renderInit(o);
+  let backup = null;
+  if (existing !== null) {
+    if (o.keepContext) {
+      const src = stripFrontmatter(existing);
+      const old = findSection(src, 'Accumulated Context');
+      const neu = findSection(body, 'Accumulated Context');
+      if (old && neu) body = body.slice(0, neu.bodyStart) + src.slice(old.bodyStart, old.bodyEnd).replace(/\n*$/, '\n\n') + body.slice(neu.bodyEnd);
+    }
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+    backup = `${p}.bak-${stamp}`;
+    fs.copyFileSync(p, backup);
+  }
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  writeStateMd(p, body, cwd);
+  return { written: true, path: path.relative(cwd, p).replace(/\\/g, '/'), backup: backup && path.relative(cwd, backup).replace(/\\/g, '/'), kept_context: !!(o.keepContext && existing) };
+}
+
+function withState(cwd, fn) {
+  const text = readBody(cwd);
+  if (text === null) return { error: 'state_missing', reason: 'state.md not found; run `pan-tools state init` first' };
+  const r = fn(stripFrontmatter(text));
+  if (r.error) return r;
+  writeStateMd(statePathOf(cwd), r.text, cwd);
+  const { text: _t, ...rest } = r;
+  return { written: true, ...rest };
+}
+
+function stateSection(cwd, name, op) {
+  if (!name) return { error: 'section_required', reason: 'Usage: state section <name> (--append <line> | --set <text>) [--under <section>]' };
+  if (op.append == null && op.set == null) return { error: 'op_required', reason: 'pass --append <line> or --set <text>' };
+  return withState(cwd, (t) => ({ text: editSection(t, name, op, op.under), section: name }));
+}
+
+function stateQuickTask(cwd, o) {
+  if (!o.description) return { error: 'description_required', reason: 'Usage: state quick-task --description D --commit SHA --directory DIR [--status S] [--date YYYY-MM-DD]' };
+  return withState(cwd, (t) => {
+    const withStatus = o.status != null;
+    let s = findSection(t, 'Quick Tasks Completed');
+    if (!s) {
+      const header = withStatus
+        ? '| # | Description | Date | Commit | Status | Directory |\n|---|-------------|------|--------|--------|-----------|'
+        : '| # | Description | Date | Commit | Directory |\n|---|-------------|------|--------|-----------|';
+      const anchor = findSection(t, 'Blockers/Concerns');
+      const at = anchor ? anchor.bodyEnd : t.length;
+      t = `${t.slice(0, at).replace(/\n*$/, '\n\n')}### Quick Tasks Completed\n\n${header}\n${t.slice(at) ? '\n' + t.slice(at).replace(/^\n*/, '') : ''}`;
+      s = findSection(t, 'Quick Tasks Completed');
+    }
+    const body = t.slice(s.bodyStart, s.bodyEnd);
+    const rows = body.split('\n').filter((l) => /^\|\s*\d+\s*\|/.test(l));
+    const hasStatusCol = /\|\s*Status\s*\|/.test(body);
+    const n = rows.length + 1;
+    // Escape a pipe once: init's description_cell arrives already escaped. Line breaks fold.
+    const cell = (x) => String(x == null ? '' : x).replace(/\r?\n+/g, ' ').replace(/(^|[^\\])\|/g, '$1\\|').replace(/(^|[^\\])\|/g, '$1\\|');
+    const cols = [n, cell(o.description), o.date || today(), cell(o.commit || '')];
+    if (hasStatusCol) cols.push(cell(o.status || ''));
+    cols.push(cell(o.directory || ''));
+    const row = `| ${cols.join(' | ')} |`;
+    const lines = body.replace(/\n+$/, '').split('\n');
+    const lastTable = lines.map((l, i) => (l.startsWith('|') ? i : -1)).filter((i) => i >= 0).pop();
+    lines.splice(lastTable + 1, 0, row);
+    const tail = s.bodyEnd < t.length ? '\n\n' : '\n';
+    return { text: `${t.slice(0, s.bodyStart)}${lines.join('\n')}${tail}${t.slice(s.bodyEnd).replace(/^\n*/, '')}`, row: n };
+  });
+}
+
+function stateApply(cwd, batch) {
+  if (!batch || typeof batch !== 'object') return { error: 'invalid_batch', reason: 'pass --json \'{"fields": {...}, "sections": {"Name": {"append": [...]} | {"set": "..."}}}\'' };
+  return withState(cwd, (t) => {
+    const updated = [];
+    const failed = [];
+    for (const [field, value] of Object.entries(batch.fields || {})) {
+      const next = setField(t, field, value);
+      if (next === null) failed.push(field); else { t = next; updated.push(field); }
+    }
+    for (const [name, op] of Object.entries(batch.sections || {})) {
+      t = editSection(t, name, op || {}, op && op.under);
+      updated.push(name);
+    }
+    return { text: t, updated, failed };
+  });
+}
+
+function cmdStateInit(cwd, o, raw) { const r = stateInit(cwd, o); output(r, raw, r.path || r.error); }
+function cmdStateSection(cwd, name, op, raw) { const r = stateSection(cwd, name, op); output(r, raw, r.section || r.error); }
+function cmdStateQuickTask(cwd, o, raw) { const r = stateQuickTask(cwd, o); output(r, raw, r.row ? String(r.row) : r.error); }
+function cmdStateApply(cwd, json, raw) {
+  let batch = null;
+  try { batch = JSON.parse(json); } catch { /* reported below */ }
+  const r = stateApply(cwd, batch);
+  output(r, raw, r.error || String((r.updated || []).length));
+}
+
+module.exports = { stateInit, stateSection, stateQuickTask, stateApply, editSection, findSection, cmdStateInit, cmdStateSection, cmdStateQuickTask, cmdStateApply };