@aperant/framework 0.7.0 → 0.7.4

package/dist/plugin/agents/apt-planner.md

@@ -59,6 +59,18 @@ For STANDARD and COMPLEX tasks:
 3. Read key files to understand current architecture
 4. Identify: files to modify, interfaces to respect, tests to update, config to change
 
+### 3.35. React state guidance — sync-store vs render-committed ref (BUG-025-planner)
+
+When a planned event handler fires a flush/persist immediately after mutating a Zustand/Jotai/refs-stored store, the spec MUST recommend reading from `store.getState()` (or the equivalent direct-read primitive) on the synchronous path, NOT from a `useRef`-populated-by-`useEffect`.
+
+Why: refs populated via `useEffect` lag the store by one render cycle. A handler that mutates the store and immediately reads the ref sees the pre-mutation value, silently corrupting persists and order-of-operations contracts. Reference pattern: `apps/desktop/src/renderer/src/App.tsx::runUpsertForIds` (post-fix commit `4c263856`).
+
+Checklist when the task touches a Zustand/Jotai store or any handler doing flush-after-mutate:
+
+- Grep for `useRef(` references that cache store state (e.g. `const fooRef = useRef(foo); useEffect(() => { fooRef.current = foo }, [foo])`).
+- If the spec or planned subtasks read from such a ref on a synchronous path that ALSO mutates the store, recommend `store.getState()` as the read primitive.
+- Note the caveat explicitly in the spec's Implementation Decisions section so the executor doesn't silently revert it.
+
 ### 3.4. Consume design.md (C24)
 
 If `{task_dir}/design.md` exists (emitted by a prior `/apt:design` run), load it before decomposing subtasks:
@@ -199,7 +211,13 @@ If unable to enumerate (network unavailable, action docs unclear), flag it expli
 
 ## 4. Write Specification
 
-Create `{task_dir}/spec.md`:
+The spec.md content format **branches on track** (Pocock adoption ID-05,
+Fast Path Guarantee). QUICK-routed tasks keep the existing 4-section
+shape; STANDARD/DEEP/COMPLEX tasks get a PRD-shaped artifact that
+survives the task as a second-consumer document.
+
+### 4.A. QUICK track / SIMPLE complexity — legacy 4-section spec
+
 ```markdown
 # Task: {task description}
 
@@ -219,6 +237,57 @@ Create `{task_dir}/spec.md`:
 {What this task explicitly does NOT cover}
 ```
 
+### 4.B. STANDARD / DEEP / COMPLEX — PRD-shaped spec.md
+
+```markdown
+# Spec: {task title}
+
+**Task ID:** {task-id}
+**Track:** {STANDARD | DEEP}
+**Scope:** {framework | desktop | web | core | ui | backend | docs}
+
+## Problem Statement
+{What pain are we solving? Cite empirical evidence where possible.}
+
+## Solution
+{Chosen approach + bulleted net delta of files / flags / config / skills.}
+
+## User Stories
+{One **US-NN (persona).** story per user-value slice. Stories map 1:1
+onto subtasks in implementation_plan.json.}
+
+## Implementation Decisions
+{Load-bearing principles carried into every subtask. Format:
+"### ID-NN: {title}" + rationale + practical consequence.}
+
+## Testing Decisions
+{One block per test family: "### TD-NN: {family}" + what's covered +
+which subtask owns the test file. Fast Path regression tests MUST be
+enumerated here.}
+
+## Out of Scope
+{Non-goals. Each bullet names what is deferred + where it belongs.}
+
+## Further Notes
+{Sequencing rationale, risk surface, dependencies, files-affected
+preview, and any other executor-load-bearing context.}
+
+### Acceptance Criteria
+{Cross-cutting **AC1..ACN** list — each AC gets a stable ID. Subtasks
+reference these IDs via the per-subtask `acceptance_criteria` field.}
+```
+
+**PRD section ordering is load-bearing.** `apt-tools coverage-check
+validate` greps `## Acceptance Criteria`; `apt-tools consistency check`
+greps `## Solution` and `## User Stories`. Renaming or reordering these
+sections breaks downstream tooling and the C15 consistency rules.
+
+**Do NOT interview the user.** The PRD is synthesized from the task
+description + codebase investigation + AGENTS.md, not from a clarifying
+back-and-forth. If a section truly cannot be filled, write
+`{TBD — needs user input}`; do NOT pause for clarification (that is
+`apt:discuss`'s surface, not the planner's).
+
 ### 4.05. Design Reference section (C24 — when design.md exists)
 
 When `{task_dir}/design.md` exists, `spec.md` MUST include a `## Design Reference` section directly below `## Requirements`. Shape:
