@cspeach/cli 0.8.0 → 1.0.0

package/dist/projects/plan-run.js

@@ -0,0 +1,254 @@
+// 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'];
+/**
+ * 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.
+ */
+export function isPhaseSatisfied(s) {
+    return s === 'validated' || s === 'validated-with-waiver';
+}
+/**
+ * Phase status lives in interaction.items (store convention). Build the
+ * id→status map; a phase with no matching item defaults to 'todo' rather
+ * than failing — the envelope passed top-level validation, so a missing
+ * item is a seeding gap, not corruption.
+ */
+export function statusesFromItems(items, phases) {
+    const byId = new Map(items.map((it) => [it.id, it.status]));
+    const out = {};
+    for (const p of phases)
+        out[p.id] = byId.get(p.id) ?? 'todo';
+    return out;
+}
+/**
+ * The next phase a resume session should execute: first phase (in the
+ * bottom-up `phases[]` order) that is not yet terminal AND whose
+ * entryCriteria are all 'validated'. In-progress statuses (a prior
+ * session died mid-phase) qualify the same as 'todo' — the phase is
+ * re-entered from the top, gates and grounding included.
+ */
+export function computeNextPhase(phases, statuses) {
+    for (const p of phases) {
+        const s = statuses[p.id] ?? 'todo';
+        if (isPhaseSatisfied(s) || s === 'blocked')
+            continue;
+        if (s !== 'todo' && !IN_PROGRESS.includes(s))
+            continue;
+        if (p.entryCriteria.every((dep) => isPhaseSatisfied(statuses[dep])))
+            return p;
+    }
+    return null;
+}
+/**
+ * Plan-progress board printed before and after every resume turn (and by
+ * `--status` for plan envelopes). Plain text — flows through chunkEmitter
+ * in Ink mode and console.log in classic mode alike.
+ *
+ *   ─ Plan: HR Dayforce Extract (v3) ── 2/7 validated ─
+ *     ✔ c1.types          abap-data-model  → ZDOM_DAYF_STATUS (S4HK903412)
+ *     ▶ c1.orchestration  abap-generate    ← THIS SESSION
+ *     ○ c1.integration    abap-generate    (needs c1.orchestration)
+ */
+// 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);
+}
+/**
+ * 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;
+    // Waived phases count as done in the header tally — the DAG treats them as
+    // satisfied; the per-line "✓* (waived)" marker carries the distinction.
+    const validated = a.content.phases.filter((p) => isPhaseSatisfied(a.statuses[p.id])).length;
+    if (a.includeHeader !== false) {
+        lines.push(chalk.dim(`─ ${a.title} (v${a.version}) · ${validated}/${total} done ─`));
+        lines.push('');
+    }
+    for (const p of a.content.phases) {
+        const s = a.statuses[p.id] ?? 'todo';
+        const isCurrent = a.currentId != null && p.id === a.currentId;
+        const title = phaseTitle(p);
+        const detail = phaseDetail(p, s);
+        const dash = detail ? ` — ${detail}` : '';
+        if (s === 'validated') {
+            lines.push(chalk.dim(`  ☒ ${title}${dash}`));
+        }
+        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)')}`);
+        }
+        else if (s === 'blocked') {
+            lines.push(`  ${chalk.red('☐')} ${chalk.red(title)} ${chalk.red('— blocked')}${detail ? chalk.dim(` · ${detail}`) : ''}`);
+        }
+        else if (isCurrent) {
+            lines.push(`  ${chalk.hex(PEACH)('☐')} ${chalk.bold(title)}${dash}  ${chalk.hex(PEACH).bold('◀ now')}`);
+        }
+        else if (IN_PROGRESS.includes(s)) {
+            lines.push(`  ${chalk.hex(PEACH)('☐')} ${chalk.bold(title)}${dash}  ${chalk.dim(`(${s})`)}`);
+        }
+        else {
+            lines.push(`  ☐ ${title}${chalk.dim(dash)}`);
+        }
+    }
+    return lines.join('\n');
+}
+/* ── 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.'];
+    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.');
+    }
+    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
+ * manifest block a resume turn emitted.
+ *
+ * Invariants preserved:
+ *  - id / createdAt / createdBy / title / source / promotedFrom unchanged
+ *    (the extract's title is intentionally IGNORED — title drift would
+ *    break the multi-file same-source detection in status.ts)
+ *  - history is append-only; version === history.length stays true
+ *  - item comments / answers added via the editor survive the revision —
+ *    only the status comes from the new extract
+ */
+export function buildPlanRevision(original, extract, author, nowIso) {
+    if (original.artefactType !== 'plan') {
+        throw new Error(`buildPlanRevision expects a plan envelope, got ${original.artefactType}`);
+    }
+    const oldItems = new Map(original.interaction.items.map((it) => [it.id, it]));
+    const mergedItems = extract.items.map((ni) => {
+        const old = oldItems.get(ni.id);
+        return old ? { ...old, status: ni.status } : ni;
+    });
+    const oldStatuses = statusesFromItems(original.interaction.items, original.content.phases);
+    const diffs = [];
+    for (const p of extract.content.phases) {
+        const before = oldStatuses[p.id] ?? 'todo';
+        const after = extract.statuses[p.id];
+        if (before !== after)
+            diffs.push(`${p.id}: ${before} → ${after}`);
+    }
+    const summary = diffs.length > 0 ? diffs.join('; ') : 'resume run — no phase status change';
+    return {
+        ...original,
+        lastEditedAt: nowIso,
+        lastEditedBy: author,
+        version: original.version + 1,
+        content: extract.content,
+        interaction: { items: mergedItems },
+        history: [...original.history, { at: nowIso, by: author, action: 'edited', summary }],
+    };
+}

package/dist/projects/plan-schema.js

@@ -0,0 +1,210 @@
+// cspeach-cli/src/projects/plan-schema.ts
+//
+// Deep validation for the 'plan' artefact content (/abap-plan envelope).
+//
+// Split of responsibilities, matching the rest of the store:
+//   - validate.ts      — top-level envelope shape, hand-rolled (adds 'plan'
+//                        to its known types + status enum; content is opaque)
+//   - plan-schema.ts   — Zod schema for the PlanContent payload, invoked by
+//                        the --resume path before any phase is executed
+//
+// The TS interfaces live in types.ts with the other content shapes; the
+// `z.ZodType<PlanContent>` annotation below keeps schema and interface in
+// lockstep at compile time.
+import { z } from 'zod';
+/** Keep in sync with PlanLayer in types.ts. */
+export const PLAN_LAYERS = [
+    'types', 'persistence', 'data-model', 'behavior', 'service',
+    'orchestration', 'integration', 'ui',
+];
+/**
+ * Existing skills a phase may delegate to. Keep in sync with
+ * PlanDelegateSkill in types.ts. Extending = one entry here + one in the
+ * union there. Typical per-layer defaults (guidance lives in the
+ * abap-plan SKILL.md, not enforced here):
+ *   types/persistence → abap-data-model
+ *   data-model/behavior/service → abap-rap (abap-eml for handler logic)
+ *   orchestration/integration → abap-generate (abap-segw for ECC OData)
+ */
+export const PLAN_DELEGATE_SKILLS = [
+    'abap-design', 'abap-data-model', 'abap-rap', 'abap-eml',
+    'abap-generate', 'abap-segw', 'abap-test', 'abap-fiori-build',
+    'abap-extend-model',
+];
+/**
+ * Keep in sync with ItemStatusByType['plan'] in types.ts.
+ * 'validated-with-waiver' (C1, 2026-06-11): the exit gate was NOT met but the
+ * user explicitly waived it — DAG eligibility treats it like 'validated'
+ * (see isPhaseSatisfied in plan-run.ts).
+ */
+export const PLAN_PHASE_STATUSES = [
+    'todo', 'designing', 'building', 'verifying', 'validated', 'validated-with-waiver', 'blocked',
+];
+const SHA256_RE = /^[0-9a-f]{64}$/;
+const planPhaseManifestSchema = z.object({
+    reads: z.array(z.string()),
+    rules: z.array(z.string()),
+    writesBack: z.array(z.string()),
+});
+// .passthrough(): live smoke showed models enrich `work` with valuable
+// extras (blockedReason, unblockPath, groundingChecks) — strip mode was
+// silently discarding them from the persisted envelope.
+const planPhaseWorkSchema = z.object({
+    generated: z.array(z.string()).optional(),
+    transport: z.string().optional(),
+    snapshot: z.string().optional(),
+    notes: z.string().optional(),
+    // C2 (D24): exact SRVB name for the plan-complete /abap-fiori-build chain.
+    binding: z.string().optional(),
+}).passthrough();
+const planPhaseSchema = z.object({
+    id: z.string().min(1),
+    // C2 (D29): optional short human name for the tracker board; old envelopes
+    // without it still parse and render via the layer/delegate label fallback.
+    title: z.string().min(1).optional(),
+    component: z.string().min(1),
+    layer: z.enum(PLAN_LAYERS),
+    entryCriteria: z.array(z.string()),
+    delegateTo: z.enum(PLAN_DELEGATE_SKILLS),
+    manifest: planPhaseManifestSchema,
+    exitGate: z.string().min(1),
+    approval: z.boolean().optional(),
+    work: planPhaseWorkSchema.optional(),
+});
+/**
+ * Validates the discovered live stack for a revision plan (RevisionTarget in
+ * types.ts). All layer fields are optional/nullable — a partial stack (e.g.
+ * a table view with no MDE) is valid. Only `anchor`, `uiKind`, and `binding`
+ * are required shape — layers is always an object but all its members are opt.
+ */
+const revisionTargetSchema = z
+    .object({
+    anchor: z.string().min(1),
+    uiKind: z.enum(['fiori-elements', 'freestyle', 'none']),
+    binding: z.string().nullable(),
+    // C2 (2026-06-26): freestyle app on-disk location (see types.ts). Additive
+    // and optional; the superRefine below makes it mandatory ONLY for freestyle.
+    app: z.object({ dir: z.string().min(1) }).optional(),
+    layers: z.object({
+        table: z.string().nullable().optional(),
+        interfaceView: z.string().nullable().optional(),
+        projectionView: z.string().nullable().optional(),
+        bdef: z.string().nullable().optional(),
+        behaviorPool: z.string().nullable().optional(),
+        mde: z.string().nullable().optional(),
+        serviceDef: z.string().nullable().optional(),
+    }),
+})
+    .superRefine((rev, ctx) => {
+    // A freestyle revision must record where the app lives on disk, or the
+    // ui-phase delegation to /abap-fiori-build amend has no appDir to amend.
+    if (rev.uiKind === 'freestyle' && !rev.app) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['app'],
+            message: 'uiKind "freestyle" requires `revision.app.dir` (the freestyle app location for amend)',
+        });
+    }
+});
+// Input type is `unknown` (third param): the `.default({})` on `from` means
+// the schema ACCEPTS input without the key while still OUTPUTTING PlanContent.
+export const planContentSchema = z
+    .object({
+    project: z.object({
+        goal: z.string().min(1),
+        source: z.string(),
+        target: z.string(),
+        // Absent mode parses as undefined (treated as 'create') — back-compat.
+        mode: z.enum(['create', 'revision']).optional(),
+    }),
+    // Tolerant by lesson (2026-06-06 live smoke): the model omitted the whole
+    // `from` key for a goal-only plan and the strict schema killed the save.
+    // Missing `from` normalises to {} — only the inner specGap ref is shaped.
+    from: z
+        .object({
+        specGap: z
+            .object({
+            path: z.string().min(1),
+            sha256: z.string().regex(SHA256_RE, 'must be a lowercase hex sha256'),
+        })
+            .optional(),
+    })
+        .default({}),
+    // Present when project.mode='revision'. Optional here; the superRefine
+    // below enforces the cross-field rule: mode='revision' requires revision.
+    revision: revisionTargetSchema.optional(),
+    phases: z.array(planPhaseSchema).min(1),
+    summary: z.object({
+        total: z.number().int().nonnegative(),
+        validated: z.number().int().nonnegative(),
+        blocked: z.number().int().nonnegative(),
+        next: z.string().nullable(),
+    }),
+})
+    .superRefine((content, ctx) => {
+    // mode:'revision' requires a revision target map (the discovered live stack).
+    // Absent mode is treated as 'create' — this check is a no-op in that case.
+    if (content.project.mode === 'revision' && !content.revision) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['revision'],
+            message: 'mode "revision" requires a `revision` target map (discovered live stack)',
+        });
+    }
+    // Phase ids must be unique, and entryCriteria may only reference phases
+    // EARLIER in the array. Bottom-up ordering by construction — this is what
+    // guarantees resume is deterministic and the dependency graph acyclic
+    // (a forward or self reference can never form, so no cycle can either).
+    const seen = new Set();
+    content.phases.forEach((p, i) => {
+        if (seen.has(p.id)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['phases', i, 'id'],
+                message: `Duplicate phase id: ${p.id}`,
+            });
+        }
+        p.entryCriteria.forEach((dep, j) => {
+            if (!seen.has(dep)) {
+                const known = content.phases.some((q) => q.id === dep);
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ['phases', i, 'entryCriteria', j],
+                    message: known
+                        ? `entryCriteria '${dep}' must reference an earlier phase (plans are ordered bottom-up)`
+                        : `entryCriteria references unknown phase: ${dep}`,
+                });
+            }
+        });
+        seen.add(p.id);
+    });
+    if (content.summary.total !== content.phases.length) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['summary', 'total'],
+            message: `summary.total (${content.summary.total}) must equal phases.length (${content.phases.length})`,
+        });
+    }
+    if (content.summary.next !== null && !seen.has(content.summary.next)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['summary', 'next'],
+            message: `summary.next references unknown phase: ${content.summary.next}`,
+        });
+    }
+});
+/**
+ * Validate an unknown value as PlanContent. Returns flattened, path-prefixed
+ * error strings suitable for printing directly in the REPL — the --resume
+ * command bails on the first failed parse rather than executing a phase
+ * against a malformed plan.
+ */
+export function parsePlanContent(input) {
+    const r = planContentSchema.safeParse(input);
+    if (r.success)
+        return { ok: true, content: r.data };
+    return {
+        ok: false,
+        errors: r.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`),
+    };
+}

package/dist/projects/promote-command.js

@@ -1,5 +1,5 @@
 import { readProjectFile } from './status.js';
-import { buildPromotedFromSnapshot, validatePromotionSource } from './promote.js';
+import { buildPromotedFromSnapshot, buildReviewDecisionsBlock, buildDetailPathHint, validatePromotionSource } from './promote.js';
 import { resolveAtTokenAsync, formatProjectFileList } from './workspace.js';
 /**
  * Per-skill predecessor map. v0.7 admits multi-source via array values —
@@ -18,6 +18,7 @@ const PREDECESSOR_BY_TARGET = {
     'abap-upgrade-verify': 'upgrade-progress',
     'abap-modernize': 'cca-assessment', // v0.7: new chain
     'abap-test': 'cca-assessment', // v0.7: new chain
+    'abap-plan': 'spec-gap', // B3: plan consumes answered gaps
 };
 function affirmative(reply) {
     const v = reply.trim().toLowerCase();
@@ -91,6 +92,29 @@ export async function runPromoteCommand(args) {
         }
     }
     const promotedFrom = await buildPromotedFromSnapshot(env);
-    const extendedSkillInput = buildExtendedInput(promotedFrom);
+    let extendedSkillInput = buildExtendedInput(promotedFrom);
+    // Always hand the skill the source detail-file path so it reads the baseline
+    // directly (the envelope at .cspeach/ root is unreadable; glob skips .cspeach/).
+    // This is what makes `--from` actually work for upgrade-fix on any scan,
+    // triaged or not — without it the skill globs for the file and fails.
+    const detailHint = buildDetailPathHint(env);
+    if (detailHint) {
+        extendedSkillInput = `${extendedSkillInput}\n\n${detailHint}`;
+    }
+    // When the source is a triaged upgrade-scan envelope, append a dedicated
+    // "Review decisions (honor these)" block joining each finding's status with
+    // its objectName/line/rule. This drives /abap-upgrade-fix off the viewer
+    // triage instead of re-asking object-by-object. Returns null (and we append
+    // nothing) for non-upgrade-scan sources or fully-untriaged scans.
+    const reviewBlock = buildReviewDecisionsBlock(env);
+    if (reviewBlock) {
+        extendedSkillInput = `${extendedSkillInput}\n\n${reviewBlock}`;
+    }
+    // Carry the originating spec document into the handoff so the downstream
+    // skill (e.g. /abap-plan) can cite the running spec the answered gaps trace
+    // back to — the Word/PDF doc → spec-gap → plan thread stays visible.
+    if (env.artefactType === 'spec-gap' && env.content.sourceDocument) {
+        extendedSkillInput = `${extendedSkillInput}\n\nSource spec document: ${env.content.sourceDocument}`;
+    }
     return { promotedFrom, extendedSkillInput };
 }

package/dist/projects/promote.js

@@ -67,6 +67,134 @@ export async function buildPromotedFromSnapshot(source) {
         snapshot: { items },
     };
 }
+/**
+ * Build the compact "Review decisions" block for an upgrade-scan source.
+ *
+ * The viewer lets the user triage each finding to one of
+ * `open | auto-fix | manual | suppress` (stored in `interaction.items[].status`).
+ * Those decisions must DRIVE /abap-upgrade-fix instead of the skill re-asking
+ * object-by-object. The skill cannot file_read the root `.cspeach/<name>.json`
+ * envelope (denylisted), so the statuses must reach it via the `--from`
+ * prompt injection — this block is what the CLI appends to that injection.
+ *
+ * Joins each item's status with the matching `content.findings[]` row
+ * (objectName / line / rule) and renders one aligned line per finding,
+ * e.g.:
+ *   finding-001  ZFI_DUNNING_SELECT  line 52  SELECT_WO_ORDER_BY  → auto-fix
+ *
+ * Returns `null` when the source is not an upgrade-scan, or when every
+ * finding is still `open` (untriaged — nothing to honor; the skill falls
+ * back to its existing interactive ask for all of them).
+ */
+export function buildReviewDecisionsBlock(source) {
+    if (source.artefactType === 'upgrade-scan')
+        return buildUpgradeScanDecisions(source);
+    if (source.artefactType === 'cca-assessment')
+        return buildCcaDecisions(source);
+    return null;
+}
+/**
+ * Always-inject hint for any `--from` source that carries a `content.detailPath`
+ * (upgrade-scan/progress/report, cca-assessment, modernize-result, test-coverage).
+ *
+ * Why this is REQUIRED, not optional: the `.cspeach.json` envelope itself lives at
+ * the denylisted `.cspeach/` root and cannot be read by the skill, and `glob` skips
+ * `.cspeach/` — so without an explicit path the skill hunts for the baseline and
+ * fails (observed live 2026-06-16: `/abap-upgrade-fix --from` globbing endlessly).
+ * The detail file lives under `.cspeach/<domain>/`, which the filesystem carve-out
+ * makes readable — so we hand the skill that exact path to `file_read` directly.
+ */
+export function buildDetailPathHint(source) {
+    const detailPath = source.content?.detailPath;
+    if (!detailPath)
+        return null;
+    return [
+        'Source detail file — READ THIS DIRECTLY with file_read at the exact path below.',
+        'Do NOT glob for it, and do NOT try to read the .cspeach.json envelope (that path',
+        'is protected). The detail file holds the full per-finding data (object, line,',
+        'rule, message, successor) and is readable under .cspeach/:',
+        `  ${detailPath}`,
+    ].join('\n');
+}
+/**
+ * Render a fixed-width "Review decisions (honor these)" table from already-built
+ * rows. `summary` is the one-line counts header; `countKeys` lists the decision
+ * tokens to tally (in display order). Shared by the upgrade-scan and
+ * cca-assessment branches so both render identically.
+ */
+function renderDecisionRows(rows, countKeys, summaryLabel) {
+    const wId = Math.max(...rows.map((r) => r.id.length));
+    const wObj = Math.max(...rows.map((r) => r.objectName.length));
+    const wLine = Math.max(...rows.map((r) => r.line.length));
+    const wRule = Math.max(...rows.map((r) => r.rule.length));
+    const counts = {};
+    for (const k of countKeys)
+        counts[k] = 0;
+    for (const r of rows)
+        counts[r.status] = (counts[r.status] ?? 0) + 1;
+    const summary = countKeys.map((k) => `${counts[k]} ${k}`).join(', ');
+    const lines = [
+        'Review decisions from the source envelope (honor these):',
+        `  ${summaryLabel}: ${summary}.`,
+        '',
+    ];
+    for (const r of rows) {
+        const parts = [
+            r.id.padEnd(wId),
+            r.objectName.padEnd(wObj),
+            r.line.padEnd(wLine),
+            r.rule.padEnd(wRule),
+            `→ ${r.status}`,
+        ];
+        // Collapse the run of spaces from an empty (line-less) column so we never
+        // emit a stray "line undefined"; padEnd of "" already keeps alignment.
+        lines.push(`  ${parts.join('  ').replace(/\s+$/, '')}`);
+    }
+    return lines.join('\n');
+}
+function buildUpgradeScanDecisions(source) {
+    const items = source.interaction.items;
+    if (items.length === 0)
+        return null;
+    // Untriaged source (all open) → omit the block; nothing was decided.
+    if (items.every((it) => it.status === 'open'))
+        return null;
+    const findingById = new Map(source.content.findings.map((f) => [f.id, f]));
+    const rows = items.map((it) => {
+        const f = findingById.get(it.id);
+        return {
+            id: it.id,
+            objectName: f?.objectName ?? '<unknown>',
+            line: f?.line !== undefined ? `line ${f.line}` : '',
+            rule: f?.rule ?? '',
+            status: it.status,
+        };
+    });
+    return renderDecisionRows(rows, ['auto-fix', 'suppress', 'manual', 'open'], 'Applying your review')
+        // The upgrade-scan summary historically reads "... K still open"; keep that
+        // wording for the open bucket while the shared renderer emits "K open".
+        .replace(/(\d+) open\./, '$1 still open.');
+}
+/**
+ * cca-assessment: the per-object review decision is the `classification`
+ * (keep/fix/retire/redesign) the consultant assigned in the worksheet, carried
+ * in content.classifications[]. interaction.items[].status is the triage
+ * lifecycle (open/reviewed/classified/archived), not the fix decision — so we
+ * surface the classification as the decision token the skill must honor.
+ */
+function buildCcaDecisions(source) {
+    const classifications = source.content.classifications;
+    if (!classifications || classifications.length === 0)
+        return null;
+    const rows = classifications.map((c) => ({
+        id: c.id,
+        objectName: c.objectName,
+        line: '',
+        rule: c.objectType ?? '',
+        status: c.classification,
+    }));
+    return renderDecisionRows(rows, ['fix', 'redesign', 'retire', 'keep'], 'Applying your assessment');
+}
 export function validatePromotionSource(source, expectedPredecessor) {
     // v0.7 — accept either a single predecessor or an array (multi-source).
     // /abap-upgrade-fix accepts both upgrade-scan AND cca-assessment, etc.