docs(corpus): add deployment corpus template

[serina-mcfall]

What

Adds launchpad/docs/corpus/templates/deployment.md
(id: corpus-template-deployment) — the corpus template for a system's
deployment view: which container instances run on what infrastructure, in
which named environment, and how that mapping changes across environments,
per PRD #605.

Closes #1336

Issue type

Task

Note on this issue's definition of done

Issue #1336's Definition of Done carries a MUST/SHOULD/enforcement/exception
checklist copied verbatim from the standards-track issues (the ones that
produced standards/confidence.md and standards/decision-references.md).
That checklist describes a policy/standard node, not a template. This node is
built against #605's actual template acceptance criterion instead: every
template states its purpose, required sections, evidence expectations and the
industry model/standard it adapts. The rest of #1336's checklist (one
hand-authored document, schema-valid front matter, one independently
maintainable idea, traceable FACT/INFERENCE/TEAM_KNOWLEDGE claims, links
instead of duplication, checked against the recorded revision, clean validator
run) is generic to any corpus node and is honoured as written. The document's
own "Scope and authority" section states this same note in place — the
identical situation batch 1's architecture-container template (#1327, PR
#1529) records for itself.

type choice

Used type: governance. node.schema.json's enum has no template or
policy value (PRD #602's corpus-surface list only). Checked
schema/README.md and schema/COMPATIBILITY.md directly, not just the
brief — neither names a template- or policy-specific enum value.
governance matches every existing corpus meta-document except AGENTS.md
(type: agent): README.md, standards/confidence.md,
standards/decision-references.md.

The node's own evidence ledger separately reasons about what a real
instance written from this template would use: most plausibly
type: architecture, reasoned against two considered-and-set-aside
alternatives — type: platforms (this repository's own sense of "platforms"
is client platforms — desktop/web/mobile — not infrastructure) and
type: operations (independently claimed for the sibling runbook template,
#1347, by its own PR #1527, which states operations is "the natural fit for
an operational document" — a different kind of subject than a structural
view). This template document itself is not such an instance.

Relationships

Declared none, and checked before deciding that rather than assuming it.
git ls-tree -r --name-only origin/launchpad -- launchpad/docs/corpus at
commit a44cf52fc740ebebbdd671427480d14f0bce0115 shows exactly four
validated content nodes: corpus-agents, corpus-readme,
corpus-standard-confidence, corpus-standard-decision-references
(schema/ excluded from validation). None has deployment, infrastructure,
environments, arc42 or C4 as its subject, so an edge to any of them would be a
citation duplicate of what the evidence ledger already cites directly, not a
substantive typed relationship. The document's own "Scope and omissions"
section names the most likely future edges (depends-on targeting a merged
architecture-container instance; implements targeting a future per-type
diagram standard, #1312, once it merges) and explains why no sibling
architecture/template node can be targeted today — all are being authored in
parallel with none merged when review starts on the others.

One relationship question is deliberately left open rather than forced: the
document's "Relationships an instance node should consider" section explains
why a part-of edge from a deployment view to an architecture-context view is
not obviously the right shape (the C4 source places Deployment outside the
context→container→component hierarchy part-of was modeled on for the
container template), and leaves that for a future author with two real
instances in hand rather than resolving it in the abstract here.

Research-note grounding

launchpad/Research/project-documentation-templates.md (unmerged PR #1466)
lists arc42's twelve sections including "7. Deployment View" and states the
C4 model's diagrams are "diagrams, not prose" that "slots into arc42 §3/§5/§7
rather than competing with it" — naming §7 as one of the sections C4's
diagrams slot into, though the note never itself elaborates on the Deployment
diagram or the container/deployment boundary. Cited as TEAM_KNOWLEDGE
attributed to launchpad-26/buzz#1466 (unmerged research note), never
FACT, per the batch brief.

Everything else this document asserts about arc42 and C4 was independently
fetched and read from the primary sources
(arc42.org/overview, docs.arc42.org/section-7/, c4model.com/,
c4model.com/diagrams/deployment, c4model.com/abstractions/container) and
cited as FACT against those URLs — including the container/deployment
boundary itself, which rests on c4model.com's own worked example (three web
applications sharing one Tomcat server in development, each on a dedicated
server in production, remaining "the same C4 container" throughout, "with the
deployment being a separate concern").

The already-open architecture-container PR (#1529, issue #1327) was read in
full (gh pr view/gh pr diff) per the batch brief's specific instruction,
so this document does not restate its container-vs-deployment reasoning. One
self-review correction is worth flagging here: an earlier draft of this
document's evidence ledger attributed an elaborate boundary framing to #1529
as if it were a direct quote; on re-checking #1529's actual diff text, that
elaborate framing was this document's own synthesis of the C4 primary source
(already cited separately as FACT), not something #1529 itself states in
those words. The ledger entry was corrected to quote #1529's actual, terser
language and attribute the synthesis to this document instead.

Worked illustration

The document's "What counts as a deployment node..." section includes a
worked, evidence-checked illustration mapping the same container
(buzz-relay, whose C4-container identity issue #1327's template
established) across three environments this repository actually defines:
local development (docker-compose.yml, relay run outside the compose file
per CLAUDE.md's just relay), quickstart/eval (deploy/charts/buzz,
quickstart=true, bundled in-cluster dependencies), and production
(deploy/charts/buzz, default profile, external managed dependencies,
GitOps via ArgoCD/Flux). It also surfaces and deliberately leaves unresolved
a real discrepancy: the chart's default image.repository is
ghcr.io/block/buzz while this fork's own Dockerfile/docker.yml publish
to ghcr.io/launchpad-26/buzz — named as a gap in the node's own
"Expected but not verified" section rather than silently resolved either way.

Verify-gate and validator evidence

$ python3 -m unittest discover -s launchpad/docs/corpus/schema/tests -p "test_*.py" -v
...
Ran 27 tests in 0.033s

OK

Run as a lone command from this worktree immediately before commit, nothing
piped or redirected; the pre-commit hook's .claude/.verified gate accepted
the commit.

$ python3 launchpad/project-intelligence/corpus/validate.py
...
PASS  corpus validation found no errors; 15 item(s) reported unverified

All 15 UNVERIFIED notices are the expected shapes (commit-reference
provenance citations, and external URLs to arc42.org/docs.arc42.org/c4model.com
that the validator can't pin or open) — none are errors.

Process notes

• Self-review (dispatched as an independent adversarial pass against the
  actual repository files and the actual text of PR docs(corpus): add architecture-container template #1529/docs(corpus): define the runbook corpus template #1527/issues
  feature: documentation corpus contract is executable #605/task: define the deployment corpus template #1336/task: the mandatory cross-model review gate has a single provider, and it is unavailable #1467, not just this document's own claims) found and this PR
  fixes four real defects before opening: (1) the docs(corpus): add architecture-container template #1529 boundary-attribution
  issue described above; (2) a buzz-relay-is-a-container claim classified
  entirely as TEAM_KNOWLEDGE even though the underlying files
  (crates/buzz-relay/Cargo.toml, src/main.rs) were independently
  re-opened for this node — split into a proper FACT citing those two
  files directly, plus a separate TEAM_KNOWLEDGE entry for the
  attribution to docs(corpus): add architecture-container template #1529's own established identification; (3) the
  Dockerfile/docker.yml trigger FACT omitted workflow_dispatch and the
  pull_request path filter, understating what the workflow's own on:
  block says — corrected to name all three trigger kinds; (4) two
  INFERENCE entries and one TEAM_KNOWLEDGE entry about a future
  instance's likely type value had no corresponding body-prose section —
  added a short paragraph to "Scope and authority" connecting them, rather
  than leaving the claim only in the ledger.
• Cross-model review was not run. Issue task: the mandatory cross-model review gate has a single provider, and it is unavailable #1467 records the cross-model review
  provider (Codex) as currently unavailable (out of credits, confirmed
  twice, no other external-model CLI installed); a same-model
  (self-adversarial) review pass was substituted, per the batch brief.

Escalations

None filed. No finding from self-review fell outside this node's own scope —
all four were defects in this document's own evidence ledger, fixed directly
per the "Blocker → fix now" branch of the batch brief's findings policy.

[tucktuck101]

Review — deployment corpus template

Every external citation I sampled holds (arc42 overview and §7, C4 home/deployment/container,
Mermaid syntax reference) and the Helm-profile facts are accurate. But this template instructs
every future deployment node to record exactly the class of detail this repository forbids in
tracked files, and nothing in its 588 lines says not to.

Blocking — nothing forbids recording private hostnames, endpoints, registry paths or credentials

Required section 5 (:356-360) makes it a MUST to record "One row per deployment node (a host,
VM, Kubernetes cluster or namespace, PaaS instance) and per infrastructure node (load balancer,
ingress, DNS, firewall) shown in the diagram(s): its name, its kind, and a one-line statement
of what runs on it or what it fronts." Section 4 requires a per-environment column for "how secrets
are provisioned". The evidence rules at :437-441 push authors off README prose and onto "a
Terraform/Pulumi resource" and "a CI/CD pipeline step that provisions it", and :447-458 tells them
to state what a private repository's documentation says, naming squareup/block-coder-tf-stacks.

I searched all 588 lines for must not (record|include|name|paste|quote), do not (record|include|paste|quote) and redact: zero matches. There is no rule anywhere against
recording a private hostname, cluster endpoint, internal registry path, IP or credential, and no
safe-reference convention offered in their place.

That contradicts three merged cohort documents:

• launchpad/AGENTS.md:332-334 — "This repository is public. Every file you commit is
  world-readable. Config is fine; credentials never are." and "Never add a secret, key, token, or
  private hostname to a tracked file."
• launchpad/ENVIRONMENTS.md:29-30 — "No hostnames. AGENTS.md §8 forbids private hostnames in
  tracked files, and the VPS hostname is not decided anyway."
• launchpad/SECURITY-POSTURE.md:185-198 — "being concrete is how operational detail reaches a
  world-readable file" and "Nothing detects a violation of section 8 ... Compliance therefore rests
  on the attention of whoever is writing."

That last line is why this is blocking rather than medium: there is no automated backstop, so the
template is the control. Every future deployment node inherits this instruction.

Fix: add a "What must never be recorded" rule before section 4, and a safe-reference convention the
inventory columns point at — record the role and the configuration key, never the value (e.g. "the
managed Postgres addressed by externalPostgresql.url, credentials held in the cluster Secret named
by secrets.existingSecret"). Extend the same rule to the Terraform/CI evidence citations at
:437-441 and :447-458, citing launchpad/AGENTS.md §8 the way ENVIRONMENTS.md:29 does.

Medium — upstream chart profiles are presented as this fork's environments

:404-411 says the worked table maps "three environments this repository actually defines" — Local
development, Quickstart / eval, Production. The merged cohort document that owns where Buzz runs is
launchpad/ENVIRONMENTS.md:20-27, and its four rows are Local development (IMPLEMENTED),
Local VM harness (OPEN, #17/#19), Cohort VPS (OPEN, #21/#22) and Contributors' machines
(OPEN, #43). Neither ENVIRONMENTS.md nor the cohort VPS appears anywhere in this node.

"Quickstart / eval" and "Production" are deploy/charts/buzz's two values profiles — upstream
Block's chart, as your own ghcr.io/block/buzz finding shows — and the ArgoCD/staging-cluster path
is upstream's pipeline in private repos, not the cohort's. Every individual fact in the table is
true; the framing would lead a first instance author to document a "Production" Kubernetes
deployment the cohort does not operate. Relabel rows two and three as chart profiles, and add
launchpad/ENVIRONMENTS.md to the Scope-and-authority pointer table as owner of the environment
list.

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.

[serina-mcfall]

Blocking finding resolved: secrets/hostnames rule added to the deployment template

Re-verified tucktuck101's CHANGES_REQUESTED review (commit 5a5197574, submitted 2026-08-27T16:38:52Z) against the current branch head before making any change — the Blocking finding was still live: nothing in the 588-line template forbade recording a live secret, hostname, endpoint, or credential value.

Blocking (fixed in bdceddfb2): Added required section 4, "Secrets and sensitive values," to deployment.md's Required sections list — modeled on configuration.md's (#1543) Secrets discipline section. It:

• Forbids recording a live secret, key, token, credential, or private hostname/endpoint value anywhere in a deployment node, citing launchpad/AGENTS.md §8 ("Never add a secret, key, token, or private hostname to a tracked file") and launchpad/SECURITY-POSTURE.md's point that no automated check catches a §8 violation.
• Gives the safe-reference convention the review asked for: name the role and the configuration reference (a Helm value, a Secret name, a Terraform/Pulumi resource) never the literal value.
• Extends into the environment inventory and node inventory items (now 5 and 6) and into Evidence expectations' Terraform/CI citation guidance (the :437-441 and :447-458 spans the review flagged), including the case of citing what another repository's own documentation says.

Remaining required sections renumbered 5-8 accordingly.

Medium (upstream Helm profiles presented as this fork's environments): left untouched, per the task's instruction — already tracked as #1713.

launchpad/project-intelligence/corpus/validate.py: PASS, no new errors. Unit test suite (test_validate.py, 79 tests): all passing.