@hegemonart/get-design-done 1.28.5 → 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.5"
+    "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.5",
+      "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.5",
+  "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,62 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.28.5",
+  "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/registry.json

@@ -819,13 +819,6 @@
       "phase": 28.5,
       "description": "ADR (Architecture Decision Record) format — adapted from mattpocock/skills (MIT). 3-criteria offer gate (hard-to-reverse AND surprising-without-context AND real-tradeoff), 4-state status lifecycle. GDD addition: optional cycle-id + phase-id cross-refs to STATE.md."
     },
-    {
-      "name": "apply-reflections-procedure",
-      "path": "reference/apply-reflections-procedure.md",
-      "type": "heuristic",
-      "phase": 28.5,
-      "description": "Phase 28.5 — apply-reflections procedure extracted from skills/apply-reflections per progressive-disclosure rule. Read by skills/apply-reflections/SKILL.md."
-    },
     {
       "name": "architecture-vocabulary",
       "path": "reference/architecture-vocabulary.md",
@@ -833,27 +826,6 @@
       "phase": 28.5,
       "description": "Ousterhout glossary (A Philosophy of Software Design) ported via mattpocock/skills LANGUAGE.md (MIT). 8 core terms (Module / Interface / Implementation / Depth / Seam / Adapter / Leverage / Locality) + 3 principles (deletion test, interface-is-test-surface, two-adapters-rule)."
     },
-    {
-      "name": "cache-policy",
-      "path": "reference/cache-policy.md",
-      "type": "heuristic",
-      "phase": 28.5,
-      "description": "Phase 28.5 — cache-policy reference extracted from skills/cache-manager + skills/warm-cache per progressive-disclosure rule (Bucket 3 orchestrator + utility rework)."
-    },
-    {
-      "name": "compare-rubric",
-      "path": "reference/compare-rubric.md",
-      "type": "heuristic",
-      "phase": 28.5,
-      "description": "Phase 28.5 — compare-rubric extracted from skills/compare per progressive-disclosure rule. Read by skills/compare/SKILL.md (Bucket 2 design-family rework)."
-    },
-    {
-      "name": "connections-onboarding",
-      "path": "reference/connections-onboarding.md",
-      "type": "meta-rules",
-      "phase": 28.5,
-      "description": "Phase 28.5 — connections-onboarding procedure extracted from skills/connections per progressive-disclosure rule (Bucket 2 design-family rework). Four-option setup prompt + onboarding flow."
-    },
     {
       "name": "context-md-format",
       "path": "reference/context-md-format.md",
@@ -861,124 +833,12 @@
       "phase": 28.5,
       "description": "CONTEXT.md format — adapted from mattpocock/skills (MIT) CONTEXT-FORMAT.md. DDD-style ubiquitous-language glossary schema, inline-write trigger, multi-context CONTEXT-MAP.md pattern. GDD additions: optional first-seen + aliases on term entries."
     },
-    {
-      "name": "darkmode-audit-procedure",
-      "path": "reference/darkmode-audit-procedure.md",
-      "type": "meta-rules",
-      "phase": 28.5,
-      "description": "Phase 28.5 — darkmode audit procedure extracted from skills/darkmode per progressive-disclosure rule (Bucket 2 design-family rework)."
-    },
-    {
-      "name": "debug-feedback-loops",
-      "path": "reference/debug-feedback-loops.md",
-      "type": "heuristic",
-      "phase": 28.5,
-      "description": "Debug feedback-loop discipline — adapted from mattpocock/skills (MIT) engineering/diagnose Phase 1. 10 construction paths in priority order (failing test -> curl -> CLI fixture -> headless browser -> trace replay -> throwaway harness -> fuzz -> bisect harness -> differential loop -> HITL bash), iterate-on-loop sub-discipline, non-determinism reproduction-rate branch."
-    },
-    {
-      "name": "design-procedure",
-      "path": "reference/design-procedure.md",
-      "type": "meta-rules",
-      "phase": 28.5,
-      "description": "Phase 28.5 — design-stage procedure extracted from skills/design per progressive-disclosure rule (Bucket 1 pipeline-stage rework)."
-    },
-    {
-      "name": "discover-procedure",
-      "path": "reference/discover-procedure.md",
-      "type": "meta-rules",
-      "phase": 28.5,
-      "description": "Phase 28.5 — discover-stage procedure extracted from skills/discover per progressive-disclosure rule (Bucket 1 pipeline-stage rework)."
-    },
-    {
-      "name": "explore-procedure",
-      "path": "reference/explore-procedure.md",
-      "type": "meta-rules",
-      "phase": 28.5,
-      "description": "Phase 28.5 — explore-stage procedure extracted from skills/explore per progressive-disclosure rule (Bucket 1 pipeline-stage rework)."
-    },
-    {
-      "name": "health-mcp-detection",
-      "path": "reference/health-mcp-detection.md",
-      "type": "heuristic",
-      "phase": 28.5,
-      "description": "Phase 28.5 — health-MCP detection procedure extracted from skills/health per progressive-disclosure rule (D-10). Documents dismissal check, detection via scripts/lib/install/mcp-register.cjs, row rendering for claude/codex/both/neither, fallback for missing mcp-register.cjs."
-    },
-    {
-      "name": "health-skill-length-report",
-      "path": "reference/health-skill-length-report.md",
-      "type": "heuristic",
-      "phase": 28.5,
-      "description": "Phase 28.5 — health-skill-length-report contract documenting validate-skill-length.cjs JSON shape + threshold rationale. Read by skills/health/SKILL.md to render the skill-length report subsection."
-    },
-    {
-      "name": "milestone-completeness-rubric",
-      "path": "reference/milestone-completeness-rubric.md",
-      "type": "heuristic",
-      "phase": 28.5,
-      "description": "Phase 28.5 — milestone-completeness rubric extracted from skills/turn-closeout per progressive-disclosure rule (Bucket 4 analysis + audit rework). Turn-closeout / new-cycle completeness criteria."
-    },
-    {
-      "name": "peer-cli-protocol",
-      "path": "reference/peer-cli-protocol.md",
-      "type": "heuristic",
-      "phase": 28.5,
-      "description": "Phase 28.5 — peer-CLI protocol scaffold extracted from skills/peer-cli-add + skills/peer-cli-customize per progressive-disclosure rule (Bucket 4 analysis + audit rework). ACP + ASP adapter scaffolding patterns, verification ladder, Windows quirk handling."
-    },
-    {
-      "name": "plan-procedure",
-      "path": "reference/plan-procedure.md",
-      "type": "meta-rules",
-      "phase": 28.5,
-      "description": "Phase 28.5 — plan-stage procedure extracted from skills/plan per progressive-disclosure rule (Bucket 1 pipeline-stage rework)."
-    },
-    {
-      "name": "router-rules",
-      "path": "reference/router-rules.md",
-      "type": "heuristic",
-      "phase": 28.5,
-      "description": "Phase 28.5 — router-rules reference extracted from skills/router per progressive-disclosure rule (Bucket 3 orchestrator + utility rework). S/M/L/XL bucket assignments + path-selection heuristic."
-    },
-    {
-      "name": "scan-procedure",
-      "path": "reference/scan-procedure.md",
-      "type": "meta-rules",
-      "phase": 28.5,
-      "description": "Phase 28.5 — scan-stage procedure extracted from skills/scan per progressive-disclosure rule (Bucket 1 pipeline-stage rework)."
-    },
     {
       "name": "skill-authoring-contract",
       "path": "reference/skill-authoring-contract.md",
       "type": "meta-rules",
       "phase": 28.5,
       "description": "Phase 28.5 skill-authoring contract — adapted from mattpocock/skills (MIT). SKILL.md <=100-line cap (warn >=100, block >=250 in CI), 1024-char description cap, <what>. Use when <triggers>. form (lax-mode default per Phase 33 A/B pending), frontmatter required fields, progressive-disclosure one-level-deep rule. Validator at scripts/validate-skill-length.cjs."
-    },
-    {
-      "name": "start-procedure",
-      "path": "reference/start-procedure.md",
-      "type": "heuristic",
-      "phase": 28.5,
-      "description": "Phase 28.5 — start-procedure reference extracted from skills/start per progressive-disclosure rule (Bucket 4 analysis + audit rework)."
-    },
-    {
-      "name": "style-doc-procedure",
-      "path": "reference/style-doc-procedure.md",
-      "type": "meta-rules",
-      "phase": 28.5,
-      "description": "Phase 28.5 — style-doc procedure extracted from skills/style per progressive-disclosure rule (Bucket 2 design-family rework)."
-    },
-    {
-      "name": "threat-modeling",
-      "path": "reference/threat-modeling.md",
-      "type": "heuristic",
-      "phase": 28.5,
-      "description": "Phase 28.5 — STRIDE threat-modeling patterns extracted from skills/quality-gate + audit-side scanning per progressive-disclosure rule (Bucket 4 analysis + audit rework). Audit-side threat-model invariants."
-    },
-    {
-      "name": "verify-procedure",
-      "path": "reference/verify-procedure.md",
-      "type": "meta-rules",
-      "phase": 28.5,
-      "description": "Phase 28.5 — verify-stage procedure extracted from skills/verify per progressive-disclosure rule (Bucket 1 pipeline-stage rework)."
     }
   ]
 }

package/reference/skill-authoring-contract.md

@@ -101,21 +101,52 @@ disable-model-invocation: true
 
 References-one-level-deep is the rule (D-06):
 
-- **One level deep.** `SKILL.md` may cross-link into `reference/<topic>.md`. A reference may
+- **One level deep.** `SKILL.md` may cross-link into a reference. A reference may
   cross-link into another reference. `SKILL.md` does NOT instruct the agent to follow a
   reference's references — load the first level only.
