@kontourai/flow-agents 0.1.2 → 0.3.0

package/packaging/conformance/fixtures/quality-gate--allow-no-path.json

@@ -0,0 +1,17 @@
+{
+  "description": "quality-gate is non-blocking (exit 0) when no file path is in tool_input",
+  "policy_class": "quality-gate",
+  "canonical_event": "postToolUse",
+  "conformance_level": "L2",
+  "hook_id": "quality-gate",
+  "hook_script": "quality-gate.js",
+  "payload": {
+    "hook_event_name": "PostToolUse",
+    "tool_name": "write",
+    "tool_input": {}
+  },
+  "expected": {
+    "exit_code": 0,
+    "stdout_echoes_input": true
+  }
+}

package/packaging/conformance/fixtures/quality-gate--allow-nonexistent-file.json

@@ -0,0 +1,19 @@
+{
+  "description": "quality-gate is non-blocking (exit 0) even for a .ts file that does not exist",
+  "policy_class": "quality-gate",
+  "canonical_event": "postToolUse",
+  "conformance_level": "L2",
+  "hook_id": "quality-gate",
+  "hook_script": "quality-gate.js",
+  "payload": {
+    "hook_event_name": "PostToolUse",
+    "tool_name": "write",
+    "tool_input": {
+      "path": "/tmp/nonexistent-file-for-conformance-test.ts"
+    }
+  },
+  "expected": {
+    "exit_code": 0,
+    "stdout_echoes_input": true
+  }
+}

package/packaging/conformance/fixtures/stop-goal-fit--allow-clean-cwd.json

@@ -0,0 +1,17 @@
+{
+  "description": "stop-goal-fit passes (exit 0, no warnings) when cwd has no .flow-agents workflow artifacts",
+  "policy_class": "stop-goal-fit",
+  "canonical_event": "stop",
+  "conformance_level": "L1",
+  "hook_id": "stop-goal-fit",
+  "hook_script": "stop-goal-fit.js",
+  "payload": {
+    "hook_event_name": "Stop",
+    "cwd": "/tmp"
+  },
+  "expected": {
+    "exit_code": 0,
+    "stdout_echoes_input": true,
+    "stderr_is_empty": true
+  }
+}

package/packaging/conformance/fixtures/stop-goal-fit--block-strict-mode.json

@@ -0,0 +1,23 @@
+{
+  "description": "stop-goal-fit blocks (exit 2) in FLOW_AGENTS_GOAL_FIT_STRICT=true mode for an active delivery artifact missing DOD and Goal Fit Gate",
+  "policy_class": "stop-goal-fit",
+  "canonical_event": "stop",
+  "conformance_level": "L2",
+  "hook_id": "stop-goal-fit",
+  "hook_script": "stop-goal-fit.js",
+  "payload": {
+    "hook_event_name": "Stop",
+    "cwd": "__TEMP_WORKSPACE__"
+  },
+  "workspace_setup": {
+    "AGENTS.md": "# Test Repo\n",
+    ".flow-agents/my-task/my-task--deliver.md": "# My Task\n\nbranch: main\nstatus: executing\ntype: deliver\n\n## Plan\n\nWork TBD.\n"
+  },
+  "env": {
+    "FLOW_AGENTS_GOAL_FIT_STRICT": "true"
+  },
+  "expected": {
+    "exit_code": 2,
+    "stderr_contains": ["status:executing"]
+  }
+}

package/packaging/conformance/fixtures/stop-goal-fit--warn-active-delivery.json

@@ -0,0 +1,21 @@
+{
+  "description": "stop-goal-fit warns (exit 0, stderr has warnings) for an active delivery artifact missing DOD and Goal Fit Gate",
+  "policy_class": "stop-goal-fit",
+  "canonical_event": "stop",
+  "conformance_level": "L1",
+  "hook_id": "stop-goal-fit",
+  "hook_script": "stop-goal-fit.js",
+  "payload": {
+    "hook_event_name": "Stop",
+    "cwd": "__TEMP_WORKSPACE__"
+  },
+  "workspace_setup": {
+    "AGENTS.md": "# Test Repo\n",
+    ".flow-agents/my-task/my-task--deliver.md": "# My Task\n\nbranch: main\nstatus: executing\ntype: deliver\n\n## Plan\n\nWork TBD.\n"
+  },
+  "expected": {
+    "exit_code": 0,
+    "stdout_echoes_input": true,
+    "stderr_contains": ["status:executing", "Definition Of Done", "Goal Fit Gate"]
+  }
+}

