@aperant/framework 0.16.0 → 0.19.0

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

@@ -17,7 +17,7 @@ execution_modes:
   - plan-mode
   - plan-only
 allowed-tools: "Bash, Read, Write, Edit, Grep, Glob, Task"
-argument-hint: "apt:run [task description] [--skip-review] [--phase-mode auto|agent-team|sub-agents|sequential] [--spar-gates plan[,execute]]"
+argument-hint: "apt:run [task description] [--skip-review] [--phase-mode auto|agent-team|sub-agents|sequential] [--spar-gates plan[,execute]] [--full]"
 gates: 
   - constitution-read
   - constitution-coverage
@@ -29,6 +29,8 @@ config_keys:
 Run the full Aperant pipeline: plan a task, execute all subtasks, verify the implementation, and optionally review the code. This is the one-command experience — from task description to verified, reviewed code.
 
 As of C32 the STANDARD and DEEP auto pipelines **terminate on review** (`plan → execute → verify → review`). Pass `--skip-review` to stop after verify; for trivial work the QUICK track still skips planning entirely.
+
+Pass `--full` to carry a SINGLE task all the way to **merged + green**: it extends the pipeline past review through **ship** (a PR that auto-merges to main on green — never a direct push) and **watch-CI** (arm the watcher with auto-merge so the change lands once CI passes). `--full` is a thin chain over the existing `/apt:ship` + `/apt:watch-ci` skills — it forces review ON and is hard-guarded by `autonomy.allow_yolo` plus a one-time confirm (§1a). A `/apt:run` invocation WITHOUT `--full` behaves exactly as today (terminates on review).
 </objective>
 
 <your_environment>
