@aperant/framework 0.17.0 → 0.20.0

package/dist/cli/produce/verification-ttl.mjs

@@ -0,0 +1,169 @@
+/**
+ * @internal
+ * produce/verification-ttl.mjs — verification-TTL: a rotating sample of OLD done
+ * milestones re-verified against HEAD each tick, regressions flagged +
+ * compensated (M4, ID-M4-03 / AC13).
+ *
+ * Verification is not permanent — a milestone marked `done` at HEAD-sha `A` can
+ * silently regress as HEAD advances to `B` (a later milestone's change breaks an
+ * earlier one). This module gives verification a TTL:
+ *
+ *   - `selectTtlReverifySample` REUSES M2's `selectSweepSample` for the rotating
+ *     done-milestone candidates (do NOT invent a parallel rotation) and annotates
+ *     staleness against the supplied HEAD sha — a done milestone is STALE when its
+ *     last recorded `produce.ttl.reverified`/`produce.probe.run` head_sha ≠ the
+ *     current HEAD (or it has never been re-verified since done); a milestone last
+ *     re-verified against the current HEAD is EXCLUDED as FRESH.
+ *   - `recordTtlReverify` REUSES the M2 cross-family guard (refuses a same-family
+ *     re-verify), appends `produce.ttl.reverified`, and on `fail` ALSO appends
+ *     `produce.ttl.regression_detected` AND fires the FORWARD compensator via
+ *     saga.mjs::compensatePhase({phase:'verify'}) — a revert-branch + reopen +
+ *     re-plan, NEVER a merged-PR rollback (ID-M4-03).
+ *
+ * `ttl.reverified` is a DISTINCT op from `probe.run` (a scheduled post-`done` TTL
+ * re-check vs a first-time done-gate probe) so the forensic trail stays clean —
+ * only the ROTATION and the CROSS-FAMILY GUARD are reused. This module records +
+ * computes; the actual re-verify RUN + the revert-ship/reopen/re-plan EXECUTION
+ * is the OOS dispatch layer.
+ */
+import { selectSweepSample } from './blind-probe.mjs';
+import { appendProduceEvent, readImplementerFamily, readProduceRunEventsMatching, } from './events.mjs';
+import { normalizeFamily } from './probe-family.mjs';
+import { projectRoadmap } from './projection.mjs';
+import { compensatePhase } from './saga.mjs';
+/**
+ * Build the per-milestone latest-recorded head_sha map from the
+ * `produce.ttl.reverified` + `produce.probe.run` events (both carry `head_sha`).
+ * Chronological fold — the last recorded run for a milestone wins.
+ *
+ * @param {string} projectDir
+ * @param {string} runId
+ * @returns {Map<string, { head_sha: string, at: string | null }>}
+ */
+function latestReverifyByMilestone(projectDir, runId) {
+    const events = readProduceRunEventsMatching(projectDir, runId, (op) => op === 'produce.ttl.reverified' || op === 'produce.probe.run');
+    const map = new Map();
+    for (const e of events) {
+        const d = e.data || {};
+        const id = typeof d.milestone_id === 'string' ? d.milestone_id : null;
+        const sha = typeof d.head_sha === 'string' ? d.head_sha : null;
+        if (!id || !sha)
+            continue;
+        map.set(id, { head_sha: sha, at: typeof e.t === 'string' ? e.t : null });
+    }
+    return map;
+}
+/**
+ * Select a DETERMINISTIC rotating sample of already-`done` milestones STALE
+ * against HEAD (ID-M4-03 / AC7). REUSES `selectSweepSample` for the rotation
+ * order (fewest/oldest last-probe-run first), then annotates each candidate with
+ * staleness against `headSha` and FILTERS OUT the FRESH ones (last re-verified
+ * against the current HEAD). Returns the first `sample` STALE candidates. An
+ * absent HEAD sha fails closed (nothing selected).
+ *
+ * @param {string} projectDir
+ * @param {string} runId
+ * @param {{ headSha: string, sample?: number }} args
+ * @returns {{ run_id: string, head_sha: string | null, sample_size: number,
+ *   selected: Array<{ milestone_id: string, title: string, last_reverify_head_sha: string | null, last_reverify_at: string | null, stale: boolean }> }}
+ */
+export function selectTtlReverifySample(projectDir, runId, { headSha, sample = 1 } = {}) {
+    if (!headSha)
+        return { run_id: runId, head_sha: null, sample_size: 0, selected: [] };
+    // The FULL rotation-ordered pool of done milestones (reuse selectSweepSample;
+    // pass the done count so it returns every done milestone in rotation order).
+    const doneCount = projectRoadmap(projectDir, runId).milestones.filter((m) => m.status === 'done').length;
+    const pool = selectSweepSample(projectDir, runId, { sample: doneCount || 1 }).selected;
+    const latest = latestReverifyByMilestone(projectDir, runId);
+    const n = Number.isFinite(sample) && sample > 0 ? Math.floor(sample) : 1;
+    const stale = [];
+    for (const candidate of pool) {
+        const last = latest.get(candidate.milestone_id) || null;
+        // STALE when never re-verified since done, or last re-verified against a sha
+        // ≠ the current HEAD. FRESH (last re-verify head_sha === HEAD) is excluded.
+        const isStale = !last || last.head_sha !== headSha;
+        if (!isStale)
+            continue;
+        stale.push({
+            milestone_id: candidate.milestone_id,
+            title: candidate.title,
+            last_reverify_head_sha: last?.head_sha ?? null,
+            last_reverify_at: last?.at ?? null,
+            stale: true,
+        });
+    }
+    const selected = stale.slice(0, n);
+    return { run_id: runId, head_sha: headSha, sample_size: selected.length, selected };
+}
+/**
+ * Record a scheduled TTL re-verify RUN against HEAD (ID-M4-03). REUSES the M2
+ * cross-family guard (refuses a same-family re-verify, or when no implementer
+ * family is recorded). Appends `produce.ttl.reverified {run_id, milestone_id,
+ * head_sha, result}`; on `result === 'fail'` ALSO appends
+ * `produce.ttl.regression_detected` AND fires the FORWARD compensator via
+ * saga.mjs::compensatePhase({phase:'verify', reason:'ttl_regression@<sha>'}) — a
+ * revert-branch + reopen + re-plan, NEVER a merged-PR rollback. A `pass`
+ * refreshes verification against the new HEAD and logs no regression.
+ *
+ * @param {string} projectDir
+ * @param {{ runId: string, milestoneId: string, result: string, probeFamily: string, headSha: string }} args
+ * @returns {{ ok: true, result: string, probe_family: string, head_sha: string, regression: boolean, compensator: object | null }
+ *   | { ok: false, reason: string }}
+ */
+export function recordTtlReverify(projectDir, { runId, milestoneId, result, probeFamily, headSha }) {
+    if (result !== 'pass' && result !== 'fail')
+        return { ok: false, reason: 'invalid_result' };
+    if (!headSha)
+        return { ok: false, reason: 'no_head_sha' };
+    if (!probeFamily)
+        return { ok: false, reason: 'no_probe_family' };
+    const implementerFamily = readImplementerFamily(projectDir, runId, milestoneId);
+    if (!implementerFamily)
+        return { ok: false, reason: 'no_recorded_implementer' };
+    // Cross-family enforcement (normalized so claude-code === claude).
+    if (normalizeFamily(probeFamily) === normalizeFamily(implementerFamily))
+        return { ok: false, reason: 'same_family_reverify' };
+    appendProduceEvent(projectDir, 'produce.ttl.reverified', {
+        run_id: runId,
+        milestone_id: milestoneId,
+        head_sha: headSha,
+        result,
+    });
+    let regression = false;
+    let compensator = null;
+    if (result === 'fail') {
+        // The regression flags the milestone AND fires the FORWARD compensator — a
+        // revert-branch + reopen + re-plan, never a merged-PR rollback (ID-M4-03).
+        appendProduceEvent(projectDir, 'produce.ttl.regression_detected', {
+            run_id: runId,
+            milestone_id: milestoneId,
+            head_sha: headSha,
+        });
+        const comp = compensatePhase(projectDir, {
+            runId,
+            milestoneId,
+            phase: 'verify',
+            reason: `ttl_regression@${headSha}`,
+        });
+        regression = true;
+        compensator = comp.ok ? comp.compensator : null;
+    }
+    return { ok: true, result, probe_family: probeFamily, head_sha: headSha, regression, compensator };
+}
+/**
+ * Read-only fold of the run's `produce.ttl.regression_detected` events (for saga
+ * status / canary context). Chronological order.
+ *
+ * @param {string} projectDir
+ * @param {string} runId
+ * @returns {Array<{ milestone_id: string | null, head_sha: string | null, t: string | null }>}
+ */
+export function listRegressions(projectDir, runId) {
+    const events = readProduceRunEventsMatching(projectDir, runId, (op) => op === 'produce.ttl.regression_detected');
+    return events.map((e) => ({
+        milestone_id: e.data && typeof e.data.milestone_id === 'string' ? e.data.milestone_id : null,
+        head_sha: e.data && typeof e.data.head_sha === 'string' ? e.data.head_sha : null,
+        t: typeof e.t === 'string' ? e.t : null,
+    }));
+}
+//# sourceMappingURL=verification-ttl.mjs.map

package/dist/cli/produce/verification-ttl.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"verification-ttl.mjs","sourceRoot":"","sources":["../../../src/cli/produce/verification-ttl.mjs"],"names":[],"mappings":"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"}

package/dist/cli/release-notes/ship-autodraft.mjs

@@ -6,8 +6,8 @@
  * should grow a `Release note: …` line OR ship should block.
  *
  * This module is intentionally pure — the apt-ship SKILL.md body shells
- * `apt-tools features-audit . --diff-since <base> --json` and feeds the
- * envelope here. Keeping the decision pure makes TD-4 trivial: fixture in,
+ * `apt-tools features-reconcile . --draft --dry-run --base "$base"` and feeds
+ * the envelope here. Keeping the decision pure makes TD-4 trivial: fixture in,
  * decision out, no I/O.
  */
 import { buildPersonaTierMap, classifyFragment } from './persona-filter.mjs';

package/dist/cli/roadmap/{conductor-view.d.mts → showrunner-view.d.mts}

@@ -1,13 +1,13 @@
 /**
- * Build a flat per-scope roadmap snapshot for the Conductor.
+ * Build a flat per-scope roadmap snapshot for the Showrunner.
  *
  * @param {string} projectRoot
  * @returns {{ scopes: Array<{ scope: string, roadmap: unknown }> }}
  */
