arreio 1.1.0 → 1.2.0

package/skills/plan/modules/design.md

@@ -22,6 +22,7 @@ Run the **[Step 0 verification](../references/error-handling.md)**. Required inp
 2. **Research Findings Artifact** with `research-id`, `Patterns Found`, `High-Risk Detection` (with `risk_level`), `Tech Stack`.
 3. `interactionMode` present (default to `smart` if missing; log warning).
 4. Cross-phase consistency: the research artifact's `scope-id` matches the scope output.
+5. `force_deep` (boolean from the Orchestrator context; default `false`). It never changes `complexity` or `tier_recommended`; it only raises the amount of material this phase must produce (Steps 4–5).
 
 ### Step 1: Approach Selection
 
@@ -90,6 +91,8 @@ Score the design across five dimensions (0–3 each) and compute the complexity
 2. Sum the scores (0–15).
 3. Map to complexity level: `TRIVIAL | LOW | MEDIUM | HIGH | VERY_HIGH`.
 4. Record all five scores, the total, and the complexity level in the Design Artifact.
+5. **Compute `tier_recommended`** by evaluating `recommend_tier(complexity, risk_level)` from [plan-tier-selection.md](../references/plan-tier-selection.md) with the actual values from steps 1–3 (complexity-driven default, then the risk floor). Apply the Anti-Default Rules there: `HIGH`/`VERY_HIGH` → `deep`, `MEDIUM` → `standard`, `TRIVIAL`/`LOW` → `fast`, raised only by risk. Do not ignore `risk_level`, and do not pick `standard` by default. `force_deep` and user preference do **not** affect this value.
+6. **If `force_deep` is true:** also draft rollout notes (feature flags, monitoring, data migration, rollback, performance baseline — or `Not applicable — <reason>` per item) and a cross-system integration map so Generate can fill the Deep sections from real content.
 
 ### Step 5: Alternative Approaches
 
@@ -97,7 +100,7 @@ Document the approaches considered but not selected, with rejection rationale.
 
 - **TRIVIAL / LOW complexity:** At least 1 alternative (may be brief).
 - **MEDIUM complexity:** At least 1 alternative with rationale.
-- **HIGH / VERY_HIGH complexity:** At least 2 alternatives with side-by-side rationale.
+- **HIGH / VERY_HIGH complexity, or `force_deep` is true:** At least 2 alternatives with side-by-side rationale.
 
 Format: `**[Approach Name]**: [Description] → **Rejected because:** [Rationale]`
 
@@ -113,7 +116,7 @@ Format: `**[Approach Name]**: [Description] → **Rejected because:** [Rationale
 1. **Assign a `design-id`** per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-design`, saved to `docs/plans/.design/`). Reuse it if the user later picks **Edit & Retry**.
 
 2. Produce a **Design Artifact** block (as markdown) following the schema in [design.md](../references/templates/artifacts/design.md).
-   - Include the generated `design-id`, inherited `scope-id` and `research-id`, `interactionMode`, `complexity`, and `tier_recommended` (derived from complexity per [plan-tier-selection.md](../references/plan-tier-selection.md)).
+   - Include the generated `design-id`, inherited `scope-id` and `research-id`, `interactionMode`, `complexity`, and `tier_recommended` (the value computed in Step 4.5 — never re-derive it from complexity alone).
 
 ### Step 7: Present, Confirm, and Save
 
@@ -128,13 +131,14 @@ 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/.design/<design-id>.md` (ensure `interactionMode`, `complexity`, and `tier_recommended` are included) and return it, with the `interactionMode` value, to the Orchestrator for the transition to Phase 4 (Generate).
+Then, **in `detailed` mode only**, save the artifact to `docs/plans/.design/<design-id>.md` (ensure `interactionMode`, `complexity`, and `tier_recommended` are included) and return it, with the `interactionMode` value, to the Orchestrator for the transition to Phase 4 (Generate). 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: Design Artifact
 
 - Verify that the Design Artifact is complete and valid, containing all required fields: `design-id`, `scope-id`, `research-id`, `interactionMode`, `complexity`, `tier_recommended`, Approach, High-Level Technical Design, Implementation Units (each with Acceptance Criteria), Complexity Assessment, Alternative Approaches, Related Learnings, and Learning Gaps.
 - Verify that the `complexity` value matches the threshold mapping from the five dimension scores.
-- Verify that `tier_recommended` is consistent with the complexity and risk level per [plan-tier-selection.md](../references/plan-tier-selection.md).
-- Verify that the artifact is saved to `docs/plans/.design/<design-id>.md` for future reference or reuse.
+- Verify that `tier_recommended` equals `recommend_tier(complexity, risk_level)` per [plan-tier-selection.md](../references/plan-tier-selection.md) (e.g., `complexity: HIGH` → `deep`, not `standard`).
+- Verify that, when `force_deep` is true, the artifact contains ≥ 2 alternatives and the rollout/integration drafts from Step 4.6.
+- Verify that, in `detailed` mode, the artifact is saved to `docs/plans/.design/<design-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 design artifact to `generate` (Phase 4) for final plan generation.

