@aperant/framework 0.13.0 → 0.15.0

package/src/cli/commands/pr-review.mjs

@@ -42,6 +42,7 @@ import { parseFlags } from '../util/args.mjs'
 import { withFileLock } from '../util/fs-lock.mjs'
 import { emitInitPrStateHint } from '../util/init-hints.mjs'
 import { err, exitWith, ok, UsageError } from '../util/result.mjs'
+import { cmdDetectSpecialists } from './pr-review/detect-specialists.mjs'
 import { cmdPrReviewAuditFixer } from './pr-review-audit-fixer.mjs'
 
 // C56 B4 — helper for self-staging committable pr-review writes. The
@@ -1083,7 +1084,7 @@ function handleSetAuthorshipOverride(root, flags) {
 export function cmdPrReview(subcommand, projectDir, extraArgs) {
 	if (!subcommand)
 		return err(
-			'Usage: apt-tools pr-review <init-pr|acquire-lock|release-lock|start-round|close-round|get-state|detect-authorship|record-comment|set-authorship-override|audit-fixer> <project-dir> [flags]',
+			'Usage: apt-tools pr-review <init-pr|acquire-lock|release-lock|start-round|close-round|get-state|detect-authorship|detect-specialists|record-comment|set-authorship-override|audit-fixer> <project-dir> [flags]',
 		)
 
 	// audit-fixer has its own argv shape (accepts --help in projectDir
@@ -1096,6 +1097,15 @@ export function cmdPrReview(subcommand, projectDir, extraArgs) {
 		return cmdPrReviewAuditFixer(projectDir, extraArgs)
 	}
 
+	// detect-specialists runs over an ARBITRARY project dir (the PR's worktree,
+	// or a unit-test fixture tree) that need NOT contain a `.aperant/` dir —
+	// the detector reads `.aperant/config.json` best-effort but does not
+	// require it. Delegate BEFORE the .aperant existence guard, like
+	// audit-fixer.
+	if (subcommand === 'detect-specialists') {
+		return cmdDetectSpecialists(projectDir, extraArgs)
+	}
+
 	if (!projectDir) return err(`Usage: apt-tools pr-review ${subcommand} <project-dir> [flags]`)
 
 	const root = resolve(projectDir)
@@ -1124,7 +1134,7 @@ export function cmdPrReview(subcommand, projectDir, extraArgs) {
 				return handleSetAuthorshipOverride(root, flags)
 			default:
 				return err(
-					`Unknown pr-review subcommand: ${subcommand}. Available: init-pr, acquire-lock, release-lock, start-round, close-round, get-state, detect-authorship, record-comment, set-authorship-override, audit-fixer`,
+					`Unknown pr-review subcommand: ${subcommand}. Available: init-pr, acquire-lock, release-lock, start-round, close-round, get-state, detect-authorship, detect-specialists, record-comment, set-authorship-override, audit-fixer`,
 				)
 		}
 	} catch (e) {

package/src/cli/commands/precompact-hook.mjs

@@ -11,6 +11,7 @@ import { existsSync, readFileSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 import { mergeClaudeHook } from '../install/claude-hooks.mjs'
 import { rawText } from '../util/result.mjs'
+import { resolveMainRepoRoot } from '../util/state-paths.mjs'
 
 /**
  * Install or merge the apt-tools PreCompact hook into
@@ -93,7 +94,10 @@ export function cmdPrecompactHook(projectDir) {
 		return rawText('', 0)
 	}
 
-	const statePath = join(aperantDir, 'state.json')
+	// state-fork-fix: state.json + tasks/ are EPHEMERAL — resolve to the main
+	// board so a post-compact agent in a worktree reads the authoritative tasks.
+	const stateRoot = resolveMainRepoRoot(targetDir)
+	const statePath = join(stateRoot, '.aperant', 'state.json')
 	if (!existsSync(statePath)) {
 		return rawText('', 0)
 	}
@@ -138,11 +142,11 @@ export function cmdPrecompactHook(projectDir) {
 	lines.push(`Active tasks (${taskIds.length}):`)
 
 	for (const [taskId, task] of Object.entries(activeTasks)) {
-		// Resolve task_dir deterministically via getTaskDir() — the task object
-		// does not store its own directory path; it's always derived from id.
-		// Use project-relative path so the post-compact agent can Read it
-		// regardless of cwd changes.
-		const taskDir = join('.aperant', 'tasks', taskId)
+		// Resolve task_dir deterministically — the task object does not store its
+		// own directory path; it's always derived from id. state-fork-fix: tasks/
+		// is EPHEMERAL, so anchor at the main-repo state root (cwd-independent AND
+		// points at the real spec/plan/progress, not a worktree's empty board).
+		const taskDir = join(stateRoot, '.aperant', 'tasks', taskId)
 		// Real schema from cmdTask create: description, lifecycle_phase,
 		// progress.{subtasks_total, subtasks_completed, current_subtask}.
 		// Title/status are fallbacks for legacy or hand-edited state.

package/src/cli/commands/roadmap.mjs

@@ -30,6 +30,7 @@ import { parseFlags } from '../util/args.mjs'
 import { withFileLock } from '../util/fs-lock.mjs'
 import { atomicWriteJson } from '../util/io.mjs'
 import { err, exitWith, ok, UsageError } from '../util/result.mjs'
+import { resolveMainRepoRoot } from '../util/state-paths.mjs'
 
 /**
  * Sentinel thrown by inner helpers (`loadRoadmap`, `resolveScope`, etc.) so
@@ -60,6 +61,15 @@ export async function cmdRoadmap(subcommand, projectDir, extraArgs) {
 
 async function cmdRoadmapImpl(subcommand, projectDir, extraArgs) {
 	const targetDir = resolve(projectDir)
+	// state-fork-fix ID-01/ID-05/ID-06: committable + ephemeral path-builds
+	// INTERLEAVE in this file. `roadmapRoot` (milestones.json + ROADMAP.md +
+	// SEEDS.md), seeds.json, and the per-scope sinks are COMMITTABLE and MUST
+	// stay worktree-local on `targetDir` so they ride the PR branch. Only the
+	// EPHEMERAL state.json reads/writes + their withFileLock roots redirect to
+	// the main repo via `stateRoot` — including the deliberately behavior-CHANGING
+	// seeds-count read (ID-05: from a worktree the SEEDS.md counts now reflect the
+	// authoritative main board, not a forked worktree's zeros).
+	const stateRoot = resolveMainRepoRoot(projectDir)
 	updateTeamMember(targetDir)
 	const roadmapRoot = join(targetDir, '.aperant', 'roadmap')
 	const flags = parseFlags(extraArgs)
@@ -332,7 +342,10 @@ async function cmdRoadmapImpl(subcommand, projectDir, extraArgs) {
 				}
 				let state = null
 				try {
-					const statePath = join(targetDir, '.aperant', 'state.json')
+					// ID-05 behavior-CHANGING redirect: seeds-count read resolves to
+					// the authoritative MAIN board so renderSeedsMd reports real
+					// project-wide counts even when render ran from a worktree.
+					const statePath = join(stateRoot, '.aperant', 'state.json')
 					state = existsSync(statePath) ? JSON.parse(readFileSync(statePath, 'utf-8')) : null
 				} catch {
 					/* state.json malformed — render with zero task counts */
@@ -526,7 +539,7 @@ async function cmdRoadmapImpl(subcommand, projectDir, extraArgs) {
 			// same state.json lock so a concurrent task create can't slip a new
 			// reference in between the check and the roadmap mutation.
 			if (status === 'deleted') {
-				const statePathLocal = join(targetDir, '.aperant', 'state.json')
+				const statePathLocal = join(stateRoot, '.aperant', 'state.json')
 				let cascadedCount = 0
 				let blockedAffected = null
 				if (existsSync(statePathLocal)) {
@@ -563,7 +576,7 @@ async function cmdRoadmapImpl(subcommand, projectDir, extraArgs) {
 								cascadedCount = freshAffected.length
 							}
 						},
-						{ projectRoot: targetDir },
+						{ projectRoot: stateRoot },
 					)
 				}
 				if (blockedAffected) {
@@ -577,7 +590,7 @@ async function cmdRoadmapImpl(subcommand, projectDir, extraArgs) {
 						1,
 					)
 				}
-				if (cascadedCount > 0) regenerateTaskIndex(targetDir)
+				if (cascadedCount > 0) regenerateTaskIndex(stateRoot)
 				// Remove the phase entirely when status=deleted.
 				milestone.phases = milestone.phases.filter((p) => p.id !== phaseId)
 				saveRoadmap(scope, roadmap)
@@ -676,7 +689,7 @@ async function cmdRoadmapImpl(subcommand, projectDir, extraArgs) {
 
 			// Atomic orphan-block check + cascade under the state.json lock to
 			// close the TOCTOU window between the check and the roadmap write.
-			const stPath = join(targetDir, '.aperant', 'state.json')
+			const stPath = join(stateRoot, '.aperant', 'state.json')
 			let cascadedCount = 0
 			let blockedAffected = null
 			if (existsSync(stPath)) {
@@ -713,7 +726,7 @@ async function cmdRoadmapImpl(subcommand, projectDir, extraArgs) {
 							cascadedCount = freshAffected.length
 						}
 					},
-					{ projectRoot: targetDir },
+					{ projectRoot: stateRoot },
 				)
 			}
 			if (blockedAffected) {
@@ -727,7 +740,7 @@ async function cmdRoadmapImpl(subcommand, projectDir, extraArgs) {
 					1,
 				)
 			}
-			if (cascadedCount > 0) regenerateTaskIndex(targetDir)
+			if (cascadedCount > 0) regenerateTaskIndex(stateRoot)
 
 			milestone.phases = milestone.phases.filter((p) => p.id !== phaseId)
 			saveRoadmap(scope, roadmap)
@@ -772,7 +785,7 @@ async function cmdRoadmapImpl(subcommand, projectDir, extraArgs) {
 				throw new RoadmapUsageError(`Milestone "${milestoneId}" not found in scope "${scope}"`)
 
 			// Atomic orphan-block check + cascade under the state.json lock.
-			const stPath = join(targetDir, '.aperant', 'state.json')
+			const stPath = join(stateRoot, '.aperant', 'state.json')
 			let cascadedCount = 0
 			let blockedAffected = null
 			if (existsSync(stPath)) {
@@ -809,7 +822,7 @@ async function cmdRoadmapImpl(subcommand, projectDir, extraArgs) {
 							cascadedCount = freshAffected.length
 						}
 					},
-					{ projectRoot: targetDir },
+					{ projectRoot: stateRoot },
 				)
 			}
 			if (blockedAffected) {
@@ -823,7 +836,7 @@ async function cmdRoadmapImpl(subcommand, projectDir, extraArgs) {
 					1,
 				)
 			}
-			if (cascadedCount > 0) regenerateTaskIndex(targetDir)
+			if (cascadedCount > 0) regenerateTaskIndex(stateRoot)
 
 			// C34c — capture the phase ids before filtering so we can unlink each
 			// `.aperant/roadmap/{scope}/phases/{id}.json` and prevent the
@@ -851,7 +864,7 @@ async function cmdRoadmapImpl(subcommand, projectDir, extraArgs) {
 			// project root and grep for `<a id="<anchor>">`. For URL: unless
 			// --offline, HEAD via curl with a 5s timeout. Emits {status, checked, broken}.
 			const offline = extraArgs.includes('--offline')
-			const statePathLocal = join(targetDir, '.aperant', 'state.json')
+			const statePathLocal = join(stateRoot, '.aperant', 'state.json')
 			const broken = []
 			let checked = 0
 

package/src/cli/commands/seed.mjs

@@ -39,6 +39,7 @@ import { updateTeamMember } from '../team/team.mjs'
 import { parseFlags } from '../util/args.mjs'
 import { withFileLock } from '../util/fs-lock.mjs'
 import { err, exitWith, ok } from '../util/result.mjs'
+import { resolveMainRepoRoot } from '../util/state-paths.mjs'
 
 /**
  * Run validateSeeds against the current on-disk state.
@@ -65,7 +66,8 @@ function runValidation(targetDir) {
  */
 function gatherSeedTasks(targetDir, refs) {
 	const out = { active: 0, completed: 0, total: 0, tasks: [] }
-	const statePath = join(targetDir, '.aperant', 'state.json')
+	// state-fork-fix: ephemeral state read resolves to the main board.
+	const statePath = join(resolveMainRepoRoot(targetDir), '.aperant', 'state.json')
 	if (!existsSync(statePath)) return out
 	let state
 	try {

package/src/cli/commands/state.mjs

@@ -16,6 +16,7 @@ import { parseFlags } from '../util/args.mjs'
 import { withFileLock } from '../util/fs-lock.mjs'
 import { atomicWriteJson } from '../util/io.mjs'
 import { err, exitWith, ok } from '../util/result.mjs'
+import { resolveMainRepoRoot } from '../util/state-paths.mjs'
 
 /**
  * Emit a human-readable preview to stderr when stdout is a TTY. Never throws;
@@ -38,7 +39,10 @@ export function cmdState(projectDir) {
 	if (!projectDir) return err('Usage: apt-tools state <project-dir>')
 	const targetDir = resolve(projectDir)
 	const aperantDir = join(targetDir, '.aperant')
-	const statePath = join(aperantDir, 'state.json')
+	// state-fork-fix: state.json is EPHEMERAL — resolve to the main board so
+	// `state .` from a worktree reads the authoritative board (the primary fork
+	// victim). config.json is COMMITTABLE — it stays worktree-local on aperantDir.
+	const statePath = join(resolveMainRepoRoot(projectDir), '.aperant', 'state.json')
 	const configPath = join(aperantDir, 'config.json')
 
 	if (!existsSync(aperantDir)) {
@@ -145,7 +149,9 @@ export function cmdStateUpdate(projectDir, args) {
 	if (!projectDir)
 		return err('Usage: apt-tools state-update <project-dir> --field <path> --value <json>')
 	const targetDir = resolve(projectDir)
-	const statePath = join(targetDir, '.aperant', 'state.json')
+	// state-fork-fix: ephemeral state-update resolves + locks against the main board.
+	const stateRoot = resolveMainRepoRoot(projectDir)
+	const statePath = join(stateRoot, '.aperant', 'state.json')
 
 	if (!existsSync(statePath)) return err('No .aperant/state.json found.')
 
@@ -183,7 +189,7 @@ export function cmdStateUpdate(projectDir, args) {
 
 			atomicWriteJson(statePath, state)
 		},
-		{ projectRoot: targetDir },
+		{ projectRoot: stateRoot },
 	)
 
 	return ok({ status: 'ok', command: 'state-update', field, value, projectDir: targetDir })

package/src/cli/commands/statusline.mjs

@@ -22,6 +22,7 @@ import { formatUpdateChips, readUpdateCache } from '../install/update-chips.mjs'
 import { statusLine, supportsColor } from '../output-style/index.mjs'
 import { parseFlags } from '../util/args.mjs'
 import { err, ok, rawText } from '../util/result.mjs'
+import { resolveMainRepoRoot } from '../util/state-paths.mjs'
 
 /**
  * Normalize `active_tasks` from state.json across the legacy (single object)
@@ -143,7 +144,10 @@ export function cmdStatusline(projectDir, extraArgs = []) {
 	})
 
 	const aperantDir = join(targetDir, '.aperant')
-	const statePath = join(aperantDir, 'state.json')
+	// state-fork-fix: state.json is EPHEMERAL — resolve to the main board (aligns
+	// with the createCoordinationStore redirect below). The local aperantDir is
+	// kept only for the not-initialized existence check.
+	const statePath = join(resolveMainRepoRoot(targetDir), '.aperant', 'state.json')
 
 	// Read SessionStart worker cache once — chips prepend onto every render
 	// path (initialized or not).

package/src/cli/commands/task.mjs

@@ -21,6 +21,7 @@ import {
 } from '../config/load.mjs'
 import { findMostRecentEventForTask } from '../coordination/event-log.mjs'
 import { createCoordinationStore } from '../coordination/store.mjs'
+import { listBlockingRowsForClose, parseFollowups } from '../followups/schema.mjs'
 import { getGitIdentity } from '../git/identity.mjs'
 import { detectWorktree } from '../git/worktree-detect.mjs'
 import {
@@ -44,6 +45,7 @@ import { parseDuration } from '../util/duration.mjs'
 import { withFileLock } from '../util/fs-lock.mjs'
 import { atomicWriteJson } from '../util/io.mjs'
 import { err, exitWith, ok } from '../util/result.mjs'
+import { resolveMainRepoRoot } from '../util/state-paths.mjs'
 import { cmdCiWatch } from './ci-watch.mjs'
 
 export function cmdTask(subcommand, projectDir, extraArgs) {
@@ -54,7 +56,14 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 	if (!projectDir) return err(`Usage: apt-tools task ${subcommand} <project-dir> [flags]`)
 
 	const targetDir = resolve(projectDir)
-	const statePath = join(targetDir, '.aperant', 'state.json')
+	// state-fork-fix ID-01/ID-04: ephemeral state (state.json + tasks/) resolves
+	// to the MAIN repo from any worktree cwd, so the task board never forks into
+	// a worktree's gitignored .aperant/. task.mjs touches ONLY ephemeral state
+	// (the mechanical exception in ID-01), so threading one stateRoot is correct.
+	// Committable roadmap path-builds in this file (the milestones.json reads)
+	// deliberately stay on the raw targetDir — they MUST ride the task branch.
+	const stateRoot = resolveMainRepoRoot(projectDir)
+	const statePath = join(stateRoot, '.aperant', 'state.json')
 	const flags = parseFlags(extraArgs)
 
 	// R8 — @internal CoordinationStore seam. V1 is a thin wrapper over the
@@ -167,8 +176,8 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 			// but allows `.` and `..` as valid characters. A lone `..` id would
 			// escape via getTaskDir's join: `tasks/..` resolves to `.aperant/`.
 			if (explicitIdRaw) {
-				const tasksBase = resolve(join(targetDir, '.aperant', 'tasks'))
-				const candidateDir = resolve(getTaskDir(targetDir, explicitIdRaw))
+				const tasksBase = resolve(join(stateRoot, '.aperant', 'tasks'))
+				const candidateDir = resolve(getTaskDir(stateRoot, explicitIdRaw))
 				if (!candidateDir.startsWith(`${tasksBase}/`) && candidateDir !== tasksBase) {
 					return err('[apt-tools] Invalid task id: path escapes the tasks directory', 1, {
 						command: 'task-create',
@@ -213,7 +222,7 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 							: []
 						const known = new Set([...activeIds, ...completedIds])
 						const isTaken = (candidate) =>
-							known.has(candidate) || existsSync(getTaskDir(targetDir, candidate))
+							known.has(candidate) || existsSync(getTaskDir(stateRoot, candidate))
 						let candidate = base
 						let counter = 2
 						while (isTaken(candidate)) {
@@ -231,7 +240,7 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 
 					// Create task directory under the lock so a concurrent
 					// run can't observe (and then re-pick) a half-created id.
-					taskDir = getTaskDir(targetDir, taskId)
+					taskDir = getTaskDir(stateRoot, taskId)
 					mkdirSync(taskDir, { recursive: true })
 					for (const subdir of ['events', 'locks']) {
 						mkdirSync(join(taskDir, subdir), { recursive: true })
@@ -295,6 +304,10 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 							if (isolation.from_branch && isolation.from_branch !== 'current') {
 								wtArgs.push('--from', isolation.from_branch)
 							}
+							// state-fork-fix ID-09b: forward the task's effective autonomy
+							// so `worktree create` can pick the 0-1 confirm vs. 2-3 log
+							// branch for a non-default `from_branch: current` base.
+							wtArgs.push('--autonomy', String(autonomy))
 							// Invoke inline so we capture the structured payload
 							// without shelling back out. We cheat by calling the
 							// worktree creator directly as a subprocess to keep
@@ -310,6 +323,19 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 							)
 							if (createRes.status === 0 && createRes.stdout) {
 								const wtOut = JSON.parse(createRes.stdout)
+								// state-fork-fix ID-09b: a requires_input non-default-base
+								// return (autonomy <= 1) is NOT a created worktree — degrade
+								// it to a worktree_warning so task-create still SUCCEEDS
+								// (task created, worktree deferred) instead of recording a
+								// bogus undefined worktree_path. The operator re-runs
+								// `worktree create` with an explicit --from.
+								if (wtOut.status === 'requires_input' || wtOut.reason === 'non_default_base') {
+									state.active_tasks[taskId].worktree_warning =
+										`worktree deferred: non-default base — re-run worktree create with explicit --from (base would be '${wtOut.base_branch}', default '${wtOut.default_branch}')`
+									state.last_activity = new Date().toISOString()
+									atomicWriteJson(statePath, state)
+									return
+								}
 								state.active_tasks[taskId].worktree_path = wtOut.worktree_path
 								state.active_tasks[taskId].branch = wtOut.branch
 								state.active_tasks[taskId].base_branch = wtOut.base_branch
@@ -370,12 +396,12 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 					state.last_activity = new Date().toISOString()
 					atomicWriteJson(statePath, state)
 				},
-				{ projectRoot: targetDir },
+				{ projectRoot: stateRoot },
 			)
 
 			if (collisionOverflowErr) return collisionOverflowErr
 
-			regenerateTaskIndex(targetDir)
+			regenerateTaskIndex(stateRoot)
 
 			// Team collaboration: register user + add to active board
 			updateTeamMember(targetDir)
@@ -517,7 +543,7 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 									atomicWriteJson(statePath, freshState)
 								}
 							},
-							{ projectRoot: targetDir },
+							{ projectRoot: stateRoot },
 						)
 					} catch {
 						/* best-effort — the in-memory `task` is already rewritten */
@@ -525,7 +551,7 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 				}
 			}
 
-			const taskDir = getTaskDir(targetDir, taskId)
+			const taskDir = getTaskDir(stateRoot, taskId)
 			const hasSpec = existsSync(join(taskDir, 'spec.md'))
 			const hasPlan = existsSync(join(taskDir, 'implementation_plan.json'))
 			const hasProgress = existsSync(join(taskDir, 'build-progress.json'))
@@ -549,6 +575,18 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 			// runs fetch + ff-only instead.
 			const prMerged = flags.has('pr-merged-remotely')
 
+			// G45 — followups disposition gate. `--force --reason "<text>"`
+			// bypasses it with an audit event (G42 Phase 1 pattern). Reject
+			// --force without --reason, mirroring gate.mjs:88.
+			const closeForce = flags.get('force') === true
+			const closeReasonRaw = flags.get('reason')
+			const closeReason = typeof closeReasonRaw === 'string' ? closeReasonRaw : null
+			if (closeForce && !closeReason) {
+				return err(
+					'--force requires --reason "<explanation>" (the override is logged to the audit trail)',
+				)
+			}
+
 			if (!existsSync(statePath)) return err('No state.json found')
 
 			// withFileLock callback can produce either an error envelope (early
@@ -560,14 +598,16 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 				() => {
 					const state = JSON.parse(readFileSync(statePath, 'utf-8'))
 
-					// Handle both formats
+					// Locate the task WITHOUT mutating yet — the G45 disposition
+					// gate (below) must run before any state mutation so a refused
+					// close leaves active_tasks intact.
 					let task = null
+					let taskInActiveMap = false
 					if (state.active_tasks?.[taskId]) {
 						task = state.active_tasks[taskId]
-						delete state.active_tasks[taskId]
+						taskInActiveMap = true
 					} else if (state.active_task?.id === taskId) {
 						task = state.active_task
-						state.active_task = null
 					}
 
 					if (!task) {
@@ -575,6 +615,75 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 						return
 					}
 
+					// G45 — followups disposition gate (ID-06 / ID-13). Runs at the
+					// TOP of the lock, before any state mutation, so close-merged
+					// (:1476 spawns `task close`) + the passive sweep inherit it.
+					// Skipped for verdict 'rejected' (abandoned work has moot
+					// follow-ups). Absent/malformed followups.json → no gating
+					// (byte-identical close; malformed is `followups check`'s
+					// problem, not close's). `--force --reason` bypasses with an
+					// audited task.close.followups-override event.
+					if (verdict !== 'rejected') {
+						const followupsPath = join(getTaskDir(stateRoot, taskId), 'followups.json')
+						let ledgerDoc = null
+						if (existsSync(followupsPath)) {
+							try {
+								ledgerDoc = JSON.parse(readFileSync(followupsPath, 'utf-8'))
+							} catch {
+								ledgerDoc = null // malformed → no gating
+							}
+						}
+						if (ledgerDoc !== null) {
+							const parsed = parseFollowups(ledgerDoc)
+							const blocking = listBlockingRowsForClose(parsed)
+							if (blocking.length > 0) {
+								const blockingSummary = blocking.map((r) => ({
+									id: r.id,
+									title: r.title ?? null,
+									status: r.status,
+									verdict: r.adjudication?.verdict ?? 'unadjudicated',
+									disposition_kind: r.disposition?.kind ?? null,
+								}))
+								if (!closeForce) {
+									closeError = err(
+										`Task "${taskId}" has ${blocking.length} open follow-up row(s) without a durable disposition — disposition them (\`apt-tools followups disposition\`) or re-run with --force --reason "<text>"`,
+										1,
+										{
+											command: 'task-close',
+											task_id: taskId,
+											blocking_followups: blockingSummary,
+										},
+									)
+									return
+								}
+								// Forced bypass — audit the override. `appendEvent` is
+								// best-effort (it swallows I/O errors so a full disk
+								// can't block a lifecycle transition). For this
+								// accountability event specifically, surface a stderr
+								// warning when the write does not land so the bypass
+								// is never SILENTLY unaudited — without re-introducing
+								// a hard block on the close.
+								const auditLogged = store.appendEvent({
+									op: 'task.close.followups-override',
+									task: taskId,
+									data: { rows: blockingSummary, reason: closeReason },
+								})
+								if (!auditLogged) {
+									process.stderr.write(
+										`[task-close] WARNING: forced followups override for "${taskId}" could not be written to the audit log — the bypass proceeded UNAUDITED.\n`,
+									)
+								}
+							}
+						}
+					}
+
+					// Gate passed (or bypassed) — now mutate.
+					if (taskInActiveMap) {
+						delete state.active_tasks[taskId]
+					} else {
+						state.active_task = null
+					}
+
 					if (!state.completed_tasks) state.completed_tasks = []
 					// C28 — preserve scope + lifecycle_phase on the completed row so
 					// INDEX.md can group completed tasks by scope and CompletedTaskRecord
@@ -591,7 +700,7 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 					state.last_activity = new Date().toISOString()
 					atomicWriteJson(statePath, state)
 
-					regenerateTaskIndex(targetDir)
+					regenerateTaskIndex(stateRoot)
 
 					// Team collaboration: remove from active board
 					updateTeamMember(targetDir)
@@ -742,7 +851,7 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 					}
 					closeResult = ok(closeOut)
 				},
-				{ projectRoot: targetDir },
+				{ projectRoot: stateRoot },
 			)
 			return closeError ?? closeResult
 		}
@@ -1054,7 +1163,7 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 						}
 					}
 
-					regenerateTaskIndex(targetDir)
+					regenerateTaskIndex(stateRoot)
 
 					// Team collaboration: sync active board with updated state
 					updateTeamMember(targetDir)
@@ -1084,7 +1193,7 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 					}
 					updateResult = ok(updateOut)
 				},
-				{ projectRoot: targetDir },
+				{ projectRoot: stateRoot },
 			)
 			return updateError ?? updateResult
 		}
@@ -1236,7 +1345,7 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 					state.last_activity = new Date().toISOString()
 					atomicWriteJson(statePath, state)
 
-					regenerateTaskIndex(targetDir)
+					regenerateTaskIndex(stateRoot)
 					updateTeamMember(targetDir)
 					store.upsertTeamStatus(taskId, {
 						description: task.description,
@@ -1253,7 +1362,7 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 						task,
 					})
 				},
-				{ projectRoot: targetDir },
+				{ projectRoot: stateRoot },
 			)
 			return moveError ?? moveResult
 		}
@@ -1272,7 +1381,10 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 			const notes = flags.get('notes') || null
 			try {
 				const result = completeSubtask({
-					projectDir: targetDir,
+					// state-fork-fix: tasks/<id>/ (plan + build-progress.json) is
+					// EPHEMERAL — resolve to the main board so a complete-subtask
+					// issued from a worktree updates the one authoritative task dir.
+					projectDir: stateRoot,
 					taskId,
 					subtaskId: subtaskIdFlag,
 					commit,
@@ -1461,7 +1573,7 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 									prUrlMutated = true
 								}
 							},
-							{ projectRoot: targetDir },
+							{ projectRoot: stateRoot },
 						)
 					}
 				} catch {
@@ -1592,7 +1704,7 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 								})
 								atomicWriteJson(statePath, fresh)
 							},
-							{ projectRoot: targetDir },
+							{ projectRoot: stateRoot },
 						)
 					} catch (e) {
 						errors.push({
@@ -1647,7 +1759,7 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 					}
 					remaining = ledger.length
 				},
-				{ projectRoot: targetDir },
+				{ projectRoot: stateRoot },
 			)
 
 			return ok({
@@ -1712,7 +1824,7 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 					skipped.push({ id: row.id, reason: 'worktree-active' })
 					continue
 				}
-				const taskDir = getTaskDir(targetDir, row.id)
+				const taskDir = getTaskDir(stateRoot, row.id)
 				if (!existsSync(taskDir)) {
 					skipped.push({ id: row.id, reason: 'dir-missing' })
 					continue