@cspeach/cli 0.8.0 → 0.9.0

package/dist/commands/plan-resume.js

@@ -0,0 +1,308 @@
+// cspeach-cli/src/commands/plan-resume.ts
+//
+// `/abap-plan --resume @<plan-file>` — B3 (2026-06-06).
+//
+// Split around the model turn:
+//
+//   preparePlanResume  (token-free, BEFORE runTurn)
+//     resolve @token → load + validate envelope → compute next eligible
+//     phase → print the tracker board → inline the phase's declared rule
+//     files → return the bounded LLM prompt. Terminal states (plan
+//     complete / everything blocked) print and return null — no model
+//     turn happens at all.
+//
+//   finishPlanResume   (AFTER runTurn)
+//     collect the turn's assistant text (ALL messages — the manifest may
+//     precede a closing ask_question, see turn-assistant-text.ts) →
+//     extract the LAST csforge:plan-manifest block → build the version
+//     N+1 revision (same id, history appended) → save → print the
+//     updated tracker + next-step hint.
+//
+// The save hook inside runTurn is suppressed for resume turns
+// (RunTurnParams.suppressSaveHook) — it would otherwise offer to save a
+// duplicate NEW envelope with a fresh id, breaking the version chain.
+// Resume persistence is unconditional: the envelope is the only state
+// that survives the session, so losing the write-back breaks the plan.
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { readProjectFile } from '../projects/status.js';
+import { resolveAtTokenAsync, formatProjectFileList, ensureWorkspace } from '../projects/workspace.js';
+import { parsePlanContent } from '../projects/plan-schema.js';
+import { statusesFromItems, computeNextPhase, renderPlanTracker, buildPlanRevision, } from '../projects/plan-run.js';
+import { extractPlan } from '../projects/extract-plan.js';
+import { saveProject } from '../projects/save.js';
+import { validateEnvelope } from '../projects/validate.js';
+import { collectTurnAssistantText } from '../agent/turn-assistant-text.js';
+import { getAuthorIdentity } from '../agent/loop.js';
+export async function preparePlanResume(args) {
+    const tokens = args.body
+        .split(/\s+/)
+        .filter((tok) => tok.startsWith('@'))
+        .map((tok) => tok.slice(1))
+        .filter((tok) => tok.length > 0);
+    if (tokens.length === 0) {
+        args.log('Usage: /abap-plan --resume @<plan>.cspeach.json');
+        args.log('Bare names work too — e.g. @hr-extract-plan — resolved from the workspace folder.');
+        return null;
+    }
+    const resolved = await resolveAtTokenAsync(tokens[0], args.cwd);
+    let path;
+    if (resolved.kind === 'path') {
+        path = resolved.path;
+    }
+    else if (resolved.kind === 'notFound') {
+        args.log(`--resume: no file matching '${resolved.token}' in workspace ${resolved.workspace}`);
+        args.log('Run /files to see available .cspeach.json files.');
+        return null;
+    }
+    else {
+        // Version-less resume: a base name / short id matches every version of one
+        // plan family. Resolve to the newest instead of erroring — the user (and
+        // the auto-fire dispatch) should never have to name a version number.
+        const newestOfFamily = pickNewestPlanVersion(resolved.matches.map((m) => m.path));
+        if (newestOfFamily) {
+            args.log(`↪ resolved @${tokens[0]} to the latest version ${basename(newestOfFamily)}`);
+            path = newestOfFamily;
+        }
+        else {
+            args.log(`--resume: '${tokens[0]}' is ambiguous — multiple matches:`);
+            args.log(formatProjectFileList(resolved.matches, ''));
+            args.log('Use a more specific @<fragment> to disambiguate.');
+            return null;
+        }
+    }
+    let envelope;
+    try {
+        envelope = readProjectFile(path);
+    }
+    catch (e) {
+        args.log(`--resume: ${e instanceof Error ? e.message : String(e)}`);
+        return null;
+    }
+    // 2026-06-06 (live-smoke UX): users should never have to remember which
+    // vN file is current — resuming a stale version re-runs already-validated
+    // phases. If a newer version of the SAME envelope (matching id) exists
+    // next to the picked file, silently redirect to it with a note.
+    const newest = findNewestVersion(path, envelope);
+    if (newest) {
+        args.log(`↪ newer version found — resuming ${basename(newest.path)} (you picked ${basename(path)})`);
+        path = newest.path;
+        envelope = newest.envelope;
+    }
+    if (envelope.artefactType !== 'plan') {
+        args.log(`--resume expects a plan envelope; got ${envelope.artefactType}.`);
+        args.log(`For ${envelope.artefactType} files use --status / --from instead.`);
+        return null;
+    }
+    // Defense-in-depth: top-level validation passed in readProjectFile, but
+    // the content payload is only checked by the Zod schema.
+    const pc = parsePlanContent(envelope.content);
+    if (!pc.ok) {
+        args.log('--resume: plan content failed validation — fix the file before resuming:');
+        for (const e of pc.errors)
+            args.log(`  ${e}`);
+        return null;
+    }
+    const content = pc.content;
+    const statuses = statusesFromItems(envelope.interaction.items, content.phases);
+    const next = computeNextPhase(content.phases, statuses);
+    args.log('');
+    args.log(renderPlanTracker({
+        title: envelope.title,
+        version: envelope.version,
+        content,
+        statuses,
+        currentId: next?.id ?? null,
+    }));
+    args.log('');
+    if (!next) {
+        const allValidated = content.phases.every((p) => statuses[p.id] === 'validated');
+        if (allValidated) {
+            args.log('Plan complete — every phase is validated.');
+            args.log('Consider /abap-preflight on the produced transport(s) before release.');
+        }
+        else {
+            const blocked = content.phases.filter((p) => statuses[p.id] === 'blocked').map((p) => p.id);
+            args.log(`No eligible phase. Blocked: ${blocked.join(', ') || '(none)'} — remaining phases wait on them.`);
+            args.log('Unblock (fix + edit the envelope status back to todo) and resume again.');
+        }
+        return null;
+    }
+    // Inline the phase's declared rule files (coarse v1: whole files).
+    // Paths resolve against cwd — dogfood runs sit inside a repo carrying
+    // .claude/rules/. A missing file is noted, not fatal: the skill falls
+    // back to its built-in Forge defaults.
+    const ruleBlocks = [];
+    for (const rel of next.manifest.rules) {
+        try {
+            const text = readFileSync(join(args.cwd, rel), 'utf8');
+            ruleBlocks.push(`<rule file="${rel}">\n${text}\n</rule>`);
+        }
+        catch {
+            ruleBlocks.push(`<rule file="${rel}" missing="true"/>  <!-- not found locally — apply built-in Forge defaults -->`);
+        }
+    }
+    const planState = JSON.stringify({ title: envelope.title, version: envelope.version, statuses, content }, null, 2);
+    const llmPrompt = [
+        `Resume execution of the project plan "${envelope.title}" (envelope v${envelope.version}).`,
+        '',
+        `Execute Mode 2 of the abap-plan skill for phase "${next.id}" ONLY — it is the computed next eligible phase. Do not execute any other phase unless the user explicitly picks "continue" at the phase-end question.`,
+        '',
+        '<plan_state>',
+        planState,
+        '</plan_state>',
+        '',
+        '<phase_rules>',
+        ...ruleBlocks,
+        '</phase_rules>',
+        '',
+        // 2026-06-06 live-smoke lesson #3: the model asked the continuation
+        // question FIRST, then ended the turn on the user's "exit" answer with
+        // a one-line acknowledgment — and the whole phase result was lost. The
+        // ordering must be explicit and the consequence named.
+        'CRITICAL — write-back ordering: emit the COMPLETE updated <!-- csforge:plan-manifest --> block (full phase list, statuses entry for every phase, this phase\'s work filled in — including work.notes with the compact decision register when the phase produced decisions rather than SAP objects) BEFORE the phase-end continuation question. The manifest block is how the result is persisted; a turn that ends without it LOSES the phase. After the user answers "exit", reply with at most one short line — the manifest must already be in the transcript by then.',
+    ].join('\n');
+    return { path, envelope, statuses, nextPhaseId: next.id, llmPrompt };
+}
+/**
+ * Given a set of candidate file paths (e.g. the matches from an ambiguous
+ * @token resolution), return the newest version IF they are all versions of
+ * ONE plan family (`<base>-v<N>[-<sub>].cspeach.json`), else null. Lets a
+ * version-less resume token (`@<base>` or a short id matching every version)
+ * resolve to the current file instead of erroring "ambiguous". Pure —
+ * deterministic ordering, no fs / mtime.
+ */
+export function pickNewestPlanVersion(paths) {
+    // Sibling: findNewestVersion (below) uses the same filename convention with a
+    // different capture shape (prefix-based + mtime) for the post-read redirect.
+    const re = /^(.+)-v(\d+)(?:-(\d+))?\.cspeach\.json$/;
+    const parsed = paths.map((p) => {
+        const m = re.exec(basename(p));
+        return m ? { path: p, base: m[1], version: Number(m[2]), sub: m[3] ? Number(m[3]) : 0 } : null;
+    });
+    if (parsed.length === 0 || parsed.some((x) => x === null))
+        return null;
+    const items = parsed;
+    const base0 = items[0].base;
+    if (items.some((x) => x.base !== base0))
+        return null;
+    items.sort((a, b) => 
+    // Tiebreak: lexically-greater path wins — deterministic, arbitrary, never
+    // reached in practice (version+sub are always distinct siblings from saveProject).
+    b.version - a.version || b.sub - a.sub || (a.path < b.path ? 1 : -1));
+    return items[0].path;
+}
+/**
+ * True when a queued dispatch command is a `/abap-plan --resume …`. The REPL
+ * uses this to clear session.messages before re-entering, so the auto-fired
+ * next phase runs in fresh, bounded context (the cheap path).
+ */
+export function isPlanResumeCommand(cmd) {
+    const c = cmd.trim();
+    return /^\/abap-plan\b/.test(c) && /(^|\s)--resume(\s|$)/.test(c);
+}
+/**
+ * Find the newest sibling version of the envelope at `path` — same
+ * filename family (`<slug>-<shortid>-vN[...]`) AND same envelope id (the
+ * filename check is just a cheap pre-filter; slug collisions are settled
+ * by the id). Returns null when `path` is already the newest.
+ */
+export function findNewestVersion(path, picked) {
+    const fam = /^(.*-v)(\d+)(?:-\d+)?\.cspeach\.json$/.exec(basename(path));
+    if (!fam)
+        return null;
+    const familyPrefix = fam[1];
+    const dir = dirname(path);
+    let candidates;
+    try {
+        candidates = readdirSync(dir)
+            .map((name) => {
+            const m = new RegExp(`^${familyPrefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(\\d+)(?:-\\d+)?\\.cspeach\\.json$`).exec(name);
+            if (!m)
+                return null;
+            const full = join(dir, name);
+            return { full, version: Number(m[1]), mtimeMs: statSync(full).mtimeMs };
+        })
+            .filter((c) => c !== null)
+            .sort((a, b) => b.version - a.version || b.mtimeMs - a.mtimeMs);
+    }
+    catch {
+        return null;
+    }
+    for (const c of candidates) {
+        if (c.full === path)
+            break; // picked file is already the newest valid one
+        try {
+            const env = readProjectFile(c.full);
+            if (env.artefactType === 'plan' && env.id === picked.id && env.version > picked.version) {
+                return { path: c.full, envelope: env };
+            }
+        }
+        catch {
+            // Unreadable sibling — skip, keep looking.
+        }
+    }
+    return null;
+}
+export async function finishPlanResume(args) {
+    const text = args.textOverride ?? collectTurnAssistantText(args.messages, args.messagesStart);
+    if (text.trim().length === 0) {
+        args.log('');
+        args.log('[plan] turn produced no assistant output — plan envelope UNCHANGED.');
+        args.log(`[plan] re-run: /abap-plan --resume @${basename(args.prepared.path)}`);
+        return;
+    }
+    let extract;
+    try {
+        extract = extractPlan(text);
+    }
+    catch (e) {
+        // Loud by design: the phase may have built real SAP objects, but the
+        // envelope write-back failed — the user must know state and file have
+        // diverged before the next resume.
+        args.log('');
+        args.log(`[plan] PHASE RESULT NOT PERSISTED — ${e instanceof Error ? e.message : String(e)}`);
+        args.log('[plan] The plan envelope is unchanged. Check what the phase actually built');
+        args.log('[plan] (transport, activated objects), update the envelope statuses by hand or');
+        args.log(`[plan] re-run: /abap-plan --resume @${basename(args.prepared.path)}`);
+        return;
+    }
+    const revision = buildPlanRevision(args.prepared.envelope, extract, getAuthorIdentity(), new Date().toISOString());
+    const check = validateEnvelope(JSON.parse(JSON.stringify(revision)));
+    if (!check.ok) {
+        args.log('');
+        args.log(`[plan] PHASE RESULT NOT PERSISTED — revision failed validation: ${check.error.message}`);
+        return;
+    }
+    let outDir;
+    try {
+        outDir = await ensureWorkspace();
+    }
+    catch {
+        outDir = process.cwd();
+    }
+    const savedPath = await saveProject(revision, { cwd: outDir });
+    const statuses = extract.statuses;
+    const next = computeNextPhase(extract.content.phases, statuses);
+    args.log('');
+    args.log(`Plan updated: ${savedPath}`);
+    args.log('');
+    args.log(renderPlanTracker({
+        title: revision.title,
+        version: revision.version,
+        content: extract.content,
+        statuses,
+        currentId: null,
+    }));
+    args.log('');
+    if (next) {
+        args.log(`Next: ${next.id} (${next.delegateTo}) — run /abap-plan --resume @${basename(savedPath)} in a fresh session.`);
+    }
+    else if (extract.content.phases.every((p) => statuses[p.id] === 'validated')) {
+        args.log('Plan complete — every phase validated. Consider /abap-preflight before release.');
+    }
+    else {
+        const blocked = extract.content.phases.filter((p) => statuses[p.id] === 'blocked').map((p) => p.id);
+        args.log(`No eligible next phase. Blocked: ${blocked.join(', ')}. Unblock, then resume again.`);
+    }
+}

package/dist/config/loader.js

@@ -11,7 +11,7 @@ export function isValidWriteMode(v) {
 }
 const DEFAULT_CONFIG = {
     proxy_url: 'https://api.cspeach.dev',
-    default_model: 'claude-opus-4-7',
+    default_model: 'claude-opus-4-8',
     effort: 'xhigh',
     telemetry: 'minimal',
     sap: {},
@@ -65,7 +65,12 @@ function sanitiseCompact(raw) {
 export async function loadConfig() {
     try {
         const raw = await fs.readFile(configFile(), 'utf-8');
-        const parsed = toml.parse(raw);
+        // Strip a leading UTF-8 BOM (U+FEFF). Node's 'utf-8' read does NOT remove it,
+        // and @iarna/toml throws "Unknown character 65279" on a BOM at row 1 col 1.
+        // PowerShell's Set-Content / Out-File add a BOM by default, so a config edited
+        // on Windows can crash the REPL on next launch — tolerate it instead.
+        const noBom = raw.charCodeAt(0) === 0xFEFF ? raw.slice(1) : raw;
+        const parsed = toml.parse(noBom);
         // Shallow merge top-level, but deep-merge `ui` and `classifier` so a user
         // config that omits the new `ui.rendering` key still receives the default.
         // Sanitize the optional shell_exec.allow array. The interface types it as

package/dist/cost/pricing.js

@@ -11,16 +11,25 @@
  * BOTH this file AND the proxy's version. Verify on the public pricing page:
  *   https://www.anthropic.com/pricing
  *
- * Last verified 2026-05-12. Same as proxy.
+ * Last verified 2026-06-07. Same as proxy.
+ *
+ * 2026-06-07 SYNC: e294cff switched the default model to claude-opus-4-8 AND
+ * applied the 3x Opus correction, but only to the proxy copy — this CLI copy
+ * was left stale, so every opus-4-8 turn was an unknown model (footer $0) and
+ * opus-4-5/4-6/4-7 still carried the legacy $15/$75 (~3x overstated). Brought
+ * back in line with cspeach-proxy/src/anthropic/pricing.ts below.
  *
  * Unknown models → returns null + records the model name to a process-level
  * Set so we surface them as an obvious warning rather than silently zeroing.
  */
 const PRICING = {
-    // Claude Opus 4.x family — input 15, output 75, cache_read 1.50, cache_write 18.75
-    'claude-opus-4-7': { inputPer1M: 15.00, outputPer1M: 75.00, cacheReadPer1M: 1.50, cacheCreatePer1M: 18.75 },
-    'claude-opus-4-6': { inputPer1M: 15.00, outputPer1M: 75.00, cacheReadPer1M: 1.50, cacheCreatePer1M: 18.75 },
-    'claude-opus-4-5': { inputPer1M: 15.00, outputPer1M: 75.00, cacheReadPer1M: 1.50, cacheCreatePer1M: 18.75 },
+    // Claude Opus 4.5+ — input 5, output 25, cache_read 0.50, cache_write 6.25 (1.25x input).
+    // 2026-06-07 correction: 4.5/4.6/4.7 were carried at the LEGACY $15/$75; actual
+    // since Opus 4.5 is $5/$25. Only claude-opus-4 (4.0/4.1) genuinely was $15/$75.
+    'claude-opus-4-8': { inputPer1M: 5.00, outputPer1M: 25.00, cacheReadPer1M: 0.50, cacheCreatePer1M: 6.25 },
+    'claude-opus-4-7': { inputPer1M: 5.00, outputPer1M: 25.00, cacheReadPer1M: 0.50, cacheCreatePer1M: 6.25 },
+    'claude-opus-4-6': { inputPer1M: 5.00, outputPer1M: 25.00, cacheReadPer1M: 0.50, cacheCreatePer1M: 6.25 },
+    'claude-opus-4-5': { inputPer1M: 5.00, outputPer1M: 25.00, cacheReadPer1M: 0.50, cacheCreatePer1M: 6.25 },
     'claude-opus-4': { inputPer1M: 15.00, outputPer1M: 75.00, cacheReadPer1M: 1.50, cacheCreatePer1M: 18.75 },
     // Claude Sonnet 4.x family — input 3, output 15, cache_read 0.30, cache_write 3.75
     'claude-sonnet-4-6': { inputPer1M: 3.00, outputPer1M: 15.00, cacheReadPer1M: 0.30, cacheCreatePer1M: 3.75 },

package/dist/projects/email-template.js

@@ -11,6 +11,7 @@ const SUBJECT_BY_TYPE = {
     'cca-assessment': (t) => `Custom code assessment — ${t}`,
     'modernize-result': (t) => `Modernization result — ${t}`,
     'test-coverage': (t) => `Test coverage report — ${t}`,
+    'plan': (t) => `Project plan — ${t}`,
 };
 const BODY_BY_TYPE = {
     'spec-gap': (a) => `Attached is the gap analysis for the ${a.title}.\n${a.itemCount} ${a.itemNoun} across business / data / authorisation / edge cases.`,
@@ -24,6 +25,7 @@ const BODY_BY_TYPE = {
     'cca-assessment': (a) => `Attached is the custom code assessment for ${a.title}.\n${a.itemCount} ${a.itemNoun} classified — review keep / fix / retire / redesign per object.`,
     'modernize-result': (a) => `Attached is the modernization result for ${a.title}.\n${a.itemCount} ${a.itemNoun} attempted — review applied / skipped / failed per object before sign-off.`,
     'test-coverage': (a) => `Attached is the test coverage report for ${a.title}.\n${a.itemCount} test ${a.itemNoun} generated — review the targets + method counts before merging.`,
+    'plan': (a) => `Attached is the project plan for ${a.title}.\n${a.itemCount} ${a.itemNoun} ordered bottom-up — each phase runs in its own session via /abap-plan --resume.`,
 };
 export function renderEmailTemplate(a) {
     const subject = SUBJECT_BY_TYPE[a.artefactType](a.title);

package/dist/projects/extract-plan.js

@@ -0,0 +1,85 @@
+import { parsePlanContent, PLAN_PHASE_STATUSES } from './plan-schema.js';
+const MANIFEST_RE = /<!--\s*csforge:plan-manifest\s*\n([\s\S]*?)\n\s*-->/g;
+export function extractPlan(markdown) {
+    // Last block wins — a continue-in-session turn emits one block per phase.
+    const re = new RegExp(MANIFEST_RE.source, MANIFEST_RE.flags);
+    let m;
+    let last = null;
+    while ((m = re.exec(markdown)) !== null)
+        last = m;
+    if (!last) {
+        throw new Error('No <!-- csforge:plan-manifest --> block found in skill output');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(last[1]);
+    }
+    catch (e) {
+        throw new Error(`plan-manifest block is not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error('plan-manifest block must be a JSON object');
+    }
+    const obj = parsed;
+    if (typeof obj.title !== 'string' || obj.title.trim().length === 0) {
+        throw new Error('plan-manifest is missing a non-empty "title"');
+    }
+    // 2026-06-06 live-smoke lesson #2: the model cannot know the consumed
+    // spec-gap's real path/sha — that provenance lives CLI-side in the
+    // envelope's promotedFrom (threaded by the --from save flow). Models
+    // emit placeholders like {"path":"@equip","sha256":""}, and a junk
+    // provenance pointer must not cost the whole plan: strip it.
+    const rawContent = obj.content;
+    if (rawContent && typeof rawContent === 'object' && rawContent.from?.specGap) {
+        const sha = String(rawContent.from.specGap.sha256 ?? '');
+        if (!/^[0-9a-f]{64}$/.test(sha))
+            delete rawContent.from.specGap;
+    }
+    // 2026-06-06 live-smoke lesson #4 (Postel): normalise model-emitted
+    // `work` blocks instead of rejecting them. Models naturally write
+    // `"transport": null` for "none" (schema fields are optional, NOT
+    // nullable) and a structured OBJECT for notes (a design phase's
+    // decision register) — both reasonable; both killed a fully correct
+    // phase write-back. null -> absent; object notes -> JSON string.
+    const rawPhases = rawContent?.phases;
+    if (Array.isArray(rawPhases)) {
+        for (const p of rawPhases) {
+            const w = p?.work;
+            if (!w || typeof w !== 'object')
+                continue;
+            for (const k of ['generated', 'transport', 'snapshot', 'notes']) {
+                if (w[k] === null)
+                    delete w[k];
+            }
+            if (w.notes !== undefined && typeof w.notes !== 'string') {
+                w.notes = JSON.stringify(w.notes);
+            }
+        }
+    }
+    const pc = parsePlanContent(obj.content);
+    if (!pc.ok) {
+        throw new Error(`plan-manifest content failed validation:\n  ${pc.errors.join('\n  ')}`);
+    }
+    if (typeof obj.statuses !== 'object' || obj.statuses === null || Array.isArray(obj.statuses)) {
+        throw new Error('plan-manifest is missing the "statuses" object');
+    }
+    const rawStatuses = obj.statuses;
+    const statuses = {};
+    for (const p of pc.content.phases) {
+        const s = rawStatuses[p.id];
+        if (typeof s !== 'string' || !PLAN_PHASE_STATUSES.includes(s)) {
+            throw new Error(`plan-manifest statuses["${p.id}"] is ${s === undefined ? 'missing' : `invalid: ${String(s)}`}; ` +
+                `allowed: ${PLAN_PHASE_STATUSES.join(', ')}`);
+        }
+        statuses[p.id] = s;
+    }
+    const items = pc.content.phases.map((p) => ({
+        id: p.id,
+        status: statuses[p.id],
+        answer: null,
+        answeredBy: null,
+        answeredAt: null,
+        comments: [],
+    }));
+    return { title: obj.title.trim(), content: pc.content, items, statuses };
+}

package/dist/projects/index.js

@@ -1,3 +1,6 @@
+export { planContentSchema, parsePlanContent, PLAN_LAYERS, PLAN_DELEGATE_SKILLS, PLAN_PHASE_STATUSES } from './plan-schema.js';
+export { extractPlan } from './extract-plan.js';
+export { statusesFromItems, computeNextPhase, renderPlanTracker, buildPlanRevision } from './plan-run.js';
 export { validateEnvelope } from './validate.js';
 export { canonicalSha256 } from './canonicalize.js';
 export { titleSlug, shortId, projectFilename } from './filename.js';

package/dist/projects/plan-run.js

@@ -0,0 +1,120 @@
+/** Statuses a dead session may have left behind — resumable, picked before fresh `todo`s. */
+const IN_PROGRESS = ['designing', 'building', 'verifying'];
+/**
+ * Phase status lives in interaction.items (store convention). Build the
+ * id→status map; a phase with no matching item defaults to 'todo' rather
+ * than failing — the envelope passed top-level validation, so a missing
+ * item is a seeding gap, not corruption.
+ */
+export function statusesFromItems(items, phases) {
+    const byId = new Map(items.map((it) => [it.id, it.status]));
+    const out = {};
+    for (const p of phases)
+        out[p.id] = byId.get(p.id) ?? 'todo';
+    return out;
+}
+/**
+ * The next phase a resume session should execute: first phase (in the
+ * bottom-up `phases[]` order) that is not yet terminal AND whose
+ * entryCriteria are all 'validated'. In-progress statuses (a prior
+ * session died mid-phase) qualify the same as 'todo' — the phase is
+ * re-entered from the top, gates and grounding included.
+ */
+export function computeNextPhase(phases, statuses) {
+    for (const p of phases) {
+        const s = statuses[p.id] ?? 'todo';
+        if (s === 'validated' || s === 'blocked')
+            continue;
+        if (s !== 'todo' && !IN_PROGRESS.includes(s))
+            continue;
+        if (p.entryCriteria.every((dep) => statuses[dep] === 'validated'))
+            return p;
+    }
+    return null;
+}
+/**
+ * Plan-progress board printed before and after every resume turn (and by
+ * `--status` for plan envelopes). Plain text — flows through chunkEmitter
+ * in Ink mode and console.log in classic mode alike.
+ *
+ *   ─ Plan: HR Dayforce Extract (v3) ── 2/7 validated ─
+ *     ✔ c1.types          abap-data-model  → ZDOM_DAYF_STATUS (S4HK903412)
+ *     ▶ c1.orchestration  abap-generate    ← THIS SESSION
+ *     ○ c1.integration    abap-generate    (needs c1.orchestration)
+ */
+export function renderPlanTracker(a) {
+    const lines = [];
+    const total = a.content.phases.length;
+    const validated = a.content.phases.filter((p) => a.statuses[p.id] === 'validated').length;
+    if (a.includeHeader !== false) {
+        lines.push(`─ Plan: ${a.title} (v${a.version}) ── ${validated}/${total} validated ─`);
+    }
+    const idWidth = Math.max(...a.content.phases.map((p) => p.id.length));
+    const skillWidth = Math.max(...a.content.phases.map((p) => p.delegateTo.length));
+    for (const p of a.content.phases) {
+        const s = a.statuses[p.id] ?? 'todo';
+        const isCurrent = a.currentId != null && p.id === a.currentId;
+        const symbol = isCurrent ? '▶'
+            : s === 'validated' ? '✔'
+                : s === 'blocked' ? '✖'
+                    : IN_PROGRESS.includes(s) ? '◌'
+                        : '○';
+        lines.push(`  ${symbol} ${p.id.padEnd(idWidth)}  ${p.delegateTo.padEnd(skillWidth)}  ${annotationFor(p, s, isCurrent, a.statuses)}`.trimEnd());
+    }
+    return lines.join('\n');
+}
+function annotationFor(p, s, isCurrent, statuses) {
+    if (isCurrent)
+        return '← THIS SESSION';
+    if (s === 'validated') {
+        const objs = p.work?.generated?.join(', ') ?? '';
+        const tr = p.work?.transport ? ` (${p.work.transport})` : '';
+        return objs || tr ? `→ ${objs}${tr}`.trimEnd() : '';
+    }
+    if (s === 'blocked')
+        return 'BLOCKED';
+    if (IN_PROGRESS.includes(s))
+        return `in progress (${s})`;
+    const unmet = p.entryCriteria.filter((dep) => statuses[dep] !== 'validated');
+    return unmet.length > 0 ? `(needs ${unmet.join(', ')})` : '';
+}
+/**
+ * Build the version-N+1 envelope from the original plan envelope and the
+ * manifest block a resume turn emitted.
+ *
+ * Invariants preserved:
+ *  - id / createdAt / createdBy / title / source / promotedFrom unchanged
+ *    (the extract's title is intentionally IGNORED — title drift would
+ *    break the multi-file same-source detection in status.ts)
+ *  - history is append-only; version === history.length stays true
+ *  - item comments / answers added via the editor survive the revision —
+ *    only the status comes from the new extract
+ */
+export function buildPlanRevision(original, extract, author, nowIso) {
+    if (original.artefactType !== 'plan') {
+        throw new Error(`buildPlanRevision expects a plan envelope, got ${original.artefactType}`);
+    }
+    const oldItems = new Map(original.interaction.items.map((it) => [it.id, it]));
+    const mergedItems = extract.items.map((ni) => {
+        const old = oldItems.get(ni.id);
+        return old ? { ...old, status: ni.status } : ni;
+    });
+    const oldStatuses = statusesFromItems(original.interaction.items, original.content.phases);
+    const diffs = [];
+    for (const p of extract.content.phases) {
+        const before = oldStatuses[p.id] ?? 'todo';
+        const after = extract.statuses[p.id];
+        if (before !== after)
+            diffs.push(`${p.id}: ${before} → ${after}`);
+    }
+    const summary = diffs.length > 0 ? diffs.join('; ') : 'resume run — no phase status change';
+    return {
+        ...original,
+        lastEditedAt: nowIso,
+        lastEditedBy: author,
+        version: original.version + 1,
+        content: extract.content,
+        interaction: { items: mergedItems },
+        history: [...original.history, { at: nowIso, by: author, action: 'edited', summary }],
+    };
+}