@aperant/framework 0.13.0 → 0.15.0

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:
 

package/skills/apt-setup/SKILL.md

@@ -199,7 +199,7 @@ AskUserQuestion([
 
 **Routing:**
 - "Verification" → jump to **Step 2** (Batch 1 + Batch 2 only), then skip to **Step 4** (mapping) and **Step 5** (write)
-- "Pipeline" → jump to **Step 3** (Batch 2: auto-branch, code review, TDD, PR Review Auto-Suggest, **Sparring Auto-Fire**) AND **Step 3b** (Batch 3 only, including Diagram Mode), then skip to **Step 4** and **Step 5**
+- "Pipeline" → jump to **Step 3** (Batch 2: auto-branch, code review, TDD, PR Review Auto-Suggest, CI Watcher, **Sparring Auto-Fire**) AND **Step 3b** (Batch 3 only, including Diagram Mode), then skip to **Step 4** and **Step 5**
 - "Orchestration" → jump to **Step 3c** (Batch 4 only), then skip to **Step 4** and **Step 5**
 - "Team Collaboration" → jump to **Step 3d** (Batch 5 only), then skip to **Step 4** and **Step 5**
 - "Visibility" → jump to **Step 3e** (Batch 6 only), then skip to **Step 4** and **Step 5**
@@ -412,6 +412,16 @@ AskUserQuestion([
       { label: "Ask me", description: "Prompt [Y/n] each time — choose per-PR." },
       { label: "Never", description: "Silent. Run /apt:pr-review manually if needed." }
     ]
+  },
+  {
+    question: "After /apt:ship opens a PR, run the post-ship CI watcher? It polls checks, auto-fixes the first red check and pushes, and can auto-merge once CI is green.",
+    header: "CI Watcher",
+    multiSelect: false,
+    options: [
+      { label: "Watch & auto-fix (Recommended)", description: "Ship auto-arms the watcher: it polls CI, fixes the first red check + pushes, then stops at green for you to merge. Ticks automatically on cron-capable hosts (Claude Code/Pi); elsewhere you advance ticks manually with /apt:watch-ci --tick." },
+      { label: "Watch, fix & auto-merge on green", description: "Same as above, plus auto-merges the PR (squash) once CI is green, then suggests /apt:close-task. Fully hands-off run." },
+      { label: "Off", description: "Ship does not arm the watcher. Watch CI and merge yourself, or run /apt:watch-ci manually." }
+    ]
   }
 ])
 ```
@@ -728,8 +738,8 @@ AskUserQuestion([
     options: [
       { label: "Auto", description: "Best available for your CLI" },
       { label: "Agent Team", description: "Uses Claude Code agent teams (requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1)" },
-      { label: "Sub-Agents", description: "Spawns 6 parallel sub-agents for review (available on Claude Code and Codex)" },
-      { label: "Sequential", description: "Runs 6 review passes inline, one at a time — works on any CLI" }
+      { label: "Sub-Agents", description: "Spawns 6-8 parallel sub-agents for review (available on Claude Code and Codex)" },
+      { label: "Sequential", description: "Runs 6-8 review passes inline, one at a time — works on any CLI" }
     ]
   },
   {
@@ -1378,6 +1388,13 @@ Map the user's selections to config values:
 - "Ask me" → `pr_review.suggest_after_ship: "ask"`
 - "Never" → `pr_review.suggest_after_ship: "never"`
 
+**CI Watcher (post-ship):** maps to the SHARED `.aperant/config.json` `ci_watch` block (team policy — NOT a per-device AUDIT-001 field, so it stays in shared `config.json`):
+- "Watch & auto-fix (Recommended)" → `ci_watch.after_ship: "auto"`, `ci_watch.auto_merge_on_green: false`
+- "Watch, fix & auto-merge on green" → `ci_watch.after_ship: "auto"`, `ci_watch.auto_merge_on_green: true`
+- "Off" → `ci_watch.after_ship: "never"`, `ci_watch.auto_merge_on_green: false`
+
+The existing `ci_watch.merge_method` key (default `"squash"`) is preserved untouched — this question does not change it. On non-cron hosts, `after_ship: "auto"` still creates the watcher state and ship prints manual-tick instructions; the host-capability fallback already lives in `apt-ship/SKILL.md` §7.2, so the value is safe to store as team policy regardless of the setup-runner's host.
+
 **Sparring Auto-Fire (FRAMEWORK-RFC-001):**
 - Phase 1 "No" → `spar.enabled: false`, ask Phase 3 (hint sub-picker)
 - Phase 1 "Yes" → `spar.enabled: true`, ask Phase 2 (partner picker)
@@ -1522,6 +1539,7 @@ Display:
 | Auto Branch          | {Yes/No}                     |
 | Code Review          | {Yes/No}                     |
 | TDD Iron Law         | {Yes/No}                     |
+| CI Watcher           | {Off / Watch & fix / Watch, fix & auto-merge} |
 | Sparring Auto-Fire   | {Off / On (codex), On (claude), On (gemini)} (hint: {Yes/No}) |
 | Date Format          | {DD-MM-YY / MM-DD-YY / YY-MM-DD} |
 | Time Format          | {24h / 12h}                  |

package/skills/apt-ship/SKILL.md

@@ -20,6 +20,7 @@ gates:
   - constitution-read
   - verify-approved
   - review-clean
+  - followups-adjudicated
   - consistency-check
   - r-persona-alignment
   - gitignore-in-sync
@@ -149,15 +150,18 @@ Capture `remote_tip_sha_pre_rebase` now — §6's lease uses it.
   ```
   Proceed to §1. §6's push will use `--force-with-lease=refs/heads/<branch>:$remote_tip_sha_pre_rebase` because history was rewritten.
 
-- **`behind > 0` AND `mergeable === false`** → STOP. Emit a structured error with the conflict preview verbatim:
-  ```
-  [APT:ship] Cannot ship — task branch is behind origin/{base_branch} and the rebase would conflict.
-  Conflicts preview:
-    - {path1}
-    - {path2}
-  Resolve manually (rebase or merge in the worktree), then re-run /apt:ship.
-  ```
-  Exit the skill — do NOT auto-resolve, do NOT proceed to §5 or §6.
+- **`behind > 0` AND `mergeable === false`** → the rebase would conflict. Default behavior is a hard STOP; AI resolution is **opt-in** via `pipeline.resolve_merge_conflicts` (default false) in `.aperant/config.json`.
+
+  - **Resolution opted in (`pipeline.resolve_merge_conflicts === true`)** → hand off to **`/apt:merge-conflict-resolution`** (`--base origin/{base_branch}`). That skill drives the rebase, resolves the conflicted files inline (reading the markers via `apt-tools merge markers`), and re-probes mergeability. On success it returns here — proceed to §1 with `--force-with-lease=refs/heads/<branch>:$remote_tip_sha_pre_rebase` (history was rewritten). On its non-convergence STOP, it aborts to a clean tree and hands back; fall through to the manual-STOP message below.
+  - **Resolution NOT opted in (default)** → STOP. Emit a structured error with the conflict preview verbatim:
+    ```
+    [APT:ship] Cannot ship — task branch is behind origin/{base_branch} and the rebase would conflict.
+    Conflicts preview:
+      - {path1}
+      - {path2}
+    Resolve manually (rebase or merge in the worktree) or enable pipeline.resolve_merge_conflicts to use /apt:merge-conflict-resolution, then re-run /apt:ship.
+    ```
+    Exit the skill — do NOT auto-resolve, do NOT proceed to §5 or §6.
 
 - **`mergeable === null` AND `audit_warning === "git-version-too-old"`** → STOP with a friendlier message:
   ```
@@ -175,8 +179,8 @@ Capture `remote_tip_sha_pre_rebase` now — §6's lease uses it.
 **Autonomy gating.** Read the active task's autonomy level from `.aperant/state.json` (`active_tasks[{task-id}].autonomy`, falling back to `autonomy.default`):
 
 - **Autonomy 0–1 (step / guided)** — print the audit envelope to the operator and ask `Rebase now? [Y/n]` before executing the `git rebase` line. On `N`, exit the skill (user can rebase manually and re-invoke).
-- **Autonomy 2 (auto-chain)** — proceed silently on the clean-rebase branch; STOP on conflict regardless.
-- **Autonomy 3 (YOLO)** — same as 2: silent on clean, STOP on conflict. Auto-resolution of conflicts is explicitly out of scope (see spec §Out of Scope).
+- **Autonomy 2 (auto-chain)** — proceed silently on the clean-rebase branch; on conflict, hand off to `/apt:merge-conflict-resolution` when `pipeline.resolve_merge_conflicts` is enabled, else STOP.
+- **Autonomy 3 (YOLO)** — same as 2: silent on clean; on conflict, AI-resolve via `/apt:merge-conflict-resolution` when opted in, else STOP. Even at YOLO the resolved branch still flows through PR → review → CI — apt:ship never auto-merges.
 
 The captured `remote_tip_sha_pre_rebase` and `behind` integer are referenced verbatim in §6's push command. Treat them as read-only state for the remainder of the skill.
 
@@ -380,11 +384,21 @@ The body structure below is the full-pipeline template — unchanged from the pr
 
 {If no review: "No code review was run for this task."}
 
+## Follow-ups
+
+{Read `{task_dir}/followups.json` and enumerate EVERY open/dispositioned row VERBATIM — never a count. One line per row:}
+
+- [{status}] {title} — {adjudication.verdict ?? 'unadjudicated'} → {disposition.kind ?? 'pending'}
+
+{If no followups.json: "No follow-ups recorded for this task."}
+
 ---
 
 Built with [Aperant Framework](https://github.com/Mikalsen-AI/aperant-cloud-desktop/tree/main/packages/framework)
 ```
 
+Counts hide work; the verbatim row list is the visibility contract (ID-16). The `followups-adjudicated` gate (Section 0) has already guaranteed every open row is adjudicated and every load-bearing row is fixed before you reach this section.
+
 ## 4. Determine Ship Mode
 
 Read `.aperant/config.json` for `project_type`.
@@ -520,8 +534,15 @@ Review: logic={n} security={n} quality={n} architecture={n} performance={n}
 Commits: {count}
 Review findings: {count by severity or "none"}
 Decisions traced: {count}
+
+Follow-ups:
+{Enumerate EVERY open/dispositioned row from {task_dir}/followups.json VERBATIM,
+one per line — `- [{status}] {title} — {verdict} → {disposition.kind ?? 'pending'}`.
+Never a count. "none" only when followups.json is absent or has zero rows.}
 ```
 
+The report's Follow-ups block mirrors the PR-body `## Follow-ups` section (ID-16) — rows verbatim, never counts.
+
 ### 7.1 Post-ship /apt:pr-review hint
 
 After printing the ship summary, conditionally emit a tip suggesting `/apt:pr-review` for a deep multi-agent review of the freshly-opened PR. The hint is controlled by `pr_review.suggest_after_ship` in `.aperant/config.json` (tri-state: `always` | `ask` | `never`; default when absent: `always`).

package/skills/apt-terminal/SKILL.md

@@ -97,6 +97,14 @@ The response is JSON to stdout. On success:
 
 `depth` is the new terminal's level (caller_depth + 1). Record `sessionId` in your task notes.
 
+The worktree the spawned terminal opens in already has the project's stored env
+blobs materialized (the per-project encrypted env store, #354) — worktree-create
+copies each `.env*` blob verbatim (traversal-guarded, best-effort) so the sibling
+terminal's CLI runs with the real env instead of crashing in no-cloud mode. If a
+long-lived worktree's stored env later drifts, re-copy on demand with
+`node packages/framework/bin/apt-tools.mjs worktree sync-env <dir> --task <id>`
+(the store is the source of truth — sync-env overwrites, never merges).
+
 ## 4. Recognise the graceful-degrade error envelopes
 
 These are **expected** error shapes — do not retry blindly. Each one tells you exactly which obligation discharged:

package/skills/apt-triage/SKILL.md

@@ -49,6 +49,10 @@ OUT-OF-SCOPE.md sub-files ported from
 - An inbound task / bug / feature request needs status assignment
 - Periodic review of `needs-triage` tasks
 - Re-triage when new info arrives on a `needs-info` task
+- A `new-task` follow-up disposition (G45) — `/apt:close-task` files an open
+  follow-up as a fresh task and enters it here at `needs-triage` via
+  `apt-tools triage init` (the configured backend mirrors it). This is a normal
+  entry point; the chained-task depth marker rides `triage.json` `extra.followups_chain`.
 
 ## When NOT to Use
 

package/skills/apt-verify/SKILL.md

@@ -266,6 +266,30 @@ for ITERATION in 1 2 3 4:
 
 **Exhaustion:** If issues remain after 4 iterations, mark them in `qa_signoff.json` and report them. The verdict should reflect the remaining issues.
 
+## 6.5 Follow-ups Adjudication (mandatory — G45)
+
+This pass is **mandatory** on every full-pipeline verify. It is the owner of follow-up adjudication: `apt:verify` always runs in the pipeline (`apt:run` = plan → execute → verify → review), whereas `apt:verify-proof` is opt-in and therefore cannot be the sole owner. (When `verify-proof` runs later it MAY overwrite an adjudication with stronger evidence, `by: 'verify-proof'`.)
+
+Run the deterministic check first:
+
+```bash
+node packages/framework/bin/apt-tools.mjs followups check . --task-id {task-id}
+```
+
+The envelope returns `missing_expected[]` — the derived expected universe (parsed `## Out of Scope` bullets ∪ raw review rows ∪ qa findings, `status !== 'fixed'`) that the ledger does not yet cover. Create/sync `{task_dir}/followups.json` rows **mechanically** from those payloads:
+
+- Append one row per `missing_expected[]` entry: `{ id, title, origin, class_proposed: <class_hint>, files: [], outcome_refs: [], status: 'open' }`. `class_proposed` is only a PROPOSAL (ID-03) — the verdict below is the authority; never let the class self-certify a deferral.
+- Voluntary rows (origin `discuss | execute | ci`) may also be present; they are adjudicated the same way.
+
+Then **adjudicate every open row**. For each, answer the single question:
+
+> "Would the feature satisfy its stated `## User Outcomes` right now WITHOUT this follow-up?"
+
+- If NO → `adjudication: { verdict: 'load-bearing', by: 'verify', outcome_ref: '<O-n>' }`. A load-bearing row blocks ship until it is fixed (flip `status: 'fixed'` once the work lands in this PR's fix loop) or bypassed via `--force --reason`.
+- If YES → `adjudication: { verdict: 'deferrable', by: 'verify', outcome_ref: '<O-n> | null' }`. `outcome_ref` is the `O<n>` id (from `parseUserOutcomes`) the row relates to; it is nullable for refactor-only specs that declare no outcomes.
+
+Re-run `followups check` until it is **derivation-clean** (exit 0 — no `missing_expected`, no `invalid_outcome_refs`, no `schema_errors`) BEFORE writing `qa_signoff.json`. The `followups-adjudicated` ship gate will block the PR otherwise.
+
 ## 7. Write QA Sign-off
 
 Create `qa_signoff.json` using the `ScoredQASignoff` format (see `packages/framework/src/types/qa-scoring.ts`):

package/skills/apt-watch-ci/SKILL.md

@@ -125,7 +125,9 @@ When `action === 'fix'` (or `diverged-rebased`/`diverged-bailed`):
 5. **Emit event.** `apt-tools event append . --type ci-watch.fix-pushed --data '{pr, attempts, commit_sha}'`.
 6. **Reschedule** per §3 step 4.
 
-For `diverged-rebased`: the cmd already returned the verb; the orchestrator runs `git -C {worktree} fetch && git rebase origin/{base}` BEFORE the fix step. On conflict the action becomes `diverged-bailed` and the watcher exits with a PR comment summarizing the conflict.
+For `diverged-rebased`: the cmd already returned the verb; the orchestrator runs `git -C {worktree} fetch && git rebase origin/{base}` BEFORE the fix step. On conflict the action becomes `diverged-bailed`.
+
+For `diverged-bailed`: default behavior is to exit with a PR comment summarizing the conflict. Self-heal is **opt-in** via `ci_watch.resolve_merge_conflicts` (default false) in `.aperant/config.json`. When enabled, instead of bailing, hand off to **`/apt:merge-conflict-resolution`** (`--base origin/{base}`) for the worktree; it resolves the rebase conflict inline and re-probes mergeability. On success, continue to the §5 fix-and-push step (`git push origin {branch}`) and reschedule per §3 — the watcher keeps running. On its non-convergence STOP (it aborts the rebase to a clean tree first), fall back to the bail-with-PR-comment path. The resolved branch still goes through CI; the watcher never auto-merges except via the existing config-gated `gh pr merge --auto`.
 
 ---
 

package/src/cli/commands/audit-branch-current.mjs

@@ -42,7 +42,7 @@ import { err, ok } from '../util/result.mjs'
  * @param {string} cwd
  * @param {string[]} args
  */
-function gitTry(cwd, args) {
+export function gitTry(cwd, args) {
 	try {
 		const stdout = execFileSync('git', args, {
 			cwd,
@@ -94,7 +94,7 @@ function parseBaseFlag(extraArgs) {
  * @param {string} stdout
  * @returns {string[]}
  */
-function parseConflictPaths(stdout) {
+export function parseConflictPaths(stdout) {
 	const paths = new Set()
 	for (const rawLine of stdout.split('\n')) {
 		const line = rawLine.replace(/\0/g, '')
@@ -125,7 +125,7 @@ function parseConflictPaths(stdout) {
  * @param {string} stderr
  * @returns {boolean}
  */
-function isGitVersionTooOld(stderr) {
+export function isGitVersionTooOld(stderr) {
 	return /unknown option|did you mean|usage: git merge-tree/i.test(stderr)
 }