arreio 1.0.0-dev.1

package/skills/review/references/templates/artifacts/review-report.md

@@ -0,0 +1,175 @@
+---
+title: Review Report Artifact
+description: Template for the Review Report Artifact produced by the Report phase. Carries the approval status (approved / changes-requested / rejected) with rationale, the findings rollup (counts by severity and by category), non-binding recommendations, the scope-creep summary, learnings-to-capture for /learn, and the registry/work-index registration state. The Review skill's final deliverable.
+type: template
+version: 1.0
+timestamp: "2026-08-08"
+---
+
+# Review Report Artifact
+
+The product of the **Report** phase is the Review Report — the Review skill's final deliverable. It records the **approval status** (`approved` / `changes-requested` / `rejected`) derived deterministically from the Findings tallies per [approval-criteria.md](../../approval-criteria.md), with a one-line rationale tied to the counts; the findings rollup (by severity and by category); non-binding **recommendations**; the **scope-creep summary**; **learnings-to-capture** candidates (handed to `/learn`); and the registration state. A registry row is appended to `docs/plans/.review/index.md` always; for work-linked input, a distinct `## Review Report — <report-id>` block is appended to `docs/tasks/<work-id>/index.md`.
+
+## Schema
+
+```yaml
+report-id: YYYY-MM-DD-NNN-report
+analyze-id: YYYY-MM-DD-NNN-analyze
+prepare-id: YYYY-MM-DD-NNN-prepare
+scope-id: YYYY-MM-DD-NNN-scope
+review-id: YYYY-MM-DD-NNN
+input-shape: change-set | work-linked | ad-hoc
+interactionMode: detailed | smart | autopilot
+status: complete
+timestamp: ISO-8601 timestamp
+
+approval-status: approved | changes-requested | rejected
+rationale: "[one-line, tied to the driving counts]"
+
+findings-rollup:
+  by-severity: { blocker: <N>, major: <N>, minor: <N>, nit: <N> }
+  by-category: { quality: <N>, security: <N>, tests: <N>, documentation: <N>, integration: <N>, scope-creep: <N> }
+  total: <N>
+
+recommendations:
+  blocking: [ "F<NN> @ <location>: <action>"          # for changes-requested/rejected — actionable blocker/major fixes
+            | null ]
+  polish: [ "F<NN> @ <location>: <optional improvement>"    # for approved (minor/nit) suggestions
+          | null ]
+
+scope-creep-summary: none | "<count> finding(s)" | "skipped (no requirements)"
+
+learnings-to-capture:
+  - title: "[working title]"
+    domain: [primary domain]
+    source: { finding-id }            # the finding id where this surfaced
+    summary: "[1-2 sentence summary]"
+    type: confirmed-pattern | refuted-assumption | gotcha | forced-decision
+
+learning-gaps:
+  - gap_name: "[Domain] — [what's missing]"
+    domain: [primary domain]
+    suggested_action: "Research external resource" | "Document post-review"
+
+work-id: YYYY-MM-DD-NNN | null          # work-linked only; null otherwise
+
+registration:
+  registry-row-appended: true          # appended to docs/plans/.review/index.md (idempotent on report-id)
+  work-index-block-appended: true | skipped   # work-linked only; skipped if the work index is missing
+```
+
+Also save the Review Report to `docs/plans/.review/.report/<report-id>.md`.
+
+## Closing Blocks
+
+### Registry row (appended to `docs/plans/.review/index.md`, always)
+
+```
+- <report-id> — <target-summary> — <approval-status> — docs/plans/.review/.report/<report-id>.md
+```
+
+### Work-index block (appended to `docs/tasks/<work-id>/index.md`, work-linked only)
+
+```markdown
+## Review Report — <report-id>
+
+- **Status:** approved | changes-requested | rejected
+- **Findings:** <blocker> blocker, <major> major, <minor> minor, <nit> nit
+- **Scope creep:** none | <count> | skipped (no requirements)
+- **Learnings to capture:** <count> (run `/learn` to persist)
+- **Review Report:** docs/plans/.review/.report/<report-id>.md
+```
+
+Both the registry row and the work-index block are **append-only** and **idempotent on `report-id`**: a re-run overwrites the entry with the same id, never duplicates it. The work-index block is deliberately distinct from Work's own `## Work Report — <review-id>` block (different label, different skill, different `report-id`).
+
+## Validation Rules
+
+- **report-id:** Required. Format `YYYY-MM-DD-NNN-report`.
+- **analyze-id, prepare-id, scope-id, review-id, input-shape:** Required, inherited (cross-phase consistency).
+- **interactionMode:** Required, identical across Prepare/Analyze/Report (orchestrator quality gate #2).
+- **approval-status:** Required. One of `approved`, `changes-requested`, `rejected`, derived per [approval-criteria.md](../../approval-criteria.md) (the derivation is non-discretionary: `rejected` iff blocker ≥ 1; `changes-requested` iff no blocker and (major ≥ 1 or scope-creep present); `approved` otherwise).
+- **rationale:** Required. One line surfacing the driving counts.
+- **findings-rollup:** Required. Counts by severity and by category must match the Findings artifact's tallies.
+- **recommendations:** Required. `blocking` populated for `changes-requested`/`rejected` (actionable blocker/major fixes); `polish` populated for `approved` (minor/nit). Either list may be empty (e.g. a genuinely clean approved review has `blocking: null`, `polish: []`).
+- **scope-creep-summary:** Required. `none`, `"<count> finding(s)"`, or `skipped (no requirements)` (consistent with the Findings `scope-creep-ran`).
+- **learnings-to-capture:** Required (may be empty). Each candidate has title/domain/source/summary/type. Review does not write `docs/learn/` directly — these are handed to `/learn`.
+- **learning-gaps:** Required (may be empty).
+- **work-id:** Required for work-linked input (and the work-index block is then expected); `null` otherwise (and the work-index block is `skipped`).
+- **registration.registry-row-appended:** Required, must be `true`.
+- **registration.work-index-block-appended:** Required for work-linked input (`true` or `skipped`); `skipped` for other input.
+- **status:** Required. `complete`.
+
+## Example (changes-requested — two majors, one scope-creep)
+
+```yaml
+report-id: 2026-08-08-001-report
+analyze-id: 2026-08-08-001-analyze
+prepare-id: 2026-08-08-001-prepare
+scope-id: 2026-08-08-001-scope
+review-id: 2026-08-08-001
+input-shape: change-set
+interactionMode: smart
+status: complete
+timestamp: 2026-08-08T15:45:00Z
+approval-status: changes-requested
+rationale: "2 major finding(s) and 1 scope-creep finding(s); no blocker"
+findings-rollup:
+  by-severity: { blocker: 0, major: 2, minor: 1, nit: 0 }
+  by-category: { quality: 1, security: 0, tests: 1, documentation: 0, integration: 0, scope-creep: 1 }
+  total: 3
+recommendations:
+  blocking:
+    - "F01 @ src/lib/session-store.ts:22: Add tests for get/save/delete per C2"
+    - "F02 @ src/lib/cache.ts:hunk-1: Split the cache layer off into its own task or roll back"
+  polish:
+    - "F03 @ src/lib/redis-client.ts:42: Extract MAX_RETRIES constant"
+scope-creep-summary: "1 finding(s)"
+learnings-to-capture:
+  - title: "TTL cache layers tend to creep into session-store changes — split before estimating"
+    domain: data-storage
+    source: { finding-id: F02 }
+    summary: "Scope-creep finding F02 recurred; confirming the pattern of cache layers bundling into session work."
+    type: confirmed-pattern
+learning-gaps: []
+work-id: null
+registration:
+  registry-row-appended: true
+  work-index-block-appended: skipped
+```
+
+## Example (approved — clean review)
+
+```yaml
+report-id: 2026-08-08-002-report
+analyze-id: 2026-08-08-002-analyze
+prepare-id: 2026-08-08-002-prepare
+scope-id: 2026-08-08-002-scope
+review-id: 2026-08-08-002
+input-shape: ad-hoc
+interactionMode: autopilot
+status: complete
+timestamp: 2026-08-08T15:50:00Z
+approval-status: approved
+rationale: "no blocker, no major, no scope-creep (0 minor, 0 nit)"
+findings-rollup:
+  by-severity: { blocker: 0, major: 0, minor: 0, nit: 0 }
+  by-category: { quality: 0, security: 0, tests: 0, documentation: 0, integration: 0, scope-creep: 0 }
+  total: 0
+recommendations:
+  blocking: null
+  polish: []
+scope-creep-summary: "skipped (no requirements)"
+learnings-to-capture: []
+learning-gaps: []
+work-id: null
+registration:
+  registry-row-appended: true
+  work-index-block-appended: skipped
+```
+
+## Notes
+
+- The Review Report is the primary deliverable of the Review skill. The Orchestrator marks the workflow complete and may chain to `/learn` when `learnings-to-capture` is non-empty.
+- Approval is **non-discretionary**: the same tallies always produce the same status. Reviewer judgment lives in finding severities and the scope-creep flag, not in the approval derivation (see [approval-criteria.md](../../approval-criteria.md)).
+- **No GitHub sync:** this skill does not post comments/reviews/labels. The registry row + (work-linked) work-index block are the only outbound writes — both local, both on disk.
+- For work-linked input, Review's `approval-status` is **independent** of Work's own `work-state`; the two verdicts coexist (the `## Review Report` block sits next to Work's `## Work Report` block).

package/skills/review/references/templates/artifacts/review-scope.md

@@ -0,0 +1,146 @@
+---
+title: Review Scope Artifact
+description: Template for the Review Scope Artifact produced by the Scope phase. Carries the resolved change boundary (required files with status + context callers + attribution), the requirements source and parsed spec-content, the preliminary scope-creep check, related learnings, and the allocated review-id umbrella; consumed by Prepare.
+type: template
+version: 1.0
+timestamp: "2026-08-08"
+---
+
+# Review Scope Artifact
+
+The product of the **Scope** phase is a resolved Review Scope: a concrete **change boundary** (`required` files with status, an optional `context` list, an `attribution`/`diff-source`), the resolved **requirements source** (and parsed `spec-content` when present), the **preliminary scope-creep** check, related learnings, and the allocated **`review-id` umbrella** (Scope is the allocating phase). Prepare consumes it.
+
+## Schema
+
+```yaml
+scope-id: YYYY-MM-DD-NNN-scope
+review-id: YYYY-MM-DD-NNN                 # umbrella id, allocated here, carried through all 4 artifacts
+input-shape: change-set | work-linked | ad-hoc
+interactionMode: detailed | smart | autopilot
+status: complete
+timestamp: ISO-8601 timestamp
+
+change-boundary:
+  required:
+    - path: "src/lib/redis-client.ts"
+      status: added | modified | deleted | renamed
+      renamed-from: "<old path>"          # only for renamed
+      tentative: false | true             # true only for work-linked blocked/skipped-task files
+  context:
+    - path: "src/api/session.ts"
+      role: "caller of redis-client.connect()"
+  attribution: commits | working-tree | task-files | current-contents
+  empty: false                            # true when a spec parses but touches no files
+  diff-source: "<base>..<head>" | working-tree | working-tree-fallback | current-contents
+
+requirements-source:
+  type: plan-id | task-criterion | spec-doc | none
+  path: "<repo-relative path> | none"
+  spec-content:                            # only when type != none
+    - criterion: "C1: <short criterion>"
+      expected-behavior:
+        - "<observable behavior>"
+        - "<observable behavior>"
+
+preliminary-scope-creep: [ { file, candidate-reason } ] | none | "skipped (no requirements)"
+
+related-learnings:                         # scoped to the change boundary (whole review, not per file)
+  - "docs/learn/XXX.md — [1-line applicability note]"
+
+learning-gaps:
+  - gap_name: "[Domain] — [what's missing]"
+    domain: [primary domain]
+    relevance: why this matters for the review
+    suggested_action: "Research external resource" | "Document post-review"
+
+work-id: YYYY-MM-DD-NNN | null             # work-linked only, for the index cross-link; null otherwise
+```
+
+Also save the Review Scope to `docs/plans/.review/.scope/<scope-id>.md`.
+
+## Validation Rules
+
+- **scope-id:** Required. Format `YYYY-MM-DD-NNN-scope`.
+- **review-id:** Required. Allocated by Scope (umbrella); format `YYYY-MM-DD-NNN`. For work-linked, **distinct from** any Work `review-id` (the two skills' artifacts are independent; `work-id` is carried separately here).
+- **input-shape:** Required. One of `change-set`, `work-linked`, `ad-hoc`.
+- **interactionMode:** Required, propagated from the Review Input Artifact.
+- **status:** Required. `complete`.
+- **change-boundary.required:** Required (may be empty only when `empty: true`). Each entry has a repo-relative `path` and a `status`; `renamed-from` only for `renamed`; `tentative: true` only for work-linked blocked/skipped-task files.
+- **change-boundary.context:** Required (may be empty). Separated from `required`; each entry has a repo-relative `path` and a one-line `role`.
+- **change-boundary.attribution & diff-source:** Required and consistent (`commits` ⇄ real range; `current-contents` ⇄ `current-contents`).
+- **change-boundary.empty:** Required. `true` is accepted (nothing-to-review; Prepare/Analyze/Report carry the empty outcome through); never silently empty.
+- **requirements-source.type:** Required. One of `plan-id`, `task-criterion`, `spec-doc`, `none`.
+- **spec-content:** Required present when `type != none` (a structured list); omitted/empty when `type: none`.
+- **preliminary-scope-creep:** Required. A list, `none`, or `skipped (no requirements)` — the last only when `requirements-source.type: none`.
+- **related-learnings:** Required (may be empty). References `docs/learn/index.md` entries.
+- **learning-gaps:** Required (may be empty).
+- **work-id:** Required (= the `work-id`) for work-linked input; `null` otherwise.
+
+## Example (change-set, with requirements)
+
+```yaml
+scope-id: 2026-08-08-001-scope
+review-id: 2026-08-08-001
+input-shape: change-set
+interactionMode: smart
+status: complete
+timestamp: 2026-08-08T14:30:00Z
+change-boundary:
+  required:
+    - { path: "src/lib/redis-client.ts", status: added, tentative: false }
+    - { path: "src/lib/session-store.ts", status: modified, tentative: false }
+  context:
+    - { path: "src/api/session.ts", role: "caller of session-store.get()" }
+  attribution: commits
+  empty: false
+  diff-source: "main..feature/redis-session"
+requirements-source:
+  type: plan-id
+  path: "docs/plans/2026-07-10-001-redis-session-store.md"
+  spec-content:
+    - criterion: "C1: Redis client connects with retry"
+      expected-behavior:
+        - "connect() reads REDIS_URL"
+        - "connect() retries up to 3 times on connection failure"
+    - criterion: "C2: SessionStore exports get/save/delete"
+      expected-behavior:
+        - "get(key) returns the stored value or null"
+preliminary-scope-creep: none
+related-learnings:
+  - "docs/learn/pattern/redis-retry-2026-07-02.md — connection retry pattern applies"
+learning-gaps: []
+work-id: null
+```
+
+## Example (work-linked, no requirements ref)
+
+```yaml
+scope-id: 2026-08-08-002-scope
+review-id: 2026-08-08-002
+input-shape: work-linked
+interactionMode: detailed
+status: complete
+timestamp: 2026-08-08T15:00:00Z
+change-boundary:
+  required:
+    - { path: "src/lib/redis-config.ts", status: added, tentative: false }
+    - { path: "src/lib/redis-client.ts", status: modified, tentative: true }
+  context: []
+  attribution: task-files
+  empty: false
+  diff-source: working-tree-fallback
+requirements-source:
+  type: none
+  path: none
+preliminary-scope-creep: "skipped (no requirements)"
+related-learnings: []
+learning-gaps: []
+work-id: 2026-07-10-001
+```
+
+## Notes
+
+- Scope is the **allocating phase** for the `review-id` umbrella; Prepare/Analyze/Report inherit it. The `review-id` shares the scope counter's NNN (see [id-generation.md](../../id-generation.md)).
+- `required` vs `context` is a hard separation: Analyze files findings only against `required` files; `context` is reviewer aid.
+- `requirements-source.type: none` is a legitimate input (the scope-creep category is skipped with a recorded note) — not an error (see [error-handling.md](../../error-handling.md)).
+- `tentative: true` flags work-linked blocked/skipped-task files so Analyze treats their findings with the note that the file may be partial.

package/skills/work/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: work
+description: "Execute implementation work through a deterministic pipeline of micro-skills: Triage -> Prepare -> Execute -> Review. Consumes /plan task artifacts, a single task file, or ad-hoc work input; runs each task test-first (Red -> Green -> Refactor) and updates task status and the index checklist. No agent dependency, no fallback paths."
+disable-model-invocation: true
+---
+
+# Work
+
+Orchestrates a deterministic pipeline of micro-skills: `Triage -> Prepare -> Execute -> Review`. Consumes `/plan` task artifacts, a single task file, **or** ad-hoc work input, executes each task test-first (Red → Green → Refactor), and updates task status and the `docs/tasks/<id>/index.md` checklist. No agent dependency, no fallback paths.
+
+## Skill Invocation
+
+This skill is invoked by prompting:
+
+- `/work <plan-id>` — execute the task list for an existing plan, sourced from `docs/tasks/<plan-id>/index.md` (produced by the `/plan` Tasks phase).
+- `/work <task file>` — execute a single task file (e.g. `docs/tasks/<plan-id>/T<NN>-<name>.md`, or a task-id like `<plan-id>-T03`). Runs **only that one task's** Red → Green → Refactor cycle, never its downstream dependents.
+- `/work <task description>` — execute ad-hoc work; Triage resolves the description into an executable task list (no full plan required).
+
+This skill runs the work pipeline, executing tasks and updating artifacts, acting as the Orchestrator.
+
+## Interaction Method
+
+- Ask the user one structured question at a time (2–4 concrete options) using the agent's interactive question capability; never hardcode a specific tool name.
+- If input is empty, ask: "What would you like to work on? Provide a plan-id, a task file, or describe the task."
+
+Before starting the workflow, ask the user to choose an interaction mode:
+
+- **Detailed** — Confirm at each phase transition and before each task's destructive step; inspect artifacts; maximum control. Best for HIGH-risk or unfamiliar work.
+- **Autopilot** — All phases run automatically; only the final Work Report is presented. Fastest. Best for straightforward, well-planned task lists.
+- **Smart** — Phases run automatically; pause only on HIGH-risk operations or tasks that fail their gates.
+
+Store in the context object:
+
+```yaml
+interactionMode: detailed | smart | autopilot
+```
+
+**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).
+
+> **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.
+
+## Orchestration Implementation
+
+Each phase runs sequentially: the orchestrator calls the phase module, receives the output artifact, validates it with a quality gate, and passes it to the next phase.
+
+### INPUT
+
+- Receives a context object (a plan-id, a task file, **or** a raw work description, plus optional goals, constraints, references) from the user, a saved prompt, a document, or a combination.
+- **Three input shapes:**
+  1. **Plan-based** — a `plan-id` referencing `docs/tasks/<plan-id>/index.md`. Executes the full task list in dependency order. Each task carries exactly one Acceptance Criterion, one test file, and Red → Green → Refactor steps (as produced by `/plan`'s Tasks phase).
+  2. **Task-file** — a path to a single task file (e.g. `docs/tasks/<plan-id>/T<NN>-<name>.md`) or a task-id (e.g. `<plan-id>-T03`). Executes **only that one task's** Red → Green → Refactor cycle, never its downstream dependents. `work-id` is inherited from the file's folder (the `plan-id`). Before running, Triage checks the task's `dependencies`: if any upstream task is **not** `completed`, it warns and asks the user whether to (a) proceed anyway, (b) run the missing upstream task(s) first, or (c) abort.
+  3. **Ad-hoc** — a raw work description (bug, feature, change). Triage classifies it and resolves it into the same task-shaped work (one AC → one task → one test, Red-first), registered under a fresh `work-id` at `docs/tasks/<work-id>/`.
+- **If no context is provided**, ask: "What would you like to work on? Provide a plan-id, a task file, or describe the task."
+- **Unified key:** downstream phases always key off a `work-id`. For plan-based and task-file input, `work-id = plan-id` (the task file's folder). For ad-hoc input, Triage allocates a `work-id` of the form `YYYY-MM-DD-NNN` (counting existing `docs/tasks/YYYY-MM-DD-NNN/` folders for that date), reusing the plan-id format so the `docs/tasks/<id>/` convention holds uniformly. The task manifest differs by shape (full list vs single task vs resolved list), but the artifact and index paths are identical.
+- Output: [Work Input Artifact](references/templates/artifacts/work-input.md)
+
+### Pre-Flight Check
+
+Before starting the work pipeline, the orchestrator verifies that required folders exist:
+
+- `docs/tasks/` — must exist for reading (plan-based) or creating (ad-hoc) the task list
+- `docs/plans/.work/.triage/`, `docs/plans/.work/.prepare/`, `docs/plans/.work/.execute/`, `docs/plans/.work/.review/` — must exist for saving the four phase artifacts
+
+**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.
+
+For plan-based input, additionally verify that `docs/tasks/<plan-id>/index.md` exists and is non-empty; if not, ask the user to run `/plan <plan-id>` (with the Tasks phase) first or switch to ad-hoc input.
+
+For task-file input, verify the task file exists and parses with valid task frontmatter (`id`, `plan-id`, `status`, `files.test`); infer `plan-id` from its folder. If missing or malformed, ask the user to locate the file or re-run the relevant `/plan` Tasks phase.
+
+### Work Branch
+
+Every new feature or plan runs on its own git branch:
+
+- **Name:** `work/<short-description>` — a kebab-case slug derived from the plan name (plan-based/task-file) or the work description (ad-hoc), capped at 50 characters.
+- **When:** created or checked out in Triage (Step 2d), right after the `work-id` is resolved and **before any task file or index is written**.
+- **Idempotent:** re-running Work resumes on the same branch (already on it → no-op; branch exists → check it out; otherwise create from the default branch).
+- **Dirty working tree:** uncommitted changes fail branch creation with an explicit error — never stashed, committed, or carried silently.
+- **Not a git repository:** one explicit warning; the pipeline continues without a branch (`work-branch: null`).
+- **Recording:** the branch name is stored as `work-branch` in the Work Manifest (with `work-branch-base` and `work-branch-state`) and carried through the Prepare/Execute/Review artifacts; the orchestrator's quality gate verifies branch coherence before Execute.
+
+### Phases
+
+| Phase | Phase Module                  | Output Artifact                                                    | Saved to                            |
+| ----- | ----------------------------- | ------------------------------------------------------------------ | ----------------------------------- |
+| 1     | [Triage](modules/triage.md)   | [Work manifest](references/templates/artifacts/work-manifest.md) + `work/<slug>` branch | `docs/plans/.work/.triage/<id>.md`  |
+| 2     | [Prepare](modules/prepare.md) | [Execution plan](references/templates/artifacts/execution-plan.md) | `docs/plans/.work/.prepare/<id>.md` |
+| 3     | [Execute](modules/execute.md) | [Execution log](references/templates/artifacts/execution-log.md)   | `docs/plans/.work/.execute/<id>.md` |
+| 4     | [Review](modules/review.md)   | [Work report](references/templates/artifacts/work-report.md)       | `docs/plans/.work/.review/<id>.md`  |
+
+### Quality Gates
+
+Between phases, the orchestrator validates the output artifact before passing it to the next phase:
+
+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 (`work-id`, `triage-id`, `prepare-id`, `execute-id`, `review-id`) match the upstream artifacts; `interactionMode` and `executionMode` are identical across artifacts.
+3. **Status check** — the artifact's `status` is `complete` (not `pending` or `failed`).
+4. **Task-status coherence** (after Execute) — every task in the work list is `completed`, `blocked` (with a recorded reason), or `skipped` (with a recorded reason); the `docs/tasks/<work-id>/index.md` checklist state matches the task files' frontmatter `status`. No task is left `in-progress`.
+5. **Branch coherence** (after Triage, before Execute) — when `work-branch` is not `null`, the repository's current branch matches the Work Manifest's `work-branch`; a mismatch returns to Triage with the error context.
+
+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)).
+
+### Index Registration
+
+Each phase is responsible for its own index updates:
+
+| Phase   | Registers To                                     | Update                                                                                                                                                                |
+| ------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Triage  | `docs/tasks/<work-id>/index.md`                  | Ad-hoc only: create folder + index with the resolved task checklist (`- [ ]`). Plan-based: read only.                                                                 |
+| Execute | `docs/tasks/<work-id>/index.md` + each task file | Flip frontmatter `status` and the task file's `## Acceptance Criteria` checkbox; tick the index checklist (`- [ ]` → `- [x]`) as tasks complete. Idempotent on retry. |
+| Review  | `docs/tasks/<work-id>/index.md`                  | Append a closing `## Work Report — <review-id>` status block; optionally note learnings to capture via `/learn`.                                                      |
+
+**Idempotency rule:** re-running Work resumes from incomplete tasks. The orchestrator reads each task file's `status`; a `completed` task is never re-opened, and index checkboxes are only ticked forward, never reset.
+
+### FINAL OUTPUT
+
+- **Task files:** Updated at `docs/tasks/<work-id>/T<NN>-<name>.md` with final `status` (`completed` / `blocked` / `skipped`) — frontmatter and the `## Acceptance Criteria` checkbox both updated.
+- **Task index:** `docs/tasks/<work-id>/index.md` checklist ticked to match task outcomes (`- [x]` complete; remaining `- [ ]` for `blocked`/`skipped`).
+- **Work branch:** `work/<short-description>` created (or checked out) during Triage Step 2d, recorded as `work-branch` in the Work Manifest; re-runs resume on the same branch.
+- **Work Report:** Saved to `docs/plans/.work/.review/<review-id>.md`, with a consolidation/simplification summary, test-regression check, any scope-creep notes, and learnings surfaced for `/learn`.
+- **(Optional) Learnings:** New learnings discovered during execution are handed to the Learn skill (`/learn`) to persist — Work does not write `docs/learn/` directly.
+
+## References
+
+The orchestrator and phase modules share these reference files:
+
+| Reference                                                                     | Used By                                                                             |
+| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| [error-handling.md](references/error-handling.md)                             | All phases (Step 0 verification)                                                    |
+| [id-generation.md](references/id-generation.md)                               | Triage, Prepare, Execute, Review (ID assignment, including `work-id` allocation)    |
+| [interaction-mode-propagation.md](references/interaction-mode-propagation.md) | All phases (Step N confirmation)                                                    |
+| [execution-mode-selection.md](references/execution-mode-selection.md)         | Prepare (choose inline / serial / parallel)                                         |
+| [ad-hoc-input-resolution.md](references/ad-hoc-input-resolution.md)           | Triage (resolve raw work into task-shaped work)                                     |
+| [task-execution-rules.md](references/task-execution-rules.md)                 | Execute (Red → Green → Refactor enforcement, per-task gates, blocked-task handling) |
+| [review-checklist.md](references/review-checklist.md)                         | Review (simplification, consolidation, learnings capture)                           |
+
+Artifact templates live in [references/templates/artifacts/](references/templates/artifacts/):
+
+| Template                                                              | Produced By  |
+| --------------------------------------------------------------------- | ------------ |
+| [work-input.md](references/templates/artifacts/work-input.md)         | Orchestrator |
+| [work-manifest.md](references/templates/artifacts/work-manifest.md)   | Triage       |
+| [execution-plan.md](references/templates/artifacts/execution-plan.md) | Prepare      |
+| [execution-log.md](references/templates/artifacts/execution-log.md)   | Execute      |
+| [work-report.md](references/templates/artifacts/work-report.md)       | Review       |
+
+## Core Principles
+
+- **Deterministic Pipeline:** Phases always execute in sequence (no agent switching, no fallback paths).
+- **Test-First Execution:** Every task runs Red → Green → Refactor — the failing test is written/confirmed **before** implementation. A task is not `completed` until its single test is green.
+- **One Acceptance Criterion per Task:** Preserve the `/plan` invariant — one AC → one task → one test. Ad-hoc work is resolved to the same shape by Triage; never bundle criteria during execution.
+- **Work Branch:** Every new feature or plan executes on its own git branch `work/<short-description>` (slug derived from the plan name or work description). The branch is created or checked out in Triage before any artifact is written, the setup is idempotent for resume, and a dirty working tree fails explicitly instead of stashing or carrying changes.
+- **Separate Execution from Planning:** Execute the plan as sliced; do not re-plan during execution. Surface scope changes to the user instead of silently expanding a task.
+- **Quality Gates (Work Review Phase 4):** After Execute completes, Phase 4 Review runs a lightweight pre-check: simplify/consolidate, run regression test (binary: any failure = gate), detect scope-creep (binary: any finding = gate). If gate fails → tasks enter `status: for-review` (not `completed`) and await Standalone Review approval. If gate passes → tasks move to `status: completed`. This decouples execution quality from final approval authority.
+- **Learnings Orthogonal to Approval:** Work Report surfaces `learnings-to-capture` candidates (from Execute + Review phases) for later `/learn` invocation. Learnings are separate from approval gates; the Learn skill is the single authoritative source for durable knowledge.
+- **Idempotent Status Updates:** Resume-safe — re-running Work picks up at the first non-`completed` task; `completed` and `for-review` tasks are never reverted (their status is idempotent on `review-id` in Review Phase 4).
+- **Error Handling:** Fail explicitly, not silently; each phase has clear error handling with recovery suggestions.
+- **Be Concrete:** Use specific files, components, and dependencies from the task artifacts.
+- **Stay Portable:** Use repository-relative paths only.
+- **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.
+- **Behavior-Described, Tool-Agnostic:** Steps describe required capabilities ("run the test", "update the task file"), not specific tool names; each agent maps to its native tools.
+- **Next Workflow Step (Task-in-Review):** If Work Report's `work-state: for-review`, user runs `/review <work-id>` next. Review discovers `status: for-review` tasks (task-in-review input shape) and gates their approval: approved → `status: completed`, changes-requested → `status: blocked`. Optional GitHub Sync:\*\* When GitHub integration is enabled, task status may be mirrored to GitHub Issues (via the sync-status micro-skill); this is integration-gated and never required to run Work.

package/skills/work/modules/execute.md

@@ -0,0 +1,109 @@
+---
+title: Execute
+description: Run the Execution Plan's ordered task list per the selected execution mode, enforcing each task's Red -> Green -> Refactor gates (definitions authoritative in task-execution-rules), updating task files and the index checklist idempotently, and producing an Execution Log for the Review phase.
+type: module
+version: 1.0
+timestamp: "2026-08-07"
+---
+
+# Phase 3 - Execute
+
+**Purpose:** Third step in the Work workflow. Reads the [Execution Plan](../references/templates/artifacts/execution-plan.md) from Prepare, runs its `execution-list` according to the selected `executionMode` (`inline` / `serial` / `parallel`), enforces each task's Red → Green → Refactor gates and resume/blocked/skip transitions (definitions authoritative in [task-execution-rules.md](../references/task-execution-rules.md) — this phase enforces them, it does not re-encode them), and updates each task file's status and the `docs/tasks/<work-id>/index.md` checklist idempotently. Returns an [Execution Log](../references/templates/artifacts/execution-log.md) for the Review phase.
+
+## Workflow
+
+This is the Phase 3 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 Plan** from Prepare. Specifically verify:
+
+1. The Execution Plan carries `prepare-id`, `triage-id`, `work-id`, `input-shape`, `interactionMode`, `executionMode`, `execution-list`, `runner`, `baseline`, and `applicable-gates`.
+2. `executionMode` is one of `inline` / `serial` / `parallel` (and resolves per the risk floor in [execution-mode-selection.md](../references/execution-mode-selection.md) — any HIGH-risk task must have `inline` treatment).
+3. `interactionMode` is present and valid (default to `smart` if missing; log warning).
+4. Cross-phase consistency: `work-id`, `triage-id` match the upstream artifacts.
+
+If `work-state: nothing-ready`, the execution-list is empty — record an empty Execution Log (Step 5) and return to the Orchestrator; do not run any test.
+
+### Step 1: Resolve the Test Command Per Task
+
+1. **Read `runner` and (for Node.js) `packageManager`** from the Execution Plan (Prepare detected them). Build the per-task test invocation from the task's `files.test`:
+   - Node.js (npm): `npm test -- <test-path>` (or `npx jest <test-path>` / `npx vitest run <test-path>` when `scripts.test` is absent).
+   - Node.js (pnpm): `pnpm test -- <test-path>` (or `pnpm exec jest <test-path>` / `pnpm exec vitest run <test-path>`).
+   - Python: `pytest <test-path>`; Go: `go test <test-path>`; Rust: `cargo test <test-path>`; Ruby: `bundle exec rspec <test-path>`; PHP: `vendor/bin/phpunit <test-path>`; Java/Kotlin: `mvn -Dtest=<...> test` / `gradle test --tests <...>`.
+2. If `runner: unknown`, stop and ask the user for the project's test command before proceeding (Prepare should have resolved this; treat its absence here as a Category 2 recovery per [error-handling.md](../references/error-handling.md)).
+3. If a task's production code needs a dependency not yet installed (e.g., a new package add in a Red/Green step), install it with the resolved package manager (`pnpm add` / `npm install`) only when the task's Green step requires it — not preemptively.
+
+### Step 2: Execute the List Per Execution Mode
+
+Run `execution-list` according to `executionMode`. The mode flows are defined canonically in **[execution-mode-selection.md](../references/execution-mode-selection.md)** — Execute follows them; it does not re-derive them:
+
+- **`inline`** — one task at a time. After each task completes or blocks, pause for the user (the `single-task-pause: true` flag) and re-confirm before the next task's Red (destructive) step. Best when `interactionMode: detailed` or any task is HIGH-risk; it is the only mode allowed for a HIGH-risk task.
+- **`serial`** — run the flat ordered list sequentially. Do **not** pause between tasks; stop only when a task becomes `blocked` (then surface the reason and ask the user whether to continue with remaining independent tasks, retry, or abort).
+- **`parallel`** — run each wave's independent tasks concurrently; waves run in order (Wave 0 fully settles before Wave 1 starts). A blocked task blocks only its dependents in later waves, not the whole wave.
+
+**Resume at entry:** before running each task, read its task-file frontmatter `status`. A `completed` task is skipped (never re-opened). A `blocked` or `skipped` task is carried with its recorded reason and not auto-retried. Only `not-started` / `in-progress` tasks in `execution-list` are run. (Definitions authoritative in [task-execution-rules.md](../references/task-execution-rules.md).)
+
+### Step 3: Per-Task Execution Cycle (Red → Green → Refactor)
+
+For each runnable task, run the three-phase cycle and enforce the gates. The gate criteria and the retry-limit / blocked / skip thresholds are recorded read-only in the Execution Plan (Prepare read them from [task-execution-rules.md](../references/task-execution-rules.md)) — Execute applies them, it does not redefine them:
+
+1. **Red** — write (or, on resume, confirm) the task's single Acceptance-Criterion test at its `files.test[0]`; run it and confirm it **fails for the right reason** (not a setup/import/compile error). Gate: failing assertion matches the AC. If the test passes immediately (already green), log it and re-check whether the AC is genuinely satisfied — the task may already be done (status `completed` on resume).
+
+2. **Green** — implement the minimum code in the task's `files.create` / `files.modify` to make the AC test pass. Gate: the task's single test is green **and** there is no regression beyond the Step 1 baseline — if `baseline: snapshot-and-continue`, the regression gate ignores the known-failing test set recorded in the Execution Plan.
+
+3. **Refactor** — clean up naming, duplication, and structure while keeping the AC test green. Gate: the test stays green and there is no regression. No behavior change.
+
+### Step 4: Status Updates (Per Task)
+
+After each task's gates pass (or a transition fires), update its artifacts. Updates are **idempotent** — re-running Execute never resets a `completed` task or a `- [x]` checkbox:
+
+1. **On `completed`:**
+   - Set the task-file frontmatter `status: completed` and flip the `## Acceptance Criteria` checkbox to `- [x]`.
+   - In `docs/tasks/<work-id>/index.md`, tick that task's row from `- [ ]` to `- [x]`.
+2. **On `blocked`** (Green gate not reached within the retry-limit recorded in the Execution Plan):
+   - Set frontmatter `status: blocked`, record a `reason` (the failing assertion snapshot and which gate failed).
+   - Leave the index checkbox as `- [ ]` and append a `— blocked: <reason>` note.
+   - Per the mode flow: `inline`/`serial` pause and surface; `parallel` blocks only dependents in later waves.
+3. **On `skip`** (explicit user confirmation only — never auto-skip):
+   - Set frontmatter `status: skipped` with a recorded `reason`.
+   - Leave the index checkbox as `- [ ]` and append a `— skipped: <reason>` note.
+4. **Mid-task (`in-progress`):** if Execute is interrupted mid-task, set frontmatter `status: in-progress` so a resume re-enters the cycle at the right gate; do **not** tick the checkbox.
+
+> Task-status coherence: the orchestrator's post-Execute quality gate (#4) requires every task to be `completed`, `blocked`, or `skipped` (with reasons) — none left `in-progress` — and the index checklist state must match the task files' frontmatter. Execute is responsible for leaving the state coherent at the end of the run.
+
+### Step 5: Generate the Execution Log Artifact
+
+1. **Assign an `execute-id`** per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-execute`, saved to `docs/plans/.work/.execute/`). Reuse it if the user later picks **Edit & Retry**.
+
+2. Produce an **Execution Log** block (as markdown) following the schema in [execution-log.md](../references/templates/artifacts/execution-log.md). Include:
+   - `execute-id`, inherited `prepare-id`, `triage-id`, `work-id`, `input-shape`
+   - `interactionMode` and `executionMode` (both carried)
+   - a per-task result table: `task-id`, `outcome` (`completed` / `blocked` / `skipped`), gate trace (Red/Green/Refactor pass timestamps), and any `reason`
+   - aggregator counts: `completed`/`blocked`/`skipped` counts and the regression-detection summary (any new failures beyond the baseline snapshot)
+   - final index-checklist state (matches the task files)
+
+### Step 6: Present, Confirm, and Save
+
+Apply the **[phase confirmation behavior](../references/interaction-mode-propagation.md)** for the current `interactionMode`, using these execute-specific **Smart pause triggers** (in addition to the per-task pauses mandated by `inline` mode and by a `blocked` task):
+
+- A task hit the retry-limit and went `blocked` (decide before auto-continuing remaining independent tasks), or
+- A new regression beyond the baseline snapshot appears on a `completed` task's Refactor re-run, or
+- `executionMode: parallel` and a blocked task in an earlier wave leaves later dependent tasks unable to run.
+
+- **Detailed:** summarize the Execution Log and ask one question with options *(1) Proceed to Review, (2) Edit & Retry, (3) Abort*. On **Edit & Retry**, loop back through Steps 1–5 reusing the `execute-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/.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).
+
+## Output: Execution Log Artifact
+
+- Verify that the Execution Log is complete and valid: `execute-id`, `prepare-id`, `triage-id`, `work-id`, `input-shape`, `interactionMode`, `executionMode`, the per-task result table, and the aggregator counts.
+- Verify **task-status coherence**: every task in `execution-list` ended `completed`, `blocked` (with reason), or `skipped` (with reason) — none left `in-progress` — and `docs/tasks/<work-id>/index.md` checklist state matches the task files' frontmatter `status`.
+- Verify that each `completed` task has its `## Acceptance Criteria` checkbox flipped to `- [x]` and the index ticked `- [ ] → - [x]` (forward only — never reset).
+- Verify that every `completed` task's single AC test is green with no new regression beyond the recorded baseline snapshot.
+- 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.
+- Verify that the artifact is saved to `docs/plans/.work/.execute/<execute-id>.md`.
+
+> Pass the Execution Log to `review` (Phase 4) for the simplification, consolidation, and learnings-capture pass.