chore: sync shared agent rules to v2

AGENTS.md

@@ -1,47 +1,90 @@
-<!-- BEGIN OPENAMROBOT SHARED RULES v1 -->
-# OpenAMRobot agent rules
-Canonical shared block: openAMRobot/.github, agent-rules/SHARED_RULES.md.
-This block is copied verbatim; GitHub does not propagate it between repositories.
+<!-- BEGIN OPENAMROBOT SHARED RULES v2 -->
+# OpenAMRobot rules for contributors and agents
+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.
 
-## Before editing
-- Read AGENTS.md, CONTRIBUTING.md, applicable nested instructions, code and tests.
-- Record the base SHA; inspect relevant open PRs and accessible branches/forks for overlap.
-- Do not infer contributor inactivity from absent public branches; disclose inaccessible work.
-- Follow the approved task scope and applicable plan/contracts. Report contradictions.
-- Reuse maintained upstream packages and existing implementation; minimize custom glue.
-- Do not replace working legacy support merely because the new-robot BOM excludes it.
+## Decisions
+- 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]
 
-## Boundaries
-- Shared ROS contracts belong in openamrobot-interfaces; identify their actual acceptance status.
-- New contract proposals stay isolated and labelled Proposed, pending owner review.
-- Do not author or modify safety implementation: E-stop, brakes, motion interlocks,
-  watchdogs, actuator enable or power-protection logic. Report required changes.
-- Status display and isolated test fixtures do not implement or validate physical safety.
-- Arm vendor SDKs stay behind Device Packages; none in UI or mission consumers.
-- Preserve Gate A Teensy/MPU6500 and Gate B STM32/ICM-42688-P distinctions.
-- Jetson is the 2.0 reference compute; retain correctly labelled historical material.
-- Public application name: Use_Case_1. No customer/partner names, secrets or private data.
-- Preserve third-party provenance. Do not change licensing, NOTICE or CODEOWNERS
-  without an explicit task that authorizes those files and the appropriate review.
-- Never connect untrusted/automated PR tests to physical motion hardware or secrets.
+## Contracts
+- 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]
 
-## Delivery
-- Use a contributor branch/fork and draft PR by default. Never merge, force-push,
-  modify protection/settings or bypass checks in ordinary implementation tasks.
-- Read applicable CLA/DCO rules. Never invent an exemption, identity or attestation.
-- Use git commit -s only with the verified contributor identity and provenance authority.
-- Disclose material AI assistance, dependencies and licence implications.
-- Report base/head SHAs, scope, safety impact, exact commands/results and evidence links.
-- For bug fixes show the regression fails before and passes after; for new features
-  demonstrate a meaningful deliberate fault is detected. Explain non-applicability.
-- Keep a Not verified section. SKIP/BLOCKED is not PASS; fixtures/fake hardware are
-  not integrated simulation, physical acceptance or release readiness.
-- Do not weaken checks, use empty suites as evidence or invent successful test results.
-- If blocked, stop the blocked activity, report command/error/next step and continue
-  independent in-scope work. Do not repeatedly reinstall or expand the architecture.
-- Owner alignment and approval status must be truthful. A draft or notification is
-  not evidence that a required discussion or technical acceptance has happened.
-<!-- END OPENAMROBOT SHARED RULES v1 -->
+## Tests
+- 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]
+
+## Evidence
+- 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]
+
+## Dependencies and licences
+- 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]
+
+## Safety
+- 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]
+
+## Publication
+- 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]
+
+## Agents
+- 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]
+
+## Failure
+- 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]
+
+## Learning
+- 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]
+<!-- END OPENAMROBOT SHARED RULES v2 -->
 
 # Repository-specific rules: openamrobot-ui
 ## Layout and ownership