rcf-lite 0.28.4 → 0.30.0

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

@@ -14,8 +14,32 @@
 // 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.
+//
+// 0.30.0 PR 9 (REQ-179 enforcement locus, spec section 17): the wrap
+// also cites the three DEFINE-stage NV-DL rules the review found
+// enforced only by the gates themselves (ADM-02 for D4 stories floor,
+// ADM-03 for D3 shapes bite, ADM-04 for the `rcf define validate`
+// finding set). Callers pass the computed readiness result (or the
+// stage envelopes they already carry) and the validate-errors array;
+// the wrap evaluates each rule against the current tree hash and the
+// freeze.gates acknowledgement map, cites the rule ids in the refusal
+// envelope, and leaves the enforcement posture of each caller intact
+// (readiness stays informational; freeze still exits 4 on an unfrozen
+// tree via its own freezeableAfterAck check). A stage that is
+// 'passed', 'acknowledged' or 'notApplicable' at the current hash
+// never cites a rule. Override channels differ by rule (R12 ruling
+// 2026-10-03): ADM-03 (D3) is cleared by an `--ack <gate>=<reason>`
+// recorded on freeze.gates at the current tree hash (D3 is ackable
+// per decision 9); ADM-02 (D4) is NOT ackable (decision 9 keeps D4
+// blocking) and its only recordedInChain channel is `freeze.override`
+// written by `rcf build bundle --next --override "<reason>"` -- in
+// the normal case the author fixes the failing D4 findings. ADM-04
+// has no gate ack either: the override is a chain correction
+// committed to git (NV-DL-ADM-04's recordedInChain shape).
 
 import { enforceAdmissibility, getRulesetToolScope } from '#admissibility';
+// 0.30.0 PR 8 (REQ-179 / TAC-4125): NV-DL admissibility.
+import { loadFreezeRecord } from '../define/freeze-record.js';
 
 /**
  * @typedef {import('../admissibility/enforce.js').AdmissibilityVerdict} AdmissibilityVerdict
@@ -30,19 +54,83 @@ import { enforceAdmissibility, getRulesetToolScope } from '#admissibility';
  * @property {string} [refusal] - human-readable summary on 'refused-admissibility'.
  */
 
