openspecpm 0.1.0-alpha.0 → 1.0.1

package/cli/src/audit.js

@@ -9,17 +9,21 @@ export function auditPath(cwd = process.cwd()) {
   return join(cwd, DIR, FILE);
 }
 
-export async function record({ command, args = {}, result = null, error = null, cwd = process.cwd() } = {}) {
+export async function record({ command, args = {}, result = null, error = null, meta = null, cwd = process.cwd() } = {}) {
   if (!command) return;
   const path = auditPath(cwd);
   await mkdir(dirname(path), { recursive: true });
+  const errorText = error ? (typeof error === 'string' ? error : error.message ?? String(error)) : null;
   const entry = {
     ts: new Date().toISOString(),
     command,
     args: scrub(args),
-    result: result ? truncate(result, 500) : null,
-    error: error ? truncate(typeof error === 'string' ? error : error.message ?? String(error), 500) : null,
+    // result + error can carry user-supplied strings (e.g. a failing-fetch
+    // message containing a webhook URL). Run them through scrubValue too.
+    result: result ? truncate(scrubValue(String(result)), 500) : null,
+    error: errorText ? truncate(scrubValue(errorText), 500) : null,
   };
+  if (meta && typeof meta === 'object') entry.meta = scrub(meta);
   await appendFile(path, JSON.stringify(entry) + '\n', 'utf8');
 }
 
@@ -33,21 +37,49 @@ export async function tail(n = 50, cwd = process.cwd()) {
   });
 }
 
-const SECRET_KEYS = /token|secret|password|pat|api[_-]?key|auth|credential/i;
+const SECRET_SEGMENTS = new Set([
+  // Original set.
+  'token', 'secret', 'password', 'pat', 'auth', 'credential',
+  // Added: real-world key naming a CLI accumulates over time.
+  // bearer/cookie/session — bearer credentials by name.
+  // webhook — Slack/Teams URLs ARE the credential.
+  // signature — webhook HMAC sigs, request-signing headers.
+  // assertion — SAML / OIDC.
+  'bearer', 'cookie', 'session', 'webhook', 'signature', 'assertion',
+]);
+
+// Webhook URLs that act as bearer credentials. Anyone holding the URL can
+// post to the channel. Redact in any string value so accidental logging
+// (e.g. a failing-fetch error message embedding the URL) never leaks.
+const WEBHOOK_URL_RE = /https:\/\/(?:hooks\.slack\.com\/services|[^\/\s"'`]*\.webhook\.office(?:365)?\.com|outlook\.office(?:365)?\.com\/webhook)[^\s"'`]+/gi;
+
+function isSecretKey(k) {
+  if (/api[_-]?key/i.test(k)) return true;
+  for (const seg of k.toLowerCase().split(/[^a-z]+/)) {
+    if (seg && SECRET_SEGMENTS.has(seg)) return true;
+  }
+  return false;
+}
+
+function scrubValue(s) {
+  if (typeof s !== 'string') return s;
+  return s.replace(WEBHOOK_URL_RE, '<redacted-webhook>');
+}
 
 function scrub(obj) {
+  if (typeof obj === 'string') return scrubValue(obj);
   if (!obj || typeof obj !== 'object') return obj;
   if (Array.isArray(obj)) return obj.map(scrub);
   const out = {};
   for (const [k, v] of Object.entries(obj)) {
-    if (SECRET_KEYS.test(k)) {
+    if (isSecretKey(k)) {
       out[k] = '<redacted>';
     } else if (v && typeof v === 'object') {
       out[k] = scrub(v);
     } else if (typeof v === 'string' && v.length > 200) {
-      out[k] = v.slice(0, 200) + '…';
+      out[k] = scrubValue(v).slice(0, 200) + '…';
     } else {
-      out[k] = v;
+      out[k] = scrubValue(v);
     }
   }
   return out;

package/cli/src/bdd/judge.js

@@ -0,0 +1,216 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const DEFAULT_MODEL = 'claude-haiku-4-5';
+export const DEFAULT_MAX_FINDINGS_PER_SPEC = 8;
+const MAX_CONCURRENT = 5;
+
+const ALLOWED_RULES = new Set([
+  'bdd/llm-contradiction',
+  'bdd/llm-missing-coverage',
+  'bdd/llm-vague-then',
+]);
+
+const ALLOWED_SEVERITY = new Set(['error', 'warning']);
+
+const REPORT_TOOL = {
+  name: 'report_findings',
+  description:
+    'Report BDD scenario findings as a structured list. Each finding flags a specific defect that the heuristic linter cannot catch: cross-spec contradictions, missing coverage against success criteria, or vague Then predicates that pass regex checks but state no observable outcome.',
+  input_schema: {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+      findings: {
+        type: 'array',
+        items: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            severity: { type: 'string', enum: ['error', 'warning'] },
+            line: { type: 'integer', minimum: 1 },
+            scenario: { type: 'string' },
+            rule: {
+              type: 'string',
+              enum: ['bdd/llm-contradiction', 'bdd/llm-missing-coverage', 'bdd/llm-vague-then'],
+            },
+            message: { type: 'string' },
+          },
+          required: ['severity', 'scenario', 'rule', 'message'],
+        },
+      },
+    },
+    required: ['findings'],
+  },
+};
+
+const SYSTEM_PROMPT = `You are a BDD scenario reviewer. You augment a heuristic linter by catching defects it cannot see: cross-spec contradictions, missing coverage of declared success criteria, and Then predicates that state no observable outcome. You are reviewing one spec file at a time, with the full feature proposal as context.
+
+Rules:
+- Use the report_findings tool exactly once.
+- Only emit findings for the three rules: bdd/llm-contradiction, bdd/llm-missing-coverage, bdd/llm-vague-then.
+- Each finding must name the specific scenario by title and include the line number where the issue appears.
+- bdd/llm-contradiction: a scenario contradicts another scenario in the same file or another spec referenced in the proposal.
+- bdd/llm-missing-coverage: the proposal's success criteria contain a requirement with no scenario covering it.
+- bdd/llm-vague-then: a Then predicate uses an observable verb but its outcome is not actually checkable (e.g. "Then the user receives confirmation" with no detail on what confirmation).
+- Severity error for contradictions and uncovered hard requirements; severity warning for vague Thens and uncovered nice-to-haves.
+- Empty findings array is the correct output when the spec is clean.
+- Never invent rule names. Never include findings outside the three rules above.`;
+
+export async function judgeChange(featureDir, opts = {}) {
+  const {
+    client,
+    model = DEFAULT_MODEL,
+    proposal = '',
+    maxFindingsPerSpec = DEFAULT_MAX_FINDINGS_PER_SPEC,
+    onUsage,
+  } = opts;
+
+  if (!client) throw new Error('judge: client is required');
+
+  const specsDir = join(featureDir, 'specs');
+  if (!existsSync(specsDir)) return [];
+
+  const files = (await readdir(specsDir)).filter((f) => f.endsWith('.md'));
+  if (!files.length) return [];
+
+  const tasks = files.map((f) => () =>
+    judgeSpec(join(specsDir, f), { client, model, proposal, maxFindingsPerSpec, onUsage }),
+  );
+
+  const results = await runBounded(tasks, MAX_CONCURRENT);
+  return results.flat();
+}
+
+async function judgeSpec(file, { client, model, proposal, maxFindingsPerSpec, onUsage }) {
+  let specSource;
+  try {
+    specSource = await readFile(file, 'utf8');
+  } catch (err) {
+    return [{
+      severity: 'warning',
+      file,
+      line: 1,
+      scenario: '(read failed)',
+      rule: 'bdd/llm-parse-error',
+      message: `Could not read spec file: ${err.message}`,
+    }];
+  }
+
+  const userPrompt = `Review the following BDD spec file. Use report_findings to report up to ${maxFindingsPerSpec} findings.
+
+<spec file="${file}">
+${specSource}
+</spec>`;
+
+  let response;
+  try {
+    response = await client.messages.create({
+      model,
+      max_tokens: 4096,
+      tools: [REPORT_TOOL],
+      tool_choice: { type: 'tool', name: 'report_findings' },
+      system: [
+        {
+          type: 'text',
+          text: SYSTEM_PROMPT,
+        },
+        {
+          type: 'text',
+          text: `Feature proposal (shared context across every spec in this feature):\n\n${proposal || '(no proposal.md available)'}`,
+          cache_control: { type: 'ephemeral' },
+        },
+      ],
+      messages: [{ role: 'user', content: userPrompt }],
+    });
+  } catch (err) {
+    return [{
+      severity: 'warning',
+      file,
+      line: 1,
+      scenario: '(judge failed)',
+      rule: 'bdd/llm-parse-error',
+      message: `LLM judge call failed: ${err.message}`,
+    }];
+  }
+
+  if (onUsage && response?.usage) {
+    try {
+      onUsage({
+        file,
+        model,
+        input_tokens: response.usage.input_tokens ?? 0,
+        output_tokens: response.usage.output_tokens ?? 0,
+        cache_creation_input_tokens: response.usage.cache_creation_input_tokens ?? 0,
+        cache_read_input_tokens: response.usage.cache_read_input_tokens ?? 0,
+      });
+    } catch { /* never break the judge on telemetry */ }
+  }
+
+  return extractFindings(response, file);
+}
+
+function extractFindings(response, file) {
+  const toolUse = (response?.content ?? []).find(
+    (b) => b.type === 'tool_use' && b.name === 'report_findings',
+  );
+  if (!toolUse) {
+    return [{
+      severity: 'warning',
+      file,
+      line: 1,
+      scenario: '(no findings reported)',
+      rule: 'bdd/llm-parse-error',
+      message: 'LLM did not call report_findings tool.',
+    }];
+  }
+  const raw = toolUse.input?.findings;
+  if (!Array.isArray(raw)) {
+    return [{
+      severity: 'warning',
+      file,
+      line: 1,
+      scenario: '(malformed response)',
+      rule: 'bdd/llm-parse-error',
+      message: 'report_findings input was not a findings array.',
+    }];
+  }
+  const out = [];
+  for (const f of raw) {
+    if (!f || typeof f !== 'object') continue;
+    if (!ALLOWED_RULES.has(f.rule)) continue;
+    if (!ALLOWED_SEVERITY.has(f.severity)) continue;
+    if (typeof f.scenario !== 'string' || !f.scenario) continue;
+    if (typeof f.message !== 'string' || !f.message) continue;
+    out.push({
+      severity: f.severity,
+      file,
+      line: Number.isInteger(f.line) && f.line > 0 ? f.line : undefined,
+      scenario: f.scenario,
+      rule: f.rule,
+      message: f.message,
+    });
+  }
+  return out;
+}
+
+async function runBounded(tasks, limit) {
+  const results = new Array(tasks.length);
+  let i = 0;
+  const workers = new Array(Math.min(limit, tasks.length)).fill(0).map(async () => {
+    while (true) {
+      const idx = i++;
+      if (idx >= tasks.length) return;
+      results[idx] = await tasks[idx]();
+    }
+  });
+  await Promise.all(workers);
+  return results;
+}
+
+export function defaultClient() {
+  return import('@anthropic-ai/sdk').then(({ default: Anthropic }) => {
+    return new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
+  });
+}

package/cli/src/commands/bulk.js

@@ -31,6 +31,11 @@ export async function runSyncAll({ dryRun = false, force = false, yes = false }
     }
   }
   process.stdout.write(`\nSummary: ${synced} synced, ${failed} failed.\n`);
+  if (failed > 0) {
+    const err = new Error(`${failed} change(s) failed to sync.`);
+    err.remediation = 'See per-change errors above; re-run for affected features after fixing.';
+    throw err;
+  }
 }
 
 export async function runShipAllReady({ yes = false, skipArchive = false } = {}) {
@@ -64,4 +69,9 @@ export async function runShipAllReady({ yes = false, skipArchive = false } = {})
     }
   }
   process.stdout.write(`\nSummary: ${shipped} shipped, ${failed} failed.\n`);
+  if (failed > 0) {
+    const err = new Error(`${failed} change(s) failed to ship.`);
+    err.remediation = 'See per-change errors above; re-run for affected features after fixing.';
+    throw err;
+  }
 }

package/cli/src/commands/doctor.js

@@ -33,6 +33,17 @@ export async function runDoctor({ adapter, install = false, setupAuth = false }
     if (install) suggestAdapterInstall(name);
     if (setupAuth) suggestAuth(name);
   }
+
+  process.stdout.write('\n[judge]\n');
+  if (process.env.ANTHROPIC_API_KEY) {
+    line(true, 'ANTHROPIC_API_KEY is set (LLM BDD judge available)');
+  } else {
+    line(
+      false,
+      'ANTHROPIC_API_KEY not set',
+      'Create a key at https://console.anthropic.com/settings/keys, then set ANTHROPIC_API_KEY in your shell. Required for `openspecpm propose --llm` and `sync --llm`.',
+    );
+  }
 }
 
 function line(ok, msg, remediation) {

package/cli/src/commands/propose.js

@@ -1,11 +1,14 @@
-import { mkdir, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { propose, changeExists, changeDir, OpenSpecError } from '../openspec-bridge.js';
 import { lintChange, summarize, formatFindings } from '../bdd/linter.js';
+import { judgeChange, defaultClient, DEFAULT_MODEL } from '../bdd/judge.js';
 import { CHANGE_TYPES, proposalTemplate, specsTemplate, STARTER_TASKS } from '../bdd/templates.js';
+import { readConfig } from '../config.js';
+import { record } from '../audit.js';
 
-export async function runPropose({ feature, prompt, type = 'feature', offline = false } = {}) {
+export async function runPropose({ feature, prompt, type = 'feature', offline = false, llm = false } = {}) {
   if (!feature) throw new Error('feature name is required');
   if (!CHANGE_TYPES.includes(type)) {
     const err = new Error(`Unknown change type "${type}".`);
@@ -15,14 +18,14 @@ export async function runPropose({ feature, prompt, type = 'feature', offline =
 
   if (changeExists(feature)) {
     process.stdout.write(`Change "${feature}" already exists at ${changeDir(feature)}. Skipping propose.\n`);
-    await softLint(changeDir(feature));
+    await softLint(changeDir(feature), { llm, feature });
     return changeDir(feature);
   }
 
   if (offline) {
     const dir = await scaffoldOffline(feature, type);
     process.stdout.write(`\nProposal scaffolded offline at ${dir} (type=${type}).\n`);
-    await softLint(dir);
+    await softLint(dir, { llm, feature });
     process.stdout.write(`Next: refine the templates, then run \`openspecpm sync ${feature}\`.\n`);
     return dir;
   }
@@ -31,7 +34,7 @@ export async function runPropose({ feature, prompt, type = 'feature', offline =
   try {
     const dir = await propose(feature, seed);
     process.stdout.write(`\nProposal created at ${dir}.\n`);
-    await softLint(dir);
+    await softLint(dir, { llm, feature });
     process.stdout.write(`Next: review proposal.md + specs/, then run \`openspecpm sync ${feature}\`.\n`);
     return dir;
   } catch (err) {
@@ -57,11 +60,43 @@ async function scaffoldOffline(feature, type) {
   return dir;
 }
 
-async function softLint(dir) { // eslint-disable-line
+async function softLint(dir, { llm = false, feature } = {}) { // eslint-disable-line
   const findings = await lintChange(dir);
+  const judgeEnabled = await isJudgeEnabled(llm);
+  if (judgeEnabled) {
+    const extra = await runJudgeSoft(dir, feature);
+    findings.push(...extra);
+  }
   const sum = summarize(findings);
   if (!sum.total) return;
   process.stdout.write(`\nBDD lint (soft): ${sum.errors} errors, ${sum.warnings} warnings\n`);
   process.stdout.write(formatFindings(findings));
   process.stdout.write('These will block `sync` unless you pass --force. Refine scenarios before pushing.\n');
 }
+
+async function isJudgeEnabled(llm) {
+  if (llm) return true;
+  const cfg = await readConfig();
+  return Boolean(cfg?.judge?.enabled);
+}
+
+async function runJudgeSoft(dir, feature) {
+  try {
+    const cfg = await readConfig();
+    const model = cfg?.judge?.model ?? DEFAULT_MODEL;
+    const proposalPath = join(dir, 'proposal.md');
+    const proposal = existsSync(proposalPath) ? await readFile(proposalPath, 'utf8') : '';
+    const client = await defaultClient();
+    return await judgeChange(dir, {
+      client,
+      model,
+      proposal,
+      onUsage: (u) => {
+        record({ command: 'judge', args: { feature }, meta: u }).catch(() => {});
+      },
+    });
+  } catch (err) {
+    process.stdout.write(`  (LLM judge skipped: ${err.message})\n`);
+    return [];
+  }
+}

package/cli/src/commands/reconcile.js

@@ -4,6 +4,7 @@ import { readConfig } from '../config.js';
 import { loadAdapter } from '../adapters/index.js';
 import { changeDir, changeExists } from '../openspec-bridge.js';
 import * as fm from '../frontmatter.js';
+import { coerceItems, safeParseFrontmatter } from '../tracking.js';
 
 export async function runReconcile({ feature, dryRun = false } = {}) {
   if (!feature) throw new Error('feature name is required');
@@ -17,10 +18,22 @@ export async function runReconcile({ feature, dryRun = false } = {}) {
 
   const dir = changeDir(feature);
   const tasksPath = join(dir, 'tasks.md');
-  let tasksRaw = '';
-  try { tasksRaw = await readFile(tasksPath, 'utf8'); } catch { /* missing */ }
-  const { data: tdata, body: tbody } = fm.parse(tasksRaw);
-  const items = tdata.items ?? [];
+  // Read + validate through the same helpers loadChange uses, so a non-array
+  // items: (or malformed YAML) raises a clear error instead of iterating
+  // character-by-character.
+  let tdata = {};
+  let tbody = '';
+  try {
+    ({ data: tdata, body: tbody } = await safeParseFrontmatter(tasksPath, feature, 'tasks.md'));
+  } catch (err) {
+    if (err.code === 'ENOENT' || /no such file/i.test(err.message)) {
+      // tasks.md missing — nothing to reconcile.
+      process.stdout.write('No items in tasks.md to reconcile.\n');
+      return;
+    }
+    throw err;
+  }
+  const items = coerceItems(tdata.items, tbody, feature);
   if (!items.length) {
     process.stdout.write('No items in tasks.md to reconcile.\n');
     return;

package/cli/src/commands/sync.js

@@ -5,9 +5,12 @@ import { readConfig } from '../config.js';
 import { loadAdapter } from '../adapters/index.js';
 import { changeDir, changeExists } from '../openspec-bridge.js';
 import { lintChange, summarize, formatFindings } from '../bdd/linter.js';
+import { judgeChange, defaultClient, DEFAULT_MODEL } from '../bdd/judge.js';
 import * as fm from '../frontmatter.js';
+import { coerceItems, safeParseFrontmatter } from '../tracking.js';
+import { record } from '../audit.js';
 
-export async function runSync({ feature, dryRun = false, force = false, diff = false } = {}) {
+export async function runSync({ feature, dryRun = false, force = false, diff = false, llm = false } = {}) {
   if (!feature) throw new Error('feature name is required');
   const config = await readConfig();
   if (!config) {
@@ -23,6 +26,30 @@ export async function runSync({ feature, dryRun = false, force = false, diff = f
 
   const dir = changeDir(feature);
   const findings = await lintChange(dir);
+  if (llm || config?.judge?.enabled) {
+    try {
+      const model = config?.judge?.model ?? DEFAULT_MODEL;
+      const proposalPath = join(dir, 'proposal.md');
+      const proposalForJudge = existsSync(proposalPath) ? await readFile(proposalPath, 'utf8') : '';
+      const client = await defaultClient();
+      const judgeFindings = await judgeChange(dir, {
+        client,
+        model,
+        proposal: proposalForJudge,
+        onUsage: (u) => {
+          record({ command: 'judge', args: { feature }, meta: u }).catch(() => {});
+        },
+      });
+      findings.push(...judgeFindings);
+    } catch (err) {
+      if (!force) {
+        const e = new Error(`LLM judge failed: ${err.message}`);
+        e.remediation = 'Run `openspecpm doctor` to check ANTHROPIC_API_KEY, or pass --force to skip the LLM judge.';
+        throw e;
+      }
+      process.stdout.write(`  (LLM judge skipped under --force: ${err.message})\n`);
+    }
+  }
   const sum = summarize(findings);
   if (sum.errors > 0 && !force) {
     process.stderr.write(`BDD lint: ${sum.errors} errors, ${sum.warnings} warnings\n`);
@@ -76,9 +103,11 @@ export async function runSync({ feature, dryRun = false, force = false, diff = f
     out('No tasks.md found — only the epic was synced.');
     return;
   }
-  const tasksRaw = await readFile(tasksPath, 'utf8');
-  const { data: tdata, body: tbody } = fm.parse(tasksRaw);
-  const items = tdata.items ?? parseChecklist(tbody);
+  // Route through the same parse+coerce helpers loadChange uses, so a
+  // non-array items: (or malformed YAML) is rejected here too — sync is the
+  // primary command and bypassing the validator was the H3 regression.
+  const { data: tdata, body: tbody } = await safeParseFrontmatter(tasksPath, feature, 'tasks.md');
+  const items = coerceItems(tdata.items, tbody, feature);
   const updatedItems = [];
 
   for (const task of items) {
@@ -106,16 +135,52 @@ export async function runSync({ feature, dryRun = false, force = false, diff = f
     const patched = fm.serialize({ ...tdata, items: updatedItems }, tbody);
     await writeFile(tasksPath, patched, 'utf8');
   }
+
+  // Exit with a non-zero status if any task failed, so CI invocations like
+  // `openspecpm sync feature && deploy` don't proceed on silent partial sync.
+  // The tasks.md patch above already persisted last_error per failed task.
+  const failed = updatedItems.filter((t) => t.sync_state === 'failed');
+  if (failed.length) {
+    const err = new Error(`${failed.length} task(s) failed to sync in "${feature}".`);
+    err.remediation = 'Inspect last_error in tasks.md frontmatter and re-run sync to retry only failed items.';
+    throw err;
+  }
 }
 
 function out(s) {
   process.stdout.write(s + '\n');
 }
 
+// Strip C0/C1 control chars (except common whitespace), bidi overrides, and
+// zero-width chars from text we forward to a remote tracker as an issue body.
+// A proposal author could intentionally or accidentally include these and
+// they show up confusingly (or as homograph-attack vectors) in GitHub/Jira
+// issue UIs. Implemented as a codepoint predicate rather than a regex literal
+// so the source file stays pure ASCII (a regex with literal control chars
+// makes git treat the file as binary).
+function isPrintableChar(cp) {
+  if (cp === 0x09 || cp === 0x0A || cp === 0x0D) return true; // keep TAB / LF / CR
+  if (cp <= 0x1F) return false;                                // C0 controls
+  if (cp === 0x7F) return false;                               // DEL
+  if (cp >= 0x80 && cp <= 0x9F) return false;                  // C1 controls
+  if (cp >= 0x200B && cp <= 0x200F) return false;              // zero-width + joiners + LRM/RLM
+  if (cp >= 0x202A && cp <= 0x202E) return false;              // LRE/RLE/PDF/LRO/RLO bidi overrides
+  if (cp >= 0x2066 && cp <= 0x2069) return false;              // LRI/RLI/FSI/PDI isolates
+  return true;
+}
+
+function sanitizeText(s) {
+  const out = [];
+  for (const ch of String(s)) {
+    if (isPrintableChar(ch.codePointAt(0))) out.push(ch);
+  }
+  return out.join('');
+}
+
 function extractSummary(md) {
   const { body } = fm.parse(md);
   const firstPara = body.split(/\r?\n\r?\n/).find((p) => p.trim() && !p.startsWith('#'));
-  return (firstPara ?? '').trim().slice(0, 1000);
+  return sanitizeText((firstPara ?? '').trim()).slice(0, 1000);
 }
 
 function parseChecklist(body) {

package/cli/src/commands/validate.js

@@ -1,13 +1,21 @@
 import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { listChanges } from '../tracking.js';
 import { lintChange, summarize } from '../bdd/linter.js';
+import { judgeChange, defaultClient, DEFAULT_MODEL } from '../bdd/judge.js';
+import { readConfig } from '../config.js';
+import { record } from '../audit.js';
 
 const REQUIRED_PROPOSAL = ['name'];
 const TASK_STATES = ['pending', 'created', 'failed'];
 
-export async function runValidate() {
+export async function runValidate({ llm = false } = {}) {
   const changes = await listChanges();
+  const config = await readConfig();
+  const judgeEnabled = llm || Boolean(config?.judge?.enabled);
+  const model = config?.judge?.model ?? DEFAULT_MODEL;
+  const client = judgeEnabled ? await defaultClient().catch(() => null) : null;
   out(`openspecpm validate — ${changes.length} change(s)\n`);
   let totalIssues = 0;
 
@@ -52,6 +60,29 @@ export async function runValidate() {
 
     // BDD lint
     const findings = await lintChange(change.dir);
+    if (judgeEnabled && client) {
+      try {
+        const proposalPath = join(change.dir, 'proposal.md');
+        const proposal = existsSync(proposalPath) ? await readFile(proposalPath, 'utf8') : '';
+        const judgeFindings = await judgeChange(change.dir, {
+          client,
+          model,
+          proposal,
+          onUsage: (u) => {
+            record({ command: 'judge', args: { feature: change.name }, meta: u }).catch(() => {});
+          },
+        });
+        findings.push(...judgeFindings);
+      } catch (err) {
+        findings.push({
+          severity: 'warning',
+          file: change.dir,
+          scenario: '(judge failed)',
+          rule: 'bdd/llm-parse-error',
+          message: `LLM judge failed: ${err.message}`,
+        });
+      }
+    }
     const { errors, warnings } = summarize(findings);
 
     const total = issues.length + errors;

package/cli/src/http.js

@@ -1,13 +1,16 @@
 import { AdapterError } from './adapters/base.js';
 
+const DEFAULT_TIMEOUT_MS = 30_000;
+
 export class HttpClient {
   #baseUrl;
   #authHeader;
   #fetchImpl;
   #defaultHeaders;
   #remediationHint;
+  #timeoutMs;
 
-  constructor({ baseUrl, auth, fetch: fetchImpl = globalThis.fetch, defaultHeaders = {}, remediationHint } = {}) {
+  constructor({ baseUrl, auth, fetch: fetchImpl = globalThis.fetch, defaultHeaders = {}, remediationHint, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
     if (!baseUrl) throw new Error('HttpClient requires baseUrl');
     if (typeof fetchImpl !== 'function') throw new Error('global fetch not available; pass {fetch} explicitly');
     this.#baseUrl = baseUrl.replace(/\/+$/, '');
@@ -15,6 +18,7 @@ export class HttpClient {
     this.#fetchImpl = fetchImpl;
     this.#defaultHeaders = defaultHeaders;
     this.#remediationHint = remediationHint;
+    this.#timeoutMs = timeoutMs;
   }
 
   async request(method, path, { query, body, headers, contentType = 'application/json', accept = 'application/json' } = {}) {
@@ -35,10 +39,18 @@ export class HttpClient {
       finalHeaders['Content-Type'] = contentType;
     }
 
+    // Bound the request with an abort signal so a hung backend can't wedge sync --all.
+    const signal = AbortSignal.timeout(this.#timeoutMs);
     let res;
     try {
-      res = await this.#fetchImpl(url, { method, headers: finalHeaders, body: payload });
+      res = await this.#fetchImpl(url, { method, headers: finalHeaders, body: payload, signal });
     } catch (err) {
+      if (err?.name === 'TimeoutError' || err?.name === 'AbortError') {
+        throw new AdapterError(`${method} ${url} timed out after ${this.#timeoutMs}ms`, {
+          remediation: 'Backend did not respond in time. Retry, or raise HttpClient timeoutMs if the endpoint is known-slow.',
+          cause: err,
+        });
+      }
       throw new AdapterError(`Network error calling ${method} ${url}: ${err.message}`, {
         remediation: this.#remediationHint ?? 'Check connectivity and base URL.',
         cause: err,