devcouncil 0.3.1 → 0.4.0

package/src/devcouncil/reporting/markdown_report.py

@@ -1,3 +1,7 @@
+from devcouncil.artifacts.coverage import (
+    acceptance_criteria_evidence_matrix,
+    requirement_task_matrix,
+)
 from devcouncil.artifacts.graph import ArtifactGraph
 
 class MarkdownReportGenerator:
@@ -6,7 +10,11 @@ class MarkdownReportGenerator:
     MAX_INLINE_GAPS = 25
     
     @staticmethod
-    def generate(graph: ArtifactGraph, live_review: dict | None = None) -> str:
+    def generate(
+        graph: ArtifactGraph,
+        live_review: dict | None = None,
+        wiki_refresh: dict | None = None,
+    ) -> str:
         summary = graph.coverage_summary()
         live_blockers = (live_review or {}).get("blocking_cards", [])
 
@@ -56,15 +64,27 @@ class MarkdownReportGenerator:
         md_output += "\n"
 
         md_output += "## Requirements Coverage Table\n"
-        md_output += "| Requirement | Task Mapping | Status |\n"
+        md_output += "| Requirement | Task | Task status |\n"
         md_output += "|---|---|---|\n"
-        
-        for req in graph.requirements.values():
-            linked_tasks = [t for t in graph.tasks.values() if req.id in t.requirement_ids]
-            task_str = ", ".join([t.id for t in linked_tasks]) if linked_tasks else "*None*"
-            status_str = "Covered" if linked_tasks else "**Unmapped**"
-            md_output += f"| {req.id} {req.title} | {task_str} | {status_str} |\n"
-                    
+        for row in requirement_task_matrix(graph):
+            title = row.get("title") or ""
+            task = row.get("task") or "(none)"
+            status = row.get("task_status") or ""
+            if task == "(none)":
+                task = "*None*"
+                status = "**Unmapped**"
+            md_output += f"| {row['requirement']} {title} | {task} | {status} |\n"
+
+        ac_rows = acceptance_criteria_evidence_matrix(graph)
+        if ac_rows:
+            md_output += "\n## Acceptance Criteria Evidence\n"
+            md_output += "| Requirement | AC | Status |\n"
+            md_output += "|---|---|---|\n"
+            for row in ac_rows:
+                md_output += (
+                    f"| {row['requirement_id']} | {row['ac_id']} | {row['status']} |\n"
+                )
+
         md_output += "\n## Blocking Gaps\n"
         blocking_gaps = graph.blocking_gaps()
         if not blocking_gaps:
@@ -92,5 +112,14 @@ class MarkdownReportGenerator:
                     if card.get("task_id"):
                         md_output += f" (`{card['task_id']}`)"
                     md_output += f": {card['summary']}\n"
+
+        if wiki_refresh is not None and wiki_refresh.get("considered"):
+            md_output += "\n## Wiki Refresh\n"
+            md_output += f"- **Reason**: {wiki_refresh.get('reason', '')}\n"
+            stale = wiki_refresh.get("stale_pages") or []
+            if stale:
+                md_output += f"- **Stale pages**: {len(stale)}\n"
+                for page in stale[:10]:
+                    md_output += f"  - {page}\n"
                 
         return md_output

package/src/devcouncil/reporting/mcp_resources.py

