arreio 1.0.0-dev.1

package/skills/review/references/error-handling.md

@@ -0,0 +1,172 @@
+---
+title: Error Handling & Recovery
+description: Reference for all Review Skill phases (Scope, Prepare, Analyze, Report). Defines the Step 0 artifact verification procedure, per-type required fields, error categories, recovery workflow, retry limits, and cross-phase consistency checks.
+type: reference
+version: 1.0
+timestamp: "2026-08-08"
+---
+
+# Error Handling & Recovery
+
+This file documents the error handling and recovery strategies shared across all Review Skill phases (Scope, Prepare, Analyze, Report). Each phase begins with a **Step 0: Verification** that validates the incoming artifact; this reference defines the validation rules, recovery actions, and termination conditions.
+
+## Core Principle
+
+**Fail explicitly, never silently.** When an artifact is missing, malformed, or inconsistent, the phase must surface a clear error with a recovery suggestion rather than guessing or proceeding with bad data. Silent failures cascade downstream and produce invalid reviews. The one recognized exception is a *missing learnings index* (Scope Step 5), which logs a single explicit warning rather than failing — but this is a deliberate non-block, not a silent no-op. A second deliberate non-block is a *missing requirements source* (`requirements-source: none`), which is a legitimate review input that skips the scope-creep category by design, not an error.
+
+## Step 0: Artifact Verification
+
+Every phase receives an artifact from the previous phase (or the Orchestrator, for Scope). Step 0 validates the artifact before any work begins.
+
+### Verification Procedure
+
+```
+1. Confirm the artifact exists and is non-empty
+2. Confirm the required frontmatter fields are present and well-formed
+3. Confirm the artifact type matches the expected phase input
+4. Confirm interactionMode is present and valid (default to "smart" if missing)
+5. Confirm cross-phase IDs match the upstream artifacts
+```
+
+### Required Fields by Artifact Type
+
+| Artifact Type   | Required Fields                                                                                                                                                                                                    | Produced By  |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
+| `review-input`  | `type`, `timestamp`, `source`, `status`, input shape (`change-set` **or** `work-id`/Work `review-id` **or** `ad-hoc`), `interactionMode`                                                                          | Orchestrator |
+| `review-scope`  | `scope-id`, `review-id`, `input-shape`, `status`, `interactionMode`, `change-boundary` (`required` + `context` + `attribution`), `requirements-source`, `preliminary-scope-creep`                                  | Scope        |
+| `review-kit`    | `prepare-id`, `scope-id`, `review-id`, `input-shape`, `status`, `interactionMode`, `diffs`, `spec-content` (or `none`), `test-context`, `tool-inventory`                                                          | Prepare      |
+| `findings`      | `analyze-id`, `prepare-id`, `scope-id`, `review-id`, `input-shape`, `status`, `interactionMode`, findings list, per-category tallies, per-severity tallies                                                        | Analyze      |
+| `review-report` | `report-id`, `analyze-id`, `prepare-id`, `scope-id`, `review-id`, `input-shape`, `status`, `interactionMode`, `approval-status`, findings rollup, `recommendations`, `scope-creep-summary`                       | Report       |
+
+## Error Categories
+
+### Category 1: Missing Artifact
+
+The expected input artifact was not provided by the Orchestrator or previous phase.
+
+| Trigger                           | Recovery Action                                               | Terminate?         |
+| --------------------------------- | ------------------------------------------------------------- | ------------------ |
+| Artifact object is null/undefined | Ask Orchestrator to re-run previous phase                     | Yes, after 1 retry |
+| Artifact file path does not exist | Log warning; ask user to locate file or re-run previous phase | No                 |
+| Artifact file is empty (0 bytes)   | Re-run previous phase from its saved context                  | Yes, after 1 retry |
+
+### Category 2: Malformed Artifact
+
+The artifact exists but is missing required fields or has invalid structure.
+
+| Trigger                                       | Recovery Action                                             | Terminate? |
+| --------------------------------------------- | ----------------------------------------------------------- | ---------- |
+| Missing required frontmatter field            | Re-run previous phase to regenerate artifact                | No         |
+| `interactionMode` missing or invalid          | Default to `smart`; log warning; continue                   | No         |
+| `status` field is `failed` or `pending`       | Reject; ask Orchestrator to re-run previous phase           | Yes        |
+| Artifact `type` does not match expected input | Reject; ask Orchestrator to check phase ordering            | Yes        |
+| YAML frontmatter has syntax errors            | Log error with line number; ask user to fix or re-run phase | No         |
+| Findings coherence violated (Step 0 of Report) | Re-run Analyze — a finding lacks severity/category/location/trace | No    |
+
+### Category 3: Invalid Review Input
+
+Only applies to the Scope phase (Step 0) when resolving a Review Input Artifact.
+
+| Trigger                                              | Recovery Action                                            | Terminate? |
+| ---------------------------------------------------- | --------------------------------------------------------- | ---------- |
+| All three input shapes empty or ambiguous            | Ask: "What would you like to review? git ref/range, work-id, or describe." | No         |
+| Change-set spec parses but the repo is not a git working tree | Ask to switch to ad-hoc input                        | No         |
+| Change-set diff is empty (spec touches no files)      | Record `change-boundary.empty: true`; continue (Report records nothing-to-review) | No |
+| Work-linked `work-id` with no `docs/tasks/<id>/index.md` | Ask to run `/work <work-id>` first, or switch to change-set | No    |
+| Work-linked Work `review-id` file missing             | Ask to switch to the `work-id` of that run                 | No         |
+| Ad-hoc description maps to no concrete files/commits  | Ask the user to name a file, module, or path               | No         |
+
+### Category 4: File System Errors
+
+Errors encountered while saving or reading artifact files.
+
+| Trigger                                          | Recovery Action                                                   | Terminate?         |
+| ------------------------------------------------ | ----------------------------------------------------------------- | ------------------ |
+| Target directory does not exist                  | Create directory (`mkdir -p`); treat counter as 0; start from 001 | No                 |
+| Counter directory exists but no files match date | Start counter at 001                                              | No                 |
+| File write permission denied                     | Log error; ask user to check permissions; retry once              | Yes, after 1 retry |
+| `docs/plans/.review/index.md` registry missing  | Create it with a `# Reviews` header (Pre-Flight already creates; idempotent) | No     |
+| `docs/tasks/<work-id>/index.md` missing (Report cross-link) | Skip the cross-link; note the absence in the report (do not fabricate a work index) | No |
+
+### Category 5: Interaction Mode Errors
+
+Errors related to `interactionMode` propagation.
+
+| Trigger                                  | Recovery Action                                            | Terminate? |
+| ---------------------------------------- | ---------------------------------------------------------- | ---------- |
+| Mode missing from incoming artifact      | Default to "smart"; log warning; continue                  | No         |
+| Mode value is not in enum                | Reject; re-prompt Orchestrator to set valid mode            | Yes        |
+| User selects "Abort" during confirmation | Stop immediately; inform Orchestrator of abort with reason   | Yes        |
+| User does not respond (timeout)          | Pause; ask user to retry or abort                          | No         |
+
+### Category 6: Analysis Errors (Analyze phase)
+
+| Trigger                                              | Recovery Action                                                    | Terminate? |
+| ---------------------------------------------------- | ------------------------------------------------------------------ | ---------- |
+| No review categories produced (empty Findings unexpectedly) | Re-run Analyze Step 1; confirm the kit's diffs were non-empty | No         |
+| A finding lacks a `trace` or `scope-creep` flag (coherence) | Reject the findings set; re-run Analyze Steps 1–3                | No         |
+| Tool corroboration fails (tool unavailable/unconfigured) | Proceed without corroboration; note it on the finding (Prepare already warned) | No |
+| Scope-creep category emitted findings with `spec-content: none` | Reject; re-run Analyze — scope-creep requires requirements       | No         |
+
+## Recovery Workflow
+
+When a verification failure is detected in Step 0, apply this workflow:
+
+```
+1. Identify the error category (1-6) from the tables above
+2. Look up the specific trigger to find the recovery action
+3. Execute the recovery action:
+   - If recovery is "ask user": ask one question with clear options (2-4 concrete choices)
+   - If recovery is "re-run previous phase": return to Orchestrator with error context
+   - If recovery is "default and continue": apply default, log warning, proceed
+4. If terminate = Yes: stop and inform Orchestrator with:
+   - Error category and trigger
+   - Recovery action attempted
+   - Reason for termination
+5. If terminate = No: after recovery, continue to Step 1 of the phase
+```
+
+## Retry Limits
+
+- **Maximum retries per error:** 1
+- **Maximum total retries per phase:** 2
+- After exhausting phase retries, terminate with a clear error suggesting the user re-run the review workflow from the start or resume from the last complete phase.
+
+> Review is **not resume-safe** like Work execution: re-running Review re-derives findings fresh because the change set may have evolved. The retry limits above apply to within-phase recovery of a malformed/missing artifact, not to resuming an interrupted review run.
+
+## Error Reporting Format
+
+When reporting an error to the Orchestrator or user, use this format:
+
+```yaml
+error:
+  phase: scope | prepare | analyze | report
+  step: 0 | 1 | 2 | ...
+  category: 1 | 2 | 3 | 4 | 5 | 6
+  trigger: "[specific trigger description]"
+  recovery_attempted: "[action taken]"
+  outcome: recovered | terminated
+  suggestion: "[next step for the user or Orchestrator]"
+```
+
+## Cross-Phase Consistency Checks
+
+The Orchestrator should verify consistency between phases:
+
+| Check                                                                 | Action on Failure                           |
+| --------------------------------------------------------------------- | ------------------------------------------- |
+| `review-id` in downstream artifact matches the Scope output           | Reject; re-run from Scope                   |
+| `scope-id` in Prepare+ matches Scope output                          | Reject; re-run from Scope                   |
+| `prepare-id` in Analyze+ matches Prepare output                      | Reject; re-run from Prepare                 |
+| `analyze-id` in Report matches Analyze output                        | Reject; re-run from Analyze                 |
+| `interactionMode` is identical across all artifacts                   | Log warning; use earliest non-default value |
+| `work-id` (work-linked only) carried consistently where present      | Log warning; do not fabricate                |
+
+## Notes
+
+- All errors and warnings should be logged with a timestamp for debugging.
+- When a phase terminates, its saved artifact (if any) should be marked `status: failed`.
+- The Orchestrator is responsible for deciding whether to retry the entire workflow or re-run from the last successful phase.
+- ID assignment and re-use (including recycle-on-edit) is defined in [id-generation.md](id-generation.md); this reference covers only verification and recovery.
+- A `requirements-source: none` input is a **legitimate** review configuration (Category 3 handles empty/ambiguous input; `none` is the documented skip path for the scope-creep category), not an error.
+- This reference is shared by all four phases; phase-specific handling is documented inline in the respective module.

