arreio 1.1.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (45) hide show
  1. package/README.md +55 -2
  2. package/package.json +1 -1
  3. package/skills/arreio-init/SKILL.md +19 -24
  4. package/skills/learn/SKILL.md +20 -6
  5. package/skills/learn/modules/capture.md +3 -3
  6. package/skills/learn/modules/index.md +2 -2
  7. package/skills/learn/modules/maintain.md +2 -2
  8. package/skills/learn/modules/refine.md +2 -2
  9. package/skills/learn/references/id-generation.md +3 -1
  10. package/skills/learn/references/interaction-mode-propagation.md +21 -1
  11. package/skills/learn/references/templates/artifacts/captured-entry.md +1 -1
  12. package/skills/learn/references/templates/artifacts/index-update.md +1 -1
  13. package/skills/learn/references/templates/artifacts/maintain-log.md +1 -1
  14. package/skills/learn/references/templates/artifacts/refined-entry.md +1 -1
  15. package/skills/plan/SKILL.md +29 -4
  16. package/skills/plan/modules/design.md +9 -5
  17. package/skills/plan/modules/generate.md +9 -9
  18. package/skills/plan/modules/research.md +2 -2
  19. package/skills/plan/modules/scope.md +2 -2
  20. package/skills/plan/references/design-complexity-assessment.md +16 -7
  21. package/skills/plan/references/error-handling.md +1 -0
  22. package/skills/plan/references/id-generation.md +3 -1
  23. package/skills/plan/references/interaction-mode-propagation.md +25 -1
  24. package/skills/plan/references/plan-tier-selection.md +95 -48
  25. package/skills/plan/references/templates/artifacts/design.md +1 -1
  26. package/skills/plan/references/templates/artifacts/scoped-context.md +1 -1
  27. package/skills/review/SKILL.md +19 -4
  28. package/skills/review/modules/analyze.md +2 -2
  29. package/skills/review/modules/prepare.md +2 -2
  30. package/skills/review/modules/scope.md +3 -3
  31. package/skills/review/references/id-generation.md +3 -1
  32. package/skills/review/references/interaction-mode-propagation.md +21 -1
  33. package/skills/review/references/templates/artifacts/findings.md +1 -1
  34. package/skills/review/references/templates/artifacts/review-kit.md +1 -1
  35. package/skills/review/references/templates/artifacts/review-scope.md +1 -1
  36. package/skills/work/SKILL.md +19 -4
  37. package/skills/work/modules/execute.md +2 -2
  38. package/skills/work/modules/prepare.md +3 -3
  39. package/skills/work/modules/triage.md +2 -2
  40. package/skills/work/references/execution-mode-selection.md +21 -2
  41. package/skills/work/references/id-generation.md +3 -1
  42. package/skills/work/references/interaction-mode-propagation.md +21 -1
  43. package/skills/work/references/templates/artifacts/execution-log.md +1 -1
  44. package/skills/work/references/templates/artifacts/execution-plan.md +1 -1
  45. package/skills/work/references/templates/artifacts/work-manifest.md +1 -1
@@ -90,7 +90,7 @@ Apply the **[phase confirmation behavior](../references/interaction-mode-propaga
90
90
  - **Smart:** pause only when a pause trigger above is true; otherwise auto-proceed.
91
91
  - **Autopilot:** auto-proceed (no confirmation).
92
92
 
93
- Then 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).
93
+ 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)).
94
94
 
95
95
  ## Output: Review Kit Artifact
96
96
 
@@ -98,6 +98,6 @@ Then save the artifact to `docs/review/.prepare/<prepare-id>.md` (ensure `intera
98
98
  - Verify that every `required` file has a diff entry (or is recorded as deleted / `current-contents`) and that `context` is separated from `required`.
99
99
  - Verify that `test-context` records covering tests per changed file and whether the change ships its own tests.
100
100
  - Verify that `requirements-source: none` propagated as `spec: none` (so Analyze skips the requirements-vs-scope-creep category rather than guessing).
101
- - Verify that the artifact is saved to `docs/review/.prepare/<prepare-id>.md`.
101
+ - 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.
102
102
 
103
103
  > Pass the Review Kit to `analyze` (Phase 3) for the categorized, severity-graded review of the diffs.
@@ -89,7 +89,7 @@ Search `docs/learn/index.md` for entries relevant to the review domains (the cha
89
89
 
90
90
  ### Step 6: Allocate review-id and Generate the Review Scope Artifact
91
91
 
92
- 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. 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).
92
+ 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).
93
93
 
94
94
  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**.
95
95
 
@@ -113,7 +113,7 @@ Apply the **[phase confirmation behavior](../references/interaction-mode-propaga
113
113
  - **Smart:** pause only when a pause trigger above is true; otherwise auto-proceed.
114
114
  - **Autopilot:** auto-proceed (no confirmation).
115
115
 
116
- Then 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).
116
+ 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)).
117
117
 
118
118
  ## Output: Review Scope Artifact
119
119
 
@@ -121,6 +121,6 @@ Then save the artifact to `docs/review/.scope/<scope-id>.md` (ensure `interactio
121
121
  - Verify that the change boundary is in **dependency-safe** form: `required` files are repository-relative and carry a status; `context` is separated from `required`.
122
122
  - Verify that `review-id` was allocated (scope is the allocating phase) and that `work-id` is carried for work-linked input.
123
123
  - 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).
124
- - Verify that the artifact is saved to `docs/review/.scope/<scope-id>.md`.
124
+ - 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.
125
125
 
126
126
  > Pass the Review Scope to `prepare` (Phase 2) to gather the diffs, spec content, test context, and tool inventory.
@@ -12,7 +12,7 @@ Shared ID algorithm for the `scope`, `prepare`, `analyze`, and `report` phases,
12
12
 
13
13
  ## ID Format by Phase
14
14
 
15
- | Phase | ID format | Saved to |
15
+ | Phase | ID format | Saved to (detailed only) |
16
16
  | -------- | ----------------------------------- | ----------------------------------- |
17
17
  | Scope | `YYYY-MM-DD-NNN-scope` | `docs/review/.scope/<id>.md` |
18
18
  | Prepare | `YYYY-MM-DD-NNN-prepare` | `docs/review/.prepare/<id>.md` |
@@ -29,6 +29,8 @@ The `review-id` is the umbrella key that ties all four phase artifacts together
29
29
 
30
30
  > **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`.
31
31
 
32
+ > **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).
33
+
32
34
  ## Algorithm (new phase artifact)
33
35
 
34
36
  ```
@@ -77,4 +77,24 @@ Review deliberately has **no** `executionMode`:
77
77
  | Invalid mode value | Reject; re-prompt Orchestrator |
78
78
  | Artifact missing mode field | Assume "smart"; log warning; continue |
79
79
  | User selects "Abort" | Stop immediately; inform Orchestrator |
80
- | Timeout/connection lost | Pause; ask user to retry or abort |
80
+ | Timeout/connection lost | Pause; ask user to retry or abort |
81
+
82
+ ## Artifact Persistence
83
+
84
+ Phase artifacts (Scope, Prepare, Analyze) are **handoff data between phases**, not deliverables. Whether they are written to disk depends on `interactionMode`:
85
+
86
+ | Mode | Phase artifacts (`docs/review/.scope/`, `.prepare/`, `.analyze/`) | Phase handoff |
87
+ | ------------- | ---------------------------------------- | ---------------------------------------------- |
88
+ | **Detailed** | Written to the hidden directories (audit trail; creating the directory on first use) | Artifact is written, shown, then passed on |
89
+ | **Smart** | **Not written** | Artifact is held in context and passed in-memory to the next phase |
90
+ | **Autopilot** | **Not written** | Artifact is held in context and passed in-memory to the next phase |
91
+
92
+ **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`).
93
+
94
+ **Rules:**
95
+
96
+ - 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.
97
+ - Never create the hidden directories in `smart`/`autopilot`; no placeholder or empty files.
98
+ - **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.
99
+ - If the user switches to `detailed` mid-run, write the artifacts produced so far, then continue writing.
100
+ - Because nothing is on disk, **Edit & Retry** reuses the in-memory artifact and its id (no file to overwrite).
@@ -53,7 +53,7 @@ scope-creep-ran: true | "skipped (no requirements)" # false only via the skipp
53
53
  work-id: YYYY-MM-DD-NNN | null # work-linked only; null otherwise
54
54
  ```
55
55
 
56
- Also save the Findings to `docs/review/.analyze/<analyze-id>.md`.
56
+ In `detailed` mode only, also save the Findings to `docs/review/.analyze/<analyze-id>.md`. In `smart`/`autopilot` mode, do not write it; pass it to the next phase in context.
57
57
 
58
58
  ## Validation Rules
59
59
 
@@ -60,7 +60,7 @@ tool-inventory:
60
60
  work-id: YYYY-MM-DD-NNN | null # work-linked only; null otherwise
61
61
  ```
62
62
 
63
- Also save the Review Kit to `docs/review/.prepare/<prepare-id>.md`.
63
+ In `detailed` mode only, also save the Review Kit to `docs/review/.prepare/<prepare-id>.md`. In `smart`/`autopilot` mode, do not write it; pass it to the next phase in context.
64
64
 
65
65
  ## Validation Rules
66
66
 
@@ -56,7 +56,7 @@ learning-gaps:
56
56
  work-id: YYYY-MM-DD-NNN | null # work-linked only, for the index cross-link; null otherwise
57
57
  ```
58
58
 
59
- Also save the Review Scope to `docs/review/.scope/<scope-id>.md`.
59
+ In `detailed` mode only, also save the Review Scope to `docs/review/.scope/<scope-id>.md`. In `smart`/`autopilot` mode, do not write it; pass it to the next phase in context.
60
60
 
61
61
  ## Validation Rules
62
62
 
@@ -35,6 +35,8 @@ Store in the context object:
35
35
  interactionMode: detailed | smart | autopilot
36
36
  ```
37
37
 
38
+ **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.
39
+
38
40
  **Propagation:** `interactionMode` flows into the `triage`, `prepare`, `execute`, and `review` artifacts; each downstream phase reads it to adjust confirmation behaviour (detailed = pause every transition; autopilot = run all; smart = pause only on HIGH-risk).
39
41
 
40
42
  > **Interaction mode is distinct from execution mode.** `interactionMode` governs _when to pause for the user_ (the same three modes as the `/plan` skill). **Execution mode** (inline / serial / parallel) governs _how multiple tasks are run_ and is selected in the Prepare phase. The two are carried independently through the pipeline.
@@ -59,7 +61,8 @@ Each phase runs sequentially: the orchestrator calls the phase module, receives
59
61
  Before starting the work pipeline, the orchestrator verifies that required folders exist:
60
62
 
61
63
  - `docs/tasks/` — must exist for reading (plan-based) or creating (ad-hoc) the task list
62
- - `docs/plans/.work/.triage/`, `docs/plans/.work/.prepare/`, `docs/plans/.work/.execute/`, `docs/plans/.work/.review/` — must exist for saving the four phase artifacts
64
+ - `docs/plans/.work/.review/` — must exist for saving the Work Report (always written)
65
+ - `docs/plans/.work/.triage/`, `docs/plans/.work/.prepare/`, `docs/plans/.work/.execute/` — **`detailed` mode only**, for saving the intermediate phase artifacts; do not create them in `smart`/`autopilot`
63
66
 
64
67
  **Self-Healing:** If any are missing, the orchestrator automatically creates them (`mkdir -p`). This allows the work skill to run even if `arreio-init` wasn't explicitly run.
65
68
 
@@ -82,9 +85,9 @@ Every new feature or plan runs on its own git branch:
82
85
 
83
86
  | Phase | Phase Module | Output Artifact | Saved to |
84
87
  | ----- | ----------------------------- | ------------------------------------------------------------------ | ----------------------------------- |
85
- | 1 | [Triage](modules/triage.md) | [Work manifest](references/templates/artifacts/work-manifest.md) + `work/<slug>` branch | `docs/plans/.work/.triage/<id>.md` |
86
- | 2 | [Prepare](modules/prepare.md) | [Execution plan](references/templates/artifacts/execution-plan.md) | `docs/plans/.work/.prepare/<id>.md` |
87
- | 3 | [Execute](modules/execute.md) | [Execution log](references/templates/artifacts/execution-log.md) | `docs/plans/.work/.execute/<id>.md` |
88
+ | 1 | [Triage](modules/triage.md) | [Work manifest](references/templates/artifacts/work-manifest.md) + `work/<slug>` branch | `docs/plans/.work/.triage/<id>.md` _(detailed only)_ |
89
+ | 2 | [Prepare](modules/prepare.md) | [Execution plan](references/templates/artifacts/execution-plan.md) | `docs/plans/.work/.prepare/<id>.md` _(detailed only)_ |
90
+ | 3 | [Execute](modules/execute.md) | [Execution log](references/templates/artifacts/execution-log.md) | `docs/plans/.work/.execute/<id>.md` _(detailed only)_ |
88
91
  | 4 | [Review](modules/review.md) | [Work report](references/templates/artifacts/work-report.md) | `docs/plans/.work/.review/<id>.md` |
89
92
 
90
93
  ### Quality Gates
@@ -143,6 +146,17 @@ Artifact templates live in [references/templates/artifacts/](references/template
143
146
  | [execution-log.md](references/templates/artifacts/execution-log.md) | Execute |
144
147
  | [work-report.md](references/templates/artifacts/work-report.md) | Review |
145
148
 
149
+ ## Execution Rules
150
+
151
+ Follow these literally; they exist to keep runs consistent across agents.
152
+
153
+ 1. **Run each module's steps in order**, starting with its Step 0 verification. Do not skip, merge, or reorder steps.
154
+ 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.
155
+ 3. **Compute, don't copy.** Values defined by an algorithm or reference (`executionMode`, per-task risk floor, task status transitions, baseline result) must be evaluated with the real inputs; a recommendation is never `serial` just because it is the fallback. Example values in references and templates are illustrations, never defaults.
156
+ 4. **One question at a time**, with 2–4 concrete options; build the question text from the current values.
157
+ 5. **Announce phase transitions in one line** (e.g., "Phase 2/4 Prepare complete: <key result>") so the user can follow progress, even in Autopilot.
158
+ 6. **Honor write rules:** intermediate phase artifacts only in `detailed` mode; final deliverables always.
159
+
146
160
  ## Core Principles
147
161
 
148
162
  - **Deterministic Pipeline:** Phases always execute in sequence (no agent switching, no fallback paths).
@@ -156,6 +170,7 @@ Artifact templates live in [references/templates/artifacts/](references/template
156
170
  - **Error Handling:** Fail explicitly, not silently; each phase has clear error handling with recovery suggestions.
157
171
  - **Be Concrete:** Use specific files, components, and dependencies from the task artifacts.
158
172
  - **Stay Portable:** Use repository-relative paths only.
173
+ - **Lean Persistence:** Phase artifacts hit disk only in `detailed` mode; `smart`/`autopilot` pass them in context to save tokens and time.
159
174
  - **Transparent Artifacts:** Each phase produces an explicit output artifact for the next phase.
160
175
  - **Interaction Mode Propagation:** `interactionMode` is read at the start of each subsequent phase and determines whether confirmation steps execute.
161
176
  - **Single Source of Truth:** This skill defines all its own rules; it does not depend on any external agent rule file.
@@ -95,7 +95,7 @@ Apply the **[phase confirmation behavior](../references/interaction-mode-propaga
95
95
  - **Smart:** pause only when a pause trigger above is true; otherwise auto-proceed.
96
96
  - **Autopilot:** auto-proceed (no confirmation).
97
97
 
98
- Then save the artifact to `docs/plans/.work/.execute/<execute-id>.md` (ensure `interactionMode` and `executionMode` are included) and return it, with both mode values, to the Orchestrator for the transition to Phase 4 (Review).
98
+ Then, **in `detailed` mode only**, save the artifact to `docs/plans/.work/.execute/<execute-id>.md` (ensure `interactionMode` and `executionMode` are included) and return it, with both mode values, to the Orchestrator for the transition to Phase 4 (Review). 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)).
99
99
 
100
100
  ## Output: Execution Log Artifact
101
101
 
@@ -104,6 +104,6 @@ Then save the artifact to `docs/plans/.work/.execute/<execute-id>.md` (ensure `i
104
104
  - Verify that each `completed` task has its `## Acceptance Criteria` checkbox flipped to `- [x]` and the index ticked `- [ ] → - [x]` (forward only — never reset).
105
105
  - Verify that every `completed` task's single AC test is green with no new regression beyond the recorded baseline snapshot.
