# CLAUDE.md

<!--
  Auto-generated by bollharness installer.
  This file is the primary instruction source for Claude Code sessions.
  Edit freely — the installer will NOT overwrite an existing CLAUDE.md.
-->

## Project Overview

<!-- TODO: 描述你的项目 — 做什么、技术栈、部署方式 -->

## Governance System (bollharness)

This project is managed by [bollharness](https://github.com/anthropics/bollharness) — an AI agent session governance framework. The following hooks and guards run automatically during Claude Code sessions.

### Hook Lifecycle

| Stage | Hook | What it does |
|-------|------|-------------|
| SessionStart | `session-start-reset-risk.ts` | Reset risk snapshot for new session |
| SessionStart | `session-start-magic-docs.ts` | Load project-specific context documents |
| SessionStart | `session-start-toolkit-reminder.ts` | Surface available skills and tools |
| PreToolUse * | `tool-call-counter.ts` | Track tool call frequency for observability |
| PreToolUse Bash | `deploy-guard.ts` | Block unauthorized deployments |
| PreToolUse Bash | `auto-python3.ts` | Intercept bare `python` → `python3` |
| PreToolUse Task | `review-agent-gatekeeper.ts` | Enforce read-only isolation on review agents |
| PreToolUse Read\|Bash | `sanitize-on-read.ts` | Sanitize sensitive data in read output |
| PostToolUse Edit\|Write | `guard-feedback.ts` | Context routing + guard checks (ADR-030) |
| PostToolUse Edit\|Write | `loop-detection.ts` | Detect edit-undo-edit loops |
| PostToolUse Edit\|Write | `risk-tracker.ts` | Update risk snapshot on file changes |
| PreCompact | `precompact.sh` | Preserve critical context before compaction |
| Stop | `stop-evaluator.ts` | Completion proposal + independent review |
| SessionEnd | `session-reflection.ts` | Session summary and learnings |
| SessionEnd | `trace-analyzer.ts` | Aggregate trace data for harness optimization |
| SessionEnd | `deploy-progress-on-session-end.ts` | Persist deployment progress metrics |
| PostToolUseFailure | `failure-analyzer.ts` | Diagnose tool call failures |

### Runtime Directories

```
.boll/
├── state/        # Risk snapshots, session state (gitignored)
├── guard/        # Guard flags, injection dedup (gitignored)
└── metrics/      # Observability data — JSONL event logs (gitignored)
```

These directories are **runtime-only** and gitignored. They are created automatically by hooks.

## AI Behavioral Constraints

### Language
- All user-facing output in **simplified Chinese**; technical identifiers stay original
- All commit messages **bilingual** (English title + Chinese summary)
- Co-Authored-By header: `Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>`

### Code Quality
- All commands use `npx ts-node`, never bare `python`
- Subagent model: review/audit/evaluator agents must use `claude-opus-4-6`
- Review agents: tool whitelist must be schema-level isolated (no Edit/Write/Bash)

### Workflow
- **Issue-first**: create `docs/issues/guard-*.md` before fixing any guardian finding
- **Verification honesty**: partial test pass ≠ full pass; closure needs evidence
- **No half-finished work**: no TODO/FIXME left behind without tracking

## Guardian Issue Workflow

Guardian/red-team findings go to `docs/issues/*.md` with YAML frontmatter:

```yaml
---
status: open          # open | fixed | wont_fix
prevention_status: open  # open | closed
mechanism_layer: guard   # guard | test | type | convention
severity: P1          # P0 | P1 | P2 | P3
component: path/to/affected/file
---
```

Rules:
- Never fix guardian issues directly on `main` — use a dedicated branch
- Close only after verification is recorded with evidence

## Path-Scoped Rules

Path-scoped rules in `.boll/rules/*.md` auto-load when Claude reads files matching their trigger patterns. No manual loading needed.

<!-- TODO: 列出你的 path-scoped rules 及触发路径 -->