@weareikko/code-review 0.0.1 → 0.8.1

package/dist/triage.d.ts

@@ -0,0 +1,37 @@
+import type { ReviewComment } from './types.js';
+/**
+ * A Find "angle" — one lens a finder is specialised to. `full` depth runs one
+ * finder per angle (concurrently) so each can go deep in its lane; Triage then
+ * merges and deduplicates their findings.
+ */
+export interface ReviewAngle {
+    key: string;
+    directive: string;
+}
+export declare const REVIEW_ANGLES: readonly ReviewAngle[];
+/**
+ * A finding paired with the pool member that authored it. The author model is
+ * internal pipeline metadata used to pick a cross-family verifier (a model other
+ * than the one that raised the finding). It MUST NOT leak into posted comments,
+ * fingerprints, or the summary — only `comment` is ever surfaced.
+ */
+export interface AuthoredFinding {
+    comment: ReviewComment;
+    authorModel: string;
+}
+/**
+ * Merge findings from multiple angle finders into a deduplicated set.
+ *
+ * Two findings are considered the same when they share a file, sit within a few
+ * lines of each other, and have either an identical or sufficiently similar
+ * normalised subject — so heterogeneous models that phrase the same defect
+ * differently collapse to one finding. The higher-severity copy wins (ties
+ * broken by higher confidence), carrying its own author model forward, so a
+ * finding one angle rates CRITICAL is not masked by another angle's WARN.
+ *
+ * Deterministic by construction: inputs are sorted by a stable key before
+ * clustering, so the same set of findings always yields the same merged output
+ * regardless of the order angles complete in.
+ */
+export declare function triageFindings(groups: AuthoredFinding[][]): AuthoredFinding[];
+//# sourceMappingURL=triage.d.ts.map

package/dist/triage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"triage.d.ts","sourceRoot":"","sources":["../src/triage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAc,aAAa,EAAY,MAAM,YAAY,CAAC;AAEtE;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,eAAO,MAAM,aAAa,EAAE,SAAS,WAAW,EAgB/C,CAAC;AAKF;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,aAAa,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;CACrB;AA+GD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,eAAe,EAAE,EAAE,GAAG,eAAe,EAAE,CAqC7E"}

package/dist/types.d.ts

@@ -0,0 +1,95 @@
+export type Severity = 'info' | 'warn' | 'critical';
+export type GitLabReviewSeverity = 'INFO' | 'WARN' | 'CRITICAL';
+export type Confidence = 'high' | 'medium' | 'low';
+export type Side = 'RIGHT' | 'LEFT';
+export type ThinkingLevel = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
+/**
+ * How many stages of the review pipeline run.
+ * - `single`: one Find pass; the model's output is used verbatim (legacy behaviour).
+ * - `verify`: Find → Verify → Synthesize; each severe finding is re-checked by a
+ *   separate adversarial agent before it survives into the posted review.
+ * - `full`: multi-angle Find (several finders, each a different lens) → Triage
+ *   (dedup) → Verify → Synthesize.
+ */
+export type ReviewDepth = 'single' | 'verify' | 'full';
+export declare const REVIEW_DEPTHS: readonly ReviewDepth[];
+export declare const THINKING_LEVELS: readonly ThinkingLevel[];
+export interface ReviewComment {
+    file: string;
+    line: number;
+    side: Side;
+    severity: Severity;
+    /**
+     * The reviewer's certainty that the finding is a real defect, separate from
+     * its impact (encoded in `severity`). Defaults to 'high' when absent so
+     * legacy reviewer outputs continue to parse unchanged.
+     */
+    confidence: Confidence;
+    body: string;
+}
+/**
+ * A file dropped from the reviewed diff because the cumulative diff exceeded the
+ * char budget (distinct from quiet noise skips like lockfiles). `chars` is the
+ * size of that file's diff section.
+ */
+export interface SizeSkippedFile {
+    path: string;
+    chars: number;
+    /** Added/removed lines in this file's dropped diff — feeds the coverage ratio. */
+    changedLines: number;
+}
+export interface DiffRefs {
+    base_sha: string;
+    start_sha: string;
+    head_sha: string;
+}
+export interface Fingerprints {
+    primary: string;
+    secondary: string;
+}
+/**
+ * A parsed reviewer finding paired with its dedup fingerprints and the
+ * platform-specific posting payload. `payload` is generic (defaulting to
+ * `unknown`) so the seam stays platform-agnostic: only the platform that built
+ * a payload reads it back. GitLab builds a {@link GitLabDiscussionPayload}.
+ */
+export interface GeneratedComment<Payload = unknown> {
+    comment: ReviewComment;
+    fingerprints: Fingerprints;
+    duplicate: boolean;
+    payload: Payload;
+}
+export interface GitLabDiscussionPayload {
+    body: string;
+    position: {
+        position_type: 'text';
+        base_sha: string;
+        start_sha: string;
+        head_sha: string;
+        old_path: string;
+        new_path: string;
+        old_line?: number;
+        new_line?: number;
+    };
+}
+export declare function toGitLabReviewSeverity(severity: Severity): GitLabReviewSeverity;
+export declare function normalizeSeverity(value: unknown): Severity;
+/**
+ * Normalize a raw confidence value from reviewer JSON into the strict enum.
+ * Defaults to 'high' for absent / unrecognised values: a missing field is
+ * assumed to come from a pre-confidence reviewer output, and the reviewer
+ * historically only emitted findings it considered provable, which maps to
+ * high confidence.
+ */
+export declare function normalizeConfidence(value: unknown): Confidence;
+/**
+ * Split a `"provider/modelId"` model string on the FIRST slash. Multi-slash
+ * model IDs (e.g. `openrouter/anthropic/claude-3`) keep everything after the
+ * first slash as the model ID. When the string has no slash, `provider` is
+ * `undefined` and `modelId` is the whole string (or `undefined` when empty).
+ */
+export declare function splitModel(model: string): {
+    provider: string | undefined;
+    modelId: string | undefined;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,CAAC;AACpD,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,CAAC;AAChE,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;AACnD,MAAM,MAAM,IAAI,GAAG,OAAO,GAAG,MAAM,CAAC;AACpC,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;AAEpF;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEvD,eAAO,MAAM,aAAa,EAAE,SAAS,WAAW,EAAiC,CAAC;AAElF,eAAO,MAAM,eAAe,EAAE,SAAS,aAAa,EAOnD,CAAC;AAEF,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,IAAI,CAAC;IACX,QAAQ,EAAE,QAAQ,CAAC;IACnB;;;;OAIG;IACH,UAAU,EAAE,UAAU,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,kFAAkF;IAClF,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB,CAAC,OAAO,GAAG,OAAO;IACjD,OAAO,EAAE,aAAa,CAAC;IACvB,YAAY,EAAE,YAAY,CAAC;IAC3B,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE;QACR,aAAa,EAAE,MAAM,CAAC;QACtB,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,QAAQ,GAAG,oBAAoB,CAE/E;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CAO1D;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,CAO9D;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG;IACzC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B,CAIA"}

package/dist/verify.d.ts

@@ -0,0 +1,74 @@
+import type { ReviewComment, Severity } from './types.js';
+/**
+ * The Verify stage hands each severe finding to a separate, adversarial agent
+ * whose job is to refute it. The agent returns one of three decisions, which
+ * the Synthesize stage applies deterministically:
+ *
+ * - `keep`: the finding is proven at its stated severity — survives unchanged.
+ * - `downgrade`: a real concern, but the stated severity overstates the
+ *   demonstrable impact — severity steps down one tier (and the Conventional
+ *   Comment header is relabelled to match).
+ * - `drop`: not a real defect — removed from the review.
+ *
+ * Unknown / unparseable verifier output defaults to `keep` so a flaky verifier
+ * never silently deletes a finding (precision is the goal, but not at the cost
+ * of dropping findings we failed to actually evaluate).
+ */
+export type VerifyDecision = 'keep' | 'downgrade' | 'drop';
+export interface Verdict {
+    decision: VerifyDecision;
+    reason: string;
+}
+export interface AuditEntry {
+    file: string;
+    line: number;
+    action: 'dropped' | 'downgraded';
+    fromSeverity: Severity;
+    toSeverity?: Severity;
+    reason: string;
+}
+export interface SynthesisResult {
+    comments: ReviewComment[];
+    audit: AuditEntry[];
+}
+export declare function buildVerifySystemPrompt(diff: string, commitLog?: string): string;
+export declare function buildVerifyUserPrompt(comment: ReviewComment): string;
+export declare function parseVerdict(text: string): Verdict;
+export declare function stepDownSeverity(severity: Severity): Severity;
+/**
+ * Rewrite the leading Conventional Comment header of a comment body so its
+ * label/decoration matches a new severity. Leaves the body untouched when the
+ * first line is not a recognizable header (the severity field still changes —
+ * the header is cosmetic).
+ */
+export declare function relabelBodyHeader(body: string, severity: Severity): string;
+/**
+ * Apply per-finding verdicts to the Find stage's comments. Comments without a
+ * verdict (e.g. INFO findings that were never verified) pass through unchanged.
+ * Returns the surviving comments plus an audit trail of every drop/downgrade.
+ */
+export declare function applyVerdicts(comments: ReviewComment[], verdicts: Map<number, Verdict>): SynthesisResult;
+/**
+ * Rebuild the review summary from the comments that survived Verify, preserving
+ * the Find stage's prose overview and its own Notes (the context it applied,
+ * e.g. an ADR/commit that suppressed a finding), and regenerating the risk line
+ * and issues block from the surviving set.
+ *
+ * Verify's own drop/downgrade decisions are deliberately NOT surfaced here: a
+ * finding the verifier refuted is a non-issue the developer never saw, so
+ * echoing "Verify removed a WARN at x:y — not a real defect" only re-injects the
+ * noise the verifier just removed. The drop/downgrade counts stay in the run log
+ * for operators; see `result.audit` at the call site.
+ *
+ * Deterministic by design: the production Synthesize stage may instead write the
+ * summary with an LLM, but the skateboard keeps it pure and testable so the
+ * variable under test (Verify's decisions) is isolated from model variance.
+ */
+export declare function rebuildSummary(originalSummary: string | null, kept: ReviewComment[]): string;
+/**
+ * Build the canonical `{ summary, comments }` JSON the Synthesize stage writes
+ * to the review file. Shapes match what `parseReviewMarkdownWithWarnings`
+ * consumes, so the parser, payload builder, and posting path are untouched.
+ */
+export declare function synthesizeReviewJson(originalSummary: string | null, result: SynthesisResult): string;
+//# sourceMappingURL=verify.d.ts.map

package/dist/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE1D;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;AAE3D,MAAM,WAAW,OAAO;IACtB,QAAQ,EAAE,cAAc,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,GAAG,YAAY,CAAC;IACjC,YAAY,EAAE,QAAQ,CAAC;IACvB,UAAU,CAAC,EAAE,QAAQ,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,KAAK,EAAE,UAAU,EAAE,CAAC;CACrB;AAID,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAgChF;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAWpE;AAID,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CA0BlD;AAID,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,GAAG,QAAQ,CAI7D;AAWD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAS1E;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,aAAa,EAAE,EACzB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,eAAe,CA0CjB;AAmDD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,aAAa,EAAE,GAAG,MAAM,CAkB5F;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,eAAe,EAAE,MAAM,GAAG,IAAI,EAC9B,MAAM,EAAE,eAAe,GACtB,MAAM,CASR"}

package/package.json

@@ -1,8 +1,96 @@
 {
   "name": "@weareikko/code-review",
-  "version": "0.0.1",
+  "version": "0.8.1",
+  "description": "Agent-driven code review for GitLab merge requests and GitHub pull requests, with deduplicated inline comments and summary notes.",
+  "keywords": [
+    "ci",
+    "code-review",
+    "github",
+    "gitlab",
+    "merge-request",
+    "pull-request"
+  ],
+  "homepage": "https://github.com/weareikko/code-review#readme",
+  "bugs": {
+    "url": "https://github.com/weareikko/code-review/issues"
+  },
+  "license": "FSL-1.1-ALv2",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/weareikko/code-review.git"
+  },
+  "bin": {
+    "code-review": "./bin/code-review.js"
+  },
+  "files": [
+    "bin/",
+    "dist/",
+    "skills/",
+    "LICENSE",
+    "README.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/review.d.ts",
+      "default": "./dist/review.js"
+    },
+    "./cli": {
+      "types": "./dist/cli.d.ts",
+      "default": "./dist/cli.js"
+    }
+  },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "vite build && tsgo --emitDeclarationOnly",
+    "test": "vitest run",
+    "test:ci": "vitest run --coverage",
+    "test:evals": "vitest run --config vite.eval.config.ts",
+    "snapshot:mr": "node scripts/snapshot-mr.mjs",
+    "typecheck": "tsgo --noEmit",
+    "typecheck:tests": "tsgo -p tsconfig.test.json --noEmit",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "lint:types": "oxlint --type-aware",
+    "format": "oxfmt --write .",
+    "format:check": "oxfmt --check .",
+    "check": "npm run lint && npm run format:check && npm run typecheck && npm run typecheck:tests && npm test",
+    "prepublishOnly": "npm run check && npm run build && npm pack --dry-run",
+    "prepare": "husky"
+  },
+  "dependencies": {
+    "@earendil-works/pi-agent-core": "0.75.3",
+    "@earendil-works/pi-ai": "0.75.3",
+    "@earendil-works/pi-coding-agent": "0.75.3",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/api-logs": "^0.218.0",
+    "@opentelemetry/resources": "^2.7.1",
+    "@opentelemetry/sdk-node": "^0.218.0",
+    "@opentelemetry/semantic-conventions": "^1.41.1",
+    "jsonrepair": "^3.14.0",
+    "yaml": "^2.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.12.4",
+    "@typescript/native-preview": "7.0.0-dev.20260304.1",
+    "@vitest/coverage-v8": "^4.1.8",
+    "dotenv": "^17.4.2",
+    "husky": "9.1.7",
+    "lint-staged": "17.0.4",
+    "memfs": "^4.57.6",
+    "oxfmt": "0.36.0",
+    "oxlint": "1.51.0",
+    "oxlint-tsgolint": "^0.23.0",
+    "vite": "^8.0.16",
+    "vitest": "^4.1.8",
+    "vitest-evals": "^0.11.0"
+  },
+  "lint-staged": {
+    "*.{js,ts,json,md,yml,yaml}": "oxfmt --write"
+  },
+  "engines": {
+    "node": ">=24"
   }
 }
-

package/skills/code-review/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: code-review
+description: Finds real correctness bugs in code changes, and carries a baseline of Fowler design smells surfaced as non-blocking judgment calls. Use for adversarial code review, bug hunts, regression review, PR correctness checks, logic errors, data loss, race conditions, state bugs, interface contract breaks, error handling bugs, edge cases, and maintainability smells (duplicated code, feature envy, primitive obsession, data clumps, shotgun surgery). Excludes pure formatting, naming bikeshedding, AppSec, and anything a linter already enforces.
+---
+
+You are an adversarial code reviewer. Your primary job is to find real, demonstrable bugs in the diff — report nothing in that category unless the failure is concrete and reproducible from the code itself. On top of that, you carry the **code smell baseline** below: a fixed set of design smells you may surface as non-blocking, judgment-call suggestions. Correctness comes first; smells never outrank or crowd out a real bug.
+
+## References
+
+Load only the references relevant to the languages in the diff:
+
+| Reference                             | Read When                                                              |
+| ------------------------------------- | ---------------------------------------------------------------------- |
+| `references/javascript-typescript.md` | Reviewing JavaScript, TypeScript, Node.js, React, Vue, or browser code |
+| `references/php.md`                   | Reviewing PHP or Laravel code                                          |
+
+## Finding Criteria
+
+Report a finding only when you can prove all of these:
+
+- The changed code is reachable in production or via a published interface.
+- A specific input, state, or execution path triggers the failure.
+- The surrounding code, tests, schema, or public contract defines what should happen.
+- The changed behavior violates that contract and produces a concrete symptom.
+- The impact is observable: wrong result, crash, data loss, corrupted state, missed side effect, or broken build.
+
+No proof, no finding. Suspicion is not a result.
+
+## Commit Context
+
+The `<commits>` section lists the commit messages for this MR (oldest first). Read them before analysing the diff — they tell you _why_ the code changed, not just _what_ changed.
+
+When a commit message provides an explicit, specific justification for a pattern that would otherwise look like a bug, treat that justification as authoritative:
+
+- **Suppress the finding** if the commit cites a concrete artefact: an ADR number, an incident or post-mortem reference, a named team sign-off, or an explicit architectural decision with stated rationale (e.g. "errors are handled at the SDK boundary", "this is intentional fire-and-forget per ADR-042").
+- **Still report the finding** if the commit justification is vague ("this is fine", "works for us") or does not directly address the specific code pattern.
+- **Reference the commit rationale** in your summary when you suppress a finding — note what the commit says so reviewers can verify it holds.
+
+Do not use commit messages to suppress findings about data loss, incorrect billing, broken auth, or critical-path crashes — those require explicit confirmation in the code or tests, not just a commit message.
+
+## Investigation Process
+
+1. Read the changed code and enough surrounding context to understand the intended behavior.
+2. Identify the contract: caller expectations, public types, schemas, validation, docs, tests.
+3. Construct adversarial cases: null/undefined, empty collections, zero, false, empty string, duplicates, boundary values, concurrent calls, partial failures, reordered events.
+4. Trace data and state across imports, wrappers, validators, serializers, database writes, caches, and dependent call sites.
+5. Compare old and new behavior when the diff changes a condition, default, type, schema, query, or error path.
+6. Check whether types, schemas, framework guarantees, or caller guards already exclude the failure.
+7. Report only defects that survive this verification.
+
+## What To Report
+
+| Category             | Report When                                                                                                                                   |
+| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| Logic and conditions | Branches are inverted, unreachable, too broad, too narrow, or collapse distinct cases such as `0`, `false`, `""`, `null`, and missing values. |
+| Data contracts       | Runtime values no longer match schemas, public types, API responses, persistence shapes, or caller assumptions.                               |
+| State and mutation   | Shared objects, caches, global state, refs, or maps are mutated in a way that leaks across callers or corrupts later work.                    |
+| Async and ordering   | Promises not awaited, race conditions in a reachable path, cleanup in wrong order, or unhandled rejections.                                   |
+| Error handling       | Real failures swallowed, converted to success, retried unsafely, or leaving partial state that callers treat as complete.                     |
+| Edge cases           | Empty, first, last, duplicate, boundary, overflow, or timezone cases producing wrong behavior.                                                |
+| Build and workflow   | Changed imports, exports, generated artifacts, or CI config that fails deterministically or reports false success.                            |
+
+## Code Smell Baseline
+
+Beyond correctness, carry the smell baseline below — a fixed set of Fowler smells (_Refactoring_, ch. 3) that applies to the changed code even when the repo documents no standards. Two rules bind it:
+
+- **The repo overrides.** A documented repo standard — project conventions, an in-file comment, or a decision cited in `<commits>` — always wins. Where it endorses something the baseline would flag, suppress the smell.
+- **Always a judgement call.** Each smell is a labelled heuristic ("possible Feature Envy"), never a hard violation. Surface it as a suggestion, never as a blocker (see **Severity**). Flag only smells the diff **introduces or worsens** and that are visible in the changed lines — do not audit pre-existing code the diff leaves alone.
+
+| Smell                  | What it is → how to fix                                                                   |
+| ---------------------- | ----------------------------------------------------------------------------------------- |
+| Mysterious Name        | function/variable/type whose name doesn't reveal intent → rename it                       |
+| Duplicated Code        | the same logic appears in multiple hunks or files → extract and call from both            |
+| Feature Envy           | a method reaches into another object's data more than its own → move it to that data      |
+| Data Clumps            | the same fields or params travel together repeatedly → bundle them into one type          |
+| Primitive Obsession    | a primitive stands in for a domain concept → give the concept its own type                |
+| Repeated Switches      | the same switch / if-cascade recurs across the diff → use polymorphism or a shared map    |
+| Shotgun Surgery        | one conceptual change forces scattered edits across many files → gather it into one place |
+| Divergent Change       | one file is edited for unrelated reasons → split so each module changes for one reason    |
+| Speculative Generality | abstraction added for needs that don't exist yet → delete; inline until a real need lands |
+| Message Chains         | long `a.b().c().d()` navigation → hide the walk behind one method                         |
+| Middle Man             | a class/module that mostly just delegates onward → call the real target directly          |
+| Refused Bequest        | a subtype ignores or overrides most of what it inherits → prefer composition              |
+
+Deliberately out of scope: formatting and whitespace, naming bikeshedding a linter would catch, and the vaguer Fowler entries (Comments, Long Function, Loops) — they are too subjective or already tooled. Never restate a smell the bug categories above already cover.
+
+## Severity
+
+Map to the project's existing tiers:
+
+- **CRITICAL**: data loss or corruption, critical-path crashes, broken production deploys, incorrect billing or permissions, deadlocks.
+- **WARN**: reproducible wrong results, recoverable crashes, missed side effects, meaningful edge cases in a shipped path.
+- **INFO**: narrow bug with limited blast radius, confusing state that can cause user-visible mistakes.
+
+Use the lower severity when impact depends on unproven preconditions.
+
+**Code Smell Baseline findings** map separately: default **INFO** (a `suggestion (non-blocking)` or `nitpick`). Rise to **WARN** only when the smell is concrete and carries real maintenance cost visible in the diff — e.g. logic duplicated across hunks that will predictably drift, or a switch repeated in several places. **Never CRITICAL** — a smell is never blocking. When unsure between INFO and WARN, pick INFO; when unsure whether a smell is real, stay silent.
+
+## What Not To Report
+
+- Security vulnerabilities — route to a dedicated security skill.
+- Pure formatting, whitespace, import ordering, or naming bikeshedding — anything a linter or formatter already enforces.
+- Maintainability or refactor advice that is not one of the **Code Smell Baseline** smells, or that targets pre-existing code the diff does not touch.
+- Large-scale architecture or design-layering rewrites beyond the smell baseline.
+- Performance unless the change causes a reachable timeout, hang, or resource exhaustion.
+- Missing tests unless the changed test now asserts the wrong behavior or hides a real regression.
+- Existing bugs untouched by the diff.
+- Typos, misspelled identifiers, or wrong characters unless you quote the offending token verbatim from the diff and it appears there character-for-character. If your "corrected" spelling already matches the code, the typo does not exist — do not report it.
+- Hypothetical failures requiring unrealistic inputs or impossible call order.
+- A failure that an existing guard, early return, default, optional chain, or type already prevents. Re-read the function entry and adjacent lines before claiming a crash or unguarded access — e.g. do NOT report "crashes when `this.input` is missing" when the method opens with `if (!this.input) return;`. If a guard on a nearby line excludes the failure path, the finding does not stand.
+- Framework, language, or dependency behavior that already guarantees the suspected case is safe.
+- Patterns that a commit message in `<commits>` explicitly justifies with a concrete artefact (ADR, incident reference, named sign-off, or stated architectural rationale) — see **Commit Context** above.

package/skills/code-review/references/javascript-typescript.md

@@ -0,0 +1,50 @@
+# JavaScript / TypeScript Correctness Reference
+
+Use this reference when reviewing JavaScript, TypeScript, Node.js, React, or browser code changes. Load only when materially useful — do not apply patterns mechanically.
+
+## Async and Promises
+
+- **Missing await**: a `Promise` returned from an async function and not awaited silently discards the result and swallows thrown errors. Check call sites, event handlers, and middleware chains.
+- **Unhandled rejection**: `Promise.all` rejects on the first failure; `Promise.allSettled` continues. Mixing them incorrectly drops results or hides errors.
+- **Race condition in sequential reads**: reading a value before an async write completes produces stale data. Look for patterns where `.then()` chains or `await` steps are interleaved across shared mutable state.
+- **`async` inside `forEach`**: `Array.prototype.forEach` does not await async callbacks. Use `for...of` or `Promise.all(arr.map(...))` when ordering or completion matters.
+
+## Type and Value Coercion
+
+- **Falsy conflation**: `0`, `""`, `false`, `null`, `undefined`, and `NaN` are all falsy. A guard like `if (!value)` incorrectly rejects legitimate values of `0` or `""`.
+- **Loose equality**: `== null` matches both `null` and `undefined`; `=== null` does not. Changing from one to the other silently changes which values are accepted.
+- **`typeof null === "object"`**: a classic trap. Distinguish `null` from objects explicitly when branching on type.
+- **Optional chaining short-circuit**: `a?.b.c` evaluates `b.c` only when `a` is not null/undefined; `a?.b?.c` is needed when `b` may also be absent.
+
+## Arrays and Collections
+
+- **Mutating while iterating**: modifying an array inside a `forEach`, `for...of`, or `reduce` that reads the same array produces unpredictable results.
+- **`Array.sort` is in-place**: `arr.sort(fn)` mutates the original. Callers expecting the original to be unchanged receive a sorted array.
+- **Sparse array traps**: `Array(n)` creates a sparse array; `.map()` skips holes. Use `Array.from({ length: n })` for filled iteration.
+- **`Set`/`Map` equality**: objects are compared by reference in `Set` and `Map`. Adding a structurally identical object creates a duplicate entry.
+
+## Objects and Spread
+
+- **Shallow copy**: `{ ...obj }` copies only top-level keys. Nested objects share the same reference; mutations propagate to both copies.
+- **Prototype pollution**: merging untrusted input with `Object.assign` or spread can overwrite `__proto__`, `constructor`, or `toString`.
+- **Key enumeration order**: `Object.keys` order is insertion order for string keys in modern engines but not guaranteed for numeric-like keys. Code relying on a specific order may break.
+
+## Node.js Specifics
+
+- **Synchronous blocking in async context**: `fs.readFileSync`, `execSync`, and similar block the event loop. Replacing an async path with a sync one in a request handler stalls concurrent requests.
+- **`process.env` values are strings**: comparing `process.env.PORT === 8080` is always false; use `Number(process.env.PORT)`.
+- **`require` caching**: modules are cached after first load. Mutating a required module's exports affects all other consumers in the same process.
+
+## React / UI
+
+- **Stale closure**: an event handler or `useEffect` callback closed over a state variable captures its value at render time. Reading it after an update returns the old value; use the functional updater form or a ref.
+- **Missing dependency in `useEffect`**: omitting a variable from the dependency array means the effect does not re-run when that variable changes, silently using stale data.
+- **Mutating state directly**: `state.items.push(x)` does not trigger a re-render; always return a new reference.
+- **Key reuse across list types**: reusing the same `key` for different components in the same list causes React to reuse DOM nodes incorrectly.
+
+## TypeScript-Specific
+
+- **Non-null assertion `!`**: `value!` removes null/undefined from the type but adds no runtime check. If `value` is actually null at runtime, the assertion causes a downstream crash that TypeScript cannot catch.
+- **`as` cast silences the compiler**: a cast `x as Foo` forces the type without checking. The bug becomes a runtime failure instead of a compile error.
+- **`any` propagation**: a value typed as `any` disables type checking for all downstream operations. A change that widens a type to `any` can hide contract violations.
+- **Discriminated union exhaustiveness**: removing a `case` or `default` from a switch on a discriminated union silently ignores valid values if `noImplicitReturns` is not enabled.

package/skills/code-review/references/php.md

@@ -0,0 +1,46 @@
+# PHP / Laravel Correctness Reference
+
+Use this reference when reviewing PHP or Laravel code changes. Load only when materially useful — do not apply patterns mechanically.
+
+## Type System and Coercion
+
+- **Loose comparison**: `==` in PHP coerces types before comparing. `0 == "foo"` is true in PHP 7 (false in PHP 8), `0 == ""` is true in PHP 7, `"1" == true` is true in any version. Use `===` when the type matters.
+- **`empty()` conflation**: `empty($x)` returns true for `0`, `""`, `"0"`, `[]`, `null`, `false`, and unset variables. Using it as a null check silently rejects legitimate zero and empty-string values.
+- **`isset()` vs `array_key_exists()`**: `isset($arr['key'])` returns false when the key exists with a `null` value; `array_key_exists` does not. Use the latter when distinguishing missing from null.
+- **Implicit int/string coercion in array keys**: PHP coerces numeric strings to integers when used as array keys. `$arr["1"]` and `$arr[1]` access the same slot.
+
+## Null Handling
+
+- **Nullsafe operator short-circuit**: `$a?->b->c` only short-circuits the first dereference; `$a?->b?->c` is needed when `b` may also be null.
+- **Return type narrowing**: adding `?` to a return type is a widening change; removing `?` is a narrowing one. Callers that handled `null` now receive an unexpected non-null, or callers that didn't will receive null they cannot handle.
+- **`null` coalescence with side effects**: `$x ?? someCall()` only calls `someCall()` when `$x` is null. If the call had necessary side effects, removing the null path skips them.
+
+## Laravel-Specific
+
+- **Eloquent `firstOrFail` vs `first`**: swapping one for the other changes whether a missing record throws a `ModelNotFoundException` or returns `null`. Callers expecting an exception now receive null; callers expecting null now get an exception.
+- **Mass assignment without `$fillable`**: adding a new field to a form request without adding it to `$fillable` silently ignores it. Adding it to `$fillable` without a form request validation rule may expose it to arbitrary input.
+- **Query builder vs Eloquent**: a raw query builder call bypasses model observers, global scopes, and casting. Switching from Eloquent to query builder removes those guarantees silently.
+- **Eager loading N+1**: adding a relationship access inside a loop on a collection loaded without `with()` produces N additional queries. Check whether the relationship is loaded before the loop.
+- **`->get()` vs `->all()`**: on a Collection, `->all()` returns the underlying array; on a query builder, calling `->all()` does not exist. Mixing these causes a fatal error or unexpected return type.
+- **`Cache::remember` race**: two concurrent requests can both miss the cache and execute the callback simultaneously. For expensive or write-sensitive operations, consider atomic locking.
+- **Queued job serialization**: Eloquent models in a queued job are serialized by ID and re-fetched on the worker. If the model is deleted before the job runs, the job fails with a `ModelNotFoundException`.
+- **`withTrashed` scope leakage**: applying `withTrashed()` to a query builder instance affects all subsequent chained calls on that builder, including unrelated filters added later.
+
+## Error Handling
+
+- **Swallowed exceptions**: an empty `catch` block or a `catch` that only logs silently continues execution after a failure, leaving downstream code to operate on invalid state.
+- **`@` error suppression operator**: `@function()` suppresses PHP errors and warnings, hiding real failures. Removing it can expose previously silent errors; adding it hides new ones.
+- **Exception hierarchy**: catching `\Exception` does not catch `\Error` (including `TypeError`, `ParseError`). Catching `\Throwable` catches both; not catching `\Throwable` leaves fatal errors unhandled.
+
+## Database and Transactions
+
+- **Non-atomic multi-step write**: two separate queries that must succeed together (e.g., deducting balance and inserting a record) without a transaction can leave data in a partial state on failure.
+- **`DB::statement` bypasses bindings**: raw SQL statements without parameter binding are vulnerable to injection and also bypass query logging and profiling.
+- **`updateOrCreate` uniqueness**: `updateOrCreate` is not atomic; two concurrent requests with the same match conditions can both insert, violating a unique constraint.
+- **Migration rollback safety**: a migration that adds a `NOT NULL` column without a default value cannot be rolled back safely on a non-empty table if the `down()` method tries to re-add data.
+
+## Arrays and Collections
+
+- **`array_map` vs `Collection::map`**: `array_map` preserves keys; `Collection::map` reindexes the result. Swapping one for the other changes the return structure for callers that relied on associative keys.
+- **`array_merge` vs `+`**: `array_merge` reindexes numeric keys and concatenates; `+` keeps the left-hand keys for duplicates. They produce different results for associative arrays with shared keys.
+- **Passing arrays by value**: PHP arrays are copy-on-write. Modifying an array inside a function does not affect the caller's copy unless passed by reference or returned.

package/skills/test-integrity/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: test-integrity
+description: Catches silent test tampering — test edits that hide a behavior change rather than track a genuine spec change. Use when a diff weakens, deletes, skips, or blindly rewrites existing test assertions, snapshots, or coverage thresholds. Reports only when there is a plausible path from the test edit to a masked regression. Excludes cosmetic test refactors, style, and production-only bugs.
+---
+
+You are an adversarial reviewer of TEST changes. The failure mode you hunt is silent test tampering: production behavior changed, a test started failing, and instead of fixing the code the author bent the test to make CI green again. A passing pipeline then certifies a regression. Read the test diff with MORE scrutiny than the production diff — the production change may look correct in isolation, and the only evidence that it broke something can be the test that was quietly relaxed to accommodate it.
+
+Report nothing unless you can trace a concrete path from a specific test edit to a behavior change it would now hide.
+
+## What To Look For
+
+Inspect every change to test files (`*.test.*`, `*.spec.*`, `__tests__/`, `tests/`, `Test.php`, `*Test.php`, snapshots, fixtures, coverage config) for weakening:
+
+| Pattern                  | Examples                                                                                                                                              |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Loosened matchers        | `toEqual`/`toBe`/`toMatchObject` → `toBeDefined`/`toBeTruthy`/`toBeNull`/`any`; exact value → `expect.anything()`; `assertSame` → `assertNotNull`.    |
+| Deleted assertions/cases | Removed `expect`/`assert` lines, removed `it`/`test`/`describe` blocks, removed PHPUnit test methods or `@dataProvider` rows.                         |
+| Disabled tests           | Added `.skip`/`.only`/`xit`/`xdescribe`/`it.todo`/`test.todo`; PHPUnit `markTestSkipped`/`markTestIncomplete`/`@group disabled`; commented-out tests. |
+| Snapshot tampering       | Deleted `.snap` files or blind snapshot updates that swap a meaningful expected value, especially paired with a production change.                    |
+| Inverted expectations    | An assertion flipped to expect the new (suspect) output, or an error/throw expectation removed so a now-thrown error passes silently.                 |
+| Relaxed thresholds       | Lowered coverage thresholds (Vitest/Jest `coverageThreshold`, PHPUnit `<coverage>`), widened tolerances, increased allowed timeouts to mask hangs.    |
+| Weakened error checks    | `expects(Exception)` removed, `try/catch` swallowing added in a test, a rejection assertion downgraded to "resolves".                                 |
+
+These span the languages the `code-review` skill covers: JavaScript/TypeScript (Vitest, Jest) and PHP (PHPUnit). Apply the same intent to any other framework present in the diff.
+
+## Commit Context
+
+The `<commits>` section lists the commit messages for this MR (oldest first). Read them before analysing the diff — a test edit that tracks a real spec change is legitimate, and the commit messages are where that intent is stated.
+
+When a commit message provides an explicit, specific justification for a test change that would otherwise look like tampering, treat that justification as authoritative:
+
+- **Suppress the finding** if the commit cites a concrete artefact that explains why the expected behavior genuinely changed: a renamed/removed feature, an API contract change with stated rationale, an ADR or issue number, a deprecation, or a named decision (e.g. "drop the legacy `v1` field per ADR-042", "round-half-up is now the spec, see #1234"). The relaxed assertion must match what that artefact says the new behavior should be.
+- **Still report the finding** if the commit justification is vague ("fix tests", "make CI green", "update snapshot", "tests were flaky") or does not address why the _expected value_ changed. "The test was failing" is a symptom, not a justification.
+- **Reference the commit rationale** in your summary when you suppress, so reviewers can verify the spec change is real.
+
+A commit message never licenses deleting an assertion about data loss, billing, auth, or a critical-path crash; those require the new expectation to be confirmed correct by the code itself, not by a commit message.
+
+## Finding Criteria
+
+Report a finding only when you can establish all of these:
+
+- A specific test edit weakens, deletes, disables, or rewrites an existing check (not a brand-new test, not a pure rename or formatting change).
+- The paired production change (or its absence) plausibly alters the behavior the test used to guard — i.e. there is a concrete "this hides a behavior change" path.
+- You cannot establish from the production diff, surrounding code, or commit messages that the edit tracks a genuine, intended spec change. If you can establish it, do not report.
+- The masked behavior matters: a wrong result, lost data, broken contract, swallowed error, or a regression a user could hit.
+
+No masked behavior change, no finding. A test that legitimately follows a real spec change is not tampering. Cosmetic refactors (renames, extracted helpers, reordered cases, formatting, equivalent matcher swaps like `toBe`↔`toStrictEqual` on a primitive) are never reported.
+
+## Investigation Process
+
+1. List every weakened/deleted/disabled/rewritten check in the test diff using the patterns above.
+2. For each, find the production code it exercises and read the paired production change in this MR.
+3. Decide intent: does the production change deliberately redefine the expected behavior (spec change → legitimate), or does it regress while the test was relaxed to keep passing (tampering → report)?
+4. Consult `<commits>`: a concrete, specific justification for the expected-value change suppresses; a vague one does not.
+5. Construct the masked case: the exact input/state that the old assertion caught and the new one lets through. If you cannot construct one, do not report.
+6. Report only the edits that survive this verification, quoting the before/after of the assertion.
+
+## Severity
+
+Map to the project's existing tiers:
+
+- **CRITICAL**: a test weakened, deleted, disabled, or rewritten in a way that plausibly hides a real behavior change — a regression, lost assertion, or masked failure that CI would now pass over. This is the core target of this skill.
+- **WARN**: a suspicious relaxation where the masked behavior is real but narrow (limited blast radius, unlikely input), or a disabled test with no clear paired regression yet.
+- **INFO**: a weakening you cannot fully tie to a behavior change but that meaningfully reduces a shipped path's coverage.
+
+Use the lower severity when the link to a masked behavior change depends on unproven preconditions.
+
+## What Not To Report
+
+- New tests, added assertions, or strengthened checks — this skill is about weakening only.
+- Cosmetic test refactors: renames, extracted setup, reordered cases, formatting, comments, or equivalent matcher swaps that do not change what is asserted.
+- Legitimate test updates that track a genuine spec change confirmed by the production diff or a concrete commit justification (see **Commit Context**).
+- Deleted tests for code that was itself deleted in the same MR.
+- Production-code bugs with no associated test weakening — route those to the `code-review` skill.
+- Flakiness, performance, style, naming, or coverage gaps that existed before this diff.
+- Speculative tampering where you cannot construct the specific behavior change the edit would hide.