Add scoped duplicate leads to review output

[lzehrung]

• Adds scoped duplicate leads to impact pretty output and review summaries.
• Adds --duplicates off|changed|impacted|all for human-summary duplicate scope.
• Keeps impact and review JSON contracts unchanged; full duplicate data remains in codegraph duplicates.
• Updates README, CLI docs, agent workflow docs, library API docs, how-it-works, the bundled skill, and the implementation plan.
• Covers impact pretty output, review summary output, and omitted duplicate-lead counts with regression tests.

Verification:

• npm run build
• npm run lint
• npm test
• npm run test:integration
• npx prettier --check README.md docs\installation.md docs\cli.md docs\library-api.md docs\agent-workflows.md docs\how-it-works.md docs\language-parity.md docs\scenario-catalog.md codegraph-skill\codegraph\SKILL.md docs\superpowers\plans\2026-05-28-docs-output-refinement.md src\duplicatesLeads.ts src\cli\impact.ts src\cli\review.ts src\cli\help.ts src\cli\options.ts tests\duplicates.test.ts tests\impact-cli.test.ts
• git diff --check

[Copilot]

Pull request overview

Adds scoped, high-confidence duplicate leads to the human-readable output paths (impact --pretty and review --summary/--pretty) without touching the existing JSON contracts. A new --duplicates off|changed|impacted|all option lets users tune the scope, and full grouped duplicate data continues to live under codegraph duplicates. Docs, the bundled skill, and the implementation plan are updated, and regression tests cover the new pretty/summary paths.

Changes:

• New src/duplicatesLeads.ts helper that runs findDuplicates() on a scoped index and filters to high-confidence exact/renamed clones with omission counts.
• impact and review CLI paths collect and append duplicate leads only for human output; --duplicates is registered as a value option and parsed with defaults changed (impact) and impacted (review).
• Documentation, README CLI examples, agent workflow notes, skill guidance, and the refinement plan are updated; tests added for pretty/summary duplicate output and an omitted-counts-only summary.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/duplicatesLeads.ts	New helper: scope type, lead/summary types, scope parser, lead collector, and prose appender.
src/cli/impact.ts	Refactors pretty impact to a string builder and wires in scoped duplicate-lead collection (default changed), reusing the existing project index.
src/cli/review.ts	Adds scoped/all duplicate-lead collection (default impacted) for --summary/--pretty; builds a fresh index for the duplicate pass.
src/cli/options.ts	Registers --duplicates as a value-bearing CLI option.
src/cli/help.ts	Adds a --duplicates off example to the impact help block.
README.md	Adds a "CLI examples" section with impact pretty, review summary, duplicates, and orient samples.
docs/cli.md	Documents --duplicates flag, defaults, and that JSON contracts are unchanged.
docs/library-api.md	Notes that duplicate leads in human summaries are presentation-only; programmatic callers should use findDuplicates().
docs/agent-workflows.md	Describes the new duplicate-lead defaults and scoping options.
docs/how-it-works.md	Mentions the scoped duplicate-lead pass for pretty/summary output.
docs/scenario-catalog.md	Prettier reflow of existing tables (no semantic change).
docs/superpowers/plans/2026-05-28-docs-output-refinement.md	Marks the plan's checklist items as done.
codegraph-skill/codegraph/SKILL.md	Adds skill guidance about default duplicate leads and the --duplicates flag.
tests/duplicates.test.ts	Adds a unit test for appendDuplicateLeadSummary() retaining omission counts when no lead survives filters.
tests/impact-cli.test.ts	Adds pretty impact duplicate-lead test (incl. --duplicates off) and a review summary duplicate-lead test; converts existing tests to the it(name, fn, timeout) form.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated no new comments.

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Other Observations (not in diff)

Issues found in unchanged code or design decisions worth noting:

File	Line	Issue
src/cli/review.ts	317	Inconsistent error handling: parseDuplicateLeadScope throws on invalid --duplicates values, but unlike src/cli/impact.ts, this call sits outside any try/catch, so users see a stack trace instead of a clean stderr message. Pre-existing review.ts option parsers share the same unprotected pattern.
src/cli/review.ts	320	When changedFiles.size === 0, buildReviewReport returns early without building the index, so reviewBuildReport?.index is undefined and duplicate detection is silently skipped. This means review --summary --duplicates all with no changes will not show duplicate leads even though the user explicitly requested project-wide scope.

Files Reviewed (12 files)

• src/cli/help.ts
• src/cli/impact.ts
• src/cli/options.ts
• src/cli/review.ts
• src/duplicatesLeads.ts
• src/review.ts
• tests/duplicates.test.ts
• tests/impact-cli.test.ts
• README.md
• docs/cli.md
• docs/agent-workflows.md
• codegraph-skill/codegraph/SKILL.md

---

_{Reviewed by kimi-k2.6 · 2,856,059 tokens}