@cspeach/cli 0.9.0 → 1.1.0

package/dist/projects/migration.js

@@ -24,11 +24,12 @@
  * The prompt is interactive (via the supplied async prompt callback);
  * one-shot mode skips it entirely (caller passes a no-op).
  */
-import { existsSync, mkdirSync, readdirSync, renameSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, renameSync, rmdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import os from 'node:os';
 import { loadConfig, saveConfig } from '../config/loader.js';
 import { defaultWorkspaceFor } from './workspace.js';
+import { OUTPUT_ROOT, LEGACY_ROOT } from './output-paths.js';
 /**
  * Run the migration prompt if and only if it hasn't run before AND
  * there's actually something to migrate. No-op otherwise. Always sets
@@ -109,3 +110,104 @@ export async function maybePromptWorkspaceMigration(deps) {
     }
     await saveConfig({ ...cfg, migration_prompted: true });
 }
+/**
+ * Recursively move every entry under `srcDir` into `dstDir`, MERGING into
+ * existing directories rather than clobbering them. Files that already exist
+ * at the destination are left untouched (the legacy copy is dropped — the
+ * dual-read already prefers the new root, so an existing new file wins).
+ * After the walk, the source directory is removed if empty.
+ */
+function mergeMoveTree(srcDir, dstDir, log) {
+    mkdirSync(dstDir, { recursive: true });
+    for (const name of readdirSync(srcDir)) {
+        const src = join(srcDir, name);
+        const dst = join(dstDir, name);
+        const isDir = statSync(src).isDirectory();
+        if (isDir) {
+            mergeMoveTree(src, dst, log);
+        }
+        else if (existsSync(dst)) {
+            log(`(keeping existing ${name} — already migrated)`);
+        }
+        else {
+            renameSync(src, dst);
+        }
+    }
+    // Remove the source dir if the walk emptied it. A merge that kept some
+    // existing-destination files may leave it non-empty — rmdir throws then,
+    // which we swallow (the leftover is harmless and visible to the user).
+    try {
+        rmdirSync(srcDir);
+    }
+    catch {
+        /* non-empty after a partial merge — leave it for the user to inspect */
+    }
+}
+/**
+ * One-time offer to migrate a workspace's legacy `.abapforge/` output root
+ * into the branded `.cspeach/` root.
+ *
+ * Fires only when a top-level `.abapforge/` directory exists in the given
+ * workspace root AND the user has not previously chosen "never". Safe to call
+ * every startup: a successful move removes the folder (so it stops naturally),
+ * and the dual-read resolver keeps old projects working in the interim if the
+ * user declines.
+ *
+ * Idempotent and non-destructive: the move MERGES into any existing
+ * `.cspeach/<domain>` rather than overwriting it.
+ */
+export async function maybeOfferAbapforgeMigration(workspaceRoot, deps) {
+    const legacyDir = join(workspaceRoot, LEGACY_ROOT);
+    if (!existsSync(legacyDir))
+        return;
+    const cfg = await loadConfig();
+    if (cfg.abapforge_migration_declined === true)
+        return;
+    const newDir = join(workspaceRoot, OUTPUT_ROOT);
+    let choice;
+    try {
+        choice = await deps.prompt({ workspaceRoot, legacyDir, newDir });
+    }
+    catch {
+        // User aborted the prompt (Ctrl+C) — leave everything as-is so the
+        // offer can re-fire next session. Never silently commit to a default.
+        return;
+    }
+    if (choice === 'never') {
+        await saveConfig({ ...cfg, abapforge_migration_declined: true });
+        deps.log(`Leaving ${legacyDir} alone. (Will not ask again.)`);
+        return;
+    }
+    if (choice === 'skip') {
+        deps.log(`Leaving ${legacyDir} alone for now.`);
+        return;
+    }
+    // choice === 'move'
+    try {
+        for (const child of readdirSync(legacyDir)) {
+            const src = join(legacyDir, child);
+            const dst = join(newDir, child);
+            if (statSync(src).isDirectory()) {
+                mergeMoveTree(src, dst, deps.log);
+            }
+            else if (existsSync(dst)) {
+                deps.log(`(keeping existing ${child} — already migrated)`);
+            }
+            else {
+                mkdirSync(newDir, { recursive: true });
+                renameSync(src, dst);
+            }
+        }
+        // Drop the now-(hopefully)-empty legacy root.
+        try {
+            rmdirSync(legacyDir);
+        }
+        catch {
+            /* a partial merge left files behind — keep the folder for inspection */
+        }
+        deps.log(`Moved legacy outputs from ${legacyDir} → ${newDir}`);
+    }
+    catch (err) {
+        deps.log(`Migration failed: ${err.message}. Old folder left untouched.`);
+    }
+}

package/dist/projects/output-paths.js

@@ -0,0 +1,27 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+/** Branded output root for customer working files (was .abapforge). */
+export const OUTPUT_ROOT = '.cspeach';
+/** Pre-2026-06 root — still READ for back-compat, never written anew. */
+export const LEGACY_ROOT = '.abapforge';
+/** Build `<projectRoot>/.cspeach/<domain>` (domain = cca | upgrades | modernize | tests). */
+export function domainDir(projectRoot, domain) {
+    return join(projectRoot, OUTPUT_ROOT, domain);
+}
+/**
+ * Resolve a project-relative detail path to an absolute path, preferring the
+ * new root and falling back to the legacy `.abapforge/` location when the new
+ * one is absent. Returns the NEW absolute path when neither exists (the caller
+ * is about to create it). `relPath` may be expressed against either root — we
+ * normalise the leading segment before probing.
+ */
+export function resolveExistingDomainPath(projectRoot, relPath) {
+    const tail = relPath.replace(/^\.(cspeach|abapforge)[/\\]/, '');
+    const asNew = join(projectRoot, OUTPUT_ROOT, tail);
+    if (existsSync(asNew))
+        return asNew;
+    const asLegacy = join(projectRoot, LEGACY_ROOT, tail);
+    if (existsSync(asLegacy))
+        return asLegacy;
+    return asNew;
+}

package/dist/projects/plan-run.js

@@ -1,5 +1,53 @@
+// cspeach-cli/src/projects/plan-run.ts
+//
+// Pure plan-execution helpers for /abap-plan --resume (B3, 2026-06-06).
+// No I/O here — file reads, prompts, and the runTurn call live in
+// commands/plan-resume.ts. Keeping these pure makes the next-phase
+// picker, the tracker renderer, and the revision builder unit-testable
+// without touching disk.
+import chalk from 'chalk';
 /** Statuses a dead session may have left behind — resumable, picked before fresh `todo`s. */
 const IN_PROGRESS = ['designing', 'building', 'verifying'];
+/**
+ * Auditor verdict resolution (2026-07-03 agentic-flow design). A phase's
+ * audit is RESOLVED when the independent auditor passed it or the user
+ * explicitly waived the findings. An ABSENT audit is resolved too — legacy
+ * envelopes (phases validated before the auditor existed) must remain
+ * satisfied, or every pre-audit plan would deadlock on resume.
+ */
+export function isAuditResolved(audit) {
+    if (!audit)
+        return true; // legacy envelope — pre-auditor phases stay satisfied
+    // 'warn' (confidence-tiered redesign, 2026-07-08) is the NON-BLOCKING tier:
+    // the phase passed with notes, so — exactly like a pass or an explicit waiver
+    // — it RESOLVES the audit and unlocks dependants. The notes ride along on
+    // audit.findings and are surfaced by the tracker glyph + the chain render.
+    //
+    // 'infra_failed' (audit-infra-continue, 2026-07-09) is RESOLVED too, for a
+    // different reason: the audit could not RUN (the model call returned no
+    // output after its in-turn retries). An audit that can't run is not a finding
+    // against the work — and the phase already passed its own exit gate
+    // (activation + ATC) — so walling verified work on an infra outage is wrong.
+    // It resolves like a warn: dependants unlock, the chain continues, and the
+    // "not verified" fact is surfaced (loud chain note + the ⚠ audit-not-run
+    // glyph) and recorded (state stays infra_failed; NOT laundered to waived).
+    return audit.state === 'passed' || audit.state === 'waived'
+        || audit.state === 'warn' || audit.state === 'infra_failed';
+}
+/**
+ * C1 (2026-06-11, D30 waiver) — a phase counts as DONE for DAG purposes when
+ * it is 'validated' OR 'validated-with-waiver' (exit gate not met, but the
+ * user explicitly waived it). Single predicate so eligibility, summary
+ * counting, and the "plan complete" checks can never drift apart.
+ *
+ * 2026-07-03 (agentic-flow): additionally, when the phase carries an auditor
+ * verdict, it must be resolved (passed/waived) — a validated-but-audit-failed
+ * phase does NOT unlock dependants. The param is optional so pre-audit call
+ * sites keep their exact behaviour.
+ */
+export function isPhaseSatisfied(s, audit) {
+    return (s === 'validated' || s === 'validated-with-waiver') && isAuditResolved(audit);
+}
 /**
  * Phase status lives in interaction.items (store convention). Build the
  * id→status map; a phase with no matching item defaults to 'todo' rather
@@ -21,13 +69,16 @@ export function statusesFromItems(items, phases) {
  * re-entered from the top, gates and grounding included.
  */
 export function computeNextPhase(phases, statuses) {
+    // Audit verdicts live on the phase objects, not the status map — look each
+    // dependency up so a validated-but-audit-failed phase gates its dependants.
+    const byId = new Map(phases.map((p) => [p.id, p]));
     for (const p of phases) {
         const s = statuses[p.id] ?? 'todo';
-        if (s === 'validated' || s === 'blocked')
+        if (isPhaseSatisfied(s, p.audit) || s === 'blocked')
             continue;
         if (s !== 'todo' && !IN_PROGRESS.includes(s))
             continue;
-        if (p.entryCriteria.every((dep) => statuses[dep] === 'validated'))
+        if (p.entryCriteria.every((dep) => isPhaseSatisfied(statuses[dep], byId.get(dep)?.audit)))
             return p;
     }
     return null;
@@ -42,41 +93,240 @@ export function computeNextPhase(phases, statuses) {
  *     ▶ c1.orchestration  abap-generate    ← THIS SESSION
  *     ○ c1.integration    abap-generate    (needs c1.orchestration)
  */
+// Human phase labels — a phase is named for the KIND of work it does, so a
+// non-ABAP reader can follow the plan. The exit-gate / produced objects carry
+// the specifics on the detail line.
+const LAYER_LABELS = {
+    'types': 'Types',
+    'persistence': 'Tables & structures',
+    'data-model': 'CDS views',
+    'behavior': 'Behaviour & validations',
+    'service': 'Service binding',
+    'orchestration': 'Jobs & reports',
+    'integration': 'Integration',
+    'ui': 'UI',
+};
+const DELEGATE_LABELS = {
+    'abap-design': 'Design',
+    'abap-test': 'Tests',
+    'abap-eml': 'Behaviour logic',
+    'abap-segw': 'OData (SEGW)',
+};
+function phaseTitle(p) {
+    // C2 (2026-06-11, D29): an explicit seed-time title wins — the seed prose
+    // instructs short human names ("Design", "Tables", "Service"). The label
+    // maps remain the fallback for envelopes seeded before titles existed.
+    const explicit = p.title?.trim();
+    if (explicit)
+        return explicit;
+    return DELEGATE_LABELS[p.delegateTo] ?? LAYER_LABELS[p.layer] ?? tidyId(p.id);
+}
+function tidyId(id) {
+    const tail = id.split('.').pop() ?? id;
+    return tail.replace(/[-_]/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+}
+// A short plain-language hint from the exit gate: the first clause, clamped.
+function shortGate(gate, n = 60) {
+    const first = String(gate ?? '').split(/[.;]/)[0].trim();
+    const s = first.length >= 10 ? first : String(gate ?? '').trim();
+    return s.length > n ? s.slice(0, n - 1).trimEnd() + '…' : s;
+}
+// The detail line: what a done phase produced, else what the phase is about.
+function phaseDetail(p, s) {
+    if (isPhaseSatisfied(s)) {
+        const objs = (p.work?.generated ?? []).join(', ');
+        return objs || shortGate(p.exitGate);
+    }
+    return shortGate(p.exitGate);
+}
+/**
+ * Auditor-verdict glyph rendered after the phase status (2026-07-03,
+ * agentic-flow). Empty string when the phase carries no audit — legacy
+ * envelopes must render byte-identical to the pre-audit tracker.
+ */
+function auditGlyph(audit) {
+    if (!audit)
+        return '';
+    switch (audit.state) {
+        case 'passed': return ` ${chalk.green('✔ audited')}`;
+        case 'warn': {
+            // Non-blocking tier: validated-WITH-NOTES. Distinct from a clean pass and
+            // from the "not run" states — it ran, passed, and carries N notes.
+            const n = audit.findings?.length ?? 0;
+            return ` ${chalk.yellow(`⚠ ${n} note${n === 1 ? '' : 's'}`)}`;
+        }
+        case 'waived': return ` ${chalk.yellow(`✎ waived${audit.waiveCategory ? ` (${audit.waiveCategory})` : ''}`)}`;
+        case 'failed': return ` ${chalk.red('✖ audit failed')}`;
+        case 'not_audited_hand_edited': return ` ${chalk.yellow('✋ hand-edited')}`;
+        case 'pending':
+        case 'infra_failed':
+        default:
+            // `default` is deliberate forward-compat, not a missed case: an unknown
+            // future PlanAuditState renders "⚠ audit not run" instead of crashing.
+            return ` ${chalk.yellow('⚠ audit not run')}`;
+    }
+}
+/**
+ * Plan-progress board — a Claude-Code-style checkbox task list. Each phase is
+ * named for the work it does (not its mechanical id), so the reader can follow
+ * along; ☒ = done (dim), ☐ = to do, the active phase is bold with a `◀ now`
+ * marker, blocked is red. Flows through chunkEmitter (Ink) and console.log
+ * (classic) alike — chalk degrades to plain text on a non-colour stream.
+ */
 export function renderPlanTracker(a) {
+    const PEACH = '#F5A623';
     const lines = [];
     const total = a.content.phases.length;
-    const validated = a.content.phases.filter((p) => a.statuses[p.id] === 'validated').length;
+    // Waived phases count as done in the header tally — the DAG treats them as
+    // satisfied; the per-line "✓* (waived)" marker carries the distinction.
+    // Audit-aware (2026-07-03): a validated-but-audit-failed phase must NOT
+    // count as done, or the header would say "N/N done" while the completion
+    // check refuses to complete — the tally uses the same predicate as the DAG.
+    const validated = a.content.phases.filter((p) => isPhaseSatisfied(a.statuses[p.id], p.audit)).length;
     if (a.includeHeader !== false) {
-        lines.push(`─ Plan: ${a.title} (v${a.version}) ── ${validated}/${total} validated ─`);
+        lines.push(chalk.dim(`─ ${a.title} (v${a.version}) · ${validated}/${total} done ─`));
+        lines.push('');
     }
-    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());
+        const title = phaseTitle(p);
+        const detail = phaseDetail(p, s);
+        const dash = detail ? ` — ${detail}` : '';
+        // Auditor verdict after the status — '' on legacy phases (no audit field),
+        // so pre-audit envelopes render byte-identical.
+        const audit = auditGlyph(p.audit);
+        if (s === 'validated') {
+            lines.push(chalk.dim(`  ☒ ${title}${dash}`) + audit);
+        }
+        else if (s === 'validated-with-waiver') {
+            // C1 (D30 waiver) — done-but-waived: the exit gate was never met; the
+            // user accepted it anyway. Distinct marker so a tracker reader can tell
+            // a verified phase from a waived one at a glance.
+            lines.push(chalk.dim(`  ☒ ${title}${dash}`) + ` ${chalk.yellow('✓* (waived)')}` + audit);
+        }
+        else if (s === 'blocked') {
+            lines.push(`  ${chalk.red('☐')} ${chalk.red(title)} ${chalk.red('— blocked')}${detail ? chalk.dim(` · ${detail}`) : ''}${audit}`);
+        }
+        else if (isCurrent) {
+            lines.push(`  ${chalk.hex(PEACH)('☐')} ${chalk.bold(title)}${dash}${audit}  ${chalk.hex(PEACH).bold('◀ now')}`);
+        }
+        else if (IN_PROGRESS.includes(s)) {
+            lines.push(`  ${chalk.hex(PEACH)('☐')} ${chalk.bold(title)}${dash}${audit}  ${chalk.dim(`(${s})`)}`);
+        }
+        else {
+            lines.push(`  ☐ ${title}${chalk.dim(dash)}${audit}`);
+        }
+    }
+    // Off-switch footer — honesty: state plainly that this run's phases are not
+    // being audited. Rendered only when the caller threads auditsOff (in-memory).
+    if (a.auditsOff) {
+        lines.push('');
+        lines.push(chalk.dim('  audits: off'));
     }
     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() : '';
+/* ── plan-complete chaining (C2, 2026-06-11, D24) ───────────────────────── */
+/**
+ * SRVB-shaped object name. Two naming families seen live + documented in
+ * .claude/rules/rap-patterns.md:
+ *   - ADT default OData suffix:  ZUI_PM_MAINTREQ_O4 / ..._O2
+ *   - rap-patterns convention:   ZSalesOrder_UI_V4 / _UI_V2 / _API_V4 / _API_V2
+ */
+const SRVB_NAME_RE = /^[zy]\w*(?:_o[24]|_(?:ui|api)_v[24])$/i;
+/**
+ * The exact service-binding name a completed plan produced, for the
+ * /abap-fiori-build hand-off. Resolution ladder (newest phase wins at
+ * each rung — a structurally-revised plan may carry several):
+ *   1. explicit `work.binding` (the seed/resume prose instructs the service
+ *      phase to record it)
+ *   2. an SRVB-shaped name in a service-layer phase's `work.generated`
+ *   3. an SRVB-shaped name anywhere in `work.generated` (binding built
+ *      outside a service-layer phase)
+ * Returns null when nothing matches — the caller still mentions
+ * /abap-fiori-build generically.
+ */
+export function findServiceBinding(phases) {
+    for (let i = phases.length - 1; i >= 0; i--) {
+        const explicit = phases[i].work?.binding?.trim();
+        if (explicit)
+            return explicit;
+    }
+    const scan = (ps) => {
+        for (let i = ps.length - 1; i >= 0; i--) {
+            const hit = (ps[i].work?.generated ?? []).find((n) => SRVB_NAME_RE.test(n.trim()));
+            if (hit)
+                return hit.trim();
+        }
+        return null;
+    };
+    return scan(phases.filter((p) => p.layer === 'service')) ?? scan(phases);
+}
+/**
+ * The lines printed when a plan has no next phase because EVERY phase is
+ * satisfied. Single construction site for both call points (preparePlanResume
+ * re-opening a finished plan, finishPlanResume completing the last phase) so
+ * the D24 fiori chain can never drift between them.
+ *
+ * A UI-less backend stack (service layer present, no ui phase) chains to
+ * /abap-fiori-build — with the EXACT binding name when resolvable. A plan
+ * that already built its UI, or never built a service, gets no chain line.
+ */
+export function planCompletionLines(phases) {
+    const lines = ['Plan complete — every phase validated.'];
+    // Confidence-tiered redesign (2026-07-08): a completed plan that carried
+    // non-blocking warn verdicts surfaces them in the FINAL summary — a warned
+    // phase shows its notes, so an "all validated" plan never hides that a phase
+    // passed WITH reservations. (Empty when no phase warned ⇒ byte-identical to
+    // the pre-warn completion message.)
+    for (const p of phases) {
+        if (p.audit?.state !== 'warn')
+            continue;
+        const notes = p.audit.findings ?? [];
+        lines.push(notes.length > 0
+            ? `⚠ ${p.id} passed with ${notes.length} note${notes.length === 1 ? '' : 's'}: ${notes.join('; ')}.`
+            : `⚠ ${p.id} passed with notes.`);
     }
-    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(', ')})` : '';
+    // §10 Q2 (audit-confidence redesign): a waived phase surfaces its light
+    // category + reason in the FINAL summary — an "all validated" plan never
+    // hides that a gate was a human override, and the category (false-positive
+    // vs accepted-risk) is right there for the reader. Legacy waivers without a
+    // category degrade to a bare `waived:` line (back-compat).
+    for (const p of phases) {
+        if (p.audit?.state !== 'waived')
+            continue;
+        const cat = p.audit.waiveCategory ? ` (${p.audit.waiveCategory})` : '';
+        const reason = p.audit.waivedReason ? `: ${p.audit.waivedReason}` : '';
+        lines.push(`✎ ${p.id} waived${cat}${reason}.`);
+    }
+    // audit-infra-continue (2026-07-09): a phase whose audit could NOT RUN
+    // surfaces in the FINAL summary as a DISTINCT "unverified" line — an "all
+    // validated" plan must never hide that a phase shipped without an independent
+    // audit. It is framed as an infrastructure failure (not a code finding) and
+    // NOT as a waiver (the user never asserted acceptance). Empty when no phase
+    // hit infra ⇒ byte-identical to the pre-fix completion message.
+    for (const p of phases) {
+        if (p.audit?.state !== 'infra_failed')
+            continue;
+        lines.push(`⚠ ${p.id} was NOT audit-verified (audit infrastructure failed — its own exit gate, activation + ATC, passed).`);
+    }
+    const hasUi = phases.some((p) => p.layer === 'ui' || p.delegateTo === 'abap-fiori-build');
+    const hasService = phases.some((p) => p.layer === 'service');
+    if (!hasUi && hasService) {
+        const binding = findServiceBinding(phases);
+        lines.push(binding
+            ? `Backend complete. Next: /abap-fiori-build — point it at ${binding}.`
+            : 'Backend complete. Next: /abap-fiori-build — point it at the published service binding.');
+    }
+    // Last-written-wins: the LAST ui phase carrying a deployedUrl, matching
+    // buildUiPhaseContext's reverse-scan resolution (both consume ui work that
+    // ui.deploy records — direction must agree between the two sites).
+    const deployed = [...phases].reverse().find((p) => p.layer === 'ui' && p.work?.deployedUrl);
+    if (deployed?.work?.deployedUrl) {
+        lines.push(`App deployed: ${deployed.work.deployedUrl}`);
+    }
+    lines.push('Consider /abap-preflight on the produced transport(s) before release.');
+    return lines;
 }
 /**
  * Build the version-N+1 envelope from the original plan envelope and the
@@ -90,7 +340,14 @@ function annotationFor(p, s, isCurrent, statuses) {
  *  - 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) {
+export function buildPlanRevision(original, extract, author, nowIso, 
+/**
+ * Task 6 (2026-07-03): optional history-entry summary. Audit-verdict
+ * revisions carry no phase-status diff, so the default "resume run — no
+ * phase status change" would hide WHY the version exists; callers like
+ * applyAuditResult pass e.g. "audit c1.design: failed (2 findings)".
+ */
+summaryOverride) {
     if (original.artefactType !== 'plan') {
         throw new Error(`buildPlanRevision expects a plan envelope, got ${original.artefactType}`);
     }
@@ -107,7 +364,8 @@ export function buildPlanRevision(original, extract, author, nowIso) {
         if (before !== after)
             diffs.push(`${p.id}: ${before} → ${after}`);
     }
-    const summary = diffs.length > 0 ? diffs.join('; ') : 'resume run — no phase status change';
+    const summary = summaryOverride
+        ?? (diffs.length > 0 ? diffs.join('; ') : 'resume run — no phase status change');
     return {
         ...original,
         lastEditedAt: nowIso,