@aperant/framework 0.7.3 → 0.8.0

package/src/cli/commands/validate-evidence.mjs

@@ -21,9 +21,12 @@
  *      → dismiss.
  *
  * Mutations are written back in place — the findings markdown gets a
- * new `- **Validation Status**: ${status}` line plus a
- * `### Validation Note` block. The command always exits 0; the caller
- * checks the JSON summary on stdout.
+ * trailing `### Validation Metadata` section per finding carrying
+ * `- **Status**: …` and (optionally) `- **Note**: …` fields (the legacy
+ * field-form `- **Validation Status**:` + `### Validation Note` shape is
+ * still READ for back-compat but never re-emitted — see
+ * FRAMEWORK-BUG-034 in `docs/frameworks/spec-gaps.md`). The command
+ * always exits 0; the caller checks the JSON summary on stdout.
  *
  * Usage:
  *   apt-tools validate-evidence <findings-dir> --worktree <path>
@@ -189,10 +192,25 @@ export function parseFindingsMarkdown(markdown) {
 }
 
 function parseFindingBlock(body, id, title, start, end) {
+	// FRAMEWORK-BUG-034: strip any stamper-emitted Validation Status /
+	// Validation Note / Validation Metadata content from the body BEFORE
+	// extracting fields and evidence. The legacy field-form
+	// `- **Validation Status**: ...` line was bleeding into `fields.evidence`
+	// because the `fieldRx` `\s*` after the empty-value `- **Evidence**:`
+	// marker consumed the newline and grabbed the next line as the field's
+	// value. Stripping pre-parse keeps the parser inputs clean regardless of
+	// whether the file was stamped under the old or new shape. The original
+	// body is preserved for `raw` and for the dual-shape `hasValidationStatus`
+	// detector below.
+	const cleanBody = body
+		.replace(/^-\s*\*\*Validation Status\*\*:[^\n]*\n?/gim, '')
+		.replace(/\n?###\s*Validation Note\s*\n[\s\S]*?(?=\n###|$)/i, '')
+		.replace(/\n?###\s*Validation Metadata\s*\n[\s\S]*?(?=\n###|$)/i, '')
+
 	const fields = {}
 	// `- **File**: \`path:line\`` etc.
 	const fieldRx = /^-\s*\*\*([^*]+)\*\*:\s*(.+)$/gm
-	for (const m of body.matchAll(fieldRx)) {
+	for (const m of cleanBody.matchAll(fieldRx)) {
 		const key = m[1].trim().toLowerCase()
 		fields[key] = m[2].trim()
 	}
@@ -226,7 +244,7 @@ function parseFindingBlock(body, id, title, start, end) {
 	}
 
 	// Description block: everything between `### Description` and the next `###`.
-	const description = extractSection(body, 'Description') ?? ''
+	const description = extractSection(cleanBody, 'Description') ?? ''
 
 	// Evidence code block: first triple-backticked block after `### Evidence`
 	// (specialist shape). BUG-032: validator-consolidated `validated.md`
@@ -234,7 +252,13 @@ function parseFindingBlock(body, id, title, start, end) {
 	// fenced block immediately following the field line. Fall back to the
 	// first fenced block after that field marker when the section heading
 	// form yields nothing.
-	const evidenceSection = extractSection(body, 'Evidence') ?? ''
+	//
+	// FRAMEWORK-BUG-034: the `fieldEvidenceRx` fallback below is safe as-is
+	// because the writer no longer emits `- **Validation Status**` field-form
+	// lines (see stampFindings comment) AND `parseFindingBlock` strips any
+	// legacy Status / Validation Note text from `cleanBody` above, so the
+	// regex can no longer trip on the stamper's own output.
+	const evidenceSection = extractSection(cleanBody, 'Evidence') ?? ''
 	let evidence
 	const fenced = /```[^\n]*\n([\s\S]*?)```/.exec(evidenceSection)
 	if (fenced) {
@@ -243,7 +267,7 @@ function parseFindingBlock(body, id, title, start, end) {
 		evidence = evidenceSection
 	} else {
 		const fieldEvidenceRx = /-\s*\*\*Evidence\*\*:\s*(?:\n+)```[^\n]*\n([\s\S]*?)```/i
-		const fieldFenced = fieldEvidenceRx.exec(body)
+		const fieldFenced = fieldEvidenceRx.exec(cleanBody)
 		evidence = fieldFenced ? fieldFenced[1] : (fields.evidence ?? '')
 	}
 
@@ -251,10 +275,10 @@ function parseFindingBlock(body, id, title, start, end) {
 	// Evidence we keep the whole section — snippets AND surrounding
 	// sentences both live here — because file tokens in either form are
 	// legitimate evidence that the fix crosses files.
-	const suggestedFix = extractSection(body, 'Suggested Fix') ?? ''
+	const suggestedFix = extractSection(cleanBody, 'Suggested Fix') ?? ''
 
 	// Line range: Evidence Context -> "Lines examined: a-b"
-	const contextSection = extractSection(body, 'Evidence Context') ?? ''
+	const contextSection = extractSection(cleanBody, 'Evidence Context') ?? ''
 	const rangeMatch = /Lines? examined[^\d]*(\d+)\s*-\s*(\d+)/i.exec(contextSection)
 	const lineRange = rangeMatch
 		? [Number(rangeMatch[1]), Number(rangeMatch[2])]
@@ -266,7 +290,7 @@ function parseFindingBlock(body, id, title, start, end) {
 
 	// Cross-file evidence (optional): `### Cross-File Evidence` block.
 	// Each file gets a `- **File**: path` + fenced snippet.
-	const crossFileSection = extractSection(body, 'Cross-File Evidence') ?? ''
+	const crossFileSection = extractSection(cleanBody, 'Cross-File Evidence') ?? ''
 	const crossFileEvidence = []
 	const crossFileRx = /-\s*\*\*File\*\*:\s*`?([^`\n]+?)`?\s*\n+```[^\n]*\n([\s\S]*?)```/g
 	for (const m of crossFileSection.matchAll(crossFileRx)) {
@@ -287,7 +311,14 @@ function parseFindingBlock(body, id, title, start, end) {
 		description,
 		suggestedFix,
 		crossFileEvidence,
-		hasValidationStatus: /\*\*Validation Status\*\*/i.test(body),
+		// FRAMEWORK-BUG-034: detection broadened to recognize BOTH the new
+		// `### Validation Metadata` section (the post-fix writer shape) AND
+		// the legacy `- **Validation Status**:` field-form (back-compat for
+		// any validated.md on disk written before the fix). The flag name
+		// stays `hasValidationStatus` for callers; see spec.md ID-01 for the
+		// "renamed conceptually" rationale.
+		hasValidationStatus:
+			/###\s*Validation Metadata/i.test(body) || /\*\*Validation Status\*\*/i.test(body),
 	}
 }
 
@@ -537,51 +568,45 @@ export function checkFinding(finding, worktreeRoot, opts = {}) {
 }
 
 /**
- * Rewrite a findings markdown in place, stamping each finding with
- * `- **Validation Status**: …` + a `### Validation Note` block.
+ * Rewrite a findings markdown in place, stamping each finding with a
+ * trailing `### Validation Metadata` section carrying Status + Note.
+ *
+ * FRAMEWORK-BUG-034 (2026-05-19, PR #208): the previous writer emitted
+ * `- **Validation Status**:` as a field-form line. The fieldRx in
+ * `parseFindingBlock` (`/^-\s*\*\*([^*]+)\*\*:\s*(.+)$/gm`) lets `\s*`
+ * consume the newline after the empty-value `- **Evidence**:` field,
+ * so on a re-read the inserted Status line is captured as
+ * `fields.evidence` and the literal-substring step dismisses 28/32
+ * findings citing the writer's own stamp as the missing source line.
+ *
+ * Fix shape (per spec.md ID-01): WRITER always emits ONLY the new
+ * `### Validation Metadata` heading shape — the `###` shape can't fall
+ * into the field-cluster regex, so the self-reference loop can't form.
+ * READER side (`parseFindingBlock`) supports BOTH the new section AND
+ * the legacy field-form so any older validated.md on disk still
+ * round-trips. See spec.md ID-01 + ID-02 for the dual-shape rationale.
  */
 function stampFindings(markdown, decisions) {
 	// Work from the end so earlier edits don't shift later offsets.
 	let out = markdown
 	for (let i = decisions.length - 1; i >= 0; i--) {
 		const { finding, decision } = decisions[i]
-		// If the finding already has a Validation Status line, replace
-		// the value; otherwise inject before the first `### Description`
-		// (or at end of body if no such heading).
-		const block = out.slice(finding.start, finding.end)
-		let newBlock
-		if (finding.hasValidationStatus) {
-			newBlock = block.replace(
-				/-\s*\*\*Validation Status\*\*:\s*[^\n]*/i,
-				`- **Validation Status**: ${decision.status}`,
-			)
-			// Replace the note block too, if any.
-			if (decision.note) {
-				if (/###\s*Validation Note/i.test(newBlock)) {
-					newBlock = newBlock.replace(
-						/###\s*Validation Note\s*\n[\s\S]*?(?=\n###|$)/i,
-						`### Validation Note\n${decision.note}\n`,
-					)
-				} else {
-					newBlock = `${newBlock.replace(/\s*$/, '')}\n\n### Validation Note\n${decision.note}\n`
-				}
-			}
-		} else {
-			// Insert "- **Validation Status**: ..." right after the first
-			// `- **...**:` field block.
-			const lastFieldRx = /((?:^-\s*\*\*[^*]+\*\*:.*(?:\n|$))+)/m
-			const match = lastFieldRx.exec(block)
-			const insertion = `- **Validation Status**: ${decision.status}\n`
-			if (match) {
-				const insertAt = match.index + match[0].length
-				newBlock = block.slice(0, insertAt) + insertion + block.slice(insertAt)
-			} else {
-				newBlock = `${block.replace(/\s*$/, '')}\n${insertion}`
-			}
-			if (decision.note) {
-				newBlock = `${newBlock.replace(/\s*$/, '')}\n\n### Validation Note\n${decision.note}\n`
-			}
-		}
+		let block = out.slice(finding.start, finding.end)
+
+		// Strip any legacy field-form Validation Status line. Multiple lines
+		// possible if a previous buggy re-run left several stamps; replaceAll-
+		// style global match keeps this idempotent.
+		block = block.replace(/^-\s*\*\*Validation Status\*\*:[^\n]*\n?/gim, '')
+		// Strip any legacy `### Validation Note` block.
+		block = block.replace(/\n?###\s*Validation Note\s*\n[\s\S]*?(?=\n###|$)/i, '')
+		// Strip any prior `### Validation Metadata` section so we can
+		// re-emit fresh values (idempotency across re-runs, spec ID-02).
+		block = block.replace(/\n?###\s*Validation Metadata\s*\n[\s\S]*?(?=\n###|$)/i, '')
+
+		const lines = [`### Validation Metadata`, `- **Status**: ${decision.status}`]
+		if (decision.note) lines.push(`- **Note**: ${decision.note}`)
+		const section = `${lines.join('\n')}\n`
+		const newBlock = `${block.replace(/\s*$/, '')}\n\n${section}`
 		out = out.slice(0, finding.start) + newBlock + out.slice(finding.end)
 	}
 	return out

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)),