rcf-lite 0.7.1 → 0.9.0

package/src/finalise/detect.js

@@ -1,23 +1,32 @@
 // rcf-verify install detection (spec §8.3, amendment 5 - install-together
-// posture). build-lite's finalise gate MUST detect whether `rcf-verify` is
-// resolvable and, when it is absent, prompt to install it - NEVER silently
-// skip the ship gate (the one behaviour §8.3 explicitly forbids).
+// posture). The finalise gate MUST detect whether `rcf-verify` is resolvable
+// and, when it is absent, prompt to install it - NEVER silently skip the ship
+// gate (the one behaviour §8.3 explicitly forbids).
 //
-// Two detection routes, in order, matching how the two packages are actually
-// installed:
-//   1. The `rcf-verify` bin on PATH - the install-together default is two
-//      global bins (`npm i -g @stravica-ai/rcf-build-lite @stravica-ai/rcf-verify-lite`).
+// Two detection routes, in order, matching how the CLI is actually installed:
+//   1. The `rcf-verify` bin on PATH - the umbrella install exposes both `rcf`
+//      and `rcf-verify` as global bins (`npm i -g rcf-lite`).
 //   2. Package resolution from the project dir - the local-project install
-//      (`npm i @stravica-ai/rcf-verify-lite` in a repo's node_modules).
-// Either hit yields a concrete invocation the finalise spawn (spawn.js) uses
-// verbatim. A miss returns { installed:false } and the caller enters the
-// prompt-or-explicit-flag path.
+//      (`npm i rcf-lite` in a repo's node_modules). Two package specifiers
+//      are tried in order: the current umbrella `rcf-lite`, then the legacy
+//      `@stravica-ai/rcf-verify-lite` name (deprecated at 0.7.1 but still
+//      resolvable in lockfiles that pinned it). Either resolves to the same
+//      `bin/rcf-verify.js` entry point.
+// Either route yields a concrete invocation the finalise spawn (spawn.js)
+// uses verbatim. A miss returns { installed:false } and the caller enters
+// the prompt-or-explicit-flag path.
 
 import { access, constants } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import { delimiter, dirname, join, resolve } from 'node:path';
 
-const VERIFY_PACKAGE = '@stravica-ai/rcf-verify-lite';
+// VERIFY_PACKAGE is the current install target and the name shown to
+// operators in absent-verify messaging. VERIFY_PACKAGE_LEGACY is only used
+// as a resolution fallback for lockfiles still pinning the pre-0.7.1 scoped
+// name; it is never displayed as an install target.
+const VERIFY_PACKAGE = 'rcf-lite';
+const VERIFY_PACKAGE_LEGACY = '@stravica-ai/rcf-verify-lite';
+const VERIFY_PACKAGE_CANDIDATES = [VERIFY_PACKAGE, VERIFY_PACKAGE_LEGACY];
 const VERIFY_BIN = 'rcf-verify';
 
 /**
@@ -69,31 +78,44 @@ export async function findOnPath(name, { env = process.env } = {}) {
 }
 
 /**
- * Resolve the rcf-verify package's bin entry point from a starting directory,
- * following the normal node_modules resolution the caller's project sees.
- * Returns the absolute path to `bin/rcf-verify.js`, or null if the package is
- * not installed / not resolvable from there.
+ * Resolve the rcf-verify bin entry point from a starting directory, following
+ * the normal node_modules resolution the caller's project sees. Returns the
+ * absolute path to `bin/rcf-verify.js`, or null if no candidate package is
+ * installed / resolvable from there.
+ *
+ * Candidates are tried in the order defined by VERIFY_PACKAGE_CANDIDATES: the
+ * current umbrella (`rcf-lite`) first, then the deprecated scoped name
+ * (`@stravica-ai/rcf-verify-lite`) as a fallback for lockfiles pinned to it.
+ * The first candidate whose bin resolves and exists on disk wins.
  *
  * @param {string} fromDir - directory to resolve from (the project root / cwd)
  * @returns {Promise<string|null>}
  */
 export async function resolvePackageBin(fromDir) {
+  // Resolve from a synthetic module living in fromDir so node walks that
+  // project's node_modules chain, not this package's own.
+  let req;
   try {
-    // Resolve from a synthetic module living in fromDir so node walks that
-    // project's node_modules chain, not build-lite's own.
-    const req = createRequire(join(fromDir, 'noop.js'));
-    const pkgJsonPath = req.resolve(`${VERIFY_PACKAGE}/package.json`);
-    const req2 = createRequire(pkgJsonPath);
-    const pkg = req2(`${VERIFY_PACKAGE}/package.json`);
-    const binField = pkg.bin;
-    const rel = typeof binField === 'string' ? binField : binField?.[VERIFY_BIN];
-    if (!rel) return null;
-    const abs = resolve(dirname(pkgJsonPath), rel);
-    await access(abs, constants.F_OK);
-    return abs;
+    req = createRequire(join(fromDir, 'noop.js'));
   } catch {
     return null;
   }
+  for (const candidate of VERIFY_PACKAGE_CANDIDATES) {
+    try {
+      const pkgJsonPath = req.resolve(`${candidate}/package.json`);
+      const req2 = createRequire(pkgJsonPath);
+      const pkg = req2(`${candidate}/package.json`);
+      const binField = pkg.bin;
+      const rel = typeof binField === 'string' ? binField : binField?.[VERIFY_BIN];
+      if (!rel) continue;
+      const abs = resolve(dirname(pkgJsonPath), rel);
+      await access(abs, constants.F_OK);
+      return abs;
+    } catch {
+      // Candidate not resolvable from here; try the next one.
+    }
+  }
+  return null;
 }
 
 /**
@@ -126,4 +148,4 @@ export async function detectVerify(deps = {}) {
   return { installed: false, invocation: null };
 }
 
-export { VERIFY_PACKAGE, VERIFY_BIN };
+export { VERIFY_PACKAGE, VERIFY_PACKAGE_LEGACY, VERIFY_PACKAGE_CANDIDATES, VERIFY_BIN };

package/src/finalise/index.js

@@ -6,10 +6,24 @@
 // absent - prompts to install rather than silently skipping the gate (detect.js
 // + install.js).
 
-export { detectVerify, findOnPath, resolvePackageBin, VERIFY_PACKAGE, VERIFY_BIN } from './detect.js';
+export {
+  detectVerify,
+  findOnPath,
+  resolvePackageBin,
+  VERIFY_PACKAGE,
+  VERIFY_PACKAGE_LEGACY,
+  VERIFY_PACKAGE_CANDIDATES,
+  VERIFY_BIN,
+} from './detect.js';
 export { buildVerifyArgs, spawnVerify } from './spawn.js';
 export { promptYesNo, installVerify, resolveAbsentVerify } from './install.js';
-export { loadReport, summariseReport, findMockOnlyDeclaredAcs, reportHasMockOnlyDeclared } from './ingest.js';
+export {
+  loadReport, summariseReport,
+  findMockOnlyDeclaredAcs, reportHasMockOnlyDeclared,
+  // 0.8.0 slug-train car 4: NV-BL-GATE-01 pull-in of the profile-vs-AC
+  // scope-mismatch check into REVIEW.
+  findScopeMismatchAcs, reportHasScopeMismatch,
+} from './ingest.js';
 export {
   composeShipWithoutVerifiedRecord,
   nextShipWithoutVerifiedId,

package/src/finalise/ingest.js

@@ -82,6 +82,17 @@ export function summariseReport(report) {
       lines.push(`  - ${d.acId ?? '?'} (${d.verdict}): ${d.reason ?? 'declaredMockOnly at pre-flight; verify emitted the honest verdict rather than a false PASS.'}`);
     }
   }
+  // 0.8.0 slug-train car 4: NV-BL-GATE-01 pulls verify's profile-vs-AC
+  // scope-mismatch check into REVIEW. When verify emits SCOPE-MISMATCH
+  // on perAcVerdicts[] the summary surfaces it so REVIEW / finalise see
+  // it. Zero-mismatch reports render nothing (no false-flag noise).
+  const scopeMismatches = findScopeMismatchAcs(report);
+  if (scopeMismatches.length > 0) {
+    lines.push(`scope mismatches (${scopeMismatches.length}):`);
+    for (const s of scopeMismatches) {
+      lines.push(`  - ${s.acId ?? '?'} (${s.verdict}): ${s.reason ?? 'a bound TC is narrower than the AC scope; NV-BL-ADM-03 / NV-BL-GATE-01.'}`);
+    }
+  }
   if (report.launchFailure?.message) {
     lines.push(`launch failure: ${report.launchFailure.message}`);
   }
@@ -117,3 +128,33 @@ export function findMockOnlyDeclaredAcs(report) {
 export function reportHasMockOnlyDeclared(report) {
   return findMockOnlyDeclaredAcs(report).length > 0;
 }
+
+/**
+ * Extract SCOPE-MISMATCH per-AC verdicts from a verify report. Introduced
+ * in the 0.8.0 slug-train (car 4) so REVIEW consumes the same shape via
+ * NV-BL-GATE-01. Earlier reports carry no such entries; this returns an
+ * empty array on those.
+ *
+ * @param {object} report
+ * @returns {Array<{ acId: string, verdict: string, reason?: string }>}
+ */
+export function findScopeMismatchAcs(report) {
+  const perAc = Array.isArray(report?.perAcVerdicts) ? report.perAcVerdicts : [];
+  return perAc
+    .filter((e) => e && e.verdict === 'SCOPE-MISMATCH')
+    .map((e) => ({ acId: e.acId, verdict: e.verdict, reason: e.reason }));
+}
+
+/**
+ * True when a verify report carries at least one SCOPE-MISMATCH per-AC
+ * verdict. NV-BL-GATE-01 (0.8.0 slug-train car 4): the REVIEW gate
+ * consumes this so a scope mismatch caught at REVIEW-time fails the
+ * gate and returns the FBS to BUILD; the finalise gate reads the same
+ * shape as a last-mile refusal.
+ *
+ * @param {object} report
+ * @returns {boolean}
+ */
+export function reportHasScopeMismatch(report) {
+  return findScopeMismatchAcs(report).length > 0;
+}

