devcouncil 0.3.1 → 0.4.0

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

@@ -0,0 +1,93 @@
+---
+name: devcouncil
+title: DevCouncil Integration for Claude Code
+description: Operate inside a DevCouncil-managed repo — use MCP tools and slash commands for status, scope, policy-gated writes, and evidence-first verification instead of guessing project state.
+triggers:
+  keywords: [devcouncil, dev council, devcouncil mcp, mcp devcouncil, dev integrate]
+  markers: [.devcouncil/config.yaml]
+---
+
+# DevCouncil Integration for Claude Code
+
+This repository is managed by **DevCouncil**: a planning, execution, and verification
+layer for coding agents. Evidence — not model confidence — decides when work is done.
+
+Use DevCouncil's MCP tools and `dev` CLI for project state, task scope, and verification.
+Do not guess at task status, file scope, or whether tests actually prove the diff.
+
+## Navigate before you edit
+
+1. Open `.devcouncil/repo_map.json` for subsystem entry points, critical files, and
+   cross-subsystem handoff paths. Regenerate with `dev map` after large refactors.
+2. Read `AGENTS.md` / `CLAUDE.md` for workspace conventions.
+3. Check status: `devcouncil_status` (MCP) or `/devcouncil:status` (slash command) or
+   `dev status` (CLI).
+
+## MCP tools vs CLI vs slash commands
+
+| Need | Prefer |
+|---|---|
+| Task loop (checkout, write, verify, release) | MCP tools (`mcp__devcouncil__devcouncil_*`) |
+| Quick human-readable status / reports | Slash commands (`/devcouncil:status`, `/devcouncil:report`) |
+| Scripting, CI, headless runs | `dev` CLI (`dev verify`, `dev go`, `dev e2e`) |
+| Read-only inspection (gaps, provenance, diff) | MCP read tools before re-running verify |
+
+MCP tool names in Claude Code are prefixed: `mcp__devcouncil__devcouncil_<name>`.
+
+## Slash commands (Claude Code)
+
+Install with `dev integrate claude --apply`. Commands live under `/devcouncil:*`:
+
+| Command | Purpose |
+|---|---|
+| `/devcouncil:status` | Phase, tasks, blocking gaps |
+| `/devcouncil:next` | Pick up the next unblocked task via MCP |
+| `/devcouncil:verify [TASK-ID]` | Run verification, report gaps |
+| `/devcouncil:repair [TASK-ID]` | Repair blocking gaps |
+| `/devcouncil:plan <goal>` | Plan a goal into requirements/tasks |
+| `/devcouncil:review [TASK-ID]` | Live-review critique cards |
+| `/devcouncil:report` | Full coverage report |
+| `/devcouncil:map [goal]` | Refresh/read the repo map |
+| `/devcouncil:wiki [topic]` | Consult the codebase wiki |
+| `/devcouncil:supervise [RUN-ID]` | Review a recorded agent run |
+
+## Key MCP tools (by role)
+
+**Orientation:** `devcouncil_status`, `devcouncil_report`, `devcouncil_integration_status`,
+`devcouncil_wiki_page`, `devcouncil_graph_context`
+
+**Task loop:** `devcouncil_next_task`, `devcouncil_checkout_task`, `devcouncil_get_task`,
+`devcouncil_get_prompt`, `devcouncil_release_task`, `devcouncil_renew_lease`
+
+**Policy-gated writes:** `devcouncil_write_file`, `devcouncil_apply_patch`,
+`devcouncil_policy_check_write` (preflight), `devcouncil_run_command`,
+`devcouncil_record_command`
+
+**Read-only inspection:** `devcouncil_read_file`, `devcouncil_get_diff`,
+`devcouncil_get_gaps`, `devcouncil_get_next_actions`, `devcouncil_get_evidence`,
+`devcouncil_get_task_provenance`
+
+**Verification:** `devcouncil_verify_task` (requires an active lease)
+
+**Live review:** `devcouncil_live_review`, `devcouncil_live_cards`,
+`devcouncil_live_repair_prompt`
+
+## Subagents
+
+When delegated, use the bundled subagents:
+
+- **devcouncil-implementer** — checkout → scoped edits → verify → release
+- **devcouncil-verifier** — read-only verification and gap reporting
+- **devcouncil-reviewer** — policy-aware diff review via live critique cards
+
+## Rules of engagement
+
+- **Scope:** edit only files declared in the task's planned scope. Out-of-scope or
+  protected paths are rejected by the write gate.
+- **Evidence:** run tests and call `devcouncil_verify_task` before claiming done.
+- **Leases:** one agent owns a task at a time; checkout before writes, release when verified.
+- **Repairs:** when gaps exist, read `devcouncil_get_next_actions` and act on each
+  typed action — do not declare success while blocking gaps remain.
+
+For the full autonomous loop, follow the **devcouncil-hero-loop** skill. For verifier
+gates and the next-actions contract, follow **devcouncil-verification**.

package/src/devcouncil/skills/registry.py

@@ -11,6 +11,7 @@ from __future__ import annotations
 
 import fnmatch
 import functools
+import logging
 import os
 import re
 from pathlib import Path
@@ -19,6 +20,8 @@ from pydantic import BaseModel, Field
 
 from devcouncil.knowledge.frontmatter import build_frontmatter_markdown, split_frontmatter
 
+logger = logging.getLogger(__name__)
+
 LIBRARY_DIR = Path(__file__).resolve().parent / "library"
 
 
@@ -50,6 +53,7 @@ _MAX_WALK_FILES = 20_000
 class SkillTriggers(BaseModel):
     keywords: list[str] = Field(default_factory=list)
     globs: list[str] = Field(default_factory=list)
+    markers: list[str] = Field(default_factory=list)
 
 
 class Skill(BaseModel):
@@ -61,7 +65,12 @@ class Skill(BaseModel):
     body: str = ""
     source_path: Path | None = None
 
-    def matches(self, goal: str, repo_files_present: "set[str] | None" = None) -> bool:
+    def matches(
+        self,
+        goal: str,
+        repo_files_present: "set[str] | None" = None,
+        project_root: Path | None = None,
+    ) -> bool:
         """True if this skill applies to the given goal text / repo file basenames."""
         if self.always:
             return True
@@ -73,9 +82,18 @@ class Skill(BaseModel):
                 pat = pattern.lower()
                 if any(fnmatch.fnmatch(name, pat) for name in repo_files_present):
                     return True
+        if project_root is not None:
+            for marker in self.triggers.markers:
+                if (project_root / marker).exists():
+                    return True
         return False
 
-    def relevance_score(self, goal: str, repo_files_present: "set[str] | None" = None) -> int:
+    def relevance_score(
+        self,
+        goal: str,
+        repo_files_present: "set[str] | None" = None,
+        project_root: Path | None = None,
+    ) -> int:
         """How strongly this skill applies — used to rank which skills ride inline before
         the size budget truncates. Goal-text keyword hits weigh more than file-glob
         presence; always-on skills sort first regardless."""
@@ -88,6 +106,8 @@ class Skill(BaseModel):
                 1 for pattern in self.triggers.globs
                 if any(fnmatch.fnmatch(name, pattern.lower()) for name in repo_files_present)
             )
+        if project_root is not None:
+            score += sum(1 for marker in self.triggers.markers if (project_root / marker).exists())
         return score
 
     def to_skill_md(self) -> str:
@@ -113,6 +133,7 @@ def _skill_from_meta(path: Path, meta: dict, body: str) -> Skill:
         triggers=SkillTriggers(
             keywords=list(triggers.get("keywords") or []),
             globs=list(triggers.get("globs") or []),
+            markers=list(triggers.get("markers") or []),
         ),
         body=body.strip(),
         source_path=path,
