@mechanai/deepreview 2.5.0 → 2.6.1

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-plan-validator.md

@@ -5,12 +5,12 @@ temperature: 0.1
 permission:
   # Read access is implicitly unrestricted (OpenCode default) — needed to inspect source files.
   edit:
-    ".ai/deepreview/**": allow
     "*": deny
+    ".ai/deepreview/**": allow
   bash:
+    "*": deny
     "git log*": allow
     "git blame*": allow
-    "*": deny
 ---
 
 You are a skeptical senior engineer. Your job is to independently verify each proposed fix in an implementation plan before it gets applied to the codebase. You are not here to agree with the planner — you are here to catch mistakes.

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mechanai/deepreview",
-  "version": "2.5.0",
+  "version": "2.6.1",
   "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";
+}