@cspeach/cli 0.9.0 → 1.1.0

package/dist/projects/handover-md.js

@@ -0,0 +1,195 @@
+// cspeach-cli/src/projects/handover-md.ts
+//
+// Task 8 (agentic-flow, 2026-07-03) — markdown handover projection.
+//
+// Design rule (docs/strategy/2026-07-02-agentic-flow-design.md, Decision 5):
+// the .cspeach.json envelope is the SINGLE machine source of truth; this
+// markdown file is a WRITE-ONLY, deterministically regenerable projection.
+// Nothing ever reads it back as state — enforced by design: no function in
+// this module accepts markdown. One `<planBase>-handover.md` per plan family
+// (the version suffix is stripped), overwritten on every envelope save.
+//
+// renderPlanHandover is PURE and DETERMINISTIC: no Date.now(), no randomness —
+// every value derives from envelope fields, so the same envelope always
+// renders byte-identical output (regenerability is the whole contract).
+import { writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import chalk from 'chalk';
+import { statusesFromItems, computeNextPhase, isPhaseSatisfied, planCompletionLines, } from './plan-run.js';
+import { projectFilename } from './filename.js';
+import { readProjectFile } from './status.js';
+/**
+ * Plain-text mirror of the tracker's auditGlyph wording (plan-run.ts) — same
+ * words, no chalk. Empty-audit phases render NO segment, matching the
+ * tracker's legacy-envelope behaviour. The `default` arm is deliberate
+ * forward-compat: an unknown future PlanAuditState reads "audit not run"
+ * instead of crashing the projection.
+ */
+function auditWords(audit) {
+    if (!audit)
+        return null;
+    switch (audit.state) {
+        case 'passed': return '✔ audited';
+        case 'warn': {
+            // Non-blocking tier — passed WITH notes. Plain-text mirror of the
+            // tracker's warn glyph; count comes from findings.
+            const n = audit.findings?.length ?? 0;
+            return `⚠ passed with ${n} note${n === 1 ? '' : 's'}`;
+        }
+        case 'waived': return `✎ waived${audit.waiveCategory ? ` (${audit.waiveCategory})` : ''}`;
+        case 'failed': return '✖ audit failed';
+        case 'not_audited_hand_edited': return '✋ hand-edited';
+        case 'pending':
+        case 'infra_failed':
+        default:
+            return '⚠ audit not run';
+    }
+}
+/**
+ * Minimal YAML scalar emitter (no library — the frontmatter fields are all
+ * scalars / string arrays). Simple token values stay bare; anything else is
+ * emitted as a JSON string, which is valid YAML 1.2 double-quoted syntax.
+ */
+function yamlScalar(v) {
+    // Bare (plain) scalar only for the safe token alphabet: starts with a
+    // non-indicator char (`@` is a YAML reserved indicator and `-` opens a
+    // block-sequence entry — both are quoted when leading, but stay fine
+    // mid-string), no `: ` (mapping ambiguity), no ` #` (comment), no
+    // trailing space. Everything else goes JSON-quoted.
+    const plainSafe = /^[A-Za-z0-9/_.][A-Za-z0-9@/_.\- ]*$/.test(v)
+        && !v.includes(': ') && !v.includes(' #') && !v.endsWith(' ');
+    return plainSafe ? v : JSON.stringify(v);
+}
+/**
+ * Audit off-switch (2026-07-06, owner) — derive `audits: on | off | mixed` for
+ * the frontmatter PURELY from phase audit-field presence, no new state:
+ * among the SATISFIED phases (the ones that actually ran to completion), an ON
+ * run leaves every one carrying an audit field (passed/waived), an OFF run
+ * leaves none. Mixed = both present (a plan run partly on, partly off).
+ * Nothing satisfied yet ⇒ 'on' (the config default; nothing has run off).
+ * Caveat: a pre-auditor legacy plan (satisfied phases, no audit fields) derives
+ * 'off' — technically "audits never existed" rather than "turned off", but the
+ * field-presence signal is honest and needs no schema addition.
+ */
+function deriveAudits(phases, statuses) {
+    const satisfied = phases.filter((p) => isPhaseSatisfied(statuses[p.id], p.audit));
+    if (satisfied.length === 0)
+        return 'on';
+    const withAudit = satisfied.filter((p) => p.audit !== undefined).length;
+    if (withAudit === 0)
+        return 'off';
+    if (withAudit === satisfied.length)
+        return 'on';
+    return 'mixed';
+}
+function progressLine(p, status) {
+    const segments = [
+        p.id,
+        p.title?.trim() || null,
+        status,
+        auditWords(p.audit),
+        p.work?.transport ? `transport ${p.work.transport}` : null,
+    ].filter((s) => s !== null && s.length > 0);
+    return `- ${segments.join(' — ')}`;
+}
+/**
+ * Render the handover markdown for a plan envelope. Pure + deterministic —
+ * see the module header. Throws on non-plan envelopes (structural misuse);
+ * the write helper below catches everything.
+ */
+export function renderPlanHandover(envelope) {
+    if (envelope.artefactType !== 'plan') {
+        throw new Error(`renderPlanHandover expects a plan envelope, got ${envelope.artefactType}`);
+    }
+    const content = envelope.content;
+    const statuses = statusesFromItems(envelope.interaction.items, content.phases);
+    // Derived status — same predicates as the DAG (never reimplemented here):
+    // all satisfied → complete; any blocked → blocked; else in-progress.
+    const allSatisfied = content.phases.every((p) => isPhaseSatisfied(statuses[p.id], p.audit));
+    const anyBlocked = content.phases.some((p) => statuses[p.id] === 'blocked');
+    const status = allSatisfied ? 'complete' : anyBlocked ? 'blocked' : 'in-progress';
+    const next = computeNextPhase(content.phases, statuses);
+    // 'done' only when genuinely complete; a deadlocked plan (no eligible phase,
+    // not all satisfied) says 'none' — 'done' would misreport a blocked plan.
+    const phaseField = next ? next.id : allSatisfied ? 'done' : 'none';
+    // The resume command uses the canonical filename reconstructed from envelope
+    // fields (deterministic). A rare on-disk `-N` collision sibling still
+    // resolves — version-less/newest-version resolution in plan-resume.ts
+    // matches the whole family.
+    const nextAction = allSatisfied
+        ? planCompletionLines(content.phases).join(' ')
+        : `/abap-plan --resume @${projectFilename({
+            title: envelope.title, artefactType: 'plan', id: envelope.id, version: envelope.version,
+        })}`;
+    const artifacts = content.phases.flatMap((p) => p.work?.generated ?? []);
+    const audits = deriveAudits(content.phases, statuses);
+    const lines = [
+        '---',
+        `status: ${status}`,
+        `audits: ${audits}`,
+        `phase: ${yamlScalar(phaseField)}`,
+        `next-action: ${yamlScalar(nextAction)}`,
+        `artifacts: [${artifacts.map(yamlScalar).join(', ')}]`,
+        `envelope-version: ${envelope.version}`,
+        '---',
+        `# ${envelope.title} — plan handover`,
+        '',
+        '## Progress',
+        '',
+        ...content.phases.map((p) => progressLine(p, statuses[p.id] ?? 'todo')),
+        '',
+        '## Last stop',
+        '',
+    ];
+    const stop = content.lastStop;
+    lines.push(stop
+        ? `${stop.phaseId} — ${stop.reason}${stop.detail ? ` — ${stop.detail}` : ''} (${stop.at})`
+        : '(none)');
+    lines.push('', '## Decisions & notes', '');
+    const noted = content.phases.filter((p) => (p.work?.notes ?? '').trim().length > 0);
+    if (noted.length === 0) {
+        lines.push('(none)');
+    }
+    else {
+        for (const p of noted) {
+            lines.push(`### ${p.id}`, '', p.work.notes.trim(), '');
+        }
+        lines.pop(); // drop the trailing blank inside the section
+    }
+    return lines.join('\n') + '\n';
+}
+/**
+ * The projection's path for an envelope path: version suffix (`-vN` and any
+ * `-vN-M` collision sub-suffix from saveProject) stripped, so ONE handover
+ * file per plan family is overwritten across versions —
+ * `hr-extract-plan-ab12-v3.cspeach.json` → `hr-extract-plan-ab12-handover.md`.
+ */
+export function handoverPathFor(envelopePath) {
+    const name = basename(envelopePath);
+    const base = name.replace(/(?:-v\d+(?:-\d+)?)?\.cspeach\.json$/, '');
+    return join(dirname(envelopePath), `${base}-handover.md`);
+}
+/**
+ * Regenerate `<planBase>-handover.md` beside a just-saved plan envelope.
+ * Reads the ENVELOPE back from `savedPath` (reading the envelope is fine —
+ * it is the source of truth; the .md is never read). Best-effort by design:
+ * any failure logs one dim line and returns null — projection loss must
+ * never break the run. Returns the written path on success; null for
+ * non-plan envelopes and on any failure.
+ */
+export function writePlanHandover(savedPath, log) {
+    const logFn = log ?? ((...lines) => { for (const l of lines)
+        console.log(l); });
+    try {
+        const envelope = readProjectFile(savedPath);
+        if (envelope.artefactType !== 'plan')
+            return null;
+        const target = handoverPathFor(savedPath);
+        writeFileSync(target, renderPlanHandover(envelope), 'utf8');
+        return target;
+    }
+    catch (e) {
+        logFn(chalk.dim(`[plan] handover markdown not regenerated (${e instanceof Error ? e.message : String(e)}) — the envelope remains the source of truth.`));
+        return null;
+    }
+}

package/dist/projects/index.js

@@ -1,10 +1,13 @@
 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 { statusesFromItems, computeNextPhase, renderPlanTracker, buildPlanRevision, isPhaseSatisfied, isAuditResolved } from './plan-run.js';
 export { validateEnvelope } from './validate.js';
 export { canonicalSha256 } from './canonicalize.js';
 export { titleSlug, shortId, projectFilename } from './filename.js';
-export { runSaveCommand } from './save-command.js';
+export { runSaveCommand, detectArtifactSkill, peekPlanManifestTitle, resolvePriorPlanEnvelope } from './save-command.js';
+export { offerAnswerBlockers, openBlockers, applyBlockerAnswers } from './answer-blockers.js';
+export { mergeCcaAssessments, renderCcaMergeManifest, parseScopePatterns, scopePatternsIntersect, CCA_MANIFEST_ROW_CAP } from './merge-cca.js';
+export { mergeUpgradeProgress, renderUpgradeMergeManifest } from './merge-upgrade.js';
 export { extractDesign } from './extract-design.js';
 export { extractEstimate } from './extract-estimate.js';
 export { buildPromotedFromSnapshot, validatePromotionSource } from './promote.js';

package/dist/projects/merge-cca.js

@@ -0,0 +1,292 @@
+/**
+ * Deterministic merge of N parallel /abap-cca assessment slices into ONE
+ * consolidated cca-assessment (the /abap-cca-merge skill's engine).
+ *
+ * WHY CODE, NOT PROSE: battery scenario S4 (docs/research/battery/
+ * s4-cca-scorecard.md, defects D6/D7) proved the model cannot keep
+ * manifest counts consistent with manifest rows when reconciling by
+ * hand — `retire: 0` next to 7 retire rows, 27/104 rows silently
+ * dropped. This module does the arithmetic; the model presents the
+ * result and adds judgment commentary, nothing else.
+ *
+ * Rules implemented (mirrors .claude/skills/abap-cca-merge/SKILL.md):
+ *   - identity: same projectId across inputs, or opts.allowCrossProject
+ *   - atcVariant must match across inputs (hard error — classifications
+ *     produced under different ATC variants are not comparable)
+ *   - scope-overlap detection: intersecting scope patterns AND duplicate
+ *     object names across inputs both produce warnings
+ *   - per-object union keyed by objectName|objectType (item ids are
+ *     PER-INPUT local — item-001 exists in every slice — so ids cannot
+ *     be the union key; merged rows are re-numbered)
+ *   - conflict rule: most-restrictive wins (retire > redesign > fix >
+ *     keep), recorded BOTH as a warning AND on the merged row
+ *     (`conflict: { values: {label: cls}, rule: 'most-restrictive' }`)
+ *   - counts RECOMPUTED from merged rows — never trusted from inputs
+ *   - truncation-aware: an input marked classificationsTruncated yields
+ *     a warning that the merge covers manifest rows only and the detail
+ *     file must be consulted for full coverage
+ */
+import { OUTPUT_ROOT } from './output-paths.js';
+/** Higher = more restrictive. Conflict resolution picks the max. */
+const RESTRICTIVENESS = {
+    retire: 3,
+    redesign: 2,
+    fix: 1,
+    keep: 0,
+};
+/**
+ * Manifest row-priority sort (matches abap-cca SKILL.md: "redesign first,
+ * then fix, then retire, then keep, ordered by confidence DESC within
+ * each group"). This is WORK priority, not restrictiveness.
+ */
+const ROW_PRIORITY = {
+    redesign: 0,
+    fix: 1,
+    retire: 2,
+    keep: 3,
+};
+const CONFIDENCE_RANK = {
+    high: 0,
+    medium: 1,
+    low: 2,
+};
+/* ── scope expression helpers ───────────────────────────────────────────── */
+/**
+ * Split a scope expression like "ZFI* + ZSD*" or "ZFI*, ZSD*" into
+ * individual patterns. Exported for tests.
+ */
+export function parseScopePatterns(scope) {
+    return scope
+        .split(/[+,]/)
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+/**
+ * Conservative intersection check for the prefix-glob patterns the
+ * --scope flag accepts (`ZFI*`, exact names). Two prefix globs intersect
+ * when one stem is a prefix of the other (`ZF*` ⊇ `ZFI*`). Patterns we
+ * cannot reason about (internal `*`) only match when identical —
+ * deliberately under-reports rather than spamming false overlaps.
+ * Exported for tests.
+ */
+export function scopePatternsIntersect(a, b) {
+    const A = a.trim().toUpperCase();
+    const B = b.trim().toUpperCase();
+    if (A === B)
+        return true;
+    const aStar = A.endsWith('*') && !A.slice(0, -1).includes('*');
+    const bStar = B.endsWith('*') && !B.slice(0, -1).includes('*');
+    const aStem = aStar ? A.slice(0, -1) : A;
+    const bStem = bStar ? B.slice(0, -1) : B;
+    if (A.includes('*') && !aStar)
+        return false; // unparseable — identical-only
+    if (B.includes('*') && !bStar)
+        return false;
+    if (aStar && bStar)
+        return aStem.startsWith(bStem) || bStem.startsWith(aStem);
+    if (aStar)
+        return B.startsWith(aStem);
+    if (bStar)
+        return A.startsWith(bStem);
+    return false; // two distinct exact names
+}
+/* ── merge ──────────────────────────────────────────────────────────────── */
+function todayUtc() {
+    return new Date().toISOString().slice(0, 10);
+}
+export function mergeCcaAssessments(inputs, opts = {}) {
+    if (inputs.length < 2) {
+        throw new Error(`cca merge requires at least 2 inputs (got ${inputs.length}) — a single assessment needs no merge`);
+    }
+    const warnings = [];
+    const first = inputs[0];
+    // ── identity validation ──
+    for (const inp of inputs.slice(1)) {
+        if (inp.content.projectId !== first.content.projectId && !opts.allowCrossProject) {
+            throw new Error(`projectId mismatch: '${inp.label}' is project '${inp.content.projectId}' but '${first.label}' is '${first.content.projectId}'. `
+                + `Merging different projects silently corrupts the estate view — pass allowCrossProject only for disjoint-scope slices of the same system.`);
+        }
+    }
+    for (const inp of inputs.slice(1)) {
+        if (inp.content.atcVariant !== first.content.atcVariant) {
+            throw new Error(`atcVariant mismatch: '${inp.label}' was classified under '${inp.content.atcVariant}' but '${first.label}' under '${first.content.atcVariant}'. `
+                + `Classifications from different ATC variants are not comparable — re-run one slice with the matching variant.`);
+        }
+    }
+    // ── scope-overlap detection (warning, not blocker) ──
+    for (let i = 0; i < inputs.length; i++) {
+        for (let j = i + 1; j < inputs.length; j++) {
+            const a = inputs[i];
+            const b = inputs[j];
+            for (const pa of parseScopePatterns(a.content.scope)) {
+                for (const pb of parseScopePatterns(b.content.scope)) {
+                    if (scopePatternsIntersect(pa, pb)) {
+                        warnings.push(`SCOPE OVERLAP: '${a.label}' scope '${pa}' intersects '${b.label}' scope '${pb}' — slices were not disjoint; duplicate objects are reconciled most-restrictive.`);
+                    }
+                }
+            }
+        }
+    }
+    // ── truncation awareness ──
+    for (const inp of inputs) {
+        if (inp.content.classificationsTruncated) {
+            const shown = inp.content.classificationsShown ?? inp.content.classifications.length;
+            const total = inp.content.classificationsTotal ?? '?';
+            warnings.push(`TRUNCATED INPUT: '${inp.label}' manifest carries only ${shown} of ${total} classifications — `
+                + `this merge covers the manifest rows only. For full coverage merge from the detail file at ${inp.content.detailPath}.`);
+        }
+    }
+    // ── per-object union (key: objectName|objectType) ──
+    const byKey = new Map();
+    const keyOrder = [];
+    for (const inp of inputs) {
+        for (const row of inp.content.classifications) {
+            const key = `${row.objectName.toUpperCase()}|${row.objectType.toUpperCase()}`;
+            if (!byKey.has(key)) {
+                byKey.set(key, []);
+                keyOrder.push(key);
+            }
+            byKey.get(key).push({
+                label: inp.label,
+                classification: row.classification,
+                confidence: row.confidence,
+                objectName: row.objectName,
+                objectType: row.objectType,
+            });
+        }
+    }
+    const mergedRows = [];
+    for (const key of keyOrder) {
+        const sources = byKey.get(key);
+        const base = sources[0];
+        const distinct = new Set(sources.map((s) => s.classification));
+        if (sources.length > 1 && distinct.size === 1) {
+            warnings.push(`DUPLICATE OBJECT: ${base.objectName} (${base.objectType}) appears in ${sources.length} inputs `
+                + `(${sources.map((s) => s.label).join(', ')}) with the same classification '${base.classification}' — overlapping slices, merged into one row.`);
+        }
+        if (distinct.size > 1) {
+            // conflict — most-restrictive wins
+            const winner = sources.reduce((best, s) => RESTRICTIVENESS[s.classification] > RESTRICTIVENESS[best.classification] ? s : best);
+            const values = {};
+            for (const s of sources)
+                values[s.label] = s.classification;
+            warnings.push(`CLASSIFICATION CONFLICT: ${base.objectName} (${base.objectType}) — `
+                + sources.map((s) => `${s.label}: ${s.classification} [${s.confidence}]`).join('; ')
+                + ` → resolved: ${winner.classification} (most-restrictive rule). Review with the consultants who classified before remediation planning.`);
+            mergedRows.push({
+                id: '', // re-numbered after sort
+                objectName: base.objectName,
+                objectType: base.objectType,
+                classification: winner.classification,
+                confidence: winner.confidence,
+                conflict: { values, rule: 'most-restrictive' },
+            });
+        }
+        else {
+            mergedRows.push({
+                id: '',
+                objectName: base.objectName,
+                objectType: base.objectType,
+                classification: base.classification,
+                confidence: base.confidence,
+            });
+        }
+    }
+    // ── manifest row-priority sort + re-number ──
+    mergedRows.sort((a, b) => {
+        const p = ROW_PRIORITY[a.classification] - ROW_PRIORITY[b.classification];
+        if (p !== 0)
+            return p;
+        const c = CONFIDENCE_RANK[a.confidence] - CONFIDENCE_RANK[b.confidence];
+        if (c !== 0)
+            return c;
+        return a.objectName.localeCompare(b.objectName);
+    });
+    mergedRows.forEach((row, i) => {
+        row.id = `item-${String(i + 1).padStart(3, '0')}`;
+    });
+    // ── counts RECOMPUTED from rows — never trusted from inputs ──
+    const tally = { keep: 0, fix: 0, retire: 0, redesign: 0 };
+    for (const row of mergedRows)
+        tally[row.classification]++;
+    // uncategorized objects have no classification rows, so they cannot be
+    // recomputed — summed across inputs (slices are disjoint by contract;
+    // overlap is already warned about above).
+    const uncategorized = inputs.reduce((sum, inp) => sum + (inp.content.summary.uncategorized || 0), 0);
+    const date = opts.mergedDate ?? todayUtc();
+    const mergedProjectId = `${first.content.projectId}_merged_${date}`;
+    const scopes = [];
+    for (const inp of inputs) {
+        const s = inp.content.scope.trim();
+        if (s.length > 0 && !scopes.includes(s))
+            scopes.push(s);
+    }
+    const merged = {
+        detailPath: `${OUTPUT_ROOT}/cca/projects/${mergedProjectId}/project.json`,
+        projectId: mergedProjectId,
+        scope: scopes.join(', '),
+        atcVariant: first.content.atcVariant,
+        summary: {
+            totalObjects: mergedRows.length + uncategorized,
+            keep: tally.keep,
+            fix: tally.fix,
+            retire: tally.retire,
+            redesign: tally.redesign,
+            uncategorized,
+        },
+        classifications: mergedRows,
+    };
+    return { merged, warnings };
+}
+/* ── manifest rendering ─────────────────────────────────────────────────── */
+/** Manifest table cap — full rows live in the merged detail data. */
+export const CCA_MANIFEST_ROW_CAP = 50;
+function renderConflictCell(conflict) {
+    const pairs = Object.entries(conflict.values)
+        .map(([label, cls]) => `${label.replace(/[|;:]/g, '_')}:${cls}`)
+        .join(';');
+    return `conflict=${pairs}`;
+}
+/**
+ * Render the EXACT `<!-- csforge:cca-manifest ... -->` block for a merged
+ * assessment. The model must paste this VERBATIM — every number is
+ * computed here, and extract-cca.ts re-validates counts-vs-rows on save,
+ * so a hand-edited block fails loudly instead of saving silently wrong.
+ *
+ * `omitDetailPath` is for the detail-write-failed path in cca_merge:
+ * a manifest must never point at a file that does not exist, so the
+ * line is dropped (the extractor then refuses the save loudly).
+ */
+export function renderCcaMergeManifest(merged, title, opts = {}) {
+    const rows = merged.classifications.slice(0, CCA_MANIFEST_ROW_CAP);
+    const truncated = merged.classifications.length > CCA_MANIFEST_ROW_CAP;
+    const lines = [
+        '<!-- csforge:cca-manifest',
+        'artefact: cca-assessment',
+        `title: ${title}`,
+        ...(opts.omitDetailPath ? [] : [`detail_path: ${merged.detailPath}`]),
+        `project_id: ${merged.projectId}`,
+        `scope: ${merged.scope}`,
+        `atc_variant: ${merged.atcVariant}`,
+        `total_objects: ${merged.summary.totalObjects}`,
+        `keep: ${merged.summary.keep}`,
+        `fix: ${merged.summary.fix}`,
+        `retire: ${merged.summary.retire}`,
+        `redesign: ${merged.summary.redesign}`,
+        `uncategorized: ${merged.summary.uncategorized}`,
+    ];
+    if (truncated) {
+        lines.push('classifications_truncated: true');
+        lines.push(`classifications_shown: ${rows.length}`);
+        lines.push(`classifications_total: ${merged.classifications.length}`);
+    }
+    lines.push('classifications:');
+    for (const row of rows) {
+        const cells = [row.id, row.objectName, row.objectType, row.classification, row.confidence];
+        if (row.conflict)
+            cells.push(renderConflictCell(row.conflict));
+        lines.push(`  ${cells.join(' | ')}`);
+    }
+    lines.push('-->');
+    return lines.join('\n');
+}

package/dist/projects/merge-upgrade.js

@@ -0,0 +1,173 @@
+/**
+ * Deterministic merge of N parallel /abap-upgrade-fix progress slices
+ * into ONE consolidated upgrade-progress (the /abap-upgrade-merge
+ * skill's engine).
+ *
+ * WHY CODE, NOT PROSE: see merge-cca.ts header — battery S4 (defects
+ * D6/D7) showed the model cannot keep counts and rows consistent when
+ * reconciling envelopes by hand. This module owns the arithmetic.
+ *
+ * Rules implemented (mirrors .claude/skills/abap-upgrade-merge/SKILL.md):
+ *   - baseline_sha256 must match across all inputs — HARD ERROR
+ *     otherwise (progress against different baselines is meaningless)
+ *   - per-finding status reconciliation, precedence:
+ *       failed > fixed > skipped > pending
+ *   - double-fix detection: same finding 'fixed' in 2+ inputs → warning
+ *   - findings in the baseline untouched by every slice → pending rows
+ *   - counts RECOMPUTED from merged rows — never trusted from inputs
+ */
+import { OUTPUT_ROOT } from './output-paths.js';
+/** Higher = wins the reconciliation. */
+const STATUS_PRECEDENCE = {
+    failed: 3,
+    fixed: 2,
+    skipped: 1,
+    pending: 0,
+};
+const VALID_STATUSES = ['fixed', 'skipped', 'failed', 'pending'];
+function todayUtc() {
+    return new Date().toISOString().slice(0, 10);
+}
+function asStatus(raw, label, findingId, warnings) {
+    if (VALID_STATUSES.includes(raw))
+        return raw;
+    warnings.push(`UNKNOWN STATUS: '${label}' reports status '${raw}' for ${findingId} — treated as 'pending'.`);
+    return 'pending';
+}
+export function mergeUpgradeProgress(inputs, baseline) {
+    if (inputs.length < 2) {
+        throw new Error(`upgrade merge requires at least 2 inputs (got ${inputs.length}) — a single progress file needs no merge`);
+    }
+    const warnings = [];
+    // ── baseline integrity — HARD ERROR on mismatch ──
+    for (const inp of inputs) {
+        if (inp.content.baselineRef.sha256 !== baseline.sha256) {
+            throw new Error(`baseline mismatch: '${inp.label}' was fixed against baseline sha256 ${inp.content.baselineRef.sha256 || '(empty)'} `
+                + `but the merge baseline is ${baseline.sha256}. Progress files from different baselines cannot be merged — `
+                + `re-run /abap-upgrade-fix against the current baseline or merge only matching slices.`);
+        }
+    }
+    // All-empty hashes pass the equality check above vacuously — that is
+    // NOT verified integrity, so say so out loud.
+    if (baseline.sha256.trim().length === 0) {
+        warnings.push('NO BASELINE HASH: no input carries a baseline_sha256 — baseline integrity is unverified. '
+            + 'The slices may have been fixed against different scans; the sha256 discipline could not be applied.');
+    }
+    const byId = new Map();
+    const idOrder = [];
+    for (const inp of inputs) {
+        for (const fix of inp.content.fixes) {
+            if (!byId.has(fix.id)) {
+                byId.set(fix.id, []);
+                idOrder.push(fix.id);
+            }
+            byId.get(fix.id).push({
+                label: inp.label,
+                status: asStatus(fix.status, inp.label, fix.id, warnings),
+                objectName: fix.objectName,
+                finding: fix.finding,
+            });
+        }
+    }
+    const mergedFixes = [];
+    for (const id of idOrder) {
+        const sources = byId.get(id);
+        const base = sources[0];
+        // data-integrity check: same finding id should reference the same object
+        const names = new Set(sources.map((s) => s.objectName.toUpperCase()));
+        if (names.size > 1) {
+            warnings.push(`ID COLLISION: ${id} maps to different objects across inputs (${sources.map((s) => `${s.label}: ${s.objectName}`).join('; ')}) `
+                + `— check that all slices came from the same scan. Keeping '${base.objectName}'.`);
+        }
+        // double-fix detection (warning, not blocker)
+        const fixers = sources.filter((s) => s.status === 'fixed');
+        if (fixers.length > 1) {
+            warnings.push(`DOUBLE-FIX: ${id} — ${base.objectName} reported 'fixed' by ${fixers.length} inputs `
+                + `(${fixers.map((s) => s.label).join(', ')}). Two devs likely claimed the same object — `
+                + `/abap-upgrade-verify will confirm which fix is active.`);
+        }
+        const winner = sources.reduce((best, s) => STATUS_PRECEDENCE[s.status] > STATUS_PRECEDENCE[best.status] ? s : best);
+        mergedFixes.push({
+            id,
+            objectName: base.objectName,
+            finding: base.finding,
+            status: winner.status,
+        });
+    }
+    // ── pending-fill: baseline findings no slice touched ──
+    if (baseline.findings) {
+        for (const f of baseline.findings) {
+            if (!byId.has(f.id)) {
+                mergedFixes.push({
+                    id: f.id,
+                    objectName: f.objectName,
+                    finding: f.finding,
+                    status: 'pending',
+                });
+            }
+        }
+    }
+    // stable order by finding id (scan order: finding-001, finding-002, ...)
+    mergedFixes.sort((a, b) => a.id.localeCompare(b.id, undefined, { numeric: true }));
+    // ── counts RECOMPUTED from rows ──
+    const tally = { fixed: 0, skipped: 0, failed: 0, pending: 0 };
+    for (const fix of mergedFixes)
+        tally[fix.status]++;
+    // ── transport: keep only when unanimous ──
+    const transports = [...new Set(inputs.map((i) => i.content.transport).filter((t) => t !== null))];
+    let transport = null;
+    if (transports.length === 1) {
+        transport = transports[0];
+    }
+    else if (transports.length > 1) {
+        warnings.push(`MULTIPLE TRANSPORTS: slices used different transports (${transports.join(', ')}) — merged progress carries no single transport; release each separately.`);
+    }
+    const baselinePath = baseline.path ?? inputs[0].content.baselineRef.path;
+    const date = baseline.mergedDate ?? todayUtc();
+    const stem = (baselinePath.split(/[\\\/]/).pop() ?? 'baseline').replace(/\.json$/i, '');
+    const merged = {
+        detailPath: `${OUTPUT_ROOT}/upgrades/${stem}_progress_merged_${date}.json`,
+        baselineRef: { path: baselinePath, sha256: baseline.sha256 },
+        transport,
+        summary: {
+            fixed: tally.fixed,
+            skipped: tally.skipped,
+            failed: tally.failed,
+            pending: tally.pending,
+        },
+        fixes: mergedFixes,
+    };
+    return { merged, warnings };
+}
+/* ── manifest rendering ─────────────────────────────────────────────────── */
+/**
+ * Render the EXACT `<!-- csforge:upgrade-manifest ... -->` block for a
+ * merged progress. The model must paste this VERBATIM — every number is
+ * computed here from the merged rows.
+ *
+ * `omitDetailPath` is for the detail-write-failed path in
+ * upgrade_merge_progress: a manifest must never point at a file that
+ * does not exist, so the line is dropped (the extractor then refuses
+ * the save loudly).
+ */
+export function renderUpgradeMergeManifest(merged, title, opts = {}) {
+    const lines = [
+        '<!-- csforge:upgrade-manifest',
+        'artefact: upgrade-progress',
+        `title: ${title}`,
+        ...(opts.omitDetailPath ? [] : [`detail_path: ${merged.detailPath}`]),
+        `baseline_path: ${merged.baselineRef.path}`,
+        `baseline_sha256: ${merged.baselineRef.sha256}`,
+        `transport: ${merged.transport ?? '-'}`,
+        `fixed: ${merged.summary.fixed}`,
+        `skipped: ${merged.summary.skipped}`,
+        `failed: ${merged.summary.failed}`,
+        `pending: ${merged.summary.pending}`,
+        'fixes:',
+    ];
+    for (const fix of merged.fixes) {
+        lines.push(`  ${[fix.id, fix.objectName, fix.finding, fix.status].join(' | ')}`);
+    }
+    lines.push('-->');
+    return lines.join('\n');
+}