@kontourai/flow-agents 2.4.0 → 3.1.0

package/.github/CODEOWNERS

@@ -13,6 +13,14 @@
 /evals/ci/                      @briananderson1222
 /scripts/ci/                    @briananderson1222
 
+# delivery/DECLARED (ADR 0022 §2) is the no-agent-delivery exemption marker
+# trust-reconcile.js reads to skip Step 2 when no bundle is delivered — a
+# self-asserted governance artifact naming approved_by, so it gets the same
+# owner-review protection as the other verify-config/anchor paths above. This
+# closes #301's file-level half; branch-protection enforcement of CODEOWNERS
+# review itself remains #225 (server-side, not code).
+/delivery/DECLARED               @briananderson1222
+
 # The verification config the CI anchor depends on — an agent must not redefine
 # trust-reconcile-verify to a fake/laundered command or rewire the lane runner
 # without owner review (convergence red-team finding).

package/.github/workflows/ci.yml

@@ -149,6 +149,26 @@ jobs:
         continue-on-error: true
         run: bash evals/ci/run-baseline.sh --check actor-identity-resolver-integration
 
+      - name: Assignment provider local-file integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check assignment-provider-local-file-integration
+
+      - name: Assignment provider github integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check assignment-provider-github-integration
+
+      - name: Pull work assignment join integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check pull-work-assignment-join-integration
+
+      - name: Ensure-session ownership guard integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check ensure-session-ownership-guard-integration
+
+      - name: Current.json per-actor integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check current-json-per-actor-integration
+
       - name: Finalize CI evidence
         if: always()
         run: bash evals/ci/run-baseline.sh --finalize

package/.github/workflows/trust-reconcile.yml

@@ -27,12 +27,41 @@
 # The agent cannot self-declare success here: it cannot modify the CI environment,
 # pre-disable this job, or post-forge results after the check runs.
 #
-# THIS JOB IS INTENDED TO BE A REQUIRED STATUS CHECK (branch protection).
-# Enabling it as required is a server-side GitHub branch-protection configuration
-# step — it is not wired here by code. Once required, no PR can merge past it.
+# THIS JOB IS ALREADY A REQUIRED, ADMIN-ENFORCED STATUS CHECK on main (verified via
+# `gh api repos/kontourai/flow-agents/branches/main/protection`: "Trust Reconcile" is in
+# required_status_checks.contexts, enforce_admins.enabled: true). No PR — including from
+# admins — can merge past a failing run. Disabling/relaxing this requires a server-side
+# branch-protection change (GitHub UI/API), not a code change in this repo.
 #
 # Additive — NOT a gate-hook change. Does not modify scripts/hooks/*, kits/knowledge,
 # or continue-work. Mirrors the structure of .github/workflows/ci.yml.
+#
+# CI-context contract for the bundle-ownership staleness check (ADR 0022 addendum, part
+# 2; scripts/ci/trust-reconcile.js bundleAttestsThisChange()): an auto-discovered bundle
+# is treated as owned only if its checkpoint's commit_sha is a git-ancestor of (or equal
+# to) this change's own commit sha, checked via `git merge-base --is-ancestor`. That
+# check requires TWO things this workflow provides deliberately, not by accident:
+#   1. Checkout step below uses `fetch-depth: 0` (full history) — the default
+#      fetch-depth: 1 (shallow clone) lacks the parent commit objects merge-base needs;
+#      an ancestor check against a shallow clone exits 128 (unresolvable), which
+#      correctly fails CLOSED (treated as stale) per trust-reconcile.js's own
+#      fail-closed-on-ambiguity contract, but would falsely stale EVERY legitimate
+#      fresh bundle on this required check without full history.
+#   2. Trust reconcile step below sets TRUST_RECONCILE_SHA to the PR's own HEAD commit
+#      (github.event.pull_request.head.sha), not github.sha — on a pull_request trigger,
+#      github.sha is GitHub's synthetic merge commit (refs/pull/N/merge), which is NOT
+#      the commit a locally-run seal-checkpoint ever stamps as commit_sha (checkpoints
+#      are always sealed against a real branch commit). Falling back to github.sha only
+#      applies on push/workflow_dispatch, where it IS the real commit. The checkout ref
+#      itself is unchanged — Step 1 (fresh verify) still runs against the same tree it
+#      always has; only the identity used for the OWNERSHIP COMPARISON changes.
+#   3. Trust reconcile step below also sets TRUST_RECONCILE_EVENT to github.event_name so
+#      trust-reconcile.js can event-scope bundle-required enforcement (ADR 0022 addendum,
+#      part 4): a push run on `main` (post-merge, after a squash-merge whose commit has no
+#      git ancestry back to the feature-branch commit a checkpoint was sealed against) is
+#      a loud no-op on Step 2 instead of a false failure — gating already happened on the
+#      PR run. This does NOT weaken PR-time gating: on pull_request, enforcement is
+#      unchanged.
 
 name: Trust Reconcile
 
