coulomb/repo-manager
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

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

Browse source 
Define ManagedRepository fields with authority vs projection, declared
record classes, signals, agent roles, and State Hub managed_repos map.
This commit is contained in:
tegwick 2026-08-09 22:01:58 +02:00
parent 4aa810179d
commit 14b3ae55b7
4 changed files with 588 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

4
README.md
View file

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

347
docs/repository-representation_v0.1.md Normal file
View file

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

232
docs/repository-representation_v0.1.yaml Normal file
View file

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

6
workplans/RMGR-WP-0001-foundation.md
View file

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