Skip to content

Commit 338b4d0

Browse files
authored
Merge pull request #1779 from launchpad-26/task/605-corpus-batch-b
docs(corpus): fix 12 review-found defects, batch B of 2 (#605)
2 parents 32aa546 + 741c941 commit 338b4d0

9 files changed

Lines changed: 193 additions & 78 deletions

File tree

‎launchpad/docs/corpus/templates/concept.md‎

Lines changed: 36 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -123,11 +123,11 @@ evidence:
123123

124124
# Template: concept
125125

126-
How to write a corpus node whose subject is a **concept** — an idea, abstraction,
127-
mechanism or term in the Buzz system that a reader needs to understand before the
128-
reference material or the how-to material about it will make sense. This node is
129-
the template itself, not an instance of one: it states what a concept node must
130-
contain, not an explanation of any real Buzz concept.
126+
How to write a corpus node whose subject is a **concept** — an idea, abstraction, or
127+
mechanism in the Buzz system that a reader needs to understand before the reference
128+
material or the how-to material about it will make sense. This node is the template
129+
itself, not an instance of one: it states what a concept node must contain, not an
130+
explanation of any real Buzz concept.
131131

132132
## Scope and authority
133133

@@ -286,6 +286,10 @@ here for the same reason the template gives.
286286
becomes a `relationships` edge instead, so the corpus's own graph carries the
287287
link rather than a paragraph that can drift out of sync with it.
288288

289+
8. **Scope and omissions**, per `AGENTS.md`'s own required step 8: what the node
290+
does not cover and who owns it, and — separately — what was expected to be
291+
verified when the node was written and could not be.
292+
289293
## Evidence expectations
290294

291295
**The definition (required section 2) is where FACT is most reachable.** If the
@@ -337,18 +341,43 @@ is it, and how does it relate to what I know" stays here. "What does it require
337341
to do" or "what exactly does it accept as input" belongs to one of the two siblings
338342
above.
339343

344+
**Against glossary term (#1340).** A subject that is a single defined term — one
345+
piece of jargon needing only a one-to-three-sentence, dictionary-style meaning —
346+
is not a concept. `glossary-term.md` (#1340) is the narrower template for exactly
347+
that case, and its own boundary table already routes the other direction: a term
348+
needing several paragraphs of discursive "why does this exist and how does it fit
349+
together" reasoning is not a glossary term any more, and belongs here instead. If
350+
what is being drafted is a short, lookup-shaped definition with no reflection or
351+
surrounding narrative, use `glossary-term.md`, not this template.
352+
353+
## A note on `type`
354+
355+
`node.schema.json`'s `type` enum (`architecture`, `layers`, `capabilities`,
356+
`platforms`, `implementation`, `interfaces-events`, `verification`, `operations`,
357+
`development`, `release`, `governance`, `agent`, `ingestion`) names the corpus
358+
**surface** a node documents, not the documentation form (explanation, reference,
359+
how-to) its prose takes. A corpus node instance actually written from this
360+
template — a real concept document about a real Buzz idea — may take a `type`
361+
value other than `governance`, decided by that instance's own subject against PRD
362+
#602's corpus-surface list. This template document itself carries
363+
`type: governance` because it documents the corpus's own authoring rules, per the
364+
precedent in the evidence ledger above, not because concept-shaped nodes in
365+
general use `governance`.
366+
340367
## Scope and omissions
341368

342369
**This document covers** the purpose of a concept node, the sections it must
343-
contain, what evidence each section needs, and the industry model it adapts. It
344-
does not itself explain any real Buzz concept.
370+
contain (including its own required scope-and-omissions section), what evidence
371+
each section needs, the industry model it adapts, and what `type` a concept
372+
instance carries. It does not itself explain any real Buzz concept.
345373

346374
**It does not cover, and these are gaps rather than silence:**
347375

348376
| Not covered here | Owned by |
349377
|---|---|
350378
| The reference document form and its required sections | #1346 |
351379
| The procedure/how-to document form and its required sections | #1345 |
380+
| The glossary-term document form, for a single defined term needing only a short lookup definition | #1340, `glossary-term.md` |
352381
| The front-matter contract itself | `launchpad/docs/corpus/schema/node.schema.json` |
353382
| Evidence classification mechanics beyond what this template's own sections need | `launchpad/docs/corpus/AGENTS.md`, `standards/confidence.md` |
354383
| Whether a diagram-authoring convention (e.g. a fixed Mermaid style) should be standardized corpus-wide | Not yet filed as its own issue at the recorded revision |

‎launchpad/docs/corpus/templates/configuration.md‎

Lines changed: 15 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ evidence:
2929
evidence:
3030
- "git_show(ref='origin/task/1335-corpus-template-decision-reference', path='launchpad/docs/corpus/templates/decision-reference.md') -> front matter type: governance"
3131
- "git_show(ref='origin/task/1346-corpus-template-reference', path='launchpad/docs/corpus/templates/reference.md') -> front matter type: governance"
32-
- statement: "relationships.schema.json defines five relationship types -- depends-on, supersedes, implements, references, part-of -- with references' directionality stated as 'source cites target as supporting context; no ownership or currency dependency implied', generated inverse referenced-by."
32+
- statement: "relationships.schema.json defines five relationship types -- depends-on, supersedes, implements, references, part-of -- with references' directionality stated as 'source cites target as supporting context; no ownership or currency dependency implied', and an inverse named referenced-by that is authored, not generated -- the only one of the five relationship types whose inverse is authored rather than generated."
3333
entry_class: FACT
3434
evidence:
3535
- "launchpad/docs/corpus/schema/relationships.schema.json"
@@ -89,18 +89,14 @@ evidence:
8989
evidence:
9090
- "launchpad/AGENT_PR_TEMPLATE.md"
9191
- statement: "Parent Feature #605's acceptance criteria require that 'every template states its purpose, required sections, evidence expectations and the industry model/standard it adapts', and this is the acceptance bar this node is built against rather than issue #1332's own copied-over standards-track Definition of Done."
92-
entry_class: FACT
93-
evidence:
94-
- "https://github.com/launchpad-26/buzz/issues/605"
92+
entry_class: TEAM_KNOWLEDGE
93+
provided_by: "launchpad-26/buzz#605 acceptance criteria"
9594
- statement: "Issue #1332's own Definition of Done is byte-identical to the standards-track boilerplate ('States scope and authority/source of the policy. Separates MUST requirements from SHOULD guidance. Defines enforcement/checks and exception/escalation process. Links decisions or higher-order policy instead of duplicating them.'), the same text independently found copied across #1326-#1351."
96-
entry_class: FACT
97-
evidence:
98-
- "https://github.com/launchpad-26/buzz/issues/1332"
95+
entry_class: TEAM_KNOWLEDGE
96+
provided_by: "launchpad-26/buzz#1332 definition of done"
9997
- statement: "Issue #1332's Objective reads 'Create launchpad/docs/corpus/templates/configuration.md as the single canonical policy node for configuration', and issue #1326's Objective reads 'Create launchpad/docs/corpus/templates/architecture-component.md as the single canonical policy node for architecture component' -- the identical phrase 'policy node' applied to a different template task, confirming the word is boilerplate carried by the planning apparatus rather than a considered classification specific to #1332."
100-
entry_class: FACT
101-
evidence:
102-
- "https://github.com/launchpad-26/buzz/issues/1332"
103-
- "https://github.com/launchpad-26/buzz/issues/1326"
98+
entry_class: TEAM_KNOWLEDGE
99+
provided_by: "launchpad-26/buzz#1332 Objective, compared against launchpad-26/buzz#1326 Objective"
104100
- statement: "An unmerged research note cataloguing industry-standard project documentation templates does not mention configuration, config files, environment variables or the Twelve-Factor App anywhere in its text."
105101
entry_class: TEAM_KNOWLEDGE
106102
provided_by: "launchpad-26/buzz#1466 (unmerged research note, launchpad/Research/project-documentation-templates.md on branch docs/research-project-doc-templates)"
@@ -158,7 +154,7 @@ review-enforced half.
158154
| Relationship types and their directionality | `launchpad/docs/corpus/schema/relationships.schema.json` |
159155
| Creating, updating and retiring a node | `launchpad/docs/corpus/AGENTS.md` |
160156
| Citing an accepted decision as evidence | `launchpad/docs/corpus/standards/decision-references.md` |
161-
| The generic reference template this one specializes | `launchpad/docs/corpus/templates/reference.md` (`#1346`, once merged) |
157+
| The generic reference template this one specializes | `launchpad/docs/corpus/templates/reference.md` (`corpus-template-reference`, #1346) |
162158
| The industry models this template adapts | *Industry model* below, and the primary sources it cites |
163159

164160
If this node and any of those disagree, **they win** -- this one has drifted and
@@ -427,12 +423,13 @@ A node built from this template:
427423
- **may** declare `part-of` toward a broader capability, deployment, or operations
428424
node this configuration surface is a subsection of, when the settings are one
429425
part of a larger documented surface rather than independently standing.
430-
- **may** declare `references` toward the generic reference template (`#1346`,
431-
once merged) or toward this template node itself (target:
432-
`corpus-template-configuration`), if the author wants the generated
433-
`referenced-by` edge; this is optional, since a node's shape (Configuration
434-
description / Settings / Litmus test / Secrets discipline / Boundary) already
435-
shows which template it followed.
426+
- **may** declare `references` toward the generic reference template
427+
(`corpus-template-reference`, #1346) when the author defers completeness to it.
428+
- **should** declare `implements` targeting `corpus-template-configuration` (this
429+
node's id) once this node is merged. `relationships.schema.json` names *"a
430+
template instance of a standard"* as `implements`' own worked example -- not
431+
the weaker `references` edge, and not a `referenced-by` edge, since no
432+
generator produces one for this relationship type.
436433
- **must**, per `AGENTS.md`'s own rule, resolve every declared target against
437434
`origin/launchpad` (or whatever the merge-target branch is at the time), never
438435
against the author's own worktree.

‎launchpad/docs/corpus/templates/deployment.md‎

Lines changed: 27 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,11 @@ evidence:
9090
entry_class: FACT
9191
evidence:
9292
- "docker-compose.yml"
93+
- statement: "launchpad/ENVIRONMENTS.md is the cohort document that owns the list of environments this repository actually operates, and its table carries four rows -- Local development (status IMPLEMENTED), Local VM harness (status OPEN, tracked by issues #17 and #19), Cohort VPS (status OPEN, tracked by issues #21 and #22), and Contributors' machines (status OPEN, tracked by issue #43) -- none of which is named \"Quickstart\" or \"Production\"; those two names belong to deploy/charts/buzz's own Helm values profiles instead, per deploy/charts/buzz/README.md."
94+
entry_class: FACT
95+
evidence:
96+
- "launchpad/ENVIRONMENTS.md"
97+
- "deploy/charts/buzz/README.md"
9398
- statement: "CLAUDE.md's Getting Started section instructs `just relay` to \"start relay at ws://localhost:3000\" as a separate step from `just setup`, consistent with the relay running as a locally built process against docker-compose's containerized Postgres and Redis rather than as a fourth container inside docker-compose.yml itself."
9499
entry_class: FACT
95100
evidence:
@@ -216,6 +221,7 @@ the ledger rather than being re-argued here in prose a second time.
216221
| The boundary this node draws against, primary source | `launchpad-26/buzz#1529` (architecture-container template) |
217222
| arc42, primary source | `https://arc42.org/overview`, `https://docs.arc42.org/section-7/` |
218223
| C4 model, primary source | `https://c4model.com/`, `https://c4model.com/diagrams/deployment`, `https://c4model.com/abstractions/container` |
224+
| This repository's own operated environments — the real list, owned separately from any chart's values profiles | `launchpad/ENVIRONMENTS.md` |
219225

220226
If this file and any of those disagree, **they win** — this one has drifted and
221227
should be fixed.
@@ -427,14 +433,28 @@ topology, which is future work for whoever writes that instance node, not this
427433
template). The container used below (`buzz-relay`) is the same container issue
428434
#1327's template established by the same test it uses (a `[[bin]]` target and
429435
`src/main.rs`); this node reuses that identity rather than re-arguing it, and
430-
maps how its deployment topology genuinely differs across three environments this
431-
repository actually defines:
432-
433-
| Environment | Source | How `buzz-relay` is deployed |
436+
maps its deployment topology across a table whose rows are of two different
437+
kinds: one row is an environment this repository's own `launchpad/ENVIRONMENTS.md`
438+
actually defines, and two rows are not additional cohort-operated environments at
439+
all, but the `deploy/charts/buzz` Helm chart's own two values profiles — `deploy/charts/buzz/README.md`
440+
labels them "Quickstart (eval)" and "Production (GitOps)", and they belong to
441+
upstream Block's chart, not to this fork's own environment list:
442+
443+
| Environment / chart profile | Source | How `buzz-relay` is deployed |
434444
|---|---|---|
435-
| **Local development** | `docker-compose.yml` | `buzz-relay` itself is **not** a service in this file — it runs as a locally built process (`just relay`, per `CLAUDE.md`) against containerized `postgres`, `redis`, `keycloak`, `minio` and `prometheus`, all on one Docker bridge network (`buzz-net`), one instance each, no load balancer, each labeled `com.buzz.env: "dev"`. |
436-
| **Quickstart / eval** | `deploy/charts/buzz`, `quickstart=true` | `buzz-relay` runs as a Kubernetes `Deployment` (from `templates/deployment.yaml`) alongside **bundled, in-cluster** Postgres, Redis and MinIO subcharts; the chart autogenerates relay and service secrets via Helm's `lookup` function; single replica; installed directly with `helm install`, not GitOps. |
437-
| **Production** | `deploy/charts/buzz`, default profile | The same `Deployment` template, but pointed at **external, managed** Postgres/Redis/S3 (`externalPostgresql.url`, `externalRedis.url`, `s3.endpoint`) with `secrets.existingSecret` required rather than chart-generated (chart-side secret generation is unsafe once ArgoCD/Flux render the chart with `helm template`, per the chart's own README); `replicaCount >= 2` for HA; a `RollingUpdate` strategy with `maxUnavailable: 0`; deployed via ArgoCD or Flux GitOps (`examples/argocd-app.yaml`, `examples/flux-helmrelease.yaml`). |
445+
| **Local development** (cohort environment, `launchpad/ENVIRONMENTS.md`, `IMPLEMENTED`) | `docker-compose.yml` | `buzz-relay` itself is **not** a service in this file — it runs as a locally built process (`just relay`, per `CLAUDE.md`) against containerized `postgres`, `redis`, `keycloak`, `minio` and `prometheus`, all on one Docker bridge network (`buzz-net`), one instance each, no load balancer, each labeled `com.buzz.env: "dev"`. |
446+
| **"Quickstart (eval)" chart profile** (`deploy/charts/buzz`'s own profile, not a cohort environment) | `deploy/charts/buzz`, `quickstart=true` | `buzz-relay` runs as a Kubernetes `Deployment` (from `templates/deployment.yaml`) alongside **bundled, in-cluster** Postgres, Redis and MinIO subcharts; the chart autogenerates relay and service secrets via Helm's `lookup` function; single replica; installed directly with `helm install`, not GitOps. |
447+
| **"Production (GitOps)" chart profile** (`deploy/charts/buzz`'s own profile, not a cohort environment) | `deploy/charts/buzz`, default profile | The same `Deployment` template, but pointed at **external, managed** Postgres/Redis/S3 (`externalPostgresql.url`, `externalRedis.url`, `s3.endpoint`) with `secrets.existingSecret` required rather than chart-generated (chart-side secret generation is unsafe once ArgoCD/Flux render the chart with `helm template`, per the chart's own README); `replicaCount >= 2` for HA; a `RollingUpdate` strategy with `maxUnavailable: 0`; deployed via ArgoCD or Flux GitOps (`examples/argocd-app.yaml`, `examples/flux-helmrelease.yaml`). |
448+
449+
This repository's own operated environments — the cohort's real, tracked list —
450+
are `launchpad/ENVIRONMENTS.md`'s four rows (Local development, Local VM harness,
451+
Cohort VPS, Contributors' machines), only one of which (Local development) is
452+
`IMPLEMENTED` today; the other three are `OPEN`. The chart's "Quickstart" and
453+
"Production" profiles are not additional rows on that list — they are two ways
454+
the same upstream Helm chart can be configured, and a real deployment instance
455+
node should map `buzz-relay` against `ENVIRONMENTS.md`'s own rows, citing the
456+
chart profile each one would use, rather than treating the chart's profile names
457+
as environment names in their own right.
438458

439459
**One real discrepancy surfaced and deliberately left unresolved.** The `buzz`
440460
chart's own default `image.repository` is `ghcr.io/block/buzz` — the upstream

‎launchpad/docs/corpus/templates/event-kind.md‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -247,11 +247,16 @@ requirement for the shape of an instance node, not a restatement of any MUST/SHO
247247
normative-policy framework — this document is a template, not a standard, per the
248248
*Scope and authority* note above.)
249249

250-
1. **Title and kind identity.** The kind's name, its integer number, and its exact
250+
1. **Title and kind identity.** The kind's name, its integer number, its exact
251251
constant name in `crates/buzz-core/src/kind.rs` (e.g. `KIND_AGENT_TURN_METRIC =
252-
44200`). If the kind is proposed but not yet implemented, say so explicitly and
253-
name the constant it will need — do not let a reader assume every documented
254-
kind already ships.
252+
44200`), and this node's own front-matter `type: interfaces-events` — the
253+
corpus-surface value `node.schema.json`'s enum reserves for the combined
254+
interface/event surface, the same value the sibling interface template
255+
(`#1342`) states a node built from *its* template carries. State the type
256+
explicitly here rather than leaving an instance author to guess it: `type` is
257+
a closed enum, and a wrong guess hard-fails schema validation. If the kind is
258+
proposed but not yet implemented, say so explicitly and name the constant it
259+
will need — do not let a reader assume every documented kind already ships.
255260

256261
2. **Referenced NIP.** Name the exact specification the kind conforms to: a
257262
numbered NIP in `nostr-protocol/nips` (pin the citation to a commit SHA, per

0 commit comments

Comments
 (0)