@cspeach/cli 0.9.0 → 1.1.0

package/dist/tools/fiori/types.js

@@ -0,0 +1 @@
+export {};

package/dist/tools/local-build.js

@@ -0,0 +1,86 @@
+// cspeach-cli/src/tools/local-build.ts
+/**
+ * Startup wiring for the persisted `local_build` config toggle (2026-06-13,
+ * renamed + broadened from `local_files`).
+ *
+ * When the effective toggle is on (see config/loader.ts resolveLocalBuild —
+ * `local_build ?? local_files` for backward compat), the otherwise flag-gated
+ * LOCAL BUILD tools are force-enabled via the in-memory override in `_flag.ts`,
+ * BEFORE the first listTools()/turn. The enable set is now:
+ *
+ *   filesystem: file_read, file_write, file_edit, glob, grep
+ *   shell:      shell_exec
+ *   fiori:      fiori_scaffold, fiori_apply, fiori_list, fiori_deploy_config,
+ *               fiori_scaffold_fe, fiori_fe_extend, fiori_render_smoke,
+ *               fiori_sample_search, fiori_sample_get
+ *   extend:     extend_model_insert (anchored CDS/DDLX edit — abap-extend-model)
+ *   subagent:   agent_run (Task 7, 2026-07-03 — customers get subagent
+ *               dispatch when local_build is on; plan phases force its
+ *               read-only tool filter regardless of the model's args)
+ *
+ * This is what makes /abap-fiori-build runnable end to end — it writes local
+ * app files (FS tools), runs safelisted build CLIs (shell), AND scaffolds /
+ * composes the app via the built-in Fiori engine (fiori_* tools). The fiori_*
+ * tools replace the old repo-only `pnpm fiori scaffold` path so shipped-binary
+ * customers get the same deterministic engine output without pnpm or the repo.
+ *
+ * The toggle is PERSISTED (config.toml), not re-consented each session, so
+ * `applyLocalBuildConfig` returns an announce line the entry point prints
+ * whenever the tools are live — the user must always see that local file access
+ * AND command execution are on this session (trust-visibility requirement).
+ *
+ * The blast radius is honestly named: the announce line surfaces the cwd (where
+ * read/write/edit operate) AND the shell safelist (which commands shell_exec may
+ * run). The FS tools' own cwd-sandbox (writes confined to the project root;
+ * .cspeach/.env/.git denylisted) and shell_exec's argv-only safelist enforcement
+ * still apply regardless of this toggle — enabling shell_exec only makes it
+ * visible, it does NOT make it unrestricted.
+ */
+import { enableToolFlags } from './_flag.js';
+// Source-of-truth for the shell safelist names surfaced in the announce line.
+// Imported (not hand-copied) so the announce can never drift from the actual
+// commands shell_exec permits. If shell_exec's DEFAULT_SAFELIST changes, this
+// announce string follows automatically.
+import { DEFAULT_SAFELIST } from './_command-shared.js';
+/**
+ * The exact tool NAMEs the flag uses (file_read → CSPEACH_TOOL_FILE_READ,
+ * shell_exec → CSPEACH_TOOL_SHELL_EXEC). `shell_exec` matches the tool's
+ * registered name in tools/shell/shell_exec.ts, so isToolFlagOn('shell_exec')
+ * checks the same override key enableToolFlags(['shell_exec']) sets.
+ */
+export const LOCAL_BUILD_TOOLS = [
+    'file_read',
+    'read_document',
+    'file_write',
+    'file_edit',
+    'glob',
+    'grep',
+    'shell_exec',
+    'fiori_scaffold',
+    'fiori_apply',
+    'fiori_list',
+    'fiori_deploy_config',
+    'fiori_scaffold_fe',
+    'fiori_fe_extend',
+    'fiori_render_smoke',
+    'fiori_sample_search',
+    'fiori_sample_get',
+    'extend_model_insert',
+    'system_capability',
+    'agent_run',
+];
+/**
+ * Apply the persisted `local_build` toggle. When on, force-enables the FS +
+ * shell build tools and returns a one-line announce string (undefined when off,
+ * so the caller prints nothing). `cwd` is surfaced so the user sees exactly
+ * which directory tree read/write/edit operate under; the shell safelist is
+ * surfaced so the user sees which commands shell_exec may run.
+ */
+export function applyLocalBuildConfig(localBuild, cwd) {
+    if (localBuild !== true)
+        return undefined;
+    enableToolFlags([...LOCAL_BUILD_TOOLS]);
+    const safelist = [...DEFAULT_SAFELIST].join(', ');
+    return (`local build tools enabled — file read/write/edit under ${cwd} ` +
+        `+ safelisted commands (${safelist}) — cspeach config set local_build off to disable`);
+}

package/dist/tools/local-files.js

@@ -0,0 +1,31 @@
+// cspeach-cli/src/tools/local-files.ts
+/**
+ * Startup wiring for the persisted `local_files` config toggle.
+ *
+ * When `cfg.local_files === true`, the otherwise flag-gated filesystem tools
+ * (file_read/file_write/file_edit/glob/grep) are force-enabled via the
+ * in-memory override in `_flag.ts`, BEFORE the first listTools()/turn. This is
+ * what makes /abap-fiori-build runnable — it writes local app files.
+ *
+ * The toggle is PERSISTED (config.toml), not re-consented each session, so
+ * `applyLocalFilesConfig` returns an announce line the entry point prints
+ * whenever the tools are live — the user must always see that local file
+ * access is on this session (trust-visibility requirement). The FS tools'
+ * own cwd-sandbox (writes confined to the project root; .cspeach/.env/.git
+ * denylisted) still applies regardless of this toggle.
+ */
+import { enableToolFlags } from './_flag.js';
+/** The exact tool NAMEs the flag uses (file_read → CSPEACH_TOOL_FILE_READ). */
+export const LOCAL_FILE_TOOLS = ['file_read', 'file_write', 'file_edit', 'glob', 'grep'];
+/**
+ * Apply the persisted `local_files` toggle. When on, force-enables the FS
+ * tools and returns a one-line announce string (undefined when off, so the
+ * caller prints nothing). `cwd` is surfaced so the user sees exactly which
+ * directory tree read/write/edit operate under.
+ */
+export function applyLocalFilesConfig(localFiles, cwd) {
+    if (localFiles !== true)
+        return undefined;
+    enableToolFlags([...LOCAL_FILE_TOOLS]);
+    return `local file tools enabled (read/write/edit under ${cwd}) — cspeach config set local_files off to disable`;
+}

package/dist/tools/project/_merge-shared.js

@@ -0,0 +1,68 @@
+/**
+ * Shared input-resolution for the two merge tools (cca_merge,
+ * upgrade_merge_progress).
+ *
+ * Inputs arrive as the same `@<token>` forms the rest of the CLI uses
+ * (workspace.ts:resolveAtToken): absolute path, relative path, or a bare
+ * workspace-filename fragment. A leading '@' is stripped — skills pass
+ * the user's `--inputs @file` tokens through verbatim.
+ *
+ * Absolute / relative paths are resolved WITHOUT touching the workspace
+ * (no ensureWorkspace side effects from a tool call); only bare tokens
+ * trigger the workspace lookup.
+ */
+import { basename, isAbsolute, join } from 'node:path';
+import { readProjectFile } from '../../projects/status.js';
+import { resolveAtTokenAsync, formatProjectFileList } from '../../projects/workspace.js';
+export function labelFor(path) {
+    return basename(path).replace(/\.cspeach\.json$/i, '');
+}
+/**
+ * Resolve one `@<token>` to an absolute path. Throws with a
+ * user-presentable message on ambiguity / not-found.
+ */
+export async function resolveEnvelopeToken(rawToken, cwd) {
+    const token = rawToken.startsWith('@') ? rawToken.slice(1) : rawToken;
+    if (token.length === 0)
+        throw new Error('empty input token');
+    if (isAbsolute(token))
+        return token;
+    if (token.includes('/') || token.includes('\\'))
+        return join(cwd, token);
+    const resolved = await resolveAtTokenAsync(token, cwd);
+    if (resolved.kind === 'path')
+        return resolved.path;
+    if (resolved.kind === 'ambiguous') {
+        throw new Error(`'@${token}' matches multiple workspace files — be more specific:\n`
+            + formatProjectFileList(resolved.matches, '(workspace)'));
+    }
+    throw new Error(`'@${token}' matches no file in the workspace (${resolved.workspace})`);
+}
+/**
+ * Resolve + read + type-check one envelope input. readProjectFile
+ * already validates the envelope schema and throws readable errors.
+ */
+export async function loadEnvelope(rawToken, cwd, expectedType) {
+    const path = await resolveEnvelopeToken(rawToken, cwd);
+    let envelope;
+    try {
+        envelope = readProjectFile(path);
+    }
+    catch (e) {
+        throw new Error(`cannot read '${rawToken}': ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (envelope.artefactType !== expectedType) {
+        throw new Error(`'${rawToken}' is a '${envelope.artefactType}' envelope — this merge needs '${expectedType}' inputs.`);
+    }
+    return { path, label: labelFor(path), envelope };
+}
+/**
+ * The presentation contract returned to the model alongside the merged
+ * numbers. Keeping the model away from arithmetic is the whole point
+ * (battery S4 defects D6/D7) — it presents, it does not recompute.
+ */
+export const MANIFEST_PASTE_INSTRUCTIONS = 'Present merged_summary, per_input and warnings to the user with your own judgment commentary '
+    + '(conflict arbitration advice, next steps). Then paste manifest_block VERBATIM — unchanged, '
+    + 'byte for byte — as the LAST block of your reply so the CLI save hook can persist the merged '
+    + 'envelope. Do NOT recompute, reformat, re-sort, or edit any number or row in the block: the '
+    + 'extractor re-validates counts against rows on save and a hand-edited block fails loudly.';

package/dist/tools/project/cca_merge.js

@@ -0,0 +1,164 @@
+/**
+ * cca_merge — deterministic reconciliation of N parallel /abap-cca
+ * assessment envelopes (the /abap-cca-merge skill's execution seam).
+ *
+ * DESIGN (2026-06-12, team-chain): the skill used to ask the MODEL to
+ * reconcile envelopes by hand; battery S4 (D6/D7) proved models can't
+ * keep counts consistent with rows. This tool runs
+ * src/projects/merge-cca.ts and returns the merged content, warnings,
+ * AND a pre-rendered manifest block the model pastes VERBATIM. The
+ * normal save hook then persists the envelope — persistence
+ * deliberately stays on the one existing save path (confirm prompt,
+ * workspace resolution, validation, version semantics) instead of the
+ * tool minting envelopes through a second door. A merge is a NEW
+ * artefact superseding its inputs (new identity is correct — there is
+ * no prior chain to extend, unlike the plan-revision case in
+ * save-command.ts), and the extractor's counts-vs-rows validation acts
+ * as a tamper backstop if the model edits the pasted block.
+ *
+ * NOT flag-gated: the abap-cca-merge skill depends on this tool; gating
+ * it off would silently break the multi-consultant chain.
+ *
+ * Stays isMutating: false despite writing the merged detail file: the
+ * write is the merge's own local artifact under .cspeach/ (derived
+ * purely from envelopes the user supplied), the same trust level as the
+ * save hook persisting the envelope — no SAP or user-file mutation.
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join } from 'node:path';
+import { registerTool } from '../index.js';
+import { mergeCcaAssessments, renderCcaMergeManifest, } from '../../projects/merge-cca.js';
+import { loadEnvelope, MANIFEST_PASTE_INSTRUCTIONS } from './_merge-shared.js';
+export async function ccaMergeHandler(args, ctx) {
+    if (!Array.isArray(args.inputs) || args.inputs.some((i) => typeof i !== 'string')) {
+        return { content: 'error: inputs must be an array of envelope paths / @-tokens.', is_error: true };
+    }
+    const tokens = args.inputs;
+    if (tokens.length === 1) {
+        return {
+            content: 'error: only one input supplied — a single assessment needs no merge. Use the file directly.',
+            is_error: true,
+        };
+    }
+    if (tokens.length < 2) {
+        return { content: 'error: at least 2 input envelopes are required.', is_error: true };
+    }
+    if (args.allow_cross_project !== undefined && typeof args.allow_cross_project !== 'boolean') {
+        return { content: 'error: allow_cross_project must be a boolean.', is_error: true };
+    }
+    // load + type-check every input before merging — fail with the precise file
+    const inputs = [];
+    const perInput = [];
+    for (const token of tokens) {
+        let resolved;
+        try {
+            resolved = await loadEnvelope(token, ctx.cwd, 'cca-assessment');
+        }
+        catch (e) {
+            return { content: `error: ${e instanceof Error ? e.message : String(e)}`, is_error: true };
+        }
+        const content = resolved.envelope.content;
+        inputs.push({ label: resolved.label, content });
+        perInput.push({
+            file: resolved.path,
+            label: resolved.label,
+            project_id: content.projectId,
+            scope: content.scope,
+            total_objects: content.summary.totalObjects,
+            keep: content.summary.keep,
+            fix: content.summary.fix,
+            retire: content.summary.retire,
+            redesign: content.summary.redesign,
+            uncategorized: content.summary.uncategorized,
+            truncated: content.classificationsTruncated === true,
+        });
+    }
+    let merged;
+    let warnings;
+    try {
+        ({ merged, warnings } = mergeCcaAssessments(inputs, {
+            allowCrossProject: args.allow_cross_project === true,
+        }));
+    }
+    catch (e) {
+        return { content: `error: ${e instanceof Error ? e.message : String(e)}`, is_error: true };
+    }
+    const title = `${inputs[0].content.projectId} — Merged (${inputs.length} slices)`;
+    // ── write the merged detail file BEFORE emitting the manifest ──────────
+    // The manifest's detail_path must point at a REAL file (the rule this
+    // branch added for /abap-cca emitters applies to the merge too). The
+    // manifest table caps at 50 rows; this file always carries every merged
+    // row. Minimal documented shape (a merge supersedes its inputs, so this
+    // is a fresh consolidated detail, not a phase-state project.json):
+    //   {
+    //     generatedAt:  ISO timestamp of the merge
+    //     projectId / scope / atcVariant / summary: as in the manifest
+    //     objects:      ALL merged classification rows (uncapped)
+    //     mergedFrom:   the input envelopes [{ file, label }]
+    //   }
+    let detailWritten = true;
+    const detailAbs = isAbsolute(merged.detailPath) ? merged.detailPath : join(ctx.cwd, merged.detailPath);
+    try {
+        mkdirSync(dirname(detailAbs), { recursive: true });
+        writeFileSync(detailAbs, JSON.stringify({
+            generatedAt: new Date().toISOString(),
+            projectId: merged.projectId,
+            scope: merged.scope,
+            atcVariant: merged.atcVariant,
+            summary: merged.summary,
+            objects: merged.classifications,
+            mergedFrom: perInput.map((p) => ({ file: p.file, label: p.label })),
+        }, null, 2), 'utf8');
+    }
+    catch (e) {
+        detailWritten = false;
+        warnings.push(`DETAIL WRITE FAILED: could not write the merged detail file '${merged.detailPath}' `
+            + `(${e instanceof Error ? e.message : String(e)}). The manifest block omits detail_path — `
+            + `a manifest must never point at a file that does not exist — so the save will refuse it. `
+            + `Fix the path/permissions and re-run the merge.`);
+    }
+    const manifestBlock = renderCcaMergeManifest(merged, title, { omitDetailPath: !detailWritten });
+    return {
+        content: JSON.stringify({
+            merged_summary: merged.summary,
+            merged_project_id: merged.projectId,
+            merged_scope: merged.scope,
+            atc_variant: merged.atcVariant,
+            ...(detailWritten ? { detail_path: merged.detailPath } : {}),
+            per_input: perInput,
+            warnings,
+            // full merged rows — the manifest block caps at 50; nothing is lost
+            // from the transcript even for large estates.
+            merged_classifications: merged.classifications,
+            manifest_block: manifestBlock,
+            instructions: MANIFEST_PASTE_INSTRUCTIONS,
+        }, null, 2),
+    };
+}
+registerTool({
+    name: 'cca_merge',
+    description: 'Deterministically merge 2+ parallel /abap-cca assessment envelopes (.cspeach.json) into one consolidated '
+        + 'cca-assessment. Validates project identity and ATC variant, detects scope overlaps and classification '
+        + 'conflicts (most-restrictive wins: retire > redesign > fix > keep), recomputes all counts from the merged '
+        + 'rows, writes the full merged rows to a new detail file under .cspeach/cca/projects/, and returns warnings '
+        + 'plus a ready-made csforge:cca-manifest block to paste verbatim. '
+        + 'Inputs accept absolute/relative paths or bare workspace @-tokens.',
+    isMutating: false,
+    category: 'project',
+    input_schema: {
+        type: 'object',
+        properties: {
+            inputs: {
+                type: 'array',
+                items: { type: 'string' },
+                description: '2+ cca-assessment envelope references (path or @-token), one per consultant slice.',
+            },
+            allow_cross_project: {
+                type: 'boolean',
+                description: 'Accept inputs with different projectId (disjoint --scope slices of the same system). Default false.',
+            },
+        },
+        required: ['inputs'],
+    },
+    handler: (args, ctx) => ccaMergeHandler(args, ctx),
+});

package/dist/tools/project/playbook_get.js

@@ -4,7 +4,7 @@
  * Fetches a SKILL.md body via ctx.skillSource (the managed / manifest /
  * bundled SkillSource abstraction the agent loop already uses). Lets the
  * agent inspect another skill's playbook for orchestration patterns
- * (e.g. /abap-incident calling /abap-dump-analyze inline) without
+ * (e.g. /abap-incident calling /abap-dump inline) without
  * triggering a full skill dispatch.
  *
  * Caching: in-process Map-based LRU. Keyed by validated skill name.

package/dist/tools/project/upgrade_merge_progress.js

@@ -0,0 +1,206 @@
+/**
+ * upgrade_merge_progress — deterministic reconciliation of N parallel
+ * /abap-upgrade-fix progress envelopes (the /abap-upgrade-merge skill's
+ * execution seam). See cca_merge.ts for the design rationale: the tool
+ * does the arithmetic (battery S4 D6/D7), the model presents; the
+ * pre-rendered manifest block is pasted verbatim and persisted by the
+ * normal save hook.
+ *
+ * Baseline discipline:
+ *   - every input's baselineRef.sha256 must match the merge baseline —
+ *     HARD ERROR otherwise.
+ *   - `baseline` arg (recommended): the originating upgrade-scan
+ *     envelope. The tool hashes the scan's detail file (that is what
+ *     baseline_sha256 refers to, per the upgrade-fix manifest contract)
+ *     and uses the scan's findings to fill never-touched findings as
+ *     'pending', so the merged view covers the whole baseline.
+ *   - without `baseline`, the first input's baselineRef is taken as
+ *     truth and the others are checked against it; untouched baseline
+ *     findings cannot be filled in (warned).
+ *
+ * NOT flag-gated: the abap-upgrade-merge skill depends on this tool.
+ *
+ * Stays isMutating: false despite writing the merged detail file: the
+ * write is the merge's own local artifact under .cspeach/ (derived
+ * purely from envelopes the user supplied), the same trust level as the
+ * save hook persisting the envelope — no SAP or user-file mutation.
+ */
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join } from 'node:path';
+import { registerTool } from '../index.js';
+import { mergeUpgradeProgress, renderUpgradeMergeManifest, } from '../../projects/merge-upgrade.js';
+import { loadEnvelope, MANIFEST_PASTE_INSTRUCTIONS } from './_merge-shared.js';
+function sha256OfFile(path) {
+    return createHash('sha256').update(readFileSync(path)).digest('hex');
+}
+export async function upgradeMergeProgressHandler(args, ctx) {
+    if (!Array.isArray(args.inputs) || args.inputs.some((i) => typeof i !== 'string')) {
+        return { content: 'error: inputs must be an array of envelope paths / @-tokens.', is_error: true };
+    }
+    const tokens = args.inputs;
+    if (tokens.length === 1) {
+        return {
+            content: 'error: only one input supplied — a single progress file needs no merge. Use the file directly.',
+            is_error: true,
+        };
+    }
+    if (tokens.length < 2) {
+        return { content: 'error: at least 2 input envelopes are required.', is_error: true };
+    }
+    if (args.baseline !== undefined && typeof args.baseline !== 'string') {
+        return { content: 'error: baseline must be a string (upgrade-scan envelope path / @-token).', is_error: true };
+    }
+    const inputs = [];
+    const perInput = [];
+    for (const token of tokens) {
+        let resolved;
+        try {
+            resolved = await loadEnvelope(token, ctx.cwd, 'upgrade-progress');
+        }
+        catch (e) {
+            return { content: `error: ${e instanceof Error ? e.message : String(e)}`, is_error: true };
+        }
+        const content = resolved.envelope.content;
+        inputs.push({ label: resolved.label, content });
+        perInput.push({
+            file: resolved.path,
+            label: resolved.label,
+            baseline_sha256: content.baselineRef.sha256,
+            transport: content.transport,
+            fixed: content.summary.fixed,
+            skipped: content.summary.skipped,
+            failed: content.summary.failed,
+            pending: content.summary.pending,
+        });
+    }
+    const extraWarnings = [];
+    let baseline;
+    let title;
+    if (typeof args.baseline === 'string') {
+        let scan;
+        try {
+            scan = await loadEnvelope(args.baseline, ctx.cwd, 'upgrade-scan');
+        }
+        catch (e) {
+            return { content: `error: ${e instanceof Error ? e.message : String(e)}`, is_error: true };
+        }
+        const scanContent = scan.envelope.content;
+        // baseline_sha256 is the sha256 of the baseline DETAIL JSON body (the
+        // upgrade-fix manifest contract), not of the envelope.
+        const detailAbs = isAbsolute(scanContent.detailPath)
+            ? scanContent.detailPath
+            : join(ctx.cwd, scanContent.detailPath);
+        let sha256;
+        try {
+            sha256 = sha256OfFile(detailAbs);
+        }
+        catch (e) {
+            return {
+                content: `error: cannot hash baseline detail file '${scanContent.detailPath}' (resolved: ${detailAbs}): `
+                    + `${e instanceof Error ? e.message : String(e)}. The merge needs the scan's detail JSON on this machine.`,
+                is_error: true,
+            };
+        }
+        baseline = {
+            sha256,
+            path: scanContent.detailPath,
+            title: scan.envelope.title,
+            findings: scanContent.findings.map((f) => ({ id: f.id, objectName: f.objectName, finding: f.rule })),
+        };
+        title = `${scan.envelope.title} — Merged (${inputs.length} slices)`;
+        if (scanContent.findingsTruncated) {
+            extraWarnings.push(`TRUNCATED BASELINE: the scan manifest carries only ${scanContent.findingsShown ?? scanContent.findings.length} `
+                + `of ${scanContent.summary.total} findings — pending-fill covers the manifest rows only.`);
+        }
+    }
+    else {
+        const ref = inputs[0].content.baselineRef;
+        baseline = { sha256: ref.sha256, path: ref.path };
+        title = `${ref.path.split(/[\\\/]/).pop() ?? 'baseline'} — Merged (${inputs.length} slices)`;
+        extraWarnings.push('NO EXPLICIT BASELINE: consistency was checked against the first input\'s baselineRef. '
+            + 'Findings untouched by every slice are NOT filled as pending — pass the upgrade-scan envelope '
+            + 'as `baseline` for full-baseline coverage.');
+    }
+    let merged;
+    let warnings;
+    try {
+        ({ merged, warnings } = mergeUpgradeProgress(inputs, baseline));
+    }
+    catch (e) {
+        return { content: `error: ${e instanceof Error ? e.message : String(e)}`, is_error: true };
+    }
+    warnings = [...extraWarnings, ...warnings];
+    // ── write the merged detail file BEFORE emitting the manifest ──────────
+    // The manifest's detail_path must point at a REAL file. Minimal
+    // documented shape (full merged rows, never capped):
+    //   {
+    //     generatedAt: ISO timestamp of the merge
+    //     baseline / transport / summary: as in the manifest
+    //     fixes:      ALL merged per-finding rows
+    //     mergedFrom: the input envelopes [{ file, label }]
+    //   }
+    let detailWritten = true;
+    const mergedDetailAbs = isAbsolute(merged.detailPath) ? merged.detailPath : join(ctx.cwd, merged.detailPath);
+    try {
+        mkdirSync(dirname(mergedDetailAbs), { recursive: true });
+        writeFileSync(mergedDetailAbs, JSON.stringify({
+            generatedAt: new Date().toISOString(),
+            baseline: { path: merged.baselineRef.path, sha256: merged.baselineRef.sha256 },
+            transport: merged.transport,
+            summary: merged.summary,
+            fixes: merged.fixes,
+            mergedFrom: perInput.map((p) => ({ file: p.file, label: p.label })),
+        }, null, 2), 'utf8');
+    }
+    catch (e) {
+        detailWritten = false;
+        warnings.push(`DETAIL WRITE FAILED: could not write the merged detail file '${merged.detailPath}' `
+            + `(${e instanceof Error ? e.message : String(e)}). The manifest block omits detail_path — `
+            + `a manifest must never point at a file that does not exist — so the save will refuse it. `
+            + `Fix the path/permissions and re-run the merge.`);
+    }
+    const manifestBlock = renderUpgradeMergeManifest(merged, title, { omitDetailPath: !detailWritten });
+    return {
+        content: JSON.stringify({
+            merged_summary: merged.summary,
+            baseline: { path: merged.baselineRef.path, sha256: merged.baselineRef.sha256 },
+            transport: merged.transport,
+            ...(detailWritten ? { detail_path: merged.detailPath } : {}),
+            per_input: perInput,
+            warnings,
+            merged_fixes: merged.fixes,
+            manifest_block: manifestBlock,
+            instructions: MANIFEST_PASTE_INSTRUCTIONS,
+        }, null, 2),
+    };
+}
+registerTool({
+    name: 'upgrade_merge_progress',
+    description: 'Deterministically merge 2+ parallel /abap-upgrade-fix progress envelopes (.cspeach.json) into one consolidated '
+        + 'upgrade-progress. Hard-errors on baseline_sha256 mismatch, reconciles per-finding status '
+        + '(failed > fixed > skipped > pending), warns on double-fixes, recomputes all counts from the merged rows, '
+        + 'writes the full merged rows to a new detail file under .cspeach/upgrades/, '
+        + 'and returns warnings plus a ready-made csforge:upgrade-manifest block to paste verbatim. '
+        + 'Pass the originating upgrade-scan envelope as `baseline` (recommended) to fill never-touched findings as pending. '
+        + 'Inputs accept absolute/relative paths or bare workspace @-tokens.',
+    isMutating: false,
+    category: 'project',
+    input_schema: {
+        type: 'object',
+        properties: {
+            inputs: {
+                type: 'array',
+                items: { type: 'string' },
+                description: '2+ upgrade-progress envelope references (path or @-token), one per developer slice.',
+            },
+            baseline: {
+                type: 'string',
+                description: 'Optional but recommended: the originating upgrade-scan envelope (path or @-token). '
+                    + 'Used to verify baseline integrity from source and to fill untouched findings as pending.',
+            },
+        },
+        required: ['inputs'],
+    },
+    handler: (args, ctx) => upgradeMergeProgressHandler(args, ctx),
+});