@@ -240,7 +261,9 @@ def load_skills(
                 # selection metadata when it doesn't declare its own — otherwise
                 # scaffolding a skill silently strips its `always`/triggers and the
                 # skill stops being selected (selection would return nothing).
-                has_own_triggers = bool(skill.triggers.keywords or skill.triggers.globs)
+                has_own_triggers = bool(
+                    skill.triggers.keywords or skill.triggers.globs or skill.triggers.markers
+                )
                 skill = skill.model_copy(update={
                     "always": skill.always or base.always,
                     "triggers": skill.triggers if has_own_triggers else base.triggers,
@@ -256,8 +279,8 @@ def load_skills(
             try:
                 from devcouncil.app.config import load_config
                 knowledge_dir = load_config(project_root).knowledge.directory
-            except Exception:
-                pass
+            except Exception as e:
+                logger.debug("Failed to load knowledge directory from config, using default: %s", e)
             for skill in load_okf_skills(project_root, directory=knowledge_dir):
                 # Only fill gaps: library + repo-local skills win on name conflict.
                 by_name.setdefault(skill.name, skill)
@@ -342,7 +365,7 @@ def select_skills(
     # Rank by relevance so the most applicable domain skill survives the inline budget on a
     # polyglot repo; always-on skills keep their leading position; ties break by name.
     scored = [
-        (s, score) for s in skills if (score := s.relevance_score(goal, repo_files)) > 0
+        (s, score) for s in skills if (score := s.relevance_score(goal, repo_files, project_root)) > 0
     ]
     scored.sort(key=lambda item: (not item[0].always, -item[1], item[0].name))
     return [skill for skill, _ in scored]
@@ -389,15 +412,23 @@ def scaffold_skills(project_root: Path, skills: list[Skill]) -> list[Path]:
     """
     written: list[Path] = []
     skills_root = project_root / ".claude" / "skills"
-    proot = project_root.resolve()
+    dev_skills_root = project_root / ".devcouncil" / "skills"
     for skill in skills:
-        # Don't re-materialize a skill that already lives inside this repo.
+        # Don't re-materialize a skill that already lives in a repo-local skill dir.
+        # Packaged library files inside a monorepo (e.g. src/.../skills/library/) still
+        # scaffold to .claude/skills/ — only skip when the source IS the destination.
         if skill.source_path is not None:
-            try:
-                skill.source_path.resolve().relative_to(proot)
+            src = skill.source_path.resolve()
+            skip = False
+            for base in (skills_root, dev_skills_root):
+                try:
+                    src.relative_to(base.resolve())
+                    skip = True
+                    break
+                except ValueError:
+                    continue
+            if skip:
                 continue
-            except ValueError:
-                pass
         target = skills_root / skill.name / "SKILL.md"
         content = skill.to_skill_md()
         if target.exists() and target.read_text(encoding="utf-8") == content:

package/src/devcouncil/storage/db.py

@@ -1,3 +1,4 @@
+import logging
 from collections import defaultdict
 from contextlib import contextmanager
 from datetime import datetime, timezone
@@ -10,6 +11,8 @@ from typing import Optional
 
 from devcouncil.storage.models import SchemaVersionModel
 
+logger = logging.getLogger(__name__)
+
 
 # v3: per-task indexes on the task/audit tables (task_id, lease status).
 # v4: machine-routable gap columns (file, line, suggested_command,
@@ -17,7 +20,15 @@ from devcouncil.storage.models import SchemaVersionModel
 # v5: partial unique index enforcing one ACTIVE lease per task (single-writer).
 # v6: gap column expected_verification_method (repair loop tells an executor-remediable
 #     "incomplete" from a manual/llm one across a reload).
-SCHEMA_VERSION = 6
+# v7: task columns agent_appended_expected_tests_json / agent_appended_allowed_commands_json
+#     (agent-negotiated scope extensions). These are NOT NULL with a scalar default, which
+#     the column migration now adds as ``ADD COLUMN ... NOT NULL DEFAULT <literal>`` —
+#     previously non-nullable additions were skipped entirely, so every SELECT on an
+#     existing database crashed with "no such column".
+# v8: optional task.priority column (high/medium/low planner hint).
+# v9: task column agent_appended_planned_files_json (lease-gated modify-op scope
+#     expansion so unwired_file / orphan_diff repairs can append the intended caller).
+SCHEMA_VERSION = 9
 
 
 # Module-level caches keyed by *resolved* paths so distinct project roots stay
@@ -42,8 +53,9 @@ def reset_db_cache() -> None:
     for db in _db_instances.values():
         try:
             db.engine.dispose()
-        except Exception:
-            pass
+        except Exception as e:
+            # A failed dispose can leave the SQLite file locked for later rebuilds.
+            logger.debug("Failed to dispose cached engine for %s: %s", db.db_path, e)
     _db_instances.clear()
     _dedup_done.clear()
 
@@ -126,13 +138,38 @@ class Database:
                     )
         _dedup_done.add(key)
 
+    @staticmethod
+    def _scalar_default_literal(column) -> Optional[str]:
+        """SQL literal for a column's scalar Python-side default, or None.
+
+        Only simple scalars (str/bool/int/float) are rendered — anything callable,
+        context-sensitive, or exotic returns None so the caller can skip the column
+        rather than emit wrong DDL."""
+        default = getattr(column, "default", None)
+        if default is None or getattr(default, "is_callable", False):
+            return None
+        arg = getattr(default, "arg", None)
+        if isinstance(arg, bool):
+            return "1" if arg else "0"
+        if isinstance(arg, (int, float)):
+            return str(arg)
+        if isinstance(arg, str):
+            escaped = arg.replace("'", "''")
+            return f"'{escaped}'"
+        return None
+
     def _create_missing_columns(self):
         # create_all never alters an existing table, so columns added to a model
         # later (e.g. the v4 gap routing columns) are missing on databases created by
         # an older version — and a SELECT of the model would then fail. Add any
-        # missing column as a nullable ADD COLUMN (the only shape SQLite can add in
-        # place without a table rewrite); non-nullable additions are intentionally
-        # skipped because existing rows could not satisfy them.
+        # missing column in place via ADD COLUMN: nullable columns as-is, and
+        # NON-nullable columns with a scalar default as
+        # ``NOT NULL DEFAULT <literal>`` (the shape SQLite accepts without a table
+        # rewrite — existing rows take the default). Previously non-nullable
+        # additions were skipped entirely, so a model gaining a required column
+        # (v7's agent_appended_*_json) crashed every SELECT on an existing database
+        # with "no such column". Non-nullable columns WITHOUT a scalar default are
+        # still skipped: existing rows could not satisfy them.
         inspector = inspect(self.engine)
         existing_tables = set(inspector.get_table_names())
         for table in SQLModel.metadata.sorted_tables:
@@ -140,13 +177,22 @@ class Database:
                 continue
             existing_cols = {col["name"] for col in inspector.get_columns(table.name)}
             for column in table.columns:
-                if column.name in existing_cols or not column.nullable:
+                if column.name in existing_cols:
                     continue
                 ddl_type = column.type.compile(self.engine.dialect)
-                stmt = text(f'ALTER TABLE "{table.name}" ADD COLUMN "{column.name}" {ddl_type}')
+                if column.nullable:
+                    ddl = f'ALTER TABLE "{table.name}" ADD COLUMN "{column.name}" {ddl_type}'
+                else:
+                    literal = self._scalar_default_literal(column)
+                    if literal is None:
+                        continue
+                    ddl = (
+                        f'ALTER TABLE "{table.name}" ADD COLUMN "{column.name}" '
+                        f"{ddl_type} NOT NULL DEFAULT {literal}"
+                    )
                 try:
                     with self.engine.begin() as conn:
-                        conn.execute(stmt)
+                        conn.execute(text(ddl))
                 except OperationalError as exc:
                     if "duplicate column name" not in str(exc).lower():
                         raise
@@ -194,8 +240,8 @@ def get_db(project_root: Path = Path(".")) -> Optional[Database]:
             return cached
         try:
             cached.engine.dispose()
-        except Exception:
-            pass
+        except Exception as e:
+            logger.debug("Failed to dispose stale cached engine for %s: %s", db_path, e)
 
     db = Database(db_path)
     db.ensure_schema_version()

package/src/devcouncil/storage/models.py

@@ -38,8 +38,14 @@ class TaskModel(SQLModel, table=True):
     acceptance_criterion_ids_json: str = Field(default="[]")
     planned_files_json: str = Field(default="[]")
     expected_tests_json: str = Field(default="[]")
+    agent_appended_expected_tests_json: str = Field(default="[]")
     allowed_commands_json: str = Field(default="[]")
+    agent_appended_allowed_commands_json: str = Field(default="[]")
+    agent_appended_planned_files_json: str = Field(default="[]")
     forbidden_changes_json: str = Field(default="[]")
+    # Manual/planner difficulty override ("easy"/"normal"/"hard"); None = estimator.
+    difficulty: Optional[str] = Field(default=None)
+    priority: Optional[str] = Field(default=None)
     status: str = "planned"
 
 class EvidenceModel(SQLModel, table=True):

package/src/devcouncil/storage/native.py

@@ -12,6 +12,8 @@ from pydantic import BaseModel
 from sqlalchemy.exc import IntegrityError
 from sqlmodel import Session, col, select
 
+from devcouncil.utils.json_persist import dump_json
+
 from devcouncil.storage.models import (
     AgentHandoffModel,
     CorrectionManifestModel,
@@ -386,7 +388,7 @@ class SemanticDiffRepository:
             task_id=task_id,
             before_snapshot_path=before_snapshot_path,
             after_snapshot_path=after_snapshot_path,
-            classifications_json=json.dumps(classifications),
+            classifications_json=dump_json(classifications),
             summary=summary,
             created_at=_utc_now(),
         )
@@ -518,8 +520,8 @@ class VerificationRunRepository:
             id=rid,
             task_id=task_id,
             sandbox=sandbox,
-            environment_json=json.dumps(environment),
-            commands_json=json.dumps(commands),
+            environment_json=dump_json(environment),
+            commands_json=dump_json(commands),
             status=status,
             started_at=_utc_now(),
             finished_at=finished_at,

package/src/devcouncil/storage/repositories.py

@@ -1,6 +1,7 @@
 from sqlmodel import Session, col, delete, select
 from typing import List, Optional, Any
 import json
+from devcouncil.utils.json_persist import dump_json
 from devcouncil.storage.models import (
     RequirementModel,
     AssumptionModel,
@@ -45,7 +46,7 @@ class RequirementRepository:
             description=req.description,
             priority=req.priority,
             source=req.source,
-            acceptance_criteria_json=json.dumps([ac.model_dump() for ac in req.acceptance_criteria])
+            acceptance_criteria_json=dump_json([ac.model_dump() for ac in req.acceptance_criteria])
         )
         self.session.merge(model)
         self.session.commit()
@@ -80,7 +81,7 @@ class AssumptionRepository:
             impact=assumption.impact,
             reversible=assumption.reversible,
             requires_user_confirmation=assumption.requires_user_confirmation,
-            linked_requirement_ids_json=json.dumps(assumption.linked_requirement_ids),
+            linked_requirement_ids_json=dump_json(assumption.linked_requirement_ids),
             status=assumption.status,
         )
         self.session.merge(model)
@@ -105,8 +106,19 @@ class TaskRepository:
             "acceptance_criterion_ids": json.loads(m.acceptance_criterion_ids_json),
             "planned_files": pf_list,
             "expected_tests": json.loads(m.expected_tests_json),
+            "agent_appended_expected_tests": json.loads(
+                getattr(m, "agent_appended_expected_tests_json", None) or "[]"
+            ),
             "allowed_commands": json.loads(m.allowed_commands_json),
+            "agent_appended_allowed_commands": json.loads(
+                getattr(m, "agent_appended_allowed_commands_json", None) or "[]"
+            ),
+            "agent_appended_planned_files": json.loads(
+                getattr(m, "agent_appended_planned_files_json", None) or "[]"
+            ),
             "forbidden_changes": json.loads(m.forbidden_changes_json),
+            "difficulty": getattr(m, "difficulty", None),
+            "priority": getattr(m, "priority", None),
             "status": m.status,
         })
 
@@ -124,8 +136,19 @@ class TaskRepository:
                 "acceptance_criterion_ids": json.loads(m.acceptance_criterion_ids_json),
                 "planned_files": pf_list,
                 "expected_tests": json.loads(m.expected_tests_json),
+                "agent_appended_expected_tests": json.loads(
+                    getattr(m, "agent_appended_expected_tests_json", None) or "[]"
+                ),
                 "allowed_commands": json.loads(m.allowed_commands_json),
+                "agent_appended_allowed_commands": json.loads(
+                    getattr(m, "agent_appended_allowed_commands_json", None) or "[]"
+                ),
+                "agent_appended_planned_files": json.loads(
+                    getattr(m, "agent_appended_planned_files_json", None) or "[]"
+                ),
                 "forbidden_changes": json.loads(m.forbidden_changes_json),
+                "difficulty": getattr(m, "difficulty", None),
+                "priority": getattr(m, "priority", None),
                 "status": m.status,
             }))
         return results
@@ -135,12 +158,17 @@ class TaskRepository:
             id=task.id,
             title=task.title,
             description=task.description,
-            requirement_ids_json=json.dumps(task.requirement_ids),
-            acceptance_criterion_ids_json=json.dumps(task.acceptance_criterion_ids),
-            planned_files_json=json.dumps([pf.model_dump() for pf in task.planned_files]),
-            expected_tests_json=json.dumps(task.expected_tests),
-            allowed_commands_json=json.dumps(task.allowed_commands),
-            forbidden_changes_json=json.dumps(task.forbidden_changes),
+            requirement_ids_json=dump_json(task.requirement_ids),
+            acceptance_criterion_ids_json=dump_json(task.acceptance_criterion_ids),
+            planned_files_json=dump_json([pf.model_dump() for pf in task.planned_files]),
+            expected_tests_json=dump_json(task.expected_tests),
+            agent_appended_expected_tests_json=dump_json(task.agent_appended_expected_tests),
+            allowed_commands_json=dump_json(task.allowed_commands),
+            agent_appended_allowed_commands_json=dump_json(task.agent_appended_allowed_commands),
+            agent_appended_planned_files_json=dump_json(task.agent_appended_planned_files),
+            forbidden_changes_json=dump_json(task.forbidden_changes),
+            difficulty=task.difficulty,
+            priority=task.priority,
             status=task.status
         )
         self.session.merge(model)
@@ -196,7 +224,7 @@ class GapRepository:
             requirement_id=gap.requirement_id,
             task_id=gap.task_id,
             description=gap.description,
-            evidence_json=json.dumps(gap.evidence),
+            evidence_json=dump_json(gap.evidence),
             recommended_fix=gap.recommended_fix,
             blocking=gap.blocking,
             file=gap.file,
@@ -360,7 +388,7 @@ class PlanningStateRepository:
                 description=req.description,
                 priority=req.priority,
                 source=req.source,
-                acceptance_criteria_json=json.dumps([ac.model_dump() for ac in req.acceptance_criteria]),
+                acceptance_criteria_json=dump_json([ac.model_dump() for ac in req.acceptance_criteria]),
             ))
 
         for assumption in assumptions:
@@ -371,7 +399,7 @@ class PlanningStateRepository:
                 impact=assumption.impact,
                 reversible=assumption.reversible,
                 requires_user_confirmation=assumption.requires_user_confirmation,
-                linked_requirement_ids_json=json.dumps(assumption.linked_requirement_ids),
+                linked_requirement_ids_json=dump_json(assumption.linked_requirement_ids),
                 status=assumption.status,
             ))
 
@@ -380,12 +408,16 @@ class PlanningStateRepository:
                 id=task.id,
                 title=task.title,
                 description=task.description,
-                requirement_ids_json=json.dumps(task.requirement_ids),
-                acceptance_criterion_ids_json=json.dumps(task.acceptance_criterion_ids),
-                planned_files_json=json.dumps([pf.model_dump() for pf in task.planned_files]),
-                expected_tests_json=json.dumps(task.expected_tests),
-                allowed_commands_json=json.dumps(task.allowed_commands),
-                forbidden_changes_json=json.dumps(task.forbidden_changes),
+                requirement_ids_json=dump_json(task.requirement_ids),
+                acceptance_criterion_ids_json=dump_json(task.acceptance_criterion_ids),
+                planned_files_json=dump_json([pf.model_dump() for pf in task.planned_files]),
+                expected_tests_json=dump_json(task.expected_tests),
+                agent_appended_expected_tests_json=dump_json(task.agent_appended_expected_tests),
+                allowed_commands_json=dump_json(task.allowed_commands),
+                agent_appended_allowed_commands_json=dump_json(task.agent_appended_allowed_commands),
+                agent_appended_planned_files_json=dump_json(task.agent_appended_planned_files),
+                forbidden_changes_json=dump_json(task.forbidden_changes),
+                difficulty=task.difficulty,
                 status=task.status,
             ))
 
@@ -455,7 +487,7 @@ class StateRepository:
             state = ProjectStateModel(
                 id="singleton",
                 current_phase=state,
-                history_json=json.dumps(history or []),
+                history_json=dump_json(history or []),
             )
         self.session.merge(state)
         self.session.commit()

package/src/devcouncil/telemetry/context.py

@@ -0,0 +1,28 @@
+"""Process-wide run attribution for telemetry.
+
+Every model_calls.jsonl record has a ``run_id`` field, but historically it was
+None on 100% of real records: the LLM router accepts ``run_id`` per call, and
+none of the planning/verification services threaded it through. Rather than
+touching every call site (and every future one), the orchestrator declares the
+current run here and the router falls back to it when a caller doesn't pass one
+explicitly.
+
+A ``ContextVar`` (not a bare global) so concurrent runs in one process — e.g.
+an MCP server planning two projects — attribute calls to their own run.
+"""
+
+from __future__ import annotations
+
+from contextvars import ContextVar
+from typing import Optional
+
+_current_run_id: ContextVar[Optional[str]] = ContextVar("devcouncil_run_id", default=None)
+
+
+def set_current_run_id(run_id: Optional[str]) -> None:
+    """Declare the run all subsequent (context-local) model calls belong to."""
+    _current_run_id.set(run_id)
+
+
+def get_current_run_id() -> Optional[str]:
+    return _current_run_id.get()

package/src/devcouncil/telemetry/cost.py

@@ -1,5 +1,6 @@
 import json
 import logging
+import os
 from pathlib import Path
 from typing import Any, Dict, List
 
@@ -45,6 +46,9 @@ class CostEstimator:
 
 
 def _model_calls_file(project_root: Path) -> Path:
+    override = os.environ.get("DEVCOUNCIL_LOG_DIR")
+    if override:
+        return Path(override) / "model_calls.jsonl"
     return project_root / ".devcouncil" / "logs" / "model_calls.jsonl"
 
 
@@ -133,8 +137,3 @@ def group_cost(project_root: Path) -> Dict[str, Any]:
         "by_task": _group(records, "task_id"),
         "by_run": _group(records, "run_id"),
     }
-
-
-def cost_by_task(project_root: Path) -> Dict[str, Dict[str, Any]]:
-    """Convenience accessor for the per-task cost breakdown (used by ``dev status``)."""
-    return group_cost(project_root)["by_task"]