devcouncil 0.2.0 → 0.3.0

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

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import json
 import asyncio
+import logging
 import time
 from pathlib import Path
 
@@ -32,6 +33,7 @@ from devcouncil.telemetry.traces import TraceLogger
 
 app = typer.Typer(help="Review active coding-agent sessions and emit critique cards.")
 console = Console()
+logger = logging.getLogger(__name__)
 
 
 @app.command("sessions")
@@ -72,6 +74,9 @@ def review(
 ):
     """Review the latest assistant response in a coding-agent transcript."""
     root = project_root.expanduser().resolve()
+    from devcouncil.telemetry.logging_setup import set_log_dir
+    set_log_dir(root)
+    logger.info("dev watch review: client=%s llm=%s", client, llm)
     transcript_path = _resolve_transcript(root, client, transcript=transcript, session=session, latest=latest)
     if transcript_path is None:
         message = "No transcript selected. Use --transcript, --session, or --latest."
@@ -91,6 +96,7 @@ def review(
 
     scoped_task_id = task_id or active_task_id(root)
     card = asyncio.run(_review_turn(turn, root, client, llm, task_id=scoped_task_id))
+    logger.info("dev watch review: card %s verdict=%s task=%s", card.id, card.verdict, scoped_task_id or "(unscoped)")
     saved_path, duplicate = _save_card_once(root, card, persist=persist, force=force)
     if saved_path:
         _log_card_reviewed(root, card, saved_path, duplicate=duplicate, source="review")
@@ -279,10 +285,13 @@ def repair_all(
     """Generate repair prompts for all blocking live-review cards in scope."""
     root = project_root.expanduser().resolve()
     summary = live_review_summary(root, task_id=task_id)
+    all_cards = {card.id: card for card in load_cards(root)}
+    # Guard the membership test with isinstance(str): a malformed (non-hashable) id would
+    # otherwise raise TypeError on `in`, whereas the old per-id lookup just skipped it.
     cards = [
-        get_card(root, item["id"])
+        all_cards[item["id"]]
         for item in summary["blocking_cards"]
-        if isinstance(item.get("id"), str)
+        if isinstance(item.get("id"), str) and item["id"] in all_cards
     ]
     resolved_cards = [card for card in cards if card is not None]
     prompt = build_bulk_live_repair_prompt(root, resolved_cards)
@@ -331,6 +340,10 @@ def pending(
 ):
     """Review every pending response-ready signal that includes a transcript path."""
     root = project_root.expanduser().resolve()
+    from devcouncil.telemetry.logging_setup import set_log_dir
+    set_log_dir(root)
+    logger.info("dev watch pending: reviewing signals (client=%s, llm=%s)", client or "all", llm)
+    fallback_task_id = active_task_id(root)
     reviewed = []
     skipped = []
     for signal in _filtered_signals(root, client):
@@ -342,7 +355,7 @@ def pending(
         if turn is None:
             skipped.append({"signal": signal.model_dump(), "reason": f"No assistant turn found in {transcript_path}."})
             continue
-        scoped_task_id = task_id or signal.task_id or active_task_id(root)
+        scoped_task_id = task_id or signal.task_id or fallback_task_id
         card = asyncio.run(_review_turn(turn, root, signal.client, llm, task_id=scoped_task_id))
         saved_path, duplicate = _save_card_once(root, card, persist=True, force=force)
         if saved_path:
@@ -363,6 +376,7 @@ def pending(
             else:
                 console.print(f"[green]Saved critique card:[/green] {saved_path}")
 
+    logger.info("dev watch pending complete: %d reviewed, %d skipped", len(reviewed), len(skipped))
     if json_format:
         typer.echo(json.dumps({"reviewed": reviewed, "skipped": skipped}, indent=2))
         return
@@ -385,11 +399,15 @@ def follow(
 ):
     """Poll a transcript and emit a critique card whenever the latest assistant turn changes."""
     root = project_root.expanduser().resolve()
+    from devcouncil.telemetry.logging_setup import set_log_dir
+    set_log_dir(root)
     transcript_path = _resolve_transcript(root, client, transcript=transcript, session=session, latest=latest)
     if transcript_path is None:
+        logger.warning("dev watch follow: no transcript selected")
         console.print("[red]No transcript selected. Use --transcript, --session, or --latest.[/red]")
         raise typer.Exit(code=2)
     seen_turn_id: str | None = None
+    logger.info("dev watch follow: watching %s (client=%s, interval=%ss, llm=%s)", transcript_path, client, interval, llm)
     console.print(f"[cyan]Watching transcript:[/cyan] {transcript_path}")
     while True:
         turn = latest_assistant_turn(transcript_path, client=client)
@@ -397,6 +415,7 @@ def follow(
             seen_turn_id = turn.turn_id
             scoped_task_id = task_id or active_task_id(root)
             card = asyncio.run(_review_turn(turn, root, client, llm, task_id=scoped_task_id))
+            logger.info("dev watch follow: new turn %s → card %s verdict=%s", turn.turn_id, card.id, card.verdict)
             saved_path, duplicate = _save_card_once(root, card, persist=True, force=force)
             if saved_path:
                 _log_card_reviewed(root, card, saved_path, duplicate=duplicate, source="follow")
@@ -564,10 +583,11 @@ async def _review_turn(turn, root: Path, client: str, use_llm: bool, task_id: st
         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)
     except Exception as exc:
+        logger.warning("Model-backed live review unavailable; using deterministic card: %s", exc)
         console.print(f"[yellow]Model-backed review unavailable; using deterministic card: {exc}[/yellow]")
         return review_turn(turn, root, client=client, task_id=task_id)
     card = await LiveReviewService(router).review(turn, root, client=client, use_llm=True)

package/src/devcouncil/cli/main.py

@@ -37,14 +37,17 @@ from devcouncil.cli.commands import (  # noqa: E402 - imports follow stdio recon
     cost,
     ast,
     dashboard,
+    design,
     doctor,
     go,
     hook,
     init,
     integrate,
+    logs,
     lsp,
     map,
     mcp_server,
+    okf,
     plan,
     prompt,
     repair,
@@ -91,6 +94,7 @@ 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(logs.app, name="logs")
 app.add_typer(cost.app, name="cost")
 app.add_typer(runs.app, name="runs")
 app.add_typer(setup.app, name="setup")
@@ -101,6 +105,8 @@ 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")
+app.add_typer(okf.app, name="okf")
+app.add_typer(design.app, name="design")
 watch.app.command("fs")(watch_fs)
 
 # Direct command registrations (those defined as def cmd())
@@ -127,10 +133,39 @@ app.command(name="status")(status.status)
 app.command(name="optimize")(agents.optimize_agent)
 
 @app.callback()
-def main(ctx: typer.Context):
+def main(
+    ctx: typer.Context,
+    verbose: int = typer.Option(
+        0,
+        "--verbose",
+        "-v",
+        count=True,
+        help="Increase console log verbosity (-v INFO, -vv DEBUG). Everything is "
+        "always captured at DEBUG in .devcouncil/logs/devcouncil.log.",
+    ),
+    quiet: bool = typer.Option(
+        False,
+        "--quiet",
+        "-q",
+        help="Only show errors on the console (the log file still captures everything).",
+    ),
+    log_level: str = typer.Option(
+        None,
+        "--log-level",
+        help="Explicit console log level (DEBUG/INFO/WARNING/ERROR). Overrides -v/-q "
+        "and the DEVCOUNCIL_LOG_LEVEL env var.",
+    ),
+):
     """
     DevCouncil: Gated orchestrator for AI-assisted software development.
     """
+    # Configure logging once, up front, for every command. Without this the many
+    # logger.info/debug calls across the orchestrator, planner, executors and
+    # verifier go nowhere — which is exactly why recurring run failures were so
+    # hard to diagnose. The durable DEBUG log lands in .devcouncil/logs/.
+    from devcouncil.telemetry.logging_setup import configure_logging
+
+    configure_logging(verbosity=verbose, quiet=quiet, log_level=log_level)
     return
 
 if __name__ == "__main__":

package/src/devcouncil/domain/evidence.py

@@ -42,6 +42,13 @@ class VerificationEvidence(BaseModel):
     command: str
     status: Literal["passed", "failed", "not_run"]
     evidence_summary: str
+    # HOW the criterion was proven, for auditing the gate's rigor (distinct from the
+    # pass/fail status). ``compiled`` = one DevCouncil per-criterion check passed;
+    # ``vote`` = a majority of independent checks passed (self-consistency);
+    # ``coarse`` = proven only by a passing acceptance-capable command, not a check tied
+    # to the criterion (weakest). Empty for legacy/unspecified evidence. Persisted in the
+    # evidence JSON blob, so adding it needs no migration; old rows default to "".
+    mode: Literal["compiled", "vote", "coarse", ""] = ""
 
 # Backward-compatible alias
 TestEvidence = VerificationEvidence

package/src/devcouncil/execution/checkpoints.py

@@ -47,6 +47,7 @@ class CheckpointService:
         return self._create(task_id, stage="attempt", ref_name=ref_template)
 
     def rollback(self, task_id: str) -> CheckpointResult:
+        logger.info("Rollback requested for %s", task_id)
         before_ref = self.REF_BEFORE.format(task_id=task_id)
         after_ref = self.REF_AFTER.format(task_id=task_id)
         after_patch = self.checkpoint_dir / f"{task_id}-after.patch"
@@ -140,8 +141,9 @@ class CheckpointService:
         # the git-ref rollback path can never fire. Falls back to HEAD if snapshotting is
         # impossible (unborn HEAD / not a git repo), preserving the patch-based rollback.
         git_ref_created = self._update_ref(ref, self._snapshot_commit())
+        verifier = Verifier(self.project_root)
         try:
-            diff = Verifier(self.project_root).get_diff()
+            diff = verifier.get_diff()
             if diff:
                 patch_path.write_text(diff, encoding="utf-8")
         except Exception as exc:
@@ -152,12 +154,20 @@ class CheckpointService:
         if stage == "before":
             snapshot = {
                 "task_id": task_id,
-                "changed_files": Verifier(self.project_root).get_changed_files(),
+                "changed_files": verifier.get_changed_files(),
             }
             snapshot_path = self.checkpoint_dir / f"{task_id}-before.json"
             snapshot_path.write_text(json.dumps(snapshot, indent=2), encoding="utf-8")
             json_path = str(snapshot_path)
 
+        # Routine bookkeeping (fires before+after every task and repair attempt) — DEBUG
+        # keeps the -v stream milestone-level; the file still records it, and a capture
+        # *failure* is logged at WARNING above.
+        logger.debug(
+            "Checkpoint %s for %s: ref=%s patch=%s",
+            stage, task_id, "yes" if git_ref_created else "no",
+            "yes" if patch_path.exists() else "no",
+        )
         return CheckpointResult(
             task_id=task_id,
             ref=ref if git_ref_created else None,

package/src/devcouncil/execution/fs_watcher.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import logging
 import time
 import uuid
 from pathlib import Path
@@ -37,6 +38,8 @@ _EVENT_IGNORED_PREFIXES = _IGNORED_PREFIXES + (".devcouncil/", ".gitignore")
 _TASK_CACHE_TTL_SECONDS = 10.0
 _EVENT_DEBOUNCE_SECONDS = 0.5
 
+logger = logging.getLogger(__name__)
+
 
 class FilesystemWatcher:
     def __init__(
@@ -53,15 +56,20 @@ class FilesystemWatcher:
         self.on_event = on_event
         self.policy = TaskPolicyEngine(self.project_root)
         self._seen: dict[str, float] = {}
+        self._seen_last_cleanup: float = 0.0
         self._task_cache: tuple[float, Task | None] | None = None
+        # Reuse one Verifier across polls (avoids rebuilding its scanners each tick) but
+        # still run get_changed_files() fresh every poll — caching the git result would
+        # make the watcher miss changes for the cache TTL, defeating the poll interval.
+        self._verifier: Verifier | None = None
 
     def should_ignore(self, path: str) -> bool:
         normalized = path.replace("\\", "/")
         return any(normalized.startswith(prefix) for prefix in _IGNORED_PREFIXES)
 
     def scan_once(self) -> list[dict]:
-        task = self._load_task()
-        changed = Verifier(self.project_root).get_changed_files()
+        task = self._task_cached()
+        changed = self._changed_files()
         events: list[dict] = []
         for path in changed:
             if self.should_ignore(path):
@@ -71,6 +79,8 @@ class FilesystemWatcher:
 
     def watch(self) -> None:
         observer = self._start_event_observer()
+        mode = "polling" if observer is None else "event-driven (watchdog)"
+        logger.info("Filesystem watcher started for %s in %s mode", self.task_id, mode)
         if observer is None:
             # Polling fallback when watchdog is unavailable.
             while True:
@@ -129,6 +139,12 @@ class FilesystemWatcher:
         now = time.monotonic()
         last = self._seen.get(rel)
         self._seen[rel] = now
+        # Periodically evict stale entries so _seen doesn't grow unbounded in long watch
+        # sessions. Anything older than the debounce window can never suppress a future
+        # event, so dropping it leaves dedup behavior unchanged. Run at most once/window.
+        if now - self._seen_last_cleanup >= window:
+            self._seen = {key: ts for key, ts in self._seen.items() if now - ts < window}
+            self._seen_last_cleanup = now
         return last is not None and (now - last) < window
 
     def _task_cached(self) -> Task | None:
@@ -139,6 +155,11 @@ class FilesystemWatcher:
         self._task_cache = (now, task)
         return task
 
+    def _changed_files(self) -> list[str]:
+        if self._verifier is None:
+            self._verifier = Verifier(self.project_root)
+        return self._verifier.get_changed_files()
+
     def _load_task(self) -> Task | None:
         db = get_db(self.project_root)
         if not db:
@@ -165,6 +186,10 @@ class FilesystemWatcher:
                     reason=decision.reason,
                 )
                 if not allowed:
+                    logger.warning(
+                        "Orphan diff for %s: %s %s (%s)",
+                        self.task_id, operation, path, decision.reason,
+                    )
                     gap_repo = GapRepository(session)
                     gap_repo.save(
                         Gap(

package/src/devcouncil/execution/handoff.py

@@ -55,7 +55,7 @@ class HandoffService:
             if not task:
                 raise ValueError(f"Task {task_id} not found")
             reqs = RequirementRepository(session).get_all()
-            gaps = [g for g in GapRepository(session).get_all() if g.task_id == task_id and g.blocking]
+            gaps = GapRepository(session).get_blocking_for_task(task_id)
             evidence = EvidenceRepository(session).get_command_results_for_task(task_id)
             semantic = SemanticDiffRepository(session).latest_for_task(task_id)
 

package/src/devcouncil/execution/patch.py

@@ -1,8 +1,11 @@
+import logging
 import re
 import subprocess
 from pathlib import Path
 from devcouncil.app.errors import ExecutionError
 
+logger = logging.getLogger(__name__)
+
 
 class PatchEngine:
     """Handles applying unified diff patches to the codebase."""
@@ -66,8 +69,11 @@ class PatchEngine:
                     errors="replace",
                 )
                 if proc.returncode == 0:
+                    logger.info("Patch applied (git apply %s)", " ".join(extra_args) or "strict")
                     return True
                 last_stderr = (proc.stderr or "").strip()
+                logger.debug("git apply %s failed: %s", " ".join(extra_args) or "strict", last_stderr)
+            logger.error("Patch failed after all fallbacks: %s", last_stderr or "(no detail)")
             raise ExecutionError(
                 "Failed to apply patch even with whitespace/3-way fallbacks. "
                 f"git reported: {last_stderr or '(no detail)'}"

package/src/devcouncil/execution/permissions.py

@@ -1,4 +1,5 @@
 import fnmatch
+import logging
 from pathlib import Path
 from typing import List, Literal, Optional
 from pydantic import BaseModel, Field
@@ -6,6 +7,8 @@ from devcouncil.domain.task import PlannedFile, Task
 from devcouncil.app.errors import GatingError
 from devcouncil.execution.policy_engine import TaskPolicyEngine
 
+logger = logging.getLogger(__name__)
+
 class PermissionPolicy(BaseModel):
     """Defines the security boundaries for task execution."""
     allow_file_create: bool = False
@@ -76,10 +79,14 @@ class PermissionManager:
         """Raise GatingError if an execution action violates permissions."""
         if action_type == "file_write":
             if not self.is_file_change_allowed(target, task, operation, internal=internal):
+                logger.warning("DENIED file %s for %s: %s (not in planned_files)", operation, task.id, target)
                 raise GatingError(
                     f"Unauthorized file {operation}: {target}. "
                     "File and operation must match task planned_files."
                 )
+            logger.debug("Allowed file %s for %s: %s", operation, task.id, target)
         elif action_type == "shell":
             if not self.is_command_allowed(target, task):
+                logger.warning("DENIED shell command for %s: %s (not in allowed_commands)", task.id, target)
                 raise GatingError(f"Unauthorized shell command: {target}. Command must be in task's allowed_commands.")
+            logger.debug("Allowed shell command for %s: %s", task.id, target)

package/src/devcouncil/execution/policy_engine.py

@@ -11,6 +11,15 @@ from pydantic import BaseModel
 
 from devcouncil.domain.task import PlannedFile, Task
 
+# Precompiled git-safety patterns for hook-command evaluation (compiled once at import
+# instead of on every evaluate_hook_command call).
+_HARD_RESET_PROTECTED_RE = re.compile(r"\bgit\s+reset\s+--hard\s+(origin/)?(main|master)\b")
+_FORCE_PUSH_FLAG_RE = re.compile(r"\bgit\s+push\b.*(\s--force(?:-with-lease)?\b|\s-f\b)")
+_FORCE_PUSH_PLUS_REFSPEC_RE = re.compile(r"\bgit\s+push\s+\S+\s+\+\S")
+_PROTECTED_BRANCH_PUSH_RE = re.compile(
+    r"\bgit\s+push\s+\S+\s+((head:)?(main|master)|(main|master):\S+)\b"
+)
+
 
 class PolicyDecision(BaseModel):
     action: Literal["allow", "warn", "deny"]
@@ -288,16 +297,14 @@ class TaskPolicyEngine:
                 target=normalized,
             )
 
-        if re.search(r"\bgit\s+reset\s+--hard\s+(origin/)?(main|master)\b", lowered):
+        if _HARD_RESET_PROTECTED_RE.search(lowered):
             return PolicyDecision(
                 action="deny",
                 reason="Protected branch hard resets are not allowed.",
                 target=normalized,
             )
 
-        if re.search(r"\bgit\s+push\b.*(\s--force(?:-with-lease)?\b|\s-f\b)", lowered) or re.search(
-            r"\bgit\s+push\s+\S+\s+\+\S", lowered
-        ):
+        if _FORCE_PUSH_FLAG_RE.search(lowered) or _FORCE_PUSH_PLUS_REFSPEC_RE.search(lowered):
             # The second pattern catches the leading-plus refspec form
             # (`git push origin +HEAD:master`), which forces a non-fast-forward update
             # without the --force flag.
@@ -307,7 +314,7 @@ class TaskPolicyEngine:
                 target=normalized,
             )
 
-        if re.search(r"\bgit\s+push\s+\S+\s+((head:)?(main|master)|(main|master):\S+)\b", lowered):
+        if _PROTECTED_BRANCH_PUSH_RE.search(lowered):
             return PolicyDecision(
                 action="warn",
                 reason="Direct pushes to protected branches should go through verification gates.",

package/src/devcouncil/execution/prompt_builder.py

@@ -33,7 +33,7 @@ _RESERVED_COMPLETION_TOKENS = 1536
 _MIN_PROMPT_CHARS = 8_000
 
 
-def _local_context_window_budget(project_root: Path) -> int | None:
+def _local_context_window_budget(project_root: Path, cfg=None) -> int | None:
     """Char budget derived from a constrained local context window, or ``None``.
 
     When the run targets the local Ollama provider with an explicit ``OLLAMA_NUM_CTX``,
@@ -42,11 +42,16 @@ def _local_context_window_budget(project_root: Path) -> int | None:
     budget that fits the window (minus completion headroom) so :meth:`build_task_prompt`
     can cap itself. Returns ``None`` for cloud providers / unset windows, leaving the
     default behavior (and the large cloud CLIs' big windows) untouched. Best-effort:
-    any error degrades to ``None``."""
+    any error degrades to ``None``.
+
+    ``cfg`` may be a pre-loaded config (loaded once per task by ``build_task_prompt``); when
+    ``None`` it is loaded here so other callers keep working."""
     try:
-        from devcouncil.app.config import load_config
+        if cfg is None:
+            from devcouncil.app.config import load_config
 
-        provider = load_config(project_root).models.provider.strip().lower()
+            cfg = load_config(project_root)
+        provider = cfg.models.provider.strip().lower()
         if provider not in {"ollama", "ollama-local", "ollama_local"}:
             return None
     except Exception:
@@ -88,10 +93,25 @@ class PromptBuilder:
         Python uses stdlib ``ast`` (method signatures, async/@property/@staticmethod
         markers under each class). Other languages (ts/tsx/js/jsx/go/rs/java) use bounded
         regex over exported/public declarations. No tree-sitter, no model call. Never
-        raises; honors the per-file symbol cap."""
+        raises; honors the per-file symbol cap.
+
+        Results are memoized per ``build_task_prompt`` run via ``self._outline_cache`` so
+        the same file is parsed once even though both the planned-files section and the
+        call-sites section need its outline. The key includes the ``text`` itself (not just
+        ``path``) so that if the file's content differs between the two reads, the outline
+        is recomputed from the current text rather than served stale — and using the text
+        directly (rather than its hash) means there is no collision risk."""
+        cache = getattr(self, "_outline_cache", None)
+        key = (path, text)
+        if cache is not None and key in cache:
+            return cache[key]
         if path.endswith(".py"):
-            return self._python_symbol_outline(text)
-        return self._regex_symbol_outline(path, text)
+            result = self._python_symbol_outline(text)
+        else:
+            result = self._regex_symbol_outline(path, text)
+        if cache is not None:
+            cache[key] = result
+        return result
 
     def _python_symbol_outline(self, text: str) -> List[str]:
         try:
@@ -252,6 +272,15 @@ class PromptBuilder:
             + "\n".join(blocks)
         )
 
+    def _load_prompt_enhancement(self):
+        """Latest run's prompt-enhancement (None if absent/unreadable). Best-effort: a
+        failure here must never break prompt construction."""
+        try:
+            from devcouncil.planning.prompt_enhancer_service import load_latest_prompt_enhancement
+            return load_latest_prompt_enhancement(self.project_root)
+        except Exception:
+            return None
+
     def _load_repo_map(self) -> dict | None:
         """Parse ``.devcouncil/repo_map.json`` once per prompt (None if absent/unreadable)."""
         map_path = self.project_root / ".devcouncil" / "repo_map.json"
@@ -361,6 +390,56 @@ class PromptBuilder:
                 section += f"- `{skill.name}`{suffix}\n"
         return section
 
+    def _knowledge_sections(self, task: Task, cfg=None) -> tuple[str, str]:
+        """Selected design-system and OKF knowledge context for this task.
+
+        Returns ``(design_text, knowledge_text)`` — either may be empty. Sourced from
+        ``.devcouncil/knowledge/{design,okf}`` via the same trigger-based selection the
+        skills library uses: a design system is always-on (a UI agent must honor it),
+        OKF knowledge fires on goal keywords / document tags. Bounded by config char
+        budgets. Never raises — a knowledge failure must not break prompt building.
+
+        ``cfg`` may be a pre-loaded config (loaded once per task by ``build_task_prompt``);
+        when ``None`` it is loaded here so other callers keep working."""
+        try:
+            from devcouncil.knowledge.sources import (
+                render_knowledge_preamble,
+                select_knowledge_sources,
+            )
+
+            if cfg is None:
+                from devcouncil.app.config import load_config
+
+                cfg = load_config(self.project_root)
+            kcfg = cfg.knowledge
+            if not kcfg.enabled:
+                return "", ""
+            goal = f"{task.title}\n{task.description}"
+            sources = select_knowledge_sources(
+                goal=goal, project_root=self.project_root,
+                directory=kcfg.directory, design_always=kcfg.design_always,
+            )
+            design_text = render_knowledge_preamble(sources, max_chars=kcfg.design_max_chars, kind="design")
+            knowledge_text = render_knowledge_preamble(sources, max_chars=kcfg.okf_max_chars, kind="okf")
+        except Exception:
+            return "", ""
+
+        design_block = ""
+        if design_text:
+            design_block = (
+                "\n## Design system (honor these tokens and rules)\n"
+                "_The project's design.md. Use these tokens/components; don't invent ad-hoc styles._\n\n"
+                f"{design_text}\n"
+            )
+        knowledge_block = ""
+        if knowledge_text:
+            knowledge_block = (
+                "\n## Project knowledge (Open Knowledge Format)\n"
+                "_Curated org/domain knowledge relevant to this task. Ground your work in it._\n\n"
+                f"{knowledge_text}\n"
+            )
+        return design_block, knowledge_block
+
     def _dependents_section(self, task: Task, data: dict | None) -> str:
         """List, per planned file the agent will change, the files that import it — the
         blast radius. Sourced from repo_map.json's precomputed reverse-import index, so
@@ -549,10 +628,22 @@ class PromptBuilder:
     ) -> str:
         if max_chars is None:
             max_chars = MAX_PROMPT_CHARS
+        # Per-task outline cache so a planned file's symbol outline is computed once even
+        # though both the planned-files section and the call-sites section consume it.
+        self._outline_cache: dict[str, List[str]] = {}
+        # Load the project config once and share it with the helpers that need it, instead
+        # of each independently re-reading + re-parsing it. Best-effort: if it fails the
+        # helpers fall back to loading it themselves (and degrade the same way).
+        try:
+            from devcouncil.app.config import load_config
+
+            cfg = load_config(self.project_root)
+        except Exception:
+            cfg = None
         # When the run targets a constrained local window (Ollama + OLLAMA_NUM_CTX),
         # cap the budget so the server doesn't silently truncate past the window. Never
         # raises the budget above the caller's value — only lowers it to fit.
-        window_budget = _local_context_window_budget(self.project_root)
+        window_budget = _local_context_window_budget(self.project_root, cfg=cfg)
         if window_budget is not None:
             max_chars = min(max_chars, window_budget)
 
@@ -572,6 +663,18 @@ class PromptBuilder:
             for ac in req.acceptance_criteria:
                 core += f"  - [ ] {ac.description} ({ac.verification_method})\n"
 
+        # Carry the planning prompt-enhancer's codebase-specific constraints through to the
+        # one who writes the code. Otherwise that domain guidance (e.g. "division truncates
+        # toward zero", "no eval") shapes only the planning debate and reaches the executor
+        # only if a planner happened to encode it into an acceptance criterion.
+        enhancement = self._load_prompt_enhancement()
+        if enhancement is not None and (enhancement.constraints or enhancement.applied_skills):
+            core += "\n## Codebase-specific constraints (from planning — honor these)\n"
+            for constraint in enhancement.constraints[:8]:
+                core += f"- {constraint}\n"
+            if enhancement.applied_skills:
+                core += f"- Apply current senior-level practices for: {', '.join(enhancement.applied_skills[:6])}.\n"
+
         core += "\n## Allowed files\n"
         for pf in task.planned_files:
             core += f"- `{pf.path}` ({pf.allowed_change}): {pf.reason}\n"
@@ -598,8 +701,12 @@ class PromptBuilder:
 1. Implement the goal described above.
 2. Ensure all acceptance criteria are met.
 3. Only modify the allowed files.
-4. Run the allowed commands to verify your work.
-5. Provide evidence of passing tests.
+4. Stay within this task's scope even inside an allowed file: change only what the
+   acceptance criteria require. Do NOT remove, rename, or alter the signature of an
+   existing public symbol the task did not ask you to touch — verification flags an
+   unrequested public-API change as scope drift and blocks it.
+5. Run the allowed commands to verify your work.
+6. Provide evidence of passing tests.
 """
 
         # --- Optional context: fitted within the remaining budget, dropped lowest-
@@ -644,6 +751,15 @@ class PromptBuilder:
         if skills_text:
             segments.append({"order": 4, "priority": 3, "name": "engineering skills", "text": skills_text})
 
+        # Design system (a hard constraint for UI work) and OKF project knowledge. The
+        # design system rides just above skills; OKF knowledge alongside them. Both are
+        # bounded by config char budgets in `_knowledge_sections`.
+        design_text, knowledge_text = self._knowledge_sections(task, cfg=cfg)
+        if design_text:
+            segments.append({"order": 4, "priority": 2, "name": "design system", "text": design_text})
+        if knowledge_text:
+            segments.append({"order": 4, "priority": 3, "name": "project knowledge", "text": knowledge_text})
+
         # Lowest priority (4): the budget drops call sites first. It only adds value once
         # the file bodies + dependents are present anyway.
         call_sites_text = self._call_sites_section(task, repo_map_data)