docs: establish INTENT/SCOPE and activate RMGR-WP-0001
Strengthen Intent and Scope for State Hub registration and HelixForge boundaries; mark foundation workplan active. Classification synced via register-from-classification (do not re-run statehub register bootstrap — it collides with RMGR-WP-0001).
This commit is contained in:
parent
c845ffdc0d
commit
e3fbdbc148
4 changed files with 132 additions and 60 deletions
162
INTENT.md
162
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`).
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
|
|
|
|||
21
SCOPE.md
21
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
|
||||
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue