@aperant/framework 0.7.4 → 0.8.1

package/src/cli/commands/wave.mjs

@@ -1,10 +1,17 @@
 /**
  * commands/wave.mjs — wave analyzer (C29).
+ *
+ * FRAMEWORK-BUG-033 ID-03 — accepts two input forms at the I/O boundary:
+ *   1. Subtask-shaped plan (`{subtasks: [...]}`) — back-compat, byte-equivalent.
+ *   2. Task-shaped plan (`{unit_kind: "task", tasks: [...]}`) — new fan-out
+ *      input. Internal algorithm is unit-agnostic; only the input
+ *      normalization + output envelope keys differ.
  */
 
 import { existsSync, readFileSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 import { err, exitWith, ok } from '../util/result.mjs'
+import { normalizeToUnits } from '../wfrun/unit-shape.mjs'
 
 export function cmdWave(subcommand, projectDir, extraArgs) {
 	if (!subcommand)
@@ -37,28 +44,29 @@ export function cmdWave(subcommand, projectDir, extraArgs) {
 				return err(`Invalid JSON in plan file: ${e.message}`)
 			}
 
-			if (!plan.subtasks || !Array.isArray(plan.subtasks)) {
-				return err('Plan must contain a "subtasks" array')
-			}
+			// FRAMEWORK-BUG-033 ID-03 — normalize subtask/task input shapes.
+			const { units, unit_kind, error: shapeError } = normalizeToUnits(plan)
+			if (shapeError) return err(shapeError)
+			const isTaskUnit = unit_kind === 'task'
 
-			// Validate each subtask has required fields
-			for (const st of plan.subtasks) {
-				if (!st.id) return err(`Subtask missing "id" field: ${JSON.stringify(st)}`)
-				if (!Array.isArray(st.dependencies)) {
-					return err(`Subtask "${st.id}" missing "dependencies" array`)
+			// Validate each unit has required fields
+			for (const u of units) {
+				if (!u.id) return err(`${unit_kind} missing "id" field: ${JSON.stringify(u)}`)
+				if (!Array.isArray(u.dependencies)) {
+					return err(`${unit_kind} "${u.id}" missing "dependencies" array`)
 				}
 			}
 
-			const subtaskMap = new Map()
-			for (const st of plan.subtasks) {
-				subtaskMap.set(st.id, st)
+			const unitMap = new Map()
+			for (const u of units) {
+				unitMap.set(u.id, u)
 			}
 
-			// Validate all dependencies reference existing subtasks
-			for (const st of plan.subtasks) {
-				for (const dep of st.dependencies) {
-					if (!subtaskMap.has(dep)) {
-						return err(`Subtask "${st.id}" depends on unknown subtask "${dep}"`)
+			// Validate all dependencies reference existing units
+			for (const u of units) {
+				for (const dep of u.dependencies) {
+					if (!unitMap.has(dep)) {
+						return err(`${unit_kind} "${u.id}" depends on unknown ${unit_kind} "${dep}"`)
 					}
 				}
 			}
@@ -68,15 +76,15 @@ export function cmdWave(subcommand, projectDir, extraArgs) {
 				GRAY = 1,
 				BLACK = 2
 			const color = new Map()
-			for (const st of plan.subtasks) color.set(st.id, WHITE)
+			for (const u of units) color.set(u.id, WHITE)
 			let cycleFound = null
 
 			function dfs(id, path) {
 				if (cycleFound) return
 				color.set(id, GRAY)
 				path.push(id)
-				const st = subtaskMap.get(id)
-				for (const dep of st.dependencies) {
+				const u = unitMap.get(id)
+				for (const dep of u.dependencies) {
 					if (color.get(dep) === GRAY) {
 						// Found cycle: extract from dep to current position
 						const cycleStart = path.indexOf(dep)
@@ -91,9 +99,9 @@ export function cmdWave(subcommand, projectDir, extraArgs) {
 				color.set(id, BLACK)
 			}
 
-			for (const st of plan.subtasks) {
-				if (color.get(st.id) === WHITE) {
-					dfs(st.id, [])
+			for (const u of units) {
+				if (color.get(u.id) === WHITE) {
+					dfs(u.id, [])
 				}
 				if (cycleFound) break
 			}
@@ -103,40 +111,40 @@ export function cmdWave(subcommand, projectDir, extraArgs) {
 			}
 
 			// Wave assignment algorithm (D-12, D-13)
-			const waveAssignment = new Map() // subtask id -> wave number
+			const waveAssignment = new Map() // unit id -> wave number
 			const assigned = new Set()
 
-			// Wave 1: subtasks with no dependencies
-			for (const st of plan.subtasks) {
-				if (st.dependencies.length === 0) {
-					waveAssignment.set(st.id, 1)
-					assigned.add(st.id)
+			// Wave 1: units with no dependencies
+			for (const u of units) {
+				if (u.dependencies.length === 0) {
+					waveAssignment.set(u.id, 1)
+					assigned.add(u.id)
 				}
 			}
 
-			// Iteratively assign remaining subtasks
+			// Iteratively assign remaining units
 			let currentWave = 1
 			let progress = true
-			while (assigned.size < plan.subtasks.length && progress) {
+			while (assigned.size < units.length && progress) {
 				progress = false
 				currentWave++
-				for (const st of plan.subtasks) {
-					if (assigned.has(st.id)) continue
+				for (const u of units) {
+					if (assigned.has(u.id)) continue
 					// Check if ALL dependencies are assigned
-					const allDepsAssigned = st.dependencies.every((dep) => assigned.has(dep))
+					const allDepsAssigned = u.dependencies.every((dep) => assigned.has(dep))
 					if (allDepsAssigned) {
-						const maxDepWave = Math.max(...st.dependencies.map((dep) => waveAssignment.get(dep)))
-						waveAssignment.set(st.id, maxDepWave + 1)
-						assigned.add(st.id)
+						const maxDepWave = Math.max(...u.dependencies.map((dep) => waveAssignment.get(dep)))
+						waveAssignment.set(u.id, maxDepWave + 1)
+						assigned.add(u.id)
 						progress = true
 					}
 				}
 			}
 
-			if (assigned.size < plan.subtasks.length) {
-				const unassigned = plan.subtasks.filter((st) => !assigned.has(st.id)).map((st) => st.id)
+			if (assigned.size < units.length) {
+				const unassigned = units.filter((u) => !assigned.has(u.id)).map((u) => u.id)
 				return err(
-					`Could not assign all subtasks to waves. Missing dependency or orphan subtasks: ${unassigned.join(', ')}`,
+					`Could not assign all ${unit_kind}s to waves. Missing dependency or orphan ${unit_kind}s: ${unassigned.join(', ')}`,
 				)
 			}
 
@@ -144,45 +152,57 @@ export function cmdWave(subcommand, projectDir, extraArgs) {
 			const totalWaves = Math.max(...waveAssignment.values())
 			const wavesMap = new Map()
 			for (let w = 1; w <= totalWaves; w++) {
-				wavesMap.set(w, { wave: w, subtasks: [], files: [] })
+				// Output key per ID-03: subtask path keeps `subtasks`; task
+				// path uses `tasks`. Bit-equivalence for the subtask path
+				// is enforced by wave-engine-subtask-bit-equivalence.test.ts.
+				wavesMap.set(
+					w,
+					isTaskUnit ? { wave: w, tasks: [], files: [] } : { wave: w, subtasks: [], files: [] },
+				)
 			}
 
-			for (const st of plan.subtasks) {
-				const w = waveAssignment.get(st.id)
-				wavesMap.get(w).subtasks.push(st.id)
-				if (Array.isArray(st.files)) {
-					for (const f of st.files) {
-						if (!wavesMap.get(w).files.includes(f)) {
-							wavesMap.get(w).files.push(f)
+			for (const u of units) {
+				const w = waveAssignment.get(u.id)
+				const group = wavesMap.get(w)
+				if (isTaskUnit) group.tasks.push(u.id)
+				else group.subtasks.push(u.id)
+				if (Array.isArray(u.files)) {
+					for (const f of u.files) {
+						if (!group.files.includes(f)) {
+							group.files.push(f)
 						}
 					}
 				}
 			}
 
-			// File conflict check: files appearing in multiple subtasks within same wave
+			// File conflict check: files appearing in multiple units within same wave
 			const fileConflicts = []
 			for (const [w, group] of wavesMap) {
 				const fileOwners = new Map()
-				for (const stId of group.subtasks) {
-					const st = subtaskMap.get(stId)
-					if (Array.isArray(st.files)) {
-						for (const f of st.files) {
+				const groupIds = isTaskUnit ? group.tasks : group.subtasks
+				for (const uId of groupIds) {
+					const u = unitMap.get(uId)
+					if (Array.isArray(u.files)) {
+						for (const f of u.files) {
 							if (!fileOwners.has(f)) fileOwners.set(f, [])
-							fileOwners.get(f).push(stId)
+							fileOwners.get(f).push(uId)
 						}
 					}
 				}
 				for (const [file, owners] of fileOwners) {
 					if (owners.length > 1) {
-						fileConflicts.push({ wave: w, file, subtasks: owners })
+						fileConflicts.push(
+							isTaskUnit ? { wave: w, file, tasks: owners } : { wave: w, file, subtasks: owners },
+						)
 					}
 				}
 			}
 
-			// Build subtask_wave_map
-			const subtaskWaveMap = {}
+			// Build wave map. Subtask path: subtask_wave_map (back-compat).
+			// Task path: unit_id_wave_map (new).
+			const unitIdWaveMap = {}
 			for (const [id, w] of waveAssignment) {
-				subtaskWaveMap[id] = w
+				unitIdWaveMap[id] = w
 			}
 
 			// Apply --wave N filter (D-16)
@@ -191,13 +211,26 @@ export function cmdWave(subcommand, projectDir, extraArgs) {
 				waves = waves.filter((w) => w.wave === waveFilter)
 			}
 
+			if (isTaskUnit) {
+				return ok({
+					status: 'ok',
+					command: 'wave-analyze-task',
+					unit_kind: 'task',
+					total_waves: totalWaves,
+					waves,
+					file_conflicts: fileConflicts,
+					unit_id_wave_map: unitIdWaveMap,
+				})
+			}
+
+			// Back-compat subtask envelope — byte-equivalent to pre-refactor output.
 			return ok({
 				status: 'ok',
 				command: 'wave-analyze',
 				total_waves: totalWaves,
 				waves,
 				file_conflicts: fileConflicts,
-				subtask_wave_map: subtaskWaveMap,
+				subtask_wave_map: unitIdWaveMap,
 			})
 		}
 		default:

package/src/cli/commands/worktree.mjs

@@ -120,11 +120,12 @@ function doCreate(_subcommand, targetDir, extraArgs, SAFE_ID_PATTERN, SAFE_BRANC
 			)
 		}
 
-		// Resolve base branch: --from beats config beats current HEAD.
+		// Resolve base branch: --from beats config beats default chain.
 		const fromFlag = flags.get('from')
-		const fromPref = fromFlag || isolation.from_branch || 'current'
+		const fromPref = fromFlag || isolation.from_branch || 'main'
 		let baseBranch = fromPref
-		if (!fromPref || fromPref === 'current') {
+		if (fromPref === 'current' || fromPref === 'HEAD') {
+			// Explicit opt-in to chaining onto the user's current branch (AC8).
 			try {
 				baseBranch =
 					execSync('git rev-parse --abbrev-ref HEAD', {
@@ -134,7 +135,59 @@ function doCreate(_subcommand, targetDir, extraArgs, SAFE_ID_PATTERN, SAFE_BRANC
 			} catch {
 				baseBranch = 'HEAD'
 			}
+		} else if (fromPref === 'main') {
+			// Main-detection chain — local refs only, no network (per ID-02).
+			const candidates = ['origin/HEAD', 'origin/main', 'origin/master', 'main', 'master']
+			let resolved = null
+			for (const ref of candidates) {
+				try {
+					const out = execSync(`git rev-parse --verify ${ref}`, {
+						cwd: targetDir,
+						encoding: 'utf-8',
+						stdio: ['ignore', 'pipe', 'pipe'],
+					}).trim()
+					if (out) {
+						// origin/HEAD is a symref — resolve it to e.g. `origin/main`
+						// so the base branch we hand to `git worktree add` is usable.
+						if (ref === 'origin/HEAD') {
+							try {
+								const sym = execSync('git symbolic-ref refs/remotes/origin/HEAD', {
+									cwd: targetDir,
+									encoding: 'utf-8',
+									stdio: ['ignore', 'pipe', 'pipe'],
+								}).trim()
+								resolved = sym.replace(/^refs\/remotes\//, '') || ref
+							} catch {
+								resolved = ref
+							}
+						} else {
+							resolved = ref
+						}
+						break
+					}
+				} catch {
+					// Ref doesn't exist — try the next one.
+				}
+			}
+			if (resolved) {
+				baseBranch = resolved
+			} else {
+				// Degenerate repo (no main/master ref anywhere). Fall back to
+				// current HEAD so users in detached or greenfield repos still
+				// get a working worktree instead of a hard error.
+				try {
+					baseBranch =
+						execSync('git rev-parse --abbrev-ref HEAD', {
+							cwd: targetDir,
+							encoding: 'utf-8',
+						}).trim() || 'HEAD'
+				} catch {
+					baseBranch = 'HEAD'
+				}
+			}
 		}
+		// Any other explicit fromPref value (e.g. `origin/main`, `feature/foo`,
+		// a SHA) is used as-is and falls through to SAFE_BRANCH_PATTERN below.
 		if (!SAFE_BRANCH_PATTERN.test(baseBranch)) {
 			throw new WorktreeUsageError(
 				'Invalid base branch: must match [a-zA-Z0-9_-/.]. Got: ' + baseBranch,

package/src/cli/config/load.mjs

@@ -252,7 +252,7 @@ export function getTaskIsolationConfig(projectDir) {
 	const defaults = {
 		worktree_per_task: false,
 		branch_prefix: 'apt',
-		from_branch: 'current',
+		from_branch: 'main',
 		push_on_create: true,
 		cleanup_on_close: 'ask',
 		// C54 — language-agnostic worktree bootstrap. All off by default so

package/src/cli/config/parallelization.mjs

@@ -0,0 +1,18 @@
+/**
+ * config/parallelization.mjs — FRAMEWORK-BUG-033 capability gap (AC10).
+ *
+ * Single helper exporting the `parallelization.max_tasks` cap consumed by
+ * the `/apt:fan-out` SKILL body. Default 4 when the key is absent. D-07:
+ * no paternalism cap — autonomy-3 power users can set arbitrarily high
+ * values via `.aperant/config.json:parallelization.max_tasks`.
+ */
+
+/**
+ * @param {unknown} config — merged project config blob (or null/undefined).
+ * @returns {number} the configured max_tasks, or 4 when absent/invalid.
+ */
+export function getMaxTasks(config) {
+	const raw = config?.parallelization?.max_tasks
+	if (typeof raw === 'number' && Number.isFinite(raw) && raw > 0) return raw
+	return 4
+}

package/src/cli/coordination/agent-identity.mjs

@@ -83,7 +83,15 @@ export function getAgentIdentity(projectDir) {
 
 	const pid = process.pid
 	const host = osHostname()
-	const agentId = process.env.APT_AGENT_ID || `${host}-${pid}`
+	const rawAgentId = process.env.APT_AGENT_ID || `${host}-${pid}`
+	// SEC-001: Disallow path traversal characters in agentId since it's used as a filesystem path component.
+	const SAFE_AGENT_ID = /^[A-Za-z0-9._-]+$/
+	if (!SAFE_AGENT_ID.test(rawAgentId)) {
+		throw new Error(
+			`Invalid APT_AGENT_ID: must match [A-Za-z0-9._-]+. Got: ${JSON.stringify(rawAgentId)}`,
+		)
+	}
+	const agentId = rawAgentId
 	const incarnation = nextIncarnation(projectDir)
 	const identity = { agentId, pid, hostname: host, incarnation }
 	cache.set(sharedRoot, identity)

package/src/cli/dispatch.mjs

@@ -57,6 +57,7 @@ import { cmdDocsAudit } from './commands/docs-audit.mjs'
 import { cmdEditCheck } from './commands/edit-check.mjs'
 import { cmdEffects } from './commands/effects.mjs'
 import { cmdEvent } from './commands/event.mjs'
+import { cmdFanOut } from './commands/fan-out.mjs'
 import { cmdFeaturesAudit } from './commands/features-audit.mjs'
 import { cmdGate } from './commands/gate.mjs'
 import { cmdHealthCheck } from './commands/health-check.mjs'
@@ -265,6 +266,7 @@ export const DISPATCH = {
 	event: (args) => wrap(cmdEvent)(args[1], args[2], args.slice(3)),
 	effects: (args) => wrap(cmdEffects)(args[1], args[2], args.slice(3)),
 	wave: (args) => wrap(cmdWave)(args[1], args[2], args.slice(3)),
+	'fan-out': (args) => wrap(cmdFanOut)(args[1], args[2], args.slice(3)),
 	'coverage-check': (args) => wrap(cmdCoverageCheck)(args[1], args[2], args.slice(3)),
 	'design-template': (args) => wrap(cmdDesignTemplate)(args[1], args[2], args.slice(3)),
 	'variant-pick': (args) => wrap(cmdVariantPick)(args[1], args[2], args.slice(3)),

package/src/cli/install/cli-to-install-root.mjs

@@ -11,8 +11,6 @@
  * the lookups below work automatically.
  *
  * `null` is returned for:
- *   - CLIs with no install target (e.g. `pi` — host detected, but no apt
- *     install root exists for the Pi runtime).
  *   - `'unknown'` — deterministic branches (init/status/help) don't need a
  *     mapping; the router falls back to the framework-scoped dev default
  *     defined in getTrustedSkillSources().

package/src/cli/install/runtime-detect.mjs

@@ -30,9 +30,7 @@ import { MANIFEST_FILENAME } from './manifest.mjs'
  * @property {string|null} cliId    The `cli` string `detectHost()` returns
  *                                  when this runtime's CLI is at the prompt.
  *                                  `null` when the runtime has no install
- *                                  target mapped to a host CLI (e.g. `pi`,
- *                                  which has a detectable host but no apt
- *                                  install root of its own).
+ *                                  target mapped to a host CLI.
  * @property {string} [displayLabel] Optional user-facing label (e.g. "Kilo Code").
  *                                  When unset, callers fall back to the
  *                                  capitalized form of `id`. Use for runtimes
@@ -77,6 +75,13 @@ export const RUNTIMES = Object.freeze([
 		markers: ['.opencode/config.json'],
 		cliId: 'opencode',
 	},
+	{
+		id: 'pi',
+		flag: '--pi',
+		installRoot: '.pi',
+		markers: ['.pi/settings.json', '.pi/skills', '.pi/prompts'],
+		cliId: 'pi',
+	},
 	{
 		id: 'kilo',
 		flag: '--kilo',

package/src/cli/install/transforms/pi.mjs

@@ -0,0 +1,37 @@
+/**
+ * install/transforms/pi.mjs — Pi coding agent transform.
+ *
+ * Pi uses prompt templates under `.pi/prompts/` for slash commands and
+ * root-level skills under `.pi/skills/`. Unlike Codex, Pi supports
+ * colon-form prompt names, so `/apt:foo` references are preserved.
+ */
+
+import { basename, dirname } from 'node:path'
+import { substituteVersion } from './_shared.mjs'
+
+function promptNameForSkill(folder) {
+	if (folder === 'apt') return 'apt'
+	if (folder.startsWith('apt-')) return `apt:${folder.slice('apt-'.length)}`
+	return folder
+}
+
+/**
+ * @param {import('../pipeline.mjs').TransformInput} input
+ * @returns {import('../pipeline.mjs').TransformOutput[]}
+ */
+export function transform({ canonicalContent, canonicalRelPath, version, fileType }) {
+	const content = substituteVersion(canonicalContent, version)
+	if (fileType === 'skill') {
+		const folder = basename(dirname(canonicalRelPath))
+		const promptName = promptNameForSkill(folder)
+		return [
+			{ outputPath: `skills/${folder}/SKILL.md`, content },
+			{ outputPath: `prompts/${promptName}.md`, content },
+		]
+	}
+	if (fileType === 'agent') {
+		const file = basename(canonicalRelPath)
+		return [{ outputPath: `skills/${file}`, content }]
+	}
+	return []
+}

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,