@openrig/cli 0.4.3 → 0.4.4

package/dist/lib/file-transfer.js

@@ -0,0 +1,300 @@
+// OPR.0.4.4.18 — `rig file copy` core: path grammar, the FR-4 security wall,
+// the closed rsync argv builder, and result classification.
+//
+// SECURITY CELL (plan §3 + §7a/§7a-2, guard-cleared over three rounds):
+// five independent layers, every rejection BEFORE any spawn —
+//   1. GRAMMAR (fail-closed): a path is remote iff it carries an explicit
+//      `<hostId>:` qualifier; no inference from cwd/env/session (FR-2).
+//      Local-prefix escapes (`/ ./ ../ ~`); an id-shaped colon prefix MUST
+//      resolve or fail loudly (N18-1); leading-dash operands are refused
+//      outright with the ./ escape taught (G18-P1 belt).
+//   2. NORMALIZATION: local paths are ~-expanded + path.resolve'd and the
+//      RESOLVED form is what is checked and transported; remote paths
+//      reject ANY raw '..' SEGMENT BEFORE normalization (G18-C1: normalize
+//      COLLAPSES '..' in absolute paths, so a post-normalize check is dead
+//      code), then '.'/'//' are collapsed for the shipped form.
+//   3. THE REMOTE CHARSET WALL (G18-P3 — supersedes a --protect-args pin:
+//      this platform's rsync is OPENRSYNC, which rejects -s; never assume
+//      GNU parity on macOS): remote paths must be ABSOLUTE (arch Q5) and
+//      match ^[A-Za-z0-9._/-]+$ — every allowed character is POSIX-shell-
+//      inert, so the ssh-invoked remote shell has NOTHING to interpret:
+//      no word-split (space excluded), no glob (*?[] excluded), no
+//      expansion (~ $ excluded), no metacharacters. Rejections TEACH
+//      (offending char named + workaround; arch note, N18-2-revisitable).
+//   4. THE `--` OPERAND PIN (G18-P1 suspenders): the builder ALWAYS places
+//      `--` before the two path operands — a flag-shaped path can never
+//      parse as an option even if a future caller bypasses the refusal.
+//   5. NO SHELL locally: spawn("rsync", argv) with argv arrays; the -e ssh
+//      string is built ONLY from registry fields (user shape-checked).
+//   Deletion-class flags are UNREACHABLE (property-tested, incl. the
+//   `-s`/--protect-args ABSENCE uniformity pin).
+//
+// DENY WALL (FR-4, arch-endorsed SHORT CLOSED NAMED list — extension = a
+// ruling, never a growing blocklist): local side denies resolved paths under
+// ~/.openrig (live rig state — crash-safety class), ~/.ssh, ~/.codex,
+// ~/.claude (credential/shared-singleton classes); remote side denies any
+// path CONTAINING one of those dot-directory segments (conservative-over-
+// broad: /srv/backup/.ssh/x is still a credentials dir; false positives are
+// loud + revisitable, false negatives are the corruption class).
+import os from "node:os";
+import path from "node:path";
+import { spawn as nodeSpawn } from "node:child_process";
+import { loadHostRegistry, resolveHost } from "./../host-registry.js";
+import { looksLikePermissionGate } from "./../cross-host-executor.js";
+import { getDefaultOpenRigPath, getOpenRigHome } from "./../openrig-compat.js";
+const HOST_ID_SHAPE = /^[A-Za-z0-9_-]+$/;
+const SSH_USER_SHAPE = /^[A-Za-z0-9._-]+$/;
+export const REMOTE_PATH_CHARSET = /^[A-Za-z0-9._/-]+$/;
+/** The FR-4 short closed named deny list (dot-directory segments). */
+export const DENIED_SEGMENTS = [".openrig", ".ssh", ".codex", ".claude"];
+export function parseFilePathArg(raw) {
+    if (raw === "")
+        return { ok: false, error: "empty path operand" };
+    if (raw.startsWith("-")) {
+        // G18-P1 belt: a flag-shaped operand is refused outright; the ./ escape
+        // is the honest way to address such a file.
+        return {
+            ok: false,
+            error: `path operand '${raw}' begins with '-' and could be mistaken for an option. If this is a real local file, address it with the ./ prefix (./${raw}).`,
+        };
+    }
+    // Local-prefix escapes: these are ALWAYS local, colon or not (N18-1).
+    if (raw.startsWith("/") || raw.startsWith("./") || raw.startsWith("../") || raw.startsWith("~")) {
+        return { ok: true, arg: { kind: "local", path: raw } };
+    }
+    const colon = raw.indexOf(":");
+    if (colon >= 0) {
+        const prefix = raw.slice(0, colon);
+        const rest = raw.slice(colon + 1);
+        if (HOST_ID_SHAPE.test(prefix)) {
+            // Id-shaped prefix: this IS a host qualifier — it must resolve or the
+            // command fails loudly (fail-closed; never a silent local fallback).
+            if (rest === "")
+                return { ok: false, error: `remote path missing after '${prefix}:' — expected ${prefix}:<absolute-path>` };
+            return { ok: true, arg: { kind: "remote", hostId: prefix, path: rest } };
+        }
+        // Non-id-shaped prefix (contains '/', empty, etc.): scp's lived
+        // behavior — the whole operand is a local path.
+        return { ok: true, arg: { kind: "local", path: raw } };
+    }
+    return { ok: true, arg: { kind: "local", path: raw } };
+}
+// ── the deny wall + normalization ──────────────────────────────────────────
+function expandLocalTilde(p) {
+    if (p === "~")
+        return os.homedir();
+    if (p.startsWith("~/"))
+        return path.join(os.homedir(), p.slice(2));
+    return p;
+}
+/** Local side: ~-expand, resolve (traversal collapses here), then deny-check
+ *  the RESOLVED form. The resolved form is what rsync receives. */
+export function checkLocalPath(raw) {
+    const resolved = path.resolve(expandLocalTilde(raw));
+    const home = os.homedir();
+    const activeOpenRigHome = path.resolve(getOpenRigHome());
+    const activeHostsRegistry = path.resolve(getDefaultOpenRigPath("hosts.yaml"));
+    if (resolved === activeHostsRegistry) {
+        return {
+            ok: false,
+            error: `refused: '${raw}' resolves to the active hosts registry (${activeHostsRegistry}) — the registry itself is not a copy source/target in v0. This is the FR-4 default-deny wall (live OpenRig state; extension requires a ruling).`,
+        };
+    }
+    for (const segment of DENIED_SEGMENTS) {
+        const deniedRoot = path.join(home, segment);
+        if (resolved === deniedRoot || resolved.startsWith(deniedRoot + path.sep)) {
+            return {
+                ok: false,
+                error: `refused: '${raw}' resolves into ${deniedRoot} — ${segment === ".openrig" ? "live OpenRig state (incl. the hosts registry) is not a copy source/target in v0 (crash-safety)" : "credential/agent-home directories are not copy sources/targets"}. This is the FR-4 default-deny wall (a short closed list; extension requires a ruling).`,
+            };
+        }
+    }
+    if (activeOpenRigHome !== path.join(home, ".openrig") &&
+        (resolved === activeOpenRigHome || resolved.startsWith(activeOpenRigHome + path.sep))) {
+        return {
+            ok: false,
+            error: `refused: '${raw}' resolves into the active OPENRIG_HOME (${activeOpenRigHome}) — live OpenRig state is not a copy source/target in v0 (crash-safety). This is the FR-4 default-deny wall (a short closed list; extension requires a ruling).`,
+        };
+    }
+    return { ok: true, normalizedPath: resolved };
+}
+/** Remote side: posix-normalize, then the wall — absolute-only (arch Q5),
+ *  no surviving traversal, the shell-inert charset (G18-P3), and the
+ *  denied-segment list. Errors TEACH (offending char + workaround). */
+export function checkRemotePath(raw, hostId) {
+    const charsetViolation = [...raw].find((ch) => !REMOTE_PATH_CHARSET.test(ch));
+    if (charsetViolation !== undefined) {
+        const shown = charsetViolation === " " ? "a space" : `'${charsetViolation}'`;
+        return {
+            ok: false,
+            error: `refused: remote path for '${hostId}' contains ${shown}, which is outside the v0 remote-path character set [A-Za-z0-9._/-]. v0 keeps remote paths shell-inert by construction${charsetViolation === " " ? " — use a space-free staging path and rename on the far side" : ""}. (v0-conservative; widening is a ruling.)`,
+        };
+    }
+    if (!raw.startsWith("/")) {
+        return { ok: false, error: `refused: remote paths are ABSOLUTE-only in v0 (got '${raw}' for host '${hostId}') — remote ~/relative resolution would smuggle in remote-side semantics. Use the full path.` };
+    }
+    // G18-C1 (guard code-review): the RAW path is checked for '..' BEFORE
+    // normalization — posix.normalize fully COLLAPSES '..' in absolute paths
+    // (/srv/../../etc/passwd → /etc/passwd), so a post-normalize "surviving
+    // .." check is dead code and the climb escapes silently. In an
+    // absolute-only grammar a '..' segment is never necessary; ANY '..'
+    // rejects outright (no benign/escaping distinction — remote symlinks
+    // make that unreasonable to judge from here).
+    if (raw.split("/").includes("..")) {
+        return { ok: false, error: `refused: remote path '${raw}' contains a '..' traversal segment (FR-4). Remote paths are absolute-only — write the final path without '..'.` };
+    }
+    const normalized = path.posix.normalize(raw);
+    for (const part of normalized.split("/")) {
+        if (DENIED_SEGMENTS.includes(part)) {
+            return {
+                ok: false,
+                error: `refused: remote path '${raw}' contains the denied directory segment '${part}' (credential/rig-state class; conservative-over-broad by design — FR-4's short closed list).`,
+            };
+        }
+    }
+    return { ok: true, normalizedPath: normalized };
+}
+function resolveRemoteSide(hostId, rawPath, deps) {
+    const loader = deps.registryLoader ?? loadHostRegistry;
+    const reg = loader();
+    if (!reg.ok)
+        return { ok: false, error: reg.error, code: "registry_error" };
+    const resolved = resolveHost(reg.registry, hostId);
+    if (!resolved.ok)
+        return { ok: false, error: resolved.error, code: "unknown_host" };
+    if (resolved.host.transport !== "ssh") {
+        return {
+            ok: false,
+            error: `host '${hostId}' uses transport '${resolved.host.transport}' — v0 file movement is ssh/rsync only. Register an ssh entry for this host or move the file another way.`,
+            code: "unsupported_transport",
+        };
+    }
+    if (resolved.host.user !== undefined && !SSH_USER_SHAPE.test(resolved.host.user)) {
+        return { ok: false, error: `registry entry '${hostId}' has a user field outside [A-Za-z0-9._-] — refusing to place it on an ssh command line`, code: "invalid_registry_user" };
+    }
+    const pathCheck = checkRemotePath(rawPath, hostId);
+    if (!pathCheck.ok)
+        return { ok: false, error: pathCheck.error, code: "denied_path" };
+    return { ok: true, side: { kind: "remote", path: pathCheck.normalizedPath, host: resolved.host } };
+}
+/** Validate the whole invocation — EVERY rejection here happens before any
+ *  spawn (the fail-closed set; spawn-spy-asserted in tests). */
+export function planFileCopy(rawSrc, rawDst, opts = {}) {
+    const srcParse = parseFilePathArg(rawSrc);
+    if (!srcParse.ok)
+        return { ok: false, error: srcParse.error, code: "bad_operand" };
+    const dstParse = parseFilePathArg(rawDst);
+    if (!dstParse.ok)
+        return { ok: false, error: dstParse.error, code: "bad_operand" };
+    if (srcParse.arg.kind === "remote" && dstParse.arg.kind === "remote") {
+        return { ok: false, error: "remote-to-remote is not in v0; pull then push (two explicit transfers — never a silent relay through this host)", code: "remote_to_remote" };
+    }
+    const sides = [];
+    for (const parsed of [srcParse.arg, dstParse.arg]) {
+        if (parsed.kind === "remote") {
+            const side = resolveRemoteSide(parsed.hostId, parsed.path, opts);
+            if (!side.ok)
+                return { ok: false, error: side.error, code: side.code };
+            sides.push(side.side);
+        }
+        else {
+            const check = checkLocalPath(parsed.path);
+            if (!check.ok)
+                return { ok: false, error: check.error, code: "denied_path" };
+            sides.push({ kind: "local", path: check.normalizedPath });
+        }
+    }
+    return { ok: true, plan: { src: sides[0], dst: sides[1], dryRun: opts.dryRun === true } };
+}
+// ── the CLOSED argv builder ─────────────────────────────────────────────────
+function sideOperand(side) {
+    if (side.kind === "local")
+        return side.path;
+    return `${side.host.target}:${side.path}`;
+}
+/** The ONLY place rsync arguments are assembled. Properties (test-asserted):
+ *  no deletion-class flag ever present; NO -s/--protect-args (uniform argv
+ *  across GNU rsync and openrsync — the G18-P3 absence pin); `--` ALWAYS
+ *  precedes the two path operands; option positions are fixed. */
+export function buildRsyncArgv(plan) {
+    const argv = ["--archive", "--itemize-changes", "--stats"];
+    if (plan.dryRun)
+        argv.push("--dry-run");
+    const remote = plan.src.kind === "remote" ? plan.src : plan.dst.kind === "remote" ? plan.dst : null;
+    if (remote) {
+        const sshParts = ["ssh", "-o", "ConnectTimeout=10"];
+        if (remote.host.user)
+            sshParts.push("-l", remote.host.user);
+        argv.push("-e", sshParts.join(" "));
+    }
+    argv.push("--", sideOperand(plan.src), sideOperand(plan.dst));
+    return argv;
+}
+const CONNECTION_FAILURE_PATTERNS = [
+    /connection refused/i,
+    /connection timed out/i,
+    /connection unexpectedly closed/i,
+    /could not resolve hostname/i,
+    /no route to host/i,
+    /operation timed out/i,
+];
+function parseStats(stdout) {
+    const bytes = stdout.match(/Total transferred file size:\s*([\d,.]+)\s*bytes/i);
+    const files = stdout.match(/Number of (?:regular )?files transferred:\s*([\d,.]+)/i);
+    const num = (m) => (m ? Number(m[1].replace(/[,.](?=\d{3})/g, "").replace(/,/g, "")) : undefined);
+    return { bytesTransferred: num(bytes), filesTransferred: num(files) };
+}
+/** rsync's classes are the executor taxonomy MINUS remote-daemon-unreachable
+ *  (rsync needs no daemon — arch ruling 2). */
+export function classifyRsyncResult(exitCode, stdout, stderr) {
+    if (exitCode === 0) {
+        return { ok: true, failedStep: "none", exitCode, stdout, stderr, ...parseStats(stdout) };
+    }
+    if (looksLikePermissionGate(stderr)) {
+        return {
+            ok: false,
+            failedStep: "permission-gate",
+            exitCode,
+            stdout,
+            stderr,
+            hint: "See openrig-work/field-notes/2026-04-29-l4-3-d6-claude-keychain-over-ssh-diagnostic.md for guidance on Keychain-over-SSH issues.",
+        };
+    }
+    if (exitCode === 255 || CONNECTION_FAILURE_PATTERNS.some((re) => re.test(stderr))) {
+        return { ok: false, failedStep: "ssh-unreachable", exitCode, stdout, stderr };
+    }
+    return { ok: false, failedStep: "remote-command-failed", exitCode, stdout, stderr };
+}
+export async function runFileCopy(plan, deps = {}) {
+    const argv = buildRsyncArgv(plan);
+    const spawn = deps.spawn ?? nodeSpawn;
+    const child = spawn("rsync", argv, { stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    let spawnFailed = null;
+    child.stdout?.on("data", (chunk) => {
+        stdout += typeof chunk === "string" ? chunk : chunk.toString("utf-8");
+    });
+    child.stderr?.on("data", (chunk) => {
+        stderr += typeof chunk === "string" ? chunk : chunk.toString("utf-8");
+    });
+    const exitCode = await new Promise((resolve) => {
+        child.on("error", (err) => {
+            spawnFailed = err;
+            resolve(null);
+        });
+        child.on("close", (code) => resolve(code));
+    });
+    if (spawnFailed !== null && spawnFailed.code === "ENOENT") {
+        return {
+            ok: false,
+            failedStep: "rsync-missing",
+            exitCode: null,
+            stdout,
+            stderr,
+            hint: "rsync is not installed locally. macOS: `brew install rsync` (or use the system openrsync ≥ the one shipped with your OS); Linux: install the rsync package.",
+        };
+    }
+    return classifyRsyncResult(exitCode, stdout, stderr);
+}
+//# sourceMappingURL=file-transfer.js.map

package/dist/lib/file-transfer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-transfer.js","sourceRoot":"","sources":["../../src/lib/file-transfer.ts"],"names":[],"mappings":"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"}

package/dist/lib/hosts/fanout-contract.d.ts

@@ -0,0 +1,33 @@
+/** The local host's id literal in every P3/P4 payload (arch pin: defined
+ *  ONCE here, imported everywhere, never retyped). Matches slice 11's
+ *  topology aggregate literal. */
+export declare const LOCAL_HOST_ID = "local";
+/** CLOSED enum (arch pin A). `unsupported-transport` is R15-2's explicit
+ *  class (an SSH-declared host is never a silently thinner payload);
+ *  `auth-failed` is distinct from `unreachable` because the operator fix
+ *  differs (rotate/set the bearer vs check the host). Extending this set =
+ *  a cross-PRD contract change (slices 15 AND 21 re-review). */
+export type PerHostStatusKind = "ok" | "unreachable" | "unsupported-transport" | "auth-failed";
+export interface PerHostStatus {
+    hostId: string;
+    status: PerHostStatusKind;
+    /** Honest failure detail, rendered muted next to the host chip/row. */
+    error?: string;
+    /** ADDITIVE OPTIONAL detail (arch adjudication): the shipped CLI
+     *  FailedStep vocabulary when a transport-level step classified the
+     *  failure. Never load-bearing — `status` is the contract. */
+    failedStep?: string;
+}
+/** items + per-host status: EVERY subscribed host appears in `hosts` on
+ *  EVERY payload — ok, unreachable, auth-failed, or unsupported-transport.
+ *  Absence is a contract violation (omission-proof; never all-or-nothing,
+ *  never silent thinning). */
+export interface AggregatedPayload<T> {
+    items: T[];
+    hosts: PerHostStatus[];
+}
+/** Contract-level completeness predicate (arch pin B: asserted as near to
+ *  the contract as tests allow): true iff every expected host id appears
+ *  exactly once in the payload's hosts array. */
+export declare function hostsCovered(payload: AggregatedPayload<unknown>, expectedHostIds: string[]): boolean;
+//# sourceMappingURL=fanout-contract.d.ts.map

package/dist/lib/hosts/fanout-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fanout-contract.d.ts","sourceRoot":"","sources":["../../../src/lib/hosts/fanout-contract.ts"],"names":[],"mappings":"AAUA;;kCAEkC;AAClC,eAAO,MAAM,aAAa,UAAU,CAAC;AAErC;;;;gEAIgE;AAChE,MAAM,MAAM,iBAAiB,GAAG,IAAI,GAAG,aAAa,GAAG,uBAAuB,GAAG,aAAa,CAAC;AAE/F,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,iBAAiB,CAAC;IAC1B,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;kEAE8D;IAC9D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;8BAG8B;AAC9B,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,KAAK,EAAE,CAAC,EAAE,CAAC;IACX,KAAK,EAAE,aAAa,EAAE,CAAC;CACxB;AAED;;iDAEiD;AACjD,wBAAgB,YAAY,CAAC,OAAO,EAAE,iBAAiB,CAAC,OAAO,CAAC,EAAE,eAAe,EAAE,MAAM,EAAE,GAAG,OAAO,CAIpG"}

package/dist/lib/hosts/fanout-contract.js

@@ -0,0 +1,23 @@
+// OPR.0.4.4.15 — THE shared intra-P4 fan-out payload contract.
+//
+// ONE contract for the whole P4 packet (arch adjudication 2026-07-05,
+// cross-PRD interface cell): slice 15's aggregated For-You attention feed
+// AND slice 21's `rig ps --all-hosts` rollup both speak AggregatedPayload —
+// items plus a per-host structured status array. Slice 15 defines this
+// module (first lander, per the whichever-builds-first rule named in both
+// PRDs); slice 21 IMPORTS it. Any change here is a CROSS-PRD contract
+// change requiring re-review of BOTH slices — never driver discretion.
+/** The local host's id literal in every P3/P4 payload (arch pin: defined
+ *  ONCE here, imported everywhere, never retyped). Matches slice 11's
+ *  topology aggregate literal. */
+export const LOCAL_HOST_ID = "local";
+/** Contract-level completeness predicate (arch pin B: asserted as near to
+ *  the contract as tests allow): true iff every expected host id appears
+ *  exactly once in the payload's hosts array. */
+export function hostsCovered(payload, expectedHostIds) {
+    const seen = new Map();
+    for (const h of payload.hosts)
+        seen.set(h.hostId, (seen.get(h.hostId) ?? 0) + 1);
+    return expectedHostIds.every((id) => seen.get(id) === 1) && payload.hosts.length === expectedHostIds.length;
+}
+//# sourceMappingURL=fanout-contract.js.map

package/dist/lib/hosts/fanout-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fanout-contract.js","sourceRoot":"","sources":["../../../src/lib/hosts/fanout-contract.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,EAAE;AACF,sEAAsE;AACtE,0EAA0E;AAC1E,4EAA4E;AAC5E,uEAAuE;AACvE,0EAA0E;AAC1E,sEAAsE;AACtE,uEAAuE;AAEvE;;kCAEkC;AAClC,MAAM,CAAC,MAAM,aAAa,GAAG,OAAO,CAAC;AA6BrC;;iDAEiD;AACjD,MAAM,UAAU,YAAY,CAAC,OAAmC,EAAE,eAAyB;IACzF,MAAM,IAAI,GAAG,IAAI,GAAG,EAAkB,CAAC;IACvC,KAAK,MAAM,CAAC,IAAI,OAAO,CAAC,KAAK;QAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACjF,OAAO,eAAe,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,CAAC,MAAM,KAAK,eAAe,CAAC,MAAM,CAAC;AAC9G,CAAC"}

package/dist/lib/scope/scope-audit.d.ts

@@ -1,6 +1,6 @@
 export type RailStatus = "present" | "missing" | "malformed" | "readme-only";
 export type FindingSeverity = "high" | "medium" | "low" | "info";
-export type FindingKind = "missing_progress" | "registration_ghost" | "missing_id" | "id_convention_violation" | "orphan_progress" | "missing_mission_brief" | "malformed_mission_brief" | "missing_mission_notes" | "missing_proof" | "progress_not_updated_on_commit";
+export type FindingKind = "missing_progress" | "registration_ghost" | "missing_id" | "id_convention_violation" | "orphan_progress" | "missing_mission_brief" | "malformed_mission_brief" | "missing_mission_notes" | "missing_proof" | "progress_not_updated_on_commit" | "proof_artifact_c1_invalid" | "missing_impl_prd" | "missing_intent_section" | "mini_requirements_missing_or_malformed" | "proof_contract_missing_or_malformed" | "ui_slice_missing_mockup";
 export interface AuditFinding {
     kind: FindingKind;
     severity: FindingSeverity;
@@ -30,11 +30,19 @@ export interface ScopeAuditInput {
     sliceStatus?: string | null;
     sliceTouchedByRecentCommit?: boolean;
     progressTouchedByRecentCommit?: boolean;
+    proofArtifacts?: Array<{
+        path: string;
+        frontmatterRaw: string | null;
+    }>;
+    implementationPrdExists?: boolean;
+    readmeContent?: string | null;
+    implementationPrdContent?: string | null;
 }
 export interface ScopeAuditResult {
     railStatus: RailStatus;
     findings: AuditFinding[];
     frontmatterError: string | null;
 }
+export declare const MISSION_BRIEF_HEADERS: string[];
 export declare function classifyScopeItem(input: ScopeAuditInput): ScopeAuditResult;
 //# sourceMappingURL=scope-audit.d.ts.map

package/dist/lib/scope/scope-audit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scope-audit.d.ts","sourceRoot":"","sources":["../../../src/lib/scope/scope-audit.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,aAAa,CAAC;AAC7E,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;AACjE,MAAM,MAAM,WAAW,GACnB,kBAAkB,GAClB,oBAAoB,GACpB,YAAY,GACZ,yBAAyB,GACzB,iBAAiB,GACjB,uBAAuB,GACvB,yBAAyB,GACzB,uBAAuB,GACvB,eAAe,GACf,gCAAgC,CAAC;AAErC,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,WAAW,CAAC;IAClB,QAAQ,EAAE,eAAe,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,kBAAkB,EAAE,OAAO,CAAC;IAC5B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,eAAe,EAAE,OAAO,CAAC;IACzB,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC;IAC3B,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAQ5B,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC,6BAA6B,CAAC,EAAE,OAAO,CAAC;CACzC;AAED,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,UAAU,CAAC;IACvB,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AA2DD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,eAAe,GAAG,gBAAgB,CAwK1E"}
+{"version":3,"file":"scope-audit.d.ts","sourceRoot":"","sources":["../../../src/lib/scope/scope-audit.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,aAAa,CAAC;AAC7E,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;AACjE,MAAM,MAAM,WAAW,GACnB,kBAAkB,GAClB,oBAAoB,GACpB,YAAY,GACZ,yBAAyB,GACzB,iBAAiB,GACjB,uBAAuB,GACvB,yBAAyB,GACzB,uBAAuB,GACvB,eAAe,GACf,gCAAgC,GAGhC,2BAA2B,GAC3B,kBAAkB,GAIlB,wBAAwB,GACxB,wCAAwC,GACxC,qCAAqC,GACrC,yBAAyB,CAAC;AAE9B,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,WAAW,CAAC;IAClB,QAAQ,EAAE,eAAe,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,kBAAkB,EAAE,OAAO,CAAC;IAC5B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,eAAe,EAAE,OAAO,CAAC;IACzB,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC;IAC3B,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAQ5B,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC,6BAA6B,CAAC,EAAE,OAAO,CAAC;IAMxC,cAAc,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;IAGxE,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAKlC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,wBAAwB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1C;AAED,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,UAAU,CAAC;IACvB,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAMD,eAAO,MAAM,qBAAqB,UAA4E,CAAC;AA2H/G,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,eAAe,GAAG,gBAAgB,CAqR1E"}

package/dist/lib/scope/scope-audit.js

@@ -1,6 +1,10 @@
 import * as YAML from "yaml";
 import { isMissionDotId, isSliceDotId } from "./dot-id.js";
-const MISSION_BRIEF_HEADERS = ["What & why", "Building", "Progress", "Proven", "Needs you", "Pointers"];
+// OPR.0.4.4.20 FR-8: exported so the review brief-spine writer conforms to
+// the SAME pinned exact-order schema this audit enforces (parity by
+// construction — the generated output can never trip malformed_mission_brief
+// without this file changing too).
+export const MISSION_BRIEF_HEADERS = ["What & why", "Building", "Progress", "Proven", "Needs you", "Pointers"];
 function childPath(parent, child) {
     return parent.endsWith("/") ? `${parent}${child}` : `${parent}/${child}`;
 }
@@ -44,6 +48,71 @@ function statusRequiresProof(status) {
         || normalized.includes("proven")
         || normalized.includes("promoted");
 }
+// OPR.0.4.4.19 FR-10 (C7) — the statusRequiresProof pattern applied one
+// phase earlier: a slice whose status implies SPECCED/BUILDING (or later)
+// must carry IMPLEMENTATION-PRD.md at its root ("no build without a
+// specifying doc"). Shaping / pre-spec statuses are NOT violations.
+function statusRequiresSpec(status) {
+    if (!status)
+        return false;
+    const normalized = status.toLowerCase().trim();
+    return normalized.includes("build")
+        || normalized.includes("implement")
+        || normalized.includes("in-progress")
+        || normalized.includes("review")
+        || normalized.includes("qa")
+        || statusRequiresProof(normalized);
+}
+// OPR.0.4.4.19 FR-10 (C1) — the ratified closed sets (BR-4; source of truth
+// for the drop path lives in the CLI proof command; this mirrored file
+// carries its own copy because both scope-audit copies must stay
+// self-contained + byte-identical. Extending the sets is a pm-lead
+// convention change, made in BOTH places).
+const C1_REQUIRED_FIELDS = ["slice", "candidate_sha", "artifact_type", "verdict", "money_evidence"];
+const C1_ARTIFACT_TYPES = ["guard", "qa", "rev1-r1", "rev1-r2", "adjudication"];
+const C1_VERDICTS = ["CLEAR", "BLOCKING", "CONCERNING", "PASS", "NOT-CLEAR"];
+/** Validate one proof artifact's raw frontmatter against the C1 contract.
+ *  Returns null when valid; else the human-readable problem list. */
+function c1ArtifactProblems(frontmatterRaw) {
+    if (frontmatterRaw === null) {
+        return [`no frontmatter header at all (required C1 fields: ${C1_REQUIRED_FIELDS.join(", ")})`];
+    }
+    let parsed = null;
+    try {
+        parsed = YAML.parse(frontmatterRaw);
+    }
+    catch (err) {
+        return [`frontmatter fails to parse: ${err instanceof Error ? err.message : String(err)}`];
+    }
+    const fm = parsed && typeof parsed === "object" && !Array.isArray(parsed)
+        ? parsed
+        : {};
+    const problems = [];
+    const missing = C1_REQUIRED_FIELDS.filter((f) => typeof fm[f] !== "string" || fm[f].trim().length === 0);
+    if (missing.length > 0)
+        problems.push(`missing field(s): ${missing.join(", ")}`);
+    if (typeof fm.artifact_type === "string" && !C1_ARTIFACT_TYPES.includes(fm.artifact_type)) {
+        problems.push(`artifact_type '${fm.artifact_type}' not in closed set (${C1_ARTIFACT_TYPES.join(" | ")})`);
+    }
+    if (typeof fm.verdict === "string" && !C1_VERDICTS.includes(fm.verdict)) {
+        problems.push(`verdict '${fm.verdict}' not in closed set (${C1_VERDICTS.join(" | ")})`);
+    }
+    return problems.length > 0 ? problems : null;
+}
+// OPR.0.4.4.23 — markdown H2-section helpers for the convention-section
+// advisories. Headings are literals owned by this file ("Intent",
+// "Proof contract", "Intent visual") — no user input reaches the regex.
+function hasH2(content, heading) {
+    return new RegExp(`^##\\s+${heading}\\s*$`, "m").test(content);
+}
+function h2Body(content, heading) {
+    const match = new RegExp(`^##\\s+${heading}\\s*$`, "m").exec(content);
+    if (!match)
+        return null;
+    const rest = content.slice(match.index + match[0].length);
+    const next = rest.search(/^##\s+/m);
+    return next === -1 ? rest : rest.slice(0, next);
+}
 // A mission is ACTIVE unless its status names a terminal / archived state.
 // The SOP wants missing_mission_notes to fire for an ACTIVE mission only — a
 // shipped/archived mission no longer needs a live continuity file. No status
@@ -198,6 +267,109 @@ export function classifyScopeItem(input) {
                 remediation: "Add PROOF.md at the slice root and put verification artifacts under proof/ per the slice-closeout SOP.",
             });
         }
+        // OPR.0.4.4.19 FR-10 (C1 backstop) — flag proof/ artifacts missing the
+        // C1 header or carrying out-of-set values. The backstop catches what
+        // bypassed the drop path (raw file writes are never gated at write
+        // time; this is where they surface).
+        for (const artifact of input.proofArtifacts ?? []) {
+            const problems = c1ArtifactProblems(artifact.frontmatterRaw);
+            if (problems) {
+                findings.push({
+                    kind: "proof_artifact_c1_invalid",
+                    severity: "medium",
+                    path: artifact.path,
+                    message: `Proof artifact violates the C1 header contract: ${problems.join("; ")}.`,
+                    remediation: `Re-drop via: rig proof add <slice> --artifact-type <${C1_ARTIFACT_TYPES.join("|")}> --verdict <${C1_VERDICTS.join("|")}> --candidate-sha <sha> --money-evidence "<line>" — or add the missing frontmatter fields in place.`,
+                });
+            }
+        }
+        // OPR.0.4.4.19 FR-10 (C7 backstop) — a specced/building-or-later slice
+        // must carry IMPLEMENTATION-PRD.md (the pinned expected filename) at its
+        // root. Status-gated: shaping is not a violation. Inert when the caller
+        // provided no fs context (implementationPrdExists undefined).
+        if (input.implementationPrdExists === false && statusRequiresSpec(status)) {
+            findings.push({
+                kind: "missing_impl_prd",
+                severity: "medium",
+                path: childPath(input.path, "IMPLEMENTATION-PRD.md"),
+                message: `Slice status "${status}" implies specced/building but there is no IMPLEMENTATION-PRD.md at the slice root (C7: no build without a specifying doc).`,
+                remediation: "Author (or relocate) the slice's IMPLEMENTATION-PRD.md at the slice root — the pinned C7 filename — before building continues.",
+            });
+        }
+        // OPR.0.4.4.23 — SDLC convention-section advisories (SSOT:
+        // docs/reference/sdlc-conventions.md). Structurally fail-open: the
+        // audit command flips its exit code on HIGH findings only, and these
+        // are low/info by construction — they record and advise, never gate.
+        // Inert when the caller provided no content context (undefined inputs).
+        if (typeof input.readmeContent === "string" && !hasH2(input.readmeContent, "Intent")) {
+            findings.push({
+                kind: "missing_intent_section",
+                severity: "low",
+                path: childPath(input.path, "README.md"),
+                message: "Slice README has no `## Intent` section, so the Living Notes UI cannot project its INTENT section.",
+                remediation: "Add `## Intent` carrying the recorded intent verbatim (conventions SSOT: docs/reference/sdlc-conventions.md; `rig scope slice create` scaffolds it).",
+            });
+        }
+        const contractSource = typeof input.implementationPrdContent === "string"
+            ? { content: input.implementationPrdContent, path: childPath(input.path, "IMPLEMENTATION-PRD.md") }
+            : typeof input.readmeContent === "string"
+                ? { content: input.readmeContent, path: childPath(input.path, "README.md") }
+                : null;
+        if (contractSource) {
+            // OPR.0.4.4.23 rev1-r2 B1 (PRD L34 guard F-3): well-formed
+            // `## Mini-requirements` — the PLAN leg of the Living Notes
+            // projection. Same source-selection policy as the proof contract
+            // (PRD preferred, README fallback). Well-formed = the heading plus
+            // at least one numbered list item; a heading over prose-only is
+            // malformed (no usable requirements projection).
+            const miniBody = h2Body(contractSource.content, "Mini-requirements");
+            const hasNumberedItem = miniBody !== null && /^\s*\d+\.\s+\S/m.test(miniBody);
+            if (!hasNumberedItem) {
+                findings.push({
+                    kind: "mini_requirements_missing_or_malformed",
+                    severity: "low",
+                    path: contractSource.path,
+                    message: miniBody === null
+                        ? "No `## Mini-requirements` section — the Living Notes PLAN section has no concise requirements tier to project."
+                        : "`## Mini-requirements` carries no numbered items (`1. …`) — the one-glance requirement tier is where approval starts.",
+                    remediation: "Add `## Mini-requirements` with a numbered list of observable outcomes (conventions SSOT: docs/reference/sdlc-conventions.md; for a small slice this may BE the whole PRD).",
+                });
+            }
+            const contractBody = h2Body(contractSource.content, "Proof contract");
+            const hasCheckboxItem = contractBody !== null && /^\s*-\s*\[[ xX]\]/m.test(contractBody);
+            if (!hasCheckboxItem) {
+                findings.push({
+                    kind: "proof_contract_missing_or_malformed",
+                    severity: "low",
+                    path: contractSource.path,
+                    message: contractBody === null
+                        ? "No `## Proof contract` section — the DELIVERED pairing has no promised-deliverables source to join proof against."
+                        : "`## Proof contract` carries no checkbox deliverables (`- [ ] …`) — the DELIVERED pairing joins proof against those items.",
+                    remediation: "Add `## Proof contract` with one checkbox line per promised deliverable, written as an observable outcome (conventions SSOT: docs/reference/sdlc-conventions.md).",
+                });
+            }
+            if (typeof input.readmeContent === "string") {
+                const visualBody = h2Body(input.readmeContent, "Intent visual");
+                const isUiSlice = visualBody !== null && !/\bN\/A\b/i.test(visualBody);
+                // rev1-r2 B2: a mockup is PRESENT only via a real markdown
+                // image/media ref in `## Intent visual` or an explicit plannedRef
+                // token in the proof contract. Generic prose containing the word
+                // "mockup" (the scaffold placeholder says "name their planned
+                // mockup") is NOT a reference and must not suppress the advisory.
+                const hasMockupRef = /!\[/.test(visualBody ?? "")
+                    || /plannedRef/i.test(contractBody ?? "")
+                    || /!\[/.test(contractBody ?? "");
+                if (isUiSlice && !hasMockupRef) {
+                    findings.push({
+                        kind: "ui_slice_missing_mockup",
+                        severity: "info",
+                        path: childPath(input.path, "README.md"),
+                        message: "Slice declares an Intent visual (UI slice) but no mockup reference is present — a UI slice with no mockup in its locked set is an incomplete plan.",
+                        remediation: "Attach the planned mockup: an image ref in `## Intent visual` or a plannedRef on the proof-contract deliverable (conventions SSOT: docs/reference/sdlc-conventions.md §3).",
+                    });
+                }
+            }
+        }
         // committed-without-PROGRESS. Fires only on POSITIVE evidence: the most
         // recent commit (HEAD) touched this slice AND definitively did NOT touch its
         // PROGRESS.md. Inputs are git-derived and CLI-only; when git context is