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

package/payload/skills/loom-review/references/shared/adoption/lightweight-retrofit-default.md

@@ -0,0 +1,71 @@
+# Lightweight Retrofit Default
+
+本文件定义 Loom 面向小型既有仓库的默认 retrofit 策略。
+
+它来自 `mail-listener` 的第一轮真实 adoption 验证，并由 `DevSkills` 的反例验证补强适用边界。
+
+## 1. 适用场景
+
+当目标仓库同时满足以下条件时，默认采用本策略：
+
+- 已有清晰的工程边界文档，例如 `AGENTS.md`
+- 已有 CI 与基础测试
+- 已有统一的仓库级验证入口，而不是只有零散子模块脚本
+- 当前缺的是治理入口、review 合同或条件化 spec 路径
+- 当前还没有明显的长任务恢复痛点
+- 当前主产物本身不是共享 contract、shared skill 或 governance module
+
+## 2. 默认目标
+
+第一轮 retrofit 的目标不是装完整 Loom，而是先建立最小治理闭环。
+
+默认先解决：
+
+- 改动如何进入实现
+- reviewer 如何判断改动
+- 哪些边界改动必须先说明再实现
+
+## 3. 默认装配
+
+本策略默认优先装配：
+
+- `WORKFLOW`
+- `code_review`
+- `spec_review`
+- 最小 PR 模板
+- 条件化 `spec.md` / `plan.md`
+
+## 4. 默认接入方式
+
+如果目标仓库已经有稳定的根级边界文档，默认采用 `companion docs` 接入：
+
+- 保留原有根规则文档
+- 只追加治理伴随文档与职责映射
+- 不在第一轮重写整个根级规则体系
+
+## 5. 默认不装配
+
+第一轮默认不装配：
+
+- 完整 recovery 模型
+- work item 合同
+- 状态面
+- profile 分层
+- 重 harness
+
+## 6. checkpoint-lite
+
+如果事项会跨多轮推进，但还不值得引入独立恢复工件，允许先采用 `checkpoint-lite`：
+
+- 在 issue 或 PR 描述中记录当前停点
+- 在 issue 或 PR 描述中记录下一步
+- 在 issue 或 PR 描述中记录阻断项
+
+这是一种轻量过渡形态，不等于永久替代 recovery 模型。
+
+以下任一条件出现时，不应继续使用本策略或 `checkpoint-lite`：
+
+- 没有统一仓库级验证入口
+- 仓库主产物本身是共享 contract、shared skill 或 governance module
+- 已出现共享契约、共享数据模型或高风险核心抽象
+- 已出现多个运行入口、多个状态入口或明显恢复痛点

package/payload/skills/loom-review/references/shared/adoption/routing-and-checkpoints.md

@@ -0,0 +1,88 @@
+# Routing And Checkpoints
+
+本文件定义 Loom 当前的事项分流与 checkpoint 策略。
+
+本文件当前承接：
+
+- `EXT-0007`
+- `EXT-0024`
+- `EXT-0019`
+- `EXT-0022`
+
+## 1. 事项分流
+
+Loom 当前默认把事项分成三条入口：
+
+- 轻量事项
+  - 不改变正式契约、上位边界或高风险链路
+- 中等事项
+  - 需要冻结目标、范围、验证与回滚，但不一定进入完整正式规约
+- 正式规约事项
+  - 涉及共享边界、共享契约、共享数据模型、高风险链路或核心实现承诺
+
+## 2. 当前默认路径
+
+- 轻量事项
+  - 直接进入实现 PR
+- 中等事项
+  - 先形成简化设计说明，再进入实现
+- 正式规约事项
+  - 先完成实现前审查，再进入实现
+
+## 3. 不应过早固化分层体系
+
+Loom 当前保留分流思想，但不先把它固化为 profile 体系。
+
+原因是：
+
+- 事项分类必须服务执行
+- 不应反过来要求用户先理解复杂分类学
+- 初始化 `SKILL` 应负责把用户场景映射到合适入口
+
+## 4. checkpoint 策略
+
+Loom 当前至少应支持三类正式判断点：
+
+- `admission checkpoint`
+  - 判断事项是否具备进入实现承诺的条件
+- `build checkpoint`
+  - 判断当前实现是否仍在已批准轨道上
+- `merge checkpoint`
+  - 判断当前 head 是否满足进入主干的条件
+
+其中：
+
+- 本文保留三类 checkpoint 的治理与采用语义
+- 执行侧的最小承接链路见 [../harness/execution-chain.md](../harness/execution-chain.md)
+- `merge checkpoint` 的执行侧输入、结果与回退去向见 [../harness/merge-checkpoint.md](../harness/merge-checkpoint.md)
+
+`admission checkpoint` 在 adoption 语义上表达“进入实现承诺前的正式判断”。
+治理内核中的稳定命名与审查分工，见 [../governance/review-model.md](../governance/review-model.md)。
+
+## 5. Loom 当前约束
+
+- 不允许只有 `merge checkpoint` 足够强，而前两者长期虚化
+- 不允许 merge 前 review 承担第一次高质量语义判断
+- 不允许中等事项长期在“轻量事项”和“正式规约事项”之间无明确入口
+- 不允许把三类 checkpoint 的执行侧输入、回写和放行规则继续留给读者自行拼装
+
+## 6. 与 `skills/` 的关系
+
+这些分流和 checkpoint 规则，最终应由初始化 `SKILL` 转化成实际提问、决策与装配逻辑。
+
+## 7. 与 `harness/` 的关系
+
+`adoption/` 只保留：
+
+- 为什么需要三类 checkpoint
+- 哪类事项默认进入哪条路径
+- checkpoint 之间的治理不变量
+
+以下执行侧细节不再由本文展开：
+
+- 初始化产物如何进入正式执行
+- 每轮开始前必须读取哪些事实
+- 每轮结束后必须回写哪些事实
+- merge checkpoint 放行前必须可读取哪些验证与状态事实
+
+这些内容统一由 `harness/` 中的稳定合同承接。

package/payload/skills/loom-review/references/shared/governance/host-object-taxonomy.md

@@ -0,0 +1,148 @@
+# Host Object Taxonomy
+
+本文件定义 Loom `v0.3.0` 当前稳定的宿主对象 taxonomy 与合同命名。
+
+本文件当前承接：
+
+- `#153`
+
+## 1. 文档定位
+
+本文件回答：
+
+- Loom 当前识别哪些对象类型
+- 各类对象在 Loom 中如何命名
+- 哪些名称可以直接进入稳定合同
+
+对象的真相分层由 [truth-and-sync-boundary.md](truth-and-sync-boundary.md) 承接。
+对象的生命周期边界由 [../harness/host-lifecycle-boundary.md](../harness/host-lifecycle-boundary.md) 承接。
+
+## 2. 四类对象
+
+Loom 当前固定四类对象：
+
+- execution objects
+  - Loom 自己直接消费的执行对象
+- host control objects
+  - 宿主平台提供的控制面对象
+- derived objects
+  - Loom 汇总得到的派生对象
+- evidence objects
+  - Loom 消费但不默认 authored 的证据对象
+
+## 3. Execution Objects
+
+进入 execution objects 的对象：
+
+- `work item`
+- recovery 主入口
+- review record
+- `workspace`
+
+命名要求：
+
+- 使用 Loom 语义名，不直接套宿主 UI 名称
+- 能区分静态真相、动态真相、审查真相与执行现场
+
+## 4. Host Control Objects
+
+进入 host control objects 的对象：
+
+- issue
+- project item
+- PR
+- branch
+- `git worktree`
+- branch protection / ruleset / required checks
+
+命名要求：
+
+- 优先使用宿主通用名
+- 在合同里明确写成 `host` 对象，而不是误写成 Loom 自己拥有生命周期
+
+例如：
+
+- `active execution issue`
+  - 指当前被选为宿主执行对象的 issue，而不是 `work item`
+- `host merge`
+  - 指宿主平台真正执行的 merge
+- `host branch`
+  - 指 Git branch，而不是 Loom 现场
+- `host PR`
+  - 指 GitHub PR，而不是 review record
+
+## 5. Derived Objects
+
+进入 derived objects 的对象：
+
+- status surface
+- merge-ready 摘要
+- closeout 摘要
+- route / resume / handoff 摘要
+
+命名要求：
+
+- 明确写成 `summary`、`surface`、`snapshot` 或 `result`
+- 不得让名称看起来像 authored 主真相
+
+## 6. Evidence Objects
+
+进入 evidence objects 的对象：
+
+- CI run
+- check run / workflow run
+- guardian 输出
+- reviewer 评论
+- 日志、trace、诊断信息
+
+命名要求：
+
+- 保留其宿主来源属性
+- 不得把 evidence 命名成 record truth
+
+例如：
+
+- `review record`
+  - 是真相对象，内部承接正式 review 的 findings / rebuttal / disposition contract
+- `review comments`
+  - 是证据对象
+
+## 7. 稳定命名规则
+
+Loom 当前固定以下命名规则：
+
+- `workspace`
+  - 只表示 Loom 执行现场，不等于 `git worktree`
+- `git worktree`
+  - 只表示 Git 宿主对象
+- issue activation
+  - 只表示宿主 issue 已进入当前执行，不等于 `work-item --activate`
+- `review record`
+  - 只表示正式 review 真相，包含同一载体内的 findings / rebuttal / disposition authored 字段
+- `PR`
+  - 只表示宿主实现载体
+- `merge-ready`
+  - 只表示 Loom 的放行前状态，不等于 host merge
+- `closeout`
+  - 只表示进入主干后的收口阶段，不等于 merge
+
+## 8. 合同命名约束
+
+在稳定合同中：
+
+- 若对象由 Loom authored
+  - 使用 Loom 语义名
+- 若对象由宿主平台拥有
+  - 保留宿主名，并在语义上标明其是 host object
+- 若对象只是汇总
+  - 名称必须包含 `summary`、`surface`、`snapshot` 或等价词
+
+不允许：
+
+- 用 `workspace` 指代 `git worktree`
+- 用 `review` 指代 PR approval、review record、review comments 三种不同对象
+- 用 `merge` 同时指 merge-ready、host merge 与 closeout
+
+## 9. 一句话结论
+
+taxonomy 的目标不是造新术语，而是保证 Loom、GitHub、Git、review engine 和执行入口在讨论同一对象时不再混用名字。

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

