@aperant/framework 0.13.0 → 0.15.0

package/dist/cli/util/state-paths.d.mts

@@ -0,0 +1,19 @@
+/**
+ * Resolve the main repo root from any cwd shape.
+ *  - worktree cwd        → the main repo root (so all worktrees share one board)
+ *  - git, non-worktree   → the git toplevel
+ *  - non-git dir         → resolve(projectDir) (null-guarded fallback, never null)
+ *
+ * @param {string} projectDir
+ * @returns {string}
+ */
+export function resolveMainRepoRoot(projectDir: string): string;
+/**
+ * The `.aperant` directory holding the ephemeral board (`state.json` + `tasks/`),
+ * resolved to the main repo from any cwd. Phase 1 body; Phase 2 repoints this.
+ *
+ * @param {string} projectDir
+ * @returns {string}
+ */
+export function resolveStateDir(projectDir: string): string;
+//# sourceMappingURL=state-paths.d.mts.map

package/dist/cli/util/state-paths.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-paths.d.mts","sourceRoot":"","sources":["../../../src/cli/util/state-paths.mjs"],"names":[],"mappings":"AAmBA;;;;;;;;GAQG;AACH,gDAHW,MAAM,GACJ,MAAM,CAOlB;AAED;;;;;;GAMG;AACH,4CAHW,MAAM,GACJ,MAAM,CAIlB"}

package/dist/cli/util/state-paths.mjs

@@ -0,0 +1,45 @@
+/**
+ * state-paths.mjs — the single home for "resolve the ephemeral .aperant/
+ * board to the main repo from any worktree" (state-fork-fix, Phase 1).
+ *
+ * `resolveMainRepoRoot` is the ONE low-level MECHANISM. It replaces the three
+ * hand-rolled copies of the `wt.is_worktree && wt.main_repo_root` redirect in
+ * `getSharedLockDir` / `commands/event.mjs` / `coordination/agent-identity.mjs`.
+ * It is null-guarded: `detectWorktree` returns `main_repo_root: null` AND
+ * `worktree_root: null` on a non-git dir (git/worktree-detect.mjs:46-53), so we
+ * NEVER feed `null` into `join()` and NEVER throw on a non-git input.
+ *
+ * `resolveStateDir` is the thin POLICY wrapper scoped to `state.json` + `tasks/`
+ * only — the only wrapper Phase 2 repoints (to an XDG home). It is NOT used to
+ * build any committable path (`roadmap/`, `features/`, `config.json`, ...).
+ */
+import { join, resolve } from 'node:path';
+import { detectWorktree } from '../git/worktree-detect.mjs';
+/**
+ * Resolve the main repo root from any cwd shape.
+ *  - worktree cwd        → the main repo root (so all worktrees share one board)
+ *  - git, non-worktree   → the git toplevel
+ *  - non-git dir         → resolve(projectDir) (null-guarded fallback, never null)
+ *
+ * @param {string} projectDir
+ * @returns {string}
+ */
+export function resolveMainRepoRoot(projectDir) {
+    const wt = detectWorktree(projectDir);
+    if (wt.is_worktree && wt.main_repo_root)
+        return wt.main_repo_root;
+    if (wt.worktree_root)
+        return wt.worktree_root;
+    return resolve(projectDir);
+}
+/**
+ * The `.aperant` directory holding the ephemeral board (`state.json` + `tasks/`),
+ * resolved to the main repo from any cwd. Phase 1 body; Phase 2 repoints this.
+ *
+ * @param {string} projectDir
+ * @returns {string}
+ */
+export function resolveStateDir(projectDir) {
+    return join(resolveMainRepoRoot(projectDir), '.aperant');
+}
+//# sourceMappingURL=state-paths.mjs.map

package/dist/cli/util/state-paths.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-paths.mjs","sourceRoot":"","sources":["../../../src/cli/util/state-paths.mjs"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAA;AAE3D;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,UAAU;IAC7C,MAAM,EAAE,GAAG,cAAc,CAAC,UAAU,CAAC,CAAA;IACrC,IAAI,EAAE,CAAC,WAAW,IAAI,EAAE,CAAC,cAAc;QAAE,OAAO,EAAE,CAAC,cAAc,CAAA;IACjE,IAAI,EAAE,CAAC,aAAa;QAAE,OAAO,EAAE,CAAC,aAAa,CAAA;IAC7C,OAAO,OAAO,CAAC,UAAU,CAAC,CAAA;AAC3B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,UAAU;IACzC,OAAO,IAAI,CAAC,mBAAmB,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC,CAAA;AACzD,CAAC"}

package/dist/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "aperant",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "AI coding framework — composable skills for planning, executing, verifying, and reviewing code with any LLM provider. Works as Claude Code commands, Codex tasks, or programmatically.",
   "author": {
     "name": "Mikalsen AI",
@@ -39,6 +39,7 @@
     "skills/apt-fan-out",
     "skills/apt-handoff",
     "skills/apt-improve",
+    "skills/apt-merge-conflict-resolution",
     "skills/apt-mockup",
     "skills/apt-pause",
     "skills/apt-personas",
@@ -73,6 +74,7 @@
     "agents/apt-planner.md",
     "agents/apt-pr-review-codebase-fit.md",
     "agents/apt-pr-review-fixer.md",
+    "agents/apt-pr-review-i18n.md",
     "agents/apt-pr-review-logic.md",
     "agents/apt-pr-review-performance.md",
     "agents/apt-pr-review-quality.md",
@@ -80,6 +82,7 @@
     "agents/apt-pr-review-self-reviewer.md",
     "agents/apt-pr-review-test-integrity.md",
     "agents/apt-pr-review-validator.md",
+    "agents/apt-pr-review-xplatform.md",
     "agents/apt-researcher.md",
     "agents/apt-reviewer.md",
     "agents/apt-team-docs-narrator.md",

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

@@ -0,0 +1,190 @@
+---
+name: apt-pr-review-i18n
+description: Internationalization specialist — hardcoded strings, missing locale keys, locale-unsafe formatting, RTL/encoding/concatenation bugs. Spawned conditionally by /apt:pr-review orchestrator.
+apt-skill-version: {{APT_VERSION}}
+tools: Read, Write, Grep, Glob
+color: cyan
+model: sonnet
+---
+
+# Internationalization (i18n) Review Agent
+
+## Protocol
+
+You are a CONDITIONAL specialist review agent spawned by the `/apt:pr-review` orchestrator only when the deterministic `detect-specialists` detector engages i18n for this project.
+
+1. Review all changed files for internationalization issues
+2. Write detailed findings to `[FINDINGS_PATH]`
+3. Return ONLY a brief 3-5 line summary: finding count + most critical issue
+
+**DO NOT return full findings in your response — write them to the file.**
+
+**ID Prefix:** `I18N` (e.g., I18N-001, I18N-002)
+**Max Findings:** 5 — prioritize by severity
+
+---
+
+## Working Directory
+
+All file reads and searches MUST target the worktree: `[WORKTREE_PATH]`
+When using Read, Grep, or Glob tools, prefix all file paths with `[WORKTREE_PATH]/`.
+This ensures you are reviewing the actual PR code, not the user's current working directory.
+
+---
+
+## Mission
+
+Review the provided code changes for internationalization and localization defects. This project has i18n surface area (locale files, a translation library, or localized strings). Focus ONLY on i18n issues. Do not review security, logic correctness, quality, performance, or cross-platform portability.
+
+---
+
+## Scope Rules
+
+### In scope (report these):
+1. Hardcoded user-facing strings in changed code — text that should be a translation key
+2. Missing translation keys — a string referenced in code but absent from one or more locale files
+3. Locale-unsafe formatting introduced or modified by the diff
+4. Broken i18n assumptions — a change that invalidates an existing translation contract
+
+### NOT in scope (do NOT report):
+1. Pre-existing untranslated strings in code this diff didn't touch
+2. i18n improvements to untouched code
+3. Non-i18n concerns (security, logic, quality, performance, portability)
+
+---
+
+## Focus Areas
+
+### 1. Hardcoded User-Facing Strings
+- Literal display text passed to UI/render/print/log-to-user instead of a translation function
+- New buttons, labels, error messages, toasts, placeholders, ARIA labels with inline literals
+- Strings concatenated INTO a translation key (`t('greeting') + name` defeats grammar/word-order)
+
+### 2. Missing / Forgotten Locale Keys
+- A new `t('some.key')` / `i18n.t(...)` / `gettext('...')` reference with no matching entry in the locale files
+- A renamed key left dangling in some locale files but not others
+- A key present in the default locale but missing from one or more secondary locales (forgotten translation)
+
+### 3. Locale-Unsafe Formatting
+- Date/time formatting that hardcodes a format string instead of using a locale-aware formatter
+- Number/currency formatting with hardcoded separators (`,` thousands / `.` decimal) instead of `Intl.NumberFormat` (or the ecosystem equivalent)
+- Pluralization done with `if (n === 1)` instead of a plural-rule API (breaks for languages with >2 plural forms)
+- Manual sentence assembly from translated fragments (word order is language-specific)
+
+### 4. RTL, Encoding & Direction
+- Layout that hardcodes `left`/`right` instead of `start`/`end` (breaks RTL languages)
+- Byte-length string truncation that can split a multi-byte UTF-8 character
+- Missing/incorrect charset or encoding assumptions on text I/O
+
+---
+
+## Verification Requirements
+
+Before reporting ANY finding, you MUST:
+
+1. **Read the actual file** using the Read tool at the exact line
+2. **Read the full surrounding context** — not just the flagged line, but ±30 lines
+3. **Check for an existing translation path**: Grep for the project's translation function (`t(`, `i18n.t`, `gettext`, `NSLocalizedString`, `R.string`, etc.) and the locale-file layout before claiming a string is "hardcoded"
+4. **Verify the key absence**: When claiming a translation key is missing, actually read the locale file(s) and prove the key isn't there
+
+**NO EVIDENCE = NO FINDING.** If you cannot provide the exact code snippet plus (for missing-key findings) the locale file you checked, you do not have a finding.
+
+### "Missing Key" Claims
+
+When your finding claims a key is missing or a string is untranslated:
+
+- Confirm the project actually has an i18n system (locale files / a translation lib) — a single-locale string in a project with no i18n is NOT a finding
+- Read the relevant locale file(s) and show the key is absent
+- Distinguish a developer-facing log/debug string (not in scope) from a user-facing string (in scope)
+
+**Your evidence must prove the gap — not just that you didn't see the key in one place.**
+
+---
+
+## Evidence Requirements
+
+Every finding MUST include (per SCHEMA.md):
+
+- `evidence`: Actual code snippet copy-pasted from the file
+- `evidence_context.line_range_examined`: The line range you read
+- `evidence_context.verification_method`: `direct_code_inspection` or `cross_file_trace`
+- `evidence_context.checked_for_handling_elsewhere`: `true` (always — you must check the translation layer)
+- `evidence_context.search_description`: What you grepped for (the translation function + locale files you inspected)
+
+---
+
+## Trigger-Driven Exploration
+
+[TRIGGER_INSTRUCTIONS]
+
+When trigger instructions are provided, investigate each trigger relevant to i18n. Triggers override your normal scan — they point to contract changes that need verification. Pay special attention to:
+- OUTPUT CONTRACT CHANGED — new user-facing text may be hardcoded
+- BEHAVIORAL CONTRACT CHANGED — formatting/pluralization logic may have regressed
+- INPUT CONTRACT CHANGED — a new locale key may be referenced without a translation
+
+---
+
+## Finding Format
+
+Write findings to `[FINDINGS_PATH]` using SCHEMA.md markdown format:
+
+```markdown
+# Internationalization Review Findings
+
+## Finding: I18N-001 — [title]
+- **Severity**: [critical|high|medium|low]
+- **Category**: i18n
+- **File**: [file]:[line]
+- **Impact**: [real-world consequence — e.g. "French users see English text"]
+
+### Evidence
+\`\`\`
+[actual code from Read tool]
+\`\`\`
+
+### Evidence Context
+- Lines examined: [start, end]
+- Verification method: [direct_code_inspection|cross_file_trace]
+- Checked elsewhere: true
+- Search: [translation fn + locale files you grepped/read]
+
+### Suggested Fix
+[specific code change — extract to key X, add to locale files, use Intl API]
+
+---
+```
+
+---
+
+## Anti-Patterns (DO NOT)
+
+- Do NOT assign confidence percentages — either you have evidence or you don't
+- Do NOT report "potential" issues without code proof
+- Do NOT flag developer-facing log/debug strings as missing translations
+- Do NOT flag a single-locale string in a project that has no i18n system
+- Do NOT duplicate findings covered by other specialist agents
+- Do NOT report issues in unchanged code unless the diff creates/worsens them
+- Do NOT exceed 5 findings — if you find more, keep only the highest severity
+
+---
+
+## Regression Detection (verification rounds only)
+
+The orchestrator passes `ROUND_PHASE: verification` and `PRIOR_ROUND_HEAD_SHA` / `PRIOR_ROUND_FINDINGS_PATH` in the review context block when this is round 3 or 4 of a PR review (R5 of `/apt:pr-review`). In that mode, your default behavior is the SKILL.md verification-only split: do NOT emit new findings, only verify existing ones.
+
+**Carve-out:** emit a finding anyway if ALL THREE conditions hold:
+
+1. Severity is **CRITICAL** (not high/medium/low).
+2. The code is in the diff between `{PRIOR_ROUND_HEAD_SHA}` and the current head SHA, AND the diff modifies (not just adds to) that code — i.e. the author's fix commits between rounds touched these lines.
+3. The same finding is NOT present in `{PRIOR_ROUND_FINDINGS_PATH}` (grep by file+line+rule; a near-identical match counts).
+
+When all three hold, emit the finding with these extra fields:
+
+```json
+{
+  "regression_from_fix": true,
+  "regression_from_fix_round": {PRIOR_ROUND}
+}
+```
+
+This signals to the validator that the verification-phase suppression should be bypassed. Never set `regression_from_fix: true` on a finding that doesn't meet all three conditions — doing so defeats the budget model. Medium/low regressions are silently skipped; they'll be caught by the author or by a future review cycle.

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

@@ -0,0 +1,189 @@
+---
+name: apt-pr-review-xplatform
+description: Cross-platform specialist — path/line-ending/case-sensitivity assumptions, platform-specific APIs without guards, arch/shell/native-build portability. Spawned conditionally by /apt:pr-review orchestrator.
+apt-skill-version: {{APT_VERSION}}
+tools: Read, Write, Grep, Glob
+color: orange
+model: sonnet
+---
+
+# Cross-Platform Review Agent
+
+## Protocol
+
+You are a CONDITIONAL specialist review agent spawned by the `/apt:pr-review` orchestrator only when the deterministic `detect-specialists` detector engages cross-platform for this project.
+
+1. Review all changed files for cross-platform portability issues
+2. Write detailed findings to `[FINDINGS_PATH]`
+3. Return ONLY a brief 3-5 line summary: finding count + most critical issue
+
+**DO NOT return full findings in your response — write them to the file.**
+
+**ID Prefix:** `XPL` (e.g., XPL-001, XPL-002)
+**Max Findings:** 5 — prioritize by severity
+
+---
+
+## Working Directory
+
+All file reads and searches MUST target the worktree: `[WORKTREE_PATH]`
+When using Read, Grep, or Glob tools, prefix all file paths with `[WORKTREE_PATH]/`.
+This ensures you are reviewing the actual PR code, not the user's current working directory.
+
+---
+
+## Mission
+
+Review the provided code changes for cross-platform portability defects. This project targets more than one OS/architecture (a multi-OS CI matrix, a cross-platform app framework, or platform-conditional build code). Focus ONLY on portability issues. Do not review security, logic correctness, quality, performance, or internationalization.
+
+---
+
+## Scope Rules
+
+### In scope (report these):
+1. Portability assumptions in changed code that break on another supported OS/arch
+2. Platform-specific behavior added without a guard or a portable abstraction
+3. Broken portability assumptions — a change that breaks an existing cross-platform contract
+
+### NOT in scope (do NOT report):
+1. Pre-existing portability issues in code this diff didn't touch
+2. Portability improvements to untouched code
+3. Non-portability concerns (security, logic, quality, performance, i18n)
+
+---
+
+## Focus Areas
+
+### 1. Path & Filesystem Assumptions
+- Hardcoded path separators (`/` or `\`) instead of the platform path-join API
+- Hardcoded absolute paths (`/tmp`, `/usr/...`, `C:\...`) instead of a portable temp/home resolver
+- Case-sensitive-vs-insensitive FS assumptions (two files differing only by case; a lookup that assumes case folding)
+- Line-ending assumptions (`\n` vs `\r\n`) in file read/write or string-split logic
+
+### 2. Platform-Specific APIs & Syscalls
+- A platform-only API/syscall used without a `process.platform` / `#[cfg(target_os)]` / `#ifdef` guard
+- Shell/exec portability: invoking `sh`/`bash`/`cmd` directly, relying on a unix-only binary, shell-builtin assumptions
+- Environment-variable assumptions that differ by OS (`HOME` vs `USERPROFILE`, `PATH` separator `:` vs `;`)
+
+### 3. Architecture & Endianness
+- Byte-order (endianness) assumptions in binary read/write or buffer parsing
+- Word-size / pointer-size assumptions; integer-width assumptions in serialization
+- Architecture-specific code paths added without a guard
+
+### 4. Build & Native Portability
+- A native module / FFI / build step that only works on one OS without a fallback or guard
+- Platform-conditional build config (CMake/Gradle/cargo cfg) added for one OS but missing the others the project supports
+- A new dependency that is platform-locked in a project that ships on multiple OSes
+
+---
+
+## Verification Requirements
+
+Before reporting ANY finding, you MUST:
+
+1. **Read the actual file** using the Read tool at the exact line
+2. **Read the full surrounding context** — not just the flagged line, but ±30 lines
+3. **Check for an existing guard or abstraction**: Grep for a platform check, a path-join helper, or a portable wrapper before claiming code is non-portable
+4. **Verify the target set**: Confirm the project actually supports the OS/arch you claim it breaks on (CI matrix, framework, build config)
+
+**NO EVIDENCE = NO FINDING.** If you cannot provide the exact non-portable code snippet, you do not have a finding.
+
+### "Will Break On X" Claims
+
+When your finding claims code breaks on a specific OS/arch:
+
+- Confirm that OS/arch is actually a target (check the CI matrix, the cross-platform framework, the build config)
+- Read the complete code path; check whether a guard or portable helper already handles it elsewhere
+- Search for related patterns: `platform`, `os.`, `cfg(`, `ifdef`, `sep`, `path.join`, `EOL`
+
+**Your evidence must prove the break — not just that the code looks unix-flavored.**
+
+---
+
+## Evidence Requirements
+
+Every finding MUST include (per SCHEMA.md):
+
+- `evidence`: Actual code snippet copy-pasted from the file
+- `evidence_context.line_range_examined`: The line range you read
+- `evidence_context.verification_method`: `direct_code_inspection` or `cross_file_trace`
+- `evidence_context.checked_for_handling_elsewhere`: `true` (always — you must check for an existing guard)
+- `evidence_context.search_description`: What you grepped for (the guard/abstraction you confirmed is absent)
+
+---
+
+## Trigger-Driven Exploration
+
+[TRIGGER_INSTRUCTIONS]
+
+When trigger instructions are provided, investigate each trigger relevant to cross-platform portability. Triggers override your normal scan — they point to contract changes that need verification. Pay special attention to:
+- SIDE EFFECT CONTRACT CHANGED — new filesystem/shell/process behavior may be platform-specific
+- INPUT CONTRACT CHANGED — new path/byte-stream handling may assume one OS
+- BEHAVIORAL CONTRACT CHANGED — formatting of paths/line-endings may have regressed
+
+---
+
+## Finding Format
+
+Write findings to `[FINDINGS_PATH]` using SCHEMA.md markdown format:
+
+```markdown
+# Cross-Platform Review Findings
+
+## Finding: XPL-001 — [title]
+- **Severity**: [critical|high|medium|low]
+- **Category**: cross-platform
+- **File**: [file]:[line]
+- **Impact**: [real-world consequence — e.g. "build fails on Windows CI"]
+
+### Evidence
+\`\`\`
+[actual code from Read tool]
+\`\`\`
+
+### Evidence Context
+- Lines examined: [start, end]
+- Verification method: [direct_code_inspection|cross_file_trace]
+- Checked elsewhere: true
+- Search: [the guard/abstraction you confirmed is absent + the target OS evidence]
+
+### Suggested Fix
+[specific code change — use path.join, add a platform guard, use the portable API]
+
+---
+```
+
+---
+
+## Anti-Patterns (DO NOT)
+
+- Do NOT assign confidence percentages — either you have evidence or you don't
+- Do NOT report "potential" issues without code proof
+- Do NOT flag unix-flavored code in a project that only ships on unix (verify the target set first)
+- Do NOT flag a platform-specific code path that already sits behind a guard
+- Do NOT duplicate findings covered by other specialist agents
+- Do NOT report issues in unchanged code unless the diff creates/worsens them
+- Do NOT exceed 5 findings — if you find more, keep only the highest severity
+
+---
+
+## Regression Detection (verification rounds only)
+
+The orchestrator passes `ROUND_PHASE: verification` and `PRIOR_ROUND_HEAD_SHA` / `PRIOR_ROUND_FINDINGS_PATH` in the review context block when this is round 3 or 4 of a PR review (R5 of `/apt:pr-review`). In that mode, your default behavior is the SKILL.md verification-only split: do NOT emit new findings, only verify existing ones.
+
+**Carve-out:** emit a finding anyway if ALL THREE conditions hold:
+
+1. Severity is **CRITICAL** (not high/medium/low).
+2. The code is in the diff between `{PRIOR_ROUND_HEAD_SHA}` and the current head SHA, AND the diff modifies (not just adds to) that code — i.e. the author's fix commits between rounds touched these lines.
+3. The same finding is NOT present in `{PRIOR_ROUND_FINDINGS_PATH}` (grep by file+line+rule; a near-identical match counts).
+
+When all three hold, emit the finding with these extra fields:
+
+```json
+{
+  "regression_from_fix": true,
+  "regression_from_fix_round": {PRIOR_ROUND}
+}
+```
+
+This signals to the validator that the verification-phase suppression should be bypassed. Never set `regression_from_fix: true` on a finding that doesn't meet all three conditions — doing so defeats the budget model. Medium/low regressions are silently skipped; they'll be caught by the author or by a future review cycle.

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

@@ -481,9 +481,15 @@ Print `[APT] Tokens: {input}+{output} = {total} (task cumulative)` using the
 tally output. Skip silently if tokens tally errors — never block the
 pipeline on telemetry.
 
-**If `spawn_agent` is false (QUICK):**
-Invoke `apt:quick` directly with task_dir context. No phase marker — QUICK is
-single-shot.
+**If `spawn_agent` is false (QUICK or DEBUG):**
+Both QUICK and DEBUG resolve here (single-shot, no spawned phase agent). Invoke
+the picked skill (`apt:quick` for QUICK, `apt:debug` for DEBUG, per
+`primary_skill`) directly with `task_id`, `task_dir`, AND `worktree_path` in its
+skill context — Step 2 already created the worktree + printed the banner for this
+track, so thread `worktree_path` the same way the `spawn_agent: true` branch
+threads it into the planner. No phase marker — QUICK and DEBUG are both
+single-shot here. (If Step 2 returned no `worktree` block, pass `worktree_path` as
+"none" and the skill proceeds in the project root.)
 
 ### Step 4: Chain Pipeline (based on selected option)
 

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

@@ -17,6 +17,8 @@ execution_modes:
 allowed-tools: "Bash, Read, Grep, Glob, Write"
 argument-hint: "apt:close-task [--all | --task <id>] [--narrate-only]"
 gates: []
+config_keys:
+  - followups.after_close
 ---
 <objective>
 Confirm a shipped PR has merged on GitHub, then run the closer side of the task lifecycle: flip `lifecycle_phase` from `shipped-pending-merge` to `completed`, strip stale per-PR overrides from `.aperant/config.json`, clean up worktree per policy, and emit `task.closed.merged` events for the audit trail. This is the post-merge counterpart to `/apt:ship`.
@@ -54,6 +56,50 @@ Run `apt-tools task close-merged . --all --dry-run` first to see what would happ
 
 If `--task <id>` is passed, narrow to that task.
 
+## 1.5 Disposition follow-ups (autonomy-aware — G45)
+
+Run this BEFORE §2. The `task close` path that §2 invokes carries a CLI-level disposition gate (G45): it refuses to close while `{task_dir}/followups.json` has any open row, or any `dispositioned` row missing a valid `disposition.kind` + `ref`. Disposition every open row here so §2 closes cleanly without `--force`.
+
+For each candidate the dry-run says `close`, read the effective policy:
+
+```bash
+node packages/framework/bin/apt-tools.mjs followups policy . --task-id <id>
+```
+
+The envelope returns `{ after_close: 'ask' | 'file' | 'chain', max_chain_depth, source }`. `after_close` derives from `config.followups.after_close` when set, else from the task autonomy level (≤1 `ask` / 2 `file` / 3 `chain`). Then enumerate the open rows from `{task_dir}/followups.json` and route each by class + policy:
+
+**`ask` (autonomy ≤ 1).** Present each open row to the user with its `class_proposed`, `adjudication.verdict`, and `files`. Offer fix / file / drop:
+- fix → execute the change in this session (only if it is genuinely small + safe), commit, flip the row `status: 'fixed'`, optionally record `executed_commit`.
+- file → the `new-task` flow below.
+- drop → `apt-tools followups disposition . --task-id <id> --row <row-id> --kind dropped_by_user --ref <reason-slug> --reason "<text>"`.
+
+**`file` (autonomy 2).** Auto-file every `new-task` row through the EXISTING triage machine (report, do NOT execute):
+
+```bash
+# 1) create the task seeded from the row
+node packages/framework/bin/apt-tools.mjs task create . --description "<row title>" --scope <scope> [...linkage]
+# 2) enter it at needs-triage; the configured task_tracking.backend mirrors it
+#    (github-issues creates/updates a real labeled issue idempotently)
+node packages/framework/bin/apt-tools.mjs triage init . --id <new-task-id>
+# 3) record the disposition (ref = the filed task id; the triage mirror carries the issue URL)
+node packages/framework/bin/apt-tools.mjs followups disposition . --task-id <id> --row <row-id> --kind filed_task --ref <new-task-id>
+```
+
+There is **NO new `gh issue create` logic** — filing goes through `task create` + `triage init`, and the backend mirror does the GitHub work (ID-08). This works with the local-only default (no `task_tracking` key) AND with `github-issues` when configured; never hard-require gh.
+
+**`polish` rows** (any policy) → park in the committable Deferred Ideas section (ID-09): append `- {title} -- deferred because {reason}` under `## Deferred Ideas` in `context/notes/{task-id}.md` (create the section/file if absent), then `apt-tools followups disposition . --task-id <id> --row <row-id> --kind parked_note --ref .aperant/context/notes/{task-id}.md`. Polish rows must NOT linger in the ledger — the ledger is ephemeral.
+
+**`chain` (autonomy 3).** Do the `file` flow, THEN auto-chain depth-1 ONLY the filed tasks that triage to `ready-for-agent` (run the chained task through the full pipeline gates). Pass the depth marker on the chained task so the next-level policy degrades `chain → file`:
+
+```bash
+node packages/framework/bin/apt-tools.mjs triage init . --id <new-task-id> \
+  --extra '{"followups_chain": {"origin_task": "<id>", "depth": 1}}'
+```
+
+`ready-for-human` items stop there by design — they are filed + reported, never auto-executed. `max_chain_depth` is clamped to 1 in v1 (anti-perpetual-motion); `followups policy` already degrades `chain → file` when the current task's `triage.json` carries `extra.followups_chain.depth >= max_chain_depth`.
+
+After this step, every open row carries a durable disposition, so §2's `task close` clears the gate.
+
 ## 2. Confirm merge
 
 For each candidate the dry-run says `close`:
@@ -124,6 +170,8 @@ 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.
 
+**Follow-ups-gate recovery (G45).** The passive post-merge sweep (and any bare `task close-merged` that skips §1.5) inherits the CLI close gate: a merged task whose `followups.json` still has open/undispositioned rows fails its spawned `task close` and lands in `errors[]` with a `task-close-failed` reason — the task STAYS in `shipped-pending-merge`. This is the designed backstop, not a bug. Recover by running `/apt:close-task --task <id>` (which runs §1.5 first to disposition every open row), then the close clears the gate. As a last resort, `apt-tools task close . --id <id> --force --reason "<text>"` bypasses the gate with an audited `task.close.followups-override` event.
+
 **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

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

@@ -42,6 +42,7 @@ reproduction, so loading this appendix is non-trivial.
 - **apt-tools path:** `node packages/framework/bin/apt-tools.mjs` or the locally installed `apt-tools` binary
 - **Constitution:** Read `AGENTS.md` in the project root if it exists
 - **Debug sessions:** `.aperant/debug/{session-id}/DEBUG.md`
+- **Task-level worktree isolation:** A worktree is provisioned at session start by `task create` (track-agnostic — DEBUG gets one too; parsed + banner-announced in §1a) when `task_isolation.worktree_per_task` is enabled. Read-only investigation (Sections 2-3 Observe / Hypothesize — `git log`, `git diff`, Grep, Read) may run from EITHER cwd; they only read. But once code changes begin — Section 4 (Checkpoint), Section 5b (Execute Test — the minimal change), Section 6b (Implement Fix + commit) — run those Bash commands with `cd {worktree_path} &&` so the fix + checkpoint commits land on the worktree's task branch. Use the `worktree_path` the router passed in skill context or that §1a parsed from `task create`'s envelope. `apt-tools` calls always take the project root as `<project-dir>`. If no `worktree` block was returned, proceed in the project root as before.
 </your_environment>
 
 <state_files>
@@ -98,6 +99,15 @@ Sequence:
 
 The debug working dir at `.aperant/debug/{session-id}/` stays — that working artifact is preserved (per spec §3 R7). The canonical task record at `.aperant/tasks/{task-id}/` is created in parallel by `task create`, and both share the same id.
 
+**Worktree isolation (both paths).** `task create` provisions a worktree when `task_isolation.worktree_per_task` is enabled (track-agnostic — DEBUG gets one too). Parse `worktree.worktree_path`, `worktree.branch`, and `worktree.base_branch` from the `task create` envelope (direct path); on the router path the orchestrator already passed `worktree_path` into your skill context — use that. When a `worktree` block is present, print the banner:
+
+```
+[APT] Working in isolated worktree: {worktree_path}
+[APT] Task branch: {branch} (from {base_branch})
+```
+
+Investigation (Sections 2-3) may run from either cwd — but once you reach the fix-applying phases (Section 4 Checkpoint, Section 5b Execute Test, Section 6b Implement Fix), prefix those Bash commands with `cd {worktree_path} &&` so commits land on the task branch. If no `worktree` block is returned, proceed in the project root as before.
+
 ### 1b. Create debug working directory
 
 ```bash
@@ -202,11 +212,11 @@ Update DEBUG.md:
 
 ## 4. Checkpoint — Save State Before Changes
 
-Before making any code changes, create a git checkpoint:
+Before making any code changes, create a git checkpoint. From here on, code-change Bash commands run in the task worktree when one was provisioned — prefix them with `cd {worktree_path} &&` (omit the prefix if no `worktree` block was returned in §1a):
 
 ```bash
-git stash push -m "debug-checkpoint-{session-id}-pre-test" || true
-git rev-parse HEAD > .aperant/debug/{session-id}/checkpoints/pre-test.ref
+cd {worktree_path} && git stash push -m "debug-checkpoint-{session-id}-pre-test" || true
+cd {worktree_path} && git rev-parse HEAD > .aperant/debug/{session-id}/checkpoints/pre-test.ref
 ```
 
 Record the checkpoint in DEBUG.md:
@@ -215,9 +225,9 @@ Record the checkpoint in DEBUG.md:
 - {timestamp} — pre-test: {commit-sha} (before testing hypotheses)
 ```
 
-If a hypothesis test fails badly, revert to checkpoint:
+If a hypothesis test fails badly, revert to checkpoint (in the worktree):
 ```bash
-git checkout $(cat .aperant/debug/{session-id}/checkpoints/pre-test.ref) -- .
+cd {worktree_path} && git checkout $(cat .aperant/debug/{session-id}/checkpoints/pre-test.ref) -- .
 ```
 
 ## 5. Test — Validate Hypotheses
@@ -229,7 +239,7 @@ For each hypothesis (starting with most likely):
 - What is the expected outcome if the hypothesis is correct?
 
 ### 5b. Execute Test
-- Make the minimal change needed to test the hypothesis
+- Make the minimal change needed to test the hypothesis — apply it in the task worktree (edit files under `{worktree_path}` and run any verification command with `cd {worktree_path} &&`) when a `worktree` block was provisioned in §1a; otherwise edit in the project root.
 - Run the relevant command/test
 - Record the actual outcome
 
@@ -283,12 +293,12 @@ Document the root cause clearly:
 ```
 
 ### 6b. Implement Fix
-- Apply the minimal fix that addresses the root cause
+- Apply the minimal fix that addresses the root cause — in the task worktree (edit files under `{worktree_path}`) when one was provisioned in §1a, so the commit lands on the task branch.
 - Run verification (tests, typecheck, lint)
-- If verification passes, commit:
+- If verification passes, commit (prefix with `cd {worktree_path} &&` when a worktree was provisioned so `git` stages + commits on the worktree's task branch; `apt-tools commit` takes no `<project-dir>` and operates on the current cwd):
 
 ```bash
-node packages/framework/bin/apt-tools.mjs commit "fix: {concise description of fix}" --files {changed-files}
+cd {worktree_path} && node packages/framework/bin/apt-tools.mjs commit "fix: {concise description of fix}" --files {changed-files}
 ```
 
 ### 6c. Update Status