devcouncil 0.1.1 → 0.2.0

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

@@ -11,7 +11,9 @@ 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
@@ -20,8 +22,32 @@ from devcouncil.telemetry.traces import TraceLogger
 console = Console()
 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/."),
 ):
@@ -62,18 +88,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)
             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 +172,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 +181,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 +212,59 @@ 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:
+            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)
+                for result in task_results:
+                    if result["task_id"] == 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 +286,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:

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

@@ -284,13 +284,13 @@ def repair_all(
         for item in summary["blocking_cards"]
         if isinstance(item.get("id"), str)
     ]
-    cards = [card for card in cards if card is not None]
-    prompt = build_bulk_live_repair_prompt(root, cards)
+    resolved_cards = [card for card in cards if card is not None]
+    prompt = build_bulk_live_repair_prompt(root, resolved_cards)
     if json_format:
         typer.echo(json.dumps({
             "ok": True,
             "scope_task_id": summary["scope_task_id"],
-            "cards": [card.model_dump() for card in cards],
+            "cards": [card.model_dump() for card in resolved_cards],
             "prompt": prompt,
         }, indent=2))
         return
@@ -557,18 +557,18 @@ def _log_signal_processed(root: Path, signal: ReviewSignal, processed_path: Path
 
 async def _review_turn(turn, root: Path, client: str, use_llm: bool, task_id: str | None = None):
     if not use_llm:
-        card = review_turn(turn, root, client=client)
-        return card.model_copy(update={"task_id": task_id}) if task_id else card
+        # Pass task_id so the deterministic review can ground completion/evidence
+        # claims against the task's real verification state.
+        return review_turn(turn, root, client=client, task_id=task_id)
     try:
         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)
         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 as exc:
         console.print(f"[yellow]Model-backed review unavailable; using deterministic card: {exc}[/yellow]")
-        card = review_turn(turn, root, client=client)
-        return card.model_copy(update={"task_id": task_id}) if task_id else card
+        return review_turn(turn, root, client=client, task_id=task_id)
     card = await LiveReviewService(router).review(turn, root, client=client, use_llm=True)
     return card.model_copy(update={"task_id": task_id}) if task_id else card

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

@@ -0,0 +1,40 @@
+import json
+import typer
+from pathlib import Path
+from rich.console import Console
+
+from devcouncil.cli.commands.init import initialize_project
+from devcouncil.execution.fs_watcher import FilesystemWatcher
+
+console = Console()
+
+
+def watch_fs(
+    task_id: str = typer.Option(..., "--task", help="Task ID to attribute file changes to."),
+    poll_interval: float = typer.Option(1.0, "--poll-interval"),
+    once: bool = typer.Option(False, "--once", help="Scan once and exit."),
+    project_root: Path = typer.Option(Path("."), "--project-root"),
+    json_format: bool = typer.Option(False, "--json"),
+):
+    root = project_root.expanduser().resolve()
+    initialize_project(root, quiet=True)
+
+    def _print_event(event: dict) -> None:
+        status = "allowed" if event["allowed"] else "denied"
+        console.print(f"[cyan]{event['path']}[/cyan] {status}: {event['reason']}")
+
+    watcher = FilesystemWatcher(root, task_id, poll_interval=poll_interval, on_event=_print_event)
+    if once:
+        events = watcher.scan_once()
+        if json_format:
+            typer.echo(json.dumps({"events": events}, indent=2))
+        else:
+            for event in events:
+                status = "allowed" if event["allowed"] else "denied"
+                console.print(f"[cyan]{event['path']}[/cyan] {status}: {event['reason']}")
+        return
+    console.print(f"[cyan]Watching filesystem for task {task_id}. Ctrl+C to stop.[/cyan]")
+    try:
+        watcher.watch()
+    except KeyboardInterrupt:
+        console.print("[yellow]Stopped filesystem watcher.[/yellow]")

package/src/devcouncil/cli/main.py

@@ -1,10 +1,40 @@
+import sys
+
 import typer
-from pathlib import Path
 
-from devcouncil.cli.commands import (
+
+def _configure_stdio() -> None:
+    """Make stdout/stderr resilient to non-cp1252 characters.
+
+    Coding agents and rich output emit Unicode such as ``✓``. On Windows the
+    default console / redirected-pipe encoding is cp1252, where an un-encodable
+    character raises UnicodeEncodeError mid-write. Because Rich buffers output,
+    that error can surface during an unrelated later write — which previously
+    got misreported as a coding agent "failing to start". Reconfigure both
+    streams to UTF-8 with replacement so output can never crash the process.
+    """
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is None:
+            continue
+        try:
+            reconfigure(encoding="utf-8", errors="replace")
+        except (ValueError, OSError):
+            try:
+                reconfigure(errors="replace")
+            except (ValueError, OSError):
+                pass
+
+
+_configure_stdio()
+
+from devcouncil.cli.commands import (  # noqa: E402 - imports follow stdio reconfiguration
     artifacts,
+    agents,
     baseline,
+    check,
     config,
+    cost,
     ast,
     dashboard,
     doctor,
@@ -22,6 +52,7 @@ from devcouncil.cli.commands import (
     reset_demo_state,
     rollback,
     run,
+    runs,
     setup,
     show,
     status,
@@ -30,8 +61,14 @@ from devcouncil.cli.commands import (
     verify,
     version,
     watch,
+    shell,
+    semantic,
+    evidence,
+    handoff,
+    skills,
+    scaffold,
 )
-from devcouncil.cli.commands.init import initialize_project
+from devcouncil.cli.commands.watch_fs import watch_fs  # noqa: E402 - imports follow stdio reconfiguration
 
 app = typer.Typer(
     name="dev",
@@ -47,41 +84,53 @@ app.add_typer(report.app, name="report")
 app.add_typer(rollback.app, name="rollback")
 app.add_typer(config.app, name="config")
 app.add_typer(artifacts.app, name="artifacts")
+app.add_typer(agents.app, name="agents")
 app.add_typer(hook.app, name="hook")
 app.add_typer(version.app, name="version")
 app.add_typer(mcp_server.app, name="mcp-server")
 app.add_typer(integrate.app, name="integrate")
 app.add_typer(integrate.app, name="integrations")
 app.add_typer(trace.app, name="trace")
+app.add_typer(cost.app, name="cost")
+app.add_typer(runs.app, name="runs")
 app.add_typer(setup.app, name="setup")
 app.add_typer(lsp.app, name="lsp")
 app.add_typer(ast.app, name="ast")
 app.add_typer(dashboard.app, name="dashboard")
 app.add_typer(watch.app, name="watch")
+app.add_typer(semantic.app, name="semantic")
+app.add_typer(evidence.app, name="evidence")
+app.add_typer(skills.app, name="skills")
+watch.app.command("fs")(watch_fs)
 
 # Direct command registrations (those defined as def cmd())
 app.command(name="baseline")(baseline.baseline)
 app.command(name="e2e")(go.go)
 app.command(name="go")(go.go)
 app.command(name="map")(map.map_repo)
+app.command(name="scaffold-ci")(scaffold.scaffold_ci_command)
 app.command(name="plan")(plan.plan)
+app.command(name="approve")(plan.approve)
 app.command(name="prompt")(prompt.prompt)
 app.command(name="reset-demo-state")(reset_demo_state.reset_demo_state)
 app.command(name="run")(run.run)
+# shell/handoff take a positional TASK_ID followed by options, so they must be
+# plain commands — as typer sub-apps (click groups) the documented
+# `dev shell TASK-001 --command ...` form fails to parse.
+app.command(name="shell")(shell.shell)
+app.command(name="handoff")(handoff.handoff)
 app.command(name="show")(show.show)
 app.command(name="verify")(verify.verify)
+app.command(name="check")(check.check)
 app.command(name="repair")(repair.repair)
 app.command(name="status")(status.status)
+app.command(name="optimize")(agents.optimize_agent)
 
 @app.callback()
 def main(ctx: typer.Context):
     """
     DevCouncil: Gated orchestrator for AI-assisted software development.
     """
-    if ctx.invoked_subcommand in {"init", "setup"}:
-        return
-
-    initialize_project(Path("."), quiet=True)
     return
 
 if __name__ == "__main__":

package/src/devcouncil/domain/evidence.py

@@ -1,5 +1,5 @@
-from pydantic import BaseModel
-from typing import Literal, List
+from pydantic import BaseModel, Field
+from typing import Literal, List, Dict
 
 class CommandResult(BaseModel):
     command: str
@@ -15,6 +15,26 @@ class DiffEvidence(BaseModel):
     deleted_files: List[str]
     diff_summary: str
 
+class DiffCoverageEvidence(BaseModel):
+    """Proof that the changed lines were (or were not) exercised by the tests.
+
+    This is the executable evidence behind DevCouncil's core promise: a passing
+    suite is only acceptance evidence if the lines the diff changed were actually
+    run. ``measured`` is False when no reliable signal could be computed (no
+    coverage tool, no instrumentable test command, or no changed executable
+    lines), in which case it must never be read as a defect.
+    """
+
+    task_id: str
+    tool: str = ""
+    measured: bool = False
+    changed_lines: int = 0
+    covered_lines: int = 0
+    coverage_ratio: float = 0.0
+    uncovered_by_file: Dict[str, List[int]] = Field(default_factory=dict)
+    absent_files: List[str] = Field(default_factory=list)
+    summary: str = ""
+
 class VerificationEvidence(BaseModel):
     __test__ = False  # Prevent pytest from collecting this as a test class
     requirement_id: str

package/src/devcouncil/domain/gap.py

@@ -11,12 +11,17 @@ class Gap(BaseModel):
         "orphan_diff",
         "missing_test",
         "test_failed",
+        "invalid_verification_command",
         "acceptance_criteria_unproven",
+        "diff_not_exercised",
         "assumption_violated",
         "architecture_drift",
         "security_risk",
         "dependency_risk",
-        "migration_gap"
+        "migration_gap",
+        "quality_gate_failed",
+        "skipped_verification_command",
+        "coarse_acceptance_proof",
     ]
     requirement_id: Optional[str] = None
     task_id: Optional[str] = None
@@ -24,3 +29,24 @@ class Gap(BaseModel):
     evidence: List[str] = Field(default_factory=list)
     recommended_fix: str
     blocking: bool
+    # Machine-actionable hints for the agent self-repair loop. Populated at gap
+    # creation where known; consumed by the typed next-actions contract (see
+    # devcouncil.verification.next_actions). As of schema v4 these are persisted by
+    # the gap store and round-tripped on reload, so a reconnecting agent gets the
+    # full repair contract rather than a heuristic reconstruction.
+    file: Optional[str] = None
+    line: Optional[int] = None
+    suggested_command: Optional[str] = None
+    # The acceptance criterion this gap is about (when applicable), so the agent can
+    # tie a failure straight back to the criterion it must satisfy.
+    acceptance_criterion_id: Optional[str] = None
+    # Paths to the captured stdout/stderr logs (written under .devcouncil/logs) for the
+    # failing command behind this gap, so the agent can open the FULL failure output
+    # without re-running. Optional and defaulted for backward compatibility; the gap
+    # store does not persist these, so they are only present on a fresh verify run.
+    stdout_path: Optional[str] = None
+    stderr_path: Optional[str] = None
+    # Expected verification method (e.g. "unit_test"/"static_check") for an unproven
+    # acceptance criterion, so missing-evidence routing is concrete rather than a
+    # restatement of the description.
+    expected_verification_method: Optional[str] = None

package/src/devcouncil/domain/task.py

@@ -13,9 +13,38 @@ class Task(BaseModel):
     requirement_ids: List[str] = Field(default_factory=list)
     acceptance_criterion_ids: List[str] = Field(default_factory=list)
     planned_files: List[PlannedFile] = Field(default_factory=list)
-    expected_tests: List[str] = Field(default_factory=list)
-    allowed_commands: List[str] = Field(default_factory=list)
+    expected_tests: List[str] = Field(
+        default_factory=list,
+        description=(
+            "Runnable shell commands (not prose) that prove this task's acceptance "
+            "criteria when they exit 0; they are executed verbatim by the verifier. "
+            "They must run right after THIS task with no missing tools or test files. "
+            "Prefer self-contained inline assertions, e.g. "
+            "python -c \"import calc; assert calc.subtract(10,3)==7\". Use pytest only "
+            "on a test file this or an earlier task creates, running the whole file "
+            "(python -m pytest tests/test_x.py -q), never a ::name node. Do not use "
+            "linters/type-checkers (flake8, mypy, ruff, eslint, tsc, npm) unless the "
+            "repo is already configured for them."
+        ),
+    )
+    allowed_commands: List[str] = Field(
+        default_factory=list,
+        description=(
+            "Shell commands the executor and verifier are permitted to run for this "
+            "task (build/test/lint commands the implementation may invoke). Literal "
+            "commands only, e.g. 'python -m pytest -q', 'uv run pytest'. Leave empty "
+            "only when the task needs no commands beyond those in expected_tests."
+        ),
+    )
     forbidden_changes: List[str] = Field(default_factory=list)
+    depends_on: List[str] = Field(
+        default_factory=list,
+        description=(
+            "IDs of tasks that must complete before this one (e.g. a task that creates a "
+            "module this task imports/tests). Used to order execution and to skip a task "
+            "whose prerequisites are unmet rather than letting it fail spuriously."
+        ),
+    )
     status: Literal[
         "planned",
         "ready",