From f7f5e2c39bc396f78d17f1c6ae930405195b65bb Mon Sep 17 00:00:00 2001 From: Serina Mcfall Date: Wed, 26 Aug 2026 19:02:02 +1200 Subject: [PATCH 1/6] docs(corpus): plan and evidence base for the diagrams standard (#1312 STEP 1) Plans launchpad/docs/corpus/standards/diagrams.md against the constraint that decides its whole shape: ADR-0028 makes Markdown-with-front-matter the one canonical authored representation, and find_ownership_violations rejects every non-.md file under the corpus root -- including one placed under generated/. Measured with validate.py --root against a scratch corpus rather than assumed. Fixes three review-plan findings before building: an uncounted "two existing diagram-as-text sites" claim (git grep measures 20 box-drawing files and one mermaid fence), a done-when grep that returns 12 rather than 1 when run against a real ledger, and a GATES line that disclaimed the undischarged cross-model gate without naming the --draft mechanism that keeps it visible. Every citation this node will carry is checked to exist on origin/launchpad, so it avoids #1473's class of failure: a bare-path citation to AGENTS.md validates locally and hard-fails on the merge target, where AGENTS.md does not exist yet. Refs #1312 Signed-off-by: Serina Mcfall --- ...-26-issue-1312-corpus-standard-diagrams.md | 205 ++++++++++++++++++ 1 file changed, 205 insertions(+) create mode 100644 launchpad/plans/2026-08-26-issue-1312-corpus-standard-diagrams.md diff --git a/launchpad/plans/2026-08-26-issue-1312-corpus-standard-diagrams.md b/launchpad/plans/2026-08-26-issue-1312-corpus-standard-diagrams.md new file mode 100644 index 00000000000..b89a425cb9d --- /dev/null +++ b/launchpad/plans/2026-08-26-issue-1312-corpus-standard-diagrams.md @@ -0,0 +1,205 @@ +Issue #1312 — task: document corpus standard for diagrams +Stated size: no `Size` line -> cap: 5 steps + +The issue carries no `Size` line. Per the batch brief governing #1307-#1325, the cap is +5 steps and is not a question to stop on: these are single documents written against +conventions #636 already settled, not the first node in an unsettled corpus. + +Deliverable: `launchpad/docs/corpus/standards/diagrams.md`, node id +`corpus-standard-diagrams` (assigned in the task prompt, permanent). + +ALREADY TRUE (verified against git and against measured tool output, not notes) + + Worktree `__worktrees/task-1312-corpus-standard-diagrams`, branch + `task/1312-corpus-standard-diagrams`, cut from `origin/task/636-corpus-agents-md` + at `ebe2daf721c7d7a96fdd84eba0a0a5d37eefa109`. `git status --porcelain` is empty. + + `launchpad/docs/corpus/` contains exactly `AGENTS.md` and `schema/`. There is no + `standards/` directory; this task creates it. + + `git ls-tree -r --name-only origin/launchpad -- launchpad/docs/corpus` returns only + `schema/**`. The merge target therefore carries NO loadable corpus node: `schema/` is + named in `EXCLUDED_TOP_LEVEL_DIRS` in `launchpad/project-intelligence/corpus/validate.py`. + `corpus-agents` is loadable from this branch's base and absent from `origin/launchpad` + (`git cat-file -e origin/launchpad:launchpad/docs/corpus/AGENTS.md` -> fatal). + + Measured, not assumed — `validate.py --root `: + * a `.png` under `generated/` -> FAIL, exit 1 ("no corpus generator exists yet") + * an `.svg` outside `generated/` -> FAIL, exit 1 ("non-.md file outside generated/") + * a node whose body carries a ```mermaid fence asserting an invented topology, + Mermaid's own `---` front-matter block inside that fence, and a Markdown link to + a file that does not exist -> `PASS corpus validation clean`, exit 0 + * `Justfile:999999` against a 1005-line `Justfile` -> no error (#1459) + * a bare directory citation `launchpad/docs/corpus` -> FAIL + + So the hard constraint this document is written under is established by measurement: + a corpus diagram cannot be an image file today, and a diagram in body prose is + invisible to every check that exists. + + `launchpad/plans/` is the plan location (root `docs/` and root `scripts/` are + upstream's trees). Agents may write code and documents in this workspace — + `Launchpad/CLAUDE.md` states the scoped exception explicitly. + +STEP 1 Fix the evidence base and the citation set, then write it to scratch. [independent] + Re-read ADR-0028 (Context: "reviewed at the pull request that changes it ... + has to be something a human reviewer can read comfortably in a PR diff"), + ADR-0029 (contextual precedence; same-claim-type conflict -> flagged), + `node.schema.json` (`evidence` = "The node's provenance ledger. One entry per + claim"), `CONTRACT.md` §3 (six citation shapes), `validate.py` + (`_load_frontmatter`, `find_ownership_violations`, `_classify_citation`), + `.github/workflows/launchpad-corpus-validate.yml`, and the existing + diagram-as-text precedent in this repository. **Count it, do not estimate it.** + An earlier draft of this step asserted "the two existing diagram-as-text sites"; + `git grep -l -E '[U+250C...U+253C]' -- '*.md'` returns 20 tracked Markdown files, + `README.md` among them, and `git grep -l '```mermaid' -- '*.md'` returns one. A + completeness claim that a reviewer can refute with one grep is the exact "FACT + cited to a source that does not support it" failure this corpus has already shipped + twice; any precedent claim in the node states the measured counts and the command + that produced them, or is not made. + Decide the citation set under one hard rule: **cite nothing absent from + `origin/launchpad`.** #1473 is an open bug where a sibling node's four + `launchpad/docs/corpus/AGENTS.md` citations become hard validator errors on the + merge target; this node avoids that class entirely by sourcing every claim to a + primary file instead of to `AGENTS.md`. + done when: `scratchpad/i1312/evidence-base.md` exists and, for every path in the + intended citation set, `git cat-file -e origin/launchpad:` exits 0 — the + loop's output pasted in, zero `fatal` lines. + +STEP 2 Write the front matter and the evidence ledger. [needs 1] + `id: corpus-standard-diagrams`, `status: active`, `origin: launchpad`. + `type: governance` — the schema calls `type` "the corpus surface this node + documents" and #1312's objective calls this "the single canonical policy node"; + `governance` is the policy surface. `audiences: [agent, reviewer]` — the document + addresses whoever authors a corpus node and the reviewer who is its only + enforcement; `developer` is deliberately omitted and the omission is stated in the + body rather than left silent. No `relationships`, and the reason recorded is merge + order, not an empty corpus: `corpus-agents` is loadable here and absent from + `origin/launchpad`, so an edge to it would validate locally and be a hard error in + CI. One commit-only FACT — the revision — and no second one. Issue-sourced claims + (which sibling task owns a deferred subject) go to TEAM_KNOWLEDGE with + `provided_by`, never to FACT on a tool-result citation. + done when: a `python3 -` script parses ONLY the front-matter block with + `yaml.safe_load`, reports zero errors from + `jsonschema.Draft202012Validator(node.schema.json).iter_errors()`, and — counting + over parsed `evidence[].evidence` citation STRINGS, never over raw file text — + reports exactly one entry whose citations are all commit references + (`re.match(r"^commit\s+[0-9a-fA-F]{7,40}\b", c)`). A `grep -c "commit "` over the + file cannot do this: run against `AGENTS.md` it returns 12, because the word + "commit" occurs inside evidence *statements* as ordinary prose. + +STEP 3 Write the body. [needs 2] <- RUNS HERE + Nine sections, each answering one clause of #1312's definition of done: + (1) what this standard governs; (2) authority and scope — ADR-0028 for + representation, `node.schema.json` for the ledger, `validate.py` for what is + actually enforced, ADR-0029 for conflict, linked and not restated; (3) **form** — + a diagram MUST be diagram-as-text in a fenced block, MUST NOT be an image file, + with the measured validator output as the reason and the image question deferred to + #1316; (4) when a node carries one (MUST/SHOULD separated); (5) **the evidence + obligation** — a diagram asserting a relationship is a substantive claim, the + ledger is one entry per claim, and the body is invisible to the checker, so the + rule is that a diagram MUST NOT be the only place a claim appears: it projects + claims the ledger already carries; (6) staleness — bare paths only, never + `path:line` (#1459), diagram and ledger edited together, automated detection + deferred to #556; (7) enforcement — the validator's one relevant check plus human + PR review, which is the same mechanism ADR-0028 says the whole corpus depends on; + (8) exceptions and escalation — an image cannot be granted locally because the + validator fails closed by design, and a diagram whose edges two same-claim-type + authorities dispute is not drawn but recorded, per ADR-0029; (9) scope, omissions, + and what could not be verified. + Do not restate enum member lists or the schema's field-combination matrix — link + the schema. Do not propose changing the validator or ADR-0028. + done when: `cd && python3 launchpad/project-intelligence/corpus/validate.py` + exits 0, and every `##` heading in the new file maps to a named clause of #1312's + definition of done in a mapping table written to `scratchpad/i1312/dod-map.md`. + +STEP 4 Prove the node is safe on the merge target, not just here. [needs 3] + Reproduce #1473's method in reverse: check out `origin/launchpad` into a throwaway + directory, copy in only `standards/diagrams.md`, and run the validator there. This + is the check no local run can make, because the local tree carries `AGENTS.md` and + `origin/launchpad` does not. + done when: the validator run against the `origin/launchpad` checkout with this node + copied in exits 0, output pasted into `scratchpad/i1312/merge-target-run.txt`. + +STEP 5 Self-audit against #1312's definition of done and the create procedure. [needs 4] + Walk #1312's eleven done-criteria one at a time and record, for each, the specific + evidence that satisfies it or the reason it cannot be satisfied. Then walk + `launchpad/docs/corpus/AGENTS.md`'s ten-step create procedure literally, recording + every point where following it as written produced a wrong or impossible result — + that record is a required output of this task, not a byproduct. Re-check the base + (`git fetch origin task/636-corpus-agents-md`); if it moved, merge (never rebase — + the branch is pushed), re-run the validator and the corpus unit suite, and + re-verify any claim that rests on a file the merge touched. + done when: `scratchpad/i1312/dod-audit.md` has an entry for all eleven criteria and + all ten procedure steps; and, as the last segment of its own command, + `cd && python3 -m unittest discover -s launchpad/project-intelligence/corpus/tests -p "test_*.py"` + exits 0. + +PARALLEL Nothing may fan out. STEP 1 is the only independent step, and STEPs 2, 3 and 5 + all write `launchpad/docs/corpus/standards/diagrams.md` or depend on its final + content — two steps editing one file are sequential regardless of how unrelated + they look. STEP 4 needs the finished file. A single agent runs all five. + +GATES `review-code` after STEP 5 (the diff is a document plus a plan; `review-code` is + the reviewer the batch brief names for it). `review-tests` does NOT apply — this + diff adds no test and changes none; if that becomes false, it applies. + `review-a11y` does not apply: no UI. Then `review-adjudicate` over every finding. + Then the mandatory cross-model final pass, which is currently unavailable + (`codex exec` -> out of credits, tracked as #1467) — attempt it, record the + failure, and run `review-final` as a labelled same-vendor stand-in rather than + presenting the gate as discharged. + **Saying that is not enough to make it true.** `pr-gate.sh` lets a non-draft PR + through on a recorded `ready` verdict and has no way to tell a cross-vendor + review-final from a same-vendor one, so a stand-in that records `ready` opens a + normal PR that LOOKS fully gated. The mechanism, not the disclaimer, is what + holds: **the PR is created with `--draft`** (`pr-gate.sh` requires no verdict from + a draft), the undischarged #1467 gate is named in the PR body's "Not verified" + section as its single most important line, and marking it ready is Serina's call. + This matches what #1307 did. `qa` explore mode does NOT apply: this change + adds one Markdown document and has no runtime interface to exercise. The + validator and the corpus unit suite are the only executable checks, and they run + inside STEPs 3, 4 and 5 rather than as a gate afterwards. + +BUDGET STEP 3 will eat the budget. Sections 5 and 8 are the two places this document has + to decide something rather than report it — what evidence obligation a diagram + carries, and what an author does when no legal form exists — and both have to + land as a rule an author can follow while staying inside what ADR-0028, the + schema and the validator actually establish. Section 5 in particular is the + genuinely open question the task prompt flags; getting it wrong means either + inventing a ledger shape the schema does not have, or waving the obligation away. + +OPEN Three things #1312 does not decide, and this plan does not resolve silently. + + 1. **Whether a diagram needs its own ledger entry at all.** The task prompt names + this as the open question. Two readings are live. (a) A diagram is a claim, so + each relationship it asserts needs an entry — honest, and it makes a + six-edge diagram a six-entry ledger addition. (b) A diagram is a *rendering* + of claims made elsewhere in the node, so it needs no entry of its own, + provided nothing in it is unsourced. The plan takes (b) and makes it a MUST + ("a diagram is never the only place a claim appears"), because (a) invents a + ledger granularity the schema does not describe and the checker cannot see + either way. That is a choice, argued in the body, not a fact — and if a + reviewer prefers (a), the fix is one section, not a rewrite. + 2. **Whether `developer` belongs in `audiences`.** The batch brief says the + question is deliberately unsettled. The plan omits it and states why in the + body. A reviewer may disagree; the disagreement should be recorded, not + resolved by copying a sibling. + 3. **Whether diagrams are within #1324's taxonomy remit or this node's.** #1324 + ("standard for taxonomy") could be read as owning which node types carry + which figures. The plan reads #1312 as owning the diagram policy and #1324 as + owning node classification, and says so in the scope section so the boundary + is visible rather than assumed. + +LEFT OUT * **Any change to `validate.py`, `node.schema.json` or ADR-0028.** The task + prompt puts it out of scope, and the generated-content contract that would + permit an image file is #1316's to write. + * **Any edit to `launchpad/docs/corpus/AGENTS.md`.** Out of scope by instruction. + Defects found while following it literally are reported (STEP 5), not fixed. + * **A new check that reads body prose.** The gap is real and is named in the + body as a gap. Building the check is a separate task and would be a second + deliverable in a task whose first done-criterion is "exactly one hand-authored + canonical corpus document". + * **A second corpus node.** Any second concept found while writing is filed as + its own issue under #605, per the standing findings policy. + * **Restating the schema's enums or its FACT/INFERENCE/TEAM_KNOWLEDGE field + matrix in prose.** The validator never reads body prose, so a copy would stay + green forever after it went stale. The schema is linked instead. From 4fa2cec07eeed8521e8f6006173d4d7eb34d9fee Mon Sep 17 00:00:00 2001 From: Serina Mcfall Date: Wed, 26 Aug 2026 19:04:16 +1200 Subject: [PATCH 2/6] docs(corpus): front matter and evidence ledger for the diagrams standard (#1312 STEP 2) Twenty-five ledger entries, one commit-only FACT (the revision), and no relationships. The reason recorded for the absence is merge order rather than an empty corpus: corpus-agents is loadable from this branch's base and absent from origin/launchpad, where an unmatched relationship target is a hard error. Every openable citation was checked to exist on the merge target before it was written, so this node cannot reproduce #1473 -- it cites no file that resolves here and fails there. That is why AGENTS.md, which governs this work, is cited nowhere: it has not merged. Issue-sourced claims about which sibling task owns a deferred subject are TEAM_KNOWLEDGE attributed to the issue, never FACT. An issue URL cannot be SHA-pinned and the validator's repository-link check matches only file and tree views, so no openable citation form for one exists. type is governance because the schema defines type as the corpus surface a node documents and #1312 calls this the canonical policy node. audiences omits developer deliberately; section 9 says why rather than leaving it silent. Refs #1312 Signed-off-by: Serina Mcfall --- launchpad/docs/corpus/standards/diagrams.md | 138 ++++++++++++++++++++ 1 file changed, 138 insertions(+) create mode 100644 launchpad/docs/corpus/standards/diagrams.md diff --git a/launchpad/docs/corpus/standards/diagrams.md b/launchpad/docs/corpus/standards/diagrams.md new file mode 100644 index 00000000000..0cbe3dc22a2 --- /dev/null +++ b/launchpad/docs/corpus/standards/diagrams.md @@ -0,0 +1,138 @@ +--- +id: corpus-standard-diagrams +type: governance +status: active +origin: launchpad +audiences: + - agent + - reviewer +evidence: + - statement: "This node was authored and checked against repository revision ebe2daf721c7d7a96fdd84eba0a0a5d37eefa109." + entry_class: FACT + evidence: + - "commit ebe2daf721c7d7a96fdd84eba0a0a5d37eefa109" + - statement: "Markdown with YAML front matter is the one canonical authored representation of a corpus node, and every other serialization is a generated derived view that is never hand-authored." + entry_class: FACT + evidence: + - "launchpad/decisions/ADR-0028-corpus-canonical-representation.md" + - statement: "ADR-0028's deciding factor is that the corpus is reviewed at the pull request that changes it, so the authored form has to be something a human reviewer can read comfortably in a PR diff." + entry_class: FACT + evidence: + - "launchpad/decisions/ADR-0028-corpus-canonical-representation.md" + - statement: "The corpus root is launchpad/docs/corpus, and validate.py is the deterministic check that governs it." + entry_class: FACT + evidence: + - "launchpad/project-intelligence/corpus/validate.py" + - statement: "Every non-.md file under the corpus root is rejected today, including one placed under generated/, because no generator exists yet to reproduce it from canonical Markdown." + entry_class: FACT + evidence: + - "launchpad/project-intelligence/corpus/validate.py" + - statement: "The validator refuses a generated artifact whose provenance it cannot establish rather than deciding the question, and names #1316 as the owner of that contract." + entry_class: FACT + evidence: + - "launchpad/project-intelligence/corpus/validate.py" + - statement: "A node is parsed by splitting its leading front matter from the remainder, and only the front matter is returned, so no check reads a node's body." + entry_class: FACT + evidence: + - "launchpad/project-intelligence/corpus/validate.py" + - statement: "A node whose body carries a fenced diagram asserting a wholly invented topology, and a Markdown link to a file that does not exist, validates clean and exits 0." + entry_class: FACT + evidence: + - "launchpad/project-intelligence/corpus/validate.py" + - statement: "The evidence array is the node's provenance ledger, carrying one entry per claim, classified FACT, INFERENCE or TEAM_KNOWLEDGE." + entry_class: FACT + evidence: + - "launchpad/docs/corpus/schema/node.schema.json" + - "launchpad/project-intelligence/CONTRACT.md" + - statement: "A bare repository path in a citation is opened on disk and must resolve to a real file inside the repository, so a directory fails." + entry_class: FACT + evidence: + - "launchpad/project-intelligence/corpus/validate.py" + - statement: "A citation naming a line or line range is checked for the path and for the position's internal consistency only; the line number is never compared against the file's length." + entry_class: FACT + evidence: + - "launchpad/project-intelligence/corpus/validate.py" + - statement: "Five relationship types are defined, each with its own directionality and an inverse marked generated or authored." + entry_class: FACT + evidence: + - "launchpad/docs/corpus/schema/relationships.schema.json" + - "launchpad/docs/corpus/schema/README.md" + - statement: "Evidence precedence is contextual by claim type, and two authoritative sources of the same claim type in conflict leave the node flagged for a human rather than silently resolved." + entry_class: FACT + evidence: + - "launchpad/decisions/ADR-0029-corpus-evidence-precedence.md" + - statement: "Changes under launchpad/docs/corpus are validated in CI on pull requests and on pushes to the launchpad branch, by the same command run locally." + entry_class: FACT + evidence: + - ".github/workflows/launchpad-corpus-validate.yml" + - statement: "ARCHITECTURE.md and README.md each carry a component topology drawn in box-drawing characters, and launchpad/Research/hardening-linux-servers.md carries a Mermaid flowchart, so diagram-as-text is an established convention in this repository rather than something this standard introduces." + entry_class: FACT + evidence: + - "ARCHITECTURE.md" + - "README.md" + - "launchpad/Research/hardening-linux-servers.md" + - statement: "At the recorded revision, one tracked Markdown file in the repository carries a Mermaid fence and twenty carry box-drawing characters." + entry_class: FACT + evidence: + - "git_grep(pattern=mermaid_fence, glob=*.md) -> 1 tracked file" + - "git_grep(pattern=box_drawing_chars, glob=*.md) -> 20 tracked files" + - statement: "A diagram drawn in a node's body is invisible to every check that exists, so a relationship asserted only in a diagram is unevidenced by construction and the ledger is the only surface on which a diagram's claims can be recorded at all." + entry_class: INFERENCE + evidence: + - "launchpad/project-intelligence/corpus/validate.py" + - "launchpad/docs/corpus/schema/node.schema.json" + confidence: 0.9 + - statement: "Diagram-as-text satisfies ADR-0028's reviewability requirement in a way an image file cannot, because every edge a fence asserts appears as reviewable text in the pull-request diff." + entry_class: INFERENCE + evidence: + - "launchpad/decisions/ADR-0028-corpus-canonical-representation.md" + - "launchpad/project-intelligence/corpus/validate.py" + confidence: 0.9 + - statement: "Human review of the pull-request diff is the only enforcement a diagram has, which is the same mechanism ADR-0028 states the corpus as a whole depends on." + entry_class: INFERENCE + evidence: + - "launchpad/decisions/ADR-0028-corpus-canonical-representation.md" + - "launchpad/project-intelligence/corpus/validate.py" + confidence: 0.85 + - statement: "This node declares no relationships because of merge order rather than an empty corpus: corpus-agents is loadable from this branch and absent from the merge target, where an unmatched relationship target is a hard error." + entry_class: INFERENCE + evidence: + - "launchpad/project-intelligence/corpus/validate.py" + - "git_ls_tree(ref=origin/launchpad, path=launchpad/docs/corpus) -> schema only" + confidence: 0.95 + - statement: "Issue #1312's definition of done requires this node to state scope and authority, separate MUST requirements from SHOULD guidance, define enforcement and an exception or escalation process, and link decisions instead of duplicating them." + entry_class: TEAM_KNOWLEDGE + provided_by: "launchpad-26/buzz#1312 definition of done" + - statement: "The generated-content standard, including how a generated artifact proves its provenance and the exception process for one, is #1316's to write." + entry_class: TEAM_KNOWLEDGE + provided_by: "launchpad-26/buzz#1316" + - statement: "Extending staleness detection to canonical documentation corpus nodes is #556's to build." + entry_class: TEAM_KNOWLEDGE + provided_by: "launchpad-26/buzz#556" + - statement: "The validator accepting a path-and-line citation whose line does not exist is a known defect tracked as #1459." + entry_class: TEAM_KNOWLEDGE + provided_by: "launchpad-26/buzz#1459" + - statement: "Node classification and taxonomy is #1324's subject, and the evidence standard is #1314's." + entry_class: TEAM_KNOWLEDGE + provided_by: "launchpad-26/buzz#1324 and launchpad-26/buzz#1314" +--- + +# Diagrams in corpus nodes + +## 1. What this standard governs + +## 2. Authority and scope + +## 3. What form a diagram takes + +## 4. When a node carries a diagram + +## 5. What evidence a diagram owes + +## 6. Keeping a diagram honest + +## 7. Enforcement, and what no check can see + +## 8. Exceptions and escalation + +## 9. Scope, omissions, and what was not verified From e60f357fb7940c8fd6c3152f0c22b02f67e8d7ad Mon Sep 17 00:00:00 2001 From: Serina Mcfall Date: Wed, 26 Aug 2026 19:07:47 +1200 Subject: [PATCH 3/6] docs(corpus): the diagrams standard body (#1312 STEP 3) Nine sections answering #1312's definition of done clause by clause. The constraint that shapes all of it: a corpus diagram cannot be an image file. ADR-0028 makes Markdown-with-front-matter the one canonical authored form, and find_ownership_violations rejects every non-.md file under the corpus root -- including under generated/, because no generator exists yet to reproduce it. Section 3 quotes the validator's own two failure messages rather than paraphrasing them. Section 5 answers the question the task actually 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. The rule: a diagram projects claims the ledger already carries and is never the only place a claim appears; it gets no entry of its own. The rejected alternative -- one entry per drawn edge -- is named with the reason, and the section says plainly that this is a choice and defers to #1314 if the evidence standard settles it otherwise. The worked example is this node's own diagram, every edge of which is backed by an entry in this node's own ledger, with the caption naming which. Section 6 forbids path:line anchors (#1459 -- the line is never bounds-checked) and requires bare paths, because that is what makes git diff --name-only against the recorded revision a real staleness test until #556 lands. Section 9 discloses the one FACT resting on tool-result citations, why AGENTS.md is cited nowhere, and three things that could not be verified -- starting with the fact that nothing in the tree establishes a Mermaid fence renders for anyone. Refs #1312 Signed-off-by: Serina Mcfall --- launchpad/docs/corpus/standards/diagrams.md | 301 ++++++++++++++++++++ 1 file changed, 301 insertions(+) diff --git a/launchpad/docs/corpus/standards/diagrams.md b/launchpad/docs/corpus/standards/diagrams.md index 0cbe3dc22a2..82acfb20ccf 100644 --- a/launchpad/docs/corpus/standards/diagrams.md +++ b/launchpad/docs/corpus/standards/diagrams.md @@ -121,18 +121,319 @@ evidence: ## 1. What this standard governs +Whether a corpus node carries a diagram, what form that diagram may take, what +evidence it owes, and how it stays honest as the thing it depicts changes. + +It governs diagrams **inside a hand-authored corpus node** — that is, inside a +Markdown file under `launchpad/docs/corpus/`. Diagrams elsewhere in this repository +are not its business. + +Look up the section you need. This is reference material for whoever authors a node +and for the reviewer who, as section 7 explains, is the only enforcement a diagram has. + ## 2. Authority and scope +**This standard duplicates none of the following. Where it and one of them disagree, +they win and this document has drifted.** + +| For | Read | +|---|---| +| Why Markdown with front matter is the one canonical authored form | `launchpad/decisions/ADR-0028-corpus-canonical-representation.md` | +| The front-matter contract, including the `evidence` ledger's shape | `launchpad/docs/corpus/schema/node.schema.json` | +| Prose explanation of those fields | `launchpad/docs/corpus/schema/README.md` | +| Relationship types and their directionality | `launchpad/docs/corpus/schema/relationships.schema.json` | +| How to rank conflicting evidence, and when to stop | `launchpad/decisions/ADR-0029-corpus-evidence-precedence.md` | +| The citation shapes | `launchpad/project-intelligence/CONTRACT.md` §3 | +| What the checker actually enforces | `launchpad/project-intelligence/corpus/validate.py` | + +Where this document states a rule that none of those establish, it says so in place and +names its own authority, which is issue #1312's definition of done. A standard is +allowed to decide things; it is not allowed to attribute its decisions to a source that +did not make them. + +**Not covered here, and these are gaps rather than silence:** + +| Not covered | Owned by | +|---|---| +| How a generated artifact proves its provenance, and the exception process for one | #1316 | +| The evidence standard as a whole — classes, citation shapes, ledger composition | #1314 | +| What a recorded revision means, and when it moves | #1321 | +| Node classification and taxonomy — which kinds of node exist | #1324 | +| Linking between nodes as a general subject | #1318 | +| Automated staleness detection for corpus nodes | #556 | + ## 3. What form a diagram takes +**MUST** — a diagram in a corpus node is **diagram-as-text inside a fenced code block +in the Markdown body**. There is no other legal form today. + +**MUST NOT** — do not add an image file under the corpus root. Not a `.png`, not an +`.svg`, not any non-`.md` file, and **not one placed under a `generated/` +directory either**. This is not a style preference; the check fails closed, in both +positions: + +``` +$ python3 launchpad/project-intelligence/corpus/validate.py --root +FAIL generated/arch.png: generated artifact whose provenance and reproducibility + cannot be established -- no corpus generator exists yet to reproduce it from + canonical Markdown (ADR-0028); see #1316 +FAIL topology.svg: non-.md file outside generated/ -- misplaced generated + artifact, or hand-authored content in the wrong format +FAIL 2 corpus validation error(s) +``` + +The `generated/` case is the surprising one and worth understanding rather than +memorising. ADR-0028 asks two things of a derived view: that it be segregated, and that +it be reproducible from canonical Markdown. A directory name can prove the first. Nothing +can prove the second until a generator exists to regenerate from, so a file hand-written +straight into `generated/` is indistinguishable from a real projection, and the validator +refuses what it cannot establish. Making that possible is #1316's work, not this +standard's, and not something to route around locally. + +**SHOULD** — prefer Mermaid for a diagram with typed nodes and labelled edges; prefer +box-drawing characters for a containment or layering picture, where the boxes *are* the +point. Both already exist in this repository — `ARCHITECTURE.md` and `README.md` carry +box-drawn component topologies, and `launchpad/Research/hardening-linux-servers.md` +carries a Mermaid flowchart — so neither is a new convention this standard is +introducing. At the recorded revision the counts are one Mermaid fence and twenty +files containing box-drawing characters, across all tracked Markdown. + +**SHOULD NOT** — do not reach for a body image link (`![...](...)`) to an image hosted +elsewhere as a way around the rule above. **Authority: this standard.** Nothing checks a +body image link, in this repository or outside it, so an external one is content that can +change underneath a green validation run — the precise staleness that provenance exists +to catch. If the picture matters, it belongs in the node as text; if it cannot be, see +section 8. + ## 4. When a node carries a diagram +A diagram is not free. Section 7 establishes that nothing checks it, which makes every +diagram a maintenance surface no tool is watching. The bar is therefore not "would a +picture be nice" but "does prose fail to carry this shape". + +**SHOULD** carry a diagram when the node's subject is a **shape**: a topology, a +call or message sequence, a state machine, a containment hierarchy. These are the cases +where prose has to enumerate what a reader then has to reassemble. + +**SHOULD NOT** carry one when ordered prose or a table says the same thing at +comparable length. A diagram restating a three-item list costs a surface and buys +nothing. + +**MUST NOT** carry a diagram whose subject is wider than the node's own subject. One +node is one independently maintainable idea; a diagram that has to reach into two of +them is a signal that the node is describing two things, not that it needs a bigger +picture. Atomicity is **#1307's** subject and this standard defers to it — but the +diagram is often where the second idea first becomes visible, so it is worth noticing +here. + ## 5. What evidence a diagram owes +This is the section with a genuinely open question in it, so the reasoning is shown +rather than just the rule. + +A diagram that draws an edge between two components asserts a relationship. Under the +front-matter contract, the `evidence` array is the node's provenance ledger and carries +one entry per claim. A diagram's edges are claims. So the ledger has to account for them +somehow — but a diagram lives in the body, and **the body is discarded before anything +is checked**: a node is parsed by splitting its leading front matter from the remainder, +and only the front matter is returned. Measured, on a node whose body carried a fenced +diagram asserting a wholly invented topology *and* a Markdown link to a file that does +not exist: + +``` +PASS corpus validation clean +``` + +A diagram therefore cannot be cited, classified, or verified as a diagram. Whatever rule +this standard picks, no tool will hold it. + +**The rule.** + +- **MUST** — every relationship a diagram asserts is **already asserted in the node's + prose by a claim that carries its own ledger entry**. A diagram projects the ledger; it + never extends it. +- **MUST NOT** — a diagram is never the only place a claim appears. +- A diagram **does not get a ledger entry for being a diagram.** It gets none of its own, + because it contributes no claim of its own. + +**How a reviewer checks it, and how an author checks their own work:** take each edge in +turn and name the ledger entry that backs it. An edge with no entry is one of two things +— a claim that was never sourced, or an edge that should not be drawn. Both are fixed by +the author, and neither is visible to CI. + +**The alternative that was rejected, and why.** The other honest reading is that each +edge is its own claim and so needs its own ledger entry. It was rejected on two grounds. +It invents a granularity the schema does not describe — the schema says one entry per +claim and gives diagrams no hook at all — and it does not survive contact with the +checker, which cannot tell the two versions apart. Between two rules neither of which is +enforced, the one worth having is the one that keeps every claim on the surface that *is* +checked. **This is a choice, not a fact.** A reviewer may reasonably prefer the other; if +the evidence standard (#1314) settles it differently, this section defers to it. + +**One sharp edge.** A drawn edge between two corpus nodes is **not** a `relationships` +entry. The front-matter array is the checked one — a target naming no loaded node's id is +a hard error — while a line drawn in a fence resolves against nothing at all. If a node +genuinely depends on another, the edge belongs in front matter, and the diagram may +depict it. Drawing it instead of declaring it produces a picture of a graph the corpus +does not have. When a diagram *does* depict edges between nodes, it **SHOULD** label them +with the vocabulary in `relationships.schema.json` rather than inventing verbs, so the +picture and the front matter read as one graph. + +**A worked example — this standard's own diagram.** Every edge below is backed by a +ledger entry in this node's own front matter, and the caption names which: + +```mermaid +flowchart LR + FM["front matter (the ledger)"] + BODY["body prose"] + DIA["diagram in a fence"] + CHK["validate.py"] + + CHK -- "reads, validates" --> FM + CHK -- "splits off and discards" --> BODY + DIA -- "lives inside" --> BODY + DIA -- "projects claims recorded in" --> FM + BODY -- "every substantive claim has an entry in" --> FM +``` + +Reading the edges against the ledger: `validate.py` reading front matter and discarding +the body is the entry on parsing; the ledger carrying one entry per claim is the entry +citing `node.schema.json` and `CONTRACT.md`; the diagram projecting rather than extending +the ledger is the INFERENCE entry on body invisibility, at confidence 0.9. The diagram +adds nothing that is not already written above it — which is the rule demonstrating +itself. + ## 6. Keeping a diagram honest +A diagram drifts from its subject silently. Nothing detects it, and no citation form +helps: a position citation would be the obvious anchor, and positions are not checked. + +- **MUST** — cite **bare repository-relative paths** for the sources a diagram's edges + rest on. A bare path is opened on disk and must resolve to a real file inside the + repository, so it is one of the few citation forms that proves anything. +- **MUST NOT** — anchor a diagram with a `path:line` or `path:start-end` citation. The + path is checked; the line number is never compared against the file's length, so a + position that has silently drifted looks precise while being wrong. Tracked as + **#1459**. +- **MUST** — when a diagram changes, update the ledger entries it projects **in the same + edit**, and re-check them against their sources. A claim whose source moved is not + still a FACT because it used to be. +- **SHOULD NOT** — draw a value into a diagram that changes more often than the node + does: counts, version numbers, port numbers, timeouts. **Authority: this standard.** + Those belong in prose beside a citation, where a reader can see what they were checked + against. + +**Why bare paths, concretely.** Once every source behind a diagram is a bare path in the +ledger, `git diff --name-only -- ` is a real +staleness test: empty output means nothing the diagram rests on has moved. That test +degrades to nothing if the paths are incomplete, and it is the only staleness check +available until **#556** extends detection to corpus nodes. + ## 7. Enforcement, and what no check can see +| Surface | What checks it | +|---|---| +| An image file anywhere under the corpus root | `validate.py`, hard error, both inside and outside `generated/` | +| A diagram's syntax, in any fence language | nothing | +| Whether a diagram's edges are true | nothing | +| Whether a diagram's edges are backed by ledger entries | nothing | +| Whether a diagram still matches what it depicts | nothing | + +The same command runs locally and in CI, on pull requests and on pushes to `launchpad`, +for changes under `launchpad/docs/corpus/`. A local failure is a CI failure — and, for +everything in the second column above, a local pass is not a check. + +So **enforcement of this standard is human review of the pull-request diff.** That is not +a weakness peculiar to diagrams: it is the mechanism ADR-0028 chose for the corpus as a +whole, whose deciding factor was that the authored form must be something a human +reviewer can read comfortably in a PR diff. Diagram-as-text keeps a diagram inside that +mechanism, because every edge it asserts appears in the diff as text. An image would +leave it. + +**Reviewer checklist**, since the reviewer is the check: + +1. Every edge traces to a ledger entry (section 5). +2. No claim appears only in the diagram. +3. No `path:line` citation anchors it (section 6). +4. Edges between corpus nodes are declared in `relationships`, not merely drawn. + ## 8. Exceptions and escalation +**An image that genuinely cannot be expressed as text.** There is no local exception, and +none can be granted here — the validator fails closed and the contract that would permit +one is #1316's to define. Do one of: express the picture as text; keep the asset outside +the corpus and describe in prose what it shows; or, if the node truly cannot be written +without it, say so in the node's scope section and raise it on **#1316** so the +generated-artifact contract is written with that case in view. Do not commit the file and +do not route around the check. + +**Two authorities disagree about an edge.** If two sources with authority over the *same* +claim type contradict each other about a relationship the diagram would show, **do not +draw it**. Record the contradiction and leave the node flagged for a human rather than +picking a side; ADR-0029 is the full rule and this standard adds nothing to it. + +**A rule in this document is wrong for a particular node.** Deviating quietly is the one +response that is not available, because nothing will surface it. State the deviation and +its reason in that node's own scope section, and file an issue against **#605** naming +the node and the rule. A standard that cannot be argued with becomes a standard people +work around silently. + ## 9. Scope, omissions, and what was not verified + +**This document covers** whether a corpus node carries a diagram, what form it may take, +what evidence obligations it carries, how it is kept honest, what enforces it, and how to +raise an exception. Section 2 names what it does not cover and who owns each of those. + +**No `relationships` in this node's front matter.** The reason is merge order, not an +empty corpus. `corpus-agents` is loadable from the branch this node was authored on and +is **absent from `origin/launchpad`**, the branch it merges into; the checker loads +whatever is present where it runs, so an edge to it would validate here and be a hard +error in CI. The edges this node wants — to the evidence standard, to generated content, +to atomicity — are all to nodes that do not exist yet. Adding them is a later pass. + +**`audiences` omits `developer`, deliberately.** This node addresses whoever authors a +corpus node and the reviewer who is its only enforcement. Whether a human developer +authoring a node is a distinct audience with distinct needs is genuinely unsettled across +the corpus standards, and asserting it here would claim an audience whose workflow this +document has not been written for. If that is wrong, it is a one-line fix and worth +raising. + +**`AGENTS.md` is cited nowhere, deliberately.** `launchpad/docs/corpus/AGENTS.md` +governs this work, but it has not merged, and a bare-path citation to it resolves on this +branch and hard-fails on `launchpad` — the failure mode **#1473** records against a +sibling node. Every claim here is therefore sourced to a primary file that exists on the +merge target, checked one at a time with `git cat-file -e origin/launchpad:` before +it was written. The cost is that rules this standard inherits from the instruction node +are cited to the schema, the ADRs and the validator instead of to the node that states +them; when `AGENTS.md` merges, those citations may be revisited. + +**One FACT in this node's ledger rests only on `UNVERIFIED` citations that are not +commit references.** The entry recording the measured diagram-as-text counts cites two +tool results, which the checker recognises and cannot open. It is disclosed here because +a reviewer holds that convention, no check does, and a reader should see the choice +rather than discover it: the counts are a direct observation, which makes `FACT` the +honest class — `TEAM_KNOWLEDGE` would attribute to a person who does not exist and +`INFERENCE` would dress an observation as reasoning — and the shape is one CONTRACT.md +§3 enumerates. The reviewer's signal named for commit-only FACTs is a **second** +commit-only entry; this node has exactly one, the revision. + +**How to check this node's recorded revision.** Run +`git diff --name-only ebe2daf721c7d7a96fdd84eba0a0a5d37eefa109 -- `. Empty output means no cited source has moved since the revision was recorded. +Do not take that on this document's word — the command is the check. + +**Expected but not verified when this node was written:** + +- **Nothing establishes that a Mermaid fence renders for any consumer of this corpus.** + No CI step, configuration, or statement in the tree says so. The single existing fence + proves the convention is used here, not that anything draws it. Section 3's preference + for Mermaid therefore rests on reviewability in a diff, which is verified, and not on + rendering, which is not. +- **The rendering capability of the knowledge crate was not inspected.** ADR-0028 records + that per ADR-0027 the crate consumes pre-rendered projections of this corpus. Whether + those projections can carry diagram-as-text through to a reader is unknown here, and it + is the question most likely to change section 3's preference between fence languages. +- **The image-rejection behaviour was measured with `--root` against scratch corpora, not + against the real corpus root.** Committing an image into the branch to prove it would + put a knowingly-invalid file in history; the `--root` form exercises the same code path + and both messages in section 3 are its verbatim output. From d3e737fe7d6e42614b2cc66ef84864a999d4ecc9 Mon Sep 17 00:00:00 2001 From: Serina Mcfall Date: Thu, 27 Aug 2026 08:04:05 +1200 Subject: [PATCH 4/6] docs(corpus): close the review gate's findings on the diagrams standard (#1312) review-final raised eight findings and the cross-model Codex pass independently confirmed one of them before it ran out of credits. Six are fixed here; two are filed. Six ledger entries added. Four issue-ownership claims -- #1321, #1318, #1307 and #1473 -- were asserted in the body with nothing backing them, breaking the convention this node's own STEP 2 set and, worse, doing it in the node whose subject is traceability. That is the finding both reviewers reached independently. The other two entries carry the new #1478 caveat and the #1489 backfill. Section 5's MUST could not be satisfied by this node's own worked example. It required every diagram edge to trace to a ledger entry, but section 2 establishes that a rule this standard authors carries no entry and names its own authority instead -- and edge 3 of the example diagram ("a diagram lives inside the body") is backed by exactly such a rule. The MUST now admits both, the caption walks all five edges instead of three, and the reviewer checklist matches. A standard whose own example fails its own rule is evidence the rule was wrong, not the example. Two findings are filed rather than fixed, because they are about other artefacts: #1488 records three defects in AGENTS.md's create procedure found by following it literally -- including the one that causes #1473 -- and #1489 tracks the relationships backfill that ten sibling branches are all deferring to nobody. The plan's GATES paragraph is corrected, not rewritten: the original said Codex was unavailable, which was true when written. The appended note records what actually happened -- Codex recovered, ran, confirmed a finding, then ran out of credits mid-review without reaching a verdict. The gate is still not discharged. Refs #1312 Signed-off-by: Serina Mcfall --- launchpad/docs/corpus/standards/diagrams.md | 60 +++++++++++++++---- ...-26-issue-1312-corpus-standard-diagrams.md | 11 +++- 2 files changed, 58 insertions(+), 13 deletions(-) diff --git a/launchpad/docs/corpus/standards/diagrams.md b/launchpad/docs/corpus/standards/diagrams.md index 82acfb20ccf..9522f23e93d 100644 --- a/launchpad/docs/corpus/standards/diagrams.md +++ b/launchpad/docs/corpus/standards/diagrams.md @@ -52,7 +52,7 @@ evidence: entry_class: FACT evidence: - "launchpad/project-intelligence/corpus/validate.py" - - statement: "Five relationship types are defined, each with its own directionality and an inverse marked generated or authored." + - statement: "A finite relationship-type vocabulary, with directionality metadata for each type, is defined for the front matter's relationships array." entry_class: FACT evidence: - "launchpad/docs/corpus/schema/relationships.schema.json" @@ -100,6 +100,9 @@ evidence: - "launchpad/project-intelligence/corpus/validate.py" - "git_ls_tree(ref=origin/launchpad, path=launchpad/docs/corpus) -> schema only" confidence: 0.95 + - statement: "Backfilling the authored relationships across the corpus standards nodes, once the batch has merged, is tracked as #1489." + entry_class: TEAM_KNOWLEDGE + provided_by: "launchpad-26/buzz#1489" - statement: "Issue #1312's definition of done requires this node to state scope and authority, separate MUST requirements from SHOULD guidance, define enforcement and an exception or escalation process, and link decisions instead of duplicating them." entry_class: TEAM_KNOWLEDGE provided_by: "launchpad-26/buzz#1312 definition of done" @@ -115,6 +118,21 @@ evidence: - statement: "Node classification and taxonomy is #1324's subject, and the evidence standard is #1314's." entry_class: TEAM_KNOWLEDGE provided_by: "launchpad-26/buzz#1324 and launchpad-26/buzz#1314" + - statement: "What a recorded revision means, and when it moves, is #1321's subject." + entry_class: TEAM_KNOWLEDGE + provided_by: "launchpad-26/buzz#1321" + - statement: "Linking between corpus nodes as a general subject is #1318's." + entry_class: TEAM_KNOWLEDGE + provided_by: "launchpad-26/buzz#1318" + - statement: "Node atomicity -- whether a node describes one independently maintainable idea -- is #1307's subject." + entry_class: TEAM_KNOWLEDGE + provided_by: "launchpad-26/buzz#1307" + - statement: "A sibling node's bare-path citations to the unmerged instruction node become hard validator errors on the merge target; that failure is tracked as #1473." + entry_class: TEAM_KNOWLEDGE + provided_by: "launchpad-26/buzz#1473" + - statement: "CONTRACT.md, the instruction node and validate.py disagree about the citation forms and their count, which is tracked as #1478." + entry_class: TEAM_KNOWLEDGE + provided_by: "launchpad-26/buzz#1478" --- # Diagrams in corpus nodes @@ -143,7 +161,7 @@ they win and this document has drifted.** | Prose explanation of those fields | `launchpad/docs/corpus/schema/README.md` | | Relationship types and their directionality | `launchpad/docs/corpus/schema/relationships.schema.json` | | How to rank conflicting evidence, and when to stop | `launchpad/decisions/ADR-0029-corpus-evidence-precedence.md` | -| The citation shapes | `launchpad/project-intelligence/CONTRACT.md` §3 | +| The citation shapes — but see **#1478**, which records that this file, the instruction node and the validator disagree on the forms and their count; where they differ, the validator is what runs | `launchpad/project-intelligence/CONTRACT.md` §3 | | What the checker actually enforces | `launchpad/project-intelligence/corpus/validate.py` | Where this document states a rule that none of those establish, it says so in place and @@ -250,8 +268,11 @@ this standard picks, no tool will hold it. **The rule.** - **MUST** — every relationship a diagram asserts is **already asserted in the node's - prose by a claim that carries its own ledger entry**. A diagram projects the ledger; it - never extends it. + prose**, by a claim carrying its own ledger entry or by a rule this standard states with + named authority (section 2). A diagram projects what the node already establishes; it + never extends it. The second case is narrow and follows from section 2: a self-authored + rule legitimately has no ledger entry, so an edge depicting one is backed by the rule + rather than exempt from backing. - **MUST NOT** — a diagram is never the only place a claim appears. - A diagram **does not get a ledger entry for being a diagram.** It gets none of its own, because it contributes no claim of its own. @@ -296,12 +317,24 @@ flowchart LR BODY -- "every substantive claim has an entry in" --> FM ``` -Reading the edges against the ledger: `validate.py` reading front matter and discarding -the body is the entry on parsing; the ledger carrying one entry per claim is the entry -citing `node.schema.json` and `CONTRACT.md`; the diagram projecting rather than extending -the ledger is the INFERENCE entry on body invisibility, at confidence 0.9. The diagram -adds nothing that is not already written above it — which is the rule demonstrating -itself. +Reading all five edges against their backing, in the order drawn: + +1. `CHK -> FM` "reads, validates" — the FACT entry citing `validate.py` on front-matter + parsing. +2. `CHK -> BODY` "splits off and discards" — the same entry; it is one parse. +3. `DIA -> BODY` "lives inside" — **section 3's MUST**, a rule this standard states with + named authority. It has no ledger entry, correctly, and this is exactly the second case + the MUST above admits. +4. `DIA -> FM` "projects claims recorded in" — the INFERENCE entry on body invisibility, + at confidence 0.9. +5. `BODY -> FM` "every substantive claim has an entry in" — the FACT entry citing + `node.schema.json` and `CONTRACT.md`. + +The diagram adds nothing that is not already written above it — which is the rule +demonstrating itself. Edge 3 is the one worth pausing on: it is why the MUST reads "or by +a rule this standard states with named authority" rather than "a ledger entry" alone. A +standard whose own worked example failed its own rule would be evidence the rule was +wrong. ## 6. Keeping a diagram honest @@ -352,7 +385,8 @@ leave it. **Reviewer checklist**, since the reviewer is the check: -1. Every edge traces to a ledger entry (section 5). +1. Every edge traces to a ledger entry, or to a rule this standard states with named + authority (section 5). 2. No claim appears only in the diagram. 3. No `path:line` citation anchors it (section 6). 4. Edges between corpus nodes are declared in `relationships`, not merely drawn. @@ -389,7 +423,9 @@ empty corpus. `corpus-agents` is loadable from the branch this node was authored is **absent from `origin/launchpad`**, the branch it merges into; the checker loads whatever is present where it runs, so an edge to it would validate here and be a hard error in CI. The edges this node wants — to the evidence standard, to generated content, -to atomicity — are all to nodes that do not exist yet. Adding them is a later pass. +to atomicity — are all to nodes that do not exist yet. Adding them is a later pass, and +because that reason expires the moment the sibling standards merge, the backfill is +tracked as **#1489** rather than left to be noticed. **`audiences` omits `developer`, deliberately.** This node addresses whoever authors a corpus node and the reviewer who is its only enforcement. Whether a human developer diff --git a/launchpad/plans/2026-08-26-issue-1312-corpus-standard-diagrams.md b/launchpad/plans/2026-08-26-issue-1312-corpus-standard-diagrams.md index b89a425cb9d..2c4e7090c8b 100644 --- a/launchpad/plans/2026-08-26-issue-1312-corpus-standard-diagrams.md +++ b/launchpad/plans/2026-08-26-issue-1312-corpus-standard-diagrams.md @@ -154,7 +154,16 @@ GATES `review-code` after STEP 5 (the diff is a document plus a plan; `revie holds: **the PR is created with `--draft`** (`pr-gate.sh` requires no verdict from a draft), the undischarged #1467 gate is named in the PR body's "Not verified" section as its single most important line, and marking it ready is Serina's call. - This matches what #1307 did. `qa` explore mode does NOT apply: this change + This matches what #1307 did. + **What actually happened, recorded 2026-08-27. The paragraph above stays: it was + true when written and the constraint is worth keeping.** Codex recovered before + the gate ran, so a real cross-model pass was attempted rather than stood in for. + It reproduced the merge-target probe independently (exit 0, 4 unverified) and + independently confirmed one finding — issue-derived ownership claims in the body + with no ledger entry — but then **ran out of credits mid-review and never reached + a verdict**. #1467 therefore still bites and the gate is still NOT discharged. + The PR stays a draft and its "Not verified" section says so. + `qa` explore mode does NOT apply: this change adds one Markdown document and has no runtime interface to exercise. The validator and the corpus unit suite are the only executable checks, and they run inside STEPs 3, 4 and 5 rather than as a gate afterwards. From f9c6c4a4bee34ad0bc8ab2c114448a7a81e0507f Mon Sep 17 00:00:00 2001 From: Serina Mcfall Date: Thu, 27 Aug 2026 11:14:59 +1200 Subject: [PATCH 5/6] docs(corpus): close the permitted-form gap, deduplicate section 6 against AGENTS.md (#1312) Section 3's MUST left "any fenced code block" legal by omission while Mermaid/box-drawing read as the only real options. Stated the open set as a deliberate choice consistent with section 7's own admission that nothing checks fence language, rather than closing it to a set this standard has no enforcement basis for. Section 6 restated AGENTS.md's citation-shape and ledger-update rules as diagram-only MUSTs, and its own worked example (edge 3, backed by a self-authored rule with no ledger entry) contradicted the MUST that every edge's source get a bare-path citation. Narrowed section 6 to the diagram-specific application -- citation follows the claim it projects, a self-authored-rule edge has nothing to cite -- and linked the general rules to AGENTS.md instead of restating them. review-final finding (fable+codex panel), verified against branch head before fixing: both gaps were still open. Signed-off-by: Serina Mcfall --- launchpad/docs/corpus/standards/diagrams.md | 32 +++++++++++++++------ 1 file changed, 24 insertions(+), 8 deletions(-) diff --git a/launchpad/docs/corpus/standards/diagrams.md b/launchpad/docs/corpus/standards/diagrams.md index 9522f23e93d..8c6ab135b82 100644 --- a/launchpad/docs/corpus/standards/diagrams.md +++ b/launchpad/docs/corpus/standards/diagrams.md @@ -185,6 +185,16 @@ did not make them. **MUST** — a diagram in a corpus node is **diagram-as-text inside a fenced code block in the Markdown body**. There is no other legal form today. +**The permitted set is deliberately open, not closed.** Any fence language is legal — +` ```mermaid `, ` ```text `, an untagged ` ``` `, box-drawing characters with no +language tag, even ASCII art — because the corpus has exactly one requirement on the +form (diagram-as-text, inside a fence, in the body) and none on the dialect. This is a +choice, stated so it reads as one: closing the set to Mermaid and box-drawing alone +would contradict section 7's own admission that nothing checks fence language, since +enforcing a closed set is precisely the enforcement that does not exist. The SHOULD +below narrows by *preference*, not by *permission* — an untagged code block or an +unlisted fence language still complies; it is merely not the preferred choice. + **MUST NOT** — do not add an image file under the corpus root. Not a `.png`, not an `.svg`, not any non-`.md` file, and **not one placed under a `generated/` directory either**. This is not a style preference; the check fails closed, in both @@ -341,15 +351,21 @@ wrong. A diagram drifts from its subject silently. Nothing detects it, and no citation form helps: a position citation would be the obvious anchor, and positions are not checked. -- **MUST** — cite **bare repository-relative paths** for the sources a diagram's edges - rest on. A bare path is opened on disk and must resolve to a real file inside the - repository, so it is one of the few citation forms that proves anything. -- **MUST NOT** — anchor a diagram with a `path:line` or `path:start-end` citation. The - path is checked; the line number is never compared against the file's length, so a - position that has silently drifted looks precise while being wrong. Tracked as - **#1459**. +The citation-shape rules — prefer a bare repository-relative path, avoid `path:line` +(**#1459**), keep the ledger updated in the same edit as the body it backs — are +`AGENTS.md`'s, corpus-wide, not this standard's. This section states only the +diagram-specific application: + +- **MUST** — for every edge whose backing is a ledger claim (section 5's first case), + that claim's own citation follows the corpus-wide rule above. A diagram adds no + citation of its own; it inherits the one on the claim it projects. +- **MUST NOT** — treat an edge backed by a rule this standard states with named + authority (section 5's second case) as needing a citation at all. Section 5 already + draws that line; requiring a citation here for every edge would contradict it, since a + self-authored rule is not evidence and has nothing to cite. - **MUST** — when a diagram changes, update the ledger entries it projects **in the same - edit**, and re-check them against their sources. A claim whose source moved is not + edit** (`AGENTS.md`'s rule, applied here: a diagram is one more place a stale claim can + hide), and re-check them against their sources. A claim whose source moved is not still a FACT because it used to be. - **SHOULD NOT** — draw a value into a diagram that changes more often than the node does: counts, version numbers, port numbers, timeouts. **Authority: this standard.** From d1b97acce0b56a86a7e3161028bd33630f299111 Mon Sep 17 00:00:00 2001 From: tucktuck101 Date: Fri, 28 Aug 2026 14:31:21 +1200 Subject: [PATCH 6/6] docs(corpus): reconcile diagrams standard to the documentation standard Per Serina's decision on #1486, this node reconciles to #1313's documentation-standard before merging: - D1: carries the six required sections in the required relative order. - D3: MUST requirements and SHOULD guidance now occupy separate sections instead of being mixed through the narrative. - D4: every requirement carries a stable identifier, DG1-DG10 and DGS1-DGS6. - D5: every requirement names what enforces it, or states that nothing does. - D10: H1 is now 'Standard: diagrams', matching the subject the id names. - G4: top-level sections are no longer numbered; internal references name a section or a requirement identifier instead of a section number. No normative content changed - every MUST and SHOULD in the previous revision is preserved, relocated and identified. Explanatory prose is retained in named sections between SHOULD and Enforcement. Refs #1486 Refs #1312 Signed-off-by: tucktuck101 --- launchpad/docs/corpus/standards/diagrams.md | 297 ++++++++++---------- 1 file changed, 145 insertions(+), 152 deletions(-) diff --git a/launchpad/docs/corpus/standards/diagrams.md b/launchpad/docs/corpus/standards/diagrams.md index 8c6ab135b82..e598dd8f233 100644 --- a/launchpad/docs/corpus/standards/diagrams.md +++ b/launchpad/docs/corpus/standards/diagrams.md @@ -133,26 +133,34 @@ evidence: - statement: "CONTRACT.md, the instruction node and validate.py disagree about the citation forms and their count, which is tracked as #1478." entry_class: TEAM_KNOWLEDGE provided_by: "launchpad-26/buzz#1478" + - statement: "Per Serina's decision on launchpad-26/buzz#1486, this node reconciles to #1313's documentation-standard: it carries the six required sections in order (D1), separates MUST requirements from SHOULD guidance into their own sections (D3), gives every requirement a stable identifier (D4) and names what enforces each one or states that nothing does (D5), takes the `# Standard: ` H1 form (D10), and no longer numbers its top-level sections (G4), so internal cross-references name a section or a requirement identifier instead of a section number." + entry_class: TEAM_KNOWLEDGE + provided_by: "launchpad-26/buzz#1486, decided 2026-08-27" --- -# Diagrams in corpus nodes - -## 1. What this standard governs +# Standard: diagrams -Whether a corpus node carries a diagram, what form that diagram may take, what -evidence it owes, and how it stays honest as the thing it depicts changes. +Whether a corpus node carries a diagram, what form that diagram may take, what evidence +it owes, and how it stays honest as the thing it depicts changes. Look up the rule you +need; this is reference material for whoever authors a node and for the reviewer who, as +*Enforcement* explains, is the only enforcement a diagram has. -It governs diagrams **inside a hand-authored corpus node** — that is, inside a -Markdown file under `launchpad/docs/corpus/`. Diagrams elsewhere in this repository -are not its business. +## Scope and authority -Look up the section you need. This is reference material for whoever authors a node -and for the reviewer who, as section 7 explains, is the only enforcement a diagram has. +**This node governs** diagrams **inside a hand-authored corpus node** — that is, inside a +Markdown file under `launchpad/docs/corpus/`: whether a node carries one, what form it may +take, what evidence obligations it carries, and how it is kept honest. Diagrams elsewhere +in this repository are not its business. -## 2. Authority and scope +**Its authority is issue #1312's definition of done**, which requires this node to state +its scope and authority, to separate MUST requirements from SHOULD guidance, to define +enforcement and an exception process, and to link decisions rather than duplicate them. +Where this document states a rule that no other source establishes, it names its own +authority in place. A standard is allowed to decide things; it is not allowed to attribute +its decisions to a source that did not make them. -**This standard duplicates none of the following. Where it and one of them disagree, -they win and this document has drifted.** +**This standard duplicates none of the following. Where it and one of them disagree, they +win and this document has drifted.** | For | Read | |---|---| @@ -161,14 +169,10 @@ they win and this document has drifted.** | Prose explanation of those fields | `launchpad/docs/corpus/schema/README.md` | | Relationship types and their directionality | `launchpad/docs/corpus/schema/relationships.schema.json` | | How to rank conflicting evidence, and when to stop | `launchpad/decisions/ADR-0029-corpus-evidence-precedence.md` | +| What a standard document must itself contain | `launchpad/docs/corpus/standards/documentation-standard.md` | | The citation shapes — but see **#1478**, which records that this file, the instruction node and the validator disagree on the forms and their count; where they differ, the validator is what runs | `launchpad/project-intelligence/CONTRACT.md` §3 | | What the checker actually enforces | `launchpad/project-intelligence/corpus/validate.py` | -Where this document states a rule that none of those establish, it says so in place and -names its own authority, which is issue #1312's definition of done. A standard is -allowed to decide things; it is not allowed to attribute its decisions to a source that -did not make them. - **Not covered here, and these are gaps rather than silence:** | Not covered | Owned by | @@ -180,25 +184,45 @@ did not make them. | Linking between nodes as a general subject | #1318 | | Automated staleness detection for corpus nodes | #556 | -## 3. What form a diagram takes - -**MUST** — a diagram in a corpus node is **diagram-as-text inside a fenced code block -in the Markdown body**. There is no other legal form today. +## MUST + +| # | Requirement | Enforced by | +|---|---|---| +| **DG1** | A diagram in a corpus node MUST be **diagram-as-text inside a fenced code block in the Markdown body**. There is no other legal form today. | Nothing. No check reads the body. | +| **DG2** | A node MUST NOT add an image file under the corpus root — not a `.png`, not an `.svg`, not any non-`.md` file, and **not one placed under a `generated/` directory either**. | `validate.py`, hard error, both inside and outside `generated/`. | +| **DG3** | A node MUST NOT carry a diagram whose subject is wider than the node's own subject. | Nothing. Atomicity is #1307's subject and this rule defers to it. | +| **DG4** | Every relationship a diagram asserts MUST **already be asserted in the node's prose**, by a claim carrying its own ledger entry or by a rule this standard states with named authority (*Scope and authority*). A diagram projects what the node already establishes; it never extends it. | Nothing. | +| **DG5** | A diagram MUST NOT be the only place a claim appears. | Nothing. | +| **DG6** | A diagram MUST NOT carry a ledger entry for being a diagram. It gets none of its own, because it contributes no claim of its own. | Nothing. | +| **DG7** | An edge drawn between two corpus nodes MUST be declared in the front matter's `relationships` array, not merely drawn. | `validate.py` checks the front-matter array — a target naming no loaded node's id is a hard error. Nothing checks that a drawn edge was declared. | +| **DG8** | For every edge whose backing is a ledger claim (DG4's first case), that claim's own citation MUST follow the corpus-wide citation rule. A diagram adds no citation of its own; it inherits the one on the claim it projects. | `validate.py` checks the citation's form, never its correspondence to the claim. | +| **DG9** | An edge backed by a rule this standard states with named authority (DG4's second case) MUST NOT be treated as needing a citation at all. Requiring one would contradict DG4, since a self-authored rule is not evidence and has nothing to cite. | Nothing. | +| **DG10** | When a diagram changes, the ledger entries it projects MUST be updated **in the same edit** and re-checked against their sources. A claim whose source moved is not still a FACT because it used to be. | Nothing. | + +## SHOULD + +| # | Guidance | Enforced by | +|---|---|---| +| **DGS1** | Prefer Mermaid for a diagram with typed nodes and labelled edges; prefer box-drawing characters for a containment or layering picture, where the boxes *are* the point. | Nothing. | +| **DGS2** | Do not reach for a body image link (`![...](...)`) to an image hosted elsewhere as a way around DG2. **Authority: this standard.** | Nothing, in this repository or outside it. | +| **DGS3** | Carry a diagram when the node's subject is a **shape**: a topology, a call or message sequence, a state machine, a containment hierarchy. | Nothing. | +| **DGS4** | Do not carry one when ordered prose or a table says the same thing at comparable length. A diagram restating a three-item list costs a surface and buys nothing. | Nothing. | +| **DGS5** | When a diagram depicts edges between nodes, label them with the vocabulary in `relationships.schema.json` rather than inventing verbs, so the picture and the front matter read as one graph. | Nothing. | +| **DGS6** | Do not draw a value into a diagram that changes more often than the node does: counts, version numbers, port numbers, timeouts. **Authority: this standard.** Those belong in prose beside a citation, where a reader can see what they were checked against. | Nothing. | + +## What form a diagram takes **The permitted set is deliberately open, not closed.** Any fence language is legal — ` ```mermaid `, ` ```text `, an untagged ` ``` `, box-drawing characters with no language tag, even ASCII art — because the corpus has exactly one requirement on the form (diagram-as-text, inside a fence, in the body) and none on the dialect. This is a choice, stated so it reads as one: closing the set to Mermaid and box-drawing alone -would contradict section 7's own admission that nothing checks fence language, since -enforcing a closed set is precisely the enforcement that does not exist. The SHOULD -below narrows by *preference*, not by *permission* — an untagged code block or an -unlisted fence language still complies; it is merely not the preferred choice. +would contradict *Enforcement*'s own admission that nothing checks fence language, since +enforcing a closed set is precisely the enforcement that does not exist. DGS1 narrows by +*preference*, not by *permission* — an untagged code block or an unlisted fence language +still complies; it is merely not the preferred choice. -**MUST NOT** — do not add an image file under the corpus root. Not a `.png`, not an -`.svg`, not any non-`.md` file, and **not one placed under a `generated/` -directory either**. This is not a style preference; the check fails closed, in both -positions: +DG2 is not a style preference; the check fails closed, in both positions: ``` $ python3 launchpad/project-intelligence/corpus/validate.py --root @@ -218,46 +242,34 @@ straight into `generated/` is indistinguishable from a real projection, and the refuses what it cannot establish. Making that possible is #1316's work, not this standard's, and not something to route around locally. -**SHOULD** — prefer Mermaid for a diagram with typed nodes and labelled edges; prefer -box-drawing characters for a containment or layering picture, where the boxes *are* the -point. Both already exist in this repository — `ARCHITECTURE.md` and `README.md` carry -box-drawn component topologies, and `launchpad/Research/hardening-linux-servers.md` -carries a Mermaid flowchart — so neither is a new convention this standard is -introducing. At the recorded revision the counts are one Mermaid fence and twenty -files containing box-drawing characters, across all tracked Markdown. +DGS1's two preferences are already established here — `ARCHITECTURE.md` and `README.md` +carry box-drawn component topologies, and `launchpad/Research/hardening-linux-servers.md` +carries a Mermaid flowchart — so neither is a new convention this standard is introducing. +At the recorded revision the counts are one Mermaid fence and twenty files containing +box-drawing characters, across all tracked Markdown. -**SHOULD NOT** — do not reach for a body image link (`![...](...)`) to an image hosted -elsewhere as a way around the rule above. **Authority: this standard.** Nothing checks a -body image link, in this repository or outside it, so an external one is content that can -change underneath a green validation run — the precise staleness that provenance exists -to catch. If the picture matters, it belongs in the node as text; if it cannot be, see -section 8. +DGS2's reason is staleness: nothing checks a body image link, so an external one is +content that can change underneath a green validation run — the precise staleness that +provenance exists to catch. If the picture matters, it belongs in the node as text; if it +cannot be, see *Exceptions and escalation*. -## 4. When a node carries a diagram +## When a node carries a diagram -A diagram is not free. Section 7 establishes that nothing checks it, which makes every +A diagram is not free. *Enforcement* establishes that nothing checks it, which makes every diagram a maintenance surface no tool is watching. The bar is therefore not "would a -picture be nice" but "does prose fail to carry this shape". - -**SHOULD** carry a diagram when the node's subject is a **shape**: a topology, a -call or message sequence, a state machine, a containment hierarchy. These are the cases -where prose has to enumerate what a reader then has to reassemble. +picture be nice" but "does prose fail to carry this shape" — which is what DGS3 and DGS4 +divide, and DG3 bounds. -**SHOULD NOT** carry one when ordered prose or a table says the same thing at -comparable length. A diagram restating a three-item list costs a surface and buys -nothing. +DGS3's cases are the ones where prose has to enumerate what a reader then has to +reassemble. DG3's bound is worth stating separately from atomicity because the diagram is +often where a second idea first becomes visible: a picture that has to reach into two +nodes is a signal that the node is describing two things, not that it needs a bigger +picture. -**MUST NOT** carry a diagram whose subject is wider than the node's own subject. One -node is one independently maintainable idea; a diagram that has to reach into two of -them is a signal that the node is describing two things, not that it needs a bigger -picture. Atomicity is **#1307's** subject and this standard defers to it — but the -diagram is often where the second idea first becomes visible, so it is worth noticing -here. +## What evidence a diagram owes -## 5. What evidence a diagram owes - -This is the section with a genuinely open question in it, so the reasoning is shown -rather than just the rule. +This is the part with a genuinely open question in it, so the reasoning is shown rather +than just the rule. A diagram that draws an edge between two components asserts a relationship. Under the front-matter contract, the `evidence` array is the node's provenance ledger and carries @@ -273,19 +285,10 @@ PASS corpus validation clean ``` A diagram therefore cannot be cited, classified, or verified as a diagram. Whatever rule -this standard picks, no tool will hold it. - -**The rule.** - -- **MUST** — every relationship a diagram asserts is **already asserted in the node's - prose**, by a claim carrying its own ledger entry or by a rule this standard states with - named authority (section 2). A diagram projects what the node already establishes; it - never extends it. The second case is narrow and follows from section 2: a self-authored - rule legitimately has no ledger entry, so an edge depicting one is backed by the rule - rather than exempt from backing. -- **MUST NOT** — a diagram is never the only place a claim appears. -- A diagram **does not get a ledger entry for being a diagram.** It gets none of its own, - because it contributes no claim of its own. +this standard picks, no tool will hold it. DG4, DG5 and DG6 are that rule; DG4's second +case is narrow and follows from *Scope and authority* — a self-authored rule legitimately +has no ledger entry, so an edge depicting one is backed by the rule rather than exempt +from backing. **How a reviewer checks it, and how an author checks their own work:** take each edge in turn and name the ledger entry that backs it. An edge with no entry is one of two things @@ -299,16 +302,14 @@ claim and gives diagrams no hook at all — and it does not survive contact with checker, which cannot tell the two versions apart. Between two rules neither of which is enforced, the one worth having is the one that keeps every claim on the surface that *is* checked. **This is a choice, not a fact.** A reviewer may reasonably prefer the other; if -the evidence standard (#1314) settles it differently, this section defers to it. +the evidence standard (#1314) settles it differently, DG4 defers to it. -**One sharp edge.** A drawn edge between two corpus nodes is **not** a `relationships` -entry. The front-matter array is the checked one — a target naming no loaded node's id is -a hard error — while a line drawn in a fence resolves against nothing at all. If a node -genuinely depends on another, the edge belongs in front matter, and the diagram may -depict it. Drawing it instead of declaring it produces a picture of a graph the corpus -does not have. When a diagram *does* depict edges between nodes, it **SHOULD** label them -with the vocabulary in `relationships.schema.json` rather than inventing verbs, so the -picture and the front matter read as one graph. +**One sharp edge**, which is why DG7 exists. A drawn edge between two corpus nodes is +**not** a `relationships` entry. The front-matter array is the checked one — a target +naming no loaded node's id is a hard error — while a line drawn in a fence resolves +against nothing at all. If a node genuinely depends on another, the edge belongs in front +matter, and the diagram may depict it. Drawing it instead of declaring it produces a +picture of a graph the corpus does not have. **A worked example — this standard's own diagram.** Every edge below is backed by a ledger entry in this node's own front matter, and the caption names which: @@ -332,45 +333,29 @@ Reading all five edges against their backing, in the order drawn: 1. `CHK -> FM` "reads, validates" — the FACT entry citing `validate.py` on front-matter parsing. 2. `CHK -> BODY` "splits off and discards" — the same entry; it is one parse. -3. `DIA -> BODY` "lives inside" — **section 3's MUST**, a rule this standard states with - named authority. It has no ledger entry, correctly, and this is exactly the second case - the MUST above admits. +3. `DIA -> BODY` "lives inside" — **DG1**, a rule this standard states with named + authority. It has no ledger entry, correctly, and this is exactly the second case + DG4 admits. 4. `DIA -> FM` "projects claims recorded in" — the INFERENCE entry on body invisibility, at confidence 0.9. 5. `BODY -> FM` "every substantive claim has an entry in" — the FACT entry citing `node.schema.json` and `CONTRACT.md`. The diagram adds nothing that is not already written above it — which is the rule -demonstrating itself. Edge 3 is the one worth pausing on: it is why the MUST reads "or by -a rule this standard states with named authority" rather than "a ledger entry" alone. A +demonstrating itself. Edge 3 is the one worth pausing on: it is why DG4 reads "or by a +rule this standard states with named authority" rather than "a ledger entry" alone. A standard whose own worked example failed its own rule would be evidence the rule was wrong. -## 6. Keeping a diagram honest +## Keeping a diagram honest A diagram drifts from its subject silently. Nothing detects it, and no citation form helps: a position citation would be the obvious anchor, and positions are not checked. The citation-shape rules — prefer a bare repository-relative path, avoid `path:line` (**#1459**), keep the ledger updated in the same edit as the body it backs — are -`AGENTS.md`'s, corpus-wide, not this standard's. This section states only the -diagram-specific application: - -- **MUST** — for every edge whose backing is a ledger claim (section 5's first case), - that claim's own citation follows the corpus-wide rule above. A diagram adds no - citation of its own; it inherits the one on the claim it projects. -- **MUST NOT** — treat an edge backed by a rule this standard states with named - authority (section 5's second case) as needing a citation at all. Section 5 already - draws that line; requiring a citation here for every edge would contradict it, since a - self-authored rule is not evidence and has nothing to cite. -- **MUST** — when a diagram changes, update the ledger entries it projects **in the same - edit** (`AGENTS.md`'s rule, applied here: a diagram is one more place a stale claim can - hide), and re-check them against their sources. A claim whose source moved is not - still a FACT because it used to be. -- **SHOULD NOT** — draw a value into a diagram that changes more often than the node - does: counts, version numbers, port numbers, timeouts. **Authority: this standard.** - Those belong in prose beside a citation, where a reader can see what they were checked - against. +`AGENTS.md`'s, corpus-wide, not this standard's. DG8, DG9, DG10 and DGS6 state only the +diagram-specific application. **Why bare paths, concretely.** Once every source behind a diagram is a bare path in the ledger, `git diff --name-only -- ` is a real @@ -378,19 +363,29 @@ staleness test: empty output means nothing the diagram rests on has moved. That degrades to nothing if the paths are incomplete, and it is the only staleness check available until **#556** extends detection to corpus nodes. -## 7. Enforcement, and what no check can see +## Enforcement | Surface | What checks it | |---|---| -| An image file anywhere under the corpus root | `validate.py`, hard error, both inside and outside `generated/` | -| A diagram's syntax, in any fence language | nothing | +| An image file anywhere under the corpus root (DG2) | `validate.py`, hard error, both inside and outside `generated/` | +| A `relationships` target naming no loaded node (DG7, declared half) | `validate.py`, hard error | +| A diagram's syntax, in any fence language (DG1) | nothing | | Whether a diagram's edges are true | nothing | -| Whether a diagram's edges are backed by ledger entries | nothing | -| Whether a diagram still matches what it depicts | nothing | +| Whether a diagram's edges are backed by ledger entries (DG4, DG5, DG6) | nothing | +| Whether a drawn inter-node edge was also declared (DG7, drawn half) | nothing | +| Whether a diagram still matches what it depicts (DG10) | nothing | +| Every SHOULD in this standard | nothing | The same command runs locally and in CI, on pull requests and on pushes to `launchpad`, -for changes under `launchpad/docs/corpus/`. A local failure is a CI failure — and, for -everything in the second column above, a local pass is not a check. +for changes under `launchpad/docs/corpus/`. A local failure is a CI failure. + +**What a passing run does not establish.** A green validation run establishes that no +image file sits under the corpus root and that every declared relationship target +resolves. It establishes nothing else in this standard. It does not establish that a +diagram is syntactically valid, that its edges are true, that any edge is backed by a +ledger entry, that a drawn inter-node edge was declared, or that the picture still matches +what it depicts — because no check reads a node's body at all. For every row in the second +column above reading "nothing", a local pass is not a check. So **enforcement of this standard is human review of the pull-request diff.** That is not a weakness peculiar to diagrams: it is the mechanism ADR-0028 chose for the corpus as a @@ -402,18 +397,18 @@ leave it. **Reviewer checklist**, since the reviewer is the check: 1. Every edge traces to a ledger entry, or to a rule this standard states with named - authority (section 5). -2. No claim appears only in the diagram. -3. No `path:line` citation anchors it (section 6). -4. Edges between corpus nodes are declared in `relationships`, not merely drawn. - -## 8. Exceptions and escalation - -**An image that genuinely cannot be expressed as text.** There is no local exception, and -none can be granted here — the validator fails closed and the contract that would permit -one is #1316's to define. Do one of: express the picture as text; keep the asset outside -the corpus and describe in prose what it shows; or, if the node truly cannot be written -without it, say so in the node's scope section and raise it on **#1316** so the + authority (DG4). +2. No claim appears only in the diagram (DG5). +3. No `path:line` citation anchors it (DG8). +4. Edges between corpus nodes are declared in `relationships`, not merely drawn (DG7). + +## Exceptions and escalation + +**An image that genuinely cannot be expressed as text.** There is no local exception to +DG2, and none can be granted here — the validator fails closed and the contract that would +permit one is #1316's to define. Do one of: express the picture as text; keep the asset +outside the corpus and describe in prose what it shows; or, if the node truly cannot be +written without it, say so in the node's scope section and raise it on **#1316** so the generated-artifact contract is written with that case in view. Do not commit the file and do not route around the check. @@ -424,24 +419,24 @@ picking a side; ADR-0029 is the full rule and this standard adds nothing to it. **A rule in this document is wrong for a particular node.** Deviating quietly is the one response that is not available, because nothing will surface it. State the deviation and -its reason in that node's own scope section, and file an issue against **#605** naming -the node and the rule. A standard that cannot be argued with becomes a standard people -work around silently. +its reason in that node's own scope section, naming the requirement by its identifier, and +file an issue against **#605** naming the node and the rule. A standard that cannot be +argued with becomes a standard people work around silently. + +**A case this standard does not cover** goes to the owner named in *Scope and authority*'s +second table if it appears there, and to **#605** otherwise. -## 9. Scope, omissions, and what was not verified +## Scope and omissions **This document covers** whether a corpus node carries a diagram, what form it may take, what evidence obligations it carries, how it is kept honest, what enforces it, and how to -raise an exception. Section 2 names what it does not cover and who owns each of those. +raise an exception. *Scope and authority* names what it does not cover and who owns each of +those. -**No `relationships` in this node's front matter.** The reason is merge order, not an -empty corpus. `corpus-agents` is loadable from the branch this node was authored on and -is **absent from `origin/launchpad`**, the branch it merges into; the checker loads -whatever is present where it runs, so an edge to it would validate here and be a hard -error in CI. The edges this node wants — to the evidence standard, to generated content, -to atomicity — are all to nodes that do not exist yet. Adding them is a later pass, and -because that reason expires the moment the sibling standards merge, the backfill is -tracked as **#1489** rather than left to be noticed. +**No `relationships` in this node's front matter.** The edges this node wants — to the +evidence standard, to generated content, to atomicity — are all to nodes that have not +merged. Declaring them is a later pass, and because the reason expires as the sibling +standards merge, the backfill is tracked as **#1489** rather than left to be noticed. **`audiences` omits `developer`, deliberately.** This node addresses whoever authors a corpus node and the reviewer who is its only enforcement. Whether a human developer @@ -450,14 +445,12 @@ the corpus standards, and asserting it here would claim an audience whose workfl document has not been written for. If that is wrong, it is a one-line fix and worth raising. -**`AGENTS.md` is cited nowhere, deliberately.** `launchpad/docs/corpus/AGENTS.md` -governs this work, but it has not merged, and a bare-path citation to it resolves on this -branch and hard-fails on `launchpad` — the failure mode **#1473** records against a -sibling node. Every claim here is therefore sourced to a primary file that exists on the -merge target, checked one at a time with `git cat-file -e origin/launchpad:` before +**`AGENTS.md` is cited nowhere, deliberately.** `launchpad/docs/corpus/AGENTS.md` governs +this work, but every claim here is sourced to a primary file instead — the schema, the +ADRs and the validator — each checked with `git cat-file -e origin/launchpad:` before it was written. The cost is that rules this standard inherits from the instruction node -are cited to the schema, the ADRs and the validator instead of to the node that states -them; when `AGENTS.md` merges, those citations may be revisited. +are cited to those files rather than to the node that states them; those citations are +worth revisiting in the **#1489** pass. **One FACT in this node's ledger rests only on `UNVERIFIED` citations that are not commit references.** The entry recording the measured diagram-as-text counts cites two @@ -478,14 +471,14 @@ Do not take that on this document's word — the command is the check. - **Nothing establishes that a Mermaid fence renders for any consumer of this corpus.** No CI step, configuration, or statement in the tree says so. The single existing fence - proves the convention is used here, not that anything draws it. Section 3's preference - for Mermaid therefore rests on reviewability in a diff, which is verified, and not on + proves the convention is used here, not that anything draws it. DGS1's preference for + Mermaid therefore rests on reviewability in a diff, which is verified, and not on rendering, which is not. - **The rendering capability of the knowledge crate was not inspected.** ADR-0028 records that per ADR-0027 the crate consumes pre-rendered projections of this corpus. Whether those projections can carry diagram-as-text through to a reader is unknown here, and it - is the question most likely to change section 3's preference between fence languages. + is the question most likely to change DGS1's preference between fence languages. - **The image-rejection behaviour was measured with `--root` against scratch corpora, not against the real corpus root.** Committing an image into the branch to prove it would put a knowingly-invalid file in history; the `--root` form exercises the same code path - and both messages in section 3 are its verbatim output. + and both messages in *What form a diagram takes* are its verbatim output.