genesis-cli 0.1.0__py3-none-any.whl

genesis_cli/main.py

@@ -0,0 +1,228 @@
+"""`genesis` — the Genesis Agent Workbench CLI.
+
+Commands:
+  genesis adopt [path]   Audit a repo for agent-readiness: run delivery gates,
+                         completeness + env analysis, score it, and draft
+                         AGENTS.md. Deterministic — no API keys, no server.
+  genesis gates [path]   Run just the delivery gates (no full analysis) and
+                         print a per-gate table. Fast local iteration + CI.
+  genesis init [path]    Scaffold a new/bare repo so agents start agent-ready:
+                         AGENTS.md, .gitignore, .env.example, audit workflow,
+                         gate config. Idempotent — never overwrites.
+  genesis --version      Print the installed genesis-cli version.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .adopt import run_audit
+from .agents_md import render_agents_md
+from .baseline import append_history, compare, render_trend
+from .report import render_html, render_terminal
+from .sarif import render_sarif
+
+
+def _version() -> str:
+    """The installed genesis-cli version, single-sourced from package metadata.
+
+    Reading the *distribution* metadata keeps pyproject the one place a version
+    is written. Running from a source checkout without an install has no
+    metadata to read, so fall back rather than crash `--version`.
+    """
+    from importlib.metadata import PackageNotFoundError, version
+
+    try:
+        return version("genesis-cli")
+    except PackageNotFoundError:
+        return "0+unknown (genesis-cli is not installed)"
+
+
+def _cmd_adopt(args: argparse.Namespace) -> int:
+    repo = Path(args.path).resolve()
+    if not repo.is_dir():
+        print(f"error: {repo} is not a directory", file=sys.stderr)
+        return 2
+    if args.fail_on_regression and not args.baseline:
+        print("error: --fail-on-regression requires --baseline", file=sys.stderr)
+        return 2
+
+    report = run_audit(repo)
+
+    comparison = None
+    if args.baseline:
+        # Read the baseline before any artifact is written: --baseline is often
+        # the previous run's report.json at the very path we are about to write.
+        baseline_path = Path(args.baseline)
+        try:
+            baseline = json.loads(baseline_path.read_text())
+        except (OSError, json.JSONDecodeError) as exc:
+            print(f"error: cannot read baseline {baseline_path}: {exc}",
+                  file=sys.stderr)
+            return 2
+        comparison = compare(report, baseline)
+        report["baseline_comparison"] = comparison
+
+    if args.review:
+        from .review import run_review
+
+        print("Running AI second-reader (claude, subscription — additive only)…",
+              file=sys.stderr)
+        report["ai_review"] = run_review(repo, report)
+        if "error" in report["ai_review"]:
+            print(f"AI review unavailable: {report['ai_review']['error']}",
+                  file=sys.stderr)
+
+    out_dir = Path(args.out) if args.out else repo / ".genesis-report"
+    out_dir.mkdir(parents=True, exist_ok=True)
+    history = append_history(out_dir, report)
+    (out_dir / "report.json").write_text(json.dumps(report, indent=2))
+    (out_dir / "report.html").write_text(render_html(report, history=history))
+    (out_dir / "report.sarif").write_text(json.dumps(render_sarif(report), indent=2))
+    agents_md = render_agents_md(report)
+    (out_dir / "AGENTS.md").write_text(agents_md)
+
+    if args.write:
+        target = repo / "AGENTS.md"
+        if target.exists() and not args.force:
+            print(f"note: {target} already exists — draft left at "
+                  f"{out_dir / 'AGENTS.md'} (use --force to overwrite)")
+        else:
+            target.write_text(agents_md)
+            print(f"wrote {target}")
+
+    if args.json:
+        print(json.dumps(report, indent=2))
+    else:
+        print(render_terminal(report))
+        if trend := render_trend(history):
+            print(trend)
+        print(f"Artifacts: {out_dir}/report.html · report.json · report.sarif "
+              f"· AGENTS.md")
+
+    score = report["readiness"]["score"]
+    ci_mode = args.min_score is not None or args.fail_on_regression
+    if ci_mode:
+        failed = False
+        if args.min_score is not None and score < args.min_score:
+            print(f"FAIL: readiness {score} below --min-score {args.min_score}",
+                  file=sys.stderr)
+            failed = True
+        if args.fail_on_regression and comparison and comparison["regressed"]:
+            print("FAIL: regression since baseline (score drop, new gap, or "
+                  "new critical/high finding)", file=sys.stderr)
+            failed = True
+        return 1 if failed else 0
+    # Default exit code mirrors the grade: A/B/C -> 0, D/F -> 1 (CI-friendly).
+    return 0 if report["readiness"]["grade"] in ("A", "B", "C") else 1
+
+
+def _cmd_gates(args: argparse.Namespace) -> int:
+    from genesis_gates import GATE_REGISTRY
+
+    from .adopt import ADOPT_GATES, run_gates
+    from .gates import gates_exit_code, render_gates_terminal
+
+    repo = Path(args.path).resolve()
+    if not repo.is_dir():
+        print(f"error: {repo} is not a directory", file=sys.stderr)
+        return 2
+
+    if args.gate:
+        # De-duplicate while preserving the order the user asked for.
+        selected = list(dict.fromkeys(args.gate))
+        if unknown := [g for g in selected if g not in GATE_REGISTRY]:
+            print(f"error: unknown gate(s): {', '.join(unknown)}. "
+                  f"Valid gates: {', '.join(sorted(GATE_REGISTRY))}",
+                  file=sys.stderr)
+            return 2
+    else:
+        selected = list(ADOPT_GATES)
+
+    package = run_gates(repo, selected)
+    if args.json:
+        print(json.dumps(package, indent=2))
+    else:
+        print(render_gates_terminal(package))
+    return gates_exit_code(package)
+
+
+def _cmd_init(args: argparse.Namespace) -> int:
+    from .init import render_summary, run_init
+
+    repo = Path(args.path).resolve()
+    if repo.exists() and not repo.is_dir():
+        print(f"error: {repo} is not a directory", file=sys.stderr)
+        return 2
+    created, skipped = run_init(repo)
+    print(render_summary(repo, created, skipped))
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="genesis",
+        description="Genesis Agent Workbench — make any repo agent-ready and "
+                    "keep AI-generated changes governed.",
+    )
+    parser.add_argument("--version", action="version",
+                        version=f"%(prog)s {_version()}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    adopt = sub.add_parser(
+        "adopt", help="audit a repo for agent-readiness (score, gaps, AGENTS.md)")
+    adopt.add_argument("path", nargs="?", default=".", help="repo to audit (default: .)")
+    adopt.add_argument("--out", help="artifact directory (default: <repo>/.genesis-report)")
+    adopt.add_argument("--write", action="store_true",
+                       help="write AGENTS.md into the repo root")
+    adopt.add_argument("--force", action="store_true",
+                       help="with --write: overwrite an existing AGENTS.md")
+    adopt.add_argument("--json", action="store_true",
+                       help="print the full JSON report to stdout")
+    adopt.add_argument("--review", action="store_true",
+                       help="add the AI second-reader pass (claude CLI, "
+                            "subscription auth; additive-only — never alters "
+                            "the deterministic score)")
+    adopt.add_argument("--min-score", type=float, default=None,
+                       help="CI mode: exit 1 if the readiness score is below "
+                            "this threshold")
+    adopt.add_argument("--baseline", metavar="PATH",
+                       help="previous report.json to diff against; adds a "
+                            "CHANGES SINCE BASELINE section and embeds "
+                            "baseline_comparison in report.json")
+    adopt.add_argument("--fail-on-regression", action="store_true",
+                       help="CI mode (requires --baseline): exit 1 on a "
+                            "regression — score drop > 0.5, a new "
+                            "mandatory-flow gap, or a new critical/high "
+                            "finding")
+    adopt.set_defaults(func=_cmd_adopt)
+
+    gates = sub.add_parser(
+        "gates", help="run just the delivery gates (no full analysis): "
+                      "per-gate table, exit 1 if any gate failed")
+    gates.add_argument("path", nargs="?", default=".",
+                       help="repo to check (default: .)")
+    gates.add_argument("--gate", action="append", metavar="NAME",
+                       help="run only this gate (repeatable); default: the "
+                            "adopt gate set")
+    gates.add_argument("--json", action="store_true",
+                       help="print the evidence package as JSON")
+    gates.set_defaults(func=_cmd_gates)
+
+    init = sub.add_parser(
+        "init", help="scaffold a new/bare repo so agents start agent-ready "
+                     "(AGENTS.md, .gitignore, .env.example, audit workflow); "
+                     "never overwrites existing files")
+    init.add_argument("path", nargs="?", default=".",
+                      help="directory to scaffold (default: .; created if missing)")
+    init.set_defaults(func=_cmd_init)
+
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

genesis_cli/report.py

@@ -0,0 +1,251 @@
+"""Report renderers: terminal (plain ANSI-light) and self-contained HTML."""
+
+from __future__ import annotations
+
+import html
+
+_BAR_W = 24
+
+
+def _bar(points: float, maximum: float) -> str:
+    filled = int(round(_BAR_W * (points / maximum))) if maximum else 0
+    return "█" * filled + "░" * (_BAR_W - filled)
+
+
+def _baseline_lines(cmp: dict) -> list[str]:
+    """The CHANGES SINCE BASELINE block (report has a `baseline_comparison`)."""
+    delta = cmp["score_delta"]
+    arrow = "▲" if delta > 0 else "▼" if delta < 0 else "="
+    head = f"  score {arrow} {delta:+.1f}"
+    if cmp["grade_change"]:
+        head += f"   grade {cmp['grade_change']}"
+    lines = [
+        "CHANGES SINCE BASELINE" + ("  — REGRESSION" if cmp["regressed"] else ""),
+        head,
+        f"  findings: {len(cmp['new_findings'])} new, "
+        f"{len(cmp['resolved_findings'])} resolved   ·   "
+        f"gaps: {len(cmp['new_gaps'])} new, "
+        f"{len(cmp['resolved_gaps'])} resolved",
+    ]
+    for f in cmp["new_findings"][:5]:
+        loc = f" ({f['location']})" if f.get("location") else ""
+        lines.append(f"  + [{f.get('severity')}] {f.get('gate')}: "
+                     f"{f.get('title')}{loc}")
+    for g in cmp["new_gaps"][:5]:
+        lines.append(f"  + gap: {g.get('title')}")
+    for f in cmp["resolved_findings"][:5]:
+        lines.append(f"  − resolved: {f.get('title')}")
+    for g in cmp["resolved_gaps"][:5]:
+        lines.append(f"  − closed gap: {g.get('title')}")
+    lines.append("")
+    return lines
+
+
+def render_terminal(report: dict) -> str:
+    r = report["readiness"]
+    lines = [
+        "",
+        f"Genesis Agent-Readiness Report — {report['repo']}",
+        f"Generated {report['generated_at']}",
+        "=" * 72,
+        "",
+        f"  READINESS SCORE: {r['score']}/100   GRADE: {r['grade']}",
+        "",
+    ]
+    for cat in r["categories"]:
+        lines.append(f"  {cat['key']:<14} {_bar(cat['points'], cat['max'])} "
+                     f"{cat['points']}/{cat['max']}")
+    lines.append("")
+    if cmp := report.get("baseline_comparison"):
+        lines += _baseline_lines(cmp)
+    for cat in r["categories"]:
+        lines.append(f"── {cat['key']} " + "─" * (68 - len(cat["key"])))
+        lines += [f"   {d}" for d in cat["details"][:10]]
+        if len(cat["details"]) > 10:
+            lines.append(f"   … {len(cat['details']) - 10} more (see HTML/JSON report)")
+        lines.append("")
+    gaps = report["completeness"].get("gaps", [])
+    if gaps:
+        lines.append("MANDATORY-FLOW GAPS (highest-priority remediation):")
+        for g in gaps:
+            lines.append(f"  • {g['title']}")
+        lines.append("")
+
+    review = report.get("ai_review")
+    if review and "error" not in review:
+        lines.append("AI SECOND-READER (additive — does not alter the score):")
+        if review.get("executive_summary"):
+            lines.append(f"  {review['executive_summary']}")
+            lines.append("")
+        for f in review.get("additional_findings", []):
+            lines.append(f"  + [{f['severity']}/{f['area']}] {f['title']}")
+        for a in review.get("annotations", [])[:6]:
+            lines.append(f"  ~ {a['ref']}: {a['note']}")
+        if review.get("remediation_plan"):
+            lines.append("  Remediation order:")
+            for i, step in enumerate(review["remediation_plan"], 1):
+                lines.append(f"    {i}. {step}")
+        lines.append("")
+    return "\n".join(lines)
+
+
+def _baseline_html(cmp: dict) -> str:
+    """CHANGES SINCE BASELINE section — mirrors `_baseline_lines`."""
+    e = html.escape
+    delta = cmp["score_delta"]
+    arrow = "▲" if delta > 0 else "▼" if delta < 0 else "="
+    cls = "up" if delta > 0 else "down" if delta < 0 else ""
+    badge = ("<span class='chip chip-bad'>REGRESSION</span>"
+             if cmp["regressed"] else "")
+    grade = (f" · grade {e(cmp['grade_change'])}" if cmp["grade_change"] else "")
+    rows: list[str] = []
+    for f in cmp["new_findings"]:
+        loc = f" <small>({e(f['location'])})</small>" if f.get("location") else ""
+        rows.append(f"<li class='base-new'>+ [{e(str(f.get('severity')))}] "
+                    f"{e(str(f.get('gate')))}: {e(str(f.get('title')))}{loc}</li>")
+    rows += [f"<li class='base-new'>+ gap: {e(str(g.get('title')))}</li>"
+             for g in cmp["new_gaps"]]
+    rows += [f"<li class='base-resolved'>− resolved: {e(str(f.get('title')))}</li>"
+             for f in cmp["resolved_findings"]]
+    rows += [f"<li class='base-resolved'>− closed gap: {e(str(g.get('title')))}</li>"
+             for g in cmp["resolved_gaps"]]
+    return (
+        f"<section><h2>Changes since baseline {badge}</h2>"
+        f"<p class='delta {cls}'>score {arrow} {delta:+.1f}{grade} · "
+        f"{len(cmp['new_findings'])} new / {len(cmp['resolved_findings'])} "
+        f"resolved findings · {len(cmp['new_gaps'])} new / "
+        f"{len(cmp['resolved_gaps'])} closed gaps</p>"
+        + (f"<ul>{''.join(rows)}</ul>" if rows else "")
+        + "</section>"
+    )
+
+
+def _history_html(history: list[dict] | None, max_shown: int = 12) -> str:
+    """Score-trend strip: one bar per audit, most recent last/highlighted."""
+    if not history or len(history) < 2:
+        return ""
+    e = html.escape
+    shown = history[-max_shown:]
+    bars = "".join(
+        f"<div class='trend-bar{' cur' if i == len(shown) - 1 else ''}' "
+        f"title='{e(str(h.get('generated_at', '')))} — "
+        f"{h.get('score')}/100 ({e(str(h.get('grade', '')))})'>"
+        f"<div style='height:{max(4, round(float(h.get('score', 0))))}%'></div>"
+        f"<span>{h.get('score')}</span></div>"
+        for i, h in enumerate(shown)
+    )
+    prefix = "… " if len(history) > len(shown) else ""
+    return (
+        f"<section><h2>Score history <span>{prefix}{len(history)} runs</span></h2>"
+        f"<div class='trend'>{bars}</div></section>"
+    )
+
+
+def _review_html(report: dict) -> str:
+    review = report.get("ai_review")
+    if not review or "error" in review:
+        return ""
+    e = html.escape
+    findings = "".join(
+        f"<li><strong>[{e(f['severity'])}/{e(f['area'])}]</strong> "
+        f"{e(f['title'])}<br><small>{e(f['detail'])}</small></li>"
+        for f in review.get("additional_findings", [])
+    )
+    notes = "".join(
+        f"<li><em>{e(a['ref'])}</em> — {e(a['note'])}</li>"
+        for a in review.get("annotations", [])
+    )
+    plan = "".join(f"<li>{e(s)}</li>" for s in review.get("remediation_plan", []))
+    return (
+        "<section><h2>AI second-reader "
+        "<span style='font-size:12px;color:#9aa7b8'>additive-only — does not "
+        "alter the deterministic score</span></h2>"
+        f"<p>{e(review.get('executive_summary', ''))}</p>"
+        + (f"<h3>Additional findings</h3><ul>{findings}</ul>" if findings else "")
+        + (f"<h3>Annotations</h3><ul>{notes}</ul>" if notes else "")
+        + (f"<h3>Remediation order</h3><ol>{plan}</ol>" if plan else "")
+        + "</section>"
+    )
+
+
+def render_html(report: dict, history: list[dict] | None = None) -> str:
+    r = report["readiness"]
+    e = html.escape
+
+    def cat_block(cat: dict) -> str:
+        pct = 100 * cat["points"] / cat["max"] if cat["max"] else 0
+        def _cls(d: str) -> str:
+            return "ok" if d.startswith("✓") else "bad" if d.startswith("✗") else ""
+
+        rows = "".join(
+            f'<li class="{_cls(d)}">{e(d)}</li>' for d in cat["details"]
+        )
+        return (
+            f"<section><h2>{e(cat['key'])} <span>{cat['points']}/{cat['max']}</span></h2>"
+            f"<div class='meter'><div style='width:{pct:.0f}%'></div></div>"
+            f"<ul>{rows}</ul></section>"
+        )
+
+    gaps = report["completeness"].get("gaps", [])
+    # Gaps are mandatory-flow misses — styled like high-severity findings
+    # (they render as `error` in the SARIF output).
+    gaps_html = "".join(
+        f"<li class='gap'><span class='sev sev-high'>required flow</span> "
+        f"<strong>{e(g['title'])}</strong>"
+        f"<br><small>{e(g['brief'])}</small></li>"
+        for g in gaps
+    )
+    gate_rows = "".join(
+        f"<tr><td>{e(str(g.get('gate')))}</td><td class='s-{e(str(g.get('status')))}'>"
+        f"{e(str(g.get('status')))}</td><td>{e(str(g.get('summary', ''))[:120])}</td></tr>"
+        for g in report["gates"]
+    )
+    grade_hue = {"A": 130, "B": 90, "C": 48, "D": 28, "F": 4}.get(r["grade"], 0)
+    return f"""<!doctype html><html><head><meta charset="utf-8">
+<title>Genesis Readiness — {e(report['repo'])}</title>
+<style>
+ body{{font:15px/1.5 -apple-system,Segoe UI,sans-serif;margin:0;background:#0e1116;color:#dde3ea}}
+ main{{max-width:880px;margin:0 auto;padding:40px 24px}}
+ h1{{font-size:22px}} h2{{font-size:16px;display:flex;justify-content:space-between}}
+ .score{{display:flex;align-items:center;gap:20px;margin:24px 0}}
+ .badge{{font-size:44px;font-weight:700;padding:18px 26px;border-radius:14px;
+        background:hsl({grade_hue} 65% 18%);color:hsl({grade_hue} 80% 65%)}}
+ .meter{{height:8px;background:#1c2330;border-radius:4px;overflow:hidden}}
+ .meter div{{height:100%;background:#3fb68b}}
+ section{{margin:26px 0;padding:18px;background:#151a22;border-radius:10px}}
+ ul{{margin:10px 0 0;padding-left:20px}} li.ok{{color:#7fd6ac}} li.bad{{color:#e08a8a}}
+ table{{width:100%;border-collapse:collapse;font-size:14px}}
+ td{{padding:6px 8px;border-top:1px solid #232b38}}
+ .s-passed{{color:#7fd6ac}} .s-failed{{color:#e08a8a}} .s-skipped{{color:#9aa7b8}}
+ small{{color:#9aa7b8}}
+ .chip{{font-size:11px;font-weight:600;padding:2px 8px;border-radius:9px;vertical-align:middle}}
+ .chip-bad{{background:#3a1d1d;color:#e08a8a}}
+ .delta{{margin:4px 0 10px;color:#9aa7b8}} .delta.up{{color:#7fd6ac}} .delta.down{{color:#e08a8a}}
+ .base-new{{color:#e08a8a}} .base-resolved{{color:#7fd6ac}}
+ .sev{{font-size:11px;font-weight:600;padding:1px 7px;border-radius:9px;margin-right:6px}}
+ .sev-high{{background:#3a1d1d;color:#e08a8a}}
+ li.gap{{margin:8px 0;list-style:none;border-left:3px solid #a04545;padding-left:10px}}
+ section ul:has(li.gap){{padding-left:4px}}
+ .trend{{display:flex;gap:5px;align-items:flex-end;height:84px;margin-top:12px}}
+ .trend-bar{{display:flex;flex-direction:column;justify-content:flex-end;align-items:center;
+   height:64px;width:26px}}
+ .trend-bar div{{width:100%;background:#28564a;border-radius:3px 3px 0 0}}
+ .trend-bar.cur div{{background:#3fb68b}}
+ .trend-bar span{{font-size:10px;color:#9aa7b8;margin-top:3px}}
+ a{{color:#7fb3d6}}
+</style></head><body><main>
+<h1>Genesis Agent-Readiness Report</h1>
+<p><code>{e(report['repo'])}</code> · {e(report['generated_at'])}</p>
+<div class="score"><div class="badge">{e(r['grade'])}</div>
+<div><strong style="font-size:28px">{r['score']}/100</strong><br>
+<small>agent-readiness score</small></div></div>
+{_baseline_html(report['baseline_comparison']) if report.get('baseline_comparison') else ''}
+{_history_html(history)}
+{''.join(cat_block(c) for c in r['categories'])}
+{f"<section><h2>Mandatory-flow gaps</h2><ul>{gaps_html}</ul></section>" if gaps else ""}
+{_review_html(report)}
+<section><h2>Gate results</h2><table>{gate_rows}</table></section>
+<p><small>Generated by <code>genesis adopt</code> — part of the
+<a href="https://genesis.dev">Genesis</a> delivery framework
+(schema: <code>readiness-report.schema.json</code>).</small></p>
+</main></body></html>"""

genesis_cli/review.py

@@ -0,0 +1,151 @@
+"""AI second-reader for `genesis adopt --review`.
+
+The deterministic audit is the trust anchor; this pass is **additive-only**:
+it may add findings, annotate, prioritize, and summarize — it can never remove
+or downgrade a deterministic finding, and it never changes the readiness score.
+
+Runs through the local `claude` CLI in headless mode using the user's existing
+subscription login (ANTHROPIC_API_KEY is explicitly unset in the child), so
+`--review` keeps the audit's zero-API-key property. If the CLI is unavailable
+or the call fails, the audit proceeds without the review — degraded, never
+broken.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+_TIMEOUT_S = 240
+_MAX_TREE_ENTRIES = 300
+_SKIP_DIRS = {".git", "node_modules", "dist", "build", "__pycache__", ".venv",
+              "venv", ".next", "coverage", ".genesis-work", ".genesis-report"}
+
+_INSTRUCTIONS = """\
+You are the AI second-reader for a Genesis agent-readiness audit. A
+deterministic scanner already produced the findings in REPORT_JSON for the
+repository whose file tree is in REPO_TREE.
+
+Your job is ADDITIVE ONLY: find what the deterministic pass missed, annotate
+what it found, and write the executive summary. You must NOT dispute scores or
+suggest removing findings — if you believe a finding is a false positive, add
+an annotation saying so; never omit it.
+
+Look especially for:
+- system kinds the scanner has no profile for (payments, file upload, email,
+  multi-tenancy, background jobs) and mandatory flows they imply that appear
+  unimplemented;
+- architectural risks visible from the tree/report (no service boundaries,
+  test gaps in critical areas, framework misuse);
+- anything that would make an AI coding agent unsafe or unproductive in this
+  repo (missing conventions, ambiguous structure, dead config).
+
+Respond with ONLY a JSON object, no prose before or after, exactly this shape:
+{
+  "executive_summary": "3-6 sentences a CTO reads first",
+  "additional_findings": [
+    {"title": "...", "severity": "critical|high|medium|low",
+     "area": "completeness|security|architecture|testing|agent-readiness",
+     "detail": "1-3 sentences, concrete"}
+  ],
+  "annotations": [
+    {"ref": "which deterministic finding/category this refers to",
+     "note": "context, likely-false-positive flag, or prioritization"}
+  ],
+  "remediation_plan": ["ordered, concrete first 5-8 steps"]
+}
+"""
+
+
+def claude_available() -> bool:
+    return shutil.which("claude") is not None
+
+
+def _repo_tree(repo: Path) -> str:
+    lines: list[str] = []
+    for f in sorted(repo.rglob("*")):
+        if len(lines) >= _MAX_TREE_ENTRIES:
+            lines.append("… (tree truncated)")
+            break
+        if any(part in _SKIP_DIRS for part in f.parts):
+            continue
+        if f.is_file():
+            lines.append(str(f.relative_to(repo)))
+    return "\n".join(lines)
+
+
+def _extract_json(text: str) -> dict | None:
+    start, end = text.find("{"), text.rfind("}")
+    if start == -1 or end <= start:
+        return None
+    try:
+        data = json.loads(text[start:end + 1])
+    except json.JSONDecodeError:
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def _sanitize(data: dict) -> dict:
+    """Enforce the additive-only contract and bound sizes."""
+    findings = []
+    for f in (data.get("additional_findings") or [])[:20]:
+        if isinstance(f, dict) and f.get("title"):
+            findings.append({
+                "title": str(f.get("title"))[:200],
+                "severity": str(f.get("severity", "medium")).lower(),
+                "area": str(f.get("area", "architecture"))[:40],
+                "detail": str(f.get("detail", ""))[:600],
+            })
+    annotations = [
+        {"ref": str(a.get("ref", ""))[:200], "note": str(a.get("note", ""))[:400]}
+        for a in (data.get("annotations") or [])[:20]
+        if isinstance(a, dict) and a.get("note")
+    ]
+    plan = [str(s)[:300] for s in (data.get("remediation_plan") or [])[:10]]
+    return {
+        "executive_summary": str(data.get("executive_summary", ""))[:2000],
+        "additional_findings": findings,
+        "annotations": annotations,
+        "remediation_plan": plan,
+        "additive_only": True,
+        "engine": "claude-cli (subscription)",
+    }
+
+
+def run_review(repo: Path, report: dict) -> dict:
+    """Return the ai_review block, or {"error": ...} (audit proceeds either way)."""
+    if not claude_available():
+        return {"error": "claude CLI not found on PATH — install Claude Code or "
+                         "run without --review"}
+    slim = {k: report[k] for k in ("readiness", "gates", "completeness", "env",
+                                   "structure") if k in report}
+    prompt = (
+        f"{_INSTRUCTIONS}\n\nREPO_TREE:\n{_repo_tree(repo)}\n\n"
+        f"REPORT_JSON:\n{json.dumps(slim, indent=1)[:60_000]}\n"
+    )
+    env = dict(os.environ)
+    env.pop("ANTHROPIC_API_KEY", None)  # force subscription auth
+    try:
+        proc = subprocess.run(
+            ["claude", "-p", prompt, "--output-format", "json"],
+            capture_output=True, text=True, timeout=_TIMEOUT_S, env=env,
+            cwd=str(repo),
+        )
+    except subprocess.TimeoutExpired:
+        return {"error": f"AI review timed out after {_TIMEOUT_S}s"}
+    except OSError as exc:
+        return {"error": f"could not launch claude CLI: {exc}"}
+    if proc.returncode != 0:
+        return {"error": f"claude CLI exited {proc.returncode}: "
+                         f"{(proc.stderr or proc.stdout)[:300]}"}
+
+    # --output-format json wraps the answer in an envelope with a `result` field.
+    envelope = _extract_json(proc.stdout) or {}
+    payload = envelope.get("result", proc.stdout)
+    data = _extract_json(payload if isinstance(payload, str) else "")
+    if data is None:
+        return {"error": "AI review returned unparseable output"}
+    return _sanitize(data)