@aperant/framework 0.6.3 → 0.6.5

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

@@ -9,6 +9,8 @@ user_invocable: true
 internal: false
 spawns_agent: false
 agent_name: null
+task_context: create-new
+default_track: QUICK
 default_execution_mode: auto
 execution_modes:
   - auto
@@ -19,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>
@@ -97,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-resume/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

package/skills/apt-review/SKILL.md

@@ -9,6 +9,7 @@ user_invocable: true
 internal: false
 spawns_agent: true
 agent_name: "apt-reviewer"
+task_context: require-existing
 default_execution_mode: auto
 execution_modes:
   - auto
@@ -17,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-roadmap/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/skills/apt-roundtable/SKILL.md

@@ -9,6 +9,8 @@ user_invocable: true
 internal: false
 spawns_agent: false
 agent_name: null
+task_context: create-new
+default_track: DEEP
 default_execution_mode: auto
 execution_modes:
   - auto

package/skills/apt-run/SKILL.md

@@ -9,6 +9,7 @@ user_invocable: true
 internal: false
 spawns_agent: false
 agent_name: null
+task_context: self-managed
 default_execution_mode: auto
 execution_modes:
   - auto
@@ -16,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.
@@ -62,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:
 
 ```
@@ -80,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)
 
@@ -160,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
@@ -187,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-scan/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

package/skills/apt-setup/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
@@ -16,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
@@ -145,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}  |
@@ -167,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)" },
@@ -180,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
 
@@ -395,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." }
+    ]
   }
 ])
 ```
@@ -858,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:
@@ -908,6 +1028,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"`
@@ -1015,6 +1141,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

@@ -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
@@ -19,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.
@@ -288,6 +292,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,20 +344,62 @@ 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.
 
 `suggest_after_ship` is purely additive — it does not affect `authorship_override`, `authorship_overrides`, or `max_rounds` in the same `pr_review` block.
 
-## 8. Transition lifecycle to `shipped-pending-merge` (C56 B5)
+### 7.2 Post-ship /apt:watch-ci hook
+
+After Section 7.1's hint resolves (whether it ran the deep review or skipped), conditionally arm a 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).
 
-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.
+**Read host cron capability + the after-ship mode:**
 
 ```bash
-node packages/framework/bin/apt-tools.mjs task update . --id {task-id} --lifecycle-phase shipped-pending-merge
+host_cron=$(node packages/framework/bin/apt-tools.mjs host-detect | jq -r '.host.capabilities.cron')
+after_ship_default=$([ "$host_cron" = "true" ] && echo "auto" || echo "never")
+after_ship_mode=$(jq -r --arg d "$after_ship_default" '.ci_watch.after_ship // $d' .aperant/config.json)
 ```
 
+**Autonomy interaction** (apply BEFORE branching, same rule as 7.1): when `autonomy === 3` (YOLO), degrade `ask` → `auto`.
+
+**Branch on `after_ship_mode`:**
+
+- **`auto` AND `host_cron=true`** — call `apt-tools ci-watch start --pr {pr_number} --task-id {task-id} --host {cli}`. On success, emit:
+
+  ```
+  [APT:ship] CI watcher armed (host cron: {cli}). Deadline: {iso}. Stop: /apt:watch-ci --stop --pr {N}.
+  ```
+
+- **`auto` AND `host_cron=false`** — call `apt-tools ci-watch start --pr {pr_number} --task-id {task-id} --host {cli}` (creates state file, sets `scheduler_handle: null`), then 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.
+
+- **`ask`** — emit:
+
+  ```
+  [APT:ship] Arm CI watcher for PR {N} now? [Y/n]
+  ```
+
+  On `Y` (or empty enter), invoke the `auto` branch logic above (with the same host-cron derivation). On `N` or any other response, proceed silently to Section 8.
+
+- **`never`** — silent. Proceed directly to Section 8.
+
+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.
+
+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.
 
 The linked phase (if any) stays `in-progress` — it only flips to `completed` when `/apt:close-task` confirms via `gh pr view` that the PR's state is `MERGED`.

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