devcouncil 0.1.0 → 0.2.0

package/src/devcouncil/artifacts/coverage.py

@@ -1,96 +1,96 @@
-"""Coverage analysis utilities for the artifact graph."""
-
-from __future__ import annotations
-
-from typing import Dict, List, Tuple
-
-from devcouncil.artifacts.graph import ArtifactGraph
-
-
-def requirement_task_matrix(graph: ArtifactGraph) -> List[Dict[str, str]]:
-    """Build a requirement → task → status coverage matrix for reporting.
-    
-    Returns a list of dicts suitable for rendering as a table:
-      [{"requirement": "REQ-001", "title": "...", "task": "TASK-001", "task_status": "verified"}, ...]
-    """
-    rows: List[Dict[str, str]] = []
-    for req in graph.requirements.values():
-        linked_tasks = [
-            t for t in graph.tasks.values() if req.id in t.requirement_ids
-        ]
-        if not linked_tasks:
-            rows.append({
-                "requirement": req.id,
-                "title": req.title,
-                "task": "(none)",
-                "task_status": "NOT PLANNED",
-            })
-        else:
-            for task in linked_tasks:
-                rows.append({
-                    "requirement": req.id,
-                    "title": req.title,
-                    "task": task.id,
-                    "task_status": task.status,
-                })
-    return rows
-
-
-def acceptance_criteria_evidence_matrix(
-    graph: ArtifactGraph,
-) -> List[Dict[str, str]]:
-    """Build an AC → evidence mapping for the final report.
-    
-    Returns rows with requirement_id, ac_id, ac_description, evidence_status.
-    """
-    evidenced: Dict[str, str] = {}
-    for ev in graph.test_evidence:
-        key = ev.acceptance_criterion_id
-        evidenced[key] = ev.status  # "passed", "failed", "not_run"
-
-    rows: List[Dict[str, str]] = []
-    for req in graph.requirements.values():
-        for ac in req.acceptance_criteria:
-            status = evidenced.get(ac.id, "no_evidence")
-            rows.append({
-                "requirement_id": req.id,
-                "ac_id": ac.id,
-                "description": ac.description,
-                "verification_method": ac.verification_method,
-                "status": status,
-            })
-    return rows
-
-
-def can_approve_plan(graph: ArtifactGraph) -> Tuple[bool, List[str]]:
-    """Check if the plan meets the PLAN_APPROVED gate criteria.
-    
-    Returns (passed, list_of_reasons_if_failed).
-    
-    Criteria (from §12):
-      - Every requirement has acceptance criteria.
-      - Every acceptance criterion has a verification method.
-      - Every requirement maps to at least one task.
-      - Every task maps to at least one requirement.
-      - Every high-impact assumption is confirmed or converted.
-      - No critical critique finding remains open.
-      - No blocking question remains unanswered.
-    """
-    reasons: List[str] = []
-
-    for req in graph.requirements_without_acceptance_criteria():
-        reasons.append(f"{req.id} has no acceptance criteria.")
-
-    for req in graph.requirements_without_tasks():
-        reasons.append(f"{req.id} is not mapped to any task.")
-
-    for task in graph.tasks_without_requirements():
-        reasons.append(f"{task.id} is not mapped to any requirement.")
-
-    for asm in graph.unconfirmed_high_impact_assumptions():
-        reasons.append(f"Assumption {asm.id} (high impact) is still open: {asm.statement}")
-
-    for finding in graph.open_findings("critical"):
-        reasons.append(f"Critical finding {finding.id} is still open: {finding.claim}")
-
-    return len(reasons) == 0, reasons
+"""Coverage analysis utilities for the artifact graph."""
+
+from __future__ import annotations
+
+from typing import Dict, List, Tuple
+
+from devcouncil.artifacts.graph import ArtifactGraph
+
+
+def requirement_task_matrix(graph: ArtifactGraph) -> List[Dict[str, str]]:
+    """Build a requirement → task → status coverage matrix for reporting.
+    
+    Returns a list of dicts suitable for rendering as a table:
+      [{"requirement": "REQ-001", "title": "...", "task": "TASK-001", "task_status": "verified"}, ...]
+    """
+    rows: List[Dict[str, str]] = []
+    for req in graph.requirements.values():
+        linked_tasks = [
+            t for t in graph.tasks.values() if req.id in t.requirement_ids
+        ]
+        if not linked_tasks:
+            rows.append({
+                "requirement": req.id,
+                "title": req.title,
+                "task": "(none)",
+                "task_status": "NOT PLANNED",
+            })
+        else:
+            for task in linked_tasks:
+                rows.append({
+                    "requirement": req.id,
+                    "title": req.title,
+                    "task": task.id,
+                    "task_status": task.status,
+                })
+    return rows
+
+
+def acceptance_criteria_evidence_matrix(
+    graph: ArtifactGraph,
+) -> List[Dict[str, str]]:
+    """Build an AC → evidence mapping for the final report.
+    
+    Returns rows with requirement_id, ac_id, ac_description, evidence_status.
+    """
+    evidenced: Dict[str, str] = {}
+    for ev in graph.test_evidence:
+        key = ev.acceptance_criterion_id
+        evidenced[key] = ev.status  # "passed", "failed", "not_run"
+
+    rows: List[Dict[str, str]] = []
+    for req in graph.requirements.values():
+        for ac in req.acceptance_criteria:
+            status = evidenced.get(ac.id, "no_evidence")
+            rows.append({
+                "requirement_id": req.id,
+                "ac_id": ac.id,
+                "description": ac.description,
+                "verification_method": ac.verification_method,
+                "status": status,
+            })
+    return rows
+
+
+def can_approve_plan(graph: ArtifactGraph) -> Tuple[bool, List[str]]:
+    """Check if the plan meets the PLAN_APPROVED gate criteria.
+    
+    Returns (passed, list_of_reasons_if_failed).
+    
+    Criteria (from §12):
+      - Every requirement has acceptance criteria.
+      - Every acceptance criterion has a verification method.
+      - Every requirement maps to at least one task.
+      - Every task maps to at least one requirement.
+      - Every high-impact assumption is confirmed or converted.
+      - No critical critique finding remains open.
+      - No blocking question remains unanswered.
+    """
+    reasons: List[str] = []
+
+    for req in graph.requirements_without_acceptance_criteria():
+        reasons.append(f"{req.id} has no acceptance criteria.")
+
+    for req in graph.requirements_without_tasks():
+        reasons.append(f"{req.id} is not mapped to any task.")
+
+    for task in graph.tasks_without_requirements():
+        reasons.append(f"{task.id} is not mapped to any requirement.")
+
+    for asm in graph.unconfirmed_high_impact_assumptions():
+        reasons.append(f"Assumption {asm.id} (high impact) is still open: {asm.statement}")
+
+    for finding in graph.open_findings("critical"):
+        reasons.append(f"Critical finding {finding.id} is still open: {finding.claim}")
+
+    return len(reasons) == 0, reasons

package/src/devcouncil/artifacts/graph.py

@@ -1,143 +1,163 @@
-"""Artifact graph: the persistent, directed graph that links requirements to evidence.
-
-This is DevCouncil's core data structure:
-  Requirement -> AcceptanceCriterion -> Task -> PlannedFile -> ChangedFile
-              -> CommandResult -> TestEvidence -> Gap
-
-The graph enables coverage queries like:
-  - Which requirements have no tasks?
-  - Which tasks produced no changed files?
-  - Which acceptance criteria have no evidence?
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass, field
-from typing import Any, Dict, List, Set, Tuple
-
-from devcouncil.domain.requirement import Requirement, AcceptanceCriterion
-from devcouncil.domain.task import Task
-from devcouncil.domain.assumption import Assumption
-from devcouncil.domain.evidence import CommandResult, DiffEvidence, TestEvidence
-from devcouncil.domain.gap import Gap
-from devcouncil.domain.critique import CritiqueFinding
-
-
-@dataclass
-class ArtifactGraph:
-    """Directed graph of all planning and execution artifacts."""
-
-    requirements: Dict[str, Requirement] = field(default_factory=dict)
-    tasks: Dict[str, Task] = field(default_factory=dict)
-    assumptions: Dict[str, Assumption] = field(default_factory=dict)
-    findings: Dict[str, CritiqueFinding] = field(default_factory=dict)
-    gaps: Dict[str, Gap] = field(default_factory=dict)
-    test_evidence: List[TestEvidence] = field(default_factory=list)
-    diff_evidence: List[DiffEvidence] = field(default_factory=list)
-    command_results: List[CommandResult] = field(default_factory=list)
-
-    # --- Mutation ---
-
-    def add_requirement(self, req: Requirement) -> None:
-        self.requirements[req.id] = req
-
-    def add_task(self, task: Task) -> None:
-        self.tasks[task.id] = task
-
-    def add_assumption(self, asm: Assumption) -> None:
-        self.assumptions[asm.id] = asm
-
-    def add_finding(self, finding: CritiqueFinding) -> None:
-        self.findings[finding.id] = finding
-
-    def add_gap(self, gap: Gap) -> None:
-        self.gaps[gap.id] = gap
-
-    def add_test_evidence(self, ev: TestEvidence) -> None:
-        self.test_evidence.append(ev)
-
-    def add_diff_evidence(self, ev: DiffEvidence) -> None:
-        self.diff_evidence.append(ev)
-
-    def add_command_result(self, cr: CommandResult) -> None:
-        self.command_results.append(cr)
-
-    # --- Coverage Queries ---
-
-    def requirements_without_tasks(self) -> List[Requirement]:
-        """Requirements that are not mapped to any task."""
-        task_req_ids: Set[str] = set()
-        for task in self.tasks.values():
-            task_req_ids.update(task.requirement_ids)
-        return [r for r in self.requirements.values() if r.id not in task_req_ids]
-
-    def tasks_without_requirements(self) -> List[Task]:
-        """Tasks that don't map back to any requirement."""
-        return [t for t in self.tasks.values() if not t.requirement_ids]
-
-    def requirements_without_acceptance_criteria(self) -> List[Requirement]:
-        """Requirements with no acceptance criteria defined."""
-        return [r for r in self.requirements.values() if not r.acceptance_criteria]
-
-    def acceptance_criteria_without_evidence(self) -> List[Tuple[str, AcceptanceCriterion]]:
-        """AC IDs that have no test evidence mapped to them."""
-        evidenced_ac_ids: Set[str] = set()
-        for ev in self.test_evidence:
-            evidenced_ac_ids.add(ev.acceptance_criterion_id)
-
-        results: List[Tuple[str, AcceptanceCriterion]] = []
-        for req in self.requirements.values():
-            for ac in req.acceptance_criteria:
-                if ac.id not in evidenced_ac_ids:
-                    results.append((req.id, ac))
-        return results
-
-    def tasks_without_changed_files(self) -> List[Task]:
-        """Tasks that have not produced any diff evidence."""
-        tasks_with_diffs: Set[str] = set()
-        for de in self.diff_evidence:
-            tasks_with_diffs.add(de.task_id)
-        return [
-            t for t in self.tasks.values()
-            if t.id not in tasks_with_diffs and t.status not in ("planned", "ready")
-        ]
-
-    def open_findings(self, min_severity: str = "low") -> List[CritiqueFinding]:
-        """Critique findings that are still open."""
-        severity_order = {"low": 0, "medium": 1, "high": 2, "critical": 3}
-        min_rank = severity_order.get(min_severity, 0)
-        return [
-            f for f in self.findings.values()
-            if f.status == "open" and severity_order.get(f.severity, 0) >= min_rank
-        ]
-
-    def blocking_gaps(self) -> List[Gap]:
-        """Gaps that are blocking progress."""
-        return [g for g in self.gaps.values() if g.blocking]
-
-    def unconfirmed_high_impact_assumptions(self) -> List[Assumption]:
-        """Assumptions with high impact that are still open."""
-        return [
-            a for a in self.assumptions.values()
-            if a.status == "open" and a.impact == "high"
-        ]
-
-    # --- Aggregate ---
-
-    def coverage_summary(self) -> Dict[str, Any]:
-        """Produce a coverage summary for reporting."""
-        return {
-            "total_requirements": len(self.requirements),
-            "requirements_without_tasks": len(self.requirements_without_tasks()),
-            "requirements_without_ac": len(self.requirements_without_acceptance_criteria()),
-            "total_tasks": len(self.tasks),
-            "tasks_without_requirements": len(self.tasks_without_requirements()),
-            "tasks_without_diffs": len(self.tasks_without_changed_files()),
-            "total_ac": sum(len(r.acceptance_criteria) for r in self.requirements.values()),
-            "ac_without_evidence": len(self.acceptance_criteria_without_evidence()),
-            "total_gaps": len(self.gaps),
-            "blocking_gaps": len(self.blocking_gaps()),
-            "open_findings": len(self.open_findings()),
-            "high_critical_open_findings": len(self.open_findings("high")),
-            "unconfirmed_high_assumptions": len(self.unconfirmed_high_impact_assumptions()),
-        }
+"""Artifact graph: the persistent, directed graph that links requirements to evidence.
+
+This is DevCouncil's core data structure:
+  Requirement -> AcceptanceCriterion -> Task -> PlannedFile -> ChangedFile
+              -> CommandResult -> TestEvidence -> Gap
+
+The graph enables coverage queries like:
+  - Which requirements have no tasks?
+  - Which tasks produced no changed files?
+  - Which acceptance criteria have no evidence?
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Set, Tuple
+
+from devcouncil.domain.requirement import Requirement, AcceptanceCriterion
+from devcouncil.domain.task import Task
+from devcouncil.domain.assumption import Assumption
+from devcouncil.domain.evidence import CommandResult, DiffCoverageEvidence, DiffEvidence, TestEvidence
+from devcouncil.domain.gap import Gap
+from devcouncil.domain.critique import CritiqueFinding
+
+
+@dataclass
+class ArtifactGraph:
+    """Directed graph of all planning and execution artifacts."""
+
+    requirements: Dict[str, Requirement] = field(default_factory=dict)
+    tasks: Dict[str, Task] = field(default_factory=dict)
+    assumptions: Dict[str, Assumption] = field(default_factory=dict)
+    findings: Dict[str, CritiqueFinding] = field(default_factory=dict)
+    gaps: Dict[str, Gap] = field(default_factory=dict)
+    test_evidence: List[TestEvidence] = field(default_factory=list)
+    diff_evidence: List[DiffEvidence] = field(default_factory=list)
+    command_results: List[CommandResult] = field(default_factory=list)
+    diff_coverage_evidence: List[DiffCoverageEvidence] = field(default_factory=list)
+
+    # --- Mutation ---
+
+    def add_requirement(self, req: Requirement) -> None:
+        self.requirements[req.id] = req
+
+    def add_task(self, task: Task) -> None:
+        self.tasks[task.id] = task
+
+    def add_assumption(self, asm: Assumption) -> None:
+        self.assumptions[asm.id] = asm
+
+    def add_finding(self, finding: CritiqueFinding) -> None:
+        self.findings[finding.id] = finding
+
+    def add_gap(self, gap: Gap) -> None:
+        self.gaps[gap.id] = gap
+
+    def add_test_evidence(self, ev: TestEvidence) -> None:
+        self.test_evidence.append(ev)
+
+    def add_diff_evidence(self, ev: DiffEvidence) -> None:
+        self.diff_evidence.append(ev)
+
+    def add_command_result(self, cr: CommandResult) -> None:
+        self.command_results.append(cr)
+
+    def add_diff_coverage_evidence(self, ev: DiffCoverageEvidence) -> None:
+        self.diff_coverage_evidence.append(ev)
+
+    def diff_coverage_findings(self) -> List[DiffCoverageEvidence]:
+        """Measured diff-coverage runs where the changed lines were NOT fully exercised
+        — i.e. a green suite that did not actually run the new code."""
+        return [
+            ev for ev in self.diff_coverage_evidence
+            if ev.measured and ev.changed_lines and ev.covered_lines < ev.changed_lines
+        ]
+
+    # --- Coverage Queries ---
+
+    def requirements_without_tasks(self) -> List[Requirement]:
+        """Requirements that are not mapped to any task."""
+        task_req_ids: Set[str] = set()
+        for task in self.tasks.values():
+            task_req_ids.update(task.requirement_ids)
+        return [r for r in self.requirements.values() if r.id not in task_req_ids]
+
+    def tasks_without_requirements(self) -> List[Task]:
+        """Tasks that don't map back to any requirement."""
+        return [t for t in self.tasks.values() if not t.requirement_ids]
+
+    def requirements_without_acceptance_criteria(self) -> List[Requirement]:
+        """Requirements with no acceptance criteria defined."""
+        return [r for r in self.requirements.values() if not r.acceptance_criteria]
+
+    def acceptance_criteria_without_evidence(self) -> List[Tuple[str, AcceptanceCriterion]]:
+        """AC IDs that have no *passing* test evidence mapped to them.
+
+        Only ``passed`` evidence counts: a failed or not-run check is not proof, so
+        it must not remove a criterion from the unproven list (which would feed a
+        falsely-green coverage summary to ``dev status`` and the MCP surface).
+        """
+        evidenced_ac_ids: Set[str] = set()
+        for ev in self.test_evidence:
+            if getattr(ev, "status", "passed") == "passed":
+                evidenced_ac_ids.add(ev.acceptance_criterion_id)
+
+        results: List[Tuple[str, AcceptanceCriterion]] = []
+        for req in self.requirements.values():
+            for ac in req.acceptance_criteria:
+                if ac.id not in evidenced_ac_ids:
+                    results.append((req.id, ac))
+        return results
+
+    def tasks_without_changed_files(self) -> List[Task]:
+        """Tasks that have not produced any diff evidence."""
+        tasks_with_diffs: Set[str] = set()
+        for de in self.diff_evidence:
+            tasks_with_diffs.add(de.task_id)
+        return [
+            t for t in self.tasks.values()
+            if t.id not in tasks_with_diffs and t.status not in ("planned", "ready")
+        ]
+
+    def open_findings(self, min_severity: str = "low") -> List[CritiqueFinding]:
+        """Critique findings that are still open."""
+        severity_order = {"low": 0, "medium": 1, "high": 2, "critical": 3}
+        min_rank = severity_order.get(min_severity, 0)
+        return [
+            f for f in self.findings.values()
+            if f.status == "open" and severity_order.get(f.severity, 0) >= min_rank
+        ]
+
+    def blocking_gaps(self) -> List[Gap]:
+        """Gaps that are blocking progress."""
+        return [g for g in self.gaps.values() if g.blocking]
+
+    def unconfirmed_high_impact_assumptions(self) -> List[Assumption]:
+        """Assumptions with high impact that are still open."""
+        return [
+            a for a in self.assumptions.values()
+            if a.status == "open" and a.impact == "high"
+        ]
+
+    # --- Aggregate ---
+
+    def coverage_summary(self) -> Dict[str, Any]:
+        """Produce a coverage summary for reporting."""
+        return {
+            "total_requirements": len(self.requirements),
+            "requirements_without_tasks": len(self.requirements_without_tasks()),
+            "requirements_without_ac": len(self.requirements_without_acceptance_criteria()),
+            "total_tasks": len(self.tasks),
+            "tasks_without_requirements": len(self.tasks_without_requirements()),
+            "tasks_without_diffs": len(self.tasks_without_changed_files()),
+            "total_ac": sum(len(r.acceptance_criteria) for r in self.requirements.values()),
+            "ac_without_evidence": len(self.acceptance_criteria_without_evidence()),
+            "total_gaps": len(self.gaps),
+            "blocking_gaps": len(self.blocking_gaps()),
+            "diff_coverage_runs": len(self.diff_coverage_evidence),
+            "unexercised_diff_findings": len(self.diff_coverage_findings()),
+            "open_findings": len(self.open_findings()),
+            "high_critical_open_findings": len(self.open_findings("high")),
+            "unconfirmed_high_assumptions": len(self.unconfirmed_high_impact_assumptions()),
+        }

package/src/devcouncil/artifacts/migrations.py

@@ -1,20 +1,20 @@
-from typing import Any, Dict
-
-class ArtifactMigrator:
-    """Migrates artifact schemas across DevCouncil versions."""
-    
-    @staticmethod
-    def migrate_requirement(data: Dict[str, Any]) -> Dict[str, Any]:
-        """Upgrade requirement payload to current schema."""
-        if "priority" not in data:
-            data["priority"] = "medium"
-        return data
-
-    @staticmethod
-    def migrate_task(data: Dict[str, Any]) -> Dict[str, Any]:
-        """Upgrade task payload to current schema."""
-        if "forbidden_changes" not in data:
-            data["forbidden_changes"] = []
-        if "expected_tests" not in data:
-            data["expected_tests"] = []
-        return data
+from typing import Any, Dict
+
+class ArtifactMigrator:
+    """Migrates artifact schemas across DevCouncil versions."""
+    
+    @staticmethod
+    def migrate_requirement(data: Dict[str, Any]) -> Dict[str, Any]:
+        """Upgrade requirement payload to current schema."""
+        if "priority" not in data:
+            data["priority"] = "medium"
+        return data
+
+    @staticmethod
+    def migrate_task(data: Dict[str, Any]) -> Dict[str, Any]:
+        """Upgrade task payload to current schema."""
+        if "forbidden_changes" not in data:
+            data["forbidden_changes"] = []
+        if "expected_tests" not in data:
+            data["expected_tests"] = []
+        return data

package/src/devcouncil/artifacts/schemas.py

@@ -1,23 +1,23 @@
-from typing import List
-from pydantic import BaseModel, Field
-
-# Common schemas that might be shared across artifacts
-class FileModification(BaseModel):
-    path: str
-    diff: str
-
-class CoverageMatrix(BaseModel):
-    """Represents a requirement to task/test mapping coverage."""
-    requirement_id: str
-    task_ids: List[str] = Field(default_factory=list)
-    test_evidence_ids: List[str] = Field(default_factory=list)
-    is_covered: bool = False
-    missing_tasks: bool = False
-    missing_tests: bool = False
-
-class ReportSchema(BaseModel):
-    project_id: str
-    tasks_completed: int
-    tasks_blocked: int
-    open_gaps: int
-    coverage_matrix: List[CoverageMatrix]
+from typing import List
+from pydantic import BaseModel, Field
+
+# Common schemas that might be shared across artifacts
+class FileModification(BaseModel):
+    path: str
+    diff: str
+
+class CoverageMatrix(BaseModel):
+    """Represents a requirement to task/test mapping coverage."""
+    requirement_id: str
+    task_ids: List[str] = Field(default_factory=list)
+    test_evidence_ids: List[str] = Field(default_factory=list)
+    is_covered: bool = False
+    missing_tasks: bool = False
+    missing_tests: bool = False
+
+class ReportSchema(BaseModel):
+    project_id: str
+    tasks_completed: int
+    tasks_blocked: int
+    open_gaps: int
+    coverage_matrix: List[CoverageMatrix]

