rcf-lite 0.7.1 → 0.8.0

package/src/core/store/walker.js

@@ -20,6 +20,28 @@ import { normaliseId } from './ids.js';
 import { listSubdirJsonFiles, loadDocument, loadRootDocument, pathForId, subdirFor } from './loader.js';
 import { validateDocument } from './validator.js';
 
+/**
+ * Derive an id from a filename stem, upper-casing the prefix segment only
+ * and leaving any slug tail verbatim (0.8.0 slug-train; w-2026-07-28-012
+ * landmine 1). Every id shape rcf-schemas 0.4.3 admits is
+ * `<PREFIX>-<digits>[-<lower-kebab>]`, so the split is always on the
+ * FIRST hyphen. Segments after the first hyphen are lower-case by
+ * construction (schema pattern `[a-z0-9]+(?:-[a-z0-9]+)*`); we still
+ * leave them verbatim rather than round-tripping through
+ * .toLowerCase() so a slug that fails the pattern surfaces as-is at the
+ * schema-validation step instead of being silently masked here.
+ *
+ * @param {string} stem - filename stem, e.g. `fbs-004-user-login`.
+ * @returns {string} canonical id, e.g. `FBS-004-user-login`.
+ */
+function idFromFilenameStem(stem) {
+  const dash = stem.indexOf('-');
+  if (dash === -1) return stem.toUpperCase();
+  const prefix = stem.slice(0, dash).toUpperCase();
+  const tail = stem.slice(dash);
+  return `${prefix}${tail}`;
+}
+
 /**
  * @typedef {object} TreeModel
  * @property {object|null} manifest
@@ -182,7 +204,23 @@ async function loadChildKind(kind, { projectRoot, tree, errors }) {
   }
   for (const entry of listing.files) {
     const stem = entry.replace(/\.json$/, '');
-    const id = stem.toUpperCase();
+    // 0.8.0 slug-train (w-2026-07-28-012 landmine 1 / d-2026-07-28-011
+    // recon): upper-case the PREFIX segment only. Full-stem toUpperCase
+    // was lossless while every id was `<PREFIX>-<digits>`; the moment a
+    // slug lands (`fbs-004-user-login.json` -> body `FBS-004-user-login`),
+    // the whole-stem fold produced `FBS-004-USER-LOGIN` in tree.byId /
+    // kindById / parentByChild while every inbound reference
+    // (dependsOnFbsIds, contextRequirements.adrIds, us.tacIds,
+    // cn.dependencies) used the lower-case form. The graph silently
+    // detached. Fixing this here, before any slug-consuming change lands,
+    // is the single load-bearing precondition of the whole slug design
+    // (see the item's regression test in test/store/walker.test.js:
+    // "walkTree preserves case on slug tails when deriving id from
+    // filename"). Slugs are lower-case kebab by construction (rcf-schemas
+    // 0.4.3 pattern `[a-z0-9]+(?:-[a-z0-9]+)*`), so leaving the tail
+    // verbatim is safe. `PRD-001.json` / `req-002.json` / mixed-case
+    // filenames continue to normalise their prefix.
+    const id = idFromFilenameStem(stem);
     // Filename-derived ids are not injective: on a case-sensitive
     // filesystem `REQ-001.json` and `req-001.json` are two files that
     // both resolve to `REQ-001`. Recording both silently collapsed the
@@ -848,10 +886,18 @@ function collectBrokenReferences(tree, errors) {
       }
     }
     // Inline TC id pattern check: `TC-<TS-suffix>-<slug>`.
-    const tsSuffix = ts.id?.match(/^TS-(\d{3})$/)?.[1];
+    // 0.8.0 slug-train (w-2026-07-28-012 landmine 3): widened from
+    // `\d{3}` (three-digit-exact) to `\d{3,}` in lockstep with
+    // rcf-schemas 0.4.3's TS/TC pattern widening. The pre-0.8.0 shape
+    // silently skipped every TS above 999: a TS-1000 failed the exact
+    // three-digit match, tsSuffix was undefined, and the whole
+    // idPrefixMatchesParent rule never fired for that TS's inline TCs.
+    // No error, no warning, just an unchecked doc -- exactly the
+    // silent-skip class this train is chartered to eliminate.
+    const tsSuffix = ts.id?.match(/^TS-(\d{3,})$/)?.[1];
     if (tsSuffix) {
       for (const tc of ts.testCases ?? []) {
-        const m = String(tc.id ?? '').match(/^TC-(\d{3})-[a-z0-9-]+$/);
+        const m = String(tc.id ?? '').match(/^TC-(\d{3,})-[a-z0-9-]+$/);
         if (m && m[1] !== tsSuffix) {
           errors.push(rcfError({
             kind: 'brokenReference',

package/src/core/store/writer.js

@@ -249,7 +249,9 @@ export function nextIdForKind(tree, kind, opts = {}) {
       if (typeof slug !== 'string' || slug.length === 0) {
         throw new TypeError('nextIdForKind tc requires opts.slug');
       }
-      const mTs = /^TS-(\d{3})$/.exec(tsId);
+      // 0.8.0 slug-train (w-2026-07-28-012 landmine 3): widened to
+      // `\d{3,}` in lockstep with rcf-schemas 0.4.3.
+      const mTs = /^TS-(\d{3,})$/.exec(tsId);
       if (!mTs) throw new TypeError('nextIdForKind tc: unrecognised TS id');
       return `TC-${mTs[1]}-${slug}`;
     }
@@ -263,15 +265,24 @@ export function nextIdForKind(tree, kind, opts = {}) {
 // set fed in (see `occupiedIdsOfKind`). Comparison stays numeric and the
 // emitted id is always the canonical three-digit-minimum spelling, so a
 // freshly allocated id is never a leading-zero variant of a taken one.
+//
+// 0.8.0 slug-train (w-2026-07-28-012 landmine 2): the previous shape used
+// `^<PREFIX>-(\\d+)$` and slug-blindly ignored any id whose number was
+// followed by a slug tail. Verified empirically: /^FBS-(\d+)$/.test(
+// 'FBS-003-user-login') === false, so a slugged id was invisible to the
+// high-water mark and the allocator reset to 001 and re-issued taken
+// numbers. Use the shared `idNumber(id, prefix)` helper (ids.js:72-78,
+// pattern `^${prefix}-(\d+)(?:-|$)`) instead of writing a second parser
+// -- that helper's whole job is to parse a number out of any id shape the
+// schemas admit (numeric-only OR slug-suffixed), so numeric-only and
+// slugged ids feed into the SAME high-water mark and cannot collide by
+// spelling. w-2026-07-28-017's `occupiedIdsOfKind` already feeds the
+// right ids in; landmine 2 is that this reader could not parse them.
 function nextFlatId(prefix, ids) {
   let max = 0;
-  const re = new RegExp(`^${prefix}-(\\d+)$`);
   for (const id of ids) {
-    const m = re.exec(id ?? '');
-    if (m) {
-      const n = Number(m[1]);
-      if (n > max) max = n;
-    }
+    const n = idNumber(id, prefix);
+    if (n !== null && n > max) max = n;
   }
   return `${prefix}-${String(max + 1).padStart(3, '0')}`;
 }
@@ -904,8 +915,14 @@ async function createInlineTc({ projectRoot, tree, options, body, walkErrors = [
       message: 'create tc: --test-pointer is required (format filePath::testName; coverage counts a TC only when its pointer resolves to a real test)',
     });
   }
-  const slug = options.slug ?? deriveSlug(description);
-  const tsSuffix = /^TS-(\d{3})$/.exec(parentTsId)?.[1];
+  // 0.8.0 slug-train (w-2026-07-28-012 landmine 4): deriveSlug now returns
+  // '' on empty derivation so the TC-specific `|| 'tc'` fallback is applied
+  // here rather than leaking the literal 'tc' into non-TC callers. See
+  // deriveSlug for the full argument.
+  const slug = options.slug ?? (deriveSlug(description) || 'tc');
+  // 0.8.0 slug-train (w-2026-07-28-012 landmine 3): widened `\d{3}` ->
+  // `\d{3,}` in lockstep with rcf-schemas 0.4.3.
+  const tsSuffix = /^TS-(\d{3,})$/.exec(parentTsId)?.[1];
   if (!tsSuffix) {
     return rcfError({ kind: 'usage', message: `create tc: parent ${parentTsId} has an unrecognised id shape` });
   }
@@ -959,7 +976,17 @@ async function createInlineTc({ projectRoot, tree, options, body, walkErrors = [
  * partial word is dropped (B2 fix, E2E matrix 2026-07-06-003 - ids
  * like "...-saved-whil" chopped mid-word). A single unbroken word
  * longer than the limit keeps its 40-char prefix (no boundary exists).
+ *
+ * 0.8.0 slug-train (w-2026-07-28-012 landmine 4): returns '' when no
+ * slug can be derived (empty / non-word / whitespace input). The previous
+ * shape returned the literal 'tc' as a fallback, which leaked the TC
+ * kind-specific default into every slug caller -- an FBS whose title
+ * derived to empty would land as `FBS-004-tc`, entirely wrong for the
+ * kind. TC callers now apply `deriveSlug(description) || 'tc'` locally
+ * (createInlineTc); every non-TC caller decides what its own empty
+ * fallback should be, or refuses.
  * @param {string} description
+ * @returns {string} slug, or '' when no slug can be derived
  */
 export function deriveSlug(description) {
   const full = String(description)
@@ -973,7 +1000,7 @@ export function deriveSlug(description) {
     if (boundary > 0) slug = slug.slice(0, boundary);
   }
   slug = slug.replace(/-+$/g, '');
-  return slug.length > 0 ? slug : 'tc';
+  return slug;
 }
 
 /**
@@ -1160,7 +1187,10 @@ function checkCrossLinks(tree, kind, doc, docId) {
 function resolveInlineId(id) {
   if (typeof id !== 'string') return null;
   if (/^AC-\d+(-\d+)?$/.test(id)) return { kind: 'ac' };
-  if (/^TC-\d{3}-[a-z0-9-]+$/.test(id)) return { kind: 'tc' };
+  // 0.8.0 slug-train (w-2026-07-28-012 landmine 3): widened `\d{3}` -> `\d{3,}`
+  // in lockstep with rcf-schemas 0.4.3. A TC-1000-... would otherwise fail
+  // the inline resolver even though the schema admits it.
+  if (/^TC-\d{3,}-[a-z0-9-]+$/.test(id)) return { kind: 'tc' };
   return null;
 }
 

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/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/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;
+}