@kontourai/flow-agents 1.1.0 → 1.3.0

package/docs/getting-started.md

@@ -0,0 +1,177 @@
+---
+title: Builder Kit Quick Start
+---
+
+# Builder Kit Quick Start
+
+This guide takes you from nothing to a running, gated build flow in about two minutes. By the end you will have Flow Agents installed in your coding agent's workspace and understand how the Builder Kit's two flows — `builder.shape` and `builder.build` — turn a raw idea into a merged change with evidence.
+
+## 1. Install
+
+Run this from any workspace you want to add discipline to:
+
+```bash
+npx @kontourai/flow-agents init --runtime <your-agent> --dest .
+```
+
+Where `--runtime` is one of `claude-code`, `codex`, `kiro`, `opencode`, or `pi`. For a fully unattended install:
+
+```bash
+npx @kontourai/flow-agents init --runtime claude-code --dest . --yes
+npx @kontourai/flow-agents init --runtime codex       --dest . --yes
+npx @kontourai/flow-agents init --runtime opencode    --dest . --yes
+```
+
+The installer copies agents, skills, context contracts, hook scripts, Kit assets, and the Flow Agents telemetry descriptor into the workspace. The Builder Kit installs automatically. Your agent reads those files at startup; no plugin registry required.
+
+**What lands in the workspace:**
+
+- `agents/`, `skills/`, `context/` — skill definitions and shared contracts the agent follows
+- `scripts/hooks/` — four canonical policy scripts (steering, quality gate, stop-goal-fit, config protection) wired to the host's native hook surface
+- `kits/builder/` — Builder Kit flows and skills
+- `console.telemetry.json` — telemetry descriptor (writes locally by default)
+
+At L2 conformance (Claude Code, Codex, Kiro) all four hooks are active and the stop hook blocks early exits that lack evidence. At L1 (opencode, pi) steering and stop-goal-fit run but without blocking capability; see the [Runtime Hook Surface spec](spec/runtime-hook-surface.html) for the gaps.
+
+## 2. What the Builder Kit gives you
+
+The Builder Kit installs two flows:
+
+| Flow | ID | What it does |
+|---|---|---|
+| Shape | `builder.shape` | Turns a raw idea into slices and executable work items |
+| Build | `builder.build` | Takes a ready work item through design probe → plan → execute → verify → PR → merge readiness → learn |
+
+These are not freeform chat sessions. Each flow has **evidence gates** — named checkpoints that expect specific claims before the next step starts. The agent cannot silently skip a gate; it either satisfies the expectation or the transition is blocked (at L2) or flagged (at L1).
+
+**Shape flow gates** (`builder.shape`):
+
+- `shape-gate` — problem, outcome, constraints, non-goals, success criteria, and risk are stated
+- `breakdown-gate` — work is split into independently useful slices
+- `file-issues-gate` — each slice becomes a filed work item with enough context to pull later
+
+**Build flow gates** (`builder.build`):
+
+- `pull-work-gate` — a ready work item is selected with scope and acceptance context
+- `design-probe-gate` — goal fit, blockers, dependencies, and planning readiness are recorded before a plan is written
+- `plan-gate` — the plan names files, changes, acceptance evidence, and sequencing
+- `execute-gate` — changed files are recorded and unrelated work is excluded
+- `verify-gate` — tests or checks have evidence tied to the implementation (up to 3 route-back attempts before blocking)
+- `merge-ready-gate` — scope, evidence, and residual risks support a merge-ready decision
+- `pr-open-gate` — a pull request exists with linked work and verification evidence
+- `merge-ready-ci-gate` — CI and review status support merge
+- `learn-gate` — decisions and delivery learnings are recorded for future work
+
+The gate semantics live in [Kontour Flow](https://kontourai.github.io/flow/); Flow Agents compiles them to whatever hook surface your agent exposes.
+
+## 3. A two-minute first run
+
+### Step 1 — Shape an idea
+
+In your coding agent, paste this:
+
+```text
+Use Builder Kit shape. I want to add a progress indicator to the CLI output so
+users can see what step the installer is on. Keep it simple — just a step count
+like "[2/5] Copying agents". Shape this into an executable work item and stop
+at the backlog gate.
+```
+
+The agent will run the `builder-shape` / `idea-to-backlog` skill, which:
+
+1. inventories the idea and classifies it
+2. proposes the thinnest meaningful slice (the step counter) and names what is out of scope
+3. drafts a shaped work item with a stated outcome, non-goals, acceptance criteria, and a verification expectation
+4. stops at the `breakdown-gate` and waits for you to confirm before creating GitHub issues
+
+You will see the agent write a local artifact at `.flow-agents/<slug>/<slug>--idea-to-backlog.md`. That artifact is the machine-readable input to the next stage — not a summary in the chat window.
+
+To continue and file the GitHub issue:
+
+```text
+That looks right. File the GitHub issue and stop.
+```
+
+The agent runs the `file-issues` step, checks the `file-issues-gate`, and stops. You now have a shaped, filed work item that the build flow can pull.
+
+### Step 2 — Build that work item
+
+```text
+Use deliver for the issue you just filed. Pull it, probe the design, plan it,
+implement it, review it, verify it, and stop if any evidence is missing.
+```
+
+The `deliver` skill orchestrates the full `builder.build` flow:
+
+1. **pull-work** — selects the issue, confirms scope and acceptance criteria (`pull-work-gate`)
+2. **design-probe** — checks goal fit, identifies blockers and dependencies, and records planning readiness before touching a file (`design-probe-gate`)
+3. **plan-work** — delegates to `tool-planner`, which writes a structured plan artifact naming files, changes, sequencing, and acceptance evidence (`plan-gate`)
+4. **execute-plan** — fans out to up to four `tool-worker` subagents in parallel waves (`execute-gate`)
+5. **review-work** — code and optional security review (`critique.json` sidecar)
+6. **verify-work** — tests and checks with evidence tied to the change; if evidence is missing the verify-gate triggers a route-back (`verify-gate`)
+7. **release-readiness** — scope, evidence, and risk assessment (`merge-ready-gate`)
+8. **pull-request** — PR with linked work item and verification evidence (`pr-open-gate`)
+
+You can also invoke each skill individually if you want explicit control:
+
+```text
+Use pull-work to select issue #42.
+```
+
+```text
+Use plan-work on the session artifact from the pull-work step.
+```
+
+```text
+Use verify-work on the current branch and report what evidence is present.
+```
+
+### What you observe
+
+- **Between each step**, the agent writes a local session sidecar under `.flow-agents/<slug>/` — `state.json`, `acceptance.json`, `evidence.json`, and `handoff.json`. These survive compaction, tab close, or a new session. A future session resumes from recorded state.
+- **At each gate**, the agent either presents the evidence and moves forward, or blocks and explains what is missing. It does not make up a confident summary and proceed.
+- **The stop-goal-fit hook** (at L2) prevents the agent from stopping when evidence is still incomplete — you see a warning or block rather than "all done!" on partial work.
+- **If verify fails**, the verify-gate routes back to execution (or plan, or design-probe, depending on the failure class) and tries again — up to three times before hard-blocking.
+
+This is guided, not fully automated. The agent handles the mechanics; you make product decisions. Gates are explicit handoff points, not invisible checkboxes.
+
+## 4. Inspect what you installed
+
+After installing, you can inspect the Builder Kit's declared contents:
+
+```bash
+node build/src/cli.js kit inspect kits/builder
+```
+
+(Or, from a global install: `flow-agents kit inspect kits/builder`)
+
+This prints the kit id, name, declared flows, skills, and conformance level (K0/K1). It does not require a running agent or active session.
+
+To see the raw flow definitions with their gate expectations:
+
+```bash
+cat kits/builder/flows/shape.flow.json
+cat kits/builder/flows/build.flow.json
+```
+
+## 5. Verify your setup
+
+After installing, run the source validation to confirm the workspace is coherent:
+
+```bash
+npm run validate:source
+```
+
+For a full static eval pass (docs layout, legacy-term checks, bundle assertions):
+
+```bash
+npm run eval:static
+```
+
+## What to read next
+
+- [Workflow Usage Guide](workflow-usage-guide.html) — example prompts and expected behavior for every skill and stage
+- [Agent System Guidebook](agent-system-guidebook.html) — how the pieces fit together conceptually
+- [Kit Authoring Guide](kit-authoring-guide.html) — author your own Flow Kit from scratch
+- [Runtime Hook Surface spec](spec/runtime-hook-surface.html) — hook events, conformance levels, and host gaps
+- [Workflow Artifact Lifecycle](workflow-artifact-lifecycle.html) — when to promote local artifacts to durable docs

package/docs/index.md

@@ -71,24 +71,31 @@ The same canonical policies wire into agent frameworks as in-process language-na
 
 ## Quick Start
 
+Install into your workspace in one command:
+
 ```bash
-npx @kontourai/flow-agents init --dest /path/to/workspace
+npx @kontourai/flow-agents init --runtime <your-agent> --dest .
 ```
 
-Runtime-specific installs:
+Where `--runtime` is `claude-code`, `codex`, `kiro`, `opencode`, or `pi`. The Builder Kit installs automatically and gives your agent two gated flows: `builder.shape` (idea → slices → filed work items) and `builder.build` (selected work item → design probe → plan → execute → verify → PR → learn).
 
-```bash
-npx @kontourai/flow-agents init --runtime claude-code --dest /path/to/workspace --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
+Ask your agent to shape an idea:
+
+```text
+Use Builder Kit shape. I want to add a progress indicator to the CLI output
+so users can see what step the installer is on. Shape this into an executable
+work item and stop at the backlog gate.
 ```
 
-Then ask for the workflow you want, in plain language:
+Then build it:
 
 ```text
-Use deliver for this GitHub issue. Plan it, implement it, review it, verify it, and stop if evidence is missing.
+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 cannot proceed past a gate without the expected evidence — it either presents it or blocks and explains what is missing. See the <a href="getting-started.html">Builder Kit Quick Start</a> for a full two-minute walkthrough with worked examples and an explanation of what you observe at each gate.
+
 For bugs:
 
 ```text
@@ -98,6 +105,10 @@ Use fix-bug. Reproduce the problem, diagnose root cause, implement the fix, and
 ## Explore the docs
 
 <div class="doc-grid">
+  <a class="doc-card" href="getting-started.html">
+    <strong>Builder Kit Quick Start</strong>
+    <span>Zero to a running, gated build flow in two minutes: install, shape an idea into a work item, build it through the builder.shape and builder.build flows, and see what the evidence gates do.</span>
+  </a>
   <a class="doc-card" href="workflow-usage-guide.html">
     <strong>Workflow Usage Guide</strong>
     <span>Every stage from shaping ideas to learning review, with example prompts and expected behavior.</span>

package/docs/kit-authoring-guide.md

@@ -74,12 +74,12 @@ A Flow Definition at minimum needs `id`, `version`, `steps`, and `gates`. Steps
       "expects": [
         {
           "id": "review-finding",
-          "kind": "surface.claim",
+          "kind": "trust.bundle",
           "required": true,
           "description": "The change was reviewed and findings were recorded.",
-          "claim": {
-            "type": "my-kit.review.finding",
-            "subject": "artifact",
+          "bundle_claim": {
+            "claimType": "my-kit.review.finding",
+            "subjectType": "artifact",
             "accepted_statuses": ["trusted", "accepted"]
           }
         }
@@ -112,7 +112,7 @@ npm run validate:source --
 Once validation passes, install the kit into a target workspace:
 
 ```bash
-npx @kontourai/flow-agents flow-kit install-local path/to/my-kit --dest /path/to/workspace
+npx @kontourai/flow-agents kit install path/to/my-kit --dest /path/to/workspace
 ```
 
 `--dest` is the installed Flow Agents bundle root. When omitted the command uses the current directory. From a contributor checkout of this repository, the equivalent form is `npm run flow-kit -- <command>`.
@@ -120,8 +120,8 @@ npx @kontourai/flow-agents flow-kit install-local path/to/my-kit --dest /path/to
 Confirm the install:
 
 ```bash
-npx @kontourai/flow-agents flow-kit list --dest /path/to/workspace
-npx @kontourai/flow-agents flow-kit status my-kit --dest /path/to/workspace
+npx @kontourai/flow-agents kit list --dest /path/to/workspace
+npx @kontourai/flow-agents kit status my-kit --dest /path/to/workspace
 ```
 
 `list` prints one summary line per installed kit. `status` prints JSON provenance including the SHA256 content hash and `installed` or `missing` state.
@@ -129,7 +129,7 @@ npx @kontourai/flow-agents flow-kit status my-kit --dest /path/to/workspace
 To replace an existing install after you update the kit source:
 
 ```bash
-npx @kontourai/flow-agents flow-kit install-local path/to/my-kit --dest /path/to/workspace --update
+npx @kontourai/flow-agents kit install path/to/my-kit --dest /path/to/workspace --update
 ```
 
 ## Activate
@@ -137,7 +137,7 @@ npx @kontourai/flow-agents flow-kit install-local path/to/my-kit --dest /path/to
 After installing, run activate to write runtime-local files into the workspace:
 
 ```bash
-npx @kontourai/flow-agents flow-kit activate --dest /path/to/workspace --format json
+npx @kontourai/flow-agents kit activate --dest /path/to/workspace --format json
 ```
 
 The `codex-local` adapter is selected automatically. To activate for Strands, pass `--adapter strands-local`.
@@ -194,7 +194,7 @@ The **container contract** is owned by [Kontour Flow](https://kontourai.github.i
 - Path rules: all declared paths must be relative, must not contain `..`, and must resolve inside the kit directory.
 - The **extension model**: unknown top-level fields are consumer extensions; core validation ignores-but-permits them.
 
-Container validation is surfaced in Flow's CLI as `flow validate-kit <kit-dir>`. Flow Agents delegates container validation to Flow when `FLOW_CLI_ROOT` is configured; without it, Flow Agents applies the same rules internally.
+Container validation is surfaced in Flow's CLI as `flow kit validate <kit-dir>`. Flow Agents delegates core container validation to `@kontourai/flow`'s `validateKitContainer` library function; the contract lives once, in Flow.
 
 For the authoritative container spec and JSON Schema, see [kontourai/flow#67](https://github.com/kontourai/flow/pull/67) (the spec PR) and the published `schemas/flow-kit-container.schema.json` in the `@kontourai/flow` package.
 
@@ -270,7 +270,7 @@ Version constraints (e.g. minimum `flow-agents` version) are the only case where
 
 ### Evidence layering: Surface and Veritas
 
-Kit gates reference evidence using `"kind": "surface.claim"`. This is **Flow-native vocabulary**: Flow is built on Surface, so Surface claims are the expected evidence substrate at the Flow level. Surface claims are not a Flow Agents coupling.
+Kit gates reference evidence using `"kind": "trust.bundle"` with a `bundle_claim` selector (`claimType`, optional `subjectType`, `accepted_statuses`). This is **Flow-native vocabulary** in the Hachure open trust-bundle format: Flow is built on Surface, so trust bundles are the expected evidence substrate at the Flow level, validated against Hachure's `trust-bundle.schema.json`. They are not a Flow Agents coupling. (Earlier Flow releases used `kind: "surface.claim"` with a `claim` selector; Flow 1.3.0 replaced that with `trust.bundle`, kontourai/flow#84.)
 
 Veritas is an **optional claim family** — a developer-repo specialization for evidence that has been through a trust pipeline. Kits may be opinionated about requiring Veritas-class evidence. Builder Kit requiring Veritas-class evidence is the kit's own policy choice, defined by Kontour as the kit author, not a platform requirement. Other kits may not require Veritas at all.
 
@@ -284,7 +284,7 @@ Layering summary:
 Use the `inspect` subcommand to derive a kit's conformance level and consumer targets:
 
 ```bash
-npm run flow-kit -- inspect path/to/my-kit
+npm run kit -- inspect path/to/my-kit
 ```
 
 Output is stable JSON:
@@ -299,7 +299,8 @@ Output is stable JSON:
     "k2": false
   },
   "targets": ["flow", "flow-agents"],
-  "third_party_extensions": []
+  "third_party_extensions": [],
+  "trust": "unverified"
 }
 ```
 
@@ -307,6 +308,117 @@ Exit code 0 when the kit is at least K0 (valid core container); exit code 1 when
 
 The `inspect` command is read-only and safe to run before install.
 
+## Trust axis: who vouches for a kit
+
+The **trust axis** is a separate, orthogonal classification from the K-level capability axis. It answers the question "who vouches for this kit?" rather than "what does this kit contain?".
+
+### Two orthogonal axes
+
+Every kit carries two independent badges:
+
+| Axis | Values | Question answered |
+|---|---|---|
+| **Capability** (K-level) | K0 / K1 / K2 | What does the kit CONTAIN? (derived from assets) |
+| **Trust** | first-party / verified / unverified | WHO vouches for it? (derived from provenance) |
+
+A K2 kit can be `unverified`. A K0 kit can be `first-party`. The levels are independent.
+
+**Marketplace listing format**: `Works with: Flow (gates-only) | K1 | ✓ First-party`
+
+### Trust levels
+
+| Level | Meaning | How it is assigned (v1) |
+|---|---|---|
+| `first-party` | Kontour authored, tested, and ships this kit in the `@kontourai/flow-agents` package. | Kit id is in the internal FIRST_PARTY_KIT_IDS allowlist in `src/flow-kit/validate.ts`. |
+| `verified` | Reserved for a future third-party verification process. | Not yet implemented; the value is reserved but not granted to any kit today. |
+| `unverified` | Default for all kits not explicitly vouched for. | All other kits, including third-party community kits. |
+
+`unverified` says nothing about the quality of a kit — it only means Kontour has not vouched for it through one of the above channels.
+
+### First-party kits (v1)
+
+The first-party allowlist in v1 contains the kits authored by Kontour and distributed with the flow-agents package:
+
+- `builder` — Builder Kit (shape, build, and deliver work)
+- `knowledge` — Knowledge Kit (durable gated knowledge store)
+
+Criteria for a kit to be first-party:
+1. Its directory lives under `kits/` in the `kontourai/flow-agents` repository.
+2. It is published as part of the `@kontourai/flow-agents` npm package.
+3. Kontour owns and maintains the kit's content and release lifecycle.
+
+Third-party forks, community kits, or kits published under a different npm package are NOT first-party even if they share a similar id. First-party is tied to provenance in this specific repository and package.
+
+### Deferred: verified trust and cryptographic attestation (v2)
+
+The `verified` value is reserved for a future verification process. The intended v2 path:
+
+- Third-party kit authors can apply for `verified` status.
+- Verification evidence: the kit passes the conformance kit self-certification + a cryptographic signature or Veritas attestation.
+- The [conformance kit](https://github.com/kontourai/flow) and [Veritas claims](veritas-integration.md) are the natural substrate for this attestation layer.
+- The signature or attestation would be checked by `flow-agents kit inspect` at derivation time.
+
+v1 deliberately omits the signing/attestation mechanism and the verification process. The `verified` value is reserved so consuming tools can handle it when it arrives without a breaking schema change.
+
+### Inspecting trust
+
+The `trust` field appears in `flow-agents kit inspect` output alongside `conformance`:
+
+```bash
+npm run kit -- inspect kits/builder
+```
+
+```json
+{
+  "kit_id": "builder",
+  "kit_name": "Builder Kit",
+  "conformance": {
+    "k0": true,
+    "k1": true,
+    "k2": false
+  },
+  "targets": ["flow", "flow-agents"],
+  "third_party_extensions": [],
+  "trust": "first-party"
+}
+```
+
+A third-party kit inspected before verification:
+
+```json
+{
+  "kit_id": "my-custom-kit",
+  "kit_name": "My Custom Kit",
+  "conformance": {
+    "k0": true,
+    "k1": true,
+    "k2": false
+  },
+  "targets": ["flow", "flow-agents"],
+  "third_party_extensions": [],
+  "trust": "unverified"
+}
+```
+
 ## Direction
 
 Flow Kits are designed to be shareable workflow units — authored once, carried across teams and workspaces. The intended growth path is distribution from git remotes and a curated Kontour kit catalog of Kontour-authored kits covering work modes beyond software delivery. Today install is local-path only; remote fetch is explicitly a non-goal in this version.
+
+## Migration: flow-kit → flow-agents kit
+
+The standalone `flow-kit` binary was removed in this release. The `flow-agents kit` subcommand is the replacement.
+
+| Old command | New command |
+|---|---|
+| `flow-kit install-local <path>` | `flow-agents kit install <path>` |
+| `flow-kit install-git <url>` | `flow-agents kit install <url>` |
+| `flow-kit activate` | `flow-agents kit activate` |
+| `flow-kit inspect <dir>` | `flow-agents kit inspect <dir>` |
+| `flow-kit list` | `flow-agents kit list` |
+| `flow-kit status <id>` | `flow-agents kit status <id>` |
+| `npx @kontourai/flow-agents flow-kit ...` | `npx @kontourai/flow-agents kit ...` |
+| `npm run flow-kit -- ...` | `npm run kit -- ...` |
+
+`install-local` and `install-git` are unified into a single `install` command. The source argument auto-detects whether it is a local path or a git URL (http://, https://, git+, ssh://, file://).
+
+Running the old `flow-kit` command will produce a "command not found" error from your shell — there is no alias or shim. Update any scripts or CI configurations that call `flow-kit` to use `flow-agents kit`.

package/docs/knowledge-kit.md

@@ -4,7 +4,7 @@ title: Knowledge Kit
 
 # Knowledge Kit
 
-The Knowledge Kit is a Flow Kit for durable, gated knowledge storage. It packages a store contract, five pipeline flows, pluggable store adapters, and a parameterized contract test suite — all validated and installed through the standard `flow-kit` path.
+The Knowledge Kit is a Flow Kit for durable, gated knowledge storage. It packages a store contract, five pipeline flows, pluggable store adapters, and a parameterized contract test suite — all validated and installed through the `flow-agents kit` path.
 
 ## What it ships
 
@@ -44,7 +44,7 @@ The vector detector is fail-closed: infrastructure failures throw `EMBED_FAILURE
 
 ```bash
 # Install the kit into a workspace
-npx @kontourai/flow-agents flow-kit install-local kits/knowledge --dest /path/to/workspace
+npx @kontourai/flow-agents kit install kits/knowledge --dest /path/to/workspace
 
 # Run the contract suite against the default adapter
 node --test kits/knowledge/evals/contract-suite/suite.test.js

package/docs/operating-layers.md

@@ -49,7 +49,7 @@ Governance tools such as Veritas belong at the Evidence boundary. Flow Agents sh
 
 ## Flow Kit Coordination
 
-Flow owns Flow Definition semantics: gates use typed `expects` entries, Surface requirements use `kind: "surface.claim"`, and project configuration owns trusted producer mappings plus gate overrides. Flow Agents should author, install, adapt, and control those assets for local runtimes; it should not become the authority source for claim trust or override semantics.
+Flow owns Flow Definition semantics: gates use typed `expects` entries, Surface requirements use `kind: "trust.bundle"` (the Hachure-aligned gate kind), and project configuration owns trusted producer mappings plus gate overrides. Flow Agents should author, install, adapt, and control those assets for local runtimes; it should not become the authority source for claim trust or override semantics.
 
 The Kit Catalog is the Flow Agents index of installable Flow Kits. A Flow Kit can contain Flow Definitions, skills, docs, adapters, and evals, but the catalog points at those assets instead of defining gate behavior itself. Builder Kit is the first Kontour-authored kit and proves the path from shaping through build, verification, merge readiness, and learning.
 
@@ -65,7 +65,7 @@ Builder Kit vocabulary should be used in public and internal guidance:
 - Builder Kit: the coding/building kit shipped by this repo.
 - Probe: question-driven design and context challenge step, surfaced as `design-probe`.
 
-Builder Kit evidence gates can reference Surface trust state without naming a provider. A trust-backed gate may attach a TrustReport or Trust Snapshot ref for the relevant Surface claim, while Flow keeps authority over gate evaluation, trusted producer mapping, and route-back behavior. Surface remains the portable trust-state layer, and Veritas remains an optional producer rather than a required Builder Kit dependency.
+Builder Kit evidence gates can reference Surface trust state without naming a provider. A trust-backed gate may attach a Hachure trust.bundle ref for the relevant Surface claim, while Flow keeps authority over gate evaluation, trusted producer mapping, and route-back behavior. Surface remains the portable trust-state layer, and Veritas remains an optional producer rather than a required Builder Kit dependency.
 
 ## Placement Rules
 

package/docs/spec/runtime-hook-surface.md

@@ -490,7 +490,7 @@ Kit flow activation for Strands workspaces is implemented as a new runtime adapt
 The CLI command is:
 
 ```bash
-flow-kit activate --adapter strands-local [--dest DIR] [--source-root DIR]
+flow-agents kit activate --adapter strands-local [--dest DIR] [--source-root DIR]
 ```
 
 This writes activated flow files to `.flow-agents/runtime/strands/flows/<kit-id>/<asset-id>.flow.json` and produces a parity-diagnostic `activation.json` (same schema as codex-local: `schema_version`, `adapter`, `supported_asset_classes`, `generated_runtime_files`, `skipped_assets`, `warnings`, `errors`).

package/docs/veritas-integration.md

@@ -106,9 +106,9 @@ If Veritas is unavailable and the workflow expected it, record `not_verified` in
 
 ## Builder Kit Trust Evidence
 
-Builder Kit gates stay provider-neutral. The Builder Kit Flow Definition names gate expectations as `kind: "surface.claim"` and declares the claim type, subject, accepted statuses, and blocking behavior. It does not name Veritas or any other trust producer.
+Builder Kit gates stay provider-neutral. The Builder Kit Flow Definition names gate expectations as `kind: "trust.bundle"` (the Hachure-aligned gate kind) and declares the claim type, subject, accepted statuses, and blocking behavior. It does not name Veritas or any other trust producer.
 
-When a trust-backed path is configured, Flow Agents may attach a compact Surface-shaped reference to the Builder Kit evidence gate. The reference points at a TrustReport or Trust Snapshot, carries the related gate id, Surface claim type, claim status, artifact ref, integrity summary, authority or trusted-producer summary, subject, and freshness state, and then maps to the normal Flow gate result. Flow owns the gate authority decision, route reason, trusted producer mapping, and accepted gap behavior. Surface owns the portable trust state represented by the Surface claim and the TrustReport / Trust Snapshot. A Probe can request or clarify the evidence needed before planning or before a later Builder Kit gate retries.
+When a trust-backed path is configured, Flow Agents may attach a compact Hachure trust.bundle reference to the Builder Kit evidence gate. The reference uses `artifact_kind: "trust.bundle"` (the Hachure-aligned canonical value), carries the related gate id, domain claim type, claim status, artifact ref, integrity summary, authority or trusted-producer summary, subject, and freshness state, and then maps to the normal Flow gate result. When the `hachure` optional dependency is installed, referenced artifacts are validated against hachure's trust-bundle.schema.json at evidence-recording time. Flow owns the gate authority decision, route reason, trusted producer mapping, and accepted gap behavior. Surface owns the portable trust state represented by the Surface claim and the TrustReport / Trust Snapshot. A Probe can request or clarify the evidence needed before planning or before a later Builder Kit gate retries.
 
 Veritas is only one optional producer of those artifacts. A local Veritas readiness run can emit native Veritas evidence and, when configured, point Flow Agents at a Surface-shaped TrustReport or Trust Snapshot. Flow Agents records the reference; it does not copy Veritas rule models, readiness semantics, or provider-native fields into Builder Kit gates.
 
@@ -116,8 +116,8 @@ Provider and artifact absence are explicit:
 
 - If no trust provider is configured, ordinary Builder Kit activation, planning, verification, and evidence gates continue to work through the existing Flow Kit path.
 - If a trust-backed path was requested but no provider is configured, the trust check records `not_verified` with a clear gap instead of blocking unrelated Builder Kit usage.
-- If a provider is configured but the expected TrustReport or Trust Snapshot is absent or unreadable, only the requested trust-backed evidence check records `not_verified`; it does not silently pass and it does not make Veritas mandatory.
-- If a TrustReport or Trust Snapshot is present but has a rejected, stale, expired, missing-authority, or integrity-mismatched Surface claim, the Builder Kit evidence gate routes through the normal `fail` or `not_verified` path.
+- If a provider is configured but the expected Hachure trust.bundle artifact is absent or unreadable, only the requested trust-backed evidence check records `not_verified`; it does not silently pass and it does not make Veritas mandatory.
+- If a Hachure trust.bundle artifact is present but has a rejected, stale, expired, missing-authority, or integrity-mismatched claim, the Builder Kit evidence gate routes through the normal `fail` or `not_verified` path.
 
 ## Adoption Gate
 

package/docs/vision.md

@@ -20,7 +20,7 @@ One official framework adapter spike exists: `integrations/strands/` is a Python
 
 ### What ships today
 
-Kit authoring is shipped. The `kit.json` contract at schema version 1.0 is validated by the `flow-kit` CLI before any install. The [Kit Authoring Guide](kit-authoring-guide.html) walks from an empty directory to a validated, locally installed kit. Two reference kits ship in `kits/`:
+Kit authoring is shipped. The `kit.json` contract at schema version 1.0 is validated by the `flow-agents kit` CLI before any install. The [Kit Authoring Guide](kit-authoring-guide.html) walks from an empty directory to a validated, locally installed kit. Two reference kits ship in `kits/`:
 
 **Builder Kit** packages the full `idea → backlog → plan → build → review → verify → evidence → release → learning` pipeline as two flows (`builder.shape`, `builder.build`). It installs automatically.
 

package/docs/workflow-eval-strategy.md

@@ -6,7 +6,7 @@ title: Workflow Eval Strategy
 
 The Builder Kit workflow system now has concrete skill contracts for `idea-to-backlog`, `pull-work`, `plan-work`, `review-work`, `deliver`, `evidence-gate`, `release-readiness`, and `learning-review`, plus shared workflow contracts in `context/contracts/`. Evals should prove both the written contracts and the agent behavior around gates, artifacts, worktrees, Goal Fit, release readiness, final acceptance docs, and learning feedback.
 
-Flow Agents evals prove coordination, install, runtime adapter behavior, and artifact discipline. They should not redefine Flow gate authority: Flow Definitions use typed `expects` entries, Surface claim gates use `kind: "surface.claim"`, and Flow project config owns trusted producer mappings plus gate overrides.
+Flow Agents evals prove coordination, install, runtime adapter behavior, and artifact discipline. They should not redefine Flow gate authority: Flow Definitions use typed `expects` entries, trust-bundle gates use `kind: "trust.bundle"`, and Flow project config owns trusted producer mappings plus gate overrides.
 
 ## Goals
 
@@ -161,7 +161,7 @@ Surface trust artifact attachment is covered by deterministic schema, runtime, a
 bash evals/integration/test_workflow_sidecar_writer.sh
 ```
 
-That eval exercises Builder Kit `surface.claim` evidence using provider-neutral TrustReport / Trust Snapshot fixtures for accepted, rejected, stale, missing-authority, integrity-mismatch, provider-absent, and artifact-absent cases. It proves Flow Agents can record compact Surface claim evidence in `evidence.json` and report pass, fail, or `NOT_VERIFIED` gaps without requiring provider-specific fields.
+That eval exercises Builder Kit `trust.bundle` evidence using provider-neutral Hachure trust.bundle fixtures for accepted, rejected, stale, missing-authority, integrity-mismatch, provider-absent, and artifact-absent cases. It proves Flow Agents can record compact Surface claim evidence in `evidence.json` and report pass, fail, or `NOT_VERIFIED` gaps without requiring provider-specific fields.
 
 This coverage does not redefine Flow gate authority. Flow Definitions continue to express expectations, Flow project config owns trusted producer mappings and gate overrides, and Flow gate authority remains outside the local report writer. Runtime/provider gaps should be recorded as `NOT_VERIFIED` when a configured Surface claim path cannot be checked; ordinary Builder Kit workflows remain valid when no trust provider or trust artifact is configured.
 

package/docs/workflow-usage-guide.md

@@ -6,7 +6,7 @@ title: Workflow Usage Guide
 
 This guide shows how to use the Builder Kit workflow skills in normal chats.
 
-> **Which doc do I want?** This page is the *driver's manual* — what to say at each stage and what should happen. If you want the conceptual map first — layers, sidecars, hooks, evidence, and why the system is shaped this way — read the [Agent System Guidebook](agent-system-guidebook.md). For a one-line summary of every skill and gate, use the [Skills Map](skills-map.md). Flow Agents coordinates the local runtime, installs Flow Kits, and records artifacts; Flow owns gate semantics, including typed `expects` entries with `kind: "surface.claim"`, trusted producer config, and gate overrides.
+> **Which doc do I want?** This page is the *driver's manual* — what to say at each stage and what should happen. If you want the conceptual map first — layers, sidecars, hooks, evidence, and why the system is shaped this way — read the [Agent System Guidebook](agent-system-guidebook.md). For a one-line summary of every skill and gate, use the [Skills Map](skills-map.md). Flow Agents coordinates the local runtime, installs Flow Kits, and records artifacts; Flow owns gate semantics, including typed `expects` entries with `kind: "trust.bundle"`, trusted producer config, and gate overrides.
 
 The core pattern is:
 
@@ -43,7 +43,7 @@ Separate these into distinct ideas, use Probe/alignment questions if the outcome
 
 Expected behavior:
 
-- delegate shaping to `skills/idea-to-backlog/SKILL.md`
+- delegate shaping to `kits/builder/skills/idea-to-backlog/SKILL.md`
 - link the artifact to the Builder Kit Flow Definition at `kits/builder/flows/shape.flow.json`
 - inventory each distinct idea separately
 - classify each idea

package/evals/acceptance/test_opencode_harness.sh

@@ -21,7 +21,7 @@ wait_for_telemetry() {
   local file="$1"
   local i=0
   while [[ $i -lt 150 ]]; do
-    [[ -s "$file" ]] && return 0
+    if [[ -s "$file" ]] && grep -q '"tool.invoke"' "$file" 2>/dev/null && grep -q '"tool.result"' "$file" 2>/dev/null; then return 0; fi
     sleep 0.1
     i=$((i + 1))
   done
@@ -73,23 +73,31 @@ for _attempt in 1 2; do
   grep -q '"tool.invoke"' "$TMP_WORK/.telemetry/full.jsonl" 2>/dev/null && break
 done
 
-LATEST_LOG="$(ls -t ~/.local/share/opencode/log/*.log 2>/dev/null | head -1 || true)"
-if [[ -n "$LATEST_LOG" ]] && grep -q "plugins/flow-agents.js loading plugin" "$LATEST_LOG" 2>/dev/null; then
-  _pass "opencode log confirms flow-agents plugin loaded"
+# Confirm load via the plugin's own marker file (written by the FlowAgentsPlugin
+# factory at startup). This replaces grepping opencode's internal
+# "plugins/flow-agents.js loading plugin" message, which opencode 1.17.x dropped
+# and which opencode does not reliably surface to its log file — a stale-assertion
+# false failure (#75). The factory runs regardless of provider, so this load
+# signal is independent of whether a model turn completes.
+if [[ -f "$TMP_WORK/.telemetry/opencode-plugin.loaded" ]]; then
+  _pass "flow-agents plugin loaded (factory marker present)"
 else
-  _fail "opencode log did not confirm flow-agents plugin loaded"
+  _fail "flow-agents plugin did not load (factory marker absent)"
 fi
 
 telemetry_file="$TMP_WORK/.telemetry/full.jsonl"
 if [[ "$provider_error" -eq 1 ]]; then
   _skip "opencode telemetry assertions skipped (provider/auth error)"
   _skip "opencode telemetry tool events skipped (provider/auth error)"
+elif ! wait_for_telemetry "$telemetry_file"; then
+  # No telemetry was produced at all — the agent never completed a model turn,
+  # expected in a provider-less environment (e.g. CI with no API key). The binary
+  # install, bundle, and mechanical hook chain are already covered; skip the
+  # live-model-dependent telemetry assertions rather than fail on them.
+  _skip "opencode telemetry assertions skipped (no telemetry — agent did not complete a turn, likely no provider)"
+  _skip "opencode telemetry tool events skipped (no turn)"
 else
-  if wait_for_telemetry "$telemetry_file"; then
-    _pass "opencode telemetry log was written"
-  else
-    _fail "opencode telemetry log was not written"
-  fi
+  _pass "opencode telemetry log was written"
 
   if [[ -f "$telemetry_file" ]] && \
     node -e "