devcouncil 0.1.0 → 0.2.0

package/src/devcouncil/cli/main.py

@@ -1,12 +1,48 @@
+import sys
+
 import typer
-from devcouncil.cli.commands import (
+
+
+def _configure_stdio() -> None:
+    """Make stdout/stderr resilient to non-cp1252 characters.
+
+    Coding agents and rich output emit Unicode such as ``✓``. On Windows the
+    default console / redirected-pipe encoding is cp1252, where an un-encodable
+    character raises UnicodeEncodeError mid-write. Because Rich buffers output,
+    that error can surface during an unrelated later write — which previously
+    got misreported as a coding agent "failing to start". Reconfigure both
+    streams to UTF-8 with replacement so output can never crash the process.
+    """
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is None:
+            continue
+        try:
+            reconfigure(encoding="utf-8", errors="replace")
+        except (ValueError, OSError):
+            try:
+                reconfigure(errors="replace")
+            except (ValueError, OSError):
+                pass
+
+
+_configure_stdio()
+
+from devcouncil.cli.commands import (  # noqa: E402 - imports follow stdio reconfiguration
     artifacts,
+    agents,
     baseline,
+    check,
     config,
+    cost,
+    ast,
+    dashboard,
     doctor,
+    go,
     hook,
     init,
     integrate,
+    lsp,
     map,
     mcp_server,
     plan,
@@ -16,6 +52,7 @@ from devcouncil.cli.commands import (
     reset_demo_state,
     rollback,
     run,
+    runs,
     setup,
     show,
     status,
@@ -23,48 +60,78 @@ from devcouncil.cli.commands import (
     trace,
     verify,
     version,
+    watch,
+    shell,
+    semantic,
+    evidence,
+    handoff,
+    skills,
+    scaffold,
+)
+from devcouncil.cli.commands.watch_fs import watch_fs  # noqa: E402 - imports follow stdio reconfiguration
+
+app = typer.Typer(
+    name="dev",
+    help="DevCouncil: Gated orchestrator for AI-assisted software development.",
+    add_completion=False,
 )
-
-app = typer.Typer(
-    name="dev",
-    help="DevCouncil: Gated orchestrator for AI-assisted software development.",
-    add_completion=False,
-)
-
-# Typer subcommands (those using app = Typer())
-app.add_typer(init.app, name="init")
-app.add_typer(doctor.app, name="doctor")
-app.add_typer(prompt.app, name="prompt")
-app.add_typer(tasks.app, name="tasks")
-app.add_typer(show.app, name="show")
+
+# Typer subcommands (those using app = Typer())
+app.add_typer(init.app, name="init")
+app.add_typer(doctor.app, name="doctor")
+app.add_typer(tasks.app, name="tasks")
 app.add_typer(report.app, name="report")
 app.add_typer(rollback.app, name="rollback")
 app.add_typer(config.app, name="config")
 app.add_typer(artifacts.app, name="artifacts")
+app.add_typer(agents.app, name="agents")
 app.add_typer(hook.app, name="hook")
 app.add_typer(version.app, name="version")
 app.add_typer(mcp_server.app, name="mcp-server")
 app.add_typer(integrate.app, name="integrate")
 app.add_typer(integrate.app, name="integrations")
 app.add_typer(trace.app, name="trace")
+app.add_typer(cost.app, name="cost")
+app.add_typer(runs.app, name="runs")
 app.add_typer(setup.app, name="setup")
+app.add_typer(lsp.app, name="lsp")
+app.add_typer(ast.app, name="ast")
+app.add_typer(dashboard.app, name="dashboard")
+app.add_typer(watch.app, name="watch")
+app.add_typer(semantic.app, name="semantic")
+app.add_typer(evidence.app, name="evidence")
+app.add_typer(skills.app, name="skills")
+watch.app.command("fs")(watch_fs)
 
 # Direct command registrations (those defined as def cmd())
 app.command(name="baseline")(baseline.baseline)
+app.command(name="e2e")(go.go)
+app.command(name="go")(go.go)
 app.command(name="map")(map.map_repo)
+app.command(name="scaffold-ci")(scaffold.scaffold_ci_command)
 app.command(name="plan")(plan.plan)
+app.command(name="approve")(plan.approve)
+app.command(name="prompt")(prompt.prompt)
 app.command(name="reset-demo-state")(reset_demo_state.reset_demo_state)
 app.command(name="run")(run.run)
+# shell/handoff take a positional TASK_ID followed by options, so they must be
+# plain commands — as typer sub-apps (click groups) the documented
+# `dev shell TASK-001 --command ...` form fails to parse.
+app.command(name="shell")(shell.shell)
+app.command(name="handoff")(handoff.handoff)
+app.command(name="show")(show.show)
 app.command(name="verify")(verify.verify)
+app.command(name="check")(check.check)
 app.command(name="repair")(repair.repair)
-app.command(name="status")(status.status)
-
-@app.callback()
-def main():
-    """
-    DevCouncil: Gated orchestrator for AI-assisted software development.
-    """
-    pass
-
-if __name__ == "__main__":
-    app()
+app.command(name="status")(status.status)
+app.command(name="optimize")(agents.optimize_agent)
+
+@app.callback()
+def main(ctx: typer.Context):
+    """
+    DevCouncil: Gated orchestrator for AI-assisted software development.
+    """
+    return
+
+if __name__ == "__main__":
+    app()

package/src/devcouncil/council/prompts/arbiter.md

@@ -1,19 +1,19 @@
-Goal: {goal}
-
-Initial Requirements:
-{requirements_json}
-
-Plan A: {plan_a_json}
-Plan B: {plan_b_json}
-
-Critique of Plan B by Critic A: {critique_a_json}
-Critique of Plan A by Critic B: {critique_b_json}
-
-Rebuttal of Critic B by Planner A: {rebuttal_a_json}
-Rebuttal of Critic A by Planner B: {rebuttal_b_json}
-
-You are the arbiter engineering manager. Your goal is to produce the final, definitive set of requirements and tasks.
-- You do not decide by vibes.
-- High-severity unrefuted findings from critics must be incorporated into the final requirements or tasks.
-- If a planner successfully rebutted a finding, you may skip it.
-- Produce a single, coherent task graph.
+Goal: {goal}
+
+Initial Requirements:
+{requirements_json}
+
+Plan A: {plan_a_json}
+Plan B: {plan_b_json}
+
+Critique of Plan B by Critic A: {critique_a_json}
+Critique of Plan A by Critic B: {critique_b_json}
+
+Rebuttal of Critic B by Planner A: {rebuttal_a_json}
+Rebuttal of Critic A by Planner B: {rebuttal_b_json}
+
+You are the arbiter engineering manager. Your goal is to produce the final, definitive set of requirements and tasks.
+- You do not decide by vibes.
+- High-severity unrefuted findings from critics must be incorporated into the final requirements or tasks.
+- If a planner successfully rebutted a finding, you may skip it.
+- Produce a single, coherent task graph.

package/src/devcouncil/council/prompts/critic_a.md

@@ -1,10 +1,10 @@
-Requirements:
-{requirements_json}
-
-Target Plan:
-{target_plan_json}
-
-You are a hostile staff engineer reviewing another team's implementation plan.
-Find missing requirements, bad assumptions, missing tests, security risks, migration risks, and unverifiable claims.
-Do not praise. Do not rewrite the plan.
-Every finding must include a falsifiable_check.
+Requirements:
+{requirements_json}
+
+Target Plan:
+{target_plan_json}
+
+You are a hostile staff engineer reviewing another team's implementation plan.
+Find missing requirements, bad assumptions, missing tests, security risks, migration risks, and unverifiable claims.
+Do not praise. Do not rewrite the plan.
+Every finding must include a falsifiable_check.

package/src/devcouncil/council/prompts/critic_b.md

@@ -1,10 +1,10 @@
-Requirements:
-{requirements_json}
-
-Target Plan:
-{target_plan_json}
-
-You are a hostile staff engineer reviewing another team's implementation plan.
-Find missing requirements, bad assumptions, missing tests, security risks, migration risks, and unverifiable claims.
-Do not praise. Do not rewrite the plan.
-Every finding must include a falsifiable_check.
+Requirements:
+{requirements_json}
+
+Target Plan:
+{target_plan_json}
+
+You are a hostile staff engineer reviewing another team's implementation plan.
+Find missing requirements, bad assumptions, missing tests, security risks, migration risks, and unverifiable claims.
+Do not praise. Do not rewrite the plan.
+Every finding must include a falsifiable_check.

package/src/devcouncil/council/prompts/implementation_reviewer.md

@@ -1,16 +1,16 @@
-You are an expert software reviewer. Review the following code changes against the task requirements.
-Task: {task.title}
-Description: {task.description}
-
-Requirements:
-{requirements_json}
-
-Code Diff:
-{diff}
-
-Your task is to identify if the implementation is complete, correct, and follows best practices.
-- Identify missing edge cases.
-- Identify architectural drift.
-- Identify security risks not caught by static scans.
-
-Return a JSON object with 'is_satisfactory' and a list of 'findings' (as Gap objects).
+You are an expert software reviewer. Review the following code changes against the task requirements.
+Task: {task.title}
+Description: {task.description}
+
+Requirements:
+{requirements_json}
+
+Code Diff:
+{diff}
+
+Your task is to identify if the implementation is complete, correct, and follows best practices.
+- Identify missing edge cases.
+- Identify architectural drift.
+- Identify security risks not caught by static scans.
+
+Return a JSON object with 'is_satisfactory' and a list of 'findings' (as Gap objects).

package/src/devcouncil/council/prompts/planner_a.md

@@ -1,16 +1,16 @@
-Goal: {goal}
-
-Requirements:
-{requirements_json}
-
-Repository Map:
-{repo_map_json}
-
-Your task is to create a detailed implementation plan.
-- Break down the requirements into atomic implementation tasks.
-- For each task, specify which files will be created or modified.
-- Specify which tests are expected to verify the task.
-- Ensure each task maps back to at least one requirement.
-
-Role-specific instructions:
-You are the pragmatic tech lead. Optimize for simplicity and minimal dependencies.
+Goal: {goal}
+
+Requirements:
+{requirements_json}
+
+Repository Map:
+{repo_map_json}
+
+Your task is to create a detailed implementation plan.
+- Break down the requirements into atomic implementation tasks.
+- For each task, specify which files will be created or modified.
+- Specify which tests are expected to verify the task.
+- Ensure each task maps back to at least one requirement.
+
+Role-specific instructions:
+You are the pragmatic tech lead. Optimize for simplicity and minimal dependencies.

package/src/devcouncil/council/prompts/planner_b.md

@@ -1,16 +1,16 @@
-Goal: {goal}
-
-Requirements:
-{requirements_json}
-
-Repository Map:
-{repo_map_json}
-
-Your task is to create a detailed implementation plan.
-- Break down the requirements into atomic implementation tasks.
-- For each task, specify which files will be created or modified.
-- Specify which tests are expected to verify the task.
-- Ensure each task maps back to at least one requirement.
-
-Role-specific instructions:
-You are the production-readiness architect. Optimize for security, performance, edge cases, failure modes, and maintainability. Assume the first plan will miss subtle requirements.
+Goal: {goal}
+
+Requirements:
+{requirements_json}
+
+Repository Map:
+{repo_map_json}
+
+Your task is to create a detailed implementation plan.
+- Break down the requirements into atomic implementation tasks.
+- For each task, specify which files will be created or modified.
+- Specify which tests are expected to verify the task.
+- Ensure each task maps back to at least one requirement.
+
+Role-specific instructions:
+You are the production-readiness architect. Optimize for security, performance, edge cases, failure modes, and maintainability. Assume the first plan will miss subtle requirements.

package/src/devcouncil/council/prompts/rebuttal.md

@@ -1,10 +1,10 @@
-Original Plan:
-{original_plan_json}
-
-Critique Findings:
-{findings_json}
-
-You are the planner who created the original plan. Review the critique findings.
-- A finding can be rejected only with artifact evidence or strong justification.
-- A finding can be accepted and converted into a requirement/task/test.
-- No hand-wavy rebuttals.
+Original Plan:
+{original_plan_json}
+
+Critique Findings:
+{findings_json}
+
+You are the planner who created the original plan. Review the critique findings.
+- A finding can be rejected only with artifact evidence or strong justification.
+- A finding can be accepted and converted into a requirement/task/test.
+- No hand-wavy rebuttals.

package/src/devcouncil/council/prompts/spec_writer.md

@@ -1,12 +1,12 @@
-Goal: {goal}
-
-Repository Map:
-{repo_map_json}
-
-Your task is to draft the initial software specification for this goal.
-1. Identify functional and non-functional requirements.
-2. Extract any assumptions you are making about the codebase or architecture.
-3. List any blocking questions that the user must answer before implementation can proceed.
-
-Each requirement MUST have clear acceptance criteria with verification methods.
-Each assumption MUST have a confidence and impact level.
+Goal: {goal}
+
+Repository Map:
+{repo_map_json}
+
+Your task is to draft the initial software specification for this goal.
+1. Identify functional and non-functional requirements.
+2. Extract any assumptions you are making about the codebase or architecture.
+3. List any blocking questions that the user must answer before implementation can proceed.
+
+Each requirement MUST have clear acceptance criteria with verification methods.
+Each assumption MUST have a confidence and impact level.

package/src/devcouncil/domain/assumption.py

@@ -1,17 +1,17 @@
-from pydantic import BaseModel, Field
-from typing import Literal, List
-
-class Assumption(BaseModel):
-    id: str
-    statement: str
-    confidence: Literal["low", "medium", "high"]
-    impact: Literal["low", "medium", "high"]
-    reversible: bool
-    requires_user_confirmation: bool
-    linked_requirement_ids: List[str] = Field(default_factory=list)
-    status: Literal[
-        "open",
-        "confirmed",
-        "rejected",
-        "converted_to_requirement"
-    ] = "open"
+from pydantic import BaseModel, Field
+from typing import Literal, List
+
+class Assumption(BaseModel):
+    id: str
+    statement: str
+    confidence: Literal["low", "medium", "high"]
+    impact: Literal["low", "medium", "high"]
+    reversible: bool
+    requires_user_confirmation: bool
+    linked_requirement_ids: List[str] = Field(default_factory=list)
+    status: Literal[
+        "open",
+        "confirmed",
+        "rejected",
+        "converted_to_requirement"
+    ] = "open"

package/src/devcouncil/domain/critique.py

@@ -1,32 +1,32 @@
-from pydantic import BaseModel
-from typing import Literal, Optional
-
-class CritiqueFinding(BaseModel):
-    id: str
-    source_agent: str
-    target_plan_id: str
-    severity: Literal["low", "medium", "high", "critical"]
-    finding_type: Literal[
-        "missing_requirement",
-        "missing_task",
-        "missing_test",
-        "bad_assumption",
-        "architecture_risk",
-        "security_risk",
-        "performance_risk",
-        "dependency_risk",
-        "migration_risk",
-        "unverifiable_acceptance_criteria"
-    ]
-    claim: str
-    linked_requirement_id: Optional[str] = None
-    suggested_requirement: Optional[str] = None
-    suggested_task: Optional[str] = None
-    falsifiable_check: str
-    status: Literal[
-        "open",
-        "accepted",
-        "rejected",
-        "converted",
-        "needs_user"
-    ] = "open"
+from pydantic import BaseModel
+from typing import Literal, Optional
+
+class CritiqueFinding(BaseModel):
+    id: str
+    source_agent: str
+    target_plan_id: str
+    severity: Literal["low", "medium", "high", "critical"]
+    finding_type: Literal[
+        "missing_requirement",
+        "missing_task",
+        "missing_test",
+        "bad_assumption",
+        "architecture_risk",
+        "security_risk",
+        "performance_risk",
+        "dependency_risk",
+        "migration_risk",
+        "unverifiable_acceptance_criteria"
+    ]
+    claim: str
+    linked_requirement_id: Optional[str] = None
+    suggested_requirement: Optional[str] = None
+    suggested_task: Optional[str] = None
+    falsifiable_check: str
+    status: Literal[
+        "open",
+        "accepted",
+        "rejected",
+        "converted",
+        "needs_user"
+    ] = "open"

package/src/devcouncil/domain/evidence.py

@@ -1,27 +1,47 @@
-from pydantic import BaseModel
-from typing import Literal, List
-
-class CommandResult(BaseModel):
-    command: str
-    exit_code: int
-    stdout_path: str
-    stderr_path: str
-    summary: str
-
-class DiffEvidence(BaseModel):
-    task_id: str
-    changed_files: List[str]
-    added_files: List[str]
-    deleted_files: List[str]
-    diff_summary: str
-
-class VerificationEvidence(BaseModel):
-    __test__ = False  # Prevent pytest from collecting this as a test class
-    requirement_id: str
-    acceptance_criterion_id: str
-    command: str
-    status: Literal["passed", "failed", "not_run"]
-    evidence_summary: str
-
-# Backward-compatible alias
-TestEvidence = VerificationEvidence
+from pydantic import BaseModel, Field
+from typing import Literal, List, Dict
+
+class CommandResult(BaseModel):
+    command: str
+    exit_code: int
+    stdout_path: str
+    stderr_path: str
+    summary: str
+
+class DiffEvidence(BaseModel):
+    task_id: str
+    changed_files: List[str]
+    added_files: List[str]
+    deleted_files: List[str]
+    diff_summary: str
+
+class DiffCoverageEvidence(BaseModel):
+    """Proof that the changed lines were (or were not) exercised by the tests.
+
+    This is the executable evidence behind DevCouncil's core promise: a passing
+    suite is only acceptance evidence if the lines the diff changed were actually
+    run. ``measured`` is False when no reliable signal could be computed (no
+    coverage tool, no instrumentable test command, or no changed executable
+    lines), in which case it must never be read as a defect.
+    """
+
+    task_id: str
+    tool: str = ""
+    measured: bool = False
+    changed_lines: int = 0
+    covered_lines: int = 0
+    coverage_ratio: float = 0.0
+    uncovered_by_file: Dict[str, List[int]] = Field(default_factory=dict)
+    absent_files: List[str] = Field(default_factory=list)
+    summary: str = ""
+
+class VerificationEvidence(BaseModel):
+    __test__ = False  # Prevent pytest from collecting this as a test class
+    requirement_id: str
+    acceptance_criterion_id: str
+    command: str
+    status: Literal["passed", "failed", "not_run"]
+    evidence_summary: str
+
+# Backward-compatible alias
+TestEvidence = VerificationEvidence

package/src/devcouncil/domain/gap.py

@@ -1,26 +1,52 @@
-from pydantic import BaseModel, Field
-from typing import Literal, List, Optional
-
-class Gap(BaseModel):
-    id: str
-    severity: Literal["low", "medium", "high", "critical"]
-    gap_type: Literal[
-        "requirement_not_planned",
-        "task_not_implemented",
-        "planned_file_not_changed",
-        "orphan_diff",
-        "missing_test",
-        "test_failed",
-        "acceptance_criteria_unproven",
-        "assumption_violated",
-        "architecture_drift",
-        "security_risk",
-        "dependency_risk",
-        "migration_gap"
-    ]
-    requirement_id: Optional[str] = None
-    task_id: Optional[str] = None
-    description: str
-    evidence: List[str] = Field(default_factory=list)
-    recommended_fix: str
-    blocking: bool
+from pydantic import BaseModel, Field
+from typing import Literal, List, Optional
+
+class Gap(BaseModel):
+    id: str
+    severity: Literal["low", "medium", "high", "critical"]
+    gap_type: Literal[
+        "requirement_not_planned",
+        "task_not_implemented",
+        "planned_file_not_changed",
+        "orphan_diff",
+        "missing_test",
+        "test_failed",
+        "invalid_verification_command",
+        "acceptance_criteria_unproven",
+        "diff_not_exercised",
+        "assumption_violated",
+        "architecture_drift",
+        "security_risk",
+        "dependency_risk",
+        "migration_gap",
+        "quality_gate_failed",
+        "skipped_verification_command",
+        "coarse_acceptance_proof",
+    ]
+    requirement_id: Optional[str] = None
+    task_id: Optional[str] = None
+    description: str
+    evidence: List[str] = Field(default_factory=list)
+    recommended_fix: str
+    blocking: bool
+    # Machine-actionable hints for the agent self-repair loop. Populated at gap
+    # creation where known; consumed by the typed next-actions contract (see
+    # devcouncil.verification.next_actions). As of schema v4 these are persisted by
+    # the gap store and round-tripped on reload, so a reconnecting agent gets the
+    # full repair contract rather than a heuristic reconstruction.
+    file: Optional[str] = None
+    line: Optional[int] = None
+    suggested_command: Optional[str] = None
+    # The acceptance criterion this gap is about (when applicable), so the agent can
+    # tie a failure straight back to the criterion it must satisfy.
+    acceptance_criterion_id: Optional[str] = None
+    # Paths to the captured stdout/stderr logs (written under .devcouncil/logs) for the
+    # failing command behind this gap, so the agent can open the FULL failure output
+    # without re-running. Optional and defaulted for backward compatibility; the gap
+    # store does not persist these, so they are only present on a fresh verify run.
+    stdout_path: Optional[str] = None
+    stderr_path: Optional[str] = None
+    # Expected verification method (e.g. "unit_test"/"static_check") for an unproven
+    # acceptance criterion, so missing-evidence routing is concrete rather than a
+    # restatement of the description.
+    expected_verification_method: Optional[str] = None