diff --git a/INTENT.md b/INTENT.md index 4de21e8..1511458 100644 --- a/INTENT.md +++ b/INTENT.md @@ -1,101 +1,149 @@ --- domain: infotech repo: repo-manager +repo_flavor: tooling updated: "2026-08-09" +parent_project: prj-state-hub-retirement --- -# Intent +# INTENT -## Why Repo Manager exists +> Why `repo-manager` exists, where its authority begins and ends, and how it +> relates to hub-core, State Hub retirement, and ordinary repositories. -HelixForge needs to work with many repositories without making those -repositories dependent on HelixForge internals. A repository must remain -coherent, inspectable, buildable, and governable on its own. At the same time, -HelixForge needs a trustworthy representation of the repository, its declared -work, its relationships, its current condition, and the agents responsible for -helping it evolve. +--- -Repo Manager is that integration boundary. +## One-line intent -It combines repository observation and governed repository control because -they are inseparable parts of the same responsibility. A component that can -observe repository state but cannot safely reconcile it is incomplete; a -component that changes repositories without maintaining an evidence-backed -model of their state is unsafe. +Repo Manager is the HelixForge **repository integration boundary**: it +represents repositories, indexes repository-owned records, reconciles drift, +and applies **governed** repository changes without making repos dependent on +HelixForge internals. + +## Why it exists + +HelixForge must work with many repositories. Each repository must stay +coherent, inspectable, buildable, and governable **on its own**. At the same +time, HelixForge needs a trustworthy representation of the repository, its +declared work, relationships, condition, and the agents that help it evolve. + +Repo Manager is that boundary. It combines **observation** and **governed +control** because they share one authority, policy, identity, and audit surface: +a component that only observes cannot safely reconcile; a component that +mutates without an evidence-backed model is unsafe. + +It is established as part of **State Hub retirement** +(`prj-state-hub-retirement`): repository registration, host paths, workplan +file indexing, consistency reconciliation, and file-backed status writeback +move here from State Hub. Cross-domain messaging, projections, and hub +composition move to **hub-core**, not here. ## Governing principle **The repository remains authoritative for repository-owned records.** Repo Manager discovers, validates, indexes, relates, and—when explicitly -authorized—changes those records. Its database representations are projections -and operational indexes, not replacements for Git or repository files. +authorized—changes those records. Database rows are **projections and +operational indexes**, not replacements for Git or repository files. Indexes +must be rebuildable from authoritative inputs. + +## What it is + +| Area | Responsibility | +| --- | --- | +| Repository registry | Identity, classification, lifecycle, remotes, checkouts, host paths | +| Record indexing | Workplans, tasks, decisions, and other file-backed work records | +| Consistency | Detect and reconcile file ↔ projection drift | +| Governed mutation | Explicit commands with policy checks, evidence, and Git outcomes | +| Agent roles | Coach / lead / director assignment **for a repository** (not hub-wide inbox) | +| Hub-core port | Emit normalized repository and work-record facts; accept addressing via contracts | + +## What it is not + +| Concern | Owner | +| --- | --- | +| Cross-domain messages, conversations, routing | `hub-core` | +| Domain hub composition / extension registry | `hub-core` | +| Progress/orientation projections across domains | `hub-core` | +| Schedules, ops-run execution, event-triggered jobs | `activity-core` | +| Non-repo issues | `issue-core` | +| AuthN / user directory | identity authorities | +| AuthZ decisions | `flex-auth` (or successor) | +| Secrets | OpenBao / credential custody | +| Git hosting | Forgejo (or other forge) | +| Temporary project coordination (`prj-*`) | project repos + their GOAL.md | +| Legacy mixed coordination service | `state-hub` (until retirement gates) | + +Repo Manager is a **functional component**, not a domain hub (Orthogonal +Architecture / SHR hub-extension taxonomy). ## Repository representation -Every managed repository receives a durable HelixForge representation that can -include: +Every managed repository may be represented with: - stable identity, ownership, purpose, classification, and lifecycle; -- local checkouts, remotes, revisions, branches, and synchronization state; +- local checkouts, remotes, revisions, branches, and sync state; - declared workplans, tasks, decisions, capabilities, services, and policies; - relationships to other repositories and external authorities; -- health, maturity, drift, risk, and attention signals; -- an assigned agent representation, including coach, lead, and director roles; -- commands the repository accepts and evidence of their outcomes. +- health, maturity, drift, risk, and attention **signals** (derived); +- coach / lead / director agent assignments; +- accepted commands and outcome evidence. -The agent roles represent the repository in HelixForge. They do not supersede -human ownership, repository policy, code review, or authorization controls. +Agent roles represent the repository inside HelixForge. They do not supersede +human ownership, code review, repository policy, or authorization controls. ## Ecosystem position -Repo Manager is a functional component used by `hub-core`. It is not a domain -hub and does not own cross-domain communication. +```text + repositories (Git + files) + ▲ + │ observe / governed command + ▼ + repo-manager ──port.repo / port.work──► hub-core + │ │ + │ ├── domain hubs + │ └── agents / MCP + └── extracts from state-hub (retirement) +``` -- `hub-core` owns cross-domain identity, addressing, messaging, interaction, - projections, telemetry, policy integration, and domain-hub composition. -- Repo Manager owns the repository integration boundary and emits normalized - repository and work-record facts to hub-core. -- Domain hubs consume repository projections through hub-core rather than - importing Repo Manager internals. -- Specialized authorities such as `activity-core`, `issue-core`, identity - services, and credential systems continue to own their respective execution - and data boundaries. +- **hub-core** addresses repositories through versioned contracts, not SQL. +- **Domain hubs** consume repository projections via hub-core. +- **State Hub** remains operational until cutover; new permanent repo-authority + features should land here (or as dual-run adapters), not as State Hub growth. + +Architecture references (project-owned until promoted): + +- `prj-state-hub-retirement/architecture/information-model_v0.1.md` +- `prj-state-hub-retirement/architecture/hub-extension-architecture_v0.1.md` +- `prj-state-hub-retirement/architecture/child-workplan-map_v0.1.md` (stream S1) ## What success looks like -A repository can join HelixForge by declaring ordinary, versioned files and +A repository joins HelixForge by declaring ordinary versioned files and registration metadata. Repo Manager can then: 1. identify and locate it; -2. explain its purpose, ownership, relationships, and current state; -3. validate and index its repository-owned records; +2. explain purpose, ownership, relationships, and current state; +3. validate and index repository-owned records; 4. assign and expose its agent representation; 5. emit changes through stable hub-core contracts; 6. accept an authorized command and apply it with auditable Git evidence; -7. recover or rebuild its projections from repository sources. +7. recover or rebuild projections from repository sources. -No repository should require direct connections to every HelixForge service or -library to participate. +No repository should require direct connections to every HelixForge service to +participate. ## Design values -- **Repository autonomy:** integration must not make a repository unusable - outside HelixForge. -- **Files and Git as evidence:** repository-owned intent and work remain - inspectable and recoverable. -- **Observation and action together:** reads and writes share one authority, - policy, identity, and audit boundary. -- **Governed mutation:** changes are explicit, scoped, reviewable, and - idempotent where possible. -- **Contract isolation:** other components integrate through stable contracts, - not Repo Manager database models. -- **Graceful degradation:** temporary hub or network failure must not corrupt a - repository or erase pending evidence. -- **Replaceable projections:** indexes can be rebuilt from authoritative inputs. +- **Repository autonomy** — usable outside HelixForge. +- **Files and Git as evidence** — intent and work remain inspectable. +- **Observation and action together** — one boundary for read and write. +- **Governed mutation** — explicit, scoped, reviewable, idempotent where possible. +- **Contract isolation** — no foreign consumers on persistence models. +- **Graceful degradation** — hub outage must not corrupt the repository. +- **Replaceable projections** — rebuild from authority. ## Genesis -Repo Manager originates in the retirement design for the legacy `state-hub`. -The detailed rationale and architectural lineage are recorded in -`history/2026-08-09-genesis.md`. +Recorded in `history/2026-08-09-genesis.md`. Implementation workplan: +`RMGR-WP-0001` (parent project `SHR-WP-0001`). diff --git a/README.md b/README.md index 5a1d227..2163e9a 100644 --- a/README.md +++ b/README.md @@ -8,5 +8,12 @@ repository a stable representation inside HelixForge, observes its declared state, performs governed repository changes, and hosts its coach/lead/director agent representation. +| | | +| --- | --- | +| **Flavor** | tooling (not a domain hub) | +| **Domain** | infotech | +| **Parent project** | [prj-state-hub-retirement](../prj-state-hub-retirement) | +| **Foundation WP** | [RMGR-WP-0001](workplans/RMGR-WP-0001-foundation.md) | + Start with [INTENT.md](INTENT.md), [SCOPE.md](SCOPE.md), and the [genesis record](history/2026-08-09-genesis.md). diff --git a/SCOPE.md b/SCOPE.md index 7145268..e27b129 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -1,5 +1,11 @@ # Scope +## One-liner + +Long-lived **tooling** component: repository representation, file-backed record +indexing, consistency reconciliation, and governed repository control for +HelixForge. + ## In scope - Repository registration, identity, classification, and lifecycle. @@ -11,12 +17,13 @@ - Controlled repository mutation through explicit commands and policy checks. - Repository event emission, idempotency, audit evidence, and recovery. - Repository-specific coach, lead, and director agent assignments. -- APIs and adapters through which hub-core addresses repositories. +- APIs and adapters through which hub-core addresses repositories + (`port.repo`, `port.work` in the extension architecture). ## Out of scope - Cross-domain inboxes, conversations, and message routing: `hub-core`. -- General work or issues without a repository authority: work/issue component. +- General work or issues without a repository authority: `issue-core`. - Recurring scheduling and workflow execution: `activity-core`. - Authentication, user directories, and identity proofing: identity authorities. - Authorization policy decisions: `flex-auth` or its successor. @@ -24,6 +31,16 @@ - Git hosting: Forgejo or another source-code forge. - Domain-specific operational, financial, security, or governance truth. - A universal knowledge store or search engine. +- Hosting production domain-hub business data or operator consoles. + +## Coordination + +| Item | Location | +| --- | --- | +| Parent project | `prj-state-hub-retirement` | +| Stream | S1 in `architecture/child-workplan-map_v0.1.md` | +| Foundation workplan | `RMGR-WP-0001` | +| Disposition inventory | `prj-state-hub-retirement/inventory/` (repo-* capabilities) | ## Initial extraction source diff --git a/workplans/RMGR-WP-0001-foundation.md b/workplans/RMGR-WP-0001-foundation.md index cf26b15..a16573c 100644 --- a/workplans/RMGR-WP-0001-foundation.md +++ b/workplans/RMGR-WP-0001-foundation.md @@ -4,7 +4,7 @@ type: workplan title: "Repo Manager architecture and foundation" domain: infotech repo: repo-manager -status: proposed +status: active owner: codex topic_slug: repo-manager created: "2026-08-09"