rcf-lite 0.7.1 → 0.8.0

package/src/ruleset/ruleset.json

@@ -0,0 +1,146 @@
+{
+  "$schemaComment": "rcf-lite shared standards ruleset v1. Machine-readable contract consumed by build-lite's chain-admissibility lint, verify's per-AC scope check, and (from the umbrella release that adds it) rcf-define-lite's elicitation checklist. camelCase per estate convention. The rulesetVersion is stamped at load time from the umbrella package.json (see src/ruleset/index.js) per NV-BL-SR-02: there is no separate ruleset semver, its version is the rcf-lite umbrella version.",
+  "id": "rcf-lite-ruleset",
+  "provenance": {
+    "requirementsDoc": "projects/rcf-build-lite/docs/2026-08-06_build-lite-nextver-requirements.md",
+    "rulingSheet": "projects/rcf-build-lite/docs/2026-08-06_nextver-ruling-sheet.md",
+    "designWorkItem": "w-2026-07-28-012",
+    "ratifiedItems": [1, 2, 3, 4, 6, 7, 8, 11, 14, 15, 16, 17, 19]
+  },
+  "admissibilityRules": [
+    {
+      "id": "NV-BL-ADM-01",
+      "title": "Every functional REQ terminates in at least one AC observable as behaviour of the running product",
+      "requiresScopeTagVocabulary": true,
+      "refuseByDefault": true,
+      "overrideChannel": "recordedInChain",
+      "notes": "For every REQ classified functional, the chain must contain at least one AC that is observable in the running product, not only in a library or a fixture. AC-shape classifier tags govern which REQ-shapes must terminate in a runtime- or deployed-scope AC."
+    },
+    {
+      "id": "NV-BL-ADM-02",
+      "title": "AC-shape classifier assigns each AC a scope tag (library / runtime / deployed)",
+      "requiresScopeTagVocabulary": true,
+      "refuseByDefault": true,
+      "overrideChannel": "migrationStateUnclassified",
+      "notes": "The scope-tag vocabulary and the AC schema field that carries the tag live in rcf-schemas. See scopeTagVocabulary below."
+    },
+    {
+      "id": "NV-BL-ADM-03",
+      "title": "Bound TCs must exercise their AC's declared scope",
+      "requiresScopeTagVocabulary": true,
+      "refuseByDefault": true,
+      "overrideChannel": "migrationStateUnclassified",
+      "notes": "For each AC, the bound TC's scope must be equal to or wider than the AC's scope tag. Bootstrap window: chains authored before scope tags land carry scope 'unclassified' and are tolerated for one release cycle."
+    },
+    {
+      "id": "NV-BL-ADM-04",
+      "title": "Source-comment honesty gate",
+      "refuseByDefault": true,
+      "overrideChannel": "adrExternalBoundaryOnly",
+      "markerVocabularyRef": "sourceCommentMarkers",
+      "notes": "Source files bound to any FBS at status complete are scanned for admission markers. Any match refuses FBS completion. Per ratified ruling-sheet item 16, the only permitted override channel is an ADR recording the deferral for a genuine external-boundary blocker; the ADR names the marker text, the blocker, and the reason. NV-BL-ADM-05's generic recorded-override channel no longer covers source markers."
+    },
+    {
+      "id": "NV-BL-ADM-05",
+      "title": "Chain-admissibility gate is refuse-first, override-recorded",
+      "refuseByDefault": true,
+      "overrideChannel": "recordedInChain",
+      "notes": "A chain failing any admissibility check is refused before build starts. Explicit overrides are permitted for non-source-marker checks, recorded in the chain with rule id, reason, and authoring identity, and surfaced in the finalise summary. Source-comment markers (NV-BL-ADM-04) fall outside this generic override channel."
+    },
+    {
+      "id": "NV-BL-ADM-06",
+      "title": "Build-stage refusal on ruleset-version drift",
+      "refuseByDefault": true,
+      "overrideChannel": "recordedInChain",
+      "notes": "At build start, build-lite compares the ruleset version the chain declares it was authored against with the version the shipping lint enforces. Behaviour-changing drift refuses; additive-only drift warns. Ratified 2026-08-11 ruling-sheet item 7: define-stage drift is a warning-with-acknowledgement; build-stage drift is a refusal."
+    }
+  ],
+  "gateRules": [
+    {
+      "id": "NV-BL-GATE-01",
+      "title": "Pull rcf-verify profile-vs-AC check into the REVIEW stage",
+      "notes": "The profile-vs-AC scope-mismatch check runs at REVIEW time for every FBS, not only at finalise. Verify carries the check; the review-stage gate consumes the same helper."
+    },
+    {
+      "id": "NV-BL-GATE-02",
+      "title": "Deploy-smoke FBS is a chain-mandatory element for any REQ with deployed-scope ACs",
+      "requiresScopeTagVocabulary": true,
+      "notes": "Any chain whose REQ set contains at least one deployed-scope AC must contain at least one FBS whose build sequence boots the built artefact against a real config and asserts operator-visible behaviour."
+    },
+    {
+      "id": "NV-BL-GATE-03",
+      "title": "Boot-integration TC template family for runtime-scope ACs",
+      "templateFamilyRef": "tcTemplateFamily",
+      "notes": "Runtime-scope ACs whose bound TC is not a boot-integration TC or a wider-scope TC fail admissibility (via NV-BL-ADM-03) and REVIEW (via NV-BL-GATE-01)."
+    },
+    {
+      "id": "NV-BL-GATE-04",
+      "title": "Ruling-set consistency light-check at ruling-application time",
+      "checkFamilyRef": "rulingConsistencyChecks",
+      "notes": "Light mechanical checks only per ratified ruling-sheet item 4: no two rulings name the same external resource with contradictory constraints; no ruling implies a capability the ruled-in service does not have on the ruled-in tier. Probabilistic and suitability work belongs in rcf-define-lite under DL-REQ-VALIDATE-04."
+    }
+  ],
+  "scopeTagVocabulary": {
+    "sourcePackage": "@stravica-ai/rcf-schemas",
+    "schemaRef": "https://schemas.stravica.io/rcf/v0.4.0/common.schema.json#/$defs/scopeTag",
+    "values": [
+      { "value": "library", "description": "Observable in an isolated library or fixture." },
+      { "value": "runtime", "description": "Observable in the running product against local integration." },
+      { "value": "deployed", "description": "Observable on a booted artefact against real config and real network." },
+      { "value": "unclassified", "description": "Migration state for chains authored before the scope-tag vocabulary shipped; ruleset-enforcing consumers decide whether unclassified is currently accepted." }
+    ],
+    "unclassifiedMigrationTolerance": {
+      "toleratedFor": "one release cycle from the umbrella release that first ships this ruleset",
+      "expiresWhen": "rcf-define-lite ships and can take over elicitation"
+    }
+  },
+  "sourceCommentMarkers": [
+    { "marker": "TODO", "caseInsensitive": true },
+    { "marker": "FIXME", "caseInsensitive": true },
+    { "marker": "XXX", "caseInsensitive": true },
+    { "marker": "HACK", "caseInsensitive": true },
+    { "marker": "placeholder", "caseInsensitive": true },
+    { "marker": "v1 refinement", "caseInsensitive": true },
+    { "marker": "deferred", "caseInsensitive": true },
+    { "marker": "stub", "caseInsensitive": true }
+  ],
+  "tcTemplateFamily": [
+    {
+      "id": "TCT-SERVER-BOOT",
+      "title": "Server-boot integration TC",
+      "surface": "server",
+      "notes": "Boots the built server against a real config and asserts an operator-visible observable (probe fires, page returns 200 with expected content, and so on)."
+    },
+    {
+      "id": "TCT-CLI-INVOKE",
+      "title": "CLI-invoke integration TC",
+      "surface": "cli",
+      "notes": "Invokes the packaged CLI as an installed artefact (not via the workspace source) against a real config and asserts an operator-visible observable."
+    },
+    {
+      "id": "TCT-CONTAINER-RUN",
+      "title": "Container-run integration TC",
+      "surface": "container",
+      "notes": "Runs the built container against a real config and asserts an operator-visible observable."
+    }
+  ],
+  "rulingConsistencyChecks": [
+    {
+      "id": "RCC-EXTERNAL-RESOURCE-CONTRADICTION",
+      "title": "No two rulings name the same external resource with contradictory constraints",
+      "kind": "lightMechanical",
+      "notes": "Detects the Resend-collision class: Ruling A names service.tier=free and Ruling B names service.domainCount=N with N > tier-limit(free)."
+    },
+    {
+      "id": "RCC-TIER-CAPABILITY-MISMATCH",
+      "title": "No ruling implies a capability the ruled-in service does not have on the ruled-in tier",
+      "kind": "lightMechanical",
+      "notes": "Detects the ruling-in of a capability against a tier that cannot deliver it. Deep suitability checks live in rcf-define-lite under DL-REQ-VALIDATE-04."
+    }
+  ],
+  "toolScope": {
+    "chainAdmissibility": true,
+    "traceabilityAndQueryTools": true,
+    "notes": "Per ratified ruling-sheet item 1 addendum: the same rule set governs what a traceability or query tool may return as much as it governs what build may consume. A query tool that hides an admissibility failure is the same class of defect as a build that hides one."
+  }
+}

