@aperant/framework 0.7.4 → 0.8.0

package/package.json

@@ -1,134 +1,134 @@
 {
-  "name": "@aperant/framework",
-  "version": "0.7.4",
-  "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",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "bin": {
-    "framework": "./bin/apt-tools.mjs",
-    "apt-tools": "./bin/apt-tools.mjs",
-    "apt-proof-video": "./bin/apt-proof-video.mjs"
-  },
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./types": {
-      "types": "./dist/types/index.d.ts",
-      "import": "./dist/types/index.js"
-    },
-    "./cost": {
-      "types": "./dist/cost/index.d.ts",
-      "import": "./dist/cost/index.js"
-    },
-    "./mappers": {
-      "types": "./dist/mappers/index.d.ts",
-      "import": "./dist/mappers/index.js"
-    },
-    "./schemas": {
-      "types": "./dist/schemas/index.d.ts",
-      "import": "./dist/schemas/index.js"
-    },
-    "./standalone": {
-      "types": "./dist/standalone/index.d.ts",
-      "import": "./dist/standalone/index.js"
-    },
-    "./coordination/event-schema": {
-      "types": "./src/cli/coordination/event-schema.d.ts",
-      "import": "./src/cli/coordination/event-schema.mjs"
-    },
-    "./roadmap/conductor-view": {
-      "types": "./src/cli/roadmap/conductor-view.d.ts",
-      "import": "./src/cli/roadmap/conductor-view.mjs"
-    },
-    "./design/scan": {
-      "import": "./src/cli/design/scan.mjs"
-    },
-    "./design/extract-repo": {
-      "import": "./src/cli/design/extract-repo.mjs"
-    },
-    "./design/synthesize": {
-      "import": "./src/cli/design/synthesize.mjs"
-    }
-  },
-  "files": [
-    "dist/",
-    "bin/",
-    "src/cli/",
-    "src/cost/",
-    "commands/",
-    "skills/",
-    "agents/",
-    "prompts/",
-    "templates/",
-    "context/",
-    "workflows/",
-    "examples/",
-    "LICENSE",
-    "README.md",
-    "CHANGELOG.md",
-    "!**/__tests__/**",
-    "!**/*.test.*",
-    "!**/*.spec.*",
-    "!**/*.test.d.ts.map",
-    "!**/*.test.js.map"
-  ],
-  "keywords": [
-    "ai",
-    "framework",
-    "coding-assistant",
-    "claude-code",
-    "codex",
-    "aperant"
-  ],
-  "license": "AGPL-3.0-only",
-  "homepage": "https://github.com/Mikalsen-AI/aperant-cloud-desktop/tree/main/packages/framework#readme",
-  "bugs": {
-    "url": "https://github.com/Mikalsen-AI/aperant-cloud-desktop/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/Mikalsen-AI/aperant-cloud-desktop.git",
-    "directory": "packages/framework"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "dependencies": {
-    "@clack/prompts": "^1.2.0",
-    "proper-lockfile": "^4.1.2",
-    "yaml": "^2.8.3",
-    "zod": "^4.3.6"
-  },
-  "optionalDependencies": {
-    "@babel/parser": "^7.29.2",
-    "@babel/traverse": "^7.29.0",
-    "@google/genai": "^1.50.1",
-    "css-tree": "^3.2.1",
-    "playwright": "^1.59.1"
-  },
-  "devDependencies": {
-    "@vitest/coverage-v8": "^4.1.5"
-  },
-  "scripts": {
-    "build": "tsc && node scripts/extract-personas-schema.mjs",
-    "dev": "tsc --watch --preserveWatchOutput",
-    "typecheck": "tsc --noEmit",
-    "lint": "biome check . --diagnostic-level=error",
-    "lint:fix": "biome check --write . --diagnostic-level=error",
-    "clean": "rm -rf dist",
-    "test": "vitest run",
-    "c28:cutover": "node scripts/c28-cutover.mjs",
-    "build-plugin": "node scripts/build-plugin.mjs",
-    "publish-plugin": "node scripts/publish-plugin.mjs",
-    "publish:verdaccio": "node scripts/publish-verdaccio.mjs",
-    "release:verdaccio": "pnpm build && pnpm publish:verdaccio",
-    "ship:verdaccio": "npm version patch --no-git-tag-version && pnpm build && pnpm publish:verdaccio"
-  }
-}
+	"name": "@aperant/framework",
+	"version": "0.8.0",
+	"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",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"bin": {
+		"framework": "./bin/apt-tools.mjs",
+		"apt-tools": "./bin/apt-tools.mjs",
+		"apt-proof-video": "./bin/apt-proof-video.mjs"
+	},
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./types": {
+			"types": "./dist/types/index.d.ts",
+			"import": "./dist/types/index.js"
+		},
+		"./cost": {
+			"types": "./dist/cost/index.d.ts",
+			"import": "./dist/cost/index.js"
+		},
+		"./mappers": {
+			"types": "./dist/mappers/index.d.ts",
+			"import": "./dist/mappers/index.js"
+		},
+		"./schemas": {
+			"types": "./dist/schemas/index.d.ts",
+			"import": "./dist/schemas/index.js"
+		},
+		"./standalone": {
+			"types": "./dist/standalone/index.d.ts",
+			"import": "./dist/standalone/index.js"
+		},
+		"./coordination/event-schema": {
+			"types": "./src/cli/coordination/event-schema.d.ts",
+			"import": "./src/cli/coordination/event-schema.mjs"
+		},
+		"./roadmap/conductor-view": {
+			"types": "./src/cli/roadmap/conductor-view.d.ts",
+			"import": "./src/cli/roadmap/conductor-view.mjs"
+		},
+		"./design/scan": {
+			"import": "./src/cli/design/scan.mjs"
+		},
+		"./design/extract-repo": {
+			"import": "./src/cli/design/extract-repo.mjs"
+		},
+		"./design/synthesize": {
+			"import": "./src/cli/design/synthesize.mjs"
+		}
+	},
+	"scripts": {
+		"build": "tsc && node scripts/extract-personas-schema.mjs",
+		"dev": "tsc --watch --preserveWatchOutput",
+		"typecheck": "tsc --noEmit",
+		"lint": "biome check . --diagnostic-level=error",
+		"lint:fix": "biome check --write . --diagnostic-level=error",
+		"clean": "rm -rf dist",
+		"test": "vitest run",
+		"c28:cutover": "node scripts/c28-cutover.mjs",
+		"build-plugin": "node scripts/build-plugin.mjs",
+		"publish-plugin": "node scripts/publish-plugin.mjs",
+		"publish:verdaccio": "node scripts/publish-verdaccio.mjs",
+		"release:verdaccio": "pnpm build && pnpm publish:verdaccio",
+		"ship:verdaccio": "npm version patch --no-git-tag-version && pnpm build && pnpm publish:verdaccio"
+	},
+	"files": [
+		"dist/",
+		"bin/",
+		"src/cli/",
+		"src/cost/",
+		"commands/",
+		"skills/",
+		"agents/",
+		"prompts/",
+		"templates/",
+		"context/",
+		"workflows/",
+		"examples/",
+		"LICENSE",
+		"README.md",
+		"CHANGELOG.md",
+		"!**/__tests__/**",
+		"!**/*.test.*",
+		"!**/*.spec.*",
+		"!**/*.test.d.ts.map",
+		"!**/*.test.js.map"
+	],
+	"keywords": [
+		"ai",
+		"framework",
+		"coding-assistant",
+		"claude-code",
+		"codex",
+		"aperant"
+	],
+	"license": "AGPL-3.0-only",
+	"homepage": "https://github.com/Mikalsen-AI/aperant-cloud-desktop/tree/main/packages/framework#readme",
+	"bugs": {
+		"url": "https://github.com/Mikalsen-AI/aperant-cloud-desktop/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/Mikalsen-AI/aperant-cloud-desktop.git",
+		"directory": "packages/framework"
+	},
+	"engines": {
+		"node": ">=18.0.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"@clack/prompts": "^1.2.0",
+		"proper-lockfile": "^4.1.2",
+		"yaml": "^2.8.3",
+		"zod": "^4.3.6"
+	},
+	"optionalDependencies": {
+		"@babel/parser": "^7.29.2",
+		"@babel/traverse": "^7.29.0",
+		"@google/genai": "^1.50.1",
+		"css-tree": "^3.2.1",
+		"playwright": "^1.59.1"
+	},
+	"devDependencies": {
+		"@vitest/coverage-v8": "^4.1.5"
+	}
+}

package/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/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/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/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