git:20260829.8fa1889 to git:20260930.bcf8dbd

# 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

```

## 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 团队 |