@aperant/framework 0.6.3 → 0.6.5

package/skills/apt-plan/SKILL.md

@@ -9,6 +9,8 @@ user_invocable: true
 internal: false
 spawns_agent: true
 agent_name: "apt-planner"
+task_context: create-new
+default_track: STANDARD
 default_execution_mode: auto
 execution_modes:
   - auto
@@ -108,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}
@@ -129,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:
@@ -210,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

@@ -9,6 +9,7 @@ user_invocable: true
 internal: false
 spawns_agent: false
 agent_name: null
+task_context: self-managed
 default_execution_mode: auto
 execution_modes:
   - auto
@@ -1453,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.

package/skills/apt-prototype/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: apt:prototype
+description: "Question-driven throwaway prototyping with 5-rule discipline — LOGIC branch (terminal-app for state-machine validation) and UI branch (delegates to apt:mockup)"
+apt-skill-version: {{APT_VERSION}}
+stage: design
+intent: design
+when_to_use: "The user has a question that wants a runnable prototype rather than a plan — 'does this state machine work?' (LOGIC branch) or 'does this UI shape feel right?' (UI branch). Throwaway code by design; do NOT confuse this with apt:plan or apt:execute."
+user_invocable: true
+internal: false
+spawns_agent: false
+agent_name: null
+task_context: create-new
+default_track: STANDARD
+default_execution_mode: step
+execution_modes:
+  - auto
+  - step
+allowed-tools: "Bash, Read, Write, Edit, Grep, Glob"
+argument-hint: "apt:prototype [question]"
+gates: []
+config_keys:
+  - coding.prototype_discipline
+---
+
+# Prototype — Question-Driven Throwaway Code
+
+This skill ships throwaway code that answers ONE question. It is NOT a
+planning artifact, NOT a feature, and NOT something to merge. The output
+is a single-command-runnable prototype that lets the user feel whether
+the question's answer is "yes" or "no", then gets thrown away.
+
+**Pocock adoption attribution.** Discipline ported from Matt Pocock's
+MIT-licensed `prototype` skill. Routes between two branches by
+question-type; the UI branch delegates to Aperant's existing
+`/apt:mockup` skill for HTML+Tailwind variants. The LOGIC branch and
+the 5-rule discipline are new for Aperant.
+
+## When to Use
+
+- The user asks a question (not a "build me X" request) — "does this
+  state machine work?", "does this UI shape feel right?", "would users
+  find this discoverable?"
+- A throwaway prototype is the cheapest answer (cheaper than designing,
+  planning, building, then discovering the answer was "no")
+- The answer can be felt by running the prototype, not just reasoning
+  about it
+
+## When NOT to Use
+
+- The user has a feature request — use `/apt:plan` + `/apt:execute`
+- The user wants a polished mockup to share — use `/apt:mockup` directly
+  (the UI branch of this skill delegates there anyway)
+- The user wants production code with tests — that's TDD-mode
+  `/apt:execute --tdd`, not a prototype
+
+## Branch routing
+
+Inspect the user's question:
+
+- **LOGIC branch** — triggers: "does this state machine work?", "does
+  this control flow handle edge case X?", "can this protocol handle
+  out-of-order messages?". Answer: a single-file terminal app the user
+  can run with one command to feel the state transitions.
+- **UI branch** — triggers: "does this UI shape feel right?", "is this
+  flow discoverable?", "does this layout work on mobile?". Answer:
+  delegate to `/apt:mockup --variants 3` for HTML+Tailwind parallel
+  variants.
+
+If the question is genuinely ambiguous, ask ONE clarifying question
+("are you asking about behavior or appearance?") — do NOT enter a long
+interview.
+
+## The 5 Universal Rules (Pocock discipline, applies to both branches)
+
+These five rules apply to EVERY prototype this skill produces. They are
+load-bearing — violating them collapses the prototype into ceremony
+disguised as a question.
+
+1. **Throwaway-marked.** Every prototype file MUST carry a top-of-file
+   comment: `// THROWAWAY PROTOTYPE — do not merge, do not extend, do
+   not test.` This is not optional. Files without this marker drift into
+   production code and the question never gets answered cleanly.
+
+2. **Single-command-run.** The prototype runs with ONE command. No
+   build step. No dependency install. `node prototype.mjs` or `pnpm dlx
+   tsx prototype.ts` or `bash prototype.sh` — pick one and stop. If you
+   reach for webpack, you're prototyping a build, not the question.
+
+3. **No-persistence-default.** The prototype does NOT touch any
+   persistent store (libSQL, Convex, localStorage, .aperant/state.json).
+   Everything is in-memory. If persistence is part of the question,
+   explicitly opt in via a tmpfile — never the project's actual stores.
+
+4. **Skip-polish.** No error handling for impossible scenarios. No
+   accessibility audit. No mobile responsive breakpoints unless the
+   question is about mobile. No animation refinement. Polish is what
+   you do AFTER the prototype answered "yes"; doing it now obscures
+   whether the answer was actually "yes".
+
+5. **Surface-state-transparently.** The prototype prints / renders its
+   internal state at every step the user might want to inspect. A
+   terminal app prints every state transition. A UI prototype shows
+   the data shape next to the rendered output. The user must be able
+   to SEE what's happening — they can't feel an answer to "does this
+   work" if the state is hidden.
+
+## LOGIC branch — terminal app for state-machine validation
+
+When the question is about behavior / control flow / state machines /
+protocols:
+
+1. Read `LOGIC.md` for the discipline (ported from Pocock's
+   `prototype/LOGIC.md` with MIT attribution).
+2. Write ONE file (e.g., `prototype.mjs`, `prototype.ts`, or
+   `prototype.py`) that:
+   - Models the state machine in code
+   - Provides a command-line driver that fires transitions one at a
+     time, printing each state
+   - Includes a 5-10 turn scripted run at the bottom that exercises the
+     interesting paths
+3. Write a one-line invocation: `node prototype.mjs` (or whatever).
+4. Verify: run it. The user reads the output, gets their answer, and
+   the file is deleted.
+
+## UI branch — delegates to apt:mockup
+
+When the question is about layout / aesthetics / flow / discoverability:
+
+1. Read `UI.md` for the discipline (ported from Pocock's
+   `prototype/UI.md` with MIT attribution).
+2. Invoke `/apt:mockup --variants 3` as a sub-step. apt:mockup already
+   enforces the UI-specific universal rules (zero-dep Tailwind CDN, no
+   JS, throwaway HTML iterations preserved).
+3. The 5 universal rules above still apply — verify each HTML file
+   carries the `<!-- THROWAWAY PROTOTYPE -->` marker.
+
+## Output contract
+
+- Single prototype file (LOGIC) OR 3 HTML variants via apt:mockup (UI).
+- No commits. No tests. No docs. The skill emits a final note: "Delete
+  this when the question is answered."
+- If the user wants to convert the prototype into real code, that's a
+  separate `/apt:plan` invocation.