@kontourai/flow-agents 3.3.0 → 3.4.1

package/.github/workflows/add-to-project.yml

@@ -0,0 +1,15 @@
+name: Add issue to org project
+
+on:
+  issues:
+    types: [opened, reopened, closed]
+
+permissions:
+  contents: read
+  issues: read
+
+jobs:
+  add-to-project:
+    uses: kontourai/.github/.github/workflows/add-issue-to-project.yml@main
+    secrets:
+      ADD_TO_PROJECT_PAT: ${{ secrets.ADD_TO_PROJECT_PAT }}

package/.github/workflows/ci.yml

@@ -145,6 +145,10 @@ jobs:
         continue-on-error: true
         run: bash evals/ci/run-baseline.sh --check sidecar-field-preservation-integration
 
+      - name: Record-check integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check record-check-integration
+
       - name: Actor identity resolver integration
         continue-on-error: true
         run: bash evals/ci/run-baseline.sh --check actor-identity-resolver-integration
@@ -185,6 +189,14 @@ jobs:
         continue-on-error: true
         run: bash evals/ci/run-baseline.sh --check current-json-per-actor-integration
 
+      - name: Liveness console relay integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check liveness-console-relay-integration
+
+      - name: Console tenant isolation integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check console-tenant-isolation-integration
+
       - name: Finalize CI evidence
         if: always()
         run: bash evals/ci/run-baseline.sh --finalize
@@ -306,6 +318,18 @@ jobs:
         continue-on-error: true
         run: bash evals/ci/run-baseline.sh --check usage-and-cost-integration
 
+      - name: Telemetry usage pipeline integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check telemetry-usage-pipeline-integration
+
+      - name: Economics record integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check economics-record-integration
+
+      - name: Learning review proposals integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check learning-review-proposals-integration
+
       - name: Utterance check integration
         continue-on-error: true
         run: bash evals/ci/run-baseline.sh --check utterance-check-integration
@@ -350,6 +374,143 @@ jobs:
           if-no-files-found: warn
           retention-days: 14
 
+  integration-coverage:
+    name: Integration Coverage
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    env:
+      FLOW_AGENTS_CI_LANE: integration-coverage
+      FLOW_AGENTS_CI_RESULTS_DIR: evals/results/ci-baseline/integration-coverage
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      - name: Set up Node.js
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: "24"
+
+      - name: Install Node dependencies
+        run: npm ci
+
+      - name: Install shell tools
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y jq ripgrep
+
+      - name: Initialize CI evidence
+        run: bash evals/ci/run-baseline.sh --init
+
+      - name: Builder step producers integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check builder-step-producers-integration
+
+      - name: Builder canonical Flow run integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check builder-canonical-flow-run-integration
+
+      - name: Codex hook resolution integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check codex-hook-resolution-integration
+
+      - name: Critique supersession roundtrip integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check critique-supersession-roundtrip-integration
+
+      - name: Dual emit flow step integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check dual-emit-flow-step-integration
+
+      - name: Evidence capture hook integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check evidence-capture-hook-integration
+
+      - name: Exemption usage review integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check exemption-usage-review-integration
+
+      - name: FlowDefinition session history preservation integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check flowdefinition-session-history-preservation-integration
+
+      - name: Gate review inquiry records integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check gate-review-inquiry-records-integration
+
+      - name: Install merge integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check install-merge-integration
+
+      - name: Kit identity trust integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check kit-identity-trust-integration
+
+      - name: Liveness worktree root integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check liveness-worktree-root-integration
+
+      - name: Migrate local artifacts integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check migrate-local-artifacts-integration
+
+      - name: Model routing escalation integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check model-routing-escalation-integration
+
+      - name: Promote gate integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check promote-gate-integration
+
+      - name: Pull work board integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check pull-work-board-integration
+
+      - name: Routing efficiency integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check routing-efficiency-integration
+
+      - name: Session resume roundtrip integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check session-resume-roundtrip-integration
+
+      - name: Skill drift check integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check skill-drift-check-integration
+
+      - name: Trust reconcile trailer diagnostic integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check trust-reconcile-trailer-diagnostic-integration
+
+      - name: Validate artifacts portability integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check validate-artifacts-portability-integration
+
+      - name: Verify CLI integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check verify-cli-integration
+
+      - name: Veritas governance adapter integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check veritas-governance-adapter-integration
+
+      - name: Workspace settings integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check workspace-settings-integration
+
+      - name: Finalize CI evidence
+        if: always()
+        run: bash evals/ci/run-baseline.sh --finalize
+
+      - name: Upload CI evidence artifacts
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: flow-agents-ci-integration-coverage
+          path: evals/results/ci-baseline/integration-coverage/
+          if-no-files-found: warn
+          retention-days: 14
+
   usage-feedback:
     name: Usage Feedback
     runs-on: ubuntu-latest

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # Changelog
 
+## [3.4.1](https://github.com/kontourai/flow-agents/compare/v3.4.0...v3.4.1) (2026-07-10)
+
+
+### Fixes
+
+* resolve packaged Flow definitions in consumer repos ([#532](https://github.com/kontourai/flow-agents/issues/532)) ([3eb4a2e](https://github.com/kontourai/flow-agents/commit/3eb4a2e42d49a9c31b16ef62484cf5b0a001c7a1))
+
+## [3.4.0](https://github.com/kontourai/flow-agents/compare/v3.3.0...v3.4.0) (2026-07-10)
+
+
+### Features
+
+* **builder:** add fail-closed FlowRun adapter prefix ([#511](https://github.com/kontourai/flow-agents/issues/511)) ([1f2a1bd](https://github.com/kontourai/flow-agents/commit/1f2a1bd0a6a6f1b5610848b417ed8c9561b85131))
+* **builder:** route Codex specialists by role ([5a53e9b](https://github.com/kontourai/flow-agents/commit/5a53e9bb79afbba6823c7c1de77125030d87dc41))
+* drive Builder sessions with canonical Flow runs ([#531](https://github.com/kontourai/flow-agents/issues/531)) ([72301c7](https://github.com/kontourai/flow-agents/commit/72301c735d3788283ffe40963ee7fc622f69e822))
+* **engine:** collapse kit trust model to structured steering (kit-neutral) ([#491](https://github.com/kontourai/flow-agents/issues/491)) ([615dc44](https://github.com/kontourai/flow-agents/commit/615dc4477f884e8ad61f37ea67fc250a3a3030ec))
+* installed-skill drift detection — per-skill manifest, skill-drift-check CLI, SessionStart advisory ([#439](https://github.com/kontourai/flow-agents/issues/439)) ([#455](https://github.com/kontourai/flow-agents/issues/455)) ([a23c346](https://github.com/kontourai/flow-agents/commit/a23c34673e41bc8dcb8fd0c72425ac5ae83f4247))
+* **install:** guided console-connect wizard + auto-verify + post-install summary (easy-install-flow PR2/3) ([#483](https://github.com/kontourai/flow-agents/issues/483)) ([573fd81](https://github.com/kontourai/flow-agents/commit/573fd81860de9731ebe76f352da8502137159bb7))
+* **install:** runtime auto-detection + surface silent fail-open paths (easy-install-flow PR1/3) ([#482](https://github.com/kontourai/flow-agents/issues/482)) ([a9d249e](https://github.com/kontourai/flow-agents/commit/a9d249ee1b5104488ead521dbd012e5cc8240b6c))
+* **learning-review:** economics-driven advisory proposals + human-ratified decision ledger ([#352](https://github.com/kontourai/flow-agents/issues/352)) ([#464](https://github.com/kontourai/flow-agents/issues/464)) ([1f8e56b](https://github.com/kontourai/flow-agents/commit/1f8e56bba2a71e77e43e42dc2574101e40399adc))
+* **telemetry:** auto-discover owner console conf via trusted workspace/global tiers (fa[#410](https://github.com/kontourai/flow-agents/issues/410) slice 1) ([#460](https://github.com/kontourai/flow-agents/issues/460)) ([4f82858](https://github.com/kontourai/flow-agents/commit/4f828589dc70d6a25bfa609961968833106d58e4))
+* **telemetry:** config-driven kit-economics console relay so ROI views populate ([#469](https://github.com/kontourai/flow-agents/issues/469)) ([#471](https://github.com/kontourai/flow-agents/issues/471)) ([f604f60](https://github.com/kontourai/flow-agents/commit/f604f609924635ea53ac051b822ee068504f59fb))
+* **veritas-governance:** exemption-usage-review skill, trailer diagnostic, DECLARED scope-forms docs ([#408](https://github.com/kontourai/flow-agents/issues/408)) ([d304621](https://github.com/kontourai/flow-agents/commit/d304621d744f84cd422ca069183f41826c2c1b20))
+
+
+### Fixes
+
+* **checks:** content-boundary scans untracked files — local matches CI (closes [#367](https://github.com/kontourai/flow-agents/issues/367)) ([#374](https://github.com/kontourai/flow-agents/issues/374)) ([a4e7a0e](https://github.com/kontourai/flow-agents/commit/a4e7a0ef8341ab951597ef6255e4b66f315f8f2c))
+* codex capture false-pass — deterministic exit codes, ambiguous default, anti-forgery extraction ([2806c5b](https://github.com/kontourai/flow-agents/commit/2806c5bb7c39e376937162ab0680c01f4fc80666))
+* codex capture false-pass — deterministic exit codes, ambiguous default, anti-forgery extraction ([#470](https://github.com/kontourai/flow-agents/issues/470)) ([06c292a](https://github.com/kontourai/flow-agents/commit/06c292a6ccfface4d778f78ec2e04ba2dd801daa))
+* enforce first-step workflow entry ([17b3a12](https://github.com/kontourai/flow-agents/commit/17b3a1282f491cd2c655b0da9847c00925f18ef8))
+* **goal-fit:** stop re-running model-asserted RECHECK text on terminal sessions ([#494](https://github.com/kontourai/flow-agents/issues/494)) ([#504](https://github.com/kontourai/flow-agents/issues/504)) ([9546252](https://github.com/kontourai/flow-agents/commit/954625233dddd14772b57ecba98016a911443f4d))
+* harden global Codex home installs ([1bfaba6](https://github.com/kontourai/flow-agents/commit/1bfaba65a3b490d0b031401268c55b8d74f930b7))
+* preserve user installer settings conflicts ([#430](https://github.com/kontourai/flow-agents/issues/430)) ([ac2d356](https://github.com/kontourai/flow-agents/commit/ac2d3567f47a744c7c5466d60aec26577f846a31))
+* **sidecar:** trust-bundle writers compose losslessly; record-check; record-time evidence-ref validation ([#418](https://github.com/kontourai/flow-agents/issues/418)) ([800675f](https://github.com/kontourai/flow-agents/commit/800675f75033a164c24e2be379dc2b41c76d2237))
+* skill-drift-check ignores foreign (non-kit) installed files ([#465](https://github.com/kontourai/flow-agents/issues/465)) ([#468](https://github.com/kontourai/flow-agents/issues/468)) ([71985c9](https://github.com/kontourai/flow-agents/commit/71985c9c8f860a50b25f1bec3818af9807832cae))
+* **telemetry:** land owner usage attributed + priced in the hosted console ([#487](https://github.com/kontourai/flow-agents/issues/487)) ([ace8faf](https://github.com/kontourai/flow-agents/commit/ace8fafc2af274302397c1e12bb09388db5fe0e9))
+* **telemetry:** real per-session token/cost + model so console ROI stops showing $0 ([#477](https://github.com/kontourai/flow-agents/issues/477)) ([2a6fcfc](https://github.com/kontourai/flow-agents/commit/2a6fcfc5d18acaddcb64eabc4341e10d2c9d7184))
+* **telemetry:** suppress console relay of genuinely-empty economics records ([#478](https://github.com/kontourai/flow-agents/issues/478)) ([b09b6de](https://github.com/kontourai/flow-agents/commit/b09b6de189f6bef051c25fbb6c52dd61919d9c62))
+
+
+### Documentation
+
+* **console:** document attribution & pricing correctness ([#487](https://github.com/kontourai/flow-agents/issues/487)) ([#490](https://github.com/kontourai/flow-agents/issues/490)) ([36b0ec2](https://github.com/kontourai/flow-agents/commit/36b0ec288b3aea6ca49efaaa2373ea9b60a55197))
+* **decisions:** embeddable engine and adapter model direction ([#499](https://github.com/kontourai/flow-agents/issues/499)) ([89aec1d](https://github.com/kontourai/flow-agents/commit/89aec1df53df27cfa85685bc24612edf0882cb5c))
+* **engine:** reframe around engine↔kit split + honest trust tiers ([#495](https://github.com/kontourai/flow-agents/issues/495)) ([b5b5ae3](https://github.com/kontourai/flow-agents/commit/b5b5ae392cd43ee2e0374b5b08da40add5c06c3a))
+* trust-reconciliation guide + trust-ledger-retention decision ([#488](https://github.com/kontourai/flow-agents/issues/488)) ([9d5feba](https://github.com/kontourai/flow-agents/commit/9d5febae318e62bb59189279321d92f4ede3afa2))
+
 ## [3.3.0](https://github.com/kontourai/flow-agents/compare/v3.2.0...v3.3.0) (2026-07-05)
 
 

package/CONTEXT.md

@@ -171,6 +171,11 @@ A stable explanation for why a Gate passed, failed, could not be verified, or ro
 One execution of a Workflow from selected scope through its gates, evidence, route-backs, and terminal outcome. A Workflow Run references its canonical Selected Scope and snapshots the selected subject identifiers for audit history. Builder Kit Delivery Runs are a build-specific kind of Workflow Run.
 _Avoid_: Delivery Run as the generic term
 
+### Workflow Entry Authority
+
+The authority to create a new Workflow Run or resume an existing one. A new run always starts at the Workflow's first step; a later current step is valid only when recovered from persisted run state whose transitions, gate outcomes, evidence, and accepted exceptions validate against the canonical Workflow definition. Gate exceptions may authorize a gate outcome inside an existing run, but never authorize selecting a later starting step.
+_Avoid_: Ad-hoc entry, skip-step override
+
 ### Run Plan
 
 The core workflow-level plan for a Workflow Run. Run Plans describe intended gate order, selected scope, required capabilities, required evidence, route-back policy, and learning points without assuming the work is software delivery.
@@ -398,4 +403,3 @@ The CI-anchored reconciliation of a session's trust claims against a manifest
 
 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

@@ -17,7 +17,7 @@
 
 Agents are powerful and forgetful. They plan well, then drift. They skip verification when context gets crowded. They call partial work done, and after a compaction nobody — including the agent — can say where the work actually stands.
 
-Flow Agents addresses this with a process-discipline layer that sits between the user and the agent: four canonical policy classes (workflow steering, quality gate, stop-goal-fit, config protection), durable sidecar state that survives compaction and handoff, evidence gates before release decisions, and telemetry that feeds corrections back into the system. [Kontour Flow](https://kontourai.github.io/flow/) owns the gate semantics underneath; Flow Agents compiles those policies to whatever hook surface a host exposes — coding-agent harnesses today, agent frameworks next.
+Flow Agents has two layers. The **engine** is product-neutral: FlowDefinition interpretation, gates, runtime and harness adapters, SDK/evidence/trust primitives, and kit validation. **Kits** are the swappable solutions on top: Builder, Knowledge, Release Evidence, Veritas Governance, and any third-party kit declared with `kit.json` and registered through a catalog. [Kontour Flow](https://kontourai.github.io/flow/) owns the gate semantics underneath; Flow Agents compiles those policies to whatever hook surface a host exposes — coding-agent harnesses today, agent frameworks next.
 
 **You ask for outcomes. The system supplies the path, the state, the checks, and the proof.**
 
@@ -28,7 +28,8 @@ Flow Agents addresses this with a process-discipline layer that sits between the
 - **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).
+- **Tamper-evident "done"** — the local runtime gate is advisory and best-effort; the controlled CI re-run is the authoritative anchor that reconciles manifest commands and git diff against fresh results before evidence is treated as CI-verified. See [Verifiable Trust — why "done" actually means done](docs/verifiable-trust.md).
+- **Engine plus opt-in kits** — `kits/catalog.json` lists discoverable kits, each `kit.json` declares its flows and assets, and bring-your-own-kit follows the same validation and activation path. See [Engine and Kits](docs/architecture-engine-and-kits.md).
 - **Evals that keep the bundle honest** — 60 integration scenarios (1,829 assertions) and 7 static suites (110 assertions) validate the skills, contracts, fixtures, and hook influence as the bundle evolves.
 
 ## Flow Agents as a process-discipline layer
@@ -83,16 +84,18 @@ npx @kontourai/flow-agents init --dest /path/to/workspace --telemetry-sink local
 
 # runtime-specific wiring
 npx @kontourai/flow-agents init --runtime claude-code --dest /path/to/workspace --yes
-npx @kontourai/flow-agents init --runtime codex --dest /path/to/workspace --activate-kits --yes
+npx @kontourai/flow-agents init --runtime codex --dest /path/to/workspace --activate-kit builder --yes
 npx @kontourai/flow-agents init --runtime opencode --dest /path/to/workspace --yes
 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.
 
+Runtime auto-detection is best-effort: it first checks environment markers set by the invoking coding agent (e.g. `CLAUDECODE`, `CODEX_SESSION_ID`, `OPENCODE_SESSION_ID`), then falls back to checking whether exactly one of `~/.claude`, `~/.codex` (or `$CODEX_HOME`), or opencode's global config dir already exists. If neither signal is unambiguous, it defaults to `base`. Pass `--runtime` explicitly to override the detected default at any time.
+
 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 …`).
+The installer copies the bundled agents, skills, context, scripts, evals, the kit catalog, and the Flow Agents-owned `console.telemetry.json` descriptor into the target workspace. Kits are opt-in at activation time: pass `--activate-kit <kit-id>` for a specific kit, or `--activate-kits` when you intentionally want every catalog kit. 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 …`).
 
 `bash install.sh` is the low-level option for CI pipelines or scripts that already have a generated bundle checkout (e.g. from a pinned `git clone` of this repo). Prefer `npx @kontourai/flow-agents init` for normal workspace setup — it fetches the latest published bundle and auto-detects the runtime:
 
@@ -106,7 +109,7 @@ After installing, ask the agent for the workflow you want — in plain language.
 
 ### Builder Kit quick start
 
-The Builder Kit installs automatically and gives your agent two gated flows: `builder.shape` turns a raw idea into slices and executable work items; `builder.build` takes a selected work item through design probe, planning, execution, verification, PR readiness, merge readiness, and learning.
+After activating the Builder Kit, your agent gets two gated flows: `builder.shape` turns a raw idea into slices and executable work items; `builder.build` takes a selected work item through design probe, planning, execution, verification, PR readiness, merge readiness, and learning.
 
 Shape an idea:
 
@@ -135,11 +138,15 @@ Use fix-bug. Reproduce the problem, diagnose root cause, implement the fix, and
 
 The [Workflow Usage Guide](docs/workflow-usage-guide.md) has example prompts and expected behavior for every stage — `pull-work`, `plan-work`, `execute-plan`, `review-work`, `verify-work`, `fix-bug`, `release-readiness`, and more. The [Agent System Guidebook](docs/agent-system-guidebook.md) is the plain-language map of how the pieces fit.
 
-## Flow Kits
+## Engine and Flow Kits
+
+Flow Agents is not the Builder Kit. The engine is kit-neutral: every kit, built-in or third-party, declares its flows and assets in `kit.json` and is discovered through a catalog. Runtime steering comes from structured `workflow_triggers` rendered through the same engine path; `first_party` or "official" status is marketplace/catalog metadata only and grants no runtime privilege.
+
+Read [Engine and Kits](docs/architecture-engine-and-kits.md) for the canonical split, including the built-in catalog, the manifest model, and the bring-your-own-kit extension point.
 
 A Flow Kit bundles a workflow AND its opinionated output shape into a single validated unit: a `kit.json` manifest (schema version 1.0), one or more Flow Definitions, and optional skills, docs, adapters, evals, and assets. Authoring a kit means deciding not just _what_ an agent does but _how the result is rendered_ — the same pipeline produces different representations depending on which store adapter is active. Kits are the extension model for Flow Agents: validated and installed through the `flow-agents kit` CLI, and activatable into any workspace that runs Flow Agents.
 
-**Builder Kit** — ships with `builder.shape` (shape a problem into slices and fileable work items) and `builder.build` (pull ready work through design probing, planning, execution, verification, PR readiness, merge readiness, and learning). Installed automatically by `npx @kontourai/flow-agents init`.
+**Builder Kit** — ships with `builder.shape` (shape a problem into slices and fileable work items), `builder.build` (pull ready work through design probing, planning, execution, verification, PR readiness, merge readiness, and learning), and `builder.publish-learn` (publish, provider/CI merge readiness, and learning feedback gates).
 
 **Knowledge Kit** — a Flow Kit for durable, gated knowledge storage. It ships a store contract with four record types (`raw`, `compiled`, `concept`, `snapshot`), five pipeline flows (`ingest`, `compile`, `synthesize`, `consolidate`, `retire`), and a mutation policy of propose→evidence-gate→apply/reject with supersede-not-delete. All mutations require provenance; nothing is silently overwritten or deleted. Ships with 198 tests.
 
@@ -161,7 +168,11 @@ npx @kontourai/flow-agents kit install path/to/my-kit --dest /path/to/workspace
 - [Flow Kit Repository Contract](docs/flow-kit-repository-contract.md) — the full validation rules, registry schema, and activation diagnostics.
 - [Knowledge Kit docs](kits/knowledge/docs/README.md) — store contract, record types, mutation ops, similarity detectors, and the Obsidian adapter.
 
-**Direction** (not shipped): domain kits that compose this substrate — a Sales Kit (territory/customer/initiative schema with side-effect adapters for CRM logging), a Research Kit (transcript capture→compile→recall). Distribution follows sequencing: authoring tooling and covetable reference kits first, then a registry, then a marketplace. No marketplace claims are shipped.
+**Release Evidence Kit** — a minimal flows-only kit that proves agentless gate evaluation over trusted `release.evidence` claims in CI.
+
+**Veritas Governance Kit** — an agentless kit that gates a real `veritas readiness` verdict as a trust.bundle software-readiness-verdict claim. It wraps @kontourai/veritas through CLI + a kit-local adapter and does not reimplement standards evaluation.
+
+**Direction**: domain kits that compose this substrate — a Sales Kit (territory/customer/initiative schema with side-effect adapters for CRM logging), a Research Kit (transcript capture→compile→recall), and community-contributed kits discovered through a marketplace. Marketplace labels such as official or first-party describe provenance; they do not grant runtime privilege.
 
 ## Framework adapters
 

package/build/src/builder-flow-run-adapter.d.ts

@@ -0,0 +1,80 @@
+import { type FlowEvidenceEntry, type FlowRunState, type GateOutcome, type JsonObject } from "@kontourai/flow";
+export declare const BUILDER_BUILD_FLOW_ID = "builder.build";
+export declare const BUILDER_BUILD_FLOW_RELATIVE_PATH = "kits/builder/flows/build.flow.json";
+export interface BuilderBuildTrustBundleEvidenceInput {
+    gate: string;
+    /**
+     * Trusted local evidence path interpreted by Flow relative to `cwd`.
+     * Callers must not pass raw user-controlled paths to this local runtime API.
+     */
+    file: string;
+    status?: "passed" | "failed";
+    producer?: string;
+    authorityTrace?: string;
+    routeReason?: string;
+    expectationIds?: string[];
+    supersede?: string | string[];
+    classifier?: JsonObject;
+    diagnostics?: JsonObject;
+    analytics?: JsonObject;
+}
+export interface StartBuilderBuildRunInput {
+    subject: string;
+    params?: JsonObject;
+    /**
+     * Trusted local runtime root. Flow owns persistence and interprets attached
+     * evidence files relative to this directory.
+     */
+    cwd?: string;
+    runId?: string;
+}
+export interface EvaluateBuilderBuildRunInput {
+    runId: string;
+    /**
+     * Trusted local runtime root. Flow owns persistence and interprets attached
+     * evidence files relative to this directory.
+     */
+    cwd?: string;
+    evidence?: BuilderBuildTrustBundleEvidenceInput;
+}
+export interface LoadBuilderBuildRunInput {
+    runId: string;
+    cwd?: string;
+}
+export interface BuilderBuildRunResult {
+    definitionId: typeof BUILDER_BUILD_FLOW_ID;
+    definitionVersion: string;
+    runId: string;
+    dir: string;
+    state: FlowRunState;
+    attachedEvidence: FlowEvidenceEntry[];
+    outcomes: GateOutcome[];
+    manifest: JsonObject;
+    freshnessTransitions: JsonObject[];
+}
+export type BuilderBuildRunIdentityMismatch = "definition-id" | "definition-version" | "definition-content";
+export declare class BuilderBuildRunInputError extends Error {
+    readonly code: "BUILDER_BUILD_RUN_INVALID_INPUT";
+    readonly field: string;
+    constructor(field: string, reason: string);
+}
+export declare class BuilderBuildRunIdentityError extends Error {
+    readonly code: "BUILDER_BUILD_RUN_IDENTITY_MISMATCH";
+    readonly expectedDefinitionId: string;
+    readonly expectedDefinitionVersion: string;
+    readonly actualDefinitionId: string;
+    readonly actualDefinitionVersion: string;
+    readonly mismatch: BuilderBuildRunIdentityMismatch;
+    readonly runId: string;
+    constructor(runId: string, expectedDefinition: {
+        id: string;
+        version: string;
+    }, actualDefinition: {
+        id: string;
+        version: string;
+    }, mismatch: BuilderBuildRunIdentityMismatch);
+}
+export declare function resolveBuilderBuildFlowDefinitionPath(startDir?: string): string;
+export declare function startBuilderBuildRun(input: StartBuilderBuildRunInput): Promise<BuilderBuildRunResult>;
+export declare function evaluateBuilderBuildRun(input: EvaluateBuilderBuildRunInput): Promise<BuilderBuildRunResult>;
+export declare function loadBuilderBuildRun(input: LoadBuilderBuildRunInput): Promise<BuilderBuildRunResult>;