@kontourai/flow-agents 2.1.1 → 2.2.0

package/scripts/hooks/lib/local-artifact-paths.js

@@ -0,0 +1,32 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const KONTOURAI_DIR = '.kontourai';
+const LEGACY_FLOW_AGENTS_DIR = '.flow-agents';
+
+function flowAgentsArtifactRoot(cwd = process.cwd()) {
+  return path.resolve(cwd, KONTOURAI_DIR, 'flow-agents');
+}
+
+function legacyFlowAgentsArtifactRoot(cwd = process.cwd()) {
+  return path.resolve(cwd, LEGACY_FLOW_AGENTS_DIR);
+}
+
+function flowAgentsArtifactRootsForRead(cwd = process.cwd()) {
+  const roots = [flowAgentsArtifactRoot(cwd), legacyFlowAgentsArtifactRoot(cwd)];
+  return roots.filter((root, index) => roots.indexOf(root) === index && fs.existsSync(root));
+}
+
+function defaultArtifactRootForRead(cwd = process.cwd()) {
+  const roots = flowAgentsArtifactRootsForRead(cwd);
+  return roots[0] || flowAgentsArtifactRoot(cwd);
+}
+
+module.exports = {
+  flowAgentsArtifactRoot,
+  legacyFlowAgentsArtifactRoot,
+  flowAgentsArtifactRootsForRead,
+  defaultArtifactRootForRead,
+};

package/scripts/hooks/stop-goal-fit.js

@@ -38,6 +38,10 @@ const {
   canonicalJsonForChain,
   hasLaunderingOperator,
 } = require('../lib/command-log-chain.js');
