Skip to content

docs(corpus): add architecture-component template node - #1528

Merged
tucktuck101 merged 1 commit into
launchpadfrom
task/1326-corpus-template-architecture-component
Aug 28, 2026
Merged

docs(corpus): add architecture-component template node#1528
tucktuck101 merged 1 commit into
launchpadfrom
task/1326-corpus-template-architecture-component

Conversation

@serina-mcfall

@serina-mcfall serina-mcfall commented Aug 27, 2026

Copy link
Copy Markdown

Node

launchpad/docs/corpus/templates/architecture-component.md, id
corpus-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 Block
View — 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.md and standards/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.

type chosen and why

type: governance. node.schema.json's type enum has thirteen members and
none of them is "template" or "policy" — I read the enum myself. I also
checked schema/README.md and schema/COMPATIBILITY.md: neither states a
rule for a meta-document's type, so this is precedent-based inference, not
written policy. Precedent: AGENTS.md is type: agent; README.md,
standards/confidence.md and standards/decision-references.md are all
type: governance. This node documents the corpus's own authoring rules for
one node shape rather than being itself a piece of architecture/capability
content, so governance is the closer fit, matching the three existing
meta-documents.

Relationships declared or checked-and-declined

None declared. Checked git ls-tree -r --name-only origin/launchpad -- launchpad/docs/corpus before drafting: at HEAD a44cf52fc740ebebbdd671427480d14f0bce0115
the tree carries exactly four validated nodes — corpus-agents,
corpus-readme, corpus-standard-confidence,
corpus-standard-decision-references — all procedural/meta-documents about
the corpus itself, none of them architecture subject matter this node would
depends-on, references, or sit part-of. None of the four sibling
templates 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-of toward the architecture-container node
being decomposed (reasoned from relationships.schema.json's directionality
definitions, cited as an INFERENCE at confidence 0.6), and optionally
depends-on toward sibling components.

Research note grounding (#4)

Cited launchpad-26/buzz#1466 (unmerged research note,
launchpad/Research/project-documentation-templates.md) as TEAM_KNOWLEDGE
only, 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.com and arc42.org/docs.arc42.org
pages I fetched and read myself, cited as FACT, not from the note. I found
no 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 (all
    unverified 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/.verified stamp 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).

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 tucktuck101 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.md and README.md both 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 leaving AGENTS.md untouched 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

task: define the architecture component corpus template

2 participants