106
106
  - Verify that the gate/transition behavior was **enforced from** [task-execution-rules.md](../references/task-execution-rules.md) and [execution-mode-selection.md](../references/execution-mode-selection.md) rather than re-defined inline.
107
- - Verify that the artifact is saved to `docs/plans/.work/.execute/<execute-id>.md`.
107
+ - Verify that, in `detailed` mode, the artifact is saved to `docs/plans/.work/.execute/<execute-id>.md`; in `smart`/`autopilot` mode, verify that **no** file was written and the artifact was passed to the next phase in context.
108
108
 
109
109
  > Pass the Execution Log to `review` (Phase 4) for the simplification, consolidation, and learnings-capture pass.
@@ -79,7 +79,7 @@ Select how `execution-list` is run. The three modes are defined canonically in *
79
79
  1. **Compute the default** from the table above, reading each task's `priority` and any HIGH-risk flag carried from the manifest.
80
80
  2. **Apply the risk floor (authoritative in [execution-mode-selection.md](../references/execution-mode-selection.md)):** any HIGH-risk task forces `inline` for that task; the user may not downgrade a HIGH-risk task below `inline`.
81
81
  3. **Determine user preference:**
82
- - **Detailed:** ask the user which mode to run, presenting the recommendation.
82
+ - **Detailed:** ask the user which mode to run using the question template in [execution-mode-selection.md](../references/execution-mode-selection.md), filled with the computed values (including `Auto`).
83
83
  - **Smart:** auto-select, unless a pause trigger fires (Step 7).
84
84
  - **Autopilot:** auto-select; never ask.
85
85
  4. **Honor user preference** unless it violates the risk floor; on violation, ask the user to accept `inline` instead.
@@ -126,7 +126,7 @@ Apply the **[phase confirmation behavior](../references/interaction-mode-propaga
126
126
  - **Smart:** pause only when a pause trigger above is true; otherwise auto-proceed.
127
127
  - **Autopilot:** auto-proceed (no confirmation).
128
128
 
129
- Then save the artifact to `docs/plans/.work/.prepare/<prepare-id>.md` (ensure `interactionMode` and `executionMode` are included) and return it, with both mode values, to the Orchestrator for the transition to Phase 3 (Execute).
129
+ Then, **in `detailed` mode only**, save the artifact to `docs/plans/.work/.prepare/<prepare-id>.md` (ensure `interactionMode` and `executionMode` are included) and return it, with both mode values, to the Orchestrator for the transition to Phase 3 (Execute). 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)).
130
130
 
131
131
  ## Output: Execution Plan Artifact
132
132
 
