@hegemonart/get-design-done 1.55.0 → 1.57.0

package/skills/override/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: gdd-override
+description: "Escalation surface for a risk-blocked action or a fact-force gate. Use when the Phase 56 risk gate blocked a writer action (suggested_action=block) and a reviewer has signed off, or when the first-write fact-force gate is holding a file you have legitimately reviewed. Activates for requests involving overriding a blocked edit, approving a high-risk change, or clearing a fact-force hold on a path."
+argument-hint: "<finding-id | factforce <path>> [--approver <who>] [--reason <text>]"
+user-invocable: true
+tools: Read, Write, Bash, Grep, Glob
+---
+
+# /gdd:override
+
+A risk-blocked action is hard: the Phase 56 risk gate routes `suggested_action=block`
+to `override` (see `scripts/lib/risk/route.cjs`), and the fact-force gate holds the
+first write to a file until its facts are read. This skill is the audited way past
+either hold. It mirrors `/gdd:unlock-decision`: a named approver plus a
+reason, recorded before anything is let through. Override is never silent.
+
+## Invocation
+
+| Command | Behavior |
+|---|---|
+| `/gdd:override <finding-id> --approver <who> --reason <text>` | Record a `D-XX` `override`-tagged decision in STATE.md `<decisions>` and let the risk-blocked action through. |
+| `/gdd:override factforce <path> --approver <who> --reason <text>` | Set `checked[path]` in the session fact-force state so the fact-force gate stops holding that path. |
+
+Both modes ask for a rationale: the audit trail is the reason override exists.
+
+## Steps
+
+1. **Parse args.** Mode is `factforce` when the first token is the literal `factforce`
+   (the next token is the `<path>`); otherwise the first token is a `<finding-id>`.
+   `--approver` is required (a non-empty name). Missing `--approver` prints the usage
+   and changes nothing. If `--reason` is absent, ASK for one (AskUserQuestion or a
+   prompt) before continuing: an override with no rationale is rejected.
+
+2. **Preview.** Show what will be written and stop for confirmation:
+   - finding mode: the decision entry from `overrideDecisionEntry(<id>, {approver, reason})`
+     (its `text`, `status: locked`, and `override` tag) plus the action it unblocks.
+   - factforce mode: the `<path>` that will gain `checked[path] = true` and the
+     session-state file it lands in.
+
+3. **Apply (finding mode).** Record the audited decision via the STATE writer
+   `mcp__gdd_state__add_decision` (it auto-assigns the next `D-N`). Pass the `text`
+   from the pure builder so the `override` tag is embedded and greppable:
+
+   ```bash
+   node -e '
+     const o = require("./scripts/lib/risk/override.cjs");
+     const [id, who, reason] = process.argv.slice(1);
+     const entry = o.overrideDecisionEntry(id, { approver: who, reason });
+     console.log(JSON.stringify(entry));
+   ' "<finding-id>" "<who>" "<reason>"
+   ```
+
+   Then call `mcp__gdd_state__add_decision` with `{ text: <entry.text>, status: "locked" }`.
+   The blocked action is now approved on the audit record; proceed with it.
+
+4. **Apply (factforce mode).** Set `checked[path]` in the session state file at
+   `<cwd>/.design/locks/factforce-<session_id>.json` (atomic tmp then rename), using
+   the pure helper so the shape matches what the fact-force gate reads:
+
+   ```bash
+   node -e '
+     const fs = require("fs"); const path = require("path");
+     const o = require("./scripts/lib/risk/override.cjs");
+     const [file, p] = process.argv.slice(1);
+     let state = {}; try { state = JSON.parse(fs.readFileSync(file, "utf8")); } catch {}
+     const next = o.setFactForceChecked(state, p);
+     fs.mkdirSync(path.dirname(file), { recursive: true });
+     const tmp = file + ".tmp";
+     fs.writeFileSync(tmp, JSON.stringify(next, null, 2) + "\n");
+     fs.renameSync(tmp, file);
+     console.log(JSON.stringify(next.checked));
+   ' "<cwd>/.design/locks/factforce-<session_id>.json" "<path>"
+   ```
+
+   The fact-force gate stops holding `<path>` for the rest of the session.
+
+5. **Report** the recorded approver, the reason, and either the new `D-XX` id (finding
+   mode) or the unblocked path (factforce mode).
+
+## Do Not
+
+- Do not skip the rationale: every override is audited.
+- Do not override a finding that the risk gate did not actually block.
+- Do not edit `scripts/lib/risk/route.cjs` or `compute-risk.cjs`: this skill consumes them.
+
+## OVERRIDE COMPLETE

package/skills/state/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: gdd-state
+description: "Query, recover, or roll back the Phase 57 SQLite state backbone. Use when you need to inspect the decisions/blockers/plans tables with a raw SELECT, rebuild a corrupt state.sqlite from the markdown STATE.md, or revert to the markdown-only source of truth by removing state.sqlite. Activates for requests involving querying the SQLite state database, recovering from SQLite corruption, or reverting the migration (demigrate)."
+argument-hint: "<query \"<sql>\" | recover | demigrate>"
+user-invocable: true
+tools: Read, Bash, Grep, Glob
+---
+
+# /gdd:state
+
+The Phase 57 SQLite state backbone is opt-in (`--migrate-state`) and fully reversible.
+Markdown `.design/STATE.md` is always the human-editable SoT; SQLite is a faster query
+layer derived from it. This skill exposes three subcommands for operating on that layer.
+
+## Subcommands
+
+| Subcommand | What it does |
+|---|---|
+| `/gdd:state query "<sql>"` | Run a read-only SELECT against `.design/state.sqlite`. |
+| `/gdd:state recover` | Rotate the current sqlite to a `.bak` and rebuild from markdown. |
+| `/gdd:state demigrate` | Remove `.design/state.sqlite`; markdown becomes the SoT again. |
+
+---
+
+## query
+
+Execute a read-only SELECT against the state database.
+
+The engine opens the file with `readonly:true` so all writes are rejected at the
+engine level. A first-token denylist (Set membership, no regex) additionally blocks
+DROP, DELETE, UPDATE, INSERT, ALTER, ATTACH, CREATE, PRAGMA, VACUUM, ANALYZE,
+REINDEX, and REPLACE before the connection is opened.
+
+```bash
+node -e '
+  const qs = require("./scripts/lib/state/query-surface.cjs");
+  const result = qs.query(process.argv[1], { projectRoot: process.cwd() });
+  console.log(JSON.stringify(result, null, 2));
+' "<sql>"
+```
+
+Outputs `{ rows: [...], backend: "sqlite" }` on success, or
+`{ degraded: true, message: "..." }` when SQLite is not active.
+
+Degrades gracefully (no throw) when `BACKEND==='markdown'` or when
+`.design/state.sqlite` has not been created yet (run `--migrate-state` first).
+
+---
+
+## recover
+
+Rotate the current (possibly corrupt) `.design/state.sqlite` to `.bak.0`, then
+rebuild a fresh database from the markdown `.design/STATE.md` using
+`migrate-to-sqlite.cjs` in force mode. Runs `PRAGMA integrity_check` on the
+result and reports the outcome.
+
+```bash
+node -e '
+  const qs = require("./scripts/lib/state/query-surface.cjs");
+  const result = qs.recover({ projectRoot: process.cwd() });
+  console.log(JSON.stringify(result, null, 2));
+'
+```
+
+Outputs `{ recovered: true, integrity: true, message: "..." }` on success.
+
+Backup rotation keeps at most 10 files (`.bak.0` through `.bak.9`). The oldest
+backup is overwritten when the cap is reached.
+
+---
+
+## demigrate
+
+Remove `.design/state.sqlite` so the markdown `STATE.md` becomes the SoT again.
+Idempotent: if the file does not exist, returns a clear no-op message without error.
+A backup is taken in `.bak.0` before removal.
+
+```bash
+node -e '
+  const qs = require("./scripts/lib/state/query-surface.cjs");
+  const result = qs.demigrate({ projectRoot: process.cwd() });
+  console.log(JSON.stringify(result, null, 2));
+'
+```
+
+Outputs `{ demigrated: true, message: "..." }` when the file was removed, or
+`{ demigrated: false, message: "..." }` when it was already absent (no-op).
+
+To re-enable SQLite after a demigrate, run `--migrate-state` again.
+
+---
+
+## Key design decisions
+
+- **Markdown is always the SoT.** SQLite is opt-in via `--migrate-state` and
+  reversible via `demigrate`. The markdown file is never silently overwritten.
+- **Read-only queries only.** The `query` subcommand enforces SELECT-only via both
+  the engine (`readonly:true`) and a defense-in-depth denylist. No writes
+  are possible through this skill.
+- **Backup rotation cap.** `rotateBak` shifts `.bak.0..8` up by one index and caps
+  at `.bak.9` (10 files total). The oldest backup is overwritten automatically.
+- **Graceful degradation.** All subcommands return a clear `{ degraded, message }`
+  object (no throw) when `better-sqlite3` is not installed or when
+  `GDD_STATE_BACKEND=markdown` is set.
+
+## STATE COMPLETE