chipgraph 0.1.0__py3-none-any.whl

chipgraph/packs/digital_rtl/rtl/context.py

@@ -0,0 +1,272 @@
+"""What an `rtl-author` task gets in its context (DESIGN.md 5.1, 5.3; task M2-04).
+
+Only the inputs an RTL module is written from, never a testbench:
+
+- `module`: the module's entry of the block's approved plan (summary, requirement ids,
+  interface ports, dependencies, write set, budget), with the plan's top, assumptions
+  and open questions;
+- `requirements`: the module's requirements, with their ids and text (the Design
+  Model's; the plan names them);
+- `interface`: the module's ports. A port the Design Model knows (the block's spec
+  ports, else its top RTL module's) is shown as the model has it (`source: model`); an
+  internal port between the block's modules is shown as the approved plan gives it
+  (`source: plan`). Clock and reset come from the model's block;
+- `dependencies`: the modules it depends on, declarations only: name and ports, from
+  the Design Model when it knows the module, else from the approved plan;
+- `naming`: the project's naming rules, rendered as text (`naming_text`): the dynamic
+  part of the `org/naming` skill;
+- `style`: the exemplars' text (`style.exemplars`, each capped, labelled "imitate this
+  style") and the style profile measured from them (`chipgraph.checks.style`). An
+  exemplar the role must not read (`is_denied`, e.g. a testbench) is refused: its entry
+  says so and holds no text.
+
+`spec_side` is the block's spec slice (registers, interrupts, clock and reset) with the
+requirements cut to the module's: what the model input `block/<block>` shows.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable, Mapping, Sequence
+from pathlib import Path
+from typing import Any
+
+from chipgraph.checks._naming_rules import NamingRules
+from chipgraph.checks.naming import _load_rules, _resolve_rules_path, _RulesError
+from chipgraph.checks.plan_check import PlanEnv, PlanEnvError, check_plan_file
+from chipgraph.checks.style import style_profile
+from chipgraph.core.config.loader import ResolvedProfile
+from chipgraph.core.contracts import RuleSpec
+from chipgraph.core.model import DesignModel
+from chipgraph.packs.digital_rtl.plan.model import Plan, PlanModule
+from chipgraph.packs.dv.interface import spec_slice
+
+MAX_EXEMPLAR_CHARS = 12_000
+"""Longest text of one exemplar in the context; longer files are cut."""
+MAX_EXEMPLARS_CHARS = 36_000
+"""Most exemplar text in one context; exemplars past it are listed without text."""
+DEFAULT_APPROVED = "plan/{block}.approved.json"
+
+IMITATE = (
+    "imitate this style: indentation, begin/end placement, port declarations, reset and "
+    "clocking, signal suffixes, comments. Do not copy its logic."
+)
+
+
+def _naming_ref(resolved: ResolvedProfile, block: str) -> str | None:
+    profile = resolved.for_block(block)
+    if profile.naming.rules is not None:
+        return profile.naming.rules
+    cfg = profile.adapters.get("naming")
+    dumped = cfg.model_dump() if cfg is not None else {}
+    rules = dumped.get("rules")
+    return rules if dumped.get("use") == "naming" and isinstance(rules, str) else None
+
+
+def naming_text(rules: NamingRules, ref: str) -> str:
+    """The naming rules as instructions a model can follow."""
+    lines = [
+        f"Naming rules ({rules.document} v{rules.version}, from {ref}). Every name you "
+        "declare must follow them; the `naming` check rejects the module otherwise.",
+        "",
+        "Allowed names, per kind (the whole name must match the pattern):",
+    ]
+    for kind, rule in rules.identifiers.items():
+        lines.append(f"- {kind}: `{rule.pattern}` ({rule.rule}): {rule.message}")
+    if rules.lexical:
+        lines.extend(["", "Lexical rules, for every name:"])
+        for lex in rules.lexical:
+            unless = f", unless it matches `{lex.allow_if_matches}`" if lex.allow_if_matches else ""
+            lines.append(f"- {lex.rule}: no match of `{lex.forbid_pattern}`{unless}: {lex.message}")
+    if rules.vocabulary is not None and rules.vocabulary.replace:
+        words = ", ".join(f"{bad} -> {good}" for bad, good in rules.vocabulary.replace.items())
+        lines.extend(["", f"Vocabulary ({rules.vocabulary.rule}): {words}"])
+    lines.extend(
+        [
+            "",
+            f"Do not use the exemption comment `// {rules.ignore_comment}`: it is for people.",
+        ]
+    )
+    return "\n".join(lines) + "\n"
+
+
+def _naming(root: Path, resolved: ResolvedProfile, block: str) -> dict[str, Any] | None:
+    ref = _naming_ref(resolved, block)
+    if ref is None:
+        return None
+    try:
+        rules, _ = _load_rules(_resolve_rules_path(ref, root))
+    except _RulesError as exc:
+        return {"rules": ref, "note": str(exc)}
+    return {"rules": ref, "text": naming_text(rules, ref)}
+
+
+def _exemplars(
+    root: Path,
+    resolved: ResolvedProfile,
+    is_denied: Callable[[str], bool],
+) -> dict[str, Any]:
+    style = resolved.profile.style
+    entries: list[dict[str, Any]] = []
+    texts: dict[str, str] = {}
+    used = 0
+    for rel in style.exemplars:
+        entry: dict[str, Any] = {"path": rel}
+        path = root / rel
+        if is_denied(rel):
+            entry["refused"] = (
+                f"{rel} is a file this role must not read (a testbench or test): it is not "
+                "shown. Remove it from the profile's style.exemplars."
+            )
+        elif not path.is_file():
+            entry["missing"] = True
+        else:
+            text = path.read_text(encoding="utf-8", errors="replace")
+            texts[rel] = text
+            if used >= MAX_EXEMPLARS_CHARS:
+                entry["omitted"] = "the context's exemplar budget is used up"
+            else:
+                cap = min(MAX_EXEMPLAR_CHARS, MAX_EXEMPLARS_CHARS - used)
+                if len(text) > cap:
+                    entry["truncated"] = True
+                    text = text[:cap]
+                used += len(text)
+                entry["label"] = IMITATE
+                entry["content"] = text
+        entries.append(entry)
+    out: dict[str, Any] = {"exemplars": entries, "enforce": list(style.enforce)}
+    if texts:
+        profile = style_profile(texts)
+        out["profile"] = profile.describe()
+    return out
+
+
+def _ports(ports: Sequence[Any], source: str) -> list[dict[str, Any]]:
+    return [
+        {"name": p.name, "direction": p.direction, "width": p.width, "source": source}
+        for p in ports
+    ]
+
+
+def _interface(
+    plan: Plan, module: PlanModule, env: PlanEnv, slice_: Mapping[str, Any]
+) -> dict[str, Any]:
+    model_ports = {p.name: p for p in env.interface}
+    ports: list[dict[str, Any]] = []
+    for port in module.interface.ports:
+        known = model_ports.get(port.name)
+        if known is not None and not port.internal:
+            ports.extend(_ports([known], "model"))
+        else:
+            ports.extend(_ports([port], "plan"))
+    return {
+        "module": module.name,
+        "top": plan.top == module.name,
+        "model_interface": env.interface_source,
+        "ports": ports,
+        "clock": slice_.get("clock"),
+        "reset": slice_.get("reset"),
+    }
+
+
+def _dependencies(plan: Plan, module: PlanModule, env: PlanEnv) -> list[dict[str, Any]]:
+    existing = {m.name: m for m in env.existing_modules}
+    out: list[dict[str, Any]] = []
+    for name in dict.fromkeys(module.depends_on):
+        found = existing.get(name)
+        planned = plan.module(name)
+        if found is not None:
+            out.append({"name": name, "source": "model", "ports": _ports(found.ports, "model")})
+        elif planned is not None:
+            out.append(
+                {
+                    "name": name,
+                    "source": "plan",
+                    "summary": planned.summary,
+                    "ports": _ports(planned.interface.ports, "plan"),
+                }
+            )
+    return out
+
+
+def approved_plan_path(root: Path, block: str, approved: str | None = None) -> str | None:
+    """The plan file an approved plan artifact names (None when there is none)."""
+    rel = (approved or DEFAULT_APPROVED).replace("{block}", block)
+    path = root / rel
+    if not path.is_file():
+        return None
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    plan = data.get("plan") if isinstance(data, dict) else None
+    return plan if isinstance(plan, str) else None
+
+
+def rtl_author_context(
+    root: Path,
+    resolved: ResolvedProfile,
+    rules: Sequence[RuleSpec],
+    *,
+    block: str,
+    module: str | None,
+    model: DesignModel | None,
+    is_denied: Callable[[str], bool],
+    approved: str | None = None,
+) -> dict[str, Any]:
+    """The `rtl` section of an `rtl-author` task's context (see the module docstring)."""
+    out: dict[str, Any] = {"block": block, "module_name": module}
+    out["naming"] = _naming(root, resolved, block)
+    out["style"] = _exemplars(root, resolved, is_denied)
+    slice_ = spec_slice(model, block) if model is not None else {}
+    plan_path = approved_plan_path(root, block, approved)
+    if module is None or plan_path is None:
+        out["note"] = "no approved plan entry for this task: write from the spec and model"
+        out["requirements"] = list(slice_.get("requirements", []))
+        return out
+    try:
+        report = check_plan_file(
+            root, block, plan_path=plan_path, resolved=resolved, rules=rules, check_existing=False
+        )
+    except PlanEnvError as exc:
+        out["note"] = str(exc)
+        return out
+    plan, env = report.plan, report.env
+    entry = plan.module(module) if plan is not None else None
+    if plan is None or env is None or entry is None:
+        out["note"] = f"module {module!r} is not in the plan {plan_path}"
+        return out
+    wanted = set(entry.reqs)
+    out["module"] = {
+        **entry.model_dump(mode="json"),
+        "plan": plan_path,
+        "plan_top": plan.top,
+        "plan_assumptions": list(plan.assumptions),
+        "plan_open_questions": list(plan.open_questions),
+    }
+    out["requirements"] = [
+        {"id": r.ref, "text": r.text} for r in env.requirements if r.refs & wanted
+    ]
+    out["interface"] = _interface(plan, entry, env, slice_)
+    out["dependencies"] = _dependencies(plan, entry, env)
+    return out
+
+
+def spec_side(model: DesignModel, block: str, reqs: Sequence[str] | None) -> dict[str, Any]:
+    """The block's spec slice with only the requirements in `reqs` (all when None)."""
+    slice_ = spec_slice(model, block)
+    if reqs is not None:
+        wanted = set(reqs)
+        slice_["requirements"] = [r for r in slice_["requirements"] if r["id"] in wanted]
+    return slice_
+
+
+__all__ = [
+    "IMITATE",
+    "MAX_EXEMPLARS_CHARS",
+    "MAX_EXEMPLAR_CHARS",
+    "approved_plan_path",
+    "naming_text",
+    "rtl_author_context",
+    "spec_side",
+]

