@kontourai/flow-agents 1.3.0 → 2.0.0

package/build/src/tools/build-universal-bundles.js

@@ -5,7 +5,7 @@ import path from "node:path";
 import { loadJson, readText, root, walkFiles, writeText } from "./common.js";
 const dist = process.env.FLOW_AGENTS_DIST_DIR ? path.resolve(process.env.FLOW_AGENTS_DIST_DIR) : path.join(root, "dist");
 const manifest = loadJson(path.join(root, "packaging/manifest.json"));
-const packs = loadJson(path.join(root, "packaging/packs.json"));
+const pkgVersion = loadJson(path.join(root, "package.json"))["version"] ?? "0.0.0";
 const textExtensions = new Set([".css", ".html", ".js", ".json", ".md", ".sh", ".toml", ".txt", ".yaml", ".yml", ".ts"]);
 const dropDiagnostics = [];
 const printDiagnostics = !["0", "false", "no"].includes(String(process.env.FLOW_AGENTS_EXPORT_DIAGNOSTICS ?? "1").toLowerCase());
@@ -190,8 +190,9 @@ function generatedAgentsSummary(agents) {
 function exportRootAgentsMd(label, agents, taskDir) {
     return `# Universal Agent Bundle (${label})\n\nThis bundle was generated from the canonical source in this repo. Treat the repo root as the source of truth and regenerate the bundle instead of editing exported agent files by hand.\n\n## Shared Conventions\n\n- \`skills/\`, \`context/\`, \`powers/\`, \`prompts/\`, \`scripts/\`, and \`evals/\` were copied from the canonical source.\n- Cross-session task artifacts should live under \`${taskDir}\`.\n- Kiro-only hook wiring was stripped from exported non-Kiro agents to keep the package portable.\n\n## Exported Agents\n\n${generatedAgentsSummary(agents)}\n`;
 }
-function exportTargetReadme(label, installHint) {
-    return `# ${label} Bundle\n\nGenerated from the canonical source in this repository.\n\n## Install\n\n\`\`\`bash\n${installHint}\n\`\`\`\n\nOptional pack filtering is available at install time with \`FLOW_AGENTS_PACKS\`.\nThe default pack is always included:\n\n\`\`\`bash\nFLOW_AGENTS_PACKS=development,knowledge ${installHint}\n\`\`\`\n\n## Contents\n\n- Harness-specific agents\n- Shared skills\n- Shared context, powers, prompts, scripts, and evals\n`;
+const CODEX_LIVE_HOOKS_README = `\n## Running with hooks active (live)\n\n\`install.sh\` lays the bundle into a workspace, but a live Codex session needs a \`CODEX_HOME\` that has both the bundle's hooks/scripts AND your real credentials. Use the dedicated installer, which flattens the config to the home root and copies your auth from \`~/.codex\`:\n\n\`\`\`bash\nbash scripts/install-codex-home.sh "$HOME/.flow-agents/codex"\nCODEX_HOME="$HOME/.flow-agents/codex" codex exec --dangerously-bypass-hook-trust -C /path/to/project "<prompt>"\n\`\`\`\n\nThe goal-fit Stop hook then enforces by default (\`FLOW_AGENTS_GOAL_FIT_MODE=block\`); set it to \`warn\` or \`off\` to override.\n`;
+function exportTargetReadme(label, installHint, extra = "") {
+    return `# ${label} Bundle\n\nGenerated from the canonical source in this repository.\n\n## Install\n\n\`\`\`bash\n${installHint}\n\`\`\`\n\nThe install ships the full standalone base (skills, agents, powers) plus the\nFlow Kits. Kit depth is activated through the Kit Catalog, not at install time.\n\n## Contents\n\n- Harness-specific agents\n- Shared skills\n- Shared context, powers, prompts, scripts, and evals\n${extra}`;
 }
 function mapClaudeTools(allowedTools) {
     const ordered = [];
@@ -277,8 +278,8 @@ function shellHook(command, timeout = 10, statusMessage) {
 function claudeTelemetry(event) {
     return `bash -lc 'root="\${CLAUDE_PROJECT_DIR:-$(pwd)}"; node "$root/scripts/hooks/claude-telemetry-hook.js" ${event} dev'`;
 }
-function claudePolicy(event, script) {
-    return `bash -lc 'root="\${CLAUDE_PROJECT_DIR:-$(pwd)}"; node "$root/scripts/hooks/claude-hook-adapter.js" ${event} ${script.replace(/\.js$/, "")} ${script} default'`;
+function claudePolicy(event, script, envPrefix = "") {
+    return `bash -lc 'root="\${CLAUDE_PROJECT_DIR:-$(pwd)}"; ${envPrefix}node "$root/scripts/hooks/claude-hook-adapter.js" ${event} ${script.replace(/\.js$/, "")} ${script} default'`;
 }
 function codexRoot(scriptPath) {
     return `root="\${CODEX_HOME:-}"; if [ -z "$root" ] || [ ! -f "$root/${scriptPath}" ]; then root=$(git rev-parse --show-toplevel 2>/dev/null || pwd); fi`;
@@ -288,17 +289,23 @@ function codexTelemetry(event) {
         return `bash -lc '${codexRoot("scripts/telemetry/telemetry.sh")}; bash "$root/scripts/telemetry/telemetry.sh" permissionRequest dev'`;
     return `bash -lc '${codexRoot("scripts/hooks/codex-telemetry-hook.js")}; node "$root/scripts/hooks/codex-telemetry-hook.js" ${event} dev'`;
 }
-function codexPolicy(script) {
-    return `bash -lc '${codexRoot("scripts/hooks/codex-hook-adapter.js")}; node "$root/scripts/hooks/codex-hook-adapter.js" ${script.replace(/\.js$/, "")} ${script} default'`;
+function codexPolicy(script, envPrefix = "") {
+    return `bash -lc '${codexRoot("scripts/hooks/codex-hook-adapter.js")}; ${envPrefix}node "$root/scripts/hooks/codex-hook-adapter.js" ${script.replace(/\.js$/, "")} ${script} default'`;
 }
+// Shipped L2 runtimes enforce goal fit by default (mode=block), while remaining
+// operator-overridable via the FLOW_AGENTS_GOAL_FIT_MODE environment variable.
+// The canonical engine default stays warn so the conformance contract is honest.
+const GOAL_FIT_MODE_PREFIX = 'FLOW_AGENTS_GOAL_FIT_MODE="${FLOW_AGENTS_GOAL_FIT_MODE:-block}" ';
 function exportClaudeSettings() {
     const hooks = {};
     for (const event of ["SessionStart", "UserPromptSubmit", "PreToolUse", "PermissionRequest", "PostToolUse", "Stop", "SessionEnd"]) {
         hooks[event] = [{ hooks: [shellHook(claudeTelemetry(event), 10, "Recording Flow Agents telemetry")] }];
     }
-    hooks.Stop.push({ hooks: [shellHook(claudePolicy("Stop", "stop-goal-fit.js"), 30, "Running Flow Agents hook policy")] });
+    hooks.Stop.push({ hooks: [shellHook(claudePolicy("Stop", "stop-goal-fit.js", GOAL_FIT_MODE_PREFIX), 30, "Running Flow Agents hook policy")] });
+    hooks.SessionStart.push({ hooks: [shellHook(claudePolicy("SessionStart", "workflow-steering.js"), 30, "Running Flow Agents hook policy")] });
     hooks.UserPromptSubmit.push({ hooks: [shellHook(claudePolicy("UserPromptSubmit", "workflow-steering.js"), 30, "Running Flow Agents hook policy")] });
     hooks.PostToolUse.push({ hooks: [shellHook(claudePolicy("PostToolUse", "quality-gate.js"), 30, "Running Flow Agents hook policy")] });
+    hooks.PostToolUse.push({ hooks: [shellHook(claudePolicy("PostToolUse", "evidence-capture.js"), 30, "Capturing Flow Agents command evidence")] });
     hooks.PreToolUse.push({ hooks: [shellHook(claudePolicy("PreToolUse", "config-protection.js"), 30, "Running Flow Agents hook policy")] });
     return `${JSON.stringify({
         statusLine: { type: "command", command: 'bash -lc \'root="${CLAUDE_PROJECT_DIR:-$(pwd)}"; node "$root/scripts/statusline/flow-agents-statusline.js"\'' },
@@ -312,8 +319,10 @@ function exportCodexHooks() {
     for (const event of ["SessionStart", "UserPromptSubmit", "PreToolUse", "PermissionRequest", "PostToolUse", "Stop"]) {
         hooks[event] = [{ hooks: [shellHook(codexTelemetry(event), 10, "Recording Flow Agents telemetry")] }];
     }
-    hooks.Stop.push({ hooks: [shellHook(codexPolicy("stop-goal-fit.js"), 30, "Running Flow Agents hook policy")] });
+    hooks.Stop.push({ hooks: [shellHook(codexPolicy("stop-goal-fit.js", GOAL_FIT_MODE_PREFIX), 30, "Running Flow Agents hook policy")] });
+    hooks.SessionStart.push({ hooks: [shellHook(codexPolicy("workflow-steering.js"), 30, "Running Flow Agents hook policy")] });
     hooks.UserPromptSubmit.push({ hooks: [shellHook(codexPolicy("workflow-steering.js"), 30, "Running Flow Agents hook policy")] });
+    hooks.PostToolUse.push({ hooks: [shellHook(codexPolicy("evidence-capture.js"), 30, "Capturing Flow Agents command evidence")] });
     return `${JSON.stringify({ hooks }, null, 2)}\n`;
 }
 function copySharedContent(targetRoot, targetName, token) {
@@ -337,21 +346,23 @@ function copySharedContent(targetRoot, targetName, token) {
     for (const dir of manifest.optional_copy_dirs ?? [])
         copyTree(path.join(root, dir), path.join(targetRoot, dir), targetName, token);
     writeText(path.join(targetRoot, "build/package.json"), `${JSON.stringify({ type: "module" }, null, 2)}\n`);
-    const filterBuilt = path.join(root, "build/src/tools/filter-installed-packs.js");
     const commonBuilt = path.join(root, "build/src/tools/common.js");
-    if (fs.existsSync(filterBuilt))
-        writeText(path.join(targetRoot, "scripts/filter-installed-packs.mjs"), readText(filterBuilt).replace("./common.js", "./common.mjs"));
     if (fs.existsSync(commonBuilt))
         writeText(path.join(targetRoot, "scripts/common.mjs"), readText(commonBuilt));
     copyTree(path.join(root, "build/src"), path.join(targetRoot, "build/src"), targetName, token);
 }
-function installScript(label, defaultDestDisplay, token, destFallbackShell) {
+function installScript(label, defaultDestDisplay, token, destFallbackShell, mergeConfig, stampConfig) {
     const replaceBlock = token ? `\nexport DEST\nfind "$DEST" -type f \\( -name '*.json' -o -name '*.md' -o -name '*.sh' -o -name '*.js' -o -name '*.ts' -o -name '*.yaml' -o -name '*.yml' \\) -print0 | xargs -0 perl -0pi -e 's#${token.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}#$ENV{DEST}#g'` : "";
     const destFallback = destFallbackShell ? `\nif [[ -z "$DEST" ]]; then\n  DEST="${destFallbackShell}"\nfi` : "";
     const destRequired = !destFallbackShell;
     const requiredCheck = destRequired ? `if [[ -z "$DEST" ]]; then\n  usage\n  exit 2\nfi\n` : "";
     const usageDest = destRequired ? "/path/to/workspace" : defaultDestDisplay;
-    return `#!/usr/bin/env bash\nset -euo pipefail\n\nusage() {\n  cat >&2 <<'EOF'\nusage: bash install.sh ${usageDest} [options]\n\nOptions:\n  --telemetry-sink NAME   local-files, local-kontour-console,\n                          kontour-hosted-console, user-hosted-console,\n                          or legacy aliases. May be repeated.\n  --console-url URL       Persist Console telemetry base URL.\n  --console-endpoint URL  Persist full Console telemetry records endpoint URL.\n  --console-token-file PATH\n                          Read Console telemetry bearer token from a file.\n  --console-tenant ID     Persist Console tenant identifier.\nEOF\n}\n\nDEST=""\nDEST_SET=0\nCONSOLE_CONFIG_ARGS=()\nwhile [[ $# -gt 0 ]]; do\n  case "$1" in\n    --telemetry-sink|--telemetry-sinks|--console-url|--console-endpoint|--console-endpoint-url|--console-token-file|--console-tenant|--console-tenant-id)\n      [[ $# -ge 2 ]] || { echo "install.sh: $1 requires a value" >&2; exit 2; }\n      CONSOLE_CONFIG_ARGS+=("$1" "$2")\n      shift 2\n      ;;\n    --help|-h)\n      usage\n      exit 0\n      ;;\n    -*)\n      echo "install.sh: unknown option: $1" >&2\n      usage\n      exit 2\n      ;;\n    *)\n      if [[ "$DEST_SET" -eq 1 ]]; then\n        echo "install.sh: unexpected argument: $1" >&2\n        usage\n        exit 2\n      fi\n      DEST="$1"\n      DEST_SET=1\n      shift\n      ;;\n  esac\ndone${destFallback}\n${requiredCheck}SRC="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"\n\nmkdir -p "$DEST"\nrsync -a ${token ? "--delete " : ""}"$SRC"/ "$DEST"/\nif [[ -n "\${FLOW_AGENTS_PACKS:-}" ]]; then\n  node "$DEST/scripts/filter-installed-packs.mjs" "$DEST" --packs "$FLOW_AGENTS_PACKS"\nfi${replaceBlock}\nif [[ \${#CONSOLE_CONFIG_ARGS[@]} -gt 0 || -n "\${FLOW_AGENTS_TELEMETRY_SINK:-}" || -n "\${FLOW_AGENTS_TELEMETRY_SINKS:-}" || -n "\${FLOW_AGENTS_CONSOLE_URL:-}" || -n "\${CONSOLE_TELEMETRY_URL:-}" || -n "\${CONSOLE_URL:-}" || -n "\${FLOW_AGENTS_CONSOLE_TOKEN_FILE:-}" || -n "\${CONSOLE_TELEMETRY_TOKEN_FILE:-}" ]]; then\n  bash "$DEST/scripts/telemetry/install-console-config.sh" "$DEST/scripts/telemetry/telemetry.conf" "\${CONSOLE_CONFIG_ARGS[@]}"\nfi\necho "Installed ${label} bundle ${token ? "to" : "into"} $DEST"\n`;
+    const mergeBlock = mergeConfig
+        ? `\nif command -v node >/dev/null 2>&1; then\n  node "$DEST/scripts/install-merge.js" --config "$DEST/${mergeConfig.configRelPath}" --managed-hooks "$SRC/${mergeConfig.managedConfigRelPath}" --version "${mergeConfig.version}" --install-record "$DEST/.flow-agents/install.json" --runtime "${mergeConfig.runtime}" || true\nfi`
+        : stampConfig
+            ? `\nif command -v node >/dev/null 2>&1; then\n  node "$DEST/scripts/install-merge.js" --stamp-only --version "${stampConfig.version}" --install-record "$DEST/.flow-agents/install.json" --runtime "${stampConfig.runtime}" || true\nfi`
+            : "";
+    return `#!/usr/bin/env bash\nset -euo pipefail\n\nusage() {\n  cat >&2 <<'EOF'\nusage: bash install.sh ${usageDest} [options]\n\nOptions:\n  --telemetry-sink NAME   local-files, local-kontour-console,\n                          kontour-hosted-console, user-hosted-console,\n                          or legacy aliases. May be repeated.\n  --console-url URL       Persist Console telemetry base URL.\n  --console-endpoint URL  Persist full Console telemetry records endpoint URL.\n  --console-token-file PATH\n                          Read Console telemetry bearer token from a file.\n  --console-tenant ID     Persist Console tenant identifier.\nEOF\n}\n\nDEST=""\nDEST_SET=0\nCONSOLE_CONFIG_ARGS=()\nwhile [[ $# -gt 0 ]]; do\n  case "$1" in\n    --telemetry-sink|--telemetry-sinks|--console-url|--console-endpoint|--console-endpoint-url|--console-token-file|--console-tenant|--console-tenant-id)\n      [[ $# -ge 2 ]] || { echo "install.sh: $1 requires a value" >&2; exit 2; }\n      CONSOLE_CONFIG_ARGS+=("$1" "$2")\n      shift 2\n      ;;\n    --help|-h)\n      usage\n      exit 0\n      ;;\n    -*)\n      echo "install.sh: unknown option: $1" >&2\n      usage\n      exit 2\n      ;;\n    *)\n      if [[ "$DEST_SET" -eq 1 ]]; then\n        echo "install.sh: unexpected argument: $1" >&2\n        usage\n        exit 2\n      fi\n      DEST="$1"\n      DEST_SET=1\n      shift\n      ;;\n  esac\ndone${destFallback}\n${requiredCheck}SRC="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"\n\nmkdir -p "$DEST"\nrsync -a ${token ? "--delete " : ""}${mergeConfig ? `--exclude="${mergeConfig.configRelPath}" ` : ""}"$SRC"/ "$DEST"/${replaceBlock}${mergeBlock}\nif [[ \${#CONSOLE_CONFIG_ARGS[@]} -gt 0 || -n "\${FLOW_AGENTS_TELEMETRY_SINK:-}" || -n "\${FLOW_AGENTS_TELEMETRY_SINKS:-}" || -n "\${FLOW_AGENTS_CONSOLE_URL:-}" || -n "\${CONSOLE_TELEMETRY_URL:-}" || -n "\${CONSOLE_URL:-}" || -n "\${FLOW_AGENTS_CONSOLE_TOKEN_FILE:-}" || -n "\${CONSOLE_TELEMETRY_TOKEN_FILE:-}" ]]; then\n  bash "$DEST/scripts/telemetry/install-console-config.sh" "$DEST/scripts/telemetry/telemetry.conf" "\${CONSOLE_CONFIG_ARGS[@]}"\nfi\necho "Installed ${label} bundle ${token ? "to" : "into"} $DEST"\n`;
 }
 function buildBase(agents) {
     const bundle = path.join(dist, "base");
@@ -360,7 +371,7 @@ function buildBase(agents) {
     writeText(path.join(bundle, ".flow-agents", ".gitkeep"), "");
     writeText(path.join(bundle, "AGENTS.md"), exportRootAgentsMd("Base", agents, ".flow-agents"));
     writeText(path.join(bundle, "README.md"), exportTargetReadme("Base", "bash install.sh /path/to/workspace"));
-    writeText(path.join(bundle, "install.sh"), installScript("Base", "/path/to/workspace"));
+    writeText(path.join(bundle, "install.sh"), installScript("Base", "/path/to/workspace", undefined, undefined, undefined, { runtime: "base", version: pkgVersion }));
     fs.chmodSync(path.join(bundle, "install.sh"), 0o755);
 }
 function buildKiro(agents) {
@@ -372,7 +383,7 @@ function buildKiro(agents) {
         writeText(path.join(bundle, "agents", `${spec.name}.json`), sanitizeText(`${JSON.stringify(sanitizeAgentJson(spec), null, 2)}\n`, "kiro", token));
     writeText(path.join(bundle, "AGENTS.md"), exportRootAgentsMd("Kiro", agents, ".flow-agents"));
     writeText(path.join(bundle, "README.md"), exportTargetReadme("Kiro", "bash install.sh $HOME/.flow-agents"));
-    writeText(path.join(bundle, "install.sh"), installScript("Kiro", "$HOME/.flow-agents", token, '${FLOW_AGENTS_DEST:-$HOME/.flow-agents}'));
+    writeText(path.join(bundle, "install.sh"), installScript("Kiro", "$HOME/.flow-agents", token, '${FLOW_AGENTS_DEST:-$HOME/.flow-agents}', undefined, { runtime: "kiro", version: pkgVersion }));
     fs.chmodSync(path.join(bundle, "install.sh"), 0o755);
 }
 function buildClaudeCode(agents) {
@@ -388,7 +399,7 @@ function buildClaudeCode(agents) {
     writeText(path.join(bundle, ".claude/settings.json"), exportClaudeSettings());
     writeText(path.join(bundle, "AGENTS.md"), exportRootAgentsMd("Claude Code", agents, manifest.claude_code.task_dir));
     writeText(path.join(bundle, "README.md"), exportTargetReadme("Claude Code", "bash install.sh /path/to/workspace"));
-    writeText(path.join(bundle, "install.sh"), installScript("Claude Code", "/path/to/workspace"));
+    writeText(path.join(bundle, "install.sh"), installScript("Claude Code", "/path/to/workspace", undefined, undefined, { configRelPath: ".claude/settings.json", managedConfigRelPath: ".claude/settings.json", runtime: "claude-code", version: pkgVersion }));
     fs.chmodSync(path.join(bundle, "install.sh"), 0o755);
 }
 function buildCodex(agents) {
@@ -409,8 +420,8 @@ function buildCodex(agents) {
         writeText(path.join(bundle, ".codex/skills", name, "SKILL.md"), sanitizeText(readText(src), "codex", "<bundle-root>"));
     }
     writeText(path.join(bundle, "AGENTS.md"), exportRootAgentsMd("Codex", targetAgents, manifest.codex.task_dir));
-    writeText(path.join(bundle, "README.md"), exportTargetReadme("Codex", "bash install.sh /path/to/workspace"));
-    writeText(path.join(bundle, "install.sh"), installScript("Codex", "/path/to/workspace"));
+    writeText(path.join(bundle, "README.md"), exportTargetReadme("Codex", "bash install.sh /path/to/workspace", CODEX_LIVE_HOOKS_README));
+    writeText(path.join(bundle, "install.sh"), installScript("Codex", "/path/to/workspace", undefined, undefined, { configRelPath: ".codex/hooks.json", managedConfigRelPath: ".codex/hooks.json", runtime: "codex", version: pkgVersion }));
     fs.chmodSync(path.join(bundle, "install.sh"), 0o755);
 }
 function exportOpencodeAgent(spec) {
@@ -546,6 +557,7 @@ export const FlowAgentsPlugin = async ({ project, client, $, directory, worktree
       const detail = { tool: input && input.tool };
       runTelemetry('tool.execute.after', detail);
       runAdapter('opencode-hook-adapter.js', 'tool.execute.after', detail, 'quality-gate', 'quality-gate.js', 'default');
+      runAdapter('opencode-hook-adapter.js', 'tool.execute.after', detail, 'evidence-capture', 'evidence-capture.js', 'default');
     },
     'session.idle': async (_input, _output) => {
       runTelemetry('session.idle');
@@ -591,7 +603,7 @@ function buildOpencode(agents) {
     writeText(path.join(bundle, "opencode.json"), exportOpencodeConfig());
     writeText(path.join(bundle, "AGENTS.md"), exportRootAgentsMd("opencode", agents, manifest.opencode.task_dir));
     writeText(path.join(bundle, "README.md"), exportTargetReadme("opencode", "bash install.sh /path/to/workspace"));
-    writeText(path.join(bundle, "install.sh"), installScript("opencode", "/path/to/workspace"));
+    writeText(path.join(bundle, "install.sh"), installScript("opencode", "/path/to/workspace", undefined, undefined, { configRelPath: "opencode.json", managedConfigRelPath: "opencode.json", runtime: "opencode", version: pkgVersion }));
     fs.chmodSync(path.join(bundle, "install.sh"), 0o755);
 }
 function exportPiExtension() {
@@ -679,6 +691,7 @@ export default function (pi: ExtensionAPI) {
   pi.on("tool_result", async (_event, _ctx) => {
     runTelemetry("tool_result");
     runAdapter("pi-hook-adapter.js", "tool_result", "quality-gate", "quality-gate.js");
+    runAdapter("pi-hook-adapter.js", "tool_result", "evidence-capture", "evidence-capture.js");
   });
 
   pi.on("session_shutdown", async (_event, _ctx) => {
@@ -701,7 +714,7 @@ function buildPi(agents) {
     writeText(path.join(bundle, ".pi/extensions/flow-agents.ts"), exportPiExtension());
     writeText(path.join(bundle, "AGENTS.md"), exportRootAgentsMd("pi", agents, manifest.pi.task_dir));
     writeText(path.join(bundle, "README.md"), exportTargetReadme("pi", "bash install.sh /path/to/workspace"));
-    writeText(path.join(bundle, "install.sh"), installScript("pi", "/path/to/workspace"));
+    writeText(path.join(bundle, "install.sh"), installScript("pi", "/path/to/workspace", undefined, undefined, undefined, { runtime: "pi", version: pkgVersion }));
     fs.chmodSync(path.join(bundle, "install.sh"), 0o755);
 }
 function buildCatalog(agents) {
@@ -711,7 +724,6 @@ function buildCatalog(agents) {
         agents: agents.slice().sort((a, b) => a.name.localeCompare(b.name)).map((spec) => spec.name),
         skills: collectAllSkills().map(({ name }) => name),
         powers: fs.readdirSync(path.join(root, "powers")).filter((name) => fs.existsSync(path.join(root, "powers", name, "mcp.json"))).sort(),
-        packs: packs.packs ?? [],
         kits: fs.existsSync(kitsCatalog) ? loadJson(kitsCatalog).kits ?? [] : [],
     };
 }

package/build/src/tools/common.d.ts

@@ -0,0 +1,9 @@
+export declare const root: string;
+export declare function rel(file: string): string;
+export declare function readText(file: string): string;
+export declare function writeText(file: string, text: string): void;
+export declare function loadJson<T = unknown>(file: string): T;
+export declare function exists(file: string): boolean;
+export declare function walkFiles(dir: string): string[];
+export declare function oneLine(value: string, limit?: number): string;
+export declare function markdownTable(headers: string[], rows: string[][]): string[];

package/build/src/tools/generate-context-map.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(argv?: string[]): number;

package/build/src/tools/generate-context-map.js

@@ -10,19 +10,20 @@ const dirDescriptions = {
     context: "Shared contracts, routing notes, templates, and reusable guidance.",
     docs: "Long-lived project documentation and GitHub Pages content.",
     evals: "Static, integration, install, and behavioral eval fixtures.",
-    powers: "Optional MCP/tool integration packs.",
+    powers: "Optional MCP/tool capability bundles.",
     prompts: "Reusable prompt entry points.",
     schemas: "JSON Schema contracts for machine-readable workflow artifacts.",
     scripts: "Build, validation, hook, telemetry, workflow, and import/export utilities.",
     skills: "On-demand capability instructions and workflow primitives.",
 };
-const workflowSkills = new Set(["idea-to-backlog", "pull-work", "plan-work", "execute-plan", "review-work", "verify-work", "evidence-gate", "release-readiness", "learning-review", "deliver", "fix-bug", "tdd-workflow"]);
+const workflowSkills = new Set(["idea-to-backlog", "pull-work", "plan-work", "execute-plan", "review-work", "verify-work", "evidence-gate", "gate-review", "release-readiness", "learning-review", "deliver", "continue-work", "fix-bug", "tdd-workflow"]);
 const commands = [
     ["Source tree", "npm run validate:source"],
     ["Static suite", "bash evals/run.sh static"],
     ["Integration suite", "bash evals/run.sh integration"],
     ["Workflow artifacts", "npm run workflow:validate-artifacts -- --require-sidecars --require-critique .flow-agents/<slug>"],
     ["Workflow sidecars", "npm run workflow:sidecar -- --help"],
+    ["Claim lookup", "npm run workflow:sidecar -- claim <id> <dir>"],
     ["Context map drift", "npm run context-map:check"],
     ["Bundle build", "npm run build:bundles"],
 ];
@@ -154,17 +155,6 @@ function powers() {
     const dir = path.join(root, "powers");
     return fs.readdirSync(dir).sort().flatMap((name) => exists(path.join(dir, name, "POWER.md")) ? [[name, rel(path.join(dir, name, "POWER.md"))]] : []);
 }
-function packs() {
-    const data = loadJson(path.join(root, "packaging/packs.json"));
-    return (data.packs ?? []).map((pack) => [
-        String(pack.name ?? ""),
-        pack.default ? "yes" : "no",
-        String(Array.isArray(pack.skills) ? pack.skills.length : 0),
-        String(Array.isArray(pack.agents) ? pack.agents.length : 0),
-        String(Array.isArray(pack.powers) ? pack.powers.length : 0),
-        oneLine(String(pack.description ?? "")),
-    ]);
-}
 function latestRuntimeStates(includeRuntime) {
     if (!includeRuntime) {
         return [
@@ -205,9 +195,6 @@ function render(includeRuntime) {
         "## Support Skills", "", ...markdownTable(["Skill", "Source", "When To Load"], supportRows), "",
         "## Agents", "", ...markdownTable(["Agent", "Model", "Tools", "Role"], agents()), "",
         "## Optional Powers", "", ...markdownTable(["Power", "Source"], powers()), "",
-        "## Packs", "",
-        "Pack composition is defined in `packaging/packs.json`. The current builder exports pack metadata in bundle catalogs, and generated install scripts support opt-in `FLOW_AGENTS_PACKS` filtering while leaving all packs installed by default.", "",
-        ...markdownTable(["Pack", "Default", "Skills", "Agents", "Powers", "Purpose"], packs()), "",
         "## Current Workflow State", "", ...latestRuntimeStates(includeRuntime), "",
         "## Context Loading Rules", "",
         "- For delivery work, load `deliver`, then the specific primitive skill for the current phase.",

package/build/src/tools/validate-package.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(argv?: string[]): number;

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

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(argv?: string[]): Promise<number>;

package/build/src/tools/validate-source-tree.js

@@ -2,7 +2,7 @@
 import fs from "node:fs";
 import { fileURLToPath } from "node:url";
 import path from "node:path";
-import { spawnSync } from "node:child_process";
+import { validateKitRepository as validateFlowKitRepository } from "../flow-kit/validate.js";
 import { loadJson, readText, rel, root, walkFiles } from "./common.js";
 class Reporter {
     errors = [];
@@ -11,14 +11,10 @@ class Reporter {
         this.fail(message); }
 }
 const manifestPath = path.join(root, "packaging/manifest.json");
-const packsPath = path.join(root, "packaging/packs.json");
 const kitsCatalogPath = path.join(root, "kits/catalog.json");
 const flowRoot = process.env.FLOW_CLI_ROOT ? path.resolve(process.env.FLOW_CLI_ROOT) : "";
 const flowSchemaPath = flowRoot ? path.join(flowRoot, "schemas", "flow-definition.schema.json") : "";
 const flowCliPath = flowRoot ? ["dist/cli.js", "src/cli.js"].map((candidate) => path.join(flowRoot, candidate)).find((candidate) => fs.existsSync(candidate)) ?? path.join(flowRoot, "dist/cli.js") : "";
-const kitIdRe = /^[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*)*$/;
-const kitAssetSections = new Set(["skills", "docs", "adapters", "evals", "assets"]);
-const kitTopLevelKeys = new Set(["schema_version", "id", "name", "product_name", "description", "flows", ...kitAssetSections]);
 const textRefExtensions = new Set([".md", ".yaml", ".yml", ".json", ".sh", ".js", ".toml"]);
 const ignoredRefDirs = new Set(["node_modules", "__pycache__", ".pytest_cache", ".cache"]);
 const legacyRefRe = /(?<![A-Za-z0-9_.-])(?:agents|agent-cards|context|evals|lib|powers|prompts|scripts|skills)\/[A-Za-z0-9_./@:+-]+/g;
@@ -32,10 +28,8 @@ const mirroredFiles = new Map([
 ]);
 const publicScriptWrappers = new Map([
     ["scripts/build-universal-bundles.js", { target: "../build/src/tools/build-universal-bundles.js", significantLines: [
-                "// Supports FLOW_AGENTS_PACKS through the TypeScript bundle builder.",
                 'import("../build/src/tools/build-universal-bundles.js").then(({ main }) => process.exit(main()));',
             ] }],
-    ["scripts/filter-installed-packs.js", { target: "../build/src/tools/filter-installed-packs.js", significantLines: ['import("../build/src/tools/filter-installed-packs.js").then(({ main }) => process.exit(main(process.argv.slice(2))));'] }],
     ["scripts/generate-context-map.js", { target: "../build/src/tools/generate-context-map.js", significantLines: ['import("../build/src/tools/generate-context-map.js").then(({ main }) => process.exit(main(process.argv.slice(2))));'] }],
     ["scripts/kit.js", { target: "../build/src/cli/kit.js", significantLines: ['import("../build/src/cli/kit.js").then(({ main }) => main().then((code) => process.exit(code)));'] }],
     ["scripts/pull-work-provider.js", { target: "../build/src/cli/pull-work-provider.js", significantLines: ['import("../build/src/cli/pull-work-provider.js").then(({ main }) => process.exit(main()));'] }],
@@ -62,6 +56,7 @@ const hookFilePolicies = new Map([
     ["scripts/hooks/codex-telemetry-hook.js", { category: "telemetry shim", requiredNeedles: ["codex", "telemetry"] }],
     ["scripts/hooks/run-hook.js", { category: "hook runner", requiredNeedles: ["isHookEnabled", "Path traversal rejected"] }],
     ["scripts/hooks/config-protection.js", { category: "policy hook", requiredNeedles: ["Config Protection Hook"] }],
+    ["scripts/hooks/evidence-capture.js", { category: "policy hook", requiredNeedles: ["Evidence Capture Hook"] }],
     ["scripts/hooks/governance-audit.sh", { category: "policy hook", requiredNeedles: ["governance-audit.sh", "audit_emit"] }],
     ["scripts/hooks/opencode-hook-adapter.js", { category: "runtime adapter", requiredNeedles: ["opencode", "run-hook.js"] }],
     ["scripts/hooks/opencode-telemetry-hook.js", { category: "telemetry shim", requiredNeedles: ["opencode", "telemetry"] }],
@@ -78,6 +73,7 @@ const hookFilePolicies = new Map([
     ["scripts/hooks/desktop-notify.sh", { category: "local notification helper", requiredNeedles: ["desktop-notify.sh", "osascript"] }],
     ["scripts/hooks/lib/audit-transport.sh", { category: "shared hook library", requiredNeedles: ["audit_emit"] }],
     ["scripts/hooks/lib/hook-flags.js", { category: "shared hook library", requiredNeedles: ["isHookEnabled"] }],
+    ["scripts/hooks/lib/liveness-read.js", { category: "shared hook library", requiredNeedles: ["freshHolders", "readLivenessEvents"] }],
     ["scripts/hooks/lib/patterns.sh", { category: "shared hook library", requiredNeedles: ["_detect_secrets"] }],
     ["scripts/hooks/lib/resolve-formatter.js", { category: "shared hook library", requiredNeedles: ["resolveFormatter"] }],
 ]);
@@ -196,81 +192,7 @@ function validateManifest(reporter, manifest, agentNames) {
     for (const agent of manifest.codex?.excluded_agents ?? [])
         reporter.check(agentNames.has(agent), `${rel(manifestPath)}: codex excluded agent '${agent}' does not exist`);
 }
-function validatePacksManifest(reporter, agentNames) {
-    const data = tryLoadJson(packsPath, reporter);
-    if (!data || typeof data !== "object")
-        return;
-    reporter.check(data.schema_version === "1.0", `${rel(packsPath)}: schema_version must be 1.0`);
-    reporter.check(Array.isArray(data.packs) && data.packs.length > 0, `${rel(packsPath)}: packs must be a non-empty list`);
-    const skillNames = new Set(fs.readdirSync(path.join(root, "skills")).filter((name) => fs.existsSync(path.join(root, "skills", name, "SKILL.md"))));
-    const powerNames = new Set(fs.readdirSync(path.join(root, "powers")).filter((name) => fs.existsSync(path.join(root, "powers", name, "POWER.md"))));
-    const names = new Set();
-    const defaults = new Set();
-    const assigned = { skills: new Set(), agents: new Set(), powers: new Set() };
-    (Array.isArray(data.packs) ? data.packs : []).forEach((pack, index) => {
-        const name = pack?.name;
-        if (typeof name !== "string" || !/^[a-z][a-z0-9-]*$/.test(name)) {
-            reporter.fail(`${rel(packsPath)}: packs[${index}].name must be a kebab-case string`);
-            return;
-        }
-        if (names.has(name))
-            reporter.fail(`${rel(packsPath)}: duplicate pack name '${name}'`);
-        names.add(name);
-        if (pack.default === true)
-            defaults.add(name);
-        reporter.check(typeof pack.description === "string" && !!pack.description, `${rel(packsPath)}: pack '${name}' missing description`);
-        for (const [field, available] of [["skills", skillNames], ["agents", agentNames], ["powers", powerNames]]) {
-            const values = pack[field] ?? [];
-            reporter.check(Array.isArray(values), `${rel(packsPath)}: pack '${name}' .${field} must be a list`);
-            const seen = new Set();
-            for (const value of Array.isArray(values) ? values : []) {
-                if (typeof value !== "string") {
-                    reporter.fail(`${rel(packsPath)}: pack '${name}' .${field} entry is not a string`);
-                    continue;
-                }
-                if (seen.has(value))
-                    reporter.fail(`${rel(packsPath)}: pack '${name}' has duplicate ${field} entry '${value}'`);
-                seen.add(value);
-                assigned[field].add(value);
-                reporter.check(available.has(value), `${rel(packsPath)}: pack '${name}' references missing ${field.slice(0, -1)} '${value}'`);
-            }
-        }
-    });
-    reporter.check(defaults.has("core"), `${rel(packsPath)}: core pack must be default`);
-    const missingSkills = [...skillNames].filter((name) => !assigned.skills.has(name)).sort();
-    reporter.check(missingSkills.length === 0, `${rel(packsPath)}: skills missing from all packs: ${missingSkills.join(", ")}`);
-}
-function safeLocalPath(baseDir, pathText, label, reporter) {
-    if (typeof pathText !== "string" || !pathText) {
-        reporter.fail(`${label} must be a non-empty relative path`);
-        return undefined;
-    }
-    if (path.isAbsolute(pathText)) {
-        reporter.fail(`${label} must be relative; absolute paths are not allowed`);
-        return undefined;
-    }
-    if (pathText.split(/[\\/]/).includes("..")) {
-        reporter.fail(`${label} must stay inside the kit directory; '..' path traversal is not allowed`);
-        return undefined;
-    }
-    return path.join(baseDir, pathText);
-}
-function validateFlowDefinitionShape(file, data, reporter) {
-    const localCli = flowCliPath;
-    if (fs.existsSync(localCli)) {
-        const result = spawnSync("node", [localCli, "validate-definition", file, "--json"], { encoding: "utf8" });
-        if (result.status !== 0)
-            reporter.fail(`${rel(file)}: Flow validation failed: ${(result.stderr || result.stdout).trim()}`);
-        return;
-    }
-    if (!data || typeof data !== "object") {
-        reporter.fail(`${rel(file)}: Flow Definition must be an object`);
-        return;
-    }
-    for (const key of ["id", "version", "steps", "gates"])
-        reporter.check(key in data, `${rel(file)}: missing .${key}`);
-}
-function validateKitRepository(kitDir, reporter) {
+async function validateKitRepository(kitDir, reporter) {
     if (!fs.existsSync(kitDir) || !fs.statSync(kitDir).isDirectory()) {
         reporter.fail(`${rel(kitDir)}: kit directory does not exist`);
         return;
@@ -279,78 +201,10 @@ function validateKitRepository(kitDir, reporter) {
     reporter.check(fs.existsSync(kitJson), `${rel(kitDir)}: missing kit.json at repository root`);
     if (!fs.existsSync(kitJson))
         return;
-    const data = tryLoadJson(kitJson, reporter);
-    if (!data || typeof data !== "object")
-        return;
-    const unknownKeys = Object.keys(data).filter((key) => !kitTopLevelKeys.has(key)).sort();
-    if (unknownKeys.length)
-        reporter.fail(`${rel(kitJson)}: unsupported fields ${unknownKeys.join(", ")}; remove them or add them to the Flow Kit Repository contract`);
-    reporter.check(data.schema_version === "1.0", `${rel(kitJson)}: .schema_version must be "1.0"`);
-    reporter.check(typeof data.id === "string" && kitIdRe.test(data.id), `${rel(kitJson)}: .id must be a stable kebab-case string`);
-    reporter.check(typeof data.name === "string" && !!data.name.trim(), `${rel(kitJson)}: .name must be a non-empty string`);
-    for (const section of [...kitAssetSections].sort())
-        if (section in data) {
-            if (!Array.isArray(data[section])) {
-                reporter.fail(`${rel(kitJson)}: .${section} must be a list of relative asset paths or objects with path`);
-                continue;
-            }
-            const seenPaths = new Set();
-            const seenIds = new Set();
-            data[section].forEach((entry, index) => {
-                const pathValue = typeof entry === "string" ? entry : entry?.path;
-                const assetId = typeof entry === "object" ? entry.id : undefined;
-                if (typeof entry === "object") {
-                    const unknown = Object.keys(entry).filter((key) => !["id", "path", "description"].includes(key)).sort();
-                    if (unknown.length)
-                        reporter.fail(`${rel(kitJson)}: ${section}[${index}] has unsupported fields ${unknown.join(", ")}; use id, path, or description`);
-                }
-                if (assetId !== undefined && (typeof assetId !== "string" || !kitIdRe.test(assetId)))
-                    reporter.fail(`${rel(kitJson)}: ${section}[${index}].id must be a stable dot/kebab-case string`);
-                const assetPath = safeLocalPath(kitDir, pathValue, `${rel(kitJson)}: ${section}[${index}].path`, reporter);
-                if (!assetPath)
-                    return;
-                if (seenPaths.has(String(pathValue)))
-                    reporter.fail(`${rel(kitJson)}: ${section}[${index}].path duplicates '${pathValue}'; declare each asset once`);
-                seenPaths.add(String(pathValue));
-                if (typeof assetId === "string") {
-                    if (seenIds.has(assetId))
-                        reporter.fail(`${rel(kitJson)}: ${section}[${index}].id duplicates '${assetId}'; use a unique asset id`);
-                    seenIds.add(assetId);
-                }
-                reporter.check(fs.existsSync(assetPath), `${rel(kitJson)}: ${section}[${index}].path points at missing asset: ${pathValue}; add the file or remove the entry`);
-            });
-        }
-    if (!Array.isArray(data.flows) || !data.flows.length) {
-        reporter.fail(`${rel(kitJson)}: .flows must be a non-empty list; add at least one Flow Definition entry`);
-        return;
-    }
-    const seenIds = new Set();
-    const seenPaths = new Set();
-    data.flows.forEach((flow, index) => {
-        if (!flow || typeof flow !== "object") {
-            reporter.fail(`${rel(kitJson)}: flows[${index}] must be an object with id and path`);
-            return;
-        }
-        if (typeof flow.id !== "string" || !kitIdRe.test(flow.id))
-            reporter.fail(`${rel(kitJson)}: flows[${index}].id must be a stable dot/kebab-case string`);
-        else if (seenIds.has(flow.id))
-            reporter.fail(`${rel(kitJson)}: flows[${index}].id duplicates '${flow.id}'; use a unique Flow id`);
-        else
-            seenIds.add(flow.id);
-        const flowPath = safeLocalPath(kitDir, flow.path, `${rel(kitJson)}: flows[${index}].path`, reporter);
-        if (!flowPath)
-            return;
-        if (seenPaths.has(String(flow.path))) {
-            reporter.fail(`${rel(kitJson)}: flows[${index}].path duplicates '${flow.path}'; declare each Flow Definition once`);
-            return;
-        }
-        seenPaths.add(String(flow.path));
-        reporter.check(fs.existsSync(flowPath), `${rel(kitJson)}: flows[${index}].path points at missing Flow Definition: ${flow.path}; add the file or fix the path`);
-        if (fs.existsSync(flowPath))
-            validateFlowDefinitionShape(flowPath, tryLoadJson(flowPath, reporter), reporter);
-    });
+    for (const error of await validateFlowKitRepository(kitDir))
+        reporter.fail(error);
 }
-function validateKits(reporter) {
+async function validateKits(reporter) {
     reporter.check(fs.existsSync(path.join(root, "kits")), "kits directory missing");
     const catalog = tryLoadJson(kitsCatalogPath, reporter);
     const kits = catalog?.kits;
@@ -362,17 +216,17 @@ function validateKits(reporter) {
         console.log(fs.existsSync(localCli) ? `info: validating kit Flow Definitions with Flow CLI at ${localCli}` : `warning: Flow validator unavailable; source-tree check only verifies Flow Definition top-level shape`);
     else
         console.log("warning: Flow schema not configured; source-tree check only verifies Flow Definition top-level shape. Set FLOW_CLI_ROOT to enable Flow CLI validation. Container validation (kit.json core fields) will delegate to 'flow validate-kit' from @kontourai/flow when FLOW_CLI_ROOT is available.");
-    kits.forEach((entry, index) => {
+    for (const [index, entry] of kits.entries()) {
         const kitText = typeof entry === "string" ? entry : ["path", "directory", "dir", "id", "name"].map((key) => entry?.[key]).find((value) => typeof value === "string" && value);
         if (!kitText) {
             reporter.fail(`${rel(kitsCatalogPath)}: kits[${index}] missing path, directory, dir, id, or name`);
-            return;
+            continue;
         }
         const kitRef = String(kitText).startsWith("kits/") ? path.join(root, kitText) : path.join(root, "kits", kitText);
         const kitDir = path.basename(kitRef) === "kit.json" ? path.dirname(kitRef) : kitRef;
         reporter.check(fs.existsSync(kitDir) && fs.statSync(kitDir).isDirectory(), `${rel(kitsCatalogPath)}: kits[${index}] points at missing kit folder: ${kitText}`);
-        validateKitRepository(kitDir, reporter);
-    });
+        await validateKitRepository(kitDir, reporter);
+    }
 }
 function validateAgentPaths(reporter, manifest) {
     for (const file of walkFiles(path.join(root, "agents")).filter((item) => item.endsWith(".json"))) {
@@ -480,6 +334,32 @@ function validatePublicScriptWrappers(reporter) {
         reporter.check(JSON.stringify(significantLines) === JSON.stringify(policy.significantLines), `${file}: public wrapper must match the exact thin launcher body for ${policy.target}`);
     }
 }
+function validateAdrNumbers(reporter) {
+    // Each ADR (a docs/adr file with an `# ADR NNNN:` heading) must own a unique
+    // number, and its filename prefix must match that number. Companion/index docs
+    // without an ADR heading (e.g. a numbered skill-audit tied to an ADR) are
+    // intentionally skipped. Guards against concurrent number collisions like the
+    // duplicate ADR 0014 from PRs #180/#172.
+    const adrDir = path.join(root, "docs/adr");
+    if (!fs.existsSync(adrDir))
+        return;
+    const byNumber = new Map();
+    for (const file of walkFiles(adrDir)) {
+        if (path.extname(file) !== ".md")
+            continue;
+        const heading = readText(file).match(/^#\s+ADR\s+(\d{4}):/m);
+        if (!heading)
+            continue; // not an ADR decision doc
+        const num = heading[1];
+        reporter.check(path.basename(file).startsWith(`${num}-`), `${rel(file)}: ADR heading number ${num} does not match the filename prefix`);
+        const list = byNumber.get(num) ?? [];
+        list.push(rel(file));
+        byNumber.set(num, list);
+    }
+    for (const [num, files] of byNumber) {
+        reporter.check(files.length === 1, `docs/adr: duplicate ADR number ${num} — ${files.join(", ")}. ADR numbers must be unique; renumber one.`);
+    }
+}
 function validateHookInventory(reporter) {
     const readme = readText(path.join(root, "scripts/README.md"));
     const hookFiles = walkFiles(path.join(root, "scripts/hooks"))
@@ -605,7 +485,7 @@ function validateNoFirstPartyPythonCommands(reporter) {
         reporter.fail(`${relative}: direct first-party Python command reference is not allowed; use npm/flow-agents TypeScript commands`);
     }
 }
-export function main(argv = process.argv.slice(2)) {
+export async function main(argv = process.argv.slice(2)) {
     const kitIndex = argv.indexOf("--kit");
     if (kitIndex >= 0) {
         const kitDir = argv[kitIndex + 1];
@@ -619,7 +499,7 @@ export function main(argv = process.argv.slice(2)) {
             console.log(`info: validating kit Flow Definitions with Flow CLI at ${localCli}`);
         else
             console.log("warning: Flow validation surface unavailable; local kit check uses the minimal Flow Definition fallback");
-        validateKitRepository(path.resolve(kitDir), reporter);
+        await validateKitRepository(path.resolve(kitDir), reporter);
         if (reporter.errors.length) {
             console.log("Flow Kit repository validation failed:");
             for (const error of reporter.errors)
@@ -635,14 +515,14 @@ export function main(argv = process.argv.slice(2)) {
     validateAgentCards(reporter, agentNames);
     validatePowers(reporter);
     validateManifest(reporter, manifest, agentNames);
-    validatePacksManifest(reporter, agentNames);
-    validateKits(reporter);
+    await validateKits(reporter);
     validateAgentPaths(reporter, manifest);
     validateLegacyRefs(reporter);
     validateMirrors(reporter);
     validateUsageFeedbackFiles(reporter);
     validatePublicScriptWrappers(reporter);
     validateHookInventory(reporter);
+    validateAdrNumbers(reporter);
     validateFixtureOwnership(reporter);
     validatePackageCommandSurface(reporter);
     validateNoFirstPartyPythonFiles(reporter);
@@ -672,5 +552,5 @@ catch {
     return process.argv[1];
 } })();
 if (_selfRealPath === _argv1RealPath) {
-    process.exitCode = main();
+    main().then((code) => { process.exitCode = code; });
 }

package/context/contracts/artifact-contract.md

@@ -20,6 +20,16 @@ The artifact root is local working memory unless a workflow explicitly promotes
 - Do not commit local workflow runtime roots such as `.flow-agents/<slug>/` as durable policy unless a repository-specific contract explicitly says that artifact is promoted.
 - Do not commit local workflow runtime roots such as `.flow-agents/<slug>/`; final acceptance must promote durable content before merge.
 
+## Persistence Integrity
+
+Writing a durable artifact must **fail loud, never fail-open.** If a record (state, evidence, a
+trust.bundle, a claim) cannot be persisted — a missing dependency, a validation failure, an I/O
+error — the operation **fails with the reason**; it must not return success while silently
+dropping the write. A silently-skipped persist is **data loss**, not a degraded mode, and is
+invisible to the caller that depended on it. Callers act on persistence **return values**, not
+just thrown exceptions. (See #160: an ignored `{written:false}` from the bundle writer dropped
+records under concurrency.)
+
 ## Required Artifact Types
 
 ### Structured Sidecars

package/context/contracts/delivery-contract.md

@@ -61,6 +61,7 @@ After CI passes and the work is merged, released, or otherwise accepted:
 - [ ] durable docs link back to the provider record, archived plan, or session artifact when useful
 - [ ] local `.flow-agents/` runtime artifacts remain untracked, and durable outcomes are promoted before merge to `main`
 - [ ] follow-up issues or learning-review items created for deferred work
+- [ ] **workspace cleaned up after a confirmed merge**: the merge is verified from the provider's own merge record (a merge commit / `mergedAt`), not a green check or a command exit code; then the isolated worktree is removed and the now-merged branch is deleted locally and on the remote, honoring the `worktree_lifecycle` (`retain_until: pr_merged`) recorded at selection. Never delete a branch or worktree before the merge is confirmed. A delivery is not complete while it leaves a stale worktree or merged branch behind.
 
 ## Distribution Rule
 

package/context/contracts/review-contract.md

@@ -59,6 +59,7 @@ All reviewers are read-only reporters. They may inspect files, run read-only ana
 Attempt relevant perspectives and record findings:
 
 - Code quality: readability, naming, function/file size, error handling, duplication, maintainability
+- Failure handling: callers act on failure *return values*, not just exceptions — flag fail-open on any data-persisting path (per the persistence-integrity invariant in the artifact contract)
 - Correctness risks: edge cases, unintended behavior, unsafe assumptions, missing tests
 - Standards fit: project conventions, local architecture, public contracts, documented decisions
 - Security: secrets, injection, XSS, path traversal, auth/authz, unsafe external calls, vulnerable dependencies