arreio 1.0.0-dev.1

package/skills/work/modules/prepare.md

@@ -0,0 +1,140 @@
+---
+title: Prepare
+description: Set up the execution environment, assemble the ordered execution list from the Work Manifest, select an execution mode (inline/serial/parallel), select the per-task gates from task-execution-rules, and return an Execution Plan for the Execute phase.
+type: module
+version: 1.0
+timestamp: "2026-08-07"
+---
+
+# Phase 2 - Prepare
+
+**Purpose:** Second step in the Work workflow. Reads the [Work Manifest](../references/templates/artifacts/work-manifest.md) from Triage, verifies the test execution environment and establishes a green baseline, assembles the ordered execution list from the manifest's `ready-tasks`, selects an execution mode, and selects the per-task quality gates (Red → Green → Refactor) and resume/blocked/skip policy from their authoritative references — without re-encoding them. Returns an [Execution Plan](../references/templates/artifacts/execution-plan.md) that the Execute phase consumes.
+
+## Workflow
+
+This is the Phase 2 pipeline for the Work Skill. It orchestrates the following steps:
+
+### Step 0: Verification
+
+Run the **[Step 0 verification](../references/error-handling.md)**. Required input: a valid **Work Manifest** from Triage. Specifically verify:
+
+1. The Work Manifest carries `triage-id`, `work-id`, `input-shape`, `interactionMode`, the resolved task list, and `ready-tasks`.
+2. Every manifest task preserves the `/plan` invariants (one Acceptance Criterion → one `files.test` → Red → Green → Refactor steps).
+3. `interactionMode` is present and valid (default to `smart` if missing; log warning).
+4. Cross-phase consistency: `work-id` matches the Triage output; `interactionMode` is identical across artifacts.
+
+If the manifest reports `work-state: nothing-ready` (no runnable task), do **not** abort — Prepare still runs Steps 1–4 to produce an Execution Plan that records the empty run; the Review phase handles the outcome.
+
+### Step 1: Verify the Test Execution Environment
+
+1. **Detect the test runner** from config files in repository root:
+
+   | Tech Stack | Config File(s)                        | Test Command (capability)          |
+   | ---------- | ------------------------------------- | ----------------------------------- |
+   | Node.js (npm)  | `package.json` + `package-lock.json`; `scripts.test`, or `jest`/`vitest`/`mocha` in deps | `npm test` / `npx jest` / `npx vitest` |
+   | Node.js (pnpm) | `package.json` + `pnpm-lock.yaml`; `scripts.test`, or `jest`/`vitest`/`mocha` in deps | `pnpm test` / `pnpm exec jest` / `pnpm exec vitest` |
+   | Python     | `pyproject.toml` / `pytest.ini` / `setup.cfg` | `pytest`                            |
+   | Go         | `go.mod` + `*_test.go`                | `go test ./...`                     |
+   | Rust       | `Cargo.toml`                          | `cargo test`                        |
+   | Ruby       | `Gemfile` (rspec/minitest)            | `bundle exec rspec`                 |
+   | PHP        | `composer.json` (phpunit)             | `vendor/bin/phpunit`                |
+   | Java/Kotlin | `pom.xml` / `build.gradle`            | `mvn test` / `gradle test`          |
+
+   **Node.js package manager detection:** read lockfiles to pick npm vs pnpm — `package-lock.json` → npm; `pnpm-lock.yaml` → pnpm. If both lockfiles exist, prefer the one that matches `package.json`'s `packageManager` field; if that is also unset, ask the user which to use. Record `packageManager: npm | pnpm` for Execute so every test/install command uses it consistently.
+
+   If NO config files match, record `runner: unknown` and ask the user for the project's test command before proceeding.
+
+2. **Establish a green baseline.** Run the existing test suite (or the targeted test path covering the tasks in scope) to confirm the suite runs and is green. Record `baseline: green` (exit clean) or `baseline: red` (pre-existing failures).
+   - **If `baseline: red`:** do not proceed silently. This is a Smart pause trigger — ask the user one question:
+     ```
+     The existing test suite is currently red (<N> failures), so later regressions cannot be detected reliably.
+     What would you like to do?
+      - Fix baseline first: Resolve the pre-existing failures before running Work
+      - Snapshot & continue: Record the currently-failing tests as the known-baseline; Execute only flags *new* regressions
+      - Abort: Stop and return to the Orchestrator
+     ```
+   - On **Snapshot & continue**, record the set of known-failing tests in the Execution Plan so Execute's regression gate ignores them (per the `snapshot & continue` policy in [task-execution-rules.md](../references/task-execution-rules.md)).
+
+3. **Verify each `files.test` path resolves** against the working directory (or will be created by Red — a not-yet-existing test path is valid for a Red step). Only surface a problem if the *directory* the test should live in doesn't exist and can't be created. Do not create files here; Execute writes tests.
+
+### Step 2: Assemble the Ordered Execution List
+
+1. **Take `ready-tasks`** from the Work Manifest (already dependency-filtered in Triage Step 4). Preserve the manifest's dependency order — do not re-sort.
+2. **Group into execution waves** (used only if Step 3 selects `parallel`):
+   - **Wave 0** — tasks with all dependencies already `completed` (the manifest's `ready-tasks` with satisfied deps).
+   - **Wave N** — tasks all of whose dependencies are in Waves `< N`; each wave is independent internally and can run concurrently.
+   - Within a wave, order by original unit number for stable output.
+3. Record the ordered list (flat for `inline`/`serial`; wave-grouped for `parallel`) as `execution-list`. If `input-shape: task-file` with the user having chosen **Proceed anyway**, the list is still the single task — record `upstream-skipped: true`.
+
+### Step 3: Select Execution Mode
+
+Select how `execution-list` is run. The three modes are defined canonically in **[execution-mode-selection.md](../references/execution-mode-selection.md)** — this step looks them up, it does not re-derive them:
+
+| Mode       | Behavior                                                                    | Default when                                       |
+| ---------- | --------------------------------------------------------------------------- | -------------------------------------------------- |
+| `inline`   | One task at a time; pause between tasks; re-confirm the user before each destructive step. | `interactionMode: detailed`, **or** any `P0`/HIGH-risk task is in the list |
+| `serial`   | Run the ordered list sequentially; no per-task pause (still stops on a blocked task). | Default fallback — most task lists                 |
+| `parallel` | Run each wave's independent tasks concurrently (waves run in order).        | `execution-list` has 2+ independent waves **and** none is HIGH-risk |
+
+1. **Compute the default** from the table above, reading each task's `priority` and any HIGH-risk flag carried from the manifest.
+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`.
+3. **Determine user preference:**
+   - **Detailed:** ask the user which mode to run, presenting the recommendation.
+   - **Smart:** auto-select, unless a pause trigger fires (Step 7).
+   - **Autopilot:** auto-select; never ask.
+4. **Honor user preference** unless it violates the risk floor; on violation, ask the user to accept `inline` instead.
+5. Record `executionMode: inline | serial | parallel` and the per-mode flow (`single-task-pause: true` for inline; `waves: [...]` for parallel).
+
+### Step 4: Select Per-Task Gates and Resume Policy
+
+Select the gates and transitions Execute will enforce. Their definitions are authoritative in **[task-execution-rules.md](../references/task-execution-rules.md)** — this step records which gates apply and the thresholds, it does not re-encode the rules:
+
+1. **Per-task gates** (record the applicable set):
+   - **Red** — the new test in `files.test` exists and **fails for the right reason** (not a setup/import/compile error).
+   - **Green** — the task's single Acceptance-Criterion test now passes, with no new regression beyond the Step 1 baseline.
+   - **Refactor** — the test stays green after cleanup, with no regression.
+   - **Complete transition** — frontmatter `status → completed`; the task file's `## Acceptance Criteria` checkbox flips to `- [x]`; the index checklist ticks forward (`- [ ]` → `- [x]`).
+2. **Resume policy (authoritative in [task-execution-rules.md](../references/task-execution-rules.md)):**
+   - Re-entry reads each task file's `status`; a `completed` task is skipped (never re-opened, checkboxes never reset).
+   - `blocked` and `skipped` tasks are carried with their recorded reasons; they are not auto-retried.
+3. **Blocked transition (record the thresholds; definitions in [task-execution-rules.md](../references/task-execution-rules.md)):** if the Green gate isn't reached within the documented retry limit, the task → `blocked` with a recorded reason and a per-task snapshot of the failing assertion. Execute pauses (per mode) before the next task.
+4. **Skip transition:** skipping a task requires explicit user confirmation (never auto-skip); the index checkbox stays `- [ ]` and the reason is recorded.
+
+Record the selected `applicable-gates` and thresholds (retry-limit, regression policy from Step 1) in the Execution Plan so Execute enforces them read-only.
+
+### Step 5: Generate the Execution Plan Artifact
+
+1. **Assign a `prepare-id`** per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-prepare`, saved to `docs/plans/.work/.prepare/`). Reuse it if the user later picks **Edit & Retry**.
+
+2. Produce an **Execution Plan** block (as markdown) following the schema in [execution-plan.md](../references/templates/artifacts/execution-plan.md). Include:
+   - `prepare-id`, inherited `triage-id` and `work-id`, `input-shape`
+   - `interactionMode` and `executionMode`
+   - the `execution-list` (flat or wave-grouped)
+   - `runner` + test command, `baseline` (`green` | `red` | `snapshot-and-continue`), and any known-failing test snapshot
+   - `applicable-gates`, retry-limit, and resume/blocked/skip policy (read from [task-execution-rules.md](../references/task-execution-rules.md))
+   - `work-state` (echo `nothing-ready` if the manifest carried it)
+
+### Step 6: Present, Confirm, and Save
+
+Apply the **[phase confirmation behavior](../references/interaction-mode-propagation.md)** for the current `interactionMode`, using these prepare-specific **Smart pause triggers**:
+
+- `baseline: red` and the user has not yet chosen a baseline policy (Step 1), or
+- `executionMode: parallel` on an execution list of > 5 tasks (concurrency risk), or
+- A HIGH-risk task is present but the selected `executionMode` would not give it `inline` treatment (risk-floor conflict pre-override).
+
+- **Detailed:** present the Execution Plan and ask one question with options *(1) Proceed to Execute, (2) Edit & Retry, (3) Abort*. On **Edit & Retry**, loop back through Steps 1–5 reusing the `prepare-id`. On **Abort**, stop and inform the Orchestrator.
+- **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/.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).
+
+## Output: Execution Plan Artifact
+
+- Verify that the Execution Plan is complete and valid: `prepare-id`, `triage-id`, `work-id`, `input-shape`, `interactionMode`, `executionMode`, `execution-list`, `runner`, `baseline`, `applicable-gates`, and resume/blocked/skip policy.
+- Verify that `executionMode` is consistent with the interaction mode and the risk floor in [execution-mode-selection.md](../references/execution-mode-selection.md) (HIGH-risk → `inline`).
+- 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).
+- Verify that `execution-list` preserves the manifest's dependency order (no task before its dependencies) and that wave-grouping (if `parallel`) respects dependency layers.
+- Verify that the `baseline` policy is recorded (a red baseline was surfaced, not hidden).
+- Verify that the artifact is saved to `docs/plans/.work/.prepare/<prepare-id>.md`.
+
+> Pass the Execution Plan to `execute` (Phase 3) for the test-first execution run.

package/skills/work/modules/review.md

@@ -0,0 +1,164 @@
+---
+title: Review
+description: Close the Work workflow by reviewing the Execution Log run simplification/consolidation (definitions authoritative in review-checklist), running a whole-work-id regression check, detecting scope creep against the Work Manifest, surfacing learnings for /learn, and gating task status to for-review (if regressions/creep detected) or completed (if clean). Updates task file frontmatter status and appends the closing Work Report status block to the task index.
+type: module
+version: 1.0
+timestamp: "2026-08-12"
+---
+
+# Phase 4 - Review
+
+**Purpose:** Fourth and final step in the Work workflow. Reads the [Execution Log](../references/templates/artifacts/execution-log.md) from Execute, reviews the executed code for simplification and consolidation, runs a whole-`work-id` test-regression check, detects any scope creep against the Work Manifest, and surfaces new learnings for the Learn skill (`/learn`) to persist. Appends the closing `## Work Report — <review-id>` status block to `docs/tasks/<work-id>/index.md`. Returns a [Work Report](../references/templates/artifacts/work-report.md) as the Work skill's final deliverable.
+
+## Workflow
+
+This is the Phase 4 pipeline for the Work Skill. It orchestrates the following steps:
+
+### Step 0: Verification
+
+Run the **[Step 0 verification](../references/error-handling.md)**. Required input: a valid **Execution Log** from Execute. Specifically verify:
+
+1. The Execution Log carries `execute-id`, `prepare-id`, `triage-id`, `work-id`, `input-shape`, `interactionMode`, `executionMode`, the per-task result table, and the aggregator counts.
+2. **Task-status coherence** (the orchestrator's quality gate #4): every task ended `completed`, `blocked` (with a recorded reason), or `skipped` (with a recorded reason) — none left `in-progress` — and `docs/tasks/<work-id>/index.md` checklist state matches the task files' frontmatter `status`. Execute is responsible for leaving this coherent; Review re-verifies and refuses to proceed (Category 2 recovery) if not.
+3. `interactionMode` is present and valid (default to `smart` if missing; log warning).
+4. Cross-phase consistency: `work-id`, `triage-id`, `prepare-id`, `execute-id` match the upstream artifacts.
+
+If the run was empty (`work-state: nothing-ready` was carried through), Review still produces a Work Report recording that no task was runnable — do not abort.
+
+### Step 1: Simplify and Consolidate
+
+Review the code touched by the `completed` tasks for simplification and consolidation. The definitions and the per-check criteria are authoritative in **[review-checklist.md](../references/review-checklist.md)** — Review applies the checklist, it does not re-encode it. Run its checks across the changed files (those listed in the completed tasks' `files.create` / `files.modify`):
+
+- **Dead code / duplication** — remove code made unreachable or duplicated by the run; honor DRY by extracting shared logic.
+- **Naming and structure** — tighten intention-revealing names; collapse overlarge functions/classes to single responsibility; no speculative generality.
+- **Boundary isolation** — keep side effects at the boundaries; prefer pure functions where the changes permit it.
+
+Apply each change as a **refactor** — the relevant tasks' AC tests must stay green; if any targeted check would change behavior, treat it as scope creep (Step 3) rather than a refactor, and do not apply it here.
+
+Record `simplification-summary` (what was simplified/clipped) and `consolidations` (any merged logic / extracted abstractions) in the Work Report.
+
+### Step 2: Whole-Work-Id Regression Check
+
+1. Run the full test suite for the `work-id`'s affected scope (the union of the `completed` tasks' test paths, plus any files they modified that are covered elsewhere) using the Execute-resolved test command (`runner` + `packageManager`).
+2. **Compare against the Prepare baseline** recorded in the Execution Plan:
+   - `baseline: green` — the suite must still be green; **any failure is a regression** (binary threshold: one failure = gate fails).
+   - `baseline: snapshot-and-continue` — failures must be a subset of the recorded known-failing snapshot; any **new** failure is a regression.
+3. Record `regression-check: clean | regressions-found` with the failing-test list if any. A regression found here is a gate trigger: if regressions exist, task status enters `for-review` (Step 4a).
+
+### Step 3: Scope-Creep Detection
+
+Compare the executed work against the Work Manifest's resolved task list and each task's single Acceptance Criterion:
+
+1. **Per-task scope** — for each `completed` task, confirm the change in `files.create` / `files.modify` is bounded by **that task's single AC**. Edits beyond the AC (extra files touched, behavior not asserted by `files.test`) are scope creep.
+2. **Manifest scope** — confirm no task was added, removed, or silently expanded beyond what Triage resolved. (A `dependency-warning: expanded-to-upstream` from the task-file shape is expected, not creep.)
+3. Record `scope-creep` findings per task (file path + why it exceeds the AC), or `scope-creep: none`. Surface any creep to the user — never fold it silently into a task.
+
+### Step 4: Scope-Creep Detection (Detailed)
+
+Compare the executed work against the Work Manifest's resolved task list and each task's single Acceptance Criterion:
+
+1. **Per-task scope** — for each `completed` task, confirm the change in `files.create` / `files.modify` is bounded by **that task's single AC**. Edits beyond the AC (extra files touched, behavior not asserted by `files.test`) are scope creep.
+2. **Manifest scope** — confirm no task was added, removed, or silently expanded beyond what Triage resolved. (A `dependency-warning: expanded-to-upstream` from the task-file shape is expected, not creep.)
+3. Record `scope-creep` findings per task (file path + why it exceeds the AC), or `scope-creep: none`. Surface any creep to the user — never fold it silently into a task. Scope-creep findings are a gate trigger (Step 4a).
+
+### Step 4a: Gate Decision — For-Review vs. Completed
+
+**Binary gate:** Decide task status based on the outcomes of Steps 2–3.
+
+If **any** of the following conditions is true, set `task-status-target: for-review` (tasks will enter `status: for-review` in Step 6):
+
+- `regression-check: regressions-found` (any test failure)
+- `scope-creep` findings exist (any file/behavior exceeds AC)
+
+Otherwise, set `task-status-target: completed` (tasks will move to `status: completed`).
+
+Record this decision with a brief summary: e.g., "Gate passed: clean regression check, no scope creep" or "Gate blocked: regressions-found (3 new failures) + scope creep in 2 files".
+
+### Step 5: Learnings Capture
+
+Surface new learnings discovered during execution for the Learn skill to persist (Work does not write `docs/learn/` directly):
+
+1. For each notable finding — a confirmed pattern, a refuted assumption, a gotcha hit, or a decision forced by the run — record a learning candidate with: a working title, the domain, the source (task-id + gate where found), and a 1–2 sentence summary.
+2. Carry the Work Manifest's `Learning Gaps` forward; add any gaps the run revealed (e.g., a missing test pattern that forced a workaround).
+3. Record `learnings-to-capture` (candidates) and `learning-gaps` in the Work Report. The user is prompted (per interaction mode) to run `/learn` to persist them (orthogonal to approval gates).
+
+### Step 6: Generate the Work Report Artifact
+
+1. **Assign a `review-id`** per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-review`, saved to `docs/plans/.work/.review/`). Reuse it if the user later picks **Edit & Retry**.
+
+2. Produce a **Work Report** block (as markdown) following the schema in [work-report.md](../references/templates/artifacts/work-report.md). Include:
+   - `review-id`, inherited `execute-id`, `prepare-id`, `triage-id`, `work-id`, `input-shape`
+   - `interactionMode` and `executionMode` (both carried)
+   - the final task-outcome rollup (echo Execute's aggregator counts: `completed` / `blocked` / `skipped`)
+   - `simplification-summary` and `consolidations`
+   - `regression-check` (`clean` | `regressions-found` + failing list)
+   - `scope-creep` findings (or `none`)
+   - `learnings-to-capture` and `learning-gaps`
+   - a final `work-state`:
+     - `for-review`: tasks gated to `status: for-review` (regressions or scope-creep detected; pending Standalone Review approval)
+     - `complete`: all tasks `completed` and regression-clean (gate passed)
+     - `partial`: some tasks `blocked`/`skipped` but progress made (all non-blocked tasks passed gate)
+     - `nothing-done`: empty run or all blocked early
+
+### Step 7: Update Task File Frontmatter and Register the Work Report
+
+**Update task file status:**
+For each task affected by the Work run (based on `task-status-target` from Step 4a):
+
+1. Open `docs/tasks/<work-id>/T<NN>-<name>.md`
+2. Update the frontmatter `status:` field:
+   - If `task-status-target: for-review` → set `status: for-review`
+   - If `task-status-target: completed` → set `status: completed` (as before)
+3. Idempotent: re-running Review with the same `review-id` overwrites the status (never duplicates).
+
+**Append status block to task index:**
+Append the closing status block to `docs/tasks/<work-id>/index.md` (the task index Triage created / Execute updated). The block records the final state next to the checklist, so a future glance shows how the run ended:
+
+```markdown
+## Work Report — <review-id>
+
+- **Status:** complete | partial | for-review | nothing-done
+- **Tasks:** <completed>/<total> completed, <for-review> for-review, <blocked> blocked, <skipped> skipped
+- **Regression check:** clean | regressions-found (<N>)
+- **Scope creep:** none | <count> finding(s)
+- **Learnings to capture:** <count> (run `/learn` to persist)
+- **Work Report:** docs/plans/.work/.review/<review-id>.md
+```
+
+If the index does not exist (ad-hoc input that somehow lost its index), create it with the checklist before appending the block. The block is **append-only** and idempotent on `review-id` (a re-run overwrites the block with the same `review-id`, never duplicates).
+
+### Step 8: Present, Confirm, and Save
+
+Apply the **[phase confirmation behavior](../references/interaction-mode-propagation.md)** for the current `interactionMode`, using these review-specific **Smart pause triggers**:
+
+- `task-status-target: for-review` (gate blocked; tasks will enter for-review), or
+- `regression-check: regressions-found` (any test failures detected), or
+- `scope-creep` findings exist (confirm the creep is intentional or roll it back), or
+- `learnings-to-capture` is non-empty and the user may want to capture them now via `/learn` before closing.
+
+- **Detailed:** present the Work Report and ask one question with options _(1) Finalize Work, (2) Edit & Retry, (3) Abort_. On **Edit & Retry**, loop back through Steps 1–7 reusing the `review-id` (the index block is overwritten, not duplicated, because it keys on `review-id`). On **Abort**, stop and inform the Orchestrator.
+- **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/.work/.review/<review-id>.md` (ensure `interactionMode` and `executionMode` are included).
+
+### Step 9: Return to Orchestrator
+
+Return the Work Report to the Orchestrator — `path`, `review-id`, `work-id`, `work-state`, `task-status-target`, `interactionMode`, `executionMode`, and `learnings-to-capture` count. The Orchestrator marks the Work workflow complete.
+
+**Next steps (user-facing):**
+
+- If `work-state: for-review`, inform the user: "Tasks have entered `for-review` status. Run `/review <work-id>` to audit them before final approval."
+- Optionally chain to the Learn skill (`/learn <work-id>` or `/learn <candidate-ref>`) when `learnings-to-capture` is non-empty; otherwise the session ends.
+
+## Output: Work Report Artifact
+
+- Verify that the Work Report is complete and valid: `review-id`, `execute-id`, `prepare-id`, `triage-id`, `work-id`, `input-shape`, `interactionMode`, `executionMode`, the task-outcome rollup, `simplification-summary`, `consolidations`, `regression-check`, `scope-creep`, `learnings-to-capture`, and `learning-gaps`.
+- Verify that **task-status coherence** held: the Execution Log's outcomes match `docs/tasks/<work-id>/index.md` and the task files' frontmatter (re-verified in Step 0).
+- Verify that task files' frontmatter `status:` fields were updated to `for-review | completed` per the gate decision (Step 4a).
+- Verify that the `## Work Report — <review-id>` block was appended to `docs/tasks/<work-id>/index.md` and is idempotent on `review-id` (no duplicate blocks).
+- Verify that the simplification/consolidation/scope-creep/learnings rules were **applied from** [review-checklist.md](../references/review-checklist.md) rather than re-encoded inline.
+- Verify that `work-state` reflects the gate outcome: `for-review | complete | partial | nothing-done`.
+- Verify that the artifact is saved to `docs/plans/.work/.review/<review-id>.md`.
+
+> The Work Report is the primary deliverable of the Work Skill. Tasks entering `for-review` status signal that Standalone Review approval is required before moving to `completed`. The Orchestrator marks the workflow complete; user runs `/review <work-id>` next if tasks are in `for-review`; optionally chains to `/learn` when learnings were surfaced (orthogonal to approval gates).

package/skills/work/modules/triage.md

@@ -0,0 +1,181 @@
+---
+title: Triage
+description: Classify work input (plan-id, task file, or ad-hoc description), resolve it into a unified, dependency-ordered Work Manifest carrying one Acceptance Criterion per task with a Red-first test, and return it for the Prepare phase.
+type: module
+version: 1.0
+timestamp: "2026-08-07"
+---
+
+# Phase 1 - Triage & Work Input Resolution
+
+**Purpose:** Entry point to the Work workflow. Classifies the incoming work input (a plan-id, a single task file, or an ad-hoc description), resolves it into a unified, dependency-ordered **Work Manifest** — one task per Acceptance Criterion, each carrying its own Red → Green → Refactor test — establishes the git work branch (`work/<short-description>`) for the run, and returns it for the Prepare phase to sequence and select an execution mode.
+
+## Workflow
+
+This is the Phase 1 pipeline for the Work Skill. It orchestrates the following steps:
+
+### Step 0: Verification
+
+Run the **[Step 0 verification](../references/error-handling.md)**. Required input: a valid **Work Input Artifact** (see [work-input.md](../references/templates/artifacts/work-input.md)) from the Orchestrator. Specifically verify:
+
+1. The Work Input Artifact carries exactly one of: a `plan-id`, a `task-file path` (or task-id), or an `ad-hoc` description.
+2. `interactionMode` is present and valid (default to `smart` if missing; log warning).
+3. The required folders already exist (the Orchestrator's Pre-Flight Check is responsible for creation); do not re-create them here.
+
+If the input is empty or ambiguous between shapes, ask the user one question: "What would you like to work on? Provide a plan-id, a task file, or describe the task."
+
+### Step 1: Classify Input Shape
+
+Determine which of the three input shapes applies, by precedence:
+
+1. **Plan-based** — the input matches an existing `docs/tasks/<plan-id>/index.md` (the value is a `YYYY-MM-DD-NNN` plan-id, or a path resolving to a `docs/tasks/<id>/index.md`).
+2. **Task-file** — the input is, or resolves to, a path matching `docs/tasks/<plan-id>/T<NN>-<name>.md`, or a task-id matching `<plan-id>-T<NN>`.
+3. **Ad-hoc** — the input is a free-text description that matches neither of the above.
+
+Record `input-shape: plan-based | task-file | ad-hoc`. If classification is ambiguous (e.g., a string that could be a plan-id or a description), ask the user one question with the candidate shapes as options.
+
+### Step 2: Resolve to Work Manifest (by Shape)
+
+Resolve the classified input into a unified **Work Manifest** — a single task list where each entry is keyed by `task-id` and carries `unit`, `acceptance-criterion`, `files`, `dependencies`, `priority`, and current `status`. Each task preserves the `/plan` invariant: exactly one Acceptance Criterion, exactly one `files.test`, Red → Green → Refactor steps.
+
+#### 2a. Plan-based
+
+1. Read `docs/tasks/<plan-id>/index.md` and parse the task checklist into an ordered list of task file paths.
+2. Set `work-id = plan-id` (inherited — never allocate a new id).
+3. For each task file, parse its frontmatter (`id`, `title`, `plan-id`, `unit`, `status`, `priority`, `dependencies`, `files`, `estimated-effort`) and body sections.
+4. Build the manifest in **dependency order** using the same topological ordering as the `/plan` Tasks phase (a task never appears before its dependencies). On a cycle, surface the involved tasks and ask the user whether to break the cycle (remove a dependency) or abort.
+5. Record the full task list. Do **not** filter by status here — resume filtering happens in Step 4.
+
+#### 2b. Task-file
+
+1. Locate the single task file. If given a task-id (`<plan-id>-T<NN>`), resolve it to the unique `docs/tasks/<plan-id>/T<NN>-*.md` match (exactly one expected; if multiple match, ask the user to disambiguate).
+2. Set `work-id = plan-id` inferred from the file's folder.
+3. Parse the task file into a one-entry manifest.
+4. Read the task's `dependencies`; for each referenced `task-id`, read that upstream task file's `status`:
+   - If **all** upstream tasks are `completed`: no warning; proceed.
+   - If **any** upstream task is not `completed`: this is a Smart pause trigger. Ask the user one question:
+     ```
+     Task <id> depends on <upstream-ids> which are not yet completed.
+     What would you like to do?
+      - Proceed anyway: Run this task's Red→Green→Refactor cycle now
+      - Run upstream first: Execute the missing upstream task(s) before this one
+      - Abort: Stop and return to the Orchestrator
+     ```
+     - **Proceed anyway:** keep the single-task manifest; record `dependency-warning: proceeded-without-upstream`.
+     - **Run upstream first:** switch to the plan-based path (Step 2a) scoped to the unmet upstream tasks **plus** this task, in dependency order; record `dependency-warning: expanded-to-upstream`.
+     - **Abort:** stop and inform the Orchestrator.
+5. The manifest contains **only this one task** (plus any upstream tasks the user chose to add). It **never** includes downstream dependents of this task.
+
+#### 2c. Ad-hoc
+
+1. Allocate a fresh `work-id` of the form `YYYY-MM-DD-NNN`, counting existing `docs/tasks/YYYY-MM-DD-NNN/` folders for today (per [id-generation.md](../references/id-generation.md)).
+
+2. Resolve the raw description into task-shaped work — **one Acceptance Criterion per task, one test per task, Red-first**. For the resolution rules (problem-frame/intended-behavior collection, AC extraction, test-file assignment, sizing, dependency ordering, priority assignment), see **[ad-hoc-input-resolution.md](../references/ad-hoc-input-resolution.md)**. Minimally:
+   - Identify the problem frame and intended behavior from the description; if either is missing or vague, ask the user one question at a time to collect them.
+   - Derive 1–3 Acceptance Criteria, **one AC per task**. If a criterion would need > 5 files or > 1 day of effort, split it into finer sub-criteria (mirror the `/plan` task-slicing rules — one test per AC).
+   - For each task: assign a dedicated test file, populate `files.create`/`files.modify` from the description, and draft Red → Green → Refactor steps.
+   - Order tasks by dependency; assign priorities (`P0` / `P1` / `P2`).
+
+Do **not** write any files in this step — task-file materialization is deferred to Step 2e, so the work branch exists before anything is written (Step 2d).
+
+#### 2d. Work Branch Creation
+
+Every new feature or plan runs on its own git branch. This step runs for all input shapes, after the shape-specific resolution (2a/2b/2c) and **before any file is written** (the dirty-tree check must see the pre-work state).
+
+1. **Verify git repository:** confirm the working directory is inside a git repository (e.g., `git rev-parse --is-inside-work-tree`). If not, record `work-branch: null` with `work-branch-state: not-a-git-repo`, log one explicit warning, and skip the remaining sub-steps — the pipeline continues without a branch.
+
+2. **Derive the branch slug** for `work/<slug>`:
+   - plan-based / task-file: from the plan's kebab-case name suffix — `docs/plans/<plan-id>-<slug>.md` or the plan title registered in `docs/plans/index.md`.
+   - ad-hoc: from the resolved description — a 2–5 word kebab-case slug naming the work's subject (e.g., "fix login timeout" → `work/fix-login-timeout`).
+   - Sanitize: lowercase; replace every character outside `[a-z0-9]` with `-`; collapse repeated `-`; trim leading/trailing `-`; cap at 50 characters. If the result is empty, fall back to the `work-id`.
+   - If no slug can be confidently derived (vague ad-hoc description), ask the user one question: "What short name should the work branch use?" (accept the raw text and sanitize it). This is a Smart pause trigger.
+
+3. **Dirty working tree check:** the tree must be clean (`git status --porcelain` empty). If there are uncommitted changes, **fail branch creation with an explicit error** (Category 7 in [error-handling.md](../references/error-handling.md)) and ask the user one question: (a) I've committed/stashed — retry, (b) proceed without a work branch (`work-branch-state: skipped-by-user`), or (c) abort. Never stash, commit, or carry changes silently.
+
+4. **Determine the base branch:** detect the repository's default branch (e.g., resolve `origin/HEAD` → `main`); fall back to an existing `main`, then `master`, then the current HEAD.
+
+5. **Select or create the branch** (idempotent — resume-safe):
+   - Already on `work/<slug>` → no-op; `work-branch-state: already-on`.
+   - `work/<slug>` exists but is not checked out → check it out; `work-branch-state: checked-out`.
+   - Otherwise create it from the base branch (`git checkout -b work/<slug> <base>`); `work-branch-state: created`.
+   - When creating and the current HEAD is not the default branch: Smart pause trigger — ask one question: (a) create from the default branch, (b) create from the current HEAD, (c) abort. Autopilot: create from the default branch and log a warning.
+
+6. **Record** `work-branch` (branch name or `null`), `work-branch-base` (base used, or `null`), and `work-branch-state` (`created` | `checked-out` | `already-on` | `skipped-by-user` | `not-a-git-repo`) in the manifest (Step 6).
+
+#### 2e. Materialize Ad-Hoc Task Files
+
+Ad-hoc shape only (for plan-based/task-file, task files already exist — no-op):
+
+1. Materialize the resolved tasks as task files under `docs/tasks/<work-id>/`:
+   - Filename: `T<NN>-<kebab-case-name>.md` (`<NN>` zero-padded, matching dependency order).
+   - Schema: the [Task Artifact template](../../plan/references/templates/artifacts/task.md) — set `plan-id` to `work-id`, `status: not-started`; infer `tier` from task count per the `/plan` Fast/Standard/Deep sizing (Fast ≤ 3; Standard 4–8; Deep 8–15), defaulting to `fast`.
+   - Create `docs/tasks/<work-id>/index.md` with the `- [ ]` checklist for all tasks (same format as the `/plan` Tasks phase index).
+
+2. Build the manifest by reading the newly created task files back (confirming shape parity with plan-based tasks).
+
+### Step 3: Task Artifact Validation
+
+For every task in the resolved manifest, validate it preserves the `/plan` invariants:
+
+1. **One Acceptance Criterion per task** — the task carries exactly one `## Acceptance Criterion` and exactly one `files.test` entry.
+2. **Red-first steps** — `## Steps` are ordered Red → Green → Refactor, with the failing test written and confirmed before implementation.
+3. **Repository-relative paths** — all `files` entries are repo-relative and backtick-formatted; `files.test` holds exactly one path.
+4. **Dependency integrity** — every `dependencies` entry references a `task-id` that exists (in the manifest for plan-based/ad-hoc, or in the parent plan's index for task-file input).
+
+On any failure: never silently drop the task. Surface the specific failure and apply the recovery workflow in [error-handling.md](../references/error-handling.md) (Category 2 — Malformed Artifact): for plan-based/task-file, ask the user to fix the task or re-run the relevant `/plan` phase; for ad-hoc, regenerate the offending task from Step 2c.
+
+### Step 4: Dependency & Resume Check
+
+1. Read each manifest task's current `status` from its task file frontmatter.
+2. **Resume-safe filtering:** a task is `ready` only if all its dependencies are `completed`. Tasks already `completed` are skipped (never re-opened — index checkboxes are ticked forward only). Tasks `blocked` or `skipped` are carried as-is with their recorded reasons.
+3. Record the manifest's `ready-tasks` (to run this session) and `already-complete-tasks` (carried for the Work Report).
+4. If **no** task is `ready` (all blocked or already complete), record `work-state: nothing-ready` and proceed to Step 6 — the Work Report will surface that no work was runnable. Do **not** abort; the Review phase handles the empty outcome.
+
+### Step 5: Learnings Index Gate
+
+Search `docs/learn/index.md` for entries relevant to the task domains in the manifest. For the matching logic (keyword extraction, exact + fuzzy match, HIGH/MEDIUM/LOW relevance scoring, gap identification, and inclusion), defer to the Plan skill's **[learnings-gate-logic.md](../../plan/references/learnings-gate-logic.md)**.
+
+- Add HIGH and MEDIUM relevance learnings to the manifest's `Related Learnings`, scoped **per task** (a learning applies to a task, not the whole manifest — mirror the `/plan` Tasks phase, which embeds learnings in each task's `## Notes`).
+- Identify and document any `Learning Gaps`.
+
+> This gate reuses the Plan skill's learnings-matching algorithm; it does not duplicate it. If `docs/learn/index.md` does not exist (arreio-init not yet run), set `Related Learnings` to empty and continue — do not block the work pipeline on a missing learnings index. But log a single explicit warning so the absence is visible rather than silently no-op'd.
+
+### Step 6: Generate the Work Manifest Artifact
+
+1. **Assign a `triage-id`** per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-triage`, saved to `docs/plans/.work/.triage/`). Reuse it if the user later picks **Edit & Retry**.
+
+2. Produce a **Work Manifest Artifact** block (as markdown) following the schema in [work-manifest.md](../references/templates/artifacts/work-manifest.md). Include:
+   - `triage-id`, `work-id`, `input-shape`, `interactionMode`, `work-branch` (plus `work-branch-base` and `work-branch-state` from Step 2d)
+   - the resolved task list (one row per task: `task-id`, `title`, `unit`, `acceptance-criterion`, `priority`, `dependencies`, `status`, `ready?`)
+   - `ready-tasks` and `already-complete-tasks`
+   - `Related Learnings` (per task) and `Learning Gaps`
+   - any `dependency-warning` (task-file shape only)
+   - `work-state` (`nothing-ready`, if applicable)
+
+### Step 7: Present, Confirm, and Save
+
+Apply the **[phase confirmation behavior](../references/interaction-mode-propagation.md)** for the current `interactionMode`, using these triage-specific **Smart pause triggers**:
+
+- `input-shape` is `ad-hoc` (the resolved task list was **inferred**, not user-authored — confirm it matches intent), or
+- Task-file input has an unmet upstream dependency (Step 2b warning case), or
+- One or more task artifacts failed validation (Step 3) and required recovery, or
+- The work branch slug could not be derived automatically and was supplied by the user (Step 2d.2), or
+- The current HEAD was not the default branch when the work branch was created (Step 2d.5).
+
+- **Detailed:** present the Work Manifest Artifact and ask one question with options *(1) Proceed to Prepare, (2) Edit & Retry, (3) Abort*. On **Edit & Retry**, loop back through Steps 1–6 reusing the `triage-id`. On **Abort**, stop and inform the Orchestrator.
+- **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/.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).
+
+## Output: Work Manifest Artifact
+
+- Verify that the Work Manifest Artifact is complete and valid: `triage-id`, `work-id`, `input-shape`, `interactionMode`, the resolved task list, `ready-tasks`, `Related Learnings`, and any `dependency-warning`.
+- Verify that every task in the manifest carries **exactly one Acceptance Criterion**, **exactly one `files.test`**, and **Red → Green → Refactor** steps (Step 3 passed).
+- Verify that the manifest is in **dependency order** — no task appears before its dependencies.
+- Verify that `work-id` is correct for the shape (inherited `plan-id` for plan-based/task-file; freshly allocated for ad-hoc).
+- Verify that `work-branch` is recorded in the manifest and, unless `null`, the repository is checked out on that branch.
+- Verify that for `ad-hoc` input, the task files and `docs/tasks/<work-id>/index.md` were created.
+- Verify that the artifact is saved to `docs/plans/.work/.triage/<triage-id>.md`.
+
+> Pass the Work Manifest to `prepare` (Phase 2) for execution-mode selection and sequencing.

package/skills/work/references/ad-hoc-input-resolution.md

@@ -0,0 +1,122 @@
+---
+title: Ad-Hoc Input Resolution
+description: Authoritative reference for the Triage phase. Defines how a raw work description is resolved into task-shaped work (one Acceptance Criterion per task, one test per task, Red-first), including problem-frame collection, AC extraction, sizing, dependency ordering, and priority assignment.
+type: reference
+version: 1.0
+timestamp: "2026-08-07"
+---
+
+# Ad-Hoc Input Resolution
+
+Authoritative reference for the **Triage** phase (Step 2c). Defines how a raw work description (bug, feature, change) is resolved into the same task-shaped work the `/plan` Tasks phase produces — **one Acceptance Criterion per task, one test per task, Red → Green → Refactor** — so ad-hoc work is fully interchangeable with plan-based work downstream.
+
+## Core Rule (mirrors `/plan`)
+
+- **One Acceptance Criterion per task.** Each derived task carries exactly one `## Acceptance Criterion` and exactly one `files.test` entry (its own test asserting that criterion).
+- **One test per task.** Never one test asserting multiple criteria. Never one task bundling multiple criteria.
+- **Red-first.** Each task's `## Steps` are ordered Red → Green → Refactor, with the failing test written and confirmed before implementation.
+
+## Resolution Steps
+
+### 1. Collect the Problem Frame and Intended Behavior
+
+If the description is missing or vague on either, ask the user one question at a time:
+
+1. **Problem Frame:** "What problem are you trying to solve? Describe it in 1–2 sentences." (maps to the task's `## Goal`)
+2. **Intended Behavior:** "What should happen after this is implemented? Describe the desired outcome." (maps to the observable outcome)
+3. **Success Criteria:** "How will we know this is complete? What specific outcomes define success?" Collect 1–3 criteria.
+
+If both are present and concrete from the description, extract them and skip the prompts.
+
+### 2. Extract Acceptance Criteria
+
+Derive 1–3 Acceptance Criteria from the success criteria — **one AC per task**. Phrase each as a single, verifiable outcome (not a bundle). If a criterion would need > 5 files or > 1 day of effort, **split it into finer sub-criteria** (each its own task) rather than slicing a task partway through a criterion (mirror the `/plan` task-slicing Rule 2). Sub-IDs use letters: `U1` → `T01a`, `T01b` (never extra digits).
+
+### 3. Assign Files Per Task
+
+For each task, populate from the description and a read of the codebase:
+
+- `files.create` — new files the implementation needs.
+- `files.modify` — existing files touched.
+- `files.test` — **exactly one** dedicated test file for this task's single AC; resolved repo-relative.
+
+At least one of `create`, `modify`, or `test` must be non-empty. All paths repository-relative, backtick-formatted in the task file.
+
+### 4. Draft Steps (Red → Green → Refactor)
+
+For each task, draft the three steps:
+
+1. **Red** — write the failing test in `files.test[0]` asserting this AC; confirm it fails for the right reason.
+2. **Green** — implement the minimum code in `files.create`/`files.modify` to make the test pass.
+3. **Refactor** — clean up naming, duplication, and structure while keeping the test green.
+
+### 5. Order by Dependencies
+
+Order tasks so each task's dependencies are satisfied by earlier tasks (topological order, stable by original unit number):
+
+```
+1. Start with all tasks as "remaining".
+2. Find tasks whose dependencies are all already ordered -> "ready".
+3. If none ready: a cycle exists -> surface to the user (break or abort).
+4. Sort ready tasks by original unit number; append to "ordered".
+5. Repeat until all tasks are ordered.
+```
+
+### 6. Assign Priorities
+
+| Priority | Criteria                                           |
+| -------- | -------------------------------------------------- |
+| P0       | Blocks all other tasks (foundation, infra, schema) |
+| P1       | On the critical path but not blocking              |
+| P2       | Can be deferred or parallelized                    |
+
+### 7. Infer Tier (for task frontmatter)
+
+Infer the `/plan` tier from the derived task count:
+
+| Tier     | Task count | Max files/task | Max effort/task |
+| -------- | ---------- | -------------- | --------------- |
+| fast     | 1–3        | 3              | Half day        |
+| standard | 4–8        | 5              | 1 day           |
+| deep     | 8–15       | 5              | 1 day           |
+
+Default to `fast` when task count ≤ 3. The tier is recorded in each task's frontmatter (`tier` field) for traceability with `/plan` task files; it does not change Work's behavior (Work runs tasks identically regardless of tier).
+
+## Materialization
+
+After resolution, materialize the tasks as files (Triage Step 2c.3):
+
+- **Filename:** `docs/tasks/<work-id>/T<NN>-<kebab-case-name>.md` (`<NN>` zero-padded 2 digits matching dependency order).
+- **Schema:** the `/plan` [Task Artifact template](../../plan/references/templates/artifacts/task.md) — set `plan-id` to `work-id`, `status: not-started`, the inferred `tier`.
+- **Index:** create `docs/tasks/<work-id>/index.md` with the `- [ ]` checklist for all tasks (same format as the `/plan` Tasks phase index).
+
+Then build the manifest by reading the created files back (confirming shape parity with plan-based tasks).
+
+## Validation (Triage Step 3 re-checks)
+
+Each derived task must pass before the manifest is accepted:
+
+- exactly one `## Acceptance Criterion` and exactly one `files.test`
+- Red → Green → Refactor step ordering, test written and confirmed first
+- repository-relative, backtick-formatted paths
+- dependencies reference task-ids that exist in the manifest
+
+On any failure, regenerate the offending task from Step 2 onward (Category 2 recovery per [error-handling.md](error-handling.md)).
+
+## Smart Pause Triggers
+
+Triage pauses in Smart mode when the input shape is `ad-hoc` (the resolved task list was **inferred**, not user-authored — confirm it matches intent). This is the ad-hoc-specific trigger; see Triage Step 7 for the full list.
+
+## Error Handling
+
+| Scenario                                   | Recovery                                              |
+| ------------------------------------------ | ----------------------------------------------------- |
+| Description empty or unobservable          | Ask the user the problem-frame/intended-behavior prompts |
+| A criterion needs > 5 files / > 1 day       | Split into finer sub-criteria (Step 2)                |
+| Dependency cycle among derived tasks        | Surface to the user; ask to break or abort             |
+| `docs/tasks/<work-id>/` write fails         | Category 4 recovery per [error-handling.md](error-handling.md) |
+
+## Notes
+
+- This reference reuses the `/plan` task-slicing heuristics (one AC per task, sub-ID letters, topological order, P0/P1/P2) so ad-hoc tasks are indistinguishable from `/plan`-produced tasks.
+- The resolved tasks inherit the same Task Artifact schema as `/plan`, so Execute and Review treat them identically to plan-based tasks.