chipgraph/packs/digital_rtl/rules/open_pr.yml

@@ -0,0 +1,30 @@
+# A block's pull request (DESIGN.md 6.1; task M2-11a).
+#
+# For each block with an approved, valid plan (`foreach: plan.block`), once every module's
+# RTL, the testbench and the Critic's review are built (the resolver adds the module
+# files and the testbench as inputs), the `open_pr` tool builds the branch
+# `chipgraph/<run id>/<block>` in a workspace outside the user's checkout (HEAD, index
+# and working tree untouched), with exactly those files; with `review: {use: github}` it
+# pushes it to `review.remote` (default origin; an https remote needs
+# CHIPGRAPH_GITHUB_TOKEN, given to git through GIT_ASKPASS only) and opens the PR into
+# `review.base` (idempotent), with the plan, requirement coverage, check results and the
+# Critic's verdict as its body. It writes `pr/{block}.json`: branch, head commit, PR number
+# and URL. A re-run with changed files moves the same branch forward (never a force push)
+# and reuses the open PR.
+#
+# The gate `pr:{block}` is on `digital-rtl/pr_gate`. chipgraph never merges.
+rule: open_pr
+kind: gen
+description: >-
+  Commit the block's RTL and testbench on a branch of their own, push it and open a pull
+  request whose body says what the plan, the checks and the Critic found.
+foreach: plan.block
+inputs:
+  - artifact: "reports/review/{block}.json"
+outputs:
+  - "pr/{block}.json"
+run:
+  use: open_pr
+  args:
+    review: "reports/review/{block}.json"
+    out: "pr/{block}.json"

chipgraph/packs/digital_rtl/rules/plan.yml

@@ -0,0 +1,28 @@
+# The Planner (DESIGN.md 5.1, 5.3; task M2-03).
+#
+# For each block, a `planner` task reads the block's slice of the Design Model
+# (requirements, interface ports, existing modules) and writes one file: the block's plan
+# (`Plan`, schemas/formats/plan.schema.json). Its context also gives the layout paths a
+# module may write, the files that already exist there, the limits (profile `plan:`),
+# the naming rule for module names and the plan schema.
+#
+# The plan is checked at once by `plan_check` (enable it in the profile:
+# `adapters: { plan_check: { use: plan_check } }`); its issues are the redo text of the
+# next try. A plan that passes is not used yet: `digital-rtl/plan_expand` waits on the
+# gate `plan:{block}` until a person reads `chipgraph plan show <block>` and approves.
+rule: plan
+kind: agent
+role: planner
+description: >-
+  Split the block into modules: what each does, which requirements it covers, its ports
+  from the Design Model, what it depends on, the files it writes and its budget; list the
+  assumptions, the open questions and every requirement left unassigned, with the reason.
+foreach: blocks
+inputs:
+  - model: "block/{block}"
+outputs:
+  - "plan/{block}.plan.yml"
+skills: [plan/modules]
+checks: [plan_check]
+budget:
+  tries: 3

chipgraph/packs/digital_rtl/rules/plan_expand.yml

@@ -0,0 +1,29 @@
+# The human gate on a block's plan (DESIGN.md 6.1; task M2-03).
+#
+# A `gen` rule whose only file input is the plan, gated by `plan:{block}`. The gate covers
+# a rule instance's file inputs, so approving it pins the plan file's hash:
+#
+#   chipgraph plan show <block>                       # read it first
+#   chipgraph approve plan:<block> --instance 'digital-rtl/plan_expand[block=<block>]'
+#
+# Editing the plan afterwards changes its hash and puts the gate back to waiting. Once
+# approved, the `plan_expand` tool checks the plan again and writes the approved plan
+# artifact below. Rules that say `foreach: plan.modules` then get one instance per
+# module (params `block`, `module`), in dependency order, each bounded by the module's
+# write set; with no approved, valid plan they get none.
+rule: plan_expand
+kind: gen
+description: >-
+  After a person approves the block's plan, check it again and write the approved plan
+  (modules in build order, their dependencies and write sets).
+foreach: blocks
+inputs:
+  - artifact: "plan/{block}.plan.yml"
+outputs:
+  - "plan/{block}.approved.json"
+gate: "plan:{block}"
+run:
+  use: plan_expand
+  args:
+    plan: "plan/{block}.plan.yml"
+    out: "plan/{block}.approved.json"

chipgraph/packs/digital_rtl/rules/pr_gate.yml

@@ -0,0 +1,27 @@
+# The human gate on a block's pull request (DESIGN.md 6.1; task M2-11a).
+#
+# Its input is the PR record `open_pr` wrote (and, from `foreach: plan.block`, the block's
+# files). With `review: {use: github}` the gate `pr:{block}` is the pull request's review:
+# approved when a reviewer approves at the PR's current head commit (a later push makes
+# the approval stale), rejected when one requests changes. With the `file` adapter (no
+# GitHub, offline) a person approves it here:
+#
+#   chipgraph approve pr:<block>
+#
+# Once approved, `pr_gate` writes the approved head below. Merging stays a person's act.
+rule: pr_gate
+kind: gen
+description: >-
+  Wait for a person to approve the block's pull request at its current head, then
+  record what was approved.
+foreach: plan.block
+inputs:
+  - artifact: "pr/{block}.json"
+outputs:
+  - "pr/{block}.approved.json"
+gate: "pr:{block}"
+run:
+  use: pr_gate
+  args:
+    pr: "pr/{block}.json"
+    out: "pr/{block}.approved.json"

chipgraph/packs/digital_rtl/rules/review.yml

@@ -0,0 +1,31 @@
+# The Critic review of one block's change (DESIGN.md 4.8, 5.1; task M2-09).
+#
+# For each block: a `critic` task gets, with a fresh context (no conversation, no author
+# reasoning, no earlier review), the block's diff (base ref vs the working tree, only the
+# block's files), its spec slice (requirements, interface, registers from the Design
+# Model) and its model slice. The Critic writes no file: it replies with a JSON review
+# (`ReviewReport`, schemas/roles/ReviewReport.schema.json); `submit` validates it and the
+# engine writes it to the one output below. An invalid reply is rejected and uses a try.
+#
+# The base ref is the instance param `base` when there is one, otherwise the merge-base
+# of HEAD with the default branch (so on the default branch itself: HEAD, and the diff is
+# the uncommitted change). Findings never block the build (DESIGN.md 4.8): a valid
+# review is accepted whatever its verdict; people read the verdict.
+#
+# `foreach: plan.blocks` (M2-11a): one instance per block. A block with an approved plan
+# takes every module's files and its testbench as inputs, so its review runs after all
+# of them (target `rtl:<block>`); a block without one is reviewed as it is.
+rule: review
+kind: agent
+role: critic
+description: >-
+  Review the block's change against its requirements, interface and Design Model; reply
+  with a structured review, which the engine writes as the block's review report.
+foreach: plan.blocks
+inputs:
+  - model: "block/{block}"
+outputs:
+  - "reports/review/{block}.json"
+skills: [review/diff]
+budget:
+  tries: 2

chipgraph/packs/digital_rtl/rules/rtl_module.yml

@@ -0,0 +1,53 @@
+# The RTL of one planned module, written without seeing its testbench (DESIGN.md 5.1,
+# 5.3, 8.6 V3; task M2-04).
+#
+# For each module of a block's approved plan (`foreach: plan.modules`, params `block` and
+# `module`), an `rtl-author` task writes the module's RTL. Its context holds only what an
+# RTL module is written from: the module's entry of the approved plan (the resolver adds
+# `plan/{block}.approved.json` as an input), the model slice (`block/{block}`: the block's
+# registers, clock and reset, with the requirements cut to the module's;
+# `interface/{module}`: its ports from the Design Model, or the approved plan for an
+# internal port; the declarations of the modules it depends on), the block's spec
+# documents (the profile layout's `spec`), the naming rules as text and the profile's
+# `style.exemplars`. Never a testbench: the role denies `tb` artifacts, the profile's
+# `layout.tb` paths and files named like tests (`test_*.py`, `tb_*.sv`, `*_tb.sv`, ...);
+# the rule validator refuses such an input, `get_context` refuses to serve one, the guard
+# refuses reads of them, and what `submit` tells the author of a failed check is
+# filtered the same way (behavioural text such as `expected 0x2, got 0x0` is kept).
+#
+# The output is the module's file in the block's RTL directory, `{layout.rtl}`: the
+# directory part of the profile's `layout.rtl` for the block (QSoC's
+# `design/{block}/rtl/*.sv` gives `design/pwm/rtl`), `rtl` when the profile has none
+# (`chipgraph.packs.digital_rtl.layout`). The plan must list it in the module's writes
+# (`plan_check` says so), and the graph refuses an output outside them.
+#
+# Besides the approved plan, the resolver adds the profile's `style.exemplars` and its
+# naming rules file as inputs: editing one makes the module stale, so it is written
+# again in the new style (an exemplar the plan itself rewrites is left out).
+#
+# Checks, in this order, each an adapter id of the profile:
+#   format     the project's formatter on the outputs, run by the engine before the
+#              other checks (`chipgraph.checks.format`: `{ use: format }`, formatter from
+#              `style.formatter`, default verible-verilog-format when on PATH)
+#   lint       the project's lint (tinysoc: `make lint BLOCK={block}`)
+#   naming     the project's naming rule (`{ use: naming, rules: ..., scope: [...] }`)
+#   style      the outputs against `style.exemplars` (`chipgraph.checks.style`:
+#              `{ use: style }`; errors only for the keys in `style.enforce`)
+#   hardcode   no contract number typed by hand (`{ use: hardcode, scope: [...] }`)
+rule: rtl_module
+kind: agent
+role: rtl-author
+description: >-
+  Write the module's synthesizable RTL from its approved plan entry, its requirements,
+  its interface and the declarations it connects to, following the naming rules and the
+  style of the exemplars; cite each requirement id next to the logic that implements it.
+foreach: plan.modules
+inputs:
+  - model: "block/{block}"
+  - model: "interface/{module}"
+outputs:
+  - "{layout.rtl}/{module}.sv"
+skills: [lang-sv/rtl, org/naming]
+checks: [format, lint, naming, style, hardcode]
+budget:
+  tries: 3

chipgraph/packs/digital_rtl/skills/lang-sv-rtl.md

@@ -0,0 +1,58 @@
+---
+id: lang-sv/rtl
+description: How to write one synthesizable SystemVerilog module from its plan entry, requirements and interface, in the project's style.
+roles: [rtl-author]
+version: 0.1.0
+---
+Write one synthesizable SystemVerilog module per output file (`outputs[0]`), named as
+`rtl.module.name`. You see the plan, the requirements, the interface, the naming rules and
+the style exemplars; you never see a testbench, and must not guess one.
+
+What to use from the context:
+
+- `rtl.module`: the module's entry of the approved plan: its summary, the requirement ids
+  it covers (`reqs`), its ports, the modules it depends on and the files it may write.
+  Stay inside it: no file outside `outputs`, no port the entry does not list, no logic
+  that belongs to another module of the plan.
+- `rtl.interface.ports`: the module's ports, exactly (name, direction, width). A port with
+  `source: model` is the Design Model's; one with `source: plan` is internal to the block,
+  as a person approved it. Do not add, drop or rename a port.
+- `rtl.dependencies`: the modules this one instantiates or connects to, declarations only.
+  Instantiate them with named port connections (`.port(signal)`), every port connected.
+- `rtl.requirements`: what the module must do. Implement each one, and put its id in a
+  comment next to the logic that implements it: `// REQ-TIM-001: ...`.
+- `rtl.style.exemplars`: files of this project. **Follow their style where it differs
+  from your habits**: indentation, `begin` placement, how ports are declared and aligned,
+  the reset (asynchronous or synchronous, active low or high, its name) and the clocked
+  block, signal suffixes (`_q`/`_d`, `_r`/`_next`, ...), the comment header, blank lines,
+  line length. `rtl.style.profile` is the same, measured; the `style` check compares your
+  file with it (the keys in `rtl.style.enforce` fail the check).
+
+Synthesizable RTL:
+
+- `logic` for every signal; `always_ff` for registers, `always_comb` for logic, `assign`
+  for simple wires. No `initial` blocks for state, no `#` delays, no `$display`.
+- One clock and one reset convention, the exemplars' (asynchronous or synchronous, the
+  active level, the reset's name); every register is reset.
+- No latches: in `always_comb`, give every signal a value on every path (a default
+  assignment first, or a `default` branch in every `case`).
+- Every output is driven; every input bit is used (see lint, below).
+- Width-explicit literals (`8'd0`, `1'b1`, `32'h0000_0010`); parameters (`localparam`) for
+  every constant with a meaning, not magic numbers; never retype an address or size the
+  spec names as a number: the `hardcode` check rejects it.
+- Nonblocking `<=` in `always_ff`, blocking `=` in `always_comb`, never mixed.
+
+Lint is Verilator with `-Wall`, and any warning fails the check:
+
+- Every input bit is used, or consumed on purpose: for bits the module ignores, write
+  `logic unused_ok; assign unused_ok = &{1'b0, wdata[31:8]};` (Verilator ignores a signal
+  whose name contains `unused`). Do the same for a part of an internal signal you never
+  read.
+- No signal declared and never read, no width mismatch in an assignment or comparison
+  (size both sides, or slice and extend explicitly), no output left unconnected on an
+  instance (connect it to a named `unused_*` signal).
+- No `lint_off` pragmas, unless the style exemplars use them.
+
+The engine runs the project's formatter on your file, then lint, naming, style and
+hardcode. If the requirements or the interface are ambiguous or contradict each other, do
+not guess: stop and report `needs_human` with the question.

