@kontourai/flow-agents 3.0.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/integration/test_workflow_sidecar_writer.sh

@@ -530,19 +530,28 @@ fi
 
 # AC5 (existing-session continuity): re-running ensure-session against the SAME slug from a
 # DIFFERENT actor never re-derives or overwrites the already-recorded branch (ADR 0021 §5
-# takeover continuity — resume the incumbent's branch, never a parallel one).
+# takeover continuity — resume the incumbent's branch, never a parallel one). #291's
+# ensure-session ownership guard now classifies alpha's still-fresh-assignment/no-liveness
+# claim as `reclaimable` and refuses gamma's entry without an explicit takeover — so this
+# takeover is made explicit via --supersede-stale (ADR 0021 §5's grace-beat/auto-resume
+# protocol is still #294's scope; #291 only wires the explicit, caller-invoked takeover path).
+# The supersede updates the ASSIGNMENT record's actor (assignment/<slug>.json), never
+# state.json — state.json's `branch` field (and the rest of state.json) must stay exactly
+# alpha's, proving the takeover resumes the incumbent's branch rather than reforking one for
+# gamma.
 if flow_agents_node "$WRITER" ensure-session \
   --artifact-root "$SESSION_ROOT" \
   --task-slug branch-derive-a \
   --actor test-actor-gamma \
+  --supersede-stale \
   --source-request "A takeover by a different actor must not refork the branch." \
   --summary "Resuming actor gamma should inherit alpha's already-recorded branch." \
   --timestamp "2026-05-09T00:03:12Z" >"$TMPDIR_EVAL/branch-no-rederive.out" 2>"$TMPDIR_EVAL/branch-no-rederive.err" \
   && rg -q '"branch": "agent/test-actor-alpha/branch-derive-a"' "$BRANCH_DERIVE_A_DIR/state.json" \
   && ! rg -q 'test-actor-gamma' "$BRANCH_DERIVE_A_DIR/state.json"; then
-  _pass "sidecar writer never re-derives an existing session's branch for a later actor (AC5, ADR 0021 §5)"
+  _pass "sidecar writer's explicit --supersede-stale takeover (#291) never re-derives or overwrites an existing session's branch for the new actor (AC5, ADR 0021 §5)"
 else
-  _fail "sidecar writer re-derived or overwrote an existing session's branch on takeover: $(cat "$TMPDIR_EVAL/branch-no-rederive.out" "$TMPDIR_EVAL/branch-no-rederive.err")"
+  _fail "sidecar writer's explicit --supersede-stale takeover re-derived or overwrote an existing session's branch: $(cat "$TMPDIR_EVAL/branch-no-rederive.out" "$TMPDIR_EVAL/branch-no-rederive.err")"
 fi
 
 # ─── #309: init-plan (and advance-state) must never drop an already-recorded branch ────

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,8 +203,14 @@ 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
+  echo ""
+  bash "$EVAL_DIR/integration/test_current_json_per_actor.sh" || result=1
+  echo ""
   bash "$EVAL_DIR/integration/test_liveness_heartbeat.sh" || result=1
   echo ""
   bash "$EVAL_DIR/integration/test_pull_work_liveness_preflight.sh" || result=1
@@ -278,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_knowledge_providers.sh

@@ -6,18 +6,27 @@
 #   - providers/conformance/suite.test.js       (AC3: all three providers conform)
 #   - providers/health/health-pass.test.js      (AC1: vault+git-repo reports;
 #                                                 AC2: work-item seeded dupe + broken blocker)
+#   - promote/promote.test.js                    (issue #313 knowledge promote sub-flow:
+#                                                 AC1 draft delta+provenance, AC2 contradiction
+#                                                 report+merge proposal, AC3 zero external writes)
+#   - providers/neo4j/neo4j.test.js              (issue #327 neo4j provider, CI-safe: sync
+#                                                 idempotency AC1, canonical queries AC3, degradation
+#                                                 AC4 — via an injected fake driver, no Docker.
+#                                                 Live Neo4j integration.test.js is gated on NEO4J_URI.)
 # Deterministic, dependency-free, fixture-driven — never touches a real board.
 set -uo pipefail
 ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
 cd "$ROOT_DIR"
 
-echo "── Knowledge store provider conformance + health (node --test) ──"
+echo "── Knowledge store provider conformance + health + promote sub-flow (node --test) ──"
 
 if node --test \
   kits/knowledge/providers/conformance/suite.test.js \
-  kits/knowledge/providers/health/health-pass.test.js; then
-  echo "  PASS: knowledge store provider conformance + health verbs"
+  kits/knowledge/providers/health/health-pass.test.js \
+  kits/knowledge/promote/promote.test.js \
+  kits/knowledge/providers/neo4j/neo4j.test.js; then
+  echo "  PASS: knowledge store provider conformance + health verbs + promote sub-flow"
 else
