@kontourai/flow-agents 2.3.0 → 3.0.0

package/docs/decisions/decision-records.md

@@ -0,0 +1,57 @@
+---
+status: current
+subject: Decision records
+decided: 2026-07-03
+evidence:
+  - kind: issue
+    ref: https://github.com/kontourai/flow-agents/issues/310
+  - kind: session-archive
+    ref: .kontourai/flow-agents/decision-registry-shape/decision-registry-shape--idea-to-backlog.md
+  - kind: pr
+    ref: https://github.com/kontourai/flow-agents/pull/316
+---
+
+# Decision records
+
+New decisions are recorded as **topic-keyed living decision records** at
+`docs/decisions/<topic-slug>.md`, one file per decision subject. Numbered ADRs
+(`docs/adr/NNNN-*.md`) are frozen history and are never written for new
+decisions.
+
+## Decision
+
+- Topic files are keyed by decision **subject** slugs drawn from the CONTEXT.md
+  domain vocabulary; the vocabulary is the topic namespace. This removes ADR
+  numbering collisions and makes topic identity downstream of ubiquitous
+  language.
+- **Supersession is an edit** to the topic file. Contradicting appendices are
+  impossible by construction; the file always holds the current answer plus lean
+  rationale. `superseded_by` / `merged_into` tombstones cover the rarer case of a
+  subject moving or merging to another slug.
+- The context that led to a decision is **linked** to archived session artifacts,
+  PRs, and frozen ADRs via `evidence[]`, never inlined. This fixes ADR bloat;
+  promotion-as-retirement provides the archive.
+- **CONTEXT.md is the only external compatibility surface** (grill-with-docs
+  interop). The numbered-ADR file format is not adopted for new decisions — the
+  behavior is inherited, not the failure mode.
+- Existing ADRs are **frozen and indexed, never converted**; history stays
+  immutable provenance. (Freeze tooling is issue #314.)
+- Frontmatter is YAML validated by `schemas/decision-record.schema.json`
+  (`status`, `subject`, `decided`, `evidence[]`, and the relationship fields),
+  enabling machine health checks.
+- A generated `docs/decisions/index.md` (slug + one-liner) is referenced from
+  CONTEXT.md so retrieval-at-write matching has a cheap, always-loaded index.
+
+## Rationale
+
+Numbered ADRs accumulate contradictions (new decisions append rather than
+supersede), bloat (derivation context inlined with the decision), and numbering
+collisions at multi-contributor scale — observed across ~6 portfolio repos and
+owner-ratified as a redesign on 2026-07-03. Topic-keyed living records make the
+current answer to any settled question findable in one place, make supersession
+an edit rather than a contradicting appendix, and let multiple contributors work
+without colliding on sequence numbers.
+
+flow-agents is the first consumer: this record self-hosts the decision, and the
+full normative contract lives at
+`context/contracts/decision-registry-contract.md`.

package/docs/decisions/index.md

@@ -0,0 +1,17 @@
+---
+title: Decision Index
+---
+
+# Decision Index
+
+Generated by `npm run gen:decisions-index`. Do not edit by hand.
+Topic-keyed living decision records per `context/contracts/decision-registry-contract.md`.
+Numbered ADRs under `docs/adr/` are frozen history and are not listed here.
+
+| Topic | Status | Decision |
+| --- | --- | --- |
+| [decision-records](./decision-records.md) | current | Decision records |
+| [knowledge-store-provider](./knowledge-store-provider.md) | current | Knowledge store provider |
+| [model-routing](./model-routing.md) | current | Model routing |
+| [promotion-gate](./promotion-gate.md) | current | Promotion gate |
+| [standing-directives](./standing-directives.md) | current | Standing directives |

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/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/promotion-gate.md

@@ -0,0 +1,52 @@
+---
+status: current
+subject: Promotion gate
+decided: 2026-07-02
+evidence:
+  - kind: issue
+    ref: https://github.com/kontourai/flow-agents/issues/312
+  - kind: session-archive
+    ref: .kontourai/flow-agents/decision-registry-shape/decision-registry-shape--idea-to-backlog.md
+  - kind: doc
+    ref: docs/workflow-artifact-lifecycle.md
+---
+
+# Promotion gate
+
+Archiving a delivered session is **gated on** promoting its durable residue. The
+sequence is `final acceptance -> promote -> archive`; durable-residue extraction
+is the archival act, not a parallel checklist chore.
+
+## Decision
+
+- The sidecar `promote` step records **what was promoted where** and writes a
+  **promotion claim** into the session `trust.bundle`. The claim is
+  **session-local by construction** — check kind `policy`, evidence type
+  `policy_rule`, no command / `execution.label` — so it needs **no new
+  reconcile-manifest entry** and can **never** become a `[not-run]` /
+  unbacked-command divergence at CI `trust-reconcile`. The reconciler classifies
+  it session-local and accepts it as an ATTESTED claim.
+- The claim's evidence refs are the **durable doc paths written**
+  (`docs/decisions/<slug>.md`, `CONTEXT.md`, `docs/learnings/*`, …); each is
+  verified to exist on disk at record time (a missing path fails loud) and is
+  mirrored into an auditable `promotion.json`. The claim is detected by the
+  archive gate and validators via `claim.metadata.promotion`.
+- An **explicit empty-promotion** path (`promote --none --reason "<why>"`) records
+  an auditable no-residue claim, so "nothing needed promoting" is a recorded
+  decision rather than a silent skip.
+- `workflow-artifact-cleanup-audit` classifies a **delivered/accepted** session
+  that reached a terminal shape **without** a promotion claim as a
+  `cleanup_candidate` (archive blocked) with a remedy naming the `promote` step;
+  **with** the claim (real residue or `--none`) it stays `terminal_done`.
+  Already-`archived` sessions are past the gate and are never re-flagged (no
+  backfill of historical archives).
+
+## Rationale
+
+Docs-promotion was a Final Acceptance checklist item done inconsistently; the
+2026-07 archival sweep retired ~40 sessions whose promotion had happened ad hoc.
+Making promotion **structural** — a claim the archive classifier checks — means no
+delivered work is retired without its knowledge extracted. Reusing the existing
+trust.bundle / stop-gate machinery (rather than a parallel mechanism) keeps the
+signal visible to validators without new manifest surface, and the session-local
+claim shape guarantees the gate can never masquerade as a CI-reconcilable command.

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/developer-architecture.md

@@ -106,7 +106,7 @@ flowchart TB
   Evidence -->|missing evidence| Plan
 ```
 
-**Current state:** The durable handoff surface is a pair of human-readable Markdown artifacts and machine-readable JSON sidecars under `.flow-agents/<slug>/`. Verification, critique, release, and learning records are explicit artifacts rather than hidden chat memory.
+**Current state:** The durable handoff surface is a pair of human-readable Markdown artifacts and machine-readable JSON sidecars under `.kontourai/flow-agents/<slug>/`. Verification, critique, release, and learning records are explicit artifacts rather than hidden chat memory.
 
 **Programmatic API (for native hosts):** The canonical sidecar writer/validator is importable as a library, not only via the `flow-agents-workflow-sidecar` CLI. A host that records workflow evidence natively should import the package root rather than reimplement validated read / merge / write:
 

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) | `evals/integration/test_assignment_provider_local_file.sh`, `evals/integration/test_assignment_provider_github.sh`, `evals/integration/test_pull_work_assignment_join.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. |
@@ -22,6 +23,9 @@ run `npm run validate:source --` and `npm run fixture:retirement-audit --`.
 | `evals/fixtures/pull-work-provider` | work item provider normalization fixtures | `evals/integration/test_pull_work_provider.sh` | Keep while provider normalization preserves blockers, artifact refs, board membership, and freshness metadata. |
 | `evals/fixtures/pull-work-wip-shepherding` | WIP shepherding state fixtures | `evals/static/test_workflow_skills.sh` | Keep while pull-work documents personal versus global WIP behavior. |
 | `evals/fixtures/surface-trust` | Surface trust evidence fixtures | `evals/integration/test_workflow_sidecar_writer.sh` | Keep while sidecar writer maps Surface trust evidence into workflow records. |
+| `evals/fixtures/trust-reconcile-exploits` | WS8 trust-reconcile anti-gaming exploit fixtures (frozen negative regressions) | `evals/integration/test_trust_reconcile_negatives.sh` | Keep while trust-reconcile.js enforces the WS8 iteration-2 soundness properties (no-label test_output, unwaived-assumed, status-misassertion, waiver-on-command); each fixture is a permanent negative regression. |
+| `evals/fixtures/trust-reconcile-mixed-bundle` | WS8 trust-reconcile mixed-evidence end-to-end proof fixture | `evals/integration/test_trust_reconcile_mixed_bundle.sh` | Keep while the trust-reconcile manifest/classification/waiver contract (ADR 0020) is enforced; proves a mixed test_output + session-local + waived bundle passes the CI anchor. |
+| `evals/fixtures/trust-reconcile-ws3` | WS8 AC6 backward-compat fixture: real ws3-kit-dependencies-namespacing old-style bundle | `evals/integration/test_trust_reconcile_negatives.sh` | Keep while backward compatibility with pre-classification (all-test_output) bundles is asserted; proves an old-style bundle still FAILS the same way (no silent pass). |
 | `evals/fixtures/usage-feedback` | usage feedback import/outcome fixtures | `evals/integration/test_usage_feedback_import.sh`, `evals/integration/test_usage_feedback_outcomes.sh`, `evals/integration/test_usage_feedback_report.sh` | Keep while usage feedback import, outcome, and report flows accept JSONL fixture input. |
 | `evals/fixtures/veritas-governance-adapter` | Veritas governance adapter fixtures | `evals/integration/test_veritas_governance_adapter.sh` | Keep while the Veritas adapter supports pass, unconfigured, and secret-failure governance paths. |
 

package/docs/flow-kit-repository-contract.md

@@ -30,7 +30,7 @@ npm run kit -- status example-kit --dest /path/to/installed-flow-agents
 npm run kit -- activate --dest /path/to/installed-flow-agents --format json
 ```
 
-`--dest` is the installed bundle or workspace root. When omitted, the command uses the current working directory. Tests and automation should pass a temp destination; the command does not need to write to a user home directory.
+`--dest` is the installed bundle, workspace root, isolated Codex home, or test fixture destination. When omitted, Codex-oriented kit commands install into the normal Codex home: `CODEX_HOME` when it is set, otherwise `~/.codex`. Pass `--dest` to override that destination for workspace installs, isolated homes, or tests.
 
 Install always runs the same repository validation used by `npm run validate:source -- --kit` before it creates or updates local install state. A validation failure exits nonzero and leaves the destination registry and copied kits unchanged.
 
@@ -64,7 +64,7 @@ Reinstalling the same kit id from the same source with the same content is idemp
 
 ## Runtime Activation
 
-`activate` reads the built-in Kit Catalog and local install overlay, selects a runtime adapter, and writes generated runtime-local files into the destination workspace. When `--adapter` is omitted, Flow Agents selects the only implemented adapter:
+`activate` reads the built-in Kit Catalog and local install overlay, selects a runtime adapter, and writes generated non-durable projection files into the destination workspace. When `--adapter` is omitted, Flow Agents selects the only implemented adapter:
 
 ```text
 codex-local
@@ -80,13 +80,13 @@ The `codex-local` adapter supports only Flow Definition assets declared in `flow
 
 Activation reuses the installed local kit registry at `<dest>/kits/local/installed-kits.json`; it does not duplicate installed kit state and does not edit `kits/catalog.json`.
 
-Generated files are written under:
+Generated adapter projections are written under:
 
 ```text
-<dest>/.flow-agents/runtime/codex/
+<dest>/.kontourai/flow-agents/projections/codex/
 ```
 
-Flow Definition copies are placed under `flows/<kit-id>/<flow-id>.flow.json`, and activation writes an `activation.json` manifest in the same runtime-local area.
+Flow Definition copies are placed under `flows/<kit-id>/<flow-id>.flow.json`, and activation writes an `activation.json` manifest in the same projection area. These files are regenerable from the Kit Catalog plus `kits/local`; they are not the durable run state for a workflow.
 
 The stable activation diagnostics include:
 

package/docs/getting-started.md

@@ -24,6 +24,16 @@ npx @kontourai/flow-agents init --runtime opencode    --dest . --yes
 
 The installer copies agents, skills, context contracts, hook scripts, Kit assets, and the Flow Agents telemetry descriptor into the workspace. The Builder Kit installs automatically. Your agent reads those files at startup; no plugin registry required.
 
+For a normal Codex global install, target the Codex home instead of a project workspace:
+
+```bash
+npx @kontourai/flow-agents init --runtime codex --global --activate-kits --yes
+```
+
+That installs into `CODEX_HOME` when it is set, otherwise `~/.codex`. Use `--dest /path/to/codex-home` only when you need an explicit override for an isolated install, CI fixture, or test.
+
+Keep generated Codex base config lean. Put profile-specific model, provider, and approval settings in separate `<profile>.config.toml` files and select them with `codex --profile <name>`.
+
 **What lands in the workspace:**
 
 - `agents/`, `skills/`, `context/` — skill definitions and shared contracts the agent follows
@@ -84,7 +94,7 @@ The agent will run the `builder-shape` / `idea-to-backlog` skill, which:
 3. drafts a shaped work item with a stated outcome, non-goals, acceptance criteria, and a verification expectation
 4. stops at the `breakdown-gate` and waits for you to confirm before creating GitHub issues
 
-You will see the agent write a local artifact at `.flow-agents/<slug>/<slug>--idea-to-backlog.md`. That artifact is the machine-readable input to the next stage — not a summary in the chat window.
+You will see the agent write a local artifact at `.kontourai/flow-agents/<slug>/<slug>--idea-to-backlog.md`. That artifact is the machine-readable input to the next stage — not a summary in the chat window.
 
 To continue and file the GitHub issue:
 
@@ -128,7 +138,7 @@ Use verify-work on the current branch and report what evidence is present.
 
 ### What you observe
 
-- **Between each step**, the agent writes a local session sidecar under `.flow-agents/<slug>/` — `state.json`, `acceptance.json`, `evidence.json`, and `handoff.json`. These survive compaction, tab close, or a new session. A future session resumes from recorded state.
+- **Between each step**, the agent writes a local session sidecar under `.kontourai/flow-agents/<slug>/` — `state.json`, `acceptance.json`, `evidence.json`, and `handoff.json`. These survive compaction, tab close, or a new session. A future session resumes from recorded state.
 - **At each gate**, the agent either presents the evidence and moves forward, or blocks and explains what is missing. It does not make up a confident summary and proceed.
 - **The stop-goal-fit hook** (at L2) prevents the agent from stopping when evidence is still incomplete — you see a warning or block rather than "all done!" on partial work.
 - **If verify fails**, the verify-gate routes back to execution (or plan, or design-probe, depending on the failure class) and tries again — up to three times before hard-blocking.

package/docs/integrations/harness-install.md

@@ -79,7 +79,8 @@ The install appends rather than replaces, so existing hooks are not removed. Rev
       …
   skills/
     …
-  .flow-agents/            ← runtime workflow artifacts (not committed)
+  .kontourai/
+    flow-agents/           ← runtime workflow artifacts (not committed)
 ```
 
 ## opencode

package/docs/kit-authoring-guide.md

@@ -54,7 +54,7 @@ Required fields:
 | `name` | Non-empty display name |
 | `flows` | Non-empty list; each entry must have `id` and `path` |
 
-Optional fields: `product_name`, `description`, `skills`, `docs`, `adapters`, `evals`, `assets`. Optional fields list relative asset paths or objects with `id`, `path`, and optional `description`. `skills` and `docs` assets are activated by both adapters alongside flows. `adapters`, `evals`, and `assets` appear in diagnostics as `skipped_assets` (see the Activate section for the full per-adapter table).
+Optional fields: `product_name`, `description`, `skills`, `docs`, `adapters`, `evals`, `assets`, `dependencies` (cross-kit dependency declarations; see [Cross-kit dependencies](#cross-kit-dependencies)). Optional fields list relative asset paths or objects with `id`, `path`, and optional `description`. `skills` and `docs` assets are activated by both adapters alongside flows. `adapters`, `evals`, and `assets` appear in diagnostics as `skipped_assets` (see the Activate section for the full per-adapter table).
 
 ## Minimal flow file
 
@@ -91,6 +91,22 @@ A Flow Definition at minimum needs `id`, `version`, `steps`, and `gates`. Steps
 
 The `id` in the flow file should match the `id` declared in `kit.json`'s `flows` list. Look at `kits/builder/flows/shape.flow.json` and `kits/builder/flows/build.flow.json` in this repository for fuller examples of multi-step flows with required and optional gate evidence.
 
+Flow Definitions may compose another declared Flow Definition at a step with `uses_flow`. The parent keeps lifecycle ownership (`active_flow_id` can remain the parent flow), while gate resolution for that step comes from the child flow with the same step id. Use this for reusable extensions such as publish, CI merge readiness, or learning closeout:
+
+```json
+{
+  "id": "builder.build",
+  "steps": [
+    { "id": "verify", "next": "pr-open" },
+    { "id": "pr-open", "next": "merge-ready-ci", "uses_flow": "builder.publish-learn" },
+    { "id": "merge-ready-ci", "next": "learn", "uses_flow": "builder.publish-learn" },
+    { "id": "learn", "next": "done", "uses_flow": "builder.publish-learn" }
+  ]
+}
+```
+
+The child flow should declare the gates for those step ids and list the claim types it intentionally exposes in `exports` (expectation ids are also accepted for non-claim expectations). Composition fails closed when a child gate expectation is not exported. Parent verification is still determined by trust-bundle claims: required child claims that are missing, disputed, or `not_verified` prevent the composed parent from being treated as verified.
+
 ## Validate
 
 Before installing or sharing a kit, run validation from the flow-agents checkout:
@@ -144,13 +160,13 @@ The `codex-local` adapter is selected automatically. To activate for Strands, pa
 
 ### What each adapter activates
 
-Each adapter copies declared assets into `.flow-agents/runtime/<adapter>/` and produces an `activation.json` manifest. The table below shows which asset classes are activated today:
+Each adapter copies declared assets into `.kontourai/flow-agents/projections/<adapter>/` and produces an `activation.json` manifest. The table below shows which asset classes are activated today:
 
 | Asset class | `codex-local` | `strands-local` | Notes |
 |---|---|---|---|
-| `flows` | Activated — `.flow-agents/runtime/codex/flows/<kit-id>/<asset-id>.flow.json` | Activated — `.flow-agents/runtime/strands/flows/<kit-id>/<asset-id>.flow.json` | Gate definitions read by each adapter's flow-routing layer. |
-| `skills` | Activated — `.flow-agents/runtime/codex/skills/<kit-id>/<filename>` | Activated — `.flow-agents/runtime/strands/skills/<kit-id>/<filename>` | Agent guidance markdown. For codex-local, reference these paths from AGENTS.md. For strands-local, the Strands steering layer can glob for `*.md` under `skills/` during system-prompt injection. |
-| `docs` | Activated — `.flow-agents/runtime/codex/docs/<kit-id>/<filename>` | Activated — `.flow-agents/runtime/strands/docs/<kit-id>/<filename>` | Documentation assets. Co-located with skill files for easy reference. |
+| `flows` | Activated — `.kontourai/flow-agents/projections/codex/flows/<kit-id>/<asset-id>.flow.json` | Activated — `.kontourai/flow-agents/projections/strands/flows/<kit-id>/<asset-id>.flow.json` | Gate definitions read by each adapter's flow-routing layer. |
+| `skills` | Activated — `.kontourai/flow-agents/projections/codex/skills/<kit-id>/<filename>` | Activated — `.kontourai/flow-agents/projections/strands/skills/<kit-id>/<filename>` | Agent guidance markdown. For codex-local, reference these paths from AGENTS.md. For strands-local, the Strands steering layer can glob for `*.md` under `skills/` during system-prompt injection. |
+| `docs` | Activated — `.kontourai/flow-agents/projections/codex/docs/<kit-id>/<filename>` | Activated — `.kontourai/flow-agents/projections/strands/docs/<kit-id>/<filename>` | Documentation assets. Co-located with skill files for easy reference. |
 | `adapters` | `skipped_assets` | `skipped_assets` | Framework or runtime adapter code — not copied by the activation layer. |
 | `evals` | `skipped_assets` | `skipped_assets` | Evaluation suites — not run or copied during activation. |
 | `assets` | `skipped_assets` | `skipped_assets` | General supporting assets — not copied during activation. |
@@ -179,6 +195,14 @@ For path errors: all declared paths must be relative, must not contain `..`, and
 
 For conflicts on re-install: if you install a different source with an existing kit id, the command fails unless you pass `--update`. Use `--force` to re-copy an existing same-source install after validation.
 
+For cross-kit dependency errors:
+
+- `kit.json: dependencies[N].kit_id must be a kebab-case kit id` — the entry's `kit_id` is missing or not lowercase kebab-case. Fix the id.
+- `kit.json: dependencies[N].kit_id must not reference the declaring kit itself` — remove the self-referential entry; a kit cannot depend on itself.
+- `kit.json: dependencies[N].kit_id duplicates '<id>'` — collapse the duplicate declaration to a single entry.
+- `warning: kit '<id>' declares a dependency on '<dep>' ... which is not installed` (at install) — advisory only; install the depended-on kit with `flow-agents kit install <source>` before activating, or activation will fail.
+- `<id>: declares a dependency on kit '<dep>' ... which is not installed or activated` (at activate, non-zero exit) — install the missing kit and re-activate, or remove the dependency declaration if it is no longer needed.
+
 See the [Flow Kit Repository Contract](flow-kit-repository-contract.md) for the full validation rules, registry schema, activation diagnostics, and the install/update/force semantics.
 
 ## Layering: container vs. agent extension
@@ -212,6 +236,41 @@ The **agent extension** is owned by Flow Agents. It defines the optional asset c
 
 Each extension field is an optional array of entries with `id`, `path`, and optional `description`. Extension fields are validated by Flow Agents using the same path rules as the container layer (relative, no `..`, must exist). Unknown extension entries are recorded as `skipped_assets` during activation rather than treated as errors.
 
+### Cross-kit dependencies
+
+A kit may declare that it depends on **another kit** whose skills it invokes at runtime. This is a Flow Agents extension-layer concern (a skill in one kit calling a skill in another), not part of the Flow-owned container contract — see [ADR 0019](adr/0019-kit-dependency-ownership.md) for the ownership rationale (grounded in the container schema's `additionalProperties: true` and ADR 0008's Dividing Test). It is **not** a package manager: it declares and validates *presence*, it does not fetch kits or resolve versions.
+
+Shape:
+
+```json
+{
+  "schema_version": "1.0",
+  "id": "builder",
+  "name": "Builder Kit",
+  "flows": [ /* ... */ ],
+  "dependencies": [
+    {
+      "kit_id": "knowledge",
+      "reason": "learning-review invokes knowledge-capture for durable knowledge storage"
+    }
+  ],
+  "skills": [ /* ... */ ]
+}
+```
+
+| Field | Rule |
+|---|---|
+| `kit_id` | Required. Kebab-case kit id (`^[a-z][a-z0-9-]*$`) of the depended-on kit. Must not reference the declaring kit itself, and must not be duplicated across entries. |
+| `reason` | Optional string explaining why the dependency exists (which skill invokes which). |
+
+Where it is checked:
+
+- **Shape** — at `flow-agents kit install`, `inspect`, and `validate` time. A malformed entry (bad `kit_id`, self-reference, duplicate) is a **hard error**.
+- **Presence at install** — `flow-agents kit install` prints a **non-blocking warning** when a declared dependency is not present in the destination's **local** registry, then exits 0. This check sees only the local installed-kits registry, not the built-in Kit Catalog (an accepted v1 limitation).
+- **Presence at activation** — `flow-agents kit activate` is a **hard error** (non-zero exit) when a declared `kit_id` is not present among the union of built-in catalog kits and locally-installed kits.
+
+`dependencies` is metadata, not evaluable-gate content, so it does **not** affect K0/K1/K2 conformance scoring (see the K-levels section below).
+
 ### When a kit "is" a Flow Agents Kit
 
 A kit is a **Flow Agents Kit** when it satisfies both layers:

package/docs/knowledge-kit.md

@@ -43,7 +43,11 @@ The vector detector is fail-closed: infrastructure failures throw `EMBED_FAILURE
 ## Quick reference
 
 ```bash
-# Install the kit into a workspace
+# Install the kit into the default Codex/global kit destination:
+# CODEX_HOME, or ~/.codex when CODEX_HOME is unset
+npx @kontourai/flow-agents kit install kits/knowledge
+
+# Override the destination for a workspace, isolated home, or test
 npx @kontourai/flow-agents kit install kits/knowledge --dest /path/to/workspace
 
 # Run the contract suite against the default adapter