git:20260930.bcf8dbd to git:20261029.59e74ed

- # Logic-Lens — Developer Guide (Claude Code)

-

- This file contains instructions for Claude when working on the Logic-Lens repository itself.

-

- ## Project Layout

-

- ```

- logic-lens/

- ├── skills/

- │ ├── _shared/

- │ │ ├── common.md ← Language rule, Iron Law, Logic Score, yaml schema

- │ │ ├── logic-risks.md ← L1–L9 risk taxonomy definitions

- │ │ ├── semiformal-guide.md ← Execution tracing methodology + min thresholds

- │ │ ├── semiformal-checklist.md ← Premises Construction Checklist (single source)

- │ │ └── report-template.md ← Report Template (English + Chinese, single source)

- │ ├── logic-{review,explain,diff,locate,health}/

- │ │ ├── SKILL.md ← Frontmatter + process skeleton (triggers the skill)

- │ │ └── *-guide.md ← Detailed step-by-step instructions (loaded on demand)

- │ └── logic-fix-all/ ← Skill 6: orchestrates the other five into one pipeline

- │ ├── SKILL.md

- │ ├── logic-fix-all-guide.md ← Navigation + shared context

- │ ├── guide-phases-0-2-consent-scope-health.md

- │ ├── guide-phases-3-5-review-locate-clarify.md

- │ └── guide-phases-6-9-fix-iterate-report.md

- ├── .claude-plugin/ ← Claude Code plugin metadata

- ├── .codex-plugin/ ← Codex CLI plugin metadata

- ├── gemini-extension.json ← Gemini CLI extension metadata

- ├── commands/ ← Short command wrappers installed by session-start hook

- ├── hooks/

- │ ├── hooks.json ← Claude Code hook registration (uses ${CLAUDE_PLUGIN_ROOT} — portable across platforms)

- │ └── session-start ← Copies commands/ to ~/.claude/commands/ on session start

- ├── evals/

- │ ├── content/v2/evals-v2.json ← Content benchmark test cases (104, current)

- │ ├── trigger/v2/ ← Trigger benchmark suites (per skill) — see Gotchas before relying on scores

- │ ├── real-world/ ← Real-code probes: second verification line, incl. decoy probes

- │ └── v1/ ← Legacy v1 cases (archived for reference)

- ├── benchmarks/

- │ ├── index.json ← Catalog of published runs

- │ ├── reports/ ← Human-readable markdown reports per version tag

- │ └── runs/ ← Frozen run summaries (workflow: see `benchmarks/README.md`)

- ├── scripts/ ← Shell scripts invoked by `npm run ...` (validate, lint-shell, trigger-evals, content-evals, grader)

- ├── tests/ ← Python unit tests (currently `test_grader.py` for the eval grader)

- ├── docs/ ← Auxiliary docs (model compatibility, research references, case studies, marketing assets)

- ├── .claude/ ← Repo-local dev harness (see "Harness" below)

- │ ├── agents/ ← eval-failure-analyzer, skill-editor, iteration-guard

- │ └── skills/ ← iterate-skill, sync-skill-cache, run-iteration-eval, bump-version, new-skill

- ├── skills-workspace/ ← Scratch space for in-progress skill iterations and benchmark probes (gitignored)

- ├── CONTRIBUTING.md ← Contribution ground rules and versioning policy

- └── AGENTS.md / GEMINI.md ← Companion guides for Codex and Gemini CLI users

- ```

-

- ## Conventions

-

- ### SKILL.md Structure

- - YAML frontmatter: `name` and `description` are required.

- - `description` must include a "Do NOT trigger for:" clause.

- - `description` should be explicit about trigger phrases — err on the side of triggering.

- - Process section: 5–7 numbered items; each item cites a step in the guide file.

- - Setup section: follow lazy loading from `skills/_shared/common.md` §13. Read only the relevant `common.md` sections and the active guide step upfront; load `logic-risks.md`, `semiformal-guide.md`, `semiformal-checklist.md`, `report-template.md`, and later guide sections on demand. Document any required eager read explicitly.