-export function buildConductorRoadmapView(projectRoot: string): {
+export function buildShowrunnerRoadmapView(projectRoot: string): {
     scopes: Array<{
         scope: string;
         roadmap: unknown;
     }>;
 };
-//# sourceMappingURL=conductor-view.d.mts.map
+//# sourceMappingURL=showrunner-view.d.mts.map

package/dist/cli/roadmap/showrunner-view.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"showrunner-view.d.mts","sourceRoot":"","sources":["../../../src/cli/roadmap/showrunner-view.mjs"],"names":[],"mappings":"AAgBA;;;;;GAKG;AACH,wDAHW,MAAM,GACJ;IAAE,MAAM,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAA;CAAE,CAUlE"}

package/dist/cli/roadmap/{conductor-view.mjs → showrunner-view.mjs}

@@ -1,24 +1,24 @@
 /**
- * conductor-view.mjs — read-only roadmap surface for the Aperant
- * Conductor's `getRoadmap` tool.
+ * showrunner-view.mjs — read-only roadmap surface for the Aperant
+ * Showrunner's `getRoadmap` tool.
  *
- * Wraps `loadRoadmapForScope` + `listRoadmapScopes` so the Conductor sees
+ * Wraps `loadRoadmapForScope` + `listRoadmapScopes` so the Showrunner sees
  * the same overlay-aware view every framework command sees. Direct reads
  * of `.aperant/roadmap/*\/phases/*.json` or `milestones.json` would miss
  * the dual-write overlay (seed_id from legacy blob, etc.) — Codex
  * roundtable correction #3.
  *
- * Step 5 of Conductor v2 ship order.
+ * Step 5 of Showrunner v2 ship order.
  */
 import { loadRoadmapForScope } from './io.mjs';
 import { listRoadmapScopes } from './paths.mjs';
 /**
- * Build a flat per-scope roadmap snapshot for the Conductor.
+ * Build a flat per-scope roadmap snapshot for the Showrunner.
  *
  * @param {string} projectRoot
  * @returns {{ scopes: Array<{ scope: string, roadmap: unknown }> }}
  */