+/**
+ * 0.30.0 PR 9 (REQ-179 enforcement locus): evaluate the three
+ * DEFINE-stage NV-DL rules against a readiness result plus a
+ * validate-errors array. Returns the set of refuseByDefault rule ids
+ * that bite at the current tree hash, after `--ack` reasons on
+ * freeze.gates are honoured. The caller composes this with the
+ * NV-BL admissibility verdict in `runWithAdmissibilityGate`.
+ *
+ * A stage counts as biting when:
+ *   - ADM-02: the D4 `stage.state` is `'failing'` (fix the failing
+ *     D4 findings; `freeze.override` written by
+ *     `rcf build bundle --next --override "<reason>"` is the only
+ *     recordedInChain override channel -- D4 is not ackable per
+ *     decision 9).
+ *   - ADM-03: the D3 `stage.state` is `'failing'` (D3 is ackable;
+ *     the override channel is `--ack <gate>=<reason>` on
+ *     `rcf define readiness` / `rcf define freeze`).
+ *   - ADM-04: `validateErrors.length > 0` (override is a chain
+ *     correction committed to git, not a gate ack).
+ *
+ * For ADM-03 the readiness compose folds a current-hash
+ * `--ack <gate>=<reason>` into `state: 'acknowledged'` via
+ * `foldState`, and a stale ack never masks a current failure.
+ * D4 is not folded (decision 9 keeps `ackable` to D3/D5/D6 only), so
+ * an ADM-02 citation only clears when the author fixes the findings
+ * or records `freeze.override`.
+ *
+ * @param {object} args
+ * @param {Array<{ stage: string, gate: string, state: string }>} [args.stages]
+ * @param {Array<unknown>} [args.validateErrors]
+ * @returns {{ bitingRules: string[], d3State: string|null, d4State: string|null, validateCount: number }}
+ */
+export function evaluateDefineStageAdmissibility({ stages = [], validateErrors = [] } = {}) {
+  const stageByName = new Map();
+  for (const s of stages) {
+    if (s && typeof s.stage === 'string') stageByName.set(s.stage, s);
+  }
+  const d3 = stageByName.get('D3');
+  const d4 = stageByName.get('D4');
+  const bitingRules = [];
+  if (d4 && d4.state === 'failing') bitingRules.push('NV-DL-ADM-02');
+  if (d3 && d3.state === 'failing') bitingRules.push('NV-DL-ADM-03');
+  const validateCount = Array.isArray(validateErrors) ? validateErrors.length : 0;
+  if (validateCount > 0) bitingRules.push('NV-DL-ADM-04');
+  return {
+    bitingRules,
+    d3State: d3?.state ?? null,
+    d4State: d4?.state ?? null,
+    validateCount,
+  };
+}
+
 /**
  * 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.
  *
+ * 0.30.0 PR 9: callers may also pass `defineStages` (the computed
+ * readiness `stages[]`) and `defineValidateErrors` so the wrap can
+ * cite NV-DL-ADM-02/03/04 alongside the NV-BL rules. The producer
+ * STILL runs when the NV-BL verdict is pass or passWithOverrides,
+ * even when the NV-DL rules bite: the wrap's refusal shape is reserved
+ * for the hard NV-BL refusal (readiness is informational per
+ * AC-17902-4; freeze keeps its own freezeableAfterAck check). The
+ * biting NV-DL rule ids appear on the returned envelope so callers can
+ * log them in a single consistent line.
+ *
  * @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>}
+ * @param {Array<{ stage: string, gate: string, state: string }>} [args.defineStages]
+ * @param {Array<unknown>} [args.defineValidateErrors]
+ * @returns {Promise<QueryResult & { defineRules?: string[] }>}
  */
 export async function runWithAdmissibilityGate({
   tree,
@@ -50,6 +138,8 @@ export async function runWithAdmissibilityGate({
   overrides = [],
   produce,
   opts = {},
+  defineStages = [],
+  defineValidateErrors = [],
 } = {}) {
   const toolScope = await getRulesetToolScope();
   if (!toolScope.traceabilityAndQueryTools) {
@@ -60,14 +150,57 @@ export async function runWithAdmissibilityGate({
     return { status: 'ok', payload };
   }
   const verdict = await enforceAdmissibility({ tree, chainRulesetVersion, overrides, opts });
+  const defineEval = evaluateDefineStageAdmissibility({
+    stages: defineStages,
+    validateErrors: defineValidateErrors,
+  });
   if (verdict.verdict === 'refuse') {
-    const ruleIds = [...new Set(verdict.unresolved.map((f) => f.rule).filter(Boolean))].sort();
+    const nvBlRuleIds = [...new Set(verdict.unresolved.map((f) => f.rule).filter(Boolean))].sort();
+    const combinedRuleIds = [...new Set([...nvBlRuleIds, ...defineEval.bitingRules])].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.`,
+      defineRules: defineEval.bitingRules,
+      refusal: `traceability/query tool refused (NV-BL-SR-03 addendum): unresolved admissibility rules [${combinedRuleIds.join(', ')}]. Fix or record a NV-BL-ADM-05 override; for NV-DL-ADM-03 an --ack reason on freeze.gates clears the gate; for NV-DL-ADM-02 fix the D4 findings or record freeze.override via \`rcf build bundle --next --override "<reason>"\`; for NV-DL-ADM-04 correct the chain document.`,
     };
   }
   const payload = await Promise.resolve(produce());
-  return { status: 'ok', admissibility: verdict, payload };
+  return {
+    status: 'ok',
+    admissibility: verdict,
+    defineRules: defineEval.bitingRules,
+    payload,
+  };
+}
+
+/**
+ * 0.30.0 PR 8 (REQ-179, TAC-4125; AC-17902-2 / AC-17902-3). Evaluate
+ * NV-DL-ADM-01 against the project's freeze record: an unfrozen tree
+ * without `freeze.override` set is a refusal; `freeze.override`
+ * present satisfies the recordedInChain channel so the caller may
+ * proceed and name the override.
+ *
+ * Pure of walker I/O: it reads the freeze record only. Callers wrap
+ * their own tool / verb refusal path around the returned verdict.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @returns {Promise<{ verdict: 'ok' | 'refuse-nv-dl-adm-01', rule?: 'NV-DL-ADM-01', override?: {reason:string, by:string, at:string}|null, message?: string }>}
+ */
+export async function evaluateDefineAdmissibility({ projectRoot }) {
+  const freeze = await loadFreezeRecord({ projectRoot });
+  if (freeze && typeof freeze === 'object' && freeze.override) {
+    const o = freeze.override;
+    return { verdict: 'ok', override: { reason: o.reason, by: o.by, at: o.at } };
+  }
+  if (freeze && typeof freeze === 'object' && freeze.docHashes) {
+    return { verdict: 'ok', override: null };
+  }
+  return {
+    verdict: 'refuse-nv-dl-adm-01',
+    rule: 'NV-DL-ADM-01',
+    message:
+      'NV-DL-ADM-01: refused on an unfrozen tree. Close the change with `rcf define readiness` and `rcf define freeze`, '
+      + 'or record `freeze.override { reason, by, at }` via `rcf build bundle --next --override "<reason>"`.',
+  };
 }

package/src/ruleset/ruleset.json

@@ -53,6 +53,41 @@
       "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."
+    },
+    {
+      "id": "NV-DL-ADM-01",
+      "title": "rcf build bundle --next refuses without a freeze record",
+      "refuseByDefault": true,
+      "overrideChannel": "recordedInChain",
+      "notes": "0.30.0 PR 8 (REQ-177, spec section 4 bundle row). The verb exits 4 and names rcf define readiness; --override \"<reason>\" writes freeze.override { reason, by, at } and proceeds. The override is the recordedInChain channel for this rule."
+    },
+    {
+      "id": "NV-DL-ADM-02",
+      "title": "D4 stories floor failing items are findings (closed sets, ownerRef)",
+      "refuseByDefault": true,
+      "overrideChannel": "recordedInChain",
+      "notes": "0.30.0 PR 8 (REQ-179, spec section 4 NV-DL row). Surfaced through the admissibility wrap as a D4 finding. D4 is not ackable (decision 9 keeps `ackable` to D3/D5/D6); the only recordedInChain override channel is `freeze.override` written by `rcf build bundle --next --override \"<reason>\"`. The normal path is to fix the failing D4 findings. Ruling R12 (2026-10-03) corrects an earlier description that named --ack as the ADM-02 override."
+    },
+    {
+      "id": "NV-DL-ADM-03",
+      "title": "D3 shapes bite failing items are findings (template markers, entity join, paths)",
+      "refuseByDefault": true,
+      "overrideChannel": "recordedInChain",
+      "notes": "0.30.0 PR 8 (REQ-179, spec section 4 NV-DL row). Surfaced through the admissibility wrap as a D3 finding; the override channel is the --ack reason on freeze.gates (D3 is ackable)."
+    },
+    {
+      "id": "NV-DL-ADM-04",
+      "title": "rcf define validate finding set refuses with exit 3",
+      "refuseByDefault": true,
+      "overrideChannel": "recordedInChain",
+      "notes": "0.30.0 PR 8 (REQ-178, spec section 4 validate row). The four findings (interface kind outside the vocabulary, bracketed AC class prefix outside the known classes, tacIds naming a non-TAC, unresolving ownerRef or deliveredBy) exit 3; the override is a chain-document correction recorded in git history."
+    },
+    {
+      "id": "NV-DL-ADM-05",
+      "title": "rcf build bundle --next skips FBS impacted by a non-empty delta",
+      "refuseByDefault": true,
+      "overrideChannel": "recordedInChain",
+      "notes": "0.30.0 PR 8 (REQ-177, spec section 4 bundle row). On a non-empty delta the next-item selection filters re-execute FBS impacted by the delta out of the actionable queue with a stderr reason; when every actionable FBS is impacted and no override is given the verb exits 4. --override \"<reason>\" writes freeze.override and lets the verb proceed."
     }
   ],
   "gateRules": [

package/src/server/index.js

@@ -14,7 +14,7 @@ import { createServer } from 'node:http';
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 
-import { LIVE_CLIENT_PATH, STYLE_CSS_PATH, VENDORED_MERMAID_PATH, renderModelToPage } from '../view/index.js';
+import { LIVE_CLIENT_PATH, PAGE_INIT_PATH, STYLE_CSS_PATH, TEST_HOST_CLIENT_PATH, VENDORED_MERMAID_PATH, renderModelToPage } from '../view/index.js';
 import { watch as defaultWatch } from '../watch/index.js';
 import { createRouter } from './routes.js';
 import { createScopeHandler } from './scope-endpoint.js';
@@ -29,6 +29,10 @@ import { createSseHub } from './sse.js';
  * @property {number} [debounceMs=50]
  * @property {(line: string) => void} [log] - stderr sink
  * @property {typeof defaultWatch} [watchImpl] - injectable watch primitive for tests
+ * @property {boolean} [testHost=false] - viewer UI refresh PR 9 (TAC-4134,
+ *   ADR-4136): when true, mount the wespa host fixture at /test-host.html
+ *   plus its embed-client script at /test-host.js. Off by default so
+ *   wespa's proxy allow-list is unaffected.
  */
 
 /**
@@ -70,6 +74,7 @@ export async function startServer(args) {
   const debounceMs = typeof args.debounceMs === 'number' ? args.debounceMs : 50;
   const log = typeof args.log === 'function' ? args.log : () => {};
   const watchImpl = typeof args.watchImpl === 'function' ? args.watchImpl : defaultWatch;
+  const testHost = args.testHost === true;
 
   /** @type {{ version: number, fullPageHtml: string, contentHtml: string, errors: import('#core/errors').RcfError[] } | null} */
   let state = null;
@@ -97,6 +102,11 @@ export async function startServer(args) {
           contentHtml: result.contentHtml,
           errors: result.errors,
           pmPartials: result.pmPartials,
+          // Viewer UI refresh PR 7 (TAC-4132, ADR-4134): the ID lookup
+          // index is built once per rewalk and snapshotted on `state`
+          // so `GET /index.json` serves from memory and the SSE
+          // `tree-update` version lets the client invalidate its cache.
+          indexJson: result.indexJson,
         };
         sse.broadcast('tree-update', { version, contentHtml: result.contentHtml });
         if (result.errors && result.errors.length > 0) {
@@ -122,10 +132,17 @@ export async function startServer(args) {
   // so a checkout branch switch during the server's lifetime cannot
   // change what gets served. The tree walker is the only path that
   // re-reads disk on rcf/ change; every other asset is fixed at boot.
-  const [styleAsset, mermaidAsset, liveClientAsset] = await Promise.all([
+  const [styleAsset, mermaidAsset, liveClientAsset, pageInitAsset, testHostClientAsset] = await Promise.all([
     loadStaticAsset(STYLE_CSS_PATH, 'text/css; charset=utf-8'),
     loadStaticAsset(VENDORED_MERMAID_PATH, 'application/javascript; charset=utf-8'),
     loadStaticAsset(LIVE_CLIENT_PATH, 'application/javascript; charset=utf-8'),
+    loadStaticAsset(PAGE_INIT_PATH, 'application/javascript; charset=utf-8'),
+    // Viewer UI refresh PR 9 (TAC-4134): the wespa host fixture client
+    // only loads when testHost is on. Keeping the read behind the gate
+    // means a startup under default options never touches the file.
+    testHost
+      ? loadStaticAsset(TEST_HOST_CLIENT_PATH, 'application/javascript; charset=utf-8')
+      : Promise.resolve(null),
   ]);
 
   const scopeHandler = createScopeHandler({ projectRoot });
@@ -138,10 +155,15 @@ export async function startServer(args) {
     styleAsset,
     mermaidAsset,
     liveClientAsset,
+    pageInitAsset,
     stylePath: STYLE_CSS_PATH,
     mermaidPath: VENDORED_MERMAID_PATH,
     liveClientPath: LIVE_CLIENT_PATH,
+    pageInitPath: PAGE_INIT_PATH,
     scope: scopeHandler,
+    testHost,
+    testHostClientAsset,
+    testHostClientPath: testHost ? TEST_HOST_CLIENT_PATH : undefined,
   });
 
   const server = createServer(router);

package/src/server/routes.js

@@ -4,7 +4,28 @@
 // GET /style.css     -> shipped stylesheet
 // GET /mermaid.min.js-> vendored mermaid runtime
 // GET /live-client.js-> phase 3.8 live client script
+// GET /page-init.js  -> viewer UI refresh PR 1 shell / router script
+//                      (Dex / wespa 2026-10-02 #263; release-noted so
+//                      the proxy's route allow-list is extended).
 // GET /scope.json    -> deep-link scope resolver (w-2026-08-30-dave-020)
+// GET /index.json    -> viewer UI refresh PR 7 ID lookup index built
+//                      from BuiltTreeModel on every rewalk; `{ rows }`
+//                      with one row per document id plus one per AC
+//                      (ADR-4134; release-noted).
+// GET /_fixtures/components -> viewer UI refresh PR 2 component
+//                      fixture page (release-noted). Static page, no
+//                      live-walk coupling, so it is always available
+//                      even before the first rewalk completes.
+// GET /test-host.html -> viewer UI refresh PR 9 wespa host fixture
+//                      page (TAC-4134, ADR-4136). Only served when
+//                      `deps.testHost === true`; 404 otherwise so
+//                      wespa's reverse-proxy allow-list is unaffected.
+//                      Mimics the wespa shell (56px header, resizable
+//                      sidebar) and iframes the viewer at `./?embed=1
+//                      &theme=light`. Test-suite proof only; not a
+//                      shipped UI.
+// GET /test-host.js  -> viewer UI refresh PR 9 wespa host fixture
+//                      client script. Same testHost gate as the HTML.
 // Everything else -> 404 text/plain.
 //
 // No CORS headers, no cache headers on static assets beyond what the
@@ -12,6 +33,9 @@
 
 import { readFile, stat } from 'node:fs/promises';
 
+import { renderComponentsFixturePage } from '../view/components-fixture.js';
+import { renderTestHostPage } from '../view/test-host/fixture.js';
+
 // Issue #248 (0.28.3): the shipped static assets (style.css,
 // mermaid.min.js, live-client.js) MUST be resolved once at server
 // startup, not read from disk on every HTTP request. If the checkout
@@ -32,12 +56,13 @@ const MIME = {
   html: 'text/html; charset=utf-8',
   css: 'text/css; charset=utf-8',
   js: 'application/javascript; charset=utf-8',
+  json: 'application/json; charset=utf-8',
   txt: 'text/plain; charset=utf-8',
 };
 
 /**
  * @typedef {object} RouterDeps
- * @property {() => { fullPageHtml: string, contentHtml: string, version: number } | null} currentState
+ * @property {() => { fullPageHtml: string, contentHtml: string, version: number, indexJson?: string } | null} currentState
  * @property {ReturnType<typeof import('./sse.js').createSseHub>} sse
  * @property {string} stylePath
  * @property {string} mermaidPath
@@ -95,6 +120,10 @@ export function createRouter(deps) {
       serveAsset(res, deps.liveClientAsset, deps.liveClientPath, MIME.js).catch((err) => fail(res, err));
       return;
     }
+    if (path === '/page-init.js') {
+      serveAsset(res, deps.pageInitAsset, deps.pageInitPath, MIME.js).catch((err) => fail(res, err));
+      return;
+    }
     if (path.startsWith('/product-map/')) {
       const state = deps.currentState();
       if (!state || !state.pmPartials) {
@@ -113,6 +142,44 @@ export function createRouter(deps) {
       res.end(html);
       return;
     }
+    if (path === '/_fixtures/components') {
+      res.writeHead(200, { 'content-type': MIME.html, 'cache-control': 'no-store' });
+      res.end(renderComponentsFixturePage());
+      return;
+    }
+    if (path === '/test-host.html' && deps.testHost) {
+      // Viewer UI refresh PR 9 (TAC-4134, ADR-4136): the wespa host
+      // fixture is only mounted when the server was started with
+      // testHost: true. No X-Frame-Options, no CSP; the viewer's
+      // framing lint asserts the same on GET /.
+      res.writeHead(200, { 'content-type': MIME.html, 'cache-control': 'no-store' });
+      res.end(renderTestHostPage());
+      return;
+    }
+    if (path === '/test-host.js' && deps.testHost) {
+      serveAsset(res, deps.testHostClientAsset, deps.testHostClientPath, MIME.js).catch((err) => fail(res, err));
+      return;
+    }
+    if (path === '/index.json') {
+      // Viewer UI refresh PR 7 (TAC-4132, ADR-4134): the ID lookup
+      // index is built once per rewalk and lives on `state.indexJson`
+      // as a pre-stringified payload, so this handler never touches
+      // disk and content-length matches the exact bytes served.
+      const state = deps.currentState();
+      if (!state || typeof state.indexJson !== 'string') {
+        res.writeHead(503, { 'content-type': MIME.txt });
+        res.end('view server initialising\n');
+        return;
+      }
+      const body = state.indexJson;
+      res.writeHead(200, {
+        'content-type': MIME.json,
+        'content-length': String(Buffer.byteLength(body)),
+        'cache-control': 'no-store',
+      });
+      res.end(body);
+      return;
+    }
     if (path === '/scope.json') {
       if (typeof deps.scope !== 'function') {
         res.writeHead(404, { 'content-type': MIME.txt });

package/src/setup/identity-seed.js

@@ -75,6 +75,23 @@ escalation.)_
 
 unstated
 
+## Surface
+
+_(how the agent frames its review-ready output when a slice closes.
+One of the three values below on a single line; the seeded default is
+\`prDiff\` and a hand-edit is one word away.)_
+
+- \`viewer\`: the slice is reviewed in a rendered viewer surface (an
+  HTML preview, a Readiness tab, a dashboard). The agent lands on a
+  URL the operator opens.
+- \`runningApp\`: the slice is reviewed by running the app and
+  observing behaviour. The agent lands on a one-line reproduction
+  recipe.
+- \`prDiff\`: the slice is reviewed as a pull-request diff on the
+  shared repo. The agent lands on a PR link with the chain IDs listed.
+
+prDiff
+
 ## Project-scoped notes
 
 _(anything specific to this project that would be useful for the agent