@@ -275,12 +344,41 @@ fix it now, not later.
 
 ## 5. Create Implementation Plan
 
-Create `{task_dir}/implementation_plan.json`:
+Subtask schema branches on track (Pocock adoption ID-05 — Fast Path Guarantee).
+
+### 5.A. QUICK track / SIMPLE complexity — legacy flat subtask schema
+
 ```json
 {
   "task": "{task description}",
-  "complexity": "simple|standard|complex",
+  "complexity": "simple",
   "spec": "spec.md",
+  "subtasks": [
+    {
+      "id": "1",
+      "title": "{subtask title}",
+      "description": "{what to do — concrete, not vague}",
+      "files": ["path/to/file1.ts", "path/to/file2.ts"],
+      "dependencies": [],
+      "status": "pending",
+      "verification": "{command or check to verify completion}"
+    }
+  ]
+}
+```
+
+QUICK subtasks omit `hitl`, `afk`, `acceptance_criteria`, and `user_value`
+fields. The one-shot path doesn't need user-value framing or per-subtask
+HITL gates.
+
+### 5.B. STANDARD / DEEP / COMPLEX — vertical-slice subtask schema
+
+```json
+{
+  "task": "{task description}",
+  "complexity": "standard|complex",
+  "spec": "spec.md",
+  "vertical_slice_schema_version": "1",
   "declared_persona_tier": "primary",
   "declared_personas": ["mobile-dev"],
   "tier_confidence": "high",
@@ -308,29 +406,48 @@ Create `{task_dir}/implementation_plan.json`:
   "subtasks": [
     {
       "id": "1",
-      "title": "{subtask title}",
+      "title": "{subtask title — user-value framing, not 'add UI'}",
       "description": "{what to do — concrete, not vague}",
       "files": ["path/to/file1.ts", "path/to/file2.ts"],
       "acceptance_criteria": ["AC1", "AC3"],
       "dependencies": [],
       "status": "pending",
+      "hitl": "required | review | none",
+      "afk": "safe | unsafe",
+      "user_value": "{one-line user-value framing — who benefits, how}",
       "verification": "{command or check to verify completion}"
     }
   ]
 }
 ```
 
+Mandatory STANDARD/DEEP fields per subtask:
+
+- `hitl` — `"required" | "review" | "none"`. `required` blocks the
+  executor pending human approval (autonomy 1 always pauses; autonomy 2
+  batches; autonomy 3 escalates only on conflict). `review` means the
+  human reviews the diff post-hoc, not blocking. `none` is agent-only.
+- `afk` — `"safe" | "unsafe"`. `safe` means proceed unattended. `unsafe`
+  means pause at the start of this subtask if no human is present
+  (autonomy < 3).
+- `acceptance_criteria` — `string[]` of id-refs (`"AC1"`, …) into spec.md's
+  `## Acceptance Criteria` section.
+- `user_value` — one-line framing of WHO benefits and HOW. Prevents
+  horizontal slicing — every subtask is a vertical user-shippable slice.
+
+Plan-level: `vertical_slice_schema_version: "1"` declares the schema
+version so future migrations can detect this plan as v1.
+
 Rules:
 - Each subtask completable in one focused session
 - Dependencies form a DAG (no circular deps)
 - Verification must be automated (test command, grep check, type check)
 - Files list must be exhaustive — every file the subtask touches
-- `acceptance_criteria` is mandatory: list the canonical AC id-refs
-  (`"AC1"`, `"AC3"`, ...) from the `## Acceptance Criteria` section of
-  spec.md that this subtask satisfies. Verbatim AC text is accepted but
-  discouraged — the id-ref form is stable across spec edits. Every AC in
-  spec.md must be referenced by at least one subtask; gate G8
-  (`consistency-check`) enforces this on ship.
+- `acceptance_criteria` is mandatory on STANDARD/DEEP: every AC in spec.md
+  must be referenced by at least one subtask; gate G8
+  (`consistency-check`) enforces this on ship. Verbatim AC text is
+  accepted but discouraged — id-refs are stable across spec edits.
+- Subtask title MUST frame user value, not file scope.
 
 ### 5.1 Framework-scope doc-sync rule
 

package/dist/plugin/agents/apt-pr-review-fixer.md

@@ -64,7 +64,7 @@ The only valid reasons to skip a finding:
    ```
    [TOOLCHAIN_COMMANDS]
    ```
-6. **If verification passes**: Stage with `git add [specific files]`
+6. **If verification passes**: Stage AND commit atomically per finding with `git add [specific files] && git commit -m "<finding-id>: <one-line>"` (BUG-016 — the audit gate only observes COMMITTED edits in the iteration window; stage-only leaves the index dirty and trips a false-positive hallucination verdict).
 7. **If verification fails**: Revert with `git checkout -- [file]`, mark as "manual fix required" in your report
 
 ---
@@ -89,7 +89,7 @@ Findings with severity `critical`:
 
 ## Report Format
 
-Write to `[REVIEW_DIR]/iterations/[N]/fixes-applied.md`:
+Write to `[REVIEW_DIR]/iterations/[N]/fixes-applied-[FIXER_NAME].md` (BUG-030 canonical naming — the audit gate resolves `fixes-applied-${FIXER_NAME}.md` ahead of the legacy `fixes-applied.md`, so parallel fixers no longer collide on a shared report path):
 
 ```markdown
 # Fix Report — Iteration [N]
@@ -142,11 +142,13 @@ Write to `[REVIEW_DIR]/iterations/[N]/fixes-applied.md`:
 
 ## Pre-Return Self-Audit (mandatory)
 
-Before emitting `VERIFICATION: PASS` or any `FIXED: N > 0` status, run BOTH of these inside the worktree:
+Before emitting `VERIFICATION: PASS` or any `FIXED: N > 0` status, run BOTH of these inside the worktree.
+
+The orchestrator passes you `[ITERATION_START_SHA]` — the SHA captured BEFORE fixers were spawned. The audit gate uses the same SHA as its `--since-sha` window, so your self-audit must mirror it (BUG-016):
 
 ```bash
+cd [WORKTREE_PATH] && git log [ITERATION_START_SHA]..HEAD --oneline
 cd [WORKTREE_PATH] && git diff --cached --name-only
-cd [WORKTREE_PATH] && git diff --name-only
 ```
 
 Paste the **literal command output** into your report under a new section:
@@ -154,11 +156,13 @@ Paste the **literal command output** into your report under a new section:
 ```markdown
 ## Pre-Return Self-Audit
 
-git diff --cached --name-only:
-<paste literal output, or empty if nothing staged>
+git log [ITERATION_START_SHA]..HEAD --oneline:
+<paste literal output — MUST list ≥ 1 commit per claimed fix>
 
