@hegemonart/get-design-done 1.58.1 → 1.59.1

package/reference/schemas/mcp-gdd-state-tools.schema.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://raw.githubusercontent.com/hegemonart/get-design-done/main/reference/schemas/mcp-gdd-state-tools.schema.json",
   "title": "McpGddStateTools",
-  "description": "Combined manifest of all 11 gdd-state MCP tool input+output schemas (Plan 20-05). Individual tool schemas live under scripts/mcp-servers/gdd-state/schemas/ and the tool handlers reference them; this combined schema exists so downstream validators and codegen can compile a single surface.",
+  "description": "Combined manifest of all 11 gdd-state MCP tool input+output schemas (Plan 20-05). Individual tool schemas live under sdk/mcp/gdd-state/schemas/ and the tool handlers reference them; this combined schema exists so downstream validators and codegen can compile a single surface.",
   "type": "object",
   "additionalProperties": false,
   "required": ["tools"],

package/reference/schemas/mcp-gdd-tools.schema.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://raw.githubusercontent.com/hegemonart/get-design-done/main/reference/schemas/mcp-gdd-tools.schema.json",
   "title": "McpGddTools",
-  "description": "Combined manifest of all gdd-mcp tool input+output schemas (Plan 27.7-02). Individual tool schemas live under scripts/mcp-servers/gdd-mcp/schemas/ and the tool handlers reference them; this combined schema exists so downstream validators and codegen can compile a single surface (D-11).",
+  "description": "Combined manifest of all gdd-mcp tool input+output schemas (Plan 27.7-02). Individual tool schemas live under sdk/mcp/gdd-mcp/schemas/ and the tool handlers reference them; this combined schema exists so downstream validators and codegen can compile a single surface (D-11).",
   "type": "object",
   "properties": {
     "tools": {

package/reference/skill-graph.md

@@ -9,7 +9,7 @@ is a `composes_with` edge (the source calls the target as sub-orchestration); a
 a `next_skills` edge (a pipeline hint for what runs next). Stage grouping is best-effort and
 inferred from the skill name; skills with no stage keyword fall under Utility.
 
-Skills: 94. Composition edges: 19 composes_with, 6 next_skills.
+Skills: 95. Composition edges: 19 composes_with, 6 next_skills.
 
 ```mermaid
 flowchart TD
@@ -65,6 +65,7 @@ flowchart TD
     n_add_backlog["add-backlog"]
     n_analyze_dependencies["analyze-dependencies"]
     n_apply_reflections["apply-reflections"]
+    n_bandit_reset["bandit-reset"]
     n_bandit_status["bandit-status"]
     n_budget["budget"]
     n_cache_manager["cache-manager"]

package/scripts/install.cjs

@@ -74,7 +74,7 @@ function helpText() {
     '  --dry-run       Print the diff without writing',
     '  --config-dir D  Override the config directory',
     '  --no-peer-prompt  Suppress the post-install peer-CLI detection nudge',
-    '  --register-mcp     Register gdd-mcp with detected harnesses (Claude Code, Codex). Opt-in.',
+    '  --register-mcp     Register gdd-mcp + gdd-state with detected harnesses (Claude Code, Codex). Opt-in.',
     '  --no-register-mcp  Skip MCP registration (default behavior; included for symmetry).',
     '  --doctor        Print Tier-2 distribution-channel status (read-only; no install)',
     '  --help, -h      Show this message',
@@ -287,6 +287,7 @@ async function main() {
   }
 
   // Phase 27.7 / Plan 27.7-04 — opt-in MCP registration (D-07).
+  // Phase 59.1 — registers BOTH gdd MCP servers (gdd-mcp + gdd-state).
   // Fires only on real install (not uninstall, not dry-run) when the user
   // passes --register-mcp explicitly. Default OFF; --no-register-mcp is a
   // no-op today (reserved for symmetry / when default flips). Idempotent
@@ -298,23 +299,29 @@ async function main() {
         try {
           const result = registerMcp({ harness });
           if (!result.detected) {
+            // CLI absent — single notice covers all servers for this harness.
             process.stderr.write('[install] ' + result.notice + '\n');
-          } else if (result.idempotent_skip) {
-            process.stdout.write(
-              '[install] gdd-mcp already registered with ' + harness + ' — skipping.\n',
-            );
-          } else if (result.applied) {
-            process.stdout.write(
-              '[install] gdd-mcp registered with ' + harness + '.\n',
-            );
-          } else {
-            process.stderr.write(
-              '[install] gdd-mcp registration with ' + harness + ' failed: exit ' + result.exit_code + '\n',
-            );
+            continue;
+          }
+          // Report each registered server individually.
+          for (const s of result.servers || []) {
+            if (s.idempotent_skip) {
+              process.stdout.write(
+                '[install] ' + s.server + ' already registered with ' + harness + ' — skipping.\n',
+              );
+            } else if (s.applied) {
+              process.stdout.write(
+                '[install] ' + s.server + ' registered with ' + harness + '.\n',
+              );
+            } else {
+              process.stderr.write(
+                '[install] ' + s.server + ' registration with ' + harness + ' failed: exit ' + s.exit_code + '\n',
+              );
+            }
           }
         } catch (err) {
           process.stderr.write(
-            '[install] gdd-mcp registration error (' + harness + '): ' + (err && err.message ? err.message : err) + '\n',
+            '[install] MCP registration error (' + harness + '): ' + (err && err.message ? err.message : err) + '\n',
           );
         }
       }

package/scripts/lib/install/mcp-register.cjs

@@ -1,10 +1,18 @@
 'use strict';
 // scripts/lib/install/mcp-register.cjs
 // ---------------------------------------------------------------------------
-// Plan 27.7-04 — registers `gdd-mcp` with the two harnesses that matter
-// (Claude Code, Codex) and detects existing registration. Idempotent;
+// Plan 27.7-04 — registers gdd's MCP servers with the two harnesses that
+// matter (Claude Code, Codex) and detects existing registration. Idempotent;
 // graceful absent-CLI fallback (D-07).
 //
+// Phase 59.1 — MCP parity: gdd ships TWO MCP servers, both registered here:
+//   - gdd-mcp   (read-only project tools; launch command `gdd-mcp`)
+//   - gdd-state (typed STATE mutators;   launch command `gdd-state-mcp`)
+// Each server is described in MCP_SERVERS as {name, launchCommand}. The
+// per-harness add-args are built per server so the registration name and the
+// launch command can differ (gdd-state registers under `gdd-state` but is
+// launched via the `gdd-state-mcp` bin).
+//
 // Pure library — no side effects on require. Invoked by:
 //   - scripts/install.cjs --register-mcp (opt-in; default off per D-07)
 //   - skills/health/SKILL.md check-mcp-registration step (read-only detect)
@@ -13,39 +21,75 @@
 // touching real CLIs in CI.
 //
 // Threat model: scripts/install.cjs --register-mcp writes to harness user-
-// level config. Command args are hardcoded in HARNESSES (no command-
-// injection surface); `--` separator before MCP_NAME prevents flag
-// injection (T-27.7-04-06).
+// level config. Command args are hardcoded in HARNESSES / MCP_SERVERS (no
+// command-injection surface); the `--` separator before the launch command
+// prevents flag injection (T-27.7-04-06).
 
 const { spawnSync } = require('node:child_process');
 
-const MCP_NAME = 'gdd-mcp';
+// The set of MCP servers gdd registers. `name` is the registration name (and
+// what appears in `<binary> mcp list`); `launchCommand` is the bin on PATH the
+// harness spawns. For gdd-mcp the two coincide; for gdd-state they differ.
+const MCP_SERVERS = Object.freeze([
+  Object.freeze({ name: 'gdd-mcp', launchCommand: 'gdd-mcp' }),
+  Object.freeze({ name: 'gdd-state', launchCommand: 'gdd-state-mcp' }),
+]);
+
+// Back-compat: the original single-server name. Retained for existing
+// importers (skills/health detection, type decls, tests).
+const MCP_NAME = MCP_SERVERS[0].name;
+
+// Build the `mcp add` argv for a given harness + server. Mirrors the original
+// per-harness shape exactly: claude pins user scope (`-s user`), codex does
+// not. The registration name precedes `--`; the launch command follows it.
+function claudeAddArgs(server) {
+  return ['mcp', 'add', server.name, '-s', 'user', '--', server.launchCommand];
+}
+function codexAddArgs(server) {
+  return ['mcp', 'add', server.name, '--', server.launchCommand];
+}
 
 const HARNESSES = Object.freeze({
   claude: Object.freeze({
     binary: 'claude',
-    addArgs: Object.freeze(['mcp', 'add', MCP_NAME, '-s', 'user', '--', MCP_NAME]),
+    addArgsFor: claudeAddArgs,
+    // Back-compat: addArgs for the primary (gdd-mcp) server.
+    addArgs: Object.freeze(claudeAddArgs(MCP_SERVERS[0])),
     listArgs: Object.freeze(['mcp', 'list']),
     listMatchPattern: /\bgdd-mcp\b/,
   }),
   codex: Object.freeze({
     binary: 'codex',
-    addArgs: Object.freeze(['mcp', 'add', MCP_NAME, '--', MCP_NAME]),
+    addArgsFor: codexAddArgs,
+    addArgs: Object.freeze(codexAddArgs(MCP_SERVERS[0])),
     listArgs: Object.freeze(['mcp', 'list']),
     listMatchPattern: /\bgdd-mcp\b/,
   }),
 });
 
+// Whether a server name appears in the harness's `mcp list` stdout. Built per
+// call so each server is matched on its own word-boundary-delimited name.
+function makeListMatchPattern(serverName) {
+  // Escape regex metacharacters in the server name (defensive; names are
+  // hardcoded today but this keeps the matcher injection-safe).
+  const escaped = serverName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp('(^|[^\\w-])' + escaped + '([^\\w-]|$)');
+}
+
 /**
- * Build the command tuple for a given harness + mode.
+ * Build the command tuple for a given harness + mode (+ optional server).
  * Currently only 'register' (add) is supported in command-build; 'detect'
  * uses listArgs internally, 'unregister' is reserved for future work.
+ *
+ * @param {'claude'|'codex'} harness
+ * @param {'register'|'detect'} [mode='register']
+ * @param {{name:string,launchCommand:string}} [server=MCP_SERVERS[0]]
  */
-function buildHarnessCommand(harness, mode = 'register') {
+function buildHarnessCommand(harness, mode = 'register', server = MCP_SERVERS[0]) {
   const h = HARNESSES[harness];
   if (!h) throw new Error('Unknown harness: ' + harness);
   if (mode === 'register') {
-    return { binary: h.binary, args: Array.from(h.addArgs) };
+    return { binary: h.binary, args: h.addArgsFor(server) };
   }
   if (mode === 'detect') {
     return { binary: h.binary, args: Array.from(h.listArgs) };
@@ -75,10 +119,16 @@ function detectHarnessPresent(harness, spawnFn = spawnSync) {
 }
 
 /**
- * Detect whether gdd-mcp is already registered with the given harness.
- * Runs `<binary> mcp list` and matches against listMatchPattern.
+ * Detect whether a given MCP server is already registered with the harness.
+ * Runs `<binary> mcp list` and matches against the server's name. When
+ * `serverName` is omitted, falls back to the harness's primary (gdd-mcp)
+ * pattern for back-compat with the original single-server signature.
+ *
+ * @param {'claude'|'codex'} harness
+ * @param {Function} [spawnFn]
+ * @param {string} [serverName]  server registration name to match
  */
-function isAlreadyRegistered(harness, spawnFn = spawnSync) {
+function isAlreadyRegistered(harness, spawnFn = spawnSync, serverName) {
   const h = HARNESSES[harness];
   if (!h) throw new Error('Unknown harness: ' + harness);
   let result;
@@ -92,45 +142,20 @@ function isAlreadyRegistered(harness, spawnFn = spawnSync) {
   }
   if (!result || result.status !== 0) return false;
   const stdout = (result.stdout || '').toString();
-  return h.listMatchPattern.test(stdout);
+  const pattern = serverName ? makeListMatchPattern(serverName) : h.listMatchPattern;
+  return pattern.test(stdout);
 }
 
 /**
- * Register gdd-mcp with the given harness.
- *
- * @param {object} opts
- * @param {'claude'|'codex'} opts.harness
- * @param {'register'|'unregister'|'detect'} [opts.mode='register']
- * @param {boolean} [opts.dryRun=false]
- * @param {Function} [opts.spawnFn]  child_process.spawnSync substitute
- * @returns {object} {harness, action, detected, command, applied,
- *                    idempotent_skip, notice?, stdout?, stderr?,
- *                    exit_code?, dry_run?}
+ * Register a single MCP server with the given harness. Assumes the harness CLI
+ * is already known to be present (caller does the PATH check once for all
+ * servers). Returns the same per-server shape the original registerMcp did.
  */
-function registerMcp({ harness, mode = 'register', dryRun = false, spawnFn = spawnSync } = {}) {
-  if (!HARNESSES[harness]) {
-    throw new Error('Unknown harness: ' + harness + ' (expected one of: ' + Object.keys(HARNESSES).join(', ') + ')');
-  }
-  if (mode !== 'register' && mode !== 'detect' && mode !== 'unregister') {
-    throw new Error('Unsupported mode: ' + mode);
-  }
-
-  // Step 1 — detect harness CLI on PATH
-  if (!detectHarnessPresent(harness, spawnFn)) {
-    return {
-      harness,
-      action: mode,
-      detected: false,
-      command: null,
-      applied: false,
-      idempotent_skip: false,
-      notice: harness + ' CLI not on PATH — skipping ' + MCP_NAME + ' registration',
-    };
-  }
-
-  // Step 2 — idempotency check: already registered?
-  if (isAlreadyRegistered(harness, spawnFn)) {
+function registerOneServer(harness, server, { mode, dryRun, spawnFn }) {
+  // Idempotency check: this specific server already registered?
+  if (isAlreadyRegistered(harness, spawnFn, server.name)) {
     return {
+      server: server.name,
       harness,
       action: mode,
       detected: true,
@@ -140,12 +165,13 @@ function registerMcp({ harness, mode = 'register', dryRun = false, spawnFn = spa
     };
   }
 
-  // Step 3 — build + dispatch add command
-  const { binary, args } = buildHarnessCommand(harness, 'register');
+  // Build + dispatch the per-server add command.
+  const { binary, args } = buildHarnessCommand(harness, 'register', server);
   const commandStr = binary + ' ' + args.join(' ');
 
   if (dryRun) {
     return {
+      server: server.name,
       harness,
       action: mode,
       detected: true,
@@ -161,6 +187,7 @@ function registerMcp({ harness, mode = 'register', dryRun = false, spawnFn = spa
     result = spawnFn(binary, args, { stdio: 'pipe', encoding: 'utf8' });
   } catch (e) {
     return {
+      server: server.name,
       harness,
       action: mode,
       detected: true,
@@ -175,6 +202,7 @@ function registerMcp({ harness, mode = 'register', dryRun = false, spawnFn = spa
   const stderr = (result && result.stderr) || '';
   const exit_code = result ? result.status : null;
   return {
+    server: server.name,
     harness,
     action: mode,
     detected: true,
@@ -187,6 +215,58 @@ function registerMcp({ harness, mode = 'register', dryRun = false, spawnFn = spa
   };
 }
 
+/**
+ * Register all gdd MCP servers (MCP_SERVERS) with the given harness.
+ *
+ * The harness CLI presence is checked ONCE; if absent, no servers are
+ * registered. Otherwise each server in MCP_SERVERS is registered (idempotent
+ * per server). The return value keeps the original single-server fields at the
+ * top level (mirroring the primary gdd-mcp server) for back-compat, and adds a
+ * `servers` array carrying the per-server results.
+ *
+ * @param {object} opts
+ * @param {'claude'|'codex'} opts.harness
+ * @param {'register'|'unregister'|'detect'} [opts.mode='register']
+ * @param {boolean} [opts.dryRun=false]
+ * @param {Function} [opts.spawnFn]  child_process.spawnSync substitute
+ * @returns {object} {harness, action, detected, command, applied,
+ *                    idempotent_skip, notice?, stdout?, stderr?,
+ *                    exit_code?, dry_run?, servers}
+ */
+function registerMcp({ harness, mode = 'register', dryRun = false, spawnFn = spawnSync } = {}) {
+  if (!HARNESSES[harness]) {
+    throw new Error('Unknown harness: ' + harness + ' (expected one of: ' + Object.keys(HARNESSES).join(', ') + ')');
+  }
+  if (mode !== 'register' && mode !== 'detect' && mode !== 'unregister') {
+    throw new Error('Unsupported mode: ' + mode);
+  }
+
+  // Step 1 — detect harness CLI on PATH (once, for all servers).
+  if (!detectHarnessPresent(harness, spawnFn)) {
+    const names = MCP_SERVERS.map((s) => s.name).join(' + ');
+    return {
+      harness,
+      action: mode,
+      detected: false,
+      command: null,
+      applied: false,
+      idempotent_skip: false,
+      notice: harness + ' CLI not on PATH — skipping ' + names + ' registration',
+      servers: [],
+    };
+  }
+
+  // Step 2 — register each server (idempotent per server).
+  const servers = MCP_SERVERS.map((server) =>
+    registerOneServer(harness, server, { mode, dryRun, spawnFn }),
+  );
+
+  // Top-level fields mirror the primary (first) server for back-compat with
+  // the original single-server callers; `servers` carries the full detail.
+  const primary = servers[0];
+  return Object.assign({}, primary, { servers });
+}
+
 /**
  * Detect overall MCP registration state across all known harnesses.
  *
@@ -232,4 +312,5 @@ module.exports = {
   buildHarnessCommand,
   HARNESSES,
   MCP_NAME,
+  MCP_SERVERS,
 };

package/scripts/lib/manifest/skills.json

@@ -29,6 +29,13 @@
       "argument_hint": "[--retroactive] [--quick] [--no-reflect]",
       "tools": "Read, Write, Task, Glob, Bash"
     },
+    {
+      "name": "bandit-reset",
+      "description": "Confirm-then-reset the per-(agent, bin, delegate) bandit posterior - backs up .design/telemetry/posterior.json to posterior.json.bak, then clears it to a fresh empty envelope. Mutation companion to read-only bandit-status. Use when the posterior is corrupted/unparseable, after a major agent/skill roster change invalidates accumulated arms, or when you deliberately want to rebootstrap adaptive routing from informed priors.",
+      "argument_hint": "[--yes to skip the confirmation prompt]",
+      "tools": "Read, Write, Bash, AskUserQuestion",
+      "disable_model_invocation": true
+    },
     {
       "name": "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.",

package/sdk/cli/commands/audit.ts

@@ -89,6 +89,11 @@ export interface AuditReport {
   readonly connections: readonly ConnectionReport[];
   readonly must_haves: readonly MustHaveReport[];
   readonly baseline?: BaselineReport;
+  // `true` when there is no active cycle (.design/STATE.md absent). The audit
+  // then runs only the static checks that do not require cycle state and exits
+  // 0 with this flag set, rather than failing. Omitted (undefined) on a normal
+  // run with an active cycle.
+  readonly degraded?: boolean;
   readonly summary: {
     readonly connections_ok: boolean;
     readonly must_haves_ok: boolean;
@@ -135,14 +140,23 @@ export async function auditCommand(
 
   const cwd: string =
     typeof flags['cwd'] === 'string' ? (flags['cwd'] as string) : process.cwd();
-  const statePath: string =
-    typeof flags['state-path'] === 'string' && (flags['state-path'] as string).length > 0
-      ? resolvePath(cwd, flags['state-path'] as string)
-      : resolvePath(cwd, '.design', 'STATE.md');
+  const explicitStatePath: boolean =
+    typeof flags['state-path'] === 'string' && (flags['state-path'] as string).length > 0;
+  const statePath: string = explicitStatePath
+    ? resolvePath(cwd, flags['state-path'] as string)
+    : resolvePath(cwd, '.design', 'STATE.md');
 
   if (!existsSync(statePath)) {
-    stderr.write(`gdd-sdk audit: STATE.md not found at ${statePath}\n`);
-    return 3;
+    // An explicit --state-path that does not exist is an arg error: the
+    // caller pointed us at a specific file that should be present.
+    if (explicitStatePath) {
+      stderr.write(`gdd-sdk audit: STATE.md not found at ${statePath}\n`);
+      return 3;
+    }
+    // No active cycle (default .design/STATE.md absent). Graceful degrade:
+    // emit a clear message + a degraded report covering the static checks
+    // that do not require cycle state, then exit 0 — never throw.
+    return emitDegraded(flags, stdout, stderr);
   }
 
   const readFn = deps.readState ?? read;
@@ -218,6 +232,46 @@ export async function auditCommand(
   return overallOk ? 0 : 1;
 }
 
+// ---------------------------------------------------------------------------
+// Degraded (no active cycle) path.
+// ---------------------------------------------------------------------------
+
+/**
+ * Emit a degraded audit report when there is no active cycle (no
+ * `.design/STATE.md`). Connections + must-haves are sourced from STATE.md,
+ * so without a cycle there is nothing cycle-bound to evaluate; we report
+ * empty sets and exit 0. The `degraded` flag signals callers (and the JSON
+ * consumers) that this was a no-cycle run, not a clean active-cycle audit.
+ */
+function emitDegraded(
+  flags: Record<string, unknown>,
+  stdout: NodeJS.WritableStream,
+  stderr: NodeJS.WritableStream,
+): number {
+  // Human-facing notice on stderr so JSON on stdout stays machine-parseable.
+  stderr.write('gdd-sdk audit: no active cycle — run /gdd:start\n');
+
+  const report: AuditReport = {
+    connections: Object.freeze([]),
+    must_haves: Object.freeze([]),
+    degraded: true,
+    summary: {
+      connections_ok: true,
+      must_haves_ok: true,
+      baseline_ok: true,
+      overall_ok: true,
+    },
+  };
+
+  if (flags['json'] === true) {
+    stdout.write(JSON.stringify(report, null, 2) + '\n');
+  } else {
+    stdout.write(renderHuman(report));
+  }
+
+  return 0;
+}
+
 // ---------------------------------------------------------------------------
 // Baseline comparison.
 // ---------------------------------------------------------------------------
@@ -352,6 +406,12 @@ function parseBaselineStateSync(raw: string): Pick<ParsedState, 'connections' |
 
 function renderHuman(report: AuditReport): string {
   const lines: string[] = [];
+  if (report.degraded === true) {
+    lines.push('audit: degraded (no active cycle — run /gdd:start)');
+    lines.push('');
+    lines.push('No active cycle: skipped connection + must-have checks.');
+    return lines.join('\n') + '\n';
+  }
   lines.push(`audit: ${report.summary.overall_ok ? 'clean' : 'REGRESSIONS'}`);
   lines.push('');
   lines.push(`connections (${report.summary.connections_ok ? 'ok' : 'degraded'}):`);

package/sdk/cli/index.js

@@ -8774,11 +8774,15 @@ async function auditCommand(args, deps = {}) {
     return 3;
   }
   const cwd = typeof flags["cwd"] === "string" ? flags["cwd"] : process.cwd();
-  const statePath = typeof flags["state-path"] === "string" && flags["state-path"].length > 0 ? (0, import_node_path17.resolve)(cwd, flags["state-path"]) : (0, import_node_path17.resolve)(cwd, ".design", "STATE.md");
+  const explicitStatePath = typeof flags["state-path"] === "string" && flags["state-path"].length > 0;
+  const statePath = explicitStatePath ? (0, import_node_path17.resolve)(cwd, flags["state-path"]) : (0, import_node_path17.resolve)(cwd, ".design", "STATE.md");
   if (!(0, import_node_fs17.existsSync)(statePath)) {
-    stderr.write(`gdd-sdk audit: STATE.md not found at ${statePath}
+    if (explicitStatePath) {
+      stderr.write(`gdd-sdk audit: STATE.md not found at ${statePath}
 `);
-    return 3;
+      return 3;
+    }
+    return emitDegraded(flags, stdout, stderr);
   }
   const readFn = deps.readState ?? read;
   let state;
@@ -8841,6 +8845,26 @@ async function auditCommand(args, deps = {}) {
   }
   return overallOk ? 0 : 1;
 }
+function emitDegraded(flags, stdout, stderr) {
+  stderr.write("gdd-sdk audit: no active cycle \u2014 run /gdd:start\n");
+  const report = {
+    connections: Object.freeze([]),
+    must_haves: Object.freeze([]),
+    degraded: true,
+    summary: {
+      connections_ok: true,
+      must_haves_ok: true,
+      baseline_ok: true,
+      overall_ok: true
+    }
+  };
+  if (flags["json"] === true) {
+    stdout.write(JSON.stringify(report, null, 2) + "\n");
+  } else {
+    stdout.write(renderHuman(report));
+  }
+  return 0;
+}
 function computeBaselineDrift(current, baselineDir) {
   const baselinePath = (0, import_node_path17.resolve)(baselineDir, "STATE.md");
   if (!(0, import_node_fs17.existsSync)(baselinePath)) {
@@ -8923,6 +8947,12 @@ function parseBaselineStateSync(raw) {
 }
 function renderHuman(report) {
   const lines = [];
+  if (report.degraded === true) {
+    lines.push("audit: degraded (no active cycle \u2014 run /gdd:start)");
+    lines.push("");
+    lines.push("No active cycle: skipped connection + must-have checks.");
+    return lines.join("\n") + "\n";
+  }
   lines.push(`audit: ${report.summary.overall_ok ? "clean" : "REGRESSIONS"}`);
   lines.push("");
   lines.push(`connections (${report.summary.connections_ok ? "ok" : "degraded"}):`);

package/skills/bandit-reset/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: gdd-bandit-reset
+description: "Confirm-then-reset the per-(agent, bin, delegate) bandit posterior - backs up .design/telemetry/posterior.json to posterior.json.bak, then clears it to a fresh empty envelope. Mutation companion to read-only bandit-status. Use when the posterior is corrupted/unparseable, after a major agent/skill roster change invalidates accumulated arms, or when you deliberately want to rebootstrap adaptive routing from informed priors."
+argument-hint: "[--yes to skip the confirmation prompt]"
+tools: Read, Write, Bash, AskUserQuestion
+disable-model-invocation: true
+---
+
+# gdd-bandit-reset
+
+## Role
+
+You are a deterministic, destructive maintenance skill. You are the ONLY skill that clears the bandit posterior - the mutation companion to read-only `/gdd:bandit-status`. You read the posterior path declared by `scripts/lib/bandit-router.cjs`'s `DEFAULT_POSTERIOR_PATH` (`.design/telemetry/posterior.json`), REQUIRE explicit confirmation, back the file up to `posterior.json.bak`, then overwrite it with a fresh empty envelope so the next bandit pull rebootstraps from informed priors. See `./reference/bandit-integration.md` for setup, interpretation, and convergence guidance.
+
+## Invocation Contract
+
+- **Input**: optional `--yes` to skip the interactive confirmation (for non-interactive/automated runs).
+- **Output**: a Markdown reset receipt to stdout (backup path + arms cleared + envelope written).
+
+## Procedure
+
+### 1. Locate the posterior file
+
+Read `.design/telemetry/posterior.json` (path declared by `scripts/lib/bandit-router.cjs`'s `DEFAULT_POSTERIOR_PATH` - never hardcode a different path). Missing → nothing to reset; emit and skip to Section 5 (Record):
+
+```
+## Bandit Posterior Reset
+
+No posterior file found at `.design/telemetry/posterior.json` — nothing to reset.
+
+The next bandit pull with `adaptive_mode: full` will bootstrap a fresh posterior from informed priors. See `reference/bandit-integration.md`.
+```
+
+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
+
+This is a DESTRUCTIVE operation. Do NOT proceed without confirmation.
+
+- If `--yes` was passed, skip straight to Section 3.
+- Otherwise, prompt via AskUserQuestion: "Reset the bandit posterior at `.design/telemetry/posterior.json`? This clears <N> learned arms. A backup will be written to `posterior.json.bak` first." with options **Reset** and **Cancel**.
+- On **Cancel** (or any non-affirmative answer), abort WITHOUT touching either the posterior or the backup, and emit:
+
+```
+## Bandit Posterior Reset — Cancelled
+
+No changes made. The posterior at `.design/telemetry/posterior.json` is untouched (<N> arms).
+```
+
+Then skip to Section 5 (Record) with `reset: false`.
+
+### 3. Back up the current posterior
+
+Copy the live posterior to `.design/telemetry/posterior.json.bak` (sibling backup) BEFORE clearing it, so the previous state is always recoverable. Overwrite any existing `.bak` from a prior reset. If the backup write fails, ABORT before clearing; never clear without a successful backup.
+
+### 4. Clear to a fresh empty envelope
+
+Overwrite `.design/telemetry/posterior.json` with a fresh empty envelope matching `scripts/lib/bandit-router.cjs`'s `loadPosterior()` shape (`SCHEMA_VERSION` = `1.0.0`, current ISO `generated_at`, empty `arms`):
+
+```json
+{
+  "schema_version": "1.0.0",
+  "generated_at": "<ISO>",
+  "arms": []
+}
+```
+
+Write atomically where possible (`.tmp` + rename, mirroring `savePosterior()`). Then emit the receipt:
+
+```
+## Bandit Posterior Reset
+
+Posterior cleared. The next bandit pull with `adaptive_mode: full` will rebootstrap from informed priors.
+
+- Backup: `.design/telemetry/posterior.json.bak`
+- Arms cleared: <N>
+- Fresh envelope: `.design/telemetry/posterior.json` (schema_version 1.0.0, 0 arms)
+
+Restore the previous state with: `cp .design/telemetry/posterior.json.bak .design/telemetry/posterior.json`
+Verify the cleared state with `/gdd:bandit-status`. See `reference/bandit-integration.md`.
+```
+
+### 5. Record
+
+Append one JSONL line to `.design/skill-records.jsonl`: `{"skill":"gdd-bandit-reset","ts":"<ISO>","reset":<bool>,"arms_cleared":<count>,"backup_written":<bool>}`. The skill mutates ONLY the posterior (+ its `.bak`) and appends to skill-records.jsonl (telemetry); it touches no other state.
+
+## Cross-references
+
+- `/gdd:bandit-status` - read-only companion; inspect the posterior before/after a reset.
+- `./reference/bandit-integration.md` - operator guide; interpretation patterns and when a reset is warranted.
+- `scripts/lib/bandit-router.cjs` - posterior shape, `DEFAULT_POSTERIOR_PATH`, `SCHEMA_VERSION`, `loadPosterior()`, `savePosterior()`, `reset()`.