repo-manager/docs/repository-representation_v0.1.yaml

# RMGR-ARCH-REP-0001 — machine-readable field catalog
id: RMGR-ARCH-REP-0001
title: Repository representation model
version: "0.1"
status: draft-reviewable
created: "2026-08-09"
document: docs/repository-representation_v0.1.md
workplan_task: RMGR-WP-0001-T01

principles:
  - repository_autonomy
  - single_authority_per_fact
  - rebuildable_indexes
  - contract_isolation
  - signals_are_not_authority

lifecycle_status:
  - draft
  - active
  - paused
  - archived
  - retired

managed_repository_fields:
  - id: uuid
    authority: repo-manager
    projection: primary_key
  - id: slug
    authority: declared_registration
    projection: unique_key
  - id: name
    authority: declared
    projection: cache
  - id: forge_repo_id
    authority: forge
    projection: optional_cache
  - id: remote_url
    authority: git_remote
    projection: cache
  - id: default_branch
    authority: git_or_forge
    projection: cache
  - id: lifecycle
    authority: governed_command
    projection: yes
    enum_ref: lifecycle_status
  - id: description
    authority: INTENT_or_GOAL
    projection: cache
  - id: intent_uri
    authority: repository_file
    projection: path_plus_sha
  - id: scope_uri
    authority: repository_file
    projection: optional
  - id: owners
    authority: declared_in_repo
    projection: cache
  - id: domain
    authority: repo_classification_yaml
    projection: cache
  - id: repo_flavor
    authority: INTENT_frontmatter_or_inferred
    projection: cache
  - id: classification
    authority: repo_classification_yaml
    fields:
      - category
      - domain
      - secondary_domains
      - capability_tags
      - business_stake
      - business_mechanics
      - classified_at
      - classified_by
      - standard_version
  - id: host_paths
    authority: operator_registration
    projection: yes
    not_in_git: true
  - id: primary_local_path
    authority: operator
    projection: cache
  - id: head_sha
    authority: git
    projection: cache
  - id: git_fingerprint
    authority: derived_observation
    projection: cache
  - id: observed_at
    authority: repo-manager
    projection: yes
  - id: last_state_synced_at
    authority: repo-manager
    projection: yes

declared_record_classes:
  - class: workplan
    paths: ["workplans/*.md"]
    kind: workplan
    authority: repository_file
  - class: task
    paths: ["workplans/*.md#task"]
    kind: task
    authority: repository_file
  - class: intake
    paths: ["intakes/**", "workplans/**"]
    kind: intake
    authority: repository_file
  - class: decision
    paths: ["decisions/**", "workplans/**"]
    kind: decision
    authority: repository_file
  - class: engagement
    paths: ["engagements/**"]
    kind: engagement
    authority: repository_file
  - class: register_entry
    paths: ["registers/**", "canon/**", "docs/**"]
    kind: register-entry
    authority: repository_file
  - class: classification
    paths: [".repo-classification.yaml"]
    authority: repository_file
  - class: intent
    paths: ["INTENT.md", "GOAL.md"]
    authority: repository_file
  - class: contribution
    paths: ["contrib/**"]
    authority: repository_file
  - class: capability_registry
    paths: ["registry/capabilities/**"]
    authority: repository_file
  - class: lockfile_inventory
    paths: ["**/uv.lock", "**/package-lock.json", "**/Cargo.lock", "**/poetry.lock"]
    authority: repository_file
  - class: agent_instructions
    paths: ["AGENTS.md", ".claude/rules/**"]
    authority: repository_file

work_record_index_spine:
  - id
  - uuid
  - kind
  - status
  - owner
  - repo_slug
  - repo_uuid
  - source_path
  - source_revision
  - lane
  - indexed_at
  - drift

relations:
  - id: member_of
    from: managed_repository
    to: domain
  - id: depends_on
    from: workplan
    to: workplan
  - id: child_of
    from: task
    to: workplan
  - id: promoted_from
    from: work_record
    to: intake
  - id: related_repo
    from: managed_repository
    to: managed_repository
  - id: extracts_from
    from: managed_repository
    to: capability_or_repo

signals:
  - id: consistency_ok
    derived: true
  - id: classification_valid
    derived: true
  - id: sync_dirty
    derived: true
  - id: doi
    derived: true
  - id: sbom_stale
    derived: true
  - id: needs_human
    derived: true
    source: work_records
  - id: drift_count
    derived: true

agent_roles:
  - id: coach
    scope: repository
  - id: lead
    scope: repository
  - id: director
    scope: repository
  rules:
    - do_not_supersede_human_ownership
    - do_not_own_cross_domain_inbox
    - assignment_prefer_repo_file

state_hub_managed_repos_map:
  id: uuid
  slug: slug
  name: name
  domain_id: domain_link
  local_path: primary_local_path
  host_paths: host_paths
  remote_url: remote_url
  description: description
  status: lifecycle
  git_fingerprint: git_fingerprint
  category: classification.category
  secondary_domains: classification.secondary_domains
  capability_tags: classification.capability_tags
  business_stake: classification.business_stake
  business_mechanics: classification.business_mechanics
  classified_at: classification.classified_at
  classified_by: classification.classified_by
  standard_version: classification.standard_version
  last_state_synced_at: last_state_synced_at
  topic_id: legacy_replace_with_domain_and_tags
  sbom_source: inventory_signal
  last_sbom_at: inventory_signal

open_questions:
  - uuid_writeback_field_names
  - agent_assignment_file_format
  - multi_remote_support
  - monorepo_packaging