governance: contribution harness, decisions register and Watchdog

.gitattributes

@@ -0,0 +1,5 @@
+# Shell scripts run under Linux bash, so they keep LF line endings even when a
+# contributor's Git uses core.autocrlf=true (CI owner review, 6 October 2026).
+# A shell script without one of these extensions gets its own line below.
+*.sh   text eol=lf
+*.bash text eol=lf

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,40 +1,58 @@
 name: Bug report
-description: Report a reproducible software or firmware defect
+description: Report a reproducible software or firmware defect with the evidence a fix needs
 title: "[Bug]: "
 labels: ["bug", "triage"]
 body:
   - type: markdown
     attributes:
-      value: "Do not include credentials, confidential information, export-controlled data, or third-party material you cannot disclose."
-  - type: textarea
-    id: summary
+      value: |
+        Issues are public. Do not include credentials, personal data, internal document links or prices.
+        The fix PR links this issue in its Work package section and adds a test that fails on the defect.
+  - type: input
+    id: repository
+    attributes:
+      label: Repository and path
+      placeholder: "openAMRobot/<repository>, path/to/file"
+    validations:
+      required: true
+  - type: input
+    id: commit
     attributes:
-      label: Summary
-      description: What happened, and what did you expect?
+      label: Commit SHA
+      description: Full or short SHA of the checkout where the defect reproduces.
+      placeholder: "d1ac6b64db83"
     validations:
       required: true
   - type: textarea
     id: reproduce
     attributes:
-      label: Reproduction steps
+      label: Exact commands
+      description: Commands that reproduce the defect, one per line, from a clean checkout.
+      render: shell
     validations:
       required: true
-  - type: input
-    id: version
+  - type: textarea
+    id: expected
     attributes:
-      label: Repository version, tag, or commit
+      label: Expected and actual result
+      description: Paste the relevant output; state the decision ID from decisions.yaml if a decided value is wrong.
     validations:
       required: true
-  - type: textarea
-    id: environment
+  - type: dropdown
+    id: safety
     attributes:
-      label: Environment
-      description: OS, ROS version, hardware, browser, and relevant dependencies.
+      label: Safety impact
+      description: E-stop, brake, contactor, watchdog, motor-enable and charge-inhibit defects are reported, never fixed by an agent.
+      options:
+        - None
+        - Motion, power, battery, actuator or safety I/O (platform lead reviews)
+    validations:
+      required: true
   - type: textarea
-    id: logs
+    id: not_verified
     attributes:
-      label: Logs and supporting evidence
-      description: Remove personal, confidential, and security-sensitive information.
+      label: Not verified
+      description: What you could not check, for example real hardware or another ROS distribution.
   - type: checkboxes
     id: provenance
     attributes:

.github/ISSUE_TEMPLATE/interface_change_request.yml → .github/ISSUE_TEMPLATE/contract_change_request.yml

@@ -1,11 +1,20 @@
-name: Interface change request
-description: Propose a controlled change to a ROS, API, message, schema, or other shared interface.
-title: "[INTERFACE] "
+name: Contract change request
+description: Propose a change to a message, service, action, schema, topic name, launch argument name or configuration ID.
+title: "[CONTRACT] "
+labels: ["contract-change", "triage"]
 body:
   - type: markdown
     attributes:
       value: |
-        Use this form before changing an interface consumed by another repository, node, service, tool, or operator surface.
+        Use this form before changing a contract consumed by another repository, node, service, tool, or operator surface:
+        messages, services, actions, schemas, topic names, launch argument names and configuration IDs (for example mast_1350).
+        The change lands in one PR that updates the contract package and every consumer together; that PR links this issue
+        in its Work package section.
+
+        To change an approved technical decision (a value, limit, exclusion or distinction in the decisions register,
+        openAMRobot/.github decisions.yaml), follow "Changing a decision" in AGENTS.md: this issue names the entry, the owner
+        updates the source document, and one reviewed PR updates the register entry, its supersedes history, its check
+        patterns with a test, and every affected consumer together. No tool rewrites the register or a source document.
 
         Keep generic interfaces generic. Do not add application-specific manipulation behavior or authoritative safety behavior to a telemetry or navigation contract without an explicit owning design decision.
 
@@ -22,11 +31,20 @@ body:
     id: contract
     attributes:
       label: Contract or interface
-      description: Name the message, service, action, API, schema, topic, or file being changed.
+      description: Name the message, service, action, schema, topic name, launch argument name, configuration ID or file being changed.
       placeholder: "repository, package, path, and interface name"
     validations:
       required: true
 
+  - type: input
+    id: decision_entry
+    attributes:
+      label: Decisions register entry
+      description: The decisions.yaml ID this request changes, or "none" for a contract that is not a recorded decision.
+      placeholder: "MAST-INSTALL-HEIGHT / none"
+    validations:
+      required: true
+
   - type: dropdown
     id: change_class
     attributes:
@@ -35,9 +53,9 @@ body:
       options:
         - Documentation-only or implementation clarification
         - Add an enum, reason code, or constant without changing field layout
-        - Add, remove, rename, reorder, or retype a field — version bump and consumer rebuild required
-        - Change the meaning, units, defaults, or validity of an existing value — version bump and consumer review required
-        - Other — explain below
+        - Add, remove, rename, reorder, or retype a field; version bump and consumer rebuild required
+        - Change the meaning, units, defaults, or validity of an existing value; version bump and consumer review required
+        - Other, explain below
     validations:
       required: true
 
