@kontourai/flow-agents 4.0.0 → 4.1.0

package/schemas/workflow-waves.schema.json

@@ -0,0 +1,347 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flow-agents.dev/schemas/workflow-waves.schema.json",
+  "title": "Flow Agents Workflow Waves",
+  "description": "Fan-out wave manifest for a workflow session. Each wave declares its expected workers (M) before dispatch; every worker lands exactly one terminal status record; the orchestrator reconciles worker_results against expected_workers at wave close and records an explicit 'N of M reported' reconciliation. A worker that never reported is recorded as not_reported — visible data, never silently absorbed. This sidecar is additive: a session without waves.json declares no fan-out and is unaffected.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "task_slug",
+    "waves"
+  ],
+  "$defs": {
+    "evidence_ref": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "kind"
+      ],
+      "properties": {
+        "kind": {
+          "type": "string",
+          "enum": [
+            "source",
+            "command",
+            "artifact",
+            "provider",
+            "external"
+          ]
+        },
+        "url": {
+          "type": "string",
+          "minLength": 1
+        },
+        "file": {
+          "type": "string",
+          "minLength": 1
+        },
+        "line_start": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "line_end": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "excerpt": {
+          "type": "string",
+          "minLength": 1
+        },
+        "summary": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "type": "object",
+            "properties": {
+              "kind": {
+                "const": "source"
+              }
+            },
+            "required": [
+              "kind"
+            ]
+          },
+          "then": {
+            "required": [
+              "file",
+              "line_start",
+              "line_end",
+              "excerpt"
+            ]
+          }
+        },
+        {
+          "if": {
+            "type": "object",
+            "properties": {
+              "kind": {
+                "const": "artifact"
+              }
+            },
+            "required": [
+              "kind"
+            ]
+          },
+          "then": {
+            "allOf": [
+              {
+                "anyOf": [
+                  {
+                    "type": "object",
+                    "required": [
+                      "file"
+                    ]
+                  },
+                  {
+                    "type": "object",
+                    "required": [
+                      "url"
+                    ]
+                  }
+                ]
+              },
+              {
+                "anyOf": [
+                  {
+                    "type": "object",
+                    "required": [
+                      "summary"
+                    ]
+                  },
+                  {
+                    "type": "object",
+                    "required": [
+                      "excerpt"
+                    ]
+                  }
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "if": {
+            "type": "object",
+            "properties": {
+              "kind": {
+                "const": "command"
+              }
+            },
+            "required": [
+              "kind"
+            ]
+          },
+          "then": {
+            "anyOf": [
+              {
+                "type": "object",
+                "required": [
+                  "excerpt"
+                ]
+              },
+              {
+                "type": "object",
+                "required": [
+                  "summary"
+                ]
+              },
+              {
+                "type": "object",
+                "required": [
+                  "url"
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "if": {
+            "type": "object",
+            "properties": {
+              "kind": {
+                "enum": [
+                  "provider",
+                  "external"
+                ]
+              }
+            },
+            "required": [
+              "kind"
+            ]
+          },
+          "then": {
+            "required": [
+              "url"
+            ]
+          }
+        }
+      ]
+    },
+    "expected_worker": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "worker_id",
+        "task"
+      ],
+      "properties": {
+        "worker_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "task": {
+          "type": "string",
+          "minLength": 1
+        },
+        "role": {
+          "type": "string",
+          "minLength": 1
+        },
+        "owned_files": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "worker_result": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "worker_id",
+        "status",
+        "summary",
+        "recorded_at"
+      ],
+      "properties": {
+        "worker_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "status": {
+          "type": "string",
+          "enum": [
+            "completed",
+            "failed",
+            "blocked",
+            "not_reported"
+          ]
+        },
+        "summary": {
+          "type": "string",
+          "minLength": 1
+        },
+        "recorded_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "evidence_refs": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/evidence_ref"
+          }
+        }
+      }
+    },
+    "reconciliation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "status",
+        "expected_count",
+        "reported_count",
+        "summary",
+        "reconciled_at"
+      ],
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": [
+            "complete",
+            "incomplete"
+          ]
+        },
+        "expected_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "reported_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "summary": {
+          "type": "string",
+          "minLength": 1
+        },
+        "reconciled_at": {
+          "type": "string",
+          "format": "date-time"
+        }
+      }
+    },
+    "wave": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "wave_id",
+        "step",
+        "declared_at",
+        "expected_workers"
+      ],
+      "properties": {
+        "wave_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "step": {
+          "type": "string",
+          "minLength": 1
+        },
+        "declared_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "expected_workers": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/expected_worker"
+          }
+        },
+        "worker_results": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/worker_result"
+          }
+        },
+        "reconciliation": {
+          "$ref": "#/$defs/reconciliation"
+        }
+      }
+    }
+  },
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "1.0"
+    },
+    "task_slug": {
+      "type": "string",
+      "minLength": 1
+    },
+    "waves": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/wave"
+      }
+    }
+  }
+}