package/packaging/conformance/fixtures/workflow-steering--allow-no-state.json

@@ -0,0 +1,16 @@
+{
+  "description": "workflow-steering passes through (exit 0, stdout echoes input) when cwd has no active workflow state",
+  "policy_class": "workflow-steering",
+  "canonical_event": "userPromptSubmit",
+  "conformance_level": "L1",
+  "hook_id": "workflow-steering",
+  "hook_script": "workflow-steering.js",
+  "payload": {
+    "hook_event_name": "UserPromptSubmit",
+    "cwd": "/tmp"
+  },
+  "expected": {
+    "exit_code": 0,
+    "stdout_echoes_input": true
+  }
+}

package/packaging/conformance/fixtures/workflow-steering--inject-active-state.json

@@ -0,0 +1,29 @@
+{
+  "description": "workflow-steering injects STATE hint (exit 0, stdout contains STATE:) for blocked workflow state at UserPromptSubmit",
+  "policy_class": "workflow-steering",
+  "canonical_event": "userPromptSubmit",
+  "conformance_level": "L1",
+  "hook_id": "workflow-steering",
+  "hook_script": "workflow-steering.js",
+  "payload": {
+    "hook_event_name": "UserPromptSubmit",
+    "cwd": "__TEMP_WORKSPACE__"
+  },
+  "workspace_setup": {
+    "AGENTS.md": "# Test Repo\n",
+    ".flow-agents/my-task/state.json": {
+      "task_slug": "my-task",
+      "status": "blocked",
+      "phase": "execute",
+      "next_action": {
+        "summary": "Needs decision from user",
+        "status": "needs_user",
+        "target_phase": "verify"
+      }
+    }
+  },
+  "expected": {
+    "exit_code": 0,
+    "stdout_contains": ["STATE:", "my-task", "blocked"]
+  }
+}

package/packaging/conformance/fixtures/workflow-steering--inject-subagent-steering.json

@@ -0,0 +1,25 @@
+{
+  "description": "workflow-steering injects EXECUTION COMPLETE hint after tool-worker subagent call completes",
+  "policy_class": "workflow-steering",
+  "canonical_event": "postToolUse",
+  "conformance_level": "L1",
+  "hook_id": "workflow-steering",
+  "hook_script": "workflow-steering.js",
+  "payload": {
+    "hook_event_name": "PostToolUse",
+    "tool_name": "mcp",
+    "tool_input": {
+      "command": "InvokeSubagents",
+      "content": {
+        "subagents": [
+          { "agent_name": "tool-worker" }
+        ]
+      }
+    },
+    "cwd": "/tmp"
+  },
+  "expected": {
+    "exit_code": 0,
+    "stdout_contains": ["EXECUTION COMPLETE"]
+  }
+}

package/packaging/conformance/package.json

@@ -0,0 +1,4 @@
+{
+  "description": "Flow Agents conformance kit — standalone runner with no npm deps",
+  "type": "commonjs"
+}

package/packaging/conformance/run-conformance.js