package/skills/plan/modules/generate.md

@@ -30,19 +30,18 @@ Select the plan tier based on complexity, risk, and user preference. For the ful
 1. **Read inputs:**
    - `complexity` from the Design Artifact
    - `risk_level` from the Research Findings (carried via the Design Artifact's complexity assessment)
-   - `tier_recommended` from the Design Artifact (the algorithm's suggestion)
+   - `force_deep` from the Orchestrator context (`--deep` flag; default `false`)
+   - `tier_recommended` from the Design Artifact — then **recompute** `recommend_tier(complexity, risk_level)`; if they differ, use the recomputed value and log a warning.
 
 2. **Determine user preference:**
-   - In **Detailed** mode: Ask the user which tier they want, presenting the recommendation. Options: `Fast`, `Standard`, `Deep`, `Auto`.
-   - In **Smart** mode: Auto-select, unless a pause trigger fires (Deep tier, preference conflicts with risk floor, or CRITICAL risk). If paused, ask the user.
+   - If `force_deep` is true: set `tier = deep`, announce "Deep plan forced by `--deep`", and **skip the tier question in every mode**.
+   - In **Detailed** mode: Ask the user which tier they want using the prompt in [plan-tier-selection.md](../references/plan-tier-selection.md#asking-the-user-for-preference), filled with the computed complexity, risk level, and `tier_recommended`. Options: `Fast`, `Standard`, `Deep`, `Auto`.
+   - In **Smart** mode: Set `user_preference = auto`, unless a pause trigger fires (Deep tier without `force_deep`, preference conflicts with risk floor, or CRITICAL risk). If paused, ask the user.
    - In **Autopilot** mode: Set `user_preference = auto`; never ask.
 
-3. **Apply the selection algorithm** (see [plan-tier-selection.md](../references/plan-tier-selection.md)):
-   - Start from the complexity-driven default tier.
-   - Upgrade if risk warrants it (respect the risk floor).
-   - Honor user preference unless it violates the risk floor.
+3. **Evaluate `select_tier(...)`** from [plan-tier-selection.md](../references/plan-tier-selection.md) with the real values. `auto` resolves to `tier_recommended` — never to `Standard` by default. Honor an explicit preference unless it is below the risk floor.
 
-4. **Record the selected tier** as `tier` and the algorithm's recommendation as `tier_recommended` (for audit when the user overrides).
+4. **Record the selected tier** as `tier` and the algorithm's recommendation as `tier_recommended` (for audit when the user overrides or `--deep` is used).
 
 ### Step 2: Plan Rendering
 
@@ -100,6 +99,7 @@ Render the final plan from the [Final Plan template](../references/templates/art
 5. **Build Operational / Rollout Notes** (Standard/Deep only) from the Design's rollout units:
    - Feature flags, monitoring, data migration, rollback plan, performance baseline
    - Skip the section entirely if not applicable (Fast tier, or no rollout units)
+   - **Deep tier:** every required item (feature flags, monitoring, data migration, rollback plan, performance baseline) and the cross-system integration map must appear; write `Not applicable — <reason>` for items that truly do not apply (typical for `--deep` on a small change). Never invent content.
 
 6. **Right-size:** Per Plan Skill core principles — small tasks → short plans; complex work → more structure. Do not pad a Fast plan with empty sections; do not omit required sections from a Deep plan.
 
@@ -112,7 +112,7 @@ Render the final plan from the [Final Plan template](../references/templates/art
 
 Apply the **[phase confirmation behavior](../references/interaction-mode-propagation.md)** for the current `interactionMode`, using these generate-specific **Smart pause triggers**:
 
-- The selected tier is `Deep`, or
+- The selected tier is `Deep` and `force_deep` is false, or
 - The user's tier preference conflicts with the risk floor, or
 - Research reported CRITICAL risk (Security or Payments).
 

package/skills/plan/modules/research.md

@@ -111,12 +111,12 @@ 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).
 
-On any proceed/skip path: save the artifact to `docs/plans/.research/<research-id>.md` (ensure `interactionMode` is included), then return the artifact and `interactionMode` to the Orchestrator for the transition to Phase 3 (Design).
+On any proceed/skip path: in `detailed` mode only, save the artifact to `docs/plans/.research/<research-id>.md` (ensure `interactionMode` is included), then return the artifact and `interactionMode` to the Orchestrator for the transition to Phase 3 (Design). 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: Research Findings Artifact
 
 - Verify that the Research Findings Artifact is complete and valid, containing all required fields, and it accurately reflects the user's input and any existing plans, learnings, or requirements found.
 - Verify that the `interactionMode` value is set correctly based on the user's selection in the Orchestrator skill.
-- Verify that the artifact is saved to `docs/plans/.research/<research-id>.md` for future reference or reuse.
+- Verify that, in `detailed` mode, the artifact is saved to `docs/plans/.research/<research-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 research findings to `design` (Phase 3) for the design phase.

package/skills/plan/modules/scope.md

@@ -110,12 +110,12 @@ 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/.scope/<scope-id>.md` (ensure `interactionMode` is included) and return it, with the `interactionMode` value, to the Orchestrator for the transition to Phase 2 (Research).
+Then, **in `detailed` mode only**, save the artifact to `docs/plans/.scope/<scope-id>.md` (ensure `interactionMode` is included) and return it, with the `interactionMode` value, to the Orchestrator for the transition to Phase 2 (Research). 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: Scoped Context Artifact
 
 - Verify that the Scoped Context Artifact is complete and valid, containing all required fields, and it accurately reflects the user's input and any existing plans, learnings, or requirements found.
 - Verify that the `interactionMode` value is set correctly based on the user's selection in the Orchestrator skill.
-- Verify that the artifact is saved to `docs/plans/.scope/<scope-id>.md` for future reference or reuse.
+- Verify that, in `detailed` mode, the artifact is saved to `docs/plans/.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 scoped context to `research` (Phase 2) for the research phase.

package/skills/plan/references/design-complexity-assessment.md

@@ -2,8 +2,8 @@
 title: Design Complexity Assessment
 description: Reference for the Design phase. Defines the complexity scoring algorithm across five dimensions, the heuristics for assigning complexity levels, and how complexity maps to interaction-mode pause behavior.
 type: reference
-version: 1.1
-timestamp: "2026-08-07"
+version: 1.2
+timestamp: "2026-10-01"
 ---
 
 # Design Complexity Assessment
@@ -22,15 +22,22 @@ Score each dimension from 0 to 3, then sum for a total complexity score (0–15)
 | ----------------------- | ----------------------- | ----------------------- | --------------------------------- | --------------------------------- |
 | **Scope Breadth**       | Single file             | 2–3 files, one module   | Multiple modules                  | Cross-system / cross-repo         |
 | **Integration Surface** | No new integrations     | One new internal API    | Multiple internal or one external | Multiple external / third-party   |
-| **Risk Level**          | LOW (from research)     | MEDIUM (single area)    | HIGH (single area)                | HIGH (multiple areas) or CRITICAL |
+| **Risk Level**          | LOW (from research)     | MEDIUM (from research)  | HIGH (from research)              | CRITICAL (from research)          |
 | **Novelty**             | Existing pattern reused | Minor variation         | New pattern in familiar domain    | New pattern in unfamiliar domain  |
 | **Data / Migration**    | No data changes         | Additive, backward-safe | Schema change with migration path | Destructive or no rollback path   |
 
+### Scoring Procedure (follow in order)
+
+1. For each of the five dimensions, write one line of **evidence** (file count, named integrations, matched pattern, migration note) before choosing the score. A score without evidence is not allowed.
+2. Pick the **lowest score whose column matches the evidence**; if evidence sits between two columns, take the higher (see Notes).
+3. Add the five scores, then apply the threshold mapping below literally. Do not adjust the level by "feel".
+4. Do not default to `MEDIUM`: a 1-file tweak is `TRIVIAL`/`LOW`, a cross-module change with an external service is `HIGH`. Let the arithmetic decide.
+
 ### Dimension Definitions
 
 - **Scope Breadth** — How many files, modules, or systems the change touches. Read from the Implementation Units' `Files` lists.
 - **Integration Surface** — Number and kind of APIs/services the solution must connect to. Pull from the Research Findings `Patterns Found` and `Tech Stack`.
-- **Risk Level** — Inherited from the Research phase `High-Risk Detection`. Do not re-score; copy the value.
+- **Risk Level** — Inherited from the Research phase `High-Risk Detection`. Do not re-score: map the inherited level to its score (`LOW`=0, `MEDIUM`=1, `HIGH`=2, `CRITICAL`=3). The artifact records the level name; the score is used only in the sum.
 - **Novelty** — Whether the approach reuses an existing local pattern or introduces a new one. Compare the chosen approach against `Patterns Found` confidence levels.
 - **Data / Migration** — Whether data schemas change and whether the change is reversible. Read from the Design's `Operational / Rollout Notes` draft.
 
@@ -85,7 +92,7 @@ Complexity feeds into tier selection in the Generate phase:
 | MEDIUM           | Standard     | Full template; phased units; risk table    |
 | HIGH / VERY_HIGH | Deep         | Full template + alternatives + rollout ops |
 
-See [plan-tier-selection.md](plan-tier-selection.md) for the complete tier-selection algorithm, including how complexity combines with risk and user preference.
+The table is the **complexity-only** default. Design then applies the risk floor with `recommend_tier(complexity, risk_level)` and writes the result as `tier_recommended`. See [plan-tier-selection.md](plan-tier-selection.md) for the complete algorithm, including user preference and the `--deep` override (which does not change `complexity` or `tier_recommended`).
 
 ## Worked Example
 
@@ -95,18 +102,20 @@ See [plan-tier-selection.md](plan-tier-selection.md) for the complete tier-selec
 | ------------------- | ----- | ------------------------------------------------- |
 | Scope Breadth       | 2     | Multiple modules: middleware, store, client       |
 | Integration Surface | 2     | One external system (Redis)                       |
-| Risk Level          | 2     | HIGH (single area: sessions/auth)                 |
+| Risk Level          | 2     | HIGH (inherited from research)                 |
 | Novelty             | 1     | Redis is new to the codebase but pattern is known |
 | Data / Migration    | 1     | Additive; sessions expire naturally               |
 | **Total**           | **8** | **Complexity: HIGH**                              |
 
+Tier: complexity HIGH → Deep; risk HIGH does not lower it → `tier_recommended: deep`.
+
 Result: In Smart mode, this would **not** pause (HIGH, not VERY_HIGH) unless the secondary flags trigger (e.g., 3+ learning gaps).
 
 ## Error Handling
 
 | Scenario                                                         | Recovery                                 |
 | ---------------------------------------------------------------- | ---------------------------------------- |
-| Risk level missing from Research artifact                        | Default to MEDIUM (score 2); log warning |
+| Risk level missing from Research artifact                        | Default to MEDIUM (score 1); log warning |
 | Implementation Units not yet drafted                             | Defer scoring until units exist          |
 | Two dimensions conflict (e.g., LOW risk + destructive migration) | Use the higher score; log warning        |
 | Score lands exactly on a threshold (e.g., 7)                     | Round up to the higher level (HIGH)      |

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

@@ -145,6 +145,7 @@ In addition to per-phase verification, the Orchestrator should verify consistenc
 | `scope-id` in design artifact matches scope output   | Reject design; re-run from research         |
 | `plan-id` references the correct design artifact     | Reject generate; re-run from design         |
 | `interactionMode` is identical across all artifacts  | Log warning; use earliest non-default value |
+| `tier_recommended` equals `recommend_tier(complexity, risk_level)` | Recompute; use the recomputed value; log warning |
 
 ## Notes
 

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

@@ -12,7 +12,7 @@ Shared ID algorithm for the `scope`, `research`, `design`, and `generate` 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/.scope/<id>.md`      |
 | Research | `YYYY-MM-DD-NNN-research`            | `docs/plans/.research/<id>.md`  |
@@ -21,6 +21,8 @@ Shared ID algorithm for the `scope`, `research`, `design`, and `generate` phases
 
 `<kebab-name>` is the plan title in lowercase-hyphen form (no stopwords).
 
+> **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 the plan-id `YYYY-MM-DD-NNN` once at Scope by counting today's final plan files in `docs/plans/` (excluding hidden dirs); every phase id is `<plan-id>-<phase>` (e.g. `2026-09-02-001-scope`). See [Artifact Persistence](interaction-mode-propagation.md#artifact-persistence).
+
 ## Algorithm (new artifact)
 
 ```

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

@@ -25,11 +25,15 @@ Reference for how `interactionMode` propagates through the Plan pipeline (Scope
 | **Scope**    | Present artifact; ask Proceed/Edit/Abort         | Auto-proceed; pause if 3+ learning gaps, non-software domain, or conflicting requirements              | Auto-proceed                      |
 | **Research** | Show findings; ask Proceed/Edit/Abort           | Auto-proceed; pause if HIGH/CRITICAL risk with <3 patterns, or zero patterns found                    | Auto-proceed                      |
 | **Design**   | Show units; ask Proceed/Edit/Abort              | Auto-proceed; pause if VERY_HIGH complexity, HIGH risk + <3 patterns, 3+ scope gaps, or Novelty=3      | Auto-proceed                      |
-| **Generate** | Show plan; ask Proceed/Edit/Skip/Abort          | Auto-proceed; pause if tier=Deep, tier preference conflicts with risk floor, or CRITICAL risk          | Auto-proceed                      |
+| **Generate** | Show plan; ask Proceed/Edit/Skip/Abort          | Auto-proceed; pause if tier=Deep (not when forced by `--deep`), tier preference conflicts with risk floor, or CRITICAL risk          | Auto-proceed                      |
 | **Tasks**    | Ask Create/Review/No (full file content shown)  | Ask Create/Review/No (summary shown)                                                                   | Ask Create/Review/No (always asks) |
 
 **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).
 
+## `--deep` Flag
+
+`/plan --deep <task>` sets `force_deep: true` in the Orchestrator context. It is orthogonal to `interactionMode`: in every mode the Generate phase selects the Deep tier without asking about tier. It does not add pauses and removes the Smart-mode "tier is Deep" pause. See [plan-tier-selection.md](plan-tier-selection.md#deep-override---deep).
+
 ## Artifact Schema
 
 All phase artifacts (Scope 1-4) include:
@@ -73,3 +77,23 @@ status: pending | complete | failed
 | Invalid mode value          | Reject; re-prompt Orchestrator        |
 | Artifact missing mode field | Assume "smart"; log warning; continue |
 | Timeout/connection lost     | Pause; ask user to retry or abort     |
+
+## Artifact Persistence
+
+Phase artifacts (Scope, Research, Design) are **handoff data between phases**, not deliverables. Whether they are written to disk depends on `interactionMode`:
+
+| Mode          | Phase artifacts (`docs/plans/.scope/`, `.research/`, `.design/`)          | 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 final plan in `docs/plans/` (+ `docs/plans/index.md`) and any task files in `docs/tasks/<plan-id>/`.
+
+**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 the plan-id `YYYY-MM-DD-NNN` once at Scope by counting today's final plan files in `docs/plans/` (excluding hidden dirs); every phase id is `<plan-id>-<phase>` (e.g. `2026-09-02-001-scope`).
+- 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).

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,7 +60,8 @@ Each phase runs sequentially: the orchestrator calls the phase module, receives
 
 Before starting the review pipeline, the orchestrator verifies that required folders exist:
 
-- `docs/review/.scope/`, `docs/review/.prepare/`, `docs/review/.analyze/`, `docs/review/.report/` — must exist for saving the four phase artifacts
+- `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,9 +76,9 @@ 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/review/.scope/<id>.md`   |
-| 2     | [Prepare](modules/prepare.md) | [Review kit](references/templates/artifacts/review-kit.md)       | `docs/review/.prepare/<id>.md` |
-| 3     | [Analyze](modules/analyze.md) | [Findings](references/templates/artifacts/findings.md)           | `docs/review/.analyze/<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
@@ -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

@@ -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/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/review/.analyze/<analyze-id>.md` (ensure `intera
 - 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/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.