@kontourai/flow-agents 2.3.0 → 3.0.0

package/.github/CODEOWNERS

@@ -13,6 +13,14 @@
 /evals/ci/                      @briananderson1222
 /scripts/ci/                    @briananderson1222
 
+# delivery/DECLARED (ADR 0022 §2) is the no-agent-delivery exemption marker
+# trust-reconcile.js reads to skip Step 2 when no bundle is delivered — a
+# self-asserted governance artifact naming approved_by, so it gets the same
+# owner-review protection as the other verify-config/anchor paths above. This
+# closes #301's file-level half; branch-protection enforcement of CODEOWNERS
+# review itself remains #225 (server-side, not code).
+/delivery/DECLARED               @briananderson1222
+
 # The verification config the CI anchor depends on — an agent must not redefine
 # trust-reconcile-verify to a fake/laundered command or rewire the lane runner
 # without owner review (convergence red-team finding).
@@ -22,6 +30,7 @@
 # The anti-gaming gate + its enforcement hooks
 /scripts/hooks/stop-goal-fit.js     @briananderson1222
 /scripts/hooks/config-protection.js @briananderson1222
+/scripts/hooks/lib/config-protection-remedies.js @briananderson1222
 /scripts/hooks/evidence-capture.js  @briananderson1222
 
 # FlowDefinition resolution + the trust producer/checkpoint/signing the gate depends on
@@ -29,3 +38,10 @@
 /src/cli/workflow-sidecar.ts    @briananderson1222
 # Modules decomposed out of workflow-sidecar.ts (ops#22) keep the same ownership.
 /src/cli/sidecar-*.ts           @briananderson1222
+
+# Kit FlowDefinitions — the enforcer's expects[] taxonomy (ADR 0016 Abstraction A) comes
+# from these files. Narrowing a gate's expects[] locally is a real self-tamper vector
+# that Layer 2 (CI trust-reconcile) does not catch for non-command-shaped claims. Per
+# ADR 0018 Decision #2, route new kill-switch vectors to Layer 4 (this file), not a new
+# config-protection.js matcher.
+/kits/*/flows/*.flow.json      @briananderson1222

package/.github/workflows/ci.yml

@@ -64,6 +64,10 @@ jobs:
         continue-on-error: true
         run: bash evals/ci/run-baseline.sh --check content-boundary
 
+      - name: Decision registry
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check decision-registry
+
       - name: Source tree validation
         continue-on-error: true
         run: bash evals/ci/run-baseline.sh --check source-tree-validation
@@ -137,6 +141,26 @@ jobs:
         continue-on-error: true
         run: bash evals/ci/run-baseline.sh --check workflow-sidecar-writer-integration
 
+      - name: Sidecar field preservation integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check sidecar-field-preservation-integration
+
+      - name: Actor identity resolver integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check actor-identity-resolver-integration
+
+      - name: Assignment provider local-file integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check assignment-provider-local-file-integration
+
+      - name: Assignment provider github integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check assignment-provider-github-integration
+
+      - name: Pull work assignment join integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check pull-work-assignment-join-integration
+
       - name: Finalize CI evidence
         if: always()
         run: bash evals/ci/run-baseline.sh --finalize
@@ -246,6 +270,10 @@ jobs:
         continue-on-error: true
         run: bash evals/ci/run-baseline.sh --check telemetry-contract-integration
 
+      - name: Liveness heartbeat integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check liveness-heartbeat-integration
+
       - name: Telemetry doctor integration
         continue-on-error: true
         run: bash evals/ci/run-baseline.sh --check telemetry-doctor-integration
@@ -262,6 +290,22 @@ jobs:
         continue-on-error: true
         run: bash evals/ci/run-baseline.sh --check pull-work-provider-integration
 
+      - name: Pull work liveness preflight integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check pull-work-liveness-preflight-integration
+
+      - name: Liveness verdict integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check liveness-verdict-integration
+
+      - name: Liveness conflict injection integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check liveness-conflict-injection-integration
+
+      - name: Veritas governance kit integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check veritas-governance-kit-integration
+
       # The anti-gaming + trust regression suite runs in this REQUIRED lane so that
       # weakening the gate / CI anchor / their protections (or removing a regression
       # test) is caught and cannot merge. Convergence red-team (Round 5/7) closure.

package/.github/workflows/trust-reconcile.yml

@@ -27,12 +27,41 @@
 # The agent cannot self-declare success here: it cannot modify the CI environment,
 # pre-disable this job, or post-forge results after the check runs.
 #
-# THIS JOB IS INTENDED TO BE A REQUIRED STATUS CHECK (branch protection).
-# Enabling it as required is a server-side GitHub branch-protection configuration
-# step — it is not wired here by code. Once required, no PR can merge past it.
+# THIS JOB IS ALREADY A REQUIRED, ADMIN-ENFORCED STATUS CHECK on main (verified via
+# `gh api repos/kontourai/flow-agents/branches/main/protection`: "Trust Reconcile" is in
+# required_status_checks.contexts, enforce_admins.enabled: true). No PR — including from
+# admins — can merge past a failing run. Disabling/relaxing this requires a server-side
+# branch-protection change (GitHub UI/API), not a code change in this repo.
 #
 # Additive — NOT a gate-hook change. Does not modify scripts/hooks/*, kits/knowledge,
 # or continue-work. Mirrors the structure of .github/workflows/ci.yml.
+#
+# CI-context contract for the bundle-ownership staleness check (ADR 0022 addendum, part
+# 2; scripts/ci/trust-reconcile.js bundleAttestsThisChange()): an auto-discovered bundle
+# is treated as owned only if its checkpoint's commit_sha is a git-ancestor of (or equal
+# to) this change's own commit sha, checked via `git merge-base --is-ancestor`. That
+# check requires TWO things this workflow provides deliberately, not by accident:
+#   1. Checkout step below uses `fetch-depth: 0` (full history) — the default
+#      fetch-depth: 1 (shallow clone) lacks the parent commit objects merge-base needs;
+#      an ancestor check against a shallow clone exits 128 (unresolvable), which
+#      correctly fails CLOSED (treated as stale) per trust-reconcile.js's own
+#      fail-closed-on-ambiguity contract, but would falsely stale EVERY legitimate
+#      fresh bundle on this required check without full history.
+#   2. Trust reconcile step below sets TRUST_RECONCILE_SHA to the PR's own HEAD commit
+#      (github.event.pull_request.head.sha), not github.sha — on a pull_request trigger,
+#      github.sha is GitHub's synthetic merge commit (refs/pull/N/merge), which is NOT
+#      the commit a locally-run seal-checkpoint ever stamps as commit_sha (checkpoints
+#      are always sealed against a real branch commit). Falling back to github.sha only
+#      applies on push/workflow_dispatch, where it IS the real commit. The checkout ref
+#      itself is unchanged — Step 1 (fresh verify) still runs against the same tree it
+#      always has; only the identity used for the OWNERSHIP COMPARISON changes.
+#   3. Trust reconcile step below also sets TRUST_RECONCILE_EVENT to github.event_name so
+#      trust-reconcile.js can event-scope bundle-required enforcement (ADR 0022 addendum,
+#      part 4): a push run on `main` (post-merge, after a squash-merge whose commit has no
+#      git ancestry back to the feature-branch commit a checkpoint was sealed against) is
+#      a loud no-op on Step 2 instead of a false failure — gating already happened on the
+#      PR run. This does NOT weaken PR-time gating: on pull_request, enforcement is
+#      unchanged.
 
 name: Trust Reconcile
 
@@ -63,6 +92,13 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          # Full history (not the default shallow fetch-depth: 1): the bundle-ownership
+          # staleness check (ADR 0022 addendum, part 2) resolves `git merge-base
+          # --is-ancestor` against the checked-out repo, which needs parent commit
+          # objects a shallow clone does not have. See the CI-context contract note
+          # above this job.
+          fetch-depth: 0
 
       - name: Set up Node.js
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
@@ -80,6 +116,23 @@ jobs:
       - name: Trust reconcile
         id: trust-reconcile
         run: node scripts/ci/trust-reconcile.js
+        env:
+          # The change identity the bundle-ownership staleness check compares the
+          # discovered checkpoint's commit_sha against (ADR 0022 addendum, part 2). On a
+          # pull_request trigger, github.sha is GitHub's synthetic merge commit, not a
+          # commit any real seal-checkpoint run ever stamps — so this MUST be the PR's
+          # own head sha. On push/workflow_dispatch there is no pull_request context, and
+          # github.sha already is the real commit, so the fallback is exact, not a guess.
+          # This does NOT change what gets checked out/verified (Step 1 fresh verify is
+          # untouched) — only the sha used for the Step-2-ownership comparison.
+          TRUST_RECONCILE_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
+          # Event-scoped enforcement (ADR 0022 addendum, part 4): lets trust-reconcile.js
+          # tell a gating pull_request run apart from a post-merge push run on `main` — a
+          # push run's bundle is expected to be absent/stale (squash-merge commits have no
+          # ancestry back to the feature-branch sha a checkpoint was sealed against) and
+          # must be a no-op, not a failure. Unset/unrecognized values fail toward the
+          # STRICTER (pull_request-shaped) enforcement — see resolveEnforcementEvent().
+          TRUST_RECONCILE_EVENT: ${{ github.event_name }}
         # Canonical verify: auto-discovered from package.json scripts["trust-reconcile-verify"]
         #   = npm run build && npm run eval:static
 #   (integration + the anti-gaming regression suite run in ci.yml's required
@@ -88,7 +141,12 @@ jobs:
         # compile-only check. Override via TRUST_RECONCILE_COMMANDS or --commands if needed.
         # Bundle auto-discovery: if delivery/trust.bundle or delivery/trust.checkpoint.json
         # exists in the checkout, CI reconciles per-command claimed passes against fresh
-        # results automatically. When absent, only the fresh verify is enforced (fail-open).
+        # results automatically. When absent, a bundle is REQUIRED by default (ADR 0022 §1):
+        # the job fails closed unless a well-formed, in-scope delivery/DECLARED
+        # no-agent-delivery marker is present, which exempts Step 2 (reconcile) only —
+        # Step 1 (fresh verify) still always runs. An auto-discovered bundle/checkpoint
+        # that does not attest THIS change (see the CI-context contract note above this
+        # job) is treated the same as absent (ADR 0022 addendum, part 2).
         # Phase 2: on success, writes ci-trust-reconcile-results.json to RUNNER_TEMP
         # for mint-attestation.js to consume.
 

package/AGENTS.md

@@ -7,7 +7,7 @@ This bundle was generated from the canonical source in this repo. Treat the repo
 - **Commit messages drive releases.** Releases are automated with release-please: `feat:` bumps minor, `fix:` bumps patch, `feat!:`/`BREAKING CHANGE` bumps major; `docs:`/`chore:`/`test:`/`refactor:` don't bump. Commits without a conventional prefix are invisible to version inference — use one. Details: CONTRIBUTING.md ("Releases").
 - **Never hand-edit release PRs** (`release-please--branches--*`); they are regenerated on every push to main.
 - **Evidence hygiene:** issue/PR permalinks must pin a real commit SHA (`git rev-parse`, never typed by hand); claims about behavior need command/test evidence.
-- `.flow-agents/` runtime artifacts stay untracked; durable records belong in docs/, issues, or tracked source.
+- `.kontourai/flow-agents/` runtime artifacts stay untracked; durable records belong in docs/, issues, `.flow-agents/` config/state when explicitly owned by Flow Agents, or tracked source.
 
 ### Operating discipline (working agreements)
 
@@ -24,7 +24,7 @@ Confirmed agreements for developing this repo — the *kit-discipline* bucket of
 ## Shared Conventions
 
 - `skills/`, `context/`, `powers/`, `prompts/`, `scripts/`, and `evals/` were copied from the canonical source.
-- Cross-session task artifacts should live under `.flow-agents`.
+- Cross-session task artifacts should live under `.kontourai/flow-agents`.
 - Kiro-only hook wiring was stripped from exported non-Kiro agents to keep the package portable.
 - **Gate awareness:** `context/gate-awareness.md` — the three active gates (goal-fit/Stop, evidence-capture, reground), why a block is the system working, and how to diagnose a suspected missed block.
 
@@ -39,8 +39,8 @@ Confirmed agreements for developing this repo — the *kit-discipline* bucket of
 - `tool-explore-patterns` — Delegate to me for Pattern detection - identifies architectural patterns, frameworks, and coding conventions
 - `tool-explore-structure` — Delegate to me to scout out the project structure - maps directory layout and identifies key folders in a codebase
 - `tool-explore-tests` — Delegate to me to find and understand testing strategies - locates test files and understands testing strategy
-- `tool-planner` — Delegate to me for codebase analysis and execution planning. Explores code, identifies patterns and dependencies, and writes plan/sidecar artifacts under .flow-agents. No production file modifications.
+- `tool-planner` — Delegate to me for codebase analysis and execution planning. Explores code, identifies patterns and dependencies, and writes plan/sidecar artifacts under .kontourai/flow-agents. No production file modifications.
 - `tool-playwright` — Delegate to me for browser automation, testing, and debugging - loading real pages, testing navigation, checking accessibility via structured snapshots, evaluating scripts, and visual verification. Anything that would otherwise require a browser. Do NOT use for general web search or fetching content
 - `tool-security-reviewer` — Delegate to me for security analysis. Checks OWASP Top 10, secrets detection, input validation, injection vulnerabilities, auth/authz, and rate limiting. Read-only analysis with shell for scanning tools.
-- `tool-verifier` — Delegate to me for implementation verification. Read-only + shell for source code; writes review/evidence artifacts under .flow-agents. Verifies acceptance criteria and produces PASS/FAIL/NOT_VERIFIED verdicts with evidence. No production file modifications.
+- `tool-verifier` — Delegate to me for implementation verification. Read-only + shell for source code; writes review/evidence artifacts under .kontourai/flow-agents. Verifies acceptance criteria and produces PASS/FAIL/NOT_VERIFIED verdicts with evidence. No production file modifications.
 - `tool-worker` — Delegate to me for writing and developing source code for a project. Works best when a detailed plan can be provided. NO access to web tools. Can be used in parallel for any coding tasks that require trusted access to the write and shell tools. WARNING: May spawn a `git worktree`

package/CHANGELOG.md

@@ -1,5 +1,67 @@
 # Changelog
 
+## [3.0.0](https://github.com/kontourai/flow-agents/compare/v2.4.0...v3.0.0) (2026-07-04)
+
+
+### ⚠ BREAKING CHANGES
+
+* **trust:** require origin/check_kind stamps — remove pre-supersession read fallback ([#355](https://github.com/kontourai/flow-agents/issues/355))
+
+### Features
+
+* **routing:** model-routing policy as datum roles — orchestrator resolves at delegation ([#365](https://github.com/kontourai/flow-agents/issues/365)) ([7acf663](https://github.com/kontourai/flow-agents/commit/7acf6635125623505097eb0f7d2b0da7026c1b00))
+* **trust-anchor:** fail-closed delivery reconciliation with governed exemptions (ADR 0022 §1) ([#358](https://github.com/kontourai/flow-agents/issues/358)) ([0631050](https://github.com/kontourai/flow-agents/commit/0631050c7d88f3dd38d7c90ee1af5adf63410334))
+
+
+### Fixes
+
+* **trust:** critique supersession + lossless check/critique round-trip (closes [#267](https://github.com/kontourai/flow-agents/issues/267), [#268](https://github.com/kontourai/flow-agents/issues/268), [#282](https://github.com/kontourai/flow-agents/issues/282)) ([#344](https://github.com/kontourai/flow-agents/issues/344)) ([c2c3fd5](https://github.com/kontourai/flow-agents/commit/c2c3fd5d322d2537847d67a6fefc6daae6893070))
+* **trust:** require origin/check_kind stamps — remove pre-supersession read fallback ([#355](https://github.com/kontourai/flow-agents/issues/355)) ([ab27f71](https://github.com/kontourai/flow-agents/commit/ab27f71ac1ee652b7125ce01336895d34162472b))
+
+
+### Documentation
+
+* **contracts:** standing owner directives — durable home for ratified policy ([#351](https://github.com/kontourai/flow-agents/issues/351)) ([e335d54](https://github.com/kontourai/flow-agents/commit/e335d540378ba7eaae5bb7162427d8db16f58e4b))
+
+## [2.4.0](https://github.com/kontourai/flow-agents/compare/v2.3.0...v2.4.0) (2026-07-03)
+
+
+### Features
+
+* **decisions:** topic-keyed living decision registry contract (Closes [#310](https://github.com/kontourai/flow-agents/issues/310)) ([#316](https://github.com/kontourai/flow-agents/issues/316)) ([0bd4e0b](https://github.com/kontourai/flow-agents/commit/0bd4e0ba593480c1e11988d2f9257082a3f06b4a))
+* **gates:** regression-lock the FlowDefinition-driven stop gate + gate-named block messages (ADR 0016 Abstraction A closeout) ([#265](https://github.com/kontourai/flow-agents/issues/265)) ([0fd0c0e](https://github.com/kontourai/flow-agents/commit/0fd0c0e56c3a8e007f116c77937f9fc61d9a6be7))
+* **kits:** cross-kit dependencies, skill-collision fixes, sidecar governance ([#264](https://github.com/kontourai/flow-agents/issues/264)) ([b2a4cc8](https://github.com/kontourai/flow-agents/commit/b2a4cc8abc1d7a822274fae90ee5e5e9e6dc7de5))
+* **kits:** veritas-governance kit — readiness→trust-bundle adapter with settled gate semantics ([#269](https://github.com/kontourai/flow-agents/issues/269)) ([7a08396](https://github.com/kontourai/flow-agents/commit/7a083966db47672ea552f13264ea3111e08fa06b))
+* **liveness:** default-on lifecycle + tool-activity heartbeats ([#288](https://github.com/kontourai/flow-agents/issues/288)) ([#306](https://github.com/kontourai/flow-agents/issues/306)) ([3134614](https://github.com/kontourai/flow-agents/commit/31346147311e829352b2219ce1a91b6babc5ec27))
+* **liveness:** runtime-agnostic actor identity; retire the "local" default ([#287](https://github.com/kontourai/flow-agents/issues/287)) ([#296](https://github.com/kontourai/flow-agents/issues/296)) ([204a4c6](https://github.com/kontourai/flow-agents/commit/204a4c68643587727b7d0c22390de4375a24ea6e))
+* promote-then-archive gate — durable-residue extraction is the archival act (Closes [#312](https://github.com/kontourai/flow-agents/issues/312)) ([#319](https://github.com/kontourai/flow-agents/issues/319)) ([490542c](https://github.com/kontourai/flow-agents/commit/490542caf461ab4e5bff1542f3e56f4fdc9fd234))
+* **pull-work:** liveness selection preflight — exclude held, claim on selection ([#329](https://github.com/kontourai/flow-agents/issues/329)) ([8c76568](https://github.com/kontourai/flow-agents/commit/8c76568407d37b145b5d3ea420c8b9746d2b5ac5))
+* **trust-anchor:** manifest-based reconcile, claim classification, loud attestations (WS8) ([55b66db](https://github.com/kontourai/flow-agents/commit/55b66dbf8c3c30f828439f1983669722981bcbae))
+* **trust-bundle:** migrate to @kontourai/surface 2.0.0 (Claim.facet rename) ([#277](https://github.com/kontourai/flow-agents/issues/277)) ([573b45e](https://github.com/kontourai/flow-agents/commit/573b45ec28453392bc11286ef7378b6627c790e0))
+* **veritas-governance:** migrate adapter to facet + schemaVersion 5 ([#285](https://github.com/kontourai/flow-agents/issues/285)) ([1948639](https://github.com/kontourai/flow-agents/commit/19486395e1c57231b9b8c9ec805d2fe2f720426e)), closes [#281](https://github.com/kontourai/flow-agents/issues/281)
+* **workflow:** branch as first-class routing state with agent/<actor>/<slug> convention ([#308](https://github.com/kontourai/flow-agents/issues/308)) ([739575c](https://github.com/kontourai/flow-agents/commit/739575c8f5f43a1f056982201cddaae699fe6409))
+
+
+### Fixes
+
+* **bundles:** resolve Codex hook script with HOME fallback; fail open with diagnostic ([e9c5993](https://github.com/kontourai/flow-agents/commit/e9c5993d84483c114641090026afaedc70afdcdb))
+* **evals:** heal integration lanes after runtime-path split ([20cdb36](https://github.com/kontourai/flow-agents/commit/20cdb36ac4b5704599faa524a5189d288b6d8a40))
+* **evals:** register WS8 fixtures with the retirement audit ([95f6baf](https://github.com/kontourai/flow-agents/commit/95f6bafe37a4eb492d6ccb70892f0038e35a3850))
+* **flow-agents:** resolve claude-code --global hook paths absolutely ([9148033](https://github.com/kontourai/flow-agents/commit/9148033f7c1e02512550f342d1bf3ac5e80fdf9d))
+* **sidecar:** preserve branch and created_at across init-plan; add field-preservation invariant sweep ([#315](https://github.com/kontourai/flow-agents/issues/315)) ([cae9c38](https://github.com/kontourai/flow-agents/commit/cae9c38d2d311e6205f665cc4943808748effaec))
+
+
+### Documentation
+
+* **adr:** ADR 0021 — assignment leases and stale-claim takeover ([#286](https://github.com/kontourai/flow-agents/issues/286)) ([df345dd](https://github.com/kontourai/flow-agents/commit/df345dd8a1dc067fff2d03334041b373057eb79c))
+* **adr:** ADR 0022 — fail-closed delivery reconciliation with governed exemptions ([#299](https://github.com/kontourai/flow-agents/issues/299)) ([046005a](https://github.com/kontourai/flow-agents/commit/046005af025663de005684c92fd825eab73fb8b1))
+* **learnings:** 2026-07 improvement-program learning review ([#284](https://github.com/kontourai/flow-agents/issues/284)) ([514b6ad](https://github.com/kontourai/flow-agents/commit/514b6ad346d0e42939b4c03bdee976fe0c166bf3))
+
+
+### Refactoring
+
+* **flow-agents:** centralize Codex home default helper ([dc9995c](https://github.com/kontourai/flow-agents/commit/dc9995cdc43a456ab6248307ef6d5ace59559313))
+
 ## [2.3.0](https://github.com/kontourai/flow-agents/compare/v2.2.0...v2.3.0) (2026-07-01)
 
 

package/CONTEXT.md

@@ -56,6 +56,16 @@ A configured implementation of a capability, such as GitHub for backlog, Obsidia
 
 The declared capabilities, defaults, conventions, and limits of a provider type. Provider contracts make integrations predictable and testable without requiring the live provider.
 
+### Knowledge Graph
+
+The Knowledge Kit's storage-independent model: typed nodes (recommended core: note, decision, issue, session, person — extensible) and typed edges (supersedes, merged-into, blocks, evidence-of, mentions, relates — a closed vocabulary), each carrying provenance so every assertion is traceable to the store it came from. Storage and synchronisation are provider concerns; the same ingest, link, and health verbs run over every provider.
+_Avoid_: Graph database as the generic term (the model is provider-independent; a graph-database provider is a separate spike)
+
+### Knowledge Store Provider
+
+A configured implementation of the knowledge-store capability behind the Knowledge Graph model. Providers expose a read interface (nodes, edges, query-by-type) and a proposals-only write interface (proposeWrite returns a proposal, never mutating a human-curated store). The reference providers are markdown-vault (the Obsidian-shaped vault), git-repo (decision registry, CONTEXT.md vocabulary, learnings), and work-item (GitHub issues as a source/sink adapter). See context/contracts/knowledge-store-contract.md.
+_Avoid_: Knowledge adapter when contrasting the provider interface with a single store adapter
+
 ### Kontour Resource Contract
 
 A versioned Kontour record shape for durable machine-readable configuration, scope, run state, evidence, provider output, and cross-product interchange. Kontour Resource Contracts are the default for new pre-public durable contracts unless a product records why a native shape is clearer.
@@ -256,6 +266,25 @@ _Avoid_: Retrospective as the generic term
 
 The ability to inspect what the agent was asked to do, which operating path it followed, what evidence was collected, which gates passed or failed, and why the next action is trustworthy or blocked.
 
+### Decision Records
+
+Topic-keyed living decision records at `docs/decisions/<topic-slug>.md`, one file per decision subject, that hold the current answer to a settled question plus lean rationale. Supersession is an edit to the file; derivation context is linked via evidence refs, never inlined. Slugs are nouns from this glossary. Numbered ADRs under `docs/adr/` are frozen history and are never written for new decisions.
+_Avoid_: Numbered ADR as the format for new decisions
+
+### Decision Registry
+
+The system of Decision Records plus the generated index at [docs/decisions/index.md](docs/decisions/index.md) (slug + one-line summary). The contract is [context/contracts/decision-registry-contract.md](context/contracts/decision-registry-contract.md); the frontmatter schema is `schemas/decision-record.schema.json`; `npm run check:decisions` validates it. Consult the index at write time to decide revise-vs-create.
+
+### Standing Directives
+
+A short, numbered, quotable list of ratified owner directives, each with a one-line rationale and date, kept at [context/contracts/standing-directives.md](context/contracts/standing-directives.md) and pointed to from the header of every other contract file in `context/contracts/`. Standing Directives override default engineering conservatism (such as keeping a compatibility path "just in case") wherever they apply; they exist so a ratified correction has a durable home instead of living only in the ephemeral context of the orchestrator session that ratified it.
+_Avoid_: Operating discipline as the generic term for owner-ratified policy, restating a directive from memory instead of citing the file
+
+### Promotion Gate
+
+The gated sequence — final acceptance -> promote -> archive — that makes durable-residue extraction the archival act: a delivered session's decisions, vocabulary, learnings, and doc updates must be promoted into durable living docs before the session is archived. The `promote` step records what was promoted where and writes a session-local **promotion claim** into the session `trust.bundle` (evidence refs = the durable doc paths written, or an explicit `--none` no-residue reason). `workflow-artifact-cleanup-audit` classifies a delivered/accepted session with no promotion claim as a cleanup candidate (archive blocked), not terminal. See [docs/decisions/promotion-gate.md](docs/decisions/promotion-gate.md) and [docs/workflow-artifact-lifecycle.md](docs/workflow-artifact-lifecycle.md).
+_Avoid_: Docs-promotion as a parallel checklist chore
+
 ### Governance Adapter
 
 An optional integration that supplies policy, proof, or trust evidence without making Flow Agents own the external tool's rule semantics. Veritas is the first known governance adapter candidate.
@@ -298,3 +327,9 @@ The Console overview for global setup, registered projects, cross-project usage,
 ### Control API
 
 The shared tool layer used by the Console, CLI, AI agents, and automation. The Control API owns operations such as reading effective settings, explaining provider resolution, testing provider health, previewing config changes, writing config, inspecting workflow state, and reporting usage or eval outcomes.
+
+### Model Routing
+
+The policy that maps a delegate role name (such as `delegate-mechanical`, `delegate-implementation`, `delegate-design`, `orchestrator`, `extraction-default`) to a specific `model@provider` ref. Model Routing is data, not code: it lives in `.datum/config.json` (read by the `@kontourai/datum` registry, schema `datum.schema.json`) and never in generated files or per-agent frontmatter. The orchestrator resolves the role at delegation time (`datum resolve <role> --json`) and passes the resolved model explicitly when spawning each delegate. See [context/contracts/execution-contract.md](context/contracts/execution-contract.md) § Delegation: Model Routing and [docs/decisions/model-routing.md](docs/decisions/model-routing.md).
+_Avoid_: Generated per-agent model frontmatter, environment-variable-only model selection
+

package/README.md

@@ -25,7 +25,7 @@ Flow Agents addresses this with a process-discipline layer that sits between the
 
 - **One workflow across runtimes** — the same `idea → backlog → plan → build → review → verify → evidence → release → learning` path installs into Claude Code, Codex, Kiro, opencode, and pi without rewriting it per tool.
 - **Workflow skills** — `idea-to-backlog`, `pull-work`, `plan-work`, `execute-plan`, `review-work`, `verify-work`, `evidence-gate`, `release-readiness`, `learning-review`, and orchestrators like `deliver` and `fix-bug` that chain them.
-- **Durable workflow state** — schema-validated sidecars under `.flow-agents/` record acceptance criteria, evidence, critique, handoff, and learning, so any session can resume from recorded state instead of chat memory.
+- **Resumable workflow state** — schema-validated sidecars under `.kontourai/flow-agents/` record acceptance criteria, evidence, critique, handoff, and learning, so any session can resume from recorded state instead of chat memory.
 - **Four canonical policies** — workflow steering (phase reminders at each turn), quality gate (per-file checks after edits), stop-goal-fit (evidence check before the agent stops), and config protection (veto writes to linter/formatter configs). Each policy class has a canonical script under `scripts/hooks/` and compiles to the host's native hook format.
 - **Evidence over confidence** — important work ends with tests, browser checks, CI results, review findings, governance reports, or an explicit `NOT_VERIFIED` gap. Optional [Veritas](docs/veritas-integration.md) integration attaches repo-governance evidence without making it mandatory.
 - **Verifiable, un-gameable "done"** — the agent can't mark work complete that isn't: the gate re-derives the verdict from independent evidence, an external CI anchor re-runs the verification fresh and fails the merge on any divergence, and CI mints a Sigstore-signed record of what shipped. See [Verifiable Trust — why "done" actually means done](docs/verifiable-trust.md).
@@ -88,6 +88,8 @@ npx @kontourai/flow-agents init --runtime opencode --dest /path/to/workspace --y
 npx @kontourai/flow-agents init --runtime pi --dest /path/to/workspace --yes
 ```
 
+For Codex global installs, omit `--dest` and use `--global`: Flow Agents installs into `CODEX_HOME` when it is set, otherwise `~/.codex`. Pass `--dest` only when you intentionally want an isolated or test-specific Codex home.
+
 Working from a checkout (for contributors): `npm install && npm run build`, then `node build/src/cli.js init --dest /path/to/workspace`.
 
 The installer copies the bundled agents, skills, context, scripts, evals, Flow Kit assets, and the Flow Agents-owned `console.telemetry.json` descriptor into the target workspace. Telemetry writes to local files by default; optional sinks mirror it to a local, hosted, or self-hosted Kontour Console (`--telemetry-sink local-kontour-console | kontour-hosted-console | user-hosted-console --console-url …`).
@@ -121,7 +123,7 @@ Use deliver for the issue you just filed. Pull it, probe the design, plan it,
 implement it, verify it, and stop if any evidence is missing.
 ```
 
-Each step has an evidence gate. The agent either presents the expected evidence and advances, or blocks and explains what is missing — it does not produce a confident summary and proceed on partial work. Session state is written to `.flow-agents/<slug>/` and survives context loss or compaction.
+Each step has an evidence gate. The agent either presents the expected evidence and advances, or blocks and explains what is missing — it does not produce a confident summary and proceed on partial work. Non-durable session state is written to `.kontourai/flow-agents/<slug>/` and survives context loss or compaction.
 
 For a full walkthrough — what each gate checks, what you observe, and how to invoke individual skills — read the [Builder Kit Quick Start](docs/getting-started.md).
 
@@ -148,6 +150,10 @@ The Knowledge Kit is also LIVE-proven: the default adapter passes the parameteri
 Install a local kit:
 
 ```bash
+# default Codex/global kit destination: CODEX_HOME, or ~/.codex when CODEX_HOME is unset
+npx @kontourai/flow-agents kit install path/to/my-kit
+
+# explicit override for workspace or test installs
 npx @kontourai/flow-agents kit install path/to/my-kit --dest /path/to/workspace
 ```
 
@@ -209,7 +215,7 @@ See [Repository Structure](docs/repository-structure.md) for the canonical map.
 - `agents/`, `agent-cards/`, `skills/`, `context/`, `powers/`, and `prompts/` are canonical bundle source.
 - `src/` and `scripts/` are product, tooling, validation, installer, hook, telemetry, and compatibility source; see [scripts/README.md](scripts/README.md).
 - `kits/`, `schemas/`, `packaging/`, `evals/`, `docs/`, and `integrations/` hold Flow Kit assets, contracts, package metadata, evals, durable docs, and optional integrations.
-- `dist/`, `build/`, and `_site/` are generated output. Local `.flow-agents/`, `.codex/`, `.claude/`, telemetry, promptfoo, Veritas, and cache directories are runtime state and stay ignored; durable outcomes belong in docs, source, schemas, or provider records.
+- `dist/`, `build/`, and `_site/` are generated output. Local `.kontourai/`, `.flow-agents/`, `.codex/`, `.claude/`, telemetry, promptfoo, Veritas, and cache directories stay ignored; durable outcomes belong in docs, source, schemas, or provider records.
 
 ## Documentation
 

package/agents/dev.json

@@ -122,6 +122,6 @@
   "welcomeMessage": "Flow Agents dev mode is ready for engineering work.",
   "name": "dev",
   "description": "Development agent for coding tasks. Writes, modifies, and validates code following existing patterns. Delegates to specialists for domain-specific research when available.",
-  "prompt": "You are a Development Agent. You write and modify code, validate it works, and deliver clean results. Delegate to specialist subagents whenever a loaded skill defines them \u2014 never do manually what a skill's subagents can do in parallel.\n\n\u26d4  You own the code \u2014 specialists provide context.\n\n## Flow Kit Boundary\nFlow owns Flow Definition gate semantics, typed `expects`, `kind: \"trust.bundle\"`, trusted producer config, and gate overrides. Flow Agents coordinates Flow Kit installation, runtime adapters, local control, and workflow artifacts. Builder Kit is the first bundled Flow Kit; use Builder Kit, Kit Catalog, Flow Kit, Probe, and `design-probe` vocabulary in guidance and artifacts.\n\n## Hard Route\nIf the user asks to explore a repository, explain what a codebase does, summarize project structure, or otherwise perform repository discovery, you MUST activate the `explore` skill before any file reads, greps, globs, shell exploration, or direct synthesis. This is a hard rule, not a preference.\n\nIf the user asks to build, create, implement, ship, or deliver a tool/app/service/feature, you MUST activate `deliver` first unless they explicitly request TDD, in which case activate `tdd-workflow` instead. Do not let `search-first` override `deliver` for broad build requests.\n\n## Skill Activation (MANDATORY FIRST STEP)\nYou have loaded skills in your context. Your FIRST action on EVERY request MUST be:\n1. Call the thinking tool\n2. State the user's request\n3. Scan ALL loaded skills by name and description \u2014 explicitly list candidates\n4. If a skill matches: state \"Activating skill: [name]\", read its SKILL.md, then delegate to the subagents it specifies immediately. Do NOT verify prerequisites yourself \u2014 the subagent handles the full workflow. Your NEXT tool call after reading the skill MUST be use_subagent \u2014 do not explore, search, or verify first.\n\nCommon skill triggers (activate these, don't handle manually):\n- Codebase exploration, repo overview, \"explore the codebase\", \"tell me what this codebase does\" \u2192 explore (delegate to tool-explore-* and respect current harness subagent limits)\n- Build, create, implement, ship, or deliver a tool/app/service/feature \u2192 deliver (unless the user explicitly requests TDD)\n- Prompt(<name>) syntax \u2192 run-prompt (use introspect to discover prompts, NOT filesystem)\n- Adding a small utility/library without a broader build request \u2192 search-first (research before coding)\n- Dependency/security scanning \u2192 dependency-update \u2192 tool-dependencies-updater\n- Code quality, standards, architecture, or security critique \u2192 review-work \u2192 tool-code-reviewer and conditional tool-security-reviewer\n- Verification/acceptance criteria/evidence \u2192 verify-work \u2192 tool-verifier\n- \"Verify changes work\" / \"check build and UI\" \u2192 feedback-loop\n- Task includes a UI component (login page, dashboard, form) \u2192 activate frontend-design for that portion. If the task ALSO has non-UI work, use deliver for the full task but delegate the UI portion to frontend-design within the plan\n\n5. If NO skill matches: proceed to Phase 0. You MUST execute these in order before writing any code:\n   a. todo_list \u2014 check/load existing work (Phase 0)\n   b. execute_bash with `git status` \u2014 check working tree (Phase 1)\n   c. todo_list \u2014 create a plan for the task (Phase 2)\n\nNEVER skip this step. NEVER call fs_read, code, grep, glob, or execute_bash before completing skill activation check.\n\n## Session File Awareness\nOn session start, check for resumption candidates:\n1. **Session files**: check `.flow-agents/` for existing session files (`deliver`, `fix-bug`, `plan-work` types)\n2. **Boo jobs**: if boo is available, run `boo list --format json` and look for recent jobs with descriptions or names related to the current project that may need follow-up\n\nIf found:\n- Briefly mention what's in flight (name, status, iteration or last run)\n- Ask: resume existing work or start fresh?\n- Session files: read the file, determine current phase, invoke the appropriate primitive skill\n- Boo jobs: use `boo resume <job>` or read the job's artifacts for context\n\n## Plan \u2192 Execute \u2192 Review \u2192 Verify Loop\nThe Builder Kit workflow uses composable primitives: `pull-work`, `design-probe` when assumptions need challenge, `plan-work`, `execute-plan`, `review-work`, and `verify-work`. These can be invoked independently or chained by orchestrator skills (deliver, fix-bug). When the loop runs:\n- plan-work produces a plan artifact that tool-worker agents read directly (no orchestrator interpretation)\n- execute-plan fans out parallel waves and checkpoints progress between them\n- review-work produces critique in `critique.json`: findings route back to execute-plan or user decision\n- verify-work produces evidence in `evidence.json`: PASS \u2192 deliver/evidence-gate, FAIL \u2192 re-plan and loop, NOT_VERIFIED \u2192 ask user\n\n## Specialist Agents\n\nThese agents handle domain-specific tasks. Delegate \u2014 do NOT do their work manually.\n\n| Request | Delegate To | Trigger |\n|---|---|---|\n| Code quality, standards, architecture review | tool-code-reviewer (via review-work) | readability, maintainability, DRY, patterns, architecture fit |\n| Security review | tool-security-reviewer (via review-work) | OWASP, vulnerabilities, secrets, auth/authz |\n| Verification | tool-verifier (via verify-work) | acceptance criteria, build/test/lint/security evidence |\n| Dependency audit | tool-dependencies-updater | outdated packages, CVEs, version checks |\n\nDelegation means use_subagent \u2014 not reading code yourself. If a skill says delegate to X, invoke X. If no session file exists for verify-work, delegate to tool-verifier directly with the user's request. If target code doesn't exist for review, delegate anyway \u2014 let the reviewer agent handle discovery.\n\nDelegation pattern (follow this exactly):\n1. thinking: identify skill + target agent\n2. fs_read: read SKILL.md\n3. use_subagent: invoke the agent specified by the skill\nDo NOT insert exploration steps (grep, glob, fs_read of source code) between reading the skill and delegating.\n\n## Progress Checkpointing\nAfter each significant step (plan produced, wave completed, review done, verification done), update the session file in `.flow-agents/<slug>/` with current status, completed tasks, and next action. The session file is your recovery point \u2014 if context is lost, a new session should be able to read it and know exactly where to pick up.\n\n## Workflow\nWhen no skill matches, follow these phases in order. Do NOT skip phases even for simple tasks.\n\n### Phase 0: CHECK EXISTING WORK\nGoal: Understand what work is already in progress for current directory\n- For any incomplete TODOs, `load` them to review tasks, context, and modified files\n- Check `.flow-agents/` for session files from plan-work, deliver, fix-bug\n- Summarize findings to the user: what's in progress, what's done, what files are being touched\n- If the user's request relates to an existing TODO or session file, ask whether to continue it or start fresh\n- Exit: You know what's in flight and which files may overlap with your task\n\n### Phase 1: ORIENT\nGoal: Understand and explore the codebase and task before touching anything.\n- Run `git status` and `git diff` to check for uncommitted changes \u2014 NEVER overwrite unsaved work\n- Explore relevant code: read existing implementation, conventions, patterns, dependencies, and tests\n- Cross-reference with in-progress TODOs from Phase 0 \u2014 if your task's files overlap with another TODO's `modified_files`, create a git worktree (`git worktree add ../worktree/kiro-<todo-id>-<feature> -b feat/<feature>`) and work there instead\n- If requirements are ambiguous, ask the user before proceeding\n- Exit: You can describe what needs to change and where\n\n### Phase 2: PLAN\nGoal: Define the set of changes needed.\n- Create a TODO list using the todo_list tool \u2014 required for ALL tasks, even single-file changes\n- Identify files to create/modify and the specific changes in each\n- If the task includes visual/UI changes (HTML, CSS, components, pages), include a tool-playwright verification step in the plan. This is MANDATORY \u2014 do not skip visual verification for any visual change\n- Prefer modifying existing code over creating new files\n- Exit: A concrete list of changes, no open questions\n\n### Phase 3: IMPLEMENT\nGoal: Write the code.\n- Follow existing patterns, naming conventions, and project structure\n- Write the minimum code necessary \u2014 no speculative features\n- No fake data, no placeholder stubs, no silent fallbacks. Errors MUST propagate \u2014 never catch and return null, empty arrays, default objects, or fallback values. Use try/catch only to add context before re-throwing.\n- Apply DRY principles \u2014 check if similar logic already exists before writing new code\n- Mark TODO items complete as you finish each change\n- Exit: All planned changes are written\n\n### Phase 4: VALIDATE\nGoal: Prove the code works with evidence. Describing what you did is NOT validation.\n\nClassify every change:\n- **Visual** (UI, CSS, layouts, components) \u2192 delegate to tool-playwright: load the page, take screenshots, verify elements exist and render correctly\n- **Integration** (APIs, CLIs, configs, logic, builds) \u2192 run tests, execute the code, capture actual output\n- **Both** \u2192 run both paths\n\nRules:\n- Evidence is mandatory \u2014 show output, screenshots, or test results. \u201cI made the change\u201d is not evidence.\n- If validation fails, fix and re-validate. Do NOT skip, downgrade to a weaker method, or punt to the user.\n- If a verification method should work but isn't, debug the method itself. Don't fall back to \u201cthe build passes so it's probably fine.\u201d\n- Keep trying until verification passes or the user explicitly says stop (per feedback-loop skill persistence rule).\n- If failures are in areas related to another TODO's in-progress work, note them but still verify YOUR changes.\n- Exit: All changes verified with captured evidence.\n\n### Phase 5: DELIVER\nGoal: Clean state ready for commit.\n- Remove any debug artifacts, temp files, or leftover copies\n- Summarize: what changed, why, and any follow-up items\n- If you deferred any issues due to other in-progress TODOs for the current directory, remind the user and list the follow-up TODO items you added\n- Exit: Working directory is clean except for intentional changes",
+  "prompt": "You are a Development Agent. You write and modify code, validate it works, and deliver clean results. Delegate to specialist subagents whenever a loaded skill defines them \u2014 never do manually what a skill's subagents can do in parallel.\n\n\u26d4  You own the code \u2014 specialists provide context.\n\n## Flow Kit Boundary\nFlow owns Flow Definition gate semantics, typed `expects`, `kind: \"trust.bundle\"`, trusted producer config, and gate overrides. Flow Agents coordinates Flow Kit installation, runtime adapters, local control, and workflow artifacts. Builder Kit is the first bundled Flow Kit; use Builder Kit, Kit Catalog, Flow Kit, Probe, and `design-probe` vocabulary in guidance and artifacts.\n\n## Hard Route\nIf the user asks to explore a repository, explain what a codebase does, summarize project structure, or otherwise perform repository discovery, you MUST activate the `explore` skill before any file reads, greps, globs, shell exploration, or direct synthesis. This is a hard rule, not a preference.\n\nIf the user asks to build, create, implement, ship, or deliver a tool/app/service/feature, you MUST activate `deliver` first unless they explicitly request TDD, in which case activate `tdd-workflow` instead. Do not let `search-first` override `deliver` for broad build requests.\n\n## Skill Activation (MANDATORY FIRST STEP)\nYou have loaded skills in your context. Your FIRST action on EVERY request MUST be:\n1. Call the thinking tool\n2. State the user's request\n3. Scan ALL loaded skills by name and description \u2014 explicitly list candidates\n4. If a skill matches: state \"Activating skill: [name]\", read its SKILL.md, then delegate to the subagents it specifies immediately. Do NOT verify prerequisites yourself \u2014 the subagent handles the full workflow. Your NEXT tool call after reading the skill MUST be use_subagent \u2014 do not explore, search, or verify first.\n\nCommon skill triggers (activate these, don't handle manually):\n- Codebase exploration, repo overview, \"explore the codebase\", \"tell me what this codebase does\" \u2192 explore (delegate to tool-explore-* and respect current harness subagent limits)\n- Build, create, implement, ship, or deliver a tool/app/service/feature \u2192 deliver (unless the user explicitly requests TDD)\n- Prompt(<name>) syntax \u2192 run-prompt (use introspect to discover prompts, NOT filesystem)\n- Adding a small utility/library without a broader build request \u2192 search-first (research before coding)\n- Dependency/security scanning \u2192 dependency-update \u2192 tool-dependencies-updater\n- Code quality, standards, architecture, or security critique \u2192 review-work \u2192 tool-code-reviewer and conditional tool-security-reviewer\n- Verification/acceptance criteria/evidence \u2192 verify-work \u2192 tool-verifier\n- \"Verify changes work\" / \"check build and UI\" \u2192 feedback-loop\n- Task includes a UI component (login page, dashboard, form) \u2192 activate frontend-design for that portion. If the task ALSO has non-UI work, use deliver for the full task but delegate the UI portion to frontend-design within the plan\n\n5. If NO skill matches: proceed to Phase 0. You MUST execute these in order before writing any code:\n   a. todo_list \u2014 check/load existing work (Phase 0)\n   b. execute_bash with `git status` \u2014 check working tree (Phase 1)\n   c. todo_list \u2014 create a plan for the task (Phase 2)\n\nNEVER skip this step. NEVER call fs_read, code, grep, glob, or execute_bash before completing skill activation check.\n\n## Session File Awareness\nOn session start, check for resumption candidates:\n1. **Session files**: check `.kontourai/flow-agents/` for existing session files (`deliver`, `fix-bug`, `plan-work` types)\n2. **Boo jobs**: if boo is available, run `boo list --format json` and look for recent jobs with descriptions or names related to the current project that may need follow-up\n\nIf found:\n- Briefly mention what's in flight (name, status, iteration or last run)\n- Ask: resume existing work or start fresh?\n- Session files: read the file, determine current phase, invoke the appropriate primitive skill\n- Boo jobs: use `boo resume <job>` or read the job's artifacts for context\n\n## Plan \u2192 Execute \u2192 Review \u2192 Verify Loop\nThe Builder Kit workflow uses composable primitives: `pull-work`, `design-probe` when assumptions need challenge, `plan-work`, `execute-plan`, `review-work`, and `verify-work`. These can be invoked independently or chained by orchestrator skills (deliver, fix-bug). When the loop runs:\n- plan-work produces a plan artifact that tool-worker agents read directly (no orchestrator interpretation)\n- execute-plan fans out parallel waves and checkpoints progress between them\n- review-work produces critique in `critique.json`: findings route back to execute-plan or user decision\n- verify-work produces evidence in `evidence.json`: PASS \u2192 deliver/evidence-gate, FAIL \u2192 re-plan and loop, NOT_VERIFIED \u2192 ask user\n\n## Specialist Agents\n\nThese agents handle domain-specific tasks. Delegate \u2014 do NOT do their work manually.\n\n| Request | Delegate To | Trigger |\n|---|---|---|\n| Code quality, standards, architecture review | tool-code-reviewer (via review-work) | readability, maintainability, DRY, patterns, architecture fit |\n| Security review | tool-security-reviewer (via review-work) | OWASP, vulnerabilities, secrets, auth/authz |\n| Verification | tool-verifier (via verify-work) | acceptance criteria, build/test/lint/security evidence |\n| Dependency audit | tool-dependencies-updater | outdated packages, CVEs, version checks |\n\nDelegation means use_subagent \u2014 not reading code yourself. If a skill says delegate to X, invoke X. If no session file exists for verify-work, delegate to tool-verifier directly with the user's request. If target code doesn't exist for review, delegate anyway \u2014 let the reviewer agent handle discovery.\n\nDelegation pattern (follow this exactly):\n1. thinking: identify skill + target agent\n2. fs_read: read SKILL.md\n3. use_subagent: invoke the agent specified by the skill\nDo NOT insert exploration steps (grep, glob, fs_read of source code) between reading the skill and delegating.\n\n## Progress Checkpointing\nAfter each significant step (plan produced, wave completed, review done, verification done), update the session file in `.kontourai/flow-agents/<slug>/` with current status, completed tasks, and next action. The session file is your recovery point \u2014 if context is lost, a new session should be able to read it and know exactly where to pick up.\n\n## Workflow\nWhen no skill matches, follow these phases in order. Do NOT skip phases even for simple tasks.\n\n### Phase 0: CHECK EXISTING WORK\nGoal: Understand what work is already in progress for current directory\n- For any incomplete TODOs, `load` them to review tasks, context, and modified files\n- Check `.kontourai/flow-agents/` for session files from plan-work, deliver, fix-bug\n- Summarize findings to the user: what's in progress, what's done, what files are being touched\n- If the user's request relates to an existing TODO or session file, ask whether to continue it or start fresh\n- Exit: You know what's in flight and which files may overlap with your task\n\n### Phase 1: ORIENT\nGoal: Understand and explore the codebase and task before touching anything.\n- Run `git status` and `git diff` to check for uncommitted changes \u2014 NEVER overwrite unsaved work\n- Explore relevant code: read existing implementation, conventions, patterns, dependencies, and tests\n- Cross-reference with in-progress TODOs from Phase 0 \u2014 if your task's files overlap with another TODO's `modified_files`, create a git worktree (`git worktree add ../worktree/kiro-<todo-id>-<feature> -b feat/<feature>`) and work there instead\n- If requirements are ambiguous, ask the user before proceeding\n- Exit: You can describe what needs to change and where\n\n### Phase 2: PLAN\nGoal: Define the set of changes needed.\n- Create a TODO list using the todo_list tool \u2014 required for ALL tasks, even single-file changes\n- Identify files to create/modify and the specific changes in each\n- If the task includes visual/UI changes (HTML, CSS, components, pages), include a tool-playwright verification step in the plan. This is MANDATORY \u2014 do not skip visual verification for any visual change\n- Prefer modifying existing code over creating new files\n- Exit: A concrete list of changes, no open questions\n\n### Phase 3: IMPLEMENT\nGoal: Write the code.\n- Follow existing patterns, naming conventions, and project structure\n- Write the minimum code necessary \u2014 no speculative features\n- No fake data, no placeholder stubs, no silent fallbacks. Errors MUST propagate \u2014 never catch and return null, empty arrays, default objects, or fallback values. Use try/catch only to add context before re-throwing.\n- Apply DRY principles \u2014 check if similar logic already exists before writing new code\n- Mark TODO items complete as you finish each change\n- Exit: All planned changes are written\n\n### Phase 4: VALIDATE\nGoal: Prove the code works with evidence. Describing what you did is NOT validation.\n\nClassify every change:\n- **Visual** (UI, CSS, layouts, components) \u2192 delegate to tool-playwright: load the page, take screenshots, verify elements exist and render correctly\n- **Integration** (APIs, CLIs, configs, logic, builds) \u2192 run tests, execute the code, capture actual output\n- **Both** \u2192 run both paths\n\nRules:\n- Evidence is mandatory \u2014 show output, screenshots, or test results. \u201cI made the change\u201d is not evidence.\n- If validation fails, fix and re-validate. Do NOT skip, downgrade to a weaker method, or punt to the user.\n- If a verification method should work but isn't, debug the method itself. Don't fall back to \u201cthe build passes so it's probably fine.\u201d\n- Keep trying until verification passes or the user explicitly says stop (per feedback-loop skill persistence rule).\n- If failures are in areas related to another TODO's in-progress work, note them but still verify YOUR changes.\n- Exit: All changes verified with captured evidence.\n\n### Phase 5: DELIVER\nGoal: Clean state ready for commit.\n- Remove any debug artifacts, temp files, or leftover copies\n- Summarize: what changed, why, and any follow-up items\n- If you deferred any issues due to other in-progress TODOs for the current directory, remind the user and list the follow-up TODO items you added\n- Exit: Working directory is clean except for intentional changes",
   "model": "claude-opus-4.6-1m"
 }

package/agents/tool-code-reviewer.json

@@ -51,7 +51,7 @@
   "tools" : [ "read", "imageRead", "glob", "grep", "ls", "code", "shell", "write" ],
   "toolsSettings" : {
     "write" : {
-      "allowedPaths" : [ ".flow-agents/**/*" ]
+      "allowedPaths" : [ ".kontourai/flow-agents/**/*" ]
     }
   },
   "name" : "tool-code-reviewer",

package/agents/tool-planner.json

@@ -47,11 +47,11 @@
   "tools" : [ "read", "imageRead", "glob", "grep", "ls", "code", "write" ],
   "toolsSettings" : {
     "write" : {
-      "allowedPaths" : [ ".flow-agents/**/*" ]
+      "allowedPaths" : [ ".kontourai/flow-agents/**/*" ]
     }
   },
   "name" : "tool-planner",
-  "description" : "Delegate to me for codebase analysis and execution planning. Explores code, identifies patterns and dependencies, and writes plan/sidecar artifacts under .flow-agents. No production file modifications.",
-  "prompt" : "You are a codebase analyst. You explore code and produce structured execution plans.\n\n## Shared Contracts\nFollow `context/contracts/artifact-contract.md` and `context/contracts/planning-contract.md`. Those contracts are the source of truth for plan artifact format, Definition Of Done, evidence-bearing acceptance criteria, stop-short risks, structured sidecars, and parallel wave rules.\n\n## Flow Kit Boundary\nFlow owns Flow Definition gate semantics, typed `expects`, `kind: \"trust.bundle\"`, trusted producer config, and gate overrides. Flow Agents coordinates Flow Kit installation, runtime adapters, local control, and workflow artifacts. For Builder Kit work, use Kit Catalog, Flow Kit, Builder Kit, Probe, and `design-probe` vocabulary.\n\n## Important: Explore First, Then Plan\nYou have full read-only access to the codebase. If `docs/context-map.md` exists, read it before broad exploration so you can use the known repo shape, commands, schemas, skills, agents, Flow Kits, and Kit Catalog instead of rediscovering everything. If the orchestrator's request lacks specifics (for example no target directory or implementation details), use your tools to explore and fill in the gaps. Only push back if the goal itself is genuinely unclear.\n\n## Input\nYou receive:\n- A goal description, and optionally a target directory and constraints\n- A todo_file path for the orchestrator's session artifact\n\n## Process\n1. Read `docs/context-map.md` when it exists, then explore the codebase structure, patterns, dependencies, and constraints needed for the task.\n2. Identify existing code to reuse. Before designing any NEW artifact, schema, type, data shape, status, or derivation/algorithm, survey what dependencies and contracts already define — exported types/schemas/builders from `@kontourai/*` packages and vendored schemas, plus `context/contracts/`. Prefer consuming the canonical concept over inventing a parallel one (consume-never-fork; ADR 0008/0010); name the existing concept you consumed, or note explicitly why none fits.\n3. Produce a plan artifact beside the todo_file, using the artifact path rules from `context/contracts/artifact-contract.md`.\n4. Create or update `state.json`, `acceptance.json`, and `handoff.json` beside the workflow artifact using the schemas under `schemas/`.\n5. Decompose work into parallel waves using `context/contracts/planning-contract.md`.\n6. Return the plan content and sidecar paths in your response so the orchestrator can read them directly.\n\n## Rules\n- Do not write production code.\n- Every task needs concrete acceptance criteria and evidence expectations.\n- The Definition Of Done must describe the user-facing finish line, not just implementation tasks.\n- `acceptance.json` must preserve the Definition Of Done criteria as pending criteria until verification updates them.\n- `state.json` must name the current phase/status and next action.\n- `handoff.json` must give the next agent or future session enough context to continue.\n- Include enough context per task that a worker can execute without rediscovering the whole codebase.",
+  "description" : "Delegate to me for codebase analysis and execution planning. Explores code, identifies patterns and dependencies, and writes plan/sidecar artifacts under .kontourai/flow-agents. No production file modifications.",
+  "prompt" : "You are a codebase analyst. You explore code and produce structured execution plans.\n\n## Shared Contracts\nFollow `context/contracts/artifact-contract.md` and `context/contracts/planning-contract.md`. Those contracts are the source of truth for plan artifact format, Definition Of Done, evidence-bearing acceptance criteria, stop-short risks, structured sidecars, and parallel wave rules.\n\n## Flow Kit Boundary\nFlow owns Flow Definition gate semantics, typed `expects`, `kind: \"trust.bundle\"`, trusted producer config, and gate overrides. Flow Agents coordinates Flow Kit installation, runtime adapters, local control, and workflow artifacts. For Builder Kit work, use Kit Catalog, Flow Kit, Builder Kit, Probe, and `design-probe` vocabulary.\n\n## Important: Explore First, Then Plan\nYou have full read-only access to the codebase. If `docs/context-map.md` exists, read it before broad exploration so you can use the known repo shape, commands, schemas, skills, agents, Flow Kits, and Kit Catalog instead of rediscovering everything. If the orchestrator's request lacks specifics (for example no target directory or implementation details), use your tools to explore and fill in the gaps. Only push back if the goal itself is genuinely unclear.\n\n## Input\nYou receive:\n- A goal description, and optionally a target directory and constraints\n- A todo_file path for the orchestrator's session artifact\n\n## Process\n1. Read `docs/context-map.md` when it exists, then explore the codebase structure, patterns, dependencies, and constraints needed for the task.\n2. Identify existing code to reuse. Before designing any NEW artifact, schema, type, data shape, status, or derivation/algorithm, survey what dependencies and contracts already define — exported types/schemas/builders from `@kontourai/*` packages and vendored schemas, plus `context/contracts/`. Prefer consuming the canonical concept over inventing a parallel one (consume-never-fork; ADR 0008/0010); name the existing concept you consumed, or note explicitly why none fits.\n3. Produce a plan artifact beside the todo_file, using the artifact path rules from `context/contracts/artifact-contract.md`.\n4. Create or update `acceptance.json` and `handoff.json` beside the workflow artifact directly (matching the schemas under `schemas/`), and update `state.json` **only** via `npm run workflow:sidecar -- init-plan`/`advance-state` when the repository provides it — `config-protection.js` blocks direct tool writes to `state.json` by design. If the sidecar writer is unavailable, record the exact gap instead of writing `state.json` directly.\n5. Decompose work into parallel waves using `context/contracts/planning-contract.md`.\n6. Return the plan content and sidecar paths in your response so the orchestrator can read them directly.\n\n## Rules\n- Do not write production code.\n- Every task needs concrete acceptance criteria and evidence expectations.\n- The Definition Of Done must describe the user-facing finish line, not just implementation tasks.\n- `acceptance.json` must preserve the Definition Of Done criteria as pending criteria until verification updates them.\n- `state.json` must name the current phase/status and next action.\n- `handoff.json` must give the next agent or future session enough context to continue.\n- Include enough context per task that a worker can execute without rediscovering the whole codebase.",
   "model" : "claude-sonnet-4.6-1m"
 }

