chipgraph 0.1.0__py3-none-any.whl

chipgraph/app/baseline.py

@@ -0,0 +1,339 @@
+"""Wire `chipgraph baseline` to the graph, git, the review store and the finding store.
+
+The generic planning lives in `chipgraph.core.engine.baseline`; this module supplies the
+concrete facts it needs and applies the plan:
+
+- it builds the graph for every target, collects each gated instance's gate and the
+  file inputs it covers, and asks the `GateEvaluator` whether each gate is already
+  decided;
+- it answers `VcsFacts` (content hash, tracked/dirty, last commit) from the git working
+  tree and history;
+- on ``--confirm`` it records one `baseline` decision per undecided gate over its clean,
+  tracked artifacts (through `core.engine.gate.baseline`) and marks every open finding as
+  baselined, and it refuses to run on a branch other than the configured main branch.
+
+`baseline` runs after `ingest`; the spec files ingest reads are ordinary file artifacts
+here, gated by whatever rule consumes them.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from collections.abc import Iterable
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+
+from chipgraph.app.build import load_rules
+from chipgraph.app.context import AppContext
+from chipgraph.app.errors import AppError
+from chipgraph.app.findings import finding_current_hashes
+from chipgraph.core.contracts import Approval, ArtifactRef, Finding, RuleInstance
+from chipgraph.core.engine import gate as gate_mod
+from chipgraph.core.engine.baseline import (
+    BaselinePlan,
+    CommitInfo,
+    GateInput,
+    clean_refs_for_gate,
+    gate_inputs_from_instances,
+    plan_baseline,
+)
+from chipgraph.core.engine.graph import GraphError, build_graph
+from chipgraph.core.engine.scheduler import _format_gate
+from chipgraph.core.state.findings import FindingStore, effective_status, waiver_gate_id
+
+__all__ = [
+    "BaselineOutcome",
+    "WrongBranchError",
+    "baseline_gate_id",
+    "current_branch",
+    "main_branch",
+    "plan_project_baseline",
+    "run_baseline",
+]
+
+_DEFAULT_MAIN_BRANCH = "main"
+
+
+def baseline_gate_id(finding_id: str) -> str:
+    """The `Approval.gate_id` a finding's `baseline` decision is recorded under.
+
+    Distinct from the waiver gate id (`finding:<id>`), so a baseline decision never
+    reads as a waiver: `chipgraph findings` keeps listing the finding as open (recorded,
+    non-blocking), which is what a baseline of existing findings means (DESIGN.md 6.4).
+    """
+    return f"baseline:finding:{finding_id}"
+
+
+class WrongBranchError(AppError):
+    """Raised when `baseline` runs on a branch other than the configured main branch."""
+
+
+@dataclass(frozen=True, slots=True)
+class BaselineOutcome:
+    """What a `--confirm` run recorded: the decisions written and findings baselined."""
+
+    approvals: tuple[Approval, ...]
+    findings_baselined: tuple[str, ...]
+
+
+# --- git facts ----------------------------------------------------------------------
+
+
+def _git(root: Path, *args: str) -> subprocess.CompletedProcess[str]:
+    """Run a read-only git command under `root`, capturing output (never a shell)."""
+    return subprocess.run(
+        ["git", "-C", str(root), *args],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+
+def current_branch(root: Path) -> str | None:
+    """The current branch name, or `None` when detached / not a git repo."""
+    result = _git(root, "rev-parse", "--abbrev-ref", "HEAD")
+    if result.returncode != 0:
+        return None
+    name = result.stdout.strip()
+    return None if name in ("", "HEAD") else name
+
+
+def main_branch(root: Path) -> str:
+    """The configured main branch: `origin/HEAD`'s target, falling back to `main`.
+
+    Read from `git symbolic-ref refs/remotes/origin/HEAD` (e.g. `origin/main` -> `main`);
+    if there is no such ref, the default `main` is used (DESIGN.md 6.4).
+    """
+    result = _git(root, "symbolic-ref", "refs/remotes/origin/HEAD")
+    if result.returncode == 0:
+        ref = result.stdout.strip()
+        prefix = "refs/remotes/origin/"
+        if ref.startswith(prefix):
+            name = ref[len(prefix) :]
+            if name:
+                return name
+    return _DEFAULT_MAIN_BRANCH
+
+
+class _GitFacts:
+    """`VcsFacts` answered from a git working tree and history under `root`.
+
+    Tracked/dirty status and content hashes come from the working tree; `last_commit`
+    reads `git log`. Results are cached per path so a listing that touches an artifact
+    from several gates does not re-shell for it.
+    """
+
+    def __init__(self, ctx: AppContext) -> None:
+        self._ctx = ctx
+        self._root = ctx.root
+        self._sha: dict[str, str | None] = {}
+        self._tracked: dict[str, bool] = {}
+        self._dirty: dict[str, bool] = {}
+        self._commit: dict[str, CommitInfo | None] = {}
+        self._changed = self._collect_changed()
+
+    def _collect_changed(self) -> frozenset[str]:
+        result = _git(self._root, "status", "--porcelain=v1", "-z")
+        paths: set[str] = set()
+        for entry in result.stdout.split("\0"):
+            if len(entry) > 3:
+                paths.add(entry[3:])
+        return frozenset(paths)
+
+    def sha256(self, path: str) -> str | None:
+        if path not in self._sha:
+            ref = ArtifactRef(kind="other", path=path)
+            hashes = self._ctx.store.current_hashes((ref,))
+            self._sha[path] = hashes.get(f"{ref.repo}:{path}")
+        return self._sha[path]
+
+    def is_tracked(self, path: str) -> bool:
+        if path not in self._tracked:
+            result = _git(self._root, "ls-files", "--error-unmatch", "--", path)
+            self._tracked[path] = result.returncode == 0
+        return self._tracked[path]
+
+    def is_dirty(self, path: str) -> bool:
+        if path not in self._dirty:
+            # Untracked paths appear in `git status` too; only a *tracked* modified path
+            # is "dirty" here (an untracked one is reported by `is_tracked`).
+            self._dirty[path] = path in self._changed and self.is_tracked(path)
+        return self._dirty[path]
+
+    def last_commit(self, path: str) -> CommitInfo | None:
+        if path not in self._commit:
+            self._commit[path] = self._read_last_commit(path)
+        return self._commit[path]
+
+    def _read_last_commit(self, path: str) -> CommitInfo | None:
+        # %h short sha, %ad author date (short), %s subject, %P parents (to spot merges).
+        # %P is last so an empty parent list (a root commit) just yields a trailing empty
+        # field; parse with a fixed split count so that empty field is never lost.
+        result = _git(
+            self._root,
+            "log",
+            "-1",
+            "--date=short",
+            "--format=%h%x1f%ad%x1f%s%x1f%P",
+            "--",
+            path,
+        )
+        if result.returncode != 0:
+            return None
+        line = result.stdout.rstrip("\n")
+        if not line:
+            return None
+        parts = line.split("\x1f", 3)
+        if len(parts) < 3:
+            return None
+        short_sha, date, subject = parts[0], parts[1], parts[2]
+        parents = parts[3] if len(parts) > 3 else ""
+        is_merge = len(parents.split()) > 1
+        return CommitInfo(short_sha=short_sha, date=date, subject=subject, is_merge=is_merge)
+
+
+# --- planning -----------------------------------------------------------------------
+
+
+def _gated_instances(ctx: AppContext) -> list[tuple[str, RuleInstance, bool]]:
+    """Every gated instance across all targets: `(gate_id, instance, already_decided)`.
+
+    The graph is built once over `"*"` (all targets). A rule with a `gate` yields one
+    entry per instance, with the gate id formatted from the instance's params; whether
+    the gate is already decided is asked of the project's `GateEvaluator`.
+    """
+    rules = load_rules(ctx)
+    from chipgraph.app.build import _resolver_for
+
+    try:
+        graph = build_graph(rules, _resolver_for(ctx), repo=ctx.store.repo)
+    except GraphError as exc:
+        raise AppError(str(exc)) from exc
+
+    gated: list[tuple[str, RuleInstance, bool]] = []
+    seen: set[tuple[str, str]] = set()
+    for iid in sorted(graph.instances):
+        instance = graph.instances[iid]
+        rule = graph.rules[instance.rule_id]
+        if not rule.gate:
+            continue
+        gate_id = _format_gate(rule.gate, instance.params)
+        key = (gate_id, iid)
+        if key in seen:
+            continue
+        seen.add(key)
+        already = ctx.gates.status(gate_id, instance) != "waiting"
+        gated.append((gate_id, instance, already))
+    return gated
+
+
+def _refs_by_path(gated: Iterable[tuple[str, RuleInstance, bool]]) -> dict[str, ArtifactRef]:
+    """Map each gated instance's file-input path to its `ArtifactRef` (repo/label kept)."""
+    by_path: dict[str, ArtifactRef] = {}
+    for _gate_id, instance, _decided in gated:
+        for ref in instance.inputs:
+            if ref.path is not None and ref.path not in by_path:
+                by_path[ref.path] = ref
+    return by_path
+
+
+def _open_finding_count(ctx: AppContext) -> int:
+    return len(_open_findings(ctx))
+
+
+def _open_findings(ctx: AppContext) -> list[Finding]:
+    store = FindingStore(ctx.layout)
+    open_rows: list[Finding] = []
+    for finding in store.list():
+        waivers = ctx.review.approvals(waiver_gate_id(finding.id))
+        current_hashes = finding_current_hashes(ctx.store, finding, waivers)
+        if effective_status(finding, waivers, current_hashes) == "open":
+            open_rows.append(finding)
+    return open_rows
+
+
+def plan_project_baseline(ctx: AppContext) -> tuple[BaselinePlan, dict[str, ArtifactRef]]:
+    """Build the `BaselinePlan` for this project, plus a path -> `ArtifactRef` map.
+
+    The map lets `run_baseline` pin a decision to the exact refs (with repo and label)
+    a gate covers, not just their paths.
+    """
+    gated = _gated_instances(ctx)
+    facts = _GitFacts(ctx)
+    gate_inputs: list[GateInput] = gate_inputs_from_instances(gated)
+    plan = plan_baseline(gate_inputs, facts, open_findings=_open_finding_count(ctx))
+    return plan, _refs_by_path(gated)
+
+
+# --- confirming ---------------------------------------------------------------------
+
+
+def run_baseline(
+    ctx: AppContext,
+    plan: BaselinePlan,
+    refs_by_path: dict[str, ArtifactRef],
+    *,
+    by: str,
+    note: str = "",
+) -> BaselineOutcome:
+    """Record the plan: one `baseline` decision per undecided gate, mark findings baselined.
+
+    Idempotent: a gate that is already decided (skipped) records nothing, so running this
+    again after a first confirm writes nothing new. A gate with no clean, tracked artifact
+    is skipped too (there is nothing on the main branch to pin). Returns what was written.
+    """
+    approvals: list[Approval] = []
+    for gate in plan.gates:
+        if not gate.will_baseline:
+            continue
+        refs = clean_refs_for_gate(gate, refs_by_path)
+        if not refs:
+            continue
+        try:
+            approval = gate_mod.baseline(
+                ctx.review, ctx.store, gate.gate_id, refs, by=by, note=note
+            )
+        except gate_mod.GateError as exc:
+            raise AppError(str(exc)) from exc
+        approvals.append(approval)
+
+    baselined = _baseline_open_findings(ctx, by=by, note=note)
+    return BaselineOutcome(approvals=tuple(approvals), findings_baselined=tuple(baselined))
+
+
+def _baseline_open_findings(ctx: AppContext, *, by: str, note: str) -> list[str]:
+    """Record a `baseline` decision against every open finding, keyed by its id.
+
+    Findings never block a build, so "baselined" here means *recorded, non-blocking,
+    still listed*: a `baseline` `Approval` bound to the finding's current artifact hashes
+    is written through the review store, distinct from a `waive` (so `chipgraph findings`
+    still lists the finding as open). Idempotent per (finding, hashes): a finding whose
+    artifacts have a current baseline decision is not recorded again.
+    """
+    recorded: list[str] = []
+    now = datetime.now(UTC)
+    for finding in _open_findings(ctx):
+        gate_id = baseline_gate_id(finding.id)
+        hashes = ctx.store.current_hashes(finding.artifacts)
+        if not hashes:
+            # No artifact to pin (e.g. a whole-check finding); still count it as recorded
+            # via its detection-time hashes if it has any, else skip pinning.
+            hashes = dict(finding.artifact_hashes)
+        if not hashes:
+            continue
+        existing = ctx.review.approvals(gate_id)
+        if any(a.decision == "baseline" and a.is_current(hashes) for a in existing):
+            continue
+        ctx.review.record(
+            Approval(
+                gate_id=gate_id,
+                by=by,
+                at=now,
+                artifact_hashes=hashes,
+                decision="baseline",
+                note=note or "baselined: recorded, non-blocking",
+            )
+        )
+        recorded.append(finding.id)
+    return recorded

chipgraph/app/build.py

@@ -0,0 +1,332 @@
+"""Building a `Scheduler` for a target: load rules from the profile's packs, expand
+`foreach` over the profile's blocks, and wire up the executors, check runner and gate
+evaluator (DESIGN.md 3.3, 3.4).
+
+The graph also knows the packs' named targets (`targets/*.yml` in a pack, e.g.
+`rtl:<block>`; `chipgraph.core.engine.targets`), so a target may be one everywhere a rule
+selector may. With `review: {use: github}` the PR gates (`pr:<...>`) are read from the
+pull request's reviews (`GitHubGateChecker`); every other gate, and every gate with the
+`file` adapter, from the decision files (`chipgraph approve`).
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Callable, Iterable, Sequence
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+from chipgraph.adapters.review.github import GitHubGateChecker
+from chipgraph.adapters.runtime.claude_code import ClaudeCodeExecutor, ClaudeCodeRuntime
+from chipgraph.app.checks import ProfileCheckRunner
+from chipgraph.app.context import AppContext
+from chipgraph.app.errors import AppError
+from chipgraph.app.executors import HumanExecutor, RunExecutor
+from chipgraph.core.contracts import ArtifactRef, RuleInstance, RuleSpec
+from chipgraph.core.engine.agent_rule import AgentRuleExecutor
+from chipgraph.core.engine.graph import (
+    BuildGraph,
+    ForeachEntry,
+    ForeachResolver,
+    GraphError,
+    build_graph,
+)
+from chipgraph.core.engine.rules import RuleLoadError, load_pack_rules
+from chipgraph.core.engine.scheduler import AgentStub, Executor, GateChecker, Scheduler
+from chipgraph.core.engine.targets import TargetError, TargetRegistry, load_pack_targets
+from chipgraph.core.plugin_api.pack import Pack, discover_packs
+from chipgraph.core.plugin_api.registry import PluginError
+from chipgraph.core.runtime import TaskQueue
+from chipgraph.core.runtime.roles import RoleError, check_agent_rules, task_denied_reads
+from chipgraph.core.state.trace import Tracer
+
+PLAN_MODULES = "plan.modules"
+"""The `foreach` selector over the modules of every block's approved plan (M2-03)."""
+PLAN_BLOCK = "plan.block"
+"""The `foreach` selector over the blocks with an approved plan (M2-11a)."""
+PLAN_BLOCKS = "plan.blocks"
+"""The `foreach` selector over every block, after its approved plan's files (M2-11a)."""
+PLAN_SELECTORS = (PLAN_MODULES, PLAN_BLOCK, PLAN_BLOCKS)
+
+
+def builtin_packs_dir() -> Path | None:
+    """The directory of the packs shipped inside the `chipgraph.packs` package (D36).
+
+    Found through `importlib.resources`, so it is the same whether chipgraph runs from a
+    checkout or is installed from a wheel. `None` if the package is not on a real
+    filesystem (e.g. imported from a zip), since packs are loaded from directories.
+    """
+    root = resources.files("chipgraph.packs")
+    return root if isinstance(root, Path) and root.is_dir() else None
+
+
+def pack_search_paths(ctx: AppContext) -> list[Path]:
+    """The search paths packs are discovered from, in order (DESIGN.md 3.2, D36).
+
+    The project's `.chipgraph/packs/`, then the built-in packs, then each entry of
+    `$CHIPGRAPH_PACK_PATH`. Two packs with the same name anywhere on the path are an error.
+    """
+    return pack_search_paths_for(ctx.root)
+
+
+def pack_search_paths_for(root: Path) -> list[Path]:
+    """`pack_search_paths` for the project at `root`."""
+    paths = [root / ".chipgraph" / "packs"]
+    builtin = builtin_packs_dir()
+    if builtin is not None:
+        paths.append(builtin)
+    env_value = os.environ.get("CHIPGRAPH_PACK_PATH", "")
+    paths.extend(Path(p) for p in env_value.split(os.pathsep) if p)
+    return paths
+
+
+def load_rules(ctx: AppContext) -> list[RuleSpec]:
+    """Load every rule from the packs named in the profile's `packs`."""
+    return rules_for_packs(ctx.root, ctx.require_profile().profile.packs)
+
+
+def rules_for_packs(root: Path, packs: Iterable[str]) -> list[RuleSpec]:
+    """Load every rule of the packs named `packs`, searched for from the project at `root`."""
+    rules: list[RuleSpec] = []
+    for pack in _packs(root, packs):
+        try:
+            rules.extend(load_pack_rules(pack))
+        except RuleLoadError as exc:
+            raise AppError(str(exc)) from exc
+    return rules
+
+
+def _packs(root: Path, packs: Iterable[str]) -> list[Pack]:
+    search_paths = pack_search_paths_for(root)
+    try:
+        available: dict[str, Pack] = discover_packs(search_paths)
+    except PluginError as exc:
+        raise AppError(str(exc)) from exc
+    found: list[Pack] = []
+    for name in packs:
+        pack = available.get(name)
+        if pack is None:
+            searched = ", ".join(str(p) for p in search_paths)
+            raise AppError(f"pack {name!r} not found; searched: {searched}")
+        found.append(pack)
+    return found
+
+
+def targets_for_packs(root: Path, packs: Iterable[str]) -> TargetRegistry:
+    """The named targets of the packs named `packs` (`<pack>/targets/*.yml`)."""
+    try:
+        return TargetRegistry(
+            spec for pack in _packs(root, packs) for spec in load_pack_targets(pack)
+        )
+    except TargetError as exc:
+        raise AppError(str(exc)) from exc
+
+
+def load_targets(ctx: AppContext) -> TargetRegistry:
+    """The named targets of the profile's packs."""
+    return targets_for_packs(ctx.root, ctx.require_profile().profile.packs)
+
+
+def _uses_layout(rules: Iterable[RuleSpec]) -> bool:
+    return any(
+        "{layout." in text
+        for rule in rules
+        for text in (*rule.outputs, *(i.selector for i in rule.inputs))
+    )
+
+
+class _ProfileForeach:
+    """The project's `ForeachResolver`: `blocks`, and the selectors over approved plans.
+
+    `blocks` expands to one entry `{"block": b}` per key of `profile.blocks`, sorted,
+    with the block's layout directories as template values (`{layout.rtl}`,
+    `{layout.tb}`, `chipgraph.packs.digital_rtl.layout`) when a rule uses them. From the
+    `digital-rtl` pack: `plan.modules` expands to one entry per module of every block's
+    approved plan (each with the module's write set, its dependencies as ordering edges,
+    the approved plan and the style files as inputs), `plan.block` to one entry per block
+    with an approved plan and `plan.blocks` to one per block (both with the plan's files
+    and the testbench as inputs, when it is approved). Any other `foreach` expression
+    needs the Design Model, which arrives in M1.
+    """
+
+    def __init__(
+        self,
+        ctx: AppContext,
+        rules: Sequence[RuleSpec],
+        plans: Callable[[], Any] | None = None,
+    ) -> None:
+        self._ctx = ctx
+        self._blocks = sorted(ctx.require_profile().profile.blocks)
+        self._layout = _uses_layout(rules)
+        self._plans_factory = plans
+        self._plans: Any = None
+
+    def _vars(self, block: str) -> dict[str, str]:
+        if not self._layout:
+            return {}
+        from chipgraph.packs.digital_rtl.layout import LayoutError, layout_vars
+
+        try:
+            return layout_vars(self._ctx.require_profile(), block)
+        except LayoutError as exc:
+            raise AppError(str(exc)) from exc
+
+    def expand(self, expr: str) -> list[dict[str, str]]:
+        return [dict(entry.params) for entry in self.expand_entries(expr)]
+
+    def expand_entries(self, expr: str) -> list[ForeachEntry]:
+        if expr == "blocks":
+            return [
+                ForeachEntry(params={"block": block}, vars=self._vars(block))
+                for block in self._blocks
+            ]
+        if expr in PLAN_SELECTORS and self._plans_factory is not None:
+            if self._plans is None:  # once per graph, however many rules use it
+                self._plans = self._plans_factory()
+            if expr == PLAN_MODULES:
+                return list(self._plans.modules())
+            if expr == PLAN_BLOCK:
+                return list(self._plans.blocks_with_plan())
+            return list(self._plans.every_block())
+        raise AppError(f"foreach {expr!r} needs the Design Model (M1)")
+
+
+def _resolver_for(ctx: AppContext, rules: Iterable[RuleSpec] | None = None) -> ForeachResolver:
+    """The project's resolver for a graph of `rules` (default: the profile's packs' rules)."""
+    rules = load_rules(ctx) if rules is None else list(rules)
+    plans: Callable[[], Any] | None = None
+    if any(rule.foreach in PLAN_SELECTORS for rule in rules):
+        from chipgraph.packs.digital_rtl.plan.resolver import PlanExpansion
+
+        def _plans() -> PlanExpansion:
+            return PlanExpansion(ctx, rules)
+
+        plans = _plans
+    resolver: ForeachResolver = _ProfileForeach(ctx, rules, plans)
+    from chipgraph.packs.digital_rtl.wrapper.resolver import SELECTORS, WrapperForeach
+
+    if any(rule.foreach in SELECTORS for rule in rules):  # `wrappers` (M2-12)
+        resolver = WrapperForeach(resolver, ctx.require_profile().profile)
+    return resolver
+
+
+def project_graph(ctx: AppContext, rules: Sequence[RuleSpec] | None = None) -> BuildGraph:
+    """The project's build graph: the packs' rules, expanded, with the packs' targets."""
+    rules = load_rules(ctx) if rules is None else list(rules)
+    try:
+        return build_graph(
+            rules, _resolver_for(ctx, rules), repo=ctx.store.repo, targets=load_targets(ctx)
+        )
+    except GraphError as exc:
+        raise AppError(str(exc)) from exc
+
+
+def graph_artifacts(graph: BuildGraph) -> list[ArtifactRef]:
+    """Every input and output of every instance of `graph`."""
+    return [ref for inst in graph.instances.values() for ref in (*inst.inputs, *inst.outputs)]
+
+
+def denied_reads_for(
+    ctx: AppContext, graph: BuildGraph | None, role: str | None, keep: Iterable[str] = ()
+) -> tuple[str, ...]:
+    """What a task of `role` must not read in this project (`task_denied_reads`).
+
+    The one computation both runtimes use: the in-process loop filters the redo text by
+    it, runtime `claude-code` sets it on the task for the guard and `submit`.
+    """
+    return task_denied_reads(
+        role,
+        artifacts=graph_artifacts(graph) if graph is not None else (),
+        profile=ctx.require_profile().profile,
+        keep=keep,
+    )
+
+
+def agent_executor(ctx: AppContext, graph: BuildGraph | None = None) -> Executor:
+    """The executor for `kind: agent` rules, chosen by the profile's `runtime` (D35).
+
+    `claude-code` queues each agent task for the user's Claude Code session (the plugin
+    command runs it and hands it back over MCP). Any other runtime runs in-process: when
+    an `AgentRuntime` plugin is registered under the profile's runtime name, its agent
+    rules run in the engine's loop (`AgentRuleExecutor`: write, check at once, triage,
+    retry within the budget, DESIGN.md 5.2). No such plugin ships yet (the API runtimes
+    arrive later), so without one agent rules fail with the scheduler's `AgentStub`.
+    """
+    profile = ctx.require_profile().profile
+    if profile.runtime == "claude-code":
+        return ClaudeCodeExecutor(ClaudeCodeRuntime(TaskQueue(ctx.layout), ctx.store))
+    if profile.runtime in ctx.registry.names("runtime"):
+        runtime = ctx.registry.get("runtime", profile.runtime)
+
+        def denied(rule: RuleSpec, instance: RuleInstance) -> tuple[str, ...]:
+            keep = [ref.path for ref in instance.outputs if ref.path is not None]
+            return denied_reads_for(ctx, graph, rule.role, keep)
+
+        return AgentRuleExecutor(runtime, store=ctx.store, layout=ctx.layout, denied_reads=denied)
+    return AgentStub()
+
+
+def gate_checker(ctx: AppContext) -> GateChecker:
+    """The gates of this project: PR gates from GitHub reviews with `review: github`.
+
+    With `review: {use: github}` a gate whose id starts with `pr:` is the pull request's
+    review (`GitHubGateChecker`, pinned to the PR's head commit); any other gate, and
+    every gate otherwise, is the decision files' (`GateEvaluator`, `chipgraph approve`).
+    """
+    if ctx.pr_review is not None:
+        return GitHubGateChecker(ctx.pr_review, fallback=ctx.gates)
+    return ctx.gates
+
+
+def make_scheduler(
+    ctx: AppContext, target: str, *, concurrency: int = 4, tracer: Tracer | None = None
+) -> Scheduler:
+    """Build a `Scheduler` ready to run/resume `target` for this project."""
+    graph = project_graph(ctx)
+    try:
+        graph.select(target)
+    except GraphError as exc:
+        raise AppError(str(exc)) from exc
+    try:  # every agent rule must fit its role's tool table (DESIGN.md 5.1)
+        check_agent_rules(graph.rules, graph.instances.values())
+    except RoleError as exc:
+        raise AppError(str(exc)) from exc
+
+    run_executor = RunExecutor(ctx)
+    executors = {
+        "gen": run_executor,
+        "import": run_executor,
+        "human": HumanExecutor(ctx),
+        "agent": agent_executor(ctx, graph),
+    }
+    return Scheduler(
+        graph,
+        layout=ctx.layout,
+        store=ctx.store,
+        executors=executors,  # type: ignore[arg-type]
+        checks=ProfileCheckRunner(ctx),
+        gates=gate_checker(ctx),
+        concurrency=concurrency,
+        tracer=tracer,
+    )
+
+
+__all__ = [
+    "PLAN_BLOCK",
+    "PLAN_BLOCKS",
+    "PLAN_MODULES",
+    "PLAN_SELECTORS",
+    "agent_executor",
+    "denied_reads_for",
+    "gate_checker",
+    "graph_artifacts",
+    "load_rules",
+    "load_targets",
+    "make_scheduler",
+    "pack_search_paths",
+    "pack_search_paths_for",
+    "project_graph",
+    "rules_for_packs",
+    "targets_for_packs",
+]