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..40e7afc --- /dev/null +++ b/.repo-classification.yaml @@ -0,0 +1,26 @@ +repo_classification: + standard: Repo Classification Standard + version: "1.0" + classified_at: "2026-08-09" + classified_by: human + category: project + domain: infotech + secondary_domains: + - agents + capability_tags: + - platform + - orchestration + - coordination + - governance + business_stake: + - technology + - execution + - intelligence + business_mechanics: + - coordination + - control + - adaptation + notes: >- + Temporary prj-flavor repository coordinating hub-core consolidation, + Repo Manager establishment, information-architecture work, and complete + State Hub retirement. Archive when GOAL.md retirement gates are met. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..229451c --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,222 @@ +# prj-state-hub-retirement — Agent Instructions + +## Repo Identity + +**Purpose:** Temporary cross-repository project for consolidating hub-core, +establishing Repo Manager and the HelixForge information architecture, and +retiring State Hub with accepted evidence. + +**Domain:** infotech +**Repo slug:** prj-state-hub-retirement +**Topic ID:** `cee7bedf-2b48-46ef-8601-006474f2ad7a` +**Workplan prefix:** `SHR-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=prj-state-hub-retirement&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=prj-state-hub-retirement&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`. +Never record secret values in project files, State Hub, workplans, evidence, or +chat. + + + + +## Project protocol + +This is a temporary project repository. It has `GOAL.md`, not `INTENT.md`. + +At session start, read in this order: + +1. `GOAL.md` — outcome, invariants, success gates, and retirement conditions. +2. `SCOPE.md` — project authority and implementation boundaries. +3. `history/2026-08-09-genesis.md` — architectural lineage. +4. `workplans/SHR-WP-0001-foundation.md` and any later active workplans. + +Implementation remains in the affected functional repositories. This project +owns architecture, decisions, sequencing, dependencies, migration ledgers, +risks, gates, and consolidated evidence. Link child workplans by stable ID; do +not copy their task lists here. + +The project is complete only when every `GOAL.md` retirement condition has +accepted evidence and all residual work has a live owner outside this repo. + +--- + +## 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/SHR-WP-NNNN-.md` + +**Archived location:** finished workplans may move to +`workplans/archived/YYMMDD-SHR-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: SHR-WP-NNNN +type: workplan +title: "..." +domain: infotech +repo: prj-state-hub-retirement +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: SHR-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: SHR-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/GOAL.md b/GOAL.md new file mode 100644 index 0000000..a965753 --- /dev/null +++ b/GOAL.md @@ -0,0 +1,88 @@ +--- +repo: prj-state-hub-retirement +repo_flavor: project +project_status: active +started: "2026-08-09" +reviewed: "2026-08-09" +--- + +# Project goal + +## Outcome + +Establish a coherent HelixForge information architecture and hub framework that +can replace State Hub without losing repository authority, coordination +history, operational evidence, or agent usability. + +The project will: + +1. consolidate the deployed `core-hub` runtime into the surviving `hub-core` + repository and retire `core-hub`; +2. define hub-core as the cross-domain identity, addressing, interaction, + messaging, projection, telemetry, policy-integration, and domain-extension + framework; +3. establish `repo-manager` as the repository representation, agent-role, + indexing, reconciliation, and governed-control component; +4. define an implementable Orthogonal Architecture extension model for domain + hubs; +5. assign every State Hub capability, API, dataset, and consumer to one explicit + destination or retirement decision; +6. migrate consumers and historical evidence without creating competing + authorities; and +7. retire State Hub completely. + +## Architectural invariants + +- Repositories remain valid and usable independently of HelixForge. +- Repository-owned files and Git history remain authoritative for + repository-owned records. +- Repo Manager combines repository observation and governed control. +- Cross-entity communication belongs to hub-core, not Repo Manager. +- Domain hubs represent domains or orthogonal aspects; infrastructure + components are not called hubs merely because they support the framework. +- Specialized services retain execution and data authority behind explicit + contracts. +- Message transport, durable interaction, work commitments, knowledge, and + telemetry remain distinct information kinds with correlated identities. +- Migration is incremental and evidence-backed; no big-bang rewrite. + +## Success gates + +The project goal is achieved only when all of the following are true: + +- A canonical information model defines entities, relations, events, signals, + messages, conversations, requests, work, decisions, knowledge, and telemetry. +- A versioned hub/domain-extension contract implements the relevant Orthogonal + Architecture concepts and has a conformance suite. +- Hub-core contains the production runtime, contracts, SDK, extension registry, + and compatibility surface required by active consumers. +- Production traffic formerly served by `core-hub` runs from the consolidated + hub-core implementation; the old repository is archived. +- Repo Manager represents repositories end to end, including file-backed work + records, consistency, agent roles, change events, and governed mutations. +- Every State Hub route, model, dataset, background job, MCP tool, dashboard, + and known consumer has a recorded keep/move/replace/retire disposition. +- All retained State Hub capabilities operate through their new owners with + compatibility, data-count, provenance, authorization, and failure-mode tests. +- State Hub receives no normal reads or writes during an agreed stabilization + window. +- Backup, restore, rollback, and historical-query evidence has been accepted. +- State Hub is stopped and its repository and final data are archived read-only. + +## Project retirement + +This repository is temporary. It can be retired when: + +1. every success gate above has accepted evidence; +2. all unfinished residuals have live owners and work records outside this + repository; +3. project decisions and final architecture have been promoted to their durable + canonical repositories; +4. child workplans are finished, cancelled with rationale, or handed off; +5. the final project report identifies the deployed revisions, migrations, + archived assets, remaining operational obligations, and rollback expiry; +6. the repository is marked completed and made read-only after a final + consistency and link check. + +Retirement means archival, not deletion. The repository remains available as +the provenance record for why and how State Hub was replaced. diff --git a/README.md b/README.md index 0d8bbd5..6c8dc92 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,12 @@ # prj-state-hub-retirement -Projectmanagement repository for replacing state-hub with the new hub-core based infrastructure of Orthogonal Architecture Framework conforman domain-hubs. \ No newline at end of file +Temporary project repository for replacing State Hub with a consolidated +hub-core information and interaction framework, Repo Manager, and +Orthogonal-Architecture-conformant domain hubs. + +The project is governed by [GOAL.md](GOAL.md). Its background, boundaries, and +first delivery plan are recorded in [history/2026-08-09-genesis.md](history/2026-08-09-genesis.md), +[SCOPE.md](SCOPE.md), and [SHR-WP-0001](workplans/SHR-WP-0001-foundation.md). + +This repository is designed to be retired when the goal and retirement gates +are satisfied. diff --git a/SCOPE.md b/SCOPE.md new file mode 100644 index 0000000..c82dd9c --- /dev/null +++ b/SCOPE.md @@ -0,0 +1,51 @@ +# Scope + +## Project authority + +This repository owns the cross-repository project goal, target architecture, +decisions, sequencing, dependency map, migration ledger, risks, acceptance +gates, and consolidated evidence for State Hub retirement. + +It does not own the production implementations being changed. + +## Participating repositories + +Initial participants include: + +- `hub-core` +- `core-hub` +- `state-hub` +- `repo-manager` +- `activity-core` +- `issue-core` +- `the-custodian` +- `ops-hub` +- `fin-hub` +- identity, authorization, audit, and knowledge components as their boundaries + are resolved + +## In scope + +- Repository-flavor and temporary-project conventions. +- HelixForge information architecture and authority model. +- Orthogonal Architecture extension contracts and conformance. +- Core-hub-to-hub-core consolidation and cutover. +- Repo Manager foundation and State Hub repository-capability extraction. +- State Hub capability, data, consumer, and integration inventory. +- Cross-repository implementation sequencing and acceptance gates. +- Compatibility adapters, migration evidence, rollback, and retirement. + +## Out of scope + +- Hosting production implementation code in this project repository. +- Replacing child-repository workplans with duplicate project tasks. +- Becoming a permanent portfolio database, message system, or knowledge store. +- Rewriting specialized services whose authority remains valid. +- Deleting historical repositories or evidence. + +## Work-record rule + +The project records milestones, dependencies, gates, decisions, and cross-repo +acceptance. Each participating repository owns its implementation workplan and +evidence. Project records link those workplans by stable identifier rather than +copying their task lists. diff --git a/WORK-RECORDS.md b/WORK-RECORDS.md new file mode 100644 index 0000000..3a946a9 --- /dev/null +++ b/WORK-RECORDS.md @@ -0,0 +1,17 @@ +# Work Records — prj-state-hub-retirement + +> 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 | SHR-WP-0001 | proposed | — | workplans/SHR-WP-0001-foundation.md | +| task | SHR-WP-0001-T01 | todo | — | workplans/SHR-WP-0001-foundation.md | +| task | SHR-WP-0001-T02 | todo | — | workplans/SHR-WP-0001-foundation.md | +| task | SHR-WP-0001-T03 | todo | — | workplans/SHR-WP-0001-foundation.md | +| task | SHR-WP-0001-T04 | todo | — | workplans/SHR-WP-0001-foundation.md | +| task | SHR-WP-0001-T05 | todo | — | workplans/SHR-WP-0001-foundation.md | +| task | SHR-WP-0001-T06 | todo | — | workplans/SHR-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..ec959c9 --- /dev/null +++ b/history/2026-08-09-genesis.md @@ -0,0 +1,53 @@ +# Project genesis + +**Recorded:** 2026-08-09 + +## Starting condition + +State Hub had grown from a useful repository-backed work coordination service +into a broad system containing development records, messages, progress, +capability workflows, service and third-party catalogs, telemetry, execution +controls, and cross-domain projections. The breadth made orientation and +authority boundaries increasingly difficult. + +An earlier architecture proposed domain hubs around a shared framework and an +Orthogonal Architecture Standard. The second-generation Inter-Hub runtime was +implemented in Haskell/IHP but proved operationally too specialized. A +third-generation Python/FastAPI `core-hub` replacement was deployed, while +generic primitives were extracted into a separate `hub-core` library. + +This successfully retired the Haskell production path, but left three problems: + +- `core-hub` and `hub-core` split one conceptual framework across confusingly + named repositories; +- the Orthogonal Architecture Standard remained mostly documentary rather than + an executable extension and information model; and +- State Hub retained a large mixture of repository, cross-domain, and + domain-specific responsibilities. + +## Direction established + +The project begins from the following direction: + +- consolidate `core-hub` into `hub-core` and make hub-core the surviving + cross-domain framework and runtime; +- build domain hubs through explicit extension contracts rather than a mesh of + direct service dependencies; +- keep specialized authorities such as identity, authorization, scheduling, + issues, audit, and finance behind delegated ports; +- create Repo Manager as the complete repository integration boundary; +- move cross-entity communication and information flow into hub-core and its + supporting components; and +- retire State Hub completely once every capability and consumer has an + evidence-backed disposition. + +## Why a project repository + +The work spans many repositories and changes their relationships. No single +functional repository should own the transformation plan. This repository is +therefore the first proposed `prj-` repository flavor: a temporary, +outcome-oriented coordination and provenance surface. + +It owns the project goal and gates while implementation remains local to the +affected repositories. When the outcome is achieved and durable decisions have +moved to their permanent homes, this repository is archived. diff --git a/workplans/SHR-WP-0001-foundation.md b/workplans/SHR-WP-0001-foundation.md new file mode 100644 index 0000000..be0312c --- /dev/null +++ b/workplans/SHR-WP-0001-foundation.md @@ -0,0 +1,109 @@ +--- +id: SHR-WP-0001 +type: workplan +title: "Project foundation and architecture baseline" +domain: infotech +repo: prj-state-hub-retirement +status: proposed +owner: codex +topic_slug: state-hub-retirement +created: "2026-08-09" +updated: "2026-08-09" +state_hub_workstream_id: "8498db77-cbe1-48ff-b7f0-03b933f0aa8a" +--- + +# Project foundation and architecture baseline + +## Goal + +Establish the durable project conventions, evidence inventories, architecture +decisions, and child-repository workplan map required before implementation +migration begins. + +## Confirm the project-repository convention + +```task +id: SHR-WP-0001-T01 +status: todo +priority: high +state_hub_task_id: "528ed9c9-57a6-4f44-b1cf-9d2c1a5cbca4" +``` + +Define the `prj-` repository flavor, lifecycle, required files, authority +boundary, and archive procedure in the Custodian canon. Confirm that project +repositories use `GOAL.md` rather than durable-product `INTENT.md`. + +## Inventory State Hub + +```task +id: SHR-WP-0001-T02 +status: todo +priority: high +state_hub_task_id: "f19351e4-c922-417c-bcc7-746a2cd7fe52" +``` + +Produce machine-readable inventories of State Hub routes, models, migrations, +jobs, MCP tools, dashboard views, datasets, callers, and operational +dependencies. Give every item an initial owner and keep/move/replace/retire +disposition. + +## Define the information architecture + +```task +id: SHR-WP-0001-T03 +status: todo +priority: high +state_hub_task_id: "65e522c7-2550-4187-a308-a23a2bae7615" +``` + +Define canonical entities and relations plus the distinct semantics of events, +signals, messages, conversations, requests, work, decisions, knowledge, and +telemetry. Specify correlation, authority, provenance, sensitivity, retention, +cost attribution, and transformation rules. + +## Define the hub and extension architecture + +```task +id: SHR-WP-0001-T04 +status: todo +priority: high +state_hub_task_id: "90e8350a-8a1c-4f46-a545-69c9cf00e6d1" +``` + +Revise the Orthogonal Architecture material into an implementable hub-core and +domain-extension contract. Define domain hubs, functional components, +authoritative services, projections, adapters, and conformance requirements. + +## Establish the child-workplan map + +```task +id: SHR-WP-0001-T05 +status: todo +priority: high +state_hub_task_id: "1fc9da32-14ed-46b6-a965-b2477414df78" +``` + +Create or identify local implementation workplans in `repo-manager`, +`hub-core`, `core-hub`, `state-hub`, and other affected repositories. Record +dependencies and project gates without duplicating their tasks here. + +## Baseline migration and retirement acceptance + +```task +id: SHR-WP-0001-T06 +status: todo +priority: medium +state_hub_task_id: "d793f242-999c-47ad-86f2-6d972cc20b84" +``` + +Record baseline row counts, callers, availability expectations, recovery paths, +and historical-evidence requirements. Turn the success and retirement clauses +in `GOAL.md` into executable or evidence-backed gates. + +## Acceptance + +- [ ] The `prj-` flavor has a durable canonical definition. +- [ ] State Hub has a complete disposition inventory. +- [ ] The information and extension architectures are reviewable. +- [ ] Each implementation stream has one local owner and workplan. +- [ ] Migration and retirement gates have measurable evidence requirements.