@aperant/framework 0.6.4 → 0.6.6

package/skills/apt-plan/SKILL.md

@@ -110,7 +110,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 +141,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 +295,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",
+  "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": "simple|standard|complex",
+  "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 +416,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/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`.

package/skills/apt-planner.md

@@ -59,7 +59,10 @@ For STANDARD and COMPLEX tasks:
 
 ## 4. Write Specification
 
-Create `{task_dir}/spec.md`:
+Content format branches on track (Pocock adoption ID-05, Fast Path Guarantee).
+
+### 4.A. QUICK track / SIMPLE complexity — legacy 4-section spec
+
 ```markdown
 # Task: {task description}
 
@@ -79,6 +82,44 @@ Create `{task_dir}/spec.md`:
 {What this task explicitly does NOT cover}
 ```
 
+### 4.B. STANDARD / DEEP / COMPLEX — PRD-shaped spec.md
+
+```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?}
+
+## Solution
+{Chosen approach + bulleted net delta.}
+
+## User Stories
+{**US-NN (persona).** stories, 1:1 onto subtasks.}
+
+## Implementation Decisions
+{### ID-NN load-bearing principles.}
+
+## Testing Decisions
+{### TD-NN test families. Fast Path regressions enumerated here.}
+
+## Out of Scope
+{Non-goals with deferral target.}
+
+## Further Notes
+{Sequencing, risk surface, dependencies, files-affected preview.}
+
+### Acceptance Criteria
+{**AC1..ACN** stable IDs referenced by subtasks.}
+```
+
+PRD section ordering is load-bearing — downstream tooling greps by header.
+Do NOT interview the user; synthesize from task description + codebase +
+AGENTS.md.
+
 ## 5. Create Implementation Plan
 
 Create `{task_dir}/implementation_plan.json`:

package/skills/apt-pr-review/SKILL.md

@@ -1454,33 +1454,63 @@ node packages/framework/bin/apt-tools.mjs workflow advance . --id ${REVIEW_ID} -
 
 If `WORKTREE_PATH != .` AND fixes were applied in Phase 6/7:
 
+Get the PR head ref (for branch reviews, use the branch name directly):
 ```bash
-cd ${WORKTREE_PATH}
+PR_HEAD_REF=$(gh pr view ${PR_NUMBER} --json headRefName -q .headRefName)
+```
 
-# Commit all staged fixes
-git add -A
-git commit -m "fix: auto-fix review findings from /apt:pr-review (review ${REVIEW_ID})"
+#### Confirmation gate (BUG-009 fix)
 
-# Push fixes back to the PR branch
-# For PRs: push to the PR's head ref
-git push origin HEAD:${PR_HEAD_REF}
+Whether the push prompts for confirmation is controlled by `pr_review.confirm_before_push` in `.aperant/config.json` (tri-state: `ask` | `auto` | `never`; default when absent: `auto` at autonomy ≥ 2, `ask` at autonomy < 2). Mirrors the `pr_review.suggest_after_ship` precedent in `/apt:ship` Section 7.1 — `ask` is honest about the irreversible-ish nature of the push (re-triggers CI on origin, visible to teammates); `auto` honors yolo pipelines.
 
-cd -
+```bash
+confirm_mode=$(jq -r '.pr_review.confirm_before_push // empty' .aperant/config.json)
+autonomy=$(jq -r '.autonomy.default // 2' .aperant/config.json)
+if [ -z "$confirm_mode" ]; then
+  if [ "${autonomy}" -ge 2 ]; then confirm_mode="auto"; else confirm_mode="ask"; fi
+fi
 ```
 
-Where `PR_HEAD_REF` is the PR's head branch name (e.g., `feat/auth`). Get it from:
+Branch on `confirm_mode`:
+
+- **`never`** — Skip push entirely. Print "fixes left in worktree; push manually with `git -C ${WORKTREE_PATH} push origin HEAD:${PR_HEAD_REF}`". Proceed to Step 0b cleanup.
+- **`auto`** — Proceed silently to the catch-all + push below. No prompt.
+- **`ask`** — Emit the structured question: `Fixes are ready in the worktree. Push to ${PR_HEAD_REF}? (y/n)`. On `n` or any non-`y`: same skip behavior as `never`. On `y` (or empty enter): proceed.
+
+`confirm_before_push` is purely additive — it does not affect `authorship_override`, `authorship_overrides`, `max_rounds`, or `suggest_after_ship` in the same `pr_review` block.
+
+#### Catch-all + push (BUG-010 fix)
+
+The fixer pipeline normally produces atomic per-finding commits, so the worktree is clean by the time Step 0 runs. The catch-all commit below exists ONLY to capture uncommitted residue (rare — e.g. a fixer's pre-return self-audit failed to detect a stray edit). Guard it before committing:
+
 ```bash
-gh pr view ${PR_NUMBER} --json headRefName -q .headRefName
-```
+cd ${WORKTREE_PATH}
 
-For branch reviews: push to the branch name directly.
+# Guard 1: skip the catch-all entirely if the tree is clean.
+# Per-finding commits with proper messages are strictly better history than a single catch-all.
+if ! git diff --quiet || ! git diff --cached --quiet || [ -n "$(git ls-files --others --exclude-standard)" ]; then
+  # Guard 2: explicit allowlist instead of `git add -A`.
+  # `git add -A` would sweep orchestrator-level Read/Write side-effects
+  # (metadata.json, audit.json, validated.md, etc.) into the PR. Bad.
+  # Stage ONLY files in the review's touched set, computed from the iteration diffs.
+  REVIEW_TOUCHED=$(git diff --name-only ${ITERATION_START_SHA:-HEAD~4}..HEAD 2>/dev/null \
+                   | grep -v '^\.aperant/' \
+                   | tr '\n' ' ')
+  if [ -n "$REVIEW_TOUCHED" ]; then
+    # shellcheck disable=SC2086
+    git add -- $REVIEW_TOUCHED
+  fi
+  # Only commit if `git add --` actually staged something.
+  if ! git diff --cached --quiet; then
+    git commit -m "fix: auto-fix review findings from /apt:pr-review (review ${REVIEW_ID})"
+  fi
+fi
 
-**IMPORTANT:** Ask the user for confirmation before pushing:
-```
-Fixes are ready in the worktree. Push to ${PR_HEAD_REF}? (y/n)
+git push origin HEAD:${PR_HEAD_REF}
+cd -
 ```
 
-If the user declines, skip the push but still write the report. The fixes remain in the worktree for manual review.
+Two guards. The outer `if` skips the whole catch-all path when the tree is clean. The inner allowlist (filter to files in the iteration-diff scope, minus anything under `.aperant/`) prevents `git add` from sweeping arbitrary orchestrator side-effects into the PR. Both guards default to the safe no-op shape on the happy path (fixers committed atomically, clean tree).
 
 ### Step 0b: Cleanup Worktree
 

package/skills/apt-prototype/LOGIC.md

@@ -0,0 +1,109 @@
+<!--
+Adapted from Matt Pocock's MIT-licensed skill suite:
+https://github.com/mattpocock/skills/blob/main/skills/engineering/prototype/LOGIC.md
+Licensed under MIT. Modifications: scoped to terminal-app prototypes
+that validate state machines, protocols, and control flow. Aligned with
+the 5 universal rules in apt-prototype/SKILL.md.
+-->
+
+# LOGIC branch — Terminal app for state-machine validation
+
+When the user's question is about **behavior**, the prototype is a
+single terminal app that the user runs and watches. The output prints
+every state transition so the user can FEEL whether the logic works,
+not just reason about it.
+
+## When this branch fires
+
+Question types that route here:
+
+- "Does this state machine work?"
+- "Does this control flow handle edge case X?"
+- "Can this protocol handle out-of-order messages?"
+- "What does the worker pool do under back-pressure?"
+- "Does this retry policy actually converge?"
+
+Question types that DO NOT route here (use UI branch instead):
+
+- "Does this UI shape feel right?"
+- "Is this flow discoverable?"
+- "Does this layout work on mobile?"
+
+## File shape
+
+ONE file. Pick the project's primary runtime (TypeScript via `tsx`,
+JavaScript via `node`, Python via `python3`, etc.). The shape:
+
+```
+// THROWAWAY PROTOTYPE — do not merge, do not extend, do not test.
+// Question: "{verbatim question from user}"
+// Decision criterion: "{what does 'yes' look like? what does 'no' look like?}"
+
+// --- State machine model ---
+// {Declare states, transitions, and any guards.}
+
+// --- Transition driver ---
+// {A function that takes (currentState, event) and returns nextState,
+//  PRINTING every transition so the user can see what's happening.}
+
+// --- Scripted run ---
+// {5-10 sequential transitions that exercise the interesting paths.}
+```
+
+## Single-command invocation
+
+The prototype runs with ONE command. Examples:
+
+- `node prototype.mjs` — no transpile, no build, no install
+- `pnpm dlx tsx prototype.ts` — uses dlx so no dependency added to the project
+- `python3 prototype.py` — no virtualenv setup
+
+If your prototype needs any of: webpack, vite, esbuild, a database
+connection, an environment variable — you are prototyping the wrong
+question. Re-scope to the BEHAVIOR question; the infrastructure is a
+separate concern.
+
+## Surface-state-transparently — concrete examples
+
+A terminal app prints state transitions inline:
+
+```
+[T+0]  state=IDLE
+[T+1]  event=user.click.submit → state=SUBMITTING
+[T+2]  event=network.timeout → state=RETRYING (attempt 1)
+[T+3]  event=network.timeout → state=RETRYING (attempt 2)
+[T+4]  event=network.timeout → state=FAILED (exceeded retries)
+```
+
+The user reads this output and either says "yes that's what I wanted"
+or "no, the retry policy needs jitter" — and the question is answered
+in 30 seconds of looking, not 3 hours of staring at a flowchart.
+
+If the state machine has parallel regions or hierarchical states, print
+the full state vector at each transition, not just the leaf state.
+
+## When the scripted run isn't enough
+
+If the user needs to drive the state machine interactively (the
+question is "what happens when I hit submit twice quickly?"), add a
+tiny REPL loop:
+
+```
+> submit
+[T+1] event=user.click.submit → state=SUBMITTING
+> submit
+[T+2] event=user.click.submit (REJECTED — already submitting)
+[T+2] state=SUBMITTING
+> timeout
+[T+3] event=network.timeout → state=RETRYING (attempt 1)
+```
+
+Keep the REPL parser dumb (split on space, no quoting, no escape
+handling). The user isn't testing your parser; they're testing the
+state machine.
+
+## Throwaway discipline reminder
+
+When the question is answered, delete the prototype file. Do not let it
+linger as "documentation of the design decision" — that's what
+`apt-tools adr write` or `.aperant/context/notes/` are for.