@hegemonart/get-design-done 1.30.5 → 1.31.0

package/scripts/lib/{gsd-health-mirror → health-mirror}/index.cjs

@@ -1,5 +1,5 @@
 'use strict';
-// scripts/lib/gsd-health-mirror/index.cjs — Plan 27.7-02
+// scripts/lib/health-mirror/index.cjs — Plan 27.7-02 (renamed in Phase 30.6-08 per D-10)
 //
 // Pure read-only mirror of skills/health/SKILL.md's check surface.
 // NO subprocess spawn — just inspects 4 well-known files/dirs and
@@ -8,12 +8,13 @@
 // Surface:
 //   async getHealthChecks(rootDir) → { checks: HealthCheck[] }
 //
-// The 5 checks (in stable order) are:
+// The 6 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)
 //
 // 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
@@ -22,6 +23,17 @@
 //   - "issue reporter: disabled by env (GDD_DISABLE_ISSUE_REPORTER=1)"
 //   - "issue reporter: disabled by config (.design/config.json: issue_reporter=false)"
 // When both env and config trigger, env wins (matches D-08 display contract).
+//
+// Check 6 was added in Plan 31-09 — surfaces figma-extract readiness so a user
+// running /gdd:health immediately knows whether figma-extract is usable. The
+// detail line is one of three exact strings:
+//   - "figma extract: ready (token set)"
+//   - "figma extract: token missing"
+//   - "figma extract: plugin sync needed for variables (Free tier detected)"
+// D-10: only FIGMA_TOKEN *presence* is used — the token VALUE is never read,
+// 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).
 
 const fs = require('node:fs');
 const path = require('node:path');
@@ -135,7 +147,82 @@ async function getHealthChecks(rootDir) {
     });
   }
 
+  // 6. figma_extract — extract readiness + Free-tier plugin-sync signal (Plan 31-09)
+  // Reports exactly one of three states. PURE read-only: presence-only token
+  // check (D-10 — value never read/logged/printed) + a LOCAL Free-tier marker
+  // (a prior pull's _meta.json recording a 403/skip on the Variables endpoint —
+  // see scripts/lib/figma-extract/pull.cjs). NEVER throws, NEVER networks.
+  {
+    // D-10: presence only. The token VALUE is never bound to a variable that
+    // could be interpolated into detail/logs — only the boolean is kept.
+    const tokenSet = !!(process.env.FIGMA_TOKEN || process.env.FIGMA_PERSONAL_ACCESS_TOKEN);
+
+    let detail;
+    let status;
+    if (!tokenSet) {
+      detail = 'figma extract: token missing';
+      status = 'warn';
+    } else if (figmaVariablesBlockedLocally(rootDir)) {
+      // Token present but a prior pull recorded a 403/skip on the Variables REST
+      // path → Free/non-Enterprise tier. Actionable (plugin sync), not a hard fail.
+      detail = 'figma extract: plugin sync needed for variables (Free tier detected)';
+      status = 'warn';
+    } else {
+      detail = 'figma extract: ready (token set)';
+      status = 'ok';
+    }
+    checks.push({ name: 'figma_extract', status, detail });
+  }
+
   return { checks };
 }
 
+/**
+ * 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
+ * the gitignored cache dir; on a Variables 403 it records a totals[] entry
+ * `{ name: 'variables', skipped: true, reason: 'HTTP 403' }`. We scan the
+ * default cache root for any such marker. Defensive: malformed/absent markers
+ * default to NOT-free (→ 'ready') so the health probe never false-alarms and
+ * NEVER throws. NEVER reads the token; NEVER makes a request.
+ *
+ * @param {string} rootDir project root passed to getHealthChecks
+ * @returns {boolean} true iff a prior pull recorded a Variables 403/skip
+ */
+function figmaVariablesBlockedLocally(rootDir) {
+  try {
+    const rawRoot = path.join(rootDir, '.figma-extract-cache', 'raw');
+    let entries;
+    try {
+      entries = fs.readdirSync(rawRoot, { withFileTypes: true });
+    } catch {
+      return false; // no cache yet → default to ready
+    }
+    for (const ent of entries) {
+      if (!ent.isDirectory()) continue;
+      const metaPath = path.join(rawRoot, ent.name, '_meta.json');
+      let meta;
+      try {
+        meta = JSON.parse(fs.readFileSync(metaPath, 'utf8'));
+      } catch {
+        continue; // missing/garbage marker → ignore this dir, keep scanning
+      }
+      const totals = meta && Array.isArray(meta.totals) ? meta.totals : [];
+      const blocked = totals.some(
+        (t) =>
+          t &&
+          t.name === 'variables' &&
+          t.skipped === true &&
+          typeof t.reason === 'string' &&
+          /403/.test(t.reason)
+      );
+      if (blocked) return true;
+    }
+    return false;
+  } catch {
+    // Absolute safety net — the health probe must never crash on this check.
+    return false;
+  }
+}
+
 module.exports = { getHealthChecks };

package/scripts/mcp-servers/gdd-mcp/tools/gdd_health.ts

@@ -1,9 +1,9 @@
 // scripts/mcp-servers/gdd-mcp/tools/gdd_health.ts
 //
-// Plan 27.7-02. Read-only mirror of skills/health/SKILL.md output via
-// scripts/lib/gsd-health-mirror/. No subprocess spawn — pure inspection.
+// Plan 27.7-02 (lib renamed to health-mirror in Phase 30.6-08 per D-10).
+// Read-only mirror of skills/health/SKILL.md output. No subprocess spawn — pure inspection.
 
-import { getHealthChecks } from '../../../lib/gsd-health-mirror/index.cjs';
+import { getHealthChecks } from '../../../lib/health-mirror/index.cjs';
 import { errorResponse, okResponse, resolveProjectRoot, type ToolResponse } from './shared.ts';
 
 export const name = 'gdd_health';

package/skills/connections/connections-onboarding.md

@@ -106,13 +106,13 @@ Bash: command -v chromatic >/dev/null 2>&1 || npx --yes chromatic --version 2>/d
                       Set   → chromatic: available
 ```
 
-**graphify** (CLI + file):
+**graphify** (native CLI + file):
 ```
-Bash: node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" graphify status 2>/dev/null
-  → Error or enabled:false → graphify: not_configured
-  → enabled:true → check graphify-out/graph.json exists
-                   Absent  → graphify: unavailable
-                   Present → graphify: available
+Bash: node -e "try{const c=JSON.parse(require('fs').readFileSync('.design/config.json','utf8'));process.stdout.write(String(c.graphify?.enabled===true))}catch{process.stdout.write('false')}"
+  → false → graphify: not_configured
+  → true  → Bash: node bin/gdd-graph status --format json
+                   → { configured: true, exists: false } → graphify: unavailable
+                   → { configured: true, exists: true }  → graphify: available
 ```
 
 **pencil-dev** (file probe):

package/skills/figma-extract/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: gdd-figma-extract
+description: Off-context Figma design-system extraction into a compact local digest (DESIGN.md + tokens.json + components.json). Pulls the file via the Figma REST API and digests it without the raw JSON ever entering the model context.
+---
+
+# gdd-figma-extract
+
+Pull a whole Figma design system into a compact, queryable local digest — **without** the raw JSON ever entering Claude context. The heavy lifting runs in tested `.cjs` tools; the model reads only the digest outputs.
+
+## Usage
+
+```
+/gdd:figma-extract <file-key-or-url>                  # full design-system digest
+/gdd:figma-extract <file-key-or-url> --component Button  # ~500-token single-component slice
+```
+
+`<file-key-or-url>` is a Figma file URL (`https://www.figma.com/file/<key>/…` or `/design/<key>/…`) or a bare file key.
+
+## Behavior
+
+1. **Preflight (D-10).** Confirm `FIGMA_TOKEN` is set in the environment:
+   ```
+   node -e "process.exit(process.env.FIGMA_TOKEN||process.env.FIGMA_PERSONAL_ACCESS_TOKEN?0:1)"
+   ```
+   If unset, tell the user to `export FIGMA_TOKEN=figd_…` (from https://www.figma.com/developers/api#access-tokens). The token comes from the environment **only** — never ask the user to paste it into a file or the chat, and never echo it back.
+
+2. **Stage 1 — pull.** Pull the file's REST endpoints into the gitignored raw cache (D-09):
+   ```
+   node scripts/lib/figma-extract/pull.cjs "<file-key-or-url>"
+   ```
+   This caches to `.figma-extract-cache/raw/<file-key>/` and skips re-pulling when Figma's `version` is unchanged (D-11). Add `--force` to bypass the cache, `--out <dir>` to relocate the cache. The tool prints a JSON summary (endpoints, bytes, cached) on stdout — the raw bodies stay on disk.
+
+3. **Stage 2 — plugin sync (OPTIONAL, Path C).** Only when the design tokens live in Figma Variables that the REST API cannot return (non-Enterprise plans → the pull summary shows `variables` skipped) and the user wants token coverage:
+   ```
+   node scripts/lib/figma-extract/receiver.cjs --out .figma-extract-cache/raw/<file-key>
+   ```
+   This binds `127.0.0.1:5179` (D-06). Tell the user to run the dev-installed **"GDD Sync"** plugin in Figma and click **"Export to GDD"** — see `figma-plugin/README.md` for the one-time dev-install. The receiver writes `variables.json` into the cache and exits on receipt or timeout. Skip this stage entirely for design systems whose tokens already come through the REST pull.
+
+4. **Stage 3 — digest.** Transform the cache into the compact digest:
+   ```
+   node scripts/lib/figma-extract/digest.cjs --raw .figma-extract-cache/raw/<file-key> --out .figma-extract-cache/digest
+   ```
+   This writes `DESIGN.md`, `tokens.json`, and `components.json`. Add `--prefer-styles` to invert the token priority to styles-first (D-04). Add `--component <name>` (D-08) to emit a single-component slice instead of the full digest.
+
+5. **Read the digest.** Open **only** `.figma-extract-cache/digest/DESIGN.md` (plus `tokens.json` / `components.json` when you need structured data). For a single component, pass `--component <name>` in Stage 3 and read the ~500-token slice instead of the full ~16K-token spec.
+
+## Required Reading
+
+- `.figma-extract-cache/digest/DESIGN.md` — the compact human/LLM-readable spec
+- `.figma-extract-cache/digest/tokens.json` — resolved design tokens (when structured token data is needed)
+- `.figma-extract-cache/digest/components.json` — components with variants/props/defaults (when structured component data is needed)
+
+## Notes
+
+- Two-stage pipeline (D-01): re-run Stage 3 against an existing cache without re-pulling. The digest does zero network calls.
+- The spike proved **0 Claude tokens** during extraction (898× compression, 223 MB → 254 KB). That property holds only because this skill never surfaces the raw cache.
+- Figma MCP remains the right tool for spot questions on a single live component; this skill is the cheaper path for whole-design-system workflows.
+
+## Do Not
+
+- **Do NOT read or `cat` the `raw/*.json` cache** (e.g. `.figma-extract-cache/raw/<file-key>/file.json`). It is tool-internal and often 100+ MB; loading it into context defeats the off-context guarantee (D-12). Read only the digest outputs above.
+- **Do not persist, log, echo, or print `FIGMA_TOKEN`** (D-10). It belongs in the environment only — never write it to a file, a commit, or chat output.
+
+## FIGMA-EXTRACT COMPLETE

package/skills/graphify/SKILL.md

@@ -19,30 +19,31 @@ Thin command wrapper around the GSD graphify tools integration.
 ## Behavior
 
 1. Read `.design/STATE.md` to check `graphify` status in `<connections>`.
-2. Check `graphify.enabled` in `.planning/config.json` via:
+2. Check `graphify.enabled` in `.design/config.json` via a direct file read (per D-09 — no `config-get` CLI subcommand):
    ```
-   node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" config-get graphify.enabled
+   node -e "try{const c=JSON.parse(require('fs').readFileSync('.design/config.json','utf8'));process.stdout.write(String(c.graphify?.enabled===true))}catch{process.stdout.write('false')}"
    ```
 3. If not enabled, print:
    ```
-   "Graphify is not enabled. Enable with: node gsd-tools.cjs config-set graphify.enabled true"
+   "Graphify is not enabled. Edit `.design/config.json` to set `graphify.enabled: true`."
    "Then run /gdd:graphify build to generate the knowledge graph."
    ```
    STOP.
-4. Execute the requested subcommand via GSD tools:
-   - build:  `node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" graphify build`
-   - query:  `node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" graphify query "<term>" --budget 2000`
-   - status: `node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" graphify status`
-   - diff:   `node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" graphify diff`
+4. Execute the requested subcommand via the native CLI:
+   - build:  `node bin/gdd-graph build`
+   - query:  `node bin/gdd-graph query "<term>" --budget 2000`
+   - status: `node bin/gdd-graph status`
+   - diff:   `node bin/gdd-graph diff`
 5. After `build` completes, update `.design/STATE.md` `<connections>`: `graphify: available`
 
 ## Required Reading
 
 - `.design/STATE.md` — for graphify status in `<connections>`
-- `.planning/config.json` — for `graphify.enabled` flag
+- `.design/config.json` — for `graphify.enabled` flag
 
 ## Notes
 
-- Graphify is optional. If the binary is not installed (`pip install graphifyy`), the build subcommand will fail with an install prompt.
+- Graphify is optional. The native CLI ships in this repo at `bin/gdd-graph` (no external install — Node only).
+- Graph is stored at `.design/graph/graph.json` (Ajv-validated against `scripts/lib/graph/schema.json`).
 - Graph covers source code (`src/`, `components/`). It does NOT index `.design/` artifacts by default.
 - Use `query` with node IDs from the graph schema: `component:<name>`, `token:color/<name>`, `decision:D-<nn>`, etc.

package/skills/health/SKILL.md

@@ -53,6 +53,16 @@ Health: 5 / 6 checks passing.
 ━━━━━━━━━━━━━━━━━━━━━
 ```
 
+## Figma-extract readiness (figma_extract)
+
+After the health table, the `gdd_health` MCP surface (`scripts/lib/health-mirror/index.cjs`) reports a `figma_extract` check so a user knows whether figma-extract is usable. The detail is one of three exact strings:
+
+- `figma extract: ready (token set)` — `FIGMA_TOKEN` (or `FIGMA_PERSONAL_ACCESS_TOKEN`) is present (status `ok`).
+- `figma extract: token missing` — no token env is set (status `warn`).
+- `figma extract: plugin sync needed for variables (Free tier detected)` — token present but a prior pull recorded a 403/skip on the Variables REST path, so run the plugin-sync step (status `warn`).
+
+Token PRESENCE only is detected (D-10) — the token value is never read, logged, or shown. The Free-tier signal is read from the local raw-pull cache only; no network call is made.
+
 ## Check MCP registration (gdd-mcp)
 
 After the health table, inspect whether `gdd-mcp` (Phase 27.7+) is registered with any installed harness and render a one-line status row. Dismissable via `.design/config.json#mcp_nudge=false`. Non-blocking: failure paths render `MCP server: unknown` rather than crash. Full detection procedure (dismissal check, detection via `scripts/lib/install/mcp-register.cjs`, row rendering for claude/codex/both/neither, fallback) lives in `./health-mcp-detection.md`.

package/skills/scan/scan-procedure.md

@@ -136,14 +136,15 @@ Write: chromatic: <status> to STATE.md <connections>
 
 ```
 Step G1 — Config check:
-  Bash: node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" graphify status
-  -> Error or { enabled: false } -> graphify: not_configured
-  -> { enabled: true }           -> proceed to Step G2
-
-Step G2 — Graph file check:
-  Bash: test -f graphify-out/graph.json
-  -> Present -> graphify: available
-  -> Absent  -> graphify: unavailable
+  Bash: node -e "try{const c=JSON.parse(require('fs').readFileSync('.design/config.json','utf8'));process.stdout.write(String(c.graphify?.enabled===true))}catch{process.stdout.write('false')}"
+  -> false -> graphify: not_configured
+  -> true  -> proceed to Step G2
+
+Step G2 — Graph file check (status JSON):
+  Bash: node bin/gdd-graph status --format json
+  -> { configured: true, exists: true, ... }  -> graphify: available
+  -> { configured: false, exists: false } or  -> graphify: unavailable
+     { exists: false }
 
 Write: graphify: <status> to STATE.md <connections>
 ```

package/agents/gdd-graphify-sync.md

@@ -1,110 +0,0 @@
----
-name: gdd-graphify-sync
-description: "Feeds the Graphify knowledge graph from .design/intel/ slices. Converts intel store graph.json nodes and edges into Graphify-compatible format and upserts them. Run after gdd-intel-updater to keep the semantic graph current."
-tools: Bash, Read, Write
-color: green
-default-tier: haiku
-tier-rationale: "Sync operation is deterministic JSON → graph DB — cheap Haiku is enough"
-parallel-safe: false
-typical-duration-seconds: 20
-reads-only: false
-writes:
-  - .design/intel/graph.json
----
-
-@reference/shared-preamble.md
-
-# gdd-graphify-sync
-
-**Role:** Bridge between the flat intel store and the Graphify semantic knowledge graph. Reads `graph.json` from the intel store and upserts nodes/edges into Graphify using the `gsd-tools.cjs graphify` CLI.
-
-## When to invoke
-
-- After `gdd-intel-updater` completes (intel store updated)
-- After a phase plan that adds new skill/agent/reference files
-- When semantic graph queries return stale results
-
-## Protocol
-
-### Step 1 — Check intel store graph slice
-
-```bash
-ls .design/intel/graph.json 2>/dev/null && echo "ready" || echo "missing"
-```
-
-If missing: print "Intel store graph.json not found — run node scripts/build-intel.cjs --force first." and stop.
-
-### Step 2 — Check Graphify availability
-
-```bash
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" graphify status 2>/dev/null | head -5
-```
-
-If Graphify is unavailable or returns an error: print "Graphify unavailable — skipping sync. Intel store remains the primary lookup source." and stop gracefully (exit 0, do not fail).
-
-### Step 3 — Read graph.json
-
-Read `.design/intel/graph.json`. Extract `nodes` and `edges` arrays.
-
-### Step 4 — Upsert nodes
-
-For each node in `nodes`:
-
-```bash
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" graphify upsert-node \
-  --id "<node.id>" \
-  --type "<node.type>" \
-  --label "<node.name>" \
-  --source "gdd-intel-store"
-```
-
-Batch in groups of 20 to avoid CLI argument limits. Report total nodes upserted.
-
-### Step 5 — Upsert edges
-
-For each edge in `edges`:
-
-```bash
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" graphify upsert-edge \
-  --from "<edge.from>" \
-  --to "<edge.to>" \
-  --kind "<edge.kind>" \
-  --source "gdd-intel-store"
-```
-
-Batch in groups of 20. Report total edges upserted.
-
-### Step 6 — Verify sync
-
-```bash
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" graphify status
-```
-
-Print the status response. Report node/edge counts in Graphify vs intel store.
-
-### Step 7 — Summary
-
-```
-━━━ Graphify sync complete ━━━
-Nodes upserted:  <N>
-Edges upserted:  <M>
-Graphify status: <status line>
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-## Required reading (conditional)
-
-@.design/intel/graph.json (if present)
-@.design/intel/files.json (if present)
-
-## GRAPHIFY-SYNC COMPLETE
-
-## Record
-
-At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
-
-```json
-{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
-```
-
-Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.