🤖 Forge Code Review

Plug-and-play AI pull request review for GitHub and Bitbucket, with audit sync to Jira, ClickUp, or GitHub Issues, built on Alibaba Open Code Review (OCR).

For a shared CLI/CI rollout, see the organization setup guide: pinned policies, repository onboarding, advisory gates, finding tracking and feedback, acceptance checklists, exported dashboards, and saved-output evaluation.

OCR does the review itself: it picks the files, groups related files, runs a sub-agent per group that can read and search the repo, places comments on the right lines, and filters out weak ones. Forge Code Review adds what a team needs around it:

| OCR provides | Forge Code Review adds | |---|---| | Agent-based diff review with line-accurate comments | Inline PR comments + summary on GitHub and Bitbucket | | Built-in per-language rules (Go, Java, TS/JS, Python, PHP, Rust, ...) | An enterprise rule library (OWASP, CWE Top 25, race conditions, business logic, PII, supply chain, frameworks) compiled into OCR's rule.json | | Many LLM providers (Anthropic, OpenAI, Gemini, OpenRouter, Bedrock, DeepSeek, Ollama, ...) | One config.json for provider, rules, gates, and tickets, with no ocr config setup in CI | | JSON / SARIF output | Severity gate (commit status + exit code), category filters, Handlebars comment templates | | | Jira / ClickUp / GitHub Issues audit comments and status transitions | | | init that scaffolds config, rules, and CI workflow for any repo |

PR opened ─▶ CI ─▶ forge-code-review review
                     ├─ compile .forge-code-review/rules/**.md ─▶ OCR rule.json
                     ├─ ocr review --from origin/<base> --to <head> --rule … --background-file …
                     ├─ severity / category policy ─▶ pass / fail gate
                     ├─ GitHub or Bitbucket: inline comments, summary, commit status
                     └─ Jira / ClickUp / GitHub Issues: audit comment (+ optional transition)

🚀 Quick start

Prerequisites: Node.js ≥ 18, Git ≥ 2.41, and an OpenAI-, OpenAI Responses- or Anthropic-compatible LLM endpoint.

# 1. Scaffold config, rule library, comment template and CI workflow
npx @knackforge-soft-solutions/forge-code-review init --scm github --ticket jira

# 2. Point it at your LLM and check the OCR CLI, LLM, and SCM / ticket credentials
export LLM_URL=https://gateway.example.com/v1
export LLM_TOKEN=sk-...
export LLM_MODEL=auto/best-coding
export LLM_PROTOCOL=openai   # or openai-responses / anthropic
npx @knackforge-soft-solutions/forge-code-review test-connection

# 3. Review your branch locally without posting anything
npx @knackforge-soft-solutions/forge-code-review review --provider local --from origin/main --dry-run

Then commit .forge-code-review/ and the generated workflow, and add the secrets listed by init to your CI.

To pin the version per project, install it as a dev dependency. The package then provides the forge-code-review command and its short alias forge-review:

npm install --save-dev --save-exact @knackforge-soft-solutions/forge-code-review
npx forge-review review --provider local --dry-run

Projects set up before the rebrand still work: if .forge-code-review/ is missing, the legacy .autocodereview/ folder is read instead.

The Open Code Review CLI is a pinned dependency (@alibaba-group/open-code-review), so you don't need to install it separately.

⚙️ Configuration (.forge-code-review/config.json)

{
  "scm": {
    "provider": "github",
    "inlineComments": true,
    "summaryComment": true,
    "severityThreshold": "medium",
    "setCommitStatus": true,
    "failOnSeverity": "critical"
  },
  "ticket": {
    "provider": "jira",
    "autoDetectFromBranch": true,
    "pattern": "([A-Z][A-Z0-9]{1,9}-\\d+)",
    "postAudit": true,
    "transitionOnBlockers": false,
    "blockerTransitionName": "In Progress"
  },
  "llm": { "provider": "llm" },
  "ocr": { "effort": "medium", "concurrency": 8, "timeoutMinutes": 15, "maxTokensBudget": 0 },
  "review": {
    "exclude": ["**/*.lock", "**/*.min.*"],
    "include": [],
    "categories": ["security", "bug", "performance", "architecture", "maintainability", "testing", "other"],
    "customPromptPath": ".forge-code-review/prompt.md",
    "rulesDir": ".forge-code-review/rules",
    "commentTemplatePath": ".forge-code-review/templates/comment.hbs",
    "disabledRules": [],
    "mergeSystemRules": true
  }
}

| Section | Key | Default | Description | |---|---|---|---| | scm | provider | local | github, bitbucket, local (auto-detected in CI) | | | inlineComments / summaryComment | true | Post line comments / a summary comment | | | severityThreshold | medium | Findings below this are dropped | | | failOnSeverity | high | Gate fails at or above: critical, high, medium, none | | | setCommitStatus | true | Commit status / build status on the head commit | | ticket | provider | none | jira, clickup, github, none | | | pattern | provider-specific | Regex to find a ticket ID; Jira keys, ClickUp CU-… / #…, or GitHub #123 | | | postAudit / transitionOnBlockers | true / false | Post the audit; move the ticket when the gate fails | | llm | provider | llm | llm (generic endpoint from LLM_* env vars), ollama, any OCR built-in provider, or ocr | | | model | – | Model ID; LLM_MODEL overrides it | | | apiBaseUrl / protocol | – | Endpoint base URL and protocol; LLM_URL / LLM_PROTOCOL override them | | | apiKeyEnvVar | – | Read the token from a differently named env var instead of LLM_TOKEN | | ocr | effort | OCR default (medium) | Review rounds: low 1, medium 2, high 3 | | | concurrency | 8 | Parallel sub-agents | | | timeoutMinutes | 15 | Per-subtask budget | | | maxTokensBudget | 0 | Total token cap per run (0 = unlimited) | | | maxTokens, language, noFilter, binaryPath, extraArgs | – | Passed through to ocr review | | review | exclude | lockfiles, minified | Extra globs OCR must not review (OCR already skips binaries, vendored code, build output, tests, and secret files) | | | include | [] | Globs that bypass OCR's default exclusions. Not a whitelist; Forge still excludes test files | | | categories | all but style, documentation | Only report these categories | | | disabledRules | [] | Rulebook IDs or paths to skip | | | mergeSystemRules | true | Keep OCR's built-in language rules under the rulebooks |

LLM setup (LLM_* environment variables)

By default ("llm": { "provider": "llm" }), the LLM is configured entirely through four environment variables, so the same config.json works with any gateway:

| Variable | Required | Example | Notes | |---|---|---|---| | LLM_URL | yes | https://gateway.example.com/v1 | Base URL ending in /v1, for every protocol. Requests go to /v1/chat/completions (openai), /v1/responses (openai-responses) or /v1/messages (anthropic) | | LLM_TOKEN | yes | sk-... | Sent as a Bearer token. Keep it in CI secrets or a git-ignored .env | | LLM_MODEL | yes | auto/best-coding | Must support tool calling | | LLM_PROTOCOL | no | openai | openai (Chat Completions, default), openai-responses (Responses API), anthropic (Messages API) |

Setting LLM_URL always selects this mode, even if llm.provider names something else. A .env file in the project root is loaded automatically, which is handy for local runs (it is already in .gitignore):

# .env
LLM_URL=https://gateway.example.com/v1
LLM_TOKEN=sk-...
LLM_MODEL=auto/best-coding
LLM_PROTOCOL=openai-responses

Other llm.provider values:

| llm.provider | Credentials | |---|---| | ollama | none; apiBaseUrl defaults to http://localhost:11434/v1 | | anthropic, openai, gemini / google, openrouter, deepseek, bedrock, ... | OCR built-in provider with its standard key variable (ANTHROPIC_API_KEY, OPENAI_API_KEY, ...). See OCR providers | | chatgpt | Your ChatGPT plan via forge-code-review auth login (local only, see below) | | ocr | Your own ~/.opencodereview/config.json / OCR_LLM_* env, unchanged (local use) |

Forge Code Review runs OCR with a temporary, isolated OCR home, so config.json decides the LLM and your personal ~/.opencodereview is never modified (except with ocr).

💻 Review with your own subscription (Claude Code, Codex, ChatGPT)

Developers can review locally with the AI subscription they already have, without an API key. CI keeps using the LLM_* gateway.

These modes are for one developer on their own machine. Subscription credentials must not be used on shared CI runners. Forge refuses chatgpt when it detects CI.

Claude Code / Codex (delegation mode)

Open Code Review picks the files and resolves the rules per file. Your agent does the review with its own model, and Forge publishes the result like any other review.

# once per project (commit the result), or with --global for your user only
npx @knackforge-soft-solutions/forge-code-review agent install --claude --codex

Then, inside the repo:

• Claude Code: /forge-review (or "review my branch with forge review")
• Codex: $forge-review (or pick it from /skills)

The skill runs three steps, which you can also run by hand:

| Step | Command | What happens | |---|---|---| | 1. Prepare | forge-code-review delegate | Writes .forge-code-review/.delegate/brief.md: files to review, the exact git diff command per file, the compiled rule group per file (built-in + company rulebooks), PR background, and the findings JSON contract. No LLM call. | | 2. Review | (the agent) | Reviews every listed file and writes .forge-code-review/.delegate/findings.json. | | 3. Publish | forge-code-review publish --findings .forge-code-review/.delegate/findings.json [--provider bitbucket] [--dry-run] | Same pipeline as review: severity / category policy, inline comments, summary, commit status, Jira / ClickUp audit. |

Notes:

• Scope: delegate reviews the current branch against origin's default branch. Use --from <ref>, --commit <sha> or --workspace (uncommitted changes) to change it.
• Publishing from a laptop: publish --provider github|bitbucket reads the repo from the origin remote, finds the open PR for the current branch (or pass --pr-id), and needs GITHUB_TOKEN or BITBUCKET_TOKEN in your shell or .env. Push the branch first so comments land on the right lines.
• .forge-code-review/.delegate/ is git-ignored.
• publish also accepts a saved ocr review --format json result.

ChatGPT plan (llm.provider: "chatgpt")

Uses OCR's "Sign in with ChatGPT" preview: the normal review command, but billed to your ChatGPT plan through OpenAI's Responses API. This is a separate sign-in, not your Codex CLI session.

npx @knackforge-soft-solutions/forge-code-review auth login     # opens the browser once (--no-browser prints a URL)
npx @knackforge-soft-solutions/forge-code-review auth status

"llm": { "provider": "chatgpt", "model": "gpt-6-luna" }

• model is optional; without it, the account's default model is used. Run npx @alibaba-group/open-code-review llm models to list what your account can use. LLM_MODEL / LLM_URL are ignored in this mode.
• Credentials stay in ~/.opencodereview/auth. Forge links them into its isolated OCR home for each run and never copies them.
• Eligibility, models and limits are decided by OpenAI. See OCR's ChatGPT preview notes.

📚 Rule library (.forge-code-review/rules/**/*.md)

init installs Markdown rulebooks. Each rule has an ID and a severity, and OCR is told to start comments with the matching ID ([ENT-CWE208] …), so findings link back to your standard.

| File | ID | Applies to | Covers | |---|---|---|---| | security.md | security-owasp | all files | OWASP Top 10 (SEC-A01…SEC-A10) | | enterprise-security.md | enterprise-security | all files | CWE-208 timing attacks, prototype pollution, state machines, price tampering, idempotency, money precision, PII in logs, DTOs, tenant isolation, ReDoS, zip bombs, pagination, IMDS / SSRF, pre-signed URLs, mass assignment, GraphQL | | race-conditions.md | race-conditions | all files | TOCTOU, atomic updates / SELECT … FOR UPDATE, transactions, distributed locks, async and thread races, queue idempotency, cache stampede | | performance.md | performance | all files | N+1, unbounded queries, indexes, event-loop blocking, leaks, timeouts, rendering | | code-quality.md | code-quality | all files | Null and error handling, logic errors, backward compatibility, layering, tests | | supply-chain.md | supply-chain | manifests, CI files | Typosquatting, unpinned deps, lifecycle scripts, pipeline integrity | | frameworks/*.md | fw-node, fw-react, fw-python, fw-php, fw-java, fw-go, fw-flutter, fw-sql, fw-infra | matching files | Express / NestJS / Prisma, React / Next.js, Django / FastAPI, Laravel / WordPress, Spring / JPA, Go, Flutter, migrations, Docker / K8s / Terraform |

How rules reach OCR

OCR picks one rule entry per file (first match wins). forge-code-review compiles the rulebooks into a rule.json where each entry already contains every rulebook that applies:

1. Entries from your hand-written .opencodereview/rule.json (if any) come first, with the universal rulebooks appended.
2. One entry per scoped glob, most specific first (for example, **/app/**/route.ts gets the Next.js and Node rulebooks).
3. A **/* catch-all with the universal rulebooks.

With mergeSystemRules: true (the default), each entry sets merge_system_rule, so OCR's built-in language rules stay in place underneath.

npx @knackforge-soft-solutions/forge-code-review rules check src/payments/service.go   # exact rule text OCR will use for a file
npx @knackforge-soft-solutions/forge-code-review rules compile --out .opencodereview/rule.json   # same rules for plain `ocr` and OCR IDE / agent plugins

Writing your own rulebook

---
id: payments
title: Payments Team Standards
appliesTo: ["src/payments/**", "**/*billing*"]
---
# Payments Rules
- **PAY-01 Ledger writes — `critical`:** Every balance change writes a ledger entry in the same transaction.

• No appliesTo means the rulebook applies to every file.
• Turn a rulebook off with enabled: false in its frontmatter, or list it in review.disabledRules.
• HTML comments (<!-- -->) are stripped, so you can leave notes for your team.
• Universal rulebooks are added to every file's prompt. Disable the ones you don't need to save tokens.

Project context (prompt.md)

.forge-code-review/prompt.md is passed to OCR as review background (--background-file), together with the PR title, branch, and description. Use it for your stack, domain, auth model, house rules, and known exceptions.

🔄 CI/CD

GitHub Actions

init --scm github writes .github/workflows/code-review.yml. It checks out the PR head with full history (OCR needs the merge-base), runs forge-code-review review --provider github, and uploads forge-review-summary.json.

The CLI filters PR destinations using scm.destinationBranches (default: release/prod, master, and main); the workflow listens to all destination branches so configuration can extend that list. New pushes trigger synchronize; PR edits also trigger a run so destination changes are checked. The CLI uses the last completed PR summary to review newly committed changes and skips an unchanged head when the destination and policy are unchanged. Keep scm.summaryComment enabled. Existing repositories must merge these changes into their committed workflow; updating the CLI does not replace it.

Secrets: LLM_URL and LLM_TOKEN; variables: LLM_MODEL and optionally LLM_PROTOCOL; plus ticket credentials if used. GITHUB_TOKEN is provided automatically.

Draft PRs and fork PRs are skipped, because forks don't receive secrets.

Bitbucket Pipelines

init --scm bitbucket writes bitbucket-pipelines.yml (or a snippet to merge if you already have one). The PR pipeline starts when a PR is opened or new commits are pushed to its source branch. Forge reviews only destinations in scm.destinationBranches (default: release/prod, master, and main); other destinations skip before fetching PR refs, running AI, or posting comments. Bitbucket's pull-requests patterns match source branches, so the destination check happens in the CLI.

It uses clone: depth: full and runs forge-code-review review --provider bitbucket without a manual range or --jira-key. Forge reads the PR's current source commit and last completed review marker: the first review covers the full PR, later reviews cover newly committed changes, and an unchanged head skips review. Changed history, destination, or review policy can require a full review. Keep scm.summaryComment enabled so completed reviews save the baseline. Jira-key discovery exclusions do not apply to this CI path.

Existing repositories must merge the updated snippet into their committed pipeline; updating the CLI package alone does not replace pipeline YAML. Pipelines must be enabled and credentials configured in Bitbucket. Commit messages containing [skip ci] or [ci skip] suppress automatic runs.

Secured repository variables:

| Variable | Description | |---|---| | BITBUCKET_TOKEN | Repository access token with Pull requests: Write (or BITBUCKET_USERNAME + BITBUCKET_APP_PASSWORD) | | LLM_URL, LLM_TOKEN, LLM_MODEL, LLM_PROTOCOL | LLM endpoint (see LLM setup) | | JIRA_URL, JIRA_EMAIL, JIRA_API_TOKEN | When ticket.provider = jira | | CLICKUP_API_TOKEN | When ticket.provider = clickup |

Configuring CI destination branches

Set exact branch names in .forge-code-review/config.json. Omit the setting to use release/prod, master, and main. An explicit non-empty list replaces the defaults; include them when adding another branch:

{
  "scm": {
    "destinationBranches": ["release/prod", "master", "main", "develop"]
  }
}

This filter applies to automatic GitHub/Bitbucket PR reviews in CI. Local reviews and Jira-key discovery retain their existing behavior. Branch patterns such as release/* are not supported. Disallowed destinations exit successfully without running review or creating a review artifact. Both workflow templates leave destination selection to the CLI. Remove older hardcoded YAML branch filters when adopting this setting. Shared organization policies can also supply or lock scm.destinationBranches.

Other CI

Run the CLI with an explicit range and provider:

npx @knackforge-soft-solutions/forge-code-review review --provider local --from "origin/$TARGET_BRANCH" --to "$HEAD_SHA" --json forge-review-summary.json

The exit code is 1 when the gate fails or the review fails, so you can use it to block merges.

🎫 Ticket sync

The ticket ID is detected from ticket.pattern, searching the PR title, then the branch, then the PR description, then the PR comments (first match wins). For example, feature/PROJ-123-pay gives PROJ-123.

• Our own rule IDs and common acronyms (ENT-CWE208, UTF-8, SHA-256, HTTP-2, ...) are never mistaken for ticket keys, and Forge's own PR comments are ignored when scanning.
• For Jira, the detected key is verified to exist (and not visible = skipped). If no real ticket is found, ticket sync is skipped and the review still posts to the PR.
• Ticket problems (missing credentials, lookup or post failures) never fail the review; they show as notes in the CLI output, not in the PR.

The ticket gets one friendly review-status comment aimed at reviewers and QA: pass / changes-requested verdict, the PR link, a severity breakdown, the top findings, and next steps. Jira uses wiki markup; GitHub Issues and ClickUp use Markdown.

| Provider | Credentials | Behavior | |---|---|---| | Jira | JIRA_URL, JIRA_EMAIL, JIRA_API_TOKEN | Verifies the key, posts the status comment (wiki markup), optional transition to blockerTransitionName | | ClickUp | CLICKUP_API_TOKEN | Status comment on the task (CU-abc123 / #abc123) | | GitHub Issues | GITHUB_TOKEN | Status comment on #123 |

Reviewing a specific PR with --pr-id

forge-code-review review --pr-id 42 --provider bitbucket

Given a PR ID, Forge loads the PR from the SCM and uses it as the source of truth: it reads the source and target branches, head commit, title, description and comments, fetches both branches into the local clone, and reviews merge-base(target, head)..head — exactly the PR's own changes. It then posts inline comments and the summary to the PR, sets the commit status, and syncs the ticket as above. This works in CI and from a laptop (the branch need not be checked out, only reachable from origin). Fork PRs are not supported, since their head isn't on origin.

Without --pr-id, Forge finds the open PR for the current branch automatically.

Optional ticket requirements

Before AI analysis, Forge reads the detected ticket's description from the configured tracker: Jira (wiki text or Atlassian rich text), ClickUp (Markdown with a text fallback), or GitHub Issues (issue body in the PR repository). The description is also included in delegated review briefs. It works on the first review and is refreshed for subsequent reviews; no prior review is required.

For Jira, Forge also reads recent visible comments using the issue comments API. It selects up to 20 entries by creation date (newest first), excludes Forge Code Review comments and empty bodies, and presents the retained discussion oldest first with comment IDs, authors, creation/edit timestamps and links. Pagination is limited to three requests; each comment body is capped at 2,000 characters and the combined bodies at 12,000 characters. Reports mark omitted history, truncated text and comment-read failures as partial context. Comments are usable even when the description is empty.

The reviewer must distinguish explicit requirement updates and clarifications from developer implementation claims and ordinary discussion. A newer comment does not automatically override the description. Conflicts or unclear authority require clarification, and findings based on comments must cite their source alongside code evidence. Comment content is untrusted input, not permission to execute instructions or change review policy. Reading comments shares the existing lookup deadline; failures preserve the description and available comments, and normal review continues. ClickUp and GitHub issue comments are not fetched.

The reviewer receives the ticket ID, title, URL and description as untrusted requirement data. It is instructed to compare clear acceptance criteria with the changed implementation and relevant existing code, then report evidenced missing or incorrect behavior as Acceptance gap: findings with code evidence and suggested fixes. Ambiguous requirements and behavior requiring runtime checks must not be presented as proven defects. The normal security and bug review still runs.

Missing IDs, descriptions, comments, credentials, inaccessible tickets and lookup failures do not stop review. Tracker reads share an eight-second lookup deadline. Dry runs may read the tracker but never post or transition anything. ticket.postAudit: false disables audit posting, not requirements lookup. ticket.provider: "none" or autoDetectFromBranch: false disables automatic ticket context.

The CLI, PR summary and summary JSON report whether requirements context was supplied. This is context availability, not a per-criterion completion checklist or proof that all acceptance criteria passed. The existing severity/category policy still controls reported findings and the gate. Requirements in attachments or custom fields are not fetched; put the relevant criteria in the description. Descriptions longer than 16,000 characters are truncated with an explicit notice to the reviewer. Publishing saved findings does not reassess them against the fetched description; regenerate the review when requirements change.

🎨 Comment templates (templates/comment.hbs)

Inline comments are rendered with Handlebars. Output is Markdown and is not HTML-escaped, so code stays intact.

Available variables: filePath, line, startLine, severity, category, title, description, impact, existingCode, suggestedFix, ruleId.

Helpers: uppercase, severityEmoji, gt.

On GitHub, multi-line findings are posted as multi-line review comments, so a suggestion block replaces the whole range. Findings that can't be placed on a diff line appear in the summary comment only.

📖 CLI reference

| Command | Description | |---|---| | init [--scm] [--ticket] [--llm] [--model] [--agent claude,codex] [--force] [--skip-workflow] | Scaffold .forge-code-review/, a CI workflow and optional agent skills; existing files are kept unless --force | | review [options] | Review and publish (see below) | | publish --findings <file> [review options] | Publish findings written by a coding agent | | delegate [--from] [--to] [--commit] [--workspace] [-q] | Write the delegated review brief for Claude Code / Codex | | agent install [--claude] [--codex] [--global] [--force] | Install the forge-review skill | | auth login \| status \| logout | Sign in with ChatGPT for llm.provider: "chatgpt" | | rules compile [--out <file>] | Print or write the compiled OCR rule.json | | rules check <files...> | Show the exact rule OCR applies to each file | | validate | Validate config and list loaded rulebooks | | test-connection | Check OCR CLI, LLM (ocr llm test), SCM and ticket credentials |

review options:

| Option | Description | |---|---| | -c, --config <path> | Config file (default .forge-code-review/config.json) | | -p, --provider <name> | Where to publish: github, bitbucket, local | | --from <ref> / --to <ref> | Review merge-base(from, to)..to (CI sets these automatically) | | --commit <sha> | Head commit for statuses; in local mode without --from, reviews that single commit | | --pr-id <id> | Review a specific pull request (loads its branches, title, description, comments). --pr is an alias | | --jira-key <key> | Find an associated open Bitbucket PR, review it with Jira requirements, and attach its URL on Jira | | --full-review | Ignore the last reviewed commit and reassess the complete PR | | --advisory | Report findings without enforcing the merge gate; organization policy still applies | | --owner, --repo, --branch, --title | Override detected PR context | | --json <path> | Write the review summary as JSON | | --dry-run | Review, print, and post nothing | | --effort <level> | Override review depth for this run: low (one round), medium (two), high (three) |

Without --from or --commit, local mode reviews your working tree (staged, unstaged, and untracked).

Repeat PR reviews

For automatic Bitbucket and GitHub PR reviews, each completed PR summary records a visible Reviewed commit and a machine-readable completion marker. The next forge-review review reads that marker from the PR, so local runs and CI share the baseline:

• First run, or no usable marker: review the full PR diff.
• New commits: review only the delta from the last reviewed commit to the current PR head. Surrounding code and ticket requirements remain context.
• Same head: skip the AI call and all external writes, preserving the previous gate result.
• Missing baseline commit, rewritten history, a changed destination, or changed merge-base: fall back to the full PR.

The marker is posted last, after analysis and configured SCM status publication. A completed review with blocking findings still records its head. Failed analysis, skipped/partial analysis or reviewer warnings do not advance the baseline. Dry runs never persist a marker. Disabling scm.summaryComment prevents new checkpoints. Old summaries without markers cause one full review before incremental reviews begin.

Incremental summaries describe new changes, not approval of the entire PR. Earlier findings are not automatically resolved. Tracked findings in changed files are explicitly rechecked; other blockers remain open. A full review can reassess all earlier findings:

forge-review review --full-review
forge-review review --jira-key PROJ-123 --full-review

Use --full-review when requirements or review rules change without a new commit, or when you want a fresh overall assessment. Manual --from / --to / --commit ranges and publishing saved findings do not use or advance automatic checkpoints. Standalone delegated briefs retain their explicitly selected range.

Review a Jira ticket's PR

Run from a checkout of the Bitbucket repository with Jira and Bitbucket credentials configured:

npx forge-review review --jira-key PROJ-123 --dry-run
npx forge-review review --jira-key PROJ-123

--jira-key selects Jira for this run and overrides ticket detection from PR text, even when autodetection is disabled. Discovery searches the current repository (or --owner / --repo) for exact key mentions in open PR titles, descriptions and source branches, plus Bitbucket PR web links stored on the Jira issue. It excludes destinations release/prod, master, and main; it does not remove existing PRs or links. Jira's development panel is not queried. PRs visible only there need a key mention, a Jira web link, or an explicit --pr-id.

If several eligible PRs match, the command lists them and asks for --pr-id <id>. This explicitly associates that PR with the supplied key even if its text does not mention the ticket. The PR must still be open and target an eligible branch. No match, inaccessible ticket, incomplete discovery, or a mismatched checkout stops selection before reviewing. Search does not span repositories or select by assignee. The PR's source and destination are fetched and its head commit drives the review; local working-tree changes are not the target. Range overrides and saved findings cannot be combined with --jira-key.

The ticket description and recent Jira comments supply optional requirements as usual; an empty description does not block review. After analysis, a normal run creates or updates a Jira web link to the selected PR using a stable global ID. This is a Jira remote issue link, not a new development-panel integration. Linking is independent of audit-comment settings and never changes assignees. Link failures appear in run notices and do not discard review results. --dry-run performs reads and local ref fetching but makes no external writes.

Review speed and comment detail

Use a single review round for quicker feedback:

npx forge-review review --provider local --from origin/main --effort low --dry-run

--effort low|medium|high overrides ocr.effort for that run: one, two, or three review rounds. The configured depth remains unchanged when omitted. One round reduces review work but can miss issues that further rounds would catch. Comment filtering and severity gates still apply. Set ocr.effort to low in your config if you want this for CI too. Actual runtime also depends on the model, provider limits, diff size, and repository searches.

Ticket lookup and diff loading run concurrently. AI analysis starts as soon as optional ticket lookup finishes, while diff loading can continue. Dry runs and reviews with inline comments disabled skip diff loading for anchoring. Reading requirements adds no separate AI call.

Review instructions ask for descriptive Markdown comments covering why the code fails, when it fails, impact, the suggested approach, why that approach helps and its limitations, and how to verify. These instructions also reach delegated coding agents. Inline comments, the CLI, and PR summaries show full finding details; replacement code is included when the reviewer supplies a safe change for the exact line range. Existing custom templates still control inline formatting. Model adherence requires checking real review output; the formatter cannot supply explanations absent from the findings.

Comments begin with What is wrong, explaining the visible problem for product owners and QA before technical details. The agent is instructed to rephrase its analysis into short paragraphs with bold labels and blank lines before submitting, preserving evidence and uncertainty. This happens within the review pass, without another model call. Bitbucket inline comments use Markdown footers and fenced replacement code; legacy template <sub> footers and GitHub suggestion fences are converted before posting. Jira status formatting is unchanged.

Inline review guidance also requires severity reasoning tied to the actual impact, an explicit requested action, a concrete failure scenario and expected verification result, and one finding per underlying problem. The agent must distinguish confirmed behavior from unverified consequences and anchor each comment to the smallest relevant changed range. Ranges spanning separate diff hunks remain in the summary. Default comment templates put the problem title first and label replacement code with its exact line range. These are instructions to the reviewer; semantic grouping and explanation quality still depend on the model's output.

Test files are excluded from OCR selection and delegated briefs, and findings on test files are dropped before gating or publishing, including imported findings. This covers test/, tests/, __tests__/, integration_test/, e2e/, and common test filenames such as *.test.*, *.spec.*, *_test.*, and test_*.*. These exclusions apply even to existing configs with an empty review.exclude. Tests can still be read as evidence for a production-code issue.

🛠️ Programmatic API

import { loadConfig, ReviewEngine, type CodeReviewer } from '@knackforge-soft-solutions/forge-code-review';

const project = loadConfig(process.cwd());
const engine = new ReviewEngine(project, { dryRun: true });
const summary = await engine.runReview({
  provider: 'local',
  repoOwner: 'acme',
  repoName: 'billing',
  diffRange: { from: 'origin/main', to: 'HEAD' }
});
console.log(summary.passed, summary.findings);

ReviewEngine accepts customReviewer (any CodeReviewer), customScmAdapter, and customTicketAdapter. Use them to plug in another review backend, SCM, or tracker.

🔍 Troubleshooting

| Symptom | Fix | |---|---| | review failed (authentication, HTTP 401) | Wrong or missing LLM key for llm.provider | | Cannot find merge-base | Shallow clone: use fetch-depth: 0 (GitHub) or clone: depth: full plus fetching the destination branch (Bitbucket) | | A file isn't reviewed | OCR skipped it (tests, vendored code, unsupported extension). Add it to review.include, and run ocr review --preview to see the reasons | | A rule doesn't seem to apply | npx @knackforge-soft-solutions/forge-code-review rules check <file> | | Comments only in the summary | The finding's lines aren't part of the PR diff |

📄 License

MIT. Open Code Review is Apache-2.0 © Alibaba.