From 7e6c4e81f77ccfc9fd7b8f33ed7390e7fe952bca Mon Sep 17 00:00:00 2001 From: Shay Date: Wed, 27 May 2026 07:06:03 -0700 Subject: [PATCH] =?UTF-8?q?docs(CLAUDE.md):=20documentation=20discipline?= =?UTF-8?q?=20=E2=80=94=20markdown-first,=20Mermaid=20+=20
=20sanc?= =?UTF-8?q?tioned,=20no=20standalone=20HTML=20(#355)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds an explicit Documentation Discipline section between Semantic Pack Discipline and Validation Through CLI. Encodes the stance that text-diffable Markdown is the substrate for ADRs, session docs, audit artifacts, and handoff briefs. Sanctions two zero-cost adoptions inside the existing format: - Mermaid fenced blocks for state machines / sequences / dependency graphs that genuinely benefit from a picture -
/ collapsibles for long proofs, large tables, generated logs Out of scope (explicitly): - Standalone HTML artifacts with embedded CSS / inline SVG / sidebars - Dashboards / status pages / visualizers as substitute for a pinned data artifact Rationale: the "open in browser" model breaks git diff, determinism (CSS / SVG element ordering), and cross-agent legibility — all load-bearing properties for a deterministic cognitive engine. No code changes. No runtime effect. --- CLAUDE.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 5ee0a8d9..a3f50fa1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -207,6 +207,35 @@ Manifest checksums must hash the bytes actually written to disk: checksum = hashlib.sha256(Path(lexicon_path).read_bytes()).hexdigest() ``` +## Documentation Discipline + +ADRs, session docs, audit artifacts, and handoff briefs stay as Markdown +(GitHub-flavored). Plain-text artifacts are diffable, greppable, and +readable by every agent in the dispatch pipeline. + +Within Markdown, two GitHub-rendered features are sanctioned and otherwise +sparingly used: + +- Mermaid fenced blocks (` ```mermaid `) when a state machine, sequence, + or dependency graph genuinely communicates more than prose. Inline, + not in a sidecar file. +- `
` / `` collapsibles to fold long proofs, large + tables, or generated logs without losing single-file context. + +Out of scope: + +- Standalone HTML artifacts with embedded CSS / inline SVG / sidebar + navigation. The "open in browser" model breaks `git diff`, breaks + determinism (CSS regen ordering, SVG element ordering), and breaks + cross-agent legibility. +- Dashboards, status pages, or visualizers as a substitute for a + pinned data artifact. If a visualization is load-bearing, the + underlying data must live in a deterministic JSON/JSONL/Markdown + artifact first; any rendering is a read-only view of that artifact. + +Diagrams go inside the doc that needs them. Specs do not become +single-file applications. + ## Validation Through CLI Use CLI lanes instead of ad hoc pytest fragments: