@hegemonart/get-design-done 1.59.2 → 1.59.4

package/scripts/generate-skill-frontmatter.cjs

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * generate-skill-frontmatter.cjs — Phase 46 (Skill UX Polish).
+ *
+ * scripts/lib/manifest/skills.json is the single source of truth for the
+ * universal skill frontmatter fields (description, argument-hint, tools,
+ * user-invocable, disable-model-invocation). This script regenerates the
+ * frontmatter block of every scripts/skill-templates/<name>/SKILL.md from that manifest,
+ * preserving the markdown body and any non-managed frontmatter lines verbatim.
+ *
+ * Direction is forward (manifest -> source frontmatter); build-skills.cjs then
+ * propagates scripts/skill-templates -> skills/ + dist/claude-code/. A CI drift gate
+ * (--check) keeps committed frontmatter == generated.
+ *
+ * Modes:
+ *   (no flag)   regenerate scripts/skill-templates/<name>/SKILL.md frontmatter from skills.json
+ *   --check     exit 1 if any committed frontmatter differs from generated (no writes)
+ *   --extract   reverse: read current source frontmatter -> rewrite skills.json
+ *               (seed/refresh the SoT from ground truth; idempotent with forward)
+ *
+ * Managed keys (emitted in this canonical order, only when present):
+ *   name, description, argument-hint, tools, user-invocable, disable-model-invocation
+ * Everything else (color, model, writes:, ...) is carried verbatim in the record's
+ * `extra_frontmatter` array and re-emitted after the managed block.
+ *
+ * Exit: 0 ok / 1 drift (--check) / 2 error.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..');
+const SRC = path.join(ROOT, 'scripts', 'skill-templates');
+const SKILLS_JSON = path.join(ROOT, 'scripts', 'lib', 'manifest', 'skills.json');
+
+// Managed frontmatter keys <-> manifest record keys, in canonical emit order.
+const MANAGED = [
+  { fm: 'name', rec: 'name', kind: 'name' },
+  { fm: 'description', rec: 'description', kind: 'qstr' },
+  { fm: 'argument-hint', rec: 'argument_hint', kind: 'qstr' },
+  { fm: 'tools', rec: 'tools', kind: 'bare' },
+  { fm: 'user-invocable', rec: 'user_invocable', kind: 'bool' },
+  { fm: 'disable-model-invocation', rec: 'disable_model_invocation', kind: 'bool' },
+];
+const MANAGED_FM = new Set(MANAGED.map((m) => m.fm));
+
+function fail(msg) {
+  process.stderr.write(`generate-skill-frontmatter: ${msg}\n`);
+  process.exit(2);
+}
+
+function listSkillDirs() {
+  if (!fs.existsSync(SRC)) fail(`source dir not found: ${SRC}`);
+  return fs
+    .readdirSync(SRC, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && fs.existsSync(path.join(SRC, e.name, 'SKILL.md')))
+    .map((e) => e.name)
+    .sort((a, b) => a.localeCompare(b));
+}
+
+/** Split a SKILL.md into { fmLines, body }. fmLines excludes the --- fences. */
+function splitFrontmatter(text, id) {
+  const norm = text.replace(/\r\n/g, '\n');
+  if (!norm.startsWith('---\n')) fail(`${id}: SKILL.md does not start with a --- frontmatter fence`);
+  const end = norm.indexOf('\n---\n', 4);
+  if (end === -1) fail(`${id}: unterminated frontmatter`);
+  const fmBlock = norm.slice(4, end + 1); // include trailing \n of last fm line
+  const body = norm.slice(end + 5); // after "\n---\n"
+  const fmLines = fmBlock.replace(/\n$/, '').split('\n');
+  return { fmLines, body };
+}
+
+function unquote(v) {
+  const t = v.trim();
+  if (t.length >= 2 && t.startsWith('"') && t.endsWith('"')) {
+    return t.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, '\\');
+  }
+  return t;
+}
+function quote(s) {
+  return '"' + String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
+}
+
+/** Parse one skill's frontmatter lines into an enriched record. */
+function recordFromFrontmatter(id, fmLines) {
+  const rec = { name: id };
+  const extra = [];
+  let i = 0;
+  while (i < fmLines.length) {
+    const line = fmLines[i];
+    const m = /^([A-Za-z][\w-]*):(.*)$/.exec(line);
+    if (!m) {
+      // stray non-key line at top level — preserve verbatim
+      extra.push(line);
+      i += 1;
+      continue;
+    }
+    const key = m[1];
+    const rawVal = m[2];
+    // gather continuation lines (indented or list items or blank-within-block)
+    const block = [line];
+    let j = i + 1;
+    while (j < fmLines.length && /^(\s+\S|\s*-\s|\s*$)/.test(fmLines[j]) && !/^[A-Za-z][\w-]*:/.test(fmLines[j])) {
+      block.push(fmLines[j]);
+      j += 1;
+    }
+    const managed = MANAGED.find((mm) => mm.fm === key);
+    if (managed && block.length === 1) {
+      const v = rawVal.trim();
+      if (managed.kind === 'name') {
+        if (v !== `gdd-${id}`) rec.frontmatter_name = v;
+      } else if (managed.kind === 'bool') {
+        rec[managed.rec] = v === 'true';
+      } else if (managed.kind === 'qstr') {
+        rec[managed.rec] = unquote(v);
+      } else {
+        rec[managed.rec] = v; // bare (tools)
+      }
+    } else {
+      extra.push(...block);
+    }
+    i = j;
+  }
+  if (extra.length) rec.extra_frontmatter = extra;
+  return rec;
+}
+
+/**
+ * Emit the frontmatter block (without --- fences) for a record.
+ *
+ * Order-preserving: `name` always leads, then the managed keys are emitted in
+ * the record's own insertion order (which --extract captures from the original
+ * file order), then any non-managed lines verbatim. This keeps forward
+ * generation a byte-for-byte fixed point on the committed tree, so existing
+ * frontmatter-snapshot baselines never churn. New skills authored directly in
+ * skills.json get whatever key order their record uses.
+ */
+function frontmatterFromRecord(rec) {
+  const out = [`name: ${rec.frontmatter_name || `gdd-${rec.name}`}`];
+  const byRec = new Map(MANAGED.filter((m) => m.kind !== 'name').map((m) => [m.rec, m]));
+  for (const key of Object.keys(rec)) {
+    const m = byRec.get(key);
+    if (!m) continue; // name / frontmatter_name / extra_frontmatter / registered_in_phase / aliases / ...
+    const v = rec[key];
+    if (v === undefined || v === null) continue;
+    if (m.kind === 'bool') out.push(`${m.fm}: ${v ? 'true' : 'false'}`);
+    else if (m.kind === 'qstr') out.push(`${m.fm}: ${quote(v)}`);
+    else out.push(`${m.fm}: ${v}`);
+  }
+  if (Array.isArray(rec.extra_frontmatter)) out.push(...rec.extra_frontmatter);
+  return out.join('\n');
+}
+
+function readSkillsJson() {
+  return JSON.parse(fs.readFileSync(SKILLS_JSON, 'utf8'));
+}
+function recordMap(json) {
+  const map = new Map();
+  for (const r of json.skills || []) map.set(r.name, r);
+  return map;
+}
+
+/** Build the regenerated SKILL.md text for one skill from its record. */
+function renderSkill(id, rec) {
+  const abs = path.join(SRC, id, 'SKILL.md');
+  const { body } = splitFrontmatter(fs.readFileSync(abs, 'utf8'), id);
+  return `---\n${frontmatterFromRecord(rec)}\n---\n${body}`;
+}
+
+function modeForward(check) {
+  const json = readSkillsJson();
+  const map = recordMap(json);
+  const dirs = listSkillDirs();
+  const drift = [];
+  let written = 0;
+  for (const id of dirs) {
+    const rec = map.get(id);
+    if (!rec) {
+      if (check) { drift.push(`${id} (missing from skills.json)`); continue; }
+      fail(`${id}: present in scripts/skill-templates but missing from skills.json — add a record (run --extract)`);
+    }
+    const abs = path.join(SRC, id, 'SKILL.md');
+    const cur = fs.readFileSync(abs, 'utf8').replace(/\r\n/g, '\n');
+    const next = renderSkill(id, rec);
+    if (cur === next) continue;
+    if (check) drift.push(id);
+    else { fs.writeFileSync(abs, next); written += 1; }
+  }
+  // records in skills.json with no source dir (e.g. not yet authored) are tolerated
+  if (check) {
+    if (drift.length) {
+      process.stderr.write(
+        `generate-skill-frontmatter --check: ${drift.length} skill(s) drift from skills.json:\n  ${drift.slice(0, 20).join('\n  ')}\n` +
+          `Run \`npm run generate:skill-frontmatter\` then \`npm run build:skills\`.\n`,
+      );
+      process.exit(1);
+    }
+    process.stdout.write(`generate-skill-frontmatter --check: OK — ${dirs.length} skills match skills.json.\n`);
+    return;
+  }
+  process.stdout.write(`generate-skill-frontmatter: regenerated ${written}/${dirs.length} skill frontmatter block(s).\n`);
+}
+
+function modeExtract() {
+  const existing = fs.existsSync(SKILLS_JSON) ? readSkillsJson() : { schema_version: 1, skills: [] };
+  const prevMap = recordMap(existing);
+  const dirs = listSkillDirs();
+  const skills = [];
+  for (const id of dirs) {
+    const { fmLines } = splitFrontmatter(fs.readFileSync(path.join(SRC, id, 'SKILL.md'), 'utf8'), id);
+    const rec = recordFromFrontmatter(id, fmLines);
+    // preserve curated fields that live only in the manifest (not frontmatter)
+    const prev = prevMap.get(id);
+    if (prev && prev.registered_in_phase != null) rec.registered_in_phase = prev.registered_in_phase;
+    if (prev && prev.aliases != null) rec.aliases = prev.aliases;
+    skills.push(rec);
+  }
+  const out = { schema_version: existing.schema_version || 1 };
+  if (existing.note) out.note = existing.note;
+  out.skills = skills;
+  fs.writeFileSync(SKILLS_JSON, JSON.stringify(out, null, 2) + '\n');
+  process.stdout.write(`generate-skill-frontmatter --extract: wrote ${skills.length} enriched records to skills.json.\n`);
+}
+
+function main(argv) {
+  const args = argv.slice(2);
+  if (args.includes('--extract')) return modeExtract();
+  return modeForward(args.includes('--check'));
+}
+
+if (require.main === module) main(process.argv);
+
+module.exports = {
+  splitFrontmatter,
+  recordFromFrontmatter,
+  frontmatterFromRecord,
+  renderSkill,
+  unquote,
+  quote,
+  MANAGED,
+  MANAGED_FM,
+  main,
+};

