arreio 1.0.0-dev.1

package/skills/work/references/error-handling.md

@@ -0,0 +1,183 @@
+---
+title: Error Handling & Recovery
+description: Reference for all Work Skill phases (Triage, Prepare, Execute, Review). Defines the Step 0 artifact verification procedure, per-type required fields, error categories, recovery workflow, retry limits, and cross-phase consistency checks.
+type: reference
+version: 1.0
+timestamp: "2026-08-07"
+---
+
+# Error Handling & Recovery
+
+This file documents the error handling and recovery strategies shared across all Work Skill phases (Triage, Prepare, Execute, Review). Each phase begins with a **Step 0: Verification** that validates the incoming artifact; this reference defines the validation rules, recovery actions, and termination conditions.
+
+## Core Principle
+
+**Fail explicitly, never silently.** When an artifact is missing, malformed, or inconsistent, the phase must surface a clear error with a recovery suggestion rather than guessing or proceeding with bad data. Silent failures cascade downstream and produce invalid work runs. The one recognized exception is a *missing learnings index* (Triage Step 5), which logs a single explicit warning rather than failing — but this is a deliberate non-block, not a silent no-op.
+
+## Step 0: Artifact Verification
+
+Every phase receives an artifact from the previous phase (or the Orchestrator, for Triage). Step 0 validates the artifact before any work begins.
+
+### Verification Procedure
+
+```
+1. Confirm the artifact exists and is non-empty
+2. Confirm the required frontmatter fields are present and well-formed
+3. Confirm the artifact type matches the expected phase input
+4. Confirm interactionMode is present and valid (default to "smart" if missing)
+5. Confirm cross-phase IDs match the upstream artifacts
+```
+
+### Required Fields by Artifact Type
+
+| Artifact Type   | Required Fields                                                                                                                                                                                                    | Produced By  |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
+| `work-input`    | `type`, `timestamp`, `source`, `status`, input shape (`plan-id` **or** `task-file` **or** `ad-hoc` description), `interactionMode`                                                                                | Orchestrator |
+| `work-manifest` | `triage-id`, `work-id`, `work-branch`, `input-shape`, `status`, `interactionMode`, resolved task list, `ready-tasks` | Triage       |
+| `execution-plan`| `prepare-id`, `triage-id`, `work-id`, `work-branch`, `input-shape`, `status`, `interactionMode`, `executionMode`, `execution-list`, `runner`, `baseline`, `applicable-gates`                                                      | Prepare      |
+| `execution-log` | `execute-id`, `prepare-id`, `triage-id`, `work-id`, `work-branch`, `input-shape`, `status`, `interactionMode`, `executionMode`, per-task result table, aggregator counts                                                          | Execute      |
+| `work-report`   | `review-id`, `execute-id`, `prepare-id`, `triage-id`, `work-id`, `work-branch`, `input-shape`, `status`, `interactionMode`, `executionMode`, task-outcome rollup, `regression-check`, `scope-creep`                               | Review       |
+
+## Error Categories
+
+### Category 1: Missing Artifact
+
+The expected input artifact was not provided by the Orchestrator or previous phase.
+
+| Trigger                           | Recovery Action                                               | Terminate?         |
+| --------------------------------- | ------------------------------------------------------------- | ------------------ |
+| Artifact object is null/undefined | Ask Orchestrator to re-run previous phase                     | Yes, after 1 retry |
+| Artifact file path does not exist | Log warning; ask user to locate file or re-run previous phase | No                 |
+| Artifact file is empty (0 bytes)  | Re-run previous phase from its saved context                  | Yes, after 1 retry |
+
+### Category 2: Malformed Artifact
+
+The artifact exists but is missing required fields or has invalid structure.
+
+| Trigger                                       | Recovery Action                                             | Terminate? |
+| --------------------------------------------- | ----------------------------------------------------------- | ---------- |
+| Missing required frontmatter field            | Re-run previous phase to regenerate artifact                | No         |
+| `interactionMode` missing or invalid          | Default to `smart`; log warning; continue                   | No         |
+| `executionMode` missing or invalid (Prepare+)| Default per execution-mode-selection.md; log warning         | No         |
+| `status` field is `failed` or `pending`       | Reject; ask Orchestrator to re-run previous phase           | Yes        |
+| Artifact `type` does not match expected input | Reject; ask Orchestrator to check phase ordering            | Yes        |
+| YAML frontmatter has syntax errors            | Log error with line number; ask user to fix or re-run phase | No         |
+
+### Category 3: Invalid Work Input
+
+Only applies to the Triage phase (Step 0) when resolving a Work Input Artifact.
+
+| Trigger                                              | Recovery Action                                            | Terminate? |
+| ---------------------------------------------------- | --------------------------------------------------------- | ---------- |
+| All three input shapes empty or ambiguous            | Ask: "What would you like to work on? plan-id, task file, or describe." | No         |
+| Plan-based `plan-id` with no `docs/tasks/<id>/index.md` | Ask to run `/plan <id>` first, or switch to ad-hoc       | No         |
+| Task-file path does not resolve to exactly one file   | Ask user to disambiguate or supply the task-id            | No         |
+| Ad-hoc description empty or unobservable              | Ask: "What should happen after this is done?"             | No         |
+
+### Category 4: File System Errors
+
+Errors encountered while saving or reading artifact files.
+
+| Trigger                                          | Recovery Action                                                   | Terminate?         |
+| ------------------------------------------------ | ----------------------------------------------------------------- | ------------------ |
+| Target directory does not exist                  | Create directory (`mkdir -p`); treat counter as 0; start from 001 | No                 |
+| Counter directory exists but no files match date | Start counter at 001                                              | No                 |
+| File write permission denied                     | Log error; ask user to check permissions; retry once              | Yes, after 1 retry |
+| Task directory `docs/tasks/<work-id>/` missing   | Create it (ad-hoc); for plan-based, ask to run `/plan` first      | No                 |
+| Index `docs/tasks/<work-id>/index.md` missing    | Create empty index; append the section (idempotent on `review-id`) | No               |
+
+### Category 5: Interaction Mode Errors
+
+Errors related to `interactionMode` propagation.
+
+| Trigger                                  | Recovery Action                                            | Terminate? |
+| ---------------------------------------- | ---------------------------------------------------------- | ---------- |
+| Mode missing from incoming artifact      | Default to "smart"; log warning; continue                  | No         |
+| Mode value is not in enum                | Reject; re-prompt Orchestrator to set valid mode            | Yes        |
+| User selects "Abort" during confirmation | Stop immediately; inform Orchestrator of abort with reason   | Yes        |
+| User does not respond (timeout)          | Pause; ask user to retry or abort                          | No         |
+
+### Category 6: Execution Errors (Execute phase)
+
+| Trigger                                              | Recovery Action                                                    | Terminate? |
+| ---------------------------------------------------- | ------------------------------------------------------------------ | ---------- |
+| Task's Green gate not reached within retry-limit      | Mark task `blocked` with reason + assertion snapshot; pause per mode | No         |
+| Test runner command fails to execute (not an assertion failure) | Ask user to verify runner/packageManager; category-2 recovery | No         |
+| Dependency install fails during a Green step         | Log error; retry once; then mark task `blocked`                    | No         |
+| New regression beyond baseline snapshot on a completed task | Surface as Review Smart pause trigger; do not auto-mark blocked | No         |
+
+Initial values: a task starts `not-started`; Execute sets `in-progress` mid-task, then transitions to `completed`, `blocked`, or `skipped`. Only `completed` ticks the index checkbox.
+
+### Category 7: Git / Branch Errors
+
+Errors from Work Branch Creation (Triage Step 2d).
+
+| Trigger                                                      | Recovery Action                                                                                                       | Terminate?                |
+| ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | ------------------------- |
+| Working directory is not a git repository                    | Log one explicit warning; record `work-branch: null`, `work-branch-state: not-a-git-repo`; continue without a branch  | No                        |
+| Dirty working tree (uncommitted changes)                      | Fail branch creation with an explicit error; ask the user: commit/stash & retry, proceed without a work branch, or abort | Yes (unless user picks proceed) |
+| Branch slug cannot be derived (vague ad-hoc description)      | Ask the user for a short kebab-case slug for `work/<slug>`                                                             | No                        |
+| Current HEAD is not the default branch at creation            | Smart pause; ask which base to branch from (default branch / current HEAD / abort); autopilot: default branch + warning | No                        |
+| Branch checkout/create fails (permissions, lock, etc.)        | Log error; retry once; then terminate with a suggestion                                                                 | Yes, after 1 retry        |
+
+## Recovery Workflow
+
+When a verification failure is detected in Step 0, apply this workflow:
+
+```
+1. Identify the error category (1-7) from the tables above
+2. Look up the specific trigger to find the recovery action
+3. Execute the recovery action:
+   - If recovery is "ask user": ask one question with clear options (2-4 concrete choices)
+   - If recovery is "re-run previous phase": return to Orchestrator with error context
+   - If recovery is "default and continue": apply default, log warning, proceed
+4. If terminate = Yes: stop and inform Orchestrator with:
+   - Error category and trigger
+   - Recovery action attempted
+   - Reason for termination
+5. If terminate = No: after recovery, continue to Step 1 of the phase
+```
+
+## Retry Limits
+
+- **Maximum retries per error:** 1
+- **Maximum total retries per phase:** 2
+- **Per-task Green-gate retry-limit:** defined in [task-execution-rules.md](task-execution-rules.md) (authoritative); reaching it transitions the task to `blocked`, not a phase termination.
+- After exhausting phase retries, terminate with a clear error suggesting the user re-run the work workflow from the start or resume from the last complete phase.
+
+## Error Reporting Format
+
+When reporting an error to the Orchestrator or user, use this format:
+
+```yaml
+error:
+  phase: triage | prepare | execute | review
+  step: 0 | 1 | 2 | ...
+  category: 1 | 2 | 3 | 4 | 5 | 6
+  trigger: "[specific trigger description]"
+  recovery_attempted: "[action taken]"
+  outcome: recovered | terminated
+  suggestion: "[next step for the user or Orchestrator]"
+```
+
+## Cross-Phase Consistency Checks
+
+The Orchestrator should verify consistency between phases:
+
+| Check                                                                 | Action on Failure                           |
+| --------------------------------------------------------------------- | ------------------------------------------- |
+| `work-id` in downstream artifact matches the Triage output            | Reject; re-run from Triage                  |
+| `triage-id` in Prepare+ matches Triage output                         | Reject Prepare; re-run from Triage          |
+| `prepare-id` in Execute+ matches Prepare output                      | Reject Execute; re-run from Prepare         |
+| `execute-id` in Review matches Execute output                        | Reject Review; re-run from Execute          |
+| `interactionMode` is identical across all artifacts                   | Log warning; use earliest non-default value |
+| `executionMode` is identical across Prepare/Execute/Review artifacts | Log warning; re-run Prepare                 |
+| `work-branch` in downstream artifacts matches the Triage manifest     | Reject; re-run from Triage                  |
+
+## Notes
+
+- All errors and warnings should be logged with a timestamp for debugging.
+- When a phase terminates, its saved artifact (if any) should be marked `status: failed`.
+- The Orchestrator is responsible for deciding whether to retry the entire workflow or resume from the last successful phase.
+- ID assignment and re-use (including recycle-on-edit) is defined in [id-generation.md](id-generation.md); this reference covers only verification and recovery.
+- This reference is shared by all four phases; phase-specific handling is documented inline in the respective module.

package/skills/work/references/execution-mode-selection.md

@@ -0,0 +1,95 @@
+---
+title: Execution Mode Selection
+description: Authoritative reference for the Prepare phase. Defines the three execution modes (inline/serial/parallel), their selection defaults, the risk floor (HIGH-risk forces inline, non-downgradable), and the per-mode flows Execute follows.
+type: reference
+version: 1.0
+timestamp: "2026-08-07"
+---
+
+# Execution Mode Selection
+
+Authoritative reference for the **Prepare** phase (Step 3). Defines the three execution modes, their selection defaults, the **risk floor**, and the per-mode flows the Execute phase follows. Prepare looks these up; Execute follows them; neither re-derives them.
+
+> `executionMode` governs **how multiple tasks are run**. It is distinct from `interactionMode` (when to pause), which is set at the Orchestrator (see [interaction-mode-propagation.md](interaction-mode-propagation.md)). Both are carried independently through every artifact.
+
+## Modes
+
+| Mode       | Behavior                                                                    | Select when (default)                                            |
+| ---------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| `inline`   | One task at a time; pause between tasks; re-confirm the user before each destructive (Red) step. | `interactionMode: detailed`, **or** any task in the list is HIGH-risk or `P0` |
+| `serial`   | Run the ordered list sequentially; no per-task pause; stop only on a `blocked` task. | Default fallback — most task lists                              |
+| `parallel` | Run each wave's independent tasks concurrently; waves run in order (Wave N starts after Wave N-1 settles). | `execution-list` has 2+ independent waves **and** no task is HIGH-risk |
+
+## Selection Algorithm (authoritative)
+
+```
+1. Read from the Work Manifest each task's priority (P0/P1/P2) and any HIGH-risk flag.
+2. default_mode =
+     inline    if interactionMode == detailed OR any task is HIGH-risk OR any P0 task present
+     parallel  if execution-list has >= 2 independent waves AND no task is HIGH-risk
+     serial    otherwise (fallback)
+3. Apply the risk floor (below): any HIGH-risk task is forced to inline
+   treatment — record per-task inline-override for that task.
+4. In Detailed mode: ask the user, presenting the recommendation.
+   In Smart mode: auto-select unless a Smart pause trigger fires.
+   In Autopilot mode: auto-select; never ask.
+5. Honor user preference unless it violates the risk floor; on violation, ask the
+   user to accept inline instead.
+6. Record executionMode + per-mode flow:
+     inline    -> single-task-pause: true
+     serial    -> stop-on-blocked: true
+     parallel  -> waves: [Wave0, Wave1, ...]
+```
+
+## Risk Floor (authoritative, non-downgradable)
+
+- **Any HIGH-risk task forces `inline` treatment for that task**, regardless of the selected `executionMode`.
+  - If the list-level `executionMode` is `serial`/`parallel` but an individual task is HIGH-risk, that task runs inline (pause + re-confirm before its Red step) while independent non-HIGH-risk tasks may keep the list mode elsewhere.
+  - The user may not downgrade a HIGH-risk task below `inline`. A preference that violates this is rejected; the user is asked to accept `inline`.
+- HIGH-risk is carried from the Work Manifest (Triage preserved the per-task risk flag from the `/plan` design/research artifacts or inferred it for ad-hoc tasks).
+
+## Per-Mode Flow (authoritative; Execute follows these)
+
+### inline
+- Run one task at a time.
+- After each task completes or blocks, pause for the user (the `single-task-pause: true` flag) and re-confirm before the next task's Red (destructive) step.
+- Best when `interactionMode: detailed` or any task is HIGH-risk; it is the only mode allowed for a HIGH-risk task.
+
+### serial
+- Run the flat ordered list sequentially.
+- Do **not** pause between tasks.
+- Stop only when a task becomes `blocked` (`stop-on-blocked: true`).
+- On a block: surface the reason and ask the user whether to (a) continue with remaining independent tasks, (b) retry, or (c) abort.
+
+### parallel
+- Group `execution-list` into waves:
+  - **Wave 0** — tasks with all dependencies already `completed`.
+  - **Wave N** — tasks all of whose dependencies are in Waves `< N`; each wave is independent internally and runs concurrently.
+  - Within a wave, stable order by original unit number.
+- Waves run in order: Wave N starts only after Wave N-1 fully settles (all its tasks completed/blocked/skipped).
+- A `blocked` task in an earlier wave blocks only its dependents in later waves, not the whole current wave.
+- A HIGH-risk task in any wave is, per the risk floor, pulled to inline treatment (pause + re-confirm) even though surrounding tasks run concurrently.
+
+## Resume Behavior
+
+On re-entry (re-running Work), Prepare recomputes `executionMode` the same way, but Execute skips any task already `completed` (per the resume policy in [task-execution-rules.md](task-execution-rules.md)) and runs from the first non-completed task. The execution mode does not change on resume.
+
+## Smart Pause Triggers (Prepare)
+
+Prepare pauses in Smart mode when:
+- `baseline: red` and the user has not yet chosen a baseline policy, or
+- `executionMode: parallel` on an execution list of > 5 tasks (concurrency risk), or
+- A HIGH-risk task is present but the selected `executionMode` would not give it `inline` treatment (risk-floor conflict pre-override).
+
+## Failure Conditions
+
+| Trigger                                                  | Recovery                                                            |
+| ------------------------------------------------------- | ------------------------------------------------------------------ |
+| `executionMode` missing from the Execution Plan         | Category 2 default per error-handling.md; re-run Prepare           |
+| A cycle in wave grouping (no wave can start)             | Surface to the user; ask to break (remove a dependency) or abort    |
+| User preference violates the risk floor                 | Ask the user to accept `inline` instead; do not silently downgrade  |
+
+## Notes
+
+- This reference is the single source of truth for mode definitions, defaults, the risk floor, and per-mode flows. Prepare records the selection; Execute follows the flow; Review verifies they match (orchestrator quality gate #2).
+- The mode is independent from `interactionMode`: a Detailed run may use parallel execution, and an Autopilot run still gives HIGH-risk tasks inline treatment.

package/skills/work/references/id-generation.md

@@ -0,0 +1,85 @@
+---
+title: Artifact ID Generation
+description: Reference for Triage, Prepare, Execute, and Review phases. Defines the daily-counter algorithm for unique artifact IDs, the work-id allocation, the recycle-on-edit rule, and the shared counter layout under docs/plans/.work/.
+type: reference
+version: 1.0
+timestamp: "2026-08-07"
+---
+
+# Artifact ID Generation
+
+Shared ID algorithm for the `triage`, `prepare`, `execute`, and `review` phases, plus `work-id` allocation for ad-hoc input. Each phase assigns exactly one ID per newly produced artifact; the ID is reused (never re-incremented) when the user picks **Edit & Retry** at the phase confirmation.
+
+## ID Format by Phase
+
+| Phase    | ID format                            | Saved to                         |
+| -------- | ----------------------------------- | -------------------------------- |
+| Triage   | `YYYY-MM-DD-NNN-triage`             | `docs/plans/.work/.triage/<id>.md`   |
+| Prepare  | `YYYY-MM-DD-NNN-prepare`            | `docs/plans/.work/.prepare/<id>.md`  |
+| Execute  | `YYYY-MM-DD-NNN-execute`             | `docs/plans/.work/.execute/<id>.md`  |
+| Review   | `YYYY-MM-DD-NNN-review`              | `docs/plans/.work/.review/<id>.md`   |
+
+`work-id` (see below) is shared across all four artifacts of a single run.
+
+## work-id
+
+The `work-id` is the key that ties all four phase artifacts together and locates the task directory. It reuses the `/plan` `plan-id` format so the `docs/tasks/<id>/` convention holds uniformly:
+
+| Input shape | work-id value                                              |
+| ----------- | --------------------------------------------------------- |
+| plan-based  | `plan-id` (inherited from `docs/tasks/<plan-id>/index.md`) |
+| task-file   | `plan-id` inferred from the task file's folder            |
+| ad-hoc      | a fresh `YYYY-MM-DD-NNN` (allocated below)                |
+
+**Format:** `YYYY-MM-DD-NNN` (date + zero-padded 3-digit daily counter), identical to the `/plan` `plan-id`.
+
+> **Work branch name:** the git branch for a run is `work/<short-description>` — a kebab-case slug derived from the plan name or work description (Triage Step 2d), **not** the `work-id` itself. The Work Manifest records the `work-branch` ↔ `work-id` pairing; see `skills/work/modules/triage.md` Step 2d.
+
+## Algorithm (new phase artifact)
+
+```
+1. Get the current date in UTC (e.g., 2026-08-07)
+2. List existing files for today in the phase's save directory:
+   - triage   -> docs/plans/.work/.triage/   matching YYYY-MM-DD-*-triage.md
+   - prepare  -> docs/plans/.work/.prepare/  matching YYYY-MM-DD-*-prepare.md
+   - execute  -> docs/plans/.work/.execute/  matching YYYY-MM-DD-*-execute.md
+   - review   -> docs/plans/.work/.review/   matching YYYY-MM-DD-*-review.md
+3. NNN = (count + 1), zero-padded to 3 digits (001, 002, ..., 010, ...)
+4. id = "<date>-<NNN>-<phase>"
+```
+
+If two triage artifacts were created today, the next one is `2026-08-07-003-triage`. Counters are independent per phase; each phase counts only its own files.
+
+## Algorithm (ad-hoc work-id allocation)
+
+Allocated only in Triage for ad-hoc input:
+
+```
+1. Get the current date in UTC
+2. List existing folders under docs/tasks/ matching YYYY-MM-DD-NNN for that date
+3. NNN = (highest existing NNN for that date) + 1, zero-padded to 3 digits
+   - if none exist for that date, start at 001
+4. work-id = "<date>-<NNN>"
+5. Create docs/tasks/<work-id>/ and its index.md (Triage Step 2c)
+```
+
+> This deliberately mirrors the `/plan` Generate-phase `plan-id` counting (per `skills/plan/references/id-generation.md`), so a `/plan`-produced `docs/tasks/<plan-id>/` and an ad-hoc `/work`-produced `docs/tasks/<work-id>/` share one numbering space per date and never collide.
+
+## Recycle on Edit & Retry
+
+When the user picks **Edit & Retry** at a phase confirmation, **reuse the original ID** and overwrite the existing artifact file. Do **not** increment the counter. This keeps IDs stable across iterations and prevents orphaned artifacts. The Review phase's `## Work Report — <review-id>` block in the task index is likewise idempotent on `review-id` (overwritten, never duplicated).
+
+## Error Handling
+
+| Trigger                                         | Action                                       |
+| ----------------------------------------------- | -------------------------------------------- |
+| Phase save directory does not exist              | Create it; treat count as 0; start from 001  |
+| Directory exists but no files match today's date | Start counter at 001                         |
+| `docs/tasks/` missing                           | Create it (ad-hoc work-id allocation)        |
+| Write permission denied                         | Log error; ask the user; retry once          |
+
+## Notes
+
+- IDs reuse the `/plan` daily-counter algorithm for cross-skill consistency; the Work skill's counters are independent from Plan's (separate save directories).
+- `work-id` carries through every artifact (`triage-id` artifacts record it; Prepare/Execute/Review inherit it), so cross-phase chaining is `triage-id → prepare-id → execute-id → review-id`, all sharing one `work-id` (see [error-handling.md](error-handling.md) "Cross-Phase Consistency Checks").
+- Counter collisions are impossible within a date because each phase writes to its own directory and recomputes the count from the directory listing.

package/skills/work/references/interaction-mode-propagation.md

@@ -0,0 +1,80 @@
+---
+title: Interaction Mode Propagation
+description: Reference for how `interactionMode` propagates through the Work pipeline (Triage -> Prepare -> Execute -> Review). Set at the Orchestrator; each phase reads and applies mode-specific behavior.
+type: reference
+version: 1.0
+timestamp: "2026-08-07"
+---
+
+# Interaction Mode Propagation
+
+Reference for how `interactionMode` propagates through the Work pipeline (`Triage → Prepare → Execute → Review`). Set at the Orchestrator; each phase reads and applies mode-specific behavior.
+
+> `interactionMode` governs **when to pause for the user**. It is distinct from **execution mode** (`inline` / `serial` / `parallel`), which governs **how multiple tasks are run** and is selected in Prepare (see [execution-mode-selection.md](execution-mode-selection.md)). Both are carried independently through every artifact.
+
+## Modes
+
+| Mode          | Behavior                                              | Use Case                             |
+| ------------- | ----------------------------------------------------- | ------------------------------------ |
+| **Detailed**  | Pause at each phase; present artifacts; require approval | Complex/high-risk work, unfamiliar codebases |
+| **Smart**     | Auto-proceed; pause only on HIGH-risk flags           | Familiar codebases with guardrails   |
+| **Autopilot** | Run all phases auto (Review still reports)             | Straightforward, well-planned task lists |
+
+## Phase Behavior by Mode
+
+| Phase        | Detailed                                         | Smart                                                                                                       | Autopilot                         |
+| ------------ | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | --------------------------------- |
+| **Triage**   | Present manifest; ask Proceed/Edit/Abort          | Auto-proceed; pause if ad-hoc inferred list, unmet upstream dep (task-file), or task-artifact validation recovery | Auto-proceed                      |
+| **Prepare**   | Present execution plan; ask Proceed/Edit/Abort   | Auto-proceed; pause if red-baseline open, parallel > 5 tasks, or HIGH-risk risk-floor conflict             | Auto-proceed                      |
+| **Execute**  | Per-task pause (inline) + ask Proceed/Edit/Abort  | Auto-proceed; pause if blocked-at-retry-limit, new regression on Refactor, or parallel dependent-blocked   | Auto-proceed (inline mode still pauses for HIGH-risk tasks) |
+| **Review**   | Present work report; ask Finalize/Edit/Abort     | Auto-proceed; pause if regressions-found, scope-creep, or learnings-to-capture non-empty                    | Auto-proceed (strips to Smart triggers) |
+
+**Smart mode pauses only on each phase's documented triggers above** (the canonical list lives in each module's confirmation step; this table is a summary).
+
+## Artifact Schema
+
+All phase artifacts include `interactionMode`:
+
+```yaml
+interactionMode: detailed | smart | autopilot # Passed from previous phase
+status: pending | complete | failed
+```
+
+## Implementation
+
+**Each phase must:**
+
+1. Read `interactionMode` from the incoming artifact (or context, for Triage).
+2. Apply mode-specific behavior per the table above.
+3. Include `interactionMode` in the output artifact.
+
+## Example
+
+**SMART mode on a plan-based run:**
+
+- Triage reads a plan-based index (no inferred list) → auto-proceeds
+- Prepare detects a GREEN baseline, serial mode → auto-proceeds
+- Execute runs serially; one task hits the retry-limit → pauses (blocked-at-retry-limit)
+- User reviews the block reason and chooses to continue with remaining independent tasks → execute resumes
+- Review finds no regressions, no scope-creep, empty learnings → auto-proceeds
+
+**Result:** Paused only for the genuine blocker; faster than Detailed with safety guardrails.
+
+## Execution Mode Independence
+
+`executionMode` is chosen in Prepare and propagated alongside `interactionMode`:
+
+- A **Detailed** run may still use **parallel** execution (every independent task runs concurrently, but Review still confirms).
+- An **Autopilot** run still gives HIGH-risk tasks **inline** treatment (per the execution-mode-selection risk floor), even though no confirmation prompt is shown.
+
+The two never override one another; the orchestrator's quality gate #2 cross-checks both are identical across artifacts.
+
+## Error Handling
+
+| Scenario                    | Recovery                              |
+| --------------------------- | ------------------------------------- |
+| Mode missing                | Default to "smart"; log warning       |
+| Invalid mode value          | Reject; re-prompt Orchestrator        |
+| Artifact missing mode field | Assume "smart"; log warning; continue |
+| User selects "Abort"        | Stop immediately; inform Orchestrator |
+| Timeout/connection lost     | Pause; ask user to retry or abort     |

package/skills/work/references/review-checklist.md

@@ -0,0 +1,94 @@
+---
+title: Review Checklist
+description: Authoritative reference for the Review phase. Defines the simplification, consolidation, scope-creep, regression, and learnings-capture checks Review applies across the completed tasks' changed files. Review applies the checklist; it does not re-encode it.
+type: reference
+version: 1.0
+timestamp: "2026-08-07"
+---
+
+# Review Checklist
+
+Authoritative reference for the **Review** phase. Defines the checks Review applies across the `completed` tasks' changed files (`files.create` / `files.modify`). Review applies the checklist; it does not re-encode it. Each check is run as a **refactor** — the relevant tasks' AC tests must stay green; any check that would change behavior is routed to scope-creep handling, not applied here.
+
+## Simplification Checks
+
+Run across the union of completed tasks' `files.create` / `files.modify`:
+
+| Check                | Criteria (authoritative)                                                           | Apply as        |
+| -------------------- | ---------------------------------------------------------------------------------- | --------------- |
+| Dead code            | Code made unreachable by the run (unused exports, unreachable branches, vestigial helpers) is removed. | refactor        |
+| Duplication (DRY)    | Repeated logic across the changed files is extracted into one shared helper/abstraction. | refactor        |
+| Naming               | Identifiers are intention-revealing; no cryptic or misnamed symbols introduced.     | refactor        |
+| Function/class size   | Functions/classes do one thing; overlarge units are collapsed to single responsibility. | refactor        |
+| Speculative generality | No added abstractions/parameters with no current consumer.                       | refactor (remove) |
+| Commented-out code   | No commented-out code or dead scaffolding left behind.                             | refactor (remove) |
+
+Record `simplification-summary` (what was simplified/clipped) and `consolidations` (any merged logic / extracted abstractions) in the Work Report.
+
+## Consolidation Checks
+
+| Check                    | Criteria                                                                          | Apply as   |
+| ------------------------ | --------------------------------------------------------------------------------- | ---------- |
+| Shared logic extraction  | Two+ completed tasks introduced parallel logic; extract to a shared, tested unit.  | refactor   |
+| Public-API minimization  | Public surface area is minimal; depend on abstractions, not concretions.         | refactor   |
+| Import boundary hygiene  | Side effects isolated at boundaries; inner functions kept pure where the change permits. | refactor |
+
+A consolidation that would change behavior is **not** applied here — it becomes a scope-creep finding (the user decides whether to accept it as a follow-up task).
+
+## Regression Check (authoritative for the suite comparison)
+
+Run the full affected-scope suite (union of completed tasks' test paths + any modified files covered elsewhere) using the Execute-resolved command. Compare against the Prepare baseline:
+
+| baseline               | Clean condition                                                 | Regression condition           |
+| ---------------------- | --------------------------------------------------------------- | ------------------------------ |
+| `green`                | Suite is still green                                            | Any failure is a regression    |
+| `snapshot-and-continue`| Failures are a **subset** of the recorded known-failing snapshot | Any **new** failure is a regression |
+
+Record `regression-check: clean | regressions-found` with the failing-test list if any. A regression on a `completed` task is a Review Smart pause trigger.
+
+## Scope-Creep Checks (authoritative)
+
+| Check                | Criteria (authoritative)                                                                              | Outcome                                  |
+| -------------------- | ----------------------------------------------------------------------------------------------------- | ---------------------------------------- |
+| Per-task scope       | A `completed` task's `files.create`/`files.modify` edits are bounded by **that task's single AC**. Edits beyond the AC (extra files, behavior not asserted by `files.test`) are scope creep. | Record per task: file path + why it exceeds the AC |
+| Manifest scope      | No task was added, removed, or silently expanded beyond what Triage resolved. (`dependency-warning: expanded-to-upstream` from the task-file shape is expected, not creep.) | Record any deviation                     |
+
+Record `scope-creep: none` or the per-task findings. Surface creep to the user — never fold it silently into a task.
+
+## Learnings-Capture Checks
+
+For each notable finding, record a learning candidate:
+
+| Finding type       | When to capture                                              | Fields                                            |
+| ------------------ | ------------------------------------------------------------ | ------------------------------------------------- |
+| Confirmed pattern   | A codebase pattern was confirmed during execution            | title, domain, source (task-id + gate), summary   |
+| Refuted assumption  | An assumption from Triage/Prepare was contradicted           | title, domain, source, summary                    |
+| Gotcha hit          | A recurring trap was encountered (e.g., a flaky test class) | title, domain, source, summary                    |
+| Forced decision     | The run forced a non-obvious decision                       | title, domain, source, summary                   |
+
+Also carry forward the Work Manifest's `Learning Gaps` and add any gaps the run revealed (e.g., a missing test pattern that forced a workaround) to `learning-gaps`.
+
+Record `learnings-to-capture` (candidates, handed to `/learn` — Work does not write `docs/learn/` directly) and the updated `learning-gaps` in the Work Report.
+
+## Final work-state (Review derives from the Execution Log)
+
+| work-state    | Condition                                                                     |
+| ------------- | ----------------------------------------------------------------------------- |
+| `complete`    | All tasks `completed` **and** regression-check `clean`                        |
+| `partial`     | Some tasks `blocked`/`skipped` but progress was made                          |
+| `nothing-done`| Empty run (`work-state: nothing-ready` carried through) or all tasks blocked early |
+
+## Failure Conditions
+
+| Trigger                                        | Recovery                                                  |
+| ---------------------------------------------- | --------------------------------------------------------- |
+| A simplification check would change behavior   | Route to scope-creep; do not apply as a refactor          |
+| Regression found on a `completed` task          | Smart pause trigger; user decides accept or roll back      |
+| Scope creep detected                            | Surface to user; do not fold silently into a task           |
+| Task-status incoherent at Review Step 0         | Category 2 recovery per [error-handling.md](error-handling.md) — re-run Execute |
+
+## Notes
+
+- This reference is the single source of truth for the simplification/consolidation/scope-creep/regression/learnings checks. Review applies it; Prepare and Execute do not re-encode it.
+- Every applied change here is a **refactor**: AC tests stay green, no behavior change. Behavior-changing ideas become scope-creep findings for the user to accept as a follow-up.
+- Learnings are surfaced for `/learn` to persist; Work never writes `docs/learn/` directly.