@aperant/framework 0.17.0 → 0.20.0

package/dist/plugin/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 ensure`, 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 create`, 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}
@@ -301,6 +291,14 @@ Document the root cause clearly:
 cd {worktree_path} && node packages/framework/bin/apt-tools.mjs commit "fix: {concise description of fix}" --files {changed-files}
 ```
 
+After the commit, emit the registry delta (one non-blocking command):
+
+```bash
+node packages/framework/bin/apt-tools.mjs features-reconcile . --draft --task-id {task-id} || true
+```
+
+Stage `.aperant/features/deltas/` with the commit; fill any `needs-disposition` field (usually `no-semantic-change` + a one-line reason).
+
 ### 6c. Update Status
 
 ```markdown

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

@@ -373,38 +373,47 @@ node packages/framework/bin/apt-tools.mjs audit pending-artifacts . --stage
 - **`unknown[]` non-empty** → HARD STOP. A path under `.aperant/` is not classified. Treat as a planner gap — the subtask touched state that the contract does not know about. Write the decision to `{task_dir}/execution-decisions.md` (decision class: `classification-gap`), then either extend `packages/framework/src/cli/artifacts/classification.mjs` inline (if the subtask already modifies framework code) or open a follow-up task (if the drift is orthogonal). Do NOT proceed to the next subtask until the envelope returns `clean`.
 - **Envelope status == `clean`** → proceed to 3e-features.
 
-### 3e-features. Features Registry Post-Step (C33)
+### 3e-features. Feature-Registry Delta Emit
 
-After the subtask commits, run `features-audit --apply-stubs` so any
-newly-added UI/core/hook/IPC file in the diff lands in
-`.aperant/features/<area>.json` automatically. The reviewer Pass 6 covers
-whatever the post-step missed; running it here closes the gap where
-executor commits introduce a new feature surface without registering it.
+After the subtask commits, emit this subtask's registry DELTA — semantic
+capture happens HERE, while the build context is still in your window.
+`/apt:ship` §0.0 materializes all pending deltas into the area JSONs +
+a receipt later; you only record what changed and what it means.
 
 ```bash
-node packages/framework/bin/apt-tools.mjs features-audit . \
-  --task-id "$TASK_ID" \
-  --diff-files "$(git diff --name-only HEAD^ HEAD | tr '\n' ',')" \
-  --apply-stubs
+node packages/framework/bin/apt-tools.mjs features-reconcile . \
+  --draft --task-id "$TASK_ID" --subtask-id "{subtask.id}"
 ```
 
+Then ENRICH the scaffold at `.aperant/features/deltas/{task-id}-{subtask.id}.json`:
+
+- Fill every `needs-disposition` files[] entry with a real disposition
+  (`upsert` | `remove` | `wiring-transition` | `no-semantic-change` — the
+  last REQUIRES a one-line `reason`). Added qualifying files MUST register
+  (added + no-semantic-change is a validation error).
+- Assign any `area: null` (the hooks/ipc/services junk drawers no longer
+  exist — pick the owning product area).
+- Replace draft upsert stubs with real feature groups: `sub_features[]`
+  entries carrying `wired` / `handler` / `test_hint` per
+  `FeatureRegistrySchema`.
+- A wired-state change is `disposition: "wiring-transition"` plus a
+  `patch-sub-feature` operation carrying `expected_from` (the prior
+  `wired` value).
+
+Stage the delta with the commit:
+`git add .aperant/features/deltas/ && git commit --amend --no-edit`.
+
 Notes:
-- `--task-id $TASK_ID` (BUG-025b) is mandatory when the executor runs
-  from the main-repo cwd instead of inside the worktree (the
-  orchestrator's common path). features-audit resolves the worktree's
-  `.aperant/features/` from the active task record and writes there,
-  preventing generated `*.json` from leaking into main. When invoked
-  from the worktree cwd directly, `--task-id` is a no-op (layer 1
-  detection short-circuits). Pass `--no-worktree-redirect` only when
-  you intentionally want to write to the invoking cwd.
-- `--apply-stubs` only runs when the matched surface's policy is
-  `auto-update` (the default for `.aperant/features/*.json`). Users who
-  opted out via `/apt:setup` Batch 7 get a no-op — the command still
-  succeeds.
-- Pre-existing flag-drift findings are never emitted here — they're the
-  reviewer's job. The post-step is append-only on internal state.
-- If the audit fails (exit code != 0), log the failure and continue; don't
-  block subtask completion on a features-registry glitch.
+- `--task-id "$TASK_ID"` (BUG-025b) redirects the delta write to the active
+  task's worktree `.aperant/features/deltas/` when you run from the
+  main-repo cwd; it is ALSO the per-writer delta filename, so it is always
+  required.
+- The write is skipped (`policy-opt-out`) when the user opted
+  `.aperant/features/*.json` out of `auto-update` via `/apt:setup` Batch 7.
+- Non-blocking: if the reconcile scaffold fails (exit code != 0), log the
+  failure and continue; don't block subtask completion on a registry
+  glitch. The ship-time `features-reconciled` gate + the always-on CI
+  check catch real gaps.
 
 ### 3e-gate. Per-Task Review Gate (R7)
 

package/dist/plugin/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/dist/plugin/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/dist/plugin/skills/apt-mockup/SKILL.md

@@ -58,7 +58,7 @@ Text-first design stays in `apt:design`. This skill never edits `DESIGN.md` or `
 **Writes:**
 - `{task_dir}/mockups/iteration-NNN.html` — One file per iteration, zero-padded 3-digit (`iteration-001.html`, `iteration-002.html`, ...). Promoted from a picked variant when the first render used `--variants`.
 - `{task_dir}/mockups/iteration-NNN-variant-<letter>.html` — One per variant in a `--variants` run (letters `a..e` for `N=2..5`)
-- `{task_dir}/mockups/iteration-NNN-gallery.html` — Generated by `apt-tools variant-gallery`; iframes the N variants side-by-side with the pick command spelled out.
+- `{task_dir}/mockups/iteration-NNN-gallery.html` — Generated by `apt-tools variant-gallery`; iframes the N variants side-by-side with the pick command spelled out, and each variant card links to its full HTML file (opens in a new tab).
 - `{task_dir}/mockups/iteration-NNN-archive/` — After `--pick <letter>`, the losing variants and the gallery move here (preserved, not deleted, so the user can review what was rejected).
 - `{task_dir}/mockups/mockup_final.html` — On `--accept`, a byte-identical copy of the latest `iteration-NNN.html` so iteration history is preserved.
 - `{task_dir}/mockups/mockup_log.md` — Append-only log: one entry per turn with iteration number, mode, user prompt, and (when relevant) variant style seeds.

package/dist/plugin/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/dist/plugin/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: