@hegemonart/get-design-done 1.39.1 → 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.1"
+    "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.1",
+      "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.1",
+  "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,82 @@ 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
+
+Closes the split Phase 39 (39.1 shipped DS migration). Phase 10.1 per-task caps + Phase 26 per-runtime telemetry track *cost* — none **forecast** it, cap it at the *project* level, or show whether the spend actually *shipped* anything. 39.2 adds a per-cycle spend **forecast**, a **`project_cap`** hard-halt, and an **ROI dashboard**. **No new runtime dependency, no new egress** — three pure helpers + an additive, disabled-by-default branch on the existing budget-enforcer hook.
+
+### Added
+
+- **`scripts/lib/budget/cost-forecast.cjs`** — pure, dep-free per-cycle forecast: `forecast()` (best/typical/worst from the mean ± k·σ of historical per-cycle rates) + `cyclesToCap()` ("hit your cap in Y cycles"). Deterministic.
+- **`scripts/lib/budget/roi.cjs`** — pure ROI join: `computeRoi()` (per-cycle cost ⋈ shipped/reverted commits → cost-per-shipped-commit + stick rate) + `roiTableMarkdown()`.
+- **`scripts/lib/budget/project-cap.cjs`** — pure cap classifier: `classifyProjectBudget(spend, cap)` → `ok`/`warn-50`/`warn-80`/`halt`; **disabled when `cap ≤ 0`** (the non-breaking default).
+- **`agents/cost-forecaster.md`** — groups `costs.jsonl` by cycle, runs the model, supports `--scenario best|typical|worst`, emits a `budget_forecast` event. Report-only (sonnet, size_budget M).
+- **`skills/budget/SKILL.md`** (`/gdd:budget [--cycles N] [--scenario …]`) — forecast + "at the current rate you'll hit your $X project cap in Y cycles."
+- **`skills/roi/SKILL.md`** (`/gdd:roi [--since <date>] [--window-days 14]`) — the ROI table; "shipped" = a commit surviving ≥ 14 days (catches revert-after-bug-discovery).
+- **`reference/cost-governance.md`** — the contract (forecast model, `project_cap` semantics, ROI signal, events). Registered.
+
+### Changed
+
+- **`hooks/budget-enforcer.ts`** — an **additive** `project_cap` branch (delegates the threshold math to `project-cap.cjs`): warns at 50% + 80%, hard-halts at 100% under `enforce`. **Disabled by default** (`project_cap_usd: 0`) so existing users see zero behavior change. **Graceful** — it blocks the *next* PreToolUse:Agent spawn, letting the current stage finish.
+- **`reference/schemas/budget.schema.json`** — + `project_cap_usd` (≥ 0; 0/absent = disabled) + `project_cap_enforcement_mode` (enforce|warn|log).
+- **`reference/schemas/events.schema.json`** — free-form `type` seed += `budget_forecast` / `project_cap_warning` / `project_cap_halt` (schema-seed only; `KNOWN_EVENT_TYPES` count unchanged).
+
+### Notes
+
+- **No new runtime dependency, no new egress** — three pure text/arithmetic helpers + a local `package.json`/`costs.jsonl` read; the hook only ever *blocks*, never spends.
+- 6-manifest lockstep at **v1.39.2** + `OFF_CADENCE_VERSIONS.add('1.39.2')` + the 31 live-pinned `manifests-version.txt` baselines forward-propagated 1.39.1 → 1.39.2.
+- Inventory relock: registry-diff 157 → 158 (+`cost-governance`), skill-list 77 → 79 (+`budget`, +`roi`), agent-list +`cost-forecaster` + both frontmatter-snapshots, event-schema-snapshot sha256 re-locked (the seed-list edit, LF-normalized), tarball golden 700 → 707 (+7). Root `SKILL.md` command table += `budget` + `roi`.
+
+---
+
 ## [1.39.1] - 2026-06-01
 
 ### Phase 39.1 — DS Migration Workflows

package/README.md

