docs(RMGR-WP-0001): complete T01 repository representation model

Define ManagedRepository fields with authority vs projection, declared
record classes, signals, agent roles, and State Hub managed_repos map.

README.md

@@ -17,3 +17,7 @@ agent representation.
 
 Start with [INTENT.md](INTENT.md), [SCOPE.md](SCOPE.md), and the
 [genesis record](history/2026-08-09-genesis.md).
+
+Architecture:
+
+- [Repository representation v0.1](docs/repository-representation_v0.1.md)

docs/repository-representation_v0.1.md

@@ -0,0 +1,347 @@
+---
+id: RMGR-ARCH-REP-0001
+type: architecture
+title: "Repository representation model v0.1"
+status: draft-reviewable
+version: "0.1"
+created: "2026-08-09"
+updated: "2026-08-09"
+workplan_task: RMGR-WP-0001-T01
+related:
+  - INTENT.md
+  - SCOPE.md
+  - docs/repository-representation_v0.1.yaml
+  - prj-state-hub-retirement/architecture/information-model_v0.1.md
+  - the-custodian/canon/standards/repo-classification-standard_v1.0.md
+  - the-custodian/canon/standards/work-record-types_v0.1.md
+---
+
+# Repository representation model v0.1
+
+## Purpose
+
+Define what Repo Manager **means** by a managed repository: identities,
+locations, revisions, classification, declared records, relationships, health,
+lifecycle, and agent roles — and which fields are **authoritative in the
+repository (or forge)** versus **replaceable projections** in Repo Manager.
+
+This is the data-model half of RMGR-WP-0001. Observation/command contracts
+(T02) and extraction from State Hub (T03) build on these field definitions.
+
+Companion machine-readable catalog:
+[`repository-representation_v0.1.yaml`](repository-representation_v0.1.yaml).
+
+---
+
+## Principles
+
+1. **Repository autonomy.** A checkout must remain usable without HelixForge.
+2. **Single authority per fact.** Projections cite `source_ref` + revision.
+3. **Rebuildable indexes.** Dropping the Repo Manager DB must not destroy
+   repo-owned work or classification.
+4. **Contract isolation.** External consumers use versioned DTOs (T02), never
+   raw SQLAlchemy models.
+5. **Signals are not authority.** Health/drift/DoI are recomputable.
+
+---
+
+## Entity: ManagedRepository
+
+The HelixForge representation of one Git repository under management.
+
+### Identity
+
+| Field | Authority | Projection | Notes |
+| --- | --- | --- | --- |
+| `uuid` | **Repo Manager** (minted at first index) | primary key | Stable bookkeeping id; UUIDv7 preferred |
+| `slug` | **Declared** in registration / forge naming | unique key | Lowercase kebab; matches hub `managed_repos.slug` |
+| `name` | **Declared** (display) | cache | Human title; may differ from slug |
+| `forge_repo_id` | **Forge** (Forgejo/Gitea id) | optional cache | External ref `{system, id}` |
+| `remote_url` | **Git remote** / forge | cache | Canonical clone URL or alias (`forgejo-remote:…`) |
+| `default_branch` | **Git / forge** | cache | Observed, not invented |
+
+**Rule:** `slug` is the human primary name; `uuid` is the join key for events
+and FKs. Renames require an explicit alias record + dual-read window.
+
+### Lifecycle
+
+| Status | Meaning |
+| --- | --- |
+| `draft` | Registration incomplete; not fully indexed |
+| `active` | Normal management |
+| `paused` | Temporarily skip automation (operator) |
+| `archived` | Read-only provenance; no normal writes |
+| `retired` | Removed from active fleet; history retained |
+
+Authority for **intent to archive/retire** is human/operator policy; Repo
+Manager records the status as a governed state (command + evidence). Forge
+archive flags are correlated, not blindly copied without a command.
+
+### Purpose and ownership
+
+| Field | Authority | Notes |
+| --- | --- | --- |
+| `description` | **INTENT.md** one-liner (or GOAL.md for `prj-`) | Projection may store copy for search |
+| `intent_uri` | path `INTENT.md` or `GOAL.md` | Relative repo path + git SHA when indexed |
+| `scope_uri` | path `SCOPE.md` | Optional |
+| `owners` | **Declared** (INTENT/AGENTS/CODEOWNERS) | List of human/agent identities — not secrets |
+| `domain` (primary) | **`.repo-classification.yaml`** | Market domain vocabulary |
+| `repo_flavor` | **INTENT frontmatter** or inferred | e.g. `tooling`, `product`, `project` (`prj-`) |
+
+### Classification
+
+Authority: **`.repo-classification.yaml`** (Repo Classification Standard).
+
+| Field | Authority | Projection |
+| --- | --- | --- |
+| `category` | file | cache |
+| `domain` | file | also binds market domain registry |
+| `secondary_domains` | file | cache |
+| `capability_tags` | file | cache |
+| `business_stake` | file | cache |
+| `business_mechanics` | file | cache |
+| `classified_at` / `classified_by` | file | cache |
+| `standard_version` | file | cache |
+
+Invalid classification → registration/index **signal** (error), not silent
+coercion beyond documented normalization.
+
+### Locations and checkouts
+
+| Field | Authority | Projection | Notes |
+| --- | --- | --- | --- |
+| `host_paths` | **Operator registration** | yes | Map `host_id → absolute path` |
+| `primary_local_path` | operator / convention | cache | Workstation convenience; multi-host uses `host_paths` |
+| `worktree_paths` | operator / git | optional | Additional worktrees |
+| `sync_state` | **Observed** (git fetch/status) | yes | dirty/clean, ahead/behind — signal-like |
+
+**Rule:** Host paths are **not** in Git. They are operator configuration with
+audit (who registered which path). Lost host map does not lose repo authority.
+
+### Revisions and fingerprints
+
+| Field | Authority | Projection |
+| --- | --- | --- |
+| `head_sha` | **Git** at observation time | cache |
+| `git_fingerprint` | derived from remotes/HEAD | cache (State Hub field today) |
+| `observed_at` | Repo Manager clock | yes |
+| `last_state_synced_at` | Repo Manager reconciliation | yes |
+
+Work-record index rows bind to `content_hash` or `git_sha` of the source file
+revision, not only “latest HEAD”.
+
+---
+
+## Declared records (indexed)
+
+These are **repository-owned files** Repo Manager discovers and indexes.
+Authority is always the file (+ Git history). The index row is a projection.
+
+| Record class | Typical paths | Work-record kind / note |
+| --- | --- | --- |
+| Workplan | `workplans/*.md` | `workplan` |
+| Task (in workplan) | task blocks in WP | `task` |
+| Intake | intakes / AWQ paths per repo convention | `intake` |
+| Decision | decisions / DEC docs | `decision` |
+| Engagement | engagements | `engagement` |
+| Register entry | risks, TD, EP, ADR, CAP, … | `register-entry` |
+| Ad-hoc tasks | `workplans/ADHOC-*.md` | `task` |
+| Classification | `.repo-classification.yaml` | knowledge/entity |
+| Intent/Goal | `INTENT.md` / `GOAL.md` | knowledge |
+| Contribution artefacts | `contrib/**` | knowledge / contrib convention |
+| Capability registry entries | `registry/capabilities/**` | knowledge |
+| SBOM / lockfiles | lockfiles, sbom outputs | inventory knowledge |
+| Agent instructions | `AGENTS.md`, `.claude/rules` | knowledge (not work) |
+
+### Index projection spine (every indexed work record)
+
+Aligned with fleet work-record spine:
+
+| Field | Source |
+| --- | --- |
+| `id` (canonical name) | frontmatter / block |
+| `uuid` | minted at first index; **writeback** to file when governed |
+| `kind` | registry |
+| `status` | file (reconciled) |
+| `owner` | file |
+| `repo_slug` / `repo_uuid` | anchor |
+| `source_path` | relative path |
+| `source_revision` | git SHA or content hash |
+| `lane` | file or default |
+| `indexed_at` | projection |
+| `drift` | signal if file ≠ index |
+
+**Writeback rule:** UUID and hub ids may be written into frontmatter only via
+**governed command** (T02), never silent agent DB edits without Git evidence.
+
+---
+
+## Relationships
+
+| Relation | Authority | Notes |
+| --- | --- | --- |
+| `member_of` domain | classification primary domain | Secondary domains as tags |
+| `depends_on` workplan | workplan dependency blocks / frontmatter | First-class edges in index |
+| `child_of` task→workplan | task block location | |
+| `promoted_from` | intake/work links | |
+| `related_repo` | declared in SCOPE/INTENT/docs | Optional graph; not inferred only from imports without policy |
+| `extracts_from` / `replaces` | migration docs | e.g. state-hub → repo-manager capabilities |
+
+Cross-repo dependencies that are **coordination truth** live in workplan files;
+Repo Manager indexes them. Hub-core may project a fleet graph from those facts.
+
+---
+
+## Health, maturity, and attention (signals)
+
+All **derived** unless an operator pins an override (override is then a governed
+annotation, not a silent replacement of the formula).
+
+| Signal | Typical inputs | Materialize? |
+| --- | --- | --- |
+| `consistency_ok` | C-rules / file vs index | yes (open findings) |
+| `classification_valid` | allowed vocab | yes on fail |
+| `sync_dirty` | git status | optional TTL |
+| `doi` / attention score | DoI engine inputs | optional cache |
+| `sbom_stale` | lockfile mtime vs last ingest | optional |
+| `needs_human` | task flags in files/index | project from work records |
+| `drift_count` | open findings | yes |
+
+Signals feed hub-core orientation; they must not become the only store of work
+status.
+
+---
+
+## Agent representation (coach / lead / director)
+
+| Role | Meaning | Authority for assignment |
+| --- | --- | --- |
+| **coach** | Improves quality, orientation, day-to-day agent hygiene for the repo | Operator / policy file (e.g. AGENTS.md or registry) |
+| **lead** | Coordinates active workplans and priorities for the repo | same |
+| **director** | Escalation, cross-repo alignment, human bridge | same |
+
+Stored as projection:
+
+```yaml
+agent_assignments:
+  coach: agt-…
+  lead: agt-…
+  director: agt-…
+```
+
+**Not** authority for:
+
+- merging PRs without forge review policy;
+- cross-domain inbox routing (hub-core);
+- inventing workplans without files.
+
+Assignments may live in a repo file (preferred) or operator registry; if only
+in DB, they are **weak** and must be exportable.
+
+---
+
+## Commands and evidence (representation hooks)
+
+Commands themselves are T02. Representation requires:
+
+| Field | Meaning |
+| --- | --- |
+| `accepted_commands` | Catalog of command types this repo allows |
+| `last_command_id` | Correlation to command log |
+| `last_command_result` | success/fail + git SHA evidence |
+
+Evidence of mutation: **Git commit SHA** (and optional PR url) is the primary
+proof; DB rows are secondary.
+
+---
+
+## Mapping from State Hub `managed_repos` (today)
+
+| State Hub column | Model field | Target authority |
+| --- | --- | --- |
+| `id` | `uuid` | RM mint |
+| `slug` / `name` | identity | declared + forge |
+| `domain_id` | domain link | classification domain |
+| `local_path` / `host_paths` | locations | operator |
+| `remote_url` | remote | git/forge |
+| `description` | purpose | INTENT/GOAL |
+| `status` | lifecycle | governed |
+| `git_fingerprint` | fingerprint | observed |
+| `category` + classification cols | classification | `.repo-classification.yaml` |
+| `last_state_synced_at` | sync timestamp | RM |
+| `topic_id` | **legacy** | replace with domain + tags (see inventory) |
+| `sbom_*` | inventory signals | lockfiles + ingest job |
+
+Workplans/tasks/decisions remain **file-backed**; State Hub tables for those
+are indexes to migrate here (T03), not new authorities.
+
+---
+
+## Minimal JSON sketch (contract-facing)
+
+Illustrative only — normative schemas in T02:
+
+```json
+{
+  "uuid": "…",
+  "slug": "repo-manager",
+  "name": "repo-manager",
+  "lifecycle": "active",
+  "domain": "infotech",
+  "classification": {
+    "category": "tooling",
+    "secondary_domains": ["agents"],
+    "capability_tags": ["platform", "coordination"]
+  },
+  "purpose": {
+    "description": "…",
+    "intent_path": "INTENT.md",
+    "intent_sha": "…"
+  },
+  "locations": {
+    "remote_url": "forgejo-remote:coulomb/repo-manager.git",
+    "host_paths": {"bnt-lap001": "/home/worsch/repo-manager"}
+  },
+  "revision": {
+    "head_sha": "…",
+    "observed_at": "…"
+  },
+  "agents": {
+    "coach": null,
+    "lead": null,
+    "director": null
+  },
+  "signals": {
+    "consistency_ok": true,
+    "open_findings": 0
+  },
+  "index": {
+    "workplan_count": 1,
+    "last_reconciled_at": "…"
+  }
+}
+```
+
+---
+
+## Open questions (T02/T04)
+
+1. **UUID writeback field names** — retire `state_hub_*_id` naming in favor of
+   neutral `repo_manager_*` / `helix_*` during migration.
+2. **Agent assignment file format** — extend AGENTS.md vs dedicated YAML.
+3. **Multi-remote repos** — primary remote only vs full remote set.
+4. **Monorepo packaging** — one ManagedRepository vs nested packages (v0.1:
+   one Git repo = one ManagedRepository).
+
+---
+
+## Acceptance (T01)
+
+- [x] Identity, locations, revisions, classification specified  
+- [x] Declared records listed with authority = files  
+- [x] Relationships catalogued  
+- [x] Health/signals marked derived  
+- [x] Coach/lead/director roles defined without superseding human ownership  
+- [x] Authority vs projection explicit per field family  
+- [x] Machine-readable companion YAML  
+- [x] State Hub column mapping for extraction (T03)  

docs/repository-representation_v0.1.yaml

@@ -0,0 +1,232 @@
+# 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

workplans/RMGR-WP-0001-foundation.md

@@ -33,7 +33,7 @@ vertical slice, coordinated by the State Hub retirement project
 
 ```task
 id: RMGR-WP-0001-T01
-status: todo
+status: done
 priority: high
 state_hub_task_id: "43468b5c-f49f-43c3-bf30-922fadc1f8c0"
 ```
@@ -43,6 +43,10 @@ declared records, relationships, health, lifecycle, and coach/lead/director
 agent assignments. Identify which fields are authoritative in the repository
 and which are replaceable projections.
 
+**Result (2026-08-09):** `docs/repository-representation_v0.1.md` + YAML
+catalog (RMGR-ARCH-REP-0001). Authority vs projection per field family; declared
+records; signals; agent roles; State Hub `managed_repos` column map for T03.
+
 ## Define observation and command contracts
 
 ```task