@@ -0,0 +1,322 @@
+#!/usr/bin/env node
+/**
+ * run-conformance.js — Flow Agents policy engine conformance test runner.
+ *
+ * Usage:
+ *   node packaging/conformance/run-conformance.js --self
+ *   node packaging/conformance/run-conformance.js --adapter-cmd "node my-adapter.js"
+ *   node packaging/conformance/run-conformance.js --adapter-cmd "..." --level L1
+ *
+ * Options:
+ *   --self              Run against the canonical engine (must reach L2).
+ *   --adapter-cmd CMD   Shell command to test. Receives JSON payload on stdin,
+ *                       must produce exit code 0 (allow) or 2 (block).
+ *   --level L0|L1|L2    Minimum level to enforce. Default: L2 for --self, L0 otherwise.
+ *   --fixtures DIR      Override fixture directory (default: same dir as this script).
+ *   --verbose           Print per-fixture payloads.
+ *
+ * No external npm dependencies — pure Node.js stdlib.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { spawnSync } = require('child_process');
+
+const CONFORMANCE_DIR = __dirname;
+const FIXTURES_DIR = path.join(CONFORMANCE_DIR, 'fixtures');
+const HOOKS_DIR = path.resolve(CONFORMANCE_DIR, '../../scripts/hooks');
+const RUN_HOOK = path.join(HOOKS_DIR, 'run-hook.js');
+
+// Conformance levels — ordered so that L2 implies L1 implies L0.
+const LEVEL_ORDER = ['L0', 'L1', 'L2'];
+const LEVEL_POLICY_CLASSES = {
+  L0: new Set([]),               // L0: telemetry only — no policy fixtures required
+  L1: new Set(['workflow-steering', 'stop-goal-fit']),
+  L2: new Set(['workflow-steering', 'stop-goal-fit', 'quality-gate', 'config-protection']),
+};
+
+// -----------------------------------------------------------------------
+// CLI parsing
+// -----------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const args = { self: false, adapterCmd: null, level: null, fixturesDir: FIXTURES_DIR, verbose: false };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--self') { args.self = true; }
+    else if (arg === '--adapter-cmd') { args.adapterCmd = argv[++i]; }
+    else if (arg === '--level') { args.level = argv[++i]; }
+    else if (arg === '--fixtures') { args.fixturesDir = argv[++i]; }
+    else if (arg === '--verbose') { args.verbose = true; }
+  }
+  return args;
+}
+
+// -----------------------------------------------------------------------
+// Workspace setup helpers
+// -----------------------------------------------------------------------
+
+function createTempWorkspace(setup) {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'fa-conformance-'));
+  for (const [relPath, content] of Object.entries(setup)) {
+    const fullPath = path.join(tmpDir, relPath);
+    fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+    const text = typeof content === 'string' ? content : JSON.stringify(content, null, 2);
+    fs.writeFileSync(fullPath, text, 'utf8');
+  }
+  return tmpDir;
+}
+
+function cleanupWorkspace(tmpDir) {
+  try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch { /* ignore */ }
+}
+
+// -----------------------------------------------------------------------
+// Fixture loading
+// -----------------------------------------------------------------------
+
+function loadFixtures(fixturesDir) {
+  if (!fs.existsSync(fixturesDir)) {
+    throw new Error(`Fixtures directory not found: ${fixturesDir}`);
+  }
+  return fs.readdirSync(fixturesDir)
+    .filter(name => name.endsWith('.json'))
+    .sort()
+    .map(name => {
+      const filePath = path.join(fixturesDir, name);
+      try {
+        const data = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+        return { name, ...data };
+      } catch (e) {
+        throw new Error(`Failed to load fixture ${name}: ${e.message}`);
+      }
+    });
+}
+
+// -----------------------------------------------------------------------
+// Self-invocation (canonical engine)
+// -----------------------------------------------------------------------
+
+function invokeSelf(fixture, tmpWorkspace) {
+  const payload = JSON.parse(JSON.stringify(fixture.payload));
+  if (tmpWorkspace && payload.cwd === '__TEMP_WORKSPACE__') {
+    payload.cwd = tmpWorkspace;
+  }
+  const input = JSON.stringify(payload);
+  const env = Object.assign({}, process.env, fixture.env || {});
+  const result = spawnSync(
+    process.execPath,
+    [RUN_HOOK, fixture.hook_id, fixture.hook_script],
+    { input, encoding: 'utf8', env, timeout: 15000, cwd: process.cwd() }
+  );
+  return {
+    exit_code: result.status,
+    stdout: result.stdout || '',
+    stderr: result.stderr || '',
+    input,
+  };
+}
+
+// -----------------------------------------------------------------------
+// Adapter invocation (third-party command)
+// -----------------------------------------------------------------------
+
+function invokeAdapter(adapterCmd, fixture, tmpWorkspace) {
+  const payload = JSON.parse(JSON.stringify(fixture.payload));
+  if (tmpWorkspace && payload.cwd === '__TEMP_WORKSPACE__') {
+    payload.cwd = tmpWorkspace;
+  }
+  const input = JSON.stringify(payload);
+  const env = Object.assign({}, process.env, fixture.env || {});
+  const result = spawnSync('sh', ['-c', adapterCmd], {
+    input,
+    encoding: 'utf8',
+    env,
+    timeout: 15000,
+    cwd: process.cwd(),
+  });
+  return {
+    exit_code: result.status,
+    stdout: result.stdout || '',
+    stderr: result.stderr || '',
+    input,
+  };
+}
+
+// -----------------------------------------------------------------------
+// Assertion evaluation
+// -----------------------------------------------------------------------
+
+function evaluate(fixture, actual) {
+  const expected = fixture.expected;
+  const failures = [];
+
+  if (typeof expected.exit_code === 'number' && actual.exit_code !== expected.exit_code) {
+    failures.push(`exit_code: expected ${expected.exit_code}, got ${actual.exit_code}`);
+  }
+
+  if (expected.stdout_echoes_input) {
+    // stdout should start with (or equal) the input JSON
+    const normalized = actual.stdout.trim();
+    const inputNorm = actual.input.trim();
+    if (!normalized.startsWith(inputNorm) && !normalized.includes(inputNorm.slice(0, 40))) {
+      failures.push(`stdout_echoes_input: stdout did not echo input payload`);
+    }
+  }
+
+  if (expected.stdout_is_empty && actual.stdout.trim()) {
+    failures.push(`stdout_is_empty: expected empty stdout, got: ${actual.stdout.slice(0, 60)}`);
+  }
+
+  if (expected.stderr_is_empty && actual.stderr.trim()) {
+    failures.push(`stderr_is_empty: expected empty stderr, got: ${actual.stderr.slice(0, 60)}`);
+  }
+
+  if (Array.isArray(expected.stdout_contains)) {
+    for (const needle of expected.stdout_contains) {
+      if (!actual.stdout.includes(needle)) {
+        failures.push(`stdout_contains: missing "${needle}"`);
+      }
+    }
+  }
+
+  if (Array.isArray(expected.stderr_contains)) {
+    for (const needle of expected.stderr_contains) {
+      if (!actual.stderr.includes(needle)) {
+        failures.push(`stderr_contains: missing "${needle}"`);
+      }
+    }
+  }
+
+  return failures;
+}
+
+// -----------------------------------------------------------------------
+// Main runner
+// -----------------------------------------------------------------------
+
+function run(argv) {
+  const args = parseArgs(argv);
+
+  if (!args.self && !args.adapterCmd) {
+    console.error('Usage: node run-conformance.js --self');
+    console.error('       node run-conformance.js --adapter-cmd "<command>"');
+    process.exit(2);
+  }
+
+  const targetLevel = args.level || (args.self ? 'L2' : 'L0');
+  if (!LEVEL_ORDER.includes(targetLevel)) {
+    console.error(`Unknown conformance level: ${targetLevel}. Use L0, L1, or L2.`);
+    process.exit(2);
+  }
+
+  // Load fixtures
+  const fixtures = loadFixtures(args.fixturesDir);
+  console.log(`\nFlow Agents Conformance Test Runner`);
+  console.log(`====================================`);
+  console.log(`Mode:    ${args.self ? 'self (canonical engine)' : `adapter: ${args.adapterCmd}`}`);
+  console.log(`Target:  ${targetLevel}`);
+  console.log(`Fixtures: ${fixtures.length} loaded from ${args.fixturesDir}`);
+  console.log('');
+
+  const results = [];
+
+  for (const fixture of fixtures) {
+    let tmpWorkspace = null;
+
+    // Set up workspace if fixture needs one
+    if (fixture.workspace_setup) {
+      tmpWorkspace = createTempWorkspace(fixture.workspace_setup);
+    }
+
+    let actual;
+    try {
+      actual = args.self
+        ? invokeSelf(fixture, tmpWorkspace)
+        : invokeAdapter(args.adapterCmd, fixture, tmpWorkspace);
+    } finally {
+      if (tmpWorkspace) cleanupWorkspace(tmpWorkspace);
+    }
+
+    const failures = evaluate(fixture, actual);
+    const passed = failures.length === 0;
+
+    results.push({ fixture, actual, failures, passed });
+
+    const icon = passed ? '  PASS' : '  FAIL';
+    console.log(`${icon}  [${fixture.conformance_level}] ${fixture.name}`);
+    if (!passed || args.verbose) {
+      console.log(`       ${fixture.description}`);
+      if (!passed) {
+        for (const f of failures) {
+          console.log(`       * ${f}`);
+        }
+      }
+      if (args.verbose) {
+        console.log(`       exit_code: ${actual.exit_code}`);
+        if (actual.stderr.trim()) console.log(`       stderr: ${actual.stderr.trim().slice(0, 120)}`);
+      }
+    }
+  }
+
+  console.log('');
+  console.log('--- Per-level verdict ---');
+
+  const levelPassed = {};
+  for (const level of LEVEL_ORDER) {
+    // Fixtures at this level or below
+    const levelFixtures = results.filter(r => {
+      const fLevel = r.fixture.conformance_level;
+      return LEVEL_ORDER.indexOf(fLevel) <= LEVEL_ORDER.indexOf(level);
+    });
+
+    const requiredPolicies = LEVEL_POLICY_CLASSES[level];
+    // For L0 there are no policy fixtures required — only check that no fixture at L0 level fails
+    const requiredResults = level === 'L0'
+      ? levelFixtures.filter(r => r.fixture.conformance_level === 'L0')
+      : levelFixtures.filter(r => requiredPolicies.has(r.fixture.policy_class) || r.fixture.conformance_level === 'L0');
+
+    const allPass = requiredResults.every(r => r.passed);
+    levelPassed[level] = allPass;
+
+    const passCount = requiredResults.filter(r => r.passed).length;
+    const icon = allPass ? 'PASS' : 'FAIL';
+    console.log(`  ${icon}  ${level}  (${passCount}/${requiredResults.length} required fixtures pass)`);
+
+    if (!allPass) {
+      const failing = requiredResults.filter(r => !r.passed);
+      for (const r of failing.slice(0, 5)) {
+        console.log(`         - ${r.fixture.name}: ${r.failures[0]}`);
+      }
+    }
+  }
+
+  console.log('');
+
+  // Determine highest satisfied level
+  let highestLevel = null;
+  for (const level of LEVEL_ORDER) {
+    if (levelPassed[level]) highestLevel = level;
+    else break;
+  }
+
+  const totalPass = results.filter(r => r.passed).length;
+  const totalFail = results.filter(r => !r.passed).length;
+  console.log(`Total: ${totalPass} passed, ${totalFail} failed`);
+  console.log(`Highest conformance level achieved: ${highestLevel || 'none'}`);
+
+  // Exit code: 0 if target level reached, 1 otherwise
+  const targetReached = highestLevel !== null && LEVEL_ORDER.indexOf(highestLevel) >= LEVEL_ORDER.indexOf(targetLevel);
+  if (targetReached) {
+    console.log(`\nSELF-TEST VERDICT: ${targetLevel} PASS — adapter satisfies ${targetLevel} conformance.`);
+    process.exit(0);
+  } else {
+    console.log(`\nSELF-TEST VERDICT: ${targetLevel} FAIL — adapter does not satisfy ${targetLevel} conformance.`);
+    process.exit(1);
+  }
+}
+
+run(process.argv.slice(2));

