@kontourai/flow-agents 2.4.0 → 3.1.0

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 ────
@@ -2791,6 +2800,85 @@ else
   _fail "trust.bundle capture-authoritative setup failed: $(cat "$TMPDIR_EVAL/tb-capture-evidence.out" "$TMPDIR_EVAL/tb-capture-evidence.err")"
 fi
 
+# ---- #347: hard cutover -- an unstamped (pre-#344) claim in a session trust bundle is a loud,
+# typed error; checksFromBundle/critiquesFromBundle carry NO claimType-derivation fallback (that
+# fallback WAS the #268 defect kept reachable). ----------------------------------------------
+TB_UNSTAMPED_DIR="$TMPDIR_EVAL/repo/.kontourai/flow-agents/trust-bundle-unstamped"
+mkdir -p "$TB_UNSTAMPED_DIR"
+cp "$ARTIFACT_DIR/auto-sidecars--deliver.md" "$TB_UNSTAMPED_DIR/trust-bundle-unstamped--deliver.md"
+flow_agents_node "$WRITER" init-plan "$TB_UNSTAMPED_DIR/trust-bundle-unstamped--deliver.md" \
+  --source-request "Unstamped bundle regression fixture." \
+  --summary "Unstamped bundle regression fixture." \
+  --next-action "Seed a stamped check, then strip its origin stamp to simulate a pre-#344 bundle." \
+  --timestamp "2026-05-09T00:00:00Z" >"$TMPDIR_EVAL/tb-unstamped-init.out" 2>"$TMPDIR_EVAL/tb-unstamped-init.err"
+flow_agents_node "$WRITER" record-evidence "$TB_UNSTAMPED_DIR" \
+  --verdict pass \
+  --check-json '{"id":"tb-unstamped-check","kind":"test","status":"pass","summary":"Stamped check, about to be corrupted."}' \
+  --timestamp "2026-05-09T00:01:00Z" >"$TMPDIR_EVAL/tb-unstamped-evidence.out" 2>"$TMPDIR_EVAL/tb-unstamped-evidence.err"
+
+# Simulate a pre-#344 bundle by stripping the origin/check_kind stamp from every claim -- never
+# done by hand-editing production sessions, only here to recreate the on-disk shape of a bundle
+# recorded before #344 shipped stamping.
+export UNSTAMPED_TARGET="$TB_UNSTAMPED_DIR/trust.bundle"
+node --input-type=module <<NODEOF
+import { readFileSync, writeFileSync } from 'node:fs';
+const target = process.env.UNSTAMPED_TARGET;
+const data = JSON.parse(readFileSync(target, 'utf8'));
+data.claims = (data.claims || []).map((c) => {
+  if (c && c.metadata && typeof c.metadata === 'object') {
+    const rest = { ...c.metadata };
+    delete rest.origin;
+    delete rest.check_kind;
+    return { ...c, metadata: rest };
+  }
+  return c;
+});
+writeFileSync(target, JSON.stringify(data, null, 2) + '\n');
+NODEOF
+
+if flow_agents_node "$WRITER" record-critique "$TB_UNSTAMPED_DIR" \
+  --id tb-unstamped-review \
+  --reviewer tool-code-reviewer \
+  --verdict pass \
+  --summary "Should never be recorded -- the bundle is unstamped." \
+  --timestamp "2026-05-09T00:02:00Z" >"$TMPDIR_EVAL/tb-unstamped-critique.out" 2>"$TMPDIR_EVAL/tb-unstamped-critique.err"; then
+  _fail "record-critique should refuse to read an unstamped (pre-#344) trust.bundle, not silently reclassify it by claimType"
+elif rg -q 'pre-supersession trust\.bundle' "$TMPDIR_EVAL/tb-unstamped-critique.out" "$TMPDIR_EVAL/tb-unstamped-critique.err" \
+  && rg -qF "$TB_UNSTAMPED_DIR" "$TMPDIR_EVAL/tb-unstamped-critique.out" "$TMPDIR_EVAL/tb-unstamped-critique.err" \
+  && rg -q 're-record evidence to regenerate' "$TMPDIR_EVAL/tb-unstamped-critique.out" "$TMPDIR_EVAL/tb-unstamped-critique.err" \
+  && rg -q 'record-evidence' "$TMPDIR_EVAL/tb-unstamped-critique.out" "$TMPDIR_EVAL/tb-unstamped-critique.err"; then
+  _pass "record-critique refuses an unstamped (pre-#344) trust.bundle: typed error names the session dir and the record-evidence remedy (no claimType-derivation fallback, #347)"
+else
+  _fail "record-critique on an unstamped bundle failed for the wrong reason: $(cat "$TMPDIR_EVAL/tb-unstamped-critique.out" "$TMPDIR_EVAL/tb-unstamped-critique.err")"
+fi
+
+# The same unstamped bundle also refuses promote (checksFromBundle) -- not just
+# record-critique/critiquesFromBundle.
+if flow_agents_node "$WRITER" promote "$TB_UNSTAMPED_DIR" --none --reason "regression probe" \
+  --timestamp "2026-05-09T00:03:00Z" >"$TMPDIR_EVAL/tb-unstamped-promote.out" 2>"$TMPDIR_EVAL/tb-unstamped-promote.err"; then
+  _fail "promote should refuse to read an unstamped (pre-#344) trust.bundle via checksFromBundle"
+elif rg -q 'pre-supersession trust\.bundle' "$TMPDIR_EVAL/tb-unstamped-promote.out" "$TMPDIR_EVAL/tb-unstamped-promote.err"; then
+  _pass "promote (checksFromBundle) also refuses an unstamped (pre-#344) trust.bundle with the same typed error"
+else
+  _fail "promote on an unstamped bundle failed for the wrong reason: $(cat "$TMPDIR_EVAL/tb-unstamped-promote.out" "$TMPDIR_EVAL/tb-unstamped-promote.err")"
+fi
+
+# (b) STAMPED bundles are unaffected: the earlier, still-stamped trust-bundle-critique fixture
+# carries the origin stamp on every claim -- the normal write path was never touched by this cutover.
+export STAMPED_TARGET="$TB_CRITIQUE_DIR/trust.bundle"
+if [[ -f "$STAMPED_TARGET" ]] && node --input-type=module <<NODEOF 2>"$TMPDIR_EVAL/tb-stamped-unaffected.err"
+import { readFileSync } from 'node:fs';
+const target = process.env.STAMPED_TARGET;
+const bundle = JSON.parse(readFileSync(target, 'utf8'));
+const unstamped = bundle.claims.filter((c) => !(c.metadata && typeof c.metadata === 'object' && typeof c.metadata.origin === 'string' && c.metadata.origin.length > 0));
+if (unstamped.length > 0) { process.stderr.write('found ' + unstamped.length + ' claim(s) with no origin stamp in a normally-written bundle\n'); process.exit(1); }
+NODEOF
+then
+  _pass "stamped bundles are unaffected: every claim in a normally-written trust bundle carries the origin stamp (#347)"
+else
+  _fail "stamped-bundle regression: $(cat "$TMPDIR_EVAL/tb-stamped-unaffected.err")"
+fi
+
 # ─── AC4: render-trust-panel projects the bundle to a standalone Surface Trust Panel (ADR 0010 Phase 3) ──
 if [[ -f "$TB_CAPTURE_DIR/trust.bundle" ]] && flow_agents_node "$WRITER" render-trust-panel "$TB_CAPTURE_DIR" --out "$TB_CAPTURE_DIR/trust-panel.html" >"$TMPDIR_EVAL/tb-panel.out" 2>"$TMPDIR_EVAL/tb-panel.err"; then
   PANEL="$TB_CAPTURE_DIR/trust-panel.html"