package/scripts/check-layer-boundary.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+/**
+ * check-layer-boundary — kit/engine layer-doctrine ratchet.
+ *
+ * Doctrine (veritas docs/architecture/engine-surface-seam.md, Invariant 3; ADR 0008/0016):
+ * kits distribute by copy/activate/CLI and consume a product engine via CLI + artifacts, NEVER
+ * as an npm library import. A kit that `import`s the veritas evaluation engine would fork the
+ * layer boundary — the kit must wrap the engine's CLI, not link its code. This is the executable
+ * enforcement of that invariant (flow-agents#651).
+ *
+ * FAILS if any tracked file under kits/ imports `@kontourai/veritas` (or its `/engine` subpath),
+ * or if any kit.json declares it as a dependency. The kit's trust-bundle adapter may import
+ * `@kontourai/surface` (the open trust format, Layer 3) — that is the sanctioned channel and is
+ * NOT matched here. No allowlist: the count is zero today and must stay zero.
+ *
+ * Not a violation (and not matched — import-syntax-scoped): the many descriptive strings naming
+ * "@kontourai/veritas" in kit.json descriptions, docs, and recorded CLI-output fixtures are prose
+ * and data, not code imports.
+ */
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+
+// Match import/require/dynamic-import of the veritas package (root or /engine subpath) only, so
+// prose/fixture mentions of the package name can never trip it — only an actual code link does.
+const PKG = String.raw`@kontourai/veritas(?:/[A-Za-z0-9_./-]+)?`;
+const IMPORT_PATTERNS = [
+  new RegExp(String.raw`from\s+['"](?:${PKG})['"]`),
+  new RegExp(String.raw`require(?:\.resolve)?\(\s*['"](?:${PKG})['"]\s*\)`),
+  new RegExp(String.raw`import\(\s*['"](?:${PKG})['"]\s*\)`),
+];
+const SOURCE_EXT = /\.(ts|tsx|mjs|cjs|js|jsx)$/;
+
+// Strip comments so an import-SHAPED example inside a doc comment (e.g. a JSDoc `* import ...`
+// line) is not a false positive. A real import statement never starts a line with `//` or `*`,
+// so this only removes prose, never a genuine dependency edge. (Line-scoped — not a full parser;
+// a package name inside a string literal remains matchable, which is intentional.)
+function codeOnly(line) {
+  const trimmed = line.trimStart();
+  if (trimmed.startsWith("//") || trimmed.startsWith("*") || trimmed.startsWith("/*")) return "";
+  return line.replace(/\/\*.*?\*\//g, "").replace(/\/\/.*$/, "");
+}
+
+function trackedFiles(dir) {
+  return execFileSync("git", ["ls-files", dir], { encoding: "utf8" })
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean);
+}
+
+const violations = [];
+
+// 1. Source imports under kits/.
+for (const file of trackedFiles("kits").filter((f) => SOURCE_EXT.test(f))) {
+  let text;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch {
+    continue;
+  }
+  text.split("\n").forEach((line, index) => {
+    if (IMPORT_PATTERNS.some((re) => re.test(codeOnly(line)))) {
+      violations.push(`${file}:${index + 1}  imports @kontourai/veritas — kits wrap the engine via CLI, not as a library`);
+    }
+  });
+}
+
+// 2. kit.json dependency declarations.
+for (const file of trackedFiles("kits").filter((f) => f.endsWith("kit.json"))) {
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    continue;
+  }
+  for (const field of ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"]) {
+    const decl = manifest[field];
+    if (decl && typeof decl === "object" && !Array.isArray(decl)) {
+      for (const name of ["@kontourai/veritas"]) {
+        if (Object.prototype.hasOwnProperty.call(decl, name)) {
+          violations.push(`${file} ${field}.${name} — a kit must not declare the engine as an npm dependency`);
+        }
+      }
+    }
+  }
+}
+
+if (violations.length) {
+  console.error("[check-layer-boundary] FAILED — a kit imports/depends on the veritas engine as a library (engine/surface seam, Invariant 3):");
+  for (const v of violations) console.error(`  ${v}`);
+  console.error(
+    "\nKits distribute by copy/activate/CLI and consume the engine via its CLI + recorded artifacts,\n" +
+      "never as an npm library import. The trust-bundle adapter may import @kontourai/surface (the open\n" +
+      "trust format); it must not import @kontourai/veritas. See veritas docs/architecture/engine-surface-seam.md.",
+  );
+  process.exitCode = 1;
+} else {
+  console.log("[check-layer-boundary] OK — no kit imports or declares the veritas engine as a library.");
+}

