@hegemonart/get-design-done 1.50.1 → 1.52.0

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.52.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",
@@ -59,7 +59,7 @@
     "test:behavior": "node scripts/run-behavior-tests.cjs",
     "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/fixtures/baselines\"",
+    "lint:md": "npx --yes markdownlint-cli2 \"**/*.md\" \"#**/node_modules\" \"#.planning\" \"#.claude\" \"#test/fixtures/baselines\"",
     "lint:links": "npx --yes lychee --no-progress --accept 200,206,403,429 \"**/*.md\" || true",
     "lint:agentskills": "node scripts/lint-agentskills-spec.cjs",
     "lint:changelog": "node scripts/lint-changelog.cjs",
@@ -74,6 +74,7 @@
     "check:domain-links": "node scripts/check-domain-cross-links.cjs",
     "check:no-duplication": "node scripts/check-no-duplication.cjs",
     "validate:composition-graph": "node scripts/validate-composition-graph.cjs",
+    "validate:design-context": "node scripts/validate-design-context.cjs",
     "validate:skill-frontmatter": "node scripts/validate-skill-frontmatter.cjs",
     "build:skill-graph": "node scripts/generate-skill-graph.cjs",
     "build:skill-graph:check": "node scripts/generate-skill-graph.cjs --check",

package/reference/design-context-schema.md

@@ -0,0 +1,159 @@
+---
+name: design-context-schema
+type: reference
+version: 1.0.0
+phase: 52
+tags: [design-context, knowledge-graph, schema, nodes, edges, mapper, two-phase]
+last_updated: 2026-06-03
+---
+
+# DesignContext Graph Schema
+
+The DesignContext graph is the typed knowledge graph of a design system. It records design
+entities as `nodes` and the relationships between them as `edges`, so an agent can reason about
+a system the way an engineer reads a dependency graph: which token a component consumes, which
+screen a flow transitions to, which pattern an anti-pattern conflicts with. The canonical graph
+lives at `.design/context-graph.json`. It is validated by `scripts/validate-design-context.cjs`
+and queried by `scripts/lib/design-context-query.cjs`.
+
+This file documents the four shapes (Node, Edge, Fragment, Graph), the ten node types, the twelve
+edge types, and the two-phase mapper pattern that builds the graph. The controlled `tags[]`
+vocabulary lives in `./design-context-tag-vocab.md`; the JSON Schema lives at
+`./schemas/design-context.schema.json`.
+
+## Shapes
+
+Four shapes make up the contract. A Graph is the assembled whole; a Fragment is one mapper's
+contribution before merge; Nodes and Edges are the parts.
+
+### Node
+
+```
+{ id, type, name, summary, tags[], complexity }
+```
+
+- `id`: stable unique string; edges reference it. A duplicate id is a hard error.
+- `type`: one of the ten node types below.
+- `name`: human-readable name of the entity.
+- `summary`: a one-line description of what the entity is and does. The deterministic pass may
+  leave this empty; the summary pass fills it. An empty summary, or one identical to `name`, is a
+  soft warning (a stub).
+- `tags[]`: strings from the controlled vocabulary. An unknown tag is a soft warning.
+- `complexity`: one of `simple`, `moderate`, `complex`.
+- `subtype` *(optional)*: a finer class. For a `token` node one of
+  `color / spacing / typography / radius / shadow`; for a `layer` node one of
+  `Atomic / Molecular / Organism / Template`.
+
+### Edge
+
+```
+{ source, target, type, direction, weight }
+```
+
+- `source`, `target`: node ids. Both must resolve to an existing node; a dangling endpoint is a
+  hard error.
+- `type`: one of the twelve edge types below.
+- `direction`: one of `forward`, `backward`, `bidirectional`. A forward edge reads
+  source-to-target; a backward edge reads target-to-source; a bidirectional edge reads both ways.
+  Traversal in the query library honors direction.
+- `weight`: a number in the inclusive range 0 to 1. It expresses relationship strength, not
+  distance, so a stronger tie has a higher weight.
+
+### Fragment
+
+```
+{ schema_version, mapper, generated_at, nodes[], edges[] }
+```
+
+A Fragment is the output of a single mapper (the Figma mapper, the codebase mapper, the docs
+mapper). It carries a `mapper` field naming its origin and is merged into the Graph by union on
+node `id`. Fragments let mappers run independently and write narrow outputs that later combine.
+
+### Graph
+
+```
+{ schema_version, generated_at, nodes[], edges[] }
+```
+
+The Graph is the merged, canonical document at `.design/context-graph.json`. `schema_version` is
+required; `generated_at` is an optional ISO-8601 timestamp recording when the graph was assembled.
+
+## Node types
+
+Ten node types cover the entities a design system holds. Each entry states what the type is and
+when a mapper emits it.
+
+- **token**: a design-token leaf such as a color, a spacing step, or a type ramp value. Emitted
+  for every resolvable token; carries a `subtype` naming the token family.
+- **component**: a reusable UI unit (a button, a card, an input). Emitted once per component
+  regardless of how many variants it has.
+- **variant**: a named configuration of a component (a button's `primary` or `ghost`). Emitted
+  when a component exposes distinct variants worth addressing on their own.
+- **state**: an interaction or lifecycle state of a component (`hover`, `disabled`, `loading`).
+  Emitted when state changes carry their own styling or behavior.
+- **motion-fragment**: a reusable motion unit (an enter transition, an easing curve, a loop).
+  Emitted when motion is named and reused rather than ad hoc.
+- **a11y-pattern**: an accessibility pattern (a focus-trap, a skip-link, an aria-live region).
+  Emitted when a component participates in a named accessibility contract.
+- **screen**: a full page or view in a product flow. Emitted once per distinct screen.
+- **layer**: a composition layer in the atomic taxonomy. Carries a `subtype` of `Atomic`,
+  `Molecular`, `Organism`, or `Template`. Emitted to record where an entity sits in the hierarchy.
+- **pattern**: a recurring solution that spans components (a master-detail layout, a wizard).
+  Emitted when a shape repeats across the system and earns a name.
+- **anti-pattern**: a recurring shape the system wants to retire (a one-off color, a duplicated
+  control). Emitted so the graph can point at debt and the edges can mark conflicts.
+
+## Edge types
+
+Twelve edge types cover how entities relate. Each entry states the relationship and when it
+applies.
+
+- **uses-token**: a component or variant consumes a token. Source is the consumer, target is the
+  token.
+- **composes**: a larger entity is built from a smaller one (a card composes a button). Source is
+  the whole, target is the part.
+- **extends**: a variant or component specializes another (a `primary` button extends the base
+  button). Source is the specialization.
+- **transitions-to**: a screen or state moves to another in a flow. Used for navigation graphs
+  and state machines.
+- **depends-on**: a generic dependency where the more specific edge types do not fit. Source
+  needs target to function.
+- **mirrors**: two entities are intentional reflections of each other (a light-mode and dark-mode
+  pair). Usually bidirectional.
+- **conflicts-with**: two entities collide or duplicate intent (an anti-pattern conflicts with a
+  sanctioned pattern). Used to surface debt.
+- **referenced-by**: an inbound citation: the target points at the source from outside the graph
+  core (a doc or a ticket references this entity). Often backward.
+- **tested-by**: an entity is covered by a test. Source is the entity, target is the test node.
+- **documented-by**: an entity is described by a doc. Source is the entity, target is the doc.
+- **consumes-context**: an entity reads shared context provided elsewhere (a component reads a
+  theme provider). Source is the reader.
+- **provides-context**: an entity supplies shared context to others (a theme provider supplies a
+  palette). Source is the provider; the matching reader uses `consumes-context`.
+
+## The two-phase mapper pattern
+
+A mapper builds the graph in two passes so the cheap, deterministic work is separate from the
+costly, judgment-bearing work.
+
+1. **Deterministic extract.** A pure pass walks the source (a Figma file, a component tree, a docs
+   set) and emits node and edge skeletons: ids, types, names, tags, complexity, and every edge it
+   can prove. Summaries are left empty. This pass is reproducible and dependency-free, so a graph
+   can be rebuilt the same way every run.
+2. **LLM summary.** A second pass fills each node `summary` with a one-line description an agent
+   can read. Only the `summary` field changes; ids, types, and edges stay fixed from the extract
+   pass. This keeps the expensive pass narrow and lets the validator flag any node the summary
+   pass missed as a stub.
+
+Splitting the work this way means the structure of the graph is deterministic and auditable, while
+the prose layer can be regenerated on its own without disturbing the topology. A mapper writes a
+Fragment; the assembler merges fragments into the canonical Graph.
+
+## Cross-references
+
+- Controlled `tags[]` vocabulary the validator enforces: see `./design-context-tag-vocab.md`.
+- The JSON Schema (Draft-07) for the Graph: see `./schemas/design-context.schema.json`.
+- The validator (structural, referential, completeness, tag checks):
+  `scripts/validate-design-context.cjs`.
+- The query library (filters, BFS path, consumers, orphans, cycles, coverage):
+  `scripts/lib/design-context-query.cjs`.

package/reference/design-context-tag-vocab.md

@@ -0,0 +1,82 @@
+---
+name: design-context-tag-vocab
+type: reference
+version: 1.0.0
+phase: 52
+tags: [design-context, knowledge-graph, tags, vocabulary, controlled-vocab]
+last_updated: 2026-06-03
+---
+
+# DesignContext Tag Vocabulary
+
+This is the controlled vocabulary the DesignContext validator checks node `tags[]` against. A tag
+outside this list is a soft warning, not a hard error, so a mapper can ship a new tag and the
+graph still loads; the warning prompts a reviewer to either fix the tag or add it here.
+
+## Source of truth
+
+The canonical list lives in code, in the `TAG_VOCAB` set inside
+`scripts/validate-design-context.cjs`. That set is what the validator enforces. This document
+mirrors it for human readers and groups the tags by concern. When the set changes, update this
+file by hand to match. If the two ever disagree, the code wins.
+
+## Why a controlled vocabulary
+
+Free-form tags drift: one node says `darkmode`, another `dark-mode`, a third `dark`. A query for
+`dark-mode` then misses two of three. A controlled list keeps tags queryable and keeps the
+`nodes(graph, { tag })` filter reliable. The list is deliberately broad rather than minimal, so
+most real tags land inside it; the soft-warning behavior absorbs the rest without blocking a build.
+
+## Tags by concern
+
+The groupings below are for reading only. The validator treats the vocabulary as one flat set, so
+a tag is valid regardless of which group it sits in.
+
+- **Color**: `color`, `palette`, `theme`, `dark-mode`, `light-mode`, `contrast`, `gradient`,
+  `surface`, `brand`.
+- **Spacing and sizing**: `spacing`, `sizing`, `density`, `gap`, `inset`, `stack`.
+- **Typography**: `typography`, `font`, `type-scale`, `heading`, `body-text`, `label`, `numeric`.
+- **Radius, shape, elevation**: `radius`, `shape`, `border`, `shadow`, `elevation`, `depth`.
+- **Motion**: `motion`, `transition`, `animation`, `easing`, `duration`, `enter`, `exit`, `loop`,
+  `gesture`.
+- **Accessibility**: `a11y`, `aria`, `focus`, `keyboard`, `screen-reader`, `reduced-motion`,
+  `contrast-safe`, `touch-target`.
+- **Layout and structure**: `layout`, `grid`, `flex`, `responsive`, `breakpoint`, `container`,
+  `overflow`, `position`, `z-index`.
+- **Interaction state**: `state`, `hover`, `active`, `disabled`, `loading`, `error`, `success`,
+  `selected`, `pressed`, `dragging`.
+- **Component taxonomy**: `atom`, `molecule`, `organism`, `template`, `primitive`, `composite`,
+  `layout-primitive`.
+- **Forms and inputs**: `form`, `input`, `control`, `validation`, `field`.
+- **Navigation and structure**: `navigation`, `overlay`, `modal`, `menu`, `tabs`, `data-display`,
+  `feedback`, `media`.
+- **Semantic role**: `interactive`, `static`, `decorative`, `destructive`, `utility`.
+- **Quality flags**: `deprecated`, `experimental`, `stable`, `anti-pattern`, `review-needed`.
+
+## Machine-readable list
+
+The fenced block below is the same vocabulary as a flat list for any tool that wants to read the
+doc instead of the code. Tokens are separated by commas or newlines (split on `/[\s,]+/`), so the
+grouping into lines is cosmetic. It must stay equal to the `TAG_VOCAB` set in
+`scripts/validate-design-context.cjs`.
+
+```text
+color, palette, theme, dark-mode, light-mode, contrast, gradient, surface, brand,
+spacing, sizing, density, gap, inset, stack,
+typography, font, type-scale, heading, body-text, label, numeric,
+radius, shape, border, shadow, elevation, depth,
+motion, transition, animation, easing, duration, enter, exit, loop, gesture,
+a11y, aria, focus, keyboard, screen-reader, reduced-motion, contrast-safe, touch-target,
+layout, grid, flex, responsive, breakpoint, container, overflow, position, z-index,
+state, hover, active, disabled, loading, error, success, selected, pressed, dragging,
+atom, molecule, organism, template, primitive, composite, layout-primitive,
+form, input, control, validation, field,
+navigation, overlay, modal, menu, tabs, data-display, feedback, media,
+interactive, static, decorative, destructive, utility,
+deprecated, experimental, stable, anti-pattern, review-needed
+```
+
+## Cross-references
+
+- The node and edge type catalogue and the four shapes: see `./design-context-schema.md`.
+- The validator that enforces this vocabulary: `scripts/validate-design-context.cjs`.

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,27 @@
       "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."
+    },
+    {
+      "name": "design-context-schema",
+      "path": "reference/design-context-schema.md",
+      "type": "schema",
+      "phase": 52,
+      "description": "Phase 52 (KEYSTONE) typed DesignContext graph: 10 node types + 12 edge types, Node/Edge/Fragment/Graph shapes, two-phase mapper pattern. Schema at reference/schemas/design-context.schema.json."
+    },
+    {
+      "name": "design-context-tag-vocab",
+      "path": "reference/design-context-tag-vocab.md",
+      "type": "meta-rules",
+      "phase": 52,
+      "description": "Phase 52 controlled tag vocabulary for DesignContext nodes; validate-design-context.cjs soft-warns on unknown tags."
     }
   ]
 }