arreio 1.0.0-dev.1

package/skills/plan/references/templates/artifacts/scoped-context.md

@@ -0,0 +1,53 @@
+---
+title: Scoped Context Artifact
+description: Template for the Scoped Context Artifact produced by the Scope phase. Captures problem frame, intended behavior, success criteria, and relevant learnings or requirements.
+type: template
+version: 1.1
+timestamp: "2026-08-07"
+---
+
+# Scoped Context Artifact
+
+The product of the **Scope** phase is a structured context object that downstream modules (research, design, generate) consume. It captures the problem frame, intended behavior, success criteria, and any relevant learnings or requirements.
+
+When the **Scope** phase completes, the orchestrator produces a scoped context block (as markdown) with this schema:
+
+```yaml
+title: [plan title]
+type: scope
+scope-id: YYYY-MM-DD-NNN-scope
+domain: software | non-software
+status: complete
+interactionMode: detailed | smart | autopilot
+timestamp: ISO-8601 timestamp (e.g., 2026-07-04T14:30:00Z)
+
+# Scoped Context
+
+## Problem
+[Clear statement of the problem frame]
+
+## Intended Behavior
+[Description of desired outcome]
+
+## Success Criteria
+- [Criterion 1]
+- [Criterion 2]
+
+## Existing Plan
+path: docs/plans/...md | null
+action: resume | review | archive | delete | create-new | none
+
+## Related Learnings
+- docs/learn/XXX.md — [1-line applicability note]
+- (List from docs/learn/index.md; empty list if none)
+
+## Learning Gaps
+- [Gap name] — [Follow-up action via /learnings]
+
+## Requirements Found
+- docs/brainstorms/XXX.md — [relevant excerpt]
+- docs/requirements/XXX.md — [relevant excerpt]
+- (Empty list if none found)
+```
+
+Also save the scoped context to `docs/plans/.scope/<scope-id>.md` for future reference or reuse. The `interactionMode` value flows into `research`, `design`, and `generate` artifacts.

package/skills/plan/references/templates/artifacts/task.md

@@ -0,0 +1,192 @@
+---
+title: Task Artifact
+description: Template for the Task Artifact produced by the Tasks phase. One task per Acceptance Criterion; one test per task; Red→Green→Refactor Steps. Defines the schema for a single executable, test-driven task file.
+type: template
+version: 2.0
+timestamp: "2026-08-07"
+---
+
+# Task Artifact
+
+The product of the **Tasks** phase (Phase 5) is a set of granular, executable, **test-driven** task files — **one per Acceptance Criterion**. Each task carries exactly one Acceptance Criterion and exactly one test file, follows Red→Green→Refactor, and is self-contained enough to execute without re-reading the full plan. It is the handoff point to the Work skill (`work/SKILL.md`).
+
+## Core rule
+
+- **One Acceptance Criterion per task.**
+- **One test per task** (in `files.test`, exactly one entry) — that test asserts this task's single Acceptance Criterion.
+- **Test-Driven:** `## Steps` run **Red → Green → Refactor** (write the failing test first and confirm it fails, implement the minimum code to pass, then refactor with the test green).
+
+## Schema
+
+```yaml
+---
+id: <plan-id>-T<NN>
+title: "[Task title]"
+plan-id: <plan-id>
+unit: U<NN> | U<NN><letter>
+tier: fast | standard | deep
+status: not-started
+priority: P0 | P1 | P2
+dependencies: [<task-id>, ...]
+files:
+  create: [path/to/file, ...]
+  modify: [path/to/file, ...]
+  test: [path/to/test]          # exactly one — the test for this task's AC
+estimated-effort: "<hours or days>"
+timestamp: ISO-8601 timestamp (e.g., 2026-08-07T14:30:00Z)
+---
+
+# [Task Title]
+
+## Goal
+[What this task accomplishes, inherited from the implementation unit and scoped to this one criterion. 1-2 sentences.]
+
+## Acceptance Criterion
+[Exactly one, single, verifiable criterion this task delivers.]
+
+## Steps
+1. **Red — Write the failing test:** add the test at `files.test[0]` asserting this Acceptance Criterion. Run it and confirm it fails for the right reason (not a setup/import error).
+2. **Green — Implement:** add 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.
+
+## Test Scenarios
+- [Scenario]: [Input -> Expected Outcome]   # the assertion(s) for this criterion (may be a single scenario)
+
+## Acceptance Criteria
+- [ ] [This task's single Acceptance Criterion, restated as a checkable box]
+
+## Dependencies
+- [task-id]: [why this task must complete first, or "None"]
+
+## Notes
+[Any context, gotchas, references to learnings, or links to related tasks. Optional.]
+```
+
+## Validation Rules
+
+- **id:** Required. Format `<plan-id>-T<NN>` where `NN` is zero-padded 2 digits matching dependency order. Sub-IDs use letters (e.g., `T02a`).
+- **title:** Required. Short, action-oriented (e.g., "Set up Redis client and session store interface").
+- **plan-id:** Required. Must match the Final Plan's `plan-id` for traceability.
+- **unit:** Required. The originating implementation unit (e.g., `U1`, `U2a`). A task never spans more than one Acceptance Criterion, so it records exactly one unit (or one sub-id).
+- **tier:** Required. Inherited from the Final Plan (`fast | standard | deep`).
+- **status:** Required. Initial value `not-started`. The Work skill updates this to `in-progress`, `completed`, or `blocked`.
+- **priority:** Required. `P0` (blocks all), `P1` (critical path), `P2` (deferrable).
+- **dependencies:** Required (may be empty list). Must reference task IDs that appear earlier in dependency order.
+- **files:** Required. `test` must contain **exactly one** path — the test for this task's single Acceptance Criterion. At least one of `create`, `modify`, or `test` must be non-empty. All paths must be repository-relative.
+- **estimated-effort:** Required. Rough estimate in hours or days. Used by the Work phase for sequencing.
+- **Goal:** Required. 1–2 sentences, inherited from the unit and scoped to this criterion.
+- **Acceptance Criterion:** Required. **Exactly one** verifiable criterion. Single, not bundled.
+- **Steps:** Required. Exactly three, in **Red → Green → Refactor** order, with the failing test written and confirmed **before** implementation.
+- **Test Scenarios:** Required for foundation/integration tasks (phases 1–2). Optional for rollout-only tasks. Format: `[Scenario]: [Input -> Expected Outcome]`. May be a single scenario (one task = one criterion = one test).
+- **Acceptance Criteria (checkbox):** Required. Exactly one checkable item restating the criterion above.
+- **Notes:** Optional. May reference learnings, gotchas, or related tasks.
+
+## Example
+
+```yaml
+---
+id: 2026-07-03-001-T01
+title: "Redis client connects and backs the SessionStore interface"
+plan-id: 2026-07-03-001
+unit: U1
+tier: standard
+status: not-started
+priority: P0
+dependencies: []
+files:
+  create:
+    - src/lib/redis-client.ts
+    - src/lib/session-store.ts
+  test:
+    - src/lib/redis-client.test.ts
+estimated-effort: "4 hours"
+timestamp: 2026-07-03T09:00:00Z
+---
+
+# Redis client connects and backs the SessionStore interface
+
+## Goal
+Create a Redis client wrapper that connects from `REDIS_URL` with retry-on-failure, and define the `SessionStore` interface it satisfies. This is the foundation for all later session work.
+
+## Acceptance Criterion
+The Redis client connects using `REDIS_URL` with retry on failure, and `SessionStore` exports `get`, `save`, and `delete` — verified by a failing-then-passing test.
+
+## Steps
+1. **Red — Write the failing test:** add `src/lib/redis-client.test.ts` asserting: store `{id, data}` → retrieve returns the same data; a 1s TTL session returns null after expiry; dropping the connection makes `get` throw a retryable error. Run it and confirm it fails (interface/client not yet implemented).
+2. **Green — Implement:** add `ioredis` to `package.json`; create `src/lib/redis-client.ts` (configured client with connection retry) and `src/lib/session-store.ts` (`get`, `save`, `delete`) until the test passes.
+3. **Refactor:** keep the client wrapper thin (business logic belongs in the store implementation — T02); ensure all three test scenarios stay green.
+
+## Test Scenarios
+- Store/retrieve session: store {id, data} -> retrieve returns same data
+- TTL expiration: store with 1s TTL -> after 1s, get returns null
+- Connection error: drop connection -> get throws retryable error
+
+## Acceptance Criteria
+- [ ] Redis client connects from `REDIS_URL` with retry on failure and `SessionStore` exposes `get`/`save`/`delete` (all three test scenarios pass)
+
+## Dependencies
+- None
+
+## Notes
+- Reuse the connection retry pattern from `docs/learn/pattern/redis-retry-2026-07-02.md` if it exists.
+- Feature flag `feature.redis_sessions` is added in T04, not here.
+- T02 implements the Redis-backed `SessionStore`; keep this task limited to the client + interface + its own test.
+```
+
+## File-Naming Convention
+
+Task files are named and stored as:
+
+```
+docs/tasks/<plan-id>/T<NN>-<kebab-case-name>.md
+```
+
+**Example:**
+
+```
+docs/tasks/2026-07-03-001/
+  T01-redis-client-and-session-store-interface.md
+  T02a-redis-session-store-implementation.md
+  T02b-session-middleware-refactor.md
+  T04-dual-write-cutover.md
+```
+
+## Usage in Workflow
+
+1. **Tasks Phase** reads the Final Plan's Implementation Units and slices them into tasks per [task-slicing-rules.md](../../task-slicing-rules.md) — **one task per Acceptance Criterion**.
+2. Each task file is saved to `docs/tasks/<plan-id>/T<NN>-<name>.md`.
+3. **Tasks Phase** updates `docs/tasks/<plan-id>/index.md` with a checklist of all tasks for the plan.
+4. **Work skill** (`work/SKILL.md`) reads task files, runs each task's Red→Green→Refactor cycle, and updates `status` and the index checklist.
+
+## Index Entry Format
+
+After saving all task files, append a section to `docs/tasks/<plan-id>/index.md`:
+
+```markdown
+## 2026-07-03-001 — Migrate Session Storage to Redis
+
+- [ ] T01 — Redis client connects and backs the SessionStore interface (`U1`, AC: client connects with retry + SessionStore get/save/delete) — `docs/tasks/2026-07-03-001/T01-redis-client-and-session-store-interface.md`
+- [ ] T02a — Redis-backed SessionStore implementation (`U2a`, AC: get/save/delete persist sessions to Redis with TTL) — `docs/tasks/2026-07-03-001/T02a-redis-session-store-implementation.md`
+- [ ] T02b — Session middleware refactor (`U2b`, AC: middleware loads valid sessions and rejects invalid/expired JWTs) — `docs/tasks/2026-07-03-001/T02b-session-middleware-refactor.md`
+- [ ] T04 — Dual-write and cutover (`U4`, AC: dual-write to Redis with feature-flagged cutover) — `docs/tasks/2026-07-03-001/T04-dual-write-cutover.md`
+```
+
+The `- [ ]` (unchecked) markers are updated to `- [x]` by the Work skill as tasks complete.
+
+## Missing Field Recovery
+
+If a task file is incomplete at validation, use this recovery workflow:
+
+| Field               | Validation                           | Recovery                                            |
+| ------------------- | ------------------------------------ | --------------------------------------------------- |
+| id                  | Matches `<plan-id>-T<NN>`            | Regenerate from dependency order                    |
+| unit                | References a single plan unit        | Ask user to map the task to one unit                |
+| files.test          | Exactly one path                     | Ask user for the single test file for this criterion |
+| files (create/modify) | At least one path non-empty        | Ask user which files the task touches               |
+| Acceptance Criterion | Exactly one, verifiable             | Ask user to state the single criterion              |
+| Steps               | Red → Green → Refactor ordering     | Re-sequence; ensure test is written and run first    |
+| Test Scenarios      | Present for phases 1–2              | Inherit from the unit's test scenarios              |
+| Acceptance Criteria | Exactly one checkable item          | Derive from the single Acceptance Criterion         |
+| dependencies        | References earlier task IDs         | Re-run dependency ordering algorithm                 |
+
+**Note:** If a task cannot be produced because the plan has no Implementation Units (or a unit has no Acceptance Criteria), abort the Tasks phase and ask the user to re-run the Design/Generate phases — the plan is incomplete.

package/skills/plan/references/templates/artifacts/user-input.md

@@ -0,0 +1,112 @@
+---
+title: User Input Artifact
+description: Template for the User Input Artifact produced by the Orchestrator. Captures raw user input, task description, intended behavior, goals, constraints, and context for downstream phases.
+type: template
+version: 1.1
+timestamp: "2026-08-07"
+---
+
+# User Input Artifact
+
+The **User Input Artifact** is the entry point to the Plan workflow. It captures the raw input from the user before the Scope phase processes and structures it. The Orchestrator produces this artifact and passes it to Phase 1 (Scope) for validation and context enrichment.
+
+## Schema
+
+```yaml
+type: user-input
+timestamp: ISO-8601 timestamp (e.g., 2026-07-02T14:30:00Z)
+source: user-prompt | saved-prompt | document | previous-plan | hybrid
+status: provided | incomplete | invalid
+
+# User Input
+
+## Task Description
+[1-3 sentence description of the task or project]
+
+## Intended Behavior
+[Description of the desired outcome or what should happen after completion]
+
+## Goals & Objectives
+- [Goal 1]
+- [Goal 2]
+- (Optional; may be empty if not provided)
+
+## Constraints & Limitations
+- [Constraint 1]
+- [Constraint 2]
+- (Optional; may be empty if not provided)
+
+## Context Source
+[Where the input came from: direct user question, saved prompt file, attached document, resume of previous plan, or combination]
+
+## Additional Context
+[Any other relevant information: related files, previous attempts, team notes, external references]
+(Optional; may be empty)
+```
+
+## Validation Rules
+
+- **Task Description:** Required. Must be non-empty and non-ambiguous.
+- **Intended Behavior:** Required. Must describe an observable outcome.
+- **Goals & Objectives:** Optional but recommended. If empty, Scope will ask clarifying questions.
+- **Constraints & Limitations:** Optional. If empty, Scope assumes no explicit constraints.
+- **Context Source:** Required. Must be one of: `user-prompt`, `saved-prompt`, `document`, `previous-plan`, or `hybrid`.
+- **Additional Context:** Optional. May be empty or contain freeform notes.
+
+## Example
+
+```yaml
+type: user-input
+timestamp: 2026-07-02T10:15:00Z
+source: user-prompt
+status: provided
+
+# User Input
+
+## Task Description
+Add real-time collaboration features to the editor. Multiple users should be able to edit the same document simultaneously and see changes update in real-time.
+
+## Intended Behavior
+When User A types in a document, User B sees the text appear within 200ms. Cursor positions and selections are also synchronized. Conflicts are resolved using operational transformation.
+
+## Goals & Objectives
+- Enable simultaneous multi-user editing
+- Keep latency under 200ms
+- Support up to 10 concurrent users per document
+- Maintain backward compatibility with single-user editing
+
+## Constraints & Limitations
+- Must use WebSocket protocol (no long-polling)
+- Backend infrastructure limited to 2 GB RAM per instance
+- Cannot require changes to existing client API
+
+## Context Source
+user-prompt
+
+## Additional Context
+Related issue: https://github.com/org/repo/issues/42
+Previous prototype: /docs/brainstorms/collab-v1.md
+Team notes in Slack: channel #editor-features
+```
+
+## Usage in Workflow
+
+1. **Orchestrator** generates this artifact from user input, saved prompt, or document
+2. **Scope Phase (Step 0)** validates the artifact for completeness and format
+3. **Scope Phase (Steps 1-5)** enriches the artifact with learnings, requirements, and existing plans
+4. **Scoped Context Artifact** is the output that downstream phases consume
+
+## Missing Input Recovery
+
+If the User Input Artifact is incomplete or invalid at Step 0, the Scope phase uses this recovery workflow:
+
+| Field                     | Validation                    | Recovery                                                     |
+| ------------------------- | ----------------------------- | ------------------------------------------------------------ |
+| Task Description          | Non-empty, < 500 chars        | Ask: "What problem are you trying to solve?"                 |
+| Intended Behavior         | Non-empty, observable outcome | Ask: "What should happen after this is implemented?"         |
+| Goals & Objectives        | Optional                      | Ask: "What specific outcomes define success?" (collect 1-3)  |
+| Constraints & Limitations | Optional                      | Ask: "Are there any hard constraints?" (collect if provided) |
+| Context Source            | Must be valid type            | Infer from input origin; ask if ambiguous                    |
+| Additional Context        | Optional                      | Skip if empty                                                |
+
+**Note:** If Task Description or Intended Behavior cannot be provided, abort planning and ask the user to return with more context.

package/skills/review/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: review
+description: "Review code changes through a deterministic pipeline of micro-skills: Scope -> Prepare -> Analyze -> Report. Accepts a PR / branch diff / commit range / working tree, a /work run's changes, or an ad-hoc target; produces graded findings and an approval status. Local-only; no GitHub sync. No agent dependency, no fallback paths."
+disable-model-invocation: true
+---
+
+# Review
+
+Orchestrates a deterministic pipeline of micro-skills: `Scope -> Prepare -> Analyze -> Report`. Reviews code changes against quality, security, tests, documentation, integration, and scope-creep standards; produces graded findings (`blocker` / `major` / `minor` / `nit`) and an approval status (`approved` / `changes-requested` / `rejected`). Accepts any code change set, a `/work` run's changes, **or** an ad-hoc target. Local-only — findings are written to a report on disk, never posted to GitHub. No agent dependency, no fallback paths.
+
+## Skill Invocation
+
+This skill is invoked by prompting:
+
+- `/review <change-set>` — review a git change set: `git diff <base>..<head>`, a PR's commits, a commit range (`A..B`), `HEAD` (uncommitted), staged changes, a branch-vs-base diff, or a set of paths/globs.
+- `/review <work-id>` — review the changes a `/work` run produced. Scope discovers `status: for-review` tasks (see below); if found, reviews those task changes and gates approval. Also accepts a Work `review-id` to scope to that run.
+- `/review <target description>` — ad-hoc review of a described target (e.g. "review the auth module", "review `src/lib/redis-client.ts`"). Scope resolves the description into a concrete change boundary.
+
+This skill runs the review pipeline, analyzing changes and producing a report, 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 review? Provide a git ref/range, a work-id, or describe a target."
+
+Before starting the workflow, ask the user to choose an interaction mode:
+
+- **Detailed** — Confirm at each phase transition and before surfacing each finding category; inspect artifacts; maximum control. Best for high-stakes or sensitive reviews.
+- **Autopilot** — All phases run automatically; only the final Review Report is presented. Fastest. Best for routine reviews of well-understood changes.
+- **Smart** — Phases run automatically; pause only when `blocker`/`major` findings appear or when scope creep is detected.
+
+Store in the context object:
+
+```yaml
+interactionMode: detailed | smart | autopilot
+```
+
+**Propagation:** `interactionMode` flows into the `scope`, `prepare`, `analyze`, and `report` artifacts; each downstream phase reads it to adjust confirmation behaviour (detailed = pause every transition; autopilot = run all; smart = pause only on `blocker`/`major` findings or detected scope creep).
+
+## Orchestration Implementation
+
+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 from the user, a saved prompt, a document, or a combination.
+- **Four input shapes:**
+  1. **Change-set** — a git change set spec: a diff range (`<base>..<head>`), a commit range (`A..B`), `HEAD` (uncommitted working tree), staged changes, a branch-vs-base diff, or a set of paths/globs. Scope resolves it to a concrete file + hunk boundary.
+  2. **Work-linked** — a `work-id` (e.g. `2026-07-10-001`) or a Work `review-id`. Scope resolves it to the changes that `/work` run touched: the union of every task file's `files.create` / `files.modify` (filtered by the `completed`/`blocked`/`skipped` outcomes in the Work Report), bounded to commits attributable to that run if discoverable.
+  3. **Task-in-review** — ✅ **NEW**: a `work-id` where one or more tasks have `status: for-review` (gated by Work Review Phase 4). Scope resolves it to files touched by those tasks. After Analyze, Report updates task file frontmatter: `status: completed` (if approved) or `status: blocked` (if changes-requested). This is the approval gate for tasks awaiting review.
+  4. **Ad-hoc** — a free-form target description. Scope maps it to a concrete change boundary by locating matching files/paths and, where applicable, the commits that most recently touched them.
+- **Optional requirements:** any review is sharper when there is a reference spec to test against. Accept an optional requirements ref — a `/plan` plan-id, a task's `## Acceptance Criterion`, a markdown spec, or a referenced doc. If provided, scope-creep detection runs against it; if absent, Scope marks `requirements-source: none` and Analyze skips the scope-creep-vs-requirements category (noting it).
+- **If no context is provided**, ask: "What would you like to review? Provide a git ref/range, a work-id, or describe a target."
+- **Unified key:** downstream phases key off a `review-id` (`YYYY-MM-DD-NNN`), allocated by Scope per [id-generation.md](references/id-generation.md). For work-linked and task-in-review input, the `review-id` is **distinct** from the Work `review-id` (the two skills produce independent artifacts) — the work-id is carried alongside for traceability and optional index cross-linking. For task-in-review input specifically, Report's approval verdict updates the task files' frontmatter `status:` field (new behavior).
+- Output: [Review Input Artifact](references/templates/artifacts/review-input.md)
+
+### Pre-Flight Check
+
+Before starting the review pipeline, the orchestrator verifies that required folders exist:
+
+- `docs/plans/.review/.scope/`, `docs/plans/.review/.prepare/`, `docs/plans/.review/.analyze/`, `docs/plans/.review/.report/` — must exist for saving the four phase artifacts
+- `docs/plans/.review/index.md` — must exist as the review registry (Report appends to it)
+
+**Self-Healing:** If any are missing, the orchestrator automatically creates them (`mkdir -p`, and a seed `index.md` with a registry header). This allows the Review skill to run even if `arreio-init` wasn't explicitly run.
+
+For **change-set** input, verify the repo is a git working tree and the spec parses to a non-empty diff; if not, ask the user to provide a valid ref/range or switch to ad-hoc.
+
+For **work-linked** input, verify the `work-id` exists (`docs/tasks/<work-id>/index.md`) and is non-empty; if given a Work `review-id`, verify `docs/plans/.work/.review/<review-id>.md` exists. If missing, ask the user to run `/work <work-id>` first or switch to a change-set spec.
+
+For **task-in-review** input, verify the `work-id` exists and contains at least one task with `status: for-review` (read task files' frontmatter or check the Work Report's task-outcome-rollup `for-review` count). If none found, inform the user: "No tasks in for-review status for this work-id. Did you run `/work <work-id>` first?" or offer to review the work-linked changes instead.
+
+### Phases
+
+| Phase | Phase Module                  | Output Artifact                                                  | Saved to                              |
+| ----- | ----------------------------- | ---------------------------------------------------------------- | ------------------------------------- |
+| 1     | [Scope](modules/scope.md)     | [Review scope](references/templates/artifacts/review-scope.md)   | `docs/plans/.review/.scope/<id>.md`   |
+| 2     | [Prepare](modules/prepare.md) | [Review kit](references/templates/artifacts/review-kit.md)       | `docs/plans/.review/.prepare/<id>.md` |
+| 3     | [Analyze](modules/analyze.md) | [Findings](references/templates/artifacts/findings.md)           | `docs/plans/.review/.analyze/<id>.md` |
+| 4     | [Report](modules/report.md)   | [Review report](references/templates/artifacts/review-report.md) | `docs/plans/.review/.report/<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 (`review-id`, `scope-id`, `prepare-id`, `analyze-id`, `report-id`) match the upstream artifacts; `interactionMode` is identical across artifacts.
+3. **Status check** — the artifact's `status` is `complete` (not `pending` or `failed`).
+4. **Scope coherence** (after Scope) — the change boundary is non-empty and parses to a concrete file list; referenced requirements resolve (or are explicitly marked `none`). Required- vs optional-only files are separated.
+5. **Findings coherence** (after Analyze) — every finding carries a `severity`, a `category` (quality / security / tests / documentation / integration / scope-creep), a repository-relative `location`, and either a requirement trace or a `scope-creep` flag.
+
+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                                                                                                                         |
+| ------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| Scope   | _(none — produces artifact only)_                                      | Allocates the `review-id`; no index write.                                                                                     |
+| Prepare | _(none)_                                                               | Gathers the review kit; no index write.                                                                                        |
+| Analyze | _(none)_                                                               | Produces findings; no index write.                                                                                             |
+| Report  | `docs/plans/.review/index.md`                                          | Append a registry row: `<report-id>`, review target summary, approval status, link to the report file.                         |
+| Report  | `docs/tasks/<work-id>/index.md` _(work-linked or task-in-review only)_ | Append a distinct `## Review Report — <report-id>` block (separate from Work's own `## Work Report` block).                    |
+| Report  | Task frontmatter _(task-in-review only)_                               | Update task file `status:` field to `completed` (if approved) or `blocked` (if changes-requested, with reason in frontmatter). |
+
+**Idempotency rule:** re-running Review over the same target re-derives findings fresh (reviews are not resume-safe like execution — the change set may have evolved). The registry row and any work-index block are **idempotent on `report-id`**: a re-run overwrites the row/block with the same id, never duplicates it.
+
+### FINAL OUTPUT
+
+- **Review Report:** Saved to `docs/plans/.review/.report/<report-id>.md`, with: the change boundary, the approval status (`approved` / `changes-requested` / `rejected`), the graded findings rollup, recommendations, and (when requirements were available) the scope-creep summary.
+- **Registry row:** `docs/plans/.review/index.md` updated with the new review.
+- **(Work-linked or task-in-review only) Index cross-link:** `docs/tasks/<work-id>/index.md` gets a `## Review Report — <report-id>` block so a future glance at the work index shows that an external Review ran over it.
+- **(Task-in-review only) Task Status Update:** ✅ **NEW**: For each task with `status: for-review`:
+  - If approval status = `approved` → update task file's frontmatter `status: completed`
+  - If approval status = `changes-requested` → update task file's frontmatter `status: blocked` (with reason in `block-reason:` field)
+  - Idempotent on `report-id` (re-running overwrites, never duplicates)
+- **No GitHub sync:** This skill does not post comments, formal reviews, or labels to GitHub. Findings live on disk only — the user wires outbound posting as a separate step if desired.
+- **(Optional) Learnings:** Recurring traps or confirmed patterns surfaced during Analyze are handed to the Learn skill (`/learn`) to persist — Review 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)                               | Scope, Prepare, Analyze, Report (ID assignment, including `review-id` allocation) |
+| [interaction-mode-propagation.md](references/interaction-mode-propagation.md) | All phases (Step N confirmation)                                                  |
+| [change-set-resolution.md](references/change-set-resolution.md)               | Scope (resolve change-set / work-id / ad-hoc into a change boundary)              |
+| [scope-creep-detection.md](references/scope-creep-detection.md)               | Scope (pre-check) + Analyze (final) detect creep vs requirements                  |
+| [review-categories.md](references/review-categories.md)                       | Analyze (quality / security / tests / documentation / integration / scope-creep)  |
+| [severity-rubric.md](references/severity-rubric.md)                           | Analyze + Report (severity assignment)                                            |
+| [approval-criteria.md](references/approval-criteria.md)                       | Report (final approval status derivation)                                         |
+| [learnings-gate-logic.md](../plan/references/learnings-gate-logic.md)         | Scope (pull related learnings from `docs/learn/index.md`) — reused from `/plan`   |
+
+Artifact templates live in [references/templates/artifacts/](references/templates/artifacts/):
+
+| Template                                                            | Produced By  |
+| ------------------------------------------------------------------- | ------------ |
+| [review-input.md](references/templates/artifacts/review-input.md)   | Orchestrator |
+| [review-scope.md](references/templates/artifacts/review-scope.md)   | Scope        |
+| [review-kit.md](references/templates/artifacts/review-kit.md)       | Prepare      |
+| [findings.md](references/templates/artifacts/findings.md)           | Analyze      |
+| [review-report.md](references/templates/artifacts/review-report.md) | Report       |
+
+## Core Principles
+
+- **Deterministic Pipeline:** Phases always execute in sequence (no agent switching, no fallback paths).
+- **Review ≠ Work's Review phase:** This is a heavyweight code review of arbitrary changes against standards (quality / security / tests / docs / integration / scope-creep) with an explicit approval status. Work's built-in Phase-4 Review is a lightweight, behavior-preserving cleanup + gate of the tasks it just executed. The two are **complementary, not overlapping**:
+  - **Work Review** (Phase 4 of `/work`): Pre-check gate. Simplify, consolidate, run regression check, detect scope-creep. If any regression/scope-creep found → tasks enter `for-review` status (not `completed`).
+  - **Standalone Review** (this skill): Comprehensive audit. Full quality/security/tests/docs analysis. Can accept `/review <work-id>` → finds `status: for-review` tasks (task-in-review input shape) → audits them with full severity rubric → approval verdict updates task status to `completed` or `blocked`.
+  - **Sequential**, not parallel: `/work` executes and gates to `for-review`; user runs `/review` next to approve or reject. No overlap in purpose.
+- **Cascade Graded Findings:** Every finding has a severity (`blocker` / `major` / `minor` / `nit`) that drives the final approval status. Severity criteria are authoritative in [severity-rubric.md](references/severity-rubric.md); Analyze assigns, Report aggregates and never re-encodes the rubric.
+- **Scope-Creep Requires Requirements:** Scope-creep detection runs only when a reference spec is available; without one, Analyze skips that category and records `requirements-source: none`. The logic is authoritative in [scope-creep-detection.md](references/scope-creep-detection.md).
+- **Test the Tests:** Reviewing changes includes evaluating the tests that accompany them — coverage, correctness of assertions, and whether they assert the intended Acceptance Criterion — not just production code.
+- **Read-Only Review:** Review analyzes and reports; it never edits the code under review. Required changes become a follow-up task (a new `/plan` + `/work`, or manual edits) — never applied inline here.
+- **Single Source of Truth:** This skill defines all its own rules; it does not depend on any external agent rule file. Category, severity, and approval definitions live once in their authoritative references and are never re-encoded inline in the modules.
+- **Transparent Artifacts:** Each phase produces an explicit output artifact for the next phase.
+- **Behavior-Described, Tool-Agnostic:** Steps describe required capabilities ("read the diff", "run the test suite", "update the index"), not specific tool names; each agent maps to its native tools.
+- **Interaction Mode Propagation:** `interactionMode` is read at the start of each subsequent phase and determines whether confirmation steps execute.
+- **Error Handling:** Fail explicitly, not silently; each phase has clear error handling with recovery suggestions.
+- **Stay Portable:** Use repository-relative paths only.
+- **Local-Only, No GitHub Sync:** Findings are written on disk only. This skill deliberately does not post to GitHub — outbound posting is left to a separate, optional step the user may add later.

