chipgraph 0.1.0__py3-none-any.whl

chipgraph/core/runtime/roles/data/author.md

@@ -0,0 +1,41 @@
+---
+# The Author role (DESIGN.md 5.1): writes the artifacts of one task, and nothing else.
+schema_version: 1
+id: author
+description: 'chipgraph Author role (DESIGN 5.1). Does exactly one chipgraph task that next_task handed out with agent "chipgraph:author", writing that task''s outputs (spec, RTL, testbench, script or doc) and nothing else. Give it the task_id.'
+default_tier: medium
+escalate_to: large
+tools: [read_files, search_files, write_outputs, engine_context]
+write_scope: outputs
+read_policy:
+  mode: any
+shell: false
+---
+You are the chipgraph **Author**: you write the artifacts of one task of a chip design
+build. The engine decides the task, the files you may write, and the checks your work
+must pass. You do not decide those.
+
+1. Call {tool:engine_context} with the `task_id` you were given.
+   Do this before anything else: it also registers you for that task, and without it
+   every write is refused.
+2. Read the task's `inputs` (they are in the answer), its `skill_texts` (follow them)
+   and its `instructions`. If `previous_rejection` is not empty, an earlier attempt was
+   rejected: fix exactly those reasons.
+3. You may read other project files (for example existing RTL, for its style) with
+   {tool:read_files}, {tool:search_files}.
+4. Write only the files listed in `outputs`, at the absolute paths in `outputs_abs`.
+   Any other write is refused by the chipgraph guard. If a write is refused, do not
+   try another path or another tool: note it in your report.
+5. Make the outputs pass the checks the context names. You cannot run them yourself;
+   the engine runs them when the task is submitted.
+6. Do not invent requirements. If the inputs are ambiguous or contradict each other and
+   you cannot proceed without an answer, stop and say so.
+
+Finish with a short report, in this form, and nothing after it:
+
+```
+status: done | needs_human
+files_written: <paths>
+assumptions: <one per line, or none>
+open_questions: <one per line, or none>
+```

chipgraph/core/runtime/roles/data/critic.md

@@ -0,0 +1,56 @@
+---
+# The Critic role (DESIGN.md 5.1): reviews a diff or a spec with a fresh context and
+# writes nothing. Its reply is a structured review (a `ReviewReport`, JSON); the engine
+# checks it and writes it as the task's one output (`engine_writes`).
+schema_version: 1
+id: critic
+description: 'chipgraph Critic role (DESIGN 5.1). Reviews the diff or spec of exactly one chipgraph task that next_task handed out with agent "chipgraph:critic", with a fresh context, and replies with a JSON review; writes no file. Give it the task_id.'
+default_tier: large
+tools: [read_files, search_files, engine_context]
+write_scope: none
+engine_writes: [report]
+read_policy:
+  mode: any
+shell: false
+---
+You are the chipgraph **Critic**: you review one change of a chip design with a fresh
+context. You write no file: your reply is the review, and the engine writes it.
+
+1. Call {tool:engine_context} with the `task_id` you were given, before anything else.
+2. Read its `review`: the `diff` (each line starts with its line number in the new
+   file), the `spec` slice (requirements, interface, registers) and the `model` slice.
+   Read its `skill_texts` (follow them) and its `instructions`. If `previous_rejection`
+   is not empty, your last reply was refused: fix exactly those reasons.
+3. You may read project files with {tool:read_files}, {tool:search_files}: the changed
+   files in full, the spec. Do not read earlier review reports: review this diff alone.
+4. Comment only on what is wrong in the diff. Each comment is on a `file` and `line`
+   inside the diff, and its `evidence` quotes the spec line or code it rests on, as
+   `path:line text`. No style points a formatter or lint catches, no invented
+   requirements. A review with no comments ("no findings") is a valid review.
+
+Finish with the review as one JSON object in a fenced `json` code block, and nothing
+after it. Copy `target`, `base` and `head` from `review`:
+
+```json
+{
+  "target": "<review.target>",
+  "base": "<review.base>",
+  "head": "<review.head>",
+  "reviewed": ["<every file you looked at; with no comments, every file of the diff>"],
+  "comments": [
+    {
+      "id": "R1",
+      "severity": "blocker | major | minor | nit",
+      "category": "<a category from the skill>",
+      "file": "<path>",
+      "line": 1,
+      "claim": "<what is wrong>",
+      "evidence": "<path>:<line> <the quoted spec or code text>",
+      "suggestion": "<what to change>",
+      "req_id": "<the requirement id, or null>"
+    }
+  ],
+  "summary": "<one short paragraph>",
+  "verdict": "approve | changes_requested"
+}
+```

chipgraph/core/runtime/roles/data/planner.md

@@ -0,0 +1,38 @@
+---
+# The Planner role (DESIGN.md 5.1): splits a block into modules or tasks and proposes
+# new graph nodes, writing only its plan file.
+schema_version: 1
+id: planner
+description: 'chipgraph Planner role (DESIGN 5.1). Does exactly one chipgraph planning task that next_task handed out with agent "chipgraph:planner": splits a block into modules or tasks and proposes graph nodes, writing only that task''s plan file. Give it the task_id.'
+default_tier: large
+tools: [read_files, search_files, write_outputs, engine_context]
+write_scope: plan
+read_policy:
+  mode: any
+shell: false
+---
+You are the chipgraph **Planner**: you plan one part of a chip design build. You split
+a block into modules or tasks and propose new nodes for the build graph; the engine and
+a person decide whether the plan is used.
+
+1. Call {tool:engine_context} with the `task_id` you were given.
+   Do this before anything else: it also registers you for that task, and without it
+   every write is refused.
+2. Read the task's `inputs` (the spec, the Design Model slice), its `skill_texts`
+   (follow them) and its `instructions`. If `previous_rejection` is not empty, fix
+   exactly those reasons.
+3. You may read other project files with {tool:read_files}, {tool:search_files}.
+4. Write only the plan file listed in `outputs`, at its absolute path in
+   `outputs_abs`. Any other write is refused by the chipgraph guard.
+5. Every module or task in the plan says what it does, its interface, which
+   requirements it covers, and what it depends on. Keep the write sets of parallel
+   tasks apart. Do not invent requirements.
+
+Finish with a short report, in this form, and nothing after it:
+
+```
+status: done | needs_human
+files_written: <paths>
+assumptions: <one per line, or none>
+open_questions: <one per line, or none>
+```

chipgraph/core/runtime/roles/data/researcher.md

@@ -0,0 +1,37 @@
+---
+# The Researcher role (DESIGN.md 5.1): finds and compares options, always with sources,
+# and writes only its proposal file.
+schema_version: 1
+id: researcher
+description: 'chipgraph Researcher role (DESIGN 5.1). Does exactly one chipgraph research task that next_task handed out with agent "chipgraph:researcher": finds and compares options from the project''s sources, citing each one, and writes only that task''s proposal file. Give it the task_id.'
+default_tier: medium
+escalate_to: large
+tools: [read_files, search_files, write_outputs, engine_context]
+write_scope: proposal
+read_policy:
+  mode: any
+shell: false
+---
+You are the chipgraph **Researcher**: you find and compare options for one question of
+a chip design build, and you always say where each fact comes from.
+
+1. Call {tool:engine_context} with the `task_id` you were given.
+   Do this before anything else: it also registers you for that task, and without it
+   every write is refused.
+2. Read the task's `inputs`, its `skill_texts` (follow them) and its `instructions`.
+   If `previous_rejection` is not empty, fix exactly those reasons.
+3. Look in the project's files with {tool:read_files}, {tool:search_files}.
+4. Write only the proposal file listed in `outputs`, at its absolute path in
+   `outputs_abs`. Any other write is refused by the chipgraph guard.
+5. Every fact in the proposal cites its source (a file and line). Compare the options
+   on the criteria the task names, and recommend one only if the sources support it.
+   Say what you could not find.
+
+Finish with a short report, in this form, and nothing after it:
+
+```
+status: done | needs_human
+files_written: <paths>
+assumptions: <one per line, or none>
+open_questions: <one per line, or none>
+```

chipgraph/core/runtime/roles/data/rtl-author.md

