@cspeach/cli 0.8.0 → 1.0.0

package/dist/projects/save-command.js

@@ -1,3 +1,5 @@
+import { readdirSync } from 'node:fs';
+import { join } from 'node:path';
 import { extractSpecGap } from './extract-spec-gap.js';
 import { extractDesign } from './extract-design.js';
 import { extractEstimate } from './extract-estimate.js';
@@ -5,10 +7,15 @@ import { extractUpgradeScan, extractUpgradeProgress, extractUpgradeReport } from
 import { extractCcaAssessment } from './extract-cca.js';
 import { extractModernizeResult } from './extract-modernize.js';
 import { extractTestCoverage } from './extract-test-coverage.js';
+import { extractPlan } from './extract-plan.js';
 import { buildEnvelope } from './build.js';
+import { buildPlanRevision } from './plan-run.js';
+import { parsePlanContent } from './plan-schema.js';
+import { validateEnvelope } from './validate.js';
+import { readProjectFile } from './status.js';
 import { saveProject } from './save.js';
 import { renderEmailTemplate } from './email-template.js';
-import { ensureWorkspace } from './workspace.js';
+import { ensureWorkspace, resolveWorkspacePath } from './workspace.js';
 const SKILL_REGISTRY = {
     'abap-spec-gap': {
         artefactType: 'spec-gap',
@@ -29,16 +36,19 @@ const SKILL_REGISTRY = {
         artefactType: 'upgrade-scan',
         extract: (md) => extractUpgradeScan(md),
         itemNoun: 'findings',
+        manifestMarker: 'csforge:upgrade-manifest',
     },
     'abap-upgrade-fix': {
         artefactType: 'upgrade-progress',
         extract: (md) => extractUpgradeProgress(md),
         itemNoun: 'fixes',
+        manifestMarker: 'csforge:upgrade-manifest',
     },
     'abap-upgrade-verify': {
         artefactType: 'upgrade-report',
         extract: (md) => extractUpgradeReport(md),
         itemNoun: 'regressions',
+        manifestMarker: 'csforge:upgrade-manifest',
     },
     'abap-upgrade-merge': {
         // Merge produces a NEW upgrade-progress (consolidated) — same shape
@@ -46,11 +56,13 @@ const SKILL_REGISTRY = {
         artefactType: 'upgrade-progress',
         extract: (md) => extractUpgradeProgress(md),
         itemNoun: 'fixes',
+        manifestMarker: 'csforge:upgrade-manifest',
     },
     'abap-cca': {
         artefactType: 'cca-assessment',
         extract: (md) => extractCcaAssessment(md),
         itemNoun: 'classifications',
+        manifestMarker: 'csforge:cca-manifest',
     },
     'abap-cca-merge': {
         // Merge produces a NEW cca-assessment (consolidated) — same shape as
@@ -58,49 +70,277 @@ const SKILL_REGISTRY = {
         artefactType: 'cca-assessment',
         extract: (md) => extractCcaAssessment(md),
         itemNoun: 'classifications',
+        manifestMarker: 'csforge:cca-manifest',
     },
     'abap-modernize': {
         artefactType: 'modernize-result',
         extract: (md) => extractModernizeResult(md),
         itemNoun: 'modernizations',
+        manifestMarker: 'csforge:modernize-manifest',
     },
     'abap-test': {
         artefactType: 'test-coverage',
         extract: (md) => extractTestCoverage(md),
         itemNoun: 'tests',
+        manifestMarker: 'csforge:test-coverage-manifest',
+    },
+    'abap-plan': {
+        // 2026-06-06 B3: Mode 1 (create) save. Mode 2 (--resume) turns
+        // suppress this hook (RunTurnParams.suppressSaveHook) and persist a
+        // REVISION of the existing envelope via commands/plan-resume.ts.
+        // C1 (2026-06-11, D30): this generic path ALSO builds a revision when a
+        // prior envelope with the same title exists in the workspace — a steered
+        // "save the project file" must never fork a new identity off an existing
+        // version chain (the 49dd duplicate). The dispatch in runSaveCommand
+        // special-cases artefactType 'plan'; this `extract` is the no-prior
+        // fallback shape only.
+        artefactType: 'plan',
+        extract: (md) => extractPlan(md),
+        itemNoun: 'phases',
+        manifestMarker: 'csforge:plan-manifest',
     },
 };
+/**
+ * C1 (2026-06-11, defect D22) — map an inline artifact-manifest block in the
+ * assistant output to the SKILL_REGISTRY key that knows how to extract it.
+ * Used by the post-turn save hook (agent/loop.ts:maybeOfferSave) as the
+ * fallback trigger when the routed-skill LABEL would not fire: a misrouted
+ * turn that still emitted a recognizable manifest must not silently lose the
+ * artifact. Returns null when no recognizable manifest is present (prose-only
+ * artefacts — spec-gap / design / estimate — have no inline marker and stay
+ * label-triggered).
+ *
+ * The upgrade marker is shared by three artefact shapes; the `artefact:` line
+ * inside the block disambiguates which extractor (registry skill) applies.
+ */
+export function detectArtifactSkill(markdown) {
+    if (/<!--\s*csforge:plan-manifest\b/.test(markdown))
+        return 'abap-plan';
+    if (/<!--\s*csforge:cca-manifest\b/.test(markdown))
+        return 'abap-cca';
+    if (/<!--\s*csforge:modernize-manifest\b/.test(markdown))
+        return 'abap-modernize';
+    if (/<!--\s*csforge:test-coverage-manifest\b/.test(markdown))
+        return 'abap-test';
+    const up = /<!--\s*csforge:upgrade-manifest\s*\n([\s\S]*?)\n\s*-->/.exec(markdown);
+    if (up) {
+        const art = /(?:^|\n)\s*artefact:\s*(\S+)/.exec(up[1] ?? '');
+        switch (art?.[1]) {
+            case 'upgrade-scan': return 'abap-upgrade-scan';
+            case 'upgrade-progress': return 'abap-upgrade-fix';
+            case 'upgrade-report': return 'abap-upgrade-verify';
+            default: return null; // marker present, artefact unknown — extractor would reject it anyway
+        }
+    }
+    return null;
+}
+// Same block grammar as extract-plan.ts:MANIFEST_RE (last block wins).
+const PLAN_MANIFEST_RE = /<!--\s*csforge:plan-manifest\s*\n([\s\S]*?)\n\s*-->/g;
+/**
+ * Cheap title peek into the LAST plan-manifest block — needed BEFORE the full
+ * extract because compact manifests can only be expanded against the prior
+ * envelope, and the prior envelope is found by title. Returns null on any
+ * malformation (the full extract then reports the precise error).
+ */
+export function peekPlanManifestTitle(markdown) {
+    const re = new RegExp(PLAN_MANIFEST_RE.source, PLAN_MANIFEST_RE.flags);
+    let m;
+    let last = null;
+    while ((m = re.exec(markdown)) !== null)
+        last = m;
+    if (!last)
+        return null;
+    try {
+        const parsed = JSON.parse(last[1]);
+        return typeof parsed.title === 'string' && parsed.title.trim().length > 0
+            ? parsed.title.trim()
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * C1 (2026-06-11, defect D30 — the 49dd duplicate) — find the existing plan
+ * envelope a generic save should REVISE instead of forking a new identity.
+ *
+ * Match key: artefactType 'plan' + same title (trimmed, case-insensitive —
+ * the title is model-emitted and may drift in casing). Among matches the
+ * HIGHEST version wins (lastEditedAt breaks ties); when a past duplicate
+ * already split the family into two ids, this picks the longer (real) chain,
+ * so subsequent saves heal onto it instead of extending the fork.
+ *
+ * Non-recursive scan of `dir` (the workspace folder where saves land);
+ * unreadable/invalid files are skipped — resolution is best-effort, never
+ * fatal to the save.
+ */
+export function resolvePriorPlanEnvelope(title, dir) {
+    if (!title)
+        return null;
+    const want = title.trim().toLowerCase();
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return null;
+    }
+    let best = null;
+    for (const name of names) {
+        if (!name.endsWith('.cspeach.json'))
+            continue;
+        const full = join(dir, name);
+        let env;
+        try {
+            env = readProjectFile(full);
+        }
+        catch {
+            continue;
+        }
+        if (env.artefactType !== 'plan')
+            continue;
+        if (env.title.trim().toLowerCase() !== want)
+            continue;
+        if (!best
+            || env.version > best.envelope.version
+            || (env.version === best.envelope.version && env.lastEditedAt > best.envelope.lastEditedAt)) {
+            best = { path: full, envelope: env };
+        }
+    }
+    return best;
+}
 export async function runSaveCommand(args) {
     const spec = SKILL_REGISTRY[args.skillName];
     if (!spec)
         return null;
+    // C1 (D30): a plan save must continue an existing version chain when one is
+    // resolvable. The prior is found by manifest title BEFORE extraction, both
+    // to decide new-vs-revision and because a COMPACT manifest (statuses +
+    // changed map) can only be expanded against the prior content. The scan is
+    // strictly READ-ONLY (resolveWorkspacePath, not ensureWorkspace): nothing
+    // before the user's confirm may mkdir the workspace or touch .gitignore as
+    // a side effect — a missing workspace dir simply means no prior
+    // (resolvePriorPlanEnvelope treats an unreadable dir as "no matches").
+    let prior = null;
+    let priorContent;
+    if (spec.artefactType === 'plan') {
+        const peekedTitle = peekPlanManifestTitle(args.skillOutput);
+        if (peekedTitle) {
+            let scanDir;
+            try {
+                scanDir = await resolveWorkspacePath();
+            }
+            catch {
+                scanDir = args.cwd;
+            }
+            prior = resolvePriorPlanEnvelope(peekedTitle, scanDir);
+            if (prior) {
+                const pc = parsePlanContent(prior.envelope.content);
+                if (pc.ok) {
+                    priorContent = pc.content;
+                }
+                else {
+                    // Prior exists but its content no longer parses — revising it would
+                    // propagate corruption. Fall back to a fresh envelope and say so.
+                    args.log(`[save] existing plan '${prior.envelope.title}' has invalid content (${pc.errors[0] ?? 'schema error'}) — saving a NEW envelope instead of a revision.`);
+                    prior = null;
+                }
+            }
+        }
+    }
     let extract;
+    let planExtract = null;
     try {
-        extract = spec.extract(args.skillOutput);
+        if (spec.artefactType === 'plan') {
+            planExtract = extractPlan(args.skillOutput, priorContent);
+            extract = planExtract;
+        }
+        else {
+            extract = spec.extract(args.skillOutput);
+        }
     }
-    catch {
+    catch (e) {
+        // C1 residual D22 — the label IS in the registry but WRONG for the output
+        // (e.g. a plan manifest under an 'abap-design' label): the label's
+        // extractor throws, and bailing here would silently lose an artifact that
+        // carries a complete, recognizable manifest. If the manifest resolves to
+        // a DIFFERENT registry skill, retry the save under that skill. Skipped
+        // when both skills share the same manifest-marker family (abap-cca-merge
+        // ↔ abap-cca, abap-upgrade-merge ↔ abap-upgrade-fix): the family
+        // extractor already ran and failed, and re-dispatching would only launder
+        // merge provenance onto the non-merge skill — keep the label's failure.
+        const detected = detectArtifactSkill(args.skillOutput);
+        if (detected && detected !== args.skillName) {
+            const detectedSpec = SKILL_REGISTRY[detected];
+            const sameFamily = detectedSpec?.manifestMarker !== undefined
+                && detectedSpec.manifestMarker === spec.manifestMarker;
+            if (detectedSpec && !sameFamily) {
+                args.log(`[save] output is a ${detected} artifact, not ${args.skillName} — saving as ${detected}`);
+                // Recursion is bounded: if the retry's extract fails too, the
+                // re-detected skill equals args.skillName and we fall through to the
+                // loud-failure path below instead of recursing again.
+                return runSaveCommand({ ...args, skillName: detected });
+            }
+        }
+        if (spec.manifestMarker && args.skillOutput.includes(spec.manifestMarker)) {
+            args.log('');
+            args.log(`[save] ${args.skillName}: a ${spec.manifestMarker} block IS present but failed to parse — artefact NOT saved.`);
+            args.log(`[save] ${e instanceof Error ? e.message : String(e)}`);
+            args.log(`[save] The output above is otherwise complete — re-run the skill or report this as a manifest bug.`);
+        }
         return null;
     }
+    // C1 review fix — name the revision target BEFORE the confirm so the user
+    // knows what a 'y' will do. Log line only, deliberately NOT a second
+    // question: the B5 headless contract (below) allows at most one prompt.
+    if (planExtract && prior) {
+        const priorFilename = prior.path.split(/[\\\/]/).pop();
+        args.log(`[save] this will save as v${prior.envelope.version + 1} of existing plan '${prior.envelope.title}' (${priorFilename})`);
+    }
+    // CONTRACT (B5): runSaveCommand may ask the user at most ONE question —
+    // this save confirm. The headless path in loop.ts (maybeOfferSave) installs
+    // a prompt that blanket-answers 'y' to WHATEVER it is asked; any second
+    // question added here would silently receive 'y' too. If you need another
+    // prompt, give maybeOfferSave's headless prompt a question-aware answer
+    // first.
     const answer = (await args.prompt('Save as project file? [y/N]: ')).trim().toLowerCase();
     if (answer !== 'y' && answer !== 'yes')
         return null;
-    const env = buildEnvelope({
-        artefactType: spec.artefactType,
-        extract,
-        author: args.author,
-        source: {
-            skill: args.skillName,
-            skillVersion: args.skillVersion,
-            input: args.skillInput,
-            tokensUsed: args.tokensUsed,
-            model: args.model,
-        },
-        promotedFrom: args.promotedFrom ?? null,
-    });
-    // Save into the workspace folder (~/CSPeach by default), not cwd. Falls
-    // back to args.cwd if the workspace can't be created (e.g. permission
-    // error on the home directory) — saving SOMEWHERE is better than losing
-    // the artefact.
+    let env;
+    if (planExtract && prior) {
+        // C1 (D30) — the 49dd duplicate: the generic save used to mint a fresh
+        // envelope id even when the same plan already lived in the workspace,
+        // forking the version chain. With a resolvable prior, the save IS a
+        // revision: same id, version+1, history appended (buildPlanRevision —
+        // the exact path /abap-plan --resume persistence uses).
+        env = buildPlanRevision(prior.envelope, planExtract, args.author, new Date().toISOString());
+        // JSON round-trip simulates disk serialization for the validator.
+        const check = validateEnvelope(JSON.parse(JSON.stringify(env)));
+        if (!check.ok) {
+            args.log(`[save] plan revision failed validation (${check.error.message}) — artefact NOT saved.`);
+            return null;
+        }
+    }
+    else {
+        env = buildEnvelope({
+            artefactType: spec.artefactType,
+            extract,
+            author: args.author,
+            source: {
+                skill: args.skillName,
+                skillVersion: args.skillVersion,
+                input: args.skillInput,
+                tokensUsed: args.tokensUsed,
+                model: args.model,
+            },
+            promotedFrom: args.promotedFrom ?? null,
+        });
+    }
+    // Saves land in the workspace folder, not cwd — created only NOW, after
+    // the user confirmed (declined saves and conversational turns leave no
+    // mkdir/.gitignore side effects). Falls back to args.cwd if the workspace
+    // can't be created (e.g. permission error on the home directory) — saving
+    // SOMEWHERE is better than losing the artefact.
     let outDir;
     try {
         outDir = await ensureWorkspace();
@@ -110,6 +350,9 @@ export async function runSaveCommand(args) {
     }
     const path = await saveProject(env, { cwd: outDir });
     args.log(`Saved: ${path}`);
+    if (planExtract && prior) {
+        args.log(`(revision v${env.version} of the existing plan — version chain preserved, no new id)`);
+    }
     args.log(`Share at: https://cspeach.dev/edit`);
     args.log('');
     args.log(renderEmailTemplate({

package/dist/projects/status.js

@@ -1,6 +1,7 @@
 import { readFileSync } from 'node:fs';
 import { validateEnvelope } from './validate.js';
 import { canonicalSha256 } from './canonicalize.js';
+import { statusesFromItems, computeNextPhase, renderPlanTracker } from './plan-run.js';
 export function readProjectFile(path) {
     const raw = readFileSync(path, 'utf8');
     let parsed;
@@ -22,6 +23,7 @@ const STATUS_BY_TYPE = {
     'estimate': ['confirmed', 'disputed', 'deferred'],
     'cca': ['keep', 'fix', 'retire', 'redesign'],
     'incident': ['pending', 'done'],
+    'plan': ['validated', 'validated-with-waiver', 'todo', 'designing', 'building', 'verifying', 'blocked'],
 };
 const PRIMARY_BY_TYPE = {
     'spec-gap': 'answered',
@@ -29,6 +31,7 @@ const PRIMARY_BY_TYPE = {
     'estimate': 'confirmed',
     'cca': 'keep',
     'incident': 'done',
+    'plan': 'validated',
 };
 const PROMOTE_HINT_BY_TYPE = {
     'spec-gap': '/abap-design --from',
@@ -36,6 +39,7 @@ const PROMOTE_HINT_BY_TYPE = {
     'estimate': null,
     'cca': null,
     'incident': null,
+    'plan': '/abap-plan --resume',
 };
 export function renderStatus(env) {
     const items = env.interaction.items;
@@ -85,6 +89,22 @@ export function renderStatus(env) {
             lines.push(`  ... ${stillOpen.length - 10} more`);
         lines.push('');
     }
+    // B3 (2026-06-06): plan envelopes get the phase tracker board — the same
+    // renderer the --resume flow prints before/after each phase. Header off:
+    // title + version were already printed above.
+    if (env.artefactType === 'plan') {
+        const content = env.content;
+        const statuses = statusesFromItems(items, content.phases);
+        lines.push(renderPlanTracker({
+            title: env.title,
+            version: env.version,
+            content,
+            statuses,
+            currentId: computeNextPhase(content.phases, statuses)?.id ?? null,
+            includeHeader: false,
+        }));
+        lines.push('');
+    }
     // Promote hint fires whenever a "next phase" exists for this artefactType.
     // Unlike the v1 implementation we no longer gate on `primaryCount > 0` —
     // a design with zero `keep` items (all `redesign` / `defer`) is still a
@@ -100,6 +120,8 @@ export function renderStatus(env) {
 function displayStatus(s) {
     if (s === 'n-a')
         return 'n/a';
+    if (s === 'validated-with-waiver')
+        return 'validated* (waived)';
     return s;
 }
 function formatDate(iso) {

package/dist/projects/validate.js

@@ -5,6 +5,7 @@ const KNOWN_ARTEFACT_TYPES = [
     'upgrade-scan', 'upgrade-progress', 'upgrade-report',
     'cca-assessment',
     'modernize-result', 'test-coverage',
+    'plan',
 ];
 const STATUS_BY_TYPE = {
     'spec-gap': ['open', 'answered', 'deferred', 'n-a'],
@@ -18,6 +19,7 @@ const STATUS_BY_TYPE = {
     'cca-assessment': ['open', 'reviewed', 'classified', 'archived'],
     'modernize-result': ['applied', 'skipped', 'failed', 'pending'],
     'test-coverage': ['generated', 'skipped', 'failed', 'pending'],
+    'plan': ['todo', 'designing', 'building', 'verifying', 'validated', 'validated-with-waiver', 'blocked'],
 };
 const REQUIRED_TOP_LEVEL = [
     'schemaVersion', 'artefactType', 'id', 'title',