@hegemonart/get-design-done 1.50.1 → 1.51.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.50.1"
+    "version": "1.51.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.50.1",
+      "version": "1.51.0",
       "author": {
         "name": "hegemonart"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.50.1",
+  "version": "1.51.0",
   "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 59 specialized agents, 88 skills, 41 connection integrations (Figma, Refero, Preview, Storybook, Chromatic, Graphify, Slack, Linear, Jira, Notion, and more), handoff-first workflow via Claude Design bundles, bidirectional Figma write-back (annotations, Code Connect), queryable intel store (`.design/intel/`) for O(1) design surface lookups, and self-improvement loop (reflector agent, frontmatter + budget feedback, global-skills layer at `~/.claude/gdd/global-skills/`). Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings, reflect, apply-reflections. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows, lint + schema + frontmatter + stale-ref + shellcheck + gitleaks + injection-scan + blocking size-budget) and release automation (auto-tag + GitHub Release + release-time smoke test). Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain. v1.27.7 ships gdd-mcp (Phase 27.7): 12 read-only MCP tools for sub-3s priming. v1.28.0 (Phase 28): Foundational References Tier 2 — 5 new reference files (color-theory, composition, proportion-systems, i18n, contrast-advanced), 2 verifier i18n probes + 1 explore i18n-readiness probe, 12 additive cross-link insertions across 10 existing references, 2 orthogonal audit-scoring lens-tags (composition_alignment + i18n_readiness).",
   "author": {
     "name": "hegemonart",

package/CHANGELOG.md

@@ -4,6 +4,52 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.51.0] - 2026-06-03
+
+### Phase 51 - Instinct-Based Learnings
+
+GDD's reflection loop was extractive, not predictive: `/gdd:extract-learnings` wrote a prose `LEARNINGS.md` that no
+downstream agent read. Phase 51 restructures learnings into atomic, confidence-weighted instinct units that are
+queryable, deduplicable, promotable, and surfaced back into agent context. Adapted from ecc's continuous-learning v2
+(project-vs-global scope). Planned and executed via the GSD pipeline (3 parallel executor subagents). No new runtime
+dependency, no new egress.
+
+### Breaking changes
+
+- **Reflection output gains atomic instinct units.** `design-reflector` now emits a `## Atomic instincts` section
+  (YAML units per `reference/instinct-format.md`) alongside a `## Narrative reflection` (dual-emit for one minor
+  version), and `/gdd:apply-reflections` gains an `[INSTINCT]` proposal class (accept/reject/defer/edit). Consumers of
+  the reflection format should read both sections.
+- **A new instinct store + schema.** `scripts/lib/instinct-store.cjs` is the source of truth (`.design/instincts/instincts.json`
+  project + `~/.claude/gdd/global-instincts.json` global); `reference/schemas/instinct.schema.json` is wired into
+  `validate:schemas` and enforces the unit shape (confidence 0.3-0.9, domain enum, scope, sha8 project_id).
+
+### Added
+
+- **`reference/instinct-format.md`** + **`reference/schemas/instinct.schema.json`**: the atomic instinct unit (YAML
+  frontmatter `id`/`trigger`/`confidence`/`domain`/`scope`/`project_id`/`source`/`cycles_seen`/`first_seen`/`last_seen`
+  with a prose body), the K=2/M=2 promotion gate, the Beta(2,8) prior, and TTL decay.
+- **`scripts/lib/instinct-store.cjs`**: JSON-canonical store with OPTIONAL FTS5 acceleration via
+  `probeOptional('better-sqlite3')` (the Phase 19.5 design-search pattern, so no dependency is added). Exports
+  `add`/`list`/`query`/`get`/`promote`/`touch`/`decay`/`deriveProjectId`; atomic writes; worktree-safe.
+- **`/gdd:instinct`** skill: `list` / `query "<keyword>"` (FTS5 or in-memory scan) / `promote <id>` (project to global,
+  gated on `cycles_seen >= 2` across `>= 2` distinct project ids; user-confirmed).
+- **Decision-injector integration**: `gdd-decision-injector.js` surfaces a top-3 `## Relevant instincts` block in
+  agent context (non-fatal; skipped when no store is present).
+- **TTL decay**: instincts not surfaced in 6 cycles decay (`confidence *= 0.9`); below 0.2 they archive. Wired into the
+  cleanup sweep. Three `instinct_*` event types seeded into `events.schema.json`. `extract-learnings` dual-emits.
+
+### Notes
+
+- 6-manifest lockstep at **v1.51.0** + `OFF_CADENCE_VERSIONS.add('1.51.0')` + 37 `manifests-version.txt` baselines.
+  Re-locked: skill-list (89), registry (176), phase-42 count (113), the events-schema sha256 snapshot,
+  resilience-primitives (40, +instinct-store.cjs), the phase-28.5 distribution + warn count (5 -> 8; apply-reflections
+  was trimmed back to <=110), skill-graph regenerated. Tarball golden 912 -> 917 (+5; the cleanup/injector/schema edits
+  are same-path).
+- Out of scope: cross-project federation, auto-skill-generation from instincts, embedding-based clustering, cross-runtime sync.
+
+---
+
 ## [1.50.1] - 2026-06-03
 
 ### Fixed

package/README.md

@@ -261,6 +261,8 @@ All 14 runtimes receive their native artifact layout (`skills/`, `command/`, `ag
 
 **Authoring contract v3 (v1.50.0).** Two additions. A verb-based anti-slop rubric (`reference/anti-slop-rubric.md`) scores five orthogonal axes (Directness, Distinctness, Hierarchy, Authenticity, Density); a sum below 35/50 routes a finding to the debt crawler as `aesthetic-slop`. It rides as a lens-tag on the existing 7-pillar audit, so it catches "generically AI-default" where the pillars catch "wrong". And a machine-parseable skill-composition manifest: optional `composes_with` / `next_skills` frontmatter, a DAG validator (`validate:composition-graph` fails on cycles or dangling refs), and an auto-generated `reference/skill-graph.md`. Skill descriptions move to a multi-paragraph v3 form (`<what>. Use when <triggers>. Activates for requests involving <kw>.`) with both forms accepted during a transition window, a boilerplate-cohort lint, and a `/gdd:new-skill` scaffolder. **No new runtime dependency.**
 
+**Instinct-based learnings (v1.51.0).** The reflection loop now produces atomic, confidence-weighted instinct units instead of prose nobody reads. Each unit (`reference/instinct-format.md`: trigger, confidence 0.3-0.9, domain, scope, project id) is stored via `scripts/lib/instinct-store.cjs` (a JSON store with optional `better-sqlite3` FTS5 acceleration, the same probe-and-fall-back pattern as cross-cycle recall, so no dependency is added). `design-reflector` dual-emits instincts plus a narrative; `/gdd:apply-reflections` accepts them; the decision-injector surfaces the top-3 relevant instincts into agent context on every design-file read; and `/gdd:instinct list|query|promote` inspects the project and global stores. A project instinct promotes to the global layer only after it recurs across at least two projects (a conservative `Beta(2,8)` prior keeps it advisory), and stale instincts decay and archive. **No new runtime dependency.**
+
 Verify with:
 
 ```

package/SKILL.md

@@ -2,7 +2,7 @@
 name: get-design-done
 short_name: gdd
 description: "Master design pipeline for Claude Code. 5-stage workflow: Brief → Explore → Plan → Design → Verify. Run 'brief' first in any new project to capture the design problem, then 'explore' to inventory the codebase and interview for context. Invoke without arguments for status and auto-routing."
-argument-hint: "[brief|explore|plan|design|verify|handoff|map|next|help|status|style|darkmode|live|compare|figma-write|graphify|discuss|list-assumptions|progress|health|todo|stats|note|plant-seed|add-backlog|review-backlog|scan|discover|settings|update|reapply-patches|audit|pause|resume|new-cycle|debug|quick|new-project|complete-cycle|fast|do|ship|undo|pr-branch|sketch|sketch-wrap-up|spike|spike-wrap-up|reflect|apply-reflections|analyze-dependencies|extract-learnings|skill-manifest|pin|unpin|list-pins|new-skill|warm-cache|optimize|cache-manager|watch-authorities|check-update|benchmark|recall|timeline|continue|zoom-out]"
+argument-hint: "[brief|explore|plan|design|verify|handoff|map|next|help|status|style|darkmode|live|compare|figma-write|graphify|discuss|list-assumptions|progress|health|todo|stats|note|plant-seed|add-backlog|review-backlog|scan|discover|settings|update|reapply-patches|audit|pause|resume|new-cycle|debug|quick|new-project|complete-cycle|fast|do|ship|undo|pr-branch|sketch|sketch-wrap-up|spike|spike-wrap-up|reflect|apply-reflections|analyze-dependencies|extract-learnings|skill-manifest|pin|unpin|list-pins|new-skill|instinct|warm-cache|optimize|cache-manager|watch-authorities|check-update|benchmark|recall|timeline|continue|zoom-out]"
 user-invocable: true
 ---
 
@@ -94,6 +94,7 @@ Each stage produces artifacts in `.design/` inside the current project.
 | `unpin <skill>` | `get-design-done:gdd-unpin` | Phase 46 - remove pinned aliases for a skill (only files carrying the gdd-pinned-skill marker) |
 | `list-pins` | `get-design-done:gdd-list-pins` | Phase 46 - show pinned aliases per harness with their source skill and last-pinned timestamp |
 | `new-skill <name>` | `get-design-done:gdd-new-skill` | Phase 50 - interactive scaffolder for a new Phase 28.5 + v3-compliant skill (multi-paragraph description, lifecycle stage, optional composes_with); writes source/skills/<name>/SKILL.md |
+| `instinct [list\|query <kw>\|promote <id>]` | `get-design-done:gdd-instinct` | Phase 51 - inspect and manage atomic instinct learning units (project + global stores); list, search by keyword, or promote a vetted project instinct to global once it clears the cross-project gate |
 | `quality-gate` | `get-design-done:quality-gate` | Phase 25 - parallel lint/type/test/visual command runner; classifies failures via quality-gate-runner agent |
 | `turn-closeout` | `get-design-done:turn-closeout` | Phase 25 - Stop-hook mirror skill; finalizes per-turn STATE blocks and emits closeout events |
 | `bandit-status` | `get-design-done:bandit-status` | Phase 27.5 - read-only diagnostic surface for the bandit posterior; per-(agent, bin, delegate, tier) snapshots (alpha, beta, mean, stddev, count, last-used). Use `/gdd:bandit-reset` to mutate. |

package/agents/design-reflector.md

@@ -257,6 +257,39 @@ Append stdout to the cycle markdown body (after Section 8 / before the Proposals
 
 ---
 
+## Atomic instincts
+
+Phase 51 adds atomic instinct units alongside the prose reflection. For each pattern you observed this cycle that is small enough to state as a single trigger plus a one-line response, emit a structured instinct unit. The narrative below stays for human reading; this section is the machine-readable twin. Both are emitted for one minor version so readers and tooling migrate together.
+
+Emit 0 to N units. Each unit follows `reference/instinct-format.md` exactly: YAML frontmatter (`id`, `trigger`, `confidence` from 0.3 to 0.9, `domain` from the format's enum, `scope`, `project_id`, `source`, `cycles_seen`, `first_seen`, `last_seen`) plus a short body. Set `source: design-reflector`. Set `confidence` from the strength of the evidence - a pattern seen once this cycle stays near 0.3 to 0.5; a pattern that recurs across prior learnings earns more. Do not exceed 0.9.
+
+A unit is a proposal, not a stored fact. You write the units here; the user accepts them via `{{command_prefix}}apply-reflections` (the `[INSTINCT]` class). Accepted units land in the store through `scripts/lib/instinct-store.cjs` `add(unit, { scope, baseDir })` at the emitted confidence. You never call `add()` yourself and you never write to `.design/instincts/instincts.json` directly.
+
+Emit each unit in a fenced `yaml` block so the apply step can parse it:
+
+```yaml
+id: in-<short-hash>
+trigger: <one-line condition that should fire this instinct>
+confidence: 0.45
+domain: <enum value from reference/instinct-format.md>
+scope: project
+project_id: <project id from STATE.md or deriveProjectId>
+source: design-reflector
+cycles_seen: 1
+first_seen: <ISO-8601>
+last_seen: <ISO-8601>
+---
+<one or two sentences: the response this instinct recommends and why>
+```
+
+If no pattern this cycle is atomic enough to state as a single trigger, write one line: "No atomic instincts this cycle." and move on. Do not pad.
+
+### Narrative reflection
+
+Keep the prose reflection for human readers. Summarize, in two to four sentences, the through-line of this cycle: what kept recurring, what shifted, and which instinct units above you have the most confidence in. This subsection is what a person skims; the units above are what tooling consumes.
+
+---
+
 ## Proposals
 
 After all sections, write a **Proposals** section. Number proposals sequentially. Every proposal must include evidence - no vague observations.

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

@@ -84,6 +84,23 @@ Incubator drafts authored by `scripts/lib/incubator-author.cjs` (Phase 29-04) ap
 
 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].
 
+## [INSTINCT]
+
+Atomic instinct units emitted by `design-reflector` (and surfaced from `/gdd:extract-learnings`) appear as a distinct proposal class, alongside `[INCUBATOR]` and `[KFM-CANDIDATE]`. Each unit is a fenced `yaml` block under the reflector's `## Atomic instincts` section, shaped per `reference/instinct-format.md` (`id`, `trigger`, `confidence`, `domain`, `scope`, `project_id`, `source`, `cycles_seen`, `first_seen`, `last_seen`, plus a short body). A unit is a proposal, never a stored fact - nothing lands until the user accepts it.
+
+Mirror the `[INCUBATOR]` flow:
+
+1. Discover the units: parse every `yaml` block under `## Atomic instincts` in the reflections file. Skip malformed blocks (warn on stderr, keep going).
+2. For each unit: show the parsed `trigger`, `domain`, `confidence`, and body so the user sees what would be stored.
+3. Prompt: `(a) accept   (r) reject   (d) defer   (e) edit   (q) quit`.
+
+**Per-action behavior:**
+
+1. **accept** - call `scripts/lib/instinct-store.cjs` `add(unit, { scope, baseDir })` with the unit at its emitted `confidence`. The store owns de-duplication and `cycles_seen` bookkeeping. On success print `Stored instinct <id> (<domain>, confidence <n>).` and append `**Applied**: <date>` to the proposal block.
+2. **reject** - do not store the unit. Append `**Reviewed: rejected**` to the reflections file.
+3. **defer** - no-op; the unit re-surfaces next run. Append `**Reviewed: deferred**`.
+4. **edit** - let the user adjust `trigger`, `confidence`, or `domain`, then accept the edited unit through the same `add(...)` call. Default `scope: 'project'` (write `global` only when the unit's frontmatter says so); never edit `.design/instincts/instincts.json` directly, and promote to global via the separate gated `/gdd:instinct promote`.
+
 ## Do Not
 
 - Do not apply any proposal without the user explicitly choosing `a` or `e`.

package/dist/claude-code/.claude/skills/extract-learnings/SKILL.md

@@ -53,6 +53,22 @@ Layout of `.design/learnings/LEARNINGS.md`:
 ---
 ```
 
+### Step 3b - Dual-emit atomic instinct units (Phase 51)
+
+Alongside the prose `LEARNINGS.md`, emit atomic instinct units for every learning the extractor tags as an `instinct-candidate`. A learning is an `instinct-candidate` when it states a single trigger plus a one-line response - the same shape the reflector emits. Broader narrative learnings stay prose-only.
+
+For each `instinct-candidate`, build a unit per `reference/instinct-format.md` (frontmatter: `id`, `trigger`, `confidence` from 0.3 to 0.9, `domain`, `scope`, `project_id`, `source`, `cycles_seen`, `first_seen`, `last_seen`, plus a short body). Set `source: extract-learnings`. Carry the learning's confidence (high / medium / low) into the numeric field (roughly 0.8 / 0.55 / 0.35), capped at 0.9.
+
+Write each unit through the store engine `scripts/lib/instinct-store.cjs` rather than by hand:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/lib/instinct-store.cjs" add --scope project
+```
+
+If the engine exposes a module API only, drive `add(unit, { scope: 'project', baseDir })` from a short `node -e` script. The engine owns de-duplication and `cycles_seen` bookkeeping; do not pre-merge.
+
+The prose `LEARNINGS.md` is **retained read-only for one minor version** so existing readers keep working while tooling migrates to the units. Keep writing it; do not drop the prose path in this version.
+
 ### Step 4 - Reference file proposal (optional)
 
 After writing LEARNINGS.md, check each learning entry with `Proposed reference update: yes`.

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

@@ -0,0 +1,111 @@
+---
+name: gdd-instinct
+description: "Inspects and manages atomic instinct learning units - small, scoped, confidence-weighted patterns the pipeline accumulates across cycles. Lists the project and global instinct stores, searches them by keyword, and promotes a vetted project instinct to the global store once it has cleared the cross-project gate. Use when the user wants to see what instincts exist, find an instinct by topic, or promote one to global scope. Activates for requests involving instincts, learned patterns, instinct promotion, instinct search, or the instinct store."
+argument-hint: "[list | query <keyword> | promote <id>] [--scope project|global] [--domain <d>]"
+tools: Read, Bash
+user-invocable: true
+---
+
+# /gdd:instinct
+
+**Role:** Front end for the atomic instinct store. An instinct is a single learned pattern with a trigger, a confidence between 0.3 and 0.9, a domain, and a scope. This skill lists, searches, and promotes instincts. It never edits stored units by hand and never invents new ones - the reflector and `/gdd:extract-learnings` author them.
+
+The store engine ships at `scripts/lib/instinct-store.cjs` (authored elsewhere - this skill only calls it). Unit shape (YAML frontmatter plus a short body) is specified in `reference/instinct-format.md`. The project store lives at `.design/instincts/instincts.json`; the global store at `~/.claude/gdd/global-instincts.json`.
+
+Invoke the engine with `node`, the same way other skills call a `scripts/lib` helper:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/lib/instinct-store.cjs" <subcommand> [args]
+```
+
+If the engine exposes only a module API rather than a CLI, drive it from a short `node -e` script:
+
+```bash
+node -e "const s=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/instinct-store.cjs'); console.log(JSON.stringify(s.list({scope:process.env.SCOPE})))"
+```
+
+## Invocation Modes
+
+| Command | Behavior |
+|---|---|
+| `/gdd:instinct list` | Compact table of stored instincts (default mode). |
+| `/gdd:instinct query "<keyword>"` | Search instincts by keyword; show the top matches. |
+| `/gdd:instinct promote <id>` | Promote one project instinct to the global store (gated). |
+
+Flags apply across modes:
+
+- `--scope project|global` selects which store to read. Default is `project`.
+- `--domain <d>` filters to one domain (the domain enum is defined in `reference/instinct-format.md`).
+
+## list
+
+Read the requested store and print a compact table. Call `instinct-store.list({ scope, domain, baseDir })`:
+
+```bash
+node -e "const s=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/instinct-store.cjs'); \
+  const rows=s.list({ scope: process.env.SCOPE || 'project', domain: process.env.DOMAIN || undefined }); \
+  console.log(JSON.stringify(rows));"
+```
+
+Render one row per instinct. Keep it scannable:
+
+```
+ID        DOMAIN     CONF   CYCLES  TRIGGER
+in-7f3a   tokens     0.72   3       palette has no neutral ramp
+in-91bc   layout     0.55   2       cards overflow on the 320px breakpoint
+```
+
+- `CONF` is the stored confidence (0.3 to 0.9).
+- `CYCLES` is `cycles_seen`.
+- Truncate `TRIGGER` to keep each line on one row.
+
+If the store is empty, print: `No instincts in the <scope> store yet. Run /gdd:reflect or /gdd:extract-learnings to accumulate some.`
+
+## query
+
+Search by keyword and show the closest matches. Call `instinct-store.query(keyword, { scope, baseDir, limit })`. The engine uses an FTS5 index when one is present and falls back to a plain scan otherwise; either path returns the same row shape.
+
+```bash
+node -e "const s=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/instinct-store.cjs'); \
+  const hits=s.query(process.env.KW, { scope: process.env.SCOPE || 'project', limit: 10 }); \
+  console.log(JSON.stringify(hits));"
+```
+
+Print the top matches in the same table shape as `list`, ordered by the engine's relevance ranking. If there are no matches, say so plainly and suggest a broader keyword. Quote multi-word keywords so the shell passes one argument.
+
+## promote
+
+Promote a single project instinct into the global store so it applies across every project. Promotion is **gated**: `instinct-store.promote(id, { baseDir })` only succeeds when the instinct has been seen across at least K cycles (K=2) spanning at least M distinct project ids (M=2). The engine enforces the gate; this skill surfaces the outcome and asks the user to confirm before the write.
+
+Confirm first. Prefer `@clack/prompts`, and fall back to `AskUserQuestion` when it is absent (mirror the probe in `/gdd:new-skill`):
+
+```bash
+node -e "try { require.resolve('@clack/prompts'); console.log('clack'); } catch { console.log('fallback'); }"
+```
+
+- `clack`: drive `clack.confirm({ message: 'Promote <id> to the global store?' })` from a short Node script.
+- `fallback`: ask the same yes or no question with `AskUserQuestion`.
+
+On a confirmed yes, run the promotion:
+
+```bash
+node -e "const s=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/instinct-store.cjs'); \
+  console.log(JSON.stringify(s.promote(process.env.ID, {})));"
+```
+
+Branch on the engine result:
+
+- Promotion succeeded: print `Promoted <id> to the global store.` and show the new global row.
+- Gate not met: the engine reports how far the instinct is from the K=2 / M=2 bar. Print that plainly, for example `<id> needs 2 cycles across 2 projects; seen 1 cycle in 1 project so far. Not promoted.` Do not retry and do not force the write.
+- Unknown id: print `No instinct <id> in the project store.` and suggest `/gdd:instinct list`.
+
+If the user answers no at the confirm step, print `Promotion cancelled.` and exit without writing.
+
+## Do Not
+
+- Do not edit `.design/instincts/instincts.json` or the global store by hand. All writes go through `scripts/lib/instinct-store.cjs`.
+- Do not author new instincts here. The reflector and `/gdd:extract-learnings` emit units; this skill reads and promotes them.
+- Do not bypass the promotion gate. If the K=2 / M=2 bar is not met, report it and stop.
+- Do not modify `reference/instinct-format.md` or the store engine.
+
+## INSTINCT COMPLETE

package/hooks/gdd-decision-injector.js

@@ -402,6 +402,96 @@ function buildAdrBlock(matched) {
   return lines.join('\n');
 }
 
+/**
+ * Phase 51 — surface the project instinct store's top matches for the opened
+ * file. Instinct units are atomic, confidence-weighted design instincts learned
+ * across cycles (schema: reference/instinct-format.md), persisted + ranked by
+ * scripts/lib/instinct-store.cjs. The store is a SIBLING module — we reference
+ * it by name and never reimplement its query/decay logic.
+ *
+ * Two seams keep this testable + resilient:
+ *   - `instinctTokens()` derives the query keyword(s) from the opened file's
+ *     basename + relPath (mirrors the matchTokens derivation used for glossary
+ *     /ADR matching, so an opened `color-tokens.md` queries on `color`+`tokens`).
+ *   - `buildInstinctsBlock()` is a PURE renderer over already-fetched units, so
+ *     the populated-path render is unit-testable without the store on disk.
+ *
+ * The store query itself (in main()) is wrapped in try/catch and is fully
+ * non-fatal: if the store module is absent (sibling not yet installed) or its
+ * data file is missing/corrupt, the block is silently skipped and the hook
+ * still returns { continue: true }.
+ */
+function instinctTokens(basename, relPath) {
+  const stem = basename.replace(/\.md$/i, '');
+  return Array.from(new Set([
+    stem,
+    ...stem.split(/[-_./\\]/),
+    ...String(relPath || '').split(/[-_./\\]/),
+  ].filter((t) => t && t.length > 2)));
+}
+
+/**
+ * Pure renderer: format up to the top-3 instinct units as a compact block.
+ * Each line carries the trigger, confidence (2dp), and domain. Returns null when
+ * there are no units so main() can omit the heading entirely.
+ *
+ * Defensive: tolerates missing fields (trigger/confidence/domain) and non-array
+ * input so a malformed store payload can never throw on the Read hot path.
+ *
+ * @param {Array<{id?: string, trigger?: string, confidence?: number, domain?: string}>} units
+ * @returns {string | null}
+ */
+function buildInstinctsBlock(units) {
+  if (!Array.isArray(units) || units.length === 0) return null;
+  const top = units.slice(0, 3);
+  const lines = [];
+  lines.push('');
+  lines.push('### Relevant instincts');
+  for (const u of top) {
+    if (!u || typeof u !== 'object') continue;
+    const trigger = (u.trigger == null ? '' : String(u.trigger)).trim() || '(no trigger)';
+    const conf = typeof u.confidence === 'number' && Number.isFinite(u.confidence)
+      ? u.confidence.toFixed(2)
+      : '?';
+    const domain = (u.domain == null ? '' : String(u.domain)).trim() || 'unknown';
+    lines.push(`> - ${trigger} (confidence ${conf}, ${domain})`);
+  }
+  // If every unit was malformed (no valid line emitted), drop the block.
+  if (lines.length <= 2) return null;
+  lines.push('');
+  return lines.join('\n');
+}
+
+/**
+ * Non-fatal glue: query the project instinct store for the opened file's tokens
+ * and render the block. Any failure (module absent, query throws, bad data)
+ * yields null so the caller simply omits the section. NEVER throws.
+ *
+ * @param {string} cwd — project root (passed to the store as baseDir)
+ * @param {string} basename
+ * @param {string} relPath
+ * @returns {string | null}
+ */
+function queryInstinctsBlock(cwd, basename, relPath) {
+  try {
+    // Sibling module — referenced by name, resolved relative to this hook.
+    // Absent in installs that predate Phase 51's instinct store.
+    // eslint-disable-next-line node/no-missing-require, global-require
+    const store = require(path.join(__dirname, '..', 'scripts', 'lib', 'instinct-store.cjs'));
+    if (!store || typeof store.query !== 'function') return null;
+    const tokens = instinctTokens(basename, relPath);
+    if (tokens.length === 0) return null;
+    // instinct-store.query() takes a STRING keyword (it splits on whitespace
+    // into terms) — pass the tokens space-joined, not the raw array.
+    const keyword = tokens.join(' ');
+    const units = store.query(keyword, { scope: 'project', baseDir: cwd, limit: 3 });
+    return buildInstinctsBlock(units);
+  } catch {
+    // Store missing or query failed — surface no instinct block, never crash.
+    return null;
+  }
+}
+
 function buildRecallBlock(matches, basename, backendLabel) {
   if (!matches.length) return null;
   const uniq = [];
@@ -526,21 +616,40 @@ async function main() {
     adrBlock = buildAdrBlock(matchedAdrs);
   } catch { /* defensive: never crash on ADR issues */ }
 
-  if (!block && !protoBlock && !glossaryBlock && !adrBlock) {
+  // Phase 51: surface the project instinct store's top-3 matches for the
+  // opened file. Fully non-fatal — queryInstinctsBlock swallows a missing
+  // store / bad data and returns null, so this can never break a Read.
+  const instinctsBlock = queryInstinctsBlock(cwd, basename, relPath);
+
+  if (!block && !protoBlock && !glossaryBlock && !adrBlock && !instinctsBlock) {
     try { require('./_hook-emit.js').emitHookFired('gdd-decision-injector', 'no-hits', { backend: backendLabel }); } catch { /* swallow */ }
     process.stdout.write(JSON.stringify({ continue: true }));
     return;
   }
 
-  const additionalContext = [block, protoBlock, glossaryBlock, adrBlock].filter(Boolean).join('\n');
+  const additionalContext = [block, protoBlock, glossaryBlock, adrBlock, instinctsBlock].filter(Boolean).join('\n');
 
-  try { require('./_hook-emit.js').emitHookFired('gdd-decision-injector', 'inject', { backend: backendLabel, hit_count: hits.length, prototyping: !!protoBlock, glossary: !!glossaryBlock, adr: !!adrBlock }); } catch { /* swallow */ }
+  try { require('./_hook-emit.js').emitHookFired('gdd-decision-injector', 'inject', { backend: backendLabel, hit_count: hits.length, prototyping: !!protoBlock, glossary: !!glossaryBlock, adr: !!adrBlock, instincts: !!instinctsBlock }); } catch { /* swallow */ }
   process.stdout.write(JSON.stringify({
     continue: true,
     hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext },
   }));
 }
 
-main().catch(() => {
-  process.stdout.write(JSON.stringify({ continue: true }));
-});
+// Auto-run when invoked directly (the hooks.json registration runs this hook
+// as `node hooks/gdd-decision-injector.js`, where require.main === module).
+// Guarding the auto-run lets tests require() the module in-process to unit-test
+// the pure helpers without triggering a stdin read.
+if (require.main === module) {
+  main().catch(() => {
+    process.stdout.write(JSON.stringify({ continue: true }));
+  });
+}
+
+// Exported for tests — pure helpers only; main() owns the I/O + contract.
+module.exports = {
+  buildInstinctsBlock,
+  instinctTokens,
+  queryInstinctsBlock,
+  main,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.50.1",
+  "version": "1.51.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",

package/reference/instinct-format.md

@@ -0,0 +1,120 @@
+---
+name: instinct-format
+type: meta-rules
+version: 1.0.0
+phase: 51
+tags: [instinct, learning, confidence, beta-prior, promotion-gate, ttl-decay]
+last_updated: 2026-06-03
+---
+
+# Instinct Unit Format
+
+An instinct is an atomic, confidence-weighted lesson the pipeline learns across design
+cycles. Where an ADR records a deliberate, hard-to-reverse decision (see `./adr-format.md`)
+and `CONTEXT.md` records agreed vocabulary (see `./context-md-format.md`), an instinct
+records a softer signal: a recurring "when X, prefer Y" reflex that earns trust by being
+seen again and again. Each unit is one trigger sentence plus a short body, stored as a YAML
+document and validated by `./schemas/instinct.schema.json`. The store
+(`scripts/lib/instinct-store.cjs`) persists, queries, promotes, and decays them.
+
+Instincts are always advisory, never directive. A fresh instinct carries low confidence and
+is offered as a suggestion; only repeated cross-project observation raises that confidence,
+and even then it is capped well below certainty.
+
+## Unit shape
+
+A unit is a YAML frontmatter block followed by a 1 to 3 paragraph body. The body explains
+the reflex in plain language: what situation fires it, what to reach for, and why.
+
+```yaml
+---
+id: prefer-token-over-hex            # kebab-case stable identifier
+trigger: When a raw color literal appears in a component, reach for a design token first.
+confidence: 0.5                      # float in [0.3, 0.9]
+domain: build                        # intake|explore|decide|build|verify|operate|utility
+scope: project                       # project|global
+project_id: abcd1234                 # sha8 of the normalized git origin (project scope)
+source: reflection                   # reflection|extract-learnings|user
+cycles_seen: 1                       # distinct cycles that surfaced this instinct
+project_ids: [abcd1234]              # distinct origins that surfaced it (promotion gate)
+first_seen: 2026-06-01               # ISO date the unit was recorded
+last_seen: 2026-06-01                # ISO date it was last surfaced (resets decay)
+---
+Hardcoded hex values drift away from the system palette over time. Routing the value
+through a token keeps one source of truth and lets a theme change land everywhere at once.
+```
+
+### Field reference
+
+- **id** (required). Kebab-case, lowercase letters and digits with single hyphens, 3 to 80
+  characters. The id is stable: touching or promoting a unit never changes it.
+- **trigger** (required). One sentence naming the situation that fires the instinct. Keep it
+  concrete enough that a reader knows when it applies.
+- **confidence** (required). A float between 0.3 and 0.9. The floor of 0.3 says a brand-new
+  instinct is a hint, not a rule. The ceiling of 0.9 says no instinct is ever certain.
+- **domain** (required). One of `intake`, `explore`, `decide`, `build`, `verify`, `operate`,
+  `utility`. These map to the Phase 50 lifecycle stages so an instinct surfaces at the right
+  moment in a cycle.
+- **scope** (required). `project` for a lesson learned in one repository, `global` for one
+  promoted after it clears the cross-project gate below.
+- **project_id** (required for project scope). The 8-character hex sha of the normalized git
+  origin, produced by `deriveProjectId`. A global unit may omit it, since a promoted instinct
+  is no longer tied to a single origin.
+- **source** (required). Which producer minted the unit: a `reflection` pass, the
+  `extract-learnings` step, or a direct `user` assertion.
+- **cycles_seen** (optional, defaults to 1). How many distinct cycles have surfaced the unit.
+- **project_ids** (optional). The set of distinct origins that surfaced it. Its size feeds the
+  promotion gate.
+- **first_seen** / **last_seen** (optional, stamped on write). ISO dates for recording and last
+  surfacing. `last_seen` resets the decay window.
+
+## The Beta(2,8) prior
+
+When an instinct is promoted to the global store it is seeded with a Beta(2,8) posterior, the
+same conservative prior the Phase 38 `design_arms` store uses. Its posterior mean is 0.2, so a
+promoted pattern still has to earn standing from real outcomes rather than starting trusted.
+The store exposes this as `INSTINCT_PRIOR = {alpha: 2, beta: 8}`. Successful outcomes add to
+`alpha`, disappointing ones add to `beta`, and the mean moves accordingly.
+
+## Promotion gate (K=2 cycles across M=2 projects)
+
+A project instinct may move to the global store only when both halves of the gate hold:
+
+1. **K = 2 cycles.** `cycles_seen` is at least 2, so the lesson repeated rather than firing once.
+2. **M = 2 projects.** The unit appears in at least 2 distinct `project_ids`, so the lesson
+   generalized beyond the repository that first taught it.
+
+`promote(id)` throws a clear error when either half is unmet, so a one-off observation in a
+single project can never leak into global advice. On a passing gate the unit is re-scoped to
+`global`, the single-origin `project_id` is dropped, the Beta(2,8) prior is applied, and the
+unit is removed from the project store. `touch(id)` is how a unit accumulates toward the gate:
+each call bumps `last_seen` and `cycles_seen` and adds the current origin to `project_ids`.
+
+## TTL decay
+
+Instincts that stop showing up should fade rather than linger as stale advice. `decay()` walks
+a scope and, for any unit not surfaced within the decay window of 6 cycles, multiplies its
+confidence by 0.9. Once a unit's confidence falls below 0.2 it is archived: the store writes it
+to `<root>/instincts/archive/<id>.json` with an `archived_at` stamp and removes it from the live
+set. Archiving is reversible by hand, so the audit trail survives. Calling `touch(id)` resets the
+window, so an instinct that keeps proving useful never decays.
+
+## Storage and recall
+
+Project units live at `<root>/instincts/instincts.json`, resolved through the worktree-aware
+root so writes land in the main checkout rather than a throwaway worktree. Global units live at
+`~/.claude/gdd/global-instincts.json`. Both files are written atomically (a temp file plus a
+rename), and JSON is always the source of truth.
+
+`query(keyword)` ranks units by how well the keyword matches their trigger, body, and domain,
+returning the best few. When `better-sqlite3` is present with its FTS5 extension the query runs
+over a small full-text index for speed; otherwise an in-memory scan answers the same query with
+the same shape. `better-sqlite3` stays a runtime probe and is never a hard dependency, so recall
+degrades gracefully wherever the native module is absent. `backendName()` reports which path is
+active.
+
+## Cross-references
+
+- Hard-to-reverse decisions belong in an ADR, not an instinct. See `./adr-format.md`.
+- Agreed domain vocabulary belongs in `CONTEXT.md`. See `./context-md-format.md`.
+- The frontmatter schema is `./schemas/instinct.schema.json`, validated under Ajv.

package/reference/registry.json

@@ -1149,6 +1149,13 @@
       "type": "meta-rules",
       "phase": 50,
       "description": "Phase 50 auto-generated skill composition graph (mermaid): skills grouped by lifecycle stage with composes_with and next_skills edges; regenerated by scripts/generate-skill-graph.cjs and drift-gated in CI."
+    },
+    {
+      "name": "instinct-format",
+      "path": "reference/instinct-format.md",
+      "type": "meta-rules",
+      "phase": 51,
+      "description": "Phase 51 instinct unit format: YAML frontmatter (id, trigger, confidence 0.3-0.9, domain, scope, project_id, source, cycles_seen, first/last_seen) + body; promotion gate K=2/M=2; Beta(2,8) prior; TTL decay. Stored via scripts/lib/instinct-store.cjs."
     }
   ]
 }

package/reference/schemas/events.schema.json

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