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

package/payload/skills/loom-merge-ready/references/shared/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-merge-ready/references/shared/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 事实复制到所有载体里。

package/payload/skills/loom-merge-ready/references/shared/harness/automation-frontload.md

@@ -0,0 +1,139 @@
+# Automation Frontload
+
+本文件定义 Loom 当前最小自动化前置规则。
+
+本文件当前承接：
+
+- `EXT-0009`
+- `EXT-0036`
+- `EXT-0041` 的 Loom 内核消费边界
+
+## 1. 能力定位
+
+能稳定机械判断的规则，应尽量前置到脚本、CI 或等价自动化入口。
+
+自动化前置负责降低重复人工判断，不负责替代语义审查。
+merge checkpoint 只消费这些结果，不把它们扩写成第一次高质量判断。
+
+## 2. 通用 core 检查矩阵
+
+| 检查类别 | 检查对象 | 失败含义 | 非目标 | 是否阻断 merge checkpoint |
+| --- | --- | --- | --- | --- |
+| 结构完整性 | 目录、命名、必备分区是否落位 | 当前仓库结构不满足 Loom 最小执行前提 | 不判断结构是否最优 | 是 |
+| 规则落点 | 关键规则是否存在唯一主落点 | 读者无法定位规则真相，或出现重复承接 | 不判断规则内容是否已经最优 | 是 |
+| 模板存在性 | 正式模板与必要字段是否存在 | 正式事项缺少承载结构，后续无法稳定消费 | 不判断模板示例是否覆盖全部业务场景 | 是 |
+| 交叉引用 | 关键文档与入口链接是否可达 | 执行链路在仓库中断裂，读取路径不可达 | 不判断引用后的内容质量 | 是 |
+| 纯度/越界信号 | 明显脏现场、无关改动、范围越界信号 | 当前执行材料不适合继续叠加或放行 | 不替代 reviewer 的语义审查 | 视严重度而定 |
+| 执行支撑入口存在性 | work item、恢复入口、验证入口、运行入口等是否可定位 | 仓库无法形成最小执行闭环 | 不判断入口实现强度是否已达最佳 | 是 |
+| checkpoint 入口存在性 | `admission`、`build`、`merge` 三类 checkpoint 入口是否可调用 | 放行链路不完整，无法按阶段消费事实链 | 不替代 checkpoint 的语义审查 | 是 |
+| 运行时证据可读性 | `Runtime Evidence` 五字段是否可读且可区分 `not_applicable` | 验证摘要不可复核，merge 消费不到稳定证据 | 不判断证据内容是否已经最优 | 是 |
+| 运行态识别 | 当前入口是否能稳定区分 `repo-local-demo`、`installed-runtime`、`upgrade-rehearsal` | 安装态 / 升级态被伪装成“入口存在且可运行” | 不替代宿主自己的安装实现 | 是 |
+| workspace lifecycle 入口存在性 | `create`、`locate`、`cleanup`、`retire` 与 `purity-check` 是否可调用 | 现场治理不可机械执行，恢复与交接风险升高 | 不替代现场治理策略设计 | 是 |
+| 基础状态一致性 | checkpoint、下一步、阻断项、验证摘要是否相互对齐 | 当前状态不可读，恢复与放行会消费到冲突事实 | 不判断事项目标本身是否值得做 | 是 |
+| 事实链唯一性 | 静态真相、动态真相与派生读面是否各守边界 | 仓库出现并行记账或事实链断裂 | 不替代 reviewer 的方案判断 | 是 |
+
+这里的“执行支撑”包括初始化入口、恢复入口、验证入口、运行入口、checkpoint 入口以及 workspace lifecycle 入口等被正式规则要求的机械支撑。
+
+## 2.1 失败分类与阻断语义
+
+为避免“失败但不可读”，前置检查至少要归类为以下失败类型：
+
+| 失败分类 | 典型触发 | 默认阻断语义 | 回退去向 |
+| --- | --- | --- | --- |
+| `fact_chain_broken` | 主真相载体缺失、断链、并行记账 | 阻断 | 回到事实链修复 |
+| `active_state_conflict` | 当前事项与恢复入口冲突、多活跃事项共享现场 | 阻断 | 回到恢复入口/现场治理 |
+| `checkpoint_gap` | checkpoint 入口缺失、阶段输入缺失、结果语义异常 | 阻断 | 回到 admission/build 补齐 |
+| `scope_overflow` | 变更明显超出当前事项范围或单目标边界 | 阻断 | 回到范围收敛与分流 |
+| `runtime_evidence_gap` | 运行时证据字段缺失或 `present/not_applicable` 冲突 | 阻断 | 回到验证入口补证据 |
+| `workspace_residue` | Loom-owned 残留未清理、无关改动未分流 | 视严重度阻断 | 回到 cleanup/purity-check |
+
+非目标保持不变：
+
+- 不把 reviewer 的方案判断改写成脚本硬编码结论
+- 不把宿主特定流程细节上移为 Loom 默认前置
+
+## 3. `skills` 触发与行为回归的候选矩阵
+
+`skills` 入口层的触发正确性与行为退化，属于 Loom 在 `EXT-0041` 下承接的候选型前置 / 回归验证面，不与通用 core 检查混写。
+
+| 候选检查面 | 最小目标 | 不进入 Loom 内核的内容 |
+| --- | --- | --- |
+| 显式触发 | 指定 skill 时能命中正确入口或 adapter | 宿主 CI 中的完整端到端脚本矩阵 |
+| 隐式触发 | 典型场景能路由到正确入口层能力 | 宿主特定 prompt 路由细节 |
+| 行为退化 | 入口层输出仍满足声明的最小职责 | 下游仓库的完整业务回归用例 |
+| adapter 失败可见性 | 失败时能暴露可读取错误入口 | 宿主内部监控产品或告警平台 |
+
+Loom 内核只定义这些检查面的边界，不内置宿主特定 CI、测试框架或 adapter 实现。
+
+## 3.1 当前仓库中的最小执行入口
+
+Loom 仓库当前通过以下入口承接最小 core 前置检查：
+
+- `make loom-check`
+- `python3 shared/scripts/loom_check.py`
+- `python3 loom-init/scripts/loom-init.py verify --target <repo>`
+- `python3 loom-init/scripts/loom-init.py runtime-state --target <repo>`
+- `python3 loom-init/scripts/loom-init.py fact-chain --target <repo>`
+- `python3 shared/scripts/loom_flow.py fact-chain --target <repo> [--item <id>]`
+- `python3 shared/scripts/loom_flow.py runtime-state --target <repo> [--item <id>]`
+- `python3 shared/scripts/loom_flow.py runtime-evidence --target <repo> [--item <id>]`
+- `python3 shared/scripts/loom_flow.py state-check --target <repo> [--item <id>]`
+- `python3 loom-pre-review/scripts/loom-pre-review.py flow pre-review --target <repo> [--item <id>]`
+- `python3 shared/scripts/loom_flow.py checkpoint <admission|build|merge> --target <repo> [--item <id>]`
+- `python3 shared/scripts/loom_flow.py workspace <create|locate|cleanup|retire> --target <repo> --item <id>`
+- `python3 loom-retire/scripts/loom-retire.py purity-check --target <repo> [--item <id>]`
+
+当前脚本至少覆盖：
+
+- 结构完整性
+- 规则与核心落点存在性
+- 模板与入口资产存在性
+- Markdown 交叉引用可解析
+- `skills` 机读 root 合同的最小一致性
+- `skills` 升级协议与 bootstrap CLI 入口的一致性
+- demo 事实链 carrier 的唯一性与一致性
+- checkpoint 入口存在性与最小结果语义
+- 活跃状态冲突与 checkpoint 缺口暴露
+- 范围越界与 workspace residue 的 purity 预检
+- 运行时证据五字段可读性与 `not_applicable` 判定
+- workspace lifecycle / purity-check 入口存在性
+
+GitHub Actions 工作流会复用同一入口，而不是维护第二套命令。
+
+对于控制面 drift，自动化前置必须显式暴露同范围 `reconciliation audit` 结果，不能把 `warn` / `fix-needed` / `block` 静默吞掉后继续走 closeout。
+closeout 需要控制面对齐时，顺序必须是先处理 `fix-needed` / `block` drift，再继续 closeout；`warn` 必须保留在输出中，但不默认升级为阻断。
+
+对于 Loom 自身仓库，默认 gate 不应退化成单一 job 的自证通过路径。
+最小执行面至少应把以下检查拆成可单独读取的失败面：
+
+- 入口脚本可编译
+- demo bootstrap 可重建
+- repo-local demo CLI 可真实执行
+- `loom_check` 仓库自检可通过
+
+最小接入 demo 则通过以下入口复验：
+
+- `make loom-demo-new-project`
+
+## 4. 不应错误前置的判断
+
+以下判断不应被伪装成全自动结论：
+
+- 目标是否值得做
+- 方案是否正确
+- 风险是否真正收口
+- 当前实现是否解决了正确问题
+
+## 5. 边界约束
+
+Loom 的自动化前置必须区分两类事情：
+
+- 机械判断交给机器
+- 语义判断保留给人、reviewer 或其他正式治理角色
+
+不允许：
+
+- 把可自动判断事项长期留给人工重复执行
+- 把需要语义判断的事项伪装成硬编码脚本结果
+- 把 `skills` 候选回归面误当成 Loom 默认 core 检查面
+- 允许 `work item`、恢复入口、状态面并行 authored 同一事实

package/payload/skills/loom-merge-ready/references/shared/harness/closeout-gate.md

@@ -0,0 +1,97 @@
+# Closeout Gate
+
+本文件定义 Loom 当前最小 closeout 执行链路。
+
+宿主动作统一结果词表与 `fallback_to` 纪律见 [host-action-contract.md](host-action-contract.md)。本文件只承接 closeout 专有的 fail-closed 顺序与同步边界。
+
+## 1. 能力定位
+
+closeout gate 用来回答两件事：
+
+- 当前事项是否已经达到“进入主干并收口”的最小条件
+- GitHub issue / PR / project / main 是否与仓内结果态一致
+
+在 installed-skills 或 `.loom/bin` carrier 下，`reconciliation audit|sync` 与 `closeout check|sync` 必须先消费 `runtime-state`。
+若 install layout、shared runtime、shared references 或 bootstrap manifest 漂移，入口必须直接 `block`。
+
+## 2. 稳定入口
+
+- `python3 skills/shared/scripts/loom_flow.py reconciliation audit --target <repo> [--issue <n>] [--pr <n>] [--project <n>]`
+- `python3 skills/shared/scripts/loom_flow.py closeout check --target <repo> [--issue <n>] [--pr <n>] [--project <n>]`
+- `python3 skills/shared/scripts/loom_flow.py closeout sync --target <repo> [--issue <n>] [--pr <n>] [--project <n>]`
+- `python3 skills/shared/scripts/loom_flow.py reconciliation sync --target <repo> [--issue <n>] [--pr <n>] [--project <n>] [--comment-file <path>] [--dry-run]`
+
+## 3. `check` 最小检查面
+
+`closeout check` 至少读取：
+
+- 本地 gate 结果
+- 同范围 `reconciliation audit` 结果
+- issue 状态
+- PR 是否已 merged
+- 事项对应实现是否已达到 `absorbed`
+- merged PR 是否已进入 `origin/main`
+- project 中对应 issue 的状态
+
+若这些事实不一致，结果必须返回 `block`。
+
+`closeout check` 只允许返回 `pass` 或 `block`：
+
+- 普通 closeout 缺口
+  - 返回 `block`，并把 `fallback_to` 指向 `merge`
+- reconciliation 返回 `fix-needed`
+  - 返回 `block`，并把 `fallback_to` 指向 `reconciliation-sync`
+- reconciliation 返回 `block`
+  - 返回 `block`，并把 `fallback_to` 指向 `manual-reconciliation`
+
+`closeout` 不把 drift 或控制面缺口伪装成顶层 `fallback` 结果。
+
+`closeout check` 内部消费 `reconciliation audit` 时，阻断纪律如下：
+
+- `pass`：允许继续读取 merge / main / project 等 closeout 事实
+- `warn`：必须显式挂到 closeout 输出，但不默认阻断
+- `fix-needed`：必须返回 `block`；先经 `reconciliation sync` 完成机械对齐，再重新执行 closeout check
+- `block`：必须返回 `block`；先消除硬冲突或缺失事实，且在 audit 重新达标前禁止任何 closeout sync 写入
+
+这里的 `absorbed` 只表示 host merge 后可证明的实现吸收结论，不等于 `closed_out`。
+因此，`closeout check` 至少要能区分：
+
+- 该 issue 已由其对应实现进入 `closed_out`
+- 该 issue 的实现已被其他 merged work `absorbed`，但控制面尚未完成 closeout sync
+- 该 issue 仍保留独立剩余缺口，不能被视为 `absorbed`
+
+## 4. `sync` 最小动作
+
+本阶段的正式写路径是 `reconciliation sync`。`closeout sync` 不单独跳过这一步；它只在同范围 reconciliation 已达可同步条件后继续消费 closeout 结论。`reconciliation sync` 只做控制面对齐动作：
+
+- 先消费同范围的 `reconciliation audit` 结果，再生成可执行 sync 计划
+- 在条件满足时关闭 issue
+- 在 project 中把对应 item 状态设为 `Done`
+
+约束：
+
+- 若 `reconciliation audit` 出现任一 `block` finding，`sync` 必须直接返回 `block`，且不做任何写入
+- `sync` 只允许对 `fix-needed` finding 做机械修复；`warn` 仅保留提示，不触发写入
+- `--dry-run` 只输出基于 audit 的计划，不修改 GitHub 控制面
+- `--comment-file` 与 `--comment` 二选一，只为当前 issue closeout comment 提供正文来源
+
+`closeout sync` 仍保持 closeout 控制面对齐入口，但不得绕过已显式暴露的 reconciliation 结果。
+
+`closeout sync` 也只允许返回 `pass` 或 `block`。若同步前置不满足，或同步后仍无法把控制面对齐，必须继续显式指向 `reconciliation-sync`、`manual-reconciliation` 或 `merge`，而不是产出新的 host action 结果词表。
+
+若 parent issue 通过 child issue 的 `closed_out` / `absorbed` 结果完成自身 closeout 判断，`sync` 只负责把这一已成立结论写回控制面，不替代 parent 对剩余缺口的判断。
+
+它不替代：
+
+- PR merge 动作
+- `absorbed` 证明本身
+- review 执行层
+- recovery writeback
+- workspace cleanup / retire
+
+## 5. 非目标
+
+- 不在 Loom 内核里固化 GitHub UI、按钮或 ruleset 细节
+- 不把 project 中不存在的 PR item 强行当作阻断
+- 不让 closeout sync 绕过 gate 或 merge 事实
+- 不把 reconciliation sync 扩展成新的对象模型或自动化宿主产品

package/payload/skills/loom-merge-ready/references/shared/harness/execution-chain.md

@@ -0,0 +1,56 @@
+# Execution Chain
+
+本文件定义 Loom 当前最小执行链路。
+
+本文件当前承接：
+
+- `EXT-0038` 的完整链路语义
+- `#24` 的稳定落点
+
+## 1. 能力定位
+
+Loom 的 harness 不是若干孤立规则，而是一条从初始化产物到 `admission -> build -> merge` checkpoint 的最小执行链路。
+字段归属与派生边界见 [fact-chain-contract.md](fact-chain-contract.md)。
+
+本文件只定义链路本身：
+
+- 每个阶段的必需输入
+- 每个阶段的最小输出
+- 唯一主入口
+- 失败或不足时的回退去向
+
+阶段内的字段级合同，仍以各稳定组件文档为准。
+
+## 2. 最小执行链路
+
+| 阶段 | 必需输入 | 最小输出 | 唯一主入口 | 不满足时的回退去向 |
+| --- | --- | --- | --- | --- |
+| 初始化产物就位 | 初始化场景、能力选择、首批事项 | 可进入执行的 work item、恢复入口、验证入口、工作现场入口 | [work-item-contract.md](work-item-contract.md) | 回到 `harness-design.md` 补初始化与装配 |
+| 正式进入执行 | 当前事项、范围、执行路径、checkpoint 状态 | 单一正式执行单元被明确绑定 | [work-item-contract.md](work-item-contract.md) | 退回 work item 补范围、目标或关闭条件 |
+| 每轮读取 | work item、恢复主入口、工作现场、最近验证摘要 | 本轮单一推进单元、当前上下文基线 | [execution-context.md](execution-context.md) | 退回恢复主入口或状态面补齐事实 |
+| 隔离现场推进 | 上下文基线、工作现场、纯度约束 | 与当前事项一致的执行结果 | [workspace-model.md](workspace-model.md) | 退回现场治理，清理纯度或范围越界问题 |
+| 每轮回写 | 本轮执行结果、验证记录、阻断项 | 最新停点、下一步、验证摘要、回退边界 | [recovery-model.md](recovery-model.md) | 回到恢复入口补齐回写，不得只停留在会话里 |
+| 验证汇总 | 自动检查结果、人工验证、运行证据入口 | 最近验证摘要、未决阻断项、是否可进 checkpoint | [status-surface.md](status-surface.md) | 回到验证入口继续补验证或声明 `not_applicable` |
+| admission checkpoint | 最新事实链、事项范围、入口完整性、关键阻断项 | `pass`、`block` 或 `fallback`（回退前序） | `checkpoint-model.md`（admission） | 回到 work item / recovery 回写补齐输入或收敛范围 |
+| build checkpoint | admission 结果、构建/测试结论、运行时证据可读性 | `pass`、`block` 或 `fallback`（回退 admission） | `checkpoint-model.md`（build） | 回到 admission 或验证入口补齐缺失证据 |
+| 正式 review | pre-review / review 基线、build 结果、review evidence、review record | reviewer 结论可被 merge checkpoint 消费 | [review-execution.md](review-execution.md) | 回到 build / review run / recovery 回写 / review record |
+| merge checkpoint 放行 | build 结果、最新 head、验证摘要、风险与回滚、未决项 | `允许放行`、`阻断待补` 或 `退回前序 checkpoint` | [merge-checkpoint.md](merge-checkpoint.md) | 按结果回退到 build / admission / 验证阶段继续补材料 |
+| closeout 收口 | main 已包含合并结果、issue / project / gate 状态 | issue / project / 主干状态一致 | [closeout-gate.md](closeout-gate.md) | 回到 merge / GitHub 状态同步 |
+
+## 3. `checkpoint-lite` 升级条件在链路中的位置
+
+`checkpoint-lite` 只适用于读取和回写成本都足够低的链路。
+
+一旦出现以下任一信号，就应在“每轮回写”阶段升级为标准恢复形态，而不是继续拖到 checkpoint 阶段再补：
+
+- 事项已连续跨多轮推进
+- 新接手者无法仅靠现有入口恢复上下文
+- 验证摘要、风险或回退边界已无法稳定寄存在 issue / PR 等载体
+- admission / build / merge checkpoint 已需要稳定消费恢复事实
+
+## 4. 链路约束
+
+- 每轮执行只推进一个清晰单元，不在同一轮并行吞入多个无关目标
+- 每个阶段都必须有唯一主入口；补充材料不得并行替代主入口
+- merge checkpoint 只承接放行，不承担第一次高质量语义判断
+- 本文件不替代各组件的字段级合同；字段级规则仍以被引用组件文档为准

package/payload/skills/loom-merge-ready/references/shared/harness/execution-context.md

@@ -0,0 +1,71 @@
+# Execution Context
+
+本文件定义 Loom 当前最小执行上下文合同。
+
+本文件当前承接：
+
+- `EXT-0011`
+- `EXT-0038` 的每轮读取部分
+
+完整时序见 [execution-chain.md](execution-chain.md)。
+
+## 1. 能力定位
+
+执行上下文用于把单次执行轮次绑定到同一组稳定事实。
+
+它服务：
+
+- 开始执行前的读取
+- `checkpoint` 与 `resume` 的对齐
+- `handoff`、review 与放行前的事实对齐
+
+它不负责保存恢复内容本身；恢复内容由 [recovery-model.md](recovery-model.md) 承接。
+字段归属见 [fact-chain-contract.md](fact-chain-contract.md)。
+
+## 2. 最小语义集合
+
+每次正式执行前，至少要能确定以下语义：
+
+- 当前事项是谁
+- 当前事项属于哪条执行路径
+- 当前目标是什么
+- 当前范围边界是什么
+- 当前工作现场是什么
+- 当前恢复主入口是什么
+- 当前 checkpoint 阶段是什么
+- 当前验证入口是什么
+- 当前环境 lane 是什么
+
+Loom 固化的是语义集合，不固化字段名、编号格式或平台来源。
+这些语义本身属于派生读取，不是独立 authored 真相。
+
+## 3. 每轮读取最小事实集
+
+进入正式执行轮次前，默认先读取以下事实：
+
+- 当前 work item 或等价执行入口
+- 当前恢复主入口中的最近停点、下一步与阻断项
+- 当前 checkpoint 阶段与执行路径
+- 当前工作现场映射与最近 git 历史
+- 最近验证摘要与验证入口
+- 当前环境 lane 与最近稳定回退边界
+
+读取完成后，本轮执行应只声明一个清晰推进单元，不在同一轮并行吞入多个无关目标。
+
+## 4. 读取产物
+
+执行上下文的读取结果至少应能支持：
+
+- 声明本轮单一推进单元
+- 绑定唯一恢复主入口
+- 确认当前工作现场与验证入口
+- 判断是否仍处于已批准范围内
+- 判断本轮结束后是否进入 merge checkpoint
+
+## 5. 边界约束
+
+- 不得只靠 issue 编号、分支名或聊天上下文识别当前事项
+- 不得让执行、恢复、review 与 merge checkpoint 分别使用不同的上下文基线
+- 不得在执行上下文载体中并行 authored `goal`、`next_step` 或 `blockers`
+- 若某字段只是下游仓库局部便利，不得提升为 Loom 固定字段
+- 本文件不重复定义执行阶段顺序；阶段顺序以 [execution-chain.md](execution-chain.md) 为准