docs: clarify commit-based scope for branch comparisons

packages/core/agents/reviewer.md

@@ -12,6 +12,7 @@ Before reviewing, always check repository guidance:
 
 1. **Load Changes**: Use `changes_load` to get the changed-file set and structured diffs
     - In CI or shallow clones, pass explicit base and head refs
+    - For branch comparisons, treat the returned commit list as the authoritative scope: review the commits ahead of base and use file diffs only as supporting context
     - Scan the summary first to understand scope, file states, and risk clusters
     - Never switch branches, create local review branches, or otherwise mutate `HEAD`; if a loader fails, prefer reporting the blocker over changing checkout state
 

packages/core/commands/pr/create.md

@@ -35,6 +35,7 @@ $ARGUMENTS
 - Store the loaded change result as `<changes>`
 - Store the current branch from `<changes>` as `<current-branch>` when it is available
 - Store the effective base branch as `<resolved-base>` by preferring `<base>` when it was provided, otherwise using the base branch implied by `<changes>.comparison`
+- When `<changes>.comparison` is not `uncommitted`, describe the PR from the commits ahead of `<resolved-base>`, not from the raw branch comparison string by itself
 
 ### Check Blockers
 
@@ -123,6 +124,7 @@ Use `pr_sync` to create the pull request:
   - `## Checklist`, followed by the checklist items and any subsection headings
 - Use `<resolved-base>` as the base branch when it is defined
 - Do NOT restate the full diff
+- Do NOT rely on the branch diff alone to describe the PR; the description must match the commits ahead of `<resolved-base>`
 - Keep it compact and directional
 - Store the returned URL as `<pr-url>`
 - If `pr_sync` reports that a PR already exists for the branch, treat the result as an existing PR

packages/core/commands/review.md

@@ -35,7 +35,7 @@ If `<changes>.comparison` is "uncommitted":
 - Store `uncommitted changes` as `<scope-description>`
 
 If `<changes>.comparison` is not "uncommitted":
-- Treat as reviewing branch changes
+- Treat as reviewing the commits ahead of base plus their resulting file diffs
 - If `<base>` is defined and `<current-branch>` is available, store `<current-branch> -> <base>` as `<scope-description>`
 - Otherwise, store `<changes>.comparison` as `<scope-description>`
 

packages/core/commands/ticket/create.md

@@ -25,6 +25,7 @@ $ARGUMENTS
 <%~ include("@change-summary", { rules: "- If `<base>` is defined: call `changes_load` with the `base` parameter set to `<base>`\n- Otherwise: call `changes_load` with no parameters" }) %>
 
 - Store the loaded change result as `<changes>`
+- When `<changes>.comparison` is not `uncommitted`, describe the ticket from the commits ahead of the resolved base branch, not from branch names alone
 
 ### Check Blockers
 

packages/core/components/change-summary.md

@@ -3,12 +3,15 @@
 <%= it.rules ?? "" %>
 - Store the returned result as `<changes>`
 - Use `<changes>` as the source of truth; no additional git analysis commands are needed
+- When `<changes>.comparison` is not `uncommitted`, treat `<changes>.commits` as the authoritative scope of work: only summarize commits that are ahead of the resolved base branch
+- Do not infer scope from the branch names alone and do not describe work that exists only on the base branch
 
 #### Step 2: Analyze Files
-- Review the paths, statuses, and diffs from `<changes>`
+- Review the paths, statuses, and diffs from `<changes>` only as file-level context for the commits in scope
 - Identify the nature of changes (added, modified, deleted)
 - Note lines added/removed per file
 
 #### Step 3: Group and Summarize
+- For branch comparisons, build the summary from `<changes>.commits` first and use file diffs only to verify or refine what those commits changed
 - Group related changes into logical themes
 - Summarize the "what" and "why" (not the "how")

packages/core/components/changes-summary.md

@@ -1,4 +1,5 @@
 - Reuse the same change themes, rationale, and reviewer-facing validation goals from the current summary work
+- For branch comparisons, ensure every theme is supported by commits in `<changes>.commits`; use file diffs only as supporting context
 - Generate a concise title (max 70 chars) that reflects the delivered outcome
 - Generate a `description` that briefly describes what was accomplished and why it matters
 - Generate checklists with:

packages/core/components/summarize-changes.md

@@ -1,6 +1,8 @@
 ### Summarize Changes
 
 - Note the comparison mode, base branch, and current branch from the result
+- If the comparison is not `uncommitted`, use only the commits in `<changes>.commits` as the branch-work scope
 - Review commit messages when they are available to understand the delivery narrative
-- Read the most relevant changed source files to understand the changes
+- Read the most relevant changed source files to understand the changes introduced by those commits
+- Do not describe work that exists only on the base branch or that is outside the commits ahead of base
 - Group related changes into themes for the final summary

packages/opencode/.opencode/agents/reviewer.md

@@ -20,6 +20,7 @@ Before reviewing, always check repository guidance:
 
 1. **Load Changes**: Use `kompass_changes_load` to get the changed-file set and structured diffs
     - In CI or shallow clones, pass explicit base and head refs
+    - For branch comparisons, treat the returned commit list as the authoritative scope: review the commits ahead of base and use file diffs only as supporting context
     - Scan the summary first to understand scope, file states, and risk clusters
     - Never switch branches, create local review branches, or otherwise mutate `HEAD`; if a loader fails, prefer reporting the blocker over changing checkout state
 

packages/opencode/.opencode/commands/branch.md

@@ -31,13 +31,16 @@ $ARGUMENTS
 - pass `uncommitted: true` to get uncommitted changes only
 - Store the returned result as `<changes>`
 - Use `<changes>` as the source of truth; no additional git analysis commands are needed
+- When `<changes>.comparison` is not `uncommitted`, treat `<changes>.commits` as the authoritative scope of work: only summarize commits that are ahead of the resolved base branch
+- Do not infer scope from the branch names alone and do not describe work that exists only on the base branch
 
 #### Step 2: Analyze Files
-- Review the paths, statuses, and diffs from `<changes>`
+- Review the paths, statuses, and diffs from `<changes>` only as file-level context for the commits in scope
 - Identify the nature of changes (added, modified, deleted)
 - Note lines added/removed per file
 
 #### Step 3: Group and Summarize
+- For branch comparisons, build the summary from `<changes>.commits` first and use file diffs only to verify or refine what those commits changed
 - Group related changes into logical themes
 - Summarize the "what" and "why" (not the "how")
 - Store the loaded change result as `<changes>`

packages/opencode/.opencode/commands/commit-and-push.md

@@ -31,13 +31,16 @@ $ARGUMENTS
 - pass `uncommitted: true` to get uncommitted changes only
 - Store the returned result as `<changes>`
 - Use `<changes>` as the source of truth; no additional git analysis commands are needed
+- When `<changes>.comparison` is not `uncommitted`, treat `<changes>.commits` as the authoritative scope of work: only summarize commits that are ahead of the resolved base branch
+- Do not infer scope from the branch names alone and do not describe work that exists only on the base branch
 
 #### Step 2: Analyze Files
-- Review the paths, statuses, and diffs from `<changes>`
+- Review the paths, statuses, and diffs from `<changes>` only as file-level context for the commits in scope
 - Identify the nature of changes (added, modified, deleted)
 - Note lines added/removed per file
 
 #### Step 3: Group and Summarize
+- For branch comparisons, build the summary from `<changes>.commits` first and use file diffs only to verify or refine what those commits changed
 - Group related changes into logical themes
 - Summarize the "what" and "why" (not the "how")
 - Store the loaded change result as `<changes>`

packages/opencode/.opencode/commands/commit.md

@@ -31,13 +31,16 @@ $ARGUMENTS
 - pass `uncommitted: true` to get uncommitted changes only
 - Store the returned result as `<changes>`
 - Use `<changes>` as the source of truth; no additional git analysis commands are needed
+- When `<changes>.comparison` is not `uncommitted`, treat `<changes>.commits` as the authoritative scope of work: only summarize commits that are ahead of the resolved base branch
+- Do not infer scope from the branch names alone and do not describe work that exists only on the base branch
 
 #### Step 2: Analyze Files
-- Review the paths, statuses, and diffs from `<changes>`
+- Review the paths, statuses, and diffs from `<changes>` only as file-level context for the commits in scope
 - Identify the nature of changes (added, modified, deleted)
 - Note lines added/removed per file
 
 #### Step 3: Group and Summarize
+- For branch comparisons, build the summary from `<changes>.commits` first and use file diffs only to verify or refine what those commits changed
 - Group related changes into logical themes
 - Summarize the "what" and "why" (not the "how")
 - Store the loaded change result as `<changes>`

packages/opencode/.opencode/commands/pr/create.md

@@ -42,19 +42,23 @@ $ARGUMENTS
 - Never pass `uncommitted: true` in this command
 - Store the returned result as `<changes>`
 - Use `<changes>` as the source of truth; no additional git analysis commands are needed
+- When `<changes>.comparison` is not `uncommitted`, treat `<changes>.commits` as the authoritative scope of work: only summarize commits that are ahead of the resolved base branch
+- Do not infer scope from the branch names alone and do not describe work that exists only on the base branch
 
 #### Step 2: Analyze Files
-- Review the paths, statuses, and diffs from `<changes>`
+- Review the paths, statuses, and diffs from `<changes>` only as file-level context for the commits in scope
 - Identify the nature of changes (added, modified, deleted)
 - Note lines added/removed per file
 
 #### Step 3: Group and Summarize
+- For branch comparisons, build the summary from `<changes>.commits` first and use file diffs only to verify or refine what those commits changed
 - Group related changes into logical themes
 - Summarize the "what" and "why" (not the "how")
 
 - Store the loaded change result as `<changes>`
 - Store the current branch from `<changes>` as `<current-branch>` when it is available
 - Store the effective base branch as `<resolved-base>` by preferring `<base>` when it was provided, otherwise using the base branch implied by `<changes>.comparison`
+- When `<changes>.comparison` is not `uncommitted`, describe the PR from the commits ahead of `<resolved-base>`, not from the raw branch comparison string by itself
 
 ### Check Blockers
 
@@ -74,8 +78,10 @@ $ARGUMENTS
 ### Summarize Changes
 
 - Note the comparison mode, base branch, and current branch from the result
+- If the comparison is not `uncommitted`, use only the commits in `<changes>.commits` as the branch-work scope
 - Review commit messages when they are available to understand the delivery narrative
-- Read the most relevant changed source files to understand the changes
+- Read the most relevant changed source files to understand the changes introduced by those commits
+- Do not describe work that exists only on the base branch or that is outside the commits ahead of base
 - Group related changes into themes for the final summary
 
 ### Resolve Ticket
@@ -109,6 +115,7 @@ $ARGUMENTS
 
 When `<ticket-mode>` is `auto`, create the ticket before creating the PR:
 - Reuse the same change themes, rationale, and reviewer-facing validation goals from the current summary work
+- For branch comparisons, ensure every theme is supported by commits in `<changes>.commits`; use file diffs only as supporting context
 - Generate a concise title (max 70 chars) that reflects the delivered outcome
 - Generate a `description` that briefly describes what was accomplished and why it matters
 - Generate checklists with:
@@ -159,6 +166,7 @@ Use `kompass_pr_sync` to create the pull request:
   - `## Checklist`, followed by the checklist items and any subsection headings
 - Use `<resolved-base>` as the base branch when it is defined
 - Do NOT restate the full diff
+- Do NOT rely on the branch diff alone to describe the PR; the description must match the commits ahead of `<resolved-base>`
 - Keep it compact and directional
 - Store the returned URL as `<pr-url>`
 - If `kompass_pr_sync` reports that a PR already exists for the branch, treat the result as an existing PR

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

@@ -40,7 +40,7 @@ If `<changes>.comparison` is "uncommitted":
 - Store `uncommitted changes` as `<scope-description>`
 
 If `<changes>.comparison` is not "uncommitted":
-- Treat as reviewing branch changes
+- Treat as reviewing the commits ahead of base plus their resulting file diffs
 - If `<base>` is defined and `<current-branch>` is available, store `<current-branch> -> <base>` as `<scope-description>`
 - Otherwise, store `<changes>.comparison` as `<scope-description>`
 

packages/opencode/.opencode/commands/ticket/create.md

@@ -33,17 +33,21 @@ $ARGUMENTS
 - Otherwise: call `kompass_changes_load` with no parameters
 - Store the returned result as `<changes>`
 - Use `<changes>` as the source of truth; no additional git analysis commands are needed
+- When `<changes>.comparison` is not `uncommitted`, treat `<changes>.commits` as the authoritative scope of work: only summarize commits that are ahead of the resolved base branch
+- Do not infer scope from the branch names alone and do not describe work that exists only on the base branch
 
 #### Step 2: Analyze Files
-- Review the paths, statuses, and diffs from `<changes>`
+- Review the paths, statuses, and diffs from `<changes>` only as file-level context for the commits in scope
 - Identify the nature of changes (added, modified, deleted)
 - Note lines added/removed per file
 
 #### Step 3: Group and Summarize
+- For branch comparisons, build the summary from `<changes>.commits` first and use file diffs only to verify or refine what those commits changed
 - Group related changes into logical themes
 - Summarize the "what" and "why" (not the "how")
 
 - Store the loaded change result as `<changes>`
+- When `<changes>.comparison` is not `uncommitted`, describe the ticket from the commits ahead of the resolved base branch, not from branch names alone
 
 ### Check Blockers
 
@@ -52,14 +56,17 @@ $ARGUMENTS
 ### Summarize Changes
 
 - Note the comparison mode, base branch, and current branch from the result
+- If the comparison is not `uncommitted`, use only the commits in `<changes>.commits` as the branch-work scope
 - Review commit messages when they are available to understand the delivery narrative
-- Read the most relevant changed source files to understand the changes
+- Read the most relevant changed source files to understand the changes introduced by those commits
+- Do not describe work that exists only on the base branch or that is outside the commits ahead of base
 - Group related changes into themes for the final summary
 
 ### Create Ticket
 
 Use `kompass_ticket_sync` with `refUrl` unset to create the ticket:
 - Reuse the same change themes, rationale, and reviewer-facing validation goals from the current summary work
+- For branch comparisons, ensure every theme is supported by commits in `<changes>.commits`; use file diffs only as supporting context
 - Generate a concise title (max 70 chars) that reflects the delivered outcome
 - Generate a `description` that briefly describes what was accomplished and why it matters
 - Generate checklists with: