@hegemonart/get-design-done 1.27.6 → 1.28.0

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

@@ -0,0 +1,381 @@
+{
+  "$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).",
+  "type": "object",
+  "properties": {
+    "tools": {
+      "type": "object",
+      "description": "Per-tool input/output schemas keyed by tool name. Exactly 12 entries (D-03 hard cap).",
+      "additionalProperties": false,
+      "properties": {
+        "gdd_status": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["input", "output"],
+          "properties": {
+            "input": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {}
+            },
+            "output": {
+              "type": "object",
+              "required": ["phase", "branch", "last_decisions", "last_completed_plans", "blocker_count"],
+              "properties": {
+                "phase": { "type": ["string", "null"] },
+                "branch": { "type": ["string", "null"] },
+                "last_decisions": { "type": "array", "items": { "type": "object" } },
+                "last_completed_plans": { "type": "array", "items": { "type": "object" } },
+                "blocker_count": { "type": "integer", "minimum": 0 }
+              }
+            }
+          }
+        },
+        "gdd_phase_current": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["input", "output"],
+          "properties": {
+            "input": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {}
+            },
+            "output": {
+              "type": "object",
+              "required": ["phase", "stage", "task_progress", "status"],
+              "properties": {
+                "phase": { "type": ["string", "null"] },
+                "stage": { "type": ["string", "null"] },
+                "task_progress": { "type": ["string", "null"] },
+                "status": { "type": ["string", "null"] }
+              }
+            }
+          }
+        },
+        "gdd_phases_list": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["input", "output"],
+          "properties": {
+            "input": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {}
+            },
+            "output": {
+              "type": "object",
+              "required": ["phases"],
+              "properties": {
+                "phases": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "required": ["number", "name", "version", "checkbox_status"],
+                    "properties": {
+                      "number": { "type": "string" },
+                      "name": { "type": "string" },
+                      "version": { "type": "string" },
+                      "checkbox_status": { "type": "string", "enum": ["shipped", "planned", "unknown"] }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "gdd_plans_list": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["input", "output"],
+          "properties": {
+            "input": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "phase": { "type": "string" }
+              }
+            },
+            "output": {
+              "type": "object",
+              "required": ["phase", "plans"],
+              "properties": {
+                "phase": { "type": ["string", "null"] },
+                "plans": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "required": ["id", "name", "status"],
+                    "properties": {
+                      "id": { "type": "string" },
+                      "name": { "type": "string" },
+                      "status": { "type": "string" }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "gdd_decisions_list": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["input", "output"],
+          "properties": {
+            "input": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "status": { "type": "string", "enum": ["locked", "tentative"] }
+              }
+            },
+            "output": {
+              "type": "object",
+              "required": ["decisions"],
+              "properties": {
+                "decisions": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "required": ["id", "text", "status"],
+                    "properties": {
+                      "id": { "type": "string" },
+                      "text": { "type": "string" },
+                      "status": { "type": "string" }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "gdd_intel_get": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["input", "output"],
+          "properties": {
+            "input": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["slice_id"],
+              "properties": {
+                "slice_id": { "type": "string", "minLength": 1 },
+                "shape": { "type": "array", "items": { "type": "string" } }
+              }
+            },
+            "output": {
+              "type": "object",
+              "required": ["slice_id", "data"],
+              "properties": {
+                "slice_id": { "type": "string" },
+                "data": { "type": "object" }
+              }
+            }
+          }
+        },
+        "gdd_telemetry_query": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["input", "output"],
+          "properties": {
+            "input": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "type": { "type": "string" },
+                "since": { "type": "string", "format": "date-time" },
+                "limit": { "type": "integer", "minimum": 1, "maximum": 10000 }
+              }
+            },
+            "output": {
+              "type": "object",
+              "required": ["events"],
+              "properties": {
+                "events": { "type": "array", "items": { "type": "object" } }
+              }
+            }
+          }
+        },
+        "gdd_cycle_recap": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["input", "output"],
+          "properties": {
+            "input": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "since_snapshot": { "type": "string" }
+              }
+            },
+            "output": {
+              "type": "object",
+              "required": ["since", "diff"],
+              "properties": {
+                "since": { "type": ["string", "null"] },
+                "diff": {
+                  "type": "object",
+                  "required": ["state_sections", "decisions_delta", "completed_plans_delta"],
+                  "properties": {
+                    "state_sections": { "type": "array", "items": { "type": "string" } },
+                    "decisions_delta": { "type": "integer" },
+                    "completed_plans_delta": { "type": "integer" }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "gdd_reflections_latest": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["input", "output"],
+          "properties": {
+            "input": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {}
+            },
+            "output": {
+              "type": "object",
+              "required": ["cycle", "path", "content_excerpt"],
+              "properties": {
+                "cycle": { "type": ["string", "null"] },
+                "path": { "type": ["string", "null"] },
+                "content_excerpt": { "type": "string", "maxLength": 4096 }
+              }
+            }
+          }
+        },
+        "gdd_learnings_digest": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["input", "output"],
+          "properties": {
+            "input": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "cycles": { "type": "integer", "minimum": 1, "maximum": 50 }
+              }
+            },
+            "output": {
+              "type": "object",
+              "required": ["digest", "cycles_included"],
+              "properties": {
+                "digest": { "type": "string", "maxLength": 5120 },
+                "cycles_included": { "type": "integer", "minimum": 0 }
+              }
+            }
+          }
+        },
+        "gdd_events_tail": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["input", "output"],
+          "properties": {
+            "input": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "type": { "type": "string" },
+                "limit": { "type": "integer", "minimum": 1, "maximum": 10000 }
+              }
+            },
+            "output": {
+              "type": "object",
+              "required": ["events"],
+              "properties": {
+                "events": { "type": "array", "items": { "type": "object" } }
+              }
+            }
+          }
+        },
+        "gdd_health": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["input", "output"],
+          "properties": {
+            "input": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {}
+            },
+            "output": {
+              "type": "object",
+              "required": ["checks"],
+              "properties": {
+                "checks": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "required": ["name", "status", "detail"],
+                    "properties": {
+                      "name": { "type": "string" },
+                      "status": { "type": "string", "enum": ["ok", "warn", "fail"] },
+                      "detail": { "type": "string" }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "ToolSchemaEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["input", "output"],
+      "properties": {
+        "input": {
+          "type": "object",
+          "description": "JSON Schema fragment describing the tool's input parameters."
+        },
+        "output": {
+          "type": "object",
+          "description": "JSON Schema fragment describing the tool's response envelope.",
+          "required": ["type"],
+          "properties": {
+            "type": { "type": "string", "enum": ["object"] }
+          }
+        }
+      }
+    },
+    "ToolError": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["code", "message", "kind"],
+      "properties": {
+        "code": { "type": "string", "minLength": 1 },
+        "message": { "type": "string", "minLength": 1 },
+        "kind": {
+          "type": "string",
+          "enum": ["validation", "state_conflict", "operation_failed", "unknown"]
+        },
+        "mcp_code": {
+          "type": "string",
+          "description": "Optional MCP-specific code (e.g. 'directory_not_found') projected by errorResponse() when an underlying NotFoundError carries a `code` property."
+        },
+        "context": {
+          "type": "object",
+          "additionalProperties": true
+        }
+      }
+    },
+    "ToolResponseEnvelope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["success"],
+      "properties": {
+        "success": { "type": "boolean" },
+        "data": { "type": "object" },
+        "error": { "$ref": "#/definitions/ToolError" }
+      }
+    }
+  }
+}

package/reference/style-vocabulary.md

@@ -16,6 +16,8 @@ This catalog gives two categories of agent a shared, unambiguous vocabulary for
 
 Style names in this file are preserved verbatim from the UUPM source to maintain ecosystem legibility. Do not rename or abbreviate styles when writing context files or audit reports.
 
+**See:** [`./proportion-systems.md`](./proportion-systems.md) for the whole-UI proportion system (4pt / 8pt / √2 baseline grids, modular relationships across type / spacing / sizing / radius) that the rows below reference when they call out "8pt spacing grid", "12-column grid", "section-level spacing (120–200px vertical rhythm)", and similar grid-anchored signatures.
+
 ---
 
 ## Style Table

package/reference/typography.md

@@ -35,6 +35,8 @@ Choose a ratio and base size. Common ratios:
 
 Never create a scale ad-hoc. Pick one ratio, generate the scale, use only values in the scale.
 
+**See:** [`./proportion-systems.md`](./proportion-systems.md) §Modular Relationships for how the type scale ties to spacing / sizing / radius scales — when one ratio drives all four scales the whole UI gains a single rhythm rather than four independently-tuned progressions.
+
 ---
 
 ## Line Height
@@ -228,6 +230,8 @@ Always include a non-variable fallback of the same family in the font stack:
 font-family: 'InterVariable', 'Inter', -apple-system, system-ui, sans-serif;
 ```
 
+**See:** [`./i18n.md`](./i18n.md) §Multi-Script Font Stacks for when a multi-script project should ship weighted-static fonts rather than a single variable font (some scripts ship as static-only families; mixing scripts in a single variable file is rarely viable).
+
 ---
 
 ## Micro-Typography

package/reference/visual-hierarchy-layout.md

@@ -75,6 +75,8 @@ The key discipline is intentionality. Asymmetry that emerges from neglect — un
 
 Rhythm in layout means that repetition creates a predictable visual beat that the eye can lock onto and traverse quickly. A card grid has rhythm. A consistent heading-body-space pattern has rhythm. Rhythm is not uniformity — it is the reliable expectation that similar content will appear in similar visual form. Break rhythm only to signal importance: a featured item in a grid that is twice the size says "this one matters."
 
+**See:** [`./composition.md`](./composition.md) §Visual-Weight Calculus for the `size × contrast × isolation × complexity` formula that quantifies why an asymmetric large/small pairing directs the eye toward the heavier element.
+
 ---
 
 ## Compositional Grids
@@ -96,6 +98,8 @@ Grids are not aesthetic choices — they are coordination mechanisms. A grid ali
 
 A baseline grid aligns text and element heights to a consistent vertical increment — typically 4px or 8px. Every element's height, padding, and margin should be a multiple of this increment. The baseline grid is what makes a layout feel "settled" rather than arbitrarily positioned, because every vertical decision relates to a shared rhythm. In practice, use 8px as the primary increment and 4px for sub-increments only (e.g., within a component's internal padding).
 
+**See:** [`./composition.md`](./composition.md) §Golden Ratio and Root Rectangles + §Focal-Point Construction for the pre-Gestalt compositional foundations (φ-grid, root rectangles, rule-of-thirds intersections) that complement the responsive-column / baseline-grid coordinations above.
+
 ---
 
 ## Figure-Ground Manipulation

package/scripts/install.cjs

@@ -62,6 +62,8 @@ 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.',
+    '  --no-register-mcp  Skip MCP registration (default behavior; included for symmetry).',
     '  --help, -h      Show this message',
     '',
     'Environment overrides (per-runtime):',
@@ -215,6 +217,46 @@ async function main() {
       );
     }
   }
+
+  // Phase 27.7 / Plan 27.7-04 — opt-in MCP registration (D-07).
+  // 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
+  // + graceful absent-CLI fallback handled inside registerMcp.
+  if (!uninstall && !dryRun && flags.has('--register-mcp')) {
+    try {
+      const { registerMcp } = require('./lib/install/mcp-register.cjs');
+      for (const harness of ['claude', 'codex']) {
+        try {
+          const result = registerMcp({ harness });
+          if (!result.detected) {
+            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',
+            );
+          }
+        } catch (err) {
+          process.stderr.write(
+            '[install] gdd-mcp registration error (' + harness + '): ' + (err && err.message ? err.message : err) + '\n',
+          );
+        }
+      }
+    } catch (e) {
+      // mcp-register lib not present (forward-compat) — silent skip.
+      process.stderr.write(
+        '[install] mcp-register lib unavailable: ' + (e && e.message ? e.message : e) + '\n',
+      );
+    }
+  }
 }
 
 // v1.27.1 — Plan 27-11: post-install nudge. Detects installed peer CLIs,

package/scripts/lib/gsd-health-mirror/index.cjs

@@ -0,0 +1,105 @@
+'use strict';
+// scripts/lib/gsd-health-mirror/index.cjs — Plan 27.7-02
+//
+// Pure read-only mirror of skills/health/SKILL.md's check surface.
+// NO subprocess spawn — just inspects 4 well-known files/dirs and
+// reports status. Used by the gdd_health MCP tool.
+//
+// Surface:
+//   async getHealthChecks(rootDir) → { checks: HealthCheck[] }
+//
+// The 4 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
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+function fileExists(p) {
+  try {
+    return fs.statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function dirExists(p) {
+  try {
+    return fs.statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+async function getHealthChecks(rootDir) {
+  const checks = [];
+
+  // 1. CLAUDE.md
+  {
+    const p = path.join(rootDir, 'CLAUDE.md');
+    const present = fileExists(p);
+    checks.push({
+      name: 'claude_md',
+      status: present ? 'ok' : 'warn',
+      detail: present ? p : 'CLAUDE.md not found at project root',
+    });
+  }
+
+  // 2. .planning/
+  {
+    const p = path.join(rootDir, '.planning');
+    const present = dirExists(p);
+    checks.push({
+      name: 'planning_dir',
+      status: present ? 'ok' : 'warn',
+      detail: present ? p : '.planning/ not found at project root',
+    });
+  }
+
+  // 3. .design/
+  {
+    const p = path.join(rootDir, '.design');
+    const present = dirExists(p);
+    checks.push({
+      name: 'design_dir',
+      status: present ? 'ok' : 'warn',
+      detail: present ? p : '.design/ not found at project root',
+    });
+  }
+
+  // 4. package.json — present + parseable
+  {
+    const p = path.join(rootDir, 'package.json');
+    if (!fileExists(p)) {
+      checks.push({
+        name: 'package_json',
+        status: 'warn',
+        detail: 'package.json not found at project root',
+      });
+    } else {
+      try {
+        const body = await fs.promises.readFile(p, 'utf8');
+        const parsed = JSON.parse(body);
+        const name = typeof parsed.name === 'string' ? parsed.name : '(unknown)';
+        const version = typeof parsed.version === 'string' ? parsed.version : '0.0.0';
+        checks.push({
+          name: 'package_json',
+          status: 'ok',
+          detail: name + '@' + version,
+        });
+      } catch (err) {
+        checks.push({
+          name: 'package_json',
+          status: 'fail',
+          detail: 'parse error: ' + (err && err.message ? err.message : String(err)),
+        });
+      }
+    }
+  }
+
+  return { checks };
+}
+
+module.exports = { getHealthChecks };

package/scripts/lib/gsd-health-mirror/index.d.cts

@@ -0,0 +1,14 @@
+// scripts/lib/gsd-health-mirror/index.d.cts — TypeScript ambient declarations
+// for the gsd-health-mirror CJS module. Plan 27.7-02.
+
+export interface HealthCheck {
+  name: string;
+  status: 'ok' | 'warn' | 'fail';
+  detail: string;
+}
+
+export interface HealthChecksResult {
+  checks: HealthCheck[];
+}
+
+export function getHealthChecks(rootDir: string): Promise<HealthChecksResult>;