docs(corpus): add implementation-reference template (#1341) - #1555
Conversation
Create the template for a corpus node whose subject is a piece of code's concrete realization of a spec, decision, or contract -- a traceability artifact, distinct from #1346/reference's Diataxis documentation-FORM template (surface vs. form are orthogonal axes). Grounded in the ISTQB Glossary's traceability/traceability-matrix definitions, MADR's Confirmation section (and the gap that none of this repository's own 51 ADRs use it), and this repository's own REQUIREMENTS.md Traceability section and git-sign-nostr/NIP-GS pairing as real working precedent. Closes #1341 Signed-off-by: Serina Mcfall <serina.mcfall@gmail.com>
tucktuck101
left a comment
tucktuck101
left a comment
There was a problem hiding this comment.
Review — implementation-reference template (#1341)
Every code and path citation in this node resolves at head — I checked, and there is no invented
code citation here. The template's job (point a corpus claim at real code durably) is the right
one and the required sections serve it. One false claim about this repository, and it is
load-bearing for the template's central argument.
High — this repository's ADRs are not MADR-structured
The ledger entry (entry_class: FACT) and the body both assert that this repo's decision records
are "visibly MADR-structured" / "several of this repository's own ADRs are visibly structured
after" MADR.
Heading census across all 51 files in launchpad/decisions/, run on launchpad:
## Context and Problem Statement 0 ## Context 50
## Decision Outcome 0 ## Decision 50
files mentioning MADR 0 ## Consequences 50
## Provenance 45
That is the classic Nygard triad plus two house sections. MADR's signature headings appear zero
times, and no ADR mentions MADR at all.
This matters because the whole "MADR supplies the gap" argument rests on our ADRs being
MADR-shaped documents that skip Confirmation — when they are Nygard-shaped documents that never
had such a section to skip. The entry's only citation is the ### Confirmation grep, which
establishes the absence but says nothing about document shape.
The gap you are naming is real; rest it on what is true: MADR names a Confirmation section, this
repo's ADR format has no equivalent, so "does the code match what was decided?" has no home today.
Medium — the implements-exclusivity claim is contradicted by the schema it cites
The entry calls implements "the one relationship type in the corpus whose stated purpose is
code-realizes-spec traceability, not documentation-to-documentation linkage."
relationships.schema.json:35-39 reads "source is the concrete realization of target (e.g. a
template instance of a standard)" — a documentation-to-documentation example, and the only
example the schema gives. Nothing in the schema mentions code.
Sibling #1546 relies on the schema's actual reading, so two nodes in this batch read the same
schema line incompatibly. Your use of implements stays legal; only the exclusivity clause is
unsupported. Suggested: "...directionality 'source is the concrete realization of target'; the
schema's own example is documentation-to-documentation, and this template extends the same edge
to code-realizes-spec."
Low — the MUST-level implements edge is rendered only as a body bullet
Relationships makes the edge a MUST ("must declare implements toward its target ... an edge to
a nonexistent id is a hard validation error"), but the skeleton renders it only as prose under
## Relationships. relationships is a frontmatter array, and neither the merged nodes nor the
validator read a body section. Omitting frontmatter from the skeleton is the batch norm (21 of 23
siblings), so this is not an outlier — but this is the only template that raises the edge to a
MUST, so an author copying the skeleton literally declares zero relationships while believing the
MUST is satisfied.
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.
2 participants
Summary
Adds
launchpad/docs/corpus/templates/implementation-reference.md: the corpus template for a node documenting how a piece of code concretely realizes a spec, decision, or contract (a traceability artifact, usingnode.schema.json'simplementationsurface andrelationships.schema.json'simplementsedge). States the boundary against#1346/reference (surface vs. form are orthogonal axes) explicitly.Related issue
Closes #1341
Issue type
Task
Agent provenance
Objective
Create
launchpad/docs/corpus/templates/implementation-reference.mdas the template a corpus node uses when its subject is a piece of code's concrete realization of a spec/decision/contract.Impacted components
Approach and rejected alternatives
Issue #1341's own Definition of Done is the standards-track boilerplate ("single canonical policy node") copied across all 26 templates-track issues (#1326-#1351) per the batch dispatch brief for this task set (confirmed independently by opening the issue body directly). The real acceptance bar is parent Feature #605's own checklist item: "every template states its purpose, required sections, evidence expectations and the industry model/standard it adapts" (verified by opening #605 directly). This node is built against that sentence; the mismatch is documented explicitly in the node's own "Note on Definition of Done" section.
The most overlap-risky part of this task is the naming collision with
#1346/reference (unmerged, PR #1534). I read PR #1534's full diff before drafting (git show origin/task/1346-corpus-template-reference:launchpad/docs/corpus/templates/reference.md). #1346 is a Diátaxis Reference documentation-form template — it fixes the prose shape and lets the corpustypesurface vary with the subject. This node fixes the opposite axis: it documents theimplementationsurface (or occasionally another surface value the realizing artifact calls for) and requires animplementsrelationship edge, while letting the documentation form vary. The two are orthogonal, not competing, and a single node could in principle satisfy both templates at once without either being redundant. Stated concretely in the node's "Boundary" section rather than left as a hand-wavy "reference vs. something else" distinction.Rejected alternative: grounding the template in the C4 model or another architecture-diagramming framework (the reflex choice given the "reference" name and prior sibling templates' precedent). Rejected because the batch brief's research check already confirmed the unmerged research note doesn't cover this topic, and node.schema.json's own
implementsrelationship type ("source is the concrete realization of target") together with a real in-repo precedent (crates/git-sign-nostr/README.md's "See NIP-GS for the full specification" pointer) made a traceability-matrix framing (ISTQB Glossary) the better-grounded, more concrete fit than a documentation-form or diagramming framework.A real, worth-recording finding while drafting: an early
WebFetchofhttps://raw.githubusercontent.com/adr/madr/main/template/adr-template.mdreturned plausible-looking content, butadr/madr'smainbranch does not exist (gh api repos/adr/madr/commits/main→ 404; the repo's default branch isdevelop). The quoted "Confirmation" guidance text happened to be accurate, but the citation itself was pinned to a non-existent ref, andvalidate.pycaught it (see raw output below). Every MADR-sourced claim in the final node was re-verified and re-cited directly againstgh api repos/adr/madr/contents/...?ref=developand pinned to the realdevelopHEAD commit SHA (d1698d0b8b6b8ef83a0a255d3e3920cbcda159ba) before committing. Flagging this because it is a real WebFetch reliability gap other batches' agents citing external GitHub-hosted templates should watch for.Pipeline: plan-issue -> self-review-plan -> build-change -> self-review-code (citation-by-citation re-verification against primary sources, described above) -> self-adjudicate -> cross-model final pass substituted by same-model adversarial self-review, since Codex is still down (#1467) -> findings handled (none required escalation; see Escalations) -> draft PR.
Verification
Command run:
Raw output:
Also run, corpus validator (exit 0 required and obtained):
Not verified
#1346is unmerged at time of writing; this node cites its stated surface/form distinction asTEAM_KNOWLEDGE, notFACT, for exactly that reason, and has not been re-checked against task: define the reference corpus template #1346's content after this PR was opened (only against the diff as it stood at PR-open time).istqb-glossary.pagemirror against the officialglossary.istqb.orgsite — that site is JS-rendered and returned no fetchable content viaWebFetch; corroborated instead via two independent tool calls (WebSearch synthesis + two separate WebFetch calls to distinct mirror pages) that agreed on the same quoted text.Security implications
None. This is a documentation-only change (one new Markdown file under
launchpad/docs/corpus/templates/) with no code, config, or secret-bearing content. Reviewed the prose for gitleaks-hazard-shaped phrases (slash-separated pairs, "key"/"token" near a colon) before committing, per the batch dispatch brief's note about PR #1548's false-positive on "bucket/prefix"; found none.Escalations
None specific to this node. Noted but not escalated as a new issue (already covered by existing #1544, "several PRs cite bare GitHub issue URLs as FACT instead of TEAM_KNOWLEDGE"): PR #1534 (
#1346/reference) citeshttps://github.com/launchpad-26/buzz/issues/605and its own issue asFACTrather thanTEAM_KNOWLEDGE, whichlaunchpad/docs/corpus/AGENTS.mdstates should beTEAM_KNOWLEDGEfor issue/PR/discussion sources. This node's own equivalent citations (to #605 and #1341) are classifiedTEAM_KNOWLEDGEto followAGENTS.mdcorrectly rather than copy the pattern.