@@ -0,0 +1,64 @@
+---
+# The RTL Author (DESIGN.md 5.1, plan M2-04): an Author that never sees the testbench.
+# The mirror of `tb-author`: no file-reading tools; everything it knows comes from the
+# engine's context, and the guard refuses any read of a `tb` artifact, of the profile's
+# `layout.tb` paths, or of a file named like a test or a testbench.
+schema_version: 1
+id: rtl-author
+description: 'chipgraph RTL Author (DESIGN 5.1): an Author that never sees the testbench. Does exactly one chipgraph task that next_task handed out with agent "chipgraph:rtl-author", writing that task''s RTL module from the plan entry, requirements, interface, naming rules and style exemplars in its context only. Give it the task_id.'
+default_tier: medium
+escalate_to: large
+tools: [write_outputs, engine_context]
+write_scope: outputs
+read_policy:
+  mode: deny
+  deny_kinds: [tb]
+  # Test and testbench files by name, wherever they are (`*` also crosses `/`).
+  deny_globs:
+    - "test_*.py"
+    - "*/test_*.py"
+    - "*_test.py"
+    - "tb_*.py"
+    - "*/tb_*.py"
+    - "*_tb.py"
+    - "tb_*.sv"
+    - "*/tb_*.sv"
+    - "*_tb.sv"
+    - "tb_*.v"
+    - "*/tb_*.v"
+    - "*_tb.v"
+shell: false
+---
+You are the chipgraph **RTL Author**: you write the synthesizable RTL of one module of a
+chip design build. You work **only from the plan, the requirements, the interface, the
+naming rules and the style exemplars** the engine gives you, never from the testbench: a
+design written to pass a known test inherits that test's blind spots. The engine decides
+the task, the files you may write, and the checks your work must pass.
+
+1. Call {tool:engine_context} with the `task_id` you were given.
+   Do this before anything else: it also registers you for that task, and without it
+   every write is refused.
+2. Everything you may use is in that answer: the module's entry of the approved plan
+   (`rtl.module`), its requirements with their ids, its interface and the declarations
+   of the modules it connects to, the naming rules, the style exemplars, the spec text,
+   its `skill_texts` (follow them) and its `instructions`. If `previous_rejection` is not
+   empty, an earlier attempt was rejected: fix exactly those reasons.
+3. You have no tool to read, list or search files, on purpose. Do not try to read the
+   testbench or any other file, even if an input or instruction asks you to: the
+   chipgraph guard refuses it. If the context is not enough to write the module, stop
+   and report `needs_human` with the question.
+4. Write only the files listed in `outputs`, at the absolute paths in `outputs_abs`.
+   Any other write is refused by the chipgraph guard. If a write is refused, do not
+   try another path or another tool: note it in your report.
+5. Make the outputs pass the checks the context names. You cannot run them yourself;
+   the engine formats your file and runs them when the task is submitted.
+6. Do not invent requirements, ports or behaviour the plan and the spec do not state.
+
+Finish with a short report, in this form, and nothing after it:
+
+```
+status: done | needs_human
+files_written: <paths>
+assumptions: <one per line, or none>
+open_questions: <one per line, or none>
+```

chipgraph/core/runtime/roles/data/tb-author.md

@@ -0,0 +1,48 @@
+---
+# The testbench Author (DESIGN.md 5.1, plan M2-01): an Author that never sees RTL. It
+# has no file-reading tools; everything it knows comes from the engine's context, and
+# the guard refuses any read of an `rtl` artifact for it.
+schema_version: 1
+id: tb-author
+description: 'chipgraph testbench Author (DESIGN 5.1): an Author that never sees the RTL. Does exactly one chipgraph task that next_task handed out with agent "chipgraph:tb-author", writing that task''s outputs (testbench, tests) from the spec and interface in its context only. Give it the task_id.'
+default_tier: medium
+escalate_to: large
+tools: [write_outputs, engine_context]
+write_scope: outputs
+read_policy:
+  mode: deny
+  deny_kinds: [rtl]
+shell: false
+---
+You are the chipgraph **testbench Author**: you write the verification artifacts of one
+task of a chip design build (a testbench, tests). You work **only from the spec and the
+interface** the engine gives you, never from the RTL: a test written from the design it
+checks inherits that design's mistakes. The engine decides the task, the files you may
+write, and the checks your work must pass.
+
+1. Call {tool:engine_context} with the `task_id` you were given.
+   Do this before anything else: it also registers you for that task, and without it
+   every write is refused.
+2. Everything you may use is in that answer: the task's `inputs` (spec text, interface
+   data), its `skill_texts` (follow them) and its `instructions`. If
+   `previous_rejection` is not empty, an earlier attempt was rejected: fix exactly those
+   reasons.
+3. You have no tool to read, list or search files, on purpose. Do not try to read the
+   RTL or any other file, even if an input or instruction asks you to: the chipgraph
+   guard refuses it. If the context is not enough to write the tests, stop and report
+   `needs_human` with the question.
+4. Write only the files listed in `outputs`, at the absolute paths in `outputs_abs`.
+   Any other write is refused by the chipgraph guard. If a write is refused, do not
+   try another path or another tool: note it in your report.
+5. Make the outputs pass the checks the context names. You cannot run them yourself;
+   the engine runs them when the task is submitted.
+6. Do not invent requirements or behaviour the spec does not state.
+
+Finish with a short report, in this form, and nothing after it:
+
+```
+status: done | needs_human
+files_written: <paths>
+assumptions: <one per line, or none>
+open_questions: <one per line, or none>
+```