package/src/devcouncil/artifacts/serializer.py

@@ -1,21 +1,21 @@
-import json
-from typing import Any, Dict, TypeVar, Type
-from pydantic import BaseModel
-
-T = TypeVar("T", bound=BaseModel)
-
-class ArtifactSerializer:
-    """Handles serialization and deserialization of DevCouncil artifacts."""
-    
-    @staticmethod
-    def to_json(artifact: BaseModel) -> str:
-        return artifact.model_dump_json(indent=2)
-
-    @staticmethod
-    def from_json(json_str: str, model_class: Type[T]) -> T:
-        data = json.loads(json_str)
-        return model_class.model_validate(data)
-
-    @staticmethod
-    def to_dict(artifact: BaseModel) -> Dict[str, Any]:
-        return artifact.model_dump()
+import json
+from typing import Any, Dict, TypeVar, Type
+from pydantic import BaseModel
+
+T = TypeVar("T", bound=BaseModel)
+
+class ArtifactSerializer:
+    """Handles serialization and deserialization of DevCouncil artifacts."""
+    
+    @staticmethod
+    def to_json(artifact: BaseModel) -> str:
+        return artifact.model_dump_json(indent=2)
+
+    @staticmethod
+    def from_json(json_str: str, model_class: Type[T]) -> T:
+        data = json.loads(json_str)
+        return model_class.model_validate(data)
+
+    @staticmethod
+    def to_dict(artifact: BaseModel) -> Dict[str, Any]:
+        return artifact.model_dump()