@@ -0,0 +1,127 @@
+# Issue Model
+
+本文件定义 Loom `v0.3.0` 当前稳定的执行型 issue 模型。
+
+本文件当前承接：
+
+- `#175`
+
+## 1. 文档定位
+
+本文件只回答四件事：
+
+- Loom 当前如何区分不同类型的 issue
+- 哪些 issue 可以作为执行对象进入活跃推进
+- parent / child issue 在 closeout 中各自承担什么角色
+- `absorbed` 这类结论如何被消费
+
+事项成熟度状态由 [state-machine.md](state-machine.md) 承接。
+成熟度与关闭总原则由 [maturity-and-closing.md](maturity-and-closing.md) 承接。
+宿主对象命名由 [host-object-taxonomy.md](host-object-taxonomy.md) 承接。
+`active issue` 与 host branch / `git worktree` / PR / merge commit 的绑定证明见 [../harness/host-issue-binding.md](../harness/host-issue-binding.md)。
+
+## 2. 稳定 issue 类型
+
+Loom 当前固定三类 issue：
+
+- `spec / planning issue`
+  - 用于冻结目标、范围、方案、拆分或阶段判断
+  - 不是默认执行对象
+- `active execution issue`
+  - 用于承接当前真实实施缺口
+  - 是默认执行对象
+- `validation / closeout issue`
+  - 用于承接验证、对账、收口或主干真相同步
+  - 只在实现主体已基本完成、但仍存在独立收口工作时使用
+
+这三类是 Loom 对 issue 的稳定语义分类，不要求宿主平台直接提供同名字段。
+
+## 3. parent / child 语义
+
+在 issue tree 中：
+
+- parent issue
+  - 默认是范围、阶段或收口容器
+  - 不默认等于当前活跃执行对象
+- child issue
+  - 默认承接可独立推进的真实执行缺口
+  - 是否激活取决于是否已经进入当前轮次实施
+
+稳定约束：
+
+- 不得把历史规划 parent 长期冒充活跃执行 issue
+- 不得把尚未进入实施的 child issue 提前写成进行中
+- 当 parent 只承担汇总与收口时，应让真正实施落在 child issue
+
+## 4. 激活规则
+
+### 4.1 issue 级激活
+
+issue 级激活表示：
+
+- 该 issue 已被选为当前轮次要推进的宿主执行对象
+- 它应在宿主控制面上体现为进行中或等价语义
+- 后续证据、PR、review 或 closeout 应围绕该 issue 建立一致关系
+
+issue 未被激活时，可以继续存在于 tree 中，但默认保持 `Todo` 或等价未开始语义。
+
+### 4.2 `work-item --activate`
+
+`work-item --activate` 表示：
+
+- Loom 执行现场把某个 `work item` 切换为当前 locator truth
+- 当前轮次恢复、停点与执行入口开始指向该 `work item`
+
+它不等于：
+
+- 自动激活对应 issue
+- 自动改变宿主 project / issue 状态
+- 自动宣称事项成熟度已进入下一阶段
+
+换句话说：
+
+- issue 级激活是宿主执行对象语义
+- `work-item --activate` 是 Loom 执行入口语义
+
+两者通常相关，但必须明确区分，不得互相偷换。
+
+## 5. 关闭与收口角色
+
+issue closeout 仍以 [state-machine.md](state-machine.md) 的 `closed_out` 为前提。
+
+在 issue tree 中：
+
+- child issue
+  - 关闭取决于该 child 自身缺口是否已进入主干并完成收口
+- parent issue
+  - 关闭取决于其应消费的 child closeout 是否已经完成，且 parent 自身不再保留真实剩余缺口
+
+因此：
+
+- parent 可以作为收口容器消费多个 child 的 closeout 结果
+- child 不应因为 parent 仍 open 就被阻止关闭
+- parent 也不应因为某个 child 曾经被规划过就长期保持失真 open
+
+## 6. `absorbed` 的边界
+
+`absorbed` 不是成熟度状态。
+
+它只表示：
+
+- 某个原始 issue 所代表的缺口，已被其他已收敛的执行结果覆盖或吸收
+
+Loom 当前只稳定约束两点：
+
+- `absorbed` 可以被 parent closeout 消费
+- `absorbed` 也可以被 child issue closeout 消费
+
+本文件不定义：
+
+- `absorbed` 需要哪些 host 证明细节
+- 由哪一类宿主证据组合才能判定 `absorbed`
+
+这些证明细节属于具体仓库 closeout 实践，不属于 Loom 当前治理合同。
+
+## 7. 一句话结论
+
+Loom 的 issue 模型目标不是把所有 issue 都变成执行对象，而是稳定区分规划、执行、验证/收口三类语义，并让激活与 closeout 只围绕真实缺口发生。

package/payload/skills/loom-review/references/shared/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-review/references/shared/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. 一句话结论
+
+治理原则的目标不是增加流程层数，而是让事项在正确入口进入、在正确载体承接、在正确时点收口。