@kontourai/flow-agents 0.1.2 → 0.2.0

package/integrations/strands-ts/test/test-telemetry.ts

@@ -0,0 +1,226 @@
+/**
+ * test-telemetry.ts — Tests for telemetry module.
+ *
+ * Covers: event mapping, JSONL emission shape, normalizeToolName.
+ * Uses node:test only — no additional dependencies.
+ */
+
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { TelemetrySink, STRANDS_TO_CANONICAL, normalizeToolName, SCHEMA_VERSION } from "../src/telemetry.js";
+
+// ---------------------------------------------------------------------------
+// STRANDS_TO_CANONICAL mapping table
+// ---------------------------------------------------------------------------
+
+describe("STRANDS_TO_CANONICAL mapping", () => {
+  test("contains all expected Strands TS event class names", () => {
+    const expected = new Set([
+      "BeforeInvocationEvent",
+      "AfterInvocationEvent",
+      "BeforeToolCallEvent",
+      "AfterToolCallEvent",
+      "AgentInitializedEvent",
+      "AfterModelCallEvent",
+      "MessageAddedEvent",
+    ]);
+    assert.deepStrictEqual(new Set(Object.keys(STRANDS_TO_CANONICAL)), expected);
+  });
+
+  test("BeforeInvocationEvent → userPromptSubmit", () => {
+    assert.strictEqual(STRANDS_TO_CANONICAL.BeforeInvocationEvent, "userPromptSubmit");
+  });
+
+  test("AfterInvocationEvent → stop", () => {
+    assert.strictEqual(STRANDS_TO_CANONICAL.AfterInvocationEvent, "stop");
+  });
+
+  test("BeforeToolCallEvent → preToolUse", () => {
+    assert.strictEqual(STRANDS_TO_CANONICAL.BeforeToolCallEvent, "preToolUse");
+  });
+
+  test("AfterToolCallEvent → postToolUse", () => {
+    assert.strictEqual(STRANDS_TO_CANONICAL.AfterToolCallEvent, "postToolUse");
+  });
+
+  test("AgentInitializedEvent → agentSpawn", () => {
+    assert.strictEqual(STRANDS_TO_CANONICAL.AgentInitializedEvent, "agentSpawn");
+  });
+
+  test("all values are non-empty strings", () => {
+    for (const [key, value] of Object.entries(STRANDS_TO_CANONICAL)) {
+      assert.strictEqual(typeof value, "string", `${key} value must be a string`);
+      assert.ok(value.length > 0, `${key} value must be non-empty`);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// normalizeToolName
+// ---------------------------------------------------------------------------
+
+describe("normalizeToolName", () => {
+  test("bash → execute_bash", () => {
+    assert.strictEqual(normalizeToolName("bash"), "execute_bash");
+  });
+
+  test("edit → fs_write", () => {
+    assert.strictEqual(normalizeToolName("edit"), "fs_write");
+  });
+
+  test("write → fs_write", () => {
+    assert.strictEqual(normalizeToolName("write"), "fs_write");
+  });
+
+  test("read → fs_read", () => {
+    assert.strictEqual(normalizeToolName("read"), "fs_read");
+  });
+
+  test("task → use_subagent", () => {
+    assert.strictEqual(normalizeToolName("task"), "use_subagent");
+  });
+
+  test("unknown passthrough", () => {
+    assert.strictEqual(normalizeToolName("my_custom_tool"), "my_custom_tool");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// TelemetrySink emission shape
+// ---------------------------------------------------------------------------
+
+function makeTempSink(agentName = "test-agent", runtime = "strands-test"): { sink: TelemetrySink; dir: string } {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "fa-ts-telemetry-"));
+  const sink = new TelemetrySink({ sinkPath: dir, agentName, runtime });
+  return { sink, dir };
+}
+
+function readEvents(dir: string): Record<string, unknown>[] {
+  const logFile = path.join(dir, "full.jsonl");
+  if (!fs.existsSync(logFile)) return [];
+  const lines = fs.readFileSync(logFile, "utf8").trim().split("\n");
+  return lines.filter((l) => l.trim()).map((l) => JSON.parse(l) as Record<string, unknown>);
+}
+
+describe("TelemetrySink emission shape", () => {
+  test("session start event has correct schema_version and event_type", () => {
+    const { sink, dir } = makeTempSink();
+    const evt = sink.emitSessionStart();
+    assert.strictEqual(evt.schema_version, SCHEMA_VERSION);
+    assert.strictEqual(evt.event_type, "session.start");
+    // cleanup
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("session start written to JSONL", () => {
+    const { sink, dir } = makeTempSink();
+    sink.emitSessionStart();
+    const events = readEvents(dir);
+    assert.strictEqual(events.length, 1);
+    assert.strictEqual((events[0] as Record<string, unknown>).event_type, "session.start");
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("event has required top-level fields (timestamp, session_id, event_id)", () => {
+    const { sink, dir } = makeTempSink();
+    const evt = sink.emitSessionStart();
+    assert.ok("timestamp" in evt, "missing timestamp");
+    assert.ok("session_id" in evt, "missing session_id");
+    assert.ok("event_id" in evt, "missing event_id");
+    assert.ok("agent" in evt, "missing agent");
+    assert.ok("hook" in evt, "missing hook");
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("agent sub-object has name and runtime", () => {
+    const { sink, dir } = makeTempSink("my-agent", "strands-ts");
+    const evt = sink.emitSessionStart();
+    const agent = evt.agent as Record<string, unknown>;
+    assert.strictEqual(agent.name, "my-agent");
+    assert.strictEqual(agent.runtime, "strands-ts");
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("hook sub-object has event_name and source fields", () => {
+    const { sink, dir } = makeTempSink();
+    const evt = sink.emitSessionStart();
+    const hook = evt.hook as Record<string, unknown>;
+    assert.ok("event_name" in hook, "hook.event_name missing");
+    assert.ok("source" in hook, "hook.source missing");
+    assert.strictEqual(hook.source, "strands-ts");
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("tool invoke event has correct event_type and tool fields", () => {
+    const { sink, dir } = makeTempSink();
+    const evt = sink.emitToolInvoke("edit", { path: "foo.py" });
+    assert.strictEqual(evt.event_type, "tool.invoke");
+    const tool = evt.tool as Record<string, unknown>;
+    assert.strictEqual(tool.name, "edit");
+    assert.strictEqual(tool.normalized_name, "fs_write");
+    assert.deepStrictEqual(tool.input, { path: "foo.py" });
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("tool result event has correct event_type", () => {
+    const { sink, dir } = makeTempSink();
+    const evt = sink.emitToolResult("read", "file contents");
+    assert.strictEqual(evt.event_type, "tool.result");
+    const tool = evt.tool as Record<string, unknown>;
+    assert.strictEqual(tool.name, "read");
+    assert.strictEqual(tool.normalized_name, "fs_read");
+    assert.strictEqual(tool.output, "file contents");
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("session end has event_type session.end", () => {
+    const { sink, dir } = makeTempSink();
+    const evt = sink.emitSessionEnd(1000);
+    assert.strictEqual(evt.event_type, "session.end");
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("user prompt submit has event_type turn.user", () => {
+    const { sink, dir } = makeTempSink();
+    const evt = sink.emitUserPromptSubmit();
+    assert.strictEqual(evt.event_type, "turn.user");
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("multiple events share the same session_id", () => {
+    const { sink, dir } = makeTempSink();
+    sink.emitSessionStart();
+    sink.emitToolInvoke("read", {});
+    sink.emitSessionEnd();
+    const events = readEvents(dir);
+    const sessionIds = new Set(events.map((e) => (e as Record<string, unknown>).session_id));
+    assert.strictEqual(sessionIds.size, 1, "All events must share one session_id");
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("each JSONL line is valid JSON", () => {
+    const { sink, dir } = makeTempSink();
+    sink.emitSessionStart();
+    sink.emitToolInvoke("bash", { command: "ls" });
+    sink.emitSessionEnd(500);
+    const logFile = path.join(dir, "full.jsonl");
+    const lines = fs.readFileSync(logFile, "utf8").split("\n");
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      const parsed = JSON.parse(line); // throws on invalid JSON
+      assert.strictEqual(typeof parsed, "object");
+    }
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("sinkPath directory creates full.jsonl", () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "fa-ts-sink-dir-"));
+    const sink = new TelemetrySink({ sinkPath: dir });
+    sink.emitSessionStart();
+    assert.ok(fs.existsSync(path.join(dir, "full.jsonl")));
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+});

package/integrations/strands-ts/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "ignoreDeprecations": "6.0",
+    "lib": ["ES2022"],
+    "types": ["node"],
+    "rootDir": ".",
+    "outDir": "dist",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*.ts", "test/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/package.json

@@ -1,15 +1,19 @@
 {
   "name": "@kontourai/flow-agents",
-  "version": "0.1.2",
-  "description": "Flow Agents — a Kontour product that applies Flow and Veritas discipline inside the agent tools you already use: Claude Code, Codex, Kiro, and GitHub Actions.",
+  "version": "0.2.0",
+  "description": "Flow Agents — a Kontour product that applies Flow and Veritas discipline as a portable process layer inside the agent tools you already use: Claude Code, Codex, Kiro, opencode, pi, and GitHub Actions — with framework adapters (AWS Strands preview) on the same policy-engine contract.",
   "keywords": [
     "agents",
     "ai-agents",
     "workflow",
     "skills",
+    "hooks",
     "claude-code",
     "codex",
     "kiro",
+    "opencode",
+    "pi",
+    "strands",
     "evidence",
     "process-transparency"
   ],
@@ -108,6 +112,7 @@
     "validate:hook-influence": "npm run build --silent && node build/src/cli.js validate-hook-influence",
     "workflow-artifact-cleanup-audit": "npm run build --silent && node build/src/cli.js workflow-artifact-cleanup-audit",
     "fixture:retirement-audit": "npm run build --silent && node build/src/cli.js fixture-retirement-audit",
+    "dogfood": "npm run build --silent && node scripts/dogfood.js",
     "setup:repo-hooks": "bash scripts/setup-repo-hooks.sh",
     "validate:repo-hooks": "bash evals/static/test_repo_hooks.sh",
     "eval": "bash evals/run.sh",

package/packaging/conformance/README.md

@@ -0,0 +1,142 @@
+# Flow Agents Conformance Kit
+
+The conformance kit lets third-party adapter authors self-certify their implementation against the Flow Agents policy engine contract.
+
+---
+
+## What is the conformance kit?
+
+Flow Agents ships four canonical policy classes (config-protection, quality-gate, stop-goal-fit, workflow-steering) that adapters must invoke via subprocess or native import. The conformance kit provides:
+
+1. **Golden fixtures** (`fixtures/`) — payload→expected-decision JSON pairs, one per policy class × canonical event × case, extracted from real engine behavior.
+2. **Conformance runner** (`run-conformance.js`) — a standalone Node.js script (no npm deps) that pipes each fixture through an adapter command and reports per-level verdict.
+
+---
+
+## Conformance levels
+
+| Level | What is required |
+|-------|-----------------|
+| **L0** | No policy fixtures required. Adapter wires telemetry only. |
+| **L1** | Workflow steering (`userPromptSubmit`) and stop-goal-fit (`stop`) in warning mode must pass. |
+| **L2** | All L1 requirements plus config-protection (`preToolUse`, blocking) and quality-gate (`postToolUse`, non-blocking). |
+
+These levels match the definitions in `docs/spec/runtime-hook-surface.md` §4.
+
+---
+
+## Quick start
+
+```bash
+# Self-test the canonical engine (must report L2):
+node packaging/conformance/run-conformance.js --self
+
+# Test a third-party adapter:
+node packaging/conformance/run-conformance.js \
+  --adapter-cmd "node /path/to/your-adapter.js" \
+  --level L2
+
+# Test at L1 only:
+node packaging/conformance/run-conformance.js \
+  --adapter-cmd "node /path/to/your-adapter.js" \
+  --level L1
+```
+
+---
+
+## Adapter contract
+
+Your adapter command:
+- Receives a canonical JSON payload on **stdin** (one JSON object, see §Payload schema).
+- Writes the input JSON (or augmented form) to **stdout** on allow.
+- Writes nothing meaningful to stdout on block (or empty/echoed input).
+- Exits **0** to allow, **2** to block, any other code for error (treated as allow / fail-open).
+
+The runner invokes your command exactly once per fixture via `sh -c "<your-cmd>"`.
+
+---
+
+## Payload schema (contract_version "1.0")
+
+All payloads are JSON objects with:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `hook_event_name` | string | Canonical event name: `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop` |
+| `tool_name` | string? | Tool name (for tool-call events) |
+| `tool_input` | object? | Tool input (for tool-call events); contains `path` or `file_path` for write tools |
+| `cwd` | string? | Current working directory of the agent session |
+
+Full payload/decision schema is documented in `docs/spec/runtime-hook-surface.md` §8 (Engine Contract).
+
+---
+
+## Fixture inventory
+
+| Fixture | Policy class | Event | Level | What it tests |
+|---------|-------------|-------|-------|---------------|
+| `config-protection--block-eslintrc.json` | config-protection | preToolUse | L2 | Block write to `.eslintrc.json` |
+| `config-protection--block-biome.json` | config-protection | preToolUse | L2 | Block edit to `biome.json` via `file_path` |
+| `config-protection--allow-safe-file.json` | config-protection | preToolUse | L2 | Allow write to `src/main.ts` |
+| `config-protection--allow-no-path.json` | config-protection | preToolUse | L2 | Allow when no path in tool_input |
+| `quality-gate--allow-nonexistent-file.json` | quality-gate | postToolUse | L2 | Non-blocking for missing .ts file |
+| `quality-gate--allow-no-path.json` | quality-gate | postToolUse | L2 | Non-blocking when no path in tool_input |
+| `stop-goal-fit--allow-clean-cwd.json` | stop-goal-fit | stop | L1 | No warnings in clean workspace |
+| `stop-goal-fit--warn-active-delivery.json` | stop-goal-fit | stop | L1 | Warnings for active delivery without DOD/GoalFit |
+| `stop-goal-fit--block-strict-mode.json` | stop-goal-fit | stop | L2 | Exit 2 with FLOW_AGENTS_GOAL_FIT_STRICT=true |
+| `workflow-steering--allow-no-state.json` | workflow-steering | userPromptSubmit | L1 | Pass-through when no active workflow state |
+| `workflow-steering--inject-active-state.json` | workflow-steering | userPromptSubmit | L1 | Injects STATE hint for blocked task |
+| `workflow-steering--inject-subagent-steering.json` | workflow-steering | postToolUse | L1 | Injects EXECUTION COMPLETE hint after tool-worker |
+
+Fixtures with `workspace_setup` create a temporary directory with the listed files before invoking the adapter, and clean it up afterward. The `cwd` field in those payloads is replaced with the temp directory path at runtime.
+
+---
+
+## How to declare conformance
+
+After running the conformance kit, include a conformance declaration in your adapter documentation:
+
+```yaml
+conformance_level: L2          # or L0 / L1
+engine_contract_version: "1.0"
+runner_version: "run-conformance.js"
+test_date: 2026-06-11
+verdict: PASS
+fixture_count: 12
+fixtures_passed: 12
+gaps: []                       # List any declared gaps here
+```
+
+If any fixtures fail, list them under `gaps` with a description of the degradation behavior.
+
+---
+
+## Declaring gaps
+
+If your adapter legitimately cannot satisfy a fixture (e.g., the host runtime has no blocking `preToolUse` equivalent), declare it explicitly:
+
+```yaml
+gaps:
+  - fixture: config-protection--block-eslintrc.json
+    reason: "Host does not support blocking tool calls; config-protection fails open"
+    degradation: "Agent may modify linter configs without interception"
+    workaround: "Run config-protection as a linting step in CI instead"
+```
+
+Declared gaps do not prevent reaching a lower conformance level.
+
+---
+
+## CLI reference
+
+```
+node packaging/conformance/run-conformance.js [options]
+
+  --self              Run against the canonical engine (target L2)
+  --adapter-cmd CMD   Shell command to pipe fixtures to (adapter under test)
+  --level L0|L1|L2    Minimum conformance level to enforce (default: L2 for --self, L0 for --adapter-cmd)
+  --fixtures DIR      Override fixture directory (default: packaging/conformance/fixtures/)
+  --verbose           Print fixture payloads and full output in per-fixture results
+```
+
+Exit codes: `0` = target level reached, `1` = target level not reached, `2` = usage error.

package/packaging/conformance/fixtures/config-protection--allow-no-path.json

@@ -0,0 +1,18 @@
+{
+  "description": "config-protection allows when no file path is present in tool_input",
+  "policy_class": "config-protection",
+  "canonical_event": "preToolUse",
+  "conformance_level": "L2",
+  "hook_id": "config-protection",
+  "hook_script": "config-protection.js",
+  "payload": {
+    "hook_event_name": "PreToolUse",
+    "tool_name": "write",
+    "tool_input": {}
+  },
+  "expected": {
+    "exit_code": 0,
+    "stderr_is_empty": true,
+    "stdout_echoes_input": true
+  }
+}

package/packaging/conformance/fixtures/config-protection--allow-safe-file.json

@@ -0,0 +1,20 @@
+{
+  "description": "config-protection allows a write to a regular source file",
+  "policy_class": "config-protection",
+  "canonical_event": "preToolUse",
+  "conformance_level": "L2",
+  "hook_id": "config-protection",
+  "hook_script": "config-protection.js",
+  "payload": {
+    "hook_event_name": "PreToolUse",
+    "tool_name": "write",
+    "tool_input": {
+      "path": "/repo/src/main.ts"
+    }
+  },
+  "expected": {
+    "exit_code": 0,
+    "stderr_is_empty": true,
+    "stdout_echoes_input": true
+  }
+}

package/packaging/conformance/fixtures/config-protection--block-biome.json

@@ -0,0 +1,20 @@
+{
+  "description": "config-protection blocks an edit to biome.json (protected Biome config)",
+  "policy_class": "config-protection",
+  "canonical_event": "preToolUse",
+  "conformance_level": "L2",
+  "hook_id": "config-protection",
+  "hook_script": "config-protection.js",
+  "payload": {
+    "hook_event_name": "PreToolUse",
+    "tool_name": "edit",
+    "tool_input": {
+      "file_path": "biome.json"
+    }
+  },
+  "expected": {
+    "exit_code": 2,
+    "stderr_contains": ["BLOCKED", "biome.json"],
+    "stdout_is_empty": true
+  }
+}

package/packaging/conformance/fixtures/config-protection--block-eslintrc.json

@@ -0,0 +1,20 @@
+{
+  "description": "config-protection blocks a write to .eslintrc.json (protected ESLint config)",
+  "policy_class": "config-protection",
+  "canonical_event": "preToolUse",
+  "conformance_level": "L2",
+  "hook_id": "config-protection",
+  "hook_script": "config-protection.js",
+  "payload": {
+    "hook_event_name": "PreToolUse",
+    "tool_name": "write",
+    "tool_input": {
+      "path": "/repo/.eslintrc.json"
+    }
+  },
+  "expected": {
+    "exit_code": 2,
+    "stderr_contains": ["BLOCKED"],
+    "stdout_is_empty": true
+  }
+}

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"]
+  }
+}