Skip to content

docs: domain-model.md ownership should be System Architect, not Software Engineer #104

@nullhack

Description

@nullhack

Problem

The current AGENTS.md contains a contradiction in domain model ownership that breaks the closed-loop architecture principle (SA designs → SE builds → SA reviews).

In the Roles section, it states:

System Architect (SA) — Owns docs/domain-model.md, docs/system.md, and docs/adr/ADR-*.md.

And in Step 1 — SCOPE / Stage 1 — Discovery:

PO reads domain-model.md but never writes to it — entity suggestions go in discovery.md for SA formalization at Step 2

However, there is no explicit rule preventing the Software Engineer (SE) from modifying domain-model.md during implementation. In practice, if the SE writes domain stubs during Step 3, it opens the door to inadvertently editing the domain model — violating SA ownership. The domain model is an architecture artifact, not an implementation artifact.

Expected Behavior

The domain-model.md file should be exclusively owned by the System Architect, with the following rules enforced:

  1. SA creates and updates domain-model.md during Step 2 (ARCH).
  2. SE reads domain-model.md for implementation guidance but never modifies it.
  3. PO reads domain-model.md during discovery but never modifies it.
  4. If the SE discovers a domain inconsistency during implementation, they escalate to the SA (via WORK.md or a new ADR), rather than editing the domain model directly.

This aligns with:

  • The closed-loop principle: the same mind that designed the architecture verifies it.
  • ISO/IEC/IEEE 42010:2022: architecture descriptions are first-class artifacts owned by architects.
  • Decision-centric architecture: domain knowledge decays when ownership is blurred.

Suggested Fix

Update AGENTS.md to explicitly state:

  • In the SE role description: "SE reads docs/domain-model.md for implementation guidance but never modifies it. Domain inconsistencies are escalated to the SA."
  • In the Step 2 description: Clarify that "write domain stubs" means the SA writes the initial .py stub files (or the SE writes them under SA direction), but the domain-model.md itself remains SA-owned.
  • Optionally, add a Domain Model Chain of Responsibility table similar to the .feature file chain of responsibility.

References

  • AGENTS.md, lines 52, 119, 165
  • Closed-loop principle: AGENTS.md, line 42

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions