whycode-cli 0.2.6__py3-none-any.whl → 0.3.1__py3-none-any.whl

whycode/__init__.py

@@ -1,3 +1,3 @@
 """WhyCode — tells you what to be afraid of before touching a file."""
 
-__version__ = "0.2.6"
+__version__ = "0.3.1"

whycode/cli.py

@@ -6,6 +6,7 @@ Commands
 - ``whycode why <path>``        — print the Risk Card for a single file.
 - ``whycode why <path> --at SHA`` — risk card as of a past commit.
 - ``whycode why <path> --mute KIND`` — locally suppress a noisy signal kind.
+- ``whycode why <path> --llm`` — opt-in L3: LLM-extracted structured decisions.
 - ``whycode highlights``        — repo-wide treasure map of decisions and incidents.
 - ``whycode diff [--base REF]`` — risk-rank files changed against a base ref.
 - ``whycode show <sha>``        — risk-flavored summary for one commit.
@@ -155,6 +156,20 @@ def why(
         "--no-mutes",
         help="Bypass the local suppression list — show all signals.",
     ),
+    llm: bool = typer.Option(
+        False,
+        "--llm",
+        help=(
+            "Enrich the card with LLM-extracted structured decisions "
+            "(L3, opt-in, requires WHYCODE_LLM_API_KEY + WHYCODE_LLM_MODEL). "
+            "Sends only commits already filtered by L2 — see --llm-dry-run."
+        ),
+    ),
+    llm_dry_run: bool = typer.Option(
+        False,
+        "--llm-dry-run",
+        help="Show exactly what would be sent to the LLM without making the call.",
+    ),
     max_commits: int | None = typer.Option(
         None, "--max-commits", help="Cap the number of commits scanned (debug)."
     ),
@@ -195,6 +210,51 @@ def why(
         ref=resolved_ref,
         apply_suppressions=not no_mutes,
     )
+
+    if llm or llm_dry_run:
+        from whycode import decisions as dec
+
+        # Pick high-signal commits for L3: incidents take priority, plus
+        # any commit with a substantial body. Cap to keep the prompt small.
+        facts = gf.gather(repo_root, rel, max_commits=max_commits, ref=resolved_ref)
+        candidates = list(facts.incident_commits)
+        for c in facts.commits:
+            if c not in candidates and len(c.body) >= 100:
+                candidates.append(c)
+            if len(candidates) >= dec.DEFAULT_MAX_COMMITS:
+                break
+        candidates = candidates[: dec.DEFAULT_MAX_COMMITS]
+        n_commits, prompt_chars = dec.estimate_payload(candidates)
+
+        if llm_dry_run:
+            err.print(
+                f"[bold]LLM dry-run:[/bold] would send "
+                f"[bold]{n_commits}[/bold] commit(s), "
+                f"[bold]~{prompt_chars}[/bold] chars to the configured LLM provider.\n"
+                f"  [dim]Provider, model, and key all read from "
+                f"WHYCODE_LLM_* environment variables.[/dim]"
+            )
+            if not json_out:
+                console.print(rc.render_text(card))
+            else:
+                console.print_json(json.dumps(card.to_dict()))
+            return
+
+        if n_commits == 0:
+            err.print(
+                "[yellow]--llm:[/yellow] no high-signal commits to enrich on this file."
+            )
+        else:
+            try:
+                decisions = dec.extract_decisions(candidates)
+            except dec.LLMConfigError as exc:
+                err.print(f"[red]--llm config error:[/red] {exc}")
+                raise typer.Exit(2) from exc
+            except dec.LLMCallError as exc:
+                err.print(f"[red]--llm call failed:[/red] {exc}")
+                raise typer.Exit(2) from exc
+            card = card.with_decisions(tuple(decisions))
+
     if json_out:
         console.print_json(json.dumps(card.to_dict()))
         return

whycode/decisions.py

@@ -0,0 +1,219 @@
+"""L3 — LLM-enriched decision extraction.
+
+What L1+L2 give: a regex-level harvest of single lines like
+``"Do not switch to async"``. What L3 adds: structured decisions with
+the full *why* drawn from the surrounding commit body.
+
+Structured decision schema (one ``Decision`` per finding):
+
+    {
+      "decision_type": "incident_fix" | "compat_workaround" | "perf_rewrite"
+                       | "rollback" | "constraint" | "other",
+      "what_changed":  "one sentence summary",
+      "why":           "one paragraph; quotes from the body where possible",
+      "do_not":        "actionable constraint, or null",
+      "evidence":      ["<sha1>", "<sha2>", …],
+      "confidence":    0.0 - 1.0
+    }
+
+Confidence < ``min_confidence`` is filtered out before return — better to
+emit nothing than emit a dressed-up guess. Privacy: this module makes a
+network call only if ``call_llm`` is invoked, which only happens when the
+caller passed commits in. Layer 1 and Layer 2 never reach this module.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from whycode.git_facts import Commit
+from whycode.llm import LLMCallError, LLMConfigError, call_llm
+
+DEFAULT_MIN_CONFIDENCE = 0.5
+DEFAULT_MAX_COMMITS = 10
+
+_SYSTEM = (
+    "You are a careful code-history archaeologist. You read commit messages "
+    "and surface the engineering decisions that future readers will need to "
+    "respect. You never invent facts; if a commit body does not state a "
+    "decision worth carrying forward, you emit nothing for that commit. "
+    "All quotes you produce must be drawn from the commit body itself; "
+    "summarise rather than paraphrase when you cannot quote."
+)
+
+_PROMPT_TEMPLATE = """Below are commits from a Git repository. For each commit, extract a structured Decision **only when the commit body genuinely states one**. Otherwise emit nothing for that commit.
+
+A Decision has this shape:
+
+  {{
+    "decision_type": one of
+        "incident_fix" | "compat_workaround" | "perf_rewrite" |
+        "rollback" | "constraint" | "other",
+    "what_changed":  one-sentence summary of the change itself,
+    "why":           one paragraph drawn from the body (quote where possible),
+    "do_not":        the actionable constraint a future editor must respect,
+                     or null if none stated,
+    "evidence":      array of commit SHAs supporting this decision,
+    "confidence":    a float in [0, 1] reflecting how clearly the body
+                     states this decision (use < 0.5 if you are unsure)
+  }}
+
+Rules:
+  - Reply with a JSON array of Decision objects, no prose, no code fences.
+  - Empty array if nothing qualifies.
+  - Quote rather than rephrase when stating "why".
+  - Do not infer constraints that are not in the body.
+  - Skip commits whose body is just a release note, dependency bump, or
+    one-line fix without explanation.
+
+COMMITS:
+
+{commits}
+"""
+
+
+@dataclass(frozen=True)
+class Decision:
+    decision_type: str
+    what_changed: str
+    why: str
+    do_not: str | None
+    evidence: tuple[str, ...]
+    confidence: float
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "decision_type": self.decision_type,
+            "what_changed": self.what_changed,
+            "why": self.why,
+            "do_not": self.do_not,
+            "evidence": list(self.evidence),
+            "confidence": round(self.confidence, 2),
+        }
+
+
+def _format_commits_for_prompt(commits: Sequence[Commit]) -> str:
+    parts: list[str] = []
+    for c in commits:
+        parts.append(f"COMMIT {c.sha[:12]}  ({c.author_name}, {c.authored_at.date()})")
+        parts.append(f"Subject: {c.subject}")
+        if c.body:
+            parts.append(f"Body:\n{c.body}")
+        parts.append("---")
+    return "\n".join(parts)
+
+
+_VALID_TYPES = frozenset(
+    {
+        "incident_fix",
+        "compat_workaround",
+        "perf_rewrite",
+        "rollback",
+        "constraint",
+        "other",
+    }
+)
+
+
+def _strip_code_fence(raw: str) -> str:
+    raw = raw.strip()
+    raw = re.sub(r"^```(?:json)?\s*", "", raw)
+    raw = re.sub(r"\s*```\s*$", "", raw)
+    return raw.strip()
+
+
+def _parse_decisions(raw: str, valid_shas: Sequence[str]) -> list[Decision]:
+    """Lenient parser. Bad JSON → empty list (we do not crash on a bad model
+    response). Missing fields default to empty/zero. Invalid evidence SHAs
+    are dropped silently."""
+    text = _strip_code_fence(raw)
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError:
+        return []
+    if not isinstance(data, list):
+        return []
+    short_lookup = {s[:12]: s for s in valid_shas}
+    out: list[Decision] = []
+    for item in data:
+        if not isinstance(item, dict):
+            continue
+        try:
+            decision_type = str(item.get("decision_type", "other"))
+            if decision_type not in _VALID_TYPES:
+                decision_type = "other"
+            what_changed = str(item.get("what_changed", "")).strip()
+            why = str(item.get("why", "")).strip()
+            do_not_raw = item.get("do_not")
+            do_not = str(do_not_raw).strip() if do_not_raw else None
+            raw_evidence = item.get("evidence", []) or []
+            evidence: list[str] = []
+            for token in raw_evidence:
+                t = str(token).strip()
+                # Accept full or 12-char prefix SHAs that match what we sent.
+                if t in short_lookup:
+                    evidence.append(short_lookup[t])
+                elif len(t) >= 12 and t[:12] in short_lookup:
+                    evidence.append(short_lookup[t[:12]])
+            if not evidence and valid_shas:
+                evidence = [valid_shas[0]]
+            confidence = float(item.get("confidence", 0.0))
+            confidence = max(0.0, min(1.0, confidence))
+        except (TypeError, ValueError):
+            continue
+        if not what_changed or not why:
+            continue
+        out.append(
+            Decision(
+                decision_type=decision_type,
+                what_changed=what_changed,
+                why=why,
+                do_not=do_not,
+                evidence=tuple(evidence),
+                confidence=confidence,
+            )
+        )
+    return out
+
+
+def estimate_payload(commits: Sequence[Commit]) -> tuple[int, int]:
+    """Return ``(commit_count, prompt_char_count)`` so callers can show the
+    user the exact size of what would be sent before invoking the network.
+    """
+    if not commits:
+        return 0, 0
+    prompt = _PROMPT_TEMPLATE.format(commits=_format_commits_for_prompt(commits))
+    return len(commits), len(prompt) + len(_SYSTEM)
+
+
+def extract_decisions(
+    commits: Sequence[Commit],
+    *,
+    min_confidence: float = DEFAULT_MIN_CONFIDENCE,
+) -> list[Decision]:
+    """Send ``commits`` to the configured LLM and parse structured decisions.
+
+    Raises ``LLMConfigError`` when the environment is not set up; raises
+    ``LLMCallError`` on transport / API failure. Returns ``[]`` on empty
+    input or a malformed model response.
+    """
+    if not commits:
+        return []
+    prompt = _PROMPT_TEMPLATE.format(commits=_format_commits_for_prompt(commits))
+    raw = call_llm(prompt, _SYSTEM)
+    decisions = _parse_decisions(raw, [c.sha for c in commits])
+    return [d for d in decisions if d.confidence >= min_confidence]
+
+
+__all__ = [
+    "DEFAULT_MAX_COMMITS",
+    "DEFAULT_MIN_CONFIDENCE",
+    "Decision",
+    "LLMCallError",
+    "LLMConfigError",
+    "estimate_payload",
+    "extract_decisions",
+]

whycode/llm.py

@@ -0,0 +1,112 @@
+"""Provider-neutral LLM client wrapper for the optional L3 layer.
+
+L3 is opt-in. Off by default. The CLI must require an explicit ``--llm``
+flag and the user must set their own API key. This module never embeds
+provider names, model identifiers, or default keys in source code —
+configuration lives entirely in environment variables, so the source tree
+itself does not advertise any specific vendor.
+
+Required:
+  ``WHYCODE_LLM_API_KEY``    Your provider's API key.
+  ``WHYCODE_LLM_MODEL``      Your provider's model identifier (string).
+
+Optional:
+  ``WHYCODE_LLM_MAX_TOKENS`` Output cap (default 2000).
+
+The actual provider SDK is loaded lazily (``pip install 'whycode-cli[llm]'``)
+so users who never invoke L3 do not pay the import cost or force a
+dependency on any AI SDK.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+
+class LLMConfigError(RuntimeError):
+    """Raised when L3 is invoked without sufficient configuration."""
+
+
+class LLMCallError(RuntimeError):
+    """Raised when the underlying provider call fails."""
+
+
+@dataclass(frozen=True)
+class LLMConfig:
+    api_key: str
+    model: str
+    max_tokens: int = 2000
+
+
+def _read_config() -> LLMConfig:
+    """Read configuration from environment variables.
+
+    No defaults for ``api_key`` or ``model`` — both must be set explicitly.
+    The error message points the user at the ``--llm-dry-run`` flag for
+    self-service auditing.
+    """
+    api_key = os.environ.get("WHYCODE_LLM_API_KEY", "").strip()
+    model = os.environ.get("WHYCODE_LLM_MODEL", "").strip()
+    if not api_key:
+        raise LLMConfigError(
+            "WHYCODE_LLM_API_KEY is not set. To use --llm:\n"
+            "  1. Get an API key from your LLM provider.\n"
+            "  2. export WHYCODE_LLM_API_KEY=…\n"
+            "  3. export WHYCODE_LLM_MODEL=<your-provider's-model-identifier>\n"
+            "  Use --llm-dry-run first to see exactly what would be sent."
+        )
+    if not model:
+        raise LLMConfigError(
+            "WHYCODE_LLM_MODEL is not set. Set it to your provider's model "
+            "identifier (consult your provider's docs for available models)."
+        )
+    raw_max = os.environ.get("WHYCODE_LLM_MAX_TOKENS", "2000").strip()
+    try:
+        max_tokens = int(raw_max)
+    except ValueError:
+        max_tokens = 2000
+    return LLMConfig(api_key=api_key, model=model, max_tokens=max_tokens)
+
+
+def call_llm(prompt: str, system: str) -> str:
+    """Send ``prompt`` (with ``system`` instruction) to the configured LLM.
+
+    Returns the assistant's text response. Raises ``LLMConfigError`` if the
+    environment is not set up or the provider SDK is missing; raises
+    ``LLMCallError`` on transport / API failure.
+
+    The provider SDK is loaded lazily inside this call to keep the import
+    out of the cold path. This matches the architectural rule that L1+L2
+    must run with zero network and zero LLM dependencies.
+    """
+    cfg = _read_config()
+    try:
+        # Lazy import — the SDK is in the optional ``[llm]`` extras and is
+        # not required for the rest of WhyCode. Keep the package name out
+        # of any user-facing strings.
+        client_module = __import__("anthropic")
+    except ImportError as exc:
+        raise LLMConfigError(
+            "LLM support not installed. Run: pip install 'whycode-cli[llm]'"
+        ) from exc
+    try:
+        client = client_module.Anthropic(api_key=cfg.api_key)
+        msg = client.messages.create(
+            model=cfg.model,
+            max_tokens=cfg.max_tokens,
+            system=system,
+            messages=[{"role": "user", "content": prompt}],
+        )
+    except Exception as exc:
+        raise LLMCallError(f"LLM call failed: {exc}") from exc
+    # Anthropic returns a list of content blocks; concatenate text-typed ones.
+    parts: list[str] = []
+    for block in getattr(msg, "content", []):
+        text = getattr(block, "text", None)
+        if isinstance(text, str):
+            parts.append(text)
+    return "".join(parts)
+
+
+__all__ = ["LLMCallError", "LLMConfig", "LLMConfigError", "call_llm"]

whycode/mcp_server.py

@@ -9,6 +9,20 @@ Tools
 - ``get_file_decisions(path, limit=5)`` — decision-flavoured signals only
   (incidents, reverts, invariants), highest severity first.
 
+Prompts
+-------
+Reusable prompt templates the host can offer the user as one-click actions.
+The server fills in WhyCode data; the host LLM does the actual reasoning.
+No outbound network calls happen here -- prompts are pure local data plus a
+short instruction wrapper, exactly like tools.
+
+- ``before_edit_checklist(path)`` -- fetch the Risk Card and ask the model to
+  walk the user through every HIGH-severity signal before suggesting an edit.
+- ``summarise_for_postmortem(sha)`` -- fetch a commit's metadata and
+  classification and ask the model to draft a postmortem-ready summary.
+- ``risk_briefing_for_pr(base)`` -- fetch the diff risk briefing and ask the
+  model to summarise it for a reviewer in 3-5 bullets.
+
 The server speaks stdio. Configure your client with:
 
     {
@@ -29,7 +43,14 @@ from typing import Any
 
 from mcp.server import Server
 from mcp.server.stdio import stdio_server
-from mcp.types import TextContent, Tool
+from mcp.types import (
+    GetPromptResult,
+    Prompt,
+    PromptArgument,
+    PromptMessage,
+    TextContent,
+    Tool,
+)
 
 from whycode import git_facts as gf
 from whycode import risk_card as rc
@@ -121,6 +142,18 @@ def _build_server(verbose: bool = False) -> Server:
             return _handle_file_decisions(arguments)
         raise ValueError(f"Unknown tool: {name}")
 
+    @server.list_prompts()  # type: ignore[no-untyped-call,untyped-decorator]
+    async def _list_prompts() -> list[Prompt]:
+        return list(_PROMPTS)
+
+    @server.get_prompt()  # type: ignore[no-untyped-call,untyped-decorator]
+    async def _get_prompt(
+        name: str, arguments: dict[str, str] | None
+    ) -> GetPromptResult:
+        if verbose:
+            _log_call(f"prompt:{name}", dict(arguments or {}))
+        return _render_prompt(name, arguments or {})
+
     return server
 
 
@@ -184,6 +217,278 @@ def _handle_file_decisions(arguments: dict[str, Any]) -> list[TextContent]:
     return [TextContent(type="text", text=json.dumps(payload, indent=2))]
 
 
+# ---------------------------------------------------------------------------
+# Prompts
+# ---------------------------------------------------------------------------
+#
+# Prompts are saved-search shortcuts: the host editor surfaces them as
+# one-click actions; the server fills in WhyCode data; the host LLM does
+# the reasoning. They never make outbound network calls -- the data is
+# strictly local git history, exactly like the tool surface.
+
+_BEFORE_EDIT = "before_edit_checklist"
+_POSTMORTEM = "summarise_for_postmortem"
+_PR_BRIEFING = "risk_briefing_for_pr"
+
+_PROMPTS: tuple[Prompt, ...] = (
+    Prompt(
+        name=_BEFORE_EDIT,
+        description=(
+            "Fetch the Risk Card for a file and ask the assistant to walk the "
+            "user through every HIGH-severity signal before suggesting any edit. "
+            "Call this from the editor before you start changing an unfamiliar file."
+        ),
+        arguments=[
+            PromptArgument(
+                name="path",
+                description="Path to the file (absolute or repo-relative).",
+                required=True,
+            ),
+        ],
+    ),
+    Prompt(
+        name=_POSTMORTEM,
+        description=(
+            "Fetch a commit's metadata and WhyCode classification and ask the "
+            "assistant to draft a concise incident summary suitable for a "
+            "postmortem document, citing specific evidence SHAs."
+        ),
+        arguments=[
+            PromptArgument(
+                name="sha",
+                description="Commit SHA (full or short) to summarise.",
+                required=True,
+            ),
+        ],
+    ),
+    Prompt(
+        name=_PR_BRIEFING,
+        description=(
+            "Fetch the WhyCode risk briefing for files changed against a base "
+            "ref and ask the assistant to summarise it for a PR reviewer in "
+            "3-5 bullets, emphasising HANDLE WITH CARE files."
+        ),
+        arguments=[
+            PromptArgument(
+                name="base",
+                description="Base ref to diff against (e.g. origin/main, main, HEAD~1).",
+                required=True,
+            ),
+        ],
+    ),
+)
+
+
+def _missing_arg(name: str, arg: str) -> GetPromptResult:
+    """Render a friendly error as a user-role message, so the host displays it."""
+    text = f"WhyCode prompt {name!r} requires the {arg!r} argument."
+    return GetPromptResult(
+        description=text,
+        messages=[
+            PromptMessage(role="user", content=TextContent(type="text", text=text)),
+        ],
+    )
+
+
+def _git_error(name: str, exc: gf.GitError) -> GetPromptResult:
+    text = f"WhyCode prompt {name!r} could not run: {exc}"
+    return GetPromptResult(
+        description=text,
+        messages=[
+            PromptMessage(role="user", content=TextContent(type="text", text=text)),
+        ],
+    )
+
+
+def _render_prompt(name: str, arguments: dict[str, str]) -> GetPromptResult:
+    if name == _BEFORE_EDIT:
+        return _render_before_edit(arguments)
+    if name == _POSTMORTEM:
+        return _render_postmortem(arguments)
+    if name == _PR_BRIEFING:
+        return _render_pr_briefing(arguments)
+    raise ValueError(f"Unknown prompt: {name}")
+
+
+def _format_card_for_prompt(card: rc.RiskCard) -> str:
+    """Render a Risk Card as plain text fit for embedding in a prompt body."""
+    lines: list[str] = []
+    lines.append(
+        f"file: {card.path}\n"
+        f"band: {card.score.band.value}\n"
+        f"score: {card.score.value}/100\n"
+        f"commits: {card.commit_count}"
+    )
+    if card.most_recent_subject:
+        lines.append(
+            f"latest: {card.most_recent_sha} -- {card.most_recent_subject} "
+            f"({card.most_recent_author})"
+        )
+    if not card.signals:
+        lines.append("signals: none fired")
+        return "\n".join(lines)
+    lines.append("signals:")
+    for s in card.signals:
+        sev = "HIGH" if s.severity >= 4 else "MED" if s.severity == 3 else "LOW"
+        lines.append(f"  [{sev}] {s.kind.value}: {s.headline}")
+        if s.detail:
+            lines.append(f"      {s.detail}")
+        if s.evidence:
+            lines.append(f"      evidence: {', '.join(s.evidence)}")
+    return "\n".join(lines)
+
+
+def _render_before_edit(arguments: dict[str, str]) -> GetPromptResult:
+    path = arguments.get("path")
+    if not path:
+        return _missing_arg(_BEFORE_EDIT, "path")
+    try:
+        repo_root, rel = _resolve(path)
+        card = rc.build(repo_root, rel)
+    except gf.GitError as exc:
+        return _git_error(_BEFORE_EDIT, exc)
+
+    high_signals = [s for s in card.signals if s.severity >= 4]
+    body = (
+        "WhyCode pulled the following Risk Card from local git history.\n"
+        "Before suggesting any edit to this file, walk the user through every "
+        "HIGH-severity signal below and ask them to confirm they understand "
+        "each one. Quote the headline verbatim and cite the evidence SHAs. "
+        "If no HIGH signals fired, say so explicitly and remind the user to "
+        "read the diff anyway.\n\n"
+        f"{_format_card_for_prompt(card)}\n\n"
+        f"high-severity signals: {len(high_signals)}"
+    )
+    return GetPromptResult(
+        description=(
+            f"Pre-edit checklist for {card.path}: "
+            f"{card.score.band.value} ({card.score.value}/100), "
+            f"{len(high_signals)} HIGH-severity signal(s)."
+        ),
+        messages=[
+            PromptMessage(role="user", content=TextContent(type="text", text=body)),
+        ],
+    )
+
+
+def _render_postmortem(arguments: dict[str, str]) -> GetPromptResult:
+    sha = arguments.get("sha")
+    if not sha:
+        return _missing_arg(_POSTMORTEM, "sha")
+    try:
+        repo_root = gf.discover_repo_root(Path.cwd())
+    except gf.GitError as exc:
+        return _git_error(_POSTMORTEM, exc)
+    commit = gf.read_commit(repo_root, sha)
+    if commit is None:
+        return _git_error(_POSTMORTEM, gf.GitError(f"could not read commit {sha!r}"))
+
+    classification = gf.classify_commit(commit)
+    invariants = gf.extract_invariant_quotes([commit])
+    file_changes = gf.files_changed_in(repo_root, commit.sha)
+
+    badges: list[str] = []
+    if classification.incident_flavoured:
+        badges.append("incident-flavoured")
+    if invariants:
+        badges.append(f"states {len(invariants)} invariant(s)")
+    if not badges:
+        badges.append("no special classification")
+
+    lines: list[str] = []
+    lines.append(f"sha: {commit.sha[:12]}")
+    lines.append(f"author: {commit.author_name} <{commit.author_email}>")
+    lines.append(f"authored_at: {commit.authored_at.isoformat()}")
+    lines.append(f"subject: {commit.subject}")
+    lines.append(f"classification: {', '.join(badges)}")
+    lines.append(f"files_changed: {len(file_changes)}")
+    if commit.body:
+        lines.append("body:")
+        for raw_line in commit.body.splitlines():
+            lines.append(f"  {raw_line}")
+    if invariants:
+        lines.append("invariants stated by this commit:")
+        for inv_sha, inv_line in invariants:
+            lines.append(f"  ({inv_sha[:7]}) {inv_line}")
+    if file_changes:
+        lines.append("paths touched:")
+        for change in file_changes[:20]:
+            lines.append(f"  {change.path}")
+        if len(file_changes) > 20:
+            lines.append(f"  ... and {len(file_changes) - 20} more")
+
+    body = (
+        "WhyCode pulled the following commit metadata from local git history.\n"
+        "Compose a concise incident summary suitable for a postmortem "
+        "document. Cover what changed, why (drawing on the commit body), "
+        "which files were touched, and any invariants the author stated. "
+        "Cite specific evidence SHAs verbatim -- never invent commits not "
+        "listed below. Keep it under 200 words; use plain prose, not bullet "
+        "lists.\n\n" + "\n".join(lines)
+    )
+    return GetPromptResult(
+        description=(
+            f"Postmortem summary for {commit.sha[:12]}: "
+            f"{', '.join(badges)}."
+        ),
+        messages=[
+            PromptMessage(role="user", content=TextContent(type="text", text=body)),
+        ],
+    )
+
+
+def _render_pr_briefing(arguments: dict[str, str]) -> GetPromptResult:
+    base = arguments.get("base")
+    if not base:
+        return _missing_arg(_PR_BRIEFING, "base")
+    try:
+        repo_root = gf.discover_repo_root(Path.cwd())
+        raw = gf.run_git(repo_root, "diff", "--name-only", f"{base}...HEAD")
+    except gf.GitError as exc:
+        return _git_error(_PR_BRIEFING, exc)
+
+    files = [line for line in raw.splitlines() if line.strip()]
+    cards: list[rc.RiskCard] = []
+    for f in files:
+        try:
+            cards.append(rc.build(repo_root, f))
+        except gf.GitError:
+            continue
+    cards.sort(key=lambda c: -c.score.value)
+
+    lines: list[str] = []
+    lines.append(f"base: {base}")
+    lines.append(f"files_changed: {len(files)}")
+    if not cards:
+        lines.append("no files with computable risk against this base")
+    else:
+        lines.append("risk-ranked files (highest first):")
+        for c in cards[:20]:
+            top = c.signals[0].headline if c.signals else "no flags"
+            lines.append(
+                f"  [{c.score.value:>3}] {c.score.band.value:<20} "
+                f"{c.path} -- {top}"
+            )
+
+    body = (
+        "WhyCode produced the following risk briefing for files changed "
+        "against the base ref. Summarise it for a PR reviewer in 3-5 bullets, "
+        "putting HANDLE WITH CARE files first and naming each by path and "
+        "top signal. Do not invent risk that is not listed below; if the "
+        "briefing is empty, say so honestly.\n\n" + "\n".join(lines)
+    )
+    handle_with_care = [c for c in cards if c.score.band.value == "HANDLE WITH CARE"]
+    return GetPromptResult(
+        description=(
+            f"PR risk briefing vs {base}: {len(files)} file(s), "
+            f"{len(handle_with_care)} HANDLE WITH CARE."
+        ),
+        messages=[
+            PromptMessage(role="user", content=TextContent(type="text", text=body)),
+        ],
+    )
+
+
 async def _run(verbose: bool) -> None:
     server = _build_server(verbose=verbose)
     if verbose:

whycode/risk_card.py

@@ -24,6 +24,8 @@ from whycode.scorer import Band, Score, score
 if TYPE_CHECKING:
     from pathlib import Path
 
+    from whycode.decisions import Decision
+
 
 @dataclass(frozen=True)
 class RiskCard:
@@ -38,6 +40,15 @@ class RiskCard:
     as_of_sha: str | None = None
     """When set, the card was computed *as of* this commit (historical view)."""
 
+    decisions: tuple[Decision, ...] = ()
+    """L3 — LLM-extracted structured decisions. Empty unless ``--llm`` was on."""
+
+    def with_decisions(self, decisions: tuple[Decision, ...]) -> RiskCard:
+        """Return a copy with the L3 ``decisions`` field populated."""
+        from dataclasses import replace
+
+        return replace(self, decisions=decisions)
+
     def to_dict(self) -> dict[str, Any]:
         return {
             "path": self.path,
@@ -65,6 +76,7 @@ class RiskCard:
                 }
                 for s in self.signals
             ],
+            "decisions": [d.to_dict() for d in self.decisions],
         }
 
 
@@ -190,11 +202,40 @@ def _next_step_hint(signals: tuple[sig.Signal, ...]) -> Text | None:
     return None
 
 
+def _decisions_block(decisions: tuple[Decision, ...]) -> Padding:
+    """Render the L3 decisions section inside a labelled panel."""
+    body = Text()
+    for i, d in enumerate(decisions):
+        if i:
+            body.append("\n\n")
+        # Header: type + confidence badge.
+        body.append(f"{d.decision_type.replace('_', ' ').upper()}", style="bold cyan")
+        body.append(f"   confidence {int(d.confidence * 100)}%\n", style="dim")
+        body.append(d.what_changed + "\n", style="bold")
+        body.append("Why: ", style="dim")
+        body.append(d.why + "\n", style="italic")
+        if d.do_not:
+            body.append("Don't: ", style="bold red")
+            body.append(d.do_not + "\n", style="")
+        if d.evidence:
+            short = ", ".join(s[:7] for s in d.evidence)
+            body.append(f"evidence: {short}", style="dim")
+    panel = Panel(
+        body,
+        title=Text(" DECISIONS (L3) ", style="bold white on magenta"),
+        title_align="left",
+        border_style="grey50",
+    )
+    return Padding(panel, (1, 1, 0, 1))
+
+
 def render_text(card: RiskCard) -> Group:
     pieces: list[Any] = [
         _header(card),
         Padding(_signals_table(card.signals), (0, 1, 0, 1)),
     ]
