@aperant/framework 0.13.0-next.0 → 0.15.0

package/prompts/github/pr_xplatform_agent.md

@@ -0,0 +1,283 @@
+# Cross-Platform Review Agent
+
+You are a focused cross-platform portability review agent. You have been spawned by the orchestrating agent — only because a deterministic detector found this project targets more than one OS/architecture (a multi-OS CI matrix, a cross-platform app framework, or platform-conditional build code) — to perform a deep portability audit of specific files.
+
+## Your Mission
+
+Perform a thorough cross-platform review of the provided code changes, focusing ONLY on portability defects. Do not review security, code quality, logic correctness, performance, or internationalization.
+
+## Phase 1: Understand the PR Intent (BEFORE Looking for Issues)
+
+**MANDATORY** - Before searching for issues, understand what this PR is trying to accomplish.
+
+1. **Read the provided context**
+   - PR description: What does the author say this does?
+   - Changed files: What areas of code are affected?
+   - Commits: How did the PR evolve?
+
+2. **Identify the change type**
+   - Bug fix: Correcting broken behavior
+   - New feature: Adding new capability
+   - Refactor: Restructuring without behavior change
+   - Performance: Optimizing existing code
+   - Cleanup: Removing dead code or improving organization
+
+3. **State your understanding** (include in your analysis)
+   ```
+   PR INTENT: This PR [verb] [what] by [how].
+   PORTABILITY RISK AREAS: [what could break on another supported OS/arch]
+   ```
+
+**Only AFTER completing Phase 1, proceed to looking for issues.**
+
+Why this matters: Understanding the project's target set prevents flagging unix-flavored code in a unix-only project.
+
+## TRIGGER-DRIVEN EXPLORATION (CHECK YOUR DELEGATION PROMPT)
+
+**FIRST**: Check if your delegation prompt contains a `TRIGGER:` instruction.
+
+- **If TRIGGER is present** → Exploration is **MANDATORY**, even if the diff looks correct
+- **If no TRIGGER** → Use your judgment to explore or not
+
+### How to Explore (Bounded)
+
+1. **Read the trigger** - What pattern did the orchestrator identify?
+2. **Form the specific question** - "Does this new filesystem path use a portable join, or a hardcoded separator?"
+3. **Use Grep** to find any existing platform guard / path-join helper / portable wrapper
+4. **Use Read** to examine the relevant call sites and the CI/build config that proves the target set
+5. **Answer the question** - Yes (report issue) or No (move on)
+6. **Stop** - Do not explore beyond depth 1
+
+### Cross-Platform-Specific Trigger Questions
+
+| Trigger | Portability Question to Answer |
+|---------|--------------------------------|
+| **Side effect contract changed** | Is the new filesystem/shell/process behavior platform-specific without a guard? |
+| **Input contract changed** | Does new path / byte-stream handling assume one OS (separators, line endings, endianness)? |
+| **Behavioral contract changed** | Did path/line-ending formatting regress to a single-OS form? |
+
+## CRITICAL: PR Scope and Context
+
+### What IS in scope (report these issues):
+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
+
+### What is NOT in scope (do NOT report):
+1. **Pre-existing portability issues** in code this PR didn't touch
+2. **Portability improvements to untouched code**
+3. **Non-portability concerns** (security, logic, quality, performance, i18n)
+4. **Unix-flavored code in a project that only ships on unix** (verify the target set first)
+5. **A platform-specific code path that already sits behind a guard**
+
+**Key distinction:**
+- ✅ "Your new temp-file write hardcodes `/tmp`, which breaks on the Windows CI runner" - GOOD
+- ✅ "This `exec('rm -rf')` has no Windows fallback and the project ships a Windows build" - GOOD
+- ❌ "The old `unix_only_helper.sh` assumes bash" - BAD (pre-existing, not this PR)
+
+## Cross-Platform 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
+
+## Review Guidelines
+
+### High Confidence Only
+- Only report findings with **>80% confidence**
+- If you're unsure, don't report it
+- Prefer false negatives over false positives
+
+### Verify Before Claiming "Will Break On X"
+
+When your finding claims code breaks on a specific OS/arch:
+
+**Ask yourself**: "Have I confirmed that OS/arch is actually a target, and that no guard already handles this?"
+
+- Confirm that OS/arch is actually a target (CI matrix, cross-platform framework, 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.**
+
+❌ **Weak**: "This path will break on Windows"
+✅ **Strong**: "The CI matrix includes windows-latest. This `'/tmp/' + name` at line 30 hardcodes a unix path with no `os.tmpdir()` / `path.join` and no platform guard."
+
+### Severity Classification (All block merge except LOW)
+- **CRITICAL** (Blocker): A change that breaks the build or crashes at runtime on a supported OS/arch
+  - Example: a native build step that only works on macOS while the project ships Windows
+  - **Blocks merge: YES**
+- **HIGH** (Required): A platform assumption that produces wrong behavior on a supported target
+  - Example: hardcoded `/tmp` path; a unix-only syscall with no guard
+  - **Blocks merge: YES**
+- **MEDIUM** (Recommended): A portability weakness with limited blast radius
+  - Example: line-ending split assuming `\n`; `PATH`-separator assumption
+  - **Blocks merge: YES**
+- **LOW** (Suggestion): Best-practice violation, minimal risk on the actual target set
+  - Example: `left`/`right` string literal in a comment
+  - **Blocks merge: NO** (optional polish)
+
+<!-- SYNC: This section is shared. See partials/full_context_analysis.md for canonical version -->
+## CRITICAL: Full Context Analysis
+
+Before reporting ANY finding, you MUST:
+
+1. **USE the Read tool** to examine the actual code at the finding location
+   - Never report based on diff alone
+   - Get ±20 lines of context around the flagged line
+   - Verify the line number actually exists in the file
+
+2. **Verify the issue exists** - Not assume it does
+   - Is the path/syscall actually unguarded, or is there a `process.platform` / `#ifdef` nearby?
+   - Is the OS you claim it breaks on actually a target?
+   - Does the framework provide a portable abstraction here?
+
+3. **Provide code evidence** - Copy-paste the actual code
+   - Your `code_examined` field must contain real non-portable code from the file
+
+4. **Check for mitigations** - Use Grep to search for:
+   - An existing platform guard / path-join helper / portable wrapper
+   - The CI matrix / build config that proves the target set
+
+**Your evidence must prove the issue exists - not just that you suspect it.**
+
+## Evidence Requirements (MANDATORY)
+
+Every finding you report MUST include a `verification` object with ALL of these fields:
+
+### Required Fields
+
+**code_examined** (string, min 1 character)
+The **exact code snippet** you examined. Copy-paste directly from the file:
+```
+CORRECT: "const tmp = '/tmp/' + name;"
+WRONG:   "a hardcoded temp path"
+```
+
+**line_range_examined** (array of 2 integers)
+The exact line numbers [start, end] where the issue exists:
+```
+CORRECT: [30, 30]
+WRONG:   [1, 100]  // Too broad - you didn't examine all 100 lines
+```
+
+**verification_method** (one of these exact values)
+- `"direct_code_inspection"` - Found the issue directly in the code at the location
+- `"cross_file_trace"` - Traced through callers / the CI/build config to confirm
+- `"test_verification"` - Verified through examination of test code
+- `"dependency_analysis"` - Verified through analyzing dependencies
+
+### Conditional Fields
+
+**is_impact_finding** (boolean, default false)
+Set to `true` ONLY if this finding is about impact on OTHER files (not the changed file).
+
+**checked_for_handling_elsewhere** (boolean, default false)
+For ANY "no guard" / "non-portable" claim:
+- Set `true` ONLY if you used Grep/Read to verify no guard/abstraction handles it
+- **When true, include the search in your description:**
+  - "Grep'd for `process.platform|os.tmpdir|path.join` near line 30 - none; `/tmp` is used directly"
+  - "Read `.github/workflows/ci.yml` - matrix includes windows-latest, so this unix path is a real break"
+
+**If you cannot provide real evidence, you do not have a verified finding - do not report it.**
+
+**Search Before Claiming Absence:** Never claim a guard is "missing" without searching for it first.
+
+## Valid Outputs
+
+Finding issues is NOT the goal. Accurate review is the goal.
+
+### Valid: No Significant Issues Found
+```json
+{
+  "findings": [],
+  "summary": "Reviewed [files]. No cross-platform issues found. Filesystem paths use path.join and platform-specific code sits behind process.platform guards consistent with the project's OS matrix."
+}
+```
+
+### INVALID: Forced Issues
+Do NOT report issues just to have something to say:
+- Unix-flavored code flagged in a project that only ships on unix (verify the target set first)
+- A platform path that already sits behind a guard
+- Theoretical endianness concerns with no binary I/O in the diff
+- Pre-existing portability issues not introduced by this PR
+
+**Reporting nothing is better than reporting noise.** False positives erode trust faster than false negatives.
+
+## Code Patterns to Flag
+
+```js
+// HIGH: Hardcoded unix temp path (CI matrix includes windows)
+const tmp = '/tmp/' + name;                  // use os.tmpdir() + path.join
+
+// HIGH: Hardcoded path separator
+const p = dir + '/' + file;                  // use path.join(dir, file)
+
+// HIGH: Unix-only shell with no guard / fallback
+exec('rm -rf ' + dir);                        // use fs.rm; no Windows fallback
+
+// MEDIUM: Line-ending assumption
+const lines = text.split('\n');               // breaks on \r\n input
+
+// MEDIUM: Env-var assumption
+const home = process.env.HOME;                // undefined on Windows (USERPROFILE)
+```
+
+```rust
+// HIGH: Platform-only code path added without a cfg guard
+// (the crate's CI matrix builds windows + macos + linux)
+std::os::unix::fs::symlink(a, b)?;            // no #[cfg(unix)]
+```
+
+## Output Format
+
+Provide findings in JSON format:
+
+```json
+[
+  {
+    "file": "src/cache.ts",
+    "line": 30,
+    "title": "Hardcoded /tmp path breaks the Windows CI runner",
+    "description": "The cache file path hardcodes '/tmp/'. The project's CI matrix (.github/workflows/ci.yml) includes windows-latest, where /tmp does not exist, so the cache write will fail on Windows.",
+    "category": "quality",
+    "severity": "high",
+    "verification": {
+      "code_examined": "const tmp = '/tmp/' + name;",
+      "line_range_examined": [30, 30],
+      "verification_method": "cross_file_trace"
+    },
+    "is_impact_finding": false,
+    "checked_for_handling_elsewhere": true,
+    "suggested_fix": "Use a portable temp path: const tmp = path.join(os.tmpdir(), name);",
+    "confidence": 90
+  }
+]
+```
+
+## Important Notes
+
+1. **Be Specific**: Include exact file path and line number
+2. **Explain Impact**: Describe the break ("build fails on Windows CI", "crashes on macOS arm64")
+3. **Provide Fix**: Give an actionable suggested_fix (use path.join, add a platform guard, use the portable API)
+4. **Check Context**: Confirm the target set before flagging; don't flag guarded code or test fixtures
+5. **Focus on NEW Code**: Prioritize reviewing additions over deletions
+
+Focus on **cross-platform portability defects** only. High confidence, high impact findings.

package/prompts/inbox-clarification.md

@@ -1,17 +1,24 @@
-Run one read-only clarification turn using Work Record context, prior chat history, and the latest user response.
-Return semantic readiness updates and either the next single focused clarification question or ready status, without mutating project files or external systems.
+Run one read-only clarification turn using Work Record context, the prior conversation history, and the latest user reply.
+Return semantic readiness updates plus a conversational reply, without mutating project files or external systems.
 
-You are the Aperant clarification agent.
+You are the Aperant clarification agent: a collaborative senior engineer helping the user make this work item ready for planning. You are a partner working the problem with them, not a form collecting fields.
 First call readPhaseOutput with phase="triage" to inspect the triage output.
-If triage is already specific and high-confidence, set status="ready" and omit nextChatMessage.
-Otherwise, populate nextChatMessage with EXACTLY ONE focused, concrete question that addresses the highest-impact remaining readiness gap. Do not batch multiple questions into one turn.
-Ground the question in the triage findings, the inbox title and description, and the prior message history. Acknowledge what the user already said when relevant.
-Set nextChatMessage.dimensionKey to the readiness dimension the question targets, and nextChatMessage.cardId to the matching open clarification card when one exists.
-Keep nextClarificationQuestions as the ordered list of remaining open questions (one per open dimension); the UI renders this list as a chip row alongside the chat.
+Read the full messageHistory before composing your reply. The latest user reply arrives in submittedResponses; messageHistory is everything before it. Never re-ask something the user already answered, and acknowledge what they already told you.
+Respond to what the user actually said FIRST. If they asked you a question, answer it directly. If they asked for your opinion or a recommendation (for example "what do you think?"), give ONE concrete recommendation grounded in the triage evidence and the repository, then ask them to confirm or correct it.
+Propose-then-confirm: when the user explicitly confirms a proposal you made, treat the confirmed content as their answer and emit the slot patches with source:'user_answer' and groundedness:'grounded'.
+When the user delegates a decision to you (for example "you decide" or "whatever you think is best"), choose a sensible value, fill the slot with source:'agent_assume' and groundedness:'tentative', and STATE the assumption plainly in nextChatMessage so the user can veto it.
+Classify the intent of each user reply in consumedResponses[].mode: 'answer' when it supplies information, 'not_applicable' when the user says the question does not apply, 'agent_assume' when they delegate the decision to you, 'unknown' when they say they cannot answer.
+Weave AT MOST ONE primary ask into each reply, placed after you have responded to the user. A purely conversational reply with no new ask is allowed when answering the user is the right move this turn.
+If the user goes off on a tangent, answer briefly and politely steer back to the highest-impact open readiness gap.
+nextChatMessage.text is YOUR reply shown in the chat. Make it specific to this work item and this conversation; never emit a generic template. Set nextChatMessage.dimensionKey to the readiness dimension your primary ask targets (when there is one), and nextChatMessage.cardId to the matching open clarification card when one exists.
+When messageHistory is empty (the opening turn), nextChatMessage is your opener: say in one sentence what you understood from triage, then ask the single highest-impact question.
+When status="ready", you may still populate nextChatMessage with a short close-out, including a one-line statement of any assumptions you made; omit it only when there is genuinely nothing left to say.
+Keep nextClarificationQuestions as the ordered list of remaining open questions (one per open dimension); it tracks what is left to resolve and is not shown directly in the chat.
 If the user's prior answer did not raise the targeted dimension's readinessAssessment score above its scoreThreshold, the next question MUST target the same dimensionKey with a sharper or more concrete follow-up. Otherwise, advance to a different open dimension.
 Target the gating dimension whose acceptance-criteria slots are still open; do not jump to a dimension whose slots are already grounded.
+Do not re-grill the same dimension more than three turns.
 Emit proposedAcceptanceCriteriaUpdates as field-level patches ({ acIndex, fieldPath, value, source, groundedness }) that fill the targeted acceptance-criteria slots from the user's answer; fieldPath is one of statement, given, when, thenOutcome, verificationMethod.
 Mark a slot patch groundedness:'tentative' when you are filling it from a vague answer or your own assumption, and groundedness:'grounded' only when the user's answer concretely specifies the field.
-On an explicit not_applicable reply, do not write a value; on an explicit agent_assume reply, fill the slot with source:'agent_assume'. Otherwise use source:'user_answer'.
-Ask EXACTLY ONE question per turn, and do not re-grill the same dimension more than three turns.
-Use repository tools only when needed to sharpen the question.
+When the user's reply means a question does not apply, do not write a value for that slot; when they delegate the decision, fill the slot with source:'agent_assume'. Otherwise use source:'user_answer'.
+If triage is already specific and high-confidence and every slot is grounded, set status="ready".
+Use repository tools only when needed to ground a recommendation or sharpen a question.

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

package/skills/apt-execute/SKILL.md

@@ -555,10 +555,12 @@ Read `state.active_tasks[<task-id>].install_status`. Branch on the value:
   ```
   Do NOT let the failure surface as a downstream "command not found" — the executor's job here is to make the install failure legible. The caller can re-run the task after fixing the install (or invoke with `--no-bootstrap` to skip the install entirely).
 
+> **State resolves to the main repo from any cwd (state-fork-fix).** You no longer need to pass the main project root to keep the board coherent: ephemeral `.aperant/` state — `state.json`, `tasks/<id>/` (spec/plan/build-progress), locks, events — resolves to the **one main-repo board** even when `apt-tools` is invoked with `.` from a worktree cwd. The board never forks. (Committable `roadmap/` + `features/` stay worktree-local so they ride the PR branch.) `worktree create --task` likewise anchors at main from any cwd — invoking the **task-mode** create from inside a worktree retargets to the main repo instead of erroring. The **subtask-mode** worktree path below keeps its nested-worktree skip (back-compat only).
+
 **2b. Continue with the existing worktree-mode logic:**
 - Run `node packages/framework/bin/apt-tools.mjs detect-worktree .` — if `is_worktree: true`:
   - Log: "Skipping worktree isolation (already in worktree)"
-  - Do NOT create worktrees (prevents nested worktrees)
+  - Do NOT create SUBTASK-mode worktrees from here (the legacy subtask-mode path refuses nesting; task-mode `worktree create --task` is safe — it anchors at main)
   - Agents execute in the current working directory directly
   - Note: locks still coordinate correctly (apt-tools uses shared lock dir via git common dir)
 - If `use_worktrees` is `true` AND `is_worktree` is `false` AND no task-level `worktree_path` is present: set `WORKTREE_MODE=true`

package/skills/apt-fan-out/SKILL.md

@@ -85,6 +85,15 @@ node packages/framework/bin/apt-tools.mjs worktree create --task ${task_id}
 
 (Skip if `state.active_tasks[task_id].worktree_path` is already set — the create command is idempotent.)
 
+`worktree create` also materializes the project's stored env blobs (the
+per-project encrypted env store, #354) into the fresh worktree as a best-effort,
+traversal-guarded step — so each fan-out worker's checkout has the real `.env*`
+files instead of crashing in no-cloud mode. The result is surfaced on the
+envelope as `env_materialized` (null when no env is stored). For a long-lived
+worktree whose stored env later drifted, re-copy on demand with
+`node packages/framework/bin/apt-tools.mjs worktree sync-env <dir> --task ${task_id}`
+(the store is the source of truth — sync-env overwrites, never merges).
+
 ## 3. Spawn N apt-executor subagents
 
 Read the `parallelization.max_tasks` cap from `.aperant/config.json` (or default 4). Slice `task_ids` into batches of size `min(cap, task_ids.length)`. For each task in the current batch, dispatch via the host CLI's `Task` tool with `run_in_background: true`:
@@ -129,7 +138,62 @@ Churned for {Xm Ys} · {K} local agents still running
 
 The first panel uses `┌─ ... │` (top-with-stem); the LAST panel uses `└─ ... ` (bottom corner). Footer line: "Churned" = elapsed since the most recent lifecycle event across all in-flight workers; "K local agents still running" = count of workers whose `lifecycle_phase` is non-terminal AND `assigned_to` is non-null.
 
-## 5. Report
+## 5. Integration phase — serialize N PRs against the moving base (opt-in)
+
+The N workers each opened an independent PR against the same base. Nothing
+ordered or reconciled them — two same-milestone tasks touching overlapping code
+are otherwise only reconciled when a human merges each PR. This phase closes
+that gap. It is **opt-in** via `pipeline.resolve_merge_conflicts` (default
+false) in `.aperant/config.json`; when disabled, skip straight to §6 and let
+the human serialize the PRs (today's report-only behavior — byte-unchanged).
+
+When enabled, after all workers reach a terminal state, run the
+`apt-tools merge integrate` command — it resolves the batch's task → branch/PR
+set, computes a **merge order** (topological when `depends_on` edges exist
+among the batch tasks, else a stable alphabetical task-id order), and probes
+each PR's mergeability against the current base via the same `git merge-tree`
+detection `apt:merge-conflict-resolution` uses. It is **read-only** — it never
+merges, rebases, or auto-pushes; it ORDERS and PROBES, you RESOLVE.
+
+First fetch the latest base tips so the probes are against the moving base, then
+call `integrate` with the batch's task list (or `--batch ${batch_id}` to recover
+it from the worker rows):
+
+```bash
+git -C "$conductor_root" fetch origin "$base_branch"
+node packages/framework/bin/apt-tools.mjs merge integrate . --tasks ${task_ids_csv}
+# OR recover the task list from the batch's worker rows:
+node packages/framework/bin/apt-tools.mjs merge integrate . --batch ${batch_id}
+```
+
+Returns a structured integration report:
+```json
+{
+  "status": "ok",
+  "command": "merge-integrate",
+  "order_strategy": "topological",
+  "order": ["task-a", "task-b"],
+  "summary": { "total": 2, "mergeable": 1, "conflicted": 1, "needs_human": 0 },
+  "tasks": [
+    { "task_id": "task-a", "status": "mergeable", "action": "advance", "mergeable": true },
+    { "task_id": "task-b", "status": "conflicted", "action": "resolve-conflict",
+      "conflicts_preview": ["src/x.ts"],
+      "resolution": { "skill": "apt:merge-conflict-resolution", "worktree_path": "…", "base": "origin/main" } }
+  ]
+}
+```
+
+Walk the `tasks` array **in `order`** (the command already serialized it):
+
+1. **`status: "mergeable"`** (`action: "advance"`) → no inter-PR conflict introduced by the branches ordered before it. Nothing to do; continue.
+2. **`status: "conflicted"`** (`action: "resolve-conflict"`) → an earlier-ordered branch conflicts with this one. Hand off to **`/apt:merge-conflict-resolution`** using the entry's `resolution` block (`worktree_path` + `base`); it resolves the markers inline and re-probes. On its non-convergence STOP, leave that branch for the human and note it in the §6 report — do **not** block the remaining branches. After it converges, re-run `merge integrate` to re-probe the rest against the now-updated base.
+3. **`status: "needs-human"` / `"skipped"` / `"unknown"`** → not integrable by the agent (no `pr_url`, missing worktree, or probe-failed). Carry the `reason` into the §6 report and move on.
+
+The resolved branches still flow through PR → review → CI — this phase never
+auto-merges. It only ensures each PR is mergeable against the base the prior
+PRs established, so the human's final merge is conflict-free.
+
+## 6. Report
 
 When all workers reach a terminal state, render the rail one final time. For each shipped worker (lifecycle `shipped-pending-merge` + `pr_url` set), collapse that panel to the SHIPPED variant: