@hegemonart/get-design-done 1.31.0 → 1.32.0

package/scripts/lib/health-mirror/index.cjs

@@ -8,13 +8,14 @@
 // Surface:
 //   async getHealthChecks(rootDir) → { checks: HealthCheck[] }
 //
-// The 6 checks (in stable order) are:
+// The 7 checks (in stable order) are:
 //   1. claude_md            — CLAUDE.md presence
 //   2. planning_dir         — .planning/ presence
 //   3. design_dir           — .design/ presence
 //   4. package_json         — package.json present AND parseable
 //   5. issue_reporter       — kill-switch state (Plan 30-06 / D-08)
 //   6. figma_extract        — extract readiness + Free-tier signal (Plan 31-09)
+//   7. skill_discipline     — using-gdd bootstrap + SessionStart inject (Plan 32-07)
 //
 // Check 5 was added in Plan 30-06 — surfaces the report-issue kill-switch
 // (env or config disable) so users can verify why the command is
@@ -34,6 +35,17 @@
 // logged, or placed in the detail. The Free-tier state is derived from a LOCAL
 // signal only (a prior pull's _meta.json recording a 403/skip on the Variables
 // endpoint) — never a live network call (health-mirror is pure read-only).
+//
+// Check 7 was added in Plan 32-07 — surfaces whether the skill-discipline
+// bootstrap (Phase 32) is live so a user can confirm the using-gdd SessionStart
+// inject is wired. The detail line is one of three exact strings:
+//   - "skill-discipline: ready"            (using-gdd present AND hooks.json
+//                                           SessionStart wires inject-using-gdd.sh)
+//   - "skill-discipline: missing using-gdd" (skills/using-gdd/SKILL.md absent)
+//   - "skill-discipline: hook not wired"    (skill present but no SessionStart
+//                                           inject-using-gdd entry)
+// status: 'ok' when ready, 'warn' otherwise. PURE read-only (rootDir-relative
+// file + JSON inspection only) — NEVER throws, NEVER networks.
 
 const fs = require('node:fs');
 const path = require('node:path');
@@ -174,9 +186,75 @@ async function getHealthChecks(rootDir) {
     checks.push({ name: 'figma_extract', status, detail });
   }
 
+  // 7. skill_discipline — using-gdd bootstrap + SessionStart inject (Plan 32-07).
+  // Reports exactly one of three states. PURE read-only: file existence +
+  // hooks.json JSON inspection only. NEVER throws, NEVER networks (every read
+  // is wrapped defensively like the figma_extract check above).
+  {
+    const skillPresent = fileExists(
+      path.join(rootDir, 'skills', 'using-gdd', 'SKILL.md')
+    );
+    const hookWired = skillPresent && sessionStartWiresInject(rootDir);
+
+    let detail;
+    let status;
+    if (!skillPresent) {
+      detail = 'skill-discipline: missing using-gdd';
+      status = 'warn';
+    } else if (!hookWired) {
+      detail = 'skill-discipline: hook not wired';
+      status = 'warn';
+    } else {
+      detail = 'skill-discipline: ready';
+      status = 'ok';
+    }
+    checks.push({ name: 'skill_discipline', status, detail });
+  }
+
   return { checks };
 }
 
+/**
+ * Does hooks/hooks.json wire the inject-using-gdd SessionStart entry?
+ * PURE read-only JSON inspection. Defensive: a missing/garbage hooks.json or an
+ * unexpected shape returns false (→ "hook not wired") rather than throwing — the
+ * health probe must never crash on this check. NEVER networks.
+ *
+ * @param {string} rootDir project root passed to getHealthChecks
+ * @returns {boolean} true iff a SessionStart hook command references inject-using-gdd
+ */
+function sessionStartWiresInject(rootDir) {
+  try {
+    const p = path.join(rootDir, 'hooks', 'hooks.json');
+    let hooks;
+    try {
+      hooks = JSON.parse(fs.readFileSync(p, 'utf8'));
+    } catch {
+      return false; // missing/garbage hooks.json → not wired
+    }
+    const sessionStart =
+      hooks && hooks.hooks && Array.isArray(hooks.hooks.SessionStart)
+        ? hooks.hooks.SessionStart
+        : [];
+    for (const entry of sessionStart) {
+      const inner = entry && Array.isArray(entry.hooks) ? entry.hooks : [];
+      for (const h of inner) {
+        if (
+          h &&
+          typeof h.command === 'string' &&
+          /inject-using-gdd/.test(h.command)
+        ) {
+          return true;
+        }
+      }
+    }
+    return false;
+  } catch {
+    // Absolute safety net — never crash the health probe on this check.
+    return false;
+  }
+}
+
 /**
  * Free-tier signal (LOCAL only — never a network call). The raw-pull stage
  * (scripts/lib/figma-extract/pull.cjs) writes a _meta.json per file key under

package/scripts/lib/iteration-budget.cjs

@@ -1,205 +1,29 @@
-// scripts/lib/iteration-budget.cjs
-//
-// Plan 20-14 — bounded fix-loop iteration budget.
+'use strict';
+// scripts/lib/iteration-budget.cjs — GDD-DEPRECATION-SHIM (Plan 31-5-06, SDK-05, D-02).
 //
-// Stops infinite fix cycles from burning unbounded context. Every fix-
-// iteration consumes 1 unit; Layer-B cache hits refund 1 unit so
-// cached answers don't count against the ceiling. When the budget
-// reaches 0, consume() throws and the caller must surface to user.
+// Thin deprecation shim. The real implementation moved to
+// sdk/primitives/iteration-budget.cjs in Plan 31-5-04 (SDK consolidation).
+// This file is re-created at the OLD path so undocumented EXTERNAL importers
+// (anyone who reached into node_modules/@hegemonart/get-design-done/scripts/
+// lib/iteration-budget.cjs directly) keep working for one minor grace window.
 //
-// State file: `.design/iteration-budget.json`. All mutations go through
-// `scripts/lib/lockfile.cjs` with atomic temp+rename writes so
-// concurrent callers (hook + fix-loop + verify) don't clobber each
-// other. The lock scope is the state file itself, so refund + consume
-// from different children serialize correctly.
+// REMOVED IN v1.33.0 (D-02). Grace window: 1.31.5 ships with shims →
+// 1.32.0 still has them → 1.33.0 removes them. Internal callers already use
+// the sdk/ path (Plan 31-5-04/05) — this shim is external-only and 31-5-10's
+// no-stale-internal-refs guard excludes files carrying the GDD-DEPRECATION-SHIM
+// marker above.
 //
-// Shape on disk matches reference/schemas/iteration-budget.schema.json:
-//   { budget, remaining, consumed, refunded, updatedAt }
-
-'use strict';
-
-const fs = require('node:fs');
-const path = require('node:path');
-
-const { acquire, renameWithRetry } = require('./lockfile.cjs');
-
-const STATE_PATH_REL = path.join('.design', 'iteration-budget.json');
-const DEFAULT_BUDGET = 50;
-const LOCK_MAX_WAIT_MS = 5_000;
-
-/** Error thrown by `consume()` when the remaining budget would go below 0. */
-class IterationBudgetExhaustedError extends Error {
-  constructor(amount, state) {
-    super(
-      `IterationBudgetExhausted: cannot consume ${amount} — remaining=${state.remaining}, budget=${state.budget}, consumed=${state.consumed}. Caller must surface to user (fix-loop has stopped converging).`,
-    );
-    this.name = 'IterationBudgetExhaustedError';
-    this.amount = amount;
-    this.state = state;
-  }
-}
-
-function stateAbsPath() {
-  return path.join(process.cwd(), STATE_PATH_REL);
-}
-
-/** Read and validate the state file. Returns null on missing/corrupt. */
-function readStateSync() {
-  const p = stateAbsPath();
-  if (!fs.existsSync(p)) return null;
-  try {
-    const raw = fs.readFileSync(p, 'utf8');
-    const parsed = JSON.parse(raw);
-    if (
-      parsed &&
-      typeof parsed === 'object' &&
-      Number.isInteger(parsed.budget) && parsed.budget >= 0 &&
-      Number.isInteger(parsed.remaining) && parsed.remaining >= 0 &&
-      Number.isInteger(parsed.consumed) && parsed.consumed >= 0 &&
-      Number.isInteger(parsed.refunded) && parsed.refunded >= 0 &&
-      typeof parsed.updatedAt === 'string'
-    ) {
-      return parsed;
-    }
-    return null;
-  } catch {
-    return null;
-  }
-}
-
-/** Atomically write state under a file-lock. */
-async function writeStateAtomic(state) {
-  const p = stateAbsPath();
-  const dir = path.dirname(p);
-  fs.mkdirSync(dir, { recursive: true });
-  const release = await acquire(p, { maxWaitMs: LOCK_MAX_WAIT_MS });
-  try {
-    // Re-read inside the lock so we merge against the very latest
-    // on-disk state, not the value the caller observed pre-lock. This
-    // is what makes concurrent consume() from 10 children add up to
-    // consumed=10 rather than racing each other.
-    const latest = readStateSync();
-    const merged = state.mergeFn ? state.mergeFn(latest || state.seed) : state.seed;
-    const tmp = `${p}.tmp.${process.pid}.${Date.now()}`;
-    fs.writeFileSync(tmp, JSON.stringify(merged, null, 2) + '\n', 'utf8');
-    await renameWithRetry(tmp, p);
-    return merged;
-  } finally {
-    await release();
-  }
-}
-
-/**
- * Initialize or restart the iteration budget.
- *
- * @param {number} [budget] default 50
- * @returns {Promise<{budget, remaining, consumed, refunded, updatedAt}>}
- */
-async function reset(budget = DEFAULT_BUDGET) {
-  if (!Number.isFinite(budget) || budget < 0) {
-    throw new Error(`iteration-budget.reset: budget must be a non-negative finite number, got ${budget}`);
-  }
-  const b = Math.floor(budget);
-  const state = {
-    budget: b,
-    remaining: b,
-    consumed: 0,
-    refunded: 0,
-    updatedAt: new Date().toISOString(),
-  };
-  return writeStateAtomic({ seed: state, mergeFn: () => state });
-}
-
-/**
- * Consume N units from the remaining budget. Throws
- * IterationBudgetExhaustedError when N would send remaining below zero.
- *
- * @param {number} [amount] default 1
- * @returns {Promise<{budget, remaining, consumed, refunded, updatedAt}>}
- *   the new on-disk state after consumption.
- */
-async function consume(amount = 1) {
-  const n = normalizeAmount(amount);
-  // Seed for the case when no state exists yet: auto-init to default budget.
-  const seed = defaultState();
-  return writeStateAtomic({
-    seed,
-    mergeFn: (current) => {
-      const base = current || seed;
-      const nextRemaining = base.remaining - n;
-      if (nextRemaining < 0) {
-        // Throw without writing — atomic: either consume fully or not at all.
-        throw new IterationBudgetExhaustedError(n, base);
-      }
-      return {
-        budget: base.budget,
-        remaining: nextRemaining,
-        consumed: base.consumed + n,
-        refunded: base.refunded,
-        updatedAt: new Date().toISOString(),
-      };
-    },
-  });
-}
-
-/**
- * Refund N units to the remaining budget, capped at `budget`.
- *
- * @param {number} [amount] default 1
- * @returns {Promise<{budget, remaining, consumed, refunded, updatedAt}>}
- */
-async function refund(amount = 1) {
-  const n = normalizeAmount(amount);
-  const seed = defaultState();
-  return writeStateAtomic({
-    seed,
-    mergeFn: (current) => {
-      const base = current || seed;
-      const nextRemaining = Math.min(base.budget, base.remaining + n);
-      // Only count the portion that actually landed — if we were already
-      // at budget, the refund is a no-op.
-      const actuallyRefunded = nextRemaining - base.remaining;
-      return {
-        budget: base.budget,
-        remaining: nextRemaining,
-        consumed: base.consumed,
-        refunded: base.refunded + actuallyRefunded,
-        updatedAt: new Date().toISOString(),
-      };
-    },
-  });
-}
-
-/**
- * Return the current on-disk state. Reads without the lock — callers
- * using this for UI display only see a best-effort snapshot; mutating
- * paths (consume/refund) always re-read inside the lock.
- */
-function remaining() {
-  return readStateSync() || defaultState();
-}
-
-function normalizeAmount(amount) {
-  if (!Number.isFinite(amount) || amount <= 0) {
-    throw new Error(`iteration-budget: amount must be a positive finite number, got ${amount}`);
-  }
-  return Math.floor(amount);
-}
+// Emits a DeprecationWarning exactly ONCE per process: the module-level
+// `warned` flag plus Node's module cache (this file is evaluated once per
+// process regardless of how many times it is required).
 
-function defaultState() {
-  return {
-    budget: DEFAULT_BUDGET,
-    remaining: DEFAULT_BUDGET,
-    consumed: 0,
-    refunded: 0,
-    updatedAt: new Date().toISOString(),
-  };
+let warned = false;
+if (!warned) {
+  warned = true;
+  process.emitWarning(
+    'scripts/lib/iteration-budget.cjs is deprecated; import sdk/primitives/iteration-budget instead. Removed in v1.33.0.',
+    'DeprecationWarning',
+  );
 }
 
-module.exports = {
-  consume,
-  refund,
-  remaining,
-  reset,
-  IterationBudgetExhaustedError,
-};
+module.exports = require('../../sdk/primitives/iteration-budget.cjs');

package/scripts/lib/jittered-backoff.cjs

@@ -1,112 +1,29 @@
-// scripts/lib/jittered-backoff.cjs
-//
-// Plan 20-14 — jittered exponential backoff primitive.
-//
-// Replaces fixed-interval retry sleeps across the codebase (update-check,
-// watch-authorities, figma probes, connection probes, hook retry loops) with
-// a deterministic, capped, jittered backoff curve.
-//
-// Formula:
-//   base = min(maxMs, baseMs * factor^attempt)
-//   delay = base * (1 + rand(-jitter, +jitter))
-//   clamp to [0, maxMs * (1 + jitter)]
-//
-// The zero-based `attempt` counter gives `baseMs` on the first call, then
-// multiplies by `factor` per attempt up to the cap. Jitter is full-width
-// symmetric (not AWS-style equal/decorrelated) because our consumers are
-// single-threaded retry loops — there's no thundering-herd problem to
-// smooth; the jitter is cosmetic protection against synchronized retries
-// between siblings like the watcher + update-check running at the same
-// session boundary.
+'use strict';
+// scripts/lib/jittered-backoff.cjs — GDD-DEPRECATION-SHIM (Plan 31-5-06, SDK-05, D-02).
 //
-// Defaults (baseMs=100, maxMs=30_000, factor=2, jitter=0.2) yield:
-//   attempt 0 → 80-120ms
-//   attempt 1 → 160-240ms
-//   attempt 2 → 320-480ms
-//   ...
-//   attempt 9 → ~24s-30s (capped)
+// Thin deprecation shim. The real implementation moved to
+// sdk/primitives/jittered-backoff.cjs in Plan 31-5-04 (SDK consolidation).
+// This file is re-created at the OLD path so undocumented EXTERNAL importers
+// (anyone who reached into node_modules/@hegemonart/get-design-done/scripts/
+// lib/jittered-backoff.cjs directly) keep working for one minor grace window.
 //
-// This module is `.cjs` (not `.ts`) per Plan 20-14 D-01 so it can be
-// `require()`d from both the `.ts` runtime (hooks, MCP server) and future
-// `.cjs` CLI invocations without needing `--experimental-strip-types` at
-// every consumer site. Types live in the paired `jittered-backoff.d.cts`.
+// REMOVED IN v1.33.0 (D-02). Grace window: 1.31.5 ships with shims →
+// 1.32.0 still has them → 1.33.0 removes them. Internal callers already use
+// the sdk/ path (Plan 31-5-04/05) — this shim is external-only and 31-5-10's
+// no-stale-internal-refs guard excludes files carrying the GDD-DEPRECATION-SHIM
+// marker above.
 //
-// No external dependencies; pure Math.random + setTimeout.
-
-'use strict';
-
-/**
- * Default backoff parameters — chosen to cover retry-after-Xms through
- * retry-after-30s with reasonable mid-range distribution.
- */
-const DEFAULTS = Object.freeze({
-  baseMs: 100,
-  maxMs: 30_000,
-  factor: 2,
-  jitter: 0.2,
-});
-
-/**
- * Compute the jittered delay in milliseconds for a given attempt number.
- *
- * @param {number} attempt zero-based attempt counter (0 = first retry)
- * @param {object} [opts]
- * @param {number} [opts.baseMs]  initial delay before any jitter. Default 100.
- * @param {number} [opts.maxMs]   maximum un-jittered base. Default 30_000.
- * @param {number} [opts.factor]  per-attempt multiplier. Default 2.
- * @param {number} [opts.jitter]  symmetric jitter fraction in [0, 1). Default 0.2.
- * @returns {number} delay in ms. Never negative. May exceed `maxMs` by up
- *   to `jitter * maxMs` on the high side.
- *
- * Invariants:
- *  - `delayMs(n, opts) >= 0` for every non-negative `n`.
- *  - `delayMs(n, opts) <= maxMs * (1 + jitter)` for every non-negative `n`.
- *  - The distribution has nonzero stddev whenever `jitter > 0`.
- */
-function delayMs(attempt, opts) {
-  const baseMs = (opts && Number.isFinite(opts.baseMs)) ? opts.baseMs : DEFAULTS.baseMs;
-  const maxMs = (opts && Number.isFinite(opts.maxMs)) ? opts.maxMs : DEFAULTS.maxMs;
-  const factor = (opts && Number.isFinite(opts.factor)) ? opts.factor : DEFAULTS.factor;
-  const jitter = (opts && Number.isFinite(opts.jitter)) ? opts.jitter : DEFAULTS.jitter;
-
-  // Guard against nonsense inputs — callers that pass garbage shouldn't
-  // cause NaN or Infinity to propagate into setTimeout.
-  const a = Math.max(0, Number.isFinite(attempt) ? Math.floor(attempt) : 0);
-  const safeBase = Math.max(0, baseMs);
-  const safeMax = Math.max(safeBase, maxMs);
-  const safeFactor = factor > 0 ? factor : DEFAULTS.factor;
-  // Clamp jitter to [0, 1) — full-range (>=1) would allow negative values
-  // after subtraction, which we want to forbid by invariant.
-  const safeJitter = Math.min(0.999, Math.max(0, jitter));
-
-  // Exponential growth capped at safeMax.
-  // Math.pow with a huge attempt count can overflow to Infinity; the
-  // Math.min picks up safeMax before Infinity escapes.
-  const unjittered = Math.min(safeMax, safeBase * Math.pow(safeFactor, a));
-
-  // Symmetric jitter in [-jitter, +jitter).
-  // Math.random() returns [0, 1); 2r - 1 maps to [-1, 1); scale by jitter.
-  const noise = (Math.random() * 2 - 1) * safeJitter;
-  const delay = unjittered * (1 + noise);
-
-  // Floor at zero (noise could in theory go slightly negative due to FP
-  // precision even with safeJitter < 1, for very small unjittered values).
-  return Math.max(0, delay);
-}
-
-/**
- * Sleep for a jittered backoff interval. Convenience wrapper around
- * `delayMs` + `setTimeout`.
- *
- * @param {number} attempt zero-based attempt counter
- * @param {object} [opts] see {@link delayMs}
- * @returns {Promise<number>} resolves to the actual delay that was applied
- */
-function sleep(attempt, opts) {
-  const ms = delayMs(attempt, opts);
-  return new Promise((resolve) => {
-    setTimeout(() => resolve(ms), ms);
-  });
+// Emits a DeprecationWarning exactly ONCE per process: the module-level
+// `warned` flag plus Node's module cache (this file is evaluated once per
+// process regardless of how many times it is required).
+
+let warned = false;
+if (!warned) {
+  warned = true;
+  process.emitWarning(
+    'scripts/lib/jittered-backoff.cjs is deprecated; import sdk/primitives/jittered-backoff instead. Removed in v1.33.0.',
+    'DeprecationWarning',
+  );
 }
 
-module.exports = { delayMs, sleep, DEFAULTS };
+module.exports = require('../../sdk/primitives/jittered-backoff.cjs');