@aperant/framework 0.7.0 → 0.7.3

package/dist/plugin/skills/apt-improve/LANGUAGE.md

@@ -0,0 +1,104 @@
+<!--
+Adapted from Matt Pocock's MIT-licensed skill suite:
+https://github.com/mattpocock/skills/blob/main/skills/engineering/improve-codebase-architecture/LANGUAGE.md
+Licensed under MIT. Modifications: scoped to Aperant's apt:improve
+Phase-1 explore step and aligned with CONTEXT.md's aliases-to-avoid
+field — this lens reads that field to catch term conflations.
+-->
+
+# LANGUAGE — Naming-consistency lens
+
+This lens asks: **does the codebase use the same word for the same
+thing?** Do field names match domain language? Is CONTEXT.md's
+"aliases to avoid" list violated anywhere?
+
+Naming inconsistency is invisible until you trip over it. A reader who
+hits `userId` in one file and `user_id` in another, or `account` in
+the UI and `customer` in the backend, has to mentally translate
+between vocabularies — and that translation cost accumulates across
+every code review and every onboarding.
+
+## Red flags this lens surfaces
+
+### Same concept, two names
+The codebase has `user`, `account`, and `customer` referring to the
+same entity in different layers. Pick one and rename. CONTEXT.md's
+"aliases to avoid" field is the canonical place to record which name
+won.
+
+### Same name, two concepts
+The codebase has two distinct `Session` types — one for an auth
+session and one for a chat session. Disambiguate with a domain prefix
+(`AuthSession`, `ChatSession`) so a reader doesn't have to import the
+right one based on file location.
+
+### Field-name drift across layers
+The backend stores `created_at`, the API returns `createdAt`, the UI
+displays `Date created`. The serialization layer becomes a translation
+graveyard. Standardize across all three layers.
+
+### Implementation-detail names
+Field or symbol names that describe *how* something is stored or
+computed rather than *what* it represents. `is_processed_boolean` vs
+`is_processed`. `temp_holder_arr` vs `pending_items`.
+
+### CONTEXT.md violations
+If `CONTEXT.md` declares "Plan thread" with aliases-to-avoid: "Plan
+session, plan chat", any code in the area that calls it a "plan
+session" or "plan chat" is a violation. Grep CONTEXT.md aliases as
+part of this lens.
+
+## Apply in Phase 1
+
+When the explore step scans the named area:
+
+1. Read `CONTEXT.md` (if present) — every term-block's `Aliases to
+   avoid` field becomes a grep target.
+2. Grep the area for each alias. Each hit is a candidate.
+3. Look for the 4 other red flags above by inspection.
+4. Note in the inventory: `{File}:{Line} — uses {wrong-term} for
+   {canonical-term} ({CONTEXT.md reference if applicable})`.
+
+## Apply in Phase 3 (deepening loop)
+
+When the user picks a LANGUAGE candidate, the deepening loop should
+write the canonical decision into CONTEXT.md via `apt-tools context
+write`:
+
+```
+apt-tools context write . \
+  --term "{canonical}" \
+  --definition "{one-line}" \
+  --aliases-to-avoid "{loser1}, {loser2}"
+```
+
+This is the cycle: LANGUAGE lens surfaces conflations → user picks the
+canonical term → CONTEXT.md upserts the term-block → future LANGUAGE
+passes use CONTEXT.md as the grep source.
+
+## Distinguishing this from DEEPENING and INTERFACE-DESIGN
+
+A symbol can have a perfectly good name and still be the wrong depth
+(DEEPENING) or sit behind the wrong boundary (INTERFACE-DESIGN).
+LANGUAGE is orthogonal — it asks "regardless of where this lives or
+how big it is, does its name match the codebase's vocabulary?"
+
+## Deletion test (Phase 2 prep)
+
+The deletion test for LANGUAGE candidates is unusual: deleting the
+*wrong* name doesn't help unless you replace it with the right one. So
+the Phase-2 priority rubric for LANGUAGE candidates is:
+
+> Number of call sites that read with friction × cost of rename
+> divided by ergonomic gain.
+
+High-call-site, cheap-rename, real-confusion candidates are
+high-priority. One-off conflations that aren't blocking anyone are
+low-priority — record them in CONTEXT.md and move on.
+
+## What this lens does NOT cover
+
+- Abstraction depth → `DEEPENING.md`
+- Boundary shape → `INTERFACE-DESIGN.md`
+
+LANGUAGE is read-only of the symbol's *name*, not its *shape*.

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

@@ -0,0 +1,141 @@
+---
+name: apt:improve
+description: "Proactive refactor discovery — scan a named area through DEEPENING / INTERFACE-DESIGN / LANGUAGE lenses, present top candidates, deepen via grill loop."
+apt-skill-version: {{APT_VERSION}}
+stage: plan
+intent: investigate
+when_to_use: "The user feels code has rotted and wants a refactor surface (not a feature). Triggers: 'this part of the codebase needs work', 'I want to refactor X but don't know where to start', 'show me what's worth refactoring in Y'."
+user_invocable: true
+internal: false
+spawns_agent: true
+agent_name: "apt-improver"
+task_context: create-new
+default_track: DEEP
+default_execution_mode: step
+execution_modes:
+  - auto
+  - step
+allowed-tools: "Read, Grep, Glob, Bash"
+argument-hint: "apt:improve [area-name]"
+gates: []
+---
+
+# Improve — Proactive Refactor Discovery
+
+Open question #2 in the Pocock adoption spec was answered concretely:
+`apt:review` Pass 4 (architecture) is strictly **reactive** — it audits
+the current diff for boundary violations. The work-intent "look at this
+codebase and tell me what to refactor proactively" has no home today
+(users retrofit it onto `apt:discuss --brainstorm` or `/apt:roundtable`,
+both scope-mismatched). This skill is that home.
+
+**Pocock adoption attribution.** 3-phase workflow + DEEPENING /
+INTERFACE-DESIGN / LANGUAGE lenses ported from Matt Pocock's MIT-licensed
+`improve-codebase-architecture` skill. Aperant-specific: spawns the
+`apt-improver` agent and references `apt-discuss/appendices/grill-discipline.md`
+as the canonical source for the autonomy-aware deepening loop rather than
+re-stating the policy here.
+
+## When to Use
+
+- Feeling that an area of the codebase has rotted but unsure where to
+  start (proactive discovery)
+- Before a multi-task refactor cycle, to surface the highest-leverage
+  candidates first
+- After a feature has bedded in and the user wants to consolidate
+
+## When NOT to Use
+
+- Auditing a current diff for boundary violations — that's `/apt:review`
+  Pass 4 (reactive)
+- Locking a specific refactor decision — use `/apt:discuss` instead
+- Renaming or restructuring without proactive discovery — use
+  `/apt:plan` directly
+
+## 3-Phase workflow
+
+### Phase 1 — Explore (scan a named area for candidate refactors)
+
+Sub-agent `apt-improver` reads:
+
+- The named area (a noun phrase like "sparring engine", "feature
+  registry", "auth flow")
+- `CONTEXT.md` term-blocks matching the area (if present)
+- Relevant files via Glob/Grep
+
+It applies three lenses, each described in its own sub-file:
+
+- **DEEPENING** (`DEEPENING.md`) — does this area model the domain at
+  the right depth? Are abstractions earning their keep, or are they
+  shallow wrappers hiding nothing?
+- **INTERFACE-DESIGN** (`INTERFACE-DESIGN.md`) — are the boundaries
+  between modules well-shaped? Are there feature-envy patterns? Hidden
+  coupling? Async leakage?
+- **LANGUAGE** (`LANGUAGE.md`) — does the codebase use the same word
+  for the same thing? Do field names match domain language? Is
+  CONTEXT.md's "aliases to avoid" list violated anywhere?
+
+Output: a Phase-1 inventory of **candidate refactors** with one-line
+diagnoses per candidate.
+
+### Phase 2 — Present candidates (top 3-5 with deletion-test rationale)
+
+The skill body filters the Phase-1 inventory down to 3-5 candidates
+using the **deletion test**: for each candidate, ask "if I deleted this
+abstraction, what would break?" If the answer is "nothing important",
+the candidate is high-priority (the abstraction was paying no rent).
+
+Output to the user:
+
+```markdown
+## Refactor candidates for {area}
+
+1. **{Candidate title}** — {one-line diagnosis}.
+   Deletion test: {what breaks if removed} → {priority: high/med/low}.
+
+2. ...
+```
+
+### Phase 3 — Deepen via grill loop (autonomy-aware)
+
+The user picks one or more candidates. For each picked candidate, the
+skill enters a deepening loop. **This loop references
+`apt-discuss/appendices/grill-discipline.md` as the canonical source**
+for autonomy-aware degradation:
+
+- Autonomy 1: ask the user about every load-bearing design question
+- Autonomy 2: batch-recommend per decision, user reviews at end
+- Autonomy 3: auto-lock with the 3 escalation triggers (conflict with
+  prior locked decision; critical-path file touched; no defensible
+  default)
+
+The deepening loop produces a concrete refactor plan (which becomes
+`/apt:plan`'s input on a subsequent invocation).
+
+## Sub-files (MIT-attributed)
+
+- `DEEPENING.md` — domain-modeling depth lens
+- `INTERFACE-DESIGN.md` — boundary-shape lens
+- `LANGUAGE.md` — naming-consistency lens
+
+All three are ported from Matt Pocock's improve-codebase-architecture
+skill with MIT attribution per AC15.
+
+## Agent spawned
+
+`apt-improver` (definition at `packages/framework/agents/apt-improver.md`)
+runs Phase 1 — the codebase scan. Phases 2 and 3 run inline in the
+parent agent (no separate sub-agent) because they require user
+interaction for the candidate filter + the deepening loop.
+
+## Output contract
+
+- Phase 1 outputs a candidate inventory to stdout (not persisted).
+- Phase 2 outputs the top 3-5 to stdout for user selection.
+- Phase 3 (deepening loop) writes locked decisions to
+  `.aperant/context/notes/{task-id}.md` via `apt-tools context write`
+  and `apt-tools adr write` (the latter only when Nygard's 3-gate
+  filter passes — most refactor decisions are reversible and stay in
+  context-notes).
+- The skill does NOT emit an implementation plan — that's `/apt:plan`'s
+  job. apt:improve produces *what to refactor*; apt:plan produces *how*.

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

@@ -99,6 +99,18 @@ For STANDARD and COMPLEX tasks:
    - Test files that will need updates
    - Configuration that may need changes
 
+### 4.4. React state guidance — sync-store vs render-committed ref (BUG-025-planner)
+
+When a planned event handler fires a flush/persist immediately after mutating a Zustand/Jotai/refs-stored store, the spec MUST recommend reading from `store.getState()` (or the equivalent direct-read primitive) on the synchronous path, NOT from a `useRef`-populated-by-`useEffect`.
+
+Why: refs populated via `useEffect` lag the store by exactly one render cycle. A handler that mutates the store and immediately reads the ref sees the pre-mutation value, silently corrupting persists and order-of-operations contracts. Reference pattern: `apps/desktop/src/renderer/src/App.tsx::runUpsertForIds` (post-fix commit `4c263856`).
+
+Investigation checklist when the task touches a Zustand/Jotai store or any handler that does flush-after-mutate:
+
+- Grep for `useRef(` references that cache store state (e.g. `const fooRef = useRef(foo)` populated by `useEffect(() => { fooRef.current = foo }, [foo])`).
+- If the spec or planned subtasks read from such a ref on a synchronous path that ALSO mutates the store, recommend `store.getState()` (or `useFooStore.getState()`) as the read primitive.
+- Note the caveat explicitly in the spec's Implementation Decisions section so the executor doesn't silently revert it.
+
 ### 4.5. Consume design.md (C24)
 
 If `{task_dir}/design.md` exists (emitted by a prior `/apt:design` run), load it before decomposing subtasks:
@@ -110,7 +122,17 @@ If `{task_dir}/design.md` exists (emitted by a prior `/apt:design` run), load it
 
 ## 5. Write Specification
 
-Create `spec.md` in the task directory (`{task_dir}` passed from the router, e.g. `.aperant/tasks/{task-id}/spec.md`):
+Create `spec.md` in the task directory (`{task_dir}` passed from the router, e.g. `.aperant/tasks/{task-id}/spec.md`).
+
+**Content format branches on track (Fast Path Guarantee — Pocock adoption ID-05):**
+
+### 5.A. QUICK track — legacy 4-section format (hard-exempt from PRD upgrade)
+
+When `track === "QUICK"` (the `apt:classify` rubric routed this as a one-shot
+task) OR the complexity is `SIMPLE`, write the existing minimal 4-section
+spec. Do NOT promote to PRD shape. The QUICK path is a constraint, not a
+toggle — the user opted into one-shot speed; PRD ceremony would violate
+that contract.
 
 ```markdown
 # Task: {task description}
@@ -131,6 +153,79 @@ Create `spec.md` in the task directory (`{task_dir}` passed from the router, e.g
 {What this task explicitly does NOT cover}
 ```
 
+### 5.B. STANDARD / DEEP / COMPLEX tracks — PRD-shaped spec.md
+
+When `track ∈ {"STANDARD", "DEEP"}` OR complexity is `STANDARD` or
+`COMPLEX`, write a PRD-shaped spec.md so the artifact survives the task
+and is committable as a second-consumer document. Section ordering is
+**load-bearing** — downstream tooling (`apt-tools coverage-check`,
+`apt-tools consistency check`) reads sections by header.
+
+```markdown
+# Spec: {task title}
+
+**Task ID:** {task-id}
+**Track:** {STANDARD | DEEP}
+**Scope:** {framework | desktop | web | core | ui | backend | docs}
+
+## Problem Statement
+
+{What pain are we solving? Cite empirical evidence, prior decisions, or
+codebase artifacts where possible. State what's broken or missing today.}
+
+## Solution
+
+{One paragraph: the chosen approach. Then a bulleted net delta of what
+ships: new files, modified files, new flags, new config, new skills.}
+
+## User Stories
+
+{One story per user value slice. Format: "**US-NN (persona).** As a
+{persona}, when I {trigger}, I want {behavior} so I can {outcome}."
+Stories map 1:1 onto subtasks in implementation_plan.json.}
+
+## Implementation Decisions
+
+{Load-bearing principles carried forward into every subtask. Format:
+"### ID-NN: {decision title}" + rationale + practical consequence. Each
+ID-NN is referenced from subtask descriptions where relevant.}
+
+## Testing Decisions
+
+{One block per test family: "### TD-NN: {test family name}" + what's
+covered + which subtask owns the test file. Critical: Fast Path Guarantee
+regression tests (QUICK-exempt assertions) MUST be enumerated here.}
+
+## Out of Scope
+
+{Explicit non-goals. Each bullet names what is deferred + where it
+belongs (parallel track, v2 follow-up, separate task).}
+
+## Further Notes
+
+{Sequencing rationale, risk surface, dependencies on other parts of the
+codebase, files-affected preview, and any other context the executor
+needs but that doesn't fit the seven primary sections.}
+
+### Acceptance Criteria
+
+{Cross-cutting AC1..ACN list — each acceptance criterion gets a stable
+ID. Subtasks reference these IDs via their per-subtask
+`acceptance_criteria` field (see Section 6). This list IS the
+plan-coverage-check input.}
+```
+
+**Constraint — do NOT interview the user.** The PRD is synthesized from
+the task description + codebase investigation + AGENTS.md, not from a
+clarifying interview. If a section truly cannot be filled, write
+`{TBD — needs user input}` so the gap is visible; do NOT pause for
+clarification (that's `apt:discuss`'s job, not the planner's).
+
+**Section ordering is mandatory.** `apt-tools coverage-check validate`
+greps `## Acceptance Criteria` for AC IDs; `apt-tools consistency check`
+greps `## Solution` and `## User Stories`. Renaming or reordering these
+breaks downstream tooling.
+
 ### 5.1. Design Reference section (C24 — when design.md exists)
 
 When `{task_dir}/design.md` exists, `spec.md` MUST include a `## Design Reference` section **directly below `## Requirements`**. The section cites the design artifact by relative path and enumerates which screens and components the subtasks cover. Shape:
@@ -212,35 +307,95 @@ When `status: warn` (non-blocking enforcement) and the user is in **auto mode**
 
 ## 6. Create Implementation Plan
 
-Create `implementation_plan.json` in the task directory (`{task_dir}/implementation_plan.json`):
+Create `implementation_plan.json` in the task directory (`{task_dir}/implementation_plan.json`).
+
+**Subtask schema branches on track (Pocock adoption ID-05 — Fast Path Guarantee).**
+
+### 6.A. QUICK track / SIMPLE complexity — legacy flat subtask schema
 
 ```json
 {
   "task": "{task description}",
-  "complexity": "simple|standard|complex",
+  "complexity": "simple",
   "spec": "spec.md",
+  "subtasks": [
+    {
+      "id": "1",
+      "title": "{subtask title}",
+      "description": "{what to do — concrete, not vague}",
+      "files": ["path/to/file1.ts", "path/to/file2.ts"],
+      "dependencies": [],
+      "status": "pending",
+      "verification": "{command or check to verify completion}"
+    }
+  ]
+}
+```
+
+QUICK subtasks omit `hitl`, `afk`, `acceptance_criteria`, and `user_value`
+fields. The one-shot path doesn't need user-value framing or per-subtask
+HITL gates.
+
+### 6.B. STANDARD / DEEP / COMPLEX — vertical-slice subtask schema
+
+```json
+{
+  "task": "{task description}",
+  "complexity": "standard|complex",
+  "spec": "spec.md",
+  "vertical_slice_schema_version": "1",
   "declared_persona_tier": "primary",
   "declared_personas": ["mobile-dev"],
   "tier_confidence": "high",
   "subtasks": [
     {
       "id": "1",
-      "title": "{subtask title}",
+      "title": "{subtask title — user-value framing, not 'add UI'}",
       "description": "{what to do — concrete, not vague}",
       "files": ["path/to/file1.ts", "path/to/file2.ts"],
+      "acceptance_criteria": ["AC1", "AC3"],
       "dependencies": [],
       "status": "pending",
+      "hitl": "required | review | none",
+      "afk": "safe | unsafe",
+      "user_value": "{one-line user-value framing — who benefits, how}",
       "verification": "{command or check to verify completion}"
     }
   ]
 }
 ```
 
+**Mandatory STANDARD/DEEP fields (per subtask):**
+
+- `hitl` — `"required" | "review" | "none"`. `required` means a human MUST
+  approve the subtask before proceeding (autonomy 1 always pauses;
+  autonomy 2 batches recommendations; autonomy 3 escalates only on
+  conflict). `review` means the human reviews the diff after the agent
+  ships it (post-hoc, not blocking). `none` means agent-only.
+- `afk` — `"safe" | "unsafe"`. `safe` means the agent may proceed
+  unattended without supervision. `unsafe` means the agent should pause
+  at the start of this subtask if no human is present (autonomy < 3).
+- `acceptance_criteria` — `string[]` of id-refs (`"AC1"`, `"AC3"`, …)
+  into the spec.md `## Acceptance Criteria` section. Every AC in spec.md
+  MUST be referenced by at least one subtask (gate G8 consistency-check
+  enforces this on ship).
+- `user_value` — one-line framing of WHO benefits and HOW. Prevents
+  horizontal slicing ("add UI" / "add backend") — every subtask must be
+  a vertical user-shippable slice with a defensible value framing.
+
+**Plan-level fields for STANDARD/DEEP:**
+
+- `vertical_slice_schema_version` — `"1"` (current). Stable across the
+  v1 schema window; bumped when the subtask shape changes incompatibly.
+  Plans without this field are treated as legacy flat schema.
+
 Reference `prompts/planner.md` for subtask decomposition patterns:
 - Each subtask should be completable in one focused session
 - Dependencies must form a DAG (no circular deps)
 - Verification must be automated (test command, grep check, type check)
 - Files list must be exhaustive — every file the subtask touches
+- Subtask title MUST frame user value, not file scope (e.g., "Solo
+  dogfooder gets PRD-shaped spec on STANDARD", NOT "edit apt-plan SKILL.md")
 
 **Framework-scope doc-sync rule (C33).** When `task.scope === "framework"` AND any subtask's `files` intersect `packages/framework/src/cli/**`, the plan MUST end with a subtask whose title contains `Doc sync` (case-insensitive) and whose `files` list includes at least one of `packages/framework/skills/apt-*/SKILL.md`, `packages/framework/agents/apt-*.md`, `packages/framework/templates/agents-*.md`, or `CLAUDE.md`. The detailed rule and rationale live in `packages/framework/agents/apt-planner.md` §5.1; the planner agent appends this subtask automatically when it would otherwise be missing. Smoke-drain emits a warn-only signal for plans that violate the rule.
 
@@ -273,6 +428,18 @@ The coverage check ensures every acceptance criterion has at least one subtask w
 node packages/framework/bin/apt-tools.mjs commit "plan: create implementation plan for {task}" --files spec.md implementation_plan.json
 ```
 
+## 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'}`
+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
+skip the adapter entirely and proceed to Section 9.
+
 ## 9. Report
 
 Output a summary:

package/dist/plugin/skills/apt-plan/adapters/conductor.md

@@ -0,0 +1,98 @@
+# apt-plan adapter — Aperant Conductor
+
+This adapter is **only loaded** when the planner runs under the Aperant
+Conductor (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:
+
+```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.
+
+## What changes under the Conductor
+
+The planner's filesystem outputs (`spec.md`, `implementation_plan.json`)
+are unchanged. The ADDITION is one extra step after Section 8 (Persist
+State) of `SKILL.md`:
+
+### Plan-Ready Signal (framework-owned, no action required)
+
+The `artifact.ready{kind:'plan'}` signal is emitted **automatically** by
+the framework's `apt-tools commit` postcondition. When the planner
+commits `spec.md` + `implementation_plan.json` via the standard:
+
+```bash
+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
+`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
+auto-stamped `terminal_id`.
+
+This replaces the earlier markdown-discipline emit step. The earlier
+step was correctly skipped on QUICK / SIMPLE classified tasks (Fast
+Path Guarantee, Pocock adoption ID-05) — moving the emit to a
+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
+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
+(slightly higher latency, same outcome).
+
+### Plan-review handshake (Step 6 + 7 of Conductor v2)
+
+After emitting `artifact.ready{kind:'plan'}` the planner SHOULD pause at
+an idle prompt and listen for ONE of three Conductor-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**.
+  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
+  decide to respawn the terminal entirely.
+
+These exact strings are pinned by the Conductor's `ConductorContextHost`
+handlers (`packages/ui/src/sections/conductor/ConductorContextHost.tsx`).
+Native CLI invocations of `/apt:plan` (no `APERANT_TERMINAL_ID`) skip
+this handshake and follow the normal report → `/apt:execute` flow.
+
+## Why this lives in an adapter (not in SKILL.md)
+
+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
+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:
+**runtime-context loader** — load when the runtime environment matches.
+
+## Adding more adapters
+
+Future runtime contexts (e.g. a hypothetical CI runner, another
+orchestrator) can add `adapters/{context}.md` files using the same
+pattern: detect via env or filesystem signal, document the additional
+obligations, and add a one-line conditional reference in `SKILL.md`.