devcouncil 0.1.1 → 0.2.0

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

@@ -5,13 +5,85 @@ import typer
 from rich.console import Console
 
 from devcouncil.cli.commands.init import initialize_project
-from devcouncil.indexing.repo_mapper import RepoMapper
+from devcouncil.indexing.repo_mapper import RepoMap, RepoMapper
 from devcouncil.integrations.code_review_graph import CodeReviewGraphAdapter
 from devcouncil.storage.db import get_db
 
 console = Console()
 status_console = Console(stderr=True)
 
+AGENT_GUIDE_MARKER = "<!-- Managed by dev map: keep this file in sync with .devcouncil/repo_map.json. -->"
+
+
+def _important_surfaces(repo_map: RepoMap) -> list[str]:
+    """Derive the 'important surfaces' list from the computed map, so the guide points
+    at THIS repo's real subsystems instead of hardcoded DevCouncil paths."""
+    lines: list[str] = []
+    for index, subsystem in enumerate(repo_map.subsystems[:6], start=1):
+        lines.append(f"{index}. `{subsystem.area}/` — {subsystem.summary}")
+    if not lines:
+        for index, path in enumerate(repo_map.important_files[:6], start=1):
+            lines.append(f"{index}. `{path}`")
+    return lines or ["1. See `.devcouncil/repo_map.json` for the file index."]
+
+
+def _agent_guide_text(repo_map_path: Path, repo_root: Path, repo_map: RepoMap) -> str:
+    return "\n".join(
+        [
+            AGENT_GUIDE_MARKER,
+            "",
+            "# Agent Workspace Guide",
+            "",
+            "Use `.devcouncil/repo_map.json` as the primary file index for this workspace.",
+            f"Repo map: `{repo_map_path.relative_to(repo_root).as_posix() if repo_map_path.is_relative_to(repo_root) else repo_map_path}`",
+            "",
+            "Workflow for agents:",
+            "1. Open `.devcouncil/repo_map.json` before guessing at file locations.",
+            "2. Use the `files` list to resolve module ownership and nearby siblings.",
+            "3. Use `subsystems` for subsystem-level navigation.",
+            "4. In `subsystems`, use `entry_points` + `critical_files` for entry points and starting context.",
+            "5. Use `role_files` in `subsystems` for subsystem role buckets (entry, runtime, policy, adapters, etc.).",
+            "6. Use `neighbors` and `handoff_paths` in `subsystems` to follow cross-subsystem flow.",
+            "7. Run `dev map` again after large refactors to refresh the map.",
+            "",
+            "Important surfaces:",
+            *_important_surfaces(repo_map),
+            "",
+            "If the map and source disagree, trust the source and regenerate the map.",
+        ]
+    )
+
+
+def _write_agent_guides(repo_root: Path, repo_map_path: Path, repo_map: RepoMap) -> None:
+    for filename in ("AGENTS.md", "CLAUDE.md"):
+        path = repo_root / filename
+        if path.exists():
+            existing = path.read_text(encoding="utf-8")
+            if AGENT_GUIDE_MARKER not in existing:
+                continue
+        path.write_text(_agent_guide_text(repo_map_path, repo_root, repo_map) + "\n", encoding="utf-8")
+
+
+def generate_map_artifacts(root: Path, output: Path, goal: str = "", *, scan_dependencies: bool = False) -> RepoMap:
+    """Build the repo map and write repo_map.json + agent guides (no LLM, no re-init).
+
+    Assumes ``.devcouncil/`` already exists. Shared by the ``dev map`` command and
+    by project initialization so a freshly set-up repo is immediately navigable.
+    ``scan_dependencies`` is opt-in (off for init and default mapping) because it can
+    shell out to dependency auditors.
+    """
+    repo_map = RepoMapper(root).map_repo(goal, scan_dependencies=scan_dependencies)
+    graph_context = CodeReviewGraphAdapter(root).get_context()
+    output = output if output.is_absolute() else root / output
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(repo_map.model_dump_json(indent=2), encoding="utf-8")
+    _write_agent_guides(root, output, repo_map)
+    if graph_context.available:
+        graph_output = output.with_name("code_review_graph_context.json")
+        graph_output.write_text(graph_context.model_dump_json(indent=2), encoding="utf-8")
+        status_console.print(f"[green]Wrote code-review-graph context to {graph_output}[/green]")
+    return repo_map
+
 
 def map_repo(
     goal: str = typer.Argument("", help="Goal text used for candidate-file ranking."),
@@ -22,21 +94,19 @@ def map_repo(
         help="Path to write repo_map.json.",
     ),
     project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
+    scan_deps: bool = typer.Option(
+        False,
+        "--scan-deps",
+        help="Run available dependency auditors (pip-audit/npm audit/osv-scanner) and record dependency_risks in the map. Off by default.",
+    ),
 ):
     """Build the deterministic repository map without calling an LLM."""
     root = project_root.expanduser().resolve()
-    initialize_project(root, quiet=True)
+    initialize_project(root, quiet=True, with_map=False)
     if not get_db(root):
         raise typer.Exit(code=1)
 
-    repo_map = RepoMapper(root).map_repo(goal)
-    graph_context = CodeReviewGraphAdapter(root).get_context()
     output = output if output.is_absolute() else root / output
-    output.parent.mkdir(parents=True, exist_ok=True)
-    output.write_text(repo_map.model_dump_json(indent=2), encoding="utf-8")
-    if graph_context.available:
-        graph_output = output.with_name("code_review_graph_context.json")
-        graph_output.write_text(graph_context.model_dump_json(indent=2), encoding="utf-8")
-        status_console.print(f"[green]Wrote code-review-graph context to {graph_output}[/green]")
+    repo_map = generate_map_artifacts(root, output, goal, scan_dependencies=scan_deps)
     typer.echo(json.dumps(repo_map.model_dump(), indent=2))
     status_console.print(f"[green]Wrote repository map to {output}[/green]")

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

@@ -15,13 +15,13 @@ from devcouncil.storage.repositories import (
 )
 from devcouncil.indexing.repo_mapper import RepoMapper
 from devcouncil.integrations.code_review_graph import CodeReviewGraphAdapter
-from devcouncil.llm.provider import MockProvider, create_provider, validate_model_provider
-from devcouncil.llm.router import ModelRouter
+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
 from devcouncil.planning.plan_service import PlanService
 from devcouncil.planning.critique_service import CritiqueService
-from devcouncil.planning.arbiter_service import ArbiterService
+from devcouncil.planning.arbiter_service import ArbiterDecision, ArbiterService
 from devcouncil.gating.policy import GatePolicy
 from devcouncil.app.orchestrator import Orchestrator
 from devcouncil.app.state_machine import ProjectPhase
@@ -32,7 +32,6 @@ from devcouncil.telemetry.traces import TraceLogger
 app = typer.Typer()
 console = Console()
 
