devcouncil 0.3.1 → 0.4.1

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

@@ -0,0 +1,79 @@
+"""`dev provenance` and `dev resource` — audit trail and MCP corpus reads."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+import typer
+
+from devcouncil.reporting.mcp_resources import list_mcp_resource_uris, read_mcp_resource
+from devcouncil.reporting.task_provenance import task_provenance_payload
+from devcouncil.telemetry.logging_setup import set_log_dir
+from devcouncil.telemetry.stages import log_stage, log_step
+from devcouncil.utils.json_persist import dump_json
+
+resource_app = typer.Typer(help="Read MCP corpus resources through the CLI service layer.")
+logger = logging.getLogger(__name__)
+
+
+def provenance(
+    task_id: str = typer.Argument(..., help="Task ID to inspect."),
+    json_format: bool = typer.Option(False, "--json", help="Output machine-readable JSON."),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
+) -> None:
+    """Show file changes, verification runs, and diff-coverage evidence for a task."""
+    root = project_root.expanduser().resolve()
+    set_log_dir(root)
+    logger.info("dev provenance: task=%s json=%s", task_id, json_format)
+
+    with log_stage("provenance", project_root=root, task_id=task_id):
+        payload = task_provenance_payload(root, task_id)
+        if json_format:
+            typer.echo(dump_json(payload, indent=2))
+            log_step("provenance/complete", project_root=root, task_id=task_id, trace=True)
+            if not payload.get("ok", True):
+                raise typer.Exit(code=1)
+            return
+
+        if not payload.get("ok", True):
+            typer.echo(payload.get("error", "provenance unavailable"))
+            raise typer.Exit(code=1)
+
+        typer.echo(
+            f"Task {task_id}: {len(payload.get('file_changes', []))} file change(s), "
+            f"{len(payload.get('verification_runs', []))} verification run(s), "
+            f"{len(payload.get('diff_coverage', []))} diff-coverage record(s)."
+        )
+        log_step("provenance/complete", project_root=root, task_id=task_id, trace=True)
+
+
+@resource_app.command("list")
+def resource_list(
+    json_format: bool = typer.Option(False, "--json", help="Output machine-readable JSON."),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
+) -> None:
+    """List browsable MCP corpus resource URIs."""
+    root = project_root.expanduser().resolve()
+    set_log_dir(root)
+    resources = list_mcp_resource_uris(root)
+    if json_format:
+        typer.echo(dump_json({"resources": resources}, indent=2))
+        return
+    for item in resources:
+        typer.echo(f"{item['uri']}  ({item['mimeType']})  {item['name']}")
+
+
+@resource_app.command("read")
+def resource_read(
+    uri: str = typer.Argument(..., help="Resource URI, e.g. devcouncil://tasks"),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
+) -> None:
+    """Read one MCP corpus resource (stdout body)."""
+    root = project_root.expanduser().resolve()
+    set_log_dir(root)
+    try:
+        typer.echo(read_mcp_resource(root, uri), nl=False)
+    except ValueError as exc:
+        typer.echo(str(exc))
+        raise typer.Exit(code=1) from exc

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

@@ -8,6 +8,7 @@ from devcouncil.llm.provider import create_provider, validate_model_provider
 from devcouncil.llm.router import ModelRouter
 from devcouncil.app.config import load_config, get_api_key
 from devcouncil.cli.commands.init import initialize_project
+from devcouncil.telemetry.stages import log_stage, log_step
 import asyncio
 import logging
 from pathlib import Path
@@ -26,63 +27,73 @@ async def run_repair_flow(project_root: Path = Path(".")):
         console.print("[red]DevCouncil state is unavailable in this directory.[/red]")
         return
 
-    with db.get_session() as session:
-        gap_repo = GapRepository(session)
-        task_repo = TaskRepository(session)
+    with log_stage("repair", project_root=root):
+        log_step("repair/1: loading blocking gaps", project_root=root)
+        with db.get_session() as session:
+            gap_repo = GapRepository(session)
+            task_repo = TaskRepository(session)
 
-        all_gaps = gap_repo.get_all()
-        blocking_gaps = [g for g in all_gaps if g.blocking]
+            all_gaps = gap_repo.get_all()
+            blocking_gaps = [g for g in all_gaps if g.blocking]
 
-        if not blocking_gaps:
-            logger.info("dev repair: no blocking gaps; nothing to repair")
-            console.print("[green]No blocking gaps found. Nothing to repair![/green]")
-            return
+            if not blocking_gaps:
+                logger.info("dev repair: no blocking gaps; nothing to repair")
+                console.print("[green]No blocking gaps found. Nothing to repair![/green]")
+                return
 
-        logger.info("dev repair: %d blocking gap(s) across %d task(s)", len(blocking_gaps), len({g.task_id for g in blocking_gaps if g.task_id}))
-        console.print(f"Found [bold]{len(blocking_gaps)}[/bold] blocking gaps. Orchestrating repair plan...")
+            logger.info("dev repair: %d blocking gap(s) across %d task(s)", len(blocking_gaps), len({g.task_id for g in blocking_gaps if g.task_id}))
+            console.print(f"Found [bold]{len(blocking_gaps)}[/bold] blocking gaps. Orchestrating repair plan...")
 
-        # 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
-        config = None
-        try:
-            config = load_config(root)
-            validate_model_provider(config.models.provider)
-            api_key = get_api_key(config.models.provider, root)
-        except (FileNotFoundError, ValueError) as e:
-            logger.warning("dev repair: no LLM provider (%s); using deterministic manifest fallback", e)
-            console.print(f"[yellow]{e}[/yellow]")
-        else:
-            provider = create_provider(config.models.provider, api_key, project_root=root, provider_prefs=config.provider)
-            role_config = {name: role.model_dump() for name, role in config.models.roles.items()}
-            router = ModelRouter(provider, role_config, project_root=root)
-            repair_service = RepairService(router)
-        context_builder = ContextBuilder(root)
-        
-        # Build minimal context for repair.
-        project_context = context_builder.get_structure_summary()
+            # 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
+            config = None
+            try:
+                config = load_config(root)
+                validate_model_provider(config.models.provider)
+                api_key = get_api_key(config.models.provider, root)
+            except (FileNotFoundError, ValueError) as e:
+                logger.warning("dev repair: no LLM provider (%s); using deterministic manifest fallback", e)
+                console.print(f"[yellow]{e}[/yellow]")
+            else:
+                provider = create_provider(config.models.provider, api_key, project_root=root, provider_prefs=config.provider)
+                role_config = {name: role.model_dump() for name, role in config.models.roles.items()}
+                router = ModelRouter(provider, role_config, project_root=root)
+                repair_service = RepairService(router)
+            context_builder = ContextBuilder(root)
 
-        from devcouncil.planning.correction_manifest import write_correction_manifest
+            # Build minimal context for repair.
+            project_context = context_builder.get_structure_summary()
 
-        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, config=config)
-                if path:
-                    console.print(f"  - Wrote correction manifest [dim]{path}[/dim]")
+            from devcouncil.planning.correction_manifest import write_correction_manifest
 
-        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}")
+            task_ids = {gap.task_id for gap in blocking_gaps if gap.task_id}
+            log_step("repair/2: writing correction manifests", project_root=root, task_count=len(task_ids))
+            for scoped_task_id in task_ids:
+                if scoped_task_id:
+                    path = write_correction_manifest(root, scoped_task_id, repair_service=repair_service, config=config)
+                    if path:
+                        console.print(f"  - Wrote correction manifest [dim]{path}[/dim]")
 
-        logger.info("dev repair complete: generated %d repair task(s)", repair_count)
-        console.print(f"\n[green]Successfully generated {repair_count} repair tasks.[/green]")
+            repair_count = 0
+            if repair_service is not None:
+                log_step("repair/3: generating LLM repair plan", project_root=root)
+                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}")
+
+            log_step(
+                "repair/complete",
+                project_root=root,
+                repair_tasks=repair_count,
+                trace=True,
+            )
+            logger.info("dev repair complete: generated %d repair task(s)", repair_count)
+            console.print(f"\n[green]Successfully generated {repair_count} repair tasks.[/green]")
 
 @app.callback(invoke_without_command=True)
 def repair(

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

@@ -1,3 +1,6 @@
+from devcouncil.utils.json_persist import dump_json
+from dataclasses import asdict
+
 import typer
 from rich.console import Console
 from rich.markdown import Markdown
@@ -8,15 +11,18 @@ from devcouncil.integrations.github import GitHubIntegration
 from devcouncil.integrations.pr_comments import GitHubPRCommenter, GitLabMRCommenter, build_pr_comment_body
 from devcouncil.artifacts.graph import ArtifactGraph
 from devcouncil.telemetry.traces import TraceLogger
+from devcouncil.telemetry.stages import log_stage, log_step
 from devcouncil.cli.commands.init import initialize_project
 from devcouncil.live.summary import live_review_summary
 import asyncio
+import logging
 import os
-import subprocess
 from pathlib import Path
+from typing import Optional
 
 app = typer.Typer()
 console = Console()
+logger = logging.getLogger(__name__)
 
 async def run_github_report(graph: ArtifactGraph, project_root: Path):
     token = os.environ.get("GITHUB_TOKEN")
@@ -27,8 +33,11 @@ async def run_github_report(graph: ArtifactGraph, project_root: Path):
         return
 
     try:
-        # Detect current SHA
-        sha = subprocess.check_output(["git", "rev-parse", "HEAD"], cwd=project_root).decode().strip()
+        sha = os.environ.get("GITHUB_SHA", "").strip()
+        if not sha:
+            from devcouncil.utils.proc import git_output
+
+            sha = git_output(["rev-parse", "HEAD"], cwd=project_root).strip()
         integration = GitHubIntegration(token, repo, sha)
         await integration.report_verification(graph)
         console.print(f"[green]Successfully reported to GitHub PR Checks for {repo} at {sha[:7]}[/green]")
@@ -78,6 +87,17 @@ 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"),
+    evidence_json: Optional[Path] = typer.Option(
+        None,
+        "--evidence-json",
+        help="Write the requirement→task→diff→evidence graph as reviewer-readable JSON to this path "
+        "(e.g. for a CI/PR artifact).",
+    ),
+    evidence_html: Optional[Path] = typer.Option(
+        None,
+        "--evidence-html",
+        help="Write a self-contained HTML evidence report (AC table + task/diff links) to this path.",
+    ),
     fail_on_blocking: bool = typer.Option(
         False,
         "--fail-on-blocking",
@@ -91,47 +111,135 @@ def report(
     if ctx.invoked_subcommand is not None:
         return
 
+    # Direct Python calls (e.g. from `dev go`) bypass Typer, leaving OptionInfo
+    # defaults in place of real values. Normalize them so `is not None` and
+    # truthiness checks behave as they do under CLI invocation.
+    if not isinstance(evidence_json, (Path, type(None))):
+        evidence_json = None
+    if not isinstance(evidence_html, (Path, type(None))):
+        evidence_html = None
+    if not isinstance(fail_on_blocking, bool):
+        fail_on_blocking = False
+
     root = project_root.expanduser().resolve()
+    from devcouncil.telemetry.logging_setup import set_log_dir
+    set_log_dir(root)
+    logger.info("dev report: json=%s planning_only=%s", json_format, planning_only)
     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 db.get_session() as session:
-        graph_repo = ArtifactGraphRepository(session)
-        graph = graph_repo.load_graph()
-        live_review = live_review_summary(root)
-        TraceLogger(root).log_event(
-            "report_generated",
-            {
-                "json": json_format,
-                "github": github,
-                "github_pr_comment": github_pr_comment,
-                "gitlab_pr_comment": gitlab_pr_comment,
-                "planning_only": planning_only,
-            },
-            summary="Generated DevCouncil report",
-        )
-        
-        if github:
-            asyncio.run(run_github_report(graph, root))
-            return
-
-        if github_pr_comment:
-            asyncio.run(run_github_pr_comment(graph, live_review=live_review))
-            return
-
-        if gitlab_pr_comment:
-            asyncio.run(run_gitlab_mr_comment(graph, live_review=live_review))
-            return
-
-        if json_format:
-            output = ReportBuilder.build_json(graph, live_review=live_review)
-            typer.echo(output)
-        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)
+    with log_stage("report", project_root=root, planning_only=planning_only):
+        log_step("report/1: loading artifact graph", project_root=root)
+        with db.get_session() as session:
+            graph_repo = ArtifactGraphRepository(session)
+            graph = graph_repo.load_graph()
+            live_review = live_review_summary(root)
+            TraceLogger(root).log_event(
+                "report_generated",
+                {
+                    "json": json_format,
+                    "github": github,
+                    "github_pr_comment": github_pr_comment,
+                    "gitlab_pr_comment": gitlab_pr_comment,
+                    "evidence_json": evidence_json is not None,
+                    "evidence_html": evidence_html is not None,
+                    "planning_only": planning_only,
+                },
+                summary="Generated DevCouncil report",
+            )
+
+            if github:
+                log_step("report/2: posting to GitHub checks", project_root=root)
+                asyncio.run(run_github_report(graph, root))
+                if fail_on_blocking and graph.blocking_gaps():
+                    raise typer.Exit(code=1)
+                return
+
+            if github_pr_comment:
+                log_step("report/2: posting GitHub PR comment", project_root=root)
+                asyncio.run(run_github_pr_comment(graph, live_review=live_review))
+                if fail_on_blocking and graph.blocking_gaps():
+                    raise typer.Exit(code=1)
+                return
+
+            if gitlab_pr_comment:
+                log_step("report/2: posting GitLab MR comment", project_root=root)
+                asyncio.run(run_gitlab_mr_comment(graph, live_review=live_review))
+                if fail_on_blocking and graph.blocking_gaps():
+                    raise typer.Exit(code=1)
+                return
+
+            if evidence_json is not None:
+                log_step("report/2: writing evidence-export JSON", project_root=root)
+                output_path = evidence_json.expanduser()
+                try:
+                    output_path.parent.mkdir(parents=True, exist_ok=True)
+                    output_path.write_text(
+                        ReportBuilder.build_evidence_export(graph, live_review=live_review) + "\n",
+                        encoding="utf-8",
+                    )
+                except OSError as exc:
+                    console.print(f"[red]Failed to write evidence export to {output_path}: {exc}[/red]")
+                    raise typer.Exit(code=1) from exc
+                console.print(f"[green]Wrote evidence export to {output_path}[/green]")
+                if fail_on_blocking and graph.blocking_gaps():
+                    raise typer.Exit(code=1)
+                return
+
+            if evidence_html is not None:
+                log_step("report/2: writing evidence-export HTML", project_root=root)
+                output_path = evidence_html.expanduser()
+                try:
+                    output_path.parent.mkdir(parents=True, exist_ok=True)
+                    output_path.write_text(
+                        ReportBuilder.build_evidence_html(graph, live_review=live_review) + "\n",
+                        encoding="utf-8",
+                    )
+                except OSError as exc:
+                    console.print(f"[red]Failed to write evidence HTML to {output_path}: {exc}[/red]")
+                    raise typer.Exit(code=1) from exc
+                console.print(f"[green]Wrote evidence HTML to {output_path}[/green]")
+                if fail_on_blocking and graph.blocking_gaps():
+                    raise typer.Exit(code=1)
+                return
+
+            log_step(
+                "report/2: rendering output",
+                project_root=root,
+                json_format=json_format,
+                trace=True,
+            )
+            if json_format:
+                output = ReportBuilder.build_json(graph, live_review=live_review)
+                typer.echo(output)
+            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)
+
+
+@app.command("rigor")
+def rigor_report(
+    json_format: bool = typer.Option(False, "--json", help="Output machine-readable JSON."),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
+):
+    """Aggregate rigor-gap patterns across persisted verification runs.
+
+    Surfaces recurring stub/effort failures and repair-loop stats so teams can
+    tune ``verification.rigor`` thresholds from evidence rather than guesses.
+    """
+    from devcouncil.verification.rigor_analytics import build_rigor_report
+
+    root = project_root.expanduser().resolve()
+    initialize_project(root, quiet=True)
+    report = build_rigor_report(root)
+
+    if json_format:
+        typer.echo(dump_json(asdict(report), indent=2))
+    else:
+        console.print(Markdown(report.to_markdown()))

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

@@ -0,0 +1,104 @@
+from devcouncil.utils.json_persist import dump_json
+import logging
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from devcouncil.cli.commands.init import initialize_project
+from devcouncil.domain.task import Task
+from devcouncil.storage.db import get_db
+from devcouncil.storage.repositories import RequirementRepository, TaskRepository
+from devcouncil.telemetry.stages import log_stage, log_step
+
+console = Console()
+logger = logging.getLogger(__name__)
+
+
+def _derive_requirement_status(req_id: str, tasks: list[Task]) -> str:
+    linked = [task for task in tasks if req_id in task.requirement_ids]
+    if not linked:
+        return "unmapped"
+    statuses = {task.status for task in linked}
+    if "blocked" in statuses:
+        return "blocked"
+    if statuses <= {"verified", "done"}:
+        return "verified"
+    if "running" in statuses:
+        return "in_progress"
+    return "planned"
+
+
+def _requirements_payload(project_root: Path) -> dict:
+    initialize_project(project_root, quiet=True)
+    db = get_db(project_root)
+    if not db:
+        return {"initialized": False, "requirements": []}
+
+    with db.get_session() as session:
+        requirements = RequirementRepository(session).get_all()
+        tasks = TaskRepository(session).get_all()
+        rows = []
+        for req in requirements:
+            linked_count = sum(1 for task in tasks if req.id in task.requirement_ids)
+            rows.append(
+                {
+                    "id": req.id,
+                    "title": req.title,
+                    "priority": req.priority,
+                    "status": _derive_requirement_status(req.id, tasks),
+                    "linked_task_count": linked_count,
+                    "requirement": req.model_dump(),
+                }
+            )
+        rows.sort(key=lambda row: (row["priority"], row["id"]))
+        return {
+            "initialized": True,
+            "requirements": rows,
+            "total_count": len(rows),
+        }
+
+
+def requirements(
+    json_format: bool = typer.Option(False, "--json", help="Output machine-readable JSON."),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
+):
+    """List requirements with priority, status, and linked task counts."""
+    root = project_root.expanduser().resolve()
+    from devcouncil.telemetry.logging_setup import set_log_dir
+
+    set_log_dir(root)
+    logger.info("dev requirements: json=%s", json_format)
+
+    with log_stage("requirements", project_root=root):
+        log_step("requirements/1: loading requirements", project_root=root, trace=True)
+        payload = _requirements_payload(root)
+
+        if json_format:
+            typer.echo(dump_json(payload, indent=2))
+            log_step("requirements/complete", project_root=root, trace=True)
+            return
+
+        if not payload["initialized"]:
+            console.print("[yellow]DevCouncil state is not available in this directory.[/yellow]")
+            log_step("requirements/complete", project_root=root, trace=True)
+            return
+
+        table = Table(title="DevCouncil Requirements")
+        table.add_column("ID", style="cyan", no_wrap=True)
+        table.add_column("Priority")
+        table.add_column("Status", style="magenta")
+        table.add_column("Linked Tasks", justify="right")
+
+        for row in payload["requirements"]:
+            table.add_row(
+                row["id"],
+                row["priority"],
+                row["status"],
+                str(row["linked_task_count"]),
+            )
+
+        console.print(table)
+        console.print(f"\n[bold]{payload['total_count']}[/bold] requirement(s)")
+        log_step("requirements/complete", project_root=root, trace=True)

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

@@ -1,3 +1,4 @@
+import logging
 import typer
 from rich.console import Console
 from sqlmodel import delete
@@ -6,8 +7,10 @@ from pathlib import Path
 from devcouncil.storage.db import get_db
 from devcouncil.storage.models import EvidenceModel, GapModel, RequirementModel, TaskModel
 from devcouncil.cli.commands.init import initialize_project
+from devcouncil.telemetry.stages import log_stage, log_step
 
 console = Console()
+logger = logging.getLogger(__name__)
 
 
 def reset_demo_state(
@@ -20,14 +23,20 @@ def reset_demo_state(
         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 reset-demo-state")
     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 db.get_session() as session:
-        for model in (EvidenceModel, GapModel, TaskModel, RequirementModel):
-            session.exec(delete(model))
+    with log_stage("reset_demo_state", project_root=root):
+        log_step("reset_demo_state/1: clearing planning artifacts", project_root=root, trace=True)
+        with db.get_session() as session:
+            for model in (EvidenceModel, GapModel, TaskModel, RequirementModel):
+                session.exec(delete(model))
 
-    console.print("[green]Cleared requirements, tasks, gaps, and evidence from local state.[/green]")
+        console.print("[green]Cleared requirements, tasks, gaps, and evidence from local state.[/green]")
+        log_step("reset_demo_state/complete", project_root=root, trace=True)