@kontourai/flow-agents 4.0.0 → 4.2.0

package/.github/workflows/ci.yml

@@ -68,6 +68,10 @@ jobs:
         continue-on-error: true
         run: bash evals/ci/run-baseline.sh --check content-boundary
 
+      - name: Layer boundary
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check layer-boundary
+
       - name: Hachure boundary
         continue-on-error: true
         run: bash evals/ci/run-baseline.sh --check hachure-boundary
@@ -326,6 +330,10 @@ jobs:
         continue-on-error: true
         run: bash evals/ci/run-baseline.sh --check flow-kit-repository-integration
 
+      - name: Kit provisioning integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check kit-provisioning-integration
+
       - name: Runtime adapter activation integration
         continue-on-error: true
         run: bash evals/ci/run-baseline.sh --check runtime-adapter-activation-integration

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## [4.2.0](https://github.com/kontourai/flow-agents/compare/v4.1.0...v4.2.0) (2026-07-18)
+
+
+### Features
+
+* **liveness:** conf-driven console relay enablement ([#567](https://github.com/kontourai/flow-agents/issues/567)) + richer real-liveness signals ([#705](https://github.com/kontourai/flow-agents/issues/705)) ([b1dd5b0](https://github.com/kontourai/flow-agents/commit/b1dd5b081280d49c07d4e92ff2ffc5103dc89800))
+
+## [4.1.0](https://github.com/kontourai/flow-agents/compare/v4.0.0...v4.1.0) (2026-07-18)
+
+
+### Features
+
+* **backlog:** board-based readiness source decision + surfaced fallback warnings ([#441](https://github.com/kontourai/flow-agents/issues/441)) ([#692](https://github.com/kontourai/flow-agents/issues/692)) ([8dc292d](https://github.com/kontourai/flow-agents/commit/8dc292d8df1e25373e603fe4d81a598aed063584))
+* **ci:** enforce kits wrap the veritas engine via CLI, not as a library ([#651](https://github.com/kontourai/flow-agents/issues/651)) ([#701](https://github.com/kontourai/flow-agents/issues/701)) ([1fd0380](https://github.com/kontourai/flow-agents/commit/1fd0380ff0310d89db9c168d363a74c0df5aee04))
+* **kit:** kit-provisioning primitive — declare files a kit scaffolds into a consumer repo ([#647](https://github.com/kontourai/flow-agents/issues/647)) ([#691](https://github.com/kontourai/flow-agents/issues/691)) ([a85bdad](https://github.com/kontourai/flow-agents/commit/a85bdad05676415cd9948b470b2d5cc079d5e6c7))
+* **kits:** standing trigger-guards contract and agent_spawn_triggers validation warning ([#664](https://github.com/kontourai/flow-agents/issues/664)) ([#686](https://github.com/kontourai/flow-agents/issues/686)) ([ffcf0d9](https://github.com/kontourai/flow-agents/commit/ffcf0d98febc1815882c1586234806b831b90912))
+* **veritas-governance:** consult-standards skill — JIT guidance via veritas explain (flow-agents[#649](https://github.com/kontourai/flow-agents/issues/649)) ([#700](https://github.com/kontourai/flow-agents/issues/700)) ([f1e8db2](https://github.com/kontourai/flow-agents/commit/f1e8db288b241e55b132be5a09dbfbdc4aaaa6b7))
+* **veritas-governance:** provision governance git hooks (flow-agents[#648](https://github.com/kontourai/flow-agents/issues/648)) ([#699](https://github.com/kontourai/flow-agents/issues/699)) ([22965dd](https://github.com/kontourai/flow-agents/commit/22965ddeaf408ee9d5f8241cea60869a793a6495))
+* **veritas-governance:** scaffold starter Repo Standards via kit provisions (flow-agents[#647](https://github.com/kontourai/flow-agents/issues/647)) ([#696](https://github.com/kontourai/flow-agents/issues/696)) ([6943362](https://github.com/kontourai/flow-agents/commit/6943362e39088682fabdbef032283041a3567411))
+* **veritas-governance:** standards-authoring flow + skill ([#647](https://github.com/kontourai/flow-agents/issues/647)) ([#698](https://github.com/kontourai/flow-agents/issues/698)) ([6591a26](https://github.com/kontourai/flow-agents/commit/6591a268b8d16b41622c5203f4c97ca051170e29))
+* **workflow:** machine-checkable wave-result reconciliation manifest ([#663](https://github.com/kontourai/flow-agents/issues/663) slice 1) ([#702](https://github.com/kontourai/flow-agents/issues/702)) ([282d2fd](https://github.com/kontourai/flow-agents/commit/282d2fdd28a941e6eb2d17fcd312d2f478f5e72d))
+
+
+### Fixes
+
+* **builder:** declare pr-open-gate route-back so missing_evidence repairs at verify ([#695](https://github.com/kontourai/flow-agents/issues/695) item a) ([#697](https://github.com/kontourai/flow-agents/issues/697)) ([d8b83df](https://github.com/kontourai/flow-agents/commit/d8b83dfd484828fadca3561bc51afdfd5d691f34))
+* make workflow critique usable for single-orchestrator review ([#689](https://github.com/kontourai/flow-agents/issues/689), [#690](https://github.com/kontourai/flow-agents/issues/690)) ([#704](https://github.com/kontourai/flow-agents/issues/704)) ([a838b2e](https://github.com/kontourai/flow-agents/commit/a838b2e162e3bd31f6cc7314507f9bee7ac4ef5d))
+
+
+### Documentation
+
+* reconcile flow-agents docs to the veritas engine/kit split ([#652](https://github.com/kontourai/flow-agents/issues/652)) ([#703](https://github.com/kontourai/flow-agents/issues/703)) ([147b87a](https://github.com/kontourai/flow-agents/commit/147b87a3de14e8cc0d127e866c8136b60ab9b5b7))
+* **veritas-governance:** point to the ratified engine/surface seam doc; refresh fixed veritas[#106](https://github.com/kontourai/flow-agents/issues/106) status ([#688](https://github.com/kontourai/flow-agents/issues/688)) ([14ba90d](https://github.com/kontourai/flow-agents/commit/14ba90db7ec844286479fc0a31af1ae5c1bc12ed))
+
 ## [4.0.0](https://github.com/kontourai/flow-agents/compare/v3.12.1...v4.0.0) (2026-07-16)
 
 

package/CONTEXT.md

@@ -196,6 +196,11 @@ _Avoid_: Boundary Crossing as the generic Flow Agents term
 An executable backlog or queue unit selected by a workflow. Work Items are provider-backed when a backlog provider is configured, and Flow Agents keeps a portable local-first Kontour Resource Contract shape for local use, tests, kit demos, and migration. A Work Item is smaller than an Initiative and large enough to move through one coherent Workflow Run with clear acceptance evidence.
 _Avoid_: Task as the generic term, Issue as the provider-neutral term
 
+### Backlog Readiness Source
+
+The provider-backed signal that marks a Work Item intentionally ready for pickup, read by `pull-work` to build the ready queue. The readiness source is declared by backlog provider settings (currently the configured BoardProvider's ready statuses); a configured readiness source that yields nothing is a surfaced warning, never a silent fallback to unranked issue listing. The live decision is recorded in `docs/decisions/backlog-readiness-source.md`.
+_Avoid_: ready label, board status as interchangeable generic terms
+
 ### Work Item Group
 
 A Builder Kit Selected Scope containing multiple related Work Items delivered through one Delivery Run because grouping reduces coordination risk and preserves one coherent acceptance and evidence story. Work Item Groups are exceptions justified by `pull-work`; they do not replace Initiatives.

package/agents/tool-security-reviewer.json

@@ -51,6 +51,6 @@
   "tools" : [ "read", "imageRead", "glob", "grep", "ls", "code", "shell" ],
   "name" : "tool-security-reviewer",
   "description" : "Delegate to me for security analysis. Checks OWASP Top 10, secrets detection, input validation, injection vulnerabilities, auth/authz, and rate limiting. Read-only analysis with shell for scanning tools.",
-  "prompt" : "You are a security reviewer. You analyze source code for vulnerabilities and produce a structured security report.\n\n## Input\nYou receive:\n- A list of files to review\n- Optional focus area (auth, input handling, DB, etc.)\n\n## Security Checklist\n\nFor each file, check:\n- **Hardcoded secrets**: API keys, tokens, passwords, connection strings, private keys\n- **SQL injection**: string concatenation in queries, missing parameterization\n- **XSS**: unescaped user input in HTML/templates, innerHTML usage\n- **CSRF**: missing CSRF tokens on state-changing endpoints\n- **Path traversal**: user input in file paths without sanitization\n- **Auth bypasses**: missing auth checks, broken access control, privilege escalation\n- **Rate limiting**: unprotected endpoints susceptible to abuse\n- **Error leakage**: stack traces, internal paths, or system info in error responses\n- **Dependency vulnerabilities**: run npm audit / pip-audit / cargo audit if available\n\n## OWASP Top 10 Mapping\n\nTag each finding with its OWASP category:\n- A01: Broken Access Control\n- A02: Cryptographic Failures\n- A03: Injection\n- A04: Insecure Design\n- A05: Security Misconfiguration\n- A06: Vulnerable Components\n- A07: Auth Failures\n- A08: Data Integrity Failures\n- A09: Logging Failures\n- A10: SSRF\n\n## Trigger Conditions\n\nPrioritize review of code involving:\n- Authentication or authorization logic\n- User input handling (forms, query params, headers)\n- Database queries\n- File system operations\n- External API calls\n- Cryptographic operations\n- Payment or financial code\n\n## Secret Patterns\n\nScan for common patterns:\n- `AKIA[0-9A-Z]{16}` (AWS access keys)\n- `-----BEGIN (RSA |EC )?PRIVATE KEY-----`\n- `(password|secret|token|api_key)\\s*[:=]\\s*['\"][^'\"]+['\"]`\n- Base64-encoded strings >40 chars in assignments\n\n## Output\n\nReturn a structured security report:\n```markdown\n## Security Review\n\nFiles analyzed: <count>\nFindings: <count by severity>\n\n### Findings\n\n#### [CRITICAL/HIGH/MEDIUM/LOW] <OWASP-ID> — <file>:<line> — <title>\n<description with evidence>\n**Remediation:** <specific fix>\n\n### Summary\n<overall assessment>\n```\n\n## Rules\n- No false positives without evidence. Show the vulnerable code.\n- Run dependency audit tools if available (npm audit, pip-audit, cargo audit).\n- If no security issues found, say so clearly — don't invent findings.\n- This is read-only analysis. Do not modify any files.",
+  "prompt" : "You are a security reviewer. You analyze source code for vulnerabilities and produce a structured security report.\n\n## Input\nYou receive:\n- A list of files to review\n- Optional focus area (auth, input handling, DB, etc.)\n\n## Security Checklist\n\nFor each file, check:\n- **Hardcoded secrets**: API keys, tokens, passwords, connection strings, private keys\n- **SQL injection**: string concatenation in queries, missing parameterization\n- **XSS**: unescaped user input in HTML/templates, innerHTML usage\n- **CSRF**: missing CSRF tokens on state-changing endpoints\n- **Path traversal**: user input in file paths without sanitization\n- **Auth bypasses**: missing auth checks, broken access control, privilege escalation\n- **Rate limiting**: unprotected endpoints susceptible to abuse\n- **Error leakage**: stack traces, internal paths, or system info in error responses\n- **Dependency vulnerabilities**: run npm audit / pip-audit / cargo audit if available\n\n## OWASP Top 10 Mapping\n\nTag each finding with its OWASP category:\n- A01: Broken Access Control\n- A02: Cryptographic Failures\n- A03: Injection\n- A04: Insecure Design\n- A05: Security Misconfiguration\n- A06: Vulnerable Components\n- A07: Auth Failures\n- A08: Data Integrity Failures\n- A09: Logging Failures\n- A10: SSRF\n\n## Trigger Conditions\n\nPrioritize review of code involving:\n- Authentication or authorization logic\n- User input handling (forms, query params, headers)\n- Database queries\n- File system operations\n- External API calls\n- Cryptographic operations\n- Payment or financial code\n\n## Secret Patterns\n\nScan for common patterns:\n- `AKIA[0-9A-Z]{16}` (AWS access keys)\n- `-----BEGIN (RSA |EC )?PRIVATE KEY-----`\n- `(password|secret|token|api_key)\\s*[:=]\\s*['\"][^'\"]+['\"]`\n- Base64-encoded strings >40 chars in assignments\n\n## Output\n\nReturn a structured security report:\n```markdown\n## Security Review\n\nFiles analyzed: <count>\nFindings: <count by severity>\n\n### Findings\n\n#### [CRITICAL/HIGH/MEDIUM/LOW] <OWASP-ID> — <file>:<line> — <title>\n<description with evidence>\n**Remediation:** <specific fix>\n\n### Summary\n<overall assessment>\n```\n\n## Rules\n- No false positives without evidence: cite the exact `file:line` and a one-line description of the weakness as the evidence.\n- Do NOT reproduce exploit payloads, working attack strings, or large copied blocks of vulnerable code in the report. A precise `file:line` reference plus a short description IS the evidence — reproduction detail belongs in the fix pass, not the recorded finding. (This keeps security findings recordable through `workflow critique`, whose reviewer runtime's provider may content-filter exploit-shaped prose.)\n- Run dependency audit tools if available (npm audit, pip-audit, cargo audit).\n- If no security issues found, say so clearly — don't invent findings.\n- This is read-only analysis. Do not modify any files.",
   "model" : "claude-sonnet-4.6-1m"
 }

package/build/src/cli/init.js

@@ -8,6 +8,7 @@ import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 import { parseArgs, flagBool, flagList, flagString } from "../lib/args.js";
 import { activateCodexLocal } from "../runtime-adapters.js";
+import { provisionKit, ProvisionConflictError } from "../flow-kit/provision.js";
 import { main as buildBundles } from "../tools/build-universal-bundles.js";
 import { root } from "../tools/common.js";
 import { defaultCodexHome, durableInstallRecordPath, skillsManifestPath } from "../lib/local-artifact-root.js";
@@ -571,7 +572,21 @@ function installBundle(bundle, options) {
     }
     return result.status ?? 1;
 }
-function activateKits(options) {
+function kitPathForInit(kitId, dest) {
+    const catalogPath = path.join(root, "kits", "catalog.json");
+    if (fs.existsSync(catalogPath)) {
+        const catalog = JSON.parse(fs.readFileSync(catalogPath, "utf8"));
+        const entry = Array.isArray(catalog.kits)
+            ? catalog.kits.find((item) => typeof item === "object" && item !== null && item.id === kitId)
+            : undefined;
+        const rel = entry && typeof entry === "object" ? entry.path : undefined;
+        if (typeof rel === "string")
+            return path.resolve(root, rel);
+    }
+    const installed = path.join(dest, "kits", "local", "repositories", kitId);
+    return fs.existsSync(installed) ? installed : null;
+}
+async function activateKits(options) {
     const activeKitIds = options.activeKitIds ?? [];
     if (!options.activateKits || activeKitIds.length === 0 || options.runtime !== "codex")
         return 0;
@@ -582,6 +597,23 @@ function activateKits(options) {
     }
     const generated = Array.isArray(result.generated_runtime_files) ? result.generated_runtime_files : [];
     console.log(`Activated ${generated.length} Codex local runtime asset(s)`);
+    for (const kitId of activeKitIds) {
+        const kitDir = kitPathForInit(kitId, options.dest);
+        if (!kitDir)
+            throw new Error(`activated kit '${kitId}' could not be resolved for provisioning`);
+        try {
+            const provisioned = await provisionKit(kitDir, options.dest);
+            if (provisioned.files.length > 0)
+                console.log(`Provisioned ${provisioned.files.length} file(s) from kit '${kitId}'`);
+        }
+        catch (error) {
+            if (!(error instanceof ProvisionConflictError))
+                throw error;
+            for (const conflict of error.conflicts) {
+                console.warn(`flow-agents init: warning: skipped existing provision '${conflict.target}' from kit '${kitId}'`);
+            }
+        }
+    }
     return 0;
 }
 /**
@@ -809,7 +841,7 @@ export async function main(argv = process.argv.slice(2)) {
             if (installed !== 0)
                 return installed;
             writeInstallRecord(options.dest, "codex", true, options.activeKitIds ?? []);
-            return activateKits(options);
+            return await activateKits(options);
         }
         // --global for pi: NOT_VERIFIED (no documented global dir). Warn and fall through to workspace install.
         if (options.global && options.runtime === "pi") {
@@ -822,7 +854,7 @@ export async function main(argv = process.argv.slice(2)) {
         if (installed !== 0)
             return installed;
         writeInstallRecord(options.dest, options.runtime, options.global, options.activeKitIds ?? []);
-        const activated = activateKits(options);
+        const activated = await activateKits(options);
         // G2/G3: shared post-install auto-verify + summary tail. Applies
         // identically whether main() reached here via headlessOptions() or
         // interactiveOptions() -- never changes `activated`'s exit code.

package/build/src/cli/kit.js

@@ -6,7 +6,8 @@ import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs, flagBool, flagString } from "../lib/args.js";
 import { assertPathContained, assertPathsDisjoint, atomicWriteJson, copyDirAtomic, ensureSafeDirectory, isoNow, readJson, walkFiles } from "../lib/fs.js";
-import { assertKitRepository, deriveKitTargets, parseKitDependencies } from "../flow-kit/validate.js";
+import { assertKitRepository, deriveKitTargets, parseKitDependencies, validateKitRepositoryDiagnostics } from "../flow-kit/validate.js";
+import { provisionKit, ProvisionConflictError } from "../flow-kit/provision.js";
 import { activateCodexLocal, activateStrandsLocal } from "../runtime-adapters.js";
 import { defaultCodexHome } from "../lib/local-artifact-root.js";
 import { root } from "../tools/common.js";
@@ -35,6 +36,18 @@ function resolveCatalogKitSource(source) {
         return null;
     return path.resolve(path.dirname(repoCatalogPath), "..", rel);
 }
+function resolveProvisionKitSource(source, dest) {
+    const localPath = path.resolve(source);
+    if (fs.existsSync(localPath))
+        return localPath;
+    const installed = loadRegistry(dest).kits.find((entry) => entry.id === source);
+    if (installed) {
+        const installedSource = installedPath(dest, source);
+        if (fs.existsSync(installedSource))
+            return installedSource;
+    }
+    return resolveCatalogKitSource(source);
+}
 function loadRegistry(dest) {
     const file = registryPath(dest);
     if (!fs.existsSync(file))
@@ -64,6 +77,17 @@ function warnUninstalledDependencies(manifest, manifestPath, dest) {
         }
     }
 }
+/**
+ * Print non-blocking kit-validation warnings (e.g. an agent-spawning trigger surface
+ * declared without complete guard config — context/contracts/trigger-guards.md).
+ * Shared by BOTH install source forms (local path and git clone) so the standing
+ * warning contract cannot silently diverge between them. Same non-blocking
+ * `warning:` convention as warnUninstalledDependencies above.
+ */
+async function printKitValidationWarnings(kitDir) {
+    for (const warning of (await validateKitRepositoryDiagnostics(kitDir)).warnings)
+        console.log(`warning: ${warning}`);
+}
 function contentHash(root) {
     const hash = crypto.createHash("sha256");
     for (const file of walkFiles(root)) {
@@ -122,6 +146,7 @@ async function installLocalSource(source, argv) {
     let manifest;
     try {
         manifest = await assertKitRepository(source);
+        await printKitValidationWarnings(source);
     }
     catch (error) {
         console.log("Flow Kit repository validation failed:");
@@ -211,6 +236,7 @@ async function installGitSource(rawUrl, argv) {
         let manifest;
         try {
             manifest = await assertKitRepository(tmpBase);
+            await printKitValidationWarnings(tmpBase);
         }
         catch (error) {
             console.log("Flow Kit repository validation failed:");
@@ -321,6 +347,69 @@ function activate(argv) {
     console.log(JSON.stringify(result, null, 2));
     return Array.isArray(result.errors) && result.errors.length ? 1 : 0;
 }
+async function validate(argv) {
+    const args = parseArgs(argv);
+    const kitDir = path.resolve(args.positionals[0] ?? ".");
+    const diagnostics = await validateKitRepositoryDiagnostics(kitDir);
+    for (const warning of diagnostics.warnings)
+        console.log(`warning: ${warning}`);
+    if (diagnostics.errors.length) {
+        console.log("Flow Kit repository validation failed:");
+        for (const error of diagnostics.errors)
+            console.log(` - ${error}`);
+        return 1;
+    }
+    console.log(`Flow Kit repository validation passed: ${kitDir}`);
+    return 0;
+}
+async function provision(argv) {
+    const args = parseArgs(argv);
+    const source = args.positionals[0];
+    if (!source) {
+        console.error("provision: missing <kit-id-or-path> argument");
+        console.error("usage: flow-agents kit provision <kit-id-or-path> [--target <dir>] [--force] [--dry-run]");
+        return 2;
+    }
+    const dest = resolveDest(args.flags);
+    const kitDir = resolveProvisionKitSource(source, dest);
+    if (!kitDir) {
+        console.error(`provision: kit '${source}' was not found as a local path, installed kit, or catalog kit`);
+        return 1;
+    }
+    const target = path.resolve(flagString(args.flags, "target", process.cwd()) ?? process.cwd());
+    try {
+        const result = await provisionKit(kitDir, target, {
+            force: flagBool(args.flags, "force"),
+            dryRun: flagBool(args.flags, "dry-run"),
+        });
+        for (const file of result.files)
+            console.log(`${result.dry_run ? "would provision" : "provisioned"}: ${file.source} -> ${file.destination}`);
+        if (result.dry_run)
+            console.log(`dry-run: ${result.files.length} file(s) declared by kit '${result.kit_id}'; no files written`);
+        else if (result.files.length === 0)
+            console.log(`kit '${result.kit_id}' declares no provisions`);
+        else
+            console.log(`provisioned ${result.files.length} file(s) from kit '${result.kit_id}' into ${target}`);
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof ProvisionConflictError) {
+            console.error(`provision: ${error.message}; rerun with --force to overwrite`);
+            for (const conflict of error.conflicts)
+                console.error(`conflict: ${conflict.target} (${conflict.destination})`);
+            return 1;
+        }
+        const diagnostics = error.diagnostics;
+        if (diagnostics?.length) {
+            console.error("Flow Kit repository validation failed:");
+            for (const diagnostic of diagnostics)
+                console.error(` - ${diagnostic}`);
+        }
+        else
+            console.error(`provision: ${error.message}`);
+        return 1;
+    }
+}
 /**
  * inspect <kit-dir> [--json]
  *
@@ -375,9 +464,13 @@ export async function main(argv = process.argv.slice(2)) {
         return status(rest);
     if (command === "activate")
         return activate(rest);
+    if (command === "validate")
+        return await validate(rest);
+    if (command === "provision")
+        return await provision(rest);
     if (command === "inspect")
         return await inspect(rest);
-    console.error("usage: flow-agents kit <install|activate|inspect|list|status> ...");
+    console.error("usage: flow-agents kit <install|activate|validate|provision|inspect|list|status> ...");
     return 2;
 }
 // Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.

package/build/src/cli/pull-work-provider.js

@@ -804,7 +804,13 @@ export function main(argv = process.argv.slice(2)) {
         const freshness = revisionFreshness(item, freshnessInputs);
         return { ...item, dependency_impacts: dependencyImpacts(item, resolved), revision_freshness: freshness, readiness: applyFreshnessToReadiness(classify(item, settings, resolved), freshness) };
     });
-    console.log(JSON.stringify({ items }, null, 2));
+    // A configured BoardProvider is the canonical readiness source (docs/decisions/backlog-readiness-source.md).
+    // Reaching this issue-level listing path with a board configured is a bypass that must be loud, never silent.
+    const bypassedBoard = asRecord(asRecord(settings.board_provider)?.board);
+    const warnings = bypassedBoard
+        ? [{ code: "board_provider_bypassed", message: "A BoardProvider is configured but this pass used WorkItemProvider issue-level listing; board-driven selection is the canonical readiness source. Surface this bypass in the pull-work artifact instead of treating issue listing as a silent fallback." }]
+        : [];
+    console.log(JSON.stringify({ items, warnings }, null, 2));
     return 0;
 }
 // Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.

package/build/src/cli/validate-workflow-artifacts.js

@@ -18,6 +18,7 @@ const sidecarSchemas = {
     "critique.json": "schemas/workflow-critique.schema.json",
     "release.json": "schemas/workflow-release.schema.json",
     "learning.json": "schemas/workflow-learning.schema.json",
+    "waves.json": "schemas/workflow-waves.schema.json",
 };
 // Runtime coordination records live below a session but are not workflow
 // sidecars. Recursing into them would validate continuation-driver/state.json
@@ -386,11 +387,63 @@ function validateSidecar(file) {
                 issues.push({ path: file, message: "deploy decision requires post_deploy_checks to be planned or pass" });
         }
     }
+    if (path.basename(file) === "waves.json") {
+        validateWaves(file, value, issues);
+    }
     if (path.basename(file) === "state.json" && value && typeof value === "object" && !Array.isArray(value) && !("branch" in value)) {
         warnings.push({ path: file, message: "state.json has no branch field (legacy/pre-#289 session) — re-run `ensure-session` to backfill agent/<actor>/<slug>." });
     }
     return { issues, warnings };
 }
+// #663 slice 1: wave-result reconciliation is machine-checkable, not prose. The schema
+// (schemas/workflow-waves.schema.json) validates the shape; these semantic checks enforce the
+// cross-record arithmetic the mini schema engine cannot express: exactly one terminal status
+// record per declared worker, no undeclared reporters, reconciliation counts that match the
+// records, and a `complete` claim that is impossible while any expected worker lacks a
+// worker-landed terminal status. Missing workers must be recorded explicitly as not_reported —
+// a reconciled wave never silently absorbs a dropped worker. Enforcement here is data-level
+// validation only; stop-hook refusal of wave completion is #663 part 3 (slice 2).
+function validateWaves(file, value, issues) {
+    const waves = Array.isArray(value?.waves) ? value.waves : [];
+    waves.forEach((wave, index) => {
+        const loc = `waves.json.waves[${index}]`;
+        const expected = Array.isArray(wave?.expected_workers) ? wave.expected_workers : [];
+        const results = Array.isArray(wave?.worker_results) ? wave.worker_results : [];
+        const expectedIds = expected.map((w) => w?.worker_id).filter((id) => typeof id === "string" && id.length > 0);
+        const expectedIdSet = new Set(expectedIds);
+        if (expectedIdSet.size !== expectedIds.length)
+            issues.push({ path: file, message: `${loc}.expected_workers must declare unique worker_id values` });
+        const resultIds = results.map((r) => r?.worker_id).filter((id) => typeof id === "string" && id.length > 0);
+        const seen = new Set();
+        for (const id of resultIds) {
+            if (seen.has(id))
+                issues.push({ path: file, message: `${loc}.worker_results has more than one terminal status record for worker ${id}; each worker lands exactly one` });
+            seen.add(id);
+            if (!expectedIdSet.has(id))
+                issues.push({ path: file, message: `${loc}.worker_results records worker ${id} that is not declared in expected_workers; declare every worker in the manifest before dispatch` });
+        }
+        const reconciliation = wave?.reconciliation;
+        if (!reconciliation || typeof reconciliation !== "object" || Array.isArray(reconciliation))
+            return;
+        const expectedCount = expectedIds.length;
+        const reportedIds = new Set(results.filter((r) => ["completed", "failed", "blocked"].includes(r?.status) && expectedIdSet.has(r?.worker_id)).map((r) => r.worker_id));
+        const reportedCount = reportedIds.size;
+        if (reconciliation.expected_count !== expectedCount)
+            issues.push({ path: file, message: `${loc}.reconciliation.expected_count is ${reconciliation.expected_count} but expected_workers declares ${expectedCount}` });
+        if (reconciliation.reported_count !== reportedCount)
+            issues.push({ path: file, message: `${loc}.reconciliation.reported_count is ${reconciliation.reported_count} but ${reportedCount} of ${expectedCount} expected workers have a worker-landed terminal status (completed|failed|blocked)` });
+        const missing = expectedIds.filter((id) => !results.some((r) => r?.worker_id === id));
+        for (const id of missing)
+            issues.push({ path: file, message: `${loc} is reconciled but worker ${id} has no terminal status record; record it explicitly as not_reported — never silently absorb a missing worker` });
+        const notReported = results.filter((r) => r?.status === "not_reported" && expectedIdSet.has(r?.worker_id));
+        if (reconciliation.status === "complete" && (missing.length > 0 || notReported.length > 0 || reportedCount !== expectedCount)) {
+            issues.push({ path: file, message: `${loc}.reconciliation.status complete requires every expected worker to have a worker-landed terminal status; got ${reportedCount} of ${expectedCount} reported` });
+        }
+        if (reconciliation.status === "incomplete" && missing.length === 0 && notReported.length === 0 && reportedCount === expectedCount) {
+            issues.push({ path: file, message: `${loc}.reconciliation.status incomplete contradicts the records: all ${expectedCount} expected workers reported` });
+        }
+    });
+}
 function validateLearningCorrections(file, status, records, issues) {
     records.forEach((record, index) => {
         const correction = record?.correction;

package/build/src/cli/workflow.js

@@ -733,7 +733,11 @@ function assertDistinctReviewActor(sessionDir, slug) {
     const assignment = readActiveAssignment(sessionDir, slug);
     const caller = resolveCurrentAssignmentActor();
     if (assignment.actor_key === caller.actorKey) {
-        throw new Error("workflow critique requires a reviewer identity distinct from the active implementation assignment actor");
+        throw new Error("workflow critique requires a reviewer identity distinct from the active implementation assignment actor. " +
+            "The reviewer identity is derived from the runtime actor, so an orchestrator that implemented and now reviews " +
+            "resolves to the same actor. To record an independent review, run the reviewer under a distinct actor: set " +
+            "FLOW_AGENTS_ACTOR=<reviewer-id> on the reviewing process, or run the reviewer in a separate runtime session " +
+            "(the runtime session id seeds the actor).");
     }
     return caller;
 }

package/build/src/flow-kit/provision.d.ts

@@ -0,0 +1,23 @@
+export type ProvisionedFile = {
+    id: string;
+    target: string;
+};
+export type ProvisionPlanEntry = ProvisionedFile & {
+    source: string;
+    destination: string;
+};
+export type ProvisionResult = {
+    kit_id: string;
+    kit_hash?: string;
+    files: ProvisionPlanEntry[];
+    manifest_path?: string;
+    dry_run: boolean;
+};
+export declare class ProvisionConflictError extends Error {
+    readonly conflicts: ProvisionPlanEntry[];
+    constructor(conflicts: ProvisionPlanEntry[]);
+}
+export declare function provisionKit(kitDir: string, targetDir: string, options?: {
+    force?: boolean;
+    dryRun?: boolean;
+}): Promise<ProvisionResult>;

package/build/src/flow-kit/provision.js

@@ -0,0 +1,99 @@
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { atomicCopyFile, atomicWriteJson, canonicalProspectivePath, walkFiles } from "../lib/fs.js";
+import { PROVISION_MANIFEST_DIR, assertKitRepository } from "./validate.js";
+export class ProvisionConflictError extends Error {
+    conflicts;
+    constructor(conflicts) {
+        super(`provisioning conflicts with ${conflicts.length} existing destination(s)`);
+        this.name = "ProvisionConflictError";
+        this.conflicts = conflicts;
+    }
+}
+function kitContentHash(kitDir) {
+    const hash = crypto.createHash("sha256");
+    for (const file of walkFiles(kitDir)) {
+        const rel = path.relative(kitDir, file).split(path.sep).join("/");
+        if (rel.split("/").some((part) => [".git", "__pycache__", ".pytest_cache"].includes(part)))
+            continue;
+        hash.update(rel);
+        hash.update("\0");
+        hash.update(fs.readFileSync(file));
+        hash.update("\0");
+    }
+    return `sha256:${hash.digest("hex")}`;
+}
+function isContained(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative !== "" && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+function assertSafeDestination(rootReal, destination) {
+    const prospective = canonicalProspectivePath(destination);
+    if (!isContained(rootReal, prospective))
+        throw new Error(`provision target escapes consumer repository: ${destination}`);
+    if (!fs.existsSync(destination))
+        return;
+    const stat = fs.lstatSync(destination);
+    if (stat.isSymbolicLink())
+        throw new Error(`refusing provision target symlink: ${destination}`);
+    if (!stat.isFile())
+        throw new Error(`provision target is not a regular file: ${destination}`);
+}
+function manifestProvisions(manifest) {
+    if (!Array.isArray(manifest.provisions))
+        return [];
+    return manifest.provisions.map((entry) => {
+        const record = entry;
+        return {
+            id: String(record.id),
+            path: String(record.path),
+            target: path.posix.normalize(String(record.target).replace(/\\/g, "/")),
+            ...(typeof record.description === "string" ? { description: record.description } : {}),
+        };
+    });
+}
+export async function provisionKit(kitDir, targetDir, options = {}) {
+    const kitRoot = fs.realpathSync(path.resolve(kitDir));
+    const targetPath = path.resolve(targetDir);
+    if (!fs.existsSync(targetPath) || !fs.statSync(targetPath).isDirectory()) {
+        throw new Error(`provision target must exist and be a directory: ${targetPath}`);
+    }
+    const targetRoot = fs.realpathSync(targetPath);
+    const manifest = await assertKitRepository(kitRoot);
+    const kitId = String(manifest.id);
+    const files = manifestProvisions(manifest).map((entry) => ({
+        id: entry.id,
+        target: entry.target,
+        source: path.resolve(kitRoot, entry.path),
+        destination: path.resolve(targetRoot, ...entry.target.split("/")),
+    }));
+    for (const file of files)
+        assertSafeDestination(targetRoot, file.destination);
+    // Defense in depth against a source swapped to a link after validation: re-assert the
+    // link-resolved source stays inside the kit before we read and copy its bytes.
+    for (const file of files) {
+        const realSource = fs.realpathSync(file.source);
+        if (realSource !== kitRoot && !realSource.startsWith(`${kitRoot}${path.sep}`)) {
+            throw new Error(`provision source escapes the kit directory: ${file.id}`);
+        }
+    }
+    const conflicts = options.force ? [] : files.filter((file) => fs.existsSync(file.destination));
+    if (conflicts.length)
+        throw new ProvisionConflictError(conflicts);
+    const kitHash = kitContentHash(kitRoot);
+    if (options.dryRun || files.length === 0)
+        return { kit_id: kitId, kit_hash: kitHash, files, dry_run: Boolean(options.dryRun) };
+    const manifestPath = path.join(targetRoot, ...PROVISION_MANIFEST_DIR.split("/"), `${kitId}.json`);
+    assertSafeDestination(targetRoot, manifestPath);
+    for (const file of files)
+        atomicCopyFile(targetRoot, file.source, file.destination);
+    atomicWriteJson(targetRoot, manifestPath, {
+        schema_version: "1.0",
+        kit_id: kitId,
+        kit_hash: kitHash,
+        provisioned_at: new Date().toISOString(),
+        files: files.map(({ id, target }) => ({ id, target })),
+    });
+    return { kit_id: kitId, kit_hash: kitHash, files, manifest_path: manifestPath, dry_run: false };
+}

package/build/src/flow-kit/validate.d.ts

@@ -4,6 +4,13 @@ export interface KitDependencyEntry {
     kit_id: string;
     reason?: string;
 }
+export interface KitProvisionEntry {
+    id: string;
+    path: string;
+    target: string;
+    description?: string;
+}
+export declare const PROVISION_MANIFEST_DIR = ".kontourai/flow-agents/provisions";
 export interface KitWorkflowTriggerEntry {
     id: string;
     when: string;
@@ -25,6 +32,18 @@ export interface KitHookInfluenceExpectationEntry {
     must_include_guidance: string[];
     must_include_actions: string[];
 }
+export interface KitAgentSpawnTriggerGuards {
+    dedup_key: string;
+    cooldown_seconds: number;
+    daily_cap: number;
+    max_concurrent: number;
+}
+export interface KitAgentSpawnTriggerEntry {
+    id: string;
+    description: string;
+    spawns_agent_runs: boolean;
+    guards?: KitAgentSpawnTriggerGuards;
+}
 export type KitSkillRole = "entrypoint" | "profile" | "step" | "shared-primitive" | "extension";
 export interface KitSkillRoleEntry {
     skill_id: string;
@@ -61,6 +80,29 @@ export declare function parseKitHookInfluenceExpectations(manifest: Record<strin
     entries: KitHookInfluenceExpectationEntry[];
     errors: string[];
 };
+/**
+ * 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 declare function parseKitAgentSpawnTriggers(manifest: Record<string, unknown>, manifestPath: string): {
+    entries: KitAgentSpawnTriggerEntry[];
+    errors: string[];
+    warnings: string[];
+};
 export declare function parseKitSkillRoles(manifest: Record<string, unknown>, manifestPath: string): {
     entries: KitSkillRoleEntry[];
     errors: string[];
@@ -126,4 +168,14 @@ export interface KitTargetsResult {
  */
 export declare function deriveKitTargets(manifest: Record<string, unknown>, kitDir?: string, sourceRoot?: string): Promise<KitTargetsResult>;
 export declare function validateKitRepository(kitDir: string): Promise<string[]>;
+/**
+ * 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 declare function validateKitRepositoryDiagnostics(kitDir: string): Promise<{
+    errors: string[];
+    warnings: string[];
+}>;
 export declare function assertKitRepository(kitDir: string): Promise<Record<string, unknown>>;