@hegemonart/get-design-done 1.28.7 → 1.30.0

package/agents/design-reflector.md

@@ -35,6 +35,18 @@ Read flow:
 
 Legacy grep-based parsing of skill outputs is preserved as a fallback for skills that haven't yet migrated to emit `reflection.proposal` events (Phase 22 scope). If no `reflection.proposal` events are present in the stream, run the legacy harvest across `.design/learnings/*.md` and `.design/intel/` exactly as before — both paths produce the same Proposals section format.
 
+## Capability-gap pattern scan (Phase 29 Plan 02)
+
+During the reflection pass, also run the capability-gap pattern scan to detect recurring patterns lacking a dedicated executable owner. The scan emits `capability_gap` events with `source: "reflector_pattern"` for Plan 29-03 to aggregate.
+
+```
+node -e "console.log(JSON.stringify(require('./scripts/lib/reflector/capability-gap-scan.cjs').runCapabilityGapScan(), null, 2))"
+```
+
+The scan reads three signal sources: `.design/intel/*.md` `Touches:` clusters, `.design/telemetry/posterior.json` high-usage arms with no specialized agent, and recent `.design/gep/events.jsonl` decision sequences. MCP-probe failures (`outcome === 'connection-error'`, `agent === 'mcp-probe'`, or `mcp_probe: true`) do NOT trigger gap events (CONTEXT D-08). See @skills/reflect/procedures/capability-gap-scan.md for the full contract.
+
+Cite the returned `emittedEventIds` in the run summary under a `## Capability gaps emitted` heading. The threshold knob is `reflector.capability_gap_threshold` in `.design/config.json` (default `N=3`, integer ≥ 1).
+
 ## Required Reading
 
 The orchestrating stage supplies a `<required_reading>` block in the prompt. Read every listed file before acting — this is mandatory.
@@ -52,6 +64,8 @@ Minimum expected inputs (skip gracefully if absent, note what's missing):
 
 Write `.design/reflections/<cycle-slug>.md`. If `--dry-run` is set in the spawning prompt, print proposals to stdout only — do not write the file.
 
+If the capability-gap pattern scan emitted any events during this run, include a `## Capability gaps emitted` heading listing each `event_id` with the source signal kind (`intel` | `posterior` | `trajectory`) and the `suggested_kind` (`agent` | `skill`) per event. Plan 29-03 reads these events from `.design/gep/events.jsonl` to cluster recurring `capability_gap` events for `/gdd:apply-reflections`.
+
 Terminate with `## REFLECTION COMPLETE`.
 
 ## Reflection Sections
@@ -203,6 +217,42 @@ Render each `bandit_arbitrage` entry into the Proposals section as a `[FRONTMATT
 
 ---
 
+### 9. Capability gaps observed (Phase 29 — D-01 / D-03)
+
+**Why this exists:** Plans 29-01 and 29-02 emit `capability_gap` events to `.design/gep/events.jsonl` whenever `/gdd:fast`, `gdd-router`, or the reflector pattern-detection pass identifies a lookup-fail with no dedicated owner. This section surfaces those events as clusters in the cycle markdown and evaluates the Stage-0 → Stage-1 gate per `reference/capability-gap-stage-gate.md`.
+
+**Data sources:**
+
+- `.design/gep/events.jsonl` — the Phase 22 causal event chain. Rows where `type === 'capability_gap'` (or `outcome === 'capability_gap'`) are aggregated by `payload.context_hash`.
+- `.design/config.json` (optional) — `capability_gap_gate.{K, M, stddev_threshold}` overrides. Defaults: `K=3`, `M=10`, `stddev_threshold=0.05` per D-03.
+
+**The mechanism:**
+
+1. Invoke `scripts/lib/reflections-cycle-writer.cjs` via Bash with `--chain=.design/gep/events.jsonl` and (when available) `--history=<path>` pointing at an array of prior cycle cluster lists.
+2. The shim calls `aggregateCapabilityGaps()` from `scripts/lib/reflector-capability-gap-aggregator.cjs` which clusters events by `context_hash`, caps each cluster's example evidence at 3, and orders by size desc.
+3. The shim calls `renderGapsSection(clusters)` which returns the `## Capability gaps observed` markdown block. The block is empty (no header emitted) when there are no clusters in this cycle — the cycle markdown is unchanged.
+4. When `--history` is supplied AND at least M cycles have been observed, the shim also calls `evaluateStageGate(history, config)`. If the gate is crossed AND `.design/config.json` does NOT already carry `capability_gap_gate.user_prompted_at`, a one-time prompt block is appended (verbatim text in `reference/capability-gap-stage-gate.md` § 5).
+
+**Bash invocation (executor follows verbatim):**
+
+```bash
+node scripts/lib/reflections-cycle-writer.cjs \
+  --chain=.design/gep/events.jsonl \
+  --config=.design/config.json
+```
+
+Append stdout to the cycle markdown body (after Section 8 / before the Proposals header). If `--history=<path>` is wired by a future cycle-aggregator, add the flag. For Stage 0 (this phase), per-cycle cluster aggregation alone is the deliverable — gate evaluation surfaces additively when history is present.
+
+**Important discipline (D-01 lock):**
+
+- This section NEVER auto-flips `capability_gap_gate.stage` or any other runtime state. The output is markdown only; the user opts in via Plan 29-05's apply-reflections extension.
+- The shim is read-only with respect to `.design/config.json`. The only state-mutating writer is the user-driven opt-in path (deferred to 29-05).
+- `evidence_refs[]` content is rendered as-is in the markdown table examples column — per the plan's threat model T-29.03-04, evidence refs are trusted-content (file:line or event-id strings from the 29-01 schema).
+
+**Helper:** `scripts/lib/reflector-capability-gap-aggregator.cjs` exports `aggregateCapabilityGaps`, `renderGapsSection`, `evaluateStageGate`. The shim wraps these for invocation from the agent prompt; tests in `tests/reflector-capability-gap-aggregation.test.cjs` cover the helper directly with synthetic fixtures (D-11).
+
+---
+
 ## Proposals
 
 After all sections, write a **Proposals** section. Number proposals sequentially. Every proposal must include evidence — no vague observations.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.28.7",
+  "version": "1.30.0",
   "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",
@@ -38,11 +38,13 @@
     "provenance": true
   },
   "scripts": {
+    "build:bundles": "node scripts/build-distribution-bundles.cjs",
     "test": "node --test --experimental-strip-types \"tests/**/*.test.cjs\" \"tests/**/*.test.ts\"",
     "typecheck": "tsc --noEmit",
     "codegen:schemas": "node --experimental-strip-types scripts/codegen-schema-types.ts",
     "lint:md": "npx --yes markdownlint-cli2 \"**/*.md\" \"#node_modules\" \"#.planning\" \"#.claude\" \"#test-fixture/baselines\"",
     "lint:links": "npx --yes lychee --no-progress --accept 200,206,403,429 \"**/*.md\" || true",
+    "lint:agentskills": "node scripts/lint-agentskills-spec.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/capability-gap-stage-gate.md

@@ -0,0 +1,261 @@
+# Capability-Gap Stage-0 → Stage-1 Gate Specification
+
+> Phase 29 reference doc. Specifies the deterministic gate that decides when
+> the reflector has gathered enough `capability_gap` signal to surface a
+> one-time opt-in prompt for Stage-1 (incubator authoring of new agents /
+> skills). **No code path in this repository auto-flips the stage** —
+> D-01 is the discipline.
+
+---
+
+## 1. Overview
+
+Phase 29 ships in two stages:
+
+- **Stage 0** (Wave A, v1.29.0) emits `capability_gap` events from
+  `/gdd:fast` no-skill-match (Plan 29-01), `gdd-router` unmatched-intent
+  (Plan 29-01), and the reflector pattern-detection pass (Plan 29-02).
+- **Stage 1** (Wave B) layers incubator authoring of agents and skills on
+  top of the Stage-0 signal (Plans 29-04 / 29-05 / 29-06).
+
+The transition Stage 0 → Stage 1 is **gated on data**, not on a calendar
+date or a release. The reflector aggregates events into per-cycle
+clusters (`scripts/lib/reflector-capability-gap-aggregator.cjs`) and
+evaluates a deterministic stability function against the project's
+cycle history. When the gate is crossed, `/gdd:apply-reflections`
+emits a **one-time user-facing prompt** in the cycle markdown — never
+an auto-stage-flip. The user opting in is a separate explicit action,
+out of scope for this gate spec.
+
+Reference: **Phase 29 CONTEXT.md decision D-01** (two-stage approach;
+user opts in per a one-time prompt; if data is thin, Stage 1 never
+auto-enables).
+
+---
+
+## 2. Default thresholds
+
+The gate has three knobs, all set in `.design/config.json`
+under the `capability_gap_gate` key. Defaults:
+
+| Knob | Default | Meaning |
+|------|---------|---------|
+| `K` | `3` | Minimum number of **stable clusters** required to cross the gate. |
+| `M` | `10` | Minimum number of **consecutive cycles** a cluster must appear in to be considered for stability. |
+| `stddev_threshold` | `0.05` | Maximum allowed posterior `stddev(Beta(α, β))` for a cluster to be considered stable. |
+
+All three are overridable via `.design/config.json`:
+
+```jsonc
+{
+  "capability_gap_gate": {
+    "K": 3,
+    "M": 10,
+    "stddev_threshold": 0.05
+  }
+}
+```
+
+Reference: **Phase 29 CONTEXT.md decision D-03** (defaults are starting
+points; first-N-users data should refine).
+
+Validation: `K` must be a positive integer, `M` a positive integer,
+`stddev_threshold` a number in `(0, 1]`. The evaluator silently falls
+back to defaults if any value is invalid (T-29.03-02 mitigation in the
+plan's threat model).
+
+---
+
+## 3. Stability formula
+
+A cluster `c` is **stable** iff both conditions hold:
+
+1. **Consecutive presence.** `c` appears in `≥ M` consecutive cycles
+   somewhere within the observed history. (The most recent unbroken
+   run is what matters — if a cluster missed a cycle, the run resets
+   and only the longest streak counts.)
+2. **Narrow posterior.** The closed-form posterior standard deviation
+   of the Beta distribution satisfies:
+
+   ```
+   stddev(Beta(α, β)) = sqrt( (α · β) / ((α + β)² · (α + β + 1)) )
+   ```
+
+   with the Laplace prior (matches Phase 23.5's bandit-router posterior
+   store):
+
+   ```
+   α = appearances + 1
+   β = (cycles_observed − appearances) + 1
+   ```
+
+   where `appearances` is the total number of cycles in which `c` was
+   present (across the full history, not just the M-window) and
+   `cycles_observed = history.length`.
+
+**Worked example.** A cluster present in 25 of the 30 observed cycles
+with a longest consecutive run of 18 has `α = 26`, `β = 6`, so
+`stddev ≈ sqrt((26·6)/(32²·33)) ≈ sqrt(0.0154) ≈ 0.124`. That fails
+the default `stddev_threshold = 0.05`. To clear `0.05`, that same
+cluster would need closer to 30/30 presence or a longer history.
+
+**Cross-link.** The closed-form Beta-stddev is shared with Phase 23.5
+(see `scripts/lib/bandit-arbitrage.cjs` and the
+"Bandit-arbitrage analysis" section in `agents/design-reflector.md`).
+The same posterior is what gates frontmatter-tier corrections; here it
+gates stage transition.
+
+---
+
+## 4. Evaluation cadence
+
+Gate evaluation runs every time `/gdd:apply-reflections` is invoked.
+Inputs:
+
+1. The reflector pass collects all cycle markdown files in
+   `.design/reflections/` and parses the `## Capability gaps observed`
+   sections (emitted by `renderGapsSection` in
+   `scripts/lib/reflector-capability-gap-aggregator.cjs`).
+2. The per-cycle cluster lists are folded into a history array of
+   `{ cycle_slug, clusters }` entries.
+3. `evaluateStageGate(history, config)` is called once and returns:
+
+   ```ts
+   { crossed: boolean, stable_cluster_ids: string[], cycles_observed: number }
+   ```
+
+4. If `crossed === true` and the project has not previously opted in
+   (see § 6), the prompt in § 5 is emitted into the cycle markdown.
+
+The evaluation is **deterministic** (no randomness), **idempotent**
+(no side-effects in the evaluator), and **read-only** with respect to
+`.design/config.json` — that file is only updated by the user's
+explicit opt-in action, never by the reflector.
+
+---
+
+## 5. Gate-crossed prompt
+
+When the gate crosses for the first time, `/gdd:apply-reflections`
+appends the following verbatim block to the cycle markdown:
+
+> ```markdown
+> ## Stage-0 → Stage-1 gate crossed — opt-in required
+>
+> Capability-gap detection has accumulated enough signal across recent
+> cycles to consider enabling Stage-1 (incubator authoring of new
+> agents / skills). The gate is informational only — **nothing has
+> changed in the runtime**, and Stage-1 will NOT auto-enable. Per
+> Phase 29 CONTEXT.md decision D-01, the user opts in explicitly.
+>
+> - Stable clusters observed: **<N>** (≥K = <K>)
+> - Cycles observed: **<cycles_observed>** (≥M = <M>)
+> - Stable cluster IDs (truncated):
+>   - `<cluster_id_1>`
+>   - `<cluster_id_2>`
+>   - `<cluster_id_3>`
+>
+> If you want to enable Stage-1 incubator authoring (Plans 29-04 / 29-05),
+> opt in with the project-local command below. You can always opt out
+> later by deleting the timestamps from `.design/config.json` (§ 7).
+>
+> <!-- TODO: confirm opt-in command — likely
+>      `node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" config set capability_gap_gate.opted_in_at "$(date -Iseconds)"`
+>      or a project-local equivalent. Plan 29-05 (apply-reflections
+>      extension) will land the canonical command. -->
+>
+> This prompt is emitted at most once per project. If you ignore it,
+> the gate continues to evaluate every cycle but does not re-prompt
+> (the `user_prompted_at` timestamp in `.design/config.json` suppresses
+> it). To re-trigger the prompt for a fresh round of evaluation, delete
+> `capability_gap_gate.user_prompted_at` from `.design/config.json`.
+> ```
+
+The wiring side of this — actually writing the `user_prompted_at`
+timestamp and routing the opt-in confirmation — is deferred to
+**Plan 29-05** (`/gdd:apply-reflections` extension). This document
+specifies the prompt text and behavior; 29-05 implements the
+state-machine that consumes it.
+
+---
+
+## 6. Opt-in semantics
+
+Two timestamps in `.design/config.json` track the project's gate state:
+
+```jsonc
+{
+  "capability_gap_gate": {
+    "K": 3,
+    "M": 10,
+    "stddev_threshold": 0.05,
+    "user_prompted_at": "2026-05-19T22:00:00.000Z",   // set when § 5 emitted
+    "opted_in_at": "2026-05-19T22:05:00.000Z"         // set when user opts in
+  }
+}
+```
+
+- **`user_prompted_at`** is set the first time the gate crosses and the
+  prompt block is rendered. The prompt is not re-emitted while this
+  timestamp is present.
+- **`opted_in_at`** is set when the user explicitly opts into Stage-1.
+  Stage-1 incubator authoring (Plans 29-04+) becomes active once this
+  timestamp is present. **Stage 1 is NEVER enabled by the reflector
+  setting this timestamp itself** — D-01 lock.
+
+Once `opted_in_at` is set, the gate stops emitting prompts entirely
+(it's a one-shot mechanism, not a continuous nudge).
+
+---
+
+## 7. Reset / override
+
+Operators can manually reset the gate by editing `.design/config.json`:
+
+| Effect desired | Action |
+|----------------|--------|
+| Re-prompt on next gate cross | Delete `capability_gap_gate.user_prompted_at`. |
+| Revert from Stage-1 to Stage-0 | Delete `capability_gap_gate.opted_in_at`. (Stage-1 artifacts in `.design/reflections/incubator/` are NOT removed by this; deletion is the user's call.) |
+| Tighten / loosen thresholds | Edit `K` / `M` / `stddev_threshold` directly. Out-of-range values silently fall back to defaults (§ 2). |
+
+Reset is **explicit** and **idempotent**. The reflector never writes
+to these fields on its own — the only writers are (a) the
+`/gdd:apply-reflections` opt-in path (Plan 29-05) and (b) the human
+operator editing the file by hand.
+
+---
+
+## 8. Test fixtures
+
+Executable examples that exercise the gate live in
+`tests/reflector-capability-gap-aggregation.test.cjs`:
+
+- **T3** — 30 cycles × 3 always-present clusters → gate crosses with
+  default K=3 / M=10 / stddev_threshold=0.05.
+- **T3b** — 10 cycles × 1 always-present cluster → gate does NOT
+  cross (posterior stddev ≈ 0.077 with α=11, β=1 is above the 0.05
+  threshold; M=10 is the lower bound on observations, not a
+  sufficient condition for stability).
+- **T4** — 30 cycles, 2 always-present clusters + 1 "noisy" cluster
+  present in only the first 4 cycles → gate does NOT cross
+  (`stable_cluster_ids.length === 2 < K=3`).
+- **T4b** — 5 cycles total → gate does NOT cross (`cycles_observed < M`).
+- **T7** — Confirms `K` and `stddev_threshold` overrides flow through
+  `normalizeConfig` and reach the evaluation.
+
+These fixtures are synthetic and inline (D-11). The gate evaluator
+never reads `.design/gep/events.jsonl` directly in CI — fixtures
+seed the cluster lists by hand.
+
+---
+
+## Decisions referenced
+
+- **D-01** — Two-stage approach: Stage 0 telemetry-only ships first;
+  Stage 1 authoring gated on data; user opts in per a one-time prompt;
+  no auto-flip.
+- **D-03** — Default `K=3` / `M=10` / `stddev_threshold=0.05`,
+  overridable via `.design/config.json`.
+- **D-11** — Tests use synthetic fixtures (no live event chain reads).
+- **Phase 23.5** — Posterior `stddev(Beta(α, β))` closed form and
+  Laplace prior convention reused here.

package/reference/known-failure-modes.md

@@ -0,0 +1,185 @@
+# Known Failure Modes (Phase 30 Triage Gate)
+
+This file is the **catalogue of locally-fixable failure modes** that the
+Phase 30 issue-reporter consults *before* prompting the user to file a
+GitHub issue. The triage gate runs first (D-07): when an entry matches
+the user's error, the gate surfaces `this looks like X — try Y` and
+exits the report flow without prompting. `--force-report` bypasses the
+gate but still requires consent (D-11).
+
+## Schema
+
+Each entry is a single fenced ```yaml block with this flat key:value shape:
+
+- `id` — stable identifier (kebab-case or `KFM-NNN` numeric). Required.
+- `pattern` — JavaScript regex string. Matched against
+  `[error.message, error.stack].filter(Boolean).join("\n")`. Required.
+- `diagnosis` — one-sentence plain-English root cause. Required.
+- `remedy` — one-sentence user-runnable action. Required.
+- `severity` — advisory only, one of `low` / `medium` / `high`. Required.
+- `propose_report` — boolean. If `true`, this mode is on the D-11
+  whitelist: 30-04 may *propose* `--report` at error time for this
+  class. Defaults to `false`. Advisory; the matcher does not act on it.
+
+## Matching policy
+
+- **First match wins.** Entries are evaluated in file order. The matcher
+  returns the first entry whose regex tests true against the haystack.
+  No severity ranking, no aggregation, no blending.
+- **Invalid regex is non-fatal.** An entry whose `pattern` fails to
+  compile is skipped with a `console.warn`, never crashes the matcher.
+- **Missing catalogue is non-fatal.** If this file is absent or
+  unparseable, `matchKnownFailure` returns `{ matched: false }` and
+  warns once.
+
+Consumed by `scripts/lib/issue-reporter/triage-matcher.cjs`
+(`matchKnownFailure(errorContext)`). Wired into `skills/report-issue`
+(Plan 30-04) before the consent prompt.
+
+## Entries
+
+### KFM-001 — EACCES on `.design/` write
+
+Permission failure when the plugin writes into `.design/`. Common after
+`sudo`-cloning a repo or running CI as a user without write access to
+the project root.
+
+```yaml
+id: KFM-001
+pattern: 'EACCES.*\.design'
+diagnosis: 'Permission denied writing to .design/ — the plugin cannot persist its work-product directory.'
+remedy: 'Run `chown -R "$USER" .design` (or recreate the directory as your normal user) and retry the command.'
+severity: medium
+propose_report: false
+```
+
+### KFM-002 — `gh` CLI not on PATH
+
+The Phase 30 outbound submission path requires the user's `gh` CLI
+(D-05). If it's missing, Plan 30-06 falls back to clipboard + URL.
+This entry catches the typical shell-spawn error.
+
+```yaml
+id: KFM-002
+pattern: '(gh: command not found|spawn gh ENOENT|''gh'' is not recognized)'
+diagnosis: 'GitHub CLI (`gh`) is not installed or not on PATH; the issue reporter''s outbound path relies on it.'
+remedy: 'Install gh from https://cli.github.com and run `gh auth login`, then retry. (Or use the clipboard fallback: the payload is already on disk under .design/issue-drafts/.)'
+severity: low
+propose_report: false
+```
+
+### KFM-003 — Node.js version mismatch
+
+`package.json` declares `engines.node: ">=22"`. Older Node versions
+crash on the `--experimental-strip-types` test runner, or fail subtle
+TypeScript-import behaviour.
+
+```yaml
+id: KFM-003
+pattern: '(engine "node" is incompatible|Unsupported engine|SyntaxError.*Unexpected token.*satisfies|--experimental-strip-types)'
+diagnosis: 'Active Node.js version is below the plugin''s required >=22; modern syntax features and the strip-types test runner are unavailable.'
+remedy: 'Upgrade Node to >=22 (e.g. `nvm install 22 && nvm use 22`) and rerun.'
+severity: high
+propose_report: false
+```
+
+### KFM-004 — Figma token missing
+
+Figma-aware flows expect `FIGMA_TOKEN` (or the documented env-var alias)
+to be present. The 401/missing-env error class is recognisable.
+
+```yaml
+id: KFM-004
+pattern: '(FIGMA_TOKEN.*(not set|missing|undefined)|Figma.*401|figma.*unauthor)'
+diagnosis: 'FIGMA_TOKEN environment variable is missing or invalid; Figma-dependent commands cannot authenticate.'
+remedy: 'Generate a personal access token at https://www.figma.com/developers/api#access-tokens and `export FIGMA_TOKEN=<token>` in your shell profile.'
+severity: medium
+propose_report: false
+```
+
+### KFM-005 — Git working tree dirty
+
+Several phase-tooling commands assume a clean working tree (clean
+checkpoints between cycles). A dirty tree surfaces as a stderr line
+the matcher can recognise.
+
+```yaml
+id: KFM-005
+pattern: '(working tree (is )?(not clean|dirty)|uncommitted changes|Changes not staged for commit)'
+diagnosis: 'Git working tree has uncommitted changes; the command requires a clean checkpoint before proceeding.'
+remedy: 'Commit, stash (`git stash -u`), or discard your local changes, then rerun the command.'
+severity: low
+propose_report: false
+```
+
+### KFM-006 — `.planning/` directory missing
+
+GSD/GDD project commands assume `.planning/` has been initialised by
+`/gsd:new-project`. A bare ENOENT on that path is a clear self-fix.
+
+```yaml
+id: KFM-006
+pattern: 'ENOENT.*\.planning'
+diagnosis: '.planning/ directory does not exist; the project has not been initialised yet.'
+remedy: 'Run `/gsd:new-project` to bootstrap the planning structure, then retry.'
+severity: medium
+propose_report: false
+```
+
+### KFM-007 — `reference/registry.json` invalid JSON
+
+The Phase 14.5 registry is hand-edited; a stray trailing comma or
+unquoted key surfaces here. Self-fixable, not a maintainer issue.
+
+```yaml
+id: KFM-007
+pattern: '(reference/registry\.json.*(SyntaxError|JSON|Unexpected token)|Unexpected token.*registry\.json)'
+diagnosis: 'reference/registry.json failed to parse as JSON — likely a trailing comma or unbalanced brace from a recent edit.'
+remedy: 'Open reference/registry.json in your editor; the JSON parser error message will pinpoint the line. Fix the syntax and retry.'
+severity: medium
+propose_report: false
+```
+
+### KFM-008 — MCP server unreachable
+
+When the Figma / GDD MCP servers are not running, commands depending
+on them fail with a clear connection-refused class of error.
+
+```yaml
+id: KFM-008
+pattern: '(MCP.*(unreachable|ECONNREFUSED|not connected)|mcp.*server.*not.*running|connection refused.*ws://)'
+diagnosis: 'An MCP server (Figma, GDD-state, or GDD-tools) is not reachable; the plugin cannot route tool calls through it.'
+remedy: 'Start the relevant MCP server (see scripts/mcp-servers/) and confirm `claude mcp list` shows it as connected.'
+severity: medium
+propose_report: true
+```
+
+### KFM-009 — Plugin file accidentally deleted
+
+A user-side `git clean -fdx` or aggressive editor refactor can remove
+plugin files. This is a re-install path, not a bug report path — but
+it's on the whitelist because users typically can't tell it apart from
+an upstream regression.
+
+```yaml
+id: KFM-009
+pattern: 'Cannot find module.*(scripts/lib/|skills/.*SKILL\.md|reference/.*\.md)'
+diagnosis: 'A plugin file is missing — most often the result of a local `git clean` or a partial install.'
+remedy: 'Reinstall the plugin: `npm install -g @hegemonart/get-design-done` (or pull the repo fresh in dev). If the file should exist, the error message gives its path.'
+severity: medium
+propose_report: true
+```
+
+### KFM-010 — Disk full / ENOSPC
+
+Out-of-space failures masquerade as obscure write errors. Self-fixable
+by freeing space; not a maintainer report path.
+
+```yaml
+id: KFM-010
+pattern: '(ENOSPC|no space left on device|disk full)'
+diagnosis: 'Disk is full — no space left on the device the plugin is writing to.'
+remedy: 'Free space (e.g. clear `.design/cache/`, prune old worktrees, empty trash) and retry.'
+severity: high
+propose_report: false
+```