arreio 1.0.0-dev.1

package/skills/review/references/severity-rubric.md

@@ -0,0 +1,107 @@
+---
+title: Severity Rubric
+description: Authoritative reference for the Analyze phase (severity assignment) and the Report phase (rollup). Defines the four severity levels (blocker / major / minor / nit), their criteria, the borderline-default rule, and how tool corroboration affects severity. Analyze assigns severities from this rubric; Report aggregates them and never re-encodes the levels.
+type: reference
+version: 1.0
+timestamp: "2026-08-08"
+---
+
+# Severity Rubric
+
+Authoritative reference for the **Analyze** phase (Step 2, severity assignment) and the **Report** phase (Step 1, rollup by severity). Defines the four severity levels, their criteria, the borderline-default rule, and how tool corroboration affects severity. Analyze assigns severities from this rubric; Report aggregates the counts and derives approval per [approval-criteria.md](approval-criteria.md); neither re-encodes the levels.
+
+## The Four Severities
+
+| Severity   | Merge impact                                | Default category pairing (guidance, not rule)                          |
+| ---------- | ------------------------------------------- | ---------------------------------------------------------------------- |
+| `blocker`  | Must fix before merge; do not merge         | Security hole, data-loss risk, broken core flow, regression in green-baseline suite |
+| `major`    | Should fix before merge                     | Significant quality/test/integration issue causing maintenance pain    |
+| `minor`    | Nice to fix; non-blocking                   | Small quality or documentation issue                                   |
+| `nit`      | Style/preference; optional                  | Cosmetic, style, minor naming                                           |
+
+## Criteria (authoritative)
+
+### blocker
+
+A `blocker` finding means the change **must not merge as-is**. Assign `blocker` when **any** of:
+
+- A **security** hole was introduced: secret leakage, injection, missing authn/authz on a protected path, unsafe deserialization of untrusted input.
+- A **data-loss risk** exists: a destructive migration without safety, a write path that can corrupt state.
+- A **core flow is broken** by the change: the change breaks a previously-working primary user/code path.
+- A **regression** in the `green`-baseline suite (a test that was green is now red because of this change).
+- The change **silently breaks a documented public contract** (consumers will fail at runtime).
+
+### major
+
+A `major` finding means the change should fix the issue before merge but it is not a hard block. Assign `major` when **any** of:
+
+- A **significant quality** issue: introduced duplication across multiple files, a new overlarge unit, a design that won't scale with the change's intent.
+- A **tests** issue: production-code change with **no** accompanying test (or a test that asserts the wrong thing and would still pass if the behavior regressed).
+- An **integration** issue: a non-silent contract change that will cause maintenance pain for callers (but compiles/works today).
+- A **scope-creep** finding that introduces a **new public API/behavior/dependency** outside the requirements (per [scope-creep-detection.md](scope-creep-detection.md)).
+- A **security** issue that is real but not a hole (e.g. weak validation that is not yet exploitable in the current call path).
+
+### minor
+
+A `minor` finding is a non-blocking improvement. Assign `minor` when **any** of:
+
+- A **small quality** issue: a locally duplicated block, a slightly-too-large function, a missing helper extraction.
+- A **documentation** issue: a public export lacks a docstring, a behavior change isn't in the CHANGELOG, a stale comment.
+- A small **integration** deviation from project conventions (naming/layering) that compiles and works.
+- An incidental **scope-creep** edit (a stray unrelated formatting change in a touched file) per [scope-creep-detection.md](scope-creep-detection.md).
+
+### nit
+
+A `nit` is purely stylistic — optional, never blocks. Assign `nit` when:
+
+- Cosmetic/style preferences: formatting, minor naming taste, comment wording.
+- The reviewer would phrase a thing differently but there is no correctness/quality impact.
+
+## Borderline-Default Rule
+
+> **When a finding's severity is borderline between two levels, default to the LOWER severity.** Do not over-escalate. Report derives the approval status from the tallies; an over-escalated `blocker`/`major` count causes spurious `changes-requested`/`rejected` verdicts.
+
+This is the deliberate counterweight to reviewer tendency to escalate. Examples:
+
+- A `blocker`/`major` borderline → assign `major`.
+- A `major`/`minor` borderline → assign `minor`.
+- A `minor`/`nit` borderline → assign `nit`.
+
+The exception to the downward default is the **security** category: a borderline `blocker`/`major` **security** finding defaults to `blocker` (security findings default upward, because the cost of a missed block is far higher than the cost of a false alarm). Document the reasoning on the finding either way.
+
+## Tool Corroboration
+
+A configured tool (linter/type-checker/test run) can **corroborate** a finding and **sharpen its severity**, never inflate it unjustly:
+
+- A `minor` quality finding that a linter flags as an **error** (not warning) for this repo → sharpen to `major` (the codebase treats it as an error).
+- A `major` tests claim corroborated by an actual **test run failing** (regression confirmed) → sharpen to `blocker` (confirmed regression).
+- A tool flag with **no change-boundary warrant** (a pre-existing repo condition, or a style rule the change didn't worsen) → **no** finding; do not let Review become a repo-wide audit.
+
+Corroboration is recorded on the finding (`corroborated-by: <tool> <rule>`); un-corroborated findings carry no such field. Tools never create findings on their own outside the change boundary.
+
+## Category × Severity Guidance Matrix
+
+This matrix pairs the [review-categories.md](review-categories.md) categories with typical severity bands (guidance, not a hard rule — the criteria above govern):
+
+| Category        | Typical blocker            | Typical major                       | Typical minor / nit             |
+| --------------- | -------------------------- | ----------------------------------- | ------------------------------- |
+| `quality`       | (rare; via core-flow)      | Duplication, overlarge units, design | Local smell, naming             |
+| `security`      | Hole, secret, injection    | Weak validation (not yet exploitable) | (rare)                          |
+| `tests`         | Regression in green suite  | No test for new behavior; wrong assertion | Missing edge case              |
+| `documentation`| Silently alters a documented contract | Change not in CHANGELOG            | Missing docstring, stale comment |
+| `integration`  | Silent contract break      | Caller maintenance pain             | Convention deviation            |
+| `scope-creep`   | Creep causes core-flow break | New public API/behavior/dep outside reqs | Incidental stray edit          |
+
+## Validation (Analyze Step 2 re-checks)
+
+Every emitted finding carries a `severity` from this rubric. A finding:
+
+- **without** a `severity` → reject (Category 2 / Category 6 recovery).
+- whose `severity` is not one of `blocker`/`major`/`minor`/`nit` → reject.
+- that is a borderline case must record the applied default (lower, except security-→-blocker) implicitly — Analyze does **not** emit a textual "defaulted" note per finding, but the borderline-default rule is the conscious policy.
+
+## Notes
+
+- This reference is the single source of truth for severity levels, their criteria, and the borderline-default rule. Analyze assigns; Report aggregates and derives approval per [approval-criteria.md](approval-criteria.md); neither re-encodes the levels.
+- The security-upward-default exception is the **only** place severity defaults upward; all other borderline cases default downward.
+- Tallies feed directly into [approval-criteria.md](approval-criteria.md): `blocker` count → `rejected`; otherwise `major` count > 0 → `changes-requested`; otherwise → `approved`.

package/skills/review/references/templates/artifacts/findings.md

@@ -0,0 +1,161 @@
+---
+title: Findings Artifact
+description: Template for the Findings Artifact produced by the Analyze phase. Carries the per-finding list (severity + category + repo-relative location + message + a requirement trace OR a scope-creep flag + optional non-binding suggested-fix + optional tool corroboration), the per-category and per-severity tallies, and the scope-creep-ran flag; consumed by Report.
+type: template
+version: 1.0
+timestamp: "2026-08-08"
+---
+
+# Findings Artifact
+
+The product of the **Analyze** phase is the Findings set: a per-finding list where each finding carries a **severity** (`blocker` / `major` / `minor` / `nit`), a **category** (`quality` / `security` / `tests` / `documentation` / `integration` / `scope-creep`), a repository-relative **location**, a `message`, and **either** a **requirement `trace`** **or** a **`scope-creep: true`** flag (orchestrator quality gate #5), plus aggregator tallies. Report consumes it.
+
+## Schema
+
+```yaml
+analyze-id: YYYY-MM-DD-NNN-analyze
+prepare-id: YYYY-MM-DD-NNN-prepare
+scope-id: YYYY-MM-DD-NNN-scope
+review-id: YYYY-MM-DD-NNN
+input-shape: change-set | work-linked | ad-hoc
+interactionMode: detailed | smart | autopilot
+status: complete
+timestamp: ISO-8601 timestamp
+
+findings: [] |                         # empty list when the review was clean or nothing-to-review
+  - id: F01
+    severity: blocker | major | minor | nit
+    category: quality | security | tests | documentation | integration | scope-creep
+    location: "src/lib/redis-client.ts:42" | "src/lib/redis-client.ts:hunk-2"   # repository-relative
+    message: "[1-2 sentence description of the issue]"
+    trace: "C1" | "general-quality" | "no-requirements"   # present when in-scope (NOT scope-creep)
+    scope-creep: true | false         # opposite of trace: a finding with scope-creep: true carries NO trace
+    suggested-fix: "[non-binding suggestion; Review is read-only]"   # optional
+    corroborated-by: "eslint rule @typescript-eslint/no-explicit-any" | null   # optional; tool evidence
+    tentative-file: false | true      # echoes the boundary's tentative flag (work-linked blocked/skipped file)
+
+tallies:
+  by-severity:
+    blocker: <N>
+    major: <N>
+    minor: <N>
+    nit: <N>
+  by-category:
+    quality: <N>
+    security: <N>
+    tests: <N>
+    documentation: <N>
+    integration: <N>
+    scope-creep: <N>
+
+scope-creep-ran: true | "skipped (no requirements)"   # false only via the skipped string; never silently absent
+
+work-id: YYYY-MM-DD-NNN | null          # work-linked only; null otherwise
+```
+
+Also save the Findings to `docs/plans/.review/.analyze/<analyze-id>.md`.
+
+## Validation Rules
+
+- **analyze-id:** Required. Format `YYYY-MM-DD-NNN-analyze`.
+- **prepare-id, scope-id, review-id, input-shape:** Required, inherited (cross-phase consistency).
+- **interactionMode:** Required, identical to the upstream artifacts.
+- **findings:** Required (may be empty — a clean review or nothing-to-review). Each finding must carry:
+  - `id` unique within this set (`F01`, `F02`, …)
+  - `severity` one of `blocker`/`major`/`minor`/`nit` (per [severity-rubric.md](../../severity-rubric.md))
+  - `category` one of the six (per [review-categories.md](../../review-categories.md))
+  - `location` repository-relative (`file:line` or `file:hunk`)
+  - `message` (1–2 sentences)
+  - **exactly one of** `trace` **or** `scope-creep: true` (findings coherence, orchestrator gate #5). A `trace: no-requirements` is used for non-creep findings when `spec-content: none`. A `scope-creep: true` finding carries **no** `trace`.
+  - `suggested-fix` and `corroborated-by` optional (suggested-fix is non-binding — Review is read-only)
+  - `tentative-file` echoes the boundary's `tentative` flag for work-linked blocked/skipped files
+- **tallies.by-severity / by-category:** Required. Counts must match the findings list exactly.
+- **scope-creep-ran:** Required. `true` only when the scope-creep category actually ran (i.e., `spec-content` was present); otherwise `skipped (no requirements)`. Never silently `false`-absent.
+- **work-id:** Required for work-linked input; `null` otherwise.
+- **status:** Required. `complete`.
+
+## Example (mixed severities, one scope-creep finding)
+
+```yaml
+analyze-id: 2026-08-08-001-analyze
+prepare-id: 2026-08-08-001-prepare
+scope-id: 2026-08-08-001-scope
+review-id: 2026-08-08-001
+input-shape: change-set
+interactionMode: smart
+status: complete
+timestamp: 2026-08-08T15:00:00Z
+findings:
+  - id: F01
+    severity: major
+    category: tests
+    location: "src/lib/session-store.ts:22"
+    message: "Production-code change to get/save/delete ships no test for the new behavior."
+    trace: C2
+    scope-creep: false
+    suggested-fix: "Add session-store.test.ts covering get/save/delete per C2."
+    corroborated-by: null
+    tentative-file: false
+  - id: F02
+    severity: major
+    category: scope-creep
+    location: "src/lib/cache.ts:hunk-1"
+    message: "Adds a new TTL cache layer beyond C1/C2; no requirement it serves."
+    trace: null
+    scope-creep: true
+    suggested-fix: "Split the cache layer into its own task with its own AC, or roll back here."
+    corroborated-by: null
+    tentative-file: false
+  - id: F03
+    severity: minor
+    category: quality
+    location: "src/lib/redis-client.ts:42"
+    message: "Magic number 3 for retry count; extract to a named constant."
+    trace: C1
+    scope-creep: false
+    suggested-fix: "const MAX_RETRIES = 3;"
+    corroborated-by: null
+    tentative-file: false
+tallies:
+  by-severity: { blocker: 0, major: 2, minor: 1, nit: 0 }
+  by-category: { quality: 1, security: 0, tests: 1, documentation: 0, integration: 0, scope-creep: 1 }
+scope-creep-ran: true
+work-id: null
+```
+
+## Example (ad-hoc, no requirements — scope-creep skipped)
+
+```yaml
+analyze-id: 2026-08-08-002-analyze
+prepare-id: 2026-08-08-002-prepare
+scope-id: 2026-08-08-002-scope
+review-id: 2026-08-08-002
+input-shape: ad-hoc
+interactionMode: autopilot
+status: complete
+timestamp: 2026-08-08T15:30:00Z
+findings:
+  - id: F01
+    severity: nit
+    category: documentation
+    location: "src/auth/session.ts:8"
+    message: "Public export lacks a docstring."
+    trace: no-requirements
+    scope-creep: false
+    suggested-fix: null
+    corroborated-by: null
+    tentative-file: false
+tallies:
+  by-severity: { blocker: 0, major: 0, minor: 0, nit: 1 }
+  by-category: { quality: 0, security: 0, tests: 0, documentation: 1, integration: 0, scope-creep: 0 }
+scope-creep-ran: "skipped (no requirements)"
+work-id: null
+```
+
+## Notes
+
+- **Findings coherence** (orchestrator gate #5): every finding has a `severity`, a `category`, a repo-relative `location`, and **exactly one of** `trace` / `scope-creep: true`. Report refuses a Findings set that violates this (Category 2 recovery — re-run Analyze).
+- `trace: no-requirements` is the correct trace for any non-creep finding when `spec-content: none` (scope-creep cannot be assessed; never set `scope-creep: true` without a spec).
+- `suggested-fix` is **non-binding** — Review is read-only; the user turns it into a follow-up `/plan` + `/work` or a manual edit, never applied inline.
+- `corroborated-by` records tool evidence; tools corroborate, never create findings outside the change boundary (see [severity-rubric.md](../../severity-rubric.md)).
+- `scope-creep-ran` must be `skipped (no requirements)` exactly when `spec-content` was `none`; the tallies `scope-creep: 0` in that case is consistent (no creep findings emitted).

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

@@ -0,0 +1,116 @@
+---
+title: Review Input Artifact
+description: Template for the Review Input Artifact produced by the Orchestrator. Carries the input shape (change-set, work-id/Work review-id, or ad-hoc) and interactionMode, plus an optional requirements ref; consumed by Scope.
+type: template
+version: 1.0
+timestamp: "2026-08-08"
+---
+
+# Review Input Artifact
+
+The Orchestrator produces a Review Input Artifact as the entry point to the Review workflow. It carries the input shape (one of change-set, work-id/Work review-id, or ad-hoc) and the user-selected `interactionMode`, plus an optional requirements ref that sharpens scope-creep detection. Scope consumes it.
+
+## Schema
+
+```yaml
+type: review-input
+timestamp: ISO-8601 timestamp (e.g., 2026-08-08T14:30:00Z)
+source: user | saved-prompt | document | combination
+status: complete
+interactionMode: detailed | smart | autopilot
+
+# Input shape — exactly one of the following:
+change-set: "<git spec>" | null         # change-set: diff range ("<base>..<head>"), commit range ("A..B"), "HEAD", staged, branch-vs-base, or paths/globs
+work-id: YYYY-MM-DD-NNN | null          # work-linked: reviews a /work run's changes
+work-review-id: YYYY-MM-DD-NNN-review | null   # work-linked: scopes to a specific Work review run (resolved to its work-id)
+ad-hoc: "<target description>" | null   # ad-hoc input (a module/symbol/path described in prose)
+
+# Optional requirements ref — sharpens scope-creep detection (Scope runs the category only when present)
+requirements-ref:
+  type: plan-id | task-criterion | spec-doc | null
+  path: "docs/plans/<plan-id>.md | docs/tasks/<plan-id>/T<NN>-<name>.md | <spec-doc path> | null"
+
+# Optional context carried:
+goals: [ ... ]
+constraints: [ ... ]
+references: [ ... ]
+```
+
+## Validation Rules
+
+- **type:** Required. Must be `review-input`.
+- **timestamp:** Required. ISO-8601.
+- **source:** Required. One of `user`, `saved-prompt`, `document`, `combination`.
+- **status:** Required. `complete` (the Orchestrator marks it complete once it has the input and the interaction mode).
+- **interactionMode:** Required. One of `detailed`, `smart`, `autopilot`. (If missing, default to `smart`; see [error-handling.md](../../error-handling.md) Category 5.)
+- **Input shape:** Exactly one of `change-set`, `work-id` (or `work-review-id`), `ad-hoc` must be non-null. If all three are null/empty, the Orchestrator asks: "What would you like to review? Provide a git ref/range, a work-id, or describe a target." (Category 3.)
+- **change-set:** When present, parses to a concrete git invocation (the repo must be a git working tree); an empty diff is accepted (Scope records `change-boundary.empty: true`).
+- **work-id / work-review-id:** When present, resolves to a non-empty `docs/tasks/<work-id>/index.md` (and, for `work-review-id`, to `docs/plans/.work/.review/<review-id>.md`). If not, ask to run `/work <work-id>` first or switch to change-set input.
+- **ad-hoc:** When present, a non-empty target description; Scope maps it to concrete files/paths (asks the user to name a file/module/path if it maps to none).
+- **requirements-ref:** Optional. `type` is one of `plan-id` / `task-criterion` / `spec-doc` / `null` with a matching `path`; when `null`, scope-creep detection is skipped (legitimate, not an error).
+
+## Example (change-set, with a requirements ref)
+
+```yaml
+type: review-input
+timestamp: 2026-08-08T09:00:00Z
+source: user
+status: complete
+interactionMode: smart
+change-set: "main..feature/redis-session"
+work-id: null
+work-review-id: null
+ad-hoc: null
+requirements-ref:
+  type: plan-id
+  path: "docs/plans/2026-07-10-001-redis-session-store.md"
+goals: null
+constraints: null
+references: null
+```
+
+## Example (work-linked, no requirements ref)
+
+```yaml
+type: review-input
+timestamp: 2026-08-08T09:05:00Z
+source: user
+status: complete
+interactionMode: detailed
+change-set: null
+work-id: 2026-07-10-001
+work-review-id: null
+ad-hoc: null
+requirements-ref:
+  type: plan-id
+  path: "docs/tasks/2026-07-10-001/index.md"
+goals: null
+constraints: null
+references: null
+```
+
+## Example (ad-hoc, no requirements ref)
+
+```yaml
+type: review-input
+timestamp: 2026-08-08T09:10:00Z
+source: user
+status: complete
+interactionMode: autopilot
+change-set: null
+work-id: null
+work-review-id: null
+ad-hoc: "review the auth module — src/auth/*"
+requirements-ref:
+  type: null
+  path: null
+goals: null
+constraints: null
+references: null
+```
+
+## Notes
+
+- The Orchestrator's Pre-Flight Check ensures `docs/plans/.review/.{scope,prepare,analyze,report}/` and `docs/plans/.review/index.md` exist (self-healing via `mkdir -p`) before handing the Review Input Artifact to Scope.
+- `interactionMode` flows from this artifact into every downstream artifact (Scope → Prepare → Analyze → Report); the orchestrator quality gate #2 cross-checks it is identical across all.
+- For work-linked input, the Work `review-id` and the Review skill's own `review-id` are **distinct** (see [id-generation.md](../../id-generation.md)); the `work-review-id` here is only an input resolver, never reused as the Review skill's umbrella id.

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

@@ -0,0 +1,135 @@
+---
+title: Review Kit Artifact
+description: Template for the Review Kit Artifact produced by the Prepare phase. Carries the gathered diffs/hunks for the change boundary, the enriched context callers, the resolved spec-content, the derived test context (runner + per-file covering tests + ships-own-tests), and the static-analysis tool inventory; consumed by Analyze.
+type: template
+version: 1.0
+timestamp: "2026-08-08"
+---
+
+# Review Kit Artifact
+
+The product of the **Prepare** phase is a Review Kit: the gathered **diffs/hunks** for the change boundary's `required` files (with the enriched `context` callers/importers), the resolved **spec-content** (when `requirements-source` is not `none`), the derived **test context** (test runner + per-file covering tests + whether the change ships its own tests), and the **tool inventory** (linters / type-checkers / test runner). Analyze consumes it. Prepare gathers materials; it does not run the analysis.
+
+## Schema
+
+```yaml
+prepare-id: YYYY-MM-DD-NNN-prepare
+scope-id: YYYY-MM-DD-NNN-scope
+review-id: YYYY-MM-DD-NNN
+input-shape: change-set | work-linked | ad-hoc
+interactionMode: detailed | smart | autopilot
+status: complete
+timestamp: ISO-8601 timestamp
+
+diffs: none |                    # "none" when change-boundary.empty was true
+  - path: "src/lib/redis-client.ts"
+    status: added | modified | deleted | renamed
+    renamed-from: "<old path>"   # only for renamed
+    tentative: false | true      # carried from the change boundary
+    added-lines: N
+    removed-lines: M
+    hunks:                        # omitted for `current-contents` attribution / deleted files
+      - { start: <line>, body: "<hunk text>" }
+    diff-source: "<base>..<head>" | working-tree | working-tree-fallback | current-contents
+
+context:                           # enriched from Scope's seed — callers/importers
+  - path: "src/api/session.ts"
+    role: "caller of redis-client.connect()"
+
+spec-content: none |               # "none" when requirements-source.type == none
+  - criterion: "C1: <short criterion>"
+    expected-behavior:
+      - "<observable behavior>"
+
+test-context:
+  test-runner: npm | pnpm | pytest | go | cargo | rspec | phpunit | mvn | gradle | unknown
+  package-manager: npm | pnpm | null   # Node.js only; null otherwise
+  per-changed-file:
+    - path: "src/lib/redis-client.ts"
+      covering-tests: [ "src/lib/redis-client.test.ts" ]   # may be empty
+      ships-own-tests: true | false    # true if a test file appears in the required (added/modified) set covering this file
+  change-ships-tests: true | false    # true if ANY test file is in the required set
+
+tool-inventory:
+  linters:
+    - { name: "eslint", command: "npx eslint", configured: true }
+  type-checkers:
+    - { name: "tsc", command: "npx tsc --noEmit", configured: true }
+  test-runner-present: true | false   # whether a runner was detected (echoes test-runner != unknown)
+
+work-id: YYYY-MM-DD-NNN | null    # work-linked only; null otherwise
+```
+
+Also save the Review Kit to `docs/plans/.review/.prepare/<prepare-id>.md`.
+
+## Validation Rules
+
+- **prepare-id:** Required. Format `YYYY-MM-DD-NNN-prepare`.
+- **scope-id, review-id, input-shape:** Required, inherited from Scope (cross-phase consistency).
+- **interactionMode:** Required, identical to the Scope artifact.
+- **diffs:** Required. `none` only when the change boundary was `empty: true`; otherwise one entry per `required` file. Each entry has a repo-relative `path`, a `status`, `added-lines`/`removed-lines` counts, and `hunks` (omitted for `current-contents`/deleted); `diff-source` matches the boundary's attribution.
+- **context:** Required (may be empty). Enriched from Scope's seed; each entry repo-relative with a one-line `role`.
+- **spec-content:** Required. `none` when `requirements-source.type: none`; otherwise the structured criteria list (so Analyze skips the scope-creep category deterministically).
+- **test-context.test-runner:** Required (may be `unknown` if undetected). Informs the tests category; not an authoritative gate.
+- **test-context.per-changed-file:** Required. One entry per changed file with `covering-tests` (may be empty) and `ships-own-tests`. A production-code file with `covering-tests: []` and `ships-own-tests: false` is a Prepare Smart pause trigger (test-gap).
+- **test-context.change-ships-tests:** Required. `true` if any test file is in the `required` set.
+- **tool-inventory:** Required (each list may be empty). Each tool has a `configured` flag. An all-empty inventory is a Prepare Smart pause trigger (warn, do not block).
+- **work-id:** Required for work-linked input; `null` otherwise.
+- **status:** Required. `complete`.
+
+## Example (change-set, with requirements)
+
+```yaml
+prepare-id: 2026-08-08-001-prepare
+scope-id: 2026-08-08-001-scope
+review-id: 2026-08-08-001
+input-shape: change-set
+interactionMode: smart
+status: complete
+timestamp: 2026-08-08T14:35:00Z
+diffs:
+  - path: "src/lib/redis-client.ts"
+    status: added
+    tentative: false
+    added-lines: 64
+    removed-lines: 0
+    hunks:
+      - { start: 1, body: "+export function connect(url: string) { ... }" }
+    diff-source: "main..feature/redis-session"
+  - path: "src/lib/session-store.ts"
+    status: modified
+    tentative: false
+    added-lines: 12
+    removed-lines: 4
+    hunks:
+      - { start: 22, body: " ... get/save/delete ..." }
+    diff-source: "main..feature/redis-session"
+context:
+  - { path: "src/api/session.ts", role: "caller of session-store.get()" }
+spec-content:
+  - criterion: "C1: Redis client connects with retry"
+    expected-behavior:
+      - "connect() reads REDIS_URL"
+      - "connect() retries up to 3 times on connection failure"
+test-context:
+  test-runner: pnpm
+  package-manager: pnpm
+  per-changed-file:
+    - { path: "src/lib/redis-client.ts", covering-tests: ["src/lib/redis-client.test.ts"], ships-own-tests: true }
+    - { path: "src/lib/session-store.ts", covering-tests: [], ships-own-tests: false }
+  change-ships-tests: true
+tool-inventory:
+  linters:
+    - { name: "eslint", command: "npx eslint", configured: true }
+  type-checkers:
+    - { name: "tsc", command: "npx tsc --noEmit", configured: true }
+  test-runner-present: true
+work-id: null
+```
+
+## Notes
+
+- The orchestrator's quality gate #2 cross-checks `interactionMode` is identical across Scope/Prepare/Analyze/Report artifacts.
+- `spec: none` (from `requirements-source.type: none`) propagates deterministically so Analyze skips the scope-creep category — Prepare does not guess requirements.
+- `test-context.covering-tests: []` with `ships-own-tests: false` is the test-gap signal Analyze elevates to a `tests`-category finding (often `major` per [severity-rubric.md](../../severity-rubric.md)).
+- Tools are **corroborative only**; Prepare inventories them but does not run them. Analyze may run a tool to corroborate a finding, never to create one outside the change boundary.