@kontourai/flow-agents 2.2.0 → 2.4.0

package/.github/CODEOWNERS

@@ -22,6 +22,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 +30,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,14 @@ 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: Finalize CI evidence
         if: always()
         run: bash evals/ci/run-baseline.sh --finalize
@@ -246,6 +258,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 +278,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/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,51 @@
 # Changelog
 
+## [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)
+
+
+### Features
+
+* **strands-ts:** consume @kontourai/console-telemetry for pricing/cost ([eb878b0](https://github.com/kontourai/flow-agents/commit/eb878b024a166b68d5cef00cd659311de9c7b49b))
+
 ## [2.2.0](https://github.com/kontourai/flow-agents/compare/v2.1.1...v2.2.0) (2026-06-30)
 
 

package/CONTEXT.md

@@ -256,6 +256,20 @@ _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.
+
+### 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.

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/console-learning-projection.js

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import { fileURLToPath } from "node:url";
 import * as path from "node:path";
 import { flagBool, flagString, parseArgs } from "../lib/args.js";
+import { defaultArtifactRootForRead } from "../lib/local-artifact-root.js";
 import { buildWorkflowLearningProjection, readWorkflowLearningSources } from "../lib/workflow-learning-projection.js";
 const SAFE_SEGMENT = /^[A-Za-z0-9._-]+$/;
 function printHelp() {
@@ -10,7 +11,7 @@ function printHelp() {
     console.log("Build an inert Console learning projection from local workflow learning sidecars.");
     console.log("");
     console.log("Options:");
-    console.log("  --artifact-root <path>  Workflow artifact root to scan (default: .flow-agents)");
+    console.log("  --artifact-root <path>  Workflow artifact root to scan (default: .kontourai/flow-agents)");
     console.log("  --kontour-root <path>   Local Kontour root to write under (default: .kontour)");
     console.log("  --scope <id>            Projection scope id (default: current directory name)");
     console.log("  --scope-kind <kind>     Projection scope kind (default: repo)");
@@ -84,7 +85,7 @@ export function main(argv = process.argv.slice(2)) {
         return 0;
     }
     try {
-        const artifactRoot = path.resolve(flagString(flags, "artifact-root", ".flow-agents") ?? ".flow-agents");
+        const artifactRoot = path.resolve(flagString(flags, "artifact-root") ?? defaultArtifactRootForRead());
         const kontourRoot = path.resolve(flagString(flags, "kontour-root", ".kontour") ?? ".kontour");
         const producer = requireSafeSegment(flagString(flags, "producer", "flow-agents-learning") ?? "flow-agents-learning", "--producer");
         const scope = {

package/build/src/cli/init.js

@@ -10,6 +10,7 @@ import { parseArgs, flagBool, flagList, flagString } from "../lib/args.js";
 import { activateCodexLocal } from "../runtime-adapters.js";
 import { main as buildBundles } from "../tools/build-universal-bundles.js";
 import { root } from "../tools/common.js";
+import { defaultCodexHome, durableInstallRecordPath } from "../lib/local-artifact-root.js";
 const runtimeBundles = {
     base: "base",
     codex: "codex",
@@ -82,8 +83,8 @@ Options:
                           Honors FLOW_AGENTS_USER_CLAUDE_SETTINGS for test isolation.
                         opencode: merges opencode.json into ~/.config/opencode/opencode.json
                           (honors XDG_CONFIG_HOME; test isolation via FLOW_AGENTS_USER_OPENCODE_CONFIG).
-                        codex: runs install-codex-home.sh into ~/.flow-agents/codex
-                          (the isolated Codex HOME; hooks merged, not overwritten).
+                        codex: runs install-codex-home.sh into CODEX_HOME or ~/.codex
+                          (hooks merged, not overwritten).
                         pi: NOT_VERIFIED (no documented global dir); warns and falls back to workspace default.
   --telemetry-sink local-files|local-kontour-console|kontour-hosted-console|user-hosted-console
   --console-url URL
@@ -174,9 +175,8 @@ function globalDest(runtime) {
         return path.join(process.env["XDG_CONFIG_HOME"] ?? path.join(os.homedir(), ".config"), "opencode");
     }
     if (runtime === "codex") {
-        // codex --global routes to the isolated Codex HOME at ~/.flow-agents/codex.
-        // This is the same path used by install-codex-home.sh; --dest overrides it for sandbox testing.
-        return path.join(os.homedir(), ".flow-agents", "codex");
+        // codex --global routes to the standard Codex home. --dest remains an explicit override.
+        return defaultCodexHome();
     }
     if (runtime === "pi") {
         // pi has no documented global config dir.
@@ -268,6 +268,75 @@ function ensureBundle(runtime) {
         throw new Error(`bundle installer missing: ${bundle}`);
     return bundle;
 }
+// The bundle's hook commands resolve the flow-agents scripts directory via
+// ${CLAUDE_PROJECT_DIR:-$(pwd)}. That is correct for a project-scoped install
+// (installBundle rsyncs scripts/ alongside .claude/, so CLAUDE_PROJECT_DIR ==
+// the install destination). It is NOT correct for a --global install: there
+// is no per-destination copy of scripts/, and CLAUDE_PROJECT_DIR varies with
+// whichever project happens to be open, so the hook resolves to a path that
+// exists in at most one project (and never for most sessions). Global
+// installs need an absolute, session-independent path instead.
+const GLOBAL_INSTALL_PROJECT_DIR_PREFIX = /root="\$\{CLAUDE_PROJECT_DIR:-\$\(pwd\)\}";\s*/g;
+const GLOBAL_INSTALL_PROJECT_DIR_VAR = /"\$root\//g;
+function rewriteCommandForGlobalInstall(command, sourceRoot) {
+    return command
+        .replace(GLOBAL_INSTALL_PROJECT_DIR_PREFIX, "")
+        .replace(GLOBAL_INSTALL_PROJECT_DIR_VAR, `"${sourceRoot}/`);
+}
+/** Recursively rewrite every `command` string found under `value` in place. */
+function rewriteCommandsForGlobalInstall(value, sourceRoot) {
+    if (Array.isArray(value)) {
+        for (const item of value)
+            rewriteCommandsForGlobalInstall(item, sourceRoot);
+        return;
+    }
+    if (!value || typeof value !== "object")
+        return;
+    const obj = value;
+    for (const key of Object.keys(obj)) {
+        if (key === "command" && typeof obj[key] === "string") {
+            obj[key] = rewriteCommandForGlobalInstall(obj[key], sourceRoot);
+            continue;
+        }
+        rewriteCommandsForGlobalInstall(obj[key], sourceRoot);
+    }
+}
+/**
+ * Additively copy every file under srcDir into destDir, creating directories
+ * as needed and overwriting files whose content changed. Never deletes files
+ * in destDir that srcDir does not own — destDir may contain unrelated content
+ * (other kits, other tools) that this sync must not touch.
+ */
+function copyDirMerge(srcDir, destDir) {
+    let added = 0;
+    let updated = 0;
+    if (!fs.existsSync(srcDir))
+        return { added, updated };
+    for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+        const srcPath = path.join(srcDir, entry.name);
+        const destPath = path.join(destDir, entry.name);
+        if (entry.isDirectory()) {
+            const nested = copyDirMerge(srcPath, destPath);
+            added += nested.added;
+            updated += nested.updated;
+            continue;
+        }
+        if (!entry.isFile())
+            continue;
+        const content = fs.readFileSync(srcPath);
+        if (fs.existsSync(destPath)) {
+            if (Buffer.compare(fs.readFileSync(destPath), content) === 0)
+                continue;
+            updated += 1;
+        }
+        else {
+            fs.mkdirSync(path.dirname(destPath), { recursive: true });
+            added += 1;
+        }
+        fs.writeFileSync(destPath, content);
+    }
+    return { added, updated };
+}
 function installBundle(bundle, options) {
     const args = ["install.sh", options.dest];
     for (const sink of options.telemetrySinks)
@@ -334,10 +403,13 @@ export async function main(argv = process.argv.slice(2)) {
             if (!options.global)
                 checkScopeCollision();
         }
-        // --global for claude-code: merge only into the global/user-level settings dir.
-        // This writes only the hook-wiring config (merge into ~/.claude/settings.json),
-        // not the full workspace bundle. The global settings dir is the claude config root,
-        // so the settings.json lives directly in dest (not dest/.claude/).
+        // --global for claude-code: merge hook-wiring into the global/user-level
+        // settings dir, plus additively sync skills/agents so a global install
+        // does not silently go stale as new Builder Kit skills ship. This does
+        // NOT rsync the full workspace bundle (no context/, powers/, prompts/,
+        // etc.) — only the parts a global Claude Code user-config needs. The
+        // global settings dir is the claude config root, so the settings.json
+        // lives directly in dest (not dest/.claude/).
         if (options.global && options.runtime === "claude-code") {
             const bundle = ensureBundle(options.runtime);
             // For --global, dest is ~/.claude/ (the global settings dir).
@@ -353,6 +425,10 @@ export async function main(argv = process.argv.slice(2)) {
             // Remove permissive defaults (not appropriate for global user settings).
             delete managed["permissions"];
             delete managed["skipDangerousModePermissionPrompt"];
+            // See rewriteCommandsForGlobalInstall: bundle hook commands assume
+            // CLAUDE_PROJECT_DIR points at this package; a global install must not
+            // depend on which project is currently open, so pin to an absolute path.
+            rewriteCommandsForGlobalInstall(managed, root);
             fs.mkdirSync(options.dest, { recursive: true });
             const destSettingsPath = path.join(options.dest, "settings.json");
             const installMergePath = path.join(root, "scripts", "install-merge.js");
@@ -371,16 +447,21 @@ export async function main(argv = process.argv.slice(2)) {
             const tmp = `${destSettingsPath}.tmp.${process.pid}`;
             fs.writeFileSync(tmp, `${JSON.stringify(merged, null, 2)}\n`, "utf8");
             fs.renameSync(tmp, destSettingsPath);
+            // Additive skills/agents sync: adds new files and updates changed ones,
+            // never deletes — dest may hold unrelated content from other kits/tools.
+            const skillsSync = copyDirMerge(path.join(bundle, ".claude", "skills"), path.join(options.dest, "skills"));
+            const agentsSync = copyDirMerge(path.join(bundle, ".claude", "agents"), path.join(options.dest, "agents"));
             // Write version stamp.
-            const installRecordDir = path.join(options.dest, ".flow-agents");
+            const recordPath = durableInstallRecordPath(options.dest);
+            const installRecordDir = path.dirname(recordPath);
             fs.mkdirSync(installRecordDir, { recursive: true });
             const pkgJson = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
             const record = { version: pkgJson["version"] ?? "0.0.0", installedAt: new Date().toISOString(), runtime: "claude-code", global: true };
-            const recordPath = path.join(installRecordDir, "install.json");
             const recordTmp = `${recordPath}.tmp.${process.pid}`;
             fs.writeFileSync(recordTmp, `${JSON.stringify(record, null, 2)}\n`, "utf8");
             fs.renameSync(recordTmp, recordPath);
             console.log(`Flow Agents global hooks merged for claude-code in ${options.dest}`);
+            console.log(`Synced skills (+${skillsSync.added} new, ~${skillsSync.updated} updated) and agents (+${agentsSync.added} new, ~${agentsSync.updated} updated) in ${options.dest}`);
             return 0;
         }
         // --global for opencode: merge FA opencode.json into the global opencode config dir.
@@ -415,11 +496,11 @@ export async function main(argv = process.argv.slice(2)) {
 `, "utf8");
             fs.renameSync(tmp, destConfigPath);
             // Write version stamp.
-            const installRecordDir = path.join(options.dest, ".flow-agents");
+            const recordPath = durableInstallRecordPath(options.dest);
+            const installRecordDir = path.dirname(recordPath);
             fs.mkdirSync(installRecordDir, { recursive: true });
             const pkgJson = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
             const record = { version: pkgJson["version"] ?? "0.0.0", installedAt: new Date().toISOString(), runtime: "opencode", global: true };
-            const recordPath = path.join(installRecordDir, "install.json");
             const recordTmp = `${recordPath}.tmp.${process.pid}`;
             fs.writeFileSync(recordTmp, `${JSON.stringify(record, null, 2)}
 `, "utf8");
@@ -427,9 +508,8 @@ export async function main(argv = process.argv.slice(2)) {
             console.log(`Flow Agents global config merged for opencode in ${options.dest}`);
             return 0;
         }
-        // --global for codex: run install-codex-home.sh to install into the isolated Codex HOME.
-        // The codex --global path is ~/.flow-agents/codex (the isolated home IS codex's global).
-        // Pass through telemetry/console args and honor --dest override for sandbox testing.
+        // --global for codex: run install-codex-home.sh to install into the Codex home.
+        // Defaults to CODEX_HOME or ~/.codex. --dest remains an explicit override.
         if (options.global && options.runtime === "codex") {
             const codexHomeScript = path.join(root, "scripts", "install-codex-home.sh");
             if (!fs.existsSync(codexHomeScript)) {
@@ -452,7 +532,10 @@ export async function main(argv = process.argv.slice(2)) {
                 console.error(`flow-agents init: unable to run install-codex-home.sh: ${result.error.message}`);
                 return 1;
             }
-            return result.status ?? 1;
+            const installed = result.status ?? 1;
+            if (installed !== 0)
+                return installed;
+            return activateKits(options);
         }
         // --global for pi: NOT_VERIFIED (no documented global dir). Warn and fall through to workspace install.
         if (options.global && options.runtime === "pi") {
@@ -541,11 +624,11 @@ function dogfoodClaudeCode(bundleRoot, dest) {
     fs.writeFileSync(tmp, `${JSON.stringify(merged, null, 2)}\n`, "utf8");
     fs.renameSync(tmp, destSettingsPath);
     // Write version stamp.
-    const installRecordDir = path.join(dest, ".flow-agents");
+    const recordPath = durableInstallRecordPath(dest);
+    const installRecordDir = path.dirname(recordPath);
     fs.mkdirSync(installRecordDir, { recursive: true });
     const pkgJson = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
     const record = { version: pkgJson["version"] ?? "0.0.0", installedAt: new Date().toISOString(), runtime: "claude-code" };
-    const recordPath = path.join(installRecordDir, "install.json");
     const recordTmp = `${recordPath}.tmp.${process.pid}`;
     fs.writeFileSync(recordTmp, `${JSON.stringify(record, null, 2)}\n`, "utf8");
     fs.renameSync(recordTmp, recordPath);
@@ -584,11 +667,11 @@ function dogfoodCodex(bundleRoot, dest) {
     fs.writeFileSync(tmp, `${JSON.stringify(merged, null, 2)}\n`, "utf8");
     fs.renameSync(tmp, destHooksPath);
     // Write version stamp.
-    const installRecordDir = path.join(dest, ".flow-agents");
+    const recordPath = durableInstallRecordPath(dest);
+    const installRecordDir = path.dirname(recordPath);
     fs.mkdirSync(installRecordDir, { recursive: true });
     const pkgJson = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
     const record = { version: pkgJson["version"] ?? "0.0.0", installedAt: new Date().toISOString(), runtime: "codex" };
-    const recordPath = path.join(installRecordDir, "install.json");
     const recordTmp = `${recordPath}.tmp.${process.pid}`;
     fs.writeFileSync(recordTmp, `${JSON.stringify(record, null, 2)}\n`, "utf8");
     fs.renameSync(recordTmp, recordPath);