@aperant/framework 0.6.4 → 0.6.5

package/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/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.
 

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.