specsmith 0.3.10.dev198__tar.gz → 0.3.10.dev210__tar.gz

{specsmith-0.3.10.dev198/src/specsmith.egg-info → specsmith-0.3.10.dev210}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specsmith
-Version: 0.3.10.dev198
+Version: 0.3.10.dev210
 Summary: Applied Epistemic Engineering toolkit — AEE agent sessions, execution profiles, FPGA/HDL governance, tool installer, 50+ CLI commands.
 Author: BitConcepts
 License-Expression: MIT
@@ -51,6 +51,8 @@ Provides-Extra: mistral
 Requires-Dist: openai>=1.0; extra == "mistral"
 Provides-Extra: gui
 Requires-Dist: PySide6>=6.6; extra == "gui"
+Provides-Extra: ag2
+Requires-Dist: ag2[ollama]; extra == "ag2"
 Provides-Extra: agent
 Requires-Dist: anthropic>=0.56; extra == "agent"
 Requires-Dist: openai>=1.0; extra == "agent"
@@ -186,12 +188,45 @@ specsmith epistemic-audit --project-dir ./my-project
 # Start the agentic REPL
 specsmith run --project-dir ./my-project
 
+# AG2 agent shell — Planner/Builder/Verifier over Ollama
+specsmith agent status                    # check agent config + Ollama
+specsmith agent plan "add logging"        # plan only (no execution)
+specsmith agent run "fix lint errors"     # full Plan → Build → Verify
+specsmith agent improve "add tests"       # self-improvement with reports
+specsmith agent verify                    # run Verifier on current state
+specsmith agent reports                   # list improvement reports
+
 # Check current AEE workflow phase
 specsmith phase --project-dir ./my-project
 ```
 
 ---
 
+## AG2 Agent Shell — Local AI Agents over Ollama
+
+specsmith includes an AG2-based agent shell with three specialized agents:
+
+- **Planner** — inspects repo, generates execution plans with acceptance criteria
+- **Builder** — makes code/doc changes following the plan
+- **Verifier** — runs tests, accepts or rejects changes
+
+All agents run locally on Ollama (default: `qwen2.5:14b`). Zero cloud cost.
+
+```bash
+pip install "specsmith[ag2]"              # install AG2 + Ollama support
+specsmith agent status                    # verify config + Ollama running
+specsmith agent run "fix lint errors"     # Plan → Build → Verify pipeline
+specsmith agent improve "add tests for config.py"  # self-improvement with reports
+```
+
+The agent shell stores structured reports at `.specsmith/agent-reports/` with task ID,
+files changed, test results, verdict (ACCEPT/REJECT), and follow-up tasks.
+
+Configurable per-project in `scaffold.yml` under `agents:` or via the VS Code
+Project Settings → Agent tab.
+
+---
+
 ## VS Code Extension
 
 The **specsmith AEE Workbench** VS Code extension is the flagship client:
@@ -211,7 +246,10 @@ The **specsmith AEE Workbench** VS Code extension is the flagship client:
 - **Execution profiles** — safe / standard / open / admin; custom allow/block command lists
 - **AEE phase indicator** — shows current phase with readiness %, Next Phase button, phase selector
 - **AI agent sessions** — independent process per project, JSONL bridge, chat with file injection
+- **AG2 agent shell** — Planner/Builder/Verifier agents over Ollama in Actions tab
+- **Agent tab** — per-project provider/model/context/iteration config (overrides global defaults)
 - **Live model listing** — Anthropic, OpenAI, Gemini, Mistral, local Ollama (GPU-aware)
+- **Ollama model catalog** — 16 models, 4 tiers, GPU-aware recommendations, filter by installed/available
 - **Ollama integration** — model manager (update/remove/update-all), version check, upgrade
 - **FPGA/HDL tool support** — vivado, gtkwave, vsg, ghdl, verilator, yosys, nextpnr, and 15 more
 - **Tool installer** — scan installed tools; one-click install via winget/brew/apt for missing tools
@@ -284,7 +322,7 @@ Supported tools: **Synthesis:** vivado, quartus, radiant, diamond, gowin.
 
 **Workflow:** `phase show/set/next/list` `ledger add/list` `req list/add/gaps/trace`
 
-**Agent:** `run` `agent providers/tools/skills`
+**Agent:** `run` `agent run/plan/status/verify/improve/reports` `agent providers/tools/skills`
 
 **Ollama:** `ollama list/available/gpu/pull/suggest`
 

{specsmith-0.3.10.dev198 → specsmith-0.3.10.dev210}/README.md

@@ -121,12 +121,45 @@ specsmith epistemic-audit --project-dir ./my-project
 # Start the agentic REPL
 specsmith run --project-dir ./my-project
 
+# AG2 agent shell — Planner/Builder/Verifier over Ollama
+specsmith agent status                    # check agent config + Ollama
+specsmith agent plan "add logging"        # plan only (no execution)
+specsmith agent run "fix lint errors"     # full Plan → Build → Verify
+specsmith agent improve "add tests"       # self-improvement with reports
+specsmith agent verify                    # run Verifier on current state
+specsmith agent reports                   # list improvement reports
+
 # Check current AEE workflow phase
 specsmith phase --project-dir ./my-project
 ```
 
 ---
 
+## AG2 Agent Shell — Local AI Agents over Ollama
+
+specsmith includes an AG2-based agent shell with three specialized agents:
+
+- **Planner** — inspects repo, generates execution plans with acceptance criteria
+- **Builder** — makes code/doc changes following the plan
+- **Verifier** — runs tests, accepts or rejects changes
+
+All agents run locally on Ollama (default: `qwen2.5:14b`). Zero cloud cost.
+
+```bash
+pip install "specsmith[ag2]"              # install AG2 + Ollama support
+specsmith agent status                    # verify config + Ollama running
+specsmith agent run "fix lint errors"     # Plan → Build → Verify pipeline
+specsmith agent improve "add tests for config.py"  # self-improvement with reports
+```
+
+The agent shell stores structured reports at `.specsmith/agent-reports/` with task ID,
+files changed, test results, verdict (ACCEPT/REJECT), and follow-up tasks.
+
+Configurable per-project in `scaffold.yml` under `agents:` or via the VS Code
+Project Settings → Agent tab.
+
+---
+
 ## VS Code Extension
 
 The **specsmith AEE Workbench** VS Code extension is the flagship client:
@@ -146,7 +179,10 @@ The **specsmith AEE Workbench** VS Code extension is the flagship client:
 - **Execution profiles** — safe / standard / open / admin; custom allow/block command lists
 - **AEE phase indicator** — shows current phase with readiness %, Next Phase button, phase selector
 - **AI agent sessions** — independent process per project, JSONL bridge, chat with file injection
+- **AG2 agent shell** — Planner/Builder/Verifier agents over Ollama in Actions tab
+- **Agent tab** — per-project provider/model/context/iteration config (overrides global defaults)
 - **Live model listing** — Anthropic, OpenAI, Gemini, Mistral, local Ollama (GPU-aware)
+- **Ollama model catalog** — 16 models, 4 tiers, GPU-aware recommendations, filter by installed/available
 - **Ollama integration** — model manager (update/remove/update-all), version check, upgrade
 - **FPGA/HDL tool support** — vivado, gtkwave, vsg, ghdl, verilator, yosys, nextpnr, and 15 more
 - **Tool installer** — scan installed tools; one-click install via winget/brew/apt for missing tools
@@ -219,7 +255,7 @@ Supported tools: **Synthesis:** vivado, quartus, radiant, diamond, gowin.
 
 **Workflow:** `phase show/set/next/list` `ledger add/list` `req list/add/gaps/trace`
 
-**Agent:** `run` `agent providers/tools/skills`
+**Agent:** `run` `agent run/plan/status/verify/improve/reports` `agent providers/tools/skills`
 
 **Ollama:** `ollama list/available/gpu/pull/suggest`
 

{specsmith-0.3.10.dev198 → specsmith-0.3.10.dev210}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specsmith"
-version = "0.3.10.dev198"
+version = "0.3.10.dev210"
 description = "Applied Epistemic Engineering toolkit — AEE agent sessions, execution profiles, FPGA/HDL governance, tool installer, 50+ CLI commands."
 readme = "README.md"
 license = "MIT"
@@ -65,6 +65,8 @@ openai = ["openai>=1.0"]
 gemini = ["google-genai>=1.0"]
 mistral = ["openai>=1.0"]  # Mistral uses the openai SDK pointed at api.mistral.ai
 gui = ["PySide6>=6.6"]
+# AG2 agent shell (Planner/Builder/Verifier over Ollama)
+ag2 = ["ag2[ollama]"]
 # Install all optional LLM providers
 agent = ["anthropic>=0.56", "openai>=1.0"]
 # Convenience bundle: everything
@@ -121,6 +123,8 @@ exclude = ["src/specsmith/gui"]
 module = [
     "anthropic",
     "anthropic.*",
+    "autogen",    # AG2 agent shell — optional extra
+    "autogen.*",
     "openai",
     "openai.*",
     "google",

{specsmith-0.3.10.dev198 → specsmith-0.3.10.dev210}/src/specsmith/agent/providers/ollama.py

@@ -226,7 +226,8 @@ class OllamaProvider:
             data=json.dumps(payload).encode(),
             headers={"Content-Type": "application/json"},
         )
-        with urllib.request.urlopen(req, timeout=120) as resp:  # noqa: S310
+        # 300s: streaming responses arrive incrementally, but model load can take time
+        with urllib.request.urlopen(req, timeout=300) as resp:  # noqa: S310
             for line in resp:
                 line = line.strip()
                 if not line:
@@ -294,7 +295,9 @@ class OllamaProvider:
             headers={"Content-Type": "application/json"},
         )
         try:
-            with urllib.request.urlopen(req, timeout=120) as resp:  # noqa: S310
+            # 600s timeout: Ollama needs time to load model (first call) + inference.
+            # 120s was too short and caused frequent "timed out" errors in VS Code.
+            with urllib.request.urlopen(req, timeout=600) as resp:  # noqa: S310
                 result: dict[str, Any] = json.loads(resp.read())
                 return result
         except urllib.error.HTTPError as e:

{specsmith-0.3.10.dev198 → specsmith-0.3.10.dev210}/src/specsmith/agent/runner.py

@@ -224,6 +224,16 @@ If a command fails (non-zero exit, "not recognized", "not found"):
      "I couldn’t find [tool] on your PATH. Please tell me the full path or add it to PATH."
   5. NEVER loop between retrying and suggesting installation.
 
+## EXEC-001 — NO INLINE PYTHON EXECUTION:
+NEVER run non-trivial Python code via `python -c "..."` or `python -c '...'`.
+Always write Python code to a file first, then execute the file:
+  1. Use write_file to create the script (e.g. /tmp/task.py or .specsmith/scripts/task.py)
+  2. Use run_command to execute: `python task.py`
+The ONLY exception: single-line import/version checks
+(e.g. `python -c "import sys; print(sys.version)"`).
+Reason: inline python -c cannot be interrupted, does not stream output,
+and fails silently on Windows.
+
 ## TOOL CALL FORMAT RULE:
 NEVER output raw JSON tool calls as text. Use ONLY the native tool_use mechanism.
 Do NOT write <tools>, <tool_call>, or JSON blocks in your response text.

specsmith-0.3.10.dev210/src/specsmith/agents/__init__.py

@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 BitConcepts, LLC. All rights reserved.
+"""specsmith AG2 agent shell — Planner/Builder/Verifier over Ollama."""
+
+from specsmith.agents.config import AgentConfig, load_agent_config
+
+__all__ = ["AgentConfig", "load_agent_config"]

specsmith-0.3.10.dev210/src/specsmith/agents/cli.py

@@ -0,0 +1,233 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 BitConcepts, LLC. All rights reserved.
+"""CLI commands for the AG2 agent shell.
+
+Wired into the main specsmith CLI as the ``agent`` command group.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+console = Console()
+
+
+@click.group()
+def agent() -> None:
+    """AG2 agent shell — Planner/Builder/Verifier over Ollama."""
+
+
+@agent.command()
+@click.argument("task")
+@click.option("--project-dir", default=".", help="Project root directory.")
+@click.option("--max-turns", default=6, help="Maximum conversation turns per agent.")
+def run(task: str, project_dir: str, max_turns: int) -> None:
+    """Execute a task through the full Planner → Builder → Verifier pipeline."""
+    try:
+        from autogen import ConversableAgent  # noqa: F401 — verify AG2 is installed
+    except ImportError:
+        console.print("[red]AG2 is not installed.[/red] Run: pip install ag2[ollama]")
+        raise SystemExit(1)  # noqa: B904
+
+    from specsmith.agents.config import load_agent_config
+    from specsmith.agents.roles import create_builder, create_planner, create_verifier
+
+    project_dir = str(Path(project_dir).resolve())
+    config = load_agent_config(project_dir)
+
+    console.print(
+        f"\n[bold cyan]specsmith agent shell[/bold cyan] — {config.primary_model} via Ollama"
+    )
+    console.print(f"Task: [bold]{task}[/bold]\n")
+
+    # Phase 1: Plan
+    console.print("[dim]─── Phase 1: Planning ───[/dim]")
+    planner = create_planner(config, project_dir)
+    plan_result = planner.run(message=f"Plan this task:\n{task}", max_turns=max_turns)
+    plan_result.process()
+
+    plan_text = ""
+    for msg in plan_result.messages:
+        if msg.get("role") == "assistant" and msg.get("content"):
+            plan_text = msg["content"]
+
+    if not plan_text:
+        console.print("[yellow]Planner produced no output.[/yellow]")
+        return
+
+    # Phase 2: Build
+    console.print("\n[dim]─── Phase 2: Building ───[/dim]")
+    builder = create_builder(config, project_dir)
+    build_result = builder.run(
+        message=f"Execute this plan:\n\n{plan_text}",
+        max_turns=max_turns,
+    )
+    build_result.process()
+
+    build_text = ""
+    for msg in build_result.messages:
+        if msg.get("role") == "assistant" and msg.get("content"):
+            build_text = msg["content"]
+
+    # Phase 3: Verify
+    console.print("\n[dim]─── Phase 3: Verifying ───[/dim]")
+    verifier = create_verifier(config, project_dir)
+    verify_result = verifier.run(
+        message=(
+            f"Verify the following changes:\n\n{build_text}"
+            "\n\nRun the relevant tests and report ACCEPT or REJECT."
+        ),
+        max_turns=max_turns,
+    )
+    verify_result.process()
+
+    # Summary
+    console.print("\n[bold cyan]─── Done ───[/bold cyan]")
+    for msg in verify_result.messages:
+        if msg.get("role") == "assistant" and msg.get("content"):
+            content = msg["content"]
+            if "ACCEPT" in content.upper():
+                console.print("[bold green]✓ ACCEPTED[/bold green]")
+            elif "REJECT" in content.upper():
+                console.print("[bold red]✗ REJECTED[/bold red]")
+            break
+
+
+@agent.command()
+@click.argument("task")
+@click.option("--project-dir", default=".", help="Project root directory.")
+@click.option("--max-turns", default=6, help="Maximum conversation turns.")
+def plan(task: str, project_dir: str, max_turns: int) -> None:
+    """Generate a plan without executing it."""
+    try:
+        from autogen import ConversableAgent  # noqa: F401
+    except ImportError:
+        console.print("[red]AG2 is not installed.[/red] Run: pip install ag2[ollama]")
+        raise SystemExit(1)  # noqa: B904
+
+    from specsmith.agents.config import load_agent_config
+    from specsmith.agents.roles import create_planner
+
+    project_dir = str(Path(project_dir).resolve())
+    config = load_agent_config(project_dir)
+
+    console.print(f"\n[bold cyan]specsmith agent plan[/bold cyan] — {config.primary_model}")
+    planner = create_planner(config, project_dir)
+    result = planner.run(message=f"Plan this task:\n{task}", max_turns=max_turns)
+    result.process()
+
+
+@agent.command()
+@click.option("--project-dir", default=".", help="Project root directory.")
+def status(project_dir: str) -> None:
+    """Show agent configuration and Ollama status."""
+    from specsmith.agents.config import load_agent_config
+
+    config = load_agent_config(project_dir)
+    console.print("[bold]Agent Configuration[/bold]")
+    console.print(f"  Primary model:  {config.primary_model}")
+    console.print(f"  Utility model:  {config.utility_model}")
+    console.print(f"  Ollama URL:     {config.ollama_base_url}")
+    console.print(f"  Max iterations: {config.max_iterations}")
+    console.print(f"  Context length: {config.num_ctx}")
+    console.print(f"  Tools enabled:  {', '.join(config.tools_enabled)}")
+
+    # Check Ollama
+    try:
+        from specsmith.agent.providers.ollama import OllamaProvider
+
+        p = OllamaProvider(base_url=config.ollama_base_url)
+        if p.is_available():
+            console.print("  Ollama:         [green]running[/green]")
+        else:
+            console.print("  Ollama:         [red]not available[/red]")
+    except Exception:  # noqa: BLE001
+        console.print("  Ollama:         [yellow]unknown[/yellow]")
+
+
+@agent.command()
+@click.option("--project-dir", default=".", help="Project root directory.")
+@click.option("--max-turns", default=4, help="Maximum conversation turns.")
+def verify(project_dir: str, max_turns: int) -> None:
+    """Run the Verifier agent on the current project state."""
+    try:
+        from autogen import ConversableAgent  # noqa: F401
+    except ImportError:
+        console.print("[red]AG2 is not installed.[/red] Run: pip install ag2[ollama]")
+        raise SystemExit(1)  # noqa: B904
+
+    from specsmith.agents.config import load_agent_config
+    from specsmith.agents.roles import create_verifier
+
+    project_dir = str(Path(project_dir).resolve())
+    config = load_agent_config(project_dir)
+
+    console.print(f"\n[bold cyan]specsmith agent verify[/bold cyan] — {config.utility_model}")
+    verifier = create_verifier(config, project_dir)
+    result = verifier.run(
+        message=(
+            "Run the full test suite and report the current project health."
+            " Report ACCEPT or REJECT."
+        ),
+        max_turns=max_turns,
+    )
+    result.process()
+
+
+@agent.command()
+@click.argument("task")
+@click.option("--project-dir", default=".", help="Project root directory.")
+@click.option("--max-turns", default=6, help="Maximum conversation turns.")
+def improve(task: str, project_dir: str, max_turns: int) -> None:
+    """Run the self-improvement workflow (Plan → Build → Verify → Report)."""
+    try:
+        from autogen import ConversableAgent  # noqa: F401
+    except ImportError:
+        console.print("[red]AG2 is not installed.[/red] Run: pip install ag2[ollama]")
+        raise SystemExit(1)  # noqa: B904
+
+    from specsmith.agents.workflows.improve import run_improvement
+
+    project_dir = str(Path(project_dir).resolve())
+    console.print("\n[bold cyan]specsmith agent improve[/bold cyan]")
+    console.print(f"Task: [bold]{task}[/bold]\n")
+
+    report = run_improvement(task, project_dir, max_turns=max_turns)
+
+    console.print(f"\n[bold]Report:[/bold] {report.summary}")
+    if report.verdict == "ACCEPT":
+        console.print("[bold green]✓ ACCEPTED[/bold green]")
+    elif report.verdict == "REJECT":
+        console.print("[bold red]✗ REJECTED[/bold red]")
+    else:
+        console.print(f"[yellow]Verdict: {report.verdict}[/yellow]")
+
+    if report.follow_up_tasks:
+        console.print("\n[bold]Follow-up tasks:[/bold]")
+        for ft in report.follow_up_tasks:
+            console.print(f"  - {ft}")
+
+    console.print(f"\n[dim]Report saved to .specsmith/agent-reports/{report.task_id}.json[/dim]")
+
+
+@agent.command()
+@click.option("--project-dir", default=".", help="Project root directory.")
+def reports(project_dir: str) -> None:
+    """List recent improvement reports."""
+    from specsmith.agents.reports import list_reports
+
+    all_reports = list_reports(project_dir)
+    if not all_reports:
+        console.print("[yellow]No improvement reports found.[/yellow]")
+        return
+
+    for r in all_reports[:10]:
+        icon = {
+            "accepted": "[green]✓[/green]",
+            "rejected": "[red]✗[/red]",
+            "failed": "[red]![/red]",
+        }.get(r.status, "[yellow]?[/yellow]")
+        console.print(f"  {icon} {r.task_id} — {r.summary}")

specsmith-0.3.10.dev210/src/specsmith/agents/config.py

@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 BitConcepts, LLC. All rights reserved.
+"""Agent configuration — loaded from scaffold.yml ``agents:`` key."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class AgentConfig:
+    """Configuration for the AG2 agent shell."""
+
+    primary_model: str = "qwen2.5:14b"
+    utility_model: str = ""  # empty = same as primary_model
+    ollama_base_url: str = "http://localhost:11434"
+    max_iterations: int = 10
+    stream: bool = False
+    num_ctx: int = 4096
+    tools_enabled: list[str] = field(
+        default_factory=lambda: ["filesystem", "shell", "git", "tests", "docs"]
+    )
+
+    @property
+    def effective_utility_model(self) -> str:
+        """Utility model, defaulting to primary if not set."""
+        return self.utility_model or self.primary_model
+
+    @property
+    def effective_max_iterations(self) -> int:
+        """0 means unlimited (use 999 as practical ceiling)."""
+        return self.max_iterations if self.max_iterations > 0 else 999
+
+    def llm_config_dict(self, model: str | None = None) -> dict[str, Any]:
+        """Return an AG2-compatible LLM config dict for Ollama."""
+        return {
+            "model": model or self.primary_model,
+            "api_type": "ollama",
+            "client_host": self.ollama_base_url,
+            "stream": self.stream,
+            "num_ctx": self.num_ctx,
+            "native_tool_calls": True,
+            "hide_tools": "if_any_run",
+        }
+
+
+def load_agent_config(project_dir: str | Path) -> AgentConfig:
+    """Load agent config from scaffold.yml ``agents:`` section.
+
+    Falls back to defaults if scaffold.yml doesn't exist or has no agents key.
+    """
+    scaffold_path = Path(project_dir) / "scaffold.yml"
+    if not scaffold_path.exists():
+        return AgentConfig()
+
+    try:
+        import yaml
+
+        with open(scaffold_path, encoding="utf-8") as f:
+            raw = yaml.safe_load(f) or {}
+        agents_raw = raw.get("agents", {}) or {}
+        return AgentConfig(
+            primary_model=agents_raw.get("primary_model", AgentConfig.primary_model),
+            utility_model=agents_raw.get("utility_model", AgentConfig.utility_model),
+            ollama_base_url=agents_raw.get("ollama_base_url", AgentConfig.ollama_base_url),
+            max_iterations=agents_raw.get("max_iterations", AgentConfig.max_iterations),
+            stream=agents_raw.get("stream", AgentConfig.stream),
+            num_ctx=agents_raw.get("num_ctx", AgentConfig.num_ctx),
+            tools_enabled=agents_raw.get("tools_enabled", AgentConfig().tools_enabled),
+        )
+    except Exception:  # noqa: BLE001
+        return AgentConfig()

