@kontourai/flow-agents 2.1.1 → 2.3.0

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 {

package/src/cli/usage-feedback.ts

@@ -3,11 +3,13 @@ import { fileURLToPath } from "node:url";
 import * as os from "node:os";
 import * as path from "node:path";
 import { parseArgs, flagBool, flagList, flagString } from "../lib/args.js";
+import { defaultArtifactRootForRead, defaultTelemetryDirForRead, defaultTelemetryDirsForRead, telemetryDataDir, flowAgentsArtifactRoot, legacyFlowAgentsArtifactRoot } from "../lib/local-artifact-root.js";
 
 const VALID_RESULTS = new Set(["success", "partial", "failure", "not_verified"]);
 
 function telemetryDir(flags: Record<string, string | boolean | string[]>): string {
-  return path.resolve(flagString(flags, "telemetry-dir", process.env.TELEMETRY_DATA_DIR ?? ".telemetry") ?? ".telemetry");
+  const explicit = flagString(flags, "telemetry-dir") ?? process.env.TELEMETRY_DATA_DIR;
+  return explicit ? path.resolve(explicit) : telemetryDataDir();
 }
 
 function ensureSafeDir(dir: string): void {
@@ -110,7 +112,8 @@ function normalize(input: Record<string, unknown>[], runtime: string, flags: Rec
 function importTelemetry(argv: string[], defaultRuntime?: string): number {
   const { flags } = parseArgs(argv);
   const runtime = defaultRuntime ?? flagString(flags, "runtime", "codex") ?? "codex";
-  const input = flagString(flags, "input-full-jsonl") ?? path.join(flagString(flags, "input-telemetry-dir") ?? "", "full.jsonl");
+  const explicitInputDir = flagString(flags, "input-telemetry-dir");
+  const input = flagString(flags, "input-full-jsonl") ?? path.join(explicitInputDir ? path.resolve(explicitInputDir) : defaultTelemetryDirForRead(), "full.jsonl");
   if (!input || !fs.existsSync(input)) throw new Error(`input telemetry file does not exist: ${input}`);
   const dir = telemetryDir(flags);
   ensureSafeDir(dir);
@@ -143,7 +146,7 @@ function syncArtifacts(argv: string[]): number {
   const dir = telemetryDir(flags);
   ensureSafeDir(dir);
   const artifacts = flagList(flags, "artifact-dir");
-  const records = (artifacts.length ? artifacts : [".flow-agents"]).flatMap((item) => fs.existsSync(item) ? artifactOutcomes(item, flags) : []);
+  const records = (artifacts.length ? artifacts : [flowAgentsArtifactRoot(), legacyFlowAgentsArtifactRoot()]).flatMap((item) => fs.existsSync(item) ? artifactOutcomes(item, flags) : []);
   writeJsonlUpsert(path.join(dir, "outcomes.jsonl"), records, "outcome_id");
   if (!flagBool(flags, "quiet")) console.log(`synced ${records.length} artifact outcome(s) to ${path.join(dir, "outcomes.jsonl")}`);
   return 0;
@@ -288,7 +291,9 @@ function markdownReport(data: Record<string, unknown>, groupBy?: string): string
 
 function report(argv: string[]): number {
   const { flags } = parseArgs(argv);
-  const dirs = flagList(flags, "telemetry-dir").map((dir) => path.resolve(dir));
+  const requestedDirs = flagList(flags, "telemetry-dir");
+  const dirs = (requestedDirs.length ? requestedDirs.map((dir) => path.resolve(dir)) : defaultTelemetryDirsForRead()).filter(Boolean);
+  if (dirs.length === 0) dirs.push(telemetryDataDir());
   dirs.forEach(ensureSafeDir);
   const data = reportData(dirs, flagString(flags, "group-by"));
   const format = flagString(flags, "format", "markdown");
@@ -319,7 +324,7 @@ function registerProject(argv: string[]): number {
   ensureSafeDir(globalDir);
   const repoRoot = path.resolve(flagString(flags, "repo-root", ".") ?? ".");
   const name = flagString(flags, "name", path.basename(repoRoot)) ?? path.basename(repoRoot);
-  const record = { name, repo_root: repoRoot, artifact_dir: path.join(repoRoot, ".flow-agents"), input_telemetry_dir: path.join(repoRoot, ".telemetry"), runtime: flagString(flags, "runtime", "codex"), repo: flagString(flags, "repo", name), agent: flagString(flags, "agent"), profile_id: flagString(flags, "profile-id"), prompt_id: flagString(flags, "prompt-id"), prompt_variant: flagString(flags, "prompt-variant"), skill_ids: flagList(flags, "skill-id"), skill_variant: flagString(flags, "skill-variant") };
+  const record = { name, repo_root: repoRoot, artifact_dir: defaultArtifactRootForRead(repoRoot), input_telemetry_dir: defaultTelemetryDirForRead(repoRoot), runtime: flagString(flags, "runtime", "codex"), repo: flagString(flags, "repo", name), agent: flagString(flags, "agent"), profile_id: flagString(flags, "profile-id"), prompt_id: flagString(flags, "prompt-id"), prompt_variant: flagString(flags, "prompt-variant"), skill_ids: flagList(flags, "skill-id"), skill_variant: flagString(flags, "skill-variant") };
   const registryFile = path.join(globalDir, "projects.json");
   const existing = fs.existsSync(registryFile) ? JSON.parse(fs.readFileSync(registryFile, "utf8")) : { projects: [] };
   const projects = Array.isArray(existing) ? existing : Array.isArray(existing.projects) ? existing.projects : [];
@@ -342,7 +347,9 @@ function syncProject(project: Record<string, unknown>, globalDir: string): void
   const name = String(project.name ?? project.repo ?? "project").replace(/[^a-zA-Z0-9_.-]+/g, "-") || "project";
   const store = path.join(globalDir, "projects", name);
   ensureSafeDir(store);
-  const artifactDir = String(project.artifact_dir ?? path.join(String(project.repo_root), ".flow-agents"));
+  const repoRoot = String(project.repo_root ?? process.cwd());
+  const configuredArtifactDir = typeof project.artifact_dir === "string" ? project.artifact_dir : "";
+  const artifactDir = configuredArtifactDir && fs.existsSync(configuredArtifactDir) ? configuredArtifactDir : defaultArtifactRootForRead(repoRoot);
   const flags: Record<string, string | boolean | string[]> = {
     "repo": String(project.repo ?? name),
     "runtime": String(project.runtime ?? "codex"),
@@ -361,9 +368,9 @@ function syncProject(project: Record<string, unknown>, globalDir: string): void
 function discoverProjects(root: string): Record<string, unknown>[] {
   if (!fs.existsSync(root)) return [];
   const candidates = [root, ...fs.readdirSync(root).map((name) => path.join(root, name))];
-  return candidates.filter((candidate) => fs.existsSync(path.join(candidate, ".flow-agents"))).map((repoRoot) => {
+  return candidates.filter((candidate) => fs.existsSync(flowAgentsArtifactRoot(candidate)) || fs.existsSync(legacyFlowAgentsArtifactRoot(candidate))).map((repoRoot) => {
     const name = path.basename(repoRoot);
-    return { name, repo: name, repo_root: repoRoot, artifact_dir: path.join(repoRoot, ".flow-agents"), input_telemetry_dir: path.join(repoRoot, ".telemetry"), runtime: "codex", skill_ids: [] };
+    return { name, repo: name, repo_root: repoRoot, artifact_dir: defaultArtifactRootForRead(repoRoot), input_telemetry_dir: defaultTelemetryDirForRead(repoRoot), runtime: "codex", skill_ids: [] };
   });
 }
 

package/src/cli/workflow-artifact-cleanup-audit.ts

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import { fileURLToPath } from "node:url";
 import * as path from "node:path";
 import { flagBool, flagString, parseArgs } from "../lib/args.js";
+import { defaultArtifactRootForRead } from "../lib/local-artifact-root.js";
 
 type Classification =
   | "active_wip"
@@ -49,7 +50,7 @@ function printHelp(): void {
   console.log("Read-only dry-run audit for local workflow artifact directories.");
   console.log("");
   console.log("Options:");
-  console.log("  --artifact-root <path>  Local artifact root to scan (default: .flow-agents)");
+  console.log("  --artifact-root <path>  Local artifact root to scan (default: .kontourai/flow-agents, with .flow-agents read fallback)");
   console.log("  --json                  Print stable JSON buckets instead of text");
   console.log("  --help                  Show this help");
   console.log("");
@@ -269,7 +270,8 @@ export function main(argv = process.argv.slice(2)): number {
   }
   let result: AuditResult;
   try {
-    result = audit(flagString(args.flags, "artifact-root", ".flow-agents") ?? ".flow-agents");
+    const root = flagString(args.flags, "artifact-root") ? path.resolve(flagString(args.flags, "artifact-root")!) : defaultArtifactRootForRead();
+    result = audit(root);
   } catch (error) {
     console.error(`workflow-artifact-cleanup-audit: ${error instanceof Error ? error.message : String(error)}`);
     return 1;

package/src/cli/workflow-sidecar.ts

@@ -7,6 +7,7 @@ import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 // ADR 0016 Abstraction A: shared FlowDefinition resolver (P-a)
 import { resolveActiveFlowStep, resolveFlowFilePath, resolvePhaseMap, resolveRouteBackPolicy, type ActiveFlowStep } from "../lib/flow-resolver.js";
+import { defaultArtifactRootForRead, flowAgentsArtifactRoot } from "../lib/local-artifact-root.js";
 
 type AnyObj = Record<string, any>;
 
@@ -652,7 +653,7 @@ function isUnderDir(dir: string, root: string): boolean {
 function explicitArtifactRoot(p: ReturnType<typeof parseArgs>): string {
   const explicit = opt(p, "artifact-dir");
   const configuredRoot = opt(p, "artifact-root");
-  if (!explicit) return path.resolve(configuredRoot || ".flow-agents");
+  if (!explicit) return configuredRoot ? path.resolve(configuredRoot) : flowAgentsArtifactRoot();
   const dir = path.resolve(explicit);
   if (!fs.existsSync(dir)) die(`artifact directory does not exist: ${dir}`);
   if (fs.lstatSync(dir).isSymbolicLink()) die(`artifact directory must not be a symlink: ${dir}`);
@@ -879,7 +880,7 @@ function initSidecars(dir: string, slug: string, sourceRequest: string, summary:
 }
 
 function ensureSession(p: ReturnType<typeof parseArgs>): number {
-  const root = path.resolve(opt(p, "artifact-root", ".flow-agents"));
+  const root = opt(p, "artifact-root") ? path.resolve(opt(p, "artifact-root")) : flowAgentsArtifactRoot();
   const slug = opt(p, "task-slug") || (opt(p, "work-item") ? workItemSlug(opt(p, "work-item")) : die("--task-slug is required (or pass --work-item to derive it)"));
   const dir = sessionDirFor(root, slug);
   fs.mkdirSync(dir, { recursive: true });
@@ -912,7 +913,7 @@ function ensureSession(p: ReturnType<typeof parseArgs>): number {
 }
 
 function current(p: ReturnType<typeof parseArgs>): number {
-  const root = path.resolve(opt(p, "artifact-root", ".flow-agents"));
+  const root = opt(p, "artifact-root") ? path.resolve(opt(p, "artifact-root")) : defaultArtifactRootForRead();
   const dir = currentDir(root);
   if (!dir) die("no current workflow session is recorded");
   const format = opt(p, "format", "path");
@@ -1829,7 +1830,7 @@ function assertExistingLearningValid(dir: string): void {
   }
 }
 async function dogfoodPass(p: ReturnType<typeof parseArgs>): Promise<number> {
-  const root = path.resolve(opt(p, "artifact-root", ".flow-agents"));
+  const root = opt(p, "artifact-root") ? path.resolve(opt(p, "artifact-root")) : defaultArtifactRootForRead();
   const dir = path.resolve(opt(p, "artifact-dir") || currentDir(root) || "");
   requireArtifactDirUnderRoot(dir, root);
   assertExistingLearningValid(dir);
@@ -2265,7 +2266,7 @@ function loadSurfacePanelJs(): string {
 }
 
 async function renderTrustPanel(p: ReturnType<typeof parseArgs>): Promise<number> {
-  const root = path.resolve(opt(p, "artifact-root", ".flow-agents"));
+  const root = opt(p, "artifact-root") ? path.resolve(opt(p, "artifact-root")) : defaultArtifactRootForRead();
   const dir = p.positional[0] ? artifactDirFrom(p.positional[0]) : currentDir(root);
   if (!dir) die("render-trust-panel requires a workflow dir or a recorded current session");
   let bundle: AnyObj | null = null;
@@ -2431,7 +2432,7 @@ function livenessLifecycle(taskDir: string, slug: string, kind: "claim" | "heart
 }
 
 async function liveness(p: ReturnType<typeof parseArgs>): Promise<number> {
-  const root = path.resolve(opt(p, "artifact-root", ".flow-agents"));
+  const root = opt(p, "artifact-root") ? path.resolve(opt(p, "artifact-root")) : flowAgentsArtifactRoot();
   const action = p.positional[0] || "";
   const subjectId = p.positional[1] || "";
   const actor = opt(p, "actor", process.env.FLOW_AGENTS_ACTOR || "unknown");
@@ -2481,130 +2482,13 @@ async function liveness(p: ReturnType<typeof parseArgs>): Promise<number> {
 // ─────────────────────────────────────────────────────────────────────────────
 
 // ─── Claim Lookup — pure helper (promotable to Surface #171) ─────────────────
-// buildClaimExplanation is a PURE function: report + bundle + id in, structured
-// explanation out. No fs, no CLI, no .flow-agents paths. Zero flow-agents
-// specifics inside it — it can be lifted to Surface unchanged (issue #171).
-
-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,
-    },
-  };
-}
+// buildClaimExplanation + its types are extracted to ./sidecar-claim-explain.ts
+// (ops#22): a PURE projection (report + bundle + id in, structured explanation out)
+// with no fs/CLI/shared state, unit-tested in isolation. Re-exported here so the
+// library facade (src/index.ts) and the IO `claimLookup` handler below are unchanged.
+export { buildClaimExplanation } from "./sidecar-claim-explain.js";
+export type { ClaimEvidenceItem, ClaimExplanation } from "./sidecar-claim-explain.js";
+import { buildClaimExplanation } from "./sidecar-claim-explain.js";
 
 /**
  * claim <id> <dir>
@@ -2768,7 +2652,9 @@ Available claim ids:
 async function main(): Promise<number> {
   const p = parseArgs(process.argv.slice(2));
   if (!p.command) die("workflow-sidecar command is required");
-  const lockRoot = ["ensure-session", "current", "dogfood-pass", "liveness"].includes(p.command) ? path.resolve(opt(p, "artifact-root", ".flow-agents")) : p.command === "record-agent-event" ? explicitArtifactRoot(p) : p.command === "claim" ? (p.positional[1] ? path.resolve(p.positional[1]) : "") : p.positional[0] ? artifactDirFrom(p.positional[0]) : "";
+  const lockRoot = ["ensure-session", "current", "dogfood-pass", "liveness"].includes(p.command)
+    ? (opt(p, "artifact-root") ? path.resolve(opt(p, "artifact-root")) : (p.command === "ensure-session" ? flowAgentsArtifactRoot() : defaultArtifactRootForRead()))
+    : p.command === "record-agent-event" ? explicitArtifactRoot(p) : p.command === "claim" ? (p.positional[1] ? path.resolve(p.positional[1]) : "") : p.positional[0] ? artifactDirFrom(p.positional[0]) : "";
   return withLock(lockRoot, ["ensure-session", "record-agent-event", "dogfood-pass"].includes(p.command), p.command, () => {
     switch (p.command) {
       case "ensure-session": return ensureSession(p);

package/src/index.ts

@@ -16,6 +16,20 @@
 import * as path from "node:path";
 import { loadJson as _loadJson, writeJson as _writeJson } from "./cli/workflow-sidecar.js";
 
+export {
+  defaultArtifactRootForRead,
+  defaultTelemetryDirForRead,
+  defaultTelemetryDirsForRead,
+  firstExistingPath,
+  flowAgentsArtifactRoot,
+  KONTOURAI_DIR,
+  legacyFlowAgentsArtifactRoot,
+  LEGACY_FLOW_AGENTS_DIR,
+  legacyTelemetryDataDir,
+  LEGACY_TELEMETRY_DIR,
+  telemetryDataDir,
+} from "./lib/local-artifact-root.js";
+
 export {
   // Trust-bundle (Hachure) validation — the same validator the writer uses.
   validateTrustBundle,

package/src/lib/local-artifact-root.ts

@@ -0,0 +1,39 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export const KONTOURAI_DIR = ".kontourai";
+export const LEGACY_FLOW_AGENTS_DIR = ".flow-agents";
+export const LEGACY_TELEMETRY_DIR = ".telemetry";
+
+export function flowAgentsArtifactRoot(cwd = process.cwd()): string {
+  return path.resolve(cwd, KONTOURAI_DIR, "flow-agents");
+}
+
+export function legacyFlowAgentsArtifactRoot(cwd = process.cwd()): string {
+  return path.resolve(cwd, LEGACY_FLOW_AGENTS_DIR);
+}
+
+export function telemetryDataDir(cwd = process.cwd()): string {
+  return path.resolve(cwd, KONTOURAI_DIR, "telemetry");
+}
+
+export function legacyTelemetryDataDir(cwd = process.cwd()): string {
+  return path.resolve(cwd, LEGACY_TELEMETRY_DIR);
+}
+
+export function firstExistingPath(candidates: string[]): string {
+  return candidates.find((candidate) => fs.existsSync(candidate)) ?? candidates[0];
+}
+
+export function defaultArtifactRootForRead(cwd = process.cwd()): string {
+  return firstExistingPath([flowAgentsArtifactRoot(cwd), legacyFlowAgentsArtifactRoot(cwd)]);
+}
+
+export function defaultTelemetryDirForRead(cwd = process.cwd()): string {
+  return firstExistingPath([telemetryDataDir(cwd), legacyTelemetryDataDir(cwd)]);
+}
+
+export function defaultTelemetryDirsForRead(cwd = process.cwd()): string[] {
+  const dirs = [telemetryDataDir(cwd), legacyTelemetryDataDir(cwd)];
+  return dirs.filter((dir, index) => dirs.indexOf(dir) === index && fs.existsSync(dir));
+}

package/src/tools/validate-source-tree.ts

@@ -74,6 +74,7 @@ const hookFilePolicies = new Map<string, { category: string; requiredNeedles: st
   ["scripts/hooks/lib/audit-transport.sh", { category: "shared hook library", requiredNeedles: ["audit_emit"] }],
   ["scripts/hooks/lib/hook-flags.js", { category: "shared hook library", requiredNeedles: ["isHookEnabled"] }],
   ["scripts/hooks/lib/liveness-read.js", { category: "shared hook library", requiredNeedles: ["freshHolders", "readLivenessEvents"] }],
+  ["scripts/hooks/lib/local-artifact-paths.js", { category: "shared hook library", requiredNeedles: ["flowAgentsArtifactRoot", "defaultArtifactRootForRead"] }],
   ["scripts/hooks/lib/patterns.sh", { category: "shared hook library", requiredNeedles: ["_detect_secrets"] }],
   ["scripts/hooks/lib/resolve-formatter.js", { category: "shared hook library", requiredNeedles: ["resolveFormatter"] }],
 ]);