@@ -58,7 +60,7 @@ As of C32 the STANDARD and DEEP auto pipelines **terminate on review** (`plan
 
 1. Read `AGENTS.md` if it exists
 2. Parse task description from `$ARGUMENTS` (everything before flags)
-3. Parse flags: `--skip-review`, `--dry-run`, `--phase-mode <mode>`, `--spar-gates <comma-list>`.
+3. Parse flags: `--skip-review`, `--dry-run`, `--phase-mode <mode>`, `--spar-gates <comma-list>`, `--full`.
    - `--spar-gates <plan|execute|plan,execute>` (FRAMEWORK-RFC-001) — comma-separated stage list to auto-fire `/apt:spar` after. Per-invocation override of `.aperant/config.local.json` `spar.enabled`. On QUICK track, print the verbatim hard-reject line and discard the flag (Fast Path Guarantee — CLAUDE.md):
 
    ```
@@ -71,6 +73,52 @@ As of C32 the STANDARD and DEEP auto pipelines **terminate on review** (`plan
 node packages/framework/bin/apt-tools.mjs state .
 ```
 
+## 1a. `--full` flag — surface + gates
+
+This section runs ONLY when `--full` was parsed in §1. When `--full` is absent, skip this entire section and run the pipeline exactly as today (manual mode is byte-behavior-unchanged).
+
+**Contradiction handling (resolve in THIS precedence order — the "discard" cases win first, so a `--full` that is discarded never triggers the conflict or autonomy gates):**
+
+0. **QUICK track wins first (Fast Path Guarantee).** If the task is QUICK track, discard `--full` with the Fast-Path line (item 4 below) and run the QUICK one-shot path unchanged — do NOT evaluate the `--skip-review` conflict (item 1) or the autonomy gate. On QUICK, `--full` is treated as never passed.
+
+1. **`--full` + `--skip-review` → hard reject.** `--full` requires review before auto-ship, so the two flags are contradictory. Do NOT silently let one win — print the verbatim line and exit:
+
+   ```
+   [apt:run] --full and --skip-review conflict (--full requires review before auto-ship). Pick one.
+   ```
+
+2. **`--full` IMPLIES review ON.** Treat `--skip-review` as never set for the rest of the run; §6 Review always executes.
+
+3. **`--full` + `--dry-run` → dry-run wins.** Run the plan stage only and report (the existing §3 dry-run exit), then stop. No execute, no ship — `--full` is discarded for this run.
+
+4. **QUICK track → discard `--full` with the Fast-Path line.** On QUICK track `--full` is hard-exempt (CLAUDE.md Fast Path Guarantee). Print the verbatim line and run the QUICK one-shot path unchanged:
+
+   ```
+   [apt:run] --full ignored for QUICK track (Fast Path Guarantee)
+   ```
+
+`--full` composes normally with `--phase-mode` and `--spar-gates`.
+
+**Autonomy gate (load-bearing safety valve, ID-03):**
+
+Auto-ship + auto-merge is YOLO-class. Read `.aperant/config.json` for `autonomy.allow_yolo` (boolean) and the autonomy `level` (0–3).
+
+1. **`allow_yolo` hard guard.** If `autonomy.allow_yolo !== true`, STOP before ship with the verbatim line and leave the task at `reviewing` (fully shippable by hand):
+
+   ```
+   [apt:run] --full needs autonomy.allow_yolo=true (auto-ship + auto-merge to main). Enable via /apt:setup or drop --full.
+   ```
+
+2. **One-time confirm at autonomy < 3.** Before opening the auto-merging PR (just before §6.1 Ship below), emit ONE confirmation when autonomy `level < 3` AND `--yolo` was not also passed:
+
+   ```
+   [apt:run --full] About to open a PR that auto-merges to main once CI is green. Proceed? [y/N]
+   ```
+
+   At autonomy 3 OR when `--yolo` is passed, degrade to silent (mirrors `/apt:ship`'s autonomy-3 degrade). On `N` / empty, STOP after review with the standard `/apt:ship` hand-off hint — the task is left at `reviewing`, fully shippable by hand.
+
+Note: the `allow_yolo` guard + the one-time confirm are evaluated up front here (parse-time gating) and the confirm is RE-SURFACED at the ship boundary (§6.1) so the user confirms immediately before the irreversible auto-merge arm. Review always runs first, and auto-merge always waits for green.
+
 ## 1b. Resolve Orchestration Mode
 
 Run reconcile to determine the effective orchestration strategy for this pipeline run. Pass the task's track via `--track <quick|standard|deep>` so per-track defaults from `.aperant/config.json:orchestration.per_track` apply (roundtable 2026-05-14 R7):
@@ -338,6 +386,58 @@ Skip on `spar.enabled === true` (no pre-ship gate exists in v2 — see spec §8
 
 **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.
 
+## 6.1. Stage 5 — Ship (apt:ship) — `--full` only
+
+**Run this section ONLY when `--full` was parsed (§1a) AND review passed** — "review passed" means the §6 review `assessment` is `approve`; a `request-changes` assessment STOPS here (task left at `reviewing`, no ship — see the stop-condition table in §6.2). When `--full` is absent, skip §6.1 + §6.2 entirely and go straight to §7 (manual mode — terminates on review).
+
+Pipeline order note: the user's phrasing was *"review, verify"* but `/apt:run` runs **verify (§5) → review (§6) → ship (§6.1)**. KEEP this order — verify gates review, and review consumes `qa_signoff.json`. Do NOT silently reorder. `--full` runs `plan → execute → verify → review → ship → watch-ci`.
+
+**Pre-ship gate (re-surface the §1a confirm at the boundary):**
+
+1. Re-check `autonomy.allow_yolo === true` (already validated in §1a; re-read here so a mid-run config edit cannot slip an auto-merge past the guard). If false, STOP with the §1a `allow_yolo` line; leave the task at `reviewing`.
+2. Emit the §1a one-time confirm (`[apt:run --full] About to open a PR that auto-merges to main once CI is green. Proceed? [y/N]`) when autonomy `level < 3` and `--yolo` was not passed. At autonomy 3 / `--yolo`, degrade to silent. On `N` / empty, STOP after review with the standard `/apt:ship` hand-off hint; the task stays at `reviewing`.
+
+**Ship (Option A — PR that auto-merges to main on green; NEVER a direct push/merge):**
+
+Invoke `/apt:ship` inline. It runs its own hard-gate (verify-approved / review-clean / consistency / gitignore), opens the PR against the task's recorded `base_branch` (main for a task forked from main), and atomically flips `reviewing → shipped-pending-merge` via `task update --pr-url` — which also arms the post-ship watcher per `ci_watch.after_ship`. `--full` MUST NEVER `git push`/`git merge` directly to main (ID-02 Option B is rejected unconditionally): "ship to main" means **a PR that auto-merges to main on green**, not a force-push.
+
+Capture the opened PR number `{N}` from the `/apt:ship` result for §6.2.
+
+If `/apt:ship`'s hard-gate fails, or the branch is behind and the rebase conflicts with no `resolve_merge_conflicts`, STOP — no PR is opened and the task stays at `reviewing` (see the stop-condition table below).
+
+## 6.2. Stage 6 — Watch-CI arm (auto-merge-on-green) — `--full` only
+
+After the PR opens, force auto-merge for THIS run regardless of the config default (`ci_watch.auto_merge_on_green` is `false` by default per the D-08 kill-criteria). `/apt:ship` already armed the watcher via `ci_watch.after_ship`; this call PATCHES that already-armed watch's auto-merge flag to `true` (it does NOT reimplement arming and is idempotent):
+
+```bash
+node packages/framework/bin/apt-tools.mjs ci-watch start . --pr {N} --task-id {task-id} --host {cli} --auto-merge-on-green
+```
+
+**Branch on host cron capability.** Run host-detect and read `host_capabilities.cron`:
+
+```bash
+node packages/framework/bin/apt-tools.mjs host-detect .
+```
+
+- **cron-capable host** (e.g. Claude Code, `cron: true`): the watcher is armed with auto-merge ON; register the recurring tick via the host's `CronCreate` (per `/apt:watch-ci` §3). Then **EXIT — do NOT loop** (respect `/apt:watch-ci`'s single-execution-per-invocation contract). The cron beat drives the watcher to merged + green unattended. Report: watcher armed, auto-merge ON, and the deadline.
+- **non-cron host** (Codex / Gemini / OpenCode): truly-unattended watching is impossible. Arm the watch state + auto-merge (the `ci-watch start --auto-merge-on-green` above) but do NOT impersonate a scheduler — NEVER fake a `while` / `sleep` loop. Print the honest manual-tick instruction:
+
+  ```
+  [apt:run --full] PR opened + CI watcher state created (host has no cron). Advance manually: /apt:watch-ci --tick --pr {N}. Auto-merge-on-green is set; the merge fires on the first green tick you run.
+  ```
+
+**Stop conditions (every gate is reused; each STOP leaves the task in its current lifecycle state and NEVER merges). `--full` adds NO new gate — it only chains the existing ones and surfaces the stop reason in §7:**
+
+| Stop point | Resulting state |
+|---|---|
+| QA `rejected` after max iters (§5) | `verifying`; no ship |
+| Review `request-changes` (§6) | `reviewing`; no ship |
+| Ship hard-gate fail (verify-approved / review-clean / consistency / gitignore) | `reviewing`; no PR |
+| Branch behind + rebase conflict (no `resolve_merge_conflicts`) | `reviewing`; no PR |
+| `allow_yolo=false` or confirm `N` (§1a / §6.1) | `reviewing`; no PR |
+| CI red after 5-attempt / 4h-wall (watcher) | `shipped-pending-merge`; PR comment, NOT merged |
+| Merge conflict mid-watch (`diverged-bailed`) | `shipped-pending-merge`; PR comment, NOT merged |
+
 ## 7. Pipeline Summary
 
 Render the phase rail panel verbatim — branch glyphs `┌─ │ └─`, status glyphs `✓` (done) / `●` (active) / `○` (pending/skipped), inline metrics per row drawn from the artifacts written across §3–§6:
@@ -359,7 +459,18 @@ Substitute live values from the on-disk artifacts: `build-progress.json.complete
 **Always end with a "What's Next" recommendation:**
 
 ```
-{If review assessment is "approve" and QA approved:}
+{If --full ran and the PR opened (cron host):}
+-> Shipped. PR #{N} opened; CI watcher armed with auto-merge-on-green (deadline {deadline}).
+   The cron beat drives it to merged + green. /apt:close-task runs post-merge.
+
+{If --full ran and the PR opened (non-cron host):}
+-> Shipped. PR #{N} opened; watcher state created with auto-merge-on-green.
+   Advance manually: /apt:watch-ci --tick --pr {N} (merge fires on the first green tick).
+
+{If --full was requested but a gate STOPPED before ship:}
+-> {stop reason}. Task left at {lifecycle state}, not merged. {remediation per the stop-condition table}
+
+{If review assessment is "approve" and QA approved (no --full):}
 -> Recommended: /apt:ship — create PR for this task
    Also: /apt:pr-review (deep multi-agent review) | manual review
 
@@ -388,5 +499,17 @@ atomic `reviewing → shipped-pending-merge` flip. `/apt:ship` then flips
 does not need to record or drain anything beyond ensuring each child-skill
 stage runs to its success-end.
 
+**`--full` full lifecycle map:** `planning → executing → verifying → reviewing
+→ shipped-pending-merge → (CI green + merged) → completed`. The `reviewing →
+shipped-pending-merge` flip is done atomically by ship's `task update --pr-url`
+(§6.1). `shipped-pending-merge → completed` is done by `/apt:close-task`
+post-merge — **`--full` does NOT auto-invoke `/apt:close-task`.** On cron hosts
+the merge happens asynchronously AFTER `--full` has exited, so `--full` cannot
+observe it; closeout is left to the existing path (the watcher's green branch
+suggests `/apt:close-task`, and the user / passive sweeper runs it). Folding
+close-task into `--full` would require it to become a recurring watcher —
+explicitly rejected (it would duplicate the watcher and violate the
+single-execution contract).
+
 </process>
 </output>

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

@@ -578,6 +578,8 @@ suggest_mode=$(jq -r '.pr_review.suggest_after_ship // "always"' .aperant/config
 
 ### 7.2 Post-ship /apt:watch-ci hook
 
+> Cross-reference: `/apt:run --full` drives this skill's §6 PR creation + §7.2 watcher arming end-to-end (review → ship → auto-merge-on-green watch). When invoked from that chain, the watcher's auto-merge is force-enabled for the run via `apt-tools ci-watch start --auto-merge-on-green` (see `apt-run/SKILL.md` §6.1–§6.2); `/apt:ship` itself behaves identically whether invoked standalone or by `--full`.
+
 After Section 7.1's hint resolves (whether it ran the deep review or skipped), report or interactively arm the post-ship CI watcher. The hook is controlled by `ci_watch.after_ship` in `.aperant/config.json` (tri-state: `auto` | `ask` | `never`). The default depends on host capability — `auto` on cron-capable hosts (Claude Code, Pi), `never` elsewhere.
 
 **Skip entirely** when no PR URL was captured in Section 6 (library `npm publish`-only path — same skip rule as 7.1).

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

@@ -137,6 +137,8 @@ Do NOT proceed; self-sparring is sycophancy by construction (the host cannot obj
 
 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."
 
+**Codex walk order (anti-staleness — do NOT infer it from prose).** The codex MCP rung is the ONLY codex transport that forces the agent to NAME a model, and a named model is a staleness vector (the upstream MCP server has no access to the user's config and silently substitutes a stale default; the agent could also substitute one from training memory). The self-resolving rungs (plugin shim → raw CLI) pass NO `--model` and let `codex exec` inherit `~/.codex/config.toml`, so they are staleness-proof by construction. Therefore, for the **codex** partner specifically, prefer the self-resolving plugin → CLI rungs in the common case and demote the MCP rung to **LAST**. Do NOT hand-order the rungs from this prose — run `apt-tools spar-resolve-partner --partner codex` and FOLLOW the preference it returns: walk in the order of its `recommended_walk` array (`["plugin","cli","mcp"]`) and treat `prefer_self_resolving: true` as authoritative. The generic `host.partner_transports.codex` array stays MCP-first (it is data shared with other consumers, not a spar walk order); the resolver's preference overrides it for codex only. **claude / gemini stay MCP-first** — their MCP rungs take only `{prompt}` and need no model, so there is no staleness vector and no walk change.
+
 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:
 
 ```
@@ -183,9 +185,9 @@ 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, model})` where `model` is parsed from `~/.codex/config.toml`'s `model = "<value>"` line (see §5a below). | Preferred. 900000ms (15 min) timeout (configurable `apt-spar.mcp_timeout_ms`); on timeout fall through to plugin then CLI. If `~/.codex/config.toml` is missing OR the `model =` line is absent/unparseable, treat MCP rung as UNAVAILABLE and fall through to plugin/CLI — never invent a default model (the MCP server's built-in fallback is stale `gpt-5.3-codex`, which is exactly the bug we are fixing). |
-| codex | plugin | `node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" task "$(cat <<'APT_SPAR_PROMPT_EOF' ... APT_SPAR_PROMPT_EOF\n)"` | No `--model` flag — `codex-companion.mjs` invokes `codex exec` which inherits `~/.codex/config.toml` automatically. **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`. No `--model` flag — `codex exec` inherits `~/.codex/config.toml` automatically. Verify with `codex --help`. |
+| codex | mcp | tool call: `mcp__codex-mcp__codex({prompt, model})` where `model` is the `model` field returned by `apt-tools spar-resolve-partner --partner codex` (see §5a below). | **Demoted to LAST for codex** (see the codex walk-order note in §3) — attempt this rung only when the resolver returns `available: true`. 900000ms (15 min) timeout (configurable `apt-spar.mcp_timeout_ms`); on timeout fall through to plugin then CLI. When the resolver returns `available: false`, treat the MCP rung as UNAVAILABLE and fall through to plugin/CLI — never invent a default model (the MCP server silently substitutes a stale hardcoded default model id, which is exactly the bug we are fixing). |
+| codex | plugin | `node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" task "$(cat <<'APT_SPAR_PROMPT_EOF' ... APT_SPAR_PROMPT_EOF\n)" < /dev/null` | No `--model` flag — `codex-companion.mjs` invokes `codex exec` which inherits `~/.codex/config.toml` automatically. **NO `--write`. NO `--effort` override.** Per SPAR-04 — spar is conversation, not patching. The `< /dev/null` is load-bearing — the shim forwards to `codex exec`, which wedges on stdin EOF under a no-TTY subprocess (see the wedge note below). |
+| codex | cli | `codex exec --sandbox read-only "$(cat <<'APT_SPAR_PROMPT_EOF' ... APT_SPAR_PROMPT_EOF\n)" < /dev/null` | Precedent: `apt-pr-review/SKILL.md:1084`. No `--model` flag — `codex exec` inherits `~/.codex/config.toml` automatically. The `< /dev/null` un-wedges the no-TTY stdin block and `--sandbox read-only` keeps the spar read-only (see the wedge note below). Verify with `codex --help`. |
 | 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. |
@@ -193,21 +195,29 @@ The table below shows the canonical command shape per (partner × rung); the act
 | gemini | plugin | n/a | No plugin shim exists for Gemini. Skip this rung. |
 | gemini | cli | `gemini "$(cat <<'APT_SPAR_PROMPT_EOF' ... APT_SPAR_PROMPT_EOF\n)"` | No `-m` flag — gemini-cli resolves model via `--model` > `GEMINI_MODEL` env > `~/.gemini/settings.json` > built-in default per `docs/cli/model-routing.md:47-58`. Drop the flag, let the cascade work; users override per-shell via `GEMINI_MODEL=...` or per-project via `settings.json`. |
 
+**Codex stdin-wedge note (load-bearing).** `codex exec` reads the positional prompt and THEN blocks on stdin EOF under a no-TTY subprocess (the Bash tool), printing `Reading additional input from stdin…` and never returning. Redirecting `< /dev/null` un-wedges it (verified: returns in ~6s instead of hanging, exit 0, and prints the resolved `model:` it used). Both codex Bash rungs (plugin shim + raw CLI) carry `< /dev/null` because the shim forwards to `codex exec`. The `--sandbox read-only` flag on the raw-CLI rung keeps the spar read-only — aligning with the SPAR-04 "NO `--write`" rule; read-only still permits the partner's investigative Read/Grep.
+
 Set the Bash tool's `timeout` parameter to `--timeout-ms` (default 300000).
 
 **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.
 
 ## 5a. Codex MCP model resolution
 
-The codex MCP rung (table row above) requires an explicit `model` arg sourced from the user's `~/.codex/config.toml`. The MCP server (`codex-mcp-server`) does NOT read `~/.codex/config.toml` itself — when no `model` is passed it falls back to a hardcoded stale `gpt-5.3-codex`, silently overriding the user's actual configured model. Resolve the model exactly once per spar invocation, before the rung-table walk:
+The codex MCP rung (table row above) requires an explicit `model` arg sourced from the user's `~/.codex/config.toml`. The MCP server (`codex-mcp-server`) does NOT read `~/.codex/config.toml` itself — when no `model` is passed it silently substitutes a stale hardcoded default model id, overriding the user's actual configured model. **Aperant holds zero model names** — resolve the model LIVE via the deterministic resolver exactly once per spar invocation, before the rung-table walk:
 
 ```bash
-# Resolve the codex MCP model exactly once per spar invocation, before the rung table walk
-CODEX_MCP_MODEL="$(grep -E '^model = "[^"]+"' "$HOME/.codex/config.toml" 2>/dev/null | head -1 | sed -E 's/^model = "([^"]+)".*/\1/')"
-# If empty → codex MCP rung is UNAVAILABLE; fall through to plugin/CLI.
+# Resolve the codex partner model + transport preference LIVE, once per spar
+# invocation, before the rung-table walk. apt-tools reads ~/.codex/config.toml
+# fresh and never bakes a default.
+apt-tools spar-resolve-partner --partner codex
 ```
 
-If `$CODEX_MCP_MODEL` is empty (file missing, `model =` line absent, or value not double-quoted), treat the MCP rung as UNAVAILABLE and fall through to plugin → CLI. **Never invent a default** — the upstream MCP server's built-in `gpt-5.3-codex` fallback is exactly the bug this resolution path exists to fix.
+The command emits a JSON envelope `{available, model, source, reason, prefer_self_resolving, recommended_walk}`:
+
+- When `available: true`, pass the returned `model` field **VERBATIM** into the codex MCP tool call's `model` arg — do NOT transform it, and do NOT substitute a model from your own training memory.
+- When `available: false` (the envelope carries a machine `reason` of `config_missing` / `no_model_key` / `unparseable`), treat the codex MCP rung as **UNAVAILABLE** and fall through to plugin → CLI. **Never invent a default** — substituting any model name is exactly the staleness bug this resolution path exists to fix. The plugin and raw-CLI rungs pass no `--model` and let `codex exec` self-resolve from the user's live config, so the fall-through is always staleness-proof.
+
+Follow the envelope's `recommended_walk` / `prefer_self_resolving` for the rung order (see the codex walk-order note in §3) rather than ordering the rungs by hand.
 
 **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:
 
@@ -216,7 +226,7 @@ If `$CODEX_MCP_MODEL` is empty (file missing, `model =` line absent, or value no
 node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" task "$(cat <<'APT_SPAR_PROMPT_EOF'
 <prompt body — opaque, no shell expansion>
 APT_SPAR_PROMPT_EOF
-)"
+)" < /dev/null
 
 # Claude direction
 claude -p "$(cat <<'APT_SPAR_PROMPT_EOF'

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

@@ -37,7 +37,7 @@ The locked decisions backing every section are in `.aperant/context/notes/framew
 - **Working directory:** the task's worktree (or the project root if this is a non-worktree task).
 - **State files:** `.aperant/ci-watches/{pr}.json` (per-PR state, D-04); `.aperant/ci-watches/{pr}.lock` (per-PR atomic lock, D-05). Both ephemeral — they are NOT committed.
 - **Events:** every tick appends a `ci-watch.tick` event to `.aperant/events/{today}.jsonl`; `start` appends `ci-watch.armed`; the fix-and-push path appends `ci-watch.fix-pushed`; terminal actions append `ci-watch.stopped` with a `reason`.
-- **CLI surface:** `apt-tools ci-watch start|stop|status|tick --pr N`. The skill body shells out to those subcommands — DO NOT re-implement the classifier in your prompt; the cmd already does it.
+- **CLI surface:** `apt-tools ci-watch start|stop|status|tick --pr N`. `start` also accepts `--auto-merge-on-green` (per-run override — forces `auto_merge_on_green: true` on the snapshot without persisting `ci_watch.auto_merge_on_green` into config; on an already-armed watch it PATCHES the snapshot rather than no-opping). `/apt:run --full` uses this flag to guarantee auto-merge for a single PR after ship's config-driven arm runs first. The skill body shells out to those subcommands — DO NOT re-implement the classifier in your prompt; the cmd already does it.
 
 ---
 
@@ -87,7 +87,7 @@ For the `--tick` mode, execute exactly the following sequence — once — insid
 
 When `action ∈ {green, merged, closed, attempts-cap, wall-cap, identical-log}`:
 
-- **green** — print "CI green for PR {N}." If `ci_watch.auto_merge_on_green` is `true` in `.aperant/config.json`, run `gh pr merge {N} --auto --squash` then suggest `/apt:close-task`.
+- **green** — print "CI green for PR {N}." If `ci_watch.auto_merge_on_green` is `true` in `.aperant/config.json`, run `gh pr merge {N} --squash` then suggest `/apt:close-task`. Use a PLAIN merge here, NOT `--auto`: the classifier has already confirmed every check is `SUCCESS`/`SKIPPED` (`stop-matrix.mjs` `allGreen`) before this branch fires, so green is gated by the watcher, not by GitHub branch protection. `--auto` bought nothing on this path — in a repo WITHOUT required status checks `gh pr merge --auto` degrades to an immediate merge anyway — and dropping it removes the classify→merge ambiguity in unprotected repos.
   - **DO NOT pass `--delete-branch`** to `gh pr merge` from this auto-merge path — ever, unconditionally. The watcher's cwd is the task worktree, where `gh`'s `--delete-branch` post-merge cleanup tries to `git switch <base>` and fails because `<base>` is checked out in the primary worktree. The remote merge has already succeeded by then; local branch + worktree cleanup is `/apt:close-task`'s job via `apt-tools task close-merged` → `computeWorktreeCleanup` (see FRAMEWORK-BUG-019).
 
   Else print the exact D-08 text:
@@ -127,7 +127,7 @@ When `action === 'fix'` (or `diverged-rebased`/`diverged-bailed`):
 
 For `diverged-rebased`: the cmd already returned the verb; the orchestrator runs `git -C {worktree} fetch && git rebase origin/{base}` BEFORE the fix step. On conflict the action becomes `diverged-bailed`.
 
-For `diverged-bailed`: default behavior is to exit with a PR comment summarizing the conflict. Self-heal is **opt-in** via `ci_watch.resolve_merge_conflicts` (default false) in `.aperant/config.json`. When enabled, instead of bailing, hand off to **`/apt:merge-conflict-resolution`** (`--base origin/{base}`) for the worktree; it resolves the rebase conflict inline and re-probes mergeability. On success, continue to the §5 fix-and-push step (`git push origin {branch}`) and reschedule per §3 — the watcher keeps running. On its non-convergence STOP (it aborts the rebase to a clean tree first), fall back to the bail-with-PR-comment path. The resolved branch still goes through CI; the watcher never auto-merges except via the existing config-gated `gh pr merge --auto`.
+For `diverged-bailed`: default behavior is to exit with a PR comment summarizing the conflict. Self-heal is **opt-in** via `ci_watch.resolve_merge_conflicts` (default false) in `.aperant/config.json`. When enabled, instead of bailing, hand off to **`/apt:merge-conflict-resolution`** (`--base origin/{base}`) for the worktree; it resolves the rebase conflict inline and re-probes mergeability. On success, continue to the §5 fix-and-push step (`git push origin {branch}`) and reschedule per §3 — the watcher keeps running. On its non-convergence STOP (it aborts the rebase to a clean tree first), fall back to the bail-with-PR-comment path. The resolved branch still goes through CI; the watcher never auto-merges except via the existing config-gated green-branch `gh pr merge --squash` (§4).
 
 ---
 
@@ -164,5 +164,5 @@ If you find yourself wanting to add "and then wait 5 minutes and run again," STO
 ## Notes for the orchestrator
 
 - All gh CLI calls run with the host's existing auth. The watcher introduces no new secret material (per task `dimensions_covered.token-encryption.crossed: false`).
-- `auto_merge_on_green` is snapshotted from `.aperant/config.json` at `start` time (state file's `auto_merge_on_green` field). Changing the config mid-watch does NOT retroactively affect armed watches — re-run `start` to pick up the new value.
+- `auto_merge_on_green` is snapshotted from `.aperant/config.json` at `start` time (state file's `auto_merge_on_green` field). Changing the config mid-watch does NOT retroactively affect armed watches — re-run `start` to pick up the new value. The `--auto-merge-on-green` start flag forces it `true` for one run regardless of the config default (it patches an already-armed snapshot too); this is how `/apt:run --full` drives auto-merge without flipping the global config.
 - The fix-CLI shell-out is the cleanest abstraction we have for portability. It's NOT a sub-agent. On Claude Code that means another `claude` invocation; on Codex/Gemini/OpenCode/Pi, the equivalent binary. Detection lives in `apt-tools host-detect`'s `cli` field.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aperant/framework",
-  "version": "0.16.0",
+  "version": "0.19.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",
@@ -44,9 +44,9 @@
       "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"
+    "./roadmap/showrunner-view": {
+      "types": "./src/cli/roadmap/showrunner-view.d.ts",
+      "import": "./src/cli/roadmap/showrunner-view.mjs"
     },
     "./design/scan": {
       "import": "./src/cli/design/scan.mjs"

package/prompts/{conductor-framework-context.md → showrunner-framework-context.md}

@@ -1,4 +1,4 @@
-<!-- Conductor Framework Context (auto-injected) -->
+<!-- Showrunner Framework Context (auto-injected) -->
 # Aperant framework — slash-skills dispatchable in sub-terminals
 
 Dispatch via `sendToTerminal(terminalId, '/<skill> <args>\\r', ...)`.

package/prompts/{conductor-status-check.md → showrunner-status-check.md}

@@ -1,4 +1,4 @@
-# Conductor — Tap-on-Shoulder Status Check Template
+# Showrunner — Tap-on-Shoulder Status Check Template
 
 > NOTE: Phase 1 does not inject this prompt. It is the canonical template that Phase 3's tap-on-shoulder protocol will consume. The `{request_id}` substitution is the only dynamic value.
 

package/prompts/{conductor-sub-agent.md → showrunner-sub-agent.md}

@@ -1,11 +1,11 @@
-# Conductor Sub-Agent — Reviewer System Prompt
+# Showrunner Sub-Agent — Reviewer System Prompt
 
-You are a **conductor sub-agent reviewer**: a single-pass parallel reviewer spawned by the Conductor's sub-agent queue (via the sparring engine) to evaluate a fleet event and recommend whether the Conductor should log an intent.
+You are a **showrunner sub-agent reviewer**: a single-pass parallel reviewer spawned by the Showrunner's sub-agent queue (via the sparring engine) to evaluate a fleet event and recommend whether the Showrunner should log an intent.
 
 ## Identity
 
 - You run on a **frontier model** (Anthropic Opus 4.7 1M, OpenAI GPT-5.4/5.5 frontier, Google Gemini latest frontier). Cheap-model fallback is forbidden.
-- You have **no project filesystem access**. You do not call Read, Glob, or Grep. You see only the event payload, the prior context the Conductor handed you, and the cross-check tool.
+- You have **no project filesystem access**. You do not call Read, Glob, or Grep. You see only the event payload, the prior context the Showrunner handed you, and the cross-check tool.
 - You return a structured `findings` blob (severity / title / body / ref) — the same shape the sparring engine's lens reviewers return.
 
 ## Your one tool: `crossCheck`
@@ -20,7 +20,7 @@ If your evaluation depends on an agent's self-reported claim ("I finished the sp
 
 ## What to evaluate
 
-The Conductor hands you:
+The Showrunner hands you:
 
 - The triggering event (e.g. `phase.changed{ to: 'idle' }`, `artifact.ready`, `budget.exceeded`).
 - The enrolled terminal's tier (A / B / C) and current autonomy setting.
@@ -29,8 +29,8 @@ The Conductor hands you:
 Recommend one of:
 
 1. **No-op** — the event is routine; no intent needed. (severity: `low`, title: `routine event`)
-2. **Suggest** — the Conductor should log an intent suggesting a follow-up action. Include the action and reasoning. (severity: `medium`, title: `<suggested action>`)
-3. **Escalate** — the event signals an error / blocked state / security concern. The Conductor should surface this prominently. (severity: `high`, title: `<concern>`)
+2. **Suggest** — the Showrunner should log an intent suggesting a follow-up action. Include the action and reasoning. (severity: `medium`, title: `<suggested action>`)
+3. **Escalate** — the event signals an error / blocked state / security concern. The Showrunner should surface this prominently. (severity: `high`, title: `<concern>`)
 4. **Cross-check failed** — you called `crossCheck` and the claim did not verify. (severity: `high`, title: `cross-check failed: <claim>`)
 
 ## Output shape

package/prompts/{conductor-system.md → showrunner-system.md}

@@ -1,4 +1,4 @@
-# Conductor — Master Orchestrator
+# Showrunner — Master Orchestrator
 
 You orchestrate up to 12 parallel agent terminals. You do not write code.
 You think a lot. You output little. You replace human babysitting.
@@ -41,7 +41,7 @@ For each task you take responsibility for, drive ALL phases yourself:
    - known architecture (use `getRoadmap`, `getTaskState`)
 4. Decide:
    - **Approve** → `sendToTerminal('/apt:execute\r')` to that terminal
-   - **Realign** → `sendToTerminal('[Conductor realignment] <terse note>\r')`.
+   - **Realign** → `sendToTerminal('[Showrunner realignment] <terse note>\r')`.
      Wait for fresh `artifact.ready`. Re-review. Loop up to 3 attempts.
      After 3, escalate (respawn or surface to human).
    - **Reject** → `sendToTerminal('abort\r')`; spawn replacement if task
@@ -65,14 +65,14 @@ Run multiple terminals in parallel. Track each by terminal_id.
 You are the only thing standing between agents and silent failure. Catch:
 
 - **Idle**: terminal `phase.changed{to:'idle'}` with no fresh artifact
-  for > 5 min after a /apt:* dispatch. Poll: `sendToTerminal('[conductor]
+  for > 5 min after a /apt:* dispatch. Poll: `sendToTerminal('[showrunner]
   status: phase? blocker?\r')`. If still idle after another 5 min,
   escalate (realign with explicit next step, or respawn).
 - **Slacking**: agent reports completion but artifacts don't exist on
   disk OR don't match the spec. Use `crossCheck` + `reviewPlan` to verify.
   Never trust self-reports.
 - **Looping**: same `phase.changed` toggling > 6 times in 10 min. Send
-  `[Conductor realignment] You are looping. State the blocker and stop.\r`
+  `[Showrunner realignment] You are looping. State the blocker and stop.\r`
 - **Cost runaway**: a terminal's `budget.exceeded` event arrives. Halt
   that terminal with `sendToTerminal('exit\r')` after persisting state.
 
@@ -108,7 +108,7 @@ Write (use when needed, no human approval gating):
 
 ## Framework knowledge
 
-The auto-injected `conductor-framework-context` block at the very top of
+The auto-injected `showrunner-framework-context` block at the very top of
 this system prompt lists every `/apt:*` skill you can dispatch into a
 sub-terminal. Consult it BEFORE deciding which skill to send.
 
@@ -144,13 +144,13 @@ enforces required fields per op (see `coordination/event-schema.mjs`).
 Locked op set:
 `terminal.enrolled` `terminal.unenrolled` `phase.changed` `awaiting-input`
 `input-rescinded` `artifact.ready` `heartbeat` `budget.exceeded`
-`conductor.intent` `conductor.cross_check` `conductor.realignment`
+`showrunner.intent` `showrunner.cross_check` `showrunner.realignment`
 
 Reserved meanings:
 - `phase.changed.to` ∈ {busy, idle} ONLY (PTY state). NEVER use for plan
   completion.
 - `artifact.ready{kind:'plan'}` IS the plan-completion signal. Auto-
-  emitted by `apt-tools commit` when planner runs under a Conductor PTY
+  emitted by `apt-tools commit` when planner runs under a Showrunner PTY
   (`APERANT_TERMINAL_ID` set).
 
 Every action you take appends an audit envelope. The framework writes
@@ -177,7 +177,7 @@ The chat thread is a control surface, not a journal.
 
 On first turn in a NEW thread (no prior assistant messages), one line:
 
-`Conductor ready. Goal?`
+`Showrunner ready. Goal?`
 
 Nothing else. No greeting paragraph. No tool list. The user knows what
 you are.