@mc-and-his-agents/loom-installer 0.1.1

package/payload/skills/loom-adopt/.loom-runtime/shared/references/governance/maturity-and-closing.md

@@ -0,0 +1,69 @@
+# Maturity And Closing
+
+本文件定义 Loom 治理内核中的稳定成熟度与关闭语义。
+
+本文件当前承接：
+
+- `EXT-0026`
+
+## 1. 文档定位
+
+`governance/maturity-and-closing.md` 负责定义：
+
+- 事项从说明到收口的最小阶段
+- 每个阶段的语义边界
+- 事项何时可以关闭
+
+稳定状态名与转移规则见 [state-machine.md](./state-machine.md)。
+issue 类型、激活规则与 `absorbed` 的消费边界见 [issue-model.md](./issue-model.md)。
+
+## 2. 成熟度先于关闭
+
+关闭语义必须与事项成熟度一致，不得提前制造“已完成”状态。
+
+说明完成、实现完成、合并就绪、主干收口是不同语义。
+
+## 3. 最小成熟度阶段
+
+稳定状态名、进入条件、允许转移与回退路径，全部唯一落在 [state-machine.md](./state-machine.md)。
+
+本文件不再并行重述四阶段名称，只保留总原则：
+
+- 不得跳过“说明已清楚 -> 实现进行中 -> 合并就绪 -> 已进入主干并收口”的语义顺序
+- 项目可以细化显示名，但不得破坏 [state-machine.md](./state-machine.md) 的稳定状态机语义
+
+## 4. 关闭一致性条件
+
+关闭条件的稳定定义也唯一落在 [state-machine.md](./state-machine.md) 中的 `closed_out` 语义。
+
+这里仅补充两个边界：
+
+- 当前执行侧入口见 [../harness/closeout-gate.md](../harness/closeout-gate.md)
+- GitHub 与仓内真相如何同步，见 [truth-and-sync-boundary.md](./truth-and-sync-boundary.md)
+- parent / child issue 如何消费 closeout，见 [issue-model.md](./issue-model.md)
+
+## 5. 规约完成与实现完成的分离语义
+
+默认语义边界：
+
+- 规约通过
+  - 表示“可进入实现”，不表示“实现完成”
+- PR 已开
+  - 表示“实现已开始”，不表示“事项完成”
+- merge-ready
+  - 表示“可进入主干”，不表示“已收口”
+- 进入主干并收口
+  - 才表示事项完成
+
+## 6. 关闭反模式
+
+禁止以下关闭方式：
+
+- 把证据冻结写成实现完成
+- 把规约通过写成事项完成
+- 在未进入主干时宣称已收口
+- 用局部结论替代整体完成判断
+
+## 7. 一句话结论
+
+成熟度模型的目标是让状态语义可验证，而不是让关闭动作更快发生。

package/payload/skills/loom-adopt/.loom-runtime/shared/references/governance/principles.md

@@ -0,0 +1,180 @@
+# Governance Principles
+
+本文件定义 Loom 治理内核中的稳定原则。
+
+这些原则来自当前已标记为 `core` 的提取条目：
+
+- `EXT-0001`
+- `EXT-0002`
+- `EXT-0006`
+- `EXT-0023`
+- `EXT-0034`
+
+## 1. 文档定位
+
+`governance/principles.md` 是治理原则真相源。
+
+它承接：
+
+- 真相源分层
+- 事项入口与分流
+- 规格准入
+- 载体职责边界
+- 仓库知识库模型
+- 机械化治理最小能力边界
+
+审查职责与 checkpoint 审查分工见 [review-model.md](./review-model.md)。
+成熟度与关闭语义见 [maturity-and-closing.md](./maturity-and-closing.md)。
+
+## 2. 真相源分层
+
+调度真相与仓库语义真相必须分层，不并行维护同一份完整真相。
+
+### 2.1 调度侧真相
+
+调度侧（例如 Issue / Project）负责：
+
+- 事项本体、目标、边界、关闭条件
+- 状态、优先级、依赖、阶段位置
+- 执行分解与排期
+
+### 2.2 仓库侧真相
+
+仓库侧负责：
+
+- 长期稳定规则
+- 边界事项规格与计划
+- 当前改动事实、验证与风险
+- checkpoint、恢复入口、handoff 等执行工件
+
+### 2.3 载体职责矩阵
+
+最小职责分离如下：
+
+- Issue
+  - 事项本体、目标、边界、关闭条件
+- Project
+  - 调度位置、优先级、阶段归属
+- PR
+  - 本次改动范围、验证证据、风险与回滚信息
+- 规则文档
+  - 长期稳定规则
+- 规格文档
+  - 边界事项的正式说明与计划
+- 执行工件
+  - checkpoint、恢复入口、handoff、阻断项
+
+禁止事项：
+
+- 在两个载体并行维护同一份完整事项状态
+- 让 PR 承担长期规则真相
+- 让执行工件承担调度层状态真相
+
+## 3. 受控执行入口与事项分流
+
+事项不得从意图直接进入实现，必须先进入受控入口。
+
+默认顺序：
+
+1. 判断事项类型
+2. 判断是否触发规格准入
+3. 确认进入实现的最低条件
+
+最小分流：
+
+- 轻量事项
+  - 默认可直接实现，但不得改动共享契约或运行模型
+- 中等事项
+  - 进入实现前需要简化设计说明
+- 边界事项
+  - 进入实现前必须通过规格准入
+
+## 4. 规格准入
+
+规格准入是治理准入机制，不是可选文档活动。
+
+### 4.1 触发条件
+
+以下任一成立时默认触发规格准入：
+
+- 共享契约变化
+- 公共边界变化
+- 运行模型变化
+- 部署方式变化
+- 高风险核心抽象变化
+
+### 4.2 最小工件
+
+边界事项至少应有：
+
+- `spec.md`
+- `plan.md`
+
+### 4.3 准入问题
+
+进入实现前至少应收口：
+
+- 为什么值得做
+- 本次改什么、不改什么
+- 影响哪些边界
+- 如何验证达标
+- 已知风险与应对方式
+
+## 5. 单一规则落点与知识库模型
+
+同一条规则必须有唯一权威落点；其他文档只做摘要、映射或引用。
+
+Loom 的知识库模型采用两层结构：
+
+- 短入口文档
+  - 负责指路、权威来源与读取顺序
+- 深知识文档
+  - 承接规则、方案、模板与运行机制
+
+禁止事项：
+
+- 把完整规则复制到多个文档并行维护
+- 把所有知识压成一个超大根文档
+- 让关键规则只留在会话中
+
+## 6. 三个 checkpoint 的治理不变量
+
+治理层必须有三个正式 checkpoint：
+
+- `admission checkpoint`
+  - 确认事项路径与准入条件
+- `build checkpoint`
+  - 在实现中纠偏并识别边界变化
+- `merge checkpoint`
+  - 只承担主干放行，不补做前序高质量判断
+
+三者的审查职责分工见 [review-model.md](./review-model.md)。
+
+## 7. 机械化治理能力边界
+
+治理规则应逐步具备可机械检查能力，至少覆盖：
+
+- 规则落点存在性
+- 核心文档结构完整性
+- 关键交叉引用可达性
+- 关键模板存在性
+- 明显职责越界信号
+
+机械检查不替代 reviewer 的语义判断。
+
+## 7.1 宿主平台硬门禁
+
+若 Loom 把仓内 gate 作为主干放行前提，宿主平台必须把这组 gate 配置成 fail-closed 的硬门禁，而不是只作为提示型检查。
+
+最小要求：
+
+- 主干分支存在受保护的合并路径
+- required checks 或等价 ruleset 已生效
+- 失败检查不得进入主干
+- 仓内 gate 通过，与宿主平台 gate 已强制，必须被明确区分并分别可复核
+
+Loom 不固化具体 GitHub UI、按钮名称或宿主产品细节，但必须把“仓内 gate 已定义”与“宿主 gate 已强制”区分为两个独立事实。
+
+## 8. 一句话结论
+
+治理原则的目标不是增加流程层数，而是让事项在正确入口进入、在正确载体承接、在正确时点收口。

package/payload/skills/loom-adopt/.loom-runtime/shared/references/governance/review-model.md

