chipgraph 0.1.0__py3-none-any.whl

chipgraph/core/config/models.py

@@ -0,0 +1,845 @@
+"""The `Profile` model: a project's layered configuration, and the personal `UserConfig`.
+
+See DESIGN.md 8.3, 8.4 and 8.6: a project is configured by exactly one `.chipgraph.yml`,
+which may `extend` organization rules, presets and shared git rule repos; a personal
+`~/.config/chipgraph/user.yml` may only adjust individual experience, never artifact
+conventions (layout, naming, templates, checks).
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from typing import Any, Literal, Self
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+from chipgraph.core.contracts.types import DataLabel, ModelTier
+
+Level = Literal["L1", "L2", "L3", "L4", "L5"]
+"""An autonomy level from L1 (human does everything) to L5 (never allowed, see DESIGN 8.3)."""
+
+
+def _reject_level_5(autonomy: dict[str, Level]) -> None:
+    for area, level in autonomy.items():
+        if level == "L5":
+            raise ValueError(f"autonomy[{area!r}] = 'L5' is never allowed")
+
+
+class SourceCfg(BaseModel):
+    """A single spec source: a file path and its format."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    path: str = Field(description="Path to the source file, relative to the project root.")
+    format: str = Field(description="Format of the source, e.g. 'qsoc-contract'.")
+
+
+_DEFAULT_REQ_ID_PATTERN = r"REQ-[A-Z][A-Z0-9_]*-\d+"
+
+
+class RequirementsCfg(BaseModel):
+    """How requirement IDs are found in text specs (DECISIONS D37).
+
+    By default REQ-IDs are declared in the spec and matched by `id_pattern`. The temporary
+    `infer: verification` mode also treats each numbered item of a spec's "Verification"
+    section as a requirement, keyed by block and content hash rather than by its number.
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    id_pattern: str = Field(
+        default=_DEFAULT_REQ_ID_PATTERN,
+        description=(
+            "Regex a declared REQ-ID must match (whole ID). '{block}' and '{BLOCK}' are "
+            "replaced by the block name, lower- and upper-case, before compiling."
+        ),
+    )
+    infer: Literal["off", "verification"] = Field(
+        default="off",
+        description=(
+            "Temporary mode: 'verification' infers one requirement per numbered item of the "
+            "spec section titled `infer_heading`, for specs without REQ-IDs."
+        ),
+    )
+    infer_heading: str = Field(
+        default="Verification",
+        description="Title of the section items are inferred from, without its number.",
+    )
+
+    @field_validator("id_pattern")
+    @classmethod
+    def _pattern_compiles(cls, value: str) -> str:
+        probe = value.replace("{block}", "x").replace("{BLOCK}", "X")
+        try:
+            re.compile(probe)
+        except re.error as exc:
+            raise ValueError(f"id_pattern is not a valid regex: {exc}") from exc
+        return value
+
+    def id_regex(self, block: str | None = None) -> re.Pattern[str]:
+        """The compiled `id_pattern`, with `{block}`/`{BLOCK}` filled in for `block`."""
+        pattern = self.id_pattern
+        if block is not None:
+            pattern = pattern.replace("{block}", re.escape(block.lower()))
+            pattern = pattern.replace("{BLOCK}", re.escape(block.upper()))
+        elif "{block}" in pattern or "{BLOCK}" in pattern:
+            raise ValueError("id_pattern uses '{block}'/'{BLOCK}'; a block name is required")
+        return re.compile(pattern)
+
+
+_DEFAULT_REGISTER_ACCESS = ("RW", "RO", "WO", "W1C", "RSVD")
+
+
+class SpecCfg(BaseModel):
+    """Where the chip-level spec and per-IP specs live."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    chip: SourceCfg | None = Field(default=None, description="The chip-level spec source.")
+    ip_dir: str | None = Field(default=None, description="Directory containing per-IP specs.")
+    requirements: RequirementsCfg = Field(
+        default_factory=RequirementsCfg,
+        description="How requirement IDs are found in text specs (D37).",
+    )
+    register_access: tuple[str, ...] = Field(
+        default=_DEFAULT_REGISTER_ACCESS,
+        description=(
+            "Access modes a register-map cell may use (case-insensitive). The MAS "
+            "extractor rejects any other mode. Extend it for IP with extra modes, e.g. "
+            "'RW0C'/'RW1C' for OpenTitan-derived blocks."
+        ),
+    )
+
+    @field_validator("register_access")
+    @classmethod
+    def _access_non_empty(cls, value: tuple[str, ...]) -> tuple[str, ...]:
+        if not value:
+            raise ValueError("register_access must list at least one access mode")
+        return value
+
+
+class AdapterCfg(BaseModel):
+    """An adapter selection for a capability; extra keys are the adapter's own options."""
+
+    model_config = ConfigDict(extra="allow", frozen=True)
+
+    use: str = Field(description="The adapter implementation to use, e.g. 'cmd', 'edalize'.")
+
+
+class NamingCfg(BaseModel):
+    """The project's naming rules and the checker that enforces them."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    rules: str | None = Field(
+        default=None, description="Reference to naming rules, e.g. 'org:qnsc/naming-v1.yml'."
+    )
+    checker: AdapterCfg | None = Field(default=None, description="Adapter that checks naming.")
+
+
+class TargetCfg(BaseModel):
+    """What kind of thing is being built, and on which process."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    kind: Literal["asic", "fpga", "ip"] = Field(
+        default="asic", description="The kind of target being built."
+    )
+    pdk: str | None = Field(default=None, description="The process design kit, if any.")
+
+
+class ModelsCfg(BaseModel):
+    """LLM providers and the model assigned to each tier."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    providers: dict[str, dict[str, str]] = Field(
+        default_factory=dict, description="LLM provider configuration by provider name."
+    )
+    tiers: dict[ModelTier, str] = Field(
+        default_factory=dict, description="Model id used for each capability/cost tier."
+    )
+    alt: dict[ModelTier, str] = Field(
+        default_factory=dict, description="Alternate model or provider per tier (see DESIGN D24)."
+    )
+
+
+class DataCfg(BaseModel):
+    """Default data sensitivity and how NDA content is isolated."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    default: DataLabel = Field(default="internal", description="Default data sensitivity label.")
+    nda_paths: tuple[str, ...] = Field(
+        default=(), description="Glob patterns of paths labeled 'nda'."
+    )
+    nda_model: Literal["block", "local"] = Field(
+        default="block", description="How NDA content is kept away from cloud models."
+    )
+
+
+class StateCfg(BaseModel):
+    """Where run state (journal, cache, trace) is kept."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    backend: str = Field(
+        default="local",
+        description="State backend: 'local', 'branch:<name>', or 'repo:<url>'.",
+    )
+
+
+class DecisionsCfg(BaseModel):
+    """Where gate approvals and waivers are kept."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    store: Literal["repo", "state"] = Field(
+        default="repo", description="Where gate/waiver decisions are stored."
+    )
+
+
+FANOUT_DEFAULT_MAX_PARALLEL = 4
+"""The most fan-out branches run at once when the profile does not say (capped by CPUs)."""
+
+
+class FanoutCfg(BaseModel):
+    """How a fan-out runs its branches (DESIGN 5.3): how many at once, how long each may take.
+
+    `max_parallel` unset means `min(4, cpu count)`; a profile sets it lower for an API rate
+    limit or an EDA license count. `branch_timeout_s` unset means no limit.
+
+    `isolate` (default **false**) puts each dispatched agent task in its own workspace
+    outside the user's tree: a worktree at HEAD with the task's declared inputs copied
+    in. The subagent writes there, not the user's files. Nothing a subagent does can
+    touch the user's tree until the engine accepts the task and copies **its outputs
+    only** back. This is the F2/F3 isolation rules for parallel agent tasks.
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    isolate: bool = Field(
+        default=False,
+        description=(
+            "Run each agent task in an isolated workspace. When true, a task gets its own "
+            "worktree at HEAD, seeded with the task's inputs; the subagent writes there, "
+            "and outputs are copied back only on acceptance. Default false: tasks write "
+            "the user's tree directly, as before."
+        ),
+    )
+    max_parallel: int | None = Field(
+        default=None,
+        ge=1,
+        description="Branches run at once; unset means min(4, cpu count).",
+    )
+    branch_timeout_s: float | None = Field(
+        default=None,
+        gt=0,
+        description="Seconds a branch may run before it is stopped; unset means no limit.",
+    )
+
+    def effective_max_parallel(self, cpu_count: int | None = None) -> int:
+        """`max_parallel`, or `min(4, cpu_count)` (the machine's CPUs when not given)."""
+        if self.max_parallel is not None:
+            return self.max_parallel
+        cpus = cpu_count if cpu_count is not None else (os.cpu_count() or 1)
+        return max(1, min(FANOUT_DEFAULT_MAX_PARALLEL, cpus))
+
+
+class SelectCfg(BaseModel):
+    """Optional best-of-N (DESIGN 5.3, F6): N candidates of one rule, chosen by its checks.
+
+    A rule opts in by its id in `rules` (or an instance parameter `best_of`); every other
+    rule runs once, as before. `n` is the default N for an opted-in rule, `max_n` the hard
+    cap on any N. The N candidates share ONE budget: `budget_factor` times the rule's
+    single-run budget (tries, tokens and cost), not N times it.
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    n: int = Field(default=2, ge=1, description="Candidates for an opted-in rule (default N).")
+    max_n: int = Field(default=3, ge=1, description="Hard cap on N, whatever asks for more.")
+    budget_factor: float = Field(
+        default=1.5,
+        gt=0,
+        description="The candidates' shared budget, as a multiple of one run's budget.",
+    )
+    rules: dict[str, int] = Field(
+        default_factory=dict,
+        description="Rule id -> N for the rules that opt in to best-of-N.",
+    )
+
+    @field_validator("rules")
+    @classmethod
+    def _check_rules(cls, value: dict[str, int]) -> dict[str, int]:
+        for rule_id, n in value.items():
+            if n < 1:
+                raise ValueError(f"rules[{rule_id!r}] = {n}: N must be >= 1")
+        return value
+
+    def effective_n(self, requested: int | None = None) -> int:
+        """`requested` (or `n`), capped at `max_n`; at least 1."""
+        wanted = requested if requested is not None else self.n
+        return max(1, min(wanted, self.max_n))
+
+
+DecideTier = Literal["small", "large"]
+"""A model tier `decide()` may ask: the small model first, the large one when unsure."""
+
+_DECIDE_TIER_ORDER: tuple[DecideTier, ...] = ("small", "large")
+
+
+def _check_tiers(value: tuple[DecideTier, ...] | None) -> tuple[DecideTier, ...] | None:
+    if value is None:
+        return None
+    if len(set(value)) != len(value):
+        raise ValueError(f"enabled_tiers lists a tier more than once: {list(value)}")
+    # Always ask in escalation order, whatever order the profile lists them in.
+    return tuple(t for t in _DECIDE_TIER_ORDER if t in value)
+
+
+class DecideOverride(BaseModel):
+    """`decide()` settings for the questions whose id starts with one prefix.
+
+    Only the fields that are set replace the project's (or a shorter prefix's) values.
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    small_min_confidence: float | None = Field(
+        default=None, ge=0, le=1, description="Overrides `small_min_confidence`."
+    )
+    large_min_confidence: float | None = Field(
+        default=None, ge=0, le=1, description="Overrides `large_min_confidence`."
+    )
+    enabled_tiers: tuple[DecideTier, ...] | None = Field(
+        default=None, description="Overrides `enabled_tiers`."
+    )
+
+    @field_validator("enabled_tiers")
+    @classmethod
+    def _tiers_unique(cls, value: tuple[DecideTier, ...] | None) -> tuple[DecideTier, ...] | None:
+        return _check_tiers(value)
+
+
+class DecideSettings(BaseModel):
+    """The effective `decide()` settings for one question (see `DecideCfg.for_question`)."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    small_min_confidence: float = Field(ge=0, le=1)
+    large_min_confidence: float = Field(ge=0, le=1)
+    enabled_tiers: tuple[DecideTier, ...]
+
+    def threshold(self, tier: DecideTier) -> float:
+        """The confidence an answer from `tier` needs to be accepted without escalating."""
+        return self.small_min_confidence if tier == "small" else self.large_min_confidence
+
+
+class DecideCfg(BaseModel):
+    """Thresholds of the fast decision layer `decide()` (DESIGN 5.4).
+
+    A question no rule answers goes to the small model; an answer under
+    `small_min_confidence` goes on to the large model; a large answer under
+    `large_min_confidence` is still returned, but logged as low confidence (AI never
+    blocks: the caller decides). `overrides` adjust this per question-id prefix, e.g.
+    `overrides: { "triage.": { small_min_confidence: 0.9 } }`; every matching prefix
+    applies, shortest first, so the longest prefix wins.
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    small_min_confidence: float = Field(
+        default=0.8,
+        ge=0,
+        le=1,
+        description="Confidence a small-model answer needs; under it, ask the large model.",
+    )
+    large_min_confidence: float = Field(
+        default=0.5,
+        ge=0,
+        le=1,
+        description="Confidence under which a large-model answer is logged as low confidence.",
+    )
+    enabled_tiers: tuple[DecideTier, ...] = Field(
+        default=_DECIDE_TIER_ORDER,
+        description="Model tiers decide() may ask, e.g. ['small'] to never use the large one.",
+    )
+    overrides: dict[str, DecideOverride] = Field(
+        default_factory=dict,
+        description="Per question-id prefix overrides, e.g. 'triage.'.",
+    )
+
+    @field_validator("enabled_tiers")
+    @classmethod
+    def _tiers_unique(cls, value: tuple[DecideTier, ...]) -> tuple[DecideTier, ...]:
+        checked = _check_tiers(value)
+        return checked if checked is not None else ()
+
+    @field_validator("overrides")
+    @classmethod
+    def _prefixes_non_empty(cls, value: dict[str, DecideOverride]) -> dict[str, DecideOverride]:
+        if "" in value:
+            raise ValueError("an overrides prefix must not be empty; set the top-level fields")
+        return value
+
+    def for_question(self, question_id: str) -> DecideSettings:
+        """The settings for `question_id`: the defaults, then each matching prefix's override."""
+        small = self.small_min_confidence
+        large = self.large_min_confidence
+        tiers = self.enabled_tiers
+        for prefix in sorted(p for p in self.overrides if question_id.startswith(p)):
+            override = self.overrides[prefix]
+            if override.small_min_confidence is not None:
+                small = override.small_min_confidence
+            if override.large_min_confidence is not None:
+                large = override.large_min_confidence
+            if override.enabled_tiers is not None:
+                tiers = override.enabled_tiers
+        return DecideSettings(
+            small_min_confidence=small, large_min_confidence=large, enabled_tiers=tiers
+        )
+
+
+class PathRule(BaseModel):
+    """An exception for one path glob: checks toggled off, writes denied, and why."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    checks: dict[str, Literal["on", "off"]] = Field(
+        default_factory=dict, description="Per-check on/off override for this path."
+    )
+    write: Literal["allow", "deny"] = Field(
+        default="allow", description="Whether agents may write files under this path."
+    )
+    reason: str | None = Field(
+        default=None,
+        description="Why this exception exists; required when a check is off or write is denied.",
+    )
+
+    @field_validator("checks", mode="before")
+    @classmethod
+    def _yaml_booleans_to_on_off(cls, value: object) -> object:
+        # YAML 1.1 (PyYAML) reads an unquoted `off` / `on` as a boolean. Accept both
+        # spellings, so `checks: { naming: off }` works as the examples in DESIGN.md show.
+        if isinstance(value, dict):
+            return {
+                k: ("on" if v is True else "off" if v is False else v) for k, v in value.items()
+            }
+        return value
+
+    @model_validator(mode="after")
+    def _require_reason_when_relaxed(self) -> Self:
+        relaxed = self.write == "deny" or any(v == "off" for v in self.checks.values())
+        if relaxed and not self.reason:
+            raise ValueError(
+                "a PathRule that turns a check off or denies write must give a 'reason'"
+            )
+        return self
+
+
+class BlockSpecOverride(BaseModel):
+    """The part of `spec` a block may override: how its requirement IDs are found.
+
+    Only the fields that are set replace the project's, e.g. a block whose spec also
+    carries another prefix: `blocks.rom.spec.requirements.id_pattern: '(?:ROM|BOOT)_\\d{3}'`
+    keeps the project's `infer` mode.
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    requirements: RequirementsCfg | None = Field(
+        default=None, description="Requirement-ID settings for this block (D37)."
+    )
+
+
+_IDENTIFIER_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_$]*$")
+
+
+class WrapperCfg(BaseModel):
+    """A wrapper module around a third-party IP of a block, written as a source the
+    project's generator expands (DESIGN 8.2; task M2-12).
+
+    The IP's files are never edited: the wrapper instantiates `vendor_module`, declared in
+    `vendor_files`, and maps its ports to the project's names. `exemplar` is an existing
+    wrapper source whose structure a new wrapper imitates.
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    name: str = Field(description="The wrapper module's name (also its file names).")
+    vendor_module: str = Field(description="The IP's module the wrapper instantiates.")
+    vendor_files: tuple[str, ...] = Field(
+        min_length=1, description="Repo-relative files that declare the IP's module."
+    )
+    exemplar: str | None = Field(
+        default=None, description="A repo-relative wrapper source to imitate, if any."
+    )
+
+    @field_validator("name", "vendor_module")
+    @classmethod
+    def _check_identifier(cls, value: str) -> str:
+        if not _IDENTIFIER_RE.match(value):
+            raise ValueError(f"{value!r} is not a module name")
+        return value
+
+    @field_validator("vendor_files")
+    @classmethod
+    def _check_files(cls, value: tuple[str, ...]) -> tuple[str, ...]:
+        for path in value:
+            _check_repo_path(path)
+        if len(set(value)) != len(value):
+            raise ValueError("a vendor file is listed more than once")
+        return value
+
+    @field_validator("exemplar")
+    @classmethod
+    def _check_exemplar(cls, value: str | None) -> str | None:
+        return None if value is None else _check_repo_path(value)
+
+    @model_validator(mode="after")
+    def _check_names(self) -> Self:
+        if self.name == self.vendor_module:
+            raise ValueError(
+                f"wrapper {self.name!r} has the name of the module it wraps; give it its own"
+            )
+        return self
+
+
+def _check_repo_path(path: str) -> str:
+    parts = path.replace("\\", "/").split("/")
+    if not path or path.startswith("/") or re.match(r"^[A-Za-z]:", path) or ".." in parts:
+        raise ValueError(f"{path!r} is not a repo-relative path")
+    return path
+
+
+class BlockOverride(BaseModel):
+    """Per-block overrides: adapters, layout, autonomy, paths, spec requirements, instances,
+    and the block's wrappers.
+
+    `instances` names the memory-map instances of this block, treated as an IP (D38):
+    e.g. `blocks.timer.instances: [timer_0, timer_1]`. Each name is a single model-key
+    part (non-empty, no ':' or '.') and must be unique within the block. With no
+    `instances`, the block matches only a same-named instance in the chip contract.
+
+    `wrappers` lists the block's wrappers around third-party IP (`WrapperCfg`); like
+    `instances` it is a block-level fact, not merged into the block's profile.
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    adapters: dict[str, AdapterCfg] = Field(
+        default_factory=dict, description="Per-block adapter overrides."
+    )
+    layout: dict[str, str | tuple[str, ...]] = Field(
+        default_factory=dict, description="Per-block layout overrides."
+    )
+    autonomy: dict[str, Level] = Field(
+        default_factory=dict, description="Per-block autonomy overrides."
+    )
+    paths: dict[str, PathRule] = Field(
+        default_factory=dict, description="Per-block path rule overrides."
+    )
+    spec: BlockSpecOverride = Field(
+        default_factory=BlockSpecOverride,
+        description="Per-block requirement-ID settings; only the fields set override.",
+    )
+    instances: tuple[str, ...] = Field(
+        default=(),
+        description=(
+            "Memory-map instances of this block-as-IP (D38); each a valid model-key part "
+            "(non-empty, no ':' or '.'), unique within the block."
+        ),
+    )
+    wrappers: tuple[WrapperCfg, ...] = Field(
+        default=(),
+        description="Wrappers of this block around third-party IP, each with a unique name.",
+    )
+
+    @field_validator("wrappers")
+    @classmethod
+    def _check_wrappers(cls, value: tuple[WrapperCfg, ...]) -> tuple[WrapperCfg, ...]:
+        names = [w.name for w in value]
+        repeated = sorted({n for n in names if names.count(n) > 1})
+        if repeated:
+            raise ValueError(f"wrapper {repeated[0]!r} is listed more than once")
+        return value
+
+    @field_validator("instances")
+    @classmethod
+    def _check_instances(cls, value: tuple[str, ...]) -> tuple[str, ...]:
+        seen: set[str] = set()
+        for name in value:
+            if not name:
+                raise ValueError("an instance name must not be empty")
+            if ":" in name or "." in name:
+                raise ValueError(f"instance name {name!r} must not contain ':' or '.'")
+            if name in seen:
+                raise ValueError(f"instance {name!r} is listed more than once")
+            seen.add(name)
+        return value
+
+    @model_validator(mode="after")
+    def _check_autonomy(self) -> Self:
+        _reject_level_5(dict(self.autonomy))
+        return self
+
+
+class TemplatesCfg(BaseModel):
+    """Per-block-name template overrides (DESIGN 8.6 V2)."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    override: dict[str, str] = Field(
+        default_factory=dict, description="Template block name to override file path."
+    )
+
+
+StyleKey = Literal[
+    "indent",
+    "begin",
+    "ports",
+    "reset",
+    "reset_kind",
+    "sequential",
+    "suffix",
+    "header",
+    "blank_lines",
+    "line_length",
+    "case",
+]
+"""A feature of the code style the `style` check derives from the exemplars."""
+
+STYLE_KEYS: tuple[StyleKey, ...] = (
+    "indent",
+    "begin",
+    "ports",
+    "reset",
+    "reset_kind",
+    "sequential",
+    "suffix",
+    "header",
+    "blank_lines",
+    "line_length",
+    "case",
+)
+"""Every `StyleKey`, in the order the `style` check reports them."""
+
+
+class StyleCfg(BaseModel):
+    """Code style exemplars and the formatter run after generation (DESIGN 8.6 V3)."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    exemplars: tuple[str, ...] = Field(
+        default=(), description="Paths to files whose style agents should imitate."
+    )
+    formatter: AdapterCfg | None = Field(
+        default=None, description="Adapter that formats generated code after it is written."
+    )
+    enforce: tuple[StyleKey, ...] = Field(
+        default=(),
+        description=(
+            "Style features whose deviations from the exemplars are errors (the others are "
+            "warnings): indent, begin, ports, reset, sequential, suffix, header, "
+            "blank_lines, line_length, case."
+        ),
+    )
+
+
+class EnvCfg(BaseModel):
+    """Environment modules and variables needed to run project tools (DESIGN 12.6)."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    modules: tuple[str, ...] = Field(
+        default=(), description="Environment Modules/Lmod modules to load."
+    )
+    vars: dict[str, str] = Field(
+        default_factory=dict, description="Environment variables to set, e.g. license servers."
+    )
+
+
+class PolicyCfg(BaseModel):
+    """Organization/project policy switches (DESIGN 8.6 layer authority table).
+
+    `local_plugins` is tighten-only across layers: an outer layer (e.g. the organization)
+    may set `deny` and no later layer may re-`allow` it (enforced in the loader).
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    local_plugins: Literal["allow", "deny"] = Field(
+        default="allow",
+        description="Whether the project may load local plugins from `.chipgraph/plugins/`.",
+    )
+
+
+class PlanCfg(BaseModel):
+    """Limits on a block's plan: how many dynamic nodes a Planner may propose (DESIGN 5.3).
+
+    The plan check rejects a plan over any limit, and the graph never expands one: the
+    limits bound how many rule instances an approved plan can add.
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    max_modules: int = Field(default=12, ge=1, description="Most modules one plan may list.")
+    max_depth: int = Field(
+        default=4,
+        ge=1,
+        description="Longest chain of module dependencies, counted in modules (1: none).",
+    )
+    max_total_tries: int = Field(
+        default=36, ge=1, description="Most tries the modules' budgets may add up to."
+    )
+
+
+class Profile(BaseModel):
+    """A project's full, merged configuration (DESIGN 8.3-8.4, 8.6, 12.6)."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    schema_version: Literal[1] = Field(default=1, description="Schema version of this model.")
+    project: str = Field(description="The project's name.")
+    extends: tuple[str, ...] = Field(
+        default=(),
+        description="Profiles this one extends: 'org:', 'preset:', 'path:', or 'git+'.",
+    )
+    packs: tuple[str, ...] = Field(default=(), description="Domain packs used by this project.")
+    spec: SpecCfg = Field(
+        default_factory=SpecCfg, description="Where the chip-level and per-IP specs live."
+    )
+    adapters: dict[str, AdapterCfg] = Field(
+        default_factory=dict, description="Capability name (e.g. 'lint', 'sim') to adapter config."
+    )
+    naming: NamingCfg = Field(default_factory=NamingCfg, description="Naming rules and checker.")
+    layout: dict[str, str | tuple[str, ...]] = Field(
+        default_factory=dict, description="Artifact kind to output path template(s)."
+    )
+    target: TargetCfg = Field(default_factory=TargetCfg, description="What is being built.")
+    autonomy: dict[str, Level] = Field(
+        default_factory=dict, description="Autonomy level per area, e.g. 'spec', 'rtl', 'verify'."
+    )
+    models: ModelsCfg = Field(
+        default_factory=ModelsCfg, description="LLM providers and tier assignments."
+    )
+    runtime: Literal["claude-code", "claude-agent-sdk", "generic"] = Field(
+        default="claude-code", description="Which agent runtime executes agent rules."
+    )
+    data: DataCfg = Field(
+        default_factory=DataCfg, description="Data sensitivity defaults and NDA handling."
+    )
+    reviewers: tuple[str, ...] = Field(default=(), description="Default reviewers for gates.")
+    state: StateCfg = Field(default_factory=StateCfg, description="Where run state is kept.")
+    decisions: DecisionsCfg = Field(
+        default_factory=DecisionsCfg, description="Where gate/waiver decisions are kept."
+    )
+    decide: DecideCfg = Field(
+        default_factory=DecideCfg,
+        description="Thresholds of the fast decision layer decide(): rule, small, large model.",
+    )
+    plan: PlanCfg = Field(
+        default_factory=PlanCfg,
+        description="Limits on a block's plan: modules, dependency depth, total tries.",
+    )
+    fanout: FanoutCfg = Field(
+        default_factory=FanoutCfg,
+        description="Fan-out limits: branches at once, time per branch (DESIGN 5.3).",
+    )
+    select: SelectCfg = Field(
+        default_factory=SelectCfg,
+        description="Optional best-of-N: N, its cap, the shared budget, opted-in rules (F6).",
+    )
+    paths: dict[str, PathRule] = Field(
+        default_factory=dict, description="Glob pattern to path-specific exception rule."
+    )
+    blocks: dict[str, BlockOverride] = Field(
+        default_factory=dict, description="Per-block overrides of adapters/layout/autonomy/paths."
+    )
+    templates: TemplatesCfg = Field(
+        default_factory=TemplatesCfg, description="Template block overrides."
+    )
+    style: StyleCfg = Field(
+        default_factory=StyleCfg, description="Code style exemplars and formatter."
+    )
+    plugins: tuple[str, ...] = Field(
+        default=(), description="Local plugin script paths (DESIGN 8.6 V5)."
+    )
+    policy: PolicyCfg = Field(
+        default_factory=PolicyCfg, description="Organization/project policy switches (DESIGN 8.6)."
+    )
+    workspace: str | None = Field(
+        default=None, description="Path to a workspace manifest, if part of one (DESIGN 8.7)."
+    )
+    offline: bool = Field(
+        default=False, description="Disable all outbound network use (DESIGN 12.6)."
+    )
+    env: EnvCfg = Field(
+        default_factory=EnvCfg, description="Environment modules and variables needed by tools."
+    )
+    vcs: AdapterCfg | None = Field(
+        default=None, description="Version control adapter, if not plain git."
+    )
+    review: AdapterCfg | None = Field(
+        default=None, description="Review/gate adapter, if not GitHub PRs."
+    )
+    runner: AdapterCfg | None = Field(
+        default=None, description="Job runner adapter, e.g. 'ssh', 'lsf', 'slurm'."
+    )
+    workflow_overrides: dict[str, dict[str, object]] = Field(
+        default_factory=dict, description="Per-workflow field overrides."
+    )
+    freeze: dict[str, str] = Field(
+        default_factory=dict, description="Pinned versions for reproducibility."
+    )
+
+    @model_validator(mode="after")
+    def _check_autonomy(self) -> Self:
+        _reject_level_5(dict(self.autonomy))
+        return self
+
+
+_USER_ALLOWED_KEYS = frozenset(
+    {"schema_version", "autonomy", "notify", "answer_language", "prefer_models", "editor"}
+)
+
+
+class UserConfig(BaseModel):
+    """A personal layer (`~/.config/chipgraph/user.yml`): experience only, never conventions."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    schema_version: Literal[1] = Field(default=1, description="Schema version of this model.")
+    autonomy: dict[str, Level] = Field(
+        default_factory=dict,
+        description="Personal autonomy override per area; may only lower the project's level.",
+    )
+    notify: str | None = Field(default=None, description="Notification channel, e.g. 'slack'.")
+    answer_language: str | None = Field(
+        default=None, description="Preferred language for agent answers."
+    )
+    prefer_models: dict[ModelTier, str] = Field(
+        default_factory=dict,
+        description="Preferred model per tier; must be one the project allows.",
+    )
+    editor: str | None = Field(default=None, description="Preferred editor to open files in.")
+
+    @model_validator(mode="before")
+    @classmethod
+    def _reject_project_conventions(cls, data: Any) -> Any:
+        if isinstance(data, dict):
+            unknown = sorted(set(data) - _USER_ALLOWED_KEYS)
+            if unknown:
+                raise ValueError(
+                    f"{unknown[0]!r} is a project artifact convention (naming, layout, "
+                    "template, check, ...); the user layer may not change project "
+                    "conventions (DESIGN 8.6), only personal experience settings"
+                )
+        return data
+
+    @model_validator(mode="after")
+    def _check_autonomy(self) -> Self:
+        _reject_level_5(dict(self.autonomy))
+        return self