icdev-core 0.2.1__py3-none-any.whl

icdev/core/__init__.py

@@ -0,0 +1,22 @@
+# CUI // SP-CTI
+"""ICDEV core contract — the seam between the domain-neutral kernel and a parent.
+
+A parent (ICDEV[IT], ICDEV[FT], ...) declares itself in an ``icdev_domain.yaml``
+at its repository root. This package reads that declaration and answers the
+three questions every kernel module used to answer for itself, 2,054 times
+over, with ``Path(__file__).resolve().parent...``:
+
+* :mod:`icdev.core.paths`   — where is the repository root and its data?
+* :mod:`icdev.core.domain`  — which domain is this, and what did it declare?
+* :mod:`icdev.core.context` — is this process allowed to run HERE, against
+  THIS database? (``assert_identity``)
+
+Nothing in this package imports anything outside the standard library and
+PyYAML, so it can be imported before ``tools.db.storage`` and from either the
+``tools.*`` shim or the ``icdev.tools.*`` canonical namespace.
+
+Programme: docs/programmes/icdev-domain-split.md (xit-decl-01).
+"""
+from __future__ import annotations
+
+__all__ = ["paths", "domain", "context"]

icdev/core/context.py

@@ -0,0 +1,205 @@
+# CUI // SP-CTI
+"""Process identity: is THIS process allowed to run HERE, against THIS database?
+
+Two ICDEV parents run on one machine, share one shell and one PostgreSQL
+server, and both read ``<PREFIX>_PG_DATABASE`` / ``<PREFIX>_DATABASE_URL``
+from the process environment. An ICDEV[FT] session that inherits ICDEV[IT]'s
+``.env`` would open ``icdev`` and write trading rows into it; nothing today
+would notice. :func:`assert_identity` is the refusal, called at the start of
+every long-lived or state-changing entry point (dashboard, genesis daemon,
+``tools/db/migrate.py``, ``tools/kanban/cli.py``).
+
+The check is FAIL-CLOSED ON A DECLARED MISMATCH and NEVER on silence: a
+process whose env names no database at all is reported ``unmeasured`` and
+allowed through, because SQLite-only deployments, CI and tests legitimately
+run without one. A declaration that lists no ``db.databases`` asserts
+nothing and is likewise ``unmeasured``.
+
+    python -m icdev.core.context --check          # human summary, exit 1 on mismatch
+    python -m icdev.core.context --check --json
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from urllib.parse import urlsplit
+
+from icdev.core import paths as core_paths
+from icdev.core.domain import Domain, DomainError, load_domain
+
+IDENTITY_GUARD_ENV = "ICDEV_IDENTITY_GUARD"  # =0 -> report only, never refuse
+
+
+class IdentityMismatch(RuntimeError):
+    """The process environment names a database this parent did not declare."""
+
+
+@dataclass(frozen=True)
+class IdentityReport:
+    domain_key: str
+    domain_name: str
+    domain_source: str
+    root: str
+    database_declared: tuple[str, ...]
+    database_observed: str | None
+    database_source: str | None  # name_env | dsn_env | None
+    verdict: str  # match | mismatch | unmeasured
+    enforced: bool
+    detail: str
+
+    def to_dict(self) -> dict:
+        d = asdict(self)
+        d["database_declared"] = list(self.database_declared)
+        return d
+
+
+def _database_from_dsn(dsn: str) -> str | None:
+    """Return the database name from a libpq URL, or None when it has none."""
+    try:
+        parts = urlsplit(dsn)
+    except ValueError:
+        return None
+    if parts.scheme not in ("postgresql", "postgres"):
+        return None
+    name = parts.path.lstrip("/")
+    return name or None
+
+
+def observed_database(domain: Domain, environ: os._Environ | dict | None = None) -> tuple[str | None, str | None]:
+    """Return ``(database_name, which_env_var)`` as the process env declares it.
+
+    ``name_env`` wins over ``dsn_env`` because that is the precedence
+    ``tools/db/storage.py`` gives ``ICDEV_PG_DATABASE`` when both are set for
+    the keyword form; a DSN's path is consulted only when the name is absent.
+    """
+    env = os.environ if environ is None else environ
+    name = (env.get(domain.db.name_env) or "").strip()
+    if name:
+        return name, domain.db.name_env
+    dsn = (env.get(domain.db.dsn_env) or "").strip()
+    if dsn:
+        parsed = _database_from_dsn(dsn)
+        if parsed:
+            return parsed, domain.db.dsn_env
+    return None, None
+
+
+def load_env(root: Path | None = None) -> Path | None:
+    """Load ``<root>/.env`` (the PARENT's, never cwd's). Returns the path loaded."""
+    root = root or core_paths.repo_root()
+    env_file = root / ".env"
+    if not env_file.is_file():
+        return None
+    try:
+        from dotenv import load_dotenv
+    except ImportError:  # pragma: no cover — dotenv is a declared dependency
+        return None
+    load_dotenv(env_file, override=False)
+    return env_file
+
+
+def check_identity(
+    *,
+    anchor: str | os.PathLike[str] | None = None,
+    domain: Domain | None = None,
+    environ: dict | None = None,
+) -> IdentityReport:
+    """Compute the identity verdict without raising."""
+    dom = domain or load_domain(anchor=anchor)
+    observed, which = observed_database(dom, environ)
+    declared = tuple(dom.db.databases)
+    enforced = os.environ.get(IDENTITY_GUARD_ENV, "1").strip().lower() not in ("0", "false", "no", "monitor")
+    if not declared:
+        verdict, detail = "unmeasured", "the declaration lists no db.databases, so it asserts nothing"
+    elif observed is None:
+        verdict, detail = "unmeasured", (
+            f"neither {dom.db.name_env} nor {dom.db.dsn_env} names a database in this process"
+        )
+    elif observed in declared:
+        verdict, detail = "match", f"{which}={observed} is declared by {dom.key}"
+    else:
+        verdict, detail = "mismatch", (
+            f"{which} names database {observed!r} but domain {dom.key!r} declares only "
+            f"{list(declared)} — this process is running against another parent's database"
+        )
+    return IdentityReport(
+        domain_key=dom.key,
+        domain_name=dom.name,
+        domain_source=dom.source,
+        root=str(dom.root),
+        database_declared=declared,
+        database_observed=observed,
+        database_source=which,
+        verdict=verdict,
+        enforced=enforced,
+        detail=detail,
+    )
+
+
+def assert_identity(
+    *,
+    anchor: str | os.PathLike[str] | None = None,
+    domain: Domain | None = None,
+    environ: dict | None = None,
+) -> IdentityReport:
+    """Refuse (``IdentityMismatch``) on a declared mismatch; return the report otherwise.
+
+    Stand it down with ``ICDEV_IDENTITY_GUARD=0`` (the report is still
+    computed and returned, so a caller can log it), never with a shell
+    neutraliser.
+    """
+    report = check_identity(anchor=anchor, domain=domain, environ=environ)
+    if report.verdict == "mismatch" and report.enforced:
+        raise IdentityMismatch(report.detail)
+    return report
+
+
+def describe(anchor: str | os.PathLike[str] | None = None) -> dict:
+    """Everything ``icdev status`` prints about where and who this process is."""
+    out: dict = {"paths": core_paths.describe(anchor)}
+    try:
+        dom = load_domain(anchor=anchor)
+    except DomainError as exc:
+        out["domain"] = None
+        out["error"] = str(exc)
+        return out
+    out["domain"] = dom.to_dict()
+    out["identity"] = check_identity(domain=dom).to_dict()
+    return out
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("--check", action="store_true", help="exit 1 on a declared mismatch")
+    ap.add_argument("--json", action="store_true")
+    ap.add_argument("--no-env", action="store_true", help="do not load <root>/.env first")
+    args = ap.parse_args(argv)
+
+    if not args.no_env:
+        load_env()
+    try:
+        info = describe()
+    except DomainError as exc:
+        print(f"domain declaration error: {exc}", file=sys.stderr)
+        return 2
+    if args.json:
+        print(json.dumps(info, indent=2))
+    else:
+        d = info.get("domain") or {}
+        ident = info.get("identity") or {}
+        print(f"domain   : {d.get('key')} ({d.get('name')}) from {d.get('source')}")
+        print(f"root     : {info['paths']['root']}  [{info['paths']['source']}]")
+        print(f"database : declared {d.get('db', {}).get('databases')} observed "
+              f"{ident.get('database_observed')!r} via {ident.get('database_source')}")
+        print(f"identity : {ident.get('verdict', 'unknown').upper()} — {ident.get('detail', info.get('error'))}")
+    if args.check and (info.get("identity") or {}).get("verdict") == "mismatch":
+        return 1
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

icdev/core/domain.py

@@ -0,0 +1,265 @@
+# CUI // SP-CTI
+"""The ``icdev_domain.yaml`` declaration — what a parent tells the core.
+
+A parent declares its key, env prefix, database, sensitivity model, component
+registry, reflex packs, dashboard port, board identity, MCP composition, trust
+policy and CI gate set in one file at its repository root. The core reads that
+file and nothing else to learn whose domain it is serving.
+
+Two deliberate properties:
+
+* **The key comes from the FILE, never from an env var.** Two parents on one
+  machine share a shell; a ``$ICDEV_DOMAIN=ft`` exported once would make the
+  IT checkout load FT's database. The file found next to the code (or, for an
+  installed kernel, in the current directory) is the only authority.
+* **A missing file is NOT an error by default.** The published wheel and every
+  project scaffolded by ``icdev init`` have no declaration and must keep
+  working byte-for-byte. They receive :data:`BUILTIN_DEFAULT`, which encodes
+  ICDEV[IT]'s constants as they stood on 2026-08-21 and reports
+  ``source == "builtin_default"`` so ``icdev status`` can say so. Set
+  ``ICDEV_REQUIRE_DOMAIN=1`` on a deployment that must refuse to start
+  undeclared.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Mapping
+
+from icdev.core.paths import DOMAIN_FILE, repo_root
+
+REQUIRE_DOMAIN_ENV = "ICDEV_REQUIRE_DOMAIN"
+SCHEMA_VERSION = 1
+
+#: ICDEV[IT] as it stood before any parent declared itself. Used when no
+#: ``icdev_domain.yaml`` is found; MUST match the checked-in file's values.
+BUILTIN_DEFAULT: dict[str, Any] = {
+    "schema_version": SCHEMA_VERSION,
+    "domain": {"key": "it", "name": "ICDEV[IT]", "env_prefix": "ICDEV"},
+    "paths": {"data": "data", "forge": ["goals", "args", "context", "hardprompts"]},
+    "db": {
+        "backend": "postgresql",
+        "name_env": "ICDEV_PG_DATABASE",
+        "dsn_env": "ICDEV_DATABASE_URL",
+        "sqlite_path_env": "ICDEV_DB_PATH",
+        "databases": ["icdev"],
+        "migrations": ["tools/db/migrations"],
+    },
+    "sensitivity": {
+        "column": "classification",
+        "labels_file": "args/classification_profiles.yaml",
+        "default": "public",
+        "egress_restricted": ["cui", "cui_sp_cti", "secret", "itar"],
+        "levels": ["IL2", "IL4", "IL5", "IL6"],
+    },
+    "components": "args/component_registry.yaml",
+    "reflexes": {"packs": []},
+    "dashboard": {"port": 5050, "blueprints": "registry"},
+    "kanban": {"board": "it", "external_repos": "args/kanban_external_repos.yaml"},
+    "mcp": {"servers": ["core", "compliance", "devsecops", "builder", "knowledge", "maintenance"]},
+    "trust": {"citation_required": True, "promotion_gates": ["coherence", "gated_tests"]},
+    "ci": {
+        "gated_lists": "args/ci_test_files",
+        "compat_suite": "args/ci_test_files/core_compat.txt",
+        "census_dir": "args",
+    },
+}
+
+_KEY_CHARS = set("abcdefghijklmnopqrstuvwxyz0123456789_")
+
+
+class DomainError(RuntimeError):
+    """The declaration is missing when required, unreadable, or invalid."""
+
+
+@dataclass(frozen=True)
+class DbDeclaration:
+    backend: str
+    name_env: str
+    dsn_env: str
+    sqlite_path_env: str
+    databases: tuple[str, ...]
+    migrations: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class SensitivityDeclaration:
+    column: str
+    labels_file: str
+    default: str
+    egress_restricted: tuple[str, ...]
+    levels: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class Domain:
+    key: str
+    name: str
+    env_prefix: str
+    root: Path
+    source: str  # "file" | "builtin_default"
+    path: Path | None
+    db: DbDeclaration
+    sensitivity: SensitivityDeclaration
+    data_dir: str = "data"
+    forge_dirs: tuple[str, ...] = ("goals", "args", "context", "hardprompts")
+    components: str = "args/component_registry.yaml"
+    reflex_packs: tuple[str, ...] = ()
+    dashboard_port: int = 5050
+    dashboard_blueprints: str = "registry"
+    kanban_board: str = "it"
+    kanban_external_repos: str = "args/kanban_external_repos.yaml"
+    mcp_servers: tuple[str, ...] = ()
+    trust: Mapping[str, Any] = field(default_factory=dict)
+    ci: Mapping[str, Any] = field(default_factory=dict)
+    raw: Mapping[str, Any] = field(default_factory=dict, repr=False, compare=False)
+
+    def env(self, suffix: str) -> str:
+        """Name of this parent's env var for ``suffix`` (``env("PG_DATABASE")``)."""
+        return f"{self.env_prefix}_{suffix}"
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "key": self.key,
+            "name": self.name,
+            "env_prefix": self.env_prefix,
+            "root": str(self.root),
+            "source": self.source,
+            "path": str(self.path) if self.path else None,
+            "db": {
+                "backend": self.db.backend,
+                "name_env": self.db.name_env,
+                "dsn_env": self.db.dsn_env,
+                "databases": list(self.db.databases),
+            },
+            "dashboard_port": self.dashboard_port,
+            "kanban_board": self.kanban_board,
+        }
+
+
+def _require(mapping: Mapping[str, Any], key: str, where: str) -> Any:
+    if key not in mapping or mapping[key] in (None, ""):
+        raise DomainError(f"{where}: missing required field {key!r}")
+    return mapping[key]
+
+
+def _tuple(value: Any, where: str) -> tuple[str, ...]:
+    if value is None:
+        return ()
+    if isinstance(value, (str, bytes)) or not hasattr(value, "__iter__"):
+        raise DomainError(f"{where}: expected a list, got {type(value).__name__}")
+    return tuple(str(v) for v in value)
+
+
+def parse_domain(data: Mapping[str, Any], *, root: Path, source: str, path: Path | None) -> Domain:
+    """Validate a declaration mapping and build a :class:`Domain`."""
+    if not isinstance(data, Mapping):
+        raise DomainError(f"{path or source}: top level must be a mapping")
+    version = data.get("schema_version", SCHEMA_VERSION)
+    if version != SCHEMA_VERSION:
+        raise DomainError(
+            f"{path or source}: schema_version {version!r} is not supported "
+            f"(this core reads {SCHEMA_VERSION})"
+        )
+    dom = _require(data, "domain", str(path or source))
+    key = str(_require(dom, "key", "domain")).strip()
+    if not key or set(key) - _KEY_CHARS or key[0].isdigit():
+        raise DomainError(
+            f"domain.key {key!r} must be lowercase [a-z0-9_] and start with a letter"
+        )
+    env_prefix = str(_require(dom, "env_prefix", "domain")).strip()
+    if not env_prefix.isidentifier() or env_prefix != env_prefix.upper():
+        raise DomainError(f"domain.env_prefix {env_prefix!r} must be an UPPERCASE identifier")
+
+    db_raw = _require(data, "db", str(path or source))
+    db = DbDeclaration(
+        backend=str(db_raw.get("backend", "postgresql")),
+        name_env=str(db_raw.get("name_env", f"{env_prefix}_PG_DATABASE")),
+        dsn_env=str(db_raw.get("dsn_env", f"{env_prefix}_DATABASE_URL")),
+        sqlite_path_env=str(db_raw.get("sqlite_path_env", f"{env_prefix}_DB_PATH")),
+        databases=_tuple(db_raw.get("databases"), "db.databases"),
+        migrations=_tuple(db_raw.get("migrations"), "db.migrations"),
+    )
+    sens_raw = data.get("sensitivity") or {}
+    sensitivity = SensitivityDeclaration(
+        column=str(sens_raw.get("column", "classification")),
+        labels_file=str(sens_raw.get("labels_file", "")),
+        default=str(sens_raw.get("default", "public")),
+        egress_restricted=_tuple(sens_raw.get("egress_restricted"), "sensitivity.egress_restricted"),
+        levels=_tuple(sens_raw.get("levels"), "sensitivity.levels"),
+    )
+    paths = data.get("paths") or {}
+    dashboard = data.get("dashboard") or {}
+    kanban = data.get("kanban") or {}
+    port = dashboard.get("port", 5050)
+    if not isinstance(port, int) or isinstance(port, bool) or not (1 <= port <= 65535):
+        raise DomainError(f"dashboard.port {port!r} must be an integer in 1..65535")
+    return Domain(
+        key=key,
+        name=str(dom.get("name", key)),
+        env_prefix=env_prefix,
+        root=root,
+        source=source,
+        path=path,
+        db=db,
+        sensitivity=sensitivity,
+        data_dir=str(paths.get("data", "data")),
+        forge_dirs=_tuple(paths.get("forge", BUILTIN_DEFAULT["paths"]["forge"]), "paths.forge"),
+        components=str(data.get("components", "args/component_registry.yaml")),
+        reflex_packs=_tuple((data.get("reflexes") or {}).get("packs"), "reflexes.packs"),
+        dashboard_port=port,
+        dashboard_blueprints=str(dashboard.get("blueprints", "registry")),
+        kanban_board=str(kanban.get("board", key)),
+        kanban_external_repos=str(kanban.get("external_repos", "args/kanban_external_repos.yaml")),
+        mcp_servers=_tuple((data.get("mcp") or {}).get("servers"), "mcp.servers"),
+        trust=dict(data.get("trust") or {}),
+        ci=dict(data.get("ci") or {}),
+        raw=dict(data),
+    )
+
+
+def _read_yaml(path: Path) -> Mapping[str, Any]:
+    import yaml  # local import: keep module import free of third-party deps
+
+    try:
+        loaded = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except (OSError, yaml.YAMLError) as exc:
+        raise DomainError(f"{path}: cannot read declaration ({exc})") from exc
+    if loaded is None:
+        raise DomainError(f"{path}: declaration is empty")
+    return loaded
+
+
+def load_domain(
+    path: str | os.PathLike[str] | None = None,
+    *,
+    anchor: str | os.PathLike[str] | None = None,
+    require: bool | None = None,
+) -> Domain:
+    """Load the declaration that governs this process.
+
+    ``path`` forces a specific file (tests, tooling). Otherwise the file is
+    ``<repo_root(anchor)>/icdev_domain.yaml``. When absent, the builtin IT
+    default is returned unless ``require`` (or ``$ICDEV_REQUIRE_DOMAIN``) says
+    to refuse.
+    """
+    if path is not None:
+        p = Path(path).resolve()
+        if not p.is_file():
+            raise DomainError(f"{p}: declaration not found")
+        return parse_domain(_read_yaml(p), root=p.parent, source="file", path=p)
+
+    root = repo_root(anchor)
+    p = root / DOMAIN_FILE
+    if p.is_file():
+        return parse_domain(_read_yaml(p), root=root, source="file", path=p)
+
+    if require is None:
+        require = os.environ.get(REQUIRE_DOMAIN_ENV, "").strip().lower() in ("1", "true", "yes")
+    if require:
+        raise DomainError(
+            f"no {DOMAIN_FILE} at {root} and {REQUIRE_DOMAIN_ENV} is set — "
+            "this deployment refuses to run undeclared"
+        )
+    return parse_domain(BUILTIN_DEFAULT, root=root, source="builtin_default", path=None)

icdev/core/paths.py

@@ -0,0 +1,179 @@
+# CUI // SP-CTI
+"""One repository-root resolver for every ICDEV parent.
+
+Three resolvers existed before this module and agreed only by accident:
+``icdev/_paths.py`` (``ICDEV_PROJECT_ROOT`` -> walk up for ``pyproject.toml``
+-> ``icdev/data``), ``tools/llm/config_path.py`` (``ICDEV_LLM_CONFIG`` -> walk
+up -> packaged copy) and ``tools/db/storage.py::_resolve_repo_base``
+(``pyproject.toml`` / ``.git`` marker, with a name-based fallback). Each public
+name survives as a thin delegate onto this module, so no call site changes.
+
+Resolution order, documented once::
+
+    1. $ICDEV_PROJECT_ROOT              explicit override (must be a directory)
+    2. the SOURCE checkout that holds the calling file — the nearest ancestor
+       of ``anchor`` carrying icdev_domain.yaml, pyproject.toml or .git
+    3. the nearest icdev_domain.yaml walking up from the CURRENT DIRECTORY —
+       the pip-installed case, where the kernel lives in site-packages and is
+       serving whichever parent the process was started in
+    4. the packaged fallback: the ``icdev/`` package directory itself
+
+Step 2 comes BEFORE step 3 on purpose, and it is a deliberate deviation from
+the first draft of the design. A session's shell resets its working directory
+to the main checkout after every command, and several worktrees of the same
+repository are live at once on one machine; a source checkout that took its
+root from CWD would silently bind a worktree's code to another checkout's
+data — the exact cross-load the identity check exists to refuse. CWD is
+consulted only when the code itself is not in a source checkout.
+
+A "source checkout" is recognised by a MARKER FILE, never by a directory
+NAME: ``_resolve_repo_base`` used to compare names and over-walked on GitHub
+Actions, whose workspace is ``/home/runner/work/icdev/icdev``.
+"""
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import Iterable
+
+DOMAIN_FILE = "icdev_domain.yaml"
+PROJECT_ROOT_ENV = "ICDEV_PROJECT_ROOT"
+
+#: Markers that identify a source checkout, most specific first.
+SOURCE_MARKERS: tuple[str, ...] = (DOMAIN_FILE, "pyproject.toml", ".git")
+
+_ICDEV_PKG_DIR = Path(__file__).resolve().parent.parent  # icdev/
+_PACKAGED_DATA_DIR = _ICDEV_PKG_DIR / "data"
+
+
+def _is_installed(path: Path) -> bool:
+    """True when ``path`` lives under site-packages or the interpreter prefix."""
+    p = str(path).replace("\\", "/").lower()
+    if "site-packages" in p or "dist-packages" in p:
+        return True
+    try:
+        prefix = str(Path(sys.prefix).resolve()).replace("\\", "/").lower()
+    except OSError:  # pragma: no cover — sys.prefix always resolves in practice
+        return False
+    return bool(prefix) and p.startswith(prefix + "/")
+
+
+def _walk_up(start: Path, markers: Iterable[str]) -> Path | None:
+    """Return the nearest directory at or above ``start`` holding any marker."""
+    markers = tuple(markers)
+    start = start if start.is_dir() else start.parent
+    for candidate in (start, *start.parents):
+        for m in markers:
+            if (candidate / m).exists():
+                return candidate
+    return None
+
+
+def find_domain_file(start: Path | None = None) -> Path | None:
+    """Return the nearest ``icdev_domain.yaml`` at or above ``start`` (default CWD)."""
+    base = _walk_up(Path(start or Path.cwd()).resolve(), (DOMAIN_FILE,))
+    return None if base is None else base / DOMAIN_FILE
+
+
+def repo_root(anchor: str | os.PathLike[str] | None = None) -> Path:
+    """Return the repository root this process should treat as home.
+
+    ``anchor`` is the calling module's ``__file__`` (or any path inside the
+    checkout). When omitted, the ``icdev`` package directory is used, which is
+    correct for the kernel's own modules and for the wheel.
+    """
+    env = os.environ.get(PROJECT_ROOT_ENV, "").strip()
+    if env:
+        p = Path(env).expanduser()
+        if p.is_dir():
+            return p.resolve()
+
+    anchor_path = Path(anchor).resolve() if anchor is not None else _ICDEV_PKG_DIR
+    if not _is_installed(anchor_path):
+        found = _walk_up(anchor_path, SOURCE_MARKERS)
+        if found is not None:
+            return found
+
+    cwd_root = _walk_up(Path.cwd().resolve(), (DOMAIN_FILE,))
+    if cwd_root is not None:
+        return cwd_root
+
+    return _ICDEV_PKG_DIR
+
+
+def data_path(name: str, anchor: str | os.PathLike[str] | None = None) -> Path:
+    """Resolve a FORGE data directory (args, context, goals, hardprompts, ...).
+
+    Falls back to the packaged ``icdev/data/<name>`` when the repository root
+    has no such directory (the wheel case), then to a CWD-relative path so a
+    caller that only wants to CREATE the directory still gets a sane answer.
+    """
+    root = repo_root(anchor)
+    candidate = root / name
+    if candidate.is_dir():
+        return candidate
+    packaged = _PACKAGED_DATA_DIR / name
+    if packaged.is_dir():
+        return packaged
+    return Path(name)
+
+
+def config_path(
+    relpath: str | os.PathLike[str],
+    *,
+    env: str | None = None,
+    anchor: str | os.PathLike[str] | None = None,
+    packaged: str | os.PathLike[str] | None = None,
+) -> Path:
+    """Resolve one configuration file: ``$env`` -> ``<repo_root>/relpath`` -> packaged.
+
+    ``relpath`` is relative to the repository root (``args/llm_config.yaml``).
+    ``packaged`` is the last-resort copy shipped inside the package; when not
+    given, ``icdev/data/<relpath>`` is tried and finally ``<repo_root>/relpath``
+    is returned even if it does not exist, so the caller's error names the
+    path that SHOULD have been there.
+    """
+    if env:
+        override = os.environ.get(env, "").strip()
+        if override:
+            return Path(override).expanduser().resolve()
+    rel = Path(relpath)
+    candidate = repo_root(anchor) / rel
+    if candidate.is_file():
+        return candidate
+    if packaged is not None:
+        return Path(packaged)
+    pkg = _PACKAGED_DATA_DIR / rel
+    if pkg.is_file():
+        return pkg
+    return candidate
+
+
+def describe(anchor: str | os.PathLike[str] | None = None) -> dict:
+    """Diagnostics for ``icdev status``: which root won, and why."""
+    env = os.environ.get(PROJECT_ROOT_ENV, "").strip()
+    anchor_path = Path(anchor).resolve() if anchor is not None else _ICDEV_PKG_DIR
+    installed = _is_installed(anchor_path)
+    source = None if installed else _walk_up(anchor_path, SOURCE_MARKERS)
+    cwd_root = _walk_up(Path.cwd().resolve(), (DOMAIN_FILE,))
+    root = repo_root(anchor)
+    if env and Path(env).expanduser().is_dir():
+        how = "env"
+    elif source is not None and source == root:
+        how = "source_checkout"
+    elif cwd_root is not None and cwd_root == root:
+        how = "cwd_domain_file"
+    else:
+        how = "packaged"
+    return {
+        "root": str(root),
+        "source": how,
+        "env_var": PROJECT_ROOT_ENV,
+        "env_value": env or None,
+        "anchor": str(anchor_path),
+        "anchor_installed": installed,
+        "source_candidate": str(source) if source else None,
+        "cwd_candidate": str(cwd_root) if cwd_root else None,
+        "domain_file": str(root / DOMAIN_FILE) if (root / DOMAIN_FILE).is_file() else None,
+    }