@@ -135,6 +135,6 @@ Then save the artifact to `docs/plans/.work/.prepare/<prepare-id>.md` (ensure `i
135
135
  - Verify that the gate/policy details were **read from** [task-execution-rules.md](../references/task-execution-rules.md) rather than re-encoded inline (no second formula contradicting the authoritative reference).
136
136
  - Verify that `execution-list` preserves the manifest's dependency order (no task before its dependencies) and that wave-grouping (if `parallel`) respects dependency layers.
137
137
  - Verify that the `baseline` policy is recorded (a red baseline was surfaced, not hidden).
138
- - Verify that the artifact is saved to `docs/plans/.work/.prepare/<prepare-id>.md`.
138
+ - Verify that, in `detailed` mode, the artifact is saved to `docs/plans/.work/.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.
139
139
 
140
140
  > Pass the Execution Plan to `execute` (Phase 3) for the test-first execution run.
@@ -166,7 +166,7 @@ Apply the **[phase confirmation behavior](../references/interaction-mode-propaga
166
166
  - **Smart:** pause only when a pause trigger above is true; otherwise auto-proceed.
167
167
  - **Autopilot:** auto-proceed (no confirmation).
168
168
 
169
- Then save the artifact to `docs/plans/.work/.triage/<triage-id>.md` (ensure `interactionMode` and `input-shape` are included) and return it, with the `interactionMode` value, to the Orchestrator for the transition to Phase 2 (Prepare).
169
+ Then, **in `detailed` mode only**, save the artifact to `docs/plans/.work/.triage/<triage-id>.md` (ensure `interactionMode` and `input-shape` 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)).
170
170
 
171
171
  ## Output: Work Manifest Artifact
172
172
 
@@ -176,6 +176,6 @@ Then save the artifact to `docs/plans/.work/.triage/<triage-id>.md` (ensure `int
176
176
  - Verify that `work-id` is correct for the shape (inherited `plan-id` for plan-based/task-file; freshly allocated for ad-hoc).
177
177
  - Verify that `work-branch` is recorded in the manifest and, unless `null`, the repository is checked out on that branch.
178
178
  - Verify that for `ad-hoc` input, the task files and `docs/tasks/<work-id>/index.md` were created.
179
- - Verify that the artifact is saved to `docs/plans/.work/.triage/<triage-id>.md`.
179
+ - Verify that, in `detailed` mode, the artifact is saved to `docs/plans/.work/.triage/<triage-id>.md`; in `smart`/`autopilot` mode, verify that **no** file was written and the artifact was passed to the next phase in context.
180
180
 
181
181
  > Pass the Work Manifest to `prepare` (Phase 2) for execution-mode selection and sequencing.
@@ -2,8 +2,8 @@
2
2
  title: Execution Mode Selection
3
3
  description: Authoritative reference for the Prepare phase. Defines the three execution modes (inline/serial/parallel), their selection defaults, the risk floor (HIGH-risk forces inline, non-downgradable), and the per-mode flows Execute follows.
4
4
  type: reference
5
- version: 1.0
6
- timestamp: "2026-08-07"
5
+ version: 1.1
6
+ timestamp: "2026-10-01"
7
7
  ---
8
8
 
9
9
  # Execution Mode Selection
@@ -41,6 +41,25 @@ Authoritative reference for the **Prepare** phase (Step 3). Defines the three ex
41
41
  parallel -> waves: [Wave0, Wave1, ...]
42
42
  ```
43
43
 
44
+ **Evaluation rules:**
45
+
46
+ - The `default_mode` branches are checked **in the order written**; the first match wins. `serial` is the result **only** when neither earlier branch matches — it is a fallback, not a neutral default.
47
+ - Evaluate with the real manifest data (task count, priorities, HIGH-risk flags, wave count). Do not copy a mode from an example.
48
+ - The recommendation shown to the user is `default_mode` after the risk floor.
49
+
50
+ **Detailed-mode question** — build it from computed values; replace every `<…>`:
51
+
52
+ ```
53
+ This run has <N> tasks in <W> wave(s); <H> HIGH-risk, <P0> P0. I recommend <default_mode>.
54
+ Which execution mode would you like?
55
+ - Inline: one task at a time, pause between tasks
56
+ - Serial: ordered list, no per-task pause
57
+ - Parallel: concurrent waves
58
+ - Auto: use the recommendation (result: <default_mode>)
59
+ ```
60
+
61
+ Append ` [Recommended]` to the option equal to `default_mode`; if the risk floor makes an option unsafe, say so on that option.
62
+
44
63
  ## Risk Floor (authoritative, non-downgradable)
45
64
 
46
65
  - **Any HIGH-risk task forces `inline` treatment for that task**, regardless of the selected `executionMode`.
@@ -12,7 +12,7 @@ Shared ID algorithm for the `triage`, `prepare`, `execute`, and `review` phases,
12
12
 
13
13
  ## ID Format by Phase
14
14
 
15
- | Phase | ID format | Saved to |
15
+ | Phase | ID format | Saved to (detailed only) |
16
16
  | -------- | ----------------------------------- | -------------------------------- |
17
17
  | Triage | `YYYY-MM-DD-NNN-triage` | `docs/plans/.work/.triage/<id>.md` |
18
18
  | Prepare | `YYYY-MM-DD-NNN-prepare` | `docs/plans/.work/.prepare/<id>.md` |
@@ -35,6 +35,8 @@ The `work-id` is the key that ties all four phase artifacts together and locates
35
35
 
36
36
  > **Work branch name:** the git branch for a run is `work/<short-description>` — a kebab-case slug derived from the plan name or work description (Triage Step 2d), **not** the `work-id` itself. The Work Manifest records the `work-branch` ↔ `work-id` pairing; see `skills/work/modules/triage.md` Step 2d.
37
37
 
38
+ > **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: Triage/Prepare/Execute ids are `<work-id>-<phase>` (in-memory labels). Only the Work Report `review-id` is persisted, so it still counts existing files in `docs/plans/.work/.review/`. See [Artifact Persistence](interaction-mode-propagation.md#artifact-persistence).
39
+
38
40
  ## Algorithm (new phase artifact)
39
41
 
40
42
  ```
@@ -77,4 +77,24 @@ The two never override one another; the orchestrator's quality gate #2 cross-che
77
77
  | Invalid mode value | Reject; re-prompt Orchestrator |
78
78
  | Artifact missing mode field | Assume "smart"; log warning; continue |
79
79
  | User selects "Abort" | Stop immediately; inform Orchestrator |
80
- | Timeout/connection lost | Pause; ask user to retry or abort |
80
+ | Timeout/connection lost | Pause; ask user to retry or abort |
81
+
82
+ ## Artifact Persistence
83
+
84
+ Phase artifacts (Triage, Prepare, Execute) are **handoff data between phases**, not deliverables. Whether they are written to disk depends on `interactionMode`:
85
+
86
+ | Mode | Phase artifacts (`docs/plans/.work/.triage/`, `.prepare/`, `.execute/`) | Phase handoff |
87
+ | ------------- | ---------------------------------------- | ---------------------------------------------- |
88
+ | **Detailed** | Written to the hidden directories (audit trail; creating the directory on first use) | Artifact is written, shown, then passed on |
89
+ | **Smart** | **Not written** | Artifact is held in context and passed in-memory to the next phase |
90
+ | **Autopilot** | **Not written** | Artifact is held in context and passed in-memory to the next phase |
91
+
92
+ **Always written, in every mode:** the Work Report in `docs/plans/.work/.review/<review-id>.md` (a cross-skill handoff read by `/review` and `/learn`), the task files/index in `docs/tasks/<work-id>/`, and the work branch.
93
+
94
+ **Rules:**
95
+
96
+ - 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.
97
+ - Never create the hidden directories in `smart`/`autopilot`; no placeholder or empty files.
98
+ - **ID allocation without files:** Triage/Prepare/Execute ids are `<work-id>-<phase>` (in-memory labels). Only the Work Report `review-id` is persisted, so it still counts existing files in `docs/plans/.work/.review/`.
99
+ - If the user switches to `detailed` mid-run, write the artifacts produced so far, then continue writing.
100
+ - Because nothing is on disk, **Edit & Retry** reuses the in-memory artifact and its id (no file to overwrite).
@@ -52,7 +52,7 @@ final-index-state:
52
52
  uncompleted-rows: [<task-id>, ...] # rows still - [] (blocked/skipped)
53
53
  ```
54
54
 
55
- Also save the Execution Log to `docs/plans/.work/.execute/<execute-id>.md`.
55
+ In `detailed` mode only, also save the Execution Log to `docs/plans/.work/.execute/<execute-id>.md`. In `smart`/`autopilot` mode, do not write it; pass it to the next phase in context.
56
56
 
57
57
  ## Validation Rules
58
58
 
@@ -55,7 +55,7 @@ policy: # recorded read-only from task-executio
55
55
  work-state: ready | nothing-ready # echoes the Work Manifest if carried through
56
56
  ```
57
57
 
58
- Also save the Execution Plan to `docs/plans/.work/.prepare/<prepare-id>.md`.
58
+ In `detailed` mode only, also save the Execution Plan to `docs/plans/.work/.prepare/<prepare-id>.md`. In `smart`/`autopilot` mode, do not write it; pass it to the next phase in context.
59
59
 
60
60
  ## Validation Rules
61
61
 
@@ -56,7 +56,7 @@ dependency-warning: null | proceeded-without-upstream | expanded-to-upstream #
56
56
  work-state: ready | nothing-ready # nothing-ready if no task is runnable
57
57
  ```
58
58
 
59
- Also save the manifest to `docs/plans/.work/.triage/<triage-id>.md` for future reference or reuse.
59
+ In `detailed` mode only, also save the manifest to `docs/plans/.work/.triage/<triage-id>.md` for future reference or reuse. In `smart`/`autopilot` mode, do not write it; pass it to the next phase in context.
60
60
 
61
61
  ## Validation Rules
62
62