prj-state-hub-retirement/GOAL.md

repo	repo_flavor	project_status	started	reviewed
prj-state-hub-retirement	project	active	2026-08-09	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.