chipgraph/packs/digital_rtl/skills/org-naming.md

@@ -0,0 +1,29 @@
+---
+id: org/naming
+description: How to name modules, ports, parameters and signals from the project's naming rules in the context.
+roles: [rtl-author]
+version: 0.1.0
+---
+Names come from the project's naming rules, never from memory or another project's
+habits. The rules are in your context as text: `rtl.naming.text` (from the file
+`rtl.naming.rules`).
+
+How to read them:
+
+- "Allowed names, per kind": one line per kind of name you declare: `module`, `port`,
+  `parameter`, `localparam`, `enum_value`, `instance`, `signal`, `memory`, `genvar`.
+  The whole name must match the pattern of its kind. A port is checked as a port, a
+  signal as a signal: the check classifies each declaration by its syntax.
+- "Lexical rules": apply to every name you declare (case, active-low marks, indices).
+- "Vocabulary": a word on the left must not appear in a name; use the word on the right.
+
+Then:
+
+- The module name and the port names are fixed by `rtl.module` and `rtl.interface`; they
+  already follow the rules. Use them exactly.
+- Name every other signal, parameter and instance by its kind's pattern. When the style
+  exemplars use a suffix the rules allow (`_q`, `_d`, `_r`, `_next`), use the exemplars'.
+- When the rules and the exemplars disagree, the rules win: the `naming` check rejects a
+  name, the `style` check only warns unless the profile enforces that key.
+- When `rtl.naming` is empty, the project has no naming rules: follow the exemplars.
+- Never use the exemption comment the rules name.

chipgraph/packs/digital_rtl/skills/plan-modules.md

