@kontourai/flow-agents 1.4.0 → 2.0.1

package/src/cli.ts

@@ -14,19 +14,18 @@ import { main as veritasGovernance } from "./cli/veritas-governance.js";
 import { main as workflowArtifactCleanupAudit } from "./cli/workflow-artifact-cleanup-audit.js";
 import { main as buildBundles } from "./tools/build-universal-bundles.js";
 import { main as contextMap } from "./tools/generate-context-map.js";
-import { main as filterInstalledPacks } from "./tools/filter-installed-packs.js";
 import { main as validateSource } from "./tools/validate-source-tree.js";
 import { main as validatePackage } from "./tools/validate-package.js";
 import { main as validateHookInfluence } from "./cli/validate-hook-influence.js";
 import { main as runtimeAdapter } from "./cli/runtime-adapter.js";
 import { main as utteranceCheck } from "./cli/utterance-check.js";
+import { main as verify } from "./cli/verify.js";
 
 const availableCommands = new Map<string, (argv: string[]) => number | Promise<number>>([
   ["build-bundles", () => buildBundles()],
   ["console-learning-projection", consoleLearningProjection],
   ["context-map", contextMap],
   ["effective-backlog-settings", effectiveBacklogSettings],
-  ["filter-installed-packs", filterInstalledPacks],
   ["fixture-retirement-audit", fixtureRetirementAudit],
   ["kit", kit],
   ["init", init],
@@ -40,6 +39,7 @@ const availableCommands = new Map<string, (argv: string[]) => number | Promise<n
   ["veritas-governance", veritasGovernance],
   ["validate-package", validatePackage],
   ["validate-hook-influence", validateHookInfluence],
+  ["verify", verify],
   ["validate-source", validateSource],
   ["workflow-artifact-cleanup-audit", workflowArtifactCleanupAudit],
 ]);
@@ -49,7 +49,6 @@ const aliases = new Map<string, string>([
   ["flow-agents-console-learning-projection", "console-learning-projection"],
   ["flow-agents-context-map", "context-map"],
   ["flow-agents-effective-backlog-settings", "effective-backlog-settings"],
-  ["flow-agents-filter-installed-packs", "filter-installed-packs"],
   ["flow-agents-fixture-retirement-audit", "fixture-retirement-audit"],
   ["flow-agents-kit", "kit"],
   ["flow-agents-promote-workflow-artifact", "promote-workflow-artifact"],

package/src/lib/flow-resolver.ts

@@ -0,0 +1,369 @@
+/**
+ * Flow-Definition resolver — ADR 0016 Abstraction A (Option B), Phase P-a.
+ *
+ * Shared resolver consumed by both the producer (workflow-sidecar.ts) and,
+ * later, the enforcer (stop-goal-fit.js via P-c). This is the SINGLE source
+ * of truth for (active_flow_id, active_step_id) → FlowDefinition gate
+ * expects[] resolution. Neither consumer duplicates this logic.
+ *
+ * Design:
+ *   - Pure and synchronous — no async, no throws.
+ *   - Returns null on ENOENT, parse error, or missing gate (fail-open).
+ *   - Kit-agnostic: kitId = flowId.split(".")[0]; no hardcoded kit list.
+ *   - Honors FLOW_AGENTS_FLOW_DEFS_DIR env-var override for custom installs.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+// ─── Security: Layer 1 traversal defense ─────────────────────────────────────
+//
+// Both kitId and flowName originate from agent-writable sources (active_flow_id
+// in current.json, and FLOW_AGENTS_FLOW_DEFS_DIR set by the runtime). A crafted
+// value like "builder.../../../.flow-agents/slug/fake-flow" produces:
+//   kitId = "builder"
+//   flowName = "../../../.flow-agents/slug/fake-flow"
+// which resolves OUTSIDE kits/ via path.join traversal.
+//
+// SLUG_RE closes this: it rejects any value containing path separators, dots,
+// or characters outside the safe identifier alphabet. Only [a-zA-Z0-9_-] is
+// allowed, making traversal sequences impossible.
+//
+// Belt-and-suspenders: after building the path we also confirm the resolved
+// absolute path stays inside the expected root directory.
+
+/** Strict slug pattern — allows only URL-safe identifier chars. */
+const SLUG_RE = /^[a-zA-Z0-9_-]+$/;
+
+/**
+ * Returns true when the given resolved absolute path falls within a .flow-agents
+ * directory (an agent-writable area). Used to reject FLOW_AGENTS_FLOW_DEFS_DIR
+ * overrides that point into agent-controlled storage.
+ */
+function isAgentWritableDir(resolvedDir: string): boolean {
+  return resolvedDir.split(path.sep).includes(".flow-agents");
+}
+
+/**
+ * Build and validate the FlowDefinition file path.
+ *
+ * Returns the validated absolute file path, or null when:
+ *  - kitId or flowName contains chars outside SLUG_RE (rejects traversal)
+ *  - FLOW_AGENTS_FLOW_DEFS_DIR resolves into a .flow-agents directory
+ *  - The resolved path escapes the expected root (belt-and-suspenders)
+ *
+ * When the override is unsafe (points into .flow-agents), falls back silently
+ * to the repoRoot/kits/ path so the resolver still works for legit flows.
+ */
+export function resolveFlowFilePath(
+  kitId: string,
+  flowName: string,
+  flowId: string,
+  repoRoot: string,
+): string | null {
+  // Primary defense: reject any slug containing traversal chars or non-identifier chars.
+  if (!SLUG_RE.test(kitId) || !SLUG_RE.test(flowName)) return null;
+
+  const override = process.env["FLOW_AGENTS_FLOW_DEFS_DIR"];
+
+  let expectedRoot: string;
+  let flowFilePath: string;
+
+  if (override) {
+    const resolvedOverride = path.resolve(override);
+    if (isAgentWritableDir(resolvedOverride)) {
+      // Override targets an agent-writable .flow-agents path — reject it and
+      // fall back to the kit root.  The session will resolve the real kit flow.
+      expectedRoot = path.resolve(repoRoot, "kits");
+      flowFilePath = path.join(repoRoot, "kits", kitId, "flows", `${flowName}.flow.json`);
+    } else {
+      expectedRoot = resolvedOverride;
+      // flowId = kitId + "." + flowName; after slug validation this contains only
+      // [a-zA-Z0-9_-.] — no slashes, no traversal.
+      flowFilePath = path.join(resolvedOverride, `${flowId}.flow.json`);
+    }
+  } else {
+    expectedRoot = path.resolve(repoRoot, "kits");
+    flowFilePath = path.join(repoRoot, "kits", kitId, "flows", `${flowName}.flow.json`);
+  }
+
+  // Belt-and-suspenders: confirm the resolved path stays within the expected root.
+  // After slug validation this is theoretically unreachable, but defense-in-depth
+  // verifies the invariant rather than merely asserting it.
+  const resolvedPath = path.resolve(flowFilePath);
+  if (!resolvedPath.startsWith(expectedRoot + path.sep) && resolvedPath !== expectedRoot) {
+    return null; // traversal still detected — paranoid fallback
+  }
+
+  return resolvedPath;
+}
+
+// ─── Public types ─────────────────────────────────────────────────────────────
+
+/** A single gate expectation from a FlowDefinition expects[] entry. */
+export type GateExpectation = {
+  id: string;
+  kind: string;
+  required: boolean;
+  bundle_claim: {
+    claimType: string;
+    subjectType: string;
+    accepted_statuses: string[];
+  };
+};
+
+/** The resolved result from the active flow step. */
+export type ActiveFlowStep = {
+  flowId: string;
+  stepId: string;
+  gateId: string;
+  gateExpects: GateExpectation[];
+};
+
+/** Shape of a gate entry in the FlowDefinition JSON. */
+type FlowGate = {
+  step: string;
+  expects?: GateExpectation[];
+  /** Reason-to-step mapping for route-back transitions (e.g. {"implementation_defect": "execute"}). */
+  on_route_back?: Record<string, string>;
+  /** Policy governing route-back attempt limits. */
+  route_back_policy?: { max_attempts: number; on_exceeded: string };
+};
+
+/** Shape of a FlowDefinition JSON file. */
+type FlowDefinition = {
+  id: string;
+  version: string;
+  /** Kit-owned phase→step mapping (ADR 0016 Abstraction A P-d). Maps lifecycle phase names
+   *  (e.g. "execution") to step ids (e.g. "execute") so advance-state can write active_step_id
+   *  without hardcoding any vocabulary in the core. */
+  phase_map?: Record<string, string>;
+  steps?: Array<{ id: string; next: string | null }>;
+  gates?: Record<string, FlowGate>;
+};
+
+/**
+ * Resolve the gate expects[] for a specific (flowId, stepId) pair.
+ *
+ * @param flowId   e.g. "builder.build" — kitId is extracted as the prefix before the first ".".
+ * @param stepId   e.g. "verify" — matched against gate.step values in the FlowDefinition.
+ * @param repoRoot Absolute path to the repository root (kits/ lives here).
+ *                 Honored only when FLOW_AGENTS_FLOW_DEFS_DIR is not set.
+ * @returns ActiveFlowStep with the matched gate's expects[], or null on any error.
+ */
+export function resolveFlowStep(flowId: string, stepId: string, repoRoot: string): ActiveFlowStep | null {
+  if (!flowId || !stepId) return null;
+  const dotIdx = flowId.indexOf(".");
+  if (dotIdx < 1) return null; // flowId must have at least one "." to derive kitId
+  const kitId = flowId.slice(0, dotIdx);
+  // The flow filename is the part after the first "." (e.g. "build" from "builder.build")
+  const flowName = flowId.slice(dotIdx + 1);
+  if (!kitId || !flowName) return null;
+
+  // Layer 1 defense: validate stepId too — it is matched against gate.step values but
+  // still originates from agent-writable current.json active_step_id.
+  if (!SLUG_RE.test(stepId)) return null;
+
+  // Determine the FlowDefinition file path with slug validation + path containment check.
+  // Returns null for traversal attempts (e.g. flowName = "../../../.flow-agents/fake").
+  const flowFilePath = resolveFlowFilePath(kitId, flowName, flowId, repoRoot);
+  if (!flowFilePath) return null;
+
+  let flowDef: FlowDefinition;
+  try {
+    const raw = fs.readFileSync(flowFilePath, "utf8");
+    flowDef = JSON.parse(raw) as FlowDefinition;
+  } catch {
+    return null; // ENOENT, permission error, or parse error → fail-open
+  }
+
+  if (!flowDef || typeof flowDef !== "object" || !flowDef.gates) return null;
+
+  // Find the gate whose .step matches stepId.
+  for (const [gateId, gate] of Object.entries(flowDef.gates)) {
+    if (!gate || gate.step !== stepId) continue;
+    const expects = Array.isArray(gate.expects) ? gate.expects : [];
+    return { flowId, stepId, gateId, gateExpects: expects };
+  }
+
+  return null; // no gate matched the given stepId
+}
+
+
+/**
+ * Resolve the phase→step mapping from a FlowDefinition's phase_map field.
+ *
+ * Returns the phase_map object (e.g. {"execution":"execute","planning":"plan",...})
+ * or null when the flow file cannot be loaded, the phase_map field is absent, or
+ * the field is not a plain Record<string,string>.
+ *
+ * Pure and synchronous — no throws, fail-open on any error.
+ *
+ * @param flowId   e.g. "builder.build" — kitId is the prefix before the first ".".
+ * @param repoRoot Absolute path to the repository root (kits/ lives here).
+ *                 Honored only when FLOW_AGENTS_FLOW_DEFS_DIR is not set.
+ * @returns Record<string,string> phase→stepId map, or null on absence/error.
+ */
+export function resolvePhaseMap(flowId: string, repoRoot: string): Record<string, string> | null {
+  if (!flowId) return null;
+  const dotIdx = flowId.indexOf(".");
+  if (dotIdx < 1) return null;
+  const kitId = flowId.slice(0, dotIdx);
+  const flowName = flowId.slice(dotIdx + 1);
+  if (!kitId || !flowName) return null;
+
+  // Layer 1 defense: same slug validation + path containment as resolveFlowStep.
+  const flowFilePath = resolveFlowFilePath(kitId, flowName, flowId, repoRoot);
+  if (!flowFilePath) return null;
+
+  let flowDef: FlowDefinition;
+  try {
+    const raw = fs.readFileSync(flowFilePath, "utf8");
+    flowDef = JSON.parse(raw) as FlowDefinition;
+  } catch {
+    return null; // ENOENT, permission error, or parse error → fail-open
+  }
+
+  if (!flowDef || typeof flowDef !== "object") return null;
+  const pm = flowDef.phase_map;
+  if (!pm || typeof pm !== "object" || Array.isArray(pm)) return null;
+  // Validate: all values must be strings
+  for (const v of Object.values(pm)) {
+    if (typeof v !== "string") return null;
+  }
+  return pm as Record<string, string>;
+}
+
+/**
+ * Find the repository root from a starting directory by walking upward to locate
+ * the nearest ancestor that contains a `kits/` subdirectory. If none is found,
+ * falls back to `process.cwd()` so the default "run from repo root" case still works.
+ *
+ * This is required because the .flow-agents directory can live anywhere (temp dirs,
+ * subprojects, CI workspaces) while the kits/ directory is always at the repo root.
+ */
+function findRepoRoot(startDir: string): string {
+  // Walk up from startDir looking for a kits/ directory
+  let dir = startDir;
+  for (let i = 0; i < 16; i++) {
+    if (fs.existsSync(path.join(dir, "kits"))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break; // reached filesystem root
+    dir = parent;
+  }
+  // Fallback: process.cwd() covers the common "run from repo root" case
+  return process.cwd();
+}
+
+/**
+ * Resolve the active flow step from current.json.
+ *
+ * Reads active_flow_id and active_step_id from <flowAgentsDir>/current.json.
+ * If both are present, delegates to resolveFlowStep. The repoRoot is derived by
+ * walking upward from flowAgentsDir to find the nearest ancestor containing kits/,
+ * with a fallback to process.cwd(). This handles temp dirs, CI workspaces, and
+ * subproject layouts without hardcoding the repo structure.
+ *
+ * @param flowAgentsDir Path to the .flow-agents directory (contains current.json).
+ * @returns ActiveFlowStep or null when fields are absent or resolution fails.
+ */
+export function resolveActiveFlowStep(flowAgentsDir: string): ActiveFlowStep | null {
+  if (!flowAgentsDir) return null;
+  const currentFile = path.join(flowAgentsDir, "current.json");
+  let current: Record<string, unknown>;
+  try {
+    const raw = fs.readFileSync(currentFile, "utf8");
+    current = JSON.parse(raw) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+
+  const flowId = typeof current["active_flow_id"] === "string" ? current["active_flow_id"] : null;
+  const stepId = typeof current["active_step_id"] === "string" ? current["active_step_id"] : null;
+  if (!flowId || !stepId) return null;
+
+  // Find repoRoot: walk up from flowAgentsDir to find kits/, fallback to cwd
+  const repoRoot = findRepoRoot(path.dirname(flowAgentsDir));
+  return resolveFlowStep(flowId, stepId, repoRoot);
+}
+
+/** The resolved route-back policy for a phase transition. */
+export type RouteBackPolicy = {
+  /** Maximum allowed route-back attempts for this transition key. */
+  maxAttempts: number;
+  /** Action when attempts are exceeded (e.g. "block"). */
+  onExceeded: string;
+  /** The step id whose gate declared this policy (e.g. "verify"). */
+  fromStepId: string;
+};
+
+/**
+ * Resolve the route-back policy for a phase transition, if the active FlowDefinition
+ * declares one on the source phase's gate.
+ *
+ * A route-back is a transition where the source phase's gate declares both
+ * `route_back_policy` and `on_route_back`, and the target phase maps to a step
+ * listed as a route-back target in `on_route_back` values.
+ *
+ * This is the FlowDefinition-driven replacement for the hardcoded
+ * `flow === "builder.build" && prev.phase === "verification" && phase === "execution"`
+ * guard in advance-state. Any flow that declares `route_back_policy` on a gate
+ * automatically gets route-back enforcement without code changes.
+ *
+ * @param flowId    e.g. "builder.build" — kitId is the prefix before the first ".".
+ * @param fromPhase Lifecycle phase leaving (e.g. "verification").
+ * @param toPhase   Lifecycle phase entering (e.g. "execution").
+ * @param repoRoot  Absolute path to the repository root (kits/ lives here).
+ * @returns RouteBackPolicy when the transition is a declared route-back, null otherwise.
+ */
+export function resolveRouteBackPolicy(
+  flowId: string,
+  fromPhase: string,
+  toPhase: string,
+  repoRoot: string,
+): RouteBackPolicy | null {
+  if (!flowId || !fromPhase || !toPhase) return null;
+  const dotIdx = flowId.indexOf(".");
+  if (dotIdx < 1) return null;
+  const kitId = flowId.slice(0, dotIdx);
+  const flowName = flowId.slice(dotIdx + 1);
+  if (!kitId || !flowName) return null;
+
+  const flowFilePath = resolveFlowFilePath(kitId, flowName, flowId, repoRoot);
+  if (!flowFilePath) return null;
+
+  let flowDef: FlowDefinition;
+  try {
+    const raw = fs.readFileSync(flowFilePath, "utf8");
+    flowDef = JSON.parse(raw) as FlowDefinition;
+  } catch {
+    return null; // ENOENT, permission error, or parse error — fail-open
+  }
+
+  if (!flowDef || typeof flowDef !== "object") return null;
+  const phaseMap = flowDef.phase_map;
+  if (!phaseMap || typeof phaseMap !== "object" || Array.isArray(phaseMap)) return null;
+
+  const fromStep = phaseMap[fromPhase];
+  const toStep = phaseMap[toPhase];
+  if (!fromStep || !toStep) return null; // phases not in this flow
+
+  if (!flowDef.gates) return null;
+  for (const gate of Object.values(flowDef.gates)) {
+    if (!gate || gate.step !== fromStep) continue;
+    if (!gate.route_back_policy || !gate.on_route_back) return null;
+    // Check if toStep is a valid route-back target declared in on_route_back
+    const routeBackTargets = Object.values(gate.on_route_back);
+    if (!routeBackTargets.includes(toStep)) return null;
+    const maxAttempts =
+      typeof gate.route_back_policy.max_attempts === "number"
+        ? gate.route_back_policy.max_attempts
+        : 3;
+    return {
+      maxAttempts,
+      onExceeded: gate.route_back_policy.on_exceeded ?? "block",
+      fromStepId: fromStep,
+    };
+  }
+  return null;
+}

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

@@ -7,7 +7,7 @@ import { loadJson, readText, root, walkFiles, writeText } from "./common.js";
 type Agent = Record<string, unknown> & { name: string; prompt: string };
 const dist = process.env.FLOW_AGENTS_DIST_DIR ? path.resolve(process.env.FLOW_AGENTS_DIST_DIR) : path.join(root, "dist");
 const manifest = loadJson<Record<string, any>>(path.join(root, "packaging/manifest.json"));
-const packs = loadJson<Record<string, any>>(path.join(root, "packaging/packs.json"));
+const pkgVersion: string = (loadJson<Record<string, unknown>>(path.join(root, "package.json")) as Record<string, string>)["version"] ?? "0.0.0";
 const textExtensions = new Set([".css", ".html", ".js", ".json", ".md", ".sh", ".toml", ".txt", ".yaml", ".yml", ".ts"]);
 const dropDiagnostics: string[] = [];
 const printDiagnostics = !["0", "false", "no"].includes(String(process.env.FLOW_AGENTS_EXPORT_DIAGNOSTICS ?? "1").toLowerCase());
@@ -181,8 +181,9 @@ function generatedAgentsSummary(agents: Agent[]): string {
 function exportRootAgentsMd(label: string, agents: Agent[], taskDir: string): string {
   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: string, installHint: string): string {
-  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: string, installHint: string, extra = ""): string {
+  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: unknown): string[] {
@@ -255,8 +256,8 @@ function shellHook(command: string, timeout = 10, statusMessage?: string): Recor
 function claudeTelemetry(event: string): string {
   return `bash -lc 'root="\${CLAUDE_PROJECT_DIR:-$(pwd)}"; node "$root/scripts/hooks/claude-telemetry-hook.js" ${event} dev'`;
 }
-function claudePolicy(event: string, script: string): string {
-  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: string, script: string, envPrefix = ""): string {
+  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: string): string {
   return `root="\${CODEX_HOME:-}"; if [ -z "$root" ] || [ ! -f "$root/${scriptPath}" ]; then root=$(git rev-parse --show-toplevel 2>/dev/null || pwd); fi`;
@@ -265,17 +266,23 @@ function codexTelemetry(event: string): string {
   if (event === "PermissionRequest") 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: string): string {
-  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: string, envPrefix = ""): string {
+  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(): string {
   const hooks: Record<string, Array<Record<string, unknown>>> = {};
   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"\'' },
@@ -289,8 +296,10 @@ function exportCodexHooks(): string {
   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`;
 }
 
@@ -310,19 +319,22 @@ function copySharedContent(targetRoot: string, targetName: string, token: string
   }
   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: string, defaultDestDisplay: string, token?: string, destFallbackShell?: string): string {
+function installScript(label: string, defaultDestDisplay: string, token?: string, destFallbackShell?: string, mergeConfig?: { configRelPath: string; managedConfigRelPath: string; runtime: string; version: string }, stampConfig?: { runtime: string; version: string }): string {
   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: Agent[]): void {
@@ -332,7 +344,7 @@ function buildBase(agents: Agent[]): void {
   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);
 }
 
@@ -344,7 +356,7 @@ function buildKiro(agents: Agent[]): void {
   for (const spec of 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: Agent[]): void {
@@ -359,7 +371,7 @@ function buildClaudeCode(agents: Agent[]): void {
   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: Agent[]): void {
@@ -378,8 +390,8 @@ function buildCodex(agents: Agent[]): void {
     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: Agent): string {
@@ -515,6 +527,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');
@@ -560,7 +573,7 @@ function buildOpencode(agents: Agent[]): void {
   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(): string {
@@ -648,6 +661,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) => {
@@ -670,7 +684,7 @@ function buildPi(agents: Agent[]): void {
   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: Agent[]): Record<string, unknown> {
@@ -680,7 +694,6 @@ function buildCatalog(agents: Agent[]): Record<string, unknown> {
     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<Record<string, unknown>>(kitsCatalog).kits ?? [] : [],
   };
 }

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

@@ -11,19 +11,20 @@ const dirDescriptions: Record<string, string> = {
   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"],
 ];
@@ -142,18 +143,6 @@ function powers(): string[][] {
   return fs.readdirSync(dir).sort().flatMap((name) => exists(path.join(dir, name, "POWER.md")) ? [[name, rel(path.join(dir, name, "POWER.md"))]] : []);
 }
 
-function packs(): string[][] {
-  const data = loadJson<{ packs?: Array<Record<string, unknown>> }>(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: boolean): string[] {
   if (!includeRuntime) {
     return [
@@ -193,9 +182,6 @@ function render(includeRuntime: boolean): string {
     "## 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.",