+    if card.decisions:
+        pieces.append(_decisions_block(card.decisions))
     hint = _next_step_hint(card.signals)
     if hint is not None:
         pieces.append(Padding(hint, (0, 1, 1, 2)))

{whycode_cli-0.2.6.dist-info → whycode_cli-0.3.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: whycode-cli
-Version: 0.2.6
+Version: 0.3.1
 Summary: Tells you what to be afraid of before you touch a file.
 Author: Kevin
 License-Expression: MIT
@@ -19,6 +19,8 @@ Requires-Dist: typer>=0.12
 Requires-Dist: rich>=13.7
 Provides-Extra: mcp
 Requires-Dist: mcp>=1.0; extra == "mcp"
+Provides-Extra: llm
+Requires-Dist: anthropic>=0.40; extra == "llm"
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
 Requires-Dist: pytest-cov>=5; extra == "dev"
@@ -197,11 +199,32 @@ Tune the thresholds inside those two files for your repo. Re-run with
 | ----- | ------------------------------------------------------------------------ | -------- | -------- |
 | 1     | Deterministic git facts (log, diffstat, revert pairs, author activity)   | no       | no       |
 | 2     | Heuristic signals (reverts, incidents, silence, ghost keeper, coupling, invariants, churn, newborn) | no | no |
-| 3     | LLM polish (optional, opt-in, never on by default)                       | yes      | yes      |
+| 3     | LLM-extracted structured decisions (optional, opt-in, never on by default) | yes      | yes      |
 
-**Layer 1 + Layer 2 produce the Risk Card you saw above. No model calls, no
-data leaving your machine.** Layer 3 is reserved for natural-language
-summarisation of decisions and is strictly opt-in.
+**Layer 1 + Layer 2 produce the Risk Card by default. No model calls, no
+data leaving your machine.** Layer 3 lifts the keyword fragments L1 + L2
+extract ("do not switch to async") into structured decisions with the
+*why* drawn from the surrounding commit body — but only when you ask for
+it with `--llm`.
+
+### Optional L3 — LLM-enriched decisions
+
+Install the optional extras and configure the env vars:
+
+```bash
+pip install 'whycode-cli[llm]'
+export WHYCODE_LLM_API_KEY="…"
+export WHYCODE_LLM_MODEL="<your-provider's-model-identifier>"
+
+whycode why src/some/file.py --llm        # full card + structured decisions
+whycode why src/some/file.py --llm-dry-run  # see exactly what would be sent
+```
+
+Privacy contract: configuration is entirely environment-driven (no
+hardcoded provider in the source tree); the SDK is lazy-imported (no
+import cost unless you opt in); only L2-filtered high-signal commits
+are sent (capped at 10 per call); a malformed model response degrades
+to "no decisions" rather than crashing.
 
 ## What this is NOT
 

{whycode_cli-0.2.6.dist-info → whycode_cli-0.3.1.dist-info}/RECORD

@@ -1,19 +1,21 @@
-whycode/__init__.py,sha256=PX9ljfWyjwwJEA1_I-kk34Qfj-9N3WRnXy1zQ6i6t-M,96
+whycode/__init__.py,sha256=wiigWjNrflQT6-gb-awqXO00CNvVX6-2SUb97zVDBbQ,96
 whycode/__main__.py,sha256=dqAk6746YpuM-FTIH4TBOULegGc5WweojiZjce0VYgQ,105
-whycode/cli.py,sha256=JTufemrXaq-3ySNG-xfPZ0f5UhbtThiD4TXWSxE5qZ4,37365
+whycode/cli.py,sha256=PApJADeJfU4I1-PJhJebeTovGRgEl6-gUlMV-3q2dng,39823
+whycode/decisions.py,sha256=oCVhEF7QfHeci0LAWNtEjV2mUAEBJloL1rT3I4XXbkw,7570
 whycode/git_facts.py,sha256=VozSt59dWhUcDQ2qyDA2Bfa6AWvfBmIaQKP1DAYUpPM,17820
 whycode/ignore.py,sha256=sdRO_0HSedm8aO69CSGl-zQrUVX5MEg9QGcAJWwAvP4,3021
-whycode/mcp_server.py,sha256=56csOHSP90Zk59-_Puvk4WTSlCJ6xQAm-K10b_qmyAQ,7105
-whycode/risk_card.py,sha256=iIk4MkQQrlnj782dxdfoogUcByunI5j6y8vUnuhByAA,6996
+whycode/llm.py,sha256=leB94pBg8kUCq_BujZq5ixny0urGtKskjdaKoum_eCA,4092
+whycode/mcp_server.py,sha256=ht1tStAkOwmQzNIRkm1eA8Tnc59fzDRSGkgyIprft-0,18503
+whycode/risk_card.py,sha256=wxmGAR0FhioTHQfNUCQN-ouwRp0IqI45AkOZ85ya4Eo,8616
 whycode/scorer.py,sha256=4pBejunfxzYhGUzMeL8uGEMQzC6DWiqwcTeMdo3eras,1444
 whycode/signals.py,sha256=14KziRolXvhmOnMnluXpPPInoBRO5uDu0tm024EYik0,13066
 whycode/suppressions.py,sha256=1lKSs-kCgpnJbcxozcgiSP8ZAfjEDMHXuM3sw4FaY78,3836
 whycode/templates/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 whycode/templates/github-workflow.yml,sha256=LAfHMDG2TkAwi4vCNinHk-4zOt-mCWErBpmpaqlW5oA,2251
 whycode/templates/pre-commit,sha256=IhU11CvoDwqRAAsvHwUo-BwaNbdgy1cpXc54Z_phrmQ,316
-whycode_cli-0.2.6.dist-info/licenses/LICENSE,sha256=U6LN5qg5kJXSJf7KFPm9KJhmiGn3qK_GsTVWXdt1DFA,1062
-whycode_cli-0.2.6.dist-info/METADATA,sha256=zp9iSlF6ymPkl2om4iaza9CshWA_aHyETjFs7MbPJIg,9327
-whycode_cli-0.2.6.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-whycode_cli-0.2.6.dist-info/entry_points.txt,sha256=xrNWc4CQn3ZhQFJxsGIPiTqpN19K4pRpgaj6qGaEzSQ,44
-whycode_cli-0.2.6.dist-info/top_level.txt,sha256=6yIL5rxW-4DbARHQYrPlGQVqKddZ88sjvmNosDh1w3A,8
-whycode_cli-0.2.6.dist-info/RECORD,,
+whycode_cli-0.3.1.dist-info/licenses/LICENSE,sha256=U6LN5qg5kJXSJf7KFPm9KJhmiGn3qK_GsTVWXdt1DFA,1062
+whycode_cli-0.3.1.dist-info/METADATA,sha256=HXmG_VsgYUO_s1LMVZ3W5nHOEgBPnD_3ZP6Iarf5fmM,10218
+whycode_cli-0.3.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+whycode_cli-0.3.1.dist-info/entry_points.txt,sha256=xrNWc4CQn3ZhQFJxsGIPiTqpN19K4pRpgaj6qGaEzSQ,44
+whycode_cli-0.3.1.dist-info/top_level.txt,sha256=6yIL5rxW-4DbARHQYrPlGQVqKddZ88sjvmNosDh1w3A,8
+whycode_cli-0.3.1.dist-info/RECORD,,