@fro.bot/systematic 2.2.0 → 2.2.1

package/skills/ce-compound-refresh/references/schema.yaml

@@ -0,0 +1,222 @@
+# Documentation schema for learnings written by ce:compound
+# Treat this as the canonical frontmatter contract for docs/solutions/.
+#
+# The schema has two tracks based on problem_type:
+#   Bug track  — problem_type is a defect or failure (build_error, test_failure, etc.)
+#   Knowledge track — problem_type is guidance or practice (best_practice, workflow_issue, etc.)
+#
+# Both tracks share the same required core fields. The tracks differ in which
+# additional fields are required vs optional (see track_rules below).
+
+# --- Track classification ---------------------------------------------------
+tracks:
+  bug:
+    description: "Defects, failures, and errors that were diagnosed and fixed"
+    problem_types:
+      - build_error
+      - test_failure
+      - runtime_error
+      - performance_issue
+      - database_issue
+      - security_issue
+      - ui_bug
+      - integration_issue
+      - logic_error
+  knowledge:
+    description: "Best practices, workflow improvements, patterns, and documentation"
+    problem_types:
+      - best_practice
+      - documentation_gap
+      - workflow_issue
+      - developer_experience
+
+# --- Fields required by BOTH tracks -----------------------------------------
+required_fields:
+  module:
+    type: string
+    description: "Module or area affected"
+
+  date:
+    type: string
+    pattern: '^\d{4}-\d{2}-\d{2}$'
+    description: "Date documented (YYYY-MM-DD)"
+
+  problem_type:
+    type: enum
+    values:
+      - build_error
+      - test_failure
+      - runtime_error
+      - performance_issue
+      - database_issue
+      - security_issue
+      - ui_bug
+      - integration_issue
+      - logic_error
+      - developer_experience
+      - workflow_issue
+      - best_practice
+      - documentation_gap
+    description: "Primary category — determines track (bug vs knowledge)"
+
+  component:
+    type: enum
+    values:
+      - rails_model
+      - rails_controller
+      - rails_view
+      - service_object
+      - background_job
+      - database
+      - frontend_stimulus
+      - hotwire_turbo
+      - email_processing
+      - brief_system
+      - assistant
+      - authentication
+      - payments
+      - development_workflow
+      - testing_framework
+      - documentation
+      - tooling
+    description: "Component involved"
+
+  severity:
+    type: enum
+    values:
+      - critical
+      - high
+      - medium
+      - low
+    description: "Impact severity"
+
+# --- Track-specific rules ----------------------------------------------------
+track_rules:
+  bug:
+    required:
+      symptoms:
+        type: array[string]
+        min_items: 1
+        max_items: 5
+        description: "Observable symptoms such as errors or broken behavior"
+      root_cause:
+        type: enum
+        values:
+          - missing_association
+          - missing_include
+          - missing_index
+          - wrong_api
+          - scope_issue
+          - thread_violation
+          - async_timing
+          - memory_leak
+          - config_error
+          - logic_error
+          - test_isolation
+          - missing_validation
+          - missing_permission
+          - missing_workflow_step
+          - inadequate_documentation
+          - missing_tooling
+          - incomplete_setup
+        description: "Fundamental technical cause of the problem"
+      resolution_type:
+        type: enum
+        values:
+          - code_fix
+          - migration
+          - config_change
+          - test_fix
+          - dependency_update
+          - environment_setup
+          - workflow_improvement
+          - documentation_update
+          - tooling_addition
+          - seed_data_update
+        description: "Type of fix applied"
+
+  knowledge:
+    optional:
+      applies_when:
+        type: array[string]
+        max_items: 5
+        description: "Conditions or situations where this guidance applies"
+      symptoms:
+        type: array[string]
+        max_items: 5
+        description: "Observable gaps or friction that prompted this guidance (optional for knowledge track)"
+      root_cause:
+        type: enum
+        values:
+          - missing_association
+          - missing_include
+          - missing_index
+          - wrong_api
+          - scope_issue
+          - thread_violation
+          - async_timing
+          - memory_leak
+          - config_error
+          - logic_error
+          - test_isolation
+          - missing_validation
+          - missing_permission
+          - missing_workflow_step
+          - inadequate_documentation
+          - missing_tooling
+          - incomplete_setup
+        description: "Underlying cause, if there is a specific one (optional for knowledge track)"
+      resolution_type:
+        type: enum
+        values:
+          - code_fix
+          - migration
+          - config_change
+          - test_fix
+          - dependency_update
+          - environment_setup
+          - workflow_improvement
+          - documentation_update
+          - tooling_addition
+          - seed_data_update
+        description: "Type of change, if applicable (optional for knowledge track)"
+
+# --- Fields optional for BOTH tracks ----------------------------------------
+optional_fields:
+  related_components:
+    type: array[string]
+    description: "Other components involved"
+
+  tags:
+    type: array[string]
+    max_items: 8
+    description: "Search keywords, lowercase and hyphen-separated"
+
+# --- Fields optional for bug track only -------------------------------------
+bug_optional_fields:
+  rails_version:
+    type: string
+    pattern: '^\d+\.\d+\.\d+$'
+    description: "Rails version in X.Y.Z format. Only relevant for bug-track docs."
+
+# --- Backward compatibility --------------------------------------------------
+# Docs created before the track system was introduced may have bug-track
+# fields (symptoms, root_cause, resolution_type) on knowledge-type
+# problem_types. These are valid legacy docs:
+#   - Bug-track fields present on a knowledge-track doc are harmless. Do not
+#     strip them during refresh unless the doc is being rewritten for other reasons.
+#   - When creating NEW docs, follow the track rules above.
+
+# --- Validation rules --------------------------------------------------------
+validation_rules:
+  - "Determine track from problem_type using the tracks section above"
+  - "All shared required_fields must be present"
+  - "Bug-track required fields (symptoms, root_cause, resolution_type) must be present on bug-track docs"
+  - "Knowledge-track docs have no additional required fields beyond the shared ones"
+  - "Bug-track fields on existing knowledge-track docs are harmless (see backward compatibility note)"
+  - "Track-specific optional fields may be included but are not required"
+  - "Enum fields must match allowed values exactly"
+  - "Array fields must respect min_items/max_items when specified"
+  - "date must match YYYY-MM-DD format"
+  - "rails_version, if provided, must match X.Y.Z format and only applies to bug-track docs"
+  - "tags should be lowercase and hyphen-separated"

package/skills/ce-compound-refresh/references/yaml-schema.md

@@ -0,0 +1,87 @@
+# YAML Frontmatter Schema
+
+`schema.yaml` in this directory is the canonical contract for `docs/solutions/` frontmatter written by `ce:compound`.
+
+Use this file as the quick reference for:
+- required fields
+- enum values
+- validation expectations
+- category mapping
+- track classification (bug vs knowledge)
+
+## Tracks
+
+The `problem_type` determines which **track** applies. Each track has different required and optional fields.
+
+| Track | problem_types | Description |
+|-------|--------------|-------------|
+| **Bug** | `build_error`, `test_failure`, `runtime_error`, `performance_issue`, `database_issue`, `security_issue`, `ui_bug`, `integration_issue`, `logic_error` | Defects and failures that were diagnosed and fixed |
+| **Knowledge** | `best_practice`, `documentation_gap`, `workflow_issue`, `developer_experience` | Practices, patterns, workflow improvements, and documentation |
+
+## Required Fields (both tracks)
+
+- **module**: Module or area affected
+- **date**: ISO date in `YYYY-MM-DD`
+- **problem_type**: One of the values listed in the Tracks table above
+- **component**: One of `rails_model`, `rails_controller`, `rails_view`, `service_object`, `background_job`, `database`, `frontend_stimulus`, `hotwire_turbo`, `email_processing`, `brief_system`, `assistant`, `authentication`, `payments`, `development_workflow`, `testing_framework`, `documentation`, `tooling`
+- **severity**: One of `critical`, `high`, `medium`, `low`
+
+## Bug Track Fields
+
+Required:
+- **symptoms**: YAML array with 1-5 observable symptoms (errors, broken behavior)
+- **root_cause**: One of `missing_association`, `missing_include`, `missing_index`, `wrong_api`, `scope_issue`, `thread_violation`, `async_timing`, `memory_leak`, `config_error`, `logic_error`, `test_isolation`, `missing_validation`, `missing_permission`, `missing_workflow_step`, `inadequate_documentation`, `missing_tooling`, `incomplete_setup`
+- **resolution_type**: One of `code_fix`, `migration`, `config_change`, `test_fix`, `dependency_update`, `environment_setup`, `workflow_improvement`, `documentation_update`, `tooling_addition`, `seed_data_update`
+
+## Knowledge Track Fields
+
+No additional required fields beyond the shared ones. All fields below are optional:
+
+- **applies_when**: Conditions or situations where this guidance applies
+- **symptoms**: Observable gaps or friction that prompted this guidance
+- **root_cause**: Underlying cause, if there is a specific one
+- **resolution_type**: Type of change, if applicable
+
+## Optional Fields (both tracks)
+
+- **related_components**: Other components involved
+- **tags**: Search keywords, lowercase and hyphen-separated
+
+## Optional Fields (bug track only)
+
+- **rails_version**: Rails version in `X.Y.Z` format
+
+## Backward Compatibility
+
+Docs created before the track system may have `symptoms`/`root_cause`/`resolution_type` on knowledge-type problem_types. These are valid legacy docs:
+
+- Bug-track fields present on a knowledge-track doc are harmless. Do not strip them during refresh unless the doc is being rewritten for other reasons.
+- When creating **new** docs, follow the track rules above.
+
+## Category Mapping
+
+- `build_error` -> `docs/solutions/build-errors/`
+- `test_failure` -> `docs/solutions/test-failures/`
+- `runtime_error` -> `docs/solutions/runtime-errors/`
+- `performance_issue` -> `docs/solutions/performance-issues/`
+- `database_issue` -> `docs/solutions/database-issues/`
+- `security_issue` -> `docs/solutions/security-issues/`
+- `ui_bug` -> `docs/solutions/ui-bugs/`
+- `integration_issue` -> `docs/solutions/integration-issues/`
+- `logic_error` -> `docs/solutions/logic-errors/`
+- `developer_experience` -> `docs/solutions/developer-experience/`
+- `workflow_issue` -> `docs/solutions/workflow-issues/`
+- `best_practice` -> `docs/solutions/best-practices/`
+- `documentation_gap` -> `docs/solutions/documentation-gaps/`
+
+## Validation Rules
+
+1. Determine the track from `problem_type` using the Tracks table.
+2. All shared required fields must be present.
+3. Bug-track required fields (`symptoms`, `root_cause`, `resolution_type`) must be present on bug-track docs.
+4. Knowledge-track docs have no additional required fields beyond the shared ones.
+5. Bug-track fields on existing knowledge-track docs are harmless (see Backward Compatibility).
+6. Enum fields must match the allowed values exactly.
+7. Array fields must respect min/max item counts.
+8. `date` must match `YYYY-MM-DD`.
+9. `rails_version`, if present, must match `X.Y.Z` and only applies to bug-track docs.

package/skills/ce-review/references/diff-scope.md

@@ -0,0 +1,31 @@
+# Diff Scope Rules
+
+These rules apply to every reviewer. They define what is "your code to review" versus pre-existing context.
+
+## Scope Discovery
+
+Determine the diff to review using this priority order:
+
+1. **User-specified scope.** If the caller passed `BASE:`, `FILES:`, or `DIFF:` markers, use that scope exactly.
+2. **Working copy changes.** If there are unstaged or staged changes (`git diff HEAD` is non-empty), review those.
+3. **Unpushed commits vs base branch.** If the working copy is clean, review `git diff $(git merge-base HEAD <base>)..HEAD` where `<base>` is the default branch (main or master).
+
+The scope step in the SKILL.md handles discovery and passes you the resolved diff. You do not need to run git commands yourself.
+
+## Finding Classification Tiers
+
+Every finding you report falls into one of three tiers based on its relationship to the diff:
+
+### Primary (directly changed code)
+
+Lines added or modified in the diff. This is your main focus. Report findings against these lines at full confidence.
+
+### Secondary (immediately surrounding code)
+
+Unchanged code within the same function, method, or block as a changed line. If a change introduces a bug that's only visible by reading the surrounding context, report it -- but note that the issue exists in the interaction between new and existing code.
+
+### Pre-existing (unrelated to this diff)
+
+Issues in unchanged code that the diff didn't touch and doesn't interact with. Mark these as `"pre_existing": true` in your output. They're reported separately and don't count toward the review verdict.
+
+**The rule:** If you'd flag the same issue on an identical diff that didn't include the surrounding file, it's pre-existing. If the diff makes the issue *newly relevant* (e.g., a new caller hits an existing buggy function), it's secondary.

package/skills/ce-review/references/findings-schema.json

@@ -0,0 +1,129 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Code Review Findings",
+  "description": "Structured output schema for code review sub-agents",
+  "type": "object",
+  "required": ["reviewer", "findings", "residual_risks", "testing_gaps"],
+  "properties": {
+    "reviewer": {
+      "type": "string",
+      "description": "Persona name that produced this output (e.g., 'correctness', 'security')"
+    },
+    "findings": {
+      "type": "array",
+      "description": "List of code review findings. Empty array if no issues found.",
+      "items": {
+        "type": "object",
+        "required": [
+          "title",
+          "severity",
+          "file",
+          "line",
+          "why_it_matters",
+          "autofix_class",
+          "owner",
+          "requires_verification",
+          "confidence",
+          "evidence",
+          "pre_existing"
+        ],
+        "properties": {
+          "title": {
+            "type": "string",
+            "description": "Short, specific issue title. 10 words or fewer.",
+            "maxLength": 100
+          },
+          "severity": {
+            "type": "string",
+            "enum": ["P0", "P1", "P2", "P3"],
+            "description": "Issue severity level"
+          },
+          "file": {
+            "type": "string",
+            "description": "Relative file path from repository root"
+          },
+          "line": {
+            "type": "integer",
+            "description": "Primary line number of the issue",
+            "minimum": 1
+          },
+          "why_it_matters": {
+            "type": "string",
+            "description": "Impact and failure mode -- not 'what is wrong' but 'what breaks'"
+          },
+          "autofix_class": {
+            "type": "string",
+            "enum": ["safe_auto", "gated_auto", "manual", "advisory"],
+            "description": "Reviewer's conservative recommendation for how this issue should be handled after synthesis"
+          },
+          "owner": {
+            "type": "string",
+            "enum": ["review-fixer", "downstream-resolver", "human", "release"],
+            "description": "Who should own the next action for this finding after synthesis"
+          },
+          "requires_verification": {
+            "type": "boolean",
+            "description": "Whether any fix for this finding must be re-verified with targeted tests or a follow-up review pass"
+          },
+          "suggested_fix": {
+            "type": ["string", "null"],
+            "description": "Concrete minimal fix. Omit or null if no good fix is obvious -- a bad suggestion is worse than none."
+          },
+          "confidence": {
+            "type": "number",
+            "description": "Reviewer confidence in this finding, calibrated per persona",
+            "minimum": 0.0,
+            "maximum": 1.0
+          },
+          "evidence": {
+            "type": "array",
+            "description": "Code-grounded evidence: snippets, line references, or pattern descriptions. At least 1 item.",
+            "items": { "type": "string" },
+            "minItems": 1
+          },
+          "pre_existing": {
+            "type": "boolean",
+            "description": "True if this issue exists in unchanged code unrelated to the current diff"
+          }
+        }
+      }
+    },
+    "residual_risks": {
+      "type": "array",
+      "description": "Risks the reviewer noticed but could not confirm as findings",
+      "items": { "type": "string" }
+    },
+    "testing_gaps": {
+      "type": "array",
+      "description": "Missing test coverage the reviewer identified",
+      "items": { "type": "string" }
+    }
+  },
+
+  "_meta": {
+    "confidence_thresholds": {
+      "suppress": "Below 0.60 -- do not report. Finding is speculative noise. Exception: P0 findings at 0.50+ may be reported.",
+      "flag": "0.60-0.69 -- include only when the issue is clearly actionable with concrete evidence.",
+      "confident": "0.70-0.84 -- real and important. Report with full evidence.",
+      "certain": "0.85-1.00 -- verifiable from the code alone. Report."
+    },
+    "severity_definitions": {
+      "P0": "Critical breakage, exploitable vulnerability, data loss/corruption. Must fix before merge.",
+      "P1": "High-impact defect likely hit in normal usage, breaking contract. Should fix.",
+      "P2": "Moderate issue with meaningful downside (edge case, perf regression, maintainability trap). Fix if straightforward.",
+      "P3": "Low-impact, narrow scope, minor improvement. User's discretion."
+    },
+    "autofix_classes": {
+      "safe_auto": "Local, deterministic code or test fix suitable for the in-skill fixer. Examples: extract duplicated helper, add missing nil check, fix off-by-one, add missing test, remove dead code. Do not default to advisory when a concrete safe fix exists.",
+      "gated_auto": "Concrete fix exists, but it changes behavior, permissions, contracts, or other sensitive areas that deserve explicit approval. Examples: add auth to unprotected endpoint, change API response shape.",
+      "manual": "Actionable issue that requires design decisions or cross-cutting changes. Examples: redesign data model, add pagination strategy, choose between architectural approaches.",
+      "advisory": "Informational or operational item that should be surfaced in the report only. Examples: design asymmetry the PR improves but does not fully resolve, residual risk notes, deployment considerations."
+    },
+    "owners": {
+      "review-fixer": "The in-skill fixer can own this when policy allows.",
+      "downstream-resolver": "Turn this into residual work for later resolution.",
+      "human": "A person must make a judgment call before code changes should continue.",
+      "release": "Operational or rollout follow-up; do not convert into code-fix work automatically."
+    }
+  }
+}

package/skills/ce-review/references/persona-catalog.md

@@ -0,0 +1,67 @@
+# Persona Catalog
+
+17 reviewer personas organized into always-on, cross-cutting conditional, and stack-specific conditional layers, plus CE-specific agents. The orchestrator uses this catalog to select which reviewers to spawn for each review.
+
+## Always-on (4 personas + 2 CE agents)
+
+Spawned on every review regardless of diff content.
+
+**Persona agents (structured JSON output):**
+
+| Persona | Agent | Focus |
+|---------|-------|-------|
+| `correctness` | `systematic:review:correctness-reviewer` | Logic errors, edge cases, state bugs, error propagation, intent compliance |
+| `testing` | `systematic:review:testing-reviewer` | Coverage gaps, weak assertions, brittle tests, missing edge case tests |
+| `maintainability` | `systematic:review:maintainability-reviewer` | Coupling, complexity, naming, dead code, premature abstraction |
+| `project-standards` | `systematic:review:project-standards-reviewer` | AGENTS.md and AGENTS.md compliance -- frontmatter, references, naming, cross-platform portability, tool selection |
+
+**CE agents (unstructured output, synthesized separately):**
+
+| Agent | Focus |
+|-------|-------|
+| `systematic:review:agent-native-reviewer` | Verify new features are agent-accessible |
+| `systematic:research:learnings-researcher` | Search docs/solutions/ for past issues related to this PR's modules and patterns |
+
+## Conditional (8 personas)
+
+Spawned when the orchestrator identifies relevant patterns in the diff. The orchestrator reads the full diff and reasons about selection -- this is agent judgment, not keyword matching.
+
+| Persona | Agent | Select when diff touches... |
+|---------|-------|---------------------------|
+| `security` | `systematic:review:security-reviewer` | Auth middleware, public endpoints, user input handling, permission checks, secrets management |
+| `performance` | `systematic:review:performance-reviewer` | Database queries, ORM calls, loop-heavy data transforms, caching layers, async/concurrent code |
+| `api-contract` | `systematic:review:api-contract-reviewer` | Route definitions, serializer/interface changes, event schemas, exported type signatures, API versioning |
+| `data-migrations` | `systematic:review:data-migrations-reviewer` | Migration files, schema changes, backfill scripts, data transformations |
+| `reliability` | `systematic:review:reliability-reviewer` | Error handling, retry logic, circuit breakers, timeouts, background jobs, async handlers, health checks |
+| `adversarial` | `systematic:review:adversarial-reviewer` | Diff has >=50 changed non-test, non-generated, non-lockfile lines, OR touches auth, payments, data mutations, external API integrations, or other high-risk domains |
+| `cli-readiness` | `systematic:review:cli-readiness-reviewer` | CLI command definitions, argument parsing, CLI framework usage, command handler implementations |
+| `previous-comments` | `systematic:review:previous-comments-reviewer` | **PR-only.** Reviewing a PR that has existing review comments or review threads from prior review rounds. Skip entirely when no PR metadata was gathered in Stage 1. |
+
+## Stack-Specific Conditional (5 personas)
+
+These reviewers keep their original opinionated lens. They are additive with the cross-cutting personas above, not replacements for them.
+
+| Persona | Agent | Select when diff touches... |
+|---------|-------|---------------------------|
+| `dhh-rails` | `systematic:review:dhh-rails-reviewer` | Rails architecture, service objects, authentication/session choices, Hotwire-vs-SPA boundaries, or abstractions that may fight Rails conventions |
+| `kieran-rails` | `systematic:review:kieran-rails-reviewer` | Rails controllers, models, views, jobs, components, routes, or other application-layer Ruby code where clarity and conventions matter |
+| `kieran-python` | `systematic:review:kieran-python-reviewer` | Python modules, endpoints, services, scripts, or typed domain code |
+| `kieran-typescript` | `systematic:review:kieran-typescript-reviewer` | TypeScript components, services, hooks, utilities, or shared types |
+| `julik-frontend-races` | `systematic:review:julik-frontend-races-reviewer` | Stimulus/Turbo controllers, DOM event wiring, timers, async UI flows, animations, or frontend state transitions with race potential |
+
+## CE Conditional Agents (migration-specific)
+
+These CE-native agents provide specialized analysis beyond what the persona agents cover. Spawn them when the diff includes database migrations, schema.rb, or data backfills.
+
+| Agent | Focus |
+|-------|-------|
+| `systematic:review:schema-drift-detector` | Cross-references schema.rb changes against included migrations to catch unrelated drift |
+| `systematic:review:deployment-verification-agent` | Produces Go/No-Go deployment checklist with SQL verification queries and rollback procedures |
+
+## Selection rules
+
+1. **Always spawn all 4 always-on personas** plus the 2 CE always-on agents.
+2. **For each cross-cutting conditional persona**, the orchestrator reads the diff and decides whether the persona's domain is relevant. This is a judgment call, not a keyword match.
+3. **For each stack-specific conditional persona**, use file types and changed patterns as a starting point, then decide whether the diff actually introduces meaningful work for that reviewer. Do not spawn language-specific reviewers just because one config or generated file happens to match the extension.
+4. **For CE conditional agents**, spawn when the diff includes migration files (`db/migrate/*.rb`, `db/schema.rb`) or data backfill scripts.
+5. **Announce the team** before spawning with a one-line justification per conditional reviewer selected.

package/skills/ce-review/references/resolve-base.sh

@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+# Resolve the review base branch and compute the merge-base for ce:review.
+# Handles fork-safe remote resolution, PR metadata, and multi-fallback detection.
+#
+# Usage: bash references/resolve-base.sh
+# Output: BASE:<sha> on success, ERROR:<message> on failure.
+#
+# Detects the base branch from (in priority order):
+# 1. PR metadata (base ref + base repo for fork safety)
+# 2. origin/HEAD symbolic ref
+# 3. gh repo view defaultBranchRef
+# 4. Common branch names: main, master, develop, trunk
+
+set -euo pipefail
+
+REVIEW_BASE_BRANCH=""
+PR_BASE_REPO=""
+PR_BASE_REMOTE=""
+BASE_REF=""
+
+# Step 1: Try PR metadata (handles fork workflows)
+if command -v gh >/dev/null 2>&1; then
+  PR_META=$(gh pr view --json baseRefName,url 2>/dev/null || true)
+  if [ -n "$PR_META" ]; then
+    REVIEW_BASE_BRANCH=$(echo "$PR_META" | jq -r '.baseRefName // empty' 2>/dev/null || true)
+    PR_BASE_REPO=$(echo "$PR_META" | jq -r '.url // empty' 2>/dev/null | sed -n 's#https://github.com/\([^/]*/[^/]*\)/pull/.*#\1#p' || true)
+  fi
+fi
+
+# Step 2: Fall back to origin/HEAD
+if [ -z "$REVIEW_BASE_BRANCH" ]; then
+  REVIEW_BASE_BRANCH=$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's#^origin/##' || true)
+fi
+
+# Step 3: Fall back to gh repo view
+if [ -z "$REVIEW_BASE_BRANCH" ] && command -v gh >/dev/null 2>&1; then
+  REVIEW_BASE_BRANCH=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name' 2>/dev/null || true)
+fi
+
+# Step 4: Fall back to common branch names
+if [ -z "$REVIEW_BASE_BRANCH" ]; then
+  for candidate in main master develop trunk; do
+    if git rev-parse --verify "origin/$candidate" >/dev/null 2>&1 || git rev-parse --verify "$candidate" >/dev/null 2>&1; then
+      REVIEW_BASE_BRANCH="$candidate"
+      break
+    fi
+  done
+fi
+
+# Resolve the base ref from the correct remote (fork-safe)
+if [ -n "$REVIEW_BASE_BRANCH" ]; then
+  if [ -n "$PR_BASE_REPO" ]; then
+    PR_BASE_REMOTE=$(git remote -v | awk "index(\$2, \"github.com:$PR_BASE_REPO\") || index(\$2, \"github.com/$PR_BASE_REPO\") {print \$1; exit}")
+    if [ -n "$PR_BASE_REMOTE" ]; then
+      git rev-parse --verify "$PR_BASE_REMOTE/$REVIEW_BASE_BRANCH" >/dev/null 2>&1 || git fetch --no-tags "$PR_BASE_REMOTE" "$REVIEW_BASE_BRANCH:refs/remotes/$PR_BASE_REMOTE/$REVIEW_BASE_BRANCH" 2>/dev/null || git fetch --no-tags "$PR_BASE_REMOTE" "$REVIEW_BASE_BRANCH" 2>/dev/null || true
+      BASE_REF=$(git rev-parse --verify "$PR_BASE_REMOTE/$REVIEW_BASE_BRANCH" 2>/dev/null || true)
+    fi
+  fi
+  if [ -z "$BASE_REF" ]; then
+    # Only try origin if it exists as a remote; otherwise skip to avoid
+    # confusing errors in fork setups where origin points at the user's fork.
+    if git remote get-url origin >/dev/null 2>&1; then
+      git rev-parse --verify "origin/$REVIEW_BASE_BRANCH" >/dev/null 2>&1 || git fetch --no-tags origin "$REVIEW_BASE_BRANCH:refs/remotes/origin/$REVIEW_BASE_BRANCH" 2>/dev/null || git fetch --no-tags origin "$REVIEW_BASE_BRANCH" 2>/dev/null || true
+      BASE_REF=$(git rev-parse --verify "origin/$REVIEW_BASE_BRANCH" 2>/dev/null || true)
+    fi
+    # Fall back to a bare local ref only if remote resolution failed
+    if [ -z "$BASE_REF" ]; then
+      BASE_REF=$(git rev-parse --verify "$REVIEW_BASE_BRANCH" 2>/dev/null || true)
+    fi
+  fi
+fi
+
+# Compute merge-base
+if [ -n "$BASE_REF" ]; then
+  BASE=$(git merge-base HEAD "$BASE_REF" 2>/dev/null) || BASE=""
+  if [ -z "$BASE" ] && [ "$(git rev-parse --is-shallow-repository 2>/dev/null || echo false)" = "true" ]; then
+    if git remote get-url origin >/dev/null 2>&1; then
+      git fetch --no-tags --unshallow origin 2>/dev/null || true
+      BASE=$(git merge-base HEAD "$BASE_REF" 2>/dev/null) || BASE=""
+    fi
+    if [ -z "$BASE" ] && [ -n "$PR_BASE_REMOTE" ] && [ "$PR_BASE_REMOTE" != "origin" ]; then
+      git fetch --no-tags --unshallow "$PR_BASE_REMOTE" 2>/dev/null || true
+      BASE=$(git merge-base HEAD "$BASE_REF" 2>/dev/null) || BASE=""
+    fi
+  fi
+else
+  BASE=""
+fi
+
+if [ -n "$BASE" ]; then
+  echo "BASE:$BASE"
+else
+  echo "ERROR:Unable to resolve review base branch locally. Fetch the base branch and rerun, or provide a PR number so the review scope can be determined from PR metadata."
+fi