@hegemonart/get-design-done 1.59.2 → 1.59.4

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

@@ -0,0 +1,170 @@
+---
+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.

package/scripts/skill-templates/audit/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: gdd-audit
+description: "Run a design audit by spawning design-auditor, design-integration-checker, and (optionally) design-verifier + design-reflector agents, then printing a consolidated 7-pillar score summary. Use when the user wants to score the current design, retroactively verify a completed cycle, or quickly re-check after a fix. Activates for requests involving scoring an existing design, retroactively reviewing quality, or re-checking after a fix."
+argument-hint: "[--retroactive] [--quick] [--no-reflect]"
+tools: Read, Write, Task, Glob, Bash
+---
+
+# {{command_prefix}}audit
+
+Wraps the existing `design-auditor`, `design-verifier`, and `design-integration-checker` agents - no new auditor logic here. Parses flags, spawns the right combination, prints summary.
+
+For the 7-pillar scoring rubric this skill aggregates, see `../../reference/audit-scoring.md`. For the shared design-quality pillar set that frames the score categories, see `../../reference/shared-preamble.md`.
+
+## Modes
+
+### Default
+Spawn `design-auditor` (7-pillar scoring 1–4) in parallel with `design-integration-checker`. After both finish, read `.design/DESIGN-AUDIT.md` and `.design/DESIGN-INTEGRATION.md` and print a consolidated summary (scores + top 3 findings each).
+
+After the auditor and integration checker complete, check if `.design/learnings/` exists and contains at least one `.md` file. If so - and unless `--no-reflect` is passed - spawn `design-reflector` for the current cycle. Append the reflection proposal count to the audit summary: "Reflection: N proposals → review with `{{command_prefix}}apply-reflections`".
+
+### `--retroactive`
+Spawn `design-verifier` with cycle-span scope. Verifier reads all tasks completed in the current cycle (from STATE.md `<completed_tasks>` list for the active `cycle:` ID) and uses `DESIGN-PLAN.md` goals as the reference baseline for what "should have been done." Output: `.design/DESIGN-VERIFICATION.md` with per-task pass/fail.
+
+### `--quick`
+Run only `design-auditor` (skip `design-integration-checker`). Faster health check when integration isn't the concern.
+
+## Steps
+
+1. Parse args for `--retroactive`, `--quick`, and `--no-reflect`.
+2. Verify `.design/STATE.md` exists; abort if not (suggest `{{command_prefix}}new-project`).
+3. Spawn the appropriate agents (Task tool). Default and `--retroactive` spawn two agents; `--quick` spawns one.
+4. Wait for completion, then read each output file and print a summary:
+   - Auditor scores per pillar
+   - Integration check pass/fail
+   - Verifier pass/fail per task (retroactive mode)
+5. **Reflection step** (default + retroactive modes only, skipped with `--no-reflect` or `--quick`):
+   - Check if `.design/learnings/` exists and has ≥1 `.md` file
+   - If yes: spawn `design-reflector` for the current cycle slug (read from STATE.md)
+   - After completion: count proposal types and append to summary
+6. Recommend next action based on findings (e.g., "Score 2/4 on typography - run `{{command_prefix}}discuss typography` to gather decisions").
+
+## Registered Audit Agents
+
+| Agent | Trigger | Output |
+|---|---|---|
+| `design-auditor` | Default, retroactive | `.design/DESIGN-AUDIT.md` |
+| `design-integration-checker` | Default, retroactive | `.design/DESIGN-INTEGRATION.md` |
+| `design-verifier` | `--retroactive` only | `.design/DESIGN-VERIFICATION.md` |
+| `design-reflector` | Default + retroactive when learnings exist | `.design/reflections/<slug>.md` |
+
+## Do Not
+
+- Do not modify source files.
+- Do not rerun stages; this is a read-only audit.
+
+## Step 7 - Update notice (post-closeout surface)
+
+After the consolidated audit summary has been printed (and any reflection-proposal count appended), emit the plugin-update banner if one is present:
+
+```bash
+[ -f .design/update-available.md ] && cat .design/update-available.md
+```
+
+Written by `hooks/update-check.sh`; suppressed mid-pipeline and when the latest release is dismissed.
+
+## Rationalizations - Thought to Reality
+
+The excuses an agent reaches for to skip or thin out an audit, and the drift each one misses:
+
+| Thought | Reality |
+|---------|---------|
+| "The audit passed last cycle, I can skip it this cycle." | Per-cycle audit catches drift the prior pass couldn't see; a skipped review is exactly where regressions accumulate unnoticed. |
+| "`--quick` is fine, integration isn't the concern here." | Dropping the integration-checker hides orphaned decisions - wiring breaks even when the 7-pillar score looks healthy. |
+| "I can eyeball the scores instead of spawning the auditor." | The auditor's rubric scores seven pillars consistently; an eyeballed review drifts toward whatever the agent already believes. |
+| "Reflection proposals are optional polish, skip the reflector." | The reflector turns this cycle's learnings into next-cycle improvements; skipping it lets the same mistakes repeat. |
+| "I'll modify the source while I'm in here fixing findings." | Audit is read-only by contract; editing source mid-audit invalidates the very scores you're producing. |
+| "Retroactive mode is overkill for a finished cycle." | Retroactive verification is the only check on tasks that shipped without per-task verify - skipping it leaves a completed cycle unaudited. |
+
+## AUDIT COMPLETE

package/scripts/skill-templates/bandit-reset/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: gdd-bandit-reset
+description: "Confirm-then-reset the per-(agent, bin, delegate) bandit posterior - backs up .design/telemetry/posterior.json to posterior.json.bak, then clears it to a fresh empty envelope. Mutation companion to read-only bandit-status. Use when the posterior is corrupted/unparseable, after a major agent/skill roster change invalidates accumulated arms, or when you deliberately want to rebootstrap adaptive routing from informed priors."
+argument-hint: "[--yes to skip the confirmation prompt]"
+tools: Read, Write, Bash, AskUserQuestion
+disable-model-invocation: true
+---
+
+# gdd-bandit-reset
+
+## Role
+
+You are a deterministic, destructive maintenance skill. You are the ONLY skill that clears the bandit posterior - the mutation companion to read-only `{{command_prefix}}bandit-status`. You read the posterior path declared by `scripts/lib/bandit-router.cjs`'s `DEFAULT_POSTERIOR_PATH` (`.design/telemetry/posterior.json`), REQUIRE explicit confirmation, back the file up to `posterior.json.bak`, then overwrite it with a fresh empty envelope so the next bandit pull rebootstraps from informed priors. See `./reference/bandit-integration.md` for setup, interpretation, and convergence guidance.
+
+## Invocation Contract
+
+- **Input**: optional `--yes` to skip the interactive confirmation (for non-interactive/automated runs).
+- **Output**: a Markdown reset receipt to stdout (backup path + arms cleared + envelope written).
+
+## Procedure
+
+### 1. Locate the posterior file
+
+Read `.design/telemetry/posterior.json` (path declared by `scripts/lib/bandit-router.cjs`'s `DEFAULT_POSTERIOR_PATH` - never hardcode a different path). Missing → nothing to reset; emit and skip to Section 5 (Record):
+
+```
+## Bandit Posterior Reset
+
+No posterior file found at `.design/telemetry/posterior.json` — nothing to reset.
+
+The next bandit pull with `adaptive_mode: full` will bootstrap a fresh posterior from informed priors. See `reference/bandit-integration.md`.
+```
+
+If present, count the arms (`arms.length`, treating a missing/non-array `arms` as `0`) so the confirmation and receipt can report what will be cleared. A corrupted/unparseable file is still resettable - report `arms: unknown (file unparseable)` and continue.
+
+### 2. Require explicit confirmation
+
+This is a DESTRUCTIVE operation. Do NOT proceed without confirmation.
+
+- If `--yes` was passed, skip straight to Section 3.
+- Otherwise, prompt via AskUserQuestion: "Reset the bandit posterior at `.design/telemetry/posterior.json`? This clears <N> learned arms. A backup will be written to `posterior.json.bak` first." with options **Reset** and **Cancel**.
+- On **Cancel** (or any non-affirmative answer), abort WITHOUT touching either the posterior or the backup, and emit:
+
+```
+## Bandit Posterior Reset — Cancelled
+
+No changes made. The posterior at `.design/telemetry/posterior.json` is untouched (<N> arms).
+```
+
+Then skip to Section 5 (Record) with `reset: false`.
+
+### 3. Back up the current posterior
+
+Copy the live posterior to `.design/telemetry/posterior.json.bak` (sibling backup) BEFORE clearing it, so the previous state is always recoverable. Overwrite any existing `.bak` from a prior reset. If the backup write fails, ABORT before clearing; never clear without a successful backup.
+
+### 4. Clear to a fresh empty envelope
+
+Overwrite `.design/telemetry/posterior.json` with a fresh empty envelope matching `scripts/lib/bandit-router.cjs`'s `loadPosterior()` shape (`SCHEMA_VERSION` = `1.0.0`, current ISO `generated_at`, empty `arms`):
+
+```json
+{
+  "schema_version": "1.0.0",
+  "generated_at": "<ISO>",
+  "arms": []
+}
+```
+
+Write atomically where possible (`.tmp` + rename, mirroring `savePosterior()`). Then emit the receipt:
+
+```
+## Bandit Posterior Reset
+
+Posterior cleared. The next bandit pull with `adaptive_mode: full` will rebootstrap from informed priors.
+
+- Backup: `.design/telemetry/posterior.json.bak`
+- Arms cleared: <N>
+- Fresh envelope: `.design/telemetry/posterior.json` (schema_version 1.0.0, 0 arms)
+
+Restore the previous state with: `cp .design/telemetry/posterior.json.bak .design/telemetry/posterior.json`
+Verify the cleared state with `{{command_prefix}}bandit-status`. See `reference/bandit-integration.md`.
+```
+
+### 5. Record
+
+Append one JSONL line to `.design/skill-records.jsonl`: `{"skill":"gdd-bandit-reset","ts":"<ISO>","reset":<bool>,"arms_cleared":<count>,"backup_written":<bool>}`. The skill mutates ONLY the posterior (+ its `.bak`) and appends to skill-records.jsonl (telemetry); it touches no other state.
+
+## Cross-references
+
+- `{{command_prefix}}bandit-status` - read-only companion; inspect the posterior before/after a reset.
+- `./reference/bandit-integration.md` - operator guide; interpretation patterns and when a reset is warranted.
+- `scripts/lib/bandit-router.cjs` - posterior shape, `DEFAULT_POSTERIOR_PATH`, `SCHEMA_VERSION`, `loadPosterior()`, `savePosterior()`, `reset()`.

package/scripts/skill-templates/bandit-status/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: gdd-bandit-status
+description: "Surface read-only per-(agent, bin, delegate) bandit posterior snapshot - alpha/beta/mean/stddev/count/last-used per arm. Phase 27.5 (v1.27.5) diagnostic. Use when investigating 'why did the bandit pick tier X for agent Y?' or when verifying posterior convergence after enabling adaptive_mode: full."
+argument-hint: ""
+tools: Read, Bash
+---
+
+# gdd-bandit-status
+
+## Role
+
+You are a deterministic, read-only diagnostic skill. You do not spawn agents and do not modify the posterior. You read `.design/telemetry/posterior.json` (path declared by `scripts/lib/bandit-router.cjs`'s `DEFAULT_POSTERIOR_PATH`), aggregate per-`(agent, bin, delegate, tier)` arm state, and emit a single Markdown table. Read-only per Phase 27.5 D-11 - to reset, use `{{command_prefix}}bandit-reset` (Phase 23.5). See `./reference/bandit-integration.md` for setup, interpretation, and convergence guidance.
+
+## Invocation Contract
+
+- **Input**: none.
+- **Output**: a Markdown bandit-status table to stdout. The table is the entire output.
+
+## Procedure
+
+### 1. Locate the posterior file
+
+Read `.design/telemetry/posterior.json`. Missing → emit empty-state message:
+
+```
+## Bandit Posterior Snapshot
+
+No posterior data yet — run a few pipeline cycles with `adaptive_mode: full` first.
+
+No posterior data found at `.design/telemetry/posterior.json`.
+
+Possible reasons:
+- `adaptive_mode` is `static` or `hedge` (bandit silent — see `.design/budget.json`).
+- No spawns have fired since Phase 27.5 wiring landed.
+- Posterior was cleared via `{{command_prefix}}bandit-reset`.
+
+See `reference/bandit-integration.md` for setup guidance.
+```
+
+Skip to Section 4 (Record). Parse failure (truncated/corrupted) → emit `Posterior file exists but is unparseable. Run {{command_prefix}}bandit-reset to start fresh, or restore from a backup.`
+
+### 2. Parse the posterior
+
+Schema:
+
+```json
+{
+  "schema_version": "1.0.0",
+  "generated_at": "<ISO>",
+  "arms": [{ "agent": "...", "bin": "...", "tier": "...", "delegate": "...", "alpha": N, "beta": N, "last_used": "...", "count": N }]
+}
+```
+
+The `delegate` field is optional - absent = Phase 23.5 legacy slice (rendered as `-` in the table).
+
+### 3. Render the table
+
+Compute per arm: `mean = alpha / (alpha + beta)` (3 decimals), `stddev = sqrt(alpha*beta / ((alpha+beta)^2 * (alpha+beta+1)))` (3 decimals).
+
+Sort by `(agent ASC, bin ASC, delegate ASC where '-' first, tier ASC opus<sonnet<haiku, last_used DESC)`. Group by agent for readability.
+
+Emit:
+
+```
+## Bandit Posterior Snapshot
+
+Per-(agent, bin, delegate, tier) posterior state. Read-only — to reset use `{{command_prefix}}bandit-reset` (Phase 23.5).
+
+Posterior file: `.design/telemetry/posterior.json` (last updated: <generated_at>)
+Total arms: <count>
+
+| Agent | Bin | Delegate | Tier | Alpha | Beta | Mean | Stddev | Count | Last Used |
+|-------|-----|----------|------|-------|------|------|--------|-------|-----------|
+| ...   | ... | ...      | ...  | ...   | ...  | ...  | ...    | ...   | ...       |
+
+> Mean = alpha / (alpha + beta). Stddev = sqrt(alpha*beta / ((alpha+beta)^2 * (alpha+beta+1))).
+> Delegate '-' = Phase 23.5 legacy slice (equivalent to 'none').
+> See `reference/bandit-integration.md` for interpretation.
+> Read-only — use `{{command_prefix}}bandit-reset` to clear posterior state.
+```
+
+Precision: alpha/beta 2 decimals; mean/stddev 3 decimals; count integer; `last_used` truncated to minute (`YYYY-MM-DDTHH:MM`); null `last_used` renders `-`.
+
+After the table, surface a per-`(agent, bin)` best-arm summary: for each unique pair, identify highest-mean arm (tie-broken by `count` DESC) - answers "why did the bandit pick tier X?" at a glance.
+
+### 4. Record
+
+Append one JSONL line to `.design/skill-records.jsonl`: `{"skill":"gdd-bandit-status","ts":"<ISO>","arms_seen":<count>,"posterior_present":<bool>}`. Skill writes ONLY to skill-records.jsonl (telemetry); never touches the posterior.
+
+## Cross-references
+
+- `./reference/bandit-integration.md` - operator guide; interpretation patterns.
+- `scripts/lib/bandit-router.cjs` (Phase 23.5) - posterior shape, `DEFAULT_POSTERIOR_PATH`, `loadPosterior()`.
+- `scripts/lib/bandit-router/integration.cjs` (27.5-01), `hooks/budget-enforcer.ts` (27.5-02), `scripts/lib/session-runner/index.ts` (27.5-03), `scripts/lib/bandit-arbitrage.cjs` (27.5-04), `{{command_prefix}}bandit-reset` (Phase 23.5) - only surface that mutates the posterior.

package/scripts/skill-templates/benchmark/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: gdd-benchmark
+description: "Harvest and synthesize per-component design benchmarks from 18 design systems and produce canonical component specs at `reference/components/<name>.md`. Use when adding a new component spec, running a benchmark wave, listing corpus coverage, or refreshing a spec after a design-system version bump."
+argument-hint: "<component> | --wave <N> | --list | --refresh <component>"
+tools: Read, Write, Bash, Grep, Glob, Task, WebFetch
+---
+
+# {{command_prefix}}benchmark
+
+Harvest per-component design knowledge from 18 design systems and synthesize canonical
+specs at `reference/components/<name>.md`. The 18-source corpus + fallback chain lives in
+`../../connections/design-corpora.md`. Per-skill output discipline + completion-marker
+conventions are at `../../reference/shared-preamble.md#output-contract-reminders`.
+
+## Invocation Modes
+
+| Invocation | Action |
+|------------|--------|
+| `{{command_prefix}}benchmark <component>` | Harvest + synthesize a single component |
+| `{{command_prefix}}benchmark --wave <N>` | Run a full wave (1 = Inputs, 2 = Containers, etc.) |
+| `{{command_prefix}}benchmark --list` | Show corpus coverage - which specs exist, which are pending |
+| `{{command_prefix}}benchmark --refresh <component>` | Re-harvest a spec (for design-system version bumps) |
+
+## Single-Component Flow (`{{command_prefix}}benchmark <component>`)
+
+1. **Check if spec exists** - `Glob("reference/components/<component>.md")`. If found and `--refresh` was not passed, confirm before overwriting.
+
+2. **Harvest** - spawn `component-benchmark-harvester` with required-reading `@connections/design-corpora.md`, target component, raw-output path `.planning/benchmarks/raw/<component>.md`, and a salvage hint to `.planning/research/impeccable-salvage/`. Acceptance: raw harvest exists with ≥4 source sections.
+
+3. **Synthesize** - spawn `component-benchmark-synthesizer` with required-reading `@.planning/benchmarks/raw/<component>.md`, `@reference/components/TEMPLATE.md`, `@reference/anti-patterns.md`. Output: `reference/components/<component>.md`. Also update `reference/components/README.md` (add entry in correct category). Acceptance: spec ≤350 lines, cites ≥4 systems, follows `TEMPLATE.md` sections, has a WAI-ARIA keyboard contract + a failing-example block.
+
+4. **Report** - print spec path, line count, systems cited.
+
+## Wave Mode (`{{command_prefix}}benchmark --wave <N>`)
+
+Read the wave definition from `reference/components/README.md` and run each component sequentially (not parallel - each harvest is network-bound and the raw files are large).
+
+| Wave | Components |
+|------|-----------|
+| 1 | button, input, select-combobox, checkbox, radio, switch, link, label |
+| 2 | card, modal-dialog, drawer, popover, tooltip, accordion, tabs |
+
+Print progress per component: `[N/total] harvesting <component>…`
+
+## List Mode (`{{command_prefix}}benchmark --list`)
+
+Read `reference/components/README.md` and diff against `reference/components/*.md` files. Print a table with columns: Component, Status, Wave, Lines.
+
+## Refresh Mode (`{{command_prefix}}benchmark --refresh <component>`)
+
+Same as single-component flow but skips the "already exists" guard. Use when a design system ships a breaking update to a component's spec.
+
+## Source List
+
+`../../connections/design-corpora.md` - 18 design systems with canonical URLs, licensing, and fallback chain (canonical → archive.org → Refero MCP → Pinterest MCP).
+
+## Output Artifacts
+
+| Artifact | Purpose |
+|----------|---------|
+| `.planning/benchmarks/raw/<component>.md` | Raw multi-source harvest (input only) |
+| `reference/components/<component>.md` | Canonical spec (distributed with plugin) |
+| `reference/components/README.md` | Corpus index (updated by synthesizer) |
+
+## BENCHMARK COMPLETE

package/scripts/skill-templates/bootstrap-ds/SKILL.md

@@ -0,0 +1,43 @@
+---
+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 {{command_prefix}}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
+---
+
+# {{command_prefix}}bootstrap-ds
+
+Greenfield design-system bootstrap. Closes the gap that GDD's `design-context-builder` assumes a design system already exists (in code or Figma) - a brand-new project has none. This skill is the **front door**: it collects a brand input and hands it to `agents/ds-generator.md`, which emits the token system + proof components per `reference/ds-bootstrap-rubric.md` (deterministic math in `scripts/lib/ds/token-scale.cjs`).
+
+## When to use
+
+- At the start of a brand-new project (no `tailwind.config`, no token file, no DS).
+- When `{{command_prefix}}discover` / `design-context-builder` reports **no existing design system** and the user opts to bootstrap one.
+
+If a design system **already exists**, do NOT run this - defer to `design-context-builder` (it maps the existing one). State that and stop.
+
+## Steps
+
+1. **Collect the brand input.** From flags, or via `AskUserQuestion` for anything missing:
+   - **primary** (required) - the brand color (hex / rgb / `oklch()`).
+   - **secondary** (optional) - a second brand color (emitted only if supplied - the rubric's ≤2-brand-colors rule).
+   - **tone tags** (optional) - `calm` / `corporate` / `editorial` / `playful` / `bold` (maps to the type ratio + chroma treatment).
+   - **target framework** (optional) - `web` (default) / `native-ios` / `native-android` / `flutter`. Detect from the project if absent (Phase 34 routing).
+2. **Delegate to `ds-generator`** (via `Task`): it resolves the primary to OKLCH, runs `token-scale.cjs` for **3 variants** (conservative / balanced / bold), and presents them.
+3. **Pick a variant.** Surface the 3 variants (primary `500`, type ratio, spacing baseline, radius, feel); the user picks ONE.
+4. **Emit + scaffold (proposal → confirm).** `ds-generator` emits the chosen token set (role-named CSS custom properties + the framework mapping) and scaffolds **button / input / card** as a coherence proof. Nothing is written to `src/` without confirmation.
+
+## Do Not
+
+- Do not invent a brand (no logomark, no typeface choice, no third brand color) - emit a token *system*, not an identity.
+- Do not overwrite an existing design system - defer to `design-context-builder`.
+- Do not add a color-conversion dependency - `token-scale.cjs` emits native CSS `oklch()`.
+
+## Output
+
+End with:
+
+```
+## BOOTSTRAP-DS COMPLETE
+```