Mcs Docs Of Record

mcs-docs-of-record

Overview

This repo has two documentation layers that drift independently: narrative docs (README, ARCHITECTURE, CONTRIBUTING) written by hand, and governance docs (pipeline/specs/, pipeline/config/budgets.json) enforced by code. Narrative docs go stale silently because nothing checks them; governance docs are truth because pre-commit hooks and CI read them at runtime. When they disagree, the enforcement code wins, never the prose.

When to use and when NOT to

Use this skill to: locate the doc that owns a fact, resolve a conflict between two docs, fix a stale count, write a handover or design doc in house style, or run the drift audit before a docs PR.

Do NOT use this skill for:

• Skill frontmatter/budget/structure rules themselves. Those live in pipeline/specs/SKILL-GOVERNANCE-SPEC.md; read the spec directly or route to mcs-claude-code-platform for skill-loading mechanics.
• OSS release readiness, novelty claims, licensing posture. Route to mcs-external-positioning.
• Live symptom triage (a hook failing right now). Route to mcs-debugging-playbook.
• Commit/PR gate rules themselves (this skill uses them, does not define them). Route to mcs-change-control.

The doc map

Authority ranking when docs conflict

Highest to lowest. Assert one, do not average:

1. Enforcement code (pipeline/hooks/*.py, .pre-commit-config.yaml, settings.json hook wiring, hooks.json), what actually runs.
2. pipeline/specs/*.md, the versioned, self-declared source of truth for governance numbers.
3. ARCHITECTURE.md, hand-maintained contributor reference, drifts but is second-line for design intent.
4. README.md, user-facing pitch, drifts fastest, lowest authority for factual counts.
5. CLAUDE.md numbers, lowest priority when a number also lives in a spec; treat as summary, not source.

Worked example (verified 2026-07-02): repo CLAUDE.md:57 says "Maximum simultaneous context load: ≤5,000 tokens" under a heading titled "Hard Limits". pipeline/config/budgets.json:11 and pipeline/specs/SKILL-GOVERNANCE-SPEC.md:110,126 both say 5,500, and the spec's own changelog (lines 14-16) demoted per-file budgets from hard to warn-tier, leaving the suite ceiling as the only hard limit. pipeline/hooks/check_token_budget.py calls sys.exit(0) unconditionally: it never blocks a commit. Conclusion: 5,500 is enforced; CLAUDE.md's "5,000" and "Hard Limits" label are both wrong. Only the owner's intent (was 5,000 ever meant to be real) is open, not the fact. Second worked example (README vs department README on agent count) and the reasoning template to reuse for a new conflict: references/authority-worked-examples.md.

Current drift list (as of 2026-07-02)

Top 3 by user-facing impact; full 12-row table with a verification command per row is references/drift-fix-queue.md:

Also queued: THIRD_PARTY_NOTICES referencing deleted skills/terraform-skill/ and skills/tdd/; ARCHITECTURE self-contradiction on agent model frontmatter; commands/council.md skill tree stale .claude/skills/council/ path header plus 2 missing entries; spec Appendix A "v1.4" banner inside the v1.5 doc; budgets.json spec_version: "1.3" against v1.5; accountant DEPARTMENT.md's 6 dead skill links (survive the HARD check_references hook because that hook only validates references/, shared-references/, templates/, scripts/, assets/, examples/ paths, pipeline/hooks/check_references.py:21, by design not evasion). Full detail and commands: references/drift-fix-queue.md.

House style

• No em dashes, anywhere, ever (owner's absolute rule, codified in repo CLAUDE.md and commit 48af508). README/ARCHITECTURE predate the rule and still contain them; fixing them is in scope for any docs touch you make nearby.
• Answer-first structure: lead with the fact or decision, push reasoning to an appendix.
• Tables for enumerable facts (counts, file lists, comparisons); prose for narrative only.
• Skill descriptions are third person; procedures inside skill bodies are imperative.
• Date-stamp every volatile fact ("as of 2026-07-02"), especially counts, versions, session-derived claims.
• Commit convention (enforced HARD at commit-msg stage by check_commit_msg.py): docs(scope): summary for narrative docs, skill-docs(name): summary for a skill's own files. Valid types: skill, skill-fix, skill-ref, skill-eval, skill-docs, chore, feat, fix, docs, style, refactor, test, ci, perf, build, revert.

Templates and deeper references

Gotchas

• Two "CLAUDE.md" files are one file, on this machine. ~/.claude/CLAUDE.md symlinks to this repo's root CLAUDE.md (readlink ~/.claude/CLAUDE.md). Editing one edits both instantly. This is machine-specific (depends on install.sh --with-claude-md); do not assume it holds on a fresh clone.
• Root README and skills/council/README.md disagree on the agent roster (21 vs 22) and neither is automatically synced to the other. Verify counts directly rather than trusting either by default.
• A commit titled "align documentation" may not have touched root README. 729adcd's message says "documentation" but git show --stat shows it only edited skills/council/README.md, commands/council.md, registry.json. Check --stat before citing a sync commit as evidence.
• check_references.py's HARD gate does not cover every markdown link, only references/, shared-references/, templates/, scripts/, assets/, examples/ paths. A DEPARTMENT.md can link to nonexistent files indefinitely without failing CI.
• check_token_budget.py always exits 0. A clean pre-commit run is not proof a skill is under budget; it is warn-only by design since spec v1.1.
• .pre-commit-config.yaml only matches files: ^skills/.*\.md$. Files under .claude/skills/ (this skill included) get none of the repo's automated frontmatter/reference/isolation checks; review by hand against the spec.
• CHANGELOG staleness is not yours to silently fix. Backfilling [Unreleased] entries asserts release claims that belong to mcs-external-positioning; flag it, don't unilaterally write it.

Provenance and maintenance

Last verified 2026-07-02, against a repo with 5 unpushed local commits ahead of the last known remote sync (105427a newest at verification time). Counts drift fast; re-run before citing a number.