@kontourai/flow-agents 2.4.0 → 3.0.0

package/docs/adr/0022-fail-closed-delivery-reconciliation-with-governed-exemptions.md

@@ -281,3 +281,183 @@ ADR 0018 §Decision.
 - #274 — the issue this ADR resolves; #269 — the first live capture-backed bundle publish
   cited in Context; #265 — the last PR to merge before that (i.e. the boundary of "every PR
   before #265 passed Trust Reconcile trivially via absence").
+
+## Addendum (2026-07-03): compound `scope` (space-separated AND) — security-review hardening
+
+A security review of the #300 implementation found that `ref:`/`branch-prefix:` scope
+conditions match against `GITHUB_HEAD_REF` (or the `TRUST_RECONCILE_REF` override), and on a
+**fork PR `GITHUB_HEAD_REF` is pusher-controlled** — any contributor who can open a PR can
+name their branch to satisfy a `ref:`- or `branch-prefix:`-only scope. A `delivery/DECLARED`
+entry written to exempt one specific bot (e.g. `ref:release-please--branches--main`) is
+therefore satisfiable by anyone who pushes a branch with that exact name, not only by the
+automation it names. `author:` (bound to the platform-set `GITHUB_ACTOR`, not attacker-chosen
+in the same way) does not have this weakness alone, but a single `author:` condition cannot
+express "and also narrow the blast radius to this branch pattern" — the two properties needed
+combining, not substituting for each other.
+
+**Decision:** `scope` may contain multiple space-separated conditions, each one of the four
+forms specified in §2 (`ref:`, `commit:`/`commit:a..b`, `author:`, `branch-prefix:`); a
+compound scope matches only if **every** condition matches (AND, not OR). A single-condition
+scope is unchanged and remains valid (backward compatible — it is the N=1 case of the same
+rule). Matching is still string equality/prefix only, per condition — no `RegExp` is
+constructed from marker content in either the single- or compound-condition path. An
+unrecognized-prefix condition anywhere in a compound scope makes the **whole** scope never
+match, the same fail-closed behavior a malformed single-condition scope already had.
+
+**`ref:`/`branch-prefix:` alone are insufficient for identity exemptions and MUST be combined
+with `author:`.** Per the finding above, a scope meant to identify a specific bot/automation
+actor (as opposed to a specific commit range or branch, where the identity question does not
+arise) should not rely on `ref:`/`branch-prefix:` in isolation — combine it with `author:` so
+the platform-set actor identity, not just a self-chosen branch name, has to match too. The
+migration marker this ADR's Consequences named for release-please is updated accordingly:
+
+```json
+{
+  "scope": "author:github-actions[bot] branch-prefix:release-please--",
+  "reason": "release-please automation PR; no agent delivery involved",
+  "approved_by": "briananderson1222",
+  "declared_at": "<ISO timestamp>"
+}
+```
+
+(`dependabot[bot]`'s entry, `author:dependabot[bot]`, was already a single `author:` condition
+— security-review-confirmed sound as-is and left unchanged.)
+
+**`/delivery/DECLARED` CODEOWNERS landed with #300/#301.** `.github/CODEOWNERS` now lists
+`/delivery/DECLARED` under the same owner as `/scripts/ci/`, `/package.json`, and
+`/evals/run.sh` (§2's original intent, made concrete); `evals/static/test_flowdef_codeowners_coverage.sh`
+carries a regression-lock assertion for the entry. This closes the file-level half of #301;
+server-side enforcement of CODEOWNERS review on `main` remains tracked separately (#225).
+
+## Addendum (2026-07-03, part 2): bundle-ownership staleness check — "for THIS change"
+
+Owner-approved follow-up to the compound-scope addendum above, closing a second gap the same
+security review surfaced, this time against a **live incident**: PR #278 (the same open
+dependabot PR cited in Baseline/Consequences) carries a `delivery/trust.checkpoint.json`
+inherited byte-for-byte from `main` (dependabot never runs the deliver skill on its own
+branch — the file only exists there because `main`'s tree already had it). Prior to this
+addendum, `discoverBundle()` finding *any* file at `delivery/trust.bundle` or
+`delivery/trust.checkpoint.json` — regardless of whether it says anything about the change
+actually being reconciled — was sufficient to route into Step 2. A stale, inherited
+checkpoint from a completely unrelated prior PR would therefore either (a) reconcile
+against claims/evidence that have nothing to do with the current diff (if it were a full
+`trust.bundle`), or (b), as in the checkpoint-only case, hit the existing
+`checkpoint-bypass` divergence — **coincidentally fail-closed today only because a bare
+checkpoint has no `evidence[]`/`claims[]` to reconcile**, not because the reconciler
+recognized the file as stale. A future stale *full* `trust.bundle` (not just a checkpoint)
+inherited the same way would not have that accidental protection.
+
+**Decision:** "bundle-required" (ADR 0022 §1) means a bundle **for this change**, not any
+bundle merely reachable at the checkout. `discoverBundle()`'s result is now checked against
+a commit-identity binding before Step 2 is allowed to run against it:
+
+- **Binding chosen:** `trust.checkpoint.json`'s `commit_sha` field (stamped by
+  `sealTrustCheckpoint()` in `src/cli/workflow-sidecar.ts` from `git rev-parse HEAD` at seal
+  time) — the strongest identity signal available today. `trust.bundle` itself carries no
+  commit/branch metadata (schema: `{schemaVersion, source, claims, evidence, policies,
+  events}` — confirmed by inspection), so when the auto-discovered file is `trust.bundle`,
+  the check falls through to its sibling `delivery/trust.checkpoint.json` (same
+  `resolveDeliveryCandidates()` seam; `publishDelivery()` always writes both together).
+- **Match rule:** the bundle's `commit_sha` equals this change's own sha
+  (`TRUST_RECONCILE_SHA`/`GITHUB_SHA`), OR is a git-ancestor of it, via the same `git
+  merge-base --is-ancestor` primitive `commit:` scopes already use. Exact equality alone was
+  considered and rejected: `sealTrustCheckpoint()` necessarily stamps a commit that precedes
+  its own delivery commit (a checkpoint cannot contain its own future commit's sha), so
+  requiring exact equality would reject every legitimately fresh delivery, not just stale
+  ones. Ancestor-or-equal correctly accepts "sealed earlier in this same open PR's own
+  linear history" while — because this repo squash-merges PRs into `main` — correctly
+  rejecting a checkpoint inherited from `main`: a squash-merged commit's checkpoint records
+  the pre-squash feature-branch tip as `commit_sha`, which is provably **not** an ancestor of
+  any later branch (squash discards the original commit graph), so any checkpoint that ever
+  lands on `main` becomes permanently unmatchable by a later, unrelated branch — exactly the
+  PR #278 shape.
+- **Fail closed on ambiguity:** no extractable `commit_sha` (missing from both the bundle and
+  its sibling checkpoint), or this change's own sha unresolvable — never treated as owned. A
+  stale/unowned bundle prints a loud, grep-stable line (`stale bundle ignored — attests
+  <theirs>, this change is <ours>`) and is then treated exactly as if `discoverBundle()` had
+  returned nothing: it falls through to `delivery/DECLARED` resolution.
+- **Scope:** this check applies ONLY to **auto-discovered** bundles. An explicit
+  `--bundle`/`TRUST_RECONCILE_BUNDLE` remains untouched — it is a deliberate caller choice
+  (test fixtures, a programmatic caller passing a specific bundle), not something silently
+  picked up from committed git tree state, and the real `.github/workflows/trust-reconcile.yml`
+  never passes `--bundle`; it always relies on auto-discovery, which is exactly the path the
+  incident went through.
+
+**Residual, honestly named:** this binding is still self-reported (the checkpoint's own
+`commit_sha`, not a cryptographic commit signature) and still only as strong as
+`sealTrustCheckpoint()`'s local `git rev-parse HEAD` call — an adversarial agent that
+controls its own local git state before delivery could, in principle, stamp an arbitrary
+sha. This does not reopen the PR #278 gap (a human/bot PR that never runs the deliver skill
+at all still cannot forge a checkpoint it never writes), but it is not a full defense against
+a fully agent-controlled delivery pipeline; that class of residual is the same
+"trust-the-humans boundary" ADR 0017/0020 already name, not newly introduced here.
+
+## Addendum (2026-07-03, part 3): CI-context contract for the staleness check
+
+A re-review found a launch-blocking gap in the staleness check (Addendum part 2, above):
+`isAncestorCommit()`'s `git merge-base --is-ancestor` call is only meaningful if the CI
+checkout actually has the parent commit objects, and if the sha compared against is a
+commit a checkpoint could plausibly have been sealed at. Neither held under
+`.github/workflows/trust-reconcile.yml`'s prior configuration: the default
+`actions/checkout` fetch depth is a **shallow clone (`fetch-depth: 1`)**, which has no
+parent objects — `git merge-base` against a missing object exits 128, so the ancestor
+check would be unresolvable for every real PR, not just stale ones, falsely staling
+**every legitimately fresh delivery** on a required, admin-enforced check. Separately, on
+a `pull_request` trigger `GITHUB_SHA` resolves to GitHub's synthetic merge commit
+(`refs/pull/N/merge`), a commit that never existed at the time any real `seal-checkpoint`
+run stamped `commit_sha` — so even a correctly-resolving ancestor check would compare
+against the wrong target. Both are now fixed at the workflow layer, not by loosening the
+reconciler's own fail-closed contract: the checkout step sets `fetch-depth: 0` (full
+history), and the trust-reconcile step sets `TRUST_RECONCILE_SHA:
+${{ github.event.pull_request.head.sha || github.sha }}` so the ownership comparison
+always uses the PR's own head commit on a `pull_request` trigger (falling back to
+`github.sha`, which is already correct, on `push`/`workflow_dispatch`). The checkout ref
+itself is unchanged — Step 1 (fresh verify) runs against the same tree it always has;
+only the identity used for the Step-2 ownership comparison changes. This is a narrow,
+deliberate, owner-recorded functional amendment to the "workflow YAML: comments only"
+scoping the original Wave 1 plan set for this file — an unavoidable consequence of
+closing the HIGH finding, not scope creep. `scripts/ci/trust-reconcile.js`'s own contract
+is unchanged and stays fail-closed either way: a shallow/missing-object condition still
+resolves to "not an ancestor" (never silently accepted), so a misconfigured downstream
+adopter that keeps the shallow default degrades safely (falsely stales real bundles,
+loudly, with a diagnosable line) rather than unsafely (accepting a bundle it cannot
+actually verify).
+
+## Addendum (2026-07-03, part 4): event-scoped enforcement — gates gate PRs, not `main`
+
+Final review found a second, more severe HIGH launch-blocker in the staleness check
+(Addendum part 3, above): even with full-history checkout and correct sha binding, a
+`push` run on `main` immediately after a squash-merge would still falsely stale the
+just-merged, genuinely legitimate bundle — because `git merge --squash` (this repo's
+merge strategy) discards the original commit graph, the resulting squash commit on `main`
+has **no** git ancestry back to the feature-branch commit its checkpoint was sealed
+against, by design, not by defect. Empirically reproduced with a synthetic squash pair.
+Left unfixed, every delivery would fail the required Trust Reconcile check on `main`
+immediately post-merge, and Phase 2 attestation minting (which runs only after Step 2
+passes) would stop entirely — a regression far worse than the bug this whole ADR closes.
+
+**Decision (reviewer option (a) — enforcement is event-scoped):** bundle-required
+enforcement (§1's `bundle-required-no-declared-marker` fail-closed branch, and the
+staleness-gate consequence of it, Addendum part 2) applies only when a run is **gating a
+proposed change** — detected via `TRUST_RECONCILE_EVENT` (set from `github.event_name` by
+the workflow), with a conservative default: an absent/unrecognized event value is treated
+as gating (enforce), so every existing local/test caller and any misconfigured CI event
+keeps today's stricter behavior. Only the literal value `push` is treated as a post-merge
+run. On `push`, an absent or stale auto-discovered bundle is a loud, exit-0 no-op
+(`push event: ... — skipping Step 2 (gating happened on the PR run)`) rather than a
+failure or a `delivery/DECLARED` requirement — there is no "change" being gated on a push
+to a protected branch (direct pushes are already excluded by branch protection; a push
+run's own job is Step 1 fresh-verify, which is unaffected by this scoping and always
+runs, plus Step 2 reconcile IF the bundle happens to still attest that exact commit,
+forming the Phase 2 attestation basis). `pull_request` gating is completely unaffected —
+the exact same squash-shape fixture used to prove the push no-op also proves the
+identical shape still fails closed when `TRUST_RECONCILE_EVENT=pull_request`, confirming
+this scoping narrows *when* enforcement applies, not *how strictly* it applies when it
+does. Residual (HIGH, documented not solved): `TRUST_RECONCILE_EVENT`'s
+source value (`github.event_name`) is authoritative GitHub Actions context, but the
+workflow FILE that assigns it to the env var is itself PR-editable content on a
+`pull_request` run — a PR could hardcode `TRUST_RECONCILE_EVENT: push` in its own copy of
+the workflow to fake the post-merge no-op path; this is closed by required code-owner
+review on `.github/workflows/trust-reconcile.yml` (#225, not yet server-side enforced),
+the same residual class as every other self-asserted CI input this ADR already carries.
+Step 1 (fresh verify) is unaffected by event scoping either way and always runs.

package/docs/context-map.md

@@ -51,6 +51,7 @@ Machine-readable workflow state lives beside Markdown artifacts in `.kontourai/f
 
 | Schema | Title | ID |
 | --- | --- | --- |
+| assignment-provider-settings.schema.json | Flow Agents Assignment Provider Settings | https://flow-agents.dev/schemas/assignment-provider-settings.schema.json |
 | backlog-provider-settings.schema.json | Flow Agents Backlog Provider Settings | https://flow-agents.dev/schemas/backlog-provider-settings.schema.json |
 | decision-record.schema.json | Flow Agents Decision Record | https://flow-agents.dev/schemas/decision-record.schema.json |
 | flow-agents-settings.schema.json | Flow Agents Settings | https://flow-agents.dev/schemas/flow-agents-settings.schema.json |

package/docs/decisions/index.md

@@ -11,4 +11,7 @@ Numbered ADRs under `docs/adr/` are frozen history and are not listed here.
 | Topic | Status | Decision |
 | --- | --- | --- |
 | [decision-records](./decision-records.md) | current | Decision records |
+| [knowledge-store-provider](./knowledge-store-provider.md) | current | Knowledge store provider |
+| [model-routing](./model-routing.md) | current | Model routing |
 | [promotion-gate](./promotion-gate.md) | current | Promotion gate |
+| [standing-directives](./standing-directives.md) | current | Standing directives |

package/docs/decisions/knowledge-store-provider.md

@@ -0,0 +1,51 @@
+---
+status: current
+subject: Knowledge store provider
+decided: 2026-07-02
+evidence:
+  - kind: issue
+    ref: https://github.com/kontourai/flow-agents/issues/317
+  - kind: doc
+    ref: context/contracts/knowledge-store-contract.md
+  - kind: session-archive
+    ref: .kontourai/flow-agents/decision-registry-shape/decision-registry-shape--idea-to-backlog.md
+---
+
+# Knowledge store provider
+
+The Knowledge Kit owns a storage-independent **Knowledge Graph** model — typed
+nodes (`note`, `decision`, `issue`, `session`, `person`; extensible), a closed
+edge vocabulary (`supersedes`, `merged-into`, `blocks`, `evidence-of`,
+`mentions`, `relates`), and provenance on both — with storage and sync as
+pluggable **providers**. The same read and health verbs run over every provider.
+
+## Decision
+
+- The normative model + provider interface live in
+  `context/contracts/knowledge-store-contract.md`, backed by JSON schemas at
+  `schemas/knowledge/{node,edge,proposal,health-report}.schema.json`.
+- The write side is **proposals-only**, expressed structurally: a provider's
+  `proposeWrite` can only return a proposal whose `status` is the const
+  `"proposed"` and MUST NOT mutate the store. Enactment is downstream — the
+  git-repo provider renders a decision-registry topic file for the **promote
+  sub-flow**; work-item renders a draft `gh` comment/label; markdown-vault
+  renders a native frontmatter+wikilink note. This mirrors the store contract's
+  `propose → apply/reject` gate rather than forking a new write path.
+- Three reference providers ship: **markdown-vault** (a thin read+propose wrapper
+  over the existing store adapter — existing skills unaffected), **git-repo**
+  (decision-registry tombstones/evidence, CONTEXT.md glossary, learnings), and
+  **work-item** (GitHub issues via an injectable `gh` runner, so backlog hygiene
+  becomes a knowledge-health pass).
+- Health verbs (duplicate detection, dependency-link integrity) are
+  **provider-agnostic** functions over `{nodes, edges}` and emit schema-valid
+  health reports. A parameterized conformance suite gates every provider.
+
+## Rationale
+
+The portfolio provider pattern (hachure format/adapters; Builder Kit
+work-item contract/providers) had not been applied to knowledge, which was fused
+to the markdown-vault shape. Rule-of-three passes on stores operated today: a
+duplicate backlog issue (traverse#14) caught manually is now caught mechanically
+by a graph pass over the work-item adapter. A graph-database provider stays a
+gated spike (#318) — adoption waits on a real query failing over file providers,
+not speculation.

package/docs/decisions/model-routing.md

@@ -0,0 +1,63 @@
+---
+status: current
+subject: Model routing
+decided: 2026-07-03
+evidence:
+  - kind: issue
+    ref: https://github.com/kontourai/flow-agents/issues/364
+  - kind: url
+    ref: https://claude.ai/code/session_01CEPxsn2GuWdysEMACRHsFQ
+---
+
+# Model routing
+
+Which model backs which delegate role is **data resolved by the orchestrator
+at delegation time**, not code baked into generated files or per-agent
+frontmatter.
+
+## Decision
+
+- Model-routing policy is committed data in `.datum/config.json` (read by the
+  `@kontourai/datum` registry, `datum.schema.json`): a `providers` map
+  (`anthropic`, `zai`) and a `roles` map keyed by delegate role name
+  (`delegate-mechanical`, `delegate-implementation`, `delegate-design`,
+  `orchestrator`, `extraction-default`) to a `model@provider` ref.
+- **The orchestrator resolves the role via datum at delegation time** —
+  `datum resolve <role> --json` or the library `resolve()` — and passes the
+  resolved model **explicitly** when spawning each delegate. The consumption
+  instruction lives in `context/contracts/execution-contract.md` § Delegation:
+  Model Routing (where orchestrators actually read it), with a matching
+  summary table in `kits/builder/skills/deliver/SKILL.md` § Model Routing.
+  `.datum/config.json` is the single source of truth for the mapping; the
+  contracts/skills only say where to read it.
+- No generated files and no per-agent frontmatter changes. Roles are the
+  stable reference; which model a role resolves to can change without
+  touching any delegation call site, skill, or agent definition.
+- When datum or the config is absent, delegation falls back to the runtime's
+  inherited model and the fallback is noted in the session/task artifact
+  rather than blocking delegation.
+
+## Rejected alternatives
+
+- **Generated per-agent frontmatter** (a build step stamping a model into
+  each agent definition file) — rejected because it reintroduces a generated
+  artifact that drifts from the data it was generated from and requires a
+  regeneration step on every routing-policy change, which this program has
+  standing directives against (no generated files as the routing surface).
+- **Environment-variable-only selection** (e.g. one global
+  `ANTHROPIC_MODEL`-style override with no role granularity) — rejected
+  because it collapses distinct delegate shapes (mechanical vs.
+  precisely-planned implementation vs. design-latitude vs. orchestrator) onto
+  a single model choice, losing the per-role routing this design exists to
+  express, and because it is not resolvable per-delegate-spawn within a
+  single process the way an explicit per-call model override is.
+
+## Rationale
+
+Routing policy changes independently of, and more often than, the skills and
+contracts that consume it (new models, new providers, retuned role-to-model
+mappings). Keeping it as data in `.datum/config.json` — the same registry
+shape the `extraction-default` role already establishes as portfolio
+precedent — means a routing change is a config edit reviewed like any other
+data change, not a source/doc change scattered across every delegating
+skill.

package/docs/decisions/standing-directives.md

@@ -0,0 +1,66 @@
+---
+status: current
+subject: Standing directives
+decided: 2026-07-03
+evidence:
+  - kind: issue
+    ref: https://github.com/kontourai/flow-agents/issues/348
+  - kind: pr
+    ref: https://github.com/kontourai/datum/pull/3
+  - kind: pr
+    ref: https://github.com/kontourai/flow-agents/pull/344
+  - kind: issue
+    ref: https://github.com/kontourai/flow-agents/issues/347
+  - kind: issue
+    ref: https://github.com/kontourai/surface/issues/110
+  - kind: pr
+    ref: https://github.com/kontourai/surface/pull/113
+  - kind: doc
+    ref: docs/repository-structure.md
+---
+
+# Standing directives
+
+Ratified owner directives get a durable, quotable home at
+`context/contracts/standing-directives.md` instead of living only in the
+ephemeral context of whichever orchestrator session ratified them.
+
+## Decision
+
+- `context/contracts/standing-directives.md` holds a short, numbered list of
+  owner-ratified directives, each with a one-line rationale and the date it
+  was ratified.
+- Every other file under `context/contracts/` carries a one-line pointer in
+  its header area to `standing-directives.md`, so any agent that loads a
+  phase contract also receives the standing directives regardless of which
+  task in a plan it was delegated.
+- A standing directive overrides default engineering conservatism (e.g.
+  keeping a compatibility path reachable "just in case") wherever it applies.
+  An agent that believes a directive does not fit a situation stops and
+  reports the conflict rather than silently choosing a side.
+- The seeded July 2026 directives: no legacy fallbacks (migrate hard, loud
+  typed error naming the regeneration command); durable-vs-runtime path
+  convention (`.kontourai/` is gitignored runtime state, `.<product>/` is a
+  product's durable committed directory); evidence must be executable;
+  standalone-first then integrate; and the regression rule for cutovers
+  (large regressions are surfaced as an explicit owner decision with data,
+  never papered over, but do not block the cutover by default).
+
+## Rationale
+
+A delegated agent working one slice of a plan only sees the task prompt it
+was given. If a ratified correction — such as "no legacy fallbacks" — lives
+only in the orchestrator's context from the session that ratified it, the
+delegate never receives it and can reintroduce the exact behavior the owner
+already corrected. Wiring a pointer into every contract header makes receipt
+structural rather than dependent on the orchestrator remembering to restate
+the correction in every task prompt.
+
+The individual directives are evidenced by hard-cutover precedent
+([datum#3](https://github.com/kontourai/datum/pull/3)), the fallback-removal
+follow-up to [flow-agents#344](https://github.com/kontourai/flow-agents/pull/344)
+tracked as [flow-agents#347](https://github.com/kontourai/flow-agents/issues/347),
+and the durable-vs-runtime path convention already documented in
+[docs/repository-structure.md](../repository-structure.md) and applied in
+[surface#110](https://github.com/kontourai/surface/issues/110) /
+[surface#113](https://github.com/kontourai/surface/pull/113).

package/docs/fixture-ownership.md

@@ -13,6 +13,7 @@ run `npm run validate:source --` and `npm run fixture:retirement-audit --`.
 
 | Fixture directory | Classification | Owners | Cleanup rule |
 | --- | --- | --- | --- |
+| `evals/fixtures/assignment-provider` | AssignmentProvider local-file and GitHub render/status fixtures (#290) | `evals/integration/test_assignment_provider_local_file.sh`, `evals/integration/test_assignment_provider_github.sh`, `evals/integration/test_pull_work_assignment_join.sh` | Keep while the assignment provider contract's claim/release/supersede/status/list operations and the assignment ⋈ liveness join are tested against local-file and GitHub fixture inputs. |
 | `evals/fixtures/backlog-provider-settings` | settings precedence fixtures | `evals/integration/test_effective_backlog_settings.sh` | Keep while backlog provider settings resolution supports global defaults and project overrides. |
 | `evals/fixtures/builder-kit-workflow-state` | Builder Kit workflow-state fixtures | `evals/static/test_workflow_skills.sh` | Keep while Builder Kit state contract and resume behavior are documented in workflow skill contracts. |
 | `evals/fixtures/console-learning-projection` | console learning projection fixtures | `evals/integration/test_console_learning_projection.sh` | Keep while learning projection supports correction and open-route examples. |

package/docs/workflow-shared-contracts.md

@@ -10,6 +10,7 @@ The workflow system now separates durable process contracts from role-specific i
 
 Shared contracts live in `context/contracts/`:
 
+- `standing-directives.md`
 - `artifact-contract.md`
 - `planning-contract.md`
 - `execution-contract.md`
@@ -17,7 +18,7 @@ Shared contracts live in `context/contracts/`:
 - `verification-contract.md`
 - `delivery-contract.md`
 
-These files define the stable rules for artifacts, planning, execution, review, verification, delivery loops, Goal Fit, and final acceptance.
+These files define the stable rules for artifacts, planning, execution, review, verification, delivery loops, Goal Fit, and final acceptance. `standing-directives.md` is cross-cutting: it holds ratified owner directives that override default engineering conservatism, pointed to from the header of every other contract file so delegated agents receive it regardless of which phase contract they load.
 
 The durable resource shape for selected scope, workflow runs, run plans, status conditions, provider-backed Work Items, and sidecar compatibility direction is documented in the Kontour Resource Contract:
 https://github.com/kontourai/flow-agents/blob/main/docs/kontour-resource-contract.md

package/docs/workflow-usage-guide.md

@@ -114,6 +114,12 @@ Expected artifact:
 
 When a repository has backlog provider settings, `pull-work` should use those settings without requiring the user to name the board. In Flow Agents, `npm run effective-backlog-settings -- --repo-path . --json` resolves `kontourai/flow-agents` to GitHub Project `kontourai/1`, so a prompt like `use pull-work` is enough for the configured provider path.
 
+### Assignment ownership: the third provider leg
+
+Beside the `WorkItemProvider` (what work exists) and `BoardProvider` (how it is grouped/ranked) settings above, `pull-work` also reads `AssignmentProvider` settings to decide who currently owns a candidate work item before offering it. This is durable, human-visible ownership — a GitHub issue assignee, an `agent:claimed` label, and a versioned machine-readable claim comment (or, for tracker-less repos and evals, an equivalent local JSON record) — joined against the ephemeral liveness presence layer so a crashed session's stale claim never blocks a second session from picking up the same work.
+
+Settings live at `context/settings/assignment-provider-settings.json` (validated by `schemas/assignment-provider-settings.schema.json`), mirroring the same `defaults`/`projects[]` shape as the backlog provider settings above; resolve them with `npm run effective-assignment-provider-settings -- --repo-path . --json`. See `context/contracts/assignment-provider-contract.md` for the full `claim`/`release`/`supersede`/`status`/`list` vocabulary, the assignment ⋈ liveness join table, and the human-assignee ask-first policy.
+
 Direct `pull-work` remains a normal workflow primitive. The Builder Kit build path adds the pickup Probe/design-probe handoff before planning; it does not require Surface/Veritas trust-backed gates and does not replace direct primitive use.
 
 Builder Kit build is the product-level entry point for implementation pickup. In that mode, `pull-work` may guide the next step automatically as `pull-work -> design-probe / pickup-probe`; direct `pull-work` still stops with a `plan-work` handoff unless you ask to continue.

package/evals/ci/run-baseline.sh

@@ -22,6 +22,9 @@ CHECKS=(
   "Workflow sidecar writer integration|bash evals/integration/test_workflow_sidecar_writer.sh"
   "Sidecar field preservation integration|bash evals/integration/test_sidecar_field_preservation.sh"
   "Actor identity resolver integration|bash evals/integration/test_actor_identity.sh"
+  "Assignment provider local-file integration|bash evals/integration/test_assignment_provider_local_file.sh"
+  "Assignment provider github integration|bash evals/integration/test_assignment_provider_github.sh"
+  "Pull work assignment join integration|bash evals/integration/test_pull_work_assignment_join.sh"
   "Goal Fit hook integration|bash evals/integration/test_goal_fit_hook.sh"
   "Hook category behavior integration|bash evals/integration/test_hook_category_behaviors.sh"
   "Workflow steering hook integration|bash evals/integration/test_workflow_steering_hook.sh"
@@ -72,6 +75,9 @@ LANE_WORKFLOW_CONTRACTS=(
   "Workflow sidecar writer integration"
   "Sidecar field preservation integration"
   "Actor identity resolver integration"
+  "Assignment provider local-file integration"
+  "Assignment provider github integration"
+  "Pull work assignment join integration"
 )
 
 LANE_RUNTIME_AND_KIT=(

package/evals/fixtures/assignment-provider/actor-a.json

@@ -0,0 +1,6 @@
+{
+  "runtime": "claude-code",
+  "session_id": "eval-actor-a-session",
+  "host": "eval-host",
+  "human": null
+}

package/evals/fixtures/assignment-provider/actor-b.json

@@ -0,0 +1,6 @@
+{
+  "runtime": "claude-code",
+  "session_id": "eval-actor-b-session",
+  "host": "eval-host",
+  "human": null
+}

package/evals/fixtures/assignment-provider/github-issue-claimed.json

@@ -0,0 +1,27 @@
+{
+  "number": 4242,
+  "state": "OPEN",
+  "assignees": [
+    {
+      "login": "flow-agents-fixture-bot"
+    }
+  ],
+  "labels": [
+    {
+      "name": "agent:claimed"
+    },
+    {
+      "name": "kind:enhancement"
+    }
+  ],
+  "comments": [
+    {
+      "id": 90001,
+      "body": "An unrelated human comment on this fixture issue."
+    },
+    {
+      "id": 90002,
+      "body": "<!-- flow-agents:assignment-claim -->\n**Assignment claim** — Claimed by an automated agent session (claude-code).\n\n- actor: `claude-code:fixture-actor-a-session:fixture-host`\n- claimed_at: 2026-06-01T12:00:00Z\n- ttl_seconds: 1800\n- branch: `agent/claude-code-fixture-actor-a-session-fixture-host/flow-agents-4242`\n\n```json\n{\n  \"schema_version\": \"1.0\",\n  \"role\": \"AssignmentClaimRecord\",\n  \"subject_id\": \"kontourai/flow-agents#4242\",\n  \"actor\": {\n    \"runtime\": \"claude-code\",\n    \"session_id\": \"fixture-actor-a-session\",\n    \"host\": \"fixture-host\",\n    \"human\": null\n  },\n  \"claimed_at\": \"2026-06-01T12:00:00Z\",\n  \"ttl_seconds\": 1800,\n  \"branch\": \"agent/claude-code-fixture-actor-a-session-fixture-host/flow-agents-4242\",\n  \"artifact_dir\": \".kontourai/flow-agents/flow-agents-4242\",\n  \"status\": \"claimed\"\n}\n```"
+    }
+  ]
+}

package/evals/fixtures/assignment-provider/github-issue-unassigned.json

@@ -0,0 +1,7 @@
+{
+  "number": 4243,
+  "state": "OPEN",
+  "assignees": [],
+  "labels": [{ "name": "kind:enhancement" }],
+  "comments": [{ "id": 90101, "body": "No assignment claim recorded yet." }]
+}

package/evals/fixtures/assignment-provider/liveness-fresh.json

@@ -0,0 +1,9 @@
+[
+  {
+    "type": "claim",
+    "subjectId": "kontourai/flow-agents#4242",
+    "actor": "claude-code:fixture-actor-a-session:fixture-host",
+    "at": "2026-06-01T12:15:00Z",
+    "ttlSeconds": 1800
+  }
+]

package/evals/fixtures/assignment-provider/liveness-stale.json

@@ -0,0 +1,9 @@
+[
+  {
+    "type": "claim",
+    "subjectId": "kontourai/flow-agents#4242",
+    "actor": "claude-code:fixture-actor-a-session:fixture-host",
+    "at": "2026-06-01T10:00:00Z",
+    "ttlSeconds": 1800
+  }
+]