@kontourai/flow-agents 2.2.0 → 2.4.0

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

@@ -1,21 +1,73 @@
 import test from "node:test";
 import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
+import { createRequire } from "node:module";
 
 import {
   defaultArtifactRootForRead,
+  defaultCodexHome,
+  durableFlowAgentsRoot,
+  durableInstallRecordPath,
+  DURABLE_FLOW_AGENTS_DIR,
+  FLOW_AGENTS_RUNTIME_DIR,
+  FLOW_AGENTS_RUNTIME_SUBDIR,
   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"));
+  assert.equal(FLOW_AGENTS_RUNTIME_SUBDIR, "flow-agents");
+  assert.equal(FLOW_AGENTS_RUNTIME_DIR, path.join(".kontourai", "flow-agents"));
+  assert.equal(DURABLE_FLOW_AGENTS_DIR, ".flow-agents");
+  assert.equal(flowAgentsArtifactRoot(cwd), path.join(cwd, FLOW_AGENTS_RUNTIME_DIR));
+  assert.equal(durableFlowAgentsRoot(cwd), path.join(cwd, ".flow-agents"));
+  assert.equal(durableInstallRecordPath(cwd), path.join(cwd, ".flow-agents", "install.json"));
+  assert.equal(defaultArtifactRootForRead(cwd), path.join(cwd, FLOW_AGENTS_RUNTIME_DIR));
+  assert.notEqual(defaultArtifactRootForRead(cwd), durableFlowAgentsRoot(cwd));
+});
+
+test("TS and CJS artifact helpers stay in parity without durable-root fallback", () => {
+  const require = createRequire(import.meta.url);
+  const cjs = require("../../scripts/hooks/lib/local-artifact-paths.js");
+  const cwd = fs.mkdtempSync(path.join(os.tmpdir(), "flow-agents-paths-"));
+
+  fs.mkdirSync(path.join(cwd, DURABLE_FLOW_AGENTS_DIR, "previous-session"), { recursive: true });
+  fs.writeFileSync(path.join(cwd, DURABLE_FLOW_AGENTS_DIR, "current.json"), "{}\n");
+
+  assert.equal(cjs.KONTOURAI_DIR, KONTOURAI_DIR);
+  assert.equal(cjs.FLOW_AGENTS_RUNTIME_SUBDIR, FLOW_AGENTS_RUNTIME_SUBDIR);
+  assert.equal(cjs.FLOW_AGENTS_RUNTIME_DIR, FLOW_AGENTS_RUNTIME_DIR);
+  assert.equal(cjs.DURABLE_FLOW_AGENTS_DIR, DURABLE_FLOW_AGENTS_DIR);
+
+  assert.equal(cjs.flowAgentsArtifactRoot(cwd), flowAgentsArtifactRoot(cwd));
+  assert.equal(cjs.defaultArtifactRootForRead(cwd), defaultArtifactRootForRead(cwd));
+  assert.equal(cjs.durableFlowAgentsRoot(cwd), durableFlowAgentsRoot(cwd));
+  assert.deepEqual(cjs.flowAgentsArtifactRootsForRead(cwd), []);
+});
+
+test("defaultCodexHome honors CODEX_HOME env override", () => {
+  const previous = process.env["CODEX_HOME"];
+  try {
+    process.env["CODEX_HOME"] = "/custom/codex-home";
+    assert.equal(defaultCodexHome(), "/custom/codex-home");
+  } finally {
+    if (previous === undefined) delete process.env["CODEX_HOME"];
+    else process.env["CODEX_HOME"] = previous;
+  }
+});
+
+test("defaultCodexHome falls back to ~/.codex when CODEX_HOME is unset", () => {
+  const previous = process.env["CODEX_HOME"];
+  try {
+    delete process.env["CODEX_HOME"];
+    assert.equal(defaultCodexHome(), path.join(os.homedir(), ".codex"));
+  } finally {
+    if (previous === undefined) delete process.env["CODEX_HOME"];
+    else process.env["CODEX_HOME"] = previous;
+  }
 });

package/src/cli/pull-work-provider.ts

@@ -2,7 +2,7 @@ import * as fs from "node:fs";
 import { fileURLToPath } from "node:url";
 import { parseArgs, flagList, flagString } from "../lib/args.js";
 
