@openrig/cli 0.5.4 → 0.5.6

package/dist/commands/scope.js

@@ -7,18 +7,18 @@
 // mission/slice frontmatter per §1 of that convention.
 import fs from "node:fs";
 import path from "node:path";
-import { execFileSync } from "node:child_process";
 import { Command } from "commander";
 import { DaemonClient } from "../client.js";
 import { attestationLineage } from "../lib/scope/attestation-lineage.js";
 import { getDaemonStatus, getDaemonUrl, statusGuardMessage } from "../daemon-lifecycle.js";
 import { realDeps } from "./daemon.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 { ensureMissionId, ensureMissionIdPersisted, findMission, resolveNodeFile, findSlice, gitTopLevel, listMissions, listSlices, moveSlice, nextSliceNN, pad2, readFrontmatter, resolveMissionsRoot, splitFrontmatter, todayDateISO, updateFrontmatter, } from "../lib/scope/scope-fs.js";
-import { renderImplementationPrdTemplate, renderMissionBriefTemplate, renderMissionNotesTemplate, renderMissionProgressTemplate, renderMissionTemplate, renderSliceProofTemplate, renderSliceProgressTemplate, renderSliceTemplate, titleFromSlug, } from "../lib/scope/templates.js";
+import { DEFAULT_PROJECT_PREFIX, inferMissionDotId, isMissionDotId, isSliceDotId, nextEscapeBandOrdinal, sliceIdFromMission, } from "../lib/scope/dot-id.js";
+import { buildMissionDependencyGraph, ensureMissionId, ensureMissionIdPersisted, findMission, resolveNodeFile, findSlice, listMissions, listSlices, moveSlice, nextSliceNN, NOTES_FILE_PRECEDENCE, pad2, readFrontmatter, resolveNotesFile, resolveMissionsRoot, splitFrontmatter, todayDateISO, updateFrontmatter, } from "../lib/scope/scope-fs.js";
+import { renderCapabilityDeltaTemplate, renderNotesTemplate, renderMissionProgressTemplate, renderMissionTemplate, renderSliceProofTemplate, 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";
+import { capabilityDeltaExpiryFindings } from "../lib/scope/capability-delta.js";
 function makeStdout() {
     return { write: (text) => process.stdout.write(text) };
 }
@@ -192,11 +192,13 @@ function buildSliceShowCommand() {
 // ---------------------------------------------------------------------
 function buildSliceCreateCommand() {
     return new Command("create")
-        .description("Create a new slice in a mission. Scaffolds the SDLC convention sections (## Intent / ## Mini-requirements / ## Proof contract) + proof/ + PROOF.md + IMPLEMENTATION-PRD.md for EVERY template kind — the shapes the Living Notes UI projects. Conventions SSOT: docs/reference/sdlc-conventions.md (installed: $OPENRIG_HOME/reference/sdlc-conventions.md).")
+        .description("Create a new slice with SPEC.md, PROGRESS.md, PROOF.md, and proof/. Conventions SSOT: docs/reference/sdlc-conventions.md (installed: $OPENRIG_HOME/reference/sdlc-conventions.md).")
         .argument("<mission>", "Mission name")
         .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("--intent <text>", "Authored intent stored in SPEC.md frontmatter (defaults to title)")
+        .option("--depends-on <dot-id...>", "Advisory build-order dependencies on sibling slice dot-IDs")
         .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) => {
@@ -238,6 +240,17 @@ function buildSliceCreateCommand() {
             }
             const id = sliceIdFromMission(missionId, nn);
             const title = opts.title ?? titleFromSlug(slug);
+            const intent = opts.intent ?? title;
+            const dependsOn = Array.isArray(opts.dependsOn) ? [...new Set(opts.dependsOn)] : [];
+            for (const dependency of dependsOn) {
+                if (!isSliceDotId(dependency) || !dependency.startsWith(`${missionId}.`)) {
+                    throw new ScopeCliError({
+                        fact: `Dependency "${dependency}" is not a sibling slice dot-ID under ${missionId}.`,
+                        consequence: "Slice not created.",
+                        action: `Use a sibling ID shaped like ${missionId}.<n>, or omit --depends-on.`,
+                    });
+                }
+            }
             const createdDate = todayDateISO();
             const body = renderSliceTemplate(kind, {
                 id,
@@ -246,20 +259,10 @@ function buildSliceCreateCommand() {
                 mission: mission.name,
                 title,
                 created_date: createdDate,
+                intent,
+                depends_on: dependsOn,
             });
             const proofBody = renderSliceProofTemplate({ id, title });
-            // OPR.0.4.4.23 — every template kind also scaffolds the
-            // IMPLEMENTATION-PRD skeleton (convention sections + elastic-middle
-            // note): the PRD is what the Living Notes UI's proof-contract join
-            // reads, so a slice without one doesn't project its DELIVERED pairing.
-            const prdBody = renderImplementationPrdTemplate({
-                id,
-                slice_number: pad2(nn),
-                slug,
-                mission: mission.name,
-                title,
-                created_date: createdDate,
-            });
             fs.mkdirSync(sliceAbs, { recursive: true });
             fs.mkdirSync(path.join(sliceAbs, "proof"), { recursive: true });
             // New scaffolds author SPEC.md; existing README-backed nodes are never rewritten.
@@ -275,7 +278,6 @@ function buildSliceCreateCommand() {
                 fs.writeFileSync(progressPath, renderSliceProgressTemplate(title), "utf8");
             }
             fs.writeFileSync(path.join(sliceAbs, "PROOF.md"), proofBody, "utf8");
-            fs.writeFileSync(path.join(sliceAbs, "IMPLEMENTATION-PRD.md"), prdBody, "utf8");
             const payload = {
                 ok: true,
                 slice: {
@@ -474,7 +476,7 @@ function buildSliceMoveCommand() {
 // ---------------------------------------------------------------------
 function buildMissionLsCommand() {
     return new Command("ls")
-        .description("List missions (top-level folders with README.md)")
+        .description("List missions (top-level folders with SPEC.md or a legacy README.md)")
         .option("--json", "Machine-readable output")
         .action(async (opts, command) => {
         const out = makeStdout();
@@ -540,7 +542,7 @@ function buildMissionShowCommand() {
                 out.write(`  closed slices: ${mission.closedSliceCount}\n`);
                 out.write(`  path: ${mission.absPath}\n`);
                 if (readme) {
-                    out.write("\n--- README ---\n");
+                    out.write(`\n--- ${path.basename(mission.readmePath)} ---\n`);
                     out.write(readme);
                     if (!readme.endsWith("\n"))
                         out.write("\n");
@@ -559,7 +561,10 @@ function buildMissionCreateCommand() {
         .option("--template <kind>", `Template: ${MISSION_TEMPLATE_KINDS.join(" | ")} (auto when name matches release-X.Y.Z)`, "")
         .option("--id <dot-id>", "Explicit dot-ID. Overrides name-pattern inference.")
         .option("--title <text>", "Display title (defaults to titlecased name)")
-        .option("--no-mission-notes", "Skip the auto-scaffold of MISSION_NOTES.md (rare; default is to scaffold from conventions/mission-notes/TEMPLATE.md)")
+        .option("--intent <text>", "Authored intent stored in SPEC.md frontmatter (defaults to title)")
+        .option("--depends-on <dot-id...>", "Advisory build-order dependencies on sibling mission dot-IDs")
+        .option("--no-notes", "Skip NOTES.md scaffolding")
+        .option("--no-mission-notes", "Deprecated alias for --no-notes")
         .option("--json", "Machine-readable output")
         .action(async (rawName, opts, command) => {
         const out = makeStdout();
@@ -619,15 +624,22 @@ function buildMissionCreateCommand() {
                 const ordinal = nextEscapeBandOrdinal(peers.map((p) => p.id));
                 id = inferMissionDotId(name, ordinal);
             }
-            // Resolve titles + render templates BEFORE any filesystem side
-            // effects (banked verify-first-then-write — guard catch on
-            // OPR.0.3.2.21.FR-3 qitem-20260601121058: a stale
-            // OPENRIG_MISSION_NOTES_TEMPLATE_PATH used to throw AFTER
-            // mkdirSync + README write, leaking a half-created mission dir
-            // that future `mission create <same-name>` would reject as
-            // already-existing). Rendering MISSION_NOTES first means a
-            // stale env-var fails before any disk mutation.
+            // Resolve titles + render templates before any filesystem side
+            // effects. A stale current or legacy notes-template override must
+            // fail before mkdir, or it leaks a half-created mission directory.
             const title = opts.title ?? titleFromSlug(name.replace(/^release-/, ""));
+            const intent = opts.intent ?? title;
+            const dependsOn = Array.isArray(opts.dependsOn) ? [...new Set(opts.dependsOn)] : [];
+            const project = id.split(".")[0];
+            for (const dependency of dependsOn) {
+                if (!isMissionDotId(dependency) || dependency.split(".")[0] !== project) {
+                    throw new ScopeCliError({
+                        fact: `Dependency "${dependency}" is not a sibling mission dot-ID in project ${project}.`,
+                        consequence: "Mission not created.",
+                        action: `Use a mission ID shaped like ${project}.<version>, or omit --depends-on.`,
+                    });
+                }
+            }
             const releaseVersion = isReleaseName ? name.replace(/^release-/, "") : "";
             const readmeBody = renderMissionTemplate(templateKind, {
                 id,
@@ -636,18 +648,30 @@ function buildMissionCreateCommand() {
                 title,
                 created_date: todayDateISO(),
                 release_version: releaseVersion,
+                intent,
+                depends_on: dependsOn,
             });
-            let missionNotesRendered = null;
-            if (opts.missionNotes !== false) {
-                const r = renderMissionNotesTemplate({
+            let notesRendered = null;
+            if (opts.notes !== false && opts.missionNotes !== false) {
+                notesRendered = renderNotesTemplate({
                     mission_id: id,
                     mission_name: title,
                     created_date: todayDateISO(),
                 });
-                missionNotesRendered = { rendered: r.rendered, resolvedFrom: r.resolvedFrom };
             }
             const progressBody = renderMissionProgressTemplate(title);
-            const missionBriefBody = renderMissionBriefTemplate(title);
+            const capabilityDeltaBody = isReleaseName
+                ? renderCapabilityDeltaTemplate({
+                    id,
+                    slug: name,
+                    mission: name,
+                    title,
+                    created_date: todayDateISO(),
+                    release_version: releaseVersion,
+                    intent,
+                    depends_on: dependsOn,
+                })
+                : null;
             // All renders succeeded — safe to touch the filesystem.
             fs.mkdirSync(absPath, { recursive: true });
             fs.mkdirSync(path.join(absPath, "slices"), { recursive: true });
@@ -656,14 +680,16 @@ function buildMissionCreateCommand() {
             fs.writeFileSync(readmePath, readmeBody, "utf8");
             const progressPath = path.join(absPath, "PROGRESS.md");
             fs.writeFileSync(progressPath, progressBody, "utf8");
-            const missionBriefPath = path.join(absPath, "MISSION_BRIEF.md");
-            fs.writeFileSync(missionBriefPath, missionBriefBody, "utf8");
-            let missionNotesPath = null;
-            let missionNotesResolvedFrom = null;
-            if (missionNotesRendered) {
-                missionNotesPath = path.join(absPath, "MISSION_NOTES.md");
-                fs.writeFileSync(missionNotesPath, missionNotesRendered.rendered, "utf8");
-                missionNotesResolvedFrom = missionNotesRendered.resolvedFrom;
+            const capabilityDeltaPath = capabilityDeltaBody
+                ? path.join(absPath, `CAPABILITY-DELTA-v${releaseVersion}.md`)
+                : null;
+            if (capabilityDeltaPath && capabilityDeltaBody) {
+                fs.writeFileSync(capabilityDeltaPath, capabilityDeltaBody, "utf8");
+            }
+            let notesPath = null;
+            if (notesRendered) {
+                notesPath = path.join(absPath, "NOTES.md");
+                fs.writeFileSync(notesPath, notesRendered.rendered, "utf8");
             }
             const humanLines = [
                 `Created mission ${name}`,
@@ -671,8 +697,13 @@ function buildMissionCreateCommand() {
                 `  template: ${templateKind}`,
                 `  path: ${absPath}`,
             ];
-            if (missionNotesPath) {
-                humanLines.push(`  mission-notes: ${missionNotesPath} (template: ${missionNotesResolvedFrom})`);
+            if (notesPath) {
+                humanLines.push(`  notes: ${notesPath} (template: ${notesRendered?.resolvedFrom})`);
+            }
+            if (capabilityDeltaPath)
+                humanLines.push(`  capability delta: ${capabilityDeltaPath}`);
+            if (notesRendered?.resolvedFrom === "legacy-env") {
+                humanLines.push("  advisory: OPENRIG_MISSION_NOTES_TEMPLATE_PATH is deprecated; use OPENRIG_NOTES_TEMPLATE_PATH");
             }
             emit(out, {
                 ok: true,
@@ -682,9 +713,12 @@ function buildMissionCreateCommand() {
                     template: templateKind,
                     path: absPath,
                     readmePath,
-                    missionBriefPath,
-                    missionNotesPath,
-                    missionNotesResolvedFrom,
+                    notesPath,
+                    capabilityDeltaPath,
+                    notesResolvedFrom: notesRendered?.resolvedFrom ?? null,
+                    advisories: notesRendered?.resolvedFrom === "legacy-env"
+                        ? ["OPENRIG_MISSION_NOTES_TEMPLATE_PATH is deprecated; use OPENRIG_NOTES_TEMPLATE_PATH"]
+                        : [],
                 },
             }, json, humanLines);
         }
@@ -693,38 +727,62 @@ function buildMissionCreateCommand() {
         }
     });
 }
+function buildMissionGraphCommand() {
+    return new Command("graph")
+        .description("Show advisory sibling build-order edges and the current ready set")
+        .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 graph = buildMissionDependencyGraph(findMission(missionsRoot, missionName));
+            emit(out, { ok: true, graph }, json, [
+                `Ready: ${graph.ready.join(", ") || "(none)"}`,
+                ...graph.waiting.map((row) => `Waiting: ${row.id} on ${row.on.join(", ")}`),
+                ...graph.advisories.map((row) => `Advisory: ${row.id}${row.dependency ? ` -> ${row.dependency}` : ""}: ${row.message}`),
+            ]);
+        }
+        catch (err) {
+            fail(err, json, out);
+        }
+    });
+}
+function buildResolveNotesCommand() {
+    return new Command("resolve-notes")
+        .description("Resolve the readable mission notes file for an absolute work-node directory")
+        .argument("<absolute-work-node-dir>", "Absolute mission or slice directory")
+        .option("--json", "Machine-readable JSON output")
+        .action((workNodeDir, opts) => {
+        const out = makeStdout();
+        const json = Boolean(opts.json);
+        try {
+            if (!path.isAbsolute(workNodeDir)) {
+                throw new ScopeCliError({
+                    fact: `Work-node directory must be absolute: ${workNodeDir}`,
+                    consequence: "Mission notes cannot be resolved from an ambiguous location.",
+                    action: "Pass the absolute mission or slice directory.",
+                });
+            }
+            const resolution = resolveNotesFile(workNodeDir);
+            emit(out, { ok: true, resolution }, json, [
+                resolution
+                    ? `${resolution.name}: ${resolution.path}`
+                    : `No readable mission notes at ${workNodeDir}`,
+            ]);
+        }
+        catch (err) {
+            fail(err, json, out);
+        }
+    });
+}
 // ---------------------------------------------------------------------
 // Audit (B2 — read-only scope audit)
 // ---------------------------------------------------------------------
-/**
- * Files changed by the most recent commit (revision basis: HEAD), returned as
- * ABSOLUTE resolved paths. Returns null when there is NO git context — the dir
- * is not inside a repo, HEAD does not resolve (e.g. a fresh repo with no
- * commits), or the git command fails. Callers then leave the
- * committed-without-PROGRESS classifier inputs UNDEFINED, so the check stays
- * inert: no false-green (we never assume "PROGRESS untouched" without evidence)
- * and no false-positive (we never fire when we cannot see the commit).
- */
-function gitHeadTouchedAbsPaths(dir) {
-    const topLevel = gitTopLevel(dir);
-    if (!topLevel)
-        return null;
-    try {
-        const out = execFileSync("git", ["-C", topLevel, "show", "--name-only", "--pretty=format:", "HEAD"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
-        const abs = out
-            .split(/\r?\n/)
-            .map((line) => line.trim())
-            .filter((line) => line.length > 0)
-            .map((rel) => path.resolve(topLevel, rel));
-        return new Set(abs);
-    }
-    catch {
-        return null;
-    }
-}
 function buildAuditCommand() {
     return new Command("audit")
-        .description("Read-only scope audit: flag missing/malformed progress rails and registration ghosts")
+        .description("Read-only scope audit: flag scope findings and show the advisory dependency graph")
         .requiredOption("--mission <name>", "Mission to audit")
         .option("--json", "Machine-readable JSON output")
         .action(async (opts, command) => {
@@ -740,11 +798,23 @@ function buildAuditCommand() {
             }
             const missionReadme = resolveNodeFile(missionDir) ?? path.join(missionDir, "SPEC.md");
             const missionProgress = path.join(missionDir, "PROGRESS.md");
-            const missionBrief = path.join(missionDir, "MISSION_BRIEF.md");
-            const missionNotes = path.join(missionDir, "MISSION_NOTES.md");
+            const missionNotesResolution = resolveNotesFile(missionDir);
+            const missionNotesPath = missionNotesResolution?.path
+                ?? path.join(missionDir, NOTES_FILE_PRECEDENCE[0]);
             const missionReadmeExists = fs.existsSync(missionReadme);
             const missionProgressExists = fs.existsSync(missionProgress);
-            const missionBriefExists = fs.existsSync(missionBrief);
+            const auditMission = missionReadmeExists
+                ? findMission(missionsRoot, missionName)
+                : {
+                    name: missionName,
+                    absPath: missionDir,
+                    readmePath: null,
+                    frontmatter: {},
+                    id: null,
+                    activeSliceCount: 0,
+                    closedSliceCount: 0,
+                };
+            const graph = buildMissionDependencyGraph(auditMission);
             let missionResult;
             if (!missionReadmeExists && missionProgressExists) {
                 missionResult = {
@@ -753,8 +823,8 @@ function buildAuditCommand() {
                             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`,
+                            message: `PROGRESS.md exists but no SPEC.md or legacy README.md (orphan progress rail, no backing scope item)`,
+                            remediation: `Add SPEC.md with frontmatter id, or remove the orphan PROGRESS.md`,
                         }],
                     frontmatterError: null,
                 };
@@ -771,22 +841,16 @@ function buildAuditCommand() {
                     readmeOnlyMarker: false,
                     isActiveRelease: true,
                     level: "mission",
-                    missionBriefExists,
-                    missionBriefPath: missionBrief,
-                    missionBriefContent: missionBriefExists ? fs.readFileSync(missionBrief, "utf-8") : null,
-                    missionNotesExists: fs.existsSync(missionNotes),
-                    missionNotesPath: missionNotes,
+                    missionNotesResolution,
+                    missionNotesPath,
                 });
             }
             const missionShadow = shadowedNodeFileFinding(missionDir, "mission");
             if (missionShadow)
                 missionResult.findings.push(missionShadow);
+            missionResult.findings.push(...capabilityDeltaExpiryFindings(missionDir));
             const slicesDir = path.join(missionDir, "slices");
             const dogfoodEvidenceRoot = defaultDogfoodEvidenceRoot(missionsRoot);
-            // Git-derived input for the committed-without-PROGRESS check (CLI-only).
-            // Revision basis = the most recent commit (HEAD). null when git context
-            // is unavailable → the check is left inert per-slice below.
-            const headTouched = gitHeadTouchedAbsPaths(missionDir);
             const sliceResults = [];
             if (fs.existsSync(slicesDir)) {
                 for (const entry of fs.readdirSync(slicesDir)) {
@@ -807,8 +871,8 @@ function buildAuditCommand() {
                                             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`,
+                                            message: `PROGRESS.md exists but no SPEC.md or legacy README.md (orphan progress rail, no backing scope item)`,
+                                            remediation: `Add SPEC.md with frontmatter id, or remove the orphan PROGRESS.md`,
                                         }],
                                     frontmatterError: null,
                                 },
@@ -831,23 +895,6 @@ function buildAuditCommand() {
                     const sliceReadmeContent = fs.readFileSync(sliceReadme, "utf-8");
                     const sliceFm = extractFrontmatterRaw(sliceReadmeContent);
                     const readmeOnlyMarker = sliceFm !== null && /^progress_rail\s*:\s*readme-only/m.test(sliceFm);
-                    // committed-without-PROGRESS inputs (CLI-only; inert when git is
-                    // unavailable — leave both undefined so the check does not fire).
-                    // Normalize to realpath so a symlinked workspace (e.g. macOS
-                    // /var → /private/var) still matches git's realpath'd output.
-                    let sliceTouchedByRecentCommit;
-                    let progressTouchedByRecentCommit;
-                    if (headTouched) {
-                        let realSliceDir = sliceDir;
-                        try {
-                            realSliceDir = fs.realpathSync(sliceDir);
-                        }
-                        catch { /* keep sliceDir */ }
-                        const slicePrefix = realSliceDir.endsWith(path.sep) ? realSliceDir : realSliceDir + path.sep;
-                        const realSliceProgress = path.join(realSliceDir, "PROGRESS.md");
-                        sliceTouchedByRecentCommit = [...headTouched].some((p) => p === realSliceDir || p.startsWith(slicePrefix));
-                        progressTouchedByRecentCommit = headTouched.has(realSliceProgress);
-                    }
                     const sliceResult = classifyScopeItem({
                         id: null,
                         path: sliceDir,
@@ -862,12 +909,11 @@ function buildAuditCommand() {
                         proofDirPath: proofDir,
                         proofDirHasEntries: directoryHasEntries(proofDir),
                         hasProofPacket: hasProofPacketForSlice(dogfoodEvidenceRoot, entry),
-                        sliceTouchedByRecentCommit,
-                        progressTouchedByRecentCommit,
                         // OPR.0.4.4.19 FR-10 backstop inputs.
                         proofArtifacts: listProofArtifactsForAudit(proofDir),
                         implementationPrdExists: fs.existsSync(path.join(sliceDir, "IMPLEMENTATION-PRD.md")),
                         // OPR.0.4.4.23 convention-section advisory inputs.
+                        nodeFileName: path.basename(sliceReadme),
                         readmeContent: sliceReadmeContent,
                         implementationPrdContent: fs.existsSync(path.join(sliceDir, "IMPLEMENTATION-PRD.md"))
                             ? fs.readFileSync(path.join(sliceDir, "IMPLEMENTATION-PRD.md"), "utf-8")
@@ -907,6 +953,7 @@ function buildAuditCommand() {
                         // OPR.0.5.0.18 — amendment lineage (present only when re-stamped).
                         ...(s.attestations ? { attestations: s.attestations } : {}),
                     })),
+                    graph,
                     totalFindings: allFindings.length,
                 }, null, 2));
                 out.write("\n");
@@ -916,7 +963,14 @@ function buildAuditCommand() {
             }
             out.write(`Scope audit: ${missionName}\n`);
             out.write(`Mission rail: ${missionResult.railStatus}\n`);
-            out.write(`Slices: ${sliceResults.length} total\n\n`);
+            out.write(`Slices: ${sliceResults.length} total\n`);
+            out.write(`Ready: ${graph.ready.join(", ") || "(none)"}\n`);
+            for (const row of graph.waiting)
+                out.write(`Waiting: ${row.id} on ${row.on.join(", ")}\n`);
+            for (const row of graph.advisories) {
+                out.write(`Advisory: ${row.id}${row.dependency ? ` -> ${row.dependency}` : ""}: ${row.message}\n`);
+            }
+            out.write("\n");
             // OPR.0.5.0.18 — amendment lineage: a re-stamped slice shows the
             // CURRENT attestation + prior-count (the append-only audit rows
             // reconstruct the full history; this is the at-a-glance surface).
@@ -1228,9 +1282,9 @@ function buildSliceStageCommand() {
             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.",
+                    fact: `Slice ${slice.name} has no SPEC.md or legacy README.md.`,
+                    consequence: "Stage is a work-node frontmatter field; nothing to write.",
+                    action: "Create the slice with `rig scope slice create` before setting its stage.",
                 });
             }
             applyStage(slice.readmePath, stage, opts.successor);
@@ -1262,9 +1316,9 @@ function buildMissionStageCommand() {
             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.",
+                    fact: `Mission ${mission.name} has no SPEC.md or legacy README.md.`,
+                    consequence: "Stage is a work-node frontmatter field; nothing to write.",
+                    action: "Create the mission with `rig scope mission create` before setting its stage.",
                 });
             }
             applyStage(mission.readmePath, stage, opts.successor);
@@ -1296,9 +1350,9 @@ function buildSliceVerifiedCommand() {
             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.",
+                    fact: `Slice ${slice.name} has no SPEC.md or legacy README.md.`,
+                    consequence: "verified is a work-node frontmatter field; nothing to write.",
+                    action: "Create the slice with `rig scope slice create` before stamping verified.",
                 });
             }
             const verified = `${todayDateISO()} against ${source}`;
@@ -1327,9 +1381,9 @@ function buildMissionVerifiedCommand() {
             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.",
+                    fact: `Mission ${mission.name} has no SPEC.md or legacy README.md.`,
+                    consequence: "verified is a work-node frontmatter field; nothing to write.",
+                    action: "Create the mission with `rig scope mission create` before stamping verified.",
                 });
             }
             const verified = `${todayDateISO()} against ${source}`;
@@ -1359,16 +1413,34 @@ function mapLegacyStatusToStage(status) {
         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). */
+/** Preserve a malformed value before repair replaces it with the conformant
+ *  representation. A pre-existing preservation key means a prior repair has
+ *  already recorded a different original; refusing is the only lossless move. */
+function preserveMalformedFrontmatterValue(frontmatter, updates, key) {
+    if (!Object.prototype.hasOwnProperty.call(frontmatter, key))
+        return;
+    const preservedKey = `repair-original-${key.replaceAll("_", "-")}`;
+    if (Object.prototype.hasOwnProperty.call(frontmatter, preservedKey)) {
+        throw new ScopeCliError({
+            fact: `${key} is malformed and ${preservedKey} already exists.`,
+            consequence: "Repair refused rather than overwrite either authored value.",
+            action: `Resolve ${key} manually and retain ${preservedKey} as the prior-value record, then re-run repair.`,
+        });
+    }
+    updates[preservedKey] = frontmatter[key];
+}
+/** Idempotently conform a scope README's mandatory frontmatter. Adds absent
+ *  fields and replaces malformed ones only after preserving their values under
+ *  repair-original-* keys. A valid id/stage/verified is never touched.
+ *  `mintId` is called only when `id` is absent or malformed (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;
+    const hasId = typeof fm.id === "string" && fm.id.trim().length > 0;
     if (!hasId) {
+        preserveMalformedFrontmatterValue(fm, updates, "id");
         const minted = mintId();
         if (minted) {
             idAdded = minted;
@@ -1376,12 +1448,16 @@ function conformReadmeFrontmatter(readmePath, mintId) {
         }
     }
     let stageAdded = null;
-    if (!fm.stage) {
+    const hasStage = typeof fm.stage === "string" && STAGE_VALUES.includes(fm.stage);
+    if (!hasStage) {
+        preserveMalformedFrontmatterValue(fm, updates, "stage");
         stageAdded = mapLegacyStatusToStage(fm.status);
         updates.stage = stageAdded;
     }
     let verifiedAdded = null;
-    if (!fm.verified) {
+    const hasVerified = typeof fm.verified === "string" && fm.verified.trim().length > 0;
+    if (!hasVerified) {
+        preserveMalformedFrontmatterValue(fm, updates, "verified");
         verifiedAdded = `${todayDateISO()} against backfill (rig scope repair)`;
         updates.verified = verifiedAdded;
     }
@@ -1424,11 +1500,16 @@ function buildSliceRepairCommand() {
         const json = Boolean(opts.json);
         try {
             const missionsRoot = resolveMissionsRoot({ override: getOpts(command).workspace });
-            const slice = findSlice(missionsRoot, slicePath, opts.mission ?? null);
+            const legacySlice = findSlice(missionsRoot, slicePath, opts.mission ?? null);
+            const specPath = ensureCurrentSpec(legacySlice.absPath, legacySlice.readmePath, legacySlice.name);
+            const slice = findSlice(missionsRoot, legacySlice.absPath, opts.mission ?? null);
             const result = backfillScopeProgress(slice.absPath, "slice");
-            const frontmatter = slice.readmePath
-                ? conformReadmeFrontmatter(slice.readmePath, mintSliceIdClosure(slice, missionsRoot))
+            const frontmatter = specPath
+                ? conformReadmeFrontmatter(specPath, mintSliceIdClosure(slice, missionsRoot))
                 : { idAdded: null, stageAdded: null, verifiedAdded: null, changed: false };
+            if (specPath)
+                ensureConventionFrontmatter(specPath, slice.name);
+            ensureSliceProofSurface(slice.absPath, readFrontmatter(specPath ?? "").id, slice.name);
             emit(out, { ok: true, result, frontmatter }, json, [
                 `${result.created ? "Backfilled" : "Skipped"} ${slice.name}: ${result.reason}`,
                 ...(result.path ? [`  path: ${result.path}`] : []),
@@ -1450,6 +1531,8 @@ function buildMissionRepairCommand() {
         const json = Boolean(opts.json);
         try {
             const missionsRoot = resolveMissionsRoot({ override: getOpts(command).workspace });
+            const legacyMission = findMission(missionsRoot, missionName);
+            const missionSpec = ensureCurrentSpec(legacyMission.absPath, legacyMission.readmePath, legacyMission.name);
             const mission = findMission(missionsRoot, missionName);
             const results = [];
             results.push(backfillScopeProgress(mission.absPath, "mission"));
@@ -1465,15 +1548,21 @@ function buildMissionRepairCommand() {
             // 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));
+            if (missionSpec) {
+                const fm = conformReadmeFrontmatter(missionSpec, () => ensureMissionId(mission, missionsRoot));
+                ensureConventionFrontmatter(missionSpec, mission.name);
                 conformed.push({ scope: "mission", name: mission.name, frontmatter: fm });
             }
             const freshMission = findMission(missionsRoot, mission.name);
+            ensureMissionNotesSurface(freshMission.absPath, freshMission);
             for (const slice of listSlices(freshMission, "all")) {
-                if (!slice.readmePath)
+                const specPath = ensureCurrentSpec(slice.absPath, slice.readmePath, slice.name);
+                if (!specPath)
                     continue;
-                const fm = conformReadmeFrontmatter(slice.readmePath, mintSliceIdClosure(slice, missionsRoot));
+                const fm = conformReadmeFrontmatter(specPath, mintSliceIdClosure(slice, missionsRoot));
+                ensureConventionFrontmatter(specPath, slice.name);
+                backfillScopeProgress(slice.absPath, "slice");
+                ensureSliceProofSurface(slice.absPath, readFrontmatter(specPath).id, slice.name);
                 conformed.push({ scope: "slice", name: slice.name, frontmatter: fm });
             }
             const created = results.filter((r) => r.created);
@@ -1489,6 +1578,63 @@ function buildMissionRepairCommand() {
         }
     });
 }
+/** Add the current authored node beside a legacy README without touching the
+ * legacy file. Existing SPEC bytes stay in place. */
+function ensureCurrentSpec(dir, nodePath, fallbackName) {
+    const specPath = path.join(dir, "SPEC.md");
+    if (fs.existsSync(specPath))
+        return specPath;
+    if (!nodePath || !fs.existsSync(nodePath))
+        return null;
+    fs.copyFileSync(nodePath, specPath);
+    ensureConventionFrontmatter(specPath, fallbackName);
+    return specPath;
+}
+function ensureConventionFrontmatter(specPath, fallbackName) {
+    const content = fs.readFileSync(specPath, "utf8");
+    const { frontmatter, body } = splitFrontmatter(content);
+    const h2Intent = /^## Intent\s*\n+([\s\S]*?)(?=\n## |$)/m.exec(body)?.[1]?.trim();
+    const h1 = /^#\s+(.+)$/m.exec(body)?.[1]?.trim();
+    const updates = {};
+    if (!(typeof frontmatter.intent === "string" && frontmatter.intent.trim().length > 0)) {
+        preserveMalformedFrontmatterValue(frontmatter, updates, "intent");
+        updates.intent = h2Intent && !/^\[.*\]$/.test(h2Intent)
+            ? h2Intent
+            : h1 ?? titleFromSlug(fallbackName.replace(/^\d+-/, ""));
+    }
+    if (!Array.isArray(frontmatter.depends_on)) {
+        preserveMalformedFrontmatterValue(frontmatter, updates, "depends_on");
+        updates.depends_on = [];
+    }
+    if (Object.keys(updates).length > 0)
+        updateFrontmatter(specPath, updates);
+}
+function ensureMissionNotesSurface(dir, mission) {
+    const notesPath = path.join(dir, NOTES_FILE_PRECEDENCE[0]);
+    const resolved = resolveNotesFile(dir);
+    if (resolved?.name === NOTES_FILE_PRECEDENCE[0])
+        return;
+    if (resolved) {
+        fs.copyFileSync(resolved.path, notesPath);
+        return;
+    }
+    const rendered = renderNotesTemplate({
+        mission_id: mission.id ?? mission.name,
+        mission_name: typeof mission.frontmatter.intent === "string" ? mission.frontmatter.intent : mission.name,
+        created_date: todayDateISO(),
+    });
+    fs.writeFileSync(notesPath, rendered.rendered, "utf8");
+}
+function ensureSliceProofSurface(dir, rawId, fallbackName) {
+    fs.mkdirSync(path.join(dir, "proof"), { recursive: true });
+    const proofPath = path.join(dir, "PROOF.md");
+    if (fs.existsSync(proofPath))
+        return;
+    fs.writeFileSync(proofPath, renderSliceProofTemplate({
+        id: typeof rawId === "string" ? rawId : fallbackName,
+        title: titleFromSlug(fallbackName.replace(/^\d+-/, "")),
+    }), "utf8");
+}
 // ---------------------------------------------------------------------
 // Approve (OPR.0.4.4.19 FR-9)
 // ---------------------------------------------------------------------
@@ -1663,12 +1809,14 @@ export function scopeCommand() {
     mission.addCommand(buildMissionLsCommand());
     mission.addCommand(buildMissionShowCommand());
     mission.addCommand(buildMissionCreateCommand());
+    mission.addCommand(buildMissionGraphCommand());
     mission.addCommand(buildMissionProgressCommand());
     mission.addCommand(buildMissionRepairCommand());
     mission.addCommand(buildMissionStageCommand());
     mission.addCommand(buildMissionVerifiedCommand());
     mission.addCommand(buildApproveCommand("mission"));
     cmd.addCommand(mission);
+    cmd.addCommand(buildResolveNotesCommand());
     cmd.addCommand(buildAuditCommand());
     return cmd;
 }