diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index bdfa7d1..5de2d5b 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -12,6 +12,7 @@
- [ ] Repository checks: `gh repo-checks repository`
- [ ] PR title and description: `gh repo-checks pr-title "
"`, `gh repo-checks pr-body `
+- [ ] `pnpm knip` passes with no unused files, exports, dependencies, or configuration or tag hints.
- [ ] Format, lint, test, build:
## Risks
diff --git a/AGENTS.md b/AGENTS.md
index 48b1272..9b67dd3 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -10,7 +10,7 @@ This repository is a local TypeScript CLI plus portable Codex skills. Treat ever
- Do not commit `.env`, `.state/`, build output, local logs, tokens, temporary workspaces, or machine-specific paths.
- Do not add private tokens, internal hostnames, private repository names, or personal filesystem paths.
- Use `rg` for searches when available.
-- Run `pnpm verify` before claiming a change is ready (`test:layout` + `vp check` + duplicates + tests + `tsc` build + package check). Prefer `vp` for lint/fmt/test when Vite+ is installed (`pnpm exec vp …`).
+- Run `pnpm verify` before claiming a change is ready (`test:layout` + `vp check` + duplicates + knip + tests + `tsc` build + package check). Prefer `vp` for lint/fmt/test when Vite+ is installed (`pnpm exec vp …`).
- Do not claim implementation work is complete until the relevant commands pass, or until skipped commands are explained with concrete blockers.
- Update tests and documentation when behavior changes.
- `feeds.json` is the repository-maintained RSS subscription list. Update it through `rss-summary feeds ...` when possible and include intentional feed changes in the pull request.
@@ -37,6 +37,7 @@ pnpm lint
pnpm duplicates # Fails on any reported duplicate.
pnpm duplicates:audit # Reports duplicates without failing on findings.
+pnpm knip # Fails CI on unused files, exports, or dependencies and on configuration or tag hints.
# Full local gate:
pnpm verify
diff --git a/CLAUDE.md b/CLAUDE.md
index 9bd37f7..e152505 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -30,6 +30,7 @@ pnpm test
pnpm typecheck
pnpm duplicates # Fails on any reported duplicate.
pnpm duplicates:audit # Reports duplicates without failing on findings.
+pnpm knip # Fails CI on unused files, exports, or dependencies and on configuration or tag hints.
pnpm build
```
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 53d5727..bf5afa0 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -53,8 +53,9 @@ pnpm lint
pnpm duplicates # Fails on any reported duplicate.
pnpm duplicates:audit # Reports duplicates without failing on findings.
+pnpm knip # Fails CI on unused files, exports, or dependencies and on configuration or tag hints.
-# Full local gate (test layout + vp check + duplicates + tests + build + package check):
+# Full local gate (test layout + vp check + duplicates + knip + tests + build + package check):
pnpm verify
# Coverage:
diff --git a/README.md b/README.md
index ee1c9ee..06d32c8 100644
--- a/README.md
+++ b/README.md
@@ -174,9 +174,10 @@ rss-summary runs show
## Development
```bash
-pnpm verify # test:layout + check + duplicates + test + build + package:check
+pnpm verify # test:layout + check + duplicates + knip + test + build + package:check
pnpm duplicates # 检出任何一处重复都会失败。
pnpm duplicates:audit # 只生成报告,发现重复也不会拦截。
+pnpm knip # 检出未使用的文件、导出、依赖,或出现配置、标签提示时,CI 失败。
```
`main` 受保护。在功能分支上改,开 PR,等 `Verify` + `Coverage` 通过后再合并。
diff --git a/docs/architecture/technology-decisions.md b/docs/architecture/technology-decisions.md
index 354a2ca..ff06a05 100644
--- a/docs/architecture/technology-decisions.md
+++ b/docs/architecture/technology-decisions.md
@@ -82,6 +82,7 @@ Alternatives considered and rejected:
- Import direction is enforced by the architecture test (`scripts/architecture/boundaries.ts` + `tests/repo/architecture.test.ts`, zero violations), not by lint rules.
- `pnpm verify` runs `pnpm check` (`vp check`) after `test:layout`.
- The next step, `pnpm duplicates`, fails on any reported duplicate. Run `pnpm duplicates:audit` separately for a report without failing on findings.
+- `pnpm knip` then checks for unused files, exports, and dependencies. Findings and configuration or tag hints fail the Verify job.
## CI Gates
@@ -89,7 +90,7 @@ Alternatives considered and rejected:
| Job | Command | Fails when |
| --- | --- | --- |
-| `Verify` | `pnpm verify` | layout mismatch, check (fmt/lint/type) failure, any reported duplicate, test failure, build failure, or packed-package check failure |
+| `Verify` | `pnpm verify` | layout mismatch, check (fmt/lint/type) failure, any reported duplicate, Knip finding or hint, test failure, build failure, or packed-package check failure |
| `Coverage` | `pnpm test:layout && pnpm test:coverage` | missing sibling tests or coverage below the thresholds in `vite.config.ts` |
Both jobs are intended to be required checks in the branch protection rule for `main` (configure in GitHub → Settings → Branches → Branch protection rules; this cannot be expressed in the workflow file itself).
diff --git a/package.json b/package.json
index 133007b..fd2cf10 100644
--- a/package.json
+++ b/package.json
@@ -46,7 +46,7 @@
"test:coverage": "vp test run --coverage",
"test:layout": "node scripts/check-test-layout.mjs",
"typecheck": "tsc --noEmit",
- "verify": "pnpm test:layout && pnpm check && pnpm duplicates && pnpm test && pnpm build && pnpm package:check"
+ "verify": "pnpm test:layout && pnpm check && pnpm duplicates && pnpm knip && pnpm test && pnpm build && pnpm package:check"
},
"devDependencies": {
"@rivus/agent": "0.18.0",
diff --git a/tests/repo/ci-harness.test.ts b/tests/repo/ci-harness.test.ts
index 88acb82..951994d 100644
--- a/tests/repo/ci-harness.test.ts
+++ b/tests/repo/ci-harness.test.ts
@@ -9,7 +9,7 @@ describe("CI harness", () => {
};
expect(pkg.scripts?.verify).toBe(
- "pnpm test:layout && pnpm check && pnpm duplicates && pnpm test && pnpm build && pnpm package:check"
+ "pnpm test:layout && pnpm check && pnpm duplicates && pnpm knip && pnpm test && pnpm build && pnpm package:check"
);
expect(pkg.scripts?.check).toBe("vp check");
expect(pkg.scripts?.lint).toBe("vp lint");
diff --git a/tests/repo/package-bin.test.ts b/tests/repo/package-bin.test.ts
index 8d7e449..e2140dd 100644
--- a/tests/repo/package-bin.test.ts
+++ b/tests/repo/package-bin.test.ts
@@ -55,7 +55,7 @@ describe("package CLI metadata", () => {
expect(pkg.scripts?.build).toBe("tsc -p tsconfig.build.json");
expect(pkg.scripts?.["package:check"]).toBe("node scripts/check-package.mjs");
expect(pkg.scripts?.verify).toBe(
- "pnpm test:layout && pnpm check && pnpm duplicates && pnpm test && pnpm build && pnpm package:check"
+ "pnpm test:layout && pnpm check && pnpm duplicates && pnpm knip && pnpm test && pnpm build && pnpm package:check"
);
expect(buildConfig.compilerOptions?.declaration).toBe(true);
});