pi-dev-team 0.2.0

package/skills/code-review/examples/aggregated-sample.json

@@ -0,0 +1,56 @@
+{
+  "overall": "warn",
+  "timestamp": "2026-07-05T12:00:00Z",
+  "targetFiles": 8,
+  "preFlightPassed": true,
+  "agents": [
+    {
+      "agentName": "structure-review",
+      "status": "warn",
+      "modelTier": "mid",
+      "issues": [
+        {
+          "severity": "warning",
+          "confidence": "high",
+          "file": "src/api/handler.ts",
+          "line": 15,
+          "message": "God object: handler mixes routing, validation, and persistence",
+          "suggestedFix": "Split routing, validation, and persistence into focused modules"
+        },
+        {
+          "severity": "warning",
+          "confidence": "medium",
+          "file": "src/api/handler.ts",
+          "line": 15,
+          "message": "Nesting depth 5 in the validation branch exceeds threshold of 3",
+          "suggestedFix": "Extract guard clauses into helper predicates"
+        }
+      ],
+      "summary": "2 issues found: 2 warnings"
+    },
+    {
+      "agentName": "test-review",
+      "status": "pass",
+      "modelTier": "mid",
+      "issues": [],
+      "summary": "No issues found"
+    }
+  ],
+  "totals": {"errors": 0, "warnings": 2, "suggestions": 0},
+  "tokenEstimate": {
+    "totalInputFiles": 12000,
+    "agentCount": 2,
+    "contextStrategy": "full-file"
+  },
+  "dispatchFailures": [],
+  "topFindings": [
+    {
+      "severity": "warning",
+      "agents": ["structure-review"],
+      "file": "src/api/handler.ts",
+      "line": 15,
+      "message": "handler mixes too many concerns and exceeds the nesting threshold"
+    }
+  ],
+  "summary": "WARN (1 agent passed, 1 warned, 0 failed). 2 total issues."
+}

package/skills/code-review/examples/sample-report.md

@@ -0,0 +1,41 @@
+# Sample Code Review Report
+
+```text
+# Code Review Summary
+
+| Agent              | Status | Issues |
+|--------------------|--------|--------|
+| test-review        | PASS   | 0      |
+| structure-review   | FAIL   | 3      |
+| naming-review      | PASS   | 0      |
+| domain-review      | PASS   | 0      |
+| security-review    | PASS   | 0      |
+| js-fp-review       | WARN   | 3      |
+
+Overall: FAIL (4 passed, 1 warned, 1 failed)
+Total issues: 6 (1 error, 3 warnings, 2 suggestions)
+```
+
+## Issues by file
+
+### src/api/handler.ts
+
+- **ERROR** [structure-review] Line 15: Function `processRequest` nests 5 levels deep validating input before touching business logic
+  - Fix: Extract validation, transformation, and persistence into separate functions
+
+- **WARNING** [structure-review] Line 15: Function handles validation, business logic, and DB writes
+  - Fix: Apply SRP — separate into validate(), transform(), persist()
+
+- **WARNING** [js-fp-review] Line 42: `results.push(item)` — array mutation
+  - Fix: Use `results = [...results, item]` or build with `.map()`
+
+### src/utils/config.ts
+
+- **WARNING** [js-fp-review] Line 8: `global.appConfig = merged` — global state mutation
+  - Fix: Export a module-level getter instead
+
+- **SUGGESTION** [structure-review] Line 1: File mixes config loading and validation
+  - Fix: Split into config-loader.ts and config-validator.ts
+
+- **SUGGESTION** [js-fp-review] Line 22: `let count` never reassigned
+  - Fix: Use `const count`

package/skills/code-review/output-format.md

@@ -0,0 +1,478 @@
+# Output Format Reference
+
+## Per-agent JSON result
+
+```json
+{
+  "agentName": "structure-review",
+  "status": "pass|warn|fail|skip",
+  "modelTier": "mid",
+  "issues": [
+    {
+      "severity": "error|warning|suggestion",
+      "confidence": "high|medium|none",
+      "file": "src/auth/login.ts",
+      "line": 42,
+      "message": "God object: AuthController handles login, registration, and password reset",
+      "suggestedFix": "Split into LoginController, RegistrationController, and PasswordResetController"
+    }
+  ],
+  "summary": "2 issues found: 1 error, 1 warning"
+}
+```
+
+### `confidence` field values
+
+| Value | Meaning | `apply-fixes` behavior |
+|-------|---------|----------------------|
+| `high` | Mechanical fix; correct with high certainty | Auto-apply |
+| `medium` | Direction right; tradeoffs possible | Present as suggested diff — require confirmation |
+| `none` | Requires human judgment | Present finding only; do not generate correction prompt |
+
+## Aggregated JSON result (`--json` flag)
+
+```json
+{
+  "overall": "pass|warn|fail",
+  "timestamp": "2026-03-01T12:00:00Z",
+  "targetFiles": 42,
+  "preFlightPassed": true,
+  "agents": [
+    {"agentName": "test-review", "status": "pass", "modelTier": "mid", "issues": [], "summary": "..."}
+  ],
+  "totals": {"errors": 0, "warnings": 2, "suggestions": 1},
+  "tokenEstimate": {
+    "totalInputFiles": 15000,
+    "agentCount": 11,
+    "contextStrategy": "diff-only|full-file|mixed"
+  },
+  "topFindings": [
+    {
+      "severity": "error|warning|suggestion",
+      "agents": ["structure-review", "correctness-review"],
+      "file": "src/api/handler.ts",
+      "line": 15,
+      "message": "God object: handler mixes routing, validation, and persistence"
+    }
+  ],
+  "dispatchFailures": [
+    {"agentName": "arch-review", "attempts": 2, "error": "Tool result missing due to internal error", "shape": null, "extraction": null}
+  ],
+  "ledgerSkipped": [
+    {"lens": "doc-review", "file": "src/api/handler.ts", "verdict": {"lens": "doc-review", "file_path": "src/api/handler.ts", "ts": "2026-03-01T11:58:00Z", "file_content_hash": "9f2c...", "outcome": "pass", "plugin_version": "1.42.0"}}
+  ],
+  "summary": "FAIL (N agents passed, N warned, N failed). N total issues. 1 lens never ran (dispatch failure)."
+}
+```
+
+The `tokenEstimate` field provides rough cost observability:
+
+- `totalInputFiles`: approximate character count of all input files passed to agents
+- `agentCount`: number of agents that actually reviewed content this run —
+  excludes `skip` (contract-shaped, but nothing was reviewed) and
+  `dispatchFailures` (never ran)
+- `contextStrategy`: whether diff-only, full-file, or a mix was used
+
+The `topFindings` array is the consolidated cross-agent view — one entry per
+distinct `file:line`, so a finding surfaced by several agents appears once:
+
+- `severity` is the **single highest** enum (`error` > `warning` > `suggestion`)
+  for that finding — never a slash- or comma-joined string.
+- `agents` is an explicit array of the reporting agents. Multi-agent
+  attribution lives here; never join multiple values into `severity` or an
+  `agent` scalar.
+
+`dispatchFailures` (issue #1752, always present, empty array when none):
+agents whose `Agent` tool dispatch failed and then failed a single individual
+retry — the lens never actually ran. Distinct from an `agents[]` entry with
+`status: "skip"` (agent had nothing to review this run — see
+[`knowledge/review-agent-output-contract.md`](../../knowledge/review-agent-output-contract.md#status-values))
+and from `status: "fail"` (agent ran and found error-severity issues). A
+non-empty `dispatchFailures` list is never omitted because the rest of the
+panel returned cleanly.
+
+`ledgerSkipped` (issue #2167, always present, empty array when none): one
+`{"lens", "file", "verdict"}` entry per `(lens, file)` pair
+`scripts/verdict_scope.py` matched to an exact, current-content `pass` row
+in `.claude/metrics/review-verdicts.jsonl` — that lens was never dispatched
+against that file this run because an earlier dispatch already cleared this
+exact content. `verdict` is the matched ledger row verbatim (its own
+snake_case fields — `ts`/`file_content_hash`/`plugin_version`/`outcome`/
+`lens`/`file_path`, exactly as `hooks/lib/review_verdicts.py` writes them —
+never renamed to camelCase), named here so a reader can verify the skip
+against the ledger directly rather than trust it blindly. An
+agent entirely absent from `agents[]` with every one of its candidate files
+listed here is a *fully* ledger-skipped lens (`verdict_scope.py`'s own
+`fullySkippedLenses`) — not a coverage gap, but never silent either: `summary`
+states the count of fully-skipped lenses whenever `ledgerSkipped` is
+non-empty, the same way it already states dispatch-failure counts. Skipped
+files contribute no new findings to `topFindings`/`totals`, so `overall`
+reflects exactly the same aggregate a from-scratch full-panel run over this
+content would reach — a fully ledger-skipped panel is never `fail`/`warn` on
+that basis alone.
+
+`shape`/`extraction` (issue #1998, both `null` when the dispatch never
+returned at all — a transport failure, not a contract failure): when the
+retry DID return but failed `validate_review_output.py`'s contract check,
+these carry that check's classification — `shape` is one of its five failure
+shapes (`empty`/`truncated`/`malformed-json`/`schema-drift`/`not-json`),
+`extraction` is set alongside `shape: "schema-drift"` or `shape:
+"malformed-json"` and names which extraction path (`clean`/`fenced`/
+`prose-preamble`) recovered the object before it failed. `error` always
+carries the human-readable reason either way (the transport error text, or
+`validate_review_output.py`'s parse/schema error, redacted and capped at 256
+characters the same way `raw_prefix` is) — `shape`/`extraction` add the
+machine-readable classification alongside it rather than replacing it.
+
+**A non-empty `dispatchFailures` forces `overall: "fail"`**, unconditionally,
+regardless of what the per-agent results alone would compute — the coverage
+gap is enforced by this DTO itself, not by each caller re-deriving it from
+`dispatchFailures` separately. This matters because `SKILL.md` step 9 (the
+`.pr-review-passed` gate) never runs under `--json` — without this rule, a
+`--json` caller (e.g. `/pr`, which reads only `overall`/`status`) could see
+`overall: "pass"` and proceed despite a lens that never ran, exactly the
+silent-gap failure mode #1752 exists to close.
+
+**A step 6a fix-loop exit via escalation also forces `overall: "fail"`**
+(issue #1880), for the same reason and by the same mechanism as the
+`dispatchFailures` rule above: `SKILL.md` step 6a's own exit-conditions table
+already treats a round-cap exit, an iteration-limit exit, and a
+"same issues persist" exit as fail-equivalent — but only for step 9's
+`.pr-review-passed` gate-write condition, and step 9 never runs under `--json`.
+Without this second rule, an escalated review whose only remaining issues are
+`warning`-severity would compute `overall: "warn"` from the per-agent totals
+alone and a `--json` caller (e.g. `/pr`'s internal `/code-review --since
+<base> --json` call) would see a passing-looking `"warn"` and proceed —
+silently missing the escalation, exactly the gap the `dispatchFailures` rule
+above already closed for dispatch coverage. A **clean** `converged` exit
+(zero actionable issues, or the round ledger reporting `converged`) is
+**not** an escalation and does not trigger this rule. Apply both override
+rules — `dispatchFailures` and fix-loop escalation — after the totals-based
+`overall` computation, so either one always wins regardless of the per-agent
+severity mix.
+
+**`--json` output contract.** When `--json` is set, the object above is the
+run's *only* output: printed to stdout, and no `corrections/*.json` files or
+`.pr-review-passed` gate file are written — regardless of scope (`--path`,
+`--since`, `--all`, auto-scope) or how many issues were found. This holds
+whether `--json` was reached directly or via `/pr`'s call into `/code-review
+--json` (see SKILL.md steps 7–9).
+
+## Per-slice section artifact (sliced mode)
+
+Written by `scripts/ledger.py` → `write_section` to
+`.dev-team-reports/code-review/raw/section-<id>.json` as each slice completes,
+then dropped from orchestrator context (persist-and-drop). `scripts/consolidate.py`
+reads these back for the final report.
+
+```json
+{
+  "schema": "code-review-section/v1",
+  "id": "0001",
+  "files": ["src/auth/login.ts", "src/auth/session.ts"],
+  "is_declarative": false,
+  "panel": ["correctness-review", "structure-review"],
+  "findings": [
+    {"severity": "warning", "confidence": "medium", "agent": "structure-review", "file": "src/auth/login.ts", "line": 42, "message": "..."}
+  ],
+  "dispatchFailures": []
+}
+```
+
+- `id` is the slice id; the filename is `section-<id>.json`.
+- `dispatchFailures` (issue #1762, always present, empty array when none): this
+  slice's own unrecovered dispatch failures — same shape as the legacy path's
+  field (below). `scripts/consolidate.py` concatenates every slice's list into
+  the consolidated aggregate's own `dispatchFailures` field (see below).
+- `panel` lists the agents that **actually ran** for this slice — a reduced-panel
+  (declarative) slice lists only `correctness-review` and `structure-review`, so
+  a reader can tell "fewer findings" from "fewer reviewers ran".
+- `findings` use the per-agent `issues[]` shape above **plus an `agent` field**
+  naming the review dimension that reported each one. Because a slice's whole
+  panel writes into one flat `findings[]` list, that `agent` tag is what lets
+  `consolidate.py` merge reporting agents per `file:line` and roll up recurring
+  themes — omitting it yields empty `agents[]` arrays and no themes.
+
+### Schema-drift tolerance (#1261)
+
+Real review-agent output drifts from this schema — agents return the native
+`{status, issues, summary}` shape, key the list as `issues` (the per-agent key)
+instead of `findings` (the section key), or add extra top-level keys. The
+aggregator absorbs these variants deterministically rather than miscounting:
+
+- `consolidate.py`'s `consolidate()` reads a section's findings from `findings`
+  **or** `issues` (canonical first), so a mis-keyed list is aggregated, never
+  silently counted as zero. A value present but not a list degrades to "no
+  findings" rather than crashing.
+- `consolidate.normalize_agent_result(raw, agent_name=None)` is the extraction
+  contract for folding one agent's raw result into a section's flat `findings[]`:
+  it pulls the list from either key, ignores extra keys (`status`, `summary`),
+  and tags each finding with its reporting `agent` (`raw["agentName"]`, else the
+  passed `agent_name`). Non-dict input degrades to `[]`; it never raises.
+
+This tolerance is a safety net for silent drift, **not** a licence to emit the
+wrong shape — the per-agent contract above (`issues[]`) remains authoritative.
+
+## Progress ledger (sliced mode)
+
+Written by `init_ledger` to `.dev-team-reports/code-review/ledger.json`, updated to
+`done` as each slice's section artifact lands. Inspectable/interruptible — a
+partial ledger is always valid JSON.
+
+```json
+{
+  "schema": "code-review-ledger/v1",
+  "cap": 50,
+  "slices": [
+    {"id": "0001", "files": ["src/auth/login.ts"], "is_declarative": false, "status": "pending"}
+  ]
+}
+```
+
+- `cap` is the per-slice file cap the run partitioned with; `--resume` **refuses**
+  a different cap rather than silently repartitioning (see `sliced-mode.md`).
+- `status` is `pending` until the slice's section artifact exists, then `done`.
+  The artifact on disk — not this status field — is the source of truth for
+  `--resume`.
+
+## Consolidated aggregate (sliced mode)
+
+Produced by `scripts/consolidate.py` → `consolidate(sections)` from all
+`section-*.json` artifacts. It extends the aggregated `--json` object above with
+three sliced-only fields, and reuses the same `topFindings` dedup contract
+(one entry per distinct `file:line`, reporting agents merged into `agents[]`,
+severity = the single highest enum).
+
+```json
+{
+  "sliced": true,
+  "sliceCount": 24,
+  "overall": "warn",
+  "totals": {"errors": 0, "warnings": 5, "suggestions": 3},
+  "topFindings": [
+    {"severity": "warning", "agents": ["structure-review", "correctness-review"], "file": "src/api/handler.ts", "line": 15, "message": "..."}
+  ],
+  "recurringThemes": [
+    {"agent": "structure-review", "slices": ["0003", "0007", "0011"], "occurrences": 9}
+  ],
+  "reducedPanelSlices": ["0002", "0019"],
+  "dispatchFailures": [
+    {"agentName": "arch-review", "attempts": 2, "error": "Tool result missing due to internal error", "shape": null, "extraction": null}
+  ],
+  "summary": "WARN across 24 slices — 0 errors, 5 warnings, 3 suggestions; 1 recurring theme(s)."
+}
+```
+
+- `summary`: a one-line roll-up (status, slice count, totals, theme count).
+- `malformedArtifacts` (optional): present only when a `section-*.json` was
+  unreadable — an array of the offending paths; `main()` also reports each to
+  stderr and exits non-zero, so a bad artifact is never silently dropped.
+- `recurringThemes`: review dimensions (by `agent`) whose findings recur across
+  **two or more slices** — the systemic-pattern rollup (e.g. the same god-class
+  or leak flagged in many modules). `slices` lists the affected slice ids;
+  `occurrences` is the total finding count for that dimension. A dimension
+  appearing in only one slice is **not** a theme.
+- `reducedPanelSlices`: the ids of slices that ran the reduced (declarative)
+  panel — so a reader can tell "fewer findings" from "fewer reviewers ran".
+- `dispatchFailures` (issue #1762, always present, empty array when none):
+  the concatenation of every slice's own `dispatchFailures` entries (per-slice
+  schema above) — agents whose `Agent` tool dispatch failed and then failed a
+  single individual retry, for that slice's panel. Same shape and same
+  `agentName`/`attempts`/`error`/`shape`/`extraction` fields as the legacy
+  aggregate's `dispatchFailures` above; consolidation only concatenates, it
+  does not re-shape. A non-empty list is never omitted because the rest of
+  the run returned cleanly.
+- **A non-empty `dispatchFailures` forces `overall: "fail"`**, unconditionally,
+  after the totals-based `overall` computation above — the same
+  unconditional-override rule as the legacy aggregate, so a lens that never
+  ran on even one slice cannot be masked by a `pass`/`warn` computed from the
+  slices that did return.
+
+## Correction prompt JSON
+
+```json
+{
+  "priority": "high|medium|low",
+  "confidence": "high|medium",
+  "category": "structure-review",
+  "instruction": "Fix: God object handles too many concerns (Suggested: Split into focused controllers)",
+  "context": "Line 42 in src/auth/login.ts",
+  "affectedFiles": ["src/auth/login.ts"]
+}
+```
+
+Severity mapping: error→high, warning→medium, suggestion→low.
+
+Correction prompts are only generated for issues with `confidence: high` or `confidence: medium`. Issues with `confidence: none` are included in the review report but do not produce correction prompts — they require human judgment and must be resolved manually before merging.
+
+## Status rules
+
+- **pass**: Zero issues
+- **warn**: Issues found, none are errors
+- **fail**: At least one error-severity issue
+- **skip**: see the canonical definition in [`knowledge/review-agent-output-contract.md`](../../knowledge/review-agent-output-contract.md#status-values)
+
+`dispatchFailures` entries carry no `status` at all — the agent never ran, so
+none of the four values above apply. See the `dispatchFailures` field
+description above.
+
+## Model tier values
+
+Each agent declares a `Model tier` field that controls which model runs it:
+
+| Tier | Model | Use for |
+| ------ | ------- | --------- |
+| `small` | Haiku | Pattern matching, thresholds, naming checks |
+| `mid` | Sonnet | Structural analysis, test quality, mutation detection |
+| `frontier` | Opus | Security analysis, domain modeling, semantic reasoning |
+
+## Context needs values
+
+Each agent declares a `Context needs` field that controls what input it receives:
+
+| Value | Input | When to use |
+| ------- | ------- | ------------- |
+| `diff-only` | Git diff output only | Pattern-matching agents (naming, FP) |
+| `full-file` | Complete file contents | Agents needing function-level context |
+| `project-structure` | Full files + directory tree | Agents reasoning about architecture |
+
+## Review Findings prompt (interactive — step 6)
+
+When actionable issues exist, present this prompt before any fix action. **This
+prompt is bypassed under `--json` (or `--yes`)**: those runs are contractually
+non-interactive and default to report-only (no code modified) — see SKILL.md
+step 6, exception (a).
+
+```text
+## Review Findings
+
+Found N actionable issues (N errors, N warnings) that can be
+auto-fixed, plus N issues requiring human review.
+
+Actionable issues by agent:
+- structure-review: 3 (2 error, 1 warning)
+- naming-review: 2 (2 warning)
+- js-fp-review: 1 (1 error)
+
+Options:
+1. **Fix** — Auto-fix actionable issues and re-run review
+   (up to 5 iterations until clean)
+2. **Report only** — Save all findings to a report without
+   modifying any code
+```
+
+## Review-Fix Loop iteration log (step 6a-iv)
+
+```text
+## Review-Fix Loop
+
+| Iteration | Actionable Issues | Fixed | Remaining | Agents Re-run |
+|-----------|-------------------|-------|-----------|---------------|
+| 1         | 7                 | 6     | 1         | 3             |
+| 2         | 1                 | 1     | 0         | 1             |
+
+Loop converged in 2 iterations.
+```
+
+If the loop did not converge:
+
+```text
+Loop stopped after 5 iterations. 2 issues remain:
+- [security-review] SQL injection at src/db/query.ts:42 [auto-fix failed — human review required]
+- [domain-review] Abstraction leak at src/api/handler.ts:15 [confidence: none — human review required]
+```
+
+## Code Review Summary report (step 7, prose mode)
+
+```text
+# Code Review Summary
+
+| Agent              | Status | Issues | Fixed | Model Tier |
+|--------------------|--------|--------|-------|------------|
+| test-review        | PASS   | 0      | —     | mid        |
+| structure-review   | PASS   | 2      | 2     | mid        |
+| security-review    | WARN   | 1      | 0     | frontier   |
+| ...                | ...    | ...    | ...   | ...        |
+
+Overall: WARN after 2 fix iterations (N agents passed, N warned, N failed)
+Total issues found: N | Auto-fixed: N | Human review required: N
+
+## Dispatch Failures
+
+| Agent | Attempts | Error |
+|-------|----------|-------|
+| arch-review | 2 | Tool result missing due to internal error |
+
+Gate NOT written: 1 lens never ran and its retry also failed. Re-run
+/code-review to retry the missing lens(es).
+```
+
+The **Dispatch Failures** section is present only when `dispatchFailures` is
+non-empty (issue #1752) — omit it entirely on a clean run, but never omit it
+when there is at least one entry, regardless of how the rest of the panel
+scored.
+
+After the summary, render remaining issues (those not auto-fixed — no
+confidence, auto-fix failed, or suggestion-only) with
+`scripts/render_tiered_findings.py` (#2170) against this round's aggregated
+finding list — the same in-memory list already assembled for the `--json`
+branch and for step 8, no re-dispatch, no I/O beyond that list. By default
+this renders **Tier-1 only**: one line per finding (file, line, agent,
+severity/confidence, first sentence of the message, finding-id), followed by
+a trailing expansion hint. This is the canonical example for this template,
+superseding the old full-message-per-issue listing:
+
+```text
+src/db/query.ts:42 [security-review] error/high — SQL injection via unescaped input. (security-review:src/db/query.ts:42:error)
+src/api/handler.ts:15 [domain-review] warning/none — Abstraction leak in handler. (domain-review:src/api/handler.ts:15:warning)
+Expand a finding with --expand <finding-id>, or --expand all for every finding.
+```
+
+`--expand <finding-id>|all` (a `/code-review` flag — see Parse Arguments and
+step 7 in `skills/code-review/SKILL.md`, issue #2170 Step 3.2) additionally
+renders the matching finding's (or, with `all`, every finding's) **Tier-2**
+block — the full message and suggested fix — appended after the Tier-1
+report above:
+
+```text
+=== security-review:src/db/query.ts:42:error ===
+SQL injection via unescaped input. User-controlled `id` is concatenated
+directly into the query string without parameterization.
+Suggested fix: Use a parameterized query / prepared statement instead of
+string concatenation.
+```
+
+A zero-finding round renders a clean-pass summary line instead
+(`render_tiered_findings.CLEAN_PASS_SUMMARY`), with no per-finding lines and
+no expansion hint — there is nothing to expand. Confidence and
+suggestion-vs-error status are visible directly in each Tier-1 line's
+`severity/confidence` field (e.g. `warning/none`, `suggestion/medium`); the
+old separate `[confidence: none]`/`[suggestion]` bracket tags are retired
+along with the full-message listing they annotated. `[auto-fix failed]` is
+not carried into this rendering — it is a step 6a fix-loop runtime outcome,
+not a property of the finding itself — and remains visible in the step
+6a-iv iteration log above when the loop did not converge. Append the
+iteration table above.
+
+`--json` (step 7's other branch) and `./corrections/*.json` (step 8) are
+unaffected by this rendering path — both already read/write the full
+finding objects independently of `render_tiered_findings.py`, which is
+prose-path only, and neither branch is touched by it. `--expand` is
+therefore a no-op under `--json` (nothing there ever calls this script); see
+`skills/code-review/SKILL.md` step 7 for the exact non-interference
+statement.
+
+## Override audit log entry (step 2, `--force` path)
+
+Append to `.claude/metrics/override-audit.jsonl` (create if missing):
+
+```json
+{
+  "timestamp": "<ISO 8601>",
+  "branch": "<current branch>",
+  "triggeredBy": "--force",
+  "reason": "<value of --reason>",
+  "targetFiles": ["<file list>"],
+  "gatesSkipped": ["lint", "type-check", "secret-scan", "semgrep", "pipeline-red"]
+}
+```

package/skills/code-review/scripts/activation.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+"""Decide whether a /code-review run should engage sliced mode, and at what cap.
+
+Pure policy — no filesystem, no globals. ``should_slice`` encodes the flag /
+scope / threshold precedence the plan's Slice 1 Gherkin specifies;
+``check_slice_ceiling`` is the advisory guard for extreme-scale repos. Kept in
+its own module (not ``partition.py``) so activation *policy* can change without
+touching the partitioning *algorithm*.
+"""
+
+from __future__ import annotations
+
+# Default per-slice file cap when sliced mode auto-engages (operator can
+# override with --slice N).
+DEFAULT_CAP = 50
+
+# A full-repo review with more than this many files auto-engages sliced mode.
+# Mirrors the existing ">500" scope-validation tier in code-review/SKILL.md.
+LARGE_REPO_THRESHOLD = 500
+
+# Above this many slices the run warns and suggests a larger cap. Advisory
+# only — it never refuses (see the plan's Risks section).
+SLICE_COUNT_CEILING = 200
+
+# The one scope kind that auto-engages. --path / --since / auto-scoped
+# uncommitted changes are never auto-sliced.
+FULL_REPO = "full-repo"
+
+
+def _validate_cap(value: object) -> int:
+    """Return ``value`` as a positive int cap, or raise ValueError naming it."""
+    if isinstance(value, bool) or not isinstance(value, int) or value < 1:
+        raise ValueError(
+            f"--slice must be a positive integer number of files per slice, "
+            f"got {value!r}"
+        )
+    return value
+
+
+def should_slice(
+    scope_kind: str,
+    file_count: int,
+    *,
+    threshold: int = LARGE_REPO_THRESHOLD,
+    slice_flag: int | None = None,
+    no_slice_flag: bool = False,
+    default_cap: int = DEFAULT_CAP,
+) -> tuple[bool, int | None]:
+    """Return ``(engage_sliced_mode, effective_cap)``.
+
+    Precedence (highest first):
+
+    1. ``--no-slice`` always wins — never slice (returns ``(False, None)``).
+    2. ``--slice N`` always slices with cap ``N`` at any size; ``N`` is
+       validated as a positive integer (raises ``ValueError`` otherwise).
+    3. Auto-engage only when ``scope_kind`` is full-repo **and**
+       ``file_count`` is strictly greater than ``threshold``. Exactly at the
+       threshold does not engage.
+    4. Otherwise do not slice.
+    """
+    if no_slice_flag:
+        return (False, None)
+
+    if slice_flag is not None:
+        return (True, _validate_cap(slice_flag))
+
+    if scope_kind == FULL_REPO and file_count > threshold:
+        return (True, default_cap)
+
+    return (False, None)
+
+
+def check_slice_ceiling(
+    slice_count: int, ceiling: int = SLICE_COUNT_CEILING
+) -> str | None:
+    """Return an advisory warning when ``slice_count`` exceeds ``ceiling``.
+
+    Advisory only — the caller reports it and proceeds; it never blocks. Returns
+    ``None`` when the count is at or below the ceiling.
+    """
+    if slice_count > ceiling:
+        return (
+            f"Slice count is very high ({slice_count} slices). Consider a larger "
+            f"--slice cap to reduce the number of agent panels and the run's cost."
+        )
+    return None