docs(corpus): standard for diagrams in corpus nodes (#1312)

[serina-mcfall]

Summary

Adds launchpad/docs/corpus/standards/diagrams.md, the canonical policy node for diagrams
inside corpus nodes: what form one may take, when a node carries one, what evidence it
owes, and what enforces it. The shape is forced by measurement rather than taste — a
corpus diagram cannot be an image file, because validate.py rejects every non-.md file
under the corpus root including one placed under generated/. Nine sections, 31 evidence
entries, no other corpus file touched.

Related issue

Closes #1312. Part of #605.

Issue type

Task

---

Agent provenance

Field	Value
Harness / provider	Claude Code
Model	claude-opus-5[1m]
Session reference	N/A - harness does not expose a run id
Initiating human	@serina-mcfall

Objective

One hand-authored corpus node at launchpad/docs/corpus/standards/diagrams.md stating the
diagram policy for the documentation corpus.

Impacted components

launchpad/docs/corpus/standards/diagrams.md          (new — the deliverable)
launchpad/plans/2026-08-26-issue-1312-corpus-standard-diagrams.md   (new — the plan)

No other file is touched. validate.py, node.schema.json, the ADRs and
launchpad/docs/corpus/AGENTS.md are all unchanged, per the issue's out-of-scope list.

Approach and rejected alternatives

The question the task turns on: a diagram asserts relationships, relationships are
substantive claims, and substantive claims need ledger entries — but the body is discarded
before anything is checked, so a claim whose only home is a diagram is unevidenced by
construction.

Chosen: a diagram projects what the node already establishes, and is never the only
place a claim appears. It gets no ledger entry of its own.

Rejected — one ledger entry per drawn edge. It invents a granularity the schema does
not describe (the schema says one entry per claim and gives diagrams no hook), and it
does not survive contact with the checker, which cannot tell the two versions apart.
Between two unenforced rules, the one worth having keeps every claim on the surface that
is checked. Section 5 states plainly that this is a choice rather than a fact and defers
to #1314 if the evidence standard settles it otherwise.

Also rejected — citing launchpad/docs/corpus/AGENTS.md, the instruction node that
governs this work. It has not merged, so a bare-path citation to it resolves on this branch
and hard-fails on launchpad. That is open bug #1473. Every claim is sourced to a primary
file that exists on the merge target instead; section 9 records the cost.

Verification

Command run:

python3 launchpad/project-intelligence/corpus/validate.py
python3 -m unittest discover -s launchpad/project-intelligence/corpus/tests -p "test_*.py"
python3 -m unittest discover -s launchpad/docs/corpus/schema/tests -p "test_*.py"

# merge-target proof: origin/launchpad tree with ONLY this node added
git archive origin/launchpad | tar -x -C $MT
cp launchpad/docs/corpus/standards/diagrams.md $MT/launchpad/docs/corpus/standards/
cd $MT && git init -q && python3 launchpad/project-intelligence/corpus/validate.py

# negative control: same tree, plus a node citing the unmerged AGENTS.md
cd $MT && python3 launchpad/project-intelligence/corpus/validate.py

Raw output:

UNVERIFIED  corpus-agents: evidence entry 1, citation 1: is a commit reference, which names no openable file
UNVERIFIED  corpus-standard-diagrams: evidence entry 1, citation 1: is a commit reference, which names no openable file
UNVERIFIED  corpus-standard-diagrams: evidence entry 16, citation 1: is a graph-edge or tool-result citation, which names no openable file
UNVERIFIED  corpus-standard-diagrams: evidence entry 16, citation 2: is a graph-edge or tool-result citation, which names no openable file
UNVERIFIED  corpus-standard-diagrams: evidence entry 20, citation 2: is a graph-edge or tool-result citation, which names no openable file
PASS  corpus validation found no errors; 5 item(s) reported unverified
EXIT=0

Ran 79 tests in 0.298s
OK

Ran 27 tests in 0.032s
OK

--- merge-target proof (origin/launchpad + this node only) ---
UNVERIFIED  corpus-standard-diagrams: evidence entry 1, citation 1: is a commit reference, which names no openable file
UNVERIFIED  corpus-standard-diagrams: evidence entry 16, citation 1: is a graph-edge or tool-result citation, which names no openable file
UNVERIFIED  corpus-standard-diagrams: evidence entry 16, citation 2: is a graph-edge or tool-result citation, which names no openable file
UNVERIFIED  corpus-standard-diagrams: evidence entry 20, citation 2: is a graph-edge or tool-result citation, which names no openable file
PASS  corpus validation found no errors; 4 item(s) reported unverified
EXIT=0

--- negative control: same tree + a node citing the unmerged AGENTS.md ---
FAIL  control-node: evidence entry 1, citation 1: does not resolve to a real file in the repository
FAIL  1 corpus validation error(s)
EXIT=1

The merge-target run is the one that matters, and the negative control is why it is worth
anything: it proves the check can actually fail rather than passing vacuously. The
cross-model reviewer reproduced that probe independently and got the same result.

The two FAIL messages quoted in section 3 of the node are verbatim output of the same
validator against a scratch corpus containing generated/arch.png and topology.svg.

• Tests or checks were run and the raw output is pasted above
• The diff is confined to the scope of the linked issue
• No secrets, keys, tokens or hostnames were added to tracked files

Not verified

• The mandatory cross-model review gate is NOT discharged. Codex recovered from task: the mandatory cross-model review gate has a single provider, and it is unavailable #1467
  and a real pass ran — it reproduced the merge-target probe and independently confirmed
  one finding — but it ran out of credits mid-review and never reached a verdict. The
  gate was genuinely attempted and genuinely did not complete. This PR is a draft for that
  reason.
• Nothing establishes that a Mermaid fence renders for any consumer of this corpus. No
  CI step, config or statement in the tree says so. The node's preference for Mermaid rests
  on reviewability in a PR diff, which is verified, not on rendering, which is not.
• The knowledge crate's rendering capability was not inspected. It is the question most
  likely to change the node's preference between fence languages.
• Image rejection was measured with --root against scratch corpora, not by committing
  a knowingly-invalid file into this branch's history.
• One FACT rests only on UNVERIFIED tool-result citations — the measured diagram
  counts (1 Mermaid fence, 20 box-drawing files). Disclosed in section 9, since no check
  holds that convention.
• .superpowers/ step ledger is gitignored, so it records the build locally only; the
  durable record of the merge-target check is this PR body.

Security implications

None. The change adds two Markdown documents and no executable path, no dependency, no
configuration and no network surface. Nothing in the diff is read by any runtime component;
the only consumer is validate.py in CI, which parses front matter and never executes it.

Escalations

Two review findings are filed rather than fixed, because they concern other artefacts:

• bug: three more defects in the corpus AGENTS.md create procedure, found by following it literally on #1312 #1488 — three defects in AGENTS.md's create procedure, found by following it
  literally as this task's plan required. One is the procedure gap that causes bug: code-references node's no-relationships rationale does not cover its own AGENTS.md citations #1473 and
  was filed nowhere; ten sibling branches are following that procedure now.
• task: backfill authored relationships across the corpus standards nodes once the batch has merged #1489 — the authored-relationships backfill. Every standards node in the batch
  ships an empty array for a reason that expires the day the batch merges, and nothing
  tracked going back.

Six further findings from review-final were fixed in d3e737f rather than deferred,
because each was a defect inside this deliverable: four issue-ownership claims asserted in
the body with no ledger entry (a finding the cross-model pass reached independently); a
MUST in section 5 that the node's own worked example could not satisfy; a ledger entry that
overclaimed; a missing #1478 caveat; and the plan's now-stale GATES paragraph, corrected by
appending what happened rather than rewriting what was true when written.

Left as a draft for your call, since the cross-model gate did not complete. To approve:

gh pr review 1490 --repo launchpad-26/buzz --approve

[tucktuck101]

Request changes

Medium: permitted diagram forms never defined

launchpad/docs/corpus/standards/diagrams.md:185-186,211-212 makes every fenced diagram block legal; Mermaid and box-drawing are only preferences. Unknown fence languages, ASCII art, or an untagged code block all "comply." State the closed permitted set with exact fence-language handling, or explicitly declare any fenced diagram-as-text form permitted and make enforcement deliberate.

Medium: restates canonical citation/update policy as diagram-specific, with a self-contradicting example

:344-355 restates the general citation-prefer-bare-path. and update-ledger rules from the base AGENTS/CONTRACT as diagram-only MUSTs, while its own example (lines 325-327) cites a source under a self-authored edge rule with no credential (line 270). Reduce these to a diagram-specific application linking AGENTS.md/CONTRACT.md, and reconcile the example against the bare-path MUST.

What looks good

The section is otherwise concrete; the scope-and-omissions and enforcement sections read cleanly.
[panel: fable+codex]
Note: also unstack this after #1462 — it carries the same AGENTS.md/plan-636/test payload.

[serina-mcfall]

Round-2 findings addressed

Both verified against branch head (d3e737fe7, which predated this review) before fixing — neither was already closed.

• Medium (permitted diagram forms never defined): section 3 now states plainly that the permitted set is open by choice — any fence language, including untagged — because section 7 already admits nothing checks fence language; closing the set to Mermaid/box-drawing alone would claim an enforcement this standard doesn't have. The SHOULD narrows by preference, not permission.
• Medium (restates AGENTS.md's citation/update policy, self-contradicting example): section 6 now links the citation-shape and ledger-update rules to AGENTS.md instead of restating them, and states only the diagram-specific application — an edge backed by a ledger claim inherits that claim's citation; an edge backed by a self-authored rule (section 5's second case) has nothing to cite. This reconciles the MUST against the worked example's edge 3, which is exactly such a case.

Merged origin/launchpad in (clean, no conflicts — AGENTS.md is byte-identical across branches). Validator passes clean (0 errors, 8 unverified/expected); full test suite green (79 tests).

Fixed at f9c6c4a4b. Requesting re-review.

Fixed since this review by follow-up commit f9c6c4a: the permitted-diagram-forms gap is now explicitly closed (open set, any fence language legal, stated as a deliberate choice), and the restated citation MUSTs were replaced with an explicit deferral to AGENTS.md. Verified directly against current text. Dismissing as stale/resolved.

[github-actions]

Reviewed commit d1b97acce0b56a86a7e3161028bd33630f299111 against merge base dea96f837690703b1298ab3f0e49e1b82fecb8cf.

Incomplete

This review is INCOMPLETE and must not be read as a full pass:

• no dimension was actually reviewed: the pipeline ran the 'default_reviewer' stub reviewer, which reports every dimension clean without reading it (a real dimension reviewer is #116)

Containment

No containment findings.

Fetched and empty: pr_review_comments.

Automated containment covers the delimiter boundary and unambiguous injection tells only. It does not cover injection phrased as ordinary, unremarkable prose. The absence of a containment finding is not evidence that this pull request contains no injection attempt.