prr-kit 1.3.0 → 2.0.0

package/src/prr/workflows/2-analyze/collect-pr-context/steps/step-04-build-knowledge-base.md

@@ -16,7 +16,18 @@ Transform collected data into structured knowledge base optimized for reviewers.
 🧠 Building PR-specific knowledge base...
 ```
 
-### 2. Create Knowledge Base Structure
+### 2. Map `manual_context` → `user_instructions`
+
+Using the `manual_context` variable set in step-03:
+
+- **If `manual_context` is null** (user skipped): set `user_instructions.provided = false`, all other fields `null`.
+- **If `manual_context` is not null** (user provided text): set `user_instructions.provided = true`, `raw = manual_context`, then parse the free-form text:
+  - `review_scope` — look for scope signals ("only SR", "skip performance", "security and architecture"). Default `"all"` if none found.
+  - `focus_areas` — extract specific things to prioritize (e.g. "focus on JWT handling" → `["JWT handling"]`). `null` if none.
+  - `custom_requirements` — extract mandatory checks the user stated (e.g. "all endpoints must have auth middleware"). `null` if none.
+  - `context_notes` — extract background info, trade-offs, constraints. `null` if none.
+
+### 3. Create Knowledge Base Structure
 
 Build YAML structure with all collected context:
 
@@ -32,15 +43,19 @@ pr_metadata:
   files_changed: {n}
   collected_at: {ISO timestamp}
 
-# ⚠️  IMPORTANT — Human-provided context from the PR author.
+# ⚠️  IMPORTANT — Human-provided instructions from the user.
 # All reviewers MUST read this section before starting any review.
-# Align all findings and focus areas against this input.
-manual_context:
+# review_scope controls which reviews run. focus_areas, custom_requirements, and context_notes
+# are highest-priority guidance — align all findings against them.
+user_instructions:
   # Populated only when the user provided input in step-03-manual-context-input.
   # If provided: true — treat this content as the highest-priority context in this file.
   provided: {true|false}
-  content: |
-    {manual_context text, or null if not provided}
+  review_scope: {"all" | [SR] | [SR, AR] | ...}   # "all" = run all reviews; list = only those codes
+  focus_areas: {list of strings, or null}           # specific things every reviewer must prioritize
+  custom_requirements: {list of strings, or null}   # mandatory checks the user specified
+  context_notes: {list of strings, or null}         # background info, trade-offs, constraints
+  raw: {original text from user, or null}           # verbatim input
 
 files_analysis:
   changed_files:
@@ -245,7 +260,7 @@ external_context:
 
 review_priorities:
   # Guide reviewers on what to focus on
-  # ⚠️  If manual_context.provided is true — reviewers MUST check findings against it first.
+  # ⚠️  If user_instructions.provided is true — reviewers MUST check findings against user_instructions first.
   critical:
     - "Verify no v-html with user input (security requirement)"
     - "Check ESLint error-level rules compliance"
@@ -261,7 +276,10 @@ review_priorities:
     - "Optional optimizations"
 
 reviewer_guidance:
-  # ⚠️  If manual_context.provided is true — read manual_context BEFORE starting any review.
+  # ⚠️  If user_instructions.provided is true:
+  #     PREPEND each reviewer's list with user_instructions.focus_areas (if any)
+  #     APPEND each reviewer's list with user_instructions.custom_requirements prefixed "MANDATORY: "
+  #     Example: if focus_areas = ["JWT handling"], add "FOCUS: JWT handling" as first item
   general_review:
     - "Check for ESLint rule violations (no-var, prefer-const)"
     - "Verify component naming follows standards"
@@ -281,35 +299,32 @@ reviewer_guidance:
     - "Check Pinia setup function style (not Options API)"
     - "Verify SRP adherence"
 
+  business_review:
+    - "Verify feature matches acceptance criteria"
+    - "Check for user-facing regressions"
+    - "Flag missing observability (logging, metrics) for new flows"
+
 context_sources:
   # Track what sources were used
   primary_docs: [CLAUDE.md, AGENTS.md]
   config_files: [.eslintrc.js, .prettierrc]
   standards_docs: [CONTRIBUTING.md, ARCHITECTURE.md]
   inline_annotations: yes
-  manual_context: {true|false}    # true if user provided input in step-03
+  user_instructions: {true|false}  # true if user provided input in step-03
   mcp_tools: []                   # list of MCP tools actually used
   rag_systems: []                 # list of RAG systems queried
   url_sources: []                 # list of plain URLs fetched
 ```
 
