@aperant/framework 0.7.3 → 0.8.0

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

@@ -0,0 +1,131 @@
+/**
+ * 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 }
+}

package/src/cli/roadmap/lifecycle.mjs

@@ -1,7 +1,17 @@
 /**
  * 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'
@@ -53,6 +63,44 @@ 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/src/cli/wfrun/unit-shape.mjs

@@ -0,0 +1,39 @@
+/**
+ * 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 }
+}

package/templates/config.json

@@ -85,7 +85,7 @@
 	"task_isolation": {
 		"worktree_per_task": false,
 		"branch_prefix": "apt",
-		"from_branch": "current",
+		"from_branch": "main",
 		"push_on_create": true,
 		"cleanup_on_close": "ask"
 	},