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

---
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)