rcf-lite 0.26.0 → 0.28.0

package/rcf/user-stories/us-7701.json

@@ -1,6 +1,6 @@
 {
   "createdAt": "2026-09-07T14:11:54.740Z",
-  "updatedAt": "2026-09-07T14:13:26.508Z",
+  "updatedAt": "2026-09-09T23:00:00.000Z",
   "usId": "US-7701",
   "prdId": "PRD-001",
   "reqId": "REQ-077",
@@ -13,9 +13,9 @@
   "acceptanceCriteria": [
     {
       "id": "AC-7701-1",
-      "description": "The fixture wrangler.toml carries at least two [[durable_objects.bindings]] blocks (one binding named CELL with class_name SingleCellObject; one binding named HUB with class_name HubObject) and at least one [[migrations]] block with tag \"v1\" and new_classes = [\"SingleCellObject\", \"HubObject\"]. The anatomy assertion greps the toml for each literal string and the migrations pair.",
+      "description": "The fixture wrangler.toml carries at least two [[durable_objects.bindings]] blocks (one binding named CELL with class_name SingleCellObject; one binding named HUB with class_name HubObject) and at least one [[migrations]] block with tag \"v1\" and new_sqlite_classes = [\"SingleCellObject\", \"HubObject\"]. The anatomy assertion greps the toml for each literal string and the migrations pair.",
       "given": "the cf-platform fixture wrangler.toml",
-      "when": "the anatomy assertion greps for the four literal strings and the migrations pair",
+      "when": "the anatomy assertion greps for the four literal strings and the migrations pair (new_sqlite_classes plus the two class names)",
       "then": "every string is present and the migrations tag \"v1\" carries the two class names",
       "testable": true,
       "scope": "runtime"

package/releases/releases.yaml

@@ -40,8 +40,28 @@
 # `npm install rcf-lite`.
 
 feedVersion: 1
-latest: "0.26.0"
+latest: "0.28.0"
 releases:
+  - version: "0.28.0"
+    date: "2026-09-17"
+    breaking: false
+    headlines:
+      - "rcf-lite 0.28.0 lands two referee-facing trains together. The rcf feedback verb family lets an agent record what a blueprint or rcf-lite did that contradicts its own docs, fails, or forces a workaround, and after one operator yes at a natural pause files each finding as a GitHub issue under the operator's own gh login, or writes a pastable outbox bundle when gh is not available."
+      - "The referee-guarantees train tightens the three sentences the docs page makes about rcf define validate, rcf audit coverage and rcf build finalise: validate now walks ADR supersededBy, coverage is strict by default with --mode shallow-any as the deliberate opt-out, and finalise refuses on the three per-AC verdicts, gates the manual verified override behind --acknowledge-verified-override, and adds a merge-state precondition with --allow-pre-merge as the deliberate pre-merge dry-run opt-out."
+      - "rcf init merges three hook entries into .claude/settings.json and .codex/hooks.json so the feedback ask fires once per session at idle; RULE 17 lands in the managed instructions block as the belt-and-braces path. Coverage-strict-by-default is the single migration surface: run rcf audit coverage --mode shallow-any when the intent is a printed gap report rather than a gate."
+    minAgentAction: rerun-init
+    notesUrl: "https://stravica.ai/docs/rcf/changelog/"
+
+  - version: "0.27.0"
+    date: "2026-09-11"
+    breaking: false
+    headlines:
+      - "rcf-lite 0.27.0 is a shelf-wide hardening release. Every shipped blueprint has been re-verified against the 2026-09-08 authoring criteria, so every requirement is backed at the REQ layer, every user story carries a sufficient acceptance-criteria set with disposition and owner references, and chain-consistency lint reports zero on every slug."
+      - "Shipped prose is now customer-facing throughout, with internal workflow labels, operator names, work-item and dispatch identifiers, and long dashes removed. CI adds a hard register-scan gate and flips the chain-consistency lint gate to hard mode over the monorepo-root shelf."
+      - "One CLI reliability fix rides along: the rcf audit view SIGINT handler is now installed before the readiness line is written, closing a race with Node's default signal disposition."
+    minAgentAction: null
+    notesUrl: "https://stravica.ai/docs/rcf/changelog/"
+
   - version: "0.26.0"
     date: "2026-09-09"
     breaking: false

package/src/blueprint/library-loader.js

@@ -59,6 +59,18 @@ const LIBRARY_VERSION_KNOWN = 1;
  * @property {string} [contact]
  */
 
+/**
+ * @typedef {object} LibraryIssuesField
+ * @property {string} repo          OWNER/REPO on github.com; HOST/OWNER/REPO permitted for GHES
+ * @property {'public' | 'private'} visibility  advisory; the tool re-checks live on submit
+ *
+ * The library owner names where feedback reports on this library are
+ * filed (design 3.3, ADR-4104). Absence is valid; the consuming
+ * project's `rcf doctor feedback-destinations` warns until the field
+ * lands. Snapshotted onto the registry entry as `issuesRepo` and
+ * `issuesVisibility` on `library add`.
+ */
+
 /**
  * @typedef {object} LoadedLibrary
  * @property {number} libraryVersion
@@ -69,6 +81,7 @@ const LIBRARY_VERSION_KNOWN = 1;
  * @property {LibraryBands} bands
  * @property {LibraryBlueprintEntry[]} blueprints
  * @property {string} [notes]
+ * @property {LibraryIssuesField} [issues]
  * @property {string} root              absolute path to the library root
  */
 
@@ -128,6 +141,7 @@ export async function loadLibrary(libraryRoot, opts = {}) {
     bands: normaliseBands(doc.bands),
     blueprints: doc.blueprints.map((b) => ({ slug: b.slug, path: b.path })),
     ...(typeof doc.notes === 'string' ? { notes: doc.notes } : {}),
+    ...(doc.issues ? { issues: normaliseIssues(doc.issues) } : {}),
     root,
   };
 
@@ -203,9 +217,43 @@ function validateManifestShape(doc, metaPath) {
   if (doc.notes !== undefined && typeof doc.notes !== 'string') {
     return rcfError({ kind: 'validation', message: 'library.json: notes must be a string when present', filePath: metaPath });
   }
+  if (doc.issues !== undefined) {
+    const err = validateIssuesField(doc.issues, metaPath);
+    if (err) return err;
+  }
   return null;
 }
 
+/**
+ * Validate the optional `issues` object (design 3.3, AC-15801-1). Refuses
+ * a present-but-shapeless value so a typo does not silently disable
+ * feedback routing. `repo` accepts `OWNER/REPO` on github.com and a
+ * host-qualified `HOST/OWNER/REPO` for GHES; `visibility` is one of
+ * `public` or `private`.
+ */
+function validateIssuesField(issues, metaPath) {
+  if (typeof issues !== 'object' || issues === null || Array.isArray(issues)) {
+    return rcfError({ kind: 'validation', message: 'library.json: issues must be an object with { repo, visibility } when present', filePath: metaPath });
+  }
+  if (typeof issues.repo !== 'string' || issues.repo.length === 0) {
+    return rcfError({ kind: 'validation', message: 'library.json: issues.repo is required (OWNER/REPO or HOST/OWNER/REPO)', filePath: metaPath });
+  }
+  if (!/^([A-Za-z0-9.-]+\/)?[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/.test(issues.repo)) {
+    return rcfError({ kind: 'validation', message: `library.json: issues.repo '${issues.repo}' must be OWNER/REPO on github.com or HOST/OWNER/REPO for GHES`, filePath: metaPath });
+  }
+  if (issues.visibility !== undefined && issues.visibility !== 'public' && issues.visibility !== 'private') {
+    return rcfError({ kind: 'validation', message: `library.json: issues.visibility '${issues.visibility}' must be 'public' or 'private' when present`, filePath: metaPath });
+  }
+  return null;
+}
+
+function normaliseIssues(issues) {
+  return {
+    repo: issues.repo,
+    visibility: issues.visibility === 'private' ? 'private' : 'public',
+  };
+}
+
 function validateBands(bands, metaPath) {
   if (typeof bands !== 'object' || bands === null) {
     return rcfError({ kind: 'validation', message: 'library.json: bands object is required', filePath: metaPath });

package/src/blueprint/library-registry.js

@@ -47,6 +47,8 @@ const CORE_BAND_RESERVATIONS_PATH = join(here, '..', '..', 'data', 'core-band-re
  * @property {'operator'} reviewedBy
  * @property {{ tier: 'local' | 'git' | 'tarball', shaVerifiedAt?: string, tarballSha256?: string }} provenance
  * @property {string} cachePath
+ * @property {string} [issuesRepo]         OWNER/REPO from the library's issues field (design 3.3, ADR-4104)
+ * @property {'public' | 'private'} [issuesVisibility]  library-declared visibility, advisory
  */
 
 /**
@@ -336,6 +338,17 @@ function validateRegistryShape(doc, path) {
     if (entry.sourceKind === 'local' && entry.resolvedSha !== undefined) {
       return rcfError({ kind: 'validation', message: `library registry: libraries[${i}] sourceKind=local must not carry a resolvedSha`, filePath: path });
     }
+    if (entry.issuesRepo !== undefined) {
+      if (typeof entry.issuesRepo !== 'string' || entry.issuesRepo.length === 0) {
+        return rcfError({ kind: 'validation', message: `library registry: libraries[${i}].issuesRepo must be a non-empty string when present`, filePath: path });
+      }
+      if (!/^([A-Za-z0-9.-]+\/)?[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/.test(entry.issuesRepo)) {
+        return rcfError({ kind: 'validation', message: `library registry: libraries[${i}].issuesRepo '${entry.issuesRepo}' must be OWNER/REPO on github.com or HOST/OWNER/REPO for GHES`, filePath: path });
+      }
+    }
+    if (entry.issuesVisibility !== undefined && entry.issuesVisibility !== 'public' && entry.issuesVisibility !== 'private') {
+      return rcfError({ kind: 'validation', message: `library registry: libraries[${i}].issuesVisibility '${entry.issuesVisibility}' must be 'public' or 'private' when present`, filePath: path });
+    }
   }
   return null;
 }

package/src/browser-verify/pack-runner.js

@@ -139,20 +139,15 @@ export async function runProbePacksForFbs({
           checkAppliesDetail = `appliesTo threw: ${err.message}`;
         }
         if (!checkApplicable) {
-          // Spec section 5.5 says the residual cure records
-          // applicable: false at the check level. rcf-schemas 0.6.1
-          // (browserVerificationProbePackCheck) closes the schema and
-          // still requires a verdict enum, so the manifest write path
-          // refuses a check that carries `applicable: false` alone.
-          // Until the schema minor promotes an `applicable` field at
-          // the check level (follow-up rcf-schemas bump), emit
-          // `verdict: 'skipped'` with a detail naming the applicability
-          // gate. Semantically the aggregate verdict still treats this
-          // as neither pass nor fail (skipped does not raise `highest`).
+          // Spec section 5.5 residual cure: record `applicable: false`
+          // at the check level so the aggregate verdict treats the
+          // check as neither pass nor fail. rcf-schemas 0.6.3 added
+          // the optional `applicable` boolean on
+          // browserVerificationProbePackCheck, and its if/then guard
+          // omits `verdict`/`severity` when `applicable: false`.
           checkRecords.push({
             id: check.id,
-            verdict: 'skipped',
-            severity: check.severity,
+            applicable: false,
             detail: checkAppliesDetail ?? 'check appliesTo returned false (required capability not applied)',
           });
           continue;

package/src/build/mark.js

@@ -86,7 +86,7 @@ export function planMark(tree, { fbsId, status }) {
       refused: true,
       message: `build: refusing --mark verified on ${fbsId}; 'verified' is written only by the `
         + `independent verify gate, not by --mark. Promote it with: rcf build finalise ${fbsId} --url <deploy-url>. `
-        + `For a deliberate manual override (no verify run) use: rcf define update ${fbsId} --set executionStatus=verified`,
+        + `For a deliberate manual override (no verify run) use: rcf define update ${fbsId} --set executionStatus=verified --acknowledge-verified-override`,
     };
   }
   const fromIndex = LIFECYCLE.indexOf(from);

package/src/cli/blueprint-library.js

@@ -266,6 +266,12 @@ async function handleAdd({ args, parsed, projectRoot, now, stdout, stderr, stdin
     reviewedBy: 'operator',
     provenance,
     cachePath: sourceKind === 'local' ? libraryRoot : cachePathRel,
+    // Feedback destination snapshot (design 3.3, AC-15801-1). Snapshotted
+    // so the resolver never re-reads the library's own library.json on
+    // every preview / submit; `library refresh` re-snapshots when the
+    // library owner changes the field.
+    ...(library.issues?.repo ? { issuesRepo: library.issues.repo } : {}),
+    ...(library.issues?.visibility ? { issuesVisibility: library.issues.visibility } : {}),
   };
 
   const nextRegistry = {
@@ -565,6 +571,11 @@ async function handleRefresh({ args, parsed, projectRoot, stdout, stderr }) {
     return 2;
   }
   const libraryPrefix = args[0];
+  // F-slice-3-02 regression fix: honour --dry-run on refresh. The
+  // re-snapshot writes below (local / git / tarball) previously ran
+  // unconditionally, so a dry-run mutated the registry even though
+  // the flag is documented as "print intended writes without executing".
+  const dryRun = parsed.values['dry-run'] === true;
   const registry = await readLibraryRegistry(projectRoot);
   if (isRcfError(registry)) {
     stderr.write(`[error] blueprint library refresh: ${registry.message}\n`);
@@ -588,8 +599,22 @@ async function handleRefresh({ args, parsed, projectRoot, stdout, stderr }) {
       stderr.write("re-run 'rcf define blueprint library add <ref>' to pick up the newer library (spec §10.1: freshness is advisory, adoption is an operator act).\n");
       return 3;
     }
+    // F-slice-3-02: re-snapshot the issues field so a library owner's
+    // later change to issues.repo / issues.visibility reaches
+    // consumers on refresh, without a re-add.
+    const snap = refreshRegistryIssues(registry, libraryPrefix, library);
+    if (snap.changed && !dryRun) {
+      const write = await writeLibraryRegistry(projectRoot, snap.registry, {});
+      if (isRcfError(write)) {
+        stderr.write(`[error] blueprint library refresh: ${write.message}\n`);
+        return 2;
+      }
+    }
     if (!parsed.values.quiet) {
       stdout.write(`[blueprint library] '${libraryPrefix}' refresh clean: on-disk library matches the registry snapshot.\n`);
+      if (snap.changed) {
+        stdout.write(`[blueprint library] '${libraryPrefix}' feedback destination ${dryRun ? 'would be re-snapshotted (dry-run)' : 're-snapshotted'}: ${describeIssuesTransition(snap.from, snap.to)}.\n`);
+      }
     }
     return 0;
   }
@@ -643,8 +668,26 @@ async function handleRefresh({ args, parsed, projectRoot, stdout, stderr }) {
     const finalAbs = resolveCachePath(projectRoot, entry.cachePath);
     const settleErr = await settleFinal(scratchAbs, finalAbs);
     if (settleErr) { stderr.write(`[error] blueprint library refresh: ${settleErr.message}\n`); return 2; }
+    // F-slice-3-02: re-snapshot the issues field on the registered
+    // entry now that the on-disk library has landed.
+    const registryReload = await readLibraryRegistry(projectRoot);
+    if (isRcfError(registryReload)) {
+      stderr.write(`[error] blueprint library refresh: ${registryReload.message}\n`);
+      return 2;
+    }
+    const snap = refreshRegistryIssues(registryReload, libraryPrefix, library);
+    if (snap.changed && !dryRun) {
+      const write = await writeLibraryRegistry(projectRoot, snap.registry, {});
+      if (isRcfError(write)) {
+        stderr.write(`[error] blueprint library refresh: ${write.message}\n`);
+        return 2;
+      }
+    }
     if (!parsed.values.quiet) {
       stdout.write(`[blueprint library] '${libraryPrefix}' refresh clean: git ref '${parsedGit.ref}' still resolves to ${upstream.resolvedSha.slice(0, 12)}.\n`);
+      if (snap.changed) {
+        stdout.write(`[blueprint library] '${libraryPrefix}' feedback destination ${dryRun ? 'would be re-snapshotted (dry-run)' : 're-snapshotted'}: ${describeIssuesTransition(snap.from, snap.to)}.\n`);
+      }
     }
     return 0;
   }
@@ -681,8 +724,26 @@ async function handleRefresh({ args, parsed, projectRoot, stdout, stderr }) {
     const finalAbs = resolveCachePath(projectRoot, entry.cachePath);
     const settleErr = await settleFinal(scratchAbs, finalAbs);
     if (settleErr) { stderr.write(`[error] blueprint library refresh: ${settleErr.message}\n`); return 2; }
+    // F-slice-3-02: re-snapshot the issues field on the registered
+    // entry now that the on-disk library has landed.
+    const registryReload = await readLibraryRegistry(projectRoot);
+    if (isRcfError(registryReload)) {
+      stderr.write(`[error] blueprint library refresh: ${registryReload.message}\n`);
+      return 2;
+    }
+    const snap = refreshRegistryIssues(registryReload, libraryPrefix, library);
+    if (snap.changed && !dryRun) {
+      const write = await writeLibraryRegistry(projectRoot, snap.registry, {});
+      if (isRcfError(write)) {
+        stderr.write(`[error] blueprint library refresh: ${write.message}\n`);
+        return 2;
+      }
+    }
     if (!parsed.values.quiet) {
       stdout.write(`[blueprint library] '${libraryPrefix}' refresh clean: tarball SHA-256 still matches ${expected.slice(0, 12)}.\n`);
+      if (snap.changed) {
+        stdout.write(`[blueprint library] '${libraryPrefix}' feedback destination ${dryRun ? 'would be re-snapshotted (dry-run)' : 're-snapshotted'}: ${describeIssuesTransition(snap.from, snap.to)}.\n`);
+      }
     }
     return 0;
   }
@@ -698,6 +759,86 @@ function compareLibrarySnapshot(entry, library) {
   return drifted;
 }
 
+/**
+ * F-slice-3-02: re-snapshot the library's `issues` field onto the
+ * registry entry. Design 3.3 says `library refresh` re-snapshots the
+ * feedback destination so a library owner's later change to
+ * `issues.repo` or `issues.visibility` reaches consumers without a
+ * re-add. Returns `{ changed, next, from, to }` where `next` is the
+ * merged entry to write; `changed` is true when the on-disk library
+ * carries a different repo or visibility from the registered snapshot
+ * (including the case where the entry never had the fields).
+ *
+ * @param {object} entry
+ * @param {object} library
+ * @returns {{ changed: boolean, next: object, from: object, to: object }}
+ */
+export function reSnapshotIssues(entry, library) {
+  const nextRepo = typeof library?.issues?.repo === 'string' && library.issues.repo.length > 0
+    ? library.issues.repo
+    : undefined;
+  const nextVisibility = library?.issues?.visibility === 'private' ? 'private'
+    : library?.issues?.visibility === 'public' ? 'public'
+      : undefined;
+  const from = {
+    issuesRepo: entry.issuesRepo,
+    issuesVisibility: entry.issuesVisibility,
+  };
+  const to = { issuesRepo: nextRepo, issuesVisibility: nextVisibility };
+  const changed = from.issuesRepo !== to.issuesRepo || from.issuesVisibility !== to.issuesVisibility;
+  const next = { ...entry };
+  if (nextRepo === undefined) delete next.issuesRepo;
+  else next.issuesRepo = nextRepo;
+  if (nextVisibility === undefined) delete next.issuesVisibility;
+  else next.issuesVisibility = nextVisibility;
+  return { changed, next, from, to };
+}
+
+/**
+ * Apply reSnapshotIssues across a registry: given the current registry
+ * and the freshly-loaded library, return the registry object with the
+ * matched entry replaced by the re-snapshotted one. Callers write the
+ * returned registry back through `writeLibraryRegistry`.
+ *
+ * @param {object} registry
+ * @param {string} libraryPrefix
+ * @param {object} library
+ * @returns {{ registry: object, changed: boolean, from: object, to: object }}
+ */
+function describeIssuesTransition(from, to) {
+  const fromRepo = from.issuesRepo ?? '(none)';
+  const toRepo = to.issuesRepo ?? '(none)';
+  const fromVis = from.issuesVisibility ?? '-';
+  const toVis = to.issuesVisibility ?? '-';
+  return `${fromRepo} (${fromVis}) -> ${toRepo} (${toVis})`;
+}
+
+function refreshRegistryIssues(registry, libraryPrefix, library) {
+  const nextLibs = [];
+  let changed = false;
+  let from = { issuesRepo: undefined, issuesVisibility: undefined };
+  let to = from;
+  for (const l of registry.libraries) {
+    if (l.libraryPrefix !== libraryPrefix) {
+      nextLibs.push(l);
+      continue;
+    }
+    const snap = reSnapshotIssues(l, library);
+    if (snap.changed) {
+      changed = true;
+      from = snap.from;
+      to = snap.to;
+    }
+    nextLibs.push(snap.next);
+  }
+  return {
+    registry: { ...registry, libraries: nextLibs },
+    changed,
+    from,
+    to,
+  };
+}
+
 function classifySourceRef(ref) {
   // Tarball extension wins over the transport check because `https://.../foo.tar.gz`
   // is a valid tarball ref and would otherwise be misclassified as git.
@@ -750,6 +891,14 @@ function printReview({ stdout, ref, library, libraryPrefix, coreReservations, so
   stdout.write(`\n  Provenance   : ${sourceKind}${sourceKind === 'local' ? ' (dev use)' : ''}\n`);
   stdout.write(`  Band check   : cross-checked ${coreReservations.ac.length} core AC row(s), ${coreReservations.suffixBlocks.length} core suffix block(s); no overlap.\n`);
   stdout.write(`  Prefix check : '${libraryPrefix}' does not collide with any core slug.\n`);
+  // Feedback destination line (design 3.3, AC-15801-1). Prints only
+  // when the library declares an `issues` field; a library without one
+  // is surfaced by `rcf doctor feedback-destinations` on the consuming
+  // project rather than by a review-card warning here.
+  if (library.issues?.repo) {
+    const vis = library.issues.visibility === 'private' ? 'private' : 'public';
+    stdout.write(`  Feedback destination: ${library.issues.repo} (${vis})\n`);
+  }
   stdout.write(`\n`);
 }
 

package/src/cli/coverage.js

@@ -1,10 +1,15 @@
 // `rcf coverage` subcommand handler. Reports structural coverage over
 // the REQ chain (PRD -> REQ -> US -> AC -> TS -> TC). Phase 5 §D2 / §D10.
 //
-// Shallow-any default (any AC covered by any TC = REQ covered);
-// --strict opts into per-AC-strict. --strict on a tree with uncovered
-// ACs exits 4 (CI-gate friendly). Otherwise coverage always exits 0 -
-// the gap count is data, not a refusal.
+// Referee-guarantees train (REQ-164 / US-16401, docs claims C-11 /
+// C-14): strict-by-default. The default mode is per-AC-strict; a
+// stub or stale pointer fails the gate exactly as a missing test does
+// when the plain `rcf audit coverage` command is run. The explicit
+// opt-out is `--mode shallow-any` (any AC covered by any resolving
+// TC = REQ covered), which prints the gaps and exits 0 as before. The
+// legacy `--strict` flag remains a no-op alias for the new default so
+// existing CI invocations, blueprints and dogfood scripts stay green;
+// `--mode shallow-any --strict` (or the inverse) is a usage refusal.
 //
 // Phase-boundary reminder (§D2, §1.4): this verb is a MECHANICAL /
 // DETERMINISTIC structural check. It does NOT answer "does the AC
@@ -32,24 +37,29 @@ import {
 
 const OPTION_SPEC = {
   strict: { type: 'boolean' },
+  // Referee-guarantee train (REQ-164 / US-16401): explicit --mode
+  // selector. Values: strict | shallow-any. Default: strict.
+  mode: { type: 'string' },
   format: { type: 'string' },
   help: { type: 'boolean' },
   // Phase 10 (X2 CodeNode bridge, D11): layer the code axis onto coverage.
   'with-code': { type: 'boolean' },
-  // 0.7.0 verification-integrity: opt-in extra gate on --strict that
+  // 0.7.0 verification-integrity: opt-in extra gate on strict mode that
   // refuses any TS still `draft` after Stage 4 (spec §7.2).
   'require-approved': { type: 'boolean' },
 };
 
+const VALID_MODES = new Set(['strict', 'shallow-any']);
+
 export const HELP = `Usage: rcf audit coverage [scope-id] [options]
 
 Report structural coverage over the REQ chain (PRD -> REQ -> US -> AC
 -> TS -> TC). A TC counts as covering its AC only when its testPointer
 (filePath::testName) resolves to a real test in the working tree; a TC
 whose pointer does not resolve is reported as covered-unresolved, never
-counted as coverage. Default is shallow-any (any AC covered by any
-resolving TC = REQ covered); --strict flips to per-AC-strict (every AC
-has resolving TC coverage).
+counted as coverage. Strict-by-default (per-AC: every AC has resolving
+TC coverage); --mode shallow-any is the explicit opt-out (any AC
+covered by any resolving TC = REQ covered) and always exits 0.
 
 This is a mechanical / deterministic structural check. It does NOT
 answer 'does the AC set adequately capture the REQ's intent?' - that
@@ -63,14 +73,16 @@ Positional:
                             TAD) are refused with exit 2.
 
 Options:
-  --strict                  Per-AC-strict mode; exits 4 on any gap. Also
-                            runs the attestation × profile matrix over
-                            every AC that binds a dependsOnServices
-                            entry (verification-integrity 0.7.0 §5.2):
-                            attestation drift, missing provenance, and
-                            missing FBS-level attestation all exit 4.
-  --require-approved        Extra --strict gate: refuse any TS still at
-                            authoringStatus 'draft' after Stage 4
+  --mode <mode>             strict (default) | shallow-any. Strict is
+                            per-AC and exits 4 on any gap; shallow-any
+                            prints gaps and exits 0.
+  --strict                  Legacy alias for --mode strict; kept for
+                            backward compatibility with existing CI,
+                            blueprints and dogfood invocations. A no-op
+                            under the new default; conflict with an
+                            explicit --mode shallow-any exits 2.
+  --require-approved        Extra strict-mode gate: refuse any TS still
+                            at authoringStatus 'draft' after Stage 4
                             (verification-integrity 0.7.0 §7.2). Off
                             by default; opt-in via CI.
   --with-code               Layer the code axis onto every AC: one of
@@ -117,6 +129,19 @@ export async function main(argv, deps = {}) {
     stderr.write('[error] usage coverage: multiple positional ids are not supported\n');
     return 2;
   }
+  // Referee-guarantee train (REQ-164): resolve strict-vs-shallow.
+  // Default is strict. --mode wins if set; --strict is a legacy alias
+  // for --mode strict; --mode shallow-any --strict is a usage refusal
+  // so a scripted invocation cannot silently disagree with itself.
+  if (flags.mode !== undefined && !VALID_MODES.has(flags.mode)) {
+    stderr.write(`[error] usage coverage: unknown --mode ${flags.mode} (expected strict | shallow-any)\n`);
+    return 2;
+  }
+  if (flags.mode === 'shallow-any' && flags.strict === true) {
+    stderr.write('[error] usage coverage: --mode shallow-any conflicts with --strict; pick one\n');
+    return 2;
+  }
+  const strict = flags.mode === 'shallow-any' ? false : true;
 
   const projectRoot = await findProjectRoot(cwd);
   if (!projectRoot) {
@@ -156,7 +181,7 @@ export async function main(argv, deps = {}) {
   // and a TC that fails resolution surfaces as covered-unresolved.
   const testPointers = await resolveTestPointers({ projectRoot, tree });
   const result = computeCoverage(tree, {
-    strict: Boolean(flags.strict), scopeId, withCode: Boolean(flags['with-code']), testPointers,
+    strict, scopeId, withCode: Boolean(flags['with-code']), testPointers,
   });
 
   let output;
@@ -165,16 +190,16 @@ export async function main(argv, deps = {}) {
   else output = formatTable(result, 'coverage');
   stdout.write(output);
 
-  // --strict on any gap = exit 4 (CI-gate friendly). Otherwise 0.
-  if (flags.strict && !result.ok) return 4;
+  // Strict mode on any gap = exit 4 (CI-gate friendly). Otherwise 0.
+  if (strict && !result.ok) return 4;
 
-  // 0.7.0 verification-integrity extension: --strict also runs the
+  // 0.7.0 verification-integrity extension: strict mode also runs the
   // attestation × profile matrix (spec §5.2). Three refusal classes:
   // (1) attestation missing, (2) provenance missing, (3) attestation
   // drift. All are additive — they never turn a passing coverage into
   // a passing --strict run; they only add exit-4 refusals on new
   // failure modes that the matrix now polices.
-  if (flags.strict) {
+  if (strict) {
     // Review N-3 (non-blocking): surface preFlightConfig services with
     // empty affectedFbsIds so the operator knows findAttestationMissing
     // is skipping them on purpose (honest-but-invisible without this
@@ -182,7 +207,7 @@ export async function main(argv, deps = {}) {
     // into a failing one.
     const emptyAffected = findServicesWithEmptyAffectedFbsIds(tree);
     for (const s of emptyAffected) {
-      stderr.write(`[warn] coverage --strict: preFlightConfig service '${s.serviceId}' (${s.preFlightConfigId}) has empty affectedFbsIds; the attestation-missing detector cannot cross-check it until the back-reference is populated.\n`);
+      stderr.write(`[warn] coverage strict: preFlightConfig service '${s.serviceId}' (${s.preFlightConfigId}) has empty affectedFbsIds; the attestation-missing detector cannot cross-check it until the back-reference is populated.\n`);
     }
 
     const missing = findAttestationMissing(tree);
@@ -203,14 +228,14 @@ export async function main(argv, deps = {}) {
       for (const d of drifts) refusals.push(`  - ${d.tsId}/${d.tcId} on ${d.acId} (service ${d.serviceId}): ${d.reason}`);
     }
     if (refusals.length > 0) {
-      stderr.write(`[error] coverage --strict: refused - the verification-integrity matrix caught the following:\n${refusals.join('\n')}\n`);
+      stderr.write(`[error] coverage strict: refused - the verification-integrity matrix caught the following:\n${refusals.join('\n')}\n`);
       return 4;
     }
 
     if (flags['require-approved']) {
       const draftTsIds = (tree.testSuites ?? []).filter((ts) => ts.status !== 'approved').map((ts) => ts.id);
       if (draftTsIds.length > 0) {
-        stderr.write(`[error] coverage --strict --require-approved: refused - ${draftTsIds.length} test suite(s) still not approved: ${draftTsIds.join(', ')}\n`);
+        stderr.write(`[error] coverage strict --require-approved: refused - ${draftTsIds.length} test suite(s) still not approved: ${draftTsIds.join(', ')}\n`);
         return 4;
       }
     }