@kontourai/flow-agents 2.4.0 → 3.0.0

package/evals/integration/test_workflow_sidecar_writer.sh

@@ -2791,6 +2791,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,12 @@ 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_liveness_heartbeat.sh" || result=1
   echo ""
   bash "$EVAL_DIR/integration/test_pull_work_liveness_preflight.sh" || result=1
@@ -241,6 +249,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,23 @@
+#!/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)
+# 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) ──"
+
+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"
+else
+  echo "  FAIL: knowledge store provider conformance + health verbs"
+  exit 1
+fi

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`

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
 

package/kits/knowledge/kit.json

@@ -91,6 +91,31 @@
       "id": "knowledge.obsidian-store",
       "path": "adapters/obsidian-store/index.js",
       "description": "Obsidian store adapter: each record is one human-canonical Obsidian markdown note. Frontmatter carries all contract fields; body rendered with callouts (raw), readable prose + Sources/Related wikilink sections (compiled/concept/snapshot). Category dots map to folder hierarchy; title-slugified filenames with collision suffix; superseded records move to archive/ (supersede-not-delete invariant). Backed by shared codec with default-store."
+    },
+    {
+      "id": "knowledge.markdown-vault-provider",
+      "path": "providers/markdown-vault/index.js",
+      "description": "Knowledge store PROVIDER (issue #317): adapts the markdown-vault store behind the typed graph model (nodes/edges/provenance). Thin read + proposals-only wrapper over an existing store adapter; existing skills unaffected."
+    },
+    {
+      "id": "knowledge.git-repo-provider",
+      "path": "providers/git-repo/index.js",
+      "description": "Knowledge store PROVIDER (issue #317): reads git-tracked docs (docs/decisions/* tombstones+evidence, CONTEXT.md glossary, docs/learnings/*) as decision/note nodes with supersedes/merged-into/evidence-of edges. Write side = decision-topic proposals shaped for the promote sub-flow."
+    },
+    {
+      "id": "knowledge.work-item-provider",
+      "path": "providers/work-item/index.js",
+      "description": "Knowledge store PROVIDER/source-sink adapter (issue #317): maps GitHub issues to issue nodes and flow-agents:work-item-metadata blockers + prose refs to blocks/relates edges via an injectable gh runner. Write side = draft comment/label proposals. Enables backlog hygiene as a knowledge-health pass."
+    },
+    {
+      "id": "knowledge.health-verbs",
+      "path": "providers/health/index.js",
+      "description": "Provider-agnostic knowledge-health verbs (issue #317): detectDuplicates + checkDependencyLinkIntegrity over any provider's graph, returning schema-valid health reports (schemas/knowledge/health-report.schema.json)."
+    },
+    {
+      "id": "knowledge.store-providers",
+      "path": "providers/index.js",
+      "description": "Public entry point for the knowledge store providers, health verbs, graph model helpers, and schema validator. See context/contracts/knowledge-store-contract.md."
     }
   ],
   "evals": [
@@ -153,6 +178,16 @@
       "id": "knowledge.hygiene-review-suite",
       "path": "evals/hygiene-review/suite.test.js",
       "description": "Eval cases for hygiene-review (#106 hygiene #5, closes the issue): opt-in orchestration (omitted audit block is skipped; empty review does nothing); each opted-in audit runs via its existing flow-runner method and its findings are collected verbatim (no detection reimplemented); proposals are normalized to adopt/retire/merge and each cites its sourceFlow + evidence; thin-orchestrator/consume-never-fork invariants — read-only by default mutates no record, no new gate is forked, the only mutation (glossary apply:true) is delegated to glossarySync's own gated propose→apply (verified via proposes-link + mutation-log on the resulting concept); sub-flow telemetry is folded in plus hygiene-review's own orchestrate-gate + review-gate; module-level export delegates to the runner."
+    },
+    {
+      "id": "knowledge.provider-conformance-suite",
+      "path": "providers/conformance/suite.test.js",
+      "description": "Conformance suite (issue #317, AC3): parameterized suite every knowledge store provider (markdown-vault, git-repo, work-item) must pass — read interface returns schema-valid nodes/edges with provenance, closed edge vocabulary, queryByType subset consistency, and proposeWrite returns a schema-valid 'proposed' proposal that mutates nothing (proposals-only)."
+    },
+    {
+      "id": "knowledge.provider-health-pass-suite",
+      "path": "providers/health/health-pass.test.js",
+      "description": "Health-pass suite (issue #317, AC1+AC2): the same health command over vault + git-repo providers yields schema-valid reports (AC1); a backlog pass over the work-item adapter driven by a seeded fixture flags a duplicate and a broken blocker link (AC2) — never the real board."
     }
   ],
   "skills": [

package/kits/knowledge/providers/conformance/fixtures/git-repo/CONTEXT.md

@@ -0,0 +1,12 @@
+# Fixture Context
+
+## Glossary
+
+### Widget
+
+A demonstration domain noun used by the git-repo provider conformance fixture.
+_Avoid_: Gadget
+
+### Sprocket
+
+Another fixture vocabulary term with a short definition line.

package/kits/knowledge/providers/conformance/fixtures/git-repo/docs/decisions/old-sprocket-shape.md

@@ -0,0 +1,13 @@
+---
+status: merged
+subject: Old sprocket shape
+decided: 2026-07-02
+merged_into: sprocket-shape
+evidence:
+  - kind: pr
+    ref: https://github.com/kontourai/flow-agents/pull/319
+---
+
+# Old sprocket shape
+
+Merged into [sprocket-shape](./sprocket-shape.md).

package/kits/knowledge/providers/conformance/fixtures/git-repo/docs/decisions/sprocket-shape.md

@@ -0,0 +1,14 @@
+---
+status: current
+subject: Sprocket shape
+decided: 2026-07-02
+supersedes:
+  - old-sprocket-shape
+evidence:
+  - kind: pr
+    ref: https://github.com/kontourai/flow-agents/pull/319
+---
+
+# Sprocket shape
+
+Sprockets are round. Absorbs the old-sprocket-shape topic.

package/kits/knowledge/providers/conformance/fixtures/git-repo/docs/decisions/widget-format.md

@@ -0,0 +1,14 @@
+---
+status: current
+subject: Widget format
+decided: 2026-07-01
+evidence:
+  - kind: issue
+    ref: https://github.com/kontourai/flow-agents/issues/317
+  - kind: doc
+    ref: docs/learnings/fixture-learning.md
+---
+
+# Widget format
+
+Widgets are stored as JSON. Lean rationale linked via evidence.

package/kits/knowledge/providers/conformance/fixtures/git-repo/docs/learnings/fixture-learning.md

@@ -0,0 +1,7 @@
+---
+title: "Fixture Learning"
+---
+
+# Fixture Learning
+
+A durable learning used by the git-repo provider conformance fixture.

package/kits/knowledge/providers/conformance/fixtures/work-item/issues.json

@@ -0,0 +1,30 @@
+[
+  {
+    "number": 14,
+    "title": "Add dark mode toggle to settings",
+    "state": "OPEN",
+    "labels": [{ "name": "enhancement" }],
+    "body": "Users want a dark mode toggle in the settings screen.\n\n<!-- flow-agents:work-item-metadata\n{\n  \"schema_version\": \"1.0\",\n  \"blockers\": []\n}\n-->"
+  },
+  {
+    "number": 15,
+    "title": "Add dark-mode toggle to settings page",
+    "state": "OPEN",
+    "labels": [{ "name": "enhancement" }],
+    "body": "Duplicate of the dark mode toggle request. Settings page needs a dark-mode toggle."
+  },
+  {
+    "number": 20,
+    "title": "Ship theme system",
+    "state": "OPEN",
+    "labels": [{ "name": "feature" }],
+    "body": "Overarching theme work. Relates to #14.\n\n<!-- flow-agents:work-item-metadata\n{\n  \"schema_version\": \"1.0\",\n  \"blockers\": [\n    { \"repo\": \"seed/fixture\", \"number\": 14 },\n    { \"repo\": \"seed/fixture\", \"number\": 999 }\n  ]\n}\n-->"
+  },
+  {
+    "number": 21,
+    "title": "Document theme tokens",
+    "state": "OPEN",
+    "labels": [],
+    "body": "Blocked by #20. Also see #14 for the toggle."
+  }
+]

package/kits/knowledge/providers/conformance/suite.test.js

@@ -0,0 +1,125 @@
+/**
+ * Knowledge Store Provider — Conformance Suite (issue #317, AC3).
+ *
+ * One parameterized suite every provider must pass. Proves that markdown-vault,
+ * git-repo, and work-item all satisfy the read + proposals-only interface and
+ * emit schema-valid nodes/edges/proposals. Run:
+ *   node --test kits/knowledge/providers/conformance/suite.test.js
+ */
+
+import { test, describe, before, after } from "node:test";
+import assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { MarkdownVaultProvider } from "../markdown-vault/index.js";
+import { GitRepoProvider } from "../git-repo/index.js";
+import { WorkItemProvider } from "../work-item/index.js";
+import DefaultKnowledgeStore from "../../adapters/default-store/index.js";
+import { loadSchemas, EDGE_TYPES } from "../lib/model.js";
+import { validate } from "../lib/schema-validate.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const FIXTURES = path.join(__dirname, "fixtures");
+const schemas = loadSchemas();
+
+function assertSchema(value, schema, label) {
+  const { valid, errors } = validate(value, schema);
+  assert.ok(valid, `${label} not schema-valid:\n  ${errors.join("\n  ")}`);
+}
+
+// --- per-provider fixture builders --------------------------------------
+
+async function buildVault() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "kg-vault-conf-"));
+  const store = new DefaultKnowledgeStore({ storeRoot: dir });
+  const rawId = await store.create({ type: "raw", title: "Raw source", body: "raw material", category: "eng", provenance: { agent: "test" } });
+  const compiledId = await store.create({ type: "compiled", title: "Compiled note", body: "distilled", category: "eng", provenance: { agent: "test" } });
+  await store.link(compiledId, [{ target_id: rawId, kind: "source" }], { agent: "test" });
+  const provider = new MarkdownVaultProvider({ store, storeRoot: dir, agent: "test" });
+  return { provider, proposeIntent: { title: "Proposed note", body: "content", category: "eng" }, cleanup: () => fs.rmSync(dir, { recursive: true, force: true }) };
+}
+
+async function buildGitRepo() {
+  const provider = new GitRepoProvider({ repoRoot: path.join(FIXTURES, "git-repo"), agent: "test" });
+  return { provider, proposeIntent: { subject: "Fixture decision", body: "the answer", evidence: [{ kind: "issue", ref: "#317" }] }, cleanup: () => {} };
+}
+
+async function buildWorkItem() {
+  const issues = fs.readFileSync(path.join(FIXTURES, "work-item", "issues.json"), "utf8");
+  const runner = async () => issues;
+  const provider = new WorkItemProvider({ repo: "seed/fixture", runner, agent: "test" });
+  return { provider, proposeIntent: { issue: 14, commentBody: "draft comment" }, cleanup: () => {} };
+}
+
+const PROVIDERS = [
+  { name: "markdown-vault", build: buildVault, expectedId: "markdown-vault" },
+  { name: "git-repo", build: buildGitRepo, expectedId: "git-repo" },
+  { name: "work-item", build: buildWorkItem, expectedId: "work-item" },
+];
+
+for (const { name, build, expectedId } of PROVIDERS) {
+  describe(`conformance: ${name}`, () => {
+    let ctx;
+    before(async () => { ctx = await build(); });
+    after(() => ctx.cleanup());
+
+    test("capabilities() declares proposals-only, non-writable", () => {
+      const cap = ctx.provider.capabilities();
+      assert.equal(cap.id, expectedId);
+      assert.equal(cap.writable, false);
+      assert.equal(cap.write_mode, "proposals-only");
+      assert.ok(Array.isArray(cap.proposal_targets) && cap.proposal_targets.length > 0);
+    });
+
+    test("readNodes() returns schema-valid nodes with unique ids and provider provenance", async () => {
+      const nodes = await ctx.provider.readNodes();
+      assert.ok(Array.isArray(nodes) && nodes.length > 0, "expected at least one node");
+      const ids = new Set();
+      for (const n of nodes) {
+        assertSchema(n, schemas.node, `${name} node ${n.id}`);
+        assert.equal(n.provenance.provider, expectedId);
+        assert.ok(!ids.has(n.id), `duplicate node id ${n.id}`);
+        ids.add(n.id);
+      }
+    });
+
+    test("readEdges() returns schema-valid edges in the closed edge vocabulary", async () => {
+      const edges = await ctx.provider.readEdges();
+      assert.ok(Array.isArray(edges));
+      for (const e of edges) {
+        assertSchema(e, schemas.edge, `${name} edge ${e.id}`);
+        assert.ok(EDGE_TYPES.includes(e.type), `edge type ${e.type} outside closed vocabulary`);
+        assert.equal(e.provenance.provider, expectedId);
+      }
+    });
+
+    test("queryByType() is a consistent subset of readNodes()", async () => {
+      const nodes = await ctx.provider.readNodes();
+      const types = [...new Set(nodes.map((n) => n.type))];
+      for (const t of types) {
+        const q = await ctx.provider.queryByType(t);
+        assert.ok(q.every((n) => n.type === t), `queryByType(${t}) returned off-type node`);
+        assert.equal(q.length, nodes.filter((n) => n.type === t).length);
+      }
+    });
+
+    test("readGraph() returns { nodes, edges }", async () => {
+      const g = await ctx.provider.readGraph();
+      assert.ok(Array.isArray(g.nodes) && Array.isArray(g.edges));
+    });
+
+    test("proposeWrite() returns a schema-valid 'proposed' proposal and mutates nothing", async () => {
+      const before = await ctx.provider.readNodes();
+      const p = await ctx.provider.proposeWrite(ctx.proposeIntent);
+      assertSchema(p, schemas.proposal, `${name} proposal`);
+      assert.equal(p.status, "proposed");
+      assert.equal(p.provider, expectedId);
+      assert.equal(typeof p.rendered, "string");
+      const after = await ctx.provider.readNodes();
+      assert.equal(after.length, before.length, "proposeWrite must not add nodes to the store");
+    });
+  });
+}