@hegemonart/get-design-done 1.28.8 → 1.30.0

package/scripts/lib/reflector-capability-gap-aggregator.cjs

@@ -0,0 +1,320 @@
+/**
+ * reflector-capability-gap-aggregator.cjs — Plan 29-03.
+ *
+ * Aggregates `capability_gap` events (emitted by Plans 29-01 + 29-02) into
+ * per-cycle cluster rollups and evaluates the Stage-0 → Stage-1 gate (D-01).
+ *
+ * Three exports:
+ *
+ *   aggregateCapabilityGaps(eventsOrPath, opts?)
+ *     - Accepts an iterable of events OR a path string to a JSONL chain file.
+ *     - Returns { clusters: Cluster[] } where each Cluster is:
+ *         { id: string,                // first 12 chars of context_hash
+ *           size: number,
+ *           sources: { fast, router, reflector_pattern },
+ *           examples: string[]         // up to 3 evidence_ref strings
+ *         }
+ *     - Filters to records where (record.type === 'capability_gap'
+ *       OR record.outcome === 'capability_gap') AND payload.context_hash is
+ *       a non-empty string. Other rows are ignored silently.
+ *     - Clusters are ordered: size DESC, id ASC tie-break.
+ *
+ *   renderGapsSection(clusters)
+ *     - Returns a markdown string. Empty list → '' (no section emitted).
+ *     - Non-empty → '## Capability gaps observed' header + table.
+ *
+ *   evaluateStageGate(history, config)
+ *     - history: [{ cycle_slug, clusters }] — at least 1 cycle.
+ *     - config: { K, M, stddev_threshold }. Defaults: K=3, M=10, threshold=0.05.
+ *     - Returns { crossed, stable_cluster_ids, cycles_observed }.
+ *     - A cluster is "stable" iff: appears in ≥ M consecutive cycles AND
+ *       posterior `stddev(Beta(α, β)) < threshold`, where
+ *       α = appearances + 1, β = (cycles_observed - appearances) + 1
+ *       (Laplace prior; matches Phase 23.5 posterior store).
+ *     - D-01 honored: this function EMITS A DECISION ONLY. The caller
+ *       prompts the user. No auto-stage-flip path exists in this module.
+ *
+ * D-11 compliance: this module is a pure reader. All tests use synthetic
+ * fixtures (tests/reflector-capability-gap-aggregation.test.cjs).
+ */
+
+'use strict';
+
+const { readFileSync, existsSync } = require('node:fs');
+
+const DEFAULT_GATE_CONFIG = Object.freeze({
+  K: 3,
+  M: 10,
+  stddev_threshold: 0.05,
+});
+
+const ALLOWED_SOURCES = ['fast', 'router', 'reflector_pattern'];
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+
+/**
+ * Return a fresh source-count bucket.
+ */
+function emptySources() {
+  return { fast: 0, router: 0, reflector_pattern: 0 };
+}
+
+/**
+ * Iterate events from either an in-memory iterable or a JSONL path string.
+ * Yields parsed records; invalid JSON lines are skipped silently (matches
+ * `event-chain.cjs.readChain` and `event-stream/reader.ts.readEvents`).
+ */
+function* iterateRecords(eventsOrPath) {
+  if (eventsOrPath == null) return;
+  if (typeof eventsOrPath === 'string') {
+    if (!existsSync(eventsOrPath)) return;
+    const raw = readFileSync(eventsOrPath, 'utf8');
+    for (const line of raw.split('\n')) {
+      const trimmed = line.trim();
+      if (trimmed === '') continue;
+      try {
+        yield JSON.parse(trimmed);
+      } catch (_err) {
+        // Malformed JSON — skip (matches existing readers' tolerance).
+      }
+    }
+    return;
+  }
+  if (typeof eventsOrPath[Symbol.iterator] === 'function' ||
+      typeof eventsOrPath[Symbol.asyncIterator] === 'function') {
+    for (const rec of eventsOrPath) {
+      if (rec != null) yield rec;
+    }
+    return;
+  }
+  // Unsupported input shape — yield nothing.
+}
+
+/**
+ * Test whether a parsed record is a capability_gap event with a usable
+ * context_hash. Either the envelope `type` OR the chain-level `outcome`
+ * may carry the marker — `appendChainEvent` writes both.
+ */
+function isCapabilityGap(rec) {
+  if (rec == null || typeof rec !== 'object') return false;
+  const typeMatch = rec.type === 'capability_gap';
+  const outcomeMatch = rec.outcome === 'capability_gap';
+  if (!typeMatch && !outcomeMatch) return false;
+  const ctxHash = rec.payload && rec.payload.context_hash;
+  return typeof ctxHash === 'string' && ctxHash.length > 0;
+}
+
+/**
+ * Stringify an evidence_ref entry for the markdown example column. If it's
+ * already a string, return it; otherwise prefer `trajectory_path` and fall
+ * back to a JSON.stringify so the test can still match.
+ */
+function refToExample(ref) {
+  if (typeof ref === 'string') return ref;
+  if (ref && typeof ref === 'object') {
+    if (typeof ref.trajectory_path === 'string') return ref.trajectory_path;
+    try { return JSON.stringify(ref); } catch (_e) { return '[ref]'; }
+  }
+  return String(ref);
+}
+
+/**
+ * Closed-form posterior stddev of Beta(α, β):
+ *   stddev = sqrt(αβ / ((α+β)^2 * (α+β+1)))
+ * No external math dependency. α + β > 0 (Laplace prior guarantees this).
+ */
+function betaStddev(alpha, beta) {
+  const sum = alpha + beta;
+  if (sum <= 0) return Infinity;
+  const variance = (alpha * beta) / (sum * sum * (sum + 1));
+  return Math.sqrt(variance);
+}
+
+/**
+ * Sanitize config — coerce to defaults if missing / invalid. Mirrors
+ * the trust-boundary mitigation in 29-03-PLAN.md threat T-29.03-02.
+ */
+function normalizeConfig(input) {
+  const out = { ...DEFAULT_GATE_CONFIG };
+  if (!input || typeof input !== 'object') return out;
+  if (Number.isInteger(input.K) && input.K > 0) out.K = input.K;
+  if (Number.isInteger(input.M) && input.M > 0) out.M = input.M;
+  if (typeof input.stddev_threshold === 'number'
+      && Number.isFinite(input.stddev_threshold)
+      && input.stddev_threshold > 0
+      && input.stddev_threshold <= 1) {
+    out.stddev_threshold = input.stddev_threshold;
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+
+/**
+ * Aggregate capability_gap events into per-context_hash clusters.
+ *
+ * @param {Iterable<object> | string} eventsOrPath
+ * @param {{ exampleLimit?: number }} [opts]
+ * @returns {{ clusters: Array<{ id: string, size: number, sources: {fast:number,router:number,reflector_pattern:number}, examples: string[] }> }}
+ */
+function aggregateCapabilityGaps(eventsOrPath, opts = {}) {
+  const exampleLimit = Number.isInteger(opts.exampleLimit) && opts.exampleLimit > 0
+    ? opts.exampleLimit : 3;
+
+  /** @type {Map<string, { id: string, size: number, sources: object, examples: string[], _hash: string }>} */
+  const byHash = new Map();
+
+  for (const rec of iterateRecords(eventsOrPath)) {
+    if (!isCapabilityGap(rec)) continue;
+    const payload = rec.payload;
+    const fullHash = payload.context_hash;
+    const id = fullHash.slice(0, 12);
+    let cluster = byHash.get(fullHash);
+    if (!cluster) {
+      cluster = { id, size: 0, sources: emptySources(), examples: [], _hash: fullHash };
+      byHash.set(fullHash, cluster);
+    }
+    cluster.size += 1;
+    const src = payload.source;
+    if (ALLOWED_SOURCES.includes(src)) {
+      cluster.sources[src] += 1;
+    }
+    if (Array.isArray(payload.evidence_refs)) {
+      for (const ref of payload.evidence_refs) {
+        if (cluster.examples.length >= exampleLimit) break;
+        cluster.examples.push(refToExample(ref));
+      }
+    }
+  }
+
+  const clusters = Array.from(byHash.values());
+  clusters.sort((a, b) => {
+    if (b.size !== a.size) return b.size - a.size;
+    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+  });
+  // Strip internal full-hash field from output (not part of public Cluster shape).
+  for (const c of clusters) delete c._hash;
+  return { clusters };
+}
+
+/**
+ * Render the markdown section appended to a reflector cycle file.
+ * Returns '' when clusters is empty — caller appends unconditionally.
+ *
+ * @param {Array} clusters
+ * @returns {string}
+ */
+function renderGapsSection(clusters) {
+  if (!Array.isArray(clusters) || clusters.length === 0) return '';
+  const lines = [];
+  lines.push('## Capability gaps observed');
+  lines.push('');
+  lines.push('| Cluster | Size | fast | router | reflector_pattern | Example evidence |');
+  lines.push('|---|---|---|---|---|---|');
+  for (const c of clusters) {
+    const examples = (c.examples || [])
+      .slice(0, 3)
+      .map((e) => '`' + e + '`')
+      .join(', ');
+    lines.push(
+      `| \`${c.id}\` | ${c.size} | ${c.sources.fast || 0} | ${c.sources.router || 0} | ${c.sources.reflector_pattern || 0} | ${examples} |`,
+    );
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+/**
+ * Evaluate the Stage-0 → Stage-1 gate per D-01 + D-03.
+ *
+ * @param {Array<{ cycle_slug: string, clusters: Array }>} history
+ * @param {{ K?: number, M?: number, stddev_threshold?: number }} [config]
+ * @returns {{ crossed: boolean, stable_cluster_ids: string[], cycles_observed: number }}
+ */
+function evaluateStageGate(history, config) {
+  const cfg = normalizeConfig(config);
+  if (!Array.isArray(history)) {
+    return { crossed: false, stable_cluster_ids: [], cycles_observed: 0 };
+  }
+
+  const cycles_observed = history.length;
+
+  // Need at least M cycles observed before we can evaluate stability.
+  if (cycles_observed < cfg.M) {
+    return { crossed: false, stable_cluster_ids: [], cycles_observed };
+  }
+
+  // Stability checks per D-03:
+  //   1. Consecutive-presence: cluster appears in M consecutive cycles
+  //      (the most recent run is the most reliable signal of "still here").
+  //   2. Posterior stddev: Beta(α, β) with α = appearances + 1,
+  //      β = (cycles_observed - appearances) + 1 — Laplace prior matches
+  //      Phase 23.5's bandit-router posterior store.
+  //
+  // Appearance counts use the FULL history (cycles_observed = history.length)
+  // so a cluster that has been present for many cycles accumulates evidence,
+  // even if it occasionally missed a cycle. The consecutive-presence check
+  // uses only the most recent run length (must be ≥ M).
+
+  /** @type {Map<string, number>} appearances across full history */
+  const appearances = new Map();
+  /** @type {Map<string, number>} most recent consecutive-presence run */
+  const currentRun = new Map();
+  /** @type {Map<string, number>} longest consecutive-presence run seen */
+  const maxConsecutive = new Map();
+
+  for (const cycle of history) {
+    const presentThisCycle = new Set();
+    if (Array.isArray(cycle.clusters)) {
+      for (const c of cycle.clusters) {
+        if (c && typeof c.id === 'string') {
+          presentThisCycle.add(c.id);
+        }
+      }
+    }
+    // Update appearance counts + consecutive runs for every id we've
+    // seen so far OR seen this cycle.
+    const allIds = new Set([...currentRun.keys(), ...presentThisCycle]);
+    for (const id of allIds) {
+      if (presentThisCycle.has(id)) {
+        appearances.set(id, (appearances.get(id) || 0) + 1);
+        const run = (currentRun.get(id) || 0) + 1;
+        currentRun.set(id, run);
+        if (run > (maxConsecutive.get(id) || 0)) {
+          maxConsecutive.set(id, run);
+        }
+      } else {
+        // Cluster missed this cycle — reset current run; max already captured.
+        currentRun.set(id, 0);
+      }
+    }
+  }
+
+  const stable_cluster_ids = [];
+  for (const [id, appCount] of appearances.entries()) {
+    const maxRun = maxConsecutive.get(id) || 0;
+    if (maxRun < cfg.M) continue; // must appear in M consecutive cycles
+    // Laplace prior (Phase 23.5): α = appearances+1, β = (cycles-appearances)+1
+    const alpha = appCount + 1;
+    const beta = (cycles_observed - appCount) + 1;
+    const sd = betaStddev(alpha, beta);
+    if (sd < cfg.stddev_threshold) {
+      stable_cluster_ids.push(id);
+    }
+  }
+
+  stable_cluster_ids.sort();
+  const crossed = stable_cluster_ids.length >= cfg.K;
+  return { crossed, stable_cluster_ids, cycles_observed };
+}
+
+module.exports = {
+  aggregateCapabilityGaps,
+  renderGapsSection,
+  evaluateStageGate,
+  // Exported for testing / introspection only:
+  _betaStddev: betaStddev,
+  _DEFAULT_GATE_CONFIG: DEFAULT_GATE_CONFIG,
+};

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.

package/skills/apply-reflections/apply-reflections-procedure.md

@@ -1,10 +1,10 @@
 ---
 name: apply-reflections-procedure
 type: heuristic
-version: 1.0.0
+version: 1.2.0
 phase: 28.5
-tags: [apply-reflections, proposal, frontmatter, reference, budget, question, global-skill]
-last_updated: 2026-05-18
+tags: [apply-reflections, proposal, frontmatter, reference, budget, question, global-skill, incubator]
+last_updated: 2026-05-20
 ---
 
 # Apply-Reflections — Per-Type Procedure
@@ -66,3 +66,71 @@ the proposal's bracketed type tag.
 
 5. Print: "Global skill written to ~/.claude/gdd/global-skills/<name>.md — auto-loads in all future gdd sessions"
 6. Append `**Applied**: <date>` to proposal in reflections file
+
+### [INCUBATOR]
+
+Incubator drafts come from `scripts/lib/incubator-author.cjs` (Phase 29-04). They live at
+`.design/reflections/incubator/<slug>/` and contain `manifest.json` + `DRAFT.md` + (optional) `ORIGIN.md`.
+
+Use `scripts/lib/apply-reflections/incubator-proposals.cjs` for all actions.
+
+**Discovery + render** (once per cycle):
+
+1. Call `discoverIncubatorDrafts()` → `Array<Draft>`. Skip malformed entries silently (already warned on stderr by the helper).
+2. For each draft: call `renderProposal(draft)` and print the returned markdown block. The user sees a header (slug + kind), a diff vs the nearest existing artifact (or "net-new"), an Origin section listing capability-gap signals, and the full draft body.
+3. Prompt: `(a) accept   (r) reject   (d) defer   (e) edit   (q) quit`.
+
+**Per-action behavior:**
+
+1. **accept** — call `applyAccept(draft, { registryPath, repoRoot })`.
+   - The helper calls `validateScope(draft.target_path)` from `scripts/validate-incubator-scope.cjs` **before** any write. Out-of-scope paths throw and the registry stays untouched. This is the non-bypassable scope guard (D-05).
+   - On success: target artifact written, `reference/registry.json` appended with `{ slug, path, added, origin: 'incubator' }`, incubator subdir removed last (T-29.05-04 — partial-failure leaves draft retryable).
+   - Print: "Accepted — promoted to <target_path>; registered."
+   - Append `**Applied**: <date>` to the proposal block.
+
+2. **reject** — call `applyReject(draft)`. Only the incubator subdir is removed; registry is untouched. Append `**Reviewed: rejected**` to the reflections file.
+
+3. **defer** — no-op. Print "Deferred — draft re-surfaces next run." Append `**Reviewed: deferred**`.
+
+4. **edit** — call `applyEdit(draft)` (uses `$EDITOR` or the `editorCmd` array option). On clean exit, the helper reloads the draft and the caller re-runs `renderProposal` + the prompt. On non-zero exit, the original draft is preserved unchanged.
+
+**Stage-1 gate (D-01 — no auto-flip):**
+
+1. At the start of the cycle, call `checkStage1Gate({ gateSpecPath, statePath, registryPath })`. The call is **read-only** — never mutates state. The returned `{ thresholdMet, summary, optInRecorded }` is informational.
+2. If `thresholdMet && !optInRecorded`, surface a one-time prompt:
+   ```
+   Stage-1 capability-gap authoring threshold met: <summary>
+   Enable incubator-draft promotion?  (y/N)
+   ```
+3. **Only on explicit `y`**, call `recordOptIn({ statePath, confirmedBy })`. The function is idempotent — a second call detects the existing record and returns `{ alreadyRecorded: true }`. Never call it on any other input.
+
+**Why this is gated.** The `[INCUBATOR]` proposal class can write executable surface (agents + skills) into the plugin runtime. Both Phase 29 D-01 (no auto-flip) and D-05 (scope guard) exist because that surface has integration-test and security implications that exceed reflector autonomy. `validateScope` keeps the file landing zone confined to `agents/<slug>.md` or `skills/<slug>/SKILL.md`. The Stage-1 gate keeps the *whether* of opting in to incubator authoring under explicit user control even after the data threshold says we have enough signal.
+
+**Bandit-fairness gate on `accept` (Phase 29 Plan 06 / CONTEXT D-04).**
+
+When the `accept` action promotes an incubator draft, the bandit-router arms for the freshly-promoted agent/skill MUST be bootstrapped with `prior_class: 'promoted_incubator'`. This invokes a conservative `Beta(2, 8)` bootstrap prior (posterior mean 0.2) instead of the optimistic Phase 23.5 informed prior — the bandit-fairness gate IS the staging mechanism (D-04: no separate two-step ratify split). The conservative prior suppresses preferential selection until ~8-10 successful pulls accumulate.
+
+Call shape (whether eagerly invoked on promotion or via first-pull lazy bootstrap):
+
+```javascript
+const bandit = require('./scripts/lib/bandit-router.cjs');
+// Per arm bootstrapped for the freshly-promoted agent:
+bandit.update({
+  agent: '<promoted-slug>',
+  bin: '<touches-bin>',
+  tier: '<chosen-tier>',
+  reward: <bernoulli>,
+  prior_class: 'promoted_incubator',  // Phase 29 Plan 06 / D-04 — Beta(2,8) staging
+});
+// Or for the delegate-aware case (Plan 27-07):
+bandit.updateWithDelegate({
+  agent: '<promoted-slug>',
+  bin: '<touches-bin>',
+  tier: '<chosen-tier>',
+  delegate: '<peer-cli-or-none>',
+  reward: <bernoulli>,
+  prior_class: 'promoted_incubator',
+});
+```
+
+Omitting `prior_class` reverts to Phase 23.5 informed-prior bootstrap (non-breaking). The reward math is unchanged — `prior_class` only affects bootstrap.

package/skills/fast/SKILL.md

@@ -41,5 +41,51 @@ The leanest possible execution path. No subagents, no STATE.md update, no DESIGN
 - No STATE.md mutation.
 - No pipeline stage invocation.
 - Do not proceed if the change turns out to be non-trivial — bail out and recommend `/gdd:quick` or the full pipeline.
+- Do not skip the `capability_gap` emit on bail-out — Stage-0 telemetry depends on it (Phase 29 D-01).
+
+## Emitting capability_gap on no-skill-match
+
+If step 2 cannot locate any candidate files for the task description (or all candidates are filtered out as off-topic), or if the change in step 4 turns out to be non-trivial in a way that has no obvious resolution without a dedicated skill/agent, emit ONE `capability_gap` event before returning control to the user. This feeds Phase 29 Stage-0 telemetry — the reflector pattern-detection pass (Plan 29-02) and aggregation (Plan 29-03) read these events from the chain file (`.design/gep/events.jsonl`) to surface recurring capability gaps in `/gdd:apply-reflections`.
+
+Synchronous emitter call (via Bash):
+
+```bash
+node -e '
+const { appendChainEvent } = require("./scripts/lib/event-chain.cjs");
+const { createHash, randomUUID } = require("node:crypto");
+const intent = process.env.GDD_INTENT || "";
+const payload = {
+  event_id: randomUUID(),
+  parent_event_id: null,
+  source: "fast",
+  context_hash: createHash("sha256").update(intent).digest("hex"),
+  intent_summary: intent.slice(0, 256),
+  suggested_kind: "skill",
+  evidence_refs: [],
+};
+appendChainEvent({
+  agent: "fast",
+  outcome: "capability_gap",
+  payload,
+  type: "capability_gap",
+  timestamp: new Date().toISOString(),
+  sessionId: process.env.GDD_SESSION_ID || "fast-cli",
+});
+'
+```
+
+Notes:
+- `evidence_refs` is empty `[]` for fast (no trajectory in `/gdd:fast` — that path is too lean by design).
+- `parent_event_id` is null (root event for the fast bail-out).
+- `suggested_kind` is `"skill"` because fast bail-outs are usually narrow primitives, not multi-step workflows. Plan 29-03's aggregator may upgrade to `"agent"` if a `context_hash` cluster shows multi-step usage.
+- The emitter MUST NOT block — `appendChainEvent` already swallows IO errors via its existing try/catch (see `scripts/lib/event-chain.cjs:97-105`).
+- The 7-field payload is preserved verbatim through `appendChainEvent`'s opaque-extras pattern; the chain row carries `type`, `timestamp`, `sessionId`, `payload` as opaque caller-supplied fields and is projected back to the events-schema envelope shape by readers (Plan 29-03 aggregator).
+
+Trigger conditions:
+- **Trigger 1**: Step 2 returns zero candidate files for the task description (target is genuinely missing).
+- **Trigger 2**: Step 2 returns more than 2 candidates AND the user bail-out in step 2 fires (stop and ask).
+- **Trigger 3**: Step 4 reveals the change is non-trivial in a way that has no obvious primitive resolution (the `## Do Not` "Do not proceed" line fires).
+
+MCP-probe failures (connection down, transport-layer errors) do NOT emit `capability_gap` — those are Phase 22 connection-status concerns (D-08).
 
 ## FAST COMPLETE