@aperant/framework 0.6.4 → 0.6.5

package/dist/plugin/skills/apt-ship/SKILL.md

@@ -9,6 +9,7 @@ user_invocable: true
 internal: false
 spawns_agent: false
 agent_name: null
+task_context: require-existing
 default_execution_mode: auto
 execution_modes:
   - auto
@@ -288,6 +289,8 @@ Capture the PR URL from the output into `pr_url` (for example, the last line of
 node packages/framework/bin/apt-tools.mjs task update . --id {task-id} --pr-url {PR_URL}
 ```
 
+This same call **atomically flips `lifecycle_phase` from `reviewing` to `shipped-pending-merge`** when the task is in `reviewing` and no explicit `--lifecycle-phase` flag is passed. Section 6 is now the single load-bearing step that both records the PR and transitions the lifecycle; Section 8 below documents the semantics but no longer issues a separate command.
+
 Display the resolution so users see which branch/base was used:
 
 ```
@@ -338,7 +341,7 @@ suggest_mode=$(jq -r '.pr_review.suggest_after_ship // "always"' .aperant/config
   ```
   [APT:ship] Run /apt:pr-review --pr {pr_number} now for deep multi-agent review? [Y/n]
   ```
-  On `Y` (or empty enter), invoke `/apt:pr-review --pr {pr_number}` inline after Section 8 flips the task to `shipped-pending-merge` — do NOT block the lifecycle transition. On `N` or any other response, proceed silently to Section 8.
+  On `Y` (or empty enter), invoke `/apt:pr-review --pr {pr_number}` inline — the task has already been flipped to `shipped-pending-merge` atomically by the `--pr-url` recording in Section 6, so the deep-review hint does NOT need to block on Section 8. On `N` or any other response, proceed silently to Section 8.
 
 - **`never`** — silent. Proceed directly to Section 8.
 
@@ -346,11 +349,9 @@ suggest_mode=$(jq -r '.pr_review.suggest_after_ship // "always"' .aperant/config
 
 ## 8. Transition lifecycle to `shipped-pending-merge` (C56 B5)
 
-Ship is NOT the final closer. The PR has just been opened — it won't merge for minutes, hours, or days, and no agent will be present on merge. Instead of closing the task now, flip its lifecycle to `shipped-pending-merge` — the intermediate state between `reviewing` and `completed`. `/apt:close-task` runs post-merge (either manually via `/apt:close-task --all` or by the user when they return to the repo) and performs the actual closeout: phase flip, documentation narration, worktree GC, per-PR config strip, task archive.
+Ship is NOT the final closer. The PR has just been opened — it won't merge for minutes, hours, or days, and no agent will be present on merge. The task lifecycle is now `shipped-pending-merge` — the intermediate state between `reviewing` and `completed`. `/apt:close-task` runs post-merge (either manually via `/apt:close-task --all` or by the user when they return to the repo) and performs the actual closeout: phase flip, documentation narration, worktree GC, per-PR config strip, task archive.
 
-```bash
-node packages/framework/bin/apt-tools.mjs task update . --id {task-id} --lifecycle-phase shipped-pending-merge
-```
+Section 6 already performed this transition atomically as part of `task update --pr-url`. This section documents the semantics; no separate command is required.
 
 The task stays in `state.active_tasks[*]` with `lifecycle_phase: "shipped-pending-merge"`. Do NOT call `task close` here — that would mark it `completed` before the PR is actually merged, producing the same artifact drift C56 was built to eliminate.
 

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

@@ -9,6 +9,7 @@ user_invocable: true
 internal: false
 spawns_agent: false
 agent_name: null
+task_context: require-existing
 default_execution_mode: step
 execution_modes:
   - auto

package/dist/plugin/skills/apt-terminal/SKILL.md

@@ -9,6 +9,7 @@ user_invocable: true
 internal: false
 spawns_agent: false
 agent_name: null
+task_context: none
 default_execution_mode: step
 execution_modes:
   - auto

package/dist/plugin/skills/apt-update/SKILL.md

@@ -9,6 +9,7 @@ user_invocable: true
 internal: false
 spawns_agent: false
 agent_name: null
+task_context: none
 default_execution_mode: auto
 execution_modes:
   - auto
@@ -33,6 +34,8 @@ The user invoked `/apt:update` because the statusline showed one of:
 - `? /apt:update` (dim): package not yet published — you can still re-run the install to refresh from source.
 
 The cache file is at `~/.cache/aperant/apt-update-check.json`. It contains `runtimes`, `framework.installed_version`, `framework.latest_version`, `update_available`, `dev_install_ahead`, `not_published`, `stale_files_total`, and per-runtime `stale_files`.
+
+**Scope boundary (0.6.1).** `apt:update` refreshes installed runtime files (skills, agents, hooks) only — it does NOT reconcile `.aperant/config.json` against the shipped template. Schema drift (new keys added between framework versions, deprecated values, etc.) is detected and handled at the next `apt-tools init` call: in non-TTY mode `init` exits 2 with a `requires_input` envelope when a Class A setting is unresolved; in TTY mode the upgrade gate prompts for the missing keys before running the runtime install. If you suspect the user's config is out of date, point them at `apt-tools init . --accept-new-defaults` (Class B fills) or `apt-tools init . --yes` (full silent fill); a no-drift run returns `{"status":"up_to_date"}` without re-installing anything.
 </context>
 
 <process>
@@ -67,6 +70,8 @@ Build the flags list from the runtime ids (e.g. `--claude --codex`) and run:
 node .aperant/deps/node_modules/@aperant/framework/bin/apt-tools.mjs init . <flags>
 ```
 
+**Do NOT add `--yes`, `--solo`, `--team`, or any other Class A flag.** This command is meant to refresh runtime files only — adding `--yes` triggers a config schema migration that can silently flip `share.visibility` to `solo` and re-write `.gitignore`, which is exactly the 0.6.0/0.6.1 dogfood bug. If `init` returns a `requires_input` envelope (schema drift), surface it to the user verbatim and stop; let them decide team vs solo with the explicit flag. From 0.6.4 onward `--yes` infers visibility from existing git tracking, but the skill must still not add it — keep this command scoped to runtime refresh.
+
 Parse the init JSON. Capture for each runtime:
 - `install_root` (shortened to the basename, e.g. `.claude`)
 - `file_count`

package/dist/plugin/skills/apt-verify/SKILL.md

@@ -9,6 +9,7 @@ user_invocable: true
 internal: false
 spawns_agent: true
 agent_name: "apt-verifier"
+task_context: require-existing
 default_execution_mode: auto
 execution_modes:
   - auto

package/dist/plugin/skills/apt-verify-proof/SKILL.md

@@ -9,6 +9,7 @@ user_invocable: true
 internal: false
 spawns_agent: false
 agent_name: null
+task_context: require-existing
 default_execution_mode: auto
 execution_modes:
   - auto

package/dist/types/config.d.ts

@@ -6,6 +6,15 @@
  */
 /** Orchestration mode — how the framework delegates work across phases */
 export type OrchestrationMode = 'auto' | 'agent-team' | 'sub-agents' | 'sequential';
+/** Track-specific orchestration overrides — roundtable 2026-05-14 R7 */
+export interface PerTrackOrchestrationConfig {
+    /** QUICK track: small fix / typo / single-file edit. Default 'sequential'. */
+    quick?: OrchestrationMode;
+    /** STANDARD track: normal feature work. Default 'sequential' per R2. */
+    standard?: OrchestrationMode;
+    /** DEEP track: multi-package refactor, schema, security. Default 'auto'. */
+    deep?: OrchestrationMode;
+}
 /** Orchestration preferences — how multi-agent workflows are executed */
 export interface OrchestrationConfig {
     /** How pipeline phases are delegated (plan → execute → verify → review) */
@@ -14,6 +23,23 @@ export interface OrchestrationConfig {
     review_mode: OrchestrationMode;
     /** How roundtable debates are orchestrated (apt:roundtable 10 agents) */
     debate_mode: OrchestrationMode;
+    /**
+     * Per-track phase_delegation overrides. When a `--track <quick|standard|deep>`
+     * flag is passed to `apt-tools reconcile` AND `per_track[track]` is set, the
+     * reconciler uses that value as the requested mode for `phase_delegation`.
+     * When unset (the default), the resolver falls back to the global
+     * `phase_delegation` field — backward-compatible.
+     *
+     * Initial defaults (roundtable 2026-05-14 R7):
+     *   per_track.quick    = 'sequential'
+     *   per_track.standard = 'sequential'  (R2 — verify uses de-anchored re-read)
+     *   per_track.deep     = 'auto'        (R4 status quo, resolves to agent-team)
+     *
+     * Exit condition documented in REPORT.md: if STANDARD verify quality drops
+     * >0.5 points across 10+ tasks, flip `per_track.standard` to `'sub-agents'`
+     * (R3 — the named fallback).
+     */
+    per_track?: PerTrackOrchestrationConfig;
 }
 /** Capabilities reported by host-detect */
 export interface HostCapabilities {
@@ -144,8 +170,12 @@ export interface AperantConfig {
     router?: RouterConfig;
     /** PR-review authorship + round budget (R4 + R5) */
     pr_review?: PrReviewConfig;
+    /** Post-ship CI watcher — `/apt:watch-ci` (C28 / D-07) */
+    ci_watch?: CiWatchConfig;
     /** TDD Iron Law — opt-in red-green-refactor enforcement (C3) */
     tdd?: TddConfig;
+    /** Diagram skill defaults (apt:diagram) — render mode + MCP consent */
+    diagram?: DiagramConfig;
 }
 /**
  * TDD Iron Law configuration (C3).
@@ -158,6 +188,29 @@ export interface TddConfig {
     /** When true, enforce test-first commit order per subtask */
     iron_law: boolean;
 }
+/**
+ * Diagram skill configuration (apt:diagram v1).
+ *
+ * `mode` is the persisted default render mode — `file` writes a local
+ * `.excalidraw` JSON, `mcp` dispatches to a live Excalidraw MCP canvas.
+ * The skill's `--mode=...` invocation flag overrides this at call time.
+ *
+ * `mcpConsent` is the per-host consent record for MCP mode. Default
+ * `null` means no host has been granted consent yet — the skill must
+ * prompt and persist on the first MCP-mode invocation. The same host
+ * does not re-prompt; a different host invalidates the existing record
+ * and re-prompts.
+ */
+export interface DiagramConfig {
+    /** Resolved default render mode (overridable per-call by --mode=...) */
+    mode: 'file' | 'mcp';
+    /** Per-host MCP consent record; null means not yet asked */
+    mcpConsent: {
+        host: string;
+        decision: 'granted' | 'denied';
+        grantedAt: string;
+    } | null;
+}
 /** Per-host LLM provider settings for router Stage 2 classification */
 export interface RouterLLMProviderConfig {
     /** CLI command to invoke (argv[0]). e.g. "claude", "codex", "gemini" */
@@ -218,4 +271,36 @@ export interface PrReviewConfig {
      */
     suggest_after_ship?: 'always' | 'ask' | 'never';
 }
+/**
+ * Post-ship CI watcher config (C28 / D-07, D-08).
+ *
+ * `/apt:watch-ci` polls a freshly-shipped PR's CI on a recurring tick,
+ * auto-fixes red checks from first red, pushes the fix, and reschedules
+ * itself — bounded by a 5-attempt / 4h wall budget and a 10-trigger stop
+ * matrix. See `.aperant/context/notes/framework-post-ship-ci-watcher.md`
+ * for the locked D-01..D-08 decisions.
+ */
+export interface CiWatchConfig {
+    /**
+     * Post-ship arming policy controlled by `/apt:ship` Section 7.2:
+     *   'auto'  — arm the watcher automatically (the default on cron-capable
+     *             hosts: Claude Code, Pi). On non-cron hosts (Codex, Gemini,
+     *             OpenCode, etc.) `auto` creates the state file but does not
+     *             register a host cron; the user advances via `/apt:watch-ci
+     *             --tick`.
+     *   'ask'   — prompt `[Y/n]` after ship. Autonomy=3 degrades 'ask' → 'auto'
+     *             for one fewer prompt in unattended chains.
+     *   'never' — silent (the default on non-cron hosts).
+     * Absent → ship hook derives the default from host capability.
+     */
+    after_ship?: 'auto' | 'ask' | 'never';
+    /**
+     * On all-green CI, auto-merge the PR via `gh pr merge --auto --squash`.
+     * Default `false` — the watcher prints a merge hint and leaves the merge
+     * decision to the user (matches the user's stated rhythm). Flip to `true`
+     * once a calendar week of clean post-launch usage shows zero false-green
+     * merges (D-08 kill criteria).
+     */
+    auto_merge_on_green?: boolean;
+}
 //# sourceMappingURL=config.d.ts.map

package/dist/types/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,126 +1,126 @@
 {
-	"name": "@aperant/framework",
-	"version": "0.6.4",
-	"description": "AI coding framework — composable skills for planning, executing, verifying, and reviewing code with any LLM provider. Works as Claude Code commands, Codex tasks, or programmatically.",
-	"author": "Mikalsen AI <hello@mikalsen.ai>",
-	"type": "module",
-	"main": "./dist/index.js",
-	"types": "./dist/index.d.ts",
-	"bin": {
-		"framework": "./bin/apt-tools.mjs",
-		"apt-tools": "./bin/apt-tools.mjs",
-		"apt-proof-video": "./bin/apt-proof-video.mjs"
-	},
-	"exports": {
-		".": {
-			"types": "./dist/index.d.ts",
-			"import": "./dist/index.js"
-		},
-		"./types": {
-			"types": "./dist/types/index.d.ts",
-			"import": "./dist/types/index.js"
-		},
-		"./cost": {
-			"types": "./dist/cost/index.d.ts",
-			"import": "./dist/cost/index.js"
-		},
-		"./mappers": {
-			"types": "./dist/mappers/index.d.ts",
-			"import": "./dist/mappers/index.js"
-		},
-		"./schemas": {
-			"types": "./dist/schemas/index.d.ts",
-			"import": "./dist/schemas/index.js"
-		},
-		"./standalone": {
-			"types": "./dist/standalone/index.d.ts",
-			"import": "./dist/standalone/index.js"
-		},
-		"./design/scan": {
-			"import": "./src/cli/design/scan.mjs"
-		},
-		"./design/extract-repo": {
-			"import": "./src/cli/design/extract-repo.mjs"
-		},
-		"./design/synthesize": {
-			"import": "./src/cli/design/synthesize.mjs"
-		}
-	},
-	"scripts": {
-		"build": "tsc && node scripts/extract-personas-schema.mjs",
-		"dev": "tsc --watch --preserveWatchOutput",
-		"typecheck": "tsc --noEmit",
-		"lint": "biome check . --diagnostic-level=error",
-		"lint:fix": "biome check --write . --diagnostic-level=error",
-		"clean": "rm -rf dist",
-		"test": "vitest run",
-		"c28:cutover": "node scripts/c28-cutover.mjs",
-		"build-plugin": "node scripts/build-plugin.mjs",
-		"publish-plugin": "node scripts/publish-plugin.mjs",
-		"publish:verdaccio": "node scripts/publish-verdaccio.mjs",
-		"release:verdaccio": "pnpm build && pnpm publish:verdaccio",
-		"ship:verdaccio": "npm version patch --no-git-tag-version && pnpm build && pnpm publish:verdaccio"
-	},
-	"files": [
-		"dist/",
-		"bin/",
-		"src/cli/",
-		"src/cost/",
-		"commands/",
-		"skills/",
-		"agents/",
-		"prompts/",
-		"templates/",
-		"context/",
-		"workflows/",
-		"examples/",
-		"LICENSE",
-		"README.md",
-		"CHANGELOG.md",
-		"!**/__tests__/**",
-		"!**/*.test.*",
-		"!**/*.spec.*",
-		"!**/*.test.d.ts.map",
-		"!**/*.test.js.map"
-	],
-	"keywords": [
-		"ai",
-		"framework",
-		"coding-assistant",
-		"claude-code",
-		"codex",
-		"aperant"
-	],
-	"license": "AGPL-3.0-only",
-	"homepage": "https://github.com/Mikalsen-AI/aperant-cloud-desktop/tree/main/packages/framework#readme",
-	"bugs": {
-		"url": "https://github.com/Mikalsen-AI/aperant-cloud-desktop/issues"
-	},
-	"repository": {
-		"type": "git",
-		"url": "https://github.com/Mikalsen-AI/aperant-cloud-desktop.git",
-		"directory": "packages/framework"
-	},
-	"engines": {
-		"node": ">=18.0.0"
-	},
-	"publishConfig": {
-		"access": "public"
-	},
-	"dependencies": {
-		"@clack/prompts": "^1.2.0",
-		"proper-lockfile": "^4.1.2",
-		"yaml": "^2.8.3",
-		"zod": "^4.3.6"
-	},
-	"optionalDependencies": {
-		"@babel/parser": "^7.29.2",
-		"@babel/traverse": "^7.29.0",
-		"@google/genai": "^1.50.1",
-		"css-tree": "^3.2.1",
-		"playwright": "^1.59.1"
-	},
-	"devDependencies": {
-		"@vitest/coverage-v8": "^4.1.5"
-	}
-}
+  "name": "@aperant/framework",
+  "version": "0.6.5",
+  "description": "AI coding framework — composable skills for planning, executing, verifying, and reviewing code with any LLM provider. Works as Claude Code commands, Codex tasks, or programmatically.",
+  "author": "Mikalsen AI <hello@mikalsen.ai>",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "framework": "./bin/apt-tools.mjs",
+    "apt-tools": "./bin/apt-tools.mjs",
+    "apt-proof-video": "./bin/apt-proof-video.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./types": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/types/index.js"
+    },
+    "./cost": {
+      "types": "./dist/cost/index.d.ts",
+      "import": "./dist/cost/index.js"
+    },
+    "./mappers": {
+      "types": "./dist/mappers/index.d.ts",
+      "import": "./dist/mappers/index.js"
+    },
+    "./schemas": {
+      "types": "./dist/schemas/index.d.ts",
+      "import": "./dist/schemas/index.js"
+    },
+    "./standalone": {
+      "types": "./dist/standalone/index.d.ts",
+      "import": "./dist/standalone/index.js"
+    },
+    "./design/scan": {
+      "import": "./src/cli/design/scan.mjs"
+    },
+    "./design/extract-repo": {
+      "import": "./src/cli/design/extract-repo.mjs"
+    },
+    "./design/synthesize": {
+      "import": "./src/cli/design/synthesize.mjs"
+    }
+  },
+  "files": [
+    "dist/",
+    "bin/",
+    "src/cli/",
+    "src/cost/",
+    "commands/",
+    "skills/",
+    "agents/",
+    "prompts/",
+    "templates/",
+    "context/",
+    "workflows/",
+    "examples/",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md",
+    "!**/__tests__/**",
+    "!**/*.test.*",
+    "!**/*.spec.*",
+    "!**/*.test.d.ts.map",
+    "!**/*.test.js.map"
+  ],
+  "keywords": [
+    "ai",
+    "framework",
+    "coding-assistant",
+    "claude-code",
+    "codex",
+    "aperant"
+  ],
+  "license": "AGPL-3.0-only",
+  "homepage": "https://github.com/Mikalsen-AI/aperant-cloud-desktop/tree/main/packages/framework#readme",
+  "bugs": {
+    "url": "https://github.com/Mikalsen-AI/aperant-cloud-desktop/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Mikalsen-AI/aperant-cloud-desktop.git",
+    "directory": "packages/framework"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.2.0",
+    "proper-lockfile": "^4.1.2",
+    "yaml": "^2.8.3",
+    "zod": "^4.3.6"
+  },
+  "optionalDependencies": {
+    "@babel/parser": "^7.29.2",
+    "@babel/traverse": "^7.29.0",
+    "@google/genai": "^1.50.1",
+    "css-tree": "^3.2.1",
+    "playwright": "^1.59.1"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.5"
+  },
+  "scripts": {
+    "build": "tsc && node scripts/extract-personas-schema.mjs",
+    "dev": "tsc --watch --preserveWatchOutput",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check . --diagnostic-level=error",
+    "lint:fix": "biome check --write . --diagnostic-level=error",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "c28:cutover": "node scripts/c28-cutover.mjs",
+    "build-plugin": "node scripts/build-plugin.mjs",
+    "publish-plugin": "node scripts/publish-plugin.mjs",
+    "publish:verdaccio": "node scripts/publish-verdaccio.mjs",
+    "release:verdaccio": "pnpm build && pnpm publish:verdaccio",
+    "ship:verdaccio": "npm version patch --no-git-tag-version && pnpm build && pnpm publish:verdaccio"
+  }
+}

package/prompts/coder.md

@@ -4,6 +4,8 @@ You are continuing work on an autonomous development task. This is a **FRESH con
 
 **Key Principle**: Work on ONE subtask at a time. Complete it. Verify it. Move on.
 
+**TDD mode (apt:execute):** if your kickoff prompt indicates `tdd_active === true` (set by `--tdd`, `coding.tdd_default`, or the legacy `tdd.iron_law` config), the red-green-refactor sequence is mandatory and audited by gate G9. Load the vertical-tracer-bullet discipline from `packages/framework/skills/apt-execute/appendices/tdd-mode.md` and follow its 5 rules. QUICK-routed tasks are hard-exempt regardless of flag or config (Fast Path Guarantee, ID-05).
+
 ---
 
 ## CRITICAL: ENVIRONMENT AWARENESS

package/prompts/planner.md

@@ -6,6 +6,18 @@ You are the **first agent** in an autonomous development process. Your job is to
 
 **MANDATORY**: You MUST call the **Write** tool to create `implementation_plan.json`. Describing the plan in your text response does NOT count — the orchestrator validates that the file exists on disk and passes schema validation. If you do not call the Write tool, the phase will fail.
 
+## TRACK BRANCH — Vertical-slice rubric vs legacy flat schema (Pocock adoption ID-05)
+
+Subtask schema depends on track:
+
+- **QUICK track / SIMPLE workflow:** legacy flat schema (id, title, description, files, dependencies, status, verification). No `hitl`, `afk`, `acceptance_criteria`, `user_value` fields. Fast Path Guarantee — one-shot tasks pay zero ceremony cost.
+- **STANDARD / DEEP / COMPLEX:** vertical-slice schema. Every subtask MUST carry:
+  - `hitl: "required" | "review" | "none"` — `required` blocks executor pending human approval; `review` is post-hoc review; `none` is agent-only.
+  - `afk: "safe" | "unsafe"` — `safe` proceeds unattended; `unsafe` pauses if no human present.
+  - `acceptance_criteria: string[]` — id-refs (e.g. `"AC1"`, `"AC3"`) into spec.md's `## Acceptance Criteria` section. Every AC in spec.md must be referenced by at least one subtask.
+  - `user_value: string` — one-line framing of WHO benefits and HOW. The vertical-slice test: a subtask titled "edit apt-plan SKILL.md" is **horizontal** and wrong; "Solo dogfooder gets a PRD-shaped spec on STANDARD" is **vertical** and right.
+- **Plan-level field:** `vertical_slice_schema_version: "1"` (STANDARD/DEEP only) declares the schema version so future migrations detect v1 plans.
+
 ---
 
 ## WHY SUBTASKS, NOT TESTS?

package/prompts/spec_writer.md

@@ -6,6 +6,15 @@ You are the **Spec Writer Agent** in the Auto-Build spec creation pipeline. Your
 
 **MANDATORY**: You MUST call the **Write** tool to create `spec.md`. Describing the spec in your text response does NOT count — the orchestrator validates that the file exists on disk. If you do not call the Write tool, the phase will fail.
 
+## TRACK BRANCH (Pocock adoption ID-05 — Fast Path Guarantee)
+
+Content format depends on the task's track / complexity:
+
+- **QUICK track OR `simple` workflow:** emit the legacy 4-section spec (Overview / Workflow Type / Task Scope / Success Criteria) — this is the QUICK-exempt fast path. Use the existing `spec_quick.md` template; this file's PRD shape does NOT apply.
+- **STANDARD / DEEP / COMPLEX:** emit the PRD-shaped spec.md per the template at the bottom of this file (Problem Statement / Solution / User Stories / Implementation Decisions / Testing Decisions / Out of Scope / Further Notes + `## Acceptance Criteria`). Section ordering is load-bearing — `apt-tools coverage-check validate` and `apt-tools consistency check` grep by header.
+
+The remainder of this file describes the STANDARD/DEEP PRD shape. When asked to emit a spec for a SIMPLE/QUICK task, fall back to `spec_quick.md` instead of expanding into PRD.
+
 ---
 
 ## YOUR CONTRACT

package/skills/apt/SKILL.md

@@ -130,6 +130,7 @@ Show available commands table:
 | `apt:resume` | Restore context after session break |
 | `apt:pause` | Human-initiated handoff — save state when YOU need to stop |
 | `apt:ship` | Create PR with traceability |
+| `apt:close-task` | Post-merge closer — confirm PR merged, flip phase, drain narration ledger |
 | `apt:setup` | Change framework preferences |
 
 Show current state summary and autonomy flags (`--supervised`, `--guided`, `--autonomous`, `--yolo`).

package/skills/apt-close-task/SKILL.md

@@ -15,7 +15,7 @@ execution_modes:
   - auto
   - step
 allowed-tools: "Bash, Read, Grep, Glob, Write"
-argument-hint: "apt:close-task [--all | --task <id>]"
+argument-hint: "apt:close-task [--all | --task <id>] [--narrate-only]"
 gates: []
 ---
 <objective>
@@ -70,6 +70,7 @@ Internally, close-merged does:
    a. `apt-tools task close . --id {task-id} --verdict approved` (respects `task_isolation.auto_close_phase`).
    b. Strips `config.pr_review.authorship_overrides['pr-{N}']` if present.
    c. Emits `task.closed.merged` event.
+   d. Appends a `pending_narration[]` ledger row to `.aperant/state.json` so `--narrate-only` (see §4) can pick it up. Additive only; never blocks the close.
 3. When `state !== 'MERGED'`, the task stays in `shipped-pending-merge` with a skip reason the user can inspect.
 
 ## 2.5 Narrate completed phases (moved from /apt:ship in C56 B5)
@@ -85,6 +86,8 @@ For each entry in the close-merged envelope's `closed[]` whose record has a non-
 
 Do NOT wait on the narrator. Its status lands in `.aperant/digests/.last-run.json`. Skip narrator spawn entirely when `closed[]` is empty or no closed item has a phase_id.
 
+After step 2.5 spawns narrators for the just-closed candidates, the skill ALSO drains `state.pending_narration[]` (entries the passive sweep parked there) — see §4.
+
 ## 3. Summary
 
 close-merged emits an envelope with:
@@ -95,6 +98,34 @@ close-merged emits an envelope with:
 
 Report the summary verbatim. If anything landed in `skipped[]` with a recoverable reason (`offline`, `rate_limited`), suggest the user re-run once the network clears.
 
+## 4. Narrate-only mode
+
+When invoked with `--narrate-only`, skip §1 (no `gh pr view` polling) and §2 (no destructive close path). The deterministic close already ran via the passive post-merge sweep — your job is to drain the `state.pending_narration[]` ledger the sweep parked.
+
+Flags:
+- `--narrate-only --all` (default when `--narrate-only` is bare) — drain every ledger entry.
+- `--narrate-only --task <id>` — drain only the entry for `<id>`.
+
+Per ledger entry `{ task_id, scope, phase_id, closed_at, pr_number }`:
+
+1. Run `apt-tools features-audit . --apply-stubs --task <task_id>` so the feature registry catches whatever the closed task introduced. If the subprocess exits non-zero, skip the entry with `reason: 'features-audit-failed'` — never block narration on registry update.
+2. When `phase_id` is non-null, spawn `apt-team-docs-narrator` (background, fire-and-forget) using the same shape as §2.5: `subagent_type: apt-team-docs-narrator`, `run_in_background: true`, `description: Narrate shipped phase {phase_id}`, `prompt: Run in phase-ship mode with --phase {phase_id} --scope {scope}.`. When `phase_id` is null, skip the spawn with `reason: 'no-phase-id'` (quick tasks have no phase to narrate).
+3. On successful spawn (or successful no-phase skip), drain the row via `apt-tools task narration-drain . --task <task_id>` which acquires `withFileLock(state.json)` and removes the matching `pending_narration[]` entry. On spawn failure, leave the row in place with `reason: 'narrator-spawn-failed'` so the user can re-invoke.
+
+Emit a summary envelope:
+
+```json
+{
+  "status": "ok",
+  "command": "close-task-narrate-only",
+  "narrated": [{ "task_id": "<id>", "phase_id": "<p|null>", "scope": "<s>" }],
+  "skipped": [{ "task_id": "<id>", "reason": "no-phase-id|features-audit-failed|narrator-spawn-failed" }],
+  "remaining": <ledger.length>
+}
+```
+
+The regular `apt:close-task` flow ALSO falls through to this drain step at the tail of §2.5 — so users who run the skill manually after the sweep get narration without remembering the flag. The `--narrate-only` flag exists for the explicit "drain only, don't poll gh" case.
+
 </process>
 
 <notes>