@hone-ai/cli 1.19.0 → 1.20.0

package/lib/mcp-tools.js

@@ -0,0 +1,310 @@
+'use strict';
+/**
+ * mcp-tools.js — HC-COMM-012 (A1 P1): the agent-eval/pipeline tool HANDLERS behind
+ * the Hone MCP server. Kept separate from the MCP protocol wiring (mcp-server.js)
+ * so the logic is unit-testable without the SDK or a real MCP client.
+ *
+ * Design (architect memo HC-COMM-012 §3): these handlers SHELL OUT to the installed
+ * `hone` CLI verbs — the one execution implementation — and parse their output. They
+ * re-implement nothing: `verify-patch` etc. still run in the CLI, honoring the
+ * server↔CLI boundary. Pure parsers are exported so the parsing is tested directly.
+ */
+const { spawn } = require('node:child_process');
+const fsSync = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+// Resolve the CLI binary. Default `hone` (the installed bin); overridable for tests
+// / non-global installs via HONE_CLI_BIN (e.g. a path to hone-cli.js run with node).
+function honeBin() {
+  return process.env.HONE_CLI_BIN || 'hone';
+}
+
+// Resolve token + apiUrl the SAME way the CLI's getConfig does (env → ~/.honerc →
+// default) — but WITHOUT exiting on a missing token (the MCP server must start and
+// report the problem via a preflight / hone_doctor, not die). Editor-agnostic:
+// works from any MCP client that passes HONE_TOKEN/HONE_API in the server env.
+function readHoneConfig() {
+  let rc = {};
+  try { rc = JSON.parse(fsSync.readFileSync(path.join(os.homedir(), '.honerc'), 'utf8')) || {}; } catch { rc = {}; }
+  const token = process.env.HONE_TOKEN || rc.token || null;
+  const apiUrl = process.env.HONE_API || rc.api || 'https://api.hone.ai';
+  return { token, apiUrl, hasToken: !!token };
+}
+
+// Run a `hone` subcommand, capturing stdout/stderr/exit. Never throws — returns a
+// structured result (mirrors the executor's never-throw contract).
+function runHone(args, { cwd, timeoutMs = 120000 } = {}) {
+  return new Promise((resolve) => {
+    let child;
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+    try {
+      child = spawn(honeBin(), args, { cwd: cwd || process.cwd(), stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch (e) {
+      return resolve({ ok: false, exitCode: null, stdout: '', stderr: '', error: e.code === 'ENOENT' ? 'hone CLI not found on PATH' : e.message });
+    }
+    const timer = setTimeout(() => { timedOut = true; try { child.kill('SIGTERM'); } catch { /* gone */ } }, timeoutMs);
+    child.stdout.on('data', (c) => { stdout += c.toString(); });
+    child.stderr.on('data', (c) => { stderr += c.toString(); });
+    child.on('error', (e) => { clearTimeout(timer); resolve({ ok: false, exitCode: null, stdout, stderr, error: e.code === 'ENOENT' ? 'hone CLI not found on PATH' : e.message }); });
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      if (timedOut) return resolve({ ok: false, exitCode: null, stdout, stderr, error: `timed out after ${timeoutMs}ms` });
+      resolve({ ok: code === 0, exitCode: code, stdout, stderr });
+    });
+  });
+}
+
+// ── Pure parsers (unit-tested directly) ──────────────────────────────────────
+
+// `hone run-story <id>` prints "Workflow started: <uuid>" on success.
+function parseRunStarted(stdout) {
+  const m = String(stdout).match(/Workflow started:\s*([0-9a-f-]{8,})/i);
+  return m ? m[1] : null;
+}
+
+// `--format json` output: the LAST JSON object/array in stdout (grounding logs may
+// precede it). Returns the parsed value or null.
+function parseLastJson(stdout) {
+  const s = String(stdout);
+  // find the last top-level '{' or '[' and try to parse from there to the end
+  for (const open of ['{', '[']) {
+    const i = s.lastIndexOf('\n' + open);
+    const start = i >= 0 ? i + 1 : (s.trimStart().startsWith(open) ? s.indexOf(open) : -1);
+    if (start < 0) continue;
+    try { return JSON.parse(s.slice(start).trim()); } catch { /* try the other bracket */ }
+  }
+  try { return JSON.parse(s.trim()); } catch { return null; }
+}
+
+// ── Tool handlers ────────────────────────────────────────────────────────────
+
+// hone_run_story — start a run. Pure API path in the CLI (POST /orchestrate).
+async function runStory({ storyId, mode = 'batch', cwd } = {}) {
+  if (storyId === undefined || storyId === null || String(storyId).trim() === '') {
+    return { isError: true, detail: 'storyId is required' };
+  }
+  const r = await runHone(['run-story', String(storyId), '--mode', String(mode)], { cwd });
+  if (r.error) return { isError: true, detail: r.error };
+  const runId = parseRunStarted(r.stdout);
+  return {
+    isError: !runId && !r.ok,
+    runId,
+    exitCode: r.exitCode,
+    detail: runId ? `run started: ${runId}` : (r.stderr || r.stdout || 'run-story produced no workflow id').slice(0, 500),
+  };
+}
+
+// hone_status — read run status (readOnly). GET /orchestrate/:id.
+async function status({ runId, cwd } = {}) {
+  if (!runId) return { isError: true, detail: 'runId is required' };
+  const r = await runHone(['run-story', String(runId), '--status', '--format', 'json'], { cwd });
+  if (r.error) return { isError: true, detail: r.error };
+  const data = parseLastJson(r.stdout);
+  return { isError: !data, status: data, exitCode: r.exitCode, detail: data ? 'ok' : (r.stderr || 'could not parse status JSON').slice(0, 500) };
+}
+
+// hone_verify_patch — apply step_4 diff in a worktree + run make ci (REAL local
+// execution, in the CLI), optionally report the verdict. Long-running → wide timeout.
+async function verifyPatch({ runId, report = false, cwd } = {}) {
+  if (!runId) return { isError: true, detail: 'runId is required' };
+  const args = ['verify-patch', String(runId), '--format', 'json'];
+  if (report) args.push('--report');
+  const r = await runHone(args, { cwd, timeoutMs: 600000 });
+  if (r.error) return { isError: true, detail: r.error };
+  const data = parseLastJson(r.stdout);
+  const verdict = data && (data.verdict || data.result) ? (data.verdict || data.result) : (r.ok ? 'pass' : 'fail');
+  return { isError: false, verdict, passed: r.ok, exitCode: r.exitCode, report: data, detail: (data && data.detail) || (r.ok ? 'tests passed' : 'tests failed') };
+}
+
+// hone_check_patch — does step_4's diff apply cleanly? (throwaway git apply --check)
+async function checkPatch({ runId, stepKey = 'step_4', cwd } = {}) {
+  if (!runId) return { isError: true, detail: 'runId is required' };
+  const r = await runHone(['check-patch', String(runId), '--step-key', String(stepKey), '--format', 'json'], { cwd });
+  if (r.error) return { isError: true, detail: r.error };
+  const data = parseLastJson(r.stdout);
+  return { isError: false, applies: r.ok, exitCode: r.exitCode, report: data, detail: (data && data.detail) || (r.ok ? 'diff applies cleanly' : 'diff does not apply') };
+}
+
+// hone_emit_pr — verified diff → branch → draft PR (staged: --push, --open-pr).
+async function emitPr({ runId, push = false, openPr = false, branch, base, cwd } = {}) {
+  if (!runId) return { isError: true, detail: 'runId is required' };
+  const args = ['emit-pr', String(runId), '--format', 'json'];
+  if (openPr) args.push('--open-pr'); else if (push) args.push('--push');
+  if (branch) args.push('--branch', String(branch));
+  if (base) args.push('--base', String(base));
+  const r = await runHone(args, { cwd, timeoutMs: 180000 });
+  if (r.error) return { isError: true, detail: r.error };
+  const data = parseLastJson(r.stdout);
+  return { isError: !r.ok, exitCode: r.exitCode, report: data, detail: ((data && (data.prUrl || data.detail)) || (r.ok ? 'emitted' : r.stderr || 'emit failed')).slice(0, 500) };
+}
+
+// hone_verify_pr — real skill audit + real CI gate on an open PR, optional report.
+async function verifyPr({ pr, report = false, workflowId, cwd } = {}) {
+  if (!pr) return { isError: true, detail: 'pr (number or branch) is required' };
+  const args = ['verify-pr', String(pr), '--format', 'json'];
+  if (report) { args.push('--report'); if (workflowId) args.push('--workflow-id', String(workflowId)); }
+  const r = await runHone(args, { cwd, timeoutMs: 600000 });
+  if (r.error) return { isError: true, detail: r.error };
+  const data = parseLastJson(r.stdout);
+  const verdict = data && data.verdict ? data.verdict : (r.ok ? 'pass' : 'fail');
+  return { isError: false, verdict, passed: r.ok, exitCode: r.exitCode, report: data, detail: (data && data.detail) || (r.ok ? 'CI green' : 'CI red') };
+}
+
+// hone_agent_eval — test the adopter's own agents (HC-COMM-011), optional report.
+async function agentEval({ category, target, judge = false, provider, report = false, workflowId, cwd } = {}) {
+  const args = ['agent-eval', '--output', 'json'];
+  if (category) args.push('--category', String(category));
+  if (target) args.push('--target', String(target));
+  if (judge) args.push('--judge');
+  if (provider) args.push('--provider', String(provider));
+  if (report) { args.push('--report'); if (workflowId) args.push('--workflow-id', String(workflowId)); }
+  const r = await runHone(args, { cwd, timeoutMs: 300000 });
+  if (r.error) return { isError: true, detail: r.error };
+  const data = parseLastJson(r.stdout);
+  const passed = data && typeof data.passed === 'boolean' ? data.passed : r.ok;
+  return { isError: false, passed, exitCode: r.exitCode, report: data, detail: (data && Array.isArray(data.results)) ? `${data.results.filter((x) => x.passed).length}/${data.results.length} probes passed` : (r.ok ? 'passed' : 'failed') };
+}
+
+// hone_show_step — the LLM output of an orchestrator step (readOnly).
+async function showStep({ runId, stepKey, cwd } = {}) {
+  if (!runId || !stepKey) return { isError: true, detail: 'runId and stepKey are required' };
+  const r = await runHone(['show', 'step', String(runId), String(stepKey)], { cwd });
+  if (r.error) return { isError: true, detail: r.error };
+  return { isError: !r.ok, exitCode: r.exitCode, output: r.stdout.slice(0, 8000), detail: r.ok ? 'ok' : (r.stderr || 'show step failed').slice(0, 500) };
+}
+
+// hone_approve — approve a paused human gate (run-story --approve).
+async function approve({ runId, stepKey, cwd } = {}) {
+  if (!runId || !stepKey) return { isError: true, detail: 'runId and stepKey are required' };
+  const r = await runHone(['run-story', String(runId), '--approve', String(stepKey)], { cwd });
+  if (r.error) return { isError: true, detail: r.error };
+  return { isError: !r.ok, exitCode: r.exitCode, detail: (r.ok ? `approved ${stepKey}` : (r.stderr || r.stdout || 'approve failed')).slice(0, 500) };
+}
+
+// hone_derive — derive/refresh the adopter's domain skills (async, server-side).
+async function derive({ cwd } = {}) {
+  const r = await runHone(['derive'], { cwd, timeoutMs: 600000 });
+  if (r.error) return { isError: true, detail: r.error };
+  return { isError: !r.ok, exitCode: r.exitCode, detail: (r.ok ? 'derive complete' : (r.stderr || r.stdout || 'derive failed')).slice(0, 500) };
+}
+
+// hone_sync — pull latest skills + agent prompts into the local repo (writes files).
+async function sync({ skillsOnly = false, agentsOnly = false, cwd } = {}) {
+  const args = ['sync'];
+  if (skillsOnly) args.push('--skills-only');
+  if (agentsOnly) args.push('--agents-only');
+  const r = await runHone(args, { cwd, timeoutMs: 120000 });
+  if (r.error) return { isError: true, detail: r.error };
+  return { isError: !r.ok, exitCode: r.exitCode, detail: (r.ok ? 'sync complete' : (r.stderr || r.stdout || 'sync failed')).slice(0, 500) };
+}
+
+// hone_doctor — self-check the setup (readOnly): is a token present, and is the
+// `hone` CLI installed + reachable? Invaluable across editors, where "is it wired?"
+// is the #1 MCP setup question. No network call (fast, never hangs).
+async function doctor({ cwd } = {}) {
+  const cfg = readHoneConfig();
+  const checks = [];
+  checks.push({ name: 'token', ok: cfg.hasToken, detail: cfg.hasToken ? 'token present (HONE_TOKEN / ~/.honerc)' : 'no token — run `hone init --token <t>` or set HONE_TOKEN' });
+  checks.push({ name: 'apiUrl', ok: true, detail: cfg.apiUrl });
+  const v = await runHone(['--version'], { cwd, timeoutMs: 15000 });
+  const cliOk = v.ok && /\d+\.\d+\.\d+/.test(v.stdout);
+  checks.push({ name: 'hone-cli', ok: cliOk, detail: cliOk ? `hone ${v.stdout.trim()}` : (v.error || 'hone CLI not found — `npm i -g @hone-ai/cli`') });
+  const allOk = checks.every((c) => c.ok);
+  return { isError: false, ok: allOk, checks, detail: allOk ? 'ready' : 'setup incomplete — see checks' };
+}
+
+// The tool registry the MCP server iterates. Kept declarative so mcp-server.js is thin.
+const TOOLS = [
+  {
+    name: 'hone_run_story',
+    description: 'Start a Hone SDLC pipeline run for a story id or GitHub issue number. Runs server-side on the org\'s Anthropic key; returns a runId. Does not execute locally.',
+    readOnly: false,
+    inputSchema: { type: 'object', properties: { storyId: { type: 'string', description: 'roadmap story id or GitHub issue number' }, mode: { type: 'string', enum: ['interactive', 'batch'], default: 'batch' } }, required: ['storyId'] },
+    handler: runStory,
+  },
+  {
+    name: 'hone_status',
+    description: 'Read the status of a Hone run (steps + gate state). Read-only.',
+    readOnly: true,
+    inputSchema: { type: 'object', properties: { runId: { type: 'string' } }, required: ['runId'] },
+    handler: status,
+  },
+  {
+    name: 'hone_verify_patch',
+    description: 'Verify a run\'s step_4 change LOCALLY: apply the diff in a throwaway worktree and run the tests (make ci), then optionally report the verdict. This RUNS YOUR TESTS and touches a temporary worktree.',
+    readOnly: false,
+    inputSchema: { type: 'object', properties: { runId: { type: 'string' }, report: { type: 'boolean', default: false } }, required: ['runId'] },
+    handler: verifyPatch,
+  },
+  {
+    name: 'hone_check_patch',
+    description: 'Check whether a run\'s step_4 diff applies cleanly (throwaway `git apply --check`). Read-mostly; touches no tracked files.',
+    readOnly: false,
+    inputSchema: { type: 'object', properties: { runId: { type: 'string' }, stepKey: { type: 'string', default: 'step_4' } }, required: ['runId'] },
+    handler: checkPatch,
+  },
+  {
+    name: 'hone_show_step',
+    description: 'Print the LLM output of an orchestrator step for a run (e.g. the plan, the tests, the diff). Read-only.',
+    readOnly: true,
+    inputSchema: { type: 'object', properties: { runId: { type: 'string' }, stepKey: { type: 'string' } }, required: ['runId', 'stepKey'] },
+    handler: showStep,
+  },
+  {
+    name: 'hone_approve',
+    description: 'Approve a paused human gate on a run so it advances (e.g. stepKey "step_4").',
+    readOnly: false,
+    inputSchema: { type: 'object', properties: { runId: { type: 'string' }, stepKey: { type: 'string' } }, required: ['runId', 'stepKey'] },
+    handler: approve,
+  },
+  {
+    name: 'hone_emit_pr',
+    description: 'Turn a verified run into a branch and (staged) a draft PR. By default a local dry run; set push=true to push, openPr=true to open a draft PR. WRITES a branch / PR when pushed.',
+    readOnly: false,
+    inputSchema: { type: 'object', properties: { runId: { type: 'string' }, push: { type: 'boolean', default: false }, openPr: { type: 'boolean', default: false }, branch: { type: 'string' }, base: { type: 'string' } }, required: ['runId'] },
+    handler: emitPr,
+  },
+  {
+    name: 'hone_verify_pr',
+    description: 'Run the real skill audit + CI gate on an open PR (gh pr checks / make ci), optionally reporting the verdict. EXECUTES locally.',
+    readOnly: false,
+    inputSchema: { type: 'object', properties: { pr: { type: 'string', description: 'PR number or branch' }, report: { type: 'boolean', default: false }, workflowId: { type: 'string' } }, required: ['pr'] },
+    handler: verifyPr,
+  },
+  {
+    name: 'hone_agent_eval',
+    description: 'Test the adopter\'s own agents (adversarial, faithfulness, safety, boundary), optionally with the free NLI judge, optionally reporting the verdict. Deterministic + $0 by default. EXECUTES locally.',
+    readOnly: false,
+    inputSchema: { type: 'object', properties: { category: { type: 'string', enum: ['adversarial', 'faithfulness', 'safety', 'boundary'] }, target: { type: 'string' }, judge: { type: 'boolean', default: false }, provider: { type: 'string', enum: ['gh-models', 'claude'] }, report: { type: 'boolean', default: false }, workflowId: { type: 'string' } } },
+    handler: agentEval,
+  },
+  {
+    name: 'hone_derive',
+    description: 'Derive/refresh the adopter\'s domain skills from the codebase (async, server-side). Long-running.',
+    readOnly: false,
+    inputSchema: { type: 'object', properties: {} },
+    handler: derive,
+  },
+  {
+    name: 'hone_sync',
+    description: 'Pull the latest derived skills + agent prompts into the local repo. WRITES files under .claude/agents and .github/skills.',
+    readOnly: false,
+    inputSchema: { type: 'object', properties: { skillsOnly: { type: 'boolean', default: false }, agentsOnly: { type: 'boolean', default: false } } },
+    handler: sync,
+  },
+  {
+    name: 'hone_doctor',
+    description: 'Self-check the Hone setup (read-only): is a token configured, and is the `hone` CLI installed + reachable? Run this first if other tools fail.',
+    readOnly: true,
+    inputSchema: { type: 'object', properties: {} },
+    handler: doctor,
+  },
+];
+
+module.exports = {
+  runStory, status, verifyPatch, checkPatch, showStep, approve, emitPr, verifyPr, agentEval, derive, sync, doctor,
+  runHone, parseRunStarted, parseLastJson, honeBin, readHoneConfig, TOOLS,
+};

package/lib/patch-apply.js

@@ -0,0 +1,108 @@
+'use strict';
+/**
+ * patch-apply.js — HC-019n-followup-20 (pipeline-recovery condition 5).
+ *
+ * The true closed loop: does step_4's diff actually APPLY to a real working
+ * tree? The server can only check that the output LOOKS like a diff
+ * (patch-validator, condition 4) because it has no adopter tree. Only the CLI,
+ * running inside the repo, can run `git apply --check`.
+ *
+ * This module is the pure half — extract a diff from agent output and interpret
+ * a `git apply --check` result. The git invocation itself lives in the command
+ * (hone-cli.js) so this stays I/O-free and unit-testable.
+ *
+ * Condition 4 (well-formed) and condition 5 (applies) are genuinely different:
+ * run c122c92a produced a diff that PASSED the server validator and FAILED to
+ * apply — the agent emitted `@@ -0,0 +1,54 @@` (create-file) for a file that
+ * already existed. Structure is not applicability.
+ */
+
+/**
+ * Pull the unified diff out of a code-builder artifact.
+ *
+ * Prefers a fenced ```diff block (what the HC-019n-followup-19 prompt asks
+ * for). Falls back to a bare diff — headers through the last hunk-ish line —
+ * so a model that forgets the fence but emits a real patch is still checkable.
+ *
+ * @param {string} output  raw step_4 output
+ * @returns {{ diff: string|null, source: 'fenced'|'bare'|null, noChanges: boolean }}
+ */
+function extractDiff(output) {
+  const text = String(output || '');
+
+  // Honest "no changes" escape from the prompt — a first-class signal, not a
+  // failure. Anchored to the ## Patch section so prose elsewhere can't trip it.
+  const patchIdx = text.indexOf('## Patch');
+  if (patchIdx !== -1) {
+    const section = text.slice(patchIdx, patchIdx + 400);
+    if (/NO CHANGES\b/i.test(section)) {
+      return { diff: null, source: null, noChanges: true };
+    }
+  }
+
+  // Fenced ```diff … ``` (allow ```patch too; both are used in the wild).
+  const fenced = text.match(/```(?:diff|patch)\r?\n([\s\S]*?)\r?\n```/);
+  if (fenced && /^---[ \t]/m.test(fenced[1])) {
+    return { diff: normalize(fenced[1]), source: 'fenced', noChanges: false };
+  }
+
+  // Bare fallback: from the first `diff --git` or `--- ` header to the end.
+  const headerMatch = text.match(/^(?:diff --git |--- )/m);
+  if (headerMatch) {
+    const start = text.indexOf(headerMatch[0]);
+    let body = text.slice(start);
+    // Trim a trailing prose tail: keep up to the last line that looks like part
+    // of a patch (context/add/remove/header/hunk). Anything after is commentary.
+    const lines = body.split('\n');
+    let lastPatchLine = -1;
+    for (let i = 0; i < lines.length; i++) {
+      if (/^(?:diff --git |index |--- |\+\+\+ |@@ |[ +\-\\])/.test(lines[i]) || lines[i] === '') {
+        lastPatchLine = i;
+      } else if (lastPatchLine !== -1 && lines[i].trim() !== '') {
+        // a non-patch, non-blank line after we've seen patch content → stop
+        break;
+      }
+    }
+    if (lastPatchLine === -1) return { diff: null, source: null, noChanges: false };
+    body = lines.slice(0, lastPatchLine + 1).join('\n');
+    return { diff: normalize(body), source: 'bare', noChanges: false };
+  }
+
+  return { diff: null, source: null, noChanges: false };
+}
+
+/** A unified diff must end with exactly one trailing newline for `git apply`. */
+function normalize(diff) {
+  return diff.replace(/\s*$/, '') + '\n';
+}
+
+/**
+ * Interpret a `git apply --check` result into a verdict.
+ *
+ * @param {{ code: number, stderr: string }} result  from running git
+ * @returns {{ applies: boolean, verdict: 'clean'|'offset'|'failed', detail: string }}
+ */
+function interpretApplyCheck({ code, stderr }) {
+  const err = String(stderr || '');
+  if (code === 0) {
+    // `--check` succeeds even with fuzz; surface offsets as a softer signal
+    // because they mean the agent's line numbers drifted from the real file.
+    const offset = /offset \d+ line/i.test(err);
+    return {
+      applies: true,
+      verdict: offset ? 'offset' : 'clean',
+      detail: offset ? 'applies, but with line-number offset (context drift)' : 'applies cleanly',
+    };
+  }
+  // Extract the most useful line: git's "patch failed" / "does not apply" / etc.
+  const firstError = (err.split('\n').find(l => /error:|patch failed|does not apply/i.test(l)) || err.split('\n')[0] || '')
+    .replace(/^error:\s*/i, '')
+    .trim();
+  return {
+    applies: false,
+    verdict: 'failed',
+    detail: firstError || 'git apply --check reported failure',
+  };
+}
+
+module.exports = { extractDiff, interpretApplyCheck, normalize };

package/lib/pipeline-config.js

@@ -152,6 +152,213 @@ function readCIGateConfig(repoRoot) {
   return defaults;
 }
 
+// ── HC-019n-followup-28: E2E spec-generation mode ─────────────────────────────
+// step_3b (e2e-test-spec-writer) writes the Playwright specs. It was defined but
+// dormant (no activation path). This makes it an adopter preference, like ci.gate:
+//   auto  (default) → run step_3b when the story requires an E2E plan (step_0
+//                     emitted `Requires E2E Plan: yes`); skip otherwise.
+//   never           → never run step_3b (the original "manual E2E mode only").
+// A per-run --e2e-specs / --no-e2e-specs flag overrides the config (flag > config
+// > default), exactly the ci.gate precedence.
+const E2E_SPEC_MODES = ['auto', 'never'];
+const DEFAULT_E2E_SPEC_MODE = 'auto';
+
+/** Normalize an e2e.spec_generation value to a known mode, defaulting to auto. */
+function normalizeE2eSpecMode(v) {
+  const s = String(v == null ? '' : v).toLowerCase().trim();
+  return E2E_SPEC_MODES.includes(s) ? s : DEFAULT_E2E_SPEC_MODE;
+}
+
+/**
+ * Read the E2E spec-generation mode from .pipeline-config.yml's `e2e:` block.
+ * Same candidate order + graceful degradation as readCIGateConfig.
+ *
+ * @param {string} repoRoot
+ * @returns {'auto'|'never'} default 'auto' when config is missing/malformed.
+ */
+function readE2eSpecMode(repoRoot) {
+  if (!repoRoot || typeof repoRoot !== 'string') return DEFAULT_E2E_SPEC_MODE;
+
+  const candidates = [
+    path.join(repoRoot, '.pipeline-config.yml'),
+    path.join(repoRoot, '.github/.pipeline-config.yml'),
+  ];
+
+  for (const p of candidates) {
+    if (!fs.existsSync(p)) continue;
+    let raw;
+    try { raw = fs.readFileSync(p, 'utf8'); } catch { continue; }
+
+    let parsed;
+    try {
+      const yaml = require('js-yaml');
+      parsed = yaml.load(raw);
+    } catch { continue; }
+
+    if (!parsed || typeof parsed !== 'object') continue;
+    const block = parsed.e2e;
+    if (!block || typeof block !== 'object') continue; // try the next candidate
+    if (block.spec_generation === undefined) continue;
+    return normalizeE2eSpecMode(block.spec_generation);
+  }
+
+  return DEFAULT_E2E_SPEC_MODE;
+}
+
+// ── HC-019n-followup-34: closed-loop verification gate ────────────────────────
+// The CLI verbs (verify-patch/verify-pr) EXECUTE and report a verdict to the
+// server. `verification.gate` controls what the server does with it:
+//   advisory (default) → record the verdict, never change flow;
+//   enforce            → (follow-up) a red verdict blocks the run.
+// Mirrors ci.gate: adopter preference in .pipeline-config.yml, default-safe.
+const VERIFICATION_GATE_MODES = ['advisory', 'enforce'];
+const DEFAULT_VERIFICATION_GATE = 'advisory';
+
+/** Normalize a verification.gate value, defaulting to advisory. */
+function normalizeVerificationGate(v) {
+  const s = String(v == null ? '' : v).toLowerCase().trim();
+  return VERIFICATION_GATE_MODES.includes(s) ? s : DEFAULT_VERIFICATION_GATE;
+}
+
+/**
+ * Read the verification gate mode from .pipeline-config.yml's `verification:`
+ * block. Same candidate order + graceful degradation as readCIGateConfig.
+ *
+ * @param {string} repoRoot
+ * @returns {'advisory'|'enforce'} default 'advisory' when missing/malformed.
+ */
+function readVerificationGateConfig(repoRoot) {
+  if (!repoRoot || typeof repoRoot !== 'string') return DEFAULT_VERIFICATION_GATE;
+
+  const candidates = [
+    path.join(repoRoot, '.pipeline-config.yml'),
+    path.join(repoRoot, '.github/.pipeline-config.yml'),
+  ];
+
+  for (const p of candidates) {
+    if (!fs.existsSync(p)) continue;
+    let raw;
+    try { raw = fs.readFileSync(p, 'utf8'); } catch { continue; }
+
+    let parsed;
+    try {
+      const yaml = require('js-yaml');
+      parsed = yaml.load(raw);
+    } catch { continue; }
+
+    if (!parsed || typeof parsed !== 'object') continue;
+    const block = parsed.verification;
+    if (!block || typeof block !== 'object') continue;
+    if (block.gate === undefined) continue;
+    return normalizeVerificationGate(block.gate);
+  }
+
+  return DEFAULT_VERIFICATION_GATE;
+}
+
+// ── HC-COMM-011-followup-6: which verdict sources may DRIVE the step_4 gate ────
+// under enforce. Default: verify-patch only (the executed-test gate) — so enabling
+// enforce never silently lets agent-eval (which verifies BEHAVIOUR, not tests)
+// auto-advance the build. An adopter doing prompt-work opts agent-eval in.
+// verify-pr is not gate-eligible (step_5c has no gate) and is rejected here.
+const KNOWN_GATE_SOURCES = ['verify-patch', 'agent-eval'];
+const DEFAULT_GATE_SOURCES = ['verify-patch'];
+
+function normalizeGateSources(raw) {
+  if (!Array.isArray(raw)) {
+    console.warn(`[pipeline-config] verification.gate_sources must be a list; got ${typeof raw}, defaulting to ${DEFAULT_GATE_SOURCES.join(',')}`);
+    return [...DEFAULT_GATE_SOURCES];
+  }
+  const valid = [...new Set(raw.filter((s) => KNOWN_GATE_SOURCES.includes(s)))];
+  if (valid.length === 0) {
+    console.warn(`[pipeline-config] verification.gate_sources had no known source (allowed: ${KNOWN_GATE_SOURCES.join('|')}); defaulting to ${DEFAULT_GATE_SOURCES.join(',')}`);
+    return [...DEFAULT_GATE_SOURCES];
+  }
+  return valid;
+}
+
+/**
+ * Read verification.gate_sources from .pipeline-config.yml. Default-safe:
+ * ['verify-patch']. Any-of semantics — under enforce, any authorized source's
+ * green verdict advances step_4; any authorized source's red blocks.
+ * @returns {string[]}
+ */
+function readVerificationGateSources(repoRoot) {
+  if (!repoRoot || typeof repoRoot !== 'string') return [...DEFAULT_GATE_SOURCES];
+  const candidates = [
+    path.join(repoRoot, '.pipeline-config.yml'),
+    path.join(repoRoot, '.github/.pipeline-config.yml'),
+  ];
+  for (const p of candidates) {
+    if (!fs.existsSync(p)) continue;
+    let raw;
+    try { raw = fs.readFileSync(p, 'utf8'); } catch { continue; }
+    let parsed;
+    try { parsed = require('js-yaml').load(raw); } catch { continue; }
+    if (!parsed || typeof parsed !== 'object') continue;
+    const block = parsed.verification;
+    if (!block || typeof block !== 'object' || block.gate_sources === undefined) continue;
+    return normalizeGateSources(block.gate_sources);
+  }
+  return [...DEFAULT_GATE_SOURCES];
+}
+
+// ── HC-COMM-011-followup-1: Agent eval config reader ──────────────────────────
+/**
+ * Read agent eval targets from .pipeline-config.yml's `agent_eval:` block.
+ * Same candidate order + graceful degradation as readCIGateConfig.
+ * 
+ * @param {string} repoRoot
+ * @returns {{ targets: Array<{name, invoke: {command}}> }} default {targets: []}
+ */
+function readAgentEvalConfig(repoRoot) {
+  if (!repoRoot || typeof repoRoot !== 'string') return { targets: [] };
+
+  const candidates = [
+    path.join(repoRoot, '.pipeline-config.yml'),
+    path.join(repoRoot, '.github/.pipeline-config.yml'),
+  ];
+
+  for (const p of candidates) {
+    if (!fs.existsSync(p)) continue;
+    let raw;
+    try { raw = fs.readFileSync(p, 'utf8'); } catch { continue; }
+
+    let parsed;
+    try {
+      const yaml = require('js-yaml');
+      parsed = yaml.load(raw);
+    } catch { continue; }
+
+    if (!parsed || typeof parsed !== 'object') continue;
+    const block = parsed.agent_eval;
+    if (!block || typeof block !== 'object') continue;
+
+    const targets = [];
+    if (Array.isArray(block.targets)) {
+      for (const target of block.targets) {
+        if (!target || typeof target !== 'object') continue;
+        if (typeof target.name !== 'string' || !target.name.trim()) {
+          console.warn(`[agent-eval-config] target has no valid name, skipping`);
+          continue;
+        }
+        if (!target.invoke || typeof target.invoke !== 'object' || typeof target.invoke.command !== 'string' || !target.invoke.command.trim()) {
+          console.warn(`[agent-eval-config] target "${target.name}" has no valid invoke.command, skipping`);
+          continue;
+        }
+        targets.push({
+          name: target.name.trim(),
+          invoke: { command: target.invoke.command.trim() },
+        });
+      }
+    }
+
+    return { targets };
+  }
+
+  return { targets: [] };
+}
+
 module.exports = {
   readStoryClassifierConfig,
   KNOWN_THRESHOLD_KEYS,
@@ -160,4 +367,17 @@ module.exports = {
   CI_GATE_MODES,
   KNOWN_CI_GATE_KEYS,
   DEFAULT_CI_LOCAL_COMMAND,
+  readE2eSpecMode,
+  normalizeE2eSpecMode,
+  E2E_SPEC_MODES,
+  DEFAULT_E2E_SPEC_MODE,
+  readVerificationGateConfig,
+  normalizeVerificationGate,
+  VERIFICATION_GATE_MODES,
+  DEFAULT_VERIFICATION_GATE,
+  readVerificationGateSources,
+  normalizeGateSources,
+  KNOWN_GATE_SOURCES,
+  DEFAULT_GATE_SOURCES,
+  readAgentEvalConfig,
 };