chipgraph 0.1.0__py3-none-any.whl

chipgraph/cli/__init__.py

@@ -0,0 +1,1688 @@
+"""chipgraph CLI (task M0-12): commands that run a project's build graph.
+
+A command is small on purpose: it parses options, builds an `AppContext` (and, when
+needed, a `Scheduler` via `chipgraph.app.build.make_scheduler`), and prints the result.
+All the wiring lives in `chipgraph.app` (DESIGN.md 3.3, 10.1, 10.4).
+
+Exit codes: 0 ok; 1 a check/run failed or is waiting; 2 usage/config error.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import json
+import os
+import shutil
+import subprocess
+import sys
+from collections import Counter
+from collections.abc import Callable, Mapping
+from pathlib import Path
+from typing import Annotated, Literal
+
+import typer
+import yaml
+
+from chipgraph import __version__
+from chipgraph.app import findings as findings_app
+from chipgraph.app.baseline import (
+    current_branch,
+    main_branch,
+    plan_project_baseline,
+    run_baseline,
+)
+from chipgraph.app.build import make_scheduler, project_graph
+from chipgraph.app.checks import ProfileCheckRunner
+from chipgraph.app.context import AppContext, default_identity, find_repo_root
+from chipgraph.app.errors import AppError
+from chipgraph.core.config.errors import ConfigError
+from chipgraph.core.config.loader import ConfigIssue
+from chipgraph.core.contracts import ArtifactRef, CheckResult, Finding, RuleInstance
+from chipgraph.core.engine import gate as gate_mod
+from chipgraph.core.engine.graph import BuildGraph, GraphError
+from chipgraph.core.engine.scheduler import RunSummary
+from chipgraph.core.plugin_api.local import LocalPluginRecord
+from chipgraph.core.state import journal as journal_mod
+from chipgraph.core.state import trace as trace_mod
+from chipgraph.core.state.findings import FindingStore, effective_status, waiver_gate_id
+from chipgraph.core.state.layout import StateLayout
+from chipgraph.core.state.trace import Tracer
+
+TraceExporter = Literal["none", "console", "otlp"]
+
+app = typer.Typer(no_args_is_help=True)
+config_app = typer.Typer(no_args_is_help=True, help="Inspect the resolved profile.")
+app.add_typer(config_app, name="config")
+
+
+class CliState:
+    """The global options every command reads: `--profile`, `--json`, `-C/--dir`, `--trace`."""
+
+    def __init__(
+        self,
+        *,
+        profile_path: Path | None,
+        json_output: bool,
+        start: Path,
+        trace: TraceExporter,
+    ) -> None:
+        self.profile_path = profile_path
+        self.json_output = json_output
+        self.start = start
+        self.trace = trace
+
+
+def _load_ctx(state: CliState) -> AppContext:
+    return AppContext.load(state.start, profile_path=state.profile_path)
+
+
+def _handle_errors[F: Callable[..., None]](func: F) -> F:
+    """Catch `AppError`/`ConfigError`, print the message, and exit 2."""
+
+    @functools.wraps(func)
+    def wrapper(*args: object, **kwargs: object) -> None:
+        try:
+            func(*args, **kwargs)
+        except (AppError, ConfigError) as exc:
+            typer.echo(str(exc), err=True)
+            raise typer.Exit(code=2) from exc
+
+    return wrapper  # type: ignore[return-value]
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"chipgraph {__version__}")
+        raise typer.Exit(code=0)
+
+
+def _default_trace() -> TraceExporter:
+    """`$CHIPGRAPH_TRACE`, if it names a known exporter, else `"none"`."""
+    value = os.environ.get("CHIPGRAPH_TRACE", "none").strip().lower()
+    if value in ("none", "console", "otlp"):
+        return value  # type: ignore[return-value]
+    return "none"
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            callback=_version_callback,
+            is_eager=True,
+            help="Show the chipgraph version and exit.",
+        ),
+    ] = False,
+    profile: Annotated[
+        Path | None,
+        typer.Option("--profile", help="Use this profile file instead of discovering one."),
+    ] = None,
+    json_output: Annotated[
+        bool, typer.Option("--json", help="Print machine-readable JSON instead of text.")
+    ] = False,
+    directory: Annotated[
+        Path | None,
+        typer.Option("-C", "--dir", help="Start looking for a profile from this directory."),
+    ] = None,
+    trace: Annotated[
+        TraceExporter | None,
+        typer.Option(
+            "--trace",
+            help="Export OpenTelemetry spans for build/resume ('none'|'console'|'otlp'); "
+            "default from $CHIPGRAPH_TRACE, else 'none'.",
+        ),
+    ] = None,
+) -> None:
+    """chipgraph: an AI agent system for chip (IC) design, built on a build graph."""
+    start = directory if directory is not None else Path.cwd()
+    ctx.obj = CliState(
+        profile_path=profile,
+        json_output=json_output,
+        start=start,
+        trace=trace if trace is not None else _default_trace(),
+    )
+
+
+# --- init --------------------------------------------------------------------------
+
+
+def _init_content(project: str, preset: str | None) -> str:
+    lines = [
+        "# chipgraph project profile (see DESIGN.md 8.3-8.6)",
+        "# generated by `chipgraph init`; edit freely.",
+        f"project: {project}",
+    ]
+    if preset:
+        lines.append(f'extends: ["preset:{preset}"]')
+    lines += [
+        "packs: []",
+        "adapters: {}",
+        "# adapters:",
+        "#   lint:",
+        "#     use: cmd",
+        '#     cmd: "make lint BLOCK={block}"',
+        "#     parser: verilator",
+        "blocks: {}",
+        "",
+    ]
+    return "\n".join(lines) + "\n"
+
+
+@app.command()
+@_handle_errors
+def init(
+    ctx: typer.Context,
+    project: Annotated[str | None, typer.Option("--project", help="Project name.")] = None,
+    preset: Annotated[
+        str | None, typer.Option("--preset", help="Extend an org/preset profile.")
+    ] = None,
+    force: Annotated[
+        bool, typer.Option("--force", help="Overwrite an existing .chipgraph.yml.")
+    ] = False,
+    from_learn: Annotated[
+        bool,
+        typer.Option(
+            "--from-learn",
+            help="Infer the profile from this repo (like `chipgraph learn`) instead of a stub.",
+        ),
+    ] = False,
+) -> None:
+    """Write a `.chipgraph.yml` at the repo root (a stub, or inferred with `--from-learn`)."""
+    state: CliState = ctx.obj
+    root = find_repo_root(state.start)
+    path = root / ".chipgraph.yml"
+    if path.is_file() and not force:
+        typer.echo(f"{path} already exists; pass --force to overwrite", err=True)
+        raise typer.Exit(code=2)
+
+    if from_learn:
+        from chipgraph.learn import InitFromLearnError, init_from_learn
+
+        if path.is_file() and force:
+            path.unlink()
+        try:
+            profile_path, naming_path = init_from_learn(root)
+        except InitFromLearnError as exc:
+            typer.echo(str(exc), err=True)
+            raise typer.Exit(code=2) from exc
+        typer.echo(f"wrote {profile_path} (inferred from {root})")
+        if naming_path is not None:
+            typer.echo(f"wrote {naming_path}")
+        typer.echo("review it, then:")
+        typer.echo("  chipgraph config check     # validate the profile")
+        return
+
+    name = project or root.name
+    path.write_text(_init_content(name, preset), encoding="utf-8")
+    typer.echo(f"wrote {path}")
+    typer.echo("next steps:")
+    typer.echo("  chipgraph config check     # validate the profile")
+    typer.echo("  chipgraph doctor           # check tools are on PATH")
+    typer.echo("  chipgraph learn            # fill this in from an existing repo (task M1-21)")
+
+
+# --- learn / try --------------------------------------------------------------------
+
+
+def _learn_json(result: object) -> str:
+    from chipgraph.learn import LearnResult
+
+    assert isinstance(result, LearnResult)
+    return json.dumps(result.model_dump(mode="json"), indent=2)
+
+
+def _print_learn_text(result: object) -> None:
+    from chipgraph.learn import LearnResult
+
+    assert isinstance(result, LearnResult)
+    typer.echo(f"# learned {result.project} from {result.root}")
+    typer.echo(f"# blocks: {', '.join(result.blocks) or '(none, single block)'}")
+    typer.echo("")
+    typer.echo("layout (kind: template  coverage):")
+    for lrule in result.layout:
+        typer.echo(f"  {lrule.kind:9} {lrule.template:34} {lrule.coverage.percent:3}%")
+    typer.echo("naming (kind: pattern  coverage  emitted):")
+    for nrule in result.naming:
+        mark = "rule" if nrule.emitted else "obs "
+        typer.echo(
+            f"  {mark} {nrule.kind:11} {nrule.pattern:30} {nrule.coverage.percent:3}% "
+            f"({nrule.coverage.matched}/{nrule.coverage.total})"
+        )
+    if result.observations:
+        typer.echo("observations:")
+        for obs in result.observations:
+            typer.echo(f"  {obs.topic:9} {obs.summary}")
+    if result.vendor_paths:
+        typer.echo("vendor paths (checks off, learned):")
+        for glob in result.vendor_paths:
+            typer.echo(f"  {glob}")
+
+
+@app.command()
+@_handle_errors
+def learn(
+    ctx: typer.Context,
+    path: Annotated[
+        Path | None, typer.Argument(help="Repo to learn (default: the current directory).")
+    ] = None,
+    out: Annotated[
+        Path | None,
+        typer.Option("--out", help="Write chipgraph.draft.yml (+ naming rules) into this dir."),
+    ] = None,
+    threshold: Annotated[
+        float,
+        typer.Option("--threshold", min=0.0, max=1.0, help="Min coverage to emit a naming rule."),
+    ] = 0.9,
+) -> None:
+    """Infer a draft profile from an existing repo, with per-rule coverage (DESIGN 8.6 V1)."""
+    from chipgraph.learn import dump_profile_yaml, write_draft
+    from chipgraph.learn import learn as run_learn
+    from chipgraph.learn.draft import DRAFT_NAMING_RULES_NAME, build_naming_rules
+
+    state: CliState = ctx.obj
+    root = (path if path is not None else state.start).resolve()
+    if not root.is_dir():
+        typer.echo(f"not a directory: {root}", err=True)
+        raise typer.Exit(code=2)
+
+    result = run_learn(root, threshold=threshold)
+
+    if state.json_output:
+        typer.echo(_learn_json(result))
+    else:
+        _print_learn_text(result)
+        naming_ref = DRAFT_NAMING_RULES_NAME if build_naming_rules(result) is not None else None
+        typer.echo("")
+        typer.echo("draft profile:")
+        typer.echo(dump_profile_yaml(result, naming_rules_ref=naming_ref))
+
+    if out is not None:
+        profile_path, naming_path = write_draft(result, out)
+        typer.echo(f"wrote {profile_path}")
+        if naming_path is not None:
+            typer.echo(f"wrote {naming_path}")
+
+
+@app.command("try")
+@_handle_errors
+def try_cmd(
+    ctx: typer.Context,
+    path: Annotated[
+        Path | None, typer.Argument(help="Repo to try (default: the current directory).")
+    ] = None,
+    profile: Annotated[
+        Path | None,
+        typer.Option("--profile", help="Use this draft profile (from `learn --out`) instead."),
+    ] = None,
+    threshold: Annotated[
+        float,
+        typer.Option("--threshold", min=0.0, max=1.0, help="Min coverage to emit a naming rule."),
+    ] = 0.9,
+) -> None:
+    """Run chipgraph read-only against a repo (ingest/check/audit), writing nothing into it."""
+    from chipgraph.learn.try_run import try_run
+
+    state: CliState = ctx.obj
+    root = (path if path is not None else state.start).resolve()
+    if not root.is_dir():
+        typer.echo(f"not a directory: {root}", err=True)
+        raise typer.Exit(code=2)
+
+    report = try_run(root, profile_path=profile, threshold=threshold)
+
+    if state.json_output:
+        payload = {
+            "project": report.result.project,
+            "ingest_ok": report.ingest_ok,
+            "ingest": report.ingest_summary,
+            "audit_available": report.audit_available,
+            "audit": report.audit_summary,
+            "files_with_issues": report.check_files_with_issues,
+            "checks": [
+                {"check": cid, "block": blk, "status": res.status, "issues": len(res.issues)}
+                for cid, blk, res in report.checks
+            ],
+        }
+        typer.echo(json.dumps(payload, indent=2))
+    else:
+        typer.echo(f"try {report.result.project} (read-only; nothing written to the repo)")
+        typer.echo(f"  ingest: {report.ingest_summary}")
+        for cid, blk, res in report.checks:
+            typer.echo(f"  {res.status.upper():6} {cid} {blk or '-'} {len(res.issues)} issues")
+        typer.echo(f"  {report.audit_summary}")
+        typer.echo(f"files with issues: {report.check_files_with_issues}")
+
+
+# --- config show / config check -----------------------------------------------------
+
+
+@config_app.command("show")
+@_handle_errors
+def config_show(
+    ctx: typer.Context,
+    explain: Annotated[
+        bool, typer.Option("--explain", help="One line per leaf key, with its source.")
+    ] = False,
+) -> None:
+    """Print the merged profile."""
+    state: CliState = ctx.obj
+    app_ctx = _load_ctx(state)
+    resolved = app_ctx.require_profile()
+    if explain:
+        for key, value, source in resolved.explain():
+            typer.echo(f"{key} = {value!r}  ({source.kind}:{source.location})")
+        return
+    typer.echo(yaml.safe_dump(resolved.profile.model_dump(mode="json"), sort_keys=True))
+
+
+@config_app.command("check")
+@_handle_errors
+def config_check(ctx: typer.Context) -> None:
+    """Print consistency issues in the resolved profile."""
+    state: CliState = ctx.obj
+    app_ctx = _load_ctx(state)
+    resolved = app_ctx.require_profile()
+    # Drop the generic per-plugin info line from `check()`: the richer lines built from
+    # what actually loaded (below) replace it, keeping the "runs code" warning wording.
+    issues = [i for i in resolved.check() if not i.key.startswith("plugins[")]
+    plugins = [_plugin_issue(index, rec) for index, rec in enumerate(app_ctx.local_plugins)]
+
+    if state.json_output:
+        payload = [
+            {"severity": i.severity, "key": i.key, "message": i.message}
+            for i in (*issues, *plugins)
+        ]
+        typer.echo(json.dumps(payload, indent=2))
+    else:
+        if not issues and not plugins:
+            typer.echo("no issues")
+        for issue in (*issues, *plugins):
+            typer.echo(f"{issue.severity:7} {issue.key}: {issue.message}")
+    if any(issue.severity == "error" for issue in (*issues, *plugins)):
+        raise typer.Exit(code=1)
+
+
+def _plugin_issue(index: int, record: LocalPluginRecord) -> ConfigIssue:
+    """One `config check` line per local plugin: loaded (with hash + registrations) or not."""
+    key = f"plugins[{index}]"
+    if not record.loaded:
+        return ConfigIssue(
+            severity="warning",
+            key=key,
+            message=f"{record.entry}: not loaded: {record.disabled_reason}",
+        )
+    registered = ", ".join(f"{kind}/{name}" for kind, name in record.registered) or "nothing"
+    return ConfigIssue(
+        severity="info",
+        key=key,
+        message=(
+            f"{record.path} (sha256 {(record.sha256 or '')[:8]}) registered {registered} "
+            "(runs code: review it like code)"
+        ),
+    )
+
+
+# --- check -------------------------------------------------------------------------
+
+
+def _fake_instance(check_id: str, block: str | None) -> RuleInstance:
+    """A throwaway `RuleInstance` carrying just the params `ProfileCheckRunner` reads."""
+    params = {"block": block} if block is not None else {}
+    rule_id = "chipgraph/check"
+    safe = "".join(c if c.isalnum() else "_" for c in check_id)
+    output_path = f".chipgraph/tmp/check-{safe}-{block or 'all'}.json"
+    return RuleInstance(
+        rule_id=rule_id,
+        params=params,
+        outputs=(ArtifactRef(kind="report", path=output_path),),
+        instance_id=RuleInstance.make_id(rule_id, params),
+    )
+
+
+async def _run_checks(
+    runner: ProfileCheckRunner, combos: list[tuple[str, str | None]]
+) -> list[tuple[str, str | None, CheckResult]]:
+    results: list[tuple[str, str | None, CheckResult]] = []
+    for check_id, block in combos:
+        instance = _fake_instance(check_id, block)
+        result = await runner.run(check_id, instance)
+        results.append((check_id, block, result))
+    return results
+
+
+@app.command()
+@_handle_errors
+def check(
+    ctx: typer.Context,
+    block: Annotated[
+        list[str], typer.Option("--block", help="Run only for this block (repeatable).")
+    ] = [],  # noqa: B006
+    only: Annotated[
+        list[str], typer.Option("--only", help="Run only this check id (repeatable).")
+    ] = [],  # noqa: B006
+) -> None:
+    """Run checks directly against the current working tree, without the build graph."""
+    state: CliState = ctx.obj
+    app_ctx = _load_ctx(state)
+    resolved = app_ctx.require_profile()
+
+    check_ids = list(only) if only else sorted(resolved.profile.adapters)
+    raw_blocks = list(block) if block else sorted(resolved.profile.blocks)
+    blocks: list[str | None] = list(raw_blocks) if raw_blocks else [None]
+
+    runner = ProfileCheckRunner(app_ctx)
+    # A chip-wide check (per_block = False) runs once for the whole project, unless the
+    # user scoped the run with --block; running it per block would repeat its issues and
+    # drop those that belong to no block.
+    combos = [
+        (cid, b)
+        for cid in check_ids
+        for b in (blocks if block or runner.runs_per_block(cid) else [None])
+    ]
+    results = asyncio.run(_run_checks(runner, combos))
+
+    if state.json_output:
+        typer.echo(json.dumps([r.model_dump(mode="json") for _, _, r in results], indent=2))
+    else:
+        for check_id, blk, result in results:
+            status = result.status.upper()
+            typer.echo(f"{status:6} {check_id} {blk or '-'} {len(result.issues)} issues")
+            for issue in result.issues:
+                loc = f"{issue.file or '-'}:{issue.line or '-'}"
+                typer.echo(f"  {loc}  [{issue.rule}] {issue.msg}")
+
+    if any(not r.ok for _, _, r in results):
+        raise typer.Exit(code=1)
+
+
+# --- audit --------------------------------------------------------------------------
+
+
+def _print_audit_text(report: object) -> None:
+    from chipgraph.packs.assist.audit import AuditReport
+
+    assert isinstance(report, AuditReport)
+    if report.ingest.ran:
+        by_sev = report.ingest.by_severity
+        summary = ", ".join(f"{sev}={by_sev[sev]}" for sev in sorted(by_sev)) or "none"
+        typer.echo(f"ingest issues: {summary}")
+        for message in report.ingest.errors:
+            typer.echo(f"  error  {message}")
+
+    typer.echo("checks:")
+    for check in report.checks:
+        typer.echo(
+            f"  {check.status.upper():6} {check.check_id} {check.block or '-'} "
+            f"L{check.layer} {check.issues} issues"
+        )
+
+    if not report.layers:
+        typer.echo("findings: none")
+    for layer in report.layers:
+        sev = ", ".join(f"{s}={layer.by_severity[s]}" for s in sorted(layer.by_severity))
+        st = ", ".join(f"{s}={layer.by_status[s]}" for s in sorted(layer.by_status))
+        typer.echo(f"layer {layer.layer}: {sev}   [{st}]")
+        for finding in layer.findings:
+            mark = "BLOCK" if finding.blocking else "     "
+            typer.echo(
+                f"  {mark} {finding.id}  {finding.severity:9}{finding.status:10}"
+                f"{finding.source:16}{finding.evidence:40}{finding.claim}"
+            )
+    typer.echo(report.summary_line())
+
+
+@app.command()
+@_handle_errors
+def audit(
+    ctx: typer.Context,
+    block: Annotated[
+        list[str], typer.Option("--block", help="Audit only this block (repeatable).")
+    ] = [],  # noqa: B006
+    no_ingest: Annotated[
+        bool, typer.Option("--no-ingest", help="Skip the ingest step (reuse the model cache).")
+    ] = False,
+    strict: Annotated[
+        bool, typer.Option("--strict", help="Exit 1 if any blocking finding exists.")
+    ] = False,
+) -> None:
+    """Run every deterministic check over the whole project, grouped by layer (DESIGN 4.8)."""
+    from chipgraph.packs.assist.audit import run_audit
+
+    state: CliState = ctx.obj
+    app_ctx = _load_ctx(state)
+    app_ctx.require_profile()
+    report = run_audit(app_ctx, ingest=not no_ingest, blocks=list(block) if block else None)
+
+    if state.json_output:
+        typer.echo(json.dumps(report.model_dump(mode="json"), indent=2))
+    else:
+        _print_audit_text(report)
+
+    if strict and report.has_blocking:
+        raise typer.Exit(code=1)
+
+
+# --- ingest -------------------------------------------------------------------------
+
+
+@app.command()
+@_handle_errors
+def ingest(
+    ctx: typer.Context,
+    strict: Annotated[
+        bool, typer.Option("--strict", help="Exit 1 if any error-severity issue was found.")
+    ] = False,
+) -> None:
+    """Run every extractor, build the Design Model, and print stats."""
+    from chipgraph.app.ingest import run_ingest
+
+    state: CliState = ctx.obj
+    app_ctx = _load_ctx(state)
+    app_ctx.require_profile()
+    report = run_ingest(app_ctx)
+    stats = report.result.stats
+
+    if state.json_output:
+        payload = {
+            "db": str(report.db_path),
+            "build_inputs_hash": report.result.build_inputs_hash,
+            "stats": stats.model_dump(mode="json"),
+            "issues": [i.model_dump(mode="json") for i in report.issues],
+        }
+        typer.echo(json.dumps(payload, indent=2))
+    else:
+        _print_ingest_text(stats, report)
+
+    if strict and report.has_error:
+        raise typer.Exit(code=1)
+
+
+def _print_ingest_text(stats: object, report: object) -> None:
+    from chipgraph.app.ingest import IngestReport
+    from chipgraph.core.model.ingest import IngestStats
+
+    assert isinstance(stats, IngestStats)
+    assert isinstance(report, IngestReport)
+    typer.echo(
+        f"inputs: {stats.inputs}   entities: {stats.entities}   relations: {stats.relations}"
+    )
+    if stats.entities_by_kind:
+        typer.echo("entities by kind:")
+        for kind, count in sorted(stats.entities_by_kind.items()):
+            typer.echo(f"  {count:5} {kind}")
+    if stats.entities_by_block:
+        typer.echo("entities by block:")
+        for block, count in sorted(stats.entities_by_block.items()):
+            typer.echo(f"  {count:5} {block or '(none)'}")
+    by_sev = stats.diagnostics_by_severity
+    if by_sev:
+        summary = ", ".join(f"{sev}={by_sev[sev]}" for sev in sorted(by_sev))
+        typer.echo(f"issues: {summary}   conflicts: {stats.conflicts}")
+    else:
+        typer.echo(f"issues: none   conflicts: {stats.conflicts}")
+    if report.documents is not None:
+        nda = len(report.documents.nda_skipped)
+        typer.echo(
+            f"documents indexed for /ask: {len(report.documents.indexed)} "
+            f"({report.documents.lines} lines; {nda} nda file(s) not indexed)"
+        )
+    shown = [i for i in report.issues if i.severity in ("warning", "error")][:20]
+    for issue in shown:
+        loc = f"{issue.file or '-'}:{issue.line or '-'}"
+        typer.echo(f"  {issue.severity:7} [{issue.code}] {loc}  {issue.message}")
+    typer.echo(f"db: {report.db_path}")
+
+
+# --- build / resume / rewind --------------------------------------------------------
+
+
+def _handoff_path(app_ctx: AppContext, run_id: str) -> Path:
+    return app_ctx.layout.run_dir(run_id) / "HANDOFF.md"
+
+
+def _print_summary(summary: RunSummary, json_output: bool, handoff_path: Path) -> None:
+    if json_output:
+        payload = summary.model_dump(mode="json")
+        payload["handoff"] = str(handoff_path)
+        typer.echo(json.dumps(payload, indent=2))
+        return
+    typer.echo(f"run {summary.run_id}")
+    for label, ids in (
+        ("done", summary.done),
+        ("skipped (fresh)", summary.skipped_fresh),
+        ("failed", summary.failed),
+        ("waiting on a gate", summary.waiting_gate),
+        ("blocked", summary.blocked),
+    ):
+        if ids:
+            typer.echo(f"  {label}: {', '.join(ids)}")
+    typer.echo(str(handoff_path))
+
+
+def _build_tracer(state: CliState, *, offline: bool) -> Tracer:
+    """Build the tracer `build`/`resume` should use for this invocation."""
+    return trace_mod.configure(state.trace, offline=offline)
+
+
+@app.command()
+@_handle_errors
+def build(
+    ctx: typer.Context,
+    target: Annotated[
+        str, typer.Argument(help="Rule id, 'id[k=v]', a named target ('rtl:timer'), or '*'.")
+    ],
+    concurrency: Annotated[int, typer.Option("--concurrency", min=1)] = 4,
+) -> None:
+    """Build TARGET with the scheduler."""
+    state: CliState = ctx.obj
+    app_ctx = _load_ctx(state)
+    resolved = app_ctx.require_profile()
+    tracer = _build_tracer(state, offline=resolved.profile.offline)
+    scheduler = make_scheduler(app_ctx, target, concurrency=concurrency, tracer=tracer)
+    try:
+        summary = asyncio.run(scheduler.run(target))
+    finally:
+        tracer.flush()
+    _print_summary(summary, state.json_output, _handoff_path(app_ctx, summary.run_id))
+    if not summary.ok:
+        raise typer.Exit(code=1)
+
+
+@app.command()
+@_handle_errors
+def resume(ctx: typer.Context, run_id: Annotated[str, typer.Argument()]) -> None:
+    """Resume a run that was interrupted."""
+    state: CliState = ctx.obj
+    app_ctx = _load_ctx(state)
+    resolved = app_ctx.require_profile()
+    tracer = _build_tracer(state, offline=resolved.profile.offline)
+    scheduler = make_scheduler(app_ctx, "*", tracer=tracer)
+    if isinstance(scheduler.checks, ProfileCheckRunner):
+        scheduler.checks.run_id = run_id
+    try:
+        summary = asyncio.run(scheduler.resume(run_id))
+    finally:
+        tracer.flush()
+    _print_summary(summary, state.json_output, _handoff_path(app_ctx, summary.run_id))
+    if not summary.ok:
+        raise typer.Exit(code=1)
+
+
+@app.command()
+@_handle_errors
+def rewind(ctx: typer.Context, instance_id: Annotated[str, typer.Argument()]) -> None:
+    """Delete a rule instance's record (and everything downstream), so it rebuilds."""
+    state: CliState = ctx.obj
+    app_ctx = _load_ctx(state)
+    app_ctx.require_profile()
+    scheduler = make_scheduler(app_ctx, "*")
+    ids = sorted(scheduler.rewind(instance_id))
+    if state.json_output:
+        typer.echo(json.dumps(ids))
+    else:
+        for iid in ids:
+            typer.echo(f"rewound {iid}")
+
+
+# --- status --------------------------------------------------------------------------
+
+
+def _latest_run_id(layout: StateLayout) -> str | None:
+    if not layout.runs_dir.is_dir():
+        return None
+    ids = sorted(p.name for p in layout.runs_dir.iterdir() if p.is_dir())
+    return ids[-1] if ids else None
+
+
+@app.command()
+@_handle_errors
+def status(ctx: typer.Context, run_id: Annotated[str | None, typer.Argument()] = None) -> None:
+    """Show the status of the latest run, or a given one."""
+    state: CliState = ctx.obj
+    app_ctx = _load_ctx(state)
+    layout = app_ctx.layout
+    rid = run_id or _latest_run_id(layout)
+    if rid is None:
+        typer.echo("no runs found")
+        return
+
+    journal_read = journal_mod.read(layout.journal(rid))
+    run_state = journal_mod.replay(journal_read.events)
+    gate_of: dict[str, str] = {}
+    for event in journal_read.events:
+        if event.type == "gate_wait" and event.rule_instance is not None:
+            gate_of[event.rule_instance] = str(event.payload.get("gate", ""))
+    waiting = {
+        iid: gate_of.get(iid, "") for iid, st in run_state.rules.items() if st == "waiting_gate"
+    }
+    counts = Counter(run_state.rules.values())
+
+    if state.json_output:
+        typer.echo(
+            json.dumps(
+                {
+                    "run_id": rid,
+                    "started": run_state.started,
+                    "stopped": run_state.stopped,
+                    "rules": run_state.rules,
+                    "counts": dict(counts),
+                    "waiting_gates": waiting,
+                    "chain": _chain_rows(app_ctx, rid, run_state.rules),
+                },
+                indent=2,
+            )
+        )
+        return
+
+    typer.echo(f"run {rid}  started={run_state.started}  stopped={run_state.stopped}")
+    for iid, st in sorted(run_state.rules.items()):
+        typer.echo(f"  {st:13} {iid}")
+    typer.echo("counts: " + ", ".join(f"{k}={v}" for k, v in sorted(counts.items())))
+    if waiting:
+        typer.echo("waiting on gates:")
+        for iid, gate_id in sorted(waiting.items()):
+            typer.echo(f"  {iid} -> {gate_id}")
+    chain = _target_chain(app_ctx, rid, run_state.rules)
+    if chain:
+        typer.echo(f"chain of {chain[0]}:")
+        typer.echo(chain[1])
+
+
+def _chain_rows(app_ctx: AppContext, rid: str, states: Mapping[str, str]) -> list[dict[str, str]]:
+    """The instances of the run's named target, in build order, with their state.
+
+    Empty when the run's target is not a named target (`rtl:<block>`), or the graph
+    cannot be built now.
+    """
+    if app_ctx.resolved is None:
+        return []
+    try:
+        target = journal_mod.read_manifest(app_ctx.layout, rid).target
+        graph = project_graph(app_ctx)
+        if graph.targets is None or not graph.targets.is_target(target):
+            return []
+        selected = graph.select(target)
+    except (AppError, GraphError, OSError, ValueError):
+        return []
+    rows: list[dict[str, str]] = []
+    for iid in graph.topo_order():
+        if iid in selected:
+            rows.append({"instance": iid, "state": states.get(iid, "not run")})
+    return rows
+
+
+def _target_chain(
+    app_ctx: AppContext, rid: str, states: Mapping[str, str]
+) -> tuple[str, str] | None:
+    rows = _chain_rows(app_ctx, rid, states)
+    if not rows:
+        return None
+    target = journal_mod.read_manifest(app_ctx.layout, rid).target
+    lines = [f"  {i + 1:2}. {r['state']:13} {r['instance']}" for i, r in enumerate(rows)]
+    return target, "\n".join(lines)
+
+
+# --- approve -------------------------------------------------------------------------
+
+
+@app.command()
+@_handle_errors
+def approve(
+    ctx: typer.Context,
+    gate_id: Annotated[str, typer.Argument()],
+    instance: Annotated[
+        str | None,
+        typer.Option(
+            "--instance",
+            help="The rule instance id; optional when exactly one instance has the gate.",
+        ),
+    ] = None,
+    reject: Annotated[bool, typer.Option("--reject", help="Reject instead of approve.")] = False,
+    by: Annotated[str | None, typer.Option("--by")] = None,
+    note: Annotated[str, typer.Option("--note")] = "",
+) -> None:
+    """Record an approve/reject decision for a gate over a rule instance's inputs."""
+    state: CliState = ctx.obj
+    app_ctx = _load_ctx(state)
+    app_ctx.require_profile()
+    scheduler = make_scheduler(app_ctx, "*")
+    if instance is None:
+        instance = _gated_instance(scheduler.graph, gate_id)
+    rule_instance = scheduler.graph.instances.get(instance)
+    if rule_instance is None:
+        raise AppError(
+            f"no such rule instance {instance!r}; known instances: "
+            f"{sorted(scheduler.graph.instances)}"
+        )
+    decision: Literal["approve", "reject"] = "reject" if reject else "approve"
+    who = by or default_identity()
+    try:
+        approval = gate_mod.approve(
+            app_ctx.review,
+            app_ctx.store,
+            gate_id,
+            rule_instance,
+            by=who,
+            decision=decision,
+            note=note,
+        )
+    except gate_mod.GateError as exc:
+        raise AppError(str(exc)) from exc
+    if state.json_output:
+        typer.echo(approval.model_dump_json())
+    else:
+        typer.echo(f"{decision} recorded for gate {gate_id!r} by {who!r}")
+
+
+def _gated_instance(graph: BuildGraph, gate_id: str) -> str:
+    """The one instance whose rule's gate is `gate_id`; an `AppError` if not exactly one."""
+    found = sorted(
+        iid
+        for iid, inst in graph.instances.items()
+        if (rule := graph.rules[inst.rule_id]).gate
+        and _format_gate_id(rule.gate, inst.params) == gate_id
+    )
+    if len(found) != 1:
+        known = sorted(
+            {
+                _format_gate_id(rule.gate, inst.params)
+                for inst in graph.instances.values()
+                if (rule := graph.rules[inst.rule_id]).gate
+            }
+        )
+        what = "no instance has" if not found else f"{len(found)} instances have"
+        raise AppError(
+            f"{what} gate {gate_id!r}: pass --instance; gates: {', '.join(known) or 'none'}"
+        )
+    return found[0]
+
+
+def _format_gate_id(template: str, params: dict[str, str]) -> str:
+    try:
+        return gate_mod.gate_id_for(template, params)
+    except gate_mod.GateError:
+        return template
+
+
+# --- plan, rtl: the RTL target of a block --------------------------------------------
+
+
+def _plan_show(state: CliState, block: str) -> None:
+    from chipgraph.packs.digital_rtl.plan.show import plan_summary, render_text
+
+    app_ctx = _load_ctx(state)
+    summary = plan_summary(app_ctx, block)
+    if state.json_output:
+        typer.echo(json.dumps(summary, indent=2))
+    else:
+        typer.echo(render_text(summary), nl=False)
+    if not summary["exists"] or not summary["ok"]:
+        raise typer.Exit(code=1)
+
+
+def _build_target(state: CliState, target: str, concurrency: int) -> None:
+    """Build a named target, print the run and what is next; exit like `build`."""
+    from chipgraph.cli.next_steps import next_steps, write_chain
+
+    app_ctx = _load_ctx(state)
+    resolved = app_ctx.require_profile()
+    tracer = _build_tracer(state, offline=resolved.profile.offline)
+    scheduler = make_scheduler(app_ctx, target, concurrency=concurrency, tracer=tracer)
+    try:
+        summary = asyncio.run(scheduler.run(target))
+    finally:
+        tracer.flush()
+    steps = next_steps(app_ctx, scheduler.graph, summary)
+    handoff = _handoff_path(app_ctx, summary.run_id)
+    steps["chain"] = [
+        {"instance": iid, "state": st}
+        for iid, st in write_chain(handoff, scheduler.graph, target, summary)
+    ]
+    if state.json_output:
+        payload = summary.model_dump(mode="json")
+        payload["handoff"] = str(handoff)
+        payload["target"] = target
+        payload["next"] = steps
+        typer.echo(json.dumps(payload, indent=2))
+    else:
+        _print_summary(summary, False, handoff)
+        typer.echo("next:")
+        for step in steps["lines"]:
+            typer.echo(f"  {step}")
+    if not summary.ok:
+        raise typer.Exit(code=1)
+
+
+@app.command("plan")
+@_handle_errors
+def plan_cmd(
+    ctx: typer.Context,
+    words: Annotated[
+        list[str],
+        typer.Argument(help="BLOCK: build its plan up to the gate; 'show BLOCK': read it."),
+    ],
+    concurrency: Annotated[int, typer.Option("--concurrency", min=1)] = 4,
+) -> None:
+    """Build a block's plan up to and including its gate `plan:<block>`, or show it.
+
+    `chipgraph plan <block>` builds target `plan:<block>` (the planner writes the plan,
+    `plan_check` checks it, the build waits on the gate) and prints what is next: the
+    gate to approve, or the tasks waiting for `/chipgraph:run`. Exit 0 when the gate is
+    approved, 1 while something waits or failed, 2 on a usage or config error.
+
+    `chipgraph plan show <block>` prints the plan for its approver: modules, REQ
+    coverage, write sets, questions; exit 1 when there is none yet or it fails
+    `plan_check`.
+    """
+    state: CliState = ctx.obj
+    if len(words) == 2 and words[0] == "show":
+        _plan_show(state, words[1])
+        return
+    if len(words) != 1:
+        raise AppError("usage: chipgraph plan <block> | chipgraph plan show <block>")
+    _build_target(state, f"plan:{words[0]}", concurrency)
+
+
+@app.command("rtl")
+@_handle_errors
+def rtl_cmd(
+    ctx: typer.Context,
+    block: Annotated[str, typer.Argument(help="The block.")],
+    concurrency: Annotated[int, typer.Option("--concurrency", min=1)] = 4,
+) -> None:
+    """Build target `rtl:<block>`: plan, gate, RTL per module, testbench, review, PR, gate.
+
+    Prints what is next: the gate to approve (`plan:<block>`, then `pr:<block>` and the
+    PR's URL), or the agent tasks waiting for `/chipgraph:run`. Exit 0 when the PR is
+    approved, 1 while something waits or failed, 2 on a usage or config error.
+    """
+    _build_target(ctx.obj, f"rtl:{block}", concurrency)
+
+
+# --- baseline ------------------------------------------------------------------------
+
+
+def _baseline_plan_json(plan: object) -> dict[str, object]:
+    from chipgraph.core.engine.baseline import BaselineArtifact, BaselineGate, BaselinePlan
+
+    assert isinstance(plan, BaselinePlan)
+
+    def _artifact(a: BaselineArtifact) -> dict[str, object]:
+        commit = (
+            {
+                "short_sha": a.last_commit.short_sha,
+                "date": a.last_commit.date,
+                "subject": a.last_commit.subject,
+                "is_merge": a.last_commit.is_merge,
+            }
+            if a.last_commit is not None
+            else None
+        )
+        return {
+            "path": a.path,
+            "sha256": a.sha256,
+            "short_sha256": a.short_sha256,
+            "status": a.status,
+            "baselineable": a.baselineable,
+            "last_commit": commit,
+        }
+
+    def _gate(g: BaselineGate) -> dict[str, object]:
+        return {
+            "gate_id": g.gate_id,
+            "instance_id": g.instance_id,
+            "already_decided": g.already_decided,
+            "will_baseline": g.will_baseline,
+            "artifacts": [_artifact(a) for a in g.artifacts],
+        }
+
+    return {
+        "gates": [_gate(g) for g in plan.gates],
+        "gates_to_baseline": [g.gate_id for g in plan.gates_to_baseline],
+        "skipped_gates": [g.gate_id for g in plan.skipped_gates],
+        "dirty_artifacts": [_artifact(a) for a in plan.dirty_artifacts],
+        "open_findings": plan.open_findings,
+    }
+
+
+def _print_baseline_text(plan: object) -> None:
+    from chipgraph.core.engine.baseline import BaselinePlan
+
+    assert isinstance(plan, BaselinePlan)
+    if not plan.gates:
+        typer.echo("no gates found: nothing to baseline")
+    for gate in plan.gates:
+        state = "decided (skipped)" if gate.already_decided else "waiting"
+        typer.echo(f"gate {gate.gate_id}  [{gate.instance_id}]  {state}")
+        for artifact in gate.artifacts:
+            commit = artifact.last_commit
+            where = (
+                f"{commit.short_sha} {commit.date} {commit.subject}"
+                if commit is not None
+                else "(no commit)"
+            )
+            typer.echo(f"    {artifact.status:9} {artifact.short_sha256}  {artifact.path}  {where}")
+    if plan.dirty_artifacts:
+        typer.echo("not baselined (modified or untracked in the working tree):")
+        for artifact in plan.dirty_artifacts:
+            typer.echo(f"    {artifact.status:9} {artifact.path}")
+    typer.echo(f"open findings: {plan.open_findings}")
+    to_do = plan.gates_to_baseline
+    if to_do:
+        typer.echo(f"would baseline {len(to_do)} gate(s): {', '.join(g.gate_id for g in to_do)}")
+    else:
+        typer.echo("would baseline 0 gates")
+
+
+@app.command("baseline")
+@_handle_errors
+def baseline_cmd(
+    ctx: typer.Context,
+    confirm: Annotated[
+        bool, typer.Option("--confirm", help="Record the baseline decisions (default: dry run).")
+    ] = False,
+    by: Annotated[str | None, typer.Option("--by")] = None,
+    note: Annotated[str, typer.Option("--note")] = "",
+    allow_branch: Annotated[
+        bool,
+        typer.Option("--allow-branch", help="Allow running on a branch other than main."),
+    ] = False,
+) -> None:
+    """List the artifacts on the main branch and, with --confirm, baseline them (DESIGN 6.4)."""
+    state: CliState = ctx.obj
+    app_ctx = _load_ctx(state)
+    app_ctx.require_profile()
+
+    branch = current_branch(app_ctx.root)
+    main = main_branch(app_ctx.root)
+    if not allow_branch and branch is not None and branch != main:
+        typer.echo(
+            f"refusing to baseline on branch {branch!r}: not the main branch {main!r} "
+            "(pass --allow-branch to override)",
+            err=True,
+        )
+        raise typer.Exit(code=1)
+
+    plan, refs_by_path = plan_project_baseline(app_ctx)
+
+    if not confirm:
+        if state.json_output:
+            typer.echo(json.dumps(_baseline_plan_json(plan), indent=2))
+        else:
+            _print_baseline_text(plan)
+        return
+
+    who = by or default_identity()
+    outcome = run_baseline(app_ctx, plan, refs_by_path, by=who, note=note)
+    if state.json_output:
+        typer.echo(
+            json.dumps(
+                {
+                    "recorded_gates": [a.gate_id for a in outcome.approvals],
+                    "findings_baselined": list(outcome.findings_baselined),
+                },
+                indent=2,
+            )
+        )
+    else:
+        if outcome.approvals:
+            typer.echo(f"recorded baseline for {len(outcome.approvals)} gate(s):")
+            for approval in outcome.approvals:
+                typer.echo(f"    {approval.gate_id}")
+        else:
+            typer.echo("recorded baseline for 0 gates (nothing new)")
+        if outcome.findings_baselined:
+            typer.echo(f"baselined {len(outcome.findings_baselined)} open finding(s)")
+
+
+# --- doctor ----------------------------------------------------------------------
+
+
+def _writable(path: Path) -> bool:
+    try:
+        path.mkdir(parents=True, exist_ok=True)
+        probe = path / ".chipgraph-doctor-write-test"
+        probe.write_text("ok", encoding="utf-8")
+        probe.unlink()
+    except OSError:
+        return False
+    return True
+
+
+def _first_word(cmd: object) -> str | None:
+    if isinstance(cmd, str):
+        parts = cmd.split()
+        return parts[0] if parts else None
+    if isinstance(cmd, list) and cmd:
+        return str(cmd[0])
+    return None
+
+
+_GUARD_MIN_PYTHON = (3, 9)
+
+
+def _guard_python() -> tuple[bool, str]:
+    """Whether the plugin's write guard can start: a `python3` >= 3.9 on PATH.
+
+    Claude Code runs the guard as `python3 guard.py`. Without it the hook cannot start and
+    Claude Code lets the tool call through, so the write guard would be off without any
+    warning (`submit` still rejects changes outside a task's outputs afterwards).
+    """
+    found = shutil.which("python3")
+    if found is None:
+        return False, "not found on PATH: the plugin's write guard cannot run"
+    try:
+        out = subprocess.run(
+            [found, "-c", "import sys; print('%d.%d' % sys.version_info[:2])"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+            check=True,
+        ).stdout.strip()
+        major, minor = (int(x) for x in out.split("."))
+    except (OSError, subprocess.SubprocessError, ValueError):
+        return False, f"{found} does not run: the plugin's write guard cannot run"
+    if (major, minor) < _GUARD_MIN_PYTHON:
+        return False, f"{found} is {out}; the write guard needs 3.9 or newer"
+    return True, f"{found} ({out})"
+
+
+@app.command()
+@_handle_errors
+def doctor(ctx: typer.Context) -> None:
+    """Report whether the environment is set up to run chipgraph."""
+    state: CliState = ctx.obj
+    lines: list[tuple[str, bool, str]] = []
+
+    py_ok = sys.version_info >= (3, 13)
+    lines.append(("python", py_ok, sys.version.split()[0]))
+
+    git_path = shutil.which("git")
+    lines.append(("git", git_path is not None, git_path or "not found on PATH"))
+
+    app_ctx: AppContext | None
+    try:
+        app_ctx = _load_ctx(state)
+    except (AppError, ConfigError) as exc:
+        app_ctx = None
+        lines.append(("profile", False, str(exc)))
+    else:
+        if app_ctx.profile is not None:
+            lines.append(("profile", True, str(app_ctx.root / ".chipgraph.yml")))
+        else:
+            lines.append(("profile", False, "no .chipgraph.yml found"))
+
+    runtime = app_ctx.profile.runtime if app_ctx is not None and app_ctx.profile else None
+    if runtime in (None, "claude-code"):
+        lines.append(("python3 for the write guard", *_guard_python()))
+
+    if app_ctx is not None and app_ctx.profile is not None:
+        state_dir = app_ctx.layout.state_dir
+        lines.append(("state dir writable", _writable(state_dir), str(state_dir)))
+        for check_id, cfg in sorted(app_ctx.profile.adapters.items()):
+            if cfg.use != "cmd":
+                continue
+            first = _first_word(cfg.model_dump().get("cmd"))
+            found = shutil.which(first) if first else None
+            detail = f"{first!r} -> {found}" if first else "no 'cmd' configured"
+            lines.append((f"tool for {check_id}", found is not None, detail))
+
+    ok = all(passed for _, passed, _ in lines)
+    if state.json_output:
+        typer.echo(json.dumps([{"check": n, "ok": p, "detail": d} for n, p, d in lines], indent=2))
+    else:
+        for name, passed, detail in lines:
+            mark = "ok" if passed else "MISSING"
+            typer.echo(f"{mark:7} {name}: {detail}")
+    if not ok:
+        raise typer.Exit(code=1)
+
+
+# --- findings / waive ---------------------------------------------------------------
+
+_FINDING_STATUS_CHOICES = ("open", "waived", "fixed", "all")
+
+
+def _finding_first_evidence(finding: Finding) -> str:
+    ev = finding.evidence[0]
+    if ev.file is not None:
+        return f"{ev.file}:{ev.line}" if ev.line is not None else ev.file
+    return f"model:{ev.model_key}"
+
+
+def _findings_with_effective_status(
+    app_ctx: AppContext, *, status: str, layer: int | None
+) -> list[Finding]:
+    """Every stored finding matching `layer`, with `.status` set to its *effective*
+    status (resolving waiver currency against the finding's current artifact hashes),
+    filtered by `status` unless it is `"all"`.
+    """
+    store = FindingStore(app_ctx.layout)
+    rows: list[Finding] = []
+    for finding in store.list(layer=layer):
+        waivers = app_ctx.review.approvals(waiver_gate_id(finding.id))
+        current_hashes = findings_app.finding_current_hashes(app_ctx.store, finding, waivers)
+        eff = effective_status(finding, waivers, current_hashes)
+        if status != "all" and eff != status:
+            continue
+        display = finding if eff == finding.status else finding.model_copy(update={"status": eff})
+        rows.append(display)
+    return rows
+
+
+@app.command("findings")
+@_handle_errors
+def findings_cmd(
+    ctx: typer.Context,
+    status: Annotated[
+        str, typer.Option("--status", help="open|waived|fixed|all (default: open).")
+    ] = "open",
+    layer: Annotated[
+        int | None, typer.Option("--layer", min=1, max=5, help="Only this DESIGN.md layer.")
+    ] = None,
+) -> None:
+    """List recorded findings, with their effective status (DESIGN.md 4.8)."""
+    state: CliState = ctx.obj
+    if status not in _FINDING_STATUS_CHOICES:
+        raise AppError(
+            f"--status must be one of {'|'.join(_FINDING_STATUS_CHOICES)}, got {status!r}"
+        )
+    app_ctx = _load_ctx(state)
+    rows = _findings_with_effective_status(app_ctx, status=status, layer=layer)
+
+    if state.json_output:
+        typer.echo(json.dumps([f.model_dump(mode="json") for f in rows], indent=2))
+        return
+    if not rows:
+        typer.echo("no findings")
+        return
+    for finding in rows:
+        typer.echo(
+            f"{finding.id}  L{finding.layer}  {finding.severity:9}{finding.source:16}"
+            f"{_finding_first_evidence(finding):40}{finding.status:7}{finding.claim}"
+        )
+
+
+@app.command("waive")
+@_handle_errors
+def waive_cmd(
+    ctx: typer.Context,
+    finding_id: Annotated[str, typer.Argument(help="A finding id, e.g. 'F-1a2b3c4d'.")],
+    reason: Annotated[str, typer.Option("--reason", help="Why this finding is waived.")],
+    by: Annotated[str | None, typer.Option("--by")] = None,
+    bind: Annotated[
+        list[str],
+        typer.Option(
+            "--bind",
+            help=(
+                "Also bind the waiver to this repo file (repeatable; may not exist yet). "
+                "Needed for a finding with no file; the waiver ends when a bound file "
+                "appears or changes."
+            ),
+        ),
+    ] = [],  # noqa: B006
+) -> None:
+    """Waive a finding, binding the waiver to its artifacts' current hashes."""
+    state: CliState = ctx.obj
+    app_ctx = _load_ctx(state)
+    store = FindingStore(app_ctx.layout)
+    finding = store.get_by_id(finding_id)
+    if finding is None:
+        typer.echo(f"no such finding: {finding_id!r}", err=True)
+        raise typer.Exit(code=2)
+
+    who = by or default_identity()
+    current_hashes = app_ctx.store.current_hashes(finding.artifacts)
+    current_hashes.update(findings_app.bound_hashes(app_ctx.store, bind))
+    try:
+        waived = findings_app.waive(
+            finding,
+            by=who,
+            reason=reason,
+            store=store,
+            review=app_ctx.review,
+            current_hashes=current_hashes,
+        )
+    except ValueError as exc:
+        raise AppError(str(exc)) from exc
+
+    if state.json_output:
+        typer.echo(waived.model_dump_json())
+    else:
+        typer.echo(f"waived {waived.id} by {who!r}: {reason}")
+
+
+# --- agents-md ----------------------------------------------------------------------
+
+
+@app.command("agents-md")
+@_handle_errors
+def agents_md_cmd(
+    ctx: typer.Context,
+    write: Annotated[
+        bool, typer.Option("--write", help="Write the file (only if its content changes).")
+    ] = False,
+    check_only: Annotated[
+        bool,
+        typer.Option(
+            "--check", help="Exit 1 if the file on disk is not what --write would write (CI)."
+        ),
+    ] = False,
+    path: Annotated[
+        Path,
+        typer.Option("--path", help="The file to manage, relative to the project root."),
+    ] = Path("AGENTS.md"),
+) -> None:
+    """Generate chipgraph's part of AGENTS.md from the profile and org rules (optional, no AI).
+
+    Only the text between `<!-- chipgraph:begin -->` and `<!-- chipgraph:end -->` is
+    chipgraph's; the rest of the file is the team's and is kept byte for byte. A file
+    without the markers gets the block appended. By default the full resulting file is
+    printed and nothing is written. Opening a PR is out of scope: review and commit the
+    file yourself.
+    """
+    from chipgraph.core.config import load as load_config
+    from chipgraph.packs.spec_core.gen.agents_md import AgentsMdError, agents_md_content
+
+    state: CliState = ctx.obj
+    if write and check_only:
+        typer.echo("--write and --check cannot be used together", err=True)
+        raise typer.Exit(code=2)
+    resolved = load_config(state.start, profile_path=state.profile_path)
+    if resolved is None:
+        raise AppError("no .chipgraph.yml: only read-only commands work; run `chipgraph init`")
+    root = find_repo_root(state.start)
+    target = path if path.is_absolute() else root / path
+
+    try:
+        existing = target.read_bytes().decode("utf-8") if target.is_file() else None
+        content = agents_md_content(existing, resolved, root)
+    except (AgentsMdError, OSError, UnicodeDecodeError) as exc:
+        typer.echo(f"{path}: {exc}", err=True)
+        raise typer.Exit(code=2) from exc
+
+    if check_only:
+        if content != existing:
+            typer.echo(f"{path} is out of date; run `chipgraph agents-md --write`", err=True)
+            raise typer.Exit(code=1)
+        typer.echo(f"{path} is up to date")
+    elif write:
+        if content == existing:
+            typer.echo(f"{path} is up to date")
+            return
+        try:
+            target.write_bytes(content.encode("utf-8"))
+        except OSError as exc:
+            typer.echo(f"{path}: {exc}", err=True)
+            raise typer.Exit(code=2) from exc
+        typer.echo(f"wrote {path}")
+    else:
+        typer.echo(content, nl=False)
+
+
+# --- ask ---------------------------------------------------------------------------
+
+
+@app.command("ask")
+@_handle_errors
+def ask_cmd(
+    ctx: typer.Context,
+    question: Annotated[str, typer.Argument(help="The question, in quotes.")],
+    limit: Annotated[
+        int, typer.Option("--limit", min=1, max=50, help="At most this many sources.")
+    ] = 12,
+    provider: Annotated[
+        str | None,
+        typer.Option("--provider", help="The models.providers entry to use (if several)."),
+    ] = None,
+) -> None:
+    """Answer a question from the Design Model and the project's documents, with citations.
+
+    Every citation is checked (an indexed `path:line` or a `model:<key>`); an answer that
+    cannot be verified is not shown. Uses the profile's `models.providers` (API runtime);
+    with none configured it prints the sources: in Claude Code, use `/chipgraph:ask`.
+    Exit 1 when the model's answer was rejected.
+    """
+    from chipgraph.packs.assist.ask import run_ask
+
+    state: CliState = ctx.obj
+    app_ctx = _load_ctx(state)
+    app_ctx.require_profile()
+    result = run_ask(app_ctx, question, limit=limit, provider_name=provider)
+
+    if state.json_output:
+        typer.echo(json.dumps(result.model_dump(mode="json"), indent=2))
+    elif result.status == "no_provider":
+        sources = result.context.sources
+        typer.echo(f"sources for: {question}" if sources else "no source matches the question")
+        for source in sources:
+            typer.echo(f"  {source.citation}  {source.text}")
+        typer.echo(
+            "no model provider is configured (models.providers); in Claude Code, run "
+            f'/chipgraph:ask "{question}" for a checked answer'
+        )
+    elif result.answer is not None:
+        typer.echo(result.answer.answer)
+        checks = {c.normalized: c for c in (result.check.citations if result.check else ())}
+        if result.answer.citations:
+            typer.echo("sources:")
+        for citation in result.answer.citations:
+            cited = checks.get(citation)
+            snippet = cited.text.splitlines()[0] if cited and cited.text else ""
+            typer.echo(f"  {citation}  {snippet}")
+        if result.status == "rejected" and result.check is not None:
+            typer.echo("the model's answer was rejected:", err=True)
+            for reason in result.check.reasons:
+                typer.echo(f"  {reason}", err=True)
+
+    if result.status == "rejected":
+        raise typer.Exit(code=1)
+
+
+# --- triage ------------------------------------------------------------------------
+
+
+@app.command("triage")
+@_handle_errors
+def triage_cmd(
+    ctx: typer.Context,
+    log: Annotated[
+        str, typer.Argument(help="The failing log file, or - to read it from stdin.")
+    ] = "-",
+    check: Annotated[
+        str | None, typer.Option("--check", help="The check id that produced the log.")
+    ] = None,
+    json_flag: Annotated[bool, typer.Option("--json", help="Print the report as JSON.")] = False,
+) -> None:
+    """Classify a failing lint/sim/check log as infra, rtl, tb or spec, and say what to do.
+
+    Deterministic rules answer first; otherwise decide() asks a model: the API runtime uses
+    `models.providers`; runtime claude-code queues the question for Claude Code (run
+    `/chipgraph:triage LOG` there). A model's label is advice and never blocks.
+    Exit 1 when no label was decided.
+    """
+    from chipgraph.packs.assist.triage import run_triage
+
+    state: CliState = ctx.obj
+    app_ctx = _load_ctx(state)
+    app_ctx.require_profile()
+    if log == "-":
+        text, source = sys.stdin.read(), None
+    else:
+        path = Path(log)
+        try:
+            text = path.read_text(encoding="utf-8", errors="replace")
+        except OSError as exc:
+            raise AppError(f"cannot read the log {log}: {exc}") from exc
+        source = log
+        resolved_log = path.resolve()
+        if resolved_log.is_relative_to(app_ctx.root.resolve()):
+            source = resolved_log.relative_to(app_ctx.root.resolve()).as_posix()
+    report = run_triage(app_ctx, text, source=source, check_id=check)
+
+    if json_flag or state.json_output:
+        typer.echo(json.dumps(report.model_dump(mode="json"), indent=2))
+    elif report.status == "decided":
+        how = f"rule {report.rule}" if report.backend == "rule" else f"{report.backend} model"
+        low = ", low confidence: advice only" if report.low_confidence else ""
+        typer.echo(f"label: {report.label} ({how}, confidence {report.confidence:.2f}{low})")
+        typer.echo(f"summary: {report.summary}")
+        typer.echo(f"suggestion: {report.suggestion}")
+        if report.evidence:
+            typer.echo("evidence:")
+            for item in report.evidence:
+                typer.echo(f"  {item}")
+    else:
+        typer.echo(f"summary: {report.summary}")
+        typer.echo(report.message, err=True)
+
+    if report.status != "decided":
+        raise typer.Exit(code=1)
+
+
+# --- eval --------------------------------------------------------------------------
+
+_EVAL_PACKAGE = "chipgraph_evals"
+
+
+def _evals_harness() -> object:
+    """`evals/harness/` of this chipgraph checkout, loaded as the package `chipgraph_evals`.
+
+    The evals are not part of the installed package; they are looked up next to the
+    source tree (an editable install), then upward from the current directory.
+    """
+    import importlib.util
+
+    if _EVAL_PACKAGE in sys.modules:
+        return sys.modules[_EVAL_PACKAGE]
+    checkout = Path(__file__).resolve().parents[3]
+    for root in (checkout, Path.cwd().resolve(), *Path.cwd().resolve().parents):
+        harness = root / "evals" / "harness"
+        if (harness / "__init__.py").is_file():
+            break
+    else:
+        raise AppError("chipgraph eval runs in a chipgraph checkout: evals/harness/ not found")
+    spec = importlib.util.spec_from_file_location(
+        _EVAL_PACKAGE, harness / "__init__.py", submodule_search_locations=[str(harness)]
+    )
+    assert spec is not None and spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[_EVAL_PACKAGE] = module
+    try:
+        spec.loader.exec_module(module)
+    except BaseException:
+        del sys.modules[_EVAL_PACKAGE]
+        raise
+    return module
+
+
+@app.command("eval")
+@_handle_errors
+def eval_cmd(
+    ctx: typer.Context,
+    suite: Annotated[
+        str,
+        typer.Argument(
+            help=(
+                "ask, triage, triage-holdout, triage-holdout2, review, review-holdout2, rtl or tb."
+            )
+        ),
+    ],
+    runtime: Annotated[
+        Literal["fake", "claude-code"],
+        typer.Option("--runtime", help="fake: scripted, no model (CI); claude-code: real."),
+    ] = "fake",
+    main_model: Annotated[
+        str, typer.Option("--main-model", help="claude-code: the main session's model.")
+    ] = "sonnet",
+    small_model: Annotated[
+        str, typer.Option("--small-model", help="claude-code triage: the small decider tier.")
+    ] = "haiku",
+    large_model: Annotated[
+        str,
+        typer.Option(
+            "--large-model",
+            help="claude-code: the large tier (triage decider, review critic, rtl/tb escalation).",
+        ),
+    ] = "opus",
+    budget_usd: Annotated[
+        float | None,
+        typer.Option(
+            "--budget-usd",
+            min=0.01,
+            help="claude-code: stop once the suite cost reaches this (default 3; rtl, tb: 10).",
+        ),
+    ] = None,
+    time_limit: Annotated[
+        int, typer.Option("--time-limit", min=1, help="claude-code: suite time limit, seconds.")
+    ] = 3600,
+    out: Annotated[
+        Path | None,
+        typer.Option("--out", help="Report directory (default: a new temporary directory)."),
+    ] = None,
+    only: Annotated[
+        str | None, typer.Option("--only", help="Only these ids, comma-separated.")
+    ] = None,
+) -> None:
+    """Run an eval suite (Inspect AI) and grade it with its deterministic grader.
+
+    Writes the Inspect log, answers.jsonl and summary.json/summary.md to --out. The fake
+    runtime calls no model. claude-code runs one headless `claude -p` per sample on a
+    tinysoc copy with the dev plugin, under --budget-usd and --time-limit; auth is
+    CLAUDE_CODE_OAUTH_TOKEN when set, else the logged-in Claude Code account.
+    Exit 0 pass (or no data yet), 1 fail, 2 error.
+    """
+    import tempfile
+    from typing import Any
+
+    try:
+        import inspect_ai  # noqa: F401
+    except ImportError as exc:
+        raise AppError(
+            "chipgraph eval needs Inspect AI: run `uv sync` (dev group) or `uv sync --extra evals`"
+        ) from exc
+    harness: Any = _evals_harness()
+    state: CliState = ctx.obj
+    out_dir = out if out is not None else Path(tempfile.mkdtemp(prefix=f"cg-eval-{suite}-"))
+    options = harness.EvalOptions(
+        runtime=runtime,
+        main_model=main_model,
+        small_model=small_model,
+        large_model=large_model,
+        budget_usd=budget_usd,
+        time_limit_s=time_limit,
+        only=tuple(i for i in (only or "").replace(",", " ").split() if i),
+    )
+    try:
+        result = harness.run_suite(
+            suite, out_dir, options, progress=lambda line: typer.echo(line, err=True)
+        )
+    except harness.EvalError as exc:
+        raise AppError(str(exc)) from exc
+    if state.json_output:
+        typer.echo(json.dumps(result.summary, indent=2))
+    else:
+        typer.echo((out_dir / "summary.md").read_text(encoding="utf-8").rstrip())
+        typer.echo(f"report: {out_dir}")
+    if result.exit_code:
+        raise typer.Exit(code=result.exit_code)
+
+
+# --- mcp ---------------------------------------------------------------------------
+
+
+@app.command("mcp")
+@_handle_errors
+def mcp_cmd(ctx: typer.Context) -> None:
+    """Start the MCP server over stdio, for Claude Code or another MCP client."""
+    from chipgraph.mcp import run_stdio
+
+    state: CliState = ctx.obj
+    asyncio.run(run_stdio(state.start, profile_path=state.profile_path))
+
+
+__all__ = ["app"]