@aperant/framework 0.6.4 → 0.6.6

package/CHANGELOG.md

@@ -3,6 +3,44 @@
 All notable changes to `@aperant/framework` are documented here. See
 [`VERSIONING.md`](VERSIONING.md) for the per-tier contract.
 
+## 0.6.5 — 2026-05-14 — Drop aggregate envelope cap
+
+Replaces the aggregate `ENVELOPE_MAX_BYTES` cap in
+`src/cli/route/envelope.mjs` with a per-skill description budget. The
+aggregate cap was bumped 9 times in 3 weeks (8192 → 11264) and was
+theater on 1M-token hosts (30 skills × 256 bytes = 0.28 % of context).
+It was a proxy for two unrelated constraints — classifier precision
+(already measured by route-eval) and per-skill description quality
+(never actually enforced) — and shouted at the wrong author each time
+a new skill landed.
+
+- **New constant.** `MAX_DESCRIPTION_BYTES = 256` is exported from
+  `envelope.mjs`. The budget binds visible AND internal skills, so an
+  internal SKILL.md cannot ship a 4 KB description through the
+  side-channel.
+- **New helper.** `enforceDescriptionBudget(skills, budgetBytes)`
+  replaces `truncateLongestFirst`. It walks each skill once: passes
+  through if the wrapped description fits the budget; else tries
+  `truncateDescriptionToFirstSentence`; if the trim succeeds and now
+  fits, marks `truncated:true` and increments `truncated_count`; if the
+  trim still doesn't fit (or trim was a no-op), records the offender
+  (`{ name, bytes, description }`) and stops. The builder throws with
+  the offender named so the next fix lands on the right author the
+  first time.
+- **Error code rename.** The `cmdRoute` catch branch now emits
+  `error_code: 'skill_description_too_long'` (was `'envelope_overflow'`).
+- **Decision source.** Codex spar 2026-05-14.
+- **Tests.** `envelope-budget.test.ts`, `envelope-truncation.test.ts`,
+  and `route-envelope-builder.test.ts` rewritten for the per-skill
+  pathway. Aggregate-cap pins and the 400-byte headroom invariant are
+  gone.
+
+Schema unchanged (still v4). The router envelope JSON shape is
+unchanged for consumers — the only externally observable difference is
+the renamed error_code in the over-budget path.
+
+`task: 14-05-26_drop-aggregate-envelope-max-bytes-cap-fr-03rb`
+
 ## 0.6.4 — 2026-05-13 — Upgrade `--yes` infers visibility from git tracking
 
 Patch on top of 0.6.3 closing the last surface of the 0.6.0/0.6.1

package/README.md

@@ -3,246 +3,66 @@
 [![npm](https://img.shields.io/npm/v/@aperant/framework)](https://www.npmjs.com/package/@aperant/framework)
 [![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](LICENSE)
 
-AI coding framework -- composable skills for planning, executing, verifying, and reviewing code with any LLM provider.
+> **Work in progress.** This is the foundation that will run the Aperant ecosystem — an agentic IDE covering the full software lifecycle. Join the waitlist at [aperant.com](https://aperant.com).
 
-The Aperant Framework provides a structured methodology for AI-assisted software development. It works as slash commands in Claude Code, tasks in OpenAI Codex, or programmatically via the TypeScript API. One set of prompts, any AI tool.
-
-## What It Does
-
-Five composable skills that cover the full implementation lifecycle:
-
-| Skill   | Command        | Description                                                                         |
-| ------- | -------------- | ----------------------------------------------------------------------------------- |
-| Plan    | `/apt:plan`    | Analyze a task, assess complexity, investigate codebase, produce spec + implementation plan |
-| Execute | `/apt:execute` | Implement subtasks from a plan with atomic commits and progress tracking             |
-| Verify  | `/apt:verify`  | Score implementation against spec on 4 dimensions (correctness, completeness, quality, coverage) |
-| Review  | `/apt:review`  | Multi-pass AI code review with findings tree and severity classification             |
-| Run     | `/apt:run`     | Full pipeline: plan -> execute -> verify -> review in one command                    |
-
-Each skill is self-contained. Use `/apt:plan` alone for planning, `/apt:verify` alone for QA, or `/apt:run` for the full pipeline.
-
-### Declarative YAML Workflows (C17)
-
-In addition to the imperative skill chains above, the framework ships a
-**declarative** runner: author a YAML DAG of skill/agent/tool nodes and
-execute or emit it via `apt-tools wfrun {validate|plan|run}`. Example
-workflows live under `workflows/examples/`.
-
-## Quickstart
-
-### Step 1: Install
+## Install
 
 ```bash
 npx @aperant/framework init .
 ```
 
-This installs the framework's repo-local runtime surfaces:
-
-- Claude Code: `.claude/skills/` and `.claude/agents/`
-- Codex: `.agents/skills/`
-
-`apt-tools init` also stamps `.apt-version` in each skill directory so `check-version` and `health-check` can detect stale installs.
-
-### Alternative install: Claude Code plugin
-
-If you use Claude Code and prefer the `/plugin install` flow, Aperant ships as a first-class Claude Code plugin:
-
-```
-/plugin install aperant
-```
-
-Both install paths are supported and install the same skills — the plugin path also ships the `apt-*` sub-agents.
-
-### Step 2: Add project constitution (optional)
-
-Create an `AGENTS.md` file at your project root describing your tech stack, conventions, and constraints:
-
-```markdown
-# Project Constitution
-
-## Tech Stack
-- TypeScript, React 19, Tailwind 4
-- PostgreSQL with Drizzle ORM
-- Vitest for testing
-
-## Conventions
-- Prefer composition over inheritance
-- All API routes must have input validation
-- 80% test coverage minimum
-```
-
-The framework reads `AGENTS.md` to adapt its behavior -- plans respect your architecture, verification checks your conventions, reviews apply your standards.
-
-### Step 3: Plan a task
-
-In Claude Code, run:
-
-```
-/apt:plan "Add user authentication with JWT"
-```
-
-In Codex, invoke the matching repo skill:
-
-```
-$apt:plan Add user authentication with JWT
-```
-
-The framework assesses complexity, investigates your codebase for relevant patterns and files, writes a specification (`spec.md`), and creates a structured implementation plan (`implementation_plan.json`) with subtasks, dependencies, and verification steps.
-
-### Step 4: Full pipeline
-
-For the complete experience -- plan, execute, verify, and review in one command:
-
-```
-/apt:run "Add user authentication with JWT"
-```
-
-This creates a feature branch, plans the work, implements each subtask with atomic commits, verifies the result against the spec, and runs a multi-pass code review. From task description to reviewed code.
-
-## Host Support
-
-The framework supports Claude Code and Codex as native repo-local hosts.
-
-- Claude Code gets the full `.claude/skills` + `.claude/agents` payload, worktree support, structured prompt dialogs, and the optional PreCompact hook.
-- Codex gets native repo-skill discovery through `.agents/skills` and can run the framework's sub-agent flows, but it does not have the Claude-only worktree and PreCompact surfaces.
-- `/apt` track classification (QUICK/STANDARD/DEEP/DEBUG) is delegated to the host model inline via SKILL.md rather than a subprocess LLM call — no recursive `codex exec` from inside a Codex session.
-
-## How It Works
-
-The framework follows a 5-stage lifecycle (review is the terminal stage of the STANDARD/DEEP auto pipelines as of C32):
-
-```
-Context -> Plan -> Execute -> Verify -> Review
-```
-
-1. **Context** -- Read the project constitution (`AGENTS.md`), assess task complexity, investigate the codebase.
-2. **Plan** -- Write a specification and decompose into subtasks with dependencies and verification criteria.
-3. **Execute** -- Implement each subtask in dependency order. Atomic commits. Progress tracked in `build-progress.json`.
-4. **Verify** -- Score the implementation on 4 dimensions (correctness, completeness, quality, coverage). Write `qa_signoff.json`.
-5. **Review** -- Inline 6-pass review (logic / security / quality / architecture / performance / docs-coherence) with fix-all pipeline. `docs-drift` `auto-update` findings patched inline via `apt-tools docs-audit` / `apt-tools features-audit`; `flag-drift` findings surfaced to `review_findings.md`. Configure per-surface policy at `/apt:setup` Batch 7 (writes `.aperant/config.json.docs_policy`). Write `review.json`. Skip with `--skip-review` only if intentional.
-
-Each stage produces artifacts. The `apt-tools` CLI kernel handles state management -- file I/O, git commits, progress tracking -- so the LLM focuses on reasoning and code, never on plumbing.
-
-### Task-Level Worktree Isolation
-
-When multiple agents run tasks in parallel on the same repo, opt-in worktree isolation gives each task its own git branch and working directory. Enable it in `.aperant/config.json` with `"task_isolation": { "worktree_per_task": true }`. Each `task create` forks a branch, adds a worktree at `.aperant/worktrees/{scope}/{task-id}/`, and records the paths on the task record. Pipeline skills edit inside the worktree while `apt-tools` commands continue to target the main repo for shared state coordination.
-
-### Artifacts
-
-| Stage   | Artifact                    | Format   |
-| ------- | --------------------------- | -------- |
-| Plan    | `spec.md`                   | Markdown |
-| Plan    | `implementation_plan.json`  | JSON     |
-| Execute | `build-progress.json`       | JSON     |
-| Verify  | `qa_signoff.json`           | JSON     |
-| Review  | `review.json`               | JSON     |
-
-## Plugin System
-
-The framework uses a **manifest + mapper** architecture for extensibility.
-
-A plugin declares what artifacts each stage produces (the **manifest**) and provides JavaScript modules that translate those artifacts into standard UI shapes (the **mappers**). The Aperant app renders any framework's output through these normalized views -- a Kanban board for plans, a progress bar for execution, a verification dashboard for QA.
-
-This means you can build your own framework (or wrap an existing one like BMAD, SpecKit, etc.) and have it render natively in the Aperant UI.
-
-```typescript
-import type { FrameworkManifest } from "@aperant/framework/types";
-
-const manifest: FrameworkManifest = {
-  id: "my-framework",
-  name: "My Framework",
-  version: "1.0.0",
-  stages: [
-    {
-      stage: "plan",
-      artifacts: [
-        { nativeName: "plan.md", role: "plan", format: "markdown" }
-      ],
-      mapper: "./mappers/plan-mapper.js"
-    }
-  ]
-};
-```
-
-## Project Structure
-
-```
-packages/framework/
-  bin/apt-tools.mjs      # Deterministic CLI kernel
-  commands/               # Slash command definitions
-    plan.md              # /apt:plan
-    execute.md           # /apt:execute
-    verify.md            # /apt:verify
-    review.md            # /apt:review
-    run.md               # /apt:run
-  prompts/               # Agent prompt templates
-  src/                   # TypeScript types + mappers
-    types/               # FrameworkManifest, UI shapes, ProviderCapabilities
-    mappers/             # Reference mapper implementation
-  dist/                  # Built output (published to npm)
-```
-
-## Provider Independence
-
-The framework is provider-agnostic. It works with Claude, GPT-4o, o3, Codex, or any model that supports tool calling. The `ProviderCapabilities` type lets skills adapt prompting strategy per provider -- preferred structured format (XML for Claude, JSON for GPT), whether to use system prompts, context window limits -- without provider-specific code branches in the orchestration logic.
-
-```typescript
-import type { ProviderCapabilities } from "@aperant/framework/types";
-```
-
-## apt-tools CLI
-
-The `apt-tools` binary is the deterministic kernel. It handles operations that the LLM should never do itself:
-
-| Command                              | Description                                      |
-| ------------------------------------ | ------------------------------------------------ |
-| `apt-tools init <dir>`               | Install command files into a project              |
-| `apt-tools state <dir>`              | Read framework state                              |
-| `apt-tools constitution <dir>`       | Read project constitution (AGENTS.md / CLAUDE.md) |
-| `apt-tools cost <dir> [flags]`       | Cost tracking (per-task, trending, comparison)    |
-| `apt-tools tokens <record\|tally\|compare\|list> <dir>` | C11: per-task token telemetry — record actuals from a Claude Code transcript or manual `--input/--output`, tally a `TaskCostSummary`, compare against an optional baseline, and list across tasks |
-| `apt-tools commit <msg> --files ...` | Commit files with message                         |
-| `apt-tools task complete-subtask <dir>` | C33: atomic plan ↔ build-progress sync. Flips `implementation_plan.json.subtasks[].status` AND appends `build-progress.json.completed_subtasks` under one lock; supports consolidated ids like `E1+E2`. Used by `/apt:execute` §3e. |
-| `apt-tools docs-audit <dir>`         | C33: docs-coherence audit. External prose (CLAUDE.md / AGENTS.md / READMEs / docs/**) + internal state. Findings bucketed by policy from `.aperant/config.json.docs_policy`. |
-| `apt-tools features-audit <dir> [--apply-stubs]` | C33: features-registry audit. Detects new UI/core-service/hook/IPC files in a diff; `--apply-stubs` auto-registers them in `.aperant/features/<area>.json`. |
-| `apt-tools roadmap rollup <dir> --scope <s> --milestone <id>` | C33: recompute a single milestone's status from its phases. Idempotent. |
-| `apt-tools audit privacy <dir>`      | Diff tracked `.aperant/*` vs share policy (exit 2 on violations; `--scrub` emits `git filter-repo` commands + checklist, never executes) |
-| `apt-tools audit visibility-signals <dir>` | Structured JSON signals for `/apt:setup`'s visibility mini-flow (public-remote host, gitignore allow rules, current policy) |
-
-All output is JSON. No external dependencies -- pure Node.js.
-
-## Artifact Sharing Policy (C35)
-
-`.aperant/config.json` includes a `share` block that controls which framework
-artifacts are committed to git and which stay local. The resolved policy drives
-both the `.aperant/.gitignore` template and `apt-tools audit privacy`.
-
-```jsonc
-{
-  "share": {
-    "visibility": "solo",   // "solo" | "team" | "oss"
-    "roadmap": false,        // commit .aperant/roadmap/
-    "tasks": false,          // commit .aperant/tasks/*/ artifacts
-    "team": { "roster": false },  // commit .aperant/team.json
-    "decisions": false,      // commit .aperant/decisions/
-    "digests": null          // null = follow digests.enabled; or true/false
-  }
-}
-```
-
-Presets:
-
-- **`solo`** (default) — nothing shared. Byte-identical to the pre-C35 template.
-- **`team`** — roadmap + tasks + team.roster + decisions + digests shared with teammates.
-- **`oss`** — identical shape to `team` today; reserved for future divergence.
-
-`apt-tools init` resolves the effective policy, renders the `.aperant/.gitignore`
-from it, and warns when a public remote (github.com / gitlab.com / bitbucket.org)
-is combined with any sharing toggle.
-
-## Part of Aperant
-
-This framework powers the [Aperant IDE](https://github.com/Mikalsen-AI/aperant-cloud-desktop) -- an AI platform covering the full software lifecycle from idea to production and everything after. The same prompts and methodology used in the CLI are used inside the Aperant app. The framework is open source; the IDE adds a visual layer, collaboration features, and managed infrastructure on top.
+## Usage
+
+Just type `/apt` and describe what you want in natural language. The router classifies your input and dispatches to the right skill.
+
+```
+/apt add OAuth login with Google
+/apt the chat scroll is jittery — debug it
+/apt help me think through the new pricing model
+/apt typo in the footer — wrong year
+/apt review my PR
+```
+
+You can also call any skill directly (e.g. `/apt:plan ...`, `/apt:debug ...`).
+
+## Available commands
+
+| Stage | Command | Purpose |
+|---|---|---|
+| **Route** | `/apt` | Smart router — natural-language dispatch to any skill |
+| **Discovery** | `/apt:scan` | Build/refresh `.aperant/features/` registry |
+| **Discovery** | `/apt:zoom-out` | One-page architectural orientation for an unfamiliar area |
+| **Discovery** | `/apt:improve` | 3-lens scan for refactor opportunities (DEEPENING / INTERFACE-DESIGN / LANGUAGE) |
+| **Discovery** | `/apt:debug` | Systematic debugging with persistent state across context resets |
+| **Planning** | `/apt:discuss` | Brainstorm a vision or lock ambiguous decisions before planning |
+| **Planning** | `/apt:design` | Pre-coding wireframe → critique → handoff to `/apt:plan` |
+| **Planning** | `/apt:mockup` | Visual HTML+Tailwind mockup loop with parallel variants |
+| **Planning** | `/apt:plan` | Investigate codebase, produce `spec.md` + `implementation_plan.json` |
+| **Planning** | `/apt:roundtable` | 10-agent structured debate with supermajority voting |
+| **Planning** | `/apt:spar` | Bidirectional adversarial sparring with a second CLI provider |
+| **Planning** | `/apt:stress-test` | Scenario simulation to catch operational gaps before execution |
+| **Planning** | `/apt:prototype` | Question-driven throwaway prototyping (LOGIC + UI branches) |
+| **Build** | `/apt:quick` | Fast single-shot task — skip planning, go straight to implementation |
+| **Build** | `/apt:execute` | Build code from a plan with atomic commits and progress tracking |
+| **Build** | `/apt:run` | Full pipeline: plan → execute → verify → review in one command |
+| **Verify** | `/apt:verify` | 4-dimension QA scoring (correctness / completeness / quality / coverage) |
+| **Verify** | `/apt:verify-proof` | Visual proof verification — screenshots, video, HTML report |
+| **Verify** | `/apt:review` | 6-pass inline code review with fix-all pipeline |
+| **Verify** | `/apt:pr-review` | Multi-agent PR review — 6 parallel specialists + validator + fixer + self-reviewer |
+| **Ship** | `/apt:ship` | Create PR with QA scores, decision traceability, commit-to-subtask mapping |
+| **Ship** | `/apt:watch-ci` | Post-ship CI watcher — polls PR checks, auto-fixes red, pushes, reschedules |
+| **Ship** | `/apt:close-task` | Post-merge closer — confirm merged, flip phase, GC state |
+| **Session** | `/apt:pause` | Human-initiated handoff — save CONTINUE artifacts when you need to stop |
+| **Session** | `/apt:resume` | Restore context from paused session and route to next action |
+| **Docs** | `/apt:docs` | Generate/update documentation verified against the actual codebase |
+| **Docs** | `/apt:create-docs` | Persona-first product docs from PROJECT.md + personas.json + features registry |
+| **Docs** | `/apt:diagram` | Render a DiagramScene to `.excalidraw` file or live Excalidraw MCP canvas |
+| **Project** | `/apt:bootstrap` | Generate/refresh PROJECT.md (product-context source of truth) |
+| **Project** | `/apt:personas` | Discover 3–5 product personas grounded in code + PROJECT.md |
+| **Project** | `/apt:roadmap` | Manage per-scope milestones, phases, owners, ROADMAP.md rendering |
+| **Project** | `/apt:triage` | Move a task through the 5-state machine |
+| **Framework** | `/apt:setup` | Change preferences (verification style, multi-model, parallelization, branching) |
+| **Framework** | `/apt:update` | Refresh installed skills / agents / hooks across every runtime |
 
 ## License
 

package/agents/apt-improver.md

@@ -0,0 +1,99 @@
+---
+name: apt-improver
+description: Proactive refactor discovery agent — runs apt:improve Phase 1 (explore a named area through DEEPENING / INTERFACE-DESIGN / LANGUAGE lenses) and outputs a candidate refactor inventory. Read-only, no code changes.
+apt-skill-version: {{APT_VERSION}}
+tools: Read, Bash, Grep, Glob
+color: orange
+---
+
+<role>
+You are an Aperant Framework proactive-refactor agent. You scan a named
+area of the codebase through three lenses (DEEPENING, INTERFACE-DESIGN,
+LANGUAGE) and produce a candidate refactor inventory.
+
+Spawned by `/apt:improve` for Phase 1 (Explore). Phases 2 (Present
+candidates) and 3 (Deepen via grill loop) run in the parent agent
+context because they require user interaction.
+
+Your job: read the area, apply the three lenses, output a candidate
+inventory. You are READ-ONLY — no code changes, no decisions locked.
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the `Read`
+tool to load every file listed there before performing any other actions.
+</role>
+
+<project_context>
+**Project instructions:** Read `./CLAUDE.md` if it exists for project structure and conventions.
+**Constitution:** Read `AGENTS.md` if it exists for architecture overview.
+**Glossary:** Read `CONTEXT.md` if it exists — its term-blocks (especially `Aliases to avoid` fields) are direct inputs to the LANGUAGE lens.
+
+**Rationalizations (R4):** Read `.aperant/rationalizations/claude-opus-4-6.md` once at session start. Pay particular attention to R-2 (skipping pre-read investigation) and R-5 ("I already verified this implicitly"). As an improver, you only have value if your candidate inventory is grounded in actually-read code — drift here ships hallucinated refactor candidates.
+</project_context>
+
+<environment>
+- **Working directory:** The project root
+- **Note:** You have NO write/edit tools. You investigate and report findings only. Phase 2 (filter + present) and Phase 3 (deepen + lock) run in the parent agent's context.
+</environment>
+
+<process>
+
+## 1. Parse the area name
+
+Extract the area from the spawn prompt. Areas are noun phrases ("sparring engine", "feature registry", "auth flow") — not file paths.
+
+If the area is ambiguous, ask the parent ONE clarifying question via your report — do NOT enter a multi-turn interview.
+
+## 2. Load CONTEXT.md (if present)
+
+If `CONTEXT.md` exists at the project root, read it and extract:
+
+- Term-blocks whose canonical term, definition, or aliases-to-avoid match keywords in the area
+- The full alias list (LANGUAGE lens grep source)
+
+If CONTEXT.md does not exist, skip silently — the LANGUAGE lens runs without the alias grep but still catches in-file conflations.
+
+## 3. Apply the three lenses
+
+Read the lens descriptions (the parent has them in context; if you don't, read them from disk).
+Paths below are relative to the project root (monorepo: `<repo>/packages/framework/` is the
+framework root; standalone install: the project root IS the framework root, so use
+`skills/apt-improve/` directly):
+
+- `packages/framework/skills/apt-improve/DEEPENING.md` (monorepo) or `skills/apt-improve/DEEPENING.md` (standalone)
+- `packages/framework/skills/apt-improve/INTERFACE-DESIGN.md` (monorepo) or `skills/apt-improve/INTERFACE-DESIGN.md` (standalone)
+- `packages/framework/skills/apt-improve/LANGUAGE.md` (monorepo) or `skills/apt-improve/LANGUAGE.md` (standalone)
+
+For each lens, walk the area's files and flag candidates per the lens's red-flag list.
+
+## 4. Output the candidate inventory
+
+Produce a structured report:
+
+```markdown
+# apt:improve Phase-1 inventory — {area}
+
+## DEEPENING candidates
+- `{File}:{Symbol}` — shallow ({reason}); deletion-test target.
+- ...
+
+## INTERFACE-DESIGN candidates
+- `{Module A}` ↔ `{Module B}` — {red-flag name} ({one-line evidence}).
+- ...
+
+## LANGUAGE candidates
+- `{File}:{Line}` — uses `{wrong-term}` for `{canonical}` ({CONTEXT.md reference if applicable}).
+- ...
+
+## Files read
+- {file1}
+- ...
+```
+
+Keep the inventory grounded — every candidate must cite a file + symbol the user can grep for. No speculation; no candidates inferred from filenames alone.
+
+## 5. Hand back to parent for Phase 2/3
+
+Your output is the input to Phase 2 (the parent agent's filter step). Do NOT enter Phase 2 yourself — your role ends here.
+
+</process>

package/agents/apt-planner.md

@@ -199,7 +199,13 @@ If unable to enumerate (network unavailable, action docs unclear), flag it expli
 
 ## 4. Write Specification
 
-Create `{task_dir}/spec.md`:
+The spec.md content format **branches on track** (Pocock adoption ID-05,
+Fast Path Guarantee). QUICK-routed tasks keep the existing 4-section
+shape; STANDARD/DEEP/COMPLEX tasks get a PRD-shaped artifact that
+survives the task as a second-consumer document.
+
+### 4.A. QUICK track / SIMPLE complexity — legacy 4-section spec
+
 ```markdown
 # Task: {task description}
 
@@ -219,6 +225,57 @@ 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? Cite empirical evidence where possible.}
+
+## Solution
+{Chosen approach + bulleted net delta of files / flags / config / skills.}
+
+## User Stories
+{One **US-NN (persona).** story per user-value slice. Stories map 1:1
+onto subtasks in implementation_plan.json.}
+
+## Implementation Decisions
+{Load-bearing principles carried into every subtask. Format:
+"### ID-NN: {title}" + rationale + practical consequence.}
+
+## Testing Decisions
+{One block per test family: "### TD-NN: {family}" + what's covered +
+which subtask owns the test file. Fast Path regression tests MUST be
+enumerated here.}
+
+## Out of Scope
+{Non-goals. Each bullet names what is deferred + where it belongs.}
+
+## Further Notes
+{Sequencing rationale, risk surface, dependencies, files-affected
+preview, and any other executor-load-bearing context.}
+
+### Acceptance Criteria
+{Cross-cutting **AC1..ACN** list — each AC gets a stable ID. Subtasks
+reference these IDs via the per-subtask `acceptance_criteria` field.}
+```
+
+**PRD section ordering is load-bearing.** `apt-tools coverage-check
+validate` greps `## Acceptance Criteria`; `apt-tools consistency check`
+greps `## Solution` and `## User Stories`. Renaming or reordering these
+sections breaks downstream tooling and the C15 consistency rules.
+
+**Do NOT interview the user.** The PRD is synthesized from the task
+description + codebase investigation + AGENTS.md, not from a clarifying
+back-and-forth. If a section truly cannot be filled, write
+`{TBD — needs user input}`; do NOT pause for clarification (that is
+`apt:discuss`'s surface, not the planner's).
+
 ### 4.05. 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`. Shape:
@@ -275,12 +332,41 @@ fix it now, not later.
 
 ## 5. Create Implementation Plan
 
-Create `{task_dir}/implementation_plan.json`:
+Subtask schema branches on track (Pocock adoption ID-05 — Fast Path Guarantee).
+
+### 5.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.
+
+### 5.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",
@@ -308,29 +394,48 @@ Create `{task_dir}/implementation_plan.json`:
   "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` blocks the
+  executor pending human approval (autonomy 1 always pauses; autonomy 2
+  batches; autonomy 3 escalates only on conflict). `review` means the
+  human reviews the diff post-hoc, not blocking. `none` is agent-only.
+- `afk` — `"safe" | "unsafe"`. `safe` means proceed unattended. `unsafe`
+  means pause at the start of this subtask if no human is present
+  (autonomy < 3).
+- `acceptance_criteria` — `string[]` of id-refs (`"AC1"`, …) into spec.md's
+  `## Acceptance Criteria` section.
+- `user_value` — one-line framing of WHO benefits and HOW. Prevents
+  horizontal slicing — every subtask is a vertical user-shippable slice.
+
+Plan-level: `vertical_slice_schema_version: "1"` declares the schema
+version so future migrations can detect this plan as v1.
+
 Rules:
 - Each subtask completable in one focused session
 - Dependencies 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
-- `acceptance_criteria` is mandatory: list the canonical AC id-refs
-  (`"AC1"`, `"AC3"`, ...) from the `## Acceptance Criteria` section of
-  spec.md that this subtask satisfies. Verbatim AC text is accepted but
-  discouraged — the id-ref form is stable across spec edits. Every AC in
-  spec.md must be referenced by at least one subtask; gate G8
-  (`consistency-check`) enforces this on ship.
+- `acceptance_criteria` is mandatory on STANDARD/DEEP: every AC in spec.md
+  must be referenced by at least one subtask; gate G8
+  (`consistency-check`) enforces this on ship. Verbatim AC text is
+  accepted but discouraged — id-refs are stable across spec edits.
+- Subtask title MUST frame user value, not file scope.
 
 ### 5.1 Framework-scope doc-sync rule
 

package/dist/__test-helpers/run-cmd.d.mts

@@ -1,15 +1,17 @@
 /**
  * @param {Function} cmdFn — the Layer 1 cmd function (sync or async).
  * @param {unknown[]} [args=[]] — argv-shaped positional args.
- * @param {{ strictExit?: boolean, env?: Record<string, string> }} [opts]
- * @returns {Promise<{ result: unknown, stdout: string, exitCode: number }>}
+ * @param {{ strictExit?: boolean, resetCaches?: boolean, env?: Record<string, string> }} [opts]
+ * @returns {Promise<{ result: unknown, stdout: string, stderr: string, exitCode: number }>}
  */
 export function runCmd(cmdFn: Function, args?: unknown[], opts?: {
     strictExit?: boolean;
+    resetCaches?: boolean;
     env?: Record<string, string>;
 }): Promise<{
     result: unknown;
     stdout: string;
+    stderr: string;
     exitCode: number;
 }>;
 //# sourceMappingURL=run-cmd.d.mts.map

package/dist/__test-helpers/run-cmd.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"run-cmd.d.mts","sourceRoot":"","sources":["../../src/__test-helpers/run-cmd.mjs"],"names":[],"mappings":"AAiCA;;;;;GAKG;AACH,+CAJW,OAAO,EAAE,SACT;IAAE,UAAU,CAAC,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GACpD,OAAO,CAAC;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAoD1E"}
+{"version":3,"file":"run-cmd.d.mts","sourceRoot":"","sources":["../../src/__test-helpers/run-cmd.mjs"],"names":[],"mappings":"AAiDA;;;;;GAKG;AACH,+CAJW,OAAO,EAAE,SACT;IAAE,UAAU,CAAC,EAAE,OAAO,CAAC;IAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAC3E,OAAO,CAAC;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAiF1F"}