@@ -0,0 +1,142 @@
+"""MCP corpus resource read/list helpers shared by CLI and MCP server."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from devcouncil.cli.commands.init import initialize_project
+from devcouncil.knowledge.resource_discovery import (
+    discover_knowledge_sources,
+    knowledge_source_uri,
+)
+from devcouncil.live.summary import live_review_summary
+from devcouncil.reporting.report_builder import ReportBuilder
+from devcouncil.storage.db import get_db
+from devcouncil.storage.repositories import ArtifactGraphRepository, GapRepository, TaskRepository
+from devcouncil.utils.json_persist import dump_json
+
+
+def read_mcp_resource(project_root: Path, uri: str) -> str:
+    """Return the body for one ``devcouncil://`` resource URI."""
+    initialize_project(project_root, quiet=True)
+    db = get_db(project_root)
+    key = uri.rstrip("/")
+
+    if key == "devcouncil://report":
+        if not db:
+            return "DevCouncil is not initialized in this directory."
+        with db.get_session() as session:
+            graph = ArtifactGraphRepository(session).load_graph()
+        return ReportBuilder.build_markdown(graph, live_review=live_review_summary(project_root))
+
+    if key == "devcouncil://tasks":
+        if not db:
+            return dump_json({"tasks": []}, indent=2)
+        with db.get_session() as session:
+            tasks = [t.model_dump() for t in TaskRepository(session).get_all()]
+        return dump_json({"tasks": tasks}, indent=2)
+
+    if key == "devcouncil://gaps":
+        if not db:
+            return dump_json({"gaps": []}, indent=2)
+        with db.get_session() as session:
+            gaps = [g.model_dump() for g in GapRepository(session).get_all()]
+        return dump_json({"gaps": gaps}, indent=2)
+
+    if key == "devcouncil://cards":
+        return dump_json(live_review_summary(project_root), indent=2)
+
+    if key.startswith("devcouncil://task/"):
+        task_id = key.rsplit("/", 1)[-1]
+        if not db:
+            return dump_json({"ok": False, "error": "not initialized"}, indent=2)
+        with db.get_session() as session:
+            task = TaskRepository(session).get_by_id(task_id)
+            if not task:
+                return dump_json({"ok": False, "error": f"Task {task_id} not found."}, indent=2)
+            gaps = [g.model_dump() for g in GapRepository(session).get_for_task(task_id)]
+        return dump_json({"task": task.model_dump(), "gaps": gaps}, indent=2)
+
+    if key == "devcouncil://knowledge":
+        sources = discover_knowledge_sources(project_root)
+        if not sources:
+            return "# Project knowledge\n\nNo OKF or design knowledge has been ingested for this project."
+        lines = ["# Project knowledge", "", "Ingested OKF and design knowledge for this project.", ""]
+        for kind in ("design", "okf"):
+            kind_sources = [s for s in sources if s.kind == kind]
+            if not kind_sources:
+                continue
+            lines.append(f"## {kind.upper() if kind == 'okf' else kind.capitalize()}")
+            lines.append("")
+            for source in kind_sources:
+                link = knowledge_source_uri(source.kind, source.name)
+                desc = source.description or source.name
+                lines.append(f"- [{desc}]({link})")
+            lines.append("")
+        return "\n".join(lines).strip()
+
+    if key.startswith("devcouncil://knowledge/"):
+        for source in discover_knowledge_sources(project_root):
+            if knowledge_source_uri(source.kind, source.name) == key:
+                body = source.render() or source.body
+                return str(body) if body is not None else ""
+        return f"Knowledge source not found: {key}"
+
+    raise ValueError(f"Unknown resource: {uri}")
+
+
+def list_mcp_resource_uris(project_root: Path) -> list[dict[str, str]]:
+    """Stable resource descriptors for MCP ``list_resources`` (without pydantic types)."""
+    initialize_project(project_root, quiet=True)
+    resources: list[dict[str, str]] = [
+        {
+            "uri": "devcouncil://report",
+            "name": "DevCouncil report",
+            "description": "Coverage report, requirement/task mapping, and blocking gaps.",
+            "mimeType": "text/markdown",
+        },
+        {
+            "uri": "devcouncil://tasks",
+            "name": "Tasks",
+            "description": "All planned tasks with scope and status.",
+            "mimeType": "application/json",
+        },
+        {
+            "uri": "devcouncil://gaps",
+            "name": "Gaps",
+            "description": "All open verification gaps.",
+            "mimeType": "application/json",
+        },
+        {
+            "uri": "devcouncil://cards",
+            "name": "Live review",
+            "description": "Live-review summary: cards, signals, and blockers.",
+            "mimeType": "application/json",
+        },
+    ]
+    db = get_db(project_root)
+    if db:
+        with db.get_session() as session:
+            for task in TaskRepository(session).get_all():
+                resources.append({
+                    "uri": f"devcouncil://task/{task.id}",
+                    "name": f"Task {task.id}: {task.title}",
+                    "description": f"Scope, status, and gaps for {task.id}.",
+                    "mimeType": "application/json",
+                })
+    knowledge_sources = discover_knowledge_sources(project_root)
+    if knowledge_sources:
+        resources.append({
+            "uri": "devcouncil://knowledge",
+            "name": "Project knowledge",
+            "description": "Index of ingested OKF and design knowledge for this project.",
+            "mimeType": "text/markdown",
+        })
+        for source in knowledge_sources:
+            resources.append({
+                "uri": knowledge_source_uri(source.kind, source.name),
+                "name": f"Knowledge ({source.kind}): {source.description or source.name}",
+                "description": source.description or source.name,
+                "mimeType": "text/markdown",
+            })
+    return resources

package/src/devcouncil/reporting/report_builder.py

@@ -3,17 +3,53 @@ from pathlib import Path
 from devcouncil.artifacts.graph import ArtifactGraph
 from devcouncil.reporting.markdown_report import MarkdownReportGenerator
 from devcouncil.reporting.json_report import JsonReportGenerator
+from devcouncil.reporting.evidence_export import EvidenceExportGenerator
+from devcouncil.reporting.evidence_html import EvidenceHtmlGenerator
 
 class ReportBuilder:
     """Builds reports in various formats from the artifact graph."""
 
     @staticmethod
-    def build_markdown(graph: ArtifactGraph, live_review: dict | None = None) -> str:
-        return MarkdownReportGenerator.generate(graph, live_review=live_review)
+    def build_markdown(
+        graph: ArtifactGraph,
+        live_review: dict | None = None,
+        wiki_refresh: dict | None = None,
+    ) -> str:
+        return MarkdownReportGenerator.generate(
+            graph, live_review=live_review, wiki_refresh=wiki_refresh
+        )
+
+    @staticmethod
+    def build_json(
+        graph: ArtifactGraph,
+        live_review: dict | None = None,
+        wiki_refresh: dict | None = None,
+    ) -> str:
+        return JsonReportGenerator.generate(
+            graph, live_review=live_review, wiki_refresh=wiki_refresh
+        )
 
     @staticmethod