package/skills/review/references/id-generation.md

@@ -0,0 +1,80 @@
+---
+title: Artifact ID Generation
+description: Reference for Scope, Prepare, Analyze, and Report phases. Defines the daily-counter algorithm for unique artifact IDs, the review-id umbrella allocation (distinct from a Work review-id), the recycle-on-edit rule, and the shared counter layout under docs/plans/.review/.
+type: reference
+version: 1.0
+timestamp: "2026-08-08"
+---
+
+# Artifact ID Generation
+
+Shared ID algorithm for the `scope`, `prepare`, `analyze`, and `report` phases, plus the `review-id` umbrella allocation in Scope. Each phase assigns exactly one ID per newly produced artifact; the ID is reused (never re-incremented) when the user picks **Edit & Retry** at the phase confirmation.
+
+## ID Format by Phase
+
+| Phase    | ID format                            | Saved to                            |
+| -------- | ----------------------------------- | ----------------------------------- |
+| Scope    | `YYYY-MM-DD-NNN-scope`              | `docs/plans/.review/.scope/<id>.md`    |
+| Prepare  | `YYYY-MM-DD-NNN-prepare`            | `docs/plans/.review/.prepare/<id>.md`  |
+| Analyze  | `YYYY-MM-DD-NNN-analyze`            | `docs/plans/.review/.analyze/<id>.md`  |
+| Report   | `YYYY-MM-DD-NNN-report`             | `docs/plans/.review/.report/<id>.md`   |
+
+`review-id` (see below) is the umbrella shared across all four artifacts of a single review run.
+
+## review-id
+
+The `review-id` is the umbrella key that ties all four phase artifacts together and keys the registry row / work-index block. It is allocated **once** in Scope Step 2 (the allocating phase) and carried through Prepare/Analyze/Report unchanged.
+
+**Format:** `YYYY-MM-DD-NNN` (date + zero-padded 3-digit daily counter), counting existing `docs/plans/.review/.scope/YYYY-MM-DD-NNN-scope.md` files for that date (the scope phase is the allocating phase, so its counter is the source of truth for the umbrella id).
+
+> **Distinct from a Work `review-id`.** When Review is invoked over a `/work` run (`input-shape: work-linked`), the Work skill's own `review-id` (`docs/plans/.work/.review/...`) **already exists**. The Review skill allocates its **own** `review-id` (`docs/plans/.review/...`) — the two skills produce independent artifacts and never share an id. The `work-id` is carried alongside in the Review artifacts for traceability and the work-index cross-link, but `review-id` ≠ Work `review-id`.
+
+## Algorithm (new phase artifact)
+
+```
+1. Get the current date in UTC (e.g., 2026-08-08)
+2. List existing files for today in the phase's save directory:
+   - scope    -> docs/plans/.review/.scope/     matching YYYY-MM-DD-*-scope.md
+   - prepare  -> docs/plans/.review/.prepare/   matching YYYY-MM-DD-*-prepare.md
+   - analyze  -> docs/plans/.review/.analyze/   matching YYYY-MM-DD-*-analyze.md
+   - report   -> docs/plans/.review/.report/    matching YYYY-MM-DD-*-report.md
+3. NNN = (count + 1), zero-padded to 3 digits (001, 002, ..., 010, ...)
+4. id = "<date>-<NNN>-<phase>"
+```
+
+If two scope artifacts were created today, the next one is `2026-08-08-003-scope`. Counters are independent per phase; each phase counts only its own files.
+
+## Algorithm (review-id umbrella allocation)
+
+Allocated **only** in Scope Step 2:
+
+```
+1. Get the current date in UTC
+2. List existing files under docs/plans/.review/.scope/ matching YYYY-MM-DD-NNN-scope.md for that date
+3. NNN = (highest existing NNN for that date), zero-padded to 3 digits
+   - if none exist for that date, start at 001
+4. review-id = "<date>-<NNN>"  (the same NNN as the scope-id being allocated)
+5. Write the scope artifact with both review-id and scope-id
+```
+
+Because `review-id` reuses the scope counter's NNN, the umbrella id and the `scope-id` share the same date+counter suffix (e.g., `review-id: 2026-08-08-001` → `scope-id: 2026-08-08-001-scope`). Subsequent phases (`prepare-id`, `analyze-id`, `report-id`) **reuse that same NNN** if available on the same date — they do **not** independently allocate a new NNN that could orphan from the umbrella id. If the NNN is taken by an unrelated artifact on the same date in a later phase directory (rare), the later phase appends and notes the divergence in its artifact (the umbrella `review-id` is still carried everywhere).
+
+## Recycle on Edit & Retry
+
+When the user picks **Edit & Retry** at a phase confirmation, **reuse the original ID** and overwrite the existing artifact file. Do **not** increment the counter. This keeps IDs stable across iterations and prevents orphaned artifacts. The Report phase's registry row in `docs/plans/.review/index.md` and the `## Review Report — <report-id>` block in the work index are likewise idempotent on `report-id` (overwritten, never duplicated).
+
+## Error Handling
+
+| Trigger                                         | Action                                       |
+| ----------------------------------------------- | -------------------------------------------- |
+| Phase save directory does not exist              | Create it; treat count as 0; start from 001  |
+| Directory exists but no files match today's date | Start counter at 001                         |
+| `docs/plans/.review/` missing                   | Create it (Pre-Flight already creates; idempotent) |
+| Write permission denied                         | Log error; ask the user; retry once          |
+
+## Notes
+
+- IDs reuse the daily-counter algorithm for cross-skill consistency with `/plan` and `/work`; the Review skill's counters are independent from those skills (separate save directories under `docs/plans/.review/` vs `.work/`).
+- `review-id` carries through every artifact (`scope-id` artifacts record it; Prepare/Analyze/Report inherit it), so cross-phase chaining is `scope-id → prepare-id → analyze-id → report-id`, all sharing one `review-id` (see [error-handling.md](error-handling.md) "Cross-Phase Consistency Checks").
+- For work-linked input, `work-id` is **additionally** carried (inherited from the Review Input Artifact), distinct from `review-id`, for the registry cross-link only.
+- Counter collisions are impossible within a date because each phase writes to its own directory and recomputes the count from the directory listing.

