@kontourai/flow-agents 3.12.1 → 4.1.0

package/dist/opencode/evals/integration/test_workflow_artifacts.sh

@@ -1271,6 +1271,263 @@ else
   _fail "extra criteria failure did not mention criteria mismatch"
 fi
 
+# --- waves.json (#663 slice 1): wave manifest + reconcile-against-manifest as data ---------
+# The manifest is additive: every earlier fixture directory in this file has no waves.json and
+# still validates — that is the "absent file changes nothing" half of AC1.
+
+GOOD_WAVES="$TMPDIR_EVAL/good-waves"
+mkdir -p "$GOOD_WAVES"
+cat > "$GOOD_WAVES/waves.json" <<'JSON'
+{
+  "schema_version": "1.0",
+  "task_slug": "good-waves",
+  "waves": [
+    {
+      "wave_id": "execute-wave-1",
+      "step": "execute",
+      "declared_at": "2026-07-16T00:00:00Z",
+      "expected_workers": [
+        {"worker_id": "worker-1", "task": "implement module a", "owned_files": ["src/a.ts"]},
+        {"worker_id": "worker-2", "task": "implement module b"}
+      ],
+      "worker_results": [
+        {"worker_id": "worker-1", "status": "completed", "summary": "module a implemented", "recorded_at": "2026-07-16T01:00:00Z"},
+        {"worker_id": "worker-2", "status": "failed", "summary": "module b tests failing", "recorded_at": "2026-07-16T01:00:00Z"}
+      ],
+      "reconciliation": {
+        "status": "complete",
+        "expected_count": 2,
+        "reported_count": 2,
+        "summary": "2 of 2 reported; no workers not_reported",
+        "reconciled_at": "2026-07-16T01:05:00Z"
+      }
+    }
+  ]
+}
+JSON
+
+if flow_agents_node "$VALIDATOR" "$GOOD_WAVES" >"$TMPDIR_EVAL/good-waves.out" 2>&1; then
+  _pass "fully reported wave manifest passes (2 of 2 reported)"
+else
+  _fail "fully reported wave manifest should pass: $(cat "$TMPDIR_EVAL/good-waves.out")"
+fi
+
+# Scenario (issue #663 AC): 3 workers expected, one never lands a terminal record. The
+# reconciled manifest records worker-3 explicitly as not_reported with "2 of 3 reported" —
+# and that is VALID DATA (exit 0), not a hook block: slice 1 makes the drop visible, slice 2
+# (stop-goal-fit) decides whether to refuse. Silent absorption is what must fail, below.
+SCENARIO_WAVES="$TMPDIR_EVAL/scenario-waves"
+mkdir -p "$SCENARIO_WAVES"
+cat > "$SCENARIO_WAVES/waves.json" <<'JSON'
+{
+  "schema_version": "1.0",
+  "task_slug": "scenario-waves",
+  "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"}
+      ],
+      "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 received 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"
+      }
+    }
+  ]
+}
+JSON
+
+if flow_agents_node "$VALIDATOR" "$SCENARIO_WAVES" >"$TMPDIR_EVAL/scenario-waves.out" 2>&1; then
+  _pass "2-of-3 scenario with explicit not_reported worker validates as data (no silent drop, no block)"
+else
+  _fail "2-of-3 not_reported scenario should validate as data: $(cat "$TMPDIR_EVAL/scenario-waves.out")"
+fi
+
+# Silent drop: reconciliation claims complete 3-of-3 while worker-3 has NO terminal record.
+mkdir -p "$BAD/waves-silent-drop"
+cat > "$BAD/waves-silent-drop/waves.json" <<'JSON'
+{
+  "schema_version": "1.0",
+  "task_slug": "waves-silent-drop",
+  "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"}
+      ],
+      "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"
+      }
+    }
+  ]
+}
+JSON
+
+if flow_agents_node "$VALIDATOR" "$BAD/waves-silent-drop" >"$TMPDIR_EVAL/waves-silent-drop.out" 2>&1; then
+  _fail "silently dropped worker behind a complete claim should fail"
+elif rg -q 'worker worker-3 has no terminal status record' "$TMPDIR_EVAL/waves-silent-drop.out" \
+  && rg -q 'reported_count is 3 but 2 of 3 expected workers' "$TMPDIR_EVAL/waves-silent-drop.out" \
+  && rg -q 'complete requires every expected worker' "$TMPDIR_EVAL/waves-silent-drop.out"; then
+  _pass "silently dropped worker fails with missing-record, count, and impossible-complete messages"
+else
+  _fail "silent-drop failure did not name the dropped worker and count mismatch: $(cat "$TMPDIR_EVAL/waves-silent-drop.out")"
+fi
+
+# A complete claim over an explicitly not_reported worker is still impossible.
+mkdir -p "$BAD/waves-complete-not-reported"
+cat > "$BAD/waves-complete-not-reported/waves.json" <<'JSON'
+{
+  "schema_version": "1.0",
+  "task_slug": "waves-complete-not-reported",
+  "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_results": [
+        {"worker_id": "worker-1", "status": "completed", "summary": "done", "recorded_at": "2026-07-16T01:00:00Z"},
+        {"worker_id": "worker-2", "status": "not_reported", "summary": "never reported", "recorded_at": "2026-07-16T01:05:00Z"}
+      ],
+      "reconciliation": {
+        "status": "complete",
+        "expected_count": 2,
+        "reported_count": 1,
+        "summary": "1 of 2 reported; worker-2 not_reported",
+        "reconciled_at": "2026-07-16T01:05:00Z"
+      }
+    }
+  ]
+}
+JSON
+
+if flow_agents_node "$VALIDATOR" "$BAD/waves-complete-not-reported" >"$TMPDIR_EVAL/waves-complete-not-reported.out" 2>&1; then
+  _fail "complete claim over a not_reported worker should fail"
+elif rg -q 'complete requires every expected worker' "$TMPDIR_EVAL/waves-complete-not-reported.out"; then
+  _pass "complete claim over a not_reported worker fails with actionable message"
+else
+  _fail "complete-over-not_reported failure did not mention the complete rule: $(cat "$TMPDIR_EVAL/waves-complete-not-reported.out")"
+fi
+
+# Exactly one terminal record per worker.
+mkdir -p "$BAD/waves-duplicate-record"
+cat > "$BAD/waves-duplicate-record/waves.json" <<'JSON'
+{
+  "schema_version": "1.0",
+  "task_slug": "waves-duplicate-record",
+  "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_results": [
+        {"worker_id": "worker-1", "status": "completed", "summary": "done", "recorded_at": "2026-07-16T01:00:00Z"},
+        {"worker_id": "worker-1", "status": "failed", "summary": "also failed?", "recorded_at": "2026-07-16T01:01:00Z"}
+      ]
+    }
+  ]
+}
+JSON
+
+if flow_agents_node "$VALIDATOR" "$BAD/waves-duplicate-record" >"$TMPDIR_EVAL/waves-duplicate-record.out" 2>&1; then
+  _fail "duplicate terminal record should fail"
+elif rg -q 'more than one terminal status record for worker worker-1' "$TMPDIR_EVAL/waves-duplicate-record.out"; then
+  _pass "duplicate terminal record fails with actionable message"
+else
+  _fail "duplicate-record failure did not name the worker: $(cat "$TMPDIR_EVAL/waves-duplicate-record.out")"
+fi
+
+# Every reporter must be declared in the manifest before dispatch.
+mkdir -p "$BAD/waves-undeclared-reporter"
+cat > "$BAD/waves-undeclared-reporter/waves.json" <<'JSON'
+{
+  "schema_version": "1.0",
+  "task_slug": "waves-undeclared-reporter",
+  "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_results": [
+        {"worker_id": "worker-1", "status": "completed", "summary": "done", "recorded_at": "2026-07-16T01:00:00Z"},
+        {"worker_id": "worker-9", "status": "completed", "summary": "surprise", "recorded_at": "2026-07-16T01:00:00Z"}
+      ]
+    }
+  ]
+}
+JSON
+
+if flow_agents_node "$VALIDATOR" "$BAD/waves-undeclared-reporter" >"$TMPDIR_EVAL/waves-undeclared-reporter.out" 2>&1; then
+  _fail "undeclared reporter should fail"
+elif rg -q 'worker worker-9 that is not declared in expected_workers' "$TMPDIR_EVAL/waves-undeclared-reporter.out"; then
+  _pass "undeclared reporter fails with actionable message"
+else
+  _fail "undeclared-reporter failure did not name the worker: $(cat "$TMPDIR_EVAL/waves-undeclared-reporter.out")"
+fi
+
+# Terminal status vocabulary is schema-enforced.
+mkdir -p "$BAD/waves-bad-status"
+cat > "$BAD/waves-bad-status/waves.json" <<'JSON'
+{
+  "schema_version": "1.0",
+  "task_slug": "waves-bad-status",
+  "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_results": [
+        {"worker_id": "worker-1", "status": "maybe-done", "summary": "unclear", "recorded_at": "2026-07-16T01:00:00Z"}
+      ]
+    }
+  ]
+}
+JSON
+
+if flow_agents_node "$VALIDATOR" "$BAD/waves-bad-status" >"$TMPDIR_EVAL/waves-bad-status.out" 2>&1; then
+  _fail "unknown worker status should fail"
+elif rg -q 'status must be one of: completed, failed, blocked, not_reported' "$TMPDIR_EVAL/waves-bad-status.out"; then
+  _pass "unknown worker status fails against the schema enum"
+else
+  _fail "bad-status failure did not mention the status enum: $(cat "$TMPDIR_EVAL/waves-bad-status.out")"
+fi
+
 if [[ "$errors" -eq 0 ]]; then
   echo "Workflow artifact integration passed."
   exit 0

