@kontourai/flow-agents 4.0.0 → 4.2.0

package/dist/kiro/docs/architecture-engine-and-kits.md

@@ -102,9 +102,26 @@ Kit trust is orthogonal to engine privilege. A marketplace may call a kit offici
 
 The answer is determined by validation, activation, and gate evidence, not by a privileged kit list.
 
+## The Portfolio Layer Doctrine
+
+The engine/kits split here is Flow Agents' instance of the portfolio-wide **Layer Doctrine**
+([surface/docs/architecture/portfolio-layer-doctrine.md](https://github.com/kontourai/surface/blob/main/docs/architecture/portfolio-layer-doctrine.md)):
+dependency direction is one-way up the stack (open trust format → building-block tools → Surface →
+products), and no layer reaches sideways into a peer. A product engine (e.g. `@kontourai/veritas`)
+never depends on the platform, and a **kit consumes an engine only through its CLI + recorded
+artifacts, never as an npm library import** — the whole point of the manifest/catalog model above.
+Both edges are now enforced executably: veritas-side by `check-no-flow-agents-dep.mjs` (the engine
+declares no flow-agents dependency) and here by [`scripts/check-layer-boundary.mjs`](../scripts/check-layer-boundary.mjs)
+(no kit imports the veritas engine as a library). See veritas's
+[Engine / Surface Seam](https://github.com/kontourai/veritas/blob/main/docs/architecture/engine-surface-seam.md)
+for the canonical engine-vs-kit capability inventory that the Veritas Governance Kit row above
+builds on.
+
 ## Related docs
 
 - [Flow Kit Authoring Guide](kit-authoring-guide.md)
 - [Flow Kit Repository Contract](flow-kit-repository-contract.md)
 - [Runtime Hook Surface spec](spec/runtime-hook-surface.md)
 - [Verifiable Trust](verifiable-trust.md)
+- [Veritas Engine / Surface Seam](https://github.com/kontourai/veritas/blob/main/docs/architecture/engine-surface-seam.md) — how `@kontourai/veritas` splits into an engine library + the kit-owned product surface
+- [Portfolio Layer Doctrine](https://github.com/kontourai/surface/blob/main/docs/architecture/portfolio-layer-doctrine.md)

package/dist/kiro/docs/context-map.md

@@ -71,6 +71,7 @@ Machine-readable workflow state lives beside Markdown artifacts in `.kontourai/f
 | workflow-learning.schema.json | Flow Agents Workflow Learning | https://flow-agents.dev/schemas/workflow-learning.schema.json |
 | workflow-release.schema.json | Flow Agents Workflow Release Readiness | https://flow-agents.dev/schemas/workflow-release.schema.json |
 | workflow-state.schema.json | Flow Agents Workflow State | https://flow-agents.dev/schemas/workflow-state.schema.json |
+| workflow-waves.schema.json | Flow Agents Workflow Waves | https://flow-agents.dev/schemas/workflow-waves.schema.json |
 
 Primary tools: public `flow-agents workflow`, `trust.bundle`, artifact validation, `scripts/hooks/stop-goal-fit.js`, and `scripts/hooks/workflow-steering.js`. The package-internal writer is not an agent or consumer interface.
 
@@ -100,6 +101,7 @@ Primary tools: public `flow-agents workflow`, `trust.bundle`, artifact validatio
 | agentic-engineering | skills/agentic-engineering/SKILL.md | Eval-first execution, task decomposition, and cost-aware model routing for AI-driven development workflows. |
 | browser-test | skills/browser-test/SKILL.md | Headless browser automation via Playwright — screenshots, accessibility checks, form filling, UI testing, DOM inspection. |
 | builder-shape | kits/builder/skills/builder-shape/SKILL.md | Builder Kit shaping entrypoint. Turns a raw idea into a provider-neutral, reviewable backlog proposal and stops before build selection unless the user explicitly continues. |
+| consult-standards | kits/veritas-governance/skills/consult-standards/SKILL.md | Get just-in-time Veritas governance guidance for a file or work area before editing it: run `veritas explain --file <path>` (or `--work-area <id>`) to see the governance excerpt, the Repo Standards rules that apply, their do/don't/exampl... |
 | dependency-update | skills/dependency-update/SKILL.md | Analyze and upgrade project dependencies — latest versions, security vulnerabilities, actionable update plan across all package managers. |
 | design-probe | kits/builder/skills/design-probe/SKILL.md | Generic one-question-at-a-time design probe for turning unclear goals, designs, and handoffs into shared understanding. |
 | eval-rebuild | skills/eval-rebuild/SKILL.md | Project-specific build and install commands for the eval feedback loop. Injected into eval-builder agent. Replace this skill for different build systems. |
@@ -108,6 +110,7 @@ Primary tools: public `flow-agents workflow`, `trust.bundle`, artifact validatio
 | knowledge-capture | kits/knowledge/skills/knowledge-capture/SKILL.md | Save durable knowledge, lightweight pointers, user corrections, decisions, lessons, relationship context, or source references into the knowledge base. Use when the user says save, remember, capture, file this, bookmark context, or when... |
 | pickup-probe | kits/builder/skills/pickup-probe/SKILL.md | Provider-grounded pickup probe used at the Builder design-probe step before planning. |
 | search-first | skills/search-first/SKILL.md | Research-before-coding workflow. Search for existing tools, libraries, and patterns before writing custom code. |
+| standards-authoring | kits/veritas-governance/skills/standards-authoring/SKILL.md | Author or update a repo's Veritas Repo Standards through the kit's standards-authoring flow: run `veritas init --explore`/`--guided` to derive a proposed starter set (project name, repo-shape-adaptive Repo Map nodes, evidence-check infer... |
 
 ## Agents
 

package/dist/kiro/docs/decisions/backlog-readiness-source.md

@@ -0,0 +1,89 @@
+---
+status: current
+subject: Backlog Readiness Source
+decided: 2026-07-16
+evidence:
+  - kind: issue
+    ref: https://github.com/kontourai/flow-agents/issues/441
+  - kind: pr
+    ref: https://github.com/kontourai/flow-agents/pull/449
+  - kind: commit
+    ref: c19c3e64a214be7d5b2585004fd3c4f2597781e5
+  - kind: url
+    ref: https://claude.ai/code/session_01SmQYjiUo1aDSXgEKyiye7M
+---
+
+# Backlog Readiness Source
+
+Which signal marks a Work Item intentionally ready for pickup, and what
+`pull-work` is allowed to do when that signal yields nothing.
+
+## Decision
+
+- **The org project board is the readiness source.** The configured
+  BoardProvider — org GitHub Project `kontourai/1` ("Flow Agents Builder
+  Platform") — carries readiness as board Status. `ready_statuses=["ready"]`
+  is the pickup filter; the board's `Priority` field ranks the cross-repo
+  ready queue.
+- **Triage is the automated intake status.** Every new `kontourai/*` issue is
+  added to the board with Status=Triage by the shared reusable workflow
+  (`kontourai/.github` `add-issue-to-project.yml`, called per-repo from
+  `.github/workflows/add-to-project.yml`); closing an issue moves it to Done.
+  Nothing reaches Ready automatically.
+- **The Triage → Ready move is the intentionality act.** Moving an item to
+  Ready (and setting Priority) is the triage responsibility that makes work
+  eligible for agent pickup. This is a deliberate human/triage-pass decision,
+  not automation.
+- **A configured readiness source that yields nothing is a surfaced warning,
+  never a silent fallback.** The board reader emits `zero_ready_items` when
+  the configured board produces an empty ready queue (landed with PR #449),
+  and the issue-listing path emits `board_provider_bypassed` whenever a
+  BoardProvider is configured but issue-level listing is used instead.
+  `pull-work` must carry these warnings into its artifact and route to
+  triage/intake rather than silently substituting unranked issue listing.
+- The settings contract declares the real board taxonomy: the schema's
+  `exclude_statuses` vocabulary includes `triage`, and this repo's settings
+  exclude `triage` explicitly. `verification` remains in the schema vocabulary
+  for provider-neutral shapes even though this board has no such column.
+
+## Evidence basis (re-verified live, 2026-07-16)
+
+Issue #441 was shaped on 2026-07-06 evidence that the board was dead (15
+items, all Done, no automation). That premise is now false:
+
+- The kontourai org has exactly **one** ProjectV2: `kontourai/1`, open, **468
+  items** (306 Triage / 14 Ready / 148 Done) spanning 13 repos; 169 of 171
+  open flow-agents issues are on it.
+- The auto-add workflow targets exactly this project
+  (`PVT_kwDOEJYCKs4BYzgP`), Status field options: Triage, Ready, In Progress,
+  Blocked, Review, Done.
+- A live board-driven `pull-work` read returns a **14-item priority-ranked
+  cross-repo ready queue** with zero warnings and zero intake gaps.
+- The agent-path `gh` token carries the `project` scope, so the read:project
+  friction recorded in #441 no longer holds.
+
+## Rejected alternative
+
+**Label-based readiness (per-repo `ready`/`blocked`/`in-progress` labels).**
+Recommended by #441 when the board was dead, because it needed no board
+maintenance and no extra token scope. Both advantages evaporated once the
+auto-add automation went live org-wide and the agent token gained `project`
+scope — and labels cannot express cross-repo priority ranking without
+inventing a parallel convention per repo. Revisit trigger: if the auto-add
+workflow or `project` token scope regresses for agent environments, reopen
+this subject rather than quietly re-deriving readiness from labels.
+
+## Follow-ups (owned elsewhere, not absorbed here)
+
+- **One-time triage sweep** of the ~306 Triage items (and any open issues
+  missing from the board) to assign Ready/Priority intentionally — owned by
+  the triage pass in #443 item 2. Not executed with this decision: the Ready
+  set was already non-empty (14 items), and bulk-moving 300+ items without
+  the accepted mechanism would manufacture fake intentionality.
+- **Board maintenance as flow responsibility** (intake adds, claim → In
+  Progress, completion Done assertion): #443.
+- **Doctor board-health checks** (configured-but-unfed board, dead readiness
+  source, missing token scope): #443 item 5 / #321. Until that surface
+  exists, the warnings live in `pull-work` provider output and the
+  `pull-work` skill contract only.
+- **Workspace-scoped pull-work** across multiple repos: #444.

package/dist/kiro/docs/decisions/index.md

@@ -12,6 +12,7 @@ Numbered ADRs under `docs/adr/` are frozen history and are not listed here.
 | --- | --- | --- |
 | [agent-coordination](./agent-coordination.md) | current | Agent coordination |
 | [anti-gaming-trust-security](./anti-gaming-trust-security.md) | needs-decision | Anti-gaming trust security |
+| [backlog-readiness-source](./backlog-readiness-source.md) | current | Backlog Readiness Source |
 | [context-lifecycle](./context-lifecycle.md) | needs-decision | Context lifecycle |
 | [core-domain-kit-boundary](./core-domain-kit-boundary.md) | needs-decision | Core vs domain kit boundary |
 | [decision-records](./decision-records.md) | current | Decision records |

package/dist/kiro/docs/developer-architecture.md

@@ -22,7 +22,7 @@ Use these local references when you need more detail:
 - [ADR 0005](adr/0005-kubernetes-inspired-resource-contracts.md) records the Kontour Resource Contract direction.
 - [Kontour Resource Contract](kontour-resource-contract.md) documents the shared durable record shape.
 - [Flow Kit Repository Contract](flow-kit-repository-contract.md) documents local kit validation and activation boundaries.
-- [Veritas Integration Boundary](veritas-integration.md) documents optional governance evidence.
+- [Veritas Integration Boundary](veritas-integration.md) records the early integration rationale; the shipped path is the **Veritas Governance Kit** (`kits/veritas-governance`) — see its [README](../kits/veritas-governance/docs/README.md) and [Engine and kits](architecture-engine-and-kits.md).
 
 ## Coordination Map
 
@@ -63,10 +63,10 @@ flowchart LR
 | Flow Agents | Agent-facing workflow bundles, skills, sidecars, artifact contracts, evals, runtime export, provider wiring, and local-first docs. | Does not become the core workflow engine for all Kontour products and should not copy product-native rule models into this repo. |
 | Flow | Generic workflow semantics, Flow Definitions, gate transitions, attempts, route-back behavior, Flow Runs, and Flow Reports. | Flow Agents may consume or project Flow concepts, but Flow owns enforcement semantics once the Flow surface is available. |
 | Builder Kit | The first Kontour-authored Flow Kit for build work: shaping, pickup probes, planning, execution, review, verification, publication, release readiness, and learning workflows. | Flow Agents validates, installs, activates, and routes Builder Kit assets; it does not make every Builder Kit specialization a core Flow Agents concept. |
-| Veritas | Repo-local standards, authority settings, policy/rule checks, and native governance reports. | Flow Agents records compact Veritas evidence references when configured; Veritas is optional and not a mandatory dependency for every workflow. |
+| Veritas | The repo-local governance **evaluation engine** (`@kontourai/veritas`): repo standards, authority settings, policy/rule checks, merge-readiness, and native governance reports. | Flow Agents ships the **Veritas Governance Kit** (`kits/veritas-governance`), which owns the repo-installed governance surface (standards scaffold, hooks, authoring, agent guidance) and gates a real `veritas readiness` verdict as a `software-readiness-verdict` trust.bundle claim — wrapping the engine's CLI, never importing or reimplementing it. The kit is optional; the engine it wraps is a standalone library. |
 | Surface | Portable trust state, claims, TrustReports, Trust Snapshots, and user-facing trust surfaces. | Flow Agents can reference Surface-shaped claims for gates, but Surface owns claim models and trust presentation. |
 
-**Current state:** Builder Kit is the first proof point for extracting out-of-the-box behavior into normal Flow Kits. Veritas integration is documented as optional and adapter-driven. Surface references appear as a trust-state boundary in local Veritas and Builder Kit evidence docs.
+**Current state:** Builder Kit is the first proof point for extracting out-of-the-box behavior into normal Flow Kits. Veritas is consumed through the **Veritas Governance Kit** (`kits/veritas-governance`) — an agentless kit that wraps the `veritas` CLI and projects its recorded readiness verdict into a trust.bundle gate; it owns the repo-installed governance surface, while veritas stays the standalone evaluation engine. Surface references appear as a trust-state boundary in local Veritas and Builder Kit evidence docs.
 
 **Future direction:** Flow Agents should support more runtime adapters, provider adapters, and Flow Kits without forcing all users to install Builder Kit, Veritas, Surface, or a specific hosted provider.
 

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

@@ -72,7 +72,7 @@ codex-local
 
 Unknown adapter ids fail with JSON diagnostics that include the available adapters. No Claude, Kiro, framework, API, npm module extraction, or remote install adapters are implemented by this activation surface.
 
-The `codex-local` adapter supports only Flow Definition assets declared in `flows`. It activates the built-in Builder Kit Flow Definitions, including `builder.shape` and `builder.build`, plus Flow Definitions from locally installed kit copies under:
+The `codex-local` adapter supports assets declared in `flows`, `skills`, and `docs`. It activates the built-in Builder Kit Flow Definitions, including `builder.shape` and `builder.build`, plus supported assets from locally installed kit copies under:
 
 ```text
 <dest>/kits/local/repositories/<kit-id>/
@@ -91,13 +91,13 @@ Flow Definition copies are placed under `flows/<kit-id>/<flow-id>.flow.json`, an
 The stable activation diagnostics include:
 
 - `selected_adapter`: selected adapter id, currently `codex-local`.
-- `supported_asset_classes`: asset classes the selected adapter activates, currently `["flows"]`.
+- `supported_asset_classes`: asset classes the selected adapter activates, currently `["flows", "skills", "docs"]`.
 - `generated_runtime_files`: generated runtime-local files with asset class, path, kit id, asset id, and source path.
 - `skipped_assets`: unsupported declared assets with asset class, path, kit id, asset id when present, and reason.
 - `warnings`: recoverable catalog, registry, or asset discovery problems.
 - `errors`: blocking discovery or activation problems.
 
-Declared `skills`, `docs`, `adapters`, `evals`, and generic `assets` are diagnostic-only for this adapter. They are skipped with explicit `skipped_assets` entries; they are not copied, installed, invoked, or treated as active runtime behavior.
+Declared `skills` and `docs` are copied into the runtime projection alongside flows. Declared `adapters`, `evals`, generic `assets`, and `provisions` are diagnostic-only for this adapter. They are skipped with explicit `skipped_assets` entries; they are not copied, installed, invoked, or treated as active runtime behavior.
 
 ## Root Manifest
 
@@ -122,6 +122,14 @@ Declared `skills`, `docs`, `adapters`, `evals`, and generic `assets` are diagnos
       "id": "example.readme",
       "path": "docs/README.md"
     }
+  ],
+  "provisions": [
+    {
+      "id": "example-kit.editor-policy",
+      "path": "provisions/editor-policy.json",
+      "target": ".editor/policy.json",
+      "description": "Initial repository policy."
+    }
   ]
 }
 ```
@@ -138,6 +146,29 @@ Optional fields:
 - `product_name`: non-empty display name when the product name differs from `name`.
 - `description`: non-empty summary.
 - `skills`, `docs`, `adapters`, `evals`, `assets`: lists of relative asset paths or objects with `id`, `path`, and optional `description`.
+- `provisions`: a list of objects with kit-id-prefixed `id`, source `path`, consumer-repository-relative `target`, and optional `description`.
+
+## Repository Provisioning
+
+Provision entries declare inert files; kits do not execute installer code. Source paths follow the other extension-asset rules: they must be relative, stay inside the kit directory, and name an existing regular file. Targets must be non-empty relative paths, must not contain traversal segments or resolve outside the consumer repository, must not be inside `.git`, and must be unique after normalization.
+
+Provision a catalog kit, an installed-registry kit, or a kit at a direct local path with:
+
+```bash
+flow-agents kit provision <kit-id-or-path> [--target <consumer-repo>] [--force] [--dry-run]
+```
+
+`--target` defaults to the current working directory and must already be a directory. The engine resolves the real path of the deepest existing destination ancestor before writing, so a symlink cannot redirect a provision outside the target repository. It preflights the whole declaration: by default, any existing destination reports every conflict, exits nonzero, and writes none of the provisioned files. `--force` replaces declared destination files. `--dry-run` prints every source-to-target mapping and writes nothing.
+
+After a successful non-dry-run copy, Flow Agents writes or replaces this bookkeeping manifest:
+
+```text
+<target>/.kontourai/flow-agents/provisions/<kit-id>.json
+```
+
+The schema is `{ schema_version: "1.0", kit_id, kit_hash, provisioned_at, files: [{ id, target }] }`. Provisioned files become consumer-repository content; uninstalling or deactivating the kit does not remove them.
+
+When `flow-agents init --activate-kit <id>` successfully activates a selected kit, init invokes the same provisioning engine against its destination with create-only semantics. Existing destinations are reported as skipped warnings and do not fail an init rerun. Provisions never enter the runtime projection directory.
 
 ## Path Rules
 

package/dist/kiro/docs/kit-authoring-guide.md

@@ -54,7 +54,7 @@ Required fields:
 | `name` | Non-empty display name |
 | `flows` | Non-empty list; each entry must have `id` and `path` |
 
-Optional fields: `product_name`, `description`, `skills`, `docs`, `adapters`, `evals`, `assets`, `dependencies` (cross-kit dependency declarations; see [Cross-kit dependencies](#cross-kit-dependencies)), `workflow_triggers` (structured workflow steering keyed by engine trigger names such as `implementation-work-detected`), `hook_influence_expectations` (kit-owned required hook-influence fixture expectations), and `first_party` (legacy catalog/marketplace metadata; no runtime privilege). Optional asset fields list relative asset paths or objects with `id`, `path`, and optional `description`. `skills` and `docs` assets are activated by both adapters alongside flows. `adapters`, `evals`, and `assets` appear in diagnostics as `skipped_assets` (see the Activate section for the full per-adapter table).
+Optional fields: `product_name`, `description`, `skills`, `docs`, `adapters`, `evals`, `assets`, `dependencies` (cross-kit dependency declarations; see [Cross-kit dependencies](#cross-kit-dependencies)), `workflow_triggers` (structured workflow steering keyed by engine trigger names such as `implementation-work-detected`), `hook_influence_expectations` (kit-owned required hook-influence fixture expectations), `agent_spawn_triggers` (perimeter trigger surfaces that spawn agent runs plus their dedup/cooldown/cap/concurrency guard config; validation warns when a spawning surface lacks complete guards — see `context/contracts/trigger-guards.md`), and `first_party` (legacy catalog/marketplace metadata; no runtime privilege). Optional asset fields list relative asset paths or objects with `id`, `path`, and optional `description`. `skills` and `docs` assets are activated by both adapters alongside flows. `adapters`, `evals`, and `assets` appear in diagnostics as `skipped_assets` (see the Activate section for the full per-adapter table).
 
 ## Minimal flow file
 

package/dist/kiro/docs/veritas-integration.md

@@ -4,6 +4,18 @@ title: Veritas Integration Boundary
 
 # Veritas Integration Boundary
 
+> **Superseded by the shipped kit.** This doc records the early rationale for how Flow Agents
+> should integrate Veritas. That decision has since been made and shipped as the **Veritas
+> Governance Kit** (`kits/veritas-governance`): an agentless kit that wraps the `veritas` CLI and
+> projects its recorded readiness verdict into a `software-readiness-verdict` trust.bundle gate,
+> and that owns the repo-installed governance surface (standards scaffold, hooks, standards
+> authoring, just-in-time agent guidance). For the current integration, read the
+> [kit README](../kits/veritas-governance/docs/README.md), [Engine and kits](architecture-engine-and-kits.md),
+> and veritas's [Engine / Surface Seam](https://github.com/kontourai/veritas/blob/main/docs/architecture/engine-surface-seam.md).
+> The boundary principle below still holds — Veritas is the evaluation engine; the kit wraps it,
+> never reimplements it — but the concrete adapter shape described here predates and is replaced by
+> the kit's flows + trust.bundle adapter.
+
 Veritas is a strong fit for Flow Agents' development evidence and governance layer, but it should stay optional and adapter-driven.
 
 The guiding rule is simple: Flow owns generic process enforcement, Flow Agents projects Flow-backed workflows into agent harnesses, and Veritas owns repo-local standards, authority, and evidence-check semantics.

package/dist/kiro/evals/ci/run-baseline.sh

@@ -11,6 +11,7 @@ mkdir -p "$LOG_DIR"
 
 CHECKS=(
   "Content boundary|npm run check:content-boundary --"
+  "Layer boundary|npm run check:layer-boundary --"
   "Hachure boundary|npm run check:hachure-boundary --"
   "Decision registry|npm run check:decisions --"
   "Source tree validation|npm run validate:source --"
@@ -52,6 +53,7 @@ CHECKS=(
   "Workflow steering hook integration|bash evals/integration/test_workflow_steering_hook.sh"
   "Hook influence contract integration|bash evals/integration/test_hook_influence_cases.sh"
   "Flow Kit repository integration|bash evals/integration/test_flow_kit_repository.sh"
+  "Kit provisioning integration|bash evals/integration/test_kit_provisioning.sh"
   "Runtime adapter activation integration|bash evals/integration/test_runtime_adapter_activation.sh"
   "Bundle install integration|bash evals/integration/test_bundle_install.sh"
   "Published Codex install integration|bash evals/integration/test_published_codex_install.sh"
@@ -119,6 +121,7 @@ CHECKS=(
 
 LANE_SOURCE_AND_STATIC=(
   "Content boundary"
+  "Layer boundary"
   "Hachure boundary"
   "Decision registry"
   "Source tree validation"
@@ -169,6 +172,7 @@ LANE_RUNTIME_AND_KIT=(
   "Workflow steering hook integration"
   "Hook influence contract integration"
   "Flow Kit repository integration"
+  "Kit provisioning integration"
   "Runtime adapter activation integration"
   "Bundle install integration"
   "Published Codex install integration"

package/dist/kiro/evals/integration/test_kit_provisioning.sh

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+source "$ROOT/evals/lib/node.sh"
+
+errors=0
+TMP_DIR="$(mktemp -d)"
+trap 'rm -rf "$TMP_DIR"' EXIT
+pass() { echo "  ✓ $1"; }
+fail() { echo "  ✗ $1"; errors=$((errors + 1)); }
+
+CLI="$ROOT/build/src/cli.js"
+KIT="$TMP_DIR/fixture-kit"
+mkdir -p "$KIT/flows" "$KIT/payload"
+cp "$ROOT/kits/release-evidence/flows/release-evidence.flow.json" "$KIT/flows/review.flow.json"
+printf 'alpha from kit\n' >"$KIT/payload/alpha.txt"
+printf 'beta from kit\n' >"$KIT/payload/beta.txt"
+cat >"$KIT/kit.json" <<'JSON'
+{
+  "schema_version": "1.0",
+  "id": "fixture-kit",
+  "name": "Provision Fixture Kit",
+  "flows": [{"id":"release-evidence","path":"flows/review.flow.json"}],
+  "provisions": [
+    {"id":"fixture-kit.alpha","path":"payload/alpha.txt","target":"docs/alpha.txt"},
+    {"id":"fixture-kit.beta","path":"payload/beta.txt","target":"config/beta.txt","description":"fixture"}
+  ]
+}
+JSON
+
+echo "=== Kit provisioning integration ==="
+npm run build --silent >/dev/null || { fail "build failed"; exit 1; }
+
+if node "$CLI" kit validate "$KIT" >"$TMP_DIR/validate.out" 2>&1; then
+  pass "kit validate accepts declared provisions"
+else
+  fail "kit validate rejected valid provisions"; sed -n '1,80p' "$TMP_DIR/validate.out"
+fi
+
+TARGET="$TMP_DIR/consumer"
+mkdir -p "$TARGET"
+if node "$CLI" kit provision "$KIT" --target "$TARGET" >"$TMP_DIR/provision.out" 2>&1 \
+  && cmp -s "$KIT/payload/alpha.txt" "$TARGET/docs/alpha.txt" \
+  && cmp -s "$KIT/payload/beta.txt" "$TARGET/config/beta.txt" \
+  && node -e 'const m=require(process.argv[1]); if(m.schema_version!=="1.0"||m.kit_id!=="fixture-kit"||m.files.length!==2)process.exit(1)' "$TARGET/.kontourai/flow-agents/provisions/fixture-kit.json"; then
+  pass "provision copies exact content and writes the two-entry manifest"
+else
+  fail "positive provision failed"; sed -n '1,100p' "$TMP_DIR/provision.out"
+fi
+
+printf 'consumer-owned alpha\n' >"$TARGET/docs/alpha.txt"
+printf 'changed source beta\n' >"$KIT/payload/beta.txt"
+if node "$CLI" kit provision "$KIT" --target "$TARGET" >"$TMP_DIR/conflict.out" 2>&1; then
+  fail "create-only conflict unexpectedly succeeded"
+elif [[ "$(cat "$TARGET/docs/alpha.txt")" == "consumer-owned alpha" ]] \
+  && [[ "$(cat "$TARGET/config/beta.txt")" == "beta from kit" ]] \
+  && rg -q 'docs/alpha.txt' "$TMP_DIR/conflict.out" \
+  && rg -q 'config/beta.txt' "$TMP_DIR/conflict.out"; then
+  pass "conflict is nonzero, names all conflicts, and overwrites nothing"
+else
+  fail "conflict handling was not atomic or diagnostic"; sed -n '1,100p' "$TMP_DIR/conflict.out"
+fi
+
+if node "$CLI" kit provision "$KIT" --target "$TARGET" --force >"$TMP_DIR/force.out" 2>&1 \
+  && cmp -s "$KIT/payload/alpha.txt" "$TARGET/docs/alpha.txt" \
+  && cmp -s "$KIT/payload/beta.txt" "$TARGET/config/beta.txt"; then
+  pass "--force overwrites declared destinations"
+else
+  fail "--force did not overwrite"; sed -n '1,100p' "$TMP_DIR/force.out"
+fi
+
+DRY="$TMP_DIR/dry-consumer"
+mkdir -p "$DRY"
+if node "$CLI" kit provision "$KIT" --target "$DRY" --dry-run >"$TMP_DIR/dry.out" 2>&1 \
+  && [[ ! -e "$DRY/docs/alpha.txt" && ! -e "$DRY/.kontourai" ]] \
+  && rg -q 'would provision' "$TMP_DIR/dry.out"; then
+  pass "--dry-run prints the plan and writes nothing"
+else
+  fail "--dry-run wrote state or omitted its plan"; sed -n '1,100p' "$TMP_DIR/dry.out"
+fi
+
+INVALID="$TMP_DIR/invalid-kit"
+cp -R "$KIT" "$INVALID"
+node -e 'const fs=require("fs"),p=process.argv[1],m=JSON.parse(fs.readFileSync(p));m.provisions[0].target="../escape.txt";m.provisions[1].target="/absolute.txt";fs.writeFileSync(p,JSON.stringify(m,null,2))' "$INVALID/kit.json"
+if node "$CLI" kit validate "$INVALID" >"$TMP_DIR/invalid-validate.out" 2>&1; then
+  fail "kit validate accepted traversal and absolute targets"
+elif node "$CLI" kit provision "$INVALID" --target "$DRY" >"$TMP_DIR/invalid-provision.out" 2>&1; then
+  fail "kit provision accepted an invalid kit"
+elif rg -q 'traversal' "$TMP_DIR/invalid-validate.out" && rg -q 'must be relative' "$TMP_DIR/invalid-validate.out"; then
+  pass "validation and provisioning refuse traversal and absolute targets"
+else
+  fail "unsafe target diagnostics were incomplete"; sed -n '1,100p' "$TMP_DIR/invalid-validate.out"
+fi
+
+HOME_FIXTURE="$TMP_DIR/kit-home"
+mkdir -p "$HOME_FIXTURE"
+if node "$CLI" kit install "$KIT" --dest "$HOME_FIXTURE" >"$TMP_DIR/install.out" 2>&1 \
+  && node "$CLI" kit activate --dest "$HOME_FIXTURE" --source-root "$ROOT" >"$TMP_DIR/activate.out" 2>&1 \
+  && node -e 'const r=JSON.parse(require("fs").readFileSync(process.argv[1],"utf8"));if(!r.skipped_assets.some(x=>x.asset_class==="provisions"&&/not activated/.test(x.reason)))process.exit(1)' "$TMP_DIR/activate.out"; then
+  pass "codex-local activation explicitly skips provisions"
+else
+  fail "activation did not report provisions as skipped"; sed -n '1,120p' "$TMP_DIR/activate.out"
+fi
+
+echo ""
+if [[ "$errors" -eq 0 ]]; then
+  echo "Kit provisioning integration passed."
+  exit 0
+fi
+echo "Kit provisioning integration failed with $errors error(s)."
+exit 1

package/dist/kiro/evals/integration/test_liveness_console_relay.sh

@@ -18,6 +18,13 @@ source "$ROOT/evals/lib/node.sh"
 
 TMPDIR_EVAL="$(mktemp -d)"
 trap 'rm -rf "$TMPDIR_EVAL"; [[ -n "${STUB_PID:-}" ]] && kill "$STUB_PID" 2>/dev/null' EXIT
+
+# Hermetic HOME: the conf-driven relay resolver (#567) reads __KIRO_PACKAGE_ROOT__/telemetry-console.conf
+# as a resolution slot. Point HOME at an empty dir so these tests never read the running machine's
+# real console conf — enablement here is controlled only by the env flag / an explicit
+# TELEMETRY_CONFIG_FILE, exactly as each case sets up.
+export HOME="$TMPDIR_EVAL/clean-home"
+mkdir -p "$HOME"
 PORT=38795
 RECV="$TMPDIR_EVAL/recv.jsonl"
 
@@ -29,6 +36,12 @@ fail() { echo "  [FAIL] $1"; errors=$((errors + 1)); }
 # controls the response — "ok" (200) or "fail" (500) — to exercise the relay-failure path.
 start_stub() {
   local mode="$1"
+  # Fresh port per stub: the relay POST is detached/async, so a late POST from a PRIOR "on" case
+  # could otherwise race into the next case's freshly-cleared RECV on a reused port and cause a
+  # spurious "a POST happened" failure in a "no POST" assertion. A new port each time sends any
+  # stray prior-case POST to a now-dead port (connection refused), never into this case's RECV.
+  PORT=$((PORT + 1))
+  ENDPOINT="http://127.0.0.1:${PORT}/records"
   STUB_MODE="$mode" node -e '
 const http=require("http"),fs=require("fs");
 const out=process.argv[1], mode=process.env.STUB_MODE||"ok";
@@ -67,7 +80,7 @@ echo "=== console liveness relay (#295) ==="
 echo "--- 1. relay on+configured: liveness emit mirrors to the Console with Bearer + tenant ---"
 : > "$RECV"; start_stub ok || { fail "stub server did not start"; }
 ROOT_A="$TMPDIR_EVAL/a"
-EVT1='{"type":"claim","subjectId":"relay-subj-1","actor":"claude-code:sessA:host","actor_key":"claude-code:sessA:host","at":"2026-07-05T00:00:00Z","ttlSeconds":1800,"host":"host","branch":"agent/a/relay-subj-1","artifact_dir":"relay-subj-1"}'
+EVT1='{"type":"claim","subjectId":"relay-subj-1","actor":"claude-code:sessA:host","actor_key":"claude-code:sessA:host","at":"2026-07-05T00:00:00Z","ttlSeconds":1800,"host":"host","branch":"agent/a/relay-subj-1","artifact_dir":"relay-subj-1","source":"tool-activity","activity":{"tool":"Bash"}}'
 (
   export FLOW_AGENTS_CONSOLE_LIVENESS_RELAY=1
   export FLOW_AGENTS_CONSOLE_LIVENESS_ENDPOINT_URL="$ENDPOINT"
@@ -92,6 +105,8 @@ const checks=[
   ["subjectId", b.subjectId==="relay-subj-1"],
   ["actor", b.actor==="claude-code:sessA:host"],
   ["branch", b.branch==="agent/a/relay-subj-1"],
+  ["source tool-activity", b.source==="tool-activity"],
+  ["activity.tool Bash (richer real-liveness rides to the Console)", !!b.activity && b.activity.tool==="Bash"],
 ];
 for(const [name,ok] of checks) console.log((ok?"OK ":"BAD ")+name);
 ' "$RECV" > "$TMPDIR_EVAL/checks.txt" 2>&1
@@ -156,6 +171,81 @@ console.log(hasRawCtl?"RAW":"ESCAPED");
 if grep -q ESCAPED "$TMPDIR_EVAL/inj.txt"; then pass "hostile actor/branch control bytes are JSON-escaped, never raw in the POST body (injection discipline)"; else fail "raw control bytes reached the POST body: $(cat "$TMPDIR_EVAL/inj.txt")"; fi
 stop_stub
 
+# ─── 6. CONF-DRIVEN enablement (#567): NO env flag, `console_liveness_relay=1` in the conf → POST ─
+echo "--- 6. conf-driven (#567): console_liveness_relay=1 in the conf relays with NO env var ---"
+: > "$RECV"; start_stub ok
+ROOT_F="$TMPDIR_EVAL/f"
+CONF6="$TMPDIR_EVAL/conf6.conf"
+printf 'console_telemetry_url=https://example.invalid\nconsole_liveness_relay=1\n' > "$CONF6"
+(
+  unset FLOW_AGENTS_CONSOLE_LIVENESS_RELAY   # the whole point: no env var
+  export TELEMETRY_CONFIG_FILE="$CONF6"
+  export FLOW_AGENTS_CONSOLE_LIVENESS_ENDPOINT_URL="$ENDPOINT"   # POST target (stub)
+  emit_event "$ROOT_F" '{"type":"claim","subjectId":"conf-on-1","actor":"a","at":"t"}'
+)
+[[ -s "$ROOT_F/liveness/events.jsonl" ]] && pass "local write happened (conf-driven case)" || fail "local write missing (conf-driven)"
+if wait_for_post; then pass "conf-driven relay POSTed with NO env var (console_liveness_relay=1)"; else fail "conf-driven relay did NOT POST (env-var-free enablement broken)"; fi
+stop_stub
+
+# ─── 7. CONF-DRIVEN auto-on parity (#469): a console url with no explicit key defaults ON ────────
+echo "--- 7. conf-driven auto-on: a console url with no explicit key relays; explicit =0 suppresses ---"
+: > "$RECV"; start_stub ok
+ROOT_G="$TMPDIR_EVAL/g"
+CONF7="$TMPDIR_EVAL/conf7.conf"
+printf 'console_telemetry_url=https://example.invalid\n' > "$CONF7"   # url only, no explicit key
+(
+  unset FLOW_AGENTS_CONSOLE_LIVENESS_RELAY
+  export TELEMETRY_CONFIG_FILE="$CONF7"
+  export FLOW_AGENTS_CONSOLE_LIVENESS_ENDPOINT_URL="$ENDPOINT"
+  emit_event "$ROOT_G" '{"type":"claim","subjectId":"auto-on-1","actor":"a","at":"t"}'
+)
+if wait_for_post; then pass "auto-on: a configured console url defaults the relay ON (#469 parity)"; else fail "auto-on did NOT POST (console-url default-on broken)"; fi
+stop_stub
+
+: > "$RECV"; start_stub ok
+ROOT_H="$TMPDIR_EVAL/h"
+CONF8="$TMPDIR_EVAL/conf8.conf"
+printf 'console_telemetry_url=https://example.invalid\nconsole_liveness_relay=0\n' > "$CONF8"   # explicit off wins
+(
+  unset FLOW_AGENTS_CONSOLE_LIVENESS_RELAY
+  export TELEMETRY_CONFIG_FILE="$CONF8"
+  export FLOW_AGENTS_CONSOLE_LIVENESS_ENDPOINT_URL="$ENDPOINT"
+  emit_event "$ROOT_H" '{"type":"claim","subjectId":"conf-off-1","actor":"a","at":"t"}'
+)
+sleep 1
+[[ -s "$ROOT_H/liveness/events.jsonl" ]] && pass "local write happened (explicit conf off)" || fail "local write missing (explicit conf off)"
+[[ ! -s "$RECV" ]] && pass "explicit console_liveness_relay=0 suppresses the relay even with a url (opt-out wins)" || fail "a POST happened despite console_liveness_relay=0"
+stop_stub
+
+# ─── 8. EXFIL DEFENSE: an UNTRUSTED (mode 644) default-path conf must NOT relay (trust gate) ─────
+# The cases above drive enablement through TELEMETRY_CONFIG_FILE, which is trusted BY DESIGN (an
+# explicit env override bypasses the mode-600 gate). This case exercises the actual supply-chain
+# defense end-to-end: a conf planted at the user-global default slot (__KIRO_PACKAGE_ROOT__/…, reached via
+# the hermetic HOME set at the top) pointing at an attacker stub with console_liveness_relay=1, but
+# mode 644 — exactly what a non-operator drop (clone/tarball/local tool) can produce, since git can
+# only ship 644/755, never 600. relay.sh re-sources config.sh, whose telemetry_conf_trusted gate
+# (mode 600 + owner + not-a-symlink) rejects it, so no URL resolves and nothing is POSTed — while
+# the durable local write still happens. NO env flag, NO TELEMETRY_CONFIG_FILE, NO endpoint env:
+# the untrusted conf is the ONLY possible signal, so a POST here would be a real exfil regression.
+echo "--- 8. exfil defense: an untrusted (mode 644) __KIRO_PACKAGE_ROOT__ conf with an attacker url never relays ---"
+: > "$RECV"; start_stub ok
+ROOT_X="$TMPDIR_EVAL/x"
+mkdir -p "__KIRO_PACKAGE_ROOT__"
+UNTRUSTED_CONF="__KIRO_PACKAGE_ROOT__/telemetry-console.conf"
+printf 'console_telemetry_url=http://127.0.0.1:%s\nconsole_liveness_relay=1\n' "$PORT" > "$UNTRUSTED_CONF"
+chmod 644 "$UNTRUSTED_CONF"
+(
+  unset FLOW_AGENTS_CONSOLE_LIVENESS_RELAY
+  unset TELEMETRY_CONFIG_FILE
+  unset FLOW_AGENTS_CONSOLE_LIVENESS_ENDPOINT_URL
+  emit_event "$ROOT_X" '{"type":"claim","subjectId":"exfil-x","actor":"a","at":"t"}'
+)
+sleep 1
+[[ -s "$ROOT_X/liveness/events.jsonl" ]] && pass "local write happened (untrusted-conf case, local-first intact)" || fail "local write missing (untrusted conf)"
+[[ ! -s "$RECV" ]] && pass "an untrusted (644) default-path conf naming an attacker url NEVER relays (trust gate holds, no exfil)" || fail "EXFIL: a POST reached the attacker stub from an untrusted 644 conf"
+rm -f "$UNTRUSTED_CONF"
+stop_stub
+
 echo ""
 if [[ "$errors" -eq 0 ]]; then
   echo "test_liveness_console_relay: all checks passed."

package/dist/kiro/evals/integration/test_liveness_heartbeat.sh

@@ -704,6 +704,72 @@ else
   _fail "maybeEmitHeartbeat did not neutralize an orphan heartbeat as expected: $J1_OUT"
 fi
 
+# ─── K. Richer "real liveness": activity descriptor on the emitted heartbeat ────────────────
+echo "--- K. Activity enrichment (tool name on the pulse) ---"
+
+# call_heartbeat_activity <scratch_root> <env_json> <now_iso> <activity_json>
+# Like call_heartbeat, but passes an `activity` descriptor through opts so we can prove the emitted
+# heartbeat carries a sanitized activity field (the "what is this agent doing right now" signal).
+call_heartbeat_activity() {
+  local root="$1" env_json="$2" now="$3" activity_json="$4"
+  MODULE_ARG="$HEARTBEAT_MODULE" ROOT_ARG="$root" ENV_JSON_ARG="$env_json" NOW_ARG="$now" ACTIVITY_ARG="$activity_json" \
+    node - <<'NODE'
+const { maybeEmitHeartbeat } = require(process.env.MODULE_ARG);
+const env = JSON.parse(process.env.ENV_JSON_ARG);
+const opts = { cwd: process.env.ROOT_ARG, env, now: process.env.NOW_ARG, activity: JSON.parse(process.env.ACTIVITY_ARG) };
+process.stdout.write(JSON.stringify(maybeEmitHeartbeat(opts)));
+NODE
+}
+
+# K1: a clean tool name rides through onto the emitted heartbeat as activity.tool.
+K1_ROOT="$(new_scratch)"
+seed_claim "$K1_ROOT" "k1-subj" "agent-k1" "2026-06-25T12:00:00.000Z" 1800
+K1_RESULT="$(call_heartbeat_activity "$K1_ROOT" '{"FLOW_AGENTS_ACTOR":"agent-k1"}' "2026-06-25T12:01:00.000Z" '{"tool":"Bash"}')"
+K1_LINE="$(tail -n 1 "$(stream_file "$K1_ROOT")" 2>/dev/null)"
+if [[ "$K1_RESULT" == '{"emitted":true}' ]] \
+  && grep -q '"type":"heartbeat"' <<<"$K1_LINE" \
+  && grep -q '"activity":{"tool":"Bash"}' <<<"$K1_LINE"; then
+  _pass "the emitted heartbeat carries a sanitized activity.tool (what the agent is doing right now)"
+else
+  _fail "the heartbeat did not carry the expected activity.tool: result=$K1_RESULT line=$K1_LINE"
+fi
+
+# K2: an MCP-style tool name (double underscores + hyphens) survives sanitizeSegment intact.
+K2_ROOT="$(new_scratch)"
+seed_claim "$K2_ROOT" "k2-subj" "agent-k2" "2026-06-25T12:00:00.000Z" 1800
+call_heartbeat_activity "$K2_ROOT" '{"FLOW_AGENTS_ACTOR":"agent-k2"}' "2026-06-25T12:01:00.000Z" '{"tool":"mcp__claude-in-chrome__navigate"}' >/dev/null
+K2_LINE="$(tail -n 1 "$(stream_file "$K2_ROOT")" 2>/dev/null)"
+if grep -q '"activity":{"tool":"mcp__claude-in-chrome__navigate"}' <<<"$K2_LINE"; then
+  _pass "an MCP tool name (double underscores + hyphens) rides through the allowlist sanitizer intact"
+else
+  _fail "the MCP tool name was not preserved on the activity descriptor: line=$K2_LINE"
+fi
+
+# K3: a hostile tool name (control bytes / injection payload) is stripped to the allowlist charset —
+# never emitted raw into the append-only stream.
+K3_ROOT="$(new_scratch)"
+seed_claim "$K3_ROOT" "k3-subj" "agent-k3" "2026-06-25T12:00:00.000Z" 1800
+call_heartbeat_activity "$K3_ROOT" '{"FLOW_AGENTS_ACTOR":"agent-k3"}' "2026-06-25T12:01:00.000Z" '{"tool":"Ba\"sh\n{\"x\":1}"}' >/dev/null
+K3_LINE="$(tail -n 1 "$(stream_file "$K3_ROOT")" 2>/dev/null)"
+# The allowlist keeps only [A-Za-z0-9_.-], so the payload collapses to "Bashx1".
+if grep -q '"activity":{"tool":"Bashx1"}' <<<"$K3_LINE" && ! grep -q 'Ba"sh' <<<"$K3_LINE"; then
+  _pass "a hostile tool name is stripped to the allowlist charset, never emitted raw (injection discipline)"
+else
+  _fail "the hostile tool name was not sanitized as expected: line=$K3_LINE"
+fi
+
+# K4: no activity supplied → the heartbeat is a plain aliveness pulse with NO activity key (the field
+# is omitted, not emitted empty).
+K4_ROOT="$(new_scratch)"
+seed_claim "$K4_ROOT" "k4-subj" "agent-k4" "2026-06-25T12:00:00.000Z" 1800
+call_heartbeat "$K4_ROOT" '{"FLOW_AGENTS_ACTOR":"agent-k4"}' "2026-06-25T12:01:00.000Z" >/dev/null
+K4_LINE="$(tail -n 1 "$(stream_file "$K4_ROOT")" 2>/dev/null)"
+if grep -q '"type":"heartbeat"' <<<"$K4_LINE" && ! grep -q '"activity"' <<<"$K4_LINE"; then
+  _pass "with no activity supplied the heartbeat omits the activity field entirely (no empty-object noise)"
+else
+  _fail "the no-activity heartbeat unexpectedly carried an activity field: line=$K4_LINE"
+fi
+
 echo ""
 if [[ "$errors" -eq 0 ]]; then
   echo "Liveness heartbeat integration passed."