@kontourai/flow-agents 4.0.0 → 4.2.0

package/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/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/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/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/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/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/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

package/kits/veritas-governance/adapter/readiness-to-trust-bundle.mjs

@@ -19,22 +19,21 @@
 // external-tool `fail`/`missing` (mirrors veritas/src/surface/readiness.mjs's own PRIVATE
 // `readinessHasBlockingFailure` helper, and matches Surface's `buildTrustReport` weakest-link
 // derivation, which downgrades a readiness claim to `rejected` on any rejected Require —
-// tests/surface/readiness-derived-claim.test.mjs:256-278). It intentionally does NOT apply
-// Veritas's EXPORTED `promotion_allowed` short-circuit (readinessSurfaceStatus/readinessVerdict
-// treat promotion_allowed===true as verified/ready regardless of blocking Require failures):
-// promotion_allowed is a workstream-routing hint from src/repo/routing.mjs `resolveWorkstream()`
-// (file-pattern lane resolution), not a safety signal — it never reads policy_results, evidence
-// checks, uncovered paths, or external tools, so it cannot account for blocking failures. This is
-// a filed Veritas bug, not a legitimate alternate reading: kontourai/veritas#106
-// (https://github.com/kontourai/veritas/issues/106) — "promotion_allowed short-circuit bypasses
-// blocking Require failures" — recommends veritas fix readiness.mjs to check
-// readinessHasBlockingFailure() before the promotion_allowed short-circuit. Conclusion: the
-// adapter's stricter derivation is correct today and will agree with veritas's own exported
-// functions once #106 lands; it is not a fork of Veritas's intended semantics, and the
-// Governance Kit's blocking-failure semantics are the successor the wider system is moving
-// toward (this adapter's independent CLI wrap was for reversibility while that landed). Ready
-// (no blocking failure) -> Surface derives `verified` -> gate passes. Not-ready -> Surface
-// derives a non-`verified` status -> gate blocks.
+// tests/surface/readiness-derived-claim.test.mjs:256-278). It does NOT treat Veritas's
+// `promotion_allowed` flag as a safety signal: promotion_allowed is a workstream-routing hint
+// from src/repo/routing.mjs `resolveWorkstream()` (file-pattern lane resolution) — it never
+// reads policy_results, evidence checks, uncovered paths, or external tools, so it cannot
+// account for blocking failures. The divergence this originally guarded against —
+// kontourai/veritas#106 (https://github.com/kontourai/veritas/issues/106), Veritas's exported
+// readinessVerdict/readinessSurfaceStatus honoring promotion_allowed before checking blocking
+// failures — is FIXED: veritas src/surface/readiness.mjs now checks
+// readinessHasBlockingFailure() before the promotion_allowed short-circuit (regression-tested
+// in veritas tests/surface/readiness-verdict.test.mjs), so this adapter and Veritas's exported
+// functions now agree. The adapter keeps its own derivation because kit code consumes the
+// recorded artifact, not Veritas library exports; the record fields and blocking-failure
+// semantics it reads are frozen in veritas docs/architecture/engine-surface-seam.md
+// (flow-agents#646 Slice 1). Ready (no blocking failure) -> Surface derives `verified` -> gate
+// passes. Not-ready -> Surface derives a non-`verified` status -> gate blocks.
 //
 // Usage: node readiness-to-trust-bundle.mjs --report <veritas-evidence-report.json> \
 //          --out <bundle.json> [--subject-id <id>]
@@ -54,10 +53,10 @@ function parseArgs(argv) {
   return out;
 }
 
