npm - arreio - Versions diffs - 1.0.0-dev.1 - Mend

arreio 1.0.0-dev.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (81) hide show

package/README.md +81 -0
package/package.json +42 -0
package/scripts/postinstall.js +50 -0
package/skills/arreio-init/SKILL.md +214 -0
package/skills/arreio-init/references/architecture-template.md +85 -0
package/skills/arreio-init/references/learn-index-template.md +15 -0
package/skills/arreio-init/references/plan-index-template.md +29 -0
package/skills/arreio-init/references/tasks-index-template.md +15 -0
package/skills/learn/SKILL.md +151 -0
package/skills/learn/modules/capture.md +108 -0
package/skills/learn/modules/index.md +94 -0
package/skills/learn/modules/maintain.md +116 -0
package/skills/learn/modules/refine.md +104 -0
package/skills/learn/references/dedup-rules.md +129 -0
package/skills/learn/references/entry-schema.md +152 -0
package/skills/learn/references/error-handling.md +178 -0
package/skills/learn/references/id-generation.md +114 -0
package/skills/learn/references/index-format.md +140 -0
package/skills/learn/references/interaction-mode-propagation.md +89 -0
package/skills/learn/references/migration-bootstrap.md +142 -0
package/skills/learn/references/templates/artifacts/captured-entry.md +172 -0
package/skills/learn/references/templates/artifacts/index-update.md +135 -0
package/skills/learn/references/templates/artifacts/learn-input.md +100 -0
package/skills/learn/references/templates/artifacts/maintain-log.md +142 -0
package/skills/learn/references/templates/artifacts/refined-entry.md +168 -0
package/skills/plan/SKILL.md +129 -0
package/skills/plan/modules/design.md +140 -0
package/skills/plan/modules/generate.md +156 -0
package/skills/plan/modules/research.md +122 -0
package/skills/plan/modules/scope.md +121 -0
package/skills/plan/modules/tasks.md +190 -0
package/skills/plan/references/design-complexity-assessment.md +118 -0
package/skills/plan/references/error-handling.md +155 -0
package/skills/plan/references/external-research-guidance.md +61 -0
package/skills/plan/references/high-risk-detection.md +111 -0
package/skills/plan/references/id-generation.md +55 -0
package/skills/plan/references/interaction-mode-propagation.md +75 -0
package/skills/plan/references/learnings-gate-logic.md +93 -0
package/skills/plan/references/plan-tier-selection.md +174 -0
package/skills/plan/references/task-slicing-rules.md +220 -0
package/skills/plan/references/templates/artifacts/design.md +134 -0
package/skills/plan/references/templates/artifacts/final-plan.md +265 -0
package/skills/plan/references/templates/artifacts/research-findings.md +50 -0
package/skills/plan/references/templates/artifacts/scoped-context.md +53 -0
package/skills/plan/references/templates/artifacts/task.md +192 -0
package/skills/plan/references/templates/artifacts/user-input.md +112 -0
package/skills/review/SKILL.md +163 -0
package/skills/review/modules/analyze.md +104 -0
package/skills/review/modules/prepare.md +103 -0
package/skills/review/modules/report.md +109 -0
package/skills/review/modules/scope.md +126 -0
package/skills/review/references/approval-criteria.md +101 -0
package/skills/review/references/change-set-resolution.md +126 -0
package/skills/review/references/error-handling.md +172 -0
package/skills/review/references/id-generation.md +80 -0
package/skills/review/references/interaction-mode-propagation.md +80 -0
package/skills/review/references/review-categories.md +124 -0
package/skills/review/references/scope-creep-detection.md +120 -0
package/skills/review/references/severity-rubric.md +107 -0
package/skills/review/references/templates/artifacts/findings.md +161 -0
package/skills/review/references/templates/artifacts/review-input.md +116 -0
package/skills/review/references/templates/artifacts/review-kit.md +135 -0
package/skills/review/references/templates/artifacts/review-report.md +175 -0
package/skills/review/references/templates/artifacts/review-scope.md +146 -0
package/skills/work/SKILL.md +163 -0
package/skills/work/modules/execute.md +109 -0
package/skills/work/modules/prepare.md +140 -0
package/skills/work/modules/review.md +164 -0
package/skills/work/modules/triage.md +181 -0
package/skills/work/references/ad-hoc-input-resolution.md +122 -0
package/skills/work/references/error-handling.md +183 -0
package/skills/work/references/execution-mode-selection.md +95 -0
package/skills/work/references/id-generation.md +85 -0
package/skills/work/references/interaction-mode-propagation.md +80 -0
package/skills/work/references/review-checklist.md +94 -0
package/skills/work/references/task-execution-rules.md +116 -0
package/skills/work/references/templates/artifacts/execution-log.md +123 -0
package/skills/work/references/templates/artifacts/execution-plan.md +111 -0
package/skills/work/references/templates/artifacts/work-input.md +78 -0
package/skills/work/references/templates/artifacts/work-manifest.md +119 -0
package/skills/work/references/templates/artifacts/work-report.md +143 -0

package/skills/review/modules/prepare.md ADDED Viewed

@@ -0,0 +1,103 @@
+---
+title: Prepare
+description: Second step in the Review workflow. Reads the Review Scope, gathers the diffs/hunks for the change boundary, resolves the spec content (when requirements are present), derives test context (which tests cover the changed files and whether the change ships its own tests), and inventories available static-analysis tools. Returns a Review Kit for the Analyze phase.
+type: module
+version: 1.0
+timestamp: "2026-08-08"
+---
+# Phase 2 - Prepare
+**Purpose:** Second step in the Review workflow. Reads the [Review Scope](../references/templates/artifacts/review-scope.md) from Scope, gathers the actual diffs/hunks for the change boundary's `required` files (and enriches the `context` list with key callers/importers), resolves the spec content when `requirements-source` is present, derives the **test context** (which tests cover the changed files, and whether the change ships its own tests), and inventories the available static-analysis tools (linters / type-checkers / test runner) for Analyze to optionally corroborate findings. Returns a [Review Kit](../references/templates/artifacts/review-kit.md) for the Analyze phase. Prepare gathers materials; it does not run the analysis.
+## Workflow
+This is the Phase 2 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 Scope** from Scope. Specifically verify:
+1. The Review Scope carries `scope-id`, `review-id`, `input-shape`, `interactionMode`, the `change-boundary` (`required` + `context` + `attribution`), `requirements-source`, and `preliminary-scope-creep`.
+2. `interactionMode` is present and valid (default to `smart` if missing; log warning).
+3. Cross-phase consistency: `review-id` matches the Scope output; `interactionMode` is identical across artifacts.
+If the change boundary is explicitly `empty` (Scope recorded a nothing-to-review case), Prepare still produces a minimal Review Kit recording `diffs: none` — do not abort; Analyze will record an empty findings set.
+### Step 1: Gather the Diffs and Enrich Context
+1. For each `required` file in the change boundary, gather the actual diff/hunks using the `attribution` source recorded in the Scope:
+   - `commits` — `git diff <base>..<head> -- <files>` (or the per-file range).
+   - `working-tree` — `git diff -- <files>` (and `git diff --cached -- <files>` for staged portions).
+   - `task-files` (work-linked, no attributable commits) — the working-tree diff of the `required` files; note `diff-source: working-tree-fallback`.
+   - `current-contents` (ad-hoc, no diff) — record the file's current contents as the review target (`diff-source: current-contents`); no hunks.
+2. Capture per file: status (added/modified/deleted/renamed), line counts (`+N / -M`), and the hunks. Deleted files record the deletion (no hunks to review).
+3. **Enrich `context`:** for each modified `required` file, discover key callers/importers of changed public symbols (best-effort: grep import/usage). Record them in `context` with a one-line role ("caller of `foo()`"). Keep this bounded — `context` is reviewer aid, not a second `required` set.
+> This step gathers diffs; it does not edit anything. Prepare is read-only with respect to the code under review.
+### Step 2: Resolve the Spec Content (when requirements present)
+If `requirements-source` is **not** `none`, resolve the source into a structured spec excerpt Analyze will test the change against:
+1. `plan-id` — read the final plan at `docs/plans/<plan-id>*.md` and/or `docs/tasks/<plan-id>/index.md`; extract the relevant Acceptance Criteria and expected behaviors.
+2. `task-criterion` — read the single task's `## Acceptance Criterion` (and its expected behavior).
+3. `spec-doc` — read the referenced markdown/doc and extract the relevant sections.
+4. Record `spec-content` as a structured list (`criterion` + `expected-behavior` per item). If the source exists but the relevant content could not be fully located (partial), that is a Smart pause trigger (Step 6).
+If `requirements-source: none`, record `spec: none` and skip — Analyze will skip the scope-creep-vs-requirements category accordingly.
+### Step 3: Derive the Test Context
+For each `required` file, identify tests that cover it — Analyze's **tests** category uses this to judge coverage and assertion correctness:
+1. **Detect the test runner** from config files in repository root using standard signals (`package.json` + `package-lock.json`/`pnpm-lock.yaml` → npm/pnpm with `jest`/`vitest`/`mocha`; `pyproject.toml`/`pytest.ini` → pytest; `go.mod` + `*_test.go` → go test; `Cargo.toml` → cargo test; `Gemfile` → rspec; `composer.json` → phpunit; `pom.xml`/`build.gradle` → mvn/gradle). Record `test-runner` (and `packageManager` for Node.js). This is informational context, not an authoritative gate.
+2. **Find covering tests** for each changed file by: (a) naming-convention match (`foo.ts` → `foo.test.ts`; `test_foo.py`; `foo_test.go`), and (b) grepping test files for imports of the changed module/symbol. Record, per changed file, the covering test files (possibly empty).
+3. **Note whether the change ships its own tests** — i.e. whether any test files appear in the `required` (added/modified) set. A change that adds production code with **no** accompanying test is itself a finding candidate Analyze will evaluate.
+### Step 4: Inventory Static-Analysis Tools
+Detect available static analysis Analyze may optionally run to corroborate findings (corroborative, not authoritative — Analyze frames findings against the change, not the whole repo). Record the tool inventory (name + command + `configured: true|false` for this repo):
+- **Linters** — `eslint` (`.eslintrc*`), `ruff` (`pyproject.toml`), `golangci-lint` (`.golangci.yml`), `rubocop` (`.rubocop.yml`), `clippy` (`Cargo.toml`), `phpstan`, `checkstyle`.
+- **Type-checkers** — `tsc` (`tsconfig.json`), `mypy`/`pyright`, `gotype`.
+- **Formatters** — `prettier`, `black`, `gofmt` (informational only).
+- **Test runner** — carried from Step 3 (Analyze may re-run the suite to confirm a claimed regression).
+If **no** linter/type-checker is configured for the repo, that is a Smart pause trigger (warn, do not block — Analyze proceeds with manual analysis and notes the absence). The inventory is informational; Prepare does not run these tools.
+### Step 5: Generate the Review Kit Artifact
+1. **Assign a `prepare-id`** per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-prepare`, saved to `docs/plans/.review/.prepare/`). Reuse it if the user later picks **Edit & Retry**.
+2. Produce a **Review Kit** block (as markdown) following the schema in [review-kit.md](../references/templates/artifacts/review-kit.md). Include:
+   - `prepare-id`, inherited `scope-id` and `review-id`, `input-shape`, `interactionMode`
+   - the `diffs` (per-file status, line counts, hunks; `diff-source`) plus the enriched `context` (callers/importers)
+   - `spec-content` (the structured criteria list, or `none`)
+   - `test-context` (per changed file: covering tests; whether the change ships its own tests)
+   - `tool-inventory` (linters/type-checkers/test runner with `configured` flags)
+   - `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 prepare-specific **Smart pause triggers**:
+- `requirements-source` was present but `spec-content` resolved only partially (Step 2), or
+- A `required` file has **no** covering test **and** the change ships **no** accompanying test (Step 3) — a likely test-gap, confirm before Analyze flags it, or
+- No linter/type-checker is configured for the repo (Step 4) — warn and continue; do not block.
+- **Detailed:** present the Review Kit and ask one question with options *(1) Proceed to Analyze, (2) Edit & Retry, (3) Abort*. On **Edit & Retry**, loop back through Steps 1–4 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/.review/.prepare/<prepare-id>.md` (ensure `interactionMode` included) and return it, with the `interactionMode` value, to the Orchestrator for the transition to Phase 3 (Analyze).
+## Output: Review Kit Artifact
+- Verify that the Review Kit is complete and valid: `prepare-id`, `scope-id`, `review-id`, `input-shape`, `interactionMode`, the `diffs`, `spec-content` (or `none`), `test-context`, and `tool-inventory`.
+- Verify that every `required` file has a diff entry (or is recorded as deleted / `current-contents`) and that `context` is separated from `required`.
+- Verify that `test-context` records covering tests per changed file and whether the change ships its own tests.
+- Verify that `requirements-source: none` propagated as `spec: none` (so Analyze skips the requirements-vs-scope-creep category rather than guessing).
+- Verify that the artifact is saved to `docs/plans/.review/.prepare/<prepare-id>.md`.
+> Pass the Review Kit to `analyze` (Phase 3) for the categorized, severity-graded review of the diffs.

package/skills/review/modules/report.md ADDED Viewed

@@ -0,0 +1,109 @@
+---
+title: Report
+description: Fourth and final step in the Review workflow. Derives the final approval status (approved / changes-requested / rejected) from the Findings per the authoritative approval criteria, composes non-binding recommendations, generates the Review Report, registers it in docs/plans/.review/index.md, and (work-linked only) appends a distinct ## Review Report — <report-id> block to the work task index. Returns the Review Report as the Review skill's final deliverable.
+type: module
+version: 1.0
+timestamp: "2026-08-08"
+---
+# Phase 4 - Report
+**Purpose:** Fourth and final step in the Review workflow. Reads the [Findings](../references/templates/artifacts/findings.md) from Analyze, derives the final **approval status** (`approved` / `changes-requested` / `rejected`) per the authoritative criteria, composes non-binding recommendations, writes the [Review Report](../references/templates/artifacts/review-report.md), registers it in `docs/plans/.review/index.md`, and — for work-linked input only — appends a distinct `## Review Report — <report-id>` block to `docs/tasks/<work-id>/index.md` (clearly separate from Work's own `## Work Report` block). Returns the Review Report as the Review skill's final deliverable.
+## Workflow
+This is the Phase 4 pipeline for the Review Skill. It orchestrates the following steps:
+### Step 0: Verification
+Run the **[Step 0 verification](../references/error-handling.md)**. Required input: valid **Findings** from Analyze. Specifically verify:
+1. The Findings carry `analyze-id`, `prepare-id`, `scope-id`, `review-id`, `input-shape`, `interactionMode`, the findings list, and the per-category / per-severity tallies.
+2. **Findings coherence** (orchestrator gate #5): every finding has a `severity`, a `category`, a repository-relative `location`, and either a `trace` or `scope-creep: true`. Report refuses to proceed (Category 2 recovery per [error-handling.md](../references/error-handling.md)) if not — re-run Analyze.
+3. `interactionMode` is present and valid (default to `smart` if missing; log warning).
+4. Cross-phase consistency: `review-id`, `scope-id`, `prepare-id`, `analyze-id` match the upstream artifacts.
+If the Findings set is empty (the nothing-to-review case, or a genuinely clean review), Report still produces a Review Report recording the clean outcome — do not abort.
+### Step 1: Derive the Approval Status
+The approval criteria are authoritative in **[approval-criteria.md](../references/approval-criteria.md)** — Report looks them up, it does not re-encode them:
+- **approved** — no `blocker`, no `major` (any number of `minor`/`nit` acceptable). The change is mergeable.
+- **changes-requested** — at least one `major`, **no** `blocker`; **or** any finding flagged `scope-creep: true`. Fix before merge.
+- **rejected** — at least one `blocker`. Do not merge.
+Derive the status deterministically from the tallies (count of `blocker`/`major` findings and whether any finding carries `scope-creep: true`). Record `approval-status` and a one-line rationale tied to the tallies.
+### Step 2: Compose Recommendations
+1. For **changes-requested / rejected**, list the actionable `blocker`/`major` findings as recommended next steps, each referencing the finding id and `location`. These are **non-binding** — Review is read-only; the user turns them into a follow-up `/plan` + `/work`, or manual fixes.
+2. For **approved** with `minor`/`nit` findings, optionally list them as non-blocking polish suggestions.
+3. Summarize the **scope-creep** outcome: if the scope-creep category ran, summarize the confirmed creep findings (or `none`); if it was `skipped (no requirements)`, record that.
+4. Surface **learnings to capture** — confirmed patterns, gotchas, or forced decisions discovered during Analyze — as candidates (with title, domain, source finding id, and a 1–2 sentence summary). Review does not write `docs/learn/` directly; these are handed to the Learn skill (`/learn`).
+### Step 3: Generate the Review Report Artifact
+1. **Assign a `report-id`** per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-report`, saved to `docs/plans/.review/.report/`). Reuse it if the user later picks **Edit & Retry**.
+2. Produce a **Review Report** block (as markdown) following the schema in [review-report.md](../references/templates/artifacts/review-report.md). Include:
+   - `report-id`, inherited `analyze-id`, `prepare-id`, `scope-id`, `review-id`, `input-shape`, `interactionMode`
+   - the `approval-status` and rationale
+   - the findings rollup (counts by severity and by category)
+   - `recommendations` (actionable for changes-requested/rejected; polish for approved)
+   - `scope-creep-summary` (confirmed findings, `none`, or `skipped (no requirements)`)
+   - `learnings-to-capture` (candidates) and any `learning-gaps`
+   - `work-id` carried (work-linked only, for the index cross-link)
+### Step 4: Register in the Review Registry
+Append a registry row to `docs/plans/.review/index.md`:
+```
+- <report-id> — <target-summary> — <approval-status> — docs/plans/.review/.report/<report-id>.md
+```
+Create the index with a registry header (`# Reviews`) if it does not yet exist. The row is **idempotent on `report-id`**: a re-run overwrites the row with the same id, never duplicates it.
+### Step 5: Cross-Link the Work Index (work-linked only)
+When `input-shape: work-linked`, append a **distinct** status block to `docs/tasks/<work-id>/index.md` — clearly labeled to never collide with Work's own `## Work Report` block:
+```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
+```
+The block is **append-only** and **idempotent on `report-id`** (a re-run overwrites the block with the same id, never duplicates it). If the work index does not exist, skip the cross-link and note it in the report (do not fabricate a work index).
+### Step 6: Present, Confirm, and Save
+Apply the **[phase confirmation behavior](../references/interaction-mode-propagation.md)** for the current `interactionMode`, using these report-specific **Smart pause triggers**:
+- `approval-status` is `changes-requested` or `rejected` (confirm the user wants to finalize vs. re-analyze), or
+- `learnings-to-capture` is non-empty and the user may want to capture them now via `/learn` before closing.
+- **Detailed:** present the Review Report and ask one question with options *(1) Finalize Review, (2) Edit & Retry, (3) Abort*. On **Edit & Retry**, loop back through Steps 1–5 reusing the `report-id` (the registry row and work-index block are overwritten, not duplicated, because they key on `report-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/.report/<report-id>.md` (ensure `interactionMode` included).
+### Step 7: Return to Orchestrator
+Return the Review Report to the Orchestrator — `path`, `report-id`, `review-id`, `approval-status`, `work-id` (if work-linked), `interactionMode`, and `learnings-to-capture` count. The Orchestrator marks the Review workflow complete. Optionally chain to the Learn skill (`/learn`) when `learnings-to-capture` is non-empty; otherwise the session ends. **No GitHub sync is performed** — findings live on disk only; outbound posting is left to a separate, optional step the user may add later.
+## Output: Review Report Artifact
+- Verify that the Review Report is complete and valid: `report-id`, `analyze-id`, `prepare-id`, `scope-id`, `review-id`, `input-shape`, `interactionMode`, `approval-status`, the findings rollup, `recommendations`, `scope-creep-summary`, and `learnings-to-capture`.
+- Verify that **findings coherence** held (re-verified in Step 0): every finding has a severity, category, repo-relative location, and a `trace` or `scope-creep: true`.
+- Verify that the approval status was **derived from** [approval-criteria.md](../references/approval-criteria.md) rather than re-defined inline (no second rule contradicting the authoritative reference).
+- Verify the registry row was appended to `docs/plans/.review/index.md` (idempotent on `report-id`), and — for work-linked input — the distinct `## Review Report — <report-id>` block was appended to `docs/tasks/<work-id>/index.md` (idempotent, never colliding with Work's `## Work Report` block).
+- Verify that the artifact is saved to `docs/plans/.review/.report/<report-id>.md`.
+> The Review Report is the primary deliverable of the Review Skill. The Orchestrator marks the workflow complete; optionally chains to `/learn` when learnings were surfaced.

package/skills/review/modules/scope.md ADDED Viewed

@@ -0,0 +1,126 @@
+---
+title: Scope
+description: Entry point to the Review workflow. Classifies the incoming review target (a git change-set, a /work run via work-id or Work review-id, or an ad-hoc description), resolves it to a concrete change boundary (required + optional-context files), resolves the optional requirements ref, allocates the review-id, runs a scope-creep pre-check against the requirements, and pulls related learnings. Returns a Review Scope for the Prepare phase.
+type: module
+version: 1.0
+timestamp: "2026-08-08"
+---
+# Phase 1 - Scope
+**Purpose:** Entry point to the Review workflow. Classifies the incoming review target (a git change-set, a `/work` run via `work-id` / Work `review-id`, or an ad-hoc description), resolves it to a concrete **change boundary** — a `required` file list (files the change actually touches) plus an optional `context` file list (files recommended for reviewer context) — resolves the optional requirements ref, allocates the `review-id`, runs a scope-creep **pre-check** against the requirements, and pulls related learnings. Returns a [Review Scope](../references/templates/artifacts/review-scope.md) for the Prepare phase.
+## Workflow
+This is the Phase 1 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 Input Artifact** (see [review-input.md](../references/templates/artifacts/review-input.md)) from the Orchestrator. Specifically verify:
+1. The Review Input Artifact carries exactly one of: a `change-set` spec, a `work-id` (or Work `review-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 review? Provide a git ref/range, a work-id, or describe a target."
+### Step 1: Classify Input Shape
+Determine which of the three input shapes applies, by precedence:
+1. **Work-linked** — the input matches an existing `docs/tasks/<work-id>/index.md` (the value is a `YYYY-MM-DD-NNN` work-id), or a Work `review-id` resolving to `docs/plans/.work/.review/<review-id>.md`.
+2. **Change-set** — the input is, or contains, a git ref/range (`<base>..<head>`, `A..B`, `HEAD`, staged, a branch-vs-base diff) or a set of paths/globs.
+3. **Ad-hoc** — a free-text description that matches neither of the above.
+Record `input-shape: work-linked | change-set | ad-hoc`. If classification is ambiguous (e.g., a string that could be a work-id or a description), ask the user one question with the candidate shapes as options.
+### Step 2: Resolve the Change Boundary (by Shape)
+Resolve the classified input into a concrete **change boundary** — `required` files (files the change actually touches — added/modified/deleted/renamed) plus an optional `context` list (files recommended for reviewer context, e.g. key callers — Prepare enriches this; Scope seeds it lightly). The resolution rules are authoritative in **[change-set-resolution.md](../references/change-set-resolution.md)** — this step looks them up, it does not re-derive them.
+#### 2a. Change-set
+1. Parse the spec into a concrete `git diff` invocation (`<base>..<head>`, a commit range, `HEAD`/staged, or paths/globs).
+2. List the files the diff touches with their status (added/modified/deleted/renamed). These are the `required` files.
+3. Seed `context` lightly: for modified files, optionally note immediate callers/importers of changed public symbols (Prepare expands this); leave `context` empty if caller discovery is non-trivial here.
+4. If the diff is empty (spec parses but touches no files), record `change-boundary.empty: true` and proceed — the Review Report will record a nothing-to-review outcome. Do not abort.
+#### 2b. Work-linked
+1. Locate the `work-id` (or, given a Work `review-id`, read `docs/plans/.work/.review/<review-id>.md` to recover the `work-id`).
+2. Read `docs/tasks/<work-id>/index.md` and each task file's `files.create` / `files.modify`. The union of these is the `required` set.
+3. Filter by task outcomes from the Work Report: include files from `completed` tasks; include `blocked`/`skipped` tasks' files but mark them `tentative` (their changes may be partial). Never include files from tasks that were not part of the run.
+4. Optionally bound to commits attributable to the run (e.g., commits whose message references the `work-id`) — best-effort heuristic; if not discoverable, fall back to the working-tree diff of the `required` files. Note which source was used (`attribution: commits | working-tree | task-files`).
+5. Seed `context` lightly as in 2a.
+#### 2c. Ad-hoc
+1. Map the description to concrete paths: locate matching files by path/glob and, where the description names a module/symbol, the files defining it.
+2. Where applicable, find the commits that most recently touched those files (e.g. the last commit per file, or a shallow range) to derive an actual diff. If no committable diff exists, treat the current file contents as the review target and mark `attribution: current-contents`.
+3. The matched files are `required`; `context` is seeded lightly (callers/importers).
+### Step 3: Resolve Optional Requirements
+Accept an optional requirements ref — a `/plan` plan-id, a task's `## Acceptance Criterion`, a markdown spec, or a referenced doc. This sharpens scope-creep detection (Step 4 + Analyze):
+1. **If provided:** record `requirements-source` (type `plan-id | task-criterion | spec-doc | none` + path). Parse it into a structured list of criteria / expected behaviors. Scope-creep detection runs against it.
+2. **If absent:** record `requirements-source: none` and continue. Analyze will **skip** the scope-creep-vs-requirements category (noting it) — Scope does not invent requirements.
+3. If the ref is a `plan-id`, read `docs/plans/<plan-id>...` or `docs/tasks/<plan-id>/index.md` for the Acceptance Criteria and expected behaviors.
+4. If the ref resolves ambiguously (multiple candidate specs), this is a Smart pause trigger (Step 7) — ask the user which to use.
+### Step 4: Scope-Creep Pre-Check
+When `requirements-source` is not `none`, run a **preliminary** scope-creep check. The detection logic is authoritative in **[scope-creep-detection.md](../references/scope-creep-detection.md)** — this step applies it, it does not re-derive it:
+1. Compare the `required` file list and changed behaviors against the resolved requirements.
+2. Flag any changed file/behavior **not traceable to a requirement** as a preliminary scope-creep candidate (file + the candidate reason).
+3. Record `preliminary-scope-creep: [...]` (or `none`). Analyze confirms these with severity in its scope-creep category.
+When `requirements-source: none`, **skip** this step and record `preliminary-scope-creep: skipped (no requirements)`.
+### Step 5: Learnings Index Gate
+Search `docs/learn/index.md` for entries relevant to the review domains (the changed files' domains and the requirements' domains). For the matching logic (keyword extraction, exact + fuzzy match, HIGH/MEDIUM/LOW relevance scoring, gap identification), defer to the Plan skill's **[learnings-gate-logic.md](../../plan/references/learnings-gate-logic.md)**.
+- Add HIGH and MEDIUM relevance learnings to the Review Scope's `Related Learnings`. Unlike Work (which scopes learnings per task), Review scopes them to the **whole change boundary** — a learning applies to the review, not to a single file.
+- 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 review 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: Allocate review-id and Generate the Review Scope Artifact
+1. **Allocate a `review-id`** of the form `YYYY-MM-DD-NNN` per [id-generation.md](../references/id-generation.md), counting existing `docs/plans/.review/.scope/YYYY-MM-DD-NNN-scope.md` files (or registry rows) for today. This is the pipeline umbrella id (distinct from any Work `review-id` for work-linked input — the two skills produce independent artifacts; the `work-id` is carried alongside for traceability).
+2. **Assign a `scope-id`** per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-scope`, saved to `docs/plans/.review/.scope/`). Reuse it if the user later picks **Edit & Retry**.
+3. Produce a **Review Scope Artifact** block (as markdown) following the schema in [review-scope.md](../references/templates/artifacts/review-scope.md). Include:
+   - `scope-id`, `review-id`, `input-shape`, `interactionMode`
+   - the `change-boundary` (`required` file list with status, plus `context` and `attribution`)
+   - `requirements-source` (type + path, or `none`) and the parsed criteria when present
+   - `preliminary-scope-creep` (candidates, `none`, or `skipped (no requirements)`)
+   - `Related Learnings` (scoped to the change boundary) and `Learning Gaps`
+   - `work-id` carried (work-linked only)
+### Step 7: Present, Confirm, and Save
+Apply the **[phase confirmation behavior](../references/interaction-mode-propagation.md)** for the current `interactionMode`, using these scope-specific **Smart pause triggers**:
+- `input-shape` is `ad-hoc` (the change boundary was **inferred**, not user-specified — confirm it matches intent), or
+- `requirements-source` resolved ambiguously (Step 3, multiple candidate specs), or
+- Preliminary scope-creep candidates were detected (Step 4) and the user may want to reconsider what's in scope.
+- **Detailed:** present the Review Scope 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 `scope-id` (and re-allocating `review-id` only if the input shape itself changed). 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/.scope/<scope-id>.md` (ensure `interactionMode`, `input-shape`, and `review-id` are included) and return it, with the `interactionMode` value, to the Orchestrator for the transition to Phase 2 (Prepare).
+## Output: Review Scope Artifact
+- Verify that the Review Scope is complete and valid: `scope-id`, `review-id`, `input-shape`, `interactionMode`, the `change-boundary` (non-empty `required` list or explicitly `empty`), `requirements-source`, and `preliminary-scope-creep`.
+- Verify that the change boundary is in **dependency-safe** form: `required` files are repository-relative and carry a status; `context` is separated from `required`.
+- Verify that `review-id` was allocated (scope is the allocating phase) and that `work-id` is carried for work-linked input.
+- Verify that scope-creep detection was run only when requirements were present (else explicitly skipped with a note), per [scope-creep-detection.md](../references/scope-creep-detection.md).
+- Verify that the artifact is saved to `docs/plans/.review/.scope/<scope-id>.md`.
+> Pass the Review Scope to `prepare` (Phase 2) to gather the diffs, spec content, test context, and tool inventory.

package/skills/review/references/approval-criteria.md ADDED Viewed

@@ -0,0 +1,101 @@
+---
+title: Approval Criteria
+description: Authoritative reference for the Report phase. Defines how the final approval status (approved / changes-requested / rejected) is derived deterministically from the Findings tallies and the presence of any scope-creep flag. Report looks this up; it does not re-encode the rule.
+type: reference
+version: 1.0
+timestamp: "2026-08-08"
+---
+# Approval Criteria
+Authoritative reference for the **Report** phase (Step 1). Defines how the final **approval status** (`approved` / `changes-requested` / `rejected`) is derived deterministically from the Findings tallies (counts by severity) and the presence of any `scope-creep: true` finding. Report looks this reference up; it does not re-encode the rule.
+## The Three Approval Statuses
+| Status                | Meaning                                                | Merge implication                       |
+| --------------------- | ------------------------------------------------------ | --------------------------------------- |
+| `approved`            | The change is mergeable                                | Merge away; optionally address minor/nit |
+| `changes-requested`   | Fix the listed issues before merge                     | Do not merge until the majors / creep are addressed |
+| `rejected`            | Do not merge — a blocker means the change is unsound  | Do not merge; rework and re-review       |
+## Decision Rule (authoritative)
+> Report derives `approval-status` **deterministically** from the Findings tallies and the scope-creep flag. There is no reviewer discretion in the derivation. Do not apply a separate formula — this rule is the single source of truth.
+```
+let b = count of findings with severity == blocker
+let m = count of findings with severity == major
+let creep = any finding with scope-creep == true
+if b >= 1:
+    approval-status = "rejected"
+    rationale = "<b> blocker finding(s); do not merge"
+else if m >= 1 or creep:
+    approval-status = "changes-requested"
+    rationale = "<m> major finding(s)" + (" and <c> scope-creep finding(s)" if creep)
+else:
+    approval-status = "approved"
+    rationale = "no blocker, no major, no scope-creep (<minor> minor, <nit> nit)"
+```
+### Derivation order
+1. **blocker** wins everything: any `blocker` → `rejected`, regardless of majors or creep. Two blockers and zero majors is still `rejected`.
+2. Otherwise **major** and **scope-creep** each independently force `changes-requested`. Either one (or both) is sufficient.
+3. Only when **no blocker, no major, and no scope-creep** is the change `approved` (any number of `minor`/`nit` is acceptable).
+### Why scope-creep forces changes-requested
+A `scope-creep: true` finding (per [scope-creep-detection.md](scope-creep-detection.md)) means the change goes **beyond** the resolved requirements. That is a scope decision the merge should not make silently — the reviewer must explicitly accept the creep as intentional (often by amending the requirements) or roll it back. Hence it forces `changes-requested` even at `minor` severity. A creep finding can still be elevated to `rejected` if it also carries `blocker` via the rubric (e.g. creep that breaks a core flow).
+## Rationale Format
+Record a one-line rationale tied to the tallies (Report Step 1):
+```yaml
+approval-status: changes-requested
+rationale: "2 major finding(s) and 1 scope-creep finding(s); no blocker"
+```
+```yaml
+approval-status: rejected
+rationale: "1 blocker finding(s); do not merge"
+```
+```yaml
+approval-status: approved
+rationale: "no blocker, no major, no scope-creep (3 minor, 2 nit)"
+```
+The rationale always surfaces the counts that drove the decision, so a glance at the report shows why the verdict landed where it did.
+## Empty Findings Set
+When the Findings set is empty (the nothing-to-review case from Scope, or a genuinely clean review), the derivation still runs:
+```
+b = 0, m = 0, creep = false -> approval-status = "approved"
+rationale = "no findings; clean review (or nothing-to-review)"
+```
+A clean review is `approved` by default. The Report records whether this was a genuine clean review or a nothing-to-review (empty boundary) so the reader can tell them apart.
+## Work-linked Edge Cases
+For `input-shape: work-linked`:
+- The Review's `approval-status` is **independent** of the Work run's own `work-state` (`complete`/`partial`/`nothing-done`). Work's Phase-4 Review is a behavior-preserving cleanup; this Review is a standards review. The two verdicts coexist without one overriding the other.
+- The `## Review Report — <report-id>` block appended to the work index records this `approval-status` next to Work's `## Work Report` block so both are visible.
+## Validation (Report Step 1 re-checks)
+- `approval-status` is one of `approved` / `changes-requested` / `rejected`.
+- The derivation matches the rule above for the recorded tallies (a `rejected` only when `b >= 1`; a `changes-requested` only when `b == 0` and (`m >= 1` or `creep`); `approved` only when `b == 0`, `m == 0`, and not `creep`).
+- The rationale surfaces the driving counts.
+- No `approval-status` is derived when findings-coherence failed (Step 0 returned the Findings to Analyze per [error-handling.md](error-handling.md) Category 2).
+## Notes
+- This reference is the single source of truth for the approval derivation. Report looks it up and records the status + rationale; the orchestrator and the other phases never re-encode the rule.
+- The rule is intentionally **non-discretionary**: the same tallies always produce the same status. Reviewer judgment lives in the **finding severities** (per [severity-rubric.md](severity-rubric.md)) and the **scope-creep flag** (per [scope-creep-detection.md](scope-creep-detection.md)), not in the approval derivation.
+- `changes-requested` and `rejected` are both Report Smart pause triggers (per [interaction-mode-propagation.md](interaction-mode-propagation.md)); `approved` with non-empty learnings is also a pause trigger.

package/skills/review/references/change-set-resolution.md ADDED Viewed

@@ -0,0 +1,126 @@
+---
+title: Change-Set Resolution
+description: Authoritative reference for the Scope phase. Defines how a review target (a git change-set, a /work run via work-id/Work review-id, or an ad-hoc description) is resolved into a concrete change boundary: a `required` file list (with status), an optional `context` list (callers/importers), and an `attribution` source (commits / working-tree / task-files / current-contents).
+type: reference
+version: 1.0
+timestamp: "2026-08-08"
+---
+# Change-Set Resolution
+Authoritative reference for the **Scope** phase (Step 2). Defines how a classified review target — a git change-set, a `/work` run (via `work-id` / Work `review-id`), **or** an ad-hoc description — is resolved into a concrete **change boundary**: a `required` file list (files the change actually touches, with status), an optional `context` list (callers/importers for reviewer context), and an `attribution` source naming how the boundary was derived. Scope looks this reference up; it does not re-derive the rules.
+## Change Boundary Shape
+```yaml
+change-boundary:
+  required:
+    - path: "src/lib/redis-client.ts"
+      status: modified | added | deleted | renamed
+      renamed-from: "<old path>"   # only for renamed
+  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
+```
+- **`required`** — files the change actually touches; these are the subjects of the review. Repository-relative.
+- **`context`** — files recommended for reviewer context (callers, importers, sibling modules); **never** subjects of review themselves. Prepare enriches this; Scope seeds it lightly.
+- **`attribution`** — names how the boundary was derived, so Prepare picks the right diff invocation and Analyze judges severity against the right baseline.
+## Resolution by Shape
+### 2a. Change-set
+```
+1. Parse the spec into a concrete git invocation:
+   - "<base>..<head>"     -> git diff <base>..<head> --name-status
+   - "A..B" (commit range)-> git diff A..B --name-status
+   - "HEAD"               -> git diff HEAD --name-status (unstaged) + git diff --cached --name-status (staged)
+   - staged / --cached    -> git diff --cached --name-status
+   - branch-vs-base       -> git diff <base-branch>...<head-branch> --name-status
+   - paths/globs          -> git diff --name-status -- <paths>
+2. Map git name-status codes to boundary statuses:
+   - A -> added, M -> modified, D -> deleted, R<x> -> renamed (record renamed-from), C<x> -> copied
+3. attribution = "commits"; diff-source = the resolved <base>..<head> / range / index form
+4. If the diff is empty (spec parses but touches no files):
+   - record change-boundary.empty: true and attribution/diff-source as above
+   - continue; Report records a nothing-to-review outcome (do not abort)
+5. Seed `context` lightly: for each modified file, optionally note immediate
+   callers/importers of changed public symbols if discoverable cheaply; leave
+   context empty otherwise (Prepare expands it).
+```
+### 2b. Work-linked
+```
+1. Resolve the work-id:
+   - given a work-id (YYYY-MM-DD-NNN): use it directly
+   - given a Work review-id: read docs/plans/.work/.review/<review-id>.md -> work-id
+2. Read docs/tasks/<work-id>/index.md and parse the task checklist
+3. For each task file, read its frontmatter files.create / files.modify
+4. required = union of all files.create + files.modify across the run's tasks
+5. Filter by task outcome from the Work Report:
+   - completed tasks -> include their files (status "modified" or "added" as declared)
+   - blocked / skipped tasks -> include their files but mark them "tentative"
+     (their changes may be partial / not present); Analyze notes the tentative flag
+   - tasks not part of this run -> excluded entirely
+6. Attribution heuristic (best-effort):
+   - if commits attributable to the run are discoverable (message references <work-id>):
+     attribution = "commits"; diff-source = those commits
+   - else fall back to the working-tree diff of the required files:
+     attribution = "task-files"; diff-source = "working-tree-fallback"
+7. Either way, record the work-id and outcome filter on the boundary
+8. Seed `context` lightly as in 2a.
+```
+> The `tentative` flag on blocked/skipped task files is the warning that those changes may be incomplete; Analyze treats a `tentative` file's findings with the understanding the file may not reflect intended final state, but does not silently downgrade severity — the reviewer sees the flag and decides.
+### 2c. Ad-hoc
+```
+1. Map the description to concrete paths:
+   - if it names a path/glob -> glob-expand to matching files
+   - if it names a module/symbol -> locate the file(s) defining it
+   - if it names a directory -> all files under it (bounded; warn if very large)
+2. required = the matched files (status "modified" as the default — ad-hoc
+   targets are usually existing files whose current contents are the review target)
+3. Derive an actual diff where possible:
+   - find the commits that most recently touched those files
+     (e.g. last commit per file, or a shallow range) -> git diff for those
+   - if no committable diff exists (uncommitted or freshly-added files):
+     attribution = "current-contents"; diff-source = "current-contents"
+     (the file's current contents are the review target; no hunks)
+4. Seed `context` lightly (callers/importers of matched symbols).
+5. If the description maps to ZERO concrete files:
+   - Category 3 (invalid review input) recovery: ask the user to name a file,
+     module, or path. Do not fabricate a boundary from a vague description.
+```
+## Attribution Source Semantics
+| attribution       | What it means                                              | Prepare uses it to                                  |
+| ----------------- | --------------------------------------------------------- | --------------------------------------------------- |
+| `commits`         | A real commit range touches the `required` files          | `git diff <range> -- <files>` for real hunks        |
+| `working-tree`   | Change-set input pointed at the working tree               | `git diff -- <files>` + `git diff --cached -- <files>` |
+| `task-files`     | Work-linked; no attributable commits, files derived from task files | `git diff -- <files>` (working-tree-fallback) |
+| `current-contents` | Ad-hoc, no committable diff; file contents are the target | Read current file contents directly (no hunks)      |
+## Validation (Scope Step 3 re-checks)
+A resolved change boundary is **accepted** only when:
+- `required` paths are repository-relative and each carries a `status` (added/modified/deleted/renamed; `tentative` is allowed for blocked/skipped work-linked tasks)
+- `context` is separated from `required` and each `context` entry has a `role` (even if brief)
+- `attribution` and `diff-source` are set consistently (e.g., `attribution: commits` pairs with a real `diff-source: <range>`; `current-contents` pairs with `diff-source: current-contents`)
+- An empty boundary is explicitly `change-boundary.empty: true` (never silently empty) — accepted; Report records nothing-to-review
+On any failure, regenerate the boundary from the relevant sub-step (2a/2b/2c) per [error-handling.md](error-handling.md) Category 2 recovery.
+## Notes
+- This reference is the single source of truth for the change-boundary shape, the per-shape resolution algorithms, and the `attribution` semantics.
+- Scope applies it; Prepare reads the `attribution`/`diff-source` to gather the right diffs (Prepare never re-derives the boundary); Analyze and Report consume the boundary read-only.
+- The boundary intentionally separates `required` (review subjects) from `context` (reviewer aid) so Analyze never files findings about `context` files as if they were the change under review.