@aperant/framework 0.13.0 → 0.16.0

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:
 

package/skills/apt-merge-conflict-resolution/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: apt:merge-conflict-resolution
+description: "Agent-inline merge-conflict resolution — detect conflicts via apt-tools merge, resolve markers inline, re-probe, fall back to STOP"
+apt-skill-version: {{APT_VERSION}}
+stage: ship
+intent: x-merge-resolve
+when_to_use: "A clean fast-forward rebase or merge is impossible because the task branch conflicts with its base (apt:ship §0.7, a fan-out integration sweep, or an apt:watch-ci diverged-bailed branch) and you want the executing agent to resolve the conflicts inline before re-probing mergeability."
+user_invocable: true
+internal: false
+spawns_agent: false
+agent_name: null
+task_context: require-existing
+default_execution_mode: auto
+execution_modes:
+  - auto
+  - step
+allowed-tools: "Bash, Read, Write, Edit, Grep, Glob"
+argument-hint: "apt:merge-conflict-resolution [--base <ref>] [--head <ref>]"
+gates: []
+---
+
+# /apt:merge-conflict-resolution — Agent-Inline Merge Conflict Resolution
+
+<objective>
+You are the Aperant merge-conflict resolver. When a task branch can no longer
+fast-forward or rebase cleanly onto its base, you resolve the conflicting
+files **inline** — reading the conflict markers, deciding the correct merged
+content with full repository context, and writing it back — then re-probe
+mergeability and continue. You are the opt-in resolution path the three
+framework merge gates fall into instead of hard-STOPping: `apt:ship` §0.7
+(single-task base-drift), the fan-out integration sweep (inter-PR conflicts
+as each branch lands), and `apt:watch-ci`'s `diverged-bailed` branch
+(self-heal instead of bail).
+
+The decisive architectural rule: resolution is **agent-inline**, never a
+programmatic provider client. The framework CLI is self-contained ESM and
+declares no `@aperant/core` dependency, so there is no app credential store
+or LLM transport to call from `.mjs`. The agent driving the CLI is already
+an LLM with a transport — you read the markers `apt-tools merge` surfaces and
+resolve them with your own reasoning. Detection is deterministic (`git
+merge-tree`); resolution is yours.
+
+The human stays the final gate. A resolved merge still flows through PR →
+review → CI; you never push to a protected branch and never auto-merge.
+</objective>
+
+<your_environment>
+- **Working directory:** The task worktree (or project root) whose branch needs to integrate its base. All `apt-tools` and `git` calls run with this as the cwd / `<project-dir>` argument.
+- **apt-tools path:** `node packages/framework/bin/apt-tools.mjs` (or `node .aperant/deps/node_modules/@aperant/framework/bin/apt-tools.mjs` when running from an install mirror).
+- **Detection primitive:** `apt-tools merge detect <dir> [--base <ref>] [--head <ref>]` — a read-only trial-merge probe (`git merge-tree --write-tree`) that reuses the exact detection from `audit branch-current`. Emits `{ mergeable, conflicts_preview? }`. NO history rewrite, NO index mutation. `--base` defaults to `origin/main`; `--head` defaults to `HEAD`.
+- **Marker reader:** `apt-tools merge markers <dir>` — after a real `git merge`/`git rebase` leaves the worktree conflicted, lists the unmerged paths and reads each file's full content (markers and all) so you can resolve them inline. Emits `{ conflicted, files: [{ path, content }] }`.
+- **git:** You drive the actual `git merge` / `git rebase` / `git add` / `git rebase --continue` yourself — the CLI only observes, it never mutates. Requires git ≥ 2.38 for the `detect` probe.
+</your_environment>
+
+<state_files>
+## State Files
+
+**Reads:**
+- `.aperant/state.json` — `active_tasks[{task-id}].autonomy` (autonomy gating) and `autonomy.default` fallback.
+- The conflicted source files themselves, via `apt-tools merge markers` (full content with markers).
+
+**Writes:**
+- The resolved source files in the worktree (via Edit/Write — your inline resolution).
+- The git index + a merge/rebase-continuation commit, via `git add` + `git commit` / `git rebase --continue` (you drive git; the CLI never does).
+
+This skill writes NO `.aperant/` state of its own — it is a leaf resolution
+step invoked by `apt:ship`, `apt:fan-out`, or `apt:watch-ci`, each of which
+owns its own state. Detection (`apt-tools merge detect|markers`) is pure
+read-only.
+</state_files>
+
+<process>
+
+## 1. Probe mergeability
+
+Resolve the base and head refs (defaults: `--base origin/main`, `--head HEAD`).
+Fetch the base first so the probe is against the live remote tip:
+
+```bash
+git -C "$dir" fetch origin "$base_branch"
+node packages/framework/bin/apt-tools.mjs merge detect "$dir" --base "origin/$base_branch"
+```
+
+Branch on the envelope:
+
+- **`mergeable === true`** → nothing to resolve. Return to the caller (or run the clean rebase the caller requested). DONE.
+- **`mergeable === null`** (`audit_warning: "git-version-too-old"` or `"merge-tree-probe-failed"`) → STOP. You cannot safely probe. Emit the warning verbatim and hand back to the human:
+  ```
+  [APT:merge] Cannot resolve — mergeability is unprobeable ({audit_warning}). Upgrade git ≥ 2.38 or rebase manually, then re-run.
+  ```
+- **`mergeable === false`** → conflicts exist. Print `conflicts_preview` verbatim and proceed to §2.
+
+## 2. Materialize the conflict in the worktree
+
+The `detect` probe is read-only — it never touched your index. To resolve, you
+need the real conflicted state on disk. Drive git yourself (the SKILL owns
+history changes, the CLI never does):
+
+```bash
+git -C "$dir" rebase "origin/$base_branch"   # or: git -C "$dir" merge "origin/$base_branch"
+```
+
+Prefer `rebase` for single-task base-drift (apt:ship §0.7) and the fan-out
+integration sweep so the branch stays linear; prefer `merge` only when the
+caller explicitly asked for it. The command will exit non-zero and leave the
+worktree in a conflicted (rebasing/merging) state — that is expected.
+
+## 3. Read the markers + resolve inline
+
+```bash
+node packages/framework/bin/apt-tools.mjs merge markers "$dir"
+```
+
+For each entry in `files`, the `content` field carries the file verbatim with
+`<<<<<<<` / `=======` / `>>>>>>>` markers. For every conflicted file:
+
+1. **Understand both sides.** The `HEAD` side (above `=======`) is the current
+   branch's change; the other side (below `=======`, up to `>>>>>>>`) is the
+   base's change. Read the surrounding file and, when the conflict is
+   semantic, the related modules — you have full repository context the
+   deterministic merger does not.
+2. **Resolve with intent, not by picking a side.** Produce the content that
+   correctly carries BOTH intents where they are compatible (e.g. both sides
+   added an import → keep both; both edited the same function → reconcile the
+   two edits). Pick one side only when the changes are genuinely mutually
+   exclusive and you can justify which wins.
+3. **Remove every marker.** The resolved file MUST contain no `<<<<<<<`,
+   `=======`, or `>>>>>>>` line. Write it back with Edit/Write.
+4. **Stage it.** `git -C "$dir" add "<path>"`.
+
+Do this for every conflicted path before continuing.
+
+## 4. Continue the merge/rebase
+
+```bash
+git -C "$dir" rebase --continue   # or: git -C "$dir" commit --no-edit  (for a merge)
+```
+
+A rebase may surface a SECOND round of conflicts on the next replayed commit.
+If so, loop back to §3 (`apt-tools merge markers` again) and resolve the new
+round. Repeat until the rebase/merge completes.
+
+## 5. Re-probe + verify
+
+Confirm the branch is now clean against the base and the tree is whole:
+
+```bash
+node packages/framework/bin/apt-tools.mjs merge detect "$dir" --base "origin/$base_branch"
+grep -rEn '^(<<<<<<<|=======|>>>>>>>)' "$dir" --include='*.*' && echo "STRAY MARKERS — re-resolve" || true
+```
+
+- **`mergeable === true` AND no stray markers** → resolution succeeded. Hand
+  back to the caller, which proceeds to its push / PR / re-run-CI step. The
+  resolved branch still goes through PR → review → CI; you do NOT auto-merge.
+- **Still `mergeable === false`** → you missed a conflict. Loop back to §3.
+- **Loop budget exhausted** (you have re-entered §3 more than **3** times, or
+  the same files keep re-conflicting) → STOP. Abort the in-progress operation
+  to leave a clean tree, and hand back to the human:
+  ```bash
+  git -C "$dir" rebase --abort   # or: git -C "$dir" merge --abort
+  ```
+  ```
+  [APT:merge] Could not converge after 3 resolution rounds — handing back. Conflicts: {paths}. Resolve manually, then re-run.
+  ```
+
+## 6. Insertion points (where this skill is invoked from)
+
+This skill is the opt-in resolution path for three existing framework gates.
+Each gate decides — by autonomy level + config — whether to fall into this
+skill or keep its legacy hard-STOP. The references are doc-only here; the
+gates document the hand-off in their own SKILL.md:
+
+- **`apt:ship` §0.7** — the `mergeable === false` branch. Legacy behavior is a
+  hard STOP ("resolve manually"). With resolution opted in, the branch hands
+  to §2 of this skill instead, then resumes §1 of apt:ship on success.
+- **`apt:fan-out` integration sweep** — the new serialization phase between
+  spawn and report. As each worker's branch lands against the moving base,
+  re-probe via `apt-tools merge detect` and resolve inter-PR conflicts here
+  before the next branch integrates.
+- **`apt:watch-ci` `diverged-bailed`** — instead of bailing on a rebase
+  conflict, run this skill to self-heal, then push the resolved branch and let
+  the watcher reschedule.
+
+</process>
+
+<rationalization>
+Common ways an agent rationalizes the wrong move — and why each is wrong:
+
+- "I'll just `git checkout --theirs` / `--ours` to clear the conflict fast." →
+  That blindly discards one side's intent. The whole reason this is
+  agent-inline (not the deterministic core merger) is that you reconcile BOTH
+  intents with repository context. Side-picking is the last resort in §3.2,
+  not the default.
+- "The probe said `mergeable: false`, I'll resolve from the `conflicts_preview`
+  list without reading the files." → The preview is only a path list. You MUST
+  materialize the conflict (§2) and read the actual markers (§3) before
+  editing — guessing from filenames produces wrong merges.
+- "I resolved the markers, I can skip the re-probe and push." → Without §5 you
+  can ship stray markers or an incomplete rebase. Always re-probe + grep for
+  stray markers before handing back.
+- "It's still conflicting after a few tries, I'll force it through." → A
+  non-converging conflict is a human decision. After 3 rounds, abort to a clean
+  tree and hand back — never leave a half-rebased worktree or force a bad
+  resolution into a PR.
+- "I'll just merge the PR since I resolved it." → You are not the final gate.
+  Resolved branches flow through PR → review → CI. Never auto-merge.
+</rationalization>
+
+<autonomy_interaction>
+Read the active task's autonomy level from `.aperant/state.json`
+(`active_tasks[{task-id}].autonomy`, falling back to `autonomy.default`):
+
+- **Autonomy 0–1 (plan-only / step)** — after §1 detects conflicts, print the
+  `conflicts_preview` and ask `Resolve these N conflicts inline? [Y/n]` before
+  driving the rebase in §2. On `N`, exit so the human can resolve manually.
+  After resolving each file in §3, show the diff and confirm before staging at
+  higher-stakes files (anything under a path the task did not touch).
+- **Autonomy 2 (auto-chain)** — resolve silently through §2–§5; STOP per §5 on
+  non-convergence after 3 rounds.
+- **Autonomy 3 (YOLO)** — same as 2: silent on convergence, STOP on
+  non-convergence. Even at YOLO you do NOT auto-merge the resulting PR — the
+  human/CI gate is non-negotiable.
+
+This skill is recoverable by construction: every STOP path (§1 unprobeable,
+§5 non-convergence) aborts the in-progress git operation to leave a clean tree
+before handing back, so a bailout never strands a half-rebased worktree.
+</autonomy_interaction>

package/skills/apt-pr-review/SCHEMA.md

@@ -26,7 +26,7 @@ Every finding produced by a review agent MUST conform to this schema:
 {
   "id": "SEC-001",
   "severity": "critical|high|medium|low",
-  "category": "security|quality|logic|codebase-fit|test-integrity|performance|auto-checks",
+  "category": "security|quality|logic|codebase-fit|test-integrity|performance|i18n|cross-platform|auto-checks",
   "title": "Short description (max 80 chars)",
   "description": "Detailed explanation of the issue",
   "impact": "Real-world consequences if not fixed",
@@ -62,7 +62,7 @@ Every finding MUST include all of the following. A finding missing any required
 |-------|------|-------------|
 | `id` | `string` | Unique identifier. Format: `{CATEGORY_PREFIX}-{NNN}`. See [ID Prefixes](#id-prefixes) below. |
 | `severity` | `enum` | One of: `critical`, `high`, `medium`, `low`. See [Severity Definitions](#severity-definitions). |
-| `category` | `enum` | One of: `security`, `quality`, `logic`, `codebase-fit`, `test-integrity`, `performance`, `auto-checks`. |
+| `category` | `enum` | One of: `security`, `quality`, `logic`, `codebase-fit`, `test-integrity`, `performance`, `i18n`, `cross-platform`, `auto-checks`. The `i18n` and `cross-platform` categories are emitted only by the two CONDITIONAL specialists, which the orchestrator spawns when `detect-specialists` engages them. |
 | `title` | `string` | Short description, max 80 characters. Must be specific enough to act on without reading the full description. |
 | `description` | `string` | Detailed explanation of what the issue is and why it matters. No filler -- every sentence must add information. |
 | `impact` | `string` | Real-world consequences if this issue is not fixed. Must describe a concrete scenario, not a vague risk statement. |
@@ -100,6 +100,8 @@ Each category has a standard prefix for finding IDs:
 | `codebase-fit` | `FIT` | `FIT-001` |
 | `test-integrity` | `TST` | `TST-001` |
 | `performance` | `PRF` | `PRF-001` |
+| `i18n` | `I18N` | `I18N-001` |
+| `cross-platform` | `XPL` | `XPL-001` |
 | `auto-checks` | `CHK` | `CHK-001` |
 
 Each agent numbers its findings sequentially starting from 001.