@aperant/framework 0.7.4 → 0.8.1

package/dist/cli/roadmap/convex-mirror.d.mts

@@ -0,0 +1,21 @@
+/**
+ * Run the convex-mirror call.
+ *
+ * @param {string} projectDir
+ * @param {{scope: string, phaseId: string, anchorId: string, proseBody: string, mergedPr?: number, baseUrl?: string, fetchImpl?: typeof fetch}} args
+ * @returns {Promise<{status: 'ok'|'queued'|'error', code?: number, message?: string}>}
+ */
+export function runConvexMirror(projectDir: string, args: {
+    scope: string;
+    phaseId: string;
+    anchorId: string;
+    proseBody: string;
+    mergedPr?: number;
+    baseUrl?: string;
+    fetchImpl?: typeof fetch;
+}): Promise<{
+    status: "ok" | "queued" | "error";
+    code?: number;
+    message?: string;
+}>;
+//# sourceMappingURL=convex-mirror.d.mts.map

package/dist/cli/roadmap/convex-mirror.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convex-mirror.d.mts","sourceRoot":"","sources":["../../../src/cli/roadmap/convex-mirror.mjs"],"names":[],"mappings":"AAiDA;;;;;;GAMG;AACH,4CAJW,MAAM,QACN;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;CAAC,GAClI,OAAO,CAAC;IAAC,MAAM,EAAE,IAAI,GAAC,QAAQ,GAAC,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAC,CAAC,CA4ErF"}

package/dist/cli/roadmap/convex-mirror.mjs

@@ -0,0 +1,133 @@
+/**
+ * Slice 5 ST14 / AC10 / ID-06 — `apt-tools roadmap convex-mirror`.
+ *
+ * Helper that POSTs the rendered narrator prose to the Next.js
+ * /api/roadmap/narrator-mirror endpoint. Markdown is canonical
+ * (ADR-0006); this call is the Convex mirror.
+ *
+ * Fail-soft contract:
+ *   - 200 {mirrored:true}      → exit 0, status='ok'
+ *   - 200 {mirrored:false,queued:true} → exit 0, status='queued'
+ *   - 401                       → exit 1, status='error'  (auth misconfig)
+ *   - 4xx (other than 401)      → exit 1, status='error'
+ *   - 5xx / network error       → exit 0, status='queued', appends a
+ *                                  pending JSONL row to
+ *                                  .aperant/digests/narrator-mirror-pending.jsonl
+ *                                  so a follow-up narrator invocation
+ *                                  can replay locally if the cron
+ *                                  drainer hasn't caught up.
+ *
+ * Token resolution order (per ID-07):
+ *   1. process.env.MCP_NARRATOR_TOKEN
+ *   2. .aperant/team.json :: narratorMirrorToken
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+function resolveToken(projectDir) {
+    const envToken = process.env.MCP_NARRATOR_TOKEN;
+    if (envToken && envToken.length > 0)
+        return envToken;
+    const teamJsonPath = join(projectDir, '.aperant', 'team.json');
+    if (!existsSync(teamJsonPath))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(teamJsonPath, 'utf-8'));
+        if (typeof parsed.narratorMirrorToken === 'string' && parsed.narratorMirrorToken.length > 0) {
+            return parsed.narratorMirrorToken;
+        }
+    }
+    catch {
+        // Bad JSON — fall through to null
+    }
+    return null;
+}
+function appendPendingJsonl(projectDir, row) {
+    const path = join(projectDir, '.aperant', 'digests', 'narrator-mirror-pending.jsonl');
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(path, `${JSON.stringify(row)}\n`);
+}
+/**
+ * Run the convex-mirror call.
+ *
+ * @param {string} projectDir
+ * @param {{scope: string, phaseId: string, anchorId: string, proseBody: string, mergedPr?: number, baseUrl?: string, fetchImpl?: typeof fetch}} args
+ * @returns {Promise<{status: 'ok'|'queued'|'error', code?: number, message?: string}>}
+ */
+export async function runConvexMirror(projectDir, args) {
+    const { scope, phaseId, anchorId, proseBody, mergedPr, baseUrl, fetchImpl } = args;
+    if (!scope || !phaseId || !anchorId || typeof proseBody !== 'string') {
+        return { status: 'error', message: 'missing required: scope, phaseId, anchorId, proseBody' };
+    }
+    const token = resolveToken(projectDir);
+    if (!token) {
+        return {
+            status: 'error',
+            message: 'No narrator token (set MCP_NARRATOR_TOKEN or .aperant/team.json::narratorMirrorToken)',
+        };
+    }
+    const url = `${(baseUrl || process.env.APERANT_BASE_URL || 'https://app.aperant.com').replace(/\/$/, '')}/api/roadmap/narrator-mirror`;
+    const body = {
+        scope,
+        phaseId,
+        narratorAnchorId: anchorId,
+        narratorProse: proseBody,
+        mergedPr,
+    };
+    const f = fetchImpl ?? fetch;
+    let res;
+    try {
+        res = await f(url, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${token}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(body),
+        });
+    }
+    catch (e) {
+        // Network failure → fail-soft queue.
+        const msg = e instanceof Error ? e.message : String(e);
+        appendPendingJsonl(projectDir, {
+            ...body,
+            lastError: `network: ${msg}`,
+            ts: new Date().toISOString(),
+        });
+        return { status: 'queued', message: `network error: ${msg}` };
+    }
+    if (res.status === 401) {
+        return { status: 'error', code: 401, message: 'auth: invalid or missing token' };
+    }
+    if (res.status >= 500) {
+        // 5xx → fail-soft queue.
+        appendPendingJsonl(projectDir, {
+            ...body,
+            lastError: `http ${res.status}`,
+            ts: new Date().toISOString(),
+        });
+        return { status: 'queued', code: res.status, message: 'server error — enqueued' };
+    }
+    if (res.status >= 400) {
+        let detail = '';
+        try {
+            detail = await res.text();
+        }
+        catch {
+            // ignore
+        }
+        return { status: 'error', code: res.status, message: detail || `http ${res.status}` };
+    }
+    // 200/2xx
+    let parsed;
+    try {
+        parsed = await res.json();
+    }
+    catch {
+        parsed = { mirrored: true, queued: false };
+    }
+    if (parsed?.queued) {
+        return { status: 'queued', code: res.status, message: 'enqueued server-side' };
+    }
+    return { status: 'ok', code: res.status };
+}
+//# sourceMappingURL=convex-mirror.mjs.map

package/dist/cli/roadmap/convex-mirror.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"convex-mirror.mjs","sourceRoot":"","sources":["../../../src/cli/roadmap/convex-mirror.mjs"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAC7E,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAEzC,SAAS,YAAY,CAAC,UAAU;IAC/B,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAA;IAC/C,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,QAAQ,CAAA;IACpD,MAAM,YAAY,GAAG,IAAI,CAAC,UAAU,EAAE,UAAU,EAAE,WAAW,CAAC,CAAA;IAC9D,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC;QAAE,OAAO,IAAI,CAAA;IAC1C,IAAI,CAAC;QACJ,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC,CAAA;QAC9D,IAAI,OAAO,MAAM,CAAC,mBAAmB,KAAK,QAAQ,IAAI,MAAM,CAAC,mBAAmB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC7F,OAAO,MAAM,CAAC,mBAAmB,CAAA;QAClC,CAAC;IACF,CAAC;IAAC,MAAM,CAAC;QACR,kCAAkC;IACnC,CAAC;IACD,OAAO,IAAI,CAAA;AACZ,CAAC;AAED,SAAS,kBAAkB,CAAC,UAAU,EAAE,GAAG;IAC1C,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,+BAA+B,CAAC,CAAA;IACrF,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IAC7C,cAAc,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;AACjD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,UAAU,EAAE,IAAI;IACrD,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,IAAI,CAAA;IAClF,IAAI,CAAC,KAAK,IAAI,CAAC,OAAO,IAAI,CAAC,QAAQ,IAAI,OAAO,SAAS,KAAK,QAAQ,EAAE,CAAC;QACtE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,uDAAuD,EAAE,CAAA;IAC7F,CAAC;IACD,MAAM,KAAK,GAAG,YAAY,CAAC,UAAU,CAAC,CAAA;IACtC,IAAI,CAAC,KAAK,EAAE,CAAC;QACZ,OAAO;YACN,MAAM,EAAE,OAAO;YACf,OAAO,EACN,uFAAuF;SACxF,CAAA;IACF,CAAC;IACD,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,yBAAyB,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,8BAA8B,CAAA;IACtI,MAAM,IAAI,GAAG;QACZ,KAAK;QACL,OAAO;QACP,gBAAgB,EAAE,QAAQ;QAC1B,aAAa,EAAE,SAAS;QACxB,QAAQ;KACR,CAAA;IACD,MAAM,CAAC,GAAG,SAAS,IAAI,KAAK,CAAA;IAC5B,IAAI,GAAG,CAAA;IACP,IAAI,CAAC;QACJ,GAAG,GAAG,MAAM,CAAC,CAAC,GAAG,EAAE;YAClB,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACR,aAAa,EAAE,UAAU,KAAK,EAAE;gBAChC,cAAc,EAAE,kBAAkB;aAClC;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;SAC1B,CAAC,CAAA;IACH,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACZ,qCAAqC;QACrC,MAAM,GAAG,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA;QACtD,kBAAkB,CAAC,UAAU,EAAE;YAC9B,GAAG,IAAI;YACP,SAAS,EAAE,YAAY,GAAG,EAAE;YAC5B,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SAC5B,CAAC,CAAA;QACF,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,kBAAkB,GAAG,EAAE,EAAE,CAAA;IAC9D,CAAC;IACD,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;QACxB,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,gCAAgC,EAAE,CAAA;IACjF,CAAC;IACD,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG,EAAE,CAAC;QACvB,yBAAyB;QACzB,kBAAkB,CAAC,UAAU,EAAE;YAC9B,GAAG,IAAI;YACP,SAAS,EAAE,QAAQ,GAAG,CAAC,MAAM,EAAE;YAC/B,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SAC5B,CAAC,CAAA;QACF,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,yBAAyB,EAAE,CAAA;IAClF,CAAC;IACD,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG,EAAE,CAAC;QACvB,IAAI,MAAM,GAAG,EAAE,CAAA;QACf,IAAI,CAAC;YACJ,MAAM,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAA;QAC1B,CAAC;QAAC,MAAM,CAAC;YACR,SAAS;QACV,CAAC;QACD,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,IAAI,QAAQ,GAAG,CAAC,MAAM,EAAE,EAAE,CAAA;IACtF,CAAC;IACD,UAAU;IACV,IAAI,MAAM,CAAA;IACV,IAAI,CAAC;QACJ,MAAM,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAA;IAC1B,CAAC;IAAC,MAAM,CAAC;QACR,MAAM,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAA;IAC3C,CAAC;IACD,IAAI,MAAM,EAAE,MAAM,EAAE,CAAC;QACpB,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,sBAAsB,EAAE,CAAA;IAC/E,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,CAAA;AAC1C,CAAC"}

package/dist/cli/roadmap/lifecycle.d.mts

@@ -45,7 +45,7 @@ export function applyLifecyclePhaseSideEffect(targetDir: any, task: any, spec: a
     commit: string | null;
     rollup: {
         before: any;
-        after: "in-progress" | "completed" | "planned" | "blocked" | null;
+        after: "planned" | "completed" | "blocked" | "in-progress" | null;
         changed: boolean;
         milestone_id: any;
     };

package/dist/cli/roadmap/lifecycle.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"lifecycle.d.mts","sourceRoot":"","sources":["../../../src/cli/roadmap/lifecycle.mjs"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;SAwEC"}
+{"version":3,"file":"lifecycle.d.mts","sourceRoot":"","sources":["../../../src/cli/roadmap/lifecycle.mjs"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;SA8GC"}

package/dist/cli/roadmap/lifecycle.mjs

@@ -1,6 +1,16 @@
 /**
  * lifecycle.mjs — shared lifecycle-phase side-effect helper (C29).
+ *
+ * FRAMEWORK-BUG-033 defect 1/5: when `spec.to === 'completed'`, the helper
+ * enumerates sibling tasks in the same scope+milestone+phase and aborts
+ * the flip (returns null — idempotent no-op shape) when any sibling
+ * remains open (lifecycle_phase !== 'closed'). The guard lives inside the
+ * helper so every caller (`task update --lifecycle-phase`, `task close
+ * --verdict approved`, the drain wrapper, and `task close-merged`
+ * transitively via its `task close` child) inherits it.
  */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { loadRoadmapForScope, saveRoadmapForScope } from './io.mjs';
 import { applyRollup } from './rollup.mjs';
 import { syncRoadmapInProcess } from './sync.mjs';
@@ -55,6 +65,50 @@ export function applyLifecyclePhaseSideEffect(targetDir, task, spec, reasonPrefi
     // From-state guard: idempotent no-op when phase is not at `spec.from`.
     if (phase.status !== spec.from)
         return null;
+    // FRAMEWORK-BUG-033 defect 1/5 — sibling-count guard. Only gates the
+    // `→ completed` direction (other transitions like `→ in-progress` are
+    // unaffected per ID-02 / AC7). Enumerates state.active_tasks filtered by
+    // scope+milestone+phase. Any open sibling (lifecycle_phase !== 'closed'
+    // and id !== task.id) blocks the flip with the same idempotent no-op
+    // shape as the from-state guard above.
+    //
+    // State source: caller may pass `opts.stateBlob` when already holding
+    // `withFileLock(state.json)` to avoid a re-read race; otherwise we read
+    // state.json from disk once. On the `task close` path the task has
+    // already been deleted from state.active_tasks before this helper runs,
+    // so the `t.id !== task.id` filter is a defensive no-op there.
+    if (spec.to === 'completed') {
+        let stateBlob = opts.stateBlob;
+        if (!stateBlob) {
+            const statePath = join(targetDir, '.aperant', 'state.json');
+            if (existsSync(statePath)) {
+                try {
+                    stateBlob = JSON.parse(readFileSync(statePath, 'utf-8'));
+                }
+                catch {
+                    // Fail-secure: cannot verify sibling state → assume siblings might exist → abort the flip.
+                    return null;
+                }
+            }
+        }
+        const activeTasks = stateBlob?.active_tasks || {};
+        for (const sibling of Object.values(activeTasks)) {
+            if (!sibling || typeof sibling !== 'object')
+                continue;
+            if (sibling.scope !== scope)
+                continue;
+            if (sibling.milestone_id !== task.milestone_id)
+                continue;
+            if (sibling.phase_id !== task.phase_id)
+                continue;
+            if (sibling.id === task.id)
+                continue;
+            if (sibling.lifecycle_phase === 'closed')
+                continue;
+            // Open sibling — abort the flip.
+            return null;
+        }
+    }
     const transition = {
         op: reasonPrefix,
         scope,

package/dist/cli/roadmap/lifecycle.mjs.map

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

package/dist/cli/roadmap/rollup.d.mts

@@ -16,7 +16,7 @@ export function rollupMilestoneStatus(milestone: object): "completed" | "in-prog
  */
 export function applyRollup(roadmap: any, milestoneId: any): {
     before: any;
-    after: "in-progress" | "completed" | "planned" | "blocked" | null;
+    after: "planned" | "completed" | "blocked" | "in-progress" | null;
     changed: boolean;
     milestone_id: any;
 };
@@ -31,7 +31,7 @@ export function applyRollup(roadmap: any, milestoneId: any): {
 export function writeRollup(projectDir: any, scope: any, milestoneId: any): {
     committed: boolean;
     before: any;
-    after: "in-progress" | "completed" | "planned" | "blocked" | null;
+    after: "planned" | "completed" | "blocked" | "in-progress" | null;
     changed: boolean;
     milestone_id: any;
 };

package/dist/cli/wfrun/unit-shape.d.mts

@@ -0,0 +1,27 @@
+/**
+ * wfrun/unit-shape.mjs — FRAMEWORK-BUG-033 capability gap (ID-03).
+ *
+ * Normalize a wave-engine plan blob to the unit-agnostic
+ * `{units, unit_kind}` shape. Two input forms accepted:
+ *   - Subtask-shaped (back-compat): `{subtasks: [...]}`.
+ *   - Task-shaped (new): `{unit_kind: "task", tasks: [...]}`.
+ *
+ * Internally the wave engine operates purely on `{id, dependencies,
+ * files}` records — only the I/O boundary cares about the rename.
+ */
+/**
+ * Detect whether a plan blob is task-shaped, subtask-shaped, or invalid.
+ *
+ * @param {unknown} plan
+ * @returns {{ units: Array<{id: string, dependencies: string[], files?: string[]}>, unit_kind: 'subtask' | 'task', error: string | null }}
+ */
+export function normalizeToUnits(plan: unknown): {
+    units: Array<{
+        id: string;
+        dependencies: string[];
+        files?: string[];
+    }>;
+    unit_kind: "subtask" | "task";
+    error: string | null;
+};
+//# sourceMappingURL=unit-shape.d.mts.map

package/dist/cli/wfrun/unit-shape.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unit-shape.d.mts","sourceRoot":"","sources":["../../../src/cli/wfrun/unit-shape.mjs"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;GAKG;AACH,uCAHW,OAAO,GACL;IAAE,KAAK,EAAE,KAAK,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;KAAC,CAAC,CAAC;IAAC,SAAS,EAAE,SAAS,GAAG,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAsBzI"}

package/dist/cli/wfrun/unit-shape.mjs

@@ -0,0 +1,38 @@
+/**
+ * wfrun/unit-shape.mjs — FRAMEWORK-BUG-033 capability gap (ID-03).
+ *
+ * Normalize a wave-engine plan blob to the unit-agnostic
+ * `{units, unit_kind}` shape. Two input forms accepted:
+ *   - Subtask-shaped (back-compat): `{subtasks: [...]}`.
+ *   - Task-shaped (new): `{unit_kind: "task", tasks: [...]}`.
+ *
+ * Internally the wave engine operates purely on `{id, dependencies,
+ * files}` records — only the I/O boundary cares about the rename.
+ */
+/**
+ * Detect whether a plan blob is task-shaped, subtask-shaped, or invalid.
+ *
+ * @param {unknown} plan
+ * @returns {{ units: Array<{id: string, dependencies: string[], files?: string[]}>, unit_kind: 'subtask' | 'task', error: string | null }}
+ */
+export function normalizeToUnits(plan) {
+    if (!plan || typeof plan !== 'object') {
+        return { units: [], unit_kind: 'subtask', error: 'Plan must be an object' };
+    }
+    const isTaskShape = plan.unit_kind === 'task' || (Array.isArray(plan.tasks) && !Array.isArray(plan.subtasks));
+    if (isTaskShape) {
+        if (!Array.isArray(plan.tasks)) {
+            return { units: [], unit_kind: 'task', error: 'Plan must contain a "tasks" array' };
+        }
+        return { units: plan.tasks, unit_kind: 'task', error: null };
+    }
+    if (!Array.isArray(plan.subtasks)) {
+        return {
+            units: [],
+            unit_kind: 'subtask',
+            error: 'Plan must contain a "subtasks" array',
+        };
+    }
+    return { units: plan.subtasks, unit_kind: 'subtask', error: null };
+}
+//# sourceMappingURL=unit-shape.mjs.map

package/dist/cli/wfrun/unit-shape.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"unit-shape.mjs","sourceRoot":"","sources":["../../../src/cli/wfrun/unit-shape.mjs"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAI;IACpC,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QACvC,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,wBAAwB,EAAE,CAAA;IAC5E,CAAC;IACD,MAAM,WAAW,GAChB,IAAI,CAAC,SAAS,KAAK,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAA;IAC1F,IAAI,WAAW,EAAE,CAAC;QACjB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YAChC,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,mCAAmC,EAAE,CAAA;QACpF,CAAC;QACD,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;IAC7D,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QACnC,OAAO;YACN,KAAK,EAAE,EAAE;YACT,SAAS,EAAE,SAAS;YACpB,KAAK,EAAE,sCAAsC;SAC7C,CAAA;IACF,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;AACnE,CAAC"}

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

@@ -1,6 +1,6 @@
 {
   "name": "aperant",
-  "version": "0.7.3",
+  "version": "0.8.1",
   "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",
@@ -34,6 +34,7 @@
     "skills/apt-discuss",
     "skills/apt-docs",
     "skills/apt-execute",
+    "skills/apt-fan-out",
     "skills/apt-improve",
     "skills/apt-mockup",
     "skills/apt-pause",

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

@@ -46,6 +46,18 @@ node packages/framework/bin/apt-tools.mjs gate check . --task-id {task-id} --ski
 
 If `status == "fail"`, STOP. Report the failed gates verbatim and exit — do NOT auto-apply `--force`. Forcing is a human decision; the user can re-invoke with `--force --reason "<explanation>"` to bypass (the override is logged to `.aperant/events/{today}.jsonl`).
 
+## 0a. Fan-out worker identity (FRAMEWORK-BUG-033 defect 3)
+
+If your spawn prompt contains both `batch_id` and `task_id` (i.e. you are a fan-out worker subagent dispatched by `/apt:fan-out`), export `APT_AGENT_ID` in EVERY `Bash` invocation that runs `apt-tools ...`:
+
+```bash
+APT_AGENT_ID=fanout-${batch_id}-${task_id} node packages/framework/bin/apt-tools.mjs <command> ...
+```
+
+This pins your `team-status/{agentId}.json` file across short-lived CLI invocations. Without it, each `apt-tools` call gets a fresh `hostname-pid` agentId (per `agent-identity.mjs:86`), the previous pid dies, and `listTeamStatus({ includeStale: false })` filters healthy workers out between invocations — the team-status dashboard flickers into emptiness instead of showing 4 stable fan-out workers.
+
+Non-fan-out invocations of this agent receive no `batch_id` and skip this export — the legacy `hostname-pid` path remains correct for single-task work.
+
 ## 1. Load Context
 
 1. Read `CLAUDE.md` and `AGENTS.md` if they exist

package/dist/plugin/agents/apt-team-docs-narrator.md

@@ -72,6 +72,17 @@ If the parent spawned you without a mode you recognize, write an error line to `
    rendered table. If present, REPLACE the content between anchors (never
    append — this is how re-runs stay idempotent).
 7. Call `apt-tools roadmap sync . --reason 'narrator:phase-ship:<phase_id>'`.
+8. **Slice 5 / AC14 / ADR-0006 dual-write.** Write the rendered prose
+   block to a temp file (e.g. `mktemp -t narrator-prose-XXXXXX.md`), then
+   run
+   `apt-tools roadmap convex-mirror . --scope <scope> --phase <phase_id> --anchor-id phase-ship:<phase_id> --prose-path <tempfile>`
+   (add `--merged-pr <pr-number>` when known). The markdown write from
+   step 7 is canonical (ADR-0006); this step is the Convex mirror.
+   Fail-soft contract:
+   - exit 0 with `status:ok` or `status:queued` → continue normally
+   - exit non-zero with `status:error` → append the error message to
+     `.aperant/digests/errors.log` and continue (do NOT block on Convex
+     failures; the in-process cron drainer reconciles within 5 min)
 
 ## Mode 2: `decision-merge` — merge a recorded decision into the roadmap
 

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

@@ -41,8 +41,9 @@ you must follow when classifying.
 - **Config:** `.aperant/config.json` — project preferences
 - **State:** `.aperant/state.json` — execution state
 - **Task directories:** `.aperant/tasks/{task-id}/` — each task gets isolated artifacts
-- **Codex repo skills:** `.agents/skills/apt*/` — native Codex discovery surface installed by `apt-tools init`
-- **Claude agents:** `.claude/agents/apt-*.md` — specialized agent definitions for heavy workflows
+- **Claude surface:** `.claude/skills/`, `.claude/agents/`
+- **Codex surface:** `.codex/commands/`, `.codex/agents/`
+- **Pi surface:** `.pi/prompts/`, `.pi/skills/`
 </your_environment>
 
 <mandatory_first_step>

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

@@ -453,6 +453,19 @@ After all subtasks are completed:
 node packages/framework/bin/apt-tools.mjs commit "build: all subtasks complete" --files implementation_plan.json build-progress.json
 ```
 
+### Mark lifecycle phase as `verifying`
+
+Flip the task's lifecycle phase at the success-end boundary so the next stage
+(`/apt:verify`) finds the task in the correct from-state. Mirror the same CLI
+shape as the start-boundary call in Section 2 — quick tasks (no phase linkage)
+silently no-op, and the update is idempotent so it is safe to re-run on
+`--continue`. Skip this step if any subtask ended in `"blocked"` — only the
+all-subtasks-completed branch should advance the phase.
+
+```bash
+node packages/framework/bin/apt-tools.mjs task update . --id {task-id} --lifecycle-phase verifying
+```
+
 Output:
 ```
 Execution complete:

package/dist/plugin/skills/apt-fan-out/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: apt:fan-out
+description: "Cross-task fan-out — spawn N apt-executor workers from one conductor terminal, each in its own worktree"
+apt-skill-version: {{APT_VERSION}}
+stage: execute
+intent: x-fan-out
+when_to_use: "You have N pre-planned, independent tasks (no file overlap, no cross-dependencies) and want to run them concurrently from a single host CLI session."
+user_invocable: true
+internal: false
+spawns_agent: true
+agent_name: "apt-executor"
+task_context: require-existing
+default_execution_mode: auto
+execution_modes:
+  - auto
+  - step
+allowed-tools: "Bash, Read, Write, Task"
+argument-hint: "apt:fan-out --tasks <id,id,id> [--phases <m/p,m/p>] [--unblocked]"
+gates: []
+---
+<objective>
+Run N pre-planned Aperant tasks concurrently from one conductor terminal. This skill is a thin orchestrator over the generalized wave engine (`unit_kind: "task"` path, see ADR-0003) and the existing primitives: `apt-tools worktree create --task`, `apt-tools lock claim`, `apt-tools event append`, and the `parallelization.max_tasks` quota. No daemon, no job queue, no in-skill scheduling. The host CLI's main thread is the conductor (ADR-0001); each spawned apt-executor subagent runs in its own worktree (ADR-0002).
+
+This is the "I have 16 unblocked tasks in this phase, run them all" surface. It replaces the old workaround of opening 16 sibling terminals manually.
+</objective>
+
+<your_environment>
+- **Working directory:** Project root (where you were invoked).
+- **apt-tools path:** `node packages/framework/bin/apt-tools.mjs` (or `node .aperant/deps/node_modules/@aperant/framework/bin/apt-tools.mjs` when running from an install mirror).
+- **Concurrency cap:** `parallelization.max_tasks` from `.aperant/config.json` (default 4, no paternalism cap per D-07). Read via `cli/config/parallelization.mjs:getMaxTasks(config)`.
+- **Worker identity:** Each spawned worker exports `APT_AGENT_ID=fanout-${batch_id}-${task_id}` before any `apt-tools ...` invocation (per FRAMEWORK-BUG-033 defect 3). This pins their `team-status/{agentId}.json` rows across short-lived CLI calls.
+- **Constitution:** Read `AGENTS.md` if it exists.
+</your_environment>
+
+<state_files>
+## State Files
+
+**Reads:**
+- `.aperant/state.json` — `active_tasks[*]` filtered when `--phases` or `--unblocked` resolves the task list.
+- `.aperant/roadmap/{scope}/milestones.json` — milestone/phase membership for `--phases`.
+- `.aperant/config.json:parallelization.max_tasks` — concurrency cap.
+
+**Writes (indirectly via spawned workers):**
+- `.aperant/team-status/fanout-${batch_id}-${task_id}.json` — one stable file per worker (per FRAMEWORK-BUG-033 defect 3 fix).
+- `.aperant/state.json:active_tasks[*].assigned_to` — workers stamp their `APT_AGENT_ID` on claim (per FRAMEWORK-BUG-033 defect 2 fix).
+- `.aperant/events/{today}.jsonl` — `task-claimed`, `wave-started`, `wave-completed` events.
+
+**No filesystem state of its own.** The skill body is pure orchestration glue; all heavy lifting reuses existing primitives.
+</state_files>
+
+<process>
+
+## 1. Resolve the batch — canonical task ID list
+
+The three input forms (`--tasks`, `--phases`, `--unblocked`) all resolve to a canonical `task_ids: [...]` list via the apt-tools helper:
+
+```bash
+node packages/framework/bin/apt-tools.mjs fan-out resolve . --tasks T1,T2,T3,T4
+# OR
+node packages/framework/bin/apt-tools.mjs fan-out resolve . --phases m1/p1,m1/p2
+# OR
+node packages/framework/bin/apt-tools.mjs fan-out resolve . --unblocked
+```
+
+Returns:
+```json
+{
+  "status": "ok",
+  "command": "fan-out-resolve",
+  "task_ids": ["T1", "T2", "T3", "T4"],
+  "source": "tasks",
+  "batch_id": "fanout-20260519-abc123"
+}
+```
+
+If `--tasks` IDs fail the `/^[a-z0-9_-]+$/i` validation regex, the helper returns `status: error` and the skill body MUST abort.
+
+## 2. Ensure each task has a worktree
+
+For each `task_id` in the batch:
+
+```bash
+node packages/framework/bin/apt-tools.mjs worktree create --task ${task_id}
+```
+
+(Skip if `state.active_tasks[task_id].worktree_path` is already set — the create command is idempotent.)
+
+## 3. Spawn N apt-executor subagents
+
+Read the `parallelization.max_tasks` cap from `.aperant/config.json` (or default 4). Slice `task_ids` into batches of size `min(cap, task_ids.length)`. For each task in the current batch, dispatch via the host CLI's `Task` tool with `run_in_background: true`:
+
+- `subagent: apt-executor`
+- `prompt` includes:
+  - `batch_id` (from step 1)
+  - `task_id`
+  - The worktree path for this task
+  - A reminder: "Export `APT_AGENT_ID=fanout-${batch_id}-${task_id}` in every Bash invocation that runs `apt-tools` — see `packages/framework/agents/apt-executor.md` §0a."
+
+The executor agent's `<process>` §0a already documents the env-export rule; the spawn prompt just has to seed `batch_id` and `task_id`.
+
+## 4. Poll team-status until all workers reach a terminal state
+
+```bash
+node packages/framework/bin/apt-tools.mjs team list .
+```
+
+Each worker's row uses its `APT_AGENT_ID=fanout-${batch_id}-${task_id}`. A worker is "done" when its corresponding task's `lifecycle_phase` is one of `closed`, `shipped-pending-merge`, or `blocked`.
+
+## 5. Report
+
+When all workers reach a terminal state, emit one consolidated summary: which tasks closed (verdict + PR URL), which are awaiting merge, which blocked. Recommend `/apt:close-task --all` for the post-merge sweep.
+
+</process>
+
+## Design references
+
+- **ADR-0001** — Host CLI main thread is the conductor; no daemon, no in-skill queue.
+- **ADR-0002** — One worktree per task; workers run independent feature branches.
+- **ADR-0003** — Wave engine accepts `unit_kind: "task"` so cross-task fan-out reuses the same primitives as intra-task subtask waves.
+
+## Config keys
+
+- `parallelization.max_tasks` (default 4) — concurrency cap for the spawn loop.
+- `parallelization.max_agents` (default 4) — global agent quota; the spawn loop respects whichever cap is lower.

package/dist/plugin/skills/apt-pr-review/SKILL.md

@@ -1110,6 +1110,8 @@ For `AUTHORSHIP_MODE == "owned"`, continue normally.
 
 AI agents have near-zero marginal cost per fix. The framework fixes **all** confirmed findings — critical, high, medium, and low — regardless of autonomy level. There is no severity gate and no "report for manual resolution" path. If a finding was confirmed by the validator, it gets fixed.
 
+**Hard rule — context budget is NOT a valid skip reason.** The orchestrator MAY NOT defer, drop, downgrade, or "punt for follow-up" any confirmed finding because its own context window feels heavy, because the run has already produced many fixes, or because it judges marginal value low. The query loop auto-compacts on its own — trust it. Per-finding fix work happens inside fix agents (separate context windows), so orchestrator pressure does not justify cutting their inputs. The only valid skip reasons are the ones enumerated in Key Principle #2 (`fixable: false`, critical finding without user approval, file assigned to another fixer). Any other skip is an unauthorized policy deviation — emit all confirmed findings to fixers, then let the audit gate adjudicate outcomes.
+
 | Autonomy | Action |
 |----------|--------|
 | `< 2` | Show findings summary before fixing. Then proceed with auto-fix. |
@@ -1647,7 +1649,7 @@ node packages/framework/bin/apt-tools.mjs workflow destroy . --id ${REVIEW_ID}
 Agents do NOT assign confidence percentages. Either they have evidence (actual code snippet from Read tool) or they do not have a finding. The validator independently verifies every finding against real code.
 
 ### 2. Fix Everything Found
-If it was found and confirmed, fix it. ALL severities. "This is minor" is NOT a valid skip reason. The only valid skip reasons are: `fixable: false`, critical findings without user approval, or files assigned to another fixer.
+If it was found and confirmed, fix it. ALL severities. "This is minor" is NOT a valid skip reason. **Neither is "my context window is heavy" or "I've already done a lot this run"** — orchestrator context pressure never authorizes dropping a confirmed finding (see Phase 6 → Principle: Fix Everything). The only valid skip reasons are: `fixable: false`, critical findings without user approval, or files assigned to another fixer.
 
 ### 3. Findings Flow Through Files
 Agents write to `.aperant/pr-reviews/{review-id}/findings/`. The orchestrator reads with the Read tool. Fix agents read finding files directly. This keeps the orchestrator context under 30%.
@@ -1711,6 +1713,11 @@ Fix agents self-report their outcome via a status line (`FIXED: X | FAILED: Y |
 **Wrong:** Skipping Phase 6 entirely when autonomy < 2.
 **Right:** Always fix all confirmed findings. At autonomy < 2, show findings summary first, then proceed with auto-fix. The only difference is whether findings are displayed before fixing — not whether they get fixed.
 
+### Mistake 7a: Dropping Findings Because Orchestrator Context Feels Heavy
+
+**Wrong:** Mid-Phase-6, the orchestrator decides "my window is getting heavy after 6 specialist rounds + Round 1 fixes — I'll skip the minor findings and report a partial fix." This is an unauthorized policy deviation, even when phrased as "judgment call" or "context-budget reasons."
+**Right:** Spawn fix agents for **every** confirmed finding regardless of orchestrator context state. Fix work happens in the fixer's window, not yours. The query loop auto-compacts when it needs to — trust it. If you genuinely cannot fit the spawn calls, that is a framework bug to file (not a license to ship a partial fix); emit all findings to fixers in the smallest batches possible and let the audit gate adjudicate. Severity, "diminishing returns," and your own token pressure are NOT skip authorities — only the three reasons in Key Principle #2 are.
+
 ### Mistake 8: Forgetting to Update metadata.json
 
 **Wrong:** Writing review.json but leaving metadata.json stuck at `"status": "in-progress"`.

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

@@ -333,6 +333,10 @@ Scores: logic={n} security={n} quality={n} architecture={n} performance={n}
 Report: {task_dir}/review.json
 ```
 
+`lifecycle_phase` remains at `reviewing` after /apt:review completes — this is
+the from-state /apt:ship expects for its atomic `reviewing → shipped-pending-merge`
+flip, so no further `task update --lifecycle-phase` call is needed here.
+
 **Always end with a "What's Next" recommendation:**
 
 ```