coding-os 0.3.2__py3-none-any.whl

board_os/_agent_runtime.py

@@ -0,0 +1,256 @@
+"""Shared agent-runtime detection helper (E2 of Wave 0 audit fixes)."""
+
+from __future__ import annotations
+
+import logging
+import os
+from functools import lru_cache
+from pathlib import Path
+
+logger = logging.getLogger("board_os.agent_runtime")
+
+# Fallback when neither env nor explicit session names a known adapter.
+_UNKNOWN_AGENT = "agent"
+
+# Hard floor: we only ever return values from this set OR the explicit
+# session string OR _UNKNOWN_AGENT. Adapter ids loaded at runtime extend
+# the allowlist via _known_agent_ids().
+_HUMAN_LITERAL = "human"
+
+# Unattended kernel maintenance (nightly auto-archive, zombie reclaim) writes
+# under this prefix so the board never misattributes daemon work to the human
+# operator (hub-architecture.md § Actor attribution contract).
+_SYSTEM_LITERAL = "system"
+SYSTEM_SESSION_PREFIX = "ses-system"
+
+
+@lru_cache(maxsize=1)
+def _known_agent_ids() -> tuple[frozenset[str], dict[str, tuple[str, ...]]]:
+    """Load adapter ids + env markers from the adapter registry, cached."""
+    here = Path(__file__).resolve()
+    repo_root = here.parent.parent.parent  # core/board_os/<file> → repo root
+    adapters_dir = repo_root / "adapters"
+
+    try:
+        # Lazy import — cli is not always on path (e.g. when called from
+        # the MCP server). Detection must remain non-fatal.
+        import sys
+
+        cli_pkg = repo_root / "cli"
+        if str(cli_pkg.parent) not in sys.path:
+            sys.path.insert(0, str(cli_pkg.parent))
+        from cli.adapter_registry import load_adapter_registry  # type: ignore
+
+        reg = load_adapter_registry(adapters_dir)
+    except Exception as exc:
+        logger.debug(
+            "adapter registry unreachable, agent detection degrades to marker-only: %s",
+            exc,
+        )
+        return frozenset(), {}
+
+    ids = frozenset(reg.keys())
+    markers = {aid: tuple(p.runtime_env_markers) for aid, p in reg.items()}
+    return ids, markers
+
+
+def detect_agent(agent_session: str | None = None) -> str:
+    """Return the adapter id of the currently running agent.
+
+    Priority order (matches cos-env.sh shell logic):
+      1. Explicit ``agent_session`` argument when it names a known id /
+         human / literal substring.
+      2. ``COS_AGENT`` env override.
+      3. Adapter ``runtime_env_markers`` declared in adapter.yaml.
+      4. Persisted ``.coding-os/.agent`` marker file.
+      5. ``_UNKNOWN_AGENT`` fallback.
+
+    The function never raises — agent attribution is best-effort and must
+    not block tool dispatch.
+    """
+    known_ids, markers_by_id = _known_agent_ids()
+
+    label = _from_explicit_session(agent_session, known_ids)
+    if label is not None:
+        return label
+
+    explicit_env = (os.environ.get("COS_AGENT") or "").strip().lower()
+    if explicit_env in known_ids or explicit_env == _HUMAN_LITERAL:
+        return explicit_env
+
+    for agent_id in sorted(known_ids):
+        for env_key in markers_by_id.get(agent_id, ()):
+            if os.environ.get(env_key):
+                return agent_id
+
+    marker_value = _read_agent_marker_file()
+    if marker_value and (marker_value in known_ids or marker_value == _HUMAN_LITERAL):
+        return marker_value
+
+    return _UNKNOWN_AGENT
+
+
+def _from_explicit_session(
+    agent_session: str | None,
+    known_ids: frozenset[str],
+) -> str | None:
+    """Best-effort match of an explicit session string to a known adapter."""
+    if not agent_session:
+        return None
+    s = agent_session.strip().lower()
+    if not s:
+        return None
+    # Match adapter ids by substring so callers can pass a fully-qualified
+    # session id like "ses-claude-20260427-...". First exact match wins;
+    # ties broken alphabetically (deterministic).
+    for agent_id in sorted(known_ids):
+        if agent_id in s:
+            return agent_id
+    if _SYSTEM_LITERAL in s:
+        return _SYSTEM_LITERAL
+    if _HUMAN_LITERAL in s:
+        return _HUMAN_LITERAL
+    return agent_session.strip()[:24]
+
+
+def _read_agent_marker_file() -> str:
+    """Read ``.coding-os/.agent`` if present; return empty string otherwise."""
+    state_dir = os.environ.get("COS_STATE_DIR")
+    if state_dir:
+        candidate = Path(state_dir) / ".agent"
+    else:
+        candidate = Path.cwd() / ".coding-os" / ".agent"
+    if not candidate.is_file():
+        return ""
+    try:
+        return candidate.read_text(encoding="utf-8", errors="ignore").strip().lower()
+    except OSError as exc:
+        logger.debug("agent marker read failed: %s", exc)
+        return ""
+
+
+def _read_active_session_pointer() -> str:
+    """Read the freshest "who is calling" session pointer, panel-first.
+
+    ``$COS_PANEL_DIR/session-id`` names THIS panel and is refreshed every
+    prompt, so it is preferred over the agent-level ``.active-session``,
+    which is shared across sibling panels and resolves last-writer-wins —
+    the source of cross-panel attribution drift (one panel's board write
+    landing under another's session). Parity with
+    ``cli.board_commands._agent_session_id``. The agent-level pointer stays
+    as the fallback for callers without a panel dir. Best-effort: ``""`` on
+    any miss.
+    """
+    panel_dir = os.environ.get("COS_PANEL_DIR")
+    if panel_dir:
+        try:
+            panel_value = (
+                (Path(panel_dir) / "session-id")
+                .read_text(encoding="utf-8", errors="ignore")
+                .strip()
+            )
+        except OSError as exc:
+            logger.debug("panel session-id read failed: %s", exc)
+            panel_value = ""
+        if panel_value:
+            return panel_value
+
+    agent_dir = os.environ.get("COS_AGENT_DIR")
+    if agent_dir:
+        pointer = Path(agent_dir) / ".active-session"
+    else:
+        state_dir = os.environ.get("COS_STATE_DIR")
+        base = Path(state_dir) if state_dir else (Path.cwd() / ".coding-os")
+        agent = (os.environ.get("COS_AGENT") or "").strip().lower() or detect_agent()
+        if not agent or agent == _UNKNOWN_AGENT:
+            return ""
+        pointer = base / agent / ".active-session"
+    try:
+        return pointer.read_text(encoding="utf-8", errors="ignore").strip()
+    except OSError as exc:
+        logger.debug("active-session pointer read failed: %s", exc)
+        return ""
+
+
+def resolve_agent_session(explicit: str | None = None) -> str | None:
+    """Return the session id to attribute a board write to.
+
+    Adapter-agnostic resolver shared by ``cos_task_create``,
+    ``cos_task_move``, ``cos_work_log_append``, and any future board
+    mutator. Priority order:
+
+      1. ``explicit`` — caller-supplied session id wins.
+      2. ``$COS_SESSION_FILE`` — written by ``cos-env.sh`` /
+         ``session-context.sh`` at every ``SessionStart startup`` in the
+         shape ``ses-<agent>-YYYYMMDD-HHMMSS-xxxx``.
+      3. ``.active-session`` disk pointer — the current panel, refreshed
+         every prompt; the bridge for the long-lived MCP server whose
+         ``$COS_SESSION_FILE`` env is frozen/empty (TASK-168).
+      4. ``$COS_SESSION_ID`` — direct env override (CI / test harness).
+      5. Synthesised ``ses-<detected-agent>-pid<PID>`` fallback so the
+         row never lands as ``NULL`` (which the board UI maps to the
+         green ``H`` glyph by default — see
+         ``core/web/ui/src/features/cos-board/useBoardStream.ts``).
+
+    Never raises; never returns an empty string.
+    """
+    if explicit:
+        s = explicit.strip()
+        if s:
+            return s
+
+    session_file = os.environ.get("COS_SESSION_FILE")
+    if session_file:
+        try:
+            value = Path(session_file).read_text(encoding="utf-8").strip()
+        except OSError as exc:
+            logger.debug("session file read failed: %s", exc)
+            value = ""
+        if value:
+            return value
+
+    # The long-lived MCP server has a frozen/empty $COS_SESSION_FILE; the
+    # agent-level .active-session pointer (refreshed every prompt by
+    # session-context.sh) is the freshest "who is calling" signal. Reading it
+    # here keeps MCP-created board writes attributed to the active panel
+    # instead of the shared ses-<agent>-pid<server-pid> synthetic.
+    pointer = _read_active_session_pointer()
+    if pointer:
+        return pointer
+
+    env_id = (os.environ.get("COS_SESSION_ID") or "").strip()
+    if env_id:
+        return env_id
+
+    agent = detect_agent()
+    if agent and agent != _UNKNOWN_AGENT:
+        return f"ses-{agent}-pid{os.getpid()}"
+    return None
+
+
+def human_actor() -> dict[str, str]:
+    """Resolve the human operator's actor identity (future-auth-ready).
+
+    No auth yet: the web panel acts as a single local human. Identity is
+    sourced from ``$COS_HUMAN_ACTOR`` (shape ``id`` or ``id:Label``) so a
+    later auth layer can set the authenticated user without touching
+    callers; the ``human`` default keeps the no-auth panel working.
+    """
+    raw = (os.environ.get("COS_HUMAN_ACTOR") or _HUMAN_LITERAL).strip()
+    actor_id, _, label = raw.partition(":")
+    actor_id = actor_id.strip() or _HUMAN_LITERAL
+    return {"type": "human", "id": actor_id, "label": label.strip() or actor_id}
+
+
+def reset_cache() -> None:
+    """Test-only: drop the cached registry so tests get fresh adapter data."""
+    _known_agent_ids.cache_clear()
+
+
+__all__ = [
+    "SYSTEM_SESSION_PREFIX",
+    "detect_agent",
+    "human_actor",
+    "reset_cache",
+    "resolve_agent_session",
+]

