@mechanai/deepreview 2.4.2 → 2.6.0

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

@@ -6,10 +6,17 @@ permission:
   edit: allow
   bash:
     "git diff*": allow
+    "mise tasks ls*": allow
     "mise run fmt*": allow
     "mise run lint*": allow
     "mise run check*": allow
     "mise run test*": allow
+    "npm run format*": allow
+    "npm run lint*": allow
+    "npm run test*": allow
+    "make fmt*": allow
+    "make lint*": allow
+    "make test*": allow
     "*": deny
 ---
 
@@ -44,13 +51,25 @@ If a fix cannot be applied (file doesn't exist, code doesn't match what was expe
 
 ## Verification (after all fixes are applied)
 
-After applying all fixes, run verification if `mise.toml` exists in the project root:
+After applying all fixes, run verification using the project's configured tooling.
 
-1. Run `mise run fmt` (auto-fix formatting — this is expected to modify files)
-2. Run `mise run lint` or `mise run check` (whichever exists)
-3. Run `mise run test`
+**Determining commands:** Check `AGENTS.md` (or `CLAUDE.md`) in the project root for explicit format/lint/test commands. If found, use those. Otherwise, auto-detect:
 
-If lint/check/test fails:
+- `mise.toml` exists: run `mise tasks ls`, then `mise run <task>` for tasks matching `fmt`/`format`, `lint`/`check`, `test`
+- `package.json` exists with matching scripts: `npm run format`, `npm run lint`, `npm run test`
+- `Makefile` exists with matching targets: `make fmt`, `make lint`, `make test`
+
+If no commands are found and no config files exist, skip verification and report `VERIFICATION: SKIPPED — no fmt/lint/test commands found`.
+
+**Steps:**
+
+1. **Format:** Run the format command (expected to modify files)
+2. **Lint:** Run the lint command
+   - If lint fails, fix errors **only in files you modified** this session. Do not fix pre-existing lint issues.
+   - Re-run format then lint. Attempt up to 2 fix-and-recheck cycles; if lint still fails, stop and report remaining errors.
+3. **Test:** Run the test command
+
+If lint/check/test still fails:
 
 - Include the error output in your response
 - Mark the relevant fix as FAILED with the error

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

@@ -19,7 +19,16 @@ You will receive a path to an input file. This may be a diff, a spec, a plan, or
 
 ## Prior Context (if provided)
 
-Your prompt may include sections titled "Design Decisions", "Prior Findings", and "Covered Regions". Rules: do NOT flag design decisions as issues; do NOT re-report prior findings; prioritize uncovered regions but you may still report _new_ issues in covered regions.
+Your prompt may include sections titled "Project Context", "Design Decisions", "Prior Findings", and "Covered Regions". Rules:
+
+- **Project Context:** If your prompt includes a "Project Context" section (version, deployment model, status), use it to calibrate severity:
+  - v0.x.0 projects: breaking changes are expected and acceptable per semver — flag them as **suggestion**, not **critical** or **warning**. The change "API breaking changes are expected" still applies at v0.x.0.
+  - v1+ public libraries: breaking changes require major version bump — flag as **critical** or **warning**.
+  - Internal tools with no external consumers: breaking changes are **suggestion**-level (internal reorganization risk only).
+  - Private/unpublished packages: breaking changes are **suggestion**, unless the project explicitly targets v1+ stability.
+- **Design Decisions:** Do NOT flag design decisions as issues; do NOT suggest alternatives.
+- **Prior Findings:** Do NOT re-report prior findings.
+- **Covered Regions:** Prioritize uncovered regions but you may still report _new_ issues in covered regions.
 
 Your prompt may also begin with framing directives (e.g., novelty-seeking instructions). Follow those directives in addition to the rules above.
 
@@ -57,9 +66,11 @@ Write your review to the output path provided. Use this format for each finding:
 
 Severity guide:
 
-- **critical:** Public API or data contract broken with no migration path
-- **warning:** Behavior change that may break some consumers silently
-- **suggestion:** Internal change that could become breaking if exposed later
+- **critical:** Public API or data contract broken with no migration path (or v1+ library with breaking change and no major version bump)
+- **warning:** Behavior change that may break some consumers silently (or v1+ breaking change that should have bumped major version)
+- **suggestion:** Internal change that could become breaking if exposed later (or v0.x.0 breaking API change — these are expected per semver)
+
+Note: For v0.x.0 projects, apply the semver exemption — breaking changes are expected during pre-1.0 development. Downgrade breaking API changes to **suggestion** unless they create data loss or irreversible corruption.
 
 If you find no issues, write: "No compatibility issues found."
 

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

@@ -19,7 +19,15 @@ You will receive a path to an input file. This may be a diff, a spec, a plan, or
 
 ## Prior Context (if provided)
 
-Your prompt may include sections titled "Design Decisions", "Prior Findings", and "Covered Regions". Rules: do NOT flag design decisions as issues; do NOT re-report prior findings; prioritize uncovered regions but you may still report _new_ issues in covered regions.
+Your prompt may include sections titled "Project Context", "Design Decisions", "Prior Findings", and "Covered Regions". Rules:
+
+- **Project Context:** If your prompt includes a "Project Context" section (version, deployment model), use it to calibrate severity:
+  - v0.x.0 projects are in active development: stale comments and docs are **suggestion**-level, not **critical** or **warning**.
+  - Published libraries (v1+) must maintain accurate docs: flag stale docs that contradict code as **critical** or **warning**.
+  - Internal tools have lower documentation burden than public APIs: cosmetic doc issues are **suggestion**, not **warning**.
+- **Design Decisions:** Do NOT flag design decisions as issues; do NOT suggest alternatives.
+- **Prior Findings:** Do NOT re-report prior findings.
+- **Covered Regions:** Prioritize uncovered regions but you may still report _new_ issues in covered regions.
 
 Your prompt may also begin with framing directives (e.g., novelty-seeking instructions). Follow those directives in addition to the rules above.
 

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

@@ -19,7 +19,16 @@ You will receive a path to an input file. This may be a diff, a spec, a plan, or
 
 ## Prior Context (if provided)
 
-Your prompt may include sections titled "Design Decisions", "Prior Findings", and "Covered Regions". Rules: do NOT flag design decisions as issues; do NOT re-report prior findings; prioritize uncovered regions but you may still report _new_ issues in covered regions.
+Your prompt may include sections titled "Project Context", "Design Decisions", "Prior Findings", and "Covered Regions". Rules:
+
+- **Project Context:** If your prompt includes a "Project Context" section (version, deployment model, threat model), use it to calibrate severity:
+  - Localhost-only tools have no network threat model: downgrade auth/network findings and missing security headers to **suggestion**-level, not **warning**.
+  - v0.x.0 projects may skip some production security checks: downgrade findings about production hardening to **suggestion**, not **critical** or **warning**.
+  - Internal-network tools are lower-threat than public-facing services: downgrade findings about external attack vectors to **suggestion**.
+  - Published libraries (v1+) must follow production security standards: flag unvalidated input and auth gaps as **critical** or **warning**.
+- **Design Decisions:** Do NOT flag design decisions as issues; do NOT suggest alternatives.
+- **Prior Findings:** Do NOT re-report prior findings.
+- **Covered Regions:** Prioritize uncovered regions but you may still report _new_ issues in covered regions.
 
 Your prompt may also begin with framing directives (e.g., novelty-seeking instructions). Follow those directives in addition to the rules above.
 

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

@@ -21,8 +21,20 @@ Set ALL_SESSION_DIRS=[] (list of all session directories used, in order)
 Determine REPO_ROOT — the main repository root (not a worktree root). Run:
 `REPO_ROOT=$(realpath "$(git rev-parse --git-common-dir)" | sed 's|/\.git$||')`
 
-If CONTEXT_FILE exists, read its contents and set PRIOR_CONTEXT to:
-"## Design Decisions (intentional — do not flag)\nThe following are deliberate design choices. Do NOT flag these as issues or suggest alternatives.\n`\n" + contents of CONTEXT_FILE + "\n`\n"
+Extract PROJECT_CONTEXT by detecting project metadata (version, deployment model, publish status):
+
+- Check for package.json or Cargo.toml to detect version and publish status
+- Check for .deepreview.yml to detect explicit deployment model (threatModel field)
+- If no .deepreview.yml exists, infer deployment model: v0.x.0 and private packages are "internal-network", v1+.x.x and public are "public-facing", otherwise "unknown"
+- 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)
+
+Build PRIOR_CONTEXT:
+
+- Start with PROJECT_CONTEXT (if non-empty)
+- If CONTEXT_FILE exists, append:
+  "## Design Decisions (intentional — do not flag)\nThe following are deliberate design choices. Do NOT flag these as issues or suggest alternatives.\n`\n" + contents of CONTEXT_FILE + "\n`\n"
+- If neither PROJECT_CONTEXT nor CONTEXT_FILE exist, set PRIOR_CONTEXT="" (empty string)
 
 STEP 2: RUN INITIAL DEEPREVIEW (full pipeline with cross-validation)
 Run the full deepreview pipeline (Stages 1-5 from the deepreview command):

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

@@ -15,7 +15,21 @@ STEP 1: DETERMINE INPUT
 - Set ALL_SESSION_DIRS=[] (list of all session directories used, in order)
 - Determine REPO_ROOT — the main repository root (not a worktree root). Run:
   `REPO_ROOT=$(realpath "$(git rev-parse --git-common-dir)" | sed 's|/\.git$||')`
-- If CONTEXT_FILE exists, set PRIOR_CONTEXT="## Design Decisions (intentional — do not flag)\nThe following are deliberate design choices. Do NOT flag these as issues or suggest alternatives.\n`\n" + contents of CONTEXT_FILE + "\n`\n\n"
+
+Extract PROJECT_CONTEXT by detecting project metadata (version, deployment model, publish status):
+
+- Check for package.json or Cargo.toml to detect version and publish status
+- Check for .deepreview.yml to detect explicit deployment model (threatModel field)
+- If no .deepreview.yml exists, infer deployment model: v0.x.0 and private packages are "internal-network", v1+.x.x and public are "public-facing", otherwise "unknown"
+- 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)
+
+Build PRIOR_CONTEXT:
+
+- Start with PROJECT_CONTEXT (if non-empty)
+- If CONTEXT_FILE exists, append:
+  "## Design Decisions (intentional — do not flag)\nThe following are deliberate design choices. Do NOT flag these as issues or suggest alternatives.\n`\n" + contents of CONTEXT_FILE + "\n`\n\n"
+- If neither PROJECT_CONTEXT nor CONTEXT_FILE exist, set PRIOR_CONTEXT="" (empty string)
 
 STEP 2: RUN INITIAL DEEPREVIEW-SPEC (full pipeline with cross-validation)
 Run the full deepreview-spec pipeline (Stages 1-5 from the deepreview-spec command):

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

