@aperant/framework 0.17.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

@@ -186,8 +186,8 @@ 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 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)"` | 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 | 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. |
@@ -195,6 +195,8 @@ 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.
@@ -224,7 +226,7 @@ Follow the envelope's `recommended_walk` / `prefer_self_resolving` for the rung
 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.17.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.

package/skills/apt/SKILL.md

@@ -17,7 +17,7 @@ execution_modes:
   - plan-mode
   - plan-only
   - research
-allowed-tools: "Bash, Read, Grep, Glob, Write, Edit, Task"
+allowed-tools: "Bash, Read, Grep, Glob, Task"
 argument-hint: "[free-text task or /apt <skill> …]"
 gates: []
 ---
@@ -234,12 +234,19 @@ Resolve the track, then create a fresh task record before invoking the skill.
    - `plan` → `STANDARD`
    - everything else with `task_context: create-new` → `STANDARD`
 
-Then run:
+Then run the deterministic allocator (NOT raw `task create`):
 
 ```bash
-node packages/framework/bin/apt-tools.mjs task create . --description "{slug}" --track {track} --autonomy {autonomy} [--scope {scope}]
+node packages/framework/bin/apt-tools.mjs task ensure . --description "{slug}" --intent create-new --track {track} --autonomy {autonomy} [--scope {scope}]
 ```
 
+`task ensure --intent create-new` is idempotent (re-running the same
+input returns the SAME task + worktree, `reused: true`) and resolves the
+effective autonomy from `config.autonomy.default` BEFORE provisioning the
+worktree — so allocation is host-agnostic and never depends on this prose
+being followed. The `allocation_intent` here is `create-new` because the
+skill's `task_context` is `create-new` (the four-value taxonomy maps 1:1).
+
 **Security note:** Do NOT interpolate `{skill_args}` directly into `--description "..."`. `skill_args` is verbatim user input and can contain double-quote characters that break out of the argument boundary and inject extra flags (e.g. `--autonomy`, `--scope`). The task slug is sufficient as the description; `skill_args` is passed to the skill separately after the task record is created.
 
 (Use `--scope framework` only when the user is on a framework-scoped task —
@@ -300,29 +307,41 @@ The router emitted a `classify` envelope. This is the main routing path —
 all free-text input and every flag-override (--quick/--deep/--debug) lands
 here.
 
-### Brainstorm hand-off (check FIRST, before picking a skill)
-
-**Before picking a skill from the envelope,** scan the user's input for
-signals that they want to *explore a vision* rather than *commit to a task*.
-If present, dispatch to `apt:discuss --brainstorm` and stop. Don't inline
-the exploration — the brainstorm posture lives in its own skill with its
-own fresh context and its own artifact shape.
-
-Signals — any one triggers the hand-off:
-- Vision statements: *"here's what I want to build"*, *"my goal is..."*, *"the idea is..."*
-- Open invitations: *"let's think about"*, *"let's brainstorm"*, *"help me figure out"*, *"what's the best way..."*
-- Paragraph-shaped input describing an outcome or direction, not a single work item
-- Explicit "before we plan, let's explore / think / brainstorm..."
-
-How to hand off:
-```
-[APT] Detected brainstorm intent — routing to /apt:discuss --brainstorm
-```
-Then invoke the `/apt:discuss --brainstorm` skill with the user's input and stop.
-
-**Task-shaped input (continue to Step 0):** concrete work item, specific
-deliverable, or existing task being continued. Examples: *"add OAuth login"*,
-*"fix the view-tracking bug"*, *"migrate reports to JSONB"*.
+### allocation_intent — the single LLM bit (decide FIRST, before picking a skill)
+
+The ONLY allocation judgment you make on the free-text path is a single
+schema-bounded `allocation_intent ∈ {create-new | require-existing |
+self-managed | none}` (the SAME four-value taxonomy as skill `task_context`).
+**Fail-closed default is `none`** — when in doubt, allocate nothing. There is
+no separate prose-only brainstorm gate that can bypass allocation; the
+brainstorm decision is just the `none` outcome of this one judgment.
+
+Map the user's input to one bit:
+
+- **`none`** — vision / exploration / investigation / status / help. The user
+  wants to *explore a vision* or *ask a question*, not commit to a work item.
+  Allocate NOTHING (no task, no worktree) and dispatch to `apt:discuss
+  --brainstorm` (or the picked investigative skill). Signals — any one →
+  `none`:
+  - Vision statements: *"here's what I want to build"*, *"my goal is..."*, *"the idea is..."*
+  - Open invitations: *"let's think about"*, *"let's brainstorm"*, *"help me figure out"*, *"what's the best way..."*
+  - Paragraph-shaped input describing an outcome or direction, not a single work item
+  - Explicit "before we plan, let's explore / think / brainstorm..."
+
+  How to hand off:
+  ```
+  [APT] allocation_intent=none (brainstorm/investigation) — routing to /apt:discuss --brainstorm
+  ```
+  Then invoke `/apt:discuss --brainstorm` with the user's input and stop.
+
+- **`self-managed`** — the picked skill owns its own task/worktree lifecycle
+  (e.g. `apt:run`, `apt:pr-review`). Allocate nothing here; let the skill do it.
+- **`require-existing`** — the user is continuing an existing task. Do NOT mint;
+  resolve the active task (Step 2 uses `task ensure --intent require-existing`).
+- **`create-new`** — concrete work item / specific deliverable that needs a
+  fresh task + worktree. Examples: *"add OAuth login"*, *"fix the view-tracking
+  bug"*, *"migrate reports to JSONB"*. Continue to Step 0; Step 2 provisions
+  deterministically via `task ensure --intent create-new`.
 
 ### Step 0a: Flag-override fast path (envelope.track is set)
 
@@ -332,6 +351,15 @@ carries `track`, `primary_skill`, `spawn_agent`, `agent`, and `options`.
 **Skip Step 0b and Step 0c — go straight to Step 1.** These were locked
 by the user typing `--quick` / `--deep` / `--debug`, not by the host LLM.
 
+**allocation_intent (flag-override is deterministic — no LLM judgment):**
+map `primary_skill` → `allocation_intent`:
+- `quick` → `create-new`
+- `debug` → `create-new`
+- `plan` → `create-new` (STANDARD / DEEP)
+- a skill whose `task_context` is `self-managed` (e.g. `run`) → `self-managed`
+
+Step 2 forwards this bit to `task ensure --intent <bit>`.
+
 ### Step 0b: Classify the skill (envelope.skills[] inline pick)
 
 When `classification.source: "host-model-deferred"` (free-text path),
@@ -405,15 +433,31 @@ Map choice: full auto → `execution_mode = "auto"`, step by step → `"step"`,
 
 If `needs_autonomy_prompt` is false (user passed --yolo/--autonomous), skip this — use `execution_mode` from route result.
 
-### Step 2: Register Task
+### Step 2: Register Task (deterministic allocation)
+
+Forward the `allocation_intent` decided above (Step 0a flag-override map,
+or the free-text bit from the allocation_intent section) to the
+deterministic, idempotent allocator — NOT raw `task create`:
 
 ```bash
-node packages/framework/bin/apt-tools.mjs task create . --description "{task_description}" --track {track} --autonomy {autonomy}
+node packages/framework/bin/apt-tools.mjs task ensure . --description "{task_description}" --intent {allocation_intent} --track {track} --autonomy {autonomy}
 ```
 
+- `--intent create-new` provisions a fresh task + worktree, idempotent on
+  re-run (`reused: true` returns the SAME task/worktree — re-issuing `/apt`
+  never duplicates). Effective autonomy is resolved from
+  `config.autonomy.default` BEFORE the worktree hook, so a
+  `from_branch: current` base is not spuriously deferred.
+- `--intent require-existing` resolves the active task WITHOUT minting
+  (returns `requires_input` on ambiguity — fall back to the
+  skill-passthrough resolution chain prompt).
+- `--intent none` / `--intent self-managed` allocate nothing
+  (`allocated: false`) — you should already have dispatched per the
+  allocation_intent section above and not reached Step 2.
+
 Parse `task_id`, `task_dir`, and (if present) `worktree.worktree_path` / `worktree.branch` / `worktree.base_branch` from the result.
 
-**Task-level worktree isolation:** when `task_isolation.worktree_per_task` is enabled (check via `host_capabilities.worktrees` + `task_isolation` in the route result) and `task create` returns a `worktree` block, every subsequent Bash call AND every spawned agent in this pipeline MUST use `worktree_path` as its working directory. Print:
+**Task-level worktree isolation:** when `task_isolation.worktree_per_task` is enabled (check via `host_capabilities.worktrees` + `task_isolation` in the route result) and `task ensure` returns a `worktree` block, every subsequent Bash call AND every spawned agent in this pipeline MUST use `worktree_path` as its working directory. Print:
 
 ```
 [APT] Working in isolated worktree: {worktree_path}
@@ -424,7 +468,7 @@ Important nuances:
 - `task_dir` is an **absolute path** under the main repo's `.aperant/tasks/{task-id}/`. All spec/plan/progress artifacts live there and are shared across worktrees.
 - `apt-tools` commands still receive the **project root** as `<project-dir>` — they coordinate state through the main repo's `.aperant/`. The worktree only affects *code editing* cwd.
 - When spawning an agent, set its `cwd` (or prefix its Bash calls with `cd {worktree_path} &&`) to the worktree for code reads/edits. Pass `worktree_path` in the agent's context so it knows where code work happens.
-- Planner artifact safety: do **not** spawn `apt-planner` with host-level worktree isolation that gives it a separate copied repo. The planner must write `spec.md` and `implementation_plan.json` to the absolute main-repo `task_dir` from `task create`; `.aperant/tasks/**` is gitignored, so artifacts written under a disposable worktree can be invisible to git and lost when that worktree is cleaned.
+- Planner artifact safety: do **not** spawn `apt-planner` with host-level worktree isolation that gives it a separate copied repo. The planner must write `spec.md` and `implementation_plan.json` to the absolute main-repo `task_dir` from `task ensure`; `.aperant/tasks/**` is gitignored, so artifacts written under a disposable worktree can be invisible to git and lost when that worktree is cleaned.
 - If no `worktree` block is returned, proceed in the project root as before.
 
 ### Step 3: Spawn Planner Agent
@@ -482,14 +526,44 @@ tally output. Skip silently if tokens tally errors — never block the
 pipeline on telemetry.
 
 **If `spawn_agent` is false (QUICK or DEBUG):**
-Both QUICK and DEBUG resolve here (single-shot, no spawned phase agent). Invoke
-the picked skill (`apt:quick` for QUICK, `apt:debug` for DEBUG, per
-`primary_skill`) directly with `task_id`, `task_dir`, AND `worktree_path` in its
-skill context — Step 2 already created the worktree + printed the banner for this
-track, so thread `worktree_path` the same way the `spawn_agent: true` branch
-threads it into the planner. No phase marker — QUICK and DEBUG are both
-single-shot here. (If Step 2 returned no `worktree` block, pass `worktree_path` as
-"none" and the skill proceeds in the project root.)
+Both QUICK and DEBUG resolve here (single-shot, no spawned phase agent).
+
+**The router itself CANNOT edit code.** Its frontmatter `allowed-tools` is
+`Bash, Read, Grep, Glob, Task` — it has NO `Write` / `Edit` tool. This is the
+load-bearing boundary (ID-05): the router can classify, allocate
+(`task ensure`), and dispatch, but it can never edit a file on `main`.
+
+So do NOT edit inline. **INVOKE the `apt:quick` / `apt:debug` SKILL** (per
+`primary_skill`) AFTER Step 2's `task ensure --intent create-new` has
+provisioned the worktree. Invoking the skill establishes that skill's OWN
+`allowed-tools` scope (`apt-quick` / `apt-debug` both carry
+`Read, Write, Edit, Bash, Grep, Glob`), which RE-GRANTS the edit affordance —
+but only once a worktree exists, so editing can never land on `main` through
+the router. Pass `task_id`, `task_dir`, AND `worktree_path` into the invoked
+skill's context (thread `worktree_path` the same way the `spawn_agent: true`
+branch threads it into the planner). This is a SKILL invocation, NOT a `Task`
+sub-agent spawn — QUICK/DEBUG stay single-agent/single-context, so the Fast
+Path Guarantee is preserved. No phase marker. (If Step 2 returned no `worktree`
+block, pass `worktree_path` as "none" and the skill proceeds in the project
+root.)
+
+> **inline vs skill-scope (read this).** "Inline" here means the OLD behavior:
+> the router editing within its own `/apt` turn under the router's allowlist.
+> That is gone — the router has no edit tool. "Skill-scope" is the NEW
+> behavior: a genuine `apt:quick` / `apt:debug` invocation whose own
+> `allowed-tools` re-grants `Write, Edit` for the edit work, after the worktree
+> exists.
+>
+> **Residual (host-runtime, not CI-provable — founder smoke-test gate).**
+> Whether Claude Code treats a nested skill's `allowed-tools` as a REPLACEMENT
+> (re-grants edit — design holds) or as an INTERSECTION/ceiling (the parent
+> router allowlist caps the child — Fast Path breaks) is a host-implementation
+> property that cannot be unit-tested from the framework. CI proves the
+> frontmatter/prose structure; a founder in-app smoke-test is the residual gate.
+> **Fallback if the smoke-test shows breakage:** revert ONLY the
+> router-frontmatter line (re-add `Write, Edit`). The host-agnostic
+> `task ensure` boundary (ID-02) still fixes the on-`main`-edit bug; the
+> allowed-tools removal is hardening, not the fix.
 
 ### Step 4: Chain Pipeline (based on selected option)