@kontourai/flow-agents 2.1.0 → 2.2.0

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/repair-command-log.js

@@ -26,17 +26,10 @@ const path = require('path');
 const crypto = require('crypto');
 
 const gate = require(path.join(__dirname, 'hooks', 'stop-goal-fit.js'));
-const GENESIS = gate.CHAIN_GENESIS_VERIFY;
-
-function canon(rec) {
-  const keys = Object.keys(rec).filter((k) => k !== '_chain').sort();
-  const obj = {};
-  for (const k of keys) obj[k] = rec[k];
-  return JSON.stringify(obj);
-}
-function hashLink(prev, rec) {
-  return crypto.createHash('sha256').update(prev + canon(rec), 'utf8').digest('hex');
-}
+// Genesis + canonicalization/hash come from the single shared module, so a repaired
+// chain is re-linked byte-identically to how the writer/verifier compute it.
+const { CHAIN_GENESIS, canonicalJsonForChain, computeChainHash } = require('./lib/command-log-chain.js');
+const GENESIS = CHAIN_GENESIS;
 
 function main() {
   const dir = process.argv[2];
@@ -77,8 +70,8 @@ function main() {
   records.sort((a, b) => {
     const ta = String(a.capturedAt || ''), tb = String(b.capturedAt || '');
     if (ta !== tb) return ta < tb ? -1 : 1;
-    const ha = crypto.createHash('sha256').update(canon(a)).digest('hex');
-    const hb = crypto.createHash('sha256').update(canon(b)).digest('hex');
+    const ha = crypto.createHash('sha256').update(canonicalJsonForChain(a)).digest('hex');
+    const hb = crypto.createHash('sha256').update(canonicalJsonForChain(b)).digest('hex');
     return ha < hb ? -1 : ha > hb ? 1 : 0;
   });
 
@@ -87,7 +80,7 @@ function main() {
   let prev = GENESIS;
   let seq = 0;
   for (const rec of records) {
-    const h = hashLink(prev, rec);
+    const h = computeChainHash(prev, rec);
     out.push(JSON.stringify({ ...rec, _chain: { seq, prevHash: prev, hash: h } }));
     prev = h; seq += 1;
   }
@@ -100,7 +93,7 @@ function main() {
     source: 'chain-repair',
     repair: { reason, entries: records.length, forkAt: verdict.forkAt },
   };
-  const mh = hashLink(prev, marker);
+  const mh = computeChainHash(prev, marker);
   out.push(JSON.stringify({ ...marker, _chain: { seq, prevHash: prev, hash: mh } }));
 
   fs.copyFileSync(file, file + '.prebackup-repair');

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,
+    },
+  };
+}

package/src/cli/sidecar-pure-helpers.test.mjs

@@ -0,0 +1,168 @@
+// Thin TypeScript-layer unit tests for the PURE helpers in workflow-sidecar (ops#22).
+//
+// Until now the ~1,924 assertions covering this module were all black-box bash that
+// drove the CLI. These tests exercise the pure, side-effect-free helpers directly
+// against the built JS — fast, deterministic, and isolating logic from fs/CLI. They
+// complement (do not replace) the bash evals.
+//
+// Run: `npm run test:unit` (builds first). Requires `npm run build` output under build/.
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  buildClaimExplanation as buildClaimExplanationReexport,
+  deriveGateCalibration,
+  gateAdvisoryFix,
+  buildGateInquiryRecords,
+  validateEvidenceRef,
+  normalizeEvidenceRefs,
+  normalizeCheck,
+} from "../../build/src/cli/workflow-sidecar.js";
+import { buildClaimExplanation } from "../../build/src/cli/sidecar-claim-explain.js";
+
+// ── buildClaimExplanation (extracted pure projection) ────────────────────────
+
+test("buildClaimExplanation: re-export from workflow-sidecar === the extracted module", () => {
+  assert.equal(buildClaimExplanationReexport, buildClaimExplanation);
+});
+
+test("buildClaimExplanation: unknown claim id returns found:false sentinel", () => {
+  const out = buildClaimExplanation({ claims: [] }, { claims: [] }, "missing");
+  assert.equal(out.found, false);
+  assert.equal(out.status, "unknown");
+  assert.deepEqual(out.evidence, []);
+  assert.equal(out.policy, null);
+});
+
+test("buildClaimExplanation: projects status, policy, and evidence for a found claim", () => {
+  const report = {
+    claims: [{ id: "c1", status: "verified", value: "pass", claimType: "workflow.check" }],
+    transparencyGaps: [{ claimId: "c1", reason: "x" }, { claimId: "other" }],
+    changeRecords: [],
+  };
+  const bundle = {
+    claims: [{ id: "c1", verificationPolicyId: "p1", value: "pass", claimType: "workflow.check" }],
+    policies: [{ id: "p1", requiredEvidence: ["test"], acceptanceCriteria: ["AC1"], reviewAuthority: "owner" }],
+    evidence: [{ claimId: "c1", evidenceType: "command", execution: { runner: "npm test", label: "npm test", exitCode: 0 } }],
+  };
+  const out = buildClaimExplanation(report, bundle, "c1");
+  assert.equal(out.found, true);
+  assert.equal(out.status, "verified");
+  assert.equal(out.policy.id, "p1");
+  assert.deepEqual(out.policy.requiredEvidence, ["test"]);
+  assert.equal(out.evidence.length, 1);
+  assert.equal(out.evidence[0].passing, true);        // exitCode 0 → not error → passing
+  assert.equal(out.evidence[0].execution.exitCode, 0);
+  assert.equal(out.why.transparencyGaps.length, 1);   // only the c1 gap, not "other"
+});
+
+// ── deriveGateCalibration (pure mapping) ─────────────────────────────────────
+
+test("deriveGateCalibration: maps outcome/status/blocked to a calibration verdict", () => {
+  assert.equal(deriveGateCalibration("unsupported", undefined, true), "missed_block");
+  assert.equal(deriveGateCalibration("matched", "disputed", true), "correct");
+  assert.equal(deriveGateCalibration("matched", "rejected", true), "correct");
+  assert.equal(deriveGateCalibration("matched", "verified", true), "false_block");
+  assert.equal(deriveGateCalibration("matched", "stale", true), "false_block"); // blocked w/o solid evidence
+  assert.equal(deriveGateCalibration("matched", "stale", false), "missed_block");
+  assert.equal(deriveGateCalibration("matched", "verified", false), "correct");
+  assert.equal(deriveGateCalibration("derived", "proposed", false), "missed_block");
+});
+
+// ── gateAdvisoryFix (pure string composition) ────────────────────────────────
+
+test("gateAdvisoryFix: composes calibration-specific guidance naming the claim", () => {
+  assert.match(gateAdvisoryFix("correct", "c1", "disputed"), /No gate change needed/);
+  assert.match(gateAdvisoryFix("correct", "c1", "disputed"), /`c1`/);
+  assert.match(gateAdvisoryFix("false_block", "c1", "verified"), /Investigate why the gate blocked/);
+  assert.match(gateAdvisoryFix("missed_block", "c1", "stale"), /Refresh the stale claim/);
+  assert.match(gateAdvisoryFix("missed_block", "c1", "absent"), /writes a bundle claim/);
+});
+
+// ── validateEvidenceRef / normalizeEvidenceRefs (pure validators) ────────────
+
+test("validateEvidenceRef: accepts a well-formed source ref", () => {
+  const ref = { kind: "source", file: "a.ts", line_start: 1, line_end: 2, excerpt: "x" };
+  assert.deepEqual(validateEvidenceRef({ ...ref }, "refs"), ref);
+});
+
+test("validateEvidenceRef: rejects bad kind, unsupported field, and incomplete source ref", () => {
+  assert.throws(() => validateEvidenceRef({ kind: "nope" }, "refs"), /kind must be one of/);
+  assert.throws(() => validateEvidenceRef({ kind: "command", bogus: 1, summary: "s" }, "refs"), /unsupported field/);
+  assert.throws(() => validateEvidenceRef({ kind: "source", file: "a.ts" }, "refs"), /source refs require/);
+});
+
+test("normalizeEvidenceRefs: rejects non-arrays and legacy string refs; passes valid arrays", () => {
+  assert.throws(() => normalizeEvidenceRefs("nope", "refs"), /must be an array/);
+  assert.throws(() => normalizeEvidenceRefs(["legacy"], "refs"), /legacy string refs are not supported/);
+  const ok = normalizeEvidenceRefs([{ kind: "command", summary: "ran tests" }], "refs");
+  assert.equal(ok.length, 1);
+  assert.equal(ok[0].kind, "command");
+});
+
+// ── normalizeCheck (pure path: no surface_trust_refs) ────────────────────────
+
+test("normalizeCheck: validates required fields, kind, and status", () => {
+  assert.throws(() => normalizeCheck({ id: "x" }), /requires id, kind, status/);
+  assert.throws(() => normalizeCheck({ id: "x", kind: "bogus", status: "pass", summary: "s" }), /kind must be one of/);
+  assert.throws(() => normalizeCheck({ id: "x", kind: "test", status: "bogus", summary: "s" }), /status must be one of/);
+  const ok = normalizeCheck({ id: "x", kind: "test", status: "pass", summary: "ran" });
+  assert.equal(ok.kind, "test");
+  assert.equal(ok.status, "pass");
+});
+
+// ── buildGateInquiryRecords (pure orchestration, fake Surface injected) ───────
+
+test("buildGateInquiryRecords: resolves each claim through the injected Surface and tags calibration", () => {
+  const fakeSurface = {
+    resolveInquiry: (_bundle, inquiry, _opts) => ({
+      id: inquiry.id,
+      inquiry,
+      outcome: "matched",
+      resolutionPath: { claimIds: [inquiry.metadata.claimId] },
+      inputSnapshot: {},
+      statusFunctionVersion: "test",
+      resolvedAt: "2026-01-01T00:00:00Z",
+      answer: { status: "disputed" },
+    }),
+  };
+  const bundle = {
+    schemaVersion: 2,
+    source: "s",
+    claims: [{ id: "c1", subjectType: "workflow-check", subjectId: "slug/AC1", fieldOrBehavior: "AC1", status: "disputed" }],
+    evidence: [], events: [], policies: [],
+  };
+  const records = buildGateInquiryRecords(
+    bundle,
+    { blocked: true, hash: "h", count: 1 },
+    "slug",
+    [],
+    fakeSurface,
+    new Date("2026-01-01T00:00:00Z"),
+  );
+  assert.equal(records.length, 1);
+  assert.equal(records[0].outcome, "matched");
+  // blocked + disputed → "correct" calibration in answer.value
+  assert.equal(records[0].answer.value.calibration, "correct");
+  assert.equal(records[0].answer.value.gateFired, true);
+  assert.equal(records[0].answer.value.sessionSlug, "slug");
+});
+
+test("buildGateInquiryRecords: emits a single missed_block record for an empty bundle", () => {
+  const fakeSurface = {
+    resolveInquiry: (_bundle, inquiry, _opts) => ({
+      id: inquiry.id,
+      inquiry,
+      outcome: "unsupported",
+      resolutionPath: { claimIds: [] },
+      inputSnapshot: {},
+      statusFunctionVersion: "test",
+      resolvedAt: "2026-01-01T00:00:00Z",
+      answer: { status: "unknown" },
+    }),
+  };
+  const bundle = { schemaVersion: 2, source: "s", claims: [], evidence: [], events: [], policies: [] };
+  const records = buildGateInquiryRecords(bundle, { blocked: false, hash: null, count: 0 }, "slug", [], fakeSurface, new Date("2026-01-01T00:00:00Z"));
+  assert.equal(records.length, 1);
+  assert.equal(records[0].answer.value.calibration, "missed_block");
+});

package/src/cli/telemetry-doctor.ts

@@ -3,6 +3,7 @@ import * as http from "node:http";
 import * as https from "node:https";
 import * as path from "node:path";
 import { parseArgs, flagBool, flagString } from "../lib/args.js";
+import { telemetryDataDir as defaultTelemetryDataDir } from "../lib/local-artifact-root.js";
 
 type Config = Record<string, string>;
 
@@ -82,10 +83,7 @@ function channelConfigValue(config: Config, channel: string, key: string, fallba
 
 function telemetryDataDir(dest: string): string {
   const configured = process.env.TELEMETRY_DATA_DIR;
-  // Must mirror scripts/telemetry/lib/config.sh: the sink lives INSIDE the
-  // workspace at <dest>/.telemetry. The previous "../.telemetry" duplicated
-  // the parent-escape bug fixed in config.sh on 2026-06-11.
-  return configured ? path.resolve(dest, configured) : path.resolve(dest, ".telemetry");
+  return configured ? path.resolve(dest, configured) : defaultTelemetryDataDir(dest);
 }
 
 function deriveConsoleEndpoint(consoleUrl: string, explicitEndpoint: string): string {