-### 3. Determine Output Filename
+### 3. Output Filename
 
-```javascript
-if (pr_number_available) {
-  filename = `pr-${pr_number}-context.yaml`
-} else {
-  // Use sanitized branch name
-  const safeBranchName = branch_name.replace(/[^a-zA-Z0-9-]/g, '-')
-  filename = `pr-${safeBranchName}-context.yaml`
-}
-```
+Always: `pr-context.yaml` — the session folder already identifies the PR uniquely.
 
 ### 4. Write Knowledge Base to File
 
-Write to: `{review_output}/{filename}`
+Write to: `{session_output}/pr-context.yaml`
 
-Example: `_prr-output/pr-123-context.yaml`
+Example: `_prr-output/reviews/2026-03-02-1430-pr123-feature-auth/pr-context.yaml`
 
 ### 5. Report Completion
 
@@ -322,9 +337,9 @@ Example: `_prr-output/pr-123-context.yaml`
    • ESLint rules: {n}
    • Guidelines: {m}
    • Inline annotations: {k}
-   • Manual context: ⚠️ YES — reviewers will prioritize this ({char_count} chars)
+   • User instructions: ⚠️ YES — scope: {scope}, focus: {focus_count} areas, requirements: {req_count}
      OR
-   • Manual context: none
+   • User instructions: none — full standard review
    • MCP tools used: {mcp_list or "none"}
    • RAG patterns: {rag_count}
    • Issue context: {issue_key or "none"}
@@ -337,17 +352,12 @@ Example: `_prr-output/pr-123-context.yaml`
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-### 6. Store Context Path
-
-Update PR context file to include knowledge base path:
+### 6. Store Knowledge Base Path in Working Context
 
-```yaml
-# {review_output}/current-pr-context.yaml
-pr_knowledge_base: "{review_output}/{filename}"
-```
+Store `pr_knowledge_base` = `{session_output}/pr-context.yaml` in working context.
 
-This allows review workflows to find the knowledge base.
+Review workflows (GR, SR, PR, AR, BR) find the knowledge base via working context or directly at `{session_output}/pr-context.yaml`.
 
 ### 7. Workflow Complete
 
-Mark workflow as complete. Context is ready for use by review workflows (GR, SR, PR, AR).
+Mark workflow as complete. Context is ready for use by review workflows (GR, SR, PR, AR, BR, IC).

package/src/prr/workflows/2-analyze/collect-pr-context/workflow.md

@@ -3,7 +3,7 @@ name: collect-pr-context
 description: "Collect fresh, PR-specific context from multiple sources after describing the PR"
 main_config: "{project-root}/_prr/prr/config.yaml"
 nextStep: "./steps/step-01-analyze-files.md"
-output_file: "{review_output}/pr-{pr_number}-context.yaml"
+output_file: "{session_output}/pr-context.yaml"
 ---
 
 # Collect PR-Specific Context Workflow
@@ -26,8 +26,10 @@ output_file: "{review_output}/pr-{pr_number}-context.yaml"
 
 ## WHEN TO RUN
 
-**Automatically** after [DP] Describe PR in the quick workflow.
-Runs before any review workflows to provide fresh context.
+**In [QR] Quick Review:** runs automatically as Phase 2.5 — no manual step needed.
+
+**In standalone mode:** run manually after [DP] Describe PR and before starting any review workflow (GR/SR/PR/AR/BR).
+The master agent will remind you to run context collection if you attempt to start a review without it.
 
 ## CONTEXT SOURCES
 
@@ -108,16 +110,14 @@ If a stack has no matching data file, skip it silently and proceed with general
 4-step process:
 1. **Analyze files** changed in PR — extract metadata, domains, and **detect technology stacks**
 2. **Collect context** from all sources: primary docs, config files, standards docs, inline annotations, **stack-specific rules**, MCP tools, RAG systems
