@kontourai/flow-agents 3.12.1 → 4.1.0

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

@@ -8,53 +8,93 @@
 // 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 fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
 
 import {
-  buildClaimExplanation as buildClaimExplanationReexport,
   deriveGateCalibration,
   gateAdvisoryFix,
   buildGateInquiryRecords,
+  isNarrativeNamespacePath,
+  isNarrativeArtifactContent,
   validateEvidenceRef,
   normalizeEvidenceRefs,
   normalizeCheck,
+  normalizeFinding,
+  normalizeLearning,
   reduceCaptureLogByCommand,
 } from "../../build/src/cli/workflow-sidecar.js";
-import { buildClaimExplanation } from "../../build/src/cli/sidecar-claim-explain.js";
 
-// ── buildClaimExplanation (extracted pure projection) ────────────────────────
+// ── explainClaim (#171: consumed from @kontourai/surface >=2.10) ─────────────
+// The local buildClaimExplanation prototype was lifted into Surface (surface#151)
+// with the drilldown composition folded inside; these tests pin the consumed
+// function's behavior through the SAME expectations the prototype carried, so a
+// Surface regression (or an accidental un-lift) fails here.
+import { explainClaim, buildTrustReport, TrustBundleBuilder } from "@kontourai/surface";
 
-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");
+test("explainClaim (Surface): unknown claim id returns found:false sentinel", () => {
+  const report = buildTrustReport(new TrustBundleBuilder({ source: "unit:171" }).build());
+  const out = explainClaim(report, "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");
+test("explainClaim (Surface): projects status, policy, evidence, and filtered gaps for a found claim", () => {
+  const builder = new TrustBundleBuilder({ source: "unit:171" });
+  builder.addClaim({
+    id: "c1", subjectType: "repo", subjectId: "flow-agents", claimType: "workflow.check",
+    fieldOrBehavior: "unit-tests", value: "pass", verificationPolicyId: "p1",
+    createdAt: "2026-07-14T00:00:00.000Z", updatedAt: "2026-07-14T00:00:00.000Z",
+  });
+  builder.addPolicy({
+    id: "p1", claimType: "workflow.check", requiredEvidence: ["test_output"], requiredMethods: ["validation"],
+    acceptanceCriteria: ["AC1"], reviewAuthority: "owner", validityRule: { kind: "manual" },
+    stalenessTriggers: [], conflictRules: [], impactLevel: "high",
+  });
+  builder.addEvidence({
+    id: "e1", claimId: "c1", evidenceType: "test_output", method: "validation",
+    sourceRef: "run:e1", excerptOrSummary: "npm test", observedAt: "2026-07-14T00:00:00.000Z",
+    collectedBy: "ci", execution: { runner: "bash", label: "npm test", exitCode: 0 },
+  });
+  const out = explainClaim(buildTrustReport(builder.build()), "c1");
   assert.equal(out.found, true);
-  assert.equal(out.status, "verified");
+  assert.equal(out.status, "proposed");               // derived by the report (no verifying event), projected verbatim
+  assert.equal(out.value, "pass");                    // String coercion of the claim value
+  assert.equal(out.claimType, "workflow.check");
   assert.equal(out.policy.id, "p1");
-  assert.deepEqual(out.policy.requiredEvidence, ["test"]);
+  assert.deepEqual(out.policy.requiredEvidence, ["test_output"]);
   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"
+  // Gap filtering: only THIS claim's transparency gaps appear (none seeded for c1,
+  // and a report-level gap for another claim must not leak in).
+  assert.deepEqual(out.why.transparencyGaps.filter((gap) => gap.claimId !== "c1"), []);
+});
+
+test("explainClaim (Surface): legacy evidence label/summary fallback tolerance survives the lift", () => {
+  // Pre-lift bundles could carry top-level label/summary on evidence; the consumed
+  // function keeps the prototype's fallback chains (label ?? excerptOrSummary ?? ...).
+  const builder = new TrustBundleBuilder({ source: "unit:171-legacy" });
+  builder.addClaim({
+    id: "c2", subjectType: "repo", subjectId: "flow-agents", claimType: "workflow.check",
+    fieldOrBehavior: "legacy", value: "pass",
+    createdAt: "2026-07-14T00:00:00.000Z", updatedAt: "2026-07-14T00:00:00.000Z",
+  });
+  builder.addEvidence({
+    id: "e2", claimId: "c2", evidenceType: "attestation", method: "attestation",
+    sourceRef: "run:e2", excerptOrSummary: "excerpt-wins-for-summary", observedAt: "2026-07-14T00:00:00.000Z",
+    collectedBy: "ci",
+  });
+  const out = explainClaim(buildTrustReport(builder.build()), "c2");
+  assert.equal(out.found, true);
+  assert.equal(out.evidence.length, 1);
+  assert.equal(out.evidence[0].label, "excerpt-wins-for-summary");   // label falls back to excerptOrSummary
+  assert.equal(out.evidence[0].summary, "excerpt-wins-for-summary"); // summary prefers excerptOrSummary
+  assert.equal(out.evidence[0].execution, null);
+  assert.equal(out.evidence[0].passing, true);                       // no execution, not disputed → passing
 });
 
 // ── deriveGateCalibration (pure mapping) ─────────────────────────────────────
@@ -93,6 +133,99 @@ test("validateEvidenceRef: rejects bad kind, unsupported field, and incomplete s
   assert.throws(() => validateEvidenceRef({ kind: "source", file: "a.ts" }, "refs"), /source refs require/);
 });
 
+test("narrative namespace paths and free-form references are rejected with the typed #619 diagnostic", () => {
+  const root = "/tmp/project";
+  assert.equal(isNarrativeNamespacePath(root, "/tmp/project/.kontourai/narrative/run/n1/envelope.json"), true);
+  assert.equal(isNarrativeNamespacePath(root, "/tmp/project/.kontourai/flow-agents/run/narrative/legacy.md"), true);
+  assert.equal(isNarrativeNamespacePath(root, "/tmp/project/docs/narrative/design.md"), false);
+  for (const ref of [
+    { kind: "source", file: "src/file.ts", line_start: 1, line_end: 1, excerpt: "see .kontourai/narrative/run/n1/envelope.json" },
+    { kind: "artifact", file: ".kontourai/narrative/run/n1/envelope.json", summary: "rendered narrative" },
+    { kind: "command", excerpt: "cat .kontourai/flow-agents/run/narrative/envelope.md" },
+    { kind: "provider", url: "file:///.kontourai/narrative/run/n1/envelope.json" },
+    { kind: "external", url: "https://example.invalid/.kontourai/narrative/run/n1/envelope.json" },
+  ]) {
+    assert.throws(() => validateEvidenceRef(ref, "refs"), /narrative trust isolation \(#619\)/);
+  }
+});
+
+test("narrative isolation canonicalizes aliases and rejects narrative content independent of location", { concurrency: false }, () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "narrative-isolation-unit-"));
+  const narrativeDir = path.join(root, ".kontourai", "narrative", "run", "n1");
+  const envelope = path.join(narrativeDir, "envelope.json");
+  const relocated = path.join(root, "evidence", "relocated.json");
+  const hardlink = path.join(root, "evidence", "hardlink.json");
+  const symlink = path.join(root, "evidence", "symlink.json");
+  const commandSymlink = path.join(root, "evidence", "narrative-symlink.sh");
+  const source = path.join(root, "src", "narrative", "composer.ts");
+  fs.mkdirSync(narrativeDir, { recursive: true });
+  fs.mkdirSync(path.dirname(relocated), { recursive: true });
+  fs.mkdirSync(path.dirname(source), { recursive: true });
+  const bytes = Buffer.from('{"schema_version":"grounded-execution-narrative/v1","narrative_id":"n1"}');
+  fs.writeFileSync(envelope, bytes);
+  fs.copyFileSync(envelope, relocated);
+  fs.linkSync(envelope, hardlink);
+  fs.symlinkSync(envelope, symlink);
+  fs.symlinkSync(envelope, commandSymlink);
+  fs.writeFileSync(source, 'export const narrativeSource = true;\n');
+  try {
+    assert.equal(isNarrativeNamespacePath(root, path.join(root, ".KONTOURAI", "NARRATIVE", "run", "n1", "envelope.json")), true);
+    assert.equal(isNarrativeArtifactContent(bytes), true);
+    for (const file of [envelope, relocated, hardlink, symlink]) {
+      assert.throws(
+        () => validateEvidenceRef({ kind: "artifact", file, summary: "must reject" }, "refs", root),
+        /narrative trust isolation \(#619\)/,
+      );
+    }
+    assert.throws(
+      () => validateEvidenceRef({ kind: "provider", url: "file%3A%2F%2F%2F.KONTOURAI%2FNARRATIVE%2Frun%2Fn1%2Fenvelope.json" }, "refs", root),
+      /narrative trust isolation \(#619\)/,
+    );
+    assert.doesNotThrow(() => validateEvidenceRef({ kind: "source", file: source, line_start: 1, line_end: 1, excerpt: "source code" }, "refs", root));
+    for (const command of [
+      "test -f .kontourai/narrative/run/n1/envelope.json",
+      "test -f .KONTOURAI/NARRATIVE/run/n1/envelope.json",
+      "test -f .kontourai%2Fnarrative%2Frun%2Fn1%2Fenvelope.json",
+      "bash evidence/narrative-symlink.sh",
+      "cd .kontourai && test -f narrative/run/n1/envelope.json",
+    ]) {
+      assert.throws(() => normalizeCheck({ id: "n", kind: "command", status: "pass", summary: "n", command }, false, undefined, root), /narrative trust isolation \(#619\)/);
+    }
+    assert.doesNotThrow(() => normalizeCheck({
+      id: "variable-composition", kind: "command", status: "pass", summary: "static scanner residual",
+      command: 'base=.kontourai; test -f "$base/narrative/run/n1/envelope.json"',
+    }, false, undefined, root));
+    assert.throws(() => normalizeCheck({
+      id: "standard-ref", kind: "test", status: "pass", summary: "must reject",
+      standard_refs: [{ standard: "junit", ref: ".kontourai/narrative/run/n1/envelope.json" }],
+    }, false, undefined, root), /narrative trust isolation \(#619\)/);
+    assert.throws(() => normalizeCheck({
+      id: "surface-ref", kind: "policy", status: "pass", summary: "must reject",
+      surface_trust_refs: [{
+        artifact_kind: "trust.bundle", artifact_ref: ".kontourai/narrative/run/n1/envelope.json",
+        claim_status: "accepted", freshness: { status: "fresh" }, authority: { producer: "surface-local" },
+        integrity: { status: "matched" }, status: "pass", summary: "accepted",
+      }],
+    }, false, undefined, root), /narrative trust isolation \(#619\)/);
+    assert.throws(() => normalizeCheck({
+      id: "standard-content", kind: "test", status: "pass", summary: "must reject",
+      standard_refs: [{ standard: "junit", ref: hardlink }],
+    }, false, undefined, root), /narrative trust isolation \(#619\)/);
+    assert.throws(() => normalizeCheck({
+      id: "surface-content", kind: "policy", status: "pass", summary: "must reject",
+      surface_trust_refs: [{
+        artifact_kind: "trust.bundle", artifact_ref: relocated, claim_status: "accepted",
+        freshness: { status: "fresh" }, authority: { producer: "surface-local" },
+        integrity: { status: "matched" }, status: "pass", summary: "accepted",
+      }],
+    }, false, undefined, root), /narrative trust isolation \(#619\)/);
+    assert.throws(() => normalizeFinding({ file_refs: [hardlink] }, root), /narrative trust isolation \(#619\)/);
+    assert.throws(() => normalizeLearning({ source_refs: [relocated], facts: [], routing: [], outcome: "unknown", correction: { needed: false, evidence: "none" } }, "2026-07-14T00:00:00.000Z", root), /narrative trust isolation \(#619\)/);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
 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/);
@@ -230,3 +363,62 @@ test("buildGateInquiryRecords: emits a single missed_block record for an empty b
   assert.equal(records.length, 1);
   assert.equal(records[0].answer.value.calibration, "missed_block");
 });
+
+// ── #634: writer-observed execution entries in the capture fold ─────────────
+test("writer-observed pass lifts an otherwise ambiguous command to pass", () => {
+  const fold = reduceCaptureLogByCommand([
+    { command: "npm run test:unit", observedResult: "ambiguous", exitCode: null, source: "postToolUse-capture" },
+    { command: "npm run test:unit", observedResult: "pass", exitCode: 0, source: "canonical-writer-execution" },
+  ]);
+  assert.equal(fold.get("npm run test:unit").observedResult, "pass");
+});
+
+test("a hook-observed fail is never buried by a writer-observed pass, in either order", () => {
+  for (const entries of [
+    [
+      { command: "npm run test:unit", observedResult: "fail", exitCode: 1, source: "postToolUse-capture" },
+      { command: "npm run test:unit", observedResult: "pass", exitCode: 0, source: "canonical-writer-execution" },
+    ],
+    [
+      { command: "npm run test:unit", observedResult: "pass", exitCode: 0, source: "canonical-writer-execution" },
+      { command: "npm run test:unit", observedResult: "fail", exitCode: 1, source: "postToolUse-capture" },
+    ],
+  ]) {
+    const fold = reduceCaptureLogByCommand(entries);
+    assert.equal(fold.get("npm run test:unit").observedResult, "fail");
+    // Review finding (#634): fail/0 would be contradictory evidence (isError:true, exitCode:0) —
+    // the exit code must travel with the winning status, never a losing entry's.
+    assert.equal(fold.get("npm run test:unit").exitCode, 1);
+  }
+});
+
+test("when both entries carry the winning status the newer non-null exit code wins", () => {
+  const sticky = reduceCaptureLogByCommand([
+    { command: "npm test", observedResult: "fail", exitCode: 2, source: "postToolUse-capture" },
+    { command: "npm test", observedResult: "fail", exitCode: null, source: "postToolUse-capture" },
+  ]);
+  assert.equal(sticky.get("npm test").exitCode, 2);
+  const newer = reduceCaptureLogByCommand([
+    { command: "npm test", observedResult: "fail", exitCode: 2, source: "postToolUse-capture" },
+    { command: "npm test", observedResult: "fail", exitCode: 3, source: "canonical-writer-execution" },
+  ]);
+  assert.equal(newer.get("npm test").exitCode, 3);
+});
+
+test("an ambiguous entry's null exit code never displaces the winning pass's code", () => {
+  const fold = reduceCaptureLogByCommand([
+    { command: "npm test", observedResult: "pass", exitCode: 0, source: "canonical-writer-execution" },
+    { command: "npm test", observedResult: "ambiguous", exitCode: null, source: "postToolUse-capture" },
+  ]);
+  assert.equal(fold.get("npm test").observedResult, "pass");
+  assert.equal(fold.get("npm test").exitCode, 0);
+});
+
+test("a writer-observed fail is sticky like any other observed fail", () => {
+  const fold = reduceCaptureLogByCommand([
+    { command: "npm run test:unit", observedResult: "fail", exitCode: 2, source: "canonical-writer-execution" },
+    { command: "npm run test:unit", observedResult: "ambiguous", exitCode: null, source: "postToolUse-capture" },
+  ]);
+  assert.equal(fold.get("npm run test:unit").observedResult, "fail");
+  assert.equal(fold.get("npm run test:unit").exitCode, 2);
+});

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

@@ -12,8 +12,11 @@
 // 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 fs from "node:fs";
+import path from "node:path";
 
-import { buildTrustBundle } from "../../build/src/cli/workflow-sidecar.js";
+import { WORKFLOW_ACCEPTANCE_STATUSES } from "../../build/src/cli/public-contracts.js";
+import { buildTrustBundle, validateTrustBundle } from "../../build/src/cli/workflow-sidecar.js";
 
 const TS = "2026-07-02T00:00:00Z";
 
@@ -85,3 +88,133 @@ test("buildTrustBundle: same-kind checks with different command-presence get DIS
   assert.equal(statuses[cmdClaim.id], "verified");
   assert.equal(statuses[noCmdClaim.id], "verified");
 });
+
+test("workflow acceptance status contract stays aligned with the artifact schema", () => {
+  const schema = JSON.parse(fs.readFileSync(path.join(process.cwd(), "schemas", "workflow-acceptance.schema.json"), "utf8"));
+  assert.deepEqual(schema.properties.criteria.items.properties.status.enum, [...WORKFLOW_ACCEPTANCE_STATUSES]);
+});
+
+test("buildTrustBundle: malformed acceptance statuses remain pending and keep invariant identity at the plan step", async () => {
+  const flowAgentsDir = path.join(process.cwd(), ".kontourai", "flow-agents");
+  const malformedStatuses = [undefined, null, "", "PASS", " pass ", true, false, 0, 1, {}, [], "verified", "unknown"];
+  for (const [index, status] of malformedStatuses.entries()) {
+    const criterion = { id: `ac-malformed-${index}`, description: "The implementation satisfies the requested behavior" };
+    if (status !== undefined) criterion.status = status;
+    const bundle = await buildTrustBundle(
+      "acceptance-integrity",
+      TS,
+      [],
+      [criterion],
+      [],
+      undefined,
+      flowAgentsDir,
+      undefined,
+      { flowId: "builder.build", stepId: "plan" },
+    );
+    assert.ok(bundle, "buildTrustBundle returned null (is @kontourai/surface installed?)");
+
+    const claim = bundle.claims.find((candidate) => candidate.metadata?.origin === "acceptance");
+    assert.ok(claim, "expected an acceptance criterion claim");
+    assert.equal(claim.claimType, "workflow.acceptance.criterion");
+    assert.equal(claim.subjectType, "flow-step");
+    assert.equal(claim.value, "pending");
+    assert.equal(claim.status, "proposed");
+    assert.equal(claim.metadata.criterion.status, "pending");
+    assert.equal(bundle.events.filter((event) => event.claimId === claim.id).length, 0);
+    assert.deepEqual(await validateTrustBundle(bundle), { valid: true, errors: [], available: true });
+  }
+});
+
+test("buildTrustBundle: evidence-free acceptance pass cannot manufacture verified trust", async () => {
+  const bundle = await buildTrustBundle(
+    "acceptance-no-evidence",
+    TS,
+    [],
+    [{ id: "ac-no-evidence", description: "The behavior is complete", status: "pass", evidence_refs: [] }],
+    [],
+  );
+  assert.ok(bundle, "buildTrustBundle returned null (is @kontourai/surface installed?)");
+  const claim = bundle.claims.find((candidate) => candidate.metadata?.origin === "acceptance");
+  assert.ok(claim, "expected an acceptance criterion claim");
+  assert.equal(claim.value, "pending");
+  assert.equal(claim.status, "proposed");
+  assert.equal(bundle.events.filter((event) => event.claimId === claim.id).length, 0);
+});
+
+test("buildTrustBundle: pass metadata without observed execution remains pending", async () => {
+  const bundle = await buildTrustBundle(
+    "acceptance-forged-provenance",
+    TS,
+    [],
+    [{
+      id: "ac-forged",
+      description: "The behavior is complete",
+      status: "pass",
+      evidence_refs: [{ kind: "command", excerpt: "npm test", summary: "Claimed test command." }],
+      identity_version: 2,
+      verified_at: TS,
+      _observed_commands: [{
+        command: "npm test",
+        exit_code: 0,
+        output_sha256: "0".repeat(64),
+        test_count: 1,
+        execution_proof: { kind: "local-process-exit", runner: "npm", static_test_units: 1 },
+      }],
+    }],
+    [],
+  );
+  assert.ok(bundle, "buildTrustBundle returned null (is @kontourai/surface installed?)");
+  const claim = bundle.claims.find((candidate) => candidate.metadata?.origin === "acceptance");
+  assert.ok(claim, "expected an acceptance criterion claim");
+  assert.equal(claim.value, "pending");
+  assert.equal(claim.status, "proposed");
+  assert.equal(bundle.evidence.filter((evidence) => evidence.claimId === claim.id).length, 0);
+  assert.equal(bundle.events.filter((event) => event.claimId === claim.id).length, 0);
+});
+
+test("buildTrustBundle: direct observed-command metadata cannot manufacture verified trust", async () => {
+  const flowAgentsDir = path.join(process.cwd(), ".kontourai", "flow-agents");
+  const criterion = {
+    id: "ac-stable",
+    description: "The accepted behavior remains independently verified",
+    status: "pass",
+    evidence_refs: [{ kind: "command", excerpt: "npm test", summary: "The observed test command passed." }],
+    identity_version: 2,
+    verified_at: TS,
+    _observed_commands: [{
+      command: "npm test",
+      exit_code: 0,
+      output_sha256: "0".repeat(64),
+      test_count: 1,
+      execution_proof: { kind: "local-process-exit", runner: "npm", static_test_units: 1 },
+    }],
+  };
+  const bundles = await Promise.all(["plan", "verify"].map((stepId) => buildTrustBundle(
+    "acceptance-stability",
+    TS,
+    [],
+    [criterion],
+    [],
+    undefined,
+    flowAgentsDir,
+    undefined,
+    { flowId: "builder.build", stepId },
+  )));
+
+  const claimIds = [];
+  for (const bundle of bundles) {
+    assert.ok(bundle, "buildTrustBundle returned null (is @kontourai/surface installed?)");
+    const claim = bundle.claims.find((candidate) => candidate.metadata?.origin === "acceptance");
+    assert.ok(claim, "expected an acceptance criterion claim");
+    assert.equal(claim.claimType, "workflow.acceptance.criterion");
+    assert.equal(claim.subjectType, "flow-step");
+    assert.equal(claim.value, "pending");
+    assert.equal(claim.status, "proposed");
+    const evidence = bundle.evidence.filter((candidate) => candidate.claimId === claim.id);
+    assert.equal(evidence.length, 0);
+    const event = bundle.events.find((candidate) => candidate.claimId === claim.id);
+    assert.equal(event, undefined);
+    claimIds.push(claim.id);
+  }
+  assert.equal(new Set(claimIds).size, 1, "acceptance claim identity changed across Builder gates");
+});

package/src/cli/validate-waves.test.mjs

@@ -0,0 +1,134 @@
+// Unit tests for waves.json wave-manifest reconciliation validation (#663 slice 1).
+//
+// validate-workflow-artifacts.ts is a CLI script (no exported helpers), so these
+// node:test units drive the built validator as a child process against temp fixture
+// directories — the same black-box surface CI's workflow-artifact-integration lane
+// uses, but fast and countable as unit executions. They pin the load-bearing
+// behavior of the reconcile-against-manifest contract:
+//   - a reconciled wave with an explicit not_reported worker is VALID DATA
+//     ("2 of 3 reported; worker-3 not_reported") — visibility, not a block;
+//   - a silent drop (complete claim over a missing worker record) FAILS with
+//     messages naming the dropped worker, the count mismatch, and the impossible
+//     complete claim.
+//
+// Run: `node --test src/cli/validate-waves.test.mjs` (requires `npm run build`).
+import test from "node:test";
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+const validator = path.join(repoRoot, "build", "src", "cli", "validate-workflow-artifacts.js");
+
+function runValidator(wavesPayload) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "waves-unit-"));
+  try {
+    fs.writeFileSync(path.join(dir, "waves.json"), JSON.stringify(wavesPayload, null, 2));
+    const result = spawnSync(process.execPath, [validator, dir], { encoding: "utf8" });
+    return { status: result.status, output: `${result.stdout}\n${result.stderr}` };
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+function manifest(waveOverrides) {
+  return {
+    schema_version: "1.0",
+    task_slug: "waves-unit",
+    waves: [
+      {
+        wave_id: "execute-wave-1",
+        step: "execute",
+        declared_at: "2026-07-16T00:00:00Z",
+        expected_workers: [
+          { worker_id: "worker-1", task: "task one" },
+          { worker_id: "worker-2", task: "task two" },
+          { worker_id: "worker-3", task: "task three" },
+        ],
+        ...waveOverrides,
+      },
+    ],
+  };
+}
+
+test("fully reported wave reconciles complete and validates", () => {
+  const { status, output } = runValidator(manifest({
+    worker_results: [
+      { worker_id: "worker-1", status: "completed", summary: "done", recorded_at: "2026-07-16T01:00:00Z" },
+      { worker_id: "worker-2", status: "failed", summary: "tests failing", recorded_at: "2026-07-16T01:00:00Z" },
+      { worker_id: "worker-3", status: "blocked", summary: "blocked on approval", recorded_at: "2026-07-16T01:00:00Z" },
+    ],
+    reconciliation: {
+      status: "complete",
+      expected_count: 3,
+      reported_count: 3,
+      summary: "3 of 3 reported; no workers not_reported",
+      reconciled_at: "2026-07-16T01:05:00Z",
+    },
+  }));
+  assert.equal(status, 0, output);
+});
+
+test("2 of 3 reported with explicit not_reported worker is valid data, not a block", () => {
+  const { status, output } = runValidator(manifest({
+    worker_results: [
+      { worker_id: "worker-1", status: "completed", summary: "done", recorded_at: "2026-07-16T01:00:00Z" },
+      { worker_id: "worker-2", status: "completed", summary: "done", recorded_at: "2026-07-16T01:00:00Z" },
+      { worker_id: "worker-3", status: "not_reported", summary: "no terminal report by wave close; routed to re-dispatch", recorded_at: "2026-07-16T01:05:00Z" },
+    ],
+    reconciliation: {
+      status: "incomplete",
+      expected_count: 3,
+      reported_count: 2,
+      summary: "2 of 3 reported; worker-3 not_reported",
+      reconciled_at: "2026-07-16T01:05:00Z",
+    },
+  }));
+  assert.equal(status, 0, output);
+});
+
+test("silent drop behind a complete claim fails naming the missing worker", () => {
+  const { status, output } = runValidator(manifest({
+    worker_results: [
+      { worker_id: "worker-1", status: "completed", summary: "done", recorded_at: "2026-07-16T01:00:00Z" },
+      { worker_id: "worker-2", status: "completed", summary: "done", recorded_at: "2026-07-16T01:00:00Z" },
+    ],
+    reconciliation: {
+      status: "complete",
+      expected_count: 3,
+      reported_count: 3,
+      summary: "3 of 3 reported",
+      reconciled_at: "2026-07-16T01:05:00Z",
+    },
+  }));
+  assert.equal(status, 1);
+  assert.match(output, /worker worker-3 has no terminal status record/);
+  assert.match(output, /reported_count is 3 but 2 of 3 expected workers/);
+  assert.match(output, /complete requires every expected worker/);
+});
+
+test("duplicate terminal records and undeclared reporters are rejected", () => {
+  const { status, output } = runValidator(manifest({
+    worker_results: [
+      { worker_id: "worker-1", status: "completed", summary: "done", recorded_at: "2026-07-16T01:00:00Z" },
+      { worker_id: "worker-1", status: "failed", summary: "again", recorded_at: "2026-07-16T01:01:00Z" },
+      { worker_id: "worker-9", status: "completed", summary: "surprise", recorded_at: "2026-07-16T01:00:00Z" },
+    ],
+  }));
+  assert.equal(status, 1);
+  assert.match(output, /more than one terminal status record for worker worker-1/);
+  assert.match(output, /worker worker-9 that is not declared in expected_workers/);
+});
+
+test("unknown terminal status fails against the schema enum", () => {
+  const { status, output } = runValidator(manifest({
+    worker_results: [
+      { worker_id: "worker-1", status: "maybe-done", summary: "unclear", recorded_at: "2026-07-16T01:00:00Z" },
+    ],
+  }));
+  assert.equal(status, 1);
+  assert.match(output, /status must be one of: completed, failed, blocked, not_reported/);
+});

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

@@ -21,6 +21,7 @@ const sidecarSchemas: Record<string, string> = {
   "critique.json": "schemas/workflow-critique.schema.json",
   "release.json": "schemas/workflow-release.schema.json",
   "learning.json": "schemas/workflow-learning.schema.json",
+  "waves.json": "schemas/workflow-waves.schema.json",
 };
 // Runtime coordination records live below a session but are not workflow
 // sidecars. Recursing into them would validate continuation-driver/state.json
@@ -321,12 +322,58 @@ function validateSidecar(file: string): { issues: Issue[]; warnings: 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" });
     }
   }
+  if (path.basename(file) === "waves.json") {
+    validateWaves(file, value, 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 };
 }
 
+// #663 slice 1: wave-result reconciliation is machine-checkable, not prose. The schema
+// (schemas/workflow-waves.schema.json) validates the shape; these semantic checks enforce the
+// cross-record arithmetic the mini schema engine cannot express: exactly one terminal status
+// record per declared worker, no undeclared reporters, reconciliation counts that match the
+// records, and a `complete` claim that is impossible while any expected worker lacks a
+// worker-landed terminal status. Missing workers must be recorded explicitly as not_reported —
+// a reconciled wave never silently absorbs a dropped worker. Enforcement here is data-level
+// validation only; stop-hook refusal of wave completion is #663 part 3 (slice 2).
+function validateWaves(file: string, value: any, issues: Issue[]): void {
+  const waves = Array.isArray(value?.waves) ? value.waves : [];
+  waves.forEach((wave: any, index: number) => {
+    const loc = `waves.json.waves[${index}]`;
+    const expected: any[] = Array.isArray(wave?.expected_workers) ? wave.expected_workers : [];
+    const results: any[] = Array.isArray(wave?.worker_results) ? wave.worker_results : [];
+    const expectedIds = expected.map((w) => w?.worker_id).filter((id) => typeof id === "string" && id.length > 0);
+    const expectedIdSet = new Set(expectedIds);
+    if (expectedIdSet.size !== expectedIds.length) issues.push({ path: file, message: `${loc}.expected_workers must declare unique worker_id values` });
+    const resultIds = results.map((r) => r?.worker_id).filter((id) => typeof id === "string" && id.length > 0);
+    const seen = new Set<string>();
+    for (const id of resultIds) {
+      if (seen.has(id)) issues.push({ path: file, message: `${loc}.worker_results has more than one terminal status record for worker ${id}; each worker lands exactly one` });
+      seen.add(id);
+      if (!expectedIdSet.has(id)) issues.push({ path: file, message: `${loc}.worker_results records worker ${id} that is not declared in expected_workers; declare every worker in the manifest before dispatch` });
+    }
+    const reconciliation = wave?.reconciliation;
+    if (!reconciliation || typeof reconciliation !== "object" || Array.isArray(reconciliation)) return;
+    const expectedCount = expectedIds.length;
+    const reportedIds = new Set(results.filter((r) => ["completed", "failed", "blocked"].includes(r?.status) && expectedIdSet.has(r?.worker_id)).map((r) => r.worker_id as string));
+    const reportedCount = reportedIds.size;
+    if (reconciliation.expected_count !== expectedCount) issues.push({ path: file, message: `${loc}.reconciliation.expected_count is ${reconciliation.expected_count} but expected_workers declares ${expectedCount}` });
+    if (reconciliation.reported_count !== reportedCount) issues.push({ path: file, message: `${loc}.reconciliation.reported_count is ${reconciliation.reported_count} but ${reportedCount} of ${expectedCount} expected workers have a worker-landed terminal status (completed|failed|blocked)` });
+    const missing = expectedIds.filter((id) => !results.some((r) => r?.worker_id === id));
+    for (const id of missing) issues.push({ path: file, message: `${loc} is reconciled but worker ${id} has no terminal status record; record it explicitly as not_reported — never silently absorb a missing worker` });
+    const notReported = results.filter((r) => r?.status === "not_reported" && expectedIdSet.has(r?.worker_id));
+    if (reconciliation.status === "complete" && (missing.length > 0 || notReported.length > 0 || reportedCount !== expectedCount)) {
+      issues.push({ path: file, message: `${loc}.reconciliation.status complete requires every expected worker to have a worker-landed terminal status; got ${reportedCount} of ${expectedCount} reported` });
+    }
+    if (reconciliation.status === "incomplete" && missing.length === 0 && notReported.length === 0 && reportedCount === expectedCount) {
+      issues.push({ path: file, message: `${loc}.reconciliation.status incomplete contradicts the records: all ${expectedCount} expected workers reported` });
+    }
+  });
+}
+
 function validateLearningCorrections(file: string, status: unknown, records: any[], issues: Issue[]): void {
   records.forEach((record, index) => {
     const correction = record?.correction;