@hegemonart/get-design-done 1.41.0 → 1.42.0

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

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.41.0",
+  "version": "1.42.0",
   "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,87 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.42.0] - 2026-06-02
+
+### Phase 42 — Multi-Harness Source Compilation
+
+One skill source, N provider bundles. The README advertised 14 harnesses but every skill hard-coded
+Claude syntax (`/gdd:`…). Phase 42 authors each skill **once** in `source/skills/` with placeholders and
+compiles per-harness bundles via a pure transformer factory that reads the Phase 41.5 manifest SoT.
+**No new runtime dependency, no new egress.**
+
+### Breaking changes
+
+- **`skills/` is now a generated artifact, not the authoring source.** Skills are authored in
+  **`source/skills/`** (with `{{command_prefix}}` and the other placeholders); the committed `skills/`
+  tree is regenerated from it for the Claude-Code default, and CI's `npm run build:skills:check` fails on
+  any drift. **Contributors must edit `source/skills/`, never `skills/` directly**, then run
+  `npm run build:skills` and commit the regenerated `skills/` + `dist/claude-code/`. The plugin contract is
+  unchanged — `.claude-plugin/plugin.json` still loads `./skills/`, now produced from `source/skills/`.
+  See `reference/DEPRECATIONS.md` → Authoring surfaces and `reference/skill-placeholders.md`.
+
+### Added
+
+- **`source/skills/`** — all 83 skills (107 `.md`) authored once with placeholders. `/gdd:` →
+  `{{command_prefix}}` is a pure string inverse, so the Claude compile reproduces `skills/` byte-for-byte.
+- **`scripts/lib/build/factory.cjs`** — the pure `compile(text, config)` transformer (no I/O): the four
+  placeholders, `<!-- harness-only: a,b -->` blocks, and `\{{…}}` escapes.
+- **`scripts/lib/build/harness-configs.cjs`** — per-harness substitutions layered over
+  `scripts/lib/manifest/harnesses.json` (41.5). 14 records; `codex` is the flat-prefix (`/gdd-`) outlier.
+  Adding a 15th harness = one manifest entry plus an optional override row.
+- **`scripts/build-skills.cjs`** (`npm run build:skills`, `build:skills:check`) — orchestrator with
+  `--harness`, `--check` (drift gate), and `--zip`. Writes `dist/<bundle>/<configDir>/skills/…` and
+  regenerates `skills/` in place. Idempotent + byte-stable.
+- **`dist/claude-code/`** — the default Claude-Code bundle, committed + shipped in the npm tarball (other
+  per-harness bundles stay build-only artifacts; `--zip` packages them for releases).
+- **`gdd-sdk build skills [--harness <id>] [--zip] [--check]`** — SDK CLI surface (operates in a repo clone
+  where `source/skills/` is present; the orchestrator + source are dev-only, not shipped).
+- **`reference/skill-placeholders.md`** — the placeholder catalogue + per-harness substitution table +
+  escape and harness-only rules.
+
+### Notes
+
+- 6-manifest lockstep at **v1.42.0** + `OFF_CADENCE_VERSIONS.add('1.42.0')` + the 37 live-pinned
+  `manifests-version.txt` baselines forward-propagated 1.41.5 → 1.42.0.
+- CI gains a `build:skills:check` drift step in the validate job; a per-harness compile smoke + a 14-harness
+  golden baseline (`test/fixtures/baselines/phase-42/`) pin the compile output.
+- Inventory: tarball golden 757 → 868 (+111: `dist/claude-code/**` 107, `scripts/lib/build/**` 2,
+  `reference/skill-placeholders.md`, `sdk/cli/commands/build.ts`). `source/skills/` is dev-only (not shipped).
+
+---
+
+## [1.41.5] - 2026-06-02
+
+### Phase 41.5 — SoT Manifest Consolidation
+
+A 2026-05-16 audit found Phase 42/44/45/47 each scoping its own "single source of truth" in a different
+corner — four formats, four schemas, four CI drift gates. 41.5 lands **one** root, **one** schema
+directory, **one** validator, **before** those phases plan their work. **No new runtime dependency, no
+new egress.**
+
+### Added
+
+- **`scripts/lib/manifest/`** — the cross-phase SoT root:
+  - `loader.cjs` — the one shared reader; a missing/unparseable file returns an empty fallback + a
+    one-line warning (never throws), with a file-mtime cache. Dep-free.
+  - `index.cjs` — typed readers `readHarnesses()` / `readSkills()` / `readProseDenylist()`.
+  - `harnesses.json` (+ `.cjs` view) — the 14 canonical runtimes (Phase 42 adds build config, Phase 45
+    the capability matrix, as views of this one record). `skills.json` — the 83 live skill names (Phase
+    47 enriches). `prose-denylist.json` — the AI-tell denylist + em-dash/`--` markers (Phase 43/44 consume).
+  - `schemas/*.schema.json` — one JSON Schema per manifest. `README.md` — the contract + migration note.
+- **`scripts/validate-manifest.cjs`** (`npm run validate:manifest`) — the single ajv CI gate that
+  replaces the four per-file drift gates 43/44/45/47 would each have shipped.
+
+### Notes
+
+- **No new runtime dependency** — the shipped `loader.cjs`/`index.cjs` are dep-free; `validate-manifest.cjs`
+  uses the already-present `ajv` and is maintainer-only (not shipped, like `lint-changelog.cjs`).
+- 6-manifest lockstep at **v1.41.5** + `OFF_CADENCE_VERSIONS.add('1.41.5')` + the 36 live-pinned
+  `manifests-version.txt` baselines forward-propagated 1.41.0 → 1.41.5.
+- Inventory: tarball golden 747 → 757 (+10: `scripts/lib/manifest/**`). No skill/agent/registry deltas.
+
+---
+
 ## [1.41.0] - 2026-06-02
 
 ### Phase 41 — Deterministic Anti-Pattern CLI (`gdd-detect`)

package/README.md

@@ -243,6 +243,8 @@ The installer prompts you to choose:
 
 All 14 runtimes receive their native artifact layout (`skills/`, `command/`, `agents/`, or `.clinerules`) via per-runtime content converters — Claude SKILL.md sources are translated to each runtime's expected shape at install time (frontmatter pass-through, path rewrite, tool-name rewrite via the Phase 21 cross-harness maps). Architecture ported from `gsd-build/get-shit-done` (MIT — see `NOTICE`; upstream is now archived following the May 2026 $GSD token rug-pull, community continuation lives at [`open-gsd/get-shit-done-redux`](https://github.com/open-gsd/get-shit-done-redux)).
 
+**Multi-harness compilation (v1.42.0).** Skills are authored once in `source/skills/` with placeholders (`{{command_prefix}}`, `{{model}}`, `{{config_file}}`, `{{ask_instruction}}`) and compiled per-harness by `scripts/build-skills.cjs` (`npm run build:skills`, or `gdd-sdk build skills`) using a pure transformer factory that reads the single harness manifest at `scripts/lib/manifest/harnesses.json`. The committed `skills/` tree is the regenerated Claude-Code default (CI drift-gates `committed === generated`); the default bundle ships at `dist/claude-code/`, and the other 13 bundles are produced on demand. Adding a 15th harness is one manifest entry. Contributors: edit `source/skills/`, never `skills/` directly — see `reference/skill-placeholders.md` and `reference/DEPRECATIONS.md`.
+
 Verify with:
 
 ```

package/dist/claude-code/.claude/skills/add-backlog/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: gdd-add-backlog
+description: "Park a design idea for a future cycle. Writes to .design/backlog/BACKLOG.md."
+argument-hint: "[text]"
+tools: Read, Write, AskUserQuestion
+disable-model-invocation: true
+---
+
+# /gdd:add-backlog
+
+**Role:** Long-term parking lot for design ideas. Backing store: `.design/backlog/BACKLOG.md`.
+
+## Step 1 — Get text
+
+If `$ARGUMENTS` is empty, ask the user: "What should be added to the backlog?"
+
+## Step 2 — Append
+
+Create `.design/backlog/` directory and `BACKLOG.md` with `# Design Backlog` header if missing.
+
+Derive `<title>` = first 60 characters of the text (strip newlines). Append:
+
+```markdown
+## <title>
+**Added**: YYYY-MM-DD
+**Status**: parked
+
+<full text>
+
+---
+```
+
+## Output
+
+```
+━━━ Backlog entry parked ━━━
+Title: <title>
+Status: parked
+Promote later via: /gdd:review-backlog
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Constraints
+
+- Do not modify files outside `.design/backlog/`.
+- Do not set status to anything other than `parked` here — `/gdd:review-backlog` owns status transitions.
+
+## ADD-BACKLOG COMPLETE

package/dist/claude-code/.claude/skills/analyze-dependencies/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: gdd-analyze-dependencies
+description: "Queries the intel store to surface token fan-out, component call-graphs, decision traceability, and circular dependency detection. Requires .design/intel/ to exist (run build-intel.cjs first)."
+tools: Bash, Read, Glob, Grep
+---
+
+# /gdd:analyze-dependencies
+
+**Role:** Surface dependency relationships, token usage spread, component graphs, and decision traceability using `.design/intel/`. All queries are O(1) reads against pre-built JSON slices — no file greps. See `./reference/heuristics.md` for the underlying dependency-analysis heuristics (fan-out thresholds, orphan-token criteria, cycle-detection bias).
+
+## Pre-flight
+
+Verify the intel store exists:
+
+```bash
+ls .design/intel/files.json 2>/dev/null && echo "ready" || echo "missing"
+```
+
+If missing, print:
+
+```
+Intel store not found. Build it first:
+  node scripts/build-intel.cjs --force
+Then re-run /gdd:analyze-dependencies.
+```
+
+## Usage modes
+
+- `/gdd:analyze-dependencies` — run all four analyses and print a combined report
+- `/gdd:analyze-dependencies tokens` — token fan-out only
+- `/gdd:analyze-dependencies components` — component call-graph only
+- `/gdd:analyze-dependencies decisions` — decision traceability only
+- `/gdd:analyze-dependencies circular` — circular dependency detection only
+
+## Analysis 1 — Token fan-out
+
+Surfaces tokens referenced in many files + orphans (referenced exactly once).
+
+1. Read `.design/intel/tokens.json`; group by `token` value; count distinct `file` values.
+2. Sort descending; print top-20 with token / file count / category columns.
+3. Append orphans list (token + file:line of the single reference).
+
+Header: `━━━ Token fan-out ━━━` … `(top 20 shown)` … `Orphaned tokens (referenced in exactly 1 file):` … footer rule.
+
+## Analysis 2 — Component call-graph
+
+Surfaces widely-referenced components and the files referencing each.
+
+1. Read `.design/intel/components.json`; group by `component` name; count distinct `file` values.
+2. Sort descending; print top-20 with component / references / files columns.
+3. If `components <Name>` is passed, print only that component's referencing files (one per line).
+
+Header: `━━━ Component call-graph ━━━` … footer rule.
+
+## Analysis 3 — Decision traceability
+
+Maps decisions to skill/agent files that cite them.
+
+1. Read `.design/intel/decisions.json` (decision IDs D-01, D-02, …).
+2. Read `.design/intel/symbols.json` for heading anchors; `.design/intel/dependencies.json` for @-reference chains.
+3. For each decision, cross-reference which files cite the ID.
+4. Print per-decision block: `D-NN  <description>` then a 6-space-indented `Referenced by: <file:line>, …` line (or `(no explicit references found)`).
+5. Footer: `Total: N decisions tracked, M with file references`.
+
+Empty-state: `No decisions indexed. Run node scripts/build-intel.cjs after creating .design/DESIGN-CONTEXT.md.`
+
+## Analysis 4 — Circular dependency detection
+
+Detects cycles in the `@`-reference graph (File A → File B → File A). DFS with path-tracking detects back-edges; algorithm + adjacency-map shape detailed in `./reference/heuristics.md` §"Dependency-cycle detection".
+
+1. Read `.design/intel/graph.json`; build adjacency map from `edges`.
+2. Run DFS with path-tracking; collect back-edges as cycles.
+3. Print each cycle with the node sequence + `<- CYCLE` marker on the closing node.
+4. Footer: `Total cycles: N` (or `All clear — no circular dependencies detected.`).
+
+## Combined report
+
+When run without a mode argument, print all four analyses in sequence separated by blank lines, prefixed with:
+
+```
+━━━ Dependency Analysis ━━━
+Intel store: .design/intel/
+Generated:   <timestamp from files.json>
+Files indexed: <count>
+```
+
+## Required reading (conditional)
+
+@.design/intel/tokens.json (if present)
+@.design/intel/components.json (if present)
+@.design/intel/dependencies.json (if present)
+@.design/intel/decisions.json (if present)
+@.design/intel/graph.json (if present)
+
+## ANALYZE-DEPENDENCIES COMPLETE

package/dist/claude-code/.claude/skills/apply-reflections/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: gdd-apply-reflections
+description: "Review and selectively apply proposals from .design/reflections/<cycle-slug>.md. Diffs each proposal, prompts user to accept/skip/edit, then writes changes."
+argument-hint: "[--cycle <slug>] [--filter <FRONTMATTER|REFERENCE|BUDGET|QUESTION|GLOBAL-SKILL>] [--dry-run]"
+tools: Read, Write, Edit, Bash, Glob
+---
+
+# /gdd:apply-reflections
+
+Interactive proposal review loop. Reads `.design/reflections/<cycle-slug>.md`, walks each numbered proposal, and applies accepted ones to the appropriate target file. Nothing is applied without explicit user confirmation.
+
+## Steps
+
+### 1. Resolve reflections file
+
+- If `--cycle <slug>` given: load `.design/reflections/<slug>.md`
+- Else: glob `.design/reflections/*.md`, sort by modified time descending, load the most recent
+- If no file found: error "No reflections found. Run `/gdd:reflect` first."
+- Print: "Reviewing reflections: <filename>"
+
+### 2. Parse proposals
+
+Scan file for lines matching `### Proposal N — [TYPE] ...`. Extract each proposal block (Why / Change / Risk).
+
+If `--filter <TYPE>` given: skip proposals whose type tag doesn't match.
+
+Print: "Found N proposals (N after filter)."
+
+### 3. Review loop
+
+For each proposal (in order):
+
+Print the full proposal block:
+```
+─────────────────────────────────────────
+Proposal N/TOTAL — [TYPE] Title
+Risk: low|medium
+
+Why: ...
+Change: ...
+─────────────────────────────────────────
+(a) apply   (s) skip   (e) edit   (q) quit
+```
+
+If `--dry-run`: print `[dry-run — would prompt here]` and continue to next proposal without prompting.
+
+Based on user choice:
+- **a** — apply (see Apply Logic below)
+- **s** — mark proposal as `**Reviewed: skipped**` in the reflections file; continue
+- **e** — show the Change text, ask user to provide edited version, then apply the edited version
+- **q** — stop processing; print "Stopped at proposal N. Resume with `/gdd:apply-reflections --cycle <slug>`."
+
+### 4. Apply Logic by Proposal Type
+
+After the user chooses `a` (apply) or `e` (edit-then-apply), branch on the proposal's bracketed type tag and follow the per-type apply procedure in `./apply-reflections-procedure.md` — one numbered procedure each for `[FRONTMATTER]`, `[REFERENCE]`, `[BUDGET]`, `[QUESTION]`, `[GLOBAL-SKILL]`. All branches end with `**Applied**: <date>` appended to the proposal block in the reflections file.
+
+### 5. Summary
+
+After all proposals processed (or `q`):
+```
+─────────────────────────────────────────
+Apply-reflections complete
+  Applied:  N
+  Skipped:  N
+  Remaining: N (run again to continue)
+─────────────────────────────────────────
+```
+
+## [INCUBATOR]
+
+Incubator drafts authored by `scripts/lib/incubator-author.cjs` (Phase 29-04) appear as a distinct proposal class. For each draft under `.design/reflections/incubator/<slug>/`, use `scripts/lib/apply-reflections/incubator-proposals.cjs`:
+
+1. `discoverIncubatorDrafts()` → list pending drafts.
+2. `renderProposal(draft)` → show full body + diff + origin signals.
+3. User chooses **accept** | **reject** | **defer** | **edit**.
+4. **accept** — scope-guard runs FIRST (`validateScope` from `scripts/validate-incubator-scope.cjs`); `applyAccept` then promotes draft → `agents/<slug>.md` or `skills/<slug>/SKILL.md` and appends a registry entry. Single-step per D-04.
+5. **reject** — `applyReject` removes the incubator subdir.
+6. **defer** — no-op; draft re-surfaces next run.
+7. **edit** — `applyEdit` opens `$EDITOR`; re-prompt user on close.
+
+**Stage-1 gate.** At session start, call `checkStage1Gate()`. If `thresholdMet && !optInRecorded`, display the opt-in prompt once. NEVER auto-flip per D-01 — recording opt-in requires explicit user confirmation via `recordOptIn()`. Full procedure: `./apply-reflections-procedure.md` §[INCUBATOR].
+
+## [KFM-CANDIDATE]
+
+KFM-catalogue proposals authored by `scripts/lib/reflector-kfm-proposer.cjs` (Phase 30.5-03 D-05) appear as a 6th proposal class. Drafts at `.design/reflections/incubator/kfm-<slug>/CATALOGUE-ENTRY.md`; pre-filled 11-field schema with `TODO:` placeholders for `pattern` + `fix`. Two upstream signals share the surface (D-06): `capability_gap` clusters (≥3, no existing match) + `kfm-candidate` events (whitelist-matched articles, 1-shot). User chooses **accept** | **reject** | **defer** | **edit**. `applyAccept` appends to `reference/known-failure-modes.md` + `reference/registry.json` (`origin: incubator-kfm`); `applyReject` removes the incubator subdir; `applyDefer` stamps `deferred_until`; `applyEdit` returns the draft path for `$EDITOR`. Full procedure: `./apply-reflections-procedure.md` §[KFM-CANDIDATE].
+
+## Do Not
+
+- Do not apply any proposal without the user explicitly choosing `a` or `e`.
+- Do not modify source code files (`.ts`, `.tsx`, `.css`, `.js`) — only agent files, reference files, budget.json, discussant questions, global skills, and incubator drafts.
+- Do not re-run the reflector — this skill only applies existing proposals.
+- Do not bypass the scope guard or auto-flip Stage-1 — both are non-negotiable per D-05 / D-01.

package/dist/claude-code/.claude/skills/apply-reflections/apply-reflections-procedure.md

@@ -0,0 +1,170 @@
+---
+name: apply-reflections-procedure
+type: heuristic
+version: 1.3.0
+phase: 30.5
+tags: [apply-reflections, proposal, frontmatter, reference, budget, question, global-skill, incubator, kfm-candidate]
+last_updated: 2026-05-21
+---
+
+# Apply-Reflections — Per-Type Procedure
+
+Extracted from `skills/apply-reflections/SKILL.md` per Phase 28.5 D-10 (extract-then-link,
+never delete content). The orchestrator loop in `apply-reflections` (resolve file → parse →
+review loop → summary) stays in the SKILL. The per-proposal-type apply logic below moves
+here because it is content-class methodology, not workflow.
+
+## Apply Logic by Proposal Type
+
+After the user chooses `a` (apply) or `e` (edit-then-apply) in the review loop, branch by
+the proposal's bracketed type tag.
+
+### [FRONTMATTER]
+
+1. Extract agent name from Change field (e.g., `agents/design-verifier.md`)
+2. Read the agent file
+3. Find the frontmatter line matching the field being changed
+4. Use Edit tool to update the specific line
+5. Append `**Applied**: <date>` to the proposal in reflections file
+
+### [REFERENCE]
+
+1. Extract target file path from Change field (e.g., `reference/heuristics.md`)
+2. If file exists: append the drafted text using Edit tool
+3. If file doesn't exist: create it with a minimal header + the drafted text using Write tool
+4. Append `**Applied**: <date>` to proposal in reflections file
+
+### [BUDGET]
+
+1. Read `.design/budget.json`
+2. Locate the key path from the Change field (e.g., `design-verifier.per_run_cap_usd`)
+3. Update the value
+4. Write updated JSON back to `.design/budget.json`
+5. Append `**Applied**: <date>` to proposal in reflections file
+
+### [QUESTION]
+
+1. Read `agents/design-discussant.md`
+2. Find the question text specified in the Change field
+3. If pruning: remove the question lines using Edit tool
+4. If rewording: replace the question text using Edit tool
+5. Append `**Applied**: <date>` to proposal in reflections file
+
+### [GLOBAL-SKILL]
+
+1. Extract target filename from Change field (e.g., `design-color-conventions.md`)
+2. Ensure `~/.claude/gdd/global-skills/` directory exists (create with `mkdir -p` if not)
+3. If target file exists: append new content using Edit tool (add a `---` separator first)
+4. If target file doesn't exist: create with header + content using Write tool:
+
+   ```markdown
+   # <Topic> Conventions (Global)
+   *Promoted from project: <project-name>, cycle: <cycle-slug>*
+
+   <content>
+   ```
+
+5. Print: "Global skill written to ~/.claude/gdd/global-skills/<name>.md — auto-loads in all future gdd sessions"
+6. Append `**Applied**: <date>` to proposal in reflections file
+
+### [INCUBATOR]
+
+Incubator drafts come from `scripts/lib/incubator-author.cjs` (Phase 29-04). They live at
+`.design/reflections/incubator/<slug>/` and contain `manifest.json` + `DRAFT.md` + (optional) `ORIGIN.md`.
+
+Use `scripts/lib/apply-reflections/incubator-proposals.cjs` for all actions.
+
+**Discovery + render** (once per cycle):
+
+1. Call `discoverIncubatorDrafts()` → `Array<Draft>`. Skip malformed entries silently (already warned on stderr by the helper).
+2. For each draft: call `renderProposal(draft)` and print the returned markdown block. The user sees a header (slug + kind), a diff vs the nearest existing artifact (or "net-new"), an Origin section listing capability-gap signals, and the full draft body.
+3. Prompt: `(a) accept   (r) reject   (d) defer   (e) edit   (q) quit`.
+
+**Per-action behavior:**
+
+1. **accept** — call `applyAccept(draft, { registryPath, repoRoot })`.
+   - The helper calls `validateScope(draft.target_path)` from `scripts/validate-incubator-scope.cjs` **before** any write. Out-of-scope paths throw and the registry stays untouched. This is the non-bypassable scope guard (D-05).
+   - On success: target artifact written, `reference/registry.json` appended with `{ slug, path, added, origin: 'incubator' }`, incubator subdir removed last (T-29.05-04 — partial-failure leaves draft retryable).
+   - Print: "Accepted — promoted to <target_path>; registered."
+   - Append `**Applied**: <date>` to the proposal block.
+
+2. **reject** — call `applyReject(draft)`. Only the incubator subdir is removed; registry is untouched. Append `**Reviewed: rejected**` to the reflections file.
+
+3. **defer** — no-op. Print "Deferred — draft re-surfaces next run." Append `**Reviewed: deferred**`.
+
+4. **edit** — call `applyEdit(draft)` (uses `$EDITOR` or the `editorCmd` array option). On clean exit, the helper reloads the draft and the caller re-runs `renderProposal` + the prompt. On non-zero exit, the original draft is preserved unchanged.
+
+**Stage-1 gate (D-01 — no auto-flip):**
+
+1. At the start of the cycle, call `checkStage1Gate({ gateSpecPath, statePath, registryPath })`. The call is **read-only** — never mutates state. The returned `{ thresholdMet, summary, optInRecorded }` is informational.
+2. If `thresholdMet && !optInRecorded`, surface a one-time prompt:
+   ```
+   Stage-1 capability-gap authoring threshold met: <summary>
+   Enable incubator-draft promotion?  (y/N)
+   ```
+3. **Only on explicit `y`**, call `recordOptIn({ statePath, confirmedBy })`. The function is idempotent — a second call detects the existing record and returns `{ alreadyRecorded: true }`. Never call it on any other input.
+
+**Why this is gated.** The `[INCUBATOR]` proposal class can write executable surface (agents + skills) into the plugin runtime. Both Phase 29 D-01 (no auto-flip) and D-05 (scope guard) exist because that surface has integration-test and security implications that exceed reflector autonomy. `validateScope` keeps the file landing zone confined to `agents/<slug>.md` or `skills/<slug>/SKILL.md`. The Stage-1 gate keeps the *whether* of opting in to incubator authoring under explicit user control even after the data threshold says we have enough signal.
+
+**Bandit-fairness gate on `accept` (Phase 29 Plan 06 / CONTEXT D-04).**
+
+When the `accept` action promotes an incubator draft, the bandit-router arms for the freshly-promoted agent/skill MUST be bootstrapped with `prior_class: 'promoted_incubator'`. This invokes a conservative `Beta(2, 8)` bootstrap prior (posterior mean 0.2) instead of the optimistic Phase 23.5 informed prior — the bandit-fairness gate IS the staging mechanism (D-04: no separate two-step ratify split). The conservative prior suppresses preferential selection until ~8-10 successful pulls accumulate.
+
+Call shape (whether eagerly invoked on promotion or via first-pull lazy bootstrap):
+
+```javascript
+const bandit = require('./scripts/lib/bandit-router.cjs');
+// Per arm bootstrapped for the freshly-promoted agent:
+bandit.update({
+  agent: '<promoted-slug>',
+  bin: '<touches-bin>',
+  tier: '<chosen-tier>',
+  reward: <bernoulli>,
+  prior_class: 'promoted_incubator',  // Phase 29 Plan 06 / D-04 — Beta(2,8) staging
+});
+// Or for the delegate-aware case (Plan 27-07):
+bandit.updateWithDelegate({
+  agent: '<promoted-slug>',
+  bin: '<touches-bin>',
+  tier: '<chosen-tier>',
+  delegate: '<peer-cli-or-none>',
+  reward: <bernoulli>,
+  prior_class: 'promoted_incubator',
+});
+```
+
+Omitting `prior_class` reverts to Phase 23.5 informed-prior bootstrap (non-breaking). The reward math is unchanged — `prior_class` only affects bootstrap.
+
+### [KFM-CANDIDATE]
+
+Known-failure-mode catalogue proposals come from `scripts/lib/reflector-kfm-proposer.cjs` (Phase 30.5-03 D-05). They live at `.design/reflections/incubator/kfm-<slug>/CATALOGUE-ENTRY.md` and contain a single fenced ```yaml block pre-filled with the Phase 30.5 schema-v2 11-field shape (`id` + `pattern` + `diagnosis` + `remedy` + `severity` + `propose_report` + `symptom` + `root_cause` + `fix` + `related_phases` + `first_observed_cycle`). Two of those — `pattern` and `fix` — are `TODO:` placeholders the reflector cannot infer; the user fills them via the **edit** action before accepting.
+
+Two upstream signals share this draft surface (D-06):
+- `capability_gap` clusters of size ≥3 with no existing-entry match (Phase 29-03 aggregator + `failure-mode-matcher.match()`).
+- `kfm-candidate` events from the Phase 30.5-03 Task 2 authority-watcher whitelist (D-06 — single events bypass the ≥3 gate).
+
+Use `scripts/lib/reflector-kfm-proposer.cjs` for all actions:
+
+**Discovery + render** (once per cycle):
+
+1. Glob `.design/reflections/incubator/kfm-*/CATALOGUE-ENTRY.md` → list pending KFM drafts.
+2. For each draft: read the body, show the origin header (source, parent event ids OR article url) + the proposed yaml block.
+3. Prompt: `(a) accept   (r) reject   (d) defer   (e) edit   (q) quit`.
+
+**Per-action behavior:**
+
+1. **accept** — call `applyAccept(draftPath, { repoRoot })`.
+   - The helper re-stamps the proposed `id` with the next available `KFM-NNN` from the catalogue (avoids collisions when multiple drafts promote in the same run).
+   - Appends a `### KFM-NNN — <symptom heading>` section into `reference/known-failure-modes.md` with the yaml block intact.
+   - Appends a `reference/registry.json` entry: `{ name: 'known-failure-modes/kfm-NNN', path: 'reference/known-failure-modes.md', type: 'failure-mode', phase: 30.5, origin: 'incubator-kfm', added: '<ISO date>' }`.
+   - Removes the incubator subdir LAST (partial-failure leaves the draft retryable).
+   - Print: "Accepted — promoted to KFM-NNN in reference/known-failure-modes.md."
+   - Append `**Applied**: <date>` to the proposal entry (when surfaced from a reflections file).
+
+2. **reject** — call `applyReject(draftPath)`. Only the incubator subdir is removed; catalogue + registry untouched. Print: "Rejected — draft removed."
+
+3. **defer** — call `applyDefer(draftPath, { deferredUntil })` where `deferredUntil` is an ISO date (default: today + 30d). The helper stamps `deferred_until: <ISO>` into the draft body. Print: "Deferred — draft re-surfaces next run."
+
+4. **edit** — call `applyEdit(draftPath)` which returns the draft path. The caller opens `$EDITOR` on the path; on clean exit, re-discover the draft and re-prompt. Typical edits: replace `pattern: 'TODO: ...'` with a conservative regex, replace `fix: 'TODO: ...'` with a step-by-step user-runnable remedy, set `severity` if `medium` default is wrong.
+
+**Why this is gated.** `reference/known-failure-modes.md` feeds Phase 30's `triage-matcher.cjs` BEFORE the consent prompt — a bad entry could mute legitimate issue reports. The user-review gate is non-negotiable (D-05). The proposer is strictly proposal-only; the canonical catalogue only changes via the accept action.

package/dist/claude-code/.claude/skills/audit/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: gdd-audit
+description: "Run a design audit by spawning design-auditor, design-integration-checker, and (optionally) design-verifier + design-reflector agents, then printing a consolidated 6-pillar score summary. Use when the user wants to score the current design, retroactively verify a completed cycle, or quickly re-check after a fix."
+argument-hint: "[--retroactive] [--quick] [--no-reflect]"
+tools: Read, Write, Task, Glob, Bash
+---
+
+# /gdd:audit
+
+Wraps the existing `design-auditor`, `design-verifier`, and `design-integration-checker` agents — no new auditor logic here. Parses flags, spawns the right combination, prints summary.
+
+For the 6-pillar scoring rubric this skill aggregates, see `../../reference/audit-scoring.md`. For the shared design-quality pillar set that frames the score categories, see `../../reference/shared-preamble.md`.
+
+## Modes
+
+### Default
+Spawn `design-auditor` (6-pillar scoring 1–4) in parallel with `design-integration-checker`. After both finish, read `.design/DESIGN-AUDIT.md` and `.design/DESIGN-INTEGRATION.md` and print a consolidated summary (scores + top 3 findings each).
+
+After the auditor and integration checker complete, check if `.design/learnings/` exists and contains at least one `.md` file. If so — and unless `--no-reflect` is passed — spawn `design-reflector` for the current cycle. Append the reflection proposal count to the audit summary: "Reflection: N proposals → review with `/gdd:apply-reflections`".
+
+### `--retroactive`
+Spawn `design-verifier` with cycle-span scope. Verifier reads all tasks completed in the current cycle (from STATE.md `<completed_tasks>` list for the active `cycle:` ID) and uses `DESIGN-PLAN.md` goals as the reference baseline for what "should have been done." Output: `.design/DESIGN-VERIFICATION.md` with per-task pass/fail.
+
+### `--quick`
+Run only `design-auditor` (skip `design-integration-checker`). Faster health check when integration isn't the concern.
+
+## Steps
+
+1. Parse args for `--retroactive`, `--quick`, and `--no-reflect`.
+2. Verify `.design/STATE.md` exists; abort if not (suggest `/gdd:new-project`).
+3. Spawn the appropriate agents (Task tool). Default and `--retroactive` spawn two agents; `--quick` spawns one.
+4. Wait for completion, then read each output file and print a summary:
+   - Auditor scores per pillar
+   - Integration check pass/fail
+   - Verifier pass/fail per task (retroactive mode)
+5. **Reflection step** (default + retroactive modes only, skipped with `--no-reflect` or `--quick`):
+   - Check if `.design/learnings/` exists and has ≥1 `.md` file
+   - If yes: spawn `design-reflector` for the current cycle slug (read from STATE.md)
+   - After completion: count proposal types and append to summary
+6. Recommend next action based on findings (e.g., "Score 2/4 on typography — run `/gdd:discuss typography` to gather decisions").
+
+## Registered Audit Agents
+
+| Agent | Trigger | Output |
+|---|---|---|
+| `design-auditor` | Default, retroactive | `.design/DESIGN-AUDIT.md` |
+| `design-integration-checker` | Default, retroactive | `.design/DESIGN-INTEGRATION.md` |
+| `design-verifier` | `--retroactive` only | `.design/DESIGN-VERIFICATION.md` |
+| `design-reflector` | Default + retroactive when learnings exist | `.design/reflections/<slug>.md` |
+
+## Do Not
+
+- Do not modify source files.
+- Do not rerun stages; this is a read-only audit.
+
+## Step 7 — Update notice (post-closeout surface)
+
+After the consolidated audit summary has been printed (and any reflection-proposal count appended), emit the plugin-update banner if one is present:
+
+```bash
+[ -f .design/update-available.md ] && cat .design/update-available.md
+```
+
+Written by `hooks/update-check.sh`; suppressed mid-pipeline and when the latest release is dismissed.
+
+## Rationalizations — Thought to Reality
+
+The excuses an agent reaches for to skip or thin out an audit, and the drift each one misses:
+
+| Thought | Reality |
+|---------|---------|
+| "The audit passed last cycle, I can skip it this cycle." | Per-cycle audit catches drift the prior pass couldn't see; a skipped review is exactly where regressions accumulate unnoticed. |
+| "`--quick` is fine, integration isn't the concern here." | Dropping the integration-checker hides orphaned decisions — wiring breaks even when the 6-pillar score looks healthy. |
+| "I can eyeball the scores instead of spawning the auditor." | The auditor's rubric scores six pillars consistently; an eyeballed review drifts toward whatever the agent already believes. |
+| "Reflection proposals are optional polish, skip the reflector." | The reflector turns this cycle's learnings into next-cycle improvements; skipping it lets the same mistakes repeat. |
+| "I'll modify the source while I'm in here fixing findings." | Audit is read-only by contract; editing source mid-audit invalidates the very scores you're producing. |
+| "Retroactive mode is overkill for a finished cycle." | Retroactive verification is the only check on tasks that shipped without per-task verify — skipping it leaves a completed cycle unaudited. |
+
+## AUDIT COMPLETE