-

- ### Guide Files

- - Numbered steps (Step 1, Step 2, ...).

- - Each step explains the *why*, not just the *what*.

- - Sub-steps use letters (Step 2a, 2b).

- - Concrete examples preferred over abstract descriptions.

-

- ### Risk Codes

- - Built-in: L1–L9 (defined in `skills/_shared/logic-risks.md`)

- - Custom project-specific: C1, C2, ... (defined in `.logic-lens.yaml` at the repo root — optional file, omit if no custom codes needed)

- - Every finding must be tagged with a risk code.

-

- `.logic-lens.yaml` schema: see `skills/_shared/common.md` — `custom_risks` is a list of records with `code`, `name`, `description`, and `severity` fields.

-

- ### Version Sync

- `package.json` is the source of truth for the version number. Use the script — it rewrites all

- six places at once and then runs `validate-repo.sh` to confirm:

-

- ```bash

- npm run bump-version -- 0.7.0

- ```

-

- The six places it touches: `package.json`, `.claude-plugin/plugin.json`,

- `.claude-plugin/marketplace.json`, `.codex-plugin/plugin.json`, `gemini-extension.json`, and the

- `README.md` version badge. `CHANGELOG.md` is **not** touched — add the release entry by hand.

-

- ### Iron Law

- See `skills/_shared/common.md` — Iron Law section. That is the canonical definition; do not duplicate or paraphrase it here.

-

- ## Companion Docs by AI Tool

-

- | File | Read by | Purpose |

- |------|---------|---------|

- | `AGENTS.md` | OpenAI Codex / Agents SDK | Task instructions for agent-based runners |

- | `GEMINI.md` | Gemini CLI | Extension setup and skill invocation for Gemini |

- | `CONTRIBUTING.md` | Human contributors | Ground rules, versioning policy, PR requirements |

-

- ## Development Commands

-

- Logic-Lens has no runtime npm dependencies; `package.json` only declares script entry points. `npm install` is unnecessary.

-

- ```bash

- npm run validate # Validate repo structure, JSON integrity, and metadata consistency (scripts/validate-repo.sh)

- npm run lint-shell # shellcheck every tracked shell script (scripts/lint-shell.sh)

- npm run unit-tests # Run Python unit tests under tests/ (currently grader tests)

- npm run trigger-evals # Run trigger-eval suites under evals/trigger/v2/ (scripts/run-trigger-evals.sh)

- npm run content-evals # Run evals/content/v2/evals-v2.json end-to-end through claude -p + grade (scripts/run-content-evals.sh) — costs API tokens

- npm run bump-version -- 0.7.0 # Sync the version across all six manifests, then validate

- ```

-

- ### 单次迭代评分（不跑完整套件）

-

- ```bash

- python scripts/grade-iteration.py <iteration-dir>

- # 对 skills-workspace/ 下某次迭代打分，无需触发完整 content-evals

- # 详见 scripts/README.md 获取参数说明

- ```

-

- Manual one-liners that don't require the scripts:

-

- ```bash

- # Verify SKILL.md frontmatter exists in all six skills

- grep -l "^name:" skills/*/SKILL.md

-

- # Verify all guide files are present

- ls skills/*/logic-*-guide.md

-

- # Verify version is consistent across all metadata files (5 JSON files + README badge)

- grep '"version"' package.json .claude-plugin/plugin.json .claude-plugin/marketplace.json .codex-plugin/plugin.json gemini-extension.json

- grep -E 'version-[0-9]' README.md

- ```

-

- ## Gotchas

-

- - **`npm run trigger-evals` recall is always 0% for Logic-Lens.** The suite delegates to skill-creator's `run_loop.py`, which asks a model (`claude -p`) whether a query *should* trigger a skill — but Logic-Lens skills are dispatched by Claude Code's IDE plugin mechanism, not by model decision, so every positive case scores 0. The suite is still useful for catching `description` regressions on negative (near-miss) cases; verify real triggers by hand in an interactive Claude Code session. (详细参数说明见 `scripts/README.md`)

- - **`skills-workspace/` 目录结构约定：** 每次迭代建子目录（如 `iteration-a25b6c7/`），完成后在目录内放 `FINAL-REPORT.md`。草稿文件不要散放在根级别。根目录下现有少量历史遗留文件（`COMPARISON.md`、`FINAL-REPORT.md` 等）仅供参考，新工作请严格使用子目录。

-

- ## First Clone Setup

-

- `hooks/hooks.json` uses the `${CLAUDE_PLUGIN_ROOT}` placeholder, so no path edit is needed regardless of where the repo lives.

-

- **1. Run the session-start hook once manually** to install short-form command wrappers (the hook fires automatically on every session start once Claude Code picks the plugin up, but the first install needs a one-shot kick):

-

- ```bash

- # Run from the repo root (macOS / Linux / WSL / Git Bash on Windows):

- bash hooks/session-start

- ```

-

- **2. Verify commands are installed:**

-

- ```bash

- ls ~/.claude/commands/logic-*.md

- # Expected: logic-diff.md logic-explain.md logic-fix-all.md logic-health.md logic-locate.md logic-review.md

- ```

-

- **Platform note:** the hook requires `bash`. On macOS and Linux it is preinstalled. On Windows, Claude Code itself runs under WSL or Git Bash, both of which provide `bash` — no extra install needed. For users installing through the marketplace (`/plugin install`), Claude Code auto-discovers `hooks/hooks.json` and runs the hook on every session — this manual step is only for clone-based development of the plugin itself.

-

- ## Adding a New Skill

- 1. Create `skills/logic-newskill/SKILL.md` following the existing SKILL.md pattern.

- 2. Create `skills/logic-newskill/logic-newskill-guide.md`.

- 3. Add a command wrapper to `commands/logic-newskill.md`.

- 4. No change needed in `gemini-extension.json` — Gemini CLI discovers skills from the `skills/` directory automatically.

- 5. No change needed in `.codex-plugin/plugin.json` — it points at `skills/` directory and auto-discovers subfolders.

- 6. Add the skill name to the `for skill in ...` loop in `hooks/session-start`:

- ```bash

- grep -n "for skill in" hooks/session-start

- ```

- 7. Add 3–5 eval cases to `evals/content/v2/evals-v2.json` (non-explain cases need `expects_defect` — see CONTRIBUTING.md "Eval Cases"; the unit tests enforce it). Optionally add trigger cases to `evals/trigger/v2/trigger-evals-{skill}.json` — but see Gotchas: positive trigger cases always score 0% for Logic-Lens; trigger evals are only useful for catching `description` regressions on negative cases.

-

- ## Harness：Logic-Lens Skill 迭代闭环

-

- **目标:** 把"改 SKILL.md → 同步缓存 → 跑 eval → 诊断 → 验证净收益"的迭代闭环固化为可复用的 agent 团队，避免每次手动踩坑（尤其缓存同步）。

-

- **触发:** 想**提升某个 logic-* skill 的 eval 分数 / 修复失败的 eval 模式**时，使用 `iterate-skill` 编排技能（它会按需调度 `eval-failure-analyzer` / `skill-editor` / `iteration-guard` 三个 agent 与 `sync-skill-cache` / `run-iteration-eval` 两个支撑技能）。单次提问、发版（用 `bump-version`）、新建 skill（用 `new-skill`）不触发本闭环。改完任何 `skills/**` 后跑 eval 前，**必须**先经 `sync-skill-cache` 同步缓存。

-

- **组件位置:** agent 在 `.claude/agents/`，支撑技能在 `.claude/skills/`。

- **变更历史:**

- | 日期 | 变更内容 | 对象 | 原因 |

- |------|----------|------|------|

- | 2026-06-01 | 初始构成：迭代闭环 harness（编排技能 iterate-skill + skill-editor/iteration-guard 两个新 agent + sync-skill-cache/run-iteration-eval 两个支撑技能；复用已有 eval-failure-analyzer/bump-version/new-skill） | 全体 | 把 skill 迭代主线工作固化为 agent 团队 |