@kontourai/flow-agents 2.4.0 → 3.1.0

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,5 +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/knowledge-store-provider.md

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

package/docs/decisions/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/model-routing.md

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

package/docs/decisions/standing-directives.md

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

package/docs/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`).

package/docs/decisions/workflow-enforcement.md

@@ -0,0 +1,18 @@
+---
+status: needs-decision
+subject: Workflow Enforcement
+decided: 2026-07-03
+evidence:
+  - kind: adr
+    ref: docs/adr/0001-flow-agents-consumes-flow.md
+---
+# Workflow Enforcement
+
+This subject has provenance in frozen ADR history ([0001-flow-agents-consumes-flow.md](../adr/0001-flow-agents-consumes-flow.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 workflow enforcement, 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/workflow-trust-state.md

@@ -0,0 +1,20 @@
+---
+status: needs-decision
+subject: Workflow trust state
+decided: 2026-07-03
+evidence:
+  - kind: adr
+    ref: docs/adr/0004-gates-expect-surface-claims.md
+  - kind: adr
+    ref: docs/adr/0010-workflow-trust-state-as-hachure-bundle.md
+---
+# Workflow trust state
+
+This subject has provenance in frozen ADR history ([0004-gates-expect-surface-claims.md](../adr/0004-gates-expect-surface-claims.md), [0010-workflow-trust-state-as-hachure-bundle.md](../adr/0010-workflow-trust-state-as-hachure-bundle.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 workflow trust state, 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/fixture-ownership.md

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

package/docs/workflow-shared-contracts.md

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

package/docs/workflow-usage-guide.md

@@ -114,6 +114,12 @@ Expected artifact:
 
 When a repository has backlog provider settings, `pull-work` should use those settings without requiring the user to name the board. In Flow Agents, `npm run effective-backlog-settings -- --repo-path . --json` resolves `kontourai/flow-agents` to GitHub Project `kontourai/1`, so a prompt like `use pull-work` is enough for the configured provider path.
 
+### Assignment ownership: the third provider leg
+
+Beside the `WorkItemProvider` (what work exists) and `BoardProvider` (how it is grouped/ranked) settings above, `pull-work` also reads `AssignmentProvider` settings to decide who currently owns a candidate work item before offering it. This is durable, human-visible ownership — a GitHub issue assignee, an `agent:claimed` label, and a versioned machine-readable claim comment (or, for tracker-less repos and evals, an equivalent local JSON record) — joined against the ephemeral liveness presence layer so a crashed session's stale claim never blocks a second session from picking up the same work.
+
+Settings live at `context/settings/assignment-provider-settings.json` (validated by `schemas/assignment-provider-settings.schema.json`), mirroring the same `defaults`/`projects[]` shape as the backlog provider settings above; resolve them with `npm run effective-assignment-provider-settings -- --repo-path . --json`. See `context/contracts/assignment-provider-contract.md` for the full `claim`/`release`/`supersede`/`status`/`list` vocabulary, the assignment ⋈ liveness join table, and the human-assignee ask-first policy.
+
 Direct `pull-work` remains a normal workflow primitive. The Builder Kit build path adds the pickup Probe/design-probe handoff before planning; it does not require Surface/Veritas trust-backed gates and does not replace direct primitive use.
 
 Builder Kit build is the product-level entry point for implementation pickup. In that mode, `pull-work` may guide the next step automatically as `pull-work -> design-probe / pickup-probe`; direct `pull-work` still stops with a `plan-work` handoff unless you ask to continue.
@@ -249,7 +255,7 @@ When verification or evidence gates route work backward, the handoff must name b
 
 For pickup or planning alignment gaps, `decision_gap -> design-probe` means returning to the pickup Probe record, resolving the missing decision or recording an accepted gap, and only then retrying `plan-work`.
 
-Pickup Probe may update durable docs only when the decision is no longer a transient planning note. Use `CONTEXT.md` for glossary-style terminology decisions, create context files lazily only when a resolved term has no existing home, and create ADRs only for hard-to-reverse, surprising decisions that came from a real trade-off. Keep selected-work details, provider snapshots, unresolved questions, and accepted gaps in workflow artifacts until the work is accepted.
+Pickup Probe may update durable docs only when the decision is no longer a transient planning note. Use `CONTEXT.md` for glossary-style terminology decisions, create context files lazily only when a resolved term has no existing home, and record decision subjects as decision-registry deltas (`docs/decisions/<slug>.md`, revise-vs-create against `docs/decisions/index.md`) rather than numbered ADRs — see `context/contracts/probe-docs-write-contract.md`. Keep selected-work details, provider snapshots, unresolved questions, and accepted gaps in workflow artifacts until the work is accepted.
 
 ## 7. Check Goal Fit Before Stopping