@opencodehub/cli 0.2.2 → 0.2.3

package/dist/plugin-assets/skills/codehub-document/references/document-templates.md

@@ -0,0 +1,347 @@
+# document-templates — per-file structural templates
+
+One template per file the artifact factory emits. Subagents consult this reference when drafting; the skill orchestrator uses it to validate Phase E output.
+
+## Conventions
+
+- H1 = identifier (repo name, module name, API section). No decorative titles.
+- No YAML frontmatter on any generated doc.
+- Every factual claim has a backtick citation (`path:LOC` or `repo:path:LOC`).
+- Mermaid only for diagrams; fenced with ```mermaid.
+- "See also" footer is written by Phase E, not by subagents.
+
+## architecture/system-overview.md
+
+```markdown
+# <repo> · System overview
+
+2-paragraph narrative of what the repo does and how the pieces fit.
+Cites `packages/foo/src/index.ts` (200 LOC) style file references.
+
+## Stack
+
+| Layer | Technology | Source |
+|---|---|---|
+| Runtime | Node 22 | `package.json:7` |
+| Storage | DuckDB + hnsw_acorn | `packages/storage/src/index.ts:12` |
+| ... | ... | ... |
+
+## Module map
+
+```mermaid
+flowchart LR
+  cli[CLI]
+  mcp[MCP server]
+  analysis[Analysis]
+  cli --> mcp
+  mcp --> analysis
+```
+
+One Mermaid `flowchart LR`, ≤ 20 nodes.
+```
+
+## architecture/module-map.md
+
+```markdown
+# <repo> · Module map
+
+## <module-1 name>
+
+One-paragraph description. Cites `path:LOC`.
+
+- `packages/module-1/src/index.ts` (320 LOC)
+- `packages/module-1/src/types.ts` (88 LOC)
+- ... top 8 files ...
+
+## <module-2 name>
+
+(same pattern)
+
+## Supporting code
+
+Everything that didn't fit into a named module.
+```
+
+## architecture/data-flow.md
+
+```markdown
+# <repo> · Data flow
+
+## Flow 1: <process-name>
+
+1. Entry point at `packages/cli/src/commands/analyze.ts:14`.
+2. Dispatches to `packages/ingestion/src/phases/*.ts`.
+3. ... numbered steps, each with a backtick citation ...
+
+```mermaid
+sequenceDiagram
+  participant CLI
+  participant Ingestion
+  participant Storage
+  CLI->>Ingestion: run(analyze)
+  Ingestion->>Storage: writeGraph()
+```
+
+## Flow 2: <process-name>
+(same pattern, max 3 flows total)
+```
+
+## reference/public-api.md
+
+```markdown
+# <repo> · Public API
+
+## <exported-symbol-1>
+
+```ts
+export function doThing(input: InputShape): OutputShape
+```
+
+One-sentence description. `packages/foo/src/index.ts:42`.
+
+## <exported-symbol-2>
+(same pattern, top 30 exports)
+```
+
+## reference/cli.md (conditional)
+
+```markdown
+# <repo> · CLI
+
+The `codehub` CLI has the following subcommands.
+
+## analyze
+
+```
+codehub analyze [--incremental] [--quiet]
+```
+
+Runs the ingestion pipeline. `packages/cli/src/commands/analyze.ts:1`.
+
+Flags:
+- `--incremental` — skip unchanged files. `packages/cli/src/commands/analyze.ts:22`.
+- `--quiet` — suppress progress output.
+
+## status
+(same pattern)
+```
+
+## reference/mcp-tools.md (conditional)
+
+```markdown
+# <repo> · MCP tools
+
+## list_repos
+
+Enumerates indexed repos on this machine. No inputs.
+
+Returns `{ repos: [{ name, graph_hash, indexed_at }] }`.
+
+Source: `packages/mcp/src/tools/list-repos.ts:1`.
+
+## query
+(same pattern, one H2 per tool)
+```
+
+## behavior/processes.md
+
+```markdown
+# <repo> · Processes
+
+## <process-1 name>
+
+Entry point: `packages/foo/src/entry.ts:10`.
+
+1. Step 1. `path:LOC`
+2. Step 2. `path:LOC`
+3. Step 3. `path:LOC`
+
+### Related
+
+- `packages/foo/src/helper-1.ts`
+- `packages/foo/src/helper-2.ts`
+
+## <process-2 name>
+(same pattern, max 8 processes)
+```
+
+## behavior/state-machines.md (conditional)
+
+```markdown
+# <repo> · State machines
+
+## <machine-1 name>
+
+```mermaid
+stateDiagram-v2
+  [*] --> Pending
+  Pending --> Running: start()
+  Running --> Done: complete()
+  Running --> Failed: error()
+```
+
+Defined at `packages/foo/src/state.ts:15`.
+```
+
+## analysis/risk-hotspots.md
+
+```markdown
+# <repo> · Risk hotspots
+
+Top 12 files by combined risk score (30-day window).
+
+| File | Trend | Open findings | Top owner | Citation |
+|---|---|---|---|---|
+| packages/foo/src/bar.ts | ↑ rising | 3 warn, 1 error | alice@ | `packages/foo/src/bar.ts` (245 LOC) |
+| ... | ... | ... | ... | ... |
+
+## Per-file drill-down
+
+### packages/foo/src/bar.ts
+
+What's there: (2-sentence summary).
+Recent activity: (from risk_trends).
+Owners: alice@ (68%), bob@ (22%).
+Findings: 3 warn, 1 error — see `list_findings` output.
+```
+
+## analysis/ownership.md
+
+```markdown
+# <repo> · Ownership
+
+| Folder | Top owner | Share | Total contributors |
+|---|---|---|---|
+| packages/mcp | ... | 72% | 4 |
+| ... | ... | ... | ... |
+
+## Single points of failure
+
+Paths where the top owner has > 70% of commits.
+
+- `packages/mcp/src/resources/` — alice@ (82%). No secondary reviewer.
+- ... (each with a 1-sentence mitigation suggestion)
+```
+
+## analysis/dead-code.md
+
+```markdown
+# <repo> · Dead code
+
+## Unreferenced exports
+
+| Symbol | Path | Last modified |
+|---|---|---|
+| oldHelper | packages/foo/src/helpers.ts:120 | 2024-11-03 |
+| ... | ... | ... |
+
+## Unreferenced files
+
+| File | Lines | Last modified |
+|---|---|---|
+| packages/legacy/src/deprecated.ts | 88 | 2024-08-12 |
+
+## Dead imports
+
+| Path | Symbol | Imported from |
+|---|---|---|
+| packages/foo/src/index.ts:3 | legacy | packages/legacy |
+```
+
+## diagrams/ — three files
+
+Each has exactly one Mermaid diagram (plus optional Legend table when node count was truncated). See `mermaid-patterns.md` for idioms.
+
+- `diagrams/architecture/components.md` — `classDiagram`.
+- `diagrams/behavioral/sequences.md` — up to 3 `sequenceDiagram` blocks.
+- `diagrams/structural/dependency-graph.md` — `flowchart LR`.
+
+## cross-repo/ — group mode only
+
+### cross-repo/portfolio-map.md
+
+```markdown
+# <group> · Portfolio map
+
+2-paragraph narrative of the group's shape (domain, member purposes, shared contracts).
+
+## Member repos
+
+```mermaid
+flowchart LR
+  billing --> core
+  web --> core
+  web --> billing
+```
+
+## Repos
+
+### billing — <one-line description>
+
+Citations: `billing:packages/api/src/index.ts:1` (120 LOC).
+[See billing docs →](../../billing/.codehub/docs/README.md)
+
+### core — <one-line description>
+(same pattern)
+```
+
+### cross-repo/contracts-matrix.md
+
+```markdown
+# <group> · Contracts matrix
+
+Rows = producers; columns = consumers. Cell = number of contracts.
+
+|       | billing | core | web |
+|-------|---------|------|-----|
+| billing | —     | 3    | 5   |
+| core  | —       | —    | 12  |
+| web   | —       | —    | —   |
+
+## Notable contracts
+
+- `billing:packages/api/src/handlers/invoice.ts:45` ← consumed by `web:packages/checkout/src/api.ts:22`.
+- ... (top 10 with direction + path + both-ends citations)
+```
+
+### cross-repo/dependency-flow.md
+
+```markdown
+# <group> · Dependency flow
+
+```mermaid
+flowchart TB
+  web["web"]
+  billing["billing"]
+  core["core"]
+  web -->|POST /invoices| billing
+  web -->|GET /user| core
+  billing -->|publishes| events[(events.stream)]
+  core -.->|consumes| events
+```
+```
+
+## README.md (Phase E output)
+
+```markdown
+# <repo-or-group> · Generated documentation
+
+*Prose is LLM-generated; structure is graph-derived. Phase E cross-references are deterministic.*
+
+Generated at: 2026-04-27T18:12:04Z
+Graph hash: sha256:…
+
+## Structure
+
+- [Architecture](architecture/system-overview.md)
+- [Reference](reference/public-api.md)
+- [Behavior](behavior/processes.md)
+- [Analysis](analysis/risk-hotspots.md)
+- [Diagrams](diagrams/architecture/components.md)
+- [Cross-repo](cross-repo/portfolio-map.md)    ← group mode only
+
+## Refreshing
+
+Run `/codehub-document --refresh` to regenerate stale sections only.
+Run `/codehub-document` without flags for a full regen.
+```

package/dist/plugin-assets/skills/codehub-document/references/mermaid-patterns.md

@@ -0,0 +1,181 @@
+# mermaid-patterns — diagram idioms
+
+One diagram type per artifact. Diagrams capped at 20 nodes; overflow goes into a Legend table, never into the diagram. All Mermaid fenced with ```mermaid.
+
+No SVG or PNG generation. Ever.
+
+## Dependency graph — `flowchart LR`
+
+For `diagrams/structural/dependency-graph.md`. Internal communities as filled nodes; external deps as leaf nodes with a distinct style.
+
+```mermaid
+flowchart LR
+  mcp[MCP server]
+  core[Core types]
+  ingestion[Ingestion DAG]
+  storage[Storage]
+  duckdb[(DuckDB)]:::external
+  mcp --> core
+  ingestion --> core
+  ingestion --> storage
+  storage --> duckdb
+  classDef external stroke-dasharray: 3 3
+```
+
+**Rules:**
+- Max 20 nodes.
+- Internal communities: plain rectangles with brackets.
+- External deps: parenthesized shape `node[(name)]:::external` + dashed stroke class.
+- Overflow nodes go into a Legend table below the fenced block.
+
+## Component view — `classDiagram`
+
+For `diagrams/architecture/components.md`. Shows has-a and uses relationships between top components.
+
+```mermaid
+classDiagram
+  class CLI {
+    +analyze()
+    +status()
+    +verdict()
+  }
+  class MCPServer {
+    +registerTools()
+  }
+  class IngestionDAG {
+    +runPhases()
+  }
+  CLI --> MCPServer : invokes
+  CLI --> IngestionDAG : triggers
+  MCPServer --> IngestionDAG : depends
+```
+
+**Rules:**
+- Max 8 components.
+- 3–5 methods per class, chosen by call-count from the graph.
+- Relationships labeled with a one-word verb.
+
+## Top process — `sequenceDiagram`
+
+For `diagrams/behavioral/sequences.md`. One diagram per top process, up to 3.
+
+```mermaid
+sequenceDiagram
+  participant User
+  participant CLI
+  participant MCP
+  participant Storage
+  User->>CLI: codehub analyze
+  CLI->>MCP: register(tools)
+  MCP->>Storage: write(graph)
+  Storage-->>MCP: graph_hash
+  MCP-->>CLI: ready
+  CLI-->>User: analyzed N files
+```
+
+**Rules:**
+- 4–8 participants per diagram.
+- Lifelines in dispatch order.
+- Solid arrows for calls, dashed for returns.
+
+## State machine — `stateDiagram-v2`
+
+For `behavior/state-machines.md` (conditional).
+
+```mermaid
+stateDiagram-v2
+  [*] --> Pending
+  Pending --> Running: start()
+  Running --> Done: complete()
+  Running --> Failed: error()
+  Failed --> Pending: retry()
+  Done --> [*]
+```
+
+**Rules:**
+- Every transition labeled with the triggering event.
+- `[*]` entry/exit always present.
+
+## Data flow — `flowchart TB`
+
+For `architecture/data-flow.md`.
+
+```mermaid
+flowchart TB
+  source[Repo files]
+  parse[tree-sitter parser]
+  graph[DuckDB graph]
+  embed[ONNX embedder]
+  query[MCP query]
+  source --> parse
+  parse --> graph
+  parse --> embed
+  embed --> graph
+  query --> graph
+```
+
+**Rules:**
+- Top-to-bottom flow (`TB`).
+- Stores as rectangular bracket nodes; processes as simple bracket nodes; external interfaces as parenthesized nodes.
+
+## Cross-repo portfolio — `flowchart LR`
+
+For `cross-repo/portfolio-map.md` (group mode).
+
+```mermaid
+flowchart LR
+  billing["billing<br/>payment domain"]
+  core["core<br/>shared types + auth"]
+  web["web<br/>customer-facing UI"]
+  web -->|contracts: 5| billing
+  web -->|contracts: 12| core
+  billing -->|contracts: 3| core
+```
+
+**Rules:**
+- Node labels include a one-line domain description (use `<br/>` for the second line).
+- Edge labels include the contract count from `group_contracts`.
+
+## Cross-repo dependency flow — `flowchart TB`
+
+For `cross-repo/dependency-flow.md` (group mode).
+
+```mermaid
+flowchart TB
+  web["web"]
+  billing["billing"]
+  core["core"]
+  events[(events.stream)]
+  web -->|POST /invoices| billing
+  web -->|GET /user| core
+  billing -->|publishes| events
+  core -.->|consumes| events
+```
+
+**Rules:**
+- Nodes are repos; events/queues are parenthesized shape.
+- Edge labels are the HTTP verb + path (for routes) or the event type (for streams).
+- Dashed edges for async/pub-sub; solid for synchronous calls.
+
+## Legend tables
+
+When a diagram exceeds 20 nodes, keep the top-20-by-edge-count in the diagram and add a Legend table immediately below:
+
+```markdown
+## Legend (overflow)
+
+These nodes were elided from the diagram above for readability:
+
+| Node | Edges | Reason for elision |
+|---|---|---|
+| peripheral-module-1 | 3 | Too few edges |
+| deprecated-thing | 2 | Slated for removal |
+```
+
+## Diagram label length rules
+
+Mermaid breaks on long labels. Keep them short:
+
+- Node labels: ≤ 20 characters (excluding explicit `<br/>`).
+- Edge labels: ≤ 15 characters.
+- Use abbreviations liberally; spell the full name in a Legend table.

package/dist/plugin-assets/skills/codehub-document/templates/agents/README.md

@@ -0,0 +1,64 @@
+# templates/agents — per-file packet skeletons
+
+Each `.md` file here is a **packet skeleton** for one output document produced by `codehub-document`. The skill orchestrator seeds one packet per output file by copying a skeleton to `<docs-root>/.packets/<file-role>.md`, substituting placeholders, and spawning a `general-purpose` subagent with a short prompt that points at the packet path.
+
+## Contract
+
+Every skeleton follows the same shape, ported from `erpaval/templates/session/task-skeleton.md` and adapted for doc-writing:
+
+```yaml
+---
+role: <file-role>                         # doc-architecture-system-overview, doc-reference-public-api, ...
+model: sonnet                             # overridable by the orchestrator
+output: "{{ docs_root }}/<path>.md"       # exactly one file per packet
+depends_on:
+  - "{{ context_path }}"                  # .codehub/docs/.context.md (or equivalent)
+  - "{{ prefetch_path }}"                 # .codehub/docs/.prefetch.md
+status: IN_PROGRESS
+---
+```
+
+Then ten numbered sections, in order, using the ERPAVal `<write_protocol>` discipline:
+
+1. **Objective** — one sentence: the single file this packet produces and why it exists.
+2. **Scope** — the exact output path; any other paths the subagent is *not* allowed to touch.
+3. **Input specification** — source MCP tools / files, each marked `cached` (read from `.prefetch.md`) or `mid-run` (subagent may call).
+4. **Process** — numbered steps from read-shared-context → draft → write.
+5. **Document format rules** — H1 shape, citation grammar, diagram rules, "no YAML frontmatter on outputs".
+6. **Tool usage guide** — a short table mapping need → tool → why.
+7. **Fallback paths** — what to do when a tool returns empty / errors / is stale.
+8. **Success criteria** — mechanical checks the subagent validates before flipping `status: COMPLETE`.
+9. **Anti-goals** — common failure modes to avoid (re-calling cached tools, inventing edges, hallucinating symbol names).
+10. **Work log / Validation / Summary** — three trailing sections the subagent edits during execution per the write protocol.
+
+## Placeholders
+
+Filled by the orchestrator at seed time. Common to every skeleton:
+
+| Placeholder | Example value (single-repo) | Example value (group mode) |
+|---|---|---|
+| `{{ docs_root }}` | `.codehub/docs` | `.codehub/groups/<group>/docs` |
+| `{{ repo }}` | `opencodehub` | member repo name |
+| `{{ context_path }}` | `.codehub/docs/.context.md` | `.codehub/groups/<group>/docs/.context.md` |
+| `{{ prefetch_path }}` | `.codehub/docs/.prefetch.md` | `.codehub/groups/<group>/docs/.prefetch.md` |
+| `{{ packet_path }}` | `.codehub/docs/.packets/doc-architecture-system-overview.md` | `.codehub/groups/<group>/docs/.packets/...` |
+| `{{ graph_hash }}` | `sha256:a1b2c3…` | (same) |
+
+Cross-repo skeletons add:
+
+| Placeholder | Example |
+|---|---|
+| `{{ group }}` | `platform` |
+| `{{ group_docs_root }}` | `.codehub/groups/platform/docs` |
+
+## Spawn prompt
+
+The orchestrator spawns each subagent with the prompt in `../orchestrator-prompt.md`. That prompt is deliberately short — all role-specific instructions live in the packet itself.
+
+## Write protocol
+
+Every skeleton embeds the doc-variant `<write_protocol>` block verbatim. The rhythm is "read tool output → Write output file → edit packet section with the outcome" (vs. ERPAVal's "read code → edit code → run check → edit packet").
+
+## Why file-level, not role-level
+
+One packet = one output file. Blast radius of a failing subagent is one file. `--refresh` and `--section` become trivial 1-subagent dispatches. `.docmeta.json.sections[i].agent` still records the role for auditability.

package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-analysis-dead-code.md

@@ -0,0 +1,104 @@
+---
+role: doc-analysis-dead-code
+model: sonnet
+output: "{{ docs_root }}/analysis/dead-code.md"
+depends_on:
+  - "{{ context_path }}"
+  - "{{ prefetch_path }}"
+status: IN_PROGRESS
+---
+
+# Packet · {{ repo }} · analysis/dead-code.md
+
+## 1. Objective
+
+Produce `{{ docs_root }}/analysis/dead-code.md`: three tables enumerating unreferenced exports, unreferenced files, and dead imports in `{{ repo }}`. The file is always emitted — when the graph reports no dead code, emit a `No unreferenced symbols detected.` banner plus a timestamp so Phase E cross-references have a stable target.
+
+## 2. Scope
+
+- Create: `{{ docs_root }}/analysis/dead-code.md`
+- Do not touch: `{{ docs_root }}/analysis/risk-hotspots.md`, `{{ docs_root }}/analysis/ownership.md`, any other file under `{{ docs_root }}/`, any source file in the repo, `.context.md`, `.prefetch.md`, or any `.packets/*.md` other than this one.
+
+## 3. Input specification
+
+| Source | Read how | Cache state |
+|---|---|---|
+| Shared context | `Read {{ context_path }}` | always first |
+| Prefetch ledger | `Read {{ prefetch_path }}` | always first |
+| Dead-code inventory | `mcp__opencodehub__list_dead_code({repo: "{{ repo }}"})` | mid-run (rarely cached; the tool is cheap) |
+| Last-modified per path | from `list_dead_code` response fields when present, else `git log -1 --format=%cs -- <path>` via shell | mid-run |
+| Graph hash | `{{ graph_hash }}` for the empty-state banner timestamp anchor | cached |
+
+## 4. Process
+
+1. `Read {{ context_path }}` and `Read {{ prefetch_path }}`. Confirm graph hash and any cached dead-code digest.
+2. Call `mcp__opencodehub__list_dead_code({repo: "{{ repo }}"})`. Partition the response into three buckets: `Unreferenced exports`, `Unreferenced files`, `Dead imports`.
+3. If all three buckets are empty: skip to step 7 (empty-state banner).
+4. For `Unreferenced exports`: draft a table with columns `Symbol | Path | Last modified`. Path is a backtick `path:LOC`. Last modified is an ISO date.
+5. For `Unreferenced files`: draft a table with columns `File | Lines | Last modified`. File is a backtick `path`. Lines is an integer LOC count.
+6. For `Dead imports`: draft a table with columns `Path | Symbol | Imported from`. Path is a backtick `path:LOC` at the import site; Imported from is a backtick `path` (module/package).
+7. Empty-state handling: if `list_dead_code` returns no rows in any bucket, emit the banner `No unreferenced symbols detected.` on its own line, followed by `Graph hash: {{ graph_hash }}` and a UTC timestamp line. Still emit the three H2 headings (`## Unreferenced exports`, `## Unreferenced files`, `## Dead imports`) each with a single `_none_` line under them, so Phase E cross-references resolve.
+8. `Write {{ docs_root }}/analysis/dead-code.md` with H1 = `{{ repo }} · Dead code`.
+
+## 5. Document format rules
+
+- H1 = `{{ repo }} · Dead code`. No decorative titles.
+- No YAML frontmatter on the output file.
+- Three H2s in this fixed order: `## Unreferenced exports`, `## Unreferenced files`, `## Dead imports`.
+- `Unreferenced exports` table columns: `Symbol | Path | Last modified`.
+- `Unreferenced files` table columns: `File | Lines | Last modified`.
+- `Dead imports` table columns: `Path | Symbol | Imported from`.
+- Every Path / File / Imported from cell is a backtick `path` or `path:LOC`.
+- Empty-state banner is a single line `No unreferenced symbols detected.` followed by `Graph hash: {{ graph_hash }}` and a UTC timestamp.
+- Under the empty state, each of the three H2 sections contains a single `_none_` line.
+- No emojis. No filler adverbs.
+
+## 6. Tool usage guide
+
+| Need | Tool | Why |
+|---|---|---|
+| Unreferenced symbols + files | `mcp__opencodehub__list_dead_code` | graph-aware; deletes are safe |
+| Last-modified per path | `list_dead_code` fields, else `git log -1` shell | graph does not always carry mtime |
+| LOC per unreferenced file | `Read` then line count | graph stores node spans, not file LOC |
+| Cross-check at import site | `Read` at `path:LOC` | verify import survives before listing as dead |
+
+## 7. Fallback paths
+
+- If `list_dead_code` errors or times out: write the failure to the Work log, retry once, and on a second failure emit the empty-state banner with an added line `*list_dead_code unavailable — re-run after codehub analyze*`. The file must still exist.
+- If `list_dead_code` returns an `Unreferenced exports` row whose symbol is actually re-exported from a barrel (false positive): `Read` the barrel and drop the row, citing the removal in the Work log.
+- If a `Last modified` field is missing from the response: run `git log -1 --format=%cs -- <path>` via the shell; if that also fails, use `—` in the cell and note in the Work log.
+- If all three buckets are empty, always follow the step-7 empty-state flow; do not skip the Write step.
+
+## 8. Success criteria
+
+- [ ] `{{ docs_root }}/analysis/dead-code.md` exists on disk (even when empty).
+- [ ] H1 line reads `# {{ repo }} · Dead code`.
+- [ ] All three H2 headings exist in the fixed order `Unreferenced exports`, `Unreferenced files`, `Dead imports`.
+- [ ] Every populated table row has a backtick path citation in its Path/File/Imported-from column.
+- [ ] When all three buckets are empty: the banner `No unreferenced symbols detected.` appears once, the graph hash is cited, and each H2 contains `_none_`.
+- [ ] When tables have rows: column headers match the fixed schema in Section 5.
+- [ ] No YAML frontmatter on the output.
+- [ ] No row cites a symbol absent from `list_dead_code` output (spot-check 3).
+
+## 9. Anti-goals
+
+- Do not re-call `list_dead_code` inside the same packet run — one call, then cache in the Work log.
+- Do not invent unreferenced symbols, files, or imports — every row must map to a `list_dead_code` response entry.
+- Do not omit the three H2 headings when buckets are empty; the skeleton must stay consistent for Phase E.
+- Do not delete the file or skip the Write step when buckets are empty — the banner is the product in that case.
+- Do not write YAML frontmatter on the output file.
+- Do not emit emojis.
+
+---
+
+## Work log
+
+{{ subagent fills this section per the write protocol }}
+
+## Validation
+
+{{ checks run, outputs pasted, any fixes applied }}
+
+## Summary
+
+{{ one paragraph — what shipped, row counts per bucket, whether the empty-state path was taken }}