-  echo "  FAIL: knowledge store provider conformance + health verbs"
+  echo "  FAIL: knowledge store provider conformance + health verbs + promote sub-flow"
   exit 1
 fi

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/evals/static/test_workflow_skills.sh

@@ -101,6 +101,8 @@ BACKLOG_PROVIDER_SETTINGS_SCHEMA="$ROOT/schemas/backlog-provider-settings.schema
 VERIFICATION_CONTRACT="$ROOT/context/contracts/verification-contract.md"
 REVIEW_CONTRACT="$ROOT/context/contracts/review-contract.md"
 DELIVERY_CONTRACT="$ROOT/context/contracts/delivery-contract.md"
+DECISION_REGISTRY_CONTRACT="$ROOT/context/contracts/decision-registry-contract.md"
+PROBE_DOCS_WRITE_CONTRACT="$ROOT/context/contracts/probe-docs-write-contract.md"
 EFFECTIVE_BACKLOG_SETTINGS="$ROOT/src/cli/effective-backlog-settings.ts"
 PULL_WORK_PROVIDER="$ROOT/src/cli/pull-work-provider.ts"
 PULL_WORK_PROVIDER_INTEGRATION="$ROOT/evals/integration/test_pull_work_provider.sh"
@@ -188,6 +190,8 @@ require_file "$PLANNING_CONTRACT" "planning contract"
 require_file "$EXECUTION_CONTRACT" "execution contract"
 require_file "$SANDBOX_CONTRACT" "sandbox policy contract"
 require_file "$GOVERNANCE_ADAPTER_CONTRACT" "governance adapter contract"
+require_file "$DECISION_REGISTRY_CONTRACT" "decision registry contract"
+require_file "$PROBE_DOCS_WRITE_CONTRACT" "probe docs-write contract"
 require_file "$WORK_ITEM_CONTRACT" "work item contract"
 require_file "$BACKLOG_PROVIDER_SETTINGS" "backlog provider settings"
 require_file "$BACKLOG_PROVIDER_SETTINGS_SCHEMA" "backlog provider settings schema"
@@ -754,8 +758,17 @@ require_text "$PICKUP_PROBE" 'planned-base drift summary and drift classificatio
 require_text "$PICKUP_PROBE" 'Update `CONTEXT.md` inline only for glossary-style durable terminology decisions' "pickup-probe limits CONTEXT.md updates"
 require_text "$PICKUP_PROBE" 'Challenge glossary conflicts immediately' "pickup-probe challenges domain terminology"
 require_text "$PICKUP_PROBE" 'Create a lazy context file only when a resolved term or workflow concept has no existing home' "pickup-probe creates context lazily"
-require_text "$PICKUP_PROBE" 'ADRs sparingly, only when all three are true' "pickup-probe limits ADRs"
-require_text "$PICKUP_PROBE" 'hard to reverse, surprising without context, and the result of a real trade-off' "pickup-probe keeps ADR threshold"
+require_text "$PICKUP_PROBE" 'context/contracts/probe-docs-write-contract.md' "pickup-probe references probe docs-write contract"
+require_text "$PICKUP_PROBE" 'Never propose or create a numbered ADR' "pickup-probe never proposes numbered ADRs"
+require_text "$PICKUP_PROBE" 'Record a decision delta at .docs/decisions/<slug>\.md' "pickup-probe records decision delta"
+require_text "$PICKUP_PROBE" 'propose revise-vs-create' "pickup-probe proposes revise-vs-create against the index"
+require_text "$PICKUP_PROBE" 'session-archive. evidence ref' "pickup-probe links transcript provenance"
+require_text "$DESIGN_PROBE" 'context/contracts/probe-docs-write-contract.md' "design-probe references probe docs-write contract"
+require_text "$DESIGN_PROBE" 'Docs-Write: Two-Delta Emission' "design-probe documents two-delta emission"
+require_text "$DESIGN_PROBE" 'Vocabulary delta' "design-probe documents vocabulary delta"
+require_text "$DESIGN_PROBE" 'Decision delta' "design-probe documents decision delta"
+require_text "$DESIGN_PROBE" 'Transcript provenance' "design-probe documents transcript provenance"
+require_text "$DESIGN_PROBE" 'Do not write a numbered ADR' "design-probe never proposes numbered ADRs"
 require_text "$BUILDER_SHAPE" 'Product-level auto-guidance' "builder-shape guides idea-to-backlog"
 require_text "$BUILDER_SHAPE" 'do not require them to type `idea-to-backlog`' "builder-shape hides primitive typing"
 require_text "$PULL" 'probe_status' "pull-work records machine-checkable probe status"

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:
@@ -277,6 +318,23 @@ After CI passes and the work is merged or otherwise accepted:
 2. Archive the working artifacts under `.kontourai/flow-agents/<slug>/archive/` or keep a stable link to them.
 3. Record provider records, verification evidence, durable docs targets, accepted gaps, and follow-up routing in durable docs or provider records.
 4. Promote the relevant plan, decision, evidence, and usage notes into long-lived docs such as `docs/`, `README.md`, or a project decision record.
