173 lines
4.2 KiB
YAML
173 lines
4.2 KiB
YAML
# 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.create_workplan
|
|
scope: repo:command:workplan
|
|
mutates_git: true
|
|
params: [workplan_id, title, goal, status, owner, domain, topic_slug]
|
|
- type: repo.work.update_workplan
|
|
scope: repo:command:workplan
|
|
mutates_git: true
|
|
params: [workplan_id, title, status, owner, domain, topic_slug]
|
|
- type: repo.work.archive_workplan
|
|
scope: repo:command:workplan
|
|
mutates_git: true
|
|
params: [workplan_id, confirm_archive]
|
|
- type: repo.work.writeback_ids
|
|
scope: repo:command:writeback_ids
|
|
mutates_git: true
|
|
- type: repo.register.upsert_entry
|
|
scope: repo:command:register
|
|
mutates_git: true
|
|
params: [kind, entry_id, title, status, data]
|
|
- type: repo.register.defer_entry
|
|
scope: repo:command:register
|
|
mutates_git: true
|
|
params: [kind, entry_id, status]
|
|
- type: repo.register.add_note
|
|
scope: repo:command:register
|
|
mutates_git: true
|
|
params: [kind, entry_id, note, author]
|
|
- 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
|