package/src/cli/builder-flow-runtime.test.mjs

@@ -1860,6 +1860,92 @@ test("publish-change reports an external capability gap and self-authored result
   await releaseBuilderFlowAssignment({ sessionDir: session.sessionDir, reason: `test cleanup for ${ambient.actorKey}` });
 });
 
+async function advanceSessionToPrOpen(session) {
+  await startBuilderFlowSession({ sessionDir: session.sessionDir });
+  const steps = [
+    () => [bundleClaim({ expectation: "selected-work", claimType: "builder.pull-work.selected", subjectType: "work-item" })],
+    () => [
+      bundleClaim({ expectation: "pickup-probe-readiness", claimType: "builder.design-probe.pickup-readiness", subjectType: "work-item" }),
+      bundleClaim({ expectation: "probe-decisions-or-accepted-gaps", claimType: "builder.design-probe.decisions", subjectType: "decision" }),
+    ],
+    () => [bundleClaim({ expectation: "implementation-plan", claimType: "builder.plan.implementation", subjectType: "artifact" })],
+    () => [bundleClaim({ expectation: "implementation-scope", claimType: "builder.execute.scope", subjectType: "change" })],
+    () => [bundleClaim({ expectation: "tests-evidence", claimType: "builder.verify.tests", subjectType: "flow-step" }), ...verifiedTestsPrerequisites(session)],
+    () => [bundleClaim({ expectation: "merge-readiness", claimType: "builder.merge-ready.readiness", subjectType: "change" })],
+  ];
+  let latest = null;
+  for (const entries of steps) latest = await writeAndSync(session, entries());
+  assert.equal(latest.run.state.current_step, "pr-open");
+  return latest;
+}
+
+test("pr-open route-back with missing_evidence returns the run to verify and supports repair re-entry (#695 item a)", async () => {
+  const session = makeSession("propen-routeback");
+  await advanceSessionToPrOpen(session);
+
+  // The #663 wedge scenario: a trust divergence is discovered at pr-open. A failing
+  // pull-request-opened claim declaring the missing_evidence route reason must land
+  // the canonical run back at verify — the sanctioned repair surface — not throw.
+  const failureTimestamp = new Date().toISOString();
+  const routed = await writeAndSync(session, [bundleClaim({
+    expectation: "pull-request-opened",
+    claimType: "builder.pr-open.pull-request",
+    subjectType: "pull-request",
+    status: "fail",
+    routeReason: "missing_evidence",
+    timestamp: failureTimestamp,
+  })]);
+
+  assert.equal(routed.attached, true);
+  assert.equal(routed.run.state.current_step, "verify");
+  const routeBacks = routed.run.state.transitions.filter((transition) => transition.type === "route_back");
+  assert.equal(routeBacks.length, 1);
+  assert.equal(routeBacks[0].from_step, "pr-open");
+  assert.equal(routeBacks[0].to_step, "verify");
+  assert.equal(routeBacks[0].route_reason, "missing_evidence");
+  assert.equal(routeBacks[0].gate_id, "builder.publish-learn:pr-open-gate");
+  assert.equal(routed.projection.flow_run.route_back_attempt, 1);
+  assert.equal(routed.projection.flow_run.route_back_max_attempts, 3);
+  assert.match(routed.projection.next_action.summary, /Route-back history: attempt 1\/3 returned to `verify` for `missing_evidence`/);
+
+  // Repair loop: fresh verify evidence re-passes verify, fresh merge-readiness
+  // re-passes merge-ready, and the run returns to pr-open.
+  const repairedAt = new Date(Date.parse(routed.run.state.transitions.at(-1).at) + 1).toISOString();
+  const reverified = await writeAndSync(session, [
+    withIdentitySuffix(bundleClaim({ expectation: "tests-evidence", claimType: "builder.verify.tests", subjectType: "flow-step", timestamp: repairedAt }), "repair"),
+    ...verifiedTestsPrerequisites(session, repairedAt).map((entry, index) => withIdentitySuffix(entry, `repair-${index}`)),
+  ]);
+  assert.equal(reverified.run.state.current_step, "merge-ready");
+  const returned = await writeAndSync(session, [
+    withIdentitySuffix(bundleClaim({ expectation: "merge-readiness", claimType: "builder.merge-ready.readiness", subjectType: "change", timestamp: new Date().toISOString() }), "repair"),
+  ]);
+  assert.equal(returned.run.state.current_step, "pr-open");
+});
+
+test("pr-open route-back with an undeclared reason still throws and mutates nothing", async () => {
+  const session = makeSession("propen-undeclared-reason");
+  await advanceSessionToPrOpen(session);
+
+  const flowDirectory = runDir(session.slug, session.projectRoot);
+  const beforeState = readJson(path.join(flowDirectory, "state.json"));
+  const beforeManifest = readJson(path.join(flowDirectory, FLOW_RUN_EVIDENCE_MANIFEST_PATH));
+
+  writeBundle(session.sessionDir, [bundleClaim({
+    expectation: "pull-request-opened",
+    claimType: "builder.pr-open.pull-request",
+    subjectType: "pull-request",
+    status: "fail",
+    routeReason: "stale_critique",
+    timestamp: new Date().toISOString(),
+  })]);
+  await assert.rejects(
+    () => syncBuilderFlowSession({ sessionDir: session.sessionDir }),
+    /route_reason.*is not declared by gate builder\.publish-learn:pr-open-gate/,
+  );
+  assert.deepEqual(readJson(path.join(flowDirectory, "state.json")), beforeState);
+  assert.deepEqual(readJson(path.join(flowDirectory, FLOW_RUN_EVIDENCE_MANIFEST_PATH)), beforeManifest);
+});
+
 test("recovery loads the slug-bound run, restores every matching projection, and preserves every Flow byte", async () => {
   const session = makeSession("recover-active");
   await startBuilderFlowSession({ sessionDir: session.sessionDir });

package/src/cli/flow-resolver-composition.test.mjs

@@ -4,7 +4,9 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
-import { resolveEffectiveFlowDefinition, resolveFlowFilePath } from "../../build/src/lib/flow-resolver.js";
+import { validateDefinition } from "@kontourai/flow";
+
+import { resolveEffectiveFlowDefinition, resolveFlowFilePath, resolveFlowStep } from "../../build/src/lib/flow-resolver.js";
 
 const REPO_ROOT = path.resolve(import.meta.dirname, "../..");
 
@@ -26,6 +28,23 @@ test("effective Builder definition materializes uses_flow and Flow-native comple
   );
 });
 
