@mechanai/deepreview 2.14.0 → 2.16.0

package/.opencode/agents/deepreview-plan-validator.md

@@ -58,9 +58,9 @@ Write your validated plan to the output path provided. Use this structure:
 
 ## Fix Plan
 
-### Fix [N]: [Issue Title]
+### Fix [N]: [Issue Title] (full format — critical/warning)
 **File(s):** path/to/file:line
-**Priority:** critical | warning | suggestion
+**Priority:** critical | warning
 **Validation:** approved | revised | rejected
 **Validation notes:** [1-2 sentences: what was checked, what was found]
 **Approach:** [original or revised approach]
@@ -68,6 +68,14 @@ Write your validated plan to the output path provided. Use this structure:
 [Original code if approved, corrected code if revised, "[rejected — see validation notes]" if rejected]
 **Verification:** [from original plan]
 
+### Fix [N]: [Issue Title] (compact format — suggestion)
+**File(s):** path/to/file:line
+**Priority:** suggestion
+**Validation:** approved | revised | rejected
+**Validation notes:** [1-2 sentences: what was checked, what was found]
+**Change:** [Original or corrected instruction; "[rejected — see validation notes]" if rejected]
+**Verification:** [from original plan, if present]
+
 ## Order of Operations
 [Revised if any fixes were rejected or reordering is needed]
 

package/.opencode/agents/deepreview-planner.md

@@ -25,19 +25,22 @@ You will receive a path to a synthesis file. Read it.
 
 ## Documentation Drift handling
 
-If the synthesis contains a "Documentation Drift" section with a batched checklist, consolidate all those items into a **single** fix entry in the plan. Do not create separate fix entries for each documentation item. Use this format:
+If the synthesis contains a "Documentation Drift" section with a batched checklist, consolidate all those items into a **single** fix entry in the plan using compact format. Do not create separate fix entries for each documentation item. Use this format:
 
 ```
 ### Fix [N]: Documentation Updates
+
 **File(s):** [list all affected files]
 **Priority:** suggestion
-**Approach:** Batch update stale/verbose documentation
-**Code changes:**
-[Group changes by file. For each file, show the exact text replacement.]
+**Change:**
+
+- path/to/file1:42 — Replace "old text" with "new text"
+- path/to/file2:18 — Delete stale comment
+- path/to/file3:55 — Replace "old description" with "new description"
 **Verification:** Confirm updated docs match current code behavior
 ```
 
-Critical documentation findings (which appear individually in the "Critical Issues" section, not in "Documentation Drift") should still get their own fix entries.
+Critical documentation findings (which appear individually in the "Critical Issues" section, not in "Documentation Drift") should still get their own fix entries using full format.
 
 ## Quality rules
 
@@ -45,6 +48,15 @@ Critical documentation findings (which appear individually in the "Critical Issu
 - **Stay within scope.** Only fix what the synthesis identifies. Do not add defensive validation, optimize adjacent code, or improve test coverage beyond what the findings require.
 - **Concrete, not aspirational.** Every code change must be copy-pasteable. No pseudocode, no "something like this", no TODOs.
 
+## Format selection
+
+Select the output format for each fix based on its priority:
+
+- **Full format** for `critical` and `warning` fixes — include Approach and Code change blocks
+- **Compact format** for `suggestion` fixes — use a one-line Change instruction instead (e.g., "Replace X with Y", "Delete line N", "Add X after line N")
+
+For batched documentation fixes, the Change field uses a bullet list (one instruction per location).
+
 ## Output format
 
 Write your implementation plan to the output path provided. Use this structure:
@@ -53,22 +65,33 @@ Write your implementation plan to the output path provided. Use this structure:
 # Implementation Plan — [PR/branch] — [date]
 
 ## Summary
+
 [What needs to be fixed and the estimated scope of work]
 
 ## Fix Plan
 
-### Fix [N]: [Issue Title]
+### Fix [N]: [Issue Title] (full format — critical/warning)
+
 **File(s):** path/to/file:line
-**Priority:** critical | warning | suggestion
+**Priority:** critical | warning
 **Approach:** [what to change and why — 1-2 sentences]
 **Code change:**
 [Exact code to replace the problematic code. Use actual variable names, actual logic. Not pseudocode.]
 **Verification:** [what to check after the fix — 1 sentence]
 
+### Fix [N]: [Issue Title] (compact format — suggestion)
+
+**File(s):** path/to/file:line
+**Priority:** suggestion
+**Change:** [One-line instruction: "Replace X with Y" or "Delete lines N-M" or "Add X after line N"]
+**Verification:** [optional — omit if obvious]
+
 ## Order of Operations
+
 [If fixes depend on each other, specify the order. Otherwise: "Fixes are independent — apply in any order."]
 
 ## Risk
+
 [Any fixes that could introduce new issues and what to watch for]
 ```
 

package/.opencode/commands/deepreview-loop.md

@@ -18,6 +18,7 @@ Set ITERATION=1
 Set PRIOR_CONTEXT="" (empty — built up across iterations; holds both design context and prior findings)
 Set CONSECUTIVE_ZERO_NEW=0 (tracks consecutive iterations with 0 new findings for deadlock detection)
 Set ALL_SESSION_DIRS=[] (list of all session directories used, in order)
+Set EXPIRED_ENTRIES=[] (calibration entries that have expired — collected at start, used at end)
 
 Determine REPO_ROOT — the main repository root (not a worktree root). Run:
 `REPO_ROOT=$(realpath "$(git rev-parse --git-common-dir)" | sed 's|/\.git$||')`
@@ -30,6 +31,12 @@ Extract PROJECT_CONTEXT by detecting project metadata (version, deployment model
 - Format as a calibration preamble with version info, deployment model, and guidance for severity adjustment
 - If metadata extraction fails or no version info is found, set PROJECT_CONTEXT="" (empty string)
 
+Load learned calibration by calling the `deepreview-calibration-load` tool (no arguments needed — it uses the working directory). Parse the JSON response:
+
+- If `preamble` is non-empty, append it to PROJECT_CONTEXT (after the static calibration guidelines)
+- If `expired` is non-empty, store EXPIRED_ENTRIES for end-of-session prompting
+- If the tool fails or returns empty, proceed without calibration (do not STOP)
+
 Build PRIOR_CONTEXT:
 
 - Start with PROJECT_CONTEXT (if non-empty)
@@ -62,7 +69,7 @@ NOVELTY MODE (iter2+ only):
 A) CONVERGENCE EXIT: If `0 new AND 0 regression`:
 
 - Tell the user: "deepreview-loop converged after $ITERATION iteration(s). No new findings detected."
-- STOP.
+- Go to STEP 6 (calibration proposal), then STOP.
 
 B) DEADLOCK (synthesizer signal): If `0 new AND N recurring (N > 0) AND 0 regression` for 2 consecutive iterations:
 
@@ -95,7 +102,7 @@ Compare this iteration's findings (file:line + issue title) against the previous
 If the synthesis/review has 0 critical AND 0 warning AND 0 suggestion findings:
 
 - Tell the user: "deepreview-loop complete after $ITERATION iteration(s). No findings remain."
-- STOP.
+- Go to STEP 6 (calibration proposal), then STOP.
 
 STEP 4: APPLY ALL FIXES
 Dispatch the applier automatically — do NOT ask the user for permission.
@@ -130,7 +137,7 @@ If ITERATION > 5:
 - Tell the user: "deepreviewloop hit iteration limit (5). Remaining findings may require manual intervention or a design decision."
 - Show the latest stats.
 - Ask the user: "Continue for more iterations, or stop here?"
-- If user says stop → STOP.
+- If user says stop → Go to STEP 6 (calibration proposal), then STOP.
 - If user says continue → reset limit to ITERATION + 5 and proceed.
 
 Create new session directory: SESSION_DIR="$REPO_ROOT/.ai/deepreview/loop-iter$ITERATION-$(date +%Y-%m-%d-%H%M%S)"
@@ -309,10 +316,48 @@ If this task fails, emit a warning: "Plan validation failed — applying unvalid
 
 Go to STEP 3.
 
+STEP 6: PROPOSE CALIBRATION UPDATES (runs after any exit — clean exit, deadlock, or iteration limit)
+
+Skip this step if ITERATION == 1 AND the exit was a clean exit (0 findings on first pass means nothing to calibrate).
+
+Compare reviewer severity to synthesized severity from the LAST completed iteration:
+
+1. Read the reviewer files ($SESSION_DIR/review-\*.md) from the last iteration
+2. Read the synthesis file ($SESSION_DIR/synthesis.md) from the last iteration
+3. For each finding in the synthesis, identify if ANY reviewer originally flagged it at a HIGHER severity
+4. Only consider DOWNGRADES (reviewer said "critical" or "warning", synthesis says lower)
+
+For each detected downgrade pattern:
+
+- Check if it matches an existing calibration entry (from EXPIRED_ENTRIES or active entries loaded at start)
+  - If yes: increment observedCount, set lastConfirmed to today
+  - If new: create a proposed entry with observedCount=1
+
+If there are proposed updates (new or incremented entries) OR expired entries to remove:
+
+- Call `deepreview-calibration-load` to get current entries
+- Present to user:
+
+```
+Calibration update proposed:
+
+- NEW: "[pattern]" in [context]: [originalSeverity] → [adjustedSeverity]
+- UPDATED: "[pattern]" in [context]: observed N→N+1, re-confirmed
+- EXPIRED: "[pattern]" (last confirmed N days ago) — will be removed
+
+Accept these changes? [y/n/edit]
+```
+
+- If user approves: merge proposed entries with existing active entries (removing expired ones), then call `deepreview-calibration-save` with the merged entries
+- If user says "edit": let them modify the proposal, then save
+- If user rejects: skip saving
+
+If no adjustments were detected and no entries expired, skip this step silently.
+
 IMPORTANT RULES:
 
-- Do NOT read any review/synthesis/plan files yourself. Ever.
-- Use ONLY the file paths and stats/summary lines returned by subagents.
+- Do NOT read any review/synthesis/plan files yourself during STEPS 1-5. Exception: STEP 6 (calibration proposal) requires reading reviewer and synthesis files to detect severity adjustments.
+- Use ONLY the file paths and stats/summary lines returned by subagents (during STEPS 1-5).
 - Apply ALL findings (critical, warning, AND suggestion) — the goal is a clean review.
 - Do NOT ask the user for permission to apply fixes. Apply automatically.
 - DO ask the user if: iteration limit is hit, deadlock is detected, verification fails, or diff size diverges.

package/.opencode/commands/deepreview-spec-loop.md

@@ -14,6 +14,7 @@ STEP 1: DETERMINE INPUT
 - Set PRIOR_CONTEXT="" (empty — built up across iterations; holds both design context and prior findings)
 - Set CONSECUTIVE_ZERO_NEW=0 (tracks consecutive iterations with 0 new findings for deadlock detection)
 - Set ALL_SESSION_DIRS=[] (list of all session directories used, in order)
+- Set EXPIRED_ENTRIES=[] (calibration entries that have expired — collected at start, used at end)
 - Determine REPO_ROOT — the main repository root (not a worktree root). Run:
   `REPO_ROOT=$(realpath "$(git rev-parse --git-common-dir)" | sed 's|/\.git$||')`
 
@@ -25,6 +26,12 @@ Extract PROJECT_CONTEXT by detecting project metadata (version, deployment model
 - Format as a calibration preamble with version info, deployment model, and guidance for severity adjustment
 - If metadata extraction fails or no version info is found, set PROJECT_CONTEXT="" (empty string)
 
+Load learned calibration by calling the `deepreview-calibration-load` tool (no arguments needed — it uses the working directory). Parse the JSON response:
+
+- If `preamble` is non-empty, append it to PROJECT_CONTEXT (after the static calibration guidelines)
+- If `expired` is non-empty, store EXPIRED_ENTRIES for end-of-session prompting
+- If the tool fails or returns empty, proceed without calibration (do not STOP)
+
 Build PRIOR_CONTEXT:
 
 - Start with PROJECT_CONTEXT (if non-empty)
@@ -56,12 +63,12 @@ NOVELTY MODE (iter2+ only):
 A) CLEAN EXIT: If 0 critical AND 0 warning AND 0 suggestion:
 
 - Tell the user: "deepreview-spec-loop complete after $ITERATION iteration(s). No findings remain."
-- STOP.
+- Go to STEP 6 (calibration proposal), then STOP.
 
 B) CONVERGENCE EXIT: If `0 new AND 0 regression`:
 
 - Tell the user: "deepreview-spec-loop converged after $ITERATION iteration(s). No new findings detected. Remaining recurring findings (if any) reflect reviewer opinion differences."
-- STOP.
+- Go to STEP 6 (calibration proposal), then STOP.
 
 C) DEADLOCK EXIT: If `0 new AND N recurring (N > 0) AND 0 regression` for 2 consecutive iterations:
 
@@ -94,13 +101,13 @@ Track the total finding count (critical + warning + suggestion) for each iterati
 A) CLEAN EXIT: If 0 critical AND 0 warning AND 0 suggestion:
 
 - Tell the user: "deepreview-spec-loop complete after $ITERATION iteration(s). No findings remain."
-- STOP.
+- Go to STEP 6 (calibration proposal), then STOP.
 
 B) PLATEAU EXIT: If ITERATION >= 3 and the total has not decreased compared to the minimum of any previous iteration for 2 consecutive iterations:
 
 - Tell the user: "deepreview-spec-loop plateau after $ITERATION iteration(s). Findings are oscillating (history: [list totals]) and not converging."
 - Show the latest stats breakdown.
-- STOP.
+- Go to STEP 6 (calibration proposal), then STOP.
 
 STEP 4: APPLY ALL FIXES
 Dispatch the applier automatically — do NOT ask the user for permission.
@@ -118,7 +125,7 @@ If ITERATION > 7:
 
 - Tell the user: "deepreview-spec-loop hit iteration limit (7). This should not normally happen — convergence or deadlock detection should have stopped earlier."
 - Show the latest stats.
-- STOP.
+- Go to STEP 6 (calibration proposal), then STOP.
 
 Create new session directory: SESSION_DIR="$REPO_ROOT/.ai/deepreview/spec-loop-iter$ITERATION-$(date +%Y-%m-%d-%H%M%S)"
 Run `mkdir -p $SESSION_DIR`
@@ -250,10 +257,48 @@ If this task fails, emit a warning: "Plan validation failed — applying unvalid
 
 Go to STEP 3.
 
+STEP 6: PROPOSE CALIBRATION UPDATES (runs after any exit — clean exit, plateau, or iteration limit)
+
+Skip this step if ITERATION == 1 AND the exit was a clean exit (0 findings on first pass means nothing to calibrate).
+
+Compare reviewer severity to synthesized severity from the LAST completed iteration:
+
+1. Read the reviewer files ($SESSION_DIR/review-\*.md) from the last iteration
+2. Read the synthesis file ($SESSION_DIR/synthesis.md) from the last iteration
+3. For each finding in the synthesis, identify if ANY reviewer originally flagged it at a HIGHER severity
+4. Only consider DOWNGRADES (reviewer said "critical" or "warning", synthesis says lower)
+
+For each detected downgrade pattern:
+
+- Check if it matches an existing calibration entry (from EXPIRED_ENTRIES or active entries loaded at start)
+  - If yes: increment observedCount, set lastConfirmed to today
+  - If new: create a proposed entry with observedCount=1
+
+If there are proposed updates (new or incremented entries) OR expired entries to remove:
+
+- Call `deepreview-calibration-load` to get current entries
+- Present to user:
+
+```
+Calibration update proposed:
+
+- NEW: "[pattern]" in [context]: [originalSeverity] → [adjustedSeverity]
+- UPDATED: "[pattern]" in [context]: observed N→N+1, re-confirmed
+- EXPIRED: "[pattern]" (last confirmed N days ago) — will be removed
+
+Accept these changes? [y/n/edit]
+```
+
+- If user approves: merge proposed entries with existing active entries (removing expired ones), then call `deepreview-calibration-save` with the merged entries
+- If user says "edit": let them modify the proposal, then save
+- If user rejects: skip saving
+
+If no adjustments were detected and no entries expired, skip this step silently.
+
 IMPORTANT RULES:
 
-- Do NOT read any review/synthesis/plan files yourself. Ever.
-- Use ONLY the file paths and stats/summary lines returned by subagents.
+- Do NOT read any review/synthesis/plan files yourself during STEPS 1-5. Exception: STEP 6 (calibration proposal) requires reading reviewer and synthesis files to detect severity adjustments.
+- Use ONLY the file paths and stats/summary lines returned by subagents (during STEPS 1-5).
 - Apply ALL findings (critical, warning, AND suggestion) — the goal is a clean review.
 - Do NOT ask the user for permission to apply fixes. Apply automatically.
 - DO ask the user if iteration limit is hit, divergence is detected, or deadlock is detected.

package/.opencode/plugins/deepreview.ts

@@ -1,6 +1,33 @@
 import { type Plugin, type PluginInput, tool } from "@opencode-ai/plugin";
+import { execSync } from "node:child_process";
+import { resolve } from "node:path";
 import { postReview } from "../../src/post-review.ts";
 import { buildPriorReview } from "../../src/build-prior-review.ts";
+import {
+  type CalibrationEntry,
+  type CalibrationSettings,
+  loadCalibration,
+  formatCalibrationPreamble,
+  writeCalibration,
+} from "../../src/calibration.ts";
+
+/**
+ * Resolve the main repository root (not a worktree root) from a working directory.
+ * Falls back to the given directory if git resolution fails.
+ */
+function resolveRepoRoot(cwd: string): string {
+  try {
+    const gitCommonDir = execSync("git rev-parse --git-common-dir", {
+      cwd,
+      encoding: "utf-8",
+    }).trim();
+    // git-common-dir returns the path to .git (or the shared .git dir for worktrees).
+    // It may be relative, so resolve against cwd, then strip trailing /.git for the repo root.
+    return resolve(cwd, gitCommonDir).replace(/\/\.git$/u, "");
+  } catch {
+    return cwd;
+  }
+}
 
 // oxlint-disable-next-line require-await, max-lines-per-function -- Why: Plugin type signature requires async but this plugin has no async initialization; function is long due to tool registrations with schema definitions
 export const server: Plugin = async (_input: PluginInput) => {
@@ -69,6 +96,41 @@ export const server: Plugin = async (_input: PluginInput) => {
           }
         },
       }),
+      "deepreview-calibration-load": tool({
+        description:
+          "Load per-project calibration entries (learned severity adjustments from prior " +
+          "review sessions). Returns active entries, expired entries needing re-confirmation, " +
+          "and a formatted preamble for reviewer injection.",
+        args: {},
+        async execute(_args, context) {
+          const repoRoot = resolveRepoRoot(context.directory);
+          const { active, expired } = loadCalibration(repoRoot);
+          const preamble = formatCalibrationPreamble(active);
+          return JSON.stringify({ active, expired, preamble });
+        },
+      }),
+      "deepreview-calibration-save": tool({
+        description:
+          "Save calibration entries to .ai/deepreview/calibration.yml (local, unversioned). " +
+          "Always writes to local — never modifies .deepreview.yml.",
+        args: {
+          entries: tool.schema.string().describe("JSON array of CalibrationEntry objects to save"),
+          expiry_days: tool.schema
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Expiry window in days (default: 30)"),
+        },
+        async execute(args, context) {
+          const repoRoot = resolveRepoRoot(context.directory);
+          // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- Why: JSON.parse returns any; schema is validated by the caller (orchestrator)
+          const entries = JSON.parse(args.entries) as CalibrationEntry[];
+          const settings: CalibrationSettings = { expiryDays: args.expiry_days ?? 30 };
+          writeCalibration(repoRoot, { version: 1, settings, entries });
+          return JSON.stringify({ written: `${repoRoot}/.ai/deepreview/calibration.yml` });
+        },
+      }),
     },
   };
 };

package/README.md

@@ -83,6 +83,65 @@ graph LR
 Stages communicate via files on disk — the orchestrator never reads review content into
 its own context, keeping token usage minimal.
 
+## Calibration
+
+deepreview learns from validator severity adjustments over time. When validators
+consistently downgrade the same category of finding (e.g., "missing auth" in a
+localhost-only tool), the system proposes calibration entries at the end of each
+review session.
+
+### How it works
+
+1. **Session end:** The orchestrator compares reviewer severity to synthesized
+   (post-validation) severity
+2. **Proposal:** Systematic downgrades are proposed as calibration entries
+3. **User confirms:** You approve, edit, or reject the proposed changes
+4. **Next session:** Approved calibration is injected into reviewer prompts,
+   reducing severity inflation
+
+### Configuration
+
+Local calibration (personal, gitignored):
+
+```yaml
+# .ai/deepreview/calibration.yml
+version: 1
+settings:
+  expiryDays: 30 # days before unconfirmed entries expire
+entries:
+  - id: "cal-001"
+    pattern: "missing authentication"
+    context: "localhost-only server"
+    originalSeverity: "warning"
+    adjustedSeverity: "suggestion"
+    observedCount: 4
+    lastConfirmed: "2026-06-28"
+    createdAt: "2026-06-01"
+```
+
+### Sharing calibration with your team
+
+To share calibration entries, add them to `.deepreview.yml` under the `calibration:` key:
+
+```yaml
+# .deepreview.yml
+threatModel: localhost-only
+calibration:
+  settings:
+    expiryDays: 60
+  entries:
+    - id: "shared-001"
+      pattern: "missing authentication"
+      context: "localhost-only server"
+      originalSeverity: "warning"
+      adjustedSeverity: "suggestion"
+      observedCount: 4
+      lastConfirmed: "2026-06-28"
+      createdAt: "2026-06-01"
+```
+
+Local entries override shared entries when both match the same `pattern` + `context`.
+
 ### Review agents
 
 | Agent                       | Code review                            | Spec review                                  |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mechanai/deepreview",
-  "version": "2.14.0",
+  "version": "2.16.0",
   "description": "Multi-agent parallel code/spec review for OpenCode",
   "license": "MIT",
   "repository": {

package/src/calibration.test.ts

@@ -0,0 +1,249 @@
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import {
+  loadCalibration,
+  writeCalibration,
+  nextId,
+  formatCalibrationPreamble,
+  type CalibrationEntry,
+} from "./calibration";
+import { mkdirSync, writeFileSync, rmSync, existsSync } from "node:fs";
+import path from "node:path";
+
+const TEST_ROOT = path.join(import.meta.dirname, "..", "tmp-calibration-test");
+
+beforeEach(() => {
+  mkdirSync(path.join(TEST_ROOT, ".ai", "deepreview"), { recursive: true });
+});
+
+afterEach(() => {
+  rmSync(TEST_ROOT, { recursive: true, force: true });
+});
+
+// oxlint-disable-next-line max-lines-per-function -- Why: comprehensive test coverage for loadCalibration requires inline YAML fixtures to keep each case self-contained; extracting fixtures would obscure the scenario being tested
+describe("calibration: loadCalibration", () => {
+  it("returns empty when no calibration file exists", () => {
+    const emptyRoot = path.join(TEST_ROOT, "no-files");
+    mkdirSync(emptyRoot, { recursive: true });
+    const result = loadCalibration(emptyRoot);
+    expect(result.active).toEqual([]);
+    expect(result.expired).toEqual([]);
+  });
+
+  it("loads entries from local calibration file", () => {
+    const yaml = `
+version: 1
+settings:
+  expiryDays: 30
+entries:
+  - id: "cal-001"
+    pattern: "missing auth"
+    context: "localhost-only server"
+    originalSeverity: "warning"
+    adjustedSeverity: "suggestion"
+    observedCount: 3
+    lastConfirmed: "${new Date().toISOString().split("T")[0]}"
+    createdAt: "2026-01-01"
+`;
+    writeFileSync(path.join(TEST_ROOT, ".ai", "deepreview", "calibration.yml"), yaml);
+    const result = loadCalibration(TEST_ROOT);
+    expect(result.active).toHaveLength(1);
+    expect(result.active[0].id).toBe("cal-001");
+    expect(result.expired).toHaveLength(0);
+  });
+
+  it("filters expired entries based on expiryDays", () => {
+    const oldDate = "2020-01-01";
+    const yaml = `
+version: 1
+settings:
+  expiryDays: 30
+entries:
+  - id: "cal-001"
+    pattern: "old pattern"
+    context: "stale context"
+    originalSeverity: "warning"
+    adjustedSeverity: "suggestion"
+    observedCount: 2
+    lastConfirmed: "${oldDate}"
+    createdAt: "2020-01-01"
+`;
+    writeFileSync(path.join(TEST_ROOT, ".ai", "deepreview", "calibration.yml"), yaml);
+    const result = loadCalibration(TEST_ROOT);
+    expect(result.active).toHaveLength(0);
+    expect(result.expired).toHaveLength(1);
+    expect(result.expired[0].id).toBe("cal-001");
+  });
+
+  it("merges shared and local entries (local wins on conflict)", () => {
+    const today = new Date().toISOString().split("T")[0];
+    const sharedYaml = `
+threatModel: localhost-only
+calibration:
+  settings:
+    expiryDays: 60
+  entries:
+    - id: "shared-001"
+      pattern: "missing auth"
+      context: "localhost-only server"
+      originalSeverity: "warning"
+      adjustedSeverity: "suggestion"
+      observedCount: 2
+      lastConfirmed: "${today}"
+      createdAt: "2026-01-01"
+    - id: "shared-002"
+      pattern: "stale docs"
+      context: "pre-1.0 project"
+      originalSeverity: "critical"
+      adjustedSeverity: "suggestion"
+      observedCount: 5
+      lastConfirmed: "${today}"
+      createdAt: "2026-01-01"
+`;
+    const localYaml = `
+version: 1
+settings:
+  expiryDays: 30
+entries:
+  - id: "cal-001"
+    pattern: "missing auth"
+    context: "localhost-only server"
+    originalSeverity: "warning"
+    adjustedSeverity: "suggestion"
+    observedCount: 5
+    lastConfirmed: "${today}"
+    createdAt: "2026-02-01"
+`;
+    writeFileSync(path.join(TEST_ROOT, ".deepreview.yml"), sharedYaml);
+    writeFileSync(path.join(TEST_ROOT, ".ai", "deepreview", "calibration.yml"), localYaml);
+
+    const result = loadCalibration(TEST_ROOT);
+    // "missing auth" + "localhost-only server" conflict: local wins (observedCount=5)
+    const authEntry = result.active.find((e) => e.pattern === "missing auth");
+    expect(authEntry?.observedCount).toBe(5);
+    expect(authEntry?.id).toBe("cal-001");
+    // "stale docs" comes from shared only
+    const docsEntry = result.active.find((e) => e.pattern === "stale docs");
+    expect(docsEntry?.id).toBe("shared-002");
+  });
+
+  it("handles malformed YAML gracefully", () => {
+    writeFileSync(
+      path.join(TEST_ROOT, ".ai", "deepreview", "calibration.yml"),
+      "not: [valid: yaml: {{{",
+    );
+    const result = loadCalibration(TEST_ROOT);
+    expect(result.active).toEqual([]);
+    expect(result.expired).toEqual([]);
+  });
+
+  it("uses shared expiryDays when local has no settings", () => {
+    // Compute a date 60 days ago — with 90-day expiry this should still be active
+    const d = new Date();
+    d.setDate(d.getDate() - 60);
+    const oldDate = d.toISOString().split("T")[0];
+    const sharedYaml = `
+threatModel: localhost-only
+calibration:
+  settings:
+    expiryDays: 90
+  entries:
+    - id: "shared-001"
+      pattern: "some pattern"
+      context: "some context"
+      originalSeverity: "warning"
+      adjustedSeverity: "suggestion"
+      observedCount: 2
+      lastConfirmed: "${oldDate}"
+      createdAt: "2026-01-01"
+`;
+    const localYaml = `
+version: 1
+entries: []
+`;
+    writeFileSync(path.join(TEST_ROOT, ".deepreview.yml"), sharedYaml);
+    writeFileSync(path.join(TEST_ROOT, ".ai", "deepreview", "calibration.yml"), localYaml);
+
+    const result = loadCalibration(TEST_ROOT);
+    // With 90-day expiry, an entry from ~60 days ago should still be active
+    expect(result.active).toHaveLength(1);
+  });
+});
+
+describe("calibration: nextId", () => {
+  it("returns cal-001 for empty list", () => {
+    expect(nextId([])).toBe("cal-001");
+  });
+
+  it("increments from highest existing ID", () => {
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- Why: test stubs only need id field; full CalibrationEntry would be verbose for this nextId unit test
+    const entries = [{ id: "cal-003" } as any, { id: "cal-001" } as any];
+    // oxlint-disable-next-line typescript/no-unsafe-argument -- Why: stub array; safe for nextId which only reads .id
+    expect(nextId(entries)).toBe("cal-004");
+  });
+
+  it("handles non-numeric IDs gracefully", () => {
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- Why: test stubs only need id field; full CalibrationEntry would be verbose for this nextId unit test
+    const entries = [{ id: "shared-001" } as any, { id: "cal-002" } as any];
+    // oxlint-disable-next-line typescript/no-unsafe-argument -- Why: stub array; safe for nextId which only reads .id
+    expect(nextId(entries)).toBe("cal-003");
+  });
+});
+
+describe("calibration: formatCalibrationPreamble", () => {
+  it("returns empty string for no entries", () => {
+    expect(formatCalibrationPreamble([])).toBe("");
+  });
+
+  it("formats entries as markdown preamble", () => {
+    const entries: CalibrationEntry[] = [
+      {
+        id: "cal-001",
+        pattern: "missing auth",
+        context: "localhost-only server",
+        originalSeverity: "warning",
+        adjustedSeverity: "suggestion",
+        observedCount: 4,
+        lastConfirmed: "2026-06-28",
+        createdAt: "2026-06-01",
+      },
+    ];
+    const preamble = formatCalibrationPreamble(entries);
+    expect(preamble).toContain("Learned Calibration");
+    expect(preamble).toContain('"missing auth" in localhost-only server');
+    expect(preamble).toContain("suggestion (not warning)");
+    expect(preamble).toContain("Confirmed 4x");
+  });
+});
+
+describe("calibration: writeCalibration", () => {
+  it("creates directory and writes YAML file", () => {
+    const writeRoot = path.join(TEST_ROOT, "write-test");
+    mkdirSync(writeRoot, { recursive: true });
+    const today = new Date().toISOString().split("T")[0];
+
+    writeCalibration(writeRoot, {
+      version: 1,
+      settings: { expiryDays: 30 },
+      entries: [
+        {
+          id: "cal-001",
+          pattern: "test pattern",
+          context: "test context",
+          originalSeverity: "warning",
+          adjustedSeverity: "suggestion",
+          observedCount: 1,
+          lastConfirmed: today,
+          createdAt: today,
+        },
+      ],
+    });
+
+    const filePath = path.join(writeRoot, ".ai", "deepreview", "calibration.yml");
+    expect(existsSync(filePath)).toBe(true);
+
+    // Verify we can read it back
+    const result = loadCalibration(writeRoot);
+    expect(result.active).toHaveLength(1);
+    expect(result.active[0].pattern).toBe("test pattern");
+  });
+});

package/src/calibration.ts

@@ -0,0 +1,212 @@
+/**
+ * Per-project calibration persistence for deepreview severity adjustments.
+ *
+ * Reads/writes .ai/deepreview/calibration.yml (local) and the calibration
+ * section of .deepreview.yml (shared). Handles merge logic, expiry, and
+ * preamble formatting for reviewer injection.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { dump as dumpYaml, load as loadYaml } from "js-yaml";
+
+/** Severity levels used by deepreview findings. */
+export type Severity = "critical" | "warning" | "suggestion";
+
+/** A single calibration entry recording a systematic severity adjustment. */
+export interface CalibrationEntry {
+  /** Unique identifier (e.g., "cal-001") */
+  id: string;
+  /** Short description of the finding category */
+  pattern: string;
+  /** Project-specific context that makes this adjustment valid */
+  context: string;
+  /** Severity the reviewer originally assigned */
+  originalSeverity: Severity;
+  /** Severity the validator adjusted to */
+  adjustedSeverity: Severity;
+  /** How many times this adjustment has been observed */
+  observedCount: number;
+  /** When a validator last made this same adjustment (ISO date) */
+  lastConfirmed: string;
+  /** When the entry was first created (ISO date) */
+  createdAt: string;
+}
+
+/** Configurable settings for calibration behavior. */
+export interface CalibrationSettings {
+  /** Days before an unconfirmed entry expires (default: 30) */
+  expiryDays: number;
+}
+
+/** Top-level calibration file structure. */
+export interface CalibrationData {
+  version: 1;
+  settings?: CalibrationSettings;
+  entries: CalibrationEntry[];
+}
+
+interface SharedConfig {
+  threatModel?: string;
+  calibration?: {
+    settings?: Partial<CalibrationSettings>;
+    entries?: CalibrationEntry[];
+  };
+}
+
+const DEFAULT_EXPIRY_DAYS = 30;
+const LOCAL_PATH = ".ai/deepreview/calibration.yml";
+const SHARED_PATH = ".deepreview.yml";
+
+function isExpired(entry: CalibrationEntry, expiryDays: number): boolean {
+  const lastConfirmed = new Date(entry.lastConfirmed);
+  const now = new Date();
+  const diffMs = now.getTime() - lastConfirmed.getTime();
+  const diffDays = diffMs / (1000 * 60 * 60 * 24);
+  return diffDays > expiryDays;
+}
+
+function parseLocalFile(filePath: string): CalibrationData | null {
+  if (!existsSync(filePath)) {
+    return null;
+  }
+  try {
+    const content = readFileSync(filePath, "utf-8");
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- Why: loadYaml returns unknown; validated by field access below
+    const data = loadYaml(content) as CalibrationData | null;
+    if (data === null || typeof data !== "object") {
+      return null;
+    }
+    return data;
+  } catch {
+    return null;
+  }
+}
+
+function parseSharedFile(filePath: string): {
+  settings?: Partial<CalibrationSettings>;
+  entries: CalibrationEntry[];
+} {
+  if (!existsSync(filePath)) {
+    return { entries: [] };
+  }
+  try {
+    const content = readFileSync(filePath, "utf-8");
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- Why: loadYaml returns unknown; validated by field access below
+    const data = loadYaml(content) as SharedConfig | null;
+    if (data?.calibration === undefined) {
+      return { entries: [] };
+    }
+    return {
+      settings: data.calibration.settings,
+      entries: data.calibration.entries ?? [],
+    };
+  } catch {
+    return { entries: [] };
+  }
+}
+
+function entryKey(entry: CalibrationEntry): string {
+  return `${entry.pattern}|||${entry.context}`;
+}
+
+/**
+ * Load and merge calibration from local + shared sources, filtering expired entries.
+ *
+ * Merge precedence: local entries override shared entries when both match on
+ * pattern + context. Settings precedence: local > shared > default (30 days).
+ */
+export function loadCalibration(repoRoot: string): {
+  active: CalibrationEntry[];
+  expired: CalibrationEntry[];
+} {
+  const localPath = path.join(repoRoot, LOCAL_PATH);
+  const sharedPath = path.join(repoRoot, SHARED_PATH);
+
+  const local = parseLocalFile(localPath);
+  const shared = parseSharedFile(sharedPath);
+
+  // Settings precedence: local > shared > default
+  const expiryDays =
+    local?.settings?.expiryDays ?? shared.settings?.expiryDays ?? DEFAULT_EXPIRY_DAYS;
+
+  // Merge: start with shared entries, then overlay local entries by key
+  const merged = new Map<string, CalibrationEntry>();
+  for (const entry of shared.entries) {
+    merged.set(entryKey(entry), entry);
+  }
+  for (const entry of local?.entries ?? []) {
+    merged.set(entryKey(entry), entry);
+  }
+
+  const active: CalibrationEntry[] = [];
+  const expired: CalibrationEntry[] = [];
+
+  for (const entry of merged.values()) {
+    if (isExpired(entry, expiryDays)) {
+      expired.push(entry);
+    } else {
+      active.push(entry);
+    }
+  }
+
+  return { active, expired };
+}
+
+/**
+ * Format active calibration entries as a markdown preamble for reviewer injection.
+ * Returns empty string if no entries.
+ */
+export function formatCalibrationPreamble(entries: CalibrationEntry[]): string {
+  if (entries.length === 0) {
+    return "";
+  }
+
+  const lines: string[] = [
+    "## Learned Calibration (from prior review sessions)",
+    "",
+    "The following patterns have been consistently downgraded by validators in this",
+    "project. Adjust your severity accordingly — do not inflate these categories:",
+    "",
+  ];
+
+  for (const entry of entries) {
+    lines.push(
+      `- "${entry.pattern}" in ${entry.context} → ${entry.adjustedSeverity} (not ${entry.originalSeverity}). Confirmed ${entry.observedCount}x.`,
+    );
+  }
+
+  return lines.join("\n") + "\n";
+}
+
+/**
+ * Write calibration data to .ai/deepreview/calibration.yml.
+ * Creates the .ai/deepreview/ directory if it doesn't exist.
+ */
+export function writeCalibration(repoRoot: string, data: CalibrationData): void {
+  const dirPath = path.join(repoRoot, ".ai", "deepreview");
+  if (!existsSync(dirPath)) {
+    mkdirSync(dirPath, { recursive: true });
+  }
+  const filePath = path.join(dirPath, "calibration.yml");
+  const yaml = dumpYaml(data, { lineWidth: 120, noRefs: true });
+  writeFileSync(filePath, `# Auto-maintained by deepreview. User-editable.\n${yaml}`);
+}
+
+/**
+ * Generate the next sequential calibration entry ID.
+ * Parses existing "cal-NNN" IDs and returns "cal-(max+1)".
+ */
+export function nextId(existing: CalibrationEntry[]): string {
+  let max = 0;
+  for (const entry of existing) {
+    const match = /^cal-(\d+)$/u.exec(entry.id);
+    if (match) {
+      const num = Number.parseInt(match[1], 10);
+      if (num > max) {
+        max = num;
+      }
+    }
+  }
+  return `cal-${String(max + 1).padStart(3, "0")}`;
+}

package/src/project-context.ts

@@ -8,6 +8,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { load as loadYaml } from "js-yaml";
+import type { Severity } from "./calibration";
 
 export interface ProjectMetadata {
   /** Semantic version (e.g., "0.1.0", "3.2.1") */
@@ -28,6 +29,20 @@ export interface DeepReviewConfig {
   threatModel?: "localhost-only" | "internal-network" | "public-facing" | "library";
   /** Additional context hints for reviewers */
   context?: string;
+  /** Shared calibration entries and settings (opt-in team calibration) */
+  calibration?: {
+    settings?: { expiryDays?: number };
+    entries?: Array<{
+      id: string;
+      pattern: string;
+      context: string;
+      originalSeverity: Severity;
+      adjustedSeverity: Severity;
+      observedCount: number;
+      lastConfirmed: string;
+      createdAt: string;
+    }>;
+  };
 }
 
 interface PackageJson {