devcouncil 0.1.1 → 0.3.0

package/src/devcouncil/cli/commands/skills.py

@@ -0,0 +1,267 @@
+import asyncio
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from devcouncil.knowledge.frontmatter import build_frontmatter_markdown
+from devcouncil.skills.registry import Skill, get_skill, load_skills, scaffold_skills, select_skills
+
+app = typer.Typer(help="Inspect and scaffold DevCouncil engineering skills for coding agents.")
+console = Console()
+
+
+def _is_repo_skill(skill, project_root: Path) -> bool:
+    if skill.source_path is None:
+        return False
+    try:
+        skill.source_path.resolve().relative_to(project_root.resolve())
+        return True
+    except ValueError:
+        return False
+
+
+@app.callback(invoke_without_command=True)
+def skills(
+    ctx: typer.Context,
+    goal: str = typer.Option("", "--goal", help="Optional goal text; highlights the skills that would apply."),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root used for file-based skill triggers."),
+):
+    """List available skills and show which apply to this repository/goal."""
+    if ctx.invoked_subcommand is not None:
+        return
+
+    root = project_root.expanduser().resolve()
+    all_skills = load_skills(project_root=root)
+    if not all_skills:
+        console.print("[yellow]No skills found in the DevCouncil skills library.[/yellow]")
+        raise typer.Exit()
+
+    selected = {skill.name for skill in select_skills(goal, root)}
+    table = Table(title="DevCouncil Skills")
+    table.add_column("Skill", style="cyan")
+    table.add_column("Source", justify="center")
+    table.add_column("Applies", justify="center")
+    table.add_column("Description")
+    for skill in all_skills:
+        applies = "always" if skill.always else ("yes" if skill.name in selected else "-")
+        style = "green" if skill.name in selected else "dim"
+        source = "repo" if _is_repo_skill(skill, root) else "library"
+        table.add_row(skill.name, source, f"[{style}]{applies}[/{style}]", skill.description)
+    console.print(table)
+    console.print(
+        "\nScaffold the applicable skills into this repo with: "
+        "[bold]dev skills scaffold[/bold] (add a goal to widen selection, or --all)."
+    )
+
+
+@app.command("show")
+def show(
+    name: str = typer.Argument(..., help="Skill name, e.g. core-engineering or android."),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root, so repo-local skills are found too."),
+):
+    """Print the full body of a single skill."""
+    skill = get_skill(name, project_root=project_root.expanduser().resolve())
+    if skill is None:
+        console.print(f"[red]No skill named '{name}'. Run 'dev skills' to list available skills.[/red]")
+        raise typer.Exit(code=1)
+    console.print(skill.to_skill_md())
+
+
+@app.command("scaffold")
+def scaffold(
+    goal: str = typer.Argument("", help="Optional goal text used to widen domain-skill selection."),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root to scaffold skills into."),
+    all_skills: bool = typer.Option(False, "--all", help="Scaffold every skill, not just the ones that apply."),
+):
+    """Write the applicable skills into <repo>/.claude/skills/<name>/SKILL.md."""
+    root = project_root.expanduser().resolve()
+    chosen = load_skills(project_root=root) if all_skills else select_skills(goal, root)
+    written = scaffold_skills(root, chosen)
+    if not written:
+        console.print(
+            f"[green]Skills already up to date in {root / '.claude' / 'skills'} "
+            f"({len(chosen)} applicable).[/green]"
+        )
+        return
+    console.print(f"[green]Wrote {len(written)} skill file(s):[/green]")
+    for path in written:
+        console.print(f"  {path.relative_to(root).as_posix()}")
+
+
+def _skill_to_markdown(skill: Skill, body: str) -> str:
+    """Render a skill back to markdown, preserving its selection frontmatter."""
+    meta: dict[str, object] = {"name": skill.name}
+    if skill.title:
+        meta["title"] = skill.title
+    if skill.description:
+        meta["description"] = skill.description
+    if skill.always:
+        meta["always"] = True
+    triggers = {
+        k: v
+        for k, v in {"keywords": skill.triggers.keywords, "globs": skill.triggers.globs}.items()
+        if v
+    }
+    if triggers:
+        meta["triggers"] = triggers
+    return build_frontmatter_markdown(meta, body)
+
+
+def _write_skill_body(project_root: Path, skill: Skill, body: str) -> Path:
+    """Persist an optimized skill body, overwriting a repo-local skill in place or
+    materializing a packaged-library skill under ``.devcouncil/skills/<name>.md``."""
+    content = _skill_to_markdown(skill, body)
+    if skill.source_path is not None:
+        try:
+            skill.source_path.resolve().relative_to(project_root.resolve())
+            skill.source_path.write_text(content, encoding="utf-8")
+            return skill.source_path
+        except ValueError:
+            pass
+    target = project_root / ".devcouncil" / "skills" / f"{skill.name}.md"
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(content, encoding="utf-8")
+    return target
+
+
+def _build_router(project_root: Path):
+    """Build a ModelRouter from project config, adding SkillOpt roles when absent."""
+    from devcouncil.app.config import get_api_key, load_config
+    from devcouncil.llm.provider import create_provider
+    from devcouncil.llm.router import ModelRouter
+
+    config = load_config(project_root)
+    api_key = get_api_key(config.models.provider, project_root)
+    provider = create_provider(config.models.provider, api_key, project_root=project_root, provider_prefs=config.provider)
+    role_config = {name: role.model_dump() for name, role in config.models.roles.items()}
+    if not role_config:
+        raise RuntimeError(
+            "No model roles configured in .devcouncil/config.yaml. "
+            "Run 'dev init' or add a 'models.roles' entry before optimizing."
+        )
+    # SkillOpt's rollout/optimizer roles fall back to a capable existing role when the
+    # project config doesn't define dedicated ones. Copy the dict so the three roles
+    # don't alias one config object.
+    capable = role_config.get("arbiter") or role_config.get("planner_a") or next(iter(role_config.values()))
+    role_config.setdefault("skill_target", dict(capable))
+    role_config.setdefault("skill_optimizer", dict(capable))
+    return ModelRouter(provider, role_config, project_root=project_root)
+
+
+@app.command("optimize")
+def optimize(
+    name: str = typer.Argument(..., help="Skill name to optimize, e.g. core-engineering."),
+    evals_path: Path = typer.Option(..., "--evals", help="JSON or JSONL dataset of evaluation tasks."),
+    profile_name: str = typer.Option(
+        "default", "--profile", help="Agent profile whose prompt preamble (guidance) is co-optimized."
+    ),
+    epochs: int = typer.Option(5, "--epochs", min=1, help="Optimization epochs."),
+    max_edits: int = typer.Option(3, "--max-edits", min=1, help="Edit budget per epoch (textual learning rate)."),
+    val_fraction: float = typer.Option(0.5, "--val-fraction", min=0.0, max=1.0, help="Held-out validation fraction."),
+    seed: int = typer.Option(0, "--seed", help="Seed for the deterministic train/validation split."),
+    apply: bool = typer.Option(
+        False,
+        "--apply/--dry-run",
+        help="Write the optimized skill body and guidance preamble back to disk. Defaults to dry-run.",
+    ),
+    output_path: Path | None = typer.Option(None, "--output", help="Write the optimization artifact to this path."),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
+):
+    """Co-optimize a skill document and its agent guidance preamble with the SkillOpt loop.
+
+    Each epoch runs the skill+guidance on training tasks, scores the rollouts, and lets an
+    optimizer model propose bounded edits to **both** documents at once; a candidate is kept
+    only if it strictly improves the held-out validation score.
+    """
+    from devcouncil.executors.agent_registry import load_agent_profiles
+    from devcouncil.optimization.gepa_agent import load_agent_eval_dataset
+    from devcouncil.optimization.skillopt import (
+        GUIDANCE,
+        SKILL,
+        DEFAULT_OBJECTIVE,
+        SkillOptConfig,
+        default_artifact_path,
+        make_llm_optimizer,
+        make_llm_rollout,
+        optimize_skill,
+        write_result_artifact,
+    )
+    from devcouncil.optimization.gepa_agent import _apply_profile_preamble
+
+    root = project_root.expanduser().resolve()
+    skill = get_skill(name, project_root=root)
+    if skill is None:
+        console.print(f"[red]No skill named '{name}'. Run 'dev skills' to list available skills.[/red]")
+        raise typer.Exit(code=1)
+
+    resolved_evals = evals_path.expanduser()
+    if not resolved_evals.is_absolute():
+        resolved_evals = root / resolved_evals
+    try:
+        dataset = load_agent_eval_dataset(resolved_evals)
+    except ValueError as exc:
+        console.print(f"[red]{exc}[/red]")
+        raise typer.Exit(code=2) from exc
+
+    profiles = load_agent_profiles(root)
+    profile = profiles.get(profile_name)
+    if profile is None:
+        known = ", ".join(sorted(profiles)) or "(none)"
+        console.print(
+            f"[red]No agent profile named '{profile_name}'. Known profiles: {known}.[/red]"
+        )
+        raise typer.Exit(code=2)
+    guidance = profile.prompt_preamble or ""
+
+    try:
+        router = _build_router(root)
+    except (RuntimeError, ValueError, FileNotFoundError) as exc:
+        console.print(f"[red]{exc}[/red]")
+        raise typer.Exit(code=1) from exc
+
+    rollout = make_llm_rollout(router)
+    optimizer = make_llm_optimizer(router)
+    result = asyncio.run(
+        optimize_skill(
+            skill_name=skill.name,
+            docs={GUIDANCE: guidance, SKILL: skill.body},
+            dataset=dataset,
+            rollout=rollout,
+            optimizer=optimizer,
+            config=SkillOptConfig(
+                epochs=epochs, max_edits_per_epoch=max_edits, val_fraction=val_fraction, seed=seed
+            ),
+        )
+    )
+
+    artifact_path = (output_path or default_artifact_path(root, skill.name)).expanduser()
+    if not artifact_path.is_absolute():
+        artifact_path = root / artifact_path
+    result.artifact_path = artifact_path
+    result.applied = apply
+    write_result_artifact(
+        artifact_path, result, objective=DEFAULT_OBJECTIVE, dataset_path=str(resolved_evals)
+    )
+
+    if apply and result.improved:
+        # Only write a document that actually changed, so a guidance-only improvement
+        # doesn't churn the skill file (and vice versa).
+        if result.best_skill_body != skill.body:
+            skill_path = _write_skill_body(root, skill, result.best_skill_body)
+            console.print(f"[green]Updated skill body:[/green] {skill_path.relative_to(root).as_posix()}")
+        if result.best_guidance_body != guidance:
+            _apply_profile_preamble(root, profile_name, result.best_guidance_body)
+            console.print(f"[green]Updated guidance preamble for profile '{profile_name}'.[/green]")
+
+    mode = "applied" if (apply and result.improved) else "dry-run"
+    console.print(
+        f"[green]SkillOpt complete ({mode}) for '{skill.name}'.[/green] "
+        f"validation {result.seed_val_score:.3f} -> {result.best_val_score:.3f} "
+        f"over {len(result.epochs)} epoch(s), "
+        f"{result.accepted_edit_count} edit(s) accepted, {result.rejected_edit_count} rejected."
+    )
+    console.print(f"Artifact: [dim]{artifact_path}[/dim]")
+    if apply and not result.improved:
+        console.print("[yellow]No validated improvement — nothing written. Re-run with more epochs or data.[/yellow]")

