@kontourai/flow-agents 4.0.0 → 4.1.0

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

@@ -133,6 +133,72 @@ echo "--- exemption-issuance: gate blocks without a verified approval, passes wi
 exemption_gate_case "$KIT/fixtures/exemption/approved.trust-bundle.json"     "exemption-positive" 0
 exemption_gate_case "$KIT/fixtures/exemption/not-approved.trust-bundle.json" "exemption-negative" 1
 
+# --- standards-authoring flow (Slice 2 PR3): registration, gate shape, gate cases ---
+# Agentless propose -> apply flow whose human-approval-gate blocks the `veritas init --apply`
+# write until a human-authored standards-authoring-approval claim is verified. The kit only
+# gates the sign-off; Veritas does the derivation and the write (no evaluation reimplemented).
+AUTHORING_FLOWDEF="$KIT/flows/standards-authoring.flow.json"
+if node -e "const f=require('$AUTHORING_FLOWDEF'); if(f.id!=='veritas-governance.standards-authoring') process.exit(1);" 2>/dev/null; then
+  pass "standards-authoring flow file has id veritas-governance.standards-authoring"
+else
+  fail "standards-authoring flow file missing or has unexpected id"
+fi
+if rg -q '"id": *"veritas-governance\.standards-authoring"' "$KIT/kit.json" && rg -q '"path": *"flows/standards-authoring\.flow\.json"' "$KIT/kit.json"; then
+  pass "standards-authoring flow is registered in kit.json flows[]"
+else
+  fail "standards-authoring flow is NOT registered in kit.json flows[]"
+fi
+if rg -q '"id": *"veritas-governance\.standards-authoring"' "$KIT/kit.json" && rg -q '"path": *"skills/standards-authoring/SKILL.md"' "$KIT/kit.json"; then
+  pass "standards-authoring skill is registered in kit.json skills[]"
+else
+  fail "standards-authoring skill is NOT registered in kit.json skills[]"
+fi
+# Agentless invariant: the kit declares no flow_step_actions (would opt into Builder's
+# producer-ownership contract and break the agentless gate flows).
+if rg -q 'flow_step_actions' "$KIT/kit.json"; then
+  fail "kit.json declares flow_step_actions — veritas-governance flows are agentless"
+else
+  pass "kit stays agentless (no flow_step_actions)"
+fi
+if node -e "
+const f=require('$AUTHORING_FLOWDEF');
+const g=f.gates['human-approval-gate'];
+const bc=g.expects[0].bundle_claim;
+if (g.expects[0].kind!=='trust.bundle') process.exit(1);
+if (bc.claimType!=='standards-authoring-approval') process.exit(1);
+if (bc.subjectType!=='repo-governance-change') process.exit(1);
+if (JSON.stringify(bc.accepted_statuses)!=='[\"verified\"]') process.exit(1);
+" 2>/dev/null; then
+  pass "standards-authoring gate expects[] kind is trust.bundle and pins claimType/subjectType/accepted_statuses exactly"
+else
+  fail "standards-authoring gate expects[] shape does not match the pinned claim selector"
+fi
+# Positive/negative gate cases against the committed fixtures. $1 bundle, $2 label, $3 expect.
+authoring_gate_case() {
+  local bundle="$1" label="$2" expect="$3"
+  local work="$TMP_DIR/$label"; mkdir -p "$work"; ( cd "$work" && node "$FLOW_CLI" init >/dev/null 2>&1 )
+  ( cd "$work" && node "$FLOW_CLI" start "$AUTHORING_FLOWDEF" --run-id "$label" >/dev/null 2>&1 )
+  ( cd "$work" && node "$FLOW_CLI" attach-evidence "$label" --gate human-approval-gate --file "$bundle" --bundle >"$work/attach.out" 2>&1 )
+  if ! rg -q 'kind: trust.bundle' "$work/attach.out"; then
+    fail "[$label] evidence did not attach as kind: trust.bundle"; sed -n '1,20p' "$work/attach.out"; return
+  fi
+  ( cd "$work" && node "$FLOW_CLI" evaluate "$label" --gate human-approval-gate --exit-code >"$work/eval.out" 2>&1 )
+  local got=$?
+  if [[ "$got" == "$expect" ]]; then
+    pass "[$label] standards-authoring gate evaluate exit $got as expected"
+  else
+    fail "[$label] standards-authoring gate evaluate exit $got, expected $expect"; sed -n '1,20p' "$work/eval.out"
+  fi
+}
+authoring_gate_case "$KIT/fixtures/standards-authoring/approved.trust-bundle.json"     "authoring-positive" 0
+authoring_gate_case "$KIT/fixtures/standards-authoring/not-approved.trust-bundle.json" "authoring-negative" 1
+# No-fork: the authoring skill wraps the veritas CLI; it must not vendor rule/claim evaluation.
+if rg -q -i 'evaluateRepoStandards|evidence-check-runner\.mjs|class +[A-Za-z]*RuleEngine|repo-standards/default\.repo-standards\.json' "$KIT/skills/standards-authoring" "$KIT/flows/standards-authoring.flow.json" 2>/dev/null; then
+  fail "standards-authoring skill/flow appears to vendor Veritas evaluation logic (no-fork violated)"
+else
+  pass "no-fork: standards-authoring wraps the veritas CLI, no vendored rule/claim engine"
+fi
+
 # --- exemption-issuance: issue-step DECLARED append semantics (AC4) --------------
 # Seed a scratch delivery/DECLARED with main's real 2-entry array (inlined here, not read
 # live from the repo, so this eval is not coupled to that file's future contents), then
@@ -364,6 +430,196 @@ else
   echo "  - SKIP live Veritas leg (set VERITAS_BIN + VERITAS_GOVERNED_REPO to enable); fixtures are captured real output"
 fi
 
+# --- Starter-standards provisioning (Slice 2 PR2): the kit scaffolds a runnable .veritas/ ---
+# The kit declares its starter Repo Standards as provisions[]; `kit provision` copies them into
+# a consumer repo. This asserts the scaffold lands and is well-formed; when a Veritas binary is
+# available it further asserts `veritas readiness` runs end-to-end against the scaffolded repo.
+echo "--- starter-standards provisioning ---"
+FA_CLI="$ROOT/build/src/cli.js"
+if [[ ! -f "$FA_CLI" ]]; then
+  fail "flow-agents CLI not built at build/src/cli.js (run npm run build)"
+else
+  prov="$TMP_DIR/provisioned-repo"; mkdir -p "$prov"
+  if node "$FA_CLI" kit provision "$KIT" --target "$prov" >"$TMP_DIR/provision.out" 2>&1; then
+    pass "kit provision scaffolds starter standards into a consumer repo"
+  else
+    fail "kit provision failed"; sed -n '1,20p' "$TMP_DIR/provision.out"
+  fi
+  # Every declared provision target must land and (for JSON) parse.
+  starter_targets=(
+    ".veritas/repo-map.json"
+    ".veritas/repo-standards/default.repo-standards.json"
+    ".veritas/authority/default.authority-settings.json"
+    ".veritas/GOVERNANCE.md"
+    ".veritas/README.md"
+    "veritas.claims.json"
+  )
+  for rel in "${starter_targets[@]}"; do
+    if [[ -f "$prov/$rel" ]]; then
+      if [[ "$rel" == *.json ]]; then
+        if node -e "JSON.parse(require('fs').readFileSync(process.argv[1],'utf8'))" "$prov/$rel" >/dev/null 2>&1; then
+          pass "scaffolded $rel is present and valid JSON"
+        else
+          fail "scaffolded $rel is not valid JSON"
+        fi
+      else
+        pass "scaffolded $rel is present"
+      fi
+    else
+      fail "expected scaffolded file missing: $rel"
+    fi
+  done
+  # The scaffold must reference the Veritas engine's OWN starter output, not reimplement it:
+  # every provision source lives under assets/, never in adapter/ or flows/ (no-fork already
+  # scopes there). Assert the declared sources exist inside the kit's assets tree.
+  if node -e "
+    const fs=require('fs'),path=require('path');
+    const kit=JSON.parse(fs.readFileSync(process.argv[1]+'/kit.json','utf8'));
+    const bad=(kit.provisions||[]).filter(p=>!p.path.startsWith('assets/')||!fs.existsSync(path.join(process.argv[1],p.path)));
+    if(bad.length){console.error('bad provisions:',bad.map(p=>p.id).join(','));process.exit(1)}
+  " "$KIT" >/dev/null 2>&1; then
+    pass "all starter provisions source from the kit's assets/ tree"
+  else
+    fail "a starter provision points outside assets/ or at a missing file"
+  fi
+  # Live: a Veritas binary must be able to run readiness against the scaffolded repo.
+  VBIN2="${VERITAS_BIN:-veritas}"
+  if command -v "$VBIN2" >/dev/null 2>&1 || [[ -x "$VBIN2" ]]; then
+    ( cd "$prov" && git init -q && printf '{"name":"scaffold-eval","scripts":{"test":"node -e \"process.exit(0)\""}}\n' > package.json \
+        && git add -A && git -c user.email=eval@local -c user.name=eval commit -qm scaffold ) >/dev/null 2>&1
+    if ( cd "$prov" && "$VBIN2" readiness --working-tree >/dev/null 2>&1 ); then :; fi
+    if ls "$prov/.kontourai/veritas/evidence/"*.json >/dev/null 2>&1; then
+      pass "veritas readiness runs end-to-end on the kit-scaffolded repo (evidence report produced)"
+    else
+      fail "veritas readiness produced no evidence report on the scaffolded repo"
+    fi
+  else
+    echo "  - SKIP scaffold readiness leg (no Veritas binary; set VERITAS_BIN to enable)"
+  fi
+fi
+
+# --- Governance git-hook provisioning (Slice 3 PR / #648) --------------------------
+# The kit ships the two governance git hooks as provisions[]; `kit provision` lands them
+# (non-executable), and a documented chmod + core.hooksPath step activates them. This asserts
+# the hook files land with the expected bodies and that, once activated, the pre-push hook fires.
+echo "--- governance git-hook provisioning ---"
+FA_CLI2="$ROOT/build/src/cli.js"
+if [[ ! -f "$FA_CLI2" ]]; then
+  fail "flow-agents CLI not built at build/src/cli.js (run npm run build)"
+else
+  hookrepo="$TMP_DIR/hook-provisioned-repo"; mkdir -p "$hookrepo"
+  ( cd "$hookrepo" && git init -q && printf '{"name":"hook-eval","scripts":{"prepush":"echo PREPUSH-RAN"}}\n' > package.json )
+  if node "$FA_CLI2" kit provision "$KIT" --target "$hookrepo" >"$TMP_DIR/hookprov.out" 2>&1; then
+    pass "kit provision lands the governance git hooks"
+  else
+    fail "kit provision (hooks) failed"; sed -n '1,20p' "$TMP_DIR/hookprov.out"
+  fi
+  # Both hook files present, match the committed kit assets byte-for-byte, AND carry their
+  # defining command. The byte-match alone cannot catch a corrupted kit asset (a bad asset is
+  # copied verbatim and still matches itself), so a content assertion pins what each hook must do.
+  declare -A hook_must_contain=(
+    [pre-push]='npm run --if-present prepush'
+    [post-commit]='veritas readiness --changed-from HEAD~1 --changed-to HEAD'
+  )
+  for hook in pre-push post-commit; do
+    if [[ -f "$hookrepo/.githooks/$hook" ]]; then
+      if cmp -s "$hookrepo/.githooks/$hook" "$KIT/assets/starter-hooks/githooks/$hook"; then
+        pass "scaffolded .githooks/$hook matches the kit asset byte-for-byte"
+      else
+        fail "scaffolded .githooks/$hook differs from the kit asset"
+      fi
+      if grep -qF "${hook_must_contain[$hook]}" "$hookrepo/.githooks/$hook"; then
+        pass "scaffolded .githooks/$hook invokes its defining command (${hook_must_contain[$hook]})"
+      else
+        fail "scaffolded .githooks/$hook is missing its defining command (${hook_must_contain[$hook]}) — corrupted asset?"
+      fi
+    else
+      fail "expected git hook missing: .githooks/$hook"
+    fi
+  done
+  # Provisions land non-executable by design (the engine copy is agent-blind) — assert for BOTH.
+  for hook in pre-push post-commit; do
+    if [[ -x "$hookrepo/.githooks/$hook" ]]; then
+      fail "provisioned .githooks/$hook is already executable — provisioning should be agent-blind (no +x)"
+    else
+      pass "provisioned .githooks/$hook lands non-executable (agent-blind copy; activation is explicit)"
+    fi
+  done
+  ( cd "$hookrepo" && chmod +x .githooks/pre-push .githooks/post-commit && git config core.hooksPath .githooks )
+  if [[ "$(cd "$hookrepo" && git config --get core.hooksPath)" == ".githooks" ]]; then
+    pass "activation sets core.hooksPath to .githooks"
+  else
+    fail "activation did not set core.hooksPath"
+  fi
+  # Prove GIT actually dispatches the hook via core.hooksPath — not just direct invocation. Push
+  # to a local bare remote; the pre-push hook (runs `npm run --if-present prepush`) fires through
+  # git's own hook machinery. Output captured to a file so pipefail + git's SIGPIPE can't interfere.
+  ( cd "$hookrepo" && git -c user.email=eval@local -c user.name=eval commit -qm base --allow-empty ) >/dev/null 2>&1
+  bare="$TMP_DIR/hook-remote.git"; git init --bare -q "$bare"
+  ( cd "$hookrepo" && git remote add origin "$bare" && git push -q origin HEAD:refs/heads/main ) >"$TMP_DIR/gitpush.out" 2>&1
+  if grep -qF PREPUSH-RAN "$TMP_DIR/gitpush.out"; then
+    pass "git dispatches the pre-push hook via core.hooksPath (real git push fires it)"
+  else
+    fail "git push did not fire the pre-push hook via core.hooksPath"; sed -n '1,12p' "$TMP_DIR/gitpush.out"
+  fi
+  # No-fork: hook assets live under assets/, and invoke the veritas CLI — they must not vendor
+  # rule/claim evaluation. (assets/ is outside the adapter/flows no-fork scope; assert explicitly.)
+  if rg -q -i 'evaluateRepoStandards|evidence-check-runner\.mjs|class +[A-Za-z]*RuleEngine' "$KIT/assets/starter-hooks" 2>/dev/null; then
+    fail "governance hook assets appear to vendor Veritas evaluation logic (no-fork violated)"
+  else
+    pass "no-fork: governance hooks invoke the veritas CLI only (no vendored rule/claim engine)"
+  fi
+fi
+
+# --- consult-standards skill (Slice 4 / #649): JIT guidance via `veritas explain` ---------
+# A pull-based advisory skill telling an agent to run `veritas explain --file <path>` before
+# editing. No MCP server; wraps the veritas CLI, reimplements no evaluation.
+echo "--- consult-standards skill ---"
+CONSULT_SKILL="$KIT/skills/consult-standards/SKILL.md"
+if [[ -f "$CONSULT_SKILL" ]]; then
+  pass "consult-standards SKILL.md is present"
+else
+  fail "consult-standards SKILL.md is missing"
+fi
+if rg -q '"id": *"veritas-governance\.consult-standards"' "$KIT/kit.json" && rg -q '"path": *"skills/consult-standards/SKILL.md"' "$KIT/kit.json"; then
+  pass "consult-standards skill is registered in kit.json skills[]"
+else
+  fail "consult-standards skill is NOT registered in kit.json skills[]"
+fi
+# It must point agents at `veritas explain` (the JIT producer), not vendor evaluation.
+if grep -qF 'veritas explain' "$CONSULT_SKILL"; then
+  pass "consult-standards points at the veritas explain CLI"
+else
+  fail "consult-standards does not reference veritas explain"
+fi
+if rg -q -i 'evaluateRepoStandards|evidence-check-runner\.mjs|class +[A-Za-z]*RuleEngine' "$KIT/skills/consult-standards" 2>/dev/null; then
+  fail "consult-standards appears to vendor Veritas evaluation logic (no-fork violated)"
+else
+  pass "no-fork: consult-standards wraps the veritas CLI, no vendored rule/claim engine"
+fi
+# No-MCP invariant (#649 / ADR 0011): the kit ships no MCP server CODE and declares no MCP
+# dependency. Scoped to non-markdown files so the docs' explicit "no MCP server" prose (which
+# names the concept precisely to say the kit avoids it) does not trip the check.
+if rg -q -i 'modelcontextprotocol|new +McpServer|StdioServerTransport|createMcpServer' "$KIT" --glob '!*.md' 2>/dev/null; then
+  fail "kit ships MCP server code/dependency — #649 guidance is a skill, not an MCP server (ADR 0011)"
+else
+  pass "no MCP server: JIT guidance is an agent-pull skill (ADR 0011)"
+fi
+# Live leg: with a Veritas binary, a scaffolded repo's `veritas explain --file` produces JIT context.
+VBIN3="${VERITAS_BIN:-veritas}"
+if command -v "$VBIN3" >/dev/null 2>&1 || [[ -x "$VBIN3" ]]; then
+  cs="$TMP_DIR/consult-repo"; mkdir -p "$cs"
+  ( cd "$cs" && git init -q && printf '{"name":"consult-eval","scripts":{"test":"node -e \\"process.exit(0)\\""}}\n' > package.json && "$VBIN3" init >/dev/null 2>&1 )
+  explain_out="$( cd "$cs" && "$VBIN3" explain --file package.json 2>&1 )"
+  if printf '%s' "$explain_out" | grep -qF 'Veritas JIT Context'; then
+    pass "veritas explain --file produces JIT context on a governed repo (the guidance the skill invokes)"
+  else
+    fail "veritas explain --file did not produce JIT context"; printf '%s\n' "$explain_out" | sed -n '1,8p'
+  fi
+else
+  echo "  - SKIP consult-standards live leg (no Veritas binary; set VERITAS_BIN to enable)"
+fi
+
 echo ""
 if [[ "$errors" -eq 0 ]]; then
   echo "PASS: veritas-governance kit gate demo (positive passes, negative blocks)"

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/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 "4.0.0" --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