# 意图目录编写与使用指南

> 适用对象：所有 agent（Claude Code、Codex、DSH 等）和人。本文件是意图目录语法与 goal 编译流程的**单一来源**。
> 模块：`.blueprint/modules/intent-catalog.md`。设计依据：`docs/tasks/2026-10-04-intent-catalog-design.md`（临时文件，IC3 后删除）。
> 试用期（P8 收口前）只用文档和 shell 单行命令；门控脚本 `intent-gate.cjs` 在 Phase 4 落地后替换「离线检查」一节。

意图目录 `.blueprint/catalog.md` 是蓝图之上由人持有的一层：每章写一个意图方向、怎么判断做对了、不做什么。任务卡单向挂到章上，agent 据此把意图编译成评估器能判定的 /goal。**书装意图，指向事实**：代码、状态、规格、凭据都不进目录，目录里只放指针。

| 角色 | 写什么 | 不写什么 |
|---|---|---|
| 人 | 章的意图、人看、不做；大版本修订；确认小版本、书签切换和 goal 确认卡 | 卡的状态（由 agent 判定）；机器坐标的具体命令 |
| agent | 机器坐标指针、小版本提案、goal 编译、收口回执、卡上的 `- 终验:` 记录 | 章的完成状态（只能推导）；替人改意图 |
| 炼境 | 无，只经 get_project_file 只读提供同一份文件 | 不编译 goal、不选模型、不判定完成 |

## 目录语法

**位置与骨架**：`.blueprint/catalog.md`，放在 modules/ 之外，依次为引言行、书签、各章、墓碑、附录。

```markdown
# 意图目录
> catalog_version: 1.0 | 前言 → path:AGENTS.md#项目定位 | 语法 → path:docs/ai-context/intent-catalog-guide.md

## 书签
- 当前 → path:docs/tasks/2026-10-03-coordination.md#0. 方针与本阶段终点

## INT-01 <章名：一个意图方向>
- rev: 1.0
- 意图: <一句话，人的原意>
- 人看: <人在投影上看到什么就算做对了>
- 机器: <可断言坐标的类型化指针，例如 card:<module>#<卡键>>
- 不做: <边界；多条用「；」分隔>

## INT-09（已撤销）
- 撤销: YYYY-MM-DD → module:<id>#决策记录

## 附录
- <名称> → <类型化指针>
```

**章导语字段**：

| 字段 | 必填 | 含义 |
|---|---|---|
| rev | 是 | 该章最后一次变更时的目录版本，不大于 catalog_version |
| 意图 | 是 | 人的原意，一句话 |
| 人看 | 是 | 人看的投影坐标（对应 human_verify） |
| 机器 | 是 | agent 可断言的坐标，只写指针，不写命令全文 |
| 不做 | 是 | 边界，agent 扩范围时的刹车 |
| 风险 | 否 | 低、中、高，或指向不可逆操作的说明 |
| 假设 | 否 | 指向既有的证伪落点（某张 spike 卡或复盘），目录里不存证伪状态 |
| 证据 | 否 | 指向已有证据（卡上的 verify 记录、PR） |
| 墙 | 否 | 关联的承重墙编号，例如 `W12,W13` |

**防膨胀（硬限制）**：

- 每个字段只写一行，不超过 120 字；
- 每个章块不超过 12 行；
- 全文件不超过 200 行、8KB；
- 禁止出现 `status`、`progress`、`doc`、`files`、`acceptance`、`model` 键，也不写模型名；
- 不设文件内修订历史，修订历史看 git log。

**类型化指针**（多个指针用「；」分隔）：

| 前缀 | 写法 | 校验方式 |
|---|---|---|
| path: | `path:<相对路径>[#标题前缀]` | 文件存在；有 `#` 时标题能匹配 |
| module: | `module:<id>[#段名]` | `.blueprint/modules/<id>.md` 存在 |
| card: | `card:<module>#<卡键>` | 该模块里存在这张卡；卡键取标题去掉状态前缀后的第一个 token，例如 `IC6`、`P8e` |
| spec: | `spec:<路径>#标题` | 指向子项目已有的规格（例如 `.specify/specs/...`），只指向不复制 |
| cmd: | `cmd:<命令或工具名>` | 只校验格式，不执行 |
| W | `W1`–`W14` | 承重墙编号，定义见模块文件「承重墙」节 |

**ID 规则**：章用两位数 `INT-NN`，永不复用。撤销的章保留墓碑 `## INT-NN（已撤销）`，注意编号后面紧跟全角括号、没有空格。

**卡侧挂靠（单向）**：

- 卡上可选写一行 `- intent: INT-NN@X.Y`，放在 `- complexity:` 后面，表示这张卡服务哪一章、编译自目录哪一版。
- 模块头 blockquote 可选写 `| intent: INT-NN` 作为整个模块的默认挂靠，不带版本，影响分析里计为低置信。
- 章的「机器:」只是验收坐标，不登记成员名单。反向索引现算，不存储。

**终验记录**：卡上另起一行 `- 终验: YYYY-MM-DD 通过|否决：<理由>`，由 agent 记录人在会话里给出的裁决。不要写进 `- notes:`，因为多条 notes 后一条会覆盖前一条。

**解析器约束**：模块 md 里，「任务卡」段以外一律不用 `###`。未识别的 `##` 段下出现 `###` 会被当成任务卡。

## 修订与钉版

**版本**：引言里写一个 `catalog_version: X.Y`；每章有自己的 `rev`。这套版本号与 manifest.iteration 互不借号。

| 级别 | 什么时候 | 怎么做 | 版本变化 |
|---|---|---|---|
| 补丁 | 只改正文（卡、模块），目录不动 | agent 自主完成，照常走需求对齐协议 | 无 |
| 小版本 | 改某章的人看、机器或不做；由正文反推修改目录 | agent 提出 S 级三行确认卡，附 diff 和 base blob，人说「确认」 | Y+1；被改章的 rev = 新版本 |
| 大版本 | 增删章节、调整方向 | 人主导，agent 协助起草 | X+1、Y 归零；涉及的章更新 rev；删掉的章留墓碑；按 T4 检查 AGENTS.md「项目定位」 |

**提案**：附上目录 diff 和 base blob，base blob 用下面的命令取：

```bash
git rev-parse --short HEAD:.blueprint/catalog.md
```

人确认后提交，提交前再取一次 blob。如果已经不等于 base，说明目录被别人改过，必须重新提案，不能硬合。

**提交格式**：

- 首行：`docs(intent): <改了什么>`
- body：一句理由，必要时写来源，例如某次终验否决、某张卡的设计发现。
- 末尾：带 `Feature-Confirmed: true`。
- 目录改动单独小提交，不和代码混在一起。

**钉版**：卡写 `- intent: INT-NN@X.Y`；goal 标签写 `INT-NN@X.Y#<blob7>`。

**影响分析**：

| 判定 | 条件 | 处理 |
|---|---|---|
| stale | 卡钉的版本低于章 rev，且卡未完成 | 复核 acceptance。没变化就改钉，算补丁，并在简报里报告；有变化就按小版本走 |
| orphan | 卡钉在已撤销的章上 | 停下找人，决定改挂哪一章还是撤卡 |
| low_confidence | 卡只有模块默认挂靠，没有卡侧钉版 | 编译 goal 前补写卡侧 intent |

**在制品保护**：钉旧版的 🔵 卡照常做完，只复核 acceptance。章被撤销，或新的「不做」覆盖了这张卡时，停下找人。任何情况下都不自动改写卡。

## goal 编译

本流程只依赖读文件和 git，不依赖任何特定客户端或模型。Claude 的 /architect 只是可选包装，任何 agent 都可以照着手工执行。产出是一张目标确认卡加一段 /goal 文本。

1. **定位**
   - 读 `.lian-jing/context.json` 取 project_id；记下当前分支、worktree 路径和 `git rev-parse --short HEAD`。
   - 要求 `git status --porcelain -- .blueprint/catalog.md` 输出为空：目录有未提交改动时不编译。
   - 取 catalog blob：`git rev-parse --short HEAD:.blueprint/catalog.md`。
2. **读书签**：书签指向当前章（P8 期间指向 coordination §0 的终点）。读该章的导语和 rev。
3. **校验**：跑「离线检查」一节的全部命令（Phase 4 后改为 `node .claude/hooks/intent-gate.cjs --report INT-NN --impact`）。只要出现悬空指针、stale 或 orphan、防膨胀超限，就先修或先提案，不往下编译。
4. **收卡**
   - 取挂在本章、标题前缀为 📋 或 🔵 的卡。
   - 没有可执行 agent_verify 的卡，列入「须先补 acceptance」，不进 goal。
5. **合成终点**
   - 取各卡 agent_verify 的合取，改写成在会话里能判定的形式：贴出命令和预期输出、纳入卡前缀都是 ✅、回执已写入。
   - human_verify 不进终点，单列为终验待办。
   - 过程词黑名单命中数必须为 0：「按方针」「符合设计」「设计已完成」「基本完成」，以及任何无法从会话输出判定的形容词。
6. **写停止条件**：遇到以下任一情况必须停下找人：
   - human_verify；
   - 写运行中的数据库；
   - 删除文件、数据或分支；
   - 凭据或机器状态变更；
   - 超出纳入卡或本章范围；
   - 需要修改目录；
   - 出现 stale 或 orphan；
   - 同一问题失败 3 次。
7. **输出**：一张目标确认卡（格式见下一节），加 /goal 文本，首行带同样的标签。人读完亲手粘贴就算确认；要改就重新编译。agent 不得自行启动 goal，也不得静默改写 goal 文本。

## 确认卡与回执

**目标确认卡**（兼作最小任务简报，新会话只读它就能开工）：

```text
[INT-NN@X.Y#<blob7>] 目标确认卡
项目: <project_id> | 分支/worktree: <branch> @ <path> | HEAD: <sha7>
章意图: <一句> | 不做: <…>
纳入卡: <卡键>（来源 agent_verify 原文）、<卡键>（…）
终点（合取）: 1) <命令> → <预期输出>  2) …  3) 纳入卡均 ✅ 且已写 Goal-Receipt
终验待办: <各卡 human_verify>
停止找人: <第 6 步清单>
能力入口: <校验命令，例如 pnpm typecheck / cargo test；可用的 MCP 工具>
没验什么: <编译时已知的盲区>
作废: 分支变化或 catalog blob ≠ <blob7>
```

由非 Claude 客户端编译时，在提交 body 里另加一行 `Compiled-By: <客户端名>`，用于跨 agent 验证。

**收口回执**：goal 收口时写进收口提交的 body；M 级同时复制到 PR body；炼境在线时可以再调一次 append_project_note。

```text
Goal-Receipt: INT-NN@X.Y#<blob7>
Goal-Cards: <纳入卡键列表>
Goal-Result: 判对|误判|中止(<原因>)
Goal-Rounds: <轮数>
Goal-Interventions: <人工介入次数>
Goal-Tokens: <客户端可得时填，否则 n/a>
Not-Verified: <没验什么>
Human-Pending: <待人终验项>
```

回执不写进模块决策记录，因为 UI 会把它当决策展示；也不要手改 `.blueprint/notes-archive.jsonl`，它以炼境 DB 为事实源，会被整文件重写。

## 离线检查

试用期的检查全部是 shell 单行命令，在仓库根目录执行。期望输出写在每条后面的注释里。

```bash
# 1. 版本行恰好一行
grep -c '^> catalog_version: ' .blueprint/catalog.md                      # → 1
# 2. 有效章数（墓碑不计）
grep -cE '^## INT-[0-9]{2} ' .blueprint/catalog.md                       # → 章数
# 3. 体量
wc -l < .blueprint/catalog.md; wc -c < .blueprint/catalog.md             # → ≤200 行、≤8192 字节
# 4. 禁用键与模型名
grep -cE '^- (status|progress|doc|files|acceptance|model):' .blueprint/catalog.md   # → 0
# 5. path 指针可解析（没有输出即通过）
grep -oE 'path:[^ #；|]+' .blueprint/catalog.md | sed 's/^path://' | sort -u | while read -r p; do test -e "$p" || echo "悬空: $p"; done
# 6. module 指针可解析（没有输出即通过）
grep -oE 'module:[a-z0-9-]+' .blueprint/catalog.md | sed 's/^module://' | sort -u | while read -r m; do test -e ".blueprint/modules/$m.md" || echo "悬空: $m"; done
# 7. 卡侧 intent 引用的章都存在且未撤销（没有输出即通过）
comm -23 <(grep -hoE '^- intent: INT-[0-9]{2}' .blueprint/modules/*.md | grep -oE 'INT-[0-9]{2}' | sort -u) <(grep -oE '^## INT-[0-9]{2} ' .blueprint/catalog.md | grep -oE 'INT-[0-9]{2}' | sort -u)
# 8. 钉版与章 rev 对照（人工比对：钉的版本低于 rev 且卡未完成，即为 stale）
grep -hoE 'intent: INT-[0-9]{2}@[0-9]+\.[0-9]+' .blueprint/modules/*.md | sort | uniq -c
awk '/^## INT-[0-9]{2} /{c=$2} /^- rev:/{print c, $3}' .blueprint/catalog.md
# 9. 改模块 md 前后的任务卡计数应相等（新增卡时等于新增数），防止误写 ###
cat .blueprint/modules/*.md | grep -c '^### '
# 10. goal 文本的过程词黑名单（把 /goal 文本存成临时文件后检查）
grep -cE '按方针|符合设计|设计已完成|基本完成' <goal 文本文件>              # → 0
```

card: 指针目前只能人工核对，到模块文件里搜索卡键，Phase 4 后由门控自动校验。指针中带 `#标题` 的部分，也是同样的人工核对方式。