@kontourai/flow-agents 4.0.0 → 4.1.0

package/dist/codex/build/src/flow-kit/validate.js

@@ -5,19 +5,24 @@ import { parseKitFlowStepActions, workflowTriggerIdentifier } from "./action-met
 import { validateActionRepositoryMetadata } from "./action-repository-validation.js";
 export { isObservableBuilderArtifactRef, isSafeBuilderArtifactRef, parseKitFlowStepActions } from "./action-metadata.js";
 // Extension-only asset classes: validated by Flow Agents. Flows are validated by @kontourai/flow.
-const EXTENSION_ASSET_CLASSES = ["skills", "docs", "adapters", "evals", "assets"];
+const EXTENSION_ASSET_CLASSES = ["skills", "docs", "adapters", "evals", "assets", "provisions"];
 // Core container fields owned by kontourai/flow (flow-kit-container.schema.json).
 // agent-extension fields are skills, docs, adapters, evals, assets.
 const CORE_CONTAINER_FIELDS = new Set(["schema_version", "id", "name", "description", "product_name", "flows"]);
-const AGENT_EXTENSION_CLASSES = new Set(["skills", "docs", "adapters", "evals", "assets"]);
+const AGENT_EXTENSION_CLASSES = new Set(["skills", "docs", "adapters", "evals", "assets", "provisions"]);
 // Flow Agents-recognized metadata fields that are neither core container fields nor
 // agent-extension asset classes. Recognized here so they are never misreported as
 // unknown third-party extension namespaces. `dependencies` declares cross-kit skill
 // dependencies (extension-layer ownership; see docs/adr/0019-kit-dependency-ownership.md),
 // workflow_triggers / hook_influence_expectations declare kit-owned runtime influence,
-// and first_party is legacy catalog/marketplace metadata. It does not grant runtime
-// capability or steering privilege.
-const KNOWN_METADATA_FIELDS = new Set(["dependencies", "workflow_triggers", "hook_influence_expectations", "flow_step_actions", "skill_roles", "first_party"]);
+// agent_spawn_triggers declares perimeter trigger surfaces that spawn agent runs plus
+// their guard config (context/contracts/trigger-guards.md), and first_party is legacy
+// catalog/marketplace metadata. It does not grant runtime capability or steering privilege.
+const KNOWN_METADATA_FIELDS = new Set(["dependencies", "workflow_triggers", "hook_influence_expectations", "flow_step_actions", "skill_roles", "first_party", "agent_spawn_triggers"]);
+// Consumer-repo-relative directory (posix, lowercase) where the engine writes its own
+// per-kit provision manifest. Reserved: a provision may not target inside it. Shared with
+// provision.ts so the reservation and the actual manifest write stay in agreement.
+export const PROVISION_MANIFEST_DIR = ".kontourai/flow-agents/provisions";
 /**
  * Parse and shape-validate a kit manifest's `dependencies` field (Flow Agents
  * extension-layer metadata; see docs/adr/0019-kit-dependency-ownership.md).
@@ -221,6 +226,120 @@ export function parseKitHookInfluenceExpectations(manifest, manifestPath) {
     });
     return { entries, errors };
 }
+const AGENT_SPAWN_TRIGGER_GUARD_FIELDS = ["dedup_key", "cooldown_seconds", "daily_cap", "max_concurrent"];
+/**
+ * Parse and shape-validate a kit manifest's optional `agent_spawn_triggers` field:
+ * perimeter trigger surfaces (check failures, schedules, watchers) that spawn agent
+ * runs, plus their guard config. Contract: context/contracts/trigger-guards.md.
+ *
+ * Shape rules (ERRORS):
+ *  - `agent_spawn_triggers` (if present) must be an array of objects.
+ *  - `id` must match the workflow-trigger identifier pattern and be unique.
+ *  - `description` must be a non-empty string.
+ *  - `spawns_agent_runs` must be a boolean.
+ *  - `guards` (if present) must be an object with exactly the four guard fields when
+ *    complete: `dedup_key` non-empty string; `cooldown_seconds`, `daily_cap`,
+ *    `max_concurrent` integers >= 1. Unknown guard fields are errors.
+ *
+ * Guard-completeness (WARNINGS, never errors — declaration-first rollout, #664):
+ *  - an entry with `spawns_agent_runs: true` and missing or incomplete `guards`
+ *    produces a warning naming the missing guard fields and the contract doc.
+ */
+export function parseKitAgentSpawnTriggers(manifest, manifestPath) {
+    const entries = [];
+    const errors = [];
+    const warnings = [];
+    const raw = manifest.agent_spawn_triggers;
+    if (raw === undefined)
+        return { entries, errors, warnings };
+    if (!Array.isArray(raw)) {
+        errors.push(`${manifestPath}: .agent_spawn_triggers must be a list`);
+        return { entries, errors, warnings };
+    }
+    const fields = new Set(["id", "description", "spawns_agent_runs", "guards"]);
+    const seen = new Set();
+    raw.forEach((entry, index) => {
+        if (typeof entry !== "object" || entry === null) {
+            errors.push(`${manifestPath}: agent_spawn_triggers[${index}] must be an object`);
+            return;
+        }
+        const record = entry;
+        const unknown = Object.keys(record).filter((field) => !fields.has(field));
+        if (unknown.length > 0) {
+            errors.push(`${manifestPath}: agent_spawn_triggers[${index}] contains unsupported field(s): ${unknown.join(", ")}`);
+            return;
+        }
+        const id = record.id;
+        if (!workflowTriggerIdentifier(id)) {
+            errors.push(`${manifestPath}: agent_spawn_triggers[${index}].id must match ^[a-z0-9]+(?:[.-][a-z0-9]+)*$`);
+            return;
+        }
+        if (seen.has(id)) {
+            errors.push(`${manifestPath}: agent_spawn_triggers[${index}].id duplicates '${id}'`);
+            return;
+        }
+        seen.add(id);
+        if (typeof record.description !== "string" || !record.description.trim()) {
+            errors.push(`${manifestPath}: agent_spawn_triggers[${index}].description must be a non-empty string`);
+            return;
+        }
+        if (typeof record.spawns_agent_runs !== "boolean") {
+            errors.push(`${manifestPath}: agent_spawn_triggers[${index}].spawns_agent_runs must be a boolean`);
+            return;
+        }
+        let guards;
+        let guardsShapeValid = true;
+        const missingGuardFields = [];
+        if (record.guards !== undefined) {
+            if (typeof record.guards !== "object" || record.guards === null || Array.isArray(record.guards)) {
+                errors.push(`${manifestPath}: agent_spawn_triggers[${index}].guards must be an object when present`);
+                return;
+            }
+            const guardRecord = record.guards;
+            const guardFieldSet = new Set(AGENT_SPAWN_TRIGGER_GUARD_FIELDS);
+            const unknownGuards = Object.keys(guardRecord).filter((field) => !guardFieldSet.has(field));
+            if (unknownGuards.length > 0) {
+                errors.push(`${manifestPath}: agent_spawn_triggers[${index}].guards contains unsupported field(s): ${unknownGuards.join(", ")}`);
+                return;
+            }
+            if (guardRecord.dedup_key !== undefined && (typeof guardRecord.dedup_key !== "string" || !guardRecord.dedup_key.trim())) {
+                errors.push(`${manifestPath}: agent_spawn_triggers[${index}].guards.dedup_key must be a non-empty string`);
+                guardsShapeValid = false;
+            }
+            for (const field of ["cooldown_seconds", "daily_cap", "max_concurrent"]) {
+                const value = guardRecord[field];
+                if (value !== undefined && (typeof value !== "number" || !Number.isInteger(value) || value < 1)) {
+                    errors.push(`${manifestPath}: agent_spawn_triggers[${index}].guards.${field} must be an integer >= 1`);
+                    guardsShapeValid = false;
+                }
+            }
+            if (!guardsShapeValid)
+                return;
+            for (const field of AGENT_SPAWN_TRIGGER_GUARD_FIELDS) {
+                if (guardRecord[field] === undefined)
+                    missingGuardFields.push(field);
+            }
+            if (missingGuardFields.length === 0) {
+                guards = {
+                    dedup_key: guardRecord.dedup_key,
+                    cooldown_seconds: guardRecord.cooldown_seconds,
+                    daily_cap: guardRecord.daily_cap,
+                    max_concurrent: guardRecord.max_concurrent,
+                };
+            }
+        }
+        else {
+            missingGuardFields.push(...AGENT_SPAWN_TRIGGER_GUARD_FIELDS);
+        }
+        if (record.spawns_agent_runs === true && missingGuardFields.length > 0) {
+            warnings.push(`${manifestPath}: agent_spawn_triggers[${index}] ('${id}') spawns agent runs without complete guard config` +
+                ` (missing: ${missingGuardFields.join(", ")}); declare dedup_key, cooldown_seconds, daily_cap, and max_concurrent` +
+                ` per context/contracts/trigger-guards.md`);
+        }
+        entries.push({ id, description: record.description, spawns_agent_runs: record.spawns_agent_runs, ...(guards ? { guards } : {}) });
+    });
+    return { entries, errors, warnings };
+}
 export function parseKitSkillRoles(manifest, manifestPath) {
     const entries = [];
     const errors = [];
@@ -393,7 +512,17 @@ export async function deriveKitTargets(manifest, kitDir = "", sourceRoot = proce
     };
 }
 export async function validateKitRepository(kitDir) {
+    return (await validateKitRepositoryDiagnostics(kitDir)).errors;
+}
+/**
+ * Repository validation with a non-blocking warnings channel alongside the blocking
+ * errors `validateKitRepository` has always returned. Warnings are advisory quality
+ * findings (today: an agent-spawning trigger surface declared without complete guard
+ * config — context/contracts/trigger-guards.md); they never fail validation.
+ */
+export async function validateKitRepositoryDiagnostics(kitDir) {
     const errors = [];
+    const warnings = [];
     const manifestPath = path.join(kitDir, "kit.json");
     let manifest;
     try {
@@ -401,14 +530,16 @@ export async function validateKitRepository(kitDir) {
     }
     catch (error) {
         errors.push(`${manifestPath}: invalid JSON: ${error.message}`);
-        return errors;
+        return { errors, warnings };
     }
     errors.push(...await delegateCoreContainerValidation(kitDir, manifest));
     errors.push(...validateExtensionAssets(kitDir, manifestPath, manifest));
-    errors.push(...validateAgentMetadata(kitDir, manifestPath, manifest));
+    const metadata = validateAgentMetadata(kitDir, manifestPath, manifest);
+    errors.push(...metadata.errors);
+    warnings.push(...metadata.warnings);
     if (manifest.first_party !== undefined && typeof manifest.first_party !== "boolean")
         errors.push(`${manifestPath}: .first_party must be a boolean when present`);
-    return errors;
+    return { errors, warnings };
 }
 function validateExtensionAssets(kitDir, manifestPath, manifest) {
     const errors = [];
@@ -429,11 +560,15 @@ function validateExtensionAssets(kitDir, manifestPath, manifest) {
             const record = entry;
             const id = record.id;
             const rel = record.path;
+            const kitId = typeof manifest.id === "string" ? manifest.id : "";
             if (typeof id === "string") {
                 if (seen.has(id))
                     errors.push(`${manifestPath}: ${section}[${index}].id duplicates`);
                 seen.add(id);
             }
+            if (section === "provisions" && (typeof id !== "string" || !kitId || !id.startsWith(`${kitId}.`))) {
+                errors.push(`${manifestPath}: provisions[${index}].id must be prefixed with '${kitId}.'`);
+            }
             if (typeof rel !== "string" || !rel) {
                 errors.push(`${manifestPath}: ${section}[${index}].path must be a string`);
                 return;
@@ -442,6 +577,10 @@ function validateExtensionAssets(kitDir, manifestPath, manifest) {
                 errors.push(`${manifestPath}: ${section}[${index}].path must be relative`);
                 return;
             }
+            if (rel.replace(/\\/g, "/").split("/").includes("..")) {
+                errors.push(`${manifestPath}: ${section}[${index}].path must not contain traversal segments`);
+                return;
+            }
             const resolved = path.resolve(kitDir, rel);
             const root = path.resolve(kitDir);
             if (resolved !== root && !resolved.startsWith(`${root}${path.sep}`)) {
@@ -451,12 +590,73 @@ function validateExtensionAssets(kitDir, manifestPath, manifest) {
             if (!fs.existsSync(resolved)) {
                 errors.push(`${manifestPath}: ${section}[${index}].path points at missing asset: ${rel}`);
             }
+            else if (section === "provisions") {
+                if (!fs.statSync(resolved).isFile()) {
+                    errors.push(`${manifestPath}: provisions[${index}].path must point at a file: ${rel}`);
+                }
+                else {
+                    // A provisioned source is copied byte-for-byte into a consumer repo, so a symlink that
+                    // resolves outside the kit would exfiltrate arbitrary readable host files. Require the
+                    // link-resolved real path to stay inside the kit.
+                    const realResolved = fs.realpathSync(resolved);
+                    const realRoot = fs.realpathSync(root);
+                    if (realResolved !== realRoot && !realResolved.startsWith(`${realRoot}${path.sep}`)) {
+                        errors.push(`${manifestPath}: provisions[${index}].path must not resolve outside the kit directory`);
+                    }
+                }
+            }
+        });
+    }
+    const rawProvisions = manifest.provisions;
+    if (Array.isArray(rawProvisions)) {
+        const targets = new Set();
+        rawProvisions.forEach((entry, index) => {
+            if (typeof entry !== "object" || entry === null)
+                return;
+            const record = entry;
+            if (record.description !== undefined && typeof record.description !== "string") {
+                errors.push(`${manifestPath}: provisions[${index}].description must be a string when present`);
+            }
+            const target = record.target;
+            if (typeof target !== "string" || target.trim().length === 0) {
+                errors.push(`${manifestPath}: provisions[${index}].target must be a non-empty string`);
+                return;
+            }
+            if (path.isAbsolute(target) || path.win32.isAbsolute(target)) {
+                errors.push(`${manifestPath}: provisions[${index}].target must be relative`);
+                return;
+            }
+            const segments = target.replace(/\\/g, "/").split("/");
+            if (segments.includes("..")) {
+                errors.push(`${manifestPath}: provisions[${index}].target must not contain traversal segments`);
+                return;
+            }
+            const normalized = path.posix.normalize(segments.join("/"));
+            if (normalized === "." || normalized.startsWith("..")) {
+                errors.push(`${manifestPath}: provisions[${index}].target must stay inside the consumer repository`);
+                return;
+            }
+            // Case-fold reserved-directory and collision checks: on a case-insensitive filesystem
+            // `.GIT/` still lands in the real `.git`, and README.md/readme.md still collide.
+            const lowered = normalized.toLowerCase();
+            if (lowered === ".git" || lowered.startsWith(".git/")) {
+                errors.push(`${manifestPath}: provisions[${index}].target must not be inside .git`);
+                return;
+            }
+            if (lowered === PROVISION_MANIFEST_DIR || lowered.startsWith(`${PROVISION_MANIFEST_DIR}/`)) {
+                errors.push(`${manifestPath}: provisions[${index}].target must not be inside the provision manifest namespace (${PROVISION_MANIFEST_DIR}/)`);
+                return;
+            }
+            if (targets.has(lowered))
+                errors.push(`${manifestPath}: provisions[${index}].target duplicates '${normalized}'`);
+            targets.add(lowered);
         });
     }
     return errors;
 }
 function validateAgentMetadata(kitDir, manifestPath, manifest) {
     const errors = [];
+    const warnings = [];
     const depResult = parseKitDependencies(manifest, manifestPath);
     for (const err of depResult.errors)
         errors.push(err);
@@ -466,6 +666,11 @@ function validateAgentMetadata(kitDir, manifestPath, manifest) {
     const hookExpectationResult = parseKitHookInfluenceExpectations(manifest, manifestPath);
     for (const err of hookExpectationResult.errors)
         errors.push(err);
+    const agentSpawnTriggerResult = parseKitAgentSpawnTriggers(manifest, manifestPath);
+    for (const err of agentSpawnTriggerResult.errors)
+        errors.push(err);
+    for (const warning of agentSpawnTriggerResult.warnings)
+        warnings.push(warning);
     const flowStepActionResult = parseKitFlowStepActions(manifest, manifestPath);
     for (const err of flowStepActionResult.errors)
         errors.push(err);
@@ -475,7 +680,7 @@ function validateAgentMetadata(kitDir, manifestPath, manifest) {
     if ((manifest.skill_roles !== undefined || manifest.flow_step_actions !== undefined) && skillRoleResult.errors.length === 0) {
         errors.push(...validateActionRepositoryMetadata({ kitDir, manifestPath, manifest, actions: flowStepActionResult.entries, skillRoles: skillRoleResult.entries }));
     }
-    return errors;
+    return { errors, warnings };
 }
 export async function assertKitRepository(kitDir) {
     const errors = await validateKitRepository(kitDir);

package/dist/codex/build/src/runtime-adapters.js

@@ -3,7 +3,7 @@ import * as path from "node:path";
 import { atomicCopyFile, atomicWriteJson, ensureSafeDirectory, readJson, relPath } from "./lib/fs.js";
 import { flowAgentsArtifactRoot } from "./lib/local-artifact-root.js";
 import { parseKitDependencies, parseKitHookInfluenceExpectations, parseKitWorkflowTriggers } from "./flow-kit/validate.js";
-const ASSET_CLASSES = ["flows", "skills", "docs", "adapters", "evals", "assets"];
+const ASSET_CLASSES = ["flows", "skills", "docs", "adapters", "evals", "assets", "provisions"];
 const KIT_ID_RE = /^[a-z][a-z0-9-]*$/;
 function assetPath(root, value) {
     if (path.isAbsolute(value))

package/dist/codex/context/contracts/execution-contract.md

@@ -42,7 +42,36 @@ Execution may upgrade to a stronger mode when risk increases. Downgrades require
 - Independent tasks with no shared files can run in the same wave.
 - Shared files, generated artifacts, migrations, and cross-cutting contracts should be serialized unless the plan gives explicit file ownership.
 - Worker delegation must name the exact worker role (`tool-worker`) rather than spawning an unnamed/default implementation agent.
-- After each wave, collect results, check conflicts, and update the session artifact before starting the next wave.
+- After each wave, reconcile results against the wave manifest (below), check conflicts, and update the session artifact before starting the next wave.
+
+## Wave Manifest And Reconciliation
+
+Fan-out collection is machine-checkable, not prose. A reduce step that silently
+drops a worker's stream is worse than one that errors.
+
+- **Declare before dispatch.** Before dispatching a wave that delegates work,
+  declare it in the session's `waves.json` sidecar (schema:
+  `schemas/workflow-waves.schema.json`): `wave_id`, owning step, and one
+  `expected_workers` entry per worker. The expected count (M) must exist before
+  any result arrives.
+- **One terminal record per worker.** Each worker lands exactly one terminal
+  status record: `completed`, `failed`, or `blocked`. Duplicate records and
+  undeclared reporters are validation errors.
+- **Reconcile at wave close.** The orchestrator's collect step is
+  reconcile-against-manifest: record every declared worker that has no terminal
+  record as `not_reported` — never silently absorb a missing worker — then
+  record the wave's `reconciliation` with `expected_count` M, `reported_count`
+  N, and an explicit "N of M reported" summary naming the `not_reported`
+  workers (for example "2 of 3 reported; worker-3 not_reported").
+- **Incomplete is visible, never silent.** A wave is `complete` only when N
+  equals M. An incomplete wave stays visible data and routes to re-dispatch, a
+  blocker report, or an explicit accepted gap; it must never be treated as
+  complete because the missing worker was forgotten.
+- **Enforcement boundary (slice 1).** `validate-workflow-artifacts` enforces
+  the shape and the cross-record arithmetic (counts, exactly-one-record,
+  undeclared reporters, impossible `complete` claims) as data-level validation.
+  Stop-hook refusal of wave completion is #663 part 3 (slice 2), deferred until
+  the hook correctness issues (#453/#450/#494) are resolved.
 
 ## Delegation: Model Routing
 

package/dist/codex/context/contracts/review-contract.md

@@ -100,6 +100,10 @@ npm run workflow:sidecar -- import-critique .kontourai/flow-agents/<slug> \
   --reviewer tool-code-reviewer
 ```
 
+A security-review finding is recorded as a structured verdict + reference — `{severity, file_refs: ["path:line"], description: "<one-line weakness>"}` — not as reproduced exploit payloads or copied vulnerable-code blocks. A precise reference is sufficient evidence; the fuller remediation detail belongs in the fix pass, not the recorded finding. This keeps security findings recordable even when the reviewer runtime's provider content-filters exploit-shaped prose.
+
+Recording a review requires a reviewer identity distinct from the active implementation-assignment actor (anti-self-review). The identity is derived from the runtime actor, so an orchestrator that implemented cannot also review under the same actor: run the reviewer under a distinct actor — set `FLOW_AGENTS_ACTOR=<reviewer-id>` on the reviewing process, or run it in a separate runtime session.
+
 ## Gate Rules
 
 - Critical or high findings block delivery until fixed, accepted by the user, deferred with explicit rationale, or marked false positive.

package/dist/codex/context/contracts/trigger-guards.md

@@ -0,0 +1,73 @@
+# Trigger-Spawned Agent Run Guards Contract
+
+> Read [`context/contracts/standing-directives.md`](standing-directives.md) — ratified owner directives that override default engineering conservatism.
+
+Any kit, hook, or integration that spawns an agent run from a trigger MUST declare, before it ships, how that spawn surface is guarded against runaway amplification. A trigger with no dedup, cooldown, cap, or concurrency guard converts one flapping upstream signal into an unbounded stream of agent runs — each of which may hold permissions, spend budget, and mutate state without a human turn in the loop. A 2026-07 field near-miss made this concrete: an on-failure escalation wired without these guards would have spawned a continuous stream of permission-skipping agent runs from a single flapping check. This contract makes the guard requirements standing suite policy so the next trigger-driven feature inherits them by default instead of rediscovering them in an incident.
+
+## Scope
+
+A **trigger-spawned agent run** is any agent execution started by an event rather than by a human request in an interactive session: a check or CI failure escalation, a schedule firing, a watcher or automation trigger, or any other perimeter event that launches headless agent work.
+
+Out of scope:
+
+- `workflow_triggers` in kit.json — in-session workflow steering for an already-running interactive session. Steering routes an existing session; it does not spawn a run.
+- Subagent delegation inside an active, human-initiated session — the session itself is the supervision boundary.
+
+No flow-agents hook spawns agent runs today (all four hook policy classes are advisory/steering), but the suite's perimeter already does, and in-repo consumers are planned (see "Future consumers" below). The contract applies the moment a surface CAN spawn a run, not the moment it misbehaves.
+
+## Required Guard Declarations
+
+Every trigger surface that spawns agent runs declares all four guards, with explicit values. The defaults below are the starting point when the feature has no measured reason to differ; declaring a weaker value than the default requires a recorded rationale on the owning work item.
+
+| Guard | Field | Meaning | Default |
+| --- | --- | --- | --- |
+| Dedup | `dedup_key` | The trigger-signature expression used to suppress duplicate spawns while an equivalent run is pending or was recently spawned. For failure escalations: subject plus normalized failure signature (e.g. `check-name+failure-signature`), so a repeat of the same failure does not spawn a second run. | subject + trigger signature |
+| Cooldown | `cooldown_seconds` | Minimum seconds between spawns for the same subject, regardless of signature churn. | `900` |
+| Daily cap | `daily_cap` | Maximum spawns per trigger surface per day; the surface goes quiet (with a visible, non-silent skip) once reached. | `20` |
+| Concurrency lock | `max_concurrent` | Maximum runs from this surface allowed to exist simultaneously, expressed as a limit; `1` is a mutual-exclusion lock. | `1` |
+
+A skipped spawn (dedup hit, cooldown window, cap reached, lock held) must be observable — logged or counted, never silently dropped — so a guard absorbing real signal is diagnosable.
+
+## Kit Declaration: `agent_spawn_triggers`
+
+Kits declare agent-spawning trigger surfaces in kit.json through the optional `agent_spawn_triggers` extension field (Flow Agents extension-layer metadata, like `dependencies` and `workflow_triggers`):
+
+```jsonc
+"agent_spawn_triggers": [
+  {
+    "id": "on-check-failure",
+    "description": "Escalates failing checks to a headless agent run.",
+    "spawns_agent_runs": true,
+    "guards": {
+      "dedup_key": "check-name+failure-signature",
+      "cooldown_seconds": 900,
+      "daily_cap": 20,
+      "max_concurrent": 1
+    }
+  }
+]
+```
+
+- `id`: unique identifier (`^[a-z0-9]+(?:[.-][a-z0-9]+)*$`).
+- `description`: non-empty human-readable purpose of the surface.
+- `spawns_agent_runs`: required boolean. `false` documents a trigger surface that fires without spawning agent runs (e.g. notification-only); such entries need no guards.
+- `guards`: required-complete when `spawns_agent_runs` is `true` — all four fields, `dedup_key` a non-empty string, the three numeric guards integers >= 1.
+
+Hooks and integrations that live outside a kit manifest declare the same four guards, with the same vocabulary, in their own configuration or design artifact.
+
+## Enforcement
+
+Kit repository validation emits a **WARNING** (not an error) when an `agent_spawn_triggers` entry has `spawns_agent_runs: true` and missing or incomplete `guards`. Malformed declarations (wrong types, duplicate ids, non-positive limits) are shape ERRORS like every other extension field.
+
+Warning-level enforcement is deliberate, declaration-first rollout: the declaration is new and optional, and no in-repo surface spawns runs yet. When the first in-repo trigger-spawned runner ships, its surface must declare complete guards, and enforcement for spawning surfaces hardens with it (validation error and/or runtime refusal). Runtime guard enforcement is explicitly NOT part of this contract's first iteration — no spawning or guard machinery exists in this repo yet, and per standing directive 4 (standalone-first), the enforcement runtime belongs with the first real spawner.
+
+## Conforming Examples
+
+- **kontourai/plumb#1** — check-failure escalation to a headless agent with per-subject cooldown, failure-signature dedup, and a max-concurrent cap: the direct antecedent of this contract's `cooldown_seconds`, `dedup_key`, and `max_concurrent` guards.
+- **ephemeris** — trigger firing that is coalesced per claim, idempotent, and rate-limited: dedup and cap expressed as coalescing plus rate limits, showing the guards generalize beyond failure escalation.
+
+Both are cited as reference implementations of the guard vocabulary; consult their current sources when implementing a new surface.
+
+## Future Consumers
+
+The autonomy epic's background-review fork — kontourai/flow-agents#252, under epic #250 — will spawn agent runs from a trigger. Any implementation of #252 MUST declare its guard configuration under this contract (an `agent_spawn_triggers` entry with complete `guards`, or the equivalent declaration in its owning design artifact) before it ships.

package/dist/codex/context/settings/backlog-provider-settings.json

@@ -41,7 +41,7 @@
           "issue_state": "open",
           "include_labels": [],
           "ready_statuses": ["ready"],
-          "exclude_statuses": ["in_progress", "blocked", "review", "verification", "done"]
+          "exclude_statuses": ["triage", "in_progress", "blocked", "review", "verification", "done"]
         },
         "wip_policy": {
           "prefer_finishing_active_work": true,

package/dist/codex/context/settings/workspace-backlog-provider-settings.example.json

@@ -36,7 +36,7 @@
         "issue_state": "open",
         "include_labels": [],
         "ready_statuses": ["ready"],
-        "exclude_statuses": ["in_progress", "blocked", "review", "verification", "done"]
+        "exclude_statuses": ["triage", "in_progress", "blocked", "review", "verification", "done"]
       },
       "wip_policy": {
         "prefer_finishing_active_work": true,

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