@@ -23,10 +23,21 @@ STEP 2: PREPARE INPUT
 
 Set INPUT_DESCRIPTION="the following spec/plan files: $ARGUMENTS"
 
-If CONTEXT_FILE exists, set DESIGN_CONTEXT to the contents of that file. Build a CONTEXT_PREAMBLE:
+Extract PROJECT_CONTEXT by detecting project metadata (version, deployment model, publish status):
+
+- Check for package.json or Cargo.toml to detect version and publish status
+- Check for .deepreview.yml to detect explicit deployment model (threatModel field)
+- If no .deepreview.yml exists, infer deployment model: v0.x.0 and private packages are "internal-network", v1+.x.x and public are "public-facing", otherwise "unknown"
+- 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)
+
+Build CONTEXT_PREAMBLE:
+If PROJECT_CONTEXT is not empty, start with: "${PROJECT_CONTEXT}\n"
+
+If CONTEXT_FILE exists, append:
 "## Design Decisions (intentional — do not flag)\nThe following are deliberate design choices. Do NOT flag these as issues or suggest alternatives.\n`\n$DESIGN_CONTEXT\n`\n\n"
 
-If CONTEXT_FILE does not exist, set CONTEXT_PREAMBLE="" (empty string).
+If both PROJECT_CONTEXT and CONTEXT_FILE are empty, set CONTEXT_PREAMBLE="" (empty string).
 
 STEP 3: DISPATCH STAGE 1 — INITIAL REVIEW (5 parallel tasks)
 Dispatch ALL FIVE of these Task tool calls simultaneously in a single message:

package/.opencode/commands/deepreview.md

@@ -41,10 +41,37 @@ Set INPUT_DESCRIPTION based on mode:
 - MODE=branch: "a branch diff against main"
 - MODE=files: "the following files: <list of filenames>"
 
+STEP 2a: EXTRACT PROJECT CONTEXT
+Build PROJECT_CONTEXT by extracting metadata (version, deployment model, publish status) from the repo:
+
+- Check for package.json or Cargo.toml to detect version and publish status
+- Check for .deepreview.yml to detect explicit deployment model (threat-model field)
+- If no .deepreview.yml exists, infer deployment model: v0.x.0 and private packages are "internal-network", v1+.x.x and public are "public-facing", otherwise "unknown"
+- Format as:
+
+```
+## Project Context (for severity calibration)
+
+**Name:** [project name]
+**Version:** [version] (if v0.x.0, include note: "pre-1.0 — relaxed API stability expectations")
+**Deployment:** [localhost-only|internal-network|public-facing|library] [threat model note]
+**Status:** [Private/internal|Published]
+
+Use this context to calibrate finding severity. For example:
+- v0.1.0 projects may have API instability — flag as **suggestion**, not **warning**.
+- Localhost-only tools have no network threat model — downgrade auth/network findings to **suggestion**.
+- Stale docs in pre-1.0 projects are **suggestion**-level, not critical.
+```
+
+If metadata extraction fails or no version info is found, set PROJECT_CONTEXT="" (empty string).
+
+STEP 2b: BUILD CONTEXT PREAMBLE
 If CONTEXT_FILE exists, set DESIGN_CONTEXT to the contents of that file. Build a CONTEXT_PREAMBLE:
-"## Design Decisions (intentional — do not flag)\nThe following are deliberate design choices. Do NOT flag these as issues or suggest alternatives.\n`\n$DESIGN_CONTEXT\n`\n\n"
+"${PROJECT_CONTEXT}## Design Decisions (intentional — do not flag)\nThe following are deliberate design choices. Do NOT flag these as issues or suggest alternatives.\n`\n$DESIGN_CONTEXT\n`\n\n"
+
+If CONTEXT_FILE does not exist and PROJECT_CONTEXT is not empty, set CONTEXT_PREAMBLE to just "${PROJECT_CONTEXT}\n"
 
-If CONTEXT_FILE does not exist, set CONTEXT_PREAMBLE="" (empty string).
+If both are empty, set CONTEXT_PREAMBLE="" (empty string).
 
 STEP 3: DISPATCH STAGE 1 — INITIAL REVIEW (5 parallel tasks)
 Dispatch ALL FIVE of these Task tool calls simultaneously in a single message:

package/README.md

@@ -83,6 +83,35 @@ its own context, keeping token usage minimal.
 - `git`
 - `gh` CLI (only for PR commands)
 
+## Configuration
+
+### Verification (formatting, linting, tests)
+
+After applying fixes, the applier agent runs formatting, linting, and tests. It auto-detects
+commands based on what exists in your project root:
+
+| File detected  | Format           | Lint                               | Test            |
+| -------------- | ---------------- | ---------------------------------- | --------------- |
+| `mise.toml`    | `mise run fmt`   | `mise run lint` / `mise run check` | `mise run test` |
+| `package.json` | `npm run format` | `npm run lint`                     | `npm run test`  |
+| `Makefile`     | `make fmt`       | `make lint`                        | `make test`     |
+
+If your project uses different commands (e.g., `cargo fmt`, `ruff check --fix`),
+specify them in `AGENTS.md`. The applier looks for commands labeled **Format**, **Lint**, and
+**Test** (or similar). For example:
+
+```markdown
+- **Format:** `cargo fmt`
+- **Lint:** `cargo clippy -- -D warnings`
+- **Tests:** `cargo test`
+```
+
+The applier checks `AGENTS.md` (or `CLAUDE.md`) first, falling back to auto-detection.
+If no commands are found and no config files exist, verification is skipped.
+
+When lint fails, the applier attempts to fix errors in the files it modified (up to 2 retry
+cycles) before reporting the failure.
+
 ## Upgrade
 
 OpenCode caches plugins on first install and does not automatically check for newer versions.

package/package.json

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

package/src/project-context.test.ts

@@ -0,0 +1,80 @@
+import { describe, it, expect } from "bun:test";
+import { getProjectMetadata, formatProjectContextPreamble } from "./project-context";
+import path from "node:path";
+
+describe("project-context: metadata extraction", () => {
+  it("should extract metadata from package.json", () => {
+    const repoRoot = path.resolve(import.meta.dirname, "..");
+    const metadata = getProjectMetadata(repoRoot);
+
+    expect(metadata).toBeDefined();
+    expect(metadata.version).toBe("0.0.0-development");
+    expect(metadata.name).toBe("@mechanai/deepreview");
+    expect(metadata.deploymentModel).toBeDefined();
+  });
+});
+
+describe("project-context: preamble version handling", () => {
+  it("should format project context preamble for v0 projects", () => {
+    const metadata = {
+      version: "0.1.0",
+      name: "test-project",
+      isPrivate: true,
+      deploymentModel: "internal-network" as const,
+      description: "A test project",
+    };
+
+    const preamble = formatProjectContextPreamble(metadata);
+
+    expect(preamble).toContain("Project Context");
+    expect(preamble).toContain("0.1.0");
+    expect(preamble).toContain("pre-1.0");
+    expect(preamble).toContain("internal-network");
+    expect(preamble).toContain("severity calibration");
+  });
+
+  it("should handle v1+ versions without pre-1.0 note", () => {
+    const metadata = {
+      version: "1.2.3",
+      name: "stable-project",
+      isPrivate: false,
+      deploymentModel: "public-facing" as const,
+    };
+
+    const preamble = formatProjectContextPreamble(metadata);
+
+    expect(preamble).toContain("1.2.3");
+    expect(preamble).not.toMatch(/1\.2\.3.*pre-1\.0/u);
+    expect(preamble).toContain("public-facing");
+  });
+});
+
+describe("project-context: preamble deployment guidance", () => {
+  it("should include deployment guidance for localhost tools", () => {
+    const metadata = {
+      version: "0.1.0",
+      name: "dev-tool",
+      isPrivate: true,
+      deploymentModel: "localhost-only" as const,
+    };
+
+    const preamble = formatProjectContextPreamble(metadata);
+
+    expect(preamble).toContain("localhost-only");
+    expect(preamble).toContain("network/auth concerns");
+  });
+
+  it("should include guidance for published libraries", () => {
+    const metadata = {
+      version: "2.0.0",
+      name: "published-lib",
+      isPrivate: false,
+      deploymentModel: "library" as const,
+    };
+
+    const preamble = formatProjectContextPreamble(metadata);
+
+    expect(preamble).toContain("library");
+    expect(preamble).toContain("API stability");
+  });
+});

package/src/project-context.ts

@@ -0,0 +1,215 @@
+/**
+ * Project context detection and formatting for severity calibration in reviewers.
+ *
+ * Extracts metadata from package.json, Cargo.toml, and .deepreview.yml to build
+ * a preamble that helps reviewers calibrate finding severity appropriately.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { load as loadYaml } from "js-yaml";
+
+export interface ProjectMetadata {
+  /** Semantic version (e.g., "0.1.0", "3.2.1") */
+  version?: string;
+  /** Whether the project is marked as private/internal */
+  isPrivate?: boolean;
+  /** Deployment model: "localhost-only" | "internal-network" | "public-facing" | "library" | "unknown" */
+  deploymentModel?: string;
+  /** True if project has publish = false in Cargo.toml */
+  isUnpublished?: boolean;
+  /** Description of the project */
+  description?: string;
+  /** Name of the project */
+  name?: string;
+}
+
+export interface DeepReviewConfig {
+  threatModel?: "localhost-only" | "internal-network" | "public-facing" | "library";
+  /** Additional context hints for reviewers */
+  context?: string;
+}
+
+interface PackageJson {
+  name?: string;
+  version?: string;
+  description?: string;
+  private?: boolean;
+}
+
+function parsePackageJson(filePath: string): Partial<ProjectMetadata> {
+  try {
+    const content = readFileSync(filePath, "utf-8");
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- Why: JSON.parse returns any; fields are all optional strings/booleans
+    const pkg = JSON.parse(content) as PackageJson;
+    return {
+      version: pkg.version,
+      isPrivate: pkg.private === true,
+      name: pkg.name,
+      description: pkg.description,
+    };
+  } catch {
+    return {};
+  }
+}
+
+function parseCargoToml(filePath: string): Partial<ProjectMetadata> {
+  try {
+    const content = readFileSync(filePath, "utf-8");
+    const versionMatch = /^version\s*=\s*["']([^"']+)["']/u.exec(content);
+    const nameMatch = /^name\s*=\s*["']([^"']+)["']/u.exec(content);
+    const publishMatch = /^\[publish\]/u.exec(content);
+    const descMatch = /^description\s*=\s*["']([^"']+)["']/u.exec(content);
+
+    return {
+      version: versionMatch?.[1],
+      name: nameMatch?.[1],
+      description: descMatch?.[1],
+      isUnpublished: publishMatch !== null,
+    };
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Parse .deepreview.yml and extract deployment model.
+ */
+function parseDeepReviewConfig(filePath: string): DeepReviewConfig {
+  try {
+    const content = readFileSync(filePath, "utf-8");
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- Why: loadYaml returns unknown; fields are all optional with safe defaults
+    const result = loadYaml(content) as DeepReviewConfig | null;
+    return result ?? {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Detect deployment model from project structure and metadata.
+ */
+function detectDeploymentModel(metadata: ProjectMetadata, config: DeepReviewConfig): string {
+  // Explicit config wins
+  if (config.threatModel) {
+    return config.threatModel;
+  }
+
+  // Infer from metadata
+  if (metadata.isPrivate === false || metadata.isUnpublished === false) {
+    return "public-facing";
+  }
+  if (metadata.isPrivate === true) {
+    return "internal-network";
+  }
+
+  return "unknown";
+}
+
+/**
+ * Extract all project metadata from the repository root.
+ */
+export function getProjectMetadata(
+  repoRoot: string,
+): ProjectMetadata & { deploymentModel: string } {
+  // Try package.json first (Node.js projects)
+  const packageJsonPath = path.join(repoRoot, "package.json");
+  let metadata: Partial<ProjectMetadata> = existsSync(packageJsonPath)
+    ? parsePackageJson(packageJsonPath)
+    : {};
+
+  // Try Cargo.toml (Rust projects) — takes precedence for version/name if both exist
+  const cargoTomlPath = path.join(repoRoot, "Cargo.toml");
+  if (existsSync(cargoTomlPath)) {
+    metadata = { ...metadata, ...parseCargoToml(cargoTomlPath) };
+  }
+
+  // Try .deepreview.yml for explicit configuration
+  const deepReviewConfigPath = path.join(repoRoot, ".deepreview.yml");
+  const config: DeepReviewConfig = existsSync(deepReviewConfigPath)
+    ? parseDeepReviewConfig(deepReviewConfigPath)
+    : {};
+
+  const deploymentModel = detectDeploymentModel(metadata as ProjectMetadata, config);
+
+  return {
+    ...(metadata as ProjectMetadata),
+    deploymentModel,
+  };
+}
+
+/**
+ * Get deployment context description for severity calibration.
+ */
+function getDeploymentContext(deploymentModel: string): string {
+  switch (deploymentModel) {
+    case "localhost-only":
+      return "(localhost-only dev tools — network/auth concerns are lower priority)";
+    case "internal-network":
+      return "(internal tool — auth is important but threat model is limited to internal users)";
+    case "public-facing":
+      return "(public-facing service — threat model includes untrusted users)";
+    case "library":
+      return "(published library — API stability and backwards compatibility are critical)";
+    default:
+      return "";
+  }
+}
+
+/**
+ * Build calibration guidelines for severity assessment.
+ */
+function getCalibrationGuidelines(): string[] {
+  return [
+    "- Pre-1.0 projects: breaking API changes are expected — flag as suggestion, not warning",
+    "- Localhost-only tools: network/auth concerns are lower priority — downgrade to suggestion",
+    "- Published libraries (v1+): API stability and auth are critical — flag violations as warning/critical",
+    "- Stale docs in pre-1.0 projects: flag as suggestion, not critical",
+  ];
+}
+
+/**
+ * Format project metadata as a context preamble for reviewers.
+ * This is prepended to PRIOR_CONTEXT and helps reviewers calibrate severity.
+ */
+export function formatProjectContextPreamble(
+  metadata: ProjectMetadata & { deploymentModel: string },
+): string {
+  const lines: string[] = ["## Project Context (for severity calibration)"];
+
+  if (metadata.name !== undefined && metadata.name !== "") {
+    lines.push(`**Name:** ${metadata.name}`);
+  }
+
+  if (metadata.version !== undefined && metadata.version !== "") {
+    const versionParts = metadata.version.split(".");
+    const majorVersion = Number.parseInt(versionParts[0] ?? "0", 10);
+    if (majorVersion === 0) {
+      lines.push(
+        `**Version:** ${metadata.version} (pre-1.0 — relaxed API stability expectations; breaking changes are expected)`,
+      );
+    } else {
+      lines.push(`**Version:** ${metadata.version}`);
+    }
+  }
+
+  if (metadata.deploymentModel !== "") {
+    const deploymentContext = getDeploymentContext(metadata.deploymentModel);
+    lines.push(`**Deployment:** ${metadata.deploymentModel} ${deploymentContext}`);
+  }
+
+  if (metadata.isPrivate === true) {
+    lines.push("**Status:** Private/internal project (no external consumers)");
+  } else if (metadata.isUnpublished === false) {
+    lines.push("**Status:** Published (breaking changes require major version bump)");
+  }
+
+  if (metadata.description !== undefined && metadata.description !== "") {
+    lines.push(`**Purpose:** ${metadata.description}`);
+  }
+
+  lines.push("\nUse this context to calibrate finding severity. Calibration guidelines:");
+  lines.push(...getCalibrationGuidelines());
+
+  return lines.join("\n") + "\n";
+}