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

package/payload/skills/loom-init/.loom-runtime/shared/references/adoption/deep-existing-repo-default.md

@@ -0,0 +1,64 @@
+# Deep Existing Repo Default
+
+本文件定义 Loom 面向成熟既有治理重仓的默认接入策略。
+
+它不替代 `lightweight-retrofit-default`，而是作为 `complex-existing` 下的保守 attach path，服务已经拥有稳定根规则、统一验证入口与沉重 repo-specific gates 的仓库。
+
+## 1. 适用场景
+
+当目标仓库同时满足以下条件时，默认采用本策略：
+
+- 属于既有仓库，且 `loom-init` 判断仍为 `复杂既有仓库`
+- 已有清晰的根级边界文档
+- 已有统一的仓库级验证入口
+- 已出现 `merge_review_semantic_overload`
+- 当前复杂度主要来自 review / guardian 负载、repo-specific gates、retained host actions 或 repo-native carriers，而不是 Loom 缺少 recovery/status carriers
+
+## 2. 默认目标
+
+第一轮接入的目标不是把成熟治理栈重写成 Loom 自己的 recovery / status 体系，而是让 Loom 先稳定挂到既有入口与读面上。
+
+默认先解决：
+
+- 让 `loom-init` 对这类仓库不再误走 `full-bootstrap`
+- 让 Loom 有稳定的 `recognize-and-attach` 入口
+- 让 repo companion 成为 Loom 读取 repo-specific rules 的正式入口
+- 让 root rules、retained host actions 与 repo-native carriers 明确保留在原 ownership
+
+## 3. 默认装配
+
+本策略默认优先装配：
+
+- `.loom/bootstrap/*` attach metadata
+- `.loom/README.md`
+- `.loom/companion/README.md`
+- companion-owned 的最小 repo-specific read surfaces
+- repo-local `.loom/bin/*` 读取与验证入口
+
+## 4. 默认接入方式
+
+本策略固定采用 `recognize-and-attach`：
+
+- 保留原有 root rules
+- 保留 retained host actions 的宿主 ownership
+- 保留 repo-native carriers
+- 只追加 Loom-owned attach metadata 与 companion 入口
+
+## 5. 默认不装配
+
+第一轮默认不装配：
+
+- `.loom/work-items/*`
+- `.loom/progress/*`
+- `.loom/status/current.md`
+- Loom-owned recovery/status carriers 的 bootstrap placeholder
+- 对 branch / PR / worktree / merge / ruleset 的底层宿主重写
+
+## 6. 升级信号
+
+以下任一条件出现时，不应继续停留在 attach-only 默认路径：
+
+- 当前仓库需要 Loom-owned recovery carrier 承接多轮执行停点
+- repo-native carriers 无法稳定承接 recovery / review / closeout 真相
+- companion 之外还需要 Loom-owned status surface 承接统一读面
+- repo-local attach 入口已经稳定，但下一轮需要 typed machine contract、interop 或 shadow parity

package/payload/skills/loom-init/.loom-runtime/shared/references/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-init/.loom-runtime/shared/references/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-init/.loom-runtime/shared/references/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-init/.loom-runtime/shared/references/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-init/.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. 一句话结论
+
+成熟度模型的目标是让状态语义可验证，而不是让关闭动作更快发生。