26 - 北极星流水线
1. 定位
本文档回答一个此前散落在 26 篇文档之间、从未被单独陈述的问题：
这套体系全部建成之后，理想运转的一天是什么样子？
- doc-00 回答"体系是什么"（架构）；doc-06/25 回答"文档层怎么运转"（结构与演化）；本文档回答"这一切为了什么"（目的态），是全体系的叙事层与验收基准。
- 北极星本身不变（见 CLAUDE.md：提高个人开发者产出质量与效率）。本文档把它翻译成一条可分段验收的流水线：任何一段的改进提案，都应能回答"它推进了流水线的哪一段"。
- 读者：人（校准方向、决定投资顺序）+ AI（进场时理解自己正处于流水线哪一段、边界在哪）。
本文档不是：实施计划（组件落地走 docs/plans/）、文档体系规范（归 doc-06/25）、方法论本体（归上游 ~/Vault/知识库/方案模板/产品文档体系方法论.md）。
2. 北极星陈述
新项目按契约依序生成文档与裁决面 → AI 在契约内完成 100% 的实现过程 → 人只出现在节点 → 运行中的问题全部落成文档 → 问题按节拍回流为体系升级 → 下一个项目启动更便宜、AI 更准确。
理想的一天（目的态叙事）：
- 早晨立项：一条命令完成规模判定，按产出时序生成契约文档骨架 + 预装裁决面（gate/词表/schema/CI）。人主笔 spec 与 constitution，签署阶段门。
- 白天执行：AI 在契约与裁决面之间自主实现。测试、gate、bench 红线代替人盯过程。遇到 ADR 级分叉或铁律冲突，才上浮一次请人拍板。
- 傍晚收口：/checkpoint 提交、写 HANDOFF、顺手跑体检——死链、指针一致性、盲区存量一屏报出。字面规则跑不通的地方已在发生时登记进 methodology-gaps。
- 月底复盘：盲区达线自动报警，人按一次"裁决按钮"，bump 上游方法论，修订以组件/模板/Skill 升级的形式下发所有项目。
- 下一个项目立项时，启动成本比上一个更低——飞轮转过了一圈。
3. 五段流水线
┌─ S1 启动段 ──► S2 执行段 ──► S4 沉淀段 ──► S5 演化段 ─┐
│ 契约+裁决面 AI 编程 问题→文档 盲区→bump→下发 │
│ ▲ │ 仅例外上浮 │
│ │ ▼ │
│ │ S3 例外段（人） │
└────────┴──────────── 飞轮：下发回到 S1，启动成本递减 ◄───────┘各段成熟度基线（📊 2026-07-02，双项目审计实测；判定依据见 §10）：
| 段 | 目标 | 现有载体 | 成熟度 |
|---|---|---|---|
| S1 启动 | 契约与裁决面一次成型 | 方法论 §3 产出时序 + /spec /plan /prd /product-design + doc-09 脚手架 | ◐ 零件全、总装线缺、预装包缺 |
| S2 执行 | 过程 100% AI | 契约文档（热区）+ 测试/gate/bench + /checkpoint | ✅ 已实证 |
| S3 例外 | 只在节点叫人 | ADR 流程 + 阶段门 + 铁律（constitution） | ✅ 已实证 |
| S4 沉淀 | 问题 100% 落文档 | HANDOFF / troubleshooting / lessons / methodology-gaps | ◐ 断点通道顺畅，盲区通道摩擦过高 |
| S5 演化 | 盲区按节拍回流 | doc-25 §5 三阶段流转 + §7 变更八步 | ✗ 设计完成、从未运转 |
3.1 S1 启动段
输入：项目想法 + 规模判定（§7，第一道分叉）。 输出：两类产物，缺一不可（§5 双翼原则）——
- 上下文面：按方法论 §3 DAG 依序生成的契约文档（人主笔 spec/constitution，AI 主笔其余，阶段门控制推进）；
- 裁决面：day-0 预装包（§6.2）——doc-governance gate、frontmatter schema、状态词表、引用语法契约、含代码反向边的影响矩阵、checkpoint 体检钩子。
分工：规模判定与文档生成由 AI 执行；spec/constitution 主笔与阶段门放行由人执行；预装接线由机器（脚手架）执行。
3.2 S2 执行段
定义：AI 在契约内自主完成实现，人不进过程。"契约内"= 上下文面告诉 AI 该做什么，裁决面告诉 AI 做对没有。 实证（📊 prompt-hub，2026-05-19 至 07-02）：130 commits / 6.5 周，改进轮 16 项 + 评审修复 5 项由 AI 独立完成并全绿推送；支撑它的裁决面为 151 前端测试 + 3 个源码级 gate + 231 Rust 测试 + CI 双 job + bench 退出码红线。 推论：AI 自主度与裁决面厚度成正比。扩大 S2 的正确投资是加厚裁决面，不是写更长的指令。
3.3 S3 例外段
上浮条件（满足其一才叫人，否则 AI 不得停机等待）：
- ADR 级决策（二选一/多选一的不可逆分叉）；
- 与 constitution 铁律冲突或需要修改铁律；
- 裁决面无法判定的验收（如真机视觉复核）；
- 外部依赖（账号、密钥、第三方动作）。
载体：ADR 模板 + 阶段门 + 会话内提问。上浮即记录——每次例外本身是 S4 的输入（它揭示契约或裁决面的缺口）。
3.4 S4 沉淀段
四通道，各有格式契约与责任时刻：
| 通道 | 内容 | 时刻 | 现状 |
|---|---|---|---|
| HANDOFF | 会话断点、下一步 | 每次 /checkpoint | ✅ 顺畅 |
| troubleshooting/ | 故障与解法 | 故障解决时 | ◐ 靠自觉 |
| lessons/ | 经验与反模式 | Agent 复盘时 | ◐ 靠自觉 |
| methodology-gaps | 字面规则跑不通 | 发生的当下 | ✗ 摩擦过高 |
摩擦红线：登记一条盲区 ≤ 2 分钟（模板复制即用），否则通道形同虚设。📊 实证：adl 的 15 条盲区靠一次专项 fan-out 审计才捞出（2026-06-04），日常流失率未知但必然很高。
3.5 S5 演化段
流程（已由 doc-25 §5 定义）：登记 → 达线（≥3 条 P0）→ bump 评估 → 走方法论 §7 八步 → 修订以可执行形态下发（组件升级 / 模板升级 / Skill 升级），回到 S1。 关键补强——下发必须是可执行物：纯文字修订不算完成下发；每条 bump 落地时必须回答"哪个 gate / 模板 / Skill 因此变了"。文字改了而执行面没变，等于没下发（§5 双翼原则在演化段的投影）。 实证（📊 adl）：P0 于 2026-06-04 达 bump 线，至 07-02 零处理、审计成果未提交、45 commits 未推送——飞轮迄今零圈。缺的不是机制设计，是节拍器（§6.3）。
4. 人的参与点契约
过程 100% AI，节点 100% 人。 两个 100% 同样重要，任何一侧塌方都是体系失败。
| 节点类型 | 具体动作 | 所在段 | 缺席后果 |
|---|---|---|---|
| 前置签署 | spec/constitution 主笔、阶段门放行、ADR 拍板 | S1 / S3 | AI 在错误方向上高效狂奔 |
| 例外裁决 | §3.3 四类上浮 | S3 | AI 停机或越权自决 |
| 周期按钮 | 月度复盘过盲区表、bump 达线裁决、（可选）checkpoint 复核 | S5 | 登记坟场，飞轮停转（📊 已发生，见 §3.5） |
两个对称的反模式：
- 监工回退：人进入 S2 过程逐步盯改。这是体系失败信号，正确响应不是继续盯，而是把盯的那条判断转化为新契约条款或新裁决面，然后退出过程。
- 节点缺席：人不按周期按钮。机器必须让"该按了"的信号主动找人（§6.3 节拍器），而不是靠人记得。
5. 双翼原则：上下文面 + 裁决面
AI 高效且准确的充要条件是两翼齐备：
| 翼 | 回答 | 载体 | 失效形态 |
|---|---|---|---|
| 上下文面 | 该做什么、边界在哪 | 契约文档（热区/温区）、CLAUDE.md、影响矩阵 | 文档失鲜/失真 → AI 高效地做错 |
| 裁决面 | 做对了没有 | 测试、gate、词表校验、bench 红线、CI | 无机器裁决 → 契约数周内漂移 |
核心命题（双项目实证）：契约显式且有机器执行面，则审计接近免费；契约只有文字面，则无论书写纪律多好，数周内必然漂移——
- 📊 prompt-hub（执行纪律最好的样本）：6.5 周内版本指针漂移 4 处、MANIFEST 漏列 4 项、frontmatter 在最新产物上开始腐化；
- 📊 adl（体系本体）：frontmatter 契约发布后 26/27 篇未执行、ADR 断号、500 行上限自违反 ×2。
推论：每新增一条"必须"级规范时，必须同时回答"哪个机器在守它"；答不出则降级为"建议"或补建 gate。
6. 三个缺失组件（规格）
流水线五段中，S2/S3 已成熟，其余三段各缺一个物理零件。
6.1 总装线（S1）——启动编排
一条命令完成：规模判定（§7 分叉）→ 按方法论 §3 DAG 依序调用 /spec /plan /prd /product-design 生成契约骨架 → 预装包接线（§6.2）→ 输出阶段门清单待人签署。 与 doc-09 的关系：这是脚手架 init 的升级目标形态——从"生成配置文件"升级为"生成契约 + 裁决面 + 节拍"。 验收：🎯 新项目从 0 到"AI 可开工"（契约签署完毕、CI 绿）≤ 半天，且过程无需人查阅方法论原文。
6.2 Day-0 预装包（S1）——契约的机器执行面
清单（每项均有双项目漂移实证支撑，见 §10）：
| 预装项 | 防的漂移 |
|---|---|
| doc-governance gate（死链 / 清单双向 / frontmatter schema / 状态词表 / 版本指针一致性 / 编号连续） | 引用腐烂、索引漂移、指针失同步 |
| frontmatter 最小 schema（type/status/version/description ≤120 字符） | 字段缺失与字段语义腐化 |
| 状态受控词表（ADR / plan / feature 三套显式声明） | 词表发散、状态僵尸 |
| 引用语法契约（wiki 目标写法、别名规则、外部前缀） | 引用形态发散 |
| 影响矩阵（含"代码事实变更 → 文档巡检"反向边） | 矩阵孤儿下游失鲜 |
| checkpoint 体检钩子 + cochange 基线流水 | 体检无节奏、指标无基线 |
形态：零依赖脚本 + 配置文件，先在本仓 dogfood，稳定后抽为通用组件（~/code/通用/）。 验收：🎯 预装项全部随 git commit / CI 自动执行，零人工触发。
6.3 节拍器（S5）——裁决节奏的机器化
- /checkpoint 收尾自动报告：盲区存量 N 条、P0 距 bump 线 X 条、超期挂起项（Proposed/Reserved > 45 天）；
- 月度复盘为强制节点：过一遍 methodology-gaps，每条给出 落地/推延/不补 三选一；
- bump 达线时主动报警（CI 或 checkpoint 输出），而非等人翻表。
验收：⚠️ 盲区从登记到获得裁决 ≤ 30 天为红线；🎯 常态 ≤ 14 天。
7. 规模适配：第一道分叉
流水线不是所有项目全量启用。规模判定是 S1 的第一步（判据沿用方法论 §4 适配矩阵）：
| 规模 | S1 启用 | 裁决面下限 |
|---|---|---|
| 微（周末工具） | CLAUDE.md + 最小 gate，不得触发全流程 | lint + 冒烟 |
| 小 | + spec / features / plan | + 单元测试 + gate |
| 中（如 prompt-hub） | 13 份按需 + 预装包全量 | + 源码级 gate + CI + bench 红线 |
| 大 | 全量 + L5 协作契约 | + eval 集 |
铁律：当人产生"这次绕过体系直接干"的冲动时，那是体系过重的报警信号——正确动作是登记一条盲区（体系该为此瘦身），而不是静默绕过。绕过不登记 = 飞轮失去燃料。
8. 飞轮健康指标
每段一个可测指标。数字标注遵循 doc-25 §4（🎯 目标 / 📊 基线 / ⚠️ 红线）。
| 段 | 指标 | 基线（2026-07-02） | 方向 |
|---|---|---|---|
| S1 | 启动成本（0 → AI 可开工的小时数） | 📊 未测 | 🎯 ≤ 4h，逐项目递减 |
| S2 | 文档协同变更率（代码提交中同步改文档占比） | 📊 34%（prompt-hub） | 持平或升 |
| S3 | 例外上浮频次与类型分布 | 📊 未测 | 观察（无好坏预设） |
| S4 | 盲区登记时延（发现 → 登记） | 📊 月级（靠专项审计） | 🎯 会话级 |
| S5 | 盲区处理时延（登记 → 裁决） | 📊 >28 天未处理 | ⚠️ 30 天红线 / 🎯 14 天 |
| 全局 | 相邻两个新项目的启动成本之比 | 📊 无（样本不足） | <1 = 飞轮在转的终极判据 |
指标记录责任：checkpoint 钩子自动追加一行流水（§6.3），月度复盘汇总。不建仪表盘（三个数够用的原则，见 doc-08）。
9. 失败模式
| 失败模式 | 症状 | 实证 | 防线 |
|---|---|---|---|
| 监工回退 | 人逐步盯 S2 过程 | —（尚未发生，预防性登记） | §4 反模式条款：盯的判断必须转化为契约/裁决面 |
| 登记坟场 | 盲区只进不出 | 📊 adl：P0 达线 28 天零处理 | §6.3 节拍器 + ⚠️ 30 天红线 |
| 重装反噬 | 小项目被拖入全流程，人绕过体系 | —（预防性登记） | §7 规模第一分叉 + 绕过必登记铁律 |
| 契约漂移 | 规范与盘面背离且无人知晓 | 📊 双项目 100% 复现（§5） | §6.2 预装包 + "必须级规范必有守卫"推论 |
10. 实证基础与谱系
本文档产出自 2026-07-02 的双项目文档体系审计对话，遵循 doc-06 §6.5"每行规则必须挣得位置"：
- prompt-hub 审计（130 commits / 56 篇 md / 1194 条 wiki 链接实测）：贡献 §3.2 执行段实证、§5 指针漂移与 frontmatter 腐化实证、§8 cochange 基线；
- adl 自审（27 篇设计文档 / 10132 行实测）：贡献 §3.5 飞轮零圈实证、§5 契约背离实证、§9 登记坟场实证;
- 外部方法论吸收（文档缺口审计手册，Tornhill 行为分析谱系）：其统计推断模式分流至 /takeover（接管无契约的外部项目），契约校验模式演化为 §6.2 预装包——吸收结论"契约显式则审计免费"即 §5 核心命题；
- 上游谱系：方法论 v1.3（§3 产出时序、§4 规模矩阵、§7 变更八步）+ doc-25（§4 数字标注、§5 盲区流转、§6 独立审计）。本文档对上游的反哺提案（影响矩阵反向边、§6.4 清单边界等）见 methodology-gaps.md 待登记项。
11. 演进路线
- v0.1（本版，draft）：叙事与规格定稿，待人审。
- v0.2：三组件（§6）落地后回填实测数据，📊 替换全部"未测"。
- v1.0（ratify 条件）：飞轮完成可验证的第一圈——一次完整的 S4 登记 → S5 bump → 下发 → 新项目 S1 受益，且 §8 全局指标 <1 得到首个样本。
关联：00-总体架构 | 06-文档体系 | 25-文档体系演化机制 | 上游方法论：~/Vault/知识库/方案模板/产品文档体系方法论.md v1.3