package/dist/opencode/evals/integration/test_workflow_sidecar_writer.sh

@@ -3573,6 +3573,61 @@ else
   _fail "compose: record-gate-claim (selected-work) failed: $(cat "$TMPDIR_EVAL/compose-gate1.out" "$TMPDIR_EVAL/compose-gate1.err")"
 fi
 
+# ─── #634: writer-observed execution — die-before-append + append-on-success ────────────────
+# A rejected expected-status mismatch must leave command-log.jsonl untouched (no writer
+# observation may exist for a claim that was refused); a successful gate claim with
+# --command must append a chain-linked canonical-writer-execution observation.
+CMDLOG_634="$COMPOSE_DIR/command-log.jsonl"
+CMDLOG_634_BEFORE=""
+[[ -f "$CMDLOG_634" ]] && CMDLOG_634_BEFORE="$(shasum -a 256 "$CMDLOG_634" | cut -d' ' -f1)"
+if flow_agents_node "$WRITER" record-gate-claim "$COMPOSE_DIR" \
+  --actor compose-actor \
+  --status pass \
+  --summary "634 mismatch: claiming pass while the command fails must die before any append" \
+  --command "test -f .kontourai/flow-agents/compose-270/definitely-not-a-real-file-634" \
+  --evidence-ref-json '{"kind":"artifact","file":".kontourai/flow-agents/compose-270/compose-270--pull-work.md","summary":"634 mismatch fixture."}' \
+  --timestamp "2026-07-14T15:00:00Z" >"$TMPDIR_EVAL/wo-mismatch.out" 2>"$TMPDIR_EVAL/wo-mismatch.err"; then
+  _fail "#634: record-gate-claim accepted a passing claim for a failing command"
+else
+  if grep -q "failed (exit" "$TMPDIR_EVAL/wo-mismatch.err"; then
+    _pass "#634: expected-status mismatch dies with the exit-code diagnostic"
+  else
+    _fail "#634: mismatch died with an unexpected diagnostic: $(cat "$TMPDIR_EVAL/wo-mismatch.err")"
+  fi
+fi
+CMDLOG_634_AFTER=""
+[[ -f "$CMDLOG_634" ]] && CMDLOG_634_AFTER="$(shasum -a 256 "$CMDLOG_634" | cut -d' ' -f1)"
+if [[ "$CMDLOG_634_BEFORE" == "$CMDLOG_634_AFTER" ]]; then
+  _pass "#634: rejected mismatch left command-log.jsonl byte-identical (die-before-append)"
+else
+  _fail "#634: rejected mismatch modified command-log.jsonl"
+fi
+
+if flow_agents_node "$WRITER" record-gate-claim "$COMPOSE_DIR" \
+  --actor compose-actor \
+  --status pass \
+  --summary "634 success: writer observation must append on a genuinely passing command" \
+  --command "test -f .kontourai/flow-agents/compose-270/compose-270--pull-work.md" \
+  --evidence-ref-json '{"kind":"artifact","file":".kontourai/flow-agents/compose-270/compose-270--pull-work.md","summary":"634 success fixture."}' \
+  --timestamp "2026-07-14T15:01:00Z" >"$TMPDIR_EVAL/wo-success.out" 2>"$TMPDIR_EVAL/wo-success.err"; then
+  if [[ -f "$CMDLOG_634" ]] && node -e "
+    const fs = require('fs');
+    const entries = fs.readFileSync(process.argv[1], 'utf8').split('\n').filter(Boolean).map(JSON.parse);
+    const writer = entries.filter((e) => e.source === 'canonical-writer-execution');
+    if (writer.length === 0) process.exit(1);
+    const last = writer[writer.length - 1];
+    if (last.observedResult !== 'pass' || last.exitCode !== 0) process.exit(1);
+    if (!last._chain || typeof last._chain.hash !== 'string') process.exit(1);
+  " "$CMDLOG_634"; then
+    _pass "#634: successful gate claim appended a chain-linked canonical-writer-execution pass"
+  else
+    _fail "#634: no chain-linked writer observation found after a successful gate claim"
+  fi
+else
+  _fail "#634: success-path record-gate-claim failed: $(cat "$TMPDIR_EVAL/wo-success.err")"
+fi
+
+
 if node --input-type=module <<NODEOF 2>"$TMPDIR_EVAL/compose-gate1-assert.err"
 import { readFileSync } from 'node:fs';
 const bundle = JSON.parse(readFileSync('${COMPOSE_DIR}/trust.bundle', 'utf8'));
@@ -3863,6 +3918,14 @@ const bundle = JSON.parse(fs.readFileSync(bundleFile, 'utf8'));
 const gate = bundle.claims.find((claim) => claim.metadata?.gate_claim?.expectation_id === 'tests-evidence');
 const review = bundle.claims.find((claim) => claim.metadata?.origin === 'critique');
 if (!gate || gate.metadata?.observed_commands?.length !== 2) process.exit(2);
+const criteria = bundle.claims.filter((claim) => claim.metadata?.origin === 'acceptance');
+if (criteria.length !== 2 || criteria.some((claim) => claim.value !== 'pass' || claim.status !== 'verified')) process.exit(4);
+for (const claim of criteria) {
+  const evidence = bundle.evidence.filter((item) => item.claimId === claim.id);
+  const event = bundle.events.find((item) => item.claimId === claim.id && item.status === 'verified');
+  if (evidence.length !== 1 || evidence[0].evidenceType !== 'test_output' || evidence[0].passing !== true) process.exit(5);
+  if (!event || event.evidenceIds.length !== 1 || event.evidenceIds[0] !== evidence[0].id) process.exit(6);
+}
 const snapshot = review?.metadata?.review_target?.workspace_snapshot;
 if (!snapshot || snapshot.version !== 1 || snapshot.algorithm !== 'sha256' || typeof snapshot.digest !== 'string') process.exit(3);
 NODE
@@ -3875,6 +3938,54 @@ else
   _fail "tests-evidence multi-command write failed: $(cat "$TMPDIR_EVAL/multi-pass.out" "$TMPDIR_EVAL/multi-pass.err")"
 fi
 
+if flow_agents_node "$WRITER" record-evidence "$MULTI_DIR" \
+  --verdict not_verified \
+  --check-json '{"id":"acceptance-rebuild-probe","kind":"external","status":"not_verified","summary":"Trigger a valid unrelated bundle rebuild."}' \
+  --timestamp "2026-07-11T11:00:35Z" >"$TMPDIR_EVAL/multi-rebuild.out" 2>"$TMPDIR_EVAL/multi-rebuild.err" \
+  && node - "$MULTI_DIR/trust.bundle" <<'NODE'
+const fs = require('node:fs');
+const bundle = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
+const criteria = bundle.claims.filter((claim) => claim.metadata?.origin === 'acceptance');
+if (criteria.length !== 2 || criteria.some((claim) => claim.value !== 'pass' || claim.status !== 'verified')) process.exit(1);
+for (const claim of criteria) {
+  if (claim.createdAt !== '2026-07-11T11:00:30Z' || claim.updatedAt !== '2026-07-11T11:00:30Z') process.exit(2);
+  const event = bundle.events.find((item) => item.claimId === claim.id);
+  if (event?.createdAt !== '2026-07-11T11:00:30Z' || event?.verifiedAt !== '2026-07-11T11:00:30Z') process.exit(3);
+}
+NODE
+then
+  _pass "verified acceptance provenance survives an unrelated rebuild without timestamp laundering"
+else
+  _fail "unrelated rebuild regressed or refreshed verified acceptance provenance: $(cat "$TMPDIR_EVAL/multi-rebuild.out" "$TMPDIR_EVAL/multi-rebuild.err")"
+fi
+
+# A direct acceptance artifact edit cannot replace or erase the durable criterion contract on a
+# later, unrelated bundle write. This reproduces the issue #601 artifact-only erasure vector.
+node - "$MULTI_DIR/acceptance.json" <<'NODE'
+const fs = require('node:fs');
+const file = process.argv[2];
+const acceptance = JSON.parse(fs.readFileSync(file, 'utf8'));
+acceptance.criteria = [{ id: null, description: 'Attempted replacement', status: 'PASS' }];
+fs.writeFileSync(file, JSON.stringify(acceptance, null, 2) + '\n');
+NODE
+if flow_agents_node "$WRITER" record-evidence "$MULTI_DIR" \
+  --verdict not_verified \
+  --check-json '{"id":"acceptance-erasure-probe","kind":"external","status":"not_verified","summary":"Trigger an unrelated bundle rebuild."}' \
+  --timestamp "2026-07-11T11:00:40Z" >"$TMPDIR_EVAL/multi-erasure.out" 2>"$TMPDIR_EVAL/multi-erasure.err"; then
+  _fail "malformed acceptance artifact was accepted during an unrelated bundle rebuild"
+elif node - "$MULTI_DIR/trust.bundle" <<'NODE'
+const fs = require('node:fs');
+const bundle = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
+const criteria = bundle.claims.filter((claim) => claim.metadata?.origin === 'acceptance');
+if (criteria.length !== 2) process.exit(1);
+if (criteria.some((claim) => claim.value !== 'pass' || claim.status !== 'verified')) process.exit(2);
+NODE
+then
+  _pass "malformed acceptance replacement fails closed without erasing durable criteria"
+else
+  _fail "rejected acceptance replacement still erased or regressed durable criteria: $(cat "$TMPDIR_EVAL/multi-erasure.out" "$TMPDIR_EVAL/multi-erasure.err")"
+fi
+
 # ─── AC4: compose-three-writer (five writer calls total: evidence x2, gate-claim x2, critique, ──
 # then record-learning) — all claim families present and correctly typed in the final bundle ──
 if flow_agents_node "$WRITER" record-learning "$COMPOSE_DIR" \
@@ -5036,8 +5147,6 @@ else
   _fail "mutation-test setup: could not locate the compiled build/src/cli/workflow-sidecar.js to mutate (ran 'npm run build' first?)"
 fi
 
-
-
 if [[ "$errors" -eq 0 ]]; then
   echo "Workflow sidecar writer integration passed."
   exit 0

package/dist/opencode/evals/run.sh

@@ -177,6 +177,14 @@ run_integration() {
   echo ""
   bash "$EVAL_DIR/integration/test_telemetry_tool_usage.sh" || result=1
   echo ""
+  bash "$EVAL_DIR/integration/test_telemetry_tool_outcome.sh" || result=1
+  echo ""
+  bash "$EVAL_DIR/integration/test_telemetry_delegation.sh" || result=1
+  echo ""
+  bash "$EVAL_DIR/integration/test_telemetry_action_class.sh" || result=1
+  echo ""
+  bash "$EVAL_DIR/integration/test_telemetry_sanitize_usage.sh" || result=1
+  echo ""
   bash "$EVAL_DIR/integration/test_telemetry_doctor.sh" || result=1
   echo ""
   bash "$EVAL_DIR/integration/test_usage_feedback_outcomes.sh" || result=1
@@ -308,6 +316,10 @@ run_integration() {
   echo ""
   bash "$EVAL_DIR/integration/test_command_log_integrity.sh" || result=1
   echo ""
+  bash "$EVAL_DIR/integration/test_narrative_source_contract.sh" || result=1
+  echo ""
+  bash "$EVAL_DIR/integration/test_narrative_redaction_failclosed.sh" || result=1
+  echo ""
   bash "$EVAL_DIR/integration/test_gate_lockdown.sh" || result=1
   echo ""
   bash "$EVAL_DIR/integration/test_resolvefirststep_security.sh" || result=1

package/dist/opencode/evals/static/test_library_exports.sh

@@ -41,6 +41,11 @@ if [[ -f "build/src/index.js" && -f "build/src/index.d.ts" ]]; then
 else
   fail "build is missing index.js or index.d.ts (run npm run build)"
 fi
+if grep -q 'GateActionArtifactBinding' build/src/index.d.ts && grep -q 'GateActionArtifactTarget' build/src/index.d.ts; then
+  pass "package root exports the public gate-action artifact binding and target types"
+else
+  fail "build/src/index.d.ts is missing a public gate-action artifact type"
+fi
 
 # 3. importing the library does not run the CLI, and the public API is present.
 # If importing executed the CLI it would call process.exit before our marker prints.

package/dist/opencode/evals/static/test_package.sh

@@ -210,6 +210,12 @@ for (const gateId of ["verify-gate", "merge-ready-gate"]) {
   for (const [reason, target] of Object.entries(expected)) if (gate.on_route_back?.[reason] !== target) throw new Error(`${gateId} ${reason} should route to ${target}`);
   if (gate.route_back_policy?.on_exceeded !== "block") throw new Error(`${gateId} route_back_policy should block on exceeded attempts`);
 }
+// #695 item (a): pr-open must not be a one-way door — the composed publish-learn
+// pr-open-gate declares the missing_evidence repair route back to verify.
+const prOpenGate = publishLearn.gates?.["pr-open-gate"] || {};
+if (prOpenGate.on_route_back?.missing_evidence !== "verify") throw new Error("pr-open-gate missing_evidence should route to verify");
+if (prOpenGate.on_route_back?.default !== "verify") throw new Error("pr-open-gate default route-back should target verify");
+if (prOpenGate.route_back_policy?.on_exceeded !== "block") throw new Error("pr-open-gate route_back_policy should block on exceeded attempts");
 for (const stepId of ["pr-open", "merge-ready-ci", "learn"]) {
   const step = (flow.steps || []).find((item) => item.id === stepId);
   if (step?.uses_flow !== "builder.publish-learn") throw new Error(`${stepId} should compose builder.publish-learn`);

package/dist/opencode/evals/static/test_workflow_skills.sh

@@ -246,6 +246,19 @@ require_text "$PLANNING_CONTRACT" 'Stop-short risks' "planning contract defines
 require_text "$PLANNING_CONTRACT" 'Source Evidence / Permalinks' "planning contract requires source evidence permalink expectations"
 require_text "$EXECUTION_CONTRACT" 'Parallel Wave Rules' "execution contract defines parallel wave rules"
 require_text "$EXECUTION_CONTRACT" 'modified files are recorded' "execution contract requires modified files"
+require_text "$EXECUTION_CONTRACT" 'Wave Manifest And Reconciliation' "execution contract defines wave manifest reconciliation (#663)"
+require_text "$EXECUTION_CONTRACT" 'N of M reported' "execution contract requires explicit N-of-M reconciliation language"
+require_text "$EXECUTION_CONTRACT" 'not_reported' "execution contract records missing workers as not_reported"
+require_text "$EXECUTION_CONTRACT" 'never silently absorb' "execution contract forbids silently absorbing missing workers"
+require_text "$EXECUTE_PLAN" 'waves\.json' "execute-plan declares the wave manifest sidecar"
+require_text "$EXECUTE_PLAN" 'N of M reported' "execute-plan reconciles waves with explicit N-of-M language"
+require_text "$EXECUTE_PLAN" 'not_reported' "execute-plan records missing workers as not_reported"
+require_text "$EXECUTE_PLAN" 'reconcile results against the wave manifest' "execute-plan collect step is reconcile-against-manifest"
+require_text "$REVIEW_WORK" 'waves\.json' "review-work declares fan-out reviewer lanes in the wave manifest"
+require_text "$REVIEW_WORK" 'N of M reported' "review-work reconciles reviewer lanes with explicit N-of-M language"
+require_text "$REVIEW_WORK" 'not_reported' "review-work records missing reviewers as not_reported"
+test -f "$ROOT/schemas/workflow-waves.schema.json" && pass "workflow waves schema exists" || fail "workflow waves schema exists"
+require_text "$ROOT/src/cli/validate-workflow-artifacts.ts" 'waves\.json.*workflow-waves\.schema\.json' "validator registers waves.json against the waves schema"
 require_text "$ARTIFACT_LIFECYCLE_DOC" 'current-state dashboard' "artifact lifecycle defines local current-state role"
 require_text "$ARTIFACT_LIFECYCLE_DOC" 'Learning records are a routing surface' "artifact lifecycle defines learning routing semantics"
 require_text "$ARTIFACT_LIFECYCLE_DOC" '14-30 days' "artifact lifecycle documents local retention window"
@@ -776,6 +789,9 @@ require_text "$BUILDER_BUILD_FLOW" 'probe_status' "Builder build flow names prob
 require_text "$BUILDER_BUILD_FLOW" 'probe_artifact_ref' "Builder build flow names probe artifact ref"
 require_text "$BUILDER_BUILD_FLOW" 'Stale broad continuation language after a merge is not sufficient' "Builder build flow blocks stale broad continuation"
 require_text "$BUILDER_BUILD_FLOW" '"uses_flow": "builder.publish-learn"' "Builder build flow composes publish-learn extension"
+require_text "$BUILDER_PUBLISH_LEARN_FLOW" '"on_route_back"' "Builder publish-learn flow declares route-back mappings (#695 item a)"
+require_text "$BUILDER_PUBLISH_LEARN_FLOW" '"missing_evidence": "verify"' "Builder publish-learn pr-open-gate routes missing evidence to verify"
+require_text "$BUILDER_PUBLISH_LEARN_FLOW" '"route_back_policy"' "Builder publish-learn pr-open-gate declares a route-back policy"
 require_text "$BUILDER_PUBLISH_LEARN_FLOW" '"builder.pr-open.pull-request"' "Builder publish-learn flow exports PR-open evidence"
 require_text "$BUILDER_PUBLISH_LEARN_FLOW" '"builder.merge-ready-ci.readiness"' "Builder publish-learn flow exports CI merge readiness evidence"
 require_text "$BUILDER_PUBLISH_LEARN_FLOW" '"builder.learn.evidence"' "Builder publish-learn flow exports learning evidence"

package/dist/opencode/install.sh

@@ -72,7 +72,7 @@ if [[ ! -e "$DEST/AGENTS.md" && ! -L "$DEST/AGENTS.md" ]]; then
   rm -f "$instruction_tmp"
 fi
 if command -v node >/dev/null 2>&1; then
-  node "$DEST/scripts/install-merge.js" --config "$DEST/opencode.json" --managed-hooks "$SRC/opencode.json" --version "3.12.1" --install-record "$DEST/.flow-agents/install.json" --runtime "opencode" || true
+  node "$DEST/scripts/install-merge.js" --config "$DEST/opencode.json" --managed-hooks "$SRC/opencode.json" --version "4.1.0" --install-record "$DEST/.flow-agents/install.json" --runtime "opencode" || true
 fi
 if [[ ${#CONSOLE_CONFIG_ARGS[@]} -gt 0 || -n "${FLOW_AGENTS_TELEMETRY_SINK:-}" || -n "${FLOW_AGENTS_TELEMETRY_SINKS:-}" || -n "${FLOW_AGENTS_CONSOLE_URL:-}" || -n "${CONSOLE_TELEMETRY_URL:-}" || -n "${CONSOLE_URL:-}" || -n "${FLOW_AGENTS_CONSOLE_TOKEN_FILE:-}" || -n "${CONSOLE_TELEMETRY_TOKEN_FILE:-}" ]]; then
   bash "$DEST/scripts/telemetry/install-console-config.sh" "$DEST/scripts/telemetry/telemetry.conf" "${CONSOLE_CONFIG_ARGS[@]}"

package/dist/opencode/kits/builder/flows/publish-learn.flow.json

@@ -1,6 +1,6 @@
 {
   "id": "builder.publish-learn",
-  "version": "1.1",
+  "version": "1.2",
   "description": "Reusable delivery closeout extension: publish the verified change, confirm merge readiness from provider/CI evidence, and record learning feedback.",
   "steps": [
     { "id": "pr-open", "next": "merge-ready-ci" },
@@ -17,6 +17,14 @@
   "gates": {
     "pr-open-gate": {
       "step": "pr-open",
+      "on_route_back": {
+        "missing_evidence": "verify",
+        "default": "verify"
+      },
+      "route_back_policy": {
+        "max_attempts": 3,
+        "on_exceeded": "block"
+      },
       "expects": [
         {
           "id": "pull-request-opened",

package/dist/opencode/kits/builder/skills/execute-plan/SKILL.md

@@ -11,7 +11,7 @@ Implement an approved plan while preserving scope, traceability, and recovery co
 
 - **Role:** canonical Builder build-step producer and standalone execution primitive.
 - **Binding:** `builder.build` step `execute`.
-- **Produces:** the active session execution report (`<slug>--deliver.md`), `state.json`, and `implementation-scope` for an active matching run.
+- **Produces:** the active session execution report (`<slug>--deliver.md`), `state.json`, the wave manifest (`waves.json`) for delegated waves, and `implementation-scope` for an active matching run.
 - **Standalone no-run behavior:** execute the supplied plan and return execution evidence. Do not start a Builder run, record Builder evidence, or imply that an inactive Builder flow advanced.
 
 ## Model Routing
@@ -33,8 +33,8 @@ Use `RepositoryAdapter` for repository, target revision, worktree, and changed-f
 
 1. Read the plan. Return it to `plan-work` when it lacks a Definition Of Done, stable acceptance criteria, task mapping, sandbox boundary, or usable execution scope.
 2. Before delegation, compare the current target revision with the plan's base through `RepositoryAdapter`. Re-ground the plan when changed scope intersects its assumptions; record missing confirmation as `NOT_VERIFIED` rather than treating it as fresh.
-3. Give each worker its bounded task, owned files, relevant acceptance IDs, required evidence, sandbox/worktree constraints, rollback conditions, and plan reference.
-4. Run safe independent tasks concurrently and dependent tasks in order. Between waves, collect results, resolve conflicts, and update the execution record with completed work, remaining work, changed files, and supported acceptance criteria.
+3. Before dispatching a wave that delegates work, declare it in the session's wave manifest (`waves.json`, schema `schemas/workflow-waves.schema.json`): `wave_id`, owning step, and one `expected_workers` entry per worker, so the expected worker count (M) exists before any result arrives. Then give each worker its bounded task, owned files, relevant acceptance IDs, required evidence, sandbox/worktree constraints, rollback conditions, and plan reference.
+4. Run safe independent tasks concurrently and dependent tasks in order. Between waves, reconcile results against the wave manifest — never collect from memory or prose. Every declared worker must land exactly one terminal status record (`completed`, `failed`, or `blocked`). Record each declared worker that has no terminal record as `not_reported` — never silently absorb a missing worker — then record the wave's `reconciliation` with an explicit "N of M reported" summary naming the `not_reported` workers (for example "2 of 3 reported; worker-3 not_reported"). Treat the wave as complete only when N equals M; an incomplete wave is visible data that routes to re-dispatch, a blocker, or an explicit accepted gap. After reconciliation, resolve conflicts and update the execution record with completed work, remaining work, changed files, and supported acceptance criteria.
 5. For UI tasks, include the applicable frontend design guidance in the worker instruction.
 6. When implementation completes, record scope integrity: changed files, accepted deviations, task-to-criterion traceability, evidence, and outstanding gaps. Hand off to report-only review and verification; do not treat implementation as verification.
 7. Reconcile the execution report and `state.json` with the active session artifact directory.
@@ -49,6 +49,7 @@ The execution record must identify:
 - each completed task and its supported `AC*` identifiers
 - changed files and any scope deviation with approval or route-back reason
 - worker evidence, conflicts, rollback notes, remaining work, and next action
+- per-wave reconciliation against the manifest: "N of M reported" and any `not_reported` workers with their recovery route
 - current revision comparison and re-grounding decision
 
 ## Active Builder Evidence

package/dist/opencode/kits/builder/skills/pull-work/SKILL.md

@@ -32,6 +32,18 @@ Select ready backlog work and prepare a bounded handoff without implementing it.
 
 An optional GitHub adapter may implement these interfaces. Do not require GitHub issue numbers, labels, Projects, pull requests, `gh`, or provider-native dependency APIs.
 
+### Readiness Source Integrity
+
+A configured `BoardProvider` is the canonical Backlog Readiness Source
+(`docs/decisions/backlog-readiness-source.md`). When the configured board
+yields zero ready items or cannot be read, record the provider warning
+(`zero_ready_items`, or the read failure) in the pull-work artifact and route
+to triage/intake for an explicit readiness decision. Never silently
+substitute `WorkItemProvider` issue-level listing for board-driven selection:
+a deliberate issue-listing pass must carry the `board_provider_bypassed`
+warning it received into the artifact, with the reason the board was
+bypassed.
+
 ## Model Routing
 
 For board scans, WIP assessment, dependency joins, and selection bookkeeping, resolve `delegate-mechanical` from `.datum/config.json`. If unavailable, inherit the session model and record the fallback.

package/dist/opencode/kits/builder/skills/review-work/SKILL.md

@@ -58,6 +58,17 @@ fallback or escalation in the critique artifact.
      security-policy changes.
    - `tool-dependencies-updater` for dependency-manifest, lockfile, or dependency-tooling changes.
    - A configured domain or policy reviewer when the repository requires one.
+
+   When review fans out to delegated reviewer lanes, declare the fan-out in the
+   session's wave manifest (`waves.json`, schema
+   `schemas/workflow-waves.schema.json`, step `review`) with one
+   `expected_workers` entry per reviewer lane before dispatch. Reconcile against
+   that manifest at collection — "N of M reported" — instead of collecting from
+   memory: every declared reviewer lands exactly one terminal status record;
+   record a reviewer that never reports as `not_reported` in the manifest —
+   never silently absorb it — and carry that lane into the critique as
+   `not_verified` with the missing report named. A missing reviewer is never a
+   clean lane.
 3. Use repository-provided scanners and checks when applicable. Do not install
    a scanner, silently substitute a different one, or mark an unavailable
    required lane clean; record the lane as `NOT_VERIFIED` with the missing