+
+   **Assisted promotion path (Knowledge Kit `knowledge.promote` sub-flow).** Rather than
+   deciding WHAT to promote by ad-hoc judgement, run the Knowledge Kit promote sub-flow
+   (`kits/knowledge/flows/promote.flow.json`, id `knowledge.promote`) over the session
+   directory. It ingests the session's plan/evidence/critique/learnings/transcripts,
+   distills schema-valid DRAFT decision-registry deltas (per
+   `context/contracts/decision-registry-contract.md`), CONTEXT.md vocabulary additions,
+   and learning entries, links each to the PR + merge SHA + session archive + touched
+   topics, and health-checks the registry for contradictions (proposing merge-repair).
+   It is PROPOSALS-ONLY: every output lands under `<session>/proposals/` — it never writes
+   docs directly. You apply the drafts you accept, then record what was promoted where with
+   the `promote` CLI (below), which stays the recording mechanism. The sub-flow is the
+   assisted path; the `promote` claim is the gate. `knowledge.promote` is a true composable
+   FlowDefinition (a parent step can `uses_flow: "knowledge.promote"`); it is invoked here
+   from the promote step rather than nested as a builder gate because the `promote` CLI —
+   not a flow gate — is #312's recording mechanism and the sub-flow's outputs are proposals
+   a human/agent applies.
 5. Link the long-lived doc back to the provider record, archived plan artifact, or accepted evidence when useful so future readers can see why and how the feature was built.
 6. Confirm `.kontourai/flow-agents/` runtime artifacts remain untracked before merge to `main`.
 7. **Clean up the workspace once the merge is confirmed.** First verify the merge actually happened from the provider's own record (a merge commit / `mergedAt`) — not a green check or a watcher's exit code. Then honor the `worktree_lifecycle` recorded by `pull-work` (`retain_until: pr_merged`): remove the isolated worktree (`git worktree remove <path>`) and delete the now-merged branch locally and on the remote. Never delete a branch or worktree before the merge is confirmed — a closed-but-unmerged PR or a prematurely deleted branch loses work. The task is not done while it leaves a stale worktree or merged branch behind.

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:
@@ -82,6 +92,43 @@ Maintain a compact running record in the active artifact or conversation when no
 
 When workflow artifacts exist, update the appropriate session, handoff, Probe record, or planning artifact according to the local artifact contract. Do not invent a project-specific storage format when the repository already defines one.
 
+## Docs-Write: Two-Delta Emission
+
+Per `context/contracts/probe-docs-write-contract.md`, when a `decisions` entry above is a **decision subject** — a durable, reusable answer to a named domain question, not an implementation detail or transient planning choice — emit two deltas into durable docs in the same motion, before moving to the next branch:
+
+1. **Vocabulary delta**: the subject noun must exist as a `CONTEXT.md` glossary term. If absent, coin it first (a tight one- or two-sentence `### <Term>` entry); if present, refine the definition when the crystallized decision changes what it says (e.g. an "open" pointer becoming a stated answer).
+2. **Decision delta**: consult `docs/decisions/index.md` and propose revise-vs-create against the existing topic slugs (this includes any `needs-decision` stub already naming the subject); revise the existing topic file in place, or create `docs/decisions/<slug>.md` per `context/contracts/decision-registry-contract.md`. Run `npm run gen:decisions-index && npm run check:decisions` after writing.
+3. **Transcript provenance**: add a `session-archive` evidence ref pointing at this Probe's own session artifact (the live `.kontourai/flow-agents/<slug>/...` path — it does not need to be archived yet).
+
+Example — coining a new term and creating its topic file:
+
+```markdown
+### Retry Budget
+
+The maximum number of automatic retries a workflow step may attempt before routing back to the user. Configured per Flow Definition step, not globally.
+```
+
+```markdown
+---
+status: current
+subject: Retry budget
+decided: 2026-07-03
+evidence:
+  - kind: session-archive
+    ref: .kontourai/flow-agents/<slug>/<slug>--design-probe.md
+  - kind: issue
+    ref: https://github.com/kontourai/flow-agents/issues/<n>
+---
+
+# Retry budget
+
+Each Flow Definition step declares its own retry budget; there is no global default. Set during design-probe alignment on <n>.
+```
+
+Example — revising a `needs-decision` stub seeded by the ADR-freeze cutover (issue #314) once its frozen ADR's decision is confirmed still current: flip `status: needs-decision` to `current`, set `decided` to today, keep the existing `adr` evidence ref, and append the `session-archive` ref for this Probe session plus a `pr` ref once one exists. See `context/contracts/probe-docs-write-contract.md` § Worked Example for the full step-by-step.
+
+Do not write a numbered ADR — `docs/adr/` is frozen history (`docs/adr/README.md`); every decision delta targets the topic-keyed registry.
+
 ## Stop Conditions
 
 Stop probing when one of these is true: