From 14b3ae55b79992bc4cdbf766bf24b8d9bc0c0147 Mon Sep 17 00:00:00 2001 From: tegwick Date: Sun, 9 Aug 2026 22:01:58 +0200 Subject: [PATCH] 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 | 4 + docs/repository-representation_v0.1.md | 347 +++++++++++++++++++++++ docs/repository-representation_v0.1.yaml | 232 +++++++++++++++ workplans/RMGR-WP-0001-foundation.md | 6 +- 4 files changed, 588 insertions(+), 1 deletion(-) create mode 100644 docs/repository-representation_v0.1.md create mode 100644 docs/repository-representation_v0.1.yaml diff --git a/README.md b/README.md index 2163e9a..ef59ad6 100644 --- a/README.md +++ b/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) diff --git a/docs/repository-representation_v0.1.md b/docs/repository-representation_v0.1.md new file mode 100644 index 0000000..9348fb9 --- /dev/null +++ b/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) diff --git a/docs/repository-representation_v0.1.yaml b/docs/repository-representation_v0.1.yaml new file mode 100644 index 0000000..a41bd21 --- /dev/null +++ b/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 diff --git a/workplans/RMGR-WP-0001-foundation.md b/workplans/RMGR-WP-0001-foundation.md index a16573c..49b77e4 100644 --- a/workplans/RMGR-WP-0001-foundation.md +++ b/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