@aperant/framework 0.7.3 → 0.8.0

package/skills/apt-run/SKILL.md

@@ -159,6 +159,10 @@ Execute the apt:execute workflow inline:
    d. Commit atomically
    e. Update subtask status to "completed"
 3. Write build-progress.json
+4. Flip lifecycle to `verifying` so Stage 3 finds the task in the correct from-state (idempotent; quick tasks no-op):
+   ```bash
+   node packages/framework/bin/apt-tools.mjs task update . --id {task-id} --lifecycle-phase verifying
+   ```
 
 **Checkpoint state:** `build-progress.json` is written after every subtask. That file is the durable resume point — do NOT self-estimate context and do NOT voluntarily exit. Keep executing until the plan is complete or a risk gate stops you. If the harness auto-compacts mid-pipeline, re-read `implementation_plan.json` + `build-progress.json` and continue from the next pending subtask. The `--continue` flag exists for human-initiated resumes (`/apt:pause` + new session), not for agent-initiated bailouts.
 
@@ -189,6 +193,10 @@ Execute the apt:verify workflow inline:
 6. Score on 4 dimensions (completeness, correctness, quality, coverage)
 7. Fix all issues found — every severity, not just critical (up to 4 iterations: first 2 discovery, last 2 verification-only)
 8. Write qa_signoff.json
+9. If `status` is `approved` or `approved-with-notes`, flip lifecycle to `reviewing` so Stage 4 (or `/apt:ship` when review is skipped) finds the task in the correct from-state. Skip this step entirely on `rejected`:
+   ```bash
+   node packages/framework/bin/apt-tools.mjs task update . --id {task-id} --lifecycle-phase reviewing
+   ```
 
 **Output:** qa_signoff.json with status
 
@@ -224,6 +232,8 @@ Execute the apt:review workflow inline (see `apt-review/SKILL.md`):
 4. Update task documentation — review.json, qa_signoff.json (re-score if fixes changed quality), build-progress.json
 5. Write review.json with final findings and assessment. The `docs_policy` at `.aperant/config.json.docs_policy` controls per-surface behavior; defaults in `packages/framework/templates/docs-policy-defaults.json`.
 
+`lifecycle_phase` stays at `reviewing` after this stage — /apt:ship handles the next transition (`reviewing → shipped-pending-merge`).
+
 **Output:** review.json (written to task directory)
 
 **This is the task review, not the PR review.** It runs inline without sub-agents. For heavy multi-agent PR review, use `/apt:pr-review` separately.
@@ -269,11 +279,16 @@ node packages/framework/bin/apt-tools.mjs commit "pipeline: complete {task}" --f
 
 ## 8. Lifecycle transitions
 
-Lifecycle phase transitions are handled by the child skills themselves:
-`apt:execute` calls `task update --lifecycle-phase executing` (which flips a
-phase-linked task from `planned` → `in-progress`), and `apt:ship` calls
-`task close --verdict approved` (which flips it to `completed`). The
-pipeline wrapper does not need to record or drain anything.
+Lifecycle phase transitions are handled by the child skills themselves.
+`apt:execute` flips `planned` → `in-progress` at start (lifecycle = `executing`)
+and at success-end (lifecycle = `verifying`). `apt:verify` flips lifecycle =
+`reviewing` on the approved verdict (skipped on `rejected`). `apt:review`
+leaves lifecycle at `reviewing` — the from-state `/apt:ship` expects for its
+atomic `reviewing → shipped-pending-merge` flip. `/apt:ship` then flips
+`reviewing → shipped-pending-merge`, and `/apt:close-task` later flips
+`shipped-pending-merge → completed` after the PR merges. The pipeline wrapper
+does not need to record or drain anything beyond ensuring each child-skill
+stage runs to its success-end.
 
 </process>
 </output>

package/skills/apt-spar/SKILL.md

@@ -90,7 +90,7 @@ Parse `$ARGUMENTS`. Extract:
   `[apt:spar] --rounds clamped to 3 (hard cap, see SPAR-05)`
   and proceed with N=3. If N<1, clamp to 1 and print:
   `[apt:spar] --rounds clamped to 1 (minimum)`
-- `--timeout-ms N` — per-partner Bash timeout in milliseconds, default 90000 (90s). Capped at 600000 (10m, the Bash tool's own ceiling).
+- `--timeout-ms N` — per-partner Bash timeout in milliseconds, default 300000 (5 min). Capped at 600000 (10 min, the Bash tool's own ceiling).
 - `[topic]` — the remaining text after flags. If empty, frame the round from the **last N conversation turns** as the context.
 
 Also read (best-effort, skip silently if missing):
@@ -135,7 +135,7 @@ Do NOT proceed; self-sparring is sycophancy by construction (the host cannot obj
 2. **Rung 2 — Plugin shim** (`${CLAUDE_PLUGIN_ROOT}/scripts/<partner>-companion.mjs`). Codex only (claude / gemini have no plugin shim).
 3. **Rung 3 — Raw CLI on `$PATH`** (`codex exec`, `claude -p`, `gemini -m`).
 
-Walk the ladder in order; pick the first rung with `detected: true` (or `"runtime-host-only"` for MCP). **MCP rung has a hard timeout** — default 60000ms, configurable via `apt-spar.mcp_timeout_ms` in `.aperant/config.json`. Empirical: the Codex MCP `claude_code` tool has been observed to hang past 120s. On MCP timeout, **automatically fall through to rung 2 or rung 3** — do NOT fail the whole spar. Treat MCP timeout as "rung unavailable for this invocation."
+Walk the ladder in order; pick the first rung with `detected: true` (or `"runtime-host-only"` for MCP). **MCP rung has a hard timeout** — default 900000ms (15 min), configurable via `apt-spar.mcp_timeout_ms` in `.aperant/config.json`. The MCP rung is a structured tool call, NOT a Bash invocation, so the Bash tool's 600000ms ceiling does NOT apply — the MCP rung can carry heavy-research partner runs (e.g. Claude Code partner doing multiple minutes of Read/Grep/Bash) where the Bash rungs would hit the host ceiling. On MCP timeout, **automatically fall through to rung 2 or rung 3** — do NOT fail the whole spar. Treat MCP timeout as "rung unavailable for this invocation."
 
 If all three rungs are unavailable (every rung `detected: false`, or MCP `runtime-host-only` timed out AND rungs 2+3 are `detected: false`), print:
 
@@ -163,13 +163,14 @@ You are the sparring partner in an apt:spar round. Your job:
 - Identify the strongest objection.
 - Cite specific evidence where possible (file:line, test output, doc reference).
 - Be specific, not generic — "this might fail" is not a finding; "this fails when X because Y" is.
+- After your main objection, provide NEXT_WEAKEST_POINT: one additional independent objection that would still matter if your first point is resolved. This populates the next round's frame.
 ```
 
 The frame is one shot per round — no multi-turn conversation with the partner inside a single round.
 
 ## 5. Invoke Partner (with timeout)
 
-**Wrap every partner Bash call with an explicit timeout** (default 90000ms, override via `--timeout-ms`). The empirical reason: the Codex MCP `claude_code` tool has been observed to hang past 120s while the `claude -p` CLI returns in seconds. A hung partner CLI must NOT stall the spar loop.
+**Wrap every partner Bash call with an explicit timeout** (default 300000ms (5 min), override via `--timeout-ms`). The empirical reason: heavy-research partner CLIs (especially Claude Code in `--with claude` mode) routinely spend multiple minutes doing genuine Read/Grep/Bash investigation per round, and a hung partner CLI must NOT stall the spar loop indefinitely.
 
 The table below shows the canonical command shape per (partner × rung); the actual invocation for shell-based rungs (plugin shim, raw CLI) MUST use the heredoc pattern in the next subsection — never raw double-quoted interpolation. The MCP rung is a structured tool call — no shell quoting concern applies.
 
@@ -182,19 +183,19 @@ The table below shows the canonical command shape per (partner × rung); the act
 
 | Partner | Rung | Command | Notes |
 |---|---|---|---|
-| codex | mcp | tool call: `mcp__codex-mcp__codex({prompt})` | Preferred. 60s timeout (configurable `apt-spar.mcp_timeout_ms`); on timeout fall through to plugin then CLI. |
+| codex | mcp | tool call: `mcp__codex-mcp__codex({prompt})` | Preferred. 900000ms (15 min) timeout (configurable `apt-spar.mcp_timeout_ms`); on timeout fall through to plugin then CLI. |
 | codex | plugin | `node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" task "$(cat <<'APT_SPAR_PROMPT_EOF' ... APT_SPAR_PROMPT_EOF\n)"` | **NO `--write`. NO `--effort` override.** Per SPAR-04 — spar is conversation, not patching. |
 | codex | cli | `codex exec "$(cat <<'APT_SPAR_PROMPT_EOF' ... APT_SPAR_PROMPT_EOF\n)"` | Precedent: `apt-pr-review/SKILL.md:1084`. Verify with `codex --help`. |
-| claude | mcp | tool call: `mcp__claude-code-mcp__claude_code({prompt})` | Preferred. Same 60s timeout + fallthrough rule. |
+| claude | mcp | tool call: `mcp__claude-code-mcp__claude_code({prompt})` | Preferred. Same 900000ms (15 min) timeout + fallthrough rule. |
 | claude | plugin | n/a | No plugin shim exists for Claude. Skip this rung. |
 | claude | cli | `claude -p "$(cat <<'APT_SPAR_PROMPT_EOF' ... APT_SPAR_PROMPT_EOF\n)" --output-format text` | Symmetric. Claude has no `--write` equivalent — asymmetric flags are a smell. |
-| gemini | mcp | tool call: `mcp__gemini-mcp__*({prompt})` | Preferred. Same 60s timeout + fallthrough rule. Any `mcp__gemini-mcp__*` tool satisfies the rung. |
+| gemini | mcp | tool call: `mcp__gemini-mcp__*({prompt})` | Preferred. Same 900000ms (15 min) timeout + fallthrough rule. Any `mcp__gemini-mcp__*` tool satisfies the rung. |
 | gemini | plugin | n/a | No plugin shim exists for Gemini. Skip this rung. |
 | gemini | cli | `gemini -m <model-from-router.llm.providers.gemini-cli> "$(cat <<'APT_SPAR_PROMPT_EOF' ... APT_SPAR_PROMPT_EOF\n)"` | Read the exact model name from `.aperant/config.json` at runtime — do not hardcode. |
 
-Set the Bash tool's `timeout` parameter to `--timeout-ms` (default 90000).
+Set the Bash tool's `timeout` parameter to `--timeout-ms` (default 300000).
 
-**Timeout calibration.** The 90s default is a conservative ceiling sized for worst-case Codex hangs (empirical: the `claude_code` MCP tool has been observed timing out at 120s while `claude -p` returns in seconds). A single unified ceiling simplifies the loop-control logic and avoids per-partner special-casing in v1. For tighter budgets, pass `--timeout-ms` explicitly; future versions may introduce per-partner defaults.
+**Timeout calibration.** The 5-min Bash-rung default and 15-min MCP-rung default are sized for heavy-research partner runs — modern partner CLIs commonly spend multiple minutes doing real Read/Grep/Bash investigation before producing a round response. The two defaults are intentionally asymmetric: the Bash rungs (plugin shim, raw CLI) are capped at the Claude Code Bash tool's 600000ms (10 min) host ceiling, while the MCP rung — a structured tool call rather than a Bash invocation — has no host ceiling and can carry the worst-case 15-min Claude Code partner. For tighter budgets (e.g. CI), pass `--timeout-ms` explicitly. The MCP-rung override is downward-only: if you observe consistent partner-CLI wedges (auth handshakes, hosted-API stalls, CI lanes wanting fast failure), set `apt-spar.mcp_timeout_ms` BELOW the 15-min default in `.aperant/config.json` (e.g. `120000` for a 2-min fast-fail budget) — raising it above 15 min is unnecessary because the default already covers the documented worst case. Future versions may introduce per-partner defaults.
 
 **Prompt-quoting safety.** The prompt is user-controlled (it comes from `[topic]` and/or conversation context) and may legitimately contain double quotes, dollar signs, backticks, or `$(...)` substitution that bash would otherwise expand or break on. NEVER interpolate `<prompt>` directly inside a double-quoted shell argument. Instead, pipe via a here-document so the shell treats the body as opaque text:
 
@@ -284,7 +285,9 @@ After each round, print a verdict block (one of these four, exact format):
 
 ## 8. Loop Control (max 3 rounds)
 
-- If `verdict=cede` → **converge, terminate** unilaterally. The host has accepted the partner's prior claim with cited evidence; no second partner turn is needed.
+- If `verdict=cede` AND `--rounds 1` was explicit → terminate this round.
+- If `verdict=cede` AND `--rounds >= 2` (default) → emit `next-round` regardless: convergence requires TWO consecutive rounds with the same disposition AND no materially new evidence. Round 1 alone cannot terminate as converged.
+- The host's `next-round` payload for Round 2 MUST include: (a) the cited evidence that confirmed the partner's Round 1 point, (b) a request to challenge the host's cited evidence with the partner's NEXT_WEAKEST_POINT.
 - If `verdict=hold` → only triggers `next-round` (partner gets the new evidence). There is no terminal `hold` convergence in a single round. If the round cap is reached with hold still active, the held position stands and the loop exits via the round-cap path below.
 - If `verdict=next-round` → invoke the partner again with the new evidence the host just cited, go to Step 4.
 - If the round counter hits **3 rounds** (or whatever `--rounds N` clamped to) → **terminate** with:

package/skills/apt-verify/SKILL.md

@@ -302,6 +302,17 @@ The `status` field is derived from the minimum dimension score:
 node packages/framework/bin/apt-tools.mjs commit "qa: verification {status}" --files qa_signoff.json
 ```
 
+### Mark lifecycle phase as `reviewing` (approved path only)
+
+If `status` is `approved` or `approved-with-notes`, flip the task's lifecycle
+phase so the next stage (`/apt:review`, or `/apt:ship` if review is skipped)
+finds the task in the correct from-state. Skip this transition entirely on
+`rejected` — the task stays in `verifying` until the user re-runs after fixes.
+
+```bash
+node packages/framework/bin/apt-tools.mjs task update . --id {task-id} --lifecycle-phase reviewing
+```
+
 ## 8. Report
 
 Output:

package/skills/apt-watch-ci/SKILL.md

@@ -69,7 +69,7 @@ Watcher already running for PR {N} (held by sessionId={x}, pid={y}); exiting.
 
 For the `--tick` mode, execute exactly the following sequence — once — inside this single skill invocation:
 
-1. **Poll.** Call `gh pr checks <N> --json name,bucket,state,conclusion,detailsUrl` and `gh pr view <N> --json state,reviewDecision`. Combine both JSON outputs into a single file shaped `{checks: <pr-checks-json>, prMetadata: <pr-view-json>}` (for example with `jq -s '{checks: .[0], prMetadata: .[1]}'`) and save it as `{captured.json}` (any path under the worktree is fine). On any `gh` failure, omit the file and let the cmd's `tick` route to `infra-backoff` (it surfaces the same action when no payload is available).
+1. **Poll.** Call `gh pr checks <N> --json name,bucket,state,link,workflow,completedAt` and `gh pr view <N> --json state,reviewDecision`. Combine both JSON outputs into a single file shaped `{checks: <pr-checks-json>, prMetadata: <pr-view-json>}` (for example with `jq -s '{checks: .[0], prMetadata: .[1]}'`) and save it as `{captured.json}` (any path under the worktree is fine). On any `gh` failure, omit the file and let the cmd's `tick` route to `infra-backoff` (it surfaces the same action when no payload is available). <!-- FRAMEWORK-BUG-016 (spec.md §D3): gh 2.65+'s `pr checks --json` schema dropped two legacy fields that the watcher previously requested; per-check status now lives in `state` (uppercase: SUCCESS / FAILURE / SKIPPED / IN_PROGRESS / …) and the failed-run URL lives in `link`. Do NOT re-introduce the legacy field names — gh exits non-zero ("Unknown JSON field") and the watcher falls into infra-backoff forever. -->
 2. **Classify + state update.** Call `apt-tools ci-watch tick {worktree} --pr {N} --payload-file {captured.json}`. The cmd reads `{captured.json}` from disk and runs the classifier — it does NOT shell out to `gh` itself (that boundary stays with the orchestrator skill; see commands/ci-watch.mjs:15). The cmd internally:
    - acquires the per-PR lock (BUSY → exit 2 → step §2);
    - reads the per-PR state file;
@@ -111,7 +111,7 @@ In all terminal cases:
 
 When `action === 'fix'` (or `diverged-rebased`/`diverged-bailed`):
 
-1. **Fetch the failed-check log.** From the gh payload, find the failed check's `detailsUrl` and call `gh run view {runId} --log` to capture the log into a temp file.
+1. **Fetch the failed-check log.** From the gh payload, find the failed check's `link` field (see FRAMEWORK-BUG-016 / §D3 for the gh 2.65+ field migration) and call `gh run view {runId} --log` to capture the log into a temp file.
 2. **Shell out to the host CLI** to fix it. The watcher does NOT inline a custom fix prompt; it hands the worktree + failed-log to the same CLI binary that's running this skill (detected by `apt-tools host-detect`). Pseudocode:
 
    ```bash

package/src/cli/ci-watch/stop-matrix.mjs

@@ -5,11 +5,17 @@
  *   { action, counts_toward_budget, reason }
  *
  * No I/O, no fs, no gh CLI shell-outs — caller pre-fetches `checks` (the
- * payload from `gh pr checks --json name,bucket,state,conclusion,detailsUrl`)
+ * payload from `gh pr checks --json name,bucket,state,link,workflow,completedAt`)
  * and `prMetadata` (`gh pr view --json state,reviewDecision`) and passes them
  * in. The orchestrator in commands/ci-watch.mjs handles the side effects
  * implied by the action.
  *
+ * Primary per-check signal is `state` (uppercase per gh-CLI: SUCCESS,
+ * FAILURE, CANCELLED, TIMED_OUT, SKIPPED, IN_PROGRESS, QUEUED, PENDING,
+ * NEUTRAL). The legacy lowercase per-check field that gh dropped circa
+ * 2.65 is kept as a soft fallback for in-memory test fixtures only —
+ * production gh payloads no longer expose it (FRAMEWORK-BUG-016).
+ *
  * Predicate order matters — short-circuits go first (merged/closed/green/cap
  * fire before any per-check inspection). See spec.md §9 table for the full
  * ordering.
@@ -31,8 +37,13 @@ const INFRA_FAILURE_CLASSES = new Set(['runner-oom', 'runner-cancelled', 'gh-5xx
 /**
  * @typedef {Object} CheckRow
  * @property {string} [name]
- * @property {string} [conclusion] e.g. 'success' | 'failure' | 'cancelled' | 'timed_out' | 'neutral'
- * @property {string} [state]
+ * @property {string} [state] Primary per-check status (gh-CLI uppercase enum):
+ *   'SUCCESS' | 'FAILURE' | 'CANCELLED' | 'TIMED_OUT' | 'SKIPPED' |
+ *   'IN_PROGRESS' | 'QUEUED' | 'PENDING' | 'NEUTRAL'.
+ * @property {string} [conclusion] Legacy lowercase per-check field
+ *   (deprecated — gh dropped it from `pr checks --json` schema circa 2.65).
+ *   Retained only as a soft fallback for in-memory test fixtures
+ *   (FRAMEWORK-BUG-016).
  * @property {string} [bucket]
  * @property {string} [failure_class] — optional pre-classified hint (test-only seam)
  * @property {string} [log_fingerprint] — optional digest for identical-log detection
@@ -65,7 +76,16 @@ export function classify({ checks, state, prMetadata }) {
 	}
 
 	const failed = rows.filter((c) => isFailing(c))
-	const allGreen = rows.length > 0 && rows.every((c) => c.conclusion === 'success')
+	// FRAMEWORK-BUG-016: `state` is gh-CLI's primary per-check field post-2.65.
+	// SKIPPED rows (workflow `if:` guards that didn't trip) are
+	// success-equivalent — they intentionally did not run and that is OK.
+	// Soft fallback to the legacy lowercase field keeps the in-memory test
+	// fixtures green (production gh payloads never hit it).
+	const isGreenRow = (c) =>
+		c.state === 'SUCCESS' ||
+		c.state === 'SKIPPED' ||
+		(c.state == null && c.conclusion === 'success')
+	const allGreen = rows.length > 0 && rows.every(isGreenRow)
 
 	// 3. All checks green.
 	if (allGreen) {
@@ -193,6 +213,26 @@ export function classify({ checks, state, prMetadata }) {
 }
 
 export function isFailing(check) {
+	// FRAMEWORK-BUG-016 / BUG-025: prefer the uppercase `state` field that gh
+	// 2.65+ exposes. SKIPPED / NEUTRAL / IN_PROGRESS / QUEUED / PENDING /
+	// SUCCESS are explicitly NOT red — SKIPPED in particular must never
+	// burn a fix attempt (workflow `if:` guards routinely skip jobs on PRs
+	// that don't trip them). The legacy lowercase field is a soft fallback
+	// for in-memory test fixtures only.
+	const s = check.state
+	if (
+		s === 'SUCCESS' ||
+		s === 'SKIPPED' ||
+		s === 'NEUTRAL' ||
+		s === 'IN_PROGRESS' ||
+		s === 'QUEUED' ||
+		s === 'PENDING'
+	) {
+		return false
+	}
+	if (s === 'FAILURE' || s === 'CANCELLED' || s === 'TIMED_OUT') {
+		return true
+	}
 	const c = check.conclusion
 	return c === 'failure' || c === 'cancelled' || c === 'timed_out' || c === 'action_required'
 }

package/src/cli/commands/fan-out.mjs

@@ -0,0 +1,129 @@
+/**
+ * commands/fan-out.mjs — FRAMEWORK-BUG-033 capability gap (ID-04 / ID-05).
+ *
+ * Single resolver helper for the `/apt:fan-out` SKILL body. Three input
+ * forms accepted (`--tasks`, `--phases`, `--unblocked`); all resolve to
+ * the canonical `{task_ids, source, batch_id}` shape. The actual
+ * orchestration loop (worktree create, worker spawn, polling) lives in
+ * the SKILL body — this CLI just materializes the batch.
+ *
+ * Subcommands: `resolve`.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { parseFlags } from '../util/args.mjs'
+import { err, ok } from '../util/result.mjs'
+
+const ID_PATTERN = /^[a-z0-9_-]+$/i
+
+function generateBatchId() {
+	const d = new Date()
+	const yyyy = d.getUTCFullYear()
+	const mm = String(d.getUTCMonth() + 1).padStart(2, '0')
+	const dd = String(d.getUTCDate()).padStart(2, '0')
+	const hex = Math.random().toString(16).slice(2, 8)
+	return `fanout-${yyyy}${mm}${dd}-${hex}`
+}
+
+function parseIdList(raw) {
+	if (typeof raw !== 'string') return []
+	return raw
+		.split(',')
+		.map((s) => s.trim())
+		.filter(Boolean)
+}
+
+function readState(targetDir) {
+	const statePath = join(targetDir, '.aperant', 'state.json')
+	if (!existsSync(statePath)) return null
+	try {
+		return JSON.parse(readFileSync(statePath, 'utf-8'))
+	} catch {
+		return null
+	}
+}
+
+function resolveFromPhases(state, phases) {
+	const wanted = new Set(phases)
+	const ids = []
+	for (const [id, task] of Object.entries(state?.active_tasks || {})) {
+		if (!task) continue
+		const key = `${task.milestone_id ?? ''}/${task.phase_id ?? ''}`
+		if (wanted.has(key) && task.lifecycle_phase !== 'closed') {
+			ids.push(id)
+		}
+	}
+	return ids
+}
+
+function resolveUnblocked(state) {
+	const ids = []
+	for (const [id, task] of Object.entries(state?.active_tasks || {})) {
+		if (task?.lifecycle_phase === 'ready-for-agent') ids.push(id)
+	}
+	return ids
+}
+
+export function cmdFanOut(subcommand, projectDir, extraArgs) {
+	if (!subcommand) {
+		return err(
+			'Usage: apt-tools fan-out <resolve> <project-dir> [--tasks <ids> | --phases <m/p,m/p> | --unblocked]',
+		)
+	}
+	switch (subcommand) {
+		case 'resolve': {
+			if (!projectDir) {
+				return err(
+					'Usage: apt-tools fan-out resolve <project-dir> [--tasks <ids> | --phases <m/p,m/p> | --unblocked]',
+				)
+			}
+			const targetDir = resolve(projectDir)
+			const flags = parseFlags(extraArgs)
+
+			const hasTasks = flags.has('tasks')
+			const hasPhases = flags.has('phases')
+			const hasUnblocked = flags.has('unblocked')
+
+			const inputForms = [hasTasks, hasPhases, hasUnblocked].filter(Boolean).length
+			if (inputForms === 0) {
+				return err('One of --tasks, --phases, or --unblocked is required')
+			}
+			if (inputForms > 1) {
+				return err('Only one of --tasks, --phases, or --unblocked may be passed at a time')
+			}
+
+			let taskIds = []
+			let source = ''
+			if (hasTasks) {
+				taskIds = parseIdList(flags.get('tasks'))
+				source = 'tasks'
+				for (const id of taskIds) {
+					if (!ID_PATTERN.test(id)) {
+						return err(`Invalid task id in --tasks: "${id}" (must match /^[a-z0-9_-]+$/i)`)
+					}
+				}
+			} else if (hasPhases) {
+				const state = readState(targetDir)
+				if (!state) return err('No state.json found — cannot resolve --phases')
+				taskIds = resolveFromPhases(state, parseIdList(flags.get('phases')))
+				source = 'phases'
+			} else {
+				const state = readState(targetDir)
+				if (!state) return err('No state.json found — cannot resolve --unblocked')
+				taskIds = resolveUnblocked(state)
+				source = 'unblocked'
+			}
+
+			return ok({
+				status: 'ok',
+				command: 'fan-out-resolve',
+				source,
+				task_ids: taskIds,
+				batch_id: generateBatchId(),
+			})
+		}
+		default:
+			return err(`Unknown fan-out subcommand: ${subcommand}. Available: resolve`)
+	}
+}

package/src/cli/commands/modes.mjs

@@ -54,7 +54,7 @@ const FRONTMATTER_RE = /^---\s*([\s\S]*?)\s*---/
  *
  * @type {Record<string, string[]>}
  */
-const SKILL_CONFIG_KEYS = {
+export const SKILL_CONFIG_KEYS = {
 	'apt:execute': ['coding.tdd_default', 'tdd.iron_law'],
 	'apt:triage': [
 		'task_tracking.backend',
@@ -69,6 +69,9 @@ const SKILL_CONFIG_KEYS = {
 	'apt:ship': ['pipeline.auto_branch', 'pipeline.branch_prefix'],
 	'apt:setup': ['*'], // setup edits config — wildcard surface
 	'apt:run': ['parallelization.enabled', 'parallelization.max_agents'],
+	// FRAMEWORK-BUG-033 capability gap (AC10) — fan-out concurrency cap.
+	// Consumed by the /apt:fan-out SKILL body via cli/config/parallelization.mjs.
+	'apt:fan-out': ['parallelization.max_tasks', 'parallelization.max_agents'],
 }
 
 /**

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

@@ -147,13 +147,24 @@ export function parseFixesAppliedMarkdown(md) {
 	const fixesSection = extractTopLevelSection(md, 'Fixes Applied')
 	const selfReviewerSection = extractTopLevelSection(md, 'Fixes Applied by Self-Reviewer')
 	const skippedSection = extractTopLevelSection(md, 'Skipped')
-	const fixes = [
-		...parseFixEntries(fixesSection),
-		...parseSelfReviewerFixEntries(selfReviewerSection),
-	]
+	const legacyFixerEntries = parseFixEntries(fixesSection)
+	const selfReviewerEntries = parseSelfReviewerFixEntries(selfReviewerSection)
+	// FRAMEWORK-BUG-035: additive `## Fix N` parser path. Scans the whole
+	// document — NOT a `## Fixes Applied` body — so it catches fixer reports
+	// shaped as numbered top-level blocks. Union, not substitution, per spec
+	// ID-03 so legacy `### {ID}` reports keep parsing unchanged.
+	const fixNEntries = parseFixNEntries(md)
+	const fixes = [...legacyFixerEntries, ...selfReviewerEntries, ...fixNEntries]
 	const skipped = parseSkippedEntries(skippedSection)
-	// Detect which heading was present; fixer takes precedence when both appear.
-	const schema = fixesSection ? 'fixer' : 'self-reviewer'
+	// Schema discriminator: when the ONLY entries came from the `## Fix N`
+	// parser path, label it `'fix-n'` so downstream code / debugging can
+	// tell which shape was on disk. Fall back to existing fixer / self-
+	// reviewer labels when those sections were present.
+	let schema
+	if (fixesSection) schema = 'fixer'
+	else if (selfReviewerSection) schema = 'self-reviewer'
+	else if (fixNEntries.length > 0) schema = 'fix-n'
+	else schema = 'fixer'
 	return { exists: true, fixes, skipped, schema }
 }
 
@@ -237,6 +248,71 @@ function parseFixEntries(section) {
 	return entries
 }
 
+/**
+ * FRAMEWORK-BUG-035 — parse `## Fix N` top-level blocks into entries shaped
+ * like `parseFixEntries` output. The bug narrative documents `## Fix N`
+ * as the canonical shape going forward for fixes-applied-fixer-N.md, but
+ * the legacy `### {ID} — title` parser silently dropped every entry on
+ * those reports, surfacing `<none parsed>` and false-positive flipping
+ * the gate to `hallucinated`.
+ *
+ * This parser scans the WHOLE document (not a `## Fixes Applied` body)
+ * because the new shape uses `## Fix N` directly as top-level headers.
+ * Finding-ID extraction priority chain (per spec ID-04):
+ *   1. `- **Finding ID**:` field line
+ *   2. `- **Fix**:`        field line
+ *   3. `- **ID**:`         field line
+ *   4. synthetic `fix-N`   fallback (matches `parseSelfReviewerFixEntries`'s
+ *      `self-reviewer-fix-N` convention; the diff-intersect step in
+ *      `decideVerdict` is the real check, not the id)
+ *
+ * Returns the same `{id, title, file, files, verification}` shape as
+ * `parseFixEntries` so downstream consumers see a uniform array.
+ */
+function parseFixNEntries(markdown) {
+	if (!markdown) return []
+	const entries = []
+	// `^## Fix N$` — top-level heading with the literal word "Fix" + a
+	// number. No trailing description in the header (the canonical shape
+	// per the BUG-034 narrative puts the description inside the body).
+	const headerRx = /^##\s+Fix\s+(\d+)\s*$/gm
+	const matches = [...markdown.matchAll(headerRx)]
+	for (let i = 0; i < matches.length; i++) {
+		const m = matches[i]
+		const start = m.index + m[0].length
+		// Terminate at the next top-level `## ` heading OR EOF. Mirrors
+		// `extractTopLevelSection`'s body slicing.
+		const rest = markdown.slice(start)
+		const nextTopRx = /\n##\s+/m
+		const nxt = nextTopRx.exec(rest)
+		const body = (nxt ? rest.slice(0, nxt.index) : rest).trim()
+		const findingId = extractFindingIdField(body) ?? `fix-${m[1]}`
+		const files = extractFileFields(body)
+		entries.push({
+			id: findingId,
+			title: null,
+			file: files[0] ?? null,
+			files,
+			verification: extractVerificationField(body),
+		})
+	}
+	return entries
+}
+
+/**
+ * Extract the finding ID from a `## Fix N` block body via the priority
+ * chain documented in `parseFixNEntries`. Returns `null` if no field
+ * matched — caller falls back to the synthetic `fix-N` id.
+ */
+function extractFindingIdField(body) {
+	for (const key of ['Finding ID', 'Fix', 'ID']) {
+		const rx = new RegExp(`-\\s*\\*\\*${key}\\*\\*:\\s*([^\\n]+)`, 'i')
+		const m = rx.exec(body)
+		if (m) return m[1].trim()
+	}
+	return null
+}
+
 function parseSkippedEntries(section) {
 	if (!section) return []
 	const entries = []

package/src/cli/commands/roadmap.mjs

@@ -11,6 +11,7 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSy
 import { basename, join, resolve } from 'node:path'
 import { selfStageCommittableWrites } from '../artifacts/self-stage.mjs'
 import { getDefaultOwner, getGitIdentity } from '../git/identity.mjs'
+import { runConvexMirror } from '../roadmap/convex-mirror.mjs'
 import {
 	loadRoadmapForScope as ioLoadRoadmapForScope,
 	saveRoadmapForScope as ioSaveRoadmapForScope,
@@ -41,7 +42,7 @@ class RoadmapUsageError extends UsageError {
 	}
 }
 
-export function cmdRoadmap(subcommand, projectDir, extraArgs) {
+export async function cmdRoadmap(subcommand, projectDir, extraArgs) {
 	if (!subcommand)
 		return err(
 			'Usage: apt-tools roadmap <init|render|add-milestone|add-phase|set-phase-status|rollup|delete-phase|delete-milestone|validate-refs|sync> <project-dir>',
@@ -49,14 +50,14 @@ export function cmdRoadmap(subcommand, projectDir, extraArgs) {
 	if (!projectDir) return err('Usage: apt-tools roadmap ' + subcommand + ' <project-dir>')
 
 	try {
-		return cmdRoadmapImpl(subcommand, projectDir, extraArgs)
+		return await cmdRoadmapImpl(subcommand, projectDir, extraArgs)
 	} catch (e) {
 		if (e instanceof RoadmapUsageError) return err(e.message)
 		throw e
 	}
 }
 
-function cmdRoadmapImpl(subcommand, projectDir, extraArgs) {
+async function cmdRoadmapImpl(subcommand, projectDir, extraArgs) {
 	const targetDir = resolve(projectDir)
 	updateTeamMember(targetDir)
 	const roadmapRoot = join(targetDir, '.aperant', 'roadmap')
@@ -904,9 +905,52 @@ function cmdRoadmapImpl(subcommand, projectDir, extraArgs) {
 			})
 		}
 
+		case 'convex-mirror': {
+			// Slice 5 ST14 / AC10 / ID-06. 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.
+			const scope = flags.get('scope')
+			const phaseId = flags.get('phase')
+			const anchorId = flags.get('anchor-id')
+			const prosePath = flags.get('prose-path')
+			const mergedPrRaw = flags.get('merged-pr')
+			if (!scope || !phaseId || !anchorId || !prosePath) {
+				return err(
+					'Usage: apt-tools roadmap convex-mirror <project-dir> --scope <s> --phase <p> --anchor-id <a> --prose-path <file> [--merged-pr <n>]',
+				)
+			}
+			let proseBody = ''
+			try {
+				proseBody = readFileSync(prosePath, 'utf-8')
+			} catch (e) {
+				return err(`prose-path read failed: ${e.message}`)
+			}
+			const mergedPr = mergedPrRaw ? Number(mergedPrRaw) : undefined
+			let result
+			try {
+				result = await runConvexMirror(targetDir, {
+					scope,
+					phaseId,
+					anchorId,
+					proseBody,
+					mergedPr,
+				})
+			} catch (e) {
+				return err(e.message)
+			}
+			if (result.status === 'error') {
+				return err(result.message ?? 'convex-mirror error')
+			}
+			return ok({
+				status: result.status,
+				command: 'roadmap-convex-mirror',
+				message: result.message,
+			})
+		}
+
 		default:
 			return err(
-				`Unknown roadmap subcommand: ${subcommand}. Expected: init, render, add-milestone, add-phase, set-phase-status, delete-phase, delete-milestone, validate-refs, sync`,
+				`Unknown roadmap subcommand: ${subcommand}. Expected: init, render, add-milestone, add-phase, set-phase-status, delete-phase, delete-milestone, validate-refs, sync, convex-mirror`,
 			)
 	}
 }

package/src/cli/commands/task.mjs

@@ -264,6 +264,12 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 						roadmap_ref_url: roadmapRefUrl,
 						depends_on: dependsOn,
 						outputs,
+						// FRAMEWORK-BUG-033 defect 2 — durable task→agent ownership.
+						// Defaults to null at create time; fan-out workers (or the
+						// `task update --assigned-to <agent-id>` path) populate it
+						// when they claim the task. Persists across short-lived CLI
+						// invocations unlike team-status/{agentId}.json (pid-keyed).
+						assigned_to: flags.has('assigned-to') ? flags.get('assigned-to') : null,
 						lifecycle_phase: 'planning',
 						history: [],
 						created_at: new Date().toISOString(),
@@ -704,6 +710,7 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 						const result = applyLifecyclePhaseSideEffect(
 							targetDir,
 							{
+								id: task.id,
 								scope: task.scope || 'project',
 								milestone_id: task.milestone_id,
 								phase_id: task.phase_id,
@@ -933,6 +940,14 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 						}
 						prUrlForCiWatch = url
 					}
+					// FRAMEWORK-BUG-033 defect 2 — durable task→agent ownership.
+					// Mutable owner field; fan-out workers write
+					// `fanout-${batch}-${task}` on claim, conductor reads to
+					// resolve crash recovery (which worker owned T1 when the
+					// conductor died?).
+					if (flags.has('assigned-to')) {
+						task.assigned_to = flags.get('assigned-to')
+					}
 					if (flags.has('subtasks-total'))
 						task.progress.subtasks_total = parseInt(flags.get('subtasks-total'), 10)
 					if (flags.has('subtasks-completed'))