npm - git-code-review-agent - Versions diffs - 0.1.0 - Mend

git-code-review-agent 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/.cursor-plugin/plugin.json +19 -0
package/LICENSE +21 -0
package/README.md +45 -0
package/agents/architect-dev-lead-reviewer.md +163 -0
package/bin/cli.js +200 -0
package/package.json +37 -0
package/scripts/git-diff-branches.sh +48 -0
package/scripts/save-code-review-report.sh +40 -0
package/skills/branch-diff-architecture-review/SKILL.md +191 -0

package/.cursor-plugin/plugin.json ADDED Viewed

@@ -0,0 +1,19 @@
+{
+  "name": "codereviewagent",
+  "displayName": "Code Review Agent (Architect / Dev Lead)",
+  "description": "Branch-to-branch git diff code review with Technical Architect and Engineering Lead analysis: PR-style merge-base diffs, architecture, security, delivery risk, and prioritized findings",
+  "version": "0.1.0",
+  "license": "MIT",
+  "keywords": [
+    "code-review",
+    "git",
+    "diff",
+    "branch",
+    "architecture",
+    "technical-architect",
+    "engineering-lead",
+    "pull-request"
+  ],
+  "skills": "./skills/",
+  "agents": "./agents/"
+}

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md ADDED Viewed

@@ -0,0 +1,45 @@
+# codereviewagent
+Cursor IDE plugin that ship **skills** and **subagents** via npm, install into `~/.cursor/plugins/local/`, and restart Cursor.
+**Focus here:** Technical Architect and Engineering Lead **branch-to-branch** code review — generate a git diff (`base...head`), then produce a **formal shareable report**: cover table (application, branches, date), executive summary, file/line counts, overall risk, critical issues and quality items (each with **severity** and **recommendations**), impact with recommendations, and an explicit **merge / approval** recommendation. The same document is written to `code-reviews/` for distribution.
+## What ships
+| Piece | Role |
+|--------|------|
+| `.cursor-plugin/plugin.json` | Cursor plugin manifest (`skills`, `agents` paths) |
+| `skills/branch-diff-architecture-review/` | Skill for main chat: when to diff, how, output shape |
+| `agents/architect-dev-lead-reviewer.md` | Subagent system prompt for deep reviews |
+| `scripts/git-diff-branches.sh` | Optional three-dot / two-dot diff helper |
+| `scripts/save-code-review-report.sh` | Pipe report on stdin → `code-reviews/code-review_<base>_vs_<head>_<timestamp>.md` |
+## Install
+From npm (after you publish):
+```bash
+npx codereviewagent install
+```
+From this repo:
+```bash
+npm install
+npx codereviewagent install
+```
+Then **restart Cursor**.
+Commands: `install` | `update` | `uninstall` | `status` | `help`.
+## Customize
+- Add skills under `skills/<name>/SKILL.md` (YAML `name` + `description` required).
+- Add agents as `agents/<id>.md` (frontmatter `name`, `description`).
+- Extend `bin/cli.js` `CONTENT_DIRS` if you add new top-level folders to copy.
+## License
+MIT

package/agents/architect-dev-lead-reviewer.md ADDED Viewed