package/src/devcouncil/cli/commands/status.py

@@ -8,7 +8,7 @@ from devcouncil.cli.commands.init import initialize_project
 from devcouncil.app.project_status import compute_phase
 from devcouncil.storage.db import get_db
 from devcouncil.storage.repositories import ArtifactGraphRepository, StateRepository
-from devcouncil.telemetry.cost import CostEstimator
+from devcouncil.telemetry.cost import group_cost
 from devcouncil.live.summary import live_review_summary
 
 console = Console()
@@ -28,19 +28,10 @@ def _status_payload(project_root: Path) -> dict:
         state = StateRepository(session).get_state()
         phase = compute_phase(graph, state.current_phase if state else None)
 
-        total_cost = 0.0
-        log_file = project_root / ".devcouncil" / "logs" / "model_calls.jsonl"
-        if log_file.exists():
-            with open(log_file, "r", encoding="utf-8") as f:
-                for line in f:
-                    try:
-                        entry = json.loads(line)
-                        total_cost += CostEstimator.estimate_cost(
-                            entry.get("response", {}).get("model", ""),
-                            entry.get("usage", {}),
-                        )
-                    except Exception:
-                        continue
+        # Single read of the model-call ledger: derive both the grand total and the
+        # per-task breakdown from one pass (group_cost -> read_cost_records). This is
+        # provider-aware (ollama records are free), matching the Cost-by-Task table.
+        cost = group_cost(project_root)
 
         status_counts: dict[str, int] = {}
         for task in graph.tasks.values():
@@ -50,7 +41,8 @@ def _status_payload(project_root: Path) -> dict:
             "initialized": True,
             "phase": phase,
             "coverage_summary": summary,
-            "total_cost": total_cost,
+            "total_cost": cost["total_cost"],
+            "cost_by_task": cost["by_task"],
             "task_status_counts": status_counts,
             "blocking_gaps": [gap.model_dump() for gap in blocking_gaps],
             "live_review": live_review_summary(project_root),
@@ -59,6 +51,11 @@ def _status_payload(project_root: Path) -> dict:
 
 def status(
     json_format: bool = typer.Option(False, "--json", help="Output machine-readable JSON."),
+    fail_on_blocking: bool = typer.Option(
+        False,
+        "--fail-on-blocking",
+        help="Exit non-zero when blocking gaps remain, so shell-driven agents can gate on $?.",
+    ),
     project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
 ):
     """
@@ -66,8 +63,14 @@ def status(
     """
     root = project_root.expanduser().resolve()
     payload = _status_payload(root)
+
+    def _maybe_fail() -> None:
+        if fail_on_blocking and payload.get("blocking_gaps"):
+            raise typer.Exit(code=1)
+
     if json_format:
         typer.echo(json.dumps(payload, indent=2))
+        _maybe_fail()
         return
 
     if not payload["initialized"]:
