@hegemonart/get-design-done 1.28.0 → 1.28.6

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.28.0"
+    "version": "1.28.6"
   },
   "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.28.0",
+      "version": "1.28.6",
       "author": {
         "name": "hegemonart"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.28.0",
+  "version": "1.28.6",
   "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",

package/CHANGELOG.md

@@ -4,6 +4,140 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.28.6] — 2026-05-18
+
+### Phase 28.6 — Skill Reference Co-Location (Corrective Follow-Up to Phase 28.5)
+
+Corrects Phase 28.5's CONTEXT.md D-06 over-generalization. Phase 28.5 extracted 20 skill-private procedure refs into a central `reference/` folder, but each of those refs is consumed by exactly 1 (or in 2 borderline cases, 2 sibling) skills. Per mattpocock/skills' actual structure at `https://github.com/mattpocock/skills/tree/main/skills`, skill-private procedure docs live next to the `SKILL.md` they describe. Phase 28.6 co-locates the 20 refs into per-skill folders and refreshes the contract's §D-06 to endorse the per-skill folder pattern for 1-/2-consumer content. No new features. No breaking changes. `git mv` preserves history on every file. Phase 28.5's contract spec, validator, CI gate, `zoom-out`, debug Phase 1 patch, CONTEXT.md + ADR project artifacts, decision-injector extension, and 70/70 length compliance are all PRESERVED; only the location of skill-private refs changes.
+
+#### Migrated refs (20 — `reference/<topic>.md` -> `skills/<owner>/<topic>.md`)
+
+- `apply-reflections-procedure.md` -> `skills/apply-reflections/`
+- `cache-policy.md` -> `skills/cache-manager/` (primary; `warm-cache` secondary via `./../cache-manager/cache-policy.md`)
+- `compare-rubric.md` -> `skills/compare/`
+- `connections-onboarding.md` -> `skills/connections/`
+- `darkmode-audit-procedure.md` -> `skills/darkmode/`
+- `debug-feedback-loops.md` -> `skills/debug/`
+- `design-procedure.md` -> `skills/design/`
+- `discover-procedure.md` -> `skills/discover/`
+- `explore-procedure.md` -> `skills/explore/`
+- `health-mcp-detection.md` -> `skills/health/`
+- `health-skill-length-report.md` -> `skills/health/`
+- `milestone-completeness-rubric.md` -> `skills/new-cycle/` (primary; `turn-closeout` secondary)
+- `peer-cli-protocol.md` -> `skills/peer-cli-add/` (primary; `peer-cli-customize` + `peers` secondary)
+- `plan-procedure.md` -> `skills/plan/`
+- `router-rules.md` -> `skills/router/`
+- `scan-procedure.md` -> `skills/scan/`
+- `start-procedure.md` -> `skills/start/`
+- `style-doc-procedure.md` -> `skills/style/`
+- `threat-modeling.md` -> `skills/quality-gate/`
+- `verify-procedure.md` -> `skills/verify/`
+
+#### Contract refresh
+
+- `reference/skill-authoring-contract.md` §D-06 refreshed: per-skill folder pattern explicitly endorsed for skill-private content. Three placement classes codified — 1-consumer in `skills/<owner>/<topic>.md`; 2-consumer in primary owner's folder with `./../<primary>/<topic>.md` secondary cross-link; multi-consumer (3+ skills across different domains) in `reference/<topic>.md`. The Phase 28.5 "rare exception only" framing is reversed.
+
+#### Registry purge
+
+- `reference/registry.json`: 20 entries removed (the migrated procedure refs are no longer tracked centrally; they're discoverable via the skill folder itself, per mattpocock's pattern). Universal refs (consumed by 3+ skills) remain in the registry.
+
+#### Phase 28.5 retrospective annotation
+
+- `.planning/phases/28.5-skill-authoring-contract/CONTEXT.md` D-06 annotated with a "Corrected by Phase 28.6" pointer for audit-trail preservation. Phase 28.5 decisions stay visible but flagged as superseded.
+
+#### Plans
+
+- 28.6-01 — `git mv` 20 refs + cross-link updates across 23 SKILL.md consumers (`./../reference/<topic>.md` -> `./<topic>.md` or `./../<primary>/<topic>.md`). (COLOC-01)
+- 28.6-02 — `reference/registry.json` 20-entry purge (D-03) + `reference/skill-authoring-contract.md` §D-06 refresh (D-04). (COLOC-02)
+- 28.6-03 — Validator + baseline + full `npm test` sweep (all green; D-05 confirmation that `scripts/validate-skill-length.cjs` globs `SKILL.md` only; no validator edit). (COLOC-03)
+- 28.6-04 — Closeout (4-manifest lockstep at v1.28.6, `OFF_CADENCE_VERSIONS.add('1.28.6')`, CHANGELOG, ROADMAP add + scoped flip, baseline at `test-fixture/baselines/phase-28.6/`, Phase 28.5 CONTEXT.md retrospective annotation). (COLOC-04)
+
+#### Non-changes
+
+- NOTICE unchanged — Phase 28.5's mattpocock/skills MIT attribution still applies (same content; file paths shifted only).
+- `test-fixture/baselines/phase-20/skill-list.txt` unchanged — no skills added or removed.
+- `scripts/validate-skill-length.cjs` unchanged — D-05 verified the validator globs `SKILL.md` only and is unaffected by co-located procedure refs.
+
+---
+
+## [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

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/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.28.0",
+  "version": "1.28.6",
   "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/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/architecture-vocabulary.md

@@ -0,0 +1,102 @@
+---
+name: architecture-vocabulary
+type: principles
+version: 1.0.0
+phase: 28.5
+tags: [architecture, ousterhout, module, interface, depth, seam, adapter, leverage, locality]
+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.
+
+# 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.
+
+This file is the canonical reference; skills cite it instead of re-defining terms inline.
+
+## Module
+
+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.
+- 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.
+
+- `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.
+- See `./component-authoring.md` (6-principle quality standard, esp. "Minimal API" and "Composability") for the component-library-level analog.
+
+## 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.
+
+- 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.
+
+## 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.
+
+- `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`.
+- 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.
+
+## 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.
+
+- **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.
+- "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.
+
+## Adapter
+
+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 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).
+
+## Leverage
+
+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.
+
+- `<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×.
+
+## 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.
+
+- 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.
+
+## Principles
+
+Three load-bearing 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.
+
+## 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.
+
+## 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`.
+- `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`.