@hegemonart/get-design-done 1.57.1 → 1.57.2

package/hooks/update-check.cjs

@@ -0,0 +1,511 @@
+#!/usr/bin/env node
+/**
+ * get-design-done — update check (Phase 13.3) — Node port
+ *
+ * Original: hooks/update-check.sh
+ * SessionStart hook. Silent-on-failure by policy (D-04): exits 0 on every error path.
+ * 24h-cached unauthenticated GET of /releases/latest. Renders .design/update-available.md
+ * only when a newer version exists AND it is not dismissed AND stage-guard allows.
+ *
+ * Sourcing guard (Node equivalent): main() runs only when require.main === module.
+ * Helpers are exported for tests. This mirrors the bash `[ "${BASH_SOURCE[0]}" = "$0" ]`
+ * pattern — sourcing the .sh in tests loads functions without side effects; requiring
+ * this .cjs likewise loads exports without running main.
+ *
+ * Non-obvious behaviors preserved:
+ *   - 4-segment semver tuple comparison (handles "v1.0.7.3" off-cadence builds).
+ *   - LATEST_TAG safety regex /^v?\d+\.\d+(\.\d+)*$/ before trusting fetched data.
+ *   - Body excerpt: stripped of control chars 0x00-0x08, 0x0B, 0x0C, 0x0E-0x1F and
+ *     double-quotes (prevents JSON read-back injection — body is display-only).
+ *   - C_DELTA allowlist gate (major|minor|patch|off-cadence|none → else "unknown").
+ *   - Atomic writes via .tmp.<pid> + rename for both cache and banner files.
+ *   - State stage suppression: plan|design|verify silences the banner.
+ *   - --refresh flag forces fresh fetch regardless of cache age.
+ *   - GDD_UPDATE_DEBUG=1 enables '[gdd update-check]' prefixed stderr logging.
+ *   - Cache freshness: mtime < 24h ago (86400s).
+ *   - Plugin root: CLAUDE_PLUGIN_ROOT env override, else dirname(__dirname).
+ *   - Windows backslashes in PLUGIN_ROOT normalized to forward slashes.
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const https = require('node:https');
+const process = require('node:process');
+
+const CACHE_TTL_SECONDS = 86400; // 24h
+
+// ---- Logger (silent unless GDD_UPDATE_DEBUG=1) ----
+function log(...args) {
+  if (process.env.GDD_UPDATE_DEBUG === '1') {
+    process.stderr.write('[gdd update-check] ' + args.join(' ') + '\n');
+  }
+}
+
+// ---- Path helpers — derive paths from cwd + plugin root ----
+function getPluginRoot() {
+  let root = process.env.CLAUDE_PLUGIN_ROOT;
+  if (!root || root.length === 0) {
+    // dirname of __dirname == project root (hooks/.. == plugin root)
+    root = path.resolve(__dirname, '..');
+  }
+  return root.replace(/\\/g, '/');
+}
+
+function getPaths(cwd) {
+  const designDir = path.join(cwd || process.cwd(), '.design');
+  return {
+    designDir,
+    cache: path.join(designDir, 'update-cache.json'),
+    banner: path.join(designDir, 'update-available.md'),
+    config: path.join(designDir, 'config.json'),
+    state: path.join(designDir, 'STATE.md'),
+    pluginJson: path.join(getPluginRoot(), '.claude-plugin', 'plugin.json'),
+  };
+}
+
+// ---- Read current plugin version from .claude-plugin/plugin.json ----
+function readCurrentTag(pluginJsonPath) {
+  const p = pluginJsonPath || getPaths().pluginJson;
+  try {
+    if (!fs.existsSync(p)) return '';
+    const raw = fs.readFileSync(p, 'utf8');
+    const obj = JSON.parse(raw);
+    const v = obj && typeof obj.version === 'string' ? obj.version : '';
+    return v;
+  } catch (e) {
+    log('readCurrentTag failed:', e && e.message);
+    return '';
+  }
+}
+
+// ---- Semver normalizer: "v1.0.7" → [1,0,7,0]; "v1.0.7.3" → [1,0,7,3] ----
+// Returns 4-element array of non-negative integers. Sanitizes each segment to digits only.
+function normalizeSemver(input) {
+  if (input == null) return [0, 0, 0, 0];
+  let t = String(input);
+  if (t.startsWith('v')) t = t.slice(1);
+  // strip any -pre/-beta suffix after first hyphen
+  const hyphenIdx = t.indexOf('-');
+  if (hyphenIdx >= 0) t = t.slice(0, hyphenIdx);
+  const parts = t.split('.');
+  const out = [0, 0, 0, 0];
+  for (let i = 0; i < 4; i++) {
+    const seg = parts[i] != null ? String(parts[i]).replace(/[^0-9]/g, '') : '';
+    out[i] = seg.length === 0 ? 0 : parseInt(seg, 10);
+    if (!Number.isFinite(out[i])) out[i] = 0;
+  }
+  return out;
+}
+
+// ---- Classify delta: compare 4-segment tuples ----
+// Returns { state: 'newer'|'older'|'same', kind: 'major'|'minor'|'patch'|'off-cadence'|'none' }
+function classifyDelta(currentTag, latestTag) {
+  const cur = normalizeSemver(currentTag);
+  const lat = normalizeSemver(latestTag);
+  const kinds = ['major', 'minor', 'patch', 'off-cadence'];
+  for (let i = 0; i < 4; i++) {
+    if (lat[i] > cur[i]) return { state: 'newer', kind: kinds[i] };
+    if (lat[i] < cur[i]) return { state: 'older', kind: kinds[i] };
+  }
+  return { state: 'same', kind: 'none' };
+}
+
+// ---- Cache freshness: returns true if cache exists and mtime is < 24h ago ----
+function isCacheFresh(cachePath) {
+  try {
+    const st = fs.statSync(cachePath);
+    if (!st || !st.isFile()) return false;
+    const now = Math.floor(Date.now() / 1000);
+    const mtime = Math.floor(st.mtimeMs / 1000);
+    const age = now - mtime;
+    return age < CACHE_TTL_SECONDS;
+  } catch (e) {
+    return false;
+  }
+}
+
+// ---- Fetch latest release. Returns Promise<string> with raw body, or '' on failure. ----
+function fetchLatest() {
+  const url = 'https://api.github.com/repos/hegemonart/get-design-done/releases/latest';
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = (val) => {
+      if (done) return;
+      done = true;
+      resolve(val);
+    };
+    try {
+      const req = https.get(
+        url,
+        {
+          headers: {
+            Accept: 'application/vnd.github+json',
+            'User-Agent': 'gdd-update-check',
+          },
+          timeout: 3000,
+        },
+        (res) => {
+          // Follow one redirect (3xx). GitHub API rarely redirects but be defensive.
+          if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+            res.resume();
+            const redirected = https.get(
+              res.headers.location,
+              {
+                headers: {
+                  Accept: 'application/vnd.github+json',
+                  'User-Agent': 'gdd-update-check',
+                },
+                timeout: 3000,
+              },
+              (r2) => {
+                if (r2.statusCode < 200 || r2.statusCode >= 300) {
+                  r2.resume();
+                  log('fetch redirect status', r2.statusCode);
+                  return finish('');
+                }
+                const chunks = [];
+                r2.on('data', (c) => chunks.push(c));
+                r2.on('end', () => finish(Buffer.concat(chunks).toString('utf8')));
+                r2.on('error', (e) => {
+                  log('redirect read error', e && e.message);
+                  finish('');
+                });
+              }
+            );
+            redirected.on('error', (e) => {
+              log('redirect request error', e && e.message);
+              finish('');
+            });
+            redirected.on('timeout', () => {
+              try { redirected.destroy(); } catch (_) {}
+              finish('');
+            });
+            return;
+          }
+          if (res.statusCode < 200 || res.statusCode >= 300) {
+            res.resume();
+            log('fetch status', res.statusCode);
+            return finish('');
+          }
+          const chunks = [];
+          res.on('data', (c) => chunks.push(c));
+          res.on('end', () => finish(Buffer.concat(chunks).toString('utf8')));
+          res.on('error', (e) => {
+            log('read error', e && e.message);
+            finish('');
+          });
+        }
+      );
+      req.on('timeout', () => {
+        try { req.destroy(); } catch (_) {}
+        log('timeout');
+        finish('');
+      });
+      req.on('error', (e) => {
+        log('request error', e && e.message);
+        finish('');
+      });
+    } catch (e) {
+      log('fetch threw', e && e.message);
+      finish('');
+    }
+  });
+}
+
+// ---- Extract tag_name from release JSON. Returns '' on failure. ----
+function extractTag(raw) {
+  if (!raw || typeof raw !== 'string') return '';
+  try {
+    const obj = JSON.parse(raw);
+    return obj && typeof obj.tag_name === 'string' ? obj.tag_name : '';
+  } catch (e) {
+    log('extractTag parse error:', e && e.message);
+    return '';
+  }
+}
+
+// ---- Extract body from release JSON. Slices to 500 chars, strips ctrl chars + double-quotes. ----
+function extractBody(raw) {
+  if (!raw || typeof raw !== 'string') return '';
+  try {
+    const obj = JSON.parse(raw);
+    let body = obj && typeof obj.body === 'string' ? obj.body : '';
+    body = body.slice(0, 500);
+    // Strip control chars: 0x00-0x08, 0x0B, 0x0C, 0x0E-0x1F
+    // eslint-disable-next-line no-control-regex
+    body = body.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F]/g, '');
+    // Strip double-quotes (display-only, prevents JSON read-back injection)
+    body = body.replace(/"/g, '');
+    return body;
+  } catch (e) {
+    log('extractBody parse error:', e && e.message);
+    return '';
+  }
+}
+
+// ---- Read .design/STATE.md stage field. Returns "brief"|"explore"|"plan"|"design"|"verify"|"" ----
+function readStateStage(statePath) {
+  const p = statePath || getPaths().state;
+  try {
+    if (!fs.existsSync(p)) return '';
+    const raw = fs.readFileSync(p, 'utf8');
+    const lines = raw.split(/\r?\n/);
+    for (const line of lines) {
+      const m = line.match(/^stage:\s*"?([^"\s]+)"?/);
+      if (m) return m[1];
+    }
+    return '';
+  } catch (e) {
+    log('readStateStage failed:', e && e.message);
+    return '';
+  }
+}
+
+// ---- Read .design/config.json#update_dismissed. Returns tag string or ''. ----
+function readDismissed(configPath) {
+  const p = configPath || getPaths().config;
+  try {
+    if (!fs.existsSync(p)) return '';
+    const raw = fs.readFileSync(p, 'utf8');
+    try {
+      const obj = JSON.parse(raw);
+      const v = obj && typeof obj.update_dismissed === 'string' ? obj.update_dismissed : '';
+      return v;
+    } catch (_) {
+      // Fall back to regex extraction if JSON is malformed — matches bash grep behavior.
+      const m = raw.match(/"update_dismissed"\s*:\s*"([^"]+)"/);
+      return m ? m[1] : '';
+    }
+  } catch (e) {
+    log('readDismissed failed:', e && e.message);
+    return '';
+  }
+}
+
+// ---- Validate that a tag string is a safe semver before trusting it (CR-02). ----
+function isSafeSemverTag(tag) {
+  if (!tag || typeof tag !== 'string') return false;
+  return /^v?\d+\.\d+(\.\d+)*$/.test(tag);
+}
+
+// ---- Atomic write: write to .tmp.<pid> then rename. On any error, attempt cleanup. ----
+function atomicWrite(targetPath, contents) {
+  const tmp = `${targetPath}.tmp.${process.pid}`;
+  try {
+    fs.writeFileSync(tmp, contents);
+    fs.renameSync(tmp, targetPath);
+    return true;
+  } catch (e) {
+    log('atomicWrite failed:', e && e.message);
+    try { fs.unlinkSync(tmp); } catch (_) {}
+    return false;
+  }
+}
+
+// ---- Build the JSON cache contents. Body excerpt is JSON-string-escaped. ----
+function buildCacheJson({ checkedAt, currentTag, latestTag, deltaKind, isNewer, bodyExcerpt }) {
+  // Match the bash output format closely: newlines and 2-space indent.
+  // JSON.stringify the body to handle escape sequences cleanly.
+  const escapedBody = JSON.stringify(bodyExcerpt || '').slice(1, -1); // strip outer quotes
+  const lines = [
+    '{',
+    `  "checked_at": ${checkedAt},`,
+    `  "current_tag": "${currentTag}",`,
+    `  "latest_tag": "${latestTag}",`,
+    `  "delta": "${deltaKind}",`,
+    `  "is_newer": ${isNewer ? 'true' : 'false'},`,
+    `  "changelog_excerpt": "${escapedBody}"`,
+    '}',
+    '',
+  ];
+  return lines.join('\n');
+}
+
+// ---- Read cache and extract the four fields the main flow consumes. ----
+function readCache(cachePath) {
+  try {
+    const raw = fs.readFileSync(cachePath, 'utf8');
+    try {
+      const obj = JSON.parse(raw);
+      return {
+        latest_tag: typeof obj.latest_tag === 'string' ? obj.latest_tag : '',
+        delta: typeof obj.delta === 'string' ? obj.delta : '',
+        is_newer: obj.is_newer === true,
+        changelog_excerpt:
+          typeof obj.changelog_excerpt === 'string'
+            ? obj.changelog_excerpt.replace(/\\n/g, '\n')
+            : '',
+      };
+    } catch (_) {
+      // Regex fallback to mirror the bash grep+sed pipeline (handles slightly malformed caches).
+      const get = (key) => {
+        const m = raw.match(new RegExp(`"${key}"\\s*:\\s*"([^"]*)"`));
+        return m ? m[1] : '';
+      };
+      const newerMatch = raw.match(/"is_newer"\s*:\s*(true|false)/);
+      return {
+        latest_tag: get('latest_tag'),
+        delta: get('delta'),
+        is_newer: newerMatch ? newerMatch[1] === 'true' : false,
+        changelog_excerpt: get('changelog_excerpt').replace(/\\n/g, '\n'),
+      };
+    }
+  } catch (e) {
+    log('readCache failed:', e && e.message);
+    return null;
+  }
+}
+
+// ---- Banner renderer ----
+function buildBanner({ displayCurrent, latestTag, deltaKind, body }) {
+  const bar = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━';
+  const lines = [];
+  lines.push(bar);
+  lines.push(` 📦 Plugin update: ${displayCurrent} → ${latestTag} (${deltaKind})`);
+  if (body && body.length > 0) {
+    lines.push(body);
+  }
+  lines.push(' Install: /gdd:update   Dismiss: /gdd:check-update --dismiss');
+  lines.push(bar);
+  lines.push('');
+  return lines.join('\n');
+}
+
+// ---- Main control flow. argv is process.argv-style; defaults to process.argv. ----
+async function main(argv) {
+  argv = argv || process.argv.slice(2);
+  const paths = getPaths();
+
+  // Ensure .design/ exists (belt+suspenders — bootstrap normally creates it).
+  try {
+    fs.mkdirSync(paths.designDir, { recursive: true });
+  } catch (_) {
+    return 0;
+  }
+
+  const currentTag = readCurrentTag(paths.pluginJson);
+  if (!currentTag) {
+    log('no plugin.json or no current version parsed');
+    return 0;
+  }
+  const displayCurrent = 'v' + currentTag.replace(/^v/, '');
+
+  let forceRefresh = false;
+  for (const arg of argv) {
+    if (arg === '--refresh') forceRefresh = true;
+  }
+
+  // 1. Populate cache if missing/stale or forced.
+  if (forceRefresh || !isCacheFresh(paths.cache)) {
+    let raw = '';
+    try {
+      raw = await fetchLatest();
+    } catch (_) {
+      raw = '';
+    }
+    if (raw && raw.length > 0) {
+      const latestTagRaw = extractTag(raw);
+      const bodyExcerpt = extractBody(raw);
+      let latestTag = latestTagRaw;
+      if (!isSafeSemverTag(latestTag)) {
+        log(`LATEST_TAG '${latestTag}' failed semver safety check — aborting cache write`);
+        latestTag = '';
+      }
+      if (latestTag) {
+        const delta = classifyDelta(displayCurrent, latestTag);
+        const isNewer = delta.state === 'newer';
+        const checkedAt = Math.floor(Date.now() / 1000);
+        const json = buildCacheJson({
+          checkedAt,
+          currentTag: displayCurrent,
+          latestTag,
+          deltaKind: delta.kind,
+          isNewer,
+          bodyExcerpt,
+        });
+        atomicWrite(paths.cache, json);
+      }
+    }
+  }
+
+  // 2. Read cache (whether freshly written or still valid).
+  if (!fs.existsSync(paths.cache)) {
+    return 0; // no cache, nothing to do — silent exit
+  }
+  const cache = readCache(paths.cache);
+  if (!cache) return 0;
+
+  const cLatest = cache.latest_tag;
+  let cDelta = cache.delta;
+  // Allowlist-gate cDelta before it reaches any banner context (WR-04).
+  const allowedDeltas = new Set(['major', 'minor', 'patch', 'off-cadence', 'none']);
+  if (!allowedDeltas.has(cDelta)) cDelta = 'unknown';
+  const cNewer = cache.is_newer === true;
+  const cBody = cache.changelog_excerpt || '';
+
+  // 3. Gate: if cache says not newer, remove any stale banner and exit.
+  if (!cNewer) {
+    try { fs.unlinkSync(paths.banner); } catch (_) {}
+    return 0;
+  }
+
+  // 4. Dismissal gate (D-13): if user already dismissed this exact tag, suppress.
+  const dismissed = readDismissed(paths.config);
+  if (dismissed && dismissed === cLatest) {
+    try { fs.unlinkSync(paths.banner); } catch (_) {}
+    return 0;
+  }
+
+  // 5. State-machine guard (D-11/D-12): suppress during plan|design|verify.
+  const stage = readStateStage(paths.state);
+  if (stage === 'plan' || stage === 'design' || stage === 'verify') {
+    try { fs.unlinkSync(paths.banner); } catch (_) {}
+    return 0;
+  }
+
+  // 6. All gates passed — render the banner atomically.
+  const banner = buildBanner({
+    displayCurrent,
+    latestTag: cLatest,
+    deltaKind: cDelta,
+    body: cBody,
+  });
+  atomicWrite(paths.banner, banner);
+
+  return 0;
+}
+
+// ---- Exports for tests (mirrors bash sourcing pattern) ----
+module.exports = {
+  // Public helpers (named to match the bash function names where reasonable).
+  normalizeSemver,
+  classifyDelta,
+  isCacheFresh,
+  readCurrentTag,
+  readStateStage,
+  readDismissed,
+  fetchLatest,
+  extractTag,
+  extractBody,
+  // Additional helpers useful for tests / orchestrator.
+  isSafeSemverTag,
+  atomicWrite,
+  buildCacheJson,
+  buildBanner,
+  readCache,
+  getPaths,
+  getPluginRoot,
+  main,
+};
+
+// ---- Entry-point guard: only run main when invoked directly (not when required). ----
+if (require.main === module) {
+  // Always exit 0 (silent-on-failure). Promise rejections also exit 0.
+  main(process.argv.slice(2))
+    .then(() => process.exit(0))
+    .catch((e) => {
+      log('main threw:', e && e.message);
+      process.exit(0);
+    });
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.57.1",
-  "description": "A design-quality pipeline for AI coding agents: brief, plan, implement, and verify UI work against your design system.",
+  "version": "1.57.2",
+  "description": "A design-quality pipeline for AI coding agents: brief, explore, plan, design, and verify UI work against your design system.",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",
   "repository": {
@@ -27,6 +27,8 @@
     "scripts/lib/",
     "scripts/cli/",
     "scripts/install.cjs",
+    "scripts/injection-patterns.cjs",
+    "scripts/bootstrap.cjs",
     "SKILL.md",
     "README.md",
     "CHANGELOG.md",
@@ -84,10 +86,15 @@
     "validate:schemas": "node --experimental-strip-types scripts/validate-schemas.ts",
     "validate:frontmatter": "node --experimental-strip-types scripts/validate-frontmatter.ts agents/",
     "detect:stale-refs": "node scripts/detect-stale-refs.cjs",
+    "validate:feature-counts": "node scripts/check-feature-counts.cjs",
+    "validate:registry-tiers": "node scripts/validate-registry-tiers.cjs",
+    "validate:no-internal-refs": "node scripts/validate-no-internal-refs.cjs",
+    "validate:cache-tiers": "node scripts/check-cache-tiers.cjs",
     "scan:injection": "node scripts/run-injection-scanner-ci.cjs",
     "scan:outbound": "node scripts/scan-outbound-network.cjs",
     "scan:ws-bind": "node scripts/scan-ws-bind.cjs",
     "test:size-budget": "node --test test/suite/agent-size-budget.test.cjs",
+    "validate:skill-surface": "node --test test/suite/skill-surface-sync.test.cjs",
     "release:extract-changelog": "node scripts/extract-changelog-section.cjs",
     "verify:version-sync": "node scripts/verify-version-sync.cjs",
     "typecheck:session-runner": "tsc --noEmit",

package/reference/STATE-TEMPLATE.md

@@ -7,10 +7,7 @@ This is the canonical template for the design pipeline's runtime state file.
 - Every subsequent stage (discover, plan, design, verify) reads `.design/STATE.md` at entry and updates it at completion, per the Write Contract below.
 - `.design/` is gitignored (not distributed with the plugin); only this template ships.
 
-**Distinction from `.planning/STATE.md`:**
-- `.planning/STATE.md` is GSD development state - used by the developers building this plugin.
-- `.design/STATE.md` is pipeline runtime state - used by the pipeline when it runs in a user's project.
-- Keep them strictly separate. Cross-references between them are deferred to Phase 6 per CONTEXT.md.
+`.design/` is the runtime state for the design pipeline as it runs in a user's project. The plugin's own internal development workspace lives outside this directory and never reaches a user install.
 
 ---
 
@@ -47,7 +44,7 @@ skipped_stages: ""
 <decisions>
 <!-- Filled by discover stage. Format: -->
 <!-- D-01: [decision text] (locked | tentative) -->
-<!-- Phase 40 (team mode): an optional attribution suffix records provenance for multi-author merges: -->
+<!-- In team mode, an optional attribution suffix records provenance for multi-author merges: -->
 <!-- D-01: [decision text] (locked | tentative) [author=<git-user> co-author=<gdd-instance-id>] -->
 <!-- The suffix is optional + backward-compatible; see reference/multi-author-model.md. -->
 </decisions>
@@ -59,7 +56,7 @@ skipped_stages: ""
 </must_haves>
 
 <prototyping>
-<!-- Phase 25: appended by sketch-wrap-up / spike-wrap-up + the prototype-gate. -->
+<!-- Appended by sketch-wrap-up / spike-wrap-up + the prototype-gate. -->
 <!-- Three child element types, each on its own line: -->
 <!-- <sketch slug="…" cycle="…" decision="D-XX" status="resolved"/> -->
 <!-- <spike slug="…" cycle="…" decision="D-XX" verdict="yes|no|partial" status="resolved"/> -->
@@ -69,7 +66,7 @@ skipped_stages: ""
 </prototyping>
 
 <quality_gate>
-<!-- Phase 25 (Plan 25-03): written by the quality-gate skill (Stage 4.5). -->
+<!-- Written by the quality-gate skill (Stage 4.5). -->
 <!-- Houses a single most-recent <run/> entry — append-mode would be overkill. -->
 <!-- Format: -->
 <!-- <run started_at="…" completed_at="…" status="pass|fail|timeout|skipped" iteration="N" commands_run="lint,typecheck,test"/> -->
@@ -173,22 +170,22 @@ Discover stage populates with observable behaviors. Verify stage updates status.
 
 ### `<prototyping>`
 
-Phase 25 surface (D-01). A checkpoint log - NOT a stage. Tracks sketch and spike outcomes plus cycle-scoped skip suppressions for the prototype gate.
+A checkpoint log - NOT a stage. Tracks sketch and spike outcomes plus cycle-scoped skip suppressions for the prototype gate.
 
 - `<sketch slug=… cycle=… decision=D-XX status=resolved/>` - written by `sketch-wrap-up` after a sketch resolves into a D-XX decision.
 - `<spike slug=… cycle=… decision=D-XX verdict=yes|no|partial status=resolved/>` - written by `spike-wrap-up` after a spike resolves; `verdict` captures the answer.
-- `<skipped at=… cycle=… reason=…/>` - written by the prototype gate when the user declines to sketch/spike at a firing point. Cycle-scoped suppression (D-02): a `<skipped/>` entry suppresses re-asking for the rest of the named cycle.
+- `<skipped at=… cycle=… reason=…/>` - written by the prototype gate when the user declines to sketch/spike at a firing point. The entry provides cycle-scoped suppression: it suppresses re-asking for the rest of the named cycle.
 
 The block is **optional** - fresh STATE.md files do not carry it. The serializer omits the block entirely when no entries exist; appending the first entry is what materializes the block.
 
 ### `<quality_gate>`
 
-Phase 25 surface (Plan 25-03 / D-06..D-09). Captures the most recent run of the Stage 4.5 quality gate (lint / typecheck / test / visual-regression) between Design and Verify. The block houses a single self-closing `<run/>` element - append-mode is overkill, so each gate completion overwrites the entry.
+Captures the most recent run of the Stage 4.5 quality gate (lint / typecheck / test / visual-regression) between Design and Verify. The block houses a single self-closing `<run/>` element - append-mode is overkill, so each gate completion overwrites the entry.
 
 - `started_at` - ISO 8601 at which the parallel command run entered.
 - `completed_at` - ISO 8601 at which the gate produced its terminal status.
-- `status` - `pass | fail | timeout | skipped`. `pass` clears the verify-entry gate; `fail` blocks; `timeout` warns + proceeds (D-07); `skipped` indicates the detection chain resolved zero commands.
-- `iteration` - non-negative integer fix-loop count (D-08). `1` = single clean pass; `N === max_iters` with `status === 'fail'` = bounded exhaustion.
+- `status` - `pass | fail | timeout | skipped`. `pass` clears the verify-entry gate; `fail` blocks; `timeout` warns + proceeds; `skipped` indicates the detection chain resolved zero commands.
+- `iteration` - non-negative integer fix-loop count. `1` = single clean pass; `N === max_iters` with `status === 'fail'` = bounded exhaustion.
 - `commands_run` - comma-separated names of the commands actually executed in Step 2 (e.g., `lint,typecheck,test`). Empty string when `status === 'skipped'`.
 
 The block is **optional** - fresh STATE.md files do not carry it. The serializer omits the block entirely when `quality_gate === null`; the SKILL writes the first `<run/>` to materialize it.
@@ -245,7 +242,7 @@ Every stage that runs in the pipeline MUST follow this contract when reading and
 
 ---
 
-## Notes for Phase 2 implementors
+## Notes for implementors
 
 - Do not add new top-level XML sections without updating this template.
 - The write contract is non-negotiable - stages that skip the read-at-entry step break resume.

package/reference/audit-scoring.md

@@ -247,7 +247,7 @@ Attach to findings under the Visual Hierarchy pillar that relate to compositiona
 
 ### `i18n_readiness`
 
-Attach to findings under the Accessibility pillar (for WCAG 3.1.1 / 3.1.2 violations) or under the Anti-Pattern Compliance pillar (for hardcoded-string / overflow-at-+40% defects). Emitted by the `agents/design-verifier.md` §i18n probes section (Phase 28-06). See [`./i18n.md`](./i18n.md) §WCAG i18n + §Verifier Integration Spec. Does NOT change pillar weights or scores.
+Attach to findings under the Accessibility pillar (for WCAG 3.1.1 / 3.1.2 violations) or under the Anti-Pattern Compliance pillar (for hardcoded-string / overflow-at-+40% defects). Emitted by the `agents/design-verifier.md` §i18n probes section. See [`./i18n.md`](./i18n.md) §WCAG i18n + §Verifier Integration Spec. Does NOT change pillar weights or scores.
 
 ### `verb_axes` (anti-slop)
 

package/reference/cache-tier-doctrine.md

@@ -0,0 +1,46 @@
+# Cache-Tier Doctrine
+
+The Anthropic prompt cache has a 5-minute TTL and is invalidated by a single byte change in the prefix. Every agent body imports `reference/shared-preamble.md` as the first thing it reads; that import expands to a flat byte block at the top of every agent's prompt. Stable bytes there mean stable cache; churning bytes there mean every agent's cache misses on every spawn.
+
+This doctrine pins the bytes that have to stay stable.
+
+## The four tiers
+
+| Tier | Lifetime | Files | Edit cost |
+|------|----------|-------|-----------|
+| **L0** | Framework-invariant | `reference/meta-rules.md` + `reference/shared-preamble.md` | Invalidates cache for every agent simultaneously. CI gate enforces SHA-256 stability; ratchet via `--rebaseline` only when the framework genuinely changes. |
+| **L1** | Per-agent stable | Agent body itself (role, tools contract, output format) | Invalidates cache for the one agent. Edits are routine. |
+| **L2** | Per-spawn dynamic | `<required_reading>` block + per-invocation prompt | Never caches. Edits are free. |
+| **L3** | Reference-only | `reference/*.md` other than L0 | Loaded per-agent on demand; not part of the cache prefix. Edits do not affect cache. |
+
+## The L0 contract
+
+1. **Two files, no more.** L0 = `reference/meta-rules.md` (framework-invariant rules: required reading, writes protocol, deviation handling, completion markers, context-exhaustion + budget) + `reference/shared-preamble.md` (the aggregator that imports meta-rules and contributes the design-family pillar lists). Any third L0 file requires a doctrine update.
+2. **Byte-stable across cycles.** Section heading text, prose order, ordering of bulleted lists, even whitespace runs; all are essential. An edit that "just rewords a sentence" still invalidates cache for every agent for one session per agent.
+3. **CI gate enforces stability.** `scripts/check-cache-tiers.cjs` computes SHA-256 of each L0 file and compares to `test/fixtures/baselines/l0-hashes.json`. Drift fails the build. A real edit requires `--rebaseline` and a baseline-hash commit alongside the L0 edit.
+4. **Pre-warming exists for legitimate L0 edits.** Run `/gdd:warm-cache` after an L0 edit lands to pre-load the new prefix so the next real spawn is a hit rather than a miss.
+
+## What goes where
+
+- A new design-pillar list shared by 5 design-family skills → `shared-preamble.md` (L0). Costs cache miss; ratchet the L0 baseline.
+- A new validator rule for a single agent → that agent body (L1). No L0 impact.
+- A per-invocation context block; the brief, the must-haves, the user's specific request → `<required_reading>` (L2). No cache implications either way.
+- A reference catalog of heuristics, anti-patterns, WCAG thresholds → `reference/*.md` (L3). No cache implications.
+
+## Verification
+
+- `npm run validate:registry-tiers` - confirms `registry.json` entries' `tier` field is one of L0/L1/L2/L3.
+- `npm run validate:cache-tiers` - confirms L0 file SHA-256 matches the baseline.
+- Both run in CI as part of the default test suite.
+
+## When to ratchet
+
+Ratchet (`--rebaseline`) only when:
+
+1. Framework invariant changes (rare).
+2. A design-pillar list shared by ≥3 skills needs updating.
+3. A factual claim that EVERY agent must know becomes false.
+
+If any of those three is true: edit the L0 file, run `node scripts/check-cache-tiers.cjs --rebaseline`, commit both the L0 edit and the updated baseline. Reviewers see the L0-hash diff and understand the cache cost.
+
+If none of the three is true: the edit belongs in L1 (an agent body), L2 (a per-spawn block), or L3 (a reference doc). Reject the L0 edit; relocate.