diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..e4e0199 --- /dev/null +++ b/.gitignore @@ -0,0 +1,5 @@ +# state-hub: track .claude/rules +# Claude Code local state (track shared rules; ignore machine-specific files) +.claude/* +!.claude/rules/ +!.claude/rules/*.md diff --git a/.repo-classification.yaml b/.repo-classification.yaml new file mode 100644 index 0000000..a398d3c --- /dev/null +++ b/.repo-classification.yaml @@ -0,0 +1,25 @@ +repo_classification: + standard: Repo Classification Standard + version: "1.0" + classified_at: "2026-08-09" + classified_by: human + category: tooling + domain: infotech + secondary_domains: + - agents + capability_tags: + - platform + - coordination + - orchestration + - governance + business_stake: + - technology + - execution + business_mechanics: + - coordination + - control + - operation + notes: >- + Long-lived functional component providing the repository integration, + representation, reconciliation, and governed-control boundary for + HelixForge. Not a domain hub. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..3666454 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,208 @@ +# repo-manager — Agent Instructions + +## Repo Identity + +**Purpose:** Repository representation, file-backed record indexing, +reconciliation, governed repository control, and coach/lead/director agent +roles for HelixForge. + +**Domain:** infotech +**Repo slug:** repo-manager +**Topic ID:** `cee7bedf-2b48-46ef-8601-006474f2ad7a` +**Workplan prefix:** `RMGR-WP-` + +--- + +## State Hub Integration + +The Custodian State Hub tracks work across all domains. Codex uses HTTP REST and +the `statehub` CLI by default. MCP is opt-in because the current Codex MCP bridge +adds severe call latency; the full administrative MCP surface remains available +to clients that need it. + +| Context | URL | +|---------|-----| +| Local workstation | `http://127.0.0.1:8000` | +| Remote via tunnel | `http://127.0.0.1:18000` | +| Optional local edge relay | http://127.0.0.1:18080 | + +When an operator has enabled the edge relay, set API_BASE to the relay URL. +Queueable writes return an explicit queued receipt if the central hub is +unreachable. Treat that as pending local evidence, then ask the operator to run +statehub outbox status/replay after connectivity returns. + +Codex workspace-write sandboxes need network access enabled to reach the host's +loopback listener. Bootstrap this once with `make -C ~/state-hub configure-codex` +and restart Codex. The canonical REST health endpoint is `/state/health`, not +`/health`. If a sandboxed loopback probe fails, retry it with escalated execution +before declaring State Hub unavailable; a managed Codex permission profile may +still enforce isolated networking. Experimental MCP can be enabled explicitly +with `make -C ~/state-hub configure-codex WITH_MCP=1`. + +### Orient at session start + +```bash +# Offline brief — works without hub connection +cat .custodian-brief.md + +# Active workplans for this domain +curl -s "http://127.0.0.1:8000/workplans/?topic_id=cee7bedf-2b48-46ef-8601-006474f2ad7a&status=active" \ + | python3 -m json.tool + +# Check inbox +curl -s "http://127.0.0.1:8000/messages/?to_agent=repo-manager&unread_only=true" \ + | python3 -m json.tool +``` + +Mark a message read: +```bash +curl -s -X PATCH "http://127.0.0.1:8000/messages//read" \ + -H "Content-Type: application/json" -d '{}' +``` + +### Log progress (required at session close) + +```bash +curl -s -X POST http://127.0.0.1:8000/progress/ \ + -H "Content-Type: application/json" \ + -d '{ + "summary": "what was done", + "event_type": "note", + "author": "codex", + "workplan_id": "", + "task_id": "" + }' +``` + +Omit `workplan_id` / `task_id` when not applicable. + +### Update task status + +```bash +curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ + -H "Content-Type: application/json" \ + -d '{"status": "progress"}' +# values: wait | todo | progress | done | cancel +``` + +### Flag a task for human review + +```bash +curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ + -H "Content-Type: application/json" \ + -d '{"needs_human": true, "intervention_note": "reason"}' +``` + +--- + +## Session Protocol + +**Start:** +1. `cat .custodian-brief.md` — domain goal and open workplans (offline-safe) +2. Check inbox: `GET /messages/?to_agent=repo-manager&unread_only=true`; mark read +3. Scan workplans: `ls workplans/` — note `status: ready`, `active`, or `blocked` files and open tasks +4. Check human-needed tasks: `GET /tasks/?needs_human=true` + +**During work:** +- Update task statuses in workplan files as tasks progress +- Record significant decisions via `POST /decisions/` + +**Close:** +1. Update workplan file task statuses to reflect progress +2. If finishing a workplan: hand off **residuals** as live work records first + (intake with `origin: residual` + `origin_ref: `, or a next workplan / + decision / engagement). Do not park leftovers only in prose or `SCOPE.md`. + Canon: `the-custodian/canon/standards/work-record-types_v0.1.md` § Residuals. +3. Log: `POST /progress/` with a summary of what changed (name handoff ids) +4. After workplan file changes, run: + ```bash + statehub fix-consistency + ``` + Coding agents should run this directly; ask the operator only if the CLI or + State Hub API is unavailable. This syncs task status from files into the hub DB. + +--- + +Before requesting credentials or access, use `warden route find "" --json`. +Repo Manager never stores secret values in repository records, State Hub, +workplans, logs, or chat. + + + + +Read `INTENT.md`, `SCOPE.md`, and `history/2026-08-09-genesis.md` before +changing architectural boundaries. Repository files remain authoritative; +database state is a replaceable projection. Observation and governed control +belong to this component, while cross-entity messaging belongs to hub-core. + +--- + +## Workplan Convention (ADR-001) + +Work items originate as files in this repo — not in the hub. The hub is a +read/cache/index layer that rebuilds from files. + +**File location:** `workplans/RMGR-WP-NNNN-.md` + +**Archived location:** finished workplans may move to +`workplans/archived/YYMMDD-RMGR-WP-NNNN-.md`. The `YYMMDD` prefix is +the completion/archive date; the frontmatter `id` does not change. + +**Ad Hoc Tasks:** small opportunistic fixes discovered during a session use +`workplans/ADHOC-YYYY-MM-DD.md` with task ids `ADHOC-YYYY-MM-DD-T01`, etc. Use +this only for low-risk work completed directly; create a normal workplan for +anything needing analysis, design, approval, dependencies, or multiple phases. + +**Frontmatter:** + +```yaml +--- +id: RMGR-WP-NNNN +type: workplan +title: "..." +domain: infotech +repo: repo-manager +status: proposed | ready | active | blocked | backlog | finished | archived +owner: codex +topic_slug: ... +created: "YYYY-MM-DD" +updated: "YYYY-MM-DD" +state_hub_workstream_id: "" # fix-consistency — do not edit (legacy field name; workplan UUID) +--- +``` + +Use `proposed` for a new draft, `ready` after review against current repo +state, and `finished` after implementation. `stalled` and `needs_review` are +derived health labels, not frontmatter statuses. + +**Terminology:** workplan is the fleet term; `workstream` appears only in legacy +API/MCP/frontmatter bridges until `STATE-WP-0069` retires them — see +`the-custodian/canon/standards/workplan-terminology-fleet_v0.1.md`. + +**Task block format** (one per `##` section): + +``` +## Task Title + +` ` `task +id: RMGR-WP-NNNN-T01 +status: wait | todo | progress | done | cancel +priority: high | medium | low +state_hub_task_id: "" # written by fix-consistency — do not edit +` ` ` + +Task description text. +``` + +Status progression: `todo` → `progress` → `done`; use `wait` for waiting/blocked work and `cancel` for stopped work. + +**Residuals when finishing:** actionable leftovers become live work records +before `status: finished` — usually an intake (`origin: residual`, +`origin_ref: RMGR-WP-NNNN`) or a spawned workplan. Residual is a *role*, +not a kind. Fleet list lives on State Hub, not in `SCOPE.md`. + +To create a new workplan: +1. Write the file following the format above +2. Run `statehub fix-consistency` locally; ask the operator only if the CLI or + State Hub API is unavailable. diff --git a/INTENT.md b/INTENT.md new file mode 100644 index 0000000..4de21e8 --- /dev/null +++ b/INTENT.md @@ -0,0 +1,101 @@ +--- +domain: infotech +repo: repo-manager +updated: "2026-08-09" +--- + +# Intent + +## Why Repo Manager exists + +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. + +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. + +## 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. + +## Repository representation + +Every managed repository receives a durable HelixForge representation that can +include: + +- stable identity, ownership, purpose, classification, and lifecycle; +- local checkouts, remotes, revisions, branches, and synchronization 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. + +The agent roles represent the repository in HelixForge. They do not supersede +human ownership, repository policy, code review, 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. + +- `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. + +## What success looks like + +A repository can join 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; +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. + +No repository should require direct connections to every HelixForge service or +library 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. + +## 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`. diff --git a/README.md b/README.md index c80eccd..5a1d227 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,12 @@ # repo-manager -Repository integration layer to the helic-forge agentic software factory and operations facility. \ No newline at end of file +Repository integration boundary for the HelixForge agentic software development +and operations environment. + +Repositories remain independently valid and usable. Repo Manager gives each +repository a stable representation inside HelixForge, observes its declared +state, performs governed repository changes, and hosts its coach/lead/director +agent representation. + +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 new file mode 100644 index 0000000..7145268 --- /dev/null +++ b/SCOPE.md @@ -0,0 +1,40 @@ +# Scope + +## In scope + +- Repository registration, identity, classification, and lifecycle. +- Local checkout, host-path, remote, revision, and synchronization awareness. +- Discovery, parsing, validation, and indexing of repository-owned records. +- Workplan, task, decision, capability, service, policy, and relationship + declarations when their authoritative form is stored in a repository. +- Consistency reconciliation between files and replaceable projections. +- 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. + +## Out of scope + +- Cross-domain inboxes, conversations, and message routing: `hub-core`. +- General work or issues without a repository authority: work/issue component. +- Recurring scheduling and workflow execution: `activity-core`. +- Authentication, user directories, and identity proofing: identity authorities. +- Authorization policy decisions: `flex-auth` or its successor. +- Credential custody: OpenBao/platform credential services. +- Git hosting: Forgejo or another source-code forge. +- Domain-specific operational, financial, security, or governance truth. +- A universal knowledge store or search engine. + +## Initial extraction source + +The first implementation may reuse proven State Hub behavior for repository +registration, host paths, workplan parsing, consistency reconciliation, and +file-backed status changes. Extraction must preserve behavior with compatibility +tests while removing assumptions that Repo Manager owns cross-domain state. + +## API boundary + +External consumers use versioned contracts. They must not depend on Repo +Manager's persistence schema. Commands distinguish requested action from +confirmed repository state; a successful command is not complete until the +resulting repository revision and normalized event are recorded. diff --git a/WORK-RECORDS.md b/WORK-RECORDS.md new file mode 100644 index 0000000..3a1e37e --- /dev/null +++ b/WORK-RECORDS.md @@ -0,0 +1,16 @@ +# Work Records — repo-manager + +> Generated by `statehub fix-consistency` (CUST-WP-0061-T04, work-record +> stage 3). Do not edit by hand — edit the source file/block listed for +> each record and re-run fix-consistency to refresh this index. Archived +> workplans are omitted; closed decisions/intakes/engagements stay listed +> so recently-resolved work is still visible. [auto] + +| Kind | ID | Status | Lane | Source | +| --- | --- | --- | --- | --- | +| workplan | RMGR-WP-0001 | proposed | — | workplans/RMGR-WP-0001-foundation.md | +| task | RMGR-WP-0001-T01 | todo | — | workplans/RMGR-WP-0001-foundation.md | +| task | RMGR-WP-0001-T02 | todo | — | workplans/RMGR-WP-0001-foundation.md | +| task | RMGR-WP-0001-T03 | todo | — | workplans/RMGR-WP-0001-foundation.md | +| task | RMGR-WP-0001-T04 | todo | — | workplans/RMGR-WP-0001-foundation.md | +| task | RMGR-WP-0001-T05 | todo | — | workplans/RMGR-WP-0001-foundation.md | diff --git a/history/2026-08-09-genesis.md b/history/2026-08-09-genesis.md new file mode 100644 index 0000000..6b71f77 --- /dev/null +++ b/history/2026-08-09-genesis.md @@ -0,0 +1,84 @@ +# Genesis of Repo Manager + +**Recorded:** 2026-08-09 +**Origin project:** `prj-state-hub-retirement` + +## Background + +State Hub began as a useful live coordination and read-model service around +repository-backed workplans. Over time it accumulated repository registration, +workplans and tasks, decisions, messaging, progress, capability workflows, +service catalogs, SBOM data, telemetry, suggestions, execution controls, +operational projections, and dashboard aggregation. + +This proved the value of file-backed work records and shared agent orientation, +but it also mixed repository integration, cross-domain information flow, and +several domain-specific projections in one service. + +A broader Inter-Hub framework was then attempted in Haskell/IHP. Its concepts— +domain hubs, manifests, widgets, events, and an operator surface—were useful, +but its implementation and build path were too specialized. A Python/FastAPI +replacement named `core-hub` was subsequently deployed, while a reusable +library named `hub-core` was extracted from State Hub. The resulting three-way +division worked technically but left confusing names and no complete extension +or information-architecture model. + +In August 2026 the direction was reset: + +1. consolidate and retire `core-hub` into the surviving `hub-core` framework; +2. make hub-core the cross-domain control and interaction plane; +3. establish domain hubs around explicit Orthogonal Architecture concerns; +4. retire State Hub rather than rename its remainder as another hub; and +5. extract repository integration into a dedicated functional component. + +## Why observation and control stay together + +An early formulation separated `repo-state` from `repo-control`. This was +rejected. Both concern the same boundary: connecting a repository that must +remain perfectly viable on its own to HelixForge. + +Repo Manager therefore owns both: + +- the evidence-backed representation of repository state; and +- governed actions that intentionally change repository-owned records. + +These remain internally separable modules, but not independent ecosystem +authorities. + +## Agent representation + +Repo Manager is more than a Git inventory. Each repository obtains a +representation inside HelixForge and may be assigned coach, lead, and director +agents. These roles help orient work, maintain quality and alignment, coordinate +dependencies, and escalate decisions. Their actions remain constrained by +repository policy, hub-core identity and authorization, and normal review +mechanisms. + +## Relationship to the information architecture + +Repository facts are only one part of HelixForge information flow. Users, +agents, services, domains, work, conversations, knowledge, telemetry, and costs +also need stable identity and communication. Cross-entity messaging and +interaction therefore belong to hub-core and its supporting components, not to +Repo Manager. + +Repo Manager publishes repository facts and accepts repository commands through +those shared contracts. It should not connect directly to every domain hub or +functional service. + +## Migration source + +Useful State Hub implementation should be extracted rather than rewritten +blindly. Candidate source capabilities include: + +- managed repository and host-path registration; +- repository file discovery; +- workplan and task parsing; +- consistency and reconciliation tooling; +- repository dependency and goal projections; +- controlled file-backed status transitions; and +- idempotency and local outbox patterns. + +Cross-domain messages, general progress telemetry, capability federation, +scheduling, and domain projections are intentionally excluded from the new +component. diff --git a/workplans/RMGR-WP-0001-foundation.md b/workplans/RMGR-WP-0001-foundation.md new file mode 100644 index 0000000..12c1c17 --- /dev/null +++ b/workplans/RMGR-WP-0001-foundation.md @@ -0,0 +1,95 @@ +--- +id: RMGR-WP-0001 +type: workplan +title: "Repo Manager architecture and foundation" +domain: infotech +repo: repo-manager +status: proposed +owner: codex +topic_slug: repo-manager +created: "2026-08-09" +updated: "2026-08-09" +state_hub_workstream_id: "e32a9d49-a38f-4117-8e37-1c66afe1dad1" +--- + +# Repo Manager architecture and foundation + +## Goal + +Turn the repository genesis and scope into an implementable contract and first +vertical slice, coordinated by the State Hub retirement project. + +## Define the repository representation + +```task +id: RMGR-WP-0001-T01 +status: todo +priority: high +state_hub_task_id: "43468b5c-f49f-43c3-bf30-922fadc1f8c0" +``` + +Specify stable repository identity, locations, revisions, classifications, +declared records, relationships, health, lifecycle, and coach/lead/director +agent assignments. Identify which fields are authoritative in the repository +and which are replaceable projections. + +## Define observation and command contracts + +```task +id: RMGR-WP-0001-T02 +status: todo +priority: high +state_hub_task_id: "2453316f-33f4-41d0-bcb5-c7552db88d68" +``` + +Define normalized repository facts, governed commands, authorization context, +idempotency, correlation, evidence, failure behavior, and hub-core integration +without exposing persistence models. + +## Inventory extraction candidates + +```task +id: RMGR-WP-0001-T03 +status: todo +priority: high +state_hub_task_id: "deee10be-25e1-4ee7-b47e-93dc816916c9" +``` + +Map relevant State Hub repository registration, host-path, workplan parsing, +consistency, reconciliation, dependency, file-mutation, and outbox behavior to +keep/adapt/replace/retire dispositions with compatibility tests. + +## Select the implementation foundation + +```task +id: RMGR-WP-0001-T04 +status: todo +priority: medium +state_hub_task_id: "0a041f4e-09fc-4f69-8a48-ac396186bc8f" +``` + +Choose the runtime, persistence, package, migration, test, and deployment shape +consistent with the ordinary HelixForge platform. Record the decision before +substantial implementation. + +## Prove one repository end to end + +```task +id: RMGR-WP-0001-T05 +status: todo +priority: high +state_hub_task_id: "5036a248-1c47-423f-be8d-4fd232896c31" +``` + +Register and represent one independently valid repository, index its declared +work, emit a normalized change through hub-core contracts, apply one authorized +file-backed transition, and prove the resulting Git evidence and rebuilt +projection. + +## Acceptance + +- [ ] The authority and data model are explicit. +- [ ] Observation and command contracts are versioned and testable. +- [ ] State Hub extraction candidates have dispositions. +- [ ] The implementation foundation has a recorded decision. +- [ ] One repository completes the end-to-end vertical slice.