@@ -0,0 +1,109 @@
+# Review Model
+
+本文件定义 Loom 治理内核中的稳定审查模型。
+
+这些规则来自当前已标记为 `core` 的提取条目：
+
+- `EXT-0004`
+- `EXT-0014`
+- `EXT-0018`
+
+## 1. 文档定位
+
+`governance/review-model.md` 负责回答三件事：
+
+- 谁在什么时点做什么判断
+- 三个 checkpoint 如何分工
+- 审查输入最小基线如何确定
+
+事项路径和规格准入见 [principles.md](./principles.md)。
+成熟度与关闭语义见 [maturity-and-closing.md](./maturity-and-closing.md)。
+
+## 2. 审查职责分层
+
+Loom 默认把审查职责分成四类角色：
+
+- 作者
+  - 正确选择事项路径，补齐所需工件，说明验证与风险
+- reviewer
+  - 判断方向、边界与实现是否满足当前路径要求
+- 自动检查
+  - 承担结构完整性、工件存在性、基础一致性与明显越界信号检查
+- merge gate
+  - 只做主干放行判断，不补做前序阶段语义审查
+
+禁止事项：
+
+- 用 CI 替代语义审查
+- 用 merge gate 替代事项方向判断
+- 让 reviewer 补做作者应完成的准入澄清
+
+## 3. 三个 checkpoint 的审查分工
+
+### 3.1 Admission checkpoint
+
+回答：
+
+- 事项路径是否正确
+- 是否触发规格准入
+- 是否具备进入实现的条件
+
+默认主责：作者 + reviewer。
+
+### 3.2 Build checkpoint
+
+回答：
+
+- 当前实现是否仍在已确认轨道上
+- 是否出现新的边界变化或风险升级
+- 是否需要回退到说明层重新收口
+
+默认主责：作者 + reviewer；自动检查提供结构和越界信号。
+
+### 3.3 Merge checkpoint
+
+回答：
+
+- 当前 head 是否达到进入主干的质量线
+- 已承诺范围是否已完成并可验证
+
+默认主责：reviewer + merge gate；不承担第一次语义理解。
+
+## 4. 最小必要上下文
+
+审查输入默认采用最小必要上下文，不做整仓材料默认广播。
+
+最小上下文建议：
+
+- Admission checkpoint
+  - 事项目标、边界、路径判定依据、所需准入工件
+- Build checkpoint
+  - 当前变更、阶段结论、风险变化、必要验证证据
+- 正式 review
+  - `flow review` 输出、review record、必要 findings 与 reviewer 结论
+- Merge checkpoint
+  - 最终变更集、验证结论、风险与回滚信息、未完成事项
+
+## 5. 审查基线来源
+
+审查必须有基线。默认读取顺序：
+
+1. Issue 的目标与边界
+2. 规格文档或简化设计说明
+3. 当前变更与验证事实
+
+只有当前证据不足时，才补充更长历史材料。
+
+## 6. 回退规则
+
+Build checkpoint 发现以下情形时，默认回退到说明层：
+
+- 新的共享契约变化
+- 运行模型或部署方式变化
+- 核心边界扩大且当前工件无法覆盖
+
+回退后应先更新准入工件，再继续实现。
+
+## 7. 一句话结论
+
+审查模型的目标是把高价值判断前移并分层，而不是把所有判断挤在 merge 前。

package/payload/skills/loom-adopt/.loom-runtime/shared/references/governance/state-machine.md

@@ -0,0 +1,163 @@
+# State Machine
+
+本文件定义 Loom `v0.3.0` 当前稳定的事项状态机与关闭语义。
+
+本文件当前承接：
+
+- `#157`
+
+## 1. 文档定位
+
+本文件只回答三件事：
+
+- Loom 事项有哪些稳定成熟度状态
+- 状态之间如何推进、阻断与回退
+- 什么条件下才允许关闭
+
+字段载体与同步边界由 [truth-and-sync-boundary.md](./truth-and-sync-boundary.md) 承接。
+执行侧 closeout 入口由 [../harness/closeout-gate.md](../harness/closeout-gate.md) 承接。
+issue 类型与激活语义由 [issue-model.md](./issue-model.md) 承接。
+
+## 2. 稳定状态
+
+Loom 当前固定四个成熟度状态：
+
+- `clarified`
+  - 说明已清楚，可进入正式执行
+- `implementing`
+  - 实现进行中，正在持续产生执行证据
+- `merge_ready`
+  - 已达到进入 host merge 前的质量线
+- `closed_out`
+  - 结果已进入主干，且控制面与仓内状态已收口
+
+这四个状态是语义状态，不要求宿主平台直接使用同名字段。
+
+## 3. 状态进入条件
+
+### 3.1 `clarified`
+
+至少同时满足：
+
+- 目标、范围与关闭条件已明确
+- 已有可消费的正式执行入口
+- 准入前置条件与验证方式已写清
+
+默认证据：
+
+- `work item`
+- 必要时附带 `spec.md` / `plan.md`
+
+### 3.2 `implementing`
+
+至少同时满足：
+
+- 已从 `clarified` 进入正式执行
+- 已存在恢复主入口或等价动态执行真相
+- 当前轮次能够回写停点、下一步、阻断项与最近验证摘要
+
+默认证据：
+
+- `work item`
+- recovery 主入口
+
+### 3.3 `merge_ready`
+
+至少同时满足：
+
+- build 级结果已达线
+- 正式 review 结论可消费
+- merge checkpoint 已能回答“可进入 host merge”
+
+默认证据：
+
+- review record
+- merge-ready 摘要或等价执行输出
+- merge checkpoint 结果
+
+### 3.4 `closed_out`
+
+至少同时满足：
+
+- 必要实现已进入主干
+- closeout gate 已通过
+- issue / project / PR / 主干状态已同步到一致结论
+
+默认证据：
+
+- 主干包含结果
+- closeout gate 结果
+- GitHub 控制面同步结果
+
+## 4. 转移规则
+
+允许的主路径转移只有：
+
+- `clarified -> implementing`
+- `implementing -> merge_ready`
+- `merge_ready -> closed_out`
+
+允许的回退只有：
+
+- `implementing -> clarified`
+  - 当范围、关闭条件或准入条件被推翻时
+- `merge_ready -> implementing`
+  - 当 review、验证或 checkpoint 结论要求回退时
+- `merge_ready -> clarified`
+  - 当晚暴露的问题已经回到 admission / 说明层，例如共享契约、运行模型或事项边界本身失真
+
+不允许：
+
+- 从 `clarified` 直接跳到 `merge_ready`
+- 从 `implementing` 直接宣称 `closed_out`
+- 在未进入主干前宣称 `closed_out`
+
+## 5. 阻断与回退不是独立成熟度状态
+
+以下语义会影响状态推进，但不是新的成熟度状态：
+
+- `block`
+  - 当前状态不能继续向后推进
+- `fallback`
+  - 必须退回前一成熟度状态或前一执行链路
+- `retired`
+  - 属于现场或恢复入口的终态，不等于事项已 `closed_out`
+- `absorbed`
+  - 属于 closeout 可消费结论，不等于事项成熟度状态
+
+换句话说：
+
+- `block` / `fallback` 是转移结果
+- `retired` 是执行现场状态
+- `absorbed` 是 closeout 可消费语义
+- 事项成熟度仍只落在四个稳定状态中
+
+## 6. 关闭语义
+
+只有 `closed_out` 才表示事项可以关闭。
+
+以下结论都不等于事项完成：
+
+- `spec` 已通过
+- PR 已创建
+- `merge_ready`
+- merge checkpoint 已允许放行
+
+关闭动作必须以 `closed_out` 为前提，而不是以“代码改完了”或“PR 绿了”为前提。
+
+## 7. 与宿主字段的关系
+
+宿主平台可以使用不同命名，但不得破坏以下语义映射：
+
+- issue / project 的进行中状态
+  - 不得冒充 `merge_ready` 或 `closed_out`
+- PR open
+  - 只表示实现载体存在，不表示已可关闭
+- PR merged
+  - 只表示结果进入主干，不自动表示已收口
+- issue closed
+  - 只能映射到 `closed_out`
+
+## 8. 一句话结论
+
+Loom 的状态机目标不是增加更多名词，而是让“何时能前进、何时要回退、何时才算完成”有稳定可消费的语义。

package/payload/skills/loom-adopt/.loom-runtime/shared/references/governance/truth-and-sync-boundary.md

@@ -0,0 +1,161 @@
+# Truth And Sync Boundary
+
+本文件定义 Loom `v0.3.0` 当前稳定的真相分层、派生面与同步边界。
+
+本文件当前承接：
+
+- `#158`
+
+## 1. 文档定位
+
+本文件回答：
+
+- 哪些对象承接 authored 真相
+- 哪些对象只能承接 host control truth
+- 哪些对象只是派生读面或运行证据
+- Loom 如何同步，而不是复制第二套真相
+
+字段级事实链仍以 [../harness/fact-chain-contract.md](../harness/fact-chain-contract.md) 为准。
+
+## 2. 四层真相模型
+
+Loom 当前固定四层：
+
+- repo execution truth
+  - 仓内 authored 执行真相
+- host control truth
+  - 宿主平台的控制面真相
+- derived read surfaces
+  - 从前两层派生的读面
+- runtime / review evidence
+  - 被消费的运行或审查证据
+
+## 3. Repo Execution Truth
+
+以下对象进入 repo execution truth：
+
+- `work item`
+  - 静态执行真相
+- recovery 主入口
+  - 动态执行真相
+- review record
+  - 正式 review 真相
+
+这些对象的 authored 字段只能在仓内主载体中维护。
+
+它们回答的问题分别是：
+
+- `work item`
+  - 做什么、范围是什么、通过什么入口推进
+- recovery 主入口
+  - 现在停在哪、下一步是什么、有什么阻断
+- review record
+  - 正式 review 给出的结论、权威 findings、rebuttal 与 disposition 是什么
+
+## 4. Host Control Truth
+
+以下对象进入 host control truth：
+
+- issue
+  - 当前治理事项在宿主平台中的控制面状态
+- project item
+  - 计划、优先级、状态展示等控制面字段
+- PR
+  - 实现载体与 merge 相关控制面
+- branch protection / required checks / ruleset
+  - host merge 前硬门禁
+
+它们回答的问题是：
+
+- 这项工作在 GitHub 上处于什么控制面状态
+- 当前实现载体是否存在、是否可被合并
+- host 平台是否允许进入下一步
+
+它们不是 repo execution truth 的替代品。
+
+## 5. Derived Read Surfaces
+
+以下对象只允许派生读取：
+
+- status surface
+- merge-ready 摘要
+- closeout 摘要
+- `init-result` 中的统一读取入口
+
+这些对象可以汇总信息，但不得反向覆盖 authored 真相。
+
+## 6. Runtime / Review Evidence
+
+以下对象进入证据层：
+
+- CI run
+- guardian / reviewer 输出
+- 日志、trace、诊断信息
+- PR 评论中的临时讨论
+
+这些对象可以被 Loom 消费，但默认不是长期 authored 真相。
+
+若其中某项需要成为长期真相，必须回写到稳定主载体：
+
+- review 结论
+  - 回写到 review record
+- review findings / disposition
+  - 仍回写到同一 review record，不新增第二 authored truth object 或状态机
+- 动态停点与下一步
+  - 回写到 recovery 主入口
+
+## 7. 同步的定义
+
+Loom 所说的 `sync`，不是把所有信息复制两份。
+
+Loom 当前只允许以下同步：
+
+- repo execution truth -> host control truth
+  - 例如 closeout 时把应关闭的 issue / project 状态推进到一致结果
+- repo execution truth -> derived read surfaces
+  - 例如从 `work item` 与 recovery 主入口重渲染状态面、resume 摘要或其他统一读取面
+- host control truth -> derived read surfaces
+  - 例如把 PR / checks 状态汇总到 merge-ready 或 closeout 读面
+
+不允许以下同步：
+
+- 用 issue body 反向覆盖 `work item`
+- 用 PR body 反向覆盖 review record
+- 用 project status 反向覆盖 recovery 主入口
+
+## 8. 冲突处理
+
+当 repo execution truth 与 host control truth 冲突时：
+
+- 先保留两边原值
+- 明确报出 drift
+- 通过专门 sync 入口修复
+
+当前执行面上：
+
+- drift 审计由 `reconciliation audit` 承接
+- control-plane 对齐由后续专门 sync 入口承接
+
+不允许：
+
+- 静默选择其中一边
+- 在派生读面里偷偷掩盖冲突
+
+## 9. 最小责任矩阵
+
+| 对象 | 层级 | 默认职责 |
+| --- | --- | --- |
+| `work item` | repo execution truth | 静态执行真相 |
+| recovery 主入口 | repo execution truth | 动态执行真相 |
+| review record | repo execution truth | 正式 review 真相 |
+| issue | host control truth | 治理事项控制面 |
+| project item | host control truth | 计划与状态展示控制面 |
+| PR | host control truth | 实现载体与 merge 控制面 |
+| status surface | derived read surface | 执行摘要读面 |
+| merge-ready 摘要 | derived read surface | 放行前汇总读面 |
+| closeout 摘要 | derived read surface | 收口前汇总读面 |
+| CI / guardian / reviewer 输出 | runtime / review evidence | 可消费证据 |
+
+## 10. 一句话结论
+
+Loom 的同步目标是让不同层的真相保持一致，不是把同一个 authored 事实复制到所有载体里。