devcouncil 0.2.0 → 0.3.0

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

@@ -0,0 +1,186 @@
+"""`dev design` — lint, export, and inspect a project design.md design system.
+
+Mirrors the upstream ``@google/design.md`` CLI's ``lint`` and ``export`` subcommands so a
+DevCouncil project can validate its design tokens and convert them to CSS / Tailwind / W3C
+Design Tokens. The same design.md is injected into coding-agent prompts (see
+``.devcouncil/knowledge/design``) so agents honor the system while they build.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from devcouncil.knowledge.design import export as export_design
+from devcouncil.knowledge.design import lint as lint_design
+from devcouncil.knowledge.design import parse_design_md
+from devcouncil.knowledge.design_conformance import (
+    STYLE_EXTENSIONS,
+    scan_files,
+)
+
+app = typer.Typer(help="Lint, export, and inspect a design.md design system.")
+console = Console()
+
+# Where a project's design system is looked for, in order.
+_DEFAULT_PATHS = (
+    ".devcouncil/knowledge/design/design.md",
+    "DESIGN.md",
+    "design.md",
+)
+
+# Directories pruned while auto-discovering style files (heavy / generated / vendored).
+_PRUNE_DIRS = frozenset({
+    ".git", ".hg", ".svn", "node_modules", ".venv", "venv", "env",
+    "dist", "build", "out", ".next", ".nuxt", ".svelte-kit", "coverage",
+    "__pycache__", ".mypy_cache", ".pytest_cache", ".cache", "vendor",
+})
+# Cap on auto-discovered files so an enormous repo can't make `check` run unbounded.
+_MAX_DISCOVERED_FILES = 5000
+
+
+def _discover_style_files(root: Path) -> list[Path]:
+    """Walk ``root`` for style-ish files, pruning heavy dirs and bounding the count."""
+    found: list[Path] = []
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in _PRUNE_DIRS and not d.startswith(".")]
+        for name in filenames:
+            if Path(name).suffix.lower() in STYLE_EXTENSIONS:
+                found.append(Path(dirpath) / name)
+                if len(found) >= _MAX_DISCOVERED_FILES:
+                    return found
+    return found
+
+
+def _resolve_path(explicit: Path | None, project_root: Path) -> Path | None:
+    if explicit is not None:
+        candidate = explicit.expanduser()
+        return candidate if candidate.is_file() else None
+    for rel in _DEFAULT_PATHS:
+        candidate = project_root / rel
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+@app.command("lint")
+def lint(
+    path: Path = typer.Argument(None, help="Path to a design.md (defaults to the project's design system)."),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root."),
+):
+    """Validate a design system: broken token refs, contrast, ordering, orphans."""
+    root = project_root.expanduser().resolve()
+    target = _resolve_path(path, root)
+    if target is None:
+        console.print("[red]No design.md found.[/red] Looked for: " + ", ".join(_DEFAULT_PATHS))
+        raise typer.Exit(code=1)
+
+    findings = lint_design(parse_design_md(target))
+    if not findings:
+        console.print(f"[green]✓ {target} passed all design.md lint rules.[/green]")
+        return
+
+    errors = [f for f in findings if f.severity == "error"]
+    color = {"error": "red", "warning": "yellow", "info": "cyan"}
+    console.print(f"[bold]{len(findings)} finding(s) in {target}:[/bold]")
+    for f in findings:
+        console.print(f"  [{color.get(f.severity, 'white')}]{f.format()}[/{color.get(f.severity, 'white')}]")
+    if errors:
+        raise typer.Exit(code=1)
+
+
+@app.command("export")
+def export(
+    path: Path = typer.Argument(None, help="Path to a design.md (defaults to the project's design system)."),
+    fmt: str = typer.Option("css", "--format", "-f", help="Output format: css | tailwind | w3c."),
+    output: Path = typer.Option(None, "--output", "-o", help="Write to this file instead of stdout."),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root."),
+):
+    """Export design tokens to CSS custom properties, a Tailwind config, or W3C tokens."""
+    root = project_root.expanduser().resolve()
+    if fmt not in ("css", "tailwind", "w3c"):
+        console.print(f"[red]Unknown format '{fmt}'.[/red] Use one of: css, tailwind, w3c.")
+        raise typer.Exit(code=2)
+    target = _resolve_path(path, root)
+    if target is None:
+        console.print("[red]No design.md found.[/red] Looked for: " + ", ".join(_DEFAULT_PATHS))
+        raise typer.Exit(code=1)
+
+    rendered = export_design(parse_design_md(target), fmt)  # type: ignore[arg-type]
+    if output is not None:
+        out = output.expanduser().resolve()
+        out.parent.mkdir(parents=True, exist_ok=True)
+        out.write_text(rendered, encoding="utf-8")
+        console.print(f"[green]Wrote {fmt} tokens to[/green] {out}")
+    else:
+        typer.echo(rendered, nl=not rendered.endswith("\n"))
+
+
+@app.command("check")
+def check(
+    files: list[Path] = typer.Argument(
+        None, help="Files to check (defaults to the repo's style-ish files)."),
+    design: Path = typer.Option(
+        None, "--design", help="Path to a design.md (defaults to the project's design system)."),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root."),
+):
+    """Flag hardcoded style literals (hex colors, px sizes) that bypass design tokens.
+
+    Exits non-zero when any violation is found so it can gate CI / a pre-commit hook.
+    """
+    root = project_root.expanduser().resolve()
+    target = _resolve_path(design, root)
+    if target is None:
+        console.print("[red]No design.md found.[/red] Looked for: " + ", ".join(_DEFAULT_PATHS))
+        raise typer.Exit(code=1)
+
+    ds = parse_design_md(target)
+    paths = [f.expanduser() for f in files] if files else _discover_style_files(root)
+    violations = scan_files(paths, ds)
+
+    if not violations:
+        scanned = len([p for p in paths if p.suffix.lower() in STYLE_EXTENSIONS])
+        console.print(
+            f"[green]✓ No design-token violations in {scanned} file(s) "
+            f"(tokens from {target}).[/green]")
+        return
+
+    by_file: dict[str, list] = {}
+    for v in violations:
+        by_file.setdefault(v.file or "<text>", []).append(v)
+
+    console.print(
+        f"[bold red]{len(violations)} design-token violation(s) "
+        f"in {len(by_file)} file(s):[/bold red]")
+    for fname in sorted(by_file):
+        console.print(f"[bold]{fname}[/bold]")
+        for v in sorted(by_file[fname], key=lambda x: (x.line, x.kind)):
+            console.print(
+                f"  [yellow]{v.line}[/yellow] [{v.kind}] {v.message}\n"
+                f"      [dim]{v.snippet}[/dim]")
+    raise typer.Exit(code=1)
+
+
+@app.command("show")
+def show(
+    path: Path = typer.Argument(None, help="Path to a design.md (defaults to the project's design system)."),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root."),
+):
+    """Summarize a design system: token counts and document sections."""
+    root = project_root.expanduser().resolve()
+    target = _resolve_path(path, root)
+    if target is None:
+        console.print("[red]No design.md found.[/red] Looked for: " + ", ".join(_DEFAULT_PATHS))
+        raise typer.Exit(code=1)
+
+    ds = parse_design_md(target)
+    console.print(f"[bold]{ds.name or target.name}[/bold] ({target})")
+    console.print(
+        f"  colors={len(ds.colors)}  typography={len(ds.typography)}  "
+        f"rounded={len(ds.rounded)}  spacing={len(ds.spacing)}  components={len(ds.components)}"
+    )
+    if ds.sections:
+        console.print("  sections: " + ", ".join(h for h, _ in ds.sections))

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

@@ -80,7 +80,156 @@ def _ollama_model_present(model: str, pulled: set[str]) -> bool:
     return any(tag in candidates or tag.split(":", 1)[0] == base and ":" not in model for tag in pulled)
 
 
+def _knowledge_dir(project_root: Path, config=None) -> str:
+    """Configured knowledge directory (honors ``knowledge.directory``), best-effort.
+
+    Mirrors ``cli.commands.okf._knowledge_okf_dir`` so doctor inspects the same location
+    ingest writes to. Any config failure falls back to the documented default rather than
+    raising — doctor must keep running even with a broken config.
+
+    ``config`` is an optional pre-loaded config (default ``None`` loads as before), so a
+    single doctor invocation can reuse one ``load_config`` call across checks.
+    """
+    directory = ".devcouncil/knowledge"
+    try:
+        cfg = config if config is not None else load_config(project_root)
+        directory = cfg.knowledge.directory
+    except Exception:
+        pass
+    return directory
+
+
+def check_ingested_knowledge(project_root: Path, config=None) -> list[tuple[str, str, str]]:
+    """Best-effort health rows for ingested knowledge under ``<knowledge dir>/{okf,design}``.
+
+    Returns ``(component, status_markup, notes)`` rows for the doctor table. This is the
+    most common "ingested but silently broken" surface: an OKF bundle with a dangling
+    cross-link, or a design.md with broken token references, both validate clean to the
+    eye but degrade the prompt context. We therefore read+validate every ingested bundle
+    and lint the design system, reporting counts and any problems.
+
+    Never raises: any knowledge-layer failure becomes a ``WARN`` row, and an empty
+    knowledge area yields a neutral ``INFO`` row — a project that never ingested knowledge
+    is not a misconfiguration.
+    """
+    ok = "[green]OK[/green]"
+    warn = "[yellow]WARN[/yellow]"
+    info = "[cyan]INFO[/cyan]"
+    rows: list[tuple[str, str, str]] = []
+
+    directory = _knowledge_dir(project_root, config=config)
+    base = project_root / directory
+    okf_area = base / "okf"
+    design_md = base / "design" / "design.md"
+
+    # Identify ingested OKF bundles. `dev okf ingest` writes each bundle into its own
+    # subfolder under okf/; treat each such subdir as a bundle. If documents sit loose
+    # directly under okf/ (and there are no subfolder bundles), treat okf/ as one bundle.
+    # Choosing one or the other avoids double-counting documents via rglob.
+    bundle_dirs: list[Path] = []
+    if okf_area.is_dir():
+        try:
+            subdir_bundles = [
+                child
+                for child in sorted(okf_area.iterdir())
+                if child.is_dir() and any(child.rglob("*.md"))
+            ]
+        except Exception:
+            subdir_bundles = []
+        loose_docs = any(p.is_file() for p in okf_area.glob("*.md"))
+        if subdir_bundles:
+            bundle_dirs = subdir_bundles
+        elif loose_docs:
+            bundle_dirs = [okf_area]
+
+    has_design = design_md.is_file()
+
+    # Nothing ingested at all → neutral info line, not a failure.
+    if not bundle_dirs and not has_design:
+        rows.append(
+            (
+                "Ingested knowledge",
+                info,
+                f"No ingested knowledge under {directory}/ (okf/, design/). "
+                "Add some with 'dev okf ingest <bundle>'.",
+            )
+        )
+        return rows
+
+    # --- OKF bundles -----------------------------------------------------------------
+    if bundle_dirs:
+        from devcouncil.knowledge.okf import read_bundle, validate_bundle
+
+        total_docs = 0
+        problems: list[str] = []
+        for bdir in bundle_dirs:
+            try:
+                bundle = read_bundle(bdir)
+                total_docs += len(bundle.documents)
+                problems.extend(validate_bundle(bundle))
+            except Exception as exc:  # never let a malformed bundle crash doctor
+                problems.append(f"{bdir.name}: failed to read bundle ({exc})")
+        summary = f"{len(bundle_dirs)} bundle(s), {total_docs} document(s)"
+        if problems:
+            preview = "; ".join(problems[:5])
+            extra = "" if len(problems) <= 5 else f" (+{len(problems) - 5} more)"
+            rows.append(
+                (
+                    "Ingested OKF",
+                    warn,
+                    f"{summary}: {len(problems)} validation problem(s): {preview}{extra}.",
+                )
+            )
+        else:
+            rows.append(("Ingested OKF", ok, f"{summary}; no validation problems."))
+
+    # --- Design system ----------------------------------------------------------------
+    if has_design:
+        from devcouncil.knowledge.design import lint, parse_design_md
+
+        try:
+            findings = lint(parse_design_md(design_md))
+        except Exception as exc:  # never let a malformed design.md crash doctor
+            rows.append(("Ingested design.md", warn, f"present, but lint failed: {exc}."))
+        else:
+            if findings:
+                preview = "; ".join(f.format() for f in findings[:5])
+                extra = "" if len(findings) <= 5 else f" (+{len(findings) - 5} more)"
+                rows.append(
+                    (
+                        "Ingested design.md",
+                        warn,
+                        f"present; {len(findings)} lint finding(s): {preview}{extra}.",
+                    )
+                )
+            else:
+                rows.append(("Ingested design.md", ok, "present; 0 lint findings."))
+
+    return rows
+
+
+def _add_logging_row(table, project_root: Path) -> None:
+    """Append a logging-health row: where the durable run log lives and how big it
+    is, so a user chasing a recurring failure knows exactly where to look."""
+    from devcouncil.telemetry.logging_setup import LOG_RELATIVE_PATH
+
+    log_path = project_root / LOG_RELATIVE_PATH
+    if log_path.exists():
+        size_kb = log_path.stat().st_size / 1024
+        detail = f"{log_path} ({size_kb:.0f} KB). View: dev logs tail"
+    else:
+        detail = f"Will write to {log_path} on first command. View: dev logs tail"
+    table.add_row("logging", "[green]OK[/green]", detail)
+
+
 def render_doctor_check(project_root: Path = Path(".")):
+    # Load config once for the whole invocation; the diagnostic checks below reuse
+    # this instead of re-reading config.yaml. None falls back to per-check loading.
+    try:
+        config = load_config(project_root)
+    except Exception:
+        config = None
+
     def _command_version(command: list[str]) -> str | None:
         executable = shutil.which(command[0])
         if not executable:
@@ -169,8 +318,13 @@ def render_doctor_check(project_root: Path = Path(".")):
             "No built-in coding CLI on PATH. Run dev integrate recommend after installing one.",
         )
 
+    # Ingested-knowledge health (added before the provider branch so it appears on every
+    # code path, including the early returns for ollama / unsupported providers).
+    for component, status, notes in check_ingested_knowledge(project_root, config=config):
+        table.add_row(component, status, notes)
+
     try:
-        provider = load_config(project_root).models.provider
+        provider = config.models.provider if config is not None else "openrouter"
     except Exception:
         provider = "openrouter"
     try:
@@ -182,6 +336,7 @@ def render_doctor_check(project_root: Path = Path(".")):
             "[red]Unsupported[/red]",
             f"{provider} is configured, but this runtime supports: {supported}.",
         )
+        _add_logging_row(table, project_root)
         console.print(table)
         return
     if provider == "ollama":
@@ -218,10 +373,10 @@ def render_doctor_check(project_root: Path = Path(".")):
 
         # A reachable server with the configured model NOT pulled is the most common
         # "all-green doctor, 404 on first call" trap. Verify the role models exist locally.
-        if reachable:
+        if reachable and config is not None:
             try:
                 configured_models = sorted(
-                    {role.model for role in load_config(project_root).models.roles.values() if role.model}
+                    {role.model for role in config.models.roles.values() if role.model}
                 )
             except Exception:
                 configured_models = []
@@ -285,6 +440,7 @@ def render_doctor_check(project_root: Path = Path(".")):
             f"(dev setup --provider ollama --model {host.recommended_ollama_model}).",
         )
 
+        _add_logging_row(table, project_root)
         console.print(table)
         return
     env_var = provider_api_key_env_var(provider)
@@ -319,6 +475,7 @@ def render_doctor_check(project_root: Path = Path(".")):
         location = os.environ.get("VERTEXAI_LOCATION") or local_secrets.get("VERTEXAI_LOCATION", "global")
         table.add_row("VERTEXAI_LOCATION", "[green]OK[/green]", location)
 
+    _add_logging_row(table, project_root)
     console.print(table)
 
 

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

@@ -1,5 +1,6 @@
 import asyncio
 import hashlib
+import logging
 import subprocess
 from pathlib import Path
 from types import SimpleNamespace
@@ -7,6 +8,9 @@ from types import SimpleNamespace
 import typer
 from rich.console import Console
 
+from devcouncil.telemetry.stages import log_stage, log_step
+from devcouncil.telemetry.logging_setup import set_log_dir
+
 from devcouncil.app.config import load_config
 from devcouncil.cli.commands import plan as plan_command
 from devcouncil.cli.commands import report as report_command
@@ -31,6 +35,7 @@ from devcouncil.reporting.report_builder import ReportBuilder
 
 
 console = Console()
+logger = logging.getLogger(__name__)
 
 SUPPORTED_EXECUTORS = {
     *BUILTIN_CODING_EXECUTOR_NAMES,
@@ -104,7 +109,22 @@ def _blocking_gap_signature(root: Path, task_id: str) -> str:
     if not db:
         return ""
     with db.get_session() as session:
-        gaps = [g for g in GapRepository(session).get_all() if g.task_id == task_id and g.blocking]
+        gaps = GapRepository(session).get_blocking_for_task(task_id)
+    key = "\n".join(sorted(f"{g.gap_type}:{g.description}" for g in gaps))
+    return hashlib.sha1(key.encode("utf-8")).hexdigest() if key else ""
+
+
+def _remediable_incomplete_signature(root: Path, task_id: str) -> str:
+    """Fingerprint of a task's remediable "incomplete" gaps (unproven acceptance criteria
+    the executor could still prove), for driving and no-progress-checking the repair loop
+    when the task verified without a hard block but isn't actually done."""
+    from devcouncil.planning.correction_manifest import remediable_incomplete_gaps
+
+    db = get_db(root)
+    if not db:
+        return ""
+    with db.get_session() as session:
+        gaps = remediable_incomplete_gaps(GapRepository(session).get_for_task(task_id))
     key = "\n".join(sorted(f"{g.gap_type}:{g.description}" for g in gaps))
     return hashlib.sha1(key.encode("utf-8")).hexdigest() if key else ""
 
@@ -122,7 +142,7 @@ def _build_repair_service(root: Path):
         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, project_root=root)
+        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()}
         return RepairService(ModelRouter(provider, role_config, project_root=root))
     except Exception:
@@ -138,6 +158,7 @@ def _execute_task_with_repair(
     stream: bool,
     max_repairs: int,
     repair_service,
+    config=None,
 ) -> tuple[str, int]:
     """Run a task, then self-repair in a bounded loop until it verifies or the budget
     is exhausted. Returns ``(final_status, repair_attempts_used)``.
@@ -174,16 +195,26 @@ def _execute_task_with_repair(
 
     _run_once()
     status = _task_status(root, task.id)
+    logger.info("Initial run of %s finished as %s (max_repairs=%d)", task.id, status, max_repairs)
 
     attempt = 0
     last_signature: str | None = None
-    while status not in {"verified", "done"} and attempt < max_repairs:
-        signature = _blocking_gap_signature(root, task.id)
+    while attempt < max_repairs:
+        blocked = status not in {"verified", "done"}
+        # When the task is blocked, repair against its blocking gaps. When it "verified"
+        # without a hard block but is still INCOMPLETE (an acceptance criterion the
+        # executor could prove has no passing evidence), keep repairing too — otherwise
+        # arm B stalls one proof short of done (the eval_rpn 5/7-incomplete case).
+        signature = (
+            _blocking_gap_signature(root, task.id) if blocked
+            else _remediable_incomplete_signature(root, task.id)
+        )
         if not signature:
-            # Blocked without recorded blocking gaps (e.g. the executor failed to
-            # start) — there is nothing concrete to repair against, so stop.
+            # Nothing concrete to repair: truly done, or blocked with no recorded gaps
+            # (e.g. the executor failed to start).
             break
         if signature == last_signature:
+            logger.warning("%s: repair made no progress (identical gaps) after attempt %d; stopping loop", task.id, attempt)
             console.print(
                 f"[yellow]{task.id}: repair made no progress (identical blocking gaps); "
                 "stopping the self-repair loop.[/yellow]"
@@ -202,18 +233,23 @@ def _execute_task_with_repair(
         if _commit_task_changes(root, task.id, status):
             intermediate_commits += 1
 
-        manifest_path = write_correction_manifest(root, task.id, repair_service=repair_service)
+        manifest_path = write_correction_manifest(
+            root, task.id, repair_service=repair_service, config=config, include_incomplete=True
+        )
         if manifest_path is None:
             break
         attempt += 1
+        logger.info("Self-repair attempt %d/%d for %s (was %s); manifest=%s", attempt, max_repairs, task.id, status, manifest_path)
         console.print(
             f"\n[bold]Self-repair attempt {attempt}/{max_repairs}[/bold] for "
             f"[bold]{task.id}[/bold] (was {status})..."
         )
         _run_once()
         status = _task_status(root, task.id)
+        logger.info("After repair attempt %d, %s is now %s", attempt, task.id, status)
 
     if status not in {"verified", "done"} and attempt >= max_repairs and max_repairs > 0:
+        logger.warning("%s: gave up after %d repair attempt(s); still %s", task.id, attempt, status)
         console.print(
             f"[yellow]{task.id}: gave up after {attempt} repair attempt(s); still {status}.[/yellow]"
         )
@@ -224,6 +260,7 @@ def _execute_task_with_repair(
     # isn't lost and the final reconciliation pass still sees committed changes.
     if status in {"verified", "done"} and squash_base and intermediate_commits:
         if _squash_repair_commits(root, task.id, squash_base, status):
+            logger.info("Squashed %d blocked attempt commit(s) for %s into one verified commit", intermediate_commits, task.id)
             console.print(
                 f"[dim]Squashed {intermediate_commits} blocked attempt commit(s) for "
                 f"{task.id} into one verified commit.[/dim]"
@@ -463,6 +500,11 @@ def go(
     Run the full DevCouncil loop in one command.
     """
     root = project_root.expanduser().resolve()
+    set_log_dir(root)
+    logger.info(
+        "dev go starting: goal=%r executor=%s quick=%s force=%s root=%s",
+        goal, executor, quick, force, root,
+    )
     initialize_project(root, quiet=True)
 
     # A goal like "#142" or a GitHub issue/PR URL is a reference, not a spec —
@@ -500,7 +542,8 @@ def go(
 
     console.print(f"[bold]Planning goal:[/bold] {goal}")
     try:
-        planned_task_ids = asyncio.run(plan_command.run_plan_flow(goal, dry_run=dry_run, persist=True, project_root=root, quick=quick))
+        with log_stage("plan", project_root=root, quick=quick, dry_run=dry_run):
+            planned_task_ids = asyncio.run(plan_command.run_plan_flow(goal, dry_run=dry_run, persist=True, project_root=root, quick=quick))
     except (ProviderRequestError, StructuredOutputError) as exc:
         plan_command.print_planning_error(exc)
         raise typer.Exit(code=1)
@@ -513,6 +556,7 @@ def go(
     # anyway and proceed — verification still gates each task's actual diff.
     if not task_ids:
         if force:
+            logger.info("No auto-approved tasks; force-approving generated plan past planning gaps")
             try:
                 plan_command.approve(run_id=None, force=True, project_root=root)
             except SystemExit:
@@ -526,6 +570,7 @@ def go(
         else:
             tasks = []
         if not tasks:
+            logger.warning("Planning produced no approved tasks; aborting run")
             console.print("[red]Planning did not produce any approved tasks.[/red]")
             console.print(
                 "Review gaps with [bold]dev status[/bold], then run [bold]dev approve[/bold] "
@@ -548,11 +593,21 @@ def go(
     # the edits), so the repair loop only applies to automated runs.
     max_repairs = _max_repair_attempts(root) if normalized_executor != "manual" else 0
     repair_service = _build_repair_service(root) if max_repairs else None
+    # Load config once for the repair loop so the correction-manifest builder doesn't
+    # reload it from disk on every repair attempt. Only needed when the loop is active;
+    # the builder falls back to loading config itself if this is None.
+    repair_config = load_config(root) if max_repairs else None
     # Run tasks in dependency order so a task never executes before the tasks it needs.
     tasks = topological_order(tasks)
+    log_step(
+        f"execution plan: {len(tasks)} task(s) in dependency order",
+        project_root=root,
+        order=[t.id for t in tasks],
+    )
     completed_ids = {task.id for task in tasks if task.status in {"verified", "done"}}
     for task in tasks:
         if task.status in {"verified", "done"}:
+            logger.info("Skipping %s; already %s", task.id, task.status)
             console.print(f"[green]Skipping {task.id}; already {task.status}.[/green]")
             completed_ids.add(task.id)
             continue
@@ -562,6 +617,7 @@ def go(
         # unsatisfiable precondition. Skip it and surface why.
         unmet = [dep for dep in task.depends_on if dep not in completed_ids]
         if unmet:
+            logger.warning("Skipping %s: upstream %s not completed", task.id, ", ".join(unmet))
             console.print(f"[yellow]Skipping {task.id}: upstream {', '.join(unmet)} not completed.[/yellow]")
             failed.append(f"{task.id} (skipped: upstream {', '.join(unmet)} unsatisfied)")
             continue
@@ -570,14 +626,29 @@ def go(
         executed_task_ids.append(task.id)
         # Run, then self-repair in a bounded loop (closes the autonomous loop: the
         # one-shot executor no longer needs a human to run `dev repair` and re-run).
-        latest_status, repairs_used = _execute_task_with_repair(
-            root,
-            task,
+        with log_stage(
+            "execute_task",
+            project_root=root,
+            task_id=task.id,
             executor=normalized_executor,
-            profile=profile,
-            stream=stream,
             max_repairs=max_repairs,
-            repair_service=repair_service,
+        ):
+            latest_status, repairs_used = _execute_task_with_repair(
+                root,
+                task,
+                executor=normalized_executor,
+                profile=profile,
+                stream=stream,
+                max_repairs=max_repairs,
+                repair_service=repair_service,
+                config=repair_config,
+            )
+        log_step(
+            f"task {task.id} finished as {latest_status}",
+            project_root=root,
+            task_id=task.id,
+            repairs_used=repairs_used,
+            trace=True,
         )
 
         # Commit whatever this task produced so the next task in the plan starts
@@ -585,6 +656,7 @@ def go(
         # tree and the whole multi-task plan stalls after task one.
         if _commit_task_changes(root, task.id, latest_status):
             note = f" after {repairs_used} repair attempt(s)" if repairs_used else ""
+            logger.info("Committed %s changes (%s)%s", task.id, latest_status, note)
             console.print(f"[dim]Committed {task.id} changes ({latest_status}){note}.[/dim]")
 
         if latest_status in {"verified", "done"}:
@@ -595,8 +667,10 @@ def go(
             # don't let one task that blocked or could not start halt the rest. The
             # final reconciliation pass judges the integrated result fairly.
             if not continue_on_blocked:
+                logger.warning("Stopping run: %s ended as %s (no --continue-on-blocked)", task.id, latest_status)
                 console.print(f"[red]Stopping because {task.id} ended as {latest_status}.[/red]")
                 break
+            logger.info("%s ended as %s; continuing to next task (--continue-on-blocked)", task.id, latest_status)
             console.print(f"[yellow]{task.id} ended as {latest_status}; continuing to the next task.[/yellow]")
 
     if not executed_task_ids:
@@ -605,10 +679,13 @@ def go(
     # Final reconciliation: re-verify every task against the fully integrated,
     # committed state. Earlier tasks are verified before later tasks create shared
     # test files, so their gates can pass now even though they blocked mid-run.
-    # The LLM review is diff-gated and the tree is clean here, so this costs no
-    # model calls — it just refreshes statuses/gaps so the final report is honest.
+    # The tree is clean here, so verification uses each task's committed checkpoint
+    # diff to prove its acceptance criteria (rather than skipping on an empty diff and
+    # wrongly blocking). Re-running the same diff is largely an LLM-cache hit, so this
+    # refreshes statuses/gaps cheaply for an honest final report.
     if executed_task_ids and _is_git_repo(root):
         console.print("\n[bold]Reconciling verification against the final integrated state...[/bold]")
+        log_step("reconcile: re-verifying against integrated state", project_root=root)
         try:
             verify_command.verify(task_id=None, sandbox="local", json_format=True, project_root=root)
         except typer.Exit:
@@ -632,10 +709,13 @@ def go(
                 failed.append(f"{planned.id} ({status})")
 
     if not failed:
+        logger.info("dev go complete: all tasks finished")
         _record_project_done(root)
     else:
+        logger.warning("dev go finished with %d unfinished task(s): %s", len(failed), ", ".join(failed))
         _record_project_blocked(root)
 
+    log_step("generating final report", project_root=root)
     console.print("\n[bold]Final DevCouncil report[/bold]")
     report_command.report(
         SimpleNamespace(invoked_subcommand=None),  # type: ignore[arg-type]