From 472d9067879ff91bac38ecc34811a95d7be75aaa Mon Sep 17 00:00:00 2001
From: Anthony Volk <14987227+anth-volk@users.noreply.github.com>
Date: Mon, 12 Oct 2026 23:37:57 +0400
Subject: [PATCH 1/5] Check agent adapters and CI scripts in the rules tool

Sync scripts/rules with policyengine-api. The rules-registry guard now
verifies that agent adapters ([agents]) only point to AGENTS.md, and a new
ci-scripts quality guard ([ci_scripts]) fails on run: blocks longer than one
logical line, workflow scripts that no test runs, and shellcheck findings,
each ratcheted against a baseline that may only shrink.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 scripts/rules/adapters.py                     |  60 +++++
 scripts/rules/ci_scripts.py                   | 215 ++++++++++++++++++
 scripts/rules/cli.py                          |  23 +-
 scripts/rules/guard.py                        |   3 +
 scripts/rules/load.py                         |  60 ++++-
 scripts/rules/model.py                        |  23 ++
 .../tests/fixtures/adapters/bad_CLAUDE.md     |   5 +
 .../tests/fixtures/adapters/good_CLAUDE.md    |   3 +
 .../multiline_bad/.github/workflows/ci.yml    |  10 +
 .../multiline_good/.github/workflows/ci.yml   |  12 +
 .../ci_scripts/shellcheck/bad_script.sh       |   7 +
 .../ci_scripts/shellcheck/good_script.sh      |   7 +
 .../untested_bad/.github/scripts/deploy.sh    |   5 +
 .../untested_bad/.github/workflows/ci.yml     |   8 +
 .../untested_good/.github/scripts/deploy.sh   |   5 +
 .../untested_good/.github/workflows/ci.yml    |   8 +
 .../untested_good/tests/test_deploy.py        |   3 +
 scripts/rules/tests/test_adapters.py          |  58 +++++
 scripts/rules/tests/test_ci_scripts.py        | 178 +++++++++++++++
 scripts/rules/validate.py                     |  28 +++
 scripts/rules/workflows.py                    |  76 ++++++-
 scripts/run_quality_guards.py                 |   6 +-
 22 files changed, 798 insertions(+), 5 deletions(-)
 create mode 100644 scripts/rules/adapters.py
 create mode 100644 scripts/rules/ci_scripts.py
 create mode 100644 scripts/rules/tests/fixtures/adapters/bad_CLAUDE.md
 create mode 100644 scripts/rules/tests/fixtures/adapters/good_CLAUDE.md
 create mode 100644 scripts/rules/tests/fixtures/ci_scripts/multiline_bad/.github/workflows/ci.yml
 create mode 100644 scripts/rules/tests/fixtures/ci_scripts/multiline_good/.github/workflows/ci.yml
 create mode 100644 scripts/rules/tests/fixtures/ci_scripts/shellcheck/bad_script.sh
 create mode 100644 scripts/rules/tests/fixtures/ci_scripts/shellcheck/good_script.sh
 create mode 100644 scripts/rules/tests/fixtures/ci_scripts/untested_bad/.github/scripts/deploy.sh
 create mode 100644 scripts/rules/tests/fixtures/ci_scripts/untested_bad/.github/workflows/ci.yml
 create mode 100644 scripts/rules/tests/fixtures/ci_scripts/untested_good/.github/scripts/deploy.sh
 create mode 100644 scripts/rules/tests/fixtures/ci_scripts/untested_good/.github/workflows/ci.yml
 create mode 100644 scripts/rules/tests/fixtures/ci_scripts/untested_good/tests/test_deploy.py
 create mode 100644 scripts/rules/tests/test_adapters.py
 create mode 100644 scripts/rules/tests/test_ci_scripts.py

diff --git a/scripts/rules/adapters.py b/scripts/rules/adapters.py
new file mode 100644
index 000000000..b22bd112a
--- /dev/null
+++ b/scripts/rules/adapters.py
@@ -0,0 +1,60 @@
+"""Check that per-tool agent instruction files stay thin pointers.
+
+``AGENTS.md`` is the one source of agent instructions: it lists the skills and
+carries the generated Rules block. Tool adapters such as ``CLAUDE.md`` and
+``.github/copilot-instructions.md`` only point to it. When an adapter starts
+listing skills or rules itself, the copies drift apart, so this rejects it.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from scripts.rules.model import Agents, Violation
+from scripts.rules.render import BEGIN
+
+_DOC_REFERENCE = re.compile(r"[\w./-]+\.md\b")
+
+
+def check_adapters(agents: Agents, root: Path) -> list[Violation]:
+    violations = []
+    instructions = Path(agents.instructions).name
+    for adapter in agents.adapters:
+        path = root / adapter
+        if not path.is_file():
+            continue
+        text = path.read_text()
+
+        def v(message: str, fix: str) -> None:
+            violations.append(Violation(None, "adapters", f"{adapter} {message}", fix))
+
+        if instructions not in text:
+            v(
+                f"does not point to {instructions}",
+                f"say that the guidance lives in {instructions}",
+            )
+        others = sorted(
+            {
+                ref
+                for ref in _DOC_REFERENCE.findall(text)
+                if Path(ref).name != instructions
+            }
+        )
+        if others:
+            v(
+                f"references other docs ({', '.join(others)})",
+                f"list skills and rules in {instructions} only; keep {adapter} a pointer",
+            )
+        if BEGIN in text:
+            v(
+                "contains the generated rules block",
+                f"the block belongs in {instructions} only",
+            )
+        lines = sum(1 for line in text.splitlines() if line.strip())
+        if lines > agents.max_adapter_lines:
+            v(
+                f"has {lines} non-empty lines (limit {agents.max_adapter_lines})",
+                f"move the guidance into {instructions} or a skill",
+            )
+    return violations
diff --git a/scripts/rules/ci_scripts.py b/scripts/rules/ci_scripts.py
new file mode 100644
index 000000000..e21391ac6
--- /dev/null
+++ b/scripts/rules/ci_scripts.py
@@ -0,0 +1,215 @@
+"""The ci-scripts quality guard: workflow logic lives in tested shell scripts.
+
+Three checks, each ratcheted against a baseline file listed in ``[ci_scripts]``:
+
+1. A workflow ``run:`` block holds at most one logical line of code.
+2. Every shell script a workflow calls is referenced by at least one test.
+3. Every shell script in the scripts directory passes ``shellcheck``.
+
+Anything found that isn't in the baseline fails, and so does a baseline entry
+that no longer applies, so baselines only shrink.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from scripts.rules.load import load_registry
+from scripts.rules.model import CiScripts, Registry, Violation
+from scripts.rules.resolve import clear_caches, workflow_jobs
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+SEPARATOR = " :: "
+
+
+@dataclass
+class Findings:
+    multiline: set[str] = field(default_factory=set)
+    untested: set[str] = field(default_factory=set)
+    shellcheck: set[str] | None = None  # None when shellcheck could not run
+    notes: list[str] = field(default_factory=list)
+
+
+def multiline_runs(config: CiScripts, root: Path) -> set[str]:
+    """``workflow :: job :: step`` for every run: block over one logical line."""
+    found = set()
+    for workflow in sorted(root.glob(config.workflows)):
+        relative = workflow.relative_to(root).as_posix()
+        for job in workflow_jobs(workflow)[0].values():
+            for block in job.run_blocks:
+                if block.code_lines > 1:
+                    found.add(SEPARATOR.join((relative, job.id, block.step)))
+    return found
+
+
+def called_scripts(config: CiScripts, root: Path) -> set[str]:
+    """Shell scripts in the scripts directory that a workflow calls."""
+    pattern = re.compile(re.escape(config.scripts_dir.rstrip("/")) + r"/[\w.-]+\.sh")
+    called = set()
+    for workflow in root.glob(config.workflows):
+        for job in workflow_jobs(workflow)[0].values():
+            called.update(pattern.findall(job.run_text))
+    return {path for path in called if (root / path).is_file()}
+
+
+def untested_scripts(config: CiScripts, root: Path) -> set[str]:
+    """Called scripts whose file name appears in no test file."""
+    tests = [
+        path.read_text(errors="replace")
+        for pattern in config.test_globs
+        for path in root.glob(pattern)
+        if path.is_file() and ".venv" not in path.parts
+    ]
+    return {
+        script
+        for script in called_scripts(config, root)
+        if not any(Path(script).name in text for text in tests)
+    }
+
+
+def shellcheck_failures(config: CiScripts, root: Path) -> set[str] | None:
+    """Scripts with any shellcheck finding, or None if shellcheck isn't installed."""
+    shellcheck = shutil.which("shellcheck")
+    if shellcheck is None:
+        return None
+    scripts = sorted(
+        path.relative_to(root).as_posix()
+        for path in (root / config.scripts_dir).glob("*.sh")
+    )
+    if not scripts:
+        return set()
+    result = subprocess.run(
+        [shellcheck, "--format=gcc", *scripts],
+        cwd=root,
+        capture_output=True,
+        text=True,
+    )
+    return {line.split(":", 1)[0] for line in result.stdout.splitlines() if ":" in line}
+
+
+def find(config: CiScripts, root: Path) -> Findings:
+    clear_caches()
+    findings = Findings(
+        multiline=multiline_runs(config, root),
+        untested=untested_scripts(config, root),
+        shellcheck=shellcheck_failures(config, root),
+    )
+    if findings.shellcheck is None:
+        findings.notes.append(
+            "shellcheck is not installed; the shellcheck check was skipped"
+        )
+    return findings
+
+
+def _baseline(root: Path, path: str) -> set[str]:
+    file = root / path
+    if not file.is_file():
+        return set()
+    return {
+        line.strip()
+        for line in file.read_text().splitlines()
+        if line.strip() and not line.lstrip().startswith("#")
+    }
+
+
+def _rule_for(registry: Registry, baseline: str) -> str | None:
+    for rule in registry.rules:
+        if rule.baseline is not None and rule.baseline.file == baseline:
+            return rule.id
+    return None
+
+
+def compare(registry: Registry, findings: Findings, root: Path) -> list[Violation]:
+    config = registry.ci_scripts
+    assert config is not None
+    checks = (
+        (
+            "multi-line run: block",
+            findings.multiline,
+            config.multiline_baseline,
+            "move the commands into a tested script under "
+            f"{config.scripts_dir} and call it from a single-line run:",
+        ),
+        (
+            "untested workflow script",
+            findings.untested,
+            config.untested_baseline,
+            "add a test that runs the script (see docs/engineering/skills/ci-workflows.md)",
+        ),
+        (
+            "shellcheck finding in",
+            findings.shellcheck,
+            config.shellcheck_baseline,
+            "fix what `shellcheck <script>` reports",
+        ),
+    )
+    violations = []
+    for label, found, baseline_path, fix in checks:
+        if found is None:
+            continue
+        rule_id = _rule_for(registry, baseline_path)
+        baseline = _baseline(root, baseline_path)
+        for entry in sorted(found - baseline):
+            violations.append(Violation(rule_id, "ci-scripts", f"{label} {entry}", fix))
+        for entry in sorted(baseline - found):
+            violations.append(
+                Violation(
+                    rule_id,
+                    "ci-scripts",
+                    f"baseline entry no longer applies: {entry}",
+                    f"remove it from {baseline_path} and lower the rule's baseline count",
+                )
+            )
+    return violations
+
+
+def write_baselines(registry: Registry, findings: Findings, root: Path) -> None:
+    """Record today's findings as the baselines (used once, when adopting the rule)."""
+    config = registry.ci_scripts
+    assert config is not None
+    for found, path in (
+        (findings.multiline, config.multiline_baseline),
+        (findings.untested, config.untested_baseline),
+        (findings.shellcheck, config.shellcheck_baseline),
+    ):
+        if found is None:
+            continue
+        lines = [
+            "# Tolerated existing violations. This list may only shrink.",
+            *sorted(found),
+        ]
+        (root / path).parent.mkdir(parents=True, exist_ok=True)
+        (root / path).write_text("\n".join(lines) + "\n")
+
+
+def run_check(root: Path = REPO_ROOT) -> tuple[list[Violation], list[str]]:
+    registry, violations = load_registry(root)
+    if registry is None or registry.ci_scripts is None:
+        return violations, [
+            "no [ci_scripts] table in rules/registry.toml; nothing to check"
+        ]
+    findings = find(registry.ci_scripts, root)
+    violations = compare(registry, findings, root)
+    if findings.shellcheck is None and os.environ.get("GITHUB_ACTIONS"):
+        violations.append(
+            Violation(
+                _rule_for(registry, registry.ci_scripts.shellcheck_baseline),
+                "ci-scripts",
+                "shellcheck is not installed in this CI job",
+                "install it in the job (pip install shellcheck-py==<version>)",
+            )
+        )
+    return violations, findings.notes
+
+
+def check() -> list[str]:
+    """Adapter for scripts/run_quality_guards.py."""
+    violations, notes = run_check(REPO_ROOT)
+    for note in notes:
+        print(f"note: {note}")
+    return [str(violation) for violation in violations]
diff --git a/scripts/rules/cli.py b/scripts/rules/cli.py
index e5fd94fda..9322bb086 100644
--- a/scripts/rules/cli.py
+++ b/scripts/rules/cli.py
@@ -6,6 +6,7 @@
 from datetime import date
 from pathlib import Path
 
