@kontourai/flow-agents 3.12.1 → 4.1.0

package/src/tools/generate-capability-matrix.ts

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+/**
+ * generate-capability-matrix.ts (#620) — the single-source generator (D2).
+ *
+ * ONE render() pass over RUNTIME_CAPABILITY_DECLARATIONS produces BOTH:
+ *   (a) the committed markdown matrix (docs/specs/harness-capability-matrix.md),
+ *       regenerated from the declarations with 7 adapter columns and the ✓/
+ *       partial/✗ vocabulary derived from each capability's union status; and
+ *   (b) a build-only JSON projection (build/generated/capability-declarations.json,
+ *       NEVER committed — build/ is gitignored) that the economics-record emitter
+ *       and hooks read, keyed on canonical runtime id.
+ *
+ * Because both artifacts come from the same object in one pass, markdown/JSON
+ * divergence is impossible by construction. `main(--check)` regenerates the
+ * markdown in-memory and diffs the committed file, exiting nonzero on drift —
+ * mirroring src/tools/generate-context-map.ts's render()/main(--check) precedent.
+ *
+ * Modes:
+ *   (default)     write BOTH the markdown doc and the build-only JSON.
+ *   --check       diff the committed markdown vs a fresh render; nonzero on drift.
+ *   --json-only   write ONLY the build-only JSON (used by the build pipeline so
+ *                 the JSON always exists post-build without mutating the doc).
+ */
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { exists, markdownTable, readText, rel, root, writeText } from "./common.js";
+import {
+  CAPABILITIES,
+  RUNTIME_ADAPTER_IDS,
+  RUNTIME_CAPABILITY_DECLARATIONS,
+  type Capability,
+  type CapabilityStatus,
+  type RuntimeAdapterId,
+} from "../lib/capability-declarations.js";
+
+const matrixDocPath = path.join(root, "docs/specs/harness-capability-matrix.md");
+const generatedJsonPath = path.join(root, "build/generated/capability-declarations.json");
+
+/** ✓ / partial / ✗ glyph for a status (matches the doc's existing 3-state vocabulary). */
+function glyph(status: CapabilityStatus): string {
+  switch (status.status) {
+    case "supported":
+      return "✓";
+    case "partial":
+      return "partial";
+    case "unsupported":
+      return "✗";
+  }
+}
+
+/** The per-cell note/reason for a non-supported status, else "". */
+function detail(status: CapabilityStatus): string {
+  if (status.status === "partial") return status.note;
+  if (status.status === "unsupported") return status.reason;
+  return "";
+}
+
+/** The build-only JSON object: canonical-runtime-id → capability → status. */
+export function buildDeclarationJson(): Record<string, Record<string, CapabilityStatus>> {
+  const out: Record<string, Record<string, CapabilityStatus>> = {};
+  for (const runtime of RUNTIME_ADAPTER_IDS) {
+    const caps: Record<string, CapabilityStatus> = {};
+    for (const capability of CAPABILITIES) {
+      caps[capability] = RUNTIME_CAPABILITY_DECLARATIONS[runtime].capabilities[capability];
+    }
+    out[runtime] = caps;
+  }
+  return out;
+}
+
+/** Render the full committed matrix markdown from the declarations (deterministic). */
+export function renderMatrixMarkdown(): string {
+  const headers = ["Capability", ...RUNTIME_ADAPTER_IDS.map((id) => `\`${id}\``)];
+  const rows: string[][] = CAPABILITIES.map((capability: Capability) => [
+    `\`${capability}\``,
+    ...RUNTIME_ADAPTER_IDS.map((runtime: RuntimeAdapterId) => glyph(RUNTIME_CAPABILITY_DECLARATIONS[runtime].capabilities[capability])),
+  ]);
+
+  // Per-cell notes/reasons for every non-supported cell, in stable order
+  // (capability outer, adapter inner) so partial/unsupported justifications are
+  // preserved in the generated doc rather than collapsed to a bare glyph.
+  const noteLines: string[] = [];
+  for (const capability of CAPABILITIES) {
+    for (const runtime of RUNTIME_ADAPTER_IDS) {
+      const status = RUNTIME_CAPABILITY_DECLARATIONS[runtime].capabilities[capability];
+      const text = detail(status);
+      if (text) noteLines.push(`- \`${capability}\` · \`${runtime}\` (${status.status}): ${text}`);
+    }
+  }
+
+  return [
+    "# Harness-capability matrix",
+    "",
+    "**The signals a feature can rely on depend on which runtime/harness the kit is hooked into. State the",
+    "coverage; never assume it, never fabricate the gap.**",
+    "",
+    "> Generated by `npm run capability-matrix` from `src/lib/capability-declarations.ts` — the single",
+    "> source of truth. Do NOT edit this file by hand; change the declarations and regenerate. CI fails on",
+    "> drift (`npm run capability-matrix -- --check`).",
+    "",
+    "This is a cross-cutting contract: any feature whose data comes from telemetry (economics, delegation",
+    "efficiency, liveness, learning) must declare which signals it needs, which *class* each falls in, and",
+    "how it degrades when the current runtime does not expose one. A missing signal is rendered as",
+    "**unavailable**, distinct from a real zero — so a consumer never reads \"harness-blind\" as \"measured 0.\"",
+    "",
+    "## The load-bearing distinction: orchestrator-observable vs sub-agent-internal",
+    "",
+    "Not all \"we can't see inside the sub-agent\" gaps are equal. Two classes:",
+    "",
+    "- **Orchestrator-observable** — what our hooks see the *main agent* (the orchestrator) do. The",
+    "  orchestrator knows the prompt it dispatched, how many times it re-dispatched/re-prompted the same",
+    "  sub-agent, its own iteration/route-back count, and when it superseded or corrected a result. Our",
+    "  telemetry observes the orchestrator directly, so **these hold on any runtime that runs our hooks —",
+    "  no sub-agent introspection required.** This is where per-delegation *outcome* comes from.",
+    "- **Sub-agent-internal** — signals that live inside the sub-agent's own turn: its token usage, its",
+    "  internal reasoning, a verdict it computed but never surfaced to the orchestrator. Capturing these",
+    "  requires the harness to expose per-sub-agent instrumentation. **Most harnesses do not today**, so",
+    "  features that need them (e.g. per-delegation *cost*) must declare the signal unavailable and fall",
+    "  back to a coarser, honest proxy.",
+    "",
+    "The practical upshot for #415: we can attribute **outcome** (accepted / rework / diverged / failed) from",
+    "orchestrator-observable behavior even though we cannot attribute **cost** per delegation — because",
+    "tokens are sub-agent-internal and outcome is not.",
+    "",
+    "## The `signals` block",
+    "",
+    "Every `kontour.console.economics` record carries a `signals` object declaring what the emitting runtime",
+    "exposed:",
+    "",
+    ...markdownTable(
+      ["Field", "Class", "Meaning"],
+      [
+        ["`runtime`", "—", "the runtime that produced the record (`claude-code`, `kiro-cli`, `codex`, …)"],
+        ["`per_delegation_tokens`", "sub-agent-internal", "`true` iff the runtime isolates per-sub-agent token usage. **`false` on every runtime today** → per-delegation cost is unavailable; the console attributes cost at `(role, model)` granularity via `cost.by_model` instead. Derived from this matrix's `per_delegation_tokens` capability declaration, not a hardcoded literal."],
+        ["`per_delegation_outcome`", "orchestrator-observable", "coverage of the outcome signal on this run: `full` (every delegation resolved to a real outcome), `partial` (some), `none` (delegations exist but none had a verdict/escalation/re-dispatch), `n/a` (no delegations observed)."],
+      ],
+    ),
+    "",
+    "Consumers (console panels, `learning-review`) MUST read `signals` before rendering a metric: if the",
+    "signal a metric needs is unavailable, show \"not measurable on this harness,\" not a misleading number.",
+    "",
+    "## Per-runtime capability coverage (generated, honest snapshot)",
+    "",
+    "`✓` exposed · `partial` best-effort/orchestrator-derived · `✗` not exposed. This table is generated",
+    "from `src/lib/capability-declarations.ts`; update the declarations there as runtimes add",
+    "instrumentation — it is the single source of truth the `signals` values are stamped from. The",
+    "`kiro-cli` runtime value normalizes to the canonical `kiro` column before lookup.",
+    "",
+    ...markdownTable(headers, rows),
+    "",
+    "### Declared notes and reasons",
+    "",
+    "Every `partial` / `✗` cell above, with its declared justification:",
+    "",
+    ...noteLines,
+    "",
+    "## The doctrine (applies to any telemetry-dependent feature)",
+    "",
+    "1. **Classify each signal** as run-level, orchestrator-observable, or sub-agent-internal. Prefer",
+    "   orchestrator-observable derivations — they are the most portable across harnesses.",
+    "2. **Declare coverage in-band** (a `signals`-style block) so a consumer can distinguish real-zero from",
+    "   harness-blind at read time.",
+    "3. **Degrade to an explicit `unavailable`**, never to a fabricated value. A cost you cannot attribute",
+    "   is not `$0`; an outcome you cannot observe is not `accepted`.",
+    "4. **Fall back to the coarsest honest proxy** when the fine signal is missing (per-delegation cost →",
+    "   `(role, model)` via `by_model`), and label the proxy as such.",
+    "5. **Keep these declarations current.** When a harness starts exposing a signal, flip the declaration in",
+    "   `src/lib/capability-declarations.ts` and regenerate — the `signals` stamp follows and the feature",
+    "   \"lights up\" without a schema change.",
+    "",
+  ].join("\n");
+}
+
+/** Write the build-only JSON projection (build/ is gitignored — never committed). */
+function writeGeneratedJson(): void {
+  writeText(generatedJsonPath, `${JSON.stringify(buildDeclarationJson(), null, 2)}\n`);
+}
+
+export function main(argv = process.argv.slice(2)): number {
+  const check = argv.includes("--check");
+  const jsonOnly = argv.includes("--json-only");
+  const markdown = renderMatrixMarkdown();
+
+  if (check) {
+    const current = exists(matrixDocPath) ? readText(matrixDocPath) : "";
+    if (current !== markdown) {
+      console.error(`${rel(matrixDocPath)} is stale; run npm run capability-matrix`);
+      return 1;
+    }
+    console.error(`${rel(matrixDocPath)} is current.`);
+    return 0;
+  }
+
+  writeGeneratedJson();
+  if (jsonOnly) {
+    // Progress/diagnostics go to stderr so stdout stays data-only: this runs inside `npm run build`,
+    // and any downstream `npm run build --silent && node … --json` command would otherwise inherit
+    // this line on stdout and corrupt the JSON its consumer parses.
+    console.error(`Wrote ${rel(generatedJsonPath)}`);
+    return 0;
+  }
+
+  writeText(matrixDocPath, markdown);
+  console.error(`Wrote ${rel(matrixDocPath)}`);
+  console.error(`Wrote ${rel(generatedJsonPath)}`);
+  return 0;
+}
+
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try { return fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return fileURLToPath(import.meta.url); } })();
+const _argv1RealPath = (() => { try { return fs.realpathSync(process.argv[1]); } catch { return process.argv[1]; } })();
+if (_selfRealPath === _argv1RealPath) { process.exitCode = main(); }

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

@@ -113,10 +113,14 @@ const fixtureOwnerPolicies = new Map<string, { owners: string[]; classification:
   ["evals/fixtures/kit-conformance-levels", { owners: ["evals/integration/test_kit_conformance_levels.sh"], classification: "K-level conformance and consumer-target derivation fixtures" }],
   ["evals/fixtures/hook-influence", { owners: ["evals/integration/test_hook_influence_cases.sh", "evals/static/test_workflow_skills.sh", "scripts/validate-hook-influence-cases.js"], classification: "hook influence behavioral cases" }],
   ["evals/fixtures/learning-review-proposals", { owners: ["evals/integration/test_learning_review_proposals.sh"], classification: "learning-review kit/gate tuning proposal fixtures (#352): pattern-present (engineered cost-inflation + gate false-block-rate pattern, with sessions/ trust.bundle + gate-review.inquiries.json joins and a hand-computed expected-aggregates.json), balanced (proportional cost/findings movement -> zero proposals), under-threshold (below LR_MIN_WINDOW_SAMPLE), repeat-window (idempotency), and effect-follow-up (later-window effect-fill pass for a ratified proposal)" }],
+  ["evals/fixtures/narrative-sources", { owners: ["evals/integration/test_narrative_source_contract.sh", "evals/integration/test_narrative_runtime_projection.sh", "evals/integration/test_narrative_grounded_envelope.sh", "evals/integration/test_narrative_redaction_failclosed.sh", "evals/integration/test_narrative_trust_isolation.sh"], classification: "narrative source snapshot, offline resolution, integrity, completeness, fail-closed redaction, grounded runtime projection, grounded execution narrative, and trust-isolation fixtures (#613, #617, #618, #619)" }],
+  ["evals/fixtures/narrative-grounding-validator", { owners: ["evals/integration/test_narrative_grounding_validator.sh"], classification: "narrative grounding validator adversarial fixtures (#623)" }],
+  ["evals/fixtures/narrative-prose-renderer", { owners: ["evals/integration/test_narrative_prose_renderer.sh"], classification: "model-assisted prose renderer adversarial fixtures (#614): provenance-subset (unsupported-summary), no-op-loop lack-of-progress wording, and prompt-injection fixtures reused from evals/fixtures/narrative-grounding-validator" }],
+  ["evals/fixtures/narrative-evals", { owners: ["evals/integration/test_narrative_evals.sh"], classification: "grounded narrative faithfulness eval corpus + result-schema package (#612): ten R1 case-class fixtures with frozen-manifest answer keys plus five R3 corruption fixtures whose named eval-check anchors are the scorer-teeth mutation targets" }],
   ["evals/fixtures/pull-work-provider", { owners: ["evals/integration/test_pull_work_provider.sh"], classification: "work item provider normalization fixtures" }],
   ["evals/fixtures/pull-work-wip-shepherding", { owners: ["evals/static/test_workflow_skills.sh"], classification: "WIP shepherding state fixtures" }],
   ["evals/fixtures/surface-trust", { owners: ["evals/integration/test_workflow_sidecar_writer.sh"], classification: "Surface trust evidence fixtures" }],
-  ["evals/fixtures/telemetry", { owners: ["evals/integration/test_usage_cost.sh", "evals/integration/test_telemetry_usage_pipeline.sh", "evals/integration/test_telemetry_tool_usage.sh"], classification: "hermetic Stop-hook usage transcript fixture (#defect-2026-07 telemetry-usage-cost-extraction): a multi-model JSONL transcript with .message.model + .message.usage token blocks proving real token/cost/model extraction end-to-end; also reused by the #568 slice 1 per-tool-call usage-enrichment eval (test_telemetry_tool_usage.sh), which adds usage-transcript-oversized-prefix.jsonl to prove the bounded tail-read" }],
+  ["evals/fixtures/telemetry", { owners: ["evals/integration/test_usage_cost.sh", "evals/integration/test_telemetry_usage_pipeline.sh", "evals/integration/test_telemetry_tool_usage.sh", "evals/integration/test_telemetry_tool_outcome.sh"], classification: "hermetic Stop-hook usage transcript fixture (#defect-2026-07 telemetry-usage-cost-extraction): a multi-model JSONL transcript with .message.model + .message.usage token blocks proving real token/cost/model extraction end-to-end; also reused by the #568 slice 1 per-tool-call usage-enrichment eval (test_telemetry_tool_usage.sh), which adds usage-transcript-oversized-prefix.jsonl to prove the bounded tail-read" }],
   ["evals/fixtures/reconcile-preflight", { owners: ["evals/integration/test_reconcile_preflight.sh"], classification: "#356 reconcile-preflight shape fixtures not already covered by trust-reconcile-exploits (un-superseded disputed critique, standalone disputed session-local claim)" }],
   ["evals/fixtures/trust-reconcile-exploits", { owners: ["evals/integration/test_trust_reconcile_negatives.sh", "evals/integration/test_reconcile_preflight.sh"], classification: "WS8 trust-reconcile anti-gaming exploit fixtures (frozen negative regressions); also reused by the #356 local reconcile-preflight eval (same shapes, no forked copies)" }],
   ["evals/fixtures/trust-reconcile-mixed-bundle", { owners: ["evals/integration/test_trust_reconcile_mixed_bundle.sh", "evals/integration/test_reconcile_preflight.sh"], classification: "WS8 trust-reconcile mixed-evidence end-to-end proof fixture; also reused by the #356 reconcile-preflight eval as its CLEAN-BUNDLE (AC4) case" }],

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

@@ -1,45 +0,0 @@
-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 declare function buildClaimExplanation(report: Record<string, unknown>, bundle: Record<string, unknown>, claimId: string): ClaimExplanation;
-export {};

package/build/src/cli/sidecar-claim-explain.js

@@ -1,87 +0,0 @@
-// 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.
-/**
- * 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, bundle, claimId) {
-    const reportClaims = Array.isArray(report.claims) ? report.claims : [];
-    const reportClaim = reportClaims.find((c) => 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 : [];
-    const bundleClaim = bundleClaims.find((c) => c.id === claimId) ?? reportClaim;
-    const bundlePolicies = Array.isArray(bundle.policies) ? bundle.policies : [];
-    const bundleEvidence = Array.isArray(bundle.evidence) ? bundle.evidence : [];
-    // Governing policy — follow verificationPolicyId into bundle.policies[]
-    const verificationPolicyId = typeof bundleClaim.verificationPolicyId === "string" ? bundleClaim.verificationPolicyId : undefined;
-    const rawPolicy = verificationPolicyId ? bundlePolicies.find((p) => p.id === verificationPolicyId) : undefined;
-    const policy = rawPolicy
-        ? {
-            id: String(rawPolicy.id ?? ""),
-            requiredEvidence: Array.isArray(rawPolicy.requiredEvidence) ? rawPolicy.requiredEvidence : [],
-            requiredMethods: Array.isArray(rawPolicy.requiredMethods) ? rawPolicy.requiredMethods : undefined,
-            acceptanceCriteria: Array.isArray(rawPolicy.acceptanceCriteria) ? rawPolicy.acceptanceCriteria : [],
-            reviewAuthority: String(rawPolicy.reviewAuthority ?? ""),
-        }
-        : null;
-    // Evidence enhancement: pull evidence items for this claim, surface the execution block
-    const claimEvidenceItems = bundleEvidence.filter((ev) => ev && ev.claimId === claimId);
-    const evidence = claimEvidenceItems.map((ev) => {
-        const exec = ev.execution && typeof ev.execution === "object" ? ev.execution : 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 : [];
-    const allChanges = Array.isArray(report.changeRecords) ? report.changeRecords : [];
-    const transparencyGaps = allGaps.filter((g) => g && g.claimId === claimId);
-    const changeRecords = allChanges.filter((c) => 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/dist/base/build/src/cli/sidecar-claim-explain.d.ts

@@ -1,45 +0,0 @@
-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 declare function buildClaimExplanation(report: Record<string, unknown>, bundle: Record<string, unknown>, claimId: string): ClaimExplanation;
-export {};

package/dist/base/build/src/cli/sidecar-claim-explain.js

@@ -1,87 +0,0 @@
-// 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.
-/**
- * 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, bundle, claimId) {
-    const reportClaims = Array.isArray(report.claims) ? report.claims : [];
-    const reportClaim = reportClaims.find((c) => 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 : [];
-    const bundleClaim = bundleClaims.find((c) => c.id === claimId) ?? reportClaim;
-    const bundlePolicies = Array.isArray(bundle.policies) ? bundle.policies : [];
-    const bundleEvidence = Array.isArray(bundle.evidence) ? bundle.evidence : [];
-    // Governing policy — follow verificationPolicyId into bundle.policies[]
-    const verificationPolicyId = typeof bundleClaim.verificationPolicyId === "string" ? bundleClaim.verificationPolicyId : undefined;
-    const rawPolicy = verificationPolicyId ? bundlePolicies.find((p) => p.id === verificationPolicyId) : undefined;
-    const policy = rawPolicy
-        ? {
-            id: String(rawPolicy.id ?? ""),
-            requiredEvidence: Array.isArray(rawPolicy.requiredEvidence) ? rawPolicy.requiredEvidence : [],
-            requiredMethods: Array.isArray(rawPolicy.requiredMethods) ? rawPolicy.requiredMethods : undefined,
-            acceptanceCriteria: Array.isArray(rawPolicy.acceptanceCriteria) ? rawPolicy.acceptanceCriteria : [],
-            reviewAuthority: String(rawPolicy.reviewAuthority ?? ""),
-        }
-        : null;
-    // Evidence enhancement: pull evidence items for this claim, surface the execution block
-    const claimEvidenceItems = bundleEvidence.filter((ev) => ev && ev.claimId === claimId);
-    const evidence = claimEvidenceItems.map((ev) => {
-        const exec = ev.execution && typeof ev.execution === "object" ? ev.execution : 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 : [];
-    const allChanges = Array.isArray(report.changeRecords) ? report.changeRecords : [];
-    const transparencyGaps = allGaps.filter((g) => g && g.claimId === claimId);
-    const changeRecords = allChanges.filter((c) => 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/dist/claude-code/build/src/cli/sidecar-claim-explain.d.ts

@@ -1,45 +0,0 @@
-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 declare function buildClaimExplanation(report: Record<string, unknown>, bundle: Record<string, unknown>, claimId: string): ClaimExplanation;
-export {};

package/dist/claude-code/build/src/cli/sidecar-claim-explain.js

@@ -1,87 +0,0 @@
-// 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.
-/**
- * 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, bundle, claimId) {
-    const reportClaims = Array.isArray(report.claims) ? report.claims : [];
-    const reportClaim = reportClaims.find((c) => 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 : [];
-    const bundleClaim = bundleClaims.find((c) => c.id === claimId) ?? reportClaim;
-    const bundlePolicies = Array.isArray(bundle.policies) ? bundle.policies : [];
-    const bundleEvidence = Array.isArray(bundle.evidence) ? bundle.evidence : [];
-    // Governing policy — follow verificationPolicyId into bundle.policies[]
-    const verificationPolicyId = typeof bundleClaim.verificationPolicyId === "string" ? bundleClaim.verificationPolicyId : undefined;
-    const rawPolicy = verificationPolicyId ? bundlePolicies.find((p) => p.id === verificationPolicyId) : undefined;
-    const policy = rawPolicy
-        ? {
-            id: String(rawPolicy.id ?? ""),
-            requiredEvidence: Array.isArray(rawPolicy.requiredEvidence) ? rawPolicy.requiredEvidence : [],
-            requiredMethods: Array.isArray(rawPolicy.requiredMethods) ? rawPolicy.requiredMethods : undefined,
-            acceptanceCriteria: Array.isArray(rawPolicy.acceptanceCriteria) ? rawPolicy.acceptanceCriteria : [],
-            reviewAuthority: String(rawPolicy.reviewAuthority ?? ""),
-        }
-        : null;
-    // Evidence enhancement: pull evidence items for this claim, surface the execution block
-    const claimEvidenceItems = bundleEvidence.filter((ev) => ev && ev.claimId === claimId);
-    const evidence = claimEvidenceItems.map((ev) => {
-        const exec = ev.execution && typeof ev.execution === "object" ? ev.execution : 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 : [];
-    const allChanges = Array.isArray(report.changeRecords) ? report.changeRecords : [];
-    const transparencyGaps = allGaps.filter((g) => g && g.claimId === claimId);
-    const changeRecords = allChanges.filter((c) => 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,
-        },
-    };
-}