@kontourai/flow-agents 1.3.0 → 2.0.0

package/build/src/cli/init.d.ts

@@ -0,0 +1,17 @@
+export declare const COLLISION_MARKER = "Recording Flow Agents telemetry";
+/**
+ * Check whether a user-level Claude Code settings file already contains
+ * Flow Agents hook commands. If it does, print a WARNING explaining that
+ * Claude Code merges user-level and project-level settings and runs ALL
+ * matching hooks, so having flow-agents in both places causes duplicate
+ * hook execution (double telemetry, double policy enforcement).
+ *
+ * The check does NOT block the install; it is advisory only.
+ *
+ * @param userSettingsFile Path to inspect (defaults to $HOME/.claude/settings.json;
+ *   overridable via FLOW_AGENTS_USER_CLAUDE_SETTINGS env var for testability).
+ * @returns true if a collision was detected, false otherwise.
+ */
+export declare function checkScopeCollision(userSettingsFile?: string): boolean;
+export declare function main(argv?: string[]): Promise<number>;
+export declare function mainDogfood(argv?: string[]): Promise<number>;

package/build/src/cli/init.js

@@ -1,6 +1,7 @@
 import { spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
 import * as os from "node:os";
 import * as path from "node:path";
 import { createInterface } from "node:readline/promises";
@@ -76,12 +77,19 @@ function usage() {
 Options:
   --runtime base|codex|claude-code|kiro|opencode|pi
   --dest PATH
+  --global              Target the runtime's global/user-level config path.
+                        claude-code: merges FA hooks into ~/.claude/settings.json.
+                          Honors FLOW_AGENTS_USER_CLAUDE_SETTINGS for test isolation.
+                        opencode: merges opencode.json into ~/.config/opencode/opencode.json
+                          (honors XDG_CONFIG_HOME; test isolation via FLOW_AGENTS_USER_OPENCODE_CONFIG).
+                        codex: runs install-codex-home.sh into ~/.flow-agents/codex
+                          (the isolated Codex HOME; hooks merged, not overwritten).
+                        pi: NOT_VERIFIED (no documented global dir); warns and falls back to workspace default.
   --telemetry-sink local-files|local-kontour-console|kontour-hosted-console|user-hosted-console
   --console-url URL
   --console-endpoint URL
   --console-token-file PATH
   --console-tenant ID
-  --packs LIST
   --activate-kits
   --yes, --headless
 `);
@@ -148,6 +156,35 @@ function defaultDest(runtime) {
         return path.join(os.homedir(), ".flow-agents");
     return process.cwd();
 }
+function globalDest(runtime) {
+    if (runtime === "claude-code") {
+        // Honor FLOW_AGENTS_USER_CLAUDE_SETTINGS for test isolation (same as checkScopeCollision).
+        const override = process.env["FLOW_AGENTS_USER_CLAUDE_SETTINGS"];
+        if (override)
+            return path.dirname(override);
+        return path.join(os.homedir(), ".claude");
+    }
+    if (runtime === "opencode") {
+        // Honor FLOW_AGENTS_USER_OPENCODE_CONFIG (points to the opencode.json FILE) for test isolation,
+        // mirroring FLOW_AGENTS_USER_CLAUDE_SETTINGS for claude-code.
+        const override = process.env["FLOW_AGENTS_USER_OPENCODE_CONFIG"];
+        if (override)
+            return path.dirname(override);
+        // Global opencode config: ~/.config/opencode/ (honor XDG_CONFIG_HOME when set, else ~/.config).
+        return path.join(process.env["XDG_CONFIG_HOME"] ?? path.join(os.homedir(), ".config"), "opencode");
+    }
+    if (runtime === "codex") {
+        // codex --global routes to the isolated Codex HOME at ~/.flow-agents/codex.
+        // This is the same path used by install-codex-home.sh; --dest overrides it for sandbox testing.
+        return path.join(os.homedir(), ".flow-agents", "codex");
+    }
+    if (runtime === "pi") {
+        // pi has no documented global config dir.
+        // NOT_VERIFIED: fall back to workspace default and warn caller.
+        return defaultDest(runtime);
+    }
+    return defaultDest(runtime);
+}
 function parseYesNo(value, fallback) {
     const normalized = value.trim().toLowerCase();
     if (!normalized)
@@ -165,7 +202,9 @@ async function interactiveOptions(argv) {
         const runtimeDefault = normalizeRuntime(flagString(args.flags, "runtime")) ?? "base";
         const runtimeAnswer = flagString(args.flags, "runtime") ?? await rl.question(`Runtime [${runtimeDefault}]: `);
         const runtime = normalizeRuntime(runtimeAnswer.trim() || runtimeDefault) ?? runtimeDefault;
-        const destDefault = flagString(args.flags, "dest", defaultDest(runtime)) ?? defaultDest(runtime);
+        const isGlobal = flagBool(args.flags, "global");
+        const destBase = isGlobal ? globalDest(runtime) : defaultDest(runtime);
+        const destDefault = flagString(args.flags, "dest", destBase) ?? destBase;
         const destAnswer = flagString(args.flags, "dest") ?? await rl.question(`Install destination [${destDefault}]: `);
         const sinkDefault = telemetrySinksFromFlags(args.flags);
         const sinkAnswer = flagList(args.flags, "telemetry-sink").length || flagList(args.flags, "telemetry-sinks").length
@@ -186,6 +225,7 @@ async function interactiveOptions(argv) {
                 : "no";
         return {
             runtime,
+            global: isGlobal,
             dest: path.resolve(destAnswer.trim() || destDefault),
             consoleUrl: consoleUrl?.trim() || undefined,
             consoleEndpoint: consoleEndpoint?.trim() || undefined,
@@ -193,7 +233,6 @@ async function interactiveOptions(argv) {
             consoleTokenValue: consoleTokenValue?.trim() || undefined,
             consoleTenant: consoleTenant?.trim() || undefined,
             telemetrySinks,
-            packs: flagString(args.flags, "packs"),
             activateKits: runtime === "codex" && parseYesNo(activateAnswer, activateDefault),
         };
     }
@@ -204,15 +243,17 @@ async function interactiveOptions(argv) {
 function headlessOptions(argv) {
     const args = parseArgs(argv);
     const runtime = normalizeRuntime(flagString(args.flags, "runtime")) ?? "base";
+    const isGlobal = flagBool(args.flags, "global");
+    const destBase = isGlobal ? globalDest(runtime) : defaultDest(runtime);
     return {
         runtime,
-        dest: path.resolve(flagString(args.flags, "dest", defaultDest(runtime)) ?? defaultDest(runtime)),
+        global: isGlobal,
+        dest: path.resolve(flagString(args.flags, "dest", destBase) ?? destBase),
         consoleUrl: flagString(args.flags, "console-url"),
         consoleEndpoint: flagString(args.flags, "console-endpoint") ?? flagString(args.flags, "console-endpoint-url"),
         consoleTokenFile: flagString(args.flags, "console-token-file"),
         consoleTenant: flagString(args.flags, "console-tenant") ?? flagString(args.flags, "console-tenant-id"),
         telemetrySinks: telemetrySinksFromFlags(args.flags),
-        packs: flagString(args.flags, "packs"),
         activateKits: runtime === "codex" && flagBool(args.flags, "activate-kits"),
     };
 }
@@ -249,8 +290,6 @@ function installBundle(bundle, options) {
     if (options.consoleTenant)
         args.push("--console-tenant", options.consoleTenant);
     const env = { ...process.env };
-    if (options.packs)
-        env.FLOW_AGENTS_PACKS = options.packs;
     const result = spawnSync("bash", args, { cwd: bundle, env, encoding: "utf8", stdio: "inherit" });
     if (tempTokenFile)
         fs.rmSync(path.dirname(tempTokenFile), { recursive: true, force: true });
@@ -290,7 +329,136 @@ export async function main(argv = process.argv.slice(2)) {
         // There is no well-known user-level codex hooks file in our install paths,
         // so no collision check is needed for codex.
         if (options.runtime === "claude-code") {
-            checkScopeCollision();
+            // Skip collision check when --global is set: the user is intentionally
+            // targeting the global settings, so the collision they'd create is expected.
+            if (!options.global)
+                checkScopeCollision();
+        }
+        // --global for claude-code: merge only into the global/user-level settings dir.
+        // This writes only the hook-wiring config (merge into ~/.claude/settings.json),
+        // not the full workspace bundle. The global settings dir is the claude config root,
+        // so the settings.json lives directly in dest (not dest/.claude/).
+        if (options.global && options.runtime === "claude-code") {
+            const bundle = ensureBundle(options.runtime);
+            // For --global, dest is ~/.claude/ (the global settings dir).
+            // dogfoodClaudeCode writes to dest/.claude/settings.json — but for global,
+            // the settings.json lives at dest/settings.json (dest IS ~/.claude/).
+            // We use a special global-merge path: merge directly into dest/settings.json.
+            const sourcePath = path.join(bundle, ".claude", "settings.json");
+            if (!fs.existsSync(sourcePath)) {
+                console.error(`flow-agents init: bundle settings missing: ${sourcePath}`);
+                return 1;
+            }
+            const managed = JSON.parse(fs.readFileSync(sourcePath, "utf8"));
+            // Remove permissive defaults (not appropriate for global user settings).
+            delete managed["permissions"];
+            delete managed["skipDangerousModePermissionPrompt"];
+            fs.mkdirSync(options.dest, { recursive: true });
+            const destSettingsPath = path.join(options.dest, "settings.json");
+            const installMergePath = path.join(root, "scripts", "install-merge.js");
+            const _require = createRequire(import.meta.url);
+            const { mergeSettings } = _require(installMergePath);
+            let existing = {};
+            if (fs.existsSync(destSettingsPath)) {
+                try {
+                    existing = JSON.parse(fs.readFileSync(destSettingsPath, "utf8"));
+                }
+                catch {
+                    existing = {};
+                }
+            }
+            const merged = mergeSettings(existing, managed);
+            const tmp = `${destSettingsPath}.tmp.${process.pid}`;
+            fs.writeFileSync(tmp, `${JSON.stringify(merged, null, 2)}\n`, "utf8");
+            fs.renameSync(tmp, destSettingsPath);
+            // Write version stamp.
+            const installRecordDir = path.join(options.dest, ".flow-agents");
+            fs.mkdirSync(installRecordDir, { recursive: true });
+            const pkgJson = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+            const record = { version: pkgJson["version"] ?? "0.0.0", installedAt: new Date().toISOString(), runtime: "claude-code", global: true };
+            const recordPath = path.join(installRecordDir, "install.json");
+            const recordTmp = `${recordPath}.tmp.${process.pid}`;
+            fs.writeFileSync(recordTmp, `${JSON.stringify(record, null, 2)}\n`, "utf8");
+            fs.renameSync(recordTmp, recordPath);
+            console.log(`Flow Agents global hooks merged for claude-code in ${options.dest}`);
+            return 0;
+        }
+        // --global for opencode: merge FA opencode.json into the global opencode config dir.
+        // Global path: ~/.config/opencode/opencode.json (honor XDG_CONFIG_HOME).
+        // Test isolation: FLOW_AGENTS_USER_OPENCODE_CONFIG points to the opencode.json FILE.
+        if (options.global && options.runtime === "opencode") {
+            const bundle = ensureBundle(options.runtime);
+            const sourcePath = path.join(bundle, "opencode.json");
+            if (!fs.existsSync(sourcePath)) {
+                console.error(`flow-agents init: bundle opencode.json missing: ${sourcePath}`);
+                return 1;
+            }
+            const managed = JSON.parse(fs.readFileSync(sourcePath, "utf8"));
+            fs.mkdirSync(options.dest, { recursive: true });
+            // The global opencode.json lives directly at dest/opencode.json.
+            const destConfigPath = path.join(options.dest, "opencode.json");
+            const installMergePath = path.join(root, "scripts", "install-merge.js");
+            const _require = createRequire(import.meta.url);
+            const { mergeSettings } = _require(installMergePath);
+            let existing = {};
+            if (fs.existsSync(destConfigPath)) {
+                try {
+                    existing = JSON.parse(fs.readFileSync(destConfigPath, "utf8"));
+                }
+                catch {
+                    existing = {};
+                }
+            }
+            const merged = mergeSettings(existing, managed);
+            const tmp = `${destConfigPath}.tmp.${process.pid}`;
+            fs.writeFileSync(tmp, `${JSON.stringify(merged, null, 2)}
+`, "utf8");
+            fs.renameSync(tmp, destConfigPath);
+            // Write version stamp.
+            const installRecordDir = path.join(options.dest, ".flow-agents");
+            fs.mkdirSync(installRecordDir, { recursive: true });
+            const pkgJson = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+            const record = { version: pkgJson["version"] ?? "0.0.0", installedAt: new Date().toISOString(), runtime: "opencode", global: true };
+            const recordPath = path.join(installRecordDir, "install.json");
+            const recordTmp = `${recordPath}.tmp.${process.pid}`;
+            fs.writeFileSync(recordTmp, `${JSON.stringify(record, null, 2)}
+`, "utf8");
+            fs.renameSync(recordTmp, recordPath);
+            console.log(`Flow Agents global config merged for opencode in ${options.dest}`);
+            return 0;
+        }
+        // --global for codex: run install-codex-home.sh to install into the isolated Codex HOME.
+        // The codex --global path is ~/.flow-agents/codex (the isolated home IS codex's global).
+        // Pass through telemetry/console args and honor --dest override for sandbox testing.
+        if (options.global && options.runtime === "codex") {
+            const codexHomeScript = path.join(root, "scripts", "install-codex-home.sh");
+            if (!fs.existsSync(codexHomeScript)) {
+                console.error(`flow-agents init: install-codex-home.sh missing: ${codexHomeScript}`);
+                return 1;
+            }
+            const scriptArgs = [options.dest];
+            for (const sink of options.telemetrySinks)
+                scriptArgs.push("--telemetry-sink", sink);
+            if (options.consoleUrl)
+                scriptArgs.push("--console-url", options.consoleUrl);
+            if (options.consoleEndpoint)
+                scriptArgs.push("--console-endpoint", options.consoleEndpoint);
+            if (options.consoleTokenFile)
+                scriptArgs.push("--console-token-file", options.consoleTokenFile);
+            if (options.consoleTenant)
+                scriptArgs.push("--console-tenant", options.consoleTenant);
+            const result = spawnSync("bash", [codexHomeScript, ...scriptArgs], { env: { ...process.env }, encoding: "utf8", stdio: "inherit" });
+            if (result.error) {
+                console.error(`flow-agents init: unable to run install-codex-home.sh: ${result.error.message}`);
+                return 1;
+            }
+            return result.status ?? 1;
+        }
+        // --global for pi: NOT_VERIFIED (no documented global dir). Warn and fall through to workspace install.
+        if (options.global && options.runtime === "pi") {
+            console.warn(`flow-agents init: NOT_VERIFIED: pi has no documented global config directory. ` +
+                `The --global flag for pi is not verified against pi documentation. ` +
+                `Falling back to workspace default destination: ${options.dest}`);
         }
         const bundle = ensureBundle(options.runtime);
         const installed = installBundle(bundle, options);
@@ -337,39 +505,93 @@ function normalizeDogfoodRuntime(value) {
     throw new Error(`dogfood: unsupported runtime '${value}'; expected claude-code, codex, opencode, or pi`);
 }
 /**
- * Write the claude-code hook-wiring artifacts into dest.
+ * Write the claude-code hook-wiring artifacts into dest using merge semantics.
  * Reads dist/claude-code/.claude/settings.json (generated by build-bundles),
- * strips the permissive-mode permission keys (defaultMode, skipDangerousModePermissionPrompt),
- * and writes .claude/settings.json to dest.
+ * strips the permissive-mode permission keys (defaultMode, skipDangerousModePermissionPrompt)
+ * from the managed bundle settings, then MERGES into any existing dest settings.json —
+ * preserving user keys, auth, and non-flow-agents hooks. Writes version stamp.
  */
 function dogfoodClaudeCode(bundleRoot, dest) {
     const sourcePath = path.join(bundleRoot, ".claude", "settings.json");
     if (!fs.existsSync(sourcePath))
         throw new Error(`dogfood: bundle settings missing: ${sourcePath}`);
-    const settings = JSON.parse(fs.readFileSync(sourcePath, "utf8"));
+    const managed = JSON.parse(fs.readFileSync(sourcePath, "utf8"));
     // Remove permissive defaults that are only appropriate for installed workspaces.
     // These keys must not be present in the source repo's .claude/settings.json.
-    delete settings["permissions"];
-    delete settings["skipDangerousModePermissionPrompt"];
+    delete managed["permissions"];
+    delete managed["skipDangerousModePermissionPrompt"];
     const outDir = path.join(dest, ".claude");
     fs.mkdirSync(outDir, { recursive: true });
-    fs.writeFileSync(path.join(outDir, "settings.json"), `${JSON.stringify(settings, null, 2)}\n`, "utf8");
+    const destSettingsPath = path.join(outDir, "settings.json");
+    // Merge: read existing, strip FA hooks, append new FA hooks, preserve all other keys.
+    const installMergePath = path.join(root, "scripts", "install-merge.js");
+    const _require = createRequire(import.meta.url);
+    const { mergeSettings } = _require(installMergePath);
+    let existing = {};
+    if (fs.existsSync(destSettingsPath)) {
+        try {
+            existing = JSON.parse(fs.readFileSync(destSettingsPath, "utf8"));
+        }
+        catch {
+            existing = {};
+        }
+    }
+    const merged = mergeSettings(existing, managed);
+    const tmp = `${destSettingsPath}.tmp.${process.pid}`;
+    fs.writeFileSync(tmp, `${JSON.stringify(merged, null, 2)}\n`, "utf8");
+    fs.renameSync(tmp, destSettingsPath);
+    // Write version stamp.
+    const installRecordDir = path.join(dest, ".flow-agents");
+    fs.mkdirSync(installRecordDir, { recursive: true });
+    const pkgJson = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+    const record = { version: pkgJson["version"] ?? "0.0.0", installedAt: new Date().toISOString(), runtime: "claude-code" };
+    const recordPath = path.join(installRecordDir, "install.json");
+    const recordTmp = `${recordPath}.tmp.${process.pid}`;
+    fs.writeFileSync(recordTmp, `${JSON.stringify(record, null, 2)}\n`, "utf8");
+    fs.renameSync(recordTmp, recordPath);
 }
 /**
- * Write the codex hook-wiring artifacts into dest.
- * Reads dist/codex/.codex/hooks.json and writes .codex/hooks.json to dest.
+ * Write the codex hook-wiring artifacts into dest using merge semantics.
+ * Reads dist/codex/.codex/hooks.json and MERGES into any existing dest hooks.json —
+ * preserving user non-FA hook groups. Writes version stamp.
  * The monolithic .codex/config.toml is not written here because it contains
  * workspace settings (approvals_reviewer, features) that would override the
- * developer's existing codex configuration. Only the hooks file is written.
+ * developer's existing codex configuration. Only the hooks file is merged.
  */
 function dogfoodCodex(bundleRoot, dest) {
     const sourcePath = path.join(bundleRoot, ".codex", "hooks.json");
     if (!fs.existsSync(sourcePath))
         throw new Error(`dogfood: bundle hooks.json missing: ${sourcePath}`);
-    const hooks = fs.readFileSync(sourcePath, "utf8");
+    const managed = JSON.parse(fs.readFileSync(sourcePath, "utf8"));
     const outDir = path.join(dest, ".codex");
     fs.mkdirSync(outDir, { recursive: true });
-    fs.writeFileSync(path.join(outDir, "hooks.json"), hooks, "utf8");
+    const destHooksPath = path.join(outDir, "hooks.json");
+    // Merge: read existing, strip FA hook-groups, append new FA hook-groups, preserve user groups.
+    const installMergePath = path.join(root, "scripts", "install-merge.js");
+    const _require = createRequire(import.meta.url);
+    const { mergeSettings } = _require(installMergePath);
+    let existing = {};
+    if (fs.existsSync(destHooksPath)) {
+        try {
+            existing = JSON.parse(fs.readFileSync(destHooksPath, "utf8"));
+        }
+        catch {
+            existing = {};
+        }
+    }
+    const merged = mergeSettings(existing, managed);
+    const tmp = `${destHooksPath}.tmp.${process.pid}`;
+    fs.writeFileSync(tmp, `${JSON.stringify(merged, null, 2)}\n`, "utf8");
+    fs.renameSync(tmp, destHooksPath);
+    // Write version stamp.
+    const installRecordDir = path.join(dest, ".flow-agents");
+    fs.mkdirSync(installRecordDir, { recursive: true });
+    const pkgJson = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+    const record = { version: pkgJson["version"] ?? "0.0.0", installedAt: new Date().toISOString(), runtime: "codex" };
+    const recordPath = path.join(installRecordDir, "install.json");
+    const recordTmp = `${recordPath}.tmp.${process.pid}`;
+    fs.writeFileSync(recordTmp, `${JSON.stringify(record, null, 2)}\n`, "utf8");
+    fs.renameSync(recordTmp, recordPath);
 }
 /**
  * Write the opencode hook-wiring artifacts into dest.

package/build/src/cli/kit.d.ts

@@ -0,0 +1 @@
+export declare function main(argv?: string[]): Promise<number>;

package/build/src/cli/promote-workflow-artifact.d.ts

@@ -0,0 +1 @@
+export declare function main(argv?: string[]): number;

package/build/src/cli/publish-change-helper.d.ts

@@ -0,0 +1 @@
+export declare function main(argv?: string[]): number;

package/build/src/cli/pull-work-provider.d.ts

@@ -0,0 +1 @@
+export declare function main(argv?: string[]): number;

package/build/src/cli/runtime-adapter.d.ts

@@ -0,0 +1 @@
+export declare function main(argv?: string[]): number;

package/build/src/cli/telemetry-doctor.d.ts

@@ -0,0 +1 @@
+export declare function main(argv?: string[]): Promise<number>;

package/build/src/cli/usage-feedback.d.ts

@@ -0,0 +1 @@
+export declare function main(argv?: string[]): number;

package/build/src/cli/utterance-check.d.ts

@@ -0,0 +1 @@
+export declare function main(argv?: string[]): Promise<number>;

package/build/src/cli/validate-hook-influence.d.ts

@@ -0,0 +1 @@
+export declare function main(argv?: string[]): number;

package/build/src/cli/validate-source-tree.d.ts

@@ -0,0 +1 @@
+export declare function main(argv?: string[]): Promise<number>;

package/build/src/cli/validate-workflow-artifacts.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

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

@@ -438,12 +438,29 @@ function validateSidecarGroup(inputs, markdown, requireSidecars, requireCritique
         for (const dir of dirs) {
             const deliver = markdown.find((p) => path.dirname(p) === dir && p.includes("deliver") && !p.includes("plan") && !p.includes("review"));
             const delivered = deliver ? /status:\s*(delivered|accepted|archived)/i.test(readText(deliver)) : true;
-            for (const name of ["state.json", "acceptance.json", ...(delivered ? ["evidence.json"] : []), "handoff.json"]) {
+            // ADR 0010 Phase 4b: trust.bundle is the primary artifact at the delivered phase.
+            // evidence.json is OPTIONAL when trust.bundle is present (still schema-validated when present).
+            // Hard-fail on evidence.json absence only when no trust.bundle exists for a delivered session.
+            const hasTrustBundle = fs.existsSync(path.join(dir, "trust.bundle"));
+            const evidenceRequired = delivered && !hasTrustBundle;
+            for (const name of ["state.json", "acceptance.json", ...(evidenceRequired ? ["evidence.json"] : []), "handoff.json"]) {
                 if (!fs.existsSync(path.join(dir, name)))
                     issues.push({ path: path.join(dir, name), message: "required sidecar is missing" });
             }
-            if (requireCritique && !fs.existsSync(path.join(dir, "critique.json")))
+            // ADR 0010 Phase 4c: critique.json no longer written; trust.bundle carries critique claims. Accept either.
+            if (requireCritique && !fs.existsSync(path.join(dir, "critique.json")) && !fs.existsSync(path.join(dir, "trust.bundle")))
                 issues.push({ path: path.join(dir, "critique.json"), message: "required sidecar is missing" });
+            // ADR 0010 Phase 4c: validate critique claims in trust.bundle (sole verification artifact).
+            const trustBundlePath = path.join(dir, "trust.bundle");
+            if (requireCritique && fs.existsSync(trustBundlePath)) {
+                const { value: bundleValue } = readJson(trustBundlePath);
+                if (bundleValue) {
+                    const claims = Array.isArray(bundleValue.claims) ? bundleValue.claims : [];
+                    const critiqueClaims = claims.filter((c) => c && c.claimType === "workflow.critique.review");
+                    if (critiqueClaims.some((c) => c.value === "fail" || c.status === "disputed"))
+                        issues.push({ path: trustBundlePath, message: "required critique must pass" });
+                }
+            }
             const acceptance = path.join(dir, "acceptance.json");
             if (deliver && fs.existsSync(acceptance)) {
                 const expected = definitionAcceptanceCriteria(readText(deliver)).length;

package/build/src/cli/verify.d.ts

@@ -0,0 +1 @@
+export declare function main(argv?: string[]): Promise<number>;

package/build/src/cli/verify.js

@@ -0,0 +1,90 @@
+import { createRequire } from "node:module";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs, flagString, flagList } from "../lib/args.js";
+import { root } from "../tools/common.js";
+/**
+ * flow-agents verify — CI trust anchor for downstream repos.
+ *
+ * Re-runs canonical verification FRESH in the current environment, then reconciles
+ * a delivered trust.bundle's claimed passes against those fresh results. Exits 1
+ * on divergence, fresh-verify failure, laundered commands, or no verify configured.
+ * Exits 0 on clean pass.
+ *
+ * This is a thin wrapper around scripts/ci/trust-reconcile.js: it resolves the
+ * script from the installed package root (via createRequire) and calls the exported
+ * runTrustReconcile() function directly so all output goes to the same process
+ * stdout/stderr without an extra subprocess layer.
+ *
+ * The script ships in the npm package `files` list, so downstream repos always have
+ * access to it at the same relative path from the package root.
+ */
+const _require = createRequire(import.meta.url);
+function usage() {
+    process.stderr.write("usage: flow-agents verify [--commands <cmd[,cmd...]>] [--bundle <path>] [--repo-root <path>]\n" +
+        "\n" +
+        "Re-runs canonical verification fresh and reconciles a delivered trust.bundle's\n" +
+        "claimed passes against CI results. Exits 1 on divergence, fresh-verify failure,\n" +
+        "compile-only/no-verify, or laundered commands. Exits 0 on clean pass.\n" +
+        "\n" +
+        "Options:\n" +
+        "  --commands <cmd,...>  Canonical verify command(s). Comma-separated or repeated.\n" +
+        "                        Falls back to TRUST_RECONCILE_COMMANDS env or\n" +
+        "                        package.json scripts['trust-reconcile-verify'].\n" +
+        "                        No-commands → fail-closed (compile-only refused).\n" +
+        "  --bundle <path>       Delivered trust.bundle or trust.checkpoint.json path.\n" +
+        "                        Falls back to TRUST_RECONCILE_BUNDLE env, then auto-\n" +
+        "                        discovers delivery/trust.bundle or delivery/trust.checkpoint.json.\n" +
+        "                        Absent bundle: only fresh verify is enforced (fail-open).\n" +
+        "  --repo-root <path>    Repository root. Default: TRUST_RECONCILE_REPO_ROOT env or cwd.\n" +
+        "\n" +
+        "Examples:\n" +
+        "  # Re-run build+test fresh; reconcile against a delivered bundle:\n" +
+        "  flow-agents verify --commands 'npm run build,npm test' --bundle delivery/trust.bundle\n" +
+        "\n" +
+        "  # Fresh-verify only (no bundle), using package.json trust-reconcile-verify script:\n" +
+        "  flow-agents verify\n");
+}
+export async function main(argv = process.argv.slice(2)) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        usage();
+        return 0;
+    }
+    const { flags } = parseArgs(argv);
+    // --commands may be specified multiple times or comma-separated within a single value.
+    const commandsRaw = flagList(flags, "commands");
+    const commands = commandsRaw.flatMap((c) => c.split(",").map((s) => s.trim()).filter(Boolean));
+    const bundle = flagString(flags, "bundle") ?? null;
+    const repoRoot = flagString(flags, "repo-root") ?? null;
+    // Resolve the trust-reconcile.js script from the installed package root.
+    // `root` (from tools/common.ts) walks up from this compiled file's directory until
+    // it finds a directory with both package.json and packaging/ — the package root.
+    // In a downstream installed package: node_modules/@kontourai/flow-agents/
+    // In the dev repo: the repo root itself.
+    // scripts/ci/trust-reconcile.js ships in the npm package `files` list.
+    const reconcilePath = path.join(root, "scripts", "ci", "trust-reconcile.js");
+    if (!fs.existsSync(reconcilePath)) {
+        process.stderr.write(`[flow-agents verify] error: trust-reconcile.js not found at ${reconcilePath}\n` +
+            "[flow-agents verify] Is the package correctly installed? Expected scripts/ci/trust-reconcile.js.\n");
+        return 1;
+    }
+    const { runTrustReconcile } = _require(reconcilePath);
+    return runTrustReconcile({ bundle, commands, repoRoot });
+}
+// Direct-script guard (mirrors pattern from other CLI subcommands).
+const _selfReal = (() => { try {
+    return fs.realpathSync(fileURLToPath(import.meta.url));
+}
+catch {
+    return fileURLToPath(import.meta.url);
+} })();
+const _argv1Real = (() => { try {
+    return fs.realpathSync(process.argv[1]);
+}
+catch {
+    return process.argv[1];
+} })();
+if (_selfReal === _argv1Real) {
+    process.exitCode = await main();
+}

package/build/src/cli/veritas-governance.d.ts

@@ -0,0 +1 @@
+export declare function main(argv?: string[]): number;

package/build/src/cli/workflow-artifact-cleanup-audit.d.ts

@@ -0,0 +1 @@
+export declare function main(argv?: string[]): number;