@hegemonart/get-design-done 1.57.2 → 1.58.0

package/skills/README.md

@@ -0,0 +1,82 @@
+# `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's gitignored and regenerated automatically:
+
+- on `npm install` (via the `prepare` lifecycle script) - so developer clones work immediately
+- on `npm pack` / `npm publish` (via `prepack`) - so the published tarball ships pre-built skills
+
+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 `/gdd:` placeholders
+in the file Claude reads, the literal text `/gdd:` 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 `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) | `skill-templates/<slug>/SKILL.md` | `scripts/build-skills.cjs` walks `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 `skill-templates/<slug>/SKILL.md`, then `build:skills` copies it onward |
+| **Non-managed frontmatter** (e.g. `color`, `model`, custom keys) | `skill-templates/<slug>/SKILL.md` itself (preserved verbatim) | carried through both generators unchanged |
+
+The forward direction is **`skills.json` -> `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 `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 `skill-templates/<slug>/SKILL.md` directly; the generator
+   preserves it.
+4. **Regenerate the built surface** -> `npm run build:skills`. This rewrites the gitignored
+   `skills/<slug>/SKILL.md` byte-for-byte from the templates.
+5. **Verify the build** -> `npm run build:skills:check` (CI gate) confirms compile determinism
+   and that the on-disk `skills/` matches what `skill-templates/` would generate.
+
+## Placeholders
+
+Four substitution slots are supported by `scripts/lib/build/factory.cjs`:
+
+- `/gdd:` - slash-command prefix (`/gdd:` for Claude, `/gdd-` for Codex, etc.)
+- `your configured Claude model` - human-readable model phrase ("your configured Claude model", etc.)
+- `.claude/settings.json` - per-harness config path (`.claude/settings.json`, `.codex/config.toml`, ...)
+- `ask Claude Code` - "ask Claude Code", "ask Codex", etc.
+
+Plus conditional blocks: `BODY` 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); `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/skills/bootstrap-ds/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-bootstrap-ds
-description: "Bootstraps a design system for a GREENFIELD project that has none - no Figma, no tokens, no component library. Takes a brand input (primary color + optional secondary + tone tags + target framework) and emits a coherent OKLCH token system (color tints, modular type scale, 4pt/8pt spacing, radius + motion defaults) in 3 variants to pick from, then scaffolds proof components (button/input/card). Use at the start of a brand-new project, or when /gdd:discover finds no existing design system. Never invents a brand; never overwrites an existing DS."
+description: "Bootstraps a design system for a GREENFIELD project that has none - no Figma, no tokens, no component library. Takes a brand input (primary color + optional secondary + tone tags + target framework) and emits a coherent OKLCH token system (color tints, modular type scale, 4pt/8pt spacing, radius + motion defaults) in 3 variants to pick from, then scaffolds proof components (button/input/card). Use at the start of a brand-new project, or when /gdd:explore finds no existing design system. Never invents a brand; never overwrites an existing DS."
 argument-hint: "[--primary <color>] [--secondary <color>] [--tone <tags>] [--framework web|native-ios|native-android|flutter]"
 user-invocable: true
 tools: Read, Write, Bash, Glob, Grep, AskUserQuestion, Task

package/skills/compare/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-compare
-description: "Compute the delta between the `DESIGN.md` baseline (from scan) and the `DESIGN-VERIFICATION.md` result (from verify), reporting per-category score delta, anti-pattern delta (resolved vs new), must-have pass/fail change, and design drift (regressions without covering tasks in `DESIGN-PLAN.md`). Use after `verify` to measure whether a design pipeline cycle actually improved the design. Writes `.design/COMPARE-REPORT.md`. Activates for requests involving diffing a design baseline against verification output, or a before-after design delta."
+description: "Compute the delta between the `DESIGN.md` baseline (from explore) and the `DESIGN-VERIFICATION.md` result (from verify), reporting per-category score delta, anti-pattern delta (resolved vs new), must-have pass/fail change, and design drift (regressions without covering tasks in `DESIGN-PLAN.md`). Use after `verify` to measure whether a design pipeline cycle actually improved the design. Writes `.design/COMPARE-REPORT.md`. Activates for requests involving diffing a design baseline against verification output, or a before-after design delta."
 argument-hint: ""
 user-invocable: true
 ---

package/skills/new-cycle/SKILL.md

@@ -7,7 +7,7 @@ tools: Read, Write, AskUserQuestion
 
 # /gdd:new-cycle
 
-The cycle is the hierarchical unit above individual pipeline runs: **Cycle > Pipeline run > Wave > Task**. Each cycle has a goal, tracks its own decisions, and can span many pipeline runs. See `./milestone-completeness-rubric.md` §"Cycle level" for what counts as cycle completion (used by `/gdd:complete-cycle` to close the cycle).
+The cycle is the hierarchical unit above individual pipeline runs: **Cycle > Pipeline run > Wave > Task**. Each cycle has a goal, tracks its own decisions, and can span many pipeline runs. `/gdd:complete-cycle` closes the cycle once goals are met and a retrospective is captured.
 
 ## Steps
 

package/skills/new-skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-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 source/skills/<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 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
@@ -8,7 +8,7 @@ user-invocable: true
 
 # /gdd:new-skill
 
-**Role:** Interactively scaffold a contract-compliant skill. Gather the fields, then write `source/skills/<name>/SKILL.md` from the pure generator at `scripts/lib/manifest/scaffolder.cjs`. This skill writes ONE source file. It does NOT touch `scripts/lib/manifest/skills.json` and does NOT run the build; it prints the exact follow-up commands instead.
+**Role:** Interactively scaffold a contract-compliant skill. Gather the fields, then write `skill-templates/<name>/SKILL.md` from the pure generator at `scripts/lib/manifest/scaffolder.cjs`. This skill writes ONE source file. It does NOT touch `scripts/lib/manifest/skills.json` and does NOT run the build; it prints the exact follow-up commands instead.
 
 Read `reference/skill-authoring-contract.md` first for the length cap, the frontmatter required fields, and the v3 description form.
 
@@ -27,7 +27,7 @@ Either way the answers feed the same record builder. Never block waiting on a TT
 
 ## Step 1 - Gather the fields
 
-1. **name**: the slug from `$ARGUMENTS` if present, else ask. Must match `^[a-z0-9][a-z0-9-._]*$`. Reject `source/skills/<name>/` collisions.
+1. **name**: the slug from `$ARGUMENTS` if present, else ask. Must match `^[a-z0-9][a-z0-9-._]*$`. Reject `skill-templates/<name>/` collisions.
 2. **description**: a multi-paragraph v3 form. Sentence one is what the skill does. Sentence two is `Use when <triggers>`. Sentence three is `Activates for requests involving <kw1>, <kw2>, <kw3>.` Keep it 20 to 1024 chars.
 3. **lifecycle stage**: pick one of brief / explore / plan / verify / ship / figma / token / report (free text allowed). This seeds the composition suggestions.
 4. **tools**: a comma list (for example `Read, Write, Bash`). Empty means inherit-all.
@@ -45,7 +45,7 @@ Present the suggestions; let the user accept, edit, or clear them.
 
 ## Step 2 - Length pre-check
 
-Before writing, estimate the body length. If the planned body would exceed about 100 lines, warn the user (the authoring contract warns at 100 and blocks at 250) and suggest extracting domain content into a co-located `source/skills/<name>/<topic>.md` reference. The generated skeleton is small; the warning is for the prose the user will add next.
+Before writing, estimate the body length. If the planned body would exceed about 100 lines, warn the user (the authoring contract warns at 100 and blocks at 250) and suggest extracting domain content into a co-located `skill-templates/<name>/<topic>.md` reference. The generated skeleton is small; the warning is for the prose the user will add next.
 
 ## Step 3 - Write the file
 
@@ -66,7 +66,7 @@ process.stdout.write(s.renderSkillMd(rec));
 "
 ```
 
-`buildSkillRecord` throws on an invalid name, an out-of-budget description, or a malformed tools list. Surface the thrown message to the user and re-prompt the offending field. Capture stdout and write it verbatim to `source/skills/<name>/SKILL.md` via the Write tool.
+`buildSkillRecord` throws on an invalid name, an out-of-budget description, or a malformed tools list. Surface the thrown message to the user and re-prompt the offending field. Capture stdout and write it verbatim to `skill-templates/<name>/SKILL.md` via the Write tool.
 
 ## Step 4 - Tell the user the follow-up
 

package/skills/peer-cli-customize/SKILL.md

@@ -79,7 +79,6 @@ See `./../peer-cli-add/peer-cli-protocol.md` §"Edge cases" for: rewire-to-unmat
 - `scripts/validate-frontmatter.ts` (Plan 27-06) - `delegate_to` validation.
 - `scripts/lib/peer-cli/registry.cjs` (Plan 27-05) - capability matrix.
 - `skills/peer-cli-add/SKILL.md` - for adding a NEW peer (this skill rewires among existing peers).
-- `.planning/phases/27-peer-cli-delegation/CONTEXT.md` D-06 - decision lineage.
 
 ## Record
 

package/skills/peers/SKILL.md

@@ -85,7 +85,7 @@ The table IS the output. No follow-up prose. Users act on it: `(opt-in disabled)
 
 - `./../peer-cli-add/peer-cli-protocol.md` - ACP/ASP handshake + adapter scaffold (procedure ref shared with peer-cli-add/customize).
 - `./reference/peer-cli-capabilities.md` (Plan 27-05) - full capability matrix doc.
-- `scripts/lib/peer-cli/registry.cjs` (Plan 27-05), `scripts/lib/install/runtimes.cjs` (Plan 27-11), `skills/peer-cli-customize/SKILL.md`, `skills/peer-cli-add/SKILL.md`, `.planning/phases/27-peer-cli-delegation/CONTEXT.md` D-10.
+- `scripts/lib/peer-cli/registry.cjs` (Plan 27-05), `scripts/lib/install/runtimes.cjs` (Plan 27-11), `skills/peer-cli-customize/SKILL.md`, `skills/peer-cli-add/SKILL.md`.
 
 ## Record
 

package/skills/reflect/procedures/capability-gap-scan.md

@@ -117,4 +117,3 @@ npm test
 - `reference/schemas/events.schema.json` - the `capability_gap` event class shipped by Plan 29-01 (the 7-field shape + `TrajectoryRef` definition).
 - `scripts/lib/event-chain.cjs` - `appendChainEvent` (the real emitter API; 29-01 did NOT ship a separate helper file).
 - `scripts/lib/bandit-router.cjs` - Phase 23.5 posterior file producer (the source for scan #2).
-- `.planning/phases/29-capability-gap-self-authoring/CONTEXT.md` - phase decisions (D-02 7-field shape, D-07 hash-pinning, D-08 MCP carve-out, D-11 tmpdir tests).

package/skills/report-issue/report-issue-procedure.md

@@ -117,4 +117,3 @@ Body is written to a tmp file to avoid arg-length and shell-escaping. URL parsed
 - [SKILL.md](./SKILL.md) - entry contract.
 - `reference/pseudonymization-rules.md` - full R1..R8 rule catalog (Plan 30-01).
 - `reference/known-failure-modes.md` - triage catalogue (Plan 30-03).
-- `.planning/phases/30-issue-reporter/CONTEXT.md` - phase decisions D-01..D-15.

package/skills/synthesize/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: synthesize
-description: "Streaming synthesizer - collapses N parallel-agent markdown outputs into one compact merged summary via a single Haiku 4.5 call. Invoked inline by orchestrators (skills/map/, skills/discover/, skills/plan/) after parallel spawns return. Not user-invocable."
+description: "Streaming synthesizer - collapses N parallel-agent markdown outputs into one compact merged summary via a single Haiku 4.5 call. Invoked inline by orchestrators (skills/map/, skills/explore/, skills/plan/) after parallel spawns return. Not user-invocable."
 tools: Read, Task
 user-invocable: false
 disable-model-invocation: true

package/skills/turn-closeout/SKILL.md

@@ -9,7 +9,7 @@ tools: Read, Bash
 
 ## Role
 
-You are a deterministic **closeout** skill. You close the per-turn telemetry gap on runtimes that don't expose a Stop event (codex, gemini, and 11 others). You are a code-level mirror of `hooks/gdd-turn-closeout.js` (D-10): same conditions, same idempotence, same emitted event shape. The only difference: the JS hook emits the nudge as `additionalContext` via the harness; this skill prints the nudge directly to the user. See `./../new-cycle/milestone-completeness-rubric.md` §"Task level" for the broader closeout discipline (what "turn complete" means within a stage).
+You are a deterministic **closeout** skill. You close the per-turn telemetry gap on runtimes that don't expose a Stop event (codex, gemini, and 11 others). You are a code-level mirror of `hooks/gdd-turn-closeout.js` (D-10): same conditions, same idempotence, same emitted event shape. The only difference: the JS hook emits the nudge as `additionalContext` via the harness; this skill prints the nudge directly to the user. A turn is "complete" when the verify command exits 0, the `<done>` criterion is observable, and the diff stays within the declared scope - any deviation is logged for the run summary.
 
 **When to invoke:** orchestrator skills (`/gdd:next`, `/gdd:design`, `/gdd:verify`) tail-call this skill as their final step before returning. Adoption is incremental - each orchestrator can wire the tail-call independently; the skill exists as a stable, callable surface today.
 

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

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

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

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

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

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

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

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