docs(corpus): add architecture-component template node - #1528
Conversation
Defines the corpus template for a component-level architecture node, grounded in the C4 model's Component diagram and arc42 section 5's Building Block View, with an explicit boundary against the sibling context/container templates and the Code level. Closes #1326 Signed-off-by: Serina Mcfall <serina.mcfall@gmail.com>
tucktuck101
left a comment
There was a problem hiding this comment.
Review — architecture-component template node
The C4 grounding here is the most accurate in the architecture group: it places classes at the Code
level correctly (:145-153), quotes the component definition correctly (:110-116), and its
required diagram plus evidence-per-element rule is the right discipline. Three findings.
High — the research note is credited with a mapping it does not contain
The TEAM_KNOWLEDGE entry at :58 states the note "frames the C4 model as 'diagrams, not prose' that
'slots into arc42 §3/§5/§7 rather than competing with it', and names the
architecture-context/-container/-component template trio as mapping 1:1 onto C4's System Context,
Container and Component diagram layers."
The first clause is verbatim-correct. The second is not in the note. I read
launchpad/Research/project-documentation-templates.md at PR #1466's head myself: 456 lines, and
grep -coE '#[0-9]{3,4}' returns 0 — no issue references anywhere.
Your body states the same mapping as its own claim (:174-177), which is fine; only the
frontmatter attribution is wrong. Sibling #1529 carries the identical misattribution, so the likely
origin is the shared dispatch brief — correct both.
Medium — the building-block row should link to a component node, not restate it
:239-243 requires, per building-block row, "name, responsibility (one sentence), its
interface/contract, and the evidence citation for its existence". #1551's component.md required
sections 2 and 3 require Responsibility and Public interface with citations for the same object. For
any component with both nodes, the same three facts are mandatory in two places with no precedence
rule.
Ownership ruling: this template owns the container-scoped decomposition; component owns the
per-component node, and the container-level row should link rather than restate. The corpus
AGENTS.md says a second copy "drifts silently", and #1330's DoD requires linking neighbours "without
duplicating their canonical content". You could not have anticipated #1330 — I have raised the
mirror-image finding on #1551, and one bullet in each closes it.
Low — the skeleton's mermaid fence contains prose, not diagram syntax
In the copy-paste skeleton (:253-262) the required Component diagram is a mermaid fence whose body
is an English description ("[C4-style component diagram: the container as the outer boundary, its
components inside, ...]"). Every other placeholder in the same skeleton is a cell replaced in place,
so an author following the pattern emits a mermaid fence containing prose, which will not parse.
Sibling architecture-context.md:325-333 supplies a real, syntactically shaped C4Context block.
This matters here because your own rule at :338-344 is that "a diagram element with no matching
evidence-ledger claim is an unsupported claim wearing a picture" — the skeleton is the one place a
worked diagram shows what compliance looks like. (You separately disclose at :428-433 that
Mermaid's C4 fidelity was not checked against a rendered example, which is the right disclosure.)
Not findings, ruled out on evidence
- Index registration: the corpus
AGENTS.mdandREADME.mdboth state that indexes are
generated derived views, never hand-authored, and the ten-step "Creating a node" procedure has
no registration step. All 26 template PRs leavingAGENTS.mduntouched is correct. - CI green at head (latest run per check); node validates clean.
Reviewed by tucktuck101's review lane. Every failing claim reported above was reproduced by me against this PR head before posting.
Node
launchpad/docs/corpus/templates/architecture-component.md, idcorpus-template-architecture-component.Closes #1326
Issue type
Task
Which of #605's real template criteria this satisfies
Parent Feature #605's acceptance criteria state: "every template states its
purpose, required sections, evidence expectations and the industry
model/standard it adapts." This node states all four directly: Scope and
authority (purpose), Required sections + the copy-paste Template
skeleton (required sections), Evidence expectations (evidence
expectations), and Industry model this template adapts — the C4 model's
Component diagram (Simon Brown,
c4model.com) plus arc42 §5's Building BlockView — grounding it with primary-source quotes I fetched and read directly
(cited as
FACT, not taken from the research note).Note on DoD
Issue #1326's own Definition of Done carries the standards-track
MUST/SHOULD/enforcement/escalation checklist, copied verbatim from the issues
that produced
standards/confidence.mdandstandards/decision-references.md.That checklist describes a policy/standard node; this node is a template, so
it has no MUST/SHOULD normative claims about existing corpus behavior to
separate. I built the node against #605's real acceptance sentence instead
(above) and documented the mismatch inside the node itself under "Note on
Definition of Done," per the dispatch brief for this task batch.
typechosen and whytype: governance.node.schema.json'stypeenum has thirteen members andnone of them is "template" or "policy" — I read the enum myself. I also
checked
schema/README.mdandschema/COMPATIBILITY.md: neither states arule for a meta-document's
type, so this is precedent-based inference, notwritten policy. Precedent:
AGENTS.mdistype: agent;README.md,standards/confidence.mdandstandards/decision-references.mdare alltype: governance. This node documents the corpus's own authoring rules forone node shape rather than being itself a piece of architecture/capability
content, so
governanceis the closer fit, matching the three existingmeta-documents.
Relationships declared or checked-and-declined
None declared. Checked
git ls-tree -r --name-only origin/launchpad -- launchpad/docs/corpusbefore drafting: at HEADa44cf52fc740ebebbdd671427480d14f0bce0115the tree carries exactly four validated nodes —
corpus-agents,corpus-readme,corpus-standard-confidence,corpus-standard-decision-references— all procedural/meta-documents aboutthe corpus itself, none of them architecture subject matter this node would
depends-on,references, or sitpart-of. None of the four siblingtemplates in this batch (#1327, #1328, #1335, #1347) target this node or are
targeted by it, deliberately — all five are authored in parallel with no
merge ordering between them. The node's body gives forward guidance for
instance nodes: declare
part-oftoward the architecture-container nodebeing decomposed (reasoned from
relationships.schema.json's directionalitydefinitions, cited as an
INFERENCEat confidence 0.6), and optionallydepends-ontoward sibling components.Research note grounding (#4)
Cited
launchpad-26/buzz#1466(unmerged research note,launchpad/Research/project-documentation-templates.md) asTEAM_KNOWLEDGEonly, per the brief — its framing that C4 is "diagrams, not prose" and
"slots into arc42 §3/§5/§7" shaped the template's two-part structure
(diagram + prose discipline), but every direct quote from C4 and arc42 in
this node's evidence ledger comes from
c4model.comandarc42.org/docs.arc42.orgpages I fetched and read myself, cited as
FACT, not from the note. I foundno conflict between the note and the primary sources.
Verify-gate and validator evidence
python3 launchpad/project-intelligence/corpus/validate.py→ exit 0,PASS corpus validation found no errors; 17 item(s) reported unverified(allunverified notices are the expected non-fatal shapes: the provenance
commit citation, one tool-result citation, and the external C4/arc42/GitHub
URLs this validator can't pin).
python3 -m unittest discover -s launchpad/docs/corpus/schema/tests -p "test_*.py" -v→ 27/27 passed, run as the last command before this commit,earning the
.claude/.verifiedstamp for this worktree.Cross-model review
Codex (the cross-model provider for
review-final) is down, tracked as#1467. I ran a same-model adversarial self-review pass instead, per the
brief's stated substitute. It caught and fixed one real defect before this
PR: the draft originally asserted Mermaid was "this repository's diagramming
convention elsewhere in
launchpad/," which a repo-wide grep showed false(exactly one other file, a research note, uses it) — reworded to recommend
Mermaid on its actual basis (native GitHub rendering, cited from GitHub's own
docs) rather than a fabricated convention claim, and added the corrected
claim to the evidence ledger.
Escalations
None. No findings outside this node's own scope were identified beyond what
the batch dispatch brief had already flagged for a sibling task (the
architecture-container/#1336-deployment boundary, noted in this node's scope
table as the container template's concern, not filed as a new issue since it
isn't a new finding).