initiative/specs/007-add-knip/tasks.md

Tasks: Add Knip Unused Code Detection

Input: Design documents from /specs/007-add-knip/ Prerequisites: plan.md (required), spec.md (required), research.md, data-model.md, quickstart.md

Tests: No automated test tasks — this is a tooling feature validated by running pnpm knip and pnpm check.

Organization: Tasks follow the two user stories (US1: quality gate enforcement, US2: standalone command).

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)
• Include exact file paths in descriptions

Phase 1: Setup

Purpose: Install Knip and create configuration

• T001 Install Knip v5 as a root devDependency via pnpm add -Dw knip
• T002 Create knip.json at the repository root with workspace-aware configuration covering packages/* and apps/*, including $schema for editor support

---

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Ensure Knip passes cleanly on the current codebase before integrating into the gate

CRITICAL: Must resolve all false positives before wiring into the quality gate

• T003 Run pnpm knip against the current codebase and capture output
• T004 If false positives are reported, tune knip.json with ignore, ignoreDependencies, entry, or plugin-specific overrides until the codebase passes cleanly (FR-006 through FR-009)

Checkpoint: pnpm knip exits with code 0 on the current codebase (SC-002)

---

Phase 3: User Story 1 - Detect Unused Code on Commit (Priority: P1)

Goal: Integrate Knip into the pnpm check quality gate so unused code is caught on every commit via Lefthook.

Independent Test: Introduce an unused export in any workspace package, run pnpm check, and confirm it fails with a clear report. Remove the unused export and confirm pnpm check passes.

Implementation for User Story 1

• T005 [US1] Update the check script in package.json to prepend knip && before biome check . so unused code is checked as part of the quality gate
• T006 [US1] Run pnpm check end-to-end and verify it passes on the current codebase (SC-001, SC-002)
• T007 [US1] Manually verify detection: (a) add a temporary unused export to packages/domain/src/index.ts, run pnpm check, confirm it fails with a report identifying the unused export and its file location (SC-001, SC-004), then remove the temporary change; (b) verify that exports re-exported through barrel files (e.g., index.ts) are correctly traced and not falsely flagged

Checkpoint: Quality gate enforces unused-code detection on every commit. US1 acceptance scenarios 1–5 are satisfied.

---

Phase 4: User Story 2 - Run Unused-Code Check Independently (Priority: P2)

Goal: Provide a standalone pnpm knip command developers can run without the full quality gate.

Independent Test: Run pnpm knip from the workspace root and verify it analyzes all three workspace packages and reports results.

Implementation for User Story 2

• T008 [US2] Add a "knip": "knip" script to package.json so developers can run pnpm knip independently
• T009 [US2] Verify pnpm knip runs from the workspace root and reports results covering all workspace packages (packages/domain, packages/application, apps/web) (SC-003, SC-004)

Checkpoint: Developers can run pnpm knip standalone. US2 acceptance scenarios 1–2 are satisfied.

---

Phase 5: Polish & Cross-Cutting Concerns

Purpose: Final validation and documentation

• T010 Run quickstart.md validation: confirm pnpm knip and pnpm check both work as documented
• T011 Update CLAUDE.md commands section if pnpm knip should be listed as a project command

---

Dependencies & Execution Order

Phase Dependencies

• Setup (Phase 1): No dependencies — start immediately
• Foundational (Phase 2): Depends on Phase 1 (T001, T002 must complete first)
• User Story 1 (Phase 3): Depends on Phase 2 (clean Knip pass required before wiring into gate)
• User Story 2 (Phase 4): Depends on Phase 3 (T008 modifies the same package.json as T005, so must follow it)
• Polish (Phase 5): Depends on Phases 3 and 4

User Story Dependencies

• User Story 1 (P1): Depends on Foundational phase — needs clean codebase pass before gate integration
• User Story 2 (P2): Depends on US1 — T008 modifies the same package.json as T005, so must execute after it

Parallel Opportunities

• T001 and T002 are sequential (T002 needs Knip installed for schema validation)
• T008 (US2) modifies package.json (same as T005), so execute sequentially after T005

---

Implementation Strategy

MVP First (User Story 1 Only)

1. Complete Phase 1: Install Knip, create config
2. Complete Phase 2: Ensure clean pass on current codebase
3. Complete Phase 3: Wire into quality gate
4. STOP and VALIDATE: pnpm check passes clean; intentional unused code is caught

Incremental Delivery

1. Phase 1 + Phase 2 → Knip works locally
2. Add US1 (Phase 3) → Quality gate enforced on every commit (MVP!)
3. Add US2 (Phase 4) → Standalone pnpm knip command available
4. Phase 5 → Documentation updated

---

Notes

• All tasks modify root-level files only (no domain/application/adapter changes)
• The Lefthook pre-commit hook already runs pnpm check, so no Lefthook config changes needed
• If Knip reports false positives in Phase 2, the most common fixes are ignoreDependencies for tooling packages and entry patterns for non-standard entry points