@kontourai/flow-agents 3.0.0 → 3.2.0

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
@@ -461,3 +463,114 @@ the workflow to fake the post-merge no-op path; this is closed by required code-
 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.
+
+## Addendum (2026-07-04, part 5): per-session delivery paths — concurrent deliveries stop contending (#379)
+
+Owner-approved follow-up closing a structural defect the fail-closed gate's first real
+deliveries surfaced repeatedly: the delivery transport used a SINGLE shared path
+(`delivery/trust.bundle` + `delivery/trust.checkpoint.json`), so every sealed delivery
+force-committed to the SAME two files. Any two concurrent deliveries therefore
+merge-conflict by construction — three seal collisions inside 24h (#330, #358, #378) each
+needed manual conflict resolution. Worse than the conflict itself: **GitHub schedules NO
+`pull_request` workflows for a conflicting (DIRTY) PR** — zero checks, no error — so the
+required Trust Reconcile check silently never re-runs. The symptom reads as "CI vanished,"
+not "conflict." This collision class scales with delivery frequency; ADR 0021's own "work
+area" vocabulary predicted it, and #335 named the `resolveDeliveryCandidates()` seam as the
+fix site.
+
+**Decision (structural): per-session delivery paths.** `publishDelivery()`
+(`src/cli/workflow-sidecar.ts`) writes to `delivery/<slug>/trust.bundle` (+ checkpoint
+companions), where `<slug>` is the session artifact dir's basename, instead of the shared
+flat path. Concurrent deliveries write to DISTINCT files and cannot contend: two deliveries
+add different `delivery/<slug>/` dirs (add/add of different paths — not a conflict), and both
+deleting the same inherited flat/legacy file is a delete/delete (auto-merges — not a
+conflict). The per-session dir NAME is only a collision-avoidance handle; it carries no
+trust weight.
+
+**Reconciler side: ownership-aware discovery, prefer-newest, not first-match.**
+`resolveDeliveryCandidates()` now returns the flat path (FIRST, for full back-compat)
+followed by every `delivery/<slug>/<filename>` (sorted). `discoverBundle()` no longer returns
+the first-existing candidate; it collects every candidate that attests THIS change
+(ancestor-or-equal, the SAME `bundleAttestsThisChange()` binding Addendum part 2 defined) and
+selects the one attesting the **NEWEST** (descendant-most) commit. This prefer-newest rule is
+load-bearing in a **merge-commit** repo (this repo's own history has merge commits, e.g.
+release-please merges): an inherited FLAT bundle's `commit_sha` can be a REAL ancestor of HEAD
+— it was committed on the trunk's linear history before this branch point — so it legitimately
+"owns" the change too, and a naive first-fresh-wins would select that STALE inherited bundle
+purely because it sorts first, reconciling the PREVIOUS delivery's claims against THIS change's
+CI. Prefer-newest makes the fresh per-session bundle win on recency, not on being deleted
+first — which in turn is what lets the cleanup policy leave the flat path in place (below)
+without corrupting selection. (Addendum parts 2/4's squash-merge reasoning still holds for
+squash repos; prefer-newest is the strict generalization that also covers merge-commit repos,
+where "inherited ⇒ non-ancestor" is NOT guaranteed.) `extractBundleCommitSha()` now resolves a
+bundle's sibling checkpoint from the bundle's OWN directory (`path.dirname(bundlePath)`), not a
+global scan — a global scan would pair a per-session bundle with the wrong session's (or the
+flat) checkpoint and read the wrong commit binding. For the flat layout this is byte-identical
+to the prior behavior; for per-session it is the only correct pairing.
+
+**Back-compat (retained, deprecation-noted).** The flat `delivery/trust.bundle` path stays
+fully supported on the READ side: an already-committed flat bundle from before this change,
+or an external adopter that has not migrated, still resolves and reconciles exactly as
+before (regression-locked by the negatives suite's flat-owner-coexist case and the
+unchanged `test_publish_delivery.sh` TEST 3/4 flat-fixture cases). Only the WRITE side moved
+to per-session — writing to both flat and per-session would re-introduce the very contention
+this closes, so the flat path is write-deprecated, read-supported.
+
+**Cleanup policy: supersede-on-publish, per-session dirs only (delivery/ stays bounded).** A
+publishing session prunes every inherited **per-session** seal dir except its own, then
+commits only `delivery/<slug>/`. Per-session dirs are the growth vector (one per delivery) and
+are UNIQUELY named, so pruning one can never conflict with a concurrent PR: two branches
+deleting the same inherited dir is a delete/delete (auto-merges), and each delivery adds its
+own distinct dir. Leaving an inherited per-session dir would be harmless anyway (prefer-newest
+ignores it) — pruning is purely to stop unbounded accumulation. The alternative,
+retain-as-history, was rejected as unbounded growth of permanently-superseded dirs with no
+reader. Pruning is best-effort: a prune failure is logged, never fatal to the delivery.
+
+**The shared flat path is deliberately NOT pruned per-delivery.** An earlier iteration of this
+addendum also pruned the flat `delivery/trust.bundle` legacy seals on every publish (to
+"migrate off" the shared path). That was reverted: during the migration window a concurrent PR
+may still seal to the flat path (this was written while PR #370 had an open flat-path seal),
+and a per-delivery deletion of that file is a **modify/delete conflict** against such a PR → a
+DIRTY PR → precisely the no-CI failure mode this whole change exists to remove. Because the
+flat path is a single fixed location (not a growth vector) and prefer-newest selection makes a
+lingering flat bundle harmless, retaining it costs nothing. Removing the flat legacy seals is a
+one-time cleanup for a **dedicated** PR once no open PR still seals to the flat path — not
+something safely bundled into every delivery.
+
+**The SILENT failure mode (documented, not "solved").** No repo-side code can make GitHub
+run `pull_request` workflows on a conflicted PR — that is platform behavior. Per-session
+paths remove the STRUCTURAL cause (the shared-path conflict) for agent-vs-agent delivery
+contention, which is the overwhelming majority of the incidents. The residual — a PR that
+goes DIRTY for some OTHER reason (a genuine same-file edit conflict with `main`) still gets
+no CI silently — is addressed by making the failure mode LOUD where we can: the deliver
+skill now documents the DIRTY→no-CI symptom and its diagnosis (`gh pr view --json
+mergeStateStatus`), and `discoverBundle()` emits a grep-stable `#379: examined N delivery
+candidate(s) … none attests this change …` concurrency hint so the next agent can tell a
+per-session collision apart from a plain stale/absent bundle. #335's detectability half
+(treating `mergeStateStatus=DIRTY` as a first-class steering/doctor input) remains open and
+is explicitly NOT claimed closed here.
+
+**Security: the forgery surface moved with the write path.** `scripts/hooks/config-protection.js`
+(and its `context/` mirror) protected only the flat `delivery/trust.bundle` /
+`delivery/trust.checkpoint.json` from direct agent Write/Edit/cp/redirect. Its three
+delivery regexes now carry an optional `(?:[^/]+\/)?` segment so `delivery/<slug>/trust.*`
+is equally blocked — otherwise moving the write path would have opened a hand-forgery hole
+one directory down. Regression-locked by `test_gate_lockdown.sh` AC1.26b/c/d. The
+`delivery/*` gitignore already covers per-session dirs (they are force-added deliberately per
+delivery exactly like the flat path).
+
+**Residuals (honest):** (1) the DIRTY→no-CI platform behavior for non-per-session conflicts
+is documented, not eliminated (above). (2) The per-session dir name is derived from the
+local session slug; a colliding slug across two sessions would re-share a path — acceptable
+because ownership is still decided by commit ancestry (a stale same-named sibling is ignored,
+not trusted), and slugs are session-unique in practice. (3) Selection correctness does NOT
+depend on merge strategy: prefer-newest resolves the owning candidate for both squash-merge
+(inherited seals are non-ancestors, trivially not-owning) and merge-commit (inherited seals
+can be ancestors, but attest an OLDER commit than this session's, so they lose on recency)
+histories — the merge-commit case was the concrete defect that forced prefer-newest and is
+regression-locked by `test_trust_reconcile_negatives.sh` §8d against a real git repo. (4) The
+flat legacy seals still on `main` are retained by design (see cleanup policy above) and remain
+until a dedicated one-time cleanup PR; they are harmless (prefer-newest) but do accumulate as a
+single fixed path, not a growth vector. This addendum changes WHERE seals live and HOW the
+owning one is chosen; it does not touch Step 1 (fresh verify), the DECLARED exemption path, or
+any fail-closed verdict — all of which are regression-locked unchanged.

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/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.

package/docs/decisions/flow-skill-kit-tool-boundary.md

@@ -0,0 +1,20 @@
+---
+status: needs-decision
+subject: Flow / Skill / Kit / Tool boundary
+decided: 2026-07-03
+evidence:
+  - kind: adr
+    ref: docs/adr/0007-flow-skill-kit-tool-boundary.md
+  - kind: adr
+    ref: docs/adr/0007-skill-audit.md
+---
+# Flow / Skill / Kit / Tool boundary
+
+This subject has provenance in frozen ADR history ([0007-flow-skill-kit-tool-boundary.md](../adr/0007-flow-skill-kit-tool-boundary.md), [0007-skill-audit.md](../adr/0007-skill-audit.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 / skill / kit / tool 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/graph-knowledge-provider.md

@@ -0,0 +1,63 @@
+---
+status: current
+subject: Graph knowledge provider
+decided: 2026-07-03
+evidence:
+  - kind: issue
+    ref: https://github.com/kontourai/flow-agents/issues/327
+  - kind: doc
+    ref: docs/spikes/graph-provider-2026-07.md
+  - kind: doc
+    ref: context/contracts/knowledge-store-contract.md
+  - kind: adr
+    ref: docs/decisions/knowledge-store-provider.md
+---
+
+# Graph knowledge provider
+
+The Knowledge Kit ships a `neo4j` knowledge-store provider: a real, queryable
+graph implementation of the #317 read interface, synced from the file/work-item
+providers. It is the OWNER'S OPT-IN personal default — the file providers remain
+the portfolio default. This decision explicitly overrides the #318 spike's
+defer-as-default verdict at the owner's request ("I still want the graph
+implementation even if it's not the default — it can be my default").
+
+## Decision
+
+- **Engine: Neo4j Community 5 over Docker.** The #318 spike compared Neo4j and
+  Kuzu; Kuzu was abandoned upstream (Oct 2025, repo archived), so Neo4j — actively
+  maintained, with the Browser for human exploration and the portable Cypher
+  baseline — is the engine when a graph is used. Kuzu, Aura/hosted, and
+  graph-as-primary-storage are non-goals.
+- **The graph is a materialized VIEW, never an authority.** File stores stay the
+  source of truth. A `sync` command reuses the #317 providers as READERS (no
+  forked extractors) and MERGEs their combined graph into Neo4j idempotently
+  (content-keyed hash guard: a re-sync of unchanged stores reports zero writes),
+  recording a snapshot digest + timestamp. The write side is proposals-only, like
+  every other provider — the graph never bypasses the human-curated stores.
+- **Connection by reference, never hardcoded.** Credentials resolve from
+  `NEO4J_URI` / `NEO4J_USER` / `NEO4J_PASSWORD` (this repo does not consume
+  `@kontourai/datum` yet, so we follow the existing env-reference precedent; a
+  future datum adoption resolves the same three names without touching call
+  sites).
+- **Cypher-backed query/health verbs when selected.** The five canonical spike
+  queries (transitive blocker closure, contradiction candidates, node-type-aware
+  orphans, duplicate candidates WITH 5-char stemming, shortest path) run as live
+  Cypher when a Neo4j is reachable and fall back to a portable JS spelling
+  (same answers) otherwise. The stemming lesson is preserved: exact title tokens
+  missed the traverse#14~#8 duplicate; stemming catches it.
+- **Never a hard dependency.** `neo4j-driver` is an optionalDependency, lazily
+  imported. A missing driver OR an unreachable server degrades to the file
+  providers with a single clear message. CI has no Neo4j: unit tests + the
+  conformance suite run against an injected fake driver; the live integration
+  test is gated on `NEO4J_URI` (or a detected Docker Neo4j) and skips loudly.
+- **Selection is config-driven, default file.** `KNOWLEDGE_PROVIDER=neo4j`
+  (repo/user-level) opts in; anything else stays on the file providers. See the
+  README "Graph provider (opt-in)" section for the owner path.
+
+## Consequences
+
+The one-off spike wins (a missing blocker edge, ADR-0007 contradiction, the
+near-duplicate canary trio) become a standing capability without forcing graph
+ops on any repo or workflow that does not opt in. The provider passes the same
+#317 conformance suite as the file providers on its read side.

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

@@ -0,0 +1,18 @@
+---
+status: needs-decision
+subject: Hook core/kit boundary
+decided: 2026-07-03
+evidence:
+  - kind: adr
+    ref: docs/adr/0009-canonical-hook-core-kit-boundary.md
+---
+# Hook core/kit boundary
+
+This subject has provenance in frozen ADR history ([0009-canonical-hook-core-kit-boundary.md](../adr/0009-canonical-hook-core-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 hook core/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/index.md

@@ -10,8 +10,27 @@ Numbered ADRs under `docs/adr/` are frozen history and are not listed here.
 
 | Topic | Status | Decision |
 | --- | --- | --- |
+| [agent-coordination](./agent-coordination.md) | needs-decision | Agent coordination |
+| [anti-gaming-trust-security](./anti-gaming-trust-security.md) | needs-decision | Anti-gaming trust security |
+| [context-lifecycle](./context-lifecycle.md) | needs-decision | Context lifecycle |
+| [core-domain-kit-boundary](./core-domain-kit-boundary.md) | needs-decision | Core vs domain kit boundary |
 | [decision-records](./decision-records.md) | current | Decision records |
+| [flow-flow-agents-boundary](./flow-flow-agents-boundary.md) | needs-decision | Flow / Flow Agents boundary |
+| [flow-kit](./flow-kit.md) | needs-decision | Flow Kit |
+| [flow-skill-kit-tool-boundary](./flow-skill-kit-tool-boundary.md) | needs-decision | Flow / Skill / Kit / Tool boundary |
+| [graph-knowledge-provider](./graph-knowledge-provider.md) | current | Graph knowledge provider |
+| [hook-core-kit-boundary](./hook-core-kit-boundary.md) | needs-decision | Hook core/kit boundary |
+| [kit-dependency-ownership](./kit-dependency-ownership.md) | needs-decision | Kit dependency ownership |
+| [kit-operation-boundary](./kit-operation-boundary.md) | needs-decision | Kit operation boundary |
+| [knowledge-promote-sub-flow](./knowledge-promote-sub-flow.md) | current | Knowledge promote sub-flow |
 | [knowledge-store-provider](./knowledge-store-provider.md) | current | Knowledge store provider |
+| [kontour-resource-contract](./kontour-resource-contract.md) | needs-decision | Kontour Resource Contract |
+| [mcp-posture](./mcp-posture.md) | needs-decision | MCP posture |
 | [model-routing](./model-routing.md) | current | Model routing |
 | [promotion-gate](./promotion-gate.md) | current | Promotion gate |
 | [standing-directives](./standing-directives.md) | current | Standing directives |
+| [three-hard-boundary-model](./three-hard-boundary-model.md) | needs-decision | Three-hard-boundary model |
+| [trust-reconcile](./trust-reconcile.md) | needs-decision | Trust-reconcile and delivery reconciliation |
+| [typescript-source-policy](./typescript-source-policy.md) | current | TypeScript-first source policy |
+| [workflow-enforcement](./workflow-enforcement.md) | needs-decision | Workflow Enforcement |
+| [workflow-trust-state](./workflow-trust-state.md) | needs-decision | Workflow trust state |

package/docs/decisions/kit-dependency-ownership.md

@@ -0,0 +1,18 @@
+---
+status: needs-decision
+subject: Kit dependency ownership
+decided: 2026-07-03
+evidence:
+  - kind: adr
+    ref: docs/adr/0019-kit-dependency-ownership.md
+---
+# Kit dependency ownership
+
+This subject has provenance in frozen ADR history ([0019-kit-dependency-ownership.md](../adr/0019-kit-dependency-ownership.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 kit dependency ownership, 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/kit-operation-boundary.md

@@ -0,0 +1,18 @@
+---
+status: needs-decision
+subject: Kit operation boundary
+decided: 2026-07-03
+evidence:
+  - kind: adr
+    ref: docs/adr/0008-kit-operation-boundary.md
+---
+# Kit operation boundary
+
+This subject has provenance in frozen ADR history ([0008-kit-operation-boundary.md](../adr/0008-kit-operation-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 kit operation 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/knowledge-promote-sub-flow.md

@@ -0,0 +1,59 @@
+---
+status: current
+subject: Knowledge promote sub-flow
+decided: 2026-07-03
+evidence:
+  - kind: issue
+    ref: https://github.com/kontourai/flow-agents/issues/313
+  - kind: doc
+    ref: context/contracts/knowledge-store-contract.md
+  - kind: doc
+    ref: context/contracts/decision-registry-contract.md
+  - kind: session-archive
+    ref: .kontourai/flow-agents/decision-registry-shape/decision-registry-shape--idea-to-backlog.md
+---
+
+# Knowledge promote sub-flow
+
+Session promotion runs through a Knowledge Kit FlowDefinition
+(`kits/knowledge/flows/promote.flow.json`, id `knowledge.promote`) with four
+steps — **ingest → distill → link → health** — so promotion quality stops
+depending on which agent did it. This is the first codebase-facing Knowledge Kit
+flow and the first "flow within a flow".
+
+## Decision
+
+- **Four steps.** *ingest* reads a completed session dir (read-only) for its
+  plan/evidence/critique/learnings/transcripts; *distill* produces DRAFT deltas —
+  decision-registry topic files (validated against
+  `schemas/decision-record.schema.json` before proposing), CONTEXT.md vocabulary
+  additions, and `docs/learnings` entries; *link* attaches provenance (PR, merge
+  SHA, session-archive path, touched topics) as `evidence[]` refs; *health* runs
+  contradiction detection over the topic files.
+- **Built on the #317 provider interface, not a forked reader.** Health reads the
+  registry through the git-repo knowledge-store provider and reuses the
+  provider-agnostic `duplicate-detection` verb: two topics with overlapping
+  subject nouns and divergent content are a contradiction. The report names BOTH
+  topics; a **merge-repair PROPOSAL** (schema-valid, `status: "proposed"`) names a
+  merge target. Merge-repair is a proposal, never an auto-edit.
+- **Proposals-only (R4).** The sub-flow NEVER writes docs directly. Every output
+  lands under `<session>/proposals/`; the promote step's human/agent applies the
+  drafts it accepts. A filesystem diff during a run shows zero writes outside the
+  session/proposal dir.
+- **Composition.** `knowledge.promote` is a true composable FlowDefinition — a
+  parent step can `uses_flow: "knowledge.promote"` and the resolver resolves its
+  gates (it `exports` every gate claim). It is invoked standalone AND from the
+  Builder promote step. The builder edge is a **documented composition** (the
+  deliver skill's promote step names it as the assisted path) rather than a nested
+  builder gate, because #312's `promote` CLI — not a flow gate — is the recording
+  mechanism, and the sub-flow's outputs are proposals a human/agent applies.
+
+## Rationale
+
+Knowledge Kit had the verbs (capture, compile, link, health) pointed at personal
+knowledge; the codebase was the missing consumer. Promotion (once gated by #312)
+still relied on ad-hoc judgement about WHAT to promote. Making the promote step
+run a Knowledge Kit pipeline over the session artifacts gives the codebase its
+knowledge use case as a composable sub-flow, while proposals-only discipline and
+the shared #317 provider interface keep it from forking a second reader or writing
+into a human-curated store.

package/docs/decisions/kontour-resource-contract.md

@@ -0,0 +1,18 @@
+---
+status: needs-decision
+subject: Kontour Resource Contract
+decided: 2026-07-03
+evidence:
+  - kind: adr
+    ref: docs/adr/0005-kubernetes-inspired-resource-contracts.md
+---
+# Kontour Resource Contract
+
+This subject has provenance in frozen ADR history ([0005-kubernetes-inspired-resource-contracts.md](../adr/0005-kubernetes-inspired-resource-contracts.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 kontour resource contract, 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/mcp-posture.md

@@ -0,0 +1,18 @@
+---
+status: needs-decision
+subject: MCP posture
+decided: 2026-07-03
+evidence:
+  - kind: adr
+    ref: docs/adr/0011-mcp-posture.md
+---
+# MCP posture
+
+This subject has provenance in frozen ADR history ([0011-mcp-posture.md](../adr/0011-mcp-posture.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 MCP posture, 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/three-hard-boundary-model.md

@@ -0,0 +1,18 @@
+---
+status: needs-decision
+subject: Three-hard-boundary model
+decided: 2026-07-03
+evidence:
+  - kind: adr
+    ref: docs/adr/0016-three-hard-boundary-model.md
+---
+# Three-hard-boundary model
+
+This subject has provenance in frozen ADR history ([0016-three-hard-boundary-model.md](../adr/0016-three-hard-boundary-model.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 Three-hard-boundary model, update this
+file's `status` to `current`, add rationale, and keep the `adr` evidence
+links as provenance for the history that led here.