Merge pull request #19 from unic/feature/pre-review/doc-context-enrichment

feat(pr-review): re-review feature v0.8.0 + doc context enrichment planning

Author: orioltf

.prettierignore

@@ -23,3 +23,6 @@ apps/claude-code/pr-review/docs/plans/
 apps/claude-code/auto-format/docs/plans/
 apps/claude-code/unic-confluence/docs/plans/
 .agents/skills/
+
+# Plugin changelogs — em-dash dates must not be reflowed
+**/CHANGELOG.md

apps/claude-code/auto-format/ralph.yml

@@ -1,16 +1,16 @@
 # Ralph Orchestrator Configuration
-# Generated for: unic-claude-code-format
+# Generated by: ralph init --backend claude
+# Project: unic-auto-format
 # Docs: https://github.com/mikeyobrien/ralph-orchestrator
 
 cli:
-  backend: "claude"
+  backend: 'claude'
 
 event_loop:
-  prompt_file: "PROMPT.md"
-  completion_promise: "LOOP_COMPLETE"
-  max_iterations: 100
-  max_runtime_seconds: 14400 # 4 hours max
-
+  prompt_file: 'PROMPT.md'
+  completion_promise: 'LOOP_COMPLETE'
+  max_iterations: 100 # 15 specs * generous retry budget
+  max_runtime_seconds: 28800 # 8 hours; abort if a spec stalls
 
 # ─────────────────────────────────────────────────────────────────────────────
 # Additional Configuration (uncomment to customize)

apps/claude-code/pr-review/.claude-plugin/marketplace.json

@@ -21,7 +21,7 @@
       "name": "pr-review",
       "source": "./",
       "tags": ["code-quality", "azure-devops"],
-      "version": "0.1.2"
+      "version": "0.8.0"
     }
   ]
 }