+test("composed pr-open-gate declares the missing_evidence repair route to verify (#695 item a)", () => {
+  const definition = resolveEffectiveFlowDefinition("builder.build", REPO_ROOT);
+  assert.ok(definition);
+  const gate = definition.gates["builder.publish-learn:pr-open-gate"];
+  assert.deepEqual(gate.on_route_back, { missing_evidence: "verify", default: "verify" });
+  assert.deepEqual(gate.route_back_policy, { max_attempts: 3, on_exceeded: "block" });
+  // Every declared route-back target must exist in the EFFECTIVE step set — the
+  // composed definition (where `verify` lives) must stay a valid Flow definition.
+  assert.doesNotThrow(() => validateDefinition(definition));
+  // The live resolver surfaces the declared reasons at the composed step, which is
+  // what record-gate-claim's --route-reason validation reads.
+  const step = resolveFlowStep("builder.build", "pr-open", REPO_ROOT);
+  assert.ok(step);
+  assert.equal(step.gateId, "builder.publish-learn:pr-open-gate");
+  assert.deepEqual([...step.routeBackReasons].sort(), ["default", "missing_evidence"]);
+});
+
 test("installed package definitions resolve when a consumer repo has no kits directory", () => {
   const consumer = fs.mkdtempSync(path.join(os.tmpdir(), "flow-agents-consumer-"));
   const resolved = resolveFlowFilePath("builder", "build", "builder.build", consumer, false);

package/src/cli/init.ts

@@ -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";
@@ -640,7 +641,21 @@ function installBundle(bundle: string, options: InitOptions): number {
   return result.status ?? 1;
 }
 
-function activateKits(options: InitOptions): number {
+function kitPathForInit(kitId: string, dest: string): string | null {
+  const catalogPath = path.join(root, "kits", "catalog.json");
+  if (fs.existsSync(catalogPath)) {
+    const catalog = JSON.parse(fs.readFileSync(catalogPath, "utf8")) as { kits?: unknown[] };
+    const entry = Array.isArray(catalog.kits)
+      ? catalog.kits.find((item) => typeof item === "object" && item !== null && (item as Record<string, unknown>).id === kitId)
+      : undefined;
+    const rel = entry && typeof entry === "object" ? (entry as Record<string, unknown>).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: InitOptions): Promise<number> {
   const activeKitIds = options.activeKitIds ?? [];
   if (!options.activateKits || activeKitIds.length === 0 || options.runtime !== "codex") return 0;
   const result = activateCodexLocal(options.dest, options.dest, { kitIdFilter: activeKitIds });
@@ -650,6 +665,19 @@ function activateKits(options: InitOptions): number {
   }
   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;
 }
 
@@ -867,7 +895,7 @@ export async function main(argv = process.argv.slice(2)): Promise<number> {
       const installed = result.status ?? 1;
       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") {
@@ -881,7 +909,7 @@ export async function main(argv = process.argv.slice(2)): Promise<number> {
     const installed = installBundle(bundle, options);
     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.