feat(unic-pr-review): surface existing Human Threads as read-only review context

[orioltf]

What to build

unic-pr-review currently fetches every ADO PR Thread but only ever classifies them bot-vs-not (Iteration Marker, ADR-0006). In first-review the Threads are then dropped; in re-review only Bot Threads feed the Re-review Coordinator. Human review discussion is invisible to a Review in every Mode.

Found comparing pr-review (legacy) vs unic-pr-review on ADO PR #5570: the legacy plugin read the 5 Human Threads (#63474–63478), cross-referenced a Finding to a still-open one, and caught a Thread marked fixed whose issue was still present ("re-verify"). v2 surfaced none of it.

Make Human Threads read-only review context, surfaced after the aspect fan-out. The full design is locked in ADR-0016 (docs/adr/0016-human-threads-as-read-only-context.md); CONTEXT.md now defines Human Thread and System Thread. Build to those.

Behaviour:

• Classify Threads three ways in the ADO Fetcher: Bot (Iteration Marker), System (comments[0].commentType === "system"), Human (neither). Only Human Threads are surfaced; System Threads never reach the Reviewer.
• Post-fan-out match (deterministic, pure function): map Findings to Human Threads by filePath + line proximity. Aspect agents stay unchanged (no prompt injection, no Spawn-Set / ADR-0008 change).
• Annotate a matched Finding ("overlaps open Human Thread #N"). Resolved-but-matched → "Thread #N marked fixed but issue still present — re-verify".
• Notice: unresolved (active/pending) Human Threads that no Finding matched, plus unresolved non-inline (no threadContext) Threads, are listed in a Notice above the Intent Check. Resolved Threads (fixed/wontFix/closed/byDesign) are NOT listed.
• Never suppress: a Finding is never dropped or down-ranked because a Human Thread exists — Confidence < 60 (ADR-0002) stays the sole filter.
• Both Modes: first-review (+first-review-fallback) and re-review. In re-review the Coordinator additionally receives a read-only humanThreads input but emits zero threadActions for them.
• Never write to a Human Thread in any Mode — the ADO Writer only ever targets Bot Threads. Pre-PR Mode unaffected (no ADO Threads).

Acceptance criteria

• ADO Fetcher emits a classified Human Thread list ({ threadId, filePath, startLine, status, excerpt }), distinct from priorFindings; System Threads excluded.
• On PR #5570 the 5 Human Threads (#63474–63478) are classified human; the System (RefUpdate) Threads are not surfaced.
• A pure, tested matching function annotates Findings overlapping a Human Thread by filePath+line proximity, with the resolved-thread "re-verify" wording when status is resolved.
• Unresolved unmatched Human Threads (incl. non-inline) appear in a Notice above the Intent Check; resolved Threads do not.
• No Finding is suppressed or down-ranked by a Human Thread (Confidence < 60 remains the only filter).
• Re-review Coordinator accepts a read-only humanThreads input and emits no threadActions referencing a Human Thread; ADO Writer never posts to a Human Thread.
• Docs reflect shipped behaviour: README.md "How it works" prose + mermaid flowchart updated (Human-Thread classify step, the new Notice render path at Step 8, the Coordinator's read-only humanThreads input, and the w2 writer box clarified to bot threads only — never human); CHANGELOG.md entry added at version bump. ADR-0016 + CONTEXT.md already landed and need no change.
• pnpm --filter unic-pr-review test + pnpm typecheck pass; pnpm ci:check clean.

Blocked by

None — can start immediately. Independent of #247 (work-item discovery), though both were found in the same PR #5570 comparison. ADR-0016 + CONTEXT.md terms already merged as the design source of truth.

[orioltf]

✅ Issue Resolution Report

PR: #250 (#250)
Version: 2.1.11
Status: COMPLETE

---

Summary

ADR-0016 is now fully wired end-to-end. The pre-built human-thread-matcher.mjs and notices.mjs library modules were connected to the review-pr.md orchestrator via three targeted edits (humanThreads → Coordinator, Step 1.8b first-review, Step 1.8b extension re-review). README.md was updated with new prose and mermaid flowchart changes reflecting the Human Thread classify step, Notice render path, Coordinator read-only input, and ADO Writer bot-threads-only constraint. All CI checks passed.

---

Changes Made

File	Change
commands/review-pr.md	3 orchestrator edits: humanThreads to Coordinator input, Step 1.8b (first-review), Step 1.8b extension (re-review)
README.md	ADR-0016 prose paragraph + 4 mermaid node/edge changes
CHANGELOG.md	[2.1.11] Added entry
scripts/lib/human-thread-matcher.mjs	CLI matcher (committed)
tests/human-thread-matcher.test.mjs	19-case unit test suite (committed)
tests/human-thread-matcher-cli.test.mjs	6-case subprocess test suite (added post-review)
scripts/lib/notices.mjs	humanThreadsNotice branch + != null bugfix
tests/notices.test.mjs	humanThreadsNotice tests + 2 boundary cases
agents/ado-fetcher.md	Step 3b Human Thread classification (committed)
agents/re-review-coordinator.md	humanThreads read-only input spec (committed)

---

Validation

✅ Typecheck (all 9 matrix) | ✅ Lint (Biome + Prettier) | ✅ Tests (695 passed / 0 failed) | ✅ verify:changelog

---

Review & Self-Fix

A 4-agent post-implementation review surfaced 8 findings:

• 1 HIGH fixed — added CLI subprocess test suite (tests/human-thread-matcher-cli.test.mjs, 6 cases)
• 1 MEDIUM fixed — aligned isMain guard to import.meta.url === pathToFileURL(process.argv[1]).href pattern
• 4 LOW fixed — array guard for findings, != null fix for filePath in notices, 2 boundary test cases

Skipped (per review-agent guidance — intentional)

Finding	Severity	Reason
No try/catch around matchHumanThreadsToFindings() in CLI	LOW	Pure function with pre-validated inputs; stack trace more useful than generic message
HumanThreadEntry typedef omits status field	LOW	Intentionally narrow API — renderer must never branch on status

---

Suggested Follow-up Issues

None — all actionable findings were addressed in this PR.

---

Resolved by Archon workflow 1e722a0fc56d0066498ee63c707874df