@aperant/framework 0.17.0 → 0.19.0

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: