# 意图目录（intent-catalog）

> 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 ✅）| 目录：.blueprint/catalog.md 1.0（IC3 ✅）| 下一步：IC5（P8 收口后首次真实 /goal）
> 来源：2026-10-03～04 与用户讨论（/goal 与 Loop Engineering 操作手册、目录/正文模型、承重墙），以及侦察工作流 wf_6dc3756a-b72 的重叠与冲突扫描。

## 概述

在蓝图之上加一层由人持有的意图目录 `.blueprint/catalog.md`：每章写意图、双坐标、不做什么和 rev；任务卡用 `- intent: INT-NN@X.Y` 单向挂靠。agent 据此编译可判定的 /goal，确认卡兼作最小任务简报，收口回执写进提交。试用期只新增文档，门控与接线排在 P8 收口后，按实测数据决定保留或撤销。

## 为什么

- 用户能给的是需求、意图方向和已知现状，不是评估器能判定的条件。/goal 这类无人值守 loop 需要可判定的终点，这一步翻译应由 agent 完成，但 agent 需要一个人持有、稳定的意图来源。
- 现状：意图散在 AGENTS.md「项目定位」、统筹文档 §0、设计文档的决策节、manifest description 和私有记忆里；manifest 的 areas 按技术层分区，不按意图方向。
- 实证：2026-09-30 的 `/goal 按照方针设计方向走，直到符合设计要求` 跑了 3 轮，评估器就以「设计已完成」为由判定达成并解除了 goal。评估器不读文件，条件只能写成可判定的终点。
- 与 `docs/tasks/2026-09-23-blueprint-agent-handoff-pilot.md` 的「项目工作账本 + 信息归属 + 最小任务简报」同构，应合并推进，不能分两处做。

## 模型（概念，待设计确认）

- **两层**：目录层由人持有，保持稳定；正文层是蓝图模块与任务卡，由 agent 维护。
- **书的比喻**：
  - 前言是长期方针，只指向 AGENTS.md「项目定位」，不另抄一份。
  - 每一章是一个意图方向。
  - 章首导语写意图、双坐标（人看的投影坐标 + agent 可断言的坐标）和「不做什么」。
  - 附录放现状指针、约束、决策与否决理由（勘误表）。
  - 索引是稳定 ID，书签标出当前阶段。
- **定位**：它是全生命周期信息的骨架与索引，不是容器——**书装意图，指向事实**。代码、CI、状态、会话、凭据和环境都留在原生位置，书里只放可机器校验的指针；意图由人写，现状由机器采。
- **迭代**：
  - 修订分三级：补丁指正文内的改动，agent 自主完成；小版本指调整章首坐标或由正文反推修改目录，agent 提案、人确认；大版本指增删章节或调整方向，由人主导。
  - 配套机制：沿 ID 做影响分析；版本钉住，卡和 goal 记录自己编译自哪一版目录；保护在制品；修订历史回流飞轮。
- **/goal 的来源**：由架构 agent 从「当前章的验收坐标 + 本阶段卡的完成判定」编译，人确认后粘贴，粘贴这一下即确认。

## 承重墙（设计纲目）

agent 开发子项目时躲不掉的现象。每面墙都要回答四个问题：落在书的哪个部位、靠什么机制承重、怎样用机器检查它生效、什么情况下算拆除（拆除即撤销对应机制）。原则是能指向已有机制的，就不新建。

| 墙 | 已有承重机制（指向） | 待补 |
|---|---|---|
| W1 迭代 | 模块迭代记录与决策记录；能力包、托管块、模板指纹三重版本 | 目录版本层、修订分级、版本钉住；与 manifest.iteration 语义分开 |
| W2 遗忘 | 启动读蓝图；catchup/taskify；统筹文档 §0；复盘笔记 | 稳定入口回答「整体方向走到哪」；书签载体；方向与卡的双向索引 |
| W3 熵增 | 文档防腐 T1–T4；模板指纹测试；blueprint-gate；梦核蒸馏 | 指针可解析门控（只警告）；禁止索引膨胀成正文 |
| W4 意图鸿沟 | 需求对齐协议与确认卡；Feature-Confirmed；双尺子；辩证收缩 | 章级意图与「不做什么」；卡挂回意图章 |
| W5 注意力稀缺 | 统筹三类找人；pending_user；回传只列待处置 | 跨章的「待人裁决」视图；书签由人确认 |
| W6 理解债 | 决策记录；复盘笔记；架构速查；导师上下文 | 从代码或模块反查「服务哪条意图」；关键决策摘要推送给人 |
| W7 自评偏差 | 两把尺子；「没验什么」；证据等级；独立/对抗审查；CI 兜底 | 章坐标标注证据等级；章完成只能推导，不能手动切换 |
| W8 不确定性 | R10 先实测；P4-0 假设证伪；三闸门 | 探索章（轮廓、试探、预算、收敛信号）→ 结晶为定型章；「假设:」指向既有的证伪落点（2026-10-04 修订） |
| W9 并发冲突 | 🔵 执行锁；每卡独立 worktree；串行队列；plan→digest→apply | 目录本身成为争用点；版本钉住复用 digest 语义 |
| W10 风险不对称 | 计划→确认→应用；confirmed=true；破坏性标注；凭据边界 | 目录大版本与书签切换的「提案 + digest + 人确认」；章级风险等级 |
| W11 资源有限 | L0/L1/L3 分层；风险预测；提交飞轮指标 | 按章、按 goal 记账（只记账不分配，不替 agent 选模型） |
| W12 环境漂移 | 工具链状态；诊断；verify_onboarding；L1 对等检查 | 基本齐全，目录只放工具指针 |
| W13 异构 agent | canonical context；AGENTS.md 跨端单一来源；三端对等 | 模型无关的 goal 编译流程（/architect 只有 Claude 有） |
| W14 摩擦重复 | 使者回传闭环；梦核；Rules-Applied；管家准入 | 修订历史与否决理由回流（复用 envoy 与复盘笔记，不新建账本） |

## 并入与依赖

- **并入**：handoff 试点中的「信息归属与同步契约」和「最小任务简报的按需读取与回执」两项。
- **留在 blueprint-governance 作为前置**：「安全派发 + blueprint-baseline 能力包」和「任务状态语义收敛」。
- **依赖**：blueprint-governance（安全派发）、agent-client-capability-packs（版本化 pack 机制）。
- **相关**：governance-feedback-loop（修订历史与否决理由回流）。

## 待设计问题（IC1 须逐条化解）

1. 「意图层」现有三处归属：CONVENTIONS「蓝图定位（意图层）」、agent-button-system「意图层 — AGENTS.md」，以及本模型。设计时需先定死术语映射，并且只在一处改名。
2. 红线：章的完成只能从卡状态加 human_verify 推导，不能做成人手动切换（AGENTS.md 设计红线）。
3. 前置：CONVENTIONS 中 in_progress/done 一处说从 Git 推断、另一处说手标，影响分析不能建立在未收敛的状态语义上。
4. 分类轴对应：修订分级、需求对齐协议（Bug/Feature × S/M/L）、文档元规则 T1–T4、manifest.iteration 之间的对应关系；考虑新增 T5「意图变更」，避免另起一套。
5. ID 前缀：承重墙用 W1–W14，章用 INT-xx，卡用 IC（2026-10-04 用 git grep 确认均未被占用）。
6. 「goal 级确认可代替逐卡确认」：起草立法提案，边界是写运行中的 DB、删除、human_verify、超出当前章的工作仍须找人。等 P8 跑完、用实测数据再定。
7. W11 只记账、不分配；CONVENTIONS 复杂度表把复杂度映射到模型名，与 handoff 的「不映射模型名」矛盾，交给前置一起收敛。
8. 防止容器化：目录只放 ID、一句话意图和指针（参照 project-context.yaml 的 label/paths，但禁止长 doc 字段），并配一个只警告的指针可解析门控。
9. 书签与统筹文档 §0 的交接：P8 期间只做指向；之后改为 agent 起草书签、人确认，统筹文档只管派单与交接。
10. 离线与降级：目录放在项目 Git 中、离线可读；影响分析与跨项目索引走 MCP 查询，并保留直接读文件的降级路径。
11. 跨 agent：goal 编译流程写成模型无关的形式（CONVENTIONS「复杂功能分析流程」），不能只靠 Claude 的 /architect。
12. 子项目已有的意图载体（例如 enterprise 的 `.specify/specs/.../spec.md`）只做指向，不复制。
13. 目录的物理位置与前言的归属（例如 `.blueprint/catalog.md`、`docs/intent/`，或放在 AGENTS.md 块外）。

## 不做什么

- 设计确认且 P8 收口之前，不写代码，不改接入包模板、CONVENTIONS、AGENTS.md、分发层和 P8 热点文件。
- 不给存量卡回填 `intent:`；试用阶段只在新卡上可选填写。
- 炼境不替 agent 编译 goal、选模型或判定完成；炼境只提供结构、校验、现状采集与查询。
- 不把蓝图的版本化事实源搬进炼境 DB，不让子项目依赖炼境在线，不建派发调度器。

## 分阶段

1. 立 concept 模块（本次）。
2. IC1 设计文档，与 P8 并行，只写文档。
3. 在炼境自身试用：新增目录文件，新卡可选 `intent:`。
4. P8 收口后：补前置，加只读校验与影响分析。
5. enterprise 隔离试点。
6. 按实测结果决定：并入能力包分发，或撤销。

## 收益度量与退出条件

- 度量：/goal 一次判对率、人工介入次数、续接所需的上下文量、方向返工与 human_verify 否决率、每阶段 token 用量；探索章另看收敛轮数、是否守住预算、否决理由是否逐轮减少。
- 退出：实测无收益、已被 agent 原生能力覆盖，或维护成本超过收益时撤销（管家准入与退出）。

## 任务卡

### ✅ IC1 — 意图目录设计文档（/architect）
- status: done
- complexity: L
- files: docs/tasks/2026-10-04-intent-catalog-design.md, .blueprint/modules/intent-catalog.md
- 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 编译七步、确认卡与回执、离线检查
- status: done
- complexity: S
- files: docs/ai-context/intent-catalog-guide.md
- depends: IC1
- acceptance: "agent_verify: [CLI] grep -cE '^## (目录语法|修订与钉版|goal 编译|确认卡与回执|离线检查)' docs/ai-context/intent-catalog-guide.md → 5；grep -ciE 'opus|sonnet|haiku|gpt-|deepseek-' 该文件 → 0；/architect 只以「可选包装」出现；git status --porcelain → 只有该文件新增。"

### ✅ IC3 — 新增 .blueprint/catalog.md：1.0 骨架与首批 2–4 章，书签只指向 coordination §0
- status: done
- complexity: S
- files: .blueprint/catalog.md
- depends: IC2
- acceptance: "agent_verify: [CLI] grep -c 'catalog_version: 1.0' → 1；grep -cE '^## INT-[0-9]{2} ' 介于 2–4；wc -l ≤200 且 wc -c ≤8192；grep -cE '^- (status|progress|doc|files|acceptance|model):' → 0；指南中的 path 指针检查 → 0 悬空；cat .blueprint/modules/*.md | grep -c '^### ' 前后相等。human_verify: 用户逐章确认意图与不做（1.0 为大版本，人定稿），提交带 Feature-Confirmed: true。"

### ✅ IC4 — 跨 agent 纸面编译：Codex 或 DSH 按指南对书签章编译确认卡（不粘贴）
- status: done
- complexity: S
- files: .blueprint/modules/intent-catalog.md
- depends: IC3
- notes: 2026-10-04 报备改断言：目标章由「书签章」改为指定 INT-02。理由：书签所指的 INT-01（P8）卡在统筹会话的 agent-client-parity.md 中，且几乎全为 ✅，纸面编译无测试价值；INT-02 挂有 IC6–IC10 五张待做卡，纸面编译即 IC5 的预演。
- result: 2026-10-04 Codex 纸面编译通过：9 个字段齐全；标签 blob 8392d18 等于目录 blob；5 条终点可追溯到 IC6–IC10 的 agent_verify；按当时的黑名单命中 0。Codex 环境起不了 Bash，改用语义等价的 PowerShell 执行；它报告的 5 处指南不足和主会话核对时发现的 2 处（字节数量法与平台有关；确认卡终点被改写成「均符合预期」，与 /goal 文本写法不一致）已修进指南。按新黑名单，该卡第 1 条终点会命中「符合预期」，这正是本次的发现。
- acceptance: "agent_verify: [CLI] git log -1 --grep='IC4' --format=%B → 含 项目、分支/worktree、HEAD、纳入卡、终点、终验待办、停止找人、没验什么、作废 9 字段与 Compiled-By: <非 Claude 客户端>；标签 blob 等于该提交中 .blueprint/catalog.md 的短 blob；每条终点可在来源卡 agent_verify 原文找到；过程词黑名单 grep → 0。"

### 📋 IC5 — 首次真实 /goal：为 Phase 4 的卡编译 → 人粘贴 → 收口回执
- status: todo
- complexity: S
- files: 收口提交 body 与 PR body；纳入卡的 intent 与终验行
- depends: IC4, P8 收口
- acceptance: "agent_verify: [CLI] git log --grep='^Goal-Receipt: INT-' --format=%B → ≥1 条，含 Goal-Cards、Goal-Result、Goal-Rounds、Goal-Interventions、Not-Verified、Human-Pending；纳入卡标题前缀均为 ✅；含 human_verify 的纳入卡各有一行终验；^### 计数增量等于新增卡数。human_verify: 人粘贴 /goal 并判定 Goal-Result。"

### 📋 IC6 — intent-gate.cjs 核心：结构、防膨胀、类型指针、卡侧引用，加 --self-test
- status: todo
- complexity: M
- intent: INT-02@1.0
- files: .claude/hooks/intent-gate.cjs
- depends: IC3, P8 收口
- acceptance: "agent_verify: [gate 脚本] node .claude/hooks/intent-gate.cjs --self-test → exit 0 且输出 self-test ok，内置 6 类坏样例（悬空 path:、未知 INT、超长字段、status: 键、card: 指向不存在的卡、探索章缺预算或收敛信号）各恰好 1 条警告；node .claude/hooks/intent-gate.cjs → exit 0、真实目录 0 警告；INTENT_CATALOG=/nonexistent → 无输出、exit 0。"

### 📋 IC7 — 门控只读视图 --report/--impact/--pending 与目录提交审计
- status: todo
- complexity: M
- intent: INT-02@1.0
- files: .claude/hooks/intent-gate.cjs
- depends: IC6
- acceptance: "agent_verify: [gate 脚本] --self-test 夹具：章 rev 1.1 而 📋 卡钉 1.0 → --impact 报 stale；钉墓碑章 → orphan；只有模块默认挂靠 → low_confidence；前缀 🔵 而 status: todo → --report 报 divergence 并标 status_source；含 human_verify 而无终验行的 ✅ 卡 → --pending 列出；缺 Feature-Confirmed 的目录提交 → --report 审计列出；全部 exit 0，运行前后 sha256sum .blueprint/catalog.md .blueprint/modules/*.md 不变。"

### 📋 IC8 — 接线：lefthook 加 intent-gate、AGENTS.md 块外加 T5 与启动读书签、agent-button-system 单处改名
- status: todo
- complexity: S
- intent: INT-02@1.0
- files: lefthook.yml, AGENTS.md, docs/ai-context/agent-button-system.md, docs/ai-context/intent-catalog-guide.md, .blueprint/modules/intent-catalog.md
- depends: IC6, P8 收口
- acceptance: "agent_verify: [YAML 解析] lefthook.yml 可解析且 pre-commit.commands.intent-gate.run 以 || true 结尾；[cargo test] cargo test onboarding → 0 failed；[CLI] git diff -U0 AGENTS.md 全部 hunk 位于 BLUEPRINT_MANAGED_START 行之前；grep -c '意图层 — AGENTS.md' docs/ai-context/agent-button-system.md → 0；临时 worktree 内提交一次「改章文不升 rev」→ pre-commit 输出 1 条警告且提交成功，验证后移除该 worktree。"

### 📋 IC9 — cargo test 锁定 parse_module_md 忽略 intent 与终验行
- status: todo
- complexity: S
- intent: INT-02@1.0
- files: src-tauri/src/commands/blueprint.rs
- depends: P8 收口
- acceptance: "agent_verify: [cargo test] cargo test parse_module_md_ignores_intent_lines → 1 passed：含 intent、终验行与模块头 intent 的样本，和删去这些行的样本相比，tasks.len()、status、acceptance、notes 逐字段相等（只改 #[cfg(test)]）；全量 cargo test 无 FAILED。"

### 📋 IC10 — 书签交接：目录书签自持三行，coordination §0 改为指向书签
- status: todo
- complexity: S
- intent: INT-02@1.0
- files: .blueprint/catalog.md, docs/tasks/2026-10-03-coordination.md
- depends: IC7, IC8
- acceptance: "agent_verify: [gate 脚本] node .claude/hooks/intent-gate.cjs → 0 警告；[CLI] grep -A3 '^## 书签' .blueprint/catalog.md → 当前、终点、确认 三行且当前章存在未撤销；coordination §0（若仍存在）含指向书签的一行；提案附 --report 与 base blob；提交带 Feature-Confirmed: true。human_verify: 用户确认书签切换。"

### 📋 IC11 — 「goal 级确认代替逐卡确认」立法提案定稿
- status: todo
- complexity: S
- files: .blueprint/modules/intent-catalog.md
- depends: IC5, P8 收口
- acceptance: "agent_verify: [读文件] 决策记录新增提案：条文、例外清单（运行中 DB、删除、human_verify、凭据与机器状态、超出纳入卡或本章、改目录、stale pin、失败 3 次）与数据（P8 期间逐卡确认次数及可合并次数、IC5 的 Goal-Result）；git diff --name-only 不含 AGENTS.md 与 src-tauri/resources/。human_verify: 用户裁决采纳或否决并记录理由。"

### 📋 IC12 — enterprise 隔离 worktree 试点：catalog 加门控试点副本，规格只用 spec: 指向
- status: todo
- complexity: M
- files: E:/code-project/enterprise-system/.blueprint/catalog.md, E:/code-project/enterprise-system/.claude/hooks/intent-gate.cjs
- depends: IC9, IC10
- acceptance: "agent_verify: [gate 脚本] 试点 worktree 内 → exit 0、0 警告、spec: 指针全部可解析；副本首行含「试点副本，IC13 后替换或删除」；[CLI] 试点 worktree git status --porcelain → 只新增这 2 个文件；enterprise 主工作区 git status --porcelain 前后一致；试点分支 ≥1 条 Goal-Receipt。human_verify: 人确认一次 enterprise goal 的意图与页面结果并记 Goal-Result。"

### 📋 IC13 — 去留决策：按五项度量并入能力包或撤销
- status: todo
- complexity: S
- files: .blueprint/modules/intent-catalog.md
- depends: IC12
- acceptance: "agent_verify: [读文件] 决策记录含五项度量的前后对比，样本 ≥5 条 Goal-Receipt；撤销分支：git grep -lE 'intent-gate|catalog_version' → 只命中决策记录，AGENTS.md 无 T5，lefthook.yml 无 intent-gate 键；保留分支：另拆 blueprint-baseline 分发卡，本卡不改模板。human_verify: 用户裁决去留。"

## 决策记录

- 2026-10-04 归属：新建本模块，并入 handoff 试点的「信息归属 + 任务简报」部分；不做 blueprint-governance 的新迭代。理由：目录层叠在蓝图之上，需要独立的家；governance 已 done，开新迭代会改变全局 iteration 口径；独立模块也便于按退出条款整体撤销。
- 2026-10-04 时机：与 P8 并行做设计，只写文档、在独立 worktree 中进行；实现等 P8 收口后再做。理由：改动的文件与 P8 不重叠，设计也需要时间，等 P8 收口正好衔接。
- 2026-10-04 试点范围：先在炼境自身试用。理由：先在自己身上踩坑成本最低；enterprise 主工作区有他人的在制品，分发机制也尚未安全化。
- 2026-10-04 立法：「goal 级确认代替逐卡确认」只在设计中起草提案，P8 之后再定。理由：先用 P8 的实测数据说话；这条规则依赖「章」的定义；现在改托管块会和 P8 撞车。
- 2026-10-04 设计确认（IC1）：采用最小文件优先方案，即 `.blueprint/catalog.md`、卡侧 `- intent:` 钉版和模型无关的 goal 编译指南；不选结构化 YAML 加 Rust/MCP（子项目离线时拿不到同等校验，撤销成本也最高），也不选最大化复用（会提前分发给所有子项目，还要改动 CONVENTIONS 的分类轴）。评审团 wf_60e4c430-bb1 两位评委打分为 25/30、24/30。设计中的五个待拍板问题，用户全部采纳推荐项：
  - 门控脚本放在 P8 收口后，试用期只新增文档；
  - IC5 首次真实 /goal 用于 P8 收口后本模块 Phase 4 的卡，不打断 P8 在制品；
  - 炼境 1.0 首批章节方向为「一键接入三端可用 / 意图编译为可判定终点 / 摩擦驱动沉淀与退出」，在 IC3 逐章定稿；
  - 去留阈值初定为样本 ≥5、一次判对率 ≥60%、人工介入不高于基线、每阶段改目录 ≤1 次，IC13 前可以调整；
  - 接受在 AGENTS.md 块外常驻约 10 行「启动读目录引言和书签」。
- 2026-10-04 修订（用户提出，采纳推荐）：增加探索章，让意图可以从迭代中结晶。起因是很多需求一开始只有模糊轮廓，甚至没有意图，要靠 MVP 反复试用才慢慢说清。原设计默认自上而下，是盲区。具体做法：
  - 章新增可选字段「形态: 定型（缺省）|探索」。它是人对意图清晰度的声明，不是任务进度，因此不违反「目录不存状态」，并且只能由人确认修改。
  - 探索章必填 轮廓、试探、不做、预算、收敛信号。
  - 探索期的 goal 只编译本轮试验的终点；人的试用反馈记成终验行（保留/否决 + 理由），作为结晶原料。
  - 收敛或预算用完时，agent 起草意图提炼，人确认后转为定型（小版本）。未收敛时由人三选一：追加预算、换方向、撤销留墓碑；agent 不得自行延长预算。
  - 修修补补和直接做 MVP 不必开章，目录与卡侧 intent 一律可选。
  - 同步：INT-02 措辞覆盖定型和探索两种形态；指南新增「探索章与结晶」一节和离线检查第 11 条；IC6 坏样例增至 6 类；W8 有了实质承重件；度量增加探索章三项。