Rocky Superproject Topology

ELI5

Rocky-hq is like a city hall: it governs but does not run shops itself. Each shop (console, ralph, hearth, contracts, algo) is an independent business with its own keys and rulebook, the city only owns the zoning map (registry.yaml) and the citywide policies (AGENTS.xml, MILESTONES.md). Visit a shop to learn how it works; visit city hall to learn who is allowed to open one.

Technical Deep Dive

Repository layout

The parent rocky-hq repo (this superproject) hosts no implementation language at all — Phase 3a explicitly “lifted” RALPH out so “zero Python at parent scope” became invariant (README.md:5).

Push-down policy

Per devarno-cloud decision 0004 (inherited): the parent CLAUDE.md is projection-only. Build, test, and runtime instructions live in each submodule’s own CLAUDE.md. The parent repo only carries: README.md, PRODUCT.md, MILESTONES.md, AGENTS.xml, registry.yaml, registry.schema.json, docs/, scripts/, and submodule pointers.

What the parent owns

flowchart TB
    subgraph Parent["rocky-hq (parent — governance only)"]
        REG[registry.yaml<br/>workspaces + tiers]
        AGENTS[AGENTS.xml<br/>PETROVA verbs]
        MILE[MILESTONES.md<br/>phase state]
        DECS[docs/decisions/<br/>append-only]
        SPECS[docs/specs/<br/>system + per-phase]
    end
    subgraph Submodules["submodules (implementation)"]
        CON[console/]
        RAL[ralph/]
        CTR[contracts/]
        HEA[hearth/]
        ALG[algo/]
    end
    Parent -->|points at SHA| Submodules
    PETROVA[petrova-hq] -->|reads AGENTS.xml verbs| Parent
    Parent -->|provision_rocky verb| HEA

Boundaries enforced by AGENTS.xml

The claude-coordinator agent in AGENTS.xml:9 declares <forbidden>any submodule interior (cross-boundary write requires submodule's own agent)</forbidden>. Cross-submodule changes need a parent-level decision plus per-submodule decisions; a parent ref-bump alone is not a handoff (AGENTS.xml:33).

Key Terms

• Superproject → a git repo whose committed content is mostly other repos’ SHAs, plus governance files
• Push-down policy → build/test instructions live in the submodule that contains the build, never at parent scope
• PETROVA → upstream governance system that calls rocky verbs declared in AGENTS.xml
• Lift → moving a codebase into a fresh repo via git subtree split to preserve history (decision 0001 §1)

Q&A

Q: Why does the parent repo carry no Python despite Rocky shipping a Python tool? A: Phase 3a moved the Python prompt-queue runner into ralph/ as a submodule precisely so the parent stays governance-only. Mixing implementation languages at parent scope would re-open the boundary the push-down policy closes.

Q: How is parent-vs-submodule history preserved during a lift? A: Decision 0001 §1 mandates git subtree split. It is slower than a flat copy but preserves commit lineage and the VTM Pass provenance for the seven existing console subsystems.

Q: What governs cross-submodule changes? A: A parent-level decision doc plus per-submodule decisions in each affected child. Submodule PRs land first; the parent ref-bump lands second.

Examples

A bicycle shop chain: head office (parent) keeps the franchise registry, the brand book, and the rule that every shop has a fire extinguisher (tenancy invariant). Each shop (submodule) decides how to stock its tools and what hours to open. Head office never re-stocks a shop directly; it sends a policy memo.