chipgraph 0.1.0__py3-none-any.whl

chipgraph/packs/assist/triage/rules.py

@@ -0,0 +1,447 @@
+"""The deterministic triage rules: the first, free tier of `decide()` (DESIGN 5.4).
+
+Each rule looks only at *generic* evidence in a parsed log: what the tools and shells
+print when a tool or a file is missing, when time runs out, which kind of check failed,
+and whether every error points into a testbench or into RTL sources. No rule names a
+project, a file or a sample: `tests/packs/assist/test_triage_rules.py` fails if one does.
+
+A rule answers only when its evidence is unambiguous and returns `None` otherwise; a
+simulation mismatch never matches a rule (whether the RTL or the testbench is wrong can
+only be told against the spec), so it goes to the model tiers.
+
+Order matters: the environment is ruled out first (`infra`), then a failing spec cross
+check (`spec`), then compile/lint errors that all point into testbenches (`tb`) or all
+into RTL sources (`rtl`).
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+from fnmatch import fnmatch
+
+from chipgraph.core.contracts import Decision, Issue
+from chipgraph.core.engine.decide import Question, Rule, rule_decision
+from chipgraph.packs.assist.triage.contract import TriageLabel
+from chipgraph.packs.assist.triage.parse import CheckRun, ParsedLog
+
+SPEC_CROSS_CHECKS = frozenset({"ports_diff", "spec_schema", "trace", "cross_chip"})
+"""Checks that compare a spec with its users: when one fails, the spec side is at fault."""
+
+HDL_SUFFIXES = (".sv", ".svh", ".v", ".vh", ".vhd", ".vhdl")
+TB_DIRS = frozenset(
+    {"tb", "tbs", "dv", "verif", "verification", "testbench", "testbenches", "test", "tests"}
+)
+"""Directory names that hold testbenches by common convention."""
+
+TB_LAYOUT_KEYS = ("tb", "dv", "tests")
+"""Profile `layout` keys whose paths hold testbenches."""
+
+
+@dataclass(frozen=True)
+class TriageFacts:
+    """What the rules look at: the parsed log, the failing check, the testbench layout."""
+
+    parsed: ParsedLog
+    check_id: str | None = None
+    """The failing check id the caller named (`--check`), if any."""
+    check_kinds: tuple[tuple[str, str], ...] = ()
+    """`(check id, check kind)` pairs: the kind is the adapter the profile runs it with."""
+    tb_patterns: tuple[str, ...] = ()
+    """Glob patterns of testbench paths, from the profile's `layout`."""
+
+    def kind_of(self, check_id: str) -> str:
+        """The check's kind (its adapter), or its id when the profile does not say."""
+        return dict(self.check_kinds).get(check_id, check_id)
+
+
+@dataclass(frozen=True)
+class RuleHit:
+    """A rule's answer: the label, the rule's name, why, and where."""
+
+    label: TriageLabel
+    rule: str
+    reason: str
+    evidence: tuple[str, ...] = ()
+    hint: str = ""
+    """A specific next step (e.g. the missing tool), used in the suggestion."""
+
+
+# --- paths ------------------------------------------------------------------------------
+
+
+def _norm(path: str) -> str:
+    path = path.replace("\\", "/")
+    while path.startswith("./"):
+        path = path[2:]
+    return path
+
+
+def is_tb_path(path: str, patterns: tuple[str, ...] = ()) -> bool:
+    """True for a testbench path: a profile `layout` match, a `tb`/`dv`/... directory,
+    or a `tb_`/`test_` prefix or `_tb`/`_test` suffix on the file name."""
+    path = _norm(path)
+    if any(fnmatch(path, pattern) for pattern in patterns):
+        return True
+    parts = path.split("/")
+    if any(part.lower() in TB_DIRS for part in parts[:-1]):
+        return True
+    stem = parts[-1].lower().split(".", 1)[0]
+    return (
+        stem == "tb"
+        or stem.startswith(("tb_", "test_"))
+        or stem.endswith(("_tb", "_test", "_tests", "_tb_top"))
+    )
+
+
+def is_rtl_path(path: str, patterns: tuple[str, ...] = ()) -> bool:
+    """True for an HDL source that is not a testbench."""
+    return _norm(path).lower().endswith(HDL_SUFFIXES) and not is_tb_path(path, patterns)
+
+
+def tb_patterns(layout: dict[str, str | tuple[str, ...]]) -> tuple[str, ...]:
+    """Glob patterns for the testbench paths a profile's `layout` names."""
+    out: list[str] = []
+    for key in TB_LAYOUT_KEYS:
+        value = layout.get(key)
+        templates = (value,) if isinstance(value, str) else (value or ())
+        for template in templates:
+            pattern = _norm(re.sub(r"\{[^}]*\}", "*", template)).rstrip("/")
+            if pattern:
+                out.extend((pattern, f"{pattern}/*"))
+    return tuple(out)
+
+
+def where(issue: Issue) -> str:
+    """`file:line` (or just `file`) of an issue."""
+    if issue.file is None:
+        return ""
+    return f"{issue.file}:{issue.line}" if issue.line is not None else issue.file
+
+
+def _locations(issues: tuple[Issue, ...] | list[Issue], limit: int = 10) -> tuple[str, ...]:
+    out: list[str] = []
+    for issue in issues:
+        loc = where(issue)
+        if loc and loc not in out:
+            out.append(loc)
+        if len(out) >= limit:
+            break
+    return tuple(out)
+
+
+# --- infra evidence -----------------------------------------------------------------------
+
+_TOOL_MISSING = (
+    re.compile(
+        r"^(?:\S*/)?(?:ba|z|da|k)?sh(?:\[\d+\])?:\s*(?:line \d+:\s*)?(?:\d+:\s*)?"
+        r"(?P<tool>[^\s:]+): (?:command )?not found",
+        re.MULTILINE,
+    ),
+    re.compile(
+        r"^(?:\S*/)?g?make(?:\[\d+\])?: (?P<tool>[^\s:*]+): "
+        r"(?:No such file or directory|command not found)",
+        re.MULTILINE,
+    ),
+    re.compile(r"\bcommand not found: (?P<tool>\S+)"),
+    re.compile(r"(?P<tool>[^\s:]+): command not found"),
+    re.compile(r"\] Error 127\b"),
+)
+
+_INPUT_MISSING = (
+    re.compile(
+        r"Cannot find file containing module: "
+        r"'(?P<path>[^']*/[^']*|[^']*\.(?:sv|svh|v|vh|vhd|vhdl))'"
+    ),
+    re.compile(r"\bFile not found: (?P<path>\S+)"),
+    re.compile(r"Cannot find include file: ['\"]?(?P<path>[^'\"\s]+)"),
+    re.compile(
+        r"\b[Cc]an(?:no|')t open (?:file |input file |include file )?['\"]?(?P<path>[^'\"\s:]+)"
+    ),
+    re.compile(r"(?P<path>[^\s:]+): Permission denied"),
+    re.compile(r"\bPermission denied\b"),
+    re.compile(r"(?P<path>[^\s:'\"]+): No such file or directory"),
+    re.compile(r"\bNo such file or directory\b"),
+)
+
+_MAKE_TARGET = re.compile(r"No rule to make target [`'\"]?(?P<target>[^'`\"\s,]+)")
+_NO_TARGETS = re.compile(r"make(?:\[\d+\])?: \*\*\* No targets\b")
+
+_TIME_LIMIT = re.compile(
+    r"\btimed out\b|\btime ?limit (?:exceeded|reached)\b"
+    r"|\btimeout (?:after|expired|exceeded|reached)\b"
+    r"|^\s*(?:Killed|Terminated)\b|\bKilled: 9\b|\bSIG(?:KILL|TERM|XCPU)\b"
+    r"|\] Error 1(?:24|37)\b",
+    re.IGNORECASE | re.MULTILINE,
+)
+
+_TOOL_FAILURE = re.compile(
+    r"\binternal error\b|\bsegmentation fault\b|\bcore dumped\b|std::bad_alloc"
+    r"|\bout of memory\b|\blicen[cs]e\b.*\b(?:fail\w*|unavailable|denied|checkout|"
+    r"not available|expired)\b",
+    re.IGNORECASE,
+)
+
+
+def _scan_text(facts: TriageFacts) -> str:
+    """The log lines that may carry environment evidence: not a testbench's own failure
+    lines (a testbench printing 'timeout waiting for irq' is not an infra problem), plus
+    the messages of issues that name no file (a check that could not run)."""
+    failures = set(facts.parsed.sim_failures)
+    lines = [line for line in facts.parsed.lines if line.strip() not in failures]
+    lines.extend(i.msg for i in facts.parsed.issues if i.file is None)
+    for check in facts.parsed.failing_checks:
+        lines.extend(i.msg for i in check.issues if i.file is None)
+    return "\n".join(lines)
+
+
+def _first_line(text: str, start: int) -> str:
+    begin = text.rfind("\n", 0, start) + 1
+    end = text.find("\n", start)
+    return text[begin : end if end >= 0 else len(text)].strip()
+
+
+def check_could_not_run(facts: TriageFacts) -> RuleHit | None:
+    """A check reported `error` (it could not run: missing model, tool, adapter, time)."""
+    failing = facts.parsed.failing_checks
+    if not failing or any(c.status != "error" for c in failing):
+        return None
+    first = failing[0]
+    msgs = [i.msg for c in failing for i in c.issues]
+    reason = f"check {first.check_id!r} could not run" + (f": {msgs[0]}" if msgs else "")
+    return RuleHit("infra", "check_could_not_run", reason, hint=msgs[0] if msgs else "")
+
+
+def tool_missing(facts: TriageFacts) -> RuleHit | None:
+    """A shell or make could not find the program to run (exit 127)."""
+    text = _scan_text(facts)
+    for pattern in _TOOL_MISSING:
+        match = pattern.search(text)
+        if match is None:
+            continue
+        tool = match.groupdict().get("tool")
+        hint = (
+            f"install `{tool}` or put it on PATH (or load its module: `env.modules`)"
+            if tool
+            else "install the missing program or put it on PATH"
+        )
+        return RuleHit(
+            "infra",
+            "tool_missing",
+            f"a program is missing: {_first_line(text, match.start())}",
+            hint=hint,
+        )
+    return None
+
+
+def input_missing(facts: TriageFacts) -> RuleHit | None:
+    """A file the command needs does not exist or cannot be read."""
+    text = _scan_text(facts)
+    for pattern in _INPUT_MISSING:
+        match = pattern.search(text)
+        if match is None:
+            continue
+        path = match.groupdict().get("path")
+        line = _first_line(text, match.start())
+        if "Permission denied" in line:
+            hint = f"make `{path}` readable" if path else "fix the file permissions"
+        elif path:
+            hint = f"fix the path `{path}` in the filelist or the command, or restore the file"
+        else:
+            hint = "fix the path in the filelist or the command, or restore the file"
+        return RuleHit(
+            "infra",
+            "input_missing",
+            f"an input file is missing: {line}",
+            evidence=(path,) if path else (),
+            hint=hint,
+        )
+    return None
+
+
+def make_target_missing(facts: TriageFacts) -> RuleHit | None:
+    """`make` has no rule for the target the flow runs."""
+    text = _scan_text(facts)
+    match = _MAKE_TARGET.search(text) or _NO_TARGETS.search(text)
+    if match is None:
+        return None
+    target = match.groupdict().get("target")
+    hint = (
+        f"add the make target `{target}` or fix the command the profile runs"
+        if target
+        else "add the make target or fix the command the profile runs"
+    )
+    line = _first_line(text, match.start())
+    return RuleHit("infra", "make_target_missing", f"make has no such target: {line}", hint=hint)
+
+
+def time_limit(facts: TriageFacts) -> RuleHit | None:
+    """The command ran out of time or was killed."""
+    text = _scan_text(facts)
+    match = _TIME_LIMIT.search(text)
+    if match is None:
+        return None
+    line = _first_line(text, match.start())
+    return RuleHit(
+        "infra",
+        "time_limit",
+        f"the command ran out of time or was killed: {line}",
+        hint="find what it waits on (a licence, a lock, a hung tool) or raise its time limit "
+        "(`adapters.<check>.timeout_s`)",
+    )
+
+
+def tool_failure(facts: TriageFacts) -> RuleHit | None:
+    """The tool itself crashed, ran out of memory, or found no licence."""
+    text = _scan_text(facts)
+    match = _TOOL_FAILURE.search(text)
+    if match is None:
+        return None
+    line = _first_line(text, match.start())
+    return RuleHit(
+        "infra",
+        "tool_failure",
+        f"the tool failed: {line}",
+        hint="check the tool's installation, memory and licence, then rerun",
+    )
+
+
+# --- design evidence ---------------------------------------------------------------------
+
+
+def _failing_spec_checks(facts: TriageFacts) -> tuple[CheckRun, ...] | None:
+    """The failing checks, when every one of them is a spec cross check that ran."""
+    failing = facts.parsed.failing_checks
+    if failing:
+        if all(
+            c.status == "fail" and facts.kind_of(c.check_id) in SPEC_CROSS_CHECKS for c in failing
+        ):
+            return failing
+        return None
+    if facts.check_id is not None and facts.kind_of(facts.check_id) in SPEC_CROSS_CHECKS:
+        issues = facts.parsed.tool_issues
+        if issues:
+            return (CheckRun(facts.check_id, None, "fail", issues),)
+    return None
+
+
+def spec_cross_check(facts: TriageFacts) -> RuleHit | None:
+    """A spec cross check (`ports_diff`, `spec_schema`, `trace`, `cross_chip`) failed."""
+    if facts.parsed.sim_ran:
+        return None
+    checks = _failing_spec_checks(facts)
+    if checks is None:
+        return None
+    issues = [i for c in checks for i in c.issues]
+    if not issues or any(i.file is None for i in issues):
+        return None
+    names = ", ".join(sorted({c.check_id for c in checks}))
+    first = issues[0]
+    return RuleHit(
+        "spec",
+        "spec_cross_check",
+        f"the spec cross check {names} failed: {where(first)} [{first.rule}] {first.msg}",
+        evidence=_locations(issues),
+    )
+
+
+def _design_issues(facts: TriageFacts) -> list[Issue] | None:
+    """The compile/lint issues behind the failure, when they say where (else None)."""
+    parsed = facts.parsed
+    if parsed.sim_ran or parsed.unlocated_errors:
+        return None
+    if any(c.status == "error" for c in parsed.failing_checks):
+        return None
+    if any(facts.kind_of(c.check_id) in SPEC_CROSS_CHECKS for c in parsed.failing_checks):
+        return None
+    issues = [i for i in parsed.tool_issues if i.severity in ("error", "warning")]
+    for check in parsed.failing_checks:
+        issues.extend(i for i in check.issues if i.severity in ("error", "warning"))
+    if not issues or any(i.file is None for i in issues):
+        return None
+    return issues
+
+
+def testbench_compile(facts: TriageFacts) -> RuleHit | None:
+    """Every compile/lint error points into a testbench, and no simulation ran."""
+    issues = _design_issues(facts)
+    if issues is None or not all(is_tb_path(i.file or "", facts.tb_patterns) for i in issues):
+        return None
+    first = issues[0]
+    return RuleHit(
+        "tb",
+        "testbench_compile",
+        f"every error is in a testbench: {where(first)} [{first.rule}] {first.msg}",
+        evidence=_locations(issues),
+    )
+
+
+def rtl_lint(facts: TriageFacts) -> RuleHit | None:
+    """Every compile/lint error points into an RTL source, and no simulation ran."""
+    issues = _design_issues(facts)
+    if issues is None or not all(is_rtl_path(i.file or "", facts.tb_patterns) for i in issues):
+        return None
+    first = issues[0]
+    return RuleHit(
+        "rtl",
+        "rtl_lint",
+        f"every error is in an RTL source: {where(first)} [{first.rule}] {first.msg}",
+        evidence=_locations(issues),
+    )
+
+
+RULES: tuple[Callable[[TriageFacts], RuleHit | None], ...] = (
+    check_could_not_run,
+    tool_missing,
+    input_missing,
+    make_target_missing,
+    time_limit,
+    tool_failure,
+    spec_cross_check,
+    testbench_compile,
+    rtl_lint,
+)
+"""Every triage rule, in the order `decide()` tries them."""
+
+
+def evaluate(facts: TriageFacts) -> RuleHit | None:
+    """The first rule that answers, or None: what `decide()`'s rule tier will say."""
+    for rule in RULES:
+        hit = rule(facts)
+        if hit is not None:
+            return hit
+    return None
+
+
+def decide_rules(facts: TriageFacts, fired: list[RuleHit]) -> list[Rule]:
+    """The rules as `decide()` rules over `facts`; the hit that answered goes to `fired`."""
+
+    def make(rule: Callable[[TriageFacts], RuleHit | None]) -> Rule:
+        def decide_rule(question: Question) -> Decision | None:
+            hit = rule(facts)
+            if hit is None:
+                return None
+            fired.append(hit)
+            return rule_decision(question, hit.label)
+
+        decide_rule.__name__ = rule.__name__
+        return decide_rule
+
+    return [make(rule) for rule in RULES]
+
+
+__all__ = [
+    "HDL_SUFFIXES",
+    "RULES",
+    "SPEC_CROSS_CHECKS",
+    "TB_DIRS",
+    "RuleHit",
+    "TriageFacts",
+    "decide_rules",
+    "evaluate",
+    "is_rtl_path",
+    "is_tb_path",
+    "tb_patterns",
+    "where",
+]

chipgraph/packs/assist/triage/run.py

@@ -0,0 +1,224 @@
+"""`run_triage`: classify a failing log with `decide()` and build the `TriageReport`.
+
+1. parse the log (`parse.parse_log`): issues, check results, simulation failures, excerpt;
+2. ask `decide()` the question `question.build_question` builds, with the deterministic
+   `rules` first and the model tiers after them;
+3. turn the answer into a report: the deterministic summary and suggestion (`report`).
+
+The model backend follows the profile's runtime: `claude-code` queues the question for
+the `chipgraph:decider` subagent of the user's Claude Code session (the report is then
+`deferred`: run `/chipgraph:triage`, which runs the decider loop and triages again);
+an API runtime asks the `models.providers` provider through `LlmDecideBackend`. With no
+backend only the rules answer, and a log no rule classifies is `undecided`.
+
+A model's label is advice (DESIGN 4.8): it never blocks, and an answer under its tier's
+threshold is marked `low_confidence`.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from typing import Any, Literal, cast
+
+from chipgraph.adapters.llm import LlmError
+from chipgraph.adapters.llm.decide_backend import LlmDecideBackend
+from chipgraph.adapters.runtime.claude_code.decisions import ClaudeCodeDecideBackend
+from chipgraph.app.context import AppContext
+from chipgraph.core.config.models import Profile
+from chipgraph.core.contracts.types import DataLabel
+from chipgraph.core.engine.decide import (
+    DecideError,
+    DecisionLog,
+    Deferred,
+    ModelBackend,
+    decide,
+    low_confidence,
+)
+from chipgraph.packs.assist.ask.answer import make_provider
+from chipgraph.packs.assist.triage.contract import LABELS, SpecLine, TriageLabel, TriageReport
+from chipgraph.packs.assist.triage.parse import ParsedLog, parse_log
+from chipgraph.packs.assist.triage.question import build_question, spec_lines, spec_sources
+from chipgraph.packs.assist.triage.report import evidence, suggestion, summary
+from chipgraph.packs.assist.triage.rules import (
+    RuleHit,
+    TriageFacts,
+    decide_rules,
+    is_rtl_path,
+    is_tb_path,
+    tb_patterns,
+)
+
+MAX_REPORT_ISSUES = 50
+
+BackendChoice = ModelBackend | None | Literal["auto"]
+"""`"auto"`: the profile's runtime decides; `None`: rules only; or a given backend."""
+
+
+def default_backend(ctx: AppContext) -> ModelBackend | None:
+    """The model backend for the profile's runtime, or None when there is none."""
+    profile = ctx.require_profile().profile
+    if profile.runtime == "claude-code":
+        return ClaudeCodeDecideBackend(ctx.layout, profile.models)
+    provider = make_provider(profile)
+    if provider is None:
+        return None
+    return LlmDecideBackend(provider, profile.models, data=profile.data)
+
+
+def _check_kinds(profile: Profile) -> tuple[tuple[str, str], ...]:
+    return tuple(sorted((check_id, cfg.use) for check_id, cfg in profile.adapters.items()))
+
+
+def _check_id(parsed: ParsedLog, given: str | None) -> str | None:
+    if given:
+        return given
+    ids = {c.check_id for c in parsed.failing_checks}
+    return ids.pop() if len(ids) == 1 else None
+
+
+def _source_label(ctx: AppContext, source: str | None) -> DataLabel:
+    labels = ctx.store.labels
+    if source is None or source == "-":
+        return labels.default
+    path = Path(source)
+    if path.is_absolute():
+        try:
+            rel = path.resolve().relative_to(ctx.root.resolve()).as_posix()
+        except ValueError:
+            return labels.default
+    else:
+        rel = path.as_posix()
+    return labels.label_for(rel)
+
+
+def _logged(ctx: AppContext, question_id: str) -> tuple[str, str | None]:
+    """The reason and model of the decision `decide()` logged last for `question_id`."""
+    entries = [
+        e
+        for e in DecisionLog.for_layout(ctx.layout).read()
+        if e.question_id == question_id and e.event == "decided"
+    ]
+    if not entries:
+        return "", None
+    return entries[-1].reason, entries[-1].model
+
+
+def _spec_side(ctx: AppContext, parsed: ParsedLog, facts: TriageFacts) -> tuple[SpecLine, ...]:
+    """For a `spec` label whose issues all point at RTL or testbenches (a port width the
+    spec gets wrong is reported at the RTL port): the spec lines about those issues."""
+    for issue in parsed.issues:
+        path = issue.file
+        if path and not is_rtl_path(path, facts.tb_patterns) and not is_tb_path(path):
+            return ()
+    query = " ".join(i.msg for i in parsed.issues[:2])
+    specs, _ = spec_sources(ctx, query, facts, limit=3)
+    return specs
+
+
+async def triage_log(
+    ctx: AppContext,
+    log_text: str,
+    *,
+    source: str | None = None,
+    check_id: str | None = None,
+    backend: BackendChoice = "auto",
+) -> TriageReport:
+    """Classify `log_text` (a failing lint/sim/check log); see the module docstring."""
+    profile = ctx.require_profile().profile
+    parsed = parse_log(log_text)
+    facts = TriageFacts(
+        parsed=parsed,
+        check_id=_check_id(parsed, check_id),
+        check_kinds=_check_kinds(profile),
+        tb_patterns=tb_patterns(profile.layout),
+    )
+    specs, spec_labels = spec_lines(ctx, parsed, facts)
+    question = build_question(
+        parsed, facts, specs=specs, labels=(_source_label(ctx, source), *spec_labels)
+    )
+    chosen = default_backend(ctx) if backend == "auto" else backend
+    fired: list[RuleHit] = []
+    base: dict[str, Any] = {
+        "question_id": question.id,
+        "check_id": facts.check_id,
+        "source": source,
+        "summary": summary(parsed),
+        "issues": parsed.issues[:MAX_REPORT_ISSUES],
+        "excerpt": parsed.excerpt,
+        "spec_lines": specs,
+    }
+
+    try:
+        outcome = await decide(
+            question,
+            rules=decide_rules(facts, fired),
+            backend=chosen,
+            cfg=profile.decide,
+            log=DecisionLog.for_layout(ctx.layout),
+        )
+    except (DecideError, LlmError) as exc:
+        if chosen is None:
+            message = (
+                "no rule classified this log and no model is configured: set "
+                "models.providers (API runtime), or use runtime claude-code and run "
+                "/chipgraph:triage in Claude Code"
+            )
+        else:
+            message = f"no model answered: {exc}"
+        return TriageReport(status="undecided", message=message, **base)
+
+    if isinstance(outcome, Deferred):
+        where = f" {source}" if source and source != "-" else " <log>"
+        message = (
+            f"no rule classified this log; it waits for the {outcome.tier} model tier"
+            f" ({outcome.model or 'its model'}). In Claude Code run /chipgraph:triage{where}: "
+            "it answers the queued question with the decider subagent and triages again."
+        )
+        return TriageReport(
+            status="deferred",
+            model=outcome.model,
+            message=message,
+            **base,
+        )
+
+    label = cast(TriageLabel, outcome.value)
+    assert label in LABELS
+    if label == "spec" and not specs:
+        specs = _spec_side(ctx, parsed, facts)
+        base["spec_lines"] = specs
+    hit = fired[-1] if outcome.backend == "rule" and fired else None
+    if hit is not None:
+        reason, model = hit.reason, None
+    else:
+        reason, model = _logged(ctx, question.id)
+    return TriageReport(
+        status="decided",
+        label=label,
+        backend=outcome.backend,
+        rule=hit.rule if hit is not None else None,
+        confidence=outcome.confidence,
+        low_confidence=low_confidence(outcome, profile.decide),
+        suggestion=suggestion(label, parsed, facts, hit, specs),
+        retry_without_counting=label == "infra",
+        ask_person=label == "spec",
+        evidence=evidence(label, parsed, facts, hit, specs),
+        reason=reason,
+        model=model,
+        **base,
+    )
+
+
+def run_triage(
+    ctx: AppContext,
+    log_text: str,
+    *,
+    source: str | None = None,
+    check_id: str | None = None,
+    backend: BackendChoice = "auto",
+) -> TriageReport:
+    """`chipgraph triage`: `triage_log` in its own event loop."""
+    return asyncio.run(triage_log(ctx, log_text, source=source, check_id=check_id, backend=backend))
+
+
+__all__ = ["BackendChoice", "default_backend", "run_triage", "triage_log"]

chipgraph/packs/digital_rtl/__init__.py

@@ -0,0 +1,19 @@
+"""The ``digital-rtl`` pack: rules and skills for digital RTL (DESIGN.md 8.2).
+
+- the Critic review of each block's change: the rule ``digital-rtl/review``
+  (``rules/review.yml``) and its skill ``review/diff`` (``skills/review-diff.md``);
+- the Planner (M2-03): the rule ``digital-rtl/plan`` (``rules/plan.yml``, skill
+  ``plan/modules``, check ``plan_check``), the gate ``plan:{block}`` on the rule
+  ``digital-rtl/plan_expand`` (``rules/plan_expand.yml``), and the code behind them in
+  :mod:`chipgraph.packs.digital_rtl.plan` (the plan file model, the ``plan.modules``
+  resolver, the ``plan_expand`` tool, ``chipgraph plan show`` and the planner context);
+- the RTL of each planned module (M2-04): the rule ``digital-rtl/rtl_module``
+  (``rules/rtl_module.yml``, role ``rtl-author``, which never sees a testbench), its
+  skills ``lang-sv/rtl`` (``skills/lang-sv-rtl.md``) and ``org/naming``
+  (``skills/org-naming.md``), and the context in :mod:`chipgraph.packs.digital_rtl.rtl`.
+  Its checks ``format`` and ``style`` are :mod:`chipgraph.checks.format` and
+  :mod:`chipgraph.checks.style`.
+
+The pack directory is discovered by :func:`chipgraph.app.build.builtin_packs_dir`; a
+project turns it on with ``packs: [digital-rtl]``.
+"""