@kontourai/flow-agents 0.1.1 → 0.2.0

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

@@ -0,0 +1,236 @@
+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).",
+        "  --extractor NAME      Extractor to use: 'reference' (default, pattern-based) or 'anthropic'",
+        "                        (model-backed, requires ANTHROPIC_API_KEY and @kontourai/survey/anthropic).",
+        "  --model MODEL         Model for the anthropic extractor (e.g. claude-haiku-4-5).",
+        "  --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;
+    }
+}
+/**
+ * Dynamically import @kontourai/survey/anthropic and create the Anthropic extractor.
+ * Fails open with a clear not_configured message when the key or peer dep is missing.
+ */
+async function loadAnthropicExtractor(model) {
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+    if (!apiKey) {
+        return {
+            notConfigured: true,
+            reason: "anthropic extractor requires ANTHROPIC_API_KEY to be set. " +
+                "Set the environment variable or switch extractor to 'reference'.",
+        };
+    }
+    try {
+        const pkg = "@kontourai/survey/anthropic";
+        const mod = await Function("m", "return import(m)")(pkg);
+        if (typeof mod.createAnthropicUtteranceExtractor !== "function") {
+            return {
+                notConfigured: true,
+                reason: "@kontourai/survey/anthropic does not export createAnthropicUtteranceExtractor. " +
+                    "Update @kontourai/survey to a version that supports the anthropic extractor.",
+            };
+        }
+        const opts = { apiKey };
+        if (model)
+            opts.model = model;
+        return mod.createAnthropicUtteranceExtractor(opts);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            notConfigured: true,
+            reason: `@kontourai/survey/anthropic is not available: ${msg}. ` +
+                "Install @kontourai/survey with the anthropic subpath export, or switch extractor to 'reference'.",
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// 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");
+    const extractorName = flagString(flags, "extractor") ?? "reference";
+    const model = flagString(flags, "model");
+    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;
+    // Resolve which extractor to use.
+    let extractor;
+    if (extractorName === "anthropic") {
+        const anthropicResult = await loadAnthropicExtractor(model);
+        if ("notConfigured" in anthropicResult) {
+            // Fail open: emit not_configured with a clear reason rather than erroring.
+            const report = {
+                status: "not_configured",
+                agent_id: agentId,
+                utterance_excerpt: excerptText(utterance),
+                statements: [],
+                summary: anthropicResult.reason,
+            };
+            process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+            process.stderr.write(`[UtteranceCheck] not_configured: ${anthropicResult.reason}\n`);
+            return 0;
+        }
+        extractor = anthropicResult;
+    }
+    else {
+        extractor = referenceUtteranceExtractor;
+    }
+    let trustReport;
+    try {
+        trustReport = await surveyAgentUtterance(utterance, extractor, {
+            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/build-universal-bundles.js

@@ -361,6 +361,270 @@ function buildCodex(agents) {
     writeText(path.join(bundle, "install.sh"), installScript("Codex", "/path/to/workspace"));
     fs.chmodSync(path.join(bundle, "install.sh"), 0o755);
 }
+function exportOpencodeAgent(spec) {
+    // Determine agent mode: orchestrator-like agents -> primary, others -> subagent
+    const primaryAgents = new Set(["dev"]);
+    const mode = primaryAgents.has(spec.name) ? "primary" : "subagent";
+    const prompt = appendExportNote(sanitizeText(spec.prompt, "opencode", "<bundle-root>"), "Kiro hook wiring and JSON-only runtime fields were omitted. If this agent mentions Kiro-specific scheduler or hook behavior, treat that as optional operational guidance rather than a hard dependency.");
+    const lines = ["---"];
+    lines.push(`description: ${String(spec.description ?? "").trim()}`);
+    lines.push(`mode: ${mode}`);
+    lines.push(`model: ${mapped("claude_model_map", spec.model)}`);
+    lines.push("---");
+    lines.push("");
+    lines.push(prompt);
+    return lines.join("\n");
+}
+function exportOpencodePlugin() {
+    // Generate the Flow Agents opencode plugin.
+    // opencode plugins are auto-loaded from .opencode/plugins/*.js at startup.
+    //
+    // NOTE: opencode has no direct user-prompt-submit hook. For prompt-submit
+    // workflow steering, we wire the steering command behind session.created
+    // (for session-start steering context) and tool.execute.before (for
+    // policy). This is the closest reasonable approximation — documented here
+    // as an honest gap matching the codex live-hook-influence caveat pattern.
+    return `/**
+ * Flow Agents opencode plugin.
+ *
+ * Auto-loaded from .opencode/plugins/flow-agents.js at opencode startup.
+ * Delegates policy and telemetry decisions to shared scripts in scripts/hooks/
+ * using the same payload contract as the claude/codex adapters.
+ *
+ * EVENT MAPPING NOTE: opencode has no direct user-prompt-submit hook.
+ * Workflow steering (workflow-steering.js) is wired to session.created
+ * (session-start context) and tool.execute.before (per-tool policy).
+ * This approximates the UserPromptSubmit behavior in other runtimes but
+ * cannot intercept mid-session user messages before they are processed.
+ * This is an accepted gap documented here analogously to the codex
+ * live-hook-influence caveat.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { join, basename } from 'node:path';
+
+// opencode runs plugins inside its own compiled (Bun-based) binary, so
+// process.execPath points at opencode itself — spawning it with a script
+// path silently does nothing (caught by live acceptance smoke 2026-06-11).
+// Resolve a real node binary instead; fall back to PATH lookup.
+const NODE_BIN = basename(process.execPath).startsWith('node') ? process.execPath : 'node';
+
+export const FlowAgentsPlugin = async ({ project, client, $, directory, worktree }) => {
+  const root = directory || process.cwd();
+
+  // The hook scripts read the event payload from stdin; an empty stdin makes
+  // the telemetry pipeline silently skip the emit (fail-open), so every spawn
+  // must pass a payload (caught by live acceptance smoke 2026-06-11).
+  function hookPayload(eventName, detail) {
+    return JSON.stringify({ hook_event_name: eventName, cwd: root, ...(detail || {}) });
+  }
+
+  function runAdapter(adapterScript, eventName, detail, ...args) {
+    const adapterPath = join(root, 'scripts', 'hooks', adapterScript);
+    const result = spawnSync(NODE_BIN, [adapterPath, eventName, ...args], {
+      input: hookPayload(eventName, detail),
+      encoding: 'utf8',
+      cwd: root,
+      env: { ...process.env, FLOW_AGENTS_HOOK_RUNTIME: 'opencode' },
+      timeout: 30000,
+    });
+    try {
+      return JSON.parse(result.stdout || '{}');
+    } catch {
+      return { allow: true };
+    }
+  }
+
+  function runTelemetry(eventName, detail) {
+    const telemetryPath = join(root, 'scripts', 'hooks', 'opencode-telemetry-hook.js');
+    spawnSync(NODE_BIN, [telemetryPath, eventName, 'dev'], {
+      input: hookPayload(eventName, detail),
+      encoding: 'utf8',
+      cwd: root,
+      env: { ...process.env, FLOW_AGENTS_TELEMETRY_RUNTIME: 'opencode' },
+      timeout: 10000,
+    });
+  }
+
+  return {
+    'session.created': async (_input, _output) => {
+      runTelemetry('session.created');
+      // Wire workflow steering on session start for context injection
+      runAdapter('opencode-hook-adapter.js', 'session.created', null, 'workflow-steering', 'workflow-steering.js', 'default');
+    },
+    'tool.execute.before': async (input, output) => {
+      const detail = { tool: input && input.tool, args: output && output.args };
+      runTelemetry('tool.execute.before', detail);
+      const policyResult = runAdapter('opencode-hook-adapter.js', 'tool.execute.before', detail, 'config-protection', 'config-protection.js', 'default');
+      if (policyResult && policyResult.allow === false) {
+        throw new Error(policyResult.reason || 'Blocked by Flow Agents hook policy.');
+      }
+    },
+    'tool.execute.after': async (input, output) => {
+      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');
+    },
+    'session.idle': async (_input, _output) => {
+      runTelemetry('session.idle');
+      runAdapter('opencode-hook-adapter.js', 'session.idle', null, 'stop-goal-fit', 'stop-goal-fit.js', 'default');
+    },
+    'session.error': async (_input, _output) => {
+      runTelemetry('session.error');
+    },
+    'session.compacted': async (_input, _output) => {
+      runTelemetry('session.compacted');
+    },
+    'permission.asked': async (_input, _output) => {
+      runTelemetry('permission.asked');
+    },
+    'file.edited': async (_input, _output) => {
+      runTelemetry('file.edited');
+    },
+  };
+};
+`;
+}
+function exportOpencodeConfig() {
+    // opencode's config schema requires `instructions` to be an ARRAY of
+    // instruction file paths/globs (a bare string fails validation and aborts
+    // startup). AGENTS.md is loaded natively by opencode, so the config stays
+    // minimal rather than double-including it.
+    return `${JSON.stringify({
+        $schema: "https://opencode.ai/config.json",
+    }, null, 2)}\n`;
+}
+function buildOpencode(agents) {
+    const bundle = path.join(dist, "opencode");
+    resetDir(bundle);
+    copySharedContent(bundle, "opencode", "<bundle-root>");
+    writeText(path.join(bundle, manifest.opencode.task_dir, ".gitkeep"), "");
+    for (const spec of agents) {
+        writeText(path.join(bundle, ".opencode/agents", `${spec.name}.md`), exportOpencodeAgent(spec));
+    }
+    for (const skill of fs.readdirSync(path.join(root, "skills"))) {
+        const skillPath = path.join(root, "skills", skill, "SKILL.md");
+        if (fs.existsSync(skillPath))
+            writeText(path.join(bundle, ".opencode/skills", skill, "SKILL.md"), sanitizeText(readText(skillPath), "opencode", "<bundle-root>"));
+    }
+    writeText(path.join(bundle, ".opencode/plugins/flow-agents.js"), exportOpencodePlugin());
+    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"));
+    fs.chmodSync(path.join(bundle, "install.sh"), 0o755);
+}
+function exportPiExtension() {
+    // Generate the Flow Agents pi extension.
+    // pi extensions are auto-discovered from .pi/extensions/*.ts (needs project trust).
+    // pi has no named-subagent registry; agents are not exported. The extension
+    // provides workflow steering (via before_agent_start context injection),
+    // tool-call policy (via tool_call event), and telemetry delegation to shared scripts.
+    return `/**
+ * Flow Agents pi extension.
+ *
+ * Auto-discovered from .pi/extensions/flow-agents.ts at startup (needs project trust).
+ * Delegates policy and telemetry to shared scripts/hooks/ using spawnSync,
+ * mirroring the payload contract used by the claude/codex adapters.
+ *
+ * NOTE: pi has no named-subagent registry. Agents are not exported for pi.
+ * Rely on AGENTS.md + skills + this extension for workflow guidance.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { spawnSync } from "node:child_process";
+import { join, basename } from "node:path";
+
+// pi may run extensions under a non-node runtime (Bun), where process.execPath
+// is not a node binary and spawning it with a script path silently fails.
+// Same failure class the opencode live smoke caught on 2026-06-11.
+const NODE_BIN = basename(process.execPath).startsWith("node") ? process.execPath : "node";
+
+export default function (pi: ExtensionAPI) {
+  const root = process.cwd();
+
+  function runAdapter(adapterScript: string, eventName: string, hookId: string, relScript: string): { allow: boolean; context?: string; reason?: string } {
+    const adapterPath = join(root, "scripts", "hooks", adapterScript);
+    const payload = JSON.stringify({ hook_event_name: eventName, cwd: root });
+    const result = spawnSync(NODE_BIN, [adapterPath, eventName, hookId, relScript, "default"], {
+      input: payload,
+      encoding: "utf8",
+      cwd: root,
+      env: { ...process.env, FLOW_AGENTS_HOOK_RUNTIME: "pi" },
+      timeout: 30000,
+    });
+    try {
+      return JSON.parse(result.stdout || "{}") as { allow: boolean; context?: string; reason?: string };
+    } catch {
+      return { allow: true };
+    }
+  }
+
+  function runTelemetry(eventName: string): void {
+    const telemetryPath = join(root, "scripts", "hooks", "pi-telemetry-hook.js");
+    const payload = JSON.stringify({ hook_event_name: eventName, cwd: root });
+    spawnSync(NODE_BIN, [telemetryPath, eventName, "dev"], {
+      input: payload,
+      encoding: "utf8",
+      cwd: root,
+      env: { ...process.env, FLOW_AGENTS_TELEMETRY_RUNTIME: "pi" },
+      timeout: 10000,
+    });
+  }
+
+  pi.on("session_start", async (_event, _ctx) => {
+    runTelemetry("session_start");
+  });
+
+  pi.on("before_agent_start", async (event, _ctx) => {
+    runTelemetry("before_agent_start");
+    // Inject workflow steering context at agent start
+    const result = runAdapter("pi-hook-adapter.js", "before_agent_start", "workflow-steering", "workflow-steering.js");
+    if (result.context) {
+      return {
+        systemPrompt: event.systemPrompt + "\\n\\n" + result.context,
+      };
+    }
+  });
+
+  pi.on("tool_call", async (event, _ctx) => {
+    runTelemetry("tool_call");
+    const result = runAdapter("pi-hook-adapter.js", "tool_call", "config-protection", "config-protection.js");
+    if (result && result.allow === false) {
+      return { block: true, reason: result.reason || "Blocked by Flow Agents hook policy." };
+    }
+  });
+
+  pi.on("tool_result", async (_event, _ctx) => {
+    runTelemetry("tool_result");
+    runAdapter("pi-hook-adapter.js", "tool_result", "quality-gate", "quality-gate.js");
+  });
+
+  pi.on("session_shutdown", async (_event, _ctx) => {
+    runTelemetry("session_shutdown");
+    runAdapter("pi-hook-adapter.js", "session_shutdown", "stop-goal-fit", "stop-goal-fit.js");
+  });
+}
+`;
+}
+function buildPi(agents) {
+    const bundle = path.join(dist, "pi");
+    resetDir(bundle);
+    copySharedContent(bundle, "pi", "<bundle-root>");
+    writeText(path.join(bundle, manifest.pi.task_dir, ".gitkeep"), "");
+    // pi has no named-subagent registry; agents are left canonical/unexported.
+    // Skills are exported to .pi/skills/ (direct .md files supported in that dir).
+    for (const skill of fs.readdirSync(path.join(root, "skills"))) {
+        const skillPath = path.join(root, "skills", skill, "SKILL.md");
+        if (fs.existsSync(skillPath))
+            writeText(path.join(bundle, ".pi/skills", skill, "SKILL.md"), sanitizeText(readText(skillPath), "pi", "<bundle-root>"));
+    }
+    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"));
+    fs.chmodSync(path.join(bundle, "install.sh"), 0o755);
+}
 function buildCatalog(agents) {
     const kitsCatalog = path.join(root, "kits/catalog.json");
     return {
@@ -379,6 +643,8 @@ export function main() {
     buildKiro(agents);
     buildClaudeCode(agents);
     buildCodex(agents);
+    buildOpencode(agents);
+    buildPi(agents);
     writeText(path.join(dist, "catalog.json"), `${JSON.stringify(buildCatalog(agents), null, 2)}\n`);
     writeText(path.join(dist, "README.md"), "# Universal Bundles\n\nRun `npm run build:bundles` from the repo root to regenerate these bundles.\n");
     console.log("Built bundles:");
@@ -386,6 +652,8 @@ export function main() {
     console.log(" - dist/kiro");
     console.log(" - dist/claude-code");
     console.log(" - dist/codex");
+    console.log(" - dist/opencode");
+    console.log(" - dist/pi");
     if (printDiagnostics && dropDiagnostics.length) {
         console.error("Export sanitization diagnostics:");
         for (const item of dropDiagnostics)

package/build/src/tools/filter-installed-packs.js

@@ -108,10 +108,13 @@ export function main(argv = process.argv.slice(2)) {
     removed += pruneNamedDirs(rootDir, "skills", allPackMembers(packs, "skills"), selected.skills, dryRun);
     removed += pruneNamedDirs(rootDir, ".claude/skills", allPackMembers(packs, "skills"), selected.skills, dryRun);
     removed += pruneNamedDirs(rootDir, ".codex/skills", allPackMembers(packs, "skills"), selected.skills, dryRun);
+    removed += pruneNamedDirs(rootDir, ".opencode/skills", allPackMembers(packs, "skills"), selected.skills, dryRun);
+    removed += pruneNamedDirs(rootDir, ".pi/skills", allPackMembers(packs, "skills"), selected.skills, dryRun);
     removed += pruneNamedDirs(rootDir, "powers", allPackMembers(packs, "powers"), selected.powers, dryRun);
     removed += pruneAgentFiles(rootDir, "agents", ".json", allPackMembers(packs, "agents"), selected.agents, dryRun);
     removed += pruneAgentFiles(rootDir, ".claude/agents", ".md", allPackMembers(packs, "agents"), selected.agents, dryRun);
     removed += pruneAgentFiles(rootDir, ".codex/agents", ".toml", allPackMembers(packs, "agents"), selected.agents, dryRun);
+    removed += pruneAgentFiles(rootDir, ".opencode/agents", ".md", allPackMembers(packs, "agents"), selected.agents, dryRun);
     const summary = {
         selected_packs: [...selectedNames].sort(),
         removed_entries: removed,

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

@@ -62,12 +62,17 @@ const hookFilePolicies = new Map([
     ["scripts/hooks/run-hook.js", { category: "hook runner", requiredNeedles: ["isHookEnabled", "Path traversal rejected"] }],
     ["scripts/hooks/config-protection.js", { category: "policy hook", requiredNeedles: ["Config Protection Hook"] }],
     ["scripts/hooks/governance-audit.sh", { category: "policy hook", requiredNeedles: ["governance-audit.sh", "audit_emit"] }],
+    ["scripts/hooks/opencode-hook-adapter.js", { category: "runtime adapter", requiredNeedles: ["opencode", "run-hook.js"] }],
+    ["scripts/hooks/opencode-telemetry-hook.js", { category: "telemetry shim", requiredNeedles: ["opencode", "telemetry"] }],
+    ["scripts/hooks/pi-hook-adapter.js", { category: "runtime adapter", requiredNeedles: ["pi", "run-hook.js"] }],
+    ["scripts/hooks/pi-telemetry-hook.js", { category: "telemetry shim", requiredNeedles: ["pi", "telemetry"] }],
     ["scripts/hooks/post-edit-accumulator.js", { category: "policy hook", requiredNeedles: ["Post-Edit"] }],
     ["scripts/hooks/pre-commit-quality.js", { category: "repo guardrail hook", requiredNeedles: ["staged"] }],
     ["scripts/hooks/quality-gate.js", { category: "policy hook", requiredNeedles: ["Quality"] }],
     ["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"] }],
@@ -94,7 +99,7 @@ const requiredUsageFeedbackFiles = [
 const fixtureOwnershipSelfAuditRefs = new Set([
     "evals/integration/test_fixture_retirement_audit.sh",
 ]);
-const pythonInventoryExcludes = new Set([".git", ".flow-agents", "node_modules", ".venv", "dist", "__pycache__", ".pytest_cache", ".cache", "build"]);
+const pythonInventoryExcludes = new Set([".git", ".flow-agents", "node_modules", ".venv", "dist", "__pycache__", ".pytest_cache", ".cache", "build", "integrations"]);
 const pythonCommandScanRoots = ["README.md", "docs", "context", "skills", "prompts", "agents", "evals", "scripts", "packaging", "package.json"];
 const allowedPythonCommandFiles = [
     /^agents\/tool-explore-deps\.json$/,

package/context/scripts/telemetry/lib/config.sh

@@ -6,7 +6,11 @@ TELEMETRY_CONFIG_FILE="${TELEMETRY_CONFIG_FILE:-${TELEMETRY_DIR}/telemetry.conf}
 
 # Defaults
 TELEMETRY_ENABLED="${TELEMETRY_ENABLED:-true}"
-TELEMETRY_DATA_DIR="${TELEMETRY_DATA_DIR:-$(cd "${TELEMETRY_DIR}/../../.." && pwd)/.telemetry}"
+# TELEMETRY_DIR is <workspace>/scripts/telemetry, so the workspace root is
+# two levels up. Three levels escaped into the workspace's PARENT directory
+# (caught by live acceptance smoke 2026-06-11: events landed in /tmp/.telemetry
+# instead of the installed workspace).
+TELEMETRY_DATA_DIR="${TELEMETRY_DATA_DIR:-$(cd "${TELEMETRY_DIR}/../.." && pwd)/.telemetry}"
 TELEMETRY_SESSION_DIR="${TELEMETRY_SESSION_DIR:-${TELEMETRY_DATA_DIR}/sessions}"
 TELEMETRY_ENRICH_SYSTEM="${TELEMETRY_ENRICH_SYSTEM:-true}"
 TELEMETRY_ENRICH_WORKSPACE="${TELEMETRY_ENRICH_WORKSPACE:-true}"

package/context/settings/flow-agents-settings.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "../../schemas/flow-agents-settings.schema.json",
+  "schema_version": "1.0",
+  "utteranceCheck": {
+    "enabled": false
+  }
+}

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/context-map.md

@@ -50,6 +50,7 @@ Machine-readable workflow state lives beside Markdown artifacts in `.flow-agents
 | Schema | Title | ID |
 | --- | --- | --- |
 | backlog-provider-settings.schema.json | Flow Agents Backlog Provider Settings | https://flow-agents.dev/schemas/backlog-provider-settings.schema.json |
+| flow-agents-settings.schema.json | Flow Agents Settings | https://flow-agents.dev/schemas/flow-agents-settings.schema.json |
 | workflow-acceptance.schema.json | Flow Agents Workflow Acceptance | https://flow-agents.dev/schemas/workflow-acceptance.schema.json |
 | workflow-critique.schema.json | Flow Agents Workflow Critique | https://flow-agents.dev/schemas/workflow-critique.schema.json |
 | workflow-evidence.schema.json | Flow Agents Workflow Evidence | https://flow-agents.dev/schemas/workflow-evidence.schema.json |