+const {
+  flowAgentsArtifactRoot,
+  flowAgentsArtifactRootsForRead,
+} = require('./lib/local-artifact-paths');
 
 const MAX_STDIN = 1024 * 1024;
 const ACTIVE_STATUSES = new Set([
@@ -1575,11 +1579,11 @@ const HARD_BLOCK = /contradicts evidence\.json|caught false-completion|evidence
 const FULL_BLOCK = /status:|Definition Of Done|Goal Fit|sidecar validation:|contradicts evidence\.json|workflow state|evidence verdict|evidence check|NOT_VERIFIED gap|critique status|critique open|next action|caught false-completion|NOT_VERIFIED —|command-log integrity check FAILED|gate misconfiguration:|surface unavailable —|expected capture log is missing|exit-code-laundered/;
 
 async function analyze(root, now = Date.now()) {
-  const flowAgentsDir = path.join(root, '.flow-agents');
+  const flowAgentsDirs = flowAgentsArtifactRootsForRead(root);
   // Scope to the session's current task when current.json names one, so an
   // unrelated active workflow elsewhere in the repo does not gate this stop.
-  const scoped = preferredArtifactDir(flowAgentsDir);
-  const searchDirs = scoped ? [scoped] : [flowAgentsDir];
+  const scoped = flowAgentsDirs.map(preferredArtifactDir).find(Boolean);
+  const searchDirs = scoped ? [scoped] : flowAgentsDirs;
   const artifacts = searchDirs
     .flatMap(dir => walkMarkdown(dir))
     .map(readArtifact)
@@ -1589,6 +1593,7 @@ async function analyze(root, now = Date.now()) {
   if (artifacts.length === 0) return { warnings: [], blocking: false };
 
   const latest = artifacts[0];
+  const latestArtifactDir = path.dirname(latest.file);
   const warnings = [];
   const relPath = relative(root, latest.file);
   const status = latest.status || 'unknown';
@@ -1604,11 +1609,11 @@ async function analyze(root, now = Date.now()) {
 
   // ADR 0016 P-c: load the active FlowDefinition gate (fail-open: null when absent).
   // Null → existing workflow.* fallback path unchanged. Non-null → expects[]-driven claim selection.
-  const activeFlowStep = loadActiveFlowStep(flowAgentsDir);
+  const activeFlowStep = loadActiveFlowStep(path.dirname(latestArtifactDir));
 
-  warnings.push(...sidecarValidation(root, path.dirname(latest.file)));
-  warnings.push(...sidecarGuidance(root, path.dirname(latest.file), activeFlowStep));
-  const captureWarnings = captureCrossReference(root, path.dirname(latest.file), activeFlowStep);
+  warnings.push(...sidecarValidation(root, latestArtifactDir));
+  warnings.push(...sidecarGuidance(root, latestArtifactDir, activeFlowStep));
+  const captureWarnings = captureCrossReference(root, latestArtifactDir, activeFlowStep);
   warnings.push(...captureWarnings);
   // Dedup: bundleEnforcement and captureCrossReference can both fire "caught false-completion"
   // for the same disputed claim. Suppress the bundleEnforcement warning ONLY when
@@ -1622,7 +1627,7 @@ async function analyze(root, now = Date.now()) {
     const m = /evidence check ([^\s:]+):/.exec(w);
     if (m) captureHardBlockIds.add(m[1]);
   }
-  const bundleWarnings = (await bundleEnforcement(path.dirname(latest.file), activeFlowStep)).filter(w => {
+  const bundleWarnings = (await bundleEnforcement(latestArtifactDir, activeFlowStep)).filter(w => {
     if (!captureHardBlockIds.size) return true;
     // bundleEnforcement warns: "trust.bundle claim disputed: <subjectId> ..."
     const m = /trust\.bundle claim (?:disputed|tampered): ([^\s(]+)/.exec(w);
@@ -1634,21 +1639,21 @@ async function analyze(root, now = Date.now()) {
     return !captureHardBlockIds.has(checkId);
   });
   warnings.push(...bundleWarnings);
-  warnings.push(...missingBundleOrStateSignal(path.dirname(latest.file), activeFlowStep));
+  warnings.push(...missingBundleOrStateSignal(latestArtifactDir, activeFlowStep));
 
   // A pre-execution task (not started) OR a terminal task (which is itself a
   // completion *claim*) must not block on mere incompleteness — but a FALSE claim
   // (capture/evidence contradiction) still blocks at any phase. This is the whole
   // point of the capture cross-reference: catch a task that falsely claims done.
-  const gateState = readJsonFile(path.join(path.dirname(latest.file), 'state.json'));
+  const gateState = readJsonFile(path.join(latestArtifactDir, 'state.json'));
   const taskStatus = gateState ? normalizedStatus(gateState.status) : normalizedStatus(status);
-  const preExecution = isPreExecution(path.dirname(latest.file), status);
+  const preExecution = isPreExecution(latestArtifactDir, status);
   const terminal = TERMINAL_STATUSES.has(taskStatus);
 
   // Namespace-agnostic captured-FAIL reconciliation (AC1 — closes the allowlist bypass).
   // Fix A: status-independent — runs on EVERY stop. A claim contradicting the capture
   // is a false-completion whether or not the agent says the task is 'done'.
-  warnings.push(...capturedFailReconciliation(root, path.dirname(latest.file), taskStatus));
+  warnings.push(...capturedFailReconciliation(root, latestArtifactDir, taskStatus));
 
   // Use module-scope HARD_BLOCK / FULL_BLOCK (defined above analyze()).
   // pre-execution/terminal tasks: only HARD_BLOCK signals cause a block.
@@ -1686,7 +1691,8 @@ function resolveMaxBlocks() {
 }
 
 function blockStreakFile(root) {
-  return path.join(root, '.flow-agents', '.goal-fit-block-streak.json');
+  const artifactRoot = flowAgentsArtifactRoot(root);
+  return path.join(artifactRoot, '.goal-fit-block-streak.json');
 }
 
 function reasonsHash(warnings) {

package/scripts/hooks/workflow-steering.js

@@ -17,6 +17,7 @@
 const fs = require('fs');
 const path = require('path');
 const { readLivenessEvents, freshHolders } = require('./lib/liveness-read');
+const { flowAgentsArtifactRootsForRead } = require('./lib/local-artifact-paths');
 
 const STEERING = {
   'tool-planner': [
@@ -101,7 +102,8 @@ function readJson(file) {
 }
 
 function latestWorkflowState(root) {
-  const states = walkStateFiles(path.join(root, '.flow-agents'))
+  const states = flowAgentsArtifactRootsForRead(root)
+    .flatMap(artifactRoot => walkStateFiles(artifactRoot))
     .map(file => {
       let stat;
       try { stat = fs.statSync(file); } catch { return null; }
@@ -295,8 +297,8 @@ function resumeSteering(root, current) {
 
     // Liveness advisory
     try {
-      const livenessFile = path.join(root, '.flow-agents', 'liveness', 'events.jsonl');
-      const events = readLivenessEvents(livenessFile);
+      const events = flowAgentsArtifactRootsForRead(root)
+        .flatMap(artifactRoot => readLivenessEvents(path.join(artifactRoot, 'liveness', 'events.jsonl')));
       if (events.length > 0) {
         const selfActor = (process.env.FLOW_AGENTS_ACTOR || '').trim() || 'local';
         const holders = freshHolders(events, slug, selfActor, Date.now());

package/scripts/lib/command-log-chain.js

@@ -51,6 +51,11 @@ function computeChainHash(prevHash, record) {
  *   - ANY `||`             (e.g. `npm test || exit 0`, `|| echo ok`, `|| /bin/true`)
  *   - `| true`             (pipe into true — the pipeline absorbs the exit code)
  *   - trailing `; true` / `; :` / `; exit 0` / `; /bin/true` (and `\n` variants)
+ *
+ * FROZEN bar-raiser (ADR 0018). Do NOT add new evasion-pattern rules here; route new
+ * laundering shapes to the external CI anchor (trust-reconcile + the anti-gaming suite).
+ * Accepted limitation: the blanket `||` rule over-blocks legitimate control-flow `||`
+ * (e.g. `test -d node_modules || npm ci`) — it fails toward blocking by design.
  */
 function hasLaunderingOperator(cmd) {
   // ANY || in a claimed verification command is an exit-code mask.

package/scripts/migrate-local-artifacts.mjs

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+const VERITAS_GENERATED = new Set([
+  "evidence",
+  "claims",
+  "runs",
+  "repo-conformance",
+  "external",
+  "eval-drafts",
+  "evals",
+  "checkins",
+  "init-plans",
+  "recommendations",
+  "surface-console",
+]);
+
+function parseArgs(argv) {
+  const opts = { repos: [], workspaces: [], apply: false, dryRun: true, json: false, includeFlowAgents: false, force: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--apply") { opts.apply = true; opts.dryRun = false; continue; }
+    if (arg === "--dry-run") { opts.dryRun = true; opts.apply = false; continue; }
+    if (arg === "--json") { opts.json = true; continue; }
+    if (arg === "--include-flow-agents") { opts.includeFlowAgents = true; continue; }
+    if (arg === "--force") { opts.force = true; continue; }
+    if (arg === "--repo") { opts.repos.push(requireValue(argv, ++i, arg)); continue; }
+    if (arg === "--workspace") { opts.workspaces.push(requireValue(argv, ++i, arg)); continue; }
+    if (arg === "--help" || arg === "-h") { opts.help = true; continue; }
+    throw new Error(`unknown option: ${arg}`);
+  }
+  return opts;
+}
+
+function requireValue(argv, index, option) {
+  const value = argv[index];
+  if (!value || value.startsWith("--")) throw new Error(`${option} requires a path`);
+  return value;
+}
+
+function usage() {
+  return `Usage: node scripts/migrate-local-artifacts.mjs [--workspace <path>] [--repo <path>] [--include-flow-agents] [--apply] [--force] [--json]
+
+Dry-run is the default. --apply copies generated local artifacts into .kontourai without deleting old paths.
+`;
+}
+
+function unique(values) {
+  return [...new Set(values.map((value) => path.resolve(value)))];
+}
+
+function repoCandidates(opts) {
+  const repos = [...opts.repos.map((repo) => path.resolve(repo))];
+  const workspaces = opts.workspaces.length ? opts.workspaces : (opts.repos.length ? [] : [process.cwd()]);
+  for (const workspace of workspaces) {
+    const root = path.resolve(workspace);
+    if (isDirectory(root)) repos.push(root);
+    let entries = [];
+    try { entries = fs.readdirSync(root, { withFileTypes: true }); } catch { continue; }
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.name === "node_modules") continue;
+      repos.push(path.join(root, entry.name));
+    }
+  }
+  return unique(repos).filter(isDirectory);
+}
+
+function isDirectory(file) {
+  try { return fs.statSync(file).isDirectory(); } catch { return false; }
+}
+
+function exists(file) {
+  try { fs.lstatSync(file); return true; } catch { return false; }
+}
+
+function symlinkStatus(file) {
+  try { return fs.lstatSync(file).isSymbolicLink(); } catch { return false; }
+}
+
+function hasSymlinkParent(repo, target) {
+  const relativeParent = path.relative(repo, path.dirname(target));
+  if (!relativeParent || relativeParent.startsWith("..") || path.isAbsolute(relativeParent)) return false;
+  let current = repo;
+  for (const part of relativeParent.split(path.sep)) {
+    if (!part) continue;
+    current = path.join(current, part);
+    if (symlinkStatus(current)) return true;
+  }
+  return false;
+}
+
+function generatedMappings(repo, includeFlowAgents) {
+  const mappings = [
+    [".kontour", ".kontourai/console"],
+    [".telemetry", ".kontourai/telemetry"],
+    [".flow/runs", ".kontourai/flow/runs"],
+    [".surface/runs", ".kontourai/surface/runs"],
+  ];
+  for (const name of VERITAS_GENERATED) mappings.push([`.veritas/${name}`, `.kontourai/veritas/${name}`]);
+  mappings.push([".veritas/standards-feedback", ".kontourai/veritas/standards-feedback"]);
+  mappings.push([".veritas/standards-feedback-drafts", ".kontourai/veritas/standards-feedback-drafts"]);
+  if (includeFlowAgents) mappings.push([".flow-agents", ".kontourai/flow-agents"]);
+  return mappings.map(([from, to]) => ({ repo, from: path.join(repo, from), to: path.join(repo, to), relFrom: from, relTo: to }));
+}
+
+function durableSkips(repo, includeFlowAgents) {
+  const paths = [
+    ".flow/config.json",
+    ".flow/definitions",
+    ".veritas/repo-map.json",
+    ".veritas/repo-standards",
+    ".veritas/authority",
+    ".veritas/proof-families",
+    ".agents",
+    ".claude/commands",
+    "docs",
+  ];
+  if (!includeFlowAgents) paths.push(".flow-agents");
+  return paths.map((rel) => ({ repo, path: path.join(repo, rel), rel, reason: "durable-or-not-included" })).filter((item) => exists(item.path));
+}
+
+function listFiles(root) {
+  const out = [];
+  const stack = [root];
+  while (stack.length) {
+    const dir = stack.pop();
+    let entries = [];
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isSymbolicLink()) {
+        out.push({ file: full, symlink: true });
+      } else if (entry.isDirectory()) {
+        stack.push(full);
+      } else if (entry.isFile()) {
+        out.push({ file: full, symlink: false });
+      }
+    }
+  }
+  return out.sort((a, b) => a.file.localeCompare(b.file));
+}
+
+function planRepo(repo, opts) {
+  const copies = [];
+  const skipped = durableSkips(repo, opts.includeFlowAgents);
+  for (const mapping of generatedMappings(repo, opts.includeFlowAgents)) {
+    if (!exists(mapping.from)) continue;
+    const stat = fs.lstatSync(mapping.from);
+    if (stat.isSymbolicLink()) {
+      skipped.push({ repo, path: mapping.from, rel: mapping.relFrom, reason: "source-is-symlink" });
+      continue;
+    }
+    if (stat.isFile()) {
+      skipped.push({ repo, path: mapping.from, rel: mapping.relFrom, reason: "generated-root-is-file" });
+      continue;
+    }
+    if (!stat.isDirectory()) continue;
+    for (const item of listFiles(mapping.from)) {
+      const rel = path.relative(mapping.from, item.file);
+      const target = path.join(mapping.to, rel);
+      if (item.symlink) {
+        skipped.push({ repo, path: item.file, rel: path.join(mapping.relFrom, rel), reason: "source-is-symlink" });
+      } else if (hasSymlinkParent(repo, target)) {
+        skipped.push({ repo, path: item.file, rel: path.join(mapping.relFrom, rel), target, reason: "target-parent-is-symlink" });
+      } else if (exists(target)) {
+        if (symlinkStatus(target)) {
+          skipped.push({ repo, path: item.file, rel: path.join(mapping.relFrom, rel), target, reason: "target-is-symlink" });
+        } else if (!opts.force) {
+          skipped.push({ repo, path: item.file, rel: path.join(mapping.relFrom, rel), target, reason: "target-exists" });
+        } else {
+          copies.push({ repo, source: item.file, target, relSource: path.join(mapping.relFrom, rel), relTarget: path.join(mapping.relTo, rel) });
+        }
+      } else {
+        copies.push({ repo, source: item.file, target, relSource: path.join(mapping.relFrom, rel), relTarget: path.join(mapping.relTo, rel) });
+      }
+    }
+  }
+  return { repo, copies, skipped };
+}
+
+function copyFile(source, target) {
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.copyFileSync(source, target);
+}
+
+export function run(argv = process.argv.slice(2)) {
+  const opts = parseArgs(argv);
+  if (opts.help) return { help: usage(), reports: [], summary: { repos: 0, copies: 0, skipped: 0, applied: false, dry_run: true } };
+  const reports = repoCandidates(opts).map((repo) => planRepo(repo, opts));
+  if (opts.apply) {
+    for (const report of reports) for (const copy of report.copies) copyFile(copy.source, copy.target);
+  }
+  const summary = {
+    repos: reports.length,
+    copies: reports.reduce((sum, report) => sum + report.copies.length, 0),
+    skipped: reports.reduce((sum, report) => sum + report.skipped.length, 0),
+    applied: opts.apply,
+    dry_run: !opts.apply,
+  };
+  return { reports, summary };
+}
+
+function printText(result) {
+  if (result.help) {
+    process.stdout.write(result.help);
+    return;
+  }
+  console.log(`Local artifact migration ${result.summary.dry_run ? "dry-run" : "apply"}`);
+  console.log(`Repositories scanned: ${result.summary.repos}`);
+  console.log(`Files to copy: ${result.summary.copies}`);
+  console.log(`Skipped paths: ${result.summary.skipped}`);
+  for (const report of result.reports) {
+    if (!report.copies.length && !report.skipped.length) continue;
+    console.log(`\n${report.repo}`);
+    for (const copy of report.copies) console.log(`  COPY ${copy.relSource} -> ${copy.relTarget}`);
+    for (const skip of report.skipped) console.log(`  SKIP ${skip.rel}${skip.target ? ` -> ${path.relative(report.repo, skip.target)}` : ""} (${skip.reason})`);
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  try {
+    const result = run();
+    if (parseArgs(process.argv.slice(2)).json) console.log(JSON.stringify(result, null, 2));
+    else printText(result);
+  } catch (error) {
+    console.error(`migrate-local-artifacts: ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 1;
+  }
+}

package/scripts/telemetry/lib/config.sh

@@ -7,10 +7,9 @@ TELEMETRY_CONFIG_FILE="${TELEMETRY_CONFIG_FILE:-${TELEMETRY_DIR}/telemetry.conf}
 # Defaults
 TELEMETRY_ENABLED="${TELEMETRY_ENABLED:-true}"
 # TELEMETRY_DIR is <workspace>/scripts/telemetry, so the workspace root is
-# two levels up. Three levels escaped into the workspace's PARENT directory
-# (caught by live acceptance smoke 2026-06-11: events landed in /tmp/.telemetry
-# instead of the installed workspace).
-TELEMETRY_DATA_DIR="${TELEMETRY_DATA_DIR:-$(cd "${TELEMETRY_DIR}/../.." && pwd)/.telemetry}"
+# two levels up. Local runtime telemetry defaults under .kontourai/telemetry;
+# explicit TELEMETRY_DATA_DIR still wins.
+TELEMETRY_DATA_DIR="${TELEMETRY_DATA_DIR:-$(cd "${TELEMETRY_DIR}/../.." && pwd)/.kontourai/telemetry}"
 TELEMETRY_SESSION_DIR="${TELEMETRY_SESSION_DIR:-${TELEMETRY_DATA_DIR}/sessions}"
 TELEMETRY_ENRICH_SYSTEM="${TELEMETRY_ENRICH_SYSTEM:-true}"
 TELEMETRY_ENRICH_WORKSPACE="${TELEMETRY_ENRICH_WORKSPACE:-true}"

package/src/cli/public-api.test.mjs

@@ -0,0 +1,21 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import path from "node:path";
+
+import {
+  defaultArtifactRootForRead,
+  flowAgentsArtifactRoot,
+  KONTOURAI_DIR,
+  legacyFlowAgentsArtifactRoot,
+  LEGACY_FLOW_AGENTS_DIR,
+} from "../../build/src/index.js";
+
+test("public API exports local artifact root helpers", () => {
+  const cwd = path.resolve("/tmp/flow-agents-public-api");
+
+  assert.equal(KONTOURAI_DIR, ".kontourai");
+  assert.equal(LEGACY_FLOW_AGENTS_DIR, ".flow-agents");
+  assert.equal(flowAgentsArtifactRoot(cwd), path.join(cwd, ".kontourai", "flow-agents"));
+  assert.equal(legacyFlowAgentsArtifactRoot(cwd), path.join(cwd, ".flow-agents"));
+  assert.equal(defaultArtifactRootForRead(cwd), path.join(cwd, ".kontourai", "flow-agents"));
+});

package/src/cli/sidecar-claim-explain.ts

@@ -0,0 +1,130 @@
+// Claim explanation — a PURE projection extracted from workflow-sidecar.ts (ops#22).
+//
+// buildClaimExplanation is a pure function: report + bundle + id in, structured
+// explanation out. No fs, no CLI, no .flow-agents paths, no shared module state —
+// zero flow-agents specifics inside it, so it is unit-testable in isolation and can
+// be lifted to Surface unchanged (issue #171). The IO command handler `claimLookup`
+// that consumes it stays in workflow-sidecar.ts.
+
+type AnyObj = Record<string, any>;
+
+export interface ClaimEvidenceItem {
+  evidenceType: string;
+  label: string;
+  execution: { runner: string; label: string; isError: boolean; exitCode: number | null } | null;
+  passing: boolean;
+  summary: string;
+}
+
+export interface ClaimExplanation {
+  found: boolean;
+  status: string;
+  value: string;
+  claimType: string;
+  evidence: ClaimEvidenceItem[];
+  policy: {
+    id: string;
+    requiredEvidence: string[];
+    requiredMethods?: string[];
+    acceptanceCriteria: string[];
+    reviewAuthority: string;
+  } | null;
+  why: {
+    directInputs: AnyObj[];
+    leafClaims: AnyObj[];
+    diagnostics: AnyObj[];
+    transparencyGaps: AnyObj[];
+    changeRecords: AnyObj[];
+  };
+}
+
+/**
+ * Build a structured explanation for a specific claim.
+ * PURE: report + bundle + id in, structured explanation out.
+ * No fs, no CLI, no .flow-agents paths. Promotable to Surface #171.
+ *
+ * @param report   TrustReport from buildTrustReport(bundle) — required for derived status
+ * @param bundle   Raw parsed trust.bundle (BundleFile shape)
+ * @param claimId  The claim id to explain
+ */
+export function buildClaimExplanation(
+  report: Record<string, unknown>,
+  bundle: Record<string, unknown>,
+  claimId: string,
+): ClaimExplanation {
+  const reportClaims = Array.isArray(report.claims) ? (report.claims as AnyObj[]) : [];
+  const reportClaim = reportClaims.find((c: AnyObj) => c.id === claimId);
+
+  if (!reportClaim) {
+    return {
+      found: false,
+      status: "unknown",
+      value: "",
+      claimType: "",
+      evidence: [],
+      policy: null,
+      why: { directInputs: [], leafClaims: [], diagnostics: [], transparencyGaps: [], changeRecords: [] },
+    };
+  }
+
+  const bundleClaims = Array.isArray(bundle.claims) ? (bundle.claims as AnyObj[]) : [];
+  const bundleClaim = bundleClaims.find((c: AnyObj) => c.id === claimId) ?? reportClaim;
+  const bundlePolicies = Array.isArray(bundle.policies) ? (bundle.policies as AnyObj[]) : [];
+  const bundleEvidence = Array.isArray(bundle.evidence) ? (bundle.evidence as AnyObj[]) : [];
+
+  // Governing policy — follow verificationPolicyId into bundle.policies[]
+  const verificationPolicyId = typeof bundleClaim.verificationPolicyId === "string" ? bundleClaim.verificationPolicyId : undefined;
+  const rawPolicy = verificationPolicyId ? bundlePolicies.find((p: AnyObj) => p.id === verificationPolicyId) : undefined;
+  const policy = rawPolicy
+    ? {
+        id: String(rawPolicy.id ?? ""),
+        requiredEvidence: Array.isArray(rawPolicy.requiredEvidence) ? (rawPolicy.requiredEvidence as string[]) : [],
+        requiredMethods: Array.isArray(rawPolicy.requiredMethods) ? (rawPolicy.requiredMethods as string[]) : undefined,
+        acceptanceCriteria: Array.isArray(rawPolicy.acceptanceCriteria) ? (rawPolicy.acceptanceCriteria as string[]) : [],
+        reviewAuthority: String(rawPolicy.reviewAuthority ?? ""),
+      }
+    : null;
+
+  // Evidence enhancement: pull evidence items for this claim, surface the execution block
+  const claimEvidenceItems = bundleEvidence.filter((ev: AnyObj) => ev && ev.claimId === claimId);
+  const evidence: ClaimEvidenceItem[] = claimEvidenceItems.map((ev: AnyObj) => {
+    const exec = ev.execution && typeof ev.execution === "object" ? (ev.execution as AnyObj) : null;
+    const execution = exec
+      ? {
+          runner: String(exec.runner ?? exec.label ?? ""),
+          label: String(exec.label ?? exec.runner ?? ""),
+          isError: Boolean(exec.isError ?? (typeof exec.exitCode === "number" && exec.exitCode !== 0)),
+          exitCode: typeof exec.exitCode === "number" ? exec.exitCode : null,
+        }
+      : null;
+    return {
+      evidenceType: String(ev.evidenceType ?? ev.type ?? "unknown"),
+      label: String(ev.label ?? ev.excerptOrSummary ?? ev.sourceRef ?? ev.id ?? ""),
+      execution,
+      passing: execution ? !execution.isError : String(ev.status ?? "") !== "disputed",
+      summary: String(ev.excerptOrSummary ?? ev.summary ?? ev.label ?? ""),
+    };
+  });
+
+  // Drilldown: extract from report structure (report.transparencyGaps, report.changeRecords)
+  const allGaps = Array.isArray(report.transparencyGaps) ? (report.transparencyGaps as AnyObj[]) : [];
+  const allChanges = Array.isArray(report.changeRecords) ? (report.changeRecords as AnyObj[]) : [];
+  const transparencyGaps = allGaps.filter((g: AnyObj) => g && g.claimId === claimId);
+  const changeRecords = allChanges.filter((c: AnyObj) => c && c.claimId === claimId);
+
+  return {
+    found: true,
+    status: String(reportClaim.status ?? "unknown"),
+    value: String(bundleClaim.value ?? reportClaim.value ?? ""),
+    claimType: String(bundleClaim.claimType ?? reportClaim.claimType ?? ""),
+    evidence,
+    policy,
+    why: {
+      directInputs: [],   // populated by buildDerivationDrilldown if non-leaf
+      leafClaims: [],
+      diagnostics: [],
+      transparencyGaps,
+      changeRecords,
+    },
+  };
+}