DR-017 — Program-level controls

Converted from docs/decisions/DR-017-program-level-controls.md to MADR (backlog B25). The text is unchanged; its sections are grouped under the MADR headings below, in their original order within each group.

Context

1. The suggestion against what we have

Suggestion	What MMDEP already has	Verdict
A program-hub repository as the single map	The MMDEP repository is the program hub: estate C4 model (architecture/workspace.dsl, draft 1), program decisions (DR-001 to DR-017), registers (labels, data sources, components, capacity, flags, jobs), the answers relay, sprint plans, runbooks. The collector reads every project repository	Already done; formalise it as the hub (§2)
Monorepo or git submodules	11 repositories across GitHub and GitLab, with different owners (Ajay owns moneymarche), data classes and CI runners	Reject both. A monorepo can't span GitHub and GitLab owners. Submodules add sync work and break agents. Stay federated (hub and spokes)
One workspace.dsl for all systems	Draft 1 holds the whole estate as software systems and containers	Adopt. Projects keep their own component detail. The hub holds systems, containers and every cross-project relationship (§2)
adrs/program and adrs/projects	Program decisions in MMDEP; project decisions in each project's repository (rules §21, DR-016)	Adapt. Don't copy project ADRs into the hub. The hub collects each project's ADR index (B25's index.json) and shows them all on one site (B29)
tasks-matrix.json cross-project ledger	Cross-project needs travel as ask-<project> issues, relay rows and routing blocks; the MMDEP hub store (SQLite) models tasks and dependencies	Adapt. A hand-edited central JSON goes stale and causes merge conflicts. Put depends_on: [<repo>#<n>] in each routing block. The collector builds the matrix automatically from all repositories (reports/dependencies.json + a page), and the harness skips items whose dependencies are still open (B28)
Runner skips blocked tasks	The harness skips by state and routing today	Adopt through depends_on (B28)
Local MCP filesystem server on the hub	Agents read GitHub; the hosted MMDEP MCP gateway is planned for sprint 3 (DR-014 §6)	Adopt for local agents (Aider, Ollama) now: point it at a read-only hub worktree (B20). Cloud agents get the same through the hosted gateway in sprint 3
Impact analysis before contract changes ("what breaks if…")	Not yet	Adopt. For items with contract: yes or a c4: element, the harness asks Gemini (paid) with workspace.dsl plus the ADR index: which systems and containers depend on this, and which tests to run. The answer goes on the PR, and high-risk items go to workflow (i) (B30)
MkDocs portal compiled by the runner	Planned (B23, B26)	Adopt, built from the hub with all projects' ADR indexes and the C4 views; refreshed after merges and nightly

2. MMDEP as the program hub (the formal part)

The hub owns: - the estate C4 model, at system and container level, with every cross-project relationship; - program decisions; - registers; - the dependency matrix (generated); - the ADR catalogue (generated); - the program site; - Actions; - sprint status.

Each project owns its component-level C4, its own ADRs, its docs/knowledge/ and session logs.

Change rule: a project PR that changes a cross-project relationship (API contract, data flow, shared database) must update the hub's workspace.dsl in a linked MMDEP PR. The collector flags project PRs labelled contract without a hub link.

3. New backlog items (Sonnet)

• B28 depends_on in routing blocks, the dependency matrix, harness skip;
• B29 ADR catalogue across repositories in the site;
• B30 impact analysis for contract items;
• B31 a local MCP filesystem server on a read-only hub worktree for Aider and Ollama.

Options

Not stated separately in the original record.

Decision

4. Decision for Atul

• PRG-1: MMDEP is formally the program hub (federated, no monorepo or submodules); cross-project dependencies are declared in routing blocks and the matrix is generated.

Consequences

Not stated separately in the original record.