-- **Centralized refs.** `reference/typography.md`, `reference/palette-catalog.md`,
-  `reference/audit-scoring.md` and friends are consumed by 15+ skills each. NEVER bundle
-  them per-skill. Per-skill folders are allowed ONLY for content that is truly
-  single-skill-private (rare; typically a fixture or schema only the owning skill reads).
 - **When to add `scripts/`.** Per mattpocock's three criteria, add a script only when the
   step is deterministic, repeated across runs, and the failure mode needs explicit error
   handling. Anything ad-hoc or once-off stays inline as agent prose.
 
-Concrete example: a skill that lists 10 framework matrices inline (~150 lines) extracts the
-matrices to `reference/<framework>-matrices.md` and replaces them with a one-sentence
-summary + cross-link. SKILL.md drops to ~80 lines, the matrices stay discoverable, no
-institutional knowledge is lost.
+### Reference placement classes
+
+Three placement classes by cross-domain consumer count (D-06, refreshed by Phase 28.6 D-04):
+
+- **1-consumer (skill-private procedure refs).** Live in `skills/<owner>/<topic>.md` next
+  to the SKILL.md they describe. Cross-link from SKILL.md as `./<topic>.md`. Matches
+  mattpocock's per-skill folder pattern. Examples: `skills/scan/scan-procedure.md`,
+  `skills/debug/debug-feedback-loops.md`.
+- **2-consumer (same-domain pair).** Live in the primary owner's skill folder. Secondary
+  consumer cross-links via `../<primary>/<topic>.md`. Examples:
+  `skills/cache-manager/cache-policy.md` (skills/warm-cache cross-links in);
+  `skills/peer-cli-add/peer-cli-protocol.md` (skills/peer-cli-customize + skills/peers
+  cross-link in).
+- **Multi-consumer (3+ cross-domain).** Live in `reference/<topic>.md`. Used by 3+ skills
+  across different domains. Examples: `reference/typography.md`,
+  `reference/palette-catalog.md`, `reference/audit-scoring.md` (each consumed by 15+
+  skills).
+
+### Migration policy
+
+When a reference grows from 1-consumer to 3+ cross-domain consumers, migrate from
+`skills/<owner>/` to `reference/` and update cross-links accordingly. When a centralized
+ref shrinks to 1–2 consumers (or its consumers turn out to be same-domain), migrate the
+other direction. Document the migration in the relevant phase's SUMMARY.md.
+
+### Phase 28.6 retrospective
+
+Phase 28.5 D-06 over-generalized by centralizing all extracted refs in `reference/`,
+including procedure refs read by exactly one skill. Phase 28.6 corrected this by migrating
+20 skill-private procedure refs back into their owning skill folders (D-01) and refreshing
+this section to endorse per-skill folders as the canonical placement for 1-consumer
+content (D-04). See
+`.planning/phases/28.6-skill-reference-co-location/CONTEXT.md` for the full discipline.
+
+Concrete example: a skill that lists 10 framework matrices inline (~150 lines) extracts
+the matrices to `reference/<framework>-matrices.md` (if 3+ skills will consume them) or
+`skills/<owner>/<framework>-matrices.md` (if only the owning skill reads them), then
+replaces the inline content with a one-sentence summary + cross-link. SKILL.md drops to
+~80 lines, the matrices stay discoverable, no institutional knowledge is lost.
 
 ## Validator usage
 

package/skills/apply-reflections/SKILL.md

@@ -52,7 +52,7 @@ Based on user choice:
 
 ### 4. Apply Logic by Proposal Type
 
-After the user chooses `a` (apply) or `e` (edit-then-apply), branch on the proposal's bracketed type tag and follow the per-type apply procedure in `./reference/apply-reflections-procedure.md` — one numbered procedure each for `[FRONTMATTER]`, `[REFERENCE]`, `[BUDGET]`, `[QUESTION]`, `[GLOBAL-SKILL]`. All branches end with `**Applied**: <date>` appended to the proposal block in the reflections file.
+After the user chooses `a` (apply) or `e` (edit-then-apply), branch on the proposal's bracketed type tag and follow the per-type apply procedure in `./apply-reflections-procedure.md` — one numbered procedure each for `[FRONTMATTER]`, `[REFERENCE]`, `[BUDGET]`, `[QUESTION]`, `[GLOBAL-SKILL]`. All branches end with `**Applied**: <date>` appended to the proposal block in the reflections file.
 
 ### 5. Summary
 

package/skills/cache-manager/SKILL.md

@@ -38,7 +38,7 @@ You are the deterministic cache-key computer and cache-manifest writer for the o
 
 ## Deterministic Input-Hash Algorithm
 
-The canonical reference implementation (single source of truth; `hooks/budget-enforcer.js` imports the same primitive via a shared helper) lives in `./reference/cache-policy.md#deterministic-input-hash-algorithm-layer-b` — it documents the JS implementation, the maintainer notes (sorted-unique paths, MISSING-file sentinel, agent-path bust behavior), the manifest shape, and TTL semantics in one place. Conform to the algorithm exactly so the hook and any orchestrator agree byte-for-byte.
+The canonical reference implementation (single source of truth; `hooks/budget-enforcer.js` imports the same primitive via a shared helper) lives in `./cache-policy.md#deterministic-input-hash-algorithm-layer-b` — it documents the JS implementation, the maintainer notes (sorted-unique paths, MISSING-file sentinel, agent-path bust behavior), the manifest shape, and TTL semantics in one place. Conform to the algorithm exactly so the hook and any orchestrator agree byte-for-byte.
 
 ## Integration Points
 
@@ -63,4 +63,4 @@ Per D-09:
 
 ## TTL Semantics
 
-Default `ttl_seconds` = `.design/budget.json.cache_ttl_seconds` = 3600s (1 hour) per D-10. `expires_at` is computed at write time and stored; readers do not recompute. Stale entries are lazily cleaned on read (no eager reaper in v1). Full TTL discussion: `./reference/cache-policy.md#ttl-semantics-layer-b`.
+Default `ttl_seconds` = `.design/budget.json.cache_ttl_seconds` = 3600s (1 hour) per D-10. `expires_at` is computed at write time and stored; readers do not recompute. Stale entries are lazily cleaned on read (no eager reaper in v1). Full TTL discussion: `./cache-policy.md#ttl-semantics-layer-b`.

package/skills/compare/SKILL.md

@@ -9,7 +9,7 @@ user-invocable: true
 
 Standalone delta command. Computes the difference between the scan baseline (`DESIGN.md`) and the verification result (`DESIGN-VERIFICATION.md`), and flags design drift for any regression not covered by an explicit task in `DESIGN-PLAN.md`. Writes one artifact: `.design/COMPARE-REPORT.md`.
 
-For the full step-by-step methodology (score parsing, set arithmetic for anti-patterns, drift-coverage map, screenshot-delta probe, and `COMPARE-REPORT.md` template), see `../../reference/compare-rubric.md`. For the cross-skill output discipline (artifact prefix, completion marker, MUST-NOT-write list, connection-probe pattern), see `../../reference/shared-preamble.md#output-contract-reminders` and `../../reference/shared-preamble.md#connection-handshake-summary`. For the underlying 0–10 category-scoring rubric the delta is computed against, see `../../reference/audit-scoring.md`.
+For the full step-by-step methodology (score parsing, set arithmetic for anti-patterns, drift-coverage map, screenshot-delta probe, and `COMPARE-REPORT.md` template), see `./compare-rubric.md`. For the cross-skill output discipline (artifact prefix, completion marker, MUST-NOT-write list, connection-probe pattern), see `../../reference/shared-preamble.md#output-contract-reminders` and `../../reference/shared-preamble.md#connection-handshake-summary`. For the underlying 0–10 category-scoring rubric the delta is computed against, see `../../reference/audit-scoring.md`.
 
 ---
 
@@ -45,13 +45,13 @@ Probe `preview` connection per `../../reference/shared-preamble.md#connection-ha
 
 ## Workflow
 
-1. **Parse Category Scores** — extract baseline + result score tables, normalize names, flag unmatched. Detail: `../../reference/compare-rubric.md#step-1--parse-category-scores`.
-2. **Compute Score Delta** — `delta = result - baseline`, classify (`improvement`/`no_change`/`regression`). Detail: `../../reference/compare-rubric.md#step-2--compute-score-delta-comp-03`.
-3. **Anti-Pattern Delta** — set arithmetic on baseline vs result anti-pattern sets (resolved / new / unchanged). Detail: `../../reference/compare-rubric.md#step-3--anti-pattern-delta`.
-4. **Must-Have Pass/Fail Change** — read `<must_haves>` from `DESIGN-CONTEXT.md`, status from `DESIGN-VERIFICATION.md`. Detail: `../../reference/compare-rubric.md#step-4--must-have-passfail-change`.
-5. **Design Drift Detection (COMP-04)** — build coverage map from `DESIGN-PLAN.md` `Type:` fields; for each `regression` not in coverage_map → emit `DRIFT: [category] ...`. Detail: `../../reference/compare-rubric.md#step-5--design-drift-detection-comp-04`.
-6. **Screenshot Delta (preview: available only)** — capture per-route screenshots to `.design/screenshots/{before,after}/<route>.png`. Detail: `../../reference/compare-rubric.md#step-5b--screenshot-delta-when-preview-available`.
-7. **Write `.design/COMPARE-REPORT.md`** — full template at `../../reference/compare-rubric.md#step-6--compare-reportmd-template`.
+1. **Parse Category Scores** — extract baseline + result score tables, normalize names, flag unmatched. Detail: `./compare-rubric.md#step-1--parse-category-scores`.
+2. **Compute Score Delta** — `delta = result - baseline`, classify (`improvement`/`no_change`/`regression`). Detail: `./compare-rubric.md#step-2--compute-score-delta-comp-03`.
+3. **Anti-Pattern Delta** — set arithmetic on baseline vs result anti-pattern sets (resolved / new / unchanged). Detail: `./compare-rubric.md#step-3--anti-pattern-delta`.
+4. **Must-Have Pass/Fail Change** — read `<must_haves>` from `DESIGN-CONTEXT.md`, status from `DESIGN-VERIFICATION.md`. Detail: `./compare-rubric.md#step-4--must-have-passfail-change`.
+5. **Design Drift Detection (COMP-04)** — build coverage map from `DESIGN-PLAN.md` `Type:` fields; for each `regression` not in coverage_map → emit `DRIFT: [category] ...`. Detail: `./compare-rubric.md#step-5--design-drift-detection-comp-04`.
+6. **Screenshot Delta (preview: available only)** — capture per-route screenshots to `.design/screenshots/{before,after}/<route>.png`. Detail: `./compare-rubric.md#step-5b--screenshot-delta-when-preview-available`.
+7. **Write `.design/COMPARE-REPORT.md`** — full template at `./compare-rubric.md#step-6--compare-reportmd-template`.
 
 ---
 

