@aperant/framework 0.16.0 → 0.19.0

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)
 

package/skills/apt-debug/SKILL.md

@@ -42,7 +42,7 @@ reproduction, so loading this appendix is non-trivial.
 - **apt-tools path:** `node packages/framework/bin/apt-tools.mjs` or the locally installed `apt-tools` binary
 - **Constitution:** Read `AGENTS.md` in the project root if it exists
 - **Debug sessions:** `.aperant/debug/{session-id}/DEBUG.md`
-- **Task-level worktree isolation:** A worktree is provisioned at session start by `task create` (track-agnostic — DEBUG gets one too; parsed + banner-announced in §1a) when `task_isolation.worktree_per_task` is enabled. Read-only investigation (Sections 2-3 Observe / Hypothesize — `git log`, `git diff`, Grep, Read) may run from EITHER cwd; they only read. But once code changes begin — Section 4 (Checkpoint), Section 5b (Execute Test — the minimal change), Section 6b (Implement Fix + commit) — run those Bash commands with `cd {worktree_path} &&` so the fix + checkpoint commits land on the worktree's task branch. Use the `worktree_path` the router passed in skill context or that §1a parsed from `task create`'s envelope. `apt-tools` calls always take the project root as `<project-dir>`. If no `worktree` block was returned, proceed in the project root as before.
+- **Task-level worktree isolation:** A worktree is provisioned at session start by `task ensure` (track-agnostic — DEBUG gets one too; parsed + banner-announced in §1a) when `task_isolation.worktree_per_task` is enabled. Read-only investigation (Sections 2-3 Observe / Hypothesize — `git log`, `git diff`, Grep, Read) may run from EITHER cwd; they only read. But once code changes begin — Section 4 (Checkpoint), Section 5b (Execute Test — the minimal change), Section 6b (Implement Fix + commit) — run those Bash commands with `cd {worktree_path} &&` so the fix + checkpoint commits land on the worktree's task branch. Use the `worktree_path` the router passed in skill context or that §1a parsed from `task ensure`'s envelope. `apt-tools` calls always take the project root as `<project-dir>`. If no `worktree` block was returned, proceed in the project root as before.
 </your_environment>
 
 <state_files>
@@ -71,35 +71,25 @@ If resuming, read DEBUG.md and skip to the current phase (observe/hypothesize/te
 
 ### 1a. Resolve canonical task id (idempotent — new sessions only)
 
-DEBUG now produces a canonical state.active_tasks record so `/apt:ship` can find the task via the lite ship profile once the fix is committed. The body owns idempotency because `apt-tools task create` does NOT guard against existing ids (see spec §3 R8).
+DEBUG now produces a canonical state.active_tasks record so `/apt:ship` can find the task via the lite ship profile once the fix is committed. Idempotency is owned by the deterministic allocator `apt-tools task ensure --intent create-new` (NOT raw `task create`) — re-running returns the SAME task + worktree (`reused: true`), so the old `task get` guard dance is gone.
 
 Two invocation paths converge here:
 
-- **Router path** (`/apt` → `/apt:debug`): the router has already called `task create` and injected `task_id` into your skill context.
-- **Direct path** (`/apt:debug foo`): no `task_id` in context — you create one now.
+- **Router path** (`/apt` → `/apt:debug`): the router has already run `task ensure --intent create-new` and injected `task_id` (+ `worktree_path`) into your skill context. Re-affirm idempotently with the same id and adopt `task_id` as `{session-id}`:
+  ```bash
+  apt-tools task ensure . --description "$ARGUMENTS" --intent create-new --track DEBUG --id {task_id}
+  ```
+  The `--id {task_id}` makes ensure resolve to the EXACT record the router just provisioned (`reused: true`) — no second task, no second worktree.
 
-Sequence:
+- **Direct path** (`/apt:debug foo`): no `task_id` in context — allocate now:
+  ```bash
+  apt-tools task ensure . --description "$ARGUMENTS" --intent create-new --track DEBUG
+  ```
+  Parse the generated `task_id` from the envelope and adopt it as `{session-id}`. ensure is keyed on the normalized description + scope, so a retry returns the SAME canonical id (replacing the legacy `debug-YYYYMMDD-HHmm` form).
 
-1. **If `task_id` is present in skill context** (router path):
-   ```bash
-   apt-tools task get . --id {task_id}
-   ```
-   - If exit 0 AND the returned record has `track === "DEBUG"` → reuse, skip the create call. Adopt `task_id` as `{session-id}`.
-   - Else (record missing OR wrong track) → call:
-     ```bash
-     apt-tools task create . --description "$ARGUMENTS" --track DEBUG --id {task_id}
-     ```
-     Adopt the id as `{session-id}`.
-
-2. **If no `task_id` in skill context** (direct path):
-   ```bash
-   apt-tools task create . --description "$ARGUMENTS" --track DEBUG
-   ```
-   Parse the generated `task_id` from the envelope and adopt it as `{session-id}`. The canonical id replaces the legacy `debug-YYYYMMDD-HHmm` form.
-
-The debug working dir at `.aperant/debug/{session-id}/` stays — that working artifact is preserved (per spec §3 R7). The canonical task record at `.aperant/tasks/{task-id}/` is created in parallel by `task create`, and both share the same id.
+The debug working dir at `.aperant/debug/{session-id}/` stays — that working artifact is preserved (per spec §3 R7). The canonical task record at `.aperant/tasks/{task-id}/` is created in parallel by `task ensure`, and both share the same id.
 
-**Worktree isolation (both paths).** `task create` provisions a worktree when `task_isolation.worktree_per_task` is enabled (track-agnostic — DEBUG gets one too). Parse `worktree.worktree_path`, `worktree.branch`, and `worktree.base_branch` from the `task create` envelope (direct path); on the router path the orchestrator already passed `worktree_path` into your skill context — use that. When a `worktree` block is present, print the banner:
+**Worktree isolation (both paths).** `task ensure --intent create-new` provisions a worktree when `task_isolation.worktree_per_task` is enabled (track-agnostic — DEBUG gets one too). Parse `worktree.worktree_path`, `worktree.branch`, and `worktree.base_branch` from the `task ensure` envelope (direct path); on the router path the orchestrator already passed `worktree_path` into your skill context — use that. When a `worktree` block is present, print the banner:
 
 ```
 [APT] Working in isolated worktree: {worktree_path}

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

@@ -1,6 +1,6 @@
 ---
 name: apt:fan-out
-description: "Cross-task fan-out — spawn N apt-executor workers from one conductor terminal, each in its own worktree"
+description: "Cross-task fan-out — spawn N apt-executor workers from one Showrunner terminal, each in its own worktree"
 apt-skill-version: {{APT_VERSION}}
 stage: execute
 intent: x-fan-out
@@ -19,7 +19,7 @@ argument-hint: "apt:fan-out --tasks <id,id,id> [--phases <m/p,m/p>] [--unblocked
 gates: []
 ---
 <objective>
-Run N pre-planned Aperant tasks concurrently from one conductor terminal. This skill is a thin orchestrator over the generalized wave engine (`unit_kind: "task"` path, see ADR-0003) and the existing primitives: `apt-tools worktree create --task`, `apt-tools lock claim`, `apt-tools event append`, and the `parallelization.max_tasks` quota. No daemon, no job queue, no in-skill scheduling. The host CLI's main thread is the conductor (ADR-0001); each spawned apt-executor subagent runs in its own worktree (ADR-0002).
+Run N pre-planned Aperant tasks concurrently from one Showrunner terminal. This skill is a thin orchestrator over the generalized wave engine (`unit_kind: "task"` path, see ADR-0003) and the existing primitives: `apt-tools worktree create --task`, `apt-tools lock claim`, `apt-tools event append`, and the `parallelization.max_tasks` quota. No daemon, no job queue, no in-skill scheduling. The host CLI's main thread is the Showrunner (ADR-0001); each spawned apt-executor subagent runs in its own worktree (ADR-0002).
 
 This is the "I have 16 unblocked tasks in this phase, run them all" surface. It replaces the old workaround of opening 16 sibling terminals manually.
 </objective>
@@ -160,7 +160,7 @@ call `integrate` with the batch's task list (or `--batch ${batch_id}` to recover
 it from the worker rows):
 
 ```bash
-git -C "$conductor_root" fetch origin "$base_branch"
+git -C "$showrunner_root" fetch origin "$base_branch"
 node packages/framework/bin/apt-tools.mjs merge integrate . --tasks ${task_ids_csv}
 # OR recover the task list from the batch's worker rows:
 node packages/framework/bin/apt-tools.mjs merge integrate . --batch ${batch_id}
@@ -213,7 +213,7 @@ Mix SHIPPED / BLOCKED / in-flight variants in the same rail. Below the panel, em
 
 ## Design references
 
-- **ADR-0001** — Host CLI main thread is the conductor; no daemon, no in-skill queue.
+- **ADR-0001** — Host CLI main thread is the Showrunner; no daemon, no in-skill queue.
 - **ADR-0002** — One worktree per task; workers run independent feature branches.
 - **ADR-0003** — Wave engine accepts `unit_kind: "task"` so cross-task fan-out reuses the same primitives as intra-task subtask waves.
 

package/skills/apt-handoff/SKILL.md

@@ -23,7 +23,7 @@ Compact the current conversation into a HANDOFF document so a different agent
 
 Writes the handoff to `.aperant/handoffs/{id}/HANDOFF.md` (or `{task_dir}/handoffs/{id}/HANDOFF.md` when inside a routed task) so the artifact lives with the repo, survives across machines, and is discoverable by `/apt:resume` and team-status tooling.
 
-**Use when:** an agent decides to transfer the work mid-flight. Examples — sender hit context-budget cap, the next phase needs a different model (e.g. Codex for a heavy refactor), a fan-out conductor is sharding scope to peers, or a planning agent is handing a locked plan to an executor.
+**Use when:** an agent decides to transfer the work mid-flight. Examples — sender hit context-budget cap, the next phase needs a different model (e.g. Codex for a heavy refactor), a fan-out Showrunner is sharding scope to peers, or a planning agent is handing a locked plan to an executor.
 
 **Do NOT use when:**
 - The human operator wants to stop — use `/apt:pause` (it stashes uncommitted work and updates `CONTINUE_INDEX.md`).

package/skills/apt-plan/SKILL.md

@@ -504,13 +504,13 @@ node packages/framework/bin/apt-tools.mjs commit "plan: create implementation pl
 ## 8a. Runtime-context adapters
 
 If `APERANT_TERMINAL_ID` is set (you are running under the Aperant
-Conductor — a master-orchestrator agent inside the Aperant app), see
-`adapters/conductor.md` for the plan-review handshake convention
-(`proceed` / `abort` / `[Conductor realignment]` stdin strings) the
-Conductor's drawer uses post-commit. The `artifact.ready{kind:'plan'}`
+Showrunner — a master-orchestrator agent inside the Aperant app), see
+`adapters/showrunner.md` for the plan-review handshake convention
+(`proceed` / `abort` / `[Showrunner realignment]` stdin strings) the
+Showrunner's drawer uses post-commit. The `artifact.ready{kind:'plan'}`
 signal itself is now emitted automatically by the `apt-tools commit`
 postcondition — no manual emit step required. Native invocations
-(Claude Code, Gemini, OpenCode, Codex with no Conductor context) can
+(Claude Code, Gemini, OpenCode, Codex with no Showrunner context) can
 skip the adapter entirely and proceed to Section 9.
 
 ## 9. Report

package/skills/apt-plan/adapters/{conductor.md → showrunner.md}

@@ -1,23 +1,23 @@
-# apt-plan adapter — Aperant Conductor
+# apt-plan adapter — Aperant Showrunner
 
 This adapter is **only loaded** when the planner runs under the Aperant
-Conductor (a master-orchestrator agent inside the Aperant desktop / web
+Showrunner (a master-orchestrator agent inside the Aperant desktop / web
 app). Native invocations of `/apt:plan` (from plain Claude Code, Gemini
 CLI, OpenCode, or Codex) IGNORE this file entirely — the framework
 behavior in `SKILL.md` is the source of truth for them.
 
 ## When to load this adapter
 
-Detect Conductor context by env var:
+Detect Showrunner context by env var:
 
 ```bash
 [ -n "$APERANT_TERMINAL_ID" ]
 ```
 
-The Conductor injects `APERANT_TERMINAL_ID` into every PTY it spawns.
-If the var is unset, you are NOT under the Conductor — stop reading.
+The Showrunner injects `APERANT_TERMINAL_ID` into every PTY it spawns.
+If the var is unset, you are NOT under the Showrunner — stop reading.
 
-## What changes under the Conductor
+## What changes under the Showrunner
 
 The planner's filesystem outputs (`spec.md`, `implementation_plan.json`)
 are unchanged. The ADDITION is one extra step after Section 8 (Persist
@@ -34,7 +34,7 @@ node packages/framework/bin/apt-tools.mjs commit "plan: ..." \
   --files spec.md implementation_plan.json
 ```
 
-…and the process is running under a Conductor PTY (env
+…and the process is running under a Showrunner PTY (env
 `APERANT_TERMINAL_ID` is set), `apt-tools commit` auto-emits a fully-
 formed `artifact.ready` envelope to `.aperant/events/{today}.jsonl`.
 The envelope carries the `task_id`, plan path, sha256 hash, and the
@@ -47,35 +47,35 @@ framework postcondition makes it work uniformly across QUICK, STANDARD,
 DEEP, and COMPLEX without violating the Fast Path Guarantee.
 
 **Planner authors don't need to do anything.** As long as you call
-`apt-tools commit` to land your plan artifacts, the Conductor will
+`apt-tools commit` to land your plan artifacts, the Showrunner will
 see `artifact.ready` and the drawer's PlanReadyCard will auto-promote.
 
 If the planner does NOT use `apt-tools commit` (it lands the plan via
 raw `git commit` or `git add`), the auto-emit will not fire. In that
-case the Conductor falls back to filesystem polling of the task dir
+case the Showrunner falls back to filesystem polling of the task dir
 (slightly higher latency, same outcome).
 
-### Plan-review handshake (Step 6 + 7 of Conductor v2)
+### Plan-review handshake (Step 6 + 7 of Showrunner v2)
 
 After emitting `artifact.ready{kind:'plan'}` the planner SHOULD pause at
-an idle prompt and listen for ONE of three Conductor-driven inputs:
+an idle prompt and listen for ONE of three Showrunner-driven inputs:
 
 - `proceed\r` — the human (via the PlanReadyCard's **Approve** button)
   approves the plan. Continue to `/apt:execute` as you would in the
   normal flow.
 - `abort\r` — the human rejected. Abandon this plan; do not start
   execution. Optionally exit the session cleanly.
-- `[Conductor realignment] <note>\r` — the human pressed **Realign**.
+- `[Showrunner realignment] <note>\r` — the human pressed **Realign**.
   Treat the `<note>` as additional planning context: re-open spec.md /
   implementation_plan.json, address the note's gaps, commit a new
   revision, and emit a fresh `artifact.ready{kind:'plan'}` (with the
   same task_id but a NEW request_id — the drawer keys cards on
   request_id, so re-using it would suppress the new card). The
-  realignment loop can repeat; after attempt_n >= 3 the Conductor may
+  realignment loop can repeat; after attempt_n >= 3 the Showrunner may
   decide to respawn the terminal entirely.
 
-These exact strings are pinned by the Conductor's `ConductorContextHost`
-handlers (`packages/ui/src/sections/conductor/ConductorContextHost.tsx`).
+These exact strings are pinned by the Showrunner's `ShowrunnerContextHost`
+handlers (`packages/ui/src/sections/showrunner/ShowrunnerContextHost.tsx`).
 Native CLI invocations of `/apt:plan` (no `APERANT_TERMINAL_ID`) skip
 this handshake and follow the normal report → `/apt:execute` flow.
 
@@ -84,7 +84,7 @@ this handshake and follow the normal report → `/apt:execute` flow.
 The Aperant Framework is consumed by multiple CLIs (Claude Code, Gemini,
 OpenCode, Codex) and by the Aperant app itself. The vast majority of
 `/apt:plan` invocations come from native CLIs — those should not see
-or execute Conductor-specific machinery. By isolating the Conductor's
+or execute Showrunner-specific machinery. By isolating the Showrunner's
 event-emit obligations to this adapter, the public skill stays minimal
 and the framework remains CLI-agnostic. The pattern mirrors
 `appendices/` (reasoning-stance loaders) but with a different semantic: