@cspeach/cli 0.9.0 → 1.0.0

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');
+}

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;
+}