@@ -182,6 +182,14 @@ GDD now tracks a design past "PR merged" to **actually live**. [`/gdd:rollout-st
 
 When a design system ships a breaking major — shadcn/ui v1→v2, Tailwind v3→v4, MUI v5→v6, or the Material 2/3 token rename — GDD detects the skew from the in-repo `package.json`, consults a curated rule library ([`reference/migrations/`](reference/migrations/)), and produces an **impact-scored, proposal-only** migration plan via [`ds-migration-planner`](agents/ds-migration-planner.md). Each affected component is scored by visual-delta × usage × tests-affected, and the planner emits codemod scaffolds to `.design/migration/` through the pure [`codemod-gen`](scripts/lib/migration/codemod-gen.cjs) — which produces jscodeshift/ast-grep template **text only** (it never imports or runs a codemod engine). [`design-verifier`](agents/design-verifier.md) then treats an in-flight migration as a contract: visual-diff within threshold, component API surface unchanged, tests green, and an unmigrated high-impact rule is a gap. **Proposal-only, no new runtime dependency, no new egress.**
 
+### Long-horizon cost governance (v1.39.2)
+
+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

@@ -102,6 +102,9 @@ Each stage produces artifacts in `.design/` inside the current project.
 | `export <cycle> --format html\|pdf\|notion [--pseudonymize] [--pr]` | `get-design-done:gdd-export` | Phase 35.5 — package a finished cycle's design output into a stakeholder-shareable artifact (self-contained HTML / Paged.js-print PDF / Notion page); redacts always, `--pseudonymize` masks identity for external sharing, `--pr` posts the HTML preview via pr-commenter |
 | `bootstrap-ds [--primary <color>] [--secondary <color>] [--tone <tags>] [--framework <t>]` | `get-design-done:gdd-bootstrap-ds` | Phase 37.2 — bootstrap a design system for a GREENFIELD project (no DS): brand input → OKLCH token system (color tints + modular type + 4pt/8pt spacing + radius/motion) in 3 variants to pick, then button/input/card proof scaffolding via `ds-generator` |
 | `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/agents/cost-forecaster.md

@@ -0,0 +1,91 @@
+---
+name: cost-forecaster
+description: Forecasts GDD spend over the next N design cycles. Reads .design/telemetry/costs.jsonl (grouping est_cost_usd by cycle) plus the configured .design/budget.json caps, runs the pure scripts/lib/budget/cost-forecast.cjs model (best/typical/worst from the variance of historical per-cycle rates), and reports "at the current rate you'll hit your project_cap in Y cycles." Supports --scenario best|typical|worst. Report-only — it never writes budget.json, never spends, never halts (the budget-enforcer hook halts). Spawned by /gdd:budget.
+tools: Read, Bash, Grep, Glob
+color: green
+default-tier: sonnet
+tier-rationale: "Groups a JSONL ledger by cycle and runs a pure projection helper, then narrates the result; bounded arithmetic + reporting, no design judgment — sonnet-tier."
+size_budget: M
+size_budget_rationale: "Honest tier sized to the ~95-line body. DELEGATES the projection math to scripts/lib/budget/cost-forecast.cjs and the contract to reference/cost-governance.md — the rollout-coordinator → rollout-status.cjs precedent."
+parallel-safe: false
+typical-duration-seconds: 30
+reads-only: true
+required_reading:
+  - "reference/cost-governance.md"
+writes:
+  - ".design/telemetry/events.jsonl (a budget_forecast event only — append, no mutation)"
+---
+
+# cost-forecaster
+
+You forecast GDD's design-cycle spend so the user sees a cost trajectory **before** the bill arrives.
+You are **report-only**: you read telemetry, run a pure model, and narrate. You never edit
+`budget.json`, never spend, and never block a spawn — the Phase 25 budget-enforcer hook is the only
+thing that halts.
+
+**Read `reference/cost-governance.md` first** — it is the contract for the model, the scenarios, and
+the `project_cap` semantics.
+
+## Inputs
+
+- **`.design/telemetry/costs.jsonl`** — one row per agent spawn: `{ ts, agent, tier, est_cost_usd,
+  cycle, phase, ... }`. The **`cycle`** field is the grouping key.
+- **`.design/budget.json`** — `project_cap_usd` (the ceiling to forecast against; `0`/absent ⇒ no
+  project cap configured, so report the trajectory without a "cycles to cap" line).
+- **`--scenario best|typical|worst`** (default `typical`) and **`--cycles N`** (default `5`).
+
+## Procedure
+
+1. **Group spend by cycle.** Read `costs.jsonl`; sum `est_cost_usd` per distinct `cycle` value, in
+   chronological order. This yields the array of per-cycle USD totals. If there are 0 cycles, say so
+   and stop (nothing to forecast).
+2. **Run the model.** Call the pure helper — do the math in the lib, never by hand:
+
+   ```bash
+   node -e '
+     const { forecast, cyclesToCap } = require("./scripts/lib/budget/cost-forecast.cjs");
+     const perCycle = JSON.parse(process.argv[1]);   // e.g. [10.2, 12.0, 8.4]
+     const f = forecast(perCycle, { nCycles: Number(process.argv[2]||5), scenario: process.argv[3]||"typical" });
+     const cap = Number(process.argv[4]||0);
+     const toCap = cap > 0 ? cyclesToCap(perCycle.reduce((a,b)=>a+b,0), cap, f.perCycle) : null;
+     console.log(JSON.stringify({ ...f, toCap }));
+   ' "$PER_CYCLE_JSON" "$N" "$SCENARIO" "$PROJECT_CAP"
+   ```
+
+3. **Report.** Print a short markdown summary:
+   - the chosen scenario + its per-cycle rate, and the best/typical/worst band (`low`/`high`);
+   - the projected total over the next N cycles;
+   - if `project_cap_usd > 0`: **"at the `<scenario>` rate (~$X/cycle) you'll reach your
+     $`<cap>` project cap in `<toCap>` cycles"** (or "never, spend is trending flat/down" when
+     `toCap` is `Infinity`).
+4. **Emit one event.** Append a `budget_forecast` event to `.design/telemetry/events.jsonl` with
+   payload `{ scenario, perCycle, projectedTotal, cyclesToCap }` (PII-free). Append only — never
+   rewrite the stream.
+
+## Scenarios (from `cost-forecast.cjs`, D-05)
+
+| `--scenario` | per-cycle rate | reads as |
+|---|---|---|
+| `best` | `max(0, mean − k·σ)` | spend trending down / favorable variance |
+| `typical` | `mean` | steady state (default) |
+| `worst` | `mean + k·σ` | spend trending up / unfavorable variance |
+
+`k = 1`. The projection is linear on the chosen rate. Always show the band, not just the point —
+a wide best↔worst gap is itself the signal that spend is volatile.
+
+## Record
+
+At run-end, print a `## Cost forecast` summary — the scenario, the per-cycle rate + band, the
+projected next-N-cycle total, and the cycles-to-cap line (when a `project_cap_usd` is set). Then
+append one JSONL line to `.design/intel/insights.jsonl` (per `reference/schemas/insight-line.schema.json`)
+recording the forecast `{ scenario, perCycle, projectedTotal, cyclesToCap }`. Close with:
+
+```
+## COST FORECAST COMPLETE
+```
+
+## Boundaries
+
+- Forecast is **cycle-scoped**, never per-agent-call.
+- You **report**; you do not act. Setting or raising `project_cap_usd` is the user's call.
+- No network. No external services. Pure local telemetry + a pure helper.

package/hooks/budget-enforcer.ts

@@ -207,6 +207,27 @@ const tierResolverOpenRouter = nodeRequire(
   '../scripts/lib/tier-resolver-openrouter.cjs',
 ) as TierResolverOpenRouterModule;
 
+// Phase 39.2 D-04: project-level cap classifier (pure). Keeping the threshold
+// math in scripts/lib/budget/project-cap.cjs (out of this hook) mirrors how the
+// hook already delegates cost computation to scripts/lib/budget-enforcer.cjs,
+// and makes the 50/80/100 thresholds unit-testable. The hook only reads the
+// running project spend and asks this module what to do.
+interface ProjectCapClassification {
+  enabled: boolean;
+  pct: number;
+  level: 'ok' | 'warn-50' | 'warn-80' | 'halt';
+  cap: number;
+  spend: number;
+}
+interface ProjectCapModule {
+  classifyProjectBudget(spendUsd: number, capUsd: number): ProjectCapClassification;
+  shouldHalt(c: ProjectCapClassification | null, enforcementMode: string): boolean;
+  capMessage(c: ProjectCapClassification | null): string | null;
+}
+const projectCap = nodeRequire(
+  '../scripts/lib/budget/project-cap.cjs',
+) as ProjectCapModule;
+
 /**
  * Plan 33.6-03 (SC#6 opt-in). OpenRouter is consulted ONLY when the user opts
  * in — either `.design/config.json#openrouter_enabled === true` OR
@@ -380,6 +401,15 @@ const PHASE_TOTALS_PATH = join(
   'telemetry',
   'phase-totals.json',
 );
+// Phase 39.2 D-04: optional fast-path for the running project spend, mirroring
+// PHASE_TOTALS_PATH. When absent the hook replays costs.jsonl (the project cap
+// is opt-in, so this replay only happens for users who set project_cap_usd).
+const PROJECT_TOTALS_PATH = join(
+  process.cwd(),
+  '.design',
+  'telemetry',
+  'project-totals.json',
+);
 const STATE_PATH = join(process.cwd(), '.design', 'STATE.md');
 
 /** Defaults per D-12 — mirror scripts/bootstrap.sh budget.json bootstrap. */
