specpipe 1.0.0

package/templates/skills/sp-spec-render/SKILL.md

@@ -0,0 +1,254 @@
+---
+description: |
+  Render spec markdown (single or multi-spec feature) into a self-contained,
+  scannable HTML file: sidebar TOC with scroll-spy, story cards with P-badges,
+  collapsible Given/When/Then for each AS, constraint callouts, dark/light theme,
+  search filter.
+
+  Use when asked to "render spec", "xem spec đẹp", "spec html", "tạo view cho spec",
+  "preview spec", or after /sp-plan finishes writing or updating a spec.
+
+  This skill is user-invoked, not auto-called. /sp-plan only writes the spec
+  markdown — it suggests this command at the end so the user chooses whether
+  to generate the HTML view.
+
+  Proactively suggest this skill when the user is reading a long spec markdown
+  in chat ("hard to scan", "lots to read") or after a Mode C update has made
+  any existing <feature>.html stale.
+
+  Skip for files that are not specs (investigation, explore doc, RFC, retro,
+  README) — those go to the generic sibling skill [[sp-md-render]] instead.
+
+  Idempotent: re-rendering overwrites the previous .html. Safe to run anytime.
+allowed-tools: Read, Write, Bash, Glob, Grep
+---
+
+Render `docs/specs/<feature>/<feature>.md` (plus sub-specs if any) into a self-contained `<feature>.html`.
+
+The source `.md` is the truth. The HTML is a **view layer**: regenerable, never hand-edited. Target output token cost ≈ source markdown size × 1.2 — `template.html` and `components.md` are read-only inputs (cached across calls), and CSS/JS never enters the output token stream.
+
+---
+
+## Inputs
+
+`$ARGUMENTS` may be:
+
+- **Feature slug** (`customer-onboarding`) — resolves to `docs/specs/<slug>/<slug>.md`
+- **Path to a root spec** (`docs/specs/billing/billing.md`) — renders that directory
+- **Path to a directory** (`docs/specs/billing/`) — renders that directory
+- **`--all`** — bulk re-render every `docs/specs/*/<name>/<name>.md`
+- **Empty** — list all `docs/specs/*/` and prompt the user to pick
+
+In every case, output is written to `<spec-dir>/<feature>.html` and overwrites any existing file.
+
+---
+
+## Skill files (read once before generating)
+
+Resolved relative to this `SKILL.md`:
+
+- `template.html` — HTML skeleton with embedded CSS, JS, and SVG sprite. Contains `{{PLACEHOLDER}}` strings and `<!-- TOC_ENTRIES -->`, `<!-- CONTENT_START -->`, `<!-- CONTENT_END -->` slots. **Read once, never modified.**
+- `components.md` — Catalog of 11 HTML snippets to copy verbatim. **Read once.**
+- `examples/user-auth.md` + `examples/user-auth.html` — Reference input/output pair. Read one pair to calibrate quality before rendering.
+
+**Read all three before producing any output.** Do not invent CSS classes, do not generate component markup from scratch, do not add new `<style>` or `<script>` tags.
+
+---
+
+## Workflow
+
+### Step 1 — Resolve inputs
+
+1. Parse `$ARGUMENTS` to determine the spec directory.
+2. List files: `ls docs/specs/<feature>/*.md` — distinguish the root spec (`<feature>.md`) from sub-specs (`<feature>-*.md`).
+3. List `snapshots/` if present (for the Snapshots section).
+4. Read the root spec fully. Read each sub-spec fully.
+5. Read `template.html`, `components.md`, and one example pair.
+
+**Classify layout:**
+
+| # | Condition | Layout |
+|---|-----------|--------|
+| L1 | Root spec only, no sub-specs | **Single-spec** — each `## H2` becomes a section; sidebar groups: "Overview" + "Reference" |
+| L2 | Root + 1 or more sub-specs | **Multi-spec** — each sub-spec becomes a section with `.subspec-head`; sidebar groups by sub-spec name |
+
+### Step 2 — Parse each spec.md
+
+For each `.md`, extract:
+
+- **Frontmatter:** `**Created**`, `**Last updated**`, `**Status**`, `**Snapshot limit**` (regex the `**Key:** value` lines at the top of the file).
+- **Overview** paragraph (the text under `## Overview`).
+- **Sub-specs table** (root only, optional) — list rows `[name](./path)` + scope.
+- **Data Model** section (root, optional).
+- **Stories** — each `### S-NNN: Title (Pn)` produces a story object with:
+  - `id` (S-NNN, namespaced by sub-spec slug in multi-spec layout)
+  - `priority` (P0/P1/P2 from the `(Pn)` suffix)
+  - `title`
+  - `description` (the paragraph after `**Description:**`)
+  - `applies_constraints` (the `C-NNN` list after `**Applies Constraints:**`, if the story has that line — optional)
+  - `acceptance_scenarios[]` — each `AS-NNN:` produces an object with `id`, `desc` (the 1-line summary after the ID), `given`, `when`, `then`, `data` (optional), `setup` (optional)
+- **Constraints** — each constraint (a line `C-NNN:` OR a bullet `- C-NNN:` / `- **C-NNN:**`) becomes a callout. A **cross-surface invariant** carries indented `scope:` / `surfaces:` / `coverage:` sub-lines (e.g. `coverage: createIntent → AS-008, pay → GAP-001`) — capture them so the callout can show per-surface coverage. If a single spec has more than 10, group them collapsed by sub-spec.
+- **What Already Exists** — paragraph or bullet list.
+- **Not in Scope** — bullet list.
+- **Change Log** — table of entries.
+
+**Counts:**
+
+- Story count, AS count, sub-spec count → used for the topbar meta.
+- Status class: `Draft` → `.status.draft`, `Active` → `.status.active`, `Deprecated` → `.status.deprecated`.
+
+### Step 3 — Build output buffer
+
+Copy `template.html` content into an in-memory string buffer. Replace placeholders (values from Step 2):
+
+| Placeholder | Value | Notes |
+|-------------|-------|-------|
+| `{{LANG}}` | ISO 639-1 code | Detect from the source prose. Default `vi` if Vietnamese dominates, `en` for English. |
+| `{{FEATURE}}` | feature slug | Appears twice: in `<title>` and `<h1>`. |
+| `{{SUBTITLE}}` | 1-line description | Pulled from the root Overview, max 200 chars. |
+| `{{VERSION}}` | from frontmatter, or snapshot count + 1 | Default `1` if absent. |
+| `{{LAST_UPDATED}}` | ISO date from frontmatter | |
+| `{{UPDATED_LABEL}}` | "updated" / "cập nhật" | Match `{{LANG}}`. |
+| `{{META_EXTRA}}` | `<span class="sep">·</span><span>N specs</span><span class="sep">·</span><span>N stories</span><span class="sep">·</span><span>N AS</span>` | Multi-spec includes `N specs`; single-spec omits it. |
+| `{{STATUS}}` | `Active` / `Draft` / `Deprecated` | |
+| `{{STATUS_CLASS}}` | `active` / `draft` / `deprecated` | Lowercase. |
+| `{{TOC_LABEL}}` | "Mục lục" / "Contents" | |
+| `{{SEARCH_PLACEHOLDER}}` | "Tìm story…" / "Search story…" | |
+| `{{SKIP_LABEL}}` | "Bỏ qua menu" / "Skip to content" | |
+| `{{THEME_TIP}}` | "Đổi theme" / "Toggle theme" | |
+
+### Step 4 — Render TOC
+
+Replace `<!-- TOC_ENTRIES -->` with entries. Use §2 in `components.md`.
+
+**Single-spec layout:**
+
+```
+[Overview]   TL;DR · Overview · Data Model (if any)
+[Stories]    1 entry per story with P-badge
+[Reference]  Constraints · What Already Exists · Not in Scope · Change Log · Snapshots
+```
+
+**Multi-spec layout:**
+
+```
+[Overview]            TL;DR · Sub-specs · Shared Data Model
+[<Sub-spec 1 name>]   count "5/19"  | 1 entry per story (P-badge + S-NNN + short title)
+[<Sub-spec 2 name>]   ...
+...
+[Root]
+[Reference]           Constraints · Not in Scope · Change Log
+```
+
+Story link text format: `<span class="p p0">P0</span>S-NNN · <short title, max ~30 chars>`
+
+### Step 5 — Render body
+
+Replace the slot between `<!-- CONTENT_START -->` and `<!-- CONTENT_END -->` with the body, in this order:
+
+1. **TL;DR card** (§3) — mandatory, generated from overview + story list. Max 10 bullets.
+2. **Sub-specs table** (multi-spec only, §10b) — if the root has a Sub-specs table.
+3. **Shared Data Model** (multi-spec) or **Data Model** (single, §10c) — collapsed by default for long tables.
+4. **Per sub-spec** (multi-spec) or **Stories** section (single):
+   - Sub-spec header: `<h2 class="subspec-head">` with an eyebrow `SUB-SPEC` / `STEP 1..4` / `ROOT` (§7).
+   - Brief overview paragraph below the header.
+   - Story cards (§4) in the order from spec.md. Within each story, the first AS is `open` and the rest are collapsed (§5). If the story has `**Applies Constraints:**`, render the bound `C-NNN` chips on the card (§4).
+5. **Constraints** (§6):
+   - Single spec → flat list of callouts.
+   - A **cross-surface invariant** (has `scope:`/`surfaces:`/`coverage:`) renders that per-surface coverage block inside its callout (§6a) — so the reader sees each money/effect surface mapped to its own `AS-NNN`/`GAP-NNN`.
+   - Multi-spec → grouped by sub-spec; each group is a `<details class="collapsible">`. The Root group defaults to `open`, sub-spec groups default closed.
+6. **What Already Exists** (§10a) — plain prose section.
+7. **Not in Scope** (§10d) — bullet list with `<b>` around each item name.
+8. **Change Log** (§8) — collapsed table. Multi-spec adds a `Spec` column.
+9. **Snapshots** (§9) — collapsed list, only if the directory contains files. Skip the section entirely when empty.
+
+### Step 6 — Write file
+
+Write the buffer to `<spec-dir>/<feature>.html`. **One Write call, no Edit loop** — repeated Edits cause drift and waste tokens.
+
+### Step 7 — Verify
+
+Re-read the written file and check:
+
+- [ ] No leftover `{{PLACEHOLDER}}` strings.
+- [ ] No leftover `<!-- TOC_ENTRIES -->`, `<!-- CONTENT_START -->`, `<!-- CONTENT_END -->`.
+- [ ] Every TOC `href="#x"` resolves to an element with `id="x"` in the body (sample 5 random IDs).
+- [ ] Count of `<article class="story">` matches the number of stories parsed.
+- [ ] Count of `<details class="as">` matches the number of AS parsed.
+
+If anything is off, fix with targeted Edits — do not rewrite the whole file.
+
+Report to the user:
+
+```
+✓ Rendered <feature> → <path>
+  <N specs> · <N stories> · <N AS> · status: <Draft|Active|Deprecated>
+  Open: open <path>
+```
+
+---
+
+## Rules
+
+1. **Source is truth.** The HTML is an idempotent regenerable view. Never hand-edit HTML.
+2. **One Write call.** Build the full buffer in memory, then write once.
+3. **No new CSS or components.** Use only the classes in the template and the snippets in `components.md`.
+4. **Never paraphrase technical content.** Field names, routes, code identifiers stay verbatim, wrapped in `<code>`.
+5. **Compact AS bodies.** Given/When/Then are 1–2 lines each. Long-form detail belongs in spec.md, not the HTML.
+6. **Local IDs per sub-spec.** Story ID is local per sub-spec (signup:S-001, store:S-001 OK). The HTML element `id` is namespaced by sub-spec slug to avoid duplicates across the rendered file.
+7. **TL;DR is mandatory.** Even for short specs.
+8. **Constraints / Snapshots / Change Log collapsed by default.** The Root constraint group may open by default in multi-spec layout; everything else stays closed.
+
+---
+
+## Edge cases
+
+- **Empty story list** → render TL;DR + frontmatter + a placeholder "No stories yet." Do not error.
+- **No `snapshots/` directory** → skip the Snapshots section entirely; do not render the header.
+- **Missing Status in frontmatter** → default to `Draft`.
+- **Missing Last updated** → use `$(date +%Y-%m-%d)`.
+- **Story without AS** → render the story card with a "No acceptance scenarios yet." stub. Do not skip the story.
+- **AS without explicit Given/When/Then** (P2 prose style) → render the flow description instead of the dl/dt grid. See §5b.
+- **Sub-spec link path does not resolve** → log a warning, skip that sub-spec, still render the rest.
+- **Source `.md` contains embedded HTML** → pass through inside `story-desc` if safe.
+
+---
+
+## Anti-patterns
+
+- ❌ Edit loop to generate the HTML piece by piece — causes drift, wastes tokens. Build the buffer, then Write once.
+- ❌ Adding a new `<style>` block or inline CSS attribute on an element. All CSS comes from the template.
+- ❌ Generating an inline SVG path for every callout. Use the `.callout .ico` class with the SVG snippet in `components.md`.
+- ❌ Translating identifiers, routes, function names. Code and paths stay verbatim.
+- ❌ Bloating AS bodies with long prose. An AS is a contract test, not a tutorial.
+- ❌ Rendering when `<feature>.md` does not exist — STOP and tell the user to run `/sp-plan` first.
+
+---
+
+## Relationship with /sp-plan
+
+This skill is decoupled from `/sp-plan`. `/sp-plan` writes the spec markdown and ends — it never calls this skill automatically. At the end of Phase 4 (new spec) and Mode C C5 (spec update), `/sp-plan` displays a 1–2 line hint telling the user to run `/sp-spec-render <feature>` if they want the HTML view.
+
+This gives the user explicit control:
+
+- Some users only want the markdown (faster, no extra tokens spent rendering).
+- Some users render once and never again until they actually want to scan the spec.
+- Some users re-render after every update to keep an HTML tab open as their primary reading surface.
+
+Manual invocation cases:
+
+- After `/sp-plan` finishes — generate or refresh the HTML view.
+- After hand-editing `<feature>.md` for a typo (no spec semantics changed, but the HTML is now stale).
+- Bulk re-render across the repo after updating `template.html` or `components.md` in this skill.
+- Rendering specs written before this skill existed.
+
+---
+
+## Bulk re-render
+
+If `$ARGUMENTS` is `--all`:
+
+1. `ls docs/specs/*/` — for each directory containing `<name>/<name>.md`, render it.
+2. Report totals: `Rendered N specs in X seconds.`
+
+Useful after updating `template.html` or `components.md` in this skill.

package/templates/skills/sp-spec-render/components.md

@@ -0,0 +1,418 @@
+# components.md — Catalog for sp-spec-render
+
+11 HTML snippets. The AI copies them verbatim and fills in content. **Never invent CSS classes.**
+
+Conventions: `{{X}}` is a placeholder string. `[...]` is a description (does not appear in output). `// comment` is a note and does not appear in output.
+
+---
+
+## §1 — Topbar meta extra
+
+Content of `{{META_EXTRA}}` in the template, inserted after `{{LAST_UPDATED}}`:
+
+**Single-spec:**
+```html
+<span class="sep">·</span><span>{{N_STORIES}} stories</span><span class="sep">·</span><span>{{N_AS}} AS</span>
+```
+
+**Multi-spec:**
+```html
+<span class="sep">·</span><span>{{N_SPECS}} specs</span><span class="sep">·</span><span>{{N_STORIES}} stories</span><span class="sep">·</span><span>{{N_AS}} AS</span>
+```
+
+---
+
+## §2 — Sidebar TOC
+
+Replace `<!-- TOC_ENTRIES -->`. Structure depends on layout.
+
+**Single-spec:**
+```html
+<div class="toc-group">Overview</div>
+<a href="#tldr" data-target="tldr">TL;DR</a>
+<a href="#overview" data-target="overview">Overview</a>
+<a href="#data-model" data-target="data-model">Data Model</a>  // skip if the spec has no data model
+
+<div class="toc-group">Stories <span class="count">{{N_STORIES}}/{{N_AS}}</span></div>
+<a href="#s-001" data-target="s-001"><span class="p p0">P0</span>S-001 · {{short title, max 30 chars}}</a>
+// ... 1 entry per story, badge matching priority
+
+<div class="toc-group">Reference</div>
+<a href="#constraints" data-target="constraints">Constraints</a>
+<a href="#existing" data-target="existing">What Already Exists</a>
+<a href="#not-in-scope" data-target="not-in-scope">Not in Scope</a>
+<a href="#changelog" data-target="changelog">Change Log</a>
+<a href="#snapshots" data-target="snapshots">Snapshots</a>  // skip if the directory is empty
+```
+
+**Multi-spec:**
+```html
+<div class="toc-group">Overview</div>
+<a href="#tldr" data-target="tldr">TL;DR</a>
+<a href="#subspecs" data-target="subspecs">Sub-specs ({{N_SPECS}})</a>
+<a href="#data-model" data-target="data-model">Shared Data Model</a>
+
+<div class="toc-group">{{Sub-spec display name}} <span class="count">{{N_STORIES_IN_SUB}}/{{N_AS_IN_SUB}}</span></div>
+<a href="#{{subslug}}-s-001" data-target="{{subslug}}-s-001"><span class="p p0">P0</span>S-001 · {{short title}}</a>
+// ... per sub-spec
+
+<div class="toc-group">Reference</div>
+<a href="#constraints" data-target="constraints">Constraints ({{TOTAL_C}})</a>
+<a href="#not-in-scope" data-target="not-in-scope">Not in Scope</a>
+<a href="#changelog" data-target="changelog">Change Log</a>
+```
+
+**Rules:**
+- Story title in the TOC is at most ~30 chars. Truncate at a word boundary, not mid-word.
+- HTML `id` is namespaced by sub-spec slug: `signup-s-001`, `store-s-001`. The sub-spec slug is the part after `<feature>-` in the filename.
+- Group name uses a readable display name: `onboarding-step-store.md` → group `Step 1 — Store`. If you cannot infer a clean name, fall back to the filename.
+
+---
+
+## §3 — TL;DR card
+
+Mandatory. Generated from the Overview + story list, max ~10 bullets.
+
+```html
+<section class="tldr" id="tldr">
+  <div class="tldr-label">TL;DR</div>
+  <p>{{1–2 sentence summary with <b>key decisions</b> inline}}</p>
+  <ul>
+    <li><b>{{S-NNN or Sub-spec name}}</b> {{title}} — {{key behavior}} ({{N}} AS, {{Pn}})</li>
+    // ...
+  </ul>
+</section>
+```
+
+**Rules:**
+- Opening sentence states the phase/scope decision (e.g. "Phase 1, single-tab, email-only.").
+- Bullets: 1 per story (single-spec) or 1 per sub-spec (multi-spec).
+- Bold the ID and the key concept. Plain prose for the rest.
+
+---
+
+## §4 — Story card
+
+Each `### S-NNN: Title (Pn)` becomes one `<article>`.
+
+```html
+<article class="story" id="{{namespaced-id}}">
+  <header class="story-head">
+    <span class="badge {{p0|p1|p2}}">{{P0|P1|P2}}</span>
+    <span class="id">{{S-NNN}}</span>
+    <span class="title">{{Story title}}</span>
+    <span class="badge count">{{N}} AS</span>
+  </header>
+  <div class="story-body">
+    <p class="story-desc">{{description, wrap identifiers in <code>}}</p>
+    {{ if the story has **Applies Constraints**:
+    <p class="story-desc"><b>Applies:</b> {{one <code>C-NNN</code> per bound constraint, space-separated}}</p>
+    }}
+    <div class="as-list">
+      // §5 AS entries here
+    </div>
+  </div>
+</article>
+```
+
+**Rules:**
+- `id` is namespaced by sub-spec slug in multi-spec layout: `signup-s-001`. Single-spec: `s-001`.
+- `badge p0/p1/p2` lowercase to match the priority.
+- Description is the paragraph after `**Description:**` in the spec; preserve technical identifiers as `<code>`.
+- If a story has no AS, still render the card. Inside `as-list`, put `<p style="color:var(--fg-muted);font-size:13px">No acceptance scenarios yet.</p>`.
+
+---
+
+## §5 — Acceptance Scenario
+
+Each `AS-NNN` becomes a `<details>`. The first AS of each story is `open`; the rest start collapsed.
+
+### §5a — Given/When/Then style (typical for P0, P1)
+
+```html
+<details class="as"{{ open if this is the first AS in the story}}>
+  <summary class="as-head">
+    <span class="id">{{AS-NNN}}</span>
+    <span class="desc">{{1-line description from the spec}}</span>
+    <span class="chev">›</span>
+  </summary>
+  <div class="as-body">
+    <dl class="gwt">
+      <dt>Given</dt><dd>{{state, wrap identifiers in <code>}}</dd>
+      <dt>When</dt><dd>{{action}}</dd>
+      <dt>Then</dt><dd>{{expected}}</dd>
+    </dl>
+    {{ if has Data:
+    <div class="as-data"><b>Data:</b> {{data}}</div>
+    }}
+    {{ if has Setup:
+    <div class="as-data"><b>Setup:</b> {{setup}}</div>
+    }}
+  </div>
+</details>
+```
+
+### §5b — Prose flow style (P2 or when the spec does not split Given/When/Then)
+
+```html
+<details class="as">
+  <summary class="as-head">
+    <span class="id">{{AS-NNN}}</span>
+    <span class="desc">{{short title}}</span>
+    <span class="chev">›</span>
+  </summary>
+  <div class="as-body">
+    <p class="as-prose">{{flow description + expected behavior}}</p>
+  </div>
+</details>
+```
+
+**Rules:**
+- The `desc` in the summary is a 1-line summary, not the full Given/When/Then.
+- Wrap `<code>` around every identifier: HTTP code, route, field name, function name, env var.
+- Drop "Setup" if it duplicates Given. Drop "Data" if it is trivial.
+- Do not bloat the AS body. An AS is a contract test — `Given X. When Y. Then Z.` is enough.
+
+---
+
+## §6 — Constraint callout
+
+### §6a — Single callout (single-spec, or per-sub-spec when grouped)
+
+```html
+<div class="callout">
+  <svg class="ico" aria-hidden="true"><use href="#i-warn"/></svg>
+  <div>
+    <p class="callout-title">{{C-NNN · short name}}</p>
+    <p>{{constraint body, wrap identifiers in <code>}}</p>
+    {{ if cross-surface invariant (has scope/surfaces/coverage):
+    <p><b>Cross-surface invariant.</b> Scope: {{<code>S-NNN</code> …}}. Surfaces: {{<code>surface</code> …}}. Coverage: {{per surface, <code>surface</code> → <code>AS-NNN</code> | <code>GAP-NNN</code>}}.</p>
+    }}
+  </div>
+</div>
+```
+
+// Cross-surface invariant block: reuses the callout's plain `<p>` (no new class, no inline style).
+// Render it ONLY for a constraint carrying scope/surfaces/coverage; omit for ordinary constraints.
+
+### §6b — Grouped constraints (multi-spec, more than 5 constraints per sub-spec)
+
+```html
+<details class="collapsible"{{ open if this is the Root group}}>
+  <summary><b>{{Sub-spec display name}} (C-{{start}}..C-{{end}})</b> <span class="count">{{N}} invariants</span></summary>
+  <div><div class="constraints">
+    // §6a callouts here
+  </div></div>
+</details>
+```
+
+**Rules:**
+- `.callout-title` uses the `C-NNN · short name` format. The short name is 2–4 words summarizing the constraint.
+- Single-spec, or fewer than 5 constraints per sub-spec → flat §6a list.
+- Multi-spec with many constraints → grouped §6b. Root group `open`, sub-spec groups closed.
+- If a group has more than 8 callouts → optionally merge a few into a single `C-XXX..C-YYY` callout to avoid a wall of yellow. Each merged callout must still represent one coherent idea.
+
+---
+
+## §7 — Sub-spec section header (multi-spec only)
+
+```html
+<h2 class="subspec-head" id="{{subspec-slug}}"><span class="ix">{{EYEBROW}}</span>{{Display Title}}</h2>
+<p style="color:var(--fg-muted);font-size:13.5px;margin-top:-4px">{{1-line overview of the sub-spec}}</p>
+```
+
+**Eyebrow values:**
+- `SUB-SPEC` — generic sub-spec
+- `STEP 1`, `STEP 2`, `STEP 3`, `STEP 4` — wizard step sub-specs
+- `ROOT` — cross-cutting / root spec stories
+- A custom eyebrow is fine when the sub-spec name suggests a clear role
+
+**Display title:** from the `## Overview` of the sub-spec, or the filename. Keep it short (≤60 chars).
+
+---
+
+## §8 — Change Log (collapsed)
+
+### §8a — Single-spec
+
+```html
+<h2 id="changelog">Change Log</h2>
+<details class="collapsible">
+  <summary>{{N}} entries <span class="count">expand</span></summary>
+  <div>
+    <table class="changelog">
+      <thead><tr><th>Date</th><th>Change</th><th>Ref</th></tr></thead>
+      <tbody>
+        <tr><td class="date">{{YYYY-MM-DD}}</td><td>{{change}}</td><td>{{ref or —}}</td></tr>
+      </tbody>
+    </table>
+  </div>
+</details>
+```
+
+### §8b — Multi-spec (adds a Spec column)
+
+```html
+<h2 id="changelog">Change Log</h2>
+<details class="collapsible">
+  <summary>{{N}} entries across {{N_SPECS}} specs <span class="count">expand</span></summary>
+  <div>
+    <table class="changelog">
+      <thead><tr><th>Date</th><th>Spec</th><th>Change</th><th>Ref</th></tr></thead>
+      <tbody>
+        <tr><td class="date">{{date}}</td><td>{{spec name}}</td><td>{{change}}</td><td>{{ref or —}}</td></tr>
+      </tbody>
+    </table>
+  </div>
+</details>
+```
+
+**Rules:**
+- Sort entries by date DESC (newest first).
+- Empty `Ref` → render as `—`.
+
+---
+
+## §9 — Snapshots (collapsed)
+
+```html
+<h2 id="snapshots">Snapshots</h2>
+<details class="collapsible">
+  <summary>{{N}} snapshots <span class="count">history</span></summary>
+  <div>
+    <div class="snapshots-list">
+      <div class="snapshot-row">
+        <span class="date">{{YYYY-MM-DD}}</span>
+        <a href="snapshots/{{filename}}">snapshots/{{filename}}</a>
+        <span class="reason">{{M-code if known}}{{: short reason}}</span>
+      </div>
+      // ...
+    </div>
+  </div>
+</details>
+```
+
+**Rules:**
+- Sort by date DESC.
+- Read the `**Reason:**` line inside each snapshot file to fill `reason` (M1/M2/.../M6 + short).
+- If the `snapshots/` directory does not exist or is empty → **skip the entire section**, do not render the header.
+
+---
+
+## §10 — Plain sections
+
+### §10a — Overview / What Already Exists
+
+```html
+<h2 id="{{slug}}">{{Heading}}</h2>
+<p>{{prose, wrap identifiers in <code>}}</p>
+```
+
+Skip the section if the spec does not have it.
+
+### §10b — Sub-specs table (multi-spec only)
+
+```html
+<h2 id="subspecs">Sub-specs</h2>
+<table class="subspec-table">
+  <thead><tr><th>Sub-spec</th><th>Scope</th></tr></thead>
+  <tbody>
+    <tr><td>{{sub-spec name}}</td><td>{{scope description, wrap identifiers in <code>}}</td></tr>
+  </tbody>
+</table>
+```
+
+Pulled from the Sub-specs table in the root spec.
+
+### §10c — Data Model (collapsed)
+
+```html
+<h2 id="data-model">{{Shared Data Model | Data Model}}</h2>
+<details class="collapsible">
+  <summary>{{N}} tables <span class="count">click expand</span></summary>
+  <div>
+    <h3 style="margin:8px 0 6px;font-size:13px;color:var(--fg-muted)"><code>{{table_name}}</code> — {{new | extend}}</h3>
+    <p style="font-size:13px;color:var(--fg-muted)">{{column summary in 1–2 lines, mention key columns + indices}}</p>
+    // repeat per table
+  </div>
+</details>
+```
+
+**Rules:**
+- Compress each table into one prose paragraph. Do not render the full schema table — readers go to spec.md for that.
+- Highlight key columns and indices in the prose.
+
+### §10d — Not in Scope
+
+```html
+<h2 id="not-in-scope">Not in Scope</h2>
+<div class="nis">
+  <ul>
+    <li><b>{{Item name}}</b> — {{reason / defer note}}</li>
+    // ...
+  </ul>
+</div>
+```
+
+---
+
+## §11 — Inline code and identifier rules
+
+**Hard rule:** every technical identifier is wrapped in `<code>`. Applies in story descriptions, AS bodies, callouts, prose, and the TL;DR.
+
+- `AS-001`, `S-003`, `P0` → `<code>`
+- File paths: `<code>src/middleware/auth.ts</code>`
+- Routes: `<code>POST /api/login</code>`
+- Field / variable names: `<code>sid</code>`, `<code>HttpOnly</code>`, `<code>email_verified_at</code>`
+- Env vars: `<code>NODE_ENV</code>`, `<code>PLUGIN_LATEST_VERSION</code>`
+- Enum values: `<code>'active'</code>`, `<code>"finished"</code>`
+- HTTP status: `<code>200</code>`, `<code>4xx</code>`
+- Error codes: `<code>EMAIL_EXISTS</code>`, `<code>RATE_LIMIT</code>`
+
+**Do NOT** wrap `<code>` around:
+
+- Personal names, product names, team names
+- Abstract references to tables ("the user table") — only wrap when writing the literal table name
+- Numbers in natural prose ("3 retries", "24 hours")
+
+---
+
+## Global rules
+
+1. **One component per chunk.** Do not nest callouts inside stories inside collapsibles.
+2. **First AS of each story is `open`**, the rest collapsed.
+3. **Constraint groups collapsed by default.** Root group `open` in multi-spec.
+4. **Change Log + Snapshots + Data Model always collapsed.**
+5. **TL;DR is mandatory.** Even for short specs.
+6. **Never invent CSS classes.** Use only classes defined in the template.
+7. **Never generate `<style>` or `<script>`.** They already exist in the template.
+8. **One Write call.** Build the full buffer, then Write once. Edit loops cause drift and waste tokens.
+9. **Identifiers always `<code>`.** Do not let `AS-001` run as plaintext inside prose.
+10. **Sort time DESC** for Change Log and Snapshots (newest first).
+
+---
+
+## Build flow (summary)
+
+```
+1. Read template.html + components.md + one example pair (cached)
+2. Read spec.md (+ sub-specs if any)
+3. Parse: frontmatter, sections, stories, AS, constraints, snapshots
+4. Classify single vs multi-spec
+5. Fill ~12 placeholder strings (§1 META_EXTRA, langs, etc.)
+6. Render TOC (§2) — 1 line per heading or story
+7. Render body section by section:
+   - TL;DR (§3) — always first
+   - Sub-specs table (§10b) — multi-spec only
+   - Data Model (§10c) — collapsed
+   - Per sub-spec: subspec-head (§7) + overview + stories (§4) + AS (§5)
+   - Constraints (§6) — flat or grouped
+   - What Already Exists (§10a) — prose
+   - Not in Scope (§10d) — list
+   - Change Log (§8) — collapsed
+   - Snapshots (§9) — collapsed (skip if empty)
+8. Write spec.html (once)
+9. Verify: no leftover placeholders, every TOC id matches the body
+```
+
+Output token cost ≈ spec.md size × 1.2. CSS/JS/sprite never appear in the AI output stream after the initial template build.