rcf-lite 0.0.1 → 0.8.0

package/src/query/formatters/mermaid.js

@@ -0,0 +1,209 @@
+// Mermaid formatter for coverage / trace / impact result envelopes.
+// Phase 5 §D14: `flowchart LR` orientation, class palette matches
+// `src/view/mermaid-diagram.js`. Text-only output; no HTML wrapper.
+//
+// The class-defs block, `classForId`, and label helpers are
+// duplicated here rather than extracted from `src/view/mermaid-diagram.js`.
+// Reason (per Phase 5 brief §5, spec §D16): view-side helpers take
+// the view's `BuiltTreeModel` (title lookup via `model.byId`), while
+// this formatter operates over a pure `computeTrace` result envelope
+// that carries only node ids and kinds. Bridging the two contract
+// shapes would need a wrapper in the view module - the "invasive"
+// extraction the spec calls out. Duplicating ~30 LoC of trivial
+// static defs is cheaper and keeps the view module unchanged.
+
+const CLASS_DEFS = `
+  classDef prd fill:#fde68a,stroke:#92400e,color:#1f2937;
+  classDef req fill:#bbf7d0,stroke:#065f46,color:#1f2937;
+  classDef us fill:#bae6fd,stroke:#0c4a6e,color:#1f2937;
+  classDef ac fill:#e0e7ff,stroke:#3730a3,color:#1f2937;
+  classDef tad fill:#fecaca,stroke:#991b1b,color:#1f2937;
+  classDef tac fill:#fed7aa,stroke:#9a3412,color:#1f2937;
+  classDef adr fill:#fbcfe8,stroke:#9d174d,color:#1f2937;
+  classDef bs fill:#ddd6fe,stroke:#5b21b6,color:#1f2937;
+  classDef fbs fill:#c7d2fe,stroke:#3730a3,color:#1f2937;
+  classDef ts fill:#99f6e4,stroke:#115e59,color:#1f2937;
+  classDef tc fill:#d9f99d,stroke:#3f6212,color:#1f2937;
+  classDef cn fill:#a5b4fc,stroke:#312e81,color:#1f2937;
+  classDef broken stroke:#dc2626,stroke-width:2px,stroke-dasharray:5 5,color:#7f1d1d;
+`.trim();
+
+function classForId(id) {
+  if (id.startsWith('PRD-')) return 'prd';
+  if (id.startsWith('REQ-')) return 'req';
+  if (id.startsWith('US-')) return 'us';
+  if (id.startsWith('AC-')) return 'ac';
+  if (id.startsWith('TAD-')) return 'tad';
+  if (id.startsWith('TAC-')) return 'tac';
+  if (id.startsWith('ADR-')) return 'adr';
+  if (id.startsWith('BS-')) return 'bs';
+  if (id.startsWith('FBS-')) return 'fbs';
+  if (id.startsWith('TS-')) return 'ts';
+  if (id.startsWith('TC-')) return 'tc';
+  // Phase 10 (X2 CodeNode bridge, spec D12): CN cosmetic class.
+  if (id.startsWith('CN-')) return 'cn';
+  return 'unknown';
+}
+
+function nodeLabel(id) {
+  return `"${id}"`;
+}
+
+/**
+ * Emit `flowchart LR` mermaid text for a query result.
+ *
+ * @param {object} result
+ * @param {'coverage' | 'trace' | 'impact'} verb
+ * @returns {string}
+ */
+export function formatMermaid(result, verb) {
+  if (verb === 'coverage') return renderCoverageMermaid(result);
+  if (verb === 'trace') return renderTraceMermaid(result);
+  if (verb === 'impact') return renderImpactMermaid(result);
+  return '';
+}
+
+function renderCoverageMermaid(result) {
+  const lines = ['flowchart LR'];
+  const seenIds = new Set();
+  // w-2026-07-28-005: TCs whose pointer does not resolve carry the
+  // `broken` class on top of `tc` - dashed red stroke, so a stub TC is
+  // visibly not the same thing as a resolving one.
+  const unresolvedTcIds = new Set();
+  const declare = (id) => {
+    if (seenIds.has(id)) return;
+    seenIds.add(id);
+    lines.push(`  ${id}[${nodeLabel(id)}]`);
+  };
+  for (const req of result.requirements) {
+    declare(req.id);
+    for (const ac of req.acs) {
+      declare(ac.id);
+      lines.push(`  ${req.id} --> ${ac.id}`);
+      const unresolved = new Set(ac.unresolvedTestCases ?? []);
+      for (const tc of ac.testCases) {
+        declare(tc);
+        lines.push(`  ${ac.id} -.-> ${tc}`);
+        if (unresolved.has(tc)) unresolvedTcIds.add(tc);
+      }
+    }
+  }
+  for (const tc of unresolvedTcIds) {
+    lines.push(`  class ${tc} broken;`);
+  }
+  return `${appendClassBlock(lines, seenIds)}\n`;
+}
+
+function renderTraceMermaid(result) {
+  if (!result.found) return `%% trace: id ${result.pivot} not found\n`;
+  if (result.direction === 'both') {
+    // Two adjacent flowchart LR blocks with the pivot appearing in both,
+    // so the pivot visually anchors between ancestors and descendants
+    // (spec §D9).
+    const pivotId = result.pivot;
+    const ancestors = result.ancestors ?? [];
+    const descendants = result.descendants ?? [];
+    const ancBlock = buildTraceBlock({
+      title: 'Ancestors',
+      pivot: pivotId,
+      nodes: [{ id: pivotId, kind: 'pivot', depth: 0 }, ...ancestors],
+      edges: pairToEdges(ancestors, pivotId, /*isAncestor*/ true),
+    });
+    const descBlock = buildTraceBlock({
+      title: 'Descendants',
+      pivot: pivotId,
+      nodes: [{ id: pivotId, kind: 'pivot', depth: 0 }, ...descendants],
+      edges: pairToEdges(descendants, pivotId, /*isAncestor*/ false),
+    });
+    return `${ancBlock}\n\n${descBlock}\n`;
+  }
+  const lines = ['flowchart LR'];
+  const seenIds = new Set();
+  const declare = (id) => {
+    if (seenIds.has(id)) return;
+    seenIds.add(id);
+    lines.push(`  ${id}[${nodeLabel(id)}]`);
+  };
+  for (const n of result.nodes ?? []) declare(n.id);
+  for (const e of result.edges ?? []) {
+    const arrow = e.kind === 'crossLink' ? '-.->' : '-->';
+    lines.push(`  ${e.from} ${arrow} ${e.to}`);
+  }
+  return `${appendClassBlock(lines, seenIds)}\n`;
+}
+
+function renderImpactMermaid(result) {
+  if (!result.found) return `%% impact: id ${result.pivot} not found\n`;
+  const lines = ['flowchart LR'];
+  const seenIds = new Set();
+  const declare = (id) => {
+    if (seenIds.has(id)) return;
+    seenIds.add(id);
+    lines.push(`  ${id}[${nodeLabel(id)}]`);
+  };
+  for (const n of result.nodes ?? []) declare(n.id);
+  for (const e of result.edges ?? []) {
+    const arrow = e.kind === 'crossLink' ? '-.->' : '-->';
+    lines.push(`  ${e.from} ${arrow} ${e.to}`);
+  }
+  return `${appendClassBlock(lines, seenIds)}\n`;
+}
+
+// -- helpers --
+
+function buildTraceBlock({ nodes, edges }) {
+  const lines = ['flowchart LR'];
+  const seen = new Set();
+  const declare = (id) => {
+    if (seen.has(id)) return;
+    seen.add(id);
+    lines.push(`  ${id}[${nodeLabel(id)}]`);
+  };
+  for (const n of nodes) declare(n.id);
+  for (const e of edges) {
+    const arrow = e.kind === 'crossLink' ? '-.->' : '-->';
+    lines.push(`  ${e.from} ${arrow} ${e.to}`);
+  }
+  return appendClassBlock(lines, seen);
+}
+
+// The both-direction trace result does not preserve raw edges; synthesise
+// a linear chain from the pivot through ancestors / descendants in
+// depth order. Edge kind defaults to parentChild because we don't know
+// the arrival relationship at this layer - the caller uses the raw
+// forward / back envelopes when precise edge kinds matter.
+function pairToEdges(list, pivot, isAncestor) {
+  const edges = [];
+  if (list.length === 0) return edges;
+  if (isAncestor) {
+    // Ancestors sorted by depth descending (closest first). Chain the
+    // pivot -> first ancestor -> next ancestor. Depth on the trace
+    // result is negative, closest ancestor has depth -1.
+    let prev = pivot;
+    const sorted = [...list].sort((a, b) => (b.depth ?? 0) - (a.depth ?? 0));
+    for (const n of sorted) {
+      edges.push({ from: n.id, to: prev, kind: 'parentChild' });
+      prev = n.id;
+    }
+    return edges;
+  }
+  // Descendants: pivot -> depth 1 -> depth 2 -> ...
+  const sorted = [...list].sort((a, b) => (a.depth ?? 0) - (b.depth ?? 0));
+  let prev = pivot;
+  for (const n of sorted) {
+    edges.push({ from: prev, to: n.id, kind: 'parentChild' });
+    prev = n.id;
+  }
+  return edges;
+}
+
+function appendClassBlock(lines, ids) {
+  for (const id of ids) {
+    const cls = classForId(id);
+    if (cls !== 'unknown') lines.push(`  class ${id} ${cls};`);
+  }
+  lines.push(CLASS_DEFS);
+  return lines.join('\n');
+}
+
+export { classForId, CLASS_DEFS };

package/src/query/formatters/table.js

@@ -0,0 +1,203 @@
+// ASCII table formatter for coverage / trace / impact result envelopes.
+// Zero-dep, uses Node built-in string padding. Column widths adapt to
+// the widest cell per column, capped at a sane per-column maximum so a
+// single very long title doesn't force the whole table off-screen.
+//
+// Phase 5 §D3: default output format. British English column headers,
+// ASCII hyphens only (§D19).
+
+const COLUMN_CAP = 60;
+
+/**
+ * Format a query result as an ASCII table (or two labelled blocks
+ * around a pivot for trace --both). Trailing newline included.
+ *
+ * @param {object} result
+ * @param {'coverage' | 'trace' | 'impact'} verb
+ * @returns {string}
+ */
+export function formatTable(result, verb) {
+  if (verb === 'coverage') return formatCoverageTable(result);
+  if (verb === 'trace') return formatTraceTable(result);
+  if (verb === 'impact') return formatImpactTable(result);
+  return '';
+}
+
+// w-2026-07-28-005: three-state cell vocabulary. 'unresolved' = TC rows
+// exist but none of their pointers resolves to a real test - the stub-TC
+// state, shown as its own word rather than folded into yes/no.
+function reqCoveredCell(req) {
+  if (req.covered) return 'yes';
+  return req.coverageClass === 'covered-unresolved' ? 'unresolved' : 'no';
+}
+
+function acCoveredCell(ac) {
+  if (ac.covered) return 'yes';
+  return ac.testCases.length > 0 ? 'unresolved' : 'no';
+}
+
+function testCasesCell(ac) {
+  if (ac.testCases.length === 0) return '-';
+  const unresolved = new Set(ac.unresolvedTestCases ?? []);
+  return ac.testCases
+    .map((tc) => (unresolved.has(tc) ? `${tc}[unresolved]` : tc))
+    .join(', ');
+}
+
+function formatCoverageTable(result) {
+  const lines = [];
+  const modeLabel = result.strict ? 'strict (per-AC)' : 'shallow-any';
+  lines.push(`Coverage mode: ${modeLabel}`);
+  lines.push(
+    `Requirements: ${result.totals.requirements}  ` +
+      `covered: ${result.totals.covered}  ` +
+      `covered-unresolved: ${result.totals.coveredUnresolved}  ` +
+      `uncovered: ${result.totals.uncovered}`,
+  );
+  lines.push('');
+  const rows = [];
+  // Phase 10 (X2 CodeNode bridge, D11): --with-code appends a Code column.
+  const withCode = Boolean(result.withCode);
+  const header = ['Requirement', 'Covered', 'AC', 'AC covered', 'Test cases'];
+  if (withCode) header.push('Code');
+  rows.push(header);
+  for (const req of result.requirements) {
+    if (req.acs.length === 0) {
+      const row = [req.id, reqCoveredCell(req), '(no AC)', '-', '-'];
+      if (withCode) row.push('-');
+      rows.push(row);
+      continue;
+    }
+    for (const [i, ac] of req.acs.entries()) {
+      const row = [
+        i === 0 ? req.id : '',
+        i === 0 ? reqCoveredCell(req) : '',
+        ac.id,
+        acCoveredCell(ac),
+        testCasesCell(ac),
+      ];
+      if (withCode) row.push(ac.codeClass ?? '-');
+      rows.push(row);
+    }
+  }
+  lines.push(renderTable(rows));
+  const unresolvedPointers = result.unresolvedTestPointers ?? [];
+  if (unresolvedPointers.length > 0) {
+    lines.push('');
+    lines.push('Unresolved test pointers (never counted as coverage):');
+    for (const u of unresolvedPointers) {
+      const pointer = u.testPointer ?? '(no pointer)';
+      lines.push(`  ${u.tcId} (${u.tsId}): ${pointer} - ${u.reason}`);
+    }
+  }
+  if (withCode) {
+    lines.push('');
+    lines.push(
+      `Code totals: implemented-and-covered=${result.codeTotals.implementedAndCovered} ` +
+        `implemented-uncovered=${result.codeTotals.implementedUncovered} ` +
+        `unimplemented=${result.codeTotals.unimplemented}`,
+    );
+    lines.push(
+      result.codeNodeOrphans.length > 0
+        ? `CN-orphaned (no implementsAcIds): ${result.codeNodeOrphans.join(', ')}`
+        : 'CN-orphaned (no implementsAcIds): (none)',
+    );
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+function formatTraceTable(result) {
+  if (!result.found) return `trace: id ${result.pivot} not found\n`;
+  if (result.direction === 'both') {
+    return formatBothTraceTable(result);
+  }
+  const lines = [];
+  const directionLabel = result.direction === 'forward' ? 'Descendants' : 'Ancestors';
+  lines.push(`Trace pivot: ${result.pivot}  direction: ${result.direction}`);
+  lines.push('');
+  const rows = [];
+  rows.push(['Depth', 'Id', 'Kind', 'Title']);
+  const showList = (result.nodes ?? []).slice();
+  if (showList.length <= 1) {
+    lines.push(`${directionLabel}: (none)`);
+  } else {
+    for (const n of showList) {
+      rows.push([String(n.depth), n.id, n.kind, cellTitle(n.id)]);
+    }
+    lines.push(renderTable(rows));
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+function formatBothTraceTable(result) {
+  const lines = [];
+  lines.push(`Trace pivot: ${result.pivot}  direction: both`);
+  lines.push('');
+  lines.push('Ancestors:');
+  const ancestors = result.ancestors ?? [];
+  if (ancestors.length === 0) {
+    lines.push('  (none)');
+  } else {
+    const rows = [['Depth', 'Id', 'Kind', 'Title']];
+    for (const n of ancestors) rows.push([String(n.depth), n.id, n.kind, '']);
+    lines.push(renderTable(rows));
+  }
+  lines.push('');
+  lines.push(`Pivot: ${result.pivot}`);
+  lines.push('');
+  lines.push('Descendants:');
+  const descendants = result.descendants ?? [];
+  if (descendants.length === 0) {
+    lines.push('  (none)');
+  } else {
+    const rows = [['Depth', 'Id', 'Kind', 'Title']];
+    for (const n of descendants) rows.push([String(n.depth), n.id, n.kind, '']);
+    lines.push(renderTable(rows));
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+function formatImpactTable(result) {
+  if (!result.found) return `impact: id ${result.pivot} not found\n`;
+  const lines = [];
+  lines.push(`Impact pivot: ${result.pivot}`);
+  lines.push('');
+  const rows = [['Id', 'Kind', 'Role', 'Action needed']];
+  for (const n of result.nodes ?? []) {
+    rows.push([n.id, n.kind, n.role, n.actionNeeded ?? '-']);
+  }
+  lines.push(renderTable(rows));
+  return `${lines.join('\n')}\n`;
+}
+
+// Table renderer. Every cell is stringified, truncated at COLUMN_CAP,
+// then padded to the column's widest observed cell. Deterministic
+// spacing; no ANSI colours; two spaces between columns.
+
+function renderTable(rows) {
+  const widths = new Array(rows[0].length).fill(0);
+  const cells = rows.map((r) => r.map((c) => {
+    let s = c == null ? '' : String(c);
+    if (s.length > COLUMN_CAP) s = `${s.slice(0, COLUMN_CAP - 3)}...`;
+    return s;
+  }));
+  for (const r of cells) {
+    for (let i = 0; i < r.length; i += 1) {
+      if (r[i].length > widths[i]) widths[i] = r[i].length;
+    }
+  }
+  const out = cells.map(
+    (r) => r.map((c, i) => c.padEnd(widths[i])).join('  ').replace(/ +$/, ''),
+  );
+  // Header separator: `-` under each column.
+  const sep = widths.map((w) => '-'.repeat(w)).join('  ').replace(/ +$/, '');
+  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 '';
+}

package/src/query/impact.js

@@ -0,0 +1,173 @@
+// Pure impact compute. Impact = trace-forward + trace-back + a
+// labelled `actionNeeded` column per node kind + role (Phase 5 §D7).
+//
+// The delta over `computeTrace(..., 'both')` is the labelled
+// `actionNeeded` column: it turns a raw traversal into an actionable
+// re-verify / re-approve fan-out that the operator can walk through
+// end-to-end.
+//
+// Action label rules (§D7):
+//   - PRD ancestor: "re-approve"
+//   - TAD ancestor: "review-arch"
+//   - BS ancestor: "review-plan"
+//   - REQ / US descendant: "review-scope"
+//   - AC descendant: "re-approve"
+//   - TS descendant: "re-verify"
+//   - TC descendant: "re-run"
+//   - FBS descendant: "re-execute" (cross-linked to an affected AC,
+//                     or a dependent of an affected FBS)
+//   - TAC / ADR descendant: "review-context" (reached via a
+//                     contextRequirements cross-link, which is what
+//                     the current impact fan-out surfaces)
+//   - Pivot: null
+
+import { computeTrace, kindOf } from './trace.js';
+
+/**
+ * @typedef {import('#core/store/walker.js').TreeModel} TreeModel
+ */
+
+/**
+ * @typedef {'pivot' | 'ancestor' | 'descendant'} ImpactRole
+ */
+
+/**
+ * @typedef {object} ImpactNode
+ * @property {string} id
+ * @property {string} kind
+ * @property {ImpactRole} role
+ * @property {string | null} actionNeeded
+ */
+
+/**
+ * @typedef {object} ImpactEdge
+ * @property {string} from
+ * @property {string} to
+ * @property {'parentChild' | 'crossLink'} kind
+ */
+
+/**
+ * @typedef {object} ImpactResult
+ * @property {string} pivot
+ * @property {boolean} found - false when the pivot id is unknown
+ * @property {ImpactNode[]} [nodes]
+ * @property {ImpactEdge[]} [edges]
+ */
+
+/**
+ * Compute impact for a pivot. Composes computeTrace('both') and layers
+ * the D7 actionNeeded column per (kind, role).
+ *
+ * @param {TreeModel} tree
+ * @param {object} opts
+ * @param {string} opts.id
+ * @param {boolean} [opts.includeCode] - Phase 10: extend the forward fan-out
+ *   into Code Nodes.
+ * @returns {ImpactResult}
+ */
+export function computeImpact(tree, { id, includeCode = false }) {
+  const pivotKind = kindOf(tree, id);
+  if (!pivotKind) return { pivot: id, found: false };
+
+  const back = computeTrace(tree, { id, direction: 'back' });
+  // expandFbsDependents: impact is the blast-radius question, so the FBS
+  // dependency fan-out is in scope here (D7: a dependent of an affected
+  // FBS is labelled re-execute). Plain trace keeps FBS as a cross-link
+  // leaf (AC-402-3).
+  const fwd = computeTrace(tree, {
+    id, direction: 'forward', includeCode, expandFbsDependents: true,
+  });
+
+  /** @type {ImpactNode[]} */
+  const nodes = [];
+  /** @type {ImpactEdge[]} */
+  const edges = [];
+  const seen = new Set();
+
+  const push = (n) => {
+    if (seen.has(n.id)) return;
+    seen.add(n.id);
+    nodes.push(n);
+  };
+
+  push({ id, kind: pivotKind, role: 'pivot', actionNeeded: null });
+
+  const backNodes = (back.nodes ?? []).filter((n) => n.id !== id);
+  for (const n of backNodes) {
+    push({
+      id: n.id,
+      kind: n.kind,
+      role: 'ancestor',
+      actionNeeded: labelFor(n.kind, 'ancestor'),
+    });
+  }
+  const fwdNodes = (fwd.nodes ?? []).filter((n) => n.id !== id);
+  for (const n of fwdNodes) {
+    push({
+      id: n.id,
+      kind: n.kind,
+      role: 'descendant',
+      actionNeeded: labelFor(n.kind, 'descendant'),
+    });
+  }
+
+  // Edges: combine both directions. De-dupe on (from, to) so the same
+  // edge doesn't appear twice when the forward and back traces share a
+  // segment (they don't, structurally, but keep the guard for safety).
+  const edgeKey = (e) => `${e.from}->${e.to}`;
+  const edgeSeen = new Set();
+  for (const e of (back.edges ?? []).concat(fwd.edges ?? [])) {
+    const k = edgeKey(e);
+    if (edgeSeen.has(k)) continue;
+    edgeSeen.add(k);
+    edges.push(e);
+  }
+
+  return { pivot: id, found: true, nodes, edges };
+}
+
+/**
+ * Map (kind, role) to a D7 action label. Returns null when no rule
+ * applies (either because it's the pivot or because the kind isn't
+ * in the D7 table for that role - a design defensive default).
+ *
+ * @param {string} kind
+ * @param {ImpactRole} role
+ * @returns {string | null}
+ */
+export function labelFor(kind, role) {
+  if (role === 'pivot') return null;
+  if (role === 'ancestor') {
+    switch (kind) {
+      case 'prd': return 're-approve';
+      case 'tad': return 'review-arch';
+      case 'buildSequence': return 'review-plan';
+      case 'req': return 'review-scope';
+      case 'userStory': return 'review-scope';
+      case 'ac': return 're-approve';
+      case 'testSuite': return 're-verify';
+      case 'tac': return 'review-arch';
+      case 'adr': return 'review-arch';
+      case 'fbs': return 're-execute';
+      default: return null;
+    }
+  }
+  // descendant
+  switch (kind) {
+    case 'prd': return 're-approve';
+    case 'tad': return 'review-arch';
+    case 'buildSequence': return 'review-plan';
+    case 'req': return 'review-scope';
+    case 'userStory': return 'review-scope';
+    case 'ac': return 're-approve';
+    case 'testSuite': return 're-verify';
+    case 'tc': return 're-run';
+    case 'fbs': return 're-execute';
+    case 'tac': return 'review-context';
+    case 'adr': return 'review-context';
+    // Phase 10 (X2 CodeNode bridge): a code node reached forward from a
+    // spec change is source that may need re-implementation + re-test.
+    case 'codeNode': return 're-verify-code';
+    default: return null;
+  }
+}

package/src/query/index.js

@@ -0,0 +1,13 @@
+// Public surface for the query layer (Phase 5 §D16). Pure logic +
+// formatters; handlers live under `src/cli/`.
+
+export { computeCoverage, classifyCoverageScope } from './coverage.js';
+export { computeTrace, kindOf } from './trace.js';
+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 };
+}