docs(corpus): add specification corpus template - #1547
Conversation
Adds launchpad/docs/corpus/templates/specification.md for issue #1348, part of PRD #605's documentation corpus contract. Serina's research note (unmerged PR #1466) does not cover this topic at all: its Open Questions section flags ISO/IEC/IEEE 29148 as unread and its OpenAPI entry is scoped to HTTP API reference only. Reproduced both gaps independently (iso.org and IEEE Xplore both returned unreadable pages) and adapted the IETF RFC Style Guide (RFC 7322) plus BCP 14 (RFC 2119 + RFC 8174) instead, grounded in this repository's own docs/nips/*.md NIP-proposal convention, which converges on RFC 7322's required structure informally but inconsistently cites BCP 14 (9 of 16 files cite nothing, 7 cite RFC 2119 alone with the older boilerplate, none cite RFC 8174/BCP 14 by name) -- a real gap this template's Required sections close by name. States boundaries against the event-kind (#1337), interface (#1342), invariant (#1343) and test-contract (#1349) templates, and against the separately-tracked formal/executable spec corpus content under feature #617 (#1369-#1374). Codex is still down (#1467); same-model adversarial self-review substitutes, including a factual correction pass that caught and fixed an overclaim about docs/nips/*.md's Security Considerations coverage and BCP 14 citation practice before commit. 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 — specification corpus template
Sound node, and the boundary against interface and event-kind is real: specification sits at a
different altitude ("what must an implementation do to conform") and does not reach for either
neighbour's territory. Worked examples resolve cleanly — a relay POST /query endpoint is an
interface node; kind 39000 is an event-kind node; a conformance contract across implementations is a
specification. Two findings.
Medium — the skeleton points at type-choice guidance that does not exist
The skeleton's type line reads
<interfaces-events | architecture | implementation -- pick per the subject's own corpus surface, per this template's own type-choice guidance above>.
There is no type-choice guidance above. Grepping the post-frontmatter body (:127-509) for
type-choice and for instance type discussion returns only the skeleton lines themselves. The only
reasoning is frontmatter evidence entry :109-113, an INFERENCE at confidence 0.65, which a reader of
the body never sees as guidance.
So the skeleton points an author at nothing, for the one required closed-enum field where a wrong
guess hard-fails node.schema.json. All three offered values are in-enum, so this is not blocking.
Promote :109-113's reasoning into a short body subsection — interface.md:219-231 does exactly
this with its "A note on type" — or point the skeleton at the evidence entry explicitly.
Low — a stitched quotation attributed to the wrong Open Questions item
The TEAM_KNOWLEDGE entry attributed to the research note's Open Questions joins two different
numbered items with an ellipsis: "iso.org returned HTTP 403 to every fetch" and "Do not cite a clause
number from these until someone has read the document" are both from item 1, which is about
ISO/IEC/IEEE 26511/26512/26514/26515; the 29148 statement is item 2.
The substance is correct — item 2 reads "Method: same as (1)", explicitly inheriting item 1's 403
finding — but the quoted string appears nowhere near 29148 in the source. That is the same "paraphrase
wearing quotation marks" failure the note itself confesses to. Attribute items 1 and 2 separately, or
quote item 2's own words.
What is correct
- RFC 7322/2119/8174, openapis.org, asyncapi.com and the ISO 403 finding all check out — verbatim or
independently reproduced. No invented citation. - The honesty about ISO 29148 being unread (rather than citing a clause number from a document nobody
opened) is exactly the right call, and the repo's own convention. referencesfor the event-kind edge agrees withinterface.md— you and #1541 are consistent, and
#1542 is the outlier. See my review there.- Required sections map onto the skeleton; an instance validates.
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/specification.md, the template for a corpus node documenting the complete normative definition of a protocol, algorithm, or wire/data format. This is one of five sibling corpus-template PRs in the current batch (#1329/#1333/#1334/#1343/#1348).Related issue
Closes #1348
Issue type
Task
Agent provenance
Objective
Create
launchpad/docs/corpus/templates/specification.mdas the corpus template for aspecificationnode.Impacted components
Approach and rejected alternatives
Issue #1348's DoD carries the same MUST/SHOULD/enforcement/policy boilerplate copied into every issue in #1326-#1351 from the standards-track issues (#1309, #1312); it describes a policy node, not a template. Built against #605's real acceptance criterion instead: purpose, required sections, evidence expectations, industry model adapted. Noted the mismatch explicitly in the document's own "Note on this document's structure" section, matching the pattern batches 2-3 used for the same boilerplate issue.
This is the one node in the batch the research note (unmerged PR #1466) explicitly does not cover, and says so in its own Open Questions section. Rejected both obvious candidates rather than forcing a weak citation:
iso.org/standard/72089.htmlreturned HTTP 403 Forbidden, and a follow-up IEEE Xplore attempt returned no retrievable content. Even setting availability aside, reasoned that 29148 is a requirements-engineering standard (SRS/StRS), a different genre than a protocol/format specification.AGENTS.mdstates Buzz's primary API is Nostr-over-WebSocket with only a narrow HTTP surface, so OpenAPI would misdescribe the dominant transport.Adopted instead: the IETF RFC Style Guide (RFC 7322)'s required document structure (fetched and verified directly - Title/Abstract/Body/mandatory Security Considerations) plus BCP 14 (RFC 2119 + RFC 8174, also fetched and verified directly), grounded in this repository's own
docs/nips/*.mdNIP-proposal convention, which converges informally on RFC 7322's shape (14 of 16 files carry a security-considerations-shaped section) but cites BCP 14 inconsistently (9 of 16 cite nothing; 7 cite RFC 2119 alone with the older, pre-RFC-8174 boilerplate; none cite RFC 8174/BCP 14 by name - verified by direct grep, not assumed). The template's Required sections close that measured gap by name.Alternative considered and rejected: treating
docs/nips/NIP-AM.md's own shape as sufficient grounding on its own, without the RFC primary sources. Rejected because a repo convention with no formal source behind it isn't independently verifiable the way the research note's own corrections (MADR's real name, TGDP's real license) show unverified secondhand claims are exactly what breaks this corpus's evidence contract.A full adversarial self-review pass (Codex is down, #1467 - same-model self-review substitutes) caught and fixed a real overclaim before commit: an early draft claimed none of Buzz's
docs/nips/*.mdfiles cite RFC 2119, and separately mischaracterized which 6 files lack a Security Considerations section. Both were re-measured by direct grep and corrected in the evidence ledger and body (see Verification below).Verification
Command run:
Raw output:
Command run:
Raw output:
Not verified
specificationnode has been built from this template yet; whether the required-sections list holds for a subject with no wire format at all (e.g. a pure algorithm) is untested.docs/nips/*.mdfiles with no security-considerations-shaped heading (NIP-PMA, NIP-RS) omit one deliberately or by oversight was not individually investigated - only the mechanical heading search was run.implements(vsreferences) is the right relationship direction for aninterfacenode pointing at aspecificationnode was reasoned fromrelationships.schema.json's own directionality description, not settled against a real example - no corpus node currently declares either edge.launchpad/docs/corpus/templates/.Security implications
None. This adds one new Markdown documentation file (a template, not executable code or configuration) under
launchpad/docs/corpus/templates/. No secrets, credentials, or runtime-affecting content are introduced.Escalations
None raised. Checked for a third factual error in the research note's RFC 2119/8174 (BCP 14) entry, since the brief named two already-found errors (MADR's real name, TGDP's real license) as a reminder to verify rather than trust the note's prose; independently re-verified RFC 2119 and RFC 8174 against their primary sources and found the note's BCP 14 entry accurate, so no third error to report. Checked for an escalation-worthy gap around formal/executable specifications (TLA+, Tamarin) not being covered by this template, but found real, already-filed coverage under feature #617 (issues #1369-#1374, targeting
launchpad/docs/corpus/verification/formal/), so no new issue was needed.