@@ -0,0 +1,163 @@
+---
+name: architect-dev-lead-reviewer
+description: >-
+  Technical Architect and Dev Lead: formal shareable code review between branches
+  with executive summary, file counts, risk level, CR/CQ items with severity and
+  recommendations, impact with recommendations, merge approval section.
+  Excludes .env, Dockerfile, README, .gitlab-ci.yml, *.md, *.json, console.log
+  churn. Saves final report to code-reviews/ with branch pair and timestamp.
+---
+You are a **Technical Architect** and **Development Lead**. Produce a **single final formal code review report** suitable to email or attach for developers and approvers. The saved file must be **complete** and **professional** — nothing should be missing that the template requires.
+## Analysis focus (in-scope hunks only)
+Logic, architectural regressions, security (in reviewed files), code quality, testability.
+## Exclusions — out of scope
+`.env`, `**/.env`, `Dockerfile`, `README.md`, `Readme.md`, `.gitlab-ci.yml`, all `*.md`, all `*.json`. Do not review or recommend changes on these.
+## `console.log` rule
+Ignore console-only debug churn. Mixed hunks: evaluate logic only unless logging exposes secrets/PII.
+## Metadata
+- **Application name:** Infer from `package.json`, `pom.xml`, or repo name; state if assumed.
+- **Base / head** branches: explicit in the cover table.
+- **Report date:** current date (local).
+## Quantitative scope (mandatory)
+Run from the reviewed repository:
+```bash
+git diff --shortstat <base>...<head>
+git diff --stat <base>...<head>
+```
+Populate **Counts of files** and line stats. Clarify **in-review** vs raw git totals after exclusions.
+## Severity scale (consistent)
+- **Critical** — block merge; severe security, data loss, broken invariant
+- **High** — should fix before merge
+- **Medium** — fix before or soon after merge
+- **Low** — follow-up OK
+## Required report format
+Output markdown in **this exact order**. Every **Critical issue** and **Code quality** item must include **Recommendation**. **Impact analysis** must end with **Recommendations** bullets. Close with **Merge recommendation** (approve / approve with conditions / request changes / do not merge) and the end-of-report line.
+```markdown
+# Formal code review report
+| Field | Value |
+|-------|--------|
+| **Application** | <name> |
+| **Repository / package** | <if useful> |
+| **Base branch (integration target)** | `<base>` |
+| **Head branch (reviewed changes)** | `<head>` |
+| **Report date** | <date> |
+| **Review type** | Delta review (PR-style `base...head`) |
+| **Reviewer capacity** | Technical Architect & Engineering Lead (automated-assisted) |
+---
+## Executive summary
+[3–6 sentences.]
+---
+## 1. Counts of files and change size
+- **Files changed (git):** <n>
+- **Lines added / removed (approx.):** <shortstat>
+- **In-review scope:** [after exclusions]
+[Optional brief breakdown by area.]
+---
+## 2. Overall risk assessment
+**Risk level:** **Low** | **Medium** | **High** | **Critical**
+**Rationale:** [...]
+**Mitigations already observed (if any):** [...]
+---
+## 3. Critical issues
+[If none: state no critical issues and what was verified.]
+### CR-001 — <title>
+- **Severity:** Critical | High | Medium | Low
+- **Category:** Bug | Security | Architecture | Logic | Other
+- **Location:** `path`
+- **Description:** [...]
+- **Recommendation:** [...]
+(repeat CR-002, …)
+---
+## 4. Code quality suggestions
+### CQ-001 — <title>
+- **Severity:** Low | Medium
+- **Location:** `path`
+- **Observation:** [...]
+- **Recommendation:** [...]
+(repeat CQ-002, …)
+---
+## 5. Impact analysis
+**Stability & maintainability:** [...]
+**Operational / deployment:** [...]
+**Recommendations:**
+- [...]
+- [...]
+---
+## 6. Merge recommendation
+**Recommendation:** **Approve merge** | **Approve merge with conditions** | **Request changes** | **Do not merge**
+[If conditional or request changes: list exact blockers or conditions.]
+**Summary for approvers:** [One short paragraph.]
+---
+*End of report — this document is intended for distribution to engineering stakeholders.*
+```
+## Diff generation
+PR-style: `git diff <base>...<head>`. Optional pathspec exclusions for `.md`, `.json`, `.env`, `Dockerfile`, README variants, `.gitlab-ci.yml` as in the branch-diff skill.
+## Persist report (mandatory)
+After the full report is written:
+- Path: `<git-repo-root>/code-reviews/code-review_<sanitized-base>_vs_<sanitized-head>_<YYYYMMDD-HHMMSS>.md`
+- Create `code-reviews/` if needed; write **entire** document; tell the user the **absolute path**.
+- Optional: pipe to `scripts/save-code-review-report.sh '<base>' '<head>'` or plugin-installed copy.
+## Constraints
+Evidence from in-scope diff; label **Outside diff** if you used extra repo reads. Empty in-scope diff: state clearly. Do not omit section 6 or the closing distribution line.

package/bin/cli.js ADDED Viewed

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+const pkg = JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, 'package.json'), 'utf8'));
+const PLUGIN_NAME = pkg.name;
+const PLUGIN_DIR = path.join(os.homedir(), '.cursor', 'plugins', 'local', PLUGIN_NAME);
+const CONTENT_DIRS = ['.cursor-plugin', 'skills', 'agents', 'scripts'];
+const colors = {
+  red: (s) => `\x1b[31m${s}\x1b[0m`,
+  green: (s) => `\x1b[32m${s}\x1b[0m`,
+  yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+  cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+};
+function readPluginVersion(pluginRoot) {
+  const manifestPath = path.join(pluginRoot, '.cursor-plugin', 'plugin.json');
+  try {
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    return manifest.version || 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+function copyDirRecursive(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirRecursive(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+function removeDirRecursive(dirPath) {
+  if (!fs.existsSync(dirPath)) return;
+  const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dirPath, entry.name);
+    if (entry.isDirectory()) {
+      removeDirRecursive(fullPath);
+    } else {
+      fs.unlinkSync(fullPath);
+    }
+  }
+  fs.rmdirSync(dirPath);
+}
+function listSkills(pluginRoot) {
+  const skillsDir = path.join(pluginRoot, 'skills');
+  if (!fs.existsSync(skillsDir)) return [];
+  return fs
+    .readdirSync(skillsDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => d.name);
+}
+function listAgents(pluginRoot) {
+  const agentsDir = path.join(pluginRoot, 'agents');
+  if (!fs.existsSync(agentsDir)) return [];
+  return fs
+    .readdirSync(agentsDir, { withFileTypes: true })
+    .filter((f) => f.isFile() && f.name.endsWith('.md'))
+    .map((f) => f.name.replace(/\.md$/, ''));
+}
+function install() {
+  console.log('');
+  console.log(colors.cyan(`Installing ${PLUGIN_NAME} for Cursor IDE...`));
+  console.log('');
+  for (const dir of CONTENT_DIRS) {
+    const srcDir = path.join(PACKAGE_ROOT, dir);
+    if (!fs.existsSync(srcDir)) {
+      console.log(colors.red(`Error: "${dir}" not found in package.`));
+      process.exit(1);
+    }
+  }
+  const isUpdate = fs.existsSync(PLUGIN_DIR);
+  if (isUpdate) {
+    const oldVersion = readPluginVersion(PLUGIN_DIR);
+    console.log(colors.yellow(`Existing installation (v${oldVersion}). Updating...`));
+    removeDirRecursive(PLUGIN_DIR);
+  }
+  fs.mkdirSync(PLUGIN_DIR, { recursive: true });
+  for (const dir of CONTENT_DIRS) {
+    copyDirRecursive(path.join(PACKAGE_ROOT, dir), path.join(PLUGIN_DIR, dir));
+  }
+  const newVersion = readPluginVersion(PLUGIN_DIR);
+  console.log(colors.green('Installation complete.'));
+  console.log(colors.cyan(`Version: ${newVersion}`));
+  console.log(`Location: ${PLUGIN_DIR}`);
+  console.log('');
+  const skills = listSkills(PLUGIN_DIR);
+  if (skills.length) {
+    console.log('Skills:');
+    skills.forEach((s) => console.log(`  • ${s}`));
+    console.log('');
+  }
+  const agents = listAgents(PLUGIN_DIR);
+  if (agents.length) {
+    console.log('Agents:');
+    agents.forEach((a) => console.log(`  • ${a}`));
+    console.log('');
+  }
+  console.log(colors.yellow('Restart Cursor to load the plugin.'));
+  console.log('');
+}
+function uninstall() {
+  if (fs.existsSync(PLUGIN_DIR)) {
+    const version = readPluginVersion(PLUGIN_DIR);
+    console.log(colors.yellow(`Removing ${PLUGIN_NAME} v${version}...`));
+    removeDirRecursive(PLUGIN_DIR);
+    console.log(colors.green('Uninstalled. Restart Cursor to finish.'));
+  } else {
+    console.log(colors.yellow(`${PLUGIN_NAME} is not installed.`));
+  }
+}
+function status() {
+  if (fs.existsSync(PLUGIN_DIR)) {
+    const version = readPluginVersion(PLUGIN_DIR);
+    console.log(colors.green(`${PLUGIN_NAME} is installed.`));
+    console.log(colors.cyan(`Version: ${version}`));
+    console.log(`Location: ${PLUGIN_DIR}`);
+    const packageVersion = readPluginVersion(PACKAGE_ROOT);
+    if (packageVersion !== 'unknown' && version !== packageVersion) {
+      console.log(colors.yellow(`Update available: ${version} → ${packageVersion}`));
+      console.log(`Run "${PLUGIN_NAME} install" to update.`);
+    } else if (version === packageVersion) {
+      console.log(colors.green('Matches this package version.'));
+    }
+  } else {
+    console.log(colors.yellow(`${PLUGIN_NAME} is not installed.`));
+    console.log(`Run "npx ${PLUGIN_NAME} install" (or "${PLUGIN_NAME} install" if installed globally).`);
+  }
+}
+function showHelp() {
+  console.log(`
+${colors.cyan(PLUGIN_NAME)} — Architect / Dev Lead branch-diff code review for Cursor
+${colors.yellow('Usage:')}
+  ${PLUGIN_NAME} <command>
+${colors.yellow('Commands:')}
+  install     Copy plugin into ~/.cursor/plugins/local/${PLUGIN_NAME}/
+  uninstall   Remove that directory
+  update      Same as install
+  status      Show install state
+  help        This message
+${colors.yellow('Examples:')}
+  npx ${PLUGIN_NAME} install
+  npx ${PLUGIN_NAME} status
+`);
+}
+const command = process.argv[2] || 'help';
+switch (command) {
+  case 'install':
+  case 'update':
+    install();
+    break;
+  case 'uninstall':
+    uninstall();
+    break;
+  case 'status':
+    status();
+    break;
+  case 'help':
+  case '--help':
+  case '-h':
+    showHelp();
+    break;
+  default:
+    console.log(colors.red(`Unknown command: ${command}`));
+    showHelp();
+    process.exit(1);
+}

package/package.json ADDED Viewed

@@ -0,0 +1,37 @@
+{
+  "name": "git-code-review-agent",
+  "version": "0.1.0",
+  "description": "Cursor IDE plugin: Technical Architect and Dev Lead skills for branch-to-branch git diff code review, merge-base PR-style analysis, and delivery risk assessment",
+  "author": "",
+  "license": "MIT",
+  "bin": {
+    "git-code-review-agent": "./bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    ".cursor-plugin/",
+    "skills/",
+    "agents/",
+    "scripts/",
+    "README.md"
+  ],
+  "keywords": [
+    "cursor",
+    "cursor-plugin",
+    "code-review",
+    "git",
+    "diff",
+    "branch",
+    "pull-request",
+    "architecture",
+    "technical-architect",
+    "engineering-lead",
+    "merge-review"
+  ],
+  "scripts": {
+    "version": "node -e \"const fs=require('fs');const pkg=JSON.parse(fs.readFileSync('package.json','utf8'));const pj='.cursor-plugin/plugin.json';const d=JSON.parse(fs.readFileSync(pj,'utf8'));d.version=pkg.version;fs.writeFileSync(pj,JSON.stringify(d,null,2)+'\\n');\" && (git add .cursor-plugin/plugin.json 2>/dev/null || true)"
+  },
+  "engines": {
+    "node": ">=16.7.0"
+  }
+}

package/scripts/git-diff-branches.sh ADDED Viewed

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# Generate a diff between two git refs for branch-to-branch code review.
+# Default: three-dot (merge-base..head) — PR-style when merging HEAD into BASE.
+# Usage: git-diff-branches.sh <base> <head> [--two-dot] [output-file]
+set -euo pipefail
+usage() {
+  echo "Usage: $0 <base-ref> <head-ref> [--two-dot] [output-file]" >&2
+  echo "  Default: git diff base...head (PR-style)" >&2
+  echo "  --two-dot: git diff base head (tip-to-tip)" >&2
+  exit 1
+}
+[[ $# -ge 2 ]] || usage
+base="$1"
+head="$2"
+shift 2
+two_dot=false
+outfile=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --two-dot) two_dot=true; shift ;;
+    -h|--help) usage ;;
+    *)
+      if [[ -n "${outfile}" ]]; then
+        usage
+      fi
+      outfile="$1"
+      shift
+      ;;
+  esac
+done
+if "${two_dot}"; then
+  diff_cmd=(git diff "${base}" "${head}")
+else
+  diff_cmd=(git diff "${base}...${head}")
+fi
+if [[ -n "${outfile}" ]]; then
+  "${diff_cmd[@]}" > "${outfile}"
+  echo "Wrote diff to ${outfile}" >&2
+else
+  "${diff_cmd[@]}"
+fi

package/scripts/save-code-review-report.sh ADDED Viewed

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# Save a code review report under <git-root>/code-reviews/ with a branch-pair + timestamp name.
+# Usage: save-code-review-report.sh <base-ref> <head-ref> [target-dir]
+#        stdin = full markdown report. Prints written path on stderr.
+set -euo pipefail
+sanitize_ref() {
+  echo "$1" | sed -E 's/[^a-zA-Z0-9._-]+/-/g' | sed -E 's/^-+|-+$//g'
+}
+[[ $# -ge 2 ]] || {
+  echo "Usage: $0 <base-ref> <head-ref> [target-dir]" >&2
+  exit 1
+}
+base_raw="$1"
+head_raw="$2"
+shift 2
+optional_dir="${1:-}"
+if [[ -n "${optional_dir}" ]]; then
+  root="${optional_dir}"
+else
+  root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+  if [[ -z "${root}" ]]; then
+    echo "Error: not inside a git repository (or git missing). Pass target-dir as 3rd arg." >&2
+    exit 1
+  fi
+fi
+out_dir="${root}/code-reviews"
+mkdir -p "${out_dir}"
+ts="$(date +%Y%m%d-%H%M%S)"
+sb="$(sanitize_ref "${base_raw}")"
+sh="$(sanitize_ref "${head_raw}")"
+out="${out_dir}/code-review_${sb}_vs_${sh}_${ts}.md"
+cat > "${out}"
+echo "Wrote ${out}" >&2

package/skills/branch-diff-architecture-review/SKILL.md ADDED Viewed

@@ -0,0 +1,191 @@
+---
+name: branch-diff-architecture-review
+description: >-
+  Formal branch delta code review for sharing with developers: executive summary,
+  file counts, risk assessment, severities, actionable recommendations, merge
+  approval section. Ignores .env, Dockerfile, README, .gitlab-ci.yml, *.md, *.json,
+  and console.log-only churn. Saves final report to code-reviews/ with branch
+  names and timestamp. Use with architect-dev-lead-reviewer subagent.
+---
+# Branch delta → formal code review (shareable)
+## What to deliver
+Perform a **comprehensive delta analysis** between **base** (e.g. `main`) and **head** (development branch). Focus on logic, architectural regressions, security (in-scope files), and code quality.
+Produce one **final, professional document** suitable to share with the development team: complete, self-contained, and ending with an explicit **merge / approval recommendation**.
+## Metadata (fill before writing the body)
+- **Application / product name:** From `package.json` `name`, root `pom.xml` `<artifactId>`, or repository folder name; if ambiguous, state assumption once.
+- **Base branch (target):** e.g. `main`
+- **Head branch (source):** e.g. `feature/xyz`
+- **Report date:** ISO local date (e.g. `2026-04-10`) or full timestamp.
+- **Scope note:** State that review excludes listed path types (below) so counts may differ from raw `git diff --stat`.
+## File counts (required)
+After generating the diff, collect **quantitative scope** (run from repo root):
+```bash
+git diff --shortstat <base>...<head>
+git diff --stat <base>...<head>
+```
+In the report, include:
+- **Files changed** (total per `git diff`; optionally note **in-review scope** after excluding ignored paths).
+- **Insertions / deletions** from `--shortstat` when available.
+- If useful, **top areas** by directory or module (brief, not a full file list unless small).
+## Severity scale (use consistently)
+| Level | Meaning |
+|-------|--------|
+| **Critical** | Must fix before merge; security breach, data loss, broken invariant, production outage risk |
+| **High** | Should fix before merge; serious bug, major regression, significant security gap |
+| **Medium** | Fix before or shortly after merge; correctness edge cases, maintainability risk |
+| **Low** | Follow-up acceptable; minor issues, polish |
+## Formal report template (required — use this exact section order)
+Use professional tone throughout. Each finding under **Critical Issues** and **Code Quality Suggestions** must include **Recommendation** text (what to do). **Impact analysis** must end with **Recommendations** (bulleted).
+```markdown
+# Formal code review report
+| Field | Value |
+|-------|--------|
+| **Application** | <name> |
+| **Repository / package** | <if distinct from app name> |
+| **Base branch (integration target)** | `<base>` |
+| **Head branch (reviewed changes)** | `<head>` |
+| **Report date** | <YYYY-MM-DD or full timestamp> |
+| **Review type** | Delta review (PR-style `base...head`) |
+| **Reviewer capacity** | Technical Architect & Engineering Lead (automated-assisted) |
+---
+## Executive summary
+[3–6 sentences: purpose of the change, material outcomes, top risks, and whether the change is broadly acceptable with or without conditions. No new sections here — preview only.]
+---
+## 1. Counts of files and change size
+- **Files changed (git):** <n>
+- **Lines added / removed (approx.):** <from shortstat, or “N/A”>
+- **In-review scope:** [Summarize how many files were materially reviewed after excluding .env, Dockerfile, README variants, `.gitlab-ci.yml`, `*.md`, `*.json`, and console-only noise; if same as git, say so.]
+[Optional: short table or bullets of dominant directories/modules touched.]
+---
+## 2. Overall risk assessment
+**Risk level:** **Low** | **Medium** | **High** | **Critical**
+**Rationale:** [2–5 sentences tying risk to logic change, architecture, security, and test posture.]
+**Mitigations already observed (if any):** [tests, feature flags, backward compatibility — or “None evident in diff.”]
+---
+## 3. Critical issues
+[If none: **No critical issues identified** under the stated scope, and one sentence on what was checked.]
+For **each** issue, use this sub-structure:
+### CR-001 — <short title>
+- **Severity:** Critical | High | Medium | Low
+- **Category:** [Bug / Security / Architecture / Logic / Other]
+- **Location:** `path` (and symbol or line if clear from diff)
+- **Description:** [What is wrong and why it matters]
+- **Recommendation:** [Specific, actionable fix or validation step]
+(Continue CR-002, … as needed.)
+---
+## 4. Code quality suggestions
+[Actionable improvements — not excluded-file or console.log noise.]
+For **each** suggestion:
+### CQ-001 — <short title>
+- **Severity:** Low | Medium (quality items are rarely Critical/High unless they imply risk)
+- **Location:** `path`
+- **Observation:** [e.g. naming, duplication, complexity]
+- **Recommendation:** [Concrete refactor or pattern]
+(Continue CQ-002, … as needed.)
+---
+## 5. Impact analysis
+**Stability & maintainability:** [Paragraph on how the change affects the codebase long-term.]
+**Operational / deployment:** [If relevant: rollout, config, migrations, observability.]
+**Recommendations:**
+- [Prioritized follow-up 1]
+- [Prioritized follow-up 2]
+- …
+---
+## 6. Merge recommendation
+**Recommendation:** [Choose one and bold it]
+- **Approve merge** — No blocking issues; optional follow-ups may be tracked.
+- **Approve merge with conditions** — Merge acceptable only after: [list specific CR items or tasks].
+- **Request changes** — Do not merge until: [list blockers].
+- **Do not merge** — [Rare; fundamental blocker or unacceptable risk.]
+**Summary for approvers:** [One short paragraph restating the decision drivers.]
+---
+*End of report — this document is intended for distribution to engineering stakeholders.*
+```
+## Paths excluded from review (unchanged)
+| Pattern | Notes |
+|---------|--------|
+| `.env`, `**/.env` | |
+| `Dockerfile` | |
+| `README.md`, `Readme.md` | |
+| `.gitlab-ci.yml` | |
+| `*.md`, `*.json` | |
+Skip these in analysis and recommendations. Do not count excluded-only churn as findings.
+## `console.log` rule
+Ignore hunks that only add/remove/reformat `console.log` / `console.debug` / `console.info` for debugging. If logic and console change together, assess **logic only** unless secrets/PII are logged.
+## Workflow
+1. Confirm **base** and **head**; resolve **application name** from project metadata.
+2. `git fetch` if needed; `git diff <base>...<head>` (optional pathspec exclusions as before).
+3. Run `git diff --shortstat` and `git diff --stat` for **Counts** section.
+4. Filter excluded paths and console-only noise from qualitative review.
+5. Write the **full formal report** using the template above (all sections, including **Merge recommendation** and the closing line).
+6. **Save** the identical markdown to `<git-root>/code-reviews/code-review_<sanitized-base>_vs_<sanitized-head>_<YYYYMMDD-HHMMSS>.md` and state the absolute path to the user.
+7. Delegate to **architect-dev-lead-reviewer** for an isolated pass if needed — same template and save step.
+## Helper scripts
+- `scripts/git-diff-branches.sh <base> <head> [outfile]`
+- `scripts/save-code-review-report.sh '<base>' '<head>'` (stdin = full report markdown)