@hegemonart/get-design-done 1.42.0 → 1.44.0

package/reference/prices/windsurf.md

@@ -1,9 +1,9 @@
-# Windsurf — Price Table (stub)
+# Windsurf - Price Table (stub)
 
 **Runtime:** `windsurf` (Windsurf / Codeium)
-**Phase 26 D-08 sub-table — STUB.** Placeholder so the price-table router (`reference/model-prices.md`) has a complete link list for all 14 runtimes. Runtime adapter authors fill this in with provenance citations in a later cycle.
+**Phase 26 D-08 sub-table - STUB.** Placeholder so the price-table router (`reference/model-prices.md`) has a complete link list for all 14 runtimes. Runtime adapter authors fill this in with provenance citations in a later cycle.
 
-**Provenance:** `<TODO: confirm at https://docs.windsurf.com/windsurf/plans>` — pending.
+**Provenance:** `<TODO: confirm at https://docs.windsurf.com/windsurf/plans>` - pending.
 
 ## Pricing (USD per 1M tokens)
 

package/reference/prices.openrouter.md

@@ -1,6 +1,6 @@
-# OpenRouter — Catalog-Derived Price Snapshot
+# OpenRouter - Catalog-Derived Price Snapshot
 
-**Phase 33.6 (v1.33.6).** This file is a **catalog-derived snapshot** of OpenRouter per-model prices — it is **generated from** `.design/cache/openrouter-models.json` (the dynamic catalog fetched by `scripts/lib/openrouter/catalog-fetcher.cjs`), **not** a hand-maintained authority. The **live source of truth is the dynamic catalog**; this table is a derived, illustrative view that can go stale between catalog fetches.
+**Phase 33.6 (v1.33.6).** This file is a **catalog-derived snapshot** of OpenRouter per-model prices - it is **generated from** `.design/cache/openrouter-models.json` (the dynamic catalog fetched by `scripts/lib/openrouter/catalog-fetcher.cjs`), **not** a hand-maintained authority. The **live source of truth is the dynamic catalog**; this table is a derived, illustrative view that can go stale between catalog fetches.
 
 Unlike the per-runtime tables under `reference/prices/` (Phase 26 D-08, hand-curated authority with provenance), OpenRouter's prices live in the upstream `/models` response and are refreshed on the 24h TTL. To inspect the current resolved prices, run `/gdd:openrouter-status` or read the cache directly. For the tier→model resolution heuristic see `reference/openrouter-tier-mapping.md`.
 
