Skip to content

DR-001: Code repository vs. estate knowledge repository

Converted from docs/decisions/DR-001-code-vs-estate-repo.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 question and the trigger

Question. Where should the orchestrator's estate knowledge — docs/spec/, docs/decisions/, docs/research/, docs/status/ and (from iteration 5, §14A) estate/reports/ — live, versus its code? Today both live in this one repository, mmdep.

Trigger (spec §10, §16A: "a second person working on the orchestrator, a remote runner, or the online gateway"). Two of those three are now met:

  1. The online gateway (spec 0.9, §15A) starts in iteration 3, not iteration 5 — it will read a snapshot of specs, items, status and board data and, later, accept connector sign-ins from chat apps. That snapshot has to come from somewhere, and today "somewhere" is this repository.
  2. mmdep was pushed to a real forge. After item #40, git remote -v shows: 
    github  https://github.com/moneymarche-dev/MMDEP.git (fetch)
github  https://github.com/moneymarche-dev/MMDEP.git (push)
    The repository is no longer local-only, so "which repo does a connector or a person point at" is no longer hypothetical.

2. Evidence

  • Forge and push. main and tags pushed to moneymarche-dev/MMDEP (private), ruleset active (item #40, Atul: "Pushed main and tags to moneymarche-dev/MMDEP; main ruleset active.", 2026-09-28).
  • What's tracked today. git ls-files lists 58 files. A targeted check for hub state or secret-shaped filenames (mmdep\.db, mmdep_hub, workspaces/, .env, credentials, .pem, id_rsa, .key) matched zero files — confirmed this session, before this record was written.
  • What's mixed together today. Design spec (docs/spec/000-orchestrator-design.md), iteration plans and status (docs/iterations/, docs/status/), research notes (docs/research/) and (from this turn) decision records (docs/decisions/) all sit next to mmdep/'s source code, in the same repo, on the same forge, under the same branch protection.
  • The existing authority. Spec §1 already names the MMDEP governance repository (GitLab, money-marche-group/money-marche-digital-engineering-program) as "the authority" for "programme requirements, standards, cross-project decisions, authorization records" — a role that overlaps with what docs/spec/, docs/decisions/ and docs/research/ hold today.
  • Forge friction already seen on GitLab. The GitLab runner is blocked on an exhausted compute quota (item #22, still open), and MR fetch/view failed authentication (turn 2, git fetch origin for MoneyMarche). Not disqualifying, but relevant to option (c)'s lock-in.

Options

3. Options

Option Set-up cost Monthly/maintenance Capability Risk Lock-in
(a) mmdep holds both (status quo) None None Simplest: one place to read spec, decisions and the code that implements them together — good while it's one person A gateway or future connector scoped to "read the estate docs" can't be scoped away from the code sitting right next to them in the same repo; blast radius grows as the gateway (iteration 3) and any read connector are added Low — a later split is a clean git filter-repo/subtree extraction at any point
(b) A separate estate repo (e.g. mmdep-estate) holding docs/spec/, docs/decisions/, docs/research/, docs/status/ (and estate/reports/ from §14A); mmdep keeps code plus per-iteration status One new repo, protected; a one-time migration and updated cross-links A second repo to keep green (link checks) and in sync with code changes Matches §12A's three-layer model directly — "estate" is already meant to be separable from any one project; a gateway/connector needs read access to one small docs repo, never the code Two repos to review together when a spec change and its implementing code land at the same time; migration has a small one-time risk of broken links Low
(c) The MMDEP governance repo (GitLab) No new repo; migration to an existing repo on a different forge Estate docs now reviewed under GitLab's process, code under GitHub's Matches spec §1's stated authority most literally — that repo already is "the authority" for standards and cross-project decisions Cross-forge split: code on GitHub, design spec on GitLab, so mmdep docs check (§12A) and any snapshot/export tooling needs two sets of forge credentials; the gateway's read connector would need GitLab access too, separate from GitHub; GitLab compute-quota and auth issues already seen (#22, #24) Medium — ties estate content to GitLab specifically, and to the TEM-convergence decision (§19) resolving in GitLab's favour

4. Recommendation (PROPOSED; not the option chosen, kept as the record)

Option (b), a separate mmdep-estate repository, over (c), for now:

  • §12A's own wording — "estate documents... Programme (Atul)... Lives in: MMDEP governance repo, or the estate knowledge repo (see the §10 repository profile decision)" — already anticipates exactly this choice, and doesn't require it to be the governance repo.
  • It gets the real benefit (a gateway or connector can be granted read access to specs/decisions/status without ever touching source code) without adding a second forge and a second credential set to everything that currently only has to deal with GitHub.
  • It stays compatible with moving to (c) later: if the TEM-convergence decision (§19) resolves this orchestrator into the technology-estate-manager repository's world, mmdep-estate's content is a clean, self-contained thing to fold into GitLab governance at that point — it doesn't have to be decided twice.

This is a proposal only. Atul decides.

Decision

5. The decision and its owner

Decided by Atul in item #47 (2026-10-03): option (c).

  • Estate knowledge lives in the GitLab MMDEP governance repo: standards, ADRs, the decision register, the estate register, and estate reports.
  • The orchestrator's code stays in its own repository: GitHub moneymarche-dev/MMDEP for now.
  • Recorded with it:
  • The orchestrator's code was pushed to GitHub after item #40: main and tags went to moneymarche-dev/MMDEP, first push b6ccc10, 2026-09-28.
  • An ADR amending ADR-001 allows GitHub for the orchestrator and Portfolio Engine. It is drafted as ADR-005 in docs/decisions/gitlab-drafts/ (spec 0.10, item #59), for Atul to submit to the governance repo.
  • Correction to §2 and the checklist: #40's "ruleset active" isn't enforced. A private repository on GitHub Free doesn't enforce rulesets (#56). Until enforced protection is decided, main on GitHub is guarded by drift detection and convention (spec 0.10 §9).
  • Spec 0.10 (§10, §12A, §14A) applies this decision.

Consequences

6. Revisit triggers

From the decision (#47):

  • when development phase 2 of the orchestrator starts, which brings the repository protection decision (spec 0.10 §9: GitLab Free or GitHub Pro); or
  • when TEM moves repositories.

The triggers listed before the decision follow; they are kept as the record:

  • A second person works on the orchestrator's own code (needs code access separable from governance-doc access).
  • A remote runner is added (needs a minimal-scope checkout; simpler if estate docs aren't mixed into whatever the code repo grants).
  • The TEM-convergence decision (§19) resolves — it may dictate the repo's final home outright, ahead of this one.
  • GitLab compute-quota or access issues (already seen: #22, #24) recur badly enough to weigh against ever adding GitLab as a second forge dependency (against option (c)).
  • The gateway (G0–G3) reaches the point of granting a connector read access to estate content — the point this record exists to prepare for.

Checklist (this repo, as of this record)

  • [ ] main protected on the forge. Item #40 reported the ruleset as active, but it isn't enforced on a private GitHub Free repository (#56). Drift detection and convention apply meanwhile (spec 0.10 §9).
  • [ ] Connector access is read-only. Not yet applicable — no connector exists yet. G0/G1 must specify a read-only scope/token before G3 builds anything that reaches this repo or its successor; this record is the gate that decision should be checked against.
  • [x] No hub state or secrets tracked. git ls-files (58 files) checked this session against mmdep\.db|mmdep_hub|workspaces/|\.env$|credentials|\.pem$|id_rsa|\.key$ — zero matches.