-    def build_json(graph: ArtifactGraph, live_review: dict | None = None) -> str:
-        return JsonReportGenerator.generate(graph, live_review=live_review)
+    def build_evidence_export(
+        graph: ArtifactGraph,
+        live_review: dict | None = None,
+        wiki_refresh: dict | None = None,
+    ) -> str:
+        """Reviewer-readable requirement→task→diff→evidence JSON (see evidence_export)."""
+        return EvidenceExportGenerator.generate(
+            graph, live_review=live_review, wiki_refresh=wiki_refresh
+        )
+
+    @staticmethod
+    def build_evidence_html(
+        graph: ArtifactGraph,
+        live_review: dict | None = None,
+        wiki_refresh: dict | None = None,
+    ) -> str:
+        """Self-contained HTML evidence report for CI artifact preview (see evidence_html)."""
+        return EvidenceHtmlGenerator.generate(
+            graph, live_review=live_review, wiki_refresh=wiki_refresh
+        )
 
     @staticmethod
     def build_okf_bundle(

package/src/devcouncil/reporting/task_provenance.py

@@ -0,0 +1,42 @@
+"""Task audit-trail payload shared by CLI and MCP."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from devcouncil.cli.commands.init import initialize_project
+from devcouncil.domain.evidence import DiffCoverageEvidence
+from devcouncil.storage.db import get_db
+from devcouncil.storage.native import (
+    CorrectionManifestRepository,
+    FileChangeRepository,
+    VerificationRunRepository,
+)
+from devcouncil.storage.repositories import EvidenceRepository
+
+
+def task_provenance_payload(project_root: Path, task_id: str) -> dict:
+    """Build the provenance audit trail for one task."""
+    initialize_project(project_root, quiet=True)
+    db = get_db(project_root)
+    if not db:
+        return {"ok": False, "error": "DevCouncil state is unavailable in this directory.", "task_id": task_id}
+
+    with db.get_session() as session:
+        file_changes = [r.model_dump() for r in FileChangeRepository(session).list_for_task(task_id)]
+        verification_runs = [r.model_dump() for r in VerificationRunRepository(session).list_for_task(task_id)]
+        coverage = [
+            ev.model_dump()
+            for ev in EvidenceRepository(session).get_all()
+            if isinstance(ev, DiffCoverageEvidence) and ev.task_id == task_id
+        ]
+        correction_manifest = CorrectionManifestRepository(session).latest_for_task(task_id)
+
+    return {
+        "ok": True,
+        "task_id": task_id,
+        "file_changes": file_changes,
+        "verification_runs": verification_runs,
+        "diff_coverage": coverage,
+        "latest_correction_manifest": correction_manifest.model_dump() if correction_manifest else None,
+    }

package/src/devcouncil/reporting/verdict.py

@@ -0,0 +1,75 @@
+"""Shared verdict classification for JSON and evidence exports."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from devcouncil.artifacts.graph import ArtifactGraph
+
+Verdict = Literal["passed", "blocked", "incomplete"]
+IncompleteKind = Literal["quality", "infra"]
+
+_INFRA_GAP_TYPES = frozenset({"invalid_verification_command"})
+_INFRA_DESC_MARKERS = (
+    "sdk is not installed",
+    "not found on path",
+    "session limit",
+    "rate limit",
+    "too many requests",
+    "limit_rpm",
+    "unknown agent profile",
+    "failed to start or execute",
+)
+
+
+def _gaps_from_graph(graph: ArtifactGraph) -> list[Any]:
+    blocking = list(graph.blocking_gaps())
+    all_gaps = getattr(graph, "all_gaps", None)
+    if callable(all_gaps):
+        return list(all_gaps())
+    return blocking
+
+
+def classify_incomplete_kind(
+    graph: ArtifactGraph,
+    *,
+    agent_run: dict[str, Any] | None = None,
+) -> IncompleteKind:
+    """Separate infra incomplete (executor/SDK/session) from quality incomplete."""
+    if agent_run:
+        returncode = agent_run.get("returncode")
+        if returncode not in (None, 0):
+            parts: list[str] = [str(agent_run.get("status") or "")]
+            for key in ("stderr_preview", "stdout_preview"):
+                val = agent_run.get(key)
+                if isinstance(val, list):
+                    parts.extend(str(x) for x in val)
+                elif val:
+                    parts.append(str(val))
+            hay = " ".join(parts).lower()
+            if any(marker in hay for marker in _INFRA_DESC_MARKERS):
+                return "infra"
+
+    for gap in _gaps_from_graph(graph):
+        gap_type = getattr(gap, "gap_type", "") or ""
+        if gap_type in _INFRA_GAP_TYPES:
+            return "infra"
+        desc = (getattr(gap, "description", "") or "").lower()
+        if any(marker in desc for marker in _INFRA_DESC_MARKERS):
+            return "infra"
+    return "quality"
+
+
+def classify_verdict(
+    graph: ArtifactGraph,
+    *,
+    live_blockers: int = 0,
+    agent_run: dict[str, Any] | None = None,
+) -> tuple[Verdict, IncompleteKind | None]:
+    """Return ``(verdict, incomplete_kind)`` where kind is set only for incomplete."""
+    summary = graph.coverage_summary()
+    if summary["blocking_gaps"] > 0 or live_blockers > 0:
+        return "blocked", None
+    if summary["ac_without_evidence"] > 0:
+        return "incomplete", classify_incomplete_kind(graph, agent_run=agent_run)
+    return "passed", None

package/src/devcouncil/skills/library/README.md

@@ -15,6 +15,7 @@ always: false              # true = always selected (only core-engineering uses
 triggers:                  # how this skill is auto-selected (omit for always-on)
   keywords: [foo, bar]     # matched against the goal text (case-insensitive substring)
   globs: ["*.foo", "build.bar"]   # matched against repo file basenames
+  markers: [.devcouncil/config.yaml]  # repo-relative paths that must exist (e.g. DevCouncil init)
 ---
 
 # Body

package/src/devcouncil/skills/library/devcouncil-hero-loop.md

@@ -0,0 +1,109 @@
+---
+name: devcouncil-hero-loop
+title: DevCouncil Hero Loop (Checkout → Verify → Release)
+description: Run DevCouncil's autonomous task loop in Claude Code — checkout a lease, implement inside scope, verify with deterministic gates, self-repair from typed next_actions, then release.
+triggers:
+  keywords: [hero loop, verify loop, checkout task, verify task, release task, next task, dev go, dev e2e, dev repair, task lease]
+  markers: [.devcouncil/config.yaml]
+---
+
+# DevCouncil Hero Loop
+
+DevCouncil's certified end-to-end path for Claude Code: the agent checks out a task,
+implements inside declared scope, verifies deterministically, self-repairs from typed
+next actions, and releases — **without a human pasting test output back and forth.**
+
+## The loop
+
+```
+checkout_task ─▶ (agent implements) ─▶ verify_task ─▶ passed? ─▶ release_task
+      ▲                                     │
+      │                                     ▼ blocking gaps
+      └──────────── self-repair ◀──── next_actions (typed)
+```
+
+## Step-by-step workflow
+
+### 1. Pick up work
+
+```
+devcouncil_next_task          # highest-priority unblocked task (or use a known TASK-ID)
+devcouncil_checkout_task      # acquire lease — required before writes or verify
+devcouncil_get_task           # scope, planned files, acceptance criteria
+devcouncil_get_prompt           # full executor prompt with rigor + context
+```
+
+One agent owns the task at a time. If checkout fails (lease held), do not bypass — pick
+another task or wait for release.
+
+### 2. Implement inside scope
+
+- Read with `devcouncil_read_file`; inspect changes with `devcouncil_get_diff`.
+- **Write only through the gate:** `devcouncil_write_file` / `devcouncil_apply_patch`.
+  Direct editor writes to out-of-scope or protected paths are rejected.
+- Run tests with `devcouncil_run_command` or `devcouncil_record_command`.
+- Preflight questionable paths with `devcouncil_policy_check_write`.
+
+Stay inside the task's **planned files** and **allowed commands**. Do not expand scope
+silently — use `devcouncil_update_task_scope` only when the task genuinely requires it.
+
+When the advisor tool is available, consult it before committing to an approach, when
+stuck on a recurring error, and before declaring the task complete.
+
+### 3. Verify
+
+```
+devcouncil_verify_task        # deterministic verifier — requires active lease
+```
+
+Returns `passed`, `blocking_gaps`, and `next_actions`. A green test suite is not enough;
+the verifier checks planned-file compliance, orphan diffs, acceptance evidence, diff
+coverage, stub detection, and more.
+
+### 4. Self-repair from next_actions
+
+When `passed` is false:
+
+```
+devcouncil_get_next_actions   # cheap read of persisted gaps — no re-verify
+```
+
+Each action is typed (`category`: `fix_code`, `add_test`, `fix_verification`, `scope`,
+`security`, `review`, `plan`) with `file`, `line`, and often `suggested_command`.
+Fix each blocking action, then call `devcouncil_verify_task` again. Repeat until clean.
+
+Do **not** weaken tests, stub around gaps, or skip verification to force a pass.
+
+### 5. Release
+
+```
+devcouncil_release_task       # only after verify passes (or explicit abandon policy)
+```
+
+Report: task ID, what changed, verification result, and any advisory (non-blocking) gaps.
+
+## Alternatives to manual MCP driving
+
+| Entry | When |
+|---|---|
+| `/devcouncil:next` | Interactive Claude Code — shells out then instructs MCP loop |
+| `dev go [TASK-ID]` | CLI-driven loop with repair budget |
+| `dev e2e "<goal>" --executor claude` | Full plan → implement → verify automation |
+| Subagent `devcouncil-implementer` | Delegate the entire loop |
+
+## Lite on-ramp (no task graph yet)
+
+Before full planning, taste the evidence gate on the current diff:
+
+```bash
+dev check --verify --goal "requirement text" --test "python -m pytest tests/ -q"
+```
+
+Same deterministic verifier as the hero loop. Graduate to `dev plan` once you trust the gate.
+
+## Common mistakes
+
+- Editing files before checkout (writes may fail or lack provenance).
+- Calling `devcouncil_verify_task` without a lease (rejected).
+- Declaring done on test pass alone (verifier may report `diff_not_exercised`, stubs, scope gaps).
+- Ignoring `next_actions` categories — branch on `category`, not prose parsing.

package/src/devcouncil/skills/library/devcouncil-verification.md

@@ -0,0 +1,109 @@
+---
+name: devcouncil-verification
+title: DevCouncil Verification & Next Actions
+description: Interpret DevCouncil verification results — blocking gaps, typed next_actions, diff coverage, and anti-laziness rigor — and repair until evidence proves the diff.
+triggers:
+  keywords: [verification, verify, blocking gap, next action, diff coverage, dev check, dev verify, dev gaps, acceptance evidence, rigor]
+  markers: [.devcouncil/config.yaml]
+---
+
+# DevCouncil Verification & Next Actions
+
+DevCouncil's verifier is **deterministic** (no extra LLM calls for stub/effort detection).
+It decides pass/fail from evidence: diffs, test output, coverage intersection, and policy checks.
+
+## Verification outputs
+
+`devcouncil_verify_task` (or `dev verify`, `dev check --verify`) returns:
+
+- **`passed`** — no blocking gaps remain
+- **`blocking_gaps`** — must fix before release
+- **`next_actions`** — typed, machine-routable repair instructions
+
+Read persisted state without re-verifying:
+
+```
+devcouncil_get_gaps           # gap list (blocking_only filter available)
+devcouncil_get_next_actions   # blocking + advisory actions, allowed_next_tools
+devcouncil_get_evidence       # command results, test evidence
+devcouncil_get_task_provenance  # audit trail: writes, verify runs, diff coverage
+```
+
+## Next-actions contract
+
+Each action includes:
+
+| Field | Use |
+|---|---|
+| `gap_id` | Stable identifier for tracking |
+| `gap_type` | e.g. `diff_not_exercised`, `stub_detected`, `orphan_diff` |
+| `category` | Branch on this: `fix_code`, `add_test`, `fix_verification`, `scope`, `security`, `review`, `plan` |
+| `severity` | `high` / `medium` / `low` |
+| `blocking` | Must fix when true |
+| `action` | Human-readable fix instruction |
+| `file` / `line` | Precise location |
+| `suggested_command` | Command to run after fixing |
+
+Act on **blocking** actions first. Advisory actions surface quality issues but do not
+block release unless configured to.
+
+## Diff↔coverage gate
+
+A passing test suite only counts if it **executed the changed lines**. The verifier
+intersects coverage data with diff hunks. An unexercised diff yields `diff_not_exercised`.
+
+- **Signal-first by default** — informational unless `verification.diff_coverage.enforce: true`
+- **Hard tasks** — `verification.rigor.enforce_coverage_on_hard` promotes to blocking
+- **Degrades silently** when coverage tooling or parseable diff is unavailable — never
+  blocks correct work for lack of measurement
+
+Config (`.devcouncil/config.yaml`):
+
+```yaml
+verification:
+  diff_coverage:
+    measure: true
+    enforce: false
+    min_ratio: 0.0
+```
+
+## Anti-laziness rigor
+
+Scales strictness by task **difficulty** (`easy` / `normal` / `hard`):
+
+| Gate | Easy/Normal | Hard |
+|---|---|---|
+| Stub/TODO detection | Advisory | Blocking |
+| Effort heuristics (undersized diff) | Advisory | Blocking |
+| Coarse acceptance proof | Advisory | Blocking |
+| Diff coverage | Advisory (unless enforce) | Blocking (default) |
+
+Stub markers (`TODO`, `NotImplementedError`, assert-free tests) block on hard tasks unless
+the task mentions scaffolding and the line carries `devcouncil: allow-stub`.
+
+Repair runs include a **correction manifest** with prior diff, failing output, and
+non-negotiable rules: never weaken tests, never stub around a gap.
+
+## Repair workflow
+
+1. `devcouncil_get_next_actions` — list blocking items
+2. Fix each gap (smallest change that closes it)
+3. Re-run suggested tests via `devcouncil_run_command`
+4. `devcouncil_verify_task` — repeat until `passed`
+5. `/devcouncil:repair [TASK-ID]` or `dev repair [TASK-ID]` for CLI-guided repair
+
+## CLI equivalents
+
+```bash
+dev verify [TASK-ID]          # full task verification
+dev gaps [TASK-ID]            # list gaps
+dev check --verify --test "…" # inline requirement on current diff
+dev report                    # Requirement→Task→Diff→Evidence coverage
+dev report rigor              # tune rigor thresholds from evidence
+```
+
+## When to call success
+
+Only when **`passed: true`** from `devcouncil_verify_task` with zero blocking gaps.
+Report the verification result and cite `file:line` for any remaining advisory findings.
+Never claim done based on test output alone without running verify.