rcf-lite 0.28.4 → 0.29.0

package/src/query/readiness.js

@@ -49,6 +49,24 @@ import {
  * @property {number[]} briefSince
  * @property {import('./impact.js').ImpactNode[]} impacted
  * @property {string[]} impactedFbs
+ * @property {Record<string, string>} currentDocHashes
+ *   Live per-document hashes (ledgers keyed as `ledger:<name>`).
+ *   Threaded from `computeDelta` so the Readiness tab can render a
+ *   document-level hash diff for each changed / added id (spec §5
+ *   block 6; the frozen body is not persisted in the freeze record
+ *   in 0.29.0, so the diff is hash-only for now).
+ */
+
+/**
+ * @typedef {object} CheckResult
+ * @property {string} name
+ * @property {boolean} ok
+ * @property {'delta'|'tree'} over
+ * @property {number} pass
+ * @property {number} total
+ * @property {Array<{ id: string, why: string }>} failing
+ * @property {'productOwner'|'engineer'} persona
+ * @property {string} question
  */
 
 /**
@@ -56,10 +74,47 @@ import {
  * @property {string} stage
  * @property {string} gate
  * @property {'passed'|'failing'|'acknowledged'|'notApplicable'} state
- * @property {Array<{ name: string, ok: boolean, over: 'delta'|'tree', pass: number, total: number, failing: Array<{ id: string, why: string }> }>} checks
+ * @property {CheckResult[]} checks
  * @property {string} [reason]
  */
 
+/**
+ * @typedef {object} Blocker
+ * @property {string} stage
+ * @property {string} gate
+ * @property {string} check
+ * @property {'productOwner'|'engineer'} persona
+ * @property {'delta'|'tree'} over
+ * @property {number} failingCount
+ * @property {string[]} ids
+ * @property {string} question
+ */
+
+/**
+ * @typedef {object} LevelVerdict
+ * @property {boolean} ok
+ * @property {Blocker[]} blockedBy
+ * @property {NextAction | null} nextAction
+ */
+
+/**
+ * @typedef {object} ReadinessLevels
+ * @property {LevelVerdict} intentComplete
+ * @property {LevelVerdict} readyToBuild
+ */
+
+/**
+ * @typedef {object} PersonaGroup
+ * @property {Blocker[]} blockers
+ * @property {NextAction | null} nextAction
+ */
+
+/**
+ * @typedef {object} ReadinessPersonas
+ * @property {PersonaGroup} productOwner
+ * @property {PersonaGroup} engineer
+ */
+
 /**
  * @typedef {object} NextAction
  * @property {string} stage
@@ -77,6 +132,8 @@ import {
  * @property {{ tree: import('./coverage.js').CoverageResult, delta: import('./coverage.js').CoverageResult[] }} coverage
  * @property {Array<Record<string, unknown>>} decisions
  * @property {boolean} freezeable
+ * @property {ReadinessLevels} levels
+ * @property {ReadinessPersonas} personas
  */
 
 /**
@@ -198,6 +255,14 @@ export function computeReadiness(tree, args = {}) {
   const freezeable = stages.every((s) => s.state === 'passed' || s.state === 'acknowledged' || s.state === 'notApplicable');
   const nextAction = freezeable ? null : deriveNextAction(stages);
 
+  // 7b. Fold `levels` and `personas` from stages[].checks[] alone
+  // (ADR-4126, proposal section 2.1). Nothing is written. L1
+  // intent-complete is "every productOwner check ok across every
+  // stage"; L2 ready-to-build equals freezeable with blockers over
+  // failing stages only.
+  const levels = deriveLevels(stages, freezeable, nextAction);
+  const personas = derivePersonas(stages, levels);
+
   // 8. Build the tree summary line inputs.
   const queue = computeQueue(tree);
   const fbsTotal = (tree.fbsItems ?? []).length;
@@ -219,12 +284,15 @@ export function computeReadiness(tree, args = {}) {
       briefSince: delta.briefSince,
       impacted: impactedNodes,
       impactedFbs,
+      currentDocHashes: delta.currentDocHashes ?? {},
     },
     stages,
     nextAction,
     coverage: { tree: coverageTree, delta: coverageDelta },
     decisions: openDecisions,
     freezeable,
+    levels,
+    personas,
   };
 }
 
@@ -266,33 +334,206 @@ function collectDeltaReqAncestors(tree, pivotIds) {
 
 /**
  * Pick the first failing stage in D1..D8 order and the first failing
- * check inside it, then compose a `NextAction`.
+ * check inside it, then compose a `NextAction`. With no `persona`
+ * passed, behaves exactly as 0.28.4 did (first failing stage, first
+ * failing check, largest failing list). With a `persona` ('productOwner'
+ * | 'engineer'), picks the first failing stage that holds a failing
+ * check of that persona, then the largest failing-list check among
+ * them; the command carries `--level intent` on the productOwner
+ * variant and no `--level` flag otherwise (proposal section 2.1).
+ *
+ * The productOwner next action is defined over every stage holding a
+ * failing PO check (not just stages with state `failing`), because
+ * `levels.intentComplete.blockedBy` ignores stage state. In practice
+ * PO checks live on blocking stages (D1, D2, D4, D7) so any failing
+ * PO check also makes its stage `failing`, but the compute does not
+ * rely on that coincidence.
  *
  * @param {StageResult[]} stages
+ * @param {'productOwner' | 'engineer'} [persona]
  * @returns {NextAction | null}
  */
-export function deriveNextAction(stages) {
+export function deriveNextAction(stages, persona) {
   const byStage = new Map(stages.map((s) => [s.stage, s]));
   for (const stageId of STAGE_ORDER) {
     const s = byStage.get(stageId);
-    if (!s || s.state !== 'failing') continue;
+    if (!s) continue;
+    // Without a persona filter: today's rule (stage must be
+    // `failing`; this skips `acknowledged` warn-with-ack stages).
+    // With a persona filter: scan any stage that holds a failing
+    // check of that persona. PO checks only live on blocking stages
+    // so this coincides with "stage failing" in practice, but it
+    // keeps the compute honest if that ever changes.
+    if (!persona && s.state !== 'failing') continue;
+    const failing = s.checks.filter((c) => !c.ok && (persona ? c.persona === persona : true));
+    if (failing.length === 0) continue;
     // First failing check; tie-break by the largest failing list so
     // the operator sees the most impactful gap first.
-    const failing = s.checks.filter((c) => !c.ok);
-    if (failing.length === 0) continue;
     const check = failing.reduce((a, b) => (b.failing.length > a.failing.length ? b : a), failing[0]);
     const ids = [...new Set(check.failing.map((f) => f.id))].slice(0, 20);
     const shortName = STAGE_SHORT_NAMES[stageId] ?? stageId;
+    const command = persona === 'productOwner'
+      ? `rcf define readiness --level intent --check ${shortName}`
+      : `rcf define readiness --check ${shortName}`;
     return {
       stage: stageId,
       check: check.name,
       ids,
-      command: `rcf define readiness --check ${shortName}`,
+      command,
     };
   }
   return null;
 }
 
+/**
+ * Build a `Blocker` row from a stage + check pair. `ids` are
+ * deduplicated and capped at 20 to match the display convention
+ * `nextAction.ids` uses (proposal section 2.1).
+ *
+ * @param {StageResult} stage
+ * @param {CheckResult} check
+ * @returns {Blocker}
+ */
+function makeBlocker(stage, check) {
+  return {
+    stage: stage.stage,
+    gate: stage.gate,
+    check: check.name,
+    persona: check.persona,
+    over: check.over,
+    failingCount: check.failing.length,
+    ids: [...new Set(check.failing.map((f) => f.id))].slice(0, 20),
+    question: check.question,
+  };
+}
+
+/**
+ * Fold the two levels from `stages[].checks[]` (ADR-4126, proposal
+ * section 2.1). L1 ignores stage state and lists every failing PO
+ * check; L2 lists every failing check in a stage whose state is
+ * `failing` (checks inside an `acknowledged` stage are not blockers).
+ *
+ * @param {StageResult[]} stages
+ * @param {boolean} freezeable
+ * @param {NextAction | null} nextAction
+ * @returns {ReadinessLevels}
+ */
+export function deriveLevels(stages, freezeable, nextAction) {
+  /** @type {Blocker[]} */
+  const poBlockers = [];
+  /** @type {Blocker[]} */
+  const buildBlockers = [];
+  for (const stage of stages) {
+    for (const check of stage.checks) {
+      if (check.ok) continue;
+      if (check.persona === 'productOwner') {
+        poBlockers.push(makeBlocker(stage, check));
+      }
+      if (stage.state === 'failing') {
+        buildBlockers.push(makeBlocker(stage, check));
+      }
+    }
+  }
+  const intentOk = poBlockers.length === 0;
+  return {
+    intentComplete: {
+      ok: intentOk,
+      blockedBy: poBlockers,
+      nextAction: intentOk ? null : deriveNextAction(stages, 'productOwner'),
+    },
+    readyToBuild: {
+      ok: freezeable,
+      blockedBy: buildBlockers,
+      nextAction,
+    },
+  };
+}
+
+/**
+ * Fold the `personas` block (ADR-4126, proposal section 3.3).
+ * `productOwner.blockers` deep-equals `levels.intentComplete.blockedBy`;
+ * `engineer.blockers` is the failing engineer checks in failing stages
+ * (the L2 blockedBy minus the PO entries).
+ *
+ * @param {StageResult[]} stages
+ * @param {ReadinessLevels} levels
+ * @returns {ReadinessPersonas}
+ */
+export function derivePersonas(stages, levels) {
+  const engineerBlockers = levels.readyToBuild.blockedBy.filter((b) => b.persona === 'engineer');
+  return {
+    productOwner: {
+      blockers: levels.intentComplete.blockedBy,
+      nextAction: levels.intentComplete.nextAction,
+    },
+    engineer: {
+      blockers: engineerBlockers,
+      nextAction: deriveNextAction(stages, 'engineer'),
+    },
+  };
+}
+
+/**
+ * Validate a `--level` flag value against the closed set
+ * `intent | build`. Returns the value, `null` when the flag was
+ * absent, or throws a usage error whose message is formatted exactly
+ * like the `--check` usage line so the CLI can forward it verbatim.
+ *
+ * @param {string | undefined} raw
+ * @returns {'intent' | 'build' | null}
+ */
+export function parseLevelFlag(raw) {
+  if (raw === undefined || raw === null) return null;
+  if (raw === 'intent' || raw === 'build') return raw;
+  throw new Error(`unknown --level ${raw} (expected intent | build)`);
+}
+
+/**
+ * Validate a `--persona` flag value against the closed set
+ * `productOwner | engineer`. Returns the value, `null` when the flag
+ * was absent, or throws a usage error with the same shape.
+ *
+ * @param {string | undefined} raw
+ * @returns {'productOwner' | 'engineer' | null}
+ */
+export function parsePersonaFlag(raw) {
+  if (raw === undefined || raw === null) return null;
+  if (raw === 'productOwner' || raw === 'engineer') return raw;
+  throw new Error(`unknown --persona ${raw} (expected productOwner | engineer)`);
+}
+
+/**
+ * Format the two verdict lines shared by the CLI text report and
+ * the Readiness tab (proposal section 2.3). The strings are built
+ * from `levels` alone so the two surfaces cannot disagree.
+ *
+ * @param {ReadinessResult} result
+ * @returns {{ intentComplete: string, readyToBuild: string }}
+ */
+export function formatVerdictLines(result) {
+  const l = result.levels;
+  const intentLine = l.intentComplete.ok
+    ? 'Intent-complete: yes. Every product-owner question is answered.'
+    : (() => {
+      const n = l.intentComplete.blockedBy.length;
+      const detail = l.intentComplete.blockedBy
+        .map((b) => `${b.stage}/${b.check}`)
+        .join(', ');
+      return `Intent-complete: no; ${n} question${n === 1 ? '' : 's'} for the product owner (${detail}).`;
+    })();
+  const buildLine = l.readyToBuild.ok
+    ? `Ready-to-build: yes. Freezeable at ${shortHash(result.tree.currentTreeHash)}.`
+    : (() => {
+      const blockers = l.readyToBuild.blockedBy;
+      const stages = [...new Set(blockers.map((b) => b.stage))].sort();
+      const total = blockers.length;
+      const p = blockers.filter((b) => b.persona === 'productOwner').length;
+      const e = blockers.filter((b) => b.persona === 'engineer').length;
+      return `Ready-to-build: no; blocked on ${stages.join(', ')} (${total} check${total === 1 ? '' : 's'}: ${p} product owner, ${e} engineer).`;
+    })();
+  return { intentComplete: intentLine, readyToBuild: buildLine };
+}
+
 /**
  * Short 8-character prefix of a `sha256:<hex>` string, or '(none)' when
  * absent. Kept exported so text formatters share one convention.

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