devcouncil 0.3.1 → 0.4.0

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

@@ -1,10 +1,12 @@
 import asyncio
+import logging
 
 import typer
 
-from devcouncil.integrations.mcp.server import run
+from devcouncil.telemetry.stages import log_stage, log_step
 
 app = typer.Typer()
+logger = logging.getLogger(__name__)
 
 
 @app.callback(invoke_without_command=True)
@@ -15,4 +17,12 @@ def mcp_server(ctx: typer.Context):
     if ctx.invoked_subcommand is not None:
         return
 
-    asyncio.run(run())
+    # Deferred import: the MCP SDK (and the server module's large import surface)
+    # loads only when this command actually runs, not on every `dev` invocation —
+    # main.py imports every command module even for `dev --help`.
+    from devcouncil.integrations.mcp.server import run
+
+    logger.info("dev mcp-server: starting stdio server")
+    with log_stage("mcp_server"):
+        log_step("mcp_server/1: initializing stdio transport", trace=True)
+        asyncio.run(run())

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

@@ -19,9 +19,12 @@ from devcouncil.cli.commands.init import initialize_project
 from devcouncil.knowledge.okf import read_bundle, validate_bundle
 from devcouncil.storage.db import get_db
 from devcouncil.storage.repositories import ArtifactGraphRepository
+from devcouncil.telemetry.stages import log_stage, log_step
+import logging
 
 app = typer.Typer(help="Export, ingest, and validate Open Knowledge Format bundles.")
 console = Console()
+logger = logging.getLogger(__name__)
 
 
 def _knowledge_okf_dir(root: Path) -> Path:
@@ -30,8 +33,8 @@ def _knowledge_okf_dir(root: Path) -> Path:
     directory = ".devcouncil/knowledge"
     try:
         directory = load_config(root).knowledge.directory
-    except Exception:
-        pass
+    except Exception as e:
+        logger.debug("Failed to load knowledge directory from config, using default: %s", e)
     return root / directory / "okf"
 
 
@@ -46,8 +49,8 @@ def _knowledge_design_md(root: Path) -> Path | None:
     directory = ".devcouncil/knowledge"
     try:
         directory = load_config(root).knowledge.directory
-    except Exception:
-        pass
+    except Exception as e:
+        logger.debug("Failed to load knowledge directory from config, using default: %s", e)
     candidates = [
         root / directory / "design" / "design.md",
         root / ".devcouncil" / "knowledge" / "design" / "design.md",
@@ -75,12 +78,22 @@ def export(
 ):
     """Export the DevCouncil artifact graph as an OKF bundle."""
     root = project_root.expanduser().resolve()
+    from devcouncil.telemetry.logging_setup import set_log_dir
+    set_log_dir(root)
+    logger.info("dev okf export")
     initialize_project(root, quiet=True)
     db = get_db(root)
     if not db:
         console.print("[red]DevCouncil state is unavailable in this directory.[/red]")
         raise typer.Exit(code=1)
 
+    with log_stage("okf", project_root=root, subcommand="export"):
+        log_step("okf/1: exporting OKF bundle", project_root=root, trace=True)
+        _run_okf_export(root, db, output, skills, design)
+        log_step("okf/complete", project_root=root, trace=True)
+
+
+def _run_okf_export(root, db, output, skills, design):
     out_dir = output.expanduser().resolve()
     with db.get_session() as session:
         graph = ArtifactGraphRepository(session).load_graph()
@@ -90,8 +103,8 @@ def export(
         from devcouncil.app.config import load_config
 
         project_name = load_config(root).project.name or project_name
-    except Exception:
-        pass
+    except Exception as e:
+        logger.debug("Failed to load project name from config, using directory name: %s", e)
 
     # Load the FULL skill set (packaged library + this repo's own skills) so the export is
     # complete; goal-driven selection would only emit the few skills that match a goal.
@@ -219,6 +232,31 @@ def validate(
     raise typer.Exit(code=1)
 
 
+@app.command("select")
+def select_knowledge(
+    goal: str = typer.Option(..., "--goal", "-g", help="Task goal used to rank ingested knowledge sources."),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
+    json_output: bool = typer.Option(False, "--json", help="Emit machine-readable JSON."),
+) -> None:
+    """Select OKF/design knowledge sources that match a goal."""
+    from devcouncil.knowledge.knowledge_select import select_knowledge_payload
+
+    root = project_root.expanduser().resolve()
+    payload = select_knowledge_payload(root, goal)
+    if json_output:
+        console.print_json(data=payload)
+        return
+    sources = payload.get("sources")
+    if isinstance(sources, list):
+        for source in sources:
+            if isinstance(source, dict):
+                console.print(
+                    f"- [{source.get('kind')}] {source.get('name')}: {source.get('description')}"
+                )
+    if payload.get("preamble"):
+        console.print("\n" + str(payload["preamble"]))
+
+
 @app.command("html")
 def html(
     bundle: Path = typer.Argument(..., help="Path to an OKF bundle directory to render."),

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

@@ -1,8 +1,8 @@
 import typer
 import asyncio
-import json
 import datetime
 import logging
+import sys
 from typing import Any
 from rich.console import Console
 from rich.panel import Panel
@@ -14,13 +14,19 @@ from devcouncil.storage.repositories import (
     GapRepository,
     PlanningStateRepository,
 )
-from devcouncil.indexing.repo_mapper import RepoMapper
 from devcouncil.integrations.code_review_graph import CodeReviewGraphAdapter
 from devcouncil.llm.provider import Provider, MockProvider, ProviderRequestError, build_role_model_config, create_provider, validate_model_provider
 from devcouncil.llm.router import ModelRouter, StructuredOutputError
 from devcouncil.planning.spec_service import SpecService
 from devcouncil.planning.prompt_enhancer_service import PromptEnhancerService, save_active_prompt_enhancement
 from devcouncil.planning.plan_service import PlanService, backfill_acceptance_criteria
+from devcouncil.planning.plan_difficulty import apply_plan_difficulty
+from devcouncil.planning.planned_files_reconcile import (
+    expand_scope_with_dependents,
+    reconcile_planned_files,
+    repo_files_from_map,
+)
+from devcouncil.planning.question_conversion import convert_blocking_questions_to_assumptions
 from devcouncil.planning.critique_service import CritiqueService
 from devcouncil.planning.arbiter_service import ArbiterDecision, ArbiterService
 from devcouncil.gating.policy import GatePolicy
@@ -29,7 +35,8 @@ from devcouncil.app.state_machine import ProjectPhase
 from devcouncil.app.config import ModelRoleConfig, load_config, get_api_key
 from devcouncil.cli.commands.init import initialize_project
 from devcouncil.telemetry.traces import TraceLogger
-from devcouncil.telemetry.stages import log_step
+from devcouncil.telemetry.stages import log_stage, log_step
+from devcouncil.utils.json_persist import dump_json
 
 app = typer.Typer()
 console = Console()
@@ -86,6 +93,46 @@ def _ensure_planning_roles(config) -> None:
     for role in REQUIRED_PLANNING_ROLES:
         config.models.roles.setdefault(role, fallback.model_copy())
 
+
+def _should_auto_convert_blocking_questions(config) -> bool:
+    if not config.planning.auto_convert_blocking_questions_in_noninteractive:
+        return False
+    return not sys.stdin.isatty()
+
+
+def _maybe_convert_blocking_questions(
+    spec_output,
+    config,
+    console,
+    *,
+    orchestrator=None,
+    artifact_path: Path | None = None,
+):
+    """In non-interactive mode, turn blocking questions into non-blocking assumptions."""
+    if not _should_auto_convert_blocking_questions(config):
+        return spec_output
+    if not spec_output.blocking_questions:
+        return spec_output
+
+    question_count = len(spec_output.blocking_questions)
+    assumptions, cleared = convert_blocking_questions_to_assumptions(
+        spec_output.assumptions,
+        spec_output.blocking_questions,
+    )
+    spec_output = spec_output.model_copy(
+        update={"assumptions": assumptions, "blocking_questions": cleared},
+    )
+    console.print(
+        f"[dim]Non-interactive mode: converted {question_count} blocking question(s) "
+        "to open assumptions (will not block plan approval).[/dim]"
+    )
+    if orchestrator is not None and orchestrator.current_run is not None:
+        orchestrator.save_run_artifact("requirements.json", spec_output.model_dump())
+    elif artifact_path is not None:
+        artifact_path.write_text(spec_output.model_dump_json(indent=2), encoding="utf-8")
+    return spec_output
+
+
 async def run_plan_flow(
     goal: str,
     requirements_only: bool = False,
@@ -129,7 +176,7 @@ async def run_plan_flow(
 
         provider = MockProvider()
         provider.responses = {
-            "mock/prompt_enhancer": json.dumps({
+            "mock/prompt_enhancer": dump_json({
                 "original_goal": goal,
                 "enhanced_goal": (
                     f"Plan and implement {goal} using the mapped repository's "
@@ -139,26 +186,26 @@ async def run_plan_flow(
                 "debate_focus": ["Compare minimal implementation scope against production-readiness concerns."],
                 "constraints": [f"Do not broaden beyond: {goal}."]
             }),
-            "mock/spec_writer": json.dumps({
+            "mock/spec_writer": dump_json({
                 "requirements": [{"id": "REQ-001", "title": "Mock Req", "description": "Desc", "priority": "high", "source": "user", "acceptance_criteria": []}],
                 "assumptions": [],
                 "blocking_questions": []
             }),
             "mock/planner_a": [
-                json.dumps({
+                dump_json({
                     "id": "PLAN-A", "rationale": "Simple", "tasks": [{"id": "TASK-001", "title": "Mock Task", "description": "Desc", "requirement_ids": ["REQ-001"], "acceptance_criterion_ids": [], "planned_files": [], "expected_tests": [], "allowed_commands": [], "status": "planned"}]
                 }),
-                json.dumps({"rebuttals": []})
+                dump_json({"rebuttals": []})
             ],
             "mock/planner_b": [
-                json.dumps({
+                dump_json({
                     "id": "PLAN-B", "rationale": "Robust", "tasks": [{"id": "TASK-001", "title": "Mock Task", "description": "Desc", "requirement_ids": ["REQ-001"], "acceptance_criterion_ids": [], "planned_files": [], "expected_tests": [], "allowed_commands": [], "status": "planned"}]
                 }),
-                json.dumps({"rebuttals": []})
+                dump_json({"rebuttals": []})
             ],
             "mock/critic_a": '{"findings": []}',
             "mock/critic_b": '{"findings": []}',
-            "mock/arbiter": json.dumps({
+            "mock/arbiter": dump_json({
                 "accepted_finding_ids": [], "rejected_finding_ids": [], 
                 "final_requirements": [{"id": "REQ-001", "title": "Mock Req", "description": "Desc", "priority": "high", "source": "user", "acceptance_criteria": [{"id": "AC-1", "description": "Test it", "verification_method": "unit_test"}]}],
                 "final_tasks": [{"id": "TASK-001", "title": "Mock Task", "description": "Desc", "requirement_ids": ["REQ-001"], "acceptance_criterion_ids": ["AC-1"], "planned_files": [{"path": "test.py", "reason": "logic", "allowed_change": "modify"}], "expected_tests": [], "allowed_commands": [], "status": "planned"}]
@@ -182,17 +229,37 @@ async def run_plan_flow(
     plan_service = PlanService(router)
     critique_service = CritiqueService(router)
     arbiter_service = ArbiterService(router)
-    mapper = RepoMapper(root)
+    with log_stage("plan", project_root=root, run_id=run_id, goal=goal, quick=quick, dry_run=dry_run):
+        return await _run_plan_body(
+            root, goal, requirements_only, dry_run, persist, quick,
+            orchestrator, run_id, db, config, router,
+            prompt_enhancer, spec_service, plan_service, critique_service,
+            arbiter_service,
+        )
 
+
+async def _run_plan_body(
+    root, goal, requirements_only, dry_run, persist, quick,
+    orchestrator, run_id, db, config, router,
+    prompt_enhancer, spec_service, plan_service, critique_service,
+    arbiter_service,
+):
     with Progress(
         SpinnerColumn(),
         TextColumn("[progress.description]{task.description}"),
         transient=True,
     ) as progress:
         # 1. Repo Map
-        log_step("plan/1: mapping repository", project_root=root, run_id=run_id)
+        log_step("plan/1: mapping repository", project_root=root, run_id=run_id, trace=True)
         progress.add_task(description="Mapping repository...", total=None)
-        repo_map = mapper.map_repo(goal)
+        from devcouncil.indexing.map_artifacts import refresh_map_artifacts
+
+        repo_map = refresh_map_artifacts(
+            root,
+            root / ".devcouncil" / "repo_map.json",
+            goal,
+            quiet=True,
+        ).repo_map
         repo_map_json = repo_map.model_dump_json(indent=2)
         # save_run_artifact re-serializes via json.dump, so pass the dict directly
         # instead of round-tripping the already-serialized JSON back through json.loads.
@@ -203,7 +270,7 @@ async def run_plan_flow(
         await orchestrator.transition_to(ProjectPhase.REPO_MAPPED)
 
         # 2. Codebase-specific prompt enhancement
-        log_step("plan/2: enhancing prompt for codebase debate", project_root=root, run_id=run_id)
+        log_step("plan/2: enhancing prompt for codebase debate", project_root=root, run_id=run_id, trace=True)
         progress.add_task(description="Enhancing prompt for codebase debate...", total=None)
         prompt_enhancement = await prompt_enhancer.enhance_prompt(
             goal,
@@ -234,7 +301,7 @@ async def run_plan_flow(
         )
 
         # 3. Spec / Requirements
-        log_step("plan/3: generating requirements", project_root=root, run_id=run_id)
+        log_step("plan/3: generating requirements", project_root=root, run_id=run_id, trace=True)
         progress.add_task(description="Generating requirements...", total=None)
         spec_output = await spec_service.generate_spec(debate_goal, repo_map_json)
         orchestrator.save_run_artifact("requirements.json", spec_output.model_dump())
@@ -244,7 +311,7 @@ async def run_plan_flow(
             console.print(Panel(f"Found {len(spec_output.requirements)} requirements.", title="Requirements Generated"))
             return []
 
-        requirements_json = json.dumps([r.model_dump() for r in spec_output.requirements])
+        requirements_json = dump_json([r.model_dump() for r in spec_output.requirements])
 
         if quick:
             # Rigor dial: single pragmatic plan, no A/B debate, critique, rebuttal,
@@ -253,7 +320,7 @@ async def run_plan_flow(
             # adversarial robustness for ~5 fewer model calls — the right setting
             # for small, well-scoped changes where verification (which still gates
             # every diff) is the real safety net, not planning debate.
-            log_step("plan/4: generating single plan (quick mode)", project_root=root, run_id=run_id)
+            log_step("plan/4: generating single plan (quick mode)", project_root=root, run_id=run_id, trace=True)
             progress.add_task(description="Generating single plan (quick mode)...", total=None)
             plan_a = await plan_service.generate_plan(
                 "planner_a", debate_goal, requirements_json, repo_map_json
@@ -277,7 +344,7 @@ async def run_plan_flow(
             final_tasks = [task.model_copy(update={"status": "planned"}) for task in decision.final_tasks]
         else:
             # 4. Independent Plans (run concurrently — they don't depend on each other)
-            log_step("plan/4: generating Plans A (pragmatic) and B (robust)", project_root=root, run_id=run_id)
+            log_step("plan/4: generating Plans A (pragmatic) and B (robust)", project_root=root, run_id=run_id, trace=True)
             progress.add_task(description="Generating Plans A (Pragmatic) and B (Robust)...", total=None)
             plan_a, plan_b = await asyncio.gather(
                 plan_service.generate_plan("planner_a", debate_goal, requirements_json, repo_map_json),
@@ -293,7 +360,7 @@ async def run_plan_flow(
             plan_b_json = plan_b.model_dump_json()
 
             # 5. Cross-Critique (independent — run concurrently)
-            log_step("plan/5: cross-critiquing Plans A and B", project_root=root, run_id=run_id)
+            log_step("plan/5: cross-critiquing Plans A and B", project_root=root, run_id=run_id, trace=True)
             progress.add_task(description="Critiquing Plans A and B...", total=None)
             critique_a, critique_b = await asyncio.gather(
                 critique_service.generate_critique("critic_a", plan_b_json, requirements_json),
@@ -306,7 +373,7 @@ async def run_plan_flow(
             critique_b_json = critique_b.model_dump_json()
 
             # 6. Rebuttals (independent — run concurrently)
-            log_step("plan/6: generating rebuttals", project_root=root, run_id=run_id)
+            log_step("plan/6: generating rebuttals", project_root=root, run_id=run_id, trace=True)
             progress.add_task(description="Generating rebuttals...", total=None)
             rebuttal_a, rebuttal_b = await asyncio.gather(
                 critique_service.generate_rebuttal("planner_a", plan_a_json, critique_b_json),
@@ -316,7 +383,7 @@ async def run_plan_flow(
             orchestrator.save_run_artifact("rebuttal_b.json", rebuttal_b.model_dump())
 
             # 7. Arbitration
-            log_step("plan/7: arbitrating final plan", project_root=root, run_id=run_id)
+            log_step("plan/7: arbitrating final plan", project_root=root, run_id=run_id, trace=True)
             progress.add_task(description="Arbitrating final plan...", total=None)
             decision = await arbiter_service.arbitrate(
                 debate_goal,
@@ -350,12 +417,37 @@ async def run_plan_flow(
             f"[dim]Linked {len(backfilled_acs)} unmapped acceptance criterion(s) to owning task(s) "
             "so every elaborated behavior is verified.[/dim]"
         )
+    # Ground planner-named files in the real repo before they become the scope
+    # whitelist: repair a typo'd/renamed modify target to its true path so the
+    # agent's correct write isn't reverted for pointing at a path the planner
+    # misspelled. Only relaxes/repairs scope — never tightens it.
+    final_tasks, planned_file_warnings = reconcile_planned_files(
+        final_tasks, repo_files_from_map(repo_map)
+    )
+    for warning in planned_file_warnings:
+        console.print(f"[yellow]{warning}[/yellow]")
+
+    # The other half: add the real callers (repo-map dependents) of each writable
+    # file so a caller the planner omitted isn't reverted mid-run. Only widens scope.
+    final_tasks, scope_widen_warnings = expand_scope_with_dependents(
+        final_tasks, repo_map.dependents, repo_files_from_map(repo_map)
+    )
+    for warning in scope_widen_warnings:
+        console.print(f"[dim]{warning}[/dim]")
+
+    final_tasks, difficulty_warnings = apply_plan_difficulty(final_tasks, decision.final_requirements)
+    for warning in difficulty_warnings:
+        console.print(f"[yellow]{warning}[/yellow]")
 
     console.print(f"Final Requirements: [bold]{len(decision.final_requirements)}[/bold]")
     console.print(f"Final Tasks: [bold]{len(final_tasks)}[/bold]")
 
+    spec_output = _maybe_convert_blocking_questions(
+        spec_output, config, console, orchestrator=orchestrator,
+    )
+
     # 8. Check Gates
-    log_step("plan/8: checking plan-approval gates", project_root=root, run_id=run_id)
+    log_step("plan/8: checking plan-approval gates", project_root=root, run_id=run_id, trace=True)
     policy = GatePolicy()
     result = policy.check_plan_approval(
         decision.final_requirements,
@@ -384,6 +476,7 @@ async def run_plan_flow(
         console.print("[green]Plan approved by gates.[/green]")
         logger.info("Plan approved by gates: %d task(s)", len(final_tasks))
         await orchestrator.transition_to(ProjectPhase.PLAN_APPROVED)
+        log_step("plan/complete: approved", project_root=root, run_id=run_id, trace=True)
         return [task.id for task in final_tasks]
     else:
         if persist:
@@ -394,6 +487,7 @@ async def run_plan_flow(
         console.print("[yellow]Plan generated but failed gates. See status for gaps.[/yellow]")
         logger.warning("Plan failed approval gates with %d gap(s)", len(result.gaps))
         await orchestrator.transition_to(ProjectPhase.AWAITING_USER_DECISIONS)
+        log_step("plan/complete: awaiting user decisions", project_root=root, run_id=run_id, trace=True)
         return []
 
 def _latest_run_with_decision(root: Path, run_id: str | None) -> Path | None:
@@ -422,64 +516,81 @@ def approve(
     from devcouncil.planning.spec_service import SpecOutput
 
     root = project_root.expanduser().resolve()
+    from devcouncil.telemetry.logging_setup import set_log_dir
+    set_log_dir(root)
+    logger.info("dev plan approve: run_id=%s force=%s", run_id or "latest", force)
     db = get_db(root)
     if not db:
         console.print("[red]DevCouncil state is unavailable in this directory.[/red]")
         raise typer.Exit(code=1)
 
-    run_dir = _latest_run_with_decision(root, run_id)
-    if run_dir is None:
-        console.print("[red]No planning run with a decision was found. Run 'dev plan' first.[/red]")
-        raise typer.Exit(code=1)
-
-    decision = ArbiterDecision.model_validate_json((run_dir / "decision.json").read_text(encoding="utf-8"))
-    spec_path = run_dir / "requirements.json"
-    spec_output = (
-        SpecOutput.model_validate_json(spec_path.read_text(encoding="utf-8")) if spec_path.exists() else None
-    )
-
-    findings = []
-    for name in ("critique_a.json", "critique_b.json"):
-        critique_path = run_dir / name
-        if critique_path.exists():
-            findings.extend(CritiqueOutput.model_validate_json(critique_path.read_text(encoding="utf-8")).findings)
-    reconciled_findings = _reconcile_findings(findings, decision)
-    final_tasks = [task.model_copy(update={"status": "planned"}) for task in decision.final_tasks]
-    assumptions = spec_output.assumptions if spec_output else []
+    with log_stage("approve", project_root=root, run_id=run_id or "latest", force=force):
+        log_step("approve/1: loading plan decision", project_root=root, trace=True)
+        run_dir = _latest_run_with_decision(root, run_id)
+        if run_dir is None:
+            console.print("[red]No planning run with a decision was found. Run 'dev plan' first.[/red]")
+            raise typer.Exit(code=1)
+
+        decision = ArbiterDecision.model_validate_json((run_dir / "decision.json").read_text(encoding="utf-8"))
+        spec_path = run_dir / "requirements.json"
+        spec_output = (
+            SpecOutput.model_validate_json(spec_path.read_text(encoding="utf-8")) if spec_path.exists() else None
+        )
 
-    policy = GatePolicy()
-    result = policy.check_plan_approval(
-        decision.final_requirements,
-        final_tasks,
-        assumptions=assumptions,
-        findings=reconciled_findings,
-        blocking_questions=spec_output.blocking_questions if spec_output else [],
-    )
-    if not result.passed and not force:
-        console.print("[yellow]Plan still fails approval gates:[/yellow]")
-        for gap in result.gaps:
-            marker = "[red][BLOCKING][/red] " if gap.blocking else ""
-            console.print(f" - {marker}{gap.description} (Fix: {gap.recommended_fix})")
-        console.print("Resolve the gaps and re-run 'dev plan', or use --force to approve anyway.")
-        raise typer.Exit(code=1)
+        config = load_config(root)
+        if spec_output is not None:
+            spec_output = _maybe_convert_blocking_questions(
+                spec_output,
+                config,
+                console,
+                artifact_path=spec_path if spec_path.exists() else None,
+            )
 
-    with db.get_session() as session:
-        GapRepository(session).delete_plan_gaps()
-        PlanningStateRepository(session).replace_active_plan(
+        findings = []
+        for name in ("critique_a.json", "critique_b.json"):
+            critique_path = run_dir / name
+            if critique_path.exists():
+                findings.extend(CritiqueOutput.model_validate_json(critique_path.read_text(encoding="utf-8")).findings)
+        reconciled_findings = _reconcile_findings(findings, decision)
+        final_tasks = [task.model_copy(update={"status": "planned"}) for task in decision.final_tasks]
+        final_tasks, _ = apply_plan_difficulty(final_tasks, decision.final_requirements)
+        assumptions = spec_output.assumptions if spec_output else []
+
+        policy = GatePolicy()
+        log_step("approve/2: checking plan-approval gates", project_root=root)
+        result = policy.check_plan_approval(
             decision.final_requirements,
-            assumptions,
             final_tasks,
-            reconciled_findings,
+            assumptions=assumptions,
+            findings=reconciled_findings,
+            blocking_questions=spec_output.blocking_questions if spec_output else [],
         )
+        if not result.passed and not force:
+            console.print("[yellow]Plan still fails approval gates:[/yellow]")
+            for gap in result.gaps:
+                marker = "[red][BLOCKING][/red] " if gap.blocking else ""
+                console.print(f" - {marker}{gap.description} (Fix: {gap.recommended_fix})")
+            console.print("Resolve the gaps and re-run 'dev plan', or use --force to approve anyway.")
+            raise typer.Exit(code=1)
 
-    orchestrator = Orchestrator(root)
-    try:
-        asyncio.run(orchestrator.transition_to(ProjectPhase.PLAN_APPROVED))
-    except ValueError as exc:
-        console.print(f"[red]Cannot approve from the current project phase: {exc}[/red]")
-        raise typer.Exit(code=1)
-    console.print(f"[green]Plan from run {run_dir.name} approved ({len(final_tasks)} tasks).[/green]")
-    console.print("Use 'dev tasks list' to see the planned tasks and 'dev run TASK-ID' to execute one.")
+        with db.get_session() as session:
+            GapRepository(session).delete_plan_gaps()
+            PlanningStateRepository(session).replace_active_plan(
+                decision.final_requirements,
+                assumptions,
+                final_tasks,
+                reconciled_findings,
+            )
+
+        orchestrator = Orchestrator(root)
+        try:
+            asyncio.run(orchestrator.transition_to(ProjectPhase.PLAN_APPROVED))
+        except ValueError as exc:
+            console.print(f"[red]Cannot approve from the current project phase: {exc}[/red]")
+            raise typer.Exit(code=1)
+        console.print(f"[green]Plan from run {run_dir.name} approved ({len(final_tasks)} tasks).[/green]")
+        console.print("Use 'dev tasks list' to see the planned tasks and 'dev run TASK-ID' to execute one.")
+        log_step("approve/complete", project_root=root, run_id=run_dir.name, trace=True)
 
 
 @app.command()
@@ -504,6 +615,10 @@ def plan(
     Run the full planning cycle (Repo map -> Spec -> Plan A/B -> Critique -> Arbiter).
     """
     should_persist = persist or not dry_run
+    root = project_root.expanduser().resolve()
+    from devcouncil.telemetry.logging_setup import set_log_dir
+    set_log_dir(root)
+    logger.info("dev plan: quick=%s dry_run=%s requirements_only=%s", quick, dry_run, requirements_only)
     try:
         asyncio.run(run_plan_flow(goal, requirements_only, dry_run, should_persist, project_root, quick=quick))
     except (ProviderRequestError, StructuredOutputError) as exc:

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

@@ -1,4 +1,5 @@
-import json
+from devcouncil.utils.json_persist import dump_json
+import logging
 from typing import NoReturn
 import typer
 from rich.console import Console
@@ -9,9 +10,11 @@ from devcouncil.storage.repositories import TaskRepository, RequirementRepositor
 from pathlib import Path
 
 from devcouncil.execution.prompt_builder import PromptBuilder
+from devcouncil.telemetry.stages import log_stage, log_step
 
 app = typer.Typer()
 console = Console()
+logger = logging.getLogger(__name__)
 
 @app.callback(invoke_without_command=True)
 def prompt(
@@ -29,33 +32,39 @@ def prompt(
 
     def _fail(message: str) -> NoReturn:
         if json_format:
-            typer.echo(json.dumps({"ok": False, "task_id": task_id, "error": message}, indent=2))
+            typer.echo(dump_json({"ok": False, "task_id": task_id, "error": message}, indent=2))
         else:
             console.print(f"[red]{message}[/red]")
         raise typer.Exit(code=1)
 
     root = project_root.expanduser().resolve()
+    from devcouncil.telemetry.logging_setup import set_log_dir
+    set_log_dir(root)
+    logger.info("dev prompt: task=%s pretty=%s", task_id, pretty)
     initialize_project(root, quiet=True)
     db = get_db(root)
     if not db:
         _fail("DevCouncil state is unavailable in this directory.")
 
-    with db.get_session() as session:
-        task_repo = TaskRepository(session)
-        req_repo = RequirementRepository(session)
+    with log_stage("prompt", project_root=root, task_id=task_id):
+        log_step("prompt/1: loading task and building prompt", project_root=root, task_id=task_id, trace=True)
+        with db.get_session() as session:
+            task_repo = TaskRepository(session)
+            req_repo = RequirementRepository(session)
 
-        task = task_repo.get_by_id(task_id)
-        if not task:
-            _fail(f"Task {task_id} not found.")
+            task = task_repo.get_by_id(task_id)
+            if not task:
+                _fail(f"Task {task_id} not found.")
 
-        reqs = req_repo.get_all()
+            reqs = req_repo.get_all()
 
-        builder = PromptBuilder(root)
-        task_prompt = builder.build_task_prompt(task, reqs)
+            builder = PromptBuilder(root)
+            task_prompt = builder.build_task_prompt(task, reqs)
 
-        if json_format:
-            typer.echo(json.dumps({"ok": True, "task_id": task_id, "prompt": task_prompt}, indent=2))
-        elif pretty:
-            console.print(Markdown(task_prompt))
-        else:
-            typer.echo(task_prompt, nl=not task_prompt.endswith("\n"))
+            if json_format:
+                typer.echo(dump_json({"ok": True, "task_id": task_id, "prompt": task_prompt}, indent=2))
+            elif pretty:
+                console.print(Markdown(task_prompt))
+            else:
+                typer.echo(task_prompt, nl=not task_prompt.endswith("\n"))
+        log_step("prompt/complete", project_root=root, task_id=task_id, trace=True)