Canonical: openAMRobot/.github, agent-rules/SHARED_RULES.md, copied verbatim into every repository's AGENTS.md (tools/check_agent_rules.py reports drift). This file holds process; approved technical values live in openAMRobot/.github decisions.yaml. Labels: [check: tool] means the tool detects that violation, and only in repositories where its workflow is installed and required (rollout/README.md); [template: file]; [human: role, evidence] is a reviewer decision. A text check proves textual consistency, never mechanical, electrical or safety correctness.
- decisions.yaml is the only register of approved values, limits, exclusions and distinctions.
No file states a contradicting value; kept history carries
decision-allow: <ID> <reason>. [check: check_decisions.py, listed patterns only] [human: entry's reviewer, entry's evidence] - Changing a decision: (1) open a contract change request issue naming the entry; (2) the owner updates the source document; (3) one reviewed PR updates the register entry, its supersedes history, its check patterns with a test, and every affected consumer, or links each consumer PR; (4) the owner approves. [template: contract change request] [human: owner]
- Source documents are provenance. CI reads only the pinned register, never a drive or the docs site; a disagreement is reported to the owner, and no tool rewrites either side. [human: owner]
- Read STATE.md before work in a repository; update it in the same PR. [check: check_pr_evidence.py]
- Messages, services, actions, schemas, topic names, launch argument names and configuration IDs change only through a contract change request and one PR that updates the contract package and its consumers together. [template: contract change request] [human: software lead]
- New contract proposals stay labelled Proposed until the owner accepts them. [human: software lead]
- Every behaviour change carries a test that fails when the change is reverted; the Tests section shows that failing run. [template: PR Tests section] [human: reviewer, the revert run]
- A suite that executes zero tests fails. [check: verify.sh; check_pr_evidence.py on reported counts]
- skip, xfail and importorskip name a tracking issue on the same line. [check: verify.sh]
- SKIP or BLOCKED is not PASS. Fixtures and fake hardware are not simulation, physical acceptance or release readiness. [human: reviewer, Not verified section]
- Every PR states base SHA, head SHA, exact commands, test counts and a Not verified section. [check: check_pr_evidence.py, presence only] [human: reviewer, that the commands were run]
- A draft becomes ready only when the evidence check passes on the current head. [human: author; ruleset required check once installed]
- Nothing is added, removed or upgraded as a side effect. A changed dependency manifest needs a Dependencies section naming each change, its licence and source. [check: check_pr_evidence.py]
- Licence headers and package.xml tags match the licence map: MIT software and firmware, CERN-OHL-P-2.0 hardware, CC-BY-4.0 documentation. [human: repository owner]
- The Integration Gate section lists overlapping PRs, reused existing or upstream work and what was rejected. Third-party provenance stays intact. [template: PR template]
- LICENSE, LICENSING.md, NOTICE and CODEOWNERS change only in a PR whose task names them. [human: platform lead]
- No agent authors or modifies E-stop, brake, contactor, watchdog, motor-enable or charge-inhibit logic; agents report the need in an issue. [check: check_pr_evidence.py fails a safety-path change whose AI disclosure is not None] [human: platform lead, undisclosed use]
- A safety-path change needs two human approvals including the platform lead. The check only reports "safety path touched, two human approvals required" and that reviewers are requested; approvals are a ruleset requirement. [human: platform lead and one more maintainer]
- Functional telemetry, watchdogs, status displays and fixtures are never safety evidence. [check: check_decisions.py wording only] [human: platform lead, hardwired safety-chain test record]
- Automated or untrusted PR jobs never reach motion hardware or secrets. [human: CI owner]
- Public material (docs/, assets/, README.md, any path containing "public") has no internal document links, prices, contact data or credentials. [check: check_public_extract.py]
- It names no private person, customer or partner; the application name is Use_Case_1. [human: docs owner]
- Before any write, state a precondition block: repository (exact full name), branch, parent SHA, expected outcome. Read-only unless the task says otherwise. [template: agent-prompts/]
- Agent PRs stay draft until the work-package owner writes adopt, adapt or reject in the thread. [human: work-package owner]
- The PR's AI disclosure section names the tool and what it produced. [check: section present]
- Commits carry DCO sign-off with the contributor's own identity; never invent an identity or attestation. [human: maintainer; DCO check where installed]
- Gate A Teensy/MPU6500 and Gate B STM32/ICM-42688-P stay distinct; Jetson is the 2.0 compute. [check: check_decisions.py] Arm vendor SDKs stay behind device packages. [human: software lead]
- A failed precondition (repository, branch, SHA, access, source) stops the task. Report the command, the error and the next step; never work around it. [template: agent-prompts/]
- Never merge, force-push, change settings, weaken a check or invent a result. [human: ruleset]
- Every agent or process mistake gets an issue labelled harness. [template: harness mistake form]
- The monthly retro turns harness issues into one PR against this block. [human: software lead]
- This repository owns shared policy, the decisions register (decisions.yaml), maintainers.yaml, the checkers under tools/ and the reusable workflows. agent-rules/SHARED_RULES.md is canonical.
- Run before every PR:
bash rollout/verify.sh(unit tests of every checker, zero-test guard),python3 tools/check_decisions.py --decisions decisions.yaml --maintainers maintainers.yaml --validate-onlyandpython3 tools/check_agent_rules.py --canonical agent-rules/SHARED_RULES.md --file AGENTS.md. - Drift across repositories:
python3 tools/check_agent_rules.py --canonical agent-rules/SHARED_RULES.md --root <workspace>. The checker does not fetch repositories; the caller supplies the checkouts. - A change to the shared block bumps its marker version; rollout/README.md lists the order in which repositories adopt it. [human: CI owner]
- Files under rollout/ are proposals for other repositories; they take effect only when that repository's owner merges them. Do not claim rollout status that has not happened.