repo-manager/SCOPE.md

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.
• 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 (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: 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.
• 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.
• 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

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.

Implemented local reuse surfaces

• rmgr sync --path <checkout> --push is the normal file-record closeout: assign missing deterministic identifiers, verify the pushed Forgejo revision and primary checkout, then request central reconciliation. A queued receipt remains pending; repository files remain authoritative.
• rmgr provenance install configures the shared hook directory. The current .githooks/pre-commit composes the Custodian generated-only commit guard with staged-secret detection for its explicit checkout allowlist. It preserves the provenance hooks; local hooks remain bypassable.
• The generated-only guard implementation belongs to the-custodian/scripts/check_generated_only_commit.py. Sharing this hook does not generate indexes, prove fleet generator adoption, or prove a week without standalone generated commits (CUST-WP-0079-T05).
• registry/capabilities/capability.security.repository-secret-prevention.md declares the bounded source/CLI capability for reuse-surface. Its local checkout coverage and discovery maturity are distinct from fleet enforcement.

Per-repository Make targets and build pipelines own their generated artifacts. Repository reconciliation and hook installation do not transfer that ownership or establish a general generated-file pipeline.

Staged work-record generator adoption

The tracked .generated-work-records.json opts this repository into the shared pre-commit generation lane. make generated-work-records uses the isolated .generated-work-records.mk recipe and the Custodian adapter to render from staged Markdown with the existing State Hub renderer. make generated-work-records-check verifies the staged result without writes. Unstaged source edits are preserved; unstaged generated-file edits and unresolved conflicts stop the commit. The existing generated-only guard and secret scan remain in place. This adoption covers WORK-RECORDS.md only; other owner indexes retain their own generators. It makes no schedule or public-release change.

Local orientation brief

.custodian-brief.md is a generated local orientation snapshot. It remains on disk for offline use and is root-ignored rather than versioned. Regenerate it with the State Hub brief renderer; workplans and other authored repository records remain authoritative. Brief refreshes must not create Git commits.

Offline pinned work-record export

python -m repo_manager.fleet_snapshot exports only workplan and decision Markdown from explicitly pinned local Git commits into a new completion-marked directory with per-file hashes. It performs no fetch, checkout, Hub write, scheduling or pruning and does not assert freshness. See docs/custodian-fleet-input-contract.md for the proposed owner publication, consumer admission and retention contract. Runtime publication, freshness enforcement and consumer acceptance remain unimplemented.

rmgr freshness run --repos <comma-separated-set> optionally targets an exact active repository set using the existing Forge/Hub verification and receipts. Missing active repositories or limits smaller than the set fail closed; partial budget/failure results still require caller coverage checks. This does not install the disabled schedule or add any credential, transport or producer.

The runtime has a default-disabled fixed-policy Custodian snapshot endpoint, reusing existing Forge read settings and targeted native freshness receipts. It prepares bounded exact-commit workplan/decision bundles, not a general file service. It is not deployed or admitted to Activity Core. Producer cancellation, combined daily timing, receiver integration and reviewed downstream private-source access remain unfinished; see docs/custodian-fleet-input-contract.md.