@cspeach/cli 0.8.0 → 1.0.0

package/dist/projects/extract-plan.js

@@ -0,0 +1,178 @@
+import { parsePlanContent, PLAN_PHASE_STATUSES } from './plan-schema.js';
+import { computeNextPhase, isPhaseSatisfied } from './plan-run.js';
+const MANIFEST_RE = /<!--\s*csforge:plan-manifest\s*\n([\s\S]*?)\n\s*-->/g;
+// 2026-06-06 live-smoke lesson #4 (Postel): normalise model-emitted
+// `work` blocks instead of rejecting them. Models naturally write
+// `"transport": null` for "none" (schema fields are optional, NOT
+// nullable) and a structured OBJECT for notes (a design phase's
+// decision register) — both reasonable; both killed a fully correct
+// phase write-back. null -> absent; object notes -> JSON string.
+function normalizeWorkFields(p) {
+    const w = p?.work;
+    if (!w || typeof w !== 'object')
+        return;
+    for (const k of ['generated', 'transport', 'snapshot', 'notes', 'binding']) {
+        if (w[k] === null)
+            delete w[k];
+    }
+    if (w.notes !== undefined && typeof w.notes !== 'string') {
+        w.notes = JSON.stringify(w.notes);
+    }
+}
+/**
+ * Expand a compact `changed` map against the prior envelope content into a
+ * full PlanContent candidate (still Zod-validated by the caller). The
+ * dangerous failure here is silently dropping or duplicating phase content
+ * during the merge — hence: every changed key must name an existing phase,
+ * an inner `id` may not contradict its key, and the phase list is ALWAYS
+ * prior.phases mapped 1:1 (no additions, no removals, no reordering).
+ */
+function expandCompactContent(changedRaw, prior, rawStatuses) {
+    if (!prior) {
+        throw new Error('compact plan-manifest ("changed" without "content") is only valid on a resume turn — ' +
+            'no prior plan content is available to merge into; seed sessions must emit the full shape');
+    }
+    if (typeof changedRaw !== 'object' || changedRaw === null || Array.isArray(changedRaw)) {
+        throw new Error('plan-manifest "changed" must be an object map keyed by phase id');
+    }
+    const changed = changedRaw;
+    const knownIds = new Set(prior.phases.map((p) => p.id));
+    for (const [id, overlay] of Object.entries(changed)) {
+        if (!knownIds.has(id)) {
+            throw new Error(`plan-manifest changed["${id}"] references an unknown phase id; ` +
+                `known phases: ${[...knownIds].join(', ')}. ` +
+                'To add or remove phases, emit the full shape with "content" instead.');
+        }
+        if (typeof overlay !== 'object' || overlay === null || Array.isArray(overlay)) {
+            throw new Error(`plan-manifest changed["${id}"] must be an object carrying the phase's updated fields`);
+        }
+        const innerId = overlay.id;
+        if (innerId !== undefined && innerId !== id) {
+            throw new Error(`plan-manifest changed["${id}"] carries a mismatched "id": ${String(innerId)}`);
+        }
+        // Lesson-#4 parity for the overlay itself: models write `"work": null`
+        // for "nothing to record". null/undefined work means "keep prior work" —
+        // drop the key so the spread below doesn't clobber the prior phase's work.
+        if (overlay.work == null) {
+            delete overlay.work;
+        }
+        normalizeWorkFields(overlay);
+    }
+    // 1:1 map over the PRIOR phase list — changed entries overlay their phase,
+    // everything else passes through verbatim from the envelope.
+    const phases = prior.phases.map((p) => changed[p.id] !== undefined ? { ...p, ...changed[p.id], id: p.id } : p);
+    // Recompute summary CLI-side from the merged statuses (the compact shape
+    // does not carry one — fewer tokens, and it cannot drift from statuses).
+    // Invalid/missing status values are skipped here; the shared statuses
+    // validation loop in extractPlan throws the precise error afterwards.
+    const statuses = {};
+    for (const p of phases) {
+        const s = rawStatuses[p.id];
+        if (typeof s === 'string' && PLAN_PHASE_STATUSES.includes(s)) {
+            statuses[p.id] = s;
+        }
+    }
+    const next = computeNextPhase(phases, statuses);
+    const summary = {
+        total: phases.length,
+        // Waived phases (C1) count as validated here — summary.validated means
+        // "done for DAG purposes", same as the tracker header tally.
+        validated: phases.filter((p) => isPhaseSatisfied(statuses[p.id])).length,
+        blocked: phases.filter((p) => statuses[p.id] === 'blocked').length,
+        next: next?.id ?? null,
+    };
+    return { ...prior, phases, summary };
+}
+/**
+ * Parse the LAST plan-manifest block out of the skill's markdown output.
+ * `priorContent` is the validated content of the envelope being resumed —
+ * required to expand the compact shape; ignored for the full shape (seed
+ * sessions pass nothing).
+ */
+export function extractPlan(markdown, priorContent) {
+    // Last block wins — defensive against a turn emitting more than one block.
+    const re = new RegExp(MANIFEST_RE.source, MANIFEST_RE.flags);
+    let m;
+    let last = null;
+    while ((m = re.exec(markdown)) !== null)
+        last = m;
+    if (!last) {
+        throw new Error('No <!-- csforge:plan-manifest --> block found in skill output');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(last[1]);
+    }
+    catch (e) {
+        throw new Error(`plan-manifest block is not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error('plan-manifest block must be a JSON object');
+    }
+    const obj = parsed;
+    if (typeof obj.title !== 'string' || obj.title.trim().length === 0) {
+        throw new Error('plan-manifest is missing a non-empty "title"');
+    }
+    if (typeof obj.statuses !== 'object' || obj.statuses === null || Array.isArray(obj.statuses)) {
+        throw new Error('plan-manifest is missing the "statuses" object');
+    }
+    const rawStatuses = obj.statuses;
+    // Dual-shape manifests are the one silent-data-loss path: a model that
+    // copies stale `content` out of <plan_state> AND emits correct `changed`
+    // updates would persist the stale plan with no signal. Refuse loudly.
+    if (obj.content !== undefined && obj.changed !== undefined) {
+        throw new Error('plan-manifest must contain either "content" (full shape) or "changed" (compact shape), ' +
+            'not both — re-emit using exactly one');
+    }
+    let contentInput;
+    if (obj.content !== undefined) {
+        // FULL shape — Mode 1 create, plus the backward-compatible / structural-
+        // change path on resume.
+        // 2026-06-06 live-smoke lesson #2: the model cannot know the consumed
+        // spec-gap's real path/sha — that provenance lives CLI-side in the
+        // envelope's promotedFrom (threaded by the --from save flow). Models
+        // emit placeholders like {"path":"@equip","sha256":""}, and a junk
+        // provenance pointer must not cost the whole plan: strip it.
+        const rawContent = obj.content;
+        if (rawContent && typeof rawContent === 'object' && rawContent.from?.specGap) {
+            const sha = String(rawContent.from.specGap.sha256 ?? '');
+            if (!/^[0-9a-f]{64}$/.test(sha))
+                delete rawContent.from.specGap;
+        }
+        const rawPhases = rawContent?.phases;
+        if (Array.isArray(rawPhases)) {
+            for (const p of rawPhases)
+                normalizeWorkFields(p);
+        }
+        contentInput = obj.content;
+    }
+    else if (obj.changed !== undefined) {
+        // COMPACT shape (A2) — resume turns only; merged into the prior content.
+        contentInput = expandCompactContent(obj.changed, priorContent, rawStatuses);
+    }
+    else {
+        throw new Error('plan-manifest must carry either "content" (full shape) or "changed" (compact resume shape)');
+    }
+    const pc = parsePlanContent(contentInput);
+    if (!pc.ok) {
+        throw new Error(`plan-manifest content failed validation:\n  ${pc.errors.join('\n  ')}`);
+    }
+    const statuses = {};
+    for (const p of pc.content.phases) {
+        const s = rawStatuses[p.id];
+        if (typeof s !== 'string' || !PLAN_PHASE_STATUSES.includes(s)) {
+            throw new Error(`plan-manifest statuses["${p.id}"] is ${s === undefined ? 'missing' : `invalid: ${String(s)}`}; ` +
+                `allowed: ${PLAN_PHASE_STATUSES.join(', ')}`);
+        }
+        statuses[p.id] = s;
+    }
+    const items = pc.content.phases.map((p) => ({
+        id: p.id,
+        status: statuses[p.id],
+        answer: null,
+        answeredBy: null,
+        answeredAt: null,
+        comments: [],
+    }));
+    return { title: obj.title.trim(), content: pc.content, items, statuses };
+}

package/dist/projects/extract-spec-gap.js

@@ -1,15 +1,24 @@
 const TITLE_RE = /^## Spec Gap Analysis — (.+)$/m;
 const DOMAIN_RE = /^\*\*Inferred Domain:\*\*\s*(.+?)(?:\s*\[INFERRED.*?\])?$/m;
 const INPUT_TYPE_RE = /^\*\*Input Type:\*\*\s*(.+)$/m;
+const SOURCE_DOC_RE = /^\*\*Source Document:\*\*\s*(.+)$/m;
 const SECTION_HEADING_RE = /^### (.+)$/gm;
 // Real-world model output shows two formatting variants:
 //   '    1. [BLOCKER] Text'        — leading indent (4 spaces or tab), plain severity
 //   '1. **[BLOCKER]** Text'        — no indent, severity wrapped in markdown bold
 // Tolerate both: optional leading whitespace + optional `**` around the severity bracket.
 const GAP_LINE_RE = /^\s*(\d+)\.\s*(?:\*\*)?\[(BLOCKER|IMPORTANT|NICE TO KNOW)\](?:\*\*)?\s*(.+)$/m;
+// An "Options:" / "Options (multi):" line under a gap — candidate answers the
+// user can pick instead of typing. Tolerant of leading whitespace + bold.
+const OPTIONS_LINE_RE = /^\s*(?:\*\*)?Options(\s*\(multi\))?(?:\*\*)?\s*:\s*(.+)$/i;
 const AUDIENCE_BY_SECTION_NAME = {
     'missing business questions': 'business',
     'missing technical questions': 'technical',
+    // Standard-vs-Custom / fit-gap: the BA knows the standard tcode/app exists,
+    // the architect confirms the technical fit — so it's a mixed audience.
+    'fit-gap': 'mixed',
+    'standard-vs-custom': 'mixed',
+    'standard functionality': 'mixed',
     'data assumptions to confirm': 'data',
     'authorization questions': 'auth',
     'authorisation questions': 'auth',
@@ -28,6 +37,9 @@ function audienceFor(sectionName) {
 const KNOWN_GAP_SECTIONS = [
     'Missing Business Questions',
     'Missing Technical Questions',
+    'Fit-Gap', // 'Standard-vs-Custom (Fit-Gap)' — matched by substring
+    'Standard-vs-Custom',
+    'Standard Functionality',
     'Data Assumptions to Confirm',
     'Authorization Questions',
     'Authorisation Questions', // British spelling — both OK
@@ -47,6 +59,7 @@ export function extractSpecGap(markdown) {
     const title = titleMatch[1].trim();
     const inputType = (INPUT_TYPE_RE.exec(markdown)?.[1] ?? 'Unknown').trim();
     const inferredDomain = (DOMAIN_RE.exec(markdown)?.[1] ?? 'Unknown').trim();
+    const sourceDocument = SOURCE_DOC_RE.exec(markdown)?.[1].trim() || undefined;
     const sectionStarts = [];
     let m;
     const reCopy = new RegExp(SECTION_HEADING_RE.source, SECTION_HEADING_RE.flags);
@@ -84,18 +97,32 @@ export function extractSpecGap(markdown) {
     }
     return {
         title,
-        content: { inputType, inferredDomain, sections },
+        content: { inputType, inferredDomain, ...(sourceDocument ? { sourceDocument } : {}), sections },
         items,
     };
 }
 function parseGapsFromSection(sectionBody, nextId) {
     const out = [];
-    const re = new RegExp(GAP_LINE_RE.source, 'gm');
-    let m;
-    while ((m = re.exec(sectionBody)) !== null) {
-        const severity = m[2];
-        const text = m[3].trim();
-        out.push({ id: nextId(), severity, text });
+    const gapRe = new RegExp(GAP_LINE_RE.source); // per-line, no /m — exec on each line
+    let current = null;
+    for (const raw of sectionBody.split('\n')) {
+        const line = raw.replace(/\r$/, '');
+        const g = gapRe.exec(line);
+        if (g) {
+            current = { id: nextId(), severity: g[2], text: g[3].trim() };
+            out.push(current);
+            continue;
+        }
+        // An Options: line attaches its choices to the gap immediately above it.
+        const o = OPTIONS_LINE_RE.exec(line);
+        if (o && current) {
+            const opts = o[2].split('|').map((s) => s.trim()).filter((s) => s.length > 0);
+            if (opts.length > 0) {
+                current.options = opts;
+                if (o[1])
+                    current.optionsMultiSelect = true;
+            }
+        }
     }
     return out;
 }

package/dist/projects/extract-test-coverage.js

@@ -10,7 +10,7 @@
  *   <!-- csforge:test-coverage-manifest
  *   artefact: test-coverage
  *   title: ZDPR_PAYMENTS — test coverage
- *   detail_path: .abapforge/tests/zdpr-payments/project.json
+ *   detail_path: .cspeach/tests/zdpr-payments/project.json
  *   baseline_path: <project-relative path>
  *   baseline_sha256: <hex>
  *   transport: <id or ->

package/dist/projects/extract-upgrade.js

@@ -9,7 +9,7 @@
  *   <!-- csforge:upgrade-manifest
  *   artefact: upgrade-scan
  *   title: ZFI* — S/4HANA 2023 readiness
- *   detail_path: .abapforge/upgrades/zfi-readiness-2023-baseline.json
+ *   detail_path: .cspeach/upgrades/zfi-readiness-2023-baseline.json
  *   atc_variant: S4HANA_READINESS_2023
  *   scope: Z* in package ZFI*
  *   total: 2847
@@ -17,12 +17,16 @@
  *   manual_review: 136
  *   suppressed: 26
  *   findings:
- *     finding-001 | ZFI_BP_SYNC | PROG | S4HANA_BUSINESS_PARTNER | E
- *     finding-002 | ZCL_FI_DOC  | CLAS | PERF_DB_SEARCH         | W
+ *     finding-001 | ZFI_BP_SYNC | PROG | S4HANA_BUSINESS_PARTNER | E | 88 | Replace BAPI_BUPA_CREATE with I_BusinessPartner CDS
+ *     finding-002 | ZCL_FI_DOC  | CLAS | PERF_DB_SEARCH          | W | -  | Add ORDER BY PRIMARY KEY to the SELECT
  *   -->
  *
  * Key-value pairs are `key: value` per line. Tabular sections use a
  * trailing colon header (`findings:`) followed by `|`-separated rows.
+ * Findings rows are 7-column: id | object | type | rule | severity | line |
+ * message. `line` is an integer or `-` (object-level, not line-specific);
+ * `message` is a one-line description incl. the fix. Legacy 5-column rows
+ * (no line/message) still parse — the extra fields are optional.
  *
  * Three artefact types share the same parser and dispatch by `artefact:`:
  *   - upgrade-scan      → findings table
@@ -82,6 +86,13 @@ function intOr(kv, key, fallback) {
     const n = Number.parseInt(v, 10);
     return Number.isFinite(n) ? n : fallback;
 }
+function optionalInt(kv, key) {
+    const v = kv[key];
+    if (v === undefined)
+        return undefined;
+    const n = Number.parseInt(v, 10);
+    return Number.isFinite(n) ? n : undefined;
+}
 function buildItems(count, defaultStatus) {
     const out = [];
     for (let i = 0; i < count; i++) {
@@ -107,24 +118,66 @@ export function extractUpgradeScan(markdown) {
     if (!kv.detail_path) {
         throw new Error("upgrade-scan manifest missing required 'detail_path'");
     }
-    const findings = (tables.findings ?? []).map((row, i) => ({
-        id: row[0] ?? `finding-${String(i + 1).padStart(3, '0')}`,
-        objectName: row[1] ?? '',
-        objectType: row[2] ?? '',
-        rule: row[3] ?? '',
-        severity: row[4] ?? '',
-    }));
+    const findings = (tables.findings ?? []).map((row, i) => {
+        const finding = {
+            id: row[0] ?? `finding-${String(i + 1).padStart(3, '0')}`,
+            objectName: row[1] ?? '',
+            objectType: row[2] ?? '',
+            rule: row[3] ?? '',
+            severity: row[4] ?? '',
+        };
+        // line: cell 6 (row[5]); include only if a finite integer (skip '-', '', non-numeric).
+        if (row[5] !== undefined) {
+            const n = Number.parseInt(row[5], 10);
+            if (Number.isFinite(n))
+                finding.line = n;
+        }
+        // message: cells 7+ rejoined with ' | ' so a '|' inside the message survives.
+        if (row.length > 6) {
+            const message = row.slice(6).join(' | ').trim();
+            if (message.length > 0)
+                finding.message = message;
+        }
+        return finding;
+    });
+    const summary = {
+        total: intOr(kv, 'total', findings.length),
+        autoFixable: intOr(kv, 'auto_fixable', 0),
+        manualReview: intOr(kv, 'manual_review', 0),
+        suppressed: intOr(kv, 'suppressed', 0),
+    };
+    // ── D7 manifest integrity (2026-06-12) ──────────────────────────────────
+    // The scan manifest is chain input for /abap-upgrade-fix slicing and the
+    // merge's pending-fill. A `total` that disagrees with the rows means
+    // either the model truncated the table without marking it (D7) or
+    // miscounted (D6) — both corrupt downstream reconciliation, so fail the
+    // extract loudly (extract-plan loud-failure style).
+    const truncated = kv.findings_truncated === 'true';
+    const shown = optionalInt(kv, 'findings_shown');
+    if (truncated) {
+        if (shown !== undefined && shown !== findings.length) {
+            throw new Error(`upgrade-scan manifest contradiction: findings_shown is ${shown} but the table has ${findings.length} rows.`);
+        }
+        if (summary.total < findings.length) {
+            throw new Error(`upgrade-scan manifest contradiction: total (${summary.total}) is smaller than the ${findings.length} rows shown.`);
+        }
+    }
+    else if (summary.total !== findings.length) {
+        throw new Error(`upgrade-scan manifest contradiction: total is ${summary.total} but the table has ${findings.length} finding rows. `
+            + `Counts must equal rows — if the table was capped, mark it with findings_truncated: true + findings_shown.`);
+    }
     const content = {
         detailPath: kv.detail_path,
         atcVariant: kv.atc_variant ?? '',
         scope: kv.scope ?? '',
-        summary: {
-            total: intOr(kv, 'total', findings.length),
-            autoFixable: intOr(kv, 'auto_fixable', 0),
-            manualReview: intOr(kv, 'manual_review', 0),
-            suppressed: intOr(kv, 'suppressed', 0),
-        },
+        summary,
         findings,
+        ...(truncated
+            ? {
+                findingsTruncated: true,
+                ...(shown !== undefined ? { findingsShown: shown } : {}),
+            }
+            : {}),
     };
     // One InteractionItem per finding, default status 'open'.
     const items = findings.map((f) => ({
@@ -154,6 +207,49 @@ export function extractUpgradeProgress(markdown) {
         finding: row[2] ?? '',
         status: row[3] ?? 'pending',
     }));
+    const summary = {
+        fixed: intOr(kv, 'fixed', 0),
+        skipped: intOr(kv, 'skipped', 0),
+        failed: intOr(kv, 'failed', 0),
+        pending: intOr(kv, 'pending', 0),
+    };
+    // ── D6/D7 manifest integrity (2026-06-12) ───────────────────────────────
+    // Same backstop as extract-cca / the scan branch above: the progress
+    // manifest is chain input for /abap-upgrade-merge — summary counts that
+    // contradict the fixes rows corrupt the consolidated team numbers, so a
+    // contradiction fails the extract LOUDLY. Unknown statuses tally as
+    // 'pending', matching the InteractionItem coercion below.
+    const STATUSES = ['fixed', 'skipped', 'failed', 'pending'];
+    const rowTally = {
+        fixed: 0, skipped: 0, failed: 0, pending: 0,
+    };
+    for (const f of fixes) {
+        const s = STATUSES.includes(f.status)
+            ? f.status
+            : 'pending';
+        rowTally[s]++;
+    }
+    const fixesTruncated = kv.fixes_truncated === 'true';
+    const fixesShown = optionalInt(kv, 'fixes_shown');
+    if (fixesTruncated) {
+        if (fixesShown !== undefined && fixesShown !== fixes.length) {
+            throw new Error(`upgrade-progress manifest contradiction: fixes_shown is ${fixesShown} but the table has ${fixes.length} rows.`);
+        }
+        for (const s of STATUSES) {
+            if (rowTally[s] > summary[s]) {
+                throw new Error(`upgrade-progress manifest contradiction: ${rowTally[s]} '${s}' rows in the table but the summary says ${s}: ${summary[s]}. `
+                    + `Counts must cover every row even when the table is truncated.`);
+            }
+        }
+    }
+    else {
+        for (const s of STATUSES) {
+            if (rowTally[s] !== summary[s]) {
+                throw new Error(`upgrade-progress manifest contradiction: summary says ${s}: ${summary[s]} but the table has ${rowTally[s]} '${s}' rows. `
+                    + `Counts must equal rows — if the table was capped, mark it with fixes_truncated: true + fixes_shown.`);
+            }
+        }
+    }
     const content = {
         detailPath: kv.detail_path,
         baselineRef: {
@@ -161,12 +257,7 @@ export function extractUpgradeProgress(markdown) {
             sha256: kv.baseline_sha256 ?? '',
         },
         transport: kv.transport && kv.transport !== '-' ? kv.transport : null,
-        summary: {
-            fixed: intOr(kv, 'fixed', 0),
-            skipped: intOr(kv, 'skipped', 0),
-            failed: intOr(kv, 'failed', 0),
-            pending: intOr(kv, 'pending', 0),
-        },
+        summary,
         fixes,
     };
     const items = fixes.map((f) => {

package/dist/projects/index.js

@@ -1,7 +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, isPhaseSatisfied } 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';