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

- [x] T001 Install Knip v5 as a root devDependency via `pnpm add -Dw knip`
- [x] 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

- [x] T003 Run `pnpm knip` against the current codebase and capture output
- [x] 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

- [x] 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
- [x] T006 [US1] Run `pnpm check` end-to-end and verify it passes on the current codebase (SC-001, SC-002)
- [x] 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

- [x] T008 [US2] Add a `"knip": "knip"` script to `package.json` so developers can run `pnpm knip` independently
- [x] 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

- [x] T010 Run quickstart.md validation: confirm `pnpm knip` and `pnpm check` both work as documented
- [x] 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