@hegemonart/get-design-done 1.58.0 → 1.59.1

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()`.