smart-commit-copilot-cli 0.1.12 → 0.1.14

package/CHANGELOG.md

@@ -6,6 +6,41 @@ The format is based on Keep a Changelog, and this project follows Semantic Versi
 
 ## [Unreleased]
 
+## [0.1.14] - 2026-06-18
+
+### Added
+
+- `smart-commit pull-request review <url>` for reviewing existing GitHub pull requests or GitLab merge requests from a web URL
+- `pullRequestReview.*` configuration for threshold, severity filters, auto-approve, auto-merge, skip-on-pass behavior, skill prompt tuning, and optional local override files
+- chunked PR/MR diff review with aggregated scoring, localized fallback summaries, and diff-aware inline comment anchoring
+- summary and inline comment publishing, including update-in-place for existing Smart Commit summary comments
+- `pull-request-review` schema target and structured JSON output for comment, approve, and merge action state
+- expanded output language support for `de`, `fr`, `es`, `it`, `pt`, `tr`, `id`, `hi`, `ru`, `ko`, and `ja`
+- localized user-facing PR review messages for unanchored inline findings
+- regression coverage for PR/MR URL parsing, review API helpers, comment rendering, publish gating, merge gating, chunked aggregation, and review workflow behavior
+
+### Changed
+
+- the shared review engine now supports chunked execution through `diffReviewRunner` for large remote diffs
+- README, configuration, contracts, integrations, getting-started, and verification docs now describe PR/MR review automation
+- publish guidance now points to the `0.1.14` release draft during pre-publish review
+
+## [0.1.13] - 2026-05-26
+
+### Added
+
+- `smart-commit commit-message generate` for standalone commit-message resolution without review, commit, push, pass-history, summaries, or PR/MR creation
+- `report generate --period custom --start-date YYYY-MM-DD --end-date YYYY-MM-DD` for inclusive natural-day report windows
+- `commit-message-generate` schema target and structured branch comparison `commits` data for PR/MR creation
+- regression coverage for commit-message generate, custom report periods, single-commit PR title fallback, and related CLI contracts
+
+### Changed
+
+- PR/MR creation reuses the sole compare-range commit subject as the title when `pullRequest.titlePrompt` is empty and exactly one commit is present
+- GitHub and GitLab compare commit parsing now share structured subject/body formatting helpers
+- README, configuration, contracts, and verification docs now describe `commit-message generate` and custom report periods
+- publish guidance now points to the `0.1.13` release draft during pre-publish review
+
 ## [0.1.12] - 2026-05-25
 
 ### Added

package/README.md

@@ -14,6 +14,7 @@ It can:
 
 - inspect staged changes
 - run AI review and gate on the result
+- review existing GitHub pull requests or GitLab merge requests by URL
 - generate or validate commit messages
 - retry malformed review or commit-message responses with configurable correction passes
 - use bundled review skills, including `c-code-review`, with diff-aware generic fallback
@@ -22,6 +23,7 @@ It can:
 - generate staged change summaries after successful review, commit, or push flows
 - auto-create GitHub PRs or GitLab MRs after a successful push when configured
 - create or dry-run PR/MR content through standalone `pull-request create`
+- review existing PR/MR URLs through standalone `pull-request review`
 - persist successful run history in pass history
 - generate local or AI-enhanced daily, yesterday, weekly, last-week, monthly, last-month, quarterly, last-quarter, or yearly Markdown work reports
 
@@ -59,18 +61,21 @@ At a high level, `smart-commit bridge` does this:
 | Commit | Only when review passes and `git.autoCommit=true` | Creates a local Git commit with the final commit message. | New local commit. |
 | Push | Only when commit succeeds and `git.autoPush=true` | Pushes the current branch to its configured upstream. | Remote branch update, or a push-phase runtime error. |
 | Staged change summary | Only after a successful review-only, commit-only, or push run when `stagedChangeSummary.enabled=true` | Writes a Markdown summary for the reviewed staged change. | Markdown file under the configured summary directory. |
-| PR/MR auto-create | Only after a successful push when `pullRequest.autoCreateAfterPush=true` | Creates or detects an existing GitHub pull request or GitLab merge request. | `pullRequestCreation` details in bridge JSON output. |
+| PR/MR auto-create | Only after a successful push when `pullRequestCreation.autoCreateAfterPush=true` | Creates or detects an existing GitHub pull request or GitLab merge request. | `pullRequestCreation` details in bridge JSON output. |
 | Pass history | Only when `passHistory.enabled=true` and the configured `passHistory.writeStage` is reached | Records or upgrades the successful run to the furthest completed stage. | Local pass-history record for later reporting. |
 
 Optional follow-up commands:
 
 ```bash
+smart-commit commit-message generate --repo . --config ./smart-commit.json
 smart-commit pull-request create --repo . --config ./smart-commit.json --target-branch main --dry-run
 smart-commit pull-request create --repo . --config ./smart-commit.json --target-branch main
+smart-commit pull-request review https://github.com/org/repo/pull/123 --config ./smart-commit.json --dry-run
 smart-commit report generate --repo . --config ./smart-commit.json --period weekly
+smart-commit report generate --repo . --config ./smart-commit.json --period custom --start-date 2026-04-01 --end-date 2026-04-09
 ```
 
-`smart-commit pull-request create` is an independent PR/MR command. `smart-commit report generate` summarizes existing pass-history records; it is not part of every `bridge` run.
+`smart-commit commit-message generate` resolves only the commit-message portion of the workflow. `smart-commit pull-request create` is an independent PR/MR command. `smart-commit pull-request review` reviews an existing PR/MR URL and can publish comments, approve, or merge based on config. `smart-commit report generate` summarizes existing pass-history records; it is not part of every `bridge` run.
 
 ## Prerequisites
 
@@ -85,7 +90,9 @@ Before you run the CLI, make sure you have:
 Important command requirements:
 
 - `smart-commit bridge` requires `--repo`
+- `smart-commit commit-message generate` requires `--repo`
 - `smart-commit report generate` requires `--repo`
+- `smart-commit pull-request review` requires a pull request or merge request URL
 - `smart-commit config resolve` does not require `--repo`
 - `smart-commit config resolve` can validate config structure without a complete connection block
 - `smart-commit bridge` requires a valid connection configuration
@@ -307,7 +314,7 @@ Use this when you want a more realistic team default without enabling automatic
     "passHistory": {
       "enabled": true,
       "writeStage": "review_passed",
-      "dirPath": ".smart-commit-cli",
+      "outputDirPath": ".smart-commit-cli",
       "maxEntries": 3000
     },
     "output": {
@@ -394,7 +401,7 @@ For first use, do not copy those values blindly. Start with `false` for both and
     "passHistory": {
       "enabled": true,
       "writeStage": "review_passed",
-      "dirPath": ".smart-commit-cli",
+      "outputDirPath": ".smart-commit-cli",
       "maxEntries": 3000
     },
     "reporting": {
@@ -415,10 +422,14 @@ For first use, do not copy those values blindly. Start with `false` for both and
       "prompt": ""
     },
     "pullRequest": {
-      "autoCreateAfterPush": false,
-      "targetBranch": "",
       "provider": "auto",
       "apiBaseUrl": "",
+      "authToken": "env:SMART_COMMIT_PULL_REQUEST_AUTH_TOKEN"
+    },
+    "pullRequestCreation": {
+      "autoCreateAfterPush": false,
+      "configFilePath": "",
+      "targetBranch": "",
       "titlePrompt": "",
       "descriptionPrompt": "",
       "maxDiffChars": 200000,
@@ -428,8 +439,18 @@ For first use, do not copy those values blindly. Start with `false` for both and
       "milestone": "",
       "draft": false,
       "removeSourceBranch": false,
-      "skipBranches": ["main", "master", "develop"],
-      "authToken": "env:SMART_COMMIT_PULL_REQUEST_AUTH_TOKEN"
+      "skipBranches": ["main", "master", "develop"]
+    },
+    "pullRequestReview": {
+      "configFilePath": "",
+      "threshold": 6,
+      "autoApprove": true,
+      "autoMerge": false,
+      "summarySeverities": ["P0", "P1", "P2"],
+      "commentSeverities": ["P0", "P1"],
+      "skillPromptTuning": "",
+      "skipSummaryOnPass": true,
+      "skipCommentOnPass": true
     },
     "output": {
       "format": "json",
@@ -547,6 +568,15 @@ smart-commit pull-request create --repo . --config ./smart-commit.json --target-
 
 Use `--dry-run` to compare branches and generate PR/MR content without creating it. The auth token is only used for GitHub/GitLab API headers and is redacted from config output and error text.
 
+### I want to review an existing PR or MR
+
+```bash
+SMART_COMMIT_PULL_REQUEST_AUTH_TOKEN=... \
+smart-commit pull-request review https://github.com/org/repo/pull/123 --config ./smart-commit.json
+```
+
+This command reads the remote PR/MR, runs review against its diff, and can publish inline comments, approve, or merge when configured. Use `--dry-run` to keep it read-only for platform actions.
+
 ### I want machine-readable schemas
 
 ```bash
@@ -558,8 +588,10 @@ Supported schema targets:
 - `config-file`
 - `config-resolve`
 - `bridge`
+- `commit-message-generate`
 - `report-generate`
 - `pull-request-create`
+- `pull-request-review`
 
 Examples:
 
@@ -567,8 +599,10 @@ Examples:
 smart-commit schema print --target config-file
 smart-commit schema print --target config-resolve
 smart-commit schema print --target bridge
+smart-commit schema print --target commit-message-generate
 smart-commit schema print --target report-generate
 smart-commit schema print --target pull-request-create
+smart-commit schema print --target pull-request-review
 ```
 
 ## Core Commands Reference
@@ -612,6 +646,12 @@ smart-commit bridge --repo . --config ./smart-commit.json
 smart-commit report generate --repo . --config ./smart-commit.json --period weekly
 ```
 
+### Review an existing PR or MR
+
+```bash
+smart-commit pull-request review https://github.com/org/repo/pull/123 --config ./smart-commit.json
+```
+
 ### Print a schema
 
 ```bash
@@ -667,6 +707,13 @@ Typical interpretation:
 - `3`: config error
 - `4`: runtime error
 
+### `commit-message generate`
+
+- `0`: success
+- `2`: blocked preflight, such as no changes or no staged diff with auto-stage disabled
+- `3`: config error
+- `4`: runtime error
+
 ## Configuration Rules
 
 Config precedence from high to low:
@@ -757,13 +804,16 @@ Pass history:
 --enable-pass-history <true|false>
 --pass-history-write-stage <review_passed|commit_completed|commit_push_completed>
 --pass-history-dir <path>
+--pass-history-output-dir <path>
 --pass-history-max-entries <number>
 ```
 
 Reporting:
 
 ```bash
---period <daily|yesterday|weekly|last-week|monthly|last-month|quarterly|last-quarter|yearly>
+--period <daily|yesterday|weekly|last-week|monthly|last-month|quarterly|last-quarter|yearly|custom>
+--start-date <YYYY-MM-DD>
+--end-date <YYYY-MM-DD>
 --report-language <zh-cn|zh-tw|en|...>
 --report-week-starts-on <monday|sunday>
 --report-output-dir <path>
@@ -773,7 +823,7 @@ Reporting:
 --no-report-ai
 ```
 
-`--period` belongs to `report generate`; it is not a global config override for `bridge`.
+`--period` belongs to `report generate`; it is not a global config override for `bridge`. Use `--period custom --start-date YYYY-MM-DD --end-date YYYY-MM-DD` for an inclusive natural-day range.
 
 Staged change summary:
 
@@ -816,6 +866,20 @@ Pull request / merge request:
 --pull-request-skip-branch <branch>
 ```
 
+Pull request review:
+
+```bash
+--pull-request-review-config-file <path1,path2,...>
+--pull-request-review-threshold <number>
+--pull-request-review-auto-approve <true|false>
+--pull-request-review-auto-merge <true|false>
+--pull-request-review-summary-severities <P0,P1,P2,P3>
+--pull-request-review-comment-severities <P0,P1,P2,P3>
+--pull-request-review-skill-prompt-tuning <text>
+--pull-request-review-skip-summary-on-pass <true|false>
+--pull-request-review-skip-comment-on-pass <true|false>
+```
+
 Repeat `--assignee`, `--reviewer`, `--label`, or `--skip-branch` to pass multiple values.
 
 ## Environment Variables Reference
@@ -872,6 +936,7 @@ SMART_COMMIT_PUSH_TIMEOUT_MS
 SMART_COMMIT_ENABLE_PASS_HISTORY
 SMART_COMMIT_PASS_HISTORY_WRITE_STAGE
 SMART_COMMIT_PASS_HISTORY_DIR
+SMART_COMMIT_PASS_HISTORY_OUTPUT_DIR
 SMART_COMMIT_PASS_HISTORY_MAX_ENTRIES
 ```
 
@@ -916,6 +981,21 @@ SMART_COMMIT_PULL_REQUEST_SKIP_BRANCHES
 SMART_COMMIT_PULL_REQUEST_AUTH_TOKEN
 ```
 
+Pull request review:
+
+```bash
+SMART_COMMIT_PULL_REQUEST_REVIEW_CONFIG_FILE
+SMART_COMMIT_PULL_REQUEST_REVIEW_CONFIG_FILE_PATH
+SMART_COMMIT_PULL_REQUEST_REVIEW_THRESHOLD
+SMART_COMMIT_PULL_REQUEST_REVIEW_AUTO_APPROVE
+SMART_COMMIT_PULL_REQUEST_REVIEW_AUTO_MERGE
+SMART_COMMIT_PULL_REQUEST_REVIEW_SUMMARY_SEVERITIES
+SMART_COMMIT_PULL_REQUEST_REVIEW_COMMENT_SEVERITIES
+SMART_COMMIT_PULL_REQUEST_REVIEW_SKILL_PROMPT_TUNING
+SMART_COMMIT_PULL_REQUEST_REVIEW_SKIP_SUMMARY_ON_PASS
+SMART_COMMIT_PULL_REQUEST_REVIEW_SKIP_COMMENT_ON_PASS
+```
+
 ## Reporting
 
 If `passHistory.enabled=true`, successful bridge runs are written to local history and can be summarized later:

package/docs/configuration.md

@@ -157,7 +157,7 @@ Recommended early team setup:
     "passHistory": {
       "enabled": true,
       "writeStage": "review_passed",
-      "dirPath": ".smart-commit-cli",
+      "outputDirPath": ".smart-commit-cli",
       "maxEntries": 3000
     },
     "output": {
@@ -303,10 +303,28 @@ These settings control local storage for successful run history.
 | --- | --- | --- | --- | --- |
 | `passHistory.enabled` | `false` | `true` if you want reporting later | Turn it on when you want local historical reporting | Forgetting to enable it and then expecting `report generate` to summarize past work |
 | `passHistory.writeStage` | `review_passed` | `review_passed` | Change it when you want pass-history records to start only after commit or push success | Assuming it changes the stored `eventType`, when it actually changes the earliest write point |
-| `passHistory.dirPath` | empty string | Leave empty first or set `.smart-commit-cli` explicitly | Change it only if you want a custom location | Thinking empty means broken, when it actually falls back to the repo-local default directory |
+| `passHistory.outputDirPath` | empty string | Leave empty first or set `.smart-commit-cli` explicitly | Change it only if you want a custom location | Thinking empty means broken, when it actually falls back to the repo-local default directory |
 | `passHistory.maxEntries` | `3000` | `3000` | Change it only if you need much shorter or longer retention | Setting it to `0` or a non-integer, which fails validation |
 
-If `passHistory.dirPath` is empty, the CLI automatically stores pass history under the repository's `.smart-commit-cli` directory.
+If `passHistory.outputDirPath` is empty, the CLI automatically stores pass history under the repository's `.smart-commit-cli` directory.
+
+### `pullRequestReview.*`
+
+These settings control the standalone `pull-request review` command.
+
+| Field | Built-in default | Recommended first value | When to change it | Common mistake |
+| --- | --- | --- | --- | --- |
+| `pullRequestReview.configFilePath` | empty string | Leave empty first, or point it at a comma-separated local fallback list | Change it when you want a local PR/MR review config file to override shared config | Putting shared PR auth fields here or expecting it to support `pullRequestReview.configFilePath` inside the local file |
+| `pullRequestReview.threshold` | `6` | `6` | Lower it if reviews block too often; raise it if you want stricter gating | Forgetting the pass rule is still score-based |
+| `pullRequestReview.autoApprove` | `true` | `true` | Disable it when you want review comments without approval side effects | Assuming it is only about UI decoration |
+| `pullRequestReview.autoMerge` | `false` | `false` | Enable it only when your platform flow and merge gate are ready | Assuming approval alone implies merge |
+| `pullRequestReview.summarySeverities` | `["P0", "P1", "P2"]` | Keep default first | Narrow it when you want the summary comment to focus on fewer severities | Expecting all severities to appear regardless of the filter |
+| `pullRequestReview.commentSeverities` | `["P0", "P1"]` | Keep default first | Broaden it when you want more inline noise | Assuming summary and inline filters are linked |
+| `pullRequestReview.skillPromptTuning` | empty string | Leave empty first | Add a short prompt tweak when the built-in review skill needs local context | Dropping in a full policy essay |
+| `pullRequestReview.skipSummaryOnPass` | `true` | `true` | Set `false` when you want a summary comment even on passing reviews | Expecting it to affect inline comments too |
+| `pullRequestReview.skipCommentOnPass` | `true` | `true` | Set `false` when you want inline comments even on passing reviews | Expecting it to affect the summary comment too |
+
+`pullRequestReview.configFilePath` accepts a comma-separated list of local file paths. The CLI picks the first existing file, then loads only `pullRequestReview` settings from it. The local file may use the canonical `smartCommitCli.pullRequestReview` shape or legacy `smartCommit.pullRequestReview*` keys, but it must not include shared connection or PR auth settings.
 
 `passHistory.writeStage` means "the earliest successful stage that is allowed to create a record." After a record exists, later successful stages update the same record instead of appending duplicates, so the stored `eventType` always shows the furthest successful stage reached by that run.
 
@@ -343,28 +361,38 @@ The generated summary uses only the reviewed staged diff, commit message, branch
 
 ### `pullRequest.*`
 
-These settings control GitHub pull request and GitLab merge request creation from the current branch.
+These settings are shared by PR/MR creation and PR/MR review.
 
 | Field | Built-in default | Recommended first value | When to change it | Common mistake |
 | --- | --- | --- | --- | --- |
-| `pullRequest.autoCreateAfterPush` | `false` | `false` first | Set `true` when `bridge` should create a PR/MR after a successful push | Expecting it to run when push is disabled or fails |
-| `pullRequest.targetBranch` | empty string | Your default integration branch | Set it in shared config when most branches target the same branch | Forgetting that `pull-request create` requires this value or `--target-branch` |
 | `pullRequest.provider` | `auto` | `auto` | Use `github` or `gitlab` when remote detection is ambiguous | Setting a provider that does not match the remote host |
 | `pullRequest.apiBaseUrl` | empty string | Leave empty for public GitHub/GitLab | Set it for GitHub Enterprise or self-managed GitLab | Including a trailing slash or a repository path instead of the API base |
-| `pullRequest.titlePrompt` | empty string | Leave empty first | Add short team guidance for generated PR/MR titles | Putting auth tokens, reviewer names, or process notes into the title prompt |
-| `pullRequest.descriptionPrompt` | empty string | Leave empty first | Add concise PR/MR template guidance | Asking it to invent tests, links, or approvals |
-| `pullRequest.maxDiffChars` | `200000` | `200000` | Lower it for very large repositories or slow models | Setting it below `1000`, which fails validation |
-| `pullRequest.assignees` | `[]` | `[]` | Set default assignees for created PRs/MRs | Assuming these are LLM prompt hints; they are sent to the provider API |
-| `pullRequest.reviewers` | `[]` | `[]` | Set default reviewers for created PRs/MRs | Assuming every provider accepts every reviewer identifier format |
-| `pullRequest.labels` | `[]` | `[]` | Apply standard labels during creation | Expecting missing provider labels to be created automatically |
-| `pullRequest.milestone` | empty string | Leave empty first | Set it when your provider project uses milestones | Using a display name where the provider expects an id |
-| `pullRequest.draft` | `false` | `false` | Set `true` when generated PRs/MRs should start as drafts | Expecting GitLab draft behavior to exactly match GitHub |
-| `pullRequest.removeSourceBranch` | `false` | `false` | Set `true` when accepted MRs should remove the source branch | Expecting GitHub to support this GitLab-only field |
-| `pullRequest.skipBranches` | `["main", "master", "develop"]` | Keep the defaults | Add protected branch names that should never auto-create PRs/MRs | Forgetting this only applies to source branch names |
 | `pullRequest.authToken` | empty string | `env:SMART_COMMIT_PULL_REQUEST_AUTH_TOKEN` | Set it when creating PRs/MRs through provider APIs | Hardcoding a token in committed config |
 
 PR/MR auth tokens are used only for provider API authentication headers. They are redacted from resolved config, generated content, LLM prompts, and visible error output.
 
+### `pullRequestCreation.*`
+
+These settings control GitHub pull request and GitLab merge request creation from the current branch.
+
+| Field | Built-in default | Recommended first value | When to change it | Common mistake |
+| --- | --- | --- | --- | --- |
+| `pullRequestCreation.autoCreateAfterPush` | `false` | `false` first | Set `true` when `bridge` should create a PR/MR after a successful push | Expecting it to run when push is disabled or fails |
+| `pullRequestCreation.configFilePath` | empty string | Leave empty first, or point it at a comma-separated local fallback list | Change it when you want a local PR/MR creation config file to override creation settings | Putting shared PR auth fields here or expecting it to support `pullRequestCreation.configFilePath` inside the local file |
+| `pullRequestCreation.targetBranch` | empty string | Your default integration branch | Set it when most branches target the same branch | Forgetting that `pull-request create` requires this value or `--target-branch` |
+| `pullRequestCreation.titlePrompt` | empty string | Leave empty first | Add short team guidance for generated PR/MR titles | Putting auth tokens, reviewer names, or process notes into the title prompt |
+| `pullRequestCreation.descriptionPrompt` | empty string | Leave empty first | Add concise PR/MR template guidance | Asking it to invent tests, links, or approvals |
+| `pullRequestCreation.maxDiffChars` | `200000` | `200000` | Lower it for very large repositories or slow models | Setting it below `1000`, which fails validation |
+| `pullRequestCreation.assignees` | `[]` | `[]` | Set default assignees for created PRs/MRs | Assuming these are LLM prompt hints; they are sent to the provider API |
+| `pullRequestCreation.reviewers` | `[]` | `[]` | Set default reviewers for created PRs/MRs | Assuming every provider accepts every reviewer identifier format |
+| `pullRequestCreation.labels` | `[]` | `[]` | Apply standard labels during creation | Expecting missing provider labels to be created automatically |
+| `pullRequestCreation.milestone` | empty string | Leave empty first | Set it when your provider project uses milestones | Using a display name where the provider expects an id |
+| `pullRequestCreation.draft` | `false` | `false` | Set `true` when generated PRs/MRs should start as drafts | Expecting GitLab draft behavior to exactly match GitHub |
+| `pullRequestCreation.removeSourceBranch` | `false` | `false` | Set `true` when accepted MRs should remove the source branch | Expecting GitHub to support this GitLab-only field |
+| `pullRequestCreation.skipBranches` | `["main", "master", "develop"]` | Keep the defaults | Add protected branch names that should never auto-create PRs/MRs | Forgetting this only applies to source branch names |
+
+`pullRequestCreation.configFilePath` accepts a comma-separated list of local file paths. The CLI picks the first existing file, then loads only `pullRequestCreation` settings from it. The local file may use the canonical `smartCommitCli.pullRequestCreation` shape or legacy `smartCommit.pullRequestCreation*` keys, but it must not include shared connection or PR auth settings.
+
 ### `output.*`
 
 These settings control how results are presented.
@@ -439,6 +467,8 @@ Most practical flags:
 --commit-language
 --commit-message-structure
 --commit-message
+--auto-generate-commit-message
+--hybrid-generate-commit-message
 --pass-history-write-stage
 --enable-staged-change-summary
 --staged-change-summary-language
@@ -453,6 +483,11 @@ Most practical flags:
 --pull-request-title-prompt
 --pull-request-description-prompt
 --pull-request-max-diff-chars
+--pull-request-review-threshold
+--pull-request-review-auto-approve
+--pull-request-review-auto-merge
+--pull-request-review-summary-severities
+--pull-request-review-comment-severities
 --assignee
 --reviewer
 --label
@@ -469,6 +504,8 @@ Common reporting flags:
 
 ```bash
 --period
+--start-date
+--end-date
 --report-language
 --report-output-dir
 --report-ai
@@ -505,6 +542,11 @@ SMART_COMMIT_PULL_REQUEST_API_BASE_URL
 SMART_COMMIT_PULL_REQUEST_TITLE_PROMPT
 SMART_COMMIT_PULL_REQUEST_DESCRIPTION_PROMPT
 SMART_COMMIT_PULL_REQUEST_MAX_DIFF_CHARS
+SMART_COMMIT_PULL_REQUEST_REVIEW_THRESHOLD
+SMART_COMMIT_PULL_REQUEST_REVIEW_AUTO_APPROVE
+SMART_COMMIT_PULL_REQUEST_REVIEW_AUTO_MERGE
+SMART_COMMIT_PULL_REQUEST_REVIEW_SUMMARY_SEVERITIES
+SMART_COMMIT_PULL_REQUEST_REVIEW_COMMENT_SEVERITIES
 SMART_COMMIT_PULL_REQUEST_ASSIGNEES
 SMART_COMMIT_PULL_REQUEST_REVIEWERS
 SMART_COMMIT_PULL_REQUEST_LABELS
@@ -555,6 +597,22 @@ Safest first run:
 smart-commit bridge --repo . --config ./smart-commit.json --no-commit --no-push
 ```
 
+### `commit-message generate`
+
+`commit-message generate` requires:
+
+- `--repo`
+- a valid repository path inside Git
+- staged changes, unless auto-stage makes input available
+- a valid connection configuration only when the command must call the model
+
+It resolves and validates the commit message only. It does not run review, create a commit, push, write pass history, generate staged-change summaries, or create PR/MR records.
+
+```bash
+smart-commit commit-message generate --repo . --config ./smart-commit.json
+smart-commit commit-message generate --repo . --commit-message "feat: keep provided message" --auto-generate-commit-message=false
+```
+
 ### `report generate`
 
 `report generate` requires:
@@ -573,8 +631,26 @@ Supported periods:
 - `quarterly`
 - `last-quarter`
 - `yearly`
+- `custom`
+
+If `--period` is omitted, it defaults to `weekly`. `yesterday` always uses the previous natural local day. For custom ranges, use `--period custom --start-date YYYY-MM-DD --end-date YYYY-MM-DD`; the range is inclusive by natural local day.
+
+### `pull-request review`
+
+`pull-request review` requires:
+
+- a GitHub pull request URL or GitLab merge request URL
+- `pullRequest.authToken`
+- a valid connection configuration
+
+It loads the remote PR/MR diff, reviews it with inline anchoring enabled, and may publish summary comments, inline comments, approvals, or merges according to `pullRequestReview.*`.
+
+```bash
+SMART_COMMIT_PULL_REQUEST_AUTH_TOKEN=... \
+smart-commit pull-request review https://github.com/org/repo/pull/123 --config ./smart-commit.json --dry-run
+```
 
-If `--period` is omitted, it defaults to `weekly`. `yesterday` always uses the previous natural local day.
+Use `--dry-run` for first checks. Dry-run still reads the PR/MR and runs the model review, but skips provider writes such as comments, approval, and merge.
 
 ## Validation Workflow
 

package/docs/contracts.md

@@ -8,8 +8,10 @@ For formal JSON Schema output, use:
 
 ```bash
 smart-commit schema print --target bridge
+smart-commit schema print --target commit-message-generate
 smart-commit schema print --target report-generate
 smart-commit schema print --target pull-request-create
+smart-commit schema print --target pull-request-review
 ```
 
 ## Shared Rules
@@ -38,6 +40,7 @@ Stable top-level fields:
 Use it to validate merged config before wiring `bridge` or `report generate` into automation.
 
 Contract consumers can safely read newly added resolved settings such as `config.connection.llmResponseCorrectionRetryCount`, `config.passHistory.writeStage`, `config.review.skill.id`, `config.commitMessage.structure`, and `config.stagedChangeSummary.enabled` from the returned `config` object.
+They can also read shared PR/MR settings from `config.pullRequest.provider`, `config.pullRequest.apiBaseUrl`, and `config.pullRequest.authToken`; creation settings from `config.pullRequestCreation.*`; and review settings such as `config.pullRequestReview.configFilePath`, `config.pullRequestReview.threshold`, `config.pullRequestReview.autoApprove`, `config.pullRequestReview.autoMerge`, `config.pullRequestReview.summarySeverities`, `config.pullRequestReview.commentSeverities`, `config.pullRequestReview.skillPromptTuning`, `config.pullRequestReview.skipSummaryOnPass`, and `config.pullRequestReview.skipCommentOnPass`.
 
 ## `bridge`
 
@@ -91,7 +94,7 @@ For example, when `passHistory.writeStage = "commit_completed"`, a successful lo
 
 `stagedChangeSummary` is always present in bridge output. When `stagedChangeSummary.enabled = true`, the CLI attempts generation only after the review/commit/push action for that run succeeds. Generation failures are reported in `stagedChangeSummary.error` and do not change the already successful bridge exit code.
 
-`pullRequestCreation` is always present in bridge output. When `pullRequest.autoCreateAfterPush = true`, the CLI attempts creation only after push succeeds and the source branch is not in `pullRequest.skipBranches`. Creation failures are reported in `pullRequestCreation.error` and do not change the already successful bridge exit code.
+`pullRequestCreation` is always present in bridge output. When `pullRequestCreation.autoCreateAfterPush = true`, the CLI attempts creation only after push succeeds and the source branch is not in `pullRequestCreation.skipBranches`. Creation failures are reported in `pullRequestCreation.error` and do not change the already successful bridge exit code.
 
 `pullRequestCreation.status` semantics:
 
@@ -132,15 +135,115 @@ Recommended automation behavior:
 - stop on `blocked` and surface `error.code` plus `summary`
 - fail on `error`
 
+## `pull-request review`
+
+Command:
+
+```bash
+SMART_COMMIT_PULL_REQUEST_AUTH_TOKEN=... \
+smart-commit pull-request review https://github.com/org/repo/pull/123 --config ./smart-commit.json
+```
+
+Stable top-level fields:
+
+- `schemaVersion`
+- `status`
+- `command`
+- `repositoryPath`
+- `url`
+- `platform`
+- `number`
+- `title`
+- `webUrl`
+- `isDraft`
+- `score`
+- `threshold`
+- `passed`
+- `reviewMode`
+- `chunkCount`
+- `summarySource`
+- `details`
+- `summaryCommentAction`
+- `inlineCommentAction`
+- `inlinePosted`
+- `inlineSkipped`
+- `inlineFailed`
+- `inlineUnanchored`
+- `approve`
+- `merge`
+- `warnings`
+- `logs`
+- `dryRun`
+- `config`
+- `summary`
+- `error`
+
+`status` semantics:
+
+- `passed`
+  The review completed and passed the configured threshold.
+- `blocked`
+  The review completed but did not pass the configured threshold.
+- `error`
+  Configuration or runtime validation failed.
+
+Recommended automation behavior:
+
+- use `--dry-run` for first validation
+- inspect `inlinePosted`, `inlineSkipped`, `inlineFailed`, and `inlineUnanchored` when publishing inline comments matters
+- inspect `approve` and `merge` before assuming the provider side effect happened
+- fail on `status: "error"`
+
+## `commit-message generate`
+
+Command:
+
+```bash
+smart-commit commit-message generate --repo /path/to/repo
+```
+
+This command resolves the final commit message without running review, commit, push, pass-history writes, staged-change summaries, or PR/MR creation.
+
+Stable top-level fields:
+
+- `schemaVersion`
+- `status`
+- `command`
+- `repositoryPath`
+- `branchName`
+- `commitMessage`
+- `commitMessageSource`
+- `commitMessageProvider`
+- `changedFiles`
+- `fullDiffChars`
+- `autoStaged`
+- `config`
+- `summary`
+- `error`
+
+`status` semantics:
+
+- `generated`
+  A commit message was generated from the staged diff.
+- `provided`
+  A provided commit message was validated and returned without model generation.
+- `hybrid`
+  A provided draft was refined by the model.
+- `blocked`
+  Preflight could not proceed because there were no changes or no staged diff.
+- `error`
+  Configuration or runtime validation failed.
+
 ## `report generate`
 
 Command:
 
 ```bash
 smart-commit report generate --repo /path/to/repo --period weekly
+smart-commit report generate --repo /path/to/repo --period custom --start-date 2026-04-01 --end-date 2026-04-09
 ```
 
-Supported `periodType` values are `daily`, `yesterday`, `weekly`, `last-week`, `monthly`, `last-month`, `quarterly`, `last-quarter`, and `yearly`.
+Supported `periodType` values are `daily`, `yesterday`, `weekly`, `last-week`, `monthly`, `last-month`, `quarterly`, `last-quarter`, `yearly`, and `custom`.
 
 Stable top-level fields:
 
@@ -149,6 +252,7 @@ Stable top-level fields:
 - `command`
 - `repositoryPath`
 - `periodType`
+- `periodSelection`
 - `passHistoryFilePath`
 - `outputFilePath`
 - `renderMode`

package/docs/getting-started.md

@@ -33,6 +33,7 @@ Important command requirements:
 
 - `bridge` requires `--repo`
 - `report generate` requires `--repo`
+- `pull-request review` requires a PR/MR URL
 - `config resolve` does not require `--repo`
 - `bridge` requires a valid connection config
 
@@ -284,6 +285,21 @@ smart-commit report generate --repo . --config ./smart-commit.json --period week
 
 If AI report generation fails, the CLI falls back to local Markdown generation automatically.
 
+## Optional: Review An Existing PR Or MR
+
+After the staged-change workflow is working, you can use the same review engine against a remote GitHub pull request or GitLab merge request.
+
+```bash
+export SMART_COMMIT_PULL_REQUEST_AUTH_TOKEN="your-provider-token"
+
+smart-commit pull-request review \
+  https://github.com/org/repo/pull/123 \
+  --config ./smart-commit.json \
+  --dry-run
+```
+
+Dry-run still reads the PR/MR and runs the model review, but it skips comments, approval, and merge. Remove `--dry-run` only after `pullRequestReview.*` and provider permissions are set the way you want.
+
 ## Suggested First Rollout
 
 For a new repository or team, use this order:
@@ -294,7 +310,8 @@ For a new repository or team, use this order:
 4. wire the same review-only command into Husky, Cursor hooks, or scripts
 5. enable pass history
 6. add reporting
-7. only then consider automatic commit or push
+7. optionally dry-run `pull-request review` against a test PR/MR
+8. only then consider automatic commit, push, approval, or merge automation
 
 This rollout keeps the first adoption phase safe while still validating the full workflow.