-3. **Manual context input** — prompt the user for any additional context (business rationale, focus areas, known trade-offs). Skip automatically if `context_collection.skip_manual_input_context: true` in config. If the user provides input, it is marked **⚠️ IMPORTANT** and reviewers treat it as highest-priority context
+3. **Manual context input** — prompt the user for any additional context (business rationale, focus areas, known trade-offs). **Always runs — user must respond before continuing.** If the user provides input, it is marked **⚠️ IMPORTANT** and reviewers treat it as highest-priority context
 4. **Build PR-specific knowledge base** — structured YAML with all context, stack rules, manual context, and reviewer guidance
 
 ## INITIALIZATION
 
 Load config from `{main_config}`.
 
-Check if PR number is available:
-- If available: use `pr-{pr_number}-context.yaml`
-- If not: use `pr-{branch_name}-context.yaml`
+Output filename is always `pr-context.yaml` — the session folder already identifies the PR uniquely.
 
 ## EXECUTION
 

package/src/prr/workflows/2-analyze/describe-pr/steps/step-01-load-context.md

@@ -14,11 +14,11 @@ Load the PR context file and the actual code diff for analysis.
 
 ### 1. Load PR Context
 
-Read `{review_output}/current-pr-context.yaml`.
+Use `session_output`, `target_branch`, `base_branch`, `pr_number` from working context.
 
-If file not found:
+If not set:
 ```
-❌ No PR selected yet. Please run [SP] Select PR first.
+❌ No active session. Run [SS] Select Session to resume a past session, or [SP] Select PR to start a new one.
 ```
 Stop workflow.
 

package/src/prr/workflows/2-analyze/describe-pr/steps/step-04-output.md

@@ -1,7 +1,7 @@
 ---
 name: "step-04-output"
 description: "Write PR description to file and display summary"
-outputFile: "{review_output}/pr-description-{date}.md"
+outputFile: "{session_output}/pr-description.md"
 templateFile: "../templates/pr-description.template.md"
 ---
 
@@ -24,14 +24,13 @@ Using the template at `{templateFile}`, generate the PR description with:
 
 ### 2. Write to File
 
-Write to `{outputFile}` (replace {date} with actual date: YYYY-MM-DD).
+Write to `{outputFile}`.
 
-### 3. Update PR Context
+### 3. Update Working Context
 
-Update `{review_output}/current-pr-context.yaml`:
-- Add `description_generated: true`
-- Add `pr_type: "{classified_type}"`
-- Add `risk_level: "{risk_level}"`
+Store in working context:
+- `pr_type` = `{classified_type}`
+- `risk_level` = `{risk_level}`
 
 ### 4. Display Summary
 
@@ -45,6 +44,11 @@ Summary:
 
 Recommended next steps:
 {recommended_reviews}
+
+💡 Before reviewing: run [CC] Collect Context to build a fresh PR-specific knowledge base.
+   Reviews use this context to apply your project's rules, stack-specific guidelines, and any
+   external sources (Jira, Confluence, Figma) — skipping it means reviewers work with
+   general rules only.
 ```
 
 Workflow complete. Return to agent menu.

package/src/prr/workflows/2-analyze/describe-pr/workflow.md

@@ -20,8 +20,8 @@ nextStep: "./steps/step-01-load-context.md"
 ## INITIALIZATION
 
 Load config from `{main_config}`.
-Load PR context from `{review_output}/current-pr-context.yaml`.
-If context file does not exist, instruct user to run [SP] Select PR first.
+Use `session_output`, `target_branch`, `base_branch`, `pr_number` from working context.
+If not set: prompt user to run [SS] Select Session (to resume a past session) or [SP] Select PR (to start a new one).
 
 ## EXECUTION
 

package/src/prr/workflows/3-review/architecture-review/checklist.md

@@ -22,5 +22,4 @@ validation-target: "Architecture review output file"
 - [ ] ❓ QUESTION findings include: specific question + list of potentially affected files outside the diff
 
 ## Output
-- [ ] Findings written to `{review_output}/architecture-review-{date}.md`
-- [ ] PR context updated with `architecture-review` in completed list
+- [ ] Findings written to `{session_output}/architecture-review.md`

package/src/prr/workflows/3-review/architecture-review/instructions.xml

@@ -98,7 +98,7 @@ Context: Loaded architectural patterns & ADRs from project docs
   </step>
 
   <step n="7" goal="Compile and write findings">
-    <action>Group findings: Layer Violations | Coupling Issues | Consistency Problems | SOLID Violations | ❓ Questions for Author</action>
+    <action>Group findings: Layer Violations | Coupling Issues | Consistency Problems | Blast Radius &amp; Breaking Changes | SOLID Violations | ❓ Questions for Author</action>
     <action>For each finding: reference the EXISTING pattern that should be followed instead</action>
     <action>Write findings to {output_file}</action>
     <action>Update {pr_context}: add 'architecture-review' to completed list</action>

package/src/prr/workflows/3-review/architecture-review/workflow.yaml

@@ -7,11 +7,12 @@ user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
 target_repo: "{config_source}:target_repo"
 review_output: "{config_source}:review_output"
+session_output: "working-context:session_output || latest-session-folder-in:{review_output}"
 date: system-generated
 
 installed_path: "{project-root}/_prr/prr/workflows/3-review/architecture-review"
 instructions: "{installed_path}/instructions.xml"
 validation: "{installed_path}/checklist.md"
 
-pr_context: "{review_output}/current-pr-context.yaml"
-output_file: "{review_output}/architecture-review-{date}.md"
+pr_context: "working-context:target_branch,base_branch,pr_number,pr_knowledge_base"
+output_file: "{session_output}/architecture-review.md"

package/src/prr/workflows/3-review/business-review/checklist.md

@@ -23,5 +23,4 @@ validation-target: "Business review output file"
 - [ ] Post-ship monitoring noted: what to watch after deploy
 
 ## Output
-- [ ] Findings written to `{review_output}/business-review-{date}.md`
-- [ ] PR context updated with `business-review` in completed list
+- [ ] Findings written to `{session_output}/business-review.md`

package/src/prr/workflows/3-review/business-review/workflow.yaml

@@ -7,11 +7,12 @@ user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
 target_repo: "{config_source}:target_repo"
 review_output: "{config_source}:review_output"
+session_output: "working-context:session_output || latest-session-folder-in:{review_output}"
 date: system-generated
 
 installed_path: "{project-root}/_prr/prr/workflows/3-review/business-review"
 instructions: "{installed_path}/instructions.xml"
 validation: "{installed_path}/checklist.md"
 
-pr_context: "{review_output}/current-pr-context.yaml"
-output_file: "{review_output}/business-review-{date}.md"
+pr_context: "working-context:target_branch,base_branch,pr_number,pr_knowledge_base,pr_type,completed_reviews"
+output_file: "{session_output}/business-review.md"

package/src/prr/workflows/3-review/general-review/checklist.md

@@ -22,6 +22,5 @@ validation-target: "General review output file"
 - [ ] Side effect findings include: the affected location OUTSIDE the diff (not just the changed file)
 
 ## Output
-- [ ] Findings written to `{review_output}/general-review-{date}.md`
-- [ ] PR context updated with `general-review` in completed list
+- [ ] Findings written to `{session_output}/general-review.md`
 - [ ] At least one positive observation included (balanced review)

package/src/prr/workflows/3-review/general-review/workflow.yaml

@@ -7,11 +7,12 @@ user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
 target_repo: "{config_source}:target_repo"
 review_output: "{config_source}:review_output"
+session_output: "working-context:session_output || latest-session-folder-in:{review_output}"
 date: system-generated
 
 installed_path: "{project-root}/_prr/prr/workflows/3-review/general-review"
 instructions: "{installed_path}/instructions.xml"
 validation: "{installed_path}/checklist.md"
 
-pr_context: "{review_output}/current-pr-context.yaml"
-output_file: "{review_output}/general-review-{date}.md"
+pr_context: "working-context:target_branch,base_branch,pr_number,pr_knowledge_base"
+output_file: "{session_output}/general-review.md"

package/src/prr/workflows/3-review/performance-review/checklist.md

@@ -20,5 +20,4 @@ validation-target: "Performance review output file"
 - [ ] ❓ QUESTION findings include: specific concern + context needed to assess severity (e.g., "Is this in a hot path?", "What is the expected data volume?")
 
 ## Output
-- [ ] Findings written to `{review_output}/performance-review-{date}.md`
-- [ ] PR context updated with `performance-review` in completed list
+- [ ] Findings written to `{session_output}/performance-review.md`

package/src/prr/workflows/3-review/performance-review/workflow.yaml

@@ -7,11 +7,12 @@ user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
 target_repo: "{config_source}:target_repo"
 review_output: "{config_source}:review_output"
+session_output: "working-context:session_output || latest-session-folder-in:{review_output}"
 date: system-generated
 
 installed_path: "{project-root}/_prr/prr/workflows/3-review/performance-review"
 instructions: "{installed_path}/instructions.xml"
 validation: "{installed_path}/checklist.md"
 
-pr_context: "{review_output}/current-pr-context.yaml"
-output_file: "{review_output}/performance-review-{date}.md"
+pr_context: "working-context:target_branch,base_branch,pr_number,pr_knowledge_base"
+output_file: "{session_output}/performance-review.md"

package/src/prr/workflows/3-review/security-review/checklist.md

@@ -22,5 +22,4 @@ validation-target: "Security review output file"
 - [ ] ❓ QUESTION findings include: specific concern + exact question to ask author (e.g., "Was this auth check intentionally removed?")
 
 ## Output
-- [ ] Findings written to `{review_output}/security-review-{date}.md`
-- [ ] PR context updated with `security-review` in completed list
+- [ ] Findings written to `{session_output}/security-review.md`

package/src/prr/workflows/3-review/security-review/workflow.yaml

@@ -7,6 +7,7 @@ user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
 target_repo: "{config_source}:target_repo"
 review_output: "{config_source}:review_output"
+session_output: "working-context:session_output || latest-session-folder-in:{review_output}"
 date: system-generated
 
 installed_path: "{project-root}/_prr/prr/workflows/3-review/security-review"
@@ -14,5 +15,5 @@ instructions: "{installed_path}/instructions.xml"
 validation: "{installed_path}/checklist.md"
 owasp_data: "{installed_path}/data/owasp-checklist.csv"
 
-pr_context: "{review_output}/current-pr-context.yaml"
-output_file: "{review_output}/security-review-{date}.md"
+pr_context: "working-context:target_branch,base_branch,pr_number,pr_knowledge_base"
+output_file: "{session_output}/security-review.md"

package/src/prr/workflows/4-improve/improve-code/checklist.md

@@ -13,6 +13,5 @@ validation-target: "Improve code output file"
 - [ ] Suggestions are correct — the AFTER code actually works
 
 ## Output
-- [ ] All suggestions written to `{review_output}/improve-code-{date}.md`
+- [ ] All suggestions written to `{session_output}/improve-code.md`
 - [ ] Suggestions grouped by category (Bugs | Quality | Performance | Best Practices)
-- [ ] PR context updated with `improve-code` in completed list

package/src/prr/workflows/4-improve/improve-code/workflow.yaml

@@ -7,11 +7,12 @@ user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
 target_repo: "{config_source}:target_repo"
 review_output: "{config_source}:review_output"
+session_output: "working-context:session_output || latest-session-folder-in:{review_output}"
 date: system-generated
 
 installed_path: "{project-root}/_prr/prr/workflows/4-improve/improve-code"
 instructions: "{installed_path}/instructions.xml"
 validation: "{installed_path}/checklist.md"
 
-pr_context: "{review_output}/current-pr-context.yaml"
-output_file: "{review_output}/improve-code-{date}.md"
+pr_context: "working-context:target_branch,base_branch,pr_number,pr_knowledge_base"
+output_file: "{session_output}/improve-code.md"

package/src/prr/workflows/5-ask/ask-code/steps/step-01-load-context.md

@@ -10,9 +10,9 @@ nextStepFile: "./step-02-answer.md"
 
 ### 1. Load PR Context
 
-Read `{review_output}/current-pr-context.yaml`.
+Use `session_output`, `target_branch`, `base_branch` from working context.
 
-If not found, prompt user to run [SP] Select PR first.
+If not set, prompt user to run [SS] Select Session or [SP] Select PR first.
 
 ### 2. Load the Diff
 

package/src/prr/workflows/6-report/generate-report/steps/step-01-collect.md

@@ -8,19 +8,23 @@ nextStepFile: "./step-02-organize.md"
 
 ## Sequence of Instructions
 
-### 1. Load PR Context
+### 1. Detect Completed Reviews
 
-Read `{review_output}/current-pr-context.yaml` to get list of completed reviews.
+Check which review files exist in `{session_output}/`:
+
+```bash
+ls "{session_output}/"
+```
 
 ### 2. Collect Review Output Files
 
-For each completed review in `review.completed` list, read the corresponding output file:
-- `general-review` → `{review_output}/general-review-*.md` (latest)
-- `security-review` → `{review_output}/security-review-*.md` (latest)
-- `performance-review` → `{review_output}/performance-review-*.md` (latest)
-- `architecture-review` → `{review_output}/architecture-review-*.md` (latest)
-- `business-review` → `{review_output}/business-review-*.md` (latest)
-- `improve-code` → `{review_output}/improve-code-*.md` (latest)
+For each review file that exists, read it:
+- `general-review` → `{session_output}/general-review.md`
+- `security-review` → `{session_output}/security-review.md`
+- `performance-review` → `{session_output}/performance-review.md`
+- `architecture-review` → `{session_output}/architecture-review.md`
+- `business-review` → `{session_output}/business-review.md`
+- `improve-code` → `{session_output}/improve-code.md`
 
 ### 3. Parse All Findings
 
@@ -37,6 +41,12 @@ From each file, extract all findings with their:
 - `🟢` or `Low` → Suggestion
 - `❓` → Question (collect separately — do not count as blocker/warning/suggestion)
 
+**Special handling — `improve-code.md`:**
+The improve-code output uses `[CATEGORY]` format (`[BUGS]`, `[QUALITY]`, `[PERFORMANCE]`, `[BEST-PRACTICES]`), not severity emojis. Treat improve-code findings as a separate collection:
+- Do NOT mix them into the Blockers/Warnings/Suggestions counts
+- Include them in the report's **💡 Code Improvement Suggestions** section (see template)
+- Map `[BUGS]` → 🔴 only if the improve-code entry describes an actual bug that could cause incorrect behavior; otherwise keep as 💡 Improvement
+
 ### 4. Count Statistics
 
 Count:

package/src/prr/workflows/6-report/generate-report/steps/step-03-write.md

@@ -1,7 +1,7 @@
 ---
 name: "step-03-write"
 description: "Write the final review report to file"
-outputFile: "{review_output}/review-{target_branch_slug}-{date}.md"
+outputFile: "{session_output}/final-review.md"
 templateFile: "../templates/review-report.template.md"
 ---
 
@@ -27,7 +27,7 @@ The report includes:
 ```
 ✅ Review Report Generated!
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-📄 File: {review_output}/review-{target_branch_slug}-{date}.md
+📄 File: {session_output}/final-review.md
 
 Summary:
   🔴 Blockers: {blocker_count}

