instrlint 0.2.2 → 0.2.4

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "instrlint",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Lint and optimize your CLAUDE.md / AGENTS.md — find dead rules, token waste, and structural issues",
   "type": "module",
   "bin": {
-    "instrlint": "./dist/cli.js"
+    "instrlint": "dist/cli.js"
   },
   "main": "./dist/index.js",
   "exports": {
@@ -26,7 +26,7 @@
   "author": "Jed Lin",
   "repository": {
     "type": "git",
-    "url": "https://github.com/jed1978/instrlint"
+    "url": "git+https://github.com/jed1978/instrlint.git"
   },
   "homepage": "https://github.com/jed1978/instrlint#readme",
   "bugs": {

package/skills/instrlint/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: instrlint
+description: Lint and optimize agent instruction files. Use when the user wants to lint, audit, refactor, or optimize their CLAUDE.md, AGENTS.md, .cursorrules, or related instruction files — finds dead rules, token waste, duplicates, contradictions, and stale references. Produces a scored health report (0–100) with auto-fix and host-orchestrated LLM verification.
+---
+
+# instrlint
+
+Lint and optimize agent instruction files. Produces a scored health report across three dimensions: token budget, dead rules, and structure.
+
+## Command Resolution Protocol
+
+When the user runs `/instrlint [args]`:
+
+1. **Detect language** — identify conversation language → output: locale
+   - 繁體中文 → `zh-TW`
+   - English or any other → `en`
+
+2. **Check `--verify`** — if args contain `--verify` → jump to LLM Verification Protocol below. Otherwise continue.
+
+3. **Map command** — parse user args against this table → output: base command
+
+   | User args | Base command |
+   |-----------|-------------|
+   | _(none)_ | `npx instrlint@latest` |
+   | `budget` | `npx instrlint@latest budget` |
+   | `deadrules` | `npx instrlint@latest deadrules` |
+   | `structure` | `npx instrlint@latest structure` |
+   | `--fix` | `npx instrlint@latest --fix` |
+   | `ci --fail-on warning` | `npx instrlint@latest ci --fail-on warning` |
+
+4. **Build final command** — append flags from steps 1 and 3:
+   `{base command} --format markdown --lang {locale}`
+   Exception: `--fix` omits `--format markdown` (output is a fix summary, not a report).
+
+5. **Execute and present** — run the command → present the markdown output directly to the user. Never summarize or paraphrase.
+
+## LLM Verification Protocol (`--verify`)
+
+contradiction / duplicate / structure detectors are text heuristics and may produce false positives. You (the host agent) can judge these semantically.
+
+**Protocol:** instrlint never calls an LLM API. It writes suspicious findings as `candidates.json`, you judge them and write `verdicts.json`, then instrlint merges the results back into the report.
+
+### Quick steps
+
+1. `npx instrlint@latest --emit-candidates instrlint-candidates.json --skip-report --lang <detected>`
+2. Read `instrlint-candidates.json` and judge each candidate using criteria from [references/judgment-framework.md](references/judgment-framework.md) (`confirmed` / `rejected` / `uncertain`)
+3. Write `instrlint-verdicts.json` with your verdicts (`id` must match 12-char hex from candidates)
+4. `npx instrlint@latest --apply-verdicts instrlint-verdicts.json --format markdown --lang <detected>`
+
+## Splitting Guidance
+
+When instrlint reports either of these conditions, **do not paste the suggestion text directly** — run the splitting decision walkthrough instead:
+
+- Budget warning: root instruction file exceeds recommended line count (> 200 lines)
+- Structure findings contain path-scope suggestions (`messageKey: structure.scopePathScoped`)
+
+### Walkthrough flow
+
+1. **Read** the file, list major sections (heading + line count)
+2. **Classify each section** using the 4-bucket framework (see [references/judgment-framework.md](references/judgment-framework.md))
+3. **Present a decision table** to the user (section / lines / recommended action / reason)
+4. **Ask** the user: "Minimum split (bucket 1 only) / Full split (buckets 1+2+3) / Custom"
+5. **Execute**: bucket 1 → extract to rules directory with `paths:` / `globs:` frontmatter; bucket 2 → extract without path-scope; bucket 3 → replace with one-line pointer

package/skills/instrlint/references/judgment-framework.md

@@ -0,0 +1,130 @@
+# LLM Verification — Judgment Framework
+
+Reference document for `/instrlint --verify`. The host agent uses this framework when judging candidates.
+
+## --verify Four-Step Protocol
+
+**Step 1** — Emit candidates:
+
+```bash
+npx instrlint@latest --emit-candidates instrlint-candidates.json --skip-report --lang <detected>
+```
+
+**Step 2** — Read and judge:
+
+Use the Read tool to read `instrlint-candidates.json`. For each candidate, apply the judgment criteria below.
+
+**Step 3** — Write verdicts to `instrlint-verdicts.json`:
+
+```json
+{
+  "version": 1,
+  "verdicts": [
+    { "id": "a3f1c9e2b4d6", "verdict": "rejected", "reason": "兩條規則 context 無關" }
+  ]
+}
+```
+
+Each verdict's `id` must exactly match the `id` in candidates.json (12-char hex). `verdict` is `confirmed` / `rejected` / `uncertain`. `reason` ≤ 500 chars.
+
+**Step 4** — Apply verdicts and render report:
+
+```bash
+npx instrlint@latest --apply-verdicts instrlint-verdicts.json --format markdown --lang <detected>
+```
+
+Present the output markdown as-is to the user.
+
+## candidates.json Format
+
+```json
+{
+  "version": 1,
+  "generatedAt": "2026-04-07T12:00:00.000Z",
+  "projectRoot": "/absolute/path/to/project",
+  "candidates": [
+    {
+      "id": "a3f1c9e2b4d6",
+      "category": "contradiction",
+      "question": "Do rules A and B actually contradict each other in practice?...",
+      "context": {
+        "type": "contradiction",
+        "ruleA": { "file": "CLAUDE.md", "line": 10, "text": "Use exceptions for error handling." },
+        "ruleB": { "file": "CLAUDE.md", "line": 20, "text": "Never throw exceptions, use Result<T> instead." }
+      },
+      "originalFinding": { "severity": "critical", "category": "contradiction", "file": "CLAUDE.md", "line": 20 }
+    }
+  ]
+}
+```
+
+## Judgment Criteria
+
+### contradiction
+
+- **confirmed**: A developer following both ruleA and ruleB simultaneously would face a real conflict in some scenario
+- **rejected**: The rules address different contexts, or the negation is only superficial (false positive)
+- **uncertain**: Semantically ambiguous; cannot judge from available context
+
+### duplicate
+
+- **confirmed**: Both rules say the same thing in different words — removing one loses no information
+- **rejected**: Surface similarity but actually covers different details, scope, or exceptions
+- **uncertain**: Cannot determine
+
+### structure
+
+- **confirmed**: This rule is genuinely better enforced by a git hook or path-scoped rule file; keeping it in the root instruction file is redundant
+- **rejected**: This rule is an architectural decision, general principle, or context requiring human judgment (e.g. "LLM verification must be host-orchestrated" is a design principle, not something a git hook can enforce)
+- **uncertain**: Cannot determine without more context
+
+### General rules
+
+- For structure: read `candidate.context.rule.text` and `candidate.context.suggestion` first
+- For contradiction / duplicate: read `candidate.context.ruleA.text` / `ruleB.text` first
+- Use the Read tool to view surrounding context in the file when needed
+- `reason` can be ≤ 20 chars in practice (max 500 chars — instrlint validates)
+- Candidates with no verdict don't need to appear in verdicts.json (instrlint leaves them unchanged)
+- `rejected` findings are filtered from the final report; `confirmed` and `uncertain` appear with your reason
+
+---
+
+## CLAUDE.md / AGENTS.md Refactoring — 4-Bucket Framework
+
+### Walkthrough Flow
+
+1. **Read** the file, list major sections (heading + line count)
+2. **Classify each section** using the 4-bucket framework below; if a section spans multiple buckets, use the primary body and note it in the decision table
+3. **Present a decision table** to the user (section name / line count / recommended action / reason)
+4. **Ask** the user: "Minimum split (bucket 1 only) / Full split (buckets 1+2+3) / Custom"
+5. **Execute the chosen actions**:
+   - bucket 1 → extract to rules directory with `paths:` / `globs:` frontmatter
+     - Claude Code: `.claude/rules/`
+     - Codex: `.agents/rules/`
+   - bucket 2 → extract without path-scope frontmatter
+   - bucket 3 → replace with a one-line pointer
+
+### 4-Bucket Classification
+
+| Bucket | Condition | Action |
+|---|---|---|
+| **1. Real savings** | Tied to specific files/modules, most conversations don't need it (< 30% load rate) | Extract + `paths:` / `globs:` frontmatter |
+| **2. Extractable, no savings** | Global, loaded in nearly every conversation (> 80% load rate) | Extract to shorten file — total tokens unchanged |
+| **3. Delete, not move** | Duplicates source code (e.g. type definitions already in `src/types.ts`) | Replace with a one-line pointer |
+| **4. Stay in root file** | Cross-conversation decisions / commands / state | Don't move |
+
+**Load rate heuristic:** Ask yourself "In what fraction of real conversations would this scope be loaded?"
+- > 80% → bucket 2 or 4 (path-scoping gives no benefit)
+- 30–80% → decide based on maintenance cost
+- < 30% → bucket 1 (real savings)
+
+### Examples
+
+| Section | Bucket | Reason |
+|---|---|---|
+| Module-specific gotchas | 1 — Real savings | Only needed when editing that module; scope to the relevant `src/` path |
+| Coding conventions | 2 — Extractable, no savings | Loaded for any .ts file; splitting doesn't change total tokens |
+| Key types (type definitions, **identical to source file with no extra commentary**) | 3 — Delete, not move | Duplicate info; keep one line: `see src/types.ts` |
+| Architecture decisions | 4 — Stay in root file | Cross-file design principles needed every conversation |
+
+> **Principle:** The purpose of path-scoping is "don't load this in conversations that don't need it." If it would be loaded in almost every conversation anyway, it's bucket 2, not bucket 1.

package/skills/claude-code/SKILL.md

@@ -1,163 +0,0 @@
----
-name: instrlint
-description: Health check your CLAUDE.md and rule files — find dead rules, token waste, duplicates, contradictions, and stale references. Produces a scored health report (0-100) with auto-fix support.
-command: /instrlint
-argument-hint: "[budget|deadrules|structure|ci] [--fix] [--verify] [--lang zh-TW]"
----
-
-# instrlint
-
-Lint and optimize agent instruction files. Produces a scored health report across three dimensions: token budget, dead rules, and structure.
-
-## How to run
-
-**Always run with `--format markdown`** so the report renders properly in Claude Code. Never use the default terminal format — it uses ANSI colors and box-drawing characters that don't display correctly here.
-
-Then **present the markdown report directly to the user** — do not summarize or paraphrase it.
-
-## Language detection
-
-**Always detect the language of the current conversation before running:**
-
-- 繁體中文 conversation → add `--lang zh-TW`
-- English conversation → add `--lang en`
-- Any other language → fall back to `--lang en`
-
-## Command mapping
-
-When the user runs `/instrlint [args]`, translate to:
-
-| User input | Command to run |
-|------------|---------------|
-| `/instrlint` | `npx instrlint@latest --format markdown --lang <detected>` |
-| `/instrlint budget` | `npx instrlint@latest budget --format markdown --lang <detected>` |
-| `/instrlint deadrules` | `npx instrlint@latest deadrules --format markdown --lang <detected>` |
-| `/instrlint structure` | `npx instrlint@latest structure --format markdown --lang <detected>` |
-| `/instrlint --fix` | `npx instrlint@latest --fix --lang <detected>` then present the fix summary as-is |
-| `/instrlint ci --fail-on warning` | `npx instrlint@latest ci --format markdown --fail-on warning --lang <detected>` |
-| `/instrlint --verify` | 執行下方「LLM 驗證流程」四步驟 |
-| `/instrlint structure --verify` | 同上，但僅對 structure 類別的 findings 進行 LLM 複核 |
-
-## LLM 驗證流程（--verify）
-
-contradiction / duplicate / structure detector 是純文字啟發式，可能產生 false positive。你（host agent）能讀懂語意，可以複核這些 findings。
-
-**協議概念：** instrlint 不會自己呼叫 LLM API。它把可疑 findings 寫成 `candidates.json`，由你判斷後寫 `verdicts.json`，再由 instrlint merge 回報告。
-
-### 四步驟
-
-**Step 1** — 產出 candidates：
-
-```bash
-npx instrlint@latest --emit-candidates instrlint-candidates.json --skip-report --lang <detected>
-```
-
-**Step 2** — 讀取並判斷：
-
-用 Read tool 讀 `instrlint-candidates.json`。對每個 candidate，根據下方「判斷框架」做出 verdict。
-
-**Step 3** — 寫出 verdicts：
-
-用 Write tool 寫 `instrlint-verdicts.json`：
-
-```json
-{
-  "version": 1,
-  "verdicts": [
-    { "id": "a3f1c9e2b4d6", "verdict": "rejected", "reason": "兩條規則 context 無關" }
-  ]
-}
-```
-
-每個 verdict 的 `id` 必須與 candidates.json 中的 `id` 完全對應（12-char hex）。`verdict` 為 `confirmed` / `rejected` / `uncertain`，`reason` ≤ 500 字元。
-
-**Step 4** — 套用 verdicts 並呈現報告：
-
-```bash
-npx instrlint@latest --apply-verdicts instrlint-verdicts.json --format markdown --lang <detected>
-```
-
-把輸出的 markdown 報告原樣呈現給使用者，不要摘要或改寫。
-
-### candidates.json 格式
-
-```json
-{
-  "version": 1,
-  "generatedAt": "2026-04-07T12:00:00.000Z",
-  "projectRoot": "/absolute/path/to/project",
-  "candidates": [
-    {
-      "id": "a3f1c9e2b4d6",
-      "category": "contradiction",
-      "question": "Do rules A and B actually contradict each other in practice?...",
-      "context": {
-        "type": "contradiction",
-        "ruleA": { "file": "CLAUDE.md", "line": 10, "text": "Use exceptions for error handling." },
-        "ruleB": { "file": "CLAUDE.md", "line": 20, "text": "Never throw exceptions, use Result<T> instead." }
-      },
-      "originalFinding": { "severity": "critical", "category": "contradiction", "file": "CLAUDE.md", "line": 20, "..." }
-    }
-  ]
-}
-```
-
-## 判斷框架（host agent 用）
-
-### contradiction
-
-- **confirmed**：開發者同時遵守 ruleA 和 ruleB 在某些情境下做不到（真實衝突）
-- **rejected**：兩條規則各做各的、context 不同、或只是字面上有否定詞（false positive）
-- **uncertain**：語意模糊，無法從現有 context 判斷
-
-### duplicate
-
-- **confirmed**：兩條規則用不同措辭說同一件事，刪掉一條沒有任何資訊損失
-- **rejected**：表面相似但實際說的是不同的細節 / 範圍 / 例外
-- **uncertain**：判不出來
-
-### structure
-
-- **confirmed**：這條規則確實更適合由 git hook 或 path-scoped rule file 自動執行，放在 CLAUDE.md 中是多餘的
-- **rejected**：這條規則是架構決策說明、一般性原則、或需要人工判斷的 context，不適合用工具強制執行（例：「LLM 驗證必須由 host orchestrate」是設計原則，不是 git hook 能攔的）
-- **uncertain**：無法判斷，需要看更多 context
-
-### 通則
-
-- structure：先讀 `candidate.context.rule.text` 和 `candidate.context.suggestion`
-- contradiction / duplicate：先讀 `candidate.context.ruleA.text` / `ruleB.text`
-- 必要時用 Read tool 看該 file 的上下文
-- `reason` 實務上寫 ≤ 20 字即可（上限 500 字元，instrlint 會驗證）
-- 沒有 verdict 的 candidate 不需要寫進 verdicts.json（instrlint 會保留它不動）
-- `rejected` findings 在最終報告中會被過濾掉；`confirmed` 和 `uncertain` 會附上你的 reason 顯示
-
-## What it checks
-
-- **Budget** — token consumption across all instruction files and MCP servers. Flags files > 200 lines, baselines > 25% of context window.
-- **Dead rules** — rules already enforced by tsconfig, prettier, eslint, commitlint, editorconfig, and more. ~15 overlap patterns.
-- **Structure** — contradictions between rules, stale file references, duplicates, and path-scoping opportunities.
-
-## Auto-fix (--fix)
-
-Auto-applied (safe, deterministic):
-- Rules already enforced by config files (dead rules)
-- References to non-existent files (stale refs)
-- Exact duplicate rules
-
-Actionable suggestions shown after fix (requires human judgment):
-- Git hook suggestions — copy-paste `.claude/settings.json` snippet
-- Path-scoped rule file suggestions — ready-to-create file content
-
-## Score and grade
-
-| Grade | Score | Meaning |
-|-------|-------|---------|
-| A | 90–100 | Excellent — minor issues only |
-| B | 80–89 | Good — a few improvements possible |
-| C | 70–79 | Fair — some issues to address |
-| D | 60–69 | Poor — significant problems |
-| F | < 60 | Critical — needs immediate attention |
-
-## Supported tools
-
-Claude Code, Codex, Cursor — auto-detected from project structure.

package/skills/codex/SKILL.md

@@ -1,122 +0,0 @@
----
-name: instrlint
-description: Health check your AGENTS.md and rule files — find dead rules, token waste, duplicates, contradictions, and stale references.
-command: /instrlint
-argument-hint: "[budget|deadrules|structure|ci] [--fix] [--format json|markdown|sarif]"
----
-
-# instrlint
-
-Lint and optimize agent instruction files. Produces a scored health report across three dimensions: token budget, dead rules, and structure.
-
-## Language detection
-
-**Always detect the language of the current conversation before running instrlint:**
-
-- If the user is conversing in **Traditional Chinese (繁體中文)**: run with `--lang zh-TW`
-- If the user is conversing in **English**: run with `--lang en`
-- For any other language instrlint does not support: fall back to `--lang en`
-
-## Usage
-
-```
-/instrlint                          # Full health check (score + grade)
-/instrlint budget                   # Token budget analysis only
-/instrlint deadrules                # Dead rule detection only
-/instrlint structure                # Structural analysis only
-/instrlint ci --fail-on warning     # CI mode: exit 1 if warnings found
-/instrlint --fix                    # Auto-fix safe issues + show actionable suggestions
-/instrlint --format json            # JSON output for CI
-/instrlint --format markdown        # Markdown output for PR comments
-/instrlint install --codex          # Install skill into .agents/skills/
-/instrlint --verify                 # LLM-assisted two-pass verification (see below)
-```
-
-## LLM 驗證流程（--verify）
-
-contradiction / duplicate detector 是純文字啟發式，可能產生 false positive。你（host agent）能讀懂語意，可以複核這些 findings。
-
-**協議概念：** instrlint 不會自己呼叫 LLM API。它把可疑 findings 寫成 `candidates.json`，由你判斷後寫 `verdicts.json`，再由 instrlint merge 回報告。
-
-### 四步驟
-
-**Step 1** — 產出 candidates：
-
-```bash
-npx instrlint@latest --emit-candidates instrlint-candidates.json --skip-report --lang <detected>
-```
-
-**Step 2** — 讀取並判斷：
-
-讀 `instrlint-candidates.json`。對每個 candidate，根據下方「判斷框架」做出 verdict。
-
-**Step 3** — 寫出 verdicts：
-
-寫 `instrlint-verdicts.json`：
-
-```json
-{
-  "version": 1,
-  "verdicts": [
-    { "id": "a3f1c9e2b4d6", "verdict": "rejected", "reason": "兩條規則 context 無關" }
-  ]
-}
-```
-
-每個 verdict 的 `id` 必須與 candidates.json 中的 `id` 完全對應（12-char hex）。`verdict` 為 `confirmed` / `rejected` / `uncertain`，`reason` ≤ 500 字元。
-
-**Step 4** — 套用 verdicts 並呈現報告：
-
-```bash
-npx instrlint@latest --apply-verdicts instrlint-verdicts.json --format markdown --lang <detected>
-```
-
-### candidates.json 格式
-
-```json
-{
-  "version": 1,
-  "generatedAt": "2026-04-07T12:00:00.000Z",
-  "projectRoot": "/absolute/path/to/project",
-  "candidates": [
-    {
-      "id": "a3f1c9e2b4d6",
-      "category": "contradiction",
-      "question": "Do rules A and B actually contradict each other in practice?...",
-      "context": {
-        "type": "contradiction",
-        "ruleA": { "file": "CLAUDE.md", "line": 10, "text": "Use exceptions for error handling." },
-        "ruleB": { "file": "CLAUDE.md", "line": 20, "text": "Never throw exceptions, use Result<T> instead." }
-      },
-      "originalFinding": { "severity": "critical", "category": "contradiction", "file": "CLAUDE.md", "line": 20, "..." }
-    }
-  ]
-}
-```
-
-## 判斷框架（host agent 用）
-
-### contradiction
-
-- **confirmed**：開發者同時遵守 ruleA 和 ruleB 在某些情境下做不到（真實衝突）
-- **rejected**：兩條規則各做各的、context 不同、或只是字面上有否定詞（false positive）
-- **uncertain**：語意模糊，無法從現有 context 判斷
-
-### duplicate
-
-- **confirmed**：兩條規則用不同措辭說同一件事，刪掉一條沒有任何資訊損失
-- **rejected**：表面相似但實際說的是不同的細節 / 範圍 / 例外
-- **uncertain**：判不出來
-
-### 通則
-
-- 先讀 `candidate.context.ruleA.text` / `ruleB.text`，必要時看該 file 的上下文
-- `reason` 實務上寫 ≤ 20 字即可（上限 500 字元，instrlint 會驗證）
-- 沒有 verdict 的 candidate 不需要寫進 verdicts.json（instrlint 會保留它不動）
-- `rejected` findings 在最終報告中會被過濾掉；`confirmed` 和 `uncertain` 會附上你的 reason 顯示
-
-## What it checks
-
-- **Budget** — token consumption across AGENTS.md, skills, and MCP servers.
-- **Dead rules** — rules already enforced by tsconfig, prettier, eslint, and other config files.
-- **Structure** — contradictions, stale file references, duplicates, and path-scoping opportunities.