package/src/mcp/tools.js

@@ -762,7 +762,12 @@ function resolveTarget(tree, id) {
     const entry = (us.acceptanceCriteria ?? []).find((ac) => ac.id === id);
     return entry ? { doc: entry } : null;
   }
-  if (/^TC-\d{3}-[a-z0-9-]+$/.test(id)) {
+  // 0.8.0 slug-train (w-2026-07-28-012 landmine 3, consumer-path
+  // straggler): widened `\d{3}` -> `\d{3,}` in lockstep with rcf-schemas
+  // 0.4.3's TC pattern. Under the previous shape a `read TC-1000-x` MCP
+  // call silently returned null even when the TC existed -- the same
+  // silent-skip class as the CLI `rcf read` path (src/cli/read.js).
+  if (/^TC-\d{3,}-[a-z0-9-]+$/.test(id)) {
     const parentId = tree.parentByChild.get(id);
     if (!parentId) return null;
     const ts = tree.byId.get(parentId);
@@ -1005,7 +1010,10 @@ export function createToolRegistry({ projectRoot, log }) {
       if (kind === 'tc') {
         if (!args.acId) return usageErrorResult('create tc: acId is required');
         body.acId = args.acId;
-        options.slug = args.slug ?? deriveSlug(body.description);
+        // 0.8.0 slug-train (w-2026-07-28-012 landmine 4): deriveSlug returns
+        // '' on empty derivation; TC keeps its historical 'tc' fallback
+        // locally rather than letting deriveSlug bake it in.
+        options.slug = args.slug ?? (deriveSlug(body.description) || 'tc');
         if (args.testPointer !== undefined) options.testPointer = args.testPointer;
       }
 

package/src/query/formatters/table.js

@@ -122,7 +122,7 @@ function formatTraceTable(result) {
     lines.push(`${directionLabel}: (none)`);
   } else {
     for (const n of showList) {
-      rows.push([String(n.depth), n.id, n.kind, cellTitle(n.id)]);
+      rows.push([String(n.depth), n.id, n.kind, n.title ?? '']);
     }
     lines.push(renderTable(rows));
   }
@@ -139,7 +139,7 @@ function formatBothTraceTable(result) {
     lines.push('  (none)');
   } else {
     const rows = [['Depth', 'Id', 'Kind', 'Title']];
-    for (const n of ancestors) rows.push([String(n.depth), n.id, n.kind, '']);
+    for (const n of ancestors) rows.push([String(n.depth), n.id, n.kind, n.title ?? '']);
     lines.push(renderTable(rows));
   }
   lines.push('');
@@ -151,7 +151,7 @@ function formatBothTraceTable(result) {
     lines.push('  (none)');
   } else {
     const rows = [['Depth', 'Id', 'Kind', 'Title']];
-    for (const n of descendants) rows.push([String(n.depth), n.id, n.kind, '']);
+    for (const n of descendants) rows.push([String(n.depth), n.id, n.kind, n.title ?? '']);
     lines.push(renderTable(rows));
   }
   return `${lines.join('\n')}\n`;
@@ -194,10 +194,7 @@ function renderTable(rows) {
   return [out[0], sep, ...out.slice(1)].join('\n');
 }
 
-// Placeholder for future title lookup - the pure trace result does not
-// carry doc bodies, so title columns render blank unless the caller
-// passes a title source. Left here for the trace `Title` column so the
-// column stays if we ever wire in a title map without a schema change.
-function cellTitle(_id) {
-  return '';
-}
+// Trace nodes carry `title` as of the paper-cut batch (previously the
+// Title column was always empty). Doc-kind title source: PRD →
+// productName, REQ/US/TAC/ADR/TAD/TS/FBS/CN → title, inline AC/TC →
+// description. Nodes lacking a title render blank.

package/src/query/index.js

@@ -7,3 +7,7 @@ export { computeImpact, labelFor } from './impact.js';
 export { formatTable } from './formatters/table.js';
 export { formatJson } from './formatters/json.js';
 export { formatMermaid } from './formatters/mermaid.js';
+// 0.8.0 slug-train car 3: NV-BL-SR-03 addendum (ruling-sheet item 1)
+// -- traceability / query tools share the refuse-first posture that
+// gates rcf build. Callers wrap their query producer with this.
+export { runWithAdmissibilityGate } from './refuse-on-admissibility.js';

package/src/query/refuse-on-admissibility.js

@@ -0,0 +1,73 @@
+// Traceability / query tool refuse-first wrapper (NV-BL-SR-03
+// addendum on ruling-sheet item 1, ratified 2026-08-11).
+//
+// The ruleset's `toolScope` block declares:
+//   { chainAdmissibility: true, traceabilityAndQueryTools: true }
+//
+// meaning the same refusal semantics that gate `rcf build` also gate
+// the traceability and query tools. A tool that hides an admissibility
+// failure is the same class of defect as a build that hides one.
+//
+// This module wraps a query result so a REFUSE verdict from
+// `enforceAdmissibility` short-circuits the tool's output. Callers
+// pass the walker tree and the chain's declared ruleset version; on
+// REFUSE the wrapper returns a refusal envelope naming the unresolved
+// findings. On PASS or PASS-WITH-OVERRIDES the query's own result flows
+// through unchanged.
+
+import { enforceAdmissibility, getRulesetToolScope } from '#admissibility';
+
+/**
+ * @typedef {import('../admissibility/enforce.js').AdmissibilityVerdict} AdmissibilityVerdict
+ * @typedef {import('../admissibility/enforce.js').AdmissibilityOverride} AdmissibilityOverride
+ */
+
+/**
+ * @typedef {object} QueryResult
+ * @property {'ok' | 'refused-admissibility'} status
+ * @property {AdmissibilityVerdict} [admissibility] - always present so callers can log.
+ * @property {*} [payload] - the underlying query result on status 'ok'.
+ * @property {string} [refusal] - human-readable summary on 'refused-admissibility'.
+ */
+
+/**
+ * Wrap a query producer with the refuse-first posture. The producer is
+ * only called when admissibility passes (or passes-with-overrides);
+ * on refusal, its produce function does NOT run and the wrapper
+ * returns a refusal envelope naming the unresolved rules.
+ *
+ * @param {object} args
+ * @param {object} args.tree
+ * @param {string|null} [args.chainRulesetVersion]
+ * @param {AdmissibilityOverride[]} [args.overrides]
+ * @param {() => (Promise<*> | *)} args.produce - the underlying query
+ * @param {object} [args.opts] - passed through to enforceAdmissibility
+ * @returns {Promise<QueryResult>}
+ */
+export async function runWithAdmissibilityGate({
+  tree,
+  chainRulesetVersion = null,
+  overrides = [],
+  produce,
+  opts = {},
+} = {}) {
+  const toolScope = await getRulesetToolScope();
+  if (!toolScope.traceabilityAndQueryTools) {
+    // Ruleset opted out of tool-scope gating (currently the artefact
+    // ships with this on -- item 1 addendum -- but the switch is
+    // read at runtime so a future ruleset revision can amend it).
+    const payload = await Promise.resolve(produce());
+    return { status: 'ok', payload };
+  }
+  const verdict = await enforceAdmissibility({ tree, chainRulesetVersion, overrides, opts });
+  if (verdict.verdict === 'refuse') {
+    const ruleIds = [...new Set(verdict.unresolved.map((f) => f.rule).filter(Boolean))].sort();
+    return {
+      status: 'refused-admissibility',
+      admissibility: verdict,
+      refusal: `traceability/query tool refused (NV-BL-SR-03 addendum): unresolved admissibility rules [${ruleIds.join(', ')}]. Fix or record a NV-BL-ADM-05 override before re-querying.`,
+    };
+  }
+  const payload = await Promise.resolve(produce());
+  return { status: 'ok', admissibility: verdict, payload };
+}

package/src/query/trace.js

@@ -32,6 +32,7 @@
  * @property {string} id
  * @property {string} kind
  * @property {number} depth - 0 for pivot; positive for descendants; negative for ancestors
+ * @property {string} title - display title, or '' when the node has none
  */
 
 /**
@@ -71,6 +72,41 @@ export function kindOf(tree, id) {
   return null;
 }
 
+/**
+ * Return the display title for an id, or '' when the node carries none.
+ * Different doc kinds carry the title on different fields (PRD →
+ * productName; inline AC/TC → description; everything else → title). A
+ * standalone doc that lacks its title field renders blank rather than
+ * throwing; that keeps trace output readable on a partially-authored tree.
+ *
+ * Inline lookup: AC / TC nodes live inside their parent's inline array
+ * (userStory.acceptanceCriteria[] / testSuite.testCases[]), not as
+ * standalone entries in `tree.byId`. Resolve via parentByChild.
+ *
+ * @param {object} tree - walker TreeModel
+ * @param {string} id
+ * @param {string} kind - as returned by `kindOf`
+ * @returns {string}
+ */
+export function titleOf(tree, id, kind) {
+  if (kind === 'ac') {
+    const usId = tree.parentByChild.get(id);
+    const us = usId ? tree.byId.get(usId) : null;
+    const ac = us?.acceptanceCriteria?.find((a) => a?.id === id);
+    return ac?.description ?? '';
+  }
+  if (kind === 'tc') {
+    const tsId = tree.parentByChild.get(id);
+    const ts = tsId ? tree.byId.get(tsId) : null;
+    const tc = ts?.testCases?.find((t) => t?.id === id);
+    return tc?.description ?? '';
+  }
+  const doc = tree.byId.get(id);
+  if (!doc) return '';
+  if (kind === 'prd') return doc.productName ?? '';
+  return doc.title ?? '';
+}
+
 /**
  * Compute a trace from `id` in the requested direction. Unknown pivot
  * returns `{found: false}`; the handler layer converts this to exit 2.
@@ -134,7 +170,7 @@ export function computeTrace(tree, {
  */
 function walkForward(tree, pivot, pivotKind, includeCode = false, expandFbsDependents = false) {
   /** @type {TraceNode[]} */
-  const nodes = [{ id: pivot, kind: pivotKind, depth: 0 }];
+  const nodes = [{ id: pivot, kind: pivotKind, depth: 0, title: titleOf(tree, pivot, pivotKind) }];
   /** @type {TraceEdge[]} */
   const edges = [];
   const seen = new Set([pivot]);
@@ -158,7 +194,12 @@ function walkForward(tree, pivot, pivotKind, includeCode = false, expandFbsDepen
       if (!childKind) continue;
       const nextDepth = curDepth + 1;
       depthById.set(child.id, nextDepth);
-      nodes.push({ id: child.id, kind: childKind, depth: nextDepth });
+      nodes.push({
+        id: child.id,
+        kind: childKind,
+        depth: nextDepth,
+        title: titleOf(tree, child.id, childKind),
+      });
       queue.push(child.id);
     }
   }
@@ -178,7 +219,7 @@ function walkForward(tree, pivot, pivotKind, includeCode = false, expandFbsDepen
  */
 function walkBack(tree, pivot, pivotKind) {
   /** @type {TraceNode[]} */
-  const nodes = [{ id: pivot, kind: pivotKind, depth: 0 }];
+  const nodes = [{ id: pivot, kind: pivotKind, depth: 0, title: titleOf(tree, pivot, pivotKind) }];
   /** @type {TraceEdge[]} */
   const edges = [];
   const seen = new Set([pivot]);
@@ -188,7 +229,7 @@ function walkBack(tree, pivot, pivotKind) {
     const k = kindOf(tree, toId);
     if (!k) return;
     seen.add(toId);
-    nodes.push({ id: toId, kind: k, depth });
+    nodes.push({ id: toId, kind: k, depth, title: titleOf(tree, toId, k) });
     edges.push({ from: fromId, to: toId, kind: edgeKind });
   };
 

package/src/ruleset/index.js

@@ -0,0 +1,140 @@
+// Shared standards ruleset loader (NV-BL-SR-01, NV-BL-SR-02, NV-BL-SR-03).
+//
+// The ruleset is a single machine-readable artefact bundled inside the
+// rcf-lite umbrella package (JSON, camelCase per estate convention). Both
+// build-lite (as a gate) and rcf-define-lite (as an elicitation checklist,
+// from the umbrella release that adds the define payload) consume the
+// identical ruleset from the identical umbrella version.
+//
+// Per NV-BL-SR-02 (ratified 2026-08-11, ruling-sheet items 2 and 6): the
+// ruleset carries no separate semver. Its version IS the rcf-lite umbrella
+// package version. This loader stamps `rulesetVersion` at read time from
+// the umbrella's package.json so a redeploy of the same JSON on a bumped
+// umbrella version reports the new version without a data edit.
+//
+// Ruleset scope covers chain admissibility AND the estate's traceability
+// and query tooling (ratified 2026-08-11, ruling-sheet item 1 addendum).
+// See toolScope on the artefact.
+
+import { readFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const rulesetPath = join(here, 'ruleset.json');
+const packageJsonPath = resolve(here, '..', '..', 'package.json');
+
+/**
+ * @typedef {object} RulesetRule
+ * @property {string} id
+ * @property {string} title
+ * @property {boolean} [refuseByDefault]
+ * @property {string} [overrideChannel]
+ */
+
+/**
+ * @typedef {object} Ruleset
+ * @property {string} id
+ * @property {string} rulesetVersion - the rcf-lite umbrella package version at load time.
+ * @property {RulesetRule[]} admissibilityRules
+ * @property {RulesetRule[]} gateRules
+ * @property {object} scopeTagVocabulary
+ * @property {Array<{ marker: string, caseInsensitive: boolean }>} sourceCommentMarkers
+ * @property {Array<{ id: string, title: string, surface: string }>} tcTemplateFamily
+ * @property {Array<{ id: string, title: string, kind: string }>} rulingConsistencyChecks
+ * @property {{ chainAdmissibility: boolean, traceabilityAndQueryTools: boolean }} toolScope
+ */
+
+let cachedRuleset = null;
+let cachedUmbrellaVersion = null;
+
+async function readJson(path) {
+  const raw = await readFile(path, 'utf8');
+  return JSON.parse(raw);
+}
+
+/**
+ * The rcf-lite umbrella package version at load time. Used by
+ * `getRuleset()` to stamp `rulesetVersion` per NV-BL-SR-02; also exported
+ * so consumers can read the umbrella version without opening
+ * `package.json` themselves.
+ *
+ * @returns {Promise<string>}
+ */
+export async function getUmbrellaVersion() {
+  if (cachedUmbrellaVersion) return cachedUmbrellaVersion;
+  const pkg = await readJson(packageJsonPath);
+  if (typeof pkg?.version !== 'string' || pkg.version.length === 0) {
+    throw new Error('rcf-lite umbrella package.json is missing a version string');
+  }
+  cachedUmbrellaVersion = pkg.version;
+  return cachedUmbrellaVersion;
+}
+
+/**
+ * Load the shared standards ruleset artefact and stamp its `rulesetVersion`
+ * from the umbrella package.json. The artefact itself carries no version
+ * field (NV-BL-SR-02); read-time stamping is the single source of truth.
+ *
+ * @param {object} [opts]
+ * @param {boolean} [opts.fresh] - bypass the module-scope cache and re-read
+ * @returns {Promise<Ruleset>}
+ */
+export async function getRuleset({ fresh = false } = {}) {
+  if (!fresh && cachedRuleset) return cachedRuleset;
+  const [artefact, umbrellaVersion] = await Promise.all([
+    readJson(rulesetPath),
+    getUmbrellaVersion(),
+  ]);
+  // Defensive: strip any accidental rulesetVersion baked into the JSON so
+  // the umbrella version is authoritative. NV-BL-SR-02 is emphatic about
+  // this: a divergence here is a spec drift, not a data field.
+  delete artefact.rulesetVersion;
+  cachedRuleset = Object.freeze({ ...artefact, rulesetVersion: umbrellaVersion });
+  return cachedRuleset;
+}
+
+/**
+ * Detect whether the ruleset version on a chain differs from the shipping
+ * ruleset version, and classify the drift for NV-BL-ADM-06 (build-stage
+ * refusal) and DL-REQ-VALIDATE-03 (define-stage warning).
+ *
+ * Additive-only drift (only new rule ids appear on the shipping side) is
+ * classified `additive` and warns rather than refuses. Any other version
+ * mismatch is classified `behavioural` and refuses at build stage.
+ *
+ * Same-version comparisons return `{ drift: 'none' }`.
+ *
+ * @param {object} args
+ * @param {string|null|undefined} args.chainRulesetVersion - version the chain declared it was authored against.
+ * @param {Ruleset} [args.ruleset] - shipping ruleset; defaults to the loaded artefact.
+ * @returns {Promise<{ drift: 'none' | 'additive' | 'behavioural' | 'missing', shippingVersion: string, chainVersion: string | null }>}
+ */
+export async function detectRulesetDrift({ chainRulesetVersion, ruleset } = {}) {
+  const shipping = ruleset ?? (await getRuleset());
+  const shippingVersion = shipping.rulesetVersion;
+  const chainVersion = typeof chainRulesetVersion === 'string' && chainRulesetVersion.length > 0
+    ? chainRulesetVersion
+    : null;
+  if (chainVersion === null) {
+    return { drift: 'missing', shippingVersion, chainVersion };
+  }
+  if (chainVersion === shippingVersion) {
+    return { drift: 'none', shippingVersion, chainVersion };
+  }
+  // v1 policy: any version mismatch is treated as behavioural drift for
+  // the build stage refusal path (NV-BL-ADM-06). Additive-only drift
+  // becomes distinguishable once the umbrella starts landing patch bumps
+  // that only add rules; the classifier lives here so define-stage
+  // warning (DL-REQ-VALIDATE-03) can consume it without duplicating logic.
+  return { drift: 'behavioural', shippingVersion, chainVersion };
+}
+
+/**
+ * Reset the module-scope cache. For tests that mutate the on-disk artefact
+ * or the package version.
+ */
+export function resetRulesetCache() {
+  cachedRuleset = null;
+  cachedUmbrellaVersion = null;
+}