@@ -63,6 +92,13 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          # Full history (not the default shallow fetch-depth: 1): the bundle-ownership
+          # staleness check (ADR 0022 addendum, part 2) resolves `git merge-base
+          # --is-ancestor` against the checked-out repo, which needs parent commit
+          # objects a shallow clone does not have. See the CI-context contract note
+          # above this job.
+          fetch-depth: 0
 
       - name: Set up Node.js
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
@@ -80,6 +116,23 @@ jobs:
       - name: Trust reconcile
         id: trust-reconcile
         run: node scripts/ci/trust-reconcile.js
+        env:
+          # The change identity the bundle-ownership staleness check compares the
+          # discovered checkpoint's commit_sha against (ADR 0022 addendum, part 2). On a
+          # pull_request trigger, github.sha is GitHub's synthetic merge commit, not a
+          # commit any real seal-checkpoint run ever stamps — so this MUST be the PR's
+          # own head sha. On push/workflow_dispatch there is no pull_request context, and
+          # github.sha already is the real commit, so the fallback is exact, not a guess.
+          # This does NOT change what gets checked out/verified (Step 1 fresh verify is
+          # untouched) — only the sha used for the Step-2-ownership comparison.
+          TRUST_RECONCILE_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
+          # Event-scoped enforcement (ADR 0022 addendum, part 4): lets trust-reconcile.js
+          # tell a gating pull_request run apart from a post-merge push run on `main` — a
+          # push run's bundle is expected to be absent/stale (squash-merge commits have no
+          # ancestry back to the feature-branch sha a checkpoint was sealed against) and
+          # must be a no-op, not a failure. Unset/unrecognized values fail toward the
+          # STRICTER (pull_request-shaped) enforcement — see resolveEnforcementEvent().
+          TRUST_RECONCILE_EVENT: ${{ github.event_name }}
         # Canonical verify: auto-discovered from package.json scripts["trust-reconcile-verify"]
         #   = npm run build && npm run eval:static
 #   (integration + the anti-gaming regression suite run in ci.yml's required
@@ -88,7 +141,12 @@ jobs:
         # compile-only check. Override via TRUST_RECONCILE_COMMANDS or --commands if needed.
         # Bundle auto-discovery: if delivery/trust.bundle or delivery/trust.checkpoint.json
         # exists in the checkout, CI reconciles per-command claimed passes against fresh
-        # results automatically. When absent, only the fresh verify is enforced (fail-open).
+        # results automatically. When absent, a bundle is REQUIRED by default (ADR 0022 §1):
+        # the job fails closed unless a well-formed, in-scope delivery/DECLARED
+        # no-agent-delivery marker is present, which exempts Step 2 (reconcile) only —
+        # Step 1 (fresh verify) still always runs. An auto-discovered bundle/checkpoint
+        # that does not attest THIS change (see the CI-context contract note above this
+        # job) is treated the same as absent (ADR 0022 addendum, part 2).
         # Phase 2: on success, writes ci-trust-reconcile-results.json to RUNNER_TEMP
         # for mint-attestation.js to consume.
 

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## [3.1.0](https://github.com/kontourai/flow-agents/compare/v3.0.0...v3.1.0) (2026-07-04)
+
+
+### Features
+
+* **docs:** probe docs-write contract — vocabulary + decision deltas ([#311](https://github.com/kontourai/flow-agents/issues/311)) ([#371](https://github.com/kontourai/flow-agents/issues/371)) ([867c3b5](https://github.com/kontourai/flow-agents/commit/867c3b5b645c896e5df6886177171b05e73e8fa9))
+* **knowledge:** neo4j knowledge-store provider — Cypher-backed [#317](https://github.com/kontourai/flow-agents/issues/317) interface (opt-in default) ([#373](https://github.com/kontourai/flow-agents/issues/373)) ([2ef2523](https://github.com/kontourai/flow-agents/commit/2ef2523cc65a5e56dec8dcbf84edc3718cfe190c))
+* **knowledge:** promote sub-flow — ingest→distill→link→health (flow within a flow) ([#313](https://github.com/kontourai/flow-agents/issues/313)) ([#372](https://github.com/kontourai/flow-agents/issues/372)) ([b345d89](https://github.com/kontourai/flow-agents/commit/b345d89873c99f65f00d0fe8ede6a8702b1a2b43))
+* **knowledge:** stable record identity — short-id prefix + slug aliases ([#339](https://github.com/kontourai/flow-agents/issues/339)) ([ff54bc7](https://github.com/kontourai/flow-agents/commit/ff54bc74f893321f13276cd147d500f91e1fc133))
+
+
+### Documentation
+
+* **adr:** ADR freeze cutover + liveness coordination experiment ([#332](https://github.com/kontourai/flow-agents/issues/332)) ([#368](https://github.com/kontourai/flow-agents/issues/368)) ([2c845b8](https://github.com/kontourai/flow-agents/commit/2c845b81675db02622fee8fa1efa6aa197ce96c0))
+
+## [3.0.0](https://github.com/kontourai/flow-agents/compare/v2.4.0...v3.0.0) (2026-07-04)
+
+
+### ⚠ BREAKING CHANGES
+
+* **trust:** require origin/check_kind stamps — remove pre-supersession read fallback ([#355](https://github.com/kontourai/flow-agents/issues/355))
+
+### Features
+
+* **routing:** model-routing policy as datum roles — orchestrator resolves at delegation ([#365](https://github.com/kontourai/flow-agents/issues/365)) ([7acf663](https://github.com/kontourai/flow-agents/commit/7acf6635125623505097eb0f7d2b0da7026c1b00))
+* **trust-anchor:** fail-closed delivery reconciliation with governed exemptions (ADR 0022 §1) ([#358](https://github.com/kontourai/flow-agents/issues/358)) ([0631050](https://github.com/kontourai/flow-agents/commit/0631050c7d88f3dd38d7c90ee1af5adf63410334))
+
+
+### Fixes
+
+* **trust:** critique supersession + lossless check/critique round-trip (closes [#267](https://github.com/kontourai/flow-agents/issues/267), [#268](https://github.com/kontourai/flow-agents/issues/268), [#282](https://github.com/kontourai/flow-agents/issues/282)) ([#344](https://github.com/kontourai/flow-agents/issues/344)) ([c2c3fd5](https://github.com/kontourai/flow-agents/commit/c2c3fd5d322d2537847d67a6fefc6daae6893070))
+* **trust:** require origin/check_kind stamps — remove pre-supersession read fallback ([#355](https://github.com/kontourai/flow-agents/issues/355)) ([ab27f71](https://github.com/kontourai/flow-agents/commit/ab27f71ac1ee652b7125ce01336895d34162472b))
+
+
+### Documentation
+
+* **contracts:** standing owner directives — durable home for ratified policy ([#351](https://github.com/kontourai/flow-agents/issues/351)) ([e335d54](https://github.com/kontourai/flow-agents/commit/e335d540378ba7eaae5bb7162427d8db16f58e4b))
+
 ## [2.4.0](https://github.com/kontourai/flow-agents/compare/v2.3.0...v2.4.0) (2026-07-03)
 
 

package/CONTEXT.md

@@ -56,6 +56,26 @@ A configured implementation of a capability, such as GitHub for backlog, Obsidia
 
 The declared capabilities, defaults, conventions, and limits of a provider type. Provider contracts make integrations predictable and testable without requiring the live provider.
 
+### Knowledge Graph
+
+The Knowledge Kit's storage-independent model: typed nodes (recommended core: note, decision, issue, session, person — extensible) and typed edges (supersedes, merged-into, blocks, evidence-of, mentions, relates — a closed vocabulary), each carrying provenance so every assertion is traceable to the store it came from. Storage and synchronisation are provider concerns; the same ingest, link, and health verbs run over every provider.
+_Avoid_: Graph database as the generic term (the model is provider-independent; a graph-database provider is a separate spike)
+
+### Knowledge Store Provider
+
+A configured implementation of the knowledge-store capability behind the Knowledge Graph model. Providers expose a read interface (nodes, edges, query-by-type) and a proposals-only write interface (proposeWrite returns a proposal, never mutating a human-curated store). The reference providers are markdown-vault (the Obsidian-shaped vault), git-repo (decision registry, CONTEXT.md vocabulary, learnings), and work-item (GitHub issues as a source/sink adapter). See context/contracts/knowledge-store-contract.md.
+_Avoid_: Knowledge adapter when contrasting the provider interface with a single store adapter
+
+### Graph Knowledge Provider
+
+The owner's opt-in Neo4j-backed Knowledge Store Provider (the `neo4j` provider). A queryable materialized view of the Knowledge Graph, synced from the file/work-item providers with idempotent MERGE semantics — the file stores stay the source of truth and the write side stays proposals-only. Selected via `KNOWLEDGE_PROVIDER=neo4j`; degrades to the file providers when no Neo4j is reachable. The file providers remain the portfolio default; the graph is a personal default only. See docs/decisions/graph-knowledge-provider.md.
+_Avoid_: Graph database as the default store (it is opt-in and a view, not the source of truth)
+
+### Knowledge Promote Sub-Flow
+
+The Knowledge Kit's codebase-facing pipeline (the "flow within a flow") that a delivered session's promotion runs through: ingest the session artifacts, distill schema-valid draft decision/vocabulary/learning deltas, link their provenance (PR, merge SHA, session archive, touched topics), and health-check the registry for contradictions with a merge-repair proposal. It is proposals-only — every output is a draft under the session's proposals directory that the promote step applies; the sub-flow never writes docs directly. Invokable standalone and composable from the Builder promote step. See docs/decisions/knowledge-promote-sub-flow.md.
+_Avoid_: Promotion gate as a synonym (the gate is the recorded promote claim; this is the assisted pipeline)
+
 ### Kontour Resource Contract
 
 A versioned Kontour record shape for durable machine-readable configuration, scope, run state, evidence, provider output, and cross-product interchange. Kontour Resource Contracts are the default for new pre-public durable contracts unless a product records why a native shape is clearer.
@@ -215,7 +235,7 @@ A reason code for a Gate that cannot be evaluated or cannot pass because a requi
 
 ### Probe
 
-A Builder Kit Alignment Gate that explores context, challenges assumptions, and records aligned decisions before the process continues. A Probe asks one question at a time, recommends an answer, and uses repository context before asking when the answer can be discovered.
+A Builder Kit Alignment Gate that explores context, challenges assumptions, and records aligned decisions before the process continues. A Probe asks one question at a time, recommends an answer, and uses repository context before asking when the answer can be discovered. As understanding crystallizes, a Probe writes it into durable docs in the same motion: a vocabulary delta into this glossary and a decision delta into the Decision Registry, per [context/contracts/probe-docs-write-contract.md](context/contracts/probe-docs-write-contract.md).
 _Avoid_: Grill, interrogation
 
 ### Flow
@@ -265,6 +285,11 @@ _Avoid_: Numbered ADR as the format for new decisions
 
 The system of Decision Records plus the generated index at [docs/decisions/index.md](docs/decisions/index.md) (slug + one-line summary). The contract is [context/contracts/decision-registry-contract.md](context/contracts/decision-registry-contract.md); the frontmatter schema is `schemas/decision-record.schema.json`; `npm run check:decisions` validates it. Consult the index at write time to decide revise-vs-create.
 
+### Standing Directives
+
+A short, numbered, quotable list of ratified owner directives, each with a one-line rationale and date, kept at [context/contracts/standing-directives.md](context/contracts/standing-directives.md) and pointed to from the header of every other contract file in `context/contracts/`. Standing Directives override default engineering conservatism (such as keeping a compatibility path "just in case") wherever they apply; they exist so a ratified correction has a durable home instead of living only in the ephemeral context of the orchestrator session that ratified it.
+_Avoid_: Operating discipline as the generic term for owner-ratified policy, restating a directive from memory instead of citing the file
+
 ### Promotion Gate
 
 The gated sequence — final acceptance -> promote -> archive — that makes durable-residue extraction the archival act: a delivered session's decisions, vocabulary, learnings, and doc updates must be promoted into durable living docs before the session is archived. The `promote` step records what was promoted where and writes a session-local **promotion claim** into the session `trust.bundle` (evidence refs = the durable doc paths written, or an explicit `--none` no-residue reason). `workflow-artifact-cleanup-audit` classifies a delivered/accepted session with no promotion claim as a cleanup candidate (archive blocked), not terminal. See [docs/decisions/promotion-gate.md](docs/decisions/promotion-gate.md) and [docs/workflow-artifact-lifecycle.md](docs/workflow-artifact-lifecycle.md).
@@ -312,3 +337,65 @@ The Console overview for global setup, registered projects, cross-project usage,
 ### Control API
 
 The shared tool layer used by the Console, CLI, AI agents, and automation. The Control API owns operations such as reading effective settings, explaining provider resolution, testing provider health, previewing config changes, writing config, inspecting workflow state, and reporting usage or eval outcomes.
+
+### Workflow trust state
+
+The trust bundle a workflow gate reads to decide whether to advance — claims, evidence, verification events, and derived status expressed as a Hachure Trust Bundle — so gates consume inspectable trust state rather than raw tool output. Provenance lives in frozen ADRs; the subject is open in the Decision Registry as [docs/decisions/workflow-trust-state.md](docs/decisions/workflow-trust-state.md).
+
+### TypeScript-first source policy
+
+The policy that Kontour product and runtime source defaults to TypeScript, with narrow JavaScript/MJS exceptions (config/tooling, generated assets, thin launchers, fixtures, historical artifacts) and staged per-repo migration for existing non-TypeScript source. Ratified in the Decision Registry as [docs/decisions/typescript-source-policy.md](docs/decisions/typescript-source-policy.md).
+
+### Flow / Skill / Kit / Tool boundary
+
+The layering that separates a Flow (workflow semantics) from a Skill (agent-facing procedure), a Flow Kit (installable bundle), and a Tool (an executable operation), so each concern has one home and does not leak into the others. Subject open in the Decision Registry as [docs/decisions/flow-skill-kit-tool-boundary.md](docs/decisions/flow-skill-kit-tool-boundary.md).
+
+### Kit operation boundary
+
+The rule for what a kit-owned operation may do versus what belongs to the core, keeping kit operations scoped to their capability and free of core enforcement responsibilities. Subject open in the Decision Registry as [docs/decisions/kit-operation-boundary.md](docs/decisions/kit-operation-boundary.md).
+
+### Hook core/kit boundary
+
+The division between canonical hook behavior owned by the core and hook contributions owned by kits, so enforcement hooks have a single authoritative implementation. Subject open in the Decision Registry as [docs/decisions/hook-core-kit-boundary.md](docs/decisions/hook-core-kit-boundary.md).
+
+### MCP posture
+
+Flow Agents' stance on the Model Context Protocol: enforcement stays in hooks, Surface owns any MCP projection, and no MCP configuration is auto-injected into a runtime. Subject open in the Decision Registry as [docs/decisions/mcp-posture.md](docs/decisions/mcp-posture.md).
+
+### Agent coordination
+
+How concurrent agents avoid stepping on each other's work, modeled as Hachure liveness claims plus assignment leases with stale-claim takeover, so a work item's holder is advisory-visible and reclaimable when stale. Subject open in the Decision Registry as [docs/decisions/agent-coordination.md](docs/decisions/agent-coordination.md).
+
+### Context lifecycle
+
+The lifecycle of an agent's working context — workflow-boundary compaction, freshness-gated reuse, and the split between durable learnings and ephemeral context — so context is refreshed rather than silently stale. Subject open in the Decision Registry as [docs/decisions/context-lifecycle.md](docs/decisions/context-lifecycle.md).
+
+### Core vs domain kit boundary
+
+The generic/kit boundary that keeps the Flow Agents core domain-agnostic while domain behavior lives in kits, so the core carries no kit-specific knowledge. Subject open in the Decision Registry as [docs/decisions/core-domain-kit-boundary.md](docs/decisions/core-domain-kit-boundary.md).
+
+### Flow / Flow Agents boundary
+
+The reconciled division of responsibility between Flow (the workflow engine consumed for enforcement) and Flow Agents (the product that consumes it), so each owns a distinct layer without duplicating the other. Subject open in the Decision Registry as [docs/decisions/flow-flow-agents-boundary.md](docs/decisions/flow-flow-agents-boundary.md).
+
+### Three-hard-boundary model
+
+The FlowDefinition-driven, kit-agnostic model that names the three hard boundaries the core enforces, unifying the individual boundary decisions into one architecture. Subject open in the Decision Registry as [docs/decisions/three-hard-boundary-model.md](docs/decisions/three-hard-boundary-model.md).
+
+### Anti-gaming trust security
+
+The layered-defense trust security model that assumes the local agent can be gamed and anchors enforcement in an external CI check, freezing the local shell-parsing heuristics and routing new enforcement to the CI anchor. Subject open in the Decision Registry as [docs/decisions/anti-gaming-trust-security.md](docs/decisions/anti-gaming-trust-security.md).
+
+### Kit dependency ownership
+
+The rule for which layer owns a kit's runtime dependencies, keeping dependency declaration and installation with the kit that needs them rather than the core. Subject open in the Decision Registry as [docs/decisions/kit-dependency-ownership.md](docs/decisions/kit-dependency-ownership.md).
+
+### Trust-reconcile and delivery reconciliation
+
+The CI-anchored reconciliation of a session's trust claims against a manifest — classifying command, session-local, and attested claims, honoring governed waivers — and the fail-closed delivery reconciliation that blocks publication on unreconciled residue unless an exemption is recorded. Subject open in the Decision Registry as [docs/decisions/trust-reconcile.md](docs/decisions/trust-reconcile.md).
+
+### Model Routing
+
+The policy that maps a delegate role name (such as `delegate-mechanical`, `delegate-implementation`, `delegate-design`, `orchestrator`, `extraction-default`) to a specific `model@provider` ref. Model Routing is data, not code: it lives in `.datum/config.json` (read by the `@kontourai/datum` registry, schema `datum.schema.json`) and never in generated files or per-agent frontmatter. The orchestrator resolves the role at delegation time (`datum resolve <role> --json`) and passes the resolved model explicitly when spawning each delegate. See [context/contracts/execution-contract.md](context/contracts/execution-contract.md) § Delegation: Model Routing and [docs/decisions/model-routing.md](docs/decisions/model-routing.md).
+_Avoid_: Generated per-agent model frontmatter, environment-variable-only model selection
+

package/README.md

@@ -217,6 +217,10 @@ See [Repository Structure](docs/repository-structure.md) for the canonical map.
 - `kits/`, `schemas/`, `packaging/`, `evals/`, `docs/`, and `integrations/` hold Flow Kit assets, contracts, package metadata, evals, durable docs, and optional integrations.
 - `dist/`, `build/`, and `_site/` are generated output. Local `.kontourai/`, `.flow-agents/`, `.codex/`, `.claude/`, telemetry, promptfoo, Veritas, and cache directories stay ignored; durable outcomes belong in docs, source, schemas, or provider records.
 
+## Graph provider (opt-in)
+
+The Knowledge Kit ships an optional `neo4j` graph provider — the owner's opt-in personal default, while the file providers remain the portfolio default. It is a queryable **materialized view** synced from the file/work-item stores (which stay the source of truth), with Cypher-backed health/query verbs when selected and graceful degradation to the file providers when no Neo4j is reachable (never a hard dependency). Opt in with `KNOWLEDGE_PROVIDER=neo4j` and see [Graph provider (opt-in)](kits/knowledge/docs/README.md#graph-provider-opt-in) for the `docker run` one-liner, env vars, sync command, and an example Cypher session.
+
 ## Documentation
 
 The [GitHub Pages site](https://kontourai.github.io/flow-agents/) is the product overview and quickstart. The repository docs are the developer reference for contracts, workflow behavior, evals, and integration boundaries. For the gate semantics underneath — definitions, runs, evidence, route-back — read the [Kontour Flow documentation](https://kontourai.github.io/flow/).

package/build/src/cli/assignment-provider.d.ts

@@ -0,0 +1,144 @@
+export type ActorStruct = {
+    runtime: string;
+    session_id: string;
+    host: string;
+    human?: string | null;
+};
+type AssignmentClaimRecordStatus = "claimed" | "released" | "superseded";
+type AssignmentAuditEntry = {
+    at: string;
+    transition: "claim" | "release" | "supersede";
+    from_actor?: ActorStruct | null;
+    to_actor?: ActorStruct | null;
+    reason?: string;
+};
+/**
+ * The versioned claim-record shape from the contract doc's "Versioned claim-record format"
+ * section (Design Decision 2). `schema_version` is bumped only on an incompatible change, per
+ * artifact-contract.md's existing sidecar rule.
+ *
+ * `actor_key` (F1 fix, fix-plan iteration 1, HIGH — additive field, schema_version unchanged):
+ * the canonical `resolveActor(env).actor` string for the claiming actor — the SAME flat/bare
+ * token every other tool (`liveness whoami`, `liveness claim --actor`, per-actor current.json,
+ * pull-work's `--self-actor`) already uses. Optional so every pre-fix record and every #290 eval
+ * fixture with no `actor_key` still parses; `computeEffectiveState` falls back to
+ * `serializeActor(record.actor)` (today's behavior) whenever it's absent. Present, it is the ONLY
+ * correct self-recognition/liveness-join key — see computeEffectiveState's holderActorKey.
+ */
+export type AssignmentClaimRecord = {
+    schema_version: "1.0";
+    role: "AssignmentClaimRecord";
+    subject_id: string;
+    actor: ActorStruct;
+    actor_key?: string;
+    claimed_at: string;
+    ttl_seconds: number;
+    branch: string;
+    artifact_dir: string;
+    status: AssignmentClaimRecordStatus;
+    audit_trail?: AssignmentAuditEntry[];
+};
+export type FreshHolder = {
+    actor: string;
+    lastAt: string;
+    ttlSeconds: number;
+    fresh: boolean;
+};
+export type EffectiveState = "held" | "reclaimable" | "human-held" | "free";
+/** Provider-neutral assignment-layer read, before any liveness join (contract doc's status()). */
+export type AssignmentStatus = {
+    subject_id: string;
+    provider: "local-file" | "github";
+    assignee: string | null;
+    record: AssignmentClaimRecord | null;
+    has_claim_label?: boolean;
+};
+export declare function assignmentFilePath(artifactRoot: string, subjectId: string): string;
+export declare function readLocalRecord(artifactRoot: string, subjectId: string): AssignmentClaimRecord | null;
+export declare function writeLocalRecord(artifactRoot: string, subjectId: string, record: AssignmentClaimRecord): void;
+/**
+ * F1 fix (fix-plan iteration 1, CRITICAL): claimLocalFile/releaseLocalFile/supersedeLocalFile were
+ * a plain read -> compare-actor -> write with no lock, so two concurrently-launched OS processes
+ * could both read "no conflicting claim" before either wrote, and the second write would silently
+ * clobber the first with zero error and zero audit-trail entry for the loser (reproduced 29/40
+ * races against the built CLI). This mirrors the EXACT mechanism `withLock` already uses in
+ * workflow-sidecar.ts:908 for the same class of shared-state mutation — atomic `fs.mkdirSync`
+ * lockdir create as the mutual-exclusion primitive, EEXIST-spin with a staleness-reclaim check
+ * (a lock directory older than the stale threshold is presumed abandoned by a crashed process and
+ * is reclaimed rather than waited on forever) and a bounded deadline, `finally` rmSync release —
+ * as a small LOCAL helper (not a cross-import of that private function, which would pull the
+ * entire workflow-sidecar module in for one primitive). Deliberately synchronous (sleepSync's
+ * Atomics.wait spin, not setTimeout/await) so claim/release/supersede can stay sync `number`
+ * -returning functions and the CLI dispatcher (src/cli.ts, `number | Promise<number>`) does not
+ * need any ripple to async. On lock-acquire failure (any error other than a live contested lock,
+ * or a timeout waiting one out) this THROWS — never a silent no-op — "fail loud, never fail-open"
+ * (artifact-contract.md). Wrap the ENTIRE read-modify-write body (the existing-claim check AND
+ * the write) of all three local-file mutators in this, since all three mutate the same record
+ * file for a given subject.
+ */
+export declare function withSubjectLock<T>(artifactRoot: string, subjectId: string, body: () => T): T;
+/**
+ * The assignment ⋈ liveness join (contract doc's "assignment ⋈ liveness join" section, ADR 0021
+ * §1). Pure function: `{ assignment, freshHoldersList, selfActor, nowMs }` -> one of five
+ * effective states (held/reclaimable/human-held/free — "held" covers both the plain and
+ * assignment-lagging rows, matching the contract table's own repeated "held" label).
+ *
+ * The human-assignee gate (AC11, Design Decision 3) reads `record.actor.human` being *present*,
+ * never a username heuristic — an idle human assignment is always `human-held`, regardless of
+ * idle duration, and is never auto-reclaimable by this function.
+ *
+ * `nowMs` (F3 fix, fix-plan iteration 1) is the SAME resolved "now" the caller already threads
+ * into `freshHolders()` (the `--now` override, when passed, else `Date.now()`) — passing it
+ * through here too means `--now` deterministically governs idle_days as well as liveness
+ * freshness, rather than idle_days silently reading the real wall clock regardless of `--now`.
+ */
+export declare function computeEffectiveState(assignment: AssignmentStatus, freshHoldersList: FreshHolder[], selfActor: string | undefined, nowMs: number): {
+    effective_state: EffectiveState;
+    reason: string;
+    holder?: {
+        actor?: string;
+        assignee?: string | null;
+        idle_days?: number | null;
+        last_at?: string;
+    };
+};
+/**
+ * Wave 1 (#291) extraction: the durable-write body previously inlined inside claimLocalFile's
+ * withSubjectLock() closure, now a parameter-driven pure function so ensure-session's ownership
+ * guard (workflow-sidecar.ts, Wave 2) can reuse the EXACT same claim logic — same-actor idempotent
+ * refresh, different-actor throw, atomic write under withSubjectLock — rather than reimplementing
+ * a second, parallel claim path. claimLocalFile (CLI wrapper, below) is now a thin
+ * parse-args/print-envelope shell around this.
+ */
+export declare function performLocalClaim(artifactRoot: string, subjectId: string, actor: ActorStruct, opts: {
+    ttlSeconds: number;
+    branch: string;
+    artifactDir: string;
+    reason?: string;
+    actorKey?: string;
+}): AssignmentClaimRecord;
+/**
+ * Wave 1 (#291) extraction: the durable-write body previously inlined inside supersedeLocalFile's
+ * withSubjectLock() closure, now a parameter-driven pure function so ensure-session's
+ * `--supersede-stale` takeover path (workflow-sidecar.ts, Wave 2) can reuse the EXACT same
+ * supersede logic — from-actor holder verification, ttl/branch/artifact_dir carry-forward,
+ * audit-trail append, atomic write under withSubjectLock — rather than reimplementing a second,
+ * parallel supersede path. supersedeLocalFile (CLI wrapper, below) is now a thin
+ * parse-args/print-envelope shell around this.
+ */
+export declare function performLocalSupersede(artifactRoot: string, subjectId: string, fromActor: ActorStruct, toActor: ActorStruct, opts?: {
+    ttlSeconds?: number;
+    branch?: string;
+    artifactDir?: string;
+    reason?: string;
+    actorKey?: string;
+}): AssignmentClaimRecord;
+/**
+ * Wave 1 (#291) extraction: the local-file branch of statusCommand's assignment-layer read,
+ * mirrored exactly so ensure-session's ownership guard (workflow-sidecar.ts, Wave 2) derives an
+ * AssignmentStatus identically to the `assignment-provider status` CLI command — a single
+ * implementation, not a second parallel local-file read.
+ */
+export declare function readLocalAssignmentStatus(artifactRoot: string, subjectId: string): AssignmentStatus;
+export declare function main(argv?: string[]): number;
+export {};