@@ -0,0 +1,63 @@
+---
+id: plan/modules
+description: How to split a block into modules and write its plan file.
+roles: [planner]
+version: 0.1.0
+---
+Write the block's plan to `outputs[0]` as YAML that follows `plan.schema` in your
+context. A person reads it (`chipgraph plan show`) and approves it before any module
+is built, so it must be complete and honest.
+
+1. **Interface first (F1).** Copy ports from `plan.interface.ports` exactly: name,
+   direction, width. Never invent a port. The `top` module carries the block's
+   interface. A helper port between two modules of the block is `internal: true`, and
+   is never on `top`.
+2. **Requirements.** Assign every requirement in `plan.requirements` to the module that
+   implements it, by its `id` (the REQ id; for an inferred requirement, its key such as
+   `timer.h1a2b3c4d`). One you cannot place goes in `unassigned_reqs` with a reason. Do
+   not invent requirements.
+3. **Write sets (F2).** Each module lists every file its nodes write, and no two modules
+   write the same file. Every path matches one of `plan.layout`. Each module's writes
+   include the files in `plan.module_outputs` (fill in `{block}` and `{module}`). Never
+   write a file in `plan.other_rules_write`. A file in `plan.existing_files` is written
+   only on purpose: say `replaces: true` on that write.
+4. **Dependencies.** `depends_on` names modules of this plan that must be built first
+   (a module needs the interfaces of the modules it instantiates). No cycles.
+5. **Size.** Stay inside `plan.limits`: at most `max_modules` modules, a dependency
+   chain of at most `max_depth` modules, and module `budget.tries` adding up to at most
+   `max_total_tries`. Prefer few modules with clear boundaries over many small ones.
+6. **Names.** Module names follow `plan.naming` when it is set.
+7. **Say what you assumed (F4).** List every assumption in `assumptions`, and anything
+   a person must decide in `open_questions` (the approver must read them).
+
+Example:
+
+```yaml
+schema_version: 1
+block: timer
+top: timer_top
+modules:
+  - name: timer_top
+    summary: Register interface and the irq output; instantiates the counter.
+    reqs: [REQ-TIM-004]
+    interface:
+      ports:
+        - { name: clk, direction: input, width: 1 }
+    depends_on: [timer_counter]
+    writes:
+      - { path: rtl/timer_top.sv }
+    budget: { tries: 3, tier: medium }
+  - name: timer_counter
+    summary: The 32-bit counter and its compare.
+    reqs: [REQ-TIM-001]
+    interface:
+      ports:
+        - { name: clk, direction: input, width: 1 }
+        - { name: count, direction: output, width: 32, internal: true }
+    writes:
+      - { path: rtl/timer_counter.sv }
+assumptions: [The counter wraps at 2^32.]
+open_questions: []
+unassigned_reqs:
+  - { req: REQ-TIM-005, reason: The read mux belongs to the bus wrapper, not planned here. }
+```

chipgraph/packs/digital_rtl/skills/review-diff.md

@@ -0,0 +1,41 @@
+---
+id: review/diff
+description: How to review a block's diff against its requirements, interface and Design Model.
+roles: [critic]
+version: 0.1.0
+---
+Review the diff in `review.diff` against `review.spec` (the block's requirements, its
+interface and its registers) and `review.model`. Read a changed file in full when the
+hunk alone does not show enough.
+
+Look for, in this order:
+
+- **spec/RTL mismatch**: behaviour a requirement states that the new code does not do,
+  or does differently (`spec_mismatch`; `missing_req` when a requirement's behaviour is
+  gone or never written).
+- **reset**: a register's reset value differs from the spec's `Reset` column (`reset`).
+- **width**: a signal, port or field narrower or wider than the spec says, a
+  truncating or extending assignment (`width`).
+- **counters and compares**: off by one, `<` for `<=`, the wrong step (`counter`).
+- **register map**: a register decoded at the wrong offset, a wrong access type, an
+  address decode that does not match the memory map (`register_map`).
+- **bit order**: fields or bits swapped or reversed against the spec (`bit_order`).
+- **latches**: a combinational block that does not assign every output on every path
+  (`latch`).
+- **CDC**: a signal crossing clock domains without a synchroniser (`cdc`).
+- **hard-coded values**: a literal where the spec has a register, parameter or named
+  constant (`hard_coded`).
+- **naming** against the project's rules, and **test gaps**: a changed requirement with
+  no test (`naming`, `test_gap`). Anything else: `other`.
+
+Rules:
+
+- Every comment is on a `file:line` inside the diff, and its `evidence` quotes what the
+  claim rests on: the spec line (`doc/...md:68 While CTRL.EN = 1, ...`) or the code line.
+  No evidence, no comment.
+- Name the requirement in `req_id` when there is one.
+- `blocker` or `major`: the design is wrong against the spec. `minor`: a real but small
+  problem. `nit`: optional. Do not comment on formatting, whitespace or comments that a
+  formatter or lint covers, and do not invent requirements the spec does not state.
+- When the diff is correct, say so: no comments, `reviewed` lists every file of the diff,
+  verdict `approve`.