@hegemonart/get-design-done 1.42.0 → 1.43.0

package/reference/authority-feeds.md

@@ -1,6 +1,6 @@
-# Authority Feeds — Whitelist
+# Authority Feeds - Whitelist
 
-> **Scope:** Curated whitelist of **design authorities** — sources that ship specs, guidelines, or named-practitioner curation. Consumed by `agents/design-authority-watcher.md` at runtime. Rejected kinds are listed explicitly below and enforced by `scripts/tests/test-authority-rejected-kinds.sh`.
+> **Scope:** Curated whitelist of **design authorities** - sources that ship specs, guidelines, or named-practitioner curation. Consumed by `agents/design-authority-watcher.md` at runtime. Rejected kinds are listed explicitly below and enforced by `scripts/tests/test-authority-rejected-kinds.sh`.
 >
 > **Anti-slop thesis:** No Dribbble. No Behance. No LinkedIn. No generic trending aggregators. See `.planning/PROJECT.md` and `.planning/phases/13.2-external-authority-watcher/13.2-CONTEXT.md` §D-08.
 
@@ -11,43 +11,43 @@
 
 ## Spec sources (4-5 feeds)
 
-- **[WAI-ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/)** — `kind: spec-source` · `url: https://github.com/w3c/aria-practices/releases.atom` · `cadence-hint: monthly` · *Normative accessibility patterns from the W3C ARIA working group; release-tagged on each APG update.*
-- **[Material Design 3](https://m3.material.io/)** — `kind: spec-source` · `url: https://github.com/material-components/material-web/releases.atom` · `cadence-hint: weekly` · *Google's design system release notes; new tokens and components land here first.*
-- **[Apple Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/)** — `kind: spec-source` · `url: https://developer.apple.com/news/releases/rss/releases.rss` · `cadence-hint: irregular` · *Apple developer release feed — HIG updates ship alongside SDK announcements.*
-- **[Fluent 2 Design System](https://fluent2.microsoft.design/)** — `kind: spec-source` · `url: https://github.com/microsoft/fluentui/releases.atom` · `cadence-hint: weekly` · *Microsoft's cross-platform design system; normative component API and token changes.*
-- **[W3C Design Tokens Community Group](https://www.w3.org/community/design-tokens/)** — `kind: spec-source` · `url: https://github.com/design-tokens/community-group/commits/main.atom` · `cadence-hint: monthly` · *Draft tokens format spec; commit feed surfaces spec edits before formal publication.*
+- **[WAI-ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/)** - `kind: spec-source` · `url: https://github.com/w3c/aria-practices/releases.atom` · `cadence-hint: monthly` · *Normative accessibility patterns from the W3C ARIA working group; release-tagged on each APG update.*
+- **[Material Design 3](https://m3.material.io/)** - `kind: spec-source` · `url: https://github.com/material-components/material-web/releases.atom` · `cadence-hint: weekly` · *Google's design system release notes; new tokens and components land here first.*
+- **[Apple Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/)** - `kind: spec-source` · `url: https://developer.apple.com/news/releases/rss/releases.rss` · `cadence-hint: irregular` · *Apple developer release feed - HIG updates ship alongside SDK announcements.*
+- **[Fluent 2 Design System](https://fluent2.microsoft.design/)** - `kind: spec-source` · `url: https://github.com/microsoft/fluentui/releases.atom` · `cadence-hint: weekly` · *Microsoft's cross-platform design system; normative component API and token changes.*
+- **[W3C Design Tokens Community Group](https://www.w3.org/community/design-tokens/)** - `kind: spec-source` · `url: https://github.com/design-tokens/community-group/commits/main.atom` · `cadence-hint: monthly` · *Draft tokens format spec; commit feed surfaces spec edits before formal publication.*
 
 ## Component systems (6-8 feeds)
 
-- **[Radix UI](https://www.radix-ui.com/)** — `kind: component-system` · `url: https://github.com/radix-ui/primitives/releases.atom` · `cadence-hint: weekly` · *Unstyled accessible primitives; release notes document ARIA behavior changes.*
-- **[shadcn/ui](https://ui.shadcn.com/)** — `kind: component-system` · `url: https://github.com/shadcn-ui/ui/releases.atom` · `cadence-hint: weekly` · *Copy-paste component library built on Radix + Tailwind; release notes map to new patterns.*
-- **[Shopify Polaris](https://polaris.shopify.com/)** — `kind: component-system` · `url: https://github.com/Shopify/polaris/releases.atom` · `cadence-hint: weekly` · *Shopify admin design system; commerce-tuned component patterns.*
-- **[IBM Carbon](https://carbondesignsystem.com/)** — `kind: component-system` · `url: https://github.com/carbon-design-system/carbon/releases.atom` · `cadence-hint: weekly` · *IBM's enterprise design system; strong on data-dense patterns and accessibility.*
-- **[GitHub Primer](https://primer.style/)** — `kind: component-system` · `url: https://github.com/primer/react/releases.atom` · `cadence-hint: weekly` · *GitHub's design system; opinionated developer-tool patterns.*
-- **[Atlassian Design System](https://atlassian.design/)** — `kind: component-system` · `url: https://github.com/atlassian/design-system/releases.atom` · `cadence-hint: weekly` · *Jira/Confluence design system; strong on collaboration and editor patterns.*
-- **[Ant Design](https://ant.design/)** — `kind: component-system` · `url: https://github.com/ant-design/ant-design/releases.atom` · `cadence-hint: weekly` · *Enterprise React component library with deep form and table patterns.*
-- **[Mantine](https://mantine.dev/)** — `kind: component-system` · `url: https://github.com/mantinedev/mantine/releases.atom` · `cadence-hint: weekly` · *React components with hooks-first architecture; strong accessibility defaults.*
+- **[Radix UI](https://www.radix-ui.com/)** - `kind: component-system` · `url: https://github.com/radix-ui/primitives/releases.atom` · `cadence-hint: weekly` · *Unstyled accessible primitives; release notes document ARIA behavior changes.*
+- **[shadcn/ui](https://ui.shadcn.com/)** - `kind: component-system` · `url: https://github.com/shadcn-ui/ui/releases.atom` · `cadence-hint: weekly` · *Copy-paste component library built on Radix + Tailwind; release notes map to new patterns.*
+- **[Shopify Polaris](https://polaris.shopify.com/)** - `kind: component-system` · `url: https://github.com/Shopify/polaris/releases.atom` · `cadence-hint: weekly` · *Shopify admin design system; commerce-tuned component patterns.*
+- **[IBM Carbon](https://carbondesignsystem.com/)** - `kind: component-system` · `url: https://github.com/carbon-design-system/carbon/releases.atom` · `cadence-hint: weekly` · *IBM's enterprise design system; strong on data-dense patterns and accessibility.*
+- **[GitHub Primer](https://primer.style/)** - `kind: component-system` · `url: https://github.com/primer/react/releases.atom` · `cadence-hint: weekly` · *GitHub's design system; opinionated developer-tool patterns.*
+- **[Atlassian Design System](https://atlassian.design/)** - `kind: component-system` · `url: https://github.com/atlassian/design-system/releases.atom` · `cadence-hint: weekly` · *Jira/Confluence design system; strong on collaboration and editor patterns.*
+- **[Ant Design](https://ant.design/)** - `kind: component-system` · `url: https://github.com/ant-design/ant-design/releases.atom` · `cadence-hint: weekly` · *Enterprise React component library with deep form and table patterns.*
+- **[Mantine](https://mantine.dev/)** - `kind: component-system` · `url: https://github.com/mantinedev/mantine/releases.atom` · `cadence-hint: weekly` · *React components with hooks-first architecture; strong accessibility defaults.*
 
 ## Research institutions (2-3 feeds)
 
-- **[Nielsen Norman Group Articles](https://www.nngroup.com/articles/)** — `kind: research` · `url: https://www.nngroup.com/feed/rss/` · `cadence-hint: weekly` · *UX research articles from the Nielsen Norman Group; heuristic updates and usability findings ship here.*
-- **[Laws of UX](https://lawsofux.com/)** — `kind: research` · `url: https://github.com/jonyablonski/laws-of-ux/releases.atom` · `cadence-hint: monthly` · *Jon Yablonski's curated catalogue of psychology-rooted UX principles; release feed tracks new laws and revisions.*
-- **[Baymard Institute](https://baymard.com/)** — `kind: research` · `url: https://baymard.com/blog/rss` · `cadence-hint: monthly` · *E-commerce UX research with empirical benchmarks; public surface of their large-scale usability studies.*
+- **[Nielsen Norman Group Articles](https://www.nngroup.com/articles/)** - `kind: research` · `url: https://www.nngroup.com/feed/rss/` · `cadence-hint: weekly` · *UX research articles from the Nielsen Norman Group; heuristic updates and usability findings ship here.*
+- **[Laws of UX](https://lawsofux.com/)** - `kind: research` · `url: https://github.com/jonyablonski/laws-of-ux/releases.atom` · `cadence-hint: monthly` · *Jon Yablonski's curated catalogue of psychology-rooted UX principles; release feed tracks new laws and revisions.*
+- **[Baymard Institute](https://baymard.com/)** - `kind: research` · `url: https://baymard.com/blog/rss` · `cadence-hint: monthly` · *E-commerce UX research with empirical benchmarks; public surface of their large-scale usability studies.*
 
 ## Named practitioners (10-12 feeds)
 
-- **[Adam Wathan](https://adamwathan.me/)** — `kind: named-practitioner` · `url: https://adamwathan.me/feed.xml` · `cadence-hint: monthly` · *Tailwind creator; utility-first CSS, component API design, refactoring patterns.*
-- **[Ryan Mulligan](https://ryanmulligan.dev/)** — `kind: named-practitioner` · `url: https://ryanmulligan.dev/feed.xml` · `cadence-hint: monthly` · *CSS craft at spec-adjacent depth; cascade layers, container queries, color functions.*
-- **[Rachel Andrew](https://rachelandrew.co.uk/)** — `kind: named-practitioner` · `url: https://rachelandrew.co.uk/feed/atom` · `cadence-hint: monthly` · *CSS Working Group member; grid, layout, and evolving layout-engine features.*
-- **[Josh W. Comeau](https://www.joshwcomeau.com/)** — `kind: named-practitioner` · `url: https://www.joshwcomeau.com/rss.xml` · `cadence-hint: monthly` · *Interactive explainers on CSS, animation, and React rendering; durable reference-quality deep dives.*
-- **[Ahmad Shadeed](https://ishadeed.com/)** — `kind: named-practitioner` · `url: https://ishadeed.com/rss.xml` · `cadence-hint: monthly` · *CSS layout and component articles grounded in real interface patterns.*
-- **[Sara Soueidan](https://www.sarasoueidan.com/)** — `kind: named-practitioner` · `url: https://www.sarasoueidan.com/feed.xml` · `cadence-hint: quarterly` · *SVG, accessibility, and inclusive design with spec-level rigor.*
-- **[Lea Verou](https://lea.verou.me/)** — `kind: named-practitioner` · `url: https://lea.verou.me/feed/atom` · `cadence-hint: quarterly` · *CSS Working Group invited expert; writes about the spec surface before it ships.*
-- **[Scott Jehl](https://scottjehl.com/)** — `kind: named-practitioner` · `url: https://scottjehl.com/feed/` · `cadence-hint: monthly` · *Progressive enhancement and web performance; long-form durable analysis.*
-- **[Heydon Pickering](https://heydonworks.com/)** — `kind: named-practitioner` · `url: https://heydonworks.com/feed.xml` · `cadence-hint: irregular` · *Accessibility-first component design; Inclusive Components author.*
-- **[Una Kravets](https://una.im/)** — `kind: named-practitioner` · `url: https://una.im/feed.xml` · `cadence-hint: monthly` · *Chrome DevRel on CSS; surfaces and explains new platform capabilities.*
-- **[Don Norman — jnd.org](https://jnd.org/)** — `kind: named-practitioner` · `url: https://jnd.org/feed/` · `cadence-hint: monthly` · *Don Norman's essays on emotional design, affordances, cognitive design, and human-centered AI. Primary source for `reference/emotional-design.md`.*
-- **[Vitsœ — Dieter Rams](https://www.vitsoe.com/gb/about/good-design)** — `kind: named-practitioner` · `url: https://www.vitsoe.com/feed` · `cadence-hint: irregular` · *Canonical source for Rams's 10 Principles of Good Design. Published by Vitsœ, who worked directly with Rams at Braun. Primary source for the Rams Lens in `reference/checklists.md`.*
+- **[Adam Wathan](https://adamwathan.me/)** - `kind: named-practitioner` · `url: https://adamwathan.me/feed.xml` · `cadence-hint: monthly` · *Tailwind creator; utility-first CSS, component API design, refactoring patterns.*
+- **[Ryan Mulligan](https://ryanmulligan.dev/)** - `kind: named-practitioner` · `url: https://ryanmulligan.dev/feed.xml` · `cadence-hint: monthly` · *CSS craft at spec-adjacent depth; cascade layers, container queries, color functions.*
+- **[Rachel Andrew](https://rachelandrew.co.uk/)** - `kind: named-practitioner` · `url: https://rachelandrew.co.uk/feed/atom` · `cadence-hint: monthly` · *CSS Working Group member; grid, layout, and evolving layout-engine features.*
+- **[Josh W. Comeau](https://www.joshwcomeau.com/)** - `kind: named-practitioner` · `url: https://www.joshwcomeau.com/rss.xml` · `cadence-hint: monthly` · *Interactive explainers on CSS, animation, and React rendering; durable reference-quality deep dives.*
+- **[Ahmad Shadeed](https://ishadeed.com/)** - `kind: named-practitioner` · `url: https://ishadeed.com/rss.xml` · `cadence-hint: monthly` · *CSS layout and component articles grounded in real interface patterns.*
+- **[Sara Soueidan](https://www.sarasoueidan.com/)** - `kind: named-practitioner` · `url: https://www.sarasoueidan.com/feed.xml` · `cadence-hint: quarterly` · *SVG, accessibility, and inclusive design with spec-level rigor.*
+- **[Lea Verou](https://lea.verou.me/)** - `kind: named-practitioner` · `url: https://lea.verou.me/feed/atom` · `cadence-hint: quarterly` · *CSS Working Group invited expert; writes about the spec surface before it ships.*
+- **[Scott Jehl](https://scottjehl.com/)** - `kind: named-practitioner` · `url: https://scottjehl.com/feed/` · `cadence-hint: monthly` · *Progressive enhancement and web performance; long-form durable analysis.*
+- **[Heydon Pickering](https://heydonworks.com/)** - `kind: named-practitioner` · `url: https://heydonworks.com/feed.xml` · `cadence-hint: irregular` · *Accessibility-first component design; Inclusive Components author.*
+- **[Una Kravets](https://una.im/)** - `kind: named-practitioner` · `url: https://una.im/feed.xml` · `cadence-hint: monthly` · *Chrome DevRel on CSS; surfaces and explains new platform capabilities.*
+- **[Don Norman - jnd.org](https://jnd.org/)** - `kind: named-practitioner` · `url: https://jnd.org/feed/` · `cadence-hint: monthly` · *Don Norman's essays on emotional design, affordances, cognitive design, and human-centered AI. Primary source for `reference/emotional-design.md`.*
+- **[Vitsœ - Dieter Rams](https://www.vitsoe.com/gb/about/good-design)** - `kind: named-practitioner` · `url: https://www.vitsoe.com/feed` · `cadence-hint: irregular` · *Canonical source for Rams's 10 Principles of Good Design. Published by Vitsœ, who worked directly with Rams at Braun. Primary source for the Rams Lens in `reference/checklists.md`.*
 
 ## User-added Are.na channels (user-extensible)
 
@@ -59,13 +59,13 @@ Are.na channels are user-curated reference collections. Add your own channel by
 
 ## Rejected kinds
 
-The following hosts and feed kinds are **explicitly rejected** from this whitelist. This list is enforced by `scripts/tests/test-authority-rejected-kinds.sh` — any merge that adds a matching URL fails CI.
+The following hosts and feed kinds are **explicitly rejected** from this whitelist. This list is enforced by `scripts/tests/test-authority-rejected-kinds.sh` - any merge that adds a matching URL fails CI.
 
-- **dribbble.com** — visual-trend aggregator; no normative content, no named-practitioner curation.
-- **behance.net** — portfolio aggregator; same category.
-- **linkedin.com** — social feed; signal-to-noise ratio incompatible with the plugin's anti-slop thesis.
-- **medium.com/topic/\*** — generic topic feeds; named Medium authors may appear as `named-practitioner` entries, but topic-level feeds are rejected wholesale.
-- **"trending"-style aggregators** (e.g., product-hunt daily digests, "top 10 UI" roundups) — curatorial output indistinguishable from advertising.
+- **dribbble.com** - visual-trend aggregator; no normative content, no named-practitioner curation.
+- **behance.net** - portfolio aggregator; same category.
+- **linkedin.com** - social feed; signal-to-noise ratio incompatible with the plugin's anti-slop thesis.
+- **medium.com/topic/\*** - generic topic feeds; named Medium authors may appear as `named-practitioner` entries, but topic-level feeds are rejected wholesale.
+- **"trending"-style aggregators** (e.g., product-hunt daily digests, "top 10 UI" roundups) - curatorial output indistinguishable from advertising.
 
 Rationale: the whitelist is restricted to sources that ship specs, guidelines, or named-practitioner curation (PROJECT.md, ROADMAP.md SC 8, CONTEXT.md D-08).
 

package/reference/bandit-integration.md

@@ -3,10 +3,10 @@ name: bandit-integration
 phase: 27.5
 version: 1.0.0
 type: meta-rules
-description: Bandit posterior + production-integration shim cheat sheet — signatures, reward function semantics, adaptive_mode gate, posterior path conventions.
+description: Bandit posterior + production-integration shim cheat sheet - signatures, reward function semantics, adaptive_mode gate, posterior path conventions.
 ---
 
-# Bandit Integration — Developer Cheat Sheet
+# Bandit Integration - Developer Cheat Sheet
 
 **Phase 27.5 (v1.27.5).** Reference for the bandit production-integration surface. Authoring or modifying a caller of the bandit posterior? Debugging a routing decision at the code level? Start here.
 
@@ -21,20 +21,20 @@ In-scope modules:
 
 ## The two-stage architecture
 
-Phase 23.5 ships the bandit primitives — Thompson-sampling pull, posterior update, computeReward, atomic persistence. Phase 27-07 added the `delegate?` arm dimension (5 peer-CLI arms + the local `none` arm). Both phases shipped library-only with no production callers.
+Phase 23.5 ships the bandit primitives - Thompson-sampling pull, posterior update, computeReward, atomic persistence. Phase 27-07 added the `delegate?` arm dimension (5 peer-CLI arms + the local `none` arm). Both phases shipped library-only with no production callers.
 
 Phase 27.5 ships the production-integration shim that wraps the primitives behind two purpose-built entry points and hides the `pull` vs `pullWithDelegate` choice. Callers pass a `delegate` argument and the shim routes internally.
 
-### Phase 23.5 + 27-07 surface — `scripts/lib/bandit-router.cjs`
+### Phase 23.5 + 27-07 surface - `scripts/lib/bandit-router.cjs`
 
 Exports: `pull`, `update`, `pullWithDelegate`, `updateWithDelegate`, `computeReward`, `loadPosterior`, `savePosterior`, `reset`, `decayArm`, `sampleBeta`, `priorFor`, `binForGlobCount`, `DEFAULT_DELEGATES`, `DELEGATE_NONE`, `TIER_PRIOR`, `PRIOR_STRENGTH`, `TOUCHES_BINS`, `DEFAULT_POSTERIOR_PATH`, `SCHEMA_VERSION`.
 
 The two-pair primitive split:
 
-- `pull({agent, bin, ...})` / `update({agent, bin, tier, reward, ...})` — operate on the `(agent, bin, tier)` arm slice. Equivalent to `delegate='none'`.
-- `pullWithDelegate({agent, bin, delegates, ...})` / `updateWithDelegate({agent, bin, tier, delegate, reward, ...})` — operate on the `(agent, bin, tier, delegate)` arm slice for any `delegate ∈ DEFAULT_DELEGATES`.
+- `pull({agent, bin, ...})` / `update({agent, bin, tier, reward, ...})` - operate on the `(agent, bin, tier)` arm slice. Equivalent to `delegate='none'`.
+- `pullWithDelegate({agent, bin, delegates, ...})` / `updateWithDelegate({agent, bin, tier, delegate, reward, ...})` - operate on the `(agent, bin, tier, delegate)` arm slice for any `delegate ∈ DEFAULT_DELEGATES`.
 
-### Phase 27.5 surface — `scripts/lib/bandit-router/integration.cjs`
+### Phase 27.5 surface - `scripts/lib/bandit-router/integration.cjs`
 
 Exports: `consultBandit`, `recordOutcome`, `DELEGATE_NONE`.
 
@@ -75,7 +75,7 @@ consultBandit({
 }
 ```
 
-`decision_log.source` is the audit trail — it tells observability tools which routing branch ran. Tests use it to assert the correct path was taken.
+`decision_log.source` is the audit trail - it tells observability tools which routing branch ran. Tests use it to assert the correct path was taken.
 
 ---
 
@@ -108,9 +108,9 @@ Phase 27.5 passes `wallTimeMs: 0` always (D-08 unchanged from Phase 23.5).
 
 Phase 23.5 ladder (D-07):
 
-- `static` — default. Bandit silent. `default-tier:` is authoritative. No reads, no writes.
-- `hedge` — measurement-only. Bandit silent on reads, but `recordOutcome` may still write to seed the posterior. Currently identical to `static` in Phase 27.5; reserved for Phase 28+ explicit "hedge mode".
-- `full` — bandit active. Reads pick via Thompson sampling; writes update posterior.
+- `static` - default. Bandit silent. `default-tier:` is authoritative. No reads, no writes.
+- `hedge` - measurement-only. Bandit silent on reads, but `recordOutcome` may still write to seed the posterior. Currently identical to `static` in Phase 27.5; reserved for Phase 28+ explicit "hedge mode".
+- `full` - bandit active. Reads pick via Thompson sampling; writes update posterior.
 
 The shim respects the gate transparently. Operators flip via `.design/budget.json#adaptive_mode`.
 
@@ -122,8 +122,8 @@ The shim respects the gate transparently. Operators flip via `.design/budget.jso
 
 Two-stage lexicographic (D-08, unchanged from Phase 23.5):
 
-- Stage 1 — correctness: if `solidify_pass !== true`, return `0`.
-- Stage 2 — cost: return `1 - lambda * normalize(cost_usd + epsilon * wall_time_ms)`.
+- Stage 1 - correctness: if `solidify_pass !== true`, return `0`.
+- Stage 2 - cost: return `1 - lambda * normalize(cost_usd + epsilon * wall_time_ms)`.
 
 Defaults: `lambda = 0.3`, `epsilon = 0.05`. `normalize` maps `[0, $5]` linearly to `[0, 1]`, clamped.
 
@@ -137,7 +137,7 @@ Canonical path: `.design/telemetry/posterior.json` (Phase 23.5 D-08, Phase 27.5
 
 Test injection: pass `baseDir` (anchors path under a different workspace root) or `posteriorPath` (overrides the file path directly). Both `consultBandit` and `recordOutcome` accept these options.
 
-Write discipline: atomic via `.tmp` + rename. Read failures yield an empty posterior; subsequent writes overwrite. Concurrent writers within the same process are not synchronized — gdd's session-runner is single-threaded.
+Write discipline: atomic via `.tmp` + rename. Read failures yield an empty posterior; subsequent writes overwrite. Concurrent writers within the same process are not synchronized - gdd's session-runner is single-threaded.
 
 ---
 
@@ -145,19 +145,19 @@ Write discipline: atomic via `.tmp` + rename. Read failures yield an empty poste
 
 Phase 27.5 wires these consumers:
 
-- **`hooks/budget-enforcer.ts`** (Plan 27.5-02) — per Agent spawn, after `resolved_models` is computed, before SDK call. Calls `consultBandit({agent, bin, delegate, agentFrontmatter, adaptiveMode})`. Overrides `resolved_models[agent]` with the bandit tier via `tier-resolver.cjs`. Emits `bandit.tier_selected` event for observability.
-- **`scripts/lib/session-runner/index.ts`** (Plan 27.5-03) — terminal-emit path. Calls `recordOutcome({agent, bin, delegate, tier, status, costUsd})` after every `emit('session.completed', ...)` site (4 sites: rate-limited, peer-success, turn-cap-zero, terminal retry-exit). Posterior write is best-effort; missing optional fields silent.
-- **`agents/design-reflector.md` Section 8** (Plan 27.5-04) — bandit-arbitrage analysis. `scripts/lib/bandit-arbitrage.cjs` reads `.design/telemetry/posterior.json` and surfaces stale-frontmatter proposals. Mirrors Phase 26-06's `cost-arbitrage.cjs` shape.
-- **`skills/peers/SKILL.md` Step 5 + `skills/bandit-status/SKILL.md`** (Plan 27.5-05) — read-only diagnostic surfaces. `/gdd:peers` posterior delta column populated; `/gdd:bandit-status` renders per-`(agent, bin, delegate, tier)` snapshots.
+- **`hooks/budget-enforcer.ts`** (Plan 27.5-02) - per Agent spawn, after `resolved_models` is computed, before SDK call. Calls `consultBandit({agent, bin, delegate, agentFrontmatter, adaptiveMode})`. Overrides `resolved_models[agent]` with the bandit tier via `tier-resolver.cjs`. Emits `bandit.tier_selected` event for observability.
+- **`scripts/lib/session-runner/index.ts`** (Plan 27.5-03) - terminal-emit path. Calls `recordOutcome({agent, bin, delegate, tier, status, costUsd})` after every `emit('session.completed', ...)` site (4 sites: rate-limited, peer-success, turn-cap-zero, terminal retry-exit). Posterior write is best-effort; missing optional fields silent.
+- **`agents/design-reflector.md` Section 8** (Plan 27.5-04) - bandit-arbitrage analysis. `scripts/lib/bandit-arbitrage.cjs` reads `.design/telemetry/posterior.json` and surfaces stale-frontmatter proposals. Mirrors Phase 26-06's `cost-arbitrage.cjs` shape.
+- **`skills/peers/SKILL.md` Step 5 + `skills/bandit-status/SKILL.md`** (Plan 27.5-05) - read-only diagnostic surfaces. `/gdd:peers` posterior delta column populated; `/gdd:bandit-status` renders per-`(agent, bin, delegate, tier)` snapshots.
 
 ---
 
 ## Cross-references
 
-- `docs/BANDIT-INTEGRATION.md` — operator guide (when bandit fires, how to disable, troubleshooting).
-- `reference/peer-protocols.md` — Phase 27 ACP/ASP cheat sheet (peer-CLI delegation transport).
-- `scripts/lib/bandit-router.cjs` — Phase 23.5 primitives surface.
-- `scripts/lib/bandit-router/integration.cjs` — Phase 27.5 production shim.
-- `scripts/lib/bandit-arbitrage.cjs` — Phase 27.5 reflector analyzer (Section 8 of `design-reflector.md`).
-- `hooks/budget-enforcer.ts` — bandit consultation site.
-- `scripts/lib/session-runner/index.ts` — `recordOutcome` site.
+- `docs/BANDIT-INTEGRATION.md` - operator guide (when bandit fires, how to disable, troubleshooting).
+- `reference/peer-protocols.md` - Phase 27 ACP/ASP cheat sheet (peer-CLI delegation transport).
+- `scripts/lib/bandit-router.cjs` - Phase 23.5 primitives surface.
+- `scripts/lib/bandit-router/integration.cjs` - Phase 27.5 production shim.
+- `scripts/lib/bandit-arbitrage.cjs` - Phase 27.5 reflector analyzer (Section 8 of `design-reflector.md`).
+- `hooks/budget-enforcer.ts` - bandit consultation site.
+- `scripts/lib/session-runner/index.ts` - `recordOutcome` site.

package/reference/brand-voice.md

@@ -2,13 +2,13 @@
 
 <!-- Source: nextlevelbuilder/ui-ux-pro-max-skill (MIT) — data/products.csv, data/ui-reasoning.csv (industry-context section) -->
 
-Brand voice is not a single setting — it is a combination of independent axes, an archetype frame, and a sensitivity to context. Agents reading this file should treat the voice axes and archetype library as orthogonal dimensions: pick a position on each axis independently, then select an archetype to layer personality on top. Neither choice is derived from the other.
+Brand voice is not a single setting - it is a combination of independent axes, an archetype frame, and a sensitivity to context. Agents reading this file should treat the voice axes and archetype library as orthogonal dimensions: pick a position on each axis independently, then select an archetype to layer personality on top. Neither choice is derived from the other.
 
 ---
 
 ## Voice Axes
 
-Each axis is a spectrum between two poles. Moving toward one pole is not superior to moving toward the other — the correct position depends entirely on the product's audience, vertical, and context of use. Most products do not land at the extreme of any axis; they occupy a deliberate range within it.
+Each axis is a spectrum between two poles. Moving toward one pole is not superior to moving toward the other - the correct position depends entirely on the product's audience, vertical, and context of use. Most products do not land at the extreme of any axis; they occupy a deliberate range within it.
 
 ### Axis 1: Formal ↔ Casual
 
@@ -30,7 +30,7 @@ Each axis is a spectrum between two poles. Moving toward one pole is not superio
 
 **Serious pole:** Tone is earnest and sober. Errors are acknowledged without irony. Humor is absent or very subdued. Stakes are treated as real. Example error message: "We were unable to process your payment. Please verify your card details and try again, or contact your bank."
 
-**Playful pole:** Tone uses wit, lightness, and occasionally emoji or metaphor to reduce tension and delight the user. Playfulness does not mean frivolous — it means the product enjoys its own existence. Example error message: "Something got tangled up on our end. Give it another go? 🙏"
+**Playful pole:** Tone uses wit, lightness, and occasionally emoji or metaphor to reduce tension and delight the user. Playfulness does not mean frivolous - it means the product enjoys its own existence. Example error message: "Something got tangled up on our end. Give it another go? 🙏"
 
 **When to move toward Serious:** Enterprise B2B, professional tools, medical platforms, legal services, and financial dashboards should maintain a serious register because users are performing consequential work and playful tone signals a mismatch in understanding stakes. An HR platform with whimsical error messages risks undermining managerial authority.
 
@@ -38,7 +38,7 @@ Each axis is a spectrum between two poles. Moving toward one pole is not superio
 
 **Copy examples:**
 - Serious: "This action cannot be undone. All selected records will be permanently deleted."
-- Playful: "Heads up — once you delete this, it's gone for good. Still want to?"
+- Playful: "Heads up - once you delete this, it's gone for good. Still want to?"
 
 ---
 
@@ -46,7 +46,7 @@ Each axis is a spectrum between two poles. Moving toward one pole is not superio
 
 **Expert pole:** Language assumes domain knowledge. Technical terms are used without definition. The product speaks as a peer to specialists. Precision is prioritized over accessibility. Example: "Configure your OAuth 2.0 PKCE flow with a 256-bit code verifier before initiating the authorization request."
 
-**Approachable pole:** Language explains concepts in plain English. Jargon is translated or avoided. The product speaks as a guide to non-specialists. Accessibility is prioritized over brevity. Example: "Connect your account securely — we use a modern login method that keeps your password private."
+**Approachable pole:** Language explains concepts in plain English. Jargon is translated or avoided. The product speaks as a guide to non-specialists. Accessibility is prioritized over brevity. Example: "Connect your account securely - we use a modern login method that keeps your password private."
 
 **When to move toward Expert:** Developer tools, ML/data platforms, DevOps dashboards, security products, and medical or legal professional tools are used by specialists who are frustrated by over-explanation. Unnecessary simplification reads as condescension and slows expert users down.
 
@@ -66,7 +66,7 @@ Each axis is a spectrum between two poles. Moving toward one pole is not superio
 
 **When to move toward Reverent:** Luxury brands, heritage fashion houses, fine dining, premium hospitality, and cultural institutions benefit from reverent language because it honors the symbolic weight users attach to these products and does not puncture the aspirational experience they are purchasing.
 
-**When to move toward Irreverent:** Challenger brands, startup disruptors, creative tools, youth-oriented products, and any brand explicitly positioning against an incumbent benefit from irreverent language because it embodies the brand's core argument — that the old way is worth questioning. An anti-establishment fintech that writes like a bank forfeits its entire premise.
+**When to move toward Irreverent:** Challenger brands, startup disruptors, creative tools, youth-oriented products, and any brand explicitly positioning against an incumbent benefit from irreverent language because it embodies the brand's core argument - that the old way is worth questioning. An anti-establishment fintech that writes like a bank forfeits its entire premise.
 
 **Copy examples:**
 - Reverent: "Each piece is hand-finished by our atelier in Lyon."
@@ -78,7 +78,7 @@ Each axis is a spectrum between two poles. Moving toward one pole is not superio
 
 **Authoritative pole:** The product speaks with confidence and direction. It tells users what to do. Instructions are commands, not suggestions. The relationship is expert-to-user. Example: "You must complete identity verification before withdrawing funds." / "Save your work before closing this window."
 
-**Collaborative pole:** The product speaks as a partner. It recommends and explains, framing choices as shared decisions. The relationship is peer-to-peer. Example: "We recommend verifying your identity now — it unlocks higher withdrawal limits." / "Just so you know — unsaved changes will be lost if you close."
+**Collaborative pole:** The product speaks as a partner. It recommends and explains, framing choices as shared decisions. The relationship is peer-to-peer. Example: "We recommend verifying your identity now - it unlocks higher withdrawal limits." / "Just so you know - unsaved changes will be lost if you close."
 
 **When to move toward Authoritative:** Compliance interfaces, safety-critical systems, legal workflows, and any context where users must follow a specific procedure without deviation benefit from authoritative language because ambiguity creates errors and liability. A safety checklist that says "You might want to confirm the valve is closed" is a design defect.
 
@@ -86,7 +86,7 @@ Each axis is a spectrum between two poles. Moving toward one pole is not superio
 
 **Copy examples:**
 - Authoritative: "Enter your password to confirm this irreversible action."
-- Collaborative: "One last check — confirm your password and we'll take it from there."
+- Collaborative: "One last check - confirm your password and we'll take it from there."
 
 ---
 
@@ -95,40 +95,40 @@ Each axis is a spectrum between two poles. Moving toward one pole is not superio
 Archetypes are personality frames, not voice axes. They describe the fundamental role the brand plays in its users' lives and the emotional contract it offers. Archetypes and voice axes are orthogonal: a Sage brand can be formal or casual, serious or playful. Select an archetype and then tune voice axes independently.
 
 ### 1. The Sage
-The Sage earns trust by sharing knowledge. It positions the product as the most informed source in the room — not arrogant, but genuinely expert. The Sage communicates in a way that makes users feel more capable after each interaction, not dependent. In UI, this means rich documentation, contextual education woven into onboarding, and copy that explains the "why" rather than just the "what." Design skews toward clarity, precision, and minimalism — nothing competes with the information itself.
+The Sage earns trust by sharing knowledge. It positions the product as the most informed source in the room - not arrogant, but genuinely expert. The Sage communicates in a way that makes users feel more capable after each interaction, not dependent. In UI, this means rich documentation, contextual education woven into onboarding, and copy that explains the "why" rather than just the "what." Design skews toward clarity, precision, and minimalism - nothing competes with the information itself.
 
 ### 2. The Hero
-The Hero is empowering and action-oriented. It frames the user as the agent of change and the product as the tool that makes the mission possible. CTAs are verbs: "Start building," "Launch your campaign," "Deploy now." The Hero archetype works best when users have a clear goal and the product gives them velocity toward it. Design is bold, directional, and high-contrast — it communicates momentum.
+The Hero is empowering and action-oriented. It frames the user as the agent of change and the product as the tool that makes the mission possible. CTAs are verbs: "Start building," "Launch your campaign," "Deploy now." The Hero archetype works best when users have a clear goal and the product gives them velocity toward it. Design is bold, directional, and high-contrast - it communicates momentum.
 
 ### 3. The Creator
-The Creator prioritizes imagination and aesthetic experience. The product itself is a canvas, and the copy celebrates what users will make rather than what the product can do. Language is evocative rather than functional. Onboarding feels like an invitation rather than a tutorial. Design is aesthetic-forward — typography, whitespace, and visual rhythm are treated as expressive elements, not just layout tools.
+The Creator prioritizes imagination and aesthetic experience. The product itself is a canvas, and the copy celebrates what users will make rather than what the product can do. Language is evocative rather than functional. Onboarding feels like an invitation rather than a tutorial. Design is aesthetic-forward - typography, whitespace, and visual rhythm are treated as expressive elements, not just layout tools.
 
 ### 4. The Caregiver
-The Caregiver is empathetic, supportive, and gentle under pressure. It anticipates user anxiety and responds with reassurance. Error messages do not blame; they comfort and guide. Onboarding is patient. The Caregiver archetype is essential for health apps, mental wellness platforms, parenting tools, and any product used during vulnerable moments. Design is warm, rounded, and low-stimulus — nothing startles or overwhelms.
+The Caregiver is empathetic, supportive, and gentle under pressure. It anticipates user anxiety and responds with reassurance. Error messages do not blame; they comfort and guide. Onboarding is patient. The Caregiver archetype is essential for health apps, mental wellness platforms, parenting tools, and any product used during vulnerable moments. Design is warm, rounded, and low-stimulus - nothing startles or overwhelms.
 
 ### 5. The Ruler
-The Ruler is premium, commanding, and authority-signaling. It does not explain itself — it presents. Copy is declarative and sparse. The Ruler archetype justifies premium pricing through an experience that communicates exclusivity and mastery. This archetype works for luxury goods, high-end B2B platforms, and any product where status is part of the value. Design is restrained, high-contrast, and architectural — every element signals control.
+The Ruler is premium, commanding, and authority-signaling. It does not explain itself - it presents. Copy is declarative and sparse. The Ruler archetype justifies premium pricing through an experience that communicates exclusivity and mastery. This archetype works for luxury goods, high-end B2B platforms, and any product where status is part of the value. Design is restrained, high-contrast, and architectural - every element signals control.
 
 ### 6. The Jester
-The Jester uses humor to disarm and delight. It understands that joy is a retention mechanism and that laughter creates loyalty. The Jester does not take itself seriously and invites users to share that lightness. This archetype works for consumer products in low-stakes categories, social tools, and brands that have earned enough trust to be self-deprecating. Design uses surprise, playful motion, and unexpected visual moments — but always purposefully, never randomly.
+The Jester uses humor to disarm and delight. It understands that joy is a retention mechanism and that laughter creates loyalty. The Jester does not take itself seriously and invites users to share that lightness. This archetype works for consumer products in low-stakes categories, social tools, and brands that have earned enough trust to be self-deprecating. Design uses surprise, playful motion, and unexpected visual moments - but always purposefully, never randomly.
 
 ### 7. The Innocent
-The Innocent is clean, optimistic, and simple. It communicates that the world is basically good and that this product exists to make it a little better. Copy is honest, unpretentious, and free of manipulation. The Innocent archetype is right for health food brands, sustainable products, children's tools, and any product positioning around purity or honesty. Design is bright, open, and generous with whitespace — nothing hidden, nothing complex.
+The Innocent is clean, optimistic, and simple. It communicates that the world is basically good and that this product exists to make it a little better. Copy is honest, unpretentious, and free of manipulation. The Innocent archetype is right for health food brands, sustainable products, children's tools, and any product positioning around purity or honesty. Design is bright, open, and generous with whitespace - nothing hidden, nothing complex.
 
 ### 8. The Explorer
 The Explorer is discovery-forward and adventurous. It communicates that the world is full of things worth finding and that this product is the best vehicle for that journey. Copy uses open-ended language: "See what's possible," "Go further," "Find your path." The Explorer archetype fits travel apps, outdoor brands, learning platforms, and curiosity-driven tools. Design uses movement, depth, and environmental imagery to evoke possibility.
 
 ### 9. The Rebel
-The Rebel challenges assumptions and frames the incumbent as the problem. It uses anti-establishment language deliberately, not carelessly. The Rebel is not angry — it is confident in its alternative. Copy names what it rejects: "Not your usual bank," "Skip the middleman," "Design without the gatekeepers." The Rebel archetype is right for challenger brands, disruptive startups, and any product that exists because the existing solution is broken. Design is unconventional — asymmetric, raw, or deliberately anti-polished to signal that the rules have changed.
+The Rebel challenges assumptions and frames the incumbent as the problem. It uses anti-establishment language deliberately, not carelessly. The Rebel is not angry - it is confident in its alternative. Copy names what it rejects: "Not your usual bank," "Skip the middleman," "Design without the gatekeepers." The Rebel archetype is right for challenger brands, disruptive startups, and any product that exists because the existing solution is broken. Design is unconventional - asymmetric, raw, or deliberately anti-polished to signal that the rules have changed.
 
 ### 10. The Lover
-The Lover creates intimacy and sensory connection. Copy is warm, personal, and physically evocative. The Lover archetype is less about romance than about deep emotional resonance — the product feels like it was made for you specifically. This archetype fits beauty brands, food and beverage, hospitality, and any product where sensory experience is central. Design is rich, textural, and emotionally warm — photography over illustration, warmth over coolness.
+The Lover creates intimacy and sensory connection. Copy is warm, personal, and physically evocative. The Lover archetype is less about romance than about deep emotional resonance - the product feels like it was made for you specifically. This archetype fits beauty brands, food and beverage, hospitality, and any product where sensory experience is central. Design is rich, textural, and emotionally warm - photography over illustration, warmth over coolness.
 
 ### 11. The Everyman
-The Everyman is relatable, unpretentious, and radically inclusive. It signals that this product is for everyone, not for a tribe or an aspirational identity. Copy avoids jargon, insider language, and exclusivity markers. The Everyman archetype is right for utility apps, mass-market consumer tools, and any product that succeeds by broad adoption rather than niche loyalty. Design is familiar and accessible — conventional enough to feel immediately understandable to any user.
+The Everyman is relatable, unpretentious, and radically inclusive. It signals that this product is for everyone, not for a tribe or an aspirational identity. Copy avoids jargon, insider language, and exclusivity markers. The Everyman archetype is right for utility apps, mass-market consumer tools, and any product that succeeds by broad adoption rather than niche loyalty. Design is familiar and accessible - conventional enough to feel immediately understandable to any user.
 
 ### 12. The Magician
-The Magician is transformation-focused. It frames the product as the mechanism by which users go from a lesser to a greater state. Copy uses before/after framing: "What used to take days takes minutes," "You used to guess. Now you know." The Magician archetype fits productivity tools, AI platforms, and any product whose core promise is that the user will be meaningfully different after using it. Design uses contrast — before states feel constrained, after states feel open and capable.
+The Magician is transformation-focused. It frames the product as the mechanism by which users go from a lesser to a greater state. Copy uses before/after framing: "What used to take days takes minutes," "You used to guess. Now you know." The Magician archetype fits productivity tools, AI platforms, and any product whose core promise is that the user will be meaningfully different after using it. Design uses contrast - before states feel constrained, after states feel open and capable.
 
 ---
 
@@ -152,18 +152,18 @@ Beyond the 12 canonical archetypes, products can adopt a design-register variant
 
 ## Tone-by-Context Table
 
-Tone is not fixed — even a consistent brand voice shifts register depending on the situation the user is in. A Jester brand should not make jokes in an error message that signals data loss. This table maps UI contexts to appropriate tone adjustments.
+Tone is not fixed - even a consistent brand voice shifts register depending on the situation the user is in. A Jester brand should not make jokes in an error message that signals data loss. This table maps UI contexts to appropriate tone adjustments.
 
 | Context | Recommended Tone | Example Copy |
 |---------|-----------------|--------------|
-| Error message | Calm, clear, helpful — never humorous for data loss or high-stakes failure | "We couldn't save your changes. Check your connection and try again." |
-| Empty state | Warm, forward-looking, actionable — explains why empty and what to do | "Nothing here yet. Add your first project to get started." |
-| Success / celebration | Positive, proportionate to stakes — brief and genuine, not excessive | "All done! Your report is ready." / "🎉 You're all set!" (casual products only) |
-| Onboarding | Welcoming, encouraging, brief — does not front-load complexity | "Let's set up your workspace. It only takes a minute." |
-| Loading state | Reassuring, informative — signals progress without being annoying | "Getting your data…" / "Almost there." |
-| Destructive action confirmation | Serious, precise, no hedging — names what will be destroyed | "Delete project 'Alpha'? This cannot be undone." |
-| Pricing page | Honest, benefit-led, no dark patterns — copy earns the price | "Everything in Pro, plus unlimited seats and priority support." |
-| Marketing headline | Archetype-forward, emotionally resonant — captures brand promise | Varies by archetype (Hero: "Ship faster." / Creator: "Make something beautiful.") |
+| Error message | Calm, clear, helpful - never humorous for data loss or high-stakes failure | "We couldn't save your changes. Check your connection and try again." |
+| Empty state | Warm, forward-looking, actionable - explains why empty and what to do | "Nothing here yet. Add your first project to get started." |
+| Success / celebration | Positive, proportionate to stakes - brief and genuine, not excessive | "All done! Your report is ready." / "🎉 You're all set!" (casual products only) |
+| Onboarding | Welcoming, encouraging, brief - does not front-load complexity | "Let's set up your workspace. It only takes a minute." |
+| Loading state | Reassuring, informative - signals progress without being annoying | "Getting your data…" / "Almost there." |
+| Destructive action confirmation | Serious, precise, no hedging - names what will be destroyed | "Delete project 'Alpha'? This cannot be undone." |
+| Pricing page | Honest, benefit-led, no dark patterns - copy earns the price | "Everything in Pro, plus unlimited seats and priority support." |
+| Marketing headline | Archetype-forward, emotionally resonant - captures brand promise | Varies by archetype (Hero: "Ship faster." / Creator: "Make something beautiful.") |
 
 ---
 
@@ -171,29 +171,29 @@ Tone is not fixed — even a consistent brand voice shifts register depending on
 
 <!-- Source: nextlevelbuilder/ui-ux-pro-max-skill (MIT) — data/products.csv, data/ui-reasoning.csv -->
 
-**Important:** Voice axis positions and industry context are orthogonal dimensions. Industry context provides defaults and constraints; voice axis positions are still chosen deliberately within those constraints. A FinTech product can be formal but approachable, or formal and expert — industry context does not collapse those choices, it narrows the range.
+**Important:** Voice axis positions and industry context are orthogonal dimensions. Industry context provides defaults and constraints; voice axis positions are still chosen deliberately within those constraints. A FinTech product can be formal but approachable, or formal and expert - industry context does not collapse those choices, it narrows the range.
 
 ---
 
 | Vertical | Voice Axis Defaults | Color Mood | Typography Mood | Key Effects | Anti-Patterns |
 |----------|-------------------|------------|-----------------|-------------|---------------|
-| **FinTech / Banking** | Formal → Serious → Expert → Authoritative; trust must be earned through consistency | Deep navy, forest green, cool greys — signals stability and security | Clean sans-serif (Inter, DM Sans), generous line-height for readability at numeric density | Microanimations on transaction confirmation; subtle loading states; no celebration for transfers | Casual tone on high-stakes actions; bright consumer palettes; playful error messages; flashy transitions on money movement |
-| **HealthTech / Medical** | Formal → Serious → Approachable → Collaborative; clarity reduces anxiety | Soft teal, warm white, calm blues — avoids red except for genuine danger signals | Clean, large, high-contrast; body text ≥16px mandatory for compliance and accessibility | Gentle loading indicators; animated check states for completed steps; no jarring motion | Dense data without explanation; dark mode with pure black; small body text; red used decoratively |
+| **FinTech / Banking** | Formal → Serious → Expert → Authoritative; trust must be earned through consistency | Deep navy, forest green, cool greys - signals stability and security | Clean sans-serif (Inter, DM Sans), generous line-height for readability at numeric density | Microanimations on transaction confirmation; subtle loading states; no celebration for transfers | Casual tone on high-stakes actions; bright consumer palettes; playful error messages; flashy transitions on money movement |
+| **HealthTech / Medical** | Formal → Serious → Approachable → Collaborative; clarity reduces anxiety | Soft teal, warm white, calm blues - avoids red except for genuine danger signals | Clean, large, high-contrast; body text ≥16px mandatory for compliance and accessibility | Gentle loading indicators; animated check states for completed steps; no jarring motion | Dense data without explanation; dark mode with pure black; small body text; red used decoratively |
 | **SaaS / B2B** | Formal–Casual range → Serious → Expert → Authoritative–Collaborative range | Neutral greys, controlled accent (brand blue/green), white space dominant | Clean sans-serif, systematic type scale; headings earn visual weight | Skeleton loading for data tables; progressive disclosure for settings; tooltips for technical fields | Over-explaining basics to expert users; inconsistent terminology across modules; AI-slop purple palette |
 | **E-commerce / DTC** | Casual → Playful–Serious range → Approachable → Collaborative | Brand-driven palette; high saturation for CTAs; warm neutrals for product context | Expressive display for headlines; clean body for product descriptions | Product zoom hover states; cart animation on add; wishlist micro-interaction | Fake urgency copy; cluttered hierarchy; hidden total cost until checkout; tiny CTA on mobile |
 | **Gaming / Entertainment** | Casual → Playful → Approachable–Expert range → Irreverent | High saturation, dark mode dominant, neon accent on dark surface | Display/gaming typefaces for headers; clean body for UI; weight contrast is high | Motion-heavy transitions; achievement celebrations; ambient background animation | Accessibility blindspots in dark mode; pure black backgrounds (vibration); low contrast on energetic backgrounds |
 | **Social / Community** | Casual → Playful → Approachable → Collaborative | Warm neutrals, brand accent, avatar-forward UI with minimal chrome | Friendly rounded sans-serif; generous spacing; conversational scale | Reaction microanimations; real-time presence indicators; celebratory confetti for milestones | Cold enterprise-grade color in social context; heavy typography hierarchy that buries user content |
 | **Dev Tools** | Casual–Formal range → Serious → Expert → Authoritative | Dark mode default; syntax-highlight palette; cool greys; code-emphasis contrast | Monospace for code; sans-serif for prose; no decorative type | Fast, no-flash loading states; inline error syntax highlighting; keyboard shortcut visibility | Explaining basics to experts; hiding power features; light-mode-only; inconsistent CLI↔UI vocabulary |
-| **EdTech** | Casual → Playful–Serious range → Approachable → Collaborative | Warm, bright, optimistic — not childish; academic versions use cooler tone | Friendly rounded sans; large body text; generous spacing for reading context | Progress animations; streak celebration; gentle nudges for return | Overwhelming choice on first launch; punitive error framing; tests without explanation of why wrong |
-| **Legal / Compliance** | Formal → Serious → Expert → Authoritative | Navy, charcoal, neutral greys — no decorative color | Readable serif or clean sans; no display type for primary content | None beyond loading states; no celebratory states — outcomes have real weight | Casual tone on contract actions; hiding consequences; playful UI that signals legal work is trivial |
+| **EdTech** | Casual → Playful–Serious range → Approachable → Collaborative | Warm, bright, optimistic - not childish; academic versions use cooler tone | Friendly rounded sans; large body text; generous spacing for reading context | Progress animations; streak celebration; gentle nudges for return | Overwhelming choice on first launch; punitive error framing; tests without explanation of why wrong |
+| **Legal / Compliance** | Formal → Serious → Expert → Authoritative | Navy, charcoal, neutral greys - no decorative color | Readable serif or clean sans; no display type for primary content | None beyond loading states; no celebratory states - outcomes have real weight | Casual tone on contract actions; hiding consequences; playful UI that signals legal work is trivial |
 | **HR / People Ops** | Formal–Casual range → Serious → Approachable → Collaborative | Warm professional: muted teal, earth tones, warm greys | Clean sans-serif; expressive enough to feel human, not cold | Subtle check animations for onboarding; gentle feedback on form completion | Clinical coldness in employee-facing UI; hiding personal data implications; confusing benefit summaries |
 | **Real Estate** | Formal → Serious → Approachable → Authoritative | Warm greys, earth tones, occasional brand accent; photography-dominant | Clean serif or premium sans; photography does the expressive work | Map interaction states; mortgage calculator animations; image gallery transitions | Overwhelming data without hierarchy; hiding total cost; small map interaction targets on mobile |
 | **Travel / Hospitality** | Casual → Playful–Serious range → Approachable → Collaborative | Destination-driven: warm ambers, ocean blues, lush greens | Expressive display for destination content; clean sans for booking flows | Immersive imagery transitions; booking confirmation celebration; ambient destination video | Hiding fees until final step; tiny date pickers; inconsistent voice between inspiration and transactional flows |
 | **Food / Delivery** | Casual → Playful → Approachable → Collaborative | Warm appetizing tones: terracotta, golden yellow, deep greens | Rounded, friendly sans-serif; photography-heavy | Order status animation; delivery tracking real-time; add-to-cart micro-interaction | Cold clinical tone; hiding delivery costs; overwhelming menu density; slow loading states for item images |
 | **Fitness / Wellness** | Casual → Serious–Playful range → Approachable → Collaborative | High energy (fitness): deep navy + neon; Wellness: warm cream, sage, earth | Strong weight contrast for motivational moments; clean body for routine content | Workout completion celebration; streak animation; activity ring fill | Shaming language for missed goals; pure black dark mode; excessive notifications; gamification without consent |
-| **Non-profit / NGO** | Casual–Formal range → Serious → Approachable → Collaborative | Mission-driven: warm humanist tones, photography-led, restrained accent | Readable, accessible, warm — never cold or corporate | Impact counter animations; donation confirmation warmth; progress-toward-goal bars | Guilt-manipulation copy; inaccessible donation flows; slow load on donation pages; hiding overhead costs |
-| **Government / Civic** | Formal → Serious → Approachable → Authoritative | Institutional: navy, red, white variants — national palette conventions | Highly readable sans-serif; no display type; large body text mandatory | Progress bars for multi-step processes; no celebration for government services | Jargon without explanation; inaccessible forms; mobile-hostile layouts; hiding deadlines |
-| **Luxury / Fashion** | Formal → Serious → Expert → Reverent | Black, white, gold, nude — restraint signals luxury | Editorial serif or geometric sans; generous whitespace; typography is the aesthetic | Elegant fade transitions; product reveal on scroll; no click-bait motion | Playful copy that undercuts premium positioning; cluttered layout; urgent sale language; AI-slop palette |
+| **Non-profit / NGO** | Casual–Formal range → Serious → Approachable → Collaborative | Mission-driven: warm humanist tones, photography-led, restrained accent | Readable, accessible, warm - never cold or corporate | Impact counter animations; donation confirmation warmth; progress-toward-goal bars | Guilt-manipulation copy; inaccessible donation flows; slow load on donation pages; hiding overhead costs |
+| **Government / Civic** | Formal → Serious → Approachable → Authoritative | Institutional: navy, red, white variants - national palette conventions | Highly readable sans-serif; no display type; large body text mandatory | Progress bars for multi-step processes; no celebration for government services | Jargon without explanation; inaccessible forms; mobile-hostile layouts; hiding deadlines |
+| **Luxury / Fashion** | Formal → Serious → Expert → Reverent | Black, white, gold, nude - restraint signals luxury | Editorial serif or geometric sans; generous whitespace; typography is the aesthetic | Elegant fade transitions; product reveal on scroll; no click-bait motion | Playful copy that undercuts premium positioning; cluttered layout; urgent sale language; AI-slop palette |
 | **Media / Publishing** | Casual–Formal range → Serious → Approachable–Expert range → Authoritative | Publication-specific; reading UX emphasizes contrast and typography | Reading-optimized: long-form line length (60–75ch), generous line-height (1.7+) | Scroll-progress indicators; reading time estimates; article-end engagement | Distraction ads interrupting reading flow; tiny body text; low contrast for long-form content |
 | **Analytics / BI** | Formal → Serious → Expert → Authoritative | Data-focused: high contrast, neutral chrome, vivid but accessible chart palette | Dense but readable sans-serif; monospace for data values; strong heading hierarchy | Interactive chart hover states; filter animation; export confirmation | Color-blind-unsafe chart palettes; pure decoration in data visualizations; hiding data provenance |
 | **AI / ML Platform** | Casual–Formal range → Serious → Expert → Authoritative–Collaborative range | Dark mode default with vibrant accent; cool-to-neutral chrome | Clean monospace for code and prompts; sans-serif for prose; strong weight contrast | Streaming text animation; generation loading state; token cost micro-display | Anthropomorphizing in ways that mislead; hiding capability limits; magical framing that hides user responsibility |

package/reference/capability-gap-stage-gate.md

@@ -3,7 +3,7 @@
 > Phase 29 reference doc. Specifies the deterministic gate that decides when
 > the reflector has gathered enough `capability_gap` signal to surface a
 > one-time opt-in prompt for Stage-1 (incubator authoring of new agents /
-> skills). **No code path in this repository auto-flips the stage** —
+> skills). **No code path in this repository auto-flips the stage** -
 > D-01 is the discipline.
 
 ---
@@ -23,7 +23,7 @@ date or a release. The reflector aggregates events into per-cycle
 clusters (`scripts/lib/reflector-capability-gap-aggregator.cjs`) and
 evaluates a deterministic stability function against the project's
 cycle history. When the gate is crossed, `/gdd:apply-reflections`
-emits a **one-time user-facing prompt** in the cycle markdown — never
+emits a **one-time user-facing prompt** in the cycle markdown - never
 an auto-stage-flip. The user opting in is a separate explicit action,
 out of scope for this gate spec.
 
@@ -72,7 +72,7 @@ A cluster `c` is **stable** iff both conditions hold:
 
 1. **Consecutive presence.** `c` appears in `≥ M` consecutive cycles
    somewhere within the observed history. (The most recent unbroken
-   run is what matters — if a cluster missed a cycle, the run resets
+   run is what matters - if a cluster missed a cycle, the run resets
    and only the longest streak counts.)
 2. **Narrow posterior.** The closed-form posterior standard deviation
    of the Beta distribution satisfies:
@@ -129,7 +129,7 @@ Inputs:
 
 The evaluation is **deterministic** (no randomness), **idempotent**
 (no side-effects in the evaluator), and **read-only** with respect to
-`.design/config.json` — that file is only updated by the user's
+`.design/config.json` - that file is only updated by the user's
 explicit opt-in action, never by the reflector.
 
 ---
@@ -140,11 +140,11 @@ When the gate crosses for the first time, `/gdd:apply-reflections`
 appends the following verbatim block to the cycle markdown:
 
 > ```markdown
-> ## Stage-0 → Stage-1 gate crossed — opt-in required
+> ## Stage-0 → Stage-1 gate crossed - opt-in required
 >
 > Capability-gap detection has accumulated enough signal across recent
 > cycles to consider enabling Stage-1 (incubator authoring of new
-> agents / skills). The gate is informational only — **nothing has
+> agents / skills). The gate is informational only - **nothing has
 > changed in the runtime**, and Stage-1 will NOT auto-enable. Per
 > Phase 29 CONTEXT.md decision D-01, the user opts in explicitly.
 >
@@ -174,8 +174,8 @@ appends the following verbatim block to the cycle markdown:
 > `capability_gap_gate.user_prompted_at` from `.design/config.json`.
 > ```
 
-The wiring side of this — actually writing the `user_prompted_at`
-timestamp and routing the opt-in confirmation — is deferred to
+The wiring side of this - actually writing the `user_prompted_at`
+timestamp and routing the opt-in confirmation - is deferred to
 **Plan 29-05** (`/gdd:apply-reflections` extension). This document
 specifies the prompt text and behavior; 29-05 implements the
 state-machine that consumes it.
@@ -204,7 +204,7 @@ Two timestamps in `.design/config.json` track the project's gate state:
 - **`opted_in_at`** is set when the user explicitly opts into Stage-1.
   Stage-1 incubator authoring (Plans 29-04+) becomes active once this
   timestamp is present. **Stage 1 is NEVER enabled by the reflector
-  setting this timestamp itself** — D-01 lock.
+  setting this timestamp itself** - D-01 lock.
 
 Once `opted_in_at` is set, the gate stops emitting prompts entirely
 (it's a one-shot mechanism, not a continuous nudge).
@@ -222,7 +222,7 @@ Operators can manually reset the gate by editing `.design/config.json`:
 | Tighten / loosen thresholds | Edit `K` / `M` / `stddev_threshold` directly. Out-of-range values silently fall back to defaults (§ 2). |
 
 Reset is **explicit** and **idempotent**. The reflector never writes
-to these fields on its own — the only writers are (a) the
+to these fields on its own - the only writers are (a) the
 `/gdd:apply-reflections` opt-in path (Plan 29-05) and (b) the human
 operator editing the file by hand.
 
@@ -233,32 +233,32 @@ operator editing the file by hand.
 Executable examples that exercise the gate live in
 `tests/reflector-capability-gap-aggregation.test.cjs`:
 
-- **T3** — 30 cycles × 3 always-present clusters → gate crosses with
+- **T3** - 30 cycles × 3 always-present clusters → gate crosses with
   default K=3 / M=10 / stddev_threshold=0.05.
-- **T3b** — 10 cycles × 1 always-present cluster → gate does NOT
+- **T3b** - 10 cycles × 1 always-present cluster → gate does NOT
   cross (posterior stddev ≈ 0.077 with α=11, β=1 is above the 0.05
   threshold; M=10 is the lower bound on observations, not a
   sufficient condition for stability).
-- **T4** — 30 cycles, 2 always-present clusters + 1 "noisy" cluster
+- **T4** - 30 cycles, 2 always-present clusters + 1 "noisy" cluster
   present in only the first 4 cycles → gate does NOT cross
   (`stable_cluster_ids.length === 2 < K=3`).
-- **T4b** — 5 cycles total → gate does NOT cross (`cycles_observed < M`).
-- **T7** — Confirms `K` and `stddev_threshold` overrides flow through
+- **T4b** - 5 cycles total → gate does NOT cross (`cycles_observed < M`).
+- **T7** - Confirms `K` and `stddev_threshold` overrides flow through
   `normalizeConfig` and reach the evaluation.
 
 These fixtures are synthetic and inline (D-11). The gate evaluator
-never reads `.design/gep/events.jsonl` directly in CI — fixtures
+never reads `.design/gep/events.jsonl` directly in CI - fixtures
 seed the cluster lists by hand.
 
 ---
 
 ## Decisions referenced
 
-- **D-01** — Two-stage approach: Stage 0 telemetry-only ships first;
+- **D-01** - Two-stage approach: Stage 0 telemetry-only ships first;
   Stage 1 authoring gated on data; user opts in per a one-time prompt;
   no auto-flip.
-- **D-03** — Default `K=3` / `M=10` / `stddev_threshold=0.05`,
+- **D-03** - Default `K=3` / `M=10` / `stddev_threshold=0.05`,
   overridable via `.design/config.json`.
-- **D-11** — Tests use synthetic fixtures (no live event chain reads).
-- **Phase 23.5** — Posterior `stddev(Beta(α, β))` closed form and
+- **D-11** - Tests use synthetic fixtures (no live event chain reads).
+- **Phase 23.5** - Posterior `stddev(Beta(α, β))` closed form and
   Laplace prior convention reused here.