-export function buildConductorRoadmapView(projectRoot) {
+export function buildShowrunnerRoadmapView(projectRoot) {
     const scopes = listRoadmapScopes(projectRoot);
     const out = [];
     for (const scope of scopes) {
@@ -28,4 +28,4 @@ export function buildConductorRoadmapView(projectRoot) {
     }
     return { scopes: out };
 }
-//# sourceMappingURL=conductor-view.mjs.map
+//# sourceMappingURL=showrunner-view.mjs.map

package/dist/cli/roadmap/showrunner-view.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"showrunner-view.mjs","sourceRoot":"","sources":["../../../src/cli/roadmap/showrunner-view.mjs"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAA;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAE/C;;;;;GAKG;AACH,MAAM,UAAU,0BAA0B,CAAC,WAAW;IACrD,MAAM,MAAM,GAAG,iBAAiB,CAAC,WAAW,CAAC,CAAA;IAC7C,MAAM,GAAG,GAAG,EAAE,CAAA;IACd,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC5B,MAAM,OAAO,GAAG,mBAAmB,CAAC,WAAW,EAAE,KAAK,CAAC,CAAA;QACvD,IAAI,OAAO,KAAK,IAAI;YAAE,GAAG,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAA;IACnD,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,CAAA;AACvB,CAAC"}

package/dist/cli/variant/gallery.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"gallery.d.mts","sourceRoot":"","sources":["../../../src/cli/variant/gallery.mjs"],"names":[],"mappings":"AA8CA;;;;;GAKG;AACH,qCAHW,YAAY,GACV,MAAM,CAkFlB;AAID;;;;;;;;;GASG;AACH,uDAJW,MAAM,EAAE,kBACR,MAAM,CAAC,MAAM,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAAC,GAClE;IAAE,QAAQ,EAAE,cAAc,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAyB7D;6BArJY;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE;2BAC1E;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,cAAc,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE"}
+{"version":3,"file":"gallery.d.mts","sourceRoot":"","sources":["../../../src/cli/variant/gallery.mjs"],"names":[],"mappings":"AAkDA;;;;;GAKG;AACH,qCAHW,YAAY,GACV,MAAM,CAkFlB;AAID;;;;;;;;;GASG;AACH,uDAJW,MAAM,EAAE,kBACR,MAAM,CAAC,MAAM,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAAC,GAClE;IAAE,QAAQ,EAAE,cAAc,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAyB7D;6BArJY;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE;2BAC1E;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,cAAc,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE"}

package/dist/cli/variant/gallery.mjs

@@ -12,6 +12,10 @@
  *     no privilege for that).  Picking happens by running a terminal
  *     command — the gallery's job is to make the letter obvious and the
  *     command copy-pasteable.
+ *   - Each card links to its variant file via a plain relative anchor
+ *     with target="_blank", so the user can open any variant full-size
+ *     in a new tab straight from the gallery (relative hrefs resolve
+ *     against the gallery's own file:// URL — no server needed).
  *   - Responsive grid: 1 column on narrow, 2 on medium, N on wide.
  *   - Each variant iframe is rendered at full device-width-feel, not a
  *     thumbnail, so the user can actually read the content.
@@ -74,11 +78,11 @@ export function renderGallery(input) {
             `              <div class="truncate text-xs text-slate-400">${description}</div>`,
             '            </div>',
             '          </div>',
-            `          <code class="shrink-0 rounded bg-slate-800 px-2 py-1 text-xs text-slate-300">${filename}</code>`,
+            `          <a href="${filename}" target="_blank" rel="noopener" title="Open variant ${letter} in a new tab" class="shrink-0 rounded bg-slate-800 px-2 py-1 text-xs text-slate-300 hover:bg-slate-700 hover:text-slate-100"><code>${filename}</code> ↗</a>`,
             '        </header>',
             `        <iframe src="${filename}" title="Variant ${letter}" loading="lazy" class="block h-[720px] w-full bg-white"></iframe>`,
             '        <footer class="flex items-center justify-between gap-3 border-t border-slate-800 px-4 py-3">',
-            `          <div class="text-xs text-slate-500">Pick this one:</div>`,
+            `          <a href="${filename}" target="_blank" rel="noopener" class="text-xs font-medium ${ACCENT} hover:underline">Open full size ↗</a>`,
             `          <code class="rounded bg-slate-800 px-2 py-1 text-xs text-slate-100">/apt:mockup --pick ${letter.toLowerCase()}</code>`,
             '        </footer>',
             '      </article>',
@@ -104,7 +108,7 @@ export function renderGallery(input) {
         '        <div>',
         `          <div class="text-xs uppercase tracking-[0.2em] text-slate-500">Variant gallery · iteration ${iterationEsc}</div>`,
         `          <h1 class="mt-1 text-2xl font-semibold text-slate-100">${featureEsc}</h1>`,
-        `          <p class="mt-1 text-sm text-slate-400">${variants.length} parallel generations. Open this page via <code>file://</code>, scan the iframes, pick the letter that lands.</p>`,
+        `          <p class="mt-1 text-sm text-slate-400">${variants.length} parallel generations. Open this page via <code>file://</code>, scan the iframes, click “Open full size” to view any variant in its own tab, then pick the letter that lands.</p>`,
         '        </div>',
         '        <div class="flex flex-col gap-2 text-xs text-slate-400 sm:items-end">',
         `          <div>Directory: <code class="text-slate-300">${taskDirEsc}/mockups/</code></div>`,

package/dist/cli/variant/gallery.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"gallery.mjs","sourceRoot":"","sources":["../../../src/cli/variant/gallery.mjs"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;GAGG;AAEH,qEAAqE;AACrE,sEAAsE;AACtE,8DAA8D;AAC9D,MAAM,UAAU,GAAG,cAAc,CAAA;AACjC,MAAM,YAAY,GAAG,gBAAgB,CAAA;AACrC,MAAM,MAAM,GAAG,iBAAiB,CAAA;AAEhC;;;;GAIG;AACH,SAAS,UAAU,CAAC,CAAC;IACpB,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,EAAE,CAAA;IACpC,OAAO,CAAC;SACN,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC;SACtB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;SACrB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;SACrB,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC;SACvB,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;AACzB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,KAAK;IAClC,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,KAAK,CAAA;IACvD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvD,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAA;IACrE,CAAC;IAED,wEAAwE;IACxE,yEAAyE;IACzE,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,CAAA;IACzC,MAAM,QAAQ,GAAG,gBAAgB,IAAI,EAAE,CAAA;IAEvC,MAAM,KAAK,GAAG,QAAQ;SACpB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACV,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,CAAC,CAAA;QACzD,MAAM,KAAK,GAAG,UAAU,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC,CAAA;QACvC,MAAM,WAAW,GAAG,UAAU,CAAC,CAAC,CAAC,WAAW,IAAI,EAAE,CAAC,CAAA;QACnD,MAAM,QAAQ,GAAG,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAA;QAEvC,4DAA4D;QAC5D,kEAAkE;QAClE,OAAO;YACN,yGAAyG;YACzG,sGAAsG;YACtG,iDAAiD;YACjD,0HAA0H,MAAM,KAAK,MAAM,SAAS;YACpJ,mCAAmC;YACnC,4EAA4E,KAAK,IAAI,SAAS,QAAQ;YACtG,8DAA8D,WAAW,QAAQ;YACjF,oBAAoB;YACpB,kBAAkB;YAClB,0FAA0F,QAAQ,SAAS;YAC3G,mBAAmB;YACnB,wBAAwB,QAAQ,oBAAoB,MAAM,oEAAoE;YAC9H,sGAAsG;YACtG,oEAAoE;YACpE,oGAAoG,MAAM,CAAC,WAAW,EAAE,SAAS;YACjI,mBAAmB;YACnB,kBAAkB;SAClB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACb,CAAC,CAAC;SACD,IAAI,CAAC,IAAI,CAAC,CAAA;IAEZ,MAAM,UAAU,GAAG,UAAU,CAAC,OAAO,CAAC,CAAA;IACtC,MAAM,YAAY,GAAG,UAAU,CAAC,SAAS,CAAC,CAAA;IAC1C,MAAM,UAAU,GAAG,UAAU,CAAC,OAAO,CAAC,CAAA;IAEtC,OAAO;QACN,iBAAiB;QACjB,kBAAkB;QAClB,UAAU;QACV,8BAA8B;QAC9B,4EAA4E;QAC5E,gCAAgC,UAAU,eAAe,YAAY,WAAW;QAChF,yDAAyD;QACzD,uBAAuB,YAAY,eAAe,UAAU,MAAM;QAClE,WAAW;QACX,kBAAkB,UAAU,IAAI,YAAY,gBAAgB;QAC5D,gEAAgE;QAChE,uEAAuE;QACvE,eAAe;QACf,wGAAwG,YAAY,QAAQ;QAC5H,oEAAoE,UAAU,OAAO;QACrF,oDAAoD,QAAQ,CAAC,MAAM,mHAAmH;QACtL,gBAAgB;QAChB,+EAA+E;QAC/E,0DAA0D,UAAU,wBAAwB;QAC5F,uJAAuJ;QACvJ,gBAAgB;QAChB,iBAAiB;QACjB,2DAA2D,QAAQ,IAAI;QACvE,KAAK;QACL,cAAc;QACd,gEAAgE;QAChE,2EAA2E,YAAY,MAAM,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE;QACvH,iBAAiB;QACjB,aAAa;QACb,WAAW;QACX,SAAS;QACT,EAAE;KACF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACb,CAAC;AAED,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAA;AAE7D;;;;;;;;;GASG;AACH,MAAM,UAAU,2BAA2B,CAAC,SAAS,EAAE,aAAa,GAAG,EAAE;IACxE,MAAM,EAAE,GAAG,2CAA2C,CAAA;IACtD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAE,CAAA;IACtB,MAAM,OAAO,GAAG,EAAE,CAAA;IAClB,KAAK,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;QAC7B,MAAM,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;QACvB,IAAI,CAAC,CAAC,EAAE,CAAC;YACR,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;YACjB,SAAQ;QACT,CAAC;QACD,MAAM,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAA;QACjC,MAAM,IAAI,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,EAAE,CAAA;QACxC,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE;YAChB,MAAM;YACN,QAAQ,EAAE,GAAG;YACb,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,WAAW,EAAE,IAAI,CAAC,WAAW;SAC7B,CAAC,CAAA;IACH,CAAC;IACD,MAAM,QAAQ,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAC3D,CAAC,CAAC,EAAE,EAAE,CAAC,6BAA6B,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAClD,CAAA;IACD,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAA;AAC7B,CAAC"}
+{"version":3,"file":"gallery.mjs","sourceRoot":"","sources":["../../../src/cli/variant/gallery.mjs"],"names":[],"mappings":"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"}

package/dist/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "aperant",
-  "version": "0.17.0",
+  "version": "0.20.0",
   "description": "AI coding framework — composable skills for planning, executing, verifying, and reviewing code with any LLM provider. Works as Claude Code commands, Codex tasks, or programmatically.",
   "author": {
     "name": "Mikalsen AI",
@@ -45,6 +45,7 @@
     "skills/apt-personas",
     "skills/apt-plan",
     "skills/apt-pr-review",
+    "skills/apt-produce",
     "skills/apt-prototype",
     "skills/apt-quick",
     "skills/apt-release-notes",

package/dist/plugin/agents/apt-executor.md

@@ -103,6 +103,12 @@ node packages/framework/bin/apt-tools.mjs commit "feat: {subtask.title}" --files
 ```
 Update `implementation_plan.json` status to `"completed"`. Write `build-progress.json`.
 
+**Delta-emit (feature registry).** After the commit, scaffold this subtask's registry delta and enrich it while the build context is still in your window:
+```bash
+node packages/framework/bin/apt-tools.mjs features-reconcile . --draft --task-id {task-id} --subtask-id {subtask.id}
+```
+Fill every `needs-disposition` entry (`upsert` / `remove` / `wiring-transition` / `no-semantic-change` — the last needs a one-line `reason`), assign any `area: null`, and replace draft upsert stubs with real `sub_features` carrying `wired`/`handler`/`test_hint`. Then stage the delta and amend it into the subtask commit: `git add .aperant/features/deltas/ && git commit --amend --no-edit`. Non-blocking: on a reconcile glitch, log and continue — the ship gate + CI check catch real gaps.
+
 ### 3f. Checkpoint State
 `build-progress.json` is written every subtask in 3e — that is the durable resume point. Do NOT self-estimate context. Do NOT voluntarily exit. Keep executing until the plan is complete or a risk gate stops you. If the harness auto-compacts mid-run, re-read `{task_dir}/implementation_plan.json` + `{task_dir}/build-progress.json` after compaction and continue from the next pending subtask — the checkpoint is authoritative, your in-memory state is not.
 

package/dist/plugin/agents/apt-planner.md

@@ -190,8 +190,9 @@ Two policy buckets, two behaviors:
   finding if you omit it.
 - **`auto-update`** (default for milestones.json, REGISTRY.md,
   project_index.json, .aperant/tasks/**): a doc subtask that invokes the
-  appropriate apt-tools subcommand (`features-audit --apply-stubs`,
-  `roadmap rollup`, etc.) so the internal state stays coherent.
+  appropriate apt-tools subcommand (`features-reconcile --draft` at the
+  executor's delta-emit step, `roadmap rollup`, etc.) so the internal
+  state stays coherent.
 
 Bias toward false positives — a no-op doc subtask costs nothing; a missed
 drift finding ships to the user. Full rules in

package/dist/plugin/skills/apt/SKILL.md

@@ -17,7 +17,7 @@ execution_modes:
   - plan-mode
   - plan-only
   - research
-allowed-tools: "Bash, Read, Grep, Glob, Write, Edit, Task"
+allowed-tools: "Bash, Read, Grep, Glob, Task"
 argument-hint: "[free-text task or /apt <skill> …]"
 gates: []
 ---
@@ -234,12 +234,19 @@ Resolve the track, then create a fresh task record before invoking the skill.
    - `plan` → `STANDARD`
    - everything else with `task_context: create-new` → `STANDARD`
 
-Then run:
+Then run the deterministic allocator (NOT raw `task create`):
 
 ```bash
-node packages/framework/bin/apt-tools.mjs task create . --description "{slug}" --track {track} --autonomy {autonomy} [--scope {scope}]
+node packages/framework/bin/apt-tools.mjs task ensure . --description "{slug}" --intent create-new --track {track} --autonomy {autonomy} [--scope {scope}]
 ```
 
+`task ensure --intent create-new` is idempotent (re-running the same
+input returns the SAME task + worktree, `reused: true`) and resolves the
+effective autonomy from `config.autonomy.default` BEFORE provisioning the
+worktree — so allocation is host-agnostic and never depends on this prose
+being followed. The `allocation_intent` here is `create-new` because the
+skill's `task_context` is `create-new` (the four-value taxonomy maps 1:1).
+
 **Security note:** Do NOT interpolate `{skill_args}` directly into `--description "..."`. `skill_args` is verbatim user input and can contain double-quote characters that break out of the argument boundary and inject extra flags (e.g. `--autonomy`, `--scope`). The task slug is sufficient as the description; `skill_args` is passed to the skill separately after the task record is created.
 
 (Use `--scope framework` only when the user is on a framework-scoped task —
@@ -300,29 +307,41 @@ The router emitted a `classify` envelope. This is the main routing path —
 all free-text input and every flag-override (--quick/--deep/--debug) lands
 here.
 
-### Brainstorm hand-off (check FIRST, before picking a skill)
-
-**Before picking a skill from the envelope,** scan the user's input for
-signals that they want to *explore a vision* rather than *commit to a task*.
-If present, dispatch to `apt:discuss --brainstorm` and stop. Don't inline
-the exploration — the brainstorm posture lives in its own skill with its
-own fresh context and its own artifact shape.
-
-Signals — any one triggers the hand-off:
-- Vision statements: *"here's what I want to build"*, *"my goal is..."*, *"the idea is..."*
-- Open invitations: *"let's think about"*, *"let's brainstorm"*, *"help me figure out"*, *"what's the best way..."*
-- Paragraph-shaped input describing an outcome or direction, not a single work item
-- Explicit "before we plan, let's explore / think / brainstorm..."
-
-How to hand off:
-```
-[APT] Detected brainstorm intent — routing to /apt:discuss --brainstorm
-```
-Then invoke the `/apt:discuss --brainstorm` skill with the user's input and stop.
-
-**Task-shaped input (continue to Step 0):** concrete work item, specific
-deliverable, or existing task being continued. Examples: *"add OAuth login"*,
-*"fix the view-tracking bug"*, *"migrate reports to JSONB"*.
+### allocation_intent — the single LLM bit (decide FIRST, before picking a skill)
+
+The ONLY allocation judgment you make on the free-text path is a single
+schema-bounded `allocation_intent ∈ {create-new | require-existing |
+self-managed | none}` (the SAME four-value taxonomy as skill `task_context`).
+**Fail-closed default is `none`** — when in doubt, allocate nothing. There is
+no separate prose-only brainstorm gate that can bypass allocation; the
+brainstorm decision is just the `none` outcome of this one judgment.
+
+Map the user's input to one bit:
+
+- **`none`** — vision / exploration / investigation / status / help. The user
+  wants to *explore a vision* or *ask a question*, not commit to a work item.
+  Allocate NOTHING (no task, no worktree) and dispatch to `apt:discuss
+  --brainstorm` (or the picked investigative skill). Signals — any one →
+  `none`:
+  - Vision statements: *"here's what I want to build"*, *"my goal is..."*, *"the idea is..."*
+  - Open invitations: *"let's think about"*, *"let's brainstorm"*, *"help me figure out"*, *"what's the best way..."*
+  - Paragraph-shaped input describing an outcome or direction, not a single work item
+  - Explicit "before we plan, let's explore / think / brainstorm..."
+
+  How to hand off:
+  ```
+  [APT] allocation_intent=none (brainstorm/investigation) — routing to /apt:discuss --brainstorm
+  ```
+  Then invoke `/apt:discuss --brainstorm` with the user's input and stop.
+
+- **`self-managed`** — the picked skill owns its own task/worktree lifecycle
+  (e.g. `apt:run`, `apt:pr-review`). Allocate nothing here; let the skill do it.
+- **`require-existing`** — the user is continuing an existing task. Do NOT mint;
+  resolve the active task (Step 2 uses `task ensure --intent require-existing`).
+- **`create-new`** — concrete work item / specific deliverable that needs a
+  fresh task + worktree. Examples: *"add OAuth login"*, *"fix the view-tracking
+  bug"*, *"migrate reports to JSONB"*. Continue to Step 0; Step 2 provisions
+  deterministically via `task ensure --intent create-new`.
 
 ### Step 0a: Flag-override fast path (envelope.track is set)
 
@@ -332,6 +351,15 @@ carries `track`, `primary_skill`, `spawn_agent`, `agent`, and `options`.
 **Skip Step 0b and Step 0c — go straight to Step 1.** These were locked
 by the user typing `--quick` / `--deep` / `--debug`, not by the host LLM.
 
+**allocation_intent (flag-override is deterministic — no LLM judgment):**
+map `primary_skill` → `allocation_intent`:
+- `quick` → `create-new`
+- `debug` → `create-new`
+- `plan` → `create-new` (STANDARD / DEEP)
+- a skill whose `task_context` is `self-managed` (e.g. `run`) → `self-managed`
+
+Step 2 forwards this bit to `task ensure --intent <bit>`.
+
 ### Step 0b: Classify the skill (envelope.skills[] inline pick)
 
 When `classification.source: "host-model-deferred"` (free-text path),
@@ -405,15 +433,31 @@ Map choice: full auto → `execution_mode = "auto"`, step by step → `"step"`,
 
 If `needs_autonomy_prompt` is false (user passed --yolo/--autonomous), skip this — use `execution_mode` from route result.
 
-### Step 2: Register Task
+### Step 2: Register Task (deterministic allocation)
+
+Forward the `allocation_intent` decided above (Step 0a flag-override map,
+or the free-text bit from the allocation_intent section) to the
+deterministic, idempotent allocator — NOT raw `task create`:
 
 ```bash
-node packages/framework/bin/apt-tools.mjs task create . --description "{task_description}" --track {track} --autonomy {autonomy}
+node packages/framework/bin/apt-tools.mjs task ensure . --description "{task_description}" --intent {allocation_intent} --track {track} --autonomy {autonomy}
 ```
 
+- `--intent create-new` provisions a fresh task + worktree, idempotent on
+  re-run (`reused: true` returns the SAME task/worktree — re-issuing `/apt`
+  never duplicates). Effective autonomy is resolved from
+  `config.autonomy.default` BEFORE the worktree hook, so a
+  `from_branch: current` base is not spuriously deferred.
+- `--intent require-existing` resolves the active task WITHOUT minting
+  (returns `requires_input` on ambiguity — fall back to the
+  skill-passthrough resolution chain prompt).
+- `--intent none` / `--intent self-managed` allocate nothing
+  (`allocated: false`) — you should already have dispatched per the
+  allocation_intent section above and not reached Step 2.
+
 Parse `task_id`, `task_dir`, and (if present) `worktree.worktree_path` / `worktree.branch` / `worktree.base_branch` from the result.
 
-**Task-level worktree isolation:** when `task_isolation.worktree_per_task` is enabled (check via `host_capabilities.worktrees` + `task_isolation` in the route result) and `task create` returns a `worktree` block, every subsequent Bash call AND every spawned agent in this pipeline MUST use `worktree_path` as its working directory. Print:
+**Task-level worktree isolation:** when `task_isolation.worktree_per_task` is enabled (check via `host_capabilities.worktrees` + `task_isolation` in the route result) and `task ensure` returns a `worktree` block, every subsequent Bash call AND every spawned agent in this pipeline MUST use `worktree_path` as its working directory. Print:
 
 ```
 [APT] Working in isolated worktree: {worktree_path}
@@ -424,7 +468,7 @@ Important nuances:
 - `task_dir` is an **absolute path** under the main repo's `.aperant/tasks/{task-id}/`. All spec/plan/progress artifacts live there and are shared across worktrees.
 - `apt-tools` commands still receive the **project root** as `<project-dir>` — they coordinate state through the main repo's `.aperant/`. The worktree only affects *code editing* cwd.
 - When spawning an agent, set its `cwd` (or prefix its Bash calls with `cd {worktree_path} &&`) to the worktree for code reads/edits. Pass `worktree_path` in the agent's context so it knows where code work happens.
-- Planner artifact safety: do **not** spawn `apt-planner` with host-level worktree isolation that gives it a separate copied repo. The planner must write `spec.md` and `implementation_plan.json` to the absolute main-repo `task_dir` from `task create`; `.aperant/tasks/**` is gitignored, so artifacts written under a disposable worktree can be invisible to git and lost when that worktree is cleaned.
+- Planner artifact safety: do **not** spawn `apt-planner` with host-level worktree isolation that gives it a separate copied repo. The planner must write `spec.md` and `implementation_plan.json` to the absolute main-repo `task_dir` from `task ensure`; `.aperant/tasks/**` is gitignored, so artifacts written under a disposable worktree can be invisible to git and lost when that worktree is cleaned.
 - If no `worktree` block is returned, proceed in the project root as before.
 
 ### Step 3: Spawn Planner Agent
@@ -482,14 +526,44 @@ tally output. Skip silently if tokens tally errors — never block the
 pipeline on telemetry.
 
 **If `spawn_agent` is false (QUICK or DEBUG):**
-Both QUICK and DEBUG resolve here (single-shot, no spawned phase agent). Invoke
-the picked skill (`apt:quick` for QUICK, `apt:debug` for DEBUG, per
-`primary_skill`) directly with `task_id`, `task_dir`, AND `worktree_path` in its
-skill context — Step 2 already created the worktree + printed the banner for this
-track, so thread `worktree_path` the same way the `spawn_agent: true` branch
-threads it into the planner. No phase marker — QUICK and DEBUG are both
-single-shot here. (If Step 2 returned no `worktree` block, pass `worktree_path` as
-"none" and the skill proceeds in the project root.)
+Both QUICK and DEBUG resolve here (single-shot, no spawned phase agent).
+
+**The router itself CANNOT edit code.** Its frontmatter `allowed-tools` is
+`Bash, Read, Grep, Glob, Task` — it has NO `Write` / `Edit` tool. This is the
+load-bearing boundary (ID-05): the router can classify, allocate
+(`task ensure`), and dispatch, but it can never edit a file on `main`.
+
+So do NOT edit inline. **INVOKE the `apt:quick` / `apt:debug` SKILL** (per
+`primary_skill`) AFTER Step 2's `task ensure --intent create-new` has
+provisioned the worktree. Invoking the skill establishes that skill's OWN
+`allowed-tools` scope (`apt-quick` / `apt-debug` both carry
+`Read, Write, Edit, Bash, Grep, Glob`), which RE-GRANTS the edit affordance —
+but only once a worktree exists, so editing can never land on `main` through
+the router. Pass `task_id`, `task_dir`, AND `worktree_path` into the invoked
+skill's context (thread `worktree_path` the same way the `spawn_agent: true`
+branch threads it into the planner). This is a SKILL invocation, NOT a `Task`
+sub-agent spawn — QUICK/DEBUG stay single-agent/single-context, so the Fast
+Path Guarantee is preserved. No phase marker. (If Step 2 returned no `worktree`
+block, pass `worktree_path` as "none" and the skill proceeds in the project
+root.)
+
+> **inline vs skill-scope (read this).** "Inline" here means the OLD behavior:
+> the router editing within its own `/apt` turn under the router's allowlist.
+> That is gone — the router has no edit tool. "Skill-scope" is the NEW
+> behavior: a genuine `apt:quick` / `apt:debug` invocation whose own
+> `allowed-tools` re-grants `Write, Edit` for the edit work, after the worktree
+> exists.
+>
+> **Residual (host-runtime, not CI-provable — founder smoke-test gate).**
+> Whether Claude Code treats a nested skill's `allowed-tools` as a REPLACEMENT
+> (re-grants edit — design holds) or as an INTERSECTION/ceiling (the parent
+> router allowlist caps the child — Fast Path breaks) is a host-implementation
+> property that cannot be unit-tested from the framework. CI proves the
+> frontmatter/prose structure; a founder in-app smoke-test is the residual gate.
+> **Fallback if the smoke-test shows breakage:** revert ONLY the
+> router-frontmatter line (re-add `Write, Edit`). The host-agnostic
+> `task ensure` boundary (ID-02) still fixes the on-`main`-edit bug; the
+> allowed-tools removal is hardening, not the fix.
 
 ### Step 4: Chain Pipeline (based on selected option)
 

package/dist/plugin/skills/apt-close-task/SKILL.md

@@ -185,7 +185,7 @@ Flags:
 Per ledger entry `{ task_id, scope, phase_id, closed_at, pr_number }`:
 
 0. **Enumerate the ledger first.** Run `apt-tools task close-merged . --narrate-only [--task <id>]`. The envelope's `closed[]` is the read-only list of pending narration rows (each carries `narration_pending: true`); state.json is not mutated. When `closed[]` is empty, exit early with `{status: 'ok', narrated: [], skipped: [], remaining: 0}` — there is nothing to drain.
-1. Run `apt-tools features-audit . --apply-stubs --task <task_id>` so the feature registry catches whatever the closed task introduced. If the subprocess exits non-zero, skip the entry with `reason: 'features-audit-failed'` — never block narration on registry update.
+1. Run `apt-tools features-reconcile . --gc` to prune feature-registry receipts that are merged to origin/main and older than 30 days. Receipt GC is close-task's ONLY registry role — the registry WRITE happened at ship time (`/apt:ship` §0.0 materialize), so there is no post-merge registry write to drift main. If the subprocess exits non-zero, skip the entry with `reason: 'features-gc-failed'` — never block narration on registry GC.
 2. When `phase_id` is non-null, spawn `apt-team-docs-narrator` (background, fire-and-forget) using the same shape as §2.5: `subagent_type: apt-team-docs-narrator`, `run_in_background: true`, `description: Narrate shipped phase {phase_id}`, `prompt: Run in phase-ship mode with --phase {phase_id} --scope {scope}.`. When `phase_id` is null, skip the spawn with `reason: 'no-phase-id'` (quick tasks have no phase to narrate).
 3. On successful spawn (or successful no-phase skip), drain the row via `apt-tools task narration-drain . --task <task_id>` which acquires `withFileLock(state.json)` and removes the matching `pending_narration[]` entry. On spawn failure, leave the row in place with `reason: 'narrator-spawn-failed'` so the user can re-invoke.
 
@@ -198,7 +198,7 @@ Emit a summary envelope:
   "status": "ok",
   "command": "close-task-narrate-only",
   "narrated": [{ "task_id": "<id>", "phase_id": "<p|null>", "scope": "<s>" }],
-  "skipped": [{ "task_id": "<id>", "reason": "no-phase-id|features-audit-failed|narrator-spawn-failed" }],
+  "skipped": [{ "task_id": "<id>", "reason": "no-phase-id|features-gc-failed|narrator-spawn-failed" }],
   "remaining": <ledger.length>
 }
 ```