@hegemonart/get-design-done 1.59.6 → 1.59.8

package/sdk/state/lockfile.ts

@@ -99,7 +99,25 @@ export async function acquire(
 
       const parsed: LockPayload | null = parseLock(existing);
       if (parsed !== null && isStale(parsed, staleMs)) {
-        // Clear stale lock and retry.
+        // Audit D3 (TOCTOU): two waiters could each observe the same stale
+        // lock and both unlink+recreate, or one could unlink a DIFFERENT,
+        // freshly-acquired lock that replaced the stale one in the read→unlink
+        // window. Guard by confirming the on-disk bytes STILL match the exact
+        // stale payload we observed immediately before unlinking; if they
+        // changed (a new holder wrote a fresh lock), abandon the clear and
+        // loop — the next iteration re-reads and re-evaluates the new holder.
+        const confirm: string | null = readLockSafe(lockPath);
+        if (confirm === null) {
+          // Already gone — someone cleared it first. Retry immediately to
+          // race for the wx-create.
+          continue;
+        }
+        if (confirm !== existing) {
+          // A different writer replaced the lock between our read and now.
+          // Do NOT unlink — that would steal a (potentially fresh) lock.
+          await sleep(pollMs);
+          continue;
+        }
         try {
           unlinkSync(lockPath);
         } catch (delErr) {
@@ -108,6 +126,9 @@ export async function acquire(
             // Someone else cleared it first; fall through to retry.
           }
         }
+        // The wx-create on the next iteration is itself atomic (O_CREAT|O_EXCL),
+        // so even if two waiters both reach the unlink, only ONE wins the
+        // recreate; the loser sees EEXIST and re-evaluates.
         continue;
       }
 
@@ -181,13 +202,31 @@ function parseLock(raw: string): LockPayload | null {
 }
 
 function isStale(payload: LockPayload, staleMs: number): boolean {
-  // 1) PID check — if the process is dead, the lock is stale.
-  if (!isPidAlive(payload.pid, payload.host)) return true;
-  // 2) Age check — acquired_at older than staleMs is stale even if the
-  //    PID is reused by something else.
-  const acquiredAt = Date.parse(payload.acquired_at);
-  if (!Number.isFinite(acquiredAt)) return true; // garbage timestamp
-  return Date.now() - acquiredAt > staleMs;
+  // Audit D3: PID-liveness is AUTHORITATIVE. A lock whose holder PID is still
+  // alive on this host is NEVER stale, regardless of age — a legitimate
+  // long-running mutation (e.g. a >60s transaction) must not have its lock
+  // stolen out from under it. The age-based fallback only applies when we
+  // CANNOT confirm liveness: a dead PID, a missing/invalid pid field, a
+  // cross-host holder, or an unsignalable PID.
+  //
+  // Note: `isPidAlive` already returns true for the conservative
+  // can't-introspect cases (different host, EPERM). For those, the holder is
+  // treated as alive and the lock is held until released — we do NOT fall
+  // through to age-staleness, because doing so reintroduces the steal. Stale
+  // reclamation for genuinely-abandoned cross-host/unsignalable locks is left
+  // to manual cleanup, which is strictly safer than racing a live writer.
+  const pidRecorded =
+    typeof payload.pid === 'number' && Number.isInteger(payload.pid) && payload.pid > 0;
+  if (!pidRecorded) {
+    // No usable pid → cannot prove liveness. Fall back to age-staleness.
+    const acquiredAt = Date.parse(payload.acquired_at);
+    if (!Number.isFinite(acquiredAt)) return true; // garbage timestamp
+    return Date.now() - acquiredAt > staleMs;
+  }
+  // A recorded, live PID is decisive: NOT stale at any age.
+  if (isPidAlive(payload.pid, payload.host)) return false;
+  // PID is recorded but confirmed dead (ESRCH on this host) → stale.
+  return true;
 }
 
 /**

package/skills/bandit-reset/SKILL.md

@@ -31,6 +31,8 @@ No posterior file found at `.design/telemetry/posterior.json` — nothing to res
 The next bandit pull with `adaptive_mode: full` will bootstrap a fresh posterior from informed priors. See `reference/bandit-integration.md`.
 ```
 
+> Note: the posterior only learns (updates from outcomes) on the SDK / headless `session-runner` path. In interactive Claude Code with `adaptive_mode: full`, the bandit samples from the configured priors but does not currently update them in-session. A reset therefore re-bootstraps the priors the SDK path will subsequently learn from. See `reference/bandit-integration.md` ("Where adaptive routing actually learns").
+
 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

package/skills/bandit-status/SKILL.md

@@ -33,10 +33,13 @@ 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 `/gdd:bandit-reset`.
+- You are running in interactive Claude Code: the posterior is updated (learns) only on the SDK / headless `session-runner` path. In interactive `adaptive_mode: full` the bandit samples from configured priors but does not learn from in-session outcomes.
 
-See `reference/bandit-integration.md` for setup guidance.
+See `reference/bandit-integration.md` ("Where adaptive routing actually learns") for setup guidance.
 ```
 
+> Note: the posterior only moves (learns) on the SDK / headless `session-runner` path. In interactive Claude Code with `adaptive_mode: full`, the bandit samples from the configured priors but does not currently update them in-session. See `reference/bandit-integration.md`.
+
 Skip to Section 4 (Record). Parse failure (truncated/corrupted) → emit `Posterior file exists but is unparseable. Run /gdd:bandit-reset to start fresh, or restore from a backup.`
 
 ### 2. Parse the posterior

package/skills/darkmode/SKILL.md

@@ -29,7 +29,7 @@ Output artifact prefix `DARKMODE-AUDIT` is distinct from the pipeline namespace
 
 ## Pre-Flight
 
-Confirm source root exists. Try in order: `src/` (preferred), `app/` (Next.js App Router), `lib/` (libraries), `pages/` (Next.js Pages Router). Set `SRC_ROOT` to the first that exists. If none exist, abort: `"No source directory detected. Run /get-design-done scan first."`
+Confirm source root exists. Try in order: `src/` (preferred), `app/` (Next.js App Router), `lib/` (libraries), `pages/` (Next.js Pages Router). Set `SRC_ROOT` to the first that exists. If none exist, abort: `"No source directory detected. Run /get-design-done explore first."`
 
 Confirm `.design/` exists (create if absent: `mkdir -p .design/`).
 

package/skills/graphify/SKILL.md

@@ -5,7 +5,7 @@ description: "Manage the Graphify knowledge graph for the current project. Build
 
 # gdd-graphify
 
-Thin command wrapper around the GSD graphify tools integration.
+Thin command wrapper around the get-design-done (GDD) graphify tools integration.
 
 ## Usage
 
@@ -30,10 +30,10 @@ Thin command wrapper around the GSD graphify tools integration.
    ```
    STOP.
 4. Execute the requested subcommand via the native CLI:
-   - build:  `node bin/gdd-graph build`
-   - query:  `node bin/gdd-graph query "<term>" --budget 2000`
-   - status: `node bin/gdd-graph status`
-   - diff:   `node bin/gdd-graph diff`
+   - build:  `node "${CLAUDE_PLUGIN_ROOT}/bin/gdd-graph" build`
+   - query:  `node "${CLAUDE_PLUGIN_ROOT}/bin/gdd-graph" query "<term>" --budget 2000`
+   - status: `node "${CLAUDE_PLUGIN_ROOT}/bin/gdd-graph" status`
+   - diff:   `node "${CLAUDE_PLUGIN_ROOT}/bin/gdd-graph" diff`
 5. After `build` completes, update `.design/STATE.md` `<connections>`: `graphify: available`
 
 ## Required Reading
@@ -43,7 +43,7 @@ Thin command wrapper around the GSD graphify tools integration.
 
 ## Notes
 
-- Graphify is optional. The native CLI ships in this repo at `bin/gdd-graph` (no external install - Node only).
+- Graphify is optional. The native CLI ships with the plugin at `${CLAUDE_PLUGIN_ROOT}/bin/gdd-graph` (no external install - Node only).
 - Graph is stored at `.design/graph/graph.json` (Ajv-validated against `scripts/lib/graph/schema.json`).
 - Graph covers source code (`src/`, `components/`). It does NOT index `.design/` artifacts by default.
 - Use `query` with node IDs from the graph schema: `component:<name>`, `token:color/<name>`, `decision:D-<nn>`, etc.

package/skills/quick/SKILL.md

@@ -26,10 +26,12 @@ Fast pipeline run. Skips optional-quality agents for speed while keeping the cor
    - Optional stage name (defaults to full pipeline from the current STATE.md position).
    - `--skip <agent-name>` (repeatable) adds to the skip list.
 2. Read `.design/STATE.md` to determine entry stage if none was passed.
-3. For each stage to execute, spawn the stage skill with a `quick_mode: true` flag and the effective skip list in the spawn context. Stage skills read this flag and route around the listed agents.
+3. For each stage to execute, invoke the stage skill but spawn it with the optional agents in the effective skip list **omitted from the spawn graph** - this skill is the orchestrator, so it simply does not call those agents (the stage skills do not read a `quick_mode` flag; the skipping happens here, by not spawning them). The kept agents run exactly as in the full pipeline.
 4. After each stage, print: "Stage <name> done. Skipped: <list>."
 5. Final summary prints which agents were skipped across the full run.
 
+Mechanism note: `/gdd:quick` is a lighter-touch *invocation* of the normal stages, not a special stage mode. It reduces ceremony by leaving the listed optional-quality agents out of the spawn graph it orchestrates. There is no flag the stage skills parse - if invoked directly (not via this skill) the stages run their full agent set.
+
 ## Use When
 
 - You trust the problem scope (no need for fresh research).

package/skills/reflect/SKILL.md

@@ -37,7 +37,7 @@ Run `design-reflector` on demand against the current (or specified) cycle. Produ
    See @skills/reflect/procedures/capability-gap-scan.md for the full procedure.
    The `design-reflector` agent runs the scan automatically as part of its reflection pass; this step lets users dry-run it independently with:
    ```
-   node scripts/lib/reflector/capability-gap-scan.cjs --dry-run
+   node "${CLAUDE_PLUGIN_ROOT}/scripts/lib/reflector/capability-gap-scan.cjs" --dry-run
    ```
    The scan emits `capability_gap` events (`source: "reflector_pattern"`) for recurring patterns lacking a dedicated executable owner; Plan 29-03 aggregates these for `/gdd:apply-reflections`.
 

package/skills/router/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-router
-description: "Routes a /gdd command to fast|quick|full path + S|M|L|XL complexity_class and returns {path, complexity_class, model_tier_overrides, resolved_models, estimated_cost_usd, cache_hits}. Deterministic - no model call. Invoked once at command entry before any Agent spawn. Read by hooks/budget-enforcer.ts."
+description: "Routes a /gdd command to fast|quick|full path + S|M|L|XL complexity_class and returns {path, complexity_class, model_tier_overrides, resolved_models, estimated_cost_usd, cache_hits}. A SKILL.md prompt the model executes to emit a routing-decision JSON from rule tables (no separate agent spawn). Optional/advisory - invoked only by the skills that opt into routing; the budget-enforcer hook tolerates its absence. Read by hooks/budget-enforcer.ts."
 argument-hint: "<intent-string> [<target-artifacts-csv>]"
 tools: Read, Bash, Grep
 ---
@@ -69,7 +69,9 @@ Delegate to `skills/cache-manager/SKILL.md` (Plan 10.1-02). The router lists can
 
 ## Integration Point
 
-Every `/gdd:*` SKILL.md's first substantive step is: spawn the router via `Task` or inline invocation; receive the JSON blob; pass it to downstream agents as context so the budget-enforcer hook has the router decision available in tool_input metadata when the first Agent spawn fires.
+The router is **optional and advisory**, not a universal first step. Only the handful of skills that explicitly opt into routing reference it (today: the root pipeline `SKILL.md` / `/gdd:handoff`, and `/gdd:style` documents that it deliberately does *not* invoke the router because it is a leaf invocation). The pipeline stage skills (explore / plan / design / verify) do **not** spawn the router. When a skill does invoke it, the flow is: invoke the router via `Task` or inline invocation; receive the JSON blob; pass it to downstream agents as context so the budget-enforcer hook has the router decision available in tool_input metadata when the first Agent spawn fires.
+
+When no skill supplies a router decision, the budget-enforcer hook reads `tool_input.context.router_decision` as absent and falls back to its legacy back-compat path - the router's absence is tolerated by design, never an error.
 
 ## Failure Modes