.blueprint/manifest.yaml

@@ -528,8 +528,8 @@ modules:
   - id: intent-catalog
     name: 意图目录
     area: backend
-    status: planned
+    status: in_progress
-    progress: 0
+    progress: 15
     updated: 2026-10-04
     note: "两层模型（人持有的意图目录 .blueprint/catalog.md + 蓝图正文），书装意图、指向事实；卡侧 intent 钉版，agent 编译可判定 /goal，确认卡兼作最小任务简报，回执写进提交。IC1 设计已确认（最小文件优先方案）；IC2–IC4 只新增文档、可与 P8 并行，门控与接线等 P8 收口后做，IC13 按实测数据决定去留。"
     position: [4000, 950]

.blueprint/modules/intent-catalog.md

@@ -1,6 +1,6 @@
 # 意图目录（intent-catalog）
 
-> status: planned | created: 2026-10-04 | 设计：docs/tasks/2026-10-04-intent-catalog-design.md（IC1 ✅，用户 2026-10-04 确认）| 下一步：IC2
+> status: in_progress | created: 2026-10-04 | 设计：docs/tasks/2026-10-04-intent-catalog-design.md（IC1 ✅，用户 2026-10-04 确认）| 指南：docs/ai-context/intent-catalog-guide.md（IC2 ✅）| 下一步：IC3（首批章节由用户定稿）
 > 来源：2026-10-03～04 与用户讨论（/goal 与 Loop Engineering 操作手册、目录/正文模型、承重墙），以及侦察工作流 wf_6dc3756a-b72 的重叠与冲突扫描。
 
 ## 概述
@@ -103,8 +103,8 @@ agent 开发子项目时躲不掉的现象。每面墙都要回答四个问题
 - acceptance: "agent_verify: [读文件] 设计文档含方案选择、设计规格 1–7、13 问化解表、W1–W14 四问表、受影响文件、系统边界变更、风险点、拆解建议、度量与退出、立法草案、没验什么。human_verify: 用户确认设计（含 5 个待拍板问题），确认后模块转 planned 并追加 IC2–IC13。"
 - notes: 2026-10-04 评审团工作流 wf_60e4c430-bb1 出稿（最小文件优先方案胜出，两位评委 25/30、24/30），设计文档已写，等用户确认。产出 `docs/tasks/<日期>-intent-catalog-design.md`，以 W1–W14 为纲、书模型为体，逐条化解上面的待设计问题，写明收益度量与退出条件；完成后交用户确认，确认后模块转 planned，再用 /splitter 拆成 S/M 卡。
 
-### 📋 IC2 — 新增 intent-catalog-guide.md：目录语法、修订钉版、goal 编译七步、确认卡与回执、离线检查
+### ✅ IC2 — 新增 intent-catalog-guide.md：目录语法、修订钉版、goal 编译七步、确认卡与回执、离线检查
-- status: todo
+- status: done
 - complexity: S
 - files: docs/ai-context/intent-catalog-guide.md
 - depends: IC1

docs/ai-context/intent-catalog-guide.md

@@ -0,0 +1,212 @@
+# 意图目录编写与使用指南
+
+> 适用对象：所有 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 后由门控自动校验。指针中带 `#标题` 的部分，也是同样的人工核对方式。