instrlint 0.1.7 → 0.1.9

package/README.md

@@ -69,6 +69,8 @@ Run from your project root where `CLAUDE.md` or `AGENTS.md` lives.
 
 **Auto-fix** — `--fix` safely removes dead rules, stale refs, and exact duplicates. Requires a clean git working tree.
 
+**LLM Verification** — `/instrlint --verify` (Claude Code / Codex skill) runs a two-pass protocol: instrlint emits low-confidence findings as `candidates.json`, you (the host agent) judge each one and write `verdicts.json`, then instrlint merges results — filtering false positives and attaching `✓ confirmed` / `❓ uncertain` badges. No API key required; the host model is the verifier.
+
 **CI Integration** — `instrlint ci` exits 0 or 1 based on findings severity, with SARIF output for GitHub Code Scanning.
 
 ## Supported tools
@@ -106,6 +108,11 @@ instrlint init-ci --gitlab        # Print GitLab CI snippet to stdout
 instrlint install --claude-code   # Install as global Claude Code skill
 instrlint install --claude-code --project  # Install into project
 instrlint install --codex         # Install as Codex skill
+
+# Host-orchestrated LLM verification (two-pass, no API key needed)
+instrlint --emit-candidates instrlint-candidates.json        # Write low-confidence findings for host LLM to judge
+instrlint --emit-candidates instrlint-candidates.json --skip-report  # Same, without printing the report
+instrlint --apply-verdicts instrlint-verdicts.json           # Apply host LLM verdicts and re-render report
 ```
 
 ## CI Integration
@@ -155,10 +162,22 @@ Then **restart Claude Code** to activate the command. Then in your editor:
 /instrlint
 /instrlint --fix
 /instrlint ci --fail-on warning
+/instrlint --verify
 ```
 
 > **Note:** Claude Code only loads custom commands at startup. `/reload-plugins` does not pick up newly installed commands.
 
+### LLM verification (`/instrlint --verify`)
+
+The `--verify` flag triggers a two-pass protocol where the host agent (Claude Code or Codex) judges low-confidence findings to eliminate false positives:
+
+1. **Emit candidates** — instrlint writes `instrlint-candidates.json` with contradiction/duplicate findings that need semantic review
+2. **Judge** — you (or the host agent) read the file and determine `confirmed` / `rejected` / `uncertain` for each
+3. **Write verdicts** — save decisions to `instrlint-verdicts.json`
+4. **Apply** — instrlint merges verdicts, filters rejected findings, and re-renders the report with `✓` / `❓` badges
+
+instrlint never calls an LLM API. It delegates judgment to whatever model is already running the session.
+
 ## Score and grade
 
 | Grade | Score | Meaning |

package/README.zh-TW.md

@@ -75,6 +75,8 @@ npx instrlint --lang zh-TW
 
 **自動修復** — `--fix` 安全地移除冗餘規則、過時參照和完全重複的規則。需要乾淨的 git 工作目錄。
 
+**LLM 驗證** — `/instrlint --verify`（Claude Code / Codex skill）執行兩段式驗證協議：instrlint 將低信心的 findings 輸出為 `candidates.json`，由你（host agent）逐一判斷後寫入 `verdicts.json`，再由 instrlint 合併結果 — 過濾 false positive，並附上 `✓ confirmed` / `❓ uncertain` badge。不需要任何 API key；host model 本身就是驗證者。
+
 **CI 整合** — `instrlint ci` 依 findings 嚴重程度回傳 exit code 0 或 1，並支援 SARIF 輸出供 GitHub Code Scanning 使用。
 
 ## 支援工具
@@ -112,6 +114,11 @@ instrlint init-ci --gitlab        # 輸出 GitLab CI 設定片段
 instrlint install --claude-code   # 安裝為全域 Claude Code skill
 instrlint install --claude-code --project  # 安裝到專案
 instrlint install --codex         # 安裝為 Codex skill
+
+# 由 host 協調的 LLM 驗證（兩段式，不需要 API key）
+instrlint --emit-candidates instrlint-candidates.json        # 將低信心 findings 輸出供 host LLM 判斷
+instrlint --emit-candidates instrlint-candidates.json --skip-report  # 同上，不印報告
+instrlint --apply-verdicts instrlint-verdicts.json           # 套用 host LLM 的判斷結果並重新呈現報告
 ```
 
 ## CI 整合
@@ -161,10 +168,22 @@ npx instrlint install --codex
 /instrlint
 /instrlint --fix
 /instrlint ci --fail-on warning
+/instrlint --verify
 ```
 
 > **注意：** Claude Code 只在啟動時載入 custom commands。`/reload-plugins` 無法載入新安裝的指令。
 
+### LLM 驗證（`/instrlint --verify`）
+
+`--verify` 觸發兩段式協議，由 host agent（Claude Code 或 Codex）判斷低信心的 findings 以消除 false positive：
+
+1. **輸出 candidates** — instrlint 將需要語意審查的 contradiction / duplicate findings 寫成 `instrlint-candidates.json`
+2. **判斷** — 你（或 host agent）讀取檔案，對每筆 finding 決定 `confirmed` / `rejected` / `uncertain`
+3. **寫 verdicts** — 將判斷結果儲存為 `instrlint-verdicts.json`
+4. **套用** — instrlint 合併 verdicts，過濾被 rejected 的 findings，並重新輸出附有 `✓` / `❓` badge 的報告
+
+instrlint 從不呼叫任何 LLM API，而是將判斷委託給當前 session 中正在運行的 model。
+
 ## 分數與等級
 
 | 等級 | 分數 | 說明 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instrlint",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Lint and optimize your CLAUDE.md / AGENTS.md — find dead rules, token waste, and structural issues",
   "type": "module",
   "bin": {

package/skills/claude-code/SKILL.md

@@ -49,16 +49,16 @@ contradiction / duplicate detector 是純文字啟發式，可能產生 false po
 **Step 1** — 產出 candidates：
 
 ```bash
-npx instrlint@latest --emit-candidates /tmp/instrlint-candidates.json --skip-report --lang <detected>
+npx instrlint@latest --emit-candidates instrlint-candidates.json --skip-report --lang <detected>
 ```
 
 **Step 2** — 讀取並判斷：
 
-用 Read tool 讀 `/tmp/instrlint-candidates.json`。對每個 candidate，根據下方「判斷框架」做出 verdict。
+用 Read tool 讀 `instrlint-candidates.json`。對每個 candidate，根據下方「判斷框架」做出 verdict。
 
 **Step 3** — 寫出 verdicts：
 
-用 Write tool 寫 `/tmp/instrlint-verdicts.json`：
+用 Write tool 寫 `instrlint-verdicts.json`：
 
 ```json
 {
@@ -74,7 +74,7 @@ npx instrlint@latest --emit-candidates /tmp/instrlint-candidates.json --skip-rep
 **Step 4** — 套用 verdicts 並呈現報告：
 
 ```bash
-npx instrlint@latest --apply-verdicts /tmp/instrlint-verdicts.json --format markdown --lang <detected>
+npx instrlint@latest --apply-verdicts instrlint-verdicts.json --format markdown --lang <detected>
 ```
 
 把輸出的 markdown 報告原樣呈現給使用者，不要摘要或改寫。

package/skills/codex/SKILL.md

@@ -43,16 +43,16 @@ contradiction / duplicate detector 是純文字啟發式，可能產生 false po
 **Step 1** — 產出 candidates：
 
 ```bash
-npx instrlint@latest --emit-candidates /tmp/instrlint-candidates.json --skip-report --lang <detected>
+npx instrlint@latest --emit-candidates instrlint-candidates.json --skip-report --lang <detected>
 ```
 
 **Step 2** — 讀取並判斷：
 
-讀 `/tmp/instrlint-candidates.json`。對每個 candidate，根據下方「判斷框架」做出 verdict。
+讀 `instrlint-candidates.json`。對每個 candidate，根據下方「判斷框架」做出 verdict。
 
 **Step 3** — 寫出 verdicts：
 
-寫 `/tmp/instrlint-verdicts.json`：
+寫 `instrlint-verdicts.json`：
 
 ```json
 {
@@ -68,7 +68,7 @@ npx instrlint@latest --emit-candidates /tmp/instrlint-candidates.json --skip-rep
 **Step 4** — 套用 verdicts 並呈現報告：
 
 ```bash
-npx instrlint@latest --apply-verdicts /tmp/instrlint-verdicts.json --format markdown --lang <detected>
+npx instrlint@latest --apply-verdicts instrlint-verdicts.json --format markdown --lang <detected>
 ```
 
 ### candidates.json 格式