@hegemonart/get-design-done 1.31.0 → 1.32.0

package/sdk/primitives/lockfile.cjs

@@ -0,0 +1,201 @@
+// scripts/lib/lockfile.cjs
+//
+// Plan 20-14 — PID+timestamp sibling lockfile for `.cjs` consumers.
+//
+// Algorithm mirrors sdk/state/lockfile.ts (Plan 20-01):
+//   Lock path:     `${target}.lock`
+//   Payload:       { pid: number, host: string, acquired_at: ISO8601 }
+//   Acquire:       atomic `writeFileSync(..., { flag: 'wx' })`
+//   Stale rule:    pid dead (ESRCH via `kill(pid, 0)`) OR `acquired_at` older
+//                  than `staleMs` OR unparseable payload
+//   Release:       unlink; ENOENT is not an error; idempotent
+//
+// Windows: AV scanners and file-indexers can hold a file briefly after
+// close. `wx` create may fail with EPERM/EBUSY even when the target is
+// free; we treat these as transient and loop (same code path as EEXIST).
+//
+// Dependency-cycle note: Plan 20-14's rate-guard + iteration-budget
+// consume this module, and both are required to stay dependency-light so
+// that hooks/budget-enforcer.ts can import them without dragging the
+// gdd-state MCP graph along. Hence this standalone .cjs port instead of
+// calling the .ts version.
+
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+
+const DEFAULT_STALE_MS = 60_000;
+const DEFAULT_MAX_WAIT_MS = 5_000;
+const DEFAULT_POLL_MS = 50;
+
+/**
+ * Acquire an advisory lock at `${path}.lock`. Returns an idempotent
+ * async release function.
+ *
+ * @param {string} path path being locked (we append `.lock`)
+ * @param {object} [opts]
+ * @param {number} [opts.staleMs]   ms after which an existing lock is stale. Default 60_000.
+ * @param {number} [opts.maxWaitMs] total ms to wait before throwing. Default 5_000.
+ * @param {number} [opts.pollMs]    ms between retry attempts. Default 50.
+ * @returns {Promise<() => Promise<void>>} release function
+ * @throws {Error} with name === 'LockAcquisitionError' when maxWaitMs elapses
+ */
+async function acquire(path, opts) {
+  const o = opts || {};
+  const staleMs = Number.isFinite(o.staleMs) ? o.staleMs : DEFAULT_STALE_MS;
+  const maxWaitMs = Number.isFinite(o.maxWaitMs) ? o.maxWaitMs : DEFAULT_MAX_WAIT_MS;
+  const pollMs = Number.isFinite(o.pollMs) ? o.pollMs : DEFAULT_POLL_MS;
+
+  if (staleMs < 0 || maxWaitMs < 0 || pollMs < 0) {
+    throw new Error(
+      `lockfile.acquire: invalid options (staleMs=${staleMs}, maxWaitMs=${maxWaitMs}, pollMs=${pollMs})`,
+    );
+  }
+
+  const lockPath = `${path}.lock`;
+  const payload = JSON.stringify({
+    pid: process.pid,
+    host: os.hostname(),
+    acquired_at: new Date().toISOString(),
+  });
+  const startedAt = Date.now();
+
+  while (true) {
+    try {
+      fs.writeFileSync(lockPath, payload, { flag: 'wx', encoding: 'utf8' });
+      return makeRelease(lockPath);
+    } catch (err) {
+      const code = err && typeof err === 'object' ? err.code : undefined;
+      if (code !== 'EEXIST' && code !== 'EPERM' && code !== 'EBUSY') {
+        throw err;
+      }
+      // Try to read the current holder; if it vanished between EEXIST and
+      // read, loop immediately.
+      const existing = readLockSafe(lockPath);
+      if (existing === null) continue;
+
+      const parsed = parseLock(existing);
+      // Only clear when we're confident the lock is stale: the payload
+      // parses AND the PID/age check says so. An unparseable payload is
+      // treated as fresh — on Windows, AV/indexer can transiently deny
+      // reads (EACCES/EPERM/EBUSY), and clearing under that condition
+      // would let two writers race and lose increments.
+      if (parsed !== null && isStale(parsed, staleMs)) {
+        // Clear stale lock; race-tolerant — if it's already gone we get
+        // ENOENT, no-op.
+        try { fs.unlinkSync(lockPath); } catch { /* ignore */ }
+        continue;
+      }
+
+      if (Date.now() - startedAt >= maxWaitMs) {
+        const e = new Error(
+          `lockfile: failed to acquire ${lockPath} within ${maxWaitMs}ms (held by ${existing})`,
+        );
+        e.name = 'LockAcquisitionError';
+        e.lockPath = lockPath;
+        e.holder = existing;
+        e.waitedMs = Date.now() - startedAt;
+        throw e;
+      }
+      await sleep(pollMs);
+    }
+  }
+}
+
+function makeRelease(lockPath) {
+  let released = false;
+  return async function release() {
+    if (released) return;
+    released = true;
+    try {
+      fs.unlinkSync(lockPath);
+    } catch (err) {
+      const code = err && typeof err === 'object' ? err.code : undefined;
+      if (code === 'ENOENT') return; // idempotent — already gone
+      if (code === 'EPERM' || code === 'EBUSY') {
+        // Windows AV/indexer: retry once.
+        await sleep(50);
+        try {
+          if (fs.existsSync(lockPath)) fs.unlinkSync(lockPath);
+        } catch { /* give up; stale-detection will reclaim */ }
+        return;
+      }
+      // Any other errno: swallow. Best-effort cleanup; stale-age check
+      // will eventually reclaim the lock.
+    }
+  };
+}
+
+function readLockSafe(p) {
+  try {
+    return fs.readFileSync(p, 'utf8');
+  } catch (err) {
+    const code = err && typeof err === 'object' ? err.code : undefined;
+    if (code === 'ENOENT') return null;
+    return '<unreadable>';
+  }
+}
+
+function parseLock(raw) {
+  try {
+    const obj = JSON.parse(raw);
+    if (
+      obj && typeof obj === 'object' &&
+      typeof obj.pid === 'number' &&
+      typeof obj.host === 'string' &&
+      typeof obj.acquired_at === 'string'
+    ) {
+      return obj;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function isStale(payload, staleMs) {
+  if (!isPidAlive(payload.pid, payload.host)) return true;
+  const t = Date.parse(payload.acquired_at);
+  if (!Number.isFinite(t)) return true;
+  return Date.now() - t > staleMs;
+}
+
+function isPidAlive(pid, host) {
+  if (host !== os.hostname()) return true; // can't introspect other hosts
+  if (pid === process.pid) return true;
+  try {
+    process.kill(pid, 0); // signal 0 = validate, don't deliver
+    return true;
+  } catch (err) {
+    const code = err && typeof err === 'object' ? err.code : undefined;
+    if (code === 'ESRCH') return false;
+    // EPERM / EACCES: process exists but is unsignalable; treat as alive.
+    return true;
+  }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * `fs.renameSync` wrapper that retries once on Windows EPERM/EBUSY/EACCES.
+ * AV scanners and the file-indexer can briefly hold a destination open
+ * after another process closed it, causing rename to fail even when the
+ * advisory lock is correctly held.
+ *
+ * Mirrors the inline retry in sdk/state/index.ts mutate().
+ */
+async function renameWithRetry(from, to) {
+  try {
+    fs.renameSync(from, to);
+  } catch (err) {
+    const code = err && typeof err === 'object' ? err.code : undefined;
+    if (code !== 'EPERM' && code !== 'EBUSY' && code !== 'EACCES') throw err;
+    await sleep(50);
+    fs.renameSync(from, to);
+  }
+}
+
+module.exports = { acquire, renameWithRetry };

package/{scripts/lib/gdd-state → sdk/state}/gates.ts

@@ -1,4 +1,4 @@
-// scripts/lib/gdd-state/gates.ts — pure transition-gate functions.
+// sdk/state/gates.ts — pure transition-gate functions.
 //
 // Plan 20-02 (SDK-03): the typed, single-source-of-truth implementation
 // of "can this pipeline advance?" that replaces prose-encoded guards in

package/sdk/state/index.ts

@@ -0,0 +1,167 @@
+// sdk/state/index.ts — public API for the gdd-state module.
+//
+// This is the ONLY file consumers should import from. The module exposes
+// exactly five surface-level names:
+//   * read(path)                    — parse STATE.md from disk
+//   * mutate(path, fn)              — atomic read-modify-write under a lock
+//   * transition(path, toStage)     — gate + stage-advance helper
+//   * ParsedState (type)            — consumer-visible shape
+//   * Stage (type)                  — stage enum
+//
+// Plan 20-02 wired the real transition gates in via `gateFor(from, to)`
+// imported from `./gates.ts`. Plan 20-04 migrated the error classes
+// (TransitionGateFailed, LockAcquisitionError, ParseError) to the
+// unified `gdd-errors` taxonomy — `types.ts` re-exports them verbatim
+// so consumers of `gdd-state` need no changes.
+
+import { readFileSync, writeFileSync, renameSync, unlinkSync, existsSync } from 'node:fs';
+
+import { acquire } from './lockfile.ts';
+import { parse } from './parser.ts';
+import { serialize } from './mutator.ts';
+import { gateFor } from './gates.ts';
+import {
+  TransitionGateFailed,
+  isStage,
+  type ParsedState,
+  type Stage,
+  type TransitionResult,
+} from './types.ts';
+
+export type { ParsedState, Stage } from './types.ts';
+export { TransitionGateFailed, LockAcquisitionError, ParseError } from './types.ts';
+
+/**
+ * Read STATE.md from disk and return the parsed state.
+ *
+ * Shared-read: no lock is taken. Reads are snapshot-safe for markdown
+ * (the OS guarantees a coherent view even if a writer is mid-rename —
+ * we either see the old file or the new file, never a torn write,
+ * because `mutate()` uses atomic rename).
+ */
+export async function read(path: string): Promise<ParsedState> {
+  const raw: string = readFileSync(path, 'utf8');
+  return parse(raw).state;
+}
+
+/**
+ * Atomic read-modify-write on STATE.md.
+ *
+ * Flow:
+ *   1. Acquire sibling `.lock` file (PID+timestamp advisory lock).
+ *   2. Read current contents.
+ *   3. Apply `fn`.
+ *   4. Serialize to a `.tmp` file next to `path`.
+ *   5. `renameSync(.tmp, path)` — POSIX-atomic; on Windows EPERM means
+ *      a scanner held it briefly, retry once.
+ *   6. Release the lock (in `finally` — released even on mid-fn throw).
+ *
+ * Crash between write and rename is benign: STATE.md is untouched; the
+ * `.tmp` file is orphaned (cleaned up on the next acquire by the caller).
+ */
+export async function mutate(
+  path: string,
+  fn: (s: ParsedState) => ParsedState,
+): Promise<ParsedState> {
+  const release = await acquire(path);
+  const tmpPath: string = `${path}.tmp`;
+  try {
+    const raw: string = readFileSync(path, 'utf8');
+    const { state, raw_bodies, raw_frontmatter, block_gaps, line_ending } =
+      parse(raw);
+    // Deep-clone so the consumer's fn cannot mutate the state we just
+    // parsed (defensive — apply() does this too for pure callers).
+    const clone = structuredClone(state);
+    const next = fn(clone);
+    const out = serialize(next, {
+      raw_frontmatter,
+      raw_bodies,
+      block_gaps,
+      line_ending,
+    });
+    writeFileSync(tmpPath, out, 'utf8');
+    try {
+      renameSync(tmpPath, path);
+    } catch (err) {
+      // Windows EPERM retry — AV / indexer holding STATE.md briefly.
+      const code =
+        typeof err === 'object' && err !== null && 'code' in err
+          ? (err as { code?: unknown }).code
+          : undefined;
+      if (code === 'EPERM' || code === 'EBUSY') {
+        await new Promise((r) => setTimeout(r, 50));
+        renameSync(tmpPath, path);
+      } else {
+        throw err;
+      }
+    }
+    return next;
+  } catch (err) {
+    // Clean up the orphaned tmp file on failure so we don't pollute.
+    try {
+      if (existsSync(tmpPath)) unlinkSync(tmpPath);
+    } catch {
+      // best-effort; a leftover tmp file does not corrupt STATE.md.
+    }
+    throw err;
+  } finally {
+    await release();
+  }
+}
+
+/**
+ * Advance to `toStage` under the locked RMW protocol.
+ *
+ * Steps:
+ *   1. Read current state (outside the lock) to pass to the gate.
+ *   2. Resolve the gate via `gateFor(position.stage, toStage)`.
+ *        - `null` → TransitionGateFailed "Invalid transition" (skip-stage,
+ *          backward, same-stage, or from outside the Stage union).
+ *   3. Invoke the gate. If `pass: false`, throw TransitionGateFailed with
+ *      the gate's blockers verbatim.
+ *   4. If `pass: true`, mutate STATE.md under the lock:
+ *        - frontmatter.stage = toStage
+ *        - position.stage = toStage
+ *        - frontmatter.last_checkpoint = now (ISO)
+ *        - timestamps[`${toStage}_started_at`] = now (ISO)
+ *
+ * Returns the updated state plus the gate response (for callers that
+ * want to log blockers — on pass, `blockers` is always `[]`).
+ */
+export async function transition(
+  path: string,
+  toStage: Stage,
+): Promise<TransitionResult> {
+  // Read (outside the lock) to pass current state to the gate — the
+  // mutate() below will re-read under the lock before applying changes.
+  // This two-phase pattern matches the GSD reference implementation.
+  const beforeMutate = await read(path);
+  const from: string = beforeMutate.position.stage;
+  // `position.stage` is typed as `string` in ParsedState (parser tolerates
+  // `scan` and other pre-brief values). Narrow it to `Stage` before asking
+  // the gate registry — anything outside the union is an invalid FROM.
+  if (!isStage(from)) {
+    throw new TransitionGateFailed(toStage, [
+      `Invalid transition: from="${from}" is not a recognized Stage`,
+    ]);
+  }
+  const gate = gateFor(from, toStage);
+  if (gate === null) {
+    throw new TransitionGateFailed(toStage, [
+      `Invalid transition: ${from} → ${toStage}`,
+    ]);
+  }
+  const gateResult = gate(beforeMutate);
+  if (!gateResult.pass) {
+    throw new TransitionGateFailed(toStage, gateResult.blockers);
+  }
+  const nowIso: string = new Date().toISOString();
+  const nextState = await mutate(path, (s): ParsedState => {
+    s.frontmatter.stage = toStage;
+    s.frontmatter.last_checkpoint = nowIso;
+    s.position.stage = toStage;
+    s.timestamps[`${toStage}_started_at`] = nowIso;
+    return s;
+  });
+  return { pass: true, blockers: gateResult.blockers, state: nextState };
+}

package/{scripts/lib/gdd-state → sdk/state}/lockfile.ts

@@ -1,4 +1,4 @@
-// scripts/lib/gdd-state/lockfile.ts — PID+timestamp sibling lockfile.
+// sdk/state/lockfile.ts — PID+timestamp sibling lockfile.
 //
 // Pattern (from GSD state-mutation.ts D2):
 //   Lock file at `${target}.lock` holds JSON

package/{scripts/lib/gdd-state → sdk/state}/mutator.ts

@@ -1,4 +1,4 @@
-// scripts/lib/gdd-state/mutator.ts — serializer + `apply(raw, fn)` mutator.
+// sdk/state/mutator.ts — serializer + `apply(raw, fn)` mutator.
 //
 // Two guarantees:
 //   1. `serialize(parse(raw).state, parse(raw).raw_bodies)` === `raw`

package/{scripts/lib/gdd-state → sdk/state}/parser.ts

@@ -1,4 +1,4 @@
-// scripts/lib/gdd-state/parser.ts — turns STATE.md text into ParsedState.
+// sdk/state/parser.ts — turns STATE.md text into ParsedState.
 //
 // Design constraints:
 //   1. Pure function (no I/O). `read()` in index.ts supplies the file.

package/{scripts/lib/gdd-state → sdk/state}/types.ts

@@ -1,4 +1,4 @@
-// scripts/lib/gdd-state/types.ts — typed shape of a parsed STATE.md.
+// sdk/state/types.ts — typed shape of a parsed STATE.md.
 //
 // Plan 20-01 (SDK-01/02): canonical type surface consumed by the parser,
 // mutator, and public read/mutate/transition API. Everything here is
@@ -241,18 +241,18 @@ export interface TransitionResult extends GateResult {
 
 // Error classes migrated to the unified GDDError taxonomy in Plan 20-04.
 // Re-exported here so existing consumers (tests, downstream modules) keep
-// importing from `gdd-state/types.ts` unchanged.
+// importing from `sdk/state/types.ts` unchanged.
 //
 //   * TransitionGateFailed  — StateConflictError subclass; retryable
 //   * LockAcquisitionError  — StateConflictError subclass; retryable
 //   * ParseError            — ValidationError subclass; fix your STATE.md
 //
-// See `scripts/lib/gdd-errors/index.ts` for the taxonomy definition.
+// See `sdk/errors/index.ts` for the taxonomy definition.
 export {
   TransitionGateFailed,
   LockAcquisitionError,
   ParseError,
-} from '../gdd-errors/index.ts';
+} from '../errors/index.ts';
 
 /** Type-guard for `Stage`. */
 export function isStage(value: unknown): value is Stage {

package/skills/audit/SKILL.md

@@ -63,4 +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
+
+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. |
+| "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. |
+
 ## AUDIT COMPLETE

package/skills/brief/SKILL.md

@@ -92,4 +92,29 @@ Next: @get-design-done explore
 ━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
+## Spec self-review (before transition)
+
+Run this final spec-quality pass over `.design/BRIEF.md` before the brief→explore transition:
+- Placeholder scan: no TBD / TODO / `<placeholder>` / lorem left in the artifact.
+- Internal consistency: sections don't contradict each other.
+- Scope check: nothing in the artifact exceeds (or silently drops) the agreed scope.
+- Ambiguity check: every requirement/decision is specific enough to act on without a follow-up question.
+
+<HARD-GATE>
+Do NOT transition to explore (or invoke `/gdd:explore`) until the brief artifact (default `.design/BRIEF.md`) is committed AND the user has approved it. If this project uses a custom `.design` location, read the artifact path from `.design/STATE.md` rather than assuming the default.
+</HARD-GATE>
+
+## Rationalizations — Thought to Reality
+
+The excuses an agent invents to skip or shortcut the brief, and what each one actually costs the cycle:
+
+| Thought | Reality |
+|---------|---------|
+| "This brief is too simple to need a problem statement." | Skip the brief = guess at requirements, then redesign mid-design when the real problem surfaces. |
+| "The user told me what to build, I can skip the interview." | Unasked constraints (a11y, brand, stack) become rework — the five questions exist because each one has blown a past cycle. |
+| "I'll capture success metrics later in verify." | Verify has nothing to check against; an un-metricked brief produces an un-verifiable cycle. |
+| "Scope is obvious, I don't need an in/out line." | Undeclared scope is scope creep waiting to happen — the explore scan widens to fill the vacuum. |
+| "I can answer all five questions for the user from context." | AskUserQuestion one-at-a-time exists because batched/assumed answers smuggle in wrong premises that compound downstream. |
+| "STATE.md bootstrap can wait." | Every later MCP mutation requires STATE.md to exist; skipping the bootstrap hard-blocks explore on entry. |
+
 ## BRIEF COMPLETE

package/skills/design/SKILL.md

@@ -78,4 +78,21 @@ Print the `=== Design stage complete ===` summary (tasks complete/total, deviati
 
 After all tasks finish, if STATE.md `<connections>` has `figma: available`, offer the user the figma-write opt-in prompt (modes: annotate / tokenize / mappings, with optional `--dry-run`). Spawn `design-figma-writer` with the selected mode on "yes"; skip silently on "no". NEVER auto-run without confirmation. Full prompt + dispatch logic: `./design-procedure.md` §Figma Write Dispatch.
 
+<HARD-GATE>
+Do NOT transition to verify (or invoke `/gdd:verify`) until `.design/DESIGN-SUMMARY.md` is committed. If this project uses a custom `.design` location, read the artifact path from `.design/STATE.md` rather than assuming the default.
+</HARD-GATE>
+
+## Rationalizations — Thought to Reality
+
+The excuses an agent uses to cut corners during design implementation, and the cost of each:
+
+| Thought | Reality |
+|---------|---------|
+| "I can skip planning for this small task and just implement it." | Plan-skipped tasks blow scope per cycle telemetry; the gate is for the typical case, not the exception. |
+| "These two tasks touch nearby files but I'll run them in parallel anyway." | Overlapping `Touches:` in a parallel batch produce merge conflicts that silently drop one task's work — split into sequential sub-waves. |
+| "Hardcoding this value is faster than wiring the token." | A hardcoded value is a stub the verifier catches as drift from the design tokens; you pay for it twice. |
+| "I'll emit the `.stories.tsx` stub later when Storybook is back up." | The CSF stub must land with the component or the next cycle's visual-regression scope misses it entirely. |
+| "This deviation is minor, I won't record a blocker." | An unrecorded deviation can't be resolved by a follow-up task, so it leaks into verify as an unexplained gap. |
+| "Auto-mode means I can ignore the wave checkpoints." | Auto-mode skips prompts, not the wave structure; ignoring wave order still corrupts dependent-task ordering. |
+
 ## DESIGN COMPLETE

package/skills/discuss/SKILL.md

@@ -80,4 +80,17 @@ Cycle: <name or "default">
 - Do not run the interview yourself — always spawn the agent.
 - Do not touch files outside `.design/`.
 
+## Rationalizations — Thought to Reality
+
+The shortcuts an agent takes during a discuss session, and what each one costs the decision record:
+
+| Thought | Reality |
+|---------|---------|
+| "I'll ask all eight questions at once to save time." | Batched questions overwhelm the user; one-at-a-time keeps each decision clean and prevents coupled answers. |
+| "I can run the interview inline instead of spawning the discussant." | The skill's contract is to always spawn the agent — running it yourself skips the discussant's mode handling and D-XX numbering. |
+| "This answer is good enough, I'll record it as a decision without follow-up." | A vague answer ("modern", "clean") recorded as a D-XX locks in an undecided premise; reject and re-ask once. |
+| "I'll batch all the new D-XX entries into STATE.md at the end." | Decisions written atomically per answer survive an interrupted session; batching loses everything if the session drops. |
+| "The glossary term can wait until I write the summary." | CONTEXT.md is written immediately per term — a deferred glossary entry is a naming inconsistency the next cycle inherits. |
+| "Every decision this session is worth an ADR." | ADRs require all three criteria (hard-to-reverse, surprising, real-tradeoff); auto-promoting routine choices buries the genuinely load-bearing ones. |
+
 ## DISCUSS COMMAND COMPLETE

package/skills/explore/SKILL.md

@@ -85,4 +85,21 @@ Full interview protocol + JSON line schema: `./explore-procedure.md` §Step 3.
 
 Print: "=== Explore complete ===\nSaved: .design/DESIGN.md, .design/DESIGN-DEBT.md, .design/DESIGN-CONTEXT.md\nNext: @get-design-done plan".
 
+<HARD-GATE>
+Do NOT transition to plan (or invoke `/gdd:plan`) until BOTH `.design/DESIGN.md` AND `.design/DESIGN-CONTEXT.md` are committed AND the user has approved them. If this project uses a custom `.design` location, read the artifact paths from `.design/STATE.md` rather than assuming the default.
+</HARD-GATE>
+
+## Rationalizations — Thought to Reality
+
+The shortcut excuses an agent reaches for during explore, and the drift each one introduces:
+
+| Thought | Reality |
+|---------|---------|
+| "I already know this codebase, I can skip the inventory scan." | An unscanned codebase hides the tokens/components you'll duplicate — the grep pass exists to stop you reinventing what's there. |
+| "The six connection probes are noise, I'll assume Figma is off." | A skipped probe means a wrong connection assumption silently breaks the design stage's tool dispatch. |
+| "`--skip-interview` is fine, the brief covered it." | The interview locks the gray areas the brief left fuzzy; skipping it ships undecided D-XX into planning. |
+| "I'll batch all the interview questions to save round-trips." | Batched questions overwhelm the user and smuggle in coupled assumptions — one-at-a-time keeps each decision clean. |
+| "DESIGN-DEBT.md is optional, the scan was clean enough." | Unrecorded debt resurfaces as an unexplained constraint three stages later with no provenance. |
+| "Prior sketches and project conventions don't apply this cycle." | Ignored conventions get overridden by defaults, producing inconsistency the audit will flag against the rest of the system. |
+
 ## EXPLORE COMPLETE

package/skills/health/SKILL.md

@@ -63,6 +63,12 @@ After the health table, the `gdd_health` MCP surface (`scripts/lib/health-mirror
 
 Token PRESENCE only is detected (D-10) — the token value is never read, logged, or shown. The Free-tier signal is read from the local raw-pull cache only; no network call is made.
 
+## Skill-discipline bootstrap (skill_discipline)
+
+The `gdd_health` MCP surface also reports a `skill_discipline` check (Phase 32) confirming the using-gdd SessionStart bootstrap is live — detail is one of three exact strings:
+- `skill-discipline: ready` — `skills/using-gdd/SKILL.md` exists AND `hooks/hooks.json` SessionStart wires `inject-using-gdd.sh` (status `ok`).
+- `skill-discipline: missing using-gdd` (skill absent) or `skill-discipline: hook not wired` (skill present, no SessionStart inject) — both `warn`.
+
 ## Check MCP registration (gdd-mcp)
 
 After the health table, inspect whether `gdd-mcp` (Phase 27.7+) is registered with any installed harness and render a one-line status row. Dismissable via `.design/config.json#mcp_nudge=false`. Non-blocking: failure paths render `MCP server: unknown` rather than crash. Full detection procedure (dismissal check, detection via `scripts/lib/install/mcp-register.cjs`, row rendering for claude/codex/both/neither, fallback) lives in `./health-mcp-detection.md`.

package/skills/plan/SKILL.md

@@ -77,4 +77,29 @@ The next stage (design) calls `mcp__gdd_state__transition_stage` on entry — th
 
 Print: plan tasks (N waves, M total tasks), files written (`.design/DESIGN-PLAN.md`, plus `.design/DESIGN-RESEARCH.md` if research ran), next step `/get-design-done:design`.
 
+## Spec self-review (before transition)
+
+Run this final spec-quality pass over `.design/DESIGN-PLAN.md` before the plan→design transition:
+- Placeholder scan: no TBD / TODO / `<placeholder>` / lorem left in the artifact.
+- Internal consistency: sections don't contradict each other.
+- Scope check: nothing in the artifact exceeds (or silently drops) the agreed scope.
+- Ambiguity check: every requirement/decision is specific enough to act on without a follow-up question.
+
+<HARD-GATE>
+Do NOT transition to design (or invoke `/gdd:design`) until `.design/DESIGN-PLAN.md` is committed AND the user has approved it. If this project uses a custom `.design` location, read the artifact path from `.design/STATE.md` rather than assuming the default.
+</HARD-GATE>
+
+## Rationalizations — Thought to Reality
+
+The reasons an agent gives to skip planning or rush DESIGN-PLAN.md, and what each one costs:
+
+| Thought | Reality |
+|---------|---------|
+| "This change is small, I can design straight from DESIGN-CONTEXT.md." | Plan-skipped tasks blow scope per cycle telemetry; the plan gate is for the typical case, not the exception you think you're in. |
+| "Pattern mapping is brownfield ceremony, I'll skip it." | Step 1.5 is mandatory because an unmapped brownfield is where the executor silently re-implements an existing pattern. |
+| "The plan-checker will just rubber-stamp it, skip the spawn." | The checker's 5 dimensions (coverage, wave order, must-have derivation) catch the gaps you can't see in your own plan. |
+| "I'll let the planner infer wave ordering at design time." | Unordered waves serialize work that could parallelize — or worse, run dependent tasks concurrently and corrupt the tree. |
+| "Research is overkill for this scope." | The complexity heuristic exists precisely because agents under-estimate scope; skipping research on a 3+-scope domain guarantees a mid-design surprise. |
+| "I can record decisions in DESIGN-PLAN.md prose instead of D-XX." | Prose decisions never reach STATE.md, so verify's integration-checker can't trace them and flags them orphaned. |
+
 ## PLAN COMPLETE

package/skills/quality-gate/SKILL.md

@@ -58,11 +58,11 @@ Else: increment `iteration`, emit `quality_gate_iteration`, spawn `design-fixer`
 
 ## Step 5 — STATE write
 
-Mutate `state.quality_gate.run` to `{started_at, completed_at, status, iteration, commands_run, extra_attrs:{}}`. Persist via `mcp__gdd_state__set_quality_gate` or `apply()` mutator from `scripts/lib/gdd-state/mutator.ts` — identical on-disk shape.
+Mutate `state.quality_gate.run` to `{started_at, completed_at, status, iteration, commands_run, extra_attrs:{}}`. Persist via `mcp__gdd_state__set_quality_gate` or `apply()` mutator from `sdk/state/mutator.ts` — identical on-disk shape.
 
 ## Step 6 — Event emission (D-09)
 
-Use `appendEvent` from `scripts/lib/event-stream/index.ts` — persist-first / broadcast-second; never throws on persist path. `ts` / `cycle` / `stage` are stamped by the writer. Six event types (one per lifecycle position):
+Use `appendEvent` from `sdk/event-stream/index.ts` — persist-first / broadcast-second; never throws on persist path. `ts` / `cycle` / `stage` are stamped by the writer. Six event types (one per lifecycle position):
 
 | Event | When | Payload |
 |-------|------|---------|

package/skills/router/SKILL.md

@@ -79,6 +79,10 @@ If `.design/budget.json` is missing, assume defaults from `reference/config-sche
 
 When the router cannot resolve `intent-string` to a known agent (no `description` match, no `default-tier` rule, no path-selection fallback), emit ONE `capability_gap` event with `source: "router"` before returning the conservative-fallback JSON. Feeds Phase 29 Stage-0 telemetry — see `./capability-gap-emitter.md` for the synchronous Node snippet, semantic notes (suggested_kind = `"agent"`, MCP-probe exclusion per D-08, back-compat invariant on router output), and the opaque-extras payload routing through `appendChainEvent`.
 
+## Emitting router_pick on a resolved pick
+
+When the router DID resolve a pick — it has the `path`/`complexity_class`/`resolved_models` decision and is about to return the decision JSON — emit ONE `router_pick` event (`source: "router"`) recording which skill/agent was auto-picked, as the last step before returning. Side-effect only; the output JSON contract is UNCHANGED. Feeds the D-02 under-reached-skill instrument (Phase 33 baselines per-skill pick rates) — see `./router-pick-emitter.md` for the synchronous Node snippet, the 7-field no-PII payload (context_hash only — never the raw prompt), and the opaque-extras routing through `appendChainEvent`.
+
 ## Non-Goals
 
 The router does not: (a) make a model call, (b) write files, (c) enforce budget caps (that's the hook's job), (d) learn from history (Phase 11 reflector territory per D-07).