@hegemonart/get-design-done 1.38.5 → 1.39.2

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

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.38.5",
+  "version": "1.39.2",
   "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,57 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [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
+
+Opens the v1.39.x arc and the first half of the split Phase 39. When a design system ships a breaking major (shadcn/ui v1→v2, Tailwind v3→v4, MUI v5→v6, Material 2/3 token rename), GDD can now read the in-repo `package.json`, detect the version skew, consult a curated rule library, and produce an **impact-scored, proposal-only migration plan** with codemod scaffolds. Nothing runs automatically and no codemod engine is bundled — `codemod-gen` emits jscodeshift/ast-grep template **text** the developer reviews and runs themselves. **No new runtime dependency, no new egress.**
+
+### Added
+
+- **`reference/migrations/{shadcn-v2,tailwind-v4,mui-v6,material-3-to-4}.md`** — 4 curated rule libraries. Each carries `## Detection` (package.json dep + version), a `## Migration rules` table (Rule ID · Kind · From → To · Note, where Kind ∈ `rename-class`/`rename-prop`/`remove-component`/`token-rename`/`new-default`), and `## Impact notes`. Grounded in the official upstream migration guides (Tailwind v4 browser baseline, MUI Grid2/`experimental_` removal, Material M2→M3 `--mdc-*` → `--md-sys-*` tokens). Registered.
+- **`scripts/lib/migration/codemod-gen.cjs`** — pure, dep-free `emitCodemod(rule, { engine: 'jscodeshift' | 'ast-grep' })` → `{ ruleId, engine, kind, template }`. One template per rule kind; deterministic. Emits template **text only** — it never imports or runs jscodeshift/ast-grep.
+- **`agents/ds-migration-planner.md`** — detects the DS + version from `package.json`, consults `reference/migrations/<ds>.md`, scores each affected component (visual-delta × usage × tests-affected), and emits codemod scaffolds to `.design/migration/` via `codemod-gen`. **Proposal-only**; long-tail DS fall back to a generic template.
+- **`agents/design-verifier.md`** — an in-place note (net-zero, stays at the 700-line cap): when a DS migration is in flight, the verifier also asserts the migration preserved the contract (visual-diff within threshold, component API surface unchanged, tests pass) and treats an unmigrated high-impact rule as a gap.
+
+### Notes
+
+- **No new runtime dependency, no new egress** — `codemod-gen` is a pure text emitter; version detection is a local `package.json` read.
+- 6-manifest lockstep at **v1.39.1** + `OFF_CADENCE_VERSIONS.add('1.39.1')` + the 30 live-pinned `manifests-version.txt` baselines forward-propagated 1.38.5 → 1.39.1.
+- Inventory relock: registry-diff 153 → 157 (+4 rule libraries), agent-list +`ds-migration-planner` + both frontmatter-snapshots, tarball golden 694 → 700 (+6: 4 rule libraries + `codemod-gen.cjs` + `ds-migration-planner.md`). No skill/connection deltas.
+
+---
+
 ## [1.38.5] - 2026-06-01
 
 ### Phase 38.5 — Deployment Coordination Loop

package/README.md

@@ -178,6 +178,14 @@ GDD now learns **which design patterns win with users**, not just which pass lin
 
 GDD now tracks a design past "PR merged" to **actually live**. [`/gdd:rollout-status`](skills/rollout-status/SKILL.md) reads the feature-flag service (the Phase 38 LaunchDarkly/Statsig/GrowthBook connections) via [`rollout-coordinator`](agents/rollout-coordinator.md) and classifies each cycle — `unrolled` / `staging-only` / `canary-N%` / `prod-100%` — surfacing **stuck** rollouts (a canary that hasn't advanced in N days). The pure [`rollout-status`](scripts/lib/rollout/rollout-status.cjs) classifier also computes a **deployed-percentage weight** that feeds the `design_arms` posterior via `verify_outcome` events — a variant that only reached 10% of users counts as weak evidence (0.1), a fully-rolled one counts 1.0. **Read-only** (GDD never advances or rolls back) and **no new runtime dependency**.
 
+### DS migration workflows (v1.39.1)
+
+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.
+
 ### 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,8 @@ 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 |
 
 ## 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/agents/design-verifier.md

@@ -182,7 +182,7 @@ Allow-list seed (skip): `console\.(log|error|warn|info|debug)`, dev-only `/* */`
 
 ## Phase 2 — Must-Have Check
 
-Read `.design/STATE.md` `<must_haves>`. Also read must-haves from DESIGN-PLAN.md acceptance criteria, **and the brief's `<prior-research>` findings (Phase 38)** — for each prior-research finding, assert the current design addresses it or note an explicit defer + rationale (an unaddressed `critical`/`serious` finding is a gap). For each M-XX must-have, determine verification method and verify:
+Read `.design/STATE.md` `<must_haves>`. Also read must-haves from DESIGN-PLAN.md acceptance criteria, **and the brief's `<prior-research>` findings (Phase 38)** — for each prior-research finding, assert the current design addresses it or note an explicit defer + rationale (an unaddressed `critical`/`serious` finding is a gap). **When a DS migration is in flight** (`.design/migration/` per Phase 39.1's `ds-migration-planner`), also assert it preserved the contract — visual-diff within threshold, component API surface unchanged, tests pass — and treat an unmigrated high-impact rule as a gap. For each M-XX must-have, determine verification method and verify:
 
 | Must-have type | Verification method |
 |---|---|

package/agents/ds-migration-planner.md

@@ -0,0 +1,72 @@
+---
+name: ds-migration-planner
+description: Plans a design-system version migration (shadcn v1→v2, Tailwind v3→v4, MUI v5→v6, Material token migration). Detects the DS + version from package.json, consults the matching reference/migrations/<ds>.md rule library, proposes an impact-scored per-component plan (visual-delta × usage-frequency × tests-affected), and emits jscodeshift/ast-grep codemod templates via scripts/lib/migration/codemod-gen.cjs. Proposal-only — the user reviews + runs each codemod; GDD never auto-applies.
+tools: Read, Bash, Grep, Glob
+color: green
+default-tier: sonnet
+tier-rationale: "Consults a rule library + scores impact + emits codemod scaffolds via a pure helper; bounded planning, not open design judgment — sonnet-tier."
+size_budget: M
+size_budget_rationale: "Honest tier sized to the ~105-line body. DELEGATES the rules to reference/migrations/<ds>.md and the codemod templating to scripts/lib/migration/codemod-gen.cjs (the pdf-executor→validate-print-css precedent)."
+parallel-safe: false
+typical-duration-seconds: 60
+reads-only: false
+writes:
+  - ".design/migration/<ds>-<from>-<to>/** (plan + codemod templates, for review)"
+---
+
+@reference/shared-preamble.md
+
+# ds-migration-planner
+
+## Role
+
+Turn a breaking design-system version bump into a reviewable, impact-ordered migration plan + ready-to-review codemod scaffolds. **Proposal-only (D-01)** — GDD detects, plans, and generates; the user reviews each codemod and runs it with their own tool (jscodeshift / ast-grep). GDD never auto-applies a migration.
+
+## When invoked
+
+When the user wants to migrate a DS across a major (or `design-context-builder` detects a dep major behind the installed one). Supported libraries: shadcn (`reference/migrations/shadcn-v2.md`), Tailwind (`tailwind-v4.md`), MUI (`mui-v6.md`), Material tokens (`material-3-to-4.md`).
+
+## Step 1 — Detect DS + version (package.json only, D-03)
+
+```bash
+node -e "const p=require('./package.json'); const d={...p.dependencies,...p.devDependencies}; console.log(JSON.stringify({ tailwind:d.tailwindcss, mui:d['@mui/material'], radix:Object.keys(d).filter(k=>k.startsWith('@radix-ui/')).length, material:d['@material/web']||d['@angular/material'] }))"
+```
+
+Resolve the DS + the from→to version boundary from the dep version. Ambiguous → ask; never guess from source.
+
+## Step 2 — Load the rule library
+
+Read `reference/migrations/<ds>.md`. Its `## Migration rules` table is the authoritative rule set (id · kind · from→to · note); `## Impact notes` flags high-visual-delta vs mechanical. **No matching library** (a long-tail DS) → emit a starter rule-library template for the user to author their own (D-05); do not guess rules.
+
+## Step 3 — Impact-scored per-component plan (D-04)
+
+For each affected component, score `impact = visual_delta × usage_frequency × tests_affected`:
+
+- **visual_delta** — from the rule's Impact notes (high for ring/shadow/color/Grid changes; low for import renames).
+- **usage_frequency** — `grep -rc` the component/class/token across `src/`.
+- **tests_affected** — count touching test files.
+
+Order the plan **highest-impact-lowest-risk first** so the user migrates the riskiest surfaces under the most scrutiny. Present the plan as a table (component · rules · impact · manual-review?).
+
+## Step 4 — Emit codemod scaffolds (review before apply)
+
+For each mechanical rule, emit a codemod template via the pure generator:
+
+```bash
+node -e "const {emitCodemod}=require('./scripts/lib/migration/codemod-gen.cjs'); \
+  console.log(emitCodemod({id:RULE_ID, kind:KIND, from:FROM, to:TO, note:NOTE}, {engine:'jscodeshift'}).template)"
+```
+
+Write each to `.design/migration/<ds>-<from>-<to>/<RULE_ID>.{js,yml}` for the user to review + run. `new-default` rules emit a **manual-review advisory** (no auto-transform). NEVER run the codemod or write into `src/`.
+
+## Step 5 — Hand off to verify
+
+After the user applies codemods, `/gdd:verify` (`design-verifier`) checks the migration preserved the contract — visual-diff threshold, component API surface unchanged, tests pass. Note unresolved high-impact rules as gaps.
+
+## Record
+
+Emit a `## Migration plan` summary: DS, from→to, the impact-ordered component table, the emitted codemod files, and manual-review items. Close with:
+
+```
+## MIGRATION PLAN COMPLETE
+```

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.38.5",
+  "version": "1.39.2",
   "description": "A design-quality pipeline for AI coding agents: brief, plan, implement, and verify UI work against your design system.",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",

package/reference/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.