devcouncil 0.1.1 → 0.3.0

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

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import json
 import asyncio
+import logging
 import time
 from pathlib import Path
 
@@ -32,6 +33,7 @@ from devcouncil.telemetry.traces import TraceLogger
 
 app = typer.Typer(help="Review active coding-agent sessions and emit critique cards.")
 console = Console()
+logger = logging.getLogger(__name__)
 
 
 @app.command("sessions")
@@ -72,6 +74,9 @@ def review(
 ):
     """Review the latest assistant response in a coding-agent transcript."""
     root = project_root.expanduser().resolve()
+    from devcouncil.telemetry.logging_setup import set_log_dir
+    set_log_dir(root)
+    logger.info("dev watch review: client=%s llm=%s", client, llm)
     transcript_path = _resolve_transcript(root, client, transcript=transcript, session=session, latest=latest)
     if transcript_path is None:
         message = "No transcript selected. Use --transcript, --session, or --latest."
@@ -91,6 +96,7 @@ def review(
 
     scoped_task_id = task_id or active_task_id(root)
     card = asyncio.run(_review_turn(turn, root, client, llm, task_id=scoped_task_id))
+    logger.info("dev watch review: card %s verdict=%s task=%s", card.id, card.verdict, scoped_task_id or "(unscoped)")
     saved_path, duplicate = _save_card_once(root, card, persist=persist, force=force)
     if saved_path:
         _log_card_reviewed(root, card, saved_path, duplicate=duplicate, source="review")
@@ -279,18 +285,21 @@ def repair_all(
     """Generate repair prompts for all blocking live-review cards in scope."""
     root = project_root.expanduser().resolve()
     summary = live_review_summary(root, task_id=task_id)
+    all_cards = {card.id: card for card in load_cards(root)}
+    # Guard the membership test with isinstance(str): a malformed (non-hashable) id would
+    # otherwise raise TypeError on `in`, whereas the old per-id lookup just skipped it.
     cards = [
-        get_card(root, item["id"])
+        all_cards[item["id"]]
         for item in summary["blocking_cards"]
-        if isinstance(item.get("id"), str)
+        if isinstance(item.get("id"), str) and item["id"] in all_cards
     ]
-    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
@@ -331,6 +340,10 @@ def pending(
 ):
     """Review every pending response-ready signal that includes a transcript path."""
     root = project_root.expanduser().resolve()
+    from devcouncil.telemetry.logging_setup import set_log_dir
+    set_log_dir(root)
+    logger.info("dev watch pending: reviewing signals (client=%s, llm=%s)", client or "all", llm)
+    fallback_task_id = active_task_id(root)
     reviewed = []
     skipped = []
     for signal in _filtered_signals(root, client):
@@ -342,7 +355,7 @@ def pending(
         if turn is None:
             skipped.append({"signal": signal.model_dump(), "reason": f"No assistant turn found in {transcript_path}."})
             continue
-        scoped_task_id = task_id or signal.task_id or active_task_id(root)
+        scoped_task_id = task_id or signal.task_id or fallback_task_id
         card = asyncio.run(_review_turn(turn, root, signal.client, llm, task_id=scoped_task_id))
         saved_path, duplicate = _save_card_once(root, card, persist=True, force=force)
         if saved_path:
@@ -363,6 +376,7 @@ def pending(
             else:
                 console.print(f"[green]Saved critique card:[/green] {saved_path}")
 
+    logger.info("dev watch pending complete: %d reviewed, %d skipped", len(reviewed), len(skipped))
     if json_format:
         typer.echo(json.dumps({"reviewed": reviewed, "skipped": skipped}, indent=2))
         return
@@ -385,11 +399,15 @@ def follow(
 ):
     """Poll a transcript and emit a critique card whenever the latest assistant turn changes."""
     root = project_root.expanduser().resolve()
+    from devcouncil.telemetry.logging_setup import set_log_dir
+    set_log_dir(root)
     transcript_path = _resolve_transcript(root, client, transcript=transcript, session=session, latest=latest)
     if transcript_path is None:
+        logger.warning("dev watch follow: no transcript selected")
         console.print("[red]No transcript selected. Use --transcript, --session, or --latest.[/red]")
         raise typer.Exit(code=2)
     seen_turn_id: str | None = None
+    logger.info("dev watch follow: watching %s (client=%s, interval=%ss, llm=%s)", transcript_path, client, interval, llm)
     console.print(f"[cyan]Watching transcript:[/cyan] {transcript_path}")
     while True:
         turn = latest_assistant_turn(transcript_path, client=client)
@@ -397,6 +415,7 @@ def follow(
             seen_turn_id = turn.turn_id
             scoped_task_id = task_id or active_task_id(root)
             card = asyncio.run(_review_turn(turn, root, client, llm, task_id=scoped_task_id))
+            logger.info("dev watch follow: new turn %s → card %s verdict=%s", turn.turn_id, card.id, card.verdict)
             saved_path, duplicate = _save_card_once(root, card, persist=True, force=force)
             if saved_path:
                 _log_card_reviewed(root, card, saved_path, duplicate=duplicate, source="follow")
@@ -557,18 +576,19 @@ 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, 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 as exc:
+        logger.warning("Model-backed live review unavailable; using deterministic card: %s", 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,20 +1,53 @@
+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,
+    design,
     doctor,
     go,
     hook,
     init,
     integrate,
+    logs,
     lsp,
     map,
     mcp_server,
+    okf,
     plan,
     prompt,
     repair,
@@ -22,6 +55,7 @@ from devcouncil.cli.commands import (
     reset_demo_state,
     rollback,
     run,
+    runs,
     setup,
     show,
     status,
@@ -30,8 +64,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 +87,85 @@ 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(logs.app, name="logs")
+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")
+app.add_typer(okf.app, name="okf")
+app.add_typer(design.app, name="design")
+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):
+def main(
+    ctx: typer.Context,
+    verbose: int = typer.Option(
+        0,
+        "--verbose",
+        "-v",
+        count=True,
+        help="Increase console log verbosity (-v INFO, -vv DEBUG). Everything is "
+        "always captured at DEBUG in .devcouncil/logs/devcouncil.log.",
+    ),
+    quiet: bool = typer.Option(
+        False,
+        "--quiet",
+        "-q",
+        help="Only show errors on the console (the log file still captures everything).",
+    ),
+    log_level: str = typer.Option(
+        None,
+        "--log-level",
+        help="Explicit console log level (DEBUG/INFO/WARNING/ERROR). Overrides -v/-q "
+        "and the DEVCOUNCIL_LOG_LEVEL env var.",
+    ),
+):
     """
     DevCouncil: Gated orchestrator for AI-assisted software development.
     """
-    if ctx.invoked_subcommand in {"init", "setup"}:
-        return
+    # Configure logging once, up front, for every command. Without this the many
+    # logger.info/debug calls across the orchestrator, planner, executors and
+    # verifier go nowhere — which is exactly why recurring run failures were so
+    # hard to diagnose. The durable DEBUG log lands in .devcouncil/logs/.
+    from devcouncil.telemetry.logging_setup import configure_logging
 
-    initialize_project(Path("."), quiet=True)
+    configure_logging(verbosity=verbose, quiet=quiet, log_level=log_level)
     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
@@ -22,6 +42,13 @@ class VerificationEvidence(BaseModel):
     command: str
     status: Literal["passed", "failed", "not_run"]
     evidence_summary: str
+    # HOW the criterion was proven, for auditing the gate's rigor (distinct from the
+    # pass/fail status). ``compiled`` = one DevCouncil per-criterion check passed;
+    # ``vote`` = a majority of independent checks passed (self-consistency);
+    # ``coarse`` = proven only by a passing acceptance-capable command, not a check tied
+    # to the criterion (weakest). Empty for legacy/unspecified evidence. Persisted in the
+    # evidence JSON blob, so adding it needs no migration; old rows default to "".
+    mode: Literal["compiled", "vote", "coarse", ""] = ""
 
 # Backward-compatible alias
 TestEvidence = VerificationEvidence

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",