@@ -392,6 +422,7 @@ const BUDGET_DEFAULTS: Required<
     | 'auto_downgrade_on_cap'
     | 'cache_ttl_seconds'
     | 'enforcement_mode'
+    | 'project_cap_usd'
   >
 > = {
   per_task_cap_usd: 2.0,
@@ -400,6 +431,11 @@ const BUDGET_DEFAULTS: Required<
   auto_downgrade_on_cap: true,
   cache_ttl_seconds: 3600,
   enforcement_mode: 'enforce',
+  // Phase 39.2 D-04: project-level cap is DISABLED by default (0). Existing
+  // users — who have no project_cap_usd in budget.json — see zero behavior
+  // change. project_cap_enforcement_mode stays optional and falls back to
+  // enforcement_mode at the use-site.
+  project_cap_usd: 0,
 };
 
 /**
@@ -504,6 +540,40 @@ export function currentPhaseSpend(phase: string): number {
   return sum;
 }
 
+// ── cumulative project spend (Phase 39.2 D-04) ───────────────────────────────
+
+/**
+ * Total project spend = sum of est_cost_usd across the WHOLE costs.jsonl ledger.
+ * Fast path: a `project-totals.json` (`{ total: number }`, written by the
+ * aggregator) mirrors the WR-02 phase-totals optimization. Falls back to a full
+ * ledger replay otherwise. Returns 0 on any error. Only ever consulted when
+ * project_cap_usd > 0, so the replay cost is paid only by opt-in users.
+ */
+export function currentProjectSpend(): number {
+  if (existsSync(PROJECT_TOTALS_PATH)) {
+    try {
+      const data = JSON.parse(readFileSync(PROJECT_TOTALS_PATH, 'utf8')) as { total?: number };
+      return Number(data.total ?? 0);
+    } catch {
+      // fall through to replay
+    }
+  }
+  if (!existsSync(TELEMETRY_PATH)) return 0;
+  const lines = readFileSync(TELEMETRY_PATH, 'utf8')
+    .split(/\r?\n/)
+    .filter(Boolean);
+  let sum = 0;
+  for (const line of lines) {
+    try {
+      const row = JSON.parse(line) as { est_cost_usd?: number };
+      sum += Number(row.est_cost_usd ?? 0);
+    } catch {
+      // tolerant — skip malformed lines
+    }
+  }
+  return sum;
+}
+
 // ── cycle + phase reader (STATE.md frontmatter) ─────────────────────────────
 
 /**
@@ -985,6 +1055,82 @@ export async function main(): Promise<void> {
   const estCost = Number(toolInput._est_cost_usd ?? 0);
   const phaseSpend = currentPhaseSpend(phase);
 
+  // ── Phase 39.2 D-04: project-level cap ─────────────────────────────────────
+  //
+  // Independent of enforcement_mode: the 50%/80% warnings + the 100% halt are
+  // governed by project_cap_enforcement_mode (falling back to enforcement_mode).
+  // No-op when project_cap_usd <= 0 (the opt-in default), so existing users see
+  // zero change. Checked here, before the per-task/per-phase branches, so a
+  // project-level breach halts the NEXT spawn regardless of the per-scope caps —
+  // the graceful halt (the current stage's in-flight spawns already ran).
+  if (budget.project_cap_usd > 0) {
+    const projectSpend = currentProjectSpend();
+    const projClass = projectCap.classifyProjectBudget(
+      projectSpend + estCost,
+      budget.project_cap_usd,
+    );
+    const projMode = budget.project_cap_enforcement_mode ?? budget.enforcement_mode;
+    if (projClass.level === 'warn-50' || projClass.level === 'warn-80') {
+      try {
+        appendEvent({
+          type: 'project_cap_warning',
+          timestamp: new Date().toISOString(),
+          sessionId: getSessionId(),
+          ...(cycle !== undefined && cycle !== 'unknown' ? { cycle } : {}),
+          payload: {
+            pct: projClass.pct,
+            spend: projClass.spend,
+            cap: projClass.cap,
+            level: projClass.level,
+          },
+        } as unknown as HookFiredEvent);
+      } catch {
+        // fail-open — event-stream errors never block the hook.
+      }
+      process.stderr.write(`gdd-budget-enforcer WARN: ${projectCap.capMessage(projClass)}\n`);
+    } else if (projClass.level === 'halt') {
+      try {
+        appendEvent({
+          type: 'project_cap_halt',
+          timestamp: new Date().toISOString(),
+          sessionId: getSessionId(),
+          ...(cycle !== undefined && cycle !== 'unknown' ? { cycle } : {}),
+          payload: {
+            pct: projClass.pct,
+            spend: projClass.spend,
+            cap: projClass.cap,
+            enforcementMode: projMode,
+          },
+        } as unknown as HookFiredEvent);
+      } catch {
+        // fail-open.
+      }
+      if (projectCap.shouldHalt(projClass, projMode)) {
+        writeTelemetry({
+          agent,
+          tier: toolInput._tier_override ?? toolInput._default_tier ?? 'sonnet',
+          tokens_in: Number(toolInput._tokens_in_est ?? 0),
+          tokens_out: Number(toolInput._tokens_out_est ?? 0),
+          cache_hit: false,
+          est_cost_usd: estCost,
+          enforcement_mode: projMode,
+          block_reason: 'project_cap',
+          _cyclePhase: cyclePhase,
+        });
+        emitHookFired('block', cycle);
+        const response: ToolOutput = {
+          continue: false,
+          suppressOutput: false,
+          message: `Project budget cap reached: $${projClass.spend.toFixed(2)} of $${budget.project_cap_usd.toFixed(2)} (${projClass.pct.toFixed(0)}%). Raise project_cap_usd in .design/budget.json, or set project_cap_enforcement_mode to "warn" to keep going. (Graceful halt — the current stage's earlier spawns already completed; this blocks the next one.)`,
+        };
+        process.stdout.write(JSON.stringify(response));
+        return;
+      }
+      // warn / log mode: surface the 100% breach but allow the spawn.
+      process.stderr.write(`gdd-budget-enforcer WARN: ${projectCap.capMessage(projClass)}\n`);
+    }
+  }
+
   // Phase 25 / D-05: per-spawn cap is class-specific when
   // complexity_class is present and class_caps_usd[class] is defined.
   // Falls back to per_task_cap_usd for backwards compatibility — when

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.39.1",
+  "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/reference/cost-governance.md

@@ -0,0 +1,93 @@
+# Cost Governance — Forecast, Project Cap, and ROI
+
+Phase 39.2 contract. GDD already tracks cost (Phase 10.1 per-task caps, Phase 26 per-runtime
+telemetry, Phase 27.5 bandit cost-arbitrage) — but it never *forecasts* spend, never imposes a
+*project-level* hard cap, and never shows whether the spend actually *shipped* anything. This file is
+the contract for the three pieces that close those gaps: the **forecast model**, the **`project_cap`
+hard-halt**, and the **ROI dashboard**. All three are read-only/report-only except the hook, which
+only ever *blocks* a spawn — it never spends, edits config, or mutates telemetry.
+
+## Telemetry inputs
+
+- **`.design/telemetry/costs.jsonl`** (OPT-09) — one row per agent spawn:
+  `{ ts, agent, tier, tokens_in, tokens_out, cache_hit, est_cost_usd, cycle, phase }`.
+  The **`cycle`** field is the join key: grouping `est_cost_usd` by `cycle` gives per-cycle USD totals.
+- **`.design/telemetry/events.jsonl`** — the event stream; this phase appends three new `type`s
+  (below).
+- **Cycle identity** — `.design/STATE.md` frontmatter `cycle:`. There is no `CYCLES.md`; per-cycle
+  commit counts are computed on demand from `git log` (the `/gdd:stats` precedent).
+
+## Forecast model (`scripts/lib/budget/cost-forecast.cjs`, pure)
+
+Group `costs.jsonl` by `cycle` → an array of per-cycle USD totals. From the **mean** `m` and
+**population standard deviation** `σ` of those rates, the three scenarios are:
+
+| Scenario | Per-cycle rate | Meaning |
+|---|---|---|
+| `best` | `max(0, m − k·σ)` | spend trends down / variance favorable |
+| `typical` | `m` | steady state |
+| `worst` | `m + k·σ` | spend trends up / variance unfavorable |
+
+`k = 1` by default. The projection over the next `N` cycles is linear: `projectedTotal = rate · N`.
+`cyclesToCap(currentSpend, cap, rate)` returns the integer number of cycles until `currentSpend`
+reaches `cap` at that rate — `Infinity` when `rate ≤ 0`, `0` when already at/over the cap. This powers
+the `/gdd:budget` warning **"at the current rate you'll hit cap $X in Y cycles."**
+
+The math is a pure, dep-free, deterministic core (no fs, no clock, no randomness) — `agents/cost-forecaster.md`
+and `/gdd:budget` read the telemetry and hand the grouped totals in. `--scenario best|typical|worst`
+selects the rate.
+
+## Project cap (`scripts/lib/budget/project-cap.cjs` + `hooks/budget-enforcer.ts`)
+
+A **project-level** hard cap, distinct from the existing per-task and per-phase caps. Config lives in
+`.design/budget.json`:
+
+| Key | Type | Default | Meaning |
+|---|---|---|---|
+| `project_cap_usd` | number ≥ 0 | `0` (disabled) | Total project spend ceiling (USD). |
+| `project_cap_enforcement_mode` | `enforce` \| `warn` \| `log` | falls back to `enforcement_mode` | How a breach is handled. |
+
+**Disabled by default.** A cap of `0` (or absent / non-finite) means *no project cap* — existing
+users see zero behavior change. The classifier `classifyProjectBudget(spend, cap)` returns a level:
+
+| Running spend vs cap | Level | Hook behavior |
+|---|---|---|
+| `< 50%` | `ok` | nothing |
+| `≥ 50%` | `warn-50` | emit `project_cap_warning`, print, allow |
+| `≥ 80%` | `warn-80` | emit `project_cap_warning`, print, allow |
+| `≥ 100%` | `halt` | emit `project_cap_halt`; under `enforce`, block the spawn |
+
+The cap is enforced in the **PreToolUse:Agent** hook, so the halt is **graceful**: it blocks the
+*next* agent spawn, letting the current pipeline stage finish. Under `warn`/`log` mode a `halt`-level
+breach prints/records but still allows the spawn (advisory). Running project spend is the sum of
+`est_cost_usd` across all `costs.jsonl` rows (a `project-totals.json` fast-path mirrors the Phase 10.1
+`phase-totals.json` optimization).
+
+## ROI dashboard (`scripts/lib/budget/roi.cjs`, pure + `/gdd:roi`)
+
+Joins per-cycle cost with what actually shipped. **"Shipped"** = a commit that **survived ≥ 14 days**
+in `main` (the ROADMAP default — a longer window catches revert-after-bug-discovery); a commit
+reverted inside that window counts as `reverted`. `/gdd:roi` shells `git log` per cycle for the
+shipped/reverted counts and reads per-cycle cost from `costs.jsonl`; `roi.cjs` computes:
+
+- `costPerShipped = costUsd / max(shipped, 1)` — USD per commit that stuck.
+- `stickRate = shipped / max(shipped + reverted, 1)` — fraction of commits that survived.
+
+Output is a markdown table (cycle · cost · shipped · reverted · $/shipped · stick rate) plus a TOTAL
+row. Markdown only — no GUI.
+
+## Events
+
+Three new free-form `type`s on `.design/telemetry/events.jsonl`:
+
+| Type | Emitted by | Payload (PII-free) |
+|---|---|---|
+| `budget_forecast` | `cost-forecaster` / `/gdd:budget` | `{ scenario, perCycle, projectedTotal, cyclesToCap }` |
+| `project_cap_warning` | budget-enforcer hook | `{ pct, spend, cap, level }` at `warn-50` / `warn-80` |
+| `project_cap_halt` | budget-enforcer hook | `{ pct, spend, cap, enforcementMode }` at `halt` |
+
+## Boundaries
+
+Forecast is **cycle-scoped** (not per-agent-call). The cap **halts**, it never spends or auto-tunes.
+ROI is **markdown**, not a GUI. Nothing here writes `budget.json` — the user sets the cap; GDD only
+reads, forecasts, warns, and (at 100% under `enforce`) blocks the next spawn.

package/reference/registry.json

@@ -1021,6 +1021,13 @@
       "type": "heuristic",
       "phase": 39.1,
       "description": "Phase 39.1 migration rule library — Material Design token migration (M3→next), grounded in the real M2→M3 token-system patterns (md.sys.color/typescale roles, @material/web mwc-→md-) — no fabricated M4 spec. Rules + Detection + Impact; codemod-gen-consumable."
+    },
+    {
+      "name": "cost-governance",
+      "path": "reference/cost-governance.md",
+      "type": "heuristic",
+      "phase": 39.2,
+      "description": "Phase 39.2 cost-governance contract: the per-cycle forecast model (best/typical/worst from mean ± k·σ, cyclesToCap) via scripts/lib/budget/cost-forecast.cjs; the project_cap hard-halt (disabled by default, graceful PreToolUse:Agent block, warn 50/80 + halt 100) via scripts/lib/budget/project-cap.cjs + hooks/budget-enforcer.ts; the ROI dashboard (shipped = surviving >=14d, cost-per-shipped-commit) via scripts/lib/budget/roi.cjs; and the budget_forecast/project_cap_warning/project_cap_halt events. Agent agents/cost-forecaster.md; skills /gdd:budget + /gdd:roi. Read/report-only — the hook only blocks, never spends."
     }
   ]
 }

package/reference/schemas/budget.schema.json

@@ -37,6 +37,16 @@
       "type": "string",
       "enum": ["enforce", "warn", "log"],
       "description": "D-11 enforcement policy. enforce = block + auto-downgrade; warn = print warnings but allow spawn; log = advisory-only telemetry without gating."
+    },
+    "project_cap_usd": {
+      "type": "number",
+      "minimum": 0,
+      "description": "Phase 39.2 D-04 — project-level hard cap (USD) across the whole project's costs.jsonl. 0 or absent = DISABLED (no project-level enforcement; zero behavior change for existing users). When > 0, hooks/budget-enforcer.ts warns at 50% + 80% of this cap and (under project_cap_enforcement_mode=enforce) hard-halts the next PreToolUse:Agent spawn at 100%. Distinct from per_task_cap_usd / per_phase_cap_usd."
+    },
+    "project_cap_enforcement_mode": {
+      "type": "string",
+      "enum": ["enforce", "warn", "log"],
+      "description": "Phase 39.2 D-04 — enforcement policy for project_cap_usd specifically. enforce = hard-halt at 100%; warn = print at 100% but allow; log = advisory telemetry only. Falls back to enforcement_mode when absent."
     }
   }
 }

package/reference/schemas/events.schema.json

@@ -10,7 +10,7 @@
     "type": {
       "type": "string",
       "minLength": 1,
-      "description": "Free-form event type identifier. Pre-registered seeds: state.mutation, state.transition, stage.entered, stage.exited, hook.fired, error, capability_gap, kfm-candidate, router_pick, verify_outcome, rollout_started, rollout_advanced, rollout_stuck."
+      "description": "Free-form event type identifier. Pre-registered seeds: state.mutation, state.transition, stage.entered, stage.exited, hook.fired, error, capability_gap, kfm-candidate, router_pick, verify_outcome, rollout_started, rollout_advanced, rollout_stuck, budget_forecast, project_cap_warning, project_cap_halt."
     },
     "timestamp": {
       "type": "string",

package/reference/schemas/generated.d.ts

@@ -58,6 +58,14 @@ export interface DesignBudgetJson {
    * D-11 enforcement policy. enforce = block + auto-downgrade; warn = print warnings but allow spawn; log = advisory-only telemetry without gating.
    */
   enforcement_mode?: 'enforce' | 'warn' | 'log';
+  /**
+   * Phase 39.2 D-04 — project-level hard cap (USD) across the whole project's costs.jsonl. 0 or absent = DISABLED (no project-level enforcement; zero behavior change for existing users). When > 0, hooks/budget-enforcer.ts warns at 50% + 80% of this cap and (under project_cap_enforcement_mode=enforce) hard-halts the next PreToolUse:Agent spawn at 100%. Distinct from per_task_cap_usd / per_phase_cap_usd.
+   */
+  project_cap_usd?: number;
+  /**
+   * Phase 39.2 D-04 — enforcement policy for project_cap_usd specifically. enforce = hard-halt at 100%; warn = print at 100% but allow; log = advisory telemetry only. Falls back to enforcement_mode when absent.
+   */
+  project_cap_enforcement_mode?: 'enforce' | 'warn' | 'log';
   [k: string]: unknown;
 }
 
@@ -106,7 +114,7 @@ export type Event = {
   [k: string]: unknown;
 } & {
   /**
-   * Free-form event type identifier. Pre-registered seeds: state.mutation, state.transition, stage.entered, stage.exited, hook.fired, error, capability_gap.
+   * Free-form event type identifier. Pre-registered seeds: state.mutation, state.transition, stage.entered, stage.exited, hook.fired, error, capability_gap, kfm-candidate, router_pick, verify_outcome, rollout_started, rollout_advanced, rollout_stuck, budget_forecast, project_cap_warning, project_cap_halt.
    */
   type: string;
   /**
@@ -581,6 +589,62 @@ export interface ClaudePluginJson {
 
 export type PluginSchema = ClaudePluginJson;
 
+// ---- pressure-scenario.schema.json ----
+/**
+ * Contract for a Phase-33 skill-behavior pressure-scenario manifest. The runner (scripts/lib/skill-behavior/runner.cjs) loads manifests conforming to this schema, spawns a subagent against `setup_prompt` under the named `pressures`, and validates the response against the `expected_compliance` / `expected_violations` regex sources (compiled with new RegExp(source)). The 5-value `pressures` enum and the required-field set come verbatim from ROADMAP Phase-33 SC#2.
+ */
+export interface PressureScenarioManifest {
+  /**
+   * Unique scenario identifier, e.g. "brief-time-pressure".
+   */
+  name: string;
+  /**
+   * The skill under test, e.g. "brief", "explore", "plan", "using-gdd".
+   */
+  target_skill: string;
+  /**
+   * One or more pressure vectors applied in the setup_prompt.
+   *
+   * @minItems 1
+   */
+  pressures: [
+    'time' | 'sunk-cost' | 'authority' | 'exhaustion' | 'scope-minimization',
+    ...('time' | 'sunk-cost' | 'authority' | 'exhaustion' | 'scope-minimization')[],
+  ];
+  /**
+   * The prompt handed to the subagent — embeds the pressure(s) and asks it to act.
+   */
+  setup_prompt: string;
+  /**
+   * Regex SOURCE strings the response MUST match to count as compliant (the runner compiles each with new RegExp(source)).
+   *
+   * @minItems 1
+   */
+  expected_compliance: [string, ...string[]];
+  /**
+   * Regex SOURCE strings that, if matched, count as a violation (the runner compiles each with new RegExp(source)). May be empty.
+   */
+  expected_violations: string[];
+  /**
+   * Optional free-text scenario note (33-03 baselines reference it).
+   */
+  description?: string;
+  /**
+   * Optional A/B variant label, e.g. "trigger-only" | "what-clause" (33-04 description-format A/B).
+   */
+  variant?: string;
+  /**
+   * Optional array of A/B variant descriptors for a single-manifest A/B pair (33-04). Each item is an object, e.g. { label, description }.
+   */
+  variants?: {}[];
+  /**
+   * Optional body-only probe prompt the A/B scenario asks (33-04 description-format A/B).
+   */
+  body_probe?: string;
+}
+
+export type PressureScenarioSchema = PressureScenarioManifest;
+
 // ---- protected-paths.schema.json ----
 /**
  * Glob list describing paths the plugin refuses to Edit/Write or mutate via destructive Bash. User additions MERGE with this default list; users cannot reduce the default set.
@@ -622,6 +686,35 @@ export interface RateLimits {
 
 export type RateLimitsSchema = RateLimits;
 
+// ---- recipe.schema.json ----
+/**
+ * Shape of a declarative recipe loaded from recipes/<name>.json by scripts/lib/recipe-loader.cjs (Plan 31-5-03, RECIPE-01 / SC#14). The recipes/ directory ships EMPTY of recipes and is populated downstream by Phase 32 (skill-trigger recipes), Phase 33.6 (per-provider), Phase 26 (per-runtime/per-model), and Phase 23.5 (bandit-arm shape). This is a minimal, forward-compatible envelope: a recipe MUST carry name/version/steps; additionalProperties:true lets the populating phases extend the envelope without breaking the loader contract. Modelled on Storybloq's src/autonomous/recipes/ loader.ts pattern.
+ */
+export interface Recipe {
+  /**
+   * The recipe identifier. Matches the filename stem (recipes/<name>.json).
+   */
+  name: string;
+  /**
+   * Recipe/schema version string for forward-compatibility. Lets the loader and downstream phases reason about envelope evolution.
+   */
+  version: string;
+  /**
+   * The ordered recipe body. Item shape is kept permissive for now — each step is an object carrying at least a `kind` OR an `id` string. Downstream phases (32/33.6/26/23.5) tighten the step contract per their domain.
+   */
+  steps: (
+    | {
+        kind: string;
+      }
+    | {
+        id: string;
+      }
+  )[];
+  [k: string]: unknown;
+}
+
+export type RecipeSchema = Recipe;
+
 // ---- runtime-models.schema.json ----
 /**
  * Parsed shape of reference/runtime-models.md — the per-runtime tier→model adapter source-of-truth shipped in Phase 26 (D-01..D-03). Consumed by scripts/lib/install/parse-runtime-models.cjs at install time and scripts/lib/tier-resolver.cjs at runtime. Strict enums catch typos at install time, not at runtime. Schema versioned via $schema_version for forward-compat (D-03).

package/scripts/lib/budget/cost-forecast.cjs

@@ -0,0 +1,103 @@
+'use strict';
+// Phase 39.2 — cost-forecast.cjs — PURE, dep-free per-cycle cost forecasting core.
+//
+// The /gdd:budget skill and agents/cost-forecaster.md read .design/telemetry/costs.jsonl, group the
+// est_cost_usd by `cycle`, and hand the resulting per-cycle USD totals here. This module does ONLY
+// the projection math — it never touches the filesystem, the clock, or randomness, so it is trivially
+// unit-testable (the build-html.cjs / codemod-gen.cjs purity precedent).
+//
+// Scenario derivation (D-05): from the variance of the historical per-cycle rates,
+//   typical = mean
+//   worst  = mean + k·stddev
+//   best   = max(0, mean − k·stddev)
+// with k = 1 by default. Projection over the next N cycles is linear on the chosen rate.
+//
+// No `require` — pure. Deterministic.
+
+/** Coerce to a finite, non-negative number or throw. */
+function num(x, label) {
+  const n = Number(x);
+  if (!Number.isFinite(n)) throw new Error(`cost-forecast: ${label} must be a finite number (got ${x})`);
+  return n;
+}
+
+/** Population mean of an array of numbers (0 for empty). */
+function mean(xs) {
+  if (!xs.length) return 0;
+  let s = 0;
+  for (const x of xs) s += x;
+  return s / xs.length;
+}
+
+/** Population standard deviation (0 for length < 2). */
+function stddev(xs) {
+  if (xs.length < 2) return 0;
+  const m = mean(xs);
+  let acc = 0;
+  for (const x of xs) acc += (x - m) * (x - m);
+  return Math.sqrt(acc / xs.length);
+}
+
+/**
+ * Normalize the cycle-cost input into a clean array of non-negative per-cycle USD totals.
+ * Accepts either an array of numbers, or an array of { costUsd } / { est_cost_usd } objects.
+ */
+function perCycleRates(cycleCosts) {
+  if (!Array.isArray(cycleCosts)) throw new Error('cost-forecast: cycleCosts must be an array');
+  return cycleCosts.map((c, i) => {
+    const v = typeof c === 'object' && c !== null
+      ? (c.costUsd !== undefined ? c.costUsd : c.est_cost_usd)
+      : c;
+    const n = num(v, `cycleCosts[${i}]`);
+    return n < 0 ? 0 : n;
+  });
+}
+
+/**
+ * Project the next `nCycles` of spend.
+ * @returns {{scenario, k, observedCycles, perCycle, projectedTotal, low, high}}
+ *   perCycle      — the per-cycle rate used for this scenario
+ *   projectedTotal — perCycle * nCycles
+ *   low/high      — the best/worst per-cycle band (always returned for context)
+ */
+function forecast(cycleCosts, opts) {
+  const o = opts || {};
+  const nCycles = o.nCycles === undefined ? 5 : Math.max(0, Math.trunc(num(o.nCycles, 'nCycles')));
+  const scenario = o.scenario === undefined ? 'typical' : String(o.scenario);
+  const k = o.k === undefined ? 1 : num(o.k, 'k');
+  if (!['best', 'typical', 'worst'].includes(scenario)) {
+    throw new Error(`cost-forecast: scenario must be best|typical|worst (got ${scenario})`);
+  }
+  const rates = perCycleRates(cycleCosts);
+  const m = mean(rates);
+  const sd = stddev(rates);
+  const low = Math.max(0, m - k * sd);
+  const high = m + k * sd;
+  const perCycle = scenario === 'best' ? low : scenario === 'worst' ? high : m;
+  return {
+    scenario,
+    k,
+    observedCycles: rates.length,
+    perCycle,
+    projectedTotal: perCycle * nCycles,
+    low,
+    high,
+  };
+}
+
+/**
+ * Integer count of full cycles until `currentSpend` reaches `cap` at `perCycleRate`.
+ *   - rate <= 0           → Infinity (never reaches cap)
+ *   - currentSpend >= cap → 0 (already at/over)
+ * Throws on non-finite inputs.
+ */
+function cyclesToCap(currentSpend, cap, perCycleRate) {
+  const s = num(currentSpend, 'currentSpend');
+  const c = num(cap, 'cap');
+  const r = num(perCycleRate, 'perCycleRate');
+  if (s >= c) return 0;
+  if (r <= 0) return Infinity;
+  return Math.ceil((c - s) / r);
+}
+
+module.exports = { perCycleRates, mean, stddev, forecast, cyclesToCap };

package/scripts/lib/budget/project-cap.cjs

@@ -0,0 +1,55 @@
+'use strict';
+// Phase 39.2 — project-cap.cjs — PURE, dep-free project-budget classifier.
+//
+// The Phase 25 budget-enforcer hook (hooks/budget-enforcer.ts) reads the running project spend and
+// the configured project cap, and calls this classifier to decide whether to warn (50% / 80%) or
+// hard-halt (100%). Keeping the decision math here (out of the .ts hook) mirrors how the hook already
+// delegates cost computation to scripts/lib/budget-enforcer.cjs, and makes the thresholds unit-testable.
+//
+// project_cap is DISABLED by default (D-04): a cap of 0 / negative / non-finite means "no project cap"
+// and always returns level 'ok' — so existing users (who have no project_cap_usd in budget.json) see
+// zero behavior change. The halt is graceful: the hook fires on PreToolUse:Agent, so a 'halt' blocks
+// the NEXT agent spawn, letting the current stage finish.
+//
+// No `require` — pure. Deterministic.
+
+const WARN_50 = 50;
+const WARN_80 = 80;
+const HALT_100 = 100;
+
+/**
+ * @param {number} spendUsd  running project spend (USD)
+ * @param {number} capUsd    configured project cap (USD); <= 0 / non-finite ⇒ disabled
+ * @returns {{enabled:boolean, pct:number, level:'ok'|'warn-50'|'warn-80'|'halt', cap:number, spend:number}}
+ */
+function classifyProjectBudget(spendUsd, capUsd) {
+  const spend = Number(spendUsd);
+  const cap = Number(capUsd);
+  const enabled = Number.isFinite(cap) && cap > 0 && Number.isFinite(spend) && spend >= 0;
+  if (!enabled) {
+    return { enabled: false, pct: 0, level: 'ok', cap: Number.isFinite(cap) ? cap : 0, spend: Number.isFinite(spend) ? spend : 0 };
+  }
+  const pct = (spend / cap) * 100;
+  let level = 'ok';
+  if (pct >= HALT_100) level = 'halt';
+  else if (pct >= WARN_80) level = 'warn-80';
+  else if (pct >= WARN_50) level = 'warn-50';
+  return { enabled: true, pct, level, cap, spend };
+}
+
+/** True when a classification should hard-block the next spawn (enforce mode + level 'halt'). */
+function shouldHalt(classification, enforcementMode) {
+  return !!classification && classification.level === 'halt' && enforcementMode === 'enforce';
+}
+
+/** A one-line human message for a non-'ok' level (null when ok). */
+function capMessage(c) {
+  if (!c || !c.enabled || c.level === 'ok') return null;
+  const pct = c.pct.toFixed(0);
+  if (c.level === 'halt') {
+    return `project budget cap reached: $${c.spend.toFixed(2)} / $${c.cap.toFixed(2)} (${pct}%) — halting before the next agent spawn`;
+  }
+  return `project budget at ${pct}%: $${c.spend.toFixed(2)} / $${c.cap.toFixed(2)}`;
+}
+
+module.exports = { classifyProjectBudget, shouldHalt, capMessage, WARN_50, WARN_80, HALT_100 };

package/scripts/lib/budget/roi.cjs

@@ -0,0 +1,73 @@
+'use strict';
+// Phase 39.2 — roi.cjs — PURE, dep-free ROI join + table formatter.
+//
+// The /gdd:roi skill shells `git log` to count, per cycle, commits that SHIPPED (survived >= 14 days
+// in main — the ROADMAP "shipped" definition, catching revert-after-bug-discovery) vs commits that
+// were REVERTED, and reads per-cycle cost from .design/telemetry/costs.jsonl. It hands the joined rows
+// here. This module does ONLY the arithmetic + markdown formatting — no fs, no clock, no git. Pure.
+//
+// No `require` — pure. Deterministic.
+
+function num(x, label) {
+  const n = Number(x);
+  if (!Number.isFinite(n)) throw new Error(`roi: ${label} must be a finite number (got ${x})`);
+  return n;
+}
+
+/**
+ * @param {Array<{cycle, costUsd, commitsShipped, commitsReverted}>} cycles
+ * @returns {{rows, totals}}
+ *   row    — { cycle, costUsd, shipped, reverted, costPerShipped, stickRate }
+ *   totals — aggregate across all cycles (same fields, cycle: 'TOTAL')
+ *   costPerShipped = costUsd / max(shipped, 1)   (USD per commit that stuck)
+ *   stickRate      = shipped / max(shipped + reverted, 1)   (0..1)
+ */
+function computeRoi(cycles) {
+  if (!Array.isArray(cycles)) throw new Error('roi: cycles must be an array');
+  const rows = cycles.map((c, i) => {
+    if (typeof c !== 'object' || c === null) throw new Error(`roi: cycles[${i}] must be an object`);
+    const costUsd = num(c.costUsd, `cycles[${i}].costUsd`);
+    const shipped = Math.max(0, Math.trunc(num(c.commitsShipped, `cycles[${i}].commitsShipped`)));
+    const reverted = Math.max(0, Math.trunc(num(c.commitsReverted, `cycles[${i}].commitsReverted`)));
+    return {
+      cycle: String(c.cycle),
+      costUsd,
+      shipped,
+      reverted,
+      costPerShipped: costUsd / Math.max(shipped, 1),
+      stickRate: shipped / Math.max(shipped + reverted, 1),
+    };
+  });
+  const totCost = rows.reduce((a, r) => a + r.costUsd, 0);
+  const totShipped = rows.reduce((a, r) => a + r.shipped, 0);
+  const totReverted = rows.reduce((a, r) => a + r.reverted, 0);
+  const totals = {
+    cycle: 'TOTAL',
+    costUsd: totCost,
+    shipped: totShipped,
+    reverted: totReverted,
+    costPerShipped: totCost / Math.max(totShipped, 1),
+    stickRate: totShipped / Math.max(totShipped + totReverted, 1),
+  };
+  return { rows, totals };
+}
+
+/** Format a USD value as $X.XX. */
+function usd(n) {
+  return '$' + num(n, 'usd').toFixed(2);
+}
+
+/** Render the ROI result as a GitHub-flavored markdown table. Pure string output. */
+function roiTableMarkdown(roi) {
+  if (!roi || !Array.isArray(roi.rows)) throw new Error('roi: roiTableMarkdown needs a computeRoi() result');
+  const head =
+    '| Cycle | Cost | Shipped | Reverted | $/shipped | Stick rate |\n' +
+    '|---|---:|---:|---:|---:|---:|';
+  const fmt = (r) =>
+    `| ${r.cycle} | ${usd(r.costUsd)} | ${r.shipped} | ${r.reverted} | ${usd(r.costPerShipped)} | ${(r.stickRate * 100).toFixed(0)}% |`;
+  const body = roi.rows.map(fmt).join('\n');
+  const foot = fmt(roi.totals);
+  return [head, body, foot].join('\n');
+}
+
+module.exports = { computeRoi, roiTableMarkdown, usd };

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/budget/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: gdd-budget
+description: "Forecasts GDD design-cycle spend before the bill arrives. Reads .design/telemetry/costs.jsonl (cost per cycle) + .design/budget.json (the project_cap), runs the pure cost-forecast model via agents/cost-forecaster.md, and projects the next N cycles — surfacing 'at the current rate you'll hit your $X project cap in Y cycles.' Supports --scenario best|typical|worst and --cycles N. Read-only — it forecasts and warns; it never spends, edits budget.json, or halts (the budget-enforcer hook halts). Use to sanity-check spend trajectory before a long run."
+argument-hint: "[--cycles N] [--scenario best|typical|worst]"
+user-invocable: true
+tools: Read, Bash, Grep, Glob, ToolSearch, Task
+---
+
+# /gdd:budget
+
+Closes the long-horizon cost gap: Phase 10.1 per-task caps + Phase 26 per-runtime telemetry track
+*cost*, but nothing **forecasts** it. This skill projects the next N cycles of spend and tells you how
+many cycles you have before you hit your `project_cap`. **Read-only** — it forecasts and warns; it
+never spends, never edits `budget.json`, and never halts (the Phase 25 budget-enforcer hook is the
+only thing that blocks a spawn). Contract: `../../reference/cost-governance.md`.
+
+## Invocation
+
+| Command | Behavior |
+|---|---|
+| `/gdd:budget` | Typical-scenario forecast over the next 5 cycles + cycles-to-cap. |
+| `/gdd:budget --cycles N` | Forecast over the next N cycles. |
+| `/gdd:budget --scenario best\|typical\|worst` | Pick the projection rate (best / steady / worst). |
+
+## Steps
+
+1. **Check telemetry exists.** No `.design/telemetry/costs.jsonl` (or zero rows) → print
+   `budget: no cost telemetry yet — run a cycle first.` and exit.
+2. **Delegate to `cost-forecaster`** (via `Task`): it groups `est_cost_usd` by `cycle`, runs the pure
+   `scripts/lib/budget/cost-forecast.cjs` model for the requested `--scenario`/`--cycles`, reads
+   `project_cap_usd` from `.design/budget.json`, and computes cycles-to-cap.
+3. **Render.** Show: the scenario + its per-cycle rate, the best↔worst band, the projected total over
+   N cycles, and — when `project_cap_usd > 0` — **"at the `<scenario>` rate (~$X/cycle) you'll reach
+   your $`<cap>` project cap in `<Y>` cycles"** (or "not at this rate" when the trend is flat/down).
+   When no cap is set, show the trajectory and note that `project_cap_usd` is unset (so the hook won't
+   halt).
+4. **Do not act.** Never raise/lower the cap, never spend — GDD forecasts; the human sets the budget.
+
+## Output
+
+End with:
+
+```
+## BUDGET COMPLETE
+```

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/roi/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: gdd-roi
+description: "Shows whether GDD spend actually shipped anything. Joins per-cycle cost (.design/telemetry/costs.jsonl) with what each cycle shipped — commits that SURVIVED in main vs commits that were reverted — and reports cost-per-shipped-commit + a stick rate per cycle. 'Shipped' = a commit surviving >= the window (default 14 days), which catches revert-after-bug-discovery. Markdown table, not a GUI. Read-only — it reads git log + cost telemetry and reports. Use to see which cycles were worth their spend."
+argument-hint: "[--since <date>] [--window-days 14]"
+user-invocable: true
+tools: Read, Bash, Grep, Glob
+---
+
+# /gdd:roi
+
+Closes the loop on cost: `/gdd:budget` forecasts *spend*, this shows the *return*. It joins per-cycle
+cost with the commits that actually stuck, so you can see cost-per-shipped-commit and which cycles
+were worth it. **Read-only** — it reads `git log` + cost telemetry and prints a table. Contract +
+the "shipped" definition: `../../reference/cost-governance.md`.
+
+## Invocation
+
+| Command | Behavior |
+|---|---|
+| `/gdd:roi` | ROI table across all cycles with cost telemetry (14-day stick window). |
+| `/gdd:roi --since <date>` | Only cycles since `<date>`. |
+| `/gdd:roi --window-days N` | "Shipped" = a commit surviving ≥ N days (default 14). |
+
+## Steps
+
+1. **Check telemetry exists.** No `.design/telemetry/costs.jsonl` (or zero rows) → print
+   `roi: no cost telemetry yet — run a cycle first.` and exit.
+2. **Per-cycle cost.** Group `est_cost_usd` in `costs.jsonl` by `cycle`.
+3. **Per-cycle shipped / reverted.** For each cycle, use `git log` to count, in that cycle's date
+   range: commits still present in `main` and older than the window = **shipped**; commits that a
+   later `revert` removed (or that were reverted within the window) = **reverted**. (A commit younger
+   than the window is "too new to score" — exclude it, don't count it as shipped.)
+4. **Join + compute** via the pure helper — never hand-compute:
+
+   ```bash
+   node -e '
+     const { computeRoi, roiTableMarkdown } = require("./scripts/lib/budget/roi.cjs");
+     const cycles = JSON.parse(process.argv[1]); // [{cycle,costUsd,commitsShipped,commitsReverted},...]
+     console.log(roiTableMarkdown(computeRoi(cycles)));
+   ' "$CYCLES_JSON"
+   ```
+
+5. **Render** the markdown table (cycle · cost · shipped · reverted · $/shipped · stick rate) plus the
+   TOTAL row. A high `$/shipped` with a low stick rate is the signal that a cycle burned budget
+   without lasting output.
+6. **Do not act.** Reporting only — never revert, re-run, or change budget.
+
+## Output
+
+End with:
+
+```
+## ROI 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