@hegemonart/get-design-done 1.39.2 → 1.39.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.39.2"
+    "version": "1.39.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.39.2",
+      "version": "1.39.5",
       "author": {
         "name": "hegemonart"
       },

package/.claude-plugin/plugin.json

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

package/CHANGELOG.md

@@ -4,6 +4,52 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.39.5] - 2026-06-01
+
+### Phase 39.5 — GDD Self-Migration Tooling
+
+GDD migrates *user* design systems (39.1) but had no systematic story for **its own** breaking
+changes — Phase 31.5 moved `scripts/lib/**` → `sdk/**` with ad-hoc shims. 39.5 formalizes it: a
+machine-readable deprecation registry, a version-aware reader, a `/gdd:migrate` skill, a post-update
+advisory, and two CI gates (a completeness check + a CHANGELOG Breaking-changes linter). **No new
+runtime dependency, no new egress** — two pure helpers + a docs/skill surface.
+
+### Breaking changes
+
+None. (This release *adds* the deprecation machinery; it removes nothing. The historical Phase 31.5 →
+`sdk/` removals it documents already shipped in v1.33.0.)
+
+### Added
+
+- **`reference/DEPRECATIONS.md`** — a `## Path migrations (machine-readable)` table
+  (`Since · Removed in · Old · New · Migration hint`) + status semantics, backfilled with the 10
+  verified Phase 31.5 → `sdk/` removals (all confirmed gone from the tree).
+- **`scripts/lib/deprecation-registry.cjs`** — pure, dep-free reader: `compareVersions`,
+  `parseDeprecations` (markdown-table parser), `classify` (pending/deprecated/removed by version),
+  `checkReference`.
+- **`skills/migrate/SKILL.md`** (`/gdd:migrate [--yes] [--dry-run]`) — scans a project's references for
+  paths deprecated/removed at the installed version and **previews a diff** before rewriting. Preview-first.
+- **`scripts/lint-changelog.cjs`** (`npm run lint:changelog`) — every `## [x.y.0]` minor at/after the
+  1.39.0 floor must declare a `### Breaking changes` section; historical minors are grandfathered.
+- **`test/suite/deprecation-completeness.test.cjs`** — the SC#4 gate: every `removed` entry's old path
+  is gone + its replacement exists; every `deprecated` entry still has a shim. No orphan entries.
+
+### Changed
+
+- **`skills/update/SKILL.md`** — a post-update step that reports deprecations crossing into
+  `deprecated`/`removed` over the upgrade window and points the user at `/gdd:migrate`.
+
+### Notes
+
+- **No new runtime dependency, no new egress.** `lint-changelog.cjs` is a maintainer/CI tool (not shipped).
+- 6-manifest lockstep at **v1.39.5** + `OFF_CADENCE_VERSIONS.add('1.39.5')` + the 32 live-pinned
+  `manifests-version.txt` baselines forward-propagated 1.39.2 → 1.39.5.
+- Inventory relock: skill-list 79 → 80 (+`migrate`, phase-20 + current), tarball golden 707 → 709
+  (+`deprecation-registry.cjs` + `skills/migrate/SKILL.md`). No agent/event/connection deltas. Root
+  `SKILL.md` command table += `migrate`.
+
+---
+
 ## [1.39.2] - 2026-06-01
 
 ### Phase 39.2 — Long-Horizon Cost Governance

package/README.md

@@ -186,6 +186,10 @@ When a design system ships a breaking major — shadcn/ui v1→v2, Tailwind v3
 
 GDD already tracks cost per task and per runtime — now it **forecasts** it, **caps** it at the project level, and shows whether the spend **shipped**. [`/gdd:budget`](skills/budget/SKILL.md) groups `costs.jsonl` by cycle and (via [`cost-forecaster`](agents/cost-forecaster.md) → the pure [`cost-forecast`](scripts/lib/budget/cost-forecast.cjs)) projects the next N cycles in **best / typical / worst** scenarios — "at the current rate you'll hit your $X project cap in Y cycles." A new `budget.json.project_cap_usd` adds a **project-level hard cap**: the [`budget-enforcer`](hooks/budget-enforcer.ts) hook warns at 50% + 80% and **gracefully halts** the next agent spawn at 100% (via the pure [`project-cap`](scripts/lib/budget/project-cap.cjs) classifier) — **disabled by default**, so existing users are unaffected. [`/gdd:roi`](skills/roi/SKILL.md) joins per-cycle cost with commits that shipped (survived ≥ 14 days) vs reverted into a cost-per-shipped-commit table ([`roi`](scripts/lib/budget/roi.cjs)). **No new runtime dependency, no new egress** — the hook only ever blocks, never spends.
 
+### GDD self-migration (v1.39.5)
+
+GDD migrates *your* design systems (above) — now it migrates **itself**. When GDD ships a breaking path change (like the Phase 31.5 `scripts/lib/**` → `sdk/**` reorg), a machine-readable registry in [`reference/DEPRECATIONS.md`](reference/DEPRECATIONS.md) records `Since · Removed in · Old · New · hint`. After an upgrade, [`/gdd:update`](skills/update/SKILL.md) flags anything that crossed into deprecated/removed, and [`/gdd:migrate`](skills/migrate/SKILL.md) rewrites your project's stale references — **previewing a diff first, never silent** — via the pure [`deprecation-registry`](scripts/lib/deprecation-registry.cjs). Two CI gates keep the system honest: a completeness check (every entry has a shim or a confirmed removal) and `lint-changelog` (every future minor must declare a `### Breaking changes` section). **No new runtime dependency, no new egress.**
+
 ### Previous releases
 
 - **v1.26.0** — Headless Model Resolver (per-runtime tier→model map, `resolved_models` router field, per-runtime price tables, `reasoning-class` runtime-neutral alias).

package/SKILL.md

@@ -104,6 +104,7 @@ Each stage produces artifacts in `.design/` inside the current project.
 | `rollout-status [<cycle>] [--all] [--stuck]` | `get-design-done:gdd-rollout-status` | Phase 38.5 — track a shipped cycle's production rollout (unrolled / staging-only / canary-N% / prod-100%) by reading the feature-flag service via `rollout-coordinator`; surfaces STUCK rollouts; feeds `design_arms` by deployed %. Read-only — never advances or rolls back |
 | `budget [--cycles N] [--scenario best\|typical\|worst]` | `get-design-done:gdd-budget` | Phase 39.2 — forecast design-cycle spend (best/typical/worst from telemetry variance) via `cost-forecaster`; "at the current rate you'll hit your $X project cap in Y cycles." Read-only — never spends, edits `budget.json`, or halts (the budget-enforcer hook halts) |
 | `roi [--since <date>] [--window-days 14]` | `get-design-done:gdd-roi` | Phase 39.2 — ROI table joining per-cycle cost with commits that shipped (survived ≥14d) vs reverted → cost-per-shipped-commit + stick rate. Read-only markdown report |
+| `migrate [--yes] [--dry-run]` | `get-design-done:gdd-migrate` | Phase 39.5 — migrate a project off GDD's own deprecated paths after an upgrade; reads `reference/DEPRECATIONS.md` via `deprecation-registry.cjs`, previews a diff, applies on confirm. Preview-first; never edits silently |
 
 ## Handoff Routing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.39.2",
+  "version": "1.39.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",
@@ -56,6 +56,7 @@
     "lint:md": "npx --yes markdownlint-cli2 \"**/*.md\" \"#node_modules\" \"#.planning\" \"#.claude\" \"#test/fixtures/baselines\"",
     "lint:links": "npx --yes lychee --no-progress --accept 200,206,403,429 \"**/*.md\" || true",
     "lint:agentskills": "node scripts/lint-agentskills-spec.cjs",
+    "lint:changelog": "node scripts/lint-changelog.cjs",
     "validate:schemas": "node --experimental-strip-types scripts/validate-schemas.ts",
     "validate:frontmatter": "node --experimental-strip-types scripts/validate-frontmatter.ts agents/",
     "detect:stale-refs": "node scripts/detect-stale-refs.cjs",

package/reference/DEPRECATIONS.md

@@ -39,3 +39,43 @@ the scanner pattern list in lockstep.
 
 The scanner excludes `.planning/`, `.claude/`, `.design/`, `node_modules/`,
 `test-fixture/`, and this file itself.
+
+## Path migrations (machine-readable)
+
+Phase 39.5 adds a machine-readable registry of **path** migrations — modules/files GDD moved or
+removed. `scripts/lib/deprecation-registry.cjs` parses the table below; `/gdd:migrate` consults it to
+help users update local references; `test/suite/deprecation-completeness.test.cjs` asserts every row
+is honest (a `removed` row's `Old` path must be gone from the tree; a `deprecated` row's `Old` path
+must still carry a shim).
+
+### Status semantics
+
+A row's status is derived from the running plugin version `v`:
+
+- **pending** — `v` < `Since` (deprecation announced for a future version; rare).
+- **deprecated** — `Since` ≤ `v` < `Removed in` (the old path still works via a shim; update at leisure).
+- **removed** — `v` ≥ `Removed in` (the old path is gone; you MUST use the new path).
+
+**Default shim lifetime is one minor version** (the Phase 31.5 precedent): a path deprecated in `x.y.z`
+is removed in the next minor `x.(y+1).0`. The `Removed in` column is authoritative per row.
+
+### Table
+
+Columns: `Since` (version the move shipped) · `Removed in` (version the old path stops working;
+blank = still shimmed) · `Old` (pre-move path) · `New` (current path) · `Migration hint`.
+
+| Since | Removed in | Old | New | Migration hint |
+|---|---|---|---|---|
+| 1.31.5 | 1.33.0 | `scripts/lib/cli` | `sdk/cli` | Import the CLI barrel from `sdk/cli` instead of `scripts/lib/cli`. |
+| 1.31.5 | 1.33.0 | `scripts/lib/event-stream` | `sdk/event-stream` | Import the event-stream barrel from `sdk/event-stream`. |
+| 1.31.5 | 1.33.0 | `scripts/lib/gdd-state` | `sdk/state` | Import the STATE primitives from `sdk/state`. |
+| 1.31.5 | 1.33.0 | `scripts/lib/gdd-errors` | `sdk/errors` | Import the error types from `sdk/errors`. |
+| 1.31.5 | 1.33.0 | `scripts/lib/error-classifier.cjs` | `sdk/primitives/error-classifier.cjs` | Require `sdk/primitives/error-classifier.cjs`. |
+| 1.31.5 | 1.33.0 | `scripts/lib/iteration-budget.cjs` | `sdk/primitives/iteration-budget.cjs` | Require `sdk/primitives/iteration-budget.cjs`. |
+| 1.31.5 | 1.33.0 | `scripts/lib/jittered-backoff.cjs` | `sdk/primitives/jittered-backoff.cjs` | Require `sdk/primitives/jittered-backoff.cjs`. |
+| 1.31.5 | 1.33.0 | `scripts/lib/lockfile.cjs` | `sdk/primitives/lockfile.cjs` | Require `sdk/primitives/lockfile.cjs`. |
+| 1.31.5 | 1.33.0 | `scripts/mcp-servers/gdd-state/server.ts` | `sdk/mcp/gdd-state/server.ts` | Point the MCP server config at `sdk/mcp/gdd-state/server.ts`. |
+| 1.31.5 | 1.33.0 | `scripts/mcp-servers/gdd-mcp/server.ts` | `sdk/mcp/gdd-mcp/server.ts` | Point the MCP server config at `sdk/mcp/gdd-mcp/server.ts`. |
+
+All ten rows are **removed** as of the current release (the Phase 31.5 → `sdk/` reorg; shims removed
+in v1.33.0). The completeness gate confirms none of the `Old` paths remain in the tree.

package/scripts/lib/deprecation-registry.cjs

@@ -0,0 +1,99 @@
+'use strict';
+// Phase 39.5 — deprecation-registry.cjs — PURE, dep-free reader for GDD's own path-migration registry.
+//
+// The canonical registry is the `## Path migrations (machine-readable)` table in
+// reference/DEPRECATIONS.md. This module parses that table and derives each entry's status against a
+// running plugin version, so /gdd:migrate, the /gdd:update advisory, and the completeness gate all
+// share one version-logic core. It reads NO files itself (callers pass the markdown text) — so it is
+// trivially unit-testable.
+//
+// No `require` — pure. Deterministic.
+
+/**
+ * Compare two dotted-numeric versions. Tolerant of decimals/patch (1.39, 1.39.2, 1.39.5).
+ * Missing components are treated as 0. Non-numeric components compare as 0.
+ * @returns -1 if a<b, 0 if equal, 1 if a>b
+ */
+function compareVersions(a, b) {
+  const pa = String(a).split('.').map((x) => parseInt(x, 10) || 0);
+  const pb = String(b).split('.').map((x) => parseInt(x, 10) || 0);
+  const n = Math.max(pa.length, pb.length);
+  for (let i = 0; i < n; i++) {
+    const da = pa[i] || 0;
+    const db = pb[i] || 0;
+    if (da < db) return -1;
+    if (da > db) return 1;
+  }
+  return 0;
+}
+
+/** Strip surrounding whitespace + a single pair of backticks from a table cell. */
+function cell(s) {
+  return String(s).trim().replace(/^`(.*)`$/, '$1').trim();
+}
+
+/**
+ * Parse the path-migrations table out of reference/DEPRECATIONS.md text.
+ * Finds the header row containing Since / Removed in / Old / New, skips the `|---|` separator, and
+ * reads pipe-delimited data rows until a non-table line. Returns [] when the table is absent.
+ * @returns {Array<{since, removedIn, old, new, hint}>}
+ */
+function parseDeprecations(mdText) {
+  const lines = String(mdText).replace(/\r\n/g, '\n').split('\n');
+  const entries = [];
+  let inTable = false;
+  for (const line of lines) {
+    const isRow = /^\s*\|.*\|\s*$/.test(line);
+    if (!inTable) {
+      if (isRow && /\bSince\b/i.test(line) && /Removed in/i.test(line) && /\bOld\b/i.test(line) && /\bNew\b/i.test(line)) {
+        inTable = true; // header found; the next line is the separator
+      }
+      continue;
+    }
+    if (!isRow) { inTable = false; continue; } // table ended
+    const cells = line.split('|').slice(1, -1).map(cell);
+    if (cells.length < 5) continue;
+    if (/^-+$/.test(cells[0].replace(/\s/g, ''))) continue; // separator row
+    if (/^since$/i.test(cells[0])) continue; // a repeated header, ignore
+    entries.push({ since: cells[0], removedIn: cells[1], old: cells[2], new: cells[3], hint: cells[4] });
+  }
+  return entries;
+}
+
+/**
+ * Status of an entry at `currentVersion`:
+ *   pending    — current < since
+ *   deprecated — since <= current < removedIn (or removedIn blank ⇒ never 'removed')
+ *   removed    — current >= removedIn
+ */
+function classify(entry, currentVersion) {
+  if (!entry || !entry.since) throw new Error('deprecation-registry: entry needs a `since` version');
+  if (compareVersions(currentVersion, entry.since) < 0) return 'pending';
+  if (entry.removedIn && String(entry.removedIn).trim() && compareVersions(currentVersion, entry.removedIn) >= 0) {
+    return 'removed';
+  }
+  return 'deprecated';
+}
+
+/**
+ * Look up a reference (an old path/name) against the registry at currentVersion.
+ * @returns {{entry, status, message} | null}  null when `ref` is not a known deprecated path.
+ */
+function checkReference(entries, ref, currentVersion) {
+  if (!Array.isArray(entries)) throw new Error('deprecation-registry: entries must be an array');
+  const r = cell(ref);
+  const entry = entries.find((e) => e.old === r);
+  if (!entry) return null;
+  const status = classify(entry, currentVersion);
+  let message;
+  if (status === 'removed') {
+    message = `${entry.old} was removed in v${entry.removedIn}; use ${entry.new}. ${entry.hint}`;
+  } else if (status === 'deprecated') {
+    message = `${entry.old} is deprecated since v${entry.since} (removed in v${entry.removedIn}); use ${entry.new}. ${entry.hint}`;
+  } else {
+    message = `${entry.old} will be deprecated in v${entry.since}; the replacement is ${entry.new}.`;
+  }
+  return { entry, status, message };
+}
+
+module.exports = { compareVersions, parseDeprecations, classify, checkReference };

package/skills/migrate/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: gdd-migrate
+description: "Migrates a project off GDD's own deprecated paths after an upgrade. Reads the machine-readable registry in reference/DEPRECATIONS.md (via scripts/lib/deprecation-registry.cjs), scans the project's .design/config.json + any local skill/agent references for paths that are now deprecated or removed at the installed version, and PREVIEWS a diff before changing anything. Interactive by default (confirm per change); --yes auto-applies; --dry-run previews only. Read-first, never silent. Use after /gdd:update flags a breaking change."
+argument-hint: "[--yes] [--dry-run]"
+user-invocable: true
+tools: Read, Write, Bash, Grep, Glob
+---
+
+# /gdd:migrate
+
+Closes the GDD-on-GDD gap: when GDD moves or removes its own paths (e.g. the Phase 31.5
+`scripts/lib/**` → `sdk/**` reorg), a project that referenced the old paths needs updating. This skill
+consults the deprecation registry, finds the stale references **in this project**, and rewrites them —
+**after showing you the diff**. It never edits silently. Contract: `../../reference/DEPRECATIONS.md`.
+
+## Invocation
+
+| Command | Behavior |
+|---|---|
+| `/gdd:migrate` | Scan + preview every applicable migration, then confirm each before applying. |
+| `/gdd:migrate --dry-run` | Preview only — print the diff, change nothing. |
+| `/gdd:migrate --yes` | Apply every applicable migration without the per-change prompt (still prints what changed). |
+
+## Steps
+
+1. **Resolve the installed version** from `.claude-plugin/plugin.json` (`version`).
+2. **Load the registry.** Parse `reference/DEPRECATIONS.md` with the pure helper:
+
+   ```bash
+   node -e '
+     const fs = require("fs");
+     const dr = require("./scripts/lib/deprecation-registry.cjs");
+     const entries = dr.parseDeprecations(fs.readFileSync("reference/DEPRECATIONS.md","utf8"));
+     const version = require("./.claude-plugin/plugin.json").version;
+     // Only entries that are deprecated/removed at the installed version are actionable.
+     const actionable = entries.filter(e => dr.classify(e, version) !== "pending");
+     console.log(JSON.stringify({ version, actionable }));
+   '
+   ```
+
+3. **Scan the project** for each actionable entry's `Old` path:
+   - `.design/config.json` (string values referencing an old path),
+   - project-local skill/agent references (`grep` the repo, excluding `.git/`, `node_modules/`, and
+     GDD's own `reference/DEPRECATIONS.md`),
+   - any `require(...)`/import of a removed SDK path.
+   For a code rewrite, scaffold the edit with `scripts/lib/migration/codemod-gen.cjs` (Phase 39.1) —
+   you emit the change as a reviewable patch, you do not run a codemod engine.
+4. **Preview.** Print a unified-diff-style preview per file: `Old → New`, the registry status
+   (`deprecated` vs `removed`), and the migration hint. If `--dry-run`, stop here.
+5. **Confirm + apply.** Without `--yes`, ask per change. With `--yes`, apply all. Use `Write` to make
+   the edits; never touch a file the user didn't consent to.
+6. **Report.** Summarize: files changed, references rewritten, and any `removed`-status reference that
+   still has no replacement wired (flag it loudly — that one breaks at the installed version).
+
+## Boundaries
+
+- **Preview-first.** Nothing changes before you've shown the diff (or `--yes` was passed).
+- Migrates **this project's references** to GDD paths — it does not rewrite GDD's own source, and it
+  never performs a downgrade (reverse migrations are out of scope).
+- Read the registry; never invent a migration that isn't in `reference/DEPRECATIONS.md`.
+
+## Record
+
+Print a `## Migration summary` (version, actionable entries, files changed, unresolved `removed`
+references) and append one JSONL line to `.design/intel/insights.jsonl` recording the migration run.
+Close with:
+
+```
+## MIGRATE COMPLETE
+```

package/skills/update/SKILL.md

@@ -23,6 +23,24 @@ Updates the `get-design-done` plugin to the latest release (or a specific tag),
 
    > Run `/gdd:reapply-patches` if you have customized any `reference/` files to restore your modifications.
 
+7.5. **Deprecation advisory** (Phase 39.5) — load the path-migration registry and report anything that
+   crossed into `deprecated` or `removed` over the `[prevVersion → currentVersion]` window:
+
+   ```bash
+   node -e '
+     const fs = require("fs");
+     const dr = require("./scripts/lib/deprecation-registry.cjs");
+     const entries = dr.parseDeprecations(fs.readFileSync("reference/DEPRECATIONS.md","utf8"));
+     const crossed = entries.filter(e =>
+       dr.classify(e, currentVersion) !== "pending" &&
+       (prevVersion == null || dr.classify(e, prevVersion) !== dr.classify(e, currentVersion)));
+     console.log(JSON.stringify(crossed));
+   '
+   ```
+
+   If any entry crossed, print a `## Deprecations in this update` list (old → new + status) and point
+   the user at **`/gdd:migrate`** to rewrite their local references. If none crossed, say nothing.
+
 8. Print the new version and the changelog URL (`https://github.com/hegemonart/get-design-done/releases`).
 
 ## Output