diff --git a/.blueprint/modules/intent-catalog.md b/.blueprint/modules/intent-catalog.md index c8368bb..7f3ba7e 100644 --- a/.blueprint/modules/intent-catalog.md +++ b/.blueprint/modules/intent-catalog.md @@ -92,9 +92,12 @@ agent 开发子项目时躲不掉的现象。每面墙都要回答四个问题 ## 任务卡 -### 💭 IC1 — 意图目录设计文档(/architect) -- status: concept -- notes: 产出 `docs/tasks/<日期>-intent-catalog-design.md`,以 W1–W14 为纲、书模型为体,逐条化解上面的待设计问题,写明收益度量与退出条件;完成后交用户确认,确认后模块转 planned,再用 /splitter 拆成 S/M 卡。 +### 🔵 IC1 — 意图目录设计文档(/architect) +- status: in_progress +- 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 卡。 ## 决策记录 diff --git a/docs/tasks/2026-10-04-intent-catalog-design.md b/docs/tasks/2026-10-04-intent-catalog-design.md new file mode 100644 index 0000000..e0b1798 --- /dev/null +++ b/docs/tasks/2026-10-04-intent-catalog-design.md @@ -0,0 +1,352 @@ +# 设计决策:意图目录(intent-catalog)· IC1 + +> status: 待用户确认 | complexity: L(本文只到设计,实现拆为 IC2–IC13)| created: 2026-10-04 | blueprint: intent-catalog +> ⚠️ 处置条款:用户确认后,稳定结论回写 `.blueprint/modules/intent-catalog.md`(决策记录与任务卡),本文件在 IC3 完成后 24h 内删除,不做第二事实来源。 +> 产出方式:/architect 评审团工作流 wf_60e4c430-bb1。3 个独立方案(最小文件优先、结构化优先、最大化复用)交 2 位评委(agent 友好度与成本、治理与风险)打分,由综合者定稿;关键代码事实已由主会话复核。 + +## 背景 + +- 需求本体见 `.blueprint/modules/intent-catalog.md`,包括两层模型、W1–W14 承重墙、13 个待设计问题和「不做什么」。 +- 并入 `docs/tasks/2026-09-23-blueprint-agent-handoff-pilot.md` 的「信息归属与同步契约」与「最小任务简报的按需读取与回执」。 +- 关联模块: + - blueprint-governance:前置,负责安全派发与状态语义收敛。 + - agent-client-capability-packs:版本化 pack 机制。 + - governance-feedback-loop:修订历史与否决理由的回流。 + - agent-client-parity:P8 在制品,期间不碰其热点文件。 + +## 方案选择 + +| 方案 | 优点 | 缺点 | 结论 | +|---|---|---|---| +| **最小文件优先**:Markdown 目录 + 卡上 intent 行 + 只警告的 node 门控 + 模型无关的编译指南 | 试用只新增文件,撤销最便宜;离线、跨 agent、零依赖;不进 DB、不加 MCP | 原稿把门控放在试用期、在文件内记修订历史、双向存归属、简报缺定位信息 | ✅ 选为主体,按评委 must_fix 修正 | +| 结构化优先:schema 化 YAML + Rust 解析/lint + 只读 MCP | 可断言程度最高;类型化指针与影响分析严谨 | 权威校验在炼境 crate 内,子项目离线拿不到;YAML 写错会让 cargo test 变红;人维护负担重;撤销成本最高 | 不选;嫁接类型化指针、stale/orphan 分类、base 不符即重提、数据门控 | +| 最大化复用:放进既有载体 + 正文上行挂靠 + 并入托管 blueprint-gate | 单一事实源守得最严;简报、blob、回执复用既有载体 | Phase 4 就把检查分发给所有子项目,早于试点与去留决策;改 CONVENTIONS 的「意图层」会破坏分类轴并整文件广播 | 不选;嫁接简报/blob/回执、单向挂靠、章 rev、待裁决视图 | + +评分:agent 友好度视角为最小 25/30、复用 25/30、结构化 19/30;治理与风险视角为最小 24/30、复用 21/30、结构化 18/30。两位评委都判最小方案无致命缺陷。 + +**选定**:以最小方案为主体,嫁接以下几点: +- 归属只从卡侧单向挂靠; +- 每章带 rev,修订审计交给 git; +- 目标确认卡兼作 handoff 的最小任务简报,包含 project_id、分支/worktree,并以 catalog blob 作 digest; +- 回执写进收口提交的 body; +- 人工终验独立成 `- 终验:` 行; +- 指针带类型前缀; +- 影响分析分 stale 与 orphan 两类; +- 代码化工作设数据门控。 + +试用期只新增两份文档、不写代码,门控脚本挪到 P8 收口后。 + +## 设计规格 + +### 1. 目录文件 + +- **位置**:`.blueprint/catalog.md`。它在 modules/ 之外,已核实以下机制都不会碰到它: + - `archive_project_docs` 只归档 modules/*.md; + - blueprint-gate 只扫描 modules/; + - `get_blueprint` 只按 manifest 读模块; + - `sync_blueprint_rules` 只整文件写 CONVENTIONS.md。 +- **格式**:纯 Markdown 小语法,依次为引言行、`## 书签`、`## INT-NN 章名`(可有多章)、撤销墓碑、`## 附录`。 +- **章导语字段**:必填 `rev`、`意图`、`人看`、`机器`、`不做`;可选 `风险`、`假设`、`证据`、`墙`。 +- **防膨胀**: + - 每字段单行,不超过 120 字; + - 每个章块不超过 12 行; + - 全文件不超过 200 行、8KB; + - 禁止 `status`、`progress`、`doc`、`files`、`acceptance`、`model` 键; + - 不设文件内修订历史。 +- **语法的单一来源**:`docs/ai-context/intent-catalog-guide.md`(IC2)。 + +示例(章名与内容仅作示意,1.0 由人在 IC3 定稿): + +```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:agent-client-parity#P8e +- 不做: 不替 agent 选模型;不让子项目依赖炼境在线 +- 墙: W12,W13 + +## INT-09(已撤销) +- 撤销: YYYY-MM-DD → module:intent-catalog#决策记录 + +## 附录 +- 承重墙 → path:.blueprint/modules/intent-catalog.md#承重墙 +- 决策与否决 → 各模块「决策记录」;终验否决理由 → 卡上 `- 终验:` 行 +``` + +### 2. 挂靠与指针 + +- **单向挂靠**: + - 卡上可选写一行 `- intent: INT-NN@X.Y`,紧跟在 complexity 后面。 + - 模块头的 blockquote 可选写 `| intent: INT-NN` 作为默认挂靠,不带版本,影响分析里计为低置信。 + - 章的「机器:」只是验收坐标指针,不登记成员;反向索引由门控现算,不存储。 +- **类型化指针**: + - `path:<路径>[#标题前缀]` + - `module:` + - `card:#<卡键>` + - `spec:<路径>#标题` + - `cmd:<命令>`:只校验格式,不执行 + - `W` + + 多个指针用「;」分隔。卡键取标题去掉状态前缀后的第一个 token,例如 `IC6`、`P8e`。 +- **解析器行为**(主会话已复核 `blueprint.rs:335-420` 与 `buff.rs:495-505`): + - `parse_module_md` 只认 status、complexity、files、depends、acceptance、notes、blocked_reason 这几个键,`- intent:` 与 `- 终验:` 不进任何字段。 + - `- status:` 行会覆盖标题前缀。 + - 多条 `- notes:` 时后一条覆盖前一条,所以终验另起 `- 终验:` 键。 + - 未识别的 `##` 段(Section::None)下出现的 `###` 会被当成任务卡,所以**模块 md 里任务卡段以外一律不许用 `###`**。 + - buff 自动标 🔵 只替换标题前缀和 `status: todo` 行,不碰 `intent`/`终验` 行。 + +### 3. 修订、钉版与影响分析 + +- **版本号**:引言里只写一个 `catalog_version: X.Y`;每章另有 `rev`,即该章最后一次变更时的版本。与 manifest.iteration 互不借号。 +- **三级修订**: + +| 级别 | 触发 | 谁改 | 版本变化 | +|---|---|---|---| +| 补丁 | 只改正文,目录不动 | agent 自主 | 无 | +| 小版本 | 改章导语的坐标,或由正文反推修改目录 | agent 出 S 级三行确认卡,附 diff 和 base blob(`git rev-parse --short HEAD:.blueprint/catalog.md`),人确认 | Y+1,被改章的 rev 设为新版本 | +| 大版本 | 增删章节、调整方向 | 人主导 | X+1、Y 归零;涉及的章更新 rev;删掉的章留墓碑;按 T4 检查 AGENTS.md「项目定位」 | + +- **审计交给 git**:目录提交写成 `docs(intent): …`,body 写一句理由,并带 `Feature-Confirmed: true`。提交前如果 HEAD 里的 blob 已不等于提案的 base,就重新提案,沿用 W9 的 plan→digest→apply 语义。 +- **钉版**:卡钉 `INT-NN@X.Y`;goal 标签写 `INT-NN@X.Y#blob7`。 +- **影响分析**: + - stale:钉的版本低于章 rev,且卡未完成。 + - orphan:钉在墓碑章上。 + - low_confidence:只有模块默认挂靠。 +- **在制品保护**: + - 钉旧版的 🔵 卡照常做完,只复核 acceptance。 + - 章被撤销,或新的「不做」覆盖了该卡时,停下来找人。 + - 不自动改写卡。agent 复核 acceptance 无变化后改钉,算补丁,在简报里报告。 + +### 4. goal 编译与目标确认卡(兼最小任务简报) + +**编译七步**:模型无关,只依赖读文件,node 门控可选;/architect 只是引用指南的 Claude 包装。 + +1. **定位**:从 `.lian-jing/context.json` 取 project_id,记下当前分支、worktree、HEAD;要求 `git status --porcelain -- .blueprint/catalog.md` 为空,取 catalog blob。 +2. **读书签**:定位当前章(P8 期间按 coordination §0 的终点),读该章导语和 rev。 +3. **校验**:P8 收口后跑 `intent-gate.cjs --report INT-NN --impact`,在此之前用指南里的 shell 等价检查。遇到悬空指针、stale/orphan 或防膨胀警告,先修或先提案,不往下编译。 +4. **收卡**:取挂在本章、状态为 📋/🔵 的卡。没有可执行 agent_verify 的,列入「须先补 acceptance」,不进 goal。 +5. **合成终点**: + - 取各卡 agent_verify 的合取,改写成会话里可判定的形式:贴出命令和预期输出、纳入卡前缀均为 ✅、回执块已写入。 + - 过程词黑名单(按方针、符合设计、设计已完成、基本完成)命中数必须为 0。 + - human_verify 不进终点,单列为终验待办。 +6. **写明停止找人的条件**:human_verify、写运行中 DB、删除、凭据或机器状态变更、超出纳入卡或本章、需改目录、stale pin、失败 3 次。 +7. **输出确认卡和 /goal 文本**:人读完亲手粘贴即为确认。要改就重新编译,agent 不得自行启动或静默改动。 + +**目标确认卡模板**(/goal 文本首行带同样的标签): + +```text +[INT-02@1.0#a1b2c3d] 目标确认卡 +项目: | 分支/worktree: @ | HEAD: +章意图: <一句> | 不做: <…> +纳入卡: IC6(来源 agent_verify 原文)、IC7(…) +终点(合取): 1) <命令> → <预期输出> 2) … 3) 纳入卡均 ✅ 且已写 Goal-Receipt +终验待办: +停止找人: <第 6 步清单> +能力入口: pnpm typecheck / cargo test / +没验什么: <…> +作废: 分支变化或 catalog blob ≠ a1b2c3d +``` + +**回执**:goal 收口时写进收口提交的 body,M 级同时复制到 PR body;炼境在线时可再调 append_project_note。格式为以下几行 trailer: + +- `Goal-Receipt: <标签>` +- `Goal-Cards:` +- `Goal-Result: 判对|误判|中止(原因)` +- `Goal-Rounds:` +- `Goal-Interventions:` +- `Goal-Tokens: <客户端可得时填,否则 n/a>` +- `Not-Verified:` +- `Human-Pending:` + +不写进模块决策记录,那会被 UI 当成决策展示;也不手改 `notes-archive.jsonl`,它以 DB 为事实源、会被整文件重写。 + +### 5. 书签 + +- **载体**:catalog.md 的 `## 书签` 段。 +- **P8 期间**:只写一行指针,指向 coordination §0,终点仍以 §0 为唯一事实源。 +- **P8 收口后(IC10)**:改为自持三行:`- 当前: INT-NN`、`- 终点 → card:#<卡键>`、`- 确认: YYYY-MM-DD`。同一次提交把 coordination §0 改成指向书签(若文件已按处置条款删除则跳过),此后统筹文档只管派单与交接。 +- **切换书签**:不升版本,但走与小版本相同的流程:附 `--report` 证据和 base blob,人确认,提交带 Feature-Confirmed。书签指针悬空时门控报警,这本身就是交接信号。 + +### 6. 机器校验 + +- **Phase 3(只新增文档,不写代码)**:检查全靠卡 acceptance 里的 shell 单行命令: + - grep 统计章数和禁用键; + - wc 检查体量; + - `grep -oE 'path:[^ #;]+' | xargs test -e` 校验路径指针; + - 新增前后用 `grep -c '^### '` 计数比对,作为 get_project_blueprint 的离线替代。 +- **Phase 4(P8 收口后)**:新增零依赖的 `.claude/hooks/intent-gate.cjs`,恒 exit 0、只警告,`INTENT_CATALOG` 环境变量可以指向夹具,没有目录文件时静默。检查分六类: + 1. 结构:版本行存在、INT 唯一、墓碑不被复用、rev 不大于 catalog_version。 + 2. 防膨胀:字段白名单、单行与体量上限、禁用键与模型名。 + 3. 类型指针可解析。 + 4. 卡侧:intent 指向的章存在且未撤销,钉的版本不高于当前版本。 + 5. 版本纪律:只读 `git diff --cached`,章文改了而 rev 或版本没升就警告。 + 6. 只读视图: + - `--report`:按解析器语义推导章的四态,标注 status_source;汇总 Goal-Receipt;审计缺 Feature-Confirmed 的目录提交。 + - `--impact`:输出 stale/orphan/low_confidence。 + - `--pending`:列出有 human_verify 但没有 `- 终验:` 行的卡,以及未提交的目录改动。 + - `--self-test`:用内置坏样例自检。 +- **接线**:lefthook pre-commit 以 `|| true` 接入;不进 CI 阻断,也不并入托管的 blueprint-gate。另加一条 cargo test,锁定解析器忽略 intent 与终验行。 +- **数据门控**:Rust 解析、MCP 查询这类代码化工作,要同时满足钉版卡不少于 5 张、至少发生过 1 次小版本修订、enterprise 试点完成、且 IC13 决定保留之后才考虑。 + +### 7. 术语映射 + +- **方针层(前言)**:AGENTS.md「项目定位」。 +- **目录层**:`.blueprint/catalog.md`,包括章、导语、附录、书签;索引就是 INT-NN。 +- **正文层**:manifest、modules/*.md 和任务卡。 +- **不改的词**:CONVENTIONS 里的「蓝图定位(意图层)」与「架构意图层」保留,解释为「.blueprint 全体(目录 + 正文)相对 git 事实层」。这样不触碰整文件分发的规则,也不破坏分类轴。 +- **唯一改名点**:`docs/ai-context/agent-button-system.md:51` 的「意图层 — AGENTS.md」改为「方针层 — AGENTS.md」。该文件不在 resources/onboarding 内,已核实;在 Phase 4 由 IC8 执行。之后新文档不再单独使用「意图层」一词。 + +## 13 个待设计问题的化解 + +| # | 问题 | 化解 | +|---|---|---| +| 1 | 「意图层」三处归属 | 定死方针层、目录层、正文层三层;CONVENTIONS 的「意图层」保留并重新解释;全仓只改 agent-button-system.md:51 一处,由 IC8 执行。否决改 CONVENTIONS 的做法,因为它会破坏分类轴并触发整文件广播 | +| 2 | 红线:章完成不能手动切换 | 目录不设任何状态字段;章的四态(未开始、进行中、待人终验、已达成)只由 `--report` 从卡状态和 `- 终验:` 行临时推导,不落盘、不提供入口。书签切换属于方向决策,不算改状态 | +| 3 | 状态语义未收敛 | 推导按解析器语义来:先看前缀,有 status 行则以它为准,并标注 status_source;前缀与 status 行不一致时警告。正式收敛交给 blueprint-governance 前置,收敛前推导结果标为「参考」;stale/orphan 不依赖状态语义 | +| 4 | 四套分类轴的对应 | 补丁对应 Bug 和章内 S/M Feature,T1–T4 照旧;小版本对应改变章坐标的 Feature(S 级确认卡),触发 T5-minor;大版本对应 L 级或方向调整,触发 T5-major,并按 T4 检查项目定位。manifest.iteration 只计模块重构。T5 先写进炼境 AGENTS.md 托管块外,登记为有意的临时分叉,在 IC13 回收 | +| 5 | ID 前缀 | 章用 INT-NN,永不复用,撤销留墓碑;W1–W14 只出现在模块和设计文档里;卡从 IC2 起编号;钉版写 `INT-NN@X.Y`,goal 标签写 `INT-NN@X.Y#blob7`。2026-10-04 已用 git grep 确认这些前缀都没被占用 | +| 6 | goal 级确认代替逐卡确认 | 只起草,见下文「立法提案草案」。P8 期间只记账,P8 收口后由 IC11 带着数据交给用户裁决 | +| 7 | W11 资源:只记账不分配 | 由 Goal-Receipt 记录轮数、介入次数,token 可得时一并记录,`--report` 按章汇总;目录与 goal 文本都禁止出现模型名。CONVENTIONS 复杂度表映射到模型名的矛盾,交给前置收敛 | +| 8 | 防止容器化 | 只放 ID、一句话意图和类型化指针,加上白名单、体量上限、禁用键,不设文件内修订历史;goal 编译第 3 步把警告当作阻塞 | +| 9 | 书签与 coordination §0 | P8 期间书签只是一行指针;之后由 IC10 改为自持,agent 起草、人确认,同一次提交把 §0 改成指向书签 | +| 10 | 离线与降级 | 目录、指南、门控、回执都在项目 Git 里,离线可读可跑;不新增 MCP 工具,在线时用现有的 get_project_file 读同一份文件;跨项目索引受数据门控约束 | +| 11 | 跨 agent | 编译流程写进 intent-catalog-guide.md,作为唯一来源,/architect 只引用不复述;IC4 由 Codex 或 DSH 纸面试跑验证。保留后经 blueprint-baseline 包或安全派发并入 CONVENTIONS,不走整文件广播 | +| 12 | 子项目已有意图载体 | 用 `spec:.specify/specs//spec.md#标题` 指向;单行和体量上限从物理上防止抄录;在 IC12 验证 | +| 13 | 物理位置与前言 | 放在 `.blueprint/catalog.md`:属于启动就读的蓝图目录,又在 modules/ 之外。前言只写一个指针 `path:AGENTS.md#项目定位`。不放 AGENTS.md,避免常驻成本和托管块覆盖;不新开 docs/intent/,因为它不在启动读取路径上 | + +## 承重墙四问 + +| 墙 | 落点 | 机制 | 机器检查 | 何时拆除 | +|---|---|---|---|---| +| W1 迭代 | 引言版本 + 各章 rev;卡和 goal 上的钉版 | 三级修订;钉版;审计交给 git;与 iteration 分开 | `--impact` 报 stale/orphan;章文改了而 rev 未升时警告 | IC13 时钉版卡少于 5 张,或从未触发复核,就撤销钉版,只留章 ID | +| W2 遗忘 | 书签 + 确认卡(兼简报) | 启动只读引言和书签约 10 行;用简报代替通读蓝图 | 书签所指章存在;确认卡 blob 等于 HEAD | 续接所需上下文没有下降,或被原生记忆覆盖 | +| W3 熵增 | 目录全文件 | 白名单、体量上限、只写指针、禁用键 | Phase 3 用 grep/wc;Phase 4 用门控;编译前把警告当阻塞 | 随目录整体撤销;阈值在 IC13 前按实测调整 | +| W4 意图鸿沟 | 章导语四个字段 + 卡侧 intent | 卡挂回章;确认卡写清「不做」与停止条件 | 卡引用的章存在;编译输出「须先补 acceptance」 | human_verify 否决率和方向返工没有下降 | +| W5 注意力稀缺 | 书签 + `--pending` | 人只确认书签、大小版本和 goal 确认卡 | `--pending` 列出待终验卡和未提交的目录改动 | 原生视图已能覆盖跨章待裁决 | +| W6 理解债 | 卡侧 intent + 章的机器指针 | 由门控现算「服务哪条意图」,不存储 | `--report INT-NN` 列出挂靠卡及来源 | 试用期内反查从未被用过 | +| W7 自评偏差 | 双坐标;回执的 Not-Verified | 章完成只能推导;终验结论由人给出 | 禁止 status 键;标注 status_source;回执 trailer 齐全 | 不拆,这是红线 | +| W8 不确定性 | 可选的「假设:」字段 | 只指向已有的证伪落点 | 指针可解析 | 试点中从未用过,就从白名单删除 | +| W9 并发冲突 | 目录文件 | 提案带 base blob,不符就重提;目录改动单独小提交 | 编译第 1 步要求目录无未提交改动 | 保留,成本极低 | +| W10 风险不对称 | 大小版本、书签;可选的「风险:」字段 | 提案、diff、blob 交人确认;停止清单是必填项 | 审计目录提交的 trailer | 不拆;立法若采纳则并入需求对齐协议 | +| W11 资源有限 | Goal-Receipt trailer | 只记账:轮数、介入次数、耗时、可得时的 token | 从 git log 按章汇总;禁止出现模型名 | 没有任何客户端提供用量,且轮数数据无助于决策 | +| W12 环境漂移 | 附录指针 | 用 cmd: 指针指向现有工具,不新建机制 | 只校验格式 | 无需拆,本身没有新增机制 | +| W13 异构 agent | intent-catalog-guide.md | 只依赖读文件;/architect 只是包装 | IC4 纸面编译;IC12 实跑 | 各客户端出现原生的同等能力 | +| W14 摩擦重复 | 回执、`- 终验:` 否决理由、envoy | 复用提交 body、append_project_note、report_envoy_return | 用 git log 统计 | 随目录整体撤销 | + +## 受影响文件 + +| 阶段 | 文件 | 改动 | 用途 | +|---|---|---|---| +| 2 设计(本文,与 P8 并行) | docs/tasks/2026-10-04-intent-catalog-design.md | 新增 | 本设计 | +| 2 设计 | .blueprint/modules/intent-catalog.md | 修改 | 改 IC1 前缀、补决策记录、追加 IC2–IC13 卡(任务卡段以外不用 `###`) | +| 2 设计 | .blueprint/manifest.yaml | 修改 | 用户确认后只改本模块的 status 一行:concept → planned | +| 3 炼境自身试用(只新增文件) | docs/ai-context/intent-catalog-guide.md | 新增 | 目录语法、修订钉版、编译七步、确认卡与回执模板、离线检查 | +| 3 | .blueprint/catalog.md | 新增 | 1.0 骨架与首批 2–4 章;书签只写一行指针 | +| 4 P8 收口后 | .claude/hooks/intent-gate.cjs | 新增 | 只警告的门控和各个只读视图 | +| 4 | src-tauri/src/commands/blueprint.rs | 修改 | 只改 `#[cfg(test)]`:锁定解析器忽略 intent 与终验行 | +| 4 | lefthook.yml | 修改 | pre-commit 加 intent-gate(带 `\|\| true`);接入包对 lefthook 是「存在即跳过」(已核实 onboarding.rs:6),不会被覆盖 | +| 4 | AGENTS.md | 修改 | 只改托管块外:T1–T4 区加 T5;块外约定加「启动读目录引言和书签」一行 | +| 4 | docs/ai-context/agent-button-system.md | 修改 | 唯一改名点:第 51 行 | +| 4 | .blueprint/catalog.md、docs/tasks/2026-10-03-coordination.md | 修改 | IC10 书签交接;§0 改为指向书签 | +| 5 enterprise 试点 | enterprise 隔离 worktree 里的 .blueprint/catalog.md 和 intent-gate.cjs 试点副本 | 新增 | 规格只用 spec: 指向;副本首行标注到期 | +| 6 去留(保留时) | onboarding 模板(经 blueprint-baseline 包)、AGENTS.md.tmpl、agents-meta-rules.md、CONVENTIONS.md | 新增/修改 | 只在 IC13 决定保留后分发,配套升版本和指纹,回收 T5 临时分叉 | +| 6 去留(撤销时) | 见撤销清单 | 删除 | 删除 3 个文件、lefthook 键、T5 和启动读书签那一行;回退 §0;删除 enterprise 副本 | + +## 系统边界变更 + +- **Phase 2**:无变化,只写文档。 +- **Phase 3**: + - 新增项目级文件格式 `.blueprint/catalog.md`。 + - 任务卡新增两个可选、解析器不读的键:`- intent:` 和 `- 终验:`,与 iteration:/replaces: 同属此类。 + - 提交新增 `Goal-Receipt:` 等 trailer 约定。 + - 不新增 Tauri command、MCP 工具、DB 表或结构体字段。 +- **Phase 4**:新增本地 CLI `node .claude/hooks/intent-gate.cjs [--self-test|--report|--impact|--pending]`、lefthook 键和 AGENTS.md 块外的 T5;仍不涉及 command、MCP 或 DB。 +- **Phase 6**:只有决定保留并过了数据门控,才可能新增 `BlueprintTask.intent` 字段或只读 MCP 工具,届时按 T1 契约变更另行设计。 + +## 风险点 + +| 风险 | 规避 | +|---|---| +| 目录膨胀成容器,或变成第二事实源 | 白名单、体量上限、只写指针、单向挂靠;编译前把警告当阻塞 | +| 只警告的门控被习惯性忽略 | 保持零警告基线、警告类别少而准;编译前要求本章零警告;是否升级为阻断由 IC13 依数据决定 | +| 会重写卡文件的工具丢掉 intent 或终验行 | 已复核解析器和 buff;其他写入路径未核实,由 IC9 锁定,并比对 IC5 前后的卡数 | +| /goal 评估器仍然过早判定达成 | 终点只写「命令 + 输出」的合取;过程词黑名单;Goal-Result 统计一次判对率 | +| 状态语义未收敛导致推导失真 | 标注 status_source、不一致时警告;推导结果标为参考、不落盘 | +| 把回执写进 notes-archive.jsonl 会被冲掉 | 主载体是提交 body;在线时只经 append_project_note 双写 | +| 归档 modules 后 card: 指针集体悬空 | 门控报出悬空后按小版本修订;归档本身就是触发信号 | +| 模块 md 的非任务卡段里用了 `###`,被当成卡 | 指南明令禁止;acceptance 比对 `^### ` 计数 | +| T5 和 enterprise 门控副本与模板分叉 | 登记为有意的临时分叉,在 IC13 统一回收 | +| 其他 agent 沙箱里没有 node,或 lefthook 静默失效 | 门控只是辅助,保留 shell 加人工读文件的降级路径 | +| 维护成本超过收益 | 由 IC13 依数据决定;撤销只需删 3 个文件和若干行 | + +## 拆解建议 + +建议拆为 12 张卡,依赖顺序: + +- IC2 → IC3 → IC4 → IC5(Phase 3,P8 期间可做,只新增文件) +- P8 收口 → IC6 → IC7;IC6 → IC8;IC9 不依赖其他卡;IC7 + IC8 → IC10;IC5 → IC11(以上为 Phase 4) +- IC9 + IC10 → IC12 → IC13(Phase 5、6) + +| 卡 | 标题 | 复杂度 | 阶段 | acceptance 要点 | +|---|---|---|---|---| +| IC2 | 新增 intent-catalog-guide.md | S | 3 | [CLI] 5 个必备节标题都在;模型名 grep 为 0;git status 只有该文件新增 | +| IC3 | 新增 catalog.md:1.0 骨架与首批 2–4 章 | S | 3 | [CLI] 版本行、章数、体量、禁用键、path 悬空数为 0;`^### ` 计数前后相等。human_verify:用户逐章定稿,提交带 Feature-Confirmed | +| IC4 | 跨 agent 纸面编译(Codex 或 DSH) | S | 3 | [CLI] 提交 body 里确认卡 9 个字段齐全,有 `Compiled-By: <非 Claude>`;blob 一致;终点都能在来源卡里找到;黑名单为 0 | +| IC5 | 首次真实 /goal:编译 → 粘贴 → 回执 | S | 3→4 | [CLI] 至少 1 条完整的 Goal-Receipt;纳入卡均为 ✅;有 human_verify 的卡带 `- 终验:` 行。human_verify:人粘贴并判定 Goal-Result | +| IC6 | intent-gate 核心加 --self-test | M | 4 | [gate] self-test 的 5 类坏样例各命中 1 条警告;真实目录 0 警告;没有目录时静默 exit 0 | +| IC7 | 只读视图 --report/--impact/--pending 与审计 | M | 4 | [gate] 夹具覆盖 stale/orphan/low_confidence/divergence/待终验/缺 trailer 审计;运行前后文件 sha256 不变 | +| IC8 | 接线:lefthook、T5、启动读书签、单处改名 | S | 4 | [YAML] run 以 `\|\| true` 结尾;[cargo test] `cargo test onboarding` 0 failed;AGENTS.md 的 diff 都在托管块之前;改名残留为 0;临时 worktree 里实测会警告 | +| IC9 | cargo test 锁定解析器忽略 intent 与终验行 | S | 4 | [cargo test] `parse_module_md_ignores_intent_lines` 1 passed:带和不带这些行的样本逐字段相等;全量无 FAILED | +| IC10 | 书签交接 | S | 4 | [gate] 0 警告;书签三行齐全;§0 改为指向书签;提交带 Feature-Confirmed。human_verify:用户确认切换 | +| IC11 | 立法提案定稿 | S | 4 | [读文件] 决策记录有条文、例外清单、P8 与 IC5 数据;diff 不含 AGENTS.md 和 resources/。human_verify:用户裁决 | +| IC12 | enterprise 隔离试点 | M | 5 | [gate] 试点 worktree 0 警告、spec: 都可解析;只新增 2 个文件;enterprise 主工作区前后一致;至少 1 条 Goal-Receipt | +| IC13 | 去留决策 | S | 6 | [读文件] 五项度量的前后对比,样本至少 5 条;撤销时 `git grep` 只命中决策记录。human_verify:用户裁决 | + +## 收益度量与退出条件 + +- **度量**:基线取 P8 期间没有目录时的数据,来源是 PR body 和统筹流水。 + - /goal 一次判对率,取自 Goal-Result; + - 每个 goal 的人工介入次数; + - 续接所需的上下文量:读简报的字节数 vs. 读 coordination 加多个模块的字节数; + - human_verify 否决率与方向返工; + - 每阶段的轮数、耗时,token 可得时一并记录。 +- **健康指标**:目录警告数、stale pin 数、目录体量、人每阶段改目录的次数。 +- **去留**(初始阈值,用户可在 IC13 前调整):样本至少 5 个 goal,其中 enterprise 至少 1 个。一次判对率不低于 60%、人工介入不高于基线、人每阶段改目录不超过 1 次,就保留并另拆分发卡;实测无收益、已被 agent 原生能力覆盖,或维护成本超过收益,就按撤销清单整体撤销。 + +## 立法提案草案:「goal 级确认代替逐卡确认」 + +不在 P8 期间生效,P8 收口后由 IC11 用实测数据定稿。 + +1. **范围**:书签所指当前章内,目标确认卡「纳入卡」所列的 S/M 卡。 +2. **确认方式**:人读完确认卡后亲手粘贴 /goal,即视为批量确认清单内各卡的 Feature 确认卡;agent 不得自行启动或改写 goal 文本。 +3. **存证**:清单内卡的 feat: 提交照常带 `Feature-Confirmed: true`,并加 `Goal-Receipt: INT-NN@X.Y#blob`;缺这一行即视为逐卡确认未完成。 +4. **例外**:以下仍须逐项找人:写运行中 DB;删除文件、数据或分支;human_verify;凭据与机器状态变更;超出纳入卡或当前章;修改目录;stale/orphan pin;失败 3 次。 +5. **失效**:分支变化、catalog blob 变化或 goal 中止时,恢复逐卡确认。 +6. **落点**:先在炼境 AGENTS.md 块外试行,采纳后再进 ONBOARDING_MANAGED「需求对齐协议」(升块版本和指纹),并同步 agents-meta-rules。试行期间任何一条例外被越过,就否决本条。 + +## 待用户拍板 + +1. **门控脚本的时机**:默认放在 P8 收口后的 Phase 4,试用期只放两份文档、不写代码。是否特批在试用期以新增文件的形式就写? +2. **IC5 首次真实 /goal 用哪个阶段**:P8 收尾,数据来得最早;还是 P8 收口后的第一个阶段,例如本模块 Phase 4 的卡,自举试用? +3. **炼境 1.0 首批章节方向**:草拟候选为「一键接入三端可用」「意图编译为可判定终点」「摩擦驱动沉淀与退出」。正式定稿在 IC3,由你逐章确认。 +4. **去留阈值**是否认可:样本至少 5 个、一次判对率不低于 60%、人工介入不高于基线、改目录每阶段不超过 1 次? +5. **常驻成本**:Phase 4 在 AGENTS.md 块外加「会话开始读目录引言和书签(约 10 行)」,是否接受? + +## 自验报告:没验什么 + +- **已复核**:archive 只归档 modules/*.md;parse_module_md 的段落与键规则(`blueprint.rs:335-420`);buff 自动标 🔵 的替换范围(`buff.rs:495-505`);lefthook「存在即跳过」(`onboarding.rs:6`);agent-button-system 不在分发模板内;W/IC/INT 前缀未被占用。 +- **未复核,沿用评审团或 handoff 简报的结论**: + - `get_project_file` 在 mcp_tools.rs:38; + - notes-archive.jsonl 由 DB 整文件重写(mcp_tools.rs:87); + - 其他可能重写卡文件的路径; + - CONVENTIONS 状态语义冲突的具体行号。 +- **侦察缺口**:侦察工作流 wf_6dc3756a-b72 中「蓝图全量」和「红线与记忆」两个侦察员卡死失败,相关约束由综合者补读和主会话已知规则补齐,可能有遗漏。 +- **跨 agent**:/goal 能否作为三端通用的粘贴载体,未核实,留给 IC4、IC12 验证。 +- **用量(W11 记账)**:侦察工作流约 178 万 token,其中两个侦察员各重试 6 次卡死,浪费明显;设计评审团约 55 万 token,6 个 agent 全部成功。