arreio 1.0.5 → 1.2.0

package/skills/plan/references/plan-tier-selection.md

@@ -2,8 +2,8 @@
 title: Plan Tier Selection
 description: Reference for the Generate phase. Defines the Fast/Standard/Deep tier model, the selection algorithm that combines complexity, risk, and user preference, and the template sections each tier requires.
 type: reference
-version: 1.1
-timestamp: "2026-08-07"
+version: 1.2
+timestamp: "2026-10-01"
 ---
 
 # Plan Tier Selection
@@ -24,40 +24,45 @@ Tier selection happens at the start of the Generate phase, after reading the Des
 
 ## Selection Algorithm
 
+Tier selection is **two pure functions**. Run them step by step with the real values; never shortcut to a "typical" tier.
+
+Values are compared case-insensitively (`HIGH` = `High`). `risk_level` comes from the Research Findings; `complexity` from the Design Artifact.
+
 ```
-function select_tier(complexity, risk_level, user_preference):
-  # 1. Start from complexity-driven default
-  if complexity in [TRIVIAL, LOW]:
-    base_tier = Fast
-  elif complexity == MEDIUM:
-    base_tier = Standard
-  else:  # HIGH or VERY_HIGH
-    base_tier = Deep
-
-  # 2. Upgrade tier if risk warrants it
-  if risk_level == HIGH and base_tier == Fast:
-    base_tier = Standard
-  if risk_level == CRITICAL:
-    base_tier = Deep
-
-  # 3. Honor explicit user preference (never downgrade below risk floor)
-  if user_preference == "fast" and risk_level not in [HIGH, CRITICAL]:
-    return Fast
-  if user_preference == "deep":
-    return Deep
-  if user_preference == "standard" and risk_level != CRITICAL:
-    return Standard
-
-  return base_tier
+# A. Recommendation — computed in the Design phase (Step 4) and re-computed in Generate (Step 1).
+#    Depends ONLY on complexity and risk. Never on user input or --deep.
+function recommend_tier(complexity, risk_level):
+  # 1. Complexity-driven default
+  if complexity in [TRIVIAL, LOW]:   tier = Fast
+  elif complexity == MEDIUM:         tier = Standard
+  else:  # HIGH or VERY_HIGH         tier = Deep
+
+  # 2. Risk floor (see table below) — may only raise the tier
+  if risk_level == HIGH and tier == Fast: tier = Standard
+  if risk_level == CRITICAL:              tier = Deep
+  return tier
+
+# B. Selection — computed in the Generate phase (Step 1).
+function select_tier(complexity, risk_level, user_preference, force_deep):
+  recommended = recommend_tier(complexity, risk_level)
+  floor       = risk_floor(risk_level)            # Fast | Standard | Deep
+
+  if force_deep:                       return Deep                  # explicit user request; always honored
+  if user_preference == "auto":        return recommended           # Auto = the algorithm, NOT a fixed tier
+  # Explicit tier: honor it, but never go below the risk floor
+  return max(user_preference, floor)   # order: Fast < Standard < Deep
 ```
 
+`tier_recommended` is **always** `recommend_tier(...)` — it is never changed by user preference or `--deep`. `tier` is `select_tier(...)`. When they differ, the plan records an auditable override.
+
 ### Inputs
 
-| Input             | Source                          | Values                                |
-| ----------------- | ------------------------------- | ------------------------------------- |
-| `complexity`      | Design Artifact                 | TRIVIAL, LOW, MEDIUM, HIGH, VERY_HIGH |
-| `risk_level`      | Research Findings Artifact      | LOW, MEDIUM, HIGH, CRITICAL           |
-| `user_preference` | User (asked in Generate Step 1) | `fast`, `standard`, `deep`, or `auto` |
+| Input             | Source                                              | Values                                |
+| ----------------- | --------------------------------------------------- | ------------------------------------- |
+| `complexity`      | Design Artifact                                     | TRIVIAL, LOW, MEDIUM, HIGH, VERY_HIGH |
+| `risk_level`      | Research Findings Artifact                          | LOW, MEDIUM, HIGH, CRITICAL           |
+| `user_preference` | User (asked in Generate Step 1; see mode behavior)  | `fast`, `standard`, `deep`, or `auto` |
+| `force_deep`      | Orchestrator context (`--deep` flag, SKILL.md)      | `true` or `false` (default `false`)   |
 
 ### Risk Floor
 
@@ -72,6 +77,22 @@ The risk level sets a **minimum tier** that user preference cannot override:
 
 Rationale: High/critical risk mandates enough structure to capture alternatives, rollout, and rollback — even if the user wants a short plan.
 
+### Anti-Default Rules (read before computing)
+
+- **`Standard` is not a neutral default.** It is the result only for `MEDIUM` complexity (or a `HIGH` risk floor lifting a Fast result). `HIGH`/`VERY_HIGH` complexity → **Deep**; `TRIVIAL`/`LOW` → **Fast** unless risk lifts it.
+- **Compute, then write.** Fill the function inputs with the actual `complexity` and `risk_level`, evaluate, and only then write `tier_recommended`. Do not copy a tier from an example in this file.
+- **Auto means "use `tier_recommended`".** Never substitute `Standard` because it is the middle option.
+
+### Deep Override (`--deep`)
+
+The user can force a Deep plan in **any** interaction mode (including Autopilot and Smart) by invoking `/plan --deep <task>` (parsing rules in [SKILL.md](../SKILL.md#skill-invocation)).
+
+- `force_deep = true` → `tier = deep`, regardless of complexity, risk, or `user_preference`. The tier question is **not asked**, in any mode.
+- `tier_recommended` still holds the algorithm's result, so the override is auditable (`tier: deep`, `tier_recommended: fast`, etc.).
+- Deep only adds structure, so it never violates the risk floor.
+- The Smart-mode "tier is Deep" pause does **not** fire for a `--deep` plan (the user already chose it). CRITICAL-risk pause still applies.
+- Because Design runs before Generate, the Design phase also receives `force_deep` so it produces the material a Deep plan needs (≥ 2 alternatives, rollout draft, integration map) — see [design.md](../modules/design.md) Steps 4–5.
+
 ## Tier Section Requirements
 
 ### Fast Tier
@@ -109,33 +130,42 @@ Required sections (all Standard sections, plus):
 - Explicit complexity and tier in frontmatter
 - Cross-system integration map (data-flow or sequence diagram)
 
+**Required does not mean invented.** On a Deep plan forced by `--deep` for a small change, a required item that genuinely does not apply (e.g., data migration for a doc-only change) is written as `Not applicable — <one-line reason>`. Never omit the item and never fabricate content to fill it.
+
 ## Interaction Mode Behavior
 
-| Mode      | Tier Selection Behavior                                                                             |
-| --------- | --------------------------------------------------------------------------------------------------- |
-| Detailed  | Ask the user to confirm the selected tier; offer to override                                        |
-| Smart     | Auto-select; pause **only** if selected tier is Deep (or user preference conflicts with risk floor) |
-| Autopilot | Auto-select with `user_preference = auto`; never pause                                              |
+| Mode      | `user_preference`                                      | Tier Selection Behavior                                                                                   |
+| --------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| Detailed  | Asked (prompt below), unless `force_deep`              | Ask the user; offer to override. `force_deep` → no question, announce "Deep plan forced by `--deep`"      |
+| Smart     | `auto` (asked only if a pause trigger fires)           | Auto-select; pause **only** on the triggers below                                                         |
+| Autopilot | `auto`                                                 | Auto-select; never pause                                                                                  |
+
+`force_deep = true` overrides `user_preference` in every row.
 
 **Smart mode pause triggers:**
 
-- Selected tier is Deep (signals complex work worth a review)
+- Selected tier is Deep **and `force_deep` is false** (signals complex work worth a review)
 - User preference conflicts with risk floor (e.g., user wants Fast but risk is HIGH)
 - Research phase reported CRITICAL risk (Security or Payments)
 
 ## Asking the User for Preference
 
-In Detailed mode (or when Smart mode pauses), ask the user one question:
+In Detailed mode (or when Smart mode pauses), ask one question. **Build it from the computed values — every `<…>` placeholder below must be replaced; never print an example tier.**
 
 ```
-Based on the design complexity (HIGH) and risk level (HIGH), I recommend the Standard tier.
+Design complexity is <complexity> (score <total>/15) and risk level is <risk_level>.
+I recommend the <tier_recommended> tier.
 Which tier would you like for the plan?
   - Fast: Short plan, minimal structure (1-2 pages)
-  - Standard: Full plan with phased units and risk table (2-4 pages) [Recommended]
+  - Standard: Full plan with phased units and risk table (2-4 pages)
   - Deep: Comprehensive plan with alternatives and rollout ops (4+ pages)
-  - Auto: Let the algorithm decide (result: Standard)
+  - Auto: Use the recommendation (result: <tier_recommended>)
 ```
 
+- Append ` [Recommended]` to the option that equals `tier_recommended`.
+- If the risk floor makes an option unavailable (e.g., Fast at HIGH risk), keep it listed but say "(below risk floor — will be raised to <floor>)".
+- Tip to include once in the question text: `/plan --deep` forces a Deep plan without this question.
+
 Record the user's choice as the selected **`tier`** in the final plan frontmatter; preserve the algorithm's suggestion as **`tier_recommended`** so an override is auditable.
 
 ## Worked Examples
@@ -143,19 +173,34 @@ Record the user's choice as the selected **`tier`** in the final plan frontmatte
 ### Example 1: Low complexity, low risk
 
 - `complexity = LOW`, `risk_level = LOW`, `user_preference = auto`
-- Base tier: Fast. No risk upgrade. Auto preference → **Fast**.
+- `recommend_tier` → Fast. Auto → **Fast** (`tier_recommended: fast`).
+
+### Example 2: Medium complexity, medium risk, auto
+
+- `complexity = MEDIUM`, `risk_level = MEDIUM`, `user_preference = auto`
+- `recommend_tier` → Standard. Auto → **Standard** (`tier_recommended: standard`).
 
-### Example 2: Medium complexity, high risk, user wants fast
+### Example 3: Medium complexity, high risk, user wants fast
 
 - `complexity = MEDIUM`, `risk_level = HIGH`, `user_preference = fast`
-- Base tier: Standard. Risk upgrade: already Standard (HIGH floor). User wants Fast but HIGH risk floor is Standard → **Standard**.
+- `recommend_tier` → Standard. Floor (HIGH) = Standard. `max(Fast, Standard)` → **Standard**.
 - Smart mode would pause (preference conflicts with risk floor).
 
-### Example 3: High complexity, critical risk (payments)
+### Example 4: High complexity, high risk, auto
+
+- `complexity = HIGH` (score 8), `risk_level = HIGH`, `user_preference = auto`
+- `recommend_tier` → **Deep** (HIGH complexity → Deep; not Standard). Auto → **Deep** (`tier_recommended: deep`).
+- Smart mode pauses (Deep tier).
+
+### Example 5: High complexity, critical risk (payments)
 
 - `complexity = HIGH`, `risk_level = CRITICAL`, `user_preference = auto`
-- Base tier: Deep. CRITICAL forces Deep. Auto preference → **Deep**.
-- Smart mode pauses (Deep tier + CRITICAL risk).
+- `recommend_tier` → Deep. Auto → **Deep**. Smart mode pauses (Deep + CRITICAL).
+
+### Example 6: `--deep` on a small change, Autopilot
+
+- `complexity = LOW`, `risk_level = LOW`, `force_deep = true`, mode = autopilot
+- `tier_recommended: fast`, `tier: deep`. No question asked, no pause. Required Deep sections without real content are written as `Not applicable — <reason>`.
 
 ## Error Handling
 
@@ -165,10 +210,12 @@ Record the user's choice as the selected **`tier`** in the final plan frontmatte
 | `risk_level` missing from Research      | Default to MEDIUM; log warning                  |
 | User provides invalid preference value  | Treat as `auto`; log warning                    |
 | Selected tier conflicts with risk floor | Enforce risk floor; inform user of the override |
+| Design's `tier_recommended` differs from `recommend_tier(complexity, risk_level)` | Recompute in Generate; the recomputed value is authoritative; log warning |
+| `--deep` given but the phase artifact lacks the rollout/alternatives material | Generate writes `Not applicable — <reason>` for items that do not apply; never invents content |
 
 ## Notes
 
 - Tier choice is recorded in the final plan's frontmatter as `tier: fast | standard | deep`
 - The tier also influences the Tasks phase: Fast tier often produces 1–3 tasks; Standard 4–8; Deep 8+
-- If the user overrides the tier, preserve the algorithm's recommendation in a `tier_recommended` field for audit
+- If the user overrides the tier (explicit choice or `--deep`), preserve the algorithm's recommendation in a `tier_recommended` field for audit
 - Tier selection is the primary "right-sizing" mechanism — Small tasks → short plans; complex work → more structure (per Plan Skill core principles)

package/skills/plan/references/templates/artifacts/design.md

@@ -98,7 +98,7 @@ tier_recommended: fast | standard | deep
 - [Gap name] — [Follow-up action via /learn]
 ```
 
-Also save the design artifact to `docs/plans/.design/<design-id>.md` for future reference or reuse. The `interactionMode` and `complexity` values flow into the Generate artifact for tier selection.
+In `detailed` mode only, also save the design artifact to `docs/plans/.design/<design-id>.md` for future reference or reuse. The `interactionMode` and `complexity` values flow into the Generate artifact for tier selection. In `smart`/`autopilot` mode, do not write it; pass it to the next phase in context.
 
 ## Validation Rules
 

package/skills/plan/references/templates/artifacts/scoped-context.md

@@ -50,4 +50,4 @@ action: resume | review | archive | delete | create-new | none
 - (Empty list if none found)
 ```
 
-Also save the scoped context to `docs/plans/.scope/<scope-id>.md` for future reference or reuse. The `interactionMode` value flows into `research`, `design`, and `generate` artifacts.
+In `detailed` mode only, also save the scoped context to `docs/plans/.scope/<scope-id>.md` for future reference or reuse. The `interactionMode` value flows into `research`, `design`, and `generate` artifacts. In `smart`/`autopilot` mode, do not write it; pass it to the next phase in context.

package/skills/review/SKILL.md

@@ -35,6 +35,8 @@ Store in the context object:
 interactionMode: detailed | smart | autopilot
 ```
 
+**Artifact persistence:** intermediate phase artifacts are written to disk **only in `detailed` mode**. In `smart`/`autopilot` they are passed between phases in context and never written (see `references/interaction-mode-propagation.md#artifact-persistence`). Final deliverables are always written.
+
 **Propagation:** `interactionMode` flows into the `scope`, `prepare`, `analyze`, and `report` artifacts; each downstream phase reads it to adjust confirmation behaviour (detailed = pause every transition; autopilot = run all; smart = pause only on `blocker`/`major` findings or detected scope creep).
 
 ## Orchestration Implementation
@@ -58,8 +60,9 @@ Each phase runs sequentially: the orchestrator calls the phase module, receives
 
 Before starting the review pipeline, the orchestrator verifies that required folders exist:
 
-- `docs/plans/.review/.scope/`, `docs/plans/.review/.prepare/`, `docs/plans/.review/.analyze/`, `docs/plans/.review/.report/` — must exist for saving the four phase artifacts
-- `docs/plans/.review/index.md` — must exist as the review registry (Report appends to it)
+- `docs/review/.report/` — must exist for saving the Review Report (always written)
+- `docs/review/.scope/`, `docs/review/.prepare/`, `docs/review/.analyze/` — **`detailed` mode only**, for saving the intermediate phase artifacts; do not create them in `smart`/`autopilot`
+- `docs/review/index.md` — must exist as the review registry (Report appends to it)
 
 **Self-Healing:** If any are missing, the orchestrator automatically creates them (`mkdir -p`, and a seed `index.md` with a registry header). This allows the Review skill to run even if `arreio-init` wasn't explicitly run.
 
@@ -73,10 +76,10 @@ For **task-in-review** input, verify the `work-id` exists and contains at least
 
 | Phase | Phase Module                  | Output Artifact                                                  | Saved to                              |
 | ----- | ----------------------------- | ---------------------------------------------------------------- | ------------------------------------- |
-| 1     | [Scope](modules/scope.md)     | [Review scope](references/templates/artifacts/review-scope.md)   | `docs/plans/.review/.scope/<id>.md`   |
-| 2     | [Prepare](modules/prepare.md) | [Review kit](references/templates/artifacts/review-kit.md)       | `docs/plans/.review/.prepare/<id>.md` |
-| 3     | [Analyze](modules/analyze.md) | [Findings](references/templates/artifacts/findings.md)           | `docs/plans/.review/.analyze/<id>.md` |
-| 4     | [Report](modules/report.md)   | [Review report](references/templates/artifacts/review-report.md) | `docs/plans/.review/.report/<id>.md`  |
+| 1     | [Scope](modules/scope.md)     | [Review scope](references/templates/artifacts/review-scope.md)   | `docs/review/.scope/<id>.md` _(detailed only)_ |
+| 2     | [Prepare](modules/prepare.md) | [Review kit](references/templates/artifacts/review-kit.md)       | `docs/review/.prepare/<id>.md` _(detailed only)_ |
+| 3     | [Analyze](modules/analyze.md) | [Findings](references/templates/artifacts/findings.md)           | `docs/review/.analyze/<id>.md` _(detailed only)_ |
+| 4     | [Report](modules/report.md)   | [Review report](references/templates/artifacts/review-report.md) | `docs/review/.report/<id>.md`  |
 
 ### Quality Gates
 
@@ -99,7 +102,7 @@ Each phase is responsible for its own index updates:
 | Scope   | _(none — produces artifact only)_                                      | Allocates the `review-id`; no index write.                                                                                     |
 | Prepare | _(none)_                                                               | Gathers the review kit; no index write.                                                                                        |
 | Analyze | _(none)_                                                               | Produces findings; no index write.                                                                                             |
-| Report  | `docs/plans/.review/index.md`                                          | Append a registry row: `<report-id>`, review target summary, approval status, link to the report file.                         |
+| Report  | `docs/review/index.md`                                          | Append a registry row: `<report-id>`, review target summary, approval status, link to the report file.                         |
 | Report  | `docs/tasks/<work-id>/index.md` _(work-linked or task-in-review only)_ | Append a distinct `## Review Report — <report-id>` block (separate from Work's own `## Work Report` block).                    |
 | Report  | Task frontmatter _(task-in-review only)_                               | Update task file `status:` field to `completed` (if approved) or `blocked` (if changes-requested, with reason in frontmatter). |
 
@@ -107,8 +110,8 @@ Each phase is responsible for its own index updates:
 
 ### FINAL OUTPUT
 
-- **Review Report:** Saved to `docs/plans/.review/.report/<report-id>.md`, with: the change boundary, the approval status (`approved` / `changes-requested` / `rejected`), the graded findings rollup, recommendations, and (when requirements were available) the scope-creep summary.
-- **Registry row:** `docs/plans/.review/index.md` updated with the new review.
+- **Review Report:** Saved to `docs/review/.report/<report-id>.md`, with: the change boundary, the approval status (`approved` / `changes-requested` / `rejected`), the graded findings rollup, recommendations, and (when requirements were available) the scope-creep summary.
+- **Registry row:** `docs/review/index.md` updated with the new review.
 - **(Work-linked or task-in-review only) Index cross-link:** `docs/tasks/<work-id>/index.md` gets a `## Review Report — <report-id>` block so a future glance at the work index shows that an external Review ran over it.
 - **(Task-in-review only) Task Status Update:** ✅ **NEW**: For each task with `status: for-review`:
   - If approval status = `approved` → update task file's frontmatter `status: completed`
@@ -143,6 +146,17 @@ Artifact templates live in [references/templates/artifacts/](references/template
 | [findings.md](references/templates/artifacts/findings.md)           | Analyze      |
 | [review-report.md](references/templates/artifacts/review-report.md) | Report       |
 
+## Execution Rules
+
+Follow these literally; they exist to keep runs consistent across agents.
+
+1. **Run each module's steps in order**, starting with its Step 0 verification. Do not skip, merge, or reorder steps.
+2. **Never invent values.** If a required input is missing, apply the recovery in [error-handling.md](references/error-handling.md) or ask the user; do not fill it with a plausible guess.
+3. **Compute, don't copy.** Values defined by a rule (finding severity, `approval-status`, scope-creep flag) must be derived from the cited rubric and the real findings — never judged by feel, and never copied from an example. Example values in references and templates are illustrations, never defaults.
+4. **One question at a time**, with 2–4 concrete options; build the question text from the current values.
+5. **Announce phase transitions in one line** (e.g., "Phase 2/4 Analyze complete: <key result>") so the user can follow progress, even in Autopilot.
+6. **Honor write rules:** intermediate phase artifacts only in `detailed` mode; final deliverables always.
+
 ## Core Principles
 
 - **Deterministic Pipeline:** Phases always execute in sequence (no agent switching, no fallback paths).
@@ -155,6 +169,7 @@ Artifact templates live in [references/templates/artifacts/](references/template
 - **Test the Tests:** Reviewing changes includes evaluating the tests that accompany them — coverage, correctness of assertions, and whether they assert the intended Acceptance Criterion — not just production code.
 - **Read-Only Review:** Review analyzes and reports; it never edits the code under review. Required changes become a follow-up task (a new `/plan` + `/work`, or manual edits) — never applied inline here.
 - **Single Source of Truth:** This skill defines all its own rules; it does not depend on any external agent rule file. Category, severity, and approval definitions live once in their authoritative references and are never re-encoded inline in the modules.
+- **Lean Persistence:** Phase artifacts hit disk only in `detailed` mode; `smart`/`autopilot` pass them in context to save tokens and time.
 - **Transparent Artifacts:** Each phase produces an explicit output artifact for the next phase.
 - **Behavior-Described, Tool-Agnostic:** Steps describe required capabilities ("read the diff", "run the test suite", "update the index"), not specific tool names; each agent maps to its native tools.
 - **Interaction Mode Propagation:** `interactionMode` is read at the start of each subsequent phase and determines whether confirmation steps execute.

package/skills/review/modules/analyze.md

@@ -69,7 +69,7 @@ Tools never **create** a finding on their own outside the change boundary; they
 ### Step 5: Aggregate Tallies and Generate the Findings Artifact
 
 1. **Aggregate** findings by category and count by severity. Compute preliminary tallies (Report derives the final approval status from these — Analyze does not pre-derive approval).
-2. **Assign an `analyze-id`** per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-analyze`, saved to `docs/plans/.review/.analyze/`). Reuse it if the user later picks **Edit & Retry**.
+2. **Assign an `analyze-id`** per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-analyze`, saved to `docs/review/.analyze/`). Reuse it if the user later picks **Edit & Retry**.
 3. Produce a **Findings** block (as markdown) following the schema in [findings.md](../references/templates/artifacts/findings.md). Include:
    - `analyze-id`, inherited `prepare-id`, `scope-id`, `review-id`, `input-shape`, `interactionMode`
    - the findings list: per finding — `id`, `severity`, `category`, `location` (repository-relative `file:line` or `file:hunk`), `message`, `trace` **or** `scope-creep: true`, and an optional non-binding `suggested-fix` (Review is read-only — suggestions are informational, never applied)
@@ -90,7 +90,7 @@ Apply the **[phase confirmation behavior](../references/interaction-mode-propaga
 - **Smart:** pause only when a pause trigger above is true; otherwise auto-proceed.
 - **Autopilot:** auto-proceed (no confirmation).
 
-Then save the artifact to `docs/plans/.review/.analyze/<analyze-id>.md` (ensure `interactionMode` included) and return it, with the `interactionMode` value, to the Orchestrator for the transition to Phase 4 (Report).
+Then, **in `detailed` mode only**, save the artifact to `docs/review/.analyze/<analyze-id>.md` (ensure `interactionMode` included) and return it, with the `interactionMode` value, to the Orchestrator for the transition to Phase 4 (Report). In `smart` and `autopilot` mode, do **not** write the file; pass the artifact to the next phase in context (see [Artifact Persistence](../references/interaction-mode-propagation.md#artifact-persistence)).
 
 ## Output: Findings Artifact
 
@@ -99,6 +99,6 @@ Then save the artifact to `docs/plans/.review/.analyze/<analyze-id>.md` (ensure
 - Verify the **scope-creep** category either ran (with `spec-content` not `none`) or is recorded `skipped (no requirements)` — never silently absent, never inventing requirements.
 - Verify severities were **assigned from** [severity-rubric.md](../references/severity-rubric.md) rather than re-defined inline (no second rubric contradicting the authoritative reference).
 - Verify the category checks were **run from** [review-categories.md](../references/review-categories.md) rather than re-encoded inline.
-- Verify that the artifact is saved to `docs/plans/.review/.analyze/<analyze-id>.md`.
+- Verify that, in `detailed` mode, the artifact is saved to `docs/review/.analyze/<analyze-id>.md`; in `smart`/`autopilot` mode, verify that **no** file was written and the artifact was passed to the next phase in context.
 
 > Pass the Findings to `report` (Phase 4) for the approval-status derivation, the report write, and the registry / work-index cross-link.

package/skills/review/modules/prepare.md

@@ -68,7 +68,7 @@ If **no** linter/type-checker is configured for the repo, that is a Smart pause
 
 ### Step 5: Generate the Review Kit Artifact
 
-1. **Assign a `prepare-id`** per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-prepare`, saved to `docs/plans/.review/.prepare/`). Reuse it if the user later picks **Edit & Retry**.
+1. **Assign a `prepare-id`** per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-prepare`, saved to `docs/review/.prepare/`). Reuse it if the user later picks **Edit & Retry**.
 
 2. Produce a **Review Kit** block (as markdown) following the schema in [review-kit.md](../references/templates/artifacts/review-kit.md). Include:
    - `prepare-id`, inherited `scope-id` and `review-id`, `input-shape`, `interactionMode`
@@ -90,7 +90,7 @@ Apply the **[phase confirmation behavior](../references/interaction-mode-propaga
 - **Smart:** pause only when a pause trigger above is true; otherwise auto-proceed.
 - **Autopilot:** auto-proceed (no confirmation).
 
-Then save the artifact to `docs/plans/.review/.prepare/<prepare-id>.md` (ensure `interactionMode` included) and return it, with the `interactionMode` value, to the Orchestrator for the transition to Phase 3 (Analyze).
+Then, **in `detailed` mode only**, save the artifact to `docs/review/.prepare/<prepare-id>.md` (ensure `interactionMode` included) and return it, with the `interactionMode` value, to the Orchestrator for the transition to Phase 3 (Analyze). In `smart` and `autopilot` mode, do **not** write the file; pass the artifact to the next phase in context (see [Artifact Persistence](../references/interaction-mode-propagation.md#artifact-persistence)).
 
 ## Output: Review Kit Artifact
 
@@ -98,6 +98,6 @@ Then save the artifact to `docs/plans/.review/.prepare/<prepare-id>.md` (ensure
 - Verify that every `required` file has a diff entry (or is recorded as deleted / `current-contents`) and that `context` is separated from `required`.
 - Verify that `test-context` records covering tests per changed file and whether the change ships its own tests.
 - Verify that `requirements-source: none` propagated as `spec: none` (so Analyze skips the requirements-vs-scope-creep category rather than guessing).
-- Verify that the artifact is saved to `docs/plans/.review/.prepare/<prepare-id>.md`.
+- Verify that, in `detailed` mode, the artifact is saved to `docs/review/.prepare/<prepare-id>.md`; in `smart`/`autopilot` mode, verify that **no** file was written and the artifact was passed to the next phase in context.
 
 > Pass the Review Kit to `analyze` (Phase 3) for the categorized, severity-graded review of the diffs.

package/skills/review/modules/report.md

@@ -1,6 +1,6 @@
 ---
 title: Report
-description: Fourth and final step in the Review workflow. Derives the final approval status (approved / changes-requested / rejected) from the Findings per the authoritative approval criteria, composes non-binding recommendations, generates the Review Report, registers it in docs/plans/.review/index.md, and (work-linked only) appends a distinct ## Review Report — <report-id> block to the work task index. Returns the Review Report as the Review skill's final deliverable.
+description: Fourth and final step in the Review workflow. Derives the final approval status (approved / changes-requested / rejected) from the Findings per the authoritative approval criteria, composes non-binding recommendations, generates the Review Report, registers it in docs/review/index.md, and (work-linked only) appends a distinct ## Review Report — <report-id> block to the work task index. Returns the Review Report as the Review skill's final deliverable.
 type: module
 version: 1.0
 timestamp: "2026-08-08"
@@ -8,7 +8,7 @@ timestamp: "2026-08-08"
 
 # Phase 4 - Report
 
-**Purpose:** Fourth and final step in the Review workflow. Reads the [Findings](../references/templates/artifacts/findings.md) from Analyze, derives the final **approval status** (`approved` / `changes-requested` / `rejected`) per the authoritative criteria, composes non-binding recommendations, writes the [Review Report](../references/templates/artifacts/review-report.md), registers it in `docs/plans/.review/index.md`, and — for work-linked input only — appends a distinct `## Review Report — <report-id>` block to `docs/tasks/<work-id>/index.md` (clearly separate from Work's own `## Work Report` block). Returns the Review Report as the Review skill's final deliverable.
+**Purpose:** Fourth and final step in the Review workflow. Reads the [Findings](../references/templates/artifacts/findings.md) from Analyze, derives the final **approval status** (`approved` / `changes-requested` / `rejected`) per the authoritative criteria, composes non-binding recommendations, writes the [Review Report](../references/templates/artifacts/review-report.md), registers it in `docs/review/index.md`, and — for work-linked input only — appends a distinct `## Review Report — <report-id>` block to `docs/tasks/<work-id>/index.md` (clearly separate from Work's own `## Work Report` block). Returns the Review Report as the Review skill's final deliverable.
 
 ## Workflow
 
@@ -44,7 +44,7 @@ Derive the status deterministically from the tallies (count of `blocker`/`major`
 
 ### Step 3: Generate the Review Report Artifact
 
-1. **Assign a `report-id`** per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-report`, saved to `docs/plans/.review/.report/`). Reuse it if the user later picks **Edit & Retry**.
+1. **Assign a `report-id`** per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-report`, saved to `docs/review/.report/`). Reuse it if the user later picks **Edit & Retry**.
 
 2. Produce a **Review Report** block (as markdown) following the schema in [review-report.md](../references/templates/artifacts/review-report.md). Include:
    - `report-id`, inherited `analyze-id`, `prepare-id`, `scope-id`, `review-id`, `input-shape`, `interactionMode`
@@ -57,10 +57,10 @@ Derive the status deterministically from the tallies (count of `blocker`/`major`
 
 ### Step 4: Register in the Review Registry
 
-Append a registry row to `docs/plans/.review/index.md`:
+Append a registry row to `docs/review/index.md`:
 
 ```
-- <report-id> — <target-summary> — <approval-status> — docs/plans/.review/.report/<report-id>.md
+- <report-id> — <target-summary> — <approval-status> — docs/review/.report/<report-id>.md
 ```
 
 Create the index with a registry header (`# Reviews`) if it does not yet exist. The row is **idempotent on `report-id`**: a re-run overwrites the row with the same id, never duplicates it.
@@ -76,7 +76,7 @@ When `input-shape: work-linked`, append a **distinct** status block to `docs/tas
 - **Findings:** <blocker> blocker, <major> major, <minor> minor, <nit> nit
 - **Scope creep:** none | <count> | skipped (no requirements)
 - **Learnings to capture:** <count> (run `/learn` to persist)
-- **Review Report:** docs/plans/.review/.report/<report-id>.md
+- **Review Report:** docs/review/.report/<report-id>.md
 ```
 
 The block is **append-only** and **idempotent on `report-id`** (a re-run overwrites the block with the same id, never duplicates it). If the work index does not exist, skip the cross-link and note it in the report (do not fabricate a work index).
@@ -92,7 +92,7 @@ Apply the **[phase confirmation behavior](../references/interaction-mode-propaga
 - **Smart:** pause only when a pause trigger above is true; otherwise auto-proceed.
 - **Autopilot:** auto-proceed (no confirmation).
 
-Then save the artifact to `docs/plans/.review/.report/<report-id>.md` (ensure `interactionMode` included).
+Then save the artifact to `docs/review/.report/<report-id>.md` (ensure `interactionMode` included).
 
 ### Step 7: Return to Orchestrator
 
@@ -103,7 +103,7 @@ Return the Review Report to the Orchestrator — `path`, `report-id`, `review-id
 - Verify that the Review Report is complete and valid: `report-id`, `analyze-id`, `prepare-id`, `scope-id`, `review-id`, `input-shape`, `interactionMode`, `approval-status`, the findings rollup, `recommendations`, `scope-creep-summary`, and `learnings-to-capture`.
 - Verify that **findings coherence** held (re-verified in Step 0): every finding has a severity, category, repo-relative location, and a `trace` or `scope-creep: true`.
 - Verify that the approval status was **derived from** [approval-criteria.md](../references/approval-criteria.md) rather than re-defined inline (no second rule contradicting the authoritative reference).
-- Verify the registry row was appended to `docs/plans/.review/index.md` (idempotent on `report-id`), and — for work-linked input — the distinct `## Review Report — <report-id>` block was appended to `docs/tasks/<work-id>/index.md` (idempotent, never colliding with Work's `## Work Report` block).
-- Verify that the artifact is saved to `docs/plans/.review/.report/<report-id>.md`.
+- Verify the registry row was appended to `docs/review/index.md` (idempotent on `report-id`), and — for work-linked input — the distinct `## Review Report — <report-id>` block was appended to `docs/tasks/<work-id>/index.md` (idempotent, never colliding with Work's `## Work Report` block).
+- Verify that the artifact is saved to `docs/review/.report/<report-id>.md`.
 
 > The Review Report is the primary deliverable of the Review Skill. The Orchestrator marks the workflow complete; optionally chains to `/learn` when learnings were surfaced.

package/skills/review/modules/scope.md

@@ -89,9 +89,9 @@ Search `docs/learn/index.md` for entries relevant to the review domains (the cha
 
 ### Step 6: Allocate review-id and Generate the Review Scope Artifact
 
-1. **Allocate a `review-id`** of the form `YYYY-MM-DD-NNN` per [id-generation.md](../references/id-generation.md), counting existing `docs/plans/.review/.scope/YYYY-MM-DD-NNN-scope.md` files (or registry rows) for today. This is the pipeline umbrella id (distinct from any Work `review-id` for work-linked input — the two skills produce independent artifacts; the `work-id` is carried alongside for traceability).
+1. **Allocate a `review-id`** of the form `YYYY-MM-DD-NNN` per [id-generation.md](../references/id-generation.md), counting existing `docs/review/.scope/YYYY-MM-DD-NNN-scope.md` files (or registry rows) for today in `detailed` mode, or existing `docs/review/.report/` files in `smart`/`autopilot` (no scope file is written; see id-generation.md). This is the pipeline umbrella id (distinct from any Work `review-id` for work-linked input — the two skills produce independent artifacts; the `work-id` is carried alongside for traceability).
 
-2. **Assign a `scope-id`** per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-scope`, saved to `docs/plans/.review/.scope/`). Reuse it if the user later picks **Edit & Retry**.
+2. **Assign a `scope-id`** per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-scope`, saved to `docs/review/.scope/`). Reuse it if the user later picks **Edit & Retry**.
 
 3. Produce a **Review Scope Artifact** block (as markdown) following the schema in [review-scope.md](../references/templates/artifacts/review-scope.md). Include:
    - `scope-id`, `review-id`, `input-shape`, `interactionMode`
@@ -113,7 +113,7 @@ Apply the **[phase confirmation behavior](../references/interaction-mode-propaga
 - **Smart:** pause only when a pause trigger above is true; otherwise auto-proceed.
 - **Autopilot:** auto-proceed (no confirmation).
 
-Then save the artifact to `docs/plans/.review/.scope/<scope-id>.md` (ensure `interactionMode`, `input-shape`, and `review-id` are included) and return it, with the `interactionMode` value, to the Orchestrator for the transition to Phase 2 (Prepare).
+Then, **in `detailed` mode only**, save the artifact to `docs/review/.scope/<scope-id>.md` (ensure `interactionMode`, `input-shape`, and `review-id` are included) and return it, with the `interactionMode` value, to the Orchestrator for the transition to Phase 2 (Prepare). In `smart` and `autopilot` mode, do **not** write the file; pass the artifact to the next phase in context (see [Artifact Persistence](../references/interaction-mode-propagation.md#artifact-persistence)).
 
 ## Output: Review Scope Artifact
 
@@ -121,6 +121,6 @@ Then save the artifact to `docs/plans/.review/.scope/<scope-id>.md` (ensure `int
 - Verify that the change boundary is in **dependency-safe** form: `required` files are repository-relative and carry a status; `context` is separated from `required`.
 - Verify that `review-id` was allocated (scope is the allocating phase) and that `work-id` is carried for work-linked input.
 - Verify that scope-creep detection was run only when requirements were present (else explicitly skipped with a note), per [scope-creep-detection.md](../references/scope-creep-detection.md).
-- Verify that the artifact is saved to `docs/plans/.review/.scope/<scope-id>.md`.
+- Verify that, in `detailed` mode, the artifact is saved to `docs/review/.scope/<scope-id>.md`; in `smart`/`autopilot` mode, verify that **no** file was written and the artifact was passed to the next phase in context.
 
 > Pass the Review Scope to `prepare` (Phase 2) to gather the diffs, spec content, test context, and tool inventory.

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

@@ -85,7 +85,7 @@ Errors encountered while saving or reading artifact files.
 | 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 |
-| `docs/plans/.review/index.md` registry missing  | Create it with a `# Reviews` header (Pre-Flight already creates; idempotent) | No     |
+| `docs/review/index.md` registry missing  | Create it with a `# Reviews` header (Pre-Flight already creates; idempotent) | No     |
 | `docs/tasks/<work-id>/index.md` missing (Report cross-link) | Skip the cross-link; note the absence in the report (do not fabricate a work index) | No |
 
 ### Category 5: Interaction Mode Errors

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

@@ -1,6 +1,6 @@
 ---
 title: Artifact ID Generation
-description: Reference for Scope, Prepare, Analyze, and Report phases. Defines the daily-counter algorithm for unique artifact IDs, the review-id umbrella allocation (distinct from a Work review-id), the recycle-on-edit rule, and the shared counter layout under docs/plans/.review/.
+description: Reference for Scope, Prepare, Analyze, and Report phases. Defines the daily-counter algorithm for unique artifact IDs, the review-id umbrella allocation (distinct from a Work review-id), the recycle-on-edit rule, and the shared counter layout under docs/review/.
 type: reference
 version: 1.0
 timestamp: "2026-08-08"
@@ -12,12 +12,12 @@ Shared ID algorithm for the `scope`, `prepare`, `analyze`, and `report` phases,
 
 ## ID Format by Phase
 
-| Phase    | ID format                            | Saved to                            |
+| Phase    | ID format                            | Saved to (detailed only)                            |
 | -------- | ----------------------------------- | ----------------------------------- |
-| Scope    | `YYYY-MM-DD-NNN-scope`              | `docs/plans/.review/.scope/<id>.md`    |
-| Prepare  | `YYYY-MM-DD-NNN-prepare`            | `docs/plans/.review/.prepare/<id>.md`  |
-| Analyze  | `YYYY-MM-DD-NNN-analyze`            | `docs/plans/.review/.analyze/<id>.md`  |
-| Report   | `YYYY-MM-DD-NNN-report`             | `docs/plans/.review/.report/<id>.md`   |
+| Scope    | `YYYY-MM-DD-NNN-scope`              | `docs/review/.scope/<id>.md`    |
+| Prepare  | `YYYY-MM-DD-NNN-prepare`            | `docs/review/.prepare/<id>.md`  |
+| Analyze  | `YYYY-MM-DD-NNN-analyze`            | `docs/review/.analyze/<id>.md`  |
+| Report   | `YYYY-MM-DD-NNN-report`             | `docs/review/.report/<id>.md`   |
 
 `review-id` (see below) is the umbrella shared across all four artifacts of a single review run.
 
@@ -25,19 +25,21 @@ Shared ID algorithm for the `scope`, `prepare`, `analyze`, and `report` phases,
 
 The `review-id` is the umbrella key that ties all four phase artifacts together and keys the registry row / work-index block. It is allocated **once** in Scope Step 2 (the allocating phase) and carried through Prepare/Analyze/Report unchanged.
 
-**Format:** `YYYY-MM-DD-NNN` (date + zero-padded 3-digit daily counter), counting existing `docs/plans/.review/.scope/YYYY-MM-DD-NNN-scope.md` files for that date (the scope phase is the allocating phase, so its counter is the source of truth for the umbrella id).
+**Format:** `YYYY-MM-DD-NNN` (date + zero-padded 3-digit daily counter), counting existing `docs/review/.scope/YYYY-MM-DD-NNN-scope.md` files for that date (the scope phase is the allocating phase, so its counter is the source of truth for the umbrella id).
 
-> **Distinct from a Work `review-id`.** When Review is invoked over a `/work` run (`input-shape: work-linked`), the Work skill's own `review-id` (`docs/plans/.work/.review/...`) **already exists**. The Review skill allocates its **own** `review-id` (`docs/plans/.review/...`) — the two skills produce independent artifacts and never share an id. The `work-id` is carried alongside in the Review artifacts for traceability and the work-index cross-link, but `review-id` ≠ Work `review-id`.
+> **Distinct from a Work `review-id`.** When Review is invoked over a `/work` run (`input-shape: work-linked`), the Work skill's own `review-id` (`docs/plans/.work/.review/...`) **already exists**. The Review skill allocates its **own** `review-id` (`docs/review/...`) — the two skills produce independent artifacts and never share an id. The `work-id` is carried alongside in the Review artifacts for traceability and the work-index cross-link, but `review-id` ≠ Work `review-id`.
+
+> **Persistence by mode.** The "Saved to" column and the directory-listing algorithm below apply **only in `detailed` mode**. In `smart`/`autopilot` mode phase artifacts are not written, so no directory is listed: Allocate `review-id` NNN by counting today's files in `docs/review/.report/` (+1); `scope-id`/`prepare-id`/`analyze-id` reuse that NNN as in-memory labels. See [Artifact Persistence](interaction-mode-propagation.md#artifact-persistence).
 
 ## Algorithm (new phase artifact)
 
 ```
 1. Get the current date in UTC (e.g., 2026-08-08)
 2. List existing files for today in the phase's save directory:
-   - scope    -> docs/plans/.review/.scope/     matching YYYY-MM-DD-*-scope.md
-   - prepare  -> docs/plans/.review/.prepare/   matching YYYY-MM-DD-*-prepare.md
-   - analyze  -> docs/plans/.review/.analyze/   matching YYYY-MM-DD-*-analyze.md
-   - report   -> docs/plans/.review/.report/    matching YYYY-MM-DD-*-report.md
+   - scope    -> docs/review/.scope/     matching YYYY-MM-DD-*-scope.md
+   - prepare  -> docs/review/.prepare/   matching YYYY-MM-DD-*-prepare.md
+   - analyze  -> docs/review/.analyze/   matching YYYY-MM-DD-*-analyze.md
+   - report   -> docs/review/.report/    matching YYYY-MM-DD-*-report.md
 3. NNN = (count + 1), zero-padded to 3 digits (001, 002, ..., 010, ...)
 4. id = "<date>-<NNN>-<phase>"
 ```
@@ -50,7 +52,7 @@ Allocated **only** in Scope Step 2:
 
 ```
 1. Get the current date in UTC
-2. List existing files under docs/plans/.review/.scope/ matching YYYY-MM-DD-NNN-scope.md for that date
+2. List existing files under docs/review/.scope/ matching YYYY-MM-DD-NNN-scope.md for that date
 3. NNN = (highest existing NNN for that date), zero-padded to 3 digits
    - if none exist for that date, start at 001
 4. review-id = "<date>-<NNN>"  (the same NNN as the scope-id being allocated)
@@ -61,7 +63,7 @@ Because `review-id` reuses the scope counter's NNN, the umbrella id and the `sco
 
 ## 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 Report phase's registry row in `docs/plans/.review/index.md` and the `## Review Report — <report-id>` block in the work index are likewise idempotent on `report-id` (overwritten, never duplicated).
+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 Report phase's registry row in `docs/review/index.md` and the `## Review Report — <report-id>` block in the work index are likewise idempotent on `report-id` (overwritten, never duplicated).
 
 ## Error Handling
 
@@ -69,12 +71,12 @@ When the user picks **Edit & Retry** at a phase confirmation, **reuse the origin
 | ----------------------------------------------- | -------------------------------------------- |
 | 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/plans/.review/` missing                   | Create it (Pre-Flight already creates; idempotent) |
+| `docs/review/` missing                   | Create it (Pre-Flight already creates; idempotent) |
 | Write permission denied                         | Log error; ask the user; retry once          |
 
 ## Notes
 
-- IDs reuse the daily-counter algorithm for cross-skill consistency with `/plan` and `/work`; the Review skill's counters are independent from those skills (separate save directories under `docs/plans/.review/` vs `.work/`).
+- IDs reuse the daily-counter algorithm for cross-skill consistency with `/plan` and `/work`; the Review skill's counters are independent from those skills (separate save directories under `docs/review/` vs `.work/`).
 - `review-id` carries through every artifact (`scope-id` artifacts record it; Prepare/Analyze/Report inherit it), so cross-phase chaining is `scope-id → prepare-id → analyze-id → report-id`, all sharing one `review-id` (see [error-handling.md](error-handling.md) "Cross-Phase Consistency Checks").
 - For work-linked input, `work-id` is **additionally** carried (inherited from the Review Input Artifact), distinct from `review-id`, for the registry cross-link only.
 - 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/review/references/interaction-mode-propagation.md

@@ -77,4 +77,24 @@ Review deliberately has **no** `executionMode`:
 | 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     |
+| Timeout/connection lost     | Pause; ask user to retry or abort     |
+
+## Artifact Persistence
+
+Phase artifacts (Scope, Prepare, Analyze) are **handoff data between phases**, not deliverables. Whether they are written to disk depends on `interactionMode`:
+
+| Mode          | Phase artifacts (`docs/review/.scope/`, `.prepare/`, `.analyze/`)          | Phase handoff                                  |
+| ------------- | ---------------------------------------- | ---------------------------------------------- |
+| **Detailed**  | Written to the hidden directories (audit trail; creating the directory on first use) | Artifact is written, shown, then passed on     |
+| **Smart**     | **Not written**                          | Artifact is held in context and passed in-memory to the next phase |
+| **Autopilot** | **Not written**                          | Artifact is held in context and passed in-memory to the next phase |
+
+**Always written, in every mode:** the Review Report in `docs/review/.report/<report-id>.md` and its row in `docs/review/index.md` (a cross-skill handoff read by `/learn`).
+
+**Rules:**
+
+- The artifact schema, quality gates, cross-phase ID checks, and pause triggers are **unchanged** — only the disk write is skipped. Validate and pass the in-memory artifact exactly as you would the file.
+- Never create the hidden directories in `smart`/`autopilot`; no placeholder or empty files.
+- **ID allocation without files:** Allocate `review-id` NNN by counting today's files in `docs/review/.report/` (+1); `scope-id`/`prepare-id`/`analyze-id` reuse that NNN as in-memory labels.
+- If the user switches to `detailed` mid-run, write the artifacts produced so far, then continue writing.
+- Because nothing is on disk, **Edit & Retry** reuses the in-memory artifact and its id (no file to overwrite).