docs(RMGR-WP-0001): complete T02 observation and command contracts

Define helixforge.repo-manager 0.1: observation ops, governed command
catalog, authz scopes, idempotency, evidence, failures, and hub-core ports.

docs/observation-command-contracts_v0.1.yaml

@@ -0,0 +1,149 @@
+# RMGR-ARCH-CMD-0001
+id: RMGR-ARCH-CMD-0001
+contract_id: helixforge.repo-manager
+contract_version: "0.1.0"
+status: draft-reviewable
+created: "2026-08-09"
+document: docs/observation-command-contracts_v0.1.md
+representation_ref: RMGR-ARCH-REP-0001
+workplan_task: RMGR-WP-0001-T02
+
+rules:
+  - no_orm_in_public_dtos
+  - applied_file_commands_require_git_sha
+  - authz_before_mutation
+  - dual_write_same_fact_forbidden
+  - secrets_never_in_events
+
+common_envelope_fields:
+  - api_version
+  - correlation_id
+  - request_id
+  - actor
+  - authz
+
+idempotency:
+  commands:
+    key: idempotency_key
+    retention: ">=24h"
+    same_key_different_payload: conflict
+
+evidence_fields:
+  - status  # accepted | applied | rejected | failed
+  - git_sha
+  - git_refs
+  - forge_pr_url
+  - files_touched
+  - content_hashes
+  - observed_at
+  - notes
+
+error_codes:
+  - unauthorized
+  - not_found
+  - conflict
+  - precondition_failed
+  - validation_error
+  - policy_denied
+  - unavailable
+  - internal
+
+scopes:
+  - repo:read
+  - repo:register
+  - repo:reconcile
+  - repo:command:work_status
+  - repo:command:writeback_ids
+  - repo:command:lifecycle
+  - repo:command:agent_assign
+  - repo:admin
+
+observation:
+  fact_types:
+    - RepositorySnapshot
+    - WorkRecordIndexEntry
+    - ConsistencyFinding
+    - RevisionObservation
+    - AgentAssignment
+    - SignalSet
+  operations:
+    - id: GetRepository
+      port: port.repo
+      scope: repo:read
+    - id: ListRepositories
+      port: port.repo
+      scope: repo:read
+    - id: ObserveRevision
+      port: port.repo
+      scope: repo:read
+    - id: ListWorkRecords
+      port: port.work
+      scope: repo:read
+    - id: GetWorkRecord
+      port: port.work
+      scope: repo:read
+    - id: ListFindings
+      port: port.repo
+      scope: repo:read
+    - id: GetSignals
+      port: port.repo
+      scope: repo:read
+
+commands:
+  lifecycle_states: [accepted, running, applied, rejected, failed]
+  catalog:
+    - type: repo.register
+      scope: repo:register
+      mutates_git: false
+    - type: repo.set_host_path
+      scope: repo:register
+      mutates_git: false
+    - type: repo.set_lifecycle
+      scope: repo:command:lifecycle
+      mutates_git: false
+    - type: repo.reconcile
+      scope: repo:reconcile
+      mutates_git: false
+    - type: repo.rebuild_index
+      scope: repo:reconcile
+      mutates_git: false
+    - type: repo.work.update_task_status
+      scope: repo:command:work_status
+      mutates_git: true
+      params: [task_id, status, blocking_reason]
+    - type: repo.work.update_workplan_status
+      scope: repo:command:work_status
+      mutates_git: true
+      params: [workplan_id, status]
+    - type: repo.work.writeback_ids
+      scope: repo:command:writeback_ids
+      mutates_git: true
+    - type: repo.agents.assign
+      scope: repo:command:agent_assign
+      mutates_git: preferred
+
+events_emitted:
+  - repo.registered
+  - repo.observed
+  - repo.reconciled
+  - repo.command.applied
+  - repo.command.failed
+  - repo.work.indexed
+  - repo.drift.detected
+
+hub_core:
+  ports: [port.repo, port.work]
+  must_not:
+    - open_repo_manager_db
+    - import_orm_models
+    - dual_write_work_status_without_command_evidence
+
+conformance_min:
+  - C1_dto_no_orm
+  - C2_reconcile_idempotent
+  - C3_command_idempotency_key
+  - C4_stale_head_precondition
+  - C5_scope_deny
+  - C6_applied_has_git_sha
+  - C7_rebuild_index
+  - C8_events_correlation_no_secrets