specsmith-0.3.10.dev210/src/specsmith/agents/reports.py

@@ -0,0 +1,77 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 BitConcepts, LLC. All rights reserved.
+"""Change reports — structured artifacts from improvement runs.
+
+Every improvement run produces a ChangeReport stored as JSON at
+``.specsmith/agent-reports/<task_id>.json``.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class ChangeReport:
+    """Structured output from an improvement run."""
+
+    task_id: str = ""
+    task_description: str = ""
+    project_dir: str = "."
+    status: str = "pending"  # pending, accepted, rejected, failed, unclear
+    verdict: str = ""  # ACCEPT, REJECT, UNCLEAR
+    plan: str = ""
+    build_output: str = ""
+    verify_output: str = ""
+    files_changed: list[str] = field(default_factory=list)
+    tests_run: int = 0
+    tests_passed: int = 0
+    tests_failed: int = 0
+    summary: str = ""
+    follow_up_tasks: list[str] = field(default_factory=list)
+    created: str = field(default_factory=lambda: datetime.now(tz=timezone.utc).isoformat())
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to a JSON-serializable dict (excludes verbose fields)."""
+        d = asdict(self)
+        # Truncate verbose fields for the summary view
+        for key in ("plan", "build_output", "verify_output"):
+            if len(d.get(key, "")) > 500:
+                d[key] = d[key][:500] + "...(truncated)"
+        return d
+
+
+def save_report(report: ChangeReport) -> Path:
+    """Save a change report to ``.specsmith/agent-reports/``."""
+    root = Path(report.project_dir).resolve()
+    reports_dir = root / ".specsmith" / "agent-reports"
+    reports_dir.mkdir(parents=True, exist_ok=True)
+    path = reports_dir / f"{report.task_id}.json"
+    path.write_text(
+        json.dumps(report.to_dict(), indent=2, ensure_ascii=False),
+        encoding="utf-8",
+    )
+    return path
+
+
+def list_reports(project_dir: str = ".") -> list[ChangeReport]:
+    """List all change reports, newest first."""
+    reports_dir = Path(project_dir).resolve() / ".specsmith" / "agent-reports"
+    if not reports_dir.exists():
+        return []
+    reports: list[ChangeReport] = []
+    for path in sorted(reports_dir.glob("*.json"), reverse=True):
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+            reports.append(
+                ChangeReport(
+                    **{k: v for k, v in data.items() if k in ChangeReport.__dataclass_fields__}
+                )
+            )
+        except Exception:  # noqa: BLE001
+            pass
+    return reports