@@ -107,3 +125,5 @@ body:
           required: true
         - label: I have not treated telemetry as authoritative safety evidence.
           required: true
+        - label: The implementing PR will update the contract package and its consumers together, or list each consumer PR.
+          required: true

.github/ISSUE_TEMPLATE/decision_review.yml

@@ -0,0 +1,63 @@
+name: Decision register review
+description: Confirm or change one approved decision after the Watchdog review reminder.
+title: "[decision-review] "
+labels:
+  - decision-review
+  - watchdog-review
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this form for one `decisions.yaml` entry. Do not paste private Drive links, prices,
+        credentials or customer information into a public issue. The Watchdog never changes the
+        register automatically; the final update is a reviewed pull request.
+  - type: input
+    id: decision_id
+    attributes:
+      label: Decision ID
+      description: The exact entry ID, for example COMPUTE or NAV-LIDAR.
+      placeholder: COMPUTE
+    validations:
+      required: true
+  - type: dropdown
+    id: outcome
+    attributes:
+      label: Review outcome
+      options:
+        - Confirm current decision
+        - Propose a decision change
+        - Insufficient evidence
+    validations:
+      required: true
+  - type: input
+    id: source_key
+    attributes:
+      label: Controlling source key and item
+      description: Use a traceable key and item/date, not a private URL.
+      placeholder: P-03-rev18.7 item 14, 6 October 2026
+    validations:
+      required: true
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Evidence summary
+      description: Summarize what was checked and include public repository paths or commit SHAs where useful.
+      placeholder: The controlling source still says ...; implementation checked at ...
+    validations:
+      required: true
+  - type: textarea
+    id: requested_action
+    attributes:
+      label: Requested action
+      description: State whether the owner should extend review_by, open a source change, or update consumers.
+    validations:
+      required: true
+  - type: checkboxes
+    id: ground_truth
+    attributes:
+      label: Ground-truth confirmation
+      options:
+        - label: I am responsible for, or have obtained, the controlling-source confirmation.
+          required: true
+        - label: I have not included private links, credentials, customer information or unverified values.
+          required: true

.github/ISSUE_TEMPLATE/good_first_issue.yml

@@ -0,0 +1,63 @@
+name: Good first issue
+description: A small, self-contained task for a first-time contributor (maintainers open these)
+title: "[Good first issue]: "
+labels: ["good first issue", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        A good first issue can be done in one PR, needs no hardware and no access beyond a fork, and
+        touches no safety path or shared contract. Maintainers add the area label from CONTRIBUTING.md.
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - documentation (openamrobot-docs)
+        - navigation and bring-up (openamr-platform-sw)
+        - interfaces (openamrobot-interfaces)
+        - manipulation (openamrobot-manipulation)
+        - operator UI (openamrobot-ui)
+        - manifest and release (openamrobot-manifest, openamrobot-release)
+        - CI and harness (.github)
+    validations:
+      required: true
+  - type: input
+    id: repository
+    attributes:
+      label: Repository and files
+      placeholder: "openAMRobot/<repository>: path/to/file"
+    validations:
+      required: true
+  - type: textarea
+    id: task
+    attributes:
+      label: Task
+      description: What needs to become true, in two or three sentences.
+    validations:
+      required: true
+  - type: textarea
+    id: done
+    attributes:
+      label: Done when
+      description: Observable pass/fail conditions, including the test that must fail before and pass after.
+      value: |
+        - [ ]
+    validations:
+      required: true
+  - type: textarea
+    id: verify
+    attributes:
+      label: How to verify
+      description: The exact command a contributor runs, and the result it prints.
+      render: shell
+    validations:
+      required: true
+  - type: input
+    id: mentor
+    attributes:
+      label: Reviewer role
+      description: Role from maintainers.yaml that reviews the PR.
+      placeholder: "docs-owner"
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/harness_mistake.yml

@@ -0,0 +1,61 @@
+name: Harness mistake
+description: Record an agent or process mistake so the monthly retro can turn it into a rule, check or template change
+title: "[Harness]: "
+labels: ["harness"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        One mistake per issue. The monthly retro reads every open issue with the label harness and
+        proposes one PR against AGENTS.md, the checkers or the templates in openAMRobot/.github.
+        Describe the mistake, not the person. No names, internal links or credentials.
+  - type: input
+    id: where
+    attributes:
+      label: Where it happened
+      description: Repository and PR or issue link.
+      placeholder: "openAMRobot/<repository>#<number>"
+    validations:
+      required: true
+  - type: dropdown
+    id: actor
+    attributes:
+      label: Who made the mistake
+      options:
+        - Agent (AI-assisted or automated)
+        - Contributor process
+        - Review process
+        - Automation or workflow
+    validations:
+      required: true
+  - type: input
+    id: template
+    attributes:
+      label: Prompt template and version
+      description: For agent runs, the agent-prompts/ file and the harness commit SHA it came from.
+      placeholder: "agent-prompts/docs-fix.md @ <sha>"
+  - type: textarea
+    id: mistake
+    attributes:
+      label: What went wrong
+      description: The observable result and the evidence (diff line, log line, comment link).
+    validations:
+      required: true
+  - type: dropdown
+    id: caught
+    attributes:
+      label: What caught it
+      options:
+        - A gate (check or CI)
+        - Human review
+        - Found after merge
+        - Not caught yet
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed harness change
+      description: A rule, a check, or a template change that would make this class of mistake unmergeable. Name who decides if it cannot be checked.
+    validations:
+      required: true