@aperant/framework 0.6.4 → 0.6.6

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.

package/skills/apt-prototype/UI.md

@@ -0,0 +1,90 @@
+<!--
+Adapted from Matt Pocock's MIT-licensed skill suite:
+https://github.com/mattpocock/skills/blob/main/skills/engineering/prototype/UI.md
+Licensed under MIT. Modifications: routed through Aperant's existing
+apt:mockup skill rather than a freestanding HTML+Tailwind generator;
+aligned with the 5 universal rules in apt-prototype/SKILL.md.
+-->
+
+# UI branch — Delegates to apt:mockup
+
+When the user's question is about **appearance / layout / flow /
+discoverability**, the prototype is one or more HTML files generated
+by Aperant's existing `/apt:mockup` skill. apt:mockup already enforces
+the UI-specific universal rules (zero-dep Tailwind CDN, no JS, throwaway
+HTML iterations preserved).
+
+## When this branch fires
+
+Question types that route here:
+
+- "Does this UI shape feel right?"
+- "Is this flow discoverable?"
+- "Does this layout work on mobile?"
+- "Should the primary action be a button or a card?"
+- "How does X scale to N items?"
+
+Question types that DO NOT route here (use LOGIC branch):
+
+- "Does this state machine work?"
+- "Does this control flow handle edge case X?"
+- "Can this protocol handle out-of-order messages?"
+
+## How the delegation works
+
+apt:prototype's UI branch is a thin wrapper that:
+
+1. Parses the user's question to extract the UI element / flow being
+   asked about (e.g., "search results card with N items").
+2. Invokes the existing skill: `/apt:mockup --variants 3 [extracted topic]`.
+3. apt:mockup produces 3 parallel HTML+Tailwind variants under
+   `.aperant/mockups/{topic-slug}/` so the user can compare them
+   side-by-side.
+
+apt:prototype does NOT re-implement HTML+Tailwind generation — the
+discipline lives in apt:mockup's body. UI.md exists so the apt:prototype
+skill body can branch on question-type without conflating "logic
+prototype" and "UI mockup" code paths.
+
+## The 5 universal rules still apply
+
+apt:mockup already enforces:
+
+- Throwaway-marked (each HTML file carries a comment marker)
+- Single-command-run (`open mockup.html` — zero dependencies)
+- No-persistence-default (static HTML, no localStorage usage by default)
+- Skip-polish (CSS reset, no animation refinement, no responsive
+  breakpoints unless the question is about responsive)
+
+The fifth rule — **surface-state-transparently** — is the one
+apt:mockup doesn't fully cover by default. For UI prototypes where the
+question is about data shape (e.g., "what does this look like with 0
+items vs 100 items?"), instruct apt:mockup to render each variant with
+a different data-fixture state, and put the fixture JSON in a
+side-panel of each mockup so the user can see what's driving the
+render.
+
+## What apt:prototype's UI branch adds over running apt:mockup directly
+
+Two things:
+
+1. **Question framing.** apt:mockup is invocable as "build me a mockup
+   of X". apt:prototype's UI branch is invocable as "I have a question
+   about UI X — show me three answers." The framing shifts the
+   discipline from "deliver the mockup the user asked for" to "answer
+   the user's question with the cheapest possible visual artifact."
+
+2. **5-rule cross-discipline reminder.** When the UI branch fires, the
+   skill body explicitly re-states all 5 universal rules (not just the
+   UI-specific ones). The user gets the apt:prototype mental model on
+   top of apt:mockup's mechanical output — which prevents the variant
+   from drifting into "polish this until it's production-ready."
+
+## When the apt:mockup delegation is NOT enough
+
+If the question requires interaction the user can drive (click through,
+hover states, conditional rendering on input), the right call is
+`/apt:prototype` LOGIC branch on top of `/apt:mockup` — a tiny
+JS-driven terminal-ish runner that swaps between the 3 mockups based
+on simulated state. This is rare; most UI questions are answered by
+the side-by-side parallel variants apt:mockup already produces.

package/skills/apt-quick/SKILL.md

@@ -21,6 +21,8 @@ gates: []
 ---
 <objective>
 Execute a small task quickly without full pipeline overhead. For small fixes, doc updates, config changes, and ad-hoc tasks. Skip planning — go straight to implementation with atomic commits and lightweight state tracking.
+
+**QUICK is sequential single-agent by contract.** Per roundtable 2026-05-14 (R1), QUICK = one agent doing intent → implementation in one context window. There are no phase sub-agents. This is a contract, not an optimization — the QUICK track exists precisely because phase isolation buys nothing on tasks small enough that the planner's mental model and the implementer's mental model would be identical.
 </objective>
 
 <your_environment>
@@ -99,6 +101,34 @@ If the task does NOT cross any obligation axes, proceed normally.
 2. Use Glob/Grep to find the files that need changes
 3. Read those files to understand current state
 
+## 3.5. Risk Check (mandatory)
+
+Before implementing, check the risk class of files this task will modify. QUICK shares the same Critical/Destructive hard stop as `/apt:execute` step 3b — the speed of QUICK does NOT waive the risk gate. Misclassified QUICK tasks touching `**/auth/**`, `**/schema*`, `**/convex/schema.*`, or other Critical paths must NOT commit without explicit human approval.
+
+```bash
+node .aperant/deps/node_modules/@aperant/framework/bin/apt-tools.mjs risk-check . --paths {target files}
+```
+
+If the task description contains destructive keywords ("delete", "remove", "drop", "force-push"), pass `--operation delete` so glob matching covers the destructive intent.
+
+Parse the JSON result and apply the gate:
+
+**If `risk_class` is `"Critical"` or `"Destructive"`:**
+Stop execution. Show the user:
+```
+RISK GATE: This QUICK task touches {risk_class} files.
+Files: {matched_paths list}
+Pattern: {matched_pattern}
+
+Approve this change? (yes/no)
+```
+Wait for explicit approval. If denied, abort the task and record `verification.risk_gate = "denied"` in `task.json`. The gate is hardcoded at ALL autonomy levels — QUICK does not get to skip it.
+
+**If `risk_class` is `"Elevated"` AND autonomy < 3:**
+Show the affected files briefly before proceeding (5-second delay; user can interrupt). At YOLO autonomy, proceed without stopping.
+
+**Why this exists:** roundtable 2026-05-14 R1 surfaced that `apt-quick` previously had no risk-check gate, meaning a misclassified QUICK task touching schema/auth could commit Critical-path changes with zero code-level safeguard. See `.aperant/roundtables/phase-mode-per-track-20260514/REPORT.md` (R1, Risk Assessment §1).
+
 ## 4. Implement
 
 Make the changes directly:

package/skills/apt-review/SKILL.md

@@ -18,6 +18,8 @@ allowed-tools: "Read, Bash, Grep, Glob"
 argument-hint: "apt:review [--skip-docs | --fix-all]"
 gates: 
   - verify-approved
+config_keys:
+  - pipeline.skip_review
 ---
 <objective>
 Review the code produced by a task's execution, analyzing logic, security, quality, architecture, and performance. Fix all findings. Update task documentation. Report what's next.

package/skills/apt-run/SKILL.md

@@ -17,10 +17,13 @@ execution_modes:
   - plan-mode
   - plan-only
 allowed-tools: "Bash, Read, Write, Edit, Grep, Glob, Task"
-argument-hint: "apt:run [task description] [--skip-review]"
+argument-hint: "apt:run [task description] [--skip-review] [--phase-mode auto|agent-team|sub-agents|sequential]"
 gates: 
   - constitution-read
   - constitution-coverage
+config_keys:
+  - parallelization.enabled
+  - parallelization.max_agents
 ---
 <objective>
 Run the full Aperant pipeline: plan a task, execute all subtasks, verify the implementation, and optionally review the code. This is the one-command experience — from task description to verified, reviewed code.
@@ -63,12 +66,14 @@ node packages/framework/bin/apt-tools.mjs state .
 
 ## 1b. Resolve Orchestration Mode
 
-Run reconcile to determine the effective orchestration strategy for this pipeline run:
+Run reconcile to determine the effective orchestration strategy for this pipeline run. Pass the task's track via `--track <quick|standard|deep>` so per-track defaults from `.aperant/config.json:orchestration.per_track` apply (roundtable 2026-05-14 R7):
 
 ```bash
-node packages/framework/bin/apt-tools.mjs reconcile .
+node packages/framework/bin/apt-tools.mjs reconcile . --track {track}
 ```
 
+**Per-invocation override:** if the user passed `--phase-mode {auto|agent-team|sub-agents|sequential}` on the invocation, use that value as `PHASE_MODE` directly (it wins over both `per_track` and the global `phase_delegation`). Still call reconcile so `review_mode` and `debate_mode` are resolved against host capabilities.
+
 Parse the result and display:
 
 ```
@@ -81,7 +86,7 @@ If `downgrades` is present in the result, display each downgrade warning:
 [APT] Warning: {downgrade.field} requested '{downgrade.requested}' but host does not support it — using '{downgrade.resolved}'. {downgrade.reason}
 ```
 
-Store `resolved.phase_delegation` as `PHASE_MODE` for use in the pipeline steps below.
+Store `resolved.phase_delegation` (or the explicit `--phase-mode` override) as `PHASE_MODE` for use in the pipeline steps below.
 
 ## 2. Create Feature Branch (or task worktree)
 
@@ -161,6 +166,19 @@ Execute the apt:execute workflow inline:
 
 ## 5. Stage 3 — Verify (apt:verify)
 
+**De-anchored re-read (PHASE_MODE=sequential only — roundtable 2026-05-14 R2):**
+
+When `PHASE_MODE` is `"sequential"` and the same agent that ran Stage 2 is about to run Stage 3 in the same context window, treat the boundary as an attention reset before proceeding. The agent MUST:
+
+1. **Re-read `spec.md` from disk** — do not rely on its in-context summary from earlier in the conversation
+2. **Re-read the diff from disk** via `git diff {base_branch}...HEAD` — verify what was actually written, not what was intended
+3. **Adopt adversarial QA posture** — for the duration of Stage 3 you are not the implementer; you are reading this code for the first time, asking "what does this break?" rather than "did I do this right?"
+4. **Ignore your prior reasoning chain** — the executor's "why I did it this way" rationalization is in-window but MUST NOT anchor the verifier's reading. If a finding conflicts with prior reasoning, prefer the finding
+
+This block exists because the roundtable's STANDARD-track de-anchoring relies on prompt-level discipline rather than fresh-context isolation. The exit condition: if verify completeness+correctness scores drop >0.5 points across 10+ STANDARD tasks measured under R6 telemetry, flip `orchestration.per_track.standard` to `"sub-agents"` (R3 — the named fallback preserved from Systems Analyst + Risk Analyst dissent). See `.aperant/roundtables/phase-mode-per-track-20260514/REPORT.md` §Dissenting Views.
+
+Sub-agents and agent-team modes skip this block — they get fresh-context isolation by spawning, which makes the de-anchored re-read redundant.
+
 Execute the apt:verify workflow inline:
 
 1. Check all subtasks completed
@@ -188,6 +206,16 @@ Stop pipeline (do not proceed to review).
 
 **Skip if** `--skip-review` flag is set.
 
+**De-anchored re-read (PHASE_MODE=sequential only — roundtable 2026-05-14 R2):**
+
+Same attention-reset discipline as Stage 3 applies before review starts. In sequential mode the reviewer is the same agent that planned, executed, and verified — the rationalization chain is in-window. Before the 6-pass loop:
+
+1. **Re-read `spec.md` and `qa_signoff.json` from disk** — do not summarize from in-context recall
+2. **Re-read changed files** at their post-execution state via `git show HEAD:{path}` or direct Read
+3. **Adopt fresh-reviewer posture** — you are reading this code as if a colleague wrote it, not as if you wrote it. The 6 review passes (logic / security / quality / architecture / performance / docs-coherence) are independent lenses; treat each lens as a fresh adversarial reading
+
+Pattern reference: `packages/core/src/workflows/sparring/engine.ts` implements this exact discipline for sparring reviewers (fresh `streamText` per lens, lens prompt in system slot). This SKILL.md block is the same idea applied to verify/review in a single-context pipeline.
+
 Execute the apt:review workflow inline (see `apt-review/SKILL.md`):
 
 1. Load context — spec, QA results, constitution

package/skills/apt-setup/SKILL.md

@@ -17,6 +17,8 @@ execution_modes:
 allowed-tools: "Bash, Read, Write, Edit, Grep, Glob"
 argument-hint: "apt:setup [--batch <n> | --reset]"
 gates: []
+config_keys:
+  - "*"
 ---
 <objective>
 Interactive configuration of the Aperant Framework. Presents human-friendly questions
@@ -146,6 +148,7 @@ Display the current settings summary:
 | Date Format          | {current value}              |
 | Time Format          | {current value}              |
 | Task Index           | {current value}              |
+| Diagram Mode         | {current value}              |
 | Phase Delegation     | {config value} → {resolved}  |
 | Review Mode          | {config value} → {resolved}  |
 | Debate Mode          | {config value} → {resolved}  |
@@ -168,7 +171,7 @@ AskUserQuestion([
     multiSelect: false,
     options: [
       { label: "Verification", description: "Verify mode, cross-verification, video review, strictness" },
-      { label: "Pipeline", description: "Auto branch, code review, TDD Iron Law, date/time format, task index" },
+      { label: "Pipeline", description: "Auto branch, code review, TDD Iron Law, date/time format, task index, diagram mode (file vs mcp)" },
       { label: "Orchestration", description: "Phase delegation, review mode, debate mode, agent teams" },
       { label: "Team Collaboration", description: "Enable/disable team mode — shared task board, roadmap, members" },
       { label: "Visibility", description: "Artifact-sharing policy — what leaves your machine (roadmap, team.json, decisions, digests, tasks)" },
@@ -181,10 +184,11 @@ AskUserQuestion([
 
 **Routing:**
 - "Verification" → jump to **Step 2** (Batch 1 + Batch 2 only), then skip to **Step 4** (mapping) and **Step 5** (write)
-- "Pipeline" → jump to **Step 3b** (Batch 3 only), then skip to **Step 4** and **Step 5**
+- "Pipeline" → jump to **Step 3b** (Batch 3 only, including Diagram Mode), then skip to **Step 4** and **Step 5**
 - "Orchestration" → jump to **Step 3c** (Batch 4 only), then skip to **Step 4** and **Step 5**
 - "Team Collaboration" → jump to **Step 3d** (Batch 5 only), then skip to **Step 4** and **Step 5**
 - "Visibility" → jump to **Step 3e** (Batch 6 only), then skip to **Step 4** and **Step 5**
+- "Task Tracking" → jump to **Step 3g** (Batch 8 only), then skip to **Step 4** and **Step 5**
 - "Everything" → proceed to **Step 2** and run all batches (same as fresh setup)
 - "Done" → display "Settings unchanged." and exit
 
@@ -396,6 +400,15 @@ AskUserQuestion([
       { label: "Yes (Recommended)", description: "Generates .aperant/tasks/INDEX.md with date, status, and title for every task — updated automatically" },
       { label: "No", description: "Skip index generation" }
     ]
+  },
+  {
+    question: "How should /apt:diagram render diagrams by default? (You can override per-call with --mode=file or --mode=mcp.)",
+    header: "Diagram Mode",
+    multiSelect: false,
+    options: [
+      { label: "File (default)", description: "Writes a local docs/diagrams/<slug>.excalidraw file — works offline, no external services" },
+      { label: "MCP (live canvas)", description: "Renders into a live Excalidraw MCP canvas — requires the Excalidraw MCP server to be connected. Asks for one-time consent on first use." }
+    ]
   }
 ])
 ```
@@ -859,6 +872,112 @@ Add a row to the Step 8 table:
 
 ---
 
+## 3g. Present Settings (Batch 8: Task Tracking + Coding) (Pocock adoption AC13)
+
+This batch captures the **task_tracking** backend and the **coding**
+defaults block introduced by the Pocock adoption (ST-10 apt:triage +
+ST-3 apt:execute --tdd).
+
+Per ID-01 (Framework full-featured locally; backends are pluggable), the
+default is `local-only` — zero GitHub auth required on first run. Users
+can switch to `github-issues` (v1 stub) or `app-inbox` (v1 stub) later;
+the framework abstraction is open for v2 adapter implementations.
+
+### 3g.1 Present the task-tracking picker
+
+```
+AskUserQuestion([
+  {
+    question: "Where should triage state mirror to?",
+    header: "Task Tracking",
+    options: [
+      { label: "Local files only (recommended for solo / 2-founder)",
+        description: "Writes to .aperant/tasks/{id}/triage.json. Zero net dep." },
+      { label: "GitHub Issues (v2 — stub returns not-implemented in v1)",
+        description: "v1 ships the adapter shape only; full implementation in v2." },
+      { label: "App inbox (post-app-launch — stub in v1)",
+        description: "Convex-backed; same state machine, app-rendered." }
+    ]
+  },
+  {
+    question: "Publish vertical-slice subtasks to the tracker?",
+    header: "Tracker Publishing",
+    options: [
+      { label: "No (recommended for solo / local)",
+        description: "Slices stay in implementation_plan.json only." },
+      { label: "Yes (only meaningful with github-issues or app-inbox backend)",
+        description: "Each vertical slice becomes an issue via the to-issues template." }
+    ]
+  }
+])
+```
+
+For hosts without structured prompts, present each as a numbered list
+and read the reply as a single number per question.
+
+### 3g.2 Present the coding-defaults picker
+
+```
+AskUserQuestion([
+  {
+    question: "Activate TDD discipline by default for /apt:execute?",
+    header: "TDD Default",
+    options: [
+      { label: "No (off — opt in per run via --tdd)",
+        description: "Single-commit flow; --tdd activates red-green-refactor + G9 audit." },
+      { label: "Yes (on — opt out per run via --no-tdd)",
+        description: "Vertical-tracer-bullet discipline on every STANDARD/DEEP run." }
+    ]
+  },
+  {
+    question: "Enforce the 5-rule prototype discipline on /apt:prototype?",
+    header: "Prototype Discipline",
+    options: [
+      { label: "Yes (recommended — throwaway-marked, single-command-run, etc.)",
+        description: "All 5 universal rules apply to every prototype." },
+      { label: "No (relaxed — rules are guidance only)",
+        description: "Prototypes may grow into production code; not recommended." }
+    ]
+  }
+])
+```
+
+### 3g.3 Map answers to `.aperant/config.json`
+
+```jsonc
+{
+  "task_tracking": {
+    "backend": "local-only",            // default; or "github-issues" | "app-inbox"
+    "publish_to_tracker": false,        // default
+    "tracker_url": null,                // user-supplied when publish_to_tracker = true
+    "tracker_label_vocabulary": "default" // or custom name
+  },
+  "coding": {
+    "tdd_default": false,               // default — see ST-3 apt:execute --tdd
+    "prototype_discipline": true        // default — see ST-8 apt:prototype
+  }
+}
+```
+
+Migration rule: any existing config WITHOUT a `task_tracking` or
+`coding` block gets defaults silently — NEVER error on a missing block.
+This is the migration path for projects that adopted Aperant pre-Pocock.
+
+### 3g.4 Review-Mode routing entry
+
+Extend the "1b. Review Mode" routing table (§1b) to include "Task
+Tracking" as a selectable edit target — jumping back into this Batch 8
+picker.
+
+### 3g.5 Confirmation row
+
+Add a row to the Step 8 table:
+```
+| Task Tracking | {backend} (publish: {true|false}, TDD default: {true|false}) |
+```
+
+---
+
 ## 4. Map Answers to Config
 
 Map the user's selections to config values:
@@ -898,6 +1017,8 @@ Map the user's selections to config values:
 - "Ask me" → `pr_review.suggest_after_ship: "ask"`
 - "Never" → `pr_review.suggest_after_ship: "never"`
 
+Note: task ids are slug-first since v0.6.6 — the date-format setting controls the trailing date component only.
+
 **Date Format:**
 - "DD-MM-YY" → `preferences.date_format: "DD-MM-YY"`
 - "MM-DD-YY" → `preferences.date_format: "MM-DD-YY"`
@@ -909,6 +1030,12 @@ Map the user's selections to config values:
 
 **Task Index:** "Yes" → `preferences.task_index: true`, "No" → `preferences.task_index: false`
 
+**Diagram Mode:**
+- "File (default)" → `diagram.mode: "file"`
+- "MCP (live canvas)" → `diagram.mode: "mcp"`
+
+If `.aperant/config.json` has no `diagram` block yet, also seed `diagram.mcpConsent: null` so the structure matches the template default. Existing `mcpConsent` records are preserved across mode flips (changing the mode does not invalidate prior consent for the same host).
+
 **Orchestration (Auto mode):** "Auto (Recommended)" → all three fields set to `"auto"`:
 - `orchestration.phase_delegation: "auto"`
 - `orchestration.review_mode: "auto"`
@@ -1016,6 +1143,7 @@ Display:
 | Date Format          | {DD-MM-YY / MM-DD-YY / YY-MM-DD} |
 | Time Format          | {24h / 12h}                  |
 | Task Index           | {Yes/No}                     |
+| Diagram Mode         | {file/mcp}                   |
 | Design Taste         | {Skip / Brutalist / Editorial / Enterprise-Clean / Playful} |
 | Phase Delegation     | {Auto / Agent Team / Sub-Agents / Sequential} |
 | Review Mode          | {Auto / Agent Team / Sub-Agents / Sequential} |

package/skills/apt-ship/SKILL.md

@@ -20,6 +20,9 @@ gates:
   - review-clean
   - all-subtasks-complete
   - gitignore-in-sync
+config_keys:
+  - pipeline.auto_branch
+  - pipeline.branch_prefix
 ---
 <objective>
 Create a pull request (or publish a package) with full traceability from decisions to implementation. The PR body includes QA dimension scores, decision audit trail, and commit-to-subtask mapping. This is the final step in any track -- after verify passes, ship it.
@@ -286,11 +289,13 @@ Capture the PR URL from the output into `pr_url` (for example, the last line of
 **Record `pr_url` on the task record (C56 A2).** `/apt:close-task` and the auto-close-phase path in `task close` both resolve the PR number from this URL to poll `gh pr view` for merge state — without it, the closer side cannot run:
 
 ```bash
-node packages/framework/bin/apt-tools.mjs task update . --id {task-id} --pr-url {PR_URL}
+ship_update=$(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.
 
+It also evaluates `ci_watch.after_ship` and may arm the post-ship CI watcher. Preserve the JSON envelope in `ship_update`; Section 7.2 reads `ci_watch_armed` and `ci_watch_skip_reason` from it instead of issuing a second auto-start command.
+
 Display the resolution so users see which branch/base was used:
 
 ```
@@ -347,6 +352,63 @@ suggest_mode=$(jq -r '.pr_review.suggest_after_ship // "always"' .aperant/config
 
 `suggest_after_ship` is purely additive — it does not affect `authorship_override`, `authorship_overrides`, or `max_rounds` in the same `pr_review` block.
 
+### 7.2 Post-ship /apt:watch-ci hook
+
+After Section 7.1's hint resolves (whether it ran the deep review or skipped), report or interactively arm the post-ship CI watcher. The hook is controlled by `ci_watch.after_ship` in `.aperant/config.json` (tri-state: `auto` | `ask` | `never`). The default depends on host capability — `auto` on cron-capable hosts (Claude Code, Pi), `never` elsewhere.
+
+**Skip entirely** when no PR URL was captured in Section 6 (library `npm publish`-only path — same skip rule as 7.1).
+
+**Read the Section 6 task-update envelope first:**
+
+```bash
+ci_watch_armed=$(echo "$ship_update" | jq -r '.ci_watch_armed // false')
+ci_watch_skip_reason=$(echo "$ship_update" | jq -r '.ci_watch_skip_reason // empty')
+ci_watch_host=$(echo "$ship_update" | jq -r '.ci_watch.host // "unknown"')
+ci_watch_deadline=$(echo "$ship_update" | jq -r '.ci_watch.deadline // empty')
+host_cron=$(node packages/framework/bin/apt-tools.mjs host-detect | jq -r '.host.capabilities.cron')
+```
+
+**Autonomy interaction** (apply BEFORE branching, same rule as 7.1): when `autonomy === 3` (YOLO), degrade `ask` → `auto`.
+
+**Branch on the task-update envelope:**
+
+- **`ci_watch_armed=true` AND `host_cron=true`** — emit:
+
+  ```
+  [APT:ship] CI watcher armed (host cron: {ci_watch_host}). Deadline: {ci_watch_deadline}. Stop: /apt:watch-ci --stop --pr {N}.
+  ```
+
+- **`ci_watch_armed=true` AND `host_cron=false`** — emit:
+
+  ```
+  [APT:ship] CI watcher state created (host has no cron; advance manually: /apt:watch-ci --tick --pr {N}).
+  ```
+
+  This is the honest-gap surface per D-03 — we never lie about cron-capability.
+
+- **`ci_watch_skip_reason=ask-deferred`** — emit:
+
+  ```
+  [APT:ship] Arm CI watcher for PR {N} now? [Y/n]
+  ```
+
+  On `Y` (or empty enter), call:
+
+  ```bash
+  node packages/framework/bin/apt-tools.mjs ci-watch start . --pr {pr_number} --task-id {task-id} --host {cli}
+  ```
+
+  Then emit the same host-cron-aware success banner used for `ci_watch_armed=true`. On `N` or any other response, proceed silently to Section 8.
+
+- **`ci_watch_skip_reason=disabled`** — silent. Proceed directly to Section 8.
+
+- **Any other skip reason** — emit:
+  ```
+  [APT:ship] CI watcher not armed: {ci_watch_skip_reason}
+  ```
+
+Section 7.2 is purely additive — it does not affect Section 7.1's `pr_review.suggest_after_ship` policy or any other config block.
+
 ## 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. 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.