@ai-support-agent/cli 0.1.32 → 0.1.33-beta.1

package/dist/plugin/commands/add-feature.md

@@ -0,0 +1,301 @@
+---
+description: Implement a new feature through a disciplined, gated pipeline of plan approval and test-first development
+argument-hint: "[feature description / requirements / issue number]"
+resumable: true
+---
+
+# Add-feature pipeline
+
+Implement a new feature or a change in behavior through a disciplined, gated pipeline. Two things are non-negotiable:
+
+1. **Not one line of implementation code gets written until the user approves the plan.**
+2. **Every task is test-first (red → green → refactor).**
+
+Target feature: $ARGUMENTS
+
+## Scope
+
+- In scope: adding new features, changing existing behavior.
+- Out of scope: fixing broken behavior — use /fix-defect for that.
+  If partway through the work it turns out this is actually a bug fix rather than a feature addition,
+  report that to the user and switch commands.
+
+## Two gates
+
+This pipeline has two gates that must never be crossed early.
+
+1. Plan-approval gate: don't write implementation code until the user has approved the plan.
+   Reads for investigation and planning are fine before approval; adding or changing production
+   or test code starts only after approval.
+2. Commit gate: never commit without the user's confirmation, under any circumstances.
+
+Even when it's tempting to push forward autonomously, always stop at the gate and get confirmation.
+
+## Completion Marker Convention
+
+This command runs under `claude -p` (non-interactive), which restarts as a fresh process every turn — past turn 1, this command body is not guaranteed to be re-expanded, so gate discipline (the two gates above) can silently erode across turns. To compensate, a hooks-based mechanism re-injects a digest of this command's must-obey constraints on the next turn whenever the pipeline is left incomplete.
+
+If this command's flow is **not yet complete** (e.g. stopped at the plan-approval gate, mid-implementation, awaiting review fixes, or stopped at the commit gate), your response **MUST end** with a line that is an exact match of:
+
+`<!-- ai-support-agent:resume name="add-feature" -->`
+
+If the flow **is complete** (implementation finished, committed with user confirmation, and the post-commit options were handled), do **not** output this marker.
+
+Never output this marker inside a code block or as an illustrative example — only emit it as the actual last line of real output when the flow is genuinely incomplete.
+
+<!-- RESUME_DIGEST_START -->
+When resuming this command on turn 2+ without the full command body re-expanded, obey these constraints:
+
+- **Two gates, never crossed early**:
+  1. Plan-approval gate: no implementation or test code changes until the user has explicitly approved the plan. Reads/investigation are fine before approval.
+  2. Commit gate: never commit without the user's explicit confirmation, under any circumstances.
+- Never self-interpret "roughly agreed to," silence, or an unrelated follow-up as approval or as commit confirmation.
+- **Test-first is non-negotiable**: for every task, write the test before the implementation, run it, and confirm it fails (red) before writing any implementation code. Then implement the minimal code to go green, then refactor while staying green.
+- **Do all work inside the dedicated worktree** created in Step 2 — never edit the main working tree directly.
+- **Step 9 verification requires evidence, not speculation**: never claim "tests pass" / "build passes" / "should work" without having actually run the command in this conversation and read its output. A stale or previous run's result does not count as evidence.
+- **Review gate (Step 8)**: every CRITICAL / HIGH finding from the code-reviewer / silent-failure-hunter review must be resolved, followed by a green re-run of the test suite, before moving on.
+- Follow the Step 10 commit-gate flow exactly: present the diff + proposed commit message, wait for confirmation, commit only after confirmation, then present the four post-commit options and execute the chosen one in the correct order (never remove a worktree before merge/PR is settled).
+<!-- RESUME_DIGEST_END -->
+
+## Procedure
+
+### 1. Declare the size classification
+
+Before starting work, declare which of the following applies.
+
+- Trivial: a small addition — one file, a handful of lines. The plan can be an abbreviated,
+  key-points-only version, but presenting it and getting approval is still not optional.
+- Small: an addition spanning a few files, with a clear, easy-to-see-through path.
+- Standard or larger: an addition touching multiple modules, or involving design decisions.
+
+Regardless of size, changes touching authentication/authorization, input handling, databases,
+external service integrations, or anything money-related always require a formal plan and approval.
+
+### 2. Create a worktree
+
+Create a dedicated branch and worktree for the work, and do everything from here on inside that worktree.
+
+First check the existing isolation state.
+
+```bash
+MAIN_ROOT=$(git rev-parse --show-toplevel)
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+SUPERPROJECT=$(git rev-parse --show-superproject-working-tree 2>/dev/null)
+echo "MAIN_ROOT=$MAIN_ROOT"
+echo "GIT_DIR=$GIT_DIR"
+echo "GIT_COMMON=$GIT_COMMON"
+echo "SUPERPROJECT=${SUPERPROJECT:-(none)}"
+```
+
+Use the output above to determine which of three states applies.
+
+| Condition | State | Action |
+|---|---|---|
+| `SUPERPROJECT` has a value | Inside a submodule | Don't create a worktree — work directly |
+| `SUPERPROJECT` is empty and `GIT_DIR != GIT_COMMON` | Already inside a worktree | Don't create a new one — keep working in the existing worktree |
+| `SUPERPROJECT` is empty and `GIT_DIR == GIT_COMMON` | Regular repository | Create a worktree (steps below) |
+
+Create the worktree.
+
+```bash
+git worktree add -b <branch-name> <path>
+# e.g. git worktree add -b feature/add-user-auth ../worktrees/add-user-auth
+```
+
+- Name the branch after what the feature does.
+- A sibling directory outside the repo is usually the most convenient path (e.g. `../worktrees/<name>`).
+- If placing it inside the project (`.worktrees/`), confirm it's in `.gitignore` before creating it (`git check-ignore -q .worktrees`). If it's not listed, add it and commit that first.
+- Working inside a worktree keeps the main working directory clean, and rolling back is as simple as deleting the whole directory.
+
+Once created, run the test suite to confirm a clean baseline. If there are pre-existing failures, report them to the user and confirm whether to proceed. If proceeding, record those failures as pre-existing issues outside the scope of this work (so they aren't later mistakenly reported as a regression introduced here).
+
+### 3. Investigate the existing code
+
+Before settling on an implementation approach, investigate the codebase first.
+
+- Look for reusable implementations: existing utilities, shared components,
+  similar features. Don't reinvent the wheel.
+- Identify the patterns to follow: directory structure, naming conventions,
+  error-handling approach, testing conventions.
+- If an existing mechanism already satisfies the requirement, use it instead of building something new.
+
+### 4. Clarifying questions
+
+**This step can be skipped for trivial changes. It is required for small and larger changes.**
+
+Building on the codebase investigation, organize the ambiguities and open points left over from restating
+the request using the perspectives below, and ask the user about them together in one batch. Don't re-ask
+about anything already clear. Wait for the answer before moving to the next step.
+
+| Perspective | What to confirm |
+|---|---|
+| Target users and permissions | Who will use this feature? What permissions/preconditions are needed to operate it? |
+| Non-functional requirements | Are there performance, throughput, or scale targets? |
+| Backward compatibility and constraints | Must existing APIs, data formats, or external integrations be preserved? Are any technologies off-limits? |
+| Failure behavior | What should be returned to the user on failure? Is a rollback needed? |
+| Definition of done | What state counts as "complete"? Are there acceptance criteria? |
+
+If there's nothing unclear, declare "No clarifying questions" and move on.
+Fold the user's answers directly into the plan.
+
+### 5. Draft a plan and get it approved (plan-approval gate)
+
+- Use the planner subagent or /plan to draft the plan. The plan should include
+  the implementation approach, what will change, a task breakdown, test strategy, and risks.
+- Present the plan to the user and wait for approval. Don't start implementing before approval.
+- If changes are requested, revise the plan and re-present it, and get approval again.
+  Never self-interpret "roughly agreed to" as approval and start implementing.
+
+### 6. Write tests first and confirm red
+
+Write tests before writing implementation code.
+
+- Following the approved plan's task breakdown, write each task's tests first.
+- Run the tests and **confirm they fail (red)**.
+  A test that doesn't go red proves nothing about the implementation — always watch the failure happen.
+- Choose the test layer appropriate to what's being tested (tasks involving DB reads/writes should
+  include integration tests against a real database — see the integration-testing skill).
+- For features touching critical UI flows (authentication, registration/updates, payments, etc.),
+  consider adding or updating E2E tests (see the e2e-testing skill).
+
+### 7. Implement (green → refactor)
+
+- Work in thin vertical slices. Build up small, working increments rather than
+  one large change that stays broken for a long time.
+- For each task, write the minimal implementation that makes step 6's tests pass (green).
+  Once green, clean up the code (refactor) while staying green.
+- If the build breaks, restore it with /build-fix before continuing.
+- Include E2E tests (if `playwright.config.*` etc. exists) when running the test suite.
+  If they can't run due to environment constraints, report that to the user.
+- If the change spans multiple repositories, run the test suite in every repository that was
+  changed and confirm there's no regression.
+- Use /test-coverage if you want to check whether test coverage is adequate.
+- If you need to deviate from the plan, don't just proceed — consult the user first.
+
+#### Logging considerations (for projects that follow a logging convention)
+
+Alongside implementation, check the following.
+
+- **New entry points** (endpoints, jobs, workers) should set `request_id` / `user_id` / `tenant_code`
+  (or equivalent) in the logging context at the start of the request.
+- **Business events** (state transitions, key start/completion points) should be logged at INFO level.
+- **Public methods in the service/use-case layer** should emit DEBUG-level start/end, input/output,
+  and duration, ideally via a cross-cutting mechanism like a decorator.
+- **ERROR logs** should include the exception, stack trace, `request_id`, and the ID of the affected resource.
+- Passwords, tokens, and personal information must be masked even at DEBUG level.
+- See your project's logging conventions doc for details.
+
+### 8. Get a review
+
+Run a review using the same parallel Workflow execution as `/code-review` (Mode A).
+
+1. Identify the changed files with `git diff HEAD --name-only`, and select reviewers per `/code-review`'s
+   "Selecting reviewers" table (`code-reviewer` and `silent-failure-hunter` are always included).
+2. Invoke the Workflow script described in `/code-review` and run the selected reviewers in parallel.
+3. Review the returned `findings` and resolve every CRITICAL / HIGH finding.
+   After making the fixes, re-run the test suite and confirm it's green.
+
+### 9. Verify before declaring done (no claims without evidence)
+
+**Iron rule: run the verification commands and read the output before claiming completion.**
+
+"Should pass," "probably fine," "I don't think there's a problem" are guesses, not claims.
+Before crossing the commit gate, actually run the following **in this conversation** and confirm:
+
+| Claim | Required evidence |
+|---|---|
+| TDD red was confirmed | Ran it right after writing the test and watched it fail (red) |
+| Tests pass | Ran the test command and saw zero failures in the output |
+| Build passes | Ran the build command and saw exit code 0 |
+| Requirements are met | Re-read the plan's task breakdown and confirmed each item was achieved |
+| No regressions | Ran the existing test suite and confirmed no failures |
+
+All of the following are prohibited:
+
+- Claiming completion with phrases like "should pass," "probably," "I believe"
+- Claiming something "passes" based on a previous run (a stale result is not evidence)
+- Trusting a subagent's "done successfully" report without verifying it yourself
+- Reporting partial verification (only some tests) as complete verification
+- Jumping from "tests pass" to "requirements are met" (test passage does not imply requirement satisfaction)
+
+### 10. Commit and clean up the worktree (commit gate)
+
+- Present a summary of the diff and a proposed commit message, and wait for the user's confirmation.
+- Commit only once confirmation is given.
+- Follow the project's existing conventions (commit log style, etc.) for message format and granularity.
+
+After committing, present the user with these four options.
+
+```
+Implementation is complete. What would you like to do with this change?
+
+1. Merge it into <base branch> locally
+2. Push and open a Pull Request
+3. Keep this branch as-is (handle it later)
+4. Discard this work
+```
+
+Handle each choice as follows.
+
+**1. Local merge**
+
+```bash
+# Move out of the worktree (to the main repo root) before running this
+cd "$MAIN_ROOT"
+git checkout <base-branch>
+git pull
+git merge <feature-branch>
+# Run the test suite after merging to confirm no regression
+git worktree remove <worktree-path>
+git worktree prune
+git branch -d <feature-branch>
+```
+
+**2. Open a PR**
+
+```bash
+git push -u origin <feature-branch>
+gh pr create --base <base-branch> --head <feature-branch> \
+  --title "<change title>" --body "<summary of the change>"
+# Don't remove the worktree — it's needed for handling PR feedback
+```
+
+**3. Keep as-is**
+
+Leave both the worktree and the branch in place. Tell the user the path and stop.
+
+**4. Discard**
+
+Ask the user to type `discard` first, and only proceed once confirmed.
+
+```bash
+cd "$MAIN_ROOT"
+git worktree remove <worktree-path>
+git worktree prune
+git branch -D <feature-branch>
+```
+
+**Order and prohibitions to observe**
+
+- Never run `git worktree remove` from inside the worktree (always move to the main repo root first).
+- Run `git branch -d` **after** `git worktree remove` (the reverse order fails).
+- Don't remove the worktree before the merge (confirm the merge succeeded first).
+- Don't remove the worktree after creating a PR (option 2).
+
+## Verification checklist
+
+Before reporting completion, confirm all of the following.
+
+- [ ] Created a worktree and ran the baseline tests to confirm a clean starting point (any pre-existing failures were recorded).
+- [ ] Investigated existing implementations and patterns, and avoided unnecessary new implementation.
+- [ ] For small/standard-or-larger changes, asked clarifying questions and resolved open points before drafting the plan.
+- [ ] The plan was approved by the user, and no implementation code was written before approval.
+- [ ] Wrote tests first for every task and confirmed red before implementing.
+- [ ] No regressions in the existing test suite (including E2E tests, if present).
+- [ ] If the change spans multiple repositories, ran the test suite in every changed repository and confirmed no regression.
+- [ ] Resolved every CRITICAL / HIGH review finding.
+- [ ] Ran verification commands and read the output before claiming completion (didn't guess "should pass").
+- [ ] Committed only after the user's confirmation (left uncommitted if not yet confirmed).
+- [ ] Presented the four-option worktree cleanup and executed it in the correct order (remove worktree → delete branch) for the chosen option.
+- [ ] If a logging convention applies: added correlation-ID context to new entry points, logged business events at INFO, and masked sensitive information.

package/dist/plugin/commands/build-fix.md

@@ -0,0 +1,47 @@
+---
+description: Fix build and type errors with the smallest possible diff to get the build green. Does not refactor or add features.
+argument-hint: "[error message | leave empty to auto-diagnose]"
+---
+
+# /build-fix command
+
+**Input**: $ARGUMENTS
+
+A command for getting a broken build back to green with the smallest possible change. This command is a thin entry point. Detecting the project type and deciding how to diagnose and fix it is delegated to the `build-error-resolver` subagent (bundled with this plugin) as a rule.
+
+## Behavior
+
+### 1. Handling the input
+
+- If `$ARGUMENTS` contains an error message, use it as the starting point for the fix.
+- If empty, start from auto-diagnosis. Detecting the project type, choosing diagnostic commands, and the discipline of minimal fixes are delegated to build-error-resolver.
+- In a monorepo, scope the work to only the workspaces that changed.
+
+### 2. Error-classification priority (overview)
+
+1. **Build-breaking** (compilation failures, module resolution failures) — highest priority
+2. **Type errors** — next
+3. **Lint warnings, deprecated APIs** — only if time allows
+
+### 3. Completion report
+
+```
+## Build fix complete
+
+Before: <n> errors → After: 0 errors
+Changed files: <list>
+Lines changed: <n>
+
+Key fixes:
+- <file:line> <one-line description of the fix>
+
+Verification:
+- <diagnostic command run>: Pass
+- Tests (if run): Pass / Warning (details)
+```
+
+## Notes
+
+- **Always confirm with the user before any destructive recovery** (clearing caches, rebuilding `node_modules`, etc.) before running it.
+- If the same error survives 5 fix attempts, present a hypothesis and options and let the user decide (don't loop indefinitely).
+- If the fix turns out to require an architectural change, stop and suggest switching to `/plan`.

package/dist/plugin/commands/code-review.md

@@ -0,0 +1,228 @@
+---
+description: Run a code review across your stack and post a report and verdict to the PR/MR
+argument-hint: "[PR/MR number or URL] (omit to review local uncommitted changes)"
+---
+
+# /code-review
+
+This command lives in this plugin's namespace and is invoked as `/<plugin>:code-review` (which is distinct, by
+namespace, from Claude Code's built-in `/code-review` and `/review` — an unprefixed `/code-review` may refer to
+the built-in version). Where the built-in command does a general-purpose diff review, this command's added value
+is applying review criteria specific to your stack (TypeScript / Python / PHP / React / Next.js / Vue / Django /
+Laravel / CakePHP / IaC, etc.) and recording the review as a structured report that gets posted back. If a
+general-purpose review is all you need, the built-in command works fine.
+
+## Determining the mode
+
+Check the `$ARGUMENTS` value to decide which mode to run in.
+
+- No argument → Mode A (local review)
+- A number (e.g. `123`) or a PR/MR URL → Mode B (PR/MR review)
+
+## Selecting reviewers (both modes)
+
+Look at the paths of the changed files and use the table below to decide which reviewers to run.
+`code-reviewer` and `silent-failure-hunter` are always included.
+
+| File-type condition | Reviewer to add |
+|---|---|
+| Includes `.ts` / `.tsx` / `.js` / `.jsx` / `.mjs` / `.cjs` | `typescript-reviewer` |
+| `.tsx` / `.jsx` with component definitions | `react-reviewer` (alongside `typescript-reviewer`) |
+| Touches `app/` / `pages/` / `next.config` / `middleware.ts` / a Server Action | `nextjs-reviewer` |
+| Includes `.py` | `python-reviewer` |
+| Touches Django-style files (`models.py` / `views.py` / `serializers.py` / `migrations/`, etc.) | `django-reviewer` (alongside `python-reviewer`) |
+| Includes `.php` | `php-reviewer` |
+| Touches UI components or layout | `ui-reviewer` |
+| Includes `*.ts` (CDK) / `serverless.yml` / `template.yaml` / CloudFormation-style files | `infra-reviewer` |
+
+This table matches the "delegating to other agents" routing table used by code-reviewer.
+Treat the code-reviewer agent's routing table as the source of truth when adding or changing reviewers, and mirror the change here too.
+
+## Workflow script (both modes)
+
+Once the reviewer list is finalized, pass the script below to the Workflow tool's `script` parameter and run it in parallel.
+Pass the selected reviewer names as `args.reviewers`, and the mode-specific review instructions (described below) as `args.reviewContext`.
+
+```javascript
+export const meta = {
+  name: 'code-review-parallel',
+  description: 'Run stack-specific reviewers in parallel to speed up code review',
+  phases: [
+    { title: 'Review' },
+    { title: 'Merge' }
+  ]
+}
+
+const SEVERITY_ORDER = { CRITICAL: 0, HIGH: 1, MEDIUM: 2, LOW: 3 }
+
+const FINDINGS_SCHEMA = {
+  type: 'object',
+  properties: {
+    findings: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          severity: { type: 'string', enum: ['CRITICAL', 'HIGH', 'MEDIUM', 'LOW'] },
+          file: { type: 'string' },
+          line: { type: 'string' },
+          description: { type: 'string' },
+          suggestion: { type: 'string' }
+        },
+        required: ['severity', 'description']
+      }
+    }
+  },
+  required: ['findings']
+}
+
+phase('Review')
+const results = await parallel(args.reviewers.map(name => () =>
+  agent(args.reviewContext, {
+    label: name,
+    phase: 'Review',
+    agentType: name,
+    schema: FINDINGS_SCHEMA
+  })
+))
+
+phase('Merge')
+const all = results.filter(Boolean).flatMap(r => r.findings || [])
+const sorted = all.sort((a, b) =>
+  (SEVERITY_ORDER[a.severity] ?? 4) - (SEVERITY_ORDER[b.severity] ?? 4)
+)
+return { findings: sorted }
+```
+
+Use the `findings` returned by the Workflow (already sorted by severity) in the steps that follow.
+
+## Mode A: local review (no argument)
+
+Review the uncommitted changes (both staged and unstaged).
+
+1. Identify the changed files with `git diff HEAD --name-only` and select reviewers (see "Selecting reviewers" above).
+2. Run the Workflow in parallel, passing the following as `args.reviewContext`:
+   ```
+   Review the current uncommitted changes (git diff HEAD, or the combination of git diff --staged and git diff).
+   Read the full content of each changed file and its surrounding code (callers, type definitions, middleware,
+   etc.) and report issues from your area of expertise. Don't judge from the diff alone.
+   ```
+3. Group the `findings` returned by the Workflow by severity (CRITICAL / HIGH / MEDIUM / LOW) and report them to the user.
+   Don't post anything remotely in this mode.
+
+## Mode B: PR/MR review (number or URL)
+
+### Determining the host
+
+Pick the CLI to use with the following rule.
+
+- If the argument is a URL: use the `gh` CLI for `github.com`, the `glab` CLI for `gitlab.com`.
+- If the argument is a bare number: check `git remote get-url origin` — use `gh` if it contains `github.com`, `glab` if it contains `gitlab.com`.
+- For self-hosted setups that match neither, show the user the remote URL and ask which CLI to use.
+
+### Steps
+
+1. **Fetch metadata and changed files**
+   - GitHub: `gh pr view <number> --json title,body,author,baseRefName,headRefName,isDraft,files` to get the list of changed files.
+   - GitLab: `glab mr view <number>` to get the list of changed files.
+2. **Build context**
+   - Read the project's CLAUDE.md (or equivalent) to understand coding conventions and background.
+   - If the PR/MR description references a plan file or an issue, read that too.
+3. **Select reviewers and run the Workflow**
+   - Select reviewers from the changed-file list obtained in step 1 (see "Selecting reviewers" above).
+   - Run the Workflow in parallel, passing the following as `args.reviewContext` (substitute `<number>` and `<CLI>` with the actual values):
+     ```
+     Review PR/MR #<number>. Fetch the diff with `<CLI> pr/mr diff <number>`, and read the full content of
+     each changed file along with its surrounding code (callers, type definitions, middleware, etc.). Don't
+     judge from the diff alone. Report issues from your area of expertise, and for each finding include the
+     severity, file, line, a description of the problem, and a suggested fix.
+     ```
+   - Use the `findings` returned by the Workflow (already sorted by severity) for the verdict step below.
+4. **Run verification**
+   - Detect the project type and run whatever applies.
+     - Node-based: type checking (tsc, etc.), lint, tests, build. Check `package.json` scripts to pick the right ones.
+     - Python-based: mypy / ruff / pytest, etc., for whichever config files are present. If a virtual environment exists (`.venv/` / `venv/`), use the tools inside it (e.g. `.venv/bin/pytest`; for poetry/uv-managed projects, run through `poetry run` / `uv run`).
+     - PHP-based: phpstan / php-cs-fixer / phpunit, etc., for whichever config files are present.
+     - E2E: if `playwright.config.*` (or `cypress.config.*`) exists, **always include E2E tests in the run**
+       (`npx playwright test`; if the config has a `webServer`, the app starts automatically). Skip only if the
+       environment can't support it, and always record why. On failure, distinguish code-caused failures from
+       environment-caused ones (external service not running, missing credentials, etc.); code-caused failures
+       count as a verification failure.
+   - Record the results (pass/fail/skip reason) for each check.
+5. **Verdict**
+
+   Apply the shared verdict rule across all reviewers, evaluated top to bottom.
+
+   | Condition | Verdict |
+   |---|---|
+   | Any CRITICAL findings | Blocked (post as change request, with BLOCKING stated at the top) |
+   | Any HIGH findings, or verification failed | Changes requested |
+   | MEDIUM only (verification passed) | Approve with warnings |
+   | No findings / LOW only (verification passed) | Approve |
+
+   When posting remotely: both "approve" and "approve with warnings" post as an approval; for the latter, include
+   the MEDIUM findings and recommended follow-ups in the report body. If the target is a draft PR/MR, post a
+   comment only regardless of verdict — don't approve or request changes.
+
+6. **Save the review record**
+   - Save it under `.claude/reviews/` as `<date>-<PR/MR number>.md` (template below).
+7. **Post remotely**
+   - GitHub: `gh pr review <number> --approve | --request-changes | --comment --body "<report>"`
+   - GitLab: approve with `glab mr approve <number>`; post the report body with `glab mr note <number> --message "<report>"`.
+     GitLab has no direct equivalent of "request changes," so for a changes-requested or blocked verdict, skip
+     approval and instead state "Changes requested" or "Blocked" at the top of the note.
+8. **Summarize for the user**
+   - Report the verdict, finding counts by severity, verification results, the link to where it was posted, and the record file path, concisely.
+
+## Review record template
+
+```markdown
+# Review record: <PR/MR title or "local changes">
+
+- Date: <YYYY-MM-DD HH:MM>
+- Target: <PR/MR number and URL, or branch name>
+- Verdict: <Approve | Approve with warnings | Changes requested | Blocked | Comment only (draft)>
+
+## Summary
+
+<2-3 sentence summary of the change>
+
+## Findings
+
+### CRITICAL
+- <file:line> <description of the problem and suggested fix> (or "None")
+
+### HIGH
+- None
+
+### MEDIUM
+- None
+
+### LOW
+- None
+
+## Verification results
+
+| Item | Command | Result |
+|---|---|---|
+| Type check | <command run> | <Pass/Fail/Skipped> |
+| Lint | <command run> | <Pass/Fail/Skipped> |
+| Tests | <command run> | <Pass/Fail/Skipped> |
+| E2E | <command run> | <Pass/Fail/Skipped (reason)> |
+| Build | <command run> | <Pass/Fail/Skipped> |
+
+## Notes
+
+<rebase recommendation, scope limitations, any fallback used, etc.>
+```
+
+## Edge cases
+
+- **CLI unavailable**: if `gh` / `glab` isn't installed or authenticated, say so and fall back to a local review
+  (equivalent to Mode A — diff against the checked-out target branch if available) without posting anything.
+- **Very large PR/MR**: if the changed files number roughly 30+ or the diff is roughly 3000+ lines, warn that
+  full coverage may not be possible, prioritize the highest-impact files (core logic, security-sensitive code,
+  public APIs), and record the actual scope covered in both the saved record and the summary.
+- **Branch diverged from base**: if the base branch has moved on and the target branch is stale, flag the risk
+  of conflicts or inconsistent verification results and suggest a rebase (or merging in the latest base). Judge
+  the verdict against the code as it currently stands.