package/packaging/manifest.json

@@ -168,6 +168,65 @@
         "from": "write files",
         "to": "write files"
       }
+    ],
+    "opencode": [
+      {
+        "from": "Claude Code",
+        "to": "opencode"
+      },
+      {
+        "from": "todo tool",
+        "to": "todo tool"
+      },
+      {
+        "from": "delegate to a specialist agent",
+        "to": "delegate to a subagent"
+      },
+      {
+        "from": "run shell commands",
+        "to": "run shell commands"
+      },
+      {
+        "from": "read files",
+        "to": "read files"
+      },
+      {
+        "from": "write files",
+        "to": "write files"
+      }
+    ],
+    "pi": [
+      {
+        "from": "Claude Code",
+        "to": "pi"
+      },
+      {
+        "from": "todo tool",
+        "to": "todo tool"
+      },
+      {
+        "from": "delegate to a specialist agent",
+        "to": "delegate to a subagent"
+      },
+      {
+        "from": "run shell commands",
+        "to": "run shell commands"
+      },
+      {
+        "from": "read files",
+        "to": "read files"
+      },
+      {
+        "from": "write files",
+        "to": "write files"
+      }
     ]
+  },
+  "opencode": {
+    "task_dir": ".flow-agents",
+    "default_agent_mode": "subagent"
+  },
+  "pi": {
+    "task_dir": ".flow-agents"
   }
 }