-const FLOW_ARTIFACT_PATTERN = /(?<path>\.flow-agents\/[^\s`'")]+)/g;
+const FLOW_ARTIFACT_PATTERN = /(?<path>\.kontourai\/flow-agents\/[^\s`'")]+)/g;
 const GITHUB_ISSUE_PATTERN = /(?:(?<owner>[A-Za-z0-9_.-]+)\/(?<repo>[A-Za-z0-9_.-]+))?#(?<number>\d+)/g;
 const GITHUB_URL_PATTERN = /https:\/\/github\.com\/(?<owner>[^/\s]+)\/(?<repo>[^/\s]+)\/(?:issues|pull)\/(?<number>\d+)/g;
 const BLOCKER_PATTERN = /\b(?:blocked by|depends on|waiting on|requires|should follow|coordinate with)\b[:\s-]*(?<refs>[^\n]+)/gi;

package/src/cli/trust-bundle-policy-order.test.mjs

@@ -0,0 +1,87 @@
+// trust-bundle-policy-order.test.mjs — WS8 (AC1, iteration 2) policy-cache order regression.
+//
+// The verifier found that ensurePolicy cached the first-seen requiredEvidence per legacy
+// claimType, so two checks of the SAME kind that differ in command-presence (browser/security/
+// runtime with vs without a command) collided: the first-recorded requiredEvidence won and
+// corrupted the SECOND claim's derived status (verified -> proposed) depending on record order.
+//
+// This proves the fix: policy construction is keyed by (claimType, requiredEvidence), so two
+// same-kind checks differing in command-presence produce IDENTICAL bundles in BOTH record
+// orders (and each claim's derived status is order-independent).
+//
+// Run: `npm run test:unit`. Requires @kontourai/surface (the bundle producer's dependency).
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { buildTrustBundle } from "../../build/src/cli/workflow-sidecar.js";
+
+const TS = "2026-07-02T00:00:00Z";
+
+// A command-backed browser check (-> test_output) and a no-command browser check
+// (-> crawl_observation): SAME legacy claimType (workflow.check.browser), DIFFERENT
+// requiredEvidence. This is the exact collision the verifier reproduced.
+const checkCmd = { id: "browser-cmd", kind: "browser", status: "pass", summary: "e2e smoke via command", command: "npm run e2e" };
+const checkNoCmd = { id: "browser-nocmd", kind: "browser", status: "pass", summary: "manual crawl observation" };
+
+/** Deep-sort every array-of-objects-with-id so ordering never affects equality. */
+function canonicalize(bundle) {
+  const clone = JSON.parse(JSON.stringify(bundle));
+  const byId = (a, b) => String(a.id).localeCompare(String(b.id));
+  for (const key of ["claims", "evidence", "events", "policies"]) {
+    if (Array.isArray(clone[key])) clone[key].sort(byId);
+  }
+  return clone;
+}
+
+function statusByClaimId(bundle) {
+  const m = {};
+  for (const c of bundle.claims) m[c.id] = c.status;
+  return m;
+}
+
+test("buildTrustBundle: two same-kind checks differing in command-presence produce identical bundles in both record orders", async () => {
+  const forward = await buildTrustBundle("perm", TS, [checkCmd, checkNoCmd], [], []);
+  const reverse = await buildTrustBundle("perm", TS, [checkNoCmd, checkCmd], [], []);
+
+  // Surface is a hard dependency of the producer; if it is genuinely unavailable the whole
+  // bundle-write path is skipped elsewhere, so a null here is a real environment failure.
+  assert.ok(forward, "buildTrustBundle returned null (is @kontourai/surface installed?)");
+  assert.ok(reverse, "buildTrustBundle returned null (is @kontourai/surface installed?)");
+
+  // The whole bundle is order-independent once canonicalized (arrays sorted by id).
+  assert.deepEqual(
+    canonicalize(forward),
+    canonicalize(reverse),
+    "bundles differ by record order — policy-cache collision has regressed",
+  );
+
+  // And, specifically, each claim's derived status is order-independent (the defect's symptom
+  // was the second same-kind claim flipping verified -> proposed depending on order).
+  assert.deepEqual(statusByClaimId(forward), statusByClaimId(reverse));
+});
+
+test("buildTrustBundle: same-kind checks with different command-presence get DISTINCT policies (not a colliding shared one)", async () => {
+  const bundle = await buildTrustBundle("perm", TS, [checkCmd, checkNoCmd], [], []);
+  assert.ok(bundle, "buildTrustBundle returned null (is @kontourai/surface installed?)");
+
+  const browserPolicies = bundle.policies.filter((p) => p.claimType === "workflow.check.browser");
+  // Two distinct required-evidence signatures -> two distinct policies (keyed, not merged).
+  assert.equal(browserPolicies.length, 2, "expected two distinct workflow.check.browser policies");
+  const reqSets = browserPolicies.map((p) => p.requiredEvidence.slice().sort().join(",")).sort();
+  assert.deepEqual(reqSets, ["crawl_observation", "test_output"]);
+
+  // requiredEvidence is all-of in Surface, so the sets must NOT have been merged into one
+  // over-constrained policy requiring BOTH types.
+  for (const p of browserPolicies) {
+    assert.equal(p.requiredEvidence.length, 1, `policy ${p.id} must require exactly one evidence type (not a merged union)`);
+  }
+
+  // Each claim references its own policy, and both derive 'verified' (neither corrupted).
+  const statuses = statusByClaimId(bundle);
+  const cmdClaim = bundle.claims.find((c) => c.subjectId === "perm/browser-cmd");
+  const noCmdClaim = bundle.claims.find((c) => c.subjectId === "perm/browser-nocmd");
+  assert.ok(cmdClaim && noCmdClaim);
+  assert.notEqual(cmdClaim.verificationPolicyId, noCmdClaim.verificationPolicyId);
+  assert.equal(statuses[cmdClaim.id], "verified");
+  assert.equal(statuses[noCmdClaim.id], "verified");
+});

package/src/cli/usage-feedback.ts

@@ -3,7 +3,7 @@ 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";
+import { defaultArtifactRootForRead, defaultTelemetryDirForRead, defaultTelemetryDirsForRead, telemetryDataDir, flowAgentsArtifactRoot } from "../lib/local-artifact-root.js";
 
 const VALID_RESULTS = new Set(["success", "partial", "failure", "not_verified"]);
 
@@ -146,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 : [flowAgentsArtifactRoot(), legacyFlowAgentsArtifactRoot()]).flatMap((item) => fs.existsSync(item) ? artifactOutcomes(item, flags) : []);
+  const records = (artifacts.length ? artifacts : [flowAgentsArtifactRoot()]).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;
@@ -368,7 +368,7 @@ 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(flowAgentsArtifactRoot(candidate)) || fs.existsSync(legacyFlowAgentsArtifactRoot(candidate))).map((repoRoot) => {
+  return candidates.filter((candidate) => fs.existsSync(flowAgentsArtifactRoot(candidate))).map((repoRoot) => {
     const name = path.basename(repoRoot);
     return { name, repo: name, repo_root: repoRoot, artifact_dir: defaultArtifactRootForRead(repoRoot), input_telemetry_dir: defaultTelemetryDirForRead(repoRoot), runtime: "codex", skill_ids: [] };
   });

package/src/cli/validate-hook-influence.ts

@@ -8,6 +8,7 @@ const validEvents = new Set(["UserPromptSubmit", "PostToolUse", "Stop"]);
 const requiredCases: Record<string, { description: string; tier: string; hook?: string; event?: string; must_include?: string[]; agent_must_do?: string[] }> = {
   "dev-builder-build-requires-pickup-probe-before-plan": { description: "missing pickup Probe before plan", tier: "design-target", must_include: ["design-probe", "accepted gaps", "provider_state", "conflict_risks"], agent_must_do: ["route decision_gap back to design-probe/pickup Probe"] },
   "dev-builder-review-before-verify-after-execute": { description: "review-before-verify after execute", tier: "adapter", event: "PostToolUse", must_include: ["Next: review", "then verify", "report only"], agent_must_do: ["review-work for report-only critique before verify-work", "not count critique.json as verification evidence"] },
+  "dev-builder-route-fresh-coding-prompt": { description: "fresh coding prompt routes into Builder workflow", tier: "adapter", event: "UserPromptSubmit", must_include: ["BUILDER WORKFLOW ROUTE", "activate `deliver`", "--flow-id builder.build", "plan-work -> execute-plan -> review-work -> verify-work", "publish/release-readiness and learning-review"], agent_must_do: ["activate Builder Kit delivery workflow before source edits", "use deliver by default for coding/build work", "do not bypass plan-work -> execute-plan -> review-work -> verify-work", "publish, release readiness, and learning feedback"] },
   "dev-verify-fail-preserves-trace-before-rework": { description: "verify failure route-back with preserved FAIL evidence", tier: "design-target", must_include: ["If verdict=FAIL: record the FAIL artifact"], agent_must_do: ["write the FAIL artifact before routing back", "route to plan"] },
   "codex-claude-strict-stop-adapter-contract": { description: "Goal Fit stop adapter behavior", tier: "adapter", hook: "stop-goal-fit", event: "Stop", must_include: ["Goal Fit warning"], agent_must_do: ["treat strict Stop guidance as a blocker"] },
   "codex-live-context-gap": { description: "Codex documented runtime gap", tier: "documented-runtime-gap", must_include: ["STATE:", "not_verified"], agent_must_do: ["record NOT_VERIFIED for live influence"] },

package/src/cli/validate-workflow-artifacts.ts

@@ -1,10 +1,16 @@
 #!/usr/bin/env node
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { fileURLToPath } from "node:url";
 
 type Issue = { path: string; message: string };
 
-const root = path.resolve(".");
+// Resolve bundled JSON Schemas relative to this compiled script's own package
+// location (build/src/cli/validate-workflow-artifacts.js -> ../../../schemas), NOT
+// process.cwd(), so `flow-agents-validate-artifacts` works from any repo (the artifact
+// paths to validate are still taken from argv/cwd). Mirrors the package-relative pattern
+// used for liveness-read.js in workflow-sidecar.ts.
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
 const statusRe = /\[(PASS|FAIL|NOT_VERIFIED|SKIP|PARTIAL)\]/i;
 const dateTimeRe = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
 const sidecarSchemas: Record<string, string> = {
@@ -259,12 +265,13 @@ function readJson(file: string): { value: any | undefined; issues: Issue[] } {
   catch (error) { return { value: undefined, issues: [{ path: file, message: `invalid JSON: ${(error as Error).message}` }] }; }
 }
 
-function validateSidecar(file: string): Issue[] {
+function validateSidecar(file: string): { issues: Issue[]; warnings: Issue[] } {
   const { value, issues } = readJson(file);
-  if (value === undefined) return issues;
+  const warnings: Issue[] = [];
+  if (value === undefined) return { issues, warnings };
   const schemaFile = sidecarSchemas[path.basename(file)];
   if (schemaFile) {
-    const schema = JSON.parse(readText(path.join(root, schemaFile)));
+    const schema = JSON.parse(readText(path.join(packageRoot, schemaFile)));
     validateSchemaValue(file, value, schema, path.basename(file), issues, schema);
   }
   if (path.basename(file) === "evidence.json") {
@@ -296,7 +303,10 @@ function validateSidecar(file: string): Issue[] {
       if (Array.isArray(value.post_deploy_checks) && value.post_deploy_checks.some((c: any) => !["planned", "pass"].includes(c.status))) issues.push({ path: file, message: "deploy decision requires post_deploy_checks to be planned or pass" });
     }
   }
-  return issues;
+  if (path.basename(file) === "state.json" && value && typeof value === "object" && !Array.isArray(value) && !("branch" in value)) {
+    warnings.push({ path: file, message: "state.json has no branch field (legacy/pre-#289 session) — re-run `ensure-session` to backfill agent/<actor>/<slug>." });
+  }
+  return { issues, warnings };
 }
 
 function validateLearningCorrections(file: string, status: unknown, records: any[], issues: Issue[]): void {
@@ -413,9 +423,15 @@ function main(): number {
   const markdown = artifactPaths(pathsIn);
   const sidecars = sidecarPaths(pathsIn);
   const issues: Issue[] = [];
+  const warnings: Issue[] = [];
   if (!skipMarkdown) for (const file of markdown) issues.push(...validateArtifact(file));
-  for (const file of sidecars) issues.push(...validateSidecar(file));
+  for (const file of sidecars) {
+    const result = validateSidecar(file);
+    issues.push(...result.issues);
+    warnings.push(...result.warnings);
+  }
   issues.push(...validateSidecarGroup(pathsIn, markdown, requireSidecars, requireCritique));
+  for (const w of warnings) console.error(`WARN ${w.path}: ${w.message}`);
   if (issues.length) {
     for (const issue of issues) console.error(`${issue.path}: ${issue.message}`);
     return 1;

package/src/cli/veritas-readiness-adapter.test.mjs

@@ -0,0 +1,267 @@
+// veritas-readiness-adapter.test.mjs — direct node:test coverage for the Veritas Governance
+// Kit adapter (kits/veritas-governance/adapter/readiness-to-trust-bundle.mjs), specifically
+// hasBlockingFailure() and buildReadinessTrustBundle().
+//
+// WS5 iteration-2 part 2: the adapter-vs-Veritas semantics fork is SETTLED (owner-ratified +
+// investigation-confirmed, see .kontourai/flow-agents/ws5-governance-kit-slice1 session
+// findings). The adapter's stricter blocking-failure derivation is CORRECT: it matches
+// Veritas's own PRIVATE readinessHasBlockingFailure helper (veritas/src/surface/readiness.mjs)
+// and Surface's weakest-link claim derivation (tests/surface/readiness-derived-claim.test.mjs
+// in veritas). The adapter intentionally does NOT apply record.promotion_allowed as a
+// short-circuit — promotion_allowed is a workstream-routing hint, not a safety signal, and
+// Veritas's own EXPORTED readinessSurfaceStatus()/readinessVerdict() short-circuiting on it is
+// a filed Veritas bug: kontourai/veritas#106
+// (https://github.com/kontourai/veritas/issues/106). These tests pin the adapter's
+// blocking-failure semantics as the durable contract, and include explicit parity-pinning
+// cases (below) asserting the adapter verdict against the documented blocking-failure
+// semantics. Once veritas#106 is fixed upstream, Veritas's exported functions will agree with
+// this adapter (and with these tests) instead of diverging from them.
+//
+// GLOB NOTE: `npm run test:unit` only globs `src/cli/*.test.mjs` (see package.json). The
+// adapter under test lives in `kits/veritas-governance/adapter/`, which is plain JS (not
+// compiled by tsc — see tsconfig.json's `include: ["src/**/*.ts"]`), so it is imported here
+// directly by relative path rather than from `build/`. This test file is placed under
+// `src/cli/` — not colocated with the adapter under `kits/veritas-governance/` — purely so it
+// is picked up by the existing test:unit glob; there is no other test runner wired for
+// `kits/**`. If a kit-scoped test glob is added later, this file (or a copy) should move
+// there instead.
+//
+// Run: `npm run test:unit`.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+import { hasBlockingFailure, buildReadinessTrustBundle } from "../../kits/veritas-governance/adapter/readiness-to-trust-bundle.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const FIXTURES_DIR = path.resolve(__dirname, "../../kits/veritas-governance/fixtures/readiness");
+
+function loadFixture(name) {
+  return JSON.parse(readFileSync(path.join(FIXTURES_DIR, name), "utf8"));
+}
+
+// ─── hasBlockingFailure — synthetic minimal records ────────────────────────────────────────
+
+test("hasBlockingFailure: clean record (no blocking signal) returns false", () => {
+  assert.equal(hasBlockingFailure({}), false);
+  assert.equal(
+    hasBlockingFailure({
+      uncovered_path_result: "pass",
+      policy_results: [{ passed: true, enforcementLevel: "Require", rule_id: "r1" }],
+      selected_evidence_checks: [{ id: "c1", evidence_check_result: { passed: true } }],
+      external_tool_results: [{ verdict: "pass", blocking: true }],
+    }),
+    false,
+  );
+});
+
+test("hasBlockingFailure: uncovered_path_result === 'fail' is blocking", () => {
+  assert.equal(hasBlockingFailure({ uncovered_path_result: "fail" }), true);
+});
+
+test("hasBlockingFailure: a failed Require-enforcement policy result is blocking", () => {
+  assert.equal(
+    hasBlockingFailure({
+      policy_results: [{ passed: false, enforcementLevel: "Require", rule_id: "required-x" }],
+    }),
+    true,
+  );
+});
+
+test("hasBlockingFailure: a failed policy result with a non-Require enforcement level is NOT blocking", () => {
+  assert.equal(
+    hasBlockingFailure({
+      policy_results: [{ passed: false, enforcementLevel: "Recommend", rule_id: "recommend-x" }],
+    }),
+    false,
+  );
+});
+
+test("hasBlockingFailure: a failed selected evidence check is blocking", () => {
+  assert.equal(
+    hasBlockingFailure({
+      selected_evidence_checks: [{ id: "c1", evidence_check_result: { passed: false } }],
+    }),
+    true,
+  );
+});
+
+test("hasBlockingFailure: a blocking external-tool fail/missing verdict is blocking", () => {
+  assert.equal(hasBlockingFailure({ external_tool_results: [{ verdict: "fail", blocking: true }] }), true);
+  assert.equal(hasBlockingFailure({ external_tool_results: [{ verdict: "missing" }] }), true); // blocking defaults truthy (only `false` opts out)
+});
+
+test("hasBlockingFailure: a NON-blocking external-tool fail (blocking: false) is not blocking", () => {
+  assert.equal(hasBlockingFailure({ external_tool_results: [{ verdict: "fail", blocking: false }] }), false);
+});
+
+// ─── hasBlockingFailure — settled promotion_allowed non-application ───────────────────────
+// SETTLED: unlike Veritas's own EXPORTED readinessSurfaceStatus()/readinessVerdict(), this
+// adapter does NOT short-circuit on record.promotion_allowed. A record with
+// promotion_allowed: true AND a failing Require rule is still treated as blocking by the
+// adapter — this is correct: promotion_allowed is a workstream-routing hint (set only in
+// Veritas's src/repo/routing.mjs resolveWorkstream() from file-pattern lane resolution), not a
+// safety signal, and Veritas's own short-circuit on it is a filed bug (kontourai/veritas#106).
+test("hasBlockingFailure: promotion_allowed=true does NOT suppress a blocking Require failure (settled semantics; veritas#106)", () => {
+  const record = {
+    promotion_allowed: true,
+    policy_results: [{ passed: false, enforcementLevel: "Require", rule_id: "required-veritas-cli-artifacts" }],
+  };
+  assert.equal(hasBlockingFailure(record), true, "adapter correctly ignores promotion_allowed — see header comment / session findings / veritas#106");
+});
+
+test("hasBlockingFailure: promotion_allowed=false with no blocking signal is not blocking (promotion_allowed is ignored either way)", () => {
+  const record = {
+    promotion_allowed: false,
+    uncovered_path_result: "pass",
+    policy_results: [{ passed: true, enforcementLevel: "Require", rule_id: "r1" }],
+    selected_evidence_checks: [{ id: "c1", evidence_check_result: { passed: true } }],
+    external_tool_results: [{ verdict: "pass", blocking: true }],
+  };
+  assert.equal(hasBlockingFailure(record), false);
+});
+
+// ─── buildReadinessTrustBundle — synthetic records ─────────────────────────────────────────
+
+test("buildReadinessTrustBundle: a clean record yields a ready/verified software-readiness-verdict claim", async () => {
+  const record = {
+    run_id: "test-run-ready",
+    timestamp: "2026-07-02T00:00:00.000Z",
+    source_ref: "test-subject-ready",
+    policy_results: [],
+    selected_evidence_checks: [],
+    external_tool_results: [],
+    uncovered_path_result: "pass",
+  };
+  const { bundle, verdict, derivedStatus } = await buildReadinessTrustBundle(record);
+
+  assert.equal(verdict, "ready");
+  assert.equal(derivedStatus, "verified");
+  // bundle uses the facet-renamed schemaVersion 5 shape (hachure@0.9's strict schema): see
+  // https://github.com/kontourai/flow-agents/issues/281.
+  assert.equal(bundle.schemaVersion, 5);
+  assert.equal(bundle.source, "veritas-governance-kit/readiness-adapter");
+  assert.equal(bundle.claims.length, 1);
+  const claim = bundle.claims[0];
+  assert.equal(claim.claimType, "software-readiness-verdict");
+  assert.equal(claim.facet, "veritas.readiness");
+  assert.equal(claim.subjectId, "test-subject-ready");
+  assert.equal(claim.value.verdict, "ready");
+  assert.equal(claim.status, "verified");
+  assert.deepEqual(claim.value.blocking, { failedRequirements: [], failedEvidenceChecks: [] });
+  assert.equal(bundle.evidence[0].passing, true);
+  assert.equal(bundle.events[0].status, "verified");
+});
+
+test("buildReadinessTrustBundle: a record with a blocking Require failure yields a not-ready/disputed claim", async () => {
+  const record = {
+    run_id: "test-run-not-ready",
+    timestamp: "2026-07-02T00:00:00.000Z",
+    source_ref: "test-subject-not-ready",
+    policy_results: [{ passed: false, enforcementLevel: "Require", rule_id: "required-thing" }],
+    selected_evidence_checks: [],
+    external_tool_results: [],
+    uncovered_path_result: "pass",
+  };
+  const { bundle, verdict, derivedStatus } = await buildReadinessTrustBundle(record);
+
+  assert.equal(verdict, "not-ready");
+  assert.equal(derivedStatus, "disputed");
+  const claim = bundle.claims[0];
+  assert.equal(claim.value.verdict, "not-ready");
+  assert.equal(claim.status, "disputed");
+  assert.deepEqual(claim.value.blocking.failedRequirements, ["required-thing"]);
+  assert.equal(bundle.evidence[0].passing, false);
+  assert.equal(bundle.events[0].status, "disputed");
+});
+
+test("buildReadinessTrustBundle: --subject-id override wins over record source_ref/integrity.sourceRef", async () => {
+  const record = {
+    run_id: "test-run-subject",
+    timestamp: "2026-07-02T00:00:00.000Z",
+    source_ref: "record-source-ref",
+    policy_results: [],
+  };
+  const { bundle } = await buildReadinessTrustBundle(record, { subjectId: "explicit-subject" });
+  assert.equal(bundle.claims[0].subjectId, "explicit-subject");
+});
+
+// ─── buildReadinessTrustBundle — real captured fixtures (settled semantics) ────────────────
+// The two committed fixtures are REAL captured `veritas readiness --check evidence
+// --working-tree` output (see kits/veritas-governance/fixtures/readiness/*). Both have
+// promotion_allowed: true; not-ready.readiness-report.json also has a failing Require rule.
+// Veritas's own EXPORTED readinessSurfaceStatus() would (today) report BOTH as verified/ready
+// because it short-circuits on promotion_allowed — that is the filed bug, kontourai/veritas#106
+// (https://github.com/kontourai/veritas/issues/106). This adapter correctly disagrees on the
+// not-ready fixture. Once #106 is fixed upstream, Veritas's exported functions will agree with
+// the adapter (and with these tests) instead of diverging from them.
+
+test("buildReadinessTrustBundle: ready.readiness-report.json fixture -> ready/verified", async () => {
+  const record = loadFixture("ready.readiness-report.json");
+  const { verdict, derivedStatus } = await buildReadinessTrustBundle(record);
+  assert.equal(verdict, "ready");
+  assert.equal(derivedStatus, "verified");
+});
+
+test("buildReadinessTrustBundle: not-ready.readiness-report.json fixture -> not-ready/disputed despite promotion_allowed=true (settled semantics; veritas#106)", async () => {
+  const record = loadFixture("not-ready.readiness-report.json");
+  assert.equal(record.promotion_allowed, true, "fixture precondition: promotion_allowed is true");
+  const { verdict, derivedStatus } = await buildReadinessTrustBundle(record);
+  assert.equal(verdict, "not-ready");
+  assert.equal(derivedStatus, "disputed");
+});
+
+// ─── Parity pinning (WS5 iteration-2 part 2) ───────────────────────────────────────────────
+// Explicit parity assertions: for both shipped fixtures plus two synthetic records, the
+// adapter verdict must match the documented blocking-failure semantics (README "Semantics"
+// section / adapter header comment) regardless of record.promotion_allowed. Once
+// kontourai/veritas#106 (https://github.com/kontourai/veritas/issues/106) is fixed, Veritas's
+// own exported readinessSurfaceStatus()/readinessVerdict() will independently agree with these
+// same verdicts instead of short-circuiting to verified/ready on promotion_allowed===true.
+
+test("parity: ready.readiness-report.json fixture matches documented blocking-failure semantics -> ready", async () => {
+  const record = loadFixture("ready.readiness-report.json");
+  const { verdict } = await buildReadinessTrustBundle(record);
+  assert.equal(verdict, hasBlockingFailure(record) ? "not-ready" : "ready");
+  assert.equal(verdict, "ready");
+});
+
+test("parity: not-ready.readiness-report.json fixture matches documented blocking-failure semantics -> not-ready (independent of promotion_allowed=true)", async () => {
+  const record = loadFixture("not-ready.readiness-report.json");
+  const { verdict } = await buildReadinessTrustBundle(record);
+  assert.equal(verdict, hasBlockingFailure(record) ? "not-ready" : "ready");
+  assert.equal(verdict, "not-ready");
+});
+
+test("parity: synthetic promotion_allowed=true + failing Require matches documented blocking-failure semantics -> not-ready", async () => {
+  const record = {
+    run_id: "parity-true-failing",
+    promotion_allowed: true,
+    policy_results: [{ passed: false, enforcementLevel: "Require", rule_id: "required-parity-check" }],
+    selected_evidence_checks: [],
+    external_tool_results: [],
+    uncovered_path_result: "pass",
+  };
+  const { verdict, derivedStatus } = await buildReadinessTrustBundle(record);
+  assert.equal(verdict, hasBlockingFailure(record) ? "not-ready" : "ready");
+  assert.equal(verdict, "not-ready");
+  assert.equal(derivedStatus, "disputed");
+});
+
+test("parity: synthetic promotion_allowed=false + clean record matches documented blocking-failure semantics -> ready", async () => {
+  const record = {
+    run_id: "parity-false-clean",
+    promotion_allowed: false,
+    policy_results: [{ passed: true, enforcementLevel: "Require", rule_id: "required-parity-check" }],
+    selected_evidence_checks: [{ id: "c1", evidence_check_result: { passed: true } }],
+    external_tool_results: [{ verdict: "pass", blocking: true }],
+    uncovered_path_result: "pass",
+  };
+  const { verdict, derivedStatus } = await buildReadinessTrustBundle(record);
+  assert.equal(verdict, hasBlockingFailure(record) ? "not-ready" : "ready");
+  assert.equal(verdict, "ready");
+  assert.equal(derivedStatus, "verified");
+});

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

@@ -41,7 +41,7 @@ const ACTIVE_STATUSES = new Set([
 const KNOWN_LEARNING_STATUSES = new Set(["pending", "learned", "followup_required", "blocked"]);
 const KNOWN_LEARNING_ROUTE_TARGETS = new Set(["rule", "skill", "power", "agent", "eval", "doc", "backlog", "knowledge", "none"]);
 const KNOWN_LEARNING_ROUTE_STATUSES = new Set(["completed", "open", "deferred", "accepted", "rejected"]);
-const SKIPPED_ROOT_ENTRIES = new Set(["archive", "changes", "delivery-history"]);
+const SKIPPED_ROOT_ENTRIES = new Set(["archive", "changes", "delivery-history", "liveness"]);
 const MAX_SIDECAR_BYTES = 1024 * 1024;
 
 function printHelp(): void {
@@ -50,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: .kontourai/flow-agents, with .flow-agents read fallback)");
+  console.log("  --artifact-root <path>  Local artifact root to scan (default: .kontourai/flow-agents)");
   console.log("  --json                  Print stable JSON buckets instead of text");
   console.log("  --help                  Show this help");
   console.log("");
@@ -160,6 +160,33 @@ function invalidItem(slug: string, workflowPath: string, reason: string): AuditI
   };
 }
 
+// Promote-then-archive gate (issue #312). A delivered session's durable residue
+// (decisions, vocabulary, learnings, doc updates) must be PROMOTED before the session
+// is archived. Promotion is recorded as a session-local promotion claim in the session
+// trust.bundle (workflow-sidecar promote), detectable here via claim.metadata.promotion
+// — no new manifest entry required. A delivered/accepted session that reached a terminal
+// shape WITHOUT that claim is a cleanup_candidate (blocked from archive) with a remedy
+// naming the promote step. Already-`archived` sessions are past the gate and are never
+// re-flagged (issue #312 non-goal: do not backfill already-archived sessions).
+const PROMOTE_REMEDY =
+  "run `flow-agents workflow-sidecar promote <dir> --evidence-path <durable-doc> ...`" +
+  " (or `promote --none --reason \"<why nothing durable>\"`) to record the promotion claim before archiving";
+
+function hasPromotionClaim(workflowDir: string): boolean {
+  const bundlePath = path.join(workflowDir, "trust.bundle");
+  if (!fs.existsSync(bundlePath)) return false;
+  const parsed = readJson(bundlePath, "trust.bundle");
+  if (!parsed.ok) return false;
+  const bundle = objectValue(parsed.value);
+  if (!bundle || !Array.isArray(bundle.claims)) return false;
+  return bundle.claims.some((entry) => {
+    const claim = objectValue(entry);
+    if (!claim) return false;
+    const meta = objectValue(claim.metadata);
+    return meta !== null && objectValue(meta.promotion) !== null;
+  });
+}
+
 function classifyWorkflow(slug: string, workflowPath: string): AuditItem {
   const statePath = path.join(workflowPath, "state.json");
   if (!fs.existsSync(statePath)) return invalidItem(slug, workflowPath, "missing state.json");
@@ -193,9 +220,15 @@ function classifyWorkflow(slug: string, workflowPath: string): AuditItem {
     return { ...base, classification: "cleanup_candidate", reasons: ["verified workflow has next_action.status done"] };
   }
   if (["delivered", "accepted", "archived"].includes(status) && phase === "done") {
+    if (status !== "archived" && !hasPromotionClaim(workflowPath)) {
+      return { ...base, classification: "cleanup_candidate", reasons: [`${status} workflow reached phase done without a promotion claim; ${PROMOTE_REMEDY}`] };
+    }
     return { ...base, classification: "terminal_done", reasons: [`${status} workflow is in phase done`] };
   }
   if ((status === "accepted" || status === "archived") && learning.reasons.length === 0) {
+    if (status !== "archived" && !hasPromotionClaim(workflowPath)) {
+      return { ...base, classification: "cleanup_candidate", reasons: [`${status} workflow has closed learning routing but no promotion claim; ${PROMOTE_REMEDY}`] };
+    }
     return { ...base, classification: "terminal_done", reasons: [`${status} workflow has no open learning routing`] };
   }
   return { ...base, classification: "invalid", reasons: [`unrecognized lifecycle shape: status=${status}, phase=${phase}, next_action.status=${nextStatus ?? "missing"}`] };