-DEFAULT_PLANNING_MODEL = "anthropic/claude-3.5-sonnet"
 REQUIRED_PLANNING_ROLES = (
     "prompt_enhancer",
     "spec_writer",
@@ -75,7 +74,11 @@ def _ensure_planning_roles(config) -> None:
     if fallback is None and config.models.roles:
         fallback = next(iter(config.models.roles.values()))
     if fallback is None:
-        fallback = ModelRoleConfig(model=DEFAULT_PLANNING_MODEL)
+        try:
+            provider_roles = build_role_model_config(config.models.provider)
+            fallback = ModelRoleConfig(model=provider_roles["spec_writer"]["model"])
+        except ValueError:
+            fallback = ModelRoleConfig(model="unconfigured")
 
     for role in REQUIRED_PLANNING_ROLES:
         config.models.roles.setdefault(role, fallback.model_copy())
@@ -86,6 +89,7 @@ async def run_plan_flow(
     dry_run: bool = False,
     persist: bool = True,
     project_root: Path = Path("."),
+    quick: bool = False,
 ):
     root = project_root.expanduser().resolve()
     initialize_project(root, quiet=True)
@@ -112,6 +116,7 @@ async def run_plan_flow(
     run_id = datetime.datetime.now(datetime.timezone.utc).strftime("%Y%m%dT%H%M%SZ") + "-plan"
     await orchestrator.start_run(run_id, goal)
 
+    provider: Provider
     if dry_run:
         # Override config models to be unique roles for mock mapping
         for role in REQUIRED_PLANNING_ROLES:
@@ -158,11 +163,14 @@ async def run_plan_flow(
         # I'll modify PlanService to use a slightly different role string if needed, 
         # but for Dry Run, let's just make the MockProvider return based on the schema requested.
     else:
-        provider = create_provider(config.models.provider, api_key)
+        if api_key is None:
+            console.print("[red]Missing API key for configured model provider.[/red]")
+            return []
+        provider = create_provider(config.models.provider, api_key, project_root=root)
 
     # Build role config after dry-run overrides so mocks are routed correctly.
     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)
     
     prompt_enhancer = PromptEnhancerService(router)
     spec_service = SpecService(router)
@@ -192,9 +200,15 @@ async def run_plan_flow(
             goal,
             repo_map_json,
             graph_context.model_dump_json() if graph_context.available else None,
+            project_root=root,
         )
         debate_goal = prompt_enhancement.debate_prompt()
         orchestrator.save_run_artifact("prompt_enhancement.json", prompt_enhancement.model_dump())
+        if prompt_enhancement.applied_skills:
+            console.print(
+                "[dim]Domain skills applied:[/dim] "
+                + ", ".join(prompt_enhancement.applied_skills)
+            )
         TraceLogger(root).log_event(
             "prompt_enhanced",
             {
@@ -203,6 +217,7 @@ async def run_plan_flow(
                 "codebase_context_count": len(prompt_enhancement.codebase_context),
                 "constraint_count": len(prompt_enhancement.constraints),
                 "debate_focus_count": len(prompt_enhancement.debate_focus),
+                "applied_skills": prompt_enhancement.applied_skills,
                 "artifact": f".devcouncil/runs/{run_id}/prompt_enhancement.json",
             },
             run_id=run_id,
@@ -219,49 +234,82 @@ async def run_plan_flow(
             console.print(Panel(f"Found {len(spec_output.requirements)} requirements.", title="Requirements Generated"))
             return []
 
-        # 4. Independent Plans
-        progress.add_task(description="Generating Plan A (Pragmatic)...", total=None)
-        plan_a = await plan_service.generate_plan("planner_a", debate_goal, json.dumps([r.model_dump() for r in spec_output.requirements]), repo_map_json)
-        orchestrator.save_run_artifact("plan_a.json", plan_a.model_dump())
-        
-        progress.add_task(description="Generating Plan B (Robust)...", total=None)
-        plan_b = await plan_service.generate_plan("planner_b", debate_goal, json.dumps([r.model_dump() for r in spec_output.requirements]), repo_map_json)
-        orchestrator.save_run_artifact("plan_b.json", plan_b.model_dump())
-        await orchestrator.transition_to(ProjectPhase.PLANS_GENERATED)
-
-        # 5. Cross-Critique
-        progress.add_task(description="Critiquing Plan B...", total=None)
-        critique_a = await critique_service.generate_critique("critic_a", plan_b.model_dump_json(), json.dumps([r.model_dump() for r in spec_output.requirements]))
-        orchestrator.save_run_artifact("critique_a.json", critique_a.model_dump())
-        
-        progress.add_task(description="Critiquing Plan A...", total=None)
-        critique_b = await critique_service.generate_critique("critic_b", plan_a.model_dump_json(), json.dumps([r.model_dump() for r in spec_output.requirements]))
-        orchestrator.save_run_artifact("critique_b.json", critique_b.model_dump())
-        await orchestrator.transition_to(ProjectPhase.CRITIQUES_GENERATED)
-
-        # 6. Rebuttals
-        progress.add_task(description="Generating rebuttals...", total=None)
-        rebuttal_a = await critique_service.generate_rebuttal("planner_a", plan_a.model_dump_json(), critique_b.model_dump_json())
-        orchestrator.save_run_artifact("rebuttal_a.json", rebuttal_a.model_dump())
-        rebuttal_b = await critique_service.generate_rebuttal("planner_b", plan_b.model_dump_json(), critique_a.model_dump_json())
-        orchestrator.save_run_artifact("rebuttal_b.json", rebuttal_b.model_dump())
-
-        # 7. Arbitration
-        progress.add_task(description="Arbitrating final plan...", total=None)
-        decision = await arbiter_service.arbitrate(
-            debate_goal,
-            json.dumps([r.model_dump() for r in spec_output.requirements]),
-            plan_a.model_dump_json(),
-            plan_b.model_dump_json(),
-            critique_a.model_dump_json(),
-            critique_b.model_dump_json(),
-            rebuttal_a.model_dump_json(),
-            rebuttal_b.model_dump_json()
-        )
-        orchestrator.save_run_artifact("decision.json", decision.model_dump())
-        await orchestrator.transition_to(ProjectPhase.ARBITRATED)
-        reconciled_findings = _reconcile_findings([*critique_a.findings, *critique_b.findings], decision)
-        final_tasks = [task.model_copy(update={"status": "planned"}) for task in decision.final_tasks]
+        requirements_json = json.dumps([r.model_dump() for r in spec_output.requirements])
+
+        if quick:
+            # Rigor dial: single pragmatic plan, no A/B debate, critique, rebuttal,
+            # or arbitration. Spec requirements (with their acceptance criteria)
+            # become the final requirements verbatim. This trades the council's
+            # 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.
+            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
+            )
+            orchestrator.save_run_artifact("plan_a.json", plan_a.model_dump())
+            await orchestrator.transition_to(ProjectPhase.PLANS_GENERATED)
+
+            decision = ArbiterDecision(
+                accepted_finding_ids=[],
+                rejected_finding_ids=[],
+                final_requirements=spec_output.requirements,
+                final_tasks=plan_a.tasks,
+            )
+            orchestrator.save_run_artifact("decision.json", decision.model_dump())
+            # Walk through CRITIQUES_GENERATED (the only path to ARBITRATED) without
+            # actually critiquing, so the rest of the lifecycle (approval, gates,
+            # status, the report's phase) is identical to the full council flow.
+            await orchestrator.transition_to(ProjectPhase.CRITIQUES_GENERATED)
+            await orchestrator.transition_to(ProjectPhase.ARBITRATED)
+            reconciled_findings = []
+            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)
+            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),
+                plan_service.generate_plan("planner_b", debate_goal, requirements_json, repo_map_json),
+            )
+            orchestrator.save_run_artifact("plan_a.json", plan_a.model_dump())
+            orchestrator.save_run_artifact("plan_b.json", plan_b.model_dump())
+            await orchestrator.transition_to(ProjectPhase.PLANS_GENERATED)
+
+            # 5. Cross-Critique (independent — run concurrently)
+            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.model_dump_json(), requirements_json),
+                critique_service.generate_critique("critic_b", plan_a.model_dump_json(), requirements_json),
+            )
+            orchestrator.save_run_artifact("critique_a.json", critique_a.model_dump())
+            orchestrator.save_run_artifact("critique_b.json", critique_b.model_dump())
+            await orchestrator.transition_to(ProjectPhase.CRITIQUES_GENERATED)
+
+            # 6. Rebuttals (independent — run concurrently)
+            progress.add_task(description="Generating rebuttals...", total=None)
+            rebuttal_a, rebuttal_b = await asyncio.gather(
+                critique_service.generate_rebuttal("planner_a", plan_a.model_dump_json(), critique_b.model_dump_json()),
+                critique_service.generate_rebuttal("planner_b", plan_b.model_dump_json(), critique_a.model_dump_json()),
+            )
+            orchestrator.save_run_artifact("rebuttal_a.json", rebuttal_a.model_dump())
+            orchestrator.save_run_artifact("rebuttal_b.json", rebuttal_b.model_dump())
+
+            # 7. Arbitration
+            progress.add_task(description="Arbitrating final plan...", total=None)
+            decision = await arbiter_service.arbitrate(
+                debate_goal,
+                json.dumps([r.model_dump() for r in spec_output.requirements]),
+                plan_a.model_dump_json(),
+                plan_b.model_dump_json(),
+                critique_a.model_dump_json(),
+                critique_b.model_dump_json(),
+                rebuttal_a.model_dump_json(),
+                rebuttal_b.model_dump_json()
+            )
+            orchestrator.save_run_artifact("decision.json", decision.model_dump())
+            await orchestrator.transition_to(ProjectPhase.ARBITRATED)
+            reconciled_findings = _reconcile_findings([*critique_a.findings, *critique_b.findings], decision)
+            final_tasks = [task.model_copy(update={"status": "planned"}) for task in decision.final_tasks]
 
     console.print("[green]Planning complete![/green]")
     console.print(f"[blue]Prompt enhancement:[/blue] .devcouncil/runs/{run_id}/prompt_enhancement.json")
@@ -308,11 +356,103 @@ async def run_plan_flow(
         await orchestrator.transition_to(ProjectPhase.AWAITING_USER_DECISIONS)
         return []
 
+def _latest_run_with_decision(root: Path, run_id: str | None) -> Path | None:
+    runs_dir = root / ".devcouncil" / "runs"
+    if run_id:
+        candidate = runs_dir / run_id
+        return candidate if (candidate / "decision.json").exists() else None
+    if not runs_dir.exists():
+        return None
+    candidates = [d for d in runs_dir.iterdir() if (d / "decision.json").exists()]
+    if not candidates:
+        return None
+    return max(candidates, key=lambda d: (d / "decision.json").stat().st_mtime)
+
+
+def approve(
+    run_id: str | None = typer.Option(None, "--run-id", help="Run whose generated plan to approve (defaults to the most recent run with a decision)."),
+    force: bool = typer.Option(False, "--force", help="Approve even if blocking gate gaps remain."),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
+):
+    """
+    Approve a generated plan after reviewing gate gaps (AWAITING_USER_DECISIONS -> PLAN_APPROVED).
+    """
+    from devcouncil.planning.arbiter_service import ArbiterDecision
+    from devcouncil.planning.critique_service import CritiqueOutput
+    from devcouncil.planning.spec_service import SpecOutput
+
+    root = project_root.expanduser().resolve()
+    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 []
+
+    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)
+
+    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.")
+
+
 @app.command()
 def plan(
     goal: str = typer.Argument(..., help="The goal of the implementation"),
     requirements_only: bool = typer.Option(False, "--requirements-only", help="Only generate requirements"),
     dry_run: bool = typer.Option(False, "--dry-run", help="Simulate planning without LLM calls"),
+    quick: bool = typer.Option(
+        False,
+        "--quick",
+        help="Rigor dial: skip the A/B debate, critique, rebuttal, and arbitration. "
+        "One spec + one plan (~5 fewer model calls). Verification still gates every diff.",
+    ),
     persist: bool = typer.Option(
         False,
         "--persist/--no-persist",
@@ -324,4 +464,25 @@ def plan(
     Run the full planning cycle (Repo map -> Spec -> Plan A/B -> Critique -> Arbiter).
     """
     should_persist = persist or not dry_run
-    asyncio.run(run_plan_flow(goal, requirements_only, dry_run, should_persist, project_root))
+    try:
+        asyncio.run(run_plan_flow(goal, requirements_only, dry_run, should_persist, project_root, quick=quick))
+    except (ProviderRequestError, StructuredOutputError) as exc:
+        print_planning_error(exc)
+        raise typer.Exit(code=1)
+
+
+def print_planning_error(exc: Exception) -> None:
+    """Render a planning/model failure as an actionable message instead of a traceback."""
+    console.print(f"\n[red]Planning could not complete:[/red] {exc}")
+    if isinstance(exc, StructuredOutputError):
+        console.print(
+            "[yellow]Tip:[/yellow] this role's model could not return valid structured JSON. "
+            "Free/very small models often can't. Set a more capable model, e.g.\n"
+            f"  [bold]dev config models --role {exc.role} --model anthropic/claude-sonnet-4.6[/bold]\n"
+            "  (or set all roles: [bold]dev config models --model <model>[/bold])"
+        )
+    elif isinstance(exc, ProviderRequestError) and exc.status_code == 402:
+        console.print(
+            "[yellow]Tip:[/yellow] add credits at https://openrouter.ai/settings/credits, "
+            "or switch to a free/cheaper model with [bold]dev config models --model <model>[/bold]."
+        )

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

@@ -1,3 +1,5 @@
+import json
+from typing import NoReturn
 import typer
 from rich.console import Console
 from rich.markdown import Markdown
@@ -16,6 +18,7 @@ def prompt(
     ctx: typer.Context,
     task_id: str = typer.Argument(..., help="ID of the task to generate a prompt for"),
     pretty: bool = typer.Option(False, "--pretty", help="Render the prompt for terminal reading."),
+    json_format: bool = typer.Option(False, "--json", help="Output machine-readable JSON: {ok, task_id, prompt}."),
     project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
 ):
     """
@@ -24,27 +27,35 @@ def prompt(
     if ctx.invoked_subcommand is not None:
         return
 
+    def _fail(message: str) -> NoReturn:
+        if json_format:
+            typer.echo(json.dumps({"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()
     initialize_project(root, quiet=True)
     db = get_db(root)
     if not db:
-        raise typer.Exit(code=1)
+        _fail("DevCouncil state is unavailable in this directory.")
 
     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:
-            console.print(f"[red]Task {task_id} not found.[/red]")
-            raise typer.Exit(code=1)
-        
+            _fail(f"Task {task_id} not found.")
+
         reqs = req_repo.get_all()
-        
+
         builder = PromptBuilder(root)
         task_prompt = builder.build_task_prompt(task, reqs)
 
-        if pretty:
+        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"))

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

@@ -14,9 +14,10 @@ from pathlib import Path
 app = typer.Typer()
 console = Console()
 
-async def run_repair_flow():
-    initialize_project(Path("."), quiet=True)
-    db = get_db()
+async def run_repair_flow(project_root: Path = Path(".")):
+    root = project_root.expanduser().resolve()
+    initialize_project(root, quiet=True)
+    db = get_db(root)
     if not db:
         console.print("[red]DevCouncil state is unavailable in this directory.[/red]")
         return
@@ -34,39 +35,55 @@ async def run_repair_flow():
 
         console.print(f"Found [bold]{len(blocking_gaps)}[/bold] blocking gaps. Orchestrating repair plan...")
 
-        # Load router
+        # Load router when credentials are available. Correction manifests have a
+        # deterministic fallback path, so missing model credentials must not block
+        # repair artifact generation.
+        repair_service = None
         try:
-            config = load_config(Path("."))
+            config = load_config(root)
             validate_model_provider(config.models.provider)
-            api_key = get_api_key(config.models.provider, Path("."))
+            api_key = get_api_key(config.models.provider, root)
         except (FileNotFoundError, ValueError) as e:
-            console.print(f"[red]{e}[/red]")
-            return
-        
-        provider = create_provider(config.models.provider, api_key)
-        role_config = {name: role.model_dump() for name, role in config.models.roles.items()}
-        router = ModelRouter(provider, role_config)
-        repair_service = RepairService(router)
-        context_builder = ContextBuilder(Path("."))
+            console.print(f"[yellow]{e}[/yellow]")
+        else:
+            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, project_root=root)
+            repair_service = RepairService(router)
+        context_builder = ContextBuilder(root)
         
         # Build minimal context for repair.
         project_context = context_builder.get_structure_summary()
 
-        repair_output = await repair_service.generate_repair_plan(blocking_gaps, str(project_context))
-        
-        for task in repair_output.suggested_tasks:
-            task.id = f"REPAIR-{task.id}"
-            task_repo.save(task)
-            console.print(f"  - Created intelligent repair task [bold]{task.id}[/bold]: {task.title}")
+        from devcouncil.planning.correction_manifest import write_correction_manifest
+
+        task_ids = {gap.task_id for gap in blocking_gaps if gap.task_id}
+        for scoped_task_id in task_ids:
+            if scoped_task_id:
+                path = write_correction_manifest(root, scoped_task_id, repair_service=repair_service)
+                if path:
+                    console.print(f"  - Wrote correction manifest [dim]{path}[/dim]")
+
+        repair_count = 0
+        if repair_service is not None:
+            repair_output = await repair_service.generate_repair_plan(blocking_gaps, str(project_context))
+            for task in repair_output.suggested_tasks:
+                task.id = f"REPAIR-{task.id}"
+                task_repo.save(task)
+                repair_count += 1
+                console.print(f"  - Created intelligent repair task [bold]{task.id}[/bold]: {task.title}")
 
-        console.print(f"\n[green]Successfully generated {len(repair_output.suggested_tasks)} repair tasks.[/green]")
+        console.print(f"\n[green]Successfully generated {repair_count} repair tasks.[/green]")
 
 @app.callback(invoke_without_command=True)
-def repair(ctx: typer.Context):
+def repair(
+    ctx: typer.Context,
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
+):
     """
     Convert blocking gaps into intelligent repair tasks using LLM inference.
     """
     if ctx.invoked_subcommand is not None:
         return
 
-    asyncio.run(run_repair_flow())
+    asyncio.run(run_repair_flow(project_root))

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

@@ -78,6 +78,11 @@ def report(
     github: bool = typer.Option(False, "--github", help="Post report to GitHub PR Checks"),
     github_pr_comment: bool = typer.Option(False, "--github-pr-comment", help="Post report as a GitHub PR comment"),
     gitlab_pr_comment: bool = typer.Option(False, "--gitlab-pr-comment", help="Post report as a GitLab merge request comment"),
+    fail_on_blocking: bool = typer.Option(
+        False,
+        "--fail-on-blocking",
+        help="Exit non-zero when blocking gaps remain, so shell-driven agents can gate on $?.",
+    ),
     project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
 ):
     """
@@ -127,3 +132,6 @@ def report(
         else:
             output = ReportBuilder.build_markdown(graph, live_review=live_review)
             console.print(Markdown(output))
+
+        if fail_on_blocking and graph.blocking_gaps():
+            raise typer.Exit(code=1)

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

@@ -12,14 +12,16 @@ console = Console()
 
 def reset_demo_state(
     yes: bool = typer.Option(False, "--yes", help="Confirm clearing planning/demo artifacts."),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
 ):
     """Clear demo planning artifacts from the local DevCouncil state database."""
     if not yes:
         console.print("[red]Refusing to clear state without --yes.[/red]")
         raise typer.Exit(code=1)
 
-    initialize_project(Path("."), quiet=True)
-    db = get_db()
+    root = project_root.expanduser().resolve()
+    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)