package/skills/review/references/interaction-mode-propagation.md

@@ -0,0 +1,80 @@
+---
+title: Interaction Mode Propagation
+description: Reference for how `interactionMode` propagates through the Review pipeline (Scope -> Prepare -> Analyze -> Report). Set at the Orchestrator; each phase reads and applies mode-specific behavior. Review has no execution mode — only interactionMode.
+type: reference
+version: 1.0
+timestamp: "2026-08-08"
+---
+
+# Interaction Mode Propagation
+
+Reference for how `interactionMode` propagates through the Review pipeline (`Scope → Prepare → Analyze → Report`). Set at the Orchestrator; each phase reads and applies mode-specific behavior.
+
+> `interactionMode` governs **when to pause for the user**. Unlike the Work skill, **Review has no execution mode** — analysis is a single forward pass over the diffs, not a multi-task run, so there is no `executionMode` selector. Only `interactionMode` is carried through every artifact.
+
+## Modes
+
+| Mode          | Behavior                                              | Use Case                             |
+| ------------- | ----------------------------------------------------- | ------------------------------------ |
+| **Detailed**  | Pause at each phase; present artifacts; require approval | High-stakes or sensitive reviews, unfamiliar changes |
+| **Smart**     | Auto-proceed; pause only on HIGH-severity findings (blocker/major) or detected scope creep | Familiar changes with guardrails |
+| **Autopilot** | Run all phases auto (Report still presented)           | Routine reviews of well-understood changes |
+
+## Phase Behavior by Mode
+
+| Phase        | Detailed                                         | Smart                                                                                                       | Autopilot                         |
+| ------------ | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | --------------------------------- |
+| **Scope**    | Present review scope; ask Proceed/Edit/Abort      | Auto-proceed; pause if ad-hoc inferred boundary, ambiguous requirements, or preliminary scope-creep detected | Auto-proceed                      |
+| **Prepare**  | Present review kit; ask Proceed/Edit/Abort        | Auto-proceed; pause if partial spec resolution, a no-coverage test gap, or no linter configured            | Auto-proceed                      |
+| **Analyze**  | Present findings; ask Proceed/Edit/Abort          | Auto-proceed; pause if any `blocker`/`major` finding, scope-creep confirmed, or creep tally differs from Scope's preliminary count | Auto-proceed                      |
+| **Report**   | Present review report; ask Finalize/Edit/Abort   | Auto-proceed; pause if `changes-requested`/`rejected`, or `learnings-to-capture` non-empty                   | Auto-proceed (strips to Smart triggers) |
+
+**Smart mode pauses only on each phase's documented triggers above** (the canonical list lives in each module's confirmation step; this table is a summary).
+
+## Artifact Schema
+
+All phase artifacts include `interactionMode`:
+
+```yaml
+interactionMode: detailed | smart | autopilot # Passed from previous phase
+status: pending | complete | failed
+```
+
+## Implementation
+
+**Each phase must:**
+
+1. Read `interactionMode` from the incoming artifact (or context, for Scope).
+2. Apply mode-specific behavior per the table above.
+3. Include `interactionMode` in the output artifact.
+
+## Example
+
+**SMART mode on a change-set review:**
+
+- Scope parses a `<base>..<head>` diff (not inferred) → auto-proceeds
+- Prepare resolves a present spec fully, finds test coverage and a configured linter → auto-proceeds
+- Analyze finds one `major` quality finding and no scope-creep → pauses (major finding trigger)
+- User reviews the major finding, confirms it's real (chooses Proceed to Report)
+- Report derives `changes-requested`, learnings-to-capture non-empty → pauses (changes-requested + learnings triggers)
+- User finalizes; the Report is saved and the registry row appended
+
+**Result:** Paused only for the genuine major finding and the change-requested finalization; faster than Detailed with safety guardrails.
+
+## No Execution Mode (contrast with Work)
+
+Review deliberately has **no** `executionMode`:
+
+- Work's `executionMode` (`inline`/`serial`/`parallel`) governs how multiple independent **tasks** run — Review has no multi-task concept; analysis is a single forward pass over the change boundary.
+- The orchestrator's quality gate #2 for Review cross-checks **only** `interactionMode` (not `interactionMode` + `executionMode` as in Work).
+- A `blocker`/`major` finding is the Review analog of Work's HIGH-risk flag: it triggers pause behavior, but via `interactionMode`'s Smart triggers, not a separate mode.
+
+## Error Handling
+
+| Scenario                    | Recovery                              |
+| --------------------------- | ------------------------------------- |
+| Mode missing                | Default to "smart"; log warning       |
+| Invalid mode value          | Reject; re-prompt Orchestrator        |
+| Artifact missing mode field | Assume "smart"; log warning; continue |
+| User selects "Abort"        | Stop immediately; inform Orchestrator |
+| Timeout/connection lost     | Pause; ask user to retry or abort     |

package/skills/review/references/review-categories.md

@@ -0,0 +1,124 @@
+---
+title: Review Categories
+description: Authoritative reference for the Analyze phase. Defines the six review categories (quality, security, tests, documentation, integration, scope-creep) and the per-category checks Analyze runs across the Review Kit's diffs. Analyze applies the categories; it does not re-encode them.
+type: reference
+version: 1.0
+timestamp: "2026-08-08"
+---
+
+# Review Categories
+
+Authoritative reference for the **Analyze** phase (Step 1). Defines the six review categories and the per-category checks Analyze runs across the Review Kit's diffs. Each finding is tagged with exactly one `category` from this reference, a `severity` per [severity-rubric.md](severity-rubric.md), and a `location` (repository-relative `file:line` or `file:hunk`). Analyze applies the categories; it does not re-encode them.
+
+## The Six Categories
+
+| Category        | What it reviews                                                          | Runs when                       |
+| --------------- | ------------------------------------------------------------------------ | ------------------------------- |
+| `quality`       | Design, clarity, DRY, naming, error handling, structural soundness       | Always                          |
+| `security`      | Input validation, authn/authz, secrets, injection, unsafe patterns       | Always                          |
+| `tests`         | **Test the tests:** coverage, assertion correctness, flakiness, test smells, missing tests | Always           |
+| `documentation` | Public API docs, README, inline comments, changelog for changed behavior | Always                          |
+| `integration`   | Caller/contract impact, module boundaries, project conventions, consumer breakage | Always                  |
+| `scope-creep`   | Changes beyond the resolved requirements                                 | Only when `spec-content` not `none` |
+
+The scope-creep category is the only conditional one; the other five always run. Its detection logic is authoritative in [scope-creep-detection.md](scope-creep-detection.md); this reference lists it only as a category and points to that file for the algorithm.
+
+## Per-Category Checks
+
+### quality
+
+Review the changed production code (and the non-test parts of touched files) for:
+
+| Check                  | Criteria (authoritative)                                                                              |
+| ---------------------- | ------------------------------------------------------------------------------------------------------ |
+| Design & structure     | The change fits the existing architecture; no gratuitous abstraction or premature layering             |
+| Clarity                 | Intent is readable; no cryptic or misnamed symbols; complex logic is commented where needed           |
+| DRY                     | No duplicated logic introduced by the change that belongs in a shared helper                            |
+| Naming                  | Identifiers are intention-revealing (matches project conventions)                                      |
+| Error handling          | Errors are propagated/handled explicitly, not swallowed; no silent `catch` that hides root causes     |
+| Structural soundness    | Functions/classes do one thing; no overlarge units introduced; no speculative generality               |
+
+Trim, don't add: a quality finding is warranted when the change **introduces** a smell, not by a pre-existing condition outside the change boundary.
+
+### security
+
+Review the change for:
+
+| Check                  | Criteria (authoritative)                                                                              |
+| ---------------------- | ------------------------------------------------------------------------------------------------------ |
+| Input validation        | User/external input is validated at the boundary; no untrusted data flowing unchecked                   |
+| Authn / authz           | Authentication/authorization checks are present where the change touches a protected path              |
+| Secret leakage          | No secrets (API keys, tokens, passwords) added to code/config/logs; no secret committed to disk        |
+| Injection               | No SQL/OS/command/template injection introduced; parameterized queries used                             |
+| Unsafe patterns         | No `eval`/`exec`/`innerHTML`/deserialization-of-untrusted-data/path-traversal introduced               |
+| Dependency safety      | No known-vulnerable dependency added (Analyze notes it; corroborate with a scanner if configured)      |
+
+A security finding is almost always at least `major`, often `blocker` per [severity-rubric.md](severity-rubric.md).
+
+### tests
+
+**Test the tests** — evaluate the tests that accompany the change, not just production code. Use the Review Kit's `test-context` (covering tests per changed file; whether the change ships its own tests):
+
+| Check                  | Criteria (authoritative)                                                                              |
+| ---------------------- | ------------------------------------------------------------------------------------------------------ |
+| Coverage                | Changed behavior is covered by a test; a production-code change with **no** accompanying test is a finding |
+| Assertion correctness   | Tests assert the **intended** behavior (the Acceptance Criterion / expected behavior), not incidental implementation details |
+| Flakiness               | No timing/order-dependent assertions, no shared mutable state, no reliance on external network/state    |
+| Test smells             | No skipped/`.only`/commented-out assertions; no brittle string-matching where structural checks suffice |
+| Boundary cases          | Edge cases (empty, null, max, error paths) are covered where the behavior warrants it                   |
+
+> A change that adds production code without any test is itself a `major` finding (or `blocker` if the changed behavior is security/core-flow). This is the **most important** tests-category signal.
+
+### documentation
+
+Review the change for:
+
+| Check                  | Criteria (authoritative)                                                                              |
+| ---------------------- | ------------------------------------------------------------------------------------------------------ |
+| Public API docs         | New/changed public exports are documented (JSDoc/docstrings/OpenAPI) where the project documents them  |
+| README / changelog     | User-facing behavior changes are noted in README/CHANGELOG per project convention                       |
+| Inline comments         | Non-obvious logic is commented (intent, not mechanics); no commented-out code left                       |
+| Removed docs            | When behavior is removed/deprecated, the docs are updated to match (no stale references)                 |
+
+Documentation findings are typically `minor`/`nit` unless the change silently alters a public/documented behavior (then `major`).
+
+### integration
+
+Review the change's impact on the surrounding system (use the Review Kit's `context` callers/importers):
+
+| Check                  | Criteria (authoritative)                                                                              |
+| ---------------------- | ------------------------------------------------------------------------------------------------------ |
+| Caller / contract impact| Callers of changed public symbols still compile/behave; no silent contract break                         |
+| Module boundaries       | The change respects module boundaries; no cross-boundary coupling introduced                            |
+| Project conventions     | The change follows the project's conventions (naming, layering, import rules, error style)              |
+| Consumer breakage       | No downstream consumer (internal or external) is broken by the change                                   |
+| Backward compatibility  | Backward-incompatible changes are deliberate and surfaced (not silent)                                   |
+
+An integration finding that breaks consumers is typically `major`; a silent breaking change is `blocker`.
+
+### scope-creep
+
+**Only when `spec-content` is not `none`.** The detection algorithm is authoritative in [scope-creep-detection.md](scope-creep-detection.md). Each creep finding carries `scope-creep: true` (never a `trace`) and a `location`. When `spec-content: none`, Analyze records this category as `skipped (no requirements)` and emits no scope-creep findings.
+
+## How to Use This Reference (Analyze)
+
+1. For each changed file in the Review Kit's `diffs`, run the five always-on categories against the hunks.
+2. Run the scope-creep category only when `spec-content` is present, per [scope-creep-detection.md](scope-creep-detection.md).
+3. Tag each finding with exactly one `category` from the table above, a `severity` from [severity-rubric.md](severity-rubric.md), and a `location`.
+4. Attach a `trace` **or** `scope-creep: true` flag per [scope-creep-detection.md](scope-creep-detection.md).
+5. Optionally corroborate a finding with a configured tool (linter/type-checker/test run) — tools corroborate, they never create findings outside the change boundary.
+
+## Failure-Condition Reference
+
+| Trigger                                                | Outcome per this reference                                  |
+| ------------------------------------------------------ | ----------------------------------------------------------- |
+| Production-code change with no accompanying test         | `tests` finding (signal severity per rubric)                |
+| Scope-creep category invoked with `spec-content: none`   | Reject per [error-handling.md](error-handling.md) Category 6 |
+| Finding with no `category` from this reference           | Reject (Category 2 / Category 6 recovery)                   |
+| A finding warranted only by a pre-existing repo condition (outside the change boundary) | Drop the finding — Review reviews the change, not the whole repo |
+
+## Notes
+
+- This reference is the single source of truth for the category set and per-category check criteria. Analyze applies it; Report aggregates by category and never re-defines the checks.
+- Tools (linters/type-checkers/test runs) are **corroborative only** — a finding must be warranted by the change under review, never by a pre-existing condition elsewhere in the repo. This is the guardrail against "Review became a repo-wide audit."
+- The scope-creep category deliberately defers to [scope-creep-detection.md](scope-creep-detection.md) for its algorithm; this reference lists it only as a category to avoid re-encoding the detection rules in two places (honoring single-source-of-truth).

package/skills/review/references/scope-creep-detection.md

@@ -0,0 +1,120 @@
+---
+title: Scope-Creep Detection
+description: Authoritative reference for the Scope phase (Step 4 pre-check) and the Analyze phase (final scope-creep category). Defines how changed files/behaviors are compared against resolved requirements to detect changes beyond the intended scope, the requirement-trace logic, and the rule that scope-creep can only run when a requirements source is present.
+type: reference
+version: 1.0
+timestamp: "2026-08-08"
+---
+
+# Scope-Creep Detection
+
+Authoritative reference for the **Scope** phase (Step 4 preliminary check) and the **Analyze** phase (Step 1, scope-creep category). Defines how the `required` file list and changed behaviors are compared against resolved requirements to detect changes **beyond the intended scope**, the **requirement-trace** logic attached to every finding, and the hard rule that the scope-creep category can only run when a requirements source is present. Scope and Analyze apply this reference; they do not re-encode it.
+
+## Core Rule
+
+> **Scope-creep detection requires requirements.** The category runs **only** when `requirements-source` is not `none`. When `requirements-source: none`, the category is **skipped** with the recorded note `skipped (no requirements)` and emits **no** scope-creep findings. Review never invents requirements to test against — without a spec, scope-creep is unmeasurable, and that is recorded explicitly, not silently.
+
+This single rule prevents the most common mis-escalation (flagging "creep" against an imagined contract). A missing spec is a legitimate review configuration, not an error (see [error-handling.md](error-handling.md)).
+
+## Resolved Requirements Shape
+
+When `requirements-source` is present, Scope (Step 3) resolves it into a structured list:
+
+```yaml
+spec-content:
+  - criterion: "C1: Redis client connects with retry"
+    expected-behavior:
+      - "connect() reads REDIS_URL"
+      - "connect() retries up to 3 times on connection failure"
+  - criterion: "C2: SessionStore exports get/save/delete"
+    expected-behavior:
+      - "get(key) returns the stored value or null"
+```
+
+Each requirement has a short `criterion` id (e.g. `C1`, `C2`) and a list of `expected-behavior` bullets. The requirement ids become the `trace` values Analyze attaches to in-scope findings.
+
+## Requirement Trace vs Scope-Creep Flag
+
+Every finding produced by Analyze carries **either** a `trace` **or** a `scope-creep: true` flag (orchestrator quality gate #5):
+
+| Field                | When                                                                 | Example                                |
+| -------------------- | ------------------------------------------------------------------- | -------------------------------------- |
+| `trace: <criterion>` | The finding is **inside** the intended scope, relating to a requirement | `trace: C1` (a quality issue in the redis connect code) |
+| `trace: general-quality` | The finding is within the change's intent but not tied to one criterion (acceptable trace) | a naming issue in a touched helper |
+| `trace: no-requirements` | The finding is a quality/security/test/doc/integration issue but `spec-content: none` (scope-creep cannot be assessed) | any finding when there is no spec |
+| `scope-creep: true`  | The finding describes a change **beyond** the requirements (the creep itself, not a defect) | a file/behavior with no requirement it serves |
+
+> `scope-creep: true` is **never** set when `spec-content: none` — without requirements, "beyond scope" is undefined. Such findings carry `trace: no-requirements` instead.
+
+## Detection Algorithm (Scope Step 4 — preliminary)
+
+Run only when `requirements-source` is not `none`. This is a **preliminary** file-level check; Analyze confirms with severity.
+
+```
+1. For each file in change-boundary.required:
+   - find the requirement(s) it serves (by path/convention match against spec-content)
+   - if a required file or a changed behavior maps to NO requirement:
+     -> add a preliminary scope-creep candidate: { file, candidate-reason }
+2. For each requirement in spec-content:
+   - if NO required file maps to it (expected change is absent):
+     -> add a preliminary gap candidate: { criterion, expected-but-absent }
+     (this is reported for context, NOT as creep — it's an omission, not creep)
+3. Record preliminary-scope-creep: [...] (or "none")
+4. If requirements-source: none -> record preliminary-scope-creep: "skipped (no requirements)"
+```
+
+The preliminary check is deliberately **coarse** (file-level); Analyze's final category check operates at the file-and-behavior level and assigns severity. The gap candidates (expected-but-absent) are surfaced for Analyze's tests/integration categories (coverage gaps), **not** mislabeled as creep.
+
+## Detection Algorithm (Analyze Step 1, scope-creep category — final)
+
+Run only when `spec-content` is not `none`. Confirms Scope's preliminary candidates and detects behavior-level creep.
+
+```
+1. Carry Scope's preliminary-scope-creep candidates as the starting set
+2. For each candidate, inspect the hunks (from the Review Kit's diffs):
+   - confirm the changed behaviors are not traceable to any requirement
+   - if genuinely beyond scope -> emit a finding:
+       { severity (per severity-rubric), category: scope-creep,
+         location: file:hunk, message: "change beyond <criterion-set>",
+         scope-creep: true }
+3. Detect behavior-level creep not caught by the file-level pre-check:
+   - a changed file that DOES map to a requirement, but a specific hunk/
+     added behavior within it serves no requirement
+   - emit a finding with scope-creep: true and a precise file:hunk location
+4. Reconcile with Scope's preliminary count:
+   - if the confirmed creep count differs from the preliminary count,
+     that is an Analyze Smart pause trigger (the user confirms the delta)
+5. If spec-content: none -> record the scope-creep category as
+   "skipped (no requirements)" and emit no scope-creep findings
+```
+
+## Severity of Scope-Creep Findings
+
+Scope-creep findings carry a severity per [severity-rubric.md](severity-rubric.md):
+
+- A creep that introduces a **new public API / behavior / dependency** outside the requirements → typically **major** (it expands the merge's surface area).
+- A creep that is a small, incidental edit (e.g. a stray comment region, an unrelated formatting change in a touched file) → **minor** or **nit**.
+- A creep that introduces a security hole or breaks a core flow → escalate via the rubric to **blocker** (rare; the issue is the security break, traced as scope-creep).
+
+Report's approval derivation treats **any** `scope-creep: true` finding as forcing `changes-requested` (see [approval-criteria.md](approval-criteria.md)) — creep always asks for a decision before merge.
+
+## Work-linked Edge Cases
+
+For `input-shape: work-linked`:
+
+- The Work Manifest's resolved task list and each task's single Acceptance Criterion **are** the de facto requirements when Scope maps `requirements-source` to those task criteria. Scope records `requirements-source.type: plan-id | task-criterion` accordingly.
+- A `dependency-warning: expanded-to-upstream` from the Work run is **expected** (the user explicitly expanded scope), **not** creep — Analyze must not flag upstream-task files as creep when the Work record shows the expansion was authorized.
+- A `tentative` (blocked/skipped) task's files are still reviewed, but creep findings on them are flagged with the `tentative` note so the reviewer knows the file may not reflect final intent.
+
+## Validation (Scope Step 4 / Analyze Step 1 re-checks)
+
+- The category ran only when requirements were present (else explicitly skipped with the note).
+- Every scope-creep finding carries `scope-creep: true` (never a `trace`) and a `location`.
+- No scope-creep finding was emitted when `spec-content: none`.
+- The confirmed count reconciles with the preliminary count (any delta is a documented Analyze pause trigger, not a silent discrepancy).
+
+## Notes
+
+- This reference is the single source of truth for the detection algorithm, the trace vs scope-creep-flag logic, and the "requires requirements" rule.
+- Scope applies the preliminary check; Analyze applies the final check; Report derives approval from the creep flag (per [approval-criteria.md](approval-criteria.md)); neither the modules nor the orchestrator re-encode the algorithm.
+- The `preliminary-scope-creep` field on the Review Scope artifact and the `scope-creep-summary` field on the Review Report are both populated from this reference's outputs.