@kontourai/flow-agents 3.1.0 → 3.2.0

package/evals/integration/test_trust_reconcile_negatives.sh

@@ -749,6 +749,176 @@ else
   _fail "push-event-failing-verify: expected the push-event no-op line -- output: $out7v"
 fi
 
+# 8. #379 per-session delivery paths — concurrent-delivery collision resolution.
+#   resolveDeliveryCandidates() now discovers delivery/<slug>/trust.bundle per-session dirs
+#   in addition to the flat path; discoverBundle() selects the candidate whose checkpoint
+#   attests THIS change (ancestor-or-equal, same bundleAttestsThisChange() semantics the flat
+#   staleness gate uses), ignoring stale siblings from OTHER concurrent sessions. A shared
+#   flat path guaranteed a git conflict between any two concurrent deliveries → a DIRTY PR →
+#   NO pull_request workflows → the required check silently never ran (field #330/#358/#378).
+echo ""
+echo "=== 8. #379 per-session delivery paths (concurrent-delivery collision) ==="
+
+PERSESSION_TMPROOT="$(mktemp -d)"
+# Chain per-session cleanup onto the existing DECLARED cleanup without clobbering the trap.
+trap 'cleanup_declared; rm -rf "$PERSESSION_TMPROOT"' EXIT
+
+# write_session_seal <repo_root> <slug> <label> <commit_sha>
+# Writes delivery/<slug>/trust.bundle (a well-formed schemaVersion-5 bundle whose only
+# claimed-pass command is <label>) + delivery/<slug>/trust.checkpoint.json (naming
+# <commit_sha>) — the per-session analogue of write_fresh_bundle + write_stale_checkpoint.
+write_session_seal() {
+  local repo_root="$1" slug="$2" label="$3" sha="$4"
+  local sdir="$repo_root/delivery/$slug"
+  mkdir -p "$sdir"
+  cat > "$sdir/trust.bundle" << EOF
+{
+  "schemaVersion": 5,
+  "source": "test-fixture:per-session:$slug",
+  "claims": [
+    {
+      "id": "c1", "claimType": "workflow.check.build", "value": "pass", "status": "verified",
+      "subjectId": "$slug/build", "facet": "flow-agents.workflow", "subjectType": "workflow-check",
+      "fieldOrBehavior": "build", "createdAt": "2026-07-01T00:00:00Z", "updatedAt": "2026-07-01T00:00:00Z",
+      "impactLevel": "high", "verificationPolicyId": "policy:workflow.check.build"
+    }
+  ],
+  "evidence": [
+    {
+      "id": "ev1", "claimId": "c1", "evidenceType": "test_output", "method": "validation",
+      "sourceRef": "$slug/command-log.jsonl", "excerptOrSummary": "build",
+      "observedAt": "2026-07-01T00:00:00Z", "collectedBy": "flow-agents/evidence-capture",
+      "passing": true,
+      "execution": { "runner": "bash", "label": "$label", "isError": false, "exitCode": 0 }
+    }
+  ],
+  "policies": [], "events": []
+}
+EOF
+  printf '{"schema_version":"1.0","slug":"%s","work_item":null,"status":"delivered","phase":"release","sealed_at":"2026-01-01T00:00:00Z","commit_sha":"%s","checkpoint":{"asOf":"2026-01-01T00:00:00.000Z","statusByClaimId":{}}}' \
+    "$slug" "$sha" > "$sdir/trust.checkpoint.json"
+}
+
+FRESH_LABEL_8="node -e 'process.exit(0)'"
+
+# 8a. OWNER WINS: two sibling session dirs — one OWNING (checkpoint commit_sha == this
+#     change's sha), one STALE (a different sha). The reconciler MUST pick the owner and
+#     reconcile it; the stale sibling is ignored, NOT a failure.
+CASE8A="$PERSESSION_TMPROOT/collision-owner-wins"
+write_session_seal "$CASE8A" "owning-session" "$FRESH_LABEL_8" "$OURS_SHA"
+write_session_seal "$CASE8A" "stale-sibling" "echo stale-should-never-be-reconciled" "$STALE_SHA"
+out8a="$(TRUST_RECONCILE_SHA="$OURS_SHA" TRUST_RECONCILE_COMMANDS="$FRESH_LABEL_8" \
+  node "$RECONCILE" --repo-root "$CASE8A" 2>&1)"
+code8a=$?
+if [[ $code8a -eq 0 ]]; then
+  _pass "persession-owner-wins: reconciler exits 0 (owning per-session candidate selected, stale sibling ignored)"
+else
+  _fail "persession-owner-wins: expected exit 0, got $code8a -- output: $out8a"
+fi
+if echo "$out8a" | grep -qF "selected delivery candidate delivery/owning-session/trust.bundle"; then
+  _pass "persession-owner-wins: emitted the #379 selection line naming the owning session dir"
+else
+  _fail "persession-owner-wins: expected the #379 selection line for delivery/owning-session/trust.bundle -- output: $out8a"
+fi
+if echo "$out8a" | grep -qF "RECONCILED"; then
+  _pass "persession-owner-wins: Step 2 reconciled the owning candidate's claimed-pass command"
+else
+  _fail "persession-owner-wins: expected RECONCILED -- output: $out8a"
+fi
+if echo "$out8a" | grep -qF "bundle-required-no-declared-marker"; then
+  _fail "persession-owner-wins: must NOT fail closed — an owning candidate exists"
+else
+  _pass "persession-owner-wins: does not fail closed (owning candidate found)"
+fi
+
+# 8b. NO OWNER: two sibling session dirs, BOTH stale (neither attests this change), no
+#     DECLARED marker -> fail closed EXACTLY as bundle-absence, plus the #379 concurrency
+#     hint so the next agent can diagnose a collision rather than a plain stale bundle.
+CASE8B="$PERSESSION_TMPROOT/collision-no-owner"
+OTHER_STALE_SHA="1111111111111111111111111111111111111111"
+write_session_seal "$CASE8B" "session-a" "echo a" "$STALE_SHA"
+write_session_seal "$CASE8B" "session-b" "echo b" "$OTHER_STALE_SHA"
+out8b="$(TRUST_RECONCILE_SHA="$OURS_SHA" TRUST_RECONCILE_COMMANDS="$FRESH_LABEL_8" \
+  node "$RECONCILE" --repo-root "$CASE8B" 2>&1)"
+code8b=$?
+if [[ $code8b -ne 0 ]]; then
+  _pass "persession-no-owner: reconciler exits non-zero ($code8b) -- no candidate attests this change, fail closed"
+else
+  _fail "persession-no-owner: expected non-zero exit, got 0 -- output: $out8b"
+fi
+if echo "$out8b" | grep -qF "none attests this change $OURS_SHA"; then
+  _pass "persession-no-owner: emitted the #379 concurrency hint (none attests this change)"
+else
+  _fail "persession-no-owner: expected the #379 'none attests this change' hint -- output: $out8b"
+fi
+if echo "$out8b" | grep -qF "bundle-required-no-declared-marker"; then
+  _pass "persession-no-owner: emitted 'bundle-required-no-declared-marker' (same fail-closed path as bundle-absence)"
+else
+  _fail "persession-no-owner: expected 'bundle-required-no-declared-marker' -- output: $out8b"
+fi
+
+# 8c. BACK-COMPAT COEXISTENCE: a flat legacy owner (delivery/trust.bundle) alongside a stale
+#     per-session sibling -> the flat owner is still selected and reconciled (the flat path
+#     stays supported; per-session discovery does not break it).
+CASE8C="$PERSESSION_TMPROOT/flat-owner-persession-stale"
+write_fresh_bundle "$CASE8C" "$FRESH_LABEL_8"          # flat delivery/trust.bundle
+write_stale_checkpoint "$CASE8C" "$OURS_SHA"           # flat delivery/trust.checkpoint.json (owns)
+write_session_seal "$CASE8C" "stale-session" "echo ignored" "$STALE_SHA"  # per-session stale sibling
+out8c="$(TRUST_RECONCILE_SHA="$OURS_SHA" TRUST_RECONCILE_COMMANDS="$FRESH_LABEL_8" \
+  node "$RECONCILE" --repo-root "$CASE8C" 2>&1)"
+code8c=$?
+if [[ $code8c -eq 0 ]]; then
+  _pass "flat-owner-coexist: reconciler exits 0 (flat legacy owner selected despite a stale per-session sibling)"
+else
+  _fail "flat-owner-coexist: expected exit 0, got $code8c -- output: $out8c"
+fi
+if echo "$out8c" | grep -qF "RECONCILED"; then
+  _pass "flat-owner-coexist: Step 2 reconciled the flat owner (back-compat preserved)"
+else
+  _fail "flat-owner-coexist: expected RECONCILED -- output: $out8c"
+fi
+
+# 8d. PREFER-NEWEST among multiple OWNING candidates (the merge-commit-repo / concurrent-PR
+#   coexistence case). An inherited FLAT bundle can attest a REAL ANCESTOR of this change
+#   (committed on the trunk before this branch), AND this session's per-session bundle attests
+#   a NEWER ancestor. "First-fresh-wins" would wrongly pick the stale flat bundle because it
+#   sorts first; the reconciler must instead pick the NEWEST-owning candidate (the per-session
+#   one). Uses a REAL git repo so `git merge-base --is-ancestor` resolves the parent→child
+#   relationship (synthetic shas cannot exercise the ancestor comparison).
+NEWEST_REPO="$PERSESSION_TMPROOT/prefer-newest-git"
+mkdir -p "$NEWEST_REPO"
+git -C "$NEWEST_REPO" init -q
+git -C "$NEWEST_REPO" config user.email "test@example.com"
+git -C "$NEWEST_REPO" config user.name "Test"
+echo "base" > "$NEWEST_REPO/f.txt"; git -C "$NEWEST_REPO" add f.txt; git -C "$NEWEST_REPO" commit -q -m "base (inherited flat seal sealed here)"
+FLAT_ANCESTOR_SHA="$(git -C "$NEWEST_REPO" rev-parse HEAD)"
+echo "delivery" >> "$NEWEST_REPO/f.txt"; git -C "$NEWEST_REPO" add f.txt; git -C "$NEWEST_REPO" commit -q -m "this session's delivery commit"
+PERSESSION_OWNER_SHA="$(git -C "$NEWEST_REPO" rev-parse HEAD)"
+echo "head" >> "$NEWEST_REPO/f.txt"; git -C "$NEWEST_REPO" add f.txt; git -C "$NEWEST_REPO" commit -q -m "seal commit (HEAD)"
+NEWEST_HEAD_SHA="$(git -C "$NEWEST_REPO" rev-parse HEAD)"
+# Flat owner attesting the OLD ancestor; per-session owner attesting the NEWER ancestor.
+write_fresh_bundle "$NEWEST_REPO" "$FRESH_LABEL_8"                 # flat delivery/trust.bundle
+write_stale_checkpoint "$NEWEST_REPO" "$FLAT_ANCESTOR_SHA"          # flat checkpoint -> OLD ancestor
+write_session_seal "$NEWEST_REPO" "this-session" "$FRESH_LABEL_8" "$PERSESSION_OWNER_SHA"  # per-session -> NEWER ancestor
+out8d="$(TRUST_RECONCILE_SHA="$NEWEST_HEAD_SHA" TRUST_RECONCILE_COMMANDS="$FRESH_LABEL_8" \
+  node "$RECONCILE" --repo-root "$NEWEST_REPO" 2>&1)"
+code8d=$?
+if [[ $code8d -eq 0 ]]; then
+  _pass "prefer-newest: reconciler exits 0 (both flat and per-session own; newest selected)"
+else
+  _fail "prefer-newest: expected exit 0, got $code8d -- output: $out8d"
+fi
+if echo "$out8d" | grep -qF "selected delivery candidate delivery/this-session/trust.bundle"; then
+  _pass "prefer-newest: selected the NEWER per-session bundle over the older inherited flat bundle"
+else
+  _fail "prefer-newest: expected the per-session bundle to be selected (newest-owning) -- output: $out8d"
+fi
+if echo "$out8d" | grep -qF "owning, newest wins"; then
+  _pass "prefer-newest: emitted the 'owning, newest wins' selection detail"
+else
+  _fail "prefer-newest: expected 'owning, newest wins' in the selection line -- output: $out8d"
+fi
+
 echo ""
 if [[ $errors -eq 0 ]]; then
   echo "test_trust_reconcile_negatives: all checks passed."

package/evals/run.sh

@@ -148,6 +148,8 @@ run_static() {
   bash "$EVAL_DIR/static/test_unit_helpers.sh" || result=1
   echo ""
   bash "$EVAL_DIR/static/test_knowledge_providers.sh" || result=1
+  echo ""
+  bash "$EVAL_DIR/static/test_model_routing_hints.sh" || result=1
   return $result
 }
 
@@ -201,6 +203,8 @@ run_integration() {
   echo ""
   bash "$EVAL_DIR/integration/test_assignment_provider_github.sh" || result=1
   echo ""
+  bash "$EVAL_DIR/integration/test_stop_hook_release.sh" || result=1
+  echo ""
   bash "$EVAL_DIR/integration/test_pull_work_assignment_join.sh" || result=1
   echo ""
   bash "$EVAL_DIR/integration/test_ensure_session_ownership_guard.sh" || result=1
@@ -282,6 +286,8 @@ run_integration() {
   echo ""
   bash "$EVAL_DIR/integration/test_kit_identity_trust.sh" || result=1
   echo ""
+  bash "$EVAL_DIR/integration/test_model_routing_escalation.sh" || result=1
+  echo ""
   bash "$EVAL_DIR/acceptance/prove-capture-teeth-declared.sh" || result=1
   return $result
 }

package/evals/static/test_model_routing_hints.sh

@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+# test_model_routing_hints.sh — #376
+# Asserts that every delegating Builder Kit skill carries a per-step model-role
+# hint pointing at the execution contract (AC1/R1), that the execution contract
+# documents the escalate-on-gate-failure ladder (R2) and the Goodhart guard
+# (R3, review/verify tier >= worker tier), and that review/verify skill hints
+# encode that guard.
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+cd "$ROOT_DIR"
+
+SKILLS="kits/builder/skills"
+CONTRACT="context/contracts/execution-contract.md"
+POINTER="context/contracts/execution-contract.md"
+
+pass() { echo "PASS: $1"; }
+fail() { echo "FAIL: $1" >&2; exit 1; }
+
+require_contains() {
+  local file="$1" pattern="$2" label="$3"
+  grep -Fq -- "$pattern" "$file" || fail "$label ($file)"
+  pass "$label"
+}
+
+skill_has_routing_hint() {
+  # A delegating skill must have a Model Routing section that points at the
+  # execution contract's routing section — the single consumption instruction.
+  local skill="$1"
+  local file="$SKILLS/$skill/SKILL.md"
+  [[ -f "$file" ]] || fail "$skill SKILL.md missing"
+  grep -q "^## Model Routing" "$file" || fail "$skill has no '## Model Routing' section"
+  grep -Fq "$POINTER" "$file" || fail "$skill routing hint does not point at the execution contract"
+  pass "$skill has a Model Routing hint pointing at the execution contract"
+}
+
+skill_names_role() {
+  local skill="$1" role="$2"
+  local file="$SKILLS/$skill/SKILL.md"
+  grep -Fq "$role" "$file" || fail "$skill does not name role '$role'"
+  pass "$skill names role '$role'"
+}
+
+# ── R1/AC1: the delegating Builder Kit skills and the role each must name ──────
+# Design tier: shaping / probing / planning need design latitude.
+for s in builder-shape design-probe idea-to-backlog plan-work; do
+  skill_has_routing_hint "$s"
+  skill_names_role "$s" "delegate-design"
+done
+
+# Mechanical tier: board selection / sync / scan bookkeeping.
+skill_has_routing_hint "pull-work"
+skill_names_role "pull-work" "delegate-mechanical"
+
+# Implementation tier: worker slices.
+skill_has_routing_hint "execute-plan"
+skill_names_role "execute-plan" "delegate-implementation"
+
+# Review / verify: default implementation, subject to the Goodhart guard (R3).
+for s in review-work verify-work; do
+  skill_has_routing_hint "$s"
+  skill_names_role "$s" "delegate-implementation"
+done
+
+# Multi-delegate orchestrators carry a role table covering all three tiers.
+for s in deliver fix-bug tdd-workflow; do
+  skill_has_routing_hint "$s"
+  skill_names_role "$s" "delegate-mechanical"
+  skill_names_role "$s" "delegate-implementation"
+  skill_names_role "$s" "delegate-design"
+done
+
+# ── Drift guard: any builder skill that names a tool-* delegate must be a
+#    registered delegating skill above (i.e., must carry a Model Routing hint).
+DELEGATING="builder-shape design-probe idea-to-backlog plan-work pull-work execute-plan review-work verify-work deliver fix-bug tdd-workflow"
+for file in "$SKILLS"/*/SKILL.md; do
+  skill="$(basename "$(dirname "$file")")"
+  if grep -qE "tool-(worker|planner|code-reviewer|security-reviewer|verifier|playwright)" "$file"; then
+    case " $DELEGATING " in
+      *" $skill "*) : ;;
+      *) fail "skill '$skill' names a tool-* delegate but has no registered Model Routing hint (register it in test_model_routing_hints.sh and add the hint)" ;;
+    esac
+  fi
+done
+pass "every tool-* delegating builder skill is registered with a Model Routing hint"
+
+# ── R3/AC3: review + verify skill hints encode the Goodhart guard ─────────────
+for s in review-work verify-work; do
+  file="$SKILLS/$s/SKILL.md"
+  grep -Fq "Goodhart guard" "$file" || fail "$s hint does not name the Goodhart guard"
+  grep -Fq "never" "$file" || fail "$s hint does not state the never-downgrade rule"
+  grep -Fiq "below" "$file" || fail "$s hint does not say review/verify never resolves below the checked work"
+  pass "$s hint encodes the Goodhart guard (never below the checked-work tier)"
+done
+
+# ── R2/AC2 + R3/AC3: the execution contract documents ladder + guard + record ─
+require_contains "$CONTRACT" "delegate-mechanical  <  delegate-implementation  <  delegate-design" "contract defines the tier ladder ordering"
+require_contains "$CONTRACT" "Escalation on gate failure" "contract documents the escalation ladder"
+require_contains "$CONTRACT" "one tier higher" "contract escalates the fix one tier higher on gate failure"
+require_contains "$CONTRACT" "Goodhart guard" "contract documents the Goodhart guard"
+require_contains "$CONTRACT" "greater than or equal to" "contract states review/verify tier >= checked-work tier"
+# R4: contract names the additive per-delegation recording shape (#349 consumable).
+require_contains "$CONTRACT" "Routing decisions in the run artifact" "contract documents routing-in-artifact recording"
+require_contains "$CONTRACT" "--escalated-from" "contract records escalations with --escalated-from"
+require_contains "$CONTRACT" "flow-agents#349" "contract ties routing records to the #349 economics record"
+
+echo "Model routing hint + ladder + Goodhart guard static checks passed."

package/kits/builder/skills/builder-shape/SKILL.md

@@ -22,6 +22,16 @@ Invoke the Builder Kit `shape` flow for raw product ideas, vague build goals, cu
 - Compatibility: Direct `idea-to-backlog` usage remains valid and should behave exactly as described in `kits/builder/skills/idea-to-backlog/SKILL.md`.
 - Primitive recovery: if a user invokes `idea-to-backlog` or another primitive with missing shaping context and appears to want the product flow, explain that Builder Kit shape is the entry point and offer to route there.
 
+## Model Routing
+
+When this skill delegates its shaping work (to `idea-to-backlog` / `design-probe`
+alignment), resolve the `delegate-design` role from `.datum/config.json`
+(`npx @kontourai/datum resolve delegate-design --json`) and pass the resolved
+model explicitly — shaping needs design latitude, so it routes to the design
+tier. See `context/contracts/execution-contract.md` § Delegation: Model Routing.
+Fallback: inherit the session model when datum/config is absent, noted in the
+artifact.
+
 ## Invocation
 
 Use this skill when the user says things like:

package/kits/builder/skills/deliver/SKILL.md

@@ -32,11 +32,16 @@ source of truth for the mapping):
 |---|---|
 | tool-worker | `delegate-mechanical` for fully-specified mechanical tasks, `delegate-implementation` for precisely-planned implementation, `delegate-design` when the task needs design latitude |
 | tool-planner | `delegate-design` |
-| tool-code-reviewer / tool-security-reviewer | `delegate-implementation` |
-| tool-verifier / tool-playwright | `delegate-implementation` |
+| tool-code-reviewer / tool-security-reviewer | `delegate-implementation` by default, raised to the worker's tier when higher — never below the tier of the checked work (Goodhart guard) |
+| tool-verifier / tool-playwright | `delegate-implementation` by default, raised to the worker's tier when higher — never below the tier of the checked work (Goodhart guard) |
 
-If datum or the config is absent, fall back to the runtime's inherited model
-and note the fallback in the session artifact.
+On a review/verify gate failure, re-dispatch the fix one tier higher on the
+ladder and record the escalation in the session artifact via
+`record-agent-event --kind escalation --role <higher> --escalated-from <lower>`
+(see `context/contracts/execution-contract.md` § Escalation on gate failure and
+§ Routing decisions in the run artifact). If datum or the config is absent, fall
+back to the runtime's inherited model and note the fallback in the session
+artifact.
 
 ## Orchestrator Rule
 
@@ -236,23 +241,59 @@ Record the final local state with `advance-state`. Use `status: verified` only w
 After review, verification, evidence, and Goal Fit are clean for the same diff:
 
 1. Confirm the working tree contains only verified scope.
-2. Publish the session trust bundle to `delivery/` so the CI trust-reconcile job can verify what the agent claimed. `record-release` (via the sidecar writer) does this automatically (best-effort). To publish or re-publish explicitly:
+2. Publish the session trust bundle so the CI trust-reconcile job can verify what the agent claimed. `record-release` (via the sidecar writer) does this automatically (best-effort). To publish or re-publish explicitly:
 
    ```bash
    npm run workflow:sidecar -- publish-delivery .kontourai/flow-agents/<slug>
    ```
 
-   Then force-stage the trust artifacts for the delivery commit. They are gitignored
-   by default (they are runtime artifacts written on every local delivery) — `-f`
-   commits them deliberately into THIS delivery PR so CI's trust-reconcile job can
-   reconcile the session's claims against fresh CI results:
+   **#379 — per-session delivery paths.** `publishDelivery()` writes to a PER-SESSION path
+   `delivery/<slug>/trust.bundle` (+ `trust.checkpoint.json` companions), where `<slug>` is
+   your session artifact dir's basename — NOT the old shared flat `delivery/trust.bundle`.
+   This is deliberate: a shared path guaranteed a git merge conflict between ANY two
+   concurrent deliveries, and a conflicting PR gets no CI (see the loud callout below). The
+   CI reconciler discovers both the flat (back-compat) and per-session layouts and selects
+   the NEWEST candidate whose checkpoint attests THIS change by commit ancestry — so an older
+   inherited bundle that also happens to be an ancestor of your change is ignored in favour of
+   your fresh one, and stale siblings from other sessions are ignored. `publishDelivery()`
+   also prunes inherited per-session sibling seal dirs (unique-named, never a cross-PR
+   conflict) so `delivery/` stays small; it deliberately does NOT delete the shared flat
+   `delivery/trust.bundle` legacy path (a concurrent PR may still seal there, and deleting it
+   would cause the DIRTY→no-CI conflict in the callout below).
+
+   Then force-stage the per-session trust dir for the delivery commit. It is gitignored by
+   default (runtime artifacts written on every local delivery) — `-f` commits it
+   deliberately into THIS delivery PR so CI's trust-reconcile job can reconcile the
+   session's claims against fresh CI results:
 
    ```bash
-   git add -f delivery/trust.bundle delivery/trust.checkpoint.json
+   git add -f delivery/<slug>/
    ```
 
-3. Commit the verified diff, including the force-added `delivery/trust.bundle` and `delivery/trust.checkpoint.json`.
+   (If `publishDelivery()` pruned a superseded per-session SIBLING dir, stage that deletion
+   too — `git add -A delivery/` after the force-add. Do NOT hand-delete the flat
+   `delivery/trust.bundle` in a delivery PR while other PRs may still seal to it.)
+
+3. Commit the verified diff, including the force-added `delivery/<slug>/` trust artifacts.
 4. Push the branch.
+
+   > **⚠ LOUD FAILURE MODE — a DIRTY PR gets NO CI, silently (#335/#379).** If `main` moves
+   > under your open PR and produces a merge conflict, GitHub marks the PR `DIRTY` and
+   > **schedules NO `pull_request` workflows for it** — zero checks, no error, nothing. The
+   > required **Trust Reconcile** gate then silently never runs, and the PR sits unbuildable
+   > looking like "CI vanished" rather than "conflict." Per-session delivery paths (#379)
+   > remove the STRUCTURAL cause for delivery-artifact conflicts (concurrent seals no longer
+   > share a file), but ANY other same-file conflict with `main` can still trigger it.
+   > **Diagnose it explicitly — do not assume a missing required check means "not run yet":**
+   >
+   > ```bash
+   > gh pr view <pr> --json mergeStateStatus,mergeable,statusCheckRollup
+   > ```
+   >
+   > `mergeStateStatus: DIRTY` (or `CONFLICTING`) with an ABSENT Trust Reconcile check is the
+   > signature. Fix by rebasing/merging `main` to clear the conflict and re-pushing — that
+   > re-triggers the `pull_request` workflows. A green-looking PR with the required gate simply
+   > MISSING is not "pending"; it is this failure mode until proven otherwise.
 5. Open or update the provider change record with issue links, closing refs, evidence links, and verification summary, or record an explicit no-provider-change reason.
 6. Wait for provider checks/CI or record missing checks as `NOT_VERIFIED`.
 7. Record the gate claim for the Builder Kit `pr-open` step immediately after the PR is opened or updated:

package/kits/builder/skills/design-probe/SKILL.md

@@ -24,6 +24,16 @@ This skill is modeled after Matt Pocock's `grill-me`: interview the user relentl
 - Stop when shared understanding exists, or when the remaining uncertainty is explicitly recorded as an accepted gap.
 - Do not silently convert uncertainty into implementation work.
 
+## Model Routing
+
+When this skill delegates its probing/alignment work, resolve the
+`delegate-design` role from `.datum/config.json`
+(`npx @kontourai/datum resolve delegate-design --json`) and pass the resolved
+model explicitly — probing a goal, design, or recovery path needs design
+latitude, so it routes to the design tier. See
+`context/contracts/execution-contract.md` § Delegation: Model Routing. Fallback:
+inherit the session model when datum/config is absent, noted in the artifact.
+
 ## When To Use
 
 Use this skill for:

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

@@ -13,6 +13,19 @@ Plan artifact in, implemented code out. Fans out to tool-worker subagents in par
 |---|---|
 | tool-worker | Implementation per task spec (up to 4 parallel) |
 
+## Model Routing
+
+Worker slices (`tool-worker`) route by task shape: `delegate-implementation` for
+precisely-planned implementation (the default), `delegate-mechanical` for
+fully-specified mechanical slices (issue sync, doc/scan bookkeeping),
+`delegate-design` when a slice genuinely needs design latitude. Resolve the role
+from `.datum/config.json` (`npx @kontourai/datum resolve <role> --json`) and pass
+the model explicitly. On a review/verify gate failure of a slice, re-dispatch its
+fix one tier higher and record the escalation. See
+`context/contracts/execution-contract.md` § Delegation: Model Routing (and
+§ Escalation on gate failure). Fallback: inherit the session model when
+datum/config is absent, noted in the artifact.
+
 ## Orchestrator Rule
 
 You do not write source files. You read the plan artifact, fan out tasks to tool-worker, and update the session file between waves.

package/kits/builder/skills/fix-bug/SKILL.md

@@ -20,6 +20,23 @@ Inherited from primitives + diagnosis:
 | tool-verifier | verify-work |
 | tool-playwright | diagnosis (reproduce) + verify-work |
 
+## Model Routing
+
+Delegates are spawned with an explicit model override resolved from
+`.datum/config.json` via `npx @kontourai/datum resolve <role> --json` — see
+`context/contracts/execution-contract.md` § Delegation: Model Routing:
+
+| Delegate | Role |
+|---|---|
+| tool-worker | `delegate-mechanical` for fully-specified mechanical slices, `delegate-implementation` for precisely-planned implementation, `delegate-design` when a slice needs design latitude |
+| tool-planner | `delegate-design` |
+| tool-code-reviewer / tool-security-reviewer | `delegate-implementation` by default, raised to the worker's tier when higher — never below the tier of the checked work (Goodhart guard) |
+| tool-verifier / tool-playwright | `delegate-implementation` by default, raised to the worker's tier when higher — never below the tier of the checked work (Goodhart guard) |
+
+On a review/verify gate failure, re-dispatch the fix one tier higher and record
+the escalation (contract § Escalation on gate failure). Fallback: inherit the
+session model when datum/config is absent, noted in the artifact.
+
 ## Orchestrator Rule
 
 You never use `read`, `glob`, `grep`, or `code` on source files. All codebase analysis goes through tool-planner. All review goes through review-work. All verification goes through tool-verifier or tool-playwright.

package/kits/builder/skills/idea-to-backlog/SKILL.md

@@ -21,6 +21,16 @@ Convert raw ideas into shaped, prioritized, executable backlog without starting
 - Keep separate ideas separate until a shared outcome, hard dependency, or sequencing reason justifies bundling them.
 - Push back when the user blends unrelated ideas, and ask them to justify why the ideas belong together before shaping bundled work.
 
+## Model Routing
+
+When this skill delegates its shaping work (opportunity review, option
+exploration, slicing), resolve the `delegate-design` role from
+`.datum/config.json` (`npx @kontourai/datum resolve delegate-design --json`) and
+pass the resolved model explicitly — shaping a raw idea into a backlog needs
+design latitude, so it routes to the design tier. See
+`context/contracts/execution-contract.md` § Delegation: Model Routing. Fallback:
+inherit the session model when datum/config is absent, noted in the artifact.
+
 ## Artifact Contract
 
 Create or update `.kontourai/flow-agents/<slug>/<slug>--idea-to-backlog.md` with:

package/kits/builder/skills/plan-work/SKILL.md

@@ -13,6 +13,15 @@ Goal + directory in, structured plan artifact out. Pure planning primitive.
 |---|---|
 | tool-planner | Codebase analysis, structured execution plan, writes plan artifact |
 
+## Model Routing
+
+Planning delegation (`tool-planner`) resolves the `delegate-design` role from
+`.datum/config.json` (`npx @kontourai/datum resolve delegate-design --json`) and
+passes the resolved model explicitly — turning a goal into a plan needs design
+latitude, so it routes to the design tier. See
+`context/contracts/execution-contract.md` § Delegation: Model Routing. Fallback:
+inherit the session model when datum/config is absent, noted in the artifact.
+
 ## Orchestrator Rule
 
 You do not read source files. You delegate to tool-planner and read the artifact it produces.

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

@@ -26,6 +26,16 @@ Select ready backlog work and prepare a bounded execution handoff without implem
 - Every pull-work artifact must correlate to selected backlog refs, shepherding refs for active PRs/sidecars/issues being finished before new work, or `backlog_gap=true` with a route to `idea-to-backlog`; direct audits with no new selection must record `shepherding_item_ids` or `backlog_gap`, not free-floating implementation scope.
 - A stale broad continuation instruction, such as "keep going", "pick up the next two", or "continue after merge", may allow queue inspection but must not bypass per-item pickup Probe evidence.
 
+## Model Routing
+
+Board selection, WIP/shepherding scans, dependency joins, liveness preflight, and
+issue-sync-style bookkeeping are fully-specified mechanical work: when this skill
+delegates them, resolve the `delegate-mechanical` role from `.datum/config.json`
+(`npx @kontourai/datum resolve delegate-mechanical --json`) and pass the resolved
+model explicitly. See `context/contracts/execution-contract.md` § Delegation:
+Model Routing. Fallback: inherit the session model when datum/config is absent,
+noted in the artifact.
+
 ## Inputs
 
 - Repository or working directory.

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

@@ -29,6 +29,17 @@ Keeping them separate makes failures route cleanly:
 | tool-dependencies-updater | Dependency review when package manifests, dependency manifests, package manager config, or lockfiles change |
 | configured architecture/domain/IaC/policy reviewer | Optional reviewer when the project or user configures one |
 
+## Model Routing
+
+Review roles never resolve **below** the tier of the work they check (Goodhart
+guard): default `delegate-implementation`, raised to match or exceed the tier
+that produced the work under review — a reviewer of `delegate-design` work
+resolves `delegate-design` or `orchestrator`, never a cheaper tier. Resolve the
+role from `.datum/config.json` (`npx @kontourai/datum resolve <role> --json`) and
+pass the model explicitly. See `context/contracts/execution-contract.md`
+§ Delegation: Model Routing and § Goodhart guard. Fallback: inherit the session
+model when datum/config is absent, noted in the artifact.
+
 ## Shared Contracts
 
 Follow:

package/kits/builder/skills/tdd-workflow/SKILL.md

@@ -25,6 +25,23 @@ Same as deliver (inherited from primitives):
 | tool-verifier | verify-work (with coverage check) |
 | tool-playwright | verify-work (if UI) |
 
+## Model Routing
+
+Delegates are spawned with an explicit model override resolved from
+`.datum/config.json` via `npx @kontourai/datum resolve <role> --json` — see
+`context/contracts/execution-contract.md` § Delegation: Model Routing:
+
+| Delegate | Role |
+|---|---|
+| tool-worker | `delegate-mechanical` for fully-specified mechanical slices, `delegate-implementation` for precisely-planned implementation (RED/GREEN/REFACTOR), `delegate-design` when a slice needs design latitude |
+| tool-planner | `delegate-design` |
+| tool-code-reviewer / tool-security-reviewer | `delegate-implementation` by default, raised to the worker's tier when higher — never below the tier of the checked work (Goodhart guard) |
+| tool-verifier / tool-playwright | `delegate-implementation` by default, raised to the worker's tier when higher — never below the tier of the checked work (Goodhart guard) |
+
+On a review/verify gate failure, re-dispatch the fix one tier higher and record
+the escalation (contract § Escalation on gate failure). Fallback: inherit the
+session model when datum/config is absent, noted in the artifact.
+
 ## Orchestrator Rule
 
 Same as deliver: you never touch source files. You coordinate the primitives with TDD-specific context.

package/kits/builder/skills/verify-work/SKILL.md

@@ -16,6 +16,17 @@ Verification is not critique. Run `review-work` first when the task needs mainta
 | tool-verifier | Code verification, acceptance criteria checking, structured verdicts |
 | tool-playwright | Visual verification, screenshots, accessibility checks |
 
+## Model Routing
+
+Verify roles never resolve **below** the tier of the work they check (Goodhart
+guard): default `delegate-implementation`, raised to match or exceed the tier
+that produced the work under verification — a verifier of `delegate-design` work
+resolves `delegate-design` or `orchestrator`, never a cheaper tier. Resolve the
+role from `.datum/config.json` (`npx @kontourai/datum resolve <role> --json`) and
+pass the model explicitly. See `context/contracts/execution-contract.md`
+§ Delegation: Model Routing and § Goodhart guard. Fallback: inherit the session
+model when datum/config is absent, noted in the artifact.
+
 ## Orchestrator Rule
 
 You do not review source files. You delegate to tool-verifier and tool-playwright, then read the verdict artifact.