arreio 1.0.5 → 1.2.0

package/skills/learn/references/templates/artifacts/learn-input.md

@@ -95,6 +95,6 @@ maintain:
 
 ## Notes
 
-- The Orchestrator's Pre-Flight Check ensures `docs/learn/`, `docs/plans/.learn/.{capture,refine,index,maintain}/` exist, and seeds `docs/learn/index.md` if missing (self-healing via `mkdir -p`), before routing the artifact.
+- The Orchestrator's Pre-Flight Check ensures `docs/learn/`, `docs/learn/.{capture,refine,index,maintain}/` exist, and seeds `docs/learn/index.md` if missing (self-healing via `mkdir -p`), before routing the artifact.
 - `interactionMode` flows from this artifact into every downstream artifact (Capture → Refine → Index for authoring; straight to Maintain otherwise); the orchestrator quality gate #2 cross-checks it is identical across the authoring chain (Maintain carries it standalone).
 - The shape **determines the route**, not just the allocation: a `maintain` shape never reaches Capture, Refine, or Index. The phase ids reflect this — `maintain-id` is standalone (no `learn-id` umbrella) per [id-generation.md](../../id-generation.md).

package/skills/learn/references/templates/artifacts/maintain-log.md

@@ -56,7 +56,7 @@ summary:                                    # a one-line human-readable summary
   "<N> entries migrated; <M> merged; <R> normalized, <F> flagged; <P> pruned; <I> indexed"
 ```
 
-Also save the Maintain Log Artifact to `docs/plans/.learn/.maintain/<maintain-id>.md`.
+In `detailed` mode only, also save the Maintain Log Artifact to `docs/learn/.maintain/<maintain-id>.md`. In `smart`/`autopilot` mode, do not write it; pass it to the next phase in context.
 
 ## Validation Rules
 

package/skills/learn/references/templates/artifacts/refined-entry.md

@@ -58,7 +58,7 @@ lineage:                                        # set ONLY when resolution == me
 source-candidate: <carried from Capture> | null
 ```
 
-Also save the Refined Entry Artifact to `docs/plans/.learn/.refine/<refine-id>.md`.
+In `detailed` mode only, also save the Refined Entry Artifact to `docs/learn/.refine/<refine-id>.md`. In `smart`/`autopilot` mode, do not write it; pass it to the next phase in context.
 
 ## Validation Rules
 

package/skills/plan/SKILL.md

@@ -10,7 +10,14 @@ Orchestrates a deterministic pipeline of micro-skills: `Scope -> Research -> Des
 
 ## Skill Invocation
 
-This skill is invoked by prompting `/plan <task description>`. This skill will run the planning pipeline, producing a final plan artifact and optionally a set of task artifacts, acting as the Orchestrator.
+This skill is invoked by prompting `/plan [--deep] <task description>`. This skill will run the planning pipeline, producing a final plan artifact and optionally a set of task artifacts, acting as the Orchestrator.
+
+**`--deep` flag (optional):** forces the **Deep** plan tier in any interaction mode, including Autopilot, bypassing the tier question and the complexity-based choice.
+
+- **Parsing:** `--deep` counts only as a standalone token at the **start or end** of the input. Remove it from the task description, then set `force_deep: true` in the context object. Anywhere else (e.g., inside a sentence or quoted text) it is plain text and `force_deep` stays `false`.
+- If nothing remains after removing the flag, ask: "What would you like to plan? Describe the task or project."
+- The flag does not change the interaction-mode question, `complexity`, or `tier_recommended`; it only sets `tier: deep`. The override stays auditable (`tier_recommended` keeps the algorithm's result).
+- Other `--word` tokens are not flags of this skill; leave them in the description.
 
 ## Interaction Method
 
@@ -27,8 +34,13 @@ Store in the context object:
 
 ```yaml
 interactionMode: detailed | smart | autopilot
+force_deep: true | false   # true only when `--deep` was passed; default false
 ```
 
+`force_deep` lives in the Orchestrator context (not in artifact files). Pass it to **Design** (to produce the material a Deep plan needs) and **Generate** (to select the tier).
+
+**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 `research`, `design`, and `generate` artifacts; each downstream phase reads it to adjust confirmation behaviour (detailed = pause every transition; autopilot = run all; smart = pause only on HIGH-risk).
 
 ## Orchestration Implementation
@@ -47,6 +59,7 @@ Before starting the planning pipeline, the orchestrator verifies that required f
 
 - `docs/plans/` — must exist for saving final plan
 - `docs/tasks/` — must exist if task generation is enabled
+- `docs/plans/.scope/`, `.research/`, `.design/` — **`detailed` mode only**, for saving the intermediate phase artifacts; do not create them in `smart`/`autopilot`
 
 **Self-Healing:** If missing, the orchestrator automatically creates these folders. This allows the plan skill to run even if `arreio-init` wasn't explicitly run.
 
@@ -69,7 +82,7 @@ Between phases, the orchestrator validates the output artifact before passing it
 1. **Schema validation** — required fields present and well-formed (see [error-handling.md](references/error-handling.md) for the per-type field list).
 2. **Cross-phase consistency** — IDs (`scope-id`, `research-id`, `design-id`, `plan-id`) match the upstream artifacts; `interactionMode` is identical across artifacts.
 3. **Status check** — the artifact's `status` is `complete` (not `pending` or `failed`).
-4. **Tier/complexity coherence** (after Design) — the `tier_recommended` is consistent with `complexity` and `risk_level` per [plan-tier-selection.md](references/plan-tier-selection.md).
+4. **Tier/complexity coherence** (after Design) — `tier_recommended` equals `recommend_tier(complexity, risk_level)` per [plan-tier-selection.md](references/plan-tier-selection.md). Recompute it; do not trust the value blindly. A `HIGH`/`VERY_HIGH` complexity must yield `deep`.
 
 If a gate fails, the orchestrator returns to the producing phase with the error context (per the recovery workflow in [error-handling.md](references/error-handling.md)).
 
@@ -84,13 +97,13 @@ Each skill module is responsible for registering its own outputs:
 
 **Who updates what:**
 
-- **Generate phase:** Creates `docs/plans/index.md` if missing; appends new plan entry with timestamp and link
+- **Generate phase:** Creates `docs/plans/index.md` if missing; inserts the new plan row (or replaces the row with the same `plan-id`)
 - **Tasks phase:** Creates `docs/tasks/<plan-id>/` folder and `docs/tasks/<plan-id>/index.md` if missing; populates with task file links and metadata
 
 ### FINAL OUTPUT
 
 - **Plan file:** Saved to `docs/plans/YYYY-MM-DD-NNN-<kebab-case-name>.md`
-  - **Registration:** Generate phase appends an entry to `docs/plans/index.md` linking the new plan
+  - **Registration:** Generate phase inserts or replaces the row in `docs/plans/index.md` linking the new plan
 - **Task files (optional):** Saved to `docs/tasks/<plan-id>/TASK-NNN-<kebab-case-name>.md`
   - **Registration:** Tasks phase creates `docs/tasks/<plan-id>/index.md` and registers task file links there
   - Ready for the Work skill to consume via `docs/tasks/<plan-id>/index.md`
@@ -113,6 +126,17 @@ The orchestrator and modules share these reference files:
 
 Artifact templates live in [references/templates/artifacts/](references/templates/artifacts/).
 
+## 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 an algorithm (`complexity`, `tier_recommended`, `tier`) must be evaluated with the real inputs. Example values in references 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 3/5 Design complete: complexity HIGH, tier_recommended deep") so the user can follow progress, even in Autopilot.
+6. **Honor write rules:** hidden phase artifacts only in `detailed` mode; the final plan, index row, and (if accepted) task files always.
+
 ## Core Principles
 
 - **Deterministic Pipeline:** Phases always execute in sequence (no agent switching, no fallback paths).
@@ -122,6 +146,7 @@ Artifact templates live in [references/templates/artifacts/](references/template
 - **Separate Planning from Execution:** NEVER simulate implementation during planning.
 - **Be Concrete:** Use specific files, components, and dependencies.
 - **Stay Portable:** Use repository-relative paths only.
+- **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.
 - **Interaction Mode Propagation:** `interactionMode` is read at the start of each subsequent phase and determines whether confirmation steps execute.
 - **Single Source of Truth:** This skill defines all its own rules; it does not depend on any external agent rule file.

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).