feat(unic-spec-review): dedup + cancellable Approval Loop

[orioltf]

What

Closes the unic-spec-review posting path (S8) with content-similarity deduplication and a fully cancellable multi-Finding Approval Loop. Resolves #208.

Why

The --post path (S5) had no deduplication and could post only one Finding per run, so reruns — by the same reviewer or anyone else — silently piled up duplicate comments on a page. There was no safeguard against re-raising an issue someone already commented on.

How

• scripts/lib/dedup-matcher.mjs (new pure library): matchDedup(finding, existingComments) computes Jaccard word-token similarity between a Finding (title + body) and every existing page comment, returning a post / skip / flag decision plus near-duplicate candidates sorted by similarity. No hidden marker and no local state file — it reads the shared page, so it is multi-user and multi-run safe by construction (ADR-0002). Exports tokenize/jaccard helpers and SKIP_THRESHOLD/FLAG_THRESHOLD constants, plus a --findings-file/--comments-file CLI mode for command integration.
• scripts/atlassian-fetch.mjs: adds a --comments <url> CLI mode wrapping fetchConfluenceComments in the same never-throws collectComments pattern as --child-pages.
• commands/review-spec.md Step 10: replaced the single-Finding picker with a multi-Finding Approval Loop — fetch existing comments → run dedup-matcher → present a ranked list annotated with [~near-dup] / [~likely-dup] badges → comma-separated selection → explicit human tiebreak on flagged/skip matches (never silently dropped or re-raised) → post approved Findings via the S7 write path with anchors + attribution footers. Cancellable at every step, including a post-none exit after selection. Bare /review-spec stays strictly read-only.
• tests/dedup-matcher.test.mjs: 22 node:test cases covering tokenize, jaccard, and matchDedup with injected comment sets; no live services. The Approval Loop driver (markdown instructions) is not unit-tested by design.

Validation

• pnpm --filter unic-spec-review typecheck — ✅
• pnpm --filter unic-spec-review test — ✅ 292 passed (22 new)
• pnpm --filter unic-spec-review verify:changelog — ✅ → 0.1.7
• pnpm ci:check — ✅
• No em dash in authored text; no LICENSE files touched; no cross-plugin imports.

🤖 Generated with Claude Code

[orioltf]

⚡ Self-Fix Report (Aggressive)

Status: COMPLETE
Pushed: ✅ Changes pushed to archon/task-feature-unic-spec-review-208-dedup-approval-loop
Commit: 695073f
Philosophy: Fix everything unless clearly a new concern

---

Fixes Applied (12 total)

Severity	Count
🔴 CRITICAL	0
🟠 HIGH	3
🟡 MEDIUM	1
🟢 LOW	8

View all fixes

• ✅ README.md S5→S8 callout (README.md:9) — Updated to describe multi-Finding loop, near-dup flags, Jaccard similarity; removed "planned for S8" sentence
• ✅ CONTEXT.md status S1–S5→S1–S8 (CONTEXT.md:5) — Bumped status; added collectComments --comments and dedup-matcher to feature list; removed dedup/multi-Finding from deferred
• ✅ AGENTS.md status S1–S5→S1–S8 (AGENTS.md:9) — Bumped status; single-Finding→multi-Finding write path; removed dedup from deferred slices
• ✅ collectComments tests (tests/atlassian-fetch.test.mjs) — 3 cases: success, null-creds auth-error shape, per-page FetchError; mirrors collectChildPages exactly
• ✅ CommentsOutput.truncated JSDoc (atlassian-fetch.mjs:940) — Appended "and the comment set is incomplete" to match ChildPagesOutput wording
• ✅ Dead union===0 guard (dedup-matcher.mjs:77) — Removed unreachable guard after early-return already handles both-empty case
• ✅ tokenize null/undefined tests (tests/dedup-matcher.test.mjs) — Added null and undefined defensive-guard test cases
• ✅ matchDedup null-array guard test (tests/dedup-matcher.test.mjs) — Added it('returns post when existingComments is null')
• ✅ Ambiguous file error in dedup-matcher CLI (dedup-matcher.mjs:142–159) — Split into two try/catch blocks naming findings file vs comments file
• ✅ Jaccard comment notation (tests/dedup-matcher.test.mjs:87,92) — Updated {a,b} → {aa,bb} to match actual two-letter token values in code
• ✅ parseCommentsArg JSDoc (atlassian-fetch.mjs:993) — Added "or empty": "or null when absent or empty"
• ✅ parseCommentsArg tests (tests/atlassian-fetch.test.mjs) — 3 cases mirroring parseChildPagesArg (present/absent/no-value)

---

Tests Added

• tokenize — returns an empty set for null input
• tokenize — returns an empty set for undefined input
• matchDedup — returns post when existingComments is null
• parseCommentsArg — returns the URL following --comments
• parseCommentsArg — returns null when the flag is absent
• parseCommentsArg — returns null when the flag has no value
• collectComments — returns comments and no errors on success
• collectComments — reports an auth-error with url "" when no credentials are configured
• collectComments — collects a per-page FetchError instead of throwing

---

Skipped (1)

Finding	Reason
Non-FetchError tagged as parse-error (atlassian-fetch.mjs:982–997)	Pre-existing intentional pattern matching collectChildPages; review explicitly recommended no action; changing requires coordinated update to both functions

---

Suggested Follow-up Issues

(none — all actionable findings addressed)

---

Validation

✅ Type check | ✅ Lint | ✅ Tests (301 passed)

---

Self-fix by Archon · aggressive mode · fixes pushed to archon/task-feature-unic-spec-review-208-dedup-approval-loop