diffly-cli 0.4.0__tar.gz → 1.0.0__tar.gz

{diffly_cli-0.4.0 → diffly_cli-1.0.0}/CHANGELOG.md

@@ -4,6 +4,25 @@ All notable changes to diffly are documented here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [1.0.0] - 2026-08-22
+
+Diffly 1.0.0 is the first production-ready release of the deterministic pull-request triage workflow. It stabilizes the command-line experience, interactive review, local analysis, GitHub Action, and explanation behavior around a clear three-outcome policy: healthy pull requests pass, focused review gates quarantine, and severe failures block.
+
+### Added
+
+- Reliable opted-in explanations: Diffly uses the configured AI provider when available and otherwise renders a clearly labelled local explanation from deterministic review facts.
+- Automatic reuse of an authenticated `gh` session when `GITHUB_TOKEN` is not set.
+- A centred terminal experience across the guided wizard, loading transition, interactive review, diagnostics, and focused report.
+- Local analysis, stable JSON output, interactive review, GitHub Action integration, an update workflow, diagnostics, and guided setup as supported 1.0.0 workflows.
+
+### Changed
+
+- Rebalanced verdicts so `PASS` is the normal healthy outcome. Missing obvious test coverage, unavailable checks, and incomplete repository-tree hints remain visible as review notes instead of automatically forcing `QUARANTINE`.
+- `QUARANTINE` is reserved for concrete review gates: security-sensitive code, database schema or migrations, dependency changes, and pending required checks.
+- `BLOCK` is reserved for failed required checks and high-confidence credential exposure in a changed hunk.
+- The guided prompts and recovery messages now give clearer next steps.
+- Updated Diffly’s visual identity with the refreshed logo and terminal loading mark.
+
 ### Fixed
 
 - Interactive mode no longer breaks imports on platforms without POSIX terminal support; it now falls back to the standard report.

{diffly_cli-0.4.0 → diffly_cli-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: diffly-cli
-Version: 0.4.0
+Version: 1.0.0
 Summary: Deterministic triage for large GitHub pull requests
 Author: Vivaan Dhawan
 License: MIT License — diffly
@@ -128,7 +128,7 @@ Requires-Dist: pyyaml>=6; extra == 'dev'
 Description-Content-Type: text/markdown
 
 <p align="center">
-  <img src="assets/logo.png" alt="diffly logo" width="140">
+  <img src="assets/logo-v2.svg" alt="diffly logo" width="280">
 </p>
 
 # ⚡ diffly
@@ -141,7 +141,7 @@ Description-Content-Type: text/markdown
 
 <p align="center">
   <a href="https://github.com/VIVAAN-DHAWAN/diffly-cli/actions/workflows/ci.yml"><img src="https://img.shields.io/badge/CI-passing-brightgreen?style=for-the-badge&logo=githubactions" alt="CI"></a>
-  <a href="https://github.com/VIVAAN-DHAWAN/diffly-cli/releases/latest"><img src="https://img.shields.io/badge/release-v0.4.0-blue?style=for-the-badge" alt="Release"></a>
+  <a href="https://github.com/VIVAAN-DHAWAN/diffly-cli/releases/latest"><img src="https://img.shields.io/badge/release-v1.0.0-blue?style=for-the-badge" alt="Release"></a>
   <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.10%2B-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="Python 3.10+"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=for-the-badge" alt="License: MIT"></a>
 </p>
@@ -161,7 +161,6 @@ curl -fsSL https://raw.githubusercontent.com/VIVAAN-DHAWAN/diffly-cli/main/insta
 ```bash
 pip install diffly-cli
 ```
-
 **uv**
 ```bash
 uv tool install diffly-cli
@@ -270,6 +269,8 @@ For automation prefer `--json`: successful triage exits `0` regardless of verdic
 
 ### Optional AI explanation
 
+Every opted-in explanation is shown in the review. With an AI key, Diffly produces a bounded, redacted AI narrative; without one—or if the provider is unavailable—it creates a clearly labelled local explanation from deterministic review facts instead. Neither path can alter the verdict.
+
 ```bash
 export DIFFLY_LLM_API_KEY="your-key"
 export DIFFLY_LLM_BASE_URL="https://api.openai.com/v1"  # omit for the default endpoint
@@ -282,11 +283,11 @@ Default model is `gpt-5-mini`; override with `DIFFLY_LLM_MODEL` or `--llm-model`
 
 | Verdict | Rule |
 | --- | --- |
-| **BLOCK** | A required check failed, or the PR touches authentication, credentials, secrets, or security-sensitive files. |
-| **QUARANTINE** | Database schema/migrations, dependency changes, missing obvious test coverage for production files, or unavailable/pending checks. |
-| **PASS** | No rule fired and observed checks passed. `SHIP` remains accepted as a legacy alias. |
+| **BLOCK** | A required check failed, or the changed hunk appears to add a credential-like value. |
+| **QUARANTINE** | Security-sensitive code, database schema/migrations, dependency changes, or still-pending checks need focused review. |
+| **PASS** | No blocking or quarantine rule fired. Missing obvious tests and unavailable checks stay visible as review notes, but do not turn an otherwise healthy PR into `QUARANTINE`. `SHIP` remains accepted as a legacy alias. |
 
-Deliberately conservative: a verdict is a review gate, not a claim that a PR is correct or safe in every context.
+`PASS` is the normal healthy outcome. A verdict is a review signal, not a claim that a PR is correct or safe in every context.
 
 ## Real examples
 
@@ -304,7 +305,7 @@ Live AI-explainer reports (deterministic verdict preserved): [ruff phase 2](demo
 
 ## Current limitations
 
-The Phase 2 explainer requires an OpenAI-compatible API key and never influences the verdict. Tree-sitter parsing covers symbols and direct calls visible in changed hunks, not a full repository-wide call graph. Test-coverage detection is heuristic (filenames + repository tree). Unavailable checks are quarantined rather than assumed passing. Model context is bounded and may truncate on very large PRs.
+Tree-sitter parsing covers symbols and direct calls visible in changed hunks, not a full repository-wide call graph. Test-coverage detection is heuristic (filenames + repository tree), so it is presented as a review note rather than a verdict gate. AI model context is bounded and may truncate on very large PRs. A local explanation is used when AI generation is not available.
 
 ## Roadmap
 

{diffly_cli-0.4.0 → diffly_cli-1.0.0}/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="assets/logo.png" alt="diffly logo" width="140">
+  <img src="assets/logo-v2.svg" alt="diffly logo" width="280">
 </p>
 
 # ⚡ diffly
@@ -12,7 +12,7 @@
 
 <p align="center">
   <a href="https://github.com/VIVAAN-DHAWAN/diffly-cli/actions/workflows/ci.yml"><img src="https://img.shields.io/badge/CI-passing-brightgreen?style=for-the-badge&logo=githubactions" alt="CI"></a>
-  <a href="https://github.com/VIVAAN-DHAWAN/diffly-cli/releases/latest"><img src="https://img.shields.io/badge/release-v0.4.0-blue?style=for-the-badge" alt="Release"></a>
+  <a href="https://github.com/VIVAAN-DHAWAN/diffly-cli/releases/latest"><img src="https://img.shields.io/badge/release-v1.0.0-blue?style=for-the-badge" alt="Release"></a>
   <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.10%2B-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="Python 3.10+"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=for-the-badge" alt="License: MIT"></a>
 </p>
@@ -32,7 +32,6 @@ curl -fsSL https://raw.githubusercontent.com/VIVAAN-DHAWAN/diffly-cli/main/insta
 ```bash
 pip install diffly-cli
 ```
-
 **uv**
 ```bash
 uv tool install diffly-cli
@@ -141,6 +140,8 @@ For automation prefer `--json`: successful triage exits `0` regardless of verdic
 
 ### Optional AI explanation
 
+Every opted-in explanation is shown in the review. With an AI key, Diffly produces a bounded, redacted AI narrative; without one—or if the provider is unavailable—it creates a clearly labelled local explanation from deterministic review facts instead. Neither path can alter the verdict.
+
 ```bash
 export DIFFLY_LLM_API_KEY="your-key"
 export DIFFLY_LLM_BASE_URL="https://api.openai.com/v1"  # omit for the default endpoint
@@ -153,11 +154,11 @@ Default model is `gpt-5-mini`; override with `DIFFLY_LLM_MODEL` or `--llm-model`
 
 | Verdict | Rule |
 | --- | --- |
-| **BLOCK** | A required check failed, or the PR touches authentication, credentials, secrets, or security-sensitive files. |
-| **QUARANTINE** | Database schema/migrations, dependency changes, missing obvious test coverage for production files, or unavailable/pending checks. |
-| **PASS** | No rule fired and observed checks passed. `SHIP` remains accepted as a legacy alias. |
+| **BLOCK** | A required check failed, or the changed hunk appears to add a credential-like value. |
+| **QUARANTINE** | Security-sensitive code, database schema/migrations, dependency changes, or still-pending checks need focused review. |
+| **PASS** | No blocking or quarantine rule fired. Missing obvious tests and unavailable checks stay visible as review notes, but do not turn an otherwise healthy PR into `QUARANTINE`. `SHIP` remains accepted as a legacy alias. |
 
-Deliberately conservative: a verdict is a review gate, not a claim that a PR is correct or safe in every context.
+`PASS` is the normal healthy outcome. A verdict is a review signal, not a claim that a PR is correct or safe in every context.
 
 ## Real examples
 
@@ -175,7 +176,7 @@ Live AI-explainer reports (deterministic verdict preserved): [ruff phase 2](demo
 
 ## Current limitations
 
-The Phase 2 explainer requires an OpenAI-compatible API key and never influences the verdict. Tree-sitter parsing covers symbols and direct calls visible in changed hunks, not a full repository-wide call graph. Test-coverage detection is heuristic (filenames + repository tree). Unavailable checks are quarantined rather than assumed passing. Model context is bounded and may truncate on very large PRs.
+Tree-sitter parsing covers symbols and direct calls visible in changed hunks, not a full repository-wide call graph. Test-coverage detection is heuristic (filenames + repository tree), so it is presented as a review note rather than a verdict gate. AI model context is bounded and may truncate on very large PRs. A local explanation is used when AI generation is not available.
 
 ## Roadmap
 

diffly_cli-1.0.0/assets/logo-v2.svg

@@ -0,0 +1,35 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" role="img" aria-labelledby="title description">
+  <title id="title">Diffly logo</title>
+  <description id="description">A mint hexagonal code-diff mark with plus, slash, and minus symbols.</description>
+  <defs>
+    <linearGradient id="mint" x1="104" y1="88" x2="416" y2="424" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#B9FFCB"/>
+      <stop offset=".45" stop-color="#68E5A4"/>
+      <stop offset="1" stop-color="#2EB67D"/>
+    </linearGradient>
+    <linearGradient id="core" x1="138" y1="112" x2="375" y2="405" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#16211F"/>
+      <stop offset="1" stop-color="#0A1114"/>
+    </linearGradient>
+    <filter id="glow" x="-30%" y="-30%" width="160%" height="160%">
+      <feGaussianBlur stdDeviation="8" result="blur"/>
+      <feMerge>
+        <feMergeNode in="blur"/>
+        <feMergeNode in="SourceGraphic"/>
+      </feMerge>
+    </filter>
+  </defs>
+
+  <path d="M256 52 431 153v206L256 460 81 359V153L256 52Z" fill="#0A1114"/>
+  <path d="M256 52 431 153v206L256 460 81 359V153L256 52Z" fill="none" stroke="url(#mint)" stroke-width="18" stroke-linejoin="round"/>
+  <path d="M256 91 397 172v168L256 421 115 340V172L256 91Z" fill="url(#core)" stroke="#6FE9AA" stroke-opacity=".56" stroke-width="4" stroke-linejoin="round"/>
+  <path d="M256 116 375 185v142L256 396 137 327V185L256 116Z" fill="none" stroke="#B9FFCB" stroke-opacity=".12" stroke-width="2" stroke-linejoin="round"/>
+
+  <g fill="url(#mint)" filter="url(#glow)">
+    <rect x="154" y="215" width="82" height="22" rx="11"/>
+    <rect x="184" y="185" width="22" height="82" rx="11"/>
+    <rect x="304" y="274" width="72" height="22" rx="11"/>
+    <path d="M271 177h25l-58 158h-25l58-158Z"/>
+  </g>
+
+</svg>

{diffly_cli-0.4.0 → diffly_cli-1.0.0}/docs/phase-2-contract.md

@@ -28,4 +28,4 @@ The explainer receives PR metadata, deterministic flags and verdict, changed-fil
 
 ## Testing target
 
-Phase 2 is complete only when redaction, schema validation, prompt construction, API failure fallback, deterministic-verdict immutability, CLI integration, and at least one live public pull-request explanation are verified.
+Phase 2 is complete only when redaction, schema validation, prompt construction, a clearly labelled local fallback, deterministic-verdict immutability, CLI integration, and at least one live public pull-request explanation are verified.

{diffly_cli-0.4.0 → diffly_cli-1.0.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "diffly-cli"
-version = "0.4.0"
+version = "1.0.0"
 description = "Deterministic triage for large GitHub pull requests"
 readme = "README.md"
 requires-python = ">=3.10"

{diffly_cli-0.4.0 → diffly_cli-1.0.0}/src/diffly_cli/__init__.py

@@ -1,3 +1,3 @@
 """Deterministic triage for large GitHub pull requests."""
 
-__version__ = "0.4.0"
+__version__ = "1.0.0"

{diffly_cli-0.4.0 → diffly_cli-1.0.0}/src/diffly_cli/cli.py

@@ -9,6 +9,7 @@ import re
 import select
 import shutil
 import sys
+import time
 from typing import Any
 
 from rich.align import Align
@@ -24,7 +25,7 @@ from . import update
 from .astmap import analyze_files
 from .explainer import ExplanationResult, generate_explanation
 from .diffparse import files_from_unified_diff
-from .github import GitHubClient, GitHubError
+from .github import GitHubClient, GitHubError, github_auth_token
 from .local import LocalAnalysisError, build_local_result, resolve_repository_root
 from .models import ChangedFile, PRMetadata, TriageResult
 from .triage import compute_flags, verdict_for
@@ -32,6 +33,12 @@ from .triage import compute_flags, verdict_for
 console = Console()
 VERDICT_STYLES = {"PASS": "bold green", "SHIP": "bold green", "QUARANTINE": "bold yellow", "BLOCK": "bold red"}
 CONTENT_WIDTH = 100
+INTERACTIVE_SECTIONS = (
+    ("verdict", "Verdict", "The decision and the reasons behind it"),
+    ("checks", "Checks", "The latest CI and commit-status results"),
+    ("risks", "Risk flags", "Changes that need extra review"),
+    ("files", "Changed files", "The scope of the pull request"),
+)
 
 
 def center(renderable: Any) -> Any:
@@ -39,6 +46,57 @@ def center(renderable: Any) -> Any:
     return Align.center(renderable, style="")
 
 
+def center_screen(renderable: Any, *, estimated_height: int) -> None:
+    """Clear the terminal and place a small interactive screen near its centre."""
+    console.clear()
+    top_padding = max((console.size.height - estimated_height) // 2, 0)
+    if top_padding:
+        console.print("\n" * top_padding, end="")
+    console.print(center(renderable))
+
+
+def _loading_mark(turn: str) -> Text:
+    """Render a terminal-safe stand-in for the existing Diffly logo.
+
+    Rich targets ordinary text terminals, where raster-image rotation is not
+    portable. The repository logo remains unchanged in ``assets/logo.png``;
+    this small + / − mark mirrors it for the short terminal animation.
+    """
+    mark = Text(justify="center")
+    mark.append("⬡ ", style="bold cyan")
+    mark.append("+ / −", style="bold white")
+    mark.append(f" {turn}", style="bold cyan")
+    return mark
+
+
+def show_loading_screen(message: str) -> None:
+    """Play a short, reduced-motion-friendly loading transition for TTY users."""
+    if not sys.stdout.isatty():
+        return
+    # Enter centre quickly, turn clockwise, pause, then settle upright.
+    frames = (("", 0.08), ("↻", 0.10), ("↻", 0.30), ("", 0.10))
+    for turn, duration in frames:
+        screen = Panel.fit(
+            Text.assemble(
+                _loading_mark(turn),
+                "\n\n",
+                (message, "dim"),
+            ),
+            border_style="cyan",
+            padding=(1, 4),
+        )
+        center_screen(screen, estimated_height=8)
+        time.sleep(duration)
+
+
+def interactive_sections(explanation: ExplanationResult | None) -> list[tuple[str, str, str]]:
+    """Return the report sections shown in the keyboard-driven review menu."""
+    sections = list(INTERACTIVE_SECTIONS)
+    if explanation is not None:
+        sections.append(("explain", "Explanation", "Optional generated context; never changes the verdict"))
+    return sections
+
+
 @dataclass(frozen=True)
 class RepoRef:
     """A repository reference, optionally carrying a PR number from a URL."""
@@ -137,15 +195,21 @@ def _risk_badge(severity: str) -> str:
 
 def render_explanation(explanation: ExplanationResult) -> list[str]:
     lines = ["## Literate diff — generated explanation", ""]
-    if explanation.error:
+    if explanation.error and explanation.explanation is None:
         lines.extend([
             f"> Generated explanation unavailable: {explanation.error}",
             f"> Redactions applied before any model call: {explanation.redactions}",
             "",
         ])
         return lines
+    if explanation.source == "local":
+        lines.extend([
+            "> Generated locally from Diffly's deterministic review facts; no code was sent to an AI service.",
+            *( [f"> Note: {explanation.warning}"] if explanation.warning else [] ),
+        ])
+    else:
+        lines.append(f"> Generated by `{explanation.model}` from bounded, redacted context. This prose cannot change the deterministic verdict.")
     lines.extend([
-        f"> Generated by `{explanation.model}` from bounded, redacted context. This prose cannot change the deterministic verdict.",
         f"> Redactions applied before the model call: {explanation.redactions}",
         "",
         "### Background",
@@ -236,7 +300,7 @@ def render_markdown(result: TriageResult, explanation: ExplanationResult | None
     for file in result.files:
         symbols = ", ".join(file.touched_symbols) if file.touched_symbols else "—"
         lines.append(f"| `{file.path}` | {file.status} | {file.additions} | {file.deletions} | {symbols} |")
-    lines += ["", "## Deterministic policy", "", "- `BLOCK`: failed checks or authentication/secrets/security-sensitive changes.", "- `QUARANTINE`: database changes, dependency changes, missing obvious production test coverage, or unavailable/pending checks.", "- `PASS`: no blocking or quarantine rule fired and observed checks passed.", "", "_Generated by diffly. Deterministic triage is authoritative; any literate-diff prose is optional generated explanation._"]
+    lines += ["", "## Deterministic policy", "", "- `BLOCK`: failed checks or a credential-like value added to a changed hunk.", "- `QUARANTINE`: security-sensitive code, database schema or migration changes, dependency changes, or still-pending checks.", "- `PASS`: no blocking or quarantine signal fired. Missing obvious tests or unavailable checks remain visible as review notes, not verdict gates.", "", "_Generated by diffly. Deterministic triage is authoritative; any literate-diff prose is optional generated explanation._"]
     return "\n".join(lines) + "\n"
 
 
@@ -249,13 +313,20 @@ def _progress(message: str):
 
 def _explanation_lines(explanation: ExplanationResult) -> list[str]:
     """Render the literate-diff explanation as compact lines for the interactive view."""
-    if explanation.error:
+    if explanation.error and explanation.explanation is None:
         hint = ""
         if "API key" in explanation.error:
             hint = "\n[dim]Enable it: export DIFFLY_LLM_API_KEY=... (optional — deterministic triage is unaffected)[/]"
         return [f"[yellow]Generated explanation unavailable:[/] {explanation.error}", hint or "[dim]Deterministic triage above remains authoritative.[/]", ""]
     data = explanation.explanation
-    lines = [f"[dim]Generated by {explanation.model} from bounded, redacted context · cannot change the verdict[/]", "", f"[bold]Background.[/] {data['background']}", f"[bold]Intent.[/] {data['intent']}", "", "[bold]Narrative steps[/]"]
+    if explanation.source == "local":
+        provenance = "[dim]Generated locally from deterministic review facts · no code was sent to an AI service[/]"
+    else:
+        provenance = f"[dim]Generated by {explanation.model} from bounded, redacted context · cannot change the verdict[/]"
+    lines = [provenance]
+    if explanation.warning:
+        lines.append(f"[yellow]{explanation.warning}[/]")
+    lines += ["", f"[bold]Background.[/] {data['background']}", f"[bold]Intent.[/] {data['intent']}", "", "[bold]Narrative steps[/]"]
     for index, step in enumerate(data["narrative"], start=1):
         lines.append(f"  {index}. [cyan]{step['title']}[/] — {step['explanation']}")
         if step["files"]:
@@ -290,47 +361,43 @@ def _section_lines(result: TriageResult, section: str, explanation: ExplanationR
 
 
 def interactive_view(result: TriageResult, explanation: ExplanationResult | None = None) -> None:
-    """Let a reviewer toggle report sections with up/down arrows and space."""
+    """Let a reviewer choose the report sections to include with the keyboard."""
     if not sys.stdin.isatty() or not sys.stdout.isatty():
-        console.print("[yellow]Interactive mode needs a terminal; showing the standard report instead.[/]")
+        console.print("[yellow]Interactive review needs a terminal. Showing the full report instead.[/]")
         console.print(Markdown(render_markdown(result, explanation)))
         return
     try:
         import termios
         import tty
     except ImportError:
-        console.print("[yellow]Interactive mode is unavailable on this platform; showing the standard report instead.[/]")
+        console.print("[yellow]Interactive review is unavailable on this platform. Showing the full report instead.[/]")
         console.print(Markdown(render_markdown(result, explanation)))
         return
-    labels = [("verdict", "Verdict"), ("checks", "Checks"), ("risks", "Risk flags"), ("files", "Changed files")]
-    if explanation is not None:
-        labels.append(("explain", "Explanation"))
-    try:
-        import termios
-        import tty
-    except ImportError:
-        console.print("[yellow]Interactive mode is unavailable on this platform; showing the standard report instead.[/]")
-        console.print(Markdown(render_markdown(result)))
-        return
-    labels = [("verdict", "Verdict"), ("checks", "Checks"), ("risks", "Risk flags"), ("files", "Changed files")]
-    enabled = {key: True for key, _ in labels}
+    labels = interactive_sections(explanation)
+    enabled = {key: True for key, _, _ in labels}
     cursor = 0
     fd = sys.stdin.fileno()
     old = termios.tcgetattr(fd)
     try:
         tty.setcbreak(fd)
         while True:
-            console.clear()
-            console.print(center(Panel.fit("[bold cyan]diffly interactive review[/]  [dim]↑/↓ move · space toggle · enter apply · q quit[/]", border_style="cyan")))
-            menu = Table(show_header=False, box=None, padding=(0, 2))
-            menu.add_column("", width=3)
-            menu.add_column("Section")
-            for index, (key, label) in enumerate(labels):
-                marker = "[cyan]›[/]" if index == cursor else " "
-                state = "[green]on[/]" if enabled[key] else "[dim]off[/]"
-                menu.add_row(marker, f"{label:<18} {state}")
-            console.print(center(menu))
-            console.print(center(Text.from_markup("[dim]Toggle sections to keep the review focused.[/]")))
+            menu = Table(show_header=False, box=None, padding=(0, 1), expand=False)
+            menu.add_column("", width=2)
+            menu.add_column("Section", min_width=16)
+            menu.add_column("Description", min_width=32)
+            menu.add_column("", justify="right", width=9)
+            for index, (key, label, description) in enumerate(labels):
+                marker = "[bold cyan]›[/]" if index == cursor else " "
+                state = "[bold green]Included[/]" if enabled[key] else "[dim]Hidden[/]"
+                menu.add_row(marker, f"[bold]{label}[/]", f"[dim]{description}[/]", state)
+            screen = Panel(
+                menu,
+                title="[bold cyan]DIFFLY[/]  [bold]Build your review[/]",
+                subtitle="[dim]↑ ↓ move  ·  Space include or hide  ·  Enter show review  ·  q quit[/]",
+                border_style="cyan",
+                padding=(1, 2),
+            )
+            center_screen(screen, estimated_height=len(labels) + 7)
             key = sys.stdin.read(1)
             if key in {"q", "Q"}:
                 return
@@ -345,16 +412,21 @@ def interactive_view(result: TriageResult, explanation: ExplanationResult | None
                     cursor = (cursor - 1) % len(labels)
                 elif sequence == "[B":
                     cursor = (cursor + 1) % len(labels)
-        console.clear()
-        result_table = Table(title=f"{result.metadata.owner}/{result.metadata.repo}#{result.metadata.number}", box=None, padding=(0, 1))
+        result_table = Table(show_header=True, header_style="bold cyan", box=None, padding=(0, 1))
         result_table.add_column("Section", style="cyan")
-        result_table.add_column("Details")
-        for key, label in labels:
+        result_table.add_column("Review details", max_width=CONTENT_WIDTH - 22)
+        for key, label, _ in labels:
             if enabled[key]:
                 details = "\n".join(_section_lines(result, key, explanation))
                 result_table.add_row(label, details)
-        console.print(center(result_table))
-        console.print()
+        screen = Panel(
+            result_table,
+            title=f"[bold cyan]DIFFLY REVIEW[/]  [bold]{result.metadata.owner}/{result.metadata.repo}#{result.metadata.number}[/]",
+            subtitle="[dim]Focused review generated from your selected sections[/]",
+            border_style="green",
+            padding=(1, 2),
+        )
+        center_screen(screen, estimated_height=min(console.size.height, len(labels) * 5 + 7))
     finally:
         termios.tcsetattr(fd, termios.TCSADRAIN, old)
 
@@ -408,6 +480,8 @@ def result_payload(result: TriageResult, explanation: ExplanationResult | None)
             "redactions": explanation.redactions,
             "model": explanation.model,
             "error": explanation.error,
+            "source": explanation.source,
+            "warning": explanation.warning,
         } if explanation is not None else None),
     }
 
@@ -430,6 +504,22 @@ def _emit_report(result: TriageResult, explanation: ExplanationResult | None, ar
     return 0
 
 
+def render_pr_error(ref: RepoRef, number: int, error: GitHubError) -> None:
+    """Show a concise recovery message for a failed pull-request lookup."""
+    if "GitHub API 404" in str(error):
+        body = (
+            f"[bold red]Pull request not found[/]\n"
+            f"[dim]{ref.slug}#{number} is unavailable. Check the repository, pull-request number, and your access.[/]\n\n"
+            "[dim]Private repositories require GITHUB_TOKEN. You can also paste the full pull-request URL to avoid entering the number manually.[/]"
+        )
+    else:
+        body = (
+            f"[bold red]Unable to inspect pull request[/]\n{error}\n\n"
+            "[dim]Check GITHUB_TOKEN, repository access, and your network connection. Run `diffly doctor` for diagnostics.[/]"
+        )
+    console.print(center(Panel.fit(body, border_style="red", padding=(1, 2))))
+
+
 def run_pr(args: argparse.Namespace) -> int:
     ref: RepoRef = args.repository
     number = args.number if args.number is not None else ref.pr_number
@@ -439,10 +529,12 @@ def run_pr(args: argparse.Namespace) -> int:
     owner, repo = ref.owner, ref.repo
     client = GitHubClient(token=args.token)
     try:
+        if getattr(args, "interactive", False):
+            show_loading_screen("Preparing your review…")
         with _progress(f"[cyan]Analyzing [bold]{ref.slug}#{number}[/] — fetching metadata, diffs, symbols, and checks…[/]"):
             result = build_result(client, owner, repo, number)
     except GitHubError as exc:
-        console.print(center(Panel.fit(f"[bold red]Unable to inspect pull request[/]\n{exc}\n\n[dim]Check GITHUB_TOKEN, repository access, and network connectivity. Run `diffly doctor` for diagnostics.[/]", border_style="red")))
+        render_pr_error(ref, number, exc)
         return 2
     if args.explain:
         with _progress("[cyan]Generating literate-diff explanation…[/]"):
@@ -469,6 +561,8 @@ def run_local(args: argparse.Namespace) -> int:
         console.print(center(Panel.fit(f"[bold red]Cannot analyze folder[/]\n{exc}\n\n[dim]Local mode works on any git checkout — including private or deleted repositories you still have on disk.[/]", border_style="red")))
         return 2
     try:
+        if getattr(args, "interactive", False):
+            show_loading_screen("Preparing your local review…")
         with _progress(f"[cyan]Analyzing [bold]{root.name}[/] ({scope}) — reading diffs and symbols locally…[/]"):
             result = build_local_result(str(root), base=args.base)
     except LocalAnalysisError as exc:
@@ -497,7 +591,9 @@ def run_doctor(_: argparse.Namespace) -> int:
     table.add_column("Status")
     pref = update.get_update_preference()
     update_status = {"auto": "auto-update enabled", "manual": "manual updates"}.get(pref, "not set (will prompt on startup)")
-    checks = [("Python", f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}"), ("GitHub token", "configured" if os.environ.get("GITHUB_TOKEN") else "not set (public API only)"), ("Terminal", "interactive" if sys.stdin.isatty() else "non-interactive"), ("diffly executable", shutil.which("diffly") or "not on PATH"), ("Update preference", update_status)]
+    github_token = github_auth_token()
+    github_status = "GITHUB_TOKEN configured" if os.environ.get("GITHUB_TOKEN") else ("GitHub CLI sign-in available" if github_token else "not set (public API only)")
+    checks = [("Python", f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}"), ("GitHub access", github_status), ("Terminal", "interactive" if sys.stdin.isatty() else "non-interactive"), ("diffly executable", shutil.which("diffly") or "not on PATH"), ("Update preference", update_status)]
     for name, value in checks:
         table.add_row(name, value)
     console.print()
@@ -645,15 +741,15 @@ def run_wizard(parser: argparse.ArgumentParser) -> int:
     console.print()
     console.print(center(Panel.fit(
         "[bold cyan]diffly[/]  [dim]Deterministic pull-request triage[/]\n"
-        "[dim]Paste a repository or pull-request URL, answer two prompts, get a focused review.[/]",
+        "[bold]Start a focused review[/] by pasting a GitHub repository or pull-request URL.",
         border_style="cyan",
         padding=(1, 4),
     )))
-    console.print(center(Text.from_markup("[dim]Tip: scripted usage stays available with `diffly pr OWNER/REPO NUMBER --json`.\n[/]")))
-    console.print(center(Text.from_markup("[dim]Format: owner/repo · or paste any GitHub repository / pull-request URL[/]\n")))
+    console.print(center(Text.from_markup("[dim]Tip: for scripts and CI, use `diffly pr OWNER/REPO NUMBER --json`.\n[/]")))
+    console.print(center(Text.from_markup("[dim]Accepted: owner/repo, a GitHub repository URL, or a full pull-request URL.[/]\n")))
     while True:
         raw_repository = Prompt.ask(
-            "[cyan]Repository URL[/]",
+            "[cyan]Repository or pull-request URL[/]",
             default=os.environ.get("DIFFLY_REPOSITORY", ""),
             show_default=False,
         )
@@ -661,30 +757,36 @@ def run_wizard(parser: argparse.ArgumentParser) -> int:
             reference = parse_repo(raw_repository)
             break
         except argparse.ArgumentTypeError as exc:
-            console.print(f"[red]Invalid repository:[/] {exc} — use owner/repo or paste a GitHub URL.")
+            console.print(f"[red]That repository address is not valid.[/] {exc}\n[dim]Use owner/repo or paste a GitHub repository or pull-request URL.[/]")
     if reference.pr_number is not None:
         number = reference.pr_number
-        console.print(f"[dim]Using pull-request #{number} from the URL you entered.[/]")
+        console.print(f"[dim]Pull request #{number} was found in the URL.[/]")
     else:
         while True:
-            raw_number = Prompt.ask("[cyan]Pull request number[/]")
+            raw_number = Prompt.ask(f"[cyan]Pull-request number for {reference.slug}[/]")
             try:
                 number = positive_pr_number(raw_number)
                 break
             except argparse.ArgumentTypeError as exc:
-                console.print(f"[red]Invalid PR number:[/] {exc}")
-    token = os.environ.get("GITHUB_TOKEN")
+                console.print(f"[red]That pull-request number is not valid.[/] {exc}")
+    token = github_auth_token()
     if not token:
-        console.print("[dim]No GITHUB_TOKEN found. Public repositories still work with lower API limits.[/]")
-    explain = Confirm.ask("[cyan]Add an optional AI-generated explanation?[/]", default=False)
+        console.print("[dim]No GitHub token found. Sign in with `gh auth login` for private repositories and higher API limits.[/]")
+    elif not os.environ.get("GITHUB_TOKEN"):
+        console.print("[dim]Using your existing GitHub CLI sign-in.[/]")
+    explain = Confirm.ask(
+        "[cyan]Include a review explanation?[/] "
+        "[dim]With an AI key it uses AI; otherwise Diffly creates a local explanation. The verdict never changes.[/]",
+        default=True,
+    )
     if not explain:
-        console.print("[dim]Deterministic mode — nothing leaves your machine.[/]")
+        console.print("[dim]Deterministic review only — no code is sent to an AI service.[/]")
     console.print(center(Panel.fit(
-        f"[bold]Ready[/]  {reference.slug}#{number}\n"
-        f"[dim]Mode: {'deterministic + explanation' if explain else 'deterministic'} · output: interactive[/]",
+        f"[bold]Review ready[/]  {reference.slug}#{number}\n"
+        f"[dim]Mode: {'deterministic + explanation' if explain else 'deterministic only'} · interactive output[/]",
         border_style="green",
     )))
-    console.print(center(Text.from_markup("[dim]Crunching the diff — your focused review will appear shortly…\n[/]")))
+    console.print(center(Text.from_markup("[dim]Reading the pull request and preparing your review…\n[/]")))
     args = parser.parse_args(["pr", reference.slug, str(number)])
     args.token = token
     args.explain = explain

{diffly_cli-0.4.0 → diffly_cli-1.0.0}/src/diffly_cli/explainer.py

@@ -23,6 +23,8 @@ class ExplanationResult:
     redactions: int
     model: str | None
     error: str | None = None
+    source: str = "ai"
+    warning: str | None = None
 
 
 EXPLANATION_SCHEMA: dict[str, Any] = {
@@ -197,6 +199,56 @@ def validate_explanation(value: Any, allowed_files: set[str] | None = None) -> d
     return value
 
 
+def local_explanation(result: TriageResult, *, redactions: int, warning: str | None = None) -> ExplanationResult:
+    """Build a useful, offline explanation when an AI provider is unavailable.
+
+    This makes the requested explanation dependable: it is always based on the
+    same deterministic facts as the verdict and never sends code off-machine.
+    """
+    metadata = result.metadata
+    narrative: list[dict[str, Any]] = []
+    for file in result.files[:8]:
+        symbols = ", ".join(file.touched_symbols[:4]) or "no named symbols detected"
+        narrative.append(
+            {
+                "title": f"{file.status.title()} {file.path}",
+                "files": [file.path],
+                "explanation": (
+                    f"This file has {file.status} changes (+{file.additions}/-{file.deletions}). "
+                    f"Diffly detected {symbols}."
+                ),
+                "evidence": [f"{file.path}: {file.status}, +{file.additions}/-{file.deletions}"],
+                "snippet": "",
+            }
+        )
+    if not narrative:
+        narrative.append(
+            {
+                "title": "Review metadata",
+                "files": [],
+                "explanation": "No changed-file details were returned, so this explanation is limited to pull-request metadata and checks.",
+                "evidence": [f"Changed files reported: {metadata.changed_files}"],
+                "snippet": "",
+            }
+        )
+    questions = [flag.message for flag in result.flags[:8]] or ["Does the implementation match the pull request's intended behavior?"]
+    uncertainties: list[str] = []
+    check_state = result.checks.get("state", "unknown")
+    if check_state in {"pending", "unknown"}:
+        uncertainties.append(f"CI check state is {check_state}; review again after checks finish.")
+    explanation = {
+        "background": (
+            f"{metadata.owner}/{metadata.repo}#{metadata.number} changes {metadata.changed_files} file(s) "
+            f"with +{metadata.additions}/-{metadata.deletions} lines. Diffly's deterministic verdict is {result.verdict}."
+        ),
+        "intent": f"The pull request is titled “{metadata.title or 'Untitled pull request'}”. The steps below describe the changed files and review signals available locally.",
+        "narrative": narrative,
+        "review_questions": questions,
+        "uncertainties": uncertainties,
+    }
+    return ExplanationResult(explanation, redactions, None, source="local", warning=warning)
+
+
 def generate_explanation(result: TriageResult, *, client: ChatClient | None = None, api_key: str | None = None, base_url: str | None = None, model: str | None = None) -> ExplanationResult:
     context, redaction_count = build_context(result)
     selected_model = model or os.environ.get("DIFFLY_LLM_MODEL", DEFAULT_MODEL)
@@ -204,11 +256,19 @@ def generate_explanation(result: TriageResult, *, client: ChatClient | None = No
     selected_base = base_url or os.environ.get("DIFFLY_LLM_BASE_URL") or os.environ.get("OPENAI_API_BASE")
     if client is None:
         if not selected_key:
-            return ExplanationResult(None, redaction_count, selected_model, "No LLM API key configured; deterministic triage remains available.")
+            return local_explanation(
+                result,
+                redactions=redaction_count,
+                warning="No AI API key is configured, so Diffly generated this explanation locally.",
+            )
         try:
             client = OpenAIChatClient(selected_key, selected_base)
         except Exception as exc:
-            return ExplanationResult(None, redaction_count, selected_model, f"Could not initialize LLM client: {exc}")
+            return local_explanation(
+                result,
+                redactions=redaction_count,
+                warning=f"AI explanation could not start ({exc}); Diffly generated this explanation locally.",
+            )
     try:
         token_limit_key, token_limit = _token_limit_for_model(selected_model)
         raw = client.chat(
@@ -224,4 +284,8 @@ def generate_explanation(result: TriageResult, *, client: ChatClient | None = No
         explanation = validate_explanation(json.loads(safe_raw.text), allowed_files)
         return ExplanationResult(explanation, redaction_count, selected_model)
     except Exception as exc:
-        return ExplanationResult(None, redaction_count, selected_model, f"Literate-diff generation failed safely: {exc}")
+        return local_explanation(
+            result,
+            redactions=redaction_count,
+            warning=f"AI explanation failed safely ({exc}); Diffly generated this explanation locally.",
+        )

{diffly_cli-0.4.0 → diffly_cli-1.0.0}/src/diffly_cli/github.py

@@ -2,10 +2,12 @@ from __future__ import annotations
 
 import json
 import os
+import subprocess
 import urllib.error
 import urllib.parse
 import urllib.request
 from dataclasses import dataclass
+from functools import lru_cache
 from typing import Any
 
 from . import __version__
@@ -17,6 +19,26 @@ class GitHubError(RuntimeError):
     pass
 
 
+@lru_cache(maxsize=1)
+def github_auth_token() -> str | None:
+    """Reuse an existing GitHub CLI sign-in without ever printing its token."""
+    configured = os.environ.get("GITHUB_TOKEN")
+    if configured:
+        return configured
+    try:
+        completed = subprocess.run(
+            ["gh", "auth", "token"],
+            check=False,
+            capture_output=True,
+            text=True,
+            timeout=3,
+        )
+    except (FileNotFoundError, subprocess.SubprocessError):
+        return None
+    token = completed.stdout.strip()
+    return token if completed.returncode == 0 and token else None
+
+
 @dataclass(frozen=True)
 class RepositoryTreeResult:
     paths: list[str]
@@ -25,7 +47,7 @@ class RepositoryTreeResult:
 
 class GitHubClient:
     def __init__(self, token: str | None = None, api_url: str = "https://api.github.com") -> None:
-        self.token = token or os.environ.get("GITHUB_TOKEN")
+        self.token = token or github_auth_token()
         self.api_url = api_url.rstrip("/")
 
     def request(self, path: str, *, accept: str = "application/vnd.github+json", params: dict[str, Any] | None = None) -> Any:

{diffly_cli-0.4.0 → diffly_cli-1.0.0}/src/diffly_cli/triage.py

@@ -6,12 +6,10 @@ from collections import defaultdict
 from typing import Any
 
 from .models import ChangedFile, PRMetadata, RiskFlag
+from .redact import redact_secrets
 
-AUTH_PATTERNS = [
-    "*auth*", "*login*", "*oauth*", "*credential*", "*secret*", "*.pem", "*.key",
-    ".env", ".env.*", "*token*", "*password*", "*security*", "*iam*",
-]
-DB_PATTERNS = ["*migration*", "*migrations*", "*schema*", "*alembic*", "*prisma*", "*.sql", "*db*model*"]
+AUTH_PATTERNS = ["*auth*", "*login*", "*oauth*", "*credential*", "*secret*", "*.pem", "*.key", ".env", ".env.*", "*password*", "*security*", "*iam*"]
+DB_PATTERNS = ["*migration*", "*migrations*", "*schema*", "*alembic*", "*prisma*", "*.sql"]
 TEST_PATTERNS = ["test*", "tests*", "spec*", "*_test.*", "*.test.*", "*.spec.*"]
 DEPENDENCY_FILES = {
     "package.json", "package-lock.json", "npm-shrinkwrap.json", "yarn.lock", "pnpm-lock.yaml",
@@ -63,17 +61,31 @@ def _covered_by_test(file: ChangedFile, test_paths: list[str]) -> list[str]:
     return matches
 
 
+def _has_exposed_secret(file: ChangedFile) -> bool:
+    """Detect a credential-like value added in the changed hunk, not just its path."""
+    added_lines = "\n".join(line[1:] for line in file.patch.splitlines() if line.startswith("+") and not line.startswith("+++"))
+    # A generic ``token = os.getenv(...)`` assignment is common application
+    # code, not evidence of an exposed credential. Block only on high-confidence
+    # credential formats (keys, bearer tokens, private keys, connection URLs).
+    redacted = redact_secrets(added_lines)
+    return any(label != "secret_assignment" for label in redacted.labels)
+
+
 def compute_flags(metadata: PRMetadata, files: list[ChangedFile], checks: dict[str, Any], repo_paths: list[str] | None = None) -> list[RiskFlag]:
     flags: list[RiskFlag] = []
     tree_complete = bool(checks.get("repository_tree_complete", repo_paths is not None))
     test_paths = [path for path in (repo_paths or []) if _matches(path, TEST_PATTERNS)] if tree_complete else []
     changed_test_paths = _test_files(files)
     if not tree_complete:
-        flags.append(RiskFlag("REPOSITORY_TREE_INCOMPLETE", "medium", "Repository file listing was unavailable or truncated; repository-wide test coverage could not be established.", ["repository tree incomplete"]))
+        flags.append(RiskFlag("REPOSITORY_TREE_INCOMPLETE", "low", "Repository file listing was unavailable or truncated; test-coverage hints may be incomplete.", ["repository tree incomplete"]))
+
+    exposed_secrets = [file.path for file in files if _has_exposed_secret(file)]
+    if exposed_secrets:
+        flags.append(RiskFlag("EXPOSED_SECRET", "critical", "Adds a credential-like value in the changed code or configuration.", exposed_secrets))
 
-    auth_files = [file.path for file in files if _matches(file.path, AUTH_PATTERNS)]
+    auth_files = [file.path for file in files if not _matches(file.path, TEST_PATTERNS) and _matches(file.path, AUTH_PATTERNS)]
     if auth_files:
-        flags.append(RiskFlag("AUTH_OR_SECRET", "high", "Touches authentication, credentials, secrets, or security-sensitive files.", auth_files))
+        flags.append(RiskFlag("AUTH_OR_SECRET", "high", "Touches authentication, credentials, secrets, or security-sensitive code that deserves focused review.", auth_files))
 
     db_files = [file.path for file in files if _matches(file.path, DB_PATTERNS)]
     if db_files:
@@ -98,7 +110,7 @@ def compute_flags(metadata: PRMetadata, files: list[ChangedFile], checks: dict[s
         if _is_production_file(file.path) and not coverage:
             untested.append(file.path)
     if untested and tree_complete:
-        flags.append(RiskFlag("NO_TEST_COVERAGE", "medium", "Changed production files have no obvious neighboring or repository test coverage.", untested[:50]))
+        flags.append(RiskFlag("NO_TEST_COVERAGE", "low", "Changed production files have no obvious neighboring or repository test coverage; this is a review hint, not a verdict gate.", untested[:50]))
 
     check_state = str(checks.get("state", "unknown"))
     if check_state == "not_applicable":
@@ -107,9 +119,9 @@ def compute_flags(metadata: PRMetadata, files: list[ChangedFile], checks: dict[s
     if check_state == "failure":
         flags.append(RiskFlag("CHECKS_FAILED", "critical", "One or more required status checks failed.", list(checks.get("failed", []))))
     elif check_state == "pending":
-        flags.append(RiskFlag("CHECKS_PENDING", "low", "Required status checks are still pending.", list(checks.get("pending", [])) or [check_state]))
+        flags.append(RiskFlag("CHECKS_PENDING", "medium", "Required status checks are still pending.", list(checks.get("pending", [])) or [check_state]))
     elif check_state != "success":
-        flags.append(RiskFlag("CHECKS_UNKNOWN", "medium", "Required status checks are missing, pending, or unavailable.", [check_state]))
+        flags.append(RiskFlag("CHECKS_UNKNOWN", "low", "Status checks are missing or unavailable; this is informational, not a failure.", [check_state]))
 
     return flags
 
@@ -120,21 +132,30 @@ def verdict_for(flags: list[RiskFlag], checks: dict[str, Any]) -> tuple[str, lis
     if "CHECKS_FAILED" in codes:
         reasoning.append("BLOCK because at least one status check failed.")
         return "BLOCK", reasoning
-    if "AUTH_OR_SECRET" in codes:
-        reasoning.append("BLOCK because the pull request touches authentication, credentials, secrets, or security-sensitive files.")
+    if "EXPOSED_SECRET" in codes:
+        reasoning.append("BLOCK because the pull request appears to add a credential-like value.")
         return "BLOCK", reasoning
+    if "AUTH_OR_SECRET" in codes:
+        reasoning.append("QUARANTINE because authentication or security-sensitive code changed and needs focused review.")
     if "DATABASE_CHANGE" in codes:
         reasoning.append("QUARANTINE because database schema or migration changes require an explicit review gate.")
     if "NEW_DEPENDENCY" in codes:
         reasoning.append("QUARANTINE because dependency changes expand the supply-chain and runtime surface.")
-    if "NO_TEST_COVERAGE" in codes:
-        reasoning.append("QUARANTINE because at least one changed production file lacks obvious test coverage.")
-    if "CHECKS_UNKNOWN" in codes:
-        reasoning.append("QUARANTINE because the pull request does not have a confirmed passing check result.")
     if "CHECKS_PENDING" in codes:
         reasoning.append("QUARANTINE because required checks are still running.")
     if reasoning:
         return "QUARANTINE", reasoning
+    observations: list[str] = []
+    if "NO_TEST_COVERAGE" in codes:
+        observations.append("no obvious test coverage was found for one or more production files")
+    if "CHECKS_UNKNOWN" in codes:
+        observations.append("status checks were unavailable")
+    if "REPOSITORY_TREE_INCOMPLETE" in codes:
+        observations.append("repository-wide test hints were incomplete")
+    if observations:
+        local_note = " local analysis has no CI checks." if str(checks.get("state")) == "not_applicable" else ""
+        reasoning.append(f"PASS with review notes: {'; '.join(observations)}.{local_note}")
+        return "PASS", reasoning
     if str(checks.get("state")) == "not_applicable":
         reasoning.append("PASS because no blocking or quarantine rule fired (local analysis has no CI checks).")
     else:

{diffly_cli-0.4.0 → diffly_cli-1.0.0}/tests/test_explainer.py

@@ -110,16 +110,18 @@ def test_model_output_is_redacted_before_validation():
     assert explanation.redactions >= 1
 
 
-def test_no_key_falls_back_without_calling_model(monkeypatch):
+def test_no_key_creates_a_local_explanation(monkeypatch):
     monkeypatch.delenv("DIFFLY_LLM_API_KEY", raising=False)
     monkeypatch.delenv("OPENAI_API_KEY", raising=False)
     explanation = generate_explanation(result())
-    assert explanation.explanation is None
-    assert "No LLM API key configured" in explanation.error
+    assert explanation.explanation["narrative"]
+    assert explanation.source == "local"
+    assert "No AI API key" in explanation.warning
 
 
 def test_model_failure_is_safe():
     fake = FakeClient("not json")
     explanation = generate_explanation(result(), client=fake)
-    assert explanation.explanation is None
-    assert "failed safely" in explanation.error
+    assert explanation.explanation["narrative"]
+    assert explanation.source == "local"
+    assert "failed safely" in explanation.warning

{diffly_cli-0.4.0 → diffly_cli-1.0.0}/tests/test_local.py

@@ -44,12 +44,12 @@ def test_clean_tree_passes_locally(repo: Path) -> None:
     assert result.source.startswith("Local git")
 
 
-def test_working_tree_change_without_tests_quarantines(repo: Path) -> None:
+def test_working_tree_change_without_tests_passes_with_a_review_note(repo: Path) -> None:
     (repo / "src" / "orphan_module.py").write_text("def lonely():\n    return 1\n")
     result = build_local_result(str(repo))
     codes = {flag.code for flag in result.flags}
     assert "NO_TEST_COVERAGE" in codes
-    assert result.verdict == "QUARANTINE"
+    assert result.verdict == "PASS"
     assert result.metadata.changed_files == 1
 
 
@@ -63,12 +63,12 @@ def test_untracked_files_are_included(repo: Path) -> None:
     assert new_file.touched_symbols == ["fresh"]
 
 
-def test_auth_change_blocks_locally(repo: Path) -> None:
+def test_auth_change_quarantines_locally(repo: Path) -> None:
     (repo / "src" / "credentials.py").write_text("TOKEN = 'value'\n")
     result = build_local_result(str(repo))
     codes = {flag.code for flag in result.flags}
     assert "AUTH_OR_SECRET" in codes
-    assert result.verdict == "BLOCK"
+    assert result.verdict == "QUARANTINE"
 
 
 def test_base_ref_compares_branch_commits_only(repo: Path) -> None:

{diffly_cli-0.4.0 → diffly_cli-1.0.0}/tests/test_regressions.py

@@ -198,6 +198,71 @@ def test_cli_exposes_interactive_and_diagnostics_commands():
     assert parser.parse_args(["setup"]).command == "setup"
 
 
+def test_interactive_menu_keeps_the_generated_explanation_section():
+    import diffly_cli.cli as cli
+    from diffly_cli.explainer import ExplanationResult
+
+    sections = cli.interactive_sections(ExplanationResult({"intent": "example"}, 0, "gpt-5-mini"))
+
+    assert [key for key, _, _ in sections] == ["verdict", "checks", "risks", "files", "explain"]
+    assert sections[-1][1] == "Explanation"
+
+
+def test_wizard_offers_a_local_explanation_when_no_key_is_configured(monkeypatch):
+    import diffly_cli.cli as cli
+
+    captured: dict[str, argparse.Namespace] = {}
+    monkeypatch.delenv("DIFFLY_LLM_API_KEY", raising=False)
+    monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+    monkeypatch.setattr(cli.sys.stdin, "isatty", lambda: True)
+    monkeypatch.setattr(cli.sys.stdout, "isatty", lambda: True)
+    monkeypatch.setattr(cli, "_check_and_prompt_update", lambda: None)
+    monkeypatch.setattr(cli, "show_loading_screen", lambda message: None)
+    answers = iter(["acme/demo", "42"])
+    monkeypatch.setattr(cli.Prompt, "ask", staticmethod(lambda *a, **k: next(answers)))
+    monkeypatch.setattr(cli.Confirm, "ask", staticmethod(lambda *a, **k: True))
+
+    def fake_run_pr(args):
+        captured["args"] = args
+        return 0
+
+    monkeypatch.setattr(cli, "run_pr", fake_run_pr)
+
+    assert cli.run_wizard(build_parser()) == 0
+    assert captured["args"].explain is True
+
+
+def test_pr_not_found_error_explains_how_to_recover(monkeypatch):
+    import diffly_cli.cli as cli
+    from rich.console import Console
+
+    recorded = Console(record=True, width=100)
+    monkeypatch.setattr(cli, "console", recorded)
+    cli.render_pr_error(cli.RepoRef("acme", "demo"), 42, GitHubError("GitHub API 404 for /repos/acme/demo/pulls/42"))
+
+    output = recorded.export_text()
+    assert "Pull request not found" in output
+    assert "acme/demo#42" in output
+    assert "paste the full pull-request URL" in output
+
+
+def test_github_client_reuses_an_authenticated_gh_session(monkeypatch):
+    import diffly_cli.github as github
+
+    github.github_auth_token.cache_clear()
+    monkeypatch.delenv("GITHUB_TOKEN", raising=False)
+
+    class Completed:
+        returncode = 0
+        stdout = "gho_example_token\n"
+
+    monkeypatch.setattr(github.subprocess, "run", lambda *args, **kwargs: Completed())
+    try:
+        assert github.GitHubClient().token == "gho_example_token"
+    finally:
+        github.github_auth_token.cache_clear()
+
+
 def test_zero_argument_invocation_uses_wizard(monkeypatch):
     import diffly_cli.cli as cli
 

{diffly_cli-0.4.0 → diffly_cli-1.0.0}/tests/test_triage.py

@@ -19,12 +19,21 @@ def test_parse_hunks_tracks_ranges_and_lines():
     assert "+new" in hunks[0].lines
 
 
-def test_auth_change_blocks():
+def test_auth_change_quarantines_for_focused_review():
     file = ChangedFile("src/auth.py", "modified", 1, 0, 1, "+def login():\n")
     flags = compute_flags(metadata(), [file], {"state": "success", "count": 1}, ["src/auth.py", "tests/test_auth.py"])
     verdict, _ = verdict_for(flags, {"state": "success"})
     assert "AUTH_OR_SECRET" in {flag.code for flag in flags}
+    assert verdict == "QUARANTINE"
+
+
+def test_exposed_credential_blocks():
+    file = ChangedFile("src/settings.py", "modified", 1, 0, 1, "+API_KEY = 'ghp_abcdefghijklmnopqrstuvwxyz123456'\n")
+    flags = compute_flags(metadata(), [file], {"state": "success", "count": 1}, ["src/settings.py", "tests/test_settings.py"])
+    verdict, reasoning = verdict_for(flags, {"state": "success"})
+    assert "EXPOSED_SECRET" in {flag.code for flag in flags}
     assert verdict == "BLOCK"
+    assert "credential-like value" in reasoning[0]
 
 
 def test_dependency_and_missing_tests_quarantines():
@@ -47,6 +56,24 @@ def test_all_clear_ships():
     assert verdict == "PASS"
 
 
+def test_missing_obvious_test_coverage_is_a_pass_with_review_note():
+    file = ChangedFile("src/new_module.py", "added", 3, 0, 3, "+def run():\n+    return 1\n")
+    flags = compute_flags(metadata(), [file], {"state": "success", "count": 1}, ["src/new_module.py"])
+    verdict, reasoning = verdict_for(flags, {"state": "success"})
+    assert "NO_TEST_COVERAGE" in {flag.code for flag in flags}
+    assert verdict == "PASS"
+    assert "review notes" in reasoning[0]
+
+
+def test_unknown_checks_do_not_downgrade_an_otherwise_healthy_pr():
+    file = ChangedFile("tests/test_math.py", "modified", 1, 0, 1, "+def test_math():\n")
+    flags = compute_flags(metadata(), [file], {"state": "unknown", "count": 0}, ["tests/test_math.py"])
+    verdict, reasoning = verdict_for(flags, {"state": "unknown"})
+    assert "CHECKS_UNKNOWN" in {flag.code for flag in flags}
+    assert verdict == "PASS"
+    assert "status checks were unavailable" in reasoning[0]
+
+
 def test_pending_checks_quarantine():
     flags = compute_flags(metadata(), [], {"state": "pending", "count": 1}, [])
     verdict, reasoning = verdict_for(flags, {"state": "pending"})