package/evals/run.sh

@@ -146,6 +146,8 @@ run_static() {
   bash "$EVAL_DIR/static/test_flowdef_codeowners_coverage.sh" || result=1
   echo ""
   bash "$EVAL_DIR/static/test_unit_helpers.sh" || result=1
+  echo ""
+  bash "$EVAL_DIR/static/test_knowledge_providers.sh" || result=1
   return $result
 }
 
@@ -195,6 +197,16 @@ run_integration() {
   echo ""
   bash "$EVAL_DIR/integration/test_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_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
@@ -241,6 +253,8 @@ run_integration() {
   echo ""
   bash "$EVAL_DIR/integration/test_flowdef_session_history_preservation.sh" || result=1
   echo ""
+  bash "$EVAL_DIR/integration/test_critique_supersession_roundtrip.sh" || result=1
+  echo ""
   bash "$EVAL_DIR/integration/test_flowdef_session_activation.sh" || result=1
   echo ""
   bash "$EVAL_DIR/integration/test_trust_checkpoint.sh" || result=1

package/evals/static/test_flowdef_codeowners_coverage.sh

@@ -53,4 +53,10 @@ require_codeowner "src/li""b/flow-resolver.ts" "src/li""b/flow-resolver.ts"
 require_codeowner "src/cli/workflow-sidecar.ts" "src/cli/workflow-sidecar.ts"
 require_codeowner "kits/*/flows/*.flow.json" "kits/*/flows/*.flow.json (kit FlowDefinitions)"
 
+# ADR 0022 §2: delivery/DECLARED is the no-agent-delivery exemption marker
+# scripts/ci/trust-reconcile.js reads — a self-asserted governance artifact (names
+# approved_by) that must stay owner-review-gated the same as the other verify-config/
+# anchor paths above (#301's file-level half; server-side review enforcement is #225).
+require_codeowner "delivery/DECLARED" "delivery/DECLARED (ADR 0022 §2 no-agent-delivery marker)"
+
 echo "FlowDefinition-related CODEOWNERS coverage checks passed."

package/evals/static/test_knowledge_providers.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# test_knowledge_providers.sh — Layer 1: Knowledge Store Provider contract
+# conformance + provider-agnostic health verbs (issue #317).
+#
+# Runs the node:test suites that back AC1–AC3:
+#   - 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 + promote sub-flow (node --test) ──"
+
+if node --test \
+  kits/knowledge/providers/conformance/suite.test.js \
+  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 + promote sub-flow"
+  exit 1
+fi

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/deliver/SKILL.md

@@ -20,6 +20,24 @@ Inherited from primitives:
 | tool-verifier | verify-work |
 | tool-playwright | 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 —
+that contract is the consumption instruction, `.datum/config.json` is the
+source of truth for the mapping):
+
+| Delegate | Role |
+|---|---|
+| 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` |
+
+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
 
 You never use `read`, `glob`, `grep`, or `code` on source files. You only read/write the session file and artifact files in `.kontourai/flow-agents/<slug>/`.
@@ -27,6 +45,7 @@ You never use `read`, `glob`, `grep`, or `code` on source files. You only read/w
 ## Shared Contracts
 
 Follow:
+- `context/contracts/standing-directives.md`
 - `context/contracts/artifact-contract.md`
 - `context/contracts/planning-contract.md`
 - `context/contracts/execution-contract.md`
@@ -258,6 +277,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

@@ -82,6 +82,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:

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

@@ -115,15 +115,15 @@ When the gate fails, record `--status fail` with `--expectation pickup-probe-rea
 
 
 
-## Docs And ADR Policy
+## Docs-Write Policy: Two-Delta Emission
 
-`pickup-probe` may identify durable terminology and decision gaps, but it must keep documentation changes narrow:
+`pickup-probe` may identify durable terminology and decision gaps, but it must keep documentation changes narrow. Per `context/contracts/probe-docs-write-contract.md`, a **decision subject** crystallizing during pickup probing (a durable, reusable answer to a named domain question — not an implementation detail or transient planning choice) gets both deltas in the same motion:
 
-- Update `CONTEXT.md` inline only for glossary-style durable terminology decisions, using tight one- or two-sentence definitions and `_Avoid_` terms when useful. Keep implementation details out of `CONTEXT.md`.
+- Update `CONTEXT.md` inline only for glossary-style durable terminology decisions, using tight one- or two-sentence definitions and `_Avoid_` terms when useful. Keep implementation details out of `CONTEXT.md`. Coin the subject term first if it is not already a glossary entry — vocabulary is the decision registry's topic namespace (`context/contracts/decision-registry-contract.md` § Slug rules) — or refine the existing entry when a decision changes what it says.
 - If a `CONTEXT-MAP.md` exists, update the relevant context instead of assuming the root glossary owns the term.
 - Create a lazy context file only when a resolved term or workflow concept has no existing home.
 - Do not create context files for transient planning notes, open questions, or provider snapshots.
-- Propose or create ADRs sparingly, only when all three are true: the decision is hard to reverse, surprising without context, and the result of a real trade-off.
+- Record a decision delta at `docs/decisions/<slug>.md`: consult `docs/decisions/index.md` first and propose revise-vs-create (an existing topic file, including a `needs-decision` stub, is revised in place; only an uncovered subject gets a new file), then run `npm run gen:decisions-index && npm run check:decisions`. Link this Probe's own session artifact as a `session-archive` evidence ref (transcript provenance). Never propose or create a numbered ADR — `docs/adr/` is frozen history; decisions go into the topic-keyed registry.
 - Prefer workflow artifacts for pickup decisions, unresolved questions, accepted gaps, and route reasons until the work is accepted.
 
 ## Handoff To Plan Work

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

@@ -10,6 +10,8 @@ Select ready backlog work and prepare a bounded execution handoff without implem
 ## Contract
 
 - Use `context/contracts/work-item-contract.md` as the source vocabulary for provider-backed work item shape, provider roles, and capability flags.
+- Use `context/contracts/assignment-provider-contract.md` as the second source vocabulary for durable ownership: the `AssignmentProvider` operations (`claim`/`release`/`supersede`/`status`/`list`), the assignment ⋈ liveness join's effective-state enum (`held`/`reclaimable`/`human-held`/`free`), and the versioned claim-record format come from that contract, not from this skill.
+- `pull-work` may perform exactly two provider-adjacent writes at selection: the liveness claim (ADR 0012, ephemeral, local runtime presence stream — see "1a. Liveness Selection Preflight" / "Liveness Claim On Selection") and the durable assignment claim (`context/contracts/assignment-provider-contract.md`, GitHub assignee/label/comment or a local-file record — see "Assignment Claim On Selection"); no other provider mutation is added to this skill.
 - Read the configured backlog provider dynamically.
 - Select one issue or a coherent issue group.
 - Do not implement code.
@@ -37,9 +39,10 @@ Create or update `.kontourai/flow-agents/<slug>/<slug>--pull-work.md` with:
 
 - `board_snapshot`: filters, issue list, labels, milestone/provider milestone state, project fields, state, blockers
 - `wip_assessment`: active work, reviews, verification, CI remediation, with personal WIP separated from global conflict context
-- `liveness_preflight`: per-candidate `{subjectId, state: held|reclaimable|free|mine, holder_actor?, status_raw}` plus `self_actor`/`self_actor_source`, computed via `liveness status --json` + `liveness whoami --json`; `self_actor` is captured exactly once per pull-work pass and pinned for reuse (see "1a. Liveness Selection Preflight" and "Liveness Claim On Selection" — never re-derived per claim call); this is the liveness-only projection of ADR 0021 §1's join, pending #290's assignment dimension
+- `liveness_preflight`: per-candidate `{subjectId, state: held|reclaimable|human-held|free|mine, holder_actor?, status_raw, effective_reason?}` plus `self_actor`/`self_actor_source`, computed via `liveness status --json` + `liveness whoami --json` joined with `assignment-provider status`'s `effective_state`/`reason` (see "1a. Liveness Selection Preflight"); `self_actor` is captured exactly once per pull-work pass and pinned for reuse (see "1a. Liveness Selection Preflight" and "Liveness Claim On Selection" — never re-derived per claim call); this is now the **full** ADR 0021 §1 `assignment ⋈ liveness` join (previously liveness-only pending #290 — #290 has landed)
 - `reclaimable_override`: recorded only when a `reclaimable` (stale) candidate is selected, or when `--force`/an explicit user instruction overrides a `held` exclusion — the explicit opt-in decision and its stated reason (see "1a. Liveness Selection Preflight")
 - `liveness_claim`: per selected item, `{subjectId, actor, emitted_at, ttl_seconds}`; on any claim-emit failure, `{skipped: <stderr reason>}` instead — fail-open (never block selection on a liveness-emit failure) but never silent: the skip reason is also surfaced in pull-work's user-facing output, and an unresolved-actor failure additionally names the remediation (`--actor <id>` / `FLOW_AGENTS_ACTOR=<id>` / a supported runtime), matching ADR 0012; also carries an optional `post_claim_conflict: {other_actor, detected_at}` when the post-claim re-check (see "Post-Claim Conflict Re-check") detects a double-hold
+- `assignment_claim`: per selected item, `{provider: "github"|"local-file", subject_id, actor, command_evidence, confirmed_status}` — the durable-claim analog of `selected_item_ids`: provider kind, subject id, actor, the rendered/executed command evidence (`gh_commands`/`claim_comment_body` for `github`, the local-file `claim` invocation for `local-file`), and the confirmed `assignment-provider status` result for each selected item, recorded once the post-claim confirmation in "Assignment Claim On Selection" succeeds; see `context/contracts/assignment-provider-contract.md` for the underlying claim-record shape
 - `my_active_work`: local worktrees, dirty branches, open PRs by the current user, active sidecars, and in-flight review/verification/release work owned by the current user
 - `shepherding_candidates`: personal PRs, worktrees, or sidecars that should be reviewed, fixed, published, merged, abandoned, or cleaned before starting more work
 - `stale_worktrees`: worktrees with no open PR, no recent activity, merged/abandoned branches, or unclear ownership that need an explicit keep/remove decision
@@ -136,18 +139,33 @@ For each ready candidate, derive `subjectId` via:
 npm run workflow:sidecar -- resolve-slug <owner>/<repo>#<issue-number>
 ```
 
-then group all rows for that `subjectId` by subject (classify per subject, not per row) and classify in this precedence order, reading each row's raw `status` field (never `label`):
+then group all rows for that `subjectId` by subject (classify per subject, not per row), reading each row's raw `status` field (never `label`). Detect the liveness-only double-hold case first, before computing the full assignment ⋈ liveness join below: when a `verified` row for an actor other than self and a `verified` row for the resolved self actor both exist on the same subject, that is a double-hold — surface it as `held` plus an explicit conflict warning (per ADR 0012 §4 detection: "a false-stale double-hold ... is detected ... not prevented"), never silently resolve it to `mine`.
 
-1. a `verified` row for an actor other than self ⇒ `held`, excluded from the ready set by default, even when a `verified` row for the resolved self actor also exists on the same subject — that combination is a double-hold: surface it as `held` plus an explicit conflict warning (per ADR 0012 §4 detection: "a false-stale double-hold ... is detected ... not prevented"), never silently resolve it to `mine`.
-2. else, a `verified` row for the resolved self actor ⇒ `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.
-3. else, a `stale` row (any actor) ⇒ `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.
-4. else (a `revoked`-only row, a `superseded` row, or no row at all) ⇒ `free`, offered normally — except a `superseded` row is surfaced but never auto-selected (full takeover semantics are #294; this is an accepted gap, not silently ignored).
+Otherwise, compute the full ADR 0021 §1 `assignment ⋈ liveness` join per candidate via `assignment-provider status` (using the effective provider kind, repo, artifact root, `label_name`, and `claim_comment_marker` from `effective-assignment-provider-settings` — see "Assignment Claim On Selection" below — joined against the same liveness stream already read above):
 
-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`).
+```bash
+npm run assignment-provider -- status \
+  --provider <github|local-file> \
+  --subject-id <subjectId> \
+  --liveness-stream <path-to-events.jsonl> \
+  --self-actor <self_actor>
+  # github: --issue-json <path-to-gh-issue-view-json|-> --label-name <label> --claim-comment-marker <marker>
+  # local-file: --artifact-root <dir>
+```
+
+Read the returned `.effective.effective_state` and `.effective.reason` and classify in this precedence order:
+
+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).
+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.
 
-This preflight computes the **liveness-only** projection of ADR 0021 §1's `assignment ⋈ liveness` join. The assignment dimension is #290's `AssignmentProvider` (durable GitHub-side claim); until it lands, assignment is treated as always-unassigned, which ADR 0021 §1's own table shows is safe because staleness — not assignment — is what excludes.
+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.
 
-`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 existing no-provider-mutation rule (see below) is unchanged by this slice. #290 will add the one narrow, audited GitHub-side mutation that pairs with this liveness emit.
+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.
+
+`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
 
@@ -260,7 +278,57 @@ Branch on the returned `winner.actor`:
 - If `winner.actor !== self_actor`, this session is the loser: immediately run `npm run workflow:sidecar -- liveness release <subjectId> --actor <self_actor>`, extend `post_claim_conflict` with `{verdict_reason, winner_actor, conceded: true}`, and return to `### 3. Select Work` to reselect within the same `pull-work` pass — excluding the just-released subject — before any handoff to `plan-work`.
 - If `winner.actor === self_actor`, this session wins: record the verdict for transparency (`{verdict_reason, winner_actor: self_actor, conceded: false}`) in `post_claim_conflict` and proceed normally; do not release.
 
-Honesty note: this re-check narrows, but does not close, the read-then-write race between the preflight's read and the claim's write. The verdict-and-release loop above closes the "detected but advisory-only" gap ADR 0012 §4 names for THIS session's own double-hold — the loser deterministically concedes and re-selects within the same pass, a new convergence guarantee this slice adds — but it still does not provide true mutual exclusion across the read-then-write race window itself; that residual is unchanged from before. True mutual exclusion arrives with the provider assignment lease (#290) and the `verify-hold` publish gate (#293).
+Honesty note: this re-check narrows, but does not close, the read-then-write race between the preflight's read and the claim's write. The verdict-and-release loop above closes the "detected but advisory-only" gap ADR 0012 §4 names for THIS session's own double-hold — the loser deterministically concedes and re-selects within the same pass, a new convergence guarantee this slice adds — but it still does not provide true mutual exclusion across the read-then-write race window itself; that residual is unchanged from before. `#290`'s provider assignment lease closes this gap for the **local-file** provider only: `claim`/`release`/`supersede` there are wrapped in a per-subject `mkdir`-lock (atomic create, EEXIST-spin, staleness reclaim), so two concurrent local-file `claim` calls on the same subject genuinely cannot both win — true mutual exclusion, not just detection. The **GitHub** provider (assignee/label/claim-comment) remains advisory/last-writer: `render-claim`/`render-supersede` emit `gh` argv for the calling skill to run, and nothing about a GitHub issue's assignee/label/comment state gives atomic compare-and-swap across two concurrent skill invocations — the post-claim `status` re-check above still only *detects* a lost race after the fact, it does not *prevent* one. Do not read "provider assignment lease" as closing the GitHub race; only the `verify-hold` publish gate (#293), not yet implemented, would do that for GitHub.
+
+### Assignment Claim On Selection
+
+After the post-claim liveness conflict re-check above resolves (no double-hold detected, or this session won the deterministic tiebreaker and any loser has reselected) and `selected_item_ids` is otherwise ready to finalize, perform the durable assignment claim — the second and last provider-adjacent write this skill performs (see `## Contract`) — before recording `selected_item_ids` as final and before any handoff to `plan-work`.
+
+Resolve the effective assignment provider settings once per pass:
+
+```bash
+npm run effective-assignment-provider-settings -- --repo-path . --json
+```
+
+If the result is `status: ask_user`, ask the user which `AssignmentProvider` (`github` or `local-file`) to use before claiming; do not silently assume. If `status: configured`, use the returned `settings.provider.kind`, `settings.provider.repo`, `settings.policy.label_name`, and `settings.policy.claim_comment_marker` for every call below.
+
+For each selected item's `subjectId` (the same `subjectId` resolved via `resolve-slug` and used throughout this pass):
+
+- **`kind: "github"`**: build an `--input-json` payload with `repo` (`{owner, name}`), `issue_number`, `assignee_login` (the current actor's GitHub login when known), `existing_assignee_login` and `existing_comment_id` (only when superseding an already-recorded `reclaimable`/confirmed `human-held` candidate — otherwise omit), `label_name`, `claim_comment_marker`, `ttl_seconds`, `branch`, and `artifact_dir`, then render:
+
+  ```bash
+  npm run assignment-provider -- render-claim \
+    --provider github \
+    --subject-id <subjectId> \
+    --input-json <path> \
+    --actor-json <path>
+  ```
+
+  Execute every command in the returned `gh_commands` array **verbatim** via the Bash tool, in order — never freehand `gh` text. Each `gh_commands` entry is an **argv array** (one element per argument, e.g. `["gh", "issue", "comment", "9101", "--repo", "kontourai/flow-agents", "--body", "..."]`) and MUST be executed as argv — every element passed as its own separate Bash-tool argument — **never** concatenated into a single shell-command string, and **never** run via `bash -c "..."` or any other shell re-interpretation of the joined elements. `claim_comment_body` (and, when superseding, `previous_record`) can carry attacker-influenced text (see the GitHub claim-record sanitization note in `context/contracts/assignment-provider-contract.md`); concatenating argv elements into a shell string before execution would reintroduce a shell-injection surface this render/execute split is designed to avoid. Record the rendered `record`, `claim_comment_body`, and each executed `gh_commands` entry as evidence.
+
+- **`kind: "local-file"`**: call the local-file `claim` subcommand directly — no render step, since this is the one path that performs real I/O inside the CLI itself:
+
+  ```bash
+  npm run assignment-provider -- claim \
+    --provider local-file \
+    --artifact-root <artifact-root> \
+    --subject-id <subjectId> \
+    --branch <branch> \
+    --artifact-dir <artifact_dir> \
+    --actor-json <path>
+  ```
+
+  A non-zero exit (already claimed by a different actor) must not be silently retried or overwritten — treat it exactly like a `held`/`reclaimable` conflict and return to `### 3. Select Work` to reselect.
+
+Then, regardless of provider kind, re-fetch current state — re-fetch the GitHub issue via `gh issue view --json assignees,labels,comments` for `github` (the local-file record is already current on disk) — and call `assignment-provider status` again, passing the same pinned `self_actor`, to **confirm** the claim landed before treating `selected_item_ids` as final:
+
+```bash
+npm run assignment-provider -- status --provider <github|local-file> --subject-id <subjectId> --self-actor <self_actor> ...
+```
+
+Confirm `effective.effective_state === "held"` with `effective.reason === "self_is_holder"` (the join function's signal that this session's own actor is the confirmed holder). Only after this confirmation does `selected_item_ids` become final for handoff. If confirmation fails — the claim did not land, or a different actor's record now appears — treat this exactly like a liveness double-hold: do not proceed to `plan-work` with this subject; return to `### 3. Select Work` to reselect, excluding the contested subject.
+
+Record the render/status evidence — provider kind, subject id, actor, the rendered/executed command(s), and the confirmed `status()` result — for every selected item under `selection` and in the dedicated `assignment_claim` artifact field (see Artifact Contract above).
 
 ### 4. Anchor Check