@hone-ai/cli 1.9.0 → 1.11.0

package/lib/compare-reviews.js

@@ -0,0 +1,279 @@
+'use strict';
+/**
+ * compare-reviews.js — HC-080a-spike side-by-side comparison helper.
+ *
+ * Reads two release-review JSON artifacts (Opus + GH Models GPT-4.1) and
+ * prints a markdown comparison table that can be pasted into the decision
+ * record in docs/architecture/release-review-llm-provider-decision.md.
+ *
+ * Usage:
+ *   node cli/lib/compare-reviews.js <opus-findings.json> <gh-models-findings.json>
+ *
+ * Both files should be JSON envelopes produced by `hone release-review --format json`
+ * (see cli/hone-cli.js release-review handler — both providers emit the same
+ * envelope shape).
+ *
+ * The script is intentionally tolerant of partial/raw outputs: if a provider
+ * returned a non-JSON response, the comparison still shows what's there and
+ * flags the format problem in the rubric.
+ *
+ * Exit codes:
+ *   0 — both files parsed, comparison printed
+ *   1 — missing file, invalid JSON, or other unrecoverable error
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ── helpers ────────────────────────────────────────────────────────────────
+
+// Normalize file paths for cross-provider equality. Strips leading "./",
+// converts backslashes, and removes duplicate separators. Coarse: does NOT
+// resolve symlinks, just compares string-equivalent paths.
+function normalizePath(p) {
+  if (typeof p !== 'string') return '';
+  let n = p.replace(/\\/g, '/').replace(/^\.\//, '').trim();
+  // collapse repeated slashes but preserve leading slash
+  n = n.replace(/\/+/g, '/');
+  return n;
+}
+
+// Escape a string for safe interpolation into a markdown table cell or bullet.
+// Replaces pipes (`|` — breaks table column count), backticks (corrupt code
+// spans), and newlines (break bullet lines). Backticks are removed (rather
+// than backslash-escaped) because backslash-escapes inside code spans are NOT
+// honored by CommonMark — replacing with a similar-looking char preserves
+// rendering. This is defense against LLM-emitted content that may contain
+// any of these chars in `issue` / `file` strings.
+function escapeMd(s) {
+  if (s == null) return '';
+  return String(s)
+    .replace(/\|/g, '\\|')
+    .replace(/`/g, '‘')      // ` → left single quote (visually close)
+    .replace(/\r?\n/g, ' ');      // newlines → spaces inside a cell
+}
+
+function loadEnvelope(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return { error: `file not found: ${filePath}` };
+  }
+  const raw = fs.readFileSync(filePath, 'utf8');
+  try {
+    return JSON.parse(raw);
+  } catch (e) {
+    return { error: `JSON parse failed: ${e.message}`, raw };
+  }
+}
+
+function bucketSeverity(findings) {
+  const buckets = { CRITICAL: 0, HIGH: 0, MEDIUM: 0, LOW: 0, OTHER: 0 };
+  if (!Array.isArray(findings)) return buckets;
+  for (const f of findings) {
+    const sev = String(f.severity || '').toUpperCase();
+    if (sev in buckets) buckets[sev]++;
+    else buckets.OTHER++;
+  }
+  return buckets;
+}
+
+function describe(env) {
+  if (env.error) {
+    return {
+      ok: false,
+      error: env.error,
+      status: 'unparseable',
+      provider: 'unknown',
+      model: 'unknown',
+      counts: bucketSeverity([]),
+      totalFindings: 0,
+      cost: { inputTokens: 0, outputTokens: 0 },
+      elapsedMs: null,
+      recommendation: 'n/a',
+      formatOk: false,
+    };
+  }
+  const findings = Array.isArray(env.findings) ? env.findings : [];
+  const counts = bucketSeverity(findings);
+  // `status` field (added by HC-080a-spike fix pass) tells operators whether
+  // this row is a real review, a known error envelope, or an unknown shape.
+  // Status values produced by the CLI: 'reviewed' | 'no_changes' |
+  // 'empty_response' | 'auth_error' | 'rate_limited' | 'http_error'.
+  // Default to 'reviewed' if absent so older artifacts still display.
+  const status = env.status || (findings.length > 0 ? 'reviewed' : 'unknown');
+  return {
+    ok: true,
+    status,
+    provider: env.provider || 'unknown',
+    model: env.model || 'unknown',
+    counts,
+    totalFindings: findings.length,
+    cost: {
+      inputTokens: env.inputTokens || 0,
+      outputTokens: env.outputTokens || 0,
+    },
+    elapsedMs: typeof env.elapsedMs === 'number' ? env.elapsedMs : null,
+    recommendation: env.recommendation || (env.raw ? 'raw-output' : 'n/a'),
+    formatOk: !env.raw,
+    summary: env.summary || null,
+    findings,
+    httpStatus: env.httpStatus ?? null,
+    errorMessage: env.errorMessage || null,
+  };
+}
+
+// ── Findings overlap detection ────────────────────────────────────────────
+//
+// Two findings are considered the "same" bug if they reference the same
+// normalized file path AND both have explicit line numbers within ±3 of each
+// other. Findings without explicit line numbers are NOT auto-merged — two
+// unrelated file-level findings on the same file would otherwise collapse
+// into a false overlap.
+//
+// This is coarse — a precise match would require semantic similarity scoring,
+// which is overkill for a 5-release spike. The output is meant to anchor
+// manual review, not auto-decide.
+function findOverlap(aFindings, bFindings) {
+  const overlap = [];
+  const aOnly = [];
+  const bUsed = new Set();
+
+  for (const a of aFindings) {
+    let matched = false;
+    const aFile = normalizePath(a.file);
+    const aLine = Number.isFinite(a.line) ? a.line : null;
+    for (let i = 0; i < bFindings.length; i++) {
+      if (bUsed.has(i)) continue;
+      const b = bFindings[i];
+      const bFile = normalizePath(b.file);
+      const bLine = Number.isFinite(b.line) ? b.line : null;
+      if (aFile !== bFile || aFile === '') continue;
+      // Require both lines to be explicit AND nearby. Two undefined lines
+      // do NOT count as a match — they're treated as distinct file-level
+      // findings until a human merges them manually in the rubric.
+      if (aLine === null || bLine === null) continue;
+      if (Math.abs(aLine - bLine) > 3) continue;
+      overlap.push({ a, b });
+      bUsed.add(i);
+      matched = true;
+      break;
+    }
+    if (!matched) aOnly.push(a);
+  }
+  const bOnly = bFindings.filter((_, i) => !bUsed.has(i));
+  return { overlap, aOnly, bOnly };
+}
+
+function renderMarkdown(opus, gh) {
+  const lines = [];
+  lines.push('# Release-Review Provider Comparison (HC-080a-spike)');
+  lines.push('');
+  lines.push(`_Generated: ${new Date().toISOString()}_`);
+  lines.push('');
+
+  lines.push('## Summary');
+  lines.push('');
+  lines.push('| Dimension | Opus (Anthropic) | GPT-4.1 (GitHub Models) |');
+  lines.push('|---|---|---|');
+  lines.push(`| Provider | ${opus.provider} | ${gh.provider} |`);
+  lines.push(`| Status | ${opus.status} | ${gh.status} |`);
+  lines.push(`| Model | ${opus.model} | ${gh.model} |`);
+  lines.push(`| Format OK | ${opus.formatOk ? 'yes' : 'NO (raw)'} | ${gh.formatOk ? 'yes' : 'NO (raw)'} |`);
+  lines.push(`| Latency (ms) | ${opus.elapsedMs ?? 'n/a'} | ${gh.elapsedMs ?? 'n/a'} |`);
+  lines.push(`| Input tokens | ${opus.cost.inputTokens} | ${gh.cost.inputTokens} |`);
+  lines.push(`| Output tokens | ${opus.cost.outputTokens} | ${gh.cost.outputTokens} |`);
+  lines.push(`| Total findings | ${opus.totalFindings} | ${gh.totalFindings} |`);
+  lines.push(`| Findings: CRITICAL | ${opus.counts.CRITICAL} | ${gh.counts.CRITICAL} |`);
+  lines.push(`| Findings: HIGH | ${opus.counts.HIGH} | ${gh.counts.HIGH} |`);
+  lines.push(`| Findings: MEDIUM | ${opus.counts.MEDIUM} | ${gh.counts.MEDIUM} |`);
+  lines.push(`| Findings: LOW | ${opus.counts.LOW} | ${gh.counts.LOW} |`);
+  lines.push(`| Recommendation | ${opus.recommendation} | ${gh.recommendation} |`);
+  lines.push('');
+
+  if (!opus.ok || !gh.ok) {
+    lines.push('## Errors');
+    lines.push('');
+    if (!opus.ok) lines.push(`- Opus envelope: ${opus.error}`);
+    if (!gh.ok)   lines.push(`- GH Models envelope: ${gh.error}`);
+    lines.push('');
+    return lines.join('\n');
+  }
+
+  const { overlap, aOnly: opusOnly, bOnly: ghOnly } = findOverlap(opus.findings, gh.findings);
+
+  lines.push('## Overlap analysis (coarse: same file + line ±3)');
+  lines.push('');
+  lines.push(`- Shared findings (both providers caught): ${overlap.length}`);
+  lines.push(`- Opus-only findings: ${opusOnly.length}`);
+  lines.push(`- GH Models-only findings: ${ghOnly.length}`);
+  lines.push('');
+
+  if (overlap.length) {
+    lines.push('### Shared findings (sample, up to 5)');
+    lines.push('');
+    for (const { a, b } of overlap.slice(0, 5)) {
+      lines.push(`- **${escapeMd(a.file)}:${a.line}** — Opus says: _${escapeMd(a.issue)}_ — GPT says: _${escapeMd(b.issue)}_`);
+    }
+    lines.push('');
+  }
+
+  if (opusOnly.length) {
+    lines.push('### Opus-only findings (POTENTIAL QUALITY GAP if real bugs)');
+    lines.push('');
+    for (const f of opusOnly.slice(0, 10)) {
+      lines.push(`- [${escapeMd(f.severity)}] **${escapeMd(f.file)}:${f.line ?? '?'}** — ${escapeMd(f.issue)}`);
+    }
+    if (opusOnly.length > 10) lines.push(`- ... and ${opusOnly.length - 10} more`);
+    lines.push('');
+  }
+
+  if (ghOnly.length) {
+    lines.push('### GH Models-only findings');
+    lines.push('');
+    for (const f of ghOnly.slice(0, 10)) {
+      lines.push(`- [${escapeMd(f.severity)}] **${escapeMd(f.file)}:${f.line ?? '?'}** — ${escapeMd(f.issue)}`);
+    }
+    if (ghOnly.length > 10) lines.push(`- ... and ${ghOnly.length - 10} more`);
+    lines.push('');
+  }
+
+  lines.push('## Decision rubric — fill after manual review');
+  lines.push('');
+  lines.push('- [ ] Did GH Models catch ≥80% of Opus HIGH/MEDIUM findings on this release?');
+  lines.push('- [ ] Were any Opus-only findings actually real bugs (not noise)?');
+  lines.push('- [ ] Were any GH Models-only findings actually real bugs that Opus missed?');
+  lines.push('- [ ] Was the output format clean for both providers?');
+  lines.push('');
+  lines.push('Append this comparison row to the rubric in');
+  lines.push('`docs/architecture/release-review-llm-provider-decision.md`.');
+
+  return lines.join('\n');
+}
+
+function main(argv) {
+  if (argv.length < 2) {
+    console.error('Usage: node cli/lib/compare-reviews.js <opus-findings.json> <gh-models-findings.json>');
+    console.error('');
+    console.error('Download both artifacts from a release CI run, then run this script.');
+    process.exit(1);
+  }
+  const opusFile = path.resolve(argv[0]);
+  const ghFile   = path.resolve(argv[1]);
+  const opus = describe(loadEnvelope(opusFile));
+  const gh   = describe(loadEnvelope(ghFile));
+  console.log(renderMarkdown(opus, gh));
+  process.exit(0);
+}
+
+if (require.main === module) {
+  main(process.argv.slice(2));
+}
+
+module.exports = {
+  loadEnvelope,
+  describe,
+  findOverlap,
+  bucketSeverity,
+  renderMarkdown,
+  normalizePath,
+  escapeMd,
+};

package/lib/parse-review-json.js

@@ -0,0 +1,87 @@
+'use strict';
+/**
+ * parse-review-json.js — HC-080a-spike extraction helper.
+ *
+ * Robust JSON extraction from LLM output. Used by `hone release-review` to
+ * parse the structured `{ findings, summary, recommendation }` response from
+ * either Anthropic Opus or GitHub Models GPT-4.1.
+ *
+ * Why this exists: LLMs don't reliably emit pure JSON. The function tries
+ * three shapes in order:
+ *
+ *   1. Pure JSON — the whole response IS valid JSON.
+ *   2. Code-fenced — ```json { ... } ``` block somewhere in the response.
+ *   3. Forward-scan balanced — find every balanced `{...}` span in the
+ *      response and JSON.parse the LONGEST one (LLMs that emit a schema
+ *      example before their real answer would otherwise corrupt a naive
+ *      greedy regex; the real answer is almost always the largest block).
+ *
+ * The function returns the parsed object, or null on failure. Callers should
+ * use the loose substring fallback (e.g., `/\bCRITICAL\b/`) on the raw text
+ * when this returns null — that's the safety net against silent CRITICAL
+ * passes on non-JSON output.
+ */
+
+/**
+ * @param {string} text  Raw LLM response.
+ * @returns {object|null}  Parsed JSON, or null if no parseable JSON found.
+ */
+function parseReviewJSON(text) {
+  if (!text || typeof text !== 'string') return null;
+
+  // Shape 1: try the whole string. Cheap; happens when the LLM follows the
+  // "Output as JSON" instruction strictly.
+  try { return JSON.parse(text); } catch { /* fall through */ }
+
+  // Shape 2: ```json ... ``` fenced block. Common when the LLM emits prose
+  // commentary before the structured answer.
+  const fenced = text.match(/```(?:json)?\s*\n?([\s\S]*?)```/i);
+  if (fenced) {
+    try { return JSON.parse(fenced[1]); } catch { /* fall through */ }
+  }
+
+  // Shape 3: forward-scan for balanced `{...}` spans, then try parsing each
+  // from longest to shortest. This handles LLMs that emit a schema example
+  // then their real answer (we'd otherwise capture both as one bad blob if
+  // we used a greedy `/\{[\s\S]*\}/` regex).
+  //
+  // The scanner tracks whether we're inside a JSON string literal so braces
+  // inside strings don't disrupt depth counting. Escape handling: a `\`
+  // inside a string marks the next character as escaped, so `\"` doesn't
+  // terminate the string.
+  const spans = [];
+  let depth = 0, start = -1, inString = false, escaped = false;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (escaped) { escaped = false; continue; }
+    if (inString) {
+      if (ch === '\\') escaped = true;
+      else if (ch === '"') inString = false;
+      continue;
+    }
+    if (ch === '"') { inString = true; continue; }
+    if (ch === '{') {
+      if (depth === 0) start = i;
+      depth++;
+    } else if (ch === '}') {
+      depth--;
+      if (depth === 0 && start >= 0) {
+        spans.push([start, i + 1]);
+        start = -1;
+      } else if (depth < 0) {
+        // Recover from malformed input — extra `}` without matching `{`.
+        depth = 0;
+      }
+    }
+  }
+
+  // Try longest spans first — the LLM's real answer is usually the largest
+  // block in the response.
+  spans.sort((a, b) => (b[1] - b[0]) - (a[1] - a[0]));
+  for (const [a, b] of spans) {
+    try { return JSON.parse(text.slice(a, b)); } catch { /* try next span */ }
+  }
+  return null;
+}
+
+module.exports = { parseReviewJSON };

package/lib/refresh-knowledge.js

@@ -26,9 +26,12 @@ const path = require('node:path');
 const crypto = require('node:crypto');
 const { execSync } = require('node:child_process');
 
+// HC-019y (2026-05-29): removed `.github/agents` from refresh paths.
+// Agents live exclusively at `.claude/agents/` (Claude Code's read path)
+// after the install-time mirror was eliminated. `.github/agents/` is now
+// a legacy directory adopters are expected to manually delete.
 const KNOWLEDGE_DIRS = [
   '.github/skills',
-  '.github/agents',
   '.claude/agents',
   '.github/copilot-instructions.md',
 ];

package/lib/release-review-config.js

@@ -0,0 +1,98 @@
+'use strict';
+/**
+ * release-review-config.js — HC-080a-spike helpers extracted for unit coverage.
+ *
+ * Two helpers exist here because they were sources of bugs in the first
+ * spike CI run (PR #313 data point 1):
+ *
+ *   1. resolveBaseRef() — the CI step passes `--base origin/main` and the
+ *      CLI was prefixing `origin/` again, producing `origin/origin/main`
+ *      which `git diff` rejects. Either calling convention (`main` or
+ *      `origin/main`) should now work.
+ *
+ *   2. getMaxDiffChars() — GH Models GPT-4.1 enforces an 8000-token cap
+ *      on the REQUEST BODY (input). The previous 100k-char truncation
+ *      worked fine for Opus (200k context) but failed every GH Models call
+ *      with "Request body too large." Provider-specific truncation fixes it.
+ *      See the function's docstring for budget math + the input-only vs
+ *      total-body interpretation.
+ */
+
+/**
+ * Resolve a base ref to a stable `origin/<branch>` form regardless of
+ * whether the caller already prefixed it.
+ *
+ * Examples:
+ *   resolveBaseRef('main')             // → 'origin/main'
+ *   resolveBaseRef('origin/main')      // → 'origin/main'  (no double prefix)
+ *   resolveBaseRef('refs/remotes/origin/main')  // → 'origin/main'
+ *
+ * @param {string} base  User-supplied base branch.
+ * @returns {string}     Normalized git revision suitable for `git diff <ref>...HEAD`.
+ */
+function resolveBaseRef(base) {
+  if (!base || typeof base !== 'string') return 'origin/main';
+  const trimmed = base.trim();
+  if (trimmed.startsWith('refs/remotes/origin/')) {
+    return 'origin/' + trimmed.slice('refs/remotes/origin/'.length);
+  }
+  if (trimmed.startsWith('origin/')) return trimmed;
+  return 'origin/' + trimmed;
+}
+
+/**
+ * Provider-specific max diff size (in chars). Models with smaller input
+ * windows need more aggressive truncation.
+ *
+ * ## Budget math
+ *
+ * GH Models `openai/gpt-4.1` via `models.github.ai/inference` enforces an
+ * 8000-token cap on the REQUEST BODY (everything in the JSON payload sent
+ * to /chat/completions: system message + user message + model name + the
+ * `max_tokens` integer). The OUTPUT cap (`max_tokens: 4096`) is counted
+ * separately by the model and does NOT consume the 8000-token request
+ * budget — that 4096 governs how many tokens the response is allowed to
+ * have, not how many tokens our request can include.
+ *
+ * Decomposition of the 8000-token input budget (typical):
+ *   system prompt           ~600 tokens (~2400 chars)
+ *   user prompt template    ~200 tokens (~800 chars)
+ *   file list (40 entries)  ~400 tokens (~1600 chars)
+ *   safety headroom         ~800 tokens (~3200 chars)
+ *   -------------------------------
+ *   diff budget             ~6000 tokens ≈ 24000 chars
+ *
+ * We use 20000 chars (≈5000 tokens) as a conservative cap to leave room
+ * for prompt drift if we evolve the system/user templates. If GH Models
+ * documentation later confirms the cap is TOTAL (input + output) instead
+ * of input-only, drop this number AND `max_tokens` together.
+ *
+ * Anthropic Opus `claude-opus-4-20250514`: 200K context window. The 100K
+ * char cap is generous and unchanged from the original implementation.
+ *
+ * ## Default behavior — FAIL CLOSED
+ *
+ * Unknown providers receive the SMALLEST known cap (20000), not the
+ * largest. Reasoning: if a future small-context provider (haiku, mini,
+ * flash) is added and a developer forgets to add a switch case here,
+ * the 20000 default truncates safely. Falling back to 100000 would
+ * re-introduce exactly the bug class this helper exists to fix.
+ *
+ * @param {string} provider  'opus' or 'gh-models'.
+ * @returns {number}         Max diff chars to send to this provider.
+ */
+function getMaxDiffChars(provider) {
+  switch (provider) {
+    case 'opus':
+      return 100000;
+    case 'gh-models':
+      return 20000;
+    default:
+      return 20000;
+  }
+}
+
+module.exports = {
+  resolveBaseRef,
+  getMaxDiffChars,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hone-ai/cli",
-  "version": "1.9.0",
+  "version": "1.11.0",
   "description": "Hone AI — Enterprise SDLC Pipeline CLI",
   "main": "hone-cli.js",
   "bin": {