@hegemonart/get-design-done 1.28.7 → 1.30.0

package/scripts/lint-agentskills-spec.cjs

@@ -0,0 +1,457 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * scripts/lint-agentskills-spec.cjs — agentskills.io spec lint.
+ *
+ * Phase 28.8 Plan 28-8-A1 (D-13 `lint-only` outcome).
+ * See .planning/research/agentskills-io-2026-05-19.md § Implementation Implications
+ * → Plan 28-8-A1 — what to ship — for the source-of-truth rule list.
+ *
+ * Walks `skills/<name>/SKILL.md` and applies the following rules per skill:
+ *
+ *   R1 (FAIL) — frontmatter contains a non-empty `name`.
+ *   R2 (FAIL) — `name` matches /^[a-z0-9]+(-[a-z0-9]+)*$/ AND length ≤ 64.
+ *   R3 (FAIL) — `name` matches the parent directory (allow bare slug OR `gdd-`-prefixed
+ *               slug, because source-tree uses bare and install-tree uses prefixed per
+ *               Phase 28.7 D-05).
+ *   R4 (FAIL) — `description` is non-empty AND ≤ 1024 chars (spec hard cap).
+ *   R5 (FAIL) — SKILL.md body line count ≤ 500 (spec readability guidance).
+ *
+ *   W1 (WARN) — both `tools` and `allowed-tools` are present. `allowed-tools` is marked
+ *               Experimental in the spec; pick one form to avoid drift.
+ *   W2 (WARN) — description length > 200 chars (Phase 28.5 D-01 advisory; distinct
+ *               from R4's 1024-char hard cap).
+ *   W3        — reserved slot (covered today by R2). No emission.
+ *
+ * CLI:
+ *   node scripts/lint-agentskills-spec.cjs               # default: lint ./skills
+ *   node scripts/lint-agentskills-spec.cjs <dir>         # lint <dir>/<name>/SKILL.md
+ *   node scripts/lint-agentskills-spec.cjs --json        # emit JSON instead of table
+ *   node scripts/lint-agentskills-spec.cjs --summary     # one-line PASS/WARN/FAIL counts
+ *   node scripts/lint-agentskills-spec.cjs --summary --json
+ *                                                        # JSON {pass,warn,fail} counts
+ *
+ * Exit codes:
+ *   0 — no FAIL rows (WARN rows do NOT fail the run)
+ *   1 — at least one FAIL row
+ *   2 — internal error (I/O failure, parse exception, bad CLI arg)
+ *
+ * Empty / missing skills directory:
+ *   Prints `Lint: no skills found at <dir> — nothing to lint.` and exits 0.
+ *   Under `--summary`, prints `PASS=0 WARN=0 FAIL=0` (or `{"pass":0,"warn":0,"fail":0}`
+ *   with `--summary --json`) and exits 0 — empty dirs never fail the run.
+ *
+ * Exports (for tests + Plan 28-8-X2 in-process consumption):
+ *   lint(skillsDir, opts?) → { rows, summary, emptyDir }
+ *   lintSummary({sourceRoot}) → { pass, warn, fail }     // Plan 28-8-X2 doctor seam
+ *   main(argv) → number (exit code; pure — does NOT call process.exit)
+ *   parseFrontmatter(content) → { frontmatter, body, hasFrontmatter }
+ *   lintSkill(skillDir, skillName) → Array<{status, skill, rule, detail}>
+ *
+ * Plan 28-8-X2 wiring:
+ *   `lintSummary` is consumed in-process by `scripts/lib/install/doctor-tier2.cjs`
+ *   (Tier-2 doctor aggregator). It returns `{pass, warn, fail}` counts only — no
+ *   table, no JSON, no IO beyond fs.readFileSync of SKILL.md files. The doctor wraps
+ *   it as the agentskills.io channel state per D-13 (lint-only adoption).
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const NAME_REGEX = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const NAME_MAX = 64;
+const DESC_MAX = 1024;
+const DESC_ADVISORY = 200;
+const BODY_MAX_LINES = 500;
+const DETAIL_TRUNCATE = 100;
+
+/**
+ * Parse YAML-ish frontmatter at the top of a markdown document.
+ *
+ * Zero-dep: handles only what our Phase 28.5 frontmatter contract emits:
+ * - leading `---\n` block delimited by `\n---\n`
+ * - scalar `key: value` lines (no nested maps, no arrays)
+ * - surrounding single or double quotes stripped from value
+ * - for values containing colons (URLs in description), the substring after the FIRST `:`
+ *   is taken — so `description: "https://example.com"` works.
+ *
+ * Returns:
+ *   { frontmatter: object, body: string, hasFrontmatter: boolean }
+ *
+ * If the opening delimiter is missing or the closing delimiter is not found, returns
+ * `hasFrontmatter: false` with `frontmatter: {}` and `body` set to the original content.
+ */
+function parseFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
+  if (!match) {
+    return { frontmatter: {}, body: content, hasFrontmatter: false };
+  }
+  const block = match[1];
+  const body = match[2];
+  const frontmatter = {};
+  const lines = block.split(/\r?\n/);
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    const colonIdx = line.indexOf(':');
+    if (colonIdx < 0) continue;
+    const key = line.slice(0, colonIdx).trim();
+    let value = line.slice(colonIdx + 1).trim();
+    if (
+      value.length >= 2 &&
+      ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'")))
+    ) {
+      value = value.slice(1, -1);
+    }
+    frontmatter[key] = value;
+  }
+  return { frontmatter, body, hasFrontmatter: true };
+}
+
+/**
+ * Lint a single skill directory. Returns one or more rows.
+ *
+ * Row shape: { status: 'PASS'|'WARN'|'FAIL', skill: string, rule: string, detail: string }
+ *
+ * If no rule fires, returns a single PASS row with rule='-' and detail='-'.
+ */
+function lintSkill(skillDir, skillName) {
+  const skillPath = path.join(skillDir, 'SKILL.md');
+  let content;
+  try {
+    content = fs.readFileSync(skillPath, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      return [
+        {
+          status: 'FAIL',
+          skill: skillName,
+          rule: 'IO',
+          detail: 'SKILL.md not found',
+        },
+      ];
+    }
+    throw err;
+  }
+
+  const { frontmatter, body } = parseFrontmatter(content);
+  const rows = [];
+
+  const name = (frontmatter.name || '').trim();
+  const description = (frontmatter.description || '').trim();
+  const hasTools = Object.prototype.hasOwnProperty.call(frontmatter, 'tools');
+  const hasAllowedTools = Object.prototype.hasOwnProperty.call(frontmatter, 'allowed-tools');
+
+  // R1
+  if (!name) {
+    rows.push({
+      status: 'FAIL',
+      skill: skillName,
+      rule: 'R1',
+      detail: 'frontmatter missing or empty `name`',
+    });
+  } else {
+    // R2
+    if (!NAME_REGEX.test(name) || name.length > NAME_MAX) {
+      rows.push({
+        status: 'FAIL',
+        skill: skillName,
+        rule: 'R2',
+        detail: `name "${name}" fails slug regex /^[a-z0-9]+(-[a-z0-9]+)*$/ or exceeds ${NAME_MAX} chars`,
+      });
+    }
+    // R3 — name must match parent dir (bare or gdd-prefixed)
+    if (
+      name !== skillName &&
+      name !== `gdd-${skillName}` &&
+      skillName !== `gdd-${name}`
+    ) {
+      rows.push({
+        status: 'FAIL',
+        skill: skillName,
+        rule: 'R3',
+        detail: `name "${name}" does not match parent dir "${skillName}" (allowed: bare slug or gdd-prefixed slug per Phase 28.7 D-05)`,
+      });
+    }
+  }
+
+  // R4
+  if (!description) {
+    rows.push({
+      status: 'FAIL',
+      skill: skillName,
+      rule: 'R4',
+      detail: 'description missing or empty',
+    });
+  } else if (description.length > DESC_MAX) {
+    rows.push({
+      status: 'FAIL',
+      skill: skillName,
+      rule: 'R4',
+      detail: `description: ${description.length} chars (>${DESC_MAX} hard cap)`,
+    });
+  }
+
+  // R5 — body line count
+  const bodyLines = body ? body.split(/\r?\n/).length : 0;
+  if (bodyLines > BODY_MAX_LINES) {
+    rows.push({
+      status: 'FAIL',
+      skill: skillName,
+      rule: 'R5',
+      detail: `body ${bodyLines} lines (>${BODY_MAX_LINES} spec guidance)`,
+    });
+  }
+
+  // W1 — both tools and allowed-tools present
+  if (hasTools && hasAllowedTools) {
+    rows.push({
+      status: 'WARN',
+      skill: skillName,
+      rule: 'W1',
+      detail: '`tools` and `allowed-tools` both present; spec marks `allowed-tools` Experimental — pick one to avoid drift',
+    });
+  }
+
+  // W2 — description over advisory cap but under hard cap
+  if (
+    description &&
+    description.length > DESC_ADVISORY &&
+    description.length <= DESC_MAX
+  ) {
+    rows.push({
+      status: 'WARN',
+      skill: skillName,
+      rule: 'W2',
+      detail: `description: ${description.length} chars (>${DESC_ADVISORY} advisory cap, Phase 28.5 D-01)`,
+    });
+  }
+
+  // W3 — reserved (covered by R2).
+
+  if (rows.length === 0) {
+    rows.push({
+      status: 'PASS',
+      skill: skillName,
+      rule: '-',
+      detail: '-',
+    });
+  }
+  return rows;
+}
+
+/**
+ * Walk a skills directory and lint each child subdirectory containing SKILL.md.
+ *
+ * Returns:
+ *   { rows: Array, summary: {total, pass, warn, fail}, emptyDir: boolean }
+ */
+function lint(skillsDir, opts) {
+  const _opts = opts || {};
+  if (!fs.existsSync(skillsDir)) {
+    return {
+      rows: [],
+      summary: { total: 0, pass: 0, warn: 0, fail: 0 },
+      emptyDir: true,
+    };
+  }
+  let stat;
+  try {
+    stat = fs.statSync(skillsDir);
+  } catch (err) {
+    return {
+      rows: [],
+      summary: { total: 0, pass: 0, warn: 0, fail: 0 },
+      emptyDir: true,
+    };
+  }
+  if (!stat.isDirectory()) {
+    return {
+      rows: [],
+      summary: { total: 0, pass: 0, warn: 0, fail: 0 },
+      emptyDir: true,
+    };
+  }
+
+  const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+  const skillDirs = entries
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .filter((name) => fs.existsSync(path.join(skillsDir, name, 'SKILL.md')))
+    .sort();
+
+  if (skillDirs.length === 0) {
+    return {
+      rows: [],
+      summary: { total: 0, pass: 0, warn: 0, fail: 0 },
+      emptyDir: true,
+    };
+  }
+
+  const rows = [];
+  for (const skillName of skillDirs) {
+    const skillDir = path.join(skillsDir, skillName);
+    const skillRows = lintSkill(skillDir, skillName);
+    for (const row of skillRows) rows.push(row);
+  }
+
+  const summary = {
+    total: skillDirs.length,
+    pass: rows.filter((r) => r.status === 'PASS').length,
+    warn: rows.filter((r) => r.status === 'WARN').length,
+    fail: rows.filter((r) => r.status === 'FAIL').length,
+  };
+
+  return { rows, summary, emptyDir: false };
+}
+
+/**
+ * Plan 28-8-X2 seam — return only the PASS/WARN/FAIL counts as a flat object.
+ *
+ * Consumed in-process by `scripts/lib/install/doctor-tier2.cjs` (Tier-2 doctor
+ * aggregator). Wraps `lint()` and projects its `summary` onto a 3-field shape
+ * matching the X2 interface contract: `{ pass, warn, fail }`. Empty dirs
+ * yield `{ pass: 0, warn: 0, fail: 0 }`. The `total` field is dropped — callers
+ * compute it from `pass + warn + fail` if needed, matching D-13 lint-only contract.
+ *
+ * Pure: no IO beyond what `lint()` already does. Never calls process.exit.
+ *
+ * @param {{ sourceRoot?: string }} [opts]  Optional. `sourceRoot` is the directory
+ *                                          containing `skills/` (NOT the skills/
+ *                                          directory itself — matches Phase 28.7
+ *                                          `findInstallSourceRoot()` return contract).
+ *                                          Defaults to `process.cwd()` when omitted.
+ * @returns {{ pass: number, warn: number, fail: number }}
+ */
+function lintSummary(opts) {
+  const _opts = opts || {};
+  const sourceRoot = _opts.sourceRoot || process.cwd();
+  const skillsDir = path.join(sourceRoot, 'skills');
+  const result = lint(skillsDir);
+  return {
+    pass: result.summary.pass,
+    warn: result.summary.warn,
+    fail: result.summary.fail,
+  };
+}
+
+/**
+ * Format the row set as an aligned plain-text table.
+ *
+ * Columns: STATUS  SKILL  RULE  DETAIL
+ * DETAIL is truncated to DETAIL_TRUNCATE chars with a `…` suffix for terminal sanity.
+ */
+function formatTable(rows) {
+  const headers = ['STATUS', 'SKILL', 'RULE', 'DETAIL'];
+  const display = rows.map((r) => {
+    let detail = String(r.detail);
+    if (detail.length > DETAIL_TRUNCATE) {
+      detail = detail.slice(0, DETAIL_TRUNCATE) + '…';
+    }
+    return [r.status, r.skill, r.rule, detail];
+  });
+  const widths = headers.map((h, i) =>
+    Math.max(h.length, ...display.map((row) => row[i].length))
+  );
+  const pad = (cells) =>
+    cells.map((c, i) => c.padEnd(widths[i])).join('  ');
+  const sep = widths.map((w) => '-'.repeat(w)).join('  ');
+  const out = [pad(headers), sep];
+  for (const row of display) out.push(pad(row));
+  return out.join('\n');
+}
+
+/**
+ * Main CLI entry. Pure — returns exit code rather than calling process.exit.
+ *
+ * argv is the argv slice AFTER node + script (i.e. process.argv.slice(2)).
+ */
+function main(argv) {
+  try {
+    let skillsDir = './skills';
+    let jsonMode = false;
+    let summaryMode = false;
+    for (const arg of argv) {
+      if (arg === '--json') {
+        jsonMode = true;
+      } else if (arg === '--summary') {
+        summaryMode = true;
+      } else if (arg === '--help' || arg === '-h') {
+        process.stdout.write(
+          'lint-agentskills-spec.cjs — agentskills.io spec lint over skills/<name>/SKILL.md\n' +
+            '\n' +
+            'Usage:\n' +
+            '  node scripts/lint-agentskills-spec.cjs [<dir>] [--json]\n' +
+            '  node scripts/lint-agentskills-spec.cjs [<dir>] --summary [--json]\n' +
+            '\n' +
+            'Modes:\n' +
+            '  default      Aligned table of all rows + final summary line\n' +
+            '  --json       JSON {rows, summary} object\n' +
+            '  --summary    One-line `PASS=N WARN=N FAIL=N`\n' +
+            '  --summary --json  JSON {pass, warn, fail} (Plan 28-8-X2 seam)\n' +
+            '\n' +
+            'Exit codes:\n' +
+            '  0  no FAIL rows (WARN rows do NOT fail the run)\n' +
+            '  1  at least one FAIL row\n' +
+            '  2  internal error\n'
+        );
+        return 0;
+      } else if (arg.startsWith('--')) {
+        process.stderr.write(`lint-agentskills-spec: unknown flag: ${arg}\n`);
+        return 2;
+      } else {
+        skillsDir = arg;
+      }
+    }
+
+    const result = lint(skillsDir);
+
+    // Plan 28-8-X2 — --summary mode short-circuits the table renderer for
+    // doctor-tier2 callers. Empty dir is treated as 0-everything (exits 0)
+    // matching the default-mode "no skills found" exit-0 contract.
+    if (summaryMode) {
+      const pass = result.summary.pass || 0;
+      const warn = result.summary.warn || 0;
+      const fail = result.summary.fail || 0;
+      if (jsonMode) {
+        process.stdout.write(JSON.stringify({ pass, warn, fail }) + '\n');
+      } else {
+        process.stdout.write(`PASS=${pass} WARN=${warn} FAIL=${fail}\n`);
+      }
+      return fail > 0 ? 1 : 0;
+    }
+
+    if (result.emptyDir) {
+      process.stdout.write(
+        `Lint: no skills found at ${skillsDir} — nothing to lint.\n`
+      );
+      return 0;
+    }
+
+    if (jsonMode) {
+      process.stdout.write(
+        JSON.stringify({ rows: result.rows, summary: result.summary }, null, 2) +
+          '\n'
+      );
+    } else {
+      process.stdout.write(formatTable(result.rows) + '\n');
+      const { total, pass, warn, fail } = result.summary;
+      process.stdout.write(
+        `\nLint summary: ${total} skills, ${pass} PASS, ${warn} WARN, ${fail} FAIL\n`
+      );
+    }
+
+    return result.summary.fail > 0 ? 1 : 0;
+  } catch (err) {
+    process.stderr.write(
+      `lint-agentskills-spec: internal error: ${err && err.message ? err.message : err}\n`
+    );
+    return 2;
+  }
+}
+
+if (require.main === module) {
+  process.exit(main(process.argv.slice(2)));
+}
+
+module.exports = { lint, lintSummary, main, parseFrontmatter, lintSkill };

package/scripts/release-smoke-test.cjs

@@ -50,6 +50,27 @@ if (!fs.existsSync(FIXTURE_SRC)) {
 const tmpDir = path.join(os.tmpdir(), `gdd-smoke-${Date.now()}`);
 fs.mkdirSync(tmpDir, { recursive: true });
 
+// Snapshot REPO_ROOT/.design/ contents BEFORE the smoke test runs. This lets
+// the post-test pollution assertion (below) detect actual pollution (new
+// files created during the run) rather than tripping on legitimately-tracked
+// `.design/` files that exist in a fresh checkout — e.g.
+// `.design/config.example.json` shipped by Plan 29-02 for discoverability.
+function snapshotDesignDir() {
+  const designDir = path.join(REPO_ROOT, '.design');
+  if (!fs.existsSync(designDir)) return '<absent>';
+  const entries = [];
+  function walk(d) {
+    for (const ent of fs.readdirSync(d, { withFileTypes: true })) {
+      const full = path.join(d, ent.name);
+      if (ent.isDirectory()) walk(full);
+      else entries.push(path.relative(designDir, full).replace(/\\/g, '/'));
+    }
+  }
+  walk(designDir);
+  return entries.sort().join('\n');
+}
+const designSnapshotBefore = snapshotDesignDir();
+
 function copyRecursive(src, dst) {
   fs.mkdirSync(dst, { recursive: true });
   for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
@@ -161,8 +182,18 @@ if (missing.length) {
 console.log(`smoke-test: ${diffs.length} diffs, ${missing.length} baseline artifacts not in fresh run`);
 
 // Ensure .design/ was not created in the real repo root.
-if (fs.existsSync(path.join(REPO_ROOT, '.design'))) {
-  console.error('ERROR: .design/ polluted repo root — smoke test must use temp dir only');
+// Pollution check: only fail if NEW files appeared in REPO_ROOT/.design/ during
+// the smoke test. Tracked files (like `.design/config.example.json` shipped by
+// Plan 29-02) are present in the fresh checkout and are NOT pollution. We
+// compare the directory snapshot taken before the test (top of file) against
+// the post-test snapshot.
+const designSnapshotAfter = snapshotDesignDir();
+if (designSnapshotBefore !== designSnapshotAfter) {
+  console.error('ERROR: .design/ contents changed during smoke test — pipeline wrote to REPO_ROOT instead of temp dir');
+  console.error('Before:');
+  for (const line of designSnapshotBefore.split('\n')) console.error(`  ${line}`);
+  console.error('After:');
+  for (const line of designSnapshotAfter.split('\n')) console.error(`  ${line}`);
   process.exit(1);
 }
 

package/scripts/validate-incubator-scope.cjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+// scripts/validate-incubator-scope.cjs — Plan 29-05
+//
+// Phase 29 D-05: scope guard for incubator-draft promotion.
+//
+// Purpose
+//   Enforce that a drafted incubator artifact can only resolve to one of:
+//     * `agents/<slug>.md`                  (Phase 28.5 agent files)
+//     * `skills/<slug>/SKILL.md`            (Phase 28.5 skill files)
+//   Any other path (script, hook, runtime, transport, root-escape, absolute
+//   path outside the repo, traversal segment) is rejected with a non-zero
+//   exit and an informative error message.
+//
+//   This script is invoked BEFORE any file write inside
+//   `scripts/lib/apply-reflections/incubator-proposals.cjs#applyAccept`, and
+//   is the second non-bypassable line of defense after the floor enforced by
+//   `scripts/lib/incubator-author.cjs#safeWritePath` at draft-time.
+//
+// Non-bypassable (D-05)
+//   No flag, env var, or argument disables the check. Promotion targets that
+//   fail the regex check throw — period. There is no opt-out flag, no
+//   environment override, and the CLI offers no escape hatch. (The scan in
+//   tests/apply-reflections-incubator.test.cjs grep-asserts the absence of
+//   bypass tokens in this file's source, so even adding such an option in
+//   future would break the build.)
+//
+// API
+//   validateScope(targetPath, { repoRoot } = {})
+//     → { ok: true }                 // accepted
+//     → throws Error(...)            // rejected; message names offending path + allowed patterns
+//
+// CLI
+//   node scripts/validate-incubator-scope.cjs <path>
+//     exit 0 + `[scope-guard] ok: <relPath>` on success
+//     exit 1 + descriptive stderr on failure
+//
+// Style: zero deps beyond node:fs + node:path (matches scripts/lib/incubator-author.cjs).
+
+'use strict';
+
+const path = require('node:path');
+
+// Allowed target patterns — slug rules match the Phase 28.5 frontmatter slug
+// regex (lowercase, digits, hyphens; must start with [a-z0-9]).
+const SLUG_RE_FRAGMENT = '[a-z0-9][a-z0-9-]*';
+const AGENT_RE = new RegExp(`^agents/${SLUG_RE_FRAGMENT}\\.md$`);
+const SKILL_RE = new RegExp(`^skills/${SLUG_RE_FRAGMENT}/SKILL\\.md$`);
+
+/**
+ * Validate that a target path is in scope for incubator promotion.
+ *
+ * Algorithm:
+ *   1. Resolve to absolute path under repoRoot.
+ *   2. Reject if the resolved path escapes repoRoot (path traversal or
+ *      absolute path pointing outside the repository).
+ *   3. Compute repo-relative path with forward-slash normalization.
+ *   4. Reject if the relative path doesn't match exactly one of the two
+ *      allowed patterns.
+ *
+ * @param {string} targetPath - file path to validate; relative paths are
+ *   resolved against repoRoot.
+ * @param {{repoRoot?: string}} [opts] - configuration. repoRoot defaults to
+ *   process.cwd().
+ * @returns {{ok: true}} on success.
+ * @throws {Error} on any rejection. Message includes the offending path and
+ *   the allowed patterns.
+ */
+function validateScope(targetPath, opts) {
+  const o = opts || {};
+  const repoRoot = path.resolve(o.repoRoot || process.cwd());
+
+  if (typeof targetPath !== 'string' || !targetPath.length) {
+    throw new Error(
+      `[scope-guard] invalid input: targetPath must be a non-empty string. ` +
+        `Allowed: ${AGENT_RE.source} or ${SKILL_RE.source}`,
+    );
+  }
+
+  // Resolve relative to repoRoot. Absolute paths bypass repoRoot prefixing;
+  // that's fine — the prefix check below catches them anyway.
+  const resolved = path.resolve(repoRoot, targetPath);
+
+  // Step 1: confirm resolved path is inside repoRoot. We compare with a
+  // trailing separator to avoid `repoRoot-evil/...` slipping past a startsWith
+  // check.
+  const rootWithSep = repoRoot + path.sep;
+  if (!(resolved === repoRoot || resolved.startsWith(rootWithSep))) {
+    throw new Error(
+      `[scope-guard] path escapes repository: ${targetPath} → ${resolved} ` +
+        `(outside ${repoRoot}). Allowed: agents/<slug>.md or skills/<slug>/SKILL.md`,
+    );
+  }
+
+  // Step 2: compute repo-relative path and normalize separators to '/'
+  // (Windows uses '\\' natively).
+  const rel = path.relative(repoRoot, resolved).replace(/\\/g, '/');
+
+  // Step 3: match exactly one of the allowed shapes.
+  if (AGENT_RE.test(rel) || SKILL_RE.test(rel)) {
+    return { ok: true };
+  }
+
+  throw new Error(
+    `[scope-guard] path not in allowed scope: ${rel} ` +
+      `(input: ${targetPath}). Allowed patterns: ` +
+      `agents/<slug>.md (regex ${AGENT_RE.source}) ` +
+      `or skills/<slug>/SKILL.md (regex ${SKILL_RE.source}). ` +
+      `Note: scope guard is non-bypassable per Phase 29 D-05.`,
+  );
+}
+
+module.exports = { validateScope };
+
+// -------------------------------------------------------------------
+// CLI entry
+// -------------------------------------------------------------------
+
+if (require.main === module) {
+  const input = process.argv[2];
+  if (!input) {
+    console.error('[scope-guard] usage: node scripts/validate-incubator-scope.cjs <path>');
+    process.exit(1);
+  }
+  try {
+    validateScope(input);
+    const rel = path.relative(process.cwd(), path.resolve(process.cwd(), input)).replace(/\\/g, '/');
+    console.log(`[scope-guard] ok: ${rel}`);
+    process.exit(0);
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+}

package/skills/apply-reflections/SKILL.md

@@ -66,8 +66,23 @@ Apply-reflections complete
 ─────────────────────────────────────────
 ```
 
+## [INCUBATOR]
+
+Incubator drafts authored by `scripts/lib/incubator-author.cjs` (Phase 29-04) appear as a distinct proposal class. For each draft under `.design/reflections/incubator/<slug>/`, use `scripts/lib/apply-reflections/incubator-proposals.cjs`:
+
+1. `discoverIncubatorDrafts()` → list pending drafts.
+2. `renderProposal(draft)` → show full body + diff + origin signals.
+3. User chooses **accept** | **reject** | **defer** | **edit**.
+4. **accept** — scope-guard runs FIRST (`validateScope` from `scripts/validate-incubator-scope.cjs`); `applyAccept` then promotes draft → `agents/<slug>.md` or `skills/<slug>/SKILL.md` and appends a registry entry. Single-step per D-04.
+5. **reject** — `applyReject` removes the incubator subdir.
+6. **defer** — no-op; draft re-surfaces next run.
+7. **edit** — `applyEdit` opens `$EDITOR`; re-prompt user on close.
+
+**Stage-1 gate.** At session start, call `checkStage1Gate()`. If `thresholdMet && !optInRecorded`, display the opt-in prompt once. NEVER auto-flip per D-01 — recording opt-in requires explicit user confirmation via `recordOptIn()`. Full procedure: `./apply-reflections-procedure.md` §[INCUBATOR].
+
 ## Do Not
 
 - Do not apply any proposal without the user explicitly choosing `a` or `e`.
-- Do not modify source code files (`.ts`, `.tsx`, `.css`, `.js`) — only agent files, reference files, budget.json, discussant questions, and global skills.
+- Do not modify source code files (`.ts`, `.tsx`, `.css`, `.js`) — only agent files, reference files, budget.json, discussant questions, global skills, and incubator drafts.
 - Do not re-run the reflector — this skill only applies existing proposals.
+- Do not bypass the scope guard or auto-flip Stage-1 — both are non-negotiable per D-05 / D-01.