@aperant/framework 0.13.0 → 0.16.0

package/dist/plugin/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/dist/plugin/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/dist/plugin/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/dist/plugin/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/dist/plugin/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" },
+  "crossplatform": { "engage": false, "signals": [], "reason": "no signals" }
+}
+```
+
+Engagement precedence (the detector encodes it; you just read the result):
+config `pr_review.specialists.{i18n,crossplatform}` ∈ `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" },
+  "crossplatform": { "engaged": false, "reason": "no signals" }
+}
+```
+
+```
+i18n: ENGAGED (strong: locale-file src/locales/fr.json)
+crossplatform: SKIPPED (no platform signals; config: auto)
+```
+
+Store `result.i18n.engage` and `result.crossplatform.engage` as `ENGAGE_I18N` /
+`ENGAGE_CROSSPLATFORM` 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_CROSSPLATFORM` 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_CROSSPLATFORM is true:
+Agent(
+  name: "crossplatform-reviewer",
+  subagent_type: "apt-pr-review-crossplatform",
+  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 crossplatform.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.crossplatform` | `"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-crossplatform.md` | Read, Write, Grep, Glob | 3 — spawned only when `detect-specialists` engages crossplatform (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 |