package/skills/review/modules/analyze.md

@@ -0,0 +1,104 @@
+---
+title: Analyze
+description: Third step in the Review workflow. Runs the review categories (quality / security / tests / documentation / integration / scope-creep) across the Review Kit's diffs, assigns each finding a severity (blocker / major / minor / nit) per the authoritative severity rubric, attaches a requirement trace or a scope-creep flag to every finding, and aggregates the tallies. Returns Findings for the Report phase.
+type: module
+version: 1.0
+timestamp: "2026-08-08"
+---
+
+# Phase 3 - Analyze
+
+**Purpose:** Third step in the Review workflow. Reads the [Review Kit](../references/templates/artifacts/review-kit.md) from Prepare, runs the review **categories** (quality / security / tests / documentation / integration / scope-creep) across the diffs, assigns each finding a **severity** (`blocker` / `major` / `minor` / `nit`) per the authoritative rubric, attaches a **requirement trace** or a **scope-creep flag** to every finding, and aggregates the tallies. Returns [Findings](../references/templates/artifacts/findings.md) for the Report phase. Analyze reviews the diffs; it does not edit the code under review (Review is read-only).
+
+## Workflow
+
+This is the Phase 3 pipeline for the Review Skill. It orchestrates the following steps:
+
+### Step 0: Verification
+
+Run the **[Step 0 verification](../references/error-handling.md)**. Required input: a valid **Review Kit** from Prepare. Specifically verify:
+
+1. The Review Kit carries `prepare-id`, `scope-id`, `review-id`, `input-shape`, `interactionMode`, the `diffs`, `spec-content` (or `none`), `test-context`, and `tool-inventory`.
+2. `interactionMode` is present and valid (default to `smart` if missing; log warning).
+3. Cross-phase consistency: `review-id`, `scope-id` match the upstream artifacts; `interactionMode` is identical.
+
+If the kit records `diffs: none` (the empty nothing-to-review case carried from Scope), Analyze produces an empty Findings set (Step 5) and returns — do not fabricate findings.
+
+### Step 1: Run Review Categories
+
+Run the six review categories across the kit's diffs. The category definitions and per-category checks are authoritative in **[review-categories.md](../references/review-categories.md)** — Analyze looks them up, it does not re-derive them:
+
+- **quality** — design, clarity, DRY, naming, error handling, and structural soundness of the changed code.
+- **security** — input validation, authn/authz, secret leakage, injection, and unsafe patterns introduced by the change.
+- **tests** — **Test the tests:** coverage of changed behavior (from `test-context`), assertion correctness (do tests assert the intended behavior?), flakiness, test smells, and whether production-code changes ship without tests.
+- **documentation** — public API docs, README, inline comments, and changelog entries for changed behavior.
+- **integration** — caller/contract impact (use the kit's `context` callers), module-boundary and convention conformance, and whether the change breaks consumers.
+- **scope-creep** — **only when** `spec-content` is not `none`: confirm Scope's `preliminary-scope-creep` candidates with severity, and detect any further changes beyond the requirements. When `spec-content: none`, record this category as **skipped** with the note `skipped (no requirements)` and emit no scope-creep findings (Review does not invent requirements).
+
+Optionally run the available tools captured in `tool-inventory` (linters / type-checkers / the test suite) to **corroborate** a finding — but tools are corroborative, not authoritative: a finding must be warranted by the change, not by a pre-existing repo-wide condition outside the change boundary.
+
+### Step 2: Assign Severity
+
+For each finding, assign a severity per **[severity-rubric.md](../references/severity-rubric.md)** (authoritative) — Analyze assigns; it does not re-encode the rubric:
+
+- **blocker** — must fix before merge: a security hole, data-loss risk, a broken core flow, or a regression in a green-baseline suite.
+- **major** — should fix: a significant quality / test / integration issue that will cause maintenance pain.
+- **minor** — nice to fix: a small quality or documentation issue.
+- **nit** — style / preference; optional.
+
+If a finding's severity is borderline, default to the **lower** severity (do not over-escalate); Report derives the approval status from the tallies.
+
+### Step 3: Attach a Requirement Trace or a Scope-Creep Flag
+
+Every finding must carry either a **requirement trace** or a **scope-creep flag** (the orchestrator's gate #5 requires this):
+
+1. **Requirement trace** — for findings inside the intended scope: reference the requirement/expected-behavior from `spec-content` the finding relates to (by criterion id or short label). Format: `trace: <criterion>` (or `trace: general-quality` for quality findings that are not tied to a specific criterion but are within the change's intent — acceptable as a trace).
+2. **Scope-creep flag** — for findings the change **goes beyond** the requirements: set `scope-creep: true` (no requirement trace). These findings describe the creep, not a defect in the intended change. When `spec-content: none`, all findings carry `trace: no-requirements` (scope-creep cannot be assessed) — never `scope-creep: true` without a spec.
+
+This makes the findings set self-describing for Report's scope-creep summary and approval derivation.
+
+### Step 4: Optionally Run Tools to Corroborate
+
+When a finding would be strengthened by tool evidence, run the relevant configured tool from `tool-inventory`:
+
+- Re-run the **test suite** to confirm a claimed regression (Analyze runs the changed file's covering tests, or the targeted suite) — record the result as corroboration on the finding.
+- Run a **linter / type-checker** on the changed files to surface corroborated quality/security issues; attach the tool output (message + rule id) to the finding.
+
+Tools never **create** a finding on their own outside the change boundary; they only corroborate an already-warranted finding or sharpen its severity. If a tool is unconfigured, proceed without it (Prepare already warned).
+
+### Step 5: Aggregate Tallies and Generate the Findings Artifact
+
+1. **Aggregate** findings by category and count by severity. Compute preliminary tallies (Report derives the final approval status from these — Analyze does not pre-derive approval).
+2. **Assign an `analyze-id`** per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-analyze`, saved to `docs/plans/.review/.analyze/`). Reuse it if the user later picks **Edit & Retry**.
+3. Produce a **Findings** block (as markdown) following the schema in [findings.md](../references/templates/artifacts/findings.md). Include:
+   - `analyze-id`, inherited `prepare-id`, `scope-id`, `review-id`, `input-shape`, `interactionMode`
+   - the findings list: per finding — `id`, `severity`, `category`, `location` (repository-relative `file:line` or `file:hunk`), `message`, `trace` **or** `scope-creep: true`, and an optional non-binding `suggested-fix` (Review is read-only — suggestions are informational, never applied)
+   - per-category and per-severity tallies
+   - a note whether the scope-creep category ran or was `skipped (no requirements)`
+   - `work-id` carried (work-linked only)
+
+### Step 6: Present, Confirm, and Save
+
+Apply the **[phase confirmation behavior](../references/interaction-mode-propagation.md)** for the current `interactionMode`, using these analyze-specific **Smart pause triggers**:
+
+- Any **blocker** finding was detected (pause before auto-continuing to Report), or
+- Any **major** finding was detected (smart mode), or
+- A finding was flagged `scope-creep: true` (confirm the creep is real before finalizing), or
+- The scope-creep category ran and the count of confirmed creep findings differs from Scope's `preliminary-scope-creep` (sanity-check the delta).
+
+- **Detailed:** present the Findings and ask one question with options *(1) Proceed to Report, (2) Edit & Retry, (3) Abort*. On **Edit & Retry**, loop back through Steps 1–5 reusing the `analyze-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/.review/.analyze/<analyze-id>.md` (ensure `interactionMode` included) and return it, with the `interactionMode` value, to the Orchestrator for the transition to Phase 4 (Report).
+
+## Output: Findings Artifact
+
+- Verify that the Findings are complete and valid: `analyze-id`, `prepare-id`, `scope-id`, `review-id`, `input-shape`, `interactionMode`, the findings list, and the per-category / per-severity tallies.
+- Verify **findings coherence** (orchestrator gate #5): every finding has a `severity`, a `category`, a repository-relative `location`, and either a `trace` or `scope-creep: true`.
+- Verify the **scope-creep** category either ran (with `spec-content` not `none`) or is recorded `skipped (no requirements)` — never silently absent, never inventing requirements.
+- Verify severities were **assigned from** [severity-rubric.md](../references/severity-rubric.md) rather than re-defined inline (no second rubric contradicting the authoritative reference).
+- Verify the category checks were **run from** [review-categories.md](../references/review-categories.md) rather than re-encoded inline.
+- Verify that the artifact is saved to `docs/plans/.review/.analyze/<analyze-id>.md`.
+
+> Pass the Findings to `report` (Phase 4) for the approval-status derivation, the report write, and the registry / work-index cross-link.