@aperant/framework 0.16.0 → 0.19.0

package/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/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/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/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/src/cli/commands/ci-watch.mjs

@@ -154,12 +154,60 @@ function doStart(root, flags) {
 	const taskId = flags.get('task-id')
 	if (!taskId) return err('Required: --task-id <id>')
 	const host = flags.get('host') || 'unknown'
+	// Per-run auto-merge override (ID-08): --auto-merge-on-green forces
+	// auto_merge_on_green:true on the new snapshot AND patches an already-armed
+	// watch instead of no-opping, because `/apt:run --full` runs ship's
+	// config-driven arm (default false) FIRST, then this call to guarantee
+	// auto-merge for this single run without persisting ci_watch.auto_merge_on_green.
+	const forceAutoMerge = flags.has('auto-merge-on-green')
 
 	// Refuse to start a second watcher for the same PR — exit 2 with a
 	// busy envelope so the caller knows the PR is already armed. The
 	// orchestrator skill prints the holder's session and exits.
 	const existingState = readState(root, pr)
 	if (existingState && !existingState.error) {
+		// --auto-merge-on-green on an already-armed watch PATCHES the snapshot's
+		// auto_merge_on_green to true and returns armed (NOT a busy no-op), so the
+		// --full chain can force auto-merge after ship's default-false config arm.
+		if (forceAutoMerge) {
+			const patchSessionId = newSessionId()
+			const patchLock = acquireLock(root, pr, patchSessionId)
+			if (patchLock.status !== 'ok') {
+				return exitWith(
+					{
+						status: 'busy',
+						command: 'ci-watch-start',
+						pr: Number(pr),
+						reason: 'lock-held',
+						holder: patchLock.holder,
+					},
+					2,
+				)
+			}
+			try {
+				// Re-read INSIDE the lock so a concurrent tick's attempts/deadline/
+				// last_poll update is not clobbered by the stale pre-lock snapshot.
+				// Mirrors the main start path below, which also re-reads under the
+				// lock before writing.
+				const current = readState(root, pr)
+				const base = current && !current.error ? current : existingState
+				const patched =
+					base.auto_merge_on_green === true ? base : { ...base, auto_merge_on_green: true }
+				if (patched !== base) writeState(root, pr, patched)
+				return ok({
+					status: 'ok',
+					command: 'ci-watch-start',
+					pr: Number(pr),
+					host: base.host,
+					scheduler_handle: patched.scheduler_handle ?? null,
+					deadline: patched.deadline,
+					auto_merge_on_green: true,
+					patched: patched !== base,
+				})
+			} finally {
+				releaseLock(root, pr, patchSessionId)
+			}
+		}
 		return exitWith(
 			{
 				status: 'busy',
@@ -202,8 +250,9 @@ function doStart(root, flags) {
 		const startedAt = existingObj.started_at || nowIso()
 		const deadline = existingObj.deadline || new Date(Date.now() + WALL_BUDGET_MS).toISOString()
 		// Snapshot auto_merge from config at start so config changes mid-watch don't
-		// surprise the orchestrator (spec.md §8).
-		const autoMergeFromConfig = readAutoMergeFromConfig(root)
+		// surprise the orchestrator (spec.md §8). --auto-merge-on-green forces it
+		// true for this run regardless of the config default (ID-08).
+		const autoMergeFromConfig = forceAutoMerge || readAutoMergeFromConfig(root)
 		const state = {
 			pr: Number(pr),
 			task_id: taskId,

package/src/cli/commands/commit.mjs

@@ -49,10 +49,10 @@ export function cmdCommit(args) {
 		return err(`Commit failed: ${e.message}`)
 	}
 
-	// Conductor v2 (post live verification 2026-05-15) — auto-emit
+	// Showrunner v2 (post live verification 2026-05-15) — auto-emit
 	// `artifact.ready{kind:'plan'}` when the commit landed a fresh
 	// `implementation_plan.json` under .aperant/tasks/{id}/ AND the
-	// process runs under a Conductor PTY (APERANT_TERMINAL_ID set).
+	// process runs under a Showrunner PTY (APERANT_TERMINAL_ID set).
 	// Code-enforced replacement for the markdown-discipline emit step
 	// that QUICK-track tasks correctly skipped per Fast Path Guarantee.
 	// Best-effort: emit failures do NOT roll back the commit.
@@ -66,7 +66,7 @@ export function cmdCommit(args) {
 			)
 		}
 	} catch {
-		// Non-fatal — the commit succeeded. The Conductor will fall back
+		// Non-fatal — the commit succeeded. The Showrunner will fall back
 		// to filesystem polling (slightly higher latency, same outcome).
 	}
 

package/src/cli/commands/event.mjs

@@ -6,7 +6,7 @@ import { appendFileSync, mkdirSync, readdirSync, readFileSync, writeFileSync } f
 import { hostname } from 'node:os'
 import { join, resolve } from 'node:path'
 import { readLifecycleEventsForDay } from '../coordination/event-log.mjs'
-import { validateConductorEvent } from '../coordination/event-schema.mjs'
+import { validateShowrunnerEvent } from '../coordination/event-schema.mjs'
 import { createCoordinationStore } from '../coordination/store.mjs'
 import { parseFlags } from '../util/args.mjs'
 import { err, ok } from '../util/result.mjs'
@@ -28,8 +28,8 @@ const VALID_EVENT_TYPES = [
 	'ci-watch.tick',
 	'ci-watch.fix-pushed',
 	'ci-watch.stopped',
-	// Phase 2.5 — Conductor-readable ops emitted by APT skills so the
-	// Conductor's readEventLog tool can drive its observe loop. These
+	// Phase 2.5 — Showrunner-readable ops emitted by APT skills so the
+	// Showrunner's readEventLog tool can drive its observe loop. These
 	// events route to JSONL (like ci-watch.*) and carry terminal_id
 	// auto-stamped from APERANT_TERMINAL_ID when present.
 	'phase.changed',
@@ -40,9 +40,9 @@ const VALID_EVENT_TYPES = [
 	'budget.exceeded',
 	'terminal.enrolled',
 	'terminal.unenrolled',
-	'conductor.intent',
-	'conductor.cross_check',
-	'conductor.realignment',
+	'showrunner.intent',
+	'showrunner.cross_check',
+	'showrunner.realignment',
 ]
 
 const CI_WATCH_EVENT_TYPES = new Set([
@@ -52,7 +52,7 @@ const CI_WATCH_EVENT_TYPES = new Set([
 	'ci-watch.stopped',
 ])
 
-const CONDUCTOR_EVENT_TYPES = new Set([
+const SHOWRUNNER_EVENT_TYPES = new Set([
 	'phase.changed',
 	'artifact.ready',
 	'awaiting-input',
@@ -61,9 +61,9 @@ const CONDUCTOR_EVENT_TYPES = new Set([
 	'budget.exceeded',
 	'terminal.enrolled',
 	'terminal.unenrolled',
-	'conductor.intent',
-	'conductor.cross_check',
-	'conductor.realignment',
+	'showrunner.intent',
+	'showrunner.cross_check',
+	'showrunner.realignment',
 ])
 
 /**
@@ -142,22 +142,22 @@ export function cmdEvent(subcommand, projectDir, extraArgs) {
 				return ok({ status: 'ok', command: 'event-append', event_file: jsonlFile, event })
 			}
 
-			// Phase 2.5 — Conductor-readable events route to the per-day JSONL
-			// path with the canonical envelope the Conductor's readEventLog
+			// Phase 2.5 — Showrunner-readable events route to the per-day JSONL
+			// path with the canonical envelope the Showrunner's readEventLog
 			// expects: { t, agent, pid, hostname, incarnation, op, task, data }.
 			// terminal_id is auto-stamped from APERANT_TERMINAL_ID env when set,
-			// so APT skills running in a Conductor-spawned PTY automatically
+			// so APT skills running in a Showrunner-spawned PTY automatically
 			// tag their events with the originating terminal.
-			if (CONDUCTOR_EVENT_TYPES.has(type)) {
+			if (SHOWRUNNER_EVENT_TYPES.has(type)) {
 				const terminalId = process.env.APERANT_TERMINAL_ID
 				if (terminalId && data && typeof data === 'object' && !data.terminal_id) {
 					data.terminal_id = terminalId
 				}
 				// Step 1 — schema gate: reject payloads that violate the per-op
 				// contract before the line lands on disk. The same validator
-				// runs at the framework store seam and the core conductor
+				// runs at the framework store seam and the core showrunner
 				// writer; gating here catches CLI emitters (APT skills).
-				const validation = validateConductorEvent(type, data)
+				const validation = validateShowrunnerEvent(type, data)
 				if (!validation.ok) {
 					return err(`Schema violation for ${type}: ${validation.error}`)
 				}

package/src/cli/commands/merge-integrate.mjs

@@ -8,7 +8,7 @@
  * exist, else stable by task id), and probes each branch's mergeability against
  * the CURRENT base via the EXACT same `git merge-tree` detection the `detect`
  * subcommand uses (#395). It emits a structured integration report the
- * conductor renders and the `apt:merge-conflict-resolution` flow consumes for
+ * showrunner renders and the `apt:merge-conflict-resolution` flow consumes for
  * any conflicted branch.
  *
  * READ-ONLY, like `detect`/`markers`: NO `git merge`, NO `git rebase`, NO index
@@ -33,7 +33,7 @@
  *   apt-tools merge integrate <project-dir> --batch <batch-id>  [--base <ref>]
  *
  * --tasks   Explicit canonical task-id list (what `fan-out resolve` returns and
- *           the conductor already holds). Primary form.
+ *           the showrunner already holds). Primary form.
  * --batch   Recover the task-id list from the batch's worker rows
  *           `.aperant/team-status/fanout-<batch>-<task>.json` (the agent-id
  *           format fan-out.mjs spawns workers with: `fanout-${batch}-${task}`).
@@ -291,7 +291,7 @@ export function mergeIntegrate(targetDir, extraArgs) {
 		const task = state?.active_tasks?.[id] || null
 
 		// Tasks with no shipped branch can't be integrated — record them so the
-		// conductor sees why, but never block the rest of the batch.
+		// showrunner sees why, but never block the rest of the batch.
 		if (!task) {
 			needsHuman++
 			tasks.push({ task_id: id, status: 'unknown', reason: 'task not found in state.json' })