@kontourai/flow-agents 3.1.0 → 3.3.0

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
 }
 
@@ -197,14 +199,22 @@ run_integration() {
   echo ""
   bash "$EVAL_DIR/integration/test_actor_identity.sh" || result=1
   echo ""
+  bash "$EVAL_DIR/integration/test_ci_actor_identity.sh" || result=1
+  echo ""
   bash "$EVAL_DIR/integration/test_assignment_provider_local_file.sh" || result=1
   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
   echo ""
+  bash "$EVAL_DIR/integration/test_verify_hold.sh" || result=1
+  echo ""
+  bash "$EVAL_DIR/integration/test_takeover_protocol.sh" || result=1
+  echo ""
   bash "$EVAL_DIR/integration/test_current_json_per_actor.sh" || result=1
   echo ""
   bash "$EVAL_DIR/integration/test_liveness_heartbeat.sh" || result=1
@@ -276,12 +286,16 @@ run_integration() {
   echo ""
   bash "$EVAL_DIR/integration/test_publish_delivery.sh" || result=1
   echo ""
+  bash "$EVAL_DIR/integration/test_reconcile_preflight.sh" || result=1
+  echo ""
   bash "$EVAL_DIR/integration/test_mint_attestation.sh" || result=1
   echo ""
   bash "$EVAL_DIR/integration/test_verify_cli.sh" || result=1
   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/continue-work/SKILL.md

@@ -49,6 +49,8 @@ Before doing anything else, restore the item's durable record into context throu
 
 If no durable record exists for the item, record that gap and rely on the issue body plus merged PRs/commits as the authoritative history.
 
+If the item was taken over from a stale incumbent (a `reclaimable` selection resumed via pull-work's **Takeover Protocol**, #294 / ADR 0021 §5), restoring the durable record IS the resumption: the deterministic slug points at the incumbent's existing `.kontourai/flow-agents/<slug>/`, and you continue the incumbent's branch (the `resume_branch` from `takeover-preflight`/the supersede output) — never a new branch, never a restarted plan. Takeover is resumption, not restart.
+
 ### 2. Determine the next undone slice
 
 From the issue body plus the merged PRs and commits referencing the issue, determine which slices have **landed** and which is the **next undone slice**.

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,132 @@ 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:
+   **#356 — local reconcile-shape preflight.** `publish-delivery`/`record-release` now run a
+   local, pre-push **reconcile-shape preflight** on the session's `trust.bundle` before
+   copying anything into `delivery/`. It reuses the exact same claim-shape classification
+   `scripts/ci/trust-reconcile.js` enforces in CI (`scripts/lib/reconcile-shape.js`), so it
+   can never silently drift from what the required Trust Reconcile check actually does. If
+   the bundle is ADR-0020-invalid (e.g. a command-backed claim whose command isn't in the
+   reconcile manifest, an unwaived `assumed` claim, or an un-superseded disputed critique),
+   publish is **refused, fail-closed** — non-zero exit, a loud `REFUSING to publish` message
+   naming each invalid claim and its fix, and nothing is written to `delivery/`. This is
+   distinct from the existing fail-**soft** behavior when no `trust.bundle` exists yet at all
+   (still a silent no-op). When refused: fix the named claim (re-record evidence, add a
+   missing waiver, or supersede the disputed critique), then retry — do not attempt to push
+   past the refusal. You can also run the same check manually, any time before publish, to
+   catch a shape issue locally instead of discovering it minutes later in CI:
 
    ```bash
-   git add -f delivery/trust.bundle delivery/trust.checkpoint.json
+   npm run workflow:sidecar -- reconcile-preflight .kontourai/flow-agents/<slug>
    ```
 
-3. Commit the verified diff, including the force-added `delivery/trust.bundle` and `delivery/trust.checkpoint.json`.
+   **#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/<slug>/
+   ```
+
+   (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.)
+
+   **#293 — verify-hold gate. HARD STOP.** Before committing/pushing/opening a PR/merging,
+   run the verify-hold check (it also runs automatically inside `publish-delivery` /
+   `record-release` / `advance-state --status delivered`, but run it explicitly here BEFORE
+   committing/pushing, since by the time `record-release` runs the branch may already be
+   pushed). **The command differs by this repo's configured assignment provider kind — a bare
+   `verify-hold <slug>` with no provider flag always defaults to `--assignment-provider
+   local-file` (`runVerifyHold`'s documented default), so on a `github`-provider repo it reads
+   no local claim record and silently resolves `free`/PASS regardless of the real GitHub hold
+   state. The local-file-only invocation below is NOT sufficient for a `github`-provider repo —
+   the github branch is MANDATORY for that provider kind:**
+
+   - **local-file provider** (this repo's configured assignment provider, from
+     `effective-assignment-provider-settings`, is `local-file`):
+
+     ```bash
+     npm run workflow:sidecar -- verify-hold .kontourai/flow-agents/<slug>
+     ```
+
+   - **github provider**: render-then-execute, mirroring `pull-work`'s SKILL.md claim-side
+     pattern for the same ADR 0021 §1 join — first read the effective state (no live `gh` call
+     happens inside `workflow-sidecar.ts`; the skill renders it here), then pass the rendered
+     `.effective` JSON into `verify-hold` via `--effective-state-json`:
+
+     ```bash
+     gh issue view <issue-number> --json assignees,labels,comments > /tmp/issue.json
+     npm run assignment-provider -- status \
+       --provider github \
+       --subject-id <slug> \
+       --issue-json /tmp/issue.json \
+       --liveness-stream <path-to-events.jsonl> \
+       --self-actor <actor> \
+       > /tmp/assignment-status.json
+     npm run workflow:sidecar -- verify-hold .kontourai/flow-agents/<slug> \
+       --assignment-provider github \
+       --effective-state-json /tmp/assignment-status.json
+     ```
+
+     (`/tmp/assignment-status.json`'s top-level shape is `{ role, provider, assignment,
+     effective }`; `verify-hold --effective-state-json` reads the `.effective` field, matching
+     `assignment-provider status`'s own output shape directly — no reshaping needed.)
+
+   This is the ONE point in the whole workflow that BLOCKS instead of warns (ADR 0021 §3). It
+   asks exactly one question: is this actor still the fresh, non-superseded holder of this
+   subject (or is the subject free/self-held)? **If the check reports not-fresh-holder (exit
+   non-zero, `ok:false` in the JSON result): DO NOT commit, push, open a PR, or merge.** This
+   is a different failure mode from the `publish-delivery`/reconcile-shape preflight paragraph
+   above — that one is about the trust *bundle's shape* being invalid; this one is about
+   *actor hold* — another actor holds a fresh claim on this subject, your own claim has gone
+   stale, or the subject is assigned to a human. Do not conflate the two "REFUSING to publish"
+   messages. When refused, follow the reconcile guidance (the CLI's own `guidance` field, or
+   verbatim): re-run `pull-work`/`pickup-probe` to discover the current holder and hand off
+   cleanly (`learning-review`/handoff), or, if a human confirms this session should resume
+   ownership, run `ensure-session --supersede-stale` before retrying.
+
+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.
@@ -157,14 +167,24 @@ Read the returned `.effective.effective_state` and `.effective.reason` and class
 
 1. `effective_state: "held"` with `reason: "self_is_holder"` ⇒ `mine`: hand to `### 2. Enforce WIP And Shepherding`'s existing personal-WIP logic; do not re-offer as new, do not exclude as held-by-other.
 2. else `effective_state: "held"` (`reason: "fresh_liveness_heartbeat"` or `"liveness_claim_present_assignment_lagging"`) ⇒ excluded from the ready set by default.
-3. else `effective_state: "reclaimable"` ⇒ offered, flagged, with a warning; selecting it requires an explicit recorded opt-in (record in `reclaimable_override`, and/or `alignment_questions`), never a silent normal pick. This issue does not implement takeover — offering a `reclaimable` candidate, never auto-reclaiming it, is the correct scope boundary (Design Decision 2; full takeover protocol is ADR 0021 §5 / #294).
+3. else `effective_state: "reclaimable"` ⇒ offered, flagged, with a warning; selecting it requires an explicit recorded opt-in (record in `reclaimable_override`, and/or `alignment_questions`), never a silent normal pick. On selecting a `reclaimable` candidate, run the **Takeover Protocol** (#294, ADR 0021 §5) below — takeover is resumption, not restart: grace-beat, supersede, then continue the incumbent's branch. Never auto-reclaim without the recorded opt-in.
 4. else `effective_state: "human-held"` ⇒ surfaced, never auto-reclaimed (Design Decision 3 / ADR 0021 §6): record the assignee identity and idle duration (`effective.holder.assignee`, `effective.holder.idle_days`) in `alignment_questions` with a recommended answer (e.g. "assigned to `<assignee>`, idle `<idle_days>` days — reclaim?" recommending confirmation before proceeding), and select only on the user's explicit confirmation.
-5. else `effective_state: "free"` ⇒ offered normally — except a `superseded` liveness row (no active assignment, no fresh liveness) is surfaced but never auto-selected (full takeover semantics are #294; this is an accepted gap, not silently ignored), exactly as before this join upgrade.
+5. else `effective_state: "free"` ⇒ offered normally — including a `superseded` liveness row (no active assignment, no fresh liveness): now select-able via the **Takeover Protocol** below once the reclaimable/opt-in gate is satisfied (#294 implements the takeover semantics previously deferred here).
 
 An explicit user instruction to proceed despite a `held` or `reclaimable` classification (`--force`, "take it anyway", equivalent) overrides the exclusion/opt-in requirement; the override and its stated reason must be recorded in the artifact (`liveness_preflight`, `reclaimable_override`, and/or `priority_rationale`). A `human-held` classification is never overridden by `--force` alone — only the user's explicit answer to the recorded `alignment_questions` entry authorizes selecting it.
 
 This preflight now computes the **full** ADR 0021 §1 `assignment ⋈ liveness` join (previously liveness-only, pending #290): the assignment dimension is `#290`'s `AssignmentProvider` `status()` (`context/contracts/assignment-provider-contract.md`), joined against the same liveness stream this preflight already reads.
 
+#### Takeover Protocol (#294, ADR 0021 §5) — resumption, not restart
+
+When a `reclaimable` (or `superseded`-liveness) candidate is selected WITH the recorded opt-in, take it over by resuming the incumbent's work — never by starting a parallel branch or replanning. This is render-don't-execute: the CLI computes the decision and emits the exact steps; you run them.
+
+1. **Preflight:** `npm run workflow:sidecar -- takeover-preflight .kontourai/flow-agents/<slug>`. It returns `{action, effective_state, holder, resume_branch, grace_seconds, next_steps}`. Only `action: "grace-then-supersede"` proceeds; `back-off` (incumbent live/revived) ⇒ STOP and reselect; `ask-first` (human-held) ⇒ do not proceed without the user's explicit answer.
+2. **Grace beat:** wait `grace_seconds` (one heartbeat interval), then **re-run `takeover-preflight`**. If it now returns `back-off`, the incumbent revived — concede and reselect (this is the AC2 race guard). Proceed only if it is still `grace-then-supersede`.
+3. **Supersede:** `npm run workflow:sidecar -- ensure-session … --supersede-stale`. It re-checks the state and REFUSES if the incumbent revived in the meantime (a live `held` is never superseded), records the audit trail ("superseded actor X, last seen T, resuming from trust bundle"), and prints `resumed_branch`.
+4. **Resume the incumbent's branch — never a new one:** `git fetch origin <resume_branch> && git checkout <resume_branch>` (the `resume_branch` from step 1/3). Re-enter the existing artifact dir (the deterministic slug points at the same `.kontourai/flow-agents/<slug>/`); restore the durable record via the resume surface (#153) and continue from `handoff.json`/plan — do NOT re-plan or restart.
+5. **Record** the takeover (superseded actor, `resume_branch`, grace outcome) in `reclaimable_override`. If the superseded incumbent later wakes, it is blocked at publish by the verify-hold gate (#293) — the takeover is authoritative.
+
 `liveness claim`/`status`/`whoami` read/write the local runtime liveness stream, never GitHub issue/label/assignee state — this is not a provider mutation, and the two-provider-writes-only invariant in `## Contract` is unchanged by this slice. `#290` adds the one narrow, audited durable assignment claim that pairs with this liveness emit — see "Assignment Claim On Selection" below.
 
 ### 2. Enforce WIP And Shepherding

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.