Skip to content

docs(adr): propose ADR-038 — dmon-home moves to its own repository - #113

Merged
ThatRendle merged 1 commit into
mainfrom
docs/adr-038-dmon-home-own-repo
Sep 8, 2026
Merged

ThatRendle merged 1 commit into
mainfrom
docs/adr-038-dmon-home-own-repo

Conversation

@ThatRendle

Copy link
Copy Markdown
Contributor

Proposes ADR-038, superseding ADR-037 Decision 1 (the home/ bucket). Docs only.

Status is Proposed deliberately — CLAUDE.md requires a superseding ADR be accepted before the change that implements it. Nothing moves on this PR; merging it records the decision, it does not perform the split.

What it decides

Supersedes ADR-037 D1 only. home/ leaves ADR-025 D2's bucket set and ADR-028 D1's membership, both reverting to their pre-ADR-037 text. ADR-037 D2–D5 are retained in full — gateway-client-not-stdio-host, the dmonium supersession and naming, speech hosting, and arm64-only. None of what dmon-home is depends on which repository holds it.

# Decision
1 dmon-home lives in daemonicai/dmon-home; home/ is removed, along with its two CI jobs, path filters and four Makefile targets
2 Split now; dmonium's retirement follows later, across the repo boundary
3 All three dmon-home capability specs move to the new repo's OpenSpec root
4 home/-specific tech-debt notes move with the code they describe
5 New repo gets its own ADR series from ADR-001
6 The ADR-012 gw sub-protocol is the entire cross-repo contract

Decision 6 is the one not asked for but needed: no source sharing, no vendored copies, no build-time dependency either way. It is enforceable rather than aspirational, because the client already checks wire compatibility on connect and refuses on mismatch — so a protocol break surfaces as a named runtime refusal, which is the only cross-repo signal a split can offer.

D1 was not wrong

The ADR is explicit about this. D1 weighed home/ against other buckets, because a separate repository was not among the options at the time. Its actual arguments — don't file a Swift client beside .NET protocol surfaces, or beside the product it replaces — are satisfied more completely by a separate repository. It answered a narrower question than the one now being asked, and the record should say so rather than imply a reversal.

The precondition that makes the split safe is new: the two-language seam is now demonstrated, not assumed. All four live verifications passed in #111, including the Keychain round trip and the auth contract against Dmon.Network — the two that no test could close.

What the split costs, stated in the ADR

  • ADR-037 D3's parity obligation becomes unenforceable by any build. Nine of ten children are still unbuilt. The ADR names who owns the retirement (dmon-core, since the code being deleted is here) and requires a retirement proposal to cite the parity evidence rather than assert it.
  • The cross-boundary defect class gets harder to see. The provisioning race took a live run of both processes to find, and no test in either repository could have caught it. Afterwards there is no build in which both sides exist.
  • The stale-binary trap gets worse, not better — nothing will rebuild ndmon and the app together.

A hazard found while drafting

daemonicai/dmon-home already exists at an initial commit — README stub, OpenSpec root, base skills — so this is a migration into a scaffolded repo, not a creation. It already carries a byte-identical copy of PRD.md. Two copies of the product's requirements document now exist with nothing keeping them in step, and ADR-037 D1's description of home/PRD.md as the bucket's founding member is exactly what makes the duplicate look legitimate in both places. The ADR requires the migration to resolve it to one copy.

Open questions for review

  • Who fixes the provisioning race, and therefore where its note ends up. It straddles the boundary. This wants deciding before the split, because afterwards the two candidate fixes live in different repositories.
  • Whether the new repo adopts this repo's apply workflow. It currently has the base OpenSpec skills only — no .claude/agents/, no CLAUDE.md — so the Architect-and-three-agents loop is not available there today. A scaffolding step, not a default.

Follow-ups on acceptance

ADR-037 needs a pointer to ADR-038, and the adr-index skill needs a row plus a count bump (CLAUDE.md carries the same count). Note this repo already has drift of exactly that kind — ADR-013 reads Accepted while the index says superseded — already filed in tech-debt/docs-drift-pass.md, so it is left alone here rather than half-fixed.

🤖 Generated with Claude Code

https://claude.ai/code/session_01BQq4d6ApWMxjLzJMPtLyt4

Supersedes ADR-037 Decision 1 (the home/ bucket) and reverts its amendments
to ADR-025 D2 and ADR-028 D1. Retains ADR-037 D2-D5 in full: none of what
dmon-home *is* depends on which repository holds it.

Status is Proposed — a superseding ADR must be accepted before the change
that implements it.

Records the Product Owner's four calls: split now with dmonium's retirement
following cross-repo; all three dmon-home capability specs move; home-specific
tech-debt notes move with the code they describe; and the new repository gets
its own ADR series from ADR-001, which makes the pending ADR-037 D4 speech
reversal a decision to write there rather than here.

daemonicai/dmon-home already exists at an initial commit, so this is a
migration into a scaffolded repository rather than a creation. It already
carries a byte-identical copy of PRD.md; the ADR requires the migration to
resolve that to one copy, since nothing keeps the two in step.

Also states what the split costs rather than only what it gains: ADR-037 D3's
parity obligation becomes unenforceable by any build, the cross-boundary defect
class already found (the provisioning race) becomes discoverable only by running
both processes, and the ADR-012 gw sub-protocol becomes the sole contract
between two repositories rather than an internal seam.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BQq4d6ApWMxjLzJMPtLyt4
@ThatRendle
ThatRendle merged commit ff13f88 into main Sep 8, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant