docs: single source of truth in the honesty rules (ADR 0022)

[vpciii]

Summary

Names the single source of truth principle in the "keep the artifacts honest" rules — the gap the opn-mcp drift incident exposed. Cuts 0.11.0.

The honesty rules bound code↔doc coupling (docs change in the same PR) but never named doc↔doc / code↔code duplication — one fact hand-copied into two places that drift. That's exactly how the opn-mcp scheduled-task prompts went stale: a canonical skill and a setup-guide template duplicated the same prompt; an update touched only one. The same-PR rule didn't fire, the same-model reviewer (ADR 0021) missed it, CI had nothing to check — the cross-model adversarial review caught it retrospectively.

The rule

A fact lives in one place. If it must exist in two — a generated artifact, a mirrored summary, a copy a tool requires — the copy is generated from or machine-checked against the source, never kept in sync by memory. Duplication of a hand-maintained fact is a review smell.

The methodology already practices this for its own mirrors (global-CLAUDE.md, the .mdc; ADR 0018) — this states the principle so consuming projects have a guard to apply.

Changes

• New ADR 0022.
• methodology.md "Keep the artifacts honest" gains the item; the global-CLAUDE.md and methodology.mdc summaries updated in the same PR (ADR 0018).
• CHANGELOG cut to 0.11.0 (rolls in the already-merged adversarial-review trial entry).

Adoption: reference-only; optionally add an equality/codegen check where a project has known duplication. Forward-only.

Companion: the concrete instance — single-sourcing the opn-mcp scheduled-task prompts — ships as its own ADR + PR in that repo.

Post-merge: tag v0.11.0; copy templates/global-CLAUDE.md → ~/.claude/CLAUDE.md (ADR 0018).

🤖 Generated with Claude Code

[claude]

Claude finished @vpciii's task in 2m 18s —— View job

---

Review — single source of truth (ADR 0022)

• Read governing artifacts (ADRs 0018/0020/0021, methodology.md, CHANGELOG)
• Review diff against this project's standards
• Check doc↔doc consistency (the PR's own subject)
• Post review

The mechanics are clean: ADR 0022 numbers correctly (0021 was the prior max), Status: Accepted / Deciders: vpc match house style, dates line up (ADR + 0.11.0 both 2026-06-20), the CHANGELOG is well-formed (compare links correct, adversarial-review entry rolled into 0.11.0 as the body states), and the conventional-commit docs: is right. The three mirrors — methodology.md, global-CLAUDE.md, methodology.mdc — are updated in the same PR and say the same thing, so the change practices ADR 0018 on itself. One substantive thing to resolve before merge.

The new rule indicts the methodology's own flagship mirror

methodology.md:145-150 lists "a mirrored summary" as a sanctioned second location, then requires that the copy be "generated from or machine-checked against the source, never kept in sync by memory."

But the methodology's own mirrored summary — templates/global-CLAUDE.md vs methodology.md — is exactly "kept in sync by memory." ADR 0018 rejected generating it and binds it solely by same-PR editorial discipline:

0018, Alternatives considered (lines 50–55): "Generate the summary from methodology.md — rejected: the summary is a curated abridgment … If drift recurs despite the same-PR rule, revisit as a CI check … not a generator."

So the one example the rule names as legitimate ("a mirrored summary") is, in this repo, synced by precisely the mechanism the rule forbids. Two concrete consequences:

1. ADR 0022 contradicts accepted ADR 0018. The References section calls 0018 "the global summary as a generated/mirrored copy — the principle already in practice." It is not generated — 0018 explicitly rejected generation. As written, the new ADR cites 0018 as evidence for a property 0018 declined to adopt. (adr/0022-single-source-of-truth.md, References)

2. The absolutist wording over-reaches. "never kept in sync by memory" makes global-CLAUDE.md, methodology.mdc, and the deployed ~/.claude/CLAUDE.md review smells under the methodology's own rule. The "mild tension" paragraph in Consequences only covers convenience value-copies ("a self-contained doc that repeats a value for readability"), not same-PR-bound mirrors — the central case.

This is on-topic, not pedantic: it's the same doc↔doc reasoning the PR is about, applied to the PR itself.

Suggested resolution — name the third sync mechanism the methodology already relies on. The honest set is generated, machine-checked, or bound by the same-PR honesty rule (ADR 0018/0020). Something like: "…the copy is generated from, machine-checked against, or bound to the source in the same PR (ADR 0018) — never left to drift between PRs." Then fix the 0022 reference to drop "generated" for 0018 (it's a same-PR-mirrored copy, with a CI equality check held in reserve). Fix this →

Everything else checks out. Your call on whether to tighten the wording or accept the residual tension explicitly — but as written the ADR states something ADR 0018 declined, so at minimum the "generated" reference to 0018 should go.