@kontourai/flow-agents 4.0.0 → 4.2.0

package/dist/pi/scripts/liveness/relay.sh

@@ -7,26 +7,36 @@
 # never forked). The Console side ingests this record type and projects the fleet view + runs the
 # janitor (console repo #125); this script is only the flow-agents EMIT half.
 #
-# STRICTLY OPTIONAL and local-first (ADR 0012 §5): a no-op unless FLOW_AGENTS_CONSOLE_LIVENESS_RELAY
-# is enabled AND a console endpoint is configured. Best-effort throughout — it must NEVER block, slow,
-# or fail the local liveness write that already happened before this was invoked. Every failure path
-# is a quiet `exit 0`.
+# STRICTLY OPTIONAL and local-first (ADR 0012 §5): a no-op unless the liveness relay is enabled AND a
+# console endpoint is configured. Enablement is conf-driven (#567, parity with economics #469): an
+# operator sets `console_liveness_relay=1` in the console conf (or it defaults on once a console url
+# resolves) — NOT an env var. config.sh (sourced below) is the authoritative, trust-gated decision
+# and also supplies the endpoint/token/tenant from the conf. Best-effort throughout — it must NEVER
+# block, slow, or fail the local liveness write that already happened before this was invoked. Every
+# failure path is a quiet `exit 0`.
 #
 # Invoked (fully detached, best-effort) from scripts/hooks/lib/liveness-write.js after the durable
 # local append. Usage: relay.sh '<liveness-event-json>'
 set -uo pipefail
 
-# Opt-in gate — off by default.
-case "${FLOW_AGENTS_CONSOLE_LIVENESS_RELAY:-}" in
-  1 | true | TRUE | yes | on) ;;
-  *) exit 0 ;;
-esac
-
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" || exit 0
 
 # transport.sh sources ${TELEMETRY_DIR}/lib/redact.sh at load — point it at the telemetry lib dir,
 # then reuse the SAME console POST core the telemetry mirror uses.
 export TELEMETRY_DIR="${TELEMETRY_DIR:-$SCRIPT_DIR/../telemetry}"
+
+# Source config.sh FIRST (best-effort, like economics-record.sh) so the conf resolves enablement
+# (FLOW_AGENTS_CONSOLE_LIVENESS_RELAY) and the endpoint/token/tenant — trust-gated for default-path
+# confs. This is what makes conf-only operation work with NO env var set.
+# shellcheck source=/dev/null
+[[ -f "$TELEMETRY_DIR/lib/config.sh" ]] && source "$TELEMETRY_DIR/lib/config.sh" 2>/dev/null || true
+
+# Opt-in gate — off by default, now honoring the conf-derived value config.sh just resolved.
+case "${FLOW_AGENTS_CONSOLE_LIVENESS_RELAY:-}" in
+  1 | true | TRUE | yes | on) ;;
+  *) exit 0 ;;
+esac
+
 [[ -f "$TELEMETRY_DIR/lib/transport.sh" ]] || exit 0
 # shellcheck source=/dev/null
 source "$TELEMETRY_DIR/lib/transport.sh" 2>/dev/null || exit 0
@@ -73,7 +83,9 @@ record="$(printf '%s' "$event_json" | jq -c '{
   ttlSeconds: (.ttlSeconds // null),
   host: (.host // null),
   branch: (.branch // null),
-  artifact_dir: (.artifact_dir // .artifactDir // null)
+  artifact_dir: (.artifact_dir // .artifactDir // null),
+  source: (.source // null),
+  activity: (.activity // null)
 }' 2>/dev/null)" || exit 0
 [[ -z "$record" || "$record" == "null" ]] && exit 0
 

package/dist/pi/scripts/telemetry/lib/config.sh

@@ -109,6 +109,13 @@ FLOW_AGENTS_CONSOLE_ECONOMICS_ENDPOINT_URL="${FLOW_AGENTS_CONSOLE_ECONOMICS_ENDP
 # Set (non-empty) only when the config file carries an explicit console_economics_relay key —
 # distinguishes "operator said 0/1" from "key absent" for the default-on rule below.
 console_economics_relay_raw=""
+# Liveness relay (#567): same conf-driven, opt-out-not-silent-off shape as economics (#469) so an
+# operator enables the hosted liveness mirror via console_liveness_relay=1 in the conf, NOT an env
+# var/.profile. A caller-pre-set env var is the starting point; the config key overrides it; absent
+# any key the default-on rule below turns it on once a console telemetry sink resolves.
+FLOW_AGENTS_CONSOLE_LIVENESS_RELAY="${FLOW_AGENTS_CONSOLE_LIVENESS_RELAY:-}"
+FLOW_AGENTS_CONSOLE_LIVENESS_ENDPOINT_URL="${FLOW_AGENTS_CONSOLE_LIVENESS_ENDPOINT_URL:-}"
+console_liveness_relay_raw=""
 # Pricing registry source (consumed by lib/pricing.sh). Explicit file/URL win;
 # otherwise lib/pricing.sh uses the bundled pricing.json offline.
 TELEMETRY_PRICING_FILE="${TELEMETRY_PRICING_FILE:-${FLOW_AGENTS_PRICING_FILE:-}}"
@@ -164,6 +171,17 @@ if [[ -f "$TELEMETRY_CONFIG_FILE" ]]; then
           esac
           ;;
         console_economics_endpoint_url) FLOW_AGENTS_CONSOLE_ECONOMICS_ENDPOINT_URL="$value" ;;
+        console_liveness_relay)
+          case "$(echo "$value" | tr '[:upper:]' '[:lower:]')" in
+            1|true|yes|on) console_liveness_relay_raw="1" ;;
+            0|false|no|off) console_liveness_relay_raw="0" ;;
+            *)
+              printf 'warning: config.sh: unrecognized console_liveness_relay value %q; treating as off\n' "$value" >&2
+              console_liveness_relay_raw="$value"
+              ;;
+          esac
+          ;;
+        console_liveness_endpoint_url) FLOW_AGENTS_CONSOLE_LIVENESS_ENDPOINT_URL="$value" ;;
         console_pricing_url) TELEMETRY_PRICING_URL="$value" ;;
         pricing_url) TELEMETRY_PRICING_URL="$value" ;;
         pricing_file) TELEMETRY_PRICING_FILE="$value" ;;
@@ -186,6 +204,17 @@ elif [[ -z "$FLOW_AGENTS_CONSOLE_ECONOMICS_RELAY" \
   FLOW_AGENTS_CONSOLE_ECONOMICS_RELAY=1
 fi
 
+# Liveness relay default-on rule (#567), identical shape to economics above: an explicit
+# console_liveness_relay config key always wins; otherwise, once a console telemetry sink resolves,
+# the relay defaults ON unless a caller already pre-set FLOW_AGENTS_CONSOLE_LIVENESS_RELAY in the
+# environment. relay.sh's own opt-in gate reads this exact variable.
+if [[ -n "$console_liveness_relay_raw" ]]; then
+  FLOW_AGENTS_CONSOLE_LIVENESS_RELAY="$console_liveness_relay_raw"
+elif [[ -z "$FLOW_AGENTS_CONSOLE_LIVENESS_RELAY" \
+      && ( -n "${CONSOLE_TELEMETRY_URL:-}" || -n "${CONSOLE_TELEMETRY_ENDPOINT_URL:-}" ) ]]; then
+  FLOW_AGENTS_CONSOLE_LIVENESS_RELAY=1
+fi
+
 # Pricing URL is explicit-only (env or config). Do not derive the console
 # pricing endpoint by default; the bundled registry is the reliable offline floor.
 

package/docs/adr/0023-kit-provisioning.md

@@ -0,0 +1,47 @@
+---
+title: "ADR 0023: Declarative Kit Provisioning"
+---
+
+# ADR 0023: Declarative Kit Provisioning
+
+**Date:** 2026-07-16
+**Status:** Accepted (owner-ratified Option A in flow-agents#647)
+
+---
+
+## Context
+
+Kits sometimes need to supply repository-owned configuration or policy files in addition to runtime projections. The motivating `veritas-governance` follow-up needs this capability, but embedding kit-specific copy logic in Flow Agents would violate the kit boundary. Runtime activation is also the wrong mechanism: its projection directory is regenerable adapter state, while these files must become normal files in the consumer repository.
+
+## Decision
+
+A kit may declare a `provisions` list in `kit.json`. Each entry is inert data naming an id, a source file inside the kit, and a consumer-repository-relative target. Provision declarations are never executed.
+
+The Flow Agents engine performs agent-blind file copying through an explicit `kit provision` operation. It validates source and target containment, preflights every destination, and creates files only when no declared destination already exists. An explicit `--force` option may replace declared destination files; the default never silently overwrites an anchor-owned or consumer-owned file. `--dry-run` reports the plan without writing.
+
+`flow-agents init --activate-kit` invokes the same engine after activation with create-only semantics. Existing destinations are reported as skipped warnings so init remains safe to rerun. Provisioning remains separate from runtime activation and its projection directory.
+
+The engine records successful copies under `.kontourai/flow-agents/provisions/<kit-id>.json`. This manifest is bookkeeping and may be replaced on a later successful provisioning operation. Enforcement policy and ownership of protected paths remain anchor-side; a kit declaration does not grant permission to overwrite them.
+
+## Consequences
+
+- Kits can ship repository files without executable installers or kit-specific engine behavior.
+- Create-only defaults preserve consumer and anchor ownership; replacement requires an explicit user operation.
+- Provisioned files belong to the consumer repository once written. Uninstalling or deactivating a kit never removes or reverts them.
+- Runtime adapters continue to activate only their supported projection assets and report provisions as explicitly skipped.
+- Consumers that need stronger protected-path policy enforce it at their anchor; the generic engine remains deliberately dumb and kit-neutral.
+
+## Accepted residuals
+
+- **Copy is best-effort against concurrent interposition (both ends).** The checks and the copy
+  are separate steps (check-then-act): a file created into a declared destination between the
+  conflict preflight and the write can still be overwritten, and a source re-pointed to a link
+  between its containment check and its read could resolve elsewhere. Provisioning targets a
+  developer/CI working tree, not a hostile multi-writer path, so both TOCTOU windows are accepted
+  rather than closed with exclusive-create / open-then-fstat plumbing. The static guarantees are
+  enforced up front: reserved-directory (`.git`, the provision manifest namespace), source and
+  destination containment (link-resolved), and case-fold collision rejection; concurrent
+  interposition on either end is out of scope.
+- **Target case-folding assumes the common single-case-family repo.** Collision and reserved-path
+  checks case-fold targets so case-insensitive filesystems are safe; a genuinely case-sensitive
+  repo that intends two targets differing only in case is rejected as a portability hazard.

package/docs/adr/index.md

@@ -32,3 +32,4 @@ Numbered ADRs below are FROZEN immutable history (see the banner on each file).
 | 0020 | Trust-Reconcile Manifest, Claim Classification, and Waivers | unknown | [0020-trust-reconcile-manifest-and-claim-classification.md](./0020-trust-reconcile-manifest-and-claim-classification.md) |
 | 0021 | Assignment Leases and Stale-Claim Takeover | 2026-07-02 | [0021-assignment-leases-and-stale-claim-takeover.md](./0021-assignment-leases-and-stale-claim-takeover.md) |
 | 0022 | Fail-Closed Delivery Reconciliation with Governed Exemptions | 2026-07-02 | [0022-fail-closed-delivery-reconciliation-with-governed-exemptions.md](./0022-fail-closed-delivery-reconciliation-with-governed-exemptions.md) |
+| 0023 | Declarative Kit Provisioning | 2026-07-16 | [0023-kit-provisioning.md](./0023-kit-provisioning.md) |

package/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/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/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/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/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/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/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/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/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/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