@aperant/framework 0.6.5 → 0.6.6

package/src/cli/commands/task.mjs

@@ -14,7 +14,7 @@
 import { spawnSync } from 'node:child_process'
 import { existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs'
 import { join, resolve } from 'node:path'
-import { getTaskIsolationConfig } from '../config/load.mjs'
+import { getTaskIsolationConfig, loadProjectConfig } from '../config/load.mjs'
 import { findMostRecentEventForTask } from '../coordination/event-log.mjs'
 import { createCoordinationStore } from '../coordination/store.mjs'
 import { getGitIdentity } from '../git/identity.mjs'
@@ -40,13 +40,14 @@ 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 { cmdCiWatch } from './ci-watch.mjs'
 
 export function cmdTask(subcommand, projectDir, extraArgs) {
 	if (!subcommand)
 		return err(
 			'Usage: apt-tools task <create|list|get|close|update|move|complete-subtask|narration-drain|prune> <project-dir> [flags]',
 		)
-	if (!projectDir) return err('Usage: apt-tools task ' + subcommand + ' <project-dir> [flags]')
+	if (!projectDir) return err(`Usage: apt-tools task ${subcommand} <project-dir> [flags]`)
 
 	const targetDir = resolve(projectDir)
 	const statePath = join(targetDir, '.aperant', 'state.json')
@@ -129,166 +130,233 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 			// Load config for date format preference
 			const configPath = join(targetDir, '.aperant', 'config.json')
 			const config = existsSync(configPath) ? JSON.parse(readFileSync(configPath, 'utf-8')) : {}
-			const taskId = flags.get('id') || generateTaskId(description, config)
-
-			// Create task directory
-			const taskDir = getTaskDir(targetDir, taskId)
-			mkdirSync(taskDir, { recursive: true })
-			for (const subdir of ['events', 'locks']) {
-				mkdirSync(join(taskDir, subdir), { recursive: true })
+			// User-supplied --id bypasses the collision guard (caller owns the
+			// uniqueness contract). Generated ids run through a numeric-counter
+			// disambiguator that appends -2, -3, … when the candidate already
+			// exists in state or on disk. Bounded at 100 iterations as a
+			// defensive ceiling; same-day same-slug collisions are vanishingly
+			// rare so the loop should almost always terminate on the first try.
+			//
+			// BUG-2 fix: the candidate-selection scan, taskDir mkdir, and
+			// state.active_tasks write MUST all happen inside a single
+			// withFileLock critical section. Two concurrent task create calls
+			// in the multi-agent environment can otherwise both compute the
+			// same candidate against the same pre-lock snapshot of state and
+			// race into a duplicate-id write that silently overwrites the
+			// first task's record.
+			const SAFE_ID_PATTERN = /^[A-Za-z0-9._-]+$/
+			const explicitIdRaw = flags.get('id')
+			if (explicitIdRaw && !SAFE_ID_PATTERN.test(explicitIdRaw)) {
+				return err('[apt-tools] Invalid task id: must match /^[A-Za-z0-9._-]+$/', 1, {
+					command: 'task-create',
+				})
+			}
+			// Secondary guard: ensure the resolved task directory stays inside the
+			// tasks base. The SAFE_ID_PATTERN above blocks `/` and most traversal
+			// 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))
+				if (!candidateDir.startsWith(`${tasksBase}/`) && candidateDir !== tasksBase) {
+					return err('[apt-tools] Invalid task id: path escapes the tasks directory', 1, {
+						command: 'task-create',
+					})
+				}
 			}
 
-			// Register in state.json
-			if (existsSync(statePath)) {
-				withFileLock(
-					statePath,
-					() => {
-						const state = JSON.parse(readFileSync(statePath, 'utf-8'))
-
-						// Migrate: if old format (active_task singular), convert
-						if (state.active_task !== undefined && state.active_tasks === undefined) {
-							state.active_tasks = {}
-							if (state.active_task) {
-								const oldId = state.active_task.id || 'legacy-task'
-								state.active_tasks[oldId] = state.active_task
+			let taskId
+			let taskDir
+			let collisionOverflowErr = null
+
+			withFileLock(
+				statePath,
+				() => {
+					// Read state under the lock so the collision scan, taskDir
+					// mkdir, and state.active_tasks write all observe the same
+					// snapshot. withFileLock seeds an empty file if statePath
+					// doesn't exist, so the JSON.parse fallback handles the
+					// first-ever task create cleanly.
+					const raw = readFileSync(statePath, 'utf-8').trim()
+					const state = raw ? JSON.parse(raw) : {}
+
+					// Migrate: if old format (active_task singular), convert
+					if (state.active_task !== undefined && state.active_tasks === undefined) {
+						state.active_tasks = {}
+						if (state.active_task) {
+							const oldId = state.active_task.id || 'legacy-task'
+							state.active_tasks[oldId] = state.active_task
+						}
+						delete state.active_task
+					}
+					if (!state.active_tasks) state.active_tasks = {}
+
+					// Resolve taskId against the locked-in state snapshot.
+					if (explicitIdRaw) {
+						taskId = explicitIdRaw
+					} else {
+						const base = generateTaskId(description, config)
+						const activeIds = Object.keys(state.active_tasks)
+						const completedIds = Array.isArray(state.completed_tasks)
+							? state.completed_tasks.map((row) => row?.id).filter(Boolean)
+							: []
+						const known = new Set([...activeIds, ...completedIds])
+						const isTaken = (candidate) =>
+							known.has(candidate) || existsSync(getTaskDir(targetDir, candidate))
+						let candidate = base
+						let counter = 2
+						while (isTaken(candidate)) {
+							if (counter > 100) {
+								collisionOverflowErr = err(
+									`task create: collision counter exceeded 100 for base id "${base}" — manual --id required`,
+								)
+								return
 							}
-							delete state.active_task
+							candidate = `${base}-${counter}`
+							counter++
 						}
-						if (!state.active_tasks) state.active_tasks = {}
-
-						// Task-record lifecycle phase (NOT roadmap phase, NOT workflow phase).
-						// C28 D-02/D-03/D-08: scope + linkage + dependency-graph fields.
-						// R11 — resolve the outputs allowlist now so it is pinned at
-						// task creation time. If the planner edits the task record
-						// later (e.g. narrows the allowlist), it overwrites this.
-						const outputs = resolveDefaultOutputs({
-							id: taskId,
-							scope,
-							milestone_id: milestoneId,
-							phase_id: phaseIdForRoadmap,
-						})
+						taskId = candidate
+					}
 
-						state.active_tasks[taskId] = {
-							id: taskId,
-							description,
-							track,
-							autonomy,
-							// C21 — execution_mode is omitted entirely when unset so legacy
-							// readers (apt-plan SKILL.md 9a) continue to see `undefined`
-							// rather than `null` and fall through to the autonomy heuristic.
-							...(executionMode ? { execution_mode: executionMode } : {}),
-							scope,
-							milestone_id: milestoneId,
-							phase_id: phaseIdForRoadmap,
-							roadmap_ref_url: roadmapRefUrl,
-							depends_on: dependsOn,
-							outputs,
-							lifecycle_phase: 'planning',
-							history: [],
-							created_at: new Date().toISOString(),
-							progress: { subtasks_total: 0, subtasks_completed: 0, current_subtask: null },
-						}
+					// 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)
+					mkdirSync(taskDir, { recursive: true })
+					for (const subdir of ['events', 'locks']) {
+						mkdirSync(join(taskDir, subdir), { recursive: true })
+					}
 
-						// ── Task-level worktree hook ──────────────────────────────
-						// When task_isolation.worktree_per_task is enabled AND we're
-						// not already inside a worktree AND the host supports them,
-						// fork a branch + worktree and record its location on the
-						// task record. Any failure is downgraded to a warning so
-						// task-create never aborts.
-						const isolation = getTaskIsolationConfig(targetDir)
-						const host = detectHost()
-						if (
-							isolation.worktree_per_task === true &&
-							host.capabilities.worktrees === true &&
-							!detectWorktree(targetDir).is_worktree
-						) {
-							try {
-								const wtArgs = ['--task', taskId, '--scope', scope]
-								if (isolation.push_on_create) wtArgs.push('--push')
-								if (isolation.from_branch && isolation.from_branch !== 'current') {
-									wtArgs.push('--from', isolation.from_branch)
+					// Task-record lifecycle phase (NOT roadmap phase, NOT workflow phase).
+					// C28 D-02/D-03/D-08: scope + linkage + dependency-graph fields.
+					// R11 — resolve the outputs allowlist now so it is pinned at
+					// task creation time. If the planner edits the task record
+					// later (e.g. narrows the allowlist), it overwrites this.
+					const outputs = resolveDefaultOutputs({
+						id: taskId,
+						scope,
+						milestone_id: milestoneId,
+						phase_id: phaseIdForRoadmap,
+					})
+
+					state.active_tasks[taskId] = {
+						id: taskId,
+						description,
+						track,
+						autonomy,
+						// C21 — execution_mode is omitted entirely when unset so legacy
+						// readers (apt-plan SKILL.md 9a) continue to see `undefined`
+						// rather than `null` and fall through to the autonomy heuristic.
+						...(executionMode ? { execution_mode: executionMode } : {}),
+						scope,
+						milestone_id: milestoneId,
+						phase_id: phaseIdForRoadmap,
+						roadmap_ref_url: roadmapRefUrl,
+						depends_on: dependsOn,
+						outputs,
+						lifecycle_phase: 'planning',
+						history: [],
+						created_at: new Date().toISOString(),
+						progress: { subtasks_total: 0, subtasks_completed: 0, current_subtask: null },
+					}
+
+					// ── Task-level worktree hook ──────────────────────────────
+					// When task_isolation.worktree_per_task is enabled AND we're
+					// not already inside a worktree AND the host supports them,
+					// fork a branch + worktree and record its location on the
+					// task record. Any failure is downgraded to a warning so
+					// task-create never aborts.
+					const isolation = getTaskIsolationConfig(targetDir)
+					const host = detectHost()
+					if (
+						isolation.worktree_per_task === true &&
+						host.capabilities.worktrees === true &&
+						!detectWorktree(targetDir).is_worktree
+					) {
+						try {
+							const wtArgs = ['--task', taskId, '--scope', scope]
+							if (isolation.push_on_create) wtArgs.push('--push')
+							if (isolation.from_branch && isolation.from_branch !== 'current') {
+								wtArgs.push('--from', isolation.from_branch)
+							}
+							// 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
+							// its output discipline intact, then parse its JSON.
+							//
+							// D-03 — single source of truth for the apt-tools binary
+							// path (replaces the legacy process.argv[1] heuristic).
+							const aptToolsBin = resolveAptToolsBin(targetDir)
+							const createRes = spawnSync(
+								process.execPath,
+								[aptToolsBin, 'worktree', 'create', targetDir, ...wtArgs],
+								{ encoding: 'utf-8' },
+							)
+							if (createRes.status === 0 && createRes.stdout) {
+								const wtOut = JSON.parse(createRes.stdout)
+								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
+								state.active_tasks[taskId].remote_tracking = !!wtOut.remote_tracking
+								if (wtOut.scope) {
+									state.active_tasks[taskId].worktree_scope = wtOut.scope
 								}
-								// 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
-								// its output discipline intact, then parse its JSON.
-								//
-								// D-03 — single source of truth for the apt-tools binary
-								// path (replaces the legacy process.argv[1] heuristic).
-								const aptToolsBin = resolveAptToolsBin(targetDir)
-								const createRes = spawnSync(
-									process.execPath,
-									[aptToolsBin, 'worktree', 'create', targetDir, ...wtArgs],
-									{ encoding: 'utf-8' },
-								)
-								if (createRes.status === 0 && createRes.stdout) {
-									const wtOut = JSON.parse(createRes.stdout)
-									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
-									state.active_tasks[taskId].remote_tracking = !!wtOut.remote_tracking
-									if (wtOut.scope) {
-										state.active_tasks[taskId].worktree_scope = wtOut.scope
-									}
-									if (wtOut.push_warning) {
-										state.active_tasks[taskId].push_warning = wtOut.push_warning
-									}
-									// C54 — merge install_* fields surfaced by the
-									// worktree-install hook in worktree.mjs. These fields are
-									// absent on pre-C54 default-config paths, so readers that
-									// don't know about install_* continue to work unchanged.
-									if (wtOut.install && typeof wtOut.install === 'object') {
-										const inst = wtOut.install
-										if (inst.install_status)
-											state.active_tasks[taskId].install_status = inst.install_status
-										if (inst.install_log_path)
-											state.active_tasks[taskId].install_log_path = inst.install_log_path
-										if (inst.install_pid !== undefined && inst.install_pid !== null)
-											state.active_tasks[taskId].install_pid = inst.install_pid
-										if (Array.isArray(inst.install_ecosystems))
-											state.active_tasks[taskId].install_ecosystems = inst.install_ecosystems
-										if (inst.install_started_at)
-											state.active_tasks[taskId].install_started_at = inst.install_started_at
-										if (inst.install_finished_at)
-											state.active_tasks[taskId].install_finished_at = inst.install_finished_at
-										if (inst.install_warning)
-											state.active_tasks[taskId].install_warning = inst.install_warning
-										// C54 review: persist the per-ecosystem breakdown and
-										// pre-spawn scanner rejections. worktree-install already
-										// wrote these directly via updateState; forwarding them
-										// through the stdout merge keeps the exposed fields
-										// consistent with the install envelope.
-										if (
-											inst.install_per_ecosystem &&
-											typeof inst.install_per_ecosystem === 'object'
-										)
-											state.active_tasks[taskId].install_per_ecosystem = inst.install_per_ecosystem
-										if (Array.isArray(inst.install_rejections))
-											state.active_tasks[taskId].install_rejections = inst.install_rejections
-									}
-									if (wtOut.install_warning && !state.active_tasks[taskId].install_warning) {
-										state.active_tasks[taskId].install_warning = wtOut.install_warning
-									}
-								} else {
-									state.active_tasks[taskId].worktree_warning =
-										'worktree create failed: ' +
-										(createRes.stderr || createRes.stdout || 'unknown')
-											.toString()
-											.trim()
-											.split('\n')
-											.pop()
+								if (wtOut.push_warning) {
+									state.active_tasks[taskId].push_warning = wtOut.push_warning
 								}
-							} catch (e) {
-								state.active_tasks[taskId].worktree_warning = 'worktree hook error: ' + e.message
+								// C54 — merge install_* fields surfaced by the
+								// worktree-install hook in worktree.mjs. These fields are
+								// absent on pre-C54 default-config paths, so readers that
+								// don't know about install_* continue to work unchanged.
+								if (wtOut.install && typeof wtOut.install === 'object') {
+									const inst = wtOut.install
+									if (inst.install_status)
+										state.active_tasks[taskId].install_status = inst.install_status
+									if (inst.install_log_path)
+										state.active_tasks[taskId].install_log_path = inst.install_log_path
+									if (inst.install_pid !== undefined && inst.install_pid !== null)
+										state.active_tasks[taskId].install_pid = inst.install_pid
+									if (Array.isArray(inst.install_ecosystems))
+										state.active_tasks[taskId].install_ecosystems = inst.install_ecosystems
+									if (inst.install_started_at)
+										state.active_tasks[taskId].install_started_at = inst.install_started_at
+									if (inst.install_finished_at)
+										state.active_tasks[taskId].install_finished_at = inst.install_finished_at
+									if (inst.install_warning)
+										state.active_tasks[taskId].install_warning = inst.install_warning
+									// C54 review: persist the per-ecosystem breakdown and
+									// pre-spawn scanner rejections. worktree-install already
+									// wrote these directly via updateState; forwarding them
+									// through the stdout merge keeps the exposed fields
+									// consistent with the install envelope.
+									if (inst.install_per_ecosystem && typeof inst.install_per_ecosystem === 'object')
+										state.active_tasks[taskId].install_per_ecosystem = inst.install_per_ecosystem
+									if (Array.isArray(inst.install_rejections))
+										state.active_tasks[taskId].install_rejections = inst.install_rejections
+								}
+								if (wtOut.install_warning && !state.active_tasks[taskId].install_warning) {
+									state.active_tasks[taskId].install_warning = wtOut.install_warning
+								}
+							} else {
+								state.active_tasks[taskId].worktree_warning =
+									'worktree create failed: ' +
+									(createRes.stderr || createRes.stdout || 'unknown')
+										.toString()
+										.trim()
+										.split('\n')
+										.pop()
 							}
+						} catch (e) {
+							state.active_tasks[taskId].worktree_warning = `worktree hook error: ${e.message}`
 						}
+					}
 
-						state.last_activity = new Date().toISOString()
-						atomicWriteJson(statePath, state)
-					},
-					{ projectRoot: targetDir },
-				)
-			}
+					state.last_activity = new Date().toISOString()
+					atomicWriteJson(statePath, state)
+				},
+				{ projectRoot: targetDir },
+			)
+
+			if (collisionOverflowErr) return collisionOverflowErr
 
 			regenerateTaskIndex(targetDir)
 
@@ -811,6 +879,12 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 					// This collapses the two-call apt:ship contract into a single
 					// load-bearing call so orchestrators can't drop the lifecycle
 					// transition. Idempotent / no-op on any other phase.
+					let ciWatchResult = {
+						ci_watch_armed: false,
+						ci_watch_skip_reason: null,
+						ci_watch: null,
+					}
+					let prUrlForCiWatch = null
 					if (flags.has('pr-url')) {
 						const url = flags.get('pr-url')
 						if (!url || typeof url !== 'string') {
@@ -846,6 +920,7 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 								},
 							})
 						}
+						prUrlForCiWatch = url
 					}
 					if (flags.has('subtasks-total'))
 						task.progress.subtasks_total = parseInt(flags.get('subtasks-total'), 10)
@@ -906,6 +981,9 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 
 					state.last_activity = new Date().toISOString()
 					atomicWriteJson(statePath, state)
+					if (prUrlForCiWatch) {
+						ciWatchResult = armCiWatchAfterPrUrl(targetDir, task, prUrlForCiWatch)
+					}
 
 					regenerateTaskIndex(targetDir)
 
@@ -924,6 +1002,11 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 
 					const updateOut = { status: 'ok', command: 'task-update', task_id: taskId, task }
 					if (lifecycleTransition) updateOut.transition = lifecycleTransition
+					if (flags.has('pr-url')) {
+						updateOut.ci_watch_armed = ciWatchResult.ci_watch_armed
+						updateOut.ci_watch_skip_reason = ciWatchResult.ci_watch_skip_reason
+						if (ciWatchResult.ci_watch) updateOut.ci_watch = ciWatchResult.ci_watch
+					}
 					updateResult = ok(updateOut)
 				},
 				{ projectRoot: targetDir },
@@ -1461,7 +1544,7 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 			const skipped = []
 
 			for (const row of state.completed_tasks || []) {
-				if (!row || !row.id) continue
+				if (!row?.id) continue
 				const rowScope = row.scope || 'project'
 				if (scopeFilter && rowScope !== scopeFilter) {
 					skipped.push({ id: row.id, reason: 'scope-mismatch' })
@@ -1538,6 +1621,76 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 	}
 }
 
+function armCiWatchAfterPrUrl(targetDir, task, prUrl) {
+	const pr = extractPrNumber(prUrl)
+	if (!pr) {
+		return {
+			ci_watch_armed: false,
+			ci_watch_skip_reason: 'invalid-pr-url',
+			ci_watch: null,
+		}
+	}
+
+	const host = detectHost()
+	const defaultMode = host.capabilities?.cron ? 'auto' : 'never'
+	const config = loadProjectConfig(targetDir)
+	const configuredMode = config?.ci_watch?.after_ship || defaultMode
+	const mode = configuredMode === 'ask' && Number(task.autonomy) === 3 ? 'auto' : configuredMode
+
+	if (mode === 'never') {
+		return {
+			ci_watch_armed: false,
+			ci_watch_skip_reason: 'disabled',
+			ci_watch: null,
+		}
+	}
+
+	if (mode === 'ask') {
+		return {
+			ci_watch_armed: false,
+			ci_watch_skip_reason: 'ask-deferred',
+			ci_watch: null,
+		}
+	}
+
+	if (mode !== 'auto') {
+		return {
+			ci_watch_armed: false,
+			ci_watch_skip_reason: `invalid-config:${mode}`,
+			ci_watch: null,
+		}
+	}
+
+	const result = cmdCiWatch('start', targetDir, [
+		'--pr',
+		String(pr),
+		'--task-id',
+		task.id,
+		'--host',
+		host.cli || 'unknown',
+	])
+	const envelope = result?.envelope || {}
+	if (envelope.status === 'ok') {
+		return {
+			ci_watch_armed: true,
+			ci_watch_skip_reason: null,
+			ci_watch: envelope,
+		}
+	}
+	if (envelope.status === 'busy' && envelope.reason === 'already-armed') {
+		return {
+			ci_watch_armed: true,
+			ci_watch_skip_reason: 'already-armed',
+			ci_watch: envelope,
+		}
+	}
+	return {
+		ci_watch_armed: false,
+		ci_watch_skip_reason: envelope.reason || 'start-failed',
+		ci_watch: envelope,
+	}
+}
+
 /**
  * Extract a PR number from a GitHub URL like https://github.com/owner/repo/pull/123
  * or a short form like `owner/repo#123`. Returns null if not parseable.

package/src/cli/commands/triage.mjs

@@ -43,6 +43,14 @@ const VALID_TRANSITIONS = new Set([
 
 const BACKENDS = new Set(['local-only', 'github-issues', 'app-inbox'])
 
+// Two task-id shapes coexist:
+//   - Legacy date-first: YY-MM-DD_slug-XXXX (preserved so the ~159
+//     pre-slug-first tasks already on disk keep resolving).
+//   - Current slug-first: slug_YY-MM-DD with optional -N counter
+//     emitted by generateTaskId since the slug-first rename.
+const TASK_ID_RE_LEGACY = /^[0-9]{2}-[0-9]{2}-[0-9]{2}_[a-z0-9-]+-[a-z0-9]{4}$/
+const TASK_ID_RE_SLUG_FIRST = /^[a-z0-9][a-z0-9-]*_[0-9]{2}-[0-9]{2}-[0-9]{2}(-\d+)?$/
+
 /**
  * Read .aperant/config.json and extract task_tracking.backend.
  * Defaults to 'local-only' if the file or the key is missing.
@@ -145,11 +153,12 @@ export function cmdTriage(subcommand, projectDir, extraArgs) {
 	if (typeof taskId !== 'string' || taskId.trim() === '') {
 		return err('--id <task-id> is required', 1, { command: `triage-${subcommand}` })
 	}
-	const TASK_ID_RE = /^[0-9]{2}-[0-9]{2}-[0-9]{2}_[a-z0-9-]+-[a-z0-9]{4}$/
-	if (!TASK_ID_RE.test(taskId)) {
-		return err(`--id must match pattern <YY-MM-DD_slug-XXXX> (e.g. 24-01-15_fix-login-a3b2)`, 1, {
-			command: `triage-${subcommand}`,
-		})
+	if (!TASK_ID_RE_LEGACY.test(taskId) && !TASK_ID_RE_SLUG_FIRST.test(taskId)) {
+		return err(
+			`--id must match pattern <slug_YY-MM-DD[-N]> (e.g. fix-login_24-01-15) or legacy <YY-MM-DD_slug-XXXX>`,
+			1,
+			{ command: `triage-${subcommand}` },
+		)
 	}
 	const backend = readBackend(absProjectDir)
 

package/src/cli/coordination/auto-emit-artifact-ready.mjs

@@ -0,0 +1,96 @@
+/**
+ * @internal
+ * auto-emit-artifact-ready.mjs — code-enforced plan-ready signal.
+ *
+ * Promotes the `artifact.ready{kind:'plan'}` emit from a markdown contract
+ * in `skills/apt-plan/adapters/conductor.md` to a framework-level
+ * postcondition of `apt-tools commit`. This closes the Conductor v2 gap
+ * exposed during live verification 2026-05-15: the planner's QUICK /
+ * SIMPLE track is hard-exempt from "new interaction discipline"
+ * (Pocock Fast Path Guarantee ID-05), so the markdown emit step was
+ * never executed for tasks router-classified as simple. The fleet
+ * never saw artifact.ready, the PlanReadyCard never auto-promoted.
+ *
+ * The fix lives in `framework` rather than the skill so:
+ *   - it works for QUICK + STANDARD + DEEP + COMPLEX uniformly
+ *   - it doesn't violate the Fast Path Guarantee (a passive log emit
+ *     is not interaction discipline)
+ *   - it's the same code path every CLI consumer (Claude Code, Gemini,
+ *     OpenCode, Codex) traverses via `apt-tools commit`
+ *
+ * Conditions for emit (ALL must hold — otherwise no-op):
+ *   1. `APERANT_TERMINAL_ID` is set in process.env (Conductor PTY context).
+ *   2. The committed files include a path matching
+ *      `.aperant/tasks/{task-id}/implementation_plan.json`.
+ *
+ * The emit re-uses the same `event-schema` validator and JSONL writer
+ * `commands/event.mjs` already uses, so the envelope structure stays
+ * byte-identical with manually-emitted ones.
+ */
+
+import { createHash } from 'node:crypto'
+import { appendFileSync, mkdirSync, readFileSync } from 'node:fs'
+import { hostname } from 'node:os'
+import { join } from 'node:path'
+import { validateConductorEvent } from './event-schema.mjs'
+
+const PLAN_PATH_RE = /^(?:\.\/)?\.aperant\/tasks\/([^/]+)\/implementation_plan\.json$/
+
+let _incarnationCounter = 0
+
+/**
+ * @param {{ files: string[], projectRoot: string }} input
+ * @returns {{ emitted: false, reason: string } | { emitted: true, envelope: object, file: string }}
+ */
+export function maybeAutoEmitPlanReady({ files, projectRoot }) {
+	const terminalId = process.env.APERANT_TERMINAL_ID
+	if (!terminalId) return { emitted: false, reason: 'APERANT_TERMINAL_ID unset' }
+
+	const match = files.map((f) => f.replace(/\\/g, '/').match(PLAN_PATH_RE)).find((m) => m !== null)
+	if (!match) return { emitted: false, reason: 'no implementation_plan.json in committed files' }
+	const taskId = match[1]
+
+	const planRelPath = `.aperant/tasks/${taskId}/implementation_plan.json`
+	const absolutePath = join(projectRoot, planRelPath)
+
+	let hash
+	try {
+		const body = readFileSync(absolutePath)
+		hash = createHash('sha256').update(body).digest('hex')
+	} catch (err) {
+		return { emitted: false, reason: `plan file unreadable: ${(err && err.message) || err}` }
+	}
+
+	const data = {
+		kind: 'plan',
+		path: planRelPath,
+		hash,
+		request_id: `plan-${taskId}-${Date.now()}`,
+		task_id: taskId,
+		terminal_id: terminalId,
+	}
+
+	const validation = validateConductorEvent('artifact.ready', data)
+	if (!validation.ok) {
+		return { emitted: false, reason: `schema violation: ${validation.error}` }
+	}
+
+	const envelope = {
+		t: new Date().toISOString(),
+		agent: `${hostname()}-${process.pid}`,
+		pid: process.pid,
+		hostname: hostname(),
+		incarnation: ++_incarnationCounter,
+		op: 'artifact.ready',
+		task: taskId,
+		data,
+	}
+
+	const eventsDir = join(projectRoot, '.aperant', 'events')
+	mkdirSync(eventsDir, { recursive: true })
+	const dayFile = `${new Date().toISOString().slice(0, 10)}.jsonl`
+	const fullPath = join(eventsDir, dayFile)
+	appendFileSync(fullPath, `${JSON.stringify(envelope)}\n`, 'utf-8')
+
+	return { emitted: true, envelope, file: dayFile }
+}