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

id	type	title	status	version	created	updated	workplan_task	related
RMGR-ARCH-REP-0001	architecture	Repository representation model v0.1	draft-reviewable	0.1	2026-08-09	2026-08-09	RMGR-WP-0001-T01	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.

---

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:

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:

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

• Identity, locations, revisions, classification specified
• Declared records listed with authority = files
• Relationships catalogued
• Health/signals marked derived
• Coach/lead/director roles defined without superseding human ownership
• Authority vs projection explicit per field family
• Machine-readable companion YAML
• State Hub column mapping for extraction (T03)