package/schemas/flow-agents-settings.schema.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flow-agents.dev/schemas/flow-agents-settings.schema.json",
+  "title": "Flow Agents Settings",
+  "description": "Per-repo policy configuration for Flow Agents features.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "schema_version": { "const": "1.0" },
+    "utteranceCheck": { "$ref": "#/$defs/utteranceCheckPolicy" }
+  },
+  "$defs": {
+    "utteranceCheckPolicy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["enabled"],
+      "description": "Policy for utterance evidence coverage checking via @kontourai/survey.",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Whether utterance checking is active for this repo. Default: false."
+        },
+        "mode": {
+          "enum": ["report", "strict"],
+          "description": "report = badges only, never blocks. strict = exit 2 on disputed/rejected/unsupported (routes hook back). Default when enabled: report."
+        },
+        "extractor": {
+          "enum": ["reference", "anthropic"],
+          "description": "Extractor used to split utterances into factual statements. reference = pattern-based (no API key needed). anthropic = model-backed via @kontourai/survey/anthropic (requires ANTHROPIC_API_KEY). Default: reference."
+        },
+        "bundlePath": {
+          "type": "string",
+          "description": "Path to a trust bundle JSON file for claim resolution. Relative paths are resolved from the repo root. Omit to use an empty bundle (all statements resolve as unsupported)."
+        },
+        "model": {
+          "type": "string",
+          "description": "Model identifier for anthropic extractor (e.g. claude-haiku-4-5). Only used when extractor is anthropic."
+        },
+        "agentId": {
+          "type": "string",
+          "description": "Agent identifier for provenance in the trust report. Default: flow-agents-hook."
+        }
+      }
+    }
+  }
+}