-// Mirrors veritas/src/surface/readiness.mjs's PRIVATE readinessHasBlockingFailure — reads
-// Veritas's OWN recorded results; does not evaluate standards. Does NOT apply promotion_allowed
-// (see header comment above): that short-circuit is a filed veritas bug (kontourai/veritas#106),
-// not a safety signal — this stricter derivation is the settled-correct semantics.
+// Mirrors veritas/src/surface/readiness.mjs's readinessHasBlockingFailure — reads Veritas's
+// OWN recorded results; does not evaluate standards. Ignores promotion_allowed (a routing hint,
+// not a safety signal — see header comment above); since veritas#106 was fixed, Veritas's own
+// verdict functions (src/surface/readiness.mjs) apply this same blocking-failure-first semantics.
 export function hasBlockingFailure(record) {
   if (record.uncovered_path_result === "fail") return true;
   if ((record.policy_results ?? []).some((r) => r.passed === false && r.enforcementLevel === "Require")) return true;

package/kits/veritas-governance/assets/starter-hooks/githooks/post-commit

@@ -0,0 +1,13 @@
+#!/bin/sh
+set -eu
+
+if [ "${VERITAS_HOOK_SKIP:-${AI_GUIDANCE_HOOK_SKIP:-0}}" = "1" ]; then
+  exit 0
+fi
+
+if git rev-parse --verify --quiet HEAD~1 >/dev/null; then
+  npm exec -- veritas readiness --changed-from HEAD~1 --changed-to HEAD
+else
+  EMPTY_TREE="$(git hash-object -t tree /dev/null)"
+  npm exec -- veritas readiness --changed-from "$EMPTY_TREE" --changed-to HEAD
+fi

package/kits/veritas-governance/assets/starter-hooks/githooks/pre-push

@@ -0,0 +1,13 @@
+#!/bin/sh
+set -eu
+
+if [ "${VERITAS_HOOK_SKIP:-${AI_GUIDANCE_HOOK_SKIP:-0}}" = "1" ]; then
+  exit 0
+fi
+
+if [ ! -f package.json ]; then
+  echo "Veritas pre-push: package.json not found; skipping."
+  exit 0
+fi
+
+npm run --if-present prepush

package/kits/veritas-governance/assets/starter-standards/veritas/GOVERNANCE.md

@@ -0,0 +1,23 @@
+# Veritas Governance
+
+Protected Standards require authority-backed review. Do not modify without a fresh Veritas attestation:
+- `.veritas/repo-map.json`
+- `.veritas/repo-standards/`
+- `.veritas/authority/`
+
+Authority-backed attestations require an explicit human approval reference. Agents may prepare
+`veritas attest ... --approval-ref <ref>` commands, but must not invent the reference or record
+the attestation without a durable approval artifact from the human authority.
+
+Standards Growth is additive. Developers and agents may propose:
+- new work areas for new feature directories
+- advisory requirements for new work areas
+- clearer change guidance backed by evidence
+
+Do not weaken or delete existing standards without the required authority.
+
+Generated Evidence is output, not the source of standards:
+- `.kontourai/veritas/evidence/`
+- `.kontourai/veritas/standards-feedback-drafts/`
+- `.kontourai/veritas/standards-feedback/`
+- `.kontourai/veritas/repo-conformance/`

package/kits/veritas-governance/assets/starter-standards/veritas/README.md

@@ -0,0 +1,58 @@
+# Veritas Starter Kit
+
+This repo was bootstrapped for `your-project` with a conservative starter kit for agent-guided development.
+
+## Generated Files
+
+- `.veritas/README.md`
+- `.veritas/GOVERNANCE.md`
+- `.veritas/repo-map.json`
+- `.veritas/repo-standards/default.repo-standards.json`
+- `.veritas/authority/default.authority-settings.json`
+
+## Inferred Repo Shape
+
+- Repo kind: `application`
+- Source roots: `src/` (default)
+- Tooling roots: `none`
+- Test roots: `tests/` (default)
+- GitHub workflows detected: `no`
+- Matching scripts seen: `test`
+
+## What To Do Next
+
+1. Confirm the inferred source/test roots match the real repo layout.
+2. Replace the suggested evidenceCheck if a stronger project health command exists.
+3. Keep uncertain requirements in Observe or Guide until evidence shows they should be required.
+
+
+
+## Suggested Commands
+
+```bash
+npx @kontourai/veritas readiness --working-tree
+npx @kontourai/veritas readiness --check coverage --working-tree
+npx @kontourai/veritas integrations codex status
+npx @kontourai/veritas attest bootstrap --actor <authority-id> --approval-ref <human-approval-reference> --non-interactive
+```
+
+If you prefer explicit paths:
+
+```bash
+npx @kontourai/veritas readiness --check evidence \
+  --repo-map ./.veritas/repo-map.json \
+  --repo-standards ./.veritas/repo-standards/default.repo-standards.json \
+  package.json
+```
+
+## Suggested Evidence Check
+
+`npm run test`
+
+## Work-Area Evidence Routing
+
+This starter stays on the minimal single-check path by default. Work-area evidence routing can be added later if the repo grows multiple independently verified work areas.
+
+## Why This Exists
+
+The goal is to give developers and agents just-in-time repo guidance from day one, while keeping review and CI grounded in the same starter standards.

package/kits/veritas-governance/assets/starter-standards/veritas/authority/default.authority-settings.json

@@ -0,0 +1,30 @@
+{
+  "version": 1,
+  "id": "your-project-default",
+  "name": "your-project Default",
+  "description": "Conservative starter settings: observe first, learn from evidence, and only require what has earned trust.",
+  "defaults": {
+    "mode": "observe",
+    "new_rule_enforcement_level": "Observe"
+  },
+  "review_preferences": {
+    "human_signoff_required_for_stage_promotion": true,
+    "reviewer_confidence_scale": [
+      "low",
+      "medium",
+      "high"
+    ],
+    "major_rewrite_definition": "A major rewrite replaces the main structure or requirement flow instead of making local edits.",
+    "attestation_approval_ref_policy": {
+      "mode": "reference-only",
+      "allowed_prefixes": []
+    }
+  },
+  "promotion_preferences": {
+    "evidence_checks_required_before_require": [
+      "npm run test"
+    ],
+    "warnings_block_in_ci": false,
+    "require_consistent_feedback_before_promotion": true
+  }
+}