initiative/specs/015-add-jscpd-gate/tasks.md

Tasks: Copy-Paste Detection Quality Gate

Input: Design documents from /specs/015-add-jscpd-gate/ Prerequisites: plan.md (required), spec.md (required for user stories), research.md, data-model.md, quickstart.md

Tests: Not explicitly requested in the spec. Test tasks are omitted.

Organization: Tasks are grouped by user story to enable independent implementation and testing of each story.

Format: [ID] [P?] [Story] Description

• [P]: Can run in parallel (different files, no dependencies)
• [Story]: Which user story this task belongs to (e.g., US1, US2, US3)
• Include exact file paths in descriptions

---

Phase 1: Setup

Purpose: Install jscpd and create its configuration file

• T001 Install jscpd as a dev dependency by adding it to package.json devDependencies and running pnpm install
• T002 Create jscpd configuration file at .jscpd.json with threshold (5%), minLines (5), minTokens (50), pattern for TypeScript/TSX files, ignore list for node_modules, dist, build, coverage, .specify, specs, and add a standalone "jscpd": "jscpd" script to package.json

Checkpoint: jscpd is installed and pnpm jscpd runs successfully, scanning TypeScript/TSX files and producing a report

---

Phase 2: User Story 1 - Automated Copy-Paste Detection on Commit (Priority: P1) 🎯 MVP

Goal: Pre-commit hook blocks commits when code duplication exceeds the configured threshold

Independent Test: Introduce a duplicated code block across two files, attempt to commit, and verify the commit is blocked with a clear duplication report. Remove the duplication and verify the commit succeeds.

Implementation for User Story 1

• T003 [US1] Add jscpd to the "check" script chain in package.json so it runs as part of the merge gate (e.g., "check": "knip && biome check . && tsc --build && vitest run && jscpd")

Checkpoint: Running pnpm check now includes jscpd. Since Lefthook runs pnpm check as the pre-commit hook, commits are automatically gated by copy-paste detection. A commit with duplicated code above threshold is blocked.

---

Phase 3: User Story 2 - On-Demand Duplication Scanning (Priority: P2)

Goal: Developers can run duplication scanning independently via a standalone command

Independent Test: Run pnpm jscpd on the codebase and verify it produces a duplication report with file paths and line numbers for any detected duplicates, or exits cleanly if none found.

Implementation for User Story 2

No additional tasks — pnpm jscpd was already configured in T002. This story is satisfied by the setup phase.

Checkpoint: pnpm jscpd runs independently and produces a readable duplication report

---

Phase 4: User Story 3 - Integration with Existing Quality Gate (Priority: P3)

Goal: Copy-paste detection runs as part of the unified pnpm check command alongside all other checks

Independent Test: Run pnpm check and verify jscpd output appears in the results alongside knip, biome, tsc, and vitest output.

Implementation for User Story 3

No additional tasks — integration into pnpm check was completed in T003. This story is satisfied by the US1 implementation.

Checkpoint: pnpm check includes jscpd and the full gate passes on a clean codebase

---

Phase 5: Polish & Cross-Cutting Concerns

Purpose: Validate the full workflow end-to-end

• T004 Verify pnpm check passes on the current codebase (no existing duplication above threshold), confirm scan completes within 10 seconds (SC-002), verify no false positives on import statements or type declarations (SC-003), and adjust threshold or ignore patterns in .jscpd.json if needed
• T005 Verify Knip does not flag jscpd as an unused dependency by running pnpm knip

---

Dependencies & Execution Order

Phase Dependencies

• Setup (Phase 1): No dependencies — T001 then T002
• US1 (Phase 2): Depends on T002
• US2 (Phase 3): Satisfied by T002 (no additional work)
• US3 (Phase 4): Satisfied by T003 (no additional work)
• Polish (Phase 5): Depends on T003

Execution Order

T001 → T002 → T003 → T004, T005 (parallel)

Parallel Opportunities

• T004 and T005 can run in parallel (independent validations)
• This is a small, linear feature — limited parallelism needed

---

Implementation Strategy

MVP First (User Story 1 Only)

1. Complete Phase 1: Install jscpd + configure (T001, T002)
2. Complete Phase 2: Add to check script (T003)
3. STOP and VALIDATE: Attempt a commit with duplicated code — verify it's blocked
4. All three user stories are satisfied at this point

Incremental Delivery

This feature is small enough that all stories are delivered in a single pass:

1. T001-T002: Setup → pnpm jscpd works (US2 done)
2. T003: Add to check → pre-commit gate works (US1 done), quality gate works (US3 done)
3. T004-T005: Polish → verify everything integrates cleanly

---

Notes

• This is a tooling/configuration feature — no domain, application, or adapter code changes
• All changes are at the workspace root (package.json, .jscpd.json)
• Lefthook config (lefthook.yml) does NOT need changes — it already runs pnpm check
• US2 and US3 are naturally satisfied by the setup and US1 implementation with no additional tasks