package/scripts/README.md

@@ -54,6 +54,10 @@ renamed, or changes category, update the table and the validator together.
 | `run-hook.js` | hook runner | `evals/integration/test_hook_category_behaviors.sh`, `evals/integration/test_goal_fit_hook.sh`, `evals/integration/test_workflow_steering_hook.sh` | Applies profile/disable flags, traversal checks, and hook execution. |
 | `config-protection.js` | policy hook | `evals/integration/test_hook_category_behaviors.sh` | Blocks unsafe runtime config edits. |
 | `governance-audit.sh` | policy hook | `evals/integration/test_hook_category_behaviors.sh`, `evals/integration/test_telemetry.sh` | Emits governance/Veritas audit context when configured. |
+| `opencode-hook-adapter.js` | runtime adapter | `evals/integration/test_bundle_install.sh` | Translates opencode plugin events into the shared hook runner contract. |
+| `opencode-telemetry-hook.js` | telemetry shim | `evals/integration/test_bundle_install.sh` | Captures opencode plugin telemetry and fails open. |
+| `pi-hook-adapter.js` | runtime adapter | `evals/integration/test_bundle_install.sh` | Translates pi extension events into the shared hook runner contract. |
+| `pi-telemetry-hook.js` | telemetry shim | `evals/integration/test_bundle_install.sh` | Captures pi extension telemetry and fails open. |
 | `post-edit-accumulator.js` | policy hook | `evals/integration/test_hook_category_behaviors.sh` | Tracks edited files across a turn for later quality hooks. |
 | `quality-gate.js` | policy hook | `evals/integration/test_hook_category_behaviors.sh` | Runs configured quality checks as hook policy. |
 | `report-only-guard.js` | policy hook | `evals/integration/test_hook_category_behaviors.sh` | Protects report-only specialist roles from production edits. |

package/scripts/dogfood.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * flow-agents dogfood wrapper.
+ *
+ * Invokes the dogfood subcommand from init.ts to write hook-wiring artifacts
+ * for the specified runtime into the current or target directory.
+ *
+ * Usage:
+ *   node scripts/dogfood.js --runtime claude-code [--dest PATH]
+ *   npm run dogfood -- --runtime claude-code [--dest PATH]
+ *
+ * This script is intentionally thin: it imports the built mainDogfood export
+ * from build/src/cli/init.js so all logic stays in one place and cannot drift.
+ * Run `npm run build` or `npm run build:bundles` first if the build is stale.
+ */
+import("../build/src/cli/init.js").then(({ mainDogfood }) => mainDogfood(process.argv.slice(2)).then((rc) => process.exit(rc)));