package/skills/connections/SKILL.md

@@ -12,7 +12,7 @@ Interactive onboarding for the 12 external integrations the pipeline supports. R
 
 Canonical per-connection specs live in `../../connections/<name>.md` (one file per integration). The capability matrix + probe-pattern spec live in `../../connections/connections.md`. This skill is the **user-facing front end** for those specs.
 
-For the 12 probe scripts (MCP + HTTP + CLI + file probes), bucket categorization, per-connection setup screen, auto-run eligibility matrix, value-prop one-liners, and STATE.md / config.json write contracts, see `../../reference/connections-onboarding.md`. For the cross-skill probe pattern + connection-handshake summary, see `../../reference/shared-preamble.md#connection-handshake-summary`. For the cross-skill output discipline, see `../../reference/shared-preamble.md#output-contract-reminders`.
+For the 12 probe scripts (MCP + HTTP + CLI + file probes), bucket categorization, per-connection setup screen, auto-run eligibility matrix, value-prop one-liners, and STATE.md / config.json write contracts, see `./connections-onboarding.md`. For the cross-skill probe pattern + connection-handshake summary, see `../../reference/shared-preamble.md#connection-handshake-summary`. For the cross-skill output discipline, see `../../reference/shared-preamble.md#output-contract-reminders`.
 
 ---
 
@@ -38,20 +38,20 @@ For the 12 probe scripts (MCP + HTTP + CLI + file probes), bucket categorization
 
 ## Workflow
 
-1. **Probe all 12 connections** — run every probe script per `../../reference/connections-onboarding.md#step-1--probe-all-12-connections`. MCP probes use `ToolSearch` first; HTTP / CLI / file probes follow non-MCP patterns. Merge results into `STATE.md <connections>` with the three-value schema (`available | unavailable | not_configured`) — never add new values.
-2. **Categorize + build summary** — bucket each probe result (available / recommended / optional / skipped / unavailable) using project-hint detection. Detail + recommendation mapping: `../../reference/connections-onboarding.md#step-2--bucket-categorization`.
-3. **Print summary table** — show buckets + value-prop one-liners (verbatim from `../../reference/connections-onboarding.md#step-3--summary-table`).
-4. **Route by mode** — `list` / `--auto` exits after summary; `<name>` jumps straight to Step 5; default mode opens an AskUserQuestion (configure recommended / pick one by one / configure all optional / re-check specific / exit). Routing detail: `../../reference/connections-onboarding.md#step-4--route-by-mode`.
-5. **Per-connection setup screen** — for each target: read `connections/<name>.md`, present the setup screen, AskUserQuestion (run now / copy-paste / skip / never ask). Auto-run only if reversible (see eligibility matrix). On success: append name to `connections_onboarding.pending_verification[]`. Detail: `../../reference/connections-onboarding.md#step-5--per-connection-setup-screen`.
-6. **Verification pass** — re-probe every name in `pending_verification[]`. Available → remove. `not_configured` → leave (needs session restart). `unavailable` → leave + note OAuth needed. Print "Setup complete" summary. Detail: `../../reference/connections-onboarding.md#step-6--verification-pass`.
+1. **Probe all 12 connections** — run every probe script per `./connections-onboarding.md#step-1--probe-all-12-connections`. MCP probes use `ToolSearch` first; HTTP / CLI / file probes follow non-MCP patterns. Merge results into `STATE.md <connections>` with the three-value schema (`available | unavailable | not_configured`) — never add new values.
+2. **Categorize + build summary** — bucket each probe result (available / recommended / optional / skipped / unavailable) using project-hint detection. Detail + recommendation mapping: `./connections-onboarding.md#step-2--bucket-categorization`.
+3. **Print summary table** — show buckets + value-prop one-liners (verbatim from `./connections-onboarding.md#step-3--summary-table`).
+4. **Route by mode** — `list` / `--auto` exits after summary; `<name>` jumps straight to Step 5; default mode opens an AskUserQuestion (configure recommended / pick one by one / configure all optional / re-check specific / exit). Routing detail: `./connections-onboarding.md#step-4--route-by-mode`.
+5. **Per-connection setup screen** — for each target: read `connections/<name>.md`, present the setup screen, AskUserQuestion (run now / copy-paste / skip / never ask). Auto-run only if reversible (see eligibility matrix). On success: append name to `connections_onboarding.pending_verification[]`. Detail: `./connections-onboarding.md#step-5--per-connection-setup-screen`.
+6. **Verification pass** — re-probe every name in `pending_verification[]`. Available → remove. `not_configured` → leave (needs session restart). `unavailable` → leave + note OAuth needed. Print "Setup complete" summary. Detail: `./connections-onboarding.md#step-6--verification-pass`.
 
-If `.design/config.json > connections_onboarding.pending_verification[]` is non-empty at entry → enter **resume flow**: run Step 6 immediately; if clean, exit; otherwise fall through to Step 3. Detail: `../../reference/connections-onboarding.md#resumability`.
+If `.design/config.json > connections_onboarding.pending_verification[]` is non-empty at entry → enter **resume flow**: run Step 6 immediately; if clean, exit; otherwise fall through to Step 3. Detail: `./connections-onboarding.md#resumability`.
 
 ---
 
 ## Do Not
 
-Per `../../reference/connections-onboarding.md#do-not`:
+Per `./connections-onboarding.md#do-not`:
 
 - Never run `npm install -g` globals automatically.
 - Never write to `~/.bashrc`, `~/.zshrc`, or shell RC files.

package/skills/darkmode/SKILL.md

@@ -9,7 +9,7 @@ user-invocable: true
 
 Standalone dark mode audit. Detects the project's dark mode architecture, runs architecture-specific checks across contrast, token completeness, anti-patterns, and meta properties, then writes a prioritized fix list to `.design/DARKMODE-AUDIT.md`.
 
-For the full step-by-step methodology (architecture-detection greps, WCAG contrast formula, anti-pattern grep snippets, meta-property checks, screenshot capture, and `DARKMODE-AUDIT.md` template), see `../../reference/darkmode-audit-procedure.md`. For the perceptual-contrast layer (APCA / WCAG 3 draft) sitting on top of WCAG 2.1 ratios, see `../../reference/contrast-advanced.md`. For OKLCH-based dark token-pair generation, see `../../reference/color-theory.md` §OKLCH. For the cross-skill output discipline + connection-probe pattern, see `../../reference/shared-preamble.md#output-contract-reminders` and `../../reference/shared-preamble.md#connection-handshake-summary`.
+For the full step-by-step methodology (architecture-detection greps, WCAG contrast formula, anti-pattern grep snippets, meta-property checks, screenshot capture, and `DARKMODE-AUDIT.md` template), see `./darkmode-audit-procedure.md`. For the perceptual-contrast layer (APCA / WCAG 3 draft) sitting on top of WCAG 2.1 ratios, see `../../reference/contrast-advanced.md`. For OKLCH-based dark token-pair generation, see `../../reference/color-theory.md` §OKLCH. For the cross-skill output discipline + connection-probe pattern, see `../../reference/shared-preamble.md#output-contract-reminders` and `../../reference/shared-preamble.md#connection-handshake-summary`.
 
 ---
 
@@ -39,13 +39,13 @@ Probe `preview` connection per `../../reference/shared-preamble.md#connection-ha
 
 ## Workflow
 
-1. **Architecture Detection (DARK-02)** — run three greps (CSS custom props / Tailwind `dark:` / JS class toggle), classify primary architecture or `Hybrid` or `None`. If `None`, abort. Detail: `../../reference/darkmode-audit-procedure.md#step-1-architecture-detection-dark-02`.
-2. **Contrast Audit (DARK-03)** — extract dark-context token pairs for the detected architecture, compute WCAG 2.1 ratios, flag failures at 4.5:1 (body) / 3:1 (large text + UI boundaries). Cross-check with APCA from `../../reference/contrast-advanced.md` for thin / large / colored text. Detail: `../../reference/darkmode-audit-procedure.md#step-2-contrast-audit-dark-03`.
-3. **Token Override Completeness (DARK-04)** — every light-mode color token must have a dark-mode override. Flag missing overrides → P1. Detail: `../../reference/darkmode-audit-procedure.md#step-3-token-override-completeness-dark-04`.
-4. **Dark-Specific Anti-Patterns (DARK-05)** — Images/SVGs without dark variant (P2), pure-black backgrounds in dark context = BAN-05 (P1), missing `@media (forced-colors)` (P2). Detail: `../../reference/darkmode-audit-procedure.md#step-4-dark-specific-anti-patterns-dark-05`.
-5. **Meta Property Check (DARK-06)** — `color-scheme` property + `prefers-color-scheme` query. Each absent → P2. Detail: `../../reference/darkmode-audit-procedure.md#step-5-meta-property-check-dark-06`.
-6. **Visual Rendering (preview: available only)** — capture light/dark screenshot pair to `.design/screenshots/darkmode/{light,dark}.png`. Detail: `../../reference/darkmode-audit-procedure.md#step-5b-dark-mode-rendering-screenshots-when-preview-available`.
-7. **Write `.design/DARKMODE-AUDIT.md`** — group flagged issues by priority (P0 → P1 → P2 → P3). Full template at `../../reference/darkmode-audit-procedure.md#step-6-darkmode-auditmd-template`.
+1. **Architecture Detection (DARK-02)** — run three greps (CSS custom props / Tailwind `dark:` / JS class toggle), classify primary architecture or `Hybrid` or `None`. If `None`, abort. Detail: `./darkmode-audit-procedure.md#step-1-architecture-detection-dark-02`.
+2. **Contrast Audit (DARK-03)** — extract dark-context token pairs for the detected architecture, compute WCAG 2.1 ratios, flag failures at 4.5:1 (body) / 3:1 (large text + UI boundaries). Cross-check with APCA from `../../reference/contrast-advanced.md` for thin / large / colored text. Detail: `./darkmode-audit-procedure.md#step-2-contrast-audit-dark-03`.
+3. **Token Override Completeness (DARK-04)** — every light-mode color token must have a dark-mode override. Flag missing overrides → P1. Detail: `./darkmode-audit-procedure.md#step-3-token-override-completeness-dark-04`.
+4. **Dark-Specific Anti-Patterns (DARK-05)** — Images/SVGs without dark variant (P2), pure-black backgrounds in dark context = BAN-05 (P1), missing `@media (forced-colors)` (P2). Detail: `./darkmode-audit-procedure.md#step-4-dark-specific-anti-patterns-dark-05`.
+5. **Meta Property Check (DARK-06)** — `color-scheme` property + `prefers-color-scheme` query. Each absent → P2. Detail: `./darkmode-audit-procedure.md#step-5-meta-property-check-dark-06`.
+6. **Visual Rendering (preview: available only)** — capture light/dark screenshot pair to `.design/screenshots/darkmode/{light,dark}.png`. Detail: `./darkmode-audit-procedure.md#step-5b-dark-mode-rendering-screenshots-when-preview-available`.
+7. **Write `.design/DARKMODE-AUDIT.md`** — group flagged issues by priority (P0 → P1 → P2 → P3). Full template at `./darkmode-audit-procedure.md#step-6-darkmode-auditmd-template`.
 
 ---
 

