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

package/payload/skills/loom-adopt/.loom-runtime/shared/references/harness/status-surface.md

@@ -0,0 +1,121 @@
+# Status Surface
+
+本文件定义 Loom 当前最小状态面合同。
+
+本文件当前承接：
+
+- `EXT-0035`
+
+## 1. 能力定位
+
+状态面用于快速读取当前执行状态和运行事实。
+
+它服务读取，不服务并行记账。
+本文件把“状态读取字段”和“运行时证据入口”明确拆开定义。
+字段归属与派生关系以 [fact-chain-contract.md](./fact-chain-contract.md) 为准。
+
+## 2. 状态读取字段
+
+Loom 当前至少要求状态面能展示：
+
+- 当前事项
+- 当前执行路径
+- 当前 checkpoint 阶段
+- 当前工作现场
+- 当前恢复主入口
+- 当前 review 入口
+- 当前环境 lane
+- 当前阻断项
+- 下一步
+- 最近验证摘要
+
+这些字段必须从已有主真相派生，不允许手工维护第二套 authored 值：
+
+- `当前事项`、`当前执行路径`
+  - 从 `work item` 派生
+- `当前 checkpoint 阶段`、`当前阻断项`、`下一步`、`最近验证摘要`、`当前环境 lane`
+  - 从恢复主入口派生
+- `当前工作现场`、`当前恢复主入口`、`当前 review 入口`、`验证入口`
+  - 从 `work item` 与 `init-result` 的 carrier 定位派生
+
+## 3. `Runtime Evidence` 固定区块
+
+状态面若承接运行时证据，必须提供固定标题区块 `Runtime Evidence`。
+
+该区块固定为以下 5 个字段，字段不得缺失：
+
+- `Run Entry`
+- `Logs Entry`
+- `Diagnostics Entry`
+- `Verification Entry`
+- `Lane Entry`
+
+每个字段的值只能是：
+
+- locator 字符串
+- `not_applicable`
+
+## 3.1 字段合同矩阵
+
+| 字段 | 最小语义 | 允许值 | `not_applicable` 允许条件 |
+| --- | --- | --- | --- |
+| `Run Entry` | 告诉执行者去哪启动当前事项运行面 | locator / `not_applicable` | 事项不涉及可运行系统 |
+| `Logs Entry` | 告诉执行者去哪看运行输出或日志 | locator / `not_applicable` | 无运行进程或无日志载体 |
+| `Diagnostics Entry` | 指向指标、trace 或等价诊断入口 | locator / `not_applicable` | 当前事项没有诊断面 |
+| `Verification Entry` | 指向 UI/API/E2E 等可验证入口 | locator / `not_applicable` | 事项不涉及可验证运行结果 |
+| `Lane Entry` | 指向当前 lane 的运行/诊断读取入口 | locator / `not_applicable` | 事项没有 lane 区分 |
+
+判定规则：
+
+- 字段缺失始终是错误，不等同于 `not_applicable`。
+- `not_applicable` 必须按字段判断，不能整组一刀切。
+- 若某字段标记 `not_applicable`，应与 `current_lane`、`execution_path`、`latest_validation_summary` 等事实不冲突。
+
+## 4. 运行时证据入口语义
+
+最小证据类别对应如下：
+
+- `Run Entry`
+  - 当前工作现场对应的运行入口
+- `Logs Entry`
+  - 日志或等价运行输出入口
+- `Diagnostics Entry`
+  - 指标、trace 或其他等价诊断入口至少一种
+- `Verification Entry`
+  - UI、接口或端到端结果中的至少一种 agent 可验证入口
+- `Lane Entry`
+  - 当前环境 lane 对应的诊断或读取入口
+
+Loom 固化的是“可读取、可验证”的能力目标，不固化具体可观测工具栈。
+
+## 5. `not_applicable` 语义
+
+若事项不涉及可运行系统，状态面应明确标出运行时证据为 `not_applicable`，而不是伪造运行入口。
+
+典型场景包括：
+
+- 纯文档事项
+- 纯治理规则调整
+- 仅结构整理、尚无运行载体的事项
+
+`not_applicable` 可以按字段逐项声明。
+
+例如：
+
+- `Verification Entry` 可读
+- `Run Entry`、`Logs Entry`、`Diagnostics Entry`、`Lane Entry` 为 `not_applicable`
+
+`not_applicable` 只说明该字段当前不适用，不说明验证已自动通过。
+
+## 6. 边界约束
+
+- 禁止手工维护第二套平行真相
+- 状态面负责读取，不重复承接正式规则定义
+- 状态面若展示的 `next_step`、`blockers`、`latest_validation_summary` 与恢复主入口不一致，应视为事实链断裂
+- `Runtime Evidence` 的 5 个字段必须全部出现；不允许用“缺字段”表达不适用
+- 运行时证据入口不等于完整 observability 平台设计；本文件只要求最小可读入口
+
+当前仓库中的统一读取入口包括：
+
+- `python3 loom-init/scripts/loom-init.py fact-chain --target <repo>`
+- `python3 shared/scripts/loom_flow.py runtime-evidence --target <repo> [--item <id>]`

package/payload/skills/loom-adopt/.loom-runtime/shared/references/harness/work-item-contract.md

@@ -0,0 +1,104 @@
+# Work Item Contract
+
+本文件定义 Loom 当前最小 work item / `exec-plan` 合同。
+
+本文件当前承接：
+
+- `EXT-0037` 的初始化产物模型
+
+完整执行顺序见 [execution-chain.md](./execution-chain.md)。
+
+## 1. 能力定位
+
+work item 是进入正式执行的入口。
+若项目使用 `exec-plan` 或等价工件，它只承接执行与恢复。
+
+本文件同时定义初始化后至少应落位哪些执行产物。
+字段归属见 [fact-chain-contract.md](./fact-chain-contract.md)。
+
+## 2. work item 最小合同
+
+进入正式执行的事项，必须有可追踪的 work item，并至少表达：
+
+- 事项标识
+- 目标
+- 范围
+- 当前执行路径
+- 关联工件
+- 工作现场入口
+- 恢复主入口路径
+- review 结论入口
+- 当前验证入口
+- 关闭条件
+
+一个 work item 对应一个清晰目标，不得承载多个无关正式事项。
+
+## 3. 初始化产物模型
+
+当 Loom 初始化一个仓库或一条正式执行链路时，最小产物应包括：
+
+- 可进入执行的首批 work item 或等价事项清单
+- 至少一个 `progress` / `checkpoint` 载体
+- 与事项关联的唯一恢复主入口约定
+- 可定位的执行路径与工作现场入口
+- 后续验证或执行支撑的入口约定
+- 首个稳定提交或等价回退边界，用于界定初始化后的首轮 clean state
+
+Loom 不固化这些产物的具体文件名，但要求它们在初始化完成后已可读取、可回写、可继续执行。
+
+## 4. `exec-plan` 的职责边界
+
+如果项目使用 `exec-plan`，其职责应限制为：
+
+- 记录当前停点
+- 记录下一步
+- 记录已验证事实
+- 记录阻断项
+- 记录与正式工件的关联
+
+禁止事项：
+
+- 用 `exec-plan` 替代正式需求真相
+- 用 `exec-plan` 替代长期状态真相
+- 用 `exec-plan` 吞并多个无关事项
+
+## 5. 与执行链路的关系
+
+work item / `exec-plan` 至少要能被以下环节消费：
+
+- 每轮读取
+- 工作现场定位
+- 每轮回写
+- 验证汇总
+- merge checkpoint 放行
+
+不同执行路径可以有不同最小输入强度：
+
+- 轻量事项
+  - work item 可直接进入实现与 PR
+- 中等事项
+  - work item 应关联简化设计说明
+- 正式规约事项
+  - work item 应关联 `spec.md` 与 `plan.md`
+
+无论路径轻重，都必须能被 [execution-context.md](./execution-context.md)、[recovery-model.md](./recovery-model.md) 与 [merge-checkpoint.md](./merge-checkpoint.md) 消费。
+
+## 6. 事实链约束
+
+- `work item` 只承接静态执行真相，不并行 authored 当前停点、下一步、阻断项或最近验证摘要
+- `work item` 可以 authored `review_entry` 这类 locator，但不得 authored review 结论本身
+- 当前 checkpoint 属于恢复主入口，而不是 `work item`
+- 状态面若展示 `goal`、`scope`、`execution_path` 等字段，必须从 `work item` 派生
+
+## 7. 最小 author/update 入口
+
+静态事项 authoring 由日常 CLI 显式承接：
+
+- `python3 shared/scripts/loom_flow.py work-item create --target <repo> --item <id> ...`
+- `python3 shared/scripts/loom_flow.py work-item update --target <repo> --item <id> ...`
+
+边界固定如下：
+
+- `create` / `update` 只写静态字段与关联工件
+- 是否切换为当前活跃事项，必须显式使用 `--activate`
+- `--activate` 只允许改 locator truth，不得顺手写 recovery 动态字段

package/payload/skills/loom-adopt/.loom-runtime/shared/references/harness/workspace-and-purity.md

@@ -0,0 +1,73 @@
+# Workspace And Purity
+
+本文件定义 Loom 当前最小纯度与范围控制规则。
+
+本文件当前承接：
+
+- `EXT-0029`
+
+## 1. 能力定位
+
+纯度与范围控制用于约束正式执行现场、分支和 PR 不发生职责漂移。
+
+它服务的是执行边界，不替代需求分流或方案判断。
+
+## 2. 最小纯度目标
+
+Loom 当前至少要求以下纯度：
+
+- 分支目标纯度
+  - 一个正式分支服务一个主要事项
+- PR 范围纯度
+  - 一个 PR 只承载同一语义目标下的改动
+- 工作现场职责纯度
+  - 当前现场不混入无关事项的执行残留
+
+## 3. 范围控制边界
+
+以下情况视为范围越界信号：
+
+- 为完成当前事项，顺手推进无关目标
+- 在同一分支或 PR 中并入另一事项的正式改动
+- 为规避拆分成本，把多个目标包装成一个执行单元
+
+纯度机制只判断是否越界，不直接判断新增目标本身是否合理。
+新增目标是否成立，应回到 work item 或治理分流处理。
+
+## 4. 默认处理
+
+发现纯度异常时，默认动作应是：
+
+- 停止继续叠加改动
+- 先拆分、清理或重新分流
+- 再进入后续审查或提交流程
+
+## 5. 与自动化前置的关系
+
+纯度和明显范围越界信号应尽量前置暴露。
+但是否需要新建事项、拆分 PR 或调整目标，仍属于执行与治理决策，不由纯度脚本单独裁决。
+
+## 6. `purity-check` 最小输出语义
+
+`python3 loom-retire/scripts/loom-retire.py purity-check --target <repo> [--item <id>]` 的输出至少包含：
+
+- `runtime_state`
+  - 当前 Loom 入口自己的 scene / carrier 判定
+  - install layout / shared runtime / shared references 漂移时必须直接 `block`
+
+- `hard_failures`
+  - 第一版硬失败项，包含事实链断裂、现场冲突、残留未分流、明显多事项共享现场等
+- `report_only`
+  - 第一版只报告不阻断项，当前包含 branch purity 与 PR purity
+- `scope_assessment`
+  - `mode: constrained | unconstrained`
+  - `declared_paths`
+  - `out_of_scope_changes`
+
+当 `scope_assessment.mode` 为 `constrained` 且出现 `out_of_scope_changes` 时，应视为范围越界阻断信号。
+
+`python3 shared/scripts/loom_flow.py state-check --target <repo> [--item <id>]` 会复用同一纯度结果，并额外检查活跃状态与 checkpoint 完整性。
+
+`python3 shared/scripts/loom_flow.py workspace cleanup|retire --target <repo> [--item <id>]` 同样必须先消费 `runtime-state`；若当前 carrier 不再可执行，不得继续清理或退休现场。
+
+branch / PR purity 的宿主生命周期边界见 [host-lifecycle-boundary.md](./host-lifecycle-boundary.md)。

package/payload/skills/loom-adopt/.loom-runtime/shared/references/harness/workspace-model.md

@@ -0,0 +1,56 @@
+# Workspace Model
+
+本文件定义 Loom 当前最小工作现场模型。
+
+本文件当前承接：
+
+- `EXT-0025`
+- `EXT-0012`
+- `EXT-0037` 的 clean state 部分
+
+## 1. 能力定位
+
+工作现场用于承接正式执行，而不是临时试探。
+
+它负责：
+
+- 为单一正式事项提供隔离现场
+- 为恢复动作提供可定位目标
+- 为该事项消费的 host branch / `git worktree` / PR 绑定提供执行侧锚点
+- 为初始化后的 clean state 提供承载边界
+
+## 2. 最小现场规则
+
+正式执行链路默认使用隔离工作现场，并满足：
+
+- 单现场单事项
+- 同一现场只服务一个主要目标
+- 恢复动作应能回到同一现场
+- 新事项不得默认复用脏现场继续推进
+
+现场标识可以参数化，但必须由稳定输入确定性生成，不能只依赖人工记忆。
+
+## 3. clean state 要求
+
+初始化或现场创建完成后，应处于可继续执行的 clean state。
+
+最小要求：
+
+- 现场与目标事项已明确绑定
+- 进入执行所需的初始工件已经落位
+- 当前现场不存在未分流的无关正式改动
+- 后续恢复不需要重新猜测应进入哪个现场
+
+## 4. 边界约束
+
+Loom 只固化现场隔离、单事项和可恢复定位。
+必要时，Loom 会读取 `active issue` 与 host branch / `git worktree` / PR 的绑定来校验现场是否仍服务同一事项。
+
+Loom 当前不固化：
+
+- 具体目录命名格式
+- 是否必须使用 worktree
+- 具体命令、脚本或平台命名约定
+
+branch、PR 与 git worktree 的宿主边界见 [host-lifecycle-boundary.md](./host-lifecycle-boundary.md)。
+`active issue` 绑定消费见 [host-issue-binding.md](./host-issue-binding.md)。

package/payload/skills/loom-adopt/.loom-runtime/shared/references/templates/pull-request.md

@@ -0,0 +1,44 @@
+# Pull Request
+
+本文件定义 Loom 当前最小 PR 模板规则。
+
+本文件当前承接：
+
+- `EXT-0008`
+- `EXT-0028`
+
+## 1. PR 模板必须服务判断
+
+PR 模板的目标是提供最小必要事实，不是把作者变成填表机器。
+
+## 2. 基础必填块
+
+Loom 的基础 PR 模板至少应包含：
+
+- 本次改动解决什么问题
+- 改动范围是什么
+- 如何验证
+- 有哪些风险或未决项
+- 关联事项是什么
+
+## 3. 条件触发块
+
+PR 模板可以有扩展块，但不应默认强加给所有 PR。
+
+默认要求：
+
+- 只有在当前改动确实涉及对应主题时，才启用额外区块
+- 扩展块应围绕特定风险、迁移、回滚、数据变更等主题展开
+
+## 4. Loom 当前约束
+
+Loom 支持结构化 PR 模板，但必须满足：
+
+- 基础模板保持短小
+- 条件块按需触发
+- 模板内容直接服务 review 与 merge 判断
+
+不允许：
+
+- 用超重模板制造机械性噪音
+- 把长期规则真相写死在 PR 模板里

package/payload/skills/loom-adopt/.loom-runtime/shared/references/templates/review-record.md

@@ -0,0 +1,35 @@
+# Review Record
+
+正式 review record 至少应表达：
+
+- `item_id`
+- `kind`
+- `reviewed_head`
+- `reviewed_validation_summary`
+- `decision`
+- `summary`
+- `reviewer`
+- `fallback_to`
+- `findings`
+- `blocking_issues`
+- `follow_ups`
+- `consumed_inputs`
+
+允许结果：
+
+- `allow`
+- `block`
+- `fallback`
+
+约束：
+
+- `fallback_to` 只在 `decision: fallback` 时使用
+- `reviewed_head` 与 `reviewed_validation_summary` 必须对应本次审查基线
+- merge checkpoint 允许 review 之后只新增 Loom 自身的 `review_entry` / recovery / status carriers 提交；除此之外的 `HEAD` 漂移仍视为 stale
+- `findings` 是权威 findings / rebuttal / disposition 数组；每条至少包含 `id`、`summary`、`severity`、`rebuttal`、`disposition`
+- `severity` 当前稳定值为 `warn`、`block`
+- `rebuttal` 当前稳定值为 `null` 或非空字符串
+- `disposition` 当前稳定值为 `null` 或对象；对象内的 `status` 只允许 `accepted`、`rejected`、`deferred`
+- `blocking_issues` / `follow_ups` 仅作为兼容字段保留，默认从 `findings` 投影，不应被当作独立 authored 真相
+- `consumed_inputs.engine_adapter`、`consumed_inputs.engine_evidence`、`consumed_inputs.normalized_findings` 只记录 evidence 来源，不构成第二 authored truth
+- review record 是 merge checkpoint 的正式输入之一，不得只留在会话或 PR 评论里

package/payload/skills/loom-adopt/.loom-runtime/shared/references/templates/spec-suite.md

@@ -0,0 +1,57 @@
+# Spec Suite
+
+本文件定义 Loom 当前最小正式规约套件。
+
+本文件当前承接：
+
+- `EXT-0015`
+- `EXT-0016`
+- `EXT-0017`
+
+## 1. 正式规约套件的最小边界
+
+Loom 当前把正式规约套件的最小内核定义为：
+
+- `spec.md`
+- `plan.md`
+
+这两个工件分别承担不同职责，不得混写。
+
+## 2. `spec.md` 最小要求
+
+`spec.md` 至少应表达：
+
+- 目标
+- 范围
+- 关键场景，优先使用 `GWT`
+- 异常与边界
+- 验收标准
+
+## 3. `plan.md` 最小要求
+
+`plan.md` 至少应表达：
+
+- 实施目标
+- 阶段拆分
+- 约束
+- 验证方式
+- `TDD` 或测试策略
+- 依赖关系
+- 进入实现前条件
+
+## 4. 套件边界规则
+
+Loom 必须区分：
+
+- 正式契约工件
+- 执行或进度工件
+
+默认要求：
+
+- `spec.md` 与 `plan.md` 属于正式最小套件
+- 进度跟踪类工件是否存在，可以按项目需要扩展
+
+Loom 当前不固化：
+
+- 所有项目都必须有同一组附加工件
+- `TODO.md` 或同类文件是永恒必选项