@kontourai/flow-agents 0.1.1 → 0.1.2

package/.github/workflows/publish-npm.yml

@@ -57,7 +57,7 @@ jobs:
       - name: Set up Node.js
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
-          node-version: "22"
+          node-version: "24"
           registry-url: "https://registry.npmjs.org"
 
       - name: Install dependencies

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.1.2
+
+- Source validation resolves the Flow CLI at `dist/cli.js` (with a
+  `src/cli.js` fallback), and the source-and-static CI lane installs
+  `@kontourai/flow` so kit Flow Definitions are validated by the real
+  Flow CLI.
+- The publish workflow builds the bundle explicitly before `npm publish`.
+- Docs routing between the System Guidebook and the Workflow Usage Guide;
+  duplicated development walkthrough removed.
+- README and Pages home advertise the npm install with the version badge;
+  pre-release caveats removed; Kontour family table links product pages
+  and gains a Survey row.
+- Fixes phantom skill references, a stale pack list, and path accuracy in
+  the docs.
+
 ## 0.1.1
 
 ### Documentation And Site

package/README.md

@@ -4,6 +4,7 @@
 
 **The discipline of Kontour Flow, inside the agent tools you already use.**
 
+[![npm version](https://img.shields.io/npm/v/%40kontourai%2Fflow-agents)](https://www.npmjs.com/package/@kontourai/flow-agents)
 [![CI](https://github.com/kontourai/flow-agents/actions/workflows/ci.yml/badge.svg)](https://github.com/kontourai/flow-agents/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 [![Node >= 22](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](package.json)
@@ -42,13 +43,7 @@ npx @kontourai/flow-agents init --dest /path/to/workspace --telemetry-sink local
 npx @kontourai/flow-agents init --runtime codex --dest /path/to/workspace --activate-kits --yes
 ```
 
-Until the first npm release lands, the same commands work from a checkout:
-
-```bash
-git clone https://github.com/kontourai/flow-agents.git
-cd flow-agents && npm install && npm run build
-node build/src/cli.js init --dest /path/to/workspace
-```
+Working from a checkout (for contributors) is the same flow: `npm install && npm run build`, then `node build/src/cli.js init --dest /path/to/workspace`.
 
 The installer copies the bundled agents, skills, context, scripts, evals, Flow Kit assets, and the Flow Agents-owned `console.telemetry.json` descriptor into the target workspace. Telemetry writes to local files by default; optional sinks mirror it to a local, hosted, or self-hosted Kontour Console (`--telemetry-sink local-kontour-console | kontour-hosted-console | user-hosted-console --console-url …`).
 
@@ -86,9 +81,10 @@ Kontour AI shows the work behind AI. Each product stands alone; together they co
 
 | Product | Owns |
 | --- | --- |
-| **[Surface](https://github.com/kontourai/surface)** | Portable trust state: claims, evidence, policies, trust snapshots |
-| **[Flow](https://github.com/kontourai/flow)** | Process transparency: steps, gates, transitions, runs, exceptions, reports |
-| **[Veritas](https://github.com/kontourai/veritas)** | Code/change transparency: repo standards, merge readiness |
+| **[Survey](https://kontourai.io/survey)** | Producer evidence: source → extraction → candidate → review → claim |
+| **[Surface](https://kontourai.io/surface)** | Portable trust state: claims, evidence, policies, trust snapshots |
+| **[Flow](https://kontourai.io/flow)** | Process transparency: steps, gates, transitions, runs, exceptions, reports |
+| **[Veritas](https://kontourai.io/veritas)** | Code/change transparency: repo standards, merge readiness |
 | **Flow Agents** | Agent-facing distribution: skills, kits, runtime adapters, hooks, telemetry |
 
 Flow Agents owns the glue — discovery, just-in-time guidance, scoped delegation, Flow-backed state inside harnesses, evidence-backed completion, and feedback loops. It deliberately does not own the model, the runtime, the workflow engine, or repo governance. The [North Star](docs/north-star.md) records the direction and design principles.

package/build/src/cli/utterance-check.js

@@ -0,0 +1,172 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { flagBool, flagString, parseArgs } from "../lib/args.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function usage() {
+    console.error([
+        "usage: flow-agents utterance-check check [options]",
+        "",
+        "Check an agent utterance for evidence coverage using @kontourai/survey.",
+        "Requires @kontourai/survey to be installed in the target workspace.",
+        "",
+        "Options:",
+        "  --utterance TEXT      Utterance text to check (required unless --not-configured).",
+        "  --bundle-path FILE    Trust bundle JSON file. Omit for an empty bundle (all unsupported).",
+        "  --agent-id ID         Agent identifier for provenance (default: flow-agents-utterance-check).",
+        "  --not-configured      Skip survey call; output not_configured without error.",
+        "  --strict              Exit non-zero when any badge is disputed, rejected, or unsupported.",
+        "  --help                Show this help.",
+    ].join("\n"));
+}
+function excerptText(text, maxLen = 200) {
+    const trimmed = text.trim().replace(/\s+/g, " ");
+    return trimmed.length > maxLen ? `${trimmed.slice(0, maxLen - 3)}...` : trimmed;
+}
+function badgeSummary(statements) {
+    if (statements.length === 0)
+        return "no factual statements extracted";
+    const counts = {};
+    for (const s of statements) {
+        counts[s.badge] = (counts[s.badge] ?? 0) + 1;
+    }
+    return Object.entries(counts)
+        .sort((a, b) => b[1] - a[1])
+        .map(([badge, n]) => `${badge}:${n}`)
+        .join(", ");
+}
+function hasConcerningBadge(badge) {
+    return badge === "disputed" || badge === "rejected" || badge === "unsupported";
+}
+async function loadSurvey() {
+    try {
+        const pkg = "@kontourai/survey";
+        // Dynamic import avoids a static dependency on @kontourai/survey —
+        // the same pattern survey/src/anthropic.ts uses for @anthropic-ai/sdk.
+        const mod = await Function("m", "return import(m)")(pkg);
+        return mod;
+    }
+    catch {
+        return undefined;
+    }
+}
+// ---------------------------------------------------------------------------
+// Core check logic
+// ---------------------------------------------------------------------------
+async function runCheck(argv) {
+    const { flags } = parseArgs(argv);
+    if (flagBool(flags, "help")) {
+        usage();
+        return 0;
+    }
+    const agentId = flagString(flags, "agent-id") ?? "flow-agents-utterance-check";
+    const notConfigured = flagBool(flags, "not-configured");
+    const strict = flagBool(flags, "strict");
+    if (notConfigured) {
+        const report = {
+            status: "not_configured",
+            agent_id: agentId,
+            utterance_excerpt: "",
+            statements: [],
+            summary: "@kontourai/survey is not configured for this workspace.",
+        };
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+        return 0;
+    }
+    const utterance = flagString(flags, "utterance");
+    if (!utterance) {
+        usage();
+        return 3;
+    }
+    const bundlePath = flagString(flags, "bundle-path");
+    let bundle = { claims: [] };
+    if (bundlePath) {
+        const resolved = path.resolve(bundlePath);
+        try {
+            const raw = fs.readFileSync(resolved, "utf8");
+            bundle = JSON.parse(raw);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[UtteranceCheck] could not read bundle from ${resolved}: ${msg}\n`);
+        }
+    }
+    const survey = await loadSurvey();
+    if (!survey) {
+        const report = {
+            status: "not_configured",
+            agent_id: agentId,
+            utterance_excerpt: excerptText(utterance),
+            statements: [],
+            summary: "@kontourai/survey is not installed. Install it or run with --not-configured.",
+        };
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+        process.stderr.write("[UtteranceCheck] not_configured: @kontourai/survey is not installed in this workspace.\n");
+        return 1;
+    }
+    const { surveyAgentUtterance, referenceUtteranceExtractor } = survey;
+    let trustReport;
+    try {
+        trustReport = await surveyAgentUtterance(utterance, referenceUtteranceExtractor, {
+            bundle,
+            agentId,
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        const report = {
+            status: "error",
+            agent_id: agentId,
+            utterance_excerpt: excerptText(utterance),
+            statements: [],
+            summary: `Survey call failed: ${msg}`,
+        };
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+        process.stderr.write(`[UtteranceCheck] survey call failed: ${msg}\n`);
+        return 1;
+    }
+    const statements = trustReport.statements.map((s) => ({
+        excerpt: s.excerpt,
+        badge: s.badge,
+        target: s.target,
+        span: s.span,
+    }));
+    const summary = badgeSummary(statements);
+    const report = {
+        status: "ok",
+        agent_id: agentId,
+        utterance_excerpt: excerptText(utterance),
+        statements,
+        summary,
+    };
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    const concerning = statements.filter((s) => hasConcerningBadge(s.badge));
+    if (concerning.length > 0) {
+        process.stderr.write(`[UtteranceCheck] ${concerning.length} statement(s) lack evidence coverage: ${summary}\n`);
+        for (const s of concerning.slice(0, 4)) {
+            process.stderr.write(`  - [${s.badge}] "${excerptText(s.excerpt, 100)}"\n`);
+        }
+    }
+    if (strict && concerning.length > 0)
+        return 2;
+    return 0;
+}
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+export async function main(argv = process.argv.slice(2)) {
+    const [subcommand, ...rest] = argv;
+    if (!subcommand || subcommand === "--help" || subcommand === "-h") {
+        usage();
+        return 0;
+    }
+    if (subcommand !== "check") {
+        console.error(`Unknown utterance-check subcommand: ${subcommand}`);
+        usage();
+        return 3;
+    }
+    return runCheck(rest);
+}
+if (import.meta.url === `file://${process.argv[1]}`)
+    process.exit(await main());

package/build/src/cli.js

@@ -19,6 +19,7 @@ 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";
 const availableCommands = new Map([
     ["build-bundles", () => buildBundles()],
     ["console-learning-projection", consoleLearningProjection],
@@ -32,6 +33,7 @@ const availableCommands = new Map([
     ["publish-change", publishChange],
     ["pull-work-provider", pullWorkProvider],
     ["runtime-adapter", runtimeAdapter],
+    ["utterance-check", utteranceCheck],
     ["telemetry-doctor", telemetryDoctor],
     ["usage-feedback", usageFeedback],
     ["veritas-governance", veritasGovernance],
@@ -56,6 +58,7 @@ const aliases = new Map([
     ["flow-agents-usage-feedback", "usage-feedback"],
     ["flow-agents-veritas-governance", "veritas-governance"],
     ["flow-agents-validate-hook-influence", "validate-hook-influence"],
+    ["flow-agents-utterance-check", "utterance-check"],
     ["flow-agents-validate-source", "validate-source"],
     ["flow-agents-workflow-artifact-cleanup-audit", "workflow-artifact-cleanup-audit"],
 ]);

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

@@ -68,6 +68,7 @@ const hookFilePolicies = new Map([
     ["scripts/hooks/report-only-guard.js", { category: "policy hook", requiredNeedles: ["Report-Only Guard Hook"] }],
     ["scripts/hooks/stop-format-typecheck.js", { category: "policy hook", requiredNeedles: ["Stop Hook", "typecheck"] }],
     ["scripts/hooks/stop-goal-fit.js", { category: "policy hook", requiredNeedles: ["Stop Hook", "Goal Fit"] }],
+    ["scripts/hooks/utterance-check.js", { category: "policy hook", requiredNeedles: ["Utterance Check Hook", "FLOW_AGENTS_UTTERANCE_CHECK_ENABLED"] }],
     ["scripts/hooks/workflow-steering.js", { category: "policy hook", requiredNeedles: ["Workflow Steering Hook"] }],
     ["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"] }],

package/docs/agent-system-guidebook.md

@@ -86,7 +86,7 @@ Flow Agents works like an agent workbench with seven cooperating layers:
 | Powers | Tool bundles and activation guidance for integrations. | `powers/` |
 | Agents | Specialist roles with scoped responsibilities. | `agents/`, `agent-cards/` |
 | Workflows | State, gates, handoffs, and task memory. | Kontour Flow concepts, `.flow-agents/`, `npm run workflow:sidecar --` |
-| Hooks | Just-in-time reminders or blockers from current workflow state. | `hooks/`, exported runtime configs |
+| Hooks | Just-in-time reminders or blockers from current workflow state. | `scripts/hooks/`, exported runtime configs |
 | Evidence | Tests, evals, telemetry, findings, and outcome records. | `evals/`, `.telemetry/`, sidecars |
 
 Each layer should stay small enough to explain independently. When the system feels complicated, the fix is usually to move behavior to the right layer, not to add more global prompt text.
@@ -252,13 +252,12 @@ The intended pattern is that every important workflow rule gets a test at the lo
 
 Packs keep the global surface understandable.
 
-`packaging/packs.json` groups capabilities into sets such as:
+`packaging/packs.json` groups capabilities into sets. Currently defined:
 
 - `core`
 - `development`
-- `knowledge`
-- `aws`
-- `experimental`
+
+Future packs (knowledge, AWS, experimental) are deferred until another producer proof shows repeated friction.
 
 All-pack installs remain the default today. `FLOW_AGENTS_PACKS` lets users opt into a smaller installed surface, and domain depth belongs in packs so a global setup can be narrowed without changing the source bundle.
 

package/docs/index.md

@@ -49,7 +49,6 @@ Flow Agents adds the operating layer around the model: skills choose the right w
 npx @kontourai/flow-agents init --dest /path/to/workspace
 ```
 
-Until the first npm release lands, the same command works from a checkout: clone the repo, `npm install && npm run build`, then `node build/src/cli.js init --dest /path/to/workspace`.
 
 Then ask for the workflow you want, in plain language:
 
@@ -122,7 +121,7 @@ Use fix-bug. Reproduce the problem, diagnose root cause, implement the fix, and
 
 ## The Kontour family
 
-Kontour AI shows the work behind AI. <a href="https://kontourai.github.io/flow/">Flow</a> proves why a process was allowed to advance. Veritas makes AI-authored code changes inspectable. Flow Agents packages those foundations into the agent tools you already use — so trustworthy autonomy doesn't require a perfect prompt, perfect memory, or a new runtime.
+Kontour AI shows the work behind AI. <a href="https://kontourai.github.io/flow/">Flow</a> proves why a process was allowed to advance. <a href="https://kontourai.io/veritas">Veritas</a> makes AI-authored code changes inspectable. <a href="https://kontourai.io/survey">Survey</a> and <a href="https://kontourai.io/surface">Surface</a> carry the evidence underneath. Flow Agents packages those foundations into the agent tools you already use — so trustworthy autonomy doesn't require a perfect prompt, perfect memory, or a new runtime.
 
 ## Why it matters
 

package/docs/north-star.md

@@ -180,7 +180,7 @@ Tasks:
 
 - Document the public layers: rules, skills, powers, agents, workflows, knowledge, and evidence. **Done:** see https://github.com/kontourai/flow-agents/blob/main/docs/operating-layers.md.
 - Mark which directories are canonical source, generated exports, runtime state, and optional integrations.
-- Decide which workflow skills are part of the core pack and which are optional domain packs. **Started:** `packaging/packs.json` defines core, development, knowledge, AWS, and experimental packs.
+- Decide which workflow skills are part of the core pack and which are optional domain packs. **Started:** `packaging/packs.json` defines core and development packs.
 - Add a standards register that lists each external standard, how Flow Agents uses it, and what Flow Agents-owned schemas still exist. **Done:** see https://github.com/kontourai/flow-agents/blob/main/docs/standards-register.md.
 - Add a "do not invent without checking standards" rule to contributor docs.
 

package/docs/repository-structure.md

@@ -96,7 +96,7 @@ specific row that matches the change.
 | Bundle/export shape | `packaging/`, `src/tools/build-universal-bundles.ts`, and source directories copied into bundles | `bash evals/static/test_universal_bundles.sh` |
 | Installer or local runtime setup behavior | `scripts/install-*.sh`, package bins, and generated bundle install scripts | `bash evals/integration/test_bundle_install.sh` |
 | Workflow artifact, sidecar, or provider contract | `context/contracts/`, `schemas/`, `src/cli/workflow-*`, and matching eval fixtures | `npm run workflow:validate-artifacts --` and workflow integration evals |
-| Flow Kit catalog or bundled kit content | `kits/`, Flow Definition files, and kit repository fixtures | `npm run flow-kit -- validate` or `bash evals/integration/test_flow_kit_repository.sh` |
+| Flow Kit catalog or bundled kit content | `kits/`, Flow Definition files, and kit repository fixtures | `npm run validate:source -- --kit <path>` or `bash evals/integration/test_flow_kit_repository.sh` |
 | Durable developer guidance | `docs/`; regenerate/check the context map when navigation or durable contracts change | `npm run context-map:check --` |
 | Eval scenario or fixture | `evals/static/`, `evals/integration/`, `evals/fixtures/`, or `evals/cases/` | The owning eval plus `bash evals/run.sh static` when contracts are touched |
 | Optional external integration configuration | `integrations/` or `veritas.claims.json`; keep local run output ignored | The integration-specific eval or documented dry run |

package/docs/skills-map.md

@@ -45,6 +45,9 @@ flowchart LR
   Learn -->|new work| Shape
 ```
 
+> `publish-change` is a CLI-driven workflow step, not a loadable skill.
+> `goal-fit` is a hook-enforced check, not a loadable skill.
+
 ## Current Shape
 
 The operating model now has first-class coverage from idea intake through trusted delivery:
@@ -76,7 +79,7 @@ This view shows how each phase is composed. The left rail is the durable phase s
     <div class="phase-step"><span>01</span><strong>Discovery & shaping</strong></div>
     <div class="phase-lanes">
       <section class="phase-lane phase-lane--primary"><h3>Primary</h3><p><code>builder-shape</code> <code>idea-to-backlog</code></p></section>
-      <section class="phase-lane"><h3>Support</h3><p><code>knowledge-search</code> <code>search-first</code> <code>explore</code> <code>crowdsource</code> <code>frontend-design</code> <code>github-cli</code> <code>knowledge-capture</code></p></section>
+      <section class="phase-lane"><h3>Support</h3><p><code>search-first</code> <code>explore</code> <code>frontend-design</code> <code>github-cli</code> <code>knowledge-capture</code></p></section>
       <section class="phase-lane"><h3>Nested sections / future primitives</h3><p>intake/dedupe, separate ideas, thinnest meaningful slice, opportunity review, explore options, <code>shape-work</code>, prioritize work, sync executable backlog</p></section>
       <section class="phase-lane phase-lane--gate"><h3>Gate & artifact</h3><p>Idea, slice, shape, and backlog gates. Writes shaped briefs and GitHub issue links in <code>.flow-agents/&lt;slug&gt;/</code>.</p></section>
     </div>
@@ -112,7 +115,7 @@ This view shows how each phase is composed. The left rail is the durable phase s
     <div class="phase-step"><span>05</span><strong>Learning & improvement</strong></div>
     <div class="phase-lanes">
       <section class="phase-lane phase-lane--primary"><h3>Primary</h3><p><code>learning-review</code></p></section>
-      <section class="phase-lane"><h3>Support</h3><p><code>knowledge-capture</code> <code>observe</code> <code>idea-to-backlog</code> <code>eval-rebuild</code></p></section>
+      <section class="phase-lane"><h3>Support</h3><p><code>knowledge-capture</code> <code>idea-to-backlog</code> <code>eval-rebuild</code></p></section>
       <section class="phase-lane"><h3>Nested sections / future primitives</h3><p>facts vs interpretation, follow-up routing, docs promotion review, knowledge updates, eval updates, skill/backlog improvements</p></section>
       <section class="phase-lane phase-lane--gate"><h3>Gate & artifact</h3><p>Learning gate. Writes outcomes, gaps, docs promotion state, follow-ups, knowledge updates, and verdict.</p></section>
     </div>
@@ -121,11 +124,11 @@ This view shows how each phase is composed. The left rail is the durable phase s
 
 | Phase | Primary workflow skill | Supporting skills | Nested sections / future primitive candidates |
 | --- | --- | --- | --- |
-| Idea discovery and shaping | `builder-shape`, `idea-to-backlog` | `knowledge-search`, `search-first`, `explore`, `crowdsource`, `frontend-design`, `github-cli`, `knowledge-capture` | intake/dedupe, separate ideas, thinnest meaningful slice, opportunity review, explore options, shape work, prioritize work, sync executable backlog |
+| Idea discovery and shaping | `builder-shape`, `idea-to-backlog` | `search-first`, `explore`, `frontend-design`, `github-cli`, `knowledge-capture` | intake/dedupe, separate ideas, thinnest meaningful slice, opportunity review, explore options, shape work, prioritize work, sync executable backlog |
 | Backlog pickup | `pull-work` | `github-cli` | board snapshot, WIP check, grouping/dependency check, Probe decision, worktree decision, handoff |
 | Execution planning and build | `design-probe`, `pickup-probe`, `plan-work`, `execute-plan`, `review-work`, `verify-work` | `feedback-loop`, `browser-test`, `deliver`, `fix-bug`, `tdd-workflow` | Probe notes, Builder Kit Probe record, Definition Of Done, execution plan, parallel waves, implementation session state, critique report, verification report, Goal Fit Gate |
 | Evidence and release confidence | `evidence-gate`, `release-readiness` | `github-cli`, `eval-rebuild` | criteria-to-evidence map, CI confidence, scope/integrity check, publish-change, rollback review, observability review, final acceptance docs, post-deploy plan |
-| Learning and improvement | `learning-review` | `knowledge-capture`, `observe`, `idea-to-backlog`, `eval-rebuild` | facts vs interpretation, docs promotion review, follow-up routing, knowledge updates, eval/skill/backlog improvements |
+| Learning and improvement | `learning-review` | `knowledge-capture`, `idea-to-backlog`, `eval-rebuild` | facts vs interpretation, docs promotion review, follow-up routing, knowledge updates, eval/skill/backlog improvements |
 
 The highest-leverage future extractions are likely `shape-work`, `test-map`, `scope-and-integrity-check`, and `remediate-ci`. They are still nested because their behavior is present, but not yet large enough to need separate activation contracts.
 
@@ -190,6 +193,9 @@ flowchart LR
   Learning -->|systemic change| Eval[eval-rebuild / backlog / skill update]
 ```
 
+> `publish-change` is a CLI-driven workflow step, not a loadable skill.
+> `goal-fit` is a hook-enforced check, not a loadable skill.
+
 ## Eval Coverage
 
 Workflow evals are layered to match this map:

package/docs/survey-utterance-check.md

@@ -0,0 +1,191 @@
+---
+title: Survey Utterance Check Integration
+---
+
+# Survey Utterance Check Integration
+
+Flow Agents can optionally check agent utterances for evidence coverage using `@kontourai/survey`. This integration is disabled by default and intentionally optional — ordinary Flow Agents workflows do not require Survey.
+
+The guiding rule mirrors the Veritas boundary: Flow Agents owns the hook wiring and badge guidance format; Survey owns the extraction, claim resolution, and trust report semantics.
+
+## Background: ADR 0003 §9
+
+ADR 0003 §9 designates agent-utterance extraction as a **Survey producer profile** — Survey pointed at agent prose instead of web sources. Each factual statement in agent output is extracted as a candidate claim and run through Survey's Inquiry pipeline. Flow Agents supplies the enforcement point (hooks) that ADR 0003 calls out. This integration is step 6 of the ADR sequencing and depends on the Inquiry pipeline already existing in Survey.
+
+## User-Facing Story
+
+```text
+Agent: "The test coverage for auth-service is 92%. All critical paths have been verified."
+
+Flow Agents (hook active):
+1. Captures the agent's response text from the PostToolUse event.
+2. Invokes the utterance-check CLI adapter with the response text.
+3. @kontourai/survey extracts factual statements: coverage:92%, paths:verified.
+4. Survey resolves each statement against the configured trust bundle.
+5. Statements without matching claims resolve as "unsupported".
+6. Flow Agents injects badge guidance into the agent context:
+   UTTERANCE CHECK: 2 statement(s) lack evidence coverage.
+   - [unsupported] "test coverage for auth-service is 92%"
+   - [unsupported] "All critical paths have been verified"
+```
+
+The agent sees honest gap disclosure rather than silent pass-through.
+
+## Ownership Split
+
+| Area | Flow Agents Owns | Survey Owns |
+| --- | --- | --- |
+| Hook wiring | PostToolUse/Stop hook, badge guidance format, enable/disable flags | None |
+| Extraction | Invoking the CLI adapter | Statement extraction, extractor interface |
+| Resolution | Passing the trust bundle path | Inquiry pipeline, claim resolution |
+| Output | Guidance text injected into agent context | UtteranceTrustReport with per-statement badges |
+| Packaging | Optional hook activation, CLI adapter | @kontourai/survey npm package |
+
+Flow Agents does not own trust claim models, inquiry semantics, or extractor implementations. Survey's `referenceUtteranceExtractor` is the default extractor; production use should inject `createAnthropicUtteranceExtractor` from `@kontourai/survey/anthropic` for model-backed extraction.
+
+## Enabling the Hook
+
+The hook is disabled by default. Set environment variables before starting the agent session:
+
+```bash
+export FLOW_AGENTS_UTTERANCE_CHECK_ENABLED=true
+
+# Optional: path to a trust bundle JSON file for claim resolution
+export FLOW_AGENTS_UTTERANCE_CHECK_BUNDLE_PATH=/path/to/trust-bundle.json
+
+# Optional: agent identifier for provenance
+export FLOW_AGENTS_UTTERANCE_CHECK_AGENT_ID=my-codex-session
+
+# Optional: strict mode — blocks Stop when concerning badges are present
+export FLOW_AGENTS_UTTERANCE_CHECK_STRICT=true
+```
+
+The hook runs through the standard `run-hook.js` runner and respects `SA_DISABLED_HOOKS` and `SA_HOOK_PROFILE`.
+
+## CLI Adapter Contract
+
+The utterance check CLI is available as:
+
+```bash
+node build/src/cli.js utterance-check check \
+  --utterance "The coverage is 92% and all tests pass." \
+  --bundle-path .surface/trust-bundle.json \
+  --agent-id my-session
+```
+
+Options:
+
+```
+  --utterance TEXT      Utterance text to check (required unless --not-configured).
+  --bundle-path FILE    Trust bundle JSON file. Omit for an empty bundle (all unsupported).
+  --agent-id ID         Agent identifier for provenance (default: flow-agents-utterance-check).
+  --not-configured      Skip survey call; output not_configured without error.
+  --strict              Exit non-zero when any badge is disputed, rejected, or unsupported.
+  --help                Show this help.
+```
+
+The CLI outputs a JSON report to stdout:
+
+```json
+{
+  "status": "ok",
+  "agent_id": "my-session",
+  "utterance_excerpt": "The coverage is 92% and all tests pass.",
+  "statements": [
+    {
+      "excerpt": "coverage is 92%",
+      "badge": "unsupported",
+      "target": {
+        "subjectType": "unknown",
+        "subjectId": "coverage",
+        "fieldOrBehavior": "is"
+      }
+    }
+  ],
+  "summary": "unsupported:2"
+}
+```
+
+Badge values:
+
+| Badge | Meaning |
+| --- | --- |
+| `verified` | Matched a claim with verified status |
+| `assumed` | Matched a claim with assumed status |
+| `stale` | Matched a claim that is stale |
+| `disputed` | Matched a claim with conflicting evidence |
+| `rejected` | Matched a claim that was rejected |
+| `unsupported` | No matching claim in the trust bundle |
+
+Exit codes: `0` = pass, `1` = survey unavailable, `2` = strict mode with concerning badges, `3` = usage error.
+
+When `@kontourai/survey` is not installed, the CLI outputs `status: "not_configured"` and exits `1`. The hook treats `not_configured` as a silent pass-through.
+
+## Registering the Hook
+
+Add the utterance check to a Claude Code session via `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node scripts/hooks/claude-hook-adapter.js PostToolUse post:utterance-check utterance-check.js standard,strict"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Or run the hook directly (Kiro/Codex convention, exit 2 blocks):
+
+```bash
+node scripts/hooks/run-hook.js post:utterance-check utterance-check.js standard,strict
+```
+
+## Installing @kontourai/survey
+
+The CLI adapter uses a dynamic import so flow-agents itself does not list `@kontourai/survey` as a dependency. Install it in the target workspace:
+
+```bash
+npm install @kontourai/survey
+```
+
+For model-backed extraction (production-quality, requires `@anthropic-ai/sdk`):
+
+```bash
+npm install @kontourai/survey @anthropic-ai/sdk
+```
+
+Then inject the Anthropic extractor by extending the CLI adapter or creating a wrapper script that calls `surveyAgentUtterance` with `createAnthropicUtteranceExtractor`.
+
+## Non-Goals
+
+- Do not make `@kontourai/survey` a mandatory dependency of flow-agents.
+- Do not copy Survey's extraction or inquiry schemas into flow-agents.
+- Do not auto-register the hook in the default pack; it is opt-in only.
+- Do not make the hook blocking without explicit `--strict` / `FLOW_AGENTS_UTTERANCE_CHECK_STRICT=true`.
+- Do not silently decide anything. The hook injects guidance; the agent decides next steps.
+
+## Current Integration Shape
+
+The integration delivers:
+
+1. `src/cli/utterance-check.ts` — TypeScript CLI adapter. Accepts utterance text, optional bundle path, and agent ID. Dynamically imports `@kontourai/survey`. Outputs a JSON badge report to stdout and human-readable guidance to stderr. Mirrors the `veritas-governance` adapter pattern.
+
+2. `scripts/hooks/utterance-check.js` — CJS hook script. PostToolUse/Stop, non-blocking by default. Reads agent output text from the hook event, invokes the CLI adapter when `FLOW_AGENTS_UTTERANCE_CHECK_ENABLED=true`, and injects badge guidance into the agent context. Always fails open.
+
+The forward path (out of scope for this slice):
+
+- Register the hook in a dedicated `survey` pack for opt-in activation.
+- Support injecting the Anthropic extractor via `FLOW_AGENTS_UTTERANCE_CHECK_EXTRACTOR=anthropic`.
+- Surface badge results as evidence sidecar entries (linking utterance coverage to workflow evidence).
+- Auto-propose new claim mappings from unsupported statements via the Survey mapping proposer.
+
+Survey source and API details: https://github.com/kontourai/survey

package/docs/workflow-usage-guide.md

@@ -378,7 +378,7 @@ Completion gate:
 
 The validator and stop hook enforce this shape for terminal workflows. If a delivery is terminal and neither the Markdown artifact nor `state.json.artifact_paths` points at durable docs, validation should fail unless the artifact records an explicit no-docs decision.
 
-## 10. Capture Learning
+## 11. Capture Learning
 
 Use `learning-review` after release, failed gates, incidents, repeated friction, or workflow gaps.