CLAUDE.md: one-owner rule for every rule the engine, server, client or theme evaluates #233

New issue

Closed

opened 2026-10-12 18:30:07 +02:00 by dominik.polakovics · 0 comments

dominik.polakovics commented

2026-10-12 18:30:07 +02:00

Owner

Why

#230 was a rule ("what is left of an items owner's children once the rows are out, and is it serializable") implemented twice: the save path merged the leftover text, the body GET did not, and the editor could not open a hand-authored text-media with two images. A sweep of the repo found the same shape in a dozen other places (see the drift audit issue): a predicate over schemas, shortcodes, params or front matter re-derived in a second package, in the web client, or in a theme partial, with no shared source of truth and no test tying the copies together. Several copies already disagree.

The two existing CLAUDE.md rules (AGENTS.md tracks the engine, skills track the engine) stop the docs from drifting from the code. Nothing stops the code from drifting from itself.

Change

Add a third rule to CLAUDE.md: every rule has exactly one owner.

A change that needs a rule the code already evaluates somewhere calls that owner, or moves the owner to where both callers can reach it. It never adds a sibling implementation.
A rule the web client or a theme partial needs is served by the server (a verdict in the payload, like the summary roles already are) or pinned by a fixture both suites load (the internal/pagepath/testdata pattern). A client or theme mirror with no fixture is incomplete.
A comment saying "same as X" or "mirrors X" is a defect marker, not a contract: it names a second copy.
When planning or reviewing: list every rule the change touches and name its owner, exactly as the skills rule asks for the affected skills.

No code changes; the rule applies from the next change on. The existing duplicates are tracked in the audit issue.

## Why #230 was a rule ("what is left of an items owner's children once the rows are out, and is it serializable") implemented twice: the save path merged the leftover text, the body GET did not, and the editor could not open a hand-authored text-media with two images. A sweep of the repo found the same shape in a dozen other places (see the drift audit issue): a predicate over schemas, shortcodes, params or front matter re-derived in a second package, in the web client, or in a theme partial, with no shared source of truth and no test tying the copies together. Several copies already disagree. The two existing CLAUDE.md rules (AGENTS.md tracks the engine, skills track the engine) stop the docs from drifting from the code. Nothing stops the code from drifting from itself. ## Change Add a third rule to CLAUDE.md: every rule has exactly one owner. - A change that needs a rule the code already evaluates somewhere calls that owner, or moves the owner to where both callers can reach it. It never adds a sibling implementation. - A rule the web client or a theme partial needs is served by the server (a verdict in the payload, like the summary roles already are) or pinned by a fixture both suites load (the `internal/pagepath/testdata` pattern). A client or theme mirror with no fixture is incomplete. - A comment saying "same as X" or "mirrors X" is a defect marker, not a contract: it names a second copy. - When planning or reviewing: list every rule the change touches and name its owner, exactly as the skills rule asks for the affected skills. No code changes; the rule applies from the next change on. The existing duplicates are tracked in the audit issue.

dominik.polakovics added the

enhancement

label

2026-10-12 18:30:07 +02:00

dominik.polakovics referenced this issue from a commit

2026-10-12 18:30:33 +02:00

docs(claude): every rule has exactly one owner

dominik.polakovics referenced this issue

2026-10-12 18:31:54 +02:00

Drift audit: rules implemented twice across engine, server, client and theme #234

dominik.polakovics referenced this issue from a pull request that will close it,

2026-10-12 18:36:48 +02:00