CLAUDE.md git:20260423.9c2d50dA

Immutable. This exact content is served forever at /api/v1/blob/86be2cceb5912278.

# Doc Harness — Entry Document

> 🔒 **AGENT IDENTITY LOCK**
>
> **你是 doc-harness 项目的代理。**
> 你的职责是维护 Doc Harness skill（文档化项目控制框架）——包括规范制定、模板更新、命令实现（init/check/sync/flush/recall）以及双语同步。
>
> 如果你对自己的身份有任何怀疑，立即停止操作并重新读取本段落。

---

**Last updated**: 2026-04-24
**Current phase**: Phase 4 → Maintenance & field-feedback watch (⏳ active — v1.6.1 flush + v1.7.0 resume shipped)
**One-line status (as of 2026-04-24)**: v1.7.0 shipped — sixth command `/doc-harness resume` adds structured state recovery with Recovery Report (7 sections) + Understanding Verification (5 questions). v1.6.1 flush hardening also included. Bilingual sync complete. 6 commands: init/check/sync/flush/recall/resume.

---

## Recovery Chain

### Must-read (baseline)

1. This file (CLAUDE.md)
2. `CURRENT_STATUS.md`

### Task-conditional

- If `inbox/` has any file with `status: unread`: read and action those first
- If looking up a file: read `FILE_INDEX.md`
- If investigating phase history: read `WORKLOG.md`
- If editing the spec or operational rules: read `skill/spec.md` (authoritative)
- If looking for principles forged by project practice: read `PHILOSOPHY.md`

### Meta-rules

- Self-contained: all entries point to project-internal files. No dependency on agent-side features.
- Living: review at phase transitions.

## Project Overview

Doc Harness is a Claude Code skill that provides document-based project control for AI-human collaboration. It creates and maintains 5 status documents per project (CLAUDE.md, CURRENT_STATUS.md, FILE_INDEX.md, WORKLOG.md, DOC_HARNESS_SPEC.md) that enable any agent or human to understand and resume project work purely from reading files.

**Six commands**: `/doc-harness init` (create docs), `/doc-harness check` (audit + reflect), `/doc-harness sync` (repair drift), `/doc-harness flush` (emergency save), `/doc-harness recall` (retrieve information), `/doc-harness resume` (recover state).

**Core principle**: "Write It Down or Lose It" — context info is temporary, files are permanent.

**Origin**: Designed and validated in `D:\Projects\project_reorganization\` (7 phases, 2026-04-01 ~ 04-03), then published as standalone skill.

## Project-Level Iron Rules

1. **中英文版本永远同步**: Every change to skill/ must be mirrored to skill-zh/, and vice versa. No exceptions.
2. **Doc Harness adapts to project, not project to Doc Harness**: The skill must accommodate diverse project structures. Never impose rigid templates that break existing workflows.
3. **spec.md is the authoritative specification**: All other files (operational_rules.md, init.md, check.md, README) derive from spec.md. Contradictions are resolved in favor of spec.md.
4. **Test before release**: Every change must be validated (blind test, real project test, or simulation) before pushing to GitHub or updating installed copies.
5. **Deployment sync**: After any change, update all 3 locations: dev source → GitHub push → installed copies (user-level + project-level).

6. **Inter-project communication via inbox/outbox (file-based protocol)**

   - **Mechanism**: This project maintains `inbox/` (received messages) and `outbox/` (sent messages). Messages are Markdown files with YAML frontmatter; filename `YYYY-MM-DD-from-<source>-<topic>.md`.
   - **Why this is mandatory (if adopted)**: Cross-project information exchanged only in chat is lost on session end. File-based messages survive session boundaries and are discoverable by any future agent through this project's Recovery Chain.
   - **Receiving**: Recovery Chain checks `inbox/` for `status: unread`. Read → update to `status: read`. After acting on the message → `status: actioned`. Never edit received messages beyond the status field; to respond, write a new message.
   - **Sending**: Write to this project's `outbox/` (permanent sender-side record) AND copy the same file into the recipient project's `inbox/`. Record the exchange in CURRENT_STATUS so it is traceable next session.
   - **Snapshots over pointers**: When communicating numbers/deliverables to another project, put the value in the message body rather than referencing internal files.
   - **Full specification**: `DOC_HARNESS_SPEC.md` §14 (in this project's root).

## Key Technical Information

**GitHub**: https://github.com/cilidinezy-commits/doc-harness (latest tag: v1.4)
**License**: MIT

**File structure**:
```
doc-harness/
├── skill/           ← English skill files (5 files, authoritative)
├── skill-zh/        ← Chinese skill files (5 files, synced)
├── README.md        ← English project description
├── README_zh.md     ← Chinese project description
└── LICENSE          ← MIT
```

**Deployment locations** (installed copies must match dev source):
- User-level: `~/.claude/skills/doc-harness/` ← from `skill/`
- Project-level (ObsVault_Tools): `.claude/skills/doc-harness/` ← from `skill/`

**Skill files** (same structure in both skill/ and skill-zh/):
| File | Role |
|------|------|
| SKILL.md | Entry point + router |
| init.md | `/doc-harness init` — create 5 docs |
| check.md | `/doc-harness check` — audit + reflect |
| operational_rules.md | Rules embedded in each project's CLAUDE.md (180 lines as of v1.4; delimited by `<!-- doc-harness-ops-start/end -->` sentinels) |
| spec.md | Complete specification (1320 lines as of v1.4, 14 chapters + 5 appendices, TOC at top) |

## Doc Harness — Operational Rules

> Complete specification: see `DOC_HARNESS_SPEC.md` in this directory.
> This section was last refreshed from `skill/operational_rules.md` at v1.6.1.

### Core Principle: "Write It Down or Lose It"

Important information must be **written to a file** and **registered in FILE_INDEX**. Not written = lost. Not registered = undiscoverable = effectively lost.

### Four Core Documents

| Document | Role | When to update |
|----------|------|---------------|
| **CLAUDE.md** | Project entry | Phase transitions; one-line status every session end |
| **CURRENT_STATUS.md** | Active status | Every session |
| **FILE_INDEX.md** | File catalog by category | When files created/deleted |
| **WORKLOG.md** | Complete history (append-only) | Phase transitions |

### Sync vs. Flush — Critical Distinction

- **`sync`** repairs existing documents (drift fix, date refresh, file registration).
- **`flush`** **must perform a context inventory and create or append new documents** from that inventory. If a flush produces no Phase B (inventory) and no Phase C (new files), it has failed — the agent performed sync, not flush. Even when no extractable items are found, flush must produce an explicit empty-scan report proving Phase B was executed.

### Session End Checklist

- [ ] CURRENT_STATUS reflects all work?
- [ ] Next steps accurate?
- [ ] Dates refreshed?
- [ ] New files registered in FILE_INDEX?
- [ ] Anything unsaved? → Write it down!