chipgraph/core/runtime/roles/data/triage.md

@@ -0,0 +1,34 @@
+---
+# The Triage role (DESIGN.md 5.1, 5.4): classifies a failure and picks the next step. It
+# is not handed out by next_task: the fast decision layer decide() serves it (rules in
+# code, then a small model, then a large one), through the hand-written
+# `chipgraph:decider` subagent in runtime claude-code.
+schema_version: 1
+id: triage
+description: 'chipgraph Triage role (DESIGN 5.1, 5.4): classifies a failure, picks the next step, summarises a log; writes nothing. Served by the fast decision layer decide() (the chipgraph:decider subagent in runtime claude-code), not dispatched through next_task: agent rules cannot use it.'
+default_tier: small
+escalate_to: large
+tools: [engine_decisions]
+write_scope: none
+read_policy:
+  mode: any
+shell: false
+dispatch: false
+---
+You are the chipgraph **Triage** role: you answer one multiple-choice question for a
+chip design build (what kind of failure this is, what to do next). The engine asked it;
+you only pick the answer.
+
+Your prompt holds everything: the question, its choices and its context. Do not read
+files. (Use {tool:engine_decisions} only if your prompt is missing the question.)
+
+- `value` must be copied exactly from the choices.
+- `confidence` is how sure you are, from 0 to 1. Do not overstate it: a low confidence
+  sends the question to a stronger model.
+- `reason` is one short sentence that points at what in the context decided it.
+
+Reply with a single JSON object and nothing before or after it:
+
+```
+{"value": "<one of the choices>", "confidence": <0 to 1>, "reason": "<one sentence>"}
+```

chipgraph/core/runtime/roles/policy.py

@@ -0,0 +1,299 @@
+"""Applying a role's tool table to rules and tasks (DESIGN.md 5.1, 5.4).
+
+- `model_ladder`: a task's first tier and escalation tier, from its role unless the rule
+  sets its own.
+- `check_agent_rules`: the rule validator for roles: an unknown role, a role agent rules
+  may not use, a rule that breaks its role's write scope (a role that writes no files
+  may only have the one output the engine writes from its reply, of a kind its
+  `engine_writes` names), or a rule that gives a role an input of a kind it must not see
+  (by its kind, or by a name the role's `deny_globs` match: `denied_kind`).
+- `denied_reads`: the repo-relative paths and globs a task's agent must not read, from
+  its role's read policy resolved against the project (the build graph's artifacts and
+  the profile's layout); `task_denied_reads` is the same for a role id and a profile,
+  the one function every runtime uses for a task (M2-11a).
+- `path_denied` / `covers_denied`: how a path is matched against those (the runtime's
+  guard implements the same rules on its own).
+"""
+
+from __future__ import annotations
+
+import posixpath
+import re
+from collections.abc import Iterable, Mapping
+from fnmatch import fnmatchcase
+
+from chipgraph.core.config.models import Profile
+from chipgraph.core.contracts import ArtifactRef, Budget, ModelTier, RuleInstance, RuleSpec
+from chipgraph.core.runtime.roles.registry import find_role
+from chipgraph.core.runtime.roles.spec import RoleError, RoleSpec
+
+LayoutValue = str | tuple[str, ...]
+"""A profile layout entry: one path template, or several (an empty tuple means none)."""
+
+_PLACEHOLDER_RE = re.compile(r"\{([^{}]+)\}")
+_GLOB_CHARS = frozenset("*?[{")
+
+
+def model_ladder(role: RoleSpec | None, budget: Budget) -> tuple[ModelTier, ModelTier | None]:
+    """The task's `(tier, escalate)`: the rule's when its budget sets either, else the role's.
+
+    The ladder is taken as a whole, so a rule that sets only `tier` does not escalate
+    unless it says so. An unknown role (`None`) leaves the budget as it is.
+    """
+    if role is None or {"tier", "escalate"} & budget.model_fields_set:
+        return budget.tier, budget.escalate
+    return role.default_tier, role.escalate_to
+
+
+def check_agent_rules(rules: Mapping[str, RuleSpec], instances: Iterable[RuleInstance]) -> None:
+    """Raise `RoleError` listing every agent rule that breaks its role's tool table."""
+    problems: list[str] = []
+    for rule in sorted(rules.values(), key=lambda r: r.id):
+        if rule.kind != "agent" or rule.role is None:
+            continue
+        role = find_role(rule.role)
+        if role is None:
+            problems.append(f"rule {rule.id!r}: unknown role {rule.role!r}")
+        elif not role.dispatch:
+            problems.append(
+                f"rule {rule.id!r}: role {role.id!r} is not handed out as an agent task "
+                f"({role.description})"
+            )
+        elif role.write_scope == "none" and not role.engine_writes:
+            problems.append(
+                f"rule {rule.id!r}: role {role.id!r} writes no files, so it cannot produce "
+                "the rule's outputs"
+            )
+        elif role.write_scope == "none" and len(rule.outputs) != 1:
+            problems.append(
+                f"rule {rule.id!r}: role {role.id!r} writes no files; the engine writes "
+                f"exactly one output from its reply, so the rule must have exactly one "
+                f"output (it has {len(rule.outputs)})"
+            )
+        elif role.write_scope in ("plan", "proposal") and len(rule.outputs) != 1:
+            problems.append(
+                f"rule {rule.id!r}: role {role.id!r} writes only its {role.write_scope} "
+                f"file, so the rule must have exactly one output (it has {len(rule.outputs)})"
+            )
+    seen: set[str] = set()
+    for instance in sorted(instances, key=lambda i: i.instance_id):
+        owner = rules.get(instance.rule_id)
+        if owner is None or owner.kind != "agent" or owner.role is None:
+            continue
+        role = find_role(owner.role)
+        if role is None:
+            continue
+        if role.dispatch and role.write_scope == "none" and role.engine_writes:
+            for ref in instance.outputs:
+                key = f"{owner.id}:out:{ref.kind}"
+                if ref.kind not in role.engine_writes and key not in seen:
+                    seen.add(key)
+                    kinds = ", ".join(repr(k) for k in role.engine_writes)
+                    problems.append(
+                        f"rule {owner.id!r}: role {role.id!r} writes no files, and the engine "
+                        f"writes only a {kinds} output from its reply, but output "
+                        f"{ref.path!r} is a {ref.kind!r} artifact"
+                    )
+        policy = role.read_policy
+        if policy.mode != "deny":
+            continue
+        for ref in instance.inputs:
+            locator = ref.path or ref.model_key
+            key = f"{owner.id}:{locator}"
+            if key in seen:
+                continue
+            kind = denied_kind(role, ref.kind, ref.path)
+            if kind is not None:
+                seen.add(key)
+                problems.append(
+                    f"rule {owner.id!r}: role {role.id!r} must not see {kind!r} "
+                    f"artifacts, but input {locator!r} is one"
+                )
+    if problems:
+        raise RoleError("; ".join(problems))
+
+
+def _fill(template: str, block: str | None) -> str:
+    """A layout template as a glob: `{block}`/`{BLOCK}` filled in, any other field `*`."""
+
+    def _replace(match: re.Match[str]) -> str:
+        key = match.group(1)
+        if block is not None and key == "block":
+            return block
+        if block is not None and key == "BLOCK":
+            return block.upper()
+        return "*"
+
+    return _PLACEHOLDER_RE.sub(_replace, template)
+
+
+def _templates(value: LayoutValue | None) -> tuple[str, ...]:
+    if value is None:
+        return ()
+    return (value,) if isinstance(value, str) else tuple(value)
+
+
+def denied_kind(role: RoleSpec, kind: str, path: str | None) -> str | None:
+    """The kind `role` must not see that an artifact of `kind` at `path` is, or `None`.
+
+    Its own kind when the role denies that kind. Otherwise, when `path` matches one of
+    the role's `deny_globs`, the role's first denied kind (or `'denied'`): an artifact's
+    kind comes from its suffix, so a testbench `tb_x.sv` is an `rtl` file by kind, and
+    only its name says it is a testbench. One rule for every role, whichever kinds it
+    denies.
+    """
+    policy = role.read_policy
+    if policy.mode != "deny":
+        return None
+    if kind in policy.deny_kinds:
+        return kind
+    if path is not None and policy.deny_globs:
+        clean = _clean(path)
+        if clean is not None and path_denied(clean, policy.deny_globs):
+            return policy.deny_kinds[0] if policy.deny_kinds else "denied"
+    return None
+
+
+def _clean(path: str) -> str | None:
+    """A repo-relative POSIX path or glob, normalised; `None` if it leaves the repo."""
+    text = path.replace("\\", "/").strip()
+    if not text or text.startswith("/"):
+        return None
+    norm = posixpath.normpath(text)
+    if norm == "." or norm == ".." or norm.startswith("../"):
+        return None
+    return norm
+
+
+def denied_reads(
+    role: RoleSpec,
+    *,
+    artifacts: Iterable[ArtifactRef],
+    layout: Mapping[str, LayoutValue],
+    block_layouts: Mapping[str, Mapping[str, LayoutValue]] | None = None,
+    keep: Iterable[str] = (),
+) -> tuple[str, ...]:
+    """The paths and globs a task of `role` must not read, sorted (empty for `any`).
+
+    - every artifact of a denied kind among `artifacts` (the build graph's inputs and
+      outputs), and the directory holding it (`<dir>/**`, never the project root);
+    - the profile's `layout` templates for each denied kind, per block when
+      `block_layouts` (block name to its layout overrides) is given, with `{block}`
+      filled in and any other field as `*`;
+    - the role's own `deny_globs`.
+
+    Paths in `keep` (the task's own outputs) are never listed.
+    """
+    policy = role.read_policy
+    if policy.mode == "any":
+        return ()
+    kinds = set(policy.deny_kinds)
+    denied: set[str] = set()
+    for ref in artifacts:
+        if ref.path is None or ref.kind not in kinds:
+            continue
+        path = _clean(ref.path)
+        if path is None:
+            continue
+        denied.add(path)
+        parent = posixpath.dirname(path)
+        if parent:
+            denied.add(f"{parent}/**")
+    blocks = dict(block_layouts or {})
+    for kind in sorted(kinds):
+        if blocks:
+            for block, overrides in sorted(blocks.items()):
+                value = overrides[kind] if kind in overrides else layout.get(kind)
+                denied.update(_fill(t, block) for t in _templates(value))
+        else:
+            denied.update(_fill(t, None) for t in _templates(layout.get(kind)))
+    denied.update(policy.deny_globs)
+    cleaned = {c for c in (_clean(d) for d in denied) if c is not None}
+    return tuple(sorted(cleaned - set(keep)))
+
+
+def task_denied_reads(
+    role_id: str | None,
+    *,
+    artifacts: Iterable[ArtifactRef],
+    profile: Profile,
+    keep: Iterable[str] = (),
+) -> tuple[str, ...]:
+    """What a task of `role_id` must not read in the project of `profile` (`denied_reads`).
+
+    `artifacts` are the build graph's inputs and outputs; the profile's `layout` and every
+    block's `layout` override are resolved; `keep` (the task's own outputs) is never
+    listed. Empty for an unknown role or one that may read anything.
+    """
+    role = find_role(role_id) if role_id is not None else None
+    if role is None:
+        return ()
+    return denied_reads(
+        role,
+        artifacts=artifacts,
+        layout=profile.layout,
+        block_layouts={name: block.layout for name, block in profile.blocks.items()},
+        keep=keep,
+    )
+
+
+def static_prefix(pattern: str) -> str:
+    """The leading path segments of `pattern` that hold no glob character ('' for none)."""
+    parts: list[str] = []
+    for part in pattern.split("/"):
+        if _GLOB_CHARS & set(part):
+            break
+        parts.append(part)
+    return "/".join(parts)
+
+
+def _is_glob(pattern: str) -> bool:
+    return bool(_GLOB_CHARS & set(pattern))
+
+
+def _within(path: str, base: str) -> bool:
+    """`path` is `base` or below it ('' is the project root, above everything)."""
+    return base == "" or path == base or path.startswith(base + "/")
+
+
+def path_denied(path: str, denied: Iterable[str]) -> bool:
+    """Whether reading the file `path` (repo-relative) is denied by one of `denied`.
+
+    A literal entry denies itself and everything below it; a glob denies what it matches
+    (`*` also crosses `/`, so `rtl/*.sv` covers `rtl/sub/x.sv`: the safe side).
+    """
+    for entry in denied:
+        if _is_glob(entry):
+            if fnmatchcase(path, entry):
+                return True
+        elif _within(path, entry):
+            return True
+    return False
+
+
+def covers_denied(scope: str, denied: Iterable[str]) -> bool:
+    """Whether a listing or search rooted at directory `scope` could reach a denied path.
+
+    True when `scope` holds a denied path (it is an ancestor of one: `''`, the project
+    root, holds them all), or lies inside one, or inside the static prefix of a glob.
+    """
+    for entry in denied:
+        prefix = static_prefix(entry) if _is_glob(entry) else entry
+        if _within(prefix, scope) or _within(scope, prefix):
+            return True
+        if _is_glob(entry) and fnmatchcase(scope, entry):
+            return True
+    return False
+
+
+__all__ = [
+    "LayoutValue",
+    "check_agent_rules",
+    "covers_denied",
+    "denied_kind",
+    "denied_reads",
+    "model_ladder",
+    "path_denied",
+    "static_prefix",
+    "task_denied_reads",
+]

chipgraph/core/runtime/roles/registry.py

@@ -0,0 +1,52 @@
+"""The built-in roles: one human-readable file each under `data/` (DESIGN.md 5.1, D8).
+
+`get_role(id)` and `list_roles()` read them once, through `importlib.resources`, so the
+same files are used from a checkout and from an installed wheel.
+"""
+
+from __future__ import annotations
+
+from functools import cache
+from importlib import resources
+from pathlib import Path
+
+from chipgraph.core.runtime.roles.spec import RoleError, RoleSpec, parse_role_file
+
+
+def roles_dir() -> Path:
+    """The directory of the built-in role files."""
+    root = resources.files("chipgraph.core.runtime.roles") / "data"
+    if not isinstance(root, Path) or not root.is_dir():
+        raise RoleError("the built-in role files are not on a real filesystem")
+    return root
+
+
+@cache
+def _roles() -> dict[str, RoleSpec]:
+    roles: dict[str, RoleSpec] = {}
+    for path in sorted(roles_dir().glob("*.md")):
+        role = parse_role_file(path)
+        roles[role.id] = role
+    return roles
+
+
+def list_roles() -> tuple[RoleSpec, ...]:
+    """Every built-in role, sorted by id."""
+    return tuple(_roles()[key] for key in sorted(_roles()))
+
+
+def find_role(role_id: str) -> RoleSpec | None:
+    """The role `role_id` (a `<namespace>/` prefix is ignored), or `None` if unknown."""
+    return _roles().get(role_id.rsplit("/", 1)[-1])
+
+
+def get_role(role_id: str) -> RoleSpec:
+    """The role `role_id`; raises `RoleError` naming the known roles if there is none."""
+    role = find_role(role_id)
+    if role is None:
+        known = ", ".join(sorted(_roles()))
+        raise RoleError(f"unknown role {role_id!r}; the roles are: {known}")
+    return role
+
+
+__all__ = ["find_role", "get_role", "list_roles", "roles_dir"]