@@ -108,6 +111,16 @@ def status(
             table.add_row(state, str(count))
         console.print(table)
 
+    cost_groups = payload.get("cost_by_task") or {}
+    if cost_groups:
+        cost_table = Table(title="Cost by Task")
+        cost_table.add_column("Task", style="cyan")
+        cost_table.add_column("Cost ($)", justify="right")
+        cost_table.add_column("Calls", justify="right")
+        for name, stats in sorted(cost_groups.items(), key=lambda kv: kv[1]["cost"], reverse=True):
+            cost_table.add_row(name, f"{stats['cost']:.4f}", str(stats["calls"]))
+        console.print(cost_table)
+
     blocking_gaps = payload["blocking_gaps"]
     if blocking_gaps:
         console.print(f"\n[red bold]WARNING: {len(blocking_gaps)} blocking gap(s) must be resolved:[/red bold]")
@@ -115,3 +128,5 @@ def status(
             console.print(f"  - [red]{gap['id']}[/red]: {gap['description'][:80]}")
         if len(blocking_gaps) > 5:
             console.print(f"  ... and {len(blocking_gaps) - 5} more. Run [bold]dev report[/bold] for details.")
+
+    _maybe_fail()

package/src/devcouncil/cli/commands/trace.py

@@ -1,11 +1,12 @@
 import json
 import time
 from pathlib import Path
+from typing import Optional
 
 import typer
 from rich.console import Console
 
-from devcouncil.telemetry.traces import read_trace_events
+from devcouncil.telemetry.traces import read_trace_events, read_trace_events_since
 
 app = typer.Typer(help="Inspect DevCouncil trace events.")
 console = Console()
@@ -13,13 +14,56 @@ console = Console()
 
 @app.command("tail")
 def tail(
-    follow: bool = typer.Option(False, "--follow", "-f", help="Continue polling for new events."),
+    follow: bool = typer.Option(
+        False, "--follow/--no-follow", "-f", help="Continue polling for new events (default is a single shot)."
+    ),
     limit: int = typer.Option(50, "--limit", "-n", help="Maximum events to print before following."),
     jsonl: bool = typer.Option(True, "--jsonl/--pretty", help="Print JSONL or compact text rows."),
+    since: Optional[int] = typer.Option(
+        None,
+        "--since",
+        help="Byte-offset cursor from a previous run; emit only events after it (stateless incremental polling).",
+    ),
+    json_summary: bool = typer.Option(
+        False,
+        "--json",
+        help="Emit a single {events, next_cursor} JSON object (incremental mode). Implies --no-follow.",
+    ),
     project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
 ):
-    """Print the DevCouncil trace JSONL stream for replay or debugging."""
+    """Print the DevCouncil trace JSONL stream for replay or debugging.
+
+    With ``--since <cursor> --no-follow`` (or ``--json``) a single-shot supervising
+    agent gets only the events appended after the cursor plus a ``next_cursor`` to
+    pass back on the next poll, so each poll is O(new) rather than O(all).
+    """
     project_root = project_root.expanduser().resolve()
+
+    # Incremental cursor mode: any of --since / --json / explicit --no-follow.
+    incremental = since is not None or json_summary
+    if incremental:
+        events, next_cursor = read_trace_events_since(project_root, since)
+        if json_summary:
+            typer.echo(
+                json.dumps(
+                    {
+                        "events": [event.model_dump(by_alias=True) for event in events],
+                        "next_cursor": next_cursor,
+                    }
+                )
+            )
+            return
+        for event in events:
+            if jsonl:
+                typer.echo(event.model_dump_json())
+            else:
+                console.print(
+                    f"{event.timestamp} {event.type} "
+                    f"{event.task_id or '-'} {event.summary or json.dumps(event.details)}"
+                )
+        console.print(f"[dim]next_cursor: {next_cursor}[/dim]")
+        return
+
     printed = 0
 
     def emit_new(start_index: int) -> int:

package/src/devcouncil/cli/commands/verify.py

@@ -1,6 +1,7 @@
 import typer
 import asyncio
 import json
+import logging
 from rich.console import Console
 from rich.table import Table
 from pathlib import Path
@@ -11,17 +12,44 @@ from devcouncil.storage.repositories import TaskRepository, RequirementRepositor
 from devcouncil.verification.verifier import Verifier
 from devcouncil.llm.provider import create_provider, validate_model_provider
 from devcouncil.llm.router import ModelRouter
-from devcouncil.domain.evidence import CommandResult, DiffEvidence, TestEvidence
+from devcouncil.domain.evidence import CommandResult, DiffEvidence, DiffCoverageEvidence, TestEvidence
+from devcouncil.domain.gap import Gap
+from devcouncil.verification.next_actions import split_next_actions
 from devcouncil.app.config import load_config, get_api_key
 from devcouncil.app.state_machine import ProjectPhase
 from devcouncil.integrations.code_review_graph import CodeReviewGraphAdapter
 from devcouncil.telemetry.traces import TraceLogger
 
 console = Console()
+logger = logging.getLogger(__name__)
 MAX_RENDERED_GAPS = 20
 
+
+def reconcile_cross_task_acceptance(
+    gaps: list[Gap], proven_acs: set[str]
+) -> list[Gap]:
+    """Drop a task's blocking ``acceptance_criteria_unproven`` gaps whose criterion is
+    already proven by passing evidence in another task.
+
+    Acceptance criteria are requirement-level, not task-private: when the planner splits
+    "implement X" and "add tests for X" into separate tasks that share criteria, the
+    implement task would otherwise stay blocked for criteria the test task proved. The
+    caller passes ``proven_acs`` gathered from passing evidence re-run against the current
+    tree, so a regression would have failed the test and excluded the criterion — only
+    genuinely-satisfied criteria are cleared. Returns the gaps to keep."""
+    return [
+        gap
+        for gap in gaps
+        if not (
+            gap.blocking
+            and gap.gap_type == "acceptance_criteria_unproven"
+            and gap.acceptance_criterion_id in proven_acs
+        )
+    ]
+
 def verify(
     task_id: Optional[str] = typer.Argument(None, help="Optional ID of the task to verify"),
+    sandbox: str = typer.Option("local", "--sandbox", help="Verification sandbox: local, docker, or nix."),
     json_format: bool = typer.Option(False, "--json", help="Output machine-readable JSON."),
     project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
 ):
@@ -29,6 +57,9 @@ def verify(
     Verify one task, or all tasks when TASK_ID is omitted.
     """
     root = project_root.expanduser().resolve()
+    from devcouncil.telemetry.logging_setup import set_log_dir
+    set_log_dir(root)
+    logger.info("dev verify: task=%s sandbox=%s", task_id or "ALL", sandbox)
     initialize_project(root, quiet=True)
     db = get_db(root)
     if not db:
@@ -62,18 +93,69 @@ def verify(
             config = load_config(root)
             validate_model_provider(config.models.provider)
             api_key = get_api_key(config.models.provider, root)
-            provider = create_provider(config.models.provider, api_key)
+            provider = create_provider(config.models.provider, api_key, project_root=root, provider_prefs=config.provider)
             role_config = {name: role.model_dump() for name, role in config.models.roles.items()}
-            router = ModelRouter(provider, role_config)
+            router = ModelRouter(provider, role_config, project_root=root)
         except Exception:
             pass
 
+        from devcouncil.verification.sandbox import get_sandbox
+
         verifier = Verifier(root, router=router)
         total_gaps = 0
         blocked_tasks = 0
         task_results = []
+        # Cross-task acceptance reconciliation state: a criterion proven by passing
+        # evidence in ANY task is proven for every task that shares it.
+        proven_acs: set[str] = set()
+        per_task_gaps: dict[str, list] = {}
 
         for task in tasks:
+            if sandbox != "local":
+                commands = task.expected_tests or task.allowed_commands
+                sandbox_result = get_sandbox(sandbox, root).run(task, commands, reqs)
+                if sandbox_result.status == "unsupported":
+                    message = f"Sandbox {sandbox} is unavailable."
+                    if json_format:
+                        typer.echo(json.dumps({"ok": False, "error": message, "sandbox": sandbox}, indent=2))
+                    else:
+                        console.print(f"[red]{message}[/red]")
+                    return
+                if sandbox_result.status == "failed":
+                    task.status = "blocked"
+                    blocked_tasks += 1
+                    task_repo.save(task)
+                    task_results.append({
+                        "task_id": task.id,
+                        "status": task.status,
+                        "sandbox": sandbox,
+                        "gap_count": 1,
+                        "blocking_gap_count": 1,
+                        "gaps": [],
+                    })
+                    if json_format:
+                        typer.echo(json.dumps({
+                            "ok": False,
+                            "task_id": task.id,
+                            "sandbox": sandbox,
+                            "commands": sandbox_result.commands,
+                        }, indent=2))
+                    else:
+                        console.print(f"[red]{task.id} failed in {sandbox} sandbox.[/red]")
+                    continue
+                task.status = "verified"
+                task_repo.save(task)
+                task_results.append({
+                    "task_id": task.id,
+                    "status": task.status,
+                    "sandbox": sandbox,
+                    "gap_count": 0,
+                    "blocking_gap_count": 0,
+                    "gaps": [],
+                })
+                if not json_format:
+                    console.print(f"[green]{task.id} passed in {sandbox} sandbox.[/green]")
+                continue
             TraceLogger(root).log_event(
                 "task_verification_started",
                 {"task_id": task.id},
@@ -95,6 +177,7 @@ def verify(
             evidence_repo.delete_for_task(task.id)
 
             gaps, evidence = asyncio.run(verifier.verify_task(task, reqs))
+            outcome = verifier.last_outcome
             total_gaps += len(gaps)
 
             for gap in gaps:
@@ -103,11 +186,16 @@ def verify(
             for ev in evidence:
                 if isinstance(ev, CommandResult):
                     evidence_repo.save_command_result(task.id, ev)
+                elif isinstance(ev, DiffCoverageEvidence):
+                    evidence_repo.save_diff_coverage_evidence(ev)
                 elif isinstance(ev, DiffEvidence):
                     evidence_repo.save_diff_evidence(ev)
                 elif isinstance(ev, TestEvidence):
                     evidence_repo.save_test_evidence(ev, task.id)
+                    if ev.status == "passed" and ev.acceptance_criterion_id:
+                        proven_acs.add(ev.acceptance_criterion_id)
 
+            per_task_gaps[task.id] = gaps
             if not json_format:
                 _print_task_result(task.id, gaps)
 
@@ -129,14 +217,60 @@ def verify(
                     summary=f"{task.id} verified",
                 )
             task_repo.save(task)
+            blocking_actions, advisory_actions = split_next_actions(gaps)
             task_results.append({
                 "task_id": task.id,
                 "status": task.status,
                 "gap_count": len(gaps),
                 "blocking_gap_count": len([gap for gap in gaps if gap.blocking]),
                 "gaps": [gap.model_dump() for gap in gaps],
+                "next_actions": [action.model_dump() for action in blocking_actions],
+                "advisory_actions": [action.model_dump() for action in advisory_actions],
+                "verification_mode": outcome.mode if outcome else "unknown",
+                "compiler_active": outcome.compiler_active if outcome else False,
+                "diff_empty": outcome.diff_empty if outcome else False,
+                "coverage_measured": outcome.coverage_measured if outcome else False,
+                "coverage_skipped_reason": outcome.coverage_skipped_reason if outcome else None,
             })
 
+        # Cross-task acceptance reconciliation (only meaningful across the full set).
+        # The planner sometimes splits "implement X" and "add tests for X" into separate
+        # tasks that share acceptance criteria; the implement task would otherwise stay
+        # blocked for criteria the test task already proved. A criterion proven by passing
+        # evidence in ANY task is proven for every task that shares it. Evidence was re-run
+        # against the current tree, so a regression would have failed the test and the AC
+        # would not be in proven_acs — this clears only genuinely-satisfied criteria.
+        if task_id is None and proven_acs:
+            result_map = {r["task_id"]: r for r in task_results}
+            for task in tasks:
+                gaps = per_task_gaps.get(task.id, [])
+                kept = reconcile_cross_task_acceptance(gaps, proven_acs)
+                if len(kept) == len(gaps):
+                    continue
+                gap_repo.delete_for_task(task.id)
+                for gap in kept:
+                    gap_repo.save(gap)
+                per_task_gaps[task.id] = kept
+                if task.status == "blocked" and not any(gap.blocking for gap in kept):
+                    task.status = "verified"
+                    blocked_tasks = max(0, blocked_tasks - 1)
+                    TraceLogger(root).log_event(
+                        "task_reconciled",
+                        {"task_id": task.id, "cross_task_proven": True},
+                        task_id=task.id,
+                        summary=f"{task.id} verified via cross-task acceptance reconciliation",
+                    )
+                task_repo.save(task)
+                if task.id in result_map:
+                    result = result_map[task.id]
+                    blocking_actions, advisory_actions = split_next_actions(kept)
+                    result["status"] = task.status
+                    result["gap_count"] = len(kept)
+                    result["blocking_gap_count"] = len([gap for gap in kept if gap.blocking])
+                    result["gaps"] = [gap.model_dump() for gap in kept]
+                    result["next_actions"] = [action.model_dump() for action in blocking_actions]
+                    result["advisory_actions"] = [action.model_dump() for action in advisory_actions]
+
         StateRepository(session).record_phase(
             ProjectPhase.TASK_BLOCKED.value if blocked_tasks else ProjectPhase.TASK_VERIFIED.value
         )
@@ -158,6 +292,13 @@ def verify(
             else:
                 console.print(f"\n[green]Verified {len(tasks)} tasks successfully.[/green]")
 
+    # Exit-code contract (so shell-driven agents can gate on $?):
+    #   0 = all verified, no blocking gaps
+    #   1 = at least one task is blocked by a verification gap
+    # Argument/state errors above return early with their own message and exit 0.
+    if blocked_tasks:
+        raise typer.Exit(code=1)
+
 
 def _print_task_result(task_id: str, gaps):
     if not gaps: