fix: tighten PR review branch handling

.github/workflows/kompass-pr-review-comment.yml

@@ -0,0 +1,55 @@
+name: Kompass PR Review Comment
+
+on:
+  issue_comment:
+    types: [created]
+
+jobs:
+  review:
+    if: github.event.issue.pull_request && startsWith(github.event.comment.body, '/review') && contains(fromJson('["OWNER","MEMBER"]'), github.event.comment.author_association)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Generate GitHub App Token
+        id: token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ secrets.KOMPASS_APP_ID }}
+          private-key: ${{ secrets.KOMPASS_APP_PRIVATE_KEY }}
+
+      - name: Get PR details
+        id: pr
+        env:
+          GH_TOKEN: ${{ steps.token.outputs.token }}
+        run: |
+          gh api /repos/${{ github.repository }}/pulls/${{ github.event.issue.number }} > pr_data.json
+          echo "head_repo=$(jq -r .head.repo.full_name pr_data.json)" >> "$GITHUB_OUTPUT"
+          echo "head_ref=$(jq -r .head.ref pr_data.json)" >> "$GITHUB_OUTPUT"
+
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          repository: ${{ steps.pr.outputs.head_repo }}
+          ref: ${{ steps.pr.outputs.head_ref }}
+          fetch-depth: 0
+          token: ${{ steps.token.outputs.token }}
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v1
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Install Kompass Tooling
+        uses: ./.github/actions/kompass-opencode-install
+
+      - name: Run Kompass PR Review
+        env:
+          GITHUB_TOKEN: ${{ steps.token.outputs.token }}
+          OPENCODE_API_KEY: ${{ secrets.OPENCODE_API_KEY }}
+        run: opencode run --model="${{ vars.OPENCODE_MODEL }}" --variant="${{ vars.OPENCODE_VARIANT }}" --thinking --command="pr/review" "${{ github.event.issue.number }}"
+
+      - name: Export Kompass Session
+        if: always()
+        uses: ./.github/actions/kompass-opencode-session-export

.github/workflows/kompass-pr-review.yml

@@ -6,7 +6,7 @@ on:
 
 jobs:
   review:
-    if: github.event.pull_request.draft == false
+    if: github.event.pull_request.draft == false && github.event.pull_request.head.repo.full_name == github.repository
     runs-on: ubuntu-latest
     steps:
       - name: Generate GitHub App Token

kompass.jsonc

@@ -51,6 +51,7 @@
   },
 
   "components": {
+    "align-pr-branch": { "enabled": true },
     "change-summary": { "enabled": true },
     "changes-summary": { "enabled": true },
     "commit": { "enabled": true },

kompass.schema.json

@@ -215,6 +215,9 @@
       "type": "object",
       "additionalProperties": false,
       "properties": {
+        "align-pr-branch": {
+          "$ref": "#/$defs/componentConfig"
+        },
         "change-summary": {
           "$ref": "#/$defs/componentConfig"
         },
@@ -243,15 +246,15 @@
           "type": "array",
           "items": {
             "type": "string",
-            "enum": ["change-summary", "changes-summary", "commit", "dev-flow", "load-pr", "load-ticket", "skill-authoring", "summarize-changes"]
+            "enum": ["align-pr-branch", "change-summary", "changes-summary", "commit", "dev-flow", "load-pr", "load-ticket", "skill-authoring", "summarize-changes"]
           },
           "uniqueItems": true,
           "deprecated": true
         },
         "paths": {
           "type": "object",
           "propertyNames": {
-            "enum": ["change-summary", "changes-summary", "commit", "dev-flow", "load-pr", "load-ticket", "skill-authoring", "summarize-changes"]
+            "enum": ["align-pr-branch", "change-summary", "changes-summary", "commit", "dev-flow", "load-pr", "load-ticket", "skill-authoring", "summarize-changes"]
           },
           "additionalProperties": {
             "type": "string"

packages/core/commands/pr/fix.md

@@ -30,13 +30,7 @@ $ARGUMENTS
 
 ### Align Local Branch
 
-- If `<pr-branch>` is unavailable, STOP and report that the PR head branch could not be determined
-- If `<current-branch>` differs from `<pr-branch>`:
-  - Checkout `<pr-branch>` before analyzing repository files or making code changes for this PR
-  - After checkout, store the active branch as `<active-branch>`
-  - If checkout fails, STOP and report that the PR branch could not be checked out locally
-- Otherwise, store `<current-branch>` as `<active-branch>`
-- Do not inspect or modify local code for this PR until `<active-branch>` equals `<pr-branch>`
+<%~ include("@align-pr-branch", { action: "analyzing repository files or making code changes for this PR", scope: "inspect or modify local code for this PR" }) %>
 
 ### Analyze Feedback
 

packages/core/commands/pr/review.md

@@ -26,13 +26,7 @@ $ARGUMENTS
 
 ### Align Local Branch
 
-- If `<pr-branch>` is unavailable, STOP and report that the PR head branch could not be determined
-- If `<current-branch>` differs from `<pr-branch>`:
-  - Checkout `<pr-branch>` before inspecting local repository files for this PR review
-  - After checkout, store the active branch as `<active-branch>`
-  - If checkout fails, STOP and report that the PR branch could not be checked out locally
-- Otherwise, store `<current-branch>` as `<active-branch>`
-- Do not inspect local repository code for this PR until `<active-branch>` equals `<pr-branch>`
+<%~ include("@align-pr-branch", { action: "inspecting local repository files for this PR review", scope: "inspect local repository code for this PR" }) %>
 
 ### Load Ticket Context
 

packages/core/components/align-pr-branch.md

@@ -0,0 +1,5 @@
+- If `<pr-branch>` is unavailable, STOP and report that the PR head branch could not be determined
+- Run `gh pr checkout <pr-context.pr.number>` before <%= it.action %>
+- After checkout, store the active branch as `<active-branch>`
+- If checkout fails, STOP and report that the PR branch could not be checked out locally
+- Do not <%= it.scope %> until `<active-branch>` equals `<pr-branch>`

packages/core/kompass.jsonc

@@ -51,6 +51,7 @@
   },
 
   "components": {
+    "align-pr-branch": { "enabled": true },
     "change-summary": { "enabled": true },
     "changes-summary": { "enabled": true },
     "commit": { "enabled": true },

packages/core/lib/config.ts

@@ -48,6 +48,7 @@ export const DEFAULT_COMMAND_NAMES = [
 export const DEFAULT_AGENT_NAMES = ["worker", "navigator", "planner", "reviewer"] as const;
 
 export const DEFAULT_COMPONENT_NAMES = [
+  "align-pr-branch",
   "change-summary",
   "changes-summary",
   "commit",
@@ -129,6 +130,7 @@ export interface KompassConfig {
     ticket_load?: ToolConfig;
   };
   components?: {
+    "align-pr-branch"?: ComponentConfig;
     "change-summary"?: ComponentConfig;
     "changes-summary"?: ComponentConfig;
     commit?: ComponentConfig;
@@ -443,6 +445,7 @@ const defaultAgentPlanner: AgentDefinition = {
 };
 
 const defaultComponentPaths: Record<string, string> = {
+  "align-pr-branch": "components/align-pr-branch.md",
   "change-summary": "components/change-summary.md",
   "changes-summary": "components/changes-summary.md",
   "commit": "components/commit.md",

packages/opencode/.opencode/commands/pr/fix.md

@@ -45,11 +45,9 @@ $ARGUMENTS
 ### Align Local Branch
 
 - If `<pr-branch>` is unavailable, STOP and report that the PR head branch could not be determined
-- If `<current-branch>` differs from `<pr-branch>`:
-  - Checkout `<pr-branch>` before analyzing repository files or making code changes for this PR
-  - After checkout, store the active branch as `<active-branch>`
-  - If checkout fails, STOP and report that the PR branch could not be checked out locally
-- Otherwise, store `<current-branch>` as `<active-branch>`
+- Run `gh pr checkout <pr-context.pr.number>` before analyzing repository files or making code changes for this PR
+- After checkout, store the active branch as `<active-branch>`
+- If checkout fails, STOP and report that the PR branch could not be checked out locally
 - Do not inspect or modify local code for this PR until `<active-branch>` equals `<pr-branch>`
 
 ### Analyze Feedback

packages/opencode/.opencode/commands/pr/review.md

@@ -41,11 +41,9 @@ $ARGUMENTS
 ### Align Local Branch
 
 - If `<pr-branch>` is unavailable, STOP and report that the PR head branch could not be determined
-- If `<current-branch>` differs from `<pr-branch>`:
-  - Checkout `<pr-branch>` before inspecting local repository files for this PR review
-  - After checkout, store the active branch as `<active-branch>`
-  - If checkout fails, STOP and report that the PR branch could not be checked out locally
-- Otherwise, store `<current-branch>` as `<active-branch>`
+- Run `gh pr checkout <pr-context.pr.number>` before inspecting local repository files for this PR review
+- After checkout, store the active branch as `<active-branch>`
+- If checkout fails, STOP and report that the PR branch could not be checked out locally
 - Do not inspect local repository code for this PR until `<active-branch>` equals `<pr-branch>`
 
 ### Load Ticket Context

packages/opencode/kompass.jsonc

@@ -51,6 +51,7 @@
   },
 
   "components": {
+    "align-pr-branch": { "enabled": true },
     "change-summary": { "enabled": true },
     "changes-summary": { "enabled": true },
     "commit": { "enabled": true },

packages/web/src/content/docs/docs/reference/components/align-pr-branch.mdx

@@ -0,0 +1,12 @@
+---
+title: align-pr-branch
+description: Shared partial for aligning PR-scoped commands to the pull request branch.
+---
+
+## Behavior
+
+- requires the caller to provide `<pr-branch>`
+- runs `gh pr checkout <pr-context.pr.number>` before local PR analysis or edits
+- stores the active branch as `<active-branch>` after checkout
+- stops if checkout fails or if the active branch does not match `<pr-branch>`
+- accepts caller-provided wording through `it.action` and `it.scope`

packages/web/src/content/docs/docs/reference/components/index.mdx

@@ -7,6 +7,7 @@ Kompass command templates can include reusable Eta partials from `packages/core/
 
 Bundled components:
 
+- `align-pr-branch`
 - `change-summary`
 - `changes-summary`
 - `commit`
@@ -18,6 +19,10 @@ Bundled components:
 
 ## Bundled components
 
+### `align-pr-branch`
+
+Guides PR-scoped commands to switch onto the PR head branch with `gh pr checkout`, capture the active branch, and stop if local work is not aligned to the PR branch.
+
 ### `change-summary`
 
 Loads changes with `changes_load`, analyzes file-level diffs, and groups the work into concise what/why themes.