@hegemonart/get-design-done 1.41.5 → 1.43.0

package/sdk/cli/commands/build.ts

@@ -0,0 +1,106 @@
+// sdk/cli/commands/build.ts — Phase 42 (COMPILE-06).
+//
+// `gdd-sdk build skills [--harness <id>] [--zip] [--check]` — compile the per-harness skill bundles
+// from source/skills/ via the orchestrator scripts/build-skills.cjs. The orchestrator is a separate
+// dep-free CJS process (no bundling entanglement with the SDK); we resolve it relative to the package
+// root and spawn it, forwarding stdout/stderr.
+//
+// Exit codes:
+//   * 0 — build (or --check) succeeded.
+//   * 1 — --check found drift (committed != generated).
+//   * 3 — arg / config error (missing/unknown target).
+
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+import {
+  coerceFlags,
+  COMMON_FLAGS,
+  type FlagSpec,
+  type ParsedArgs,
+} from '../parse-args.ts';
+
+const BUILD_FLAGS: readonly FlagSpec[] = [
+  ...COMMON_FLAGS,
+  { name: 'harness', type: 'string' },
+  { name: 'zip', type: 'boolean' },
+  { name: 'check', type: 'boolean' },
+];
+
+export const BUILD_USAGE = `gdd-sdk build skills [flags]
+
+Compile per-harness skill bundles from source/skills/ into dist/<bundle>/ (and regenerate the
+committed Claude-Code surface skills/). One source, N provider bundles.
+
+Flags:
+  --harness <id>   Build only one harness (e.g. claude, codex, gemini). Default: all 14.
+  --zip            Also package each bundle as dist/<bundle>.tgz (needs tar).
+  --check          Verify committed skills/ + dist/claude-code/ match source/ (the drift gate); no writes.
+  -h, --help       Show this help.
+
+Exit codes: 0 ok · 1 drift (--check) · 3 arg error
+`;
+
+interface CommandCtx {
+  readonly stdout: NodeJS.WritableStream;
+  readonly stderr: NodeJS.WritableStream;
+}
+
+/** Walk up from the CLI entry (argv[1]) to the package root that holds scripts/build-skills.cjs. */
+function findOrchestrator(): string | null {
+  let dir = dirname(process.argv[1] ?? process.cwd());
+  for (let i = 0; i < 8; i++) {
+    const candidate = join(dir, 'scripts', 'build-skills.cjs');
+    if (existsSync(candidate)) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  const cwdCandidate = join(process.cwd(), 'scripts', 'build-skills.cjs');
+  return existsSync(cwdCandidate) ? cwdCandidate : null;
+}
+
+export async function buildCommand(parsed: ParsedArgs, ctx: CommandCtx): Promise<number> {
+  if (parsed.flags['help'] === true || parsed.flags['h'] === true) {
+    ctx.stdout.write(BUILD_USAGE);
+    return 0;
+  }
+
+  const target = parsed.positionals[0];
+  if (target !== 'skills') {
+    ctx.stderr.write(`gdd-sdk build: expected target "skills" (got ${target ? `"${target}"` : 'nothing'})\n${BUILD_USAGE}`);
+    return 3;
+  }
+
+  let flags: Record<string, unknown>;
+  try {
+    flags = coerceFlags(parsed, BUILD_FLAGS);
+  } catch {
+    ctx.stderr.write(`gdd-sdk build: invalid flags\n${BUILD_USAGE}`);
+    return 3;
+  }
+
+  const script = findOrchestrator();
+  if (!script) {
+    ctx.stderr.write('gdd-sdk build: could not locate scripts/build-skills.cjs\n');
+    return 3;
+  }
+
+  const orchestratorArgs: string[] = [];
+  if (flags['check'] === true) orchestratorArgs.push('--check');
+  if (flags['zip'] === true) orchestratorArgs.push('--zip');
+  const harness = flags['harness'];
+  if (typeof harness === 'string' && harness.length > 0) {
+    orchestratorArgs.push('--harness', harness);
+  }
+
+  const res = spawnSync(process.execPath, [script, ...orchestratorArgs], { encoding: 'utf8' });
+  if (res.stdout) ctx.stdout.write(res.stdout);
+  if (res.stderr) ctx.stderr.write(res.stderr);
+  if (res.error) {
+    ctx.stderr.write(`gdd-sdk build: failed to run orchestrator: ${res.error.message}\n`);
+    return 3;
+  }
+  return typeof res.status === 'number' ? res.status : 3;
+}

package/sdk/cli/index.js

@@ -8004,6 +8004,83 @@ function errMessage5(err) {
   return String(err);
 }
 
+// sdk/cli/commands/build.ts
+var import_node_child_process = require("node:child_process");
+var import_node_fs22 = require("node:fs");
+var import_node_path20 = require("node:path");
+var BUILD_FLAGS = [
+  ...COMMON_FLAGS,
+  { name: "harness", type: "string" },
+  { name: "zip", type: "boolean" },
+  { name: "check", type: "boolean" }
+];
+var BUILD_USAGE = `gdd-sdk build skills [flags]
+
+Compile per-harness skill bundles from source/skills/ into dist/<bundle>/ (and regenerate the
+committed Claude-Code surface skills/). One source, N provider bundles.
+
+Flags:
+  --harness <id>   Build only one harness (e.g. claude, codex, gemini). Default: all 14.
+  --zip            Also package each bundle as dist/<bundle>.tgz (needs tar).
+  --check          Verify committed skills/ + dist/claude-code/ match source/ (the drift gate); no writes.
+  -h, --help       Show this help.
+
+Exit codes: 0 ok \xB7 1 drift (--check) \xB7 3 arg error
+`;
+function findOrchestrator() {
+  let dir = (0, import_node_path20.dirname)(process.argv[1] ?? process.cwd());
+  for (let i = 0; i < 8; i++) {
+    const candidate = (0, import_node_path20.join)(dir, "scripts", "build-skills.cjs");
+    if ((0, import_node_fs22.existsSync)(candidate)) return candidate;
+    const parent = (0, import_node_path20.dirname)(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  const cwdCandidate = (0, import_node_path20.join)(process.cwd(), "scripts", "build-skills.cjs");
+  return (0, import_node_fs22.existsSync)(cwdCandidate) ? cwdCandidate : null;
+}
+async function buildCommand(parsed, ctx) {
+  if (parsed.flags["help"] === true || parsed.flags["h"] === true) {
+    ctx.stdout.write(BUILD_USAGE);
+    return 0;
+  }
+  const target = parsed.positionals[0];
+  if (target !== "skills") {
+    ctx.stderr.write(`gdd-sdk build: expected target "skills" (got ${target ? `"${target}"` : "nothing"})
+${BUILD_USAGE}`);
+    return 3;
+  }
+  let flags;
+  try {
+    flags = coerceFlags(parsed, BUILD_FLAGS);
+  } catch {
+    ctx.stderr.write(`gdd-sdk build: invalid flags
+${BUILD_USAGE}`);
+    return 3;
+  }
+  const script = findOrchestrator();
+  if (!script) {
+    ctx.stderr.write("gdd-sdk build: could not locate scripts/build-skills.cjs\n");
+    return 3;
+  }
+  const orchestratorArgs = [];
+  if (flags["check"] === true) orchestratorArgs.push("--check");
+  if (flags["zip"] === true) orchestratorArgs.push("--zip");
+  const harness = flags["harness"];
+  if (typeof harness === "string" && harness.length > 0) {
+    orchestratorArgs.push("--harness", harness);
+  }
+  const res = (0, import_node_child_process.spawnSync)(process.execPath, [script, ...orchestratorArgs], { encoding: "utf8" });
+  if (res.stdout) ctx.stdout.write(res.stdout);
+  if (res.stderr) ctx.stderr.write(res.stderr);
+  if (res.error) {
+    ctx.stderr.write(`gdd-sdk build: failed to run orchestrator: ${res.error.message}
+`);
+    return 3;
+  }
+  return typeof res.status === "number" ? res.status : 3;
+}
+
 // sdk/cli/index.ts
 var USAGE6 = `gdd-sdk <command> [flags]
 
@@ -8013,6 +8090,7 @@ Commands:
   query <op>       Typed STATE.md read operations.
   audit            Probe connections + dry-run verify.
   init             Bootstrap a new project.
+  build skills     Compile per-harness skill bundles from source/skills/.
 
 Use 'gdd-sdk <command> -h' for command-specific flags.
 
@@ -8030,7 +8108,8 @@ async function dispatch(parsed, deps = {}) {
     stage: deps.commands?.stage ?? stageCommand,
     query: deps.commands?.query ?? queryCommand,
     audit: deps.commands?.audit ?? auditCommand,
-    init: deps.commands?.init ?? initCommand
+    init: deps.commands?.init ?? initCommand,
+    build: deps.commands?.build ?? buildCommand
   };
   if (parsed.subcommand === null) {
     stdout.write(USAGE6);
@@ -8054,6 +8133,8 @@ async function dispatch(parsed, deps = {}) {
       return await commands.audit(parsed, { stdout, stderr });
     case "init":
       return await commands.init(parsed, { stdout, stderr });
+    case "build":
+      return await commands.build(parsed, { stdout, stderr });
     default:
       stderr.write(
         `gdd-sdk: unknown subcommand "${parsed.subcommand}"
@@ -8067,7 +8148,8 @@ var KNOWN_SUBCOMMANDS = /* @__PURE__ */ new Set([
   "stage",
   "query",
   "audit",
-  "init"
+  "init",
+  "build"
 ]);
 async function main(argv = process.argv.slice(2), deps = {}) {
   const parsed = parseArgs(argv);

package/sdk/cli/index.ts

@@ -21,6 +21,7 @@ import { stageCommand } from './commands/stage.ts';
 import { queryCommand } from './commands/query.ts';
 import { auditCommand } from './commands/audit.ts';
 import { initCommand } from './commands/init.ts';
+import { buildCommand } from './commands/build.ts';
 
 // ---------------------------------------------------------------------------
 // Top-level USAGE.
@@ -34,6 +35,7 @@ Commands:
   query <op>       Typed STATE.md read operations.
   audit            Probe connections + dry-run verify.
   init             Bootstrap a new project.
+  build skills     Compile per-harness skill bundles from source/skills/.
 
 Use 'gdd-sdk <command> -h' for command-specific flags.
 
@@ -57,6 +59,7 @@ export interface DispatcherDeps {
     readonly query?: typeof queryCommand;
     readonly audit?: typeof auditCommand;
     readonly init?: typeof initCommand;
+    readonly build?: typeof buildCommand;
   };
 }
 
@@ -81,6 +84,7 @@ export async function dispatch(
     query: deps.commands?.query ?? queryCommand,
     audit: deps.commands?.audit ?? auditCommand,
     init: deps.commands?.init ?? initCommand,
+    build: deps.commands?.build ?? buildCommand,
   };
 
   // Bare invocation or top-level help → USAGE.
@@ -111,6 +115,8 @@ export async function dispatch(
       return await commands.audit(parsed, { stdout, stderr });
     case 'init':
       return await commands.init(parsed, { stdout, stderr });
+    case 'build':
+      return await commands.build(parsed, { stdout, stderr });
     default:
       stderr.write(
         `gdd-sdk: unknown subcommand "${parsed.subcommand}"\n${USAGE}`,
@@ -125,6 +131,7 @@ const KNOWN_SUBCOMMANDS: ReadonlySet<string> = new Set([
   'query',
   'audit',
   'init',
+  'build',
 ]);
 
 // ---------------------------------------------------------------------------

package/skills/add-backlog/SKILL.md

@@ -10,11 +10,11 @@ disable-model-invocation: true
 
 **Role:** Long-term parking lot for design ideas. Backing store: `.design/backlog/BACKLOG.md`.
 
-## Step 1 — Get text
+## Step 1 - Get text
 
 If `$ARGUMENTS` is empty, ask the user: "What should be added to the backlog?"
 
-## Step 2 — Append
+## Step 2 - Append
 
 Create `.design/backlog/` directory and `BACKLOG.md` with `# Design Backlog` header if missing.
 
@@ -43,6 +43,6 @@ 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.
+- Do not set status to anything other than `parked` here - `/gdd:review-backlog` owns status transitions.
 
 ## ADD-BACKLOG COMPLETE

package/skills/analyze-dependencies/SKILL.md

@@ -6,7 +6,7 @@ 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).
+**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
 
@@ -26,13 +26,13 @@ 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
+- `/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
+## Analysis 1 - Token fan-out
 
 Surfaces tokens referenced in many files + orphans (referenced exactly once).
 
@@ -42,7 +42,7 @@ Surfaces tokens referenced in many files + orphans (referenced exactly once).
 
 Header: `━━━ Token fan-out ━━━` … `(top 20 shown)` … `Orphaned tokens (referenced in exactly 1 file):` … footer rule.
 
-## Analysis 2 — Component call-graph
+## Analysis 2 - Component call-graph
 
 Surfaces widely-referenced components and the files referencing each.
 
@@ -52,7 +52,7 @@ Surfaces widely-referenced components and the files referencing each.
 
 Header: `━━━ Component call-graph ━━━` … footer rule.
 
-## Analysis 3 — Decision traceability
+## Analysis 3 - Decision traceability
 
 Maps decisions to skill/agent files that cite them.
 
@@ -64,7 +64,7 @@ Maps decisions to skill/agent files that cite them.
 
 Empty-state: `No decisions indexed. Run node scripts/build-intel.cjs after creating .design/DESIGN-CONTEXT.md.`
 
-## Analysis 4 — Circular dependency detection
+## 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".
 

package/skills/apply-reflections/SKILL.md

@@ -45,14 +45,14 @@ Change: ...
 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>`."
+- **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.
+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
 
@@ -73,12 +73,12 @@ Incubator drafts authored by `scripts/lib/incubator-author.cjs` (Phase 29-04) ap
 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.
+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].
+**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]
 
@@ -87,6 +87,6 @@ KFM-catalogue proposals authored by `scripts/lib/reflector-kfm-proposer.cjs` (Ph
 ## 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.
+- 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/skills/apply-reflections/apply-reflections-procedure.md

@@ -7,7 +7,7 @@ tags: [apply-reflections, proposal, frontmatter, reference, budget, question, gl
 last_updated: 2026-05-21
 ---
 
-# Apply-Reflections — Per-Type Procedure
+# 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 →
@@ -64,7 +64,7 @@ the proposal's bracketed type tag.
    <content>
    ```
 
-5. Print: "Global skill written to ~/.claude/gdd/global-skills/<name>.md — auto-loads in all future gdd sessions"
+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]
@@ -82,33 +82,33 @@ Use `scripts/lib/apply-reflections/incubator-proposals.cjs` for all actions.
 
 **Per-action behavior:**
 
-1. **accept** — call `applyAccept(draft, { registryPath, repoRoot })`.
+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."
+   - 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.
+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**`.
+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.
+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):**
+**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.
+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.
+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.
+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):
 
@@ -133,7 +133,7 @@ bandit.updateWithDelegate({
 });
 ```
 
-Omitting `prior_class` reverts to Phase 23.5 informed-prior bootstrap (non-breaking). The reward math is unchanged — `prior_class` only affects bootstrap.
+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]
 
@@ -141,7 +141,7 @@ Known-failure-mode catalogue proposals come from `scripts/lib/reflector-kfm-prop
 
 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).
+- `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:
 
@@ -153,18 +153,18 @@ Use `scripts/lib/reflector-kfm-proposer.cjs` for all actions:
 
 **Per-action behavior:**
 
-1. **accept** — call `applyAccept(draftPath, { repoRoot })`.
+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."
+   - 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."
+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."
+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.
+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.
+**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/skills/audit/SKILL.md

@@ -7,7 +7,7 @@ tools: Read, Write, Task, Glob, Bash
 
 # /gdd: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.
+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 6-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`.
 
@@ -16,7 +16,7 @@ For the 6-pillar scoring rubric this skill aggregates, see `../../reference/audi
 ### Default
 Spawn `design-auditor` (6-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 `/gdd:apply-reflections`".
+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 `/gdd: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.
@@ -37,7 +37,7 @@ Run only `design-auditor` (skip `design-integration-checker`). Faster health che
    - 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 `/gdd:discuss typography` to gather decisions").
+6. Recommend next action based on findings (e.g., "Score 2/4 on typography - run `/gdd:discuss typography` to gather decisions").
 
 ## Registered Audit Agents
 
@@ -53,7 +53,7 @@ Run only `design-auditor` (skip `design-integration-checker`). Faster health che
 - Do not modify source files.
 - Do not rerun stages; this is a read-only audit.
 
-## Step 7 — Update notice (post-closeout surface)
+## 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:
 
@@ -63,17 +63,17 @@ After the consolidated audit summary has been printed (and any reflection-propos
 
 Written by `hooks/update-check.sh`; suppressed mid-pipeline and when the latest release is dismissed.
 
-## Rationalizations — Thought to Reality
+## 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 6-pillar score looks healthy. |
+| "`--quick` is fine, integration isn't the concern here." | Dropping the integration-checker hides orphaned decisions - wiring breaks even when the 6-pillar score looks healthy. |
 | "I can eyeball the scores instead of spawning the auditor." | The auditor's rubric scores six 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. |
+| "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/skills/bandit-status/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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."
+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
 ---
@@ -9,7 +9,7 @@ tools: Read, Bash
 
 ## 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 `/gdd:bandit-reset` (Phase 23.5). See `./reference/bandit-integration.md` for setup, interpretation, and convergence guidance.
+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 `/gdd:bandit-reset` (Phase 23.5). See `./reference/bandit-integration.md` for setup, interpretation, and convergence guidance.
 
 ## Invocation Contract
 
@@ -51,7 +51,7 @@ Schema:
 }
 ```
 
-The `delegate` field is optional — absent = Phase 23.5 legacy slice (rendered as `-` in the table).
+The `delegate` field is optional - absent = Phase 23.5 legacy slice (rendered as `-` in the table).
 
 ### 3. Render the table
 
@@ -81,7 +81,7 @@ Total arms: <count>
 
 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.
+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
 
@@ -89,6 +89,6 @@ Append one JSONL line to `.design/skill-records.jsonl`: `{"skill":"gdd-bandit-st
 
 ## 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), `/gdd:bandit-reset` (Phase 23.5) — only surface that mutates the posterior.
+- `./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), `/gdd:bandit-reset` (Phase 23.5) - only surface that mutates the posterior.