@hegemonart/get-design-done 1.28.8 → 1.30.5

package/scripts/lib/reflector-kfm-proposer.cjs

@@ -0,0 +1,468 @@
+/**
+ * scripts/lib/reflector-kfm-proposer.cjs — Plan 30.5-03 Task 1.
+ *
+ * Reflector KFM proposer: when a capability_gap cluster recurs ≥3 times
+ * with NO matching entry in `reference/known-failure-modes.md`, this
+ * module drops a draft catalogue entry into
+ * `.design/reflections/incubator/kfm-<slug>/CATALOGUE-ENTRY.md`. The
+ * draft is STRICTLY proposal-only — promotion to the canonical catalogue
+ * is gated through `applyAccept()` (the apply-reflections accept action,
+ * Plan 30.5-03 Task 1 step 5).
+ *
+ * Decisions honored:
+ *   * D-05 — Reflector follows Phase 29 incubator-author on-disk pattern
+ *     (drafts in `.design/reflections/incubator/<slug>/`). User reviews
+ *     via `/gdd:apply-reflections`.
+ *   * D-06 — Same draft surface consumed by Task 2's authority-watcher
+ *     `kfm-candidate` event. One unified review path, not two.
+ *   * 30.5 D-07/D-08 — Re-uses `failure-mode-matcher.match()` for
+ *     existing-entry detection. Threshold is the matcher's default 0.4
+ *     unless overridden via options.matcherThreshold.
+ *   * Phase 29 SC-8 — Nothing the reflector authors auto-ships. Drafts
+ *     sit in the incubator until the user accepts them.
+ *
+ * Public API:
+ *   proposeKfmDraft(input, options) → Result
+ *   shouldPropose(cluster, options) → boolean
+ *   applyAccept(draftPath, options) → { action: 'accepted', promotedModeId }
+ *   applyReject(draftPath, options) → { action: 'rejected' }
+ *   applyDefer(draftPath, options) → { action: 'deferred' }
+ *   applyEdit(draftPath, options) → { action: 'edited', path }
+ *
+ * Input shape (capability_gap cluster shape from Plan 29-03):
+ *   { cluster_id, size, intent_summary, symptom?, suggested_kind,
+ *     posterior?, parent_event_ids?, sources?, ... }
+ *
+ * Alternate input shape (kfm-candidate event from Task 2):
+ *   { event_type: 'kfm-candidate', event_id, article_url, article_title,
+ *     suggested_symptom, suggested_pattern_hint, raw_excerpt, ... }
+ *
+ * Both shapes are merged into the same `kfm-<slug>/CATALOGUE-ENTRY.md`
+ * draft surface (D-06).
+ *
+ * Pure CommonJS, deps = node:fs + node:path. No npm dependencies.
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const matcher = require('./failure-mode-matcher.cjs');
+
+// -------------------------------------------------------------------
+// Constants
+// -------------------------------------------------------------------
+
+const DEFAULT_STABILITY_K = 3;
+const DEFAULT_MATCHER_THRESHOLD = 0.4; // matches failure-mode-matcher default
+const INCUBATOR_PREFIX = 'kfm-';
+
+// Phase 30.5 schema v2 fields. The two un-inferable ones (`pattern`,
+// `fix`) get `TODO:` placeholders — user fills them via the apply-
+// reflections edit action.
+const REQUIRED_SCHEMA_FIELDS = Object.freeze([
+  'id',
+  'pattern',
+  'diagnosis',
+  'remedy',
+  'severity',
+  'propose_report',
+  'symptom',
+  'root_cause',
+  'fix',
+  'related_phases',
+  'first_observed_cycle',
+]);
+
+// -------------------------------------------------------------------
+// Helpers
+// -------------------------------------------------------------------
+
+function findRepoRoot(startDir) {
+  let dir = startDir || __dirname;
+  for (let i = 0; i < 12; i++) {
+    if (fs.existsSync(path.join(dir, 'package.json'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return path.resolve(__dirname, '..', '..');
+}
+
+/**
+ * Kebab-case slug from a free-text symptom (mirrors incubator-author
+ * deriveSlug semantics — ASCII-only, dash-collapsed, ≤40 chars).
+ */
+function deriveSlug(text) {
+  const raw = typeof text === 'string' ? text : '';
+  let s = raw.toLowerCase();
+  s = s.replace(/[^\x20-\x7e]+/g, '');
+  s = s.replace(/[^a-z0-9]+/g, '-');
+  s = s.replace(/-+/g, '-');
+  s = s.replace(/^-+|-+$/g, '');
+  if (s.length > 40) s = s.slice(0, 40);
+  s = s.replace(/-+$/g, '');
+  return s || 'unnamed';
+}
+
+/**
+ * Quote a YAML scalar — single-quote shape with `''` escape (matches the
+ * catalogue's serialization).
+ */
+function quoteYaml(s) {
+  if (s === undefined || s === null) return "''";
+  const str = String(s);
+  // Use single quotes with `''` escape if value contains : # or starts/ends with whitespace.
+  if (/[:#'"\\\n\r]|^\s|\s$/.test(str) || str === '') {
+    return `'${str.replace(/'/g, "''")}'`;
+  }
+  return str;
+}
+
+/**
+ * Build a YAML block string from a fields object.
+ * Order: REQUIRED_SCHEMA_FIELDS, then any extras alphabetised.
+ */
+function serializeYaml(fields) {
+  const out = [];
+  const extras = Object.keys(fields)
+    .filter((k) => !REQUIRED_SCHEMA_FIELDS.includes(k))
+    .sort();
+  for (const k of [...REQUIRED_SCHEMA_FIELDS, ...extras]) {
+    if (!(k in fields)) continue;
+    const v = fields[k];
+    if (Array.isArray(v)) {
+      out.push(`${k}: [${v.join(', ')}]`);
+    } else if (typeof v === 'boolean') {
+      out.push(`${k}: ${v}`);
+    } else if (typeof v === 'number') {
+      out.push(`${k}: ${v}`);
+    } else {
+      out.push(`${k}: ${quoteYaml(v)}`);
+    }
+  }
+  return out.join('\n');
+}
+
+/**
+ * Compute the next available `KFM-NNN` numeric id from the catalogue.
+ * Returns the modeId string.
+ */
+function nextKfmId(cataloguePath) {
+  let max = 0;
+  try {
+    const text = fs.readFileSync(cataloguePath, 'utf8');
+    const ids = text.match(/id:\s*KFM-(\d+)/g) || [];
+    for (const m of ids) {
+      const n = parseInt(m.replace(/[^0-9]/g, ''), 10);
+      if (Number.isFinite(n) && n > max) max = n;
+    }
+  } catch (_e) {
+    // Catalogue missing — start from 1.
+  }
+  return `KFM-${String(max + 1).padStart(3, '0')}`;
+}
+
+// -------------------------------------------------------------------
+// Input shape normalisation (cluster OR kfm-candidate event)
+// -------------------------------------------------------------------
+
+/**
+ * Normalise either a capability_gap cluster OR a kfm-candidate event
+ * into a uniform `{ symptom, slug, size, sourceLabel, articleUrl?,
+ * articleTitle?, suggestedPatternHint?, rawExcerpt? }` shape.
+ */
+function normaliseInput(input) {
+  if (!input || typeof input !== 'object') return null;
+
+  // kfm-candidate event shape (Task 2, D-06).
+  if (input.event_type === 'kfm-candidate' ||
+      (input.source === 'authority_watcher' && input.suggested_symptom)) {
+    const symptom = String(input.suggested_symptom || '').trim();
+    if (!symptom) return null;
+    return {
+      symptom,
+      slug: deriveSlug(symptom),
+      size: 1, // single-event source; bypasses ≥3 gate (D-06: authority signal is a 1-shot whitelist match).
+      sourceLabel: 'authority_watcher',
+      articleUrl: input.article_url,
+      articleTitle: input.article_title,
+      suggestedPatternHint: input.suggested_pattern_hint,
+      rawExcerpt: input.raw_excerpt,
+      via: 'kfm-candidate',
+    };
+  }
+
+  // capability_gap cluster shape (Task 1, D-05).
+  const symptom = String(
+    input.symptom || input.intent_summary || ''
+  ).trim();
+  if (!symptom) return null;
+  return {
+    symptom,
+    slug: deriveSlug(symptom),
+    size: Number(input.size) || 0,
+    sourceLabel: 'reflector_capability_gap',
+    parentEventIds: Array.isArray(input.parent_event_ids) ? input.parent_event_ids : [],
+    suggestedKind: input.suggested_kind,
+    posterior: input.posterior,
+    sources: input.sources,
+    cycles: input.cycles_observed,
+    via: 'capability_gap',
+    intentSummary: input.intent_summary,
+  };
+}
+
+// -------------------------------------------------------------------
+// Public API
+// -------------------------------------------------------------------
+
+/**
+ * Decide whether a normalised input qualifies for proposal.
+ * Returns { ok: boolean, reason?: string, matchedModeId?: string }.
+ */
+function shouldPropose(input, options) {
+  const opts = options || {};
+  const repoRoot = opts.repoRoot || findRepoRoot();
+  const cataloguePath = path.join(repoRoot, 'reference', 'known-failure-modes.md');
+  const threshold = Number.isFinite(opts.matcherThreshold)
+    ? opts.matcherThreshold
+    : DEFAULT_MATCHER_THRESHOLD;
+  const stabilityK = Number.isFinite(opts.stabilityK)
+    ? opts.stabilityK
+    : DEFAULT_STABILITY_K;
+
+  const norm = normaliseInput(input);
+  if (!norm) return { ok: false, reason: 'invalid_input' };
+
+  // kfm-candidate events bypass ≥K gate (D-06 — authority-watcher is a
+  // human-curated whitelist hit, treated as 1-shot signal).
+  if (norm.via !== 'kfm-candidate' && norm.size < stabilityK) {
+    return { ok: false, reason: 'below_stability_k' };
+  }
+
+  // Existing-entry check via failure-mode-matcher.
+  const matches = matcher.match(
+    { message: norm.symptom, stack: '' },
+    { cataloguePath, threshold, topN: 1 }
+  );
+  if (Array.isArray(matches) && matches.length >= 1 && matches[0].confidence >= threshold) {
+    return { ok: false, reason: 'matched_existing', matchedModeId: matches[0].modeId };
+  }
+
+  return { ok: true };
+}
+
+/**
+ * Propose a KFM draft for a capability_gap cluster OR a kfm-candidate
+ * event. Returns:
+ *   { action: 'drafted', path, slug, proposed_id }
+ *   { action: 'skipped', reason, matchedModeId? }
+ */
+function proposeKfmDraft(input, options) {
+  const opts = options || {};
+  const repoRoot = opts.repoRoot || findRepoRoot();
+  const incubatorRoot = path.join(repoRoot, '.design', 'reflections', 'incubator');
+  const cataloguePath = path.join(repoRoot, 'reference', 'known-failure-modes.md');
+  const now = opts.now || new Date().toISOString().slice(0, 10);
+  const cycleSlug = opts.cycleSlug || `cycle-${now.slice(0, 7)}`; // cycle-YYYY-MM
+
+  const gate = shouldPropose(input, opts);
+  if (!gate.ok) {
+    return { action: 'skipped', reason: gate.reason, matchedModeId: gate.matchedModeId };
+  }
+
+  const norm = normaliseInput(input);
+  const slug = norm.slug;
+  const proposedId = opts.proposedId || nextKfmId(cataloguePath);
+
+  // Provisional schema fields — `pattern` and `fix` MUST be placeholders
+  // per Plan 30.5-03 Task 1 step 3 (reflector can't infer these).
+  const fields = {
+    id: proposedId,
+    pattern: 'TODO: <regex against error.message + error.stack>',
+    diagnosis: norm.symptom.length > 0 ? norm.symptom.split('\n')[0].slice(0, 240) : 'TODO: <one-sentence root cause>',
+    remedy: 'TODO: <user-runnable one-liner>',
+    severity: 'medium',
+    propose_report: false,
+    symptom: norm.symptom,
+    root_cause: norm.suggestedPatternHint || 'TODO: <technical explanation>',
+    fix: 'TODO: <step-by-step user-runnable remedy>',
+    related_phases: [],
+    first_observed_cycle: cycleSlug,
+  };
+
+  const draftDir = path.join(incubatorRoot, `${INCUBATOR_PREFIX}${slug}`);
+  fs.mkdirSync(draftDir, { recursive: true });
+  const draftPath = path.join(draftDir, 'CATALOGUE-ENTRY.md');
+
+  const originHeader = [
+    `# KFM proposal — ${proposedId}`,
+    '',
+    `**Source:** ${norm.sourceLabel}`,
+    `**Via:** ${norm.via}`,
+    norm.parentEventIds ? `**Parent event ids:** ${norm.parentEventIds.join(', ') || '(none)'}` : null,
+    norm.articleUrl ? `**Article URL:** ${norm.articleUrl}` : null,
+    norm.articleTitle ? `**Article title:** ${norm.articleTitle}` : null,
+    norm.rawExcerpt ? `**Excerpt:** ${norm.rawExcerpt.replace(/\n/g, ' ').slice(0, 500)}` : null,
+    '',
+    `Drafted ${now}. Review via \`/gdd:apply-reflections\` → [KFM-CANDIDATE] proposal class.`,
+    '',
+    'Fill the `TODO:` placeholders before accepting. The `pattern` regex is matched against',
+    '`[error.message, error.stack].filter(Boolean).join("\\n")` — keep it conservative so',
+    'first-match-wins (Phase 30 D-13) does not steal traffic from other entries.',
+    '',
+    '## Proposed YAML',
+    '',
+    '```yaml',
+    serializeYaml(fields),
+    '```',
+    '',
+  ].filter((line) => line !== null).join('\n');
+
+  fs.writeFileSync(draftPath, originHeader);
+
+  return {
+    action: 'drafted',
+    path: draftPath,
+    slug: `${INCUBATOR_PREFIX}${slug}`,
+    proposed_id: proposedId,
+  };
+}
+
+// -------------------------------------------------------------------
+// Apply-reflections actions: accept / reject / defer / edit
+// -------------------------------------------------------------------
+
+/**
+ * Promote a draft → canonical catalogue + registry.json.
+ * Returns { action: 'accepted', promotedModeId }.
+ */
+function applyAccept(draftPath, options) {
+  const opts = options || {};
+  const repoRoot = opts.repoRoot || findRepoRoot();
+  const cataloguePath = path.join(repoRoot, 'reference', 'known-failure-modes.md');
+  const registryPath = path.join(repoRoot, 'reference', 'registry.json');
+
+  if (!fs.existsSync(draftPath)) {
+    throw new Error(`KFM draft not found: ${draftPath}`);
+  }
+  const draftText = fs.readFileSync(draftPath, 'utf8');
+  const yamlMatch = draftText.match(/```yaml\s*\n([\s\S]*?)\n```/);
+  if (!yamlMatch) {
+    throw new Error(`KFM draft missing yaml block: ${draftPath}`);
+  }
+  let yamlBody = yamlMatch[1];
+
+  // Re-stamp id to next available — the proposed id may have collided
+  // with intervening promotions on shared incubator surfaces.
+  const finalId = opts.finalId || nextKfmId(cataloguePath);
+  yamlBody = yamlBody.replace(/^id:\s*KFM-\d+/m, `id: ${finalId}`);
+
+  // Extract the symptom for the catalogue heading.
+  const symptomMatch = yamlBody.match(/^symptom:\s*'?(.+?)'?$/m);
+  const symptomHeading = symptomMatch ? symptomMatch[1].slice(0, 80) : finalId;
+
+  // Append to catalogue.
+  const block = `\n### ${finalId} — ${symptomHeading}\n\nPromoted from incubator KFM proposal.\n\n\`\`\`yaml\n${yamlBody}\n\`\`\`\n`;
+  fs.appendFileSync(cataloguePath, block);
+
+  // Register in registry.json.
+  let registry;
+  try {
+    registry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+  } catch (_e) {
+    registry = { version: 1, entries: [] };
+  }
+  if (!Array.isArray(registry.entries)) registry.entries = [];
+  registry.entries.push({
+    name: `known-failure-modes/${finalId.toLowerCase()}`,
+    path: 'reference/known-failure-modes.md',
+    type: 'failure-mode',
+    phase: 30.5,
+    description: `${finalId} — ${symptomHeading}`,
+    origin: 'incubator-kfm',
+    added: new Date().toISOString().slice(0, 10),
+  });
+  fs.writeFileSync(registryPath, JSON.stringify(registry, null, 2));
+
+  // Remove incubator dir LAST (T-29.05-04 — partial failure leaves draft retryable).
+  const incubatorDir = path.dirname(draftPath);
+  try {
+    for (const f of fs.readdirSync(incubatorDir)) {
+      fs.unlinkSync(path.join(incubatorDir, f));
+    }
+    fs.rmdirSync(incubatorDir);
+  } catch (_e) {
+    // Best-effort; the catalogue + registry promotions already landed.
+  }
+
+  return { action: 'accepted', promotedModeId: finalId };
+}
+
+/**
+ * Remove the incubator draft directory.
+ */
+function applyReject(draftPath, _options) {
+  if (!fs.existsSync(draftPath)) {
+    return { action: 'rejected', noop: true };
+  }
+  const dir = path.dirname(draftPath);
+  try {
+    for (const f of fs.readdirSync(dir)) {
+      fs.unlinkSync(path.join(dir, f));
+    }
+    fs.rmdirSync(dir);
+  } catch (_e) {
+    // Best-effort.
+  }
+  return { action: 'rejected' };
+}
+
+/**
+ * Stamp `deferred_until` into the draft body. Draft remains in place.
+ */
+function applyDefer(draftPath, options) {
+  const opts = options || {};
+  if (!fs.existsSync(draftPath)) {
+    throw new Error(`KFM draft not found: ${draftPath}`);
+  }
+  const deferredUntil = opts.deferredUntil || new Date(Date.now() + 30 * 86_400_000).toISOString().slice(0, 10);
+  const orig = fs.readFileSync(draftPath, 'utf8');
+  let updated;
+  if (/^deferred_until:/m.test(orig)) {
+    updated = orig.replace(/^deferred_until:.*$/m, `deferred_until: ${deferredUntil}`);
+  } else {
+    updated = `${orig}\ndeferred_until: ${deferredUntil}\n`;
+  }
+  fs.writeFileSync(draftPath, updated);
+  return { action: 'deferred', deferredUntil };
+}
+
+/**
+ * Edit hook — returns the draft path so the caller can open `$EDITOR`.
+ * Caller re-renders the proposal after edit, per Phase 29-05 semantics.
+ */
+function applyEdit(draftPath, _options) {
+  if (!fs.existsSync(draftPath)) {
+    throw new Error(`KFM draft not found: ${draftPath}`);
+  }
+  return { action: 'edited', path: draftPath };
+}
+
+module.exports = {
+  proposeKfmDraft,
+  shouldPropose,
+  applyAccept,
+  applyReject,
+  applyDefer,
+  applyEdit,
+  // Exposed for tests / higher-level integration.
+  _deriveSlug: deriveSlug,
+  _nextKfmId: nextKfmId,
+  _normaliseInput: normaliseInput,
+  _REQUIRED_SCHEMA_FIELDS: REQUIRED_SCHEMA_FIELDS,
+  _DEFAULT_STABILITY_K: DEFAULT_STABILITY_K,
+  _DEFAULT_MATCHER_THRESHOLD: DEFAULT_MATCHER_THRESHOLD,
+};

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,27 @@ 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].
+
+## [KFM-CANDIDATE]
+
+KFM-catalogue proposals authored by `scripts/lib/reflector-kfm-proposer.cjs` (Phase 30.5-03 D-05) appear as a 6th proposal class. Drafts at `.design/reflections/incubator/kfm-<slug>/CATALOGUE-ENTRY.md`; pre-filled 11-field schema with `TODO:` placeholders for `pattern` + `fix`. Two upstream signals share the surface (D-06): `capability_gap` clusters (≥3, no existing match) + `kfm-candidate` events (whitelist-matched articles, 1-shot). User chooses **accept** | **reject** | **defer** | **edit**. `applyAccept` appends to `reference/known-failure-modes.md` + `reference/registry.json` (`origin: incubator-kfm`); `applyReject` removes the incubator subdir; `applyDefer` stamps `deferred_until`; `applyEdit` returns the draft path for `$EDITOR`. Full procedure: `./apply-reflections-procedure.md` §[KFM-CANDIDATE].
+
 ## 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.