package/scripts/lib/manifest/scaffolder.cjs

@@ -3,7 +3,7 @@
  * scripts/lib/manifest/scaffolder.cjs — Phase 50 (Authoring Contract v3).
  *
  * Pure, dependency-free generator behind the `/gdd:new-skill` scaffolder skill.
- * The SKILL.md (skill-templates/new-skill/SKILL.md) drives the interactive
+ * The SKILL.md (scripts/skill-templates/new-skill/SKILL.md) drives the interactive
  * prompts; this module is the deterministic core it (and the test suite) call.
  *
  * Exports:

package/scripts/lib/manifest/schemas/skills.schema.json

@@ -25,7 +25,7 @@
           "name": {
             "type": "string",
             "minLength": 1,
-            "description": "Skill id = skill-templates/<name>/ directory name."
+            "description": "Skill id = scripts/skill-templates/<name>/ directory name."
           },
           "frontmatter_name": {
             "type": "string",

package/scripts/lib/manifest/skills.json

@@ -319,7 +319,7 @@
     },
     {
       "name": "new-skill",
-      "description": "Scaffolds a new Phase-28.5 + Phase-50-compliant skill: gathers a name, a multi-paragraph v3 description, a lifecycle stage, an allowed-tools list, and optional composes_with neighbours, then writes skill-templates/<name>/SKILL.md from the pure generator. Use when adding a brand-new gdd skill and you want the frontmatter, length cap, and v3 description form correct from the first commit. Activates for requests involving authoring a skill, scaffolding a command, creating a new SKILL.md, or adding a slash command.",
+      "description": "Scaffolds a new Phase-28.5 + Phase-50-compliant skill: gathers a name, a multi-paragraph v3 description, a lifecycle stage, an allowed-tools list, and optional composes_with neighbours, then writes scripts/skill-templates/<name>/SKILL.md from the pure generator. Use when adding a brand-new gdd skill and you want the frontmatter, length cap, and v3 description form correct from the first commit. Activates for requests involving authoring a skill, scaffolding a command, creating a new SKILL.md, or adding a slash command.",
       "argument_hint": "<skill-name>",
       "tools": "Read, Write, Bash, AskUserQuestion",
       "user_invocable": true,

package/scripts/lib/new-addendum.cjs

@@ -3,7 +3,7 @@
  * scripts/lib/new-addendum.cjs — Phase 54 (Composable Reference Addendums), REG-01.
  *
  * Pure, dependency-free generator behind the `/gdd:new-addendum <kind> <name>`
- * scaffolder skill (skill-templates/new-addendum/SKILL.md). The SKILL.md drives
+ * scaffolder skill (scripts/skill-templates/new-addendum/SKILL.md). The SKILL.md drives
  * the prompts; this module is the deterministic core it (and the test suite)
  * call. Mirrors scripts/lib/manifest/scaffolder.cjs (the Phase 50 skill
  * scaffolder): same ReDoS-safe NAME_RE, same throw-on-invalid contract, same

package/scripts/skill-templates/README.md

@@ -0,0 +1,90 @@
+# `scripts/skill-templates/` - Editable Skill Source (Single Source of Truth)
+
+This directory is the **only** place to edit skill content. Every `SKILL.md` and sibling
+doc here is the editable truth - the per-skill prose, examples, procedure files
+(`*-procedure.md`, `*-rules.md`, emitters, etc.) all live here.
+
+The user-facing `skills/` directory at the repo root is a **build artifact**, not source.
+It is **committed** (since v1.58.1, NOT gitignored) and regenerated from this directory:
+
+- on `npm install` (via the `prepare` lifecycle script) - so contributor clones rebuild it from source
+- on `npm pack` / `npm publish` (via `prepack`) - so the published tarball ships pre-built skills
+- on demand via `node scripts/build-skills.cjs`, with the `build:skills:check` drift gate (CI)
+  failing the build whenever the committed `skills/` no longer matches `scripts/skill-templates/`
+
+It stays in git because the Claude Code marketplace install path git-clones the plugin
+**without** running `npm install`, so `./skills/` must already exist post-clone. v1.58.0
+briefly gitignored it and broke that path; v1.58.1 restored it as a committed, drift-gated
+build output.
+
+End users installing `@hegemonart/get-design-done` from the npm registry receive a tarball
+with `skills/` already built; no build step runs on their machine.
+
+## Why two directories, not one
+
+Claude Code reads `./skills/<slug>/SKILL.md` raw. If we kept `{{command_prefix}}` placeholders
+in the file Claude reads, the literal text `{{command_prefix}}` would show up in the prompt.
+So the editable templates need to live separately from the rendered output.
+
+The previous layout (Phase 42) put templates under `source/skills/` AND committed the
+rendered `skills/` alongside. That meant 232 tracked files for 116 distinct skills with
+identical content modulo a single placeholder substitution. Pure git churn.
+
+v1.58.0 fixes this: templates are tracked once at `scripts/skill-templates/`, the rendered output
+is generated on demand.
+
+## Source-of-truth split (what lives where)
+
+| Concern | Source of truth | How it reaches `skills/` |
+|---|---|---|
+| **Body content** (everything below the frontmatter) | `scripts/skill-templates/<slug>/SKILL.md` | `scripts/build-skills.cjs` walks `scripts/skill-templates/`, applies per-harness placeholder substitution, writes to `skills/` |
+| **Universal frontmatter** (`name`, `description`, `argument-hint`, `tools`, `user-invocable`, `disable-model-invocation`) | `scripts/lib/manifest/skills.json` | `scripts/generate-skill-frontmatter.cjs` writes the managed block into `scripts/skill-templates/<slug>/SKILL.md`, then `build:skills` copies it onward |
+| **Non-managed frontmatter** (e.g. `color`, `model`, custom keys) | `scripts/skill-templates/<slug>/SKILL.md` itself (preserved verbatim) | carried through both generators unchanged |
+
+The forward direction is **`skills.json` -> `scripts/skill-templates/` -> `skills/`**.
+Treat that direction as canonical; the `--extract` mode of `generate-skill-frontmatter.cjs` exists
+only to seed the manifest from current sources when reconciling drift.
+
+## Editing protocol
+
+1. **Edit body** -> modify `scripts/skill-templates/<slug>/SKILL.md` (anything below the frontmatter delimiter).
+2. **Edit universal frontmatter** -> modify `scripts/lib/manifest/skills.json`, then run
+   `npm run generate:skill-frontmatter`.
+3. **Edit non-managed frontmatter** -> modify `scripts/skill-templates/<slug>/SKILL.md` directly; the generator
+   preserves it.
+4. **Regenerate the built surface** -> `npm run build:skills`. This rewrites the committed
+   `skills/<slug>/SKILL.md` byte-for-byte from the templates; commit the regenerated `skills/`
+   alongside your template edit so the `build:skills:check` drift gate stays green.
+5. **Verify the build** -> `npm run build:skills:check` (CI gate) confirms compile determinism
+   and that the on-disk `skills/` matches what `scripts/skill-templates/` would generate.
+
+## Placeholders
+
+Four substitution slots are supported by `scripts/lib/build/factory.cjs`:
+
+- `{{command_prefix}}` - slash-command prefix (`/gdd:` for Claude, `/gdd-` for Codex, etc.)
+- `{{model}}` - human-readable model phrase ("your configured Claude model", etc.)
+- `{{config_file}}` - per-harness config path (`.claude/settings.json`, `.codex/config.toml`, ...)
+- `{{ask_instruction}}` - "ask Claude Code", "ask Codex", etc.
+
+Plus conditional blocks: `<!-- harness-only: claude,codex -->BODY<!-- /harness-only -->` keeps
+`BODY` only when the active harness id is in the listed set.
+
+Escape with `\{{ ... }}` to emit a literal `{{...}}` in the output (never substituted).
+
+Full grammar + the per-harness substitution table: `reference/skill-placeholders.md`.
+
+## What npm ships
+
+`package.json` `files` lists `skills/` (the built surface); `scripts/skill-templates/` is repo-only and
+is **not** distributed via npm. The `prepack` lifecycle runs `npm run build:skills` so the tarball
+always contains a freshly-built `skills/`.
+
+## Cross-references
+
+- `scripts/build-skills.cjs` - the multi-harness orchestrator that compiles this directory.
+- `scripts/lib/build/factory.cjs` - the pure transformer applied per-harness.
+- `scripts/lib/manifest/README.md` - explains why `skills.json` is the universal-frontmatter SoT.
+- `scripts/generate-skill-frontmatter.cjs` - manifest -> source-frontmatter generator (with
+  `--check` drift gate and `--extract` reverse mode).
+- `reference/skill-placeholders.md` - placeholder grammar + per-harness substitution table.

package/scripts/skill-templates/add-backlog/SKILL.md

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

package/scripts/skill-templates/analyze-dependencies/SKILL.md

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

package/scripts/skill-templates/apply-reflections/SKILL.md

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