package/src/prr/workflows/6-report/generate-report/workflow.md

@@ -19,7 +19,8 @@ nextStep: "./steps/step-01-collect.md"
 ## INITIALIZATION
 
 Load config from `{main_config}`.
-Load PR context from `{review_output}/current-pr-context.yaml`.
+Use `session_output` from working context.
+If not set: prompt user to run [SS] Select Session or [SP] Select PR first.
 
 ## EXECUTION
 

package/src/prr/workflows/6-report/post-comments/steps/step-01-format.md

@@ -10,9 +10,9 @@ nextStepFile: "./step-02-post.md"
 
 ### 1. Check Prerequisites
 
-Verify `{review_output}/current-pr-context.yaml` exists and contains:
-- `pr_number` — if missing, show: `❌ No PR number found. Run [SP] Select PR first.`
-- `target_branch`, `base_branch`
+Verify working context contains:
+- `pr_number` — if missing, show: `❌ No PR number found. Run [SS] Select Session or [SP] Select PR first.`
+- `target_branch`, `base_branch`, `session_output`
 
 Verify platform CLI is available:
 
@@ -54,8 +54,20 @@ Store as `{commit_sha}`.
 
 ### 3. Load Review Report
 
-Find the latest report in `{review_output}/review-*.md`.
-Sort by modification time, take the most recent.
+Check that `{session_output}/final-review.md` exists:
+```bash
+ls "{session_output}/final-review.md"
+```
+
+If it does NOT exist:
+```
+❌ No report found at {session_output}/final-review.md
+   Run [RR] Generate Report first to compile all findings into a report,
+   then run [PC] Post Comments to post them.
+```
+Stop workflow.
+
+Read the report at `{session_output}/final-review.md`.
 
 ### 4. Parse All Findings
 

