@aperant/framework 0.6.7 → 0.7.3

package/dist/plugin/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
@@ -118,7 +120,20 @@ Also check for global defaults at `~/.aperant/defaults.json` — if they exist a
 
 ## 1b. Review Mode (existing config detected)
 
-If `.aperant/config.json` already exists AND `--reset` was NOT passed, enter **review mode** instead of running all batches from scratch.
+**Canonical signal.** The `onboarding.completed` marker inside `.aperant/config.json` is the canonical signal that a user has walked through the full /apt:setup batch sequence. Structural completeness of the JSON config does NOT imply onboarding completeness — `packages/framework/templates/config.json` ships with all keys populated to sensible defaults by design, so the JSON alone cannot disambiguate "fresh seed" from "fully tuned." Future template additions must not assume otherwise.
+
+**Dispatch.** Read `.aperant/config.json` and inspect the `onboarding` block. Branch on the four marker states:
+
+| Marker state                                                | `/apt:setup` behaviour                                                |
+|-------------------------------------------------------------|-----------------------------------------------------------------------|
+| No `onboarding` block (legacy pre-fix config)               | enter **review mode** (preserve current behaviour; do NOT re-onboard) |
+| `onboarding.seeded_from_template: true` AND `onboarding.completed: false` | enter **full Batch 1-8 flow** (treat as fresh setup)      |
+| `onboarding.completed: true`                                | enter **review mode**                                                 |
+| `--reset` flag passed                                       | enter **full Batch 1-8 flow** always (overrides marker)               |
+
+`init` writes the `seeded_from_template: true` / `completed: false` marker on fresh seed only (see `packages/framework/src/cli/commands/init.mjs::applyInterviewAnswers`). The upgrade path never writes the marker — that is why a legacy unmarked config routes to review mode.
+
+If the dispatch lands you in review mode, continue below. If it lands you in the full flow, jump to **Step 2**.
 
 First, run host detection to show resolved orchestration:
 
@@ -146,6 +161,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,10 +184,12 @@ 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)" },
+      { label: "Task Tracking", description: "Tracker backend (local-only / github-issues / app-inbox), publish to tracker, TDD default, prototype discipline" },
+      { label: "Changelog & Release Notes", description: "Internal dev changelog + opt-in user-facing release notes (audience, persona filter)" },
       { label: "Everything", description: "Re-run full setup from scratch" },
       { label: "Done", description: "Keep current settings" }
     ]
@@ -181,11 +199,13 @@ 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**
-- "Everything" → proceed to **Step 2** and run all batches (same as fresh setup)
+- "Task Tracking" → jump to **Step 3g** (Batch 8 only), then skip to **Step 4** and **Step 5**
+- "Changelog & Release Notes" → jump to **Step 3h** (Batch 9 only), then skip to **Step 4** and **Step 5**
+- "Everything" → proceed to **Step 2** and run all batches (same as fresh setup). **Legacy-completes-Everything marker write:** if the starting config has no `onboarding` block (legacy unmarked config) and the user completes the full flow, write a full `onboarding` block at Step 5 as `{ completed: true, seeded_from_template: false, seeded_at: <ISO-8601 now> }` to record the explicit onboarding pass.
 - "Done" → display "Settings unchanged." and exit
 
 For selective edits, **pre-fill the existing values** as the default selection in each question. The user can confirm or change. Unchanged values are preserved — do not overwrite the entire config, only merge the changed section.
@@ -396,6 +416,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,8 +888,257 @@ 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}) |
+```
+
+---
+
+## 3h. Present Settings (Batch 9: Changelog & Release Notes)
+
+This batch captures the **persona-aware changelog + release-notes** preferences introduced by `apt-release-notes/SKILL.md`. Two top-level questions: (1) keep an internal dev `CHANGELOG.md` and (2) publish user-facing release notes. Q2 defaults to **No** on internal/library projects (per spec ID-7: the presence of `personas.json` does NOT auto-enable release-notes — opt-in must be explicit).
+
+If a host supports structured prompts (Claude Code), prefer `AskUserQuestion`. For non-structured hosts (Codex, Gemini-CLI plain mode), present each question as a numbered list and read the reply as a single number per question.
+
+### 3h.1 Present the dev-changelog picker
+
+```
+AskUserQuestion([
+  {
+    question: "Keep an internal dev changelog?",
+    header: "Dev Changelog",
+    options: [
+      { label: "Yes (Recommended)",
+        description: "Auto-update CHANGELOG.md from commits on every /apt:ship. Dev-flavored, internal." },
+      { label: "No",
+        description: "Skip the dev changelog entirely." }
+    ]
+  }
+])
+```
+
+### 3h.2 Present the release-notes picker
+
+```
+AskUserQuestion([
+  {
+    question: "Publish user-facing release notes?",
+    header: "Release Notes",
+    options: [
+      { label: "No (Recommended for internal / library projects)",
+        description: "Skip the user-facing surface entirely. Most projects pick this." },
+      { label: "Yes",
+        description: "Enable /apt:release-notes — auto-draft fragments on /apt:ship, compile at tag time." }
+    ]
+  }
+])
+```
+
+### 3h.3 If Yes — present the audience + persona-filter sub-pickers
+
+When Q2 = Yes, ask:
+
+```
+AskUserQuestion([
+  {
+    question: "Who is the primary audience for these release notes?",
+    header: "Audience",
+    options: [
+      { label: "End user",        description: "Plain-language, value-focused. Suits consumer apps." },
+      { label: "Developer / API", description: "Technical, references API + SDK semantics. Suits libraries." },
+      { label: "Internal team",   description: "Lighter polish, faster cadence. Suits company-internal apps." }
+    ]
+  },
+  {
+    question: "Which personas should drive the published notes?",
+    header: "Persona Filter",
+    options: [
+      { label: "Primary only",
+        description: "Only primary-tier personas surface in published notes." },
+      { label: "Primary + Secondary (Recommended)",
+        description: "Primary + secondary tiers. Default — balances signal with completeness." },
+      { label: "All personas",
+        description: "Every tier surfaces. Useful for marketplaces / multi-sided products." }
+    ]
+  }
+])
+```
+
+If `.aperant/personas.json` is absent and Q2 = Yes, emit a non-blocking hint:
+
+```
+[apt:setup] Note: .aperant/personas.json is missing. Release notes will work but every
+            fragment will land in `## Needs Triage` until you run /apt:personas.
+```
+
+This is a hint only — the user can still complete setup; the triage bucket is the intentional safety net (spec ID-6 never-silent-drop).
+
+### 3h.4 Map answers to `.aperant/config.json`
+
+Mapping rules (extend Section 4 below):
+
+| User picked | Config write |
+|---|---|
+| Q1: Yes | `changelog.dev.enabled = true` |
+| Q1: No | `changelog.dev.enabled = false` |
+| Q2: No  | `changelog.release_notes.enabled = false` (DEFAULT — leave audience + persona_filter at template defaults) |
+| Q2: Yes | `changelog.release_notes.enabled = true` and apply the audience + persona-filter sub-pickers |
+| Audience: End user        | `changelog.release_notes.audience = "end-user"` |
+| Audience: Developer / API | `changelog.release_notes.audience = "developer-api"` |
+| Audience: Internal team   | `changelog.release_notes.audience = "internal-team"` |
+| Persona filter: Primary only            | `changelog.release_notes.persona_filter = "primary"` |
+| Persona filter: Primary + Secondary    | `changelog.release_notes.persona_filter = "primary+secondary"` (DEFAULT) |
+| Persona filter: All personas           | `changelog.release_notes.persona_filter = "all"` |
+
+The remaining `release_notes` keys (`output_dir`, `require_pr_field`, `draft.*`, `compile.*`, `publish.*`) keep their template defaults from `packages/framework/templates/config.json` v5. Users wanting to override those edit `.aperant/config.json` directly — they are not surfaced through the Q-block to keep the picker short.
+
+Migration rule: any existing config WITHOUT a `changelog` block gets defaults silently from the template migrator (`migrateConfigSchema` in `src/cli/config/schema-migrate.mjs`) — this is the same auto_added path Batch 8 relies on for the `task_tracking` / `coding` blocks.
+
+### 3h.5 Review-Mode routing entry
+
+Extend the "1b. Review Mode" routing table (§1b) to include "Changelog & Release Notes" as a selectable edit target — jumping back into this Batch 9 picker.
+
+### 3h.6 Confirmation row
+
+Add a row to the Step 8 table:
+```
+| Changelog & Release Notes | dev: {Yes/No}; release-notes: {Yes/No} (audience: {value}, persona-filter: {value}) |
+```
+
+The selective-edit pass through Batch 9 MUST respect the §1b dispatch — it does NOT flip `onboarding.completed`. Marker writes are reserved for the full-flow / "Everything" branches.
+
+---
+
 ## 4. Map Answers to Config
 
+**AUDIT-001 — file-routing contract for per-device fields (UPDATED 0.7.2):** the
+following five fields are PER-DEVICE and MUST land in `.aperant/config.local.json`
+(gitignored), NOT the shared `.aperant/config.json`:
+- `verification.open_report` — covered in the "Auto-Open" mapping below.
+- `multi_model.cross_verification.tools` — covered in the "Cross-Verification" mapping below.
+- `preferences.date_format` — covered in the "Date Format" mapping below.
+- `preferences.time_format` — covered in the "Time Format" mapping below.
+- `preferences.quick_task_post_verify` — covered in apt-quick SKILL config block.
+
+All other fields (including `verification.evidence_capture`,
+`multi_model.cross_verification.enabled`, `multi_model.video_review.*`,
+`preferences.task_index`, every `orchestration.*` value) stay in shared
+`.aperant/config.json`.
+
+Implementation: use the framework's `writeLocalConfigField(targetDir, dotPath, value)`
+helper from `packages/framework/src/cli/config/load.mjs` (or its shell-out
+equivalent via `apt-tools config write . --local --key <dotpath> --value <json>`)
+for the five fields above. NEVER hand-roll `JSON.parse(readFileSync('.aperant/config.json'))`
+followed by `writeFileSync('.aperant/config.json', ...)` for these fields — it
+will land per-device data in the shared file and re-introduce the
+shared-config trap AUDIT-001 was designed to close.
+
+Reads of these fields anywhere in the framework MUST go through
+`loadMergedProjectConfig(targetDir)` or `readLocalOrSharedField(targetDir, dotPath)`
+so per-device overrides are honored.
+
+---
+
 Map the user's selections to config values:
 
 **Verify Mode:**
@@ -898,6 +1176,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 +1189,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"`
+
+**Diagram MCP consent (per-user, FRAMEWORK-AUDIT-001).** The `diagram.mcpConsent` field is per-user and lives in `.aperant/config.local.json` (gitignored), NOT in the shared `config.json`. If `config.local.json` doesn't exist or has no `diagram.mcpConsent` field, seed `{diagram: {mcpConsent: null}}` in `config.local.json`. The `diagram.mode` field (file vs mcp) stays in `config.json` as team-shared policy and continues to seed there. Existing `mcpConsent` records in `config.local.json` 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"`
@@ -922,13 +1208,16 @@ Map the user's selections to config values:
 
 ## 5. Write Config
 