apps/claude-code/pr-review/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-review",
-  "version": "0.1.2",
+  "version": "0.8.0",
   "description": "Review Azure DevOps pull requests with multi-agent analysis and post threaded comments back to the PR.",
   "author": {
     "name": "Unic AG",

apps/claude-code/pr-review/CHANGELOG.md

@@ -3,17 +3,124 @@
 ## [Unreleased]
 
 ### Breaking
+- (none)
+
+### Added
+- (none)
+
+### Fixed
+- (none)
+
+## [0.8.0] — 2026-05-06
+
+### Breaking
+- (none)
+
+### Added
+- Re-review: detect prior Claude Code threads in Step 3.5; set `IS_REREVIEW`, `PRIOR_THREADS_FILE`, `SUMMARY_THREAD_ID`, and `PRIOR_ITERATION_ID`; normalize signature format to `🤖 *Reviewed by Claude Code* — Iteration N` for detection and iteration targeting (specs 01–02)
+- Re-review: resolve `LATEST_ITERATION_ID` and `LATEST_COMMIT_ID` from PR iterations API; compute `PRIOR_COMMIT_ID` from prior review signature; replace hardcoded `iterationId=1` (spec 03)
+- Re-review: incremental diff between `PRIOR_COMMIT_ID` and `LATEST_COMMIT_ID` in Step 5; early exit with pending thread list when no new commits detected (spec 04)
+- Re-review: classify each prior bot thread as `addressed`, `disputed`, `pending`, or `obsolete` in Step 5.5; detect deleted-file threads as `obsolete` (spec 05)
+- Re-review: reply to existing bot threads instead of posting new duplicates in Step 10; apply per-classification actions and post run-completion marker on every successful run (spec 06)
+- Re-review: skip full summary when no new or addressed findings; post delta reply (counts + new finding bullets) to existing summary thread; fall back to full summary if prior summary thread was deleted (spec 07)
+
+### Fixed
+- (none)
+
+## [0.7.0] — 2026-05-06
+
+### Breaking
+- (none)
+
+### Added
+- On re-review, skip full summary when nothing changed; post delta reply (counts + new finding bullet list) to existing summary thread when findings exist; fall back to full summary if prior summary thread was deleted (spec 07)
+
+### Fixed
+- (none)
+
+## [0.6.0] — 2026-05-06
+
+### Breaking
+- (none)
+
+### Added
+- Reply to existing bot threads instead of duplicating them on re-review: match prior threads by file path and line-range overlap (±3 line drift), branch Step 10 on `IS_REREVIEW`, apply per-classification actions (skip `pending`, reply `disputed`/`addressed`, ignore `obsolete`), post run-completion marker on every successful run (spec 06)
+
+### Fixed
+- (none)
+
+## [0.5.0] — 2026-05-06
+
+### Breaking
+- (none)
+
+### Added
+- Classify each prior bot thread as `addressed`, `disputed`, `pending`, or `obsolete` in Step 5.5; print summary count before Step 6; detect deleted-file threads as `obsolete` (spec 05)
+
+### Fixed
+- (none)
+
+## [0.4.0] — 2026-05-06
+
+### Breaking
+- (none)
+
+### Added
+- Branch Step 5 on `IS_REREVIEW`: incremental diff between `PRIOR_COMMIT_ID` and `LATEST_COMMIT_ID` for re-reviews; early exit with pending thread list when no new commits; fallback warnings with both commit IDs on fetch failure or missing commit IDs; hunk boundaries exported to `DIFF_HUNKS_FILE` for spec 05 (spec 04)
+
+### Fixed
+- (none)
+
+## [0.3.0] — 2026-05-06
 
+### Breaking
+- (none)
+
+### Added
+- Fetch PR iterations to resolve `LATEST_ITERATION_ID` and `LATEST_COMMIT_ID`; replace hardcoded `iterationId=1` in Step 4; add `PRIOR_COMMIT_ID` resolution for re-review mode (spec 03)
+
+### Fixed
+- (none)
+
+## [0.2.1] — 2026-05-06
+
+### Breaking
 - (none)
 
 ### Added
+- (none)
+
+### Fixed
+- Set `isSummaryThread` flag only on the most-recent prior summary thread (not all matching threads) to avoid ambiguity in re-review targeting
+
+## [0.2.0] — 2026-05-06
+
+### Breaking
 
 - (none)
 
+### Added
+
+- Added Step 3.5 (Detect prior review): paginated fetch of all PR threads, bot-comment detection via signature prefix, and export of `IS_REREVIEW`, `PRIOR_THREADS_FILE`, `SUMMARY_THREAD_ID`, and `PRIOR_ITERATION_ID` for use by later re-review steps
+
 ### Fixed
 
 - (none)
 
+## [0.1.3] — 2026-05-06
+
+### Breaking
+
+- (none)
+
+### Added
+
+- (none)
+
+### Fixed
+
+- Normalized all emitted comment signatures to asterisk italics and added `— Iteration {LATEST_ITERATION_ID}` suffix; documented detection prefix in Notes and Comment signature sections
+
 ## [0.1.2] — 2026-04-30
 
 ### Breaking

apps/claude-code/pr-review/CLAUDE.md

@@ -34,9 +34,9 @@ When bumping the version, update it in **both** files:
 
 - YAML frontmatter declares `allowed-tools` — add any new tools the command needs there
 - Auto-generated files are explicitly skipped in Step 6 (serialization YAMLs, `*.g.cs`, generated types output, `swagger.md`)
-- All comments posted to ADO **must** end with the exact signature: `---\n🤖 *Reviewed by Claude Code*`
+- All comments posted to ADO **must** end with the exact signature: `---\n🤖 *Reviewed by Claude Code* — Iteration N` (where N = LATEST_ITERATION_ID)
 - Inline threads use ADO REST `pullRequestThreads` via `az devops invoke`; file paths must match ADO format (leading `/`, forward slashes)
-- `iterationId=1` is always used unless there's a specific reason to target a later iteration
+- Always use the latest iteration of the PR. `iterationId=1` is never used. Re-reviews additionally compute `PRIOR_ITERATION_ID` from the prior review's signature — see spec 02.
 - If `az devops invoke` returns a `threadContext` error, fall back to posting without `threadContext` (general comment)
 
 ## External dependencies
@@ -64,5 +64,4 @@ Then add `"pr-review@unic": true` to `enabledPlugins` and restart Claude Code.
 
 - GitHub PR support
 - Vote on PR (approve/reject) after review
-- Re-review: detect existing Claude Code threads and update instead of duplicating
 - PR description generation from diff

apps/claude-code/pr-review/CONTEXT.md

@@ -59,6 +59,16 @@ _Avoid_: response, follow-up comment
 A fixed text marker appended to every Plugin-authored comment, used to identify Review Threads and Replies created by this Plugin.
 _Avoid_: watermark, marker, signature
 
+### Doc context enrichment
+
+**Doc Context**:
+The aggregated summaries of linked work items and Confluence pages passed to Review Aspect agents as background on the business intent of the PR. Produced before the review phase and injected as a preamble into each agent's prompt.
+_Avoid_: ticket context, background info, extra context
+
+**Doc Context Sub-agent**:
+A short-lived agent spawned to fetch and summarise a single source — either a work item description or a Confluence page — in a diff-aware way. Multiple Doc Context Sub-agents run in parallel; their outputs are merged into the Doc Context.
+_Avoid_: context agent, doc agent, fetcher agent
+
 ### Re-review classification
 
 **Thread Classification**:
@@ -85,6 +95,8 @@ A Thread Classification state. The relevant code was deleted or moved; the comme
 - A **Reply** is added to an existing **Review Thread** — it does not open a new one
 - The **Bot Signature** is present on every comment authored by the Plugin, enabling prior-review detection
 - A **Revision** is the code snapshot a **Review** or **Re-review** analyses
+- A **Doc Context** is assembled by one or more **Doc Context Sub-agents** before the Review phase and injected into every Review Aspect agent
+- A **Doc Context Sub-agent** operates on a single source (work item or Confluence page) and receives the changed files list and the local diff when available
 
 ## Example dialogue
 

apps/claude-code/pr-review/PROMPT.md

@@ -4,7 +4,7 @@ You are implementing the **re-review** capability for the `unic-pr-review` plugi
 
 ## Step 1 — Determine what's next
 
-Open `docs/plans/README.md`. Scan spec files in order (00 → 09) and find the first file whose status is **not** `done`.
+Open `docs/plans/README.md`. Scan spec files in order and find the first file whose status is **not** `done` nor `ignore`.
 
 If **all** specs contain `**Status: done**`, output exactly:
 

apps/claude-code/pr-review/README.md

@@ -11,7 +11,7 @@ Run `/pr-review:review-pr <ADO-PR-URL>` to:
 3. Post each finding as an inline comment at the exact file and line in the ADO web UI
 4. Post a summary comment with severity-grouped findings and positive observations
 
-All comments are signed `🤖 *Reviewed by Claude Code*` so reviewers know they are AI-generated.
+All comments are signed `🤖 *Reviewed by Claude Code* — Iteration N` so reviewers know they are AI-generated and can track which review iteration produced each finding.
 
 ---
 
@@ -127,18 +127,39 @@ Every comment posted to the PR ends with:
 
 ```
 ---
-🤖 *Reviewed by Claude Code*
+🤖 *Reviewed by Claude Code* — Iteration N
 ```
 
-This consistent signature lets team members immediately identify AI-generated review comments.
+This consistent signature lets team members immediately identify AI-generated review comments and track which review iteration produced each finding.
+
+---
+
+## Re-review
+
+Running `/pr-review:review-pr <url>` on a PR that already has Claude Code review threads triggers re-review mode automatically.
+
+**What changes in re-review mode:**
+
+- **Detection** — Step 3.5 scans all existing PR threads for the bot signature and extracts their file paths, line ranges, and classification metadata.
+- **Thread reuse** — New findings are posted as replies to the matching prior thread (matched by file path and line-range overlap ±3 lines) rather than creating duplicate threads.
+- **Classification** — Each prior thread is classified as `addressed` (resolved), `disputed` (active disagreement), `pending` (still open), or `obsolete` (file deleted or lines moved far).
+- **Incremental diff** — The diff is computed between the prior review's commit and the latest commit, so only new changes are analysed.
+- **Delta summary** — Instead of a full summary, a short reply is posted to the existing summary thread listing new findings and counts. If nothing changed, no summary is posted.
+- **Completion marker** — Every successful run appends a completion marker to the summary thread so subsequent runs can detect partial-run failures.
+
+**Signature format:** `🤖 *Reviewed by Claude Code* — Iteration N` (N = ADO PR iteration number).
+
+**Known limitations:**
+
+- Force-push that rewrites history falls back to a full diff (prior commit no longer exists in the remote).
+- If a run was interrupted before posting the completion marker, the next run treats it as a partial run and skips to a recovery path.
 
 ---
 
 ## Roadmap
 
 - **GitHub PR support** — detect `https://github.com/...` URLs and route to `gh pr review`
 - **Vote on PR** — optionally set approval/rejection after review
-- **Re-review** — detect existing Claude Code threads and update rather than duplicate
 - **PR description generation** — generate a PR description from the diff
 
 ---