package/src/prr/workflows/6-report/post-comments/steps/step-02-post.md

@@ -74,21 +74,40 @@ done
 ---
 
 **Bitbucket:**
+
+**⚠️ Do NOT embed `$(cat ...)` in curl `-d` — the summary body contains emojis and backticks that will break shell expansion.**
+
+Use the runtime script approach to build the summary payload first:
+
+Write `{temp_dir}/build-bb-summary.mjs` (or `.py`) using the Write tool:
+
+```js
+// Node.js
+import { readFileSync, writeFileSync } from 'fs'
+const body = readFileSync("{temp_dir}/prr-summary.md", "utf-8")
+const payload = { content: { raw: body } }
+writeFileSync("{temp_dir}/prr-bb-summary.json", JSON.stringify(payload, null, 2), "utf-8")
+console.log("OK: summary payload written")
+```
+
+Execute: `node "{temp_dir}/build-bb-summary.mjs"`
+
+Then post using `--data @`:
 ```bash
 # Post summary
 curl -s -X POST \
   "https://api.bitbucket.org/2.0/repositories/{platform_repo}/pullrequests/{pr_number}/comments" \
   -H "Authorization: Bearer {BB_TOKEN}" \
   -H "Content-Type: application/json" \
-  -d "{\"content\": {\"raw\": \"$(cat '{temp_dir}/prr-summary.md')\"}}"
+  --data "@{temp_dir}/prr-bb-summary.json"
 
 # Post each inline comment
-for payload in "{temp_dir}/prr-bb-"*.json; do
+for payload in "{temp_dir}/prr-bb-"[0-9]*.json; do
   curl -s -X POST \
     "https://api.bitbucket.org/2.0/repositories/{platform_repo}/pullrequests/{pr_number}/comments" \
     -H "Authorization: Bearer {BB_TOKEN}" \
     -H "Content-Type: application/json" \
-    -d "@$payload"
+    --data "@$payload"
 done
 ```
 
