@aperant/framework 0.8.0 → 0.8.1

package/dist/cli/personas/sidecar.d.mts

@@ -209,7 +209,7 @@ export type PersonaEvidenceAnchor = {
     source: "codebase" | "project_md" | "app_wizard";
     file: string;
     line_range?: string | undefined;
-    confidence?: "high" | "low" | "medium" | undefined;
+    confidence?: "medium" | "high" | "low" | undefined;
 };
 export type Persona = {
     id?: string | undefined;

package/dist/cli/roadmap/lifecycle.d.mts

@@ -45,7 +45,7 @@ export function applyLifecyclePhaseSideEffect(targetDir: any, task: any, spec: a
     commit: string | null;
     rollup: {
         before: any;
-        after: "completed" | "in-progress" | "planned" | "blocked" | null;
+        after: "planned" | "completed" | "blocked" | "in-progress" | null;
         changed: boolean;
         milestone_id: any;
     };

package/dist/cli/roadmap/rollup.d.mts

@@ -16,7 +16,7 @@ export function rollupMilestoneStatus(milestone: object): "completed" | "in-prog
  */
 export function applyRollup(roadmap: any, milestoneId: any): {
     before: any;
-    after: "in-progress" | "completed" | "planned" | "blocked" | null;
+    after: "planned" | "completed" | "blocked" | "in-progress" | null;
     changed: boolean;
     milestone_id: any;
 };
@@ -31,7 +31,7 @@ export function applyRollup(roadmap: any, milestoneId: any): {
 export function writeRollup(projectDir: any, scope: any, milestoneId: any): {
     committed: boolean;
     before: any;
-    after: "in-progress" | "completed" | "planned" | "blocked" | null;
+    after: "planned" | "completed" | "blocked" | "in-progress" | null;
     changed: boolean;
     milestone_id: any;
 };

package/dist/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "aperant",
-  "version": "0.7.3",
+  "version": "0.8.1",
   "description": "AI coding framework — composable skills for planning, executing, verifying, and reviewing code with any LLM provider. Works as Claude Code commands, Codex tasks, or programmatically.",
   "author": {
     "name": "Mikalsen AI",
@@ -34,6 +34,7 @@
     "skills/apt-discuss",
     "skills/apt-docs",
     "skills/apt-execute",
+    "skills/apt-fan-out",
     "skills/apt-improve",
     "skills/apt-mockup",
     "skills/apt-pause",

package/dist/plugin/agents/apt-executor.md

@@ -46,6 +46,18 @@ node packages/framework/bin/apt-tools.mjs gate check . --task-id {task-id} --ski
 
 If `status == "fail"`, STOP. Report the failed gates verbatim and exit — do NOT auto-apply `--force`. Forcing is a human decision; the user can re-invoke with `--force --reason "<explanation>"` to bypass (the override is logged to `.aperant/events/{today}.jsonl`).
 
+## 0a. Fan-out worker identity (FRAMEWORK-BUG-033 defect 3)
+
+If your spawn prompt contains both `batch_id` and `task_id` (i.e. you are a fan-out worker subagent dispatched by `/apt:fan-out`), export `APT_AGENT_ID` in EVERY `Bash` invocation that runs `apt-tools ...`:
+
+```bash
+APT_AGENT_ID=fanout-${batch_id}-${task_id} node packages/framework/bin/apt-tools.mjs <command> ...
+```
+
+This pins your `team-status/{agentId}.json` file across short-lived CLI invocations. Without it, each `apt-tools` call gets a fresh `hostname-pid` agentId (per `agent-identity.mjs:86`), the previous pid dies, and `listTeamStatus({ includeStale: false })` filters healthy workers out between invocations — the team-status dashboard flickers into emptiness instead of showing 4 stable fan-out workers.
+
+Non-fan-out invocations of this agent receive no `batch_id` and skip this export — the legacy `hostname-pid` path remains correct for single-task work.
+
 ## 1. Load Context
 
 1. Read `CLAUDE.md` and `AGENTS.md` if they exist

package/dist/plugin/agents/apt-team-docs-narrator.md

@@ -72,6 +72,17 @@ If the parent spawned you without a mode you recognize, write an error line to `
    rendered table. If present, REPLACE the content between anchors (never
    append — this is how re-runs stay idempotent).
 7. Call `apt-tools roadmap sync . --reason 'narrator:phase-ship:<phase_id>'`.
+8. **Slice 5 / AC14 / ADR-0006 dual-write.** Write the rendered prose
+   block to a temp file (e.g. `mktemp -t narrator-prose-XXXXXX.md`), then
+   run
+   `apt-tools roadmap convex-mirror . --scope <scope> --phase <phase_id> --anchor-id phase-ship:<phase_id> --prose-path <tempfile>`
+   (add `--merged-pr <pr-number>` when known). The markdown write from
+   step 7 is canonical (ADR-0006); this step is the Convex mirror.
+   Fail-soft contract:
+   - exit 0 with `status:ok` or `status:queued` → continue normally
+   - exit non-zero with `status:error` → append the error message to
+     `.aperant/digests/errors.log` and continue (do NOT block on Convex
+     failures; the in-process cron drainer reconciles within 5 min)
 
 ## Mode 2: `decision-merge` — merge a recorded decision into the roadmap
 

package/dist/plugin/skills/apt/SKILL.md

@@ -41,8 +41,9 @@ you must follow when classifying.
 - **Config:** `.aperant/config.json` — project preferences
 - **State:** `.aperant/state.json` — execution state
 - **Task directories:** `.aperant/tasks/{task-id}/` — each task gets isolated artifacts
-- **Codex repo skills:** `.agents/skills/apt*/` — native Codex discovery surface installed by `apt-tools init`
-- **Claude agents:** `.claude/agents/apt-*.md` — specialized agent definitions for heavy workflows
+- **Claude surface:** `.claude/skills/`, `.claude/agents/`
+- **Codex surface:** `.codex/commands/`, `.codex/agents/`
+- **Pi surface:** `.pi/prompts/`, `.pi/skills/`
 </your_environment>
 
 <mandatory_first_step>

package/dist/plugin/skills/apt-execute/SKILL.md

@@ -453,6 +453,19 @@ After all subtasks are completed:
 node packages/framework/bin/apt-tools.mjs commit "build: all subtasks complete" --files implementation_plan.json build-progress.json
 ```
 
+### Mark lifecycle phase as `verifying`
+
+Flip the task's lifecycle phase at the success-end boundary so the next stage
+(`/apt:verify`) finds the task in the correct from-state. Mirror the same CLI
+shape as the start-boundary call in Section 2 — quick tasks (no phase linkage)
+silently no-op, and the update is idempotent so it is safe to re-run on
+`--continue`. Skip this step if any subtask ended in `"blocked"` — only the
+all-subtasks-completed branch should advance the phase.
+
+```bash
+node packages/framework/bin/apt-tools.mjs task update . --id {task-id} --lifecycle-phase verifying
+```
+
 Output:
 ```
 Execution complete:

package/dist/plugin/skills/apt-fan-out/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: apt:fan-out
+description: "Cross-task fan-out — spawn N apt-executor workers from one conductor terminal, each in its own worktree"
+apt-skill-version: {{APT_VERSION}}
+stage: execute
+intent: x-fan-out
+when_to_use: "You have N pre-planned, independent tasks (no file overlap, no cross-dependencies) and want to run them concurrently from a single host CLI session."
+user_invocable: true
+internal: false
+spawns_agent: true
+agent_name: "apt-executor"
+task_context: require-existing
+default_execution_mode: auto
+execution_modes:
+  - auto
+  - step
+allowed-tools: "Bash, Read, Write, Task"
+argument-hint: "apt:fan-out --tasks <id,id,id> [--phases <m/p,m/p>] [--unblocked]"
+gates: []
+---
+<objective>
+Run N pre-planned Aperant tasks concurrently from one conductor terminal. This skill is a thin orchestrator over the generalized wave engine (`unit_kind: "task"` path, see ADR-0003) and the existing primitives: `apt-tools worktree create --task`, `apt-tools lock claim`, `apt-tools event append`, and the `parallelization.max_tasks` quota. No daemon, no job queue, no in-skill scheduling. The host CLI's main thread is the conductor (ADR-0001); each spawned apt-executor subagent runs in its own worktree (ADR-0002).
+
+This is the "I have 16 unblocked tasks in this phase, run them all" surface. It replaces the old workaround of opening 16 sibling terminals manually.
+</objective>
+
+<your_environment>
+- **Working directory:** Project root (where you were invoked).
+- **apt-tools path:** `node packages/framework/bin/apt-tools.mjs` (or `node .aperant/deps/node_modules/@aperant/framework/bin/apt-tools.mjs` when running from an install mirror).
+- **Concurrency cap:** `parallelization.max_tasks` from `.aperant/config.json` (default 4, no paternalism cap per D-07). Read via `cli/config/parallelization.mjs:getMaxTasks(config)`.
+- **Worker identity:** Each spawned worker exports `APT_AGENT_ID=fanout-${batch_id}-${task_id}` before any `apt-tools ...` invocation (per FRAMEWORK-BUG-033 defect 3). This pins their `team-status/{agentId}.json` rows across short-lived CLI calls.
+- **Constitution:** Read `AGENTS.md` if it exists.
+</your_environment>
+
+<state_files>
+## State Files
+
+**Reads:**
+- `.aperant/state.json` — `active_tasks[*]` filtered when `--phases` or `--unblocked` resolves the task list.
+- `.aperant/roadmap/{scope}/milestones.json` — milestone/phase membership for `--phases`.
+- `.aperant/config.json:parallelization.max_tasks` — concurrency cap.
+
+**Writes (indirectly via spawned workers):**
+- `.aperant/team-status/fanout-${batch_id}-${task_id}.json` — one stable file per worker (per FRAMEWORK-BUG-033 defect 3 fix).
+- `.aperant/state.json:active_tasks[*].assigned_to` — workers stamp their `APT_AGENT_ID` on claim (per FRAMEWORK-BUG-033 defect 2 fix).
+- `.aperant/events/{today}.jsonl` — `task-claimed`, `wave-started`, `wave-completed` events.
+
+**No filesystem state of its own.** The skill body is pure orchestration glue; all heavy lifting reuses existing primitives.
+</state_files>
+
+<process>
+
+## 1. Resolve the batch — canonical task ID list
+
+The three input forms (`--tasks`, `--phases`, `--unblocked`) all resolve to a canonical `task_ids: [...]` list via the apt-tools helper:
+
+```bash
+node packages/framework/bin/apt-tools.mjs fan-out resolve . --tasks T1,T2,T3,T4
+# OR
+node packages/framework/bin/apt-tools.mjs fan-out resolve . --phases m1/p1,m1/p2
+# OR
+node packages/framework/bin/apt-tools.mjs fan-out resolve . --unblocked
+```
+
+Returns:
+```json
+{
+  "status": "ok",
+  "command": "fan-out-resolve",
+  "task_ids": ["T1", "T2", "T3", "T4"],
+  "source": "tasks",
+  "batch_id": "fanout-20260519-abc123"
+}
+```
+
+If `--tasks` IDs fail the `/^[a-z0-9_-]+$/i` validation regex, the helper returns `status: error` and the skill body MUST abort.
+
+## 2. Ensure each task has a worktree
+
+For each `task_id` in the batch:
+
+```bash
+node packages/framework/bin/apt-tools.mjs worktree create --task ${task_id}
+```
+
+(Skip if `state.active_tasks[task_id].worktree_path` is already set — the create command is idempotent.)
+
+## 3. Spawn N apt-executor subagents
+
+Read the `parallelization.max_tasks` cap from `.aperant/config.json` (or default 4). Slice `task_ids` into batches of size `min(cap, task_ids.length)`. For each task in the current batch, dispatch via the host CLI's `Task` tool with `run_in_background: true`:
+
+- `subagent: apt-executor`
+- `prompt` includes:
+  - `batch_id` (from step 1)
+  - `task_id`
+  - The worktree path for this task
+  - A reminder: "Export `APT_AGENT_ID=fanout-${batch_id}-${task_id}` in every Bash invocation that runs `apt-tools` — see `packages/framework/agents/apt-executor.md` §0a."
+
+The executor agent's `<process>` §0a already documents the env-export rule; the spawn prompt just has to seed `batch_id` and `task_id`.
+
+## 4. Poll team-status until all workers reach a terminal state
+
+```bash
+node packages/framework/bin/apt-tools.mjs team list .
+```
+
+Each worker's row uses its `APT_AGENT_ID=fanout-${batch_id}-${task_id}`. A worker is "done" when its corresponding task's `lifecycle_phase` is one of `closed`, `shipped-pending-merge`, or `blocked`.
+
+## 5. Report
+
+When all workers reach a terminal state, emit one consolidated summary: which tasks closed (verdict + PR URL), which are awaiting merge, which blocked. Recommend `/apt:close-task --all` for the post-merge sweep.
+
+</process>
+
+## Design references
+
+- **ADR-0001** — Host CLI main thread is the conductor; no daemon, no in-skill queue.
+- **ADR-0002** — One worktree per task; workers run independent feature branches.
+- **ADR-0003** — Wave engine accepts `unit_kind: "task"` so cross-task fan-out reuses the same primitives as intra-task subtask waves.
+
+## Config keys
+
+- `parallelization.max_tasks` (default 4) — concurrency cap for the spawn loop.
+- `parallelization.max_agents` (default 4) — global agent quota; the spawn loop respects whichever cap is lower.

package/dist/plugin/skills/apt-pr-review/SKILL.md

@@ -1110,6 +1110,8 @@ For `AUTHORSHIP_MODE == "owned"`, continue normally.
 
 AI agents have near-zero marginal cost per fix. The framework fixes **all** confirmed findings — critical, high, medium, and low — regardless of autonomy level. There is no severity gate and no "report for manual resolution" path. If a finding was confirmed by the validator, it gets fixed.
 
+**Hard rule — context budget is NOT a valid skip reason.** The orchestrator MAY NOT defer, drop, downgrade, or "punt for follow-up" any confirmed finding because its own context window feels heavy, because the run has already produced many fixes, or because it judges marginal value low. The query loop auto-compacts on its own — trust it. Per-finding fix work happens inside fix agents (separate context windows), so orchestrator pressure does not justify cutting their inputs. The only valid skip reasons are the ones enumerated in Key Principle #2 (`fixable: false`, critical finding without user approval, file assigned to another fixer). Any other skip is an unauthorized policy deviation — emit all confirmed findings to fixers, then let the audit gate adjudicate outcomes.
+
 | Autonomy | Action |
 |----------|--------|
 | `< 2` | Show findings summary before fixing. Then proceed with auto-fix. |
@@ -1647,7 +1649,7 @@ node packages/framework/bin/apt-tools.mjs workflow destroy . --id ${REVIEW_ID}
 Agents do NOT assign confidence percentages. Either they have evidence (actual code snippet from Read tool) or they do not have a finding. The validator independently verifies every finding against real code.
 
 ### 2. Fix Everything Found
-If it was found and confirmed, fix it. ALL severities. "This is minor" is NOT a valid skip reason. The only valid skip reasons are: `fixable: false`, critical findings without user approval, or files assigned to another fixer.
+If it was found and confirmed, fix it. ALL severities. "This is minor" is NOT a valid skip reason. **Neither is "my context window is heavy" or "I've already done a lot this run"** — orchestrator context pressure never authorizes dropping a confirmed finding (see Phase 6 → Principle: Fix Everything). The only valid skip reasons are: `fixable: false`, critical findings without user approval, or files assigned to another fixer.
 
 ### 3. Findings Flow Through Files
 Agents write to `.aperant/pr-reviews/{review-id}/findings/`. The orchestrator reads with the Read tool. Fix agents read finding files directly. This keeps the orchestrator context under 30%.
@@ -1711,6 +1713,11 @@ Fix agents self-report their outcome via a status line (`FIXED: X | FAILED: Y |
 **Wrong:** Skipping Phase 6 entirely when autonomy < 2.
 **Right:** Always fix all confirmed findings. At autonomy < 2, show findings summary first, then proceed with auto-fix. The only difference is whether findings are displayed before fixing — not whether they get fixed.
 
+### Mistake 7a: Dropping Findings Because Orchestrator Context Feels Heavy
+
+**Wrong:** Mid-Phase-6, the orchestrator decides "my window is getting heavy after 6 specialist rounds + Round 1 fixes — I'll skip the minor findings and report a partial fix." This is an unauthorized policy deviation, even when phrased as "judgment call" or "context-budget reasons."
+**Right:** Spawn fix agents for **every** confirmed finding regardless of orchestrator context state. Fix work happens in the fixer's window, not yours. The query loop auto-compacts when it needs to — trust it. If you genuinely cannot fit the spawn calls, that is a framework bug to file (not a license to ship a partial fix); emit all findings to fixers in the smallest batches possible and let the audit gate adjudicate. Severity, "diminishing returns," and your own token pressure are NOT skip authorities — only the three reasons in Key Principle #2 are.
+
 ### Mistake 8: Forgetting to Update metadata.json
 
 **Wrong:** Writing review.json but leaving metadata.json stuck at `"status": "in-progress"`.

package/dist/plugin/skills/apt-review/SKILL.md

@@ -333,6 +333,10 @@ Scores: logic={n} security={n} quality={n} architecture={n} performance={n}
 Report: {task_dir}/review.json
 ```
 
+`lifecycle_phase` remains at `reviewing` after /apt:review completes — this is
+the from-state /apt:ship expects for its atomic `reviewing → shipped-pending-merge`
+flip, so no further `task update --lifecycle-phase` call is needed here.
+
 **Always end with a "What's Next" recommendation:**
 
 ```

package/dist/plugin/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/dist/plugin/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/dist/plugin/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/dist/plugin/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/dist/schemas/quick-task.d.ts

@@ -1,8 +1,8 @@
 import { z } from 'zod';
 declare const VerificationStatusEnum: z.ZodEnum<{
     skip: "skip";
-    pass: "pass";
     fail: "fail";
+    pass: "pass";
 }>;
 declare const FileChangeSchema: z.ZodObject<{
     path: z.ZodString;
@@ -11,23 +11,23 @@ declare const FileChangeSchema: z.ZodObject<{
 declare const VerificationSchema: z.ZodObject<{
     typecheck: z.ZodEnum<{
         skip: "skip";
-        pass: "pass";
         fail: "fail";
+        pass: "pass";
     }>;
     lint: z.ZodEnum<{
         skip: "skip";
-        pass: "pass";
         fail: "fail";
+        pass: "pass";
     }>;
     visual: z.ZodEnum<{
         skip: "skip";
-        pass: "pass";
         fail: "fail";
+        pass: "pass";
     }>;
     test: z.ZodEnum<{
         skip: "skip";
-        pass: "pass";
         fail: "fail";
+        pass: "pass";
     }>;
     evidence_path: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
@@ -50,23 +50,23 @@ export declare const QuickTaskSchema: z.ZodObject<{
     verification: z.ZodObject<{
         typecheck: z.ZodEnum<{
             skip: "skip";
-            pass: "pass";
             fail: "fail";
+            pass: "pass";
         }>;
         lint: z.ZodEnum<{
             skip: "skip";
-            pass: "pass";
             fail: "fail";
+            pass: "pass";
         }>;
         visual: z.ZodEnum<{
             skip: "skip";
-            pass: "pass";
             fail: "fail";
+            pass: "pass";
         }>;
         test: z.ZodEnum<{
             skip: "skip";
-            pass: "pass";
             fail: "fail";
+            pass: "pass";
         }>;
         evidence_path: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
@@ -96,10 +96,10 @@ export declare function validateQuickTask(data: unknown): z.ZodSafeParseResult<{
         change: string;
     }[];
     verification: {
-        typecheck: "skip" | "pass" | "fail";
-        lint: "skip" | "pass" | "fail";
-        visual: "skip" | "pass" | "fail";
-        test: "skip" | "pass" | "fail";
+        typecheck: "skip" | "fail" | "pass";
+        lint: "skip" | "fail" | "pass";
+        visual: "skip" | "fail" | "pass";
+        test: "skip" | "fail" | "pass";
         evidence_path?: string | undefined;
     };
     commit: {
@@ -124,23 +124,23 @@ export declare const quickTaskJsonSchema: z.core.ZodStandardJSONSchemaPayload<z.
     verification: z.ZodObject<{
         typecheck: z.ZodEnum<{
             skip: "skip";
-            pass: "pass";
             fail: "fail";
+            pass: "pass";
         }>;
         lint: z.ZodEnum<{
             skip: "skip";
-            pass: "pass";
             fail: "fail";
+            pass: "pass";
         }>;
         visual: z.ZodEnum<{
             skip: "skip";
-            pass: "pass";
             fail: "fail";
+            pass: "pass";
         }>;
         test: z.ZodEnum<{
             skip: "skip";
-            pass: "pass";
             fail: "fail";
+            pass: "pass";
         }>;
         evidence_path: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@aperant/framework",
-	"version": "0.8.0",
+	"version": "0.8.1",
 	"description": "AI coding framework — composable skills for planning, executing, verifying, and reviewing code with any LLM provider. Works as Claude Code commands, Codex tasks, or programmatically.",
 	"author": "Mikalsen AI <hello@mikalsen.ai>",
 	"type": "module",

package/skills/apt/SKILL.md

@@ -41,8 +41,9 @@ you must follow when classifying.
 - **Config:** `.aperant/config.json` — project preferences
 - **State:** `.aperant/state.json` — execution state
 - **Task directories:** `.aperant/tasks/{task-id}/` — each task gets isolated artifacts
-- **Codex repo skills:** `.agents/skills/apt*/` — native Codex discovery surface installed by `apt-tools init`
-- **Claude agents:** `.claude/agents/apt-*.md` — specialized agent definitions for heavy workflows
+- **Claude surface:** `.claude/skills/`, `.claude/agents/`
+- **Codex surface:** `.codex/commands/`, `.codex/agents/`
+- **Pi surface:** `.pi/prompts/`, `.pi/skills/`
 </your_environment>
 
 <mandatory_first_step>