Seed Repo Manager foundation

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`.