@hegemonart/get-design-done 1.28.7 → 1.30.0

package/scripts/lib/apply-reflections/incubator-proposals.cjs

@@ -0,0 +1,448 @@
+// scripts/lib/apply-reflections/incubator-proposals.cjs — Plan 29-05
+//
+// Incubator-draft proposal class for /gdd:apply-reflections. Consumes drafts
+// authored by scripts/lib/incubator-author.cjs (Plan 29-04) at
+// `.design/reflections/incubator/<slug>/` and exposes the 7 actions surfaced
+// in skills/apply-reflections/SKILL.md.
+//
+// Exports: discoverIncubatorDrafts, renderProposal, applyAccept, applyReject,
+//          applyEdit, checkStage1Gate, recordOptIn.
+//
+// Decisions honoured:
+//   * D-01 — checkStage1Gate is read-only; recordOptIn is the sole writer and
+//            only fires on explicit user confirmation. No auto-flip ever.
+//   * D-04 — applyAccept performs the full draft → final-artifact write +
+//            registry append in one call. No intermediate state.
+//   * D-05 — applyAccept calls validateScope from
+//            scripts/validate-incubator-scope.cjs BEFORE any filesystem
+//            mutation. Failure throws; registry and incubator subdir
+//            untouched. Non-bypassable.
+//   * D-12 — DRAFT.md is copied verbatim, so the drafter's `delegate_to: null`
+//            frontmatter survives the promotion.
+//
+// Style: CommonJS, zero external deps (node:fs / node:path / node:child_process /
+//        node:os only).
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const child_process = require('node:child_process');
+const os = require('node:os');
+
+const { validateScope } = require('../../validate-incubator-scope.cjs');
+
+// ---  Constants  ---
+
+const DEFAULT_INCUBATOR_DIR = '.design/reflections/incubator';
+const DEFAULT_REGISTRY_PATH = 'reference/registry.json';
+const DEFAULT_GATE_SPEC_PATH = 'reference/capability-gap-stage-gate.md';
+const DEFAULT_STATE_PATH = '.planning/STATE.md';
+const OPT_IN_HEADING = '## Capability-gap Stage-1 opt-in';
+const OPT_IN_TOKEN_RE = /Stage-1 opt-in|capability.gap.*opt.in|confirmed_by/i;
+
+// ---  Helpers  ---
+
+function safeReadFileSync(p) {
+  try {
+    return fs.readFileSync(p, 'utf8');
+  } catch (_) {
+    return null;
+  }
+}
+
+function warn(msg) {
+  // Single-line stderr warning. Keeps SKILL.md UX clean.
+  process.stderr.write(`[incubator-proposals] WARN: ${msg}\n`);
+}
+
+function quoteArg(s) {
+  // Cross-platform quote: wrap in double quotes and escape embedded ones.
+  // Sufficient for tmpdir paths (no real shell metachars expected).
+  return `"${String(s).replace(/"/g, '\\"')}"`;
+}
+
+// ---  discoverIncubatorDrafts  ---
+
+/**
+ * Walk the incubator directory and return one Draft per valid slug. Malformed
+ * subdirs (missing/unparseable manifest, missing DRAFT.md) are skipped with a
+ * stderr warning; never throws.
+ */
+function discoverIncubatorDrafts(options) {
+  const o = options || {};
+  const incubatorDir = o.incubatorDir || DEFAULT_INCUBATOR_DIR;
+  if (!fs.existsSync(incubatorDir)) {
+    return [];
+  }
+
+  let entries;
+  try {
+    entries = fs.readdirSync(incubatorDir, { withFileTypes: true });
+  } catch (err) {
+    warn(`cannot read incubator dir ${incubatorDir}: ${err.message}`);
+    return [];
+  }
+
+  const drafts = [];
+  for (const ent of entries) {
+    if (!ent.isDirectory()) continue;
+    if (ent.name === 'archive') continue; // D-06: archived drafts not surfaced
+
+    const slugDir = path.join(incubatorDir, ent.name);
+    const manifestPath = path.join(slugDir, 'manifest.json');
+    const draftPath = path.join(slugDir, 'DRAFT.md');
+    const originPath = path.join(slugDir, 'ORIGIN.md');
+
+    if (!fs.existsSync(manifestPath)) {
+      warn(`skip ${slugDir}: missing manifest.json`);
+      continue;
+    }
+    if (!fs.existsSync(draftPath)) {
+      warn(`skip ${slugDir}: missing DRAFT.md`);
+      continue;
+    }
+    let manifest;
+    try {
+      manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    } catch (err) {
+      warn(`skip ${slugDir}: manifest.json parse error: ${err.message}`);
+      continue;
+    }
+    if (!manifest || typeof manifest !== 'object' || !manifest.slug || !manifest.kind || !manifest.target_path) {
+      warn(`skip ${slugDir}: manifest missing required fields (slug/kind/target_path)`);
+      continue;
+    }
+
+    drafts.push({
+      slug: manifest.slug,
+      kind: manifest.kind,
+      target_path: manifest.target_path,
+      draft_path: draftPath,
+      origin_path: fs.existsSync(originPath) ? originPath : null,
+      manifest,
+    });
+  }
+
+  // Deterministic ordering by slug ascending — matches incubator-author.cjs style.
+  drafts.sort((a, b) => (a.slug < b.slug ? -1 : a.slug > b.slug ? 1 : 0));
+  return drafts;
+}
+
+// ---  renderProposal  ---
+
+/**
+ * Render a draft as markdown: header (slug + kind), diff vs nearest existing
+ * artifact (or "net-new"), Origin section, full draft body.
+ */
+function renderProposal(draft, options) {
+  const o = options || {};
+  const resolver = typeof o.existingArtifactResolver === 'function' ? o.existingArtifactResolver : () => null;
+
+  const body = safeReadFileSync(draft.draft_path) || '';
+  const origin = draft.origin_path ? safeReadFileSync(draft.origin_path) : null;
+
+  const existing = resolver(draft.target_path);
+  let diffSection;
+  if (existing == null) {
+    diffSection = `### Diff vs existing\n\nNo existing artifact — net-new proposal.\n`;
+  } else {
+    diffSection = `### Diff vs existing\n\n\`\`\`diff\n--- ${draft.target_path} (existing)\n+++ ${draft.target_path} (proposed)\n${renderUnifiedDiff(existing, body)}\n\`\`\`\n`;
+  }
+
+  const originSection = origin
+    ? `## Origin\n\n${origin.trim()}\n`
+    : `## Origin\n\n(no ORIGIN.md found in incubator subdir)\n`;
+
+  return [
+    `## Proposal — ${draft.slug} (${draft.kind})`,
+    `Target: \`${draft.target_path}\``,
+    '',
+    diffSection,
+    originSection,
+    '### Draft body',
+    '',
+    body.trim(),
+    '',
+  ].join('\n');
+}
+
+/**
+ * Minimal unified-diff renderer (line-level, no LCS) for human review only.
+ * Not for round-trip patch application — that would need an actual diff
+ * library, which we deliberately avoid to keep deps at zero.
+ */
+function renderUnifiedDiff(oldText, newText) {
+  const oldLines = (oldText || '').split('\n');
+  const newLines = (newText || '').split('\n');
+  // Cheap diff: emit `-` for old lines absent in new, `+` for new lines
+  // absent in old, ` ` for shared lines. Order: all `-`, then all `+`.
+  const oldSet = new Set(oldLines);
+  const newSet = new Set(newLines);
+  const out = [];
+  for (const ln of oldLines) {
+    if (!newSet.has(ln)) out.push(`-${ln}`);
+  }
+  for (const ln of newLines) {
+    if (!oldSet.has(ln)) out.push(`+${ln}`);
+  }
+  if (out.length === 0) {
+    return '(no line-level differences)';
+  }
+  return out.join('\n');
+}
+
+// ---  applyAccept (D-04 + D-05)  ---
+
+/**
+ * Promote draft → final artifact + registry entry in one call (D-04).
+ *
+ * Order: validateScope (D-05; throws → no writes) → read DRAFT.md →
+ * [dryRun: return intent] → mkdirp parent → atomic-write target →
+ * append-and-atomic-write registry → fs.rm incubator subdir last
+ * (so partial failure leaves draft retryable — T-29.05-04).
+ */
+function applyAccept(draft, options) {
+  const o = options || {};
+  const repoRoot = o.repoRoot || process.cwd();
+  const registryPath = path.isAbsolute(o.registryPath || '')
+    ? o.registryPath
+    : path.join(repoRoot, o.registryPath || DEFAULT_REGISTRY_PATH);
+  const dryRun = !!o.dryRun;
+
+  // Step 1 — D-05 scope guard. THROWS on failure; registry untouched.
+  validateScope(draft.target_path, { repoRoot });
+
+  const draftBody = fs.readFileSync(draft.draft_path, 'utf8');
+  const targetAbs = path.resolve(repoRoot, draft.target_path);
+
+  const registryEntry = {
+    slug: draft.slug,
+    path: draft.target_path.replace(/\\/g, '/'),
+    added: new Date().toISOString(),
+    origin: 'incubator',
+  };
+
+  if (dryRun) {
+    return {
+      wouldWrite: draft.target_path.replace(/\\/g, '/'),
+      wouldRegister: registryEntry,
+      kind: draft.kind,
+    };
+  }
+
+  // Step 4 — mkdirp parent
+  fs.mkdirSync(path.dirname(targetAbs), { recursive: true });
+
+  // Step 5 — atomic write of target file
+  atomicWriteFileSync(targetAbs, draftBody);
+
+  // Step 6 — append registry entry
+  appendRegistryEntry(registryPath, draft.kind, registryEntry);
+
+  // Step 7 — remove incubator subdir last (partial-failure rollback safety)
+  const slugDir = path.dirname(path.resolve(draft.draft_path));
+  fs.rmSync(slugDir, { recursive: true, force: true });
+
+  return { accepted: true, path: draft.target_path.replace(/\\/g, '/') };
+}
+
+function atomicWriteFileSync(targetAbs, body) {
+  const tmp = `${targetAbs}.tmp-${process.pid}-${Date.now()}`;
+  fs.writeFileSync(tmp, body);
+  fs.renameSync(tmp, targetAbs);
+}
+
+function appendRegistryEntry(registryPath, kind, entry) {
+  let registry;
+  if (fs.existsSync(registryPath)) {
+    try {
+      registry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+    } catch (err) {
+      throw new Error(`[incubator-proposals] registry parse error at ${registryPath}: ${err.message}`);
+    }
+  } else {
+    registry = { agents: [], skills: [] };
+  }
+  if (!registry || typeof registry !== 'object') {
+    throw new Error(`[incubator-proposals] registry root must be an object: ${registryPath}`);
+  }
+
+  // Phase 14.5 self-authoring shape: { agents: [...], skills: [...] }.
+  // Initialize missing arrays additively so we never clobber another schema's data.
+  if (kind === 'agent') {
+    if (!Array.isArray(registry.agents)) registry.agents = [];
+    registry.agents.push(entry);
+  } else if (kind === 'skill') {
+    if (!Array.isArray(registry.skills)) registry.skills = [];
+    registry.skills.push(entry);
+  } else {
+    throw new Error(`[incubator-proposals] unknown kind: ${kind} (expected 'agent' or 'skill')`);
+  }
+
+  atomicWriteFileSync(registryPath, JSON.stringify(registry, null, 2) + '\n');
+}
+
+// ---  applyReject  ---
+
+/**
+ * Remove the incubator subdir for this draft. Registry untouched.
+ *
+ * @param {object} draft
+ * @returns {{rejected:true, slug:string}}
+ */
+function applyReject(draft) {
+  const slugDir = path.dirname(path.resolve(draft.draft_path));
+  fs.rmSync(slugDir, { recursive: true, force: true });
+  return { rejected: true, slug: draft.slug };
+}
+
+// ---  applyEdit  ---
+
+/**
+ * Open the user's editor ($EDITOR / editorEnv / 'vi' fallback) on a temp copy
+ * of DRAFT.md. On exit-0, copy edits back and return the reloaded draft. On
+ * non-zero exit, return {edited:false, reason}. editorEnv may include args
+ * (split on whitespace, e.g. "node /path/to/mock-editor.cjs").
+ */
+function applyEdit(draft, options) {
+  const o = options || {};
+  const editorEnv = o.editorEnv || process.env.EDITOR || 'vi';
+
+  // Write a temp copy
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'incu-edit-'));
+  const tmpFile = path.join(tmpDir, path.basename(draft.draft_path));
+  fs.copyFileSync(draft.draft_path, tmpFile);
+
+  try {
+    // Two invocation modes:
+    //   options.editorCmd: [exec, ...args]  -- no shell, fully tokenized
+    //   options.editorEnv: shell command line (default: $EDITOR or 'vi')
+    // The array form avoids shell quoting headaches for Windows editor paths
+    // that contain spaces (e.g. node.exe installed under a Program-Files
+    // location) in tests.
+    let r;
+    if (Array.isArray(o.editorCmd) && o.editorCmd.length) {
+      const [cmd, ...args] = o.editorCmd;
+      r = child_process.spawnSync(cmd, args.concat([tmpFile]), { stdio: 'inherit' });
+    } else {
+      const cmdline = `${editorEnv} ${quoteArg(tmpFile)}`;
+      r = child_process.spawnSync(cmdline, { stdio: 'inherit', shell: true });
+    }
+
+    if (r.status !== 0) {
+      return { edited: false, reason: 'editor_aborted', exit_code: r.status };
+    }
+
+    // Copy edited tmp back over the draft
+    fs.copyFileSync(tmpFile, draft.draft_path);
+
+    // Reload the draft so target_path / manifest re-sync if anything in
+    // the editor changed (manifest itself is not edited here, but the body
+    // may have changed). discoverIncubatorDrafts re-reads manifest.json.
+    const incubatorDir = path.dirname(path.dirname(path.resolve(draft.draft_path)));
+    const all = discoverIncubatorDrafts({ incubatorDir });
+    const reloaded = all.find((d) => d.slug === draft.slug);
+    return reloaded || { edited: false, reason: 'draft_vanished_post_edit' };
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
+// ---  checkStage1Gate (D-01: read-only)  ---
+
+/**
+ * Read-only Stage-1 gate inspection (D-01).
+ *   thresholdMet  = count(registry entries with origin === 'incubator') ≥ K
+ *   optInRecorded = state file contains an opt-in token
+ *   summary       = human-readable one-liner
+ * Reads only — never writes. Surfacing the threshold is a prompt, not a flip.
+ */
+function checkStage1Gate(options) {
+  const o = options || {};
+  const gateSpecPath = o.gateSpecPath || DEFAULT_GATE_SPEC_PATH;
+  const statePath = o.statePath || DEFAULT_STATE_PATH;
+  const registryPath = o.registryPath || DEFAULT_REGISTRY_PATH;
+
+  const K = readK(gateSpecPath);
+
+  let acceptedCount = 0;
+  const regSrc = safeReadFileSync(registryPath);
+  if (regSrc) {
+    try {
+      const reg = JSON.parse(regSrc);
+      const skills = Array.isArray(reg.skills) ? reg.skills : [];
+      const agents = Array.isArray(reg.agents) ? reg.agents : [];
+      for (const e of skills.concat(agents)) {
+        if (e && e.origin === 'incubator') acceptedCount += 1;
+      }
+    } catch (_) {
+      // Malformed registry — treat as zero accepted; do not throw.
+    }
+  }
+
+  const thresholdMet = acceptedCount >= K;
+
+  const stateSrc = safeReadFileSync(statePath) || '';
+  const optInRecorded = OPT_IN_TOKEN_RE.test(stateSrc);
+
+  return {
+    thresholdMet,
+    summary: `${acceptedCount} of ${K} incubator-origin entries accepted` +
+      (thresholdMet ? ' (Stage-1 gate met)' : ' (Stage-1 gate not yet met)'),
+    optInRecorded,
+  };
+}
+
+/**
+ * Pull `K` out of capability-gap-stage-gate.md. The doc encodes K as a row
+ * in a markdown table:  `| K | 3 | Minimum number of stable clusters... |`.
+ * If absent or unparseable, fall back to 3 (Phase 29 D-03 default).
+ */
+function readK(gateSpecPath) {
+  const src = safeReadFileSync(gateSpecPath);
+  if (!src) return 3;
+  const m = src.match(/\|\s*`?K`?\s*\|\s*`?(\d+)`?\s*\|/);
+  if (!m) return 3;
+  const v = parseInt(m[1], 10);
+  return Number.isFinite(v) && v > 0 ? v : 3;
+}
+
+// ---  recordOptIn (D-01: explicit-only)  ---
+
+/**
+ * Persist the user's explicit Stage-1 opt-in to STATE.md. Idempotent.
+ * IMPORTANT: this is the SOLE state writer in this module. Only invoke after
+ * explicit user confirmation in the apply-reflections UX (D-01).
+ */
+function recordOptIn(options) {
+  const o = options || {};
+  const statePath = o.statePath || DEFAULT_STATE_PATH;
+  const confirmedBy = o.confirmedBy || 'user';
+
+  const existing = safeReadFileSync(statePath) || '';
+  if (OPT_IN_TOKEN_RE.test(existing)) {
+    return { alreadyRecorded: true };
+  }
+
+  const at = new Date().toISOString();
+  const block =
+    `\n${OPT_IN_HEADING}\n\n` +
+    `- recorded_at: ${at}\n` +
+    `- confirmed_by: ${confirmedBy}\n`;
+  const next = existing + (existing.endsWith('\n') ? '' : '\n') + block;
+  atomicWriteFileSync(statePath, next);
+  return { optInRecorded: true, at, confirmedBy };
+}
+
+// ---  Exports  ---
+
+module.exports = {
+  discoverIncubatorDrafts,
+  renderProposal,
+  applyAccept,
+  applyReject,
+  applyEdit,
+  checkStage1Gate,
+  recordOptIn,
+};

package/scripts/lib/bandit-router.cjs

@@ -26,6 +26,18 @@
  *     neutral — the same TIER_PRIOR shape, on the assumption that we
  *     have no prior to favour any delegate over local; data drives.
  *
+ * Bootstrap discipline (Phase 29 Plan 06 / CONTEXT D-04):
+ *   - Default `prior_class` (omitted or 'default'): existing informed
+ *     TIER_PRIOR bootstrap (Phase 23.5) — byte-for-byte unchanged.
+ *   - `prior_class: 'promoted_incubator'`: Beta(2, 8) bootstrap for
+ *     arms registered when `/gdd:apply-reflections accept` promotes
+ *     an incubator draft. The conservative prior (posterior mean 0.2)
+ *     suppresses preferential selection until ~8-10 successful pulls
+ *     accumulate. The bandit-fairness gate IS the promotion staging
+ *     mechanism (D-04: no two-step staging/ratify split).
+ *   - The `prior_class` value is persisted on the arm so subsequent
+ *     reads + decay calculations preserve it (forward-compat).
+ *
  * Atomic .tmp + rename. Discounted Thompson via per-arm time-decay
  * factor `rho^days_since_last_use` applied at sample time, not stored.
  *
@@ -59,6 +71,14 @@ const TIER_PRIOR = Object.freeze({
 const PRIOR_STRENGTH = 10;
 const DEFAULT_TIERS = Object.freeze(['haiku', 'sonnet', 'opus']);
 
+// Phase 29 Plan 06 / CONTEXT D-04. Conservative prior for arms
+// bootstrapped via `/gdd:apply-reflections accept` (incubator → live
+// agent/skill). Beta(2, 8) — posterior mean 0.2 — suppresses
+// preferential selection until ~8-10 successful pulls accumulate.
+// The bandit-fairness gate IS the staging mechanism (D-04: no
+// two-step staging/ratify split).
+const PROMOTED_INCUBATOR_PRIOR = Object.freeze({ alpha: 2, beta: 8 });
+
 // Plan 27-07 / D-08. Delegate context dimension. 'none' = local Anthropic
 // call; the other 5 are peer-CLI delegations via ACP/ASP. Adding this as
 // a third context dimension expands the arm space 6× (78 → ~468 contexts).
@@ -158,7 +178,26 @@ function reset(opts = {}) {
   return { deleted: existed, path: p, reason: opts.reason };
 }
 
-function priorFor(tier, strength) {
+/**
+ * Compute the bootstrap prior for a freshly-created arm.
+ *
+ * @param {string} tier
+ * @param {number} strength
+ * @param {string} [prior_class] — 'default' (existing behaviour, omittable)
+ *   or 'promoted_incubator' (Beta(2,8) bootstrap per Phase 29 Plan 06 /
+ *   CONTEXT D-04). The promoted-incubator class is tier-independent —
+ *   the conservative suppression applies uniformly across haiku/sonnet/
+ *   opus until evidence accumulates.
+ * @returns {{alpha: number, beta: number}}
+ */
+function priorFor(tier, strength, prior_class) {
+  if (prior_class === 'promoted_incubator') {
+    return {
+      alpha: PROMOTED_INCUBATOR_PRIOR.alpha,
+      beta: PROMOTED_INCUBATOR_PRIOR.beta,
+    };
+  }
+  // Default-path (Phase 23.5) — byte-for-byte unchanged.
   const prior = TIER_PRIOR[tier];
   if (prior === undefined) {
     return { alpha: strength / 2, beta: strength / 2 };
@@ -207,11 +246,17 @@ function findArm(arms, agent, bin, tier, delegate) {
  * 23.5 prior — no migration needed because the legacy slice and the
  * 'none' slice are independent contexts) and for the 5 peer delegates
  * (each starts neutral with the same TIER_PRIOR shape; data drives).
+ *
+ * For Phase 29 Plan 06: when `prior_class === 'promoted_incubator'`, the
+ * bootstrap prior is Beta(2, 8) regardless of tier/delegate (CONTEXT D-04).
+ * The `prior_class` is persisted on the arm so re-reads + decay preserve it.
+ * If omitted or 'default', no `prior_class` field is added (clean
+ * round-trip with existing posterior files — non-breaking change).
  */
-function ensureArm(posterior, agent, bin, tier, strength, delegate) {
+function ensureArm(posterior, agent, bin, tier, strength, delegate, prior_class) {
   let arm = findArm(posterior.arms, agent, bin, tier, delegate);
   if (arm) return arm;
-  const { alpha, beta } = priorFor(tier, strength);
+  const { alpha, beta } = priorFor(tier, strength, prior_class);
   arm = {
     agent,
     bin,
@@ -224,6 +269,9 @@ function ensureArm(posterior, agent, bin, tier, strength, delegate) {
   if (delegate !== undefined) {
     arm.delegate = delegate;
   }
+  if (prior_class !== undefined && prior_class !== 'default') {
+    arm.prior_class = prior_class;
+  }
   posterior.arms.push(arm);
   return arm;
 }
@@ -312,7 +360,10 @@ function decayArm(arm, opts = {}) {
  * counters. Bandit pull does NOT update the success/fail counters —
  * that happens in `update()` once the outcome is known.
  *
- * @param {{agent: string, bin: string, tiers?: string[], baseDir?: string, posteriorPath?: string, decay?: number, strength?: number, now?: Date}} input
+ * @param {{agent: string, bin: string, tiers?: string[], baseDir?: string, posteriorPath?: string, decay?: number, strength?: number, now?: Date, prior_class?: string}} input
+ *   `prior_class` (optional, Phase 29 Plan 06 / D-04): 'promoted_incubator'
+ *   bootstraps fresh arms with Beta(2,8). Omitting it preserves Phase 23.5
+ *   informed-prior behaviour (non-breaking).
  * @returns {{tier: string, samples: Record<string, number>, posteriorPath: string}}
  */
 function pull(input) {
@@ -332,7 +383,7 @@ function pull(input) {
   let bestTier = tiers[0];
   let bestSample = -1;
   for (const tier of tiers) {
-    const arm = ensureArm(posterior, input.agent, input.bin, tier, strength);
+    const arm = ensureArm(posterior, input.agent, input.bin, tier, strength, undefined, input.prior_class);
     const decayed = decayArm(arm, { decay: input.decay, now, strength });
     const s = sampleBeta(decayed.alpha, decayed.beta);
     samples[tier] = s;
@@ -342,7 +393,7 @@ function pull(input) {
     }
   }
   // Bump counters on the chosen arm.
-  const chosen = ensureArm(posterior, input.agent, input.bin, bestTier, strength);
+  const chosen = ensureArm(posterior, input.agent, input.bin, bestTier, strength, undefined, input.prior_class);
   chosen.last_used = now.toISOString();
   chosen.count += 1;
   const written = savePosterior(posterior, input);
@@ -353,7 +404,11 @@ function pull(input) {
  * Update the posterior with a reward signal. Reward is applied as a
  * Bernoulli observation: success → α += reward, β += (1 - reward).
  *
- * @param {{agent: string, bin: string, tier: string, reward: number, baseDir?: string, posteriorPath?: string, strength?: number}} input
+ * @param {{agent: string, bin: string, tier: string, reward: number, baseDir?: string, posteriorPath?: string, strength?: number, prior_class?: string}} input
+ *   `prior_class` (optional, Phase 29 Plan 06 / D-04): 'promoted_incubator'
+ *   bootstraps fresh arms with Beta(2,8). Omitting preserves Phase 23.5
+ *   informed-prior behaviour (non-breaking). The reward math is unchanged
+ *   — `prior_class` only affects bootstrap, not the Bernoulli update.
  * @returns {{alpha: number, beta: number, posteriorPath: string}}
  */
 function update(input) {
@@ -369,7 +424,15 @@ function update(input) {
   // Reward must be in [0, 1].
   const r = Math.min(1, Math.max(0, input.reward));
   const posterior = loadPosterior(input);
-  const arm = ensureArm(posterior, input.agent, input.bin, input.tier, input.strength ?? PRIOR_STRENGTH);
+  const arm = ensureArm(
+    posterior,
+    input.agent,
+    input.bin,
+    input.tier,
+    input.strength ?? PRIOR_STRENGTH,
+    undefined,
+    input.prior_class,
+  );
   arm.alpha += r;
   arm.beta += 1 - r;
   const p = savePosterior(posterior, input);
@@ -401,7 +464,11 @@ function update(input) {
  *   decay?: number,
  *   strength?: number,
  *   now?: Date,
+ *   prior_class?: string,
  * }} input
+ *   `prior_class` (optional, Phase 29 Plan 06 / D-04): 'promoted_incubator'
+ *   bootstraps fresh arms with Beta(2,8). Omitting preserves Phase 23.5 +
+ *   Plan 27-07 behaviour (non-breaking).
  * @returns {{
  *   tier: string,
  *   delegate: string,
@@ -435,7 +502,15 @@ function pullWithDelegate(input) {
   for (const delegate of delegates) {
     samples[delegate] = {};
     for (const tier of tiers) {
-      const arm = ensureArm(posterior, input.agent, input.bin, tier, strength, delegate);
+      const arm = ensureArm(
+        posterior,
+        input.agent,
+        input.bin,
+        tier,
+        strength,
+        delegate,
+        input.prior_class,
+      );
       const decayed = decayArm(arm, { decay: input.decay, now, strength });
       const s = sampleBeta(decayed.alpha, decayed.beta);
       samples[delegate][tier] = s;
@@ -453,6 +528,7 @@ function pullWithDelegate(input) {
     bestTier,
     strength,
     bestDelegate,
+    input.prior_class,
   );
   chosen.last_used = now.toISOString();
   chosen.count += 1;
@@ -482,7 +558,12 @@ function pullWithDelegate(input) {
  *   baseDir?: string,
  *   posteriorPath?: string,
  *   strength?: number,
+ *   prior_class?: string,
  * }} input
+ *   `prior_class` (optional, Phase 29 Plan 06 / D-04): 'promoted_incubator'
+ *   bootstraps fresh arms with Beta(2,8). Omitting preserves Plan 27-07
+ *   behaviour (non-breaking). The reward math is unchanged — `prior_class`
+ *   only affects bootstrap, not the Bernoulli update.
  * @returns {{alpha: number, beta: number, posteriorPath: string}}
  */
 function updateWithDelegate(input) {
@@ -506,6 +587,7 @@ function updateWithDelegate(input) {
     input.tier,
     input.strength ?? PRIOR_STRENGTH,
     input.delegate,
+    input.prior_class,
   );
   arm.alpha += r;
   arm.beta += 1 - r;
@@ -569,6 +651,7 @@ module.exports = {
   DELEGATE_NONE,
   TIER_PRIOR,
   PRIOR_STRENGTH,
+  PROMOTED_INCUBATOR_PRIOR,
   TOUCHES_BINS,
   DEFAULT_POSTERIOR_PATH,
   SCHEMA_VERSION,