@kontourai/flow-agents 3.0.0 → 3.1.0

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

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.

package/docs/decisions/trust-reconcile.md

@@ -0,0 +1,20 @@
+---
+status: needs-decision
+subject: Trust-reconcile and delivery reconciliation
+decided: 2026-07-03
+evidence:
+  - kind: adr
+    ref: docs/adr/0020-trust-reconcile-manifest-and-claim-classification.md
+  - kind: adr
+    ref: docs/adr/0022-fail-closed-delivery-reconciliation-with-governed-exemptions.md
+---
+# Trust-reconcile and delivery reconciliation
+
+This subject has provenance in frozen ADR history ([0020-trust-reconcile-manifest-and-claim-classification.md](../adr/0020-trust-reconcile-manifest-and-claim-classification.md), [0022-fail-closed-delivery-reconciliation-with-governed-exemptions.md](../adr/0022-fail-closed-delivery-reconciliation-with-governed-exemptions.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 Trust-reconcile and delivery reconciliation, 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/typescript-source-policy.md

@@ -0,0 +1,48 @@
+---
+status: current
+subject: TypeScript-first source policy
+decided: 2026-07-04
+evidence:
+  - kind: adr
+    ref: docs/adr/0006-typescript-first-source-policy.md
+  - kind: session-archive
+    ref: .kontourai/flow-agents/kontourai-flow-agents-311/kontourai-flow-agents-311--deliver.md
+  - kind: issue
+    ref: https://github.com/kontourai/flow-agents/issues/311
+---
+
+# TypeScript-first source policy
+
+Kontour product and runtime source defaults to TypeScript across Flow, Flow
+Agents, Surface, Veritas, and `kontourai.io`. New durable product code, runtime
+adapters, package APIs, CLI behavior, workflow orchestration, hooks, provider
+bridges, and shared contracts are authored in TypeScript by default in
+repositories that are TypeScript-enabled or migrating toward TypeScript.
+
+## Decision
+
+- TypeScript-enabled repositories expose a typecheck or build validation that
+  proves the authored TypeScript surface compiles, and CI runs that validation
+  before code is treated as releasable.
+- Narrow JavaScript/MJS/CJS exceptions remain acceptable: package/tool
+  configuration that expects JS/MJS, generated docs/site assets, thin
+  shell-adjacent launchers, fixtures/examples/tests following existing local
+  convention, and historical archived/vendored/generated artifacts that are not
+  edited as active source. Exceptions stay narrow — expanding product/runtime
+  behavior in JS/MJS is a deliberate exception or routed into a migration plan.
+- Repositories with nontrivial non-TypeScript runtime source track staged
+  migration through repo-specific issues rather than being grandfathered as
+  permanent direction (see the original inventory and linked migration issues
+  in the frozen ADR below).
+
+## Rationale
+
+Cross-repo shared source, contracts, adapters, and workflow tooling need a
+consistent default language, or new work deepens fragmentation and turns every
+existing non-TypeScript file into an implicit permanent exception. This is a
+purely technical, already-settled call: the frozen ADR below made the decision
+on 2026-05-31 and it has not changed. This entry upgrades the ADR-freeze
+cutover's `needs-decision` stub for this subject (issue #314) to a living
+decision — nothing new is decided here beyond recording that the frozen ADR's
+call still stands, per the Probe docs-write contract's worked example
+(`context/contracts/probe-docs-write-contract.md`).