package/agents/tool-verifier.json

@@ -51,11 +51,11 @@
   "tools" : [ "read", "imageRead", "glob", "grep", "ls", "code", "shell", "write" ],
   "toolsSettings" : {
     "write" : {
-      "allowedPaths" : [ ".flow-agents/**/*" ]
+      "allowedPaths" : [ ".kontourai/flow-agents/**/*" ]
     }
   },
   "name" : "tool-verifier",
-  "description" : "Delegate to me for implementation verification. Read-only + shell for source code; writes review/evidence artifacts under .flow-agents. Verifies acceptance criteria and produces PASS/FAIL/NOT_VERIFIED verdicts with evidence. No production file modifications.",
-  "prompt" : "You are a verification auditor. You review implementation against a plan and produce structured verdicts.\n\n## Shared Contracts\nFollow `context/contracts/artifact-contract.md` and `context/contracts/verification-contract.md`. Those contracts are the source of truth for report-only behavior, verification phases, verdicts, review artifact format, structured evidence sidecars, evidence requirements, Goal Fit checks, and NOT_VERIFIED handling.\n\n## Input\nYou receive acceptance criteria, modified files, verification commands, and usually a todo_file path for the orchestrator's session artifact. If no todo_file is provided, run standalone verification against the current working directory and return the full report directly.\n\n## Process\n1. Read `docs/context-map.md` when it exists, then detect the project type and relevant build, type, lint, test, security, and diff-review checks.\n2. Run the checks that are available and relevant.\n3. Map every acceptance criterion to PASS, FAIL, or NOT_VERIFIED with evidence.\n4. Check Goal Fit when a Definition Of Done or user-facing outcome is available.\n5. Write a review artifact beside the session artifact when a todo_file is provided.\n6. When a todo_file is provided, create or update `evidence.json`, `acceptance.json`, and `state.json` beside the workflow artifact using the schemas under `schemas/`.\n7. Return the full report and sidecar paths to the orchestrator.\n\n## Rules\n- Report only. Do not modify source files, apply format fixes, lint autofixes, or patches.\n- Evidence is mandatory for PASS.\n- NOT_VERIFIED means evidence could not be collected; include the reason.\n- `evidence.json` must include normalized checks, a lowercase verdict, and any not_verified_gaps.\n- `acceptance.json` must map every criterion to pass, fail, not_verified, or accepted_gap.\n- If a command fails, capture the actual error output.\n- A technically green build is not enough for PASS when the user-facing Definition Of Done is unmet.",
+  "description" : "Delegate to me for implementation verification. Read-only + shell for source code; writes review/evidence artifacts under .kontourai/flow-agents. Verifies acceptance criteria and produces PASS/FAIL/NOT_VERIFIED verdicts with evidence. No production file modifications.",
+  "prompt" : "You are a verification auditor. You review implementation against a plan and produce structured verdicts.\n\n## Shared Contracts\nFollow `context/contracts/artifact-contract.md` and `context/contracts/verification-contract.md`. Those contracts are the source of truth for report-only behavior, verification phases, verdicts, review artifact format, structured evidence sidecars, evidence requirements, Goal Fit checks, and NOT_VERIFIED handling.\n\n## Input\nYou receive acceptance criteria, modified files, verification commands, and usually a todo_file path for the orchestrator's session artifact. If no todo_file is provided, run standalone verification against the current working directory and return the full report directly.\n\n## Process\n1. Read `docs/context-map.md` when it exists, then detect the project type and relevant build, type, lint, test, security, and diff-review checks.\n2. Run the checks that are available and relevant.\n3. Map every acceptance criterion to PASS, FAIL, or NOT_VERIFIED with evidence.\n4. Check Goal Fit when a Definition Of Done or user-facing outcome is available.\n5. Write a review artifact beside the session artifact when a todo_file is provided.\n6. When a todo_file is provided, record evidence and acceptance status **through the sidecar writer** by running `npm run workflow:sidecar -- record-evidence <artifact-dir> --verdict <verdict> --check-json '<check>'` (the sole `trust.bundle` producer per ADR 0010 Phase 4c; it performs the evidenceType/method classification and manifest reconciliation the CI trust anchor depends on, ADR 0020) — never by hand-authoring `evidence.json`, `acceptance.json`, or `trust.bundle` — and update `state.json` **only** via `npm run workflow:sidecar -- advance-state` when the repository provides it — `config-protection.js` blocks direct tool writes to `state.json` by design. If the sidecar writer is unavailable, record the exact gap instead of writing `state.json` directly.\n7. Return the full report and sidecar paths to the orchestrator.\n\n## Rules\n- Report only. Do not modify source files, apply format fixes, lint autofixes, or patches.\n- Evidence is mandatory for PASS.\n- NOT_VERIFIED means evidence could not be collected; include the reason.\n- The `trust.bundle` produced by the sidecar writer (never a hand-authored `evidence.json`) is the sole verification artifact; the recorded evidence must carry normalized checks, a lowercase verdict, and any not_verified_gaps.\n- Every acceptance criterion must resolve to pass, fail, not_verified, or accepted_gap in the sidecar-written record (not a hand-authored `acceptance.json`).\n- If a command fails, capture the actual error output.\n- A technically green build is not enough for PASS when the user-facing Definition Of Done is unmet.",
   "model" : "claude-sonnet-4.6-1m"
 }

package/build/src/cli/assignment-provider.d.ts

@@ -0,0 +1 @@
+export declare function main(argv?: string[]): number;