package/src/verify/chain/index.js

@@ -119,6 +119,29 @@ function fbsIdsFor(fbsItems, acId) {
   return out;
 }
 
+/**
+ * The bound TCs for `acId`, each carrying its own scope tag (if the TC
+ * declares one; unspecified surfaces as `undefined`). 0.8.0 slug-train
+ * car 4 (NV-BL-GATE-01: pull rcf-verify profile-vs-AC check into the
+ * REVIEW stage). Verify uses this to detect SCOPE-MISMATCH per-AC
+ * verdicts: a bound TC whose scope is NARROWER than the AC's scope tag
+ * cannot legitimately cover that AC (per NV-BL-ADM-03).
+ *
+ * @param {object[]} testSuites
+ * @param {string} acId
+ * @returns {Array<{ tsId: string, tcId: string, scope: string|undefined }>}
+ */
+function boundTcsFor(testSuites, acId) {
+  const out = [];
+  for (const ts of testSuites ?? []) {
+    for (const tc of ts.testCases ?? []) {
+      if (tc?.acId !== acId) continue;
+      out.push({ tsId: ts.id, tcId: tc.id, scope: tc.scope });
+    }
+  }
+  return out;
+}
+
 /**
  * Read the acceptance contract from the chain. Returns the flattened list of
  * acceptance criteria (each mapped back to its user story + requirement — the
@@ -157,6 +180,7 @@ export async function readChain({ repo, chainRef } = {}) {
 
   const resolvedRef = chainRef ?? tree.prd?.prdId ?? 'PRD-UNKNOWN';
   const fbsItems = tree.fbsItems ?? [];
+  const testSuites = tree.testSuites ?? [];
   const acs = [];
   for (const us of tree.userStories ?? []) {
     for (const ac of us.acceptanceCriteria ?? []) {
@@ -175,6 +199,13 @@ export async function readChain({ repo, chainRef } = {}) {
         serviceAttestations: serviceAttestationsFor(fbsItems, ac.id),
         fbsUiBearing: fbsUiBearingFor(fbsItems, ac.id),
         fbsIds: fbsIdsFor(fbsItems, ac.id),
+        // 0.8.0 slug-train car 4 (NV-BL-GATE-01, NV-BL-ADM-03): scope
+        // tags read straight off rcf-schemas 0.4.3's AC/TC subschemas;
+        // the verdict layer runs the scope check per-AC in REVIEW,
+        // matching what NV-BL-GATE-01 pulls in from the finalise-time
+        // profile check.
+        scope: ac.scope,
+        boundTcs: boundTcsFor(testSuites, ac.id),
       });
     }
   }

package/src/verify/verdict/index.js

@@ -50,12 +50,19 @@ export const VERDICTS = Object.freeze([...FINDING_SEVERITIES, 'NOT-DEPLOYED', 'B
  * `report.perAcVerdicts[]`. Consumed by `rcf finalise` to refuse promotion
  * to `verified` on any of these AC-level verdicts (see
  * `packages/rcf-lite/src/finalise/ingest.js:findMockOnlyDeclaredAcs`).
+ *
+ * 0.8.0 slug-train car 4 addition (NV-BL-GATE-01 + NV-BL-ADM-03):
+ *   - SCOPE-MISMATCH: an AC whose declared scope tag exceeds the scope
+ *     of every bound TC. Verify emits this at REVIEW time so the pull-in
+ *     from the finalise-time profile-vs-AC check fires per FBS rather
+ *     than only at finalise.
  */
 export const PER_AC_VERDICTS = Object.freeze([
   'MOCK-ONLY-DECLARED',
   'BLOCKED-BY-DECLARATION',
   'UI-BASELINE-UNMET',
   'BROWSER-VERIFICATION-MISSING',
+  'SCOPE-MISMATCH',
 ]);
 
 /**
@@ -220,6 +227,61 @@ export function uiPerAcVerdict(ac, browserVerification = []) {
   return null;
 }
 
+/**
+ * Rank each scope tag so we can compare "TC scope >= AC scope"
+ * numerically. Mirrors `packages/rcf-lite/src/admissibility/scope-lint.js`
+ * (single source of truth on rcf-schemas 0.4.3's scopeTag values;
+ * this copy stays deliberately local so the verdict layer does not
+ * depend on the admissibility module -- both consume the same schemas
+ * vocabulary and the same values, and duplicating the ranking here
+ * keeps the verdict layer standalone).
+ */
+const SCOPE_RANK = Object.freeze({
+  library: 1,
+  runtime: 2,
+  deployed: 3,
+});
+
+/**
+ * 0.8.0 slug-train car 4 (NV-BL-GATE-01 + NV-BL-ADM-03): the profile-vs-AC
+ * scope-mismatch check, pulled from finalise into REVIEW so it fires
+ * per FBS. An AC declared runtime-scope bound only to library-scope TCs
+ * emits SCOPE-MISMATCH; a wider TC (deployed covering runtime) is fine;
+ * an AC with no scope declaration is silent here (NV-BL-ADM-02 catches
+ * it at admissibility); a bound TC with no declared scope is silent
+ * here (bootstrap window; NV-BL-ADM-03 in the admissibility lint
+ * catches it there).
+ *
+ * @param {object} ac - flattened AC with `scope` and `boundTcs`
+ * @returns {{ verdict: 'SCOPE-MISMATCH', reason: string } | null}
+ */
+export function scopePerAcVerdict(ac) {
+  if (!ac || typeof ac.scope !== 'string') return null;
+  if (!Object.prototype.hasOwnProperty.call(SCOPE_RANK, ac.scope)) return null;
+  const boundTcs = Array.isArray(ac.boundTcs) ? ac.boundTcs : [];
+  if (boundTcs.length === 0) return null; // coverage rule handles "no TC at all".
+  const acRank = SCOPE_RANK[ac.scope];
+  const narrower = [];
+  let anyAtLeastAsWide = false;
+  for (const tc of boundTcs) {
+    if (typeof tc?.scope !== 'string') continue;
+    if (!Object.prototype.hasOwnProperty.call(SCOPE_RANK, tc.scope)) continue;
+    const tcRank = SCOPE_RANK[tc.scope];
+    if (tcRank >= acRank) {
+      anyAtLeastAsWide = true;
+      break;
+    }
+    narrower.push({ tsId: tc.tsId, tcId: tc.tcId, scope: tc.scope });
+  }
+  if (anyAtLeastAsWide) return null;
+  if (narrower.length === 0) return null;
+  const detail = narrower.map((n) => `${n.tcId} on ${n.tsId} (scope=${n.scope})`).join(', ');
+  return {
+    verdict: 'SCOPE-MISMATCH',
+    reason: `AC ${ac.acId} is scope=${ac.scope} but every bound TC is narrower: ${detail}. NV-BL-GATE-01 pulls this check into REVIEW; NV-BL-ADM-03 refuses at admissibility.`,
+  };
+}
+
 /**
  * Emit per-AC verdicts across the whole chain. Combines Track A's service
  * attestation verdicts with Track B's UI-baseline verdicts. An AC can carry
@@ -229,6 +291,9 @@ export function uiPerAcVerdict(ac, browserVerification = []) {
  * `packages/rcf-lite/src/finalise/ingest.js:findMockOnlyDeclaredAcs`, which
  * filters on verdict class and does not deduplicate by acId.
  *
+ * 0.8.0 slug-train car 4: SCOPE-MISMATCH runs here too, alongside the
+ * attestation and UI verdicts.
+ *
  * @param {object} opts
  * @param {Array<object>} opts.acs - flattened ACs from `readChain`
  * @param {object[]} [opts.browserVerification] - manifest.browserVerification[]
@@ -241,6 +306,8 @@ export function derivePerAcVerdicts({ acs = [], browserVerification = [] } = {})
     if (attest) out.push({ acId: ac.acId, verdict: attest.verdict, reason: attest.reason });
     const ui = uiPerAcVerdict(ac, browserVerification);
     if (ui) out.push({ acId: ac.acId, verdict: ui.verdict, reason: ui.reason });
+    const scopeMismatch = scopePerAcVerdict(ac);
+    if (scopeMismatch) out.push({ acId: ac.acId, verdict: scopeMismatch.verdict, reason: scopeMismatch.reason });
   }
   return out;
 }