agentpack-cli 0.3.16__tar.gz → 0.3.17__tar.gz

{agentpack_cli-0.3.16 → agentpack_cli-0.3.17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentpack-cli
-Version: 0.3.16
+Version: 0.3.17
 Summary: Local MCP context router for Claude Code, Codex, Cursor, and AI coding agents.
 License: MIT
 License-File: LICENSE
@@ -29,6 +29,7 @@ Requires-Dist: watchdog>=4.0.0; extra == 'all'
 Provides-Extra: dev
 Requires-Dist: mypy; extra == 'dev'
 Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'
 Requires-Dist: ruff; extra == 'dev'
 Requires-Dist: tomli>=2.0.0; (python_version < '3.11') and extra == 'dev'
@@ -376,6 +377,7 @@ gate.
 | `agentpack guard --repair-stale --refresh-context` | Check freshness, repair stale rules, refresh context |
 | `agentpack status` | Show context freshness and git/task state |
 | `agentpack stats` | Show pack size, token savings, and top files |
+| `agentpack dashboard` | Local HTML control plane for context, skills, learning, and benchmark quality |
 | `agentpack explain --task auto` | Debug selected and omitted files |
 | `agentpack diagnose-selection` | Turn latest pack/benchmark signals into concrete tuning actions |
 | `agentpack ignore suggest|apply` | Suggest or apply `.agentignore` improvements |
@@ -459,6 +461,7 @@ AgentPack writes local artifacts under `.agentpack/`:
 | `.agentpack/learning.prompt.md` | optional source-backed prompt for external LLM refinement |
 | `.agentpack/pr-learning-comment.md` | optional PR-comment-ready learning summary |
 | `.agentpack/learning-dashboard.html` | optional static dashboard from `agentpack learn --dashboard` |
+| `.agentpack/dashboard.html` | local project dashboard from `agentpack dashboard` |
 | `.agentpack/team-lessons.md` | optional shared lesson export from `agentpack learn --team-export` |
 | `.agentpack/learning-feedback.jsonl` | optional local helpful/not-helpful feedback records |
 | `.agentpack/pack_metadata.json` | freshness and pack metadata |

{agentpack_cli-0.3.16 → agentpack_cli-0.3.17}/README.md

@@ -336,6 +336,7 @@ gate.
 | `agentpack guard --repair-stale --refresh-context` | Check freshness, repair stale rules, refresh context |
 | `agentpack status` | Show context freshness and git/task state |
 | `agentpack stats` | Show pack size, token savings, and top files |
+| `agentpack dashboard` | Local HTML control plane for context, skills, learning, and benchmark quality |
 | `agentpack explain --task auto` | Debug selected and omitted files |
 | `agentpack diagnose-selection` | Turn latest pack/benchmark signals into concrete tuning actions |
 | `agentpack ignore suggest|apply` | Suggest or apply `.agentignore` improvements |
@@ -419,6 +420,7 @@ AgentPack writes local artifacts under `.agentpack/`:
 | `.agentpack/learning.prompt.md` | optional source-backed prompt for external LLM refinement |
 | `.agentpack/pr-learning-comment.md` | optional PR-comment-ready learning summary |
 | `.agentpack/learning-dashboard.html` | optional static dashboard from `agentpack learn --dashboard` |
+| `.agentpack/dashboard.html` | local project dashboard from `agentpack dashboard` |
 | `.agentpack/team-lessons.md` | optional shared lesson export from `agentpack learn --team-export` |
 | `.agentpack/learning-feedback.jsonl` | optional local helpful/not-helpful feedback records |
 | `.agentpack/pack_metadata.json` | freshness and pack metadata |

{agentpack_cli-0.3.16 → agentpack_cli-0.3.17}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentpack-cli"
-version = "0.3.16"
+version = "0.3.17"
 description = "Local MCP context router for Claude Code, Codex, Cursor, and AI coding agents."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -47,6 +47,7 @@ all = [
 
 dev = [
   "pytest",
+  "pytest-asyncio",
   "pytest-cov",
   "ruff",
   "mypy",
@@ -55,6 +56,7 @@ dev = [
 
 [tool.pytest.ini_options]
 pythonpath = ["src"]
+asyncio_default_fixture_loop_scope = "function"
 markers = [
     "slow: marks tests as slow (deselect with '-m \"not slow\"')",
 ]

{agentpack_cli-0.3.16 → agentpack_cli-0.3.17}/src/agentpack/__init__.py

@@ -1,3 +1,3 @@
 """AgentPack — task-aware context packing for AI coding agents."""
 
-__version__ = "0.3.16"
+__version__ = "0.3.17"

{agentpack_cli-0.3.16 → agentpack_cli-0.3.17}/src/agentpack/cli.py

@@ -5,6 +5,7 @@ from agentpack.commands import (
     benchmark,
     claude_cmd,
     ci_cmd,
+    dashboard,
     dev_check,
     diagnose_selection,
     diff,
@@ -70,6 +71,7 @@ for mod in [
     task_cmd,
     threads,
     stats,
+    dashboard,
     summarize,
     learn,
     pack,

{agentpack_cli-0.3.16 → agentpack_cli-0.3.17}/src/agentpack/commands/benchmark.py

@@ -1930,21 +1930,21 @@ def benchmark(
     mode: str = typer.Option("balanced", "--mode", help="Mode for single-task run (lite|minimal|balanced|deep)."),
     workspace: str = typer.Option("", "--workspace", help="Restrict benchmark packs to a workspace, e.g. apps/web."),
     cases: str = typer.Option("", "--cases", help="Path to TOML cases file (default: .agentpack/benchmark.toml)."),
-    compare: bool = typer.Option(False, "--compare", is_flag=True, help="Compare minimal/balanced/deep for each task."),
-    init: bool = typer.Option(False, "--init", is_flag=True, help="Scaffold a benchmark.toml and exit."),
-    results_template: bool = typer.Option(False, "--results-template", is_flag=True, help="Create benchmarks/results/YYYY-MM-DD.md for publishing benchmark evidence."),
+    compare: bool = typer.Option(False, "--compare", help="Compare minimal/balanced/deep for each task."),
+    init: bool = typer.Option(False, "--init", help="Scaffold a benchmark.toml and exit."),
+    results_template: bool = typer.Option(False, "--results-template", help="Create benchmarks/results/YYYY-MM-DD.md for publishing benchmark evidence."),
     from_history: int = typer.Option(0, "--from-history", help="Sample last N unique tasks from metrics.jsonl history."),
     write_cases: bool = typer.Option(False, "--write-cases", help="Append --from-history cases to .agentpack/benchmark.toml."),
-    sample_fixtures: bool = typer.Option(False, "--sample-fixtures", is_flag=True, help="Run bundled FastAPI/Next.js/mixed-repo fixture evals from a source checkout."),
-    release_gate: bool = typer.Option(False, "--release-gate", is_flag=True, help="Run the public real-repo release gate."),
-    public_repos: bool = typer.Option(False, "--public-repos", is_flag=True, help="Run real public-repo commit cases from benchmarks/public-repos.toml."),
+    sample_fixtures: bool = typer.Option(False, "--sample-fixtures", help="Run bundled FastAPI/Next.js/mixed-repo fixture evals from a source checkout."),
+    release_gate: bool = typer.Option(False, "--release-gate", help="Run the public real-repo release gate."),
+    public_repos: bool = typer.Option(False, "--public-repos", help="Run real public-repo commit cases from benchmarks/public-repos.toml."),
     public_repos_file: str = typer.Option("", "--public-repos-file", help="Path to public repo benchmark manifest."),
     public_repos_cache: str = typer.Option("", "--public-repos-cache", help="Directory for cached public repo clones."),
-    refresh_public_repos: bool = typer.Option(False, "--refresh-public-repos", is_flag=True, help="Delete and reclone public repo benchmark cache before running."),
-    public_table: bool = typer.Option(False, "--public-table", is_flag=True, help="Write a publishable Markdown benchmark table under benchmarks/results/."),
+    refresh_public_repos: bool = typer.Option(False, "--refresh-public-repos", help="Delete and reclone public repo benchmark cache before running."),
+    public_table: bool = typer.Option(False, "--public-table", help="Write a publishable Markdown benchmark table under benchmarks/results/."),
     no_public_table: bool = typer.Option(False, "--no-public-table", help="Do not write a benchmark results markdown table."),
-    misses: bool = typer.Option(False, "--misses", is_flag=True, help="Show diagnostics for expected files that were not selected."),
-    prove_targets: bool = typer.Option(False, "--prove-targets", is_flag=True, help="Exit non-zero unless recall/token precision targets pass."),
+    misses: bool = typer.Option(False, "--misses", help="Show diagnostics for expected files that were not selected."),
+    prove_targets: bool = typer.Option(False, "--prove-targets", help="Exit non-zero unless recall/token precision targets pass."),
     min_recall: float = typer.Option(0.60, "--min-recall", help="Recall target for --prove-targets."),
     min_token_precision: float = typer.Option(0.50, "--min-token-precision", help="Token precision target for --prove-targets."),
 ) -> None:

agentpack_cli-0.3.17/src/agentpack/commands/dashboard.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import typer
+
+from agentpack.commands._shared import _atomic_write, _root, console
+from agentpack.dashboard.collectors import build_project_dashboard_snapshot
+from agentpack.dashboard.renderers import render_dashboard_html
+
+
+def register(app: typer.Typer) -> None:
+    @app.command()
+    def dashboard(
+        json_output: bool = typer.Option(False, "--json", help="Print normalized dashboard snapshot JSON."),
+        open_browser: bool = typer.Option(False, "--open", help="Open the generated HTML dashboard."),
+        output: str = typer.Option("", "--output", "-o", help="Dashboard HTML output path."),
+    ) -> None:
+        """Generate a local AgentPack dashboard."""
+        root = _root()
+        snapshot = build_project_dashboard_snapshot(root)
+        if json_output:
+            typer.echo(json.dumps(snapshot.model_dump(mode="json"), indent=2, sort_keys=True))
+            return
+
+        out = root / (output or ".agentpack/dashboard.html")
+        out.parent.mkdir(parents=True, exist_ok=True)
+        _atomic_write(out, render_dashboard_html(snapshot))
+        console.print(f"[green]✓[/] Wrote [bold]{out}[/]")
+        if open_browser:
+            _open_file(out)
+
+
+def _open_file(path: Path) -> None:
+    if sys.platform == "darwin":
+        subprocess.run(["open", str(path)], check=False)
+    elif sys.platform.startswith("win"):
+        subprocess.run(["cmd", "/c", "start", "", str(path)], check=False)
+    else:
+        subprocess.run(["xdg-open", str(path)], check=False)

{agentpack_cli-0.3.16 → agentpack_cli-0.3.17}/src/agentpack/commands/eval_cmd.py

@@ -28,25 +28,25 @@ from agentpack.core.evals import (
 def register(app: typer.Typer) -> None:
     @app.command(name="eval")
     def eval_command(
-        init: bool = typer.Option(False, "--init", is_flag=True, help="Scaffold .agentpack/evals.toml and exit."),
+        init: bool = typer.Option(False, "--init", help="Scaffold .agentpack/evals.toml and exit."),
         cases: str = typer.Option("", "--cases", help="Path to eval TOML file (default: .agentpack/evals.toml)."),
         case: str = typer.Option("", "--case", help="Run one eval case by id."),
-        prove_targets: bool = typer.Option(False, "--prove-targets", is_flag=True, help="Exit non-zero when any eval case fails."),
+        prove_targets: bool = typer.Option(False, "--prove-targets", help="Exit non-zero when any eval case fails."),
         capture: str = typer.Option("", "--capture", help="Append a case from current git diff using this id."),
         failure_class: str = typer.Option("context", "--failure-class", help=f"Failure class ({' | '.join(FAILURE_CLASSES)})."),
         failure_source: str = typer.Option("agent_failed", "--failure-source", help="Failure source for captured cases."),
         check: list[str] | None = typer.Option(None, "--check", help="Deterministic command check for --capture. Repeatable."),
         task: str = typer.Option("", "--task", help="Task text for --capture."),
         base_ref: str = typer.Option("HEAD", "--base-ref", help="Git base ref for diff checks."),
-        report: bool = typer.Option(False, "--report", is_flag=True, help="Write benchmarks/results/YYYY-MM-DD-eval.md."),
-        ci_template: bool = typer.Option(False, "--ci-template", is_flag=True, help="Scaffold .github/workflows/agentpack-eval.yml and exit."),
+        report: bool = typer.Option(False, "--report", help="Write benchmarks/results/YYYY-MM-DD-eval.md."),
+        ci_template: bool = typer.Option(False, "--ci-template", help="Scaffold .github/workflows/agentpack-eval.yml and exit."),
         variant: str = typer.Option("agentpack", "--variant", help="Result variant label, e.g. baseline or agentpack."),
         compare_variants: str = typer.Option("", "--compare-variants", help="Compare latest results as BASELINE:VARIANT."),
-        replay: bool = typer.Option(False, "--replay", is_flag=True, help="Run cases in isolated git worktrees using captured patch_file artifacts."),
-        watch: bool = typer.Option(False, "--watch", is_flag=True, help="Rerun evals when git diff state changes."),
+        replay: bool = typer.Option(False, "--replay", help="Run cases in isolated git worktrees using captured patch_file artifacts."),
+        watch: bool = typer.Option(False, "--watch", help="Rerun evals when git diff state changes."),
         interval: float = typer.Option(2.0, "--interval", help="Watch polling interval in seconds."),
         max_runs: int = typer.Option(0, "--max-runs", help="Maximum watch runs (0 = unlimited)."),
-        until_pass: bool = typer.Option(False, "--until-pass", is_flag=True, help="Stop watch mode after all cases pass."),
+        until_pass: bool = typer.Option(False, "--until-pass", help="Stop watch mode after all cases pass."),
         agent: str = typer.Option("", "--agent", help="Agent label to store with --capture metadata."),
         prompt_file: str = typer.Option("", "--prompt-file", help="Prompt artifact path to store with --capture."),
         context_file: str = typer.Option(".agentpack/context.md", "--context-file", help="Context artifact path to store with --capture."),

{agentpack_cli-0.3.16 → agentpack_cli-0.3.17}/src/agentpack/commands/explain.py

@@ -294,9 +294,9 @@ def register(app: typer.Typer) -> None:
         budget: int = typer.Option(0, "--budget", help="Token budget (0 = use config default)."),
         since: Optional[str] = typer.Option(None, "--since", help="Git ref to compare against (e.g. HEAD~1, main)."),
         file: Optional[str] = typer.Option(None, "--file", help="Show detailed score breakdown for a specific file."),
-        omitted: bool = typer.Option(False, "--omitted", is_flag=True, help="Show top-10 excluded files and why."),
-        why_noisy: bool = typer.Option(False, "--why-noisy", is_flag=True, help="Explain broad task terms and noisy selection signals."),
-        budget_plan: bool = typer.Option(False, "--budget-plan", is_flag=True, help="Show selected modes, token costs, and value per token."),
+        omitted: bool = typer.Option(False, "--omitted", help="Show top-10 excluded files and why."),
+        why_noisy: bool = typer.Option(False, "--why-noisy", help="Explain broad task terms and noisy selection signals."),
+        budget_plan: bool = typer.Option(False, "--budget-plan", help="Show selected modes, token costs, and value per token."),
     ) -> None:
         """Explain which files would be selected and why, without writing a context file."""
         if mode not in ("lite", "minimal", "balanced", "deep"):

{agentpack_cli-0.3.16 → agentpack_cli-0.3.17}/src/agentpack/commands/init.py

@@ -71,6 +71,10 @@ def _repo_gitignore_entries(share_cache: bool = False, agent: str = "generic") -
             ".agentpack/learning-dashboard.html",
             ".agentpack/team-lessons.md",
             ".agentpack/learning-feedback.jsonl",
+            ".agentpack/loop_state.json",
+            ".agentpack/progress.md",
+            ".agentpack/loop_events.jsonl",
+            ".agentpack/loop_failures.jsonl",
             ".agentignore",
         ]
     )
@@ -112,6 +116,10 @@ def _agentpack_gitignore_content(share_cache: bool = False) -> str:
             "learning-dashboard.html",
             "team-lessons.md",
             "learning-feedback.jsonl",
+            "loop_state.json",
+            "progress.md",
+            "loop_events.jsonl",
+            "loop_failures.jsonl",
         ]
     )
     return "\n".join(entries) + "\n"

{agentpack_cli-0.3.16 → agentpack_cli-0.3.17}/src/agentpack/commands/next_cmd.py

@@ -7,9 +7,12 @@ import typer
 from agentpack.commands._shared import console, _root, run_refresh
 from agentpack.commands.diagnose_selection import build_selection_diagnosis, _markdown_report
 from agentpack.commands.guard import _context_is_fresh
+from agentpack.core.config import load_config
 from agentpack.core.context_pack import load_pack_metadata
+from agentpack.core.loop_protocol import load_loop_state
 from agentpack.core.thread_context import detect_conflicts, list_thread_rows
 from agentpack.integrations.platform import cli_module_argv
+from agentpack.router.skills_index import ensure_inventory_index
 from agentpack.session.state import TASK_FILE
 import subprocess
 
@@ -60,6 +63,8 @@ def _recommendations(root) -> list[dict[str, str]]:
         items.append({"kind": "thread_conflict", "command": "agentpack threads --conflicts", "reason": "active threads overlap on this branch/worktree"})
     if _pack_looks_noisy(root):
         items.append({"kind": "selection_noise", "command": "agentpack diagnose-selection", "reason": "latest pack has broad/noisy selection signals"})
+    items.extend(_skills_index_recommendations(root))
+    items.extend(_loop_recommendations(root))
     return items
 
 
@@ -90,6 +95,37 @@ def _pack_looks_noisy(root) -> bool:
     return False
 
 
+def _skills_index_recommendations(root) -> list[dict[str, str]]:
+    cfg = load_config(root)
+    try:
+        ensure_inventory_index(root, cfg.skills.paths)
+    except Exception as exc:
+        return [
+            {
+                "kind": "skills_index_failed",
+                "command": "agentpack skills index",
+                "reason": f"automatic skills index refresh failed: {exc}",
+            }
+        ]
+    return []
+
+
+def _loop_recommendations(root) -> list[dict[str, str]]:
+    cfg = load_config(root)
+    if not cfg.loop.enabled:
+        return []
+    state = load_loop_state(root)
+    if state is None:
+        return []
+    if not state.runner:
+        return [{"kind": "loop_runner_missing", "command": 'agentpack work "..." --run --runner "..."', "reason": "Ralph Loop state exists but no runner is configured"}]
+    if state.status == "ready_to_finish":
+        return [{"kind": "loop_ready_to_finish", "command": "agentpack finish --since main", "reason": "Ralph Loop verification passed"}]
+    if state.status == "blocked":
+        return [{"kind": "loop_blocked", "command": "agentpack dashboard", "reason": f"Ralph Loop blocked: {state.blocked_reason or 'inspect loop failures'}"}]
+    return [{"kind": "loop_continue", "command": f'agentpack work "{state.task}" --run', "reason": f"Ralph Loop is {state.status}"}]
+
+
 def _fix_all_safe(root, recommendations: list[dict[str, str]]) -> tuple[list[dict[str, str]], list[dict[str, str | int]]]:
     fixes: list[dict[str, str | int]] = []
     if any(item["kind"] == "init" for item in recommendations):

{agentpack_cli-0.3.16 → agentpack_cli-0.3.17}/src/agentpack/commands/scan.py

@@ -16,7 +16,7 @@ def register(app: typer.Typer) -> None:
     @app.command(name="scan")
     def scan_cmd(
         largest: int = typer.Option(10, "--largest", min=0, help="Show the N largest packable files by estimated tokens."),
-        ignored_summary: bool = typer.Option(False, "--ignored-summary", is_flag=True, help="Group ignored/binary files by directory or extension."),
+        ignored_summary: bool = typer.Option(False, "--ignored-summary", help="Group ignored/binary files by directory or extension."),
     ) -> None:
         """Scan the repository and report file statistics."""
         root = _root()

{agentpack_cli-0.3.16 → agentpack_cli-0.3.17}/src/agentpack/commands/skills.py

@@ -9,7 +9,8 @@ from rich.table import Table
 from agentpack.commands._shared import _root, console
 from agentpack.core.config import load_config
 from agentpack.router.prompt_builder import render_plain
-from agentpack.router.discovery import discover_inventory, write_inventory_index
+from agentpack.router.discovery import discover_inventory
+from agentpack.router.skills_index import ensure_inventory_index
 from agentpack.router.service import RouteService
 
 skills_app = typer.Typer(help="Inspect and index local agent skills and rules.")
@@ -44,10 +45,10 @@ def index_skills() -> None:
     """Write .agentpack/skills_index.json."""
     root = _root()
     cfg = load_config(root)
-    inventory = discover_inventory(root, cfg.skills.paths)
-    path = write_inventory_index(root, inventory)
+    result = ensure_inventory_index(root, cfg.skills.paths, force=True)
+    inventory = result.document.inventory
     console.print(
-        f"Indexed {len(inventory.skills)} skills and {len(inventory.rules)} rules at {path}"
+        f"Indexed {len(inventory.skills)} skills and {len(inventory.rules)} rules at {result.path}"
     )
 
 
@@ -102,5 +103,6 @@ def record_skill_feedback(
         "tests_passed": tests_passed,
         "user_feedback": user_feedback.strip(),
     }
-    out.open("a", encoding="utf-8").write(json.dumps(record) + "\n")
+    with out.open("a", encoding="utf-8") as handle:
+        handle.write(json.dumps(record) + "\n")
     console.print(f"[green]✓[/] Recorded skill feedback in [bold]{out}[/]")

{agentpack_cli-0.3.16 → agentpack_cli-0.3.17}/src/agentpack/commands/tune.py

@@ -22,7 +22,7 @@ def register(app: typer.Typer) -> None:
     @app.command()
     def tune(
         from_benchmark: bool = typer.Option(True, "--from-benchmark/--no-benchmark", help="Use .agentpack/benchmark_results.jsonl."),
-        write: bool = typer.Option(False, "--write", is_flag=True, help="Write suggestions to .agentpack/tuning.md."),
+        write: bool = typer.Option(False, "--write", help="Write suggestions to .agentpack/tuning.md."),
     ) -> None:
         """Suggest tuning actions from benchmark misses and recent pack metrics."""
         root = _root()

{agentpack_cli-0.3.16 → agentpack_cli-0.3.17}/src/agentpack/commands/workflow_cmd.py

@@ -7,7 +7,18 @@ from typing import Any
 
 import typer
 
-from agentpack.commands._shared import console, _root
+from agentpack.commands._shared import console, _root, run_refresh
+from agentpack.commands.guard import _context_is_fresh
+from agentpack.core.config import load_config
+from agentpack.core.loop_protocol import (
+    LoopCommandResult,
+    dry_run_plan,
+    finish_blockers,
+    initialize_loop,
+    load_loop_state,
+    mark_done,
+    run_loop,
+)
 from agentpack.core.thread_context import resolve_thread_option
 from agentpack.integrations.platform import cli_module_argv
 
@@ -24,6 +35,11 @@ def register(app: typer.Typer) -> None:
         pack_only: bool = typer.Option(False, "--pack-only", help="Run pack directly instead of guard."),
         no_init: bool = typer.Option(False, "--no-init", help="Do not initialize the repo when .agentpack/config.toml is missing."),
         no_next: bool = typer.Option(False, "--no-next", help="Do not print next-step diagnostics after context refresh."),
+        run_loop_requested: bool = typer.Option(False, "--run", help="Run the configured Ralph Loop after preparing context."),
+        dry_run: bool = typer.Option(False, "--dry-run", help="Plan Ralph Loop execution without running the configured runner."),
+        runner: str = typer.Option("", "--runner", help="Generic shell command for the Ralph Loop runner."),
+        max_iterations: int = typer.Option(0, "--max-iterations", help="Override [loop].max_iterations for this run."),
+        verify: list[str] = typer.Option([], "--verify", help="Verification command for Ralph Loop. Repeatable."),
         json_output: bool = typer.Option(False, "--json", help="Emit JSON."),
     ) -> None:
         """Initialize if needed, write a task, refresh context, and show next steps."""
@@ -44,9 +60,39 @@ def register(app: typer.Typer) -> None:
         if pack_only:
             start_args.append("--pack-only")
         stages.append(_run("start", cli_module_argv(*start_args), root))
-        if stages[-1]["returncode"] == 0 and not no_next:
+        if stages[-1]["returncode"] == 0 and not no_next and not run_loop_requested and not dry_run:
             stages.append(_run("next", cli_module_argv("next"), root))
-        _finish(stages, json_output)
+        if stages[-1]["returncode"] != 0:
+            _finish(stages, json_output)
+
+        loop_plan = None
+        loop_summary = None
+        if run_loop_requested or dry_run:
+            cfg = load_config(root)
+            state = initialize_loop(
+                root,
+                task_text,
+                cfg.loop,
+                runner_override=runner,
+                max_iterations_override=max_iterations,
+                verification_overrides=list(verify) if verify else None,
+            )
+            if dry_run:
+                loop_plan = dry_run_plan(root, state).model_dump(mode="json")
+                _finish(stages, json_output, loop_plan=loop_plan)
+                return
+            if not state.runner:
+                console.print("[red]Ralph Loop runner missing.[/] Set [loop].runner or pass --runner.")
+                raise typer.Exit(1)
+            loop_summary = run_loop(
+                root,
+                state,
+                refresh=lambda: _refresh_loop_context(root, agent, mode, budget, resolve_thread_option(thread)),
+            ).model_dump(mode="json")
+            if loop_summary["status"] != "ready_to_finish":
+                _finish(stages, json_output, loop_summary=loop_summary)
+                raise typer.Exit(1)
+        _finish(stages, json_output, loop_plan=loop_plan, loop_summary=loop_summary)
 
     @app.command("finish")
     def finish(
@@ -64,6 +110,16 @@ def register(app: typer.Typer) -> None:
         """Run finish checks, capture benchmark evidence, and mark work done."""
         root = _root()
         stages: list[dict[str, Any]] = []
+        loop_state = load_loop_state(root)
+        cfg = load_config(root)
+        finish_task = task or _read_task(root, thread) or (loop_state.task if loop_state else "")
+        loop_applies = loop_state is not None and cfg.loop.enabled and (not finish_task or finish_task == loop_state.task)
+        if loop_applies:
+            blockers = _loop_finish_blockers(root, cfg.loop, loop_state, thread)
+            if blockers:
+                _finish_blocked(blockers, json_output)
+                raise typer.Exit(1)
+
         if not skip_diagnosis:
             stages.append(_run("diagnose-selection", cli_module_argv("diagnose-selection", "--write"), root))
         if not skip_benchmark_capture and since:
@@ -84,6 +140,8 @@ def register(app: typer.Typer) -> None:
         if thread_id:
             state_args.extend(["--thread", thread_id])
         stages.append(_run("state-done", cli_module_argv(*state_args), root))
+        if stages[-1]["returncode"] == 0 and loop_applies:
+            mark_done(root, summary)
         if archive_thread and thread_id and stages[-1]["returncode"] == 0:
             stages.append(_run("threads-archive", cli_module_argv("threads", "archive", thread_id, "--summary", summary), root))
         _finish(stages, json_output)
@@ -100,10 +158,21 @@ def _run(name: str, command: list[str], root: Path) -> dict[str, Any]:
     }
 
 
-def _finish(stages: list[dict[str, Any]], json_output: bool) -> None:
+def _finish(
+    stages: list[dict[str, Any]],
+    json_output: bool,
+    *,
+    loop_plan: dict[str, Any] | None = None,
+    loop_summary: dict[str, Any] | None = None,
+) -> None:
     passed = all(stage["returncode"] == 0 for stage in stages)
     if json_output:
-        typer.echo(json.dumps({"passed": passed, "stages": stages}, indent=2, sort_keys=True))
+        payload: dict[str, Any] = {"passed": passed, "stages": stages}
+        if loop_plan is not None:
+            payload["loop_plan"] = loop_plan
+        if loop_summary is not None:
+            payload["loop_summary"] = loop_summary
+        typer.echo(json.dumps(payload, indent=2, sort_keys=True))
     else:
         for stage in stages:
             marker = "[green]✓[/]" if stage["returncode"] == 0 else "[red]✗[/]"
@@ -112,10 +181,39 @@ def _finish(stages: list[dict[str, Any]], json_output: bool) -> None:
                 console.print(f"  rerun: [bold]{stage['command']}[/]")
                 if stage.get("detail"):
                     console.print(f"  [dim]{stage['detail']}[/]")
+        if loop_plan is not None:
+            console.print(f"[green]✓[/] Ralph Loop dry run: {loop_plan['next_action']}")
+        if loop_summary is not None:
+            marker = "[green]✓[/]" if loop_summary.get("status") == "ready_to_finish" else "[yellow]![/]"
+            console.print(f"{marker} Ralph Loop {loop_summary.get('status')}: {loop_summary.get('reason') or loop_summary.get('next_command')}")
     if not passed:
         raise typer.Exit(1)
 
 
+def _loop_finish_blockers(root: Path, loop_cfg, loop_state, thread: str) -> list[dict[str, Any]]:
+    blockers = [blocker.model_dump(mode="json") for blocker in finish_blockers(root, loop_cfg, loop_state)]
+    fresh, reason = _context_is_fresh(root, thread_id=resolve_thread_option(thread))
+    if not fresh:
+        blockers.append(
+            {
+                "kind": "stale_context",
+                "message": f"Context is stale: {reason}",
+                "command": "agentpack guard --agent auto --repair-stale --refresh-context",
+            }
+        )
+    return blockers
+
+
+def _finish_blocked(blockers: list[dict[str, Any]], json_output: bool) -> None:
+    if json_output:
+        typer.echo(json.dumps({"passed": False, "stages": [], "loop_blockers": blockers}, indent=2, sort_keys=True))
+        return
+    console.print("[red]Ralph Loop completion blockers:[/]")
+    for blocker in blockers:
+        console.print(f"  [yellow]![/] {blocker['message']}")
+        console.print(f"    Run: [bold]{blocker['command']}[/]")
+
+
 def _read_task(root: Path, thread: str) -> str:
     thread_id = resolve_thread_option(thread)
     if thread_id:
@@ -125,3 +223,10 @@ def _read_task(root: Path, thread: str) -> str:
     if not path.exists():
         return ""
     return path.read_text(encoding="utf-8").strip().splitlines()[0].strip()
+
+
+def _refresh_loop_context(root: Path, agent: str, mode: str, budget: int, thread_id: str | None) -> LoopCommandResult:
+    stats = run_refresh(root, agent, mode, budget, thread_id=thread_id)
+    if stats is None:
+        return LoopCommandResult(command="agentpack guard --repair-stale --refresh-context", returncode=1, output_excerpt="context refresh failed")
+    return LoopCommandResult(command="agentpack guard --repair-stale --refresh-context", returncode=0, output_excerpt=json.dumps(stats, sort_keys=True))

{agentpack_cli-0.3.16 → agentpack_cli-0.3.17}/src/agentpack/core/config.py

@@ -67,6 +67,21 @@ class LearningConfig(BaseModel):
     min_groundedness_score: int = 70
 
 
+class LoopConfig(BaseModel):
+    enabled: bool = True
+    runner: str = ""
+    max_iterations: int = 10
+    verification_commands: list[str] = Field(default_factory=list)
+    require_verification: bool = True
+    require_progress_update: bool = True
+    require_clean_tree: bool = True
+    auto_commit: bool = False
+    auto_push: bool = False
+    runner_timeout_seconds: int = 600
+    verification_timeout_seconds: int = 600
+    max_repeated_failures: int = 3
+
+
 class HooksConfig(BaseModel):
     task_switch_detection: bool = True
     task_switch_min_terms: int = 1
@@ -137,6 +152,7 @@ class Config(BaseModel):
     context_lite: LiteContextConfig = Field(default_factory=LiteContextConfig)
     summary: SummaryConfig = Field(default_factory=SummaryConfig)
     learning: LearningConfig = Field(default_factory=LearningConfig)
+    loop: LoopConfig = Field(default_factory=LoopConfig)
     hooks: HooksConfig = Field(default_factory=HooksConfig)
     skills: SkillsConfig = Field(default_factory=SkillsConfig)
     agents: AgentsConfig = Field(default_factory=AgentsConfig)
@@ -199,6 +215,20 @@ max_cards = 5
 max_quiz_questions = 5
 min_groundedness_score = 70
 
+[loop]
+enabled = true
+runner = ""
+max_iterations = 10
+verification_commands = []
+require_verification = true
+require_progress_update = true
+require_clean_tree = true
+auto_commit = false
+auto_push = false
+runner_timeout_seconds = 600
+verification_timeout_seconds = 600
+max_repeated_failures = 3
+
 [hooks]
 # Claude UserPromptSubmit can detect a clearly different coding prompt,
 # update .agentpack/task.md, and repack even if files did not change.