package/skills/debug/SKILL.md

@@ -7,15 +7,15 @@ tools: Read, Write, Grep, Glob, AskUserQuestion, Task
 
 # /gdd:debug
 
-Systematic, checkpoint-driven design debugger. Loads framing from `./../reference/debugger-philosophy.md` (five principles) and the feedback-loop construction catalog from `./../reference/debug-feedback-loops.md` (10 priority-ordered loop paths). Phase 1 builds the loop; Phase 2 generates hypotheses. Writes every step to `.design/DEBUG.md` so killed sessions can resume.
+Systematic, checkpoint-driven design debugger. Loads framing from `./../reference/debugger-philosophy.md` (five principles) and the feedback-loop construction catalog from `./debug-feedback-loops.md` (10 priority-ordered loop paths). Phase 1 builds the loop; Phase 2 generates hypotheses. Writes every step to `.design/DEBUG.md` so killed sessions can resume.
 
 ## Steps
 
-1. **Load philosophy + feedback-loop catalog**: Read `reference/debugger-philosophy.md` (five principles) and `./../reference/debug-feedback-loops.md` (10 construction paths; iterate-on-loop discipline). Keep both in mind for the entire session.
+1. **Load philosophy + feedback-loop catalog**: Read `reference/debugger-philosophy.md` (five principles) and `./debug-feedback-loops.md` (10 construction paths; iterate-on-loop discipline). Keep both in mind for the entire session.
 2. **Symptom**: If no symptom argument was passed, ask (AskUserQuestion): "What design symptom are you investigating? (observable only — 'cards look crowded', not 'padding is wrong')"
 3. **Resume check**: Read `.design/DEBUG.md` if it exists. If there is an open session with no `### Fix Proposal` block, ask: "Resume existing session '<symptom>' or start a new one?"
 4. **Ground truth load**: Read `.design/DESIGN-PLAN.md` (goals), `.design/STATE.md` `<decisions>` block (D-XX items), and any source files pointed at by the symptom.
-5. **Phase 1 — Build a feedback loop**: Before ANY hypothesizing, build a deterministic, fast, agent-runnable pass/fail signal that reproduces the symptom. See `./../reference/debug-feedback-loops.md` for the 10 construction paths in priority order (failing test > curl > CLI fixture > headless browser > trace replay > throwaway harness > fuzz > bisect > differential > HITL bash). Iterate on the loop itself (cache setup, narrow scope, pin time, seed RNG, isolate filesystem, freeze network) before iterating on the bug. For non-deterministic bugs: raise reproduction rate to at least 30%, not clean repro. **Do not proceed to Phase 2 (hypothesis generation) until you have a loop you believe in.**
+5. **Phase 1 — Build a feedback loop**: Before ANY hypothesizing, build a deterministic, fast, agent-runnable pass/fail signal that reproduces the symptom. See `./debug-feedback-loops.md` for the 10 construction paths in priority order (failing test > curl > CLI fixture > headless browser > trace replay > throwaway harness > fuzz > bisect > differential > HITL bash). Iterate on the loop itself (cache setup, narrow scope, pin time, seed RNG, isolate filesystem, freeze network) before iterating on the bug. For non-deterministic bugs: raise reproduction rate to at least 30%, not clean repro. **Do not proceed to Phase 2 (hypothesis generation) until you have a loop you believe in.**
 6. **Optional rendered-output check**: Use ToolSearch to see if Playwright/Preview MCP tools are available. If yes, capture rendered state. If no, fall back to code-only analysis.
 7. **Phase 2 — Investigation loop** (one hypothesis at a time) — for each step:
    - Form one hypothesis (one variable).