@@ -20,7 +20,7 @@ Derived from the fixture catalog at `test/fixtures/baselines/phase-33-6/openrout
 
 ## Notes
 
-- **Derived view, not authority.** Do not hand-edit prices here to "fix" cost math — fix the catalog fetch instead. This file documents the *shape* and *source* of OpenRouter pricing for the registry round-trip and for human reference.
+- **Derived view, not authority.** Do not hand-edit prices here to "fix" cost math - fix the catalog fetch instead. This file documents the *shape* and *source* of OpenRouter pricing for the registry round-trip and for human reference.
 - **Per-token vs per-1M.** The native runtime tables (`reference/prices/<runtime>.md`) quote `input_per_1m` / `output_per_1m`; OpenRouter's catalog quotes per-token. Multiply by 1,000,000 to compare (e.g. `anthropic/claude-opus-4-7` ≈ $15 input / $75 output per 1M tokens).
-- **Cost telemetry.** When a model is resolved via the OpenRouter adapter, the cost row tags `provider: openrouter` (Phase 33.6-03, SC#6) — see `scripts/lib/budget-enforcer.cjs#buildCostEventPayload`.
-- **Drift.** The authority-watcher diffs the catalog weekly and surfaces `deprecated`/`withdrawn` models matching a configured `openrouter_tier_overrides` pin (SC#8) — see `scripts/lib/authority-watcher/index.cjs#diffOpenRouterCatalog`.
+- **Cost telemetry.** When a model is resolved via the OpenRouter adapter, the cost row tags `provider: openrouter` (Phase 33.6-03, SC#6) - see `scripts/lib/budget-enforcer.cjs#buildCostEventPayload`.
+- **Drift.** The authority-watcher diffs the catalog weekly and surfaces `deprecated`/`withdrawn` models matching a configured `openrouter_tier_overrides` pin (SC#8) - see `scripts/lib/authority-watcher/index.cjs#diffOpenRouterCatalog`.

package/reference/print-design.md

@@ -1,7 +1,7 @@
-# Print Design — Constraint Catalogue
+# Print Design - Constraint Catalogue
 
 This reference is the **print/PDF constraint catalogue**: the hard print-production rules a
-print-ready document MUST honor. Print is a *constrained* output surface — the screen-RGB
+print-ready document MUST honor. Print is a *constrained* output surface - the screen-RGB
 HTML/CSS the web executor emits has no `@page` box model, no bleed/crop marks, no CMYK
 color space, no font embedding, and no 300dpi raster guidance, so it cannot be sent to a
 press as-is. This file is the **authority** that the `pdf-executor` (Phase 34.3-02) generates
@@ -15,10 +15,10 @@ and must not be confused:
 
 | File | Job |
 | --- | --- |
-| `reference/platforms.md` (Phase 19) | Interaction **conventions** — navigation, safe areas, gestures, native typography, haptics. *Behavioral* knowledge for native/web screens. |
-| `reference/native-platforms.md` (Phase 34.1) | The native **token bridge** — maps canonical CSS tokens to SwiftUI / Jetpack Compose / Flutter with a precision contract. *Token-identity* knowledge for native generators. |
-| `reference/email-design.md` (Phase 34.2) | The email **constraint catalogue** — table layout, inline styles, MSO comments, dark-mode `color-scheme`. *Structural* knowledge an email template implements. |
-| `reference/print-design.md` (Phase 34.3, this file) | The print **constraint catalogue** — the `@page` box model, bleed + crop marks, CMYK awareness, font embedding, and 300dpi raster fallback. *Production* knowledge a print/PDF document implements. |
+| `reference/platforms.md` (Phase 19) | Interaction **conventions** - navigation, safe areas, gestures, native typography, haptics. *Behavioral* knowledge for native/web screens. |
+| `reference/native-platforms.md` (Phase 34.1) | The native **token bridge** - maps canonical CSS tokens to SwiftUI / Jetpack Compose / Flutter with a precision contract. *Token-identity* knowledge for native generators. |
+| `reference/email-design.md` (Phase 34.2) | The email **constraint catalogue** - table layout, inline styles, MSO comments, dark-mode `color-scheme`. *Structural* knowledge an email template implements. |
+| `reference/print-design.md` (Phase 34.3, this file) | The print **constraint catalogue** - the `@page` box model, bleed + crop marks, CMYK awareness, font embedding, and 300dpi raster fallback. *Production* knowledge a print/PDF document implements. |
 
 Per **D-02** there is **no bundled `pdfkit` / `paged` / `puppeteer` / `playwright`
 dependency**: the `pdf-executor` generates **Paged.js-compatible print HTML/CSS** as its
@@ -51,19 +51,19 @@ The catalogue is **prose + tables**, not an implementation. Illustrative snippet
 
 ---
 
-## 2. The print box model — `@page`
+## 2. The print box model - `@page`
 
 Print uses the CSS **`@page`** rule to define the page box: its `size` (a named page such as
 `A4` / `Letter`, or an explicit `WIDTH HEIGHT` with physical units), its `margin`, and its
-`marks` (`crop` / `cross`). Screen CSS has no page box at all — content flows in one
-continuous viewport — so a print stylesheet that omits `@page` has no defined page geometry
+`marks` (`crop` / `cross`). Screen CSS has no page box at all - content flows in one
+continuous viewport - so a print stylesheet that omits `@page` has no defined page geometry
 and cannot paginate predictably. Paged.js consumes the `@page` CSS to paginate in headless
 Chrome; PDFKit instead constructs the page box programmatically (`new PDFDocument({ size,
 margins })`).
 
 | Rule-id | Constraint |
 | --- | --- |
-| **PR-PAGE-01** | A print stylesheet MUST declare an `@page` rule — the print box model. Its absence means no defined page geometry. *(Statically checkable: absence of an `@page` rule is flagged.)* |
+| **PR-PAGE-01** | A print stylesheet MUST declare an `@page` rule - the print box model. Its absence means no defined page geometry. *(Statically checkable: absence of an `@page` rule is flagged.)* |
 | PR-PAGE-02 | The `@page` rule SHOULD set `size` (named `A4`/`Letter` or explicit physical `WIDTH HEIGHT`) and `margin`; use `@page :first` / `:left` / `:right` for cover/spread-specific geometry. |
 | PR-PAGE-03 | Control pagination with `break-before` / `break-after` / `break-inside: avoid` (and the legacy `page-break-*`) so headings, tables, and figures do not split badly across page boundaries. |
 
@@ -85,9 +85,9 @@ critical content sits in the cut-tolerance band.
 
 | Rule-id | Constraint |
 | --- | --- |
-| **PR-BLEED-01** | A print document targeting edge-to-edge output MUST signal a bleed box / crop marks — a CSS `bleed:` declaration, a `marks: crop\|cross` declaration, or a documented bleed/crop-marks convention. *(Statically checkable: total absence of any bleed/marks signal is flagged.)* |
+| **PR-BLEED-01** | A print document targeting edge-to-edge output MUST signal a bleed box / crop marks - a CSS `bleed:` declaration, a `marks: crop\|cross` declaration, or a documented bleed/crop-marks convention. *(Statically checkable: total absence of any bleed/marks signal is flagged.)* |
 | PR-BLEED-02 | Bleed is conventionally **3mm** (≈0.125in); registration marks sit in the trim waste outside the bleed box so they are removed when the sheet is cut. |
-| PR-BLEED-03 | Keep a **safe area** inside the trim (≈3–5mm) — critical text and logos stay inside it so cut tolerance never clips them. |
+| PR-BLEED-03 | Keep a **safe area** inside the trim (≈3–5mm) - critical text and logos stay inside it so cut tolerance never clips them. |
 
 ---
 
@@ -97,15 +97,15 @@ Print is **subtractive CMYK** (cyan/magenta/yellow/key-black ink on paper), not
 screen **RGB** the web executor emits. Pure-RGB output risks visible color shift on press:
 bright RGB blues/greens fall outside the CMYK gamut and reproduce duller, and an untagged
 document leaves the RIP to guess a conversion. A print artifact must therefore signal CMYK
-awareness — a `cmyk()` color, a `color-profile` / `@color-profile` reference (an ICC/CMYK
+awareness - a `cmyk()` color, a `color-profile` / `@color-profile` reference (an ICC/CMYK
 target profile), or an explicit documented CMYK-target note. Exact ICC-profile correctness
 and on-press gamut matching are **render-tested**, not statically assertable (see §8).
 
 | Rule-id | Constraint |
 | --- | --- |
-| **PR-CMYK-01** | A print document MUST show CMYK awareness — a `cmyk()` color value, a `color-profile` / `@color-profile` reference, or a documented CMYK-target note. *(Statically checkable: total absence of any CMYK-awareness signal — pure screen-RGB only — is flagged.)* |
+| **PR-CMYK-01** | A print document MUST show CMYK awareness - a `cmyk()` color value, a `color-profile` / `@color-profile` reference, or a documented CMYK-target note. *(Statically checkable: total absence of any CMYK-awareness signal - pure screen-RGB only - is flagged.)* |
 | PR-CMYK-02 | Prefer named spot/`cmyk()` values for brand colors that must match on press; flag wide-gamut RGB (`display-p3`, neon RGB) that will not survive CMYK conversion. |
-| PR-CMYK-03 | Rich black (e.g. `C30 M30 Y30 K100`) for large solid areas; pure `K100` for small text to avoid registration fringing. *(ICC correctness is render-tested — §8.)* |
+| PR-CMYK-03 | Rich black (e.g. `C30 M30 Y30 K100`) for large solid areas; pure `K100` for small text to avoid registration fringing. *(ICC correctness is render-tested - §8.)* |
 
 ```css
 :root { color-profile: url(./CoatedFOGRA39.icc); }   /* CMYK target */
@@ -116,7 +116,7 @@ and on-press gamut matching are **render-tested**, not statically assertable (se
 
 ## 5. Font embedding
 
-Print **RIPs have no web fonts** and no system-font-stack fallback chain — whatever font is
+Print **RIPs have no web fonts** and no system-font-stack fallback chain - whatever font is
 referenced must be **embedded** in the document (`@font-face` with an embedded `src:`) or the
 text must be **outlined to vector**. A bare `font-family: Arial, sans-serif` system-font-stack
 assumption is a print bug: the RIP may substitute a metrically-different face (reflowing the
@@ -125,7 +125,7 @@ Paged.js relies on `@font-face` declarations resolved before pagination.
 
 | Rule-id | Constraint |
 | --- | --- |
-| **PR-FONT-01** | Fonts MUST be embedded or outlined — an `@font-face` rule with an embedded `src:`, or a documented font-embed/outline note. A bare system-font-stack assumption (no embed) is a print bug. *(Statically checkable: absence of any font-embed signal is flagged.)* |
+| **PR-FONT-01** | Fonts MUST be embedded or outlined - an `@font-face` rule with an embedded `src:`, or a documented font-embed/outline note. A bare system-font-stack assumption (no embed) is a print bug. *(Statically checkable: absence of any font-embed signal is flagged.)* |
 | PR-FONT-02 | Embed only the weights/styles actually used (subset where possible) to keep the PDF small; ensure the license permits embedding. |
 | PR-FONT-03 | Outline display/headline type to vector when exact rendering matters more than text selectability; keep body copy as embedded text for accessibility and reflow. |
 
@@ -137,7 +137,7 @@ Paged.js relies on `@font-face` declarations resolved before pagination.
 
 ## 6. 300dpi raster fallback
 
-Raster/image assets need **300dpi** at final print size or they pixelate — screen assets are
+Raster/image assets need **300dpi** at final print size or they pixelate - screen assets are
 authored at 72/96dpi, which is ~3–4× too coarse for press. **Vector is preferred** wherever
 possible (logos, icons, rules) because it is resolution-independent; where raster is
 unavoidable (photography), it must carry a 300dpi guarantee. The CSS signals are
@@ -146,7 +146,7 @@ unavoidable (photography), it must carry a 300dpi guarantee. The CSS signals are
 
 | Rule-id | Constraint |
 | --- | --- |
-| **PR-DPI-01** | Raster assets MUST carry a 300dpi raster-fallback signal — an `image-resolution:` declaration (`300dpi` / `from-image`), a `min-resolution` query, or a documented 300dpi note. *(Statically checkable: absence of any 300dpi signal is flagged.)* |
+| **PR-DPI-01** | Raster assets MUST carry a 300dpi raster-fallback signal - an `image-resolution:` declaration (`300dpi` / `from-image`), a `min-resolution` query, or a documented 300dpi note. *(Statically checkable: absence of any 300dpi signal is flagged.)* |
 | PR-DPI-02 | Prefer vector (SVG/PDF) for logos, icons, and line art so they stay crisp at any output size; reserve raster for continuous-tone photography. |
 | PR-DPI-03 | Size raster assets so their *effective* resolution at the placed dimensions is ≥300dpi; upscaling a 72dpi screen asset does not add real detail. |
 
@@ -155,16 +155,16 @@ unavoidable (photography), it must carry a 300dpi guarantee. The CSS signals are
 ## 7. Print color + units
 
 Print prefers **physical units** (`mm` / `cm` / `pt` / `in`) over screen `px`, because the
-page is a physical object — `px` has no fixed physical size across RIPs. Print-safe color,
+page is a physical object - `px` has no fixed physical size across RIPs. Print-safe color,
 overprint, and knockout are production concerns the executor should honor; most are
 **render-tested guidance** (see §8), not statically asserted by the validator.
 
 | Rule-id | Constraint |
 | --- | --- |
 | PR-UNIT-01 | Use physical units (`mm`/`cm`/`pt`/`in`) for page geometry, margins, and bleed; reserve `px` for screen. *(Guidance.)* |
-| PR-COLOR-01 | **Overprint vs knockout** — small black text overprints (prints on top) to avoid registration gaps; light-on-dark knocks out. *(Render-tested — §8.)* |
-| PR-COLOR-02 | **Trap/registration** — adjacent CMYK separations are trapped (slightly overlapped) so misregistration on press shows no white gap. *(Render-tested — §8.)* |
-| PR-COLOR-03 | **True vector tessellation** — complex vector fills/gradients must tessellate without seams in the RIP. *(Render-tested — §8.)* |
+| PR-COLOR-01 | **Overprint vs knockout** - small black text overprints (prints on top) to avoid registration gaps; light-on-dark knocks out. *(Render-tested - §8.)* |
+| PR-COLOR-02 | **Trap/registration** - adjacent CMYK separations are trapped (slightly overlapped) so misregistration on press shows no white gap. *(Render-tested - §8.)* |
+| PR-COLOR-03 | **True vector tessellation** - complex vector fills/gradients must tessellate without seams in the RIP. *(Render-tested - §8.)* |
 
 ---
 
@@ -173,16 +173,16 @@ overprint, and knockout are production concerns the executor should honor; most
 This table is the **contract** the validator's `rule` ids map to. The five rule-ids below are
 the deterministic subset that `scripts/lib/print/validate-print-css.cjs` asserts via
 regex/string analysis of the supplied print CSS/HTML string. Every other rule-id in this
-catalogue is **render-tested guidance** — verified by the optional Paged.js-headless-Chrome /
+catalogue is **render-tested guidance** - verified by the optional Paged.js-headless-Chrome /
 PDFKit render-test connection (34.3-02), never asserted by the static validator.
 
 | Rule-id | Check | Statically checked by the validator? | How verified otherwise |
 | --- | --- | --- | --- |
-| **PR-PAGE-01** | An `@page` rule is present (the print box model) | **YES** — absence flagged | — |
-| **PR-BLEED-01** | A bleed box / crop-marks signal is present (`bleed:` / `marks:` / a documented bleed-marks note) | **YES** — total absence flagged | — |
-| **PR-CMYK-01** | A CMYK-awareness signal is present (`cmyk(` / `color-profile` / `@color-profile` / a CMYK note) | **YES** — total absence (pure RGB) flagged | — |
-| **PR-FONT-01** | A font-embed signal is present (`@font-face` with `src:` / a font-embed/outline note) | **YES** — absence flagged | — |
-| **PR-DPI-01** | A 300dpi raster-fallback signal is present (`image-resolution:` / `min-resolution` / a 300dpi note) | **YES** — absence flagged | — |
+| **PR-PAGE-01** | An `@page` rule is present (the print box model) | **YES** - absence flagged | - |
+| **PR-BLEED-01** | A bleed box / crop-marks signal is present (`bleed:` / `marks:` / a documented bleed-marks note) | **YES** - total absence flagged | - |
+| **PR-CMYK-01** | A CMYK-awareness signal is present (`cmyk(` / `color-profile` / `@color-profile` / a CMYK note) | **YES** - total absence (pure RGB) flagged | - |
+| **PR-FONT-01** | A font-embed signal is present (`@font-face` with `src:` / a font-embed/outline note) | **YES** - absence flagged | - |
+| **PR-DPI-01** | A 300dpi raster-fallback signal is present (`image-resolution:` / `min-resolution` / a 300dpi note) | **YES** - absence flagged | - |
 | PR-PAGE-02..03 | `size`/`margin` set, sensible page breaks | No | Render test (paginated output) |
 | PR-BLEED-02..03 | 3mm bleed value, marks in trim waste, safe area | No | Render test (preflight) |
 | PR-CMYK-02..03 | In-gamut brand colors, rich-black vs K100, **ICC-profile correctness** | No | Render test (press proof / ICC) |
@@ -198,26 +198,26 @@ Notes on the five statically-checked rules:
   and trip exactly one.
 - **CMYK awareness is satisfied by any of three signals.** A `cmyk()` color, a
   `color-profile` / `@color-profile` reference, **or** a documented `/* CMYK … */` note each
-  satisfy PR-CMYK-01 on their own — a fully RGB document with an explicit CMYK-target note
+  satisfy PR-CMYK-01 on their own - a fully RGB document with an explicit CMYK-target note
   still passes (the note records the production intent the RIP needs).
 - **Render-tested rules are out of the static validator's scope by design.** Overprint
   behavior, ICC-profile correctness, trap/registration, and true vector tessellation require
-  an actual PDF RIP / rendering engine — they are catalogued here as executor guidance and
+  an actual PDF RIP / rendering engine - they are catalogued here as executor guidance and
   verified by the optional print-render connection, never asserted statically (D-03 / D-10).
 
 ---
 
 ## 9. Cross-references
 
-- [`reference/email-design.md`](./email-design.md) — the email-constraint sibling
+- [`reference/email-design.md`](./email-design.md) - the email-constraint sibling
   (table layout, inline styles, MSO comments, dark mode). The non-web siblings share the
   catalogue-plus-static-validator shape.
-- [`reference/native-platforms.md`](./native-platforms.md) — the native token-bridge sibling
+- [`reference/native-platforms.md`](./native-platforms.md) - the native token-bridge sibling
   (SwiftUI / Compose / Flutter). The other non-web output surface.
-- [`reference/platforms.md`](./platforms.md) — the interaction-conventions sibling.
+- [`reference/platforms.md`](./platforms.md) - the interaction-conventions sibling.
 - [`scripts/lib/print/validate-print-css.cjs`](../scripts/lib/print/validate-print-css.cjs)
-  — the deterministic static validator that asserts the §8 subset; its `rule` ids are the
+  - the deterministic static validator that asserts the §8 subset; its `rule` ids are the
   constraint-ids defined here.
-- [`reference/registry.json`](./registry.json) — this catalogue is registered as the
+- [`reference/registry.json`](./registry.json) - this catalogue is registered as the
   `print-design` entry (type `heuristic`, phase `34.3`) so the registry round-trip test
   (`test/suite/reference-registry.test.cjs`) stays green (D-05, the 34.1-01 / 34.2-01 lesson).

package/reference/priority-matrix.md

@@ -1,4 +1,4 @@
-# Priority Matrix — 10 Categories, CRITICAL → LOW
+# Priority Matrix - 10 Categories, CRITICAL → LOW
 
 Adapted from `ui-ux-pro-max`. Use this to rank findings when auditing, critiquing, or deciding fix order.
 
@@ -27,5 +27,5 @@ Adapted from `ui-ux-pro-max`. Use this to rank findings when auditing, critiquin
 1. Run the discover stage audit or a manual grep pass using `reference/anti-patterns.md` patterns.
 2. For each finding, assign a category (1–10) from above.
 3. Sort by severity descending.
-4. Fix P0s before shipping — never ship with one open.
+4. Fix P0s before shipping - never ship with one open.
 5. Map each P0/P1 to a task type in the Design stage: color findings → `color` task, typography → `typography` task, accessibility → `accessibility` task.

package/reference/project-skills-guide.md

@@ -5,9 +5,9 @@ Project-local skills live at `./.claude/skills/` within the user's project (not
 ## Auto-loaded patterns
 
 Files matching `./.claude/skills/design-*-conventions.md` are read by:
-- `explore` — included in DESIGN-CONTEXT.md synthesis under a `<project_conventions>` section
-- `plan` — passed to design-planner as `<required_reading>`
-- `design` — passed to the executor as `<required_reading>`
+- `explore` - included in DESIGN-CONTEXT.md synthesis under a `<project_conventions>` section
+- `plan` - passed to design-planner as `<required_reading>`
+- `design` - passed to the executor as `<required_reading>`
 
 ## File format
 

package/reference/proportion-systems.md

@@ -7,21 +7,21 @@ tags: [proportion, spacing, baseline-grid, vertical-rhythm, modular-scale]
 last_updated: 2026-05-18
 ---
 
-# Proportion Systems — Whole-UI Modular Relationships
+# Proportion Systems - Whole-UI Modular Relationships
 
-The existing [typography reference](./typography.md) covers the modular type scale — base 16px, a ratio (1.250 Major Third, 1.333 Perfect Fourth, 1.414 √2, 1.618 φ), and the geometric ladder of font sizes that scale produces. That ladder is one slice of a larger system. A proportion system is the rule that *every* dimension in the UI — type, spacing between elements, sizing of icons and avatars, and corner radius on components — derives from a single underlying unit and a small set of multipliers, so that values across the four systems land on the same grid and visibly belong to the same composition.
+The existing [typography reference](./typography.md) covers the modular type scale - base 16px, a ratio (1.250 Major Third, 1.333 Perfect Fourth, 1.414 √2, 1.618 φ), and the geometric ladder of font sizes that scale produces. That ladder is one slice of a larger system. A proportion system is the rule that *every* dimension in the UI - type, spacing between elements, sizing of icons and avatars, and corner radius on components - derives from a single underlying unit and a small set of multipliers, so that values across the four systems land on the same grid and visibly belong to the same composition.
 
-This file exists because that whole-UI view is undocumented today: [design-system-guidance.md](./design-system-guidance.md) mentions 8pt spacing in passing, [style-vocabulary.md](./style-vocabulary.md) cites "8pt spacing grid" as a Flat Design 2.0 marker, and `typography.md` owns the type-scale slice — but nothing ties them together. An agent that picks `padding: 12px` next to body text at `16/24` on an 8pt grid is breaking proportion silently, because the cross-system relationship was never stated. This is the file an agent should consult any time it is *constructing* the underlying grid of a UI — choosing a baseline unit, deriving a spacing ladder, deciding whether icon-md should be 20px or 24px, or auditing why a layout "feels off" despite each token being internally consistent.
+This file exists because that whole-UI view is undocumented today: [design-system-guidance.md](./design-system-guidance.md) mentions 8pt spacing in passing, [style-vocabulary.md](./style-vocabulary.md) cites "8pt spacing grid" as a Flat Design 2.0 marker, and `typography.md` owns the type-scale slice - but nothing ties them together. An agent that picks `padding: 12px` next to body text at `16/24` on an 8pt grid is breaking proportion silently, because the cross-system relationship was never stated. This is the file an agent should consult any time it is *constructing* the underlying grid of a UI - choosing a baseline unit, deriving a spacing ladder, deciding whether icon-md should be 20px or 24px, or auditing why a layout "feels off" despite each token being internally consistent.
 
-The jump this file closes is from *"we use a modular type scale"* to *"we use a coherent proportion system across type + spacing + sizing + radius — the whole UI snaps to one grid."*
+The jump this file closes is from *"we use a modular type scale"* to *"we use a coherent proportion system across type + spacing + sizing + radius - the whole UI snaps to one grid."*
 
 ## Baseline Grid Systems
 
-A baseline grid is the invisible underlying structure every dimension snaps to. It is one number — `4`, `8`, or `1.414` — and the rule that no value in the UI may be authored that is not a multiple of that number. The grid is not a layout grid (columns and gutters); it is the smallest atomic unit out of which both the column grid and every spacing / sizing / radius token are composed. Three baselines dominate: 4pt, 8pt, and √2. Pick one for the whole product; do not mix.
+A baseline grid is the invisible underlying structure every dimension snaps to. It is one number - `4`, `8`, or `1.414` - and the rule that no value in the UI may be authored that is not a multiple of that number. The grid is not a layout grid (columns and gutters); it is the smallest atomic unit out of which both the column grid and every spacing / sizing / radius token are composed. Three baselines dominate: 4pt, 8pt, and √2. Pick one for the whole product; do not mix.
 
 ### 4pt Grid
 
-When it fits: dense data UIs where rows must be visually compact (trading terminals, observability dashboards, IDE-style tooling, spreadsheet-derived layouts). The 4pt unit lets you author 12px / 20px / 28px row heights that an 8pt grid forbids, which matters when 10–20 horizontal rows need to fit above the fold. The cost is that fine increments invite drift — without strict review, a team will quickly have `13px`, `15px`, and `17px` in production.
+When it fits: dense data UIs where rows must be visually compact (trading terminals, observability dashboards, IDE-style tooling, spreadsheet-derived layouts). The 4pt unit lets you author 12px / 20px / 28px row heights that an 8pt grid forbids, which matters when 10–20 horizontal rows need to fit above the fold. The cost is that fine increments invite drift - without strict review, a team will quickly have `13px`, `15px`, and `17px` in production.
 
 ```css
 /* 4pt grid — dense data UI */
@@ -46,7 +46,7 @@ When it fits: dense data UIs where rows must be visually compact (trading termin
 
 ### 8pt Grid
 
-When it fits: product UI, marketing surfaces, default for most consumer apps. Material Design, iOS Human Interface Guidelines, and the majority of modern design systems converge on 8pt because the unit is large enough to prevent drift (no one accidentally authors 9px) yet small enough to express every meaningful step. Half-units (4px) are permitted only at the smallest scale (icon padding, single-character chip insets) and are explicitly named — never freehand.
+When it fits: product UI, marketing surfaces, default for most consumer apps. Material Design, iOS Human Interface Guidelines, and the majority of modern design systems converge on 8pt because the unit is large enough to prevent drift (no one accidentally authors 9px) yet small enough to express every meaningful step. Half-units (4px) are permitted only at the smallest scale (icon padding, single-character chip insets) and are explicitly named - never freehand.
 
 ```css
 /* 8pt grid — product UI default */
@@ -71,7 +71,7 @@ When it fits: product UI, marketing surfaces, default for most consumer apps. Ma
 
 ### √2 Grid (root-2)
 
-When it fits: editorial layouts, print-adjacent surfaces, long-form article pages, document viewers. The √2 ratio (≈1.414) is the proportion that survives bisection — fold an A4 page in half and you get an A5 page with the same proportion. UIs that mirror physical paper (PDF readers, marketing landing pages with magazine layouts, layouts that breathe like print) feel right on √2 because subdivisions cascade self-similarly. The underlying spacing unit is still an integer (typically 8px or 16px) but the column and section *ratios* are √2, and key dimensions are generated by repeated multiplication or division by 1.414. See `./composition.md` §Root Rectangles — √2, √3, √5 for the geometry behind the ratio.
+When it fits: editorial layouts, print-adjacent surfaces, long-form article pages, document viewers. The √2 ratio (≈1.414) is the proportion that survives bisection - fold an A4 page in half and you get an A5 page with the same proportion. UIs that mirror physical paper (PDF readers, marketing landing pages with magazine layouts, layouts that breathe like print) feel right on √2 because subdivisions cascade self-similarly. The underlying spacing unit is still an integer (typically 8px or 16px) but the column and section *ratios* are √2, and key dimensions are generated by repeated multiplication or division by 1.414. See `./composition.md` §Root Rectangles - √2, √3, √5 for the geometry behind the ratio.
 
 ```css
 /* √2 grid — editorial / print-adjacent */
@@ -92,11 +92,11 @@ When it fits: editorial layouts, print-adjacent surfaces, long-form article page
 }
 ```
 
-**Decision rule:** if the product is a dense data UI where row density is the dominant constraint, pick 4pt. If the product is editorial or print-adjacent and pages should feel like documents, pick √2 (over an integer pixel unit). For everything else — and that is most product work — pick 8pt. Document the decision once at the design-system level; do not let individual surfaces pick their own grid.
+**Decision rule:** if the product is a dense data UI where row density is the dominant constraint, pick 4pt. If the product is editorial or print-adjacent and pages should feel like documents, pick √2 (over an integer pixel unit). For everything else - and that is most product work - pick 8pt. Document the decision once at the design-system level; do not let individual surfaces pick their own grid.
 
 ## Baseline-Grid Lock
 
-Baseline-grid lock is the discipline that every text baseline in the UI lands on a grid line — typically the same 4pt or 8pt unit used for spacing. The mechanism is the `line-height` of every text style: set line-height so the resulting line box is a whole multiple of the grid unit. Body text at 16px font with line-height `24px` consumes exactly three 8pt units per line. Heading text at 32px with line-height `40px` consumes five. Caption at 14px with line-height `24px` consumes three. Every block of text — regardless of size — stacks on the same invisible horizontal rulings.
+Baseline-grid lock is the discipline that every text baseline in the UI lands on a grid line - typically the same 4pt or 8pt unit used for spacing. The mechanism is the `line-height` of every text style: set line-height so the resulting line box is a whole multiple of the grid unit. Body text at 16px font with line-height `24px` consumes exactly three 8pt units per line. Heading text at 32px with line-height `40px` consumes five. Caption at 14px with line-height `24px` consumes three. Every block of text - regardless of size - stacks on the same invisible horizontal rulings.
 
 Lock matters because mixed-size text without it produces drift. A page that interleaves body, headings, and captions whose line-heights are *not* grid multiples will accumulate fractional-pixel errors block-by-block; by mid-page, the right column has slid out of alignment with the left. Visually the page looks "slightly wrong" without an obvious cause. Lock eliminates the symptom by construction.
 
@@ -120,7 +120,7 @@ h2          { font-size: 32px; line-height: var(--line-heading); }
 
 Vertical rhythm is the lived consequence of baseline-grid lock: because every text block consumes a whole number of grid units, block-level elements stack on the grid without ever needing manual margin tweaks. The page reads with a quiet, mechanical regularity that the eye registers as polish even when no one can articulate why. Vertical rhythm is what readers mean when they say a layout feels "professional" or "calm".
 
-The rule that produces it is: pick the baseline unit once, set every line-height in the type ramp as a multiple of that unit, and set every block-level margin (margin-top, margin-bottom, padding-block on cards and sections) as a multiple of the same unit. Once both type and spacing are on-grid, rhythm emerges automatically — no per-element adjustment.
+The rule that produces it is: pick the baseline unit once, set every line-height in the type ramp as a multiple of that unit, and set every block-level margin (margin-top, margin-bottom, padding-block on cards and sections) as a multiple of the same unit. Once both type and spacing are on-grid, rhythm emerges automatically - no per-element adjustment.
 
 ```css
 /* Vertical rhythm — body, heading, caption, all on the 8pt grid */
@@ -150,11 +150,11 @@ article > * + * {
 }
 ```
 
-**Exceptions are explicit, not freehand.** Display-scale type (font-size ≥ 56px) is often set with optical line-height — a unitless ratio of 1.05–1.15 — because mechanical 8pt multiples look too sparse at hero scale. Single-line callouts (status badges, single-character chips) may use `line-height: 1` with vertical padding rounded to the grid. Treat both as named utilities (`.display-line-height`, `.chip-vertical`) rather than ad-hoc overrides — once the exception is a token, it remains visible to audit.
+**Exceptions are explicit, not freehand.** Display-scale type (font-size ≥ 56px) is often set with optical line-height - a unitless ratio of 1.05–1.15 - because mechanical 8pt multiples look too sparse at hero scale. Single-line callouts (status badges, single-character chips) may use `line-height: 1` with vertical padding rounded to the grid. Treat both as named utilities (`.display-line-height`, `.chip-vertical`) rather than ad-hoc overrides - once the exception is a token, it remains visible to audit.
 
 ## Modular Relationships
 
-The point of the proportion system is that the four sub-systems — type, spacing, sizing, radius — are not authored independently. Each derives from the same baseline unit, and certain pairs of values across systems are intentionally identical. Body line-height equals the spacing token that separates two body paragraphs equals the height of a medium icon. The numerical equality is the visible signature of an authored composition.
+The point of the proportion system is that the four sub-systems - type, spacing, sizing, radius - are not authored independently. Each derives from the same baseline unit, and certain pairs of values across systems are intentionally identical. Body line-height equals the spacing token that separates two body paragraphs equals the height of a medium icon. The numerical equality is the visible signature of an authored composition.
 
 | System  | Token       | Value | Grid relationship              | Cross-system pairing                  |
 | ------- | ----------- | ----- | ------------------------------ | ------------------------------------- |
@@ -179,15 +179,15 @@ The point of the proportion system is that the four sub-systems — type, spacin
 | size    | avatar-md   | 48px  | 6 × baseline                   | matches `space-6`                     |
 | size    | avatar-lg   | 64px  | 8 × baseline                   | 8 grid units, matches hero spacing    |
 
-The pairing column is the asset. An agent picking a value reads across the table: "I need padding around 16px text on an 8pt grid" → `space-2` (16px) or `space-3` (24px), never `padding: 12px` (1.5 units — half-step, reserved for chips). "I need an icon next to body text" → `icon-md` (24px), because body line-height is 24px and the icon should occupy the same vertical band. The relationships make these decisions one-step.
+The pairing column is the asset. An agent picking a value reads across the table: "I need padding around 16px text on an 8pt grid" → `space-2` (16px) or `space-3` (24px), never `padding: 12px` (1.5 units - half-step, reserved for chips). "I need an icon next to body text" → `icon-md` (24px), because body line-height is 24px and the icon should occupy the same vertical band. The relationships make these decisions one-step.
 
-**A concrete pairing example.** Body text is 16px on 24px line-height (8pt grid). A button next to body text should have vertical padding such that the total button height is a clean multiple of the grid. Padding 8px + line-height 24px + padding 8px = 40px (5 units — on-grid). Padding 12px + line-height 24px + padding 12px = 48px (6 units — on-grid). Padding 10px gives 44px (5.5 units — off-grid, breaks rhythm); the only way to know that is to consult the matrix. Once a team internalizes the pairings, the choice between 8px and 12px stops being aesthetic — both are correct, both produce on-grid heights, and the team picks based on density.
+**A concrete pairing example.** Body text is 16px on 24px line-height (8pt grid). A button next to body text should have vertical padding such that the total button height is a clean multiple of the grid. Padding 8px + line-height 24px + padding 8px = 40px (5 units - on-grid). Padding 12px + line-height 24px + padding 12px = 48px (6 units - on-grid). Padding 10px gives 44px (5.5 units - off-grid, breaks rhythm); the only way to know that is to consult the matrix. Once a team internalizes the pairings, the choice between 8px and 12px stops being aesthetic - both are correct, both produce on-grid heights, and the team picks based on density.
 
 ## Radius Scale as Proportion
 
-Corner radius is the easiest token to author ad-hoc — `border-radius: 6px` looks fine in isolation — and the easiest to break the system with. The radius scale belongs to proportion because it must derive from component height, not be chosen freehand. The common rule is `radius-md ≈ 0.25 × component height`: a 40px-tall button gets 8px radius, a 32px-tall chip gets 8px radius, a 24px-tall tag gets 4px or 8px. The 0.25× ratio is visually balanced — large enough to register as "rounded", small enough to keep the geometry of the rectangle dominant.
+Corner radius is the easiest token to author ad-hoc - `border-radius: 6px` looks fine in isolation - and the easiest to break the system with. The radius scale belongs to proportion because it must derive from component height, not be chosen freehand. The common rule is `radius-md ≈ 0.25 × component height`: a 40px-tall button gets 8px radius, a 32px-tall chip gets 8px radius, a 24px-tall tag gets 4px or 8px. The 0.25× ratio is visually balanced - large enough to register as "rounded", small enough to keep the geometry of the rectangle dominant.
 
-Two exceptions matter and are named, not freehand. **Pill** sets `border-radius: 9999px` (or `border-radius: 50%` on a square) — explicit "fully rounded", used for tags, status badges, and avatar wrappers. **Square** sets `border-radius: 0` — explicit "no rounding", used inside data tables where rectangular cells must butt against each other, and on heavily geometric brand systems.
+Two exceptions matter and are named, not freehand. **Pill** sets `border-radius: 9999px` (or `border-radius: 50%` on a square) - explicit "fully rounded", used for tags, status badges, and avatar wrappers. **Square** sets `border-radius: 0` - explicit "no rounding", used inside data tables where rectangular cells must butt against each other, and on heavily geometric brand systems.
 
 ```css
 /* Radius scale as proportion to component height */
@@ -219,7 +219,7 @@ Two exceptions matter and are named, not freehand. **Pill** sets `border-radius:
 
 ## Sizing Scale Derivation
 
-Sizing tokens — icon dimensions, avatar dimensions, button heights, input heights — are not a separate ladder. They are derived from the spacing scale by consistent multipliers, so that every size token equals some `space-N` token. This is the rule that prevents sizing drift: a new size token must reuse an existing spacing value; it may not introduce a new pixel value.
+Sizing tokens - icon dimensions, avatar dimensions, button heights, input heights - are not a separate ladder. They are derived from the spacing scale by consistent multipliers, so that every size token equals some `space-N` token. This is the rule that prevents sizing drift: a new size token must reuse an existing spacing value; it may not introduce a new pixel value.
 
 The derivation table for an 8pt grid:
 
@@ -254,14 +254,14 @@ The derivation table for an 8pt grid:
 }
 ```
 
-The rule that makes this work: **a new sizing token must derive from spacing — never freehand.** If a designer needs a 36px button, the answer is not `--button-custom: 36px`; the answer is either 32px (`--space-4`) or 40px (`--space-5`), and the designer picks one. The token system declines to express off-grid sizes, which is the point.
+The rule that makes this work: **a new sizing token must derive from spacing - never freehand.** If a designer needs a 36px button, the answer is not `--button-custom: 36px`; the answer is either 32px (`--space-4`) or 40px (`--space-5`), and the designer picks one. The token system declines to express off-grid sizes, which is the point.
 
 ## Cross-References
 
-- [design-system-guidance.md](./design-system-guidance.md) — general design-system authoring context that this file deepens for proportion. That file mentions 8pt grids in passing; this file is the formal treatment.
-- [typography.md](./typography.md) §Type Scale Systems — the canonical modular-scale slice this file extends to the whole UI. Read that section first for the upstream type ladder.
-- [style-vocabulary.md](./style-vocabulary.md) — style rows that cite "8pt spacing grid" (Flat Design 2.0) and other proportional vocabulary surfaces. This file is the underlying mechanism behind those style-row markers.
+- [design-system-guidance.md](./design-system-guidance.md) - general design-system authoring context that this file deepens for proportion. That file mentions 8pt grids in passing; this file is the formal treatment.
+- [typography.md](./typography.md) §Type Scale Systems - the canonical modular-scale slice this file extends to the whole UI. Read that section first for the upstream type ladder.
+- [style-vocabulary.md](./style-vocabulary.md) - style rows that cite "8pt spacing grid" (Flat Design 2.0) and other proportional vocabulary surfaces. This file is the underlying mechanism behind those style-row markers.
 
-Forward reading: [composition.md](./composition.md) §Root Rectangles — √2, √3, √5 for the geometry behind the √2 grid baseline option above.
+Forward reading: [composition.md](./composition.md) §Root Rectangles - √2, √3, √5 for the geometry behind the √2 grid baseline option above.
 
 Note: reciprocal inbound cross-links from these files into `proportion-systems.md` land in Phase 28-06 (additive-only, decision D-06). This file declares its three outbound links now; the inverse direction is a separate, batched edit.

package/reference/pseudonymization-rules.md

@@ -12,13 +12,13 @@ The 8 substitution rules applied by `scripts/lib/pseudonymize.cjs` to identity-c
 
 ## Pseudonymization, not anonymization
 
-These rules **reduce** identity correlation. They do not **eliminate** it. A determined adversary with side-channel data — writing style, code-style patterns, repository fingerprints, timing — may still re-identify a reporter. Phase 30 explicitly delivers pseudonymization-not-anonymization (CONTEXT D-01); over-promising would be misleading.
+These rules **reduce** identity correlation. They do not **eliminate** it. A determined adversary with side-channel data - writing style, code-style patterns, repository fingerprints, timing - may still re-identify a reporter. Phase 30 explicitly delivers pseudonymization-not-anonymization (CONTEXT D-01); over-promising would be misleading.
 
 Pseudonymization here serves three concrete goals:
 
 - **(a) Prevent casual identification** by other users who later read the public GitHub issue.
 - **(b) Reduce corporate-DLP false-positives** at submission time on common identifier shapes (usernames in paths, hostnames in stack traces, email patterns in logs). The pseudonymized payload is less likely to be intercepted by enterprise DLP tools that scan for these exact patterns.
-- **(c) Give the user a structural opportunity** to inspect and edit the payload before it leaves their machine. The pseudonymization step makes the payload's identity-correlation surface visible — the user can read it and decide.
+- **(c) Give the user a structural opportunity** to inspect and edit the payload before it leaves their machine. The pseudonymization step makes the payload's identity-correlation surface visible - the user can read it and decide.
 
 Submission is always user-initiated and user-reviewed per Plan 30-04 (CONTEXT D-03). Phase 30 does **not** auto-submit, ever.
 
@@ -28,8 +28,8 @@ Pseudonymization runs **after** redaction (`scripts/lib/redact.cjs`, Phase 22) i
 
 | Layer | Module | What it scrubs |
 |---|---|---|
-| Secrets (high-stakes floor) | `scripts/lib/redact.cjs` | Tokens, API keys, JWTs, PEM blocks, AWS credentials, Slack/Stripe/GitHub tokens — strings that must **never** escape |
-| Identity (privacy) | `scripts/lib/pseudonymize.cjs` | Names, paths, hostnames, repo origins, env-var values, emails, IPs — strings that **may** be published but should not personally identify the reporter |
+| Secrets (high-stakes floor) | `scripts/lib/redact.cjs` | Tokens, API keys, JWTs, PEM blocks, AWS credentials, Slack/Stripe/GitHub tokens - strings that must **never** escape |
+| Identity (privacy) | `scripts/lib/pseudonymize.cjs` | Names, paths, hostnames, repo origins, env-var values, emails, IPs - strings that **may** be published but should not personally identify the reporter |
 
 Redaction handles "this string must never escape"; pseudonymization handles "this string is fine to publish but should not personally identify the reporter." The two modules do not import each other; composition lives at the caller (Plan 30-02 payload assembly). See CONTEXT D-01 for the framing rationale and CONTEXT references for the redaction prerequisite.
 
@@ -37,7 +37,7 @@ Redaction handles "this string must never escape"; pseudonymization handles "thi
 
 Eight rules. Each rule has a stable id (R1..R8) used by `/gdd:update --show-privacy-diff` (Plan 30-07) to enumerate active rules.
 
-### R1 — git-identity
+### R1 - git-identity
 
 **Replaces:** `user.name` and `user.email` from git config when they appear in payload strings (stack traces, log messages, commit-author lines).
 
@@ -51,7 +51,7 @@ Author: <user> <<user>@<domain>> committed at 12:34
 
 **Coverage notes:** Word-boundary regex (`\b<name>\b`) prevents stripping unrelated substrings. Email match is case-insensitive (`alice@example.com` and `Alice@Example.Com` both replaced). Name values shorter than 2 chars and email values shorter than 3 chars are skipped to avoid over-eager matching on common short sequences.
 
-### R2 — absolute-paths
+### R2 - absolute-paths
 
 **Replaces:** Home-directory absolute paths across all three OS conventions:
 
@@ -68,9 +68,9 @@ Author: <user> <<user>@<domain>> committed at 12:34
 C:\Users\alice\code\proj\file.ts:42  →  <home>\code\proj\file.ts:42
 ```
 
-**Coverage notes:** Six regex sweeps — three identity-aware (when the name is known) and three generic (matching `/Users/<any>/`, `/home/<any>/`, `<drive>:\Users\<any>\`). Identity-aware sweeps run first so the identity-aware substitution takes precedence; generic sweeps catch references to teammates or other users that may appear in stack traces.
+**Coverage notes:** Six regex sweeps - three identity-aware (when the name is known) and three generic (matching `/Users/<any>/`, `/home/<any>/`, `<drive>:\Users\<any>\`). Identity-aware sweeps run first so the identity-aware substitution takes precedence; generic sweeps catch references to teammates or other users that may appear in stack traces.
 
-### R3 — hostname
+### R3 - hostname
 
 **Replaces:** `os.hostname()` value with `<host>`.
 
@@ -82,9 +82,9 @@ Connected to alices-macbook.local from alices-macbook
 Connected to <host>.local from <host>
 ```
 
-**Coverage notes:** Two sweeps — one for `@hostname` (ssh-shape), one with standard word-boundary. Hostnames shorter than 2 chars are skipped.
+**Coverage notes:** Two sweeps - one for `@hostname` (ssh-shape), one with standard word-boundary. Hostnames shorter than 2 chars are skipped.
 
-### R4 — repo-origin
+### R4 - repo-origin
 
 **Replaces:** Git origin URL with `<category>-hash:<sha8>` where:
 
@@ -100,9 +100,9 @@ Remote: git@github.com:acme-corp/internal-tools.git
 Remote: private-org-hash:a1b2c3d4
 ```
 
-**Coverage notes:** Caller resolves visibility via `gh repo view --json visibility` (or skips if `gh` is absent — module then uses the conservative `private-org-hash` default). The module performs no network calls; visibility is an injected `opts.repoVisibility` value. Owner-is-user vs owner-is-org distinction is the caller's responsibility (the module cannot tell from a URL alone). Both the raw `repoOrigin` substring and the normalized form are substituted so multiple shapes of the same URL in a stack trace all collapse to one placeholder.
+**Coverage notes:** Caller resolves visibility via `gh repo view --json visibility` (or skips if `gh` is absent - module then uses the conservative `private-org-hash` default). The module performs no network calls; visibility is an injected `opts.repoVisibility` value. Owner-is-user vs owner-is-org distinction is the caller's responsibility (the module cannot tell from a URL alone). Both the raw `repoOrigin` substring and the normalized form are substituted so multiple shapes of the same URL in a stack trace all collapse to one placeholder.
 
-### R5 — env-vars
+### R5 - env-vars
 
 **Replaces:** **VALUES** (not key names) of these environment variables wherever they appear in payload strings:
 
@@ -119,13 +119,13 @@ Error: GITHUB_TOKEN=ghp_abcDEFghi123 was rejected
 Error: GITHUB_TOKEN=<env:GITHUB_TOKEN> was rejected
 ```
 
-**Coverage notes:** Empty / 1-char / 2-char values are skipped (corruption guard — short values would over-match unrelated content). Longer-value entries are processed first (descending by length) so a token that contains another's substring does not get half-replaced. R5 walks the entire payload tree (strings get value substitution, objects/arrays recurse, cycles detected via WeakSet) — value substitution works regardless of nesting depth.
+**Coverage notes:** Empty / 1-char / 2-char values are skipped (corruption guard - short values would over-match unrelated content). Longer-value entries are processed first (descending by length) so a token that contains another's substring does not get half-replaced. R5 walks the entire payload tree (strings get value substitution, objects/arrays recurse, cycles detected via WeakSet) - value substitution works regardless of nesting depth.
 
-### R6 — email-in-logs
+### R6 - email-in-logs
 
 **Replaces:** Email addresses that slipped past R1's identity-aware substitution (e.g., third-party emails mentioned in a stack trace or log line) with `<email>`.
 
-**Why:** R1 catches the user's own `user.email`. R6 is the generic catch-all for any other email addresses that may appear in a payload — including teammates' emails in error messages, vendor support emails in stack traces, or addresses pulled from data being processed at the time of the error.
+**Why:** R1 catches the user's own `user.email`. R6 is the generic catch-all for any other email addresses that may appear in a payload - including teammates' emails in error messages, vendor support emails in stack traces, or addresses pulled from data being processed at the time of the error.
 
 **Before/after example:**
 ```
@@ -135,7 +135,7 @@ Stack frame: at notify(<email>)
 
 **Coverage notes:** Standard RFC-5322-ish regex (`/[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g`). R6 runs **after** R1 in the rule pipeline so identity-aware substitution takes precedence (the user's email becomes `<user>@<domain>`, not `<email>`).
 
-### R7 — ip-addresses
+### R7 - ip-addresses
 
 **Replaces:** IPv4 and IPv6 addresses, retaining only network class:
 
@@ -152,16 +152,16 @@ fe80::1ff:fe23:4567:890a       →  <ipv6:fe80::1ff:fe23:4567::>
 
 **Coverage notes:** Regex guards prevent false-positives on:
 
-- Semver strings (`v1.2.3.4`) — leading `v` blocked by lookbehind
-- Email-adjacent strings (`@1.2.3.4`) — `@` blocked by lookbehind
-- Date strings (`2026-05-20`) — dashes don't match the dotted-octet pattern
-- Longer dotted strings (`1.2.3.4.5`) — trailing `.` blocked by lookahead
+- Semver strings (`v1.2.3.4`) - leading `v` blocked by lookbehind
+- Email-adjacent strings (`@1.2.3.4`) - `@` blocked by lookbehind
+- Date strings (`2026-05-20`) - dashes don't match the dotted-octet pattern
+- Longer dotted strings (`1.2.3.4.5`) - trailing `.` blocked by lookahead
 
 IPv6 regex requires at least 5 segments to avoid false-positives on time strings (`12:34`, `12:34:56`).
 
-### R8 — stable-pseudonym
+### R8 - stable-pseudonym
 
-**Replaces:** Nothing in payload text — R8 is a **separate utility export** (`stablePseudonym(userId, repoOrigin)`) the caller invokes when constructing payload metadata.
+**Replaces:** Nothing in payload text - R8 is a **separate utility export** (`stablePseudonym(userId, repoOrigin)`) the caller invokes when constructing payload metadata.
 
 **Why:** Maintainers want to group reports from the same user-and-repo without ever seeing identity. A deterministic 8-char hex pseudonym = `sha256(userId + ':' + normalized_repo_origin)[:8]` gives them that grouping key. Same user + same repo always hashes to the same 8 chars; different inputs produce different outputs. The URL normalization (strip protocol prefix, strip `.git`, lowercase) makes the hash stable across `git@github.com:foo/bar.git` and `https://github.com/foo/bar` shapes of the same origin.
 
@@ -173,17 +173,17 @@ repoOrigin: 'git@github.com:foo/bar.git'
 pseudonym: 'a1b2c3d4'
 ```
 
-**Coverage notes:** Defensive sentinel — if either input is falsy, returns `'00000000'` so call sites never crash on missing inputs. Caller may check for the sentinel if it matters. The `:` separator between userId and repoOrigin prevents collisions between `userId='a' + repoOrigin='bcd'` and `userId='abc' + repoOrigin='d'`.
+**Coverage notes:** Defensive sentinel - if either input is falsy, returns `'00000000'` so call sites never crash on missing inputs. Caller may check for the sentinel if it matters. The `:` separator between userId and repoOrigin prevents collisions between `userId='a' + repoOrigin='bcd'` and `userId='abc' + repoOrigin='d'`.
 
 ## Consumed by
 
-- **`scripts/lib/pseudonymize.cjs`** — implements R1..R8. The module's `RULES` manifest constant has a 1:1 correspondence with the sections above (R1..R8 ids match `RULES[i].id`).
-- **Plan 30-02 (payload assembly)** — composes Phase 22 redaction + Phase 30 pseudonymization.
-- **Plan 30-04 (consent prompt)** — uses the `replacements` log returned by `pseudonymize()` to display "X replacements made (R1: 3, R2: 5, ...)" summary before the user submits.
-- **Plan 30-07 (`/gdd:update --show-privacy-diff`)** — diffs this document plus `pseudonymize.cjs` between installed and target versions of the plugin. Always-show on first run after upgrade that touched these files; opt-in afterward (CONTEXT D-09).
+- **`scripts/lib/pseudonymize.cjs`** - implements R1..R8. The module's `RULES` manifest constant has a 1:1 correspondence with the sections above (R1..R8 ids match `RULES[i].id`).
+- **Plan 30-02 (payload assembly)** - composes Phase 22 redaction + Phase 30 pseudonymization.
+- **Plan 30-04 (consent prompt)** - uses the `replacements` log returned by `pseudonymize()` to display "X replacements made (R1: 3, R2: 5, ...)" summary before the user submits.
+- **Plan 30-07 (`/gdd:update --show-privacy-diff`)** - diffs this document plus `pseudonymize.cjs` between installed and target versions of the plugin. Always-show on first run after upgrade that touched these files; opt-in afterward (CONTEXT D-09).
 
 ## See also
 
-- `scripts/lib/redact.cjs` (Phase 22) — secrets-stripping prerequisite layer in the payload pipeline.
-- `.planning/phases/30-issue-reporter/CONTEXT.md` — D-01 pseudonymization-not-anonymization framing; D-13 synthetic-fixtures-plus-tmpdir test contract.
-- `reference/registry.json` — registry entry for this document (`name: 'pseudonymization-rules'`, `phase: 30`, `type: 'meta-rules'`).
+- `scripts/lib/redact.cjs` (Phase 22) - secrets-stripping prerequisite layer in the payload pipeline.
+- `.planning/phases/30-issue-reporter/CONTEXT.md` - D-01 pseudonymization-not-anonymization framing; D-13 synthetic-fixtures-plus-tmpdir test contract.
+- `reference/registry.json` - registry entry for this document (`name: 'pseudonymization-rules'`, `phase: 30`, `type: 'meta-rules'`).