@hegemonart/get-design-done 1.27.7 → 1.28.5

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Get Design Done — 5-stage agent-orchestrated design pipeline with 9 connections, handoff-first workflow, bidirectional Figma write-back, 22+ specialized agents, queryable knowledge layer (intel store, dependency analysis, learnings extraction), and a self-improvement loop (reflector, frontmatter + budget feedback, global-skills layer). v1.20.0 ships the SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream, and resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) for rate-limit + 429 + context-overflow recovery. Full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation (auto-tag + GitHub Release + release-time smoke test).",
-    "version": "1.27.7"
+    "version": "1.28.5"
   },
   "plugins": [
     {
       "name": "get-design-done",
       "source": "./",
       "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), Claude Design handoff, bidirectional Figma write-back, and a queryable intel store (.design/intel/) for dependency and learnings queries. Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation. Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain.",
-      "version": "1.27.7",
+      "version": "1.28.5",
       "author": {
         "name": "hegemonart"
       },

package/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.27.7",
-  "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), handoff-first workflow via Claude Design bundles, bidirectional Figma write-back (annotations, Code Connect), queryable intel store (`.design/intel/`) for O(1) design surface lookups, and self-improvement loop (reflector agent, frontmatter + budget feedback, global-skills layer at `~/.claude/gdd/global-skills/`). Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings, reflect, apply-reflections. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows, lint + schema + frontmatter + stale-ref + shellcheck + gitleaks + injection-scan + blocking size-budget) and release automation (auto-tag + GitHub Release + release-time smoke test). Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain. v1.27.7 ships gdd-mcp (Phase 27.7): 12 read-only MCP tools for sub-3s priming.",
+  "version": "1.28.5",
+  "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), handoff-first workflow via Claude Design bundles, bidirectional Figma write-back (annotations, Code Connect), queryable intel store (`.design/intel/`) for O(1) design surface lookups, and self-improvement loop (reflector agent, frontmatter + budget feedback, global-skills layer at `~/.claude/gdd/global-skills/`). Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings, reflect, apply-reflections. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows, lint + schema + frontmatter + stale-ref + shellcheck + gitleaks + injection-scan + blocking size-budget) and release automation (auto-tag + GitHub Release + release-time smoke test). Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain. v1.27.7 ships gdd-mcp (Phase 27.7): 12 read-only MCP tools for sub-3s priming. v1.28.0 (Phase 28): Foundational References Tier 2 — 5 new reference files (color-theory, composition, proportion-systems, i18n, contrast-advanced), 2 verifier i18n probes + 1 explore i18n-readiness probe, 12 additive cross-link insertions across 10 existing references, 2 orthogonal audit-scoring lens-tags (composition_alignment + i18n_readiness).",
   "author": {
     "name": "hegemonart",
     "url": "https://github.com/hegemonart"

package/CHANGELOG.md

@@ -4,6 +4,148 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.28.5] — 2026-05-18
+
+### Phase 28.5 — Skill Authoring Contract + Skill Rework + Project Artifacts
+
+Adopts the mattpocock/skills (MIT) authoring contract and applies it retroactively across the entire shipped skill set. Closes the authoring-discipline gap surfaced by the 2026-05-02 comparison audit. 12 plans across 4 waves; off-cadence decimal patch from v1.28.0 parent (CONTEXT.md D-12 convention).
+
+#### New reference files
+
+- `reference/skill-authoring-contract.md` (28.5-01) — 100-line `SKILL.md` cap (warn >=100, block >=250 in CI), 1024-char description cap, required `<what>. Use when <triggers>.` form, frontmatter required fields, progressive-disclosure one-level-deep rule, when to add `scripts/`, per-skill domain-specific files allowed only when content is single-skill-private.
+- `reference/context-md-format.md` (28.5-02) — DDD-style ubiquitous-language glossary schema with optional `first-seen` + `aliases` GDD additions; CONTEXT-MAP.md multi-context pattern; inline-write-on-resolution trigger.
+- `reference/adr-format.md` (28.5-02) — 3-criteria offer gate (hard-to-reverse AND surprising-without-context AND real-tradeoff), 4-state status lifecycle, optional `cycle-id` + `phase-id` cross-refs back to STATE.md (GDD addition).
+- `reference/architecture-vocabulary.md` (28.5-03) — Ousterhout's 8 core terms (Module / Interface / Implementation / Depth / Seam / Adapter / Leverage / Locality) + 3 principles (deletion test, interface-is-test-surface, two-adapters-rule).
+- `reference/scan-procedure.md`, `verify-procedure.md`, `design-procedure.md`, `plan-procedure.md`, `explore-procedure.md`, `discover-procedure.md` (28.5-04) — 6 procedure references extracted from pipeline-stage skills as progressive-disclosure satellites.
+- `reference/shared-preamble.md` (28.5-05, extended), `style-doc-procedure.md`, `compare-rubric.md`, `darkmode-audit-procedure.md`, `connections-onboarding.md` (28.5-05) — 4 new + 1 extended (Bucket 2 design-family rework).
+- `reference/health-mcp-detection.md`, `apply-reflections-procedure.md`, `cache-policy.md`, `router-rules.md`, `start-procedure.md` (28.5-06) — 5 references extracted from Bucket 3 orchestrator + utility skills.
+- `reference/debug-feedback-loops.md` (28.5-07 scaffold + 28.5-09 fill) — 10 construction paths in priority order, iterate-on-loop sub-discipline, non-determinism reproduction-rate branch.
+- `reference/threat-modeling.md`, `milestone-completeness-rubric.md`, `peer-cli-protocol.md` (28.5-07) — 3 additional Bucket 4 extraction targets (analysis + audit skills).
+- `reference/health-skill-length-report.md` (28.5-11) — health-skill subsection contract documenting validator JSON shape + threshold rationale.
+
+#### Skill rework
+
+- Bucket 1 (28.5-04) — 11 pipeline-stage skills (`brief`, `discuss`, `plan`, `design`, `verify`, `explore`, `discover`, `scan`, `sketch`, `spike`, `new-cycle`, `complete-cycle`) reworked to <=100 lines.
+- Bucket 2 (28.5-05) — 7 design-family skills (`audit`, `style`, `darkmode`, `compare`, `design`, `figma-write`, `connections`, `benchmark`) cross-link cleanup + description standardization.
+- Bucket 3 (28.5-06) — 34 orchestrator + utility skills (`help`, `stats`, `note`, `add-backlog`, `todo`, `progress`, `health`, `update`, `undo`, `fast`, `quick`, `next`, `do`, `resume`, `pause`, etc.) `disable-model-invocation: true` whitelist applied; targeted trims on the offenders.
+- Bucket 4 (28.5-07) — 17 analysis + audit skills (`scan`, `map`, `analyze-dependencies`, `sketch-wrap-up`, `spike-wrap-up`, `skill-manifest`, `debug`, `peers`, `peer-cli-add`, `peer-cli-customize`, `quality-gate`, `turn-closeout`, `start`, `check-update`, `optimize`, etc.) extraction-then-link pattern; new refs created where content qualified as proper reference material.
+- All 70 skills under 100 lines post-rework (`scripts/validate-skill-length.cjs --quiet --json` summary: 70 total / 70 clean / 0 warn / 0 block).
+
+#### Skill patches + new skill
+
+- `discuss` + `brief` skill patches (28.5-08) — inline `CONTEXT.md` glossary maintenance (no batching) + ADR-offer 3-criteria gate at session end.
+- `hooks/gdd-decision-injector.js` extended (28.5-08) — reads `CONTEXT.md` + `docs/adr/*` additively alongside STATE.md cycle-scoped decisions.
+- `debug` skill Phase 1 patch (28.5-09) — explicit feedback-loop gate before any hypothesizing; cross-link to `reference/debug-feedback-loops.md` one level deep.
+- New `/gdd:zoom-out` micro-skill (28.5-10) at `skills/zoom-out/SKILL.md` — ~10 lines body, frontmatter `disable-model-invocation: true`. Direct port from mattpocock/skills (MIT). Total shipped skills: 69 -> 70.
+
+#### CI gate + health reporting (28.5-11)
+
+- `.github/workflows/ci.yml` lint job invokes `node scripts/validate-skill-length.cjs --quiet --json`. Block-level errors (>=250 lines, missing required frontmatter, description out of 1024-char range, unauthorized `disable-model-invocation: true`) fail the build. Warn-level findings (>=100 lines) are advisory.
+- `skills/health/SKILL.md` gains a "Skill-length report" subsection rendering validator summary post-health-table.
+- Regression baseline at `test-fixture/baselines/phase-28.5/` snapshots current line-count distribution + validator summary + 4-manifest version + cross-link integrity + registry diff.
+- `tests/phase-28.5-baseline.test.cjs` (9 assertions) locks the baseline; future PRs cannot regress without regenerating the fixture.
+
+#### Closeout (28.5-12)
+
+- 4-manifest lockstep at v1.28.5: `package.json`, `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json` (metadata.version + plugins[0].version), `test-fixture/baselines/phase-28/manifests-version.txt` (Phase 28 baseline propagates forward per closeout discipline).
+- `tests/semver-compare.test.cjs`: `OFF_CADENCE_VERSIONS.add('1.28.5')`.
+- `NOTICE` extended with Phase 28.5 MIT attribution block for mattpocock/skills (covers 5 reference ports + zoom-out direct port + debug Phase 1 ordering).
+- `reference/registry.json` += 24 new Phase 28.5 entries; `reference/registry.schema.json` aligned to `"phase": { "type": "number" }` (precedent already established by phase 19.6 / 27.5 / 27.6 / 27.7 entries).
+- `test-fixture/baselines/phase-20/skill-list.txt` += `zoom-out` (now 70 skills).
+- `.planning/ROADMAP.md` Phase 28.5 plan checkboxes (28.5-01..28.5-12) flipped to `[x]`; top-level overview entry flipped.
+
+### Decisions locked
+
+- D-01: SKILL.md hard cap = 100 lines (warn), 250 lines (block). Strict description-format off by default — validator regex stays open until Phase 33's A/B evidence lands.
+- D-02: Description format follows `<what>. Use when <triggers>.` shape (lax-mode default; Phase 33 A/B will tighten or relax).
+- D-03: NOTICE MIT attribution covers 5 reference ports + zoom-out direct port + debug Phase 1 ordering.
+- D-04: `reference/debug-feedback-loops.md` ships as a proper reference, not inline in the debug SKILL — per progressive-disclosure rule.
+- D-05: `gdd-zoom-out` skill ships with `disable-model-invocation: true` (user-invoked-only shortcut).
+- D-06: CI gate is two-tier — warn-level advisory, block-level fails the build.
+- D-07: `hooks/gdd-decision-injector.js` reads CONTEXT.md + `docs/adr/*` additively alongside STATE.md (no replacement, no precedence change).
+- D-08: ADR-offer fires only when ALL three criteria hold (hard-to-reverse AND surprising-without-context AND real-tradeoff). Routine decisions are explicitly skipped.
+- D-09: 28 skills marked `disable-model-invocation: true` (27 from Bucket 3 + new zoom-out).
+- D-10: Health-MCP detection procedure extracted to `reference/health-mcp-detection.md`; SKILL links one level deep.
+- D-11: `gdd-health` SKILL gains skill-length report subsection — validator JSON shape documented in `reference/health-skill-length-report.md`.
+- D-12: 4-manifest lockstep at v1.28.5; off-cadence decimal patch from v1.28.0 parent. `OFF_CADENCE_VERSIONS.add('1.28.5')` per Phase 27.5/27.6/27.7 closeout discipline.
+
+### Out of scope (deferred or rejected)
+
+- Description-format regex tightening — deferred until Phase 33 A/B evidence on `<what>` clause shortcut behavior lands at `.design/research/description-format-ab.md`.
+- Generating SKILL.md from a frontmatter-only spec (DSL) — keeps SKILL.md authorable by humans; reject machine-only generation per first-class-prose principle.
+- Auto-fixer for over-limit skills — validator is read-only; manual rework preserves authorial intent.
+- Cross-skill description deduplication — accept some triggering overlap; D-02 form is a soft cap, not a uniqueness invariant.
+
+### Attribution
+
+See `NOTICE` Phase 28.5 block for the mattpocock/skills (MIT) attribution covering ported content. License remains MIT (compatible with mattpocock's MIT) — see `LICENSE`.
+
+---
+
+## [1.28.0] — 2026-05-18
+
+### Phase 28 — Foundational References Tier 2 — Color, Composition, Proportion, i18n
+
+Closes 4 foundational-fundamentals gaps + 1 contrast layer surfaced by the 2026-05-01 huashu-design comparison audit + parallel i18n-coverage audit. Pure content + light agent wiring; no architectural change, no new pillar, no breaking consumer contract.
+
+#### New reference files (Wave A + B)
+
+- `reference/color-theory.md` (28-01) — color spaces (sRGB / HSL / OKLCH / LCH), 6 harmonies in OKLCH, simultaneous contrast, color-blindness palettes, color interpolation in animation (closes the sRGB muddy-mid-transition problem).
+- `reference/composition.md` (28-02) — rule of thirds, phi / sqrt(2) / sqrt(3) / sqrt(5) root rectangles, Fibonacci, focal-point construction, visual-weight calculus (size x contrast x isolation x complexity), optical-vs-mathematical centering, Z/F/Gutenberg eye-flow patterns.
+- `reference/proportion-systems.md` (28-03) — 4pt / 8pt / sqrt(2) baseline grids, baseline-grid lock, vertical rhythm, modular relationships across type + spacing + sizing + radius.
+- `reference/i18n.md` (28-04) — text expansion per locale, CSS logical properties, RTL mirroring + directional-icon flip catalog, bidi isolation, full `Intl.*` family (DateTimeFormat / NumberFormat / PluralRules / RelativeTimeFormat / ListFormat / Collator / Segmenter), ICU MessageFormat, Unicode hygiene, multi-script font stacks, WCAG i18n; spec source for design-verifier + explore probes.
+- `reference/contrast-advanced.md` (28-05) — APCA (WCAG 3 draft) Lc 75/60/45/30 thresholds, why 4.5:1 misranks thin/large/colored text (3 worked examples), dual-target pattern with WCAG 2.1 AA, Lc-to-WCAG conversion table. **Ships at v1.28.0 (D-02 — not deferred).**
+
+#### Consumer integration (Wave C — 28-06)
+
+- `agents/design-verifier.md` gains `### i18n probes` subsection with 2 probes: hardcoded-string scan (regex catalog matches react-intl / next-intl / i18next / vue-i18n patterns per D-10) + +40% text-overflow simulation (`scrollWidth > clientWidth` check per D-03). Findings tagged `i18n_readiness` (orthogonal lens, NOT a new pillar).
+- `skills/explore/SKILL.md` gains i18n-readiness probe under Step 2 — informational 3-state classification (`framework-managed` / `partial` / `none`) per D-04 + D-11. NO gate, NO blocking.
+- `reference/registry.json` gains 5 new entries (D-05) — round-trip schema enforced.
+- `reference/audit-scoring.md` gains 2 orthogonal lens-tags (D-07) — `composition_alignment` + `i18n_readiness`. NO new pillar, NO weight change.
+- 12 additive cross-link insertions across 10 existing reference files (D-06): `palette-catalog.md` Step 4 -> `color-theory.md`; `motion-interpolate.md` -> `color-theory.md`; `visual-hierarchy-layout.md` (Compositional Grids + Asymmetry) -> `composition.md`; `design-system-guidance.md` -> `proportion-systems.md`; `typography.md` (Type Scale Systems + Variable Fonts) -> `proportion-systems.md` + `i18n.md`; `rtl-cjk-cultural.md` (top-of-file) -> `i18n.md`; `form-patterns.md` -> `i18n.md`; `accessibility.md` (x2) -> `i18n.md` + `contrast-advanced.md`; `iconography.md` -> `composition.md`; `style-vocabulary.md` -> `proportion-systems.md`.
+
+#### Decisions locked
+
+- D-01 (rejection): No net-new audit pillar — orthogonal lens-tags only on existing pillars.
+- D-02: `contrast-advanced.md` ships at v1.28.0 (not deferred).
+- D-03: Verifier overflow probe uses `scrollWidth > clientWidth` after +40% text expansion (cheap synchronous DOM check, no headless-browser dependency).
+- D-04: Explore i18n probe is informational only — 3-state output (`framework-managed` / `partial` / `none`), no gate, no blocking.
+- D-05: 5 new `reference/registry.json` entries with phase=28.
+- D-06: All 12 cross-link insertions are additive (no removals, no rewordings of existing content).
+- D-07: 2 audit-scoring lens-tags (`composition_alignment` + `i18n_readiness`) — orthogonal to existing pillars, not new pillars.
+- D-08: 4-manifest lockstep at 1.28.0 — `package.json#version`, `.claude-plugin/plugin.json#version`, `.claude-plugin/marketplace.json#metadata.version`, `.claude-plugin/marketplace.json#plugins[0].version` all align. `OFF_CADENCE_VERSIONS.add('1.28.0')` added to `tests/semver-compare.test.cjs`.
+- D-09: Phase 20 baselines unchanged (no new agents/skills/hooks introduced in Phase 28).
+- D-10: Hardcoded-string scan covers react-intl / next-intl / i18next / vue-i18n call-site patterns; false-positive tightening is reflector carry-forward debt.
+- D-11: Explore probe is single-shot per run (no caching, no telemetry pinning).
+- D-12: ROADMAP scoped flip — 7 inline plan checkboxes (28-01..28-07) + 1 top-level overview entry. STRICTLY bounded to Phase 28; other phases' `[ ]` markers untouched.
+
+#### Tests added
+
+- `tests/phase-28-probes.test.cjs` — 21 tests (28-06): verifier i18n probes, explore i18n-readiness probe, 5 registry entries, cross-link integrity across 12 insertions, audit-scoring lens-tags.
+- `tests/phase-28-baseline.test.cjs` — 8 tests (28-07): 4-manifest alignment, baseline file presence, reference file presence, registry round-trip, cross-link integrity, verifier + explore probe markers, CHANGELOG block at top, OFF_CADENCE recognition. Version-agnostic (reads `package.json#version` dynamically — D-08 lesson).
+- `test-fixture/baselines/phase-28/` — 6 baseline text files: `reference-files-presence.txt`, `registry-diff.txt`, `cross-link-integrity.txt`, `verifier-probes-presence.txt`, `explore-probe-presence.txt`, `manifests-version.txt`.
+
+#### Out of scope (deferred or rejected)
+
+- 20 designer-school philosophies catalog (huashu-design license unresolved).
+- Brand asset acquisition protocol (5-10-2-8 curation rule — separate phase).
+- Color-management profiles (Display-P3 / Rec.2020 / BT.2100 — video/print only).
+- Generative color systems (Material You algorithm — already in `style-vocabulary.md`).
+- Net-new audit pillar (lens-tags instead, per D-07).
+- Translation-management workflows (Crowdin / Lokalise / Phrase — ops concern).
+- Locale-pack bundling / lazy-loading (production tuning concern).
+- Pseudolocalization tooling (+40% overflow at verifier layer covers same QA goal).
+- RTL typography subtleties beyond mirroring (Arabic kashida, vertical CJK — `rtl-cjk-cultural.md` already touches).
+
+#### Carry-forward debt
+
+- Verifier hardcoded-string scan false-positive rate (D-10) — reflector measures over first N runs; tightens regex per Phase 11 self-improvement loop.
+- APCA spec ratification — currently WCAG 3 draft; if it advances to candidate-recommendation, `contrast-advanced.md` becomes more authoritative.
+- ICU MessageFormat 2.0 status — currently Stage 3 / draft at TC39; if it lands, `i18n.md` ICU section may add 2.0 examples in a follow-up.
+- `Intl.Segmenter` browser-support drift — Safari shipped late; polyfill/fallback note may need adding to `i18n.md` Unicode Hygiene section.
+
+---
+
 ## [1.27.7] — 2026-05-18
 
 ### Added

package/SKILL.md

@@ -2,7 +2,7 @@
 name: get-design-done
 short_name: gdd
 description: "Master design pipeline for Claude Code. 5-stage workflow: Brief → Explore → Plan → Design → Verify. Run 'brief' first in any new project to capture the design problem, then 'explore' to inventory the codebase and interview for context. Invoke without arguments for status and auto-routing."
-argument-hint: "[brief|explore|plan|design|verify|handoff|map|next|help|status|style|darkmode|compare|figma-write|graphify|discuss|list-assumptions|progress|health|todo|stats|note|plant-seed|add-backlog|review-backlog|scan|discover|settings|update|reapply-patches|audit|pause|resume|new-cycle|debug|quick|new-project|complete-cycle|fast|do|ship|undo|pr-branch|sketch|sketch-wrap-up|spike|spike-wrap-up|reflect|apply-reflections|analyze-dependencies|extract-learnings|skill-manifest|warm-cache|optimize|cache-manager|watch-authorities|check-update|benchmark|recall|timeline|continue]"
+argument-hint: "[brief|explore|plan|design|verify|handoff|map|next|help|status|style|darkmode|compare|figma-write|graphify|discuss|list-assumptions|progress|health|todo|stats|note|plant-seed|add-backlog|review-backlog|scan|discover|settings|update|reapply-patches|audit|pause|resume|new-cycle|debug|quick|new-project|complete-cycle|fast|do|ship|undo|pr-branch|sketch|sketch-wrap-up|spike|spike-wrap-up|reflect|apply-reflections|analyze-dependencies|extract-learnings|skill-manifest|warm-cache|optimize|cache-manager|watch-authorities|check-update|benchmark|recall|timeline|continue|zoom-out]"
 user-invocable: true
 ---
 

package/agents/design-verifier.md

@@ -161,6 +161,23 @@ Before → After
 ━━━━━━━━━━━━━━━━━━━━━
 ```
 
+### i18n probes
+
+Two additive probes (Phase 28, D-03 — orthogonal `i18n_readiness` lens-tag, NOT a new pillar). Full spec: `./reference/i18n.md` §Verifier Integration Spec; severity rules: `./reference/audit-scoring.md` §Lens-Tags.
+
+**Probe 1 — Hardcoded-string scan.** Regex catalog (D-10 patterns):
+
+```txt
+react-intl:  <FormattedMessage\s+id="[^"]+"
+next-intl:   \bt\(\s*['"][a-zA-Z][\w.]*['"]
+i18next:     \bt\(\s*['"][a-zA-Z][\w.]*['"]\s*,\s*\{
+vue-i18n:    \$t\(\s*['"][a-zA-Z][\w.]*['"]
+```
+
+Allow-list seed (skip): `console\.(log|error|warn|info|debug)`, dev-only `/* */` comments, `data-testid=`, `className=`, `import … from` paths. Severity: `MINOR` per file; `MAJOR` if violating files > 10. Output: `i18n_readiness: <N> hardcoded strings in <M> files`.
+
+**Probe 2 — +40% text-overflow simulation.** Worst-case LTR expansion (RU/FI/PL family — `./reference/i18n.md` §Text Expansion). Per text node `T`: pad `T.textContent` to `length × 1.4`, measure `T.parentElement.scrollWidth > clientWidth`, restore original. Prefer Preview MCP screenshot-diff when available; fall back to in-process DOM measurement headless. Severity `MINOR` per finding; `MAJOR` if overflowing components > 10. Output: `i18n_readiness: <N> components overflow at +40% expansion`.
+
 ---
 
 ## Phase 2 — Must-Have Check

package/hooks/gdd-decision-injector.js

@@ -280,6 +280,128 @@ function buildPrototypingBlock(stateFile, basename, relPath) {
   return lines.join('\n');
 }
 
+/**
+ * Phase 28.5 plan 08 (D-04) — additive CONTEXT.md / ADR context.
+ *
+ * `CONTEXT.md` is a project-scoped ubiquitous-language glossary (schema:
+ * reference/context-md-format.md). Each entry is an `## Term` heading + body
+ * paragraph; optional `**Aliases:** [...]` line enables term-merging. The hook
+ * surfaces entries whose name or aliases match the opened file's tokens.
+ *
+ * ADRs live at `docs/adr/NNNN-<slug>.md` (schema: reference/adr-format.md). The
+ * hook surfaces matching titles as one-line cross-references.
+ *
+ * All file reads are defensive: missing or malformed files yield [] silently so
+ * the hook NEVER crashes (T-28.5-08-01 mitigation). Output is bounded by
+ * PROTOTYPING_TOP_N to prevent DoS (T-28.5-08-03).
+ */
+function readContextMd(repoRoot) {
+  const ctxPath = path.join(repoRoot, 'CONTEXT.md');
+  if (!fs.existsSync(ctxPath)) return [];
+  let content;
+  try { content = fs.readFileSync(ctxPath, 'utf8'); } catch { return []; }
+  const entries = [];
+  // Split on `## ` only when it is the start of a line. The first segment is
+  // preamble (everything before the first ## heading) — discard it.
+  const sections = content.split(/^## /m).slice(1);
+  for (const sec of sections) {
+    const lines = sec.split(/\r?\n/);
+    const term = (lines[0] || '').trim();
+    if (!term) continue;
+    const body = lines.slice(1).join('\n');
+    let aliases = [];
+    const aliasMatch = body.match(/\*\*Aliases:\*\*\s*\[([^\]]+)\]/);
+    if (aliasMatch) {
+      aliases = aliasMatch[1]
+        .split(',')
+        .map((s) => s.trim().replace(/^["']|["']$/g, ''))
+        .filter(Boolean);
+    }
+    entries.push({ term, body, aliases });
+  }
+  return entries;
+}
+
+function readAdrs(repoRoot) {
+  const adrDir = path.join(repoRoot, 'docs', 'adr');
+  if (!fs.existsSync(adrDir)) return [];
+  let files;
+  try { files = fs.readdirSync(adrDir); } catch { return []; }
+  const entries = [];
+  for (const f of files) {
+    if (!/^\d{4}-.*\.md$/.test(f)) continue;
+    let content;
+    try { content = fs.readFileSync(path.join(adrDir, f), 'utf8'); } catch { continue; }
+    // Title from frontmatter `title:` line, else first H1, else filename.
+    const titleMatch = content.match(/^title:\s*(.+)$/m) || content.match(/^# (.+)$/m);
+    const title = titleMatch
+      ? titleMatch[1].trim().replace(/^["']|["']$/g, '')
+      : f.replace(/\.md$/, '');
+    entries.push({ path: `docs/adr/${f}`, title, body: content.slice(0, 500) });
+  }
+  return entries;
+}
+
+function matchContextEntries(entries, tokens) {
+  if (!entries.length || !tokens.length) return [];
+  const lcTokens = tokens.map((t) => String(t).toLowerCase()).filter(Boolean);
+  const out = [];
+  for (const e of entries) {
+    const candidates = [e.term, ...e.aliases].map((s) => String(s).toLowerCase());
+    const hit = candidates.some((cand) =>
+      lcTokens.some((tok) => cand.includes(tok) || tok.includes(cand))
+    );
+    if (hit) out.push(e);
+  }
+  return out;
+}
+
+function matchAdrEntries(entries, tokens) {
+  if (!entries.length || !tokens.length) return [];
+  const lcTokens = tokens.map((t) => String(t).toLowerCase()).filter(Boolean);
+  return entries.filter((a) => {
+    const t = a.title.toLowerCase();
+    return lcTokens.some((tok) => t.includes(tok));
+  });
+}
+
+function buildGlossaryBlock(matched) {
+  if (!matched.length) return null;
+  const lines = [];
+  lines.push('');
+  lines.push('### Project glossary (CONTEXT.md)');
+  for (const e of matched.slice(0, PROTOTYPING_TOP_N)) {
+    const snippet = e.body
+      .split(/\r?\n/)
+      .filter((l) => l.trim() && !l.startsWith('**'))
+      .slice(0, 2)
+      .join(' ')
+      .trim();
+    const trimmed = snippet.length > 200 ? snippet.slice(0, 197) + '…' : snippet;
+    lines.push(`> - **${e.term}** — ${trimmed}`);
+  }
+  if (matched.length > PROTOTYPING_TOP_N) {
+    lines.push(`> … (${matched.length - PROTOTYPING_TOP_N} more glossary entr${matched.length - PROTOTYPING_TOP_N === 1 ? 'y' : 'ies'})`);
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+function buildAdrBlock(matched) {
+  if (!matched.length) return null;
+  const lines = [];
+  lines.push('');
+  lines.push('### Architecture Decision Records (ADRs)');
+  for (const a of matched.slice(0, PROTOTYPING_TOP_N)) {
+    lines.push(`> - [${a.title}](${a.path})`);
+  }
+  if (matched.length > PROTOTYPING_TOP_N) {
+    lines.push(`> … (${matched.length - PROTOTYPING_TOP_N} more ADR${matched.length - PROTOTYPING_TOP_N === 1 ? '' : 's'})`);
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
 function buildRecallBlock(matches, basename, backendLabel) {
   if (!matches.length) return null;
   const uniq = [];
@@ -380,15 +502,39 @@ async function main() {
   const stateFile = sources.find((p) => p.endsWith(path.sep + 'STATE.md') || p.endsWith('/STATE.md'));
   const protoBlock = buildPrototypingBlock(stateFile, basename, relPath);
 
-  if (!block && !protoBlock) {
+  // Phase 28.5 plan 08 (D-04): additive CONTEXT.md + ADR context. Tokens used
+  // for matching are derived from the opened file's basename + relPath, split
+  // on kebab/snake/path separators and filtered down to substantive tokens.
+  // The match is intentionally loose (substring both ways) so an alias like
+  // "heuristics" surfaces when opening reference/heuristics.md.
+  const matchTokens = Array.from(new Set([
+    basename.replace(/\.md$/i, ''),
+    ...basename.replace(/\.md$/i, '').split(/[-_./\\]/),
+    ...relPath.split(/[-_./\\]/),
+  ].filter((t) => t && t.length > 2)));
+
+  let glossaryBlock = null;
+  let adrBlock = null;
+  try {
+    const ctxEntries = readContextMd(cwd);
+    const matchedCtx = matchContextEntries(ctxEntries, matchTokens);
+    glossaryBlock = buildGlossaryBlock(matchedCtx);
+  } catch { /* defensive: never crash on CONTEXT.md issues */ }
+  try {
+    const adrEntries = readAdrs(cwd);
+    const matchedAdrs = matchAdrEntries(adrEntries, matchTokens);
+    adrBlock = buildAdrBlock(matchedAdrs);
+  } catch { /* defensive: never crash on ADR issues */ }
+
+  if (!block && !protoBlock && !glossaryBlock && !adrBlock) {
     try { require('./_hook-emit.js').emitHookFired('gdd-decision-injector', 'no-hits', { backend: backendLabel }); } catch { /* swallow */ }
     process.stdout.write(JSON.stringify({ continue: true }));
     return;
   }
 
-  const additionalContext = [block, protoBlock].filter(Boolean).join('\n');
+  const additionalContext = [block, protoBlock, glossaryBlock, adrBlock].filter(Boolean).join('\n');
 
-  try { require('./_hook-emit.js').emitHookFired('gdd-decision-injector', 'inject', { backend: backendLabel, hit_count: hits.length, prototyping: !!protoBlock }); } catch { /* swallow */ }
+  try { require('./_hook-emit.js').emitHookFired('gdd-decision-injector', 'inject', { backend: backendLabel, hit_count: hits.length, prototyping: !!protoBlock, glossary: !!glossaryBlock, adr: !!adrBlock }); } catch { /* swallow */ }
   process.stdout.write(JSON.stringify({
     continue: true,
     hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.27.7",
+  "version": "1.28.5",
   "description": "A design-quality pipeline for AI coding agents: brief, plan, implement, and verify UI work against your design system.",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",

package/reference/accessibility.md

@@ -25,6 +25,8 @@ Common pitfalls:
 
 Tools: Use browser DevTools > Accessibility tab, or pass hex values through contrast calculation.
 
+**See also:** [`./contrast-advanced.md`](./contrast-advanced.md) — APCA (WCAG 3 draft) for perceptual contrast when WCAG 2.1 4.5:1 misranks thin/large/colored text. Recommended dual-target pattern: enforce WCAG 2.1 AA as a floor + APCA Lc-thresholds (75 / 60 / 45 / 30) for perceptual accuracy.
+
 ### Touch Target Size
 
 | Platform | Minimum tap target |
@@ -75,6 +77,8 @@ Recommended focus ring: **3px solid**, `2px offset`, brand primary or `#2563eb`.
 - Images have descriptive `alt=""` for meaningful images; `alt=""` for decorative.
 - Icon-only buttons have `aria-label`: `<button aria-label="Close dialog">×</button>`.
 
+**See:** [`./i18n.md`](./i18n.md) §WCAG i18n for SC 3.1.1 (`<html lang>`) and SC 3.1.2 (`<span lang="…">` language-of-parts) patterns — screen readers select voice/pronunciation packs from these attributes; a missing or wrong `lang` value forces the user to hear French announced in an English accent.
+
 ### Color Must Not Be The Only Differentiator
 
 Error states: red color + error icon + text message (not just red border).

package/reference/adr-format.md

@@ -0,0 +1,96 @@
+---
+name: adr-format
+type: meta-rules
+version: 1.0.0
+phase: 28.5
+tags: [adr, decision, project-scoped, architecture, offer-gate]
+last_updated: 2026-05-18
+---
+
+Source: mattpocock/skills (MIT) — adapted with permission. See `../NOTICE` for the full attribution block.
+
+# ADR Format
+
+An Architecture Decision Record (ADR) is a project-scoped record of a decision that
+outlives the current cycle. ADRs live at `docs/adr/NNNN-<slug>.md` (zero-padded sequence,
+kebab-case slug) and are offered SPARINGLY — only when all three criteria of the offer
+gate hold (D-04). Most decisions stay in `STATE.md` and roll over with the cycle; ADRs
+are the rare exception. See `./context-md-format.md` for the lighter glossary form that
+shares the same project-scoped lifetime.
+
+## 3-criteria offer gate
+
+ALL THREE criteria must hold for the agent to offer an ADR. If ANY criterion fails, keep
+the decision in `STATE.md` instead.
+
+- **hard-to-reverse.** Undoing this decision requires migrating data, breaking APIs, or
+  coordinating across multiple teams or agents. Routine code changes do not qualify.
+- **surprising-without-context.** A reader six months from now, given only the codebase,
+  would be confused. The rationale must be NON-OBVIOUS from the result.
+- **real-tradeoff.** At least one credible alternative was considered and rejected for
+  stated reasons. Decisions with no plausible alternative (e.g., "use HTTPS") do not
+  qualify.
+
+Worked example — **qualifier:** "Switch from REST to GraphQL for the public API."
+Hard-to-reverse (clients integrate against the schema), surprising-without-context (most
+greenfield APIs default to REST), real-tradeoff (tRPC and gRPC were rejected for stated
+reasons). Ship an ADR.
+
+Worked example — **disqualifier:** "Rename the `users` table to `accounts`." Hard-to-reverse,
+but the rationale is obvious from the rename and there is no real alternative once the
+domain has settled on the word. Log in `STATE.md`, not an ADR.
+
+## Frontmatter
+
+```yaml
+---
+title: <Active-voice imperative — e.g., "Adopt OKLCH for design tokens">
+status: Proposed | Accepted | Superseded | Deprecated
+date: <ISO 8601, YYYY-MM-DD>
+cycle-id: <optional GDD addition — originating cycle slug, e.g., "v1.28.5">
+phase-id: <optional GDD addition — originating phase, e.g., "28.5">
+supersedes: <optional — ADR number this one replaces, e.g., "0042">
+---
+```
+
+- **Required.** `title`, `status`, `date`.
+- **Optional (GDD additions per D-04).** `cycle-id` and `phase-id` back-link to the
+  originating cycle's `STATE.md` and the phase that produced the decision. `supersedes`
+  points at the prior ADR number when this ADR replaces one.
+- **Path convention.** `docs/adr/NNNN-<slug>.md` where `NNNN` is zero-padded (`0001`,
+  `0042`, etc.) and the slug is kebab-case.
+
+## Body structure
+
+The ADR body uses four `##` sections in the following order. Each section is a thin
+paragraph or short bullet list — ADRs are decision records, not design docs.
+
+- `## Context` — what situation made this decision necessary; cite the originating
+  cycle's `BRIEF.md` or `STATE.md` if relevant.
+- `## Decision` — what was chosen, stated as an imperative.
+- `## Alternatives` — what was considered and rejected, with brief rationale per
+  alternative.
+- `## Consequences` — what this enables, what it costs, what it constrains downstream.
+
+## Status lifecycle
+
+ADRs progress through four states. The status field in frontmatter is the source of
+truth; transitions are explicit, never silent.
+
+- **Proposed.** Drafted but not yet decided; reviewer pass pending. Downstream work
+  does not cite Proposed ADRs.
+- **Accepted.** Decision active; downstream work cites this ADR by number.
+- **Superseded.** Replaced by a later ADR. The later ADR's `supersedes:` field points
+  here, and this ADR's status is flipped to Superseded. NEVER delete a Superseded ADR —
+  the audit trail is the point.
+- **Deprecated.** No longer relevant (e.g., the system the ADR governed was removed).
+  Kept for history.
+
+## Cross-references
+
+- Domain terms used in the ADR body should already appear in `CONTEXT.md` — see
+  `./context-md-format.md`. If a term is missing, the writer adds it before referencing it.
+- Cycle-scoped decisions (most routine choices) stay in `STATE.md` — see
+  `./STATE-TEMPLATE.md`.
+- Skill structural rules (length cap, frontmatter, progressive disclosure) — see
+  `./skill-authoring-contract.md`.

package/reference/apply-reflections-procedure.md

@@ -0,0 +1,68 @@
+---
+name: apply-reflections-procedure
+type: heuristic
+version: 1.0.0
+phase: 28.5
+tags: [apply-reflections, proposal, frontmatter, reference, budget, question, global-skill]
+last_updated: 2026-05-18
+---
+
+# Apply-Reflections — Per-Type Procedure
+
+Extracted from `skills/apply-reflections/SKILL.md` per Phase 28.5 D-10 (extract-then-link,
+never delete content). The orchestrator loop in `apply-reflections` (resolve file → parse →
+review loop → summary) stays in the SKILL. The per-proposal-type apply logic below moves
+here because it is content-class methodology, not workflow.
+
+## Apply Logic by Proposal Type
+
+After the user chooses `a` (apply) or `e` (edit-then-apply) in the review loop, branch by
+the proposal's bracketed type tag.
+
+### [FRONTMATTER]
+
+1. Extract agent name from Change field (e.g., `agents/design-verifier.md`)
+2. Read the agent file
+3. Find the frontmatter line matching the field being changed
+4. Use Edit tool to update the specific line
+5. Append `**Applied**: <date>` to the proposal in reflections file
+
+### [REFERENCE]
+
+1. Extract target file path from Change field (e.g., `reference/heuristics.md`)
+2. If file exists: append the drafted text using Edit tool
+3. If file doesn't exist: create it with a minimal header + the drafted text using Write tool
+4. Append `**Applied**: <date>` to proposal in reflections file
+
+### [BUDGET]
+
+1. Read `.design/budget.json`
+2. Locate the key path from the Change field (e.g., `design-verifier.per_run_cap_usd`)
+3. Update the value
+4. Write updated JSON back to `.design/budget.json`
+5. Append `**Applied**: <date>` to proposal in reflections file
+
+### [QUESTION]
+
+1. Read `agents/design-discussant.md`
+2. Find the question text specified in the Change field
+3. If pruning: remove the question lines using Edit tool
+4. If rewording: replace the question text using Edit tool
+5. Append `**Applied**: <date>` to proposal in reflections file
+
+### [GLOBAL-SKILL]
+
+1. Extract target filename from Change field (e.g., `design-color-conventions.md`)
+2. Ensure `~/.claude/gdd/global-skills/` directory exists (create with `mkdir -p` if not)
+3. If target file exists: append new content using Edit tool (add a `---` separator first)
+4. If target file doesn't exist: create with header + content using Write tool:
+
+   ```markdown
+   # <Topic> Conventions (Global)
+   *Promoted from project: <project-name>, cycle: <cycle-slug>*
+
+   <content>
+   ```
+
+5. Print: "Global skill written to ~/.claude/gdd/global-skills/<name>.md — auto-loads in all future gdd sessions"
+6. Append `**Applied**: <date>` to proposal in reflections file