package/skills/design/SKILL.md

@@ -10,7 +10,7 @@ tools: Read, Write, Bash, Grep, Glob, Task, AskUserQuestion, mcp__gdd_state__get
 
 **Stage 4 of 5** in the get-design-done pipeline. Thin orchestrator. All design execution intelligence lives in `agents/design-executor.md`.
 
-Full procedure detail: `../../reference/design-procedure.md`.
+Full procedure detail: `./design-procedure.md`.
 
 ---
 
@@ -20,7 +20,7 @@ Full procedure detail: `../../reference/design-procedure.md`.
 2. `mcp__gdd_state__get` -> snapshot `state`; read `state.position.wave` for execution plan.
 3. Abort only if `.design/DESIGN-PLAN.md` is missing: "No plan found. Run `/get-design-done:plan` first."
 
-Detail: `../../reference/design-procedure.md` §Stage entry.
+Detail: `./design-procedure.md` §Stage entry.
 
 ---
 
@@ -30,7 +30,7 @@ Detail: `../../reference/design-procedure.md` §Stage entry.
 - `--parallel` -> `parallel_mode=true` (use worktree isolation for `Parallel: true` tasks).
 - **Directionally-open check** (skipped if `auto_mode`): scan DESIGN-PLAN.md for tasks whose criteria read "explore N directions" / "pick a visual approach" and suggest `/gdd:sketch` first.
 - **Project-local conventions**: include any `./.claude/skills/design-*-conventions.md` and `~/.claude/gdd/global-skills/*.md` in every executor's `<required_reading>` — global conventions inform but do not override project-local D-XX decisions.
-- **`.stories.tsx` stub**: after each new component file is created by the executor, emit a CSF stub alongside if `.storybook/` exists or `"storybook"` is in `package.json`, even with the dev server offline. Detail: `../../reference/design-procedure.md` §.stories.tsx Stub.
+- **`.stories.tsx` stub**: after each new component file is created by the executor, emit a CSF stub alongside if `.storybook/` exists or `"storybook"` is in `package.json`, even with the dev server offline. Detail: `./design-procedure.md` §.stories.tsx Stub.
 
 ---
 
@@ -49,7 +49,7 @@ For each wave in order:
 3. **Parallel batch** (when `parallel_mode=true` AND any `Parallel: true` tasks in wave): announce the partition, spawn all `Parallel: true` tasks via concurrent `Task("design-executor", ..., isolation: "worktree")` calls in ONE response, wait for all `## EXECUTION COMPLETE` markers, merge worktrees (non-overlapping `Touches:` guarantees no conflicts; surface any conflict to the user before continuing), then `update_progress` + `checkpoint`.
 4. **Sequential tail** (`Parallel: false` or `parallel_mode=false`): spawn one `design-executor` at a time (no worktree isolation), waiting for each `## EXECUTION COMPLETE` and emitting `update_progress` per task; `checkpoint` after the final task of the wave.
 
-Full executor prompts (parallel + sequential variants) and the merge-worktrees protocol: `../../reference/design-procedure.md` §Step 2.
+Full executor prompts (parallel + sequential variants) and the merge-worktrees protocol: `./design-procedure.md` §Step 2.
 
 ---
 
@@ -70,12 +70,12 @@ Check task-NN.md files for `status: deviation`. If found: `mcp__gdd_state__get`
 
 ## After Completion
 
-Print the `=== Design stage complete ===` summary (tasks complete/total, deviations, commits since stage start, next step `/get-design-done:verify`). Template: `../../reference/design-procedure.md` §After Completion.
+Print the `=== Design stage complete ===` summary (tasks complete/total, deviations, commits since stage start, next step `/get-design-done:verify`). Template: `./design-procedure.md` §After Completion.
 
 ---
 
 ## Figma Write Dispatch
 
-After all tasks finish, if STATE.md `<connections>` has `figma: available`, offer the user the figma-write opt-in prompt (modes: annotate / tokenize / mappings, with optional `--dry-run`). Spawn `design-figma-writer` with the selected mode on "yes"; skip silently on "no". NEVER auto-run without confirmation. Full prompt + dispatch logic: `../../reference/design-procedure.md` §Figma Write Dispatch.
+After all tasks finish, if STATE.md `<connections>` has `figma: available`, offer the user the figma-write opt-in prompt (modes: annotate / tokenize / mappings, with optional `--dry-run`). Spawn `design-figma-writer` with the selected mode on "yes"; skip silently on "no". NEVER auto-run without confirmation. Full prompt + dispatch logic: `./design-procedure.md` §Figma Write Dispatch.
 
 ## DESIGN COMPLETE