@hegemonart/get-design-done 1.45.0 → 1.47.0

package/reference/skill-metadata.md

@@ -0,0 +1,117 @@
+---
+name: skill-metadata
+type: meta-rules
+version: 1.0.0
+phase: 46
+tags: [skill, metadata, frontmatter, single-source-of-truth, generator, description-budget]
+last_updated: 2026-06-02
+---
+
+# Skill Metadata Single Source of Truth
+
+`scripts/lib/manifest/skills.json` is the one place skill frontmatter is authored. A
+generator projects it onto every `source/skills/<id>/SKILL.md`, the build step compiles
+those into the shipped trees, and CI gates keep the three copies identical. This doc
+explains the file, the generator, and the description budget. For the structural rules a
+SKILL.md body must follow (line cap, progressive disclosure, frontmatter required fields),
+see `./skill-authoring-contract.md`.
+
+## What skills.json is
+
+The file is a JSON object: a `schema_version` integer and a `skills` array. Each array
+element is one skill record. Only `name` is required (it must equal the
+`source/skills/<id>/` directory name); every other field is optional and omitted when it
+has no value.
+
+```json
+{
+  "schema_version": 1,
+  "skills": [
+    {
+      "name": "health",
+      "description": "Reports .design/ artifact health - staleness, missing files, token drift, broken state transitions.",
+      "tools": "Read, Bash, Glob, Grep, mcp__gdd_state__get",
+      "disable_model_invocation": true
+    }
+  ]
+}
+```
+
+Recognized record fields: `name`, `description`, `argument_hint`, `tools`,
+`user_invocable`, `disable_model_invocation`, `frontmatter_name` (the `name:` value when it
+is not the default `gdd-<id>`), `extra_frontmatter` (see below), plus `registered_in_phase`
+and `aliases`, which live only in the manifest and never round-trip to frontmatter. The
+schema at `scripts/lib/manifest/schemas/skills.schema.json` validates the shape.
+
+## The build chain
+
+Metadata flows in one direction, and a `*:check` gate guards each hop:
+
+```text
+skills.json
+  -> generate-skill-frontmatter      (npm run generate:skill-frontmatter)
+  -> source/skills/<id>/SKILL.md
+  -> build:skills                     (npm run build:skills)
+  -> skills/  +  dist/claude-code/
+```
+
+`scripts/generate-skill-frontmatter.cjs` rewrites only the frontmatter block of each
+`SKILL.md`, never the markdown body. It has three modes:
+
+- forward (no flag): manifest to frontmatter. The default.
+- `--extract`: the reverse direction, reading current frontmatter back into `skills.json`
+  to seed or refresh the source of truth. Idempotent with forward.
+- `--check`: the CI drift gate. It writes nothing and exits non-zero when any committed
+  frontmatter differs from what the manifest would generate.
+
+`scripts/build-skills.cjs` then propagates `source/skills/` into the committed `skills/`
+tree and `dist/claude-code/`; its own check mode asserts that the built output equals the
+committed output. So the contract is: edit `skills.json`, regenerate, build. Never
+hand-edit a managed frontmatter line in `SKILL.md`, because the drift gate will fail.
+
+## Managed vs preserved fields
+
+The generator owns six frontmatter keys and emits them in this canonical order whenever the
+record carries a value:
+
+1. `name`
+2. `description`
+3. `argument-hint`
+4. `tools`
+5. `user-invocable`
+6. `disable-model-invocation`
+
+String values for `description` and `argument-hint` are always double-quoted on emit, so
+quoting stays uniform across every skill. Anything outside these six keys is not managed.
+The generator carries it verbatim in the record's `extra_frontmatter` array and re-emits it
+after the managed block. The `quality-gate` skill is the working example: its `color`,
+`model`, `default-tier`, `size_budget`, `parallel-safe`, `typical-duration-seconds`,
+`reads-only`, and multi-line `writes:` block all live in `extra_frontmatter` and survive
+every regeneration untouched.
+
+## Description budget
+
+Every `description` must be at least 20 and at most 1024 characters. Two validators enforce
+the ceiling in CI:
+
+- `scripts/validate-skill-length.cjs` treats `DESC_MAX = 1024` as a blocker (it also blocks
+  under 20 characters as under-specification) and is the Phase 28.5 authoring-contract gate.
+- `scripts/lint-agentskills-spec.cjs` rule R4 applies the same 1024-character hard cap from
+  the agentskills.io spec angle, and warns past 200 characters.
+
+Phase 46 keeps that contract intact and wires `npm run lint:agentskills` in as its own
+explicit CI gate, so the spec lint runs on every change rather than only in-process via the
+doctor aggregator.
+
+## How pin consumes it
+
+The `pin`, `unpin`, and `list-pins` skills shipping in this phase read `description`,
+`argument_hint`, and `tools` straight from `skills.json`. That manifest is the pin metadata
+catalogue: the pin surface never live-scrapes a `SKILL.md` or re-derives a description at
+runtime. Reading one structured file keeps pin output consistent with what the generator
+emits, and the `aliases` array is reserved for the pin shortcuts those skills honor.
+
+## See also
+
+- `./skill-authoring-contract.md` for the SKILL.md line cap, description-format guidance,
+  required frontmatter fields, and progressive-disclosure rule.

package/scripts/lib/live/bandit-feed.cjs

@@ -0,0 +1,64 @@
+'use strict';
+/**
+ * scripts/lib/live/bandit-feed.cjs — Phase 47 (Live Mode) → Phase 38 design-arms bridge.
+ *
+ * When a user ACCEPTS a generated variant in /gdd:live, that acceptance is a weak,
+ * dev-time positive signal for the variant's design pattern. We fold it into the Phase 38
+ * `design_arms` posterior store as a WON observation — but at a discounted weight
+ * (DEV_TIME_WEIGHT = 0.5) because a developer's pick during authoring is advisory until
+ * real production A/B + user-research data arrives (Phase 38 D-03: advisory, never
+ * directive). The full posterior math + atomic persistence lives in the design-arms
+ * store; we only reuse it (variantKey + observe) and never duplicate the Beta math.
+ *
+ * Pure, dependency-free CommonJS. Persistence + `baseDir`/`armsPath` test-injection are
+ * inherited from the store. Ships in the npm package; requires only the in-repo store.
+ */
+
+const { variantKey, observe } = require('../ds-arms/design-arms-store.cjs');
+
+/**
+ * The dev-time acceptance weight. Half a win — a developer's accept is a discounted,
+ * advisory signal (Phase 38 D-03) until production user-outcome data shifts the arm.
+ */
+const DEV_TIME_WEIGHT = 0.5;
+
+/**
+ * Record an accepted Live Mode variant as a discounted WON observation on its design arm.
+ *
+ * @param {object} args
+ * @param {string} args.componentType   The component class (e.g. 'button', 'card').
+ * @param {string|object} args.pattern  The variant's design pattern (string or object;
+ *                                       hashed to the arm key via the store's variantKey).
+ * @param {string} [args.label]         Human-readable arm label, stored on first observe.
+ * @param {number} [args.weight]        Override the dev-time weight (defaults to DEV_TIME_WEIGHT).
+ * @param {string} [args.projectRoot]   Repo root — forwarded to the store as `baseDir` so the
+ *                                       arms file resolves under it (testable / hermetic).
+ * @param {string} [args.armsPath]      Explicit arms-file path override (forwarded to the store).
+ * @returns {object} The updated arm posterior (as returned by the store's observe()).
+ */
+function recordAccepted(args = {}) {
+  const { componentType, pattern, label, projectRoot, armsPath } = args;
+  if (typeof componentType !== 'string' || componentType.length === 0) {
+    throw new TypeError('recordAccepted: componentType is required (non-empty string)');
+  }
+  if (pattern == null) {
+    throw new TypeError('recordAccepted: pattern is required');
+  }
+
+  const weight = typeof args.weight === 'number' && args.weight > 0 ? args.weight : DEV_TIME_WEIGHT;
+  const hash = variantKey(componentType, pattern);
+
+  // Forward store options only when provided so the store keeps its own defaults otherwise.
+  const opts = {};
+  if (projectRoot) opts.baseDir = projectRoot;
+  if (armsPath) opts.armsPath = armsPath;
+
+  return observe(
+    componentType,
+    hash,
+    { won: true, weight, source: 'dev_time', label },
+    opts,
+  );
+}
+
+module.exports = { recordAccepted, DEV_TIME_WEIGHT };

package/scripts/lib/live/events.cjs

@@ -0,0 +1,86 @@
+'use strict';
+/**
+ * scripts/lib/live/events.cjs — Phase 47 (Live Mode) telemetry emitter.
+ *
+ * /gdd:live emits six event types across a session — start, pick, generate, accept,
+ * discard, end. This module is the single typed entry point: it validates the `type`
+ * against the closed LIVE_EVENT_TYPES allow-list (an unknown live type is a programmer
+ * error and is rejected) and appends the event via the in-repo event-chain emitter
+ * (scripts/lib/event-chain.cjs), the same write path router_pick uses.
+ *
+ * The emitted row carries the events.schema.json envelope fields verbatim
+ * (type / timestamp / sessionId / payload) so that, projected back to
+ * {type, timestamp, sessionId, payload}, it validates against the additive `live_*`
+ * seed types in reference/schemas/events.schema.json. `agent` + `outcome` are the
+ * chain emitter's two required fields; we set agent='live' and outcome=type.
+ *
+ * Pure, dependency-free CommonJS:
+ *   - NO top-level clock: the timestamp comes from an injectable `now` (default
+ *     `Date.now`), so tests are deterministic.
+ *   - `baseDir` is injectable (the emitter resolves the chain file relative to it),
+ *     so tests write to a temp project and never touch the repo's real stream.
+ *
+ * Ships in the npm package; requires only the in-repo event-chain emitter.
+ */
+
+const { appendChainEvent } = require('../event-chain.cjs');
+
+/** The six Live Mode event types. Closed allow-list — an unknown type is rejected. */
+const LIVE_EVENT_TYPES = Object.freeze([
+  'live_session_start',
+  'live_pick',
+  'live_generate',
+  'live_accept',
+  'live_discard',
+  'live_session_end',
+]);
+
+const LIVE_EVENT_TYPE_SET = new Set(LIVE_EVENT_TYPES);
+
+/**
+ * Emit a Live Mode telemetry event.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot   Repo root — injected as the emitter `baseDir` so the
+ *                                     chain file resolves under it (testable / hermetic).
+ * @param {string} args.type          One of LIVE_EVENT_TYPES. Anything else throws.
+ * @param {string} args.sessionId     Stable per-session id (correlates the event stream).
+ * @param {object} [args.payload]     Free-form, event-specific payload (MVP: opaque object).
+ * @param {(() => number)} [args.now] Injectable clock returning epoch ms (default Date.now).
+ * @returns {{event_id: string, type: string, timestamp: string, sessionId: string, payload: object}}
+ *          The projected envelope (also the shape that validates against events.schema.json).
+ */
+function emitLiveEvent(args = {}) {
+  const { projectRoot, type, sessionId, payload } = args;
+  const now = typeof args.now === 'function' ? args.now : Date.now;
+
+  if (!LIVE_EVENT_TYPE_SET.has(type)) {
+    throw new Error(
+      `emitLiveEvent: unknown live event type "${String(type)}". ` +
+        `Expected one of: ${LIVE_EVENT_TYPES.join(', ')}.`,
+    );
+  }
+  if (typeof sessionId !== 'string' || sessionId.length === 0) {
+    throw new TypeError('emitLiveEvent: sessionId is required (non-empty string)');
+  }
+
+  const timestamp = new Date(now()).toISOString();
+  const envelopePayload = payload && typeof payload === 'object' ? payload : {};
+
+  // Mirror the router_pick emit surface: write a chain row carrying the events-schema
+  // envelope fields verbatim. agent/outcome are the chain emitter's required fields.
+  const event_id = appendChainEvent({
+    baseDir: projectRoot,
+    agent: 'live',
+    outcome: type,
+    // Envelope fields preserved verbatim by appendChainEvent (opaque-extras pass-through):
+    type,
+    timestamp,
+    sessionId,
+    payload: envelopePayload,
+  });
+
+  return { event_id, type, timestamp, sessionId, payload: envelopePayload };
+}
+
+module.exports = { emitLiveEvent, LIVE_EVENT_TYPES };

package/scripts/lib/live/harness-mode.cjs

@@ -0,0 +1,93 @@
+'use strict';
+/**
+ * scripts/lib/live/harness-mode.cjs — Phase 47 (Live Mode) capability gate.
+ *
+ * `/gdd:live` drives the Claude Preview MCP at runtime (preview_inspect /
+ * preview_click / preview_eval / preview_screenshot). That whole loop is only
+ * available on a harness whose capability matrix reports `mcp_support: true`.
+ * Harnesses without MCP support cannot inject the runtime or read picks back, so
+ * live mode degrades to a screenshot-only experience on them.
+ *
+ * This module is the single source of truth for that gate. It reads the canonical
+ * harness record (scripts/lib/manifest/harnesses.cjs, a typed re-export of
+ * harnesses.json) and projects each harness onto one of two live-mode strings:
+ *
+ *   'puppeteer' — full live mode: the harness has mcp_support, the skill probes
+ *                 Preview, injects scripts/lib/live/runtime.cjs, and hot-swaps
+ *                 variants in place. (Named for the Preview MCP's Playwright /
+ *                 puppeteer-class browser driver, not a bundled dependency: there
+ *                 is NO bundled puppeteer; the skill drives the MCP.)
+ *   'degraded'  — screenshot-only: no mcp_support, so no live injection. The skill
+ *                 falls back to generating variants and capturing static
+ *                 screenshots, and says so up front.
+ *
+ * Design constraints (mirror the other scripts/lib/live/* modules):
+ *   - Pure, dependency-free apart from the manifest re-export. No fs, no network,
+ *     no Date / Math.random. Cross-platform (no path work, no OS calls).
+ *   - The harness list is injectable so tests can pass a fixture; it defaults to
+ *     the real manifest.
+ *
+ * Exports:
+ *   - liveModeFor(harnessId, harnesses?) -> 'puppeteer' | 'degraded'
+ *   - degradedHarnesses(harnesses?)      -> string[] of ids in degraded mode
+ *   - isMcpSupported(harnessId, harnesses?) -> boolean
+ *   - MODE_FULL / MODE_DEGRADED          -> the two mode string constants
+ */
+
+const MODE_FULL = 'puppeteer';
+const MODE_DEGRADED = 'degraded';
+
+/** Lazily resolve the default harness list (the typed re-export of harnesses.json). */
+function defaultHarnesses() {
+  return require('../manifest/harnesses.cjs');
+}
+
+/** Find a harness record by id in a list. Returns undefined when absent. */
+function findHarness(harnessId, harnesses) {
+  const list = Array.isArray(harnesses) ? harnesses : defaultHarnesses();
+  return list.find((h) => h && h.id === harnessId);
+}
+
+/**
+ * True when the named harness reports `capability_matrix.mcp_support === true`.
+ * Unknown harness ids and harnesses missing the flag are treated as false (no
+ * MCP -> no live injection).
+ */
+function isMcpSupported(harnessId, harnesses) {
+  const h = findHarness(harnessId, harnesses);
+  return Boolean(h && h.capability_matrix && h.capability_matrix.mcp_support === true);
+}
+
+/**
+ * Live mode for a harness: 'puppeteer' when mcp_support is true, else 'degraded'.
+ * An unknown harness id degrades (fail safe to screenshot-only).
+ *
+ * @param {string} harnessId
+ * @param {Array=} harnesses  Optional injected list; defaults to the manifest.
+ * @returns {'puppeteer'|'degraded'}
+ */
+function liveModeFor(harnessId, harnesses) {
+  return isMcpSupported(harnessId, harnesses) ? MODE_FULL : MODE_DEGRADED;
+}
+
+/**
+ * The ids of every harness currently in degraded (screenshot-only) live mode,
+ * in manifest order.
+ *
+ * @param {Array=} harnesses  Optional injected list; defaults to the manifest.
+ * @returns {string[]}
+ */
+function degradedHarnesses(harnesses) {
+  const list = Array.isArray(harnesses) ? harnesses : defaultHarnesses();
+  return list
+    .filter((h) => h && h.id && !isMcpSupported(h.id, list))
+    .map((h) => h.id);
+}
+
+module.exports = {
+  liveModeFor,
+  degradedHarnesses,
+  isMcpSupported,
+  MODE_FULL,
+  MODE_DEGRADED,
+};

package/scripts/lib/live/postcheck.cjs

@@ -0,0 +1,158 @@
+'use strict';
+/**
+ * scripts/lib/live/postcheck.cjs — Phase 47 (Live Mode) variant post-check.
+ *
+ * After /gdd:live generates a design variant, we run that variant's source through the
+ * in-repo gdd-detect engine (Phase 41) and surface its anti-pattern findings on the
+ * variant card. Per the Live Mode spec, an `error`-severity finding is FLAGGED but NOT
+ * auto-rejected — the human still chooses; the detector is advisory at dev-time. So
+ * `autoReject` is ALWAYS false; we only surface counts + a compact card summary.
+ *
+ * Pure, dependency-free CommonJS. We reuse the detect engine's `scanContent` +`RULES`
+ * (NOT a CLI shell-out, NOT a temp-file write) so post-checking a generated variant is
+ * fully in-memory and hermetically testable. The engine is the single source of truth
+ * for the finding shape ({ruleId, category, name, severity, file, line, column, match,
+ * references}); we never reimplement rule matching.
+ *
+ * Ships in the npm package (scripts/lib/** is in package.json `files`), so it requires
+ * only the in-repo detect engine — no runtime dependency, no network, no optional dep.
+ */
+
+const path = require('node:path');
+const { scanContent, run, RULES } = require('../detect/engine.cjs');
+
+/**
+ * Normalize the caller's `files`/`content` input into a list of
+ * `{ path, content, ext }` units to scan in-memory.
+ *
+ * Accepts either:
+ *   - `content`: a raw string (single anonymous unit), or
+ *   - `files`: an array of `{ path, content }` (or `{ name, content }`) units, or
+ *              an object map of `{ "<path>": "<content>" }`.
+ *
+ * @param {{files?: any, content?: string}} input
+ * @returns {{path: string, content: string, ext: string}[]}
+ */
+function normalizeUnits(input) {
+  const units = [];
+  if (input && typeof input.content === 'string') {
+    const p = input.path || input.file || 'variant';
+    units.push({ path: p, content: input.content, ext: path.extname(p).toLowerCase() });
+  }
+  const files = input && input.files;
+  if (Array.isArray(files)) {
+    for (const f of files) {
+      if (!f) continue;
+      if (typeof f === 'string') continue; // a bare path with no content is not scannable in-memory
+      const p = f.path || f.name || f.file || 'variant';
+      const content = typeof f.content === 'string' ? f.content : '';
+      units.push({ path: p, content, ext: path.extname(p).toLowerCase() });
+    }
+  } else if (files && typeof files === 'object') {
+    for (const p of Object.keys(files)) {
+      const content = typeof files[p] === 'string' ? files[p] : '';
+      units.push({ path: p, content, ext: path.extname(p).toLowerCase() });
+    }
+  }
+  return units;
+}
+
+/**
+ * Post-check a generated variant against the gdd-detect anti-pattern rule set.
+ *
+ * Prefers an in-memory scan of the supplied variant source via the detect engine's
+ * `scanContent`. When NO inline content is supplied but a `projectRoot` is given,
+ * falls back to the documented programmatic engine form `run(projectRoot)` so the
+ * caller can still post-check files already written to disk.
+ *
+ * @param {object} args
+ * @param {string} [args.projectRoot]  Repo root — used for the on-disk fallback and as the
+ *                                      `cwd` so finding `file` paths are repo-relative.
+ * @param {Array|object} [args.files]  Variant files: `[{path, content}]` or `{ "<path>": "<content>" }`.
+ * @param {string} [args.content]      A single raw variant source string.
+ * @returns {{findings: object[], errorCount: number, warnCount: number, autoReject: boolean}}
+ */
+function postCheckVariant(args = {}) {
+  const { projectRoot } = args;
+  const units = normalizeUnits(args);
+
+  let findings = [];
+  if (units.length > 0) {
+    const cwd = projectRoot || process.cwd();
+    for (const u of units) {
+      // Make the reported `file` repo-relative when projectRoot is known, mirroring the
+      // engine's own relativization in run().
+      let rel = u.path;
+      if (projectRoot && path.isAbsolute(u.path)) {
+        rel = path.relative(cwd, u.path).split(path.sep).join('/') || u.path;
+      }
+      const hits = scanContent(u.content, { path: rel, ext: u.ext }, RULES);
+      findings.push(...hits);
+    }
+    // Match the engine's deterministic ordering (file, line, column, ruleId).
+    findings.sort(
+      (a, b) =>
+        a.file.localeCompare(b.file) ||
+        a.line - b.line ||
+        a.column - b.column ||
+        a.ruleId.localeCompare(b.ruleId),
+    );
+  } else if (projectRoot) {
+    // No inline content — fall back to the documented programmatic engine form against
+    // files already on disk under projectRoot.
+    const result = run(projectRoot, { cwd: projectRoot });
+    findings = result.findings;
+  }
+
+  let errorCount = 0;
+  let warnCount = 0;
+  for (const f of findings) {
+    if (f.severity === 'error') errorCount += 1;
+    else warnCount += 1;
+  }
+
+  // Spec D: error-severity is flagged, NOT auto-rejected. autoReject is always false.
+  return { findings, errorCount, warnCount, autoReject: false };
+}
+
+/**
+ * Compact, single-line summary of a findings array for a variant card.
+ * Always returns a string (never null/undefined) so the skill can render it verbatim.
+ *
+ *   []                                  → "clean — no anti-patterns"
+ *   [1 error, 2 warn]                   → "2 issue(s): 1 error, 2 warn — BAN-06, BAN-01, BAN-08"
+ *
+ * Rule ids are de-duplicated and listed in first-seen order, capped so the card stays compact.
+ *
+ * @param {object[]} findings
+ * @returns {string}
+ */
+function summarizeForCard(findings) {
+  const list = Array.isArray(findings) ? findings : [];
+  if (list.length === 0) return 'clean — no anti-patterns';
+
+  let errors = 0;
+  let warns = 0;
+  const ids = [];
+  const seen = new Set();
+  for (const f of list) {
+    if (f && f.severity === 'error') errors += 1;
+    else warns += 1;
+    const id = f && f.ruleId;
+    if (id && !seen.has(id)) {
+      seen.add(id);
+      ids.push(id);
+    }
+  }
+
+  const MAX_IDS = 5;
+  const shownIds = ids.slice(0, MAX_IDS);
+  const idTail = ids.length > MAX_IDS ? `, +${ids.length - MAX_IDS} more` : '';
+  const parts = [];
+  if (errors) parts.push(`${errors} error`);
+  if (warns) parts.push(`${warns} warn`);
+
+  return `${list.length} issue(s): ${parts.join(', ')} — ${shownIds.join(', ')}${idTail}`;
+}
+
+module.exports = { postCheckVariant, summarizeForCard, normalizeUnits };