@aperant/framework 0.13.0-next.0 → 0.15.0

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.

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

@@ -1,10 +1,10 @@
 ---
 name: apt:pr-review
-description: "Multi-agent PR review — 6 parallel specialists, validator, fixer, self-reviewer"
+description: "Multi-agent PR review — 6-8 parallel specialists (i18n + cross-platform engage conditionally), validator, fixer, self-reviewer"
 apt-skill-version: {{APT_VERSION}}
 stage: review
 intent: ship
-when_to_use: "Use when the user asks to review a GitHub PR — by number, URL, 'the PR', 'my PR', 'Adam's PR', 'deep-verify this PR'. Spawns 6 parallel specialist agents + validator + fixer + self-reviewer in an isolated worktree. Handles owned (in-session fix loop, auto-push) and external (single-round comment-only) authorship modes, detected automatically."
+when_to_use: "Use when the user asks to review a GitHub PR — by number, URL, 'the PR', 'my PR', 'Adam's PR', 'deep-verify this PR'. Spawns 6-8 parallel specialist agents (6 core + i18n + cross-platform conditionally) + validator + fixer + self-reviewer in an isolated worktree. Handles owned (in-session fix loop, auto-push) and external (single-round comment-only) authorship modes, detected automatically."
 user_invocable: true
 internal: false
 spawns_agent: false
@@ -21,7 +21,7 @@ gates: []
 
 # /apt:pr-review -- Multi-Agent PR Review System
 
-You are a **senior staff engineer and orchestrator** performing a thorough code review using a team of specialized agents. Your job is to coordinate 6 parallel review agents, validate their findings, synthesize results, and optionally auto-fix issues before the code ships.
+You are a **senior staff engineer and orchestrator** performing a thorough code review using a team of specialized agents. Your job is to coordinate 6-8 parallel review agents (the 6 core specialists, plus the i18n and cross-platform specialists when `detect-specialists` engages them), validate their findings, synthesize results, and optionally auto-fix issues before the code ships.
 
 **You orchestrate agents using Claude Code's `Agent` tool.** Review agents write detailed findings to files. Fix agents read those files directly and verify their own work. A self-review agent reviews and fixes autonomously. **Your context stays minimal throughout.**
 
@@ -37,7 +37,7 @@ YOU (Orchestrator) -- LIGHTWEIGHT COORDINATOR ONLY
   Phase 0: Set up isolated worktree (for PR/branch reviews)
   Phase 1: Gather diff, create review directory, detect triggers + toolchain
   Phase 2: Spawn 1 agent for auto-checks (runs in worktree)
-  Phase 3: Spawn 6 review agents (parallel, read files from worktree)
+  Phase 3: Spawn 6-8 review agents (6 core + up to 2 conditional, parallel, read files from worktree)
   Phase 4: Spawn 1 validator agent (reads from worktree)
   Phase 5: Read validated findings, synthesize, write review.json
   Phase 6: Spawn fix agents (edit files in worktree, up to 4 iterations)
@@ -50,14 +50,20 @@ YOU (Orchestrator) -- LIGHTWEIGHT COORDINATOR ONLY
 PHASE 2 -- AUTO-CHECKS (1 agent):
   auto-checks       -> Run lint, typecheck, tests using detected toolchain
 
-PHASE 3 -- PARALLEL REVIEW (6 agents, independent, all spawned in ONE message):
-  security           -> OWASP, injection, auth bypass, secrets
-  quality            -> Error handling, duplication, complexity, naming
-  logic              -> Off-by-one, null handling, edge cases, race conditions
-  codebase-fit       -> Naming conventions, import patterns, architecture
-  test-integrity     -> Deleted tests, weakened assertions, coverage gaps
-  performance        -> N+1 queries, re-renders, memory leaks, bundle size
-
+PHASE 3 -- PARALLEL REVIEW (6-8 agents, 6 core + up to 2 conditional, independent, all spawned in ONE message):
+  security           -> OWASP, injection, auth bypass, secrets         [core]
+  quality            -> Error handling, duplication, complexity, naming [core]
+  logic              -> Off-by-one, null handling, edge cases, races    [core]
+  codebase-fit       -> Naming conventions, import patterns, arch       [core]
+  test-integrity     -> Deleted tests, weakened assertions, coverage    [core]
+  performance        -> N+1 queries, re-renders, memory leaks, bundle   [core]
+  i18n               -> Hardcoded strings, missing locale keys,         [conditional —
+                        locale-unsafe formatting, RTL/encoding           engages per
+  cross-platform     -> Path/line-ending/case-sensitivity, platform     detect-specialists]
+                        APIs, arch/endianness, shell/native portability
+
+  ** The 6 core ALWAYS run. i18n + cross-platform are appended ONLY when **
+  ** `detect-specialists` engages them (or config forces `always`).      **
   ** Each has Read/Grep/Glob tools for evidence verification **
   ** Each writes DETAILED findings to .aperant/pr-reviews/{review-id}/findings/{name}.md **
   ** Each returns ONLY a brief 3-5 line summary to orchestrator **
@@ -171,13 +177,13 @@ If `downgrades` contains an entry for `review_mode`, display the warning:
 [APT] Warning: review_mode requested '{requested}' but host does not support it — using '{resolved}'. {reason}
 ```
 
-Store `resolved.review_mode` as `REVIEW_MODE`. This determines how the 6 specialist agents in Phase 3 are launched:
+Store `resolved.review_mode` as `REVIEW_MODE`. This determines how the 6-8 specialist agents in Phase 3 are launched (the 6 core plus any conditional specialist engaged in Step 4b):
 
-- **`agent-team`**: Use TeamCreate to spawn all 6 reviewers as a coordinated team
-- **`sub-agents`**: Spawn all 6 agents in a single message using the Agent tool (current default behavior)
-- **`sequential`**: Run each of the 6 review perspectives inline, one at a time — the orchestrator adopts each specialist role in sequence, writing findings to the same finding files
+- **`agent-team`**: Use TeamCreate to spawn all selected reviewers (6-8) as a coordinated team
+- **`sub-agents`**: Spawn all selected agents (6-8) in a single message using the Agent tool (current default behavior)
+- **`sequential`**: Run each selected review perspective (6-8) inline, one at a time — the orchestrator adopts each specialist role in sequence, writing findings to the same finding files
 
-**Runtime fallback (FRAMEWORK-BUG-003):** if `REVIEW_MODE` resolves to `sub-agents` or `agent-team` BUT the orchestrator runtime doesn't actually expose the `Agent` / `Task` / `TeamCreate` tool (e.g. some host-LLM environments don't propagate `Agent` to nested sub-agents — observed on PR #68 + PR #69 pr-reviews where a general-purpose orchestrator was spawned and lost Agent-tool access), **degrade to `sequential` automatically** and continue. Record the downgrade in `metadata.json` as `review_mode_resolved: 'sequential'` with `review_mode_requested: '<original>'` and `review_mode_downgrade_reason: 'Agent tool not exposed in this runtime'`. Findings rigor is identical — same 6 perspectives, same evidence rule, same audit gate. Only the spawn shape changes.
+**Runtime fallback (FRAMEWORK-BUG-003):** if `REVIEW_MODE` resolves to `sub-agents` or `agent-team` BUT the orchestrator runtime doesn't actually expose the `Agent` / `Task` / `TeamCreate` tool (e.g. some host-LLM environments don't propagate `Agent` to nested sub-agents — observed on PR #68 + PR #69 pr-reviews where a general-purpose orchestrator was spawned and lost Agent-tool access), **degrade to `sequential` automatically** and continue. Record the downgrade in `metadata.json` as `review_mode_resolved: 'sequential'` with `review_mode_requested: '<original>'` and `review_mode_downgrade_reason: 'Agent tool not exposed in this runtime'`. Findings rigor is identical — same selected perspectives, same evidence rule, same audit gate. Only the spawn shape changes.
 
 ### Create Workflow Gate
 
@@ -455,6 +461,57 @@ CHANGED_FILES=$(git diff main...HEAD --name-only)
 
 If the diff is empty, report "No changes to review" and exit.
 
+### Step 4b: Detect Conditional Specialists
+
+Decide whether the two CONDITIONAL Phase-3 specialists (i18n + cross-platform)
+engage for this project. **The orchestrator does NOT read the diff itself to
+decide** — it calls the deterministic detector and obeys the JSON (spec ID-01).
+
+```bash
+# Runs over the worktree (repo baseline) ∪ the PR diff. v1 passes NO --scope
+# flag → defaults to `repo` (spec ID-02a). The --diff is the diff.patch you
+# just wrote.
+SPECIALISTS_JSON=$(node packages/framework/bin/apt-tools.mjs pr-review detect-specialists \
+  ${WORKTREE_PATH:-.} --diff .aperant/pr-reviews/${REVIEW_ID}/diff.patch)
+```
+
+The detector returns:
+
+```json
+{
+  "i18n":      { "engage": true,  "signals": [{ "kind": "...", "detail": "...", "tier": "strong|weak" }], "reason": "strong: locale-file src/locales/fr.json" },
+  "xplatform": { "engage": false, "signals": [], "reason": "no signals" }
+}
+```
+
+Engagement precedence (the detector encodes it; you just read the result):
+config `pr_review.specialists.{i18n,xplatform}` ∈ `auto|always|never` (default
+`auto`) is checked FIRST and is absolute — `always` engages with no scan,
+`never` skips with no scan (even when the diff introduces the first locale
+file). Otherwise `auto` defers to the STRONG/WEAK tier scan.
+
+**Write the result into `metadata.json` under `conditional_specialists`** (ID-05)
+so the decision is auditable, and **emit one visible ENGAGED/SKIPPED line per
+conditional specialist** in your orchestrator output. A config-`never` skip MUST
+be distinguishable from a no-signal skip (the `reason` names the override
+verbatim, e.g. `config override: never`):
+
+```jsonc
+// metadata.json (additive key)
+"conditional_specialists": {
+  "i18n":      { "engaged": true,  "reason": "strong: locale-file src/locales/fr.json" },
+  "xplatform": { "engaged": false, "reason": "no signals" }
+}
+```
+
+```
+i18n: ENGAGED (strong: locale-file src/locales/fr.json)
+xplatform: SKIPPED (no platform signals; config: auto)
+```
+
+Store `result.i18n.engage` and `result.xplatform.engage` as `ENGAGE_I18N` /
+`ENGAGE_XPLATFORM` for Phase 3.
+
 **R3: pin the reviewed head SHA (PR reviews only).** After `gh pr diff` fetches into `pr-review-${REVIEW_ID}`, capture the SHA and pass it to `pr-review start-round`. All subsequent evidence reads within this round should reference this pinned SHA, not a fresh `gh pr view` call — otherwise a mid-round force-push invalidates cited line numbers.
 
 ```bash
@@ -782,7 +839,7 @@ DO NOT return full error output in your response -- write it to the file.
 node packages/framework/bin/apt-tools.mjs workflow advance . --id ${REVIEW_ID} --phase specialist-review
 ```
 
-**CRITICAL: Spawn all 6 review agents in ONE message using 6 parallel Agent tool calls.**
+**CRITICAL: Spawn all SELECTED review agents (6-8) in ONE message using parallel Agent tool calls.** The 6 core specialists ALWAYS spawn. Additionally append the **i18n** agent when `ENGAGE_I18N` is true and the **cross-platform** agent when `ENGAGE_XPLATFORM` is true (from Step 4b). So the set is 6, 7, or 8 agents — all in the SAME message.
 
 Each agent receives:
 1. The changed file list
@@ -795,7 +852,7 @@ Each agent receives:
 
 ### Agent Spawning Pattern
 
-In a SINGLE message, make 6 Agent tool calls:
+In a SINGLE message, make 6-8 Agent tool calls (the 6 core below, plus each engaged conditional specialist):
 
 ```
 Agent(
@@ -841,9 +898,29 @@ Agent(
 )
 ```
 
+**Conditional specialists — include each ONLY when Step 4b engaged it:**
+
+```
+# Append ONLY if ENGAGE_I18N is true:
+Agent(
+  name: "i18n-reviewer",
+  subagent_type: "apt-pr-review-i18n",
+  description: "Internationalization review of PR changes",
+  prompt: "{CONSTRUCTED_PROMPT_WITH_FILLED_PLACEHOLDERS}",
+)
+
+# Append ONLY if ENGAGE_XPLATFORM is true:
+Agent(
+  name: "xplatform-reviewer",
+  subagent_type: "apt-pr-review-xplatform",
+  description: "Cross-platform review of PR changes",
+  prompt: "{CONSTRUCTED_PROMPT_WITH_FILLED_PLACEHOLDERS}",
+)
+```
+
 ### Constructing Agent Prompts
 
-For each of the 6 specialist agents, read the agent definition from `.claude/agents/apt-pr-review-{name}.md` and fill in these placeholders:
+For each SELECTED specialist agent (the 6 core + any engaged conditional), read the agent definition from `.claude/agents/apt-pr-review-{name}.md` and fill in these placeholders:
 
 | Placeholder | Value |
 |-------------|-------|
@@ -854,7 +931,7 @@ For each of the 6 specialist agents, read the agent definition from `.claude/age
 | `[WORKTREE_PATH]` | The worktree path from Phase 0 (or `.` for HEAD vs main / staged reviews) |
 | `[LOCKED_DECISIONS]` | **(R6)** ≤500-token digest from `.aperant/context/notes/{task-id}.md` if a task-id can be derived from the PR/branch. Empty string if no ledger found. |
 
-**R6 — Decision ledger inject (required):** Before spawning the 6 specialist agents, look for `.aperant/context/notes/{task-id}.md` (where task-id is parseable from the PR branch name or the latest task directory). If found, read the file and extract a ≤500-token digest of locked decisions. Pass it into every specialist prompt as `[LOCKED_DECISIONS]` so reviewers don't flag decisions the team already settled. If no ledger exists, pass an empty string and skip the block.
+**R6 — Decision ledger inject (required):** Before spawning the specialist agents, look for `.aperant/context/notes/{task-id}.md` (where task-id is parseable from the PR branch name or the latest task directory). If found, read the file and extract a ≤500-token digest of locked decisions. Pass it into every specialist prompt as `[LOCKED_DECISIONS]` so reviewers don't flag decisions the team already settled. If no ledger exists, pass an empty string and skip the block.
 
 Append to each agent prompt:
 
@@ -898,7 +975,7 @@ If the diff exceeds approximately 3000 lines:
 
 ### Waiting for Completion
 
-Wait for all 6 agents to complete. Each returns a brief 3-5 line summary:
+Wait for all selected agents (6-8) to complete. Each returns a brief 3-5 line summary:
 - Finding count
 - Severity breakdown
 - Most critical issue (if any)
@@ -949,7 +1026,8 @@ Review ID: {REVIEW_ID}
 Review Directory: {REVIEW_DIR}
 
 Read all finding files from {REVIEW_DIR}/findings/ (excluding validated.md if it exists).
-The finding files are: security.md, quality.md, logic.md, codebase-fit.md, test-integrity.md, performance.md
+The core finding files are: security.md, quality.md, logic.md, codebase-fit.md, test-integrity.md, performance.md.
+Additionally read i18n.md and/or xplatform.md when present (the conditional specialists write them only when engaged).
 
 For each finding in each file, run the hypothesis-validation process from your instructions.
 
@@ -1031,13 +1109,19 @@ Score each dimension 1-10 based on validated findings:
 | Dimension | What lowers the score |
 |-----------|----------------------|
 | Security | Security findings (critical = -4, high = -2, medium = -1) |
-| Quality | Quality findings (same scale) |
+| Quality | Quality findings **and `i18n` findings** (same scale) |
 | Logic | Logic findings (same scale) |
-| Architecture | Codebase-fit findings (same scale) |
+| Architecture | Codebase-fit findings **and `cross-platform` findings** (same scale) |
 | Performance | Performance findings (same scale) |
 
 Start at 10 for each dimension. Subtract based on finding severity. Floor at 1.
 
+> The two conditional categories fold into existing dimensions (lower-churn,
+> per spec ID-04 — no new `scores` key in `review.json`): `i18n` findings
+> reduce **Quality**, `cross-platform` findings reduce **Architecture**
+> (compatibility is an architecture concern). They only contribute when the
+> orchestrator spawned that conditional specialist.
+
 ### Step 6: Determine Assessment
 
 | Assessment | Condition |
@@ -1223,7 +1307,7 @@ A specialist agent MAY emit a new finding in verification phase if ALL three hol
 
 The agent marks the finding with `regression_from_fix: true` and `regression_from_fix_round: {PRIOR_ROUND}`. The validator (Phase 4) honors this field and does NOT dismiss the finding as "out-of-scope for verification phase." Medium/low regressions are silently skipped — they'll be caught by the author or by a future cycle.
 
-Each of the 6 Phase 3 specialist agent definitions carries a `## Regression Detection (verification rounds only)` block with this carve-out written out.
+Each Phase 3 specialist agent definition (the 6 core + the 2 conditional) carries a `## Regression Detection (verification rounds only)` block with this carve-out written out.
 
 ### Iteration Loop (owned mode — max 4 iterations, discovery/verification split)
 
@@ -1389,7 +1473,7 @@ git diff > .aperant/pr-reviews/${REVIEW_ID}/iterations/${ITERATION}/diff.patch
 If fixes were applied:
 
 1. Capture the new diff (post-fix changes vs the original base)
-2. Spawn fresh review agents (same 6 specialists) on the NEW code state
+2. Spawn fresh review agents (the same selected specialists — 6 core + any conditional engaged in Step 4b) on the NEW code state
 3. Each fresh agent writes to `.aperant/pr-reviews/${REVIEW_ID}/iterations/${ITERATION}/findings/`
 4. Spawn a fresh validator on the new findings
 5. Read validated results
@@ -1774,7 +1858,7 @@ Fix agents self-report their outcome via a status line (`FIXED: X | FAILED: Y |
 ### Mistake 2: Spawning the Phase 3 REVIEW Agents Sequentially
 
 **Wrong:** Spawn security agent, wait, spawn quality agent, wait, etc.
-**Right:** Spawn all 6 review agents in ONE message using 6 parallel Agent tool calls. They run concurrently.
+**Right:** Spawn all selected review agents (6-8) in ONE message using parallel Agent tool calls. They run concurrently.
 
 > Scope note: this applies ONLY to the Phase 3 review specialists, which are read-only (Read/Grep/Glob,
 > no Edit/Bash, no git writes) and therefore cannot race the index. The Phase 6 FIXERS are the
@@ -1817,7 +1901,7 @@ Fix agents self-report their outcome via a status line (`FIXED: X | FAILED: Y |
 
 ### Mistake 9: Processing All Agent Files in Orchestrator Context
 
-**Wrong:** Reading all 6 finding files + validated.md in one go, causing context bloat.
+**Wrong:** Reading all 6-8 finding files + validated.md in one go, causing context bloat.
 **Right:** In Phase 5 synthesis, read validated.md first (it has the condensed verdicts). Only read original agent files if you need to resolve a specific cross-validation question.
 
 ### Mistake 10: Spawning Fixers for Non-Fixable Findings
@@ -1850,6 +1934,8 @@ Fix agents self-report their outcome via a status line (`FIXED: X | FAILED: Y |
 | `pipeline.skip_review` | boolean | false | If true, `/apt:run` skips the review phase. Does not affect direct `/apt:pr-review` invocation. |
 | `review.max_iterations` | number | 4 | Maximum fix-review iterations before stopping. |
 | `review.optional_agents` | string[] | [] | Reserved for future use. Additional specialist agents to spawn beyond the core 6. |
+| `pr_review.specialists.i18n` | `"auto"\|"always"\|"never"` | `"auto"` | Override for the conditional i18n specialist. `always` forces engage, `never` forces skip (over the detector AND over a diff-introduced signal), `auto`/absent defers to `detect-specialists`. Override is the TOP of the precedence chain (ID-01a). |
+| `pr_review.specialists.xplatform` | `"auto"\|"always"\|"never"` | `"auto"` | Override for the conditional cross-platform specialist. Same semantics as `pr_review.specialists.i18n`. |
 
 ---
 
@@ -1877,6 +1963,8 @@ Agent(
 | Codebase-fit reviewer | `.claude/agents/apt-pr-review-codebase-fit.md` | Read, Write, Grep, Glob | 3 |
 | Test-integrity reviewer | `.claude/agents/apt-pr-review-test-integrity.md` | Read, Write, Grep, Glob | 3 |
 | Performance reviewer | `.claude/agents/apt-pr-review-performance.md` | Read, Write, Grep, Glob | 3 |
+| i18n reviewer **(conditional)** | `.claude/agents/apt-pr-review-i18n.md` | Read, Write, Grep, Glob | 3 — spawned only when `detect-specialists` engages i18n (or config `always`) |
+| Cross-platform reviewer **(conditional)** | `.claude/agents/apt-pr-review-xplatform.md` | Read, Write, Grep, Glob | 3 — spawned only when `detect-specialists` engages xplatform (or config `always`) |
 | Finding validator | `.claude/agents/apt-pr-review-validator.md` | Read, Write, Grep, Glob | 4 |
 | Fix agent (x3) | `.claude/agents/apt-pr-review-fixer.md` | Read, Write, Edit, Bash, Grep, Glob | 6 |
 | Self-reviewer | `.claude/agents/apt-pr-review-self-reviewer.md` | Read, Write, Edit, Bash, Grep, Glob | 7 |

package/skills/apt-quick/SKILL.md

@@ -29,7 +29,7 @@ Execute a small task quickly without full pipeline overhead. For small fixes, do
 - **Working directory:** The project root (where you were invoked) UNLESS an active task has a task-level worktree (see below).
 - **Constitution:** Read `AGENTS.md` in the project root if it exists
 - **State directory:** `.aperant/quick/{task-id}/`
-- **Task-level worktree isolation:** If `.aperant/state.json` has an active task with a `worktree_path`, run all editing Bash commands with `cd {worktree_path} &&` prefix. `apt-tools` calls still take the project root as `<project-dir>` so they coordinate through the main repo's shared `.aperant/`. The quick task's `.aperant/quick/{task-id}/` directory lives in the main repo, not the worktree.
+- **Task-level worktree isolation:** Use the `worktree_path` the router passed in skill context (router path) OR that §1a parsed from `task create`'s envelope (direct path) — this is the worktree `task create` literally just provisioned for this task. When present, run all editing Bash commands with `cd {worktree_path} &&` prefix so the fix lands on the task branch. `apt-tools` calls still take the project root as `<project-dir>` so they coordinate through the main repo's shared `.aperant/`. The quick task's `.aperant/quick/{task-id}/` directory lives in the main repo, not the worktree. (Last-resort fallback only: if neither source supplied a `worktree_path` but `.aperant/state.json` has an active task with one, you may use that.)
 </your_environment>
 
 <state_files>
@@ -82,6 +82,15 @@ Sequence:
 
 The task id is now canonical (no more `quick-YYYYMMDD-*` invention). `QuickTaskSchema` accepts both the canonical `{slug}_YY-MM-DD` form and the legacy `quick-YYYYMMDD-{slug}` form for back-compat with already-shipped task records on disk.
 
+**Worktree isolation (both paths).** `task create` provisions a worktree when `task_isolation.worktree_per_task` is enabled (track-agnostic — QUICK 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 and run all subsequent editing Bash commands with `cd {worktree_path} &&`:
+
+```
+[APT] Working in isolated worktree: {worktree_path}
+[APT] Task branch: {branch} (from {base_branch})
+```
+
+If no `worktree` block is returned (isolation off, no host support, or already inside a worktree), proceed in the project root as before. `apt-tools` calls always take the project root as `<project-dir>`.
+
 ### 1b. Create QUICK working directory
 
 ```bash
@@ -205,6 +214,20 @@ Use appropriate conventional commit type:
 
 ## 7. Record Task
 
+**Persistence & git (quick records follow `share.tasks`).** Quick-task records
+live under `.aperant/quick/{task-id}/` and are governed by the SAME share policy
+as full-task artifacts (`.aperant/.gitignore` is policy-driven — see
+`share-policy.mjs`). Two rules:
+
+- `.aperant/quick/INDEX.md` is a **derived** index — it is ALWAYS gitignored
+  (regenerated from the per-task records, like `tasks/INDEX.md`). Never
+  `git add` it. Writing/updating it leaves no dirty tracked file.
+- The per-task record directory follows `share.tasks`. When sharing is **off**
+  (the `solo` default), the records are gitignored — write them and do nothing
+  else. When `share.tasks` is **on**, the records are committable; stage
+  `.aperant/quick/{task-id}/` alongside the code commit in Step 6 (or in a
+  follow-up `chore` commit) so they ride into version control like task specs.
+
 Write `.aperant/quick/{task-id}/TASK.md`:
 
 ```markdown

package/skills/apt-review/SKILL.md

@@ -276,6 +276,12 @@ node packages/framework/bin/apt-tools.mjs commit "fix: {finding title}" --files
 
 Update `review.json` with final state after the loop completes (findings resolved vs remaining, iteration count).
 
+### Follow-ups: `in-pr` rows execute ONLY inside this loop (G45)
+
+A follow-up ledger row whose `class_proposed: 'in-pr'` may be executed **only inside this pre-ship fix-all loop** — the loop already re-verifies, re-reviews the fixed files, rewrites `review.json`, and re-scores `qa_signoff.json` (§6b), so there is no stale-artifact problem (ID-10). When you fix an `in-pr` row here, flip its `{task_dir}/followups.json` row `status: 'fixed'` (optionally recording `executed_commit`).
+
+Discoveries made AFTER review (or outside this loop) may NOT take the in-PR path — executing them post-review would stale the QA evidence. Route those to `new-task` (file via the triage machine at close-task) or trigger a bounded re-review instead.
+
 ## 6. Update Task Documentation
 
 After fixes are applied, update the task artifacts to reflect what happened:

package/skills/apt-run/SKILL.md

@@ -103,7 +103,7 @@ If `.aperant/config.json` has `task_isolation.worktree_per_task: true` AND the h
 node packages/framework/bin/apt-tools.mjs task create . --description "{task}" --track {track} --autonomy {autonomy}
 ```
 
-Parse `worktree.worktree_path`, `worktree.branch`, and `worktree.base_branch` from the result. For every subsequent step in this pipeline, prefix Bash commands with `cd {worktree_path} &&` OR pass `worktree_path` as the spawned agent's `cwd`. `apt-tools` commands still receive the project root as their `<project-dir>` — they must hit the main repo's `.aperant/`, which is shared across worktrees. The task directory (`.aperant/tasks/{task-id}/`) is absolute and lives in the main repo, so spec/plan/progress artifacts remain shared regardless of which tree you edit code in.
+Parse `worktree.worktree_path`, `worktree.branch`, and `worktree.base_branch` from the result. For every subsequent step in this pipeline, prefix Bash commands with `cd {worktree_path} &&` OR pass `worktree_path` as the spawned agent's `cwd`. **Ephemeral `.aperant/` state resolves to the main repo from any cwd automatically** (state-fork-fix): `apt-tools` commands may receive `.` (or the worktree path) as their `<project-dir>` — `state.json` + `tasks/<task-id>/` (spec/plan/progress) and locks/events all resolve to the one main-repo `.aperant/` board, so the board never forks into a worktree. (Committable artifacts like `roadmap/` + `features/` stay worktree-local so they ride the PR branch.) `worktree create --task` likewise anchors at main from any cwd — invoking it from inside a worktree creates the new task worktree under the **main** repo's `.aperant/worktrees/` instead of erroring.
 
 Otherwise fall back to the legacy branch flow: