@aperant/framework 0.6.2

package/skills/apt-stress-test/SKILL.md

@@ -0,0 +1,339 @@
+---
+name: apt:stress-test
+description: "Scenario simulation to catch operational gaps in plans before implementation"
+apt-skill-version: {{APT_VERSION}}
+stage: plan
+intent: investigate
+when_to_use: "A plan is drafted and the user wants scenario simulation to catch operational gaps before implementation begins."
+user_invocable: true
+internal: false
+spawns_agent: false
+agent_name: null
+default_execution_mode: step
+execution_modes:
+  - auto
+  - step
+allowed-tools: "Read, Grep, Glob, Bash, Write"
+argument-hint: "apt:stress-test [task-id]"
+gates: []
+---
+<objective>
+You are the Aperant Stress-Test orchestrator. You run pre-implementation scenario simulations that catch operational gaps in plans, specs, or design documents before any code is written.
+
+This is NOT a code test. It is a design validation tool. It simulates humans using the proposed system before it is built. You spawn 3-5 parallel scenario agents, each playing a different fictional persona walking through the entire proposed workflow, reporting friction, gaps, and failure modes.
+
+**Origin:** This skill was born from the framework's own design process. Two adversarial reviews (Claude + Codex) challenged the spec's logic and assumptions but missed 24 operational gaps. Five parallel scenario agents simulating real users caught every one of them. Adversarial reviews and scenario tests catch fundamentally different classes of problems -- together they provide near-complete coverage.
+
+| Review Type | What It Catches | What It Misses |
+|------------|----------------|---------------|
+| **Adversarial review** | Logical flaws, unsafe assumptions, missing safety primitives | Whether the design actually works when a human sits down to use it |
+| **Stress-test** | Operational gaps, UX friction, edge cases in real workflows, missing lifecycle steps | Abstract design flaws, philosophical tradeoffs |
+| **Both together** | Near-complete coverage | Very little |
+</objective>
+
+<your_environment>
+- **Working directory:** The project root (where you were invoked)
+- **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 -- it defines project principles, tech stack, and conventions that override defaults
+- **Config:** `.aperant/config.json` -- project preferences (autonomy, QA thresholds, risk map, project_type)
+- **Target:** The plan, spec, or design document to stress-test, extracted from `$ARGUMENTS`
+</your_environment>
+
+<state_files>
+## State Files
+
+**Reads:**
+- `AGENTS.md` -- Project constitution (principles, conventions, tech stack)
+- `.aperant/config.json` -- Autonomy level, risk map, project_type (used for scenario weighting)
+- Target plan/spec/design document provided via `$ARGUMENTS`
+- `.aperant/state.json` -- If no explicit target, resolve the active plan via `active_tasks[*].spec.path` / `implementation_plan`, falling back to the most-recent `.aperant/tasks/{task-id}/implementation_plan.json`
+
+**Writes:**
+- `.aperant/stress-tests/{slug}-{YYYYMMDD}/` -- Complete stress-test output directory tree
+</state_files>
+
+<output_structure>
+## Output Directory
+
+Every stress-test produces the following file tree:
+
+```
+.aperant/stress-tests/{slug}-{YYYYMMDD}/
+  scenarios/
+    scenario-1-{name}.md      # Full simulation report from agent 1
+    scenario-2-{name}.md      # Full simulation report from agent 2
+    scenario-3-{name}.md      # Full simulation report from agent 3
+    scenario-4-{name}.md      # (if 4-5 scenario run)
+    scenario-5-{name}.md      # (if 5 scenario run)
+  STRESS-TEST.md               # Consolidated gap analysis
+```
+</output_structure>
+
+<process>
+
+## Step 0: Parse Input
+
+1. Extract the target file path from `$ARGUMENTS`
+2. If no path is provided, resolve the active plan from `.aperant/state.json` — read `active_tasks[*].spec.path` (or `implementation_plan`) and fall back to the most-recent `.aperant/tasks/{task-id}/implementation_plan.json`
+3. If still no target found, ask: "What plan or spec should I stress-test? Provide a file path."
+4. Read the target document in full
+5. Generate a slug from the document title or filename: lowercase, hyphens, max 40 characters
+6. Get today's date in `YYYYMMDD` format
+7. Set `OUTPUT_DIR=.aperant/stress-tests/{slug}-{YYYYMMDD}`
+
+## Step 1: Scenario Generation (Orchestrator)
+
+Read the target plan/spec/design document carefully. Then generate 3-5 fictional scenarios that stress-test it from maximally different angles.
+
+### Diversity Axes
+
+Select scenarios to maximize coverage across these axes:
+
+| Diversity Axis | Example Variations |
+|---------------|-------------------|
+| **User expertise** | Junior dev (6 months experience) vs Senior architect (15 years) vs Non-technical PM |
+| **Project type** | Greenfield SaaS vs Brownfield enterprise vs CLI tool vs library vs mobile app |
+| **Scale** | Solo dev side project vs Small startup team (3-5) vs 50-engineer enterprise |
+| **Codebase state** | Clean with full test coverage vs Messy MVP with no tests vs Legacy monolith with 10 years of debt |
+| **Risk profile** | Prototyping (speed over safety) vs Production (reliability critical) vs Compliance (audit trail required) |
+
+### Scenario Selection Rules
+
+1. Pick 3 scenarios for a quick run, 5 for a thorough run (default: 3 unless `--thorough` flag)
+2. No two scenarios should share the same value on more than 2 diversity axes
+3. At least one scenario should be an adversarial edge case (the user most likely to break things)
+4. Read `.aperant/config.json` for `project_type` -- weight scenarios similar to the user's actual situation higher (they appear first)
+5. At least one scenario should represent a user very DIFFERENT from the project's target audience
+
+### Scenario Definition Format
+
+For each scenario, define:
+
+```markdown
+## Scenario {N}: {Descriptive Name}
+
+**Persona:** {Name}, {Role} with {experience level}
+- Motivations: {what they want to achieve}
+- Technical comfort: {Junior/Mid/Senior/Non-technical}
+- Patience level: {Low/Medium/High}
+
+**Project:** {Project description}
+- Tech stack: {relevant technologies}
+- Size: {lines of code, team size}
+- Maturity: {Greenfield/Growing/Legacy}
+- Constraints: {time, budget, compliance, etc.}
+
+**Challenge:** {What makes THIS scenario a stress-test}
+- {specific friction point this persona will hit}
+- {edge case this project type introduces}
+- {scale or state issue that could break the design}
+
+**Journey Steps:**
+1. {First interaction with the system}
+2. {Next step in the workflow}
+3. {Key decision point}
+4. {Error or edge case encounter}
+5. {Completion or abandonment}
+```
+
+Create the output directory:
+```bash
+mkdir -p "${OUTPUT_DIR}/scenarios"
+```
+
+## Step 2: Parallel Simulation (3-5 Agents)
+
+Spawn ALL scenario agents in a SINGLE message for parallel execution. Each agent uses the `sonnet` model.
+
+### Scenario Agent Prompt Template
+
+Use this EXACT template for each agent. Replace placeholders with scenario-specific values.
+
+```
+You are simulating a FICTIONAL SCENARIO to stress-test a design document.
+
+READ THIS FILE FIRST: {path to plan/spec}
+
+SCENARIO: "{scenario name}"
+- PERSONA: {persona name}, {role} with {experience level}. Motivations: {motivations}. Technical comfort: {level}. Patience: {level}.
+- PROJECT: {project description}. Tech stack: {tech stack}. Size: {size}. Maturity: {maturity}. Constraints: {constraints}.
+- CHALLENGE: {what makes this scenario a stress-test}
+
+SIMULATE THE ENTIRE USER JOURNEY:
+1. {step 1 specific to this scenario}
+2. {step 2 specific to this scenario}
+3. {step 3 specific to this scenario}
+4. {step 4 specific to this scenario}
+5. {step 5 specific to this scenario}
+{add more steps as needed for this scenario}
+
+FOR EACH STEP identify:
+- Does the spec cover this? (cite section numbers)
+- Are there GAPS where the spec is silent or ambiguous?
+- Would this experience be BETTER or WORSE than alternatives?
+- Any friction points or confusing moments?
+
+WRITE YOUR REPORT TO: {OUTPUT_DIR}/scenarios/scenario-{N}-{name}.md
+
+FORMAT (~1000 words):
+
+# Scenario {N}: {Scenario Name}
+
+## Persona
+{Brief persona recap}
+
+## Journey Simulation
+
+### Step 1: {Step title}
+**Spec coverage:** {section number or "NOT COVERED"}
+**Experience:** {What happens at this step. Be specific and narrative.}
+**Friction:** {Any confusion, frustration, or blocking issue}
+
+### Step 2: {Step title}
+...
+
+{repeat for all steps}
+
+## What Works Well
+- {thing the spec handles well for this persona}
+- {thing the spec handles well for this persona}
+
+## Gaps Found
+
+| ID | Gap | Severity | Spec Section | Description |
+|----|-----|----------|-------------|-------------|
+| G1 | {gap title} | Critical / High / Medium / Low | {section or "missing"} | {description} |
+| G2 | {gap title} | Critical / High / Medium / Low | {section or "missing"} | {description} |
+...
+
+## Overall Assessment
+{1-2 paragraph assessment: would this persona succeed with this spec? What is the biggest risk?}
+```
+
+Wait for all scenario agents to complete their reports.
+
+## Step 3: Gap Synthesis (Orchestrator)
+
+Read ALL scenario reports from `{OUTPUT_DIR}/scenarios/`. Then synthesize:
+
+### 3a: Deduplicate Gaps
+
+- Compare gaps across all scenarios by root cause, not by surface description
+- Same root cause found in multiple scenarios = ONE gap (note all scenarios it appears in)
+- Different manifestations of the same missing spec section = ONE gap
+
+### 3b: Classify Severity
+
+| Severity | Definition | Action Required |
+|----------|-----------|-----------------|
+| **Critical** | Blocks usage entirely -- user cannot complete the workflow | Must fix before implementation |
+| **High** | Significant friction -- user can work around it but experience is degraded | Should fix before implementation |
+| **Medium** | Post-launch fix acceptable -- user notices but is not blocked | Fix in first iteration |
+| **Low** | Polish item -- minor friction or aesthetic issue | Fix when convenient |
+
+### 3c: Map to Spec Sections
+
+For each unique gap, identify the specific section of the spec/plan that:
+- Needs to be updated (if the section exists but is incomplete)
+- Needs to be created (if the spec is silent on this topic)
+
+### 3d: Identify Shared vs Single-Scenario Gaps
+
+- Gaps found in 2+ scenarios get higher priority (systemic issue)
+- Single-scenario gaps are still valid but lower priority (edge case)
+
+### 3e: Write STRESS-TEST.md
+
+Write `{OUTPUT_DIR}/STRESS-TEST.md` with this structure:
+
+```markdown
+# Stress-Test Report: {Plan/Spec Name}
+
+**Date:** {YYYY-MM-DD}
+**Target:** {path to plan/spec}
+**Scenarios tested:** {count}
+**Total unique gaps found:** {count}
+**Critical gaps:** {count}
+
+## Critical Gaps
+
+### G1 -- {Gap Title}
+**Found in:** Scenario {N} ({name}), Scenario {M} ({name})
+**Spec section:** {section numbers or "missing section"}
+**Description:** {What is missing or ambiguous and why it blocks usage}
+**Recommended fix:** {Specific change to the spec/plan to address this gap}
+
+### G2 -- {Gap Title}
+...
+
+## High Gaps
+
+### G{N} -- {Gap Title}
+**Found in:** {scenarios}
+**Spec section:** {sections}
+**Description:** {What causes significant friction}
+**Recommended fix:** {Specific change}
+
+## Medium Gaps
+
+### G{N} -- {Gap Title}
+**Found in:** {scenarios}
+**Description:** {Post-launch fix acceptable}
+
+## Low Gaps
+
+### G{N} -- {Gap Title}
+**Found in:** {scenarios}
+**Description:** {Polish item}
+
+## What Works Well
+
+{List of things that every or most scenarios validated as strong, well-designed aspects of the spec.
+These are the parts that should NOT be changed.}
+
+- {strength 1} -- validated by scenarios {list}
+- {strength 2} -- validated by scenarios {list}
+
+## Gap Distribution Matrix
+
+| Gap | Severity | Scenario 1 | Scenario 2 | Scenario 3 | Scenario 4 | Scenario 5 |
+|-----|----------|-----------|-----------|-----------|-----------|-----------|
+| G1: {title} | Critical | X | X | | | |
+| G2: {title} | High | | X | X | | |
+| G3: {title} | Medium | X | | | X | |
+{... for all gaps}
+
+**Shared gaps (2+ scenarios):** {count} -- these are systemic issues
+**Single-scenario gaps:** {count} -- these are edge cases
+```
+
+## Step 4: Commit Output
+
+```bash
+node packages/framework/bin/apt-tools.mjs commit "stress-test: {slug}" --files .aperant/stress-tests/{slug}-{date}
+```
+
+</process>
+
+<autonomy_interaction>
+## Autonomy Interaction
+
+| Autonomy Level | Behavior |
+|----------------|----------|
+| 0-1 (Guardian/Supervised) | Router suggests stress-test for DEEP plans; user chooses to run or skip |
+| 2 (Balanced) | Router auto-runs stress-test for plans touching Critical risk areas |
+| 3 (YOLO) | Skipped -- YOLO mode trusts the plan |
+</autonomy_interaction>
+
+<cost_timing>
+## Cost and Timing
+
+| Mode | Scenarios | Time | Tokens |
+|------|-----------|------|--------|
+| Quick (default) | 3 | ~5 minutes | ~50k tokens |
+| Thorough (`--thorough`) | 5 | ~10 minutes | ~100k tokens |
+
+The cost is trivial compared to implementing a plan with critical gaps and discovering them during execution (which consumes tokens for wrong code, fix iterations, and re-planning).
+
+Cost optimization: Uses `sonnet` model for scenario agents; orchestrator uses opus for synthesis.
+</cost_timing>

package/skills/apt-terminal/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: apt:terminal
+description: "Spawn a sibling Aperant terminal with its own worktree + CLI instance for parallel work"
+apt-skill-version: {{APT_VERSION}}
+stage: ops
+intent: configure
+when_to_use: "The user is inside an Aperant-spawned PTY and wants to open a sibling terminal with its own worktree for parallel subtask execution."
+user_invocable: true
+internal: false
+spawns_agent: false
+agent_name: null
+default_execution_mode: step
+execution_modes:
+  - auto
+  - step
+allowed-tools: "Bash, Read, Write"
+argument-hint: "apt:terminal [task-id] [--cwd <path>]"
+gates: []
+---
+<objective>
+Open a sibling Aperant terminal from inside an existing Aperant-spawned PTY. Each spawned terminal gets its own worktree (cwd) and starts a fresh Claude Code (or other CLI) instance — useful when the executor has identified parallel-safe subtasks and wants to fan out work across multiple agent windows.
+
+This is an OPT-IN capability for executors. The default `apt:execute` flow stays sequential. Use `apt:terminal` only when:
+1. You have ≥2 subtasks with NO file overlap and NO ordering dependencies, AND
+2. You are running inside an Aperant terminal (host-detect `aperant_terminal:true`).
+
+The hard cap is 4 levels of nested spawn (APERANT_MAX_SPAWN_DEPTH) to prevent fork-bomb feedback loops.
+</objective>
+
+<your_environment>
+- **Working directory:** Whatever the current task's worktree is (or project root if no worktree).
+- **apt-tools:** Always invoke as `node packages/framework/bin/apt-tools.mjs` from the project root.
+- **Detection:** `apt-tools host-detect` returns `aperant_terminal: true|false` plus `aperant_socket: <path|null>`.
+- **Transport:** Unix-domain socket at `process.env.APERANT_IPC_SOCKET`. Web-mode callers use the HTTP proxy at `http://127.0.0.1:14714/terminal/spawn` instead — same payload shape.
+- **Constitution:** Read `AGENTS.md` if it exists.
+</your_environment>
+
+<state_files>
+## State Files
+
+**Reads:**
+- `process.env.APERANT_IPC_SOCKET` — absolute path to AperantIpcServer's Unix socket (set by NodePtyProvider when the parent terminal was spawned by Aperant)
+- `process.env.APERANT_SPAWN_DEPTH` — current depth (0 for user-launched, 1+ for nested). Read by the CLI client and forwarded as `_callerDepth` so the server can enforce the cap.
+- `.aperant/state.json` (read indirectly by the server's worktree allowlist) — used to validate that `--worktree` points to a path under a known Aperant project.
+
+**Writes:**
+- Each spawned terminal becomes a new PTY session inside Electron-main; the spawned `sessionId` is also visible in `apt-tools terminal list`.
+- The agent SHOULD record spawned task IDs in its own task notes (`.aperant/tasks/{task-id}/build-progress.json` or equivalent) for traceability.
+
+**No filesystem state of its own.** The skill is pure compute glue.
+</state_files>
+
+<process>
+
+## 1. Preflight — confirm we are inside Aperant
+
+```bash
+node packages/framework/bin/apt-tools.mjs host-detect
+```
+
+Inspect the JSON output:
+- `host.aperant_terminal` MUST be `true`. If `false`, **stop**: spawning is unavailable in the current shell.
+- `host.aperant_socket` MUST be a non-null path. If `null`, **stop** with the same reason.
+
+If preflight fails, surface this to the user verbatim and fall back to sequential execution. Do NOT try to start an IPC server yourself — only Electron main owns it.
+
+## 2. Decide whether to spawn
+
+The executor MAY call `apt:terminal spawn` when ALL of these hold:
+
+- Two or more remaining subtasks share NO files (compare `subtask.files` arrays — strict set disjoint).
+- None of those subtasks declare a dependency on another subtask in the same fan-out group.
+- The subtasks each touch ≤1 package boundary (so ./pnpm install or build-step dependencies do not collide).
+
+If even one condition fails, do NOT spawn — keep the sequential `apt:execute` flow.
+
+## 3. Spawn
+
+The exact command shape (`apt-tools terminal spawn` is the canonical name; the
+.mjs suffix is just the local invocation when running from a checkout):
+
+```bash
+node packages/framework/bin/apt-tools.mjs terminal spawn \
+  --worktree /abs/path/to/worktree \
+  --task <task-id> \
+  [--instructions "kick-off prompt for Claude Code"] \
+  [--cli claude-code] \
+  [--yolo]
+```
+
+The response is JSON to stdout. On success:
+
+```json
+{"id":"…","ok":true,"result":{"sessionId":"…","wsUrl":"ws://127.0.0.1:14714/terminal/…","depth":N}}
+```
+
+`depth` is the new terminal's level (caller_depth + 1). Record `sessionId` in your task notes.
+
+## 4. Recognise the graceful-degrade error envelopes
+
+These are **expected** error shapes — do not retry blindly. Each one tells you exactly which obligation discharged:
+
+| Error code | Meaning | Action |
+|---|---|---|
+| `not_in_aperant_terminal` | `APERANT_IPC_SOCKET` was not in env. You are not inside an Aperant PTY. | Fall back to sequential execution. |
+| `electron_compute_unavailable` | The socket file does not exist (Electron main is not running). | Surface to the user and fall back. |
+| `depth_exceeded` | The new spawn would exceed `APERANT_MAX_SPAWN_DEPTH=4`. | Stop fanning out. The current depth is `(payload._callerDepth)`. |
+| `outside_known_project` | `--worktree` was not under a directory containing `.aperant/state.json`. | Re-check the worktree path. |
+| `validation_failed` | Missing `--worktree` or `--task`, or non-absolute path. | Fix the flags. |
+| `timeout` | Server did not respond within 10 s. | Retry once; if it persists, surface to the user. |
+
+## 5. List / status / health (read-only)
+
+```bash
+# Every session known to AperantIpcServer (via its TerminalManager)
+node packages/framework/bin/apt-tools.mjs terminal list
+
+# One session's metadata
+node packages/framework/bin/apt-tools.mjs terminal status --session <sessionId>
+
+# Smoke-test the socket — handy when debugging "why isn't spawn working?"
+node packages/framework/bin/apt-tools.mjs terminal health
+```
+
+## 6. After spawn — track and let the spawned agent finish
+
+The spawned terminal runs its own Claude Code (or other CLI) instance. It is a peer, not a child of the current process. Once spawned:
+
+- The current agent SHOULD continue with whatever subtask remains in its own queue.
+- The spawned agent will pick up its task via the `--instructions` it was given (or a follow-up `apt:plan`/`apt:execute` round started by the user).
+- If the spawned terminal's task is also in the same plan, mark its subtask in `implementation_plan.json` as `status: "in-progress"` and add `assigned_to: "<sessionId>"` for traceability.
+
+**Do NOT** add auto-spawn logic to `apt:execute` from this skill — auto-spawn is a follow-up subtask in a different milestone. `apt:terminal` is a documented capability that the executor MAY invoke when appropriate, never a default.
+</process>
+
+<security>
+## Security Notes
+
+- The IPC socket is `chmod 0600` under a `chmod 0700` parent dir, with the OS username embedded in the path. Single-user desktop threat model.
+- The socket is bound to a Unix domain — never a TCP port.
+- The HTTP proxy at `:14714/terminal/spawn` is bound to `127.0.0.1` only (verified in `terminal-websocket-server.ts`).
+- Worktree paths are validated against a "must be under a directory containing `.aperant/state.json`" allowlist. Arbitrary `cwd` injection is rejected.
+- The `--instructions` payload is shell-quoted before being written to PTY stdin. There is no `eval` or template-string interpolation into a shell command.
+- Spawn-depth cap (4) prevents fork-bomb feedback loops.
+</security>

package/skills/apt-update/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: apt:update
+description: "Refresh installed skills/agents/hooks across every runtime and clear the update chip"
+apt-skill-version: {{APT_VERSION}}
+stage: ops
+intent: configure
+when_to_use: "The statusline chip says an Aperant update is available, or the user manually wants to refresh installed skills/agents/hooks across every installed runtime."
+user_invocable: true
+internal: false
+spawns_agent: false
+agent_name: null
+default_execution_mode: auto
+execution_modes:
+  - auto
+  - step
+allowed-tools: "Bash, Read, Write"
+argument-hint: "apt:update"
+gates: []
+---
+
+<objective>
+You re-install the Aperant Framework's runtime files (skills, agents, hooks) into every runtime root that's currently installed in the project. You ALWAYS use the existing install via the manifest — you never guess which runtimes to install. You always clear the cache file at the end so the statusline chip immediately reflects the fresh state.
+
+**Output discipline:** hide the raw apt-tools JSON envelopes from the user. Parse them, extract the numbers, and print a short summary in the format specified under `<output_format>`. The user wants to see "version X → Y, files refreshed" — not a wall of JSON.
+</objective>
+
+<context>
+The user invoked `/apt:update` because the statusline showed one of:
+
+- `⬆ /apt:update` (yellow): npm has a newer version than what's installed.
+- `⚠ stale skills — run /apt:update` (red): per-file drift was detected (header_mismatch, hash_mismatch, missing_header, or missing_file in one or more runtime manifests).
+- `⚠ dev install — re-run installer` (yellow): installed version > npm latest (typical for local dev).
+- `? /apt:update` (dim): package not yet published — you can still re-run the install to refresh from source.
+
+The cache file is at `~/.cache/aperant/apt-update-check.json`. It contains `runtimes`, `framework.installed_version`, `framework.latest_version`, `update_available`, `dev_install_ahead`, `not_published`, `stale_files_total`, and per-runtime `stale_files`.
+
+**Scope boundary (0.6.1).** `apt:update` refreshes installed runtime files (skills, agents, hooks) only — it does NOT reconcile `.aperant/config.json` against the shipped template. Schema drift (new keys added between framework versions, deprecated values, etc.) is detected and handled at the next `apt-tools init` call: in non-TTY mode `init` exits 2 with a `requires_input` envelope when a Class A setting is unresolved; in TTY mode the upgrade gate prompts for the missing keys before running the runtime install. If you suspect the user's config is out of date, point them at `apt-tools init . --accept-new-defaults` (Class B fills) or `apt-tools init . --yes` (full silent fill); a no-drift run returns `{"status":"up_to_date"}` without re-installing anything.
+</context>
+
+<process>
+
+## 1. Read current state
+
+```bash
+node .aperant/deps/node_modules/@aperant/framework/bin/apt-tools.mjs check-version . --json
+```
+
+Parse the JSON. Capture:
+- `framework.installed_version` — what's currently on disk
+- `framework.latest_version` — what's in the source / published
+- `runtimes[]` — list of installed runtime ids + per-runtime `stale_files` count
+- `stale_files_total` — drift tally across runtimes
+
+If `runtimes[]` is empty, tell the user they haven't installed Aperant into any runtime yet and suggest `apt-tools init . --claude` (or their preferred runtime). Stop.
+
+## 2. Classify the update scenario
+
+Pick ONE of three scenarios based on what you just parsed:
+
+- **A. Version bump available** — `installed_version !== latest_version` (regardless of drift). Users see this most often.
+- **B. Drift only** — `installed_version === latest_version` but `stale_files_total > 0`. User hand-edited an installed file or something was partially overwritten.
+- **C. Nothing to do** — `installed_version === latest_version` AND `stale_files_total === 0`. Still re-run init to refresh the update-check cache, but tell the user plainly that no changes were applied.
+
+## 3. Re-install the currently-installed runtimes
+
+Build the flags list from the runtime ids (e.g. `--claude --codex`) and run:
+
+```bash
+node .aperant/deps/node_modules/@aperant/framework/bin/apt-tools.mjs init . <flags>
+```
+
+Parse the init JSON. Capture for each runtime:
+- `install_root` (shortened to the basename, e.g. `.claude`)
+- `file_count`
+- Kernel status from `kernel.status` + `kernel.path` (resolves to `.aperant/deps/`)
+
+In autonomy 3 (YOLO) run immediately. In lower autonomy, skip the prompt too — `/apt:update` is idempotent by design and users who typed it already consented.
+
+## 4. Clear the update-check cache
+
+```bash
+rm -f ~/.cache/aperant/apt-update-check.json
+```
+
+The next SessionStart will repopulate it; until then, the statusline shows no chips.
+
+## 5. Emit the status summary
+
+Use the format in `<output_format>` below, tailored to the scenario from step 2. Nothing else. Do NOT dump the init JSON, do NOT recap the process, do NOT add a bulleted "what's new" list unless you have concrete facts from a local changelog.
+
+</process>
+
+<output_format>
+
+## Scenario A — version bump applied
+
+```
+✓ Aperant updated {installed_version} → {latest_version}
+
+  {install_root_basename}     {file_count} files refreshed
+  {install_root_basename}     {file_count} files refreshed
+  .aperant/deps/   kernel v{latest_version}
+
+  Next: restart Claude Code / Codex to activate the refreshed skills.
+```
+
+Example:
+```
+✓ Aperant updated 0.2.1 → 0.2.5
+
+  .claude/         47 files refreshed
+  .codex/          67 files refreshed
+  .aperant/deps/   kernel v0.2.5
+
+  Next: restart Claude Code / Codex to activate the refreshed skills.
+```
+
+## Scenario B — drift detected and fixed
+
+```
+⚠ Aperant had drift — refreshed
+
+  Detected:  {stale_files_total} stale files across {runtime list}
+  After:     all files match manifest
+
+  {install_root_basename}     {file_count} files ({stale_count} refreshed)
+  {install_root_basename}     {file_count} files
+
+  Statusline chip cleared.
+```
+
+## Scenario C — already up to date
+
+```
+✓ Aperant is up to date ({installed_version})
+
+  {install_root_basename}   {file_count} files
+  {install_root_basename}   {file_count} files
+
+  No changes applied. Statusline cache cleared.
+```
+
+## Scenario D — kernel install failed
+
+If init's `kernel.status !== "installed"`, append a warning ABOVE the summary:
+
+```
+⚠ Kernel refresh failed: {kernel.reason}
+  Manual fallback: npm install --prefix .aperant/deps @aperant/framework@{latest_version}
+
+[...scenario A/B/C summary as normal...]
+```
+
+Runtime files were still refreshed; `/apt` will still work from PATH if `apt-tools` is globally installed. The warning tells the user why the self-contained kernel didn't provision.
+
+</output_format>
+
+<edge_cases>
+
+- **No runtimes installed yet**: `check-version --json` returns an empty `runtimes` array. Tell the user to run `apt-tools init . --claude` (or their preferred runtime) first. Do not attempt the re-install.
+- **Worker hasn't run yet**: the cache file is missing. That's fine — run check-version directly (step 1 is robust to a missing cache). Proceed normally.
+- **Re-install fails (non-zero exit from init)**: surface the JSON `error` field verbatim in a single line, then stop. Do NOT delete the cache file — the chip should remain visible so the user sees the failure persists.
+- **Kernel install fails but runtime install succeeds**: see Scenario D above. Do not treat this as a total failure; the user's skills still work via PATH fallback.
+
+</edge_cases>