@hegemonart/get-design-done 1.27.1 → 1.27.6

package/hooks/budget-enforcer.ts

@@ -105,6 +105,76 @@ interface RuntimeDetectModule {
 }
 const runtimeDetect = nodeRequire('../scripts/lib/runtime-detect.cjs') as RuntimeDetectModule;
 
+// Plan 27.5-01: bandit production-integration shim. Hides pull /
+// pullWithDelegate choice from the hook; reads adaptive_mode + frontmatter
+// tier_override under the same gating discipline as Phase 23.5 D-07 and
+// Phase 27.5 D-05.
+interface BanditIntegrationModule {
+  consultBandit(args: {
+    agent: string;
+    bin: string;
+    delegate: string;
+    agentFrontmatter: { tier_override?: string; default_tier?: string };
+    adaptiveMode?: 'static' | 'hedge' | 'full';
+    baseDir?: string;
+    posteriorPath?: string;
+  }): {
+    tier: 'haiku' | 'sonnet' | 'opus';
+    decision_log: {
+      source:
+        | 'frontmatter'
+        | 'tier_override_bypass'
+        | 'bandit_pull'
+        | 'bandit_pull_with_delegate';
+      samples?: Record<string, number> | Record<string, Record<string, number>>;
+      delegate?: string;
+      adaptive_mode: 'static' | 'hedge' | 'full';
+      reason?: string;
+    };
+  };
+  recordOutcome(args: unknown): void;
+  DELEGATE_NONE: 'none';
+}
+const banditIntegration = nodeRequire(
+  '../scripts/lib/bandit-router/integration.cjs',
+) as BanditIntegrationModule;
+
+// Plan 27.5-02: adaptive-mode module surfaces the single gating predicate.
+interface AdaptiveModeModule {
+  getMode(opts?: {
+    baseDir?: string;
+    budgetPath?: string;
+    quiet?: boolean;
+  }): 'static' | 'hedge' | 'full';
+  isBanditEnabled(opts?: { baseDir?: string; budgetPath?: string }): boolean;
+}
+const adaptiveMode = nodeRequire(
+  '../scripts/lib/adaptive-mode.cjs',
+) as AdaptiveModeModule;
+
+// Plan 27.5-02: bin selection helper for bandit (agent, bin) addressing.
+// budget-enforcer doesn't currently surface glob_count; default to 'medium'
+// as a safe per-agent partition until a future plan wires the real count.
+interface BanditRouterCoreModule {
+  binForGlobCount(n: number): 'tiny' | 'small' | 'medium' | 'large';
+  DEFAULT_DELEGATES: readonly string[];
+}
+const banditRouterCore = nodeRequire(
+  '../scripts/lib/bandit-router.cjs',
+) as BanditRouterCoreModule;
+
+// Plan 27.5-02: tier-resolver translates bandit tier → concrete model.
+interface TierResolverModule {
+  resolve(
+    runtime: string,
+    tier: string,
+    opts?: { silent?: boolean },
+  ): string | null;
+}
+const tierResolver = nodeRequire(
+  '../scripts/lib/tier-resolver.cjs',
+) as TierResolverModule;
+
 // ── Types ───────────────────────────────────────────────────────────────────
 
 /**
@@ -618,6 +688,50 @@ function emitCostRecorded(
   }
 }
 
+/**
+ * Plan 27.5-02 / D-03: emit `bandit.tier_selected` event when the bandit
+ * is consulted (regardless of whether it overrode the prior tier). The
+ * event captures the prior tier, the bandit's pick, the sampled posterior
+ * (when applicable), the delegate dimension, and the runtime tag so
+ * Phase 11 reflector (27.5-04) and `/gdd:bandit-status` (27.5-05) can
+ * reconstruct decision history without re-reading the posterior file.
+ *
+ * Fail-open like every other emit in this hook.
+ */
+function emitBanditTierSelected(
+  payload: {
+    agent: string;
+    bin: string;
+    prior_tier: string;
+    selected_tier: 'haiku' | 'sonnet' | 'opus';
+    source:
+      | 'frontmatter'
+      | 'tier_override_bypass'
+      | 'bandit_pull'
+      | 'bandit_pull_with_delegate';
+    delegate: string;
+    adaptive_mode: 'static' | 'hedge' | 'full';
+    samples?: unknown;
+    runtime: string;
+    model_id: string | null;
+    reason?: string;
+  },
+  cycle?: string,
+): void {
+  const ev = {
+    type: 'bandit.tier_selected',
+    timestamp: new Date().toISOString(),
+    sessionId: getSessionId(),
+    ...(cycle !== undefined && cycle !== 'unknown' ? { cycle } : {}),
+    payload,
+  };
+  try {
+    appendEvent(ev as unknown as HookFiredEvent);
+  } catch {
+    // Fail open.
+  }
+}
+
 // ── main ────────────────────────────────────────────────────────────────────
 
 async function readStdin(): Promise<string> {
@@ -905,12 +1019,142 @@ export async function main(): Promise<void> {
       ? routerDecision.runtime
       : runtimeDetect.detect()) ?? 'claude';
 
+  // ── Plan 27.5-02 — bandit consultation ────────────────────────────────────
+  //
+  // D-01 / D-02 / D-03 / D-07: per-spawn after `resolved_models` is computed,
+  // before the SDK call. Skip conditions (all silent — no event, no override):
+  //   - adaptive_mode !== 'full' (D-07)
+  //   - toolInput._tier_downgraded === true (80% downgrade fired upstream —
+  //     bandit must not undo budget)
+  //
+  // When bandit fires, override resolved_models[agent] through tier-resolver
+  // so downstream consumers see the bandit's pick as the actual model.
+  // model_tier_overrides[agent] is preserved (D-03 back-compat).
+  const currentMode = adaptiveMode.getMode({ quiet: true });
+  const priorTier = resolvedTier; // captured before bandit override
+  // Mutable references for the cost/telemetry path; bandit may rewrite.
+  let effectiveTier: string = resolvedTier;
+  let effectiveModelId: string | null = resolvedModelId;
+
+  if (currentMode === 'full' && toolInput._tier_downgraded !== true) {
+    // Bin defaults to 'medium' — budget-enforcer doesn't currently surface
+    // glob_count; future plan can wire it. Per-agent bandit arms still
+    // converge correctly under a fixed bin (Phase 23.5 D-08). The function
+    // call below makes the integration point explicit for future plans.
+    void banditRouterCore.binForGlobCount(0);
+    const bin = 'medium';
+
+    // Source the frontmatter view from the in-flight toolInput. The hook
+    // reads frontmatter indirectly: _default_tier carries the agent's
+    // declared default-tier, _tier_override (if any) carries an explicit
+    // override the router emitted. For bandit purposes, _tier_override
+    // means "operator has already taken control" — the shim returns
+    // source='tier_override_bypass' (no posterior side effect).
+    const agentFrontmatter: {
+      tier_override?: string;
+      default_tier?: string;
+    } = {};
+    if (
+      typeof toolInput._tier_override === 'string' &&
+      toolInput._tier_override.length > 0
+    ) {
+      agentFrontmatter.tier_override = toolInput._tier_override;
+    }
+    if (
+      typeof toolInput._default_tier === 'string' &&
+      toolInput._default_tier.length > 0
+    ) {
+      agentFrontmatter.default_tier = toolInput._default_tier;
+    }
+
+    // Delegate dimension: budget-enforcer doesn't currently see the
+    // agent's delegate_to: frontmatter (session-runner does). For 27.5-02
+    // we always consult the local-call slice (delegate='none'); 27.5-03
+    // wires delegate=<peer> for the recordOutcome side.
+    const banditDelegate = banditIntegration.DELEGATE_NONE;
+
+    let banditResult: ReturnType<
+      BanditIntegrationModule['consultBandit']
+    > | null = null;
+    try {
+      banditResult = banditIntegration.consultBandit({
+        agent,
+        bin,
+        delegate: banditDelegate,
+        agentFrontmatter,
+        adaptiveMode: currentMode,
+      });
+    } catch {
+      // Fail open — never let a bandit error block a spawn.
+    }
+
+    if (banditResult !== null) {
+      // Translate the bandit tier into a concrete model. The tier-resolver
+      // emits its own fallback events (tier_resolution_fallback /
+      // tier_resolution_failed) when the runtime row is incomplete, so we
+      // don't need to re-emit those here.
+      const banditModel = tierResolver.resolve(
+        runtimeId,
+        banditResult.tier,
+        { silent: true },
+      );
+
+      // Apply override only when:
+      //   1. bandit actually picked a different tier than priorTier
+      //      (no-op write avoided)
+      //   2. tier-resolver returned a non-null model (fall back to
+      //      existing resolvedModelId on null)
+      //   3. source is 'bandit_pull' or 'bandit_pull_with_delegate'
+      //      (frontmatter/bypass paths don't override resolved_models)
+      if (
+        banditResult.tier !== priorTier &&
+        banditModel !== null &&
+        (banditResult.decision_log.source === 'bandit_pull' ||
+          banditResult.decision_log.source === 'bandit_pull_with_delegate')
+      ) {
+        // Override resolved_models[agent] without touching
+        // model_tier_overrides[agent] (D-03 back-compat).
+        if (routerDecision !== undefined) {
+          const rm = routerDecision.resolved_models ?? {};
+          rm[agent] = banditModel;
+          routerDecision.resolved_models = rm;
+        }
+        // Also stamp _tier_override on toolInput so downstream readers
+        // see the bandit's pick.
+        toolInput._tier_override = banditResult.tier;
+        effectiveTier = banditResult.tier;
+        effectiveModelId = banditModel;
+      }
+
+      // Emit one bandit.tier_selected event regardless of override outcome
+      // (the event captures the decision, not the override side effect).
+      emitBanditTierSelected(
+        {
+          agent,
+          bin,
+          prior_tier: priorTier,
+          selected_tier: banditResult.tier,
+          source: banditResult.decision_log.source,
+          delegate: banditResult.decision_log.delegate ?? banditDelegate,
+          adaptive_mode: banditResult.decision_log.adaptive_mode,
+          samples: banditResult.decision_log.samples,
+          runtime: runtimeId,
+          model_id: effectiveModelId ?? resolvedModelId,
+          ...(banditResult.decision_log.reason !== undefined
+            ? { reason: banditResult.decision_log.reason }
+            : {}),
+        },
+        cycle,
+      );
+    }
+  }
+
   // Compute runtime-aware cost via the shared backend. Failures return
   // null cost; we emit the event regardless so the cost-aggregator sees
   // the lookup attempt (Phase 22 events.jsonl tagging).
   const costLookup = budgetBackend.computeCost({
-    model_id: resolvedModelId,
-    tier: resolvedTier,
+    model_id: effectiveModelId,
+    tier: effectiveTier,
     runtime: runtimeId,
     tokens_in: Number(toolInput._tokens_in_est ?? 0),
     tokens_out: Number(toolInput._tokens_out_est ?? 0),
@@ -920,8 +1164,8 @@ export async function main(): Promise<void> {
     {
       runtime: runtimeId,
       agent,
-      model_id: resolvedModelId ?? costLookup.model,
-      tier: costLookup.tier ?? resolvedTier,
+      model_id: effectiveModelId ?? costLookup.model,
+      tier: costLookup.tier ?? effectiveTier,
       tokens_in: Number(toolInput._tokens_in_est ?? 0),
       tokens_out: Number(toolInput._tokens_out_est ?? 0),
       cost_usd: costLookup.cost_usd,
@@ -932,7 +1176,7 @@ export async function main(): Promise<void> {
   // Branch E: standard spawn-allowed (includes tier-downgraded path).
   writeTelemetry({
     agent,
-    tier: resolvedTier,
+    tier: effectiveTier,
     tokens_in: Number(toolInput._tokens_in_est ?? 0),
     tokens_out: Number(toolInput._tokens_out_est ?? 0),
     cache_hit: false,

package/hooks/gdd-precompact-snapshot.js

@@ -0,0 +1,334 @@
+#!/usr/bin/env node
+/**
+ * hooks/gdd-precompact-snapshot.js — Plan 27.6-05
+ *
+ * Claude Code PreCompact hook. Immediately before context compaction,
+ * writes an atomic snapshot of STATE.md sections + last-N event-chain
+ * entries + last-N decisions to `.design/snapshots/<ts>.json`.
+ *
+ * Phase 27.6 D-08: atomic .tmp + rename via scripts/lib/lockfile.cjs.
+ *   - Lockfile serializes concurrent PreCompact writers.
+ *   - .tmp + rename guarantees no partial file ever appears at target path
+ *     (a SIGKILL between writeFileSync and renameSync leaves an orphan
+ *     .tmp file, never a corrupted snapshot).
+ *
+ * Phase 27.6 D-10: harness-aware — Codex has no PreCompact, so on
+ *   harness=codex this is a one-line stderr no-op (Phase 45 dep for
+ *   full pre-large-context-action interception).
+ *
+ * Silent-on-failure: tolerable errors exit 0 with stderr breadcrumb.
+ * Emits `snapshot.written` event via lazy appendEvent (best-effort).
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const SNAPSHOT_DIR = path.resolve(process.cwd(), '.design', 'snapshots');
+const STATE_MD_PATH = path.resolve(process.cwd(), '.design', 'STATE.md');
+const EVENTS_PATH = path.resolve(process.cwd(), '.design', 'telemetry', 'events.jsonl');
+const RETENTION_COUNT = 10;
+const EVENTS_TAIL_COUNT = 50;
+const DECISIONS_TAIL_COUNT = 10;
+const SCHEMA_VERSION = '1.0.0';
+
+// ---------------------------------------------------------------------------
+// Harness detection (D-10)
+// ---------------------------------------------------------------------------
+
+function detectHarness() {
+  const explicit = (process.env.CLAUDE_HARNESS || process.env.GDD_HARNESS || '')
+    .toLowerCase()
+    .trim();
+  if (explicit === 'codex' || explicit === 'codex-cli') return 'codex';
+  // Default — Claude Code (only harness that emits PreCompact today).
+  return 'claude-code';
+}
+
+// ---------------------------------------------------------------------------
+// Lazy event-stream emit (best-effort — never blocks the hook)
+// ---------------------------------------------------------------------------
+
+function getAppendEvent() {
+  try {
+    const m = require('../scripts/lib/event-stream');
+    if (m && typeof m.appendEvent === 'function') return m.appendEvent;
+  } catch {
+    /* swallow — event-stream is optional infrastructure */
+  }
+  return function noopAppend(_ev) {
+    /* no-op */
+  };
+}
+
+// ---------------------------------------------------------------------------
+// STATE.md tolerant parser — extracts frontmatter + decisions + blockers
+// ---------------------------------------------------------------------------
+
+function readStateSections() {
+  if (!fs.existsSync(STATE_MD_PATH)) {
+    return { frontmatter: {}, decisions: [], blockers: [], session: '' };
+  }
+  let body;
+  try {
+    body = fs.readFileSync(STATE_MD_PATH, 'utf8');
+  } catch {
+    return { frontmatter: {}, decisions: [], blockers: [], session: '' };
+  }
+
+  // Extract YAML frontmatter (between leading '---' delimiters)
+  const frontmatter = {};
+  const fmMatch = body.match(/^---\n([\s\S]*?)\n---\n/);
+  if (fmMatch) {
+    for (const line of fmMatch[1].split('\n')) {
+      const m = line.match(/^(\w+):\s*(.+)$/);
+      if (m) frontmatter[m[1]] = m[2].trim();
+    }
+  }
+
+  // Decisions: extract D-XX entries from a '<decisions>' or '## Decisions' section
+  const decisions = [];
+  const decisionsMatch = body.match(
+    /(?:<decisions>|## Decisions)([\s\S]*?)(?:<\/decisions>|^##\s|\Z)/m,
+  );
+  if (decisionsMatch) {
+    const dRe = /D-\d+:[^\n]+/g;
+    let m2;
+    while ((m2 = dRe.exec(decisionsMatch[1])) !== null) {
+      decisions.push(m2[0].trim());
+    }
+  }
+
+  // Blockers: similar to decisions
+  const blockers = [];
+  const blockersMatch = body.match(
+    /(?:<blockers>|## Blockers)([\s\S]*?)(?:<\/blockers>|^##\s|\Z)/m,
+  );
+  if (blockersMatch) {
+    const bRe = /B-\d+:[^\n]+/g;
+    let m3;
+    while ((m3 = bRe.exec(blockersMatch[1])) !== null) {
+      blockers.push(m3[0].trim());
+    }
+  }
+
+  // Session prefix (first ~500 chars after '## Session' or '<session>')
+  const sessionMatch = body.match(/(?:## Session|<session>)([\s\S]{0,500})/);
+  const session = sessionMatch ? sessionMatch[1].trim().slice(0, 500) : '';
+
+  return { frontmatter, decisions, blockers, session };
+}
+
+// ---------------------------------------------------------------------------
+// Events tail reader — JSONL-tolerant (malformed lines are skipped)
+// ---------------------------------------------------------------------------
+
+function readEventsTail(count) {
+  if (!fs.existsSync(EVENTS_PATH)) return [];
+  let body;
+  try {
+    body = fs.readFileSync(EVENTS_PATH, 'utf8');
+  } catch {
+    return [];
+  }
+  const events = [];
+  for (const line of body.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+    try {
+      events.push(JSON.parse(trimmed));
+    } catch {
+      /* tolerate malformed line — T-27.6.05-05 mitigation */
+    }
+  }
+  return events.slice(-count);
+}
+
+// ---------------------------------------------------------------------------
+// Retention prune — LRU by mtime, keep last RETENTION_COUNT (D-08)
+// ---------------------------------------------------------------------------
+
+function pruneSnapshots() {
+  let files;
+  try {
+    files = fs.readdirSync(SNAPSHOT_DIR);
+  } catch {
+    return;
+  }
+  const jsonFiles = files
+    .filter((f) => f.endsWith('.json') && f !== 'last-recap.json')
+    .map((f) => ({ name: f, full: path.join(SNAPSHOT_DIR, f), mtime: 0 }));
+
+  for (const entry of jsonFiles) {
+    try {
+      entry.mtime = fs.statSync(entry.full).mtimeMs;
+    } catch {
+      /* swallow */
+    }
+  }
+
+  jsonFiles.sort((a, b) => a.mtime - b.mtime);
+  while (jsonFiles.length > RETENTION_COUNT) {
+    const oldest = jsonFiles.shift();
+    try {
+      fs.unlinkSync(oldest.full);
+    } catch {
+      /* swallow — race with another writer; LRU eventually wins */
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main — atomic write with lockfile serialization
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const harness = detectHarness();
+  if (harness === 'codex') {
+    // D-10: Codex has no PreCompact event; emit notice + exit. Phase 45 dep
+    // for full `pre-large-context-action` interception.
+    process.stderr.write(
+      '[gdd-precompact-snapshot] this harness does not emit PreCompact; snapshots disabled\n',
+    );
+    process.exit(0);
+  }
+
+  // Drain stdin (Claude Code may pipe a hook event JSON; we don't need it
+  // but draining avoids EPIPE on the parent's writer side).
+  try {
+    if (!process.stdin.isTTY) {
+      // Best-effort, non-blocking — we have nothing time-sensitive in stdin.
+      process.stdin.on('error', () => {
+        /* swallow */
+      });
+      process.stdin.resume();
+    }
+  } catch {
+    /* swallow */
+  }
+
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+  const snapshotPath = path.join(SNAPSHOT_DIR, ts + '.json');
+  const tmpPath = snapshotPath + '.tmp';
+
+  // Ensure snapshot dir exists (mkdir -p semantics).
+  try {
+    fs.mkdirSync(SNAPSHOT_DIR, { recursive: true });
+  } catch {
+    /* swallow — write will fail loudly below if truly missing */
+  }
+
+  // Acquire lockfile on the target path (T-27.6.05-02 mitigation).
+  // The lock file lives at <snapshotPath>.lock and serializes concurrent
+  // PreCompact writers; the second writer either waits or fails-silent.
+  let release = null;
+  try {
+    const lockfile = require('../scripts/lib/lockfile.cjs');
+    release = await lockfile.acquire(snapshotPath, {
+      staleMs: 60_000,
+      maxWaitMs: 10_000,
+      pollMs: 50,
+    });
+  } catch (err) {
+    process.stderr.write(
+      '[gdd-precompact-snapshot] lock acquire failed: ' +
+        (err && err.message ? err.message : String(err)) +
+        '\n',
+    );
+    process.exit(0);
+  }
+
+  try {
+    const sections = readStateSections();
+    const events = readEventsTail(EVENTS_TAIL_COUNT);
+    const decisions = sections.decisions.slice(-DECISIONS_TAIL_COUNT);
+    const cycleId =
+      sections.frontmatter && sections.frontmatter.milestone
+        ? sections.frontmatter.milestone
+        : 'unknown';
+
+    const snapshot = {
+      schema_version: SCHEMA_VERSION,
+      timestamp: new Date().toISOString(),
+      cycle_id: cycleId,
+      state_md_sections: sections,
+      last_n_events: events,
+      last_n_decisions: decisions,
+    };
+
+    const body = JSON.stringify(snapshot, null, 2);
+
+    // Atomic write: .tmp + rename (T-27.6.05-01 mitigation).
+    // A SIGKILL between writeFileSync and renameSync leaves <snapshotPath>.tmp
+    // orphaned but NEVER a partial file at <snapshotPath> itself.
+    try {
+      fs.writeFileSync(tmpPath, body, 'utf8');
+      fs.renameSync(tmpPath, snapshotPath);
+    } catch (err) {
+      process.stderr.write(
+        '[gdd-precompact-snapshot] atomic write failed: ' +
+          (err && err.message ? err.message : String(err)) +
+          '\n',
+      );
+      try {
+        fs.unlinkSync(tmpPath);
+      } catch {
+        /* swallow orphan cleanup */
+      }
+      process.exit(0);
+    }
+
+    // Retention prune (T-27.6.05-04 DoS mitigation).
+    pruneSnapshots();
+
+    // Best-effort event emit.
+    const appendEvent = getAppendEvent();
+    try {
+      appendEvent({
+        type: 'snapshot.written',
+        timestamp: new Date().toISOString(),
+        sessionId: process.env.GDD_SESSION_ID || 'precompact-hook',
+        payload: {
+          path: snapshotPath,
+          size_bytes: Buffer.byteLength(body, 'utf8'),
+          events_count: events.length,
+          decisions_count: decisions.length,
+          harness,
+        },
+      });
+    } catch {
+      /* swallow — telemetry never blocks */
+    }
+
+    // Emit non-blocking continue verdict on stdout (matches other hooks).
+    try {
+      process.stdout.write(JSON.stringify({ continue: true, suppressOutput: true }));
+    } catch {
+      /* swallow */
+    }
+
+    process.exit(0);
+  } finally {
+    if (release) {
+      try {
+        await release();
+      } catch {
+        /* swallow — stale-detection reclaims */
+      }
+    }
+  }
+}
+
+main().catch((err) => {
+  try {
+    process.stderr.write(
+      '[gdd-precompact-snapshot] uncaught: ' +
+        (err && err.message ? err.message : String(err)) +
+        '\n',
+    );
+  } catch {
+    /* swallow */
+  }
+  process.exit(0);
+});