diff --git a/AGENTS.md b/AGENTS.md index 5fa48da2..81df5c47 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,47 +1,90 @@ - -# 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. + +# 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: `. + [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. - +## 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] + # Repository-specific rules: openamrobot-ui ## Layout and ownership