@@ -146,8 +165,12 @@ rm -f "{temp_dir}/prr-payload.json" \
        "{temp_dir}/prr-summary.md" \
        "{temp_dir}/prr-thread-"*.json \
        "{temp_dir}/prr-bb-"*.json \
+       "{temp_dir}/prr-bb-summary.json" \
        "{temp_dir}/build-payload.mjs" \
-       "{temp_dir}/build-payload.py"
+       "{temp_dir}/build-payload.py" \
+       "{temp_dir}/build-bb-summary.mjs" \
+       "{temp_dir}/build-bb-summary.py"
+rmdir "{temp_dir}" 2>/dev/null || true
 ```
 
 ---

package/src/prr/workflows/6-report/post-comments/workflow.md

@@ -37,10 +37,11 @@ Depends on `{active_platform}`:
 ## INITIALIZATION
 
 Load config from `{main_config}`.
-Load PR context from `{review_output}/current-pr-context.yaml`.
+Use `session_output`, `target_branch`, `base_branch`, `pr_number`, `active_platform` from working context.
+If `session_output` not set: prompt user to run [SS] Select Session or [SP] Select PR first.
 Use `{active_platform}` (or detect from `{platform}` config).
 
-Set `{temp_dir}` = `{review_output}/temp`.
+Set `{temp_dir}` = `{session_output}/temp`.
 Create it if it doesn't exist:
 ```bash
 mkdir -p "{temp_dir}"