-Write merged config to `.aperant/config.json`:
+Write merged config to two files per AUDIT-001 routing (see Step 4 block):
+
+- Shared `.aperant/config.json` — all project policy values (the bulk of the answers).
+- Per-device `.aperant/config.local.json` — the five AUDIT-001 fields enumerated in Step 4.
 
 ```bash
 mkdir -p .aperant
 ```
 
-Write the JSON file with 2-space indentation. Bump `version` to 4 if upgrading from an older config (versions 2/3 load forward-compatibly — the new `tdd` block is optional).
+Write each JSON file with 2-space indentation. Bump shared `config.json`'s `version` to 4 if upgrading from an older config (versions 2/3 load forward-compatibly — the new `tdd` block is optional). `config.local.json` is gitignored by `.aperant/.gitignore` — do not check it in.
 
 ## 6. Save as Global Defaults (Optional)
 
@@ -1016,11 +1305,13 @@ 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} |
 | Debate Mode          | {Auto / Agent Team / Sub-Agents / Sequential} |
 | Visibility           | {solo / team / oss} (overrides if any)        |
+| Changelog & Release Notes | dev: {Yes/No}; release-notes: {Yes/No} (audience, persona-filter) |
 | Saved as Defaults    | {Yes/No}                     |
 
 Config saved to: .aperant/config.json
@@ -1032,6 +1323,17 @@ Commands now use these settings automatically:
   /apt:setup        — change settings anytime
 ```
 
+### 8. (continued) Flip `onboarding.completed` on full-flow success
+
+After a successful **full Batch 1-8 pass** (i.e. the user came in via `--reset`, via the fresh-seed marker-state `seeded_from_template:true / completed:false`, or via the review-mode "Everything" option), patch `.aperant/config.json` to set `onboarding.completed: true`. **Preserve** the existing `seeded_from_template` and `seeded_at` fields untouched — they carry forensic value (debug "did init upgrade overwrite my config?"). Concretely:
+
+- Read the current `.aperant/config.json` you just wrote in **Step 5**.
+- Set `onboarding.completed = true`. If the `onboarding` block was already present, preserve the other fields verbatim.
+- If the starting config was a **legacy unmarked config** (no `onboarding` block — see §1b "Everything" routing), instead write the full block as `{ completed: true, seeded_from_template: false, seeded_at: <ISO-8601 now> }`.
+- Re-write `.aperant/config.json` with 2-space indentation.
+
+Selective edits in review mode (Verification, Pipeline, Orchestration, Team Collaboration, Visibility, Task Tracking) DO NOT flip the marker — only a full Batch 1-8 pass does.
+
 ### 8a. PreCompact Hook Status
 
 After confirming settings, check whether the framework's PreCompact hook is

package/dist/plugin/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.
@@ -143,6 +146,53 @@ Format as a markdown table:
 
 If no plan exists (ad-hoc task), list commits without subtask mapping.
 
+## 2.6 Release-note auto-draft (persona-aware release-notes opt-in)
+
+This section runs ONLY when `.aperant/config.json` has `changelog.release_notes.enabled === true`. When the toggle is `false` (the default for the 9-of-10 internal projects that never publish user-facing notes), skip the section entirely — do NOT compute the feature diff and do NOT touch the PR body draft.
+
+Read the toggle:
+
+```bash
+rn_enabled=$(jq -r '.changelog.release_notes.enabled // false' .aperant/config.json)
+```
+
+If `rn_enabled !== "true"`, jump to Section 3.
+
+### 2.6.1 Compute the feature-registry diff
+
+The auto-draft needs to know which features the PR's commits touched. Use the same `features-audit` surface that `apt:execute` uses post-step:
+
+```bash
+base=$(node packages/framework/bin/apt-tools.mjs task get . --id {task-id} | jq -r '.base_branch // "main"')
+feature_diff=$(node packages/framework/bin/apt-tools.mjs features-audit . --diff-since "$base" --json)
+```
+
+The envelope shape (see `packages/framework/src/cli/commands/features-audit.mjs`) returns the list of touched features with their declared `personas: []` field (when the registry's feature row carries one).
+
+### 2.6.2 Decide draft vs block via the helper
+
+Hand the diff + the project's personas envelope + the filter mode to `ship-autodraft.mjs`. The CLI returns one of three envelopes:
+
+- `{status: 'draft', line, persona, matchedFeatures}` — append `line` to the PR body draft built in Section 3.
+- `{status: 'block', reason, message}` — fire the block path below.
+- `{status: 'warn', reason, message}` — log the warning and proceed without the line.
+
+The block path triggers when `release_notes.require_pr_field === true` (default) AND auto-draft failed (no feature match OR no persona signal). The exact error string is locked by AC7:
+
+```
+[APT] No release-note signal found — author manual note in PR body or label PR no-notes
+```
+
+When the block fires, STOP — do NOT proceed to `gh pr create`. The user must either (a) author a manual `Release note: …` line in the PR body via `git commit --amend` (or by editing the PR body after open), or (b) label the PR `no-notes` via `gh pr edit --add-label no-notes` and re-run `/apt:ship`. The label-based escape hatch keeps the gate from blocking infra-only PRs that genuinely have no user-facing impact.
+
+### 2.6.3 Inject the line into the PR body draft
+
+When the helper returns `status: 'draft'`, append the `line` value verbatim to the PR body draft assembled in Section 3, immediately under the `## Summary` heading. The line is one sentence, persona-voice-tuned, suitable for a user-facing surface.
+
+### 2.6.4 Helper contract (for testability)
+
+The helper lives at `packages/framework/src/cli/release-notes/ship-autodraft.mjs`. It is a pure function — given the feature-diff envelope + personas envelope + filter mode + the `require_pr_field` toggle, it returns the decision. The `decideAutodraft` export is unit-tested via TD-4; the SKILL.md body wires it without re-deriving the decision logic.
+
 ## 3. Build PR Body
 
 **Title:** Derived from task description. Keep it short (<70 characters).
@@ -286,11 +336,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 +399,75 @@ 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')
+ci_watch_scheduler_handle=$(echo "$ship_update" | jq -r '.scheduler_handle // 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** (FRAMEWORK-BUG-018 — Track 1: distinguish state-recording from wake-registration):
+
+- **`ci_watch_armed=true` AND `host_cron=true` AND `ci_watch_scheduler_handle` non-empty** — emit:
+
+  ```
+  [APT:ship] CI watcher armed (host cron: {ci_watch_host}). Deadline: {ci_watch_deadline}. Stop: /apt:watch-ci --stop --pr {N}.
+  ```
+
+  This is the only honest "armed" case — a scheduler handle proves the wake is registered.
+
+- **`ci_watch_armed=true` AND `host_cron=true` AND `ci_watch_scheduler_handle` empty** — emit:
+
+  ```
+  [APT:ship] CI watcher state created (host: {ci_watch_host}). Register a wake-up to drive ticks: CronCreate every ~3min running '/apt:watch-ci --tick --pr {N}'. Deadline: {ci_watch_deadline}. Stop: /apt:watch-ci --stop --pr {N}.
+  ```
+
+  State is recorded but no scheduler is registered — the orchestrator MUST register a wake or ticks will never fire. Track 2 (auto-wake on arm) will populate `scheduler_handle` and route into the first branch instead.
+
+- **`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
+  arm_envelope=$(node packages/framework/bin/apt-tools.mjs ci-watch start . --pr {pr_number} --task-id {task-id} --host {cli})
+  ci_watch_scheduler_handle=$(echo "$arm_envelope" | jq -r '.scheduler_handle // empty')
+  ```
+
+  Then route into the same four-way logic above — branch 1 (armed with handle), branch 2 (state-created, needs wake), or branch 3 (host has no cron). 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.