+from scripts.rules import ci_scripts
 from scripts.rules.guard import REPO_ROOT, run_guard
 from scripts.rules.load import load_registry
 from scripts.rules.render import write_outputs
@@ -26,15 +27,35 @@ def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(
         prog="python -m scripts.rules", description=__doc__
     )
-    parser.add_argument("command", choices=["validate", "render", "guard"])
+    parser.add_argument(
+        "command", choices=["validate", "render", "guard", "ci-scripts"]
+    )
     parser.add_argument("--root", type=Path, default=REPO_ROOT, help="repository root")
     parser.add_argument(
         "--base-ref",
         help="git ref to compare baselines against (default: origin/$GITHUB_BASE_REF)",
     )
+    parser.add_argument(
+        "--write-baselines",
+        action="store_true",
+        help="ci-scripts only: record today's findings as the baselines (when adopting the rule)",
+    )
     args = parser.parse_args(argv)
     root = args.root.resolve()
 
+    if args.command == "ci-scripts":
+        if args.write_baselines:
+            registry, violations = load_registry(root)
+            if registry is None or registry.ci_scripts is None:
+                return _print(violations or ["no [ci_scripts] table"])
+            ci_scripts.write_baselines(
+                registry, ci_scripts.find(registry.ci_scripts, root), root
+            )
+            print("wrote ci_scripts baselines; update the rules' baseline counts")
+            return 0
+        violations, notes = ci_scripts.run_check(root)
+        return _print(violations, notes)
+
     if args.command == "guard":
         result = run_guard(root, base_ref=args.base_ref)
         return _print(result.violations, result.notes)
diff --git a/scripts/rules/guard.py b/scripts/rules/guard.py
index f6c703e2c..42d4b6a37 100644
--- a/scripts/rules/guard.py
+++ b/scripts/rules/guard.py
@@ -7,6 +7,7 @@
 from datetime import date
 from pathlib import Path
 
+from scripts.rules.adapters import check_adapters
 from scripts.rules.baseline import (
     BaseUnavailable,
     check_baselines,
@@ -87,6 +88,8 @@ def run_guard(
         result.violations += resolve_ci(rule, root)
         result.violations += resolve_proof_ci(rule, root)
     result.violations += discover_hidden(registry, root)
+    if registry.agents is not None:
+        result.violations += check_adapters(registry.agents, root)
     result.violations += _stale_outputs(registry, root)
 
     ref = base_ref or default_base_ref()
diff --git a/scripts/rules/load.py b/scripts/rules/load.py
index 10b6faa60..14c588942 100644
--- a/scripts/rules/load.py
+++ b/scripts/rules/load.py
@@ -12,9 +12,11 @@
 from typing import Any
 
 from scripts.rules.model import (
+    Agents,
     Baseline,
     Category,
     CiRef,
+    CiScripts,
     Discovery,
     Enforcer,
     Ignored,
@@ -30,7 +32,25 @@
 
 REGISTRY_PATH = Path("rules/registry.toml")
 
-_TOP_KEYS = {"schema_version", "repo", "tool_version", "category", "discovery", "rule"}
+_TOP_KEYS = {
+    "schema_version",
+    "repo",
+    "tool_version",
+    "category",
+    "discovery",
+    "rule",
+    "agents",
+    "ci_scripts",
+}
+_AGENTS_KEYS = {"instructions", "adapters", "max_adapter_lines"}
+_CI_SCRIPTS_KEYS = {
+    "workflows",
+    "scripts_dir",
+    "test_globs",
+    "multiline_baseline",
+    "untested_baseline",
+    "shellcheck_baseline",
+}
 _RULE_KEYS = {
     "id",
     "category",
@@ -170,6 +190,42 @@ def _discovery(c: _Collector, raw: Any) -> Discovery:
     )
 
 
+def _agents(c: _Collector, raw: Any) -> Agents | None:
+    if raw is None:
+        return None
+    if not isinstance(raw, dict):
+        c.add(None, "agents must be a table", "write [agents]")
+        return None
+    c.unknown_keys(None, raw, _AGENTS_KEYS, "agents")
+    max_lines = raw.get("max_adapter_lines", 20)
+    if not isinstance(max_lines, int) or max_lines < 1:
+        c.add(None, "agents.max_adapter_lines must be a positive integer", "fix it")
+        max_lines = 20
+    return Agents(
+        instructions=c.string(None, raw, "instructions", "agents"),
+        adapters=c.string_list(None, raw, "adapters", "agents"),
+        max_adapter_lines=max_lines,
+    )
+
+
+def _ci_scripts(c: _Collector, raw: Any) -> CiScripts | None:
+    if raw is None:
+        return None
+    if not isinstance(raw, dict):
+        c.add(None, "ci_scripts must be a table", "write [ci_scripts]")
+        return None
+    c.unknown_keys(None, raw, _CI_SCRIPTS_KEYS, "ci_scripts")
+    where = "ci_scripts"
+    return CiScripts(
+        workflows=c.string(None, raw, "workflows", where),
+        scripts_dir=c.string(None, raw, "scripts_dir", where),
+        test_globs=c.string_list(None, raw, "test_globs", where),
+        multiline_baseline=c.string(None, raw, "multiline_baseline", where),
+        untested_baseline=c.string(None, raw, "untested_baseline", where),
+        shellcheck_baseline=c.string(None, raw, "shellcheck_baseline", where),
+    )
+
+
 def _rule(c: _Collector, raw: Any, index: int) -> Rule | None:
     if not isinstance(raw, dict):
         c.add(None, f"rule #{index + 1} must be a table", "write [[rule]]")
@@ -323,6 +379,8 @@ def parse(raw: dict[str, Any]) -> tuple[Registry | None, list[Violation]]:
         categories=tuple(categories),
         discovery=_discovery(c, raw.get("discovery")),
         rules=tuple(rule for rule in rules if rule is not None),
+        agents=_agents(c, raw.get("agents")),
+        ci_scripts=_ci_scripts(c, raw.get("ci_scripts")),
     )
     return registry, c.violations
 
diff --git a/scripts/rules/model.py b/scripts/rules/model.py
index 38247b9d4..eceec446d 100644
--- a/scripts/rules/model.py
+++ b/scripts/rules/model.py
@@ -72,6 +72,27 @@ class Discovery:
     ignore_tests: tuple[Ignored, ...] = ()
 
 
+@dataclass(frozen=True)
+class Agents:
+    """Agent instruction files: one source, plus thin per-tool adapters."""
+
+    instructions: str
+    adapters: tuple[str, ...]
+    max_adapter_lines: int = 20
+
+
+@dataclass(frozen=True)
+class CiScripts:
+    """Where workflow scripts live, where their tests are, and their baselines."""
+
+    workflows: str
+    scripts_dir: str
+    test_globs: tuple[str, ...]
+    multiline_baseline: str
+    untested_baseline: str
+    shellcheck_baseline: str
+
+
 @dataclass(frozen=True)
 class Enforcer:
     kind: Kind
@@ -184,6 +205,8 @@ class Registry:
     categories: tuple[Category, ...]
     discovery: Discovery
     rules: tuple[Rule, ...]
+    agents: Agents | None = None
+    ci_scripts: CiScripts | None = None
 
     def rule(self, rule_id: str) -> Rule | None:
         for rule in self.rules:
diff --git a/scripts/rules/tests/fixtures/adapters/bad_CLAUDE.md b/scripts/rules/tests/fixtures/adapters/bad_CLAUDE.md
new file mode 100644
index 000000000..8b7c0f9c0
--- /dev/null
+++ b/scripts/rules/tests/fixtures/adapters/bad_CLAUDE.md
@@ -0,0 +1,5 @@
+# Claude Instructions
+
+Guidance lives in `AGENTS.md`.
+
+When changing tests, read `docs/engineering/skills/testing.md`.
diff --git a/scripts/rules/tests/fixtures/adapters/good_CLAUDE.md b/scripts/rules/tests/fixtures/adapters/good_CLAUDE.md
new file mode 100644
index 000000000..6108d4ea9
--- /dev/null
+++ b/scripts/rules/tests/fixtures/adapters/good_CLAUDE.md
@@ -0,0 +1,3 @@
+# Claude Instructions
+
+Repository-wide guidance for AI agents lives in `AGENTS.md`. Read it first.
diff --git a/scripts/rules/tests/fixtures/ci_scripts/multiline_bad/.github/workflows/ci.yml b/scripts/rules/tests/fixtures/ci_scripts/multiline_bad/.github/workflows/ci.yml
new file mode 100644
index 000000000..6d8795076
--- /dev/null
+++ b/scripts/rules/tests/fixtures/ci_scripts/multiline_bad/.github/workflows/ci.yml
@@ -0,0 +1,10 @@
+name: CI
+on: pull_request
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Build
+        run: |
+          make deps
+          make build
diff --git a/scripts/rules/tests/fixtures/ci_scripts/multiline_good/.github/workflows/ci.yml b/scripts/rules/tests/fixtures/ci_scripts/multiline_good/.github/workflows/ci.yml
new file mode 100644
index 000000000..0ac8ccd7f
--- /dev/null
+++ b/scripts/rules/tests/fixtures/ci_scripts/multiline_good/.github/workflows/ci.yml
@@ -0,0 +1,12 @@
+name: CI
+on: pull_request
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Build
+        run: bash .github/scripts/build.sh
+      - name: Long single command
+        run: >-
+          python -m pytest tests/unit
+          tests/contract -q
diff --git a/scripts/rules/tests/fixtures/ci_scripts/shellcheck/bad_script.sh b/scripts/rules/tests/fixtures/ci_scripts/shellcheck/bad_script.sh
new file mode 100644
index 000000000..d4e9fc633
--- /dev/null
+++ b/scripts/rules/tests/fixtures/ci_scripts/shellcheck/bad_script.sh
@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# Proof fixture: an unquoted variable (SC2086). shellcheck must reject it.
+
+set -euo pipefail
+
+target=$1
+rm -rf $target/build
diff --git a/scripts/rules/tests/fixtures/ci_scripts/shellcheck/good_script.sh b/scripts/rules/tests/fixtures/ci_scripts/shellcheck/good_script.sh
new file mode 100644
index 000000000..b2499e8e0
--- /dev/null
+++ b/scripts/rules/tests/fixtures/ci_scripts/shellcheck/good_script.sh
@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# Proof fixture: the same script, quoted. shellcheck must accept it.
+
+set -euo pipefail
+
+target="${1:?target directory is required}"
+rm -rf "${target}/build"
diff --git a/scripts/rules/tests/fixtures/ci_scripts/untested_bad/.github/scripts/deploy.sh b/scripts/rules/tests/fixtures/ci_scripts/untested_bad/.github/scripts/deploy.sh
new file mode 100644
index 000000000..0eedfc322
--- /dev/null
+++ b/scripts/rules/tests/fixtures/ci_scripts/untested_bad/.github/scripts/deploy.sh
@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+echo "deploying"
diff --git a/scripts/rules/tests/fixtures/ci_scripts/untested_bad/.github/workflows/ci.yml b/scripts/rules/tests/fixtures/ci_scripts/untested_bad/.github/workflows/ci.yml
new file mode 100644
index 000000000..a83661ae6
--- /dev/null
+++ b/scripts/rules/tests/fixtures/ci_scripts/untested_bad/.github/workflows/ci.yml
@@ -0,0 +1,8 @@
+name: CI
+on: push
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy
+        run: bash .github/scripts/deploy.sh
diff --git a/scripts/rules/tests/fixtures/ci_scripts/untested_good/.github/scripts/deploy.sh b/scripts/rules/tests/fixtures/ci_scripts/untested_good/.github/scripts/deploy.sh
new file mode 100644
index 000000000..0eedfc322
--- /dev/null
+++ b/scripts/rules/tests/fixtures/ci_scripts/untested_good/.github/scripts/deploy.sh
@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+echo "deploying"
diff --git a/scripts/rules/tests/fixtures/ci_scripts/untested_good/.github/workflows/ci.yml b/scripts/rules/tests/fixtures/ci_scripts/untested_good/.github/workflows/ci.yml
new file mode 100644
index 000000000..a83661ae6
--- /dev/null
+++ b/scripts/rules/tests/fixtures/ci_scripts/untested_good/.github/workflows/ci.yml
@@ -0,0 +1,8 @@
+name: CI
+on: push
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy
+        run: bash .github/scripts/deploy.sh
diff --git a/scripts/rules/tests/fixtures/ci_scripts/untested_good/tests/test_deploy.py b/scripts/rules/tests/fixtures/ci_scripts/untested_good/tests/test_deploy.py
new file mode 100644
index 000000000..fcac52dd8
--- /dev/null
+++ b/scripts/rules/tests/fixtures/ci_scripts/untested_good/tests/test_deploy.py
@@ -0,0 +1,3 @@
+"""Fixture: the only thing that matters is that this test names deploy.sh."""
+
+SCRIPT = ".github/scripts/deploy.sh"
diff --git a/scripts/rules/tests/test_adapters.py b/scripts/rules/tests/test_adapters.py
new file mode 100644
index 000000000..00fed8ed2
--- /dev/null
+++ b/scripts/rules/tests/test_adapters.py
@@ -0,0 +1,58 @@
+"""Tests for the agent-adapter check: CLAUDE.md and friends only point to AGENTS.md."""
+
+from __future__ import annotations
+
+import shutil
+import tempfile
+import unittest
+from pathlib import Path
+
+from scripts.rules.adapters import check_adapters
+from scripts.rules.model import Agents
+from scripts.rules.render import BEGIN
+
+FIXTURES = Path(__file__).parent / "fixtures" / "adapters"
+AGENTS = Agents(instructions="AGENTS.md", adapters=("CLAUDE.md",), max_adapter_lines=5)
+
+
+def violations_for(adapter_text: str) -> list[str]:
+    with tempfile.TemporaryDirectory() as tmp:
+        root = Path(tmp)
+        (root / "AGENTS.md").write_text("# Agent Instructions\n")
+        (root / "CLAUDE.md").write_text(adapter_text)
+        return [str(v) for v in check_adapters(AGENTS, root)]
+
+
+class TestAdaptersProof(unittest.TestCase):
+    def test_rule_proof_adapters(self) -> None:
+        bad = (FIXTURES / "bad_CLAUDE.md").read_text()
+        good = (FIXTURES / "good_CLAUDE.md").read_text()
+        self.assertTrue(violations_for(bad))
+        self.assertEqual(violations_for(good), [])
+
+
+class AdapterTest(unittest.TestCase):
+    def test_adapter_must_point_to_agents_md(self) -> None:
+        self.assertIn("does not point to AGENTS.md", violations_for("# Claude\n")[0])
+
+    def test_adapter_must_not_list_skills(self) -> None:
+        text = "See `AGENTS.md`.\nRead `docs/engineering/skills/testing.md`.\n"
+        self.assertIn("references other docs", violations_for(text)[0])
+
+    def test_adapter_must_not_carry_the_rules_block(self) -> None:
+        text = f"See `AGENTS.md`.\n{BEGIN}\n"
+        self.assertIn("contains the generated rules block", violations_for(text)[0])
+
+    def test_adapter_must_stay_short(self) -> None:
+        text = "See `AGENTS.md`.\n" + "guidance\n" * 6
+        self.assertIn("non-empty lines (limit 5)", violations_for(text)[0])
+
+    def test_missing_adapter_is_left_to_validation(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            shutil.copy(FIXTURES / "good_CLAUDE.md", root / "OTHER.md")
+            self.assertEqual(check_adapters(AGENTS, root), [])
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/scripts/rules/tests/test_ci_scripts.py b/scripts/rules/tests/test_ci_scripts.py
new file mode 100644
index 000000000..018a8d680
--- /dev/null
+++ b/scripts/rules/tests/test_ci_scripts.py
@@ -0,0 +1,178 @@
+"""Tests for the ci-scripts guard: workflow logic lives in tested shell scripts."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import tempfile
+import unittest
+from pathlib import Path
+
+from scripts.rules.ci_scripts import (
+    Findings,
+    compare,
+    multiline_runs,
+    shellcheck_failures,
+    untested_scripts,
+)
+from scripts.rules.load import load_text
+from scripts.rules.model import CiScripts
+from scripts.rules.workflows import logical_lines, parse_jobs
+
+FIXTURES = Path(__file__).parent / "fixtures" / "ci_scripts"
+CONFIG = CiScripts(
+    workflows=".github/workflows/*.yml",
+    scripts_dir=".github/scripts",
+    test_globs=("tests/**/test_*.py",),
+    multiline_baseline="rules/baselines/ci-multiline-run.txt",
+    untested_baseline="rules/baselines/ci-untested-scripts.txt",
+    shellcheck_baseline="rules/baselines/ci-shellcheck.txt",
+)
+
+
+def require_shellcheck(test: unittest.TestCase) -> None:
+    if shutil.which("shellcheck") is None:
+        if os.environ.get("GITHUB_ACTIONS"):
+            test.fail("shellcheck must be installed in CI")
+        test.skipTest("shellcheck is not installed")
+
+
+class TestCiScriptsProof(unittest.TestCase):
+    """Proofs that each ci-scripts check rejects a bad example and accepts a good one."""
+
+    def test_rule_proof_multiline_run(self) -> None:
+        self.assertEqual(
+            multiline_runs(CONFIG, FIXTURES / "multiline_bad"),
+            {".github/workflows/ci.yml :: build :: Build"},
+        )
+        self.assertEqual(multiline_runs(CONFIG, FIXTURES / "multiline_good"), set())
+
+    def test_rule_proof_untested_script(self) -> None:
+        self.assertEqual(
+            untested_scripts(CONFIG, FIXTURES / "untested_bad"),
+            {".github/scripts/deploy.sh"},
+        )
+        self.assertEqual(untested_scripts(CONFIG, FIXTURES / "untested_good"), set())
+
+    def test_rule_proof_shellcheck(self) -> None:
+        require_shellcheck(self)
+        for name, expected in (("bad_script.sh", True), ("good_script.sh", False)):
+            with tempfile.TemporaryDirectory() as tmp:
+                scripts = Path(tmp) / ".github" / "scripts"
+                scripts.mkdir(parents=True)
+                shutil.copy(FIXTURES / "shellcheck" / name, scripts / name)
+                failures = shellcheck_failures(CONFIG, Path(tmp))
+                self.assertEqual(bool(failures), expected, name)
+
+
+class LogicalLinesTest(unittest.TestCase):
+    def test_literal_block_counts_lines(self) -> None:
+        self.assertEqual(logical_lines("make deps\nmake build", "|"), 2)
+
+    def test_backslash_continuation_is_one_line(self) -> None:
+        self.assertEqual(logical_lines("docker build \\\n  --tag x \\\n  .", "|"), 1)
+
+    def test_folded_block_is_one_line_per_paragraph(self) -> None:
+        self.assertEqual(logical_lines("pytest a\nb\n\npytest c", ">"), 2)
+
+    def test_blank_lines_do_not_count(self) -> None:
+        self.assertEqual(logical_lines("\nmake build\n\n", "|"), 1)
+
+    def test_comment_lines_are_stripped_by_the_reader(self) -> None:
+        text = (
+            "jobs:\n  a:\n    steps:\n      - name: One\n        run: |\n"
+            "          # explain\n          make build\n"
+        )
+        jobs, _ = parse_jobs(text)
+        self.assertEqual(jobs["a"].run_blocks[0].code_lines, 1)
+
+    def test_steps_are_labelled_by_name_or_position(self) -> None:
+        text = (
+            "jobs:\n  a:\n    steps:\n    - uses: actions/checkout@v4\n"
+            "    - run: |\n        one\n        two\n      name: Named after\n"
+            "    - run: echo three\n"
+        )
+        jobs, _ = parse_jobs(text)
+        steps = [(block.step, block.code_lines) for block in jobs["a"].run_blocks]
+        self.assertEqual(steps, [("Named after", 2), ("step 3", 1)])
+
+
+REGISTRY = """
+schema_version = 1
+repo = "example"
+tool_version = "0.1.0"
+
+[[category]]
+id = "ci"
+title = "CI"
+
+[ci_scripts]
+workflows = ".github/workflows/*.yml"
+scripts_dir = ".github/scripts"
+test_globs = ["tests/**/test_*.py"]
+multiline_baseline = "rules/baselines/ci-multiline-run.txt"
+untested_baseline = "rules/baselines/ci-untested-scripts.txt"
+shellcheck_baseline = "rules/baselines/ci-shellcheck.txt"
+
+[[rule]]
+id = "ex.ci.multiline"
+category = "ci"
+statement = "One line per run block."
+rationale = "README.md"
+scope = ["README.md"]
+tier = "mechanical"
+status = "ratcheted"
+autofix = false
+[rule.enforcer]
+kind = "quality-guard"
+name = "ci-scripts"
+[[rule.ci]]
+workflow = ".github/workflows/pr.yml"
+job = "guards"
+invocation = "run_quality_guards.py"
+[rule.baseline]
+file = "rules/baselines/ci-multiline-run.txt"
+count = 1
+"""
+
+
+class CompareTest(unittest.TestCase):
+    def setUp(self) -> None:
+        self.tmp = tempfile.TemporaryDirectory()
+        self.root = Path(self.tmp.name)
+        baselines = self.root / "rules" / "baselines"
+        baselines.mkdir(parents=True)
+        (baselines / "ci-multiline-run.txt").write_text(
+            "# tolerated\nold :: job :: step\n"
+        )
+        registry, violations = load_text(REGISTRY)
+        assert registry is not None and not violations, violations
+        self.registry = registry
+
+    def tearDown(self) -> None:
+        self.tmp.cleanup()
+
+    def messages(self, found: set[str]) -> list[str]:
+        findings = Findings(multiline=found, untested=set(), shellcheck=set())
+        return [str(v) for v in compare(self.registry, findings, self.root)]
+
+    def test_baselined_finding_passes(self) -> None:
+        self.assertEqual(self.messages({"old :: job :: step"}), [])
+
+    def test_new_finding_fails_with_its_rule_id(self) -> None:
+        messages = self.messages({"old :: job :: step", "new :: job :: step"})
+        self.assertEqual(len(messages), 1)
+        self.assertIn(
+            "[ex.ci.multiline] ci-scripts: multi-line run: block new :: job :: step",
+            messages[0],
+        )
+
+    def test_fixed_finding_must_leave_the_baseline(self) -> None:
+        messages = self.messages(set())
+        self.assertIn(
+            "baseline entry no longer applies: old :: job :: step", messages[0]
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/scripts/rules/validate.py b/scripts/rules/validate.py
index 011a33c66..79aab5441 100644
--- a/scripts/rules/validate.py
+++ b/scripts/rules/validate.py
@@ -253,6 +253,34 @@ def v(rule_id: str | None, message: str, fix: str, check: str = "schema") -> Non
             "sync scripts/rules (see SYNC.md) and update tool_version",
         )
 
+    if registry.agents is not None:
+        for path in (registry.agents.instructions, *registry.agents.adapters):
+            if path and not (root / path).is_file():
+                v(
+                    None,
+                    f"agents file {path} does not exist",
+                    "fix [agents] or create the file",
+                )
+    if registry.ci_scripts is not None:
+        config = registry.ci_scripts
+        if config.scripts_dir and not (root / config.scripts_dir).is_dir():
+            v(
+                None,
+                f"ci_scripts.scripts_dir {config.scripts_dir} does not exist",
+                "fix [ci_scripts]",
+            )
+        for path in (
+            config.multiline_baseline,
+            config.untested_baseline,
+            config.shellcheck_baseline,
+        ):
+            if path and not (root / path).is_file():
+                v(
+                    None,
+                    f"ci_scripts baseline {path} does not exist",
+                    "create it (it may be empty)",
+                )
+
     category_ids = [category.id for category in registry.categories]
     for duplicate in sorted({c for c in category_ids if category_ids.count(c) > 1}):
         v(None, f"duplicate category '{duplicate}'", "give each category a unique id")
diff --git a/scripts/rules/workflows.py b/scripts/rules/workflows.py
index 2c3555f9d..2eba4a280 100644
--- a/scripts/rules/workflows.py
+++ b/scripts/rules/workflows.py
@@ -6,8 +6,9 @@
 block scalars), and ``strategy.matrix`` lists. Anything outside that subset is
 reported as unsupported rather than guessed at.
 
-It answers two questions: does job X exist, and does its run text (or reusable
-workflow reference) contain a given invocation string?
+It answers three questions: does job X exist, does its run text (or reusable
+workflow reference) contain a given invocation string, and how many lines of
+code does each step's ``run:`` block hold?
 """
 
 from __future__ import annotations
@@ -20,6 +21,15 @@
 _UNSUPPORTED = re.compile(r"(<<:|:\s*[&*][A-Za-z0-9_-]+\s*$)")
 
 
+@dataclass(frozen=True)
+class RunBlock:
+    """One step's ``run:`` script."""
+
+    step: str
+    code_lines: int
+    text: str
+
+
 @dataclass(frozen=True)
 class JobBlock:
     id: str
@@ -29,6 +39,7 @@ class JobBlock:
     step_names: tuple[str, ...]
     step_uses: tuple[str, ...] = ()
     matrix: dict[str, tuple[str, ...]] = field(default_factory=dict)
+    run_blocks: tuple[RunBlock, ...] = ()
 
     def invokes(self, invocation: str) -> bool:
         """Whether the job's commands or actions mention ``invocation``."""
@@ -63,6 +74,35 @@ def _indent(line: str) -> int:
     return len(line) - len(line.lstrip(" "))
 
 
+def logical_lines(text: str, style: str) -> int:
+    """Lines of code in a run: script, as the shell sees them.
+
+    A folded (``>``) block is one command per paragraph, because YAML joins its
+    lines with spaces. In a literal (``|``) block, a line ending in a backslash
+    continues onto the next. Blank and comment-only lines don't count.
+    """
+    lines = [line for line in text.splitlines()]
+    if style == ">":
+        paragraphs, current = 0, False
+        for line in lines:
+            if line.strip():
+                if not current:
+                    paragraphs += 1
+                current = True
+            else:
+                current = False
+        return paragraphs
+    count, continued = 0, False
+    for line in lines:
+        if not line.strip():
+            continued = False
+            continue
+        if not continued:
+            count += 1
+        continued = line.rstrip().endswith("\\")
+    return count
+
+
 def _inline_list(value: str) -> tuple[str, ...]:
     inner = value.strip()[1:-1]
     return tuple(_unquote(item) for item in inner.split(",") if item.strip())
@@ -76,11 +116,22 @@ def _parse_job(job_id: str, lines: list[str], job_indent: int) -> JobBlock:
     steps: list[str] = []
     matrix: dict[str, tuple[str, ...]] = {}
     body_indent = None
+    # Step tracking, so each run: block can be attributed to its step.
+    item_indent: int | None = None
+    in_steps = False
+    step_index = 0
+    step_key_column = -1
+    step_labels: dict[int, str] = {}
+    blocks: list[tuple[int, str, str]] = []
     index = 0
     while index < len(lines):
         line = lines[index]
         match = _KEY.match(line)
         if not match:
+            item = _LIST_ITEM.match(line)
+            if in_steps and item and item_indent is not None:
+                if len(item.group(1)) == item_indent:
+                    step_index += 1
             index += 1
             continue
         leading, dash, key, value = match.groups()
@@ -88,6 +139,17 @@ def _parse_job(job_id: str, lines: list[str], job_indent: int) -> JobBlock:
         if body_indent is None and not dash:
             body_indent = key_column
         top_level = not dash and key_column == body_indent
+        if top_level:
+            in_steps = key == "steps" and not value
+            item_indent = None
+        elif in_steps and dash:
+            if item_indent is None:
+                item_indent = len(leading)
+            if len(leading) == item_indent:
+                step_index += 1
+                step_key_column = key_column
+        if in_steps and key == "name" and key_column == step_key_column:
+            step_labels[step_index] = _unquote(value)
 
         if key == "name" and top_level:
             name = _unquote(value)
@@ -107,8 +169,10 @@ def _parse_job(job_id: str, lines: list[str], job_indent: int) -> JobBlock:
                     block.append(lines[index].strip())
                     index += 1
                 runs.append("\n".join(block))
+                blocks.append((step_index, "\n".join(block), value.strip()[:1]))
                 continue
             runs.append(_unquote(value))
+            blocks.append((step_index, _unquote(value), "|"))
         elif key == "matrix" and not value:
             index += 1
             while index < len(lines) and (
@@ -146,6 +210,14 @@ def _parse_job(job_id: str, lines: list[str], job_indent: int) -> JobBlock:
         step_uses=tuple(step_uses),
         step_names=tuple(steps),
         matrix=matrix,
+        run_blocks=tuple(
+            RunBlock(
+                step=step_labels.get(number) or f"step {number}",
+                code_lines=logical_lines(text, style),
+                text=text,
+            )
+            for number, text, style in blocks
+        ),
     )
 
 
diff --git a/scripts/run_quality_guards.py b/scripts/run_quality_guards.py
index 0338c10d1..d347fb40e 100644
--- a/scripts/run_quality_guards.py
+++ b/scripts/run_quality_guards.py
@@ -11,12 +11,16 @@
 if str(REPO_ROOT) not in sys.path:
     sys.path.insert(0, str(REPO_ROOT))
 
+from scripts.rules import ci_scripts  # noqa: E402
 from scripts.rules import guard as rules_guard  # noqa: E402
 
 
 Guard = tuple[str, Callable[[], list[str]]]
 
-GUARDS: tuple[Guard, ...] = (("rules-registry", rules_guard.check),)
+GUARDS: tuple[Guard, ...] = (
+    ("rules-registry", rules_guard.check),
+    ("ci-scripts", ci_scripts.check),
+)
 
 
 def main() -> int:

From c31e1a1f7325243f45cb3f7cacd24379fbb27d65 Mon Sep 17 00:00:00 2001
From: Anthony Volk <14987227+anth-volk@users.noreply.github.com>
Date: Mon, 12 Oct 2026 23:37:57 +0400
Subject: [PATCH 2/5] Point CLAUDE.md and the Copilot instructions to AGENTS.md

Both adapters duplicated part of the skill list and had drifted from
AGENTS.md (observability and the rules registry were missing). They now
only point to AGENTS.md; the safety boundaries move into AGENTS.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/copilot-instructions.md | 13 +++++--------
 CLAUDE.md                       | 29 +++++------------------------
 2 files changed, 10 insertions(+), 32 deletions(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index c10c24527..230175d7b 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -1,11 +1,8 @@
 # Copilot Instructions
 
-Follow the repository's canonical engineering skills under
-`docs/engineering/skills/`.
+Repository-wide guidance for AI agents lives in `AGENTS.md`. Read it first: it
+lists the engineering skill to read for each kind of change, and its generated
+Rules section lists every rule that governs this repository.
 
-For tests, read `docs/engineering/skills/testing.md` before adding, moving, or
-reviewing test files. Do not duplicate or override that testing guidance here.
-
-For pull requests, read `docs/engineering/skills/github-prs.md` before opening,
-replacing, or sharing a PR. This repository only accepts same-repository PRs
-from branches in `PolicyEngine/policyengine-sim-api`; never create fork PRs.
+This file is a Copilot adapter. Keep it a pointer: put guidance in `AGENTS.md`
+or in a skill under `docs/engineering/skills/`, never here.
diff --git a/CLAUDE.md b/CLAUDE.md
index 8a6908e88..e31fcf566 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,27 +1,8 @@
 # Claude Instructions
 
-These instructions apply repository-wide.
+Repository-wide guidance for AI agents lives in `AGENTS.md`. Read it first: it
+lists the engineering skill to read for each kind of change, and its generated
+Rules section lists every rule that governs this repository.
 
-## Canonical Guidance
-
-Repository-wide AI-facing engineering guidance lives in `AGENTS.md`.
-Canonical skills live under `docs/engineering/skills/`.
-
-Use those files as the source of truth. This file is a Claude adapter and should
-stay thin; do not duplicate detailed testing, CI, formatting, or architecture
-rules here.
-
-## Required Skill Lookup
-
-Before opening, replacing, or sharing a PR, read
-`docs/engineering/skills/github-prs.md`.
-
-When adding, moving, or reviewing tests, read
-`docs/engineering/skills/testing.md`.
-
-## Safety Boundaries
-
-Do not commit directly to `main`.
-
-Do not make production deployment changes or publish clients unless the user
-explicitly asks for that operation.
+This file is a Claude adapter. Keep it a pointer: put guidance in `AGENTS.md` or
+in a skill under `docs/engineering/skills/`, never here.

From 8d5a4336d9ef1e2beafb3fda562693caa3f20cdf Mon Sep 17 00:00:00 2001
From: Anthony Volk <14987227+anth-volk@users.noreply.github.com>
Date: Mon, 12 Oct 2026 23:37:58 +0400
Subject: [PATCH 3/5] Require tested scripts for multi-line workflow steps

Document the rule in docs/engineering/skills/ci-workflows.md, install a
pinned shellcheck in the quality-guards job, and record today's exceptions
as baselines: 16 multi-line run: blocks, 4 untested scripts and 1 script
with a shellcheck finding.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/pr.yml                |  3 ++
 docs/engineering/skills/README.md       |  2 +
 docs/engineering/skills/ci-workflows.md | 50 +++++++++++++++++++++++++
 rules/baselines/ci-multiline-run.txt    | 17 +++++++++
 rules/baselines/ci-shellcheck.txt       |  2 +
 rules/baselines/ci-untested-scripts.txt |  5 +++
 6 files changed, 79 insertions(+)
 create mode 100644 docs/engineering/skills/ci-workflows.md
 create mode 100644 rules/baselines/ci-multiline-run.txt
 create mode 100644 rules/baselines/ci-shellcheck.txt
 create mode 100644 rules/baselines/ci-untested-scripts.txt

diff --git a/.github/workflows/pr.yml b/.github/workflows/pr.yml
index 64de3f752..96cc7e737 100644
--- a/.github/workflows/pr.yml
+++ b/.github/workflows/pr.yml
@@ -127,6 +127,9 @@ jobs:
     - name: Test the rules registry tool
       run: python -m unittest discover -s scripts/rules/tests -t .
 
+    - name: Install shellcheck (for the ci-scripts guard)
+      run: pip install "shellcheck-py==0.11.0.1"
+
     - name: Run quality guards
       run: python scripts/run_quality_guards.py
 
diff --git a/docs/engineering/skills/README.md b/docs/engineering/skills/README.md
index 180b4799e..f3f02b96c 100644
--- a/docs/engineering/skills/README.md
+++ b/docs/engineering/skills/README.md
@@ -9,6 +9,8 @@ first, then keep adapters thin.
 
 Current skills:
 
+- `ci-workflows.md`: one line of code per workflow `run:` block, tested
+  workflow scripts, and shellcheck.
 - `github-prs.md`: same-repository draft PR workflow, issue linkage, PR head
   verification, and title conventions.
 - `testing.md`: test placement, dependency boundaries, and expected validation
diff --git a/docs/engineering/skills/ci-workflows.md b/docs/engineering/skills/ci-workflows.md
new file mode 100644
index 000000000..51facdc2c
--- /dev/null
+++ b/docs/engineering/skills/ci-workflows.md
@@ -0,0 +1,50 @@
+# CI Workflows
+
+Read this before adding or changing a GitHub Actions workflow step, or a script
+under `.github/scripts/`.
+
+## One line of code per `run:` block
+
+A workflow `run:` block may hold only one line of code. Anything longer goes in
+a shell script under `.github/scripts/`, called from a single-line step:
+
+```yaml
+- name: Extract package versions
+  id: versions
+  run: .github/scripts/modal-extract-versions.sh projects/policyengine-simulation-executor
+```
+
+Inline shell in YAML can't be linted, unit-tested or run locally; a script can.
+
+Lines are counted as the shell sees them: a folded (`>`) block is one command
+per paragraph, a backslash-continued command is one line, and blank or
+comment-only lines don't count. A single line that chains commands (`a && b`)
+is allowed for now.
+
+## Writing a workflow script
+
+- Start with `#!/usr/bin/env bash` and `set -euo pipefail`.
+- Take inputs from arguments or environment variables, not from `${{ }}`
+  expressions inside the script.
+- It must pass `shellcheck` (the `ci-scripts` quality guard runs it).
+
+## Testing a workflow script
+
+Every script a workflow calls must be referenced by name in at least one test.
+Test it the way the existing scripts are tested: start it with `subprocess`,
+put fake versions of the commands it calls (`gcloud`, `pip`, `curl`, ...) first
+on `PATH`, and assert on what they were called with. Cover the success path and
+at least one failure path.
+
+Examples: `projects/policyengine-simulation-executor/tests/test_modal_scripts.py`
+and `projects/policyengine-simulation-entry/tests/test_deployment_assets.py`.
+
+## Enforcement and baselines
+
+The `ci-scripts` quality guard (`python scripts/run_quality_guards.py`, or
+`python -m scripts.rules ci-scripts`) checks all three rules above. Existing
+violations are listed in `rules/baselines/ci-*.txt`. Anything new fails, and so
+does a baseline entry that no longer applies, so each list only shrinks. When
+you convert an existing multi-line block into a script, or add a missing test,
+remove its baseline entry and lower the rule's `baseline.count` in
+`rules/registry.toml`.
diff --git a/rules/baselines/ci-multiline-run.txt b/rules/baselines/ci-multiline-run.txt
new file mode 100644
index 000000000..e924f370c
--- /dev/null
+++ b/rules/baselines/ci-multiline-run.txt
@@ -0,0 +1,17 @@
+# Tolerated existing violations. This list may only shrink.
+.github/workflows/pr-image-smoke.yml :: image-smoke :: Run image smokes
+.github/workflows/pr.yml :: lint :: Run ruff format check
+.github/workflows/pr.yml :: test :: Install dependencies
+.github/workflows/pr.yml :: test :: Run tests
+.github/workflows/pr.yml :: test-integration :: Run integration tests (local services only)
+.github/workflows/pr.yml :: test-integration :: Start services
+.github/workflows/publish-clients.yml :: publish :: Build simulation API client from the entrypoint contract
+.github/workflows/simulation-deploy.reusable.yml :: deploy_entrypoint :: Build and push entrypoint image
+.github/workflows/simulation-deploy.reusable.yml :: deploy_entrypoint :: Capture stable service state before deployment
+.github/workflows/simulation-deploy.reusable.yml :: deploy_entrypoint :: Resolve exact candidate metadata
+.github/workflows/simulation-deploy.reusable.yml :: deploy_executor :: Select versioned executor app
+.github/workflows/simulation-deploy.reusable.yml :: deploy_stage12_v2 :: Select the bundle-derived v2 application name
+.github/workflows/simulation-deploy.reusable.yml :: deploy_stage12_v2 :: Validate installed bundles, secrets, datasets, and calculations
+.github/workflows/simulation-deploy.reusable.yml :: deployment_ready :: Check deployment result
+.github/workflows/simulation-deploy.reusable.yml :: stage12_v2_ready :: Check Stage 12 deployment result
+.github/workflows/simulation-deploy.reusable.yml :: update_routing :: Publish active routing state
diff --git a/rules/baselines/ci-shellcheck.txt b/rules/baselines/ci-shellcheck.txt
new file mode 100644
index 000000000..9bc2c636a
--- /dev/null
+++ b/rules/baselines/ci-shellcheck.txt
@@ -0,0 +1,2 @@
+# Tolerated existing violations. This list may only shrink.
+.github/scripts/modal-precompute.sh
diff --git a/rules/baselines/ci-untested-scripts.txt b/rules/baselines/ci-untested-scripts.txt
new file mode 100644
index 000000000..bcc106dcb
--- /dev/null
+++ b/rules/baselines/ci-untested-scripts.txt
@@ -0,0 +1,5 @@
+# Tolerated existing violations. This list may only shrink.
+.github/scripts/dependency-update-commit-and-push.sh
+.github/scripts/dependency-update-create-pr.sh
+.github/scripts/dependency-update-prepare-branch.sh
+.github/scripts/update-policyengine-package.sh

From 1d5eead6aa051f58803d16601c5ad79d7ad4e74a Mon Sep 17 00:00:00 2001
From: Anthony Volk <14987227+anth-volk@users.noreply.github.com>
Date: Mon, 12 Oct 2026 23:37:58 +0400
Subject: [PATCH 4/5] Register the agent-adapter, tracking-issue and CI-script
 rules

Steps 1.3, 1.5 and 1.6: sim.agents.adapters-point-to-agents-md (enforced,
with proof), sim.process.pr-tracking-issue (doc-only, split out of
sim.process.same-repo-draft-prs), and three ratcheted sim.ci.* rules with
proofs. AGENTS.md gains the safety boundaries and a pointer to the CI
workflows skill.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 AGENTS.md               |  20 +++++-
 changelog_entry.yaml    |   1 +
 docs/generated/rules.md |  48 +++++++++++---
 rules/registry.toml     | 137 +++++++++++++++++++++++++++++++++++++++-
 4 files changed, 195 insertions(+), 11 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 52c8bc159..cd8ff1e71 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -18,6 +18,9 @@ Before changing correlation identifiers, telemetry transport, spans, stage
 names, logging, or observability failure handling, read
 `docs/engineering/skills/observability.md`.
 
+When adding or changing a GitHub Actions workflow step or a script under
+`.github/scripts/`, read `docs/engineering/skills/ci-workflows.md`.
+
 When adding, changing, or removing a rule, a guard test, a checker
 configuration, or a CI job that enforces one, read
 `docs/engineering/skills/rules-registry.md`.
@@ -67,6 +70,13 @@ same-repository draft PR.
   (including the rules registry), Docker build, and local integration tests.
 - There is currently no repository-wide changelog fragment requirement.
 
+## Safety Boundaries
+
+Do not commit directly to `main`.
+
+Do not make production deployment changes or publish clients unless the user
+explicitly asks for that operation.
+
 ## Rules
 
 <!-- BEGIN GENERATED: rules (python -m scripts.rules render) -->
@@ -128,12 +138,20 @@ To add or change a rule, read `docs/engineering/skills/rules-registry.md`.
 - `sim.quality.ruff-lint`: Python code passes ruff check with the rules selected in ruff.toml (ruff's defaults, made explicit); CI does not run ruff check yet. (advisory: ruff check (E4, E7, E9, F), not blocking)
 - `sim.quality.tests-pass`: Each project's unit tests pass in its own locked environment. (blocking: CI job `test`)
 
+### CI workflows and scripts
+
+- `sim.ci.multiline-run-is-script`: A GitHub Actions run: block holds at most one line of code; longer logic lives in a tested script under .github/scripts/, called from a single-line step. (blocking: quality guard `ci-scripts`)
+- `sim.ci.shell-scripts-pass-shellcheck`: Every shell script under .github/scripts/ passes shellcheck. (blocking: quality guard `ci-scripts`)
+- `sim.ci.workflow-scripts-tested`: Every shell script a workflow calls is run by at least one test. (blocking: quality guard `ci-scripts`)
+
 ### Process and repository hygiene
 
+- `sim.agents.adapters-point-to-agents-md`: CLAUDE.md and .github/copilot-instructions.md only point to AGENTS.md; skills and rules are listed in AGENTS.md alone. (blocking: quality guard `rules-registry`)
 - `sim.process.agents-never-bypass`: Agents never bypass branch rules, even with admin credentials: no gh pr merge --admin and no bypass option; a blocked merge is reported to a human. (doc-only, not checked: follow it yourself)
+- `sim.process.pr-tracking-issue`: Every PR has a tracking issue in this repository, and the first line of its description is Fixes #ISSUE_NUMBER. (doc-only, not checked: follow it yourself)
 - `sim.process.rule-machinery-code-owned`: Changes to the rule machinery (rules/, scripts/rules/, scripts/run_quality_guards.py and CODEOWNERS) need approval from a core developer other than the author. (doc-only, not checked: follow it yourself)
 - `sim.process.rules-registry`: Every rule is registered in rules/registry.toml, is enforced where it claims to be, and its rendered views are current. (blocking: quality guard `rules-registry`)
-- `sim.process.same-repo-draft-prs`: PRs are opened as drafts from branches in PolicyEngine/policyengine-sim-api, never from forks, and start with 'Fixes #<issue>'. (doc-only, not checked: follow it yourself)
+- `sim.process.same-repo-draft-prs`: PRs are opened as drafts from branches in PolicyEngine/policyengine-sim-api, never from forks. (doc-only, not checked: follow it yourself)
 - `sim.process.stacked-prs-full-ci-at-bottom`: In a stack of pull requests, only the lowest unmerged one runs the full PR workflow and the Modal image smoke. Every pr.yml job is needed by the CI complete gate, which fails on the pull requests above it and otherwise passes only when every job passed, so a stack merges bottom-up and nothing merges untested. (blocking: pytest `projects/policyengine-simulation-executor/tests/test_ci_complete_gate.py`)
 
 <!-- END GENERATED: rules -->
diff --git a/changelog_entry.yaml b/changelog_entry.yaml
index fbc6287fd..979e3506e 100644
--- a/changelog_entry.yaml
+++ b/changelog_entry.yaml
@@ -1,6 +1,7 @@
 - bump: patch
   changes:
     added:
+      - Made CLAUDE.md and the Copilot instructions thin pointers to AGENTS.md, required workflow logic longer than one line to live in tested and shellchecked scripts, and registered the tracking-issue rule
       - Added a rules registry (rules/registry.toml) with a standard-library tool that validates it, checks every rule is enforced where it claims, and renders docs/generated/rules.md and the Rules block in AGENTS.md
     changed:
       - Added CODEOWNERS for the rule machinery, pinned CI's ruff to 0.15.22 with an explicit rule selection, and documented that agents never bypass branch rules
diff --git a/docs/generated/rules.md b/docs/generated/rules.md
index bb5851ca9..1859f82e7 100644
--- a/docs/generated/rules.md
+++ b/docs/generated/rules.md
@@ -1,6 +1,6 @@
 # Rules
 
-Generated by `python -m scripts.rules render` (scripts/rules v0.1.0, tool sha256 `803fdc2cb511`) from `rules/registry.toml`. Do not edit by hand.
+Generated by `python -m scripts.rules render` (scripts/rules v0.1.0, tool sha256 `c261415e2136`) from `rules/registry.toml`. Do not edit by hand.
 
 Every rule that governs `policyengine-sim-api` is listed here with how it is enforced. Blocking rules fail CI. The Gaps section lists what is written down but not yet enforced or proven. To add or change a rule, see `docs/engineering/skills/rules-registry.md`.
 
@@ -8,11 +8,11 @@ Every rule that governs `policyengine-sim-api` is listed here with how it is enf
 
 | Tier | enforced | ratcheted | advisory | doc-only | Total |
 | --- | ---: | ---: | ---: | ---: | ---: |
-| mechanical | 25 | 0 | 1 | 13 | 39 |
+| mechanical | 26 | 3 | 1 | 14 | 44 |
 | metric | 0 | 0 | 0 | 0 | 0 |
 | judgment | 0 | 0 | 0 | 0 | 0 |
 
-**Blocking:** 25 of 39 rules.
+**Blocking:** 29 of 44 rules.
 
 ## Gaps
 
@@ -27,8 +27,9 @@ Every rule that governs `policyengine-sim-api` is listed here with how it is enf
 - `sim.observability.id-is-diagnostic-only`: observability_id has diagnostic meaning only: never use it for idempotency, authorization, database identity, routing or business logic.
 - `sim.observability.registered-stages-only`: Span names come from the stage plans in policyengine_simulation_observability.stages; runtime code never adds span-name string literals.
 - `sim.process.agents-never-bypass`: Agents never bypass branch rules, even with admin credentials: no gh pr merge --admin and no bypass option; a blocked merge is reported to a human.
+- `sim.process.pr-tracking-issue`: Every PR has a tracking issue in this repository, and the first line of its description is Fixes #ISSUE_NUMBER.
 - `sim.process.rule-machinery-code-owned`: Changes to the rule machinery (rules/, scripts/rules/, scripts/run_quality_guards.py and CODEOWNERS) need approval from a core developer other than the author.
-- `sim.process.same-repo-draft-prs`: PRs are opened as drafts from branches in PolicyEngine/policyengine-sim-api, never from forks, and start with 'Fixes #<issue>'.
+- `sim.process.same-repo-draft-prs`: PRs are opened as drafts from branches in PolicyEngine/policyengine-sim-api, never from forks.
 - `sim.quality.every-project-tested`: Every project and library with unit tests runs them in the PR test matrix.
 - `sim.quality.ruff-format-tests`: Test code is formatted with ruff format too; CI currently checks only src directories.
 
@@ -59,7 +60,9 @@ Every rule that governs `policyengine-sim-api` is listed here with how it is enf
 
 ### Ratcheted (existing violations still tolerated)
 
-- None.
+- `sim.ci.multiline-run-is-script`: 16 remaining in `rules/baselines/ci-multiline-run.txt`
+- `sim.ci.shell-scripts-pass-shellcheck`: 1 remaining in `rules/baselines/ci-shellcheck.txt`
+- `sim.ci.workflow-scripts-tested`: 4 remaining in `rules/baselines/ci-untested-scripts.txt`
 
 ### Exceptions and review dates
 
@@ -259,33 +262,60 @@ flowchart LR
   e_CI_job_test --> j_CI_pr_yml_test
 ```
 
+## CI workflows and scripts
+
+| Rule | Statement | Tier | Status | Blocking | Enforced by | CI | Proof |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `sim.ci.multiline-run-is-script` | A GitHub Actions run: block holds at most one line of code; longer logic lives in a tested script under .github/scripts/, called from a single-line step. | mechanical | ratcheted | yes | quality guard `ci-scripts` | `pr.yml:quality-guards` | yes |
+| `sim.ci.shell-scripts-pass-shellcheck` | Every shell script under .github/scripts/ passes shellcheck. | mechanical | ratcheted | yes | quality guard `ci-scripts` | `pr.yml:quality-guards` | yes |
+| `sim.ci.workflow-scripts-tested` | Every shell script a workflow calls is run by at least one test. | mechanical | ratcheted | yes | quality guard `ci-scripts` | `pr.yml:quality-guards` | yes |
+
+```mermaid
+flowchart LR
+  r_sim_ci_multiline_run_is_script("sim.ci.multiline-run-is-script (ratcheted)")
+  e_quality_guard_ci_scripts["quality guard ci-scripts"]
+  j_CI_pr_yml_quality_guards["CI pr.yml:quality-guards"]
+  r_sim_ci_shell_scripts_pass_shellcheck("sim.ci.shell-scripts-pass-shellcheck (ratcheted)")
+  r_sim_ci_workflow_scripts_tested("sim.ci.workflow-scripts-tested (ratcheted)")
+  r_sim_ci_multiline_run_is_script --> e_quality_guard_ci_scripts
+  e_quality_guard_ci_scripts --> j_CI_pr_yml_quality_guards
+  r_sim_ci_shell_scripts_pass_shellcheck --> e_quality_guard_ci_scripts
+  r_sim_ci_workflow_scripts_tested --> e_quality_guard_ci_scripts
+```
+
 ## Process and repository hygiene
 
 | Rule | Statement | Tier | Status | Blocking | Enforced by | CI | Proof |
 | --- | --- | --- | --- | --- | --- | --- | --- |
+| `sim.agents.adapters-point-to-agents-md` | CLAUDE.md and .github/copilot-instructions.md only point to AGENTS.md; skills and rules are listed in AGENTS.md alone. | mechanical | enforced | yes | quality guard `rules-registry` | `pr.yml:quality-guards` | yes |
 | `sim.process.agents-never-bypass` | Agents never bypass branch rules, even with admin credentials: no gh pr merge --admin and no bypass option; a blocked merge is reported to a human. | mechanical | doc-only | no | nothing | — | — |
+| `sim.process.pr-tracking-issue` | Every PR has a tracking issue in this repository, and the first line of its description is Fixes #ISSUE_NUMBER. | mechanical | doc-only | no | nothing | — | — |
 | `sim.process.rule-machinery-code-owned` | Changes to the rule machinery (rules/, scripts/rules/, scripts/run_quality_guards.py and CODEOWNERS) need approval from a core developer other than the author. | mechanical | doc-only | no | nothing | — | — |
 | `sim.process.rules-registry` | Every rule is registered in rules/registry.toml, is enforced where it claims to be, and its rendered views are current. | mechanical | enforced | yes | quality guard `rules-registry` | `pr.yml:quality-guards` | **unproven** |
-| `sim.process.same-repo-draft-prs` | PRs are opened as drafts from branches in PolicyEngine/policyengine-sim-api, never from forks, and start with 'Fixes #<issue>'. | mechanical | doc-only | no | nothing | — | — |
+| `sim.process.same-repo-draft-prs` | PRs are opened as drafts from branches in PolicyEngine/policyengine-sim-api, never from forks. | mechanical | doc-only | no | nothing | — | — |
 | `sim.process.stacked-prs-full-ci-at-bottom` | In a stack of pull requests, only the lowest unmerged one runs the full PR workflow and the Modal image smoke. Every pr.yml job is needed by the CI complete gate, which fails on the pull requests above it and otherwise passes only when every job passed, so a stack merges bottom-up and nothing merges untested. | mechanical | enforced | yes | pytest `projects/policyengine-simulation-executor/tests/test_ci_complete_gate.py` | `pr.yml:test`, `pr.yml:ci-complete` | yes |
 
 ```mermaid
 flowchart LR
+  r_sim_agents_adapters_point_to_agents_md("sim.agents.adapters-point-to-agents-md (enforced)")
+  e_quality_guard_rules_registry["quality guard rules-registry"]
+  j_CI_pr_yml_quality_guards["CI pr.yml:quality-guards"]
   r_sim_process_agents_never_bypass("sim.process.agents-never-bypass (doc-only)")
   gap_unenforced>"not enforced"]
+  r_sim_process_pr_tracking_issue("sim.process.pr-tracking-issue (doc-only)")
   r_sim_process_rule_machinery_code_owned("sim.process.rule-machinery-code-owned (doc-only)")
   r_sim_process_rules_registry("sim.process.rules-registry (enforced)")
-  e_quality_guard_rules_registry["quality guard rules-registry"]
-  j_CI_pr_yml_quality_guards["CI pr.yml:quality-guards"]
   r_sim_process_same_repo_draft_prs("sim.process.same-repo-draft-prs (doc-only)")
   r_sim_process_stacked_prs_full_ci_at_bottom("sim.process.stacked-prs-full-ci-at-bottom (enforced)")
   e_pytest_projects_policyengine_simulation_executor_tests_test_ci_complete_gate_py["pytest projects/policyengine-simulation-executor/tests/test_ci_complete_gate.py"]
   j_CI_pr_yml_test["CI pr.yml:test"]
   j_CI_pr_yml_ci_complete["CI pr.yml:ci-complete"]
+  r_sim_agents_adapters_point_to_agents_md --> e_quality_guard_rules_registry
+  e_quality_guard_rules_registry --> j_CI_pr_yml_quality_guards
   r_sim_process_agents_never_bypass -.-> gap_unenforced
+  r_sim_process_pr_tracking_issue -.-> gap_unenforced
   r_sim_process_rule_machinery_code_owned -.-> gap_unenforced
   r_sim_process_rules_registry --> e_quality_guard_rules_registry
-  e_quality_guard_rules_registry --> j_CI_pr_yml_quality_guards
   r_sim_process_same_repo_draft_prs -.-> gap_unenforced
   r_sim_process_stacked_prs_full_ci_at_bottom --> e_pytest_projects_policyengine_simulation_executor_tests_test_ci_complete_gate_py
   e_pytest_projects_policyengine_simulation_executor_tests_test_ci_complete_gate_py --> j_CI_pr_yml_test
diff --git a/rules/registry.toml b/rules/registry.toml
index c6c339387..77c07ea50 100644
--- a/rules/registry.toml
+++ b/rules/registry.toml
@@ -36,6 +36,10 @@ title = "Observability"
 id = "quality"
 title = "Code quality and tests"
 
+[[category]]
+id = "ci"
+title = "CI workflows and scripts"
+
 [[category]]
 id = "process"
 title = "Process and repository hygiene"
@@ -50,6 +54,18 @@ guard_test_globs = [
   "projects/policyengine-simulation-gateway/tests/test_openapi_golden.py",
 ]
 
+[agents]
+instructions = "AGENTS.md"
+adapters = ["CLAUDE.md", ".github/copilot-instructions.md"]
+
+[ci_scripts]
+workflows = ".github/workflows/*.yml"
+scripts_dir = ".github/scripts"
+test_globs = ["projects/*/tests/**/test_*.py", "libs/*/tests/**/test_*.py"]
+multiline_baseline = "rules/baselines/ci-multiline-run.txt"
+untested_baseline = "rules/baselines/ci-untested-scripts.txt"
+shellcheck_baseline = "rules/baselines/ci-shellcheck.txt"
+
 # --- Service and package boundaries ----------------------------------------
 
 [[rule]]
@@ -634,6 +650,89 @@ autofix = false
 [rule.enforcer]
 kind = "none"
 
+# --- CI workflows and scripts ----------------------------------------------
+
+[[rule]]
+id = "sim.ci.multiline-run-is-script"
+category = "ci"
+statement = "A GitHub Actions run: block holds at most one line of code; longer logic lives in a tested script under .github/scripts/, called from a single-line step."
+rationale = "docs/engineering/skills/ci-workflows.md#one-line-of-code-per-run-block"
+scope = [".github/workflows/*.yml"]
+tier = "mechanical"
+status = "ratcheted"
+autofix = false
+[rule.enforcer]
+kind = "quality-guard"
+name = "ci-scripts"
+[[rule.ci]]
+workflow = ".github/workflows/pr.yml"
+job = "quality-guards"
+invocation = "run_quality_guards.py"
+[rule.baseline]
+file = "rules/baselines/ci-multiline-run.txt"
+count = 16
+[rule.proof]
+bad_fixture = "scripts/rules/tests/fixtures/ci_scripts/multiline_bad"
+good_fixture = "scripts/rules/tests/fixtures/ci_scripts/multiline_good"
+test = "scripts/rules/tests/test_ci_scripts.py::TestCiScriptsProof::test_rule_proof_multiline_run"
+workflow = ".github/workflows/pr.yml"
+job = "quality-guards"
+invocation = "unittest discover -s scripts/rules/tests"
+
+[[rule]]
+id = "sim.ci.workflow-scripts-tested"
+category = "ci"
+statement = "Every shell script a workflow calls is run by at least one test."
+rationale = "docs/engineering/skills/ci-workflows.md#testing-a-workflow-script"
+scope = [".github/scripts/*.sh"]
+tier = "mechanical"
+status = "ratcheted"
+autofix = false
+[rule.enforcer]
+kind = "quality-guard"
+name = "ci-scripts"
+[[rule.ci]]
+workflow = ".github/workflows/pr.yml"
+job = "quality-guards"
+invocation = "run_quality_guards.py"
+[rule.baseline]
+file = "rules/baselines/ci-untested-scripts.txt"
+count = 4
+[rule.proof]
+bad_fixture = "scripts/rules/tests/fixtures/ci_scripts/untested_bad"
+good_fixture = "scripts/rules/tests/fixtures/ci_scripts/untested_good"
+test = "scripts/rules/tests/test_ci_scripts.py::TestCiScriptsProof::test_rule_proof_untested_script"
+workflow = ".github/workflows/pr.yml"
+job = "quality-guards"
+invocation = "unittest discover -s scripts/rules/tests"
+
+[[rule]]
+id = "sim.ci.shell-scripts-pass-shellcheck"
+category = "ci"
+statement = "Every shell script under .github/scripts/ passes shellcheck."
+rationale = "docs/engineering/skills/ci-workflows.md#writing-a-workflow-script"
+scope = [".github/scripts/*.sh"]
+tier = "mechanical"
+status = "ratcheted"
+autofix = false
+[rule.enforcer]
+kind = "quality-guard"
+name = "ci-scripts"
+[[rule.ci]]
+workflow = ".github/workflows/pr.yml"
+job = "quality-guards"
+invocation = "run_quality_guards.py"
+[rule.baseline]
+file = "rules/baselines/ci-shellcheck.txt"
+count = 1
+[rule.proof]
+bad_fixture = "scripts/rules/tests/fixtures/ci_scripts/shellcheck/bad_script.sh"
+good_fixture = "scripts/rules/tests/fixtures/ci_scripts/shellcheck/good_script.sh"
+test = "scripts/rules/tests/test_ci_scripts.py::TestCiScriptsProof::test_rule_proof_shellcheck"
+workflow = ".github/workflows/pr.yml"
+job = "quality-guards"
+invocation = "unittest discover -s scripts/rules/tests"
+
 # --- Process and repository hygiene ----------------------------------------
 
 [[rule]]
@@ -704,10 +803,46 @@ autofix = false
 [rule.enforcer]
 kind = "none"
 
+[[rule]]
+id = "sim.agents.adapters-point-to-agents-md"
+category = "process"
+statement = "CLAUDE.md and .github/copilot-instructions.md only point to AGENTS.md; skills and rules are listed in AGENTS.md alone."
+rationale = "AGENTS.md"
+scope = ["CLAUDE.md", ".github/copilot-instructions.md"]
+tier = "mechanical"
+status = "enforced"
+autofix = false
+[rule.enforcer]
+kind = "quality-guard"
+name = "rules-registry"
+[[rule.ci]]
+workflow = ".github/workflows/pr.yml"
+job = "quality-guards"
+invocation = "run_quality_guards.py"
+[rule.proof]
+bad_fixture = "scripts/rules/tests/fixtures/adapters/bad_CLAUDE.md"
+good_fixture = "scripts/rules/tests/fixtures/adapters/good_CLAUDE.md"
+test = "scripts/rules/tests/test_adapters.py::TestAdaptersProof::test_rule_proof_adapters"
+workflow = ".github/workflows/pr.yml"
+job = "quality-guards"
+invocation = "unittest discover -s scripts/rules/tests"
+
+[[rule]]
+id = "sim.process.pr-tracking-issue"
+category = "process"
+statement = "Every PR has a tracking issue in this repository, and the first line of its description is Fixes #ISSUE_NUMBER."
+rationale = "docs/engineering/skills/github-prs.md#same-repository-draft-prs-only"
+scope = [".github/pull_request_template.md"]
+tier = "mechanical"
+status = "doc-only"
+autofix = false
+[rule.enforcer]
+kind = "none"
+
 [[rule]]
 id = "sim.process.same-repo-draft-prs"
 category = "process"
-statement = "PRs are opened as drafts from branches in PolicyEngine/policyengine-sim-api, never from forks, and start with 'Fixes #<issue>'."
+statement = "PRs are opened as drafts from branches in PolicyEngine/policyengine-sim-api, never from forks."
 rationale = "docs/engineering/skills/github-prs.md"
 scope = [".github/pull_request_template.md"]
 tier = "mechanical"

From 938d02aa257dfc70b543865fba2e709b6a0ac379 Mon Sep 17 00:00:00 2001
From: Anthony Volk <14987227+anth-volk@users.noreply.github.com>
Date: Mon, 12 Oct 2026 23:57:14 +0400
Subject: [PATCH 5/5] Count every line and chained commands in run: blocks

Sync scripts/rules with policyengine-api: folded blocks and
backslash-continued lines now count line by line, and chaining commands
with &&, || or ; counts as more than one line. The multi-line baseline
grows from 16 to 20 entries (the backslash-continued commands).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 AGENTS.md                                     |  2 +-
 docs/engineering/skills/ci-workflows.md       | 14 ++--
 docs/generated/rules.md                       |  6 +-
 rules/baselines/ci-multiline-run.txt          |  4 +
 rules/registry.toml                           |  4 +-
 scripts/rules/ci_scripts.py                   |  7 +-
 .../multiline_bad/.github/workflows/ci.yml    |  6 ++
 .../multiline_good/.github/workflows/ci.yml   |  8 +-
 scripts/rules/tests/test_ci_scripts.py        | 44 ++++++++---
 scripts/rules/workflows.py                    | 78 ++++++++++++-------
 10 files changed, 114 insertions(+), 59 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index cd8ff1e71..5a457a752 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -140,7 +140,7 @@ To add or change a rule, read `docs/engineering/skills/rules-registry.md`.
 
 ### CI workflows and scripts
 
-- `sim.ci.multiline-run-is-script`: A GitHub Actions run: block holds at most one line of code; longer logic lives in a tested script under .github/scripts/, called from a single-line step. (blocking: quality guard `ci-scripts`)
+- `sim.ci.multiline-run-is-script`: A GitHub Actions run: block holds one line of code and no chained commands (&&, ||, ;); anything more lives in a tested script under .github/scripts/, called from a single-line step. (blocking: quality guard `ci-scripts`)
 - `sim.ci.shell-scripts-pass-shellcheck`: Every shell script under .github/scripts/ passes shellcheck. (blocking: quality guard `ci-scripts`)
 - `sim.ci.workflow-scripts-tested`: Every shell script a workflow calls is run by at least one test. (blocking: quality guard `ci-scripts`)
 
diff --git a/docs/engineering/skills/ci-workflows.md b/docs/engineering/skills/ci-workflows.md
index 51facdc2c..ad00fc324 100644
--- a/docs/engineering/skills/ci-workflows.md
+++ b/docs/engineering/skills/ci-workflows.md
@@ -5,8 +5,9 @@ under `.github/scripts/`.
 
 ## One line of code per `run:` block
 
-A workflow `run:` block may hold only one line of code. Anything longer goes in
-a shell script under `.github/scripts/`, called from a single-line step:
+A workflow `run:` block may hold only one line of code, with no chained
+commands. Anything more goes in a shell script under `.github/scripts/`, called
+from a single-line step:
 
 ```yaml
 - name: Extract package versions
@@ -16,10 +17,11 @@ a shell script under `.github/scripts/`, called from a single-line step:
 
 Inline shell in YAML can't be linted, unit-tested or run locally; a script can.
 
-Lines are counted as the shell sees them: a folded (`>`) block is one command
-per paragraph, a backslash-continued command is one line, and blank or
-comment-only lines don't count. A single line that chains commands (`a && b`)
-is allowed for now.
+Every non-empty, non-comment line counts, including each line of a folded
+(`>`) block and each backslash-continued line. Chaining commands on one line
+with `&&`, `||` or `;` also counts as more than one line. Operators inside
+quotes or `${{ }}` expressions don't count, and a single pipeline (`a | b`) is
+one command.
 
 ## Writing a workflow script
 
diff --git a/docs/generated/rules.md b/docs/generated/rules.md
index 1859f82e7..94ce0fd09 100644
--- a/docs/generated/rules.md
+++ b/docs/generated/rules.md
@@ -1,6 +1,6 @@
 # Rules
 
-Generated by `python -m scripts.rules render` (scripts/rules v0.1.0, tool sha256 `c261415e2136`) from `rules/registry.toml`. Do not edit by hand.
+Generated by `python -m scripts.rules render` (scripts/rules v0.1.0, tool sha256 `afc55ba219f1`) from `rules/registry.toml`. Do not edit by hand.
 
 Every rule that governs `policyengine-sim-api` is listed here with how it is enforced. Blocking rules fail CI. The Gaps section lists what is written down but not yet enforced or proven. To add or change a rule, see `docs/engineering/skills/rules-registry.md`.
 
@@ -60,7 +60,7 @@ Every rule that governs `policyengine-sim-api` is listed here with how it is enf
 
 ### Ratcheted (existing violations still tolerated)
 
-- `sim.ci.multiline-run-is-script`: 16 remaining in `rules/baselines/ci-multiline-run.txt`
+- `sim.ci.multiline-run-is-script`: 20 remaining in `rules/baselines/ci-multiline-run.txt`
 - `sim.ci.shell-scripts-pass-shellcheck`: 1 remaining in `rules/baselines/ci-shellcheck.txt`
 - `sim.ci.workflow-scripts-tested`: 4 remaining in `rules/baselines/ci-untested-scripts.txt`
 
@@ -266,7 +266,7 @@ flowchart LR
 
 | Rule | Statement | Tier | Status | Blocking | Enforced by | CI | Proof |
 | --- | --- | --- | --- | --- | --- | --- | --- |
-| `sim.ci.multiline-run-is-script` | A GitHub Actions run: block holds at most one line of code; longer logic lives in a tested script under .github/scripts/, called from a single-line step. | mechanical | ratcheted | yes | quality guard `ci-scripts` | `pr.yml:quality-guards` | yes |
+| `sim.ci.multiline-run-is-script` | A GitHub Actions run: block holds one line of code and no chained commands (&&, \|\|, ;); anything more lives in a tested script under .github/scripts/, called from a single-line step. | mechanical | ratcheted | yes | quality guard `ci-scripts` | `pr.yml:quality-guards` | yes |
 | `sim.ci.shell-scripts-pass-shellcheck` | Every shell script under .github/scripts/ passes shellcheck. | mechanical | ratcheted | yes | quality guard `ci-scripts` | `pr.yml:quality-guards` | yes |
 | `sim.ci.workflow-scripts-tested` | Every shell script a workflow calls is run by at least one test. | mechanical | ratcheted | yes | quality guard `ci-scripts` | `pr.yml:quality-guards` | yes |
 
diff --git a/rules/baselines/ci-multiline-run.txt b/rules/baselines/ci-multiline-run.txt
index e924f370c..bb27165c7 100644
--- a/rules/baselines/ci-multiline-run.txt
+++ b/rules/baselines/ci-multiline-run.txt
@@ -12,6 +12,10 @@
 .github/workflows/simulation-deploy.reusable.yml :: deploy_executor :: Select versioned executor app
 .github/workflows/simulation-deploy.reusable.yml :: deploy_stage12_v2 :: Select the bundle-derived v2 application name
 .github/workflows/simulation-deploy.reusable.yml :: deploy_stage12_v2 :: Validate installed bundles, secrets, datasets, and calculations
+.github/workflows/simulation-deploy.reusable.yml :: deploy_stage12_v2 :: Validate the packaged PolicyEngine.py bundle
 .github/workflows/simulation-deploy.reusable.yml :: deployment_ready :: Check deployment result
+.github/workflows/simulation-deploy.reusable.yml :: prepare :: Synchronize the Modal UK private-data credential
+.github/workflows/simulation-deploy.reusable.yml :: publish_stage12_v2_manifest :: Publish only the separate v2 manifest
 .github/workflows/simulation-deploy.reusable.yml :: stage12_v2_ready :: Check Stage 12 deployment result
 .github/workflows/simulation-deploy.reusable.yml :: update_routing :: Publish active routing state
+.github/workflows/simulation-deploy.yml :: summary :: Report promotion status
diff --git a/rules/registry.toml b/rules/registry.toml
index 77c07ea50..603b88d34 100644
--- a/rules/registry.toml
+++ b/rules/registry.toml
@@ -655,7 +655,7 @@ kind = "none"
 [[rule]]
 id = "sim.ci.multiline-run-is-script"
 category = "ci"
-statement = "A GitHub Actions run: block holds at most one line of code; longer logic lives in a tested script under .github/scripts/, called from a single-line step."
+statement = "A GitHub Actions run: block holds one line of code and no chained commands (&&, ||, ;); anything more lives in a tested script under .github/scripts/, called from a single-line step."
 rationale = "docs/engineering/skills/ci-workflows.md#one-line-of-code-per-run-block"
 scope = [".github/workflows/*.yml"]
 tier = "mechanical"
@@ -670,7 +670,7 @@ job = "quality-guards"
 invocation = "run_quality_guards.py"
 [rule.baseline]
 file = "rules/baselines/ci-multiline-run.txt"
-count = 16
+count = 20
 [rule.proof]
 bad_fixture = "scripts/rules/tests/fixtures/ci_scripts/multiline_bad"
 good_fixture = "scripts/rules/tests/fixtures/ci_scripts/multiline_good"
diff --git a/scripts/rules/ci_scripts.py b/scripts/rules/ci_scripts.py
index e21391ac6..02b5f3f47 100644
--- a/scripts/rules/ci_scripts.py
+++ b/scripts/rules/ci_scripts.py
@@ -2,7 +2,7 @@
 
 Three checks, each ratcheted against a baseline file listed in ``[ci_scripts]``:
 
-1. A workflow ``run:`` block holds at most one logical line of code.
+1. A workflow ``run:`` block holds one line of code and no chained commands.
 2. Every shell script a workflow calls is referenced by at least one test.
 3. Every shell script in the scripts directory passes ``shellcheck``.
 
@@ -36,13 +36,14 @@ class Findings:
 
 
 def multiline_runs(config: CiScripts, root: Path) -> set[str]:
-    """``workflow :: job :: step`` for every run: block over one logical line."""
+    """``workflow :: job :: step`` for every run: block with more than one line of
+    code, or with commands chained by ``&&``, ``||`` or ``;``."""
     found = set()
     for workflow in sorted(root.glob(config.workflows)):
         relative = workflow.relative_to(root).as_posix()
         for job in workflow_jobs(workflow)[0].values():
             for block in job.run_blocks:
-                if block.code_lines > 1:
+                if not block.single_line:
                     found.add(SEPARATOR.join((relative, job.id, block.step)))
     return found
 
diff --git a/scripts/rules/tests/fixtures/ci_scripts/multiline_bad/.github/workflows/ci.yml b/scripts/rules/tests/fixtures/ci_scripts/multiline_bad/.github/workflows/ci.yml
index 6d8795076..02b440215 100644
--- a/scripts/rules/tests/fixtures/ci_scripts/multiline_bad/.github/workflows/ci.yml
+++ b/scripts/rules/tests/fixtures/ci_scripts/multiline_bad/.github/workflows/ci.yml
@@ -8,3 +8,9 @@ jobs:
         run: |
           make deps
           make build
+      - name: Folded test command
+        run: >-
+          python -m pytest tests/unit
+          tests/contract -q
+      - name: Chained
+        run: make deps && make build
diff --git a/scripts/rules/tests/fixtures/ci_scripts/multiline_good/.github/workflows/ci.yml b/scripts/rules/tests/fixtures/ci_scripts/multiline_good/.github/workflows/ci.yml
index 0ac8ccd7f..fa1eae23f 100644
--- a/scripts/rules/tests/fixtures/ci_scripts/multiline_good/.github/workflows/ci.yml
+++ b/scripts/rules/tests/fixtures/ci_scripts/multiline_good/.github/workflows/ci.yml
@@ -6,7 +6,7 @@ jobs:
     steps:
       - name: Build
         run: bash .github/scripts/build.sh
-      - name: Long single command
-        run: >-
-          python -m pytest tests/unit
-          tests/contract -q
+      - name: Test
+        run: python -m pytest tests -q | tee pytest.log
+      - name: Report
+        run: echo "${{ github.event_name == 'push' && 'push' || 'pr' }}; done"
diff --git a/scripts/rules/tests/test_ci_scripts.py b/scripts/rules/tests/test_ci_scripts.py
index 018a8d680..a4ec38b7c 100644
--- a/scripts/rules/tests/test_ci_scripts.py
+++ b/scripts/rules/tests/test_ci_scripts.py
@@ -17,7 +17,7 @@
 )
 from scripts.rules.load import load_text
 from scripts.rules.model import CiScripts
-from scripts.rules.workflows import logical_lines, parse_jobs
+from scripts.rules.workflows import chains_commands, code_lines, parse_jobs
 
 FIXTURES = Path(__file__).parent / "fixtures" / "ci_scripts"
 CONFIG = CiScripts(
@@ -43,7 +43,11 @@ class TestCiScriptsProof(unittest.TestCase):
     def test_rule_proof_multiline_run(self) -> None:
         self.assertEqual(
             multiline_runs(CONFIG, FIXTURES / "multiline_bad"),
-            {".github/workflows/ci.yml :: build :: Build"},
+            {
+                ".github/workflows/ci.yml :: build :: Build",
+                ".github/workflows/ci.yml :: build :: Folded test command",
+                ".github/workflows/ci.yml :: build :: Chained",
+            },
         )
         self.assertEqual(multiline_runs(CONFIG, FIXTURES / "multiline_good"), set())
 
@@ -65,18 +69,36 @@ def test_rule_proof_shellcheck(self) -> None:
                 self.assertEqual(bool(failures), expected, name)
 
 
-class LogicalLinesTest(unittest.TestCase):
-    def test_literal_block_counts_lines(self) -> None:
-        self.assertEqual(logical_lines("make deps\nmake build", "|"), 2)
+class CodeLinesTest(unittest.TestCase):
+    def test_every_line_counts(self) -> None:
+        self.assertEqual(code_lines("make deps\nmake build"), 2)
 
-    def test_backslash_continuation_is_one_line(self) -> None:
-        self.assertEqual(logical_lines("docker build \\\n  --tag x \\\n  .", "|"), 1)
-
-    def test_folded_block_is_one_line_per_paragraph(self) -> None:
-        self.assertEqual(logical_lines("pytest a\nb\n\npytest c", ">"), 2)
+    def test_backslash_continuation_lines_count(self) -> None:
+        self.assertEqual(code_lines("docker build \\\n  --tag x \\\n  ."), 3)
 
     def test_blank_lines_do_not_count(self) -> None:
-        self.assertEqual(logical_lines("\nmake build\n\n", "|"), 1)
+        self.assertEqual(code_lines("\nmake build\n\n"), 1)
+
+    def test_folded_block_counts_each_line(self) -> None:
+        text = "jobs:\n  a:\n    steps:\n      - run: >-\n          pytest a\n          b\n"
+        jobs, _ = parse_jobs(text)
+        block = jobs["a"].run_blocks[0]
+        self.assertEqual(block.code_lines, 2)
+        self.assertFalse(block.single_line)
+
+    def test_chained_commands_are_not_one_line(self) -> None:
+        for text in ("a && b", "a || b", "a; b", 'cd "$dir" && make'):
+            self.assertTrue(chains_commands(text), text)
+
+    def test_operators_in_quotes_and_expressions_are_ignored(self) -> None:
+        for text in (
+            'echo "a; b"',
+            "echo 'a && b'",
+            "echo ${{ a && b || c }}",
+            "echo \\; done",
+            "pytest -q | tee log",
+        ):
+            self.assertFalse(chains_commands(text), text)
 
     def test_comment_lines_are_stripped_by_the_reader(self) -> None:
         text = (
diff --git a/scripts/rules/workflows.py b/scripts/rules/workflows.py
index 2eba4a280..a432455fd 100644
--- a/scripts/rules/workflows.py
+++ b/scripts/rules/workflows.py
@@ -7,8 +7,8 @@
 reported as unsupported rather than guessed at.
 
 It answers three questions: does job X exist, does its run text (or reusable
-workflow reference) contain a given invocation string, and how many lines of
-code does each step's ``run:`` block hold?
+workflow reference) contain a given invocation string, and does each step's
+``run:`` block hold more than one line of code (or chain several commands)?
 """
 
 from __future__ import annotations
@@ -27,8 +27,13 @@ class RunBlock:
 
     step: str
     code_lines: int
+    chained: bool
     text: str
 
+    @property
+    def single_line(self) -> bool:
+        return self.code_lines <= 1 and not self.chained
+
 
 @dataclass(frozen=True)
 class JobBlock:
@@ -74,33 +79,47 @@ def _indent(line: str) -> int:
     return len(line) - len(line.lstrip(" "))
 
 
-def logical_lines(text: str, style: str) -> int:
-    """Lines of code in a run: script, as the shell sees them.
+def code_lines(text: str) -> int:
+    """Lines of code in a run: script: every non-empty, non-comment line.
 
-    A folded (``>``) block is one command per paragraph, because YAML joins its
-    lines with spaces. In a literal (``|``) block, a line ending in a backslash
-    continues onto the next. Blank and comment-only lines don't count.
+    The lines of a folded (``>``) block and backslash-continued lines each
+    count, because each is a line written in the workflow.
     """
-    lines = [line for line in text.splitlines()]
-    if style == ">":
-        paragraphs, current = 0, False
-        for line in lines:
-            if line.strip():
-                if not current:
-                    paragraphs += 1
-                current = True
-            else:
-                current = False
-        return paragraphs
-    count, continued = 0, False
-    for line in lines:
-        if not line.strip():
-            continued = False
-            continue
-        if not continued:
-            count += 1
-        continued = line.rstrip().endswith("\\")
-    return count
+    return sum(1 for line in text.splitlines() if line.strip())
+
+
+_CHAIN_OPERATORS = ("&&", "||", ";")
+
+
+def chains_commands(text: str) -> bool:
+    """Whether a line chains commands with ``&&``, ``||`` or ``;``.
+
+    Operators inside quotes or GitHub ``${{ }}`` expressions don't count. A
+    single pipeline (``a | b``) is one command and is allowed.
+    """
+    for line in text.splitlines():
+        index, quote = 0, ""
+        while index < len(line):
+            char = line[index]
+            if quote:
+                if char == "\\" and quote == '"':
+                    index += 2
+                    continue
+                if char == quote:
+                    quote = ""
+            elif line.startswith("${{", index):
+                end = line.find("}}", index)
+                index = len(line) if end == -1 else end + 2
+                continue
+            elif char == "\\":
+                index += 2
+                continue
+            elif char in "'\"":
+                quote = char
+            elif any(line.startswith(op, index) for op in _CHAIN_OPERATORS):
+                return True
+            index += 1
+    return False
 
 
 def _inline_list(value: str) -> tuple[str, ...]:
@@ -213,10 +232,11 @@ def _parse_job(job_id: str, lines: list[str], job_indent: int) -> JobBlock:
         run_blocks=tuple(
             RunBlock(
                 step=step_labels.get(number) or f"step {number}",
-                code_lines=logical_lines(text, style),
+                code_lines=code_lines(text),
+                chained=chains_commands(text),
                 text=text,
             )
-            for number, text, style in blocks
+            for number, text, _style in blocks
         ),
     )