devcouncil 0.2.0 → 0.3.1

package/README.md

@@ -25,6 +25,7 @@ DevCouncil does not replace coding agents. It sits beside tools like Codex CLI,
 - [Executor adapters](docs/executor-adapters.md): manual, coding CLI, native-preview, Mini-SWE, and OpenHands execution paths.
 - [Live review](docs/live-review.md): `dev watch` session review, cards, signals, and blocking behavior.
 - [Model routing](docs/model-routing.md): provider selection, role models, OpenRouter, Vertex AI, Doubleword, and Ollama (local) setup.
+- [Knowledge formats](docs/knowledge-formats.md): Open Knowledge Format (OKF) export/ingest/browse (`dev okf html` renders a bundle as a self-contained static HTML site) and design.md design-system lint/export plus `dev design check` (a CI-friendly gate that fails on hardcoded color/spacing/typography literals bypassing the tokens), injected as planning and coding context, plus the bidirectional OKF <-> engineering-skills bridge (`dev okf export --skills` / `dev okf ingest`).
 - [Security model](docs/security.md): redaction, permissions, allowlists, and local state.
 - [Project status](docs/project-status.md): current maturity by subsystem.
 - [Roadmap](docs/roadmap.md): planned work.
@@ -226,11 +227,21 @@ DevCouncil stores local workflow state in the target repository:
 - `.devcouncil/repo_map.json`: generated repository map and subsystem navigation index.
 - `.devcouncil/state.sqlite`: SQLite state for requirements, assumptions, tasks, evidence, gaps, critique findings, and project phase history.
 - `.devcouncil/checkpoints/`: task snapshots used by verification and rollback.
-- `.devcouncil/logs/`: redacted stdout/stderr from verification commands.
+- `.devcouncil/logs/`: the durable run log (`devcouncil.log`, rotating, DEBUG-level) plus redacted stdout/stderr from verification commands.
+- `.devcouncil/runs/<run-id>/run.log`: the full per-run log isolated to a single executor run.
 - `.devcouncil/runs/<run-id>/agent-run.json`: prompt, executor, profile, exit status, and run metadata for automated agent executions.
 - `.devcouncil/reports/latest.json`: optional machine-readable report generated by `dev e2e --agent`.
 - `.devcouncil/integrations/` and `.agents/`: generated integration files such as Warp/Oz MCP JSON and Antigravity MCP config.
 
+### Logging & diagnostics
+
+Every command logs each stage and step. The full DEBUG trail always lands in `.devcouncil/logs/devcouncil.log` (rotating), each executor run also gets an isolated `.devcouncil/runs/<run-id>/run.log`, and uncaught crashes are captured there with a full traceback. The console stays quiet by default — raise it per command:
+
+- `dev <command> -v` (INFO) or `-vv` (DEBUG); `-q` for errors only; `--log-level DEBUG`. The `DEVCOUNCIL_LOG_LEVEL` env var sets a default.
+- `dev logs tail [-n N] [-f] [--grep TEXT]` — read/follow/filter the shared log.
+- `dev logs tail --run <run-id>` — read one run's log; `dev logs runs` lists them; `dev logs path` prints the location.
+- `dev doctor` reports the log location and size.
+
 ### Maturity
 
 The stable daily workflow is planning, manual sidecar execution, verification, repair, rollback, and reporting. Coding CLI executors, MCP, live review, dashboard, PR comments, LSP/AST tools, and GitHub check surfaces are preview features. Native autonomous execution is experimental and still requires DevCouncil verification before work is considered complete.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devcouncil",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Gated orchestrator for AI-assisted software development",
   "license": "Apache-2.0",
   "homepage": "https://github.com/bharathvbcr/DevCouncil#readme",

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "devcouncil"
-version = "0.2.0"
+version = "0.3.1"
 description = "Gated orchestrator for AI-assisted software development"
 readme = "README.md"
 requires-python = ">=3.12"

package/src/devcouncil/app/config.py

@@ -5,18 +5,37 @@ Replaces scattered yaml.safe_load() calls with a single validated config service
 
 from __future__ import annotations
 
+import logging
 import os
 import shutil
 import subprocess
+import time
 from pathlib import Path
-from typing import Dict, List
+from typing import Dict, List, Optional, Tuple
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, field_validator
+
+logger = logging.getLogger(__name__)
 
 
 class ModelRoleConfig(BaseModel):
     model: str
     temperature: float = 0.0
+    # Optional per-role provider override. When unset, the role uses
+    # ``models.provider``. Lets a single run route some roles to one provider
+    # (e.g. planning on OpenRouter) and others to another (e.g. live review on
+    # local Ollama). Validated/normalized against the supported provider list.
+    provider: str | None = None
+
+    @field_validator("provider")
+    @classmethod
+    def _normalize_provider(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        # Lazy import avoids a circular import (llm.provider imports app.config).
+        from devcouncil.llm.provider import validate_model_provider
+
+        return validate_model_provider(value)
 
 
 class ModelsConfig(BaseModel):
@@ -59,9 +78,54 @@ class DiffCoverageConfig(BaseModel):
     min_ratio: float = 0.0
 
 
+class AcceptanceCheckConfig(BaseModel):
+    """Tuning for DevCouncil's per-criterion compiled acceptance checks.
+
+    These default to single-shot behavior (``samples=1``, ``repair_attempts=1``)
+    so a strong cloud model is unaffected. They exist to make a WEAK/LOCAL model
+    (e.g. an Ollama reviewer) trustworthy: such a model frequently emits a check
+    that does not run (wrong import, broken one-liner) — recorded as ``incomplete``
+    — or a single mis-asserting check that false-``blocked`` correct code.
+
+    - ``repair_attempts``: when a compiled check FAILS TO RUN (malformed/unrunnable,
+      proves nothing), feed the error back and regenerate the COMMAND up to this many
+      times. Safe by construction — a check that never ran cannot weaken the gate.
+    - ``samples``: generate this many INDEPENDENT checks per criterion and decide by
+      majority vote (proven iff a strict majority pass; unanimous-fail blocks; a split
+      stays unproven with a non-blocking advisory). Local sampling is cost-free, so
+      raising this (e.g. 3) outvotes a single mis-generated check without ever
+      auto-passing a real defect. ``1`` reproduces today's single-check behavior.
+    """
+
+    samples: int = 1
+    repair_attempts: int = 1
+    # Compile one criterion per model call instead of batching them all into a single
+    # prompt. A weak/local model batching N criteria into one JSON routinely omits or
+    # mis-attributes some (a false "incomplete"); a focused single-criterion prompt is far
+    # more reliable. Costs N× the calls — cheap on a local monitor, so opt-in. Off keeps
+    # the single batched call.
+    per_criterion: bool = False
+
+
+class ReviewerCheckConfig(BaseModel):
+    """Self-consistency voting for the LLM live reviewer.
+
+    A weak/local reviewer can emit a lone, mis-calibrated "Critical Issues" verdict that
+    falsely BLOCKS (the live card becomes a blocking gap). Sampling ``samples`` independent
+    reviews and majority-voting the verdict outvotes a single bad judgment: the gate only
+    escalates to the blocking verdict when a strict majority agree; a split de-escalates to
+    the non-blocking "Concerns". ``samples=1`` reproduces today's single-review behavior, so
+    a strong cloud model is unaffected. Local sampling is cost-free — raise it (e.g. 3) there.
+    """
+
+    samples: int = 1
+
+
 class VerificationConfig(BaseModel):
     sandbox: VerificationSandboxConfig = Field(default_factory=VerificationSandboxConfig)
     diff_coverage: DiffCoverageConfig = Field(default_factory=DiffCoverageConfig)
+    acceptance_checks: AcceptanceCheckConfig = Field(default_factory=AcceptanceCheckConfig)
+    reviewer_checks: ReviewerCheckConfig = Field(default_factory=ReviewerCheckConfig)
 
 
 class GatesConfig(BaseModel):
@@ -88,6 +152,13 @@ class ExecutionConfig(BaseModel):
     verify_on_post_task: bool = False
     cursor_resume_mode: str = "off"
     coding_cli_probe_order: List[str] = Field(default_factory=list)
+    # Opt-in scope gate for executors WITHOUT a pre-write hook (CLI subprocesses that write
+    # directly to disk). When true, DevCouncil re-checks every file a coding-CLI subprocess
+    # changed against the task's authorization right after it exits and REVERTS any the task
+    # did not allow — so unplanned drift never reaches the verify gate or a commit, instead
+    # of only being flagged post-verify by orphan_diff. Off by default (it reverts the
+    # agent's writes; teams opt in once their plans declare planned_files reliably).
+    enforce_file_scope_pre_verify: bool = False
 
 
 class PrivacyConfig(BaseModel):
@@ -200,6 +271,23 @@ class IntegrationsConfig(BaseModel):
     cli_agents: CliAgentsIntegrationConfig = Field(default_factory=CliAgentsIntegrationConfig)
 
 
+class KnowledgeConfig(BaseModel):
+    """Ingested knowledge (Open Knowledge Format bundles + a project design.md) that gets
+    injected into planning/council/task prompts.
+
+    Sources live under ``<directory>/{okf,design}``. A design system is always selected
+    (``design_always``) because a coding agent should honor it on every UI task; OKF
+    knowledge is selected by goal keywords / document tags. The ``*_max_chars`` budgets
+    bound how much rides inline so a large knowledge base can't crowd out file context.
+    """
+
+    enabled: bool = True
+    directory: str = ".devcouncil/knowledge"
+    design_always: bool = True
+    okf_max_chars: int = 3000
+    design_max_chars: int = 4000
+
+
 class ProviderConfig(BaseModel):
     sort: str = "price"
     allow_fallbacks: bool = True
@@ -219,29 +307,59 @@ class DevCouncilConfig(BaseModel):
     verification: VerificationConfig = Field(default_factory=VerificationConfig)
     privacy: PrivacyConfig = Field(default_factory=PrivacyConfig)
     integrations: IntegrationsConfig = Field(default_factory=IntegrationsConfig)
+    knowledge: KnowledgeConfig = Field(default_factory=KnowledgeConfig)
+
+
+# Memoized parsed configs keyed by resolved config path. Each entry stores the
+# file's stat signature (mtime_ns, size, inode) so a rewritten config.yaml — common in
+# tests that mutate config mid-process, including delete+recreate — is re-read instead
+# of served stale.
+_CONFIG_CACHE: Dict[Path, Tuple[Tuple[int, int, int], DevCouncilConfig]] = {}
 
 
 def load_config(project_root: Path = Path(".")) -> DevCouncilConfig:
     """Load and validate .devcouncil/config.yaml.
-    
+
     Returns DevCouncilConfig with defaults for any missing fields.
     Raises FileNotFoundError if config doesn't exist.
+
+    Parsed results are memoized per resolved config path and invalidated when the
+    file's mtime/size changes, so repeated callers avoid redundant disk reads while
+    still picking up a rewritten config.
     """
     import yaml  # type: ignore[import-untyped]
 
     config_path = project_root / ".devcouncil" / "config.yaml"
-    if not config_path.exists():
+    try:
+        stat = config_path.stat()
+    except FileNotFoundError:
         raise FileNotFoundError(f"Config not found at {config_path}. Run 'dev init' first.")
 
+    cache_key = config_path.resolve()
+    # Include the inode so a delete+recreate under the same path (new inode) is treated
+    # as changed even if the rewritten file lands with the same mtime and size.
+    signature = (stat.st_mtime_ns, stat.st_size, stat.st_ino)
+    cached = _CONFIG_CACHE.get(cache_key)
+    if cached is not None and cached[0] == signature:
+        # The cached instance is shared across callers; treat it as read-only. Nothing
+        # in the codebase mutates a loaded DevCouncilConfig (settings are rewritten on
+        # disk via the raw-config helpers, then re-read), so we avoid a per-call copy.
+        return cached[1]
+
+    logger.debug("Loading config from %s", config_path)
     with open(config_path, encoding="utf-8") as f:
         try:
             raw = yaml.safe_load(f) or {}
         except yaml.YAMLError as exc:
+            logger.error("Invalid YAML in %s: %s", config_path, exc)
             raise ValueError(
                 f"Invalid YAML in {config_path}: {exc}. Fix the syntax or re-run 'dev init'."
             ) from exc
 
-    return DevCouncilConfig.model_validate(raw)
+    config = DevCouncilConfig.model_validate(raw)
+    _CONFIG_CACHE[cache_key] = (signature, config)
+    logger.debug("Config loaded: provider=%s", config.models.provider)
+    return config
 
 
 def provider_api_key_env_var(provider: str = "openrouter") -> str:
@@ -261,11 +379,27 @@ def _normalized_provider_name(provider: str) -> str:
     return provider.strip().lower().replace("-", "").replace("_", "")
 
 
+# Memoized parsed secrets keyed by resolved secrets path, with the same
+# stat-signature (mtime_ns, size) invalidation as load_config.
+_SECRETS_CACHE: Dict[Path, Tuple[Tuple[int, int, int], Dict[str, str]]] = {}
+
+
 def load_local_secrets(project_root: Path = Path(".")) -> Dict[str, str]:
     secrets_path = project_root / ".devcouncil" / "secrets.env"
-    if not secrets_path.exists():
+    try:
+        stat = secrets_path.stat()
+    except FileNotFoundError:
         return {}
 
+    cache_key = secrets_path.resolve()
+    # Include the inode so a delete+recreate under the same path (new inode) is treated
+    # as changed even if the rewritten file lands with the same mtime and size.
+    signature = (stat.st_mtime_ns, stat.st_size, stat.st_ino)
+    cached = _SECRETS_CACHE.get(cache_key)
+    if cached is not None and cached[0] == signature:
+        # Copy so callers can't mutate the cached mapping.
+        return dict(cached[1])
+
     secrets: Dict[str, str] = {}
     for line in secrets_path.read_text(encoding="utf-8").splitlines():
         stripped = line.strip()
@@ -273,10 +407,18 @@ def load_local_secrets(project_root: Path = Path(".")) -> Dict[str, str]:
             continue
         key, value = stripped.split("=", 1)
         secrets[key.strip()] = value.strip().strip('"').strip("'")
+    _SECRETS_CACHE[cache_key] = (signature, dict(secrets))
     return secrets
 
 
 def get_gcloud_access_token() -> str | None:
+    """Fetch a fresh gcloud access token by shelling out to ``gcloud``.
+
+    This always spawns the subprocess (no caching) so callers that need a guaranteed
+    fresh token — e.g. the Vertex provider refreshing after a 401/403 — get one. For
+    the hot path (per-provider-construction key lookups) use
+    :func:`get_cached_gcloud_access_token`, which memoizes the result with a TTL.
+    """
     executable = shutil.which("gcloud")
     if not executable:
         return None
@@ -294,6 +436,37 @@ def get_gcloud_access_token() -> str | None:
     return token or None
 
 
+# Cached gcloud access token + monotonic expiry. gcloud tokens last ~60 min, so the
+# hot path (a fresh provider per role/run calling get_api_key) reuses a fetched token
+# for a conservative window instead of spawning ``gcloud auth print-access-token`` on
+# every lookup. A single gcloud identity is assumed, so no cache key is needed. A
+# failed fetch (None) is never cached.
+_GCLOUD_TOKEN_TTL_SECONDS = 50 * 60
+_gcloud_token_cache: Optional[Tuple[str, float]] = None
+
+
+def get_cached_gcloud_access_token() -> str | None:
+    """Return a gcloud access token, reusing a recent one within the TTL window.
+
+    Falls back to :func:`get_gcloud_access_token` on a cache miss/expiry. ``gcloud``
+    absence is checked first so an environment without gcloud short-circuits to None
+    without ever consulting the cache (preserving the uncached error/None behavior).
+    """
+    global _gcloud_token_cache
+
+    if shutil.which("gcloud") is None:
+        return None
+
+    cached = _gcloud_token_cache
+    if cached is not None and time.monotonic() < cached[1]:
+        return cached[0]
+
+    token = get_gcloud_access_token()
+    if token:
+        _gcloud_token_cache = (token, time.monotonic() + _GCLOUD_TOKEN_TTL_SECONDS)
+    return token
+
+
 def get_api_key(provider: str = "openrouter", project_root: Path = Path(".")) -> str:
     """Retrieve the API key for the configured provider from environment.
     
@@ -302,12 +475,13 @@ def get_api_key(provider: str = "openrouter", project_root: Path = Path(".")) ->
     env_var = provider_api_key_env_var(provider)
     key = os.environ.get(env_var) or load_local_secrets(project_root).get(env_var)
     if not key and _normalized_provider_name(provider) == "vertexai":
-        key = get_gcloud_access_token()
+        key = get_cached_gcloud_access_token()
     if not key and _normalized_provider_name(provider) == "ollama":
         # Ollama is a local server and needs no API key; an explicitly-set
         # OLLAMA_API_KEY still flows through above if present.
         return ""
     if not key:
+        logger.warning("API key not found for provider %s (env var %s)", provider, env_var)
         extra = (
             " You can also authenticate with 'gcloud auth login' for vertexai."
             if _normalized_provider_name(provider) == "vertexai"

package/src/devcouncil/app/orchestrator.py

@@ -18,9 +18,13 @@ class Orchestrator:
         self.project_root = project_root
         self.persist_state = persist_state
         
-        db = get_db(self.project_root)
-        if db:
-            with db.get_session() as session:
+        # Cache the Database handle once: get_db() rebuilds the SQLAlchemy engine
+        # and runs a schema check on every call, and transition_to() is invoked
+        # several times per run. The handle is reusable, so build it here and
+        # reuse it everywhere in this orchestrator instance.
+        self.db = get_db(self.project_root)
+        if self.db:
+            with self.db.get_session() as session:
                 repo = StateRepository(session)
                 state = repo.get_state()
                 if state:
@@ -45,6 +49,7 @@ class Orchestrator:
             goal=goal
         )
         self.current_run.initialize()
+        logger.info("Run started: run_id=%s goal=%r", run_id, goal)
         TraceLogger(self.project_root).log_event(
             "planning_started",
             {"goal": goal},
@@ -60,9 +65,8 @@ class Orchestrator:
         old_phase = self.state_machine.phase
         self.state_machine.transition(target_phase)
         
-        db = get_db(self.project_root)
-        if db and self.persist_state:
-            with db.get_session() as session:
+        if self.db and self.persist_state:
+            with self.db.get_session() as session:
                 repo = StateRepository(session)
                 repo.save_state(
                     self.state_machine.phase.value,

package/src/devcouncil/app/state_machine.py

@@ -9,9 +9,12 @@ States (from §12):
 
 from __future__ import annotations
 
+import logging
 from enum import Enum
 from typing import Dict, List, Set
 
+logger = logging.getLogger(__name__)
+
 
 
 class ProjectPhase(str, Enum):
@@ -99,6 +102,7 @@ class StateMachine:
         Raises InvalidTransitionError if the transition is not allowed.
         """
         if not self.can_transition(target):
+            logger.error("Invalid phase transition: %s -> %s", self._phase.value, target.value)
             raise InvalidTransitionError(self._phase, target)
         self._phase = target
         self._history.append(target)

package/src/devcouncil/artifacts/graph.py

@@ -144,6 +144,13 @@ class ArtifactGraph:
 
     def coverage_summary(self) -> Dict[str, Any]:
         """Produce a coverage summary for reporting."""
+        # Single pass over open findings; the "high"-filtered count reuses the same
+        # severity_order/rank predicate as open_findings("high") (rank >= 2).
+        all_open = self.open_findings()
+        severity_order = {"low": 0, "medium": 1, "high": 2, "critical": 3}
+        high_critical_open = sum(
+            1 for f in all_open if severity_order.get(f.severity, 0) >= severity_order["high"]
+        )
         return {
             "total_requirements": len(self.requirements),
             "requirements_without_tasks": len(self.requirements_without_tasks()),
@@ -157,7 +164,7 @@ class ArtifactGraph:
             "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")),
+            "open_findings": len(all_open),
+            "high_critical_open_findings": high_critical_open,
             "unconfirmed_high_assumptions": len(self.unconfirmed_high_impact_assumptions()),
         }

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

@@ -11,6 +11,7 @@ from __future__ import annotations
 
 import asyncio
 import json
+import logging
 import subprocess
 from pathlib import Path
 
@@ -30,6 +31,7 @@ from devcouncil.verification.implementation_reviewer import ImplementationReview
 from devcouncil.verification.verifier import Verifier
 
 console = Console()
+logger = logging.getLogger(__name__)
 
 
 def _diff(root: Path, base: str | None) -> str:
@@ -55,6 +57,8 @@ def check(
 ):
     """Audit the current changes — scope, risks, missing edge cases, secrets — no planning required."""
     root = project_root.expanduser().resolve()
+    from devcouncil.telemetry.logging_setup import set_log_dir
+    set_log_dir(root)
     initialize_project(root, quiet=True)
 
     # A --goal of "#142" or a GitHub issue/PR URL is a reference, not a spec —
@@ -85,14 +89,18 @@ def check(
 
     verifier = Verifier(root)
 
+    logger.info("dev check (LLM audit): base=%s goal=%s", base or "working-tree", "set" if goal else "none")
     diff = _diff(root, base)
     if not diff.strip():
+        logger.info("dev check: clean working tree; nothing to audit")
         msg = "No changes to check (clean working tree)."
         typer.echo(json.dumps({"ok": True, "message": msg}) if json_format else msg)
         return
 
     changed_files = verifier.get_changed_files()
     secret_gaps = verifier.secret_scanner.scan_diff(diff, "check")
+    if secret_gaps:
+        logger.warning("dev check: %d possible secret(s) in diff across %d changed file(s)", len(secret_gaps), len(changed_files))
 
     # Blast radius: what do the changed files ripple into? Surfaced from the
     # structural graph when the code-review-graph integration is enabled, so a
@@ -105,7 +113,7 @@ def check(
         config = load_config(root)
         validate_model_provider(config.models.provider)
         api_key = get_api_key(config.models.provider, root)
-        provider = create_provider(config.models.provider, api_key, project_root=root)
+        provider = create_provider(config.models.provider, api_key, project_root=root, provider_prefs=config.provider)
         role_config = {name: role.model_dump() for name, role in config.models.roles.items()}
         router = ModelRouter(provider, role_config, project_root=root)
         synthetic = Task(
@@ -120,9 +128,12 @@ def check(
         review = asyncio.run(ImplementationReviewer(router).review_changes(synthetic, [], diff))
         findings = review.findings
     except (ProviderRequestError, StructuredOutputError) as exc:
+        logger.warning("dev check: LLM review unavailable: %s", exc)
         review_note = f"LLM review unavailable: {exc}"
     except Exception as exc:  # pragma: no cover - best effort
+        logger.warning("dev check: LLM review unavailable: %s", exc)
         review_note = f"LLM review unavailable: {exc}"
+    logger.info("dev check audit complete: %d secret finding(s), %d review finding(s)", len(secret_gaps), len(findings))
 
     if json_format:
         typer.echo(json.dumps({