-git diff --name-only:
-<paste literal output, or empty if nothing unstaged>
+git diff --cached --name-only:
+<paste literal output — MUST be empty (index clean after every commit)>
 ```
 
-**Rule:** if BOTH outputs are empty AND you claimed to have fixed ≥ 1 finding, your status line MUST be `FIXED: 0 | FAILED: N | SKIPPED: 0 | VERIFICATION: FAIL` and every claimed fix MUST be marked FAILED in the report with `- **Verification**: FAIL — no diff produced`. Do not emit `VERIFICATION: PASS` with an empty diff — the orchestrator runs an **independent** deterministic audit (see `/apt:pr-review` SKILL.md Phase 6 Step 4b, `apt-tools pr-review audit-fixer`) that cross-checks your status line against the worktree git state. Emitting `PASS` when the diff is empty will be caught deterministically and counted as a hallucination; your findings will be treated as unresolved and you may be re-spawned with an explicit hallucination callout.
+**Pass condition (BUG-016 — commit discipline):** the `git log` output MUST contain ≥ 1 commit attributable to this fixer (one commit per fixed finding, message prefixed with the finding id) AND `git diff --cached --name-only` MUST be empty. The previous "I see staged files" rule is OBSOLETE — staging without committing leaves the index dirty and the audit gate's `--since-sha` window (which scopes to committed diff for the current iteration) sees zero matching paths, false-positiving `hallucinated`.
+
+**Fail condition:** if `git log [ITERATION_START_SHA]..HEAD --oneline` is EMPTY AND you claimed to have fixed ≥ 1 finding, your status line MUST be `FIXED: 0 | FAILED: N | SKIPPED: 0 | VERIFICATION: FAIL` and every claimed fix MUST be marked FAILED in the report with `- **Verification**: FAIL — no commit produced`. Likewise if `git diff --cached --name-only` is NON-EMPTY (you forgot to commit some staged edits), status MUST be `VERIFICATION: FAIL` until the index is clean. Do not emit `VERIFICATION: PASS` with an empty commit log or dirty index — the orchestrator runs an **independent** deterministic audit (see `/apt:pr-review` SKILL.md Phase 6 Step 4b, `apt-tools pr-review audit-fixer`) that cross-checks your status line against the worktree git state. Emitting `PASS` when no commits exist will be caught deterministically and counted as a hallucination; your findings will be treated as unresolved and you may be re-spawned with an explicit hallucination callout.

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

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

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

@@ -15,7 +15,7 @@ execution_modes:
   - auto
   - step
 allowed-tools: "Bash, Read, Grep, Glob, Write"
-argument-hint: "apt:close-task [--all | --task <id>]"
+argument-hint: "apt:close-task [--all | --task <id>] [--narrate-only]"
 gates: []
 ---
 <objective>
@@ -40,6 +40,7 @@ Confirm a shipped PR has merged on GitHub, then run the closer side of the task
 - `.aperant/events/{today}.jsonl` — emits `task.closed.merged`.
 - `.aperant/config.json` — strips `authorship_overrides['pr-{N}']` entries for merged PRs.
 - `.aperant/roadmap/{scope}/**` — linked-phase flip (when `task_isolation.auto_close_phase: true`).
+- `.aperant/ci-watches/{pr}.json` — removed for each merged PR (BUG-027 (b) side-effect: prevents watcher state files leaking past PR-terminal-state). Idempotent — already-removed state is a no-op. For retroactive cleanup of orphan state files left behind by pre-fix runs, use `apt-tools ci-watch sweep . --orphaned`.
 </state_files>
 
 <process>
@@ -70,6 +71,7 @@ Internally, close-merged does:
    a. `apt-tools task close . --id {task-id} --verdict approved` (respects `task_isolation.auto_close_phase`).
    b. Strips `config.pr_review.authorship_overrides['pr-{N}']` if present.
    c. Emits `task.closed.merged` event.
+   d. Appends a `pending_narration[]` ledger row to `.aperant/state.json` so `--narrate-only` (see §4) can pick it up. Additive only; never blocks the close.
 3. When `state !== 'MERGED'`, the task stays in `shipped-pending-merge` with a skip reason the user can inspect.
 
 ## 2.5 Narrate completed phases (moved from /apt:ship in C56 B5)
@@ -85,6 +87,33 @@ For each entry in the close-merged envelope's `closed[]` whose record has a non-
 
 Do NOT wait on the narrator. Its status lands in `.aperant/digests/.last-run.json`. Skip narrator spawn entirely when `closed[]` is empty or no closed item has a phase_id.
 
+After step 2.5 spawns narrators for the just-closed candidates, the skill ALSO drains `state.pending_narration[]` (entries the passive sweep parked there) — see §4.
+
+## 2.6 Drop user-facing release-note fragment (persona-aware release-notes opt-in)
+
+This step is additive bookkeeping — it must NEVER block the close path or surface a destructive failure. Runs ONLY when `.aperant/config.json` has `changelog.release_notes.enabled === true`. When the toggle is `false` (the default for projects that don't publish user-facing notes), skip the section entirely.
+
+For each entry in the close-merged envelope's `closed[]`:
+
+1. Read the merged PR body via `gh pr view <pr_number> --json body`. Look for a single `Release note:` line (case-insensitive). The line is what `/apt:ship` Section 2.6 auto-drafted (or a manual edit by the author).
+2. Look for a persona tag in the PR body or in commits. Reasonable sources: the `Release note:` line itself if the author included one (e.g. `Release note: [Maya] …`), a `release-note-persona:` trailer in the most recent commit, or the persona name embedded in the auto-drafted line by §2.6.2 of /apt:ship.
+3. Invoke the deterministic drafter:
+
+```bash
+node packages/framework/bin/apt-tools.mjs release-notes draft . \
+  --pr <pr_number> \
+  --note "<release-note-line-text>" \
+  [--persona <persona-name>]
+```
+
+This call is synchronous, sub-100ms, and idempotent per subtask 2 — re-running close-task does not duplicate the fragment.
+
+4. On non-zero exit from `release-notes draft`, append a `pending_release_note[]` row to `.aperant/state.json` so a manual re-run can recover. Do NOT block close-merged on this — it is additive bookkeeping, not core lifecycle. Use `apt-tools state-update . --append-pending-release-note '{"task_id": "<id>", "pr_number": <n>, "reason": "<error>"}'` if such a helper exists, otherwise call `apt-tools state-artifacts . --note '<msg>'` or write a one-line warning to stderr.
+
+Skip the section quietly when:
+- The PR body has no `Release note:` line AND no auto-draft signal (intentional infra-only PR, or the `no-notes` label was applied at ship time).
+- The CLI returns `{status: 'ok', written: false, reason: 'no-change'}` — already idempotent-handled by subtask 2's contract; treat as success.
+
 ## 3. Summary
 
 close-merged emits an envelope with:
@@ -95,6 +124,39 @@ close-merged emits an envelope with:
 
 Report the summary verbatim. If anything landed in `skipped[]` with a recoverable reason (`offline`, `rate_limited`), suggest the user re-run once the network clears.
 
+**Local cleanup recap (best-effort).** On confirmed merge, `task close-merged` runs `computeWorktreeCleanup` against the primary repo (`packages/framework/src/cli/task/worktree-cleanup.mjs:140-230`): `git fetch origin <base>` (failure → recorded as `fetch_failed` warning, cleanup proceeds), `git checkout <base>` (failure → returns `action: 'checkout_failed'` and preserves BOTH the worktree and the task branch — nothing is removed), `git merge --ff-only origin/<base>` (failure → `ff_only_failed` warning, GC still runs), `git worktree remove <wtPath>`, and `git branch -d <taskBranch>` (failure on squash/rebase merges → `branch_delete_failed` warning, `branch_deleted: false` in the envelope; user can `git branch -D` manually). This is why `/apt:watch-ci` auto-merge MUST NOT pass `gh pr merge --delete-branch` — that flag would try to do the same work from inside the worktree where `git switch <base>` cannot succeed (see FRAMEWORK-BUG-019).
+
+## 4. Narrate-only mode
+
+When invoked with `--narrate-only`, skip §1 (no `gh pr view` polling) and §2 (no destructive close path). The deterministic close already ran via the passive post-merge sweep — your job is to drain the `state.pending_narration[]` ledger the sweep parked.
+
+Flags:
+- `--narrate-only --all` (default when `--narrate-only` is bare) — drain every ledger entry.
+- `--narrate-only --task <id>` — drain only the entry for `<id>`.
+
+Per ledger entry `{ task_id, scope, phase_id, closed_at, pr_number }`:
+
+0. **Enumerate the ledger first.** Run `apt-tools task close-merged . --narrate-only [--task <id>]`. The envelope's `closed[]` is the read-only list of pending narration rows (each carries `narration_pending: true`); state.json is not mutated. When `closed[]` is empty, exit early with `{status: 'ok', narrated: [], skipped: [], remaining: 0}` — there is nothing to drain.
+1. Run `apt-tools features-audit . --apply-stubs --task <task_id>` so the feature registry catches whatever the closed task introduced. If the subprocess exits non-zero, skip the entry with `reason: 'features-audit-failed'` — never block narration on registry update.
+2. When `phase_id` is non-null, spawn `apt-team-docs-narrator` (background, fire-and-forget) using the same shape as §2.5: `subagent_type: apt-team-docs-narrator`, `run_in_background: true`, `description: Narrate shipped phase {phase_id}`, `prompt: Run in phase-ship mode with --phase {phase_id} --scope {scope}.`. When `phase_id` is null, skip the spawn with `reason: 'no-phase-id'` (quick tasks have no phase to narrate).
+3. On successful spawn (or successful no-phase skip), drain the row via `apt-tools task narration-drain . --task <task_id>` which acquires `withFileLock(state.json)` and removes the matching `pending_narration[]` entry. On spawn failure, leave the row in place with `reason: 'narrator-spawn-failed'` so the user can re-invoke.
+
+**At-least-once retry semantics (FRAMEWORK-BUG-020).** Step 0 is read-only — it does NOT remove rows. Steps 1–3 are the existing per-row drain contract: a row stays in `pending_narration[]` until step 3 calls `narration-drain` successfully. If the orchestrator crashes between step 2 (narrator spawn) and step 3 (drain), the row remains parked and a retry will spawn narration again. Re-spawning is safe because the narrator is **anchor-replace idempotent** by design (see `agents/apt-team-docs-narrator.md` §6 / §2 and the "Idempotent operations only" rule in §notes) — it uses HTML-comment anchors to bound the replaced region in ROADMAP.md, so a second run replaces the same span rather than appending.
+
+Emit a summary envelope:
+
+```json
+{
+  "status": "ok",
+  "command": "close-task-narrate-only",
+  "narrated": [{ "task_id": "<id>", "phase_id": "<p|null>", "scope": "<s>" }],
+  "skipped": [{ "task_id": "<id>", "reason": "no-phase-id|features-audit-failed|narrator-spawn-failed" }],
+  "remaining": <ledger.length>
+}
+```
+
+The regular `apt:close-task` flow ALSO falls through to this drain step at the tail of §2.5 — so users who run the skill manually after the sweep get narration without remembering the flag. The `--narrate-only` flag exists for the explicit "drain only, don't poll gh" case.
+
 </process>
 
 <notes>

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

@@ -21,6 +21,19 @@ gates: []
 ---
 <objective>
 Debug an issue using the scientific method: observe symptoms, form hypotheses, test them systematically, and reach a conclusion. State persists across context resets via `.aperant/debug/{session-id}/DEBUG.md`.
+
+**Diagnose-discipline posture loader (Pocock adoption AC10).** You MUST
+load `appendices/diagnose-discipline.md` into reasoning context at
+session start. It carries the 6-phase loop (Reproduce → Minimise →
+Hypothesise → Instrument → Fix → Regression-test) and the **Phase-1
+prerequisite** constraint: do NOT advance from Observe (Section 2) to
+Hypothesize (Section 3) until DEBUG.md records `repro_loop_verified:
+true`. The appendix carries the rationale, the anti-pattern list
+(sprint-to-hypothesis, stack-trace cargo cult, test-the-fix-not-the-bug,
+logging-without-minimising), and the distinction between Phase 1
+"reproduce" and Phase 2 "minimise". Open question #1 was verified —
+apt:debug's existing Section 2 conflates symptom-gathering with
+reproduction, so loading this appendix is non-trivial.
 </objective>
 
 <your_environment>
@@ -59,18 +72,38 @@ mkdir -p .aperant/debug/{session-id}
 mkdir -p .aperant/debug/{session-id}/checkpoints
 ```
 
-## 2. Observe — Gather Symptoms
+## 2. Observe — Gather Symptoms + Phase 1 (Reproduce — prerequisite)
+
+Collect all available evidence about the bug, then establish a
+**reliable repro loop as a hard prerequisite** before advancing to
+Section 3 (Hypothesize). The Phase-1-reproduce constraint comes from
+`appendices/diagnose-discipline.md` and is load-bearing — you do NOT
+emit any hypothesis until DEBUG.md records `repro_loop_verified: true`.
 
-Collect all available evidence about the bug:
+Sub-steps (the existing 4 + 1 prerequisite check):
 
 1. **User description:** Extract from `$ARGUMENTS` what the issue is
 2. **Error output:** If the user provided error messages, record them verbatim
-3. **Reproduce:** Attempt to reproduce the issue:
-   - Run relevant test commands
-   - Check logs, console output
-   - Identify the exact failure point
+3. **Phase 1 — Reproduce (prerequisite, per appendices/diagnose-discipline.md):**
+   Establish a reliable repro loop. The loop MUST be:
+   - Deterministic (same input → same failure)
+   - Cheap (under 10 seconds preferred; certainly under 60)
+   - Minimal (no irrelevant setup; just enough to fail)
+   Record the repro command + verification in DEBUG.md as
+   `repro_command: "..."` and `repro_loop_verified: true`. If you
+   cannot reproduce reliably, do NOT proceed to Section 3 — instead,
+   loop here: gather more environment context, add logging to the
+   target environment, ask the user for repro details. Hypothesis-driven
+   debugging without a reliable repro is just hope, dressed up as
+   method.
 4. **Context:** Note environment details (branch, recent commits, dependencies)
 
+After Phase 1 succeeds, run **Phase 2 — Minimise** (also from the
+appendix): strip the repro to the smallest case that still fails.
+Record the minimised repro in DEBUG.md as `minimised_repro: "..."`.
+Phase 2 prevents Sections 3-5 from anchoring on the first plausible
+cause inside a 200-line repro.
+
 ```bash
 git log --oneline -10
 git diff --stat

package/dist/plugin/skills/apt-debug/appendices/diagnose-discipline.md

@@ -0,0 +1,119 @@
+<!--
+Adapted from Matt Pocock's MIT-licensed skill suite:
+https://github.com/mattpocock/skills/blob/main/skills/engineering/diagnose
+Licensed under MIT. Modifications: ported as an apt:debug posture loader
+so the 6-phase loop attaches to the existing 5-phase apt:debug body
+without forking apt:debug's control flow. Aligned with apt:debug's
+DEBUG.md state file and checkpoint conventions.
+-->
+
+# Diagnose Discipline — apt:debug posture loader (6-phase loop)
+
+This appendix loads into `apt:debug`'s reasoning context as a posture
+upgrade. The existing apt:debug body has 5 phases (Observe → Hypothesize
+→ Checkpoint → Test → Conclude) but its Section 2 "Observe" conflates
+symptom-gathering with reproduction. Open question #1 was verified — the
+gap is real, the appendix is non-trivial.
+
+This appendix carries the 6-phase Pocock discipline. The skill body
+loads it and uses Phase 1 (Reproduce) as a **hard prerequisite** before
+advancing from Observe to Hypothesize.
+
+## The 6-phase loop
+
+1. **Reproduce.** Establish a reliable repro loop. Until you can
+   trigger the bug at will, no hypothesis is testable — you'd be
+   guessing about a moving target. The loop MUST be:
+   - Deterministic (same input → same failure)
+   - Cheap (under 10 seconds preferred; certainly under 60)
+   - Minimal (no irrelevant setup; just enough to fail)
+
+2. **Minimise.** Once you can repro, strip the repro to the smallest
+   case. Remove every component that isn't load-bearing for the
+   failure. A 200-line repro is a hypothesis space; a 10-line repro is
+   a near-confirmed cause.
+
+3. **Hypothesise.** ONLY after minimise: write 3-5 ranked falsifiable
+   hypotheses. Each hypothesis must:
+   - Predict an observable consequence
+   - Be testable by changing ONE variable
+   - Be ordered by prior probability + cost-to-test
+
+4. **Instrument.** Add the minimum logging / breakpoint / probe to test
+   the highest-ranked hypothesis. Change ONE variable. Re-run the
+   minimal repro. Observe.
+
+5. **Fix.** When a hypothesis confirms, write the fix. Run the minimal
+   repro again — it must now PASS (no more failure). Run the full test
+   suite — no new regressions.
+
+6. **Regression-test.** Write a test that pins the fix. The test must
+   fail on the pre-fix code and pass on the fixed code. This is what
+   stops the bug from coming back six months later when someone
+   refactors.
+
+## The Phase-1 prerequisite (load-bearing)
+
+apt:debug's body enforces this constraint: **you do NOT advance from
+Observe to Hypothesize until Phase 1 produces a reliable repro loop**.
+
+If you cannot reproduce reliably:
+
+- Spend the budget on getting the repro working before guessing causes
+- Add logging in the production / target environment to gather more
+  evidence of the failure trigger
+- Ask the user for more context (when does it happen? on what input?
+  intermittent or consistent?)
+
+It is better to spend 80% of your debug budget on the repro and 20% on
+the fix than to spend 100% guessing at causes. Hypothesis-driven
+debugging without a reliable repro is just hope, dressed up as method.
+
+## Distinguishing Phase 1 from apt:debug's existing "Observe"
+
+apt:debug's existing Section 2 collects symptom evidence (error
+messages, user reports, environment). That's still valuable — it's the
+*input* to Phase 1. But "I read the error and inferred the cause"
+DOES NOT count as a repro. The repro is a callable artifact: a
+command-line invocation, a test, a script — something the agent can
+run on demand to trigger the failure.
+
+## Distinguishing Phase 2 (Minimise) from Phase 3 (Hypothesise)
+
+These are different mental modes. Minimise asks "what's the smallest
+thing that still fails?" — a reductive activity. Hypothesise asks
+"WHY does it fail?" — an explanatory activity. Pocock's discipline
+separates them because skipping Phase 2 and going straight from "I can
+repro" to "here's why" tends to anchor on the first plausible cause
+and miss alternatives.
+
+## Practical consequence for the apt:debug body
+
+When this appendix is loaded, apt:debug's Section 2 (Observe) renames
+its "Reproduce" sub-step to **Phase 1 (Reproduce — prerequisite)** and
+adds a gate: the skill MUST NOT emit any hypothesis (Section 3) until
+DEBUG.md records a `repro_loop_verified: true` field.
+
+The appendix's Phase 2 (Minimise) becomes a new sub-section between
+apt:debug's Section 2 (Observe) and Section 3 (Hypothesize). DEBUG.md
+gains a `minimised_repro` field.
+
+apt:debug's Sections 3-5 (Hypothesize / Checkpoint / Test / Conclude)
+align with Phases 3-6 of this appendix; no structural change there.
+
+## Anti-patterns this discipline prevents
+
+- **Sprint-to-hypothesis.** Agent reads the error, picks the first
+  plausible cause, writes a fix, and ships. The bug comes back two
+  days later under different inputs.
+- **Stack-trace cargo cult.** Agent assumes the line at the top of the
+  stack trace IS the bug. Often it's an effect, not a cause.
+- **Test the fix, not the bug.** Agent writes a test that proves the
+  fix works but doesn't exercise the original buggy condition. The
+  regression test is a no-op against the future regression.
+- **Logging without minimising.** Agent adds 50 log lines in a 200-line
+  repro, then drowns in noise. Minimise first; THEN instrument the
+  minimal repro.
+
+Loading this appendix and following its Phase 1 prerequisite cuts most
+of these failure modes by structural constraint.