@hegemonart/get-design-done 1.41.5 → 1.43.0

package/reference/architecture-vocabulary.md

@@ -7,11 +7,11 @@ tags: [architecture, ousterhout, module, interface, depth, seam, adapter, levera
 last_updated: 2026-05-18
 ---
 
-Source: mattpocock/skills (MIT) via Ousterhout, *A Philosophy of Software Design* — adapted with permission. See `../NOTICE` for the full attribution block.
+Source: mattpocock/skills (MIT) via Ousterhout, *A Philosophy of Software Design* - adapted with permission. See `../NOTICE` for the full attribution block.
 
 # Architecture Vocabulary
 
-A shared vocabulary for architectural reasoning across GDD skills. Same words mean the same things across `zoom-out`, `debug`, `analyze-dependencies`, `map`, `quality-gate`, and the planning skills — so agents and humans do not re-litigate "what did you mean by *module*" every conversation. Drawn from John Ousterhout's *A Philosophy of Software Design* via mattpocock's `improve-codebase-architecture/LANGUAGE.md`. GDD design-engineering analogs are surfaced where applicable — a UI component is a module, a design-token API is an interface, a token theme is an adapter.
+A shared vocabulary for architectural reasoning across GDD skills. Same words mean the same things across `zoom-out`, `debug`, `analyze-dependencies`, `map`, `quality-gate`, and the planning skills - so agents and humans do not re-litigate "what did you mean by *module*" every conversation. Drawn from John Ousterhout's *A Philosophy of Software Design* via mattpocock's `improve-codebase-architecture/LANGUAGE.md`. GDD design-engineering analogs are surfaced where applicable - a UI component is a module, a design-token API is an interface, a token theme is an adapter.
 
 This file is the canonical reference; skills cite it instead of re-defining terms inline.
 
@@ -19,13 +19,13 @@ This file is the canonical reference; skills cite it instead of re-defining term
 
 A unit of code that hides implementation behind an interface. The module's value to its caller is everything inside that the caller no longer has to think about.
 
-- A React component is a module — props are the interface, internal state and effects are the implementation.
-- A skill is a module — frontmatter + workflow are the interface, the SKILL.md body is the implementation.
+- A React component is a module - props are the interface, internal state and effects are the implementation.
+- A skill is a module - frontmatter + workflow are the interface, the SKILL.md body is the implementation.
 - See `./design-system-guidance.md` for the design-system-level analog: a component is a module; the token contract is its interface.
 
 ## Interface
 
-What a module exposes to callers — function signatures, props, return types, error contracts, side-effect promises. The interface is what callers depend on; everything else they must NOT depend on. Small, stable interfaces are the goal.
+What a module exposes to callers - function signatures, props, return types, error contracts, side-effect promises. The interface is what callers depend on; everything else they must NOT depend on. Small, stable interfaces are the goal.
 
 - `function fetchUser(id: string): Promise<User>` is the interface. How `fetchUser` calls the database is implementation.
 - A React component's `props` plus its rendered DOM contract is the interface; useState, useEffect, internal helpers are not.
@@ -33,27 +33,27 @@ What a module exposes to callers — function signatures, props, return types, e
 
 ## Implementation
 
-What the module hides — the code that does the work. Callers must not depend on it. Implementation is free to change as long as the interface holds.
+What the module hides - the code that does the work. Callers must not depend on it. Implementation is free to change as long as the interface holds.
 
 - Switching `fetchUser` from REST to GraphQL without changing the call site = implementation change without interface change. Healthy.
 - Renaming a private helper inside a React component does not break callers. Healthy.
-- Exposing a class's "private" field that callers started reading turns implementation into de-facto interface. Unhealthy — fix by either formalizing the field as interface or stopping the leak.
+- Exposing a class's "private" field that callers started reading turns implementation into de-facto interface. Unhealthy - fix by either formalizing the field as interface or stopping the leak.
 
 ## Depth
 
-A module is **deep** when the interface is simple and the implementation hides genuine complexity. A module is **shallow** when the interface is as complex as the implementation — the wrapper adds no leverage and just shuffles the caller's mental load sideways.
+A module is **deep** when the interface is simple and the implementation hides genuine complexity. A module is **shallow** when the interface is as complex as the implementation - the wrapper adds no use and just shuffles the caller's mental load sideways.
 
-- `Array.sort()` is deep — one method name hides ~50 lines of comparison-sort logic plus stable-ordering guarantees.
-- `class Wrapper { getX() { return this.x; } }` is shallow — the wrapper adds no leverage; the caller has to know about `Wrapper` AND `x`.
+- `Array.sort()` is deep - one method name hides ~50 lines of comparison-sort logic plus stable-ordering guarantees.
+- `class Wrapper { getX() { return this.x; } }` is shallow - the wrapper adds no use; the caller has to know about `Wrapper` AND `x`.
 - Asymmetry in the caller's favor is the goal. Shallow modules cost the caller mental complexity without paying it back.
-- See `./component-authoring.md` "Minimal API" — a 1-prop `<Image src=... />` that handles preload, lazy load, srcset, blur placeholder, error fallback is the depth principle applied to component design.
+- See `./component-authoring.md` "Minimal API" - a 1-prop `<Image src=... />` that handles preload, lazy load, srcset, blur placeholder, error fallback is the depth principle applied to component design.
 
 ## Seam
 
-The boundary where two abstractions meet — where one module's interface is consumed by another. Seams are where you can replace one side without touching the other.
+The boundary where two abstractions meet - where one module's interface is consumed by another. Seams are where you can replace one side without touching the other.
 
-- **Hypothetical seam.** Only one implementation exists behind the boundary. Nothing yet validates the abstraction is meaningful — the seam is a possibility statement.
-- **Real seam.** Two or more implementations exist; the boundary has been proved load-bearing by actual substitution. The seam is evidence.
+- **Hypothetical seam.** Only one implementation exists behind the boundary. Nothing yet validates the abstraction is meaningful - the seam is a possibility statement.
+- **Real seam.** Two or more implementations exist; the boundary has been proved essential by actual substitution. The seam is evidence.
 - "One adapter = hypothetical seam; two adapters = real seam." See `## Principles` below.
 - A `fetchUser` function backed only by Postgres is hypothetical; once a test double + a Postgres impl coexist, the seam is real.
 
@@ -61,42 +61,42 @@ The boundary where two abstractions meet — where one module's interface is con
 
 A module that transforms one interface into another to enable substitution behind a seam. Adapters create seams; the count of distinct adapters approximates the seam's realism.
 
-- A Redux-to-Zustand adapter exposes Redux's `store.dispatch` while wrapping a Zustand store underneath — callers keep their Redux API; the implementation moved.
+- A Redux-to-Zustand adapter exposes Redux's `store.dispatch` while wrapping a Zustand store underneath - callers keep their Redux API; the implementation moved.
 - A design-token theme is an adapter: it transforms one token contract (`--color-bg`) into specific concrete values (`oklch(98% 0 0)` in light theme, `oklch(15% 0 0)` in dark).
-- An `acp-client` plus an `asp-client` are two adapters over the same "peer-CLI" seam — the second one proves the seam is meaningful (Phase 27).
+- An `acp-client` plus an `asp-client` are two adapters over the same "peer-CLI" seam - the second one proves the seam is meaningful (Phase 27).
 
-## Leverage
+## Use
 
-The ratio of work-the-system-does to interface-the-caller-touches. High leverage = high depth = the caller buys a lot of work for a little API. Architectural choices that maximize leverage reduce future cost across all callers.
+The ratio of work-the-system-does to interface-the-caller-touches. High use = high depth = the caller buys a lot of work for a little API. Architectural choices that maximize use reduce future cost across all callers.
 
-- `<Image />` with a `src` prop that handles preload, lazy load, srcset generation, blur placeholder, error fallback — high leverage from a 1-prop API. Every caller benefits.
-- A 5-prop `<Button variant size leftIcon rightIcon onClick />` that only renders a styled `<button>` — low leverage; the caller is still doing most of the configuration work.
-- Leverage compounds. A high-leverage primitive used by 20 components multiplies the original investment 20×.
+- `<Image />` with a `src` prop that handles preload, lazy load, srcset generation, blur placeholder, error fallback - high use from a 1-prop API. Every caller benefits.
+- A 5-prop `<Button variant size leftIcon rightIcon onClick />` that only renders a styled `<button>` - low use; the caller is still doing most of the configuration work.
+- Use compounds. A high-impact primitive used by 20 components multiplies the original investment 20×.
 
 ## Locality
 
-Related changes happen in the same place; unrelated changes do not ripple. Spatial cohesion of the change footprint. Locality is what makes a codebase "easy to modify" — you can find the thing and change just the thing.
+Related changes happen in the same place; unrelated changes do not ripple. Spatial cohesion of the change footprint. Locality is what makes a codebase "easy to modify" - you can find the thing and change just the thing.
 
 - Healthy: adding a new chart type touches `chart-types/<new-type>.ts` only.
 - Broken: adding a new chart type touches `chart-types.ts` AND `chart-renderer.ts` AND `chart-config.ts` AND `chart-styles.css` AND `chart-icons.svg`. The system is forcing the author to remember 5 files for a 1-concept change.
-- Test it with the **deletion test** (see `## Principles`) — if removing the feature requires touching the same N files, locality is asymmetric and the abstraction is leaking.
+- Test it with the **deletion test** (see `## Principles`) - if removing the feature requires touching the same N files, locality is asymmetric and the abstraction is leaking.
 
 ## Principles
 
-Three load-bearing rules that operationalize the vocabulary above. Each one is a question you can ask during review.
+Three essential rules that operationalize the vocabulary above. Each one is a question you can ask during review.
 
-- **Deletion test.** Can you delete the implementation and the interface still tells callers what they could do? If yes, the interface is well-defined and the module is properly encapsulated. If no, the interface is leaking implementation — callers are reaching past the abstraction. Apply this when reviewing a new module: imagine deleting the body; can a reader still describe the surface from the signature alone?
-- **Interface is the test surface.** Tests target the interface; implementation churn does not churn tests. If a refactor that preserves behavior breaks tests, the test was implementation-coupled — fix the test, not the refactor. This is also the diagnostic for whether you have a real interface at all: if you cannot test through it, the interface is too narrow or the implementation is leaking.
-- **One adapter = hypothetical seam; two adapters = real seam.** One substitution is a possibility statement; two substitutions are evidence the boundary is meaningful. Do not over-design seams without ≥2 implementations — the second one teaches you what the seam actually needs. This is YAGNI for boundaries: ship the first impl, extract the seam when the second one arrives.
+- **Deletion test.** Can you delete the implementation and the interface still tells callers what they could do? If yes, the interface is well-defined and the module is properly encapsulated. If no, the interface is leaking implementation - callers are reaching past the abstraction. Apply this when reviewing a new module: imagine deleting the body; can a reader still describe the surface from the signature alone?
+- **Interface is the test surface.** Tests target the interface; implementation churn does not churn tests. If a refactor that preserves behavior breaks tests, the test was implementation-coupled - fix the test, not the refactor. This is also the diagnostic for whether you have a real interface at all: if you cannot test through it, the interface is too narrow or the implementation is leaking.
+- **One adapter = hypothetical seam; two adapters = real seam.** One substitution is a possibility statement; two substitutions are evidence the boundary is meaningful. Do not over-design seams without ≥2 implementations - the second one teaches you what the seam actually needs. This is YAGNI for boundaries: ship the first impl, extract the seam when the second one arrives.
 
 ## How this applies to skill authoring
 
-Skills are modules. The frontmatter (`name`, `description`, `tags`) plus the workflow signature is the interface; the SKILL.md body is the implementation. A deep skill has a small, predictable interface (clear when to invoke, clear output shape) hiding genuine workflow value. A shallow skill is one whose body adds little beyond what the frontmatter already implies — those skills should be either deepened or deleted. The skill-authoring contract's 100-line cap is the depth principle applied to skills: if the implementation cannot fit in 100 lines, either the workflow is too broad (split it) or supporting domain content should move to `reference/*.md` (extract-then-link, D-10). See `./skill-authoring-contract.md` for the full spec.
+Skills are modules. The frontmatter (`name`, `description`, `tags`) plus the workflow signature is the interface; the SKILL.md body is the implementation. A deep skill has a small, predictable interface (clear when to invoke, clear output shape) hiding genuine workflow value. A shallow skill is one whose body adds little beyond what the frontmatter already implies - those skills should be either deepened or deleted. The skill-authoring contract's 100-line cap is the depth principle applied to skills: if the implementation cannot fit in 100 lines, either the workflow is too broad (split it) or supporting domain content should move to `reference/*.md` (extract-then-link, D-10). See `./skill-authoring-contract.md` for the full spec.
 
 ## Cross-references
 
-- Design-system-level analog — component-as-module, design-token-as-interface: see `./design-system-guidance.md`.
-- Component-library-level analog — the 6-principle quality standard (Minimal API, Composability, ...): see `./component-authoring.md`.
-- Skill-authoring application — extract-then-link, 100-line cap, refs-one-level-deep: see `./skill-authoring-contract.md`.
+- Design-system-level analog - component-as-module, design-token-as-interface: see `./design-system-guidance.md`.
+- Component-library-level analog - the 6-principle quality standard (Minimal API, Composability, ...): see `./component-authoring.md`.
+- Skill-authoring application - extract-then-link, 100-line cap, refs-one-level-deep: see `./skill-authoring-contract.md`.
 - `CONTEXT.md` glossary format (project-scoped ubiquitous language alongside this vocabulary): see `./context-md-format.md`.
 - ADR format (heavier project-scoped decisions about architectural seams): see `./adr-format.md`.

package/reference/audit-scoring.md

@@ -8,7 +8,7 @@ Use during Discover (establishing baseline) and Verify (measuring improvement).
 
 | Level | Code | Impact | Action |
 |---|---|---|---|
-| Blocker | **P0** | Breaks functionality or violates a hard requirement | Fix before shipping — no exceptions |
+| Blocker | **P0** | Breaks functionality or violates a hard requirement | Fix before shipping - no exceptions |
 | Major | **P1** | Significantly degrades UX or fails accessibility standard | Fix in this design pass |
 | Minor | **P2** | Noticeable issue but doesn't break flows | Fix if time allows |
 | Cosmetic | **P3** | Polish item only, subjective quality issue | Deferred to polish pass |
@@ -24,10 +24,10 @@ Score each category 0–10. Overall score = weighted average.
 | Score | Criteria |
 |---|---|
 | 10 | All WCAG 2.1 AA criteria pass. Keyboard nav works end-to-end. Focus rings visible. No color-only meaning. |
-| 8–9 | Minor issues — 1–2 non-critical violations, no contrast failures on primary text |
-| 5–7 | Several violations — contrast issues on secondary text, some missing labels |
-| 3–4 | Multiple failures — some interactive elements inaccessible, missing alt text |
-| 0–2 | Critical failures — primary text fails contrast, keyboard nav broken, missing form labels |
+| 8–9 | Minor issues - 1–2 non-critical violations, no contrast failures on primary text |
+| 5–7 | Several violations - contrast issues on secondary text, some missing labels |
+| 3–4 | Multiple failures - some interactive elements inaccessible, missing alt text |
+| 0–2 | Critical failures - primary text fails contrast, keyboard nav broken, missing form labels |
 
 Auto-checkable:
 - Body text contrast ≥ 4.5:1
@@ -73,7 +73,7 @@ grep -rEn "(padding|margin|gap):\s*(8|12|16)px" src/ --include="*.css" 2>/dev/nu
 grep -rEn "(margin-top|margin-bottom|gap):\s*(32|40|48|64)px" src/ --include="*.css" 2>/dev/null | head -5
 ```
 
-These patterns supplement the qualitative rubric above — they cannot replace
+These patterns supplement the qualitative rubric above - they cannot replace
 visual inspection but reduce false positives during automated audit passes.
 
 ### 3. Typography (Weight: 15%)
@@ -162,11 +162,11 @@ Score = (Accessibility × 0.25)
 
 | Grade | Score | Meaning |
 |---|---|---|
-| A | 90–100 | Excellent — production ready |
-| B | 75–89 | Good — minor polish needed |
-| C | 60–74 | Acceptable — notable issues to address |
-| D | 45–59 | Poor — significant redesign needed |
-| F | 0–44 | Failing — fundamental problems |
+| A | 90–100 | Excellent - production ready |
+| B | 75–89 | Good - minor polish needed |
+| C | 60–74 | Acceptable - notable issues to address |
+| D | 45–59 | Poor - significant redesign needed |
+| F | 0–44 | Failing - fundamental problems |
 
 ---
 
@@ -226,7 +226,7 @@ Check for (see `reference/checklists.md` Micro-Polish Check gate):
 - Font smoothing at `:root` only
 - Dynamic numbers: `font-variant-numeric: tabular-nums`
 - Nested elements: concentric radius (`innerRadius = outerRadius − padding`)
-- Images: `outline: 1px solid rgba(0,0,0,0.08)` — no tinted outlines
+- Images: `outline: 1px solid rgba(0,0,0,0.08)` - no tinted outlines
 - Interactive elements <40px: `::after` hit-area extension to 40×40
 - Press feedback: `scale(0.96)` exactly
 - `AnimatePresence` on persistent UI: `initial={false}`
@@ -239,7 +239,7 @@ Check for (see `reference/checklists.md` Micro-Polish Check gate):
 
 ## Lens-Tags (Orthogonal)
 
-Tags auditors attach to findings under existing pillars to record cross-cutting dimensions without changing the pillar structure or weights. Same orthogonal pattern as Phase 19.6 `emotion_levels` and `authoring_principles`. Adding a lens-tag does NOT change pillar weights, scoring math, or audit output format — it is a label on an existing finding.
+Tags auditors attach to findings under existing pillars to record cross-cutting dimensions without changing the pillar structure or weights. Same orthogonal pattern as Phase 19.6 `emotion_levels` and `authoring_principles`. Adding a lens-tag does NOT change pillar weights, scoring math, or audit output format - it is a label on an existing finding.
 
 ### `composition_alignment`
 

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.