@kontourai/flow-agents 0.1.1

package/context/scripts/hooks/run-hook.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+/**
+ * Hook runner — checks profile/disable flags before executing the actual hook.
+ *
+ * Usage:
+ *   node run-hook.js <hookId> <scriptRelativePath> [profilesCsv]
+ *
+ * Exit codes:
+ *   0 = allow (pass through)
+ *   2 = block (preToolUse only)
+ *   other = error (non-blocking)
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { isHookEnabled } = require('./lib/hook-flags');
+
+const MAX_STDIN = 1024 * 1024;
+
+function readStdinRaw() {
+  return new Promise(resolve => {
+    let raw = '';
+    let truncated = false;
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', chunk => {
+      if (raw.length < MAX_STDIN) {
+        const remaining = MAX_STDIN - raw.length;
+        raw += chunk.substring(0, remaining);
+        if (chunk.length > remaining) truncated = true;
+      } else {
+        truncated = true;
+      }
+    });
+    process.stdin.on('end', () => resolve({ raw, truncated }));
+    process.stdin.on('error', () => resolve({ raw, truncated }));
+  });
+}
+
+function emitHookResult(raw, output) {
+  if (typeof output === 'string' || Buffer.isBuffer(output)) {
+    process.stdout.write(String(output));
+    return 0;
+  }
+  if (output && typeof output === 'object') {
+    if (output.stderr) {
+      process.stderr.write(output.stderr.endsWith('\n') ? output.stderr : `${output.stderr}\n`);
+    }
+    if (Object.prototype.hasOwnProperty.call(output, 'stdout')) {
+      process.stdout.write(String(output.stdout ?? ''));
+    } else if (!Number.isInteger(output.exitCode) || output.exitCode === 0) {
+      process.stdout.write(raw);
+    }
+    return Number.isInteger(output.exitCode) ? output.exitCode : 0;
+  }
+  process.stdout.write(raw);
+  return 0;
+}
+
+async function main() {
+  const [, , hookId, relScriptPath, profilesCsv] = process.argv;
+  const { raw, truncated } = await readStdinRaw();
+
+  if (!hookId || !relScriptPath) {
+    process.stdout.write(raw);
+    process.exit(0);
+  }
+
+  if (!isHookEnabled(hookId, { profiles: profilesCsv })) {
+    process.stdout.write(raw);
+    process.exit(0);
+  }
+
+  const hooksDir = __dirname;
+  const scriptPath = path.resolve(hooksDir, relScriptPath);
+
+  if (!scriptPath.startsWith(hooksDir + path.sep)) {
+    process.stderr.write(`[Hook] Path traversal rejected for ${hookId}: ${scriptPath}\n`);
+    process.stdout.write(raw);
+    process.exit(0);
+  }
+
+  if (!fs.existsSync(scriptPath)) {
+    process.stderr.write(`[Hook] Script not found for ${hookId}: ${scriptPath}\n`);
+    process.stdout.write(raw);
+    process.exit(0);
+  }
+
+  // Prefer direct require() when the hook exports run() — saves ~50-100ms
+  let hookModule;
+  const src = fs.readFileSync(scriptPath, 'utf8');
+  if (/\bmodule\.exports\b/.test(src) && /\brun\b/.test(src)) {
+    try { hookModule = require(scriptPath); } catch (e) {
+      process.stderr.write(`[Hook] require() failed for ${hookId}: ${e.message}\n`);
+    }
+  }
+
+  if (hookModule && typeof hookModule.run === 'function') {
+    try {
+      const output = hookModule.run(raw, { truncated, maxStdin: MAX_STDIN });
+      process.exit(emitHookResult(raw, output));
+    } catch (e) {
+      process.stderr.write(`[Hook] run() error for ${hookId}: ${e.message}\n`);
+      process.stdout.write(raw);
+      process.exit(0);
+    }
+  }
+
+  // Legacy fallback: spawn child process
+  const result = spawnSync(process.execPath, [scriptPath], {
+    input: raw,
+    encoding: 'utf8',
+    env: { ...process.env, SA_HOOK_INPUT_TRUNCATED: truncated ? '1' : '0', SA_HOOK_INPUT_MAX_BYTES: String(MAX_STDIN) },
+    cwd: process.cwd(),
+    timeout: 30000,
+  });
+
+  if (result.stdout) process.stdout.write(result.stdout);
+  else if (Number.isInteger(result.status) && result.status === 0) process.stdout.write(raw);
+  if (result.stderr) process.stderr.write(result.stderr);
+
+  if (result.error || result.signal || result.status === null) {
+    const detail = result.error ? result.error.message : result.signal ? `signal ${result.signal}` : 'missing exit status';
+    process.stderr.write(`[Hook] legacy execution failed for ${hookId}: ${detail}\n`);
+    process.exit(1);
+  }
+
+  process.exit(Number.isInteger(result.status) ? result.status : 0);
+}
+
+main().catch(err => {
+  process.stderr.write(`[Hook] run-hook error: ${err.message}\n`);
+  process.exit(0);
+});

package/context/scripts/hooks/stop-format-typecheck.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+/**
+ * Stop Hook: Batch format + typecheck all JS/TS files edited this response
+ *
+ * Reads the accumulator from post-edit-accumulator.js, groups files by
+ * project root for formatter and by tsconfig dir for typecheck.
+ * Budget is distributed evenly across batches.
+ */
+
+'use strict';
+
+const { execFileSync, spawnSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const { findProjectRoot, detectFormatter, resolveFormatterBin } = require('./lib/resolve-formatter');
+
+const MAX_STDIN = 1024 * 1024;
+const TOTAL_BUDGET_MS = 270_000;
+
+function getAccumFile() {
+  // Import from accumulator to share session ID logic
+  try {
+    return require('./post-edit-accumulator').getAccumFile();
+  } catch {
+    const crypto = require('crypto');
+    const os = require('os');
+    const id = crypto.createHash('sha1').update(process.cwd()).digest('hex').slice(0, 12);
+    return path.join(os.tmpdir(), `flow-agents-edited-${id}.txt`);
+  }
+}
+
+function parseAccumulator(raw) {
+  return [...new Set(raw.split('\n').map(l => l.trim()).filter(Boolean))];
+}
+
+function formatBatch(projectRoot, files, timeoutMs) {
+  const formatter = detectFormatter(projectRoot);
+  if (!formatter) return;
+  const resolved = resolveFormatterBin(projectRoot, formatter);
+  if (!resolved) return;
+  const existing = files.filter(f => fs.existsSync(f));
+  if (existing.length === 0) return;
+  const args = formatter === 'biome'
+    ? [...resolved.prefix, 'check', '--write', ...existing]
+    : [...resolved.prefix, '--write', ...existing];
+  try {
+    execFileSync(resolved.bin, args, { cwd: projectRoot, stdio: ['pipe', 'pipe', 'pipe'], timeout: timeoutMs });
+  } catch { /* non-blocking */ }
+}
+
+function findTsConfigDir(filePath) {
+  let dir = path.dirname(filePath);
+  const root = path.parse(dir).root;
+  let depth = 0;
+  while (dir !== root && depth < 20) {
+    if (fs.existsSync(path.join(dir, 'tsconfig.json'))) return dir;
+    dir = path.dirname(dir);
+    depth++;
+  }
+  return null;
+}
+
+function typecheckBatch(tsConfigDir, editedFiles, timeoutMs) {
+  const args = ['tsc', '--noEmit', '--pretty', 'false'];
+  const opts = { cwd: tsConfigDir, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'], timeout: timeoutMs };
+  let stdout = '', stderr = '', failed = false;
+  try {
+    execFileSync('npx', args, opts);
+  } catch (err) {
+    stdout = err.stdout || '';
+    stderr = err.stderr || '';
+    failed = true;
+  }
+  if (!failed) return;
+  const lines = (stdout + stderr).split('\n');
+  for (const filePath of editedFiles) {
+    const relPath = path.relative(tsConfigDir, filePath);
+    const relevant = lines
+      .filter(line => line.includes(filePath) || line.includes(relPath))
+      .slice(0, 10);
+    if (relevant.length > 0) {
+      process.stderr.write(`[Hook] TypeScript errors in ${path.basename(filePath)}:\n`);
+      relevant.forEach(l => process.stderr.write(l + '\n'));
+    }
+  }
+}
+
+function main() {
+  const accumFile = getAccumFile();
+  let raw;
+  try { raw = fs.readFileSync(accumFile, 'utf8'); } catch { return; }
+  try { fs.unlinkSync(accumFile); } catch { /* best-effort */ }
+
+  const files = parseAccumulator(raw);
+  if (files.length === 0) return;
+
+  const byRoot = new Map();
+  const byTsConfig = new Map();
+  for (const f of files) {
+    if (!/\.(ts|tsx|js|jsx)$/.test(f)) continue;
+    const resolved = path.resolve(f);
+    if (!fs.existsSync(resolved)) continue;
+    const root = findProjectRoot(path.dirname(resolved));
+    if (!byRoot.has(root)) byRoot.set(root, []);
+    byRoot.get(root).push(resolved);
+    if (/\.(ts|tsx)$/.test(f)) {
+      const tsDir = findTsConfigDir(resolved);
+      if (tsDir) {
+        if (!byTsConfig.has(tsDir)) byTsConfig.set(tsDir, []);
+        byTsConfig.get(tsDir).push(resolved);
+      }
+    }
+  }
+
+  const totalBatches = byRoot.size + byTsConfig.size;
+  const perBatch = totalBatches > 0 ? Math.floor(TOTAL_BUDGET_MS / totalBatches) : 60_000;
+
+  for (const [root, batch] of byRoot) formatBatch(root, batch, perBatch);
+  for (const [tsDir, batch] of byTsConfig) typecheckBatch(tsDir, batch, perBatch);
+}
+
+function run(rawInput) {
+  try { main(); } catch (e) {
+    process.stderr.write(`[Hook] stop-format-typecheck error: ${e.message}\n`);
+  }
+  return rawInput;
+}
+
+if (require.main === module) {
+  let data = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => {
+    if (data.length < MAX_STDIN) data += chunk.substring(0, MAX_STDIN - data.length);
+  });
+  process.stdin.on('end', () => {
+    process.stdout.write(run(data));
+    process.exit(0);
+  });
+}
+
+module.exports = { run, parseAccumulator };

package/context/scripts/hooks/stop-goal-fit.js

@@ -0,0 +1,337 @@
+#!/usr/bin/env node
+/**
+ * Stop Hook: warn when an active workflow is about to stop short of its goal.
+ *
+ * The hook reads .flow-agents artifacts, looks for the most recent active
+ * delivery/session file, and reports missing Definition Of Done, Goal Fit, or
+ * Final Acceptance state. It is warning-only by default. Set
+ * FLOW_AGENTS_GOAL_FIT_STRICT=true to return exit code 2 when local goal fit is
+ * incomplete.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const MAX_STDIN = 1024 * 1024;
+const ACTIVE_STATUSES = new Set([
+  'planning',
+  'planned',
+  'executing',
+  'executed',
+  'reviewing',
+  'verifying',
+  'failed',
+  'needs-decision',
+  'in-progress',
+  'blocked',
+  'partial',
+]);
+const DELIVERY_TYPES = new Set(['deliver', 'delivery', 'fix-bug', 'execute-plan', 'verify-work']);
+const SIDECAR_NAMES = new Set(['state.json', 'acceptance.json', 'evidence.json', 'handoff.json']);
+const OPTIONAL_SIDECAR_NAMES = new Set(['critique.json']);
+
+function parseJson(raw) {
+  try { return JSON.parse(raw || '{}'); } catch { return {}; }
+}
+
+function findRepoRoot(startDir) {
+  let dir = path.resolve(startDir || process.cwd());
+  const root = path.parse(dir).root;
+  for (let depth = 0; dir && depth < 40; depth++) {
+    if (fs.existsSync(path.join(dir, '.git')) || fs.existsSync(path.join(dir, 'AGENTS.md'))) return dir;
+    if (dir === root) break;
+    dir = path.dirname(dir);
+  }
+  return path.resolve(startDir || process.cwd());
+}
+
+function walkMarkdown(dir, out = []) {
+  if (!fs.existsSync(dir)) return out;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === 'archive') continue;
+      walkMarkdown(full, out);
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+function readArtifact(file) {
+  let text = '';
+  try { text = fs.readFileSync(file, 'utf8'); } catch { return null; }
+  const stat = fs.statSync(file);
+  const status = (text.match(/^status:\s*([A-Za-z0-9_-]+)/m) || [])[1] || '';
+  const type = (text.match(/^type:\s*([A-Za-z0-9_-]+)/m) || [])[1] || '';
+  const role = (text.match(/^role:\s*([A-Za-z0-9_-]+)/m) || [])[1] || '';
+  return { file, text, status, type, role, mtimeMs: stat.mtimeMs };
+}
+
+function hasSidecars(dir) {
+  try {
+    return fs.readdirSync(dir).some(name => SIDECAR_NAMES.has(name));
+  } catch {
+    return false;
+  }
+}
+
+function sidecarValidation(root, artifactDir) {
+  const requireSidecars = String(process.env.FLOW_AGENTS_REQUIRE_SIDECARS || '').toLowerCase() === 'true';
+  const requireCritique = String(process.env.FLOW_AGENTS_REQUIRE_CRITIQUE || '').toLowerCase() === 'true';
+  if (!requireSidecars && !requireCritique && !hasSidecars(artifactDir)) return [];
+
+  const packageRoot = fs.existsSync(path.join(root, 'package.json'))
+    ? root
+    : path.resolve(__dirname, '..', '..');
+  const packageJson = path.join(packageRoot, 'package.json');
+  if (!fs.existsSync(packageJson)) return [`${relative(root, artifactDir)} sidecar validation: package.json is missing; cannot run TypeScript workflow validator.`];
+
+  let sidecarFiles = [];
+  try {
+    sidecarFiles = fs.readdirSync(artifactDir)
+      .filter(name => SIDECAR_NAMES.has(name) || OPTIONAL_SIDECAR_NAMES.has(name))
+      .map(name => path.join(artifactDir, name));
+  } catch {
+    sidecarFiles = [];
+  }
+
+  if (requireSidecars || requireCritique) {
+    const present = new Set(sidecarFiles.map(file => path.basename(file)));
+    const requiredNames = new Set(requireSidecars ? SIDECAR_NAMES : []);
+    if (requireCritique) requiredNames.add('critique.json');
+    const missing = [...requiredNames].filter(name => !present.has(name)).sort();
+    if (missing.length > 0) {
+      return missing.map(name => `${relative(root, path.join(artifactDir, name))} sidecar validation: required sidecar is missing`);
+    }
+  }
+
+  if (sidecarFiles.length === 0) return [];
+
+  const args = ['run', 'workflow:validate-artifacts', '--silent', '--'];
+  args.push('--skip-markdown-validation');
+  if (requireSidecars) args.push('--require-sidecars');
+  if (requireCritique) args.push('--require-critique');
+  args.push(artifactDir);
+
+  const result = spawnSync('npm', args, {
+    cwd: packageRoot,
+    encoding: 'utf8',
+    timeout: 30000,
+  });
+
+  if (result.status === 0) return [];
+  const output = `${result.stdout || ''}\n${result.stderr || ''}`
+    .split('\n')
+    .map(line => line.trim())
+    .filter(Boolean)
+    .slice(0, 12);
+  if (output.length === 0) output.push(`validator exited with status ${result.status ?? 'unknown'}`);
+  return output.map(line => `${relative(root, artifactDir)} sidecar validation: ${line}`);
+}
+
+function isWorkflowArtifact(artifact) {
+  if (!artifact) return false;
+  if (artifact.role === 'plan' || artifact.role === 'review') return false;
+  if (artifact.file.endsWith('-plan.md') || artifact.file.endsWith('-review.md')) return false;
+  if (DELIVERY_TYPES.has(artifact.type)) return true;
+  return /--(deliver|fix-bug|execute-plan|verify-work)\b/.test(path.basename(artifact.file));
+}
+
+function uncheckedInSection(text, heading) {
+  const start = text.indexOf(`## ${heading}`);
+  if (start < 0) return [];
+  const rest = text.slice(start + heading.length + 3);
+  const next = rest.search(/\n##\s+/);
+  const section = next >= 0 ? rest.slice(0, next) : rest;
+  return section
+    .split('\n')
+    .filter(line => /^\s*-\s+\[\s\]/.test(line))
+    .map(line => line.replace(/^\s*-\s+\[\s\]\s*/, '').trim())
+    .filter(Boolean);
+}
+
+function hasHeading(text, heading) {
+  return new RegExp(`^##\\s+${heading.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*$`, 'm').test(text);
+}
+
+function relative(root, file) {
+  return path.relative(root, file).split(path.sep).join('/');
+}
+
+function readJsonFile(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function safeOneLine(value, maxLength = 220) {
+  const text = String(value || '').replace(/\s+/g, ' ').trim();
+  if (text.length <= maxLength) return text;
+  return `${text.slice(0, maxLength - 3)}...`;
+}
+
+function normalizedStatus(value) {
+  return safeOneLine(value, 80).toLowerCase();
+}
+
+function sidecarGuidance(root, artifactDir) {
+  const warnings = [];
+  const state = readJsonFile(path.join(artifactDir, 'state.json'));
+  const evidence = readJsonFile(path.join(artifactDir, 'evidence.json'));
+  const critique = readJsonFile(path.join(artifactDir, 'critique.json'));
+  const base = relative(root, artifactDir);
+
+  if (state) {
+    const status = normalizedStatus(state.status || 'unknown');
+    const phase = normalizedStatus(state.phase || 'unknown');
+    const next = state.next_action && typeof state.next_action === 'object' ? state.next_action : null;
+    if (!['done', 'delivered', 'archived', 'accepted', 'complete', 'completed'].includes(status)) {
+      const nextStatus = next ? normalizedStatus(next.status || 'unknown') : 'unknown';
+      const nextSummary = next && next.summary ? `; next_action:${nextStatus} "${safeOneLine(next.summary)}"` : '';
+      warnings.push(`${base} workflow state: status:${status} phase:${phase}${nextSummary}`);
+    }
+  }
+
+  if (state && state.next_action && normalizedStatus(state.next_action.status) !== 'done') {
+    const next = state.next_action;
+    warnings.push(`${base} next action: ${safeOneLine(next.summary)}${next.target_phase ? ` (target phase: ${safeOneLine(next.target_phase, 80)})` : ''}`);
+  }
+
+  if (evidence && normalizedStatus(evidence.verdict) && normalizedStatus(evidence.verdict) !== 'pass') {
+    warnings.push(`${base} evidence verdict:${safeOneLine(evidence.verdict, 40)}; do not deliver without accepted gap or new evidence.`);
+  }
+  if (evidence && Array.isArray(evidence.not_verified_gaps) && evidence.not_verified_gaps.length > 0) {
+    for (const gap of evidence.not_verified_gaps.slice(0, 3)) {
+      warnings.push(`${base} evidence NOT_VERIFIED gap: ${safeOneLine(gap)}`);
+    }
+  }
+  if (evidence && Array.isArray(evidence.checks)) {
+    const blockingChecks = evidence.checks.filter(check => {
+      const status = normalizedStatus(check && check.status);
+      return status === 'fail' || status === 'failed' || status === 'not_verified' || status === 'not-verified';
+    });
+    for (const check of blockingChecks.slice(0, 4)) {
+      const status = safeOneLine(check.status || 'unknown', 40);
+      warnings.push(`${base} evidence check ${safeOneLine(check.id || 'unknown', 80)} status:${status}: ${safeOneLine(check.summary)}`);
+    }
+  }
+
+  if (critique && critique.required === true && normalizedStatus(critique.status) !== 'pass') {
+    warnings.push(`${base} critique status:${safeOneLine(critique.status || 'unknown', 40)}; required critique must pass or findings be accepted.`);
+    const critiques = Array.isArray(critique.critiques) ? critique.critiques : [];
+    let openCount = 0;
+    for (const review of critiques) {
+      const findings = Array.isArray(review && review.findings) ? review.findings : [];
+      for (const finding of findings) {
+        if (!finding || normalizedStatus(finding.status) !== 'open') continue;
+        warnings.push(`${base} critique open ${safeOneLine(finding.severity || 'unknown', 40)}: ${safeOneLine(finding.description)}`);
+        openCount += 1;
+        if (openCount >= 3) break;
+      }
+      if (openCount >= 3) break;
+    }
+  }
+
+  return warnings;
+}
+
+function markdownVerdict(text) {
+  const verdict = (/###\s+Verdict:\s*([A-Za-z_ -]+)/i.exec(text) || [])[1]
+    || (/^Build:\s*\[?([A-Za-z_ -]+)\]?/im.exec(text) || [])[1]
+    || '';
+  return normalizedStatus(verdict).replace(/[^a-z_ -].*$/, '').trim();
+}
+
+function analyze(root, now = Date.now()) {
+  const dirs = [path.join(root, '.flow-agents')];
+  const artifacts = dirs
+    .flatMap(dir => walkMarkdown(dir))
+    .map(readArtifact)
+    .filter(isWorkflowArtifact)
+    .sort((a, b) => b.mtimeMs - a.mtimeMs);
+
+  if (artifacts.length === 0) return { warnings: [], blocking: false };
+
+  const latest = artifacts[0];
+  const warnings = [];
+  const relPath = relative(root, latest.file);
+  const status = latest.status || 'unknown';
+  const ageMinutes = Math.max(0, Math.round((now - latest.mtimeMs) / 60000));
+
+  if (ACTIVE_STATUSES.has(status)) {
+    warnings.push(`${relPath} is still status:${status} (${ageMinutes}m old). Do not final-answer as complete unless the next step is explicit.`);
+  }
+
+  if (!hasHeading(latest.text, 'Definition Of Done')) {
+    warnings.push(`${relPath} is missing ## Definition Of Done, so the user-facing finish line is not explicit.`);
+  }
+
+  if (!hasHeading(latest.text, 'Goal Fit Gate')) {
+    warnings.push(`${relPath} is missing ## Goal Fit Gate, so local acceptance has not been checked.`);
+  } else {
+    for (const item of uncheckedInSection(latest.text, 'Goal Fit Gate').slice(0, 6)) {
+      warnings.push(`${relPath} Goal Fit unchecked: ${item}`);
+    }
+  }
+
+  if (status === 'delivered' && hasHeading(latest.text, 'Final Acceptance')) {
+    const uncheckedFinal = uncheckedInSection(latest.text, 'Final Acceptance');
+    if (uncheckedFinal.length > 0) {
+      warnings.push(`${relPath} local delivery is marked delivered, but Final Acceptance still has ${uncheckedFinal.length} open item(s) for CI/merge/docs promotion.`);
+    }
+  }
+
+  warnings.push(...sidecarValidation(root, path.dirname(latest.file)));
+  const evidence = readJsonFile(path.join(path.dirname(latest.file), 'evidence.json'));
+  if (evidence && markdownVerdict(latest.text) === 'pass' && normalizedStatus(evidence.verdict) === 'fail') {
+    warnings.push(`${relPath} Markdown PASS contradicts evidence.json verdict fail.`);
+  }
+  warnings.push(...sidecarGuidance(root, path.dirname(latest.file)));
+
+  const blocking = warnings.some(w => /status:|Definition Of Done|Goal Fit|sidecar validation|contradicts evidence\.json|workflow state|evidence verdict|evidence check|NOT_VERIFIED gap|critique status|critique open|next action/.test(w));
+  return { warnings, blocking };
+}
+
+function run(rawInput) {
+  const input = parseJson(rawInput);
+  const root = findRepoRoot(input.cwd || process.cwd());
+  const result = analyze(root);
+  if (result.warnings.length === 0) return rawInput;
+
+  const message = [
+    '[Hook] Goal Fit warning:',
+    ...result.warnings.map(w => ` - ${w}`),
+  ].join('\n');
+  const strict = String(process.env.FLOW_AGENTS_GOAL_FIT_STRICT || '').toLowerCase() === 'true';
+  return {
+    stdout: rawInput,
+    stderr: message,
+    exitCode: strict && result.blocking ? 2 : 0,
+  };
+}
+
+if (require.main === module) {
+  let data = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => {
+    if (data.length < MAX_STDIN) data += chunk.substring(0, MAX_STDIN - data.length);
+  });
+  process.stdin.on('end', () => {
+    const output = run(data);
+    if (output && typeof output === 'object') {
+      if (output.stderr) process.stderr.write(output.stderr.endsWith('\n') ? output.stderr : `${output.stderr}\n`);
+      process.stdout.write(String(output.stdout ?? data));
+      process.exit(Number.isInteger(output.exitCode) ? output.exitCode : 0);
+    }
+    process.stdout.write(String(output));
+  });
+}
+
+module.exports = { analyze, run, uncheckedInSection, findRepoRoot, sidecarGuidance, safeOneLine };