@kontourai/flow-agents 2.4.0 → 3.1.0

package/docs/adr/0003-flow-agents-coordinates-kits-and-adapters.md

@@ -2,6 +2,8 @@
 title: ADR 0003: Flow Agents Coordinates Kits And Adapters
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0003: Flow Agents Coordinates Kits And Adapters
 
 Flow Agents will not own the builder, or knowledge workflows as core behavior. Those out-of-the-box behaviors will be extracted into normal Flow Kits that use the same manifest, Flow Definition, skill, doc, provider, and eval contracts as third-party kits. Flow Agents owns kit validation, installation, runtime adapter selection, provider wiring, status/control commands, and runtime-specific export; Runtime Adapters own target-specific integration for local agent runtimes and API/framework agents.

package/docs/adr/0004-gates-expect-surface-claims.md

@@ -2,6 +2,8 @@
 title: ADR 0004: Gates Expect Hachure Trust Bundles
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0004: Gates Expect Hachure Trust Bundles
 
 Flow-backed kits will model rich gate evidence as claim expectations using the Hachure trust.bundle format rather than provider-specific requirements. A gate expectation can require `kind: "trust.bundle"`, a domain claim type such as `builder.verify.tests`, accepted trust statuses such as `verified`, and whether the expectation blocks the transition; project or runtime config maps claim types to trusted Surface producers and authority traces. This lets the Builder Kit use repo governance, command checks, CI, human decisions, or future producers without naming a specific provider in the Flow Definition.

package/docs/adr/0005-kubernetes-inspired-resource-contracts.md

@@ -2,6 +2,8 @@
 title: ADR 0005: Kubernetes-Inspired Kontour Resource Contracts
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0005: Kubernetes-Inspired Kontour Resource Contracts
 
 Date: 2026-05-27

package/docs/adr/0006-typescript-first-source-policy.md

@@ -2,6 +2,8 @@
 title: ADR 0006: TypeScript-First Source Policy
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0006: TypeScript-First Source Policy
 
 Date: 2026-05-31

package/docs/adr/0007-flow-skill-kit-tool-boundary.md

@@ -2,6 +2,8 @@
 title: "ADR 0007: Flow / Skill / Kit / Tool Boundary"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0007: Flow / Skill / Kit / Tool Boundary
 
 **Date:** 2026-06-15  

package/docs/adr/0007-skill-audit.md

@@ -2,6 +2,8 @@
 title: "Skill Audit 2026-06-15: Flow / Skill / Kit / Tool Boundary"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # Skill Audit: Flow / Skill / Kit / Tool Boundary
 
 **Date:** 2026-06-15  

package/docs/adr/0008-kit-operation-boundary.md

@@ -2,6 +2,8 @@
 title: "ADR 0008: Kit Operation Boundary"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0008: Kit Operation Boundary
 
 **Date:** 2026-06-15  

package/docs/adr/0009-canonical-hook-core-kit-boundary.md

@@ -2,6 +2,8 @@
 title: "ADR 0009: Canonical Hook Core/Kit Boundary"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0009: Canonical Hook Core/Kit Boundary
 
 **Date:** 2026-06-23

package/docs/adr/0010-workflow-trust-state-as-hachure-bundle.md

@@ -2,6 +2,8 @@
 title: "ADR 0010: Workflow Trust State as a Hachure Trust Bundle"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0010: Workflow Trust State as a Hachure Trust Bundle
 
 **Date:** 2026-06-23

package/docs/adr/0011-mcp-posture.md

@@ -2,6 +2,8 @@
 title: "ADR 0011: MCP Posture — Enforcement Stays Hooks; Surface Owns MCP Projection; No Auto-Injected Config"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0011: MCP Posture
 
 **Date:** 2026-06-24

package/docs/adr/0012-agent-coordination-as-liveness-claims.md

@@ -2,6 +2,8 @@
 title: "ADR 0012: Agent Coordination as Hachure Liveness Claims"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0012: Agent Coordination as Hachure Liveness Claims
 
 **Date:** 2026-06-24

package/docs/adr/0013-context-lifecycle.md

@@ -2,6 +2,8 @@
 title: "ADR 0013: Context Lifecycle — Workflow-Boundary Compaction, Freshness-Gated Reuse, and the Learning Split"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0013: Context Lifecycle
 
 **Date:** 2026-06-25

package/docs/adr/0014-core-vs-domain-kit-boundary.md

@@ -2,6 +2,8 @@
 title: "ADR 0014: Flow Agents core vs domain kits — the generic/kit boundary"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0014: Flow Agents core vs domain kits
 
 **Date:** 2026-06-25

package/docs/adr/0015-flow-flow-agents-boundary-reconciliation.md

@@ -2,6 +2,8 @@
 title: "ADR 0015: Flow / Flow Agents Boundary Reconciliation"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0015: Flow / Flow Agents Boundary Reconciliation
 
 **Date:** 2026-06-25

package/docs/adr/0016-three-hard-boundary-model.md

@@ -2,6 +2,8 @@
 title: "ADR 0016: The Three-Hard-Boundary Model — a FlowDefinition-Driven, Kit-Agnostic Core"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0016: The Three-Hard-Boundary Model — a FlowDefinition-Driven, Kit-Agnostic Core
 
 **Date:** 2026-06-26

package/docs/adr/0017-anti-gaming-trust-security-model.md

@@ -2,6 +2,8 @@
 title: "ADR 0017: The Anti-Gaming Trust Security Model — Layered Defense + External CI Anchor"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0017: The Anti-Gaming Trust Security Model — Layered Defense + External CI Anchor
 
 Status: Accepted

package/docs/adr/0018-freeze-local-shell-heuristics.md

@@ -2,6 +2,8 @@
 title: "ADR 0018: Freeze the Local Shell-Parsing Heuristics; Route New Enforcement to the CI Anchor"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0018: Freeze the Local Shell-Parsing Heuristics; Route New Enforcement to the CI Anchor
 
 Status: Accepted

package/docs/adr/0019-kit-dependency-ownership.md

@@ -2,6 +2,8 @@
 title: "ADR 0019: Kit Dependency Ownership"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0019: Kit Dependency Ownership
 
 **Date:** 2026-07-01  

package/docs/adr/0020-trust-reconcile-manifest-and-claim-classification.md

@@ -2,6 +2,8 @@
 title: "ADR 0020: Trust-Reconcile Manifest, Claim Classification, and Waivers"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0020: Trust-Reconcile Manifest, Claim Classification, and Waivers
 
 Status: Accepted

package/docs/adr/0021-assignment-leases-and-stale-claim-takeover.md

@@ -2,6 +2,8 @@
 title: "ADR 0021: Assignment Leases and Stale-Claim Takeover"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0021: Assignment Leases and Stale-Claim Takeover
 
 **Date:** 2026-07-02
@@ -98,7 +100,7 @@ Five touchpoints, one policy:
 |---|---|---|
 | `workflow-steering.js`, every turn | read | one-line liveness digest; "superseded" interrupt for the held subject |
 | `pull-work` | read + write | exclude held; claim (liveness + provider) on selection |
-| `ensure-session` / pickup | read + write | refuse entry to a session dir under a fresh other-actor claim; supersede-then-enter if stale |
+| `ensure-session` / pickup | read + write | refuse entry to a session dir under a fresh other-actor claim; supersede-then-enter if stale (**implemented by #291**) |
 | `advance-state` + tool activity | write | heartbeat rides existing writes; no bespoke timer |
 | **publish (push / PR / merge)** | **read, blocking** | **verify-hold**: hard-stop if not the fresh, non-superseded holder |
 

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

@@ -2,6 +2,8 @@
 title: "ADR 0022: Fail-Closed Delivery Reconciliation with Governed Exemptions"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0022: Fail-Closed Delivery Reconciliation with Governed Exemptions
 
 **Date:** 2026-07-02
@@ -281,3 +283,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/adr/README.md

@@ -0,0 +1,49 @@
+---
+title: ADR Directory (Frozen)
+---
+
+# Architecture Decision Records — FROZEN
+
+**This directory is frozen immutable history. Do not add ADR 0023, and do not
+edit the numbered ADRs here** (each carries a `FROZEN — immutable history.`
+banner). The numbered `docs/adr/NNNN-*.md` files are preserved as provenance for
+the decisions that shaped Flow Agents; their subjects have been carried forward
+into the topic-keyed decision registry.
+
+See [`index.md`](./index.md) for the generated list of frozen ADRs.
+
+## Where decisions live now
+
+New and superseding decisions are recorded as **topic-keyed living decision
+records** under [`docs/decisions/`](../decisions/index.md), one file per decision
+**subject** (a noun from the `CONTEXT.md` glossary), never as a new numbered ADR.
+
+- Contract: [`context/contracts/decision-registry-contract.md`](../../context/contracts/decision-registry-contract.md)
+  — the normative rules for topic slugs, frontmatter, evidence, and supersession.
+- Frontmatter schema: `schemas/decision-record.schema.json`.
+- Validate + regenerate the index: `npm run check:decisions` /
+  `npm run gen:decisions-index`.
+- Glossary: [`../decisions/decision-records.md`](../decisions/decision-records.md)
+  explains the registry model; `CONTEXT.md`'s **Decision Records** / **Decision
+  Registry** terms are the vocabulary.
+
+## How to record a decision
+
+1. Consult [`../decisions/index.md`](../decisions/index.md) to decide
+   **revise-vs-create**: if the subject already has a topic file, edit it
+   (supersession is an edit); otherwise create `docs/decisions/<subject-slug>.md`
+   using a subject noun from `CONTEXT.md` (add the term first if absent).
+2. Fill the frontmatter (`status`, `subject`, `decided`, `evidence[]`) per the
+   registry contract, then run `npm run gen:decisions-index` and
+   `npm run check:decisions`.
+3. Each frozen ADR whose subject you are ratifying is already linked from its
+   `needs-decision` stub's `evidence[]`; flip that stub's `status` to `current`
+   and add rationale rather than starting a new file.
+
+Agent **probes** (`design-probe`, `pickup-probe`) author decision records
+directly per
+[`context/contracts/probe-docs-write-contract.md`](../../context/contracts/probe-docs-write-contract.md)
+(issue [#311](https://github.com/kontourai/flow-agents/issues/311)): each
+crystallized understanding emits a `CONTEXT.md` vocabulary delta, a
+`docs/decisions/<slug>.md` decision delta (revise-vs-create against the index),
+and a transcript-provenance link back to the Probe's session artifact.

package/docs/adr/index.md

@@ -0,0 +1,34 @@
+---
+title: ADR Index
+---
+
+# ADR Index
+
+Generated by `node scripts/freeze-adrs.mjs` (`npm run freeze:adrs`). Do not edit by hand.
+Numbered ADRs below are FROZEN immutable history (see the banner on each file). Current and superseding decisions live in [docs/decisions/](../decisions/index.md); a frozen ADR's subject is carried forward there as a `needs-decision` stub or a ratified decision.
+
+| Number | Title | Date | Link |
+| --- | --- | --- | --- |
+| 0001 | Flow Agents Consumes Flow For Workflow Enforcement | 2026-05-24 | [0001-flow-agents-consumes-flow.md](./0001-flow-agents-consumes-flow.md) |
+| 0002 | Flow Kits As The Extension Unit | unknown | [0002-flow-kits-as-extension-unit.md](./0002-flow-kits-as-extension-unit.md) |
+| 0003 | Flow Agents Coordinates Kits And Adapters | unknown | [0003-flow-agents-coordinates-kits-and-adapters.md](./0003-flow-agents-coordinates-kits-and-adapters.md) |
+| 0004 | Gates Expect Hachure Trust Bundles | 2026-06-26 | [0004-gates-expect-surface-claims.md](./0004-gates-expect-surface-claims.md) |
+| 0005 | Kubernetes-Inspired Kontour Resource Contracts | 2026-05-27 | [0005-kubernetes-inspired-resource-contracts.md](./0005-kubernetes-inspired-resource-contracts.md) |
+| 0006 | TypeScript-First Source Policy | 2026-05-31 | [0006-typescript-first-source-policy.md](./0006-typescript-first-source-policy.md) |
+| 0007 | Flow / Skill / Kit / Tool Boundary | 2026-06-15 | [0007-flow-skill-kit-tool-boundary.md](./0007-flow-skill-kit-tool-boundary.md) |
+| 0007 | Skill Audit: Flow / Skill / Kit / Tool Boundary | 2026-06-15 | [0007-skill-audit.md](./0007-skill-audit.md) |
+| 0008 | Kit Operation Boundary | 2026-06-15 | [0008-kit-operation-boundary.md](./0008-kit-operation-boundary.md) |
+| 0009 | Canonical Hook Core/Kit Boundary | 2026-06-23 | [0009-canonical-hook-core-kit-boundary.md](./0009-canonical-hook-core-kit-boundary.md) |
+| 0010 | Workflow Trust State as a Hachure Trust Bundle | 2026-06-23 | [0010-workflow-trust-state-as-hachure-bundle.md](./0010-workflow-trust-state-as-hachure-bundle.md) |
+| 0011 | MCP Posture | 2026-06-24 | [0011-mcp-posture.md](./0011-mcp-posture.md) |
+| 0012 | Agent Coordination as Hachure Liveness Claims | 2026-06-24 | [0012-agent-coordination-as-liveness-claims.md](./0012-agent-coordination-as-liveness-claims.md) |
+| 0013 | Context Lifecycle | 2026-06-25 | [0013-context-lifecycle.md](./0013-context-lifecycle.md) |
+| 0014 | Flow Agents core vs domain kits | 2026-06-25 | [0014-core-vs-domain-kit-boundary.md](./0014-core-vs-domain-kit-boundary.md) |
+| 0015 | Flow / Flow Agents Boundary Reconciliation | 2026-06-25 | [0015-flow-flow-agents-boundary-reconciliation.md](./0015-flow-flow-agents-boundary-reconciliation.md) |
+| 0016 | The Three-Hard-Boundary Model — a FlowDefinition-Driven, Kit-Agnostic Core | 2026-06-26 | [0016-three-hard-boundary-model.md](./0016-three-hard-boundary-model.md) |
+| 0017 | The Anti-Gaming Trust Security Model — Layered Defense + External CI Anchor | unknown | [0017-anti-gaming-trust-security-model.md](./0017-anti-gaming-trust-security-model.md) |
+| 0018 | Freeze the Local Shell-Parsing Heuristics; Route New Enforcement to the CI Anchor | unknown | [0018-freeze-local-shell-heuristics.md](./0018-freeze-local-shell-heuristics.md) |
+| 0019 | Kit Dependency Ownership | 2026-07-01 | [0019-kit-dependency-ownership.md](./0019-kit-dependency-ownership.md) |
+| 0020 | Trust-Reconcile Manifest, Claim Classification, and Waivers | unknown | [0020-trust-reconcile-manifest-and-claim-classification.md](./0020-trust-reconcile-manifest-and-claim-classification.md) |
+| 0021 | Assignment Leases and Stale-Claim Takeover | 2026-07-02 | [0021-assignment-leases-and-stale-claim-takeover.md](./0021-assignment-leases-and-stale-claim-takeover.md) |
+| 0022 | Fail-Closed Delivery Reconciliation with Governed Exemptions | 2026-07-02 | [0022-fail-closed-delivery-reconciliation-with-governed-exemptions.md](./0022-fail-closed-delivery-reconciliation-with-governed-exemptions.md) |

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/agent-coordination.md

@@ -0,0 +1,20 @@
+---
+status: needs-decision
+subject: Agent coordination
+decided: 2026-07-03
+evidence:
+  - kind: adr
+    ref: docs/adr/0012-agent-coordination-as-liveness-claims.md
+  - kind: adr
+    ref: docs/adr/0021-assignment-leases-and-stale-claim-takeover.md
+---
+# Agent coordination
+
+This subject has provenance in frozen ADR history ([0012-agent-coordination-as-liveness-claims.md](../adr/0012-agent-coordination-as-liveness-claims.md), [0021-assignment-leases-and-stale-claim-takeover.md](../adr/0021-assignment-leases-and-stale-claim-takeover.md)) but no living
+decision has been ratified yet under the topic-keyed decision registry
+(`context/contracts/decision-registry-contract.md`). This stub records that the
+subject is open and links the frozen ADR(s) as provenance; it is not a decision.
+
+When a living decision is ratified for agent coordination, update this
+file's `status` to `current`, add rationale, and keep the `adr` evidence
+links as provenance for the history that led here.

package/docs/decisions/anti-gaming-trust-security.md

@@ -0,0 +1,20 @@
+---
+status: needs-decision
+subject: Anti-gaming trust security
+decided: 2026-07-03
+evidence:
+  - kind: adr
+    ref: docs/adr/0017-anti-gaming-trust-security-model.md
+  - kind: adr
+    ref: docs/adr/0018-freeze-local-shell-heuristics.md
+---
+# Anti-gaming trust security
+
+This subject has provenance in frozen ADR history ([0017-anti-gaming-trust-security-model.md](../adr/0017-anti-gaming-trust-security-model.md), [0018-freeze-local-shell-heuristics.md](../adr/0018-freeze-local-shell-heuristics.md)) but no living
+decision has been ratified yet under the topic-keyed decision registry
+(`context/contracts/decision-registry-contract.md`). This stub records that the
+subject is open and links the frozen ADR(s) as provenance; it is not a decision.
+
+When a living decision is ratified for Anti-gaming trust security, update this
+file's `status` to `current`, add rationale, and keep the `adr` evidence
+links as provenance for the history that led here.

package/docs/decisions/context-lifecycle.md

@@ -0,0 +1,18 @@
+---
+status: needs-decision
+subject: Context lifecycle
+decided: 2026-07-03
+evidence:
+  - kind: adr
+    ref: docs/adr/0013-context-lifecycle.md
+---
+# Context lifecycle
+
+This subject has provenance in frozen ADR history ([0013-context-lifecycle.md](../adr/0013-context-lifecycle.md)) but no living
+decision has been ratified yet under the topic-keyed decision registry
+(`context/contracts/decision-registry-contract.md`). This stub records that the
+subject is open and links the frozen ADR(s) as provenance; it is not a decision.
+
+When a living decision is ratified for context lifecycle, update this
+file's `status` to `current`, add rationale, and keep the `adr` evidence
+links as provenance for the history that led here.

package/docs/decisions/core-domain-kit-boundary.md

@@ -0,0 +1,18 @@
+---
+status: needs-decision
+subject: Core vs domain kit boundary
+decided: 2026-07-03
+evidence:
+  - kind: adr
+    ref: docs/adr/0014-core-vs-domain-kit-boundary.md
+---
+# Core vs domain kit boundary
+
+This subject has provenance in frozen ADR history ([0014-core-vs-domain-kit-boundary.md](../adr/0014-core-vs-domain-kit-boundary.md)) but no living
+decision has been ratified yet under the topic-keyed decision registry
+(`context/contracts/decision-registry-contract.md`). This stub records that the
+subject is open and links the frozen ADR(s) as provenance; it is not a decision.
+
+When a living decision is ratified for core vs domain kit boundary, update this
+file's `status` to `current`, add rationale, and keep the `adr` evidence
+links as provenance for the history that led here.

package/docs/decisions/flow-flow-agents-boundary.md

@@ -0,0 +1,18 @@
+---
+status: needs-decision
+subject: Flow / Flow Agents boundary
+decided: 2026-07-03
+evidence:
+  - kind: adr
+    ref: docs/adr/0015-flow-flow-agents-boundary-reconciliation.md
+---
+# Flow / Flow Agents boundary
+
+This subject has provenance in frozen ADR history ([0015-flow-flow-agents-boundary-reconciliation.md](../adr/0015-flow-flow-agents-boundary-reconciliation.md)) but no living
+decision has been ratified yet under the topic-keyed decision registry
+(`context/contracts/decision-registry-contract.md`). This stub records that the
+subject is open and links the frozen ADR(s) as provenance; it is not a decision.
+
+When a living decision is ratified for flow / flow agents boundary, update this
+file's `status` to `current`, add rationale, and keep the `adr` evidence
+links as provenance for the history that led here.

package/docs/decisions/flow-kit.md

@@ -0,0 +1,20 @@
+---
+status: needs-decision
+subject: Flow Kit
+decided: 2026-07-03
+evidence:
+  - kind: adr
+    ref: docs/adr/0002-flow-kits-as-extension-unit.md
+  - kind: adr
+    ref: docs/adr/0003-flow-agents-coordinates-kits-and-adapters.md
+---
+# Flow Kit
+
+This subject has provenance in frozen ADR history ([0002-flow-kits-as-extension-unit.md](../adr/0002-flow-kits-as-extension-unit.md), [0003-flow-agents-coordinates-kits-and-adapters.md](../adr/0003-flow-agents-coordinates-kits-and-adapters.md)) but no living
+decision has been ratified yet under the topic-keyed decision registry
+(`context/contracts/decision-registry-contract.md`). This stub records that the
+subject is open and links the frozen ADR(s) as provenance; it is not a decision.
+
+When a living decision is ratified for flow kit, update this
+file's `status` to `current`, add rationale, and keep the `adr` evidence
+links as provenance for the history that led here.