Point agent adapters to AGENTS.md and move multi-line workflow steps into tested scripts

[anth-volk]

Fixes #3889

Summary

The top of the rules stack: Phase 0 (#3887) → rules registry (#3884) → this PR, which covers Phase 1 steps 1.3, 1.5 and 1.6. The sim counterpart is PolicyEngine/policyengine-sim-api#757.

• 1.3: one source of agent instructions.

  • CLAUDE.md and .github/copilot-instructions.md are now short pointers to AGENTS.md. Both had duplicated the skill list and drifted from it.
  • The migration safety boundary moves from CLAUDE.md into AGENTS.md, so nothing is lost.
  • test_alembic_skill.py now checks AGENTS.md only.
  • The rules-registry guard enforces this through a new [agents] table: an adapter must mention AGENTS.md, must not reference other docs or carry the generated rules block, and must stay within 20 non-empty lines.
  • It's registered as api.agents.adapters-point-to-agents-md (enforced, with proof).

• 1.5: api.process.pr-tracking-issue is registered as doc-only (tracking issue plus Fixes #N first line). CI enforcement comes in step 2.8.

• 1.6: workflow logic lives in tested scripts. A new ci-scripts quality guard, configured in a [ci_scripts] table, runs three checks:

  • run: blocks with more than one line of code. Every non-empty line counts, including each line of a folded > block and each backslash-continued line. Commands chained with &&, || or ; also count as more than one line. Operators inside quotes or ${{ }} are ignored, and a single pipeline is one command.
  • Workflow scripts that no test file names.
  • shellcheck findings in .github/scripts/*.sh.

  Each check is ratcheted against a baseline in rules/baselines/: 10 multi-line or chained blocks, 1 untested script (cleanup_cloud_run_images.sh) and 1 shellcheck finding (deploy_observability_collector.sh, SC2129). Anything new fails, and so does a stale baseline entry, so the lists only shrink.

  The rules are api.ci.multiline-run-is-script, api.ci.workflow-scripts-tested and api.ci.shell-scripts-pass-shellcheck, all ratcheted, with proofs. The quality-guards jobs install a pinned shellcheck-py==0.11.0.1. The rule and how to test a workflow script are documented in docs/engineering/skills/ci-workflows.md.

• Tool changes: the workflow reader now records each step's run: block. The tool stays byte-identical with sim's copy; the tool sha256 in rules.md matches.

Testing

• python -m unittest discover -s scripts/rules/tests -t .: 74 tests pass, including the three CI-script proofs and the adapter proof. The shellcheck proof skips locally when shellcheck is missing, but fails in CI if it is missing there.

• With shellcheck installed, python scripts/run_quality_guards.py passes all three guards: migration-contracts, rules-registry and ci-scripts.

• python -m scripts.rules guard --base-ref origin/master passes.

• pytest on the API tests that read workflows, scripts or adapters, plus the CRUD boundary tests: 204 pass.

• Negative checks, each reverted afterwards:

  Change	Result
  Make the changelog step two lines	api.ci.multiline-run-is-script fails
  Call a new script that no test names	api.ci.workflow-scripts-tested fails
  Add an unquoted variable to health_check.sh	api.ci.shell-scripts-pass-shellcheck fails
  List a skill in CLAUDE.md	the adapters check fails

• ruff format --check . passes. actionlint reports nothing new.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.56%. Comparing base (880260a) to head (344702f).

Additional details and impacted files

@@               Coverage Diff               @@
##           rules-registry    #3890   +/-   ##
===============================================
  Coverage           87.56%   87.56%           
===============================================
  Files                 198      198           
  Lines               12211    12211           
  Branches             2159     2159           
===============================================
  Hits                10692    10692           
  Misses                922      922           
  Partials              597      597           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.