@openrig/cli 0.3.4-rc.0 → 0.4.0

package/dist/commands/scope.js

@@ -8,10 +8,12 @@
 import fs from "node:fs";
 import path from "node:path";
 import { Command } from "commander";
-import { CLOSE_REASONS, MISSION_TEMPLATE_KINDS, SLICE_TEMPLATE_KINDS, ScopeCliError, } from "../lib/scope/types.js";
+import { CLOSE_REASONS, MISSION_TEMPLATE_KINDS, SLICE_TEMPLATE_KINDS, STAGE_VALUES, ScopeCliError, } from "../lib/scope/types.js";
 import { DEFAULT_PROJECT_PREFIX, inferMissionDotId, isMissionDotId, nextEscapeBandOrdinal, sliceIdFromMission, } from "../lib/scope/dot-id.js";
-import { ensureMissionIdPersisted, findMission, findSlice, listMissions, listSlices, moveSlice, nextSliceNN, pad2, resolveMissionsRoot, splitFrontmatter, todayDateISO, updateFrontmatter, } from "../lib/scope/scope-fs.js";
-import { renderMissionNotesTemplate, renderMissionTemplate, renderSliceTemplate, titleFromSlug, } from "../lib/scope/templates.js";
+import { ensureMissionId, ensureMissionIdPersisted, findMission, findSlice, listMissions, listSlices, moveSlice, nextSliceNN, pad2, readFrontmatter, resolveMissionsRoot, splitFrontmatter, todayDateISO, updateFrontmatter, } from "../lib/scope/scope-fs.js";
+import { renderMissionNotesTemplate, renderMissionProgressTemplate, renderMissionTemplate, renderSliceProgressTemplate, renderSliceTemplate, titleFromSlug, } from "../lib/scope/templates.js";
+import { addProgressRow, DEFAULT_PROGRESS_SECTION, parseStatus, PROGRESS_STATUSES, setProgressRow, } from "../lib/scope/progress-edit.js";
+import { deriveScopeTrust } from "../lib/scope/trust.js";
 function makeStdout() {
     return { write: (text) => process.stdout.write(text) };
 }
@@ -63,6 +65,16 @@ function getOpts(cmd) {
     }
     return {};
 }
+/** FR-5: a one-line human render of the derived stage. Shows the declared
+ *  stage, and (when a weak `verified` downgrades it) the effective stage +
+ *  why. Derived at read time; nothing is written. */
+function formatTrustLine(trust) {
+    const declared = trust.declaredStage || "—";
+    if (trust.downgraded) {
+        return `  stage: ${declared} (effective: ${trust.effectiveStage} — ${trust.verified.status})\n`;
+    }
+    return `  stage: ${declared}\n`;
+}
 // ---------------------------------------------------------------------
 // rig scope slice ls
 // ---------------------------------------------------------------------
@@ -131,6 +143,8 @@ function buildSliceShowCommand() {
             const readme = slice.readmePath ? fs.readFileSync(slice.readmePath, "utf8") : null;
             const children = fs.readdirSync(slice.absPath, { withFileTypes: true })
                 .map((e) => ({ name: e.name, kind: e.isDirectory() ? "dir" : "file" }));
+            // FR-5: derive read-time trust from (stage x verified) — NEVER stored.
+            const trust = deriveScopeTrust(slice.frontmatter);
             const payload = {
                 ok: true,
                 slice: {
@@ -140,6 +154,7 @@ function buildSliceShowCommand() {
                     status: slice.status,
                     path: slice.absPath,
                     frontmatter: slice.frontmatter,
+                    trust,
                     readme,
                     children,
                 },
@@ -151,6 +166,7 @@ function buildSliceShowCommand() {
                 out.write(`Slice: ${slice.missionName}/${slice.name}\n`);
                 out.write(`  id: ${slice.id ?? "—"}\n`);
                 out.write(`  status: ${slice.status ?? "—"}\n`);
+                out.write(formatTrustLine(trust));
                 out.write(`  path: ${slice.absPath}\n`);
                 out.write(`  children: ${children.length}\n`);
                 if (readme) {
@@ -176,6 +192,7 @@ function buildSliceCreateCommand() {
         .argument("<slug>", "Short slug (becomes the folder name's suffix)")
         .option("--template <kind>", `Template: ${SLICE_TEMPLATE_KINDS.join(" | ")}`, "placeholder")
         .option("--title <text>", "Display title (defaults to titlecased slug)")
+        .option("--readme-only", "Write progress_rail: readme-only in README frontmatter instead of scaffolding PROGRESS.md")
         .option("--json", "Machine-readable output")
         .action(async (missionName, rawSlug, opts, command) => {
         const out = makeStdout();
@@ -226,7 +243,16 @@ function buildSliceCreateCommand() {
             });
             fs.mkdirSync(sliceAbs, { recursive: true });
             const readmePath = path.join(sliceAbs, "README.md");
-            fs.writeFileSync(readmePath, body, "utf8");
+            const readmeOnly = Boolean(opts.readmeOnly);
+            if (readmeOnly) {
+                const markerBody = body.replace(/^(---\n)/, `---\nprogress_rail: readme-only\n`);
+                fs.writeFileSync(readmePath, markerBody, "utf8");
+            }
+            else {
+                fs.writeFileSync(readmePath, body, "utf8");
+                const progressPath = path.join(sliceAbs, "PROGRESS.md");
+                fs.writeFileSync(progressPath, renderSliceProgressTemplate(title), "utf8");
+            }
             const payload = {
                 ok: true,
                 slice: {
@@ -464,6 +490,8 @@ function buildMissionShowCommand() {
             const slices = listSlices(mission, "all").map((s) => ({
                 name: s.name, id: s.id, status: s.status, nn: s.nn,
             }));
+            // FR-5: derive read-time trust from (stage x verified) — NEVER stored.
+            const trust = deriveScopeTrust(mission.frontmatter);
             const payload = {
                 ok: true,
                 mission: {
@@ -473,6 +501,7 @@ function buildMissionShowCommand() {
                     activeSliceCount: mission.activeSliceCount,
                     closedSliceCount: mission.closedSliceCount,
                     frontmatter: mission.frontmatter,
+                    trust,
                     readme,
                     slices,
                 },
@@ -483,6 +512,7 @@ function buildMissionShowCommand() {
             else {
                 out.write(`Mission: ${mission.name}\n`);
                 out.write(`  id: ${mission.id ?? "—"}\n`);
+                out.write(formatTrustLine(trust));
                 out.write(`  active slices: ${mission.activeSliceCount}\n`);
                 out.write(`  closed slices: ${mission.closedSliceCount}\n`);
                 out.write(`  path: ${mission.absPath}\n`);
@@ -593,11 +623,14 @@ function buildMissionCreateCommand() {
                 });
                 missionNotesRendered = { rendered: r.rendered, resolvedFrom: r.resolvedFrom };
             }
+            const progressBody = renderMissionProgressTemplate(title);
             // All renders succeeded — safe to touch the filesystem.
             fs.mkdirSync(absPath, { recursive: true });
             fs.mkdirSync(path.join(absPath, "slices"), { recursive: true });
             const readmePath = path.join(absPath, "README.md");
             fs.writeFileSync(readmePath, readmeBody, "utf8");
+            const progressPath = path.join(absPath, "PROGRESS.md");
+            fs.writeFileSync(progressPath, progressBody, "utf8");
             let missionNotesPath = null;
             let missionNotesResolvedFrom = null;
             if (missionNotesRendered) {
@@ -633,6 +666,648 @@ function buildMissionCreateCommand() {
     });
 }
 // ---------------------------------------------------------------------
+// Audit (B2 — read-only scope audit)
+// ---------------------------------------------------------------------
+function buildAuditCommand() {
+    return new Command("audit")
+        .description("Read-only scope audit: flag missing/malformed progress rails and registration ghosts")
+        .requiredOption("--mission <name>", "Mission to audit")
+        .option("--json", "Machine-readable JSON output")
+        .action(async (opts, command) => {
+        const out = makeStdout();
+        const json = Boolean(opts.json);
+        try {
+            const missionsRoot = resolveMissionsRoot({ override: getOpts(command).workspace });
+            const { classifyScopeItem } = await import("../lib/scope/scope-audit.js");
+            const missionName = opts.mission;
+            const missionDir = path.join(missionsRoot, missionName);
+            if (!fs.existsSync(missionDir)) {
+                throw new ScopeCliError({ fact: `Mission "${missionName}" not found at ${missionDir}.`, consequence: "Cannot audit.", action: "Check the mission name." });
+            }
+            const missionReadme = path.join(missionDir, "README.md");
+            const missionProgress = path.join(missionDir, "PROGRESS.md");
+            const missionReadmeExists = fs.existsSync(missionReadme);
+            const missionProgressExists = fs.existsSync(missionProgress);
+            let missionResult;
+            if (!missionReadmeExists && missionProgressExists) {
+                missionResult = {
+                    railStatus: "malformed",
+                    findings: [{
+                            kind: "orphan_progress",
+                            severity: "high",
+                            path: missionDir,
+                            message: `PROGRESS.md exists but no README.md (orphan progress rail, no backing scope item)`,
+                            remediation: `Add a README.md with frontmatter id, or remove the orphan PROGRESS.md`,
+                        }],
+                    frontmatterError: null,
+                };
+            }
+            else {
+                const missionFm = missionReadmeExists
+                    ? extractFrontmatterRaw(fs.readFileSync(missionReadme, "utf-8"))
+                    : null;
+                missionResult = classifyScopeItem({
+                    id: null,
+                    path: missionDir,
+                    readmeFrontmatterRaw: missionFm,
+                    progressFileExists: missionProgressExists,
+                    readmeOnlyMarker: false,
+                    isActiveRelease: true,
+                    level: "mission",
+                });
+            }
+            const slicesDir = path.join(missionDir, "slices");
+            const sliceResults = [];
+            if (fs.existsSync(slicesDir)) {
+                for (const entry of fs.readdirSync(slicesDir)) {
+                    const sliceDir = path.join(slicesDir, entry);
+                    if (!fs.statSync(sliceDir).isDirectory())
+                        continue;
+                    const sliceReadme = path.join(sliceDir, "README.md");
+                    const sliceProgress = path.join(sliceDir, "PROGRESS.md");
+                    if (!fs.existsSync(sliceReadme)) {
+                        if (fs.existsSync(sliceProgress)) {
+                            sliceResults.push({
+                                name: entry,
+                                result: {
+                                    railStatus: "malformed",
+                                    findings: [{
+                                            kind: "orphan_progress",
+                                            severity: "high",
+                                            path: sliceDir,
+                                            message: `PROGRESS.md exists but no README.md (orphan progress rail, no backing scope item)`,
+                                            remediation: `Add a README.md with frontmatter id, or remove the orphan PROGRESS.md`,
+                                        }],
+                                    frontmatterError: null,
+                                },
+                            });
+                        }
+                        else {
+                            const noReadmeResult = classifyScopeItem({
+                                id: null,
+                                path: sliceDir,
+                                readmeFrontmatterRaw: null,
+                                progressFileExists: false,
+                                readmeOnlyMarker: false,
+                                isActiveRelease: true,
+                                level: "slice",
+                            });
+                            sliceResults.push({ name: entry, result: noReadmeResult });
+                        }
+                        continue;
+                    }
+                    const sliceFm = extractFrontmatterRaw(fs.readFileSync(sliceReadme, "utf-8"));
+                    const readmeOnlyMarker = sliceFm !== null && /^progress_rail\s*:\s*readme-only/m.test(sliceFm);
+                    const sliceResult = classifyScopeItem({
+                        id: null,
+                        path: sliceDir,
+                        readmeFrontmatterRaw: sliceFm,
+                        progressFileExists: fs.existsSync(sliceProgress),
+                        readmeOnlyMarker,
+                        isActiveRelease: true,
+                        level: "slice",
+                    });
+                    if (!/^\d{2}-/.test(entry)) {
+                        sliceResult.findings.push({
+                            kind: "id_convention_violation",
+                            severity: "high",
+                            path: sliceDir,
+                            message: `Directory "${entry}" does not match the NN-slug slice naming convention (e.g. 01-my-slice)`,
+                            remediation: `Rename to NN-slug format or move out of slices/`,
+                        });
+                    }
+                    sliceResults.push({ name: entry, result: sliceResult });
+                }
+            }
+            const allFindings = [
+                ...missionResult.findings.map((f) => ({ ...f, scope: "mission", scopeName: missionName })),
+                ...sliceResults.flatMap((s) => s.result.findings.map((f) => ({ ...f, scope: "slice", scopeName: s.name }))),
+            ];
+            if (json) {
+                out.write(JSON.stringify({
+                    ok: allFindings.length === 0,
+                    mission: { name: missionName, railStatus: missionResult.railStatus, frontmatterError: missionResult.frontmatterError, findings: missionResult.findings },
+                    slices: sliceResults.map((s) => ({ name: s.name, railStatus: s.result.railStatus, frontmatterError: s.result.frontmatterError, findings: s.result.findings })),
+                    totalFindings: allFindings.length,
+                }, null, 2));
+                out.write("\n");
+                if (allFindings.length > 0)
+                    process.exitCode = 1;
+                return;
+            }
+            out.write(`Scope audit: ${missionName}\n`);
+            out.write(`Mission rail: ${missionResult.railStatus}\n`);
+            out.write(`Slices: ${sliceResults.length} total\n\n`);
+            if (allFindings.length > 0) {
+                out.write("FINDINGS:\n");
+                for (const f of allFindings) {
+                    out.write(`  [${f.severity}] [${f.kind}] ${f.scope}/${f.scopeName}\n`);
+                    out.write(`    ${f.message}\n`);
+                    out.write(`    fix: ${f.remediation}\n`);
+                }
+                out.write(`\nFAIL: ${allFindings.length} finding(s)\n`);
+                process.exitCode = 1;
+            }
+            else {
+                out.write("PASS: all scope items have valid rails\n");
+            }
+        }
+        catch (err) {
+            if (err instanceof ScopeCliError) {
+                fail(err, json, out);
+            }
+            throw err;
+        }
+    });
+}
+function extractFrontmatterRaw(content) {
+    if (!content.startsWith("---"))
+        return null;
+    const match = /^---\s*\n([\s\S]*?)\n---/.exec(content);
+    return match ? match[1] : null;
+}
+// ---------------------------------------------------------------------
+// rig scope <tier> progress  (OPR.0.4.0.33 FR-3 — deterministic update)
+// ---------------------------------------------------------------------
+/** Resolve which file a progress update edits for a scope dir: the
+ *  PROGRESS.md when present, else the README's rail for a readme-only
+ *  scope, else an error directing to create/repair (the verb UPDATES an
+ *  existing surface; it does not scaffold). */
+function resolveProgressTarget(scopeDir, level) {
+    const progressPath = path.join(scopeDir, "PROGRESS.md");
+    if (fs.existsSync(progressPath))
+        return { targetPath: progressPath, kind: "progress" };
+    const readmePath = path.join(scopeDir, "README.md");
+    if (fs.existsSync(readmePath)) {
+        const fm = readFrontmatter(readmePath);
+        if (String(fm.progress_rail ?? "") === "readme-only") {
+            return { targetPath: readmePath, kind: "readme-only" };
+        }
+    }
+    throw new ScopeCliError({
+        fact: `${level} at ${scopeDir} has no progress surface (no PROGRESS.md and no readme-only rail).`,
+        consequence: "The progress verb updates an existing surface; it does not scaffold.",
+        action: `Backfill it with: rig scope ${level} repair <target> (creates PROGRESS.md), or rig scope ${level} create.`,
+    });
+}
+/** Shared body for slice/mission progress: validate the mutually
+ *  exclusive --add/--set modes, edit the resolved surface, write only
+ *  on change. */
+function runProgressUpdate(scopeDir, level, scopeName, opts, out, json) {
+    const hasAdd = typeof opts.add === "string";
+    const hasSet = typeof opts.set === "string";
+    if (hasAdd === hasSet) {
+        throw new ScopeCliError({
+            fact: hasAdd
+                ? "Both --add and --set were given."
+                : "Neither --add nor --set was given.",
+            consequence: "No progress update was made.",
+            action: 'Pass exactly one of --add "<row text>" or --set "<row text>".',
+        });
+    }
+    const status = parseStatus(opts.status ?? "active");
+    const { targetPath, kind } = resolveProgressTarget(scopeDir, level);
+    const before = fs.readFileSync(targetPath, "utf8");
+    let result;
+    let operation;
+    if (hasAdd) {
+        operation = "add";
+        result = addProgressRow(before, {
+            section: opts.section ?? DEFAULT_PROGRESS_SECTION,
+            text: opts.add,
+            status,
+        });
+    }
+    else {
+        operation = "set";
+        result = setProgressRow(before, { text: opts.set, status });
+    }
+    if (result.changed)
+        fs.writeFileSync(targetPath, result.content, "utf8");
+    emit(out, {
+        ok: true,
+        progress: {
+            scope: level,
+            name: scopeName,
+            target: targetPath,
+            kind,
+            operation,
+            status,
+            changed: result.changed,
+        },
+    }, json, [
+        `${result.changed ? "Updated" : "No change"} ${level} ${scopeName} progress (${operation})`,
+        `  target: ${targetPath}`,
+        `  status: ${status}`,
+    ]);
+}
+function buildSliceProgressCommand() {
+    return new Command("progress")
+        .description("Update a slice's progress rail deterministically (append a row, or set a row's status)")
+        .argument("<slice-path>", "Slice path (absolute, relative, or NN-slug)")
+        .option("--mission <name>", "Hint mission when slice-path is just NN-slug")
+        .option("--add <text>", "Append a checkbox row with this text")
+        .option("--set <text>", "Set the status of the row whose trimmed text exactly matches")
+        .option("--section <heading>", `Section heading for --add (default: ${DEFAULT_PROGRESS_SECTION})`)
+        .option("--status <status>", `Row status: ${PROGRESS_STATUSES.join(" | ")}`, "active")
+        .option("--json", "Machine-readable output")
+        .action(async (slicePath, opts, command) => {
+        const out = makeStdout();
+        const json = Boolean(opts.json);
+        try {
+            const missionsRoot = resolveMissionsRoot({ override: getOpts(command).workspace });
+            const slice = findSlice(missionsRoot, slicePath, opts.mission ?? null);
+            runProgressUpdate(slice.absPath, "slice", slice.name, opts, out, json);
+        }
+        catch (err) {
+            fail(err, json, out);
+        }
+    });
+}
+function buildMissionProgressCommand() {
+    return new Command("progress")
+        .description("Update a mission's progress rail deterministically (append a row, or set a row's status)")
+        .argument("<mission>", "Mission name")
+        .option("--add <text>", "Append a checkbox row with this text")
+        .option("--set <text>", "Set the status of the row whose trimmed text exactly matches")
+        .option("--section <heading>", `Section heading for --add (default: ${DEFAULT_PROGRESS_SECTION})`)
+        .option("--status <status>", `Row status: ${PROGRESS_STATUSES.join(" | ")}`, "active")
+        .option("--json", "Machine-readable output")
+        .action(async (missionName, opts, command) => {
+        const out = makeStdout();
+        const json = Boolean(opts.json);
+        try {
+            const missionsRoot = resolveMissionsRoot({ override: getOpts(command).workspace });
+            const mission = findMission(missionsRoot, missionName);
+            runProgressUpdate(mission.absPath, "mission", mission.name, opts, out, json);
+        }
+        catch (err) {
+            fail(err, json, out);
+        }
+    });
+}
+/** Mirror the create-time title derivation so a backfilled PROGRESS.md
+ *  is byte-identical to what create would have written. */
+function backfillTitle(level, scopeDir) {
+    const base = path.basename(scopeDir);
+    return level === "mission"
+        ? titleFromSlug(base.replace(/^release-/, ""))
+        : titleFromSlug(base.replace(/^\d+-/, ""));
+}
+/** Create a missing PROGRESS.md for a single scope dir. Idempotent
+ *  (skips when one exists) and non-clobbering (skips an intentional
+ *  readme-only scope, and skips README-less dirs that are not declared
+ *  scopes). */
+function backfillScopeProgress(scopeDir, level) {
+    const name = path.basename(scopeDir);
+    const readmePath = path.join(scopeDir, "README.md");
+    if (!fs.existsSync(readmePath)) {
+        return { scope: level, name, created: false, reason: "no-readme (not a declared scope)", path: null };
+    }
+    const progressPath = path.join(scopeDir, "PROGRESS.md");
+    if (fs.existsSync(progressPath)) {
+        return { scope: level, name, created: false, reason: "already-present", path: progressPath };
+    }
+    const fm = readFrontmatter(readmePath);
+    if (String(fm.progress_rail ?? "") === "readme-only") {
+        return { scope: level, name, created: false, reason: "readme-only (intentional opt-out)", path: null };
+    }
+    const title = backfillTitle(level, scopeDir);
+    const body = level === "mission"
+        ? renderMissionProgressTemplate(title)
+        : renderSliceProgressTemplate(title);
+    fs.writeFileSync(progressPath, body, "utf8");
+    return { scope: level, name, created: true, reason: "backfilled", path: progressPath };
+}
+// ---------------------------------------------------------------------
+// OPR.0.4.1.6 — stage + verified verbs (deterministic §2 maturity edits)
+// ---------------------------------------------------------------------
+/** Validate a stage against the §2 enum, rejecting invented values. */
+function validateStage(raw) {
+    if (!STAGE_VALUES.includes(raw)) {
+        throw new ScopeCliError({
+            fact: `Invalid stage "${raw}".`,
+            consequence: "Stage not changed.",
+            action: `Use one of: ${STAGE_VALUES.join(" | ")}.`,
+        });
+    }
+    return raw;
+}
+/** Surgically set `stage` (+ `superseded-by` when superseded) on a scope
+ *  README, enforcing the §2 superseded-needs-successor rule. */
+function applyStage(readmePath, stage, successor) {
+    const updates = { stage };
+    if (stage === "superseded") {
+        const id = typeof successor === "string" ? successor.trim() : "";
+        if (!id) {
+            throw new ScopeCliError({
+                fact: "stage 'superseded' requires a successor.",
+                consequence: "Stage not changed (a superseded scope must name what replaces it, per scope-and-versioning §2).",
+                action: "Re-run with --successor <id>, e.g. --successor OPR.0.4.1.7.",
+            });
+        }
+        updates["superseded-by"] = id;
+    }
+    updateFrontmatter(readmePath, updates);
+}
+/** `retired` is an exit, not a rung — warn (do not block). */
+function warnRetired(stage) {
+    if (stage === "retired") {
+        process.stderr.write("Warning: stage 'retired' means do-not-use (an exit, not a maturity rung).\n");
+    }
+}
+/** Validate a --against provenance: mandatory, non-empty, non-whitespace
+ *  (the §2 "no bare timestamp" rule). Returns the trimmed source. */
+function validateAgainst(raw) {
+    const source = typeof raw === "string" ? raw.trim() : "";
+    if (!source) {
+        throw new ScopeCliError({
+            fact: "--against provenance is empty or missing.",
+            consequence: "verified not stamped — scope-and-versioning §2 forbids a bare timestamp without a named source.",
+            action: 'Provide what it was verified against, e.g. --against "runtime (npm+tag+origin)".',
+        });
+    }
+    return source;
+}
+function buildSliceStageCommand() {
+    return new Command("stage")
+        .description(`Set a slice's epistemic stage (${STAGE_VALUES.join(" | ")}); superseded needs --successor`)
+        .argument("<slice-path>", "Slice path (absolute, relative, or NN-slug)")
+        .argument("<new-stage>", `New stage: ${STAGE_VALUES.join(" | ")}`)
+        .option("--successor <id>", "Successor scope id — REQUIRED when new-stage is superseded")
+        .option("--mission <name>", "Hint mission when slice-path is just NN-slug")
+        .option("--json", "Machine-readable output")
+        .action(async (slicePath, newStage, opts, command) => {
+        const out = makeStdout();
+        const json = Boolean(opts.json);
+        try {
+            const stage = validateStage(newStage);
+            const missionsRoot = resolveMissionsRoot({ override: getOpts(command).workspace });
+            const slice = findSlice(missionsRoot, slicePath, opts.mission ?? null);
+            if (!slice.readmePath) {
+                throw new ScopeCliError({
+                    fact: `Slice ${slice.name} has no README.md.`,
+                    consequence: "Stage is a frontmatter field on the README; nothing to write.",
+                    action: "Create the slice README (rig scope slice create) before setting its stage.",
+                });
+            }
+            applyStage(slice.readmePath, stage, opts.successor);
+            warnRetired(stage);
+            const supersededBy = stage === "superseded" ? String(opts.successor).trim() : undefined;
+            emit(out, { ok: true, scope: { tier: "slice", mission: slice.missionName, name: slice.name, id: slice.id, stage, ...(supersededBy ? { supersededBy } : {}) } }, json, [
+                `Set ${slice.missionName}/${slice.name} stage: ${stage}`,
+                ...(supersededBy ? [`  superseded-by: ${supersededBy}`] : []),
+            ]);
+        }
+        catch (err) {
+            fail(err, json, out);
+        }
+    });
+}
+function buildMissionStageCommand() {
+    return new Command("stage")
+        .description(`Set a mission's epistemic stage (${STAGE_VALUES.join(" | ")}); superseded needs --successor`)
+        .argument("<mission>", "Mission name")
+        .argument("<new-stage>", `New stage: ${STAGE_VALUES.join(" | ")}`)
+        .option("--successor <id>", "Successor scope id — REQUIRED when new-stage is superseded")
+        .option("--json", "Machine-readable output")
+        .action(async (missionName, newStage, opts, command) => {
+        const out = makeStdout();
+        const json = Boolean(opts.json);
+        try {
+            const stage = validateStage(newStage);
+            const missionsRoot = resolveMissionsRoot({ override: getOpts(command).workspace });
+            const mission = findMission(missionsRoot, missionName);
+            if (!mission.readmePath) {
+                throw new ScopeCliError({
+                    fact: `Mission ${mission.name} has no README.md.`,
+                    consequence: "Stage is a frontmatter field on the README; nothing to write.",
+                    action: "Create the mission README before setting its stage.",
+                });
+            }
+            applyStage(mission.readmePath, stage, opts.successor);
+            warnRetired(stage);
+            const supersededBy = stage === "superseded" ? String(opts.successor).trim() : undefined;
+            emit(out, { ok: true, scope: { tier: "mission", name: mission.name, id: mission.id, stage, ...(supersededBy ? { supersededBy } : {}) } }, json, [
+                `Set ${mission.name} stage: ${stage}`,
+                ...(supersededBy ? [`  superseded-by: ${supersededBy}`] : []),
+            ]);
+        }
+        catch (err) {
+            fail(err, json, out);
+        }
+    });
+}
+function buildSliceVerifiedCommand() {
+    return new Command("verified")
+        .description("Stamp a slice's verified line: <today> against <source> (provenance mandatory; overwrites the prior line)")
+        .argument("<slice-path>", "Slice path (absolute, relative, or NN-slug)")
+        .option("--against <source>", "What it was verified against — MANDATORY (no bare timestamps)")
+        .option("--mission <name>", "Hint mission when slice-path is just NN-slug")
+        .option("--json", "Machine-readable output")
+        .action(async (slicePath, opts, command) => {
+        const out = makeStdout();
+        const json = Boolean(opts.json);
+        try {
+            const source = validateAgainst(opts.against);
+            const missionsRoot = resolveMissionsRoot({ override: getOpts(command).workspace });
+            const slice = findSlice(missionsRoot, slicePath, opts.mission ?? null);
+            if (!slice.readmePath) {
+                throw new ScopeCliError({
+                    fact: `Slice ${slice.name} has no README.md.`,
+                    consequence: "verified is a frontmatter field on the README; nothing to write.",
+                    action: "Create the slice README before stamping verified.",
+                });
+            }
+            const verified = `${todayDateISO()} against ${source}`;
+            updateFrontmatter(slice.readmePath, { verified });
+            emit(out, { ok: true, scope: { tier: "slice", mission: slice.missionName, name: slice.name, id: slice.id, verified } }, json, [
+                `Stamped ${slice.missionName}/${slice.name} verified: ${verified}`,
+            ]);
+        }
+        catch (err) {
+            fail(err, json, out);
+        }
+    });
+}
+function buildMissionVerifiedCommand() {
+    return new Command("verified")
+        .description("Stamp a mission's verified line: <today> against <source> (provenance mandatory; overwrites the prior line)")
+        .argument("<mission>", "Mission name")
+        .option("--against <source>", "What it was verified against — MANDATORY (no bare timestamps)")
+        .option("--json", "Machine-readable output")
+        .action(async (missionName, opts, command) => {
+        const out = makeStdout();
+        const json = Boolean(opts.json);
+        try {
+            const source = validateAgainst(opts.against);
+            const missionsRoot = resolveMissionsRoot({ override: getOpts(command).workspace });
+            const mission = findMission(missionsRoot, missionName);
+            if (!mission.readmePath) {
+                throw new ScopeCliError({
+                    fact: `Mission ${mission.name} has no README.md.`,
+                    consequence: "verified is a frontmatter field on the README; nothing to write.",
+                    action: "Create the mission README before stamping verified.",
+                });
+            }
+            const verified = `${todayDateISO()} against ${source}`;
+            updateFrontmatter(mission.readmePath, { verified });
+            emit(out, { ok: true, scope: { tier: "mission", name: mission.name, id: mission.id, verified } }, json, [
+                `Stamped ${mission.name} verified: ${verified}`,
+            ]);
+        }
+        catch (err) {
+            fail(err, json, out);
+        }
+    });
+}
+/** Map a legacy `status:` to a §4 migration stage. Default `wip` when absent
+ *  or unmapped (the safe floor). */
+function mapLegacyStatusToStage(status) {
+    const s = typeof status === "string" ? status.toLowerCase().trim() : "";
+    if (s === "placeholder")
+        return "wip";
+    if (s === "draft" || s === "draft-for-comms")
+        return "wip";
+    if (s === "active" || s === "in-flight")
+        return "established";
+    if (s.startsWith("shipped") || s.startsWith("closed"))
+        return "established";
+    if (s === "ready-for-mission" || s === "ready-for-orch-dispatch")
+        return "provisional";
+    return "wip";
+}
+/** Idempotently conform a scope README's mandatory frontmatter. Only ADDS
+ *  absent fields — never clobbers an existing id/stage/verified. `mintId` is
+ *  called only when `id` is absent (it may persist a parent id per §1 lazy
+ *  adoption). */
+function conformReadmeFrontmatter(readmePath, mintId) {
+    const fm = readFrontmatter(readmePath);
+    const updates = {};
+    let idAdded = null;
+    const hasId = typeof fm.id === "string" && fm.id.length > 0;
+    if (!hasId) {
+        const minted = mintId();
+        if (minted) {
+            idAdded = minted;
+            updates.id = minted;
+        }
+    }
+    let stageAdded = null;
+    if (!fm.stage) {
+        stageAdded = mapLegacyStatusToStage(fm.status);
+        updates.stage = stageAdded;
+    }
+    let verifiedAdded = null;
+    if (!fm.verified) {
+        verifiedAdded = `${todayDateISO()} against backfill (rig scope repair)`;
+        updates.verified = verifiedAdded;
+    }
+    const changed = Object.keys(updates).length > 0;
+    if (changed)
+        updateFrontmatter(readmePath, updates);
+    return { idAdded, stageAdded, verifiedAdded, changed };
+}
+/** Mint a slice's id from its (persisted) parent mission id + NN — the §1
+ *  lazy parent-ID adoption site. Null when the folder has no NN. */
+function mintSliceIdClosure(slice, missionsRoot) {
+    return () => {
+        if (slice.nn == null)
+            return null;
+        const mission = findMission(missionsRoot, slice.missionName);
+        const missionId = ensureMissionIdPersisted(mission, missionsRoot);
+        return sliceIdFromMission(missionId, slice.nn);
+    };
+}
+function conformLines(scope, r) {
+    if (!r.changed)
+        return [`  frontmatter: conformant (no change)`];
+    const parts = [];
+    if (r.idAdded)
+        parts.push(`id=${r.idAdded}`);
+    if (r.stageAdded)
+        parts.push(`stage=${r.stageAdded}`);
+    if (r.verifiedAdded)
+        parts.push(`verified=${r.verifiedAdded}`);
+    return [`  frontmatter conformed: ${parts.join(", ")}`];
+}
+function buildSliceRepairCommand() {
+    return new Command("repair")
+        .description("Backfill a slice's missing PROGRESS.md + conform mandatory frontmatter (id/stage/verified); idempotent")
+        .argument("<slice-path>", "Slice path (absolute, relative, or NN-slug)")
+        .option("--mission <name>", "Hint mission when slice-path is just NN-slug")
+        .option("--json", "Machine-readable output")
+        .action(async (slicePath, opts, command) => {
+        const out = makeStdout();
+        const json = Boolean(opts.json);
+        try {
+            const missionsRoot = resolveMissionsRoot({ override: getOpts(command).workspace });
+            const slice = findSlice(missionsRoot, slicePath, opts.mission ?? null);
+            const result = backfillScopeProgress(slice.absPath, "slice");
+            const frontmatter = slice.readmePath
+                ? conformReadmeFrontmatter(slice.readmePath, mintSliceIdClosure(slice, missionsRoot))
+                : { idAdded: null, stageAdded: null, verifiedAdded: null, changed: false };
+            emit(out, { ok: true, result, frontmatter }, json, [
+                `${result.created ? "Backfilled" : "Skipped"} ${slice.name}: ${result.reason}`,
+                ...(result.path ? [`  path: ${result.path}`] : []),
+                ...conformLines("slice", frontmatter),
+            ]);
+        }
+        catch (err) {
+            fail(err, json, out);
+        }
+    });
+}
+function buildMissionRepairCommand() {
+    return new Command("repair")
+        .description("Backfill missing PROGRESS.md + conform mandatory frontmatter (id/stage/verified) for a mission and its slices; idempotent")
+        .argument("<mission>", "Mission name")
+        .option("--json", "Machine-readable output")
+        .action(async (missionName, opts, command) => {
+        const out = makeStdout();
+        const json = Boolean(opts.json);
+        try {
+            const missionsRoot = resolveMissionsRoot({ override: getOpts(command).workspace });
+            const mission = findMission(missionsRoot, missionName);
+            const results = [];
+            results.push(backfillScopeProgress(mission.absPath, "mission"));
+            const slicesDir = path.join(mission.absPath, "slices");
+            if (fs.existsSync(slicesDir)) {
+                for (const entry of fs.readdirSync(slicesDir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+                    if (!entry.isDirectory() || !/^\d+-/.test(entry.name))
+                        continue;
+                    results.push(backfillScopeProgress(path.join(slicesDir, entry.name), "slice"));
+                }
+            }
+            // FR-4: conform mandatory frontmatter — mission first (mints+persists
+            // the mission id), then each slice (child ids derive from the now-
+            // persisted parent id).
+            const conformed = [];
+            if (mission.readmePath) {
+                const fm = conformReadmeFrontmatter(mission.readmePath, () => ensureMissionId(mission, missionsRoot));
+                conformed.push({ scope: "mission", name: mission.name, frontmatter: fm });
+            }
+            const freshMission = findMission(missionsRoot, mission.name);
+            for (const slice of listSlices(freshMission, "all")) {
+                if (!slice.readmePath)
+                    continue;
+                const fm = conformReadmeFrontmatter(slice.readmePath, mintSliceIdClosure(slice, missionsRoot));
+                conformed.push({ scope: "slice", name: slice.name, frontmatter: fm });
+            }
+            const created = results.filter((r) => r.created);
+            const fmChanged = conformed.filter((c) => c.frontmatter.changed);
+            emit(out, { ok: true, mission: mission.name, created, results, conformed }, json, [
+                `Repaired ${mission.name}: ${created.length} PROGRESS.md backfilled, ${fmChanged.length} frontmatter conformed`,
+                ...created.map((r) => `  + PROGRESS ${r.scope}/${r.name}`),
+                ...fmChanged.map((c) => `  ~ frontmatter ${c.scope}/${c.name}`),
+            ]);
+        }
+        catch (err) {
+            fail(err, json, out);
+        }
+    });
+}
+// ---------------------------------------------------------------------
 // Aggregate
 // ---------------------------------------------------------------------
 export function scopeCommand() {
@@ -646,12 +1321,21 @@ export function scopeCommand() {
     slice.addCommand(buildSliceShipCommand());
     slice.addCommand(buildSliceCloseCommand());
     slice.addCommand(buildSliceMoveCommand());
+    slice.addCommand(buildSliceProgressCommand());
+    slice.addCommand(buildSliceRepairCommand());
+    slice.addCommand(buildSliceStageCommand());
+    slice.addCommand(buildSliceVerifiedCommand());
     cmd.addCommand(slice);
     const mission = new Command("mission").description("Mission-tier commands");
     mission.addCommand(buildMissionLsCommand());
     mission.addCommand(buildMissionShowCommand());
     mission.addCommand(buildMissionCreateCommand());
+    mission.addCommand(buildMissionProgressCommand());
+    mission.addCommand(buildMissionRepairCommand());
+    mission.addCommand(buildMissionStageCommand());
+    mission.addCommand(buildMissionVerifiedCommand());
     cmd.addCommand(mission);
+    cmd.addCommand(buildAuditCommand());
     return cmd;
 }
 // Re-exports for tests.