board_os/config.py

@@ -0,0 +1,421 @@
+"""board_os — Scrumban configuration loader and validator (L.0).
+
+Reads `.coding-os/scrumban-config.yaml` from the project root and
+returns a typed, validated `ScrumbanConfig`. The config defines which
+swimlanes (domains) are valid, which WIP caps apply per column, and
+which label families have explicit colours.
+
+Per-project overrides ship in templates/<stack>/scaffold/.coding-os/.
+The base default ships in templates/_base/scaffold/.coding-os/.
+
+The four categorization axes (see plan §6.1.1):
+  swimlane = domain (config-enum, this file)
+  kind     = work type (closed enum, KIND_ENUM below)
+  epic     = initiative grouping (optional free string)
+  labels   = free tags (no rendering impact)
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+logger = logging.getLogger("coding_os.board_os.config")
+
+
+# Closed enums — see plan §6.1.1.  These are NOT configurable: card
+# colour stability across all repos requires a fixed work-type set.
+KIND_ENUM: tuple[str, ...] = (
+    "feature",
+    "bug",
+    "chore",
+    "spike",
+    "docs",
+    "refactor",
+    "test",
+    "security",
+)
+
+STATUS_ENUM: tuple[str, ...] = (
+    "icebox",
+    "emergency",
+    "in_progress",
+    "testing",
+    "complete",
+    "blocked",
+    "archive",
+)
+
+# "ready" is no longer a status column — it collapses into a label on
+# tasks that still live in icebox.  Declared here so the label chip
+# renders with a distinct colour in the UI and so lint passes keep it
+# out of the KIND_ENUM (KIND == "ready" would shadow the label).
+READY_LABEL: str = "ready"
+
+PRIORITY_ENUM: tuple[str, ...] = ("P0", "P1", "P2", "P3")
+
+# Default colour palette per work-type.  Hex codes chosen for
+# deuteranopia/protanopia distinguishability (Okabe-Ito-adjacent).
+_DEFAULT_KIND_COLORS: dict[str, str] = {
+    "feature": "#eab308",  # yellow
+    "bug": "#dc2626",  # red
+    "chore": "#22c55e",  # green
+    "spike": "#3b82f6",  # blue
+    "docs": "#a855f7",  # purple
+    "refactor": "#14b8a6",  # teal
+    "test": "#f59e0b",  # amber
+    "security": "#ea580c",  # orange
+}
+
+# Identifier regex for swimlane ids, label values, epic ids.
+_ID_RE = re.compile(r"^[a-z0-9][a-z0-9_-]*$")
+# Hex colour regex (3 or 6 char).
+_HEX_RE = re.compile(r"^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$")
+# Appetite regex (Shape Up style: 30m, 2h, 1d, 3w, 1cy).
+APPETITE_RE = re.compile(r"^\d+(?:m|h|d|w|cy)$")
+# Canonical task-id shape (TASK-NNN, optionally namespaced TASK-NS-NNN).
+# depends_on/blocked_by entries are matched literally by the cycle detector
+# and the dependents junction — a malformed id silently never matches.
+TASK_ID_FORMAT_RE = re.compile(r"^TASK-(?:[A-Z][A-Z0-9]*-)?\d+$")
+
+
+class ConfigValidationError(ValueError):
+    """Raised when scrumban-config.yaml fails schema validation.
+
+    Carries a list of human-readable errors so the CLI can print them
+    one per line.  Always includes the offending file path when known.
+    """
+
+    def __init__(self, errors: list[str], path: Path | None = None) -> None:
+        self.errors = errors
+        self.path = path
+        header = f"scrumban-config.yaml validation failed ({path or '<inline>'})"
+        super().__init__(header + ":\n  - " + "\n  - ".join(errors))
+
+
+@dataclass(frozen=True)
+class Swimlane:
+    """One row on the Scrumban board — a domain / subsystem / team.
+
+    color  — primary band colour (lighter, used for row tint + left strip).
+    accent — darker shade for text + 3-4 px border; defaults to color if
+             not set, but picking a deliberate darker tone gives the board
+             the distinct per-lane identity the prototype was built around
+             (see docs/phase-l-scrumban-task-system-plan.md §12 and the
+             design bundle in core/web/ui/coding-os-scrumban/).
+    """
+
+    id: str
+    label: str
+    color: str
+    description: str = ""
+    accent: str = ""
+
+    def effective_accent(self) -> str:
+        return self.accent or self.color
+
+
+@dataclass(frozen=True)
+class WipLimits:
+    """Per-column WIP caps.  Defaults match the solo-dev defense (1/3/2)."""
+
+    in_progress: int = 1
+    testing: int = 3
+    emergency: int = 2
+
+    def cap_for(self, status: str) -> int | None:
+        """Return cap for a column or None if uncapped (icebox/ready/etc.)."""
+        return {
+            "in_progress": self.in_progress,
+            "testing": self.testing,
+            "emergency": self.emergency,
+        }.get(status)
+
+
+@dataclass(frozen=True)
+class LabelFamily:
+    """A named label family with a colour override (optional)."""
+
+    name: str
+    color: str
+    emoji: str = ""
+
+
+@dataclass(frozen=True)
+class WorkflowPolicy:
+    """Config-driven Scrumban state-machine policy gates.
+
+    Gate defaults are True so a fresh project enforces the disciplined
+    flow; a consumer can relax any knob via `workflow_policy:` in
+    scrumban-config.yaml.
+
+    per_session_wip — count the in_progress cap per agent_session so
+        concurrent sessions don't block each other on a global cap.
+    reclaim_idle_hours — an in_progress task idle this long whose owner
+        session is inactive is a zombie-reclaim candidate.
+    """
+
+    require_ready_label: bool = True
+    block_in_progress_to_complete: bool = True
+    # icebox→in_progress is blocked while any depends_on task is not 'complete'
+    # (RETRYABLE conflict; force/emergency bypass). cos_task_pick omits cards
+    # with an incomplete dependency.
+    require_deps_complete: bool = True
+    per_session_wip: bool = True
+    reclaim_idle_hours: int = 24
+    # Per-status reclaim window. `testing` is where the testing-first
+    # protocol funnels near-done work, so a stranded testing card is
+    # mid-flight, not backlog — reclaim it sooner than a generic
+    # in_progress zombie. 0 falls back to reclaim_idle_hours.
+    testing_reclaim_idle_hours: int = 6
+    # SLA dwell budgets — a card whose time-in-current-status exceeds its
+    # budget is flagged `stale` on every board surface (observability
+    # only; no mutation). 0 disables the flag for that status.
+    in_progress_sla_hours: int = 24
+    testing_sla_hours: int = 6
+    icebox_stale_days: int = 30
+    # A card parked in `blocked` past this budget is flagged stale on board/daily
+    # so aging blockers surface (observability only — never auto-escalated to the
+    # emergency lane). 0 disables. Default 72h ≈ the "Day 3: surface" escalation rung.
+    blocked_sla_hours: int = 72
+    # Auto-archive aged cards. A `keep`/`parked` label always exempts a card and
+    # archive is reversible (archive->icebox is a legal edge).
+    #   icebox  — OFF by default (0): never silently retire *unstarted* backlog.
+    #   complete — 30d default: finished work older than a month is history, so it
+    #     auto-archives to keep the COMPLETE column bounded to recent work. Safe
+    #     because the work is done and the move is reversible/hidden, not deleted.
+    icebox_auto_archive_days: int = 0
+    complete_auto_archive_days: int = 30
+
+
+@dataclass(frozen=True)
+class ScrumbanConfig:
+    swimlanes: tuple[Swimlane, ...]
+    wip_limits: WipLimits = field(default_factory=WipLimits)
+    label_families: tuple[LabelFamily, ...] = field(default_factory=tuple)
+    workflow_policy: WorkflowPolicy = field(default_factory=WorkflowPolicy)
+    # Task-id allocation. "sequential" → TASK-NNN (default, single-owner).
+    # "namespaced" → TASK-<NS>-NNN so un-synced contributors never collide
+    # (multi-contributor). NS comes from task_id_prefix, else git user.email.
+    task_id_scheme: str = "sequential"
+    task_id_prefix: str = ""
+    source_path: Path | None = None
+
+    @property
+    def swimlane_ids(self) -> set[str]:
+        return {sl.id for sl in self.swimlanes}
+
+    def get_swimlane(self, swimlane_id: str) -> Swimlane | None:
+        for sl in self.swimlanes:
+            if sl.id == swimlane_id:
+                return sl
+        return None
+
+    def kind_color(self, kind: str) -> str:
+        """Return the stable card colour for a work-type."""
+        return _DEFAULT_KIND_COLORS.get(kind, "#6b7280")  # gray fallback
+
+
+def _validate_id(value: Any, field_name: str, errors: list[str]) -> None:
+    if not isinstance(value, str) or not _ID_RE.match(value):
+        errors.append(f"{field_name}={value!r} must match {_ID_RE.pattern}")
+
+
+def _validate_color(value: Any, field_name: str, errors: list[str]) -> None:
+    if not isinstance(value, str) or not _HEX_RE.match(value):
+        errors.append(f"{field_name}={value!r} must be a hex colour (#rgb or #rrggbb)")
+
+
+def parse_config(data: dict[str, Any], source_path: Path | None = None) -> ScrumbanConfig:
+    errors: list[str] = []
+
+    # swimlanes (required, non-empty)
+    swimlanes_raw = data.get("swimlanes")
+    if not isinstance(swimlanes_raw, list) or not swimlanes_raw:
+        errors.append("swimlanes must be a non-empty list")
+        raise ConfigValidationError(errors, path=source_path)
+
+    seen_ids: set[str] = set()
+    swimlanes: list[Swimlane] = []
+    for i, sl in enumerate(swimlanes_raw):
+        if not isinstance(sl, dict):
+            errors.append(f"swimlanes[{i}] must be a mapping")
+            continue
+        sid = sl.get("id")
+        _validate_id(sid, f"swimlanes[{i}].id", errors)
+        if isinstance(sid, str) and sid in seen_ids:
+            errors.append(f"swimlanes[{i}].id={sid!r} is duplicated")
+        if isinstance(sid, str):
+            seen_ids.add(sid)
+        label = sl.get("label", sid if isinstance(sid, str) else "")
+        if not isinstance(label, str):
+            errors.append(f"swimlanes[{i}].label must be a string")
+            label = ""
+        color = sl.get("color", "#6b7280")
+        _validate_color(color, f"swimlanes[{i}].color", errors)
+        accent = sl.get("accent", color)
+        _validate_color(accent, f"swimlanes[{i}].accent", errors)
+        description = sl.get("description", "")
+        if not isinstance(description, str):
+            errors.append(f"swimlanes[{i}].description must be a string")
+            description = ""
+        if (
+            isinstance(sid, str)
+            and isinstance(label, str)
+            and isinstance(color, str)
+            and isinstance(accent, str)
+        ):
+            swimlanes.append(
+                Swimlane(
+                    id=sid,
+                    label=label,
+                    color=color,
+                    accent=accent,
+                    description=description,
+                )
+            )
+
+    # wip_limits (optional)
+    wip_raw = data.get("wip_limits", {}) or {}
+    if not isinstance(wip_raw, dict):
+        errors.append("wip_limits must be a mapping")
+        wip_raw = {}
+    wip_kwargs: dict[str, int] = {}
+    for col in ("in_progress", "testing", "emergency"):
+        if col in wip_raw:
+            v = wip_raw[col]
+            if not isinstance(v, int) or v < 0:
+                errors.append(f"wip_limits.{col}={v!r} must be a non-negative int")
+            else:
+                wip_kwargs[col] = v
+    wip_limits = WipLimits(**wip_kwargs)
+
+    # label_families (optional)
+    label_families_raw = data.get("label_families", []) or []
+    if not isinstance(label_families_raw, list):
+        errors.append("label_families must be a list")
+        label_families_raw = []
+    label_families: list[LabelFamily] = []
+    seen_lf: set[str] = set()
+    for i, lf in enumerate(label_families_raw):
+        if not isinstance(lf, dict):
+            errors.append(f"label_families[{i}] must be a mapping")
+            continue
+        name = lf.get("name")
+        _validate_id(name, f"label_families[{i}].name", errors)
+        if isinstance(name, str) and name in KIND_ENUM:
+            errors.append(
+                f"label_families[{i}].name={name!r} collides with KIND_ENUM "
+                f"(use kind, not labels, for {name})"
+            )
+        if isinstance(name, str) and name in seen_lf:
+            errors.append(f"label_families[{i}].name={name!r} is duplicated")
+        if isinstance(name, str):
+            seen_lf.add(name)
+        color = lf.get("color", "#6b7280")
+        _validate_color(color, f"label_families[{i}].color", errors)
+        emoji = lf.get("emoji", "")
+        if not isinstance(emoji, str):
+            errors.append(f"label_families[{i}].emoji must be a string")
+            emoji = ""
+        if isinstance(name, str) and isinstance(color, str):
+            label_families.append(LabelFamily(name=name, color=color, emoji=emoji))
+
+    # workflow_policy (optional) — both gates default True (enforce).
+    policy_raw = data.get("workflow_policy", {}) or {}
+    if not isinstance(policy_raw, dict):
+        errors.append("workflow_policy must be a mapping")
+        policy_raw = {}
+    policy_kwargs: dict[str, object] = {}
+    for flag in (
+        "require_ready_label",
+        "block_in_progress_to_complete",
+        "require_deps_complete",
+        "per_session_wip",
+    ):
+        if flag in policy_raw:
+            v = policy_raw[flag]
+            if not isinstance(v, bool):
+                errors.append(f"workflow_policy.{flag}={v!r} must be a boolean")
+            else:
+                policy_kwargs[flag] = v
+    if "reclaim_idle_hours" in policy_raw:
+        v = policy_raw["reclaim_idle_hours"]
+        if not isinstance(v, int) or isinstance(v, bool) or v <= 0:
+            errors.append(f"workflow_policy.reclaim_idle_hours={v!r} must be a positive int")
+        else:
+            policy_kwargs["reclaim_idle_hours"] = v
+    # Non-negative int knobs (0 = disabled for SLA/auto-archive; 0 falls
+    # back to reclaim_idle_hours for testing_reclaim_idle_hours).
+    for knob in (
+        "testing_reclaim_idle_hours",
+        "in_progress_sla_hours",
+        "testing_sla_hours",
+        "icebox_stale_days",
+        "blocked_sla_hours",
+        "icebox_auto_archive_days",
+        "complete_auto_archive_days",
+    ):
+        if knob in policy_raw:
+            v = policy_raw[knob]
+            if not isinstance(v, int) or isinstance(v, bool) or v < 0:
+                errors.append(f"workflow_policy.{knob}={v!r} must be a non-negative int")
+            else:
+                policy_kwargs[knob] = v
+    workflow_policy = WorkflowPolicy(**policy_kwargs)
+
+    # Task-id scheme (optional). namespaced needs a valid NS prefix shape when
+    # given explicitly; an empty prefix under namespaced is derived at runtime.
+    task_id_scheme = data.get("task_id_scheme", "sequential")
+    if task_id_scheme not in ("sequential", "namespaced"):
+        errors.append(f"task_id_scheme={task_id_scheme!r} must be 'sequential' or 'namespaced'")
+        task_id_scheme = "sequential"
+    task_id_prefix = data.get("task_id_prefix", "") or ""
+    if not isinstance(task_id_prefix, str):
+        errors.append("task_id_prefix must be a string")
+        task_id_prefix = ""
+    if task_id_prefix and not re.match(r"^[A-Z][A-Z0-9]{1,7}$", task_id_prefix):
+        errors.append(
+            f"task_id_prefix={task_id_prefix!r} must be 2-8 chars, uppercase, "
+            "starting with a letter (e.g. 'KO')"
+        )
+        task_id_prefix = ""
+
+    if errors:
+        raise ConfigValidationError(errors, path=source_path)
+
+    return ScrumbanConfig(
+        swimlanes=tuple(swimlanes),
+        wip_limits=wip_limits,
+        label_families=tuple(label_families),
+        workflow_policy=workflow_policy,
+        task_id_scheme=task_id_scheme,
+        task_id_prefix=task_id_prefix,
+        source_path=source_path,
+    )
+
+
+def _config_path(project_root: Path) -> Path:
+    """Resolve the canonical config path for a project."""
+    return project_root / ".coding-os" / "scrumban-config.yaml"
+
+
+def load_config(project_root: str | os.PathLike[str] | None = None) -> ScrumbanConfig:
+    root = Path(project_root or os.getcwd()).resolve()
+    path = _config_path(root)
+    if not path.exists():
+        raise FileNotFoundError(
+            f"scrumban-config.yaml not found at {path}. "
+            f"Run `cos board-config --init` to scaffold a default."
+        )
+    with path.open("r", encoding="utf-8") as fh:
+        data = yaml.safe_load(fh) or {}
+    if not isinstance(data, dict):
+        raise ConfigValidationError(["top-level YAML must be a mapping"], path=path)
+    return parse_config(data, source_path=path)