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

package/payload/skills/loom-init/.loom-runtime/shared/references/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-init/.loom-runtime/shared/references/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-init/.loom-runtime/shared/references/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-init/.loom-runtime/shared/references/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) 为准

package/payload/skills/loom-init/.loom-runtime/shared/references/harness/fact-chain-contract.md

@@ -0,0 +1,160 @@
+# Fact Chain Contract
+
+本文件定义 Loom 当前完整执行内核的单一事实链合同。
+
+本文件当前承接：
+
+- `#35` 的稳定主落点
+
+执行链路顺序见 [execution-chain.md](./execution-chain.md)。
+
+## 1. 能力定位
+
+Loom 的执行真相只允许沿一条事实链流动：
+
+- `work item`
+  - 承接静态执行真相
+- 恢复主入口
+  - 承接动态执行真相
+- 状态面
+  - 只负责派生读取
+- merge checkpoint
+  - 只消费上述真相，不补读第二套状态来源
+
+本文件只定义 repo execution truth 内部的字段归属、派生关系与禁止事项。
+字段的最低表达要求，仍以各组件文档为准。
+
+跨 repo 与 GitHub 控制面的真相分层，见 [../governance/truth-and-sync-boundary.md](../governance/truth-and-sync-boundary.md)。
+
+## 2. 主真相载体
+
+### 2.1 `work item`
+
+`work item` 是静态执行真相的唯一主入口，至少承接：
+
+- `item_id`
+- `goal`
+- `scope`
+- `execution_path`
+- `associated_artifacts`
+- `workspace_entry`
+- `recovery_entry`
+- `review_entry`
+- `validation_entry`
+- `closing_condition`
+
+这些字段服务执行入口与范围识别，不随单轮推进频繁回写。
+
+### 2.2 恢复主入口
+
+恢复主入口是动态执行真相的唯一主入口，至少承接：
+
+- `item_id`
+- `current_checkpoint`
+- `current_stop`
+- `next_step`
+- `blockers`
+- `latest_validation_summary`
+- `recovery_boundary`
+- `current_lane`
+
+这些字段服务 `checkpoint`、`resume`、`handoff` 与 merge checkpoint 放行前的状态读取。
+
+### 2.3 `init-result`
+
+`init-result` 不是实时执行状态真相。
+
+它只允许承接：
+
+- 初始化路径
+- 装配强度
+- 恢复模式
+- carrier 定位信息
+- 统一读取入口
+
+它不得并行复制当前停点、下一步、阻断项、最近验证摘要或当前 checkpoint。
+
+## 2.4 标准事实模型与字段来源矩阵
+
+以下矩阵是 Loom 完整执行内核当前稳定的最小事实模型。
+
+| 字段 | 主来源 | 类型 | 允许消费方 |
+| --- | --- | --- | --- |
+| `item_id` | `work item` | authored | execution-context、status-surface、checkpoint、merge-checkpoint |
+| `goal` | `work item` | authored | execution-context、checkpoint、merge-checkpoint |
+| `scope` | `work item` | authored | execution-context、checkpoint、purity-check |
+| `execution_path` | `work item` | authored | execution-context、checkpoint |
+| `workspace_entry` | `work item` | authored | workspace-lifecycle、purity-check、status-surface |
+| `recovery_entry` | `work item` | authored | execution-context、workspace-lifecycle、checkpoint |
+| `review_entry` | `work item` | authored | review-execution、merge-checkpoint |
+| `validation_entry` | `work item` | authored | checkpoint、merge-checkpoint、verify |
+| `closing_condition` | `work item` | authored | checkpoint、merge-checkpoint |
+| `current_checkpoint` | recovery 主入口 | authored | status-surface、checkpoint、workspace-lifecycle |
+| `current_stop` | recovery 主入口 | authored | execution-context、checkpoint |
+| `next_step` | recovery 主入口 | authored | execution-context、status-surface、checkpoint |
+| `blockers` | recovery 主入口 | authored | execution-context、status-surface、checkpoint |
+| `latest_validation_summary` | recovery 主入口 | authored | status-surface、checkpoint、merge-checkpoint |
+| `recovery_boundary` | recovery 主入口 | authored | checkpoint、merge-checkpoint |
+| `current_lane` | recovery 主入口 | authored | status-surface、checkpoint、runtime-evidence |
+| `read_entry` | `init-result` | locator | verify、fact-chain、daily CLI |
+| `status_surface` locator | `init-result` + `work item` 派生 | derived | fact-chain、verify、checkpoint、workspace-lifecycle |
+| `runtime_evidence.*` | status-surface `Runtime Evidence` | derived | fact-chain、verify、merge-checkpoint、loom-check |
+
+约束：
+
+- `authored` 字段只能在主来源中维护。
+- `derived` 字段只能由读取脚本从主来源计算或映射，不得手工改写为第二真相。
+- `--activate` 只能显式切换当前 locator，不得通过 `resume`、`handoff` 或其他只读 flow 隐式改写活跃事项。
+
+## 3. 派生读面
+
+以下载体只允许派生读取，不允许独立 authored 字段覆盖主真相：
+
+- [execution-context.md](./execution-context.md)
+- [status-surface.md](./status-surface.md)
+- [merge-checkpoint.md](./merge-checkpoint.md)
+
+派生规则固定如下：
+
+- 静态执行事实
+  - 从 `work item` 派生
+- 动态执行事实
+  - 从恢复主入口派生
+- carrier 定位与读取入口
+  - 从 `init-result` 派生
+
+若派生读面展示的值与主真相不一致，应视为事实链断裂。
+
+## 4. 不允许的并行记账
+
+以下情况都属于并行真相，必须报错或阻断：
+
+- 在 `work item` 之外 authored 第二份 `goal`、`scope`、`execution_path`
+- 在恢复主入口之外 authored 第二份 `current_checkpoint`、`current_stop`、`next_step`、`blockers`
+- 让状态面手工维护与恢复主入口不同的 `next_step` 或验证摘要
+- 让 merge checkpoint 依赖另一份未声明主入口的状态摘要
+- 让 `init-result` 承载实时执行状态
+
+## 5. 最小消费规则
+
+任何机械入口在读取执行状态时，至少要遵守以下顺序：
+
+1. 先读 `init-result` 中的 carrier 定位
+2. 再读 `work item`
+3. 再读恢复主入口
+4. 需要状态汇总时，再读派生状态面
+
+不允许跳过主真相，直接把状态面或 merge checkpoint 输入当成 authored 真相。
+
+当前仓库中的统一读取入口包括：
+
+- `python3 loom-init/scripts/loom-init.py fact-chain --target <repo>`
+- `python3 shared/scripts/loom_flow.py fact-chain --target <repo> [--item <id>]`
+
+## 6. 边界约束
+
+- Loom 固化的是字段归属与派生关系，不固化具体文件名或宿主平台字段名
+- 若某仓库还停留在 `checkpoint-lite`，也必须明确唯一动态事实承载面
+- 本文件不重复定义字段如何呈现在 Markdown、JSON 或其他载体；只定义谁拥有 authored 权限
+- issue / project / PR / checks 等 host control truth 不在本文件内定义 authored 归属
+- `active issue` 与 branch / `git worktree` / PR / merge commit 的绑定关系只可被本事实链消费，不进入仓内 authored 真相；其最小绑定合同见 [host-issue-binding.md](./host-issue-binding.md)

package/payload/skills/loom-init/.loom-runtime/shared/references/harness/host-action-contract.md

@@ -0,0 +1,128 @@
+# Host Action Contract
+
+本文件定义 Loom 当前已冻结的宿主动作合同。
+
+本文件当前承接：
+
+- `#167`
+
+它只收口三件事：
+
+- 哪些现有入口属于 Loom 的宿主动作面
+- 每类入口允许返回什么结果，以及 `fallback_to` 指向哪里
+- Loom 与宿主平台各自拥有哪部分动作，不新增新的宿主产品或自动化层
+
+## 1. 能力定位
+
+Loom 的宿主动作面不是新的 umbrella CLI，也不是宿主平台替身。
+
+它是 Loom 对现有 host-facing actions 的统一合同层，用来把以下能力收成同一组结果语义：
+
+- 宿主对象边界读取
+- 宿主 gate / required checks / merge controls 的放行消费
+- post-merge 的 drift 审计与控制面对齐
+
+具体专题落点仍保持拆分：
+
+- 对象 ownership 边界见 [host-lifecycle-boundary.md](./host-lifecycle-boundary.md)
+- merge 前放行细节见 [merge-checkpoint.md](./merge-checkpoint.md)
+- 自动检查与 required checks 读面见 [automation-frontload.md](./automation-frontload.md)
+- drift taxonomy 见 [reconciliation-audit.md](./reconciliation-audit.md)
+- closeout 检查与 sync 顺序见 [closeout-gate.md](./closeout-gate.md)
+
+## 2. 覆盖范围
+
+当前冻结的宿主动作只包括现有入口：
+
+| 类别 | 稳定入口 | 宿主写入 | 说明 |
+| --- | --- | --- | --- |
+| boundary read | `python3 skills/shared/scripts/loom_flow.py host-lifecycle --target <repo> [--item <id>]` | 否 | 读取 workspace / branch / PR / git worktree 的 ownership boundary |
+| merge control read | `python3 skills/shared/scripts/loom_flow.py checkpoint merge --target <repo> [--item <id>]` | 否 | 读取 Loom 对 required checks / validation / review / risk rollback 的放行结论 |
+| merge control summary | `python3 skills/loom-merge-ready/scripts/loom-merge-ready.py flow merge-ready --target <repo> [--item <id>]` | 否 | 汇总进入 host merge 前的统一放行摘要 |
+| drift audit | `python3 skills/shared/scripts/loom_flow.py reconciliation audit --target <repo> [--issue <n>] [--pr <n>] [--project <n>]` | 否 | 只读 issue / PR / project 控制面并输出 drift findings |
+| control-plane sync | `python3 skills/shared/scripts/loom_flow.py reconciliation sync --target <repo> [--issue <n>] [--pr <n>] [--project <n>] [--comment-file <path>] [--dry-run]` | 是 | 只修机械可证明的 reconciliation drift |
+| closeout check | `python3 skills/shared/scripts/loom_flow.py closeout check --target <repo> [--issue <n>] [--pr <n>] [--project <n>]` | 否 | 校验 main、issue、PR、project 与仓内结果是否一致 |
+| closeout sync | `python3 skills/shared/scripts/loom_flow.py closeout sync --target <repo> [--issue <n>] [--pr <n>] [--project <n>]` | 是 | 在可同步条件下继续做 closeout 控制面对齐 |
+
+以下内容继续明确排除在 Loom 宿主动作面之外：
+
+- branch create / rename / retire
+- PR create / update / merge / close
+- git worktree create / remove
+- CI 产品实现、required checks 配置界面、merge button 与 ruleset 细节
+
+## 3. 统一输出面
+
+宿主动作沿用 Loom 既有 JSON 输出骨架，不新增第二套结果对象：
+
+- `command`
+- `operation`（若该入口有子动作）
+- `result`
+- `summary`
+- `missing_inputs`
+- `fallback_to`
+
+某些入口会额外带上专题字段，例如：
+
+- `host-lifecycle.objects`
+- `reconciliation.findings`
+- `closeout.reconciliation`
+- `flow merge-ready` / `checkpoint merge` 的放行细节
+
+这些专题字段可以扩展，但不得绕过本文件定义的结果纪律。
+
+## 4. 结果与 `fallback_to` 纪律
+
+宿主动作当前冻结以下结果集合：
+
+| 入口 | 允许结果 | `fallback_to` 纪律 |
+| --- | --- | --- |
+| `host-lifecycle` | `pass` / `block` | 只在事实链无法读取时回到 `admission`；正常边界读取不产生 `fallback` 结果 |
+| `checkpoint merge` | `pass` / `block` / `fallback` | `fallback_to` 只能指向 Loom 内部 checkpoint，不得指向宿主控制面动作 |
+| `flow merge-ready` | `pass` / `block` / `fallback` | `fallback_to` 只能指向 Loom 内部 checkpoint 摘要，不得把 host merge 伪装成回退目标 |
+| `reconciliation audit` | `pass` / `warn` / `fix-needed` / `block` | 非 `pass` 时只允许 `manual-reconciliation` 或 `null`；它负责报 drift，不把 drift 伪装成 `fallback` |
+| `reconciliation sync` | `pass` / `block` | `block` 时只允许指向 `manual-reconciliation` 或 `null`；`--dry-run` 也不得把未解决 drift 伪装成通过 |
+| `closeout check` | `pass` / `block` | 普通 closeout 缺口指向 `merge`；若 reconciliation 为 `fix-needed` 必须指向 `reconciliation-sync`；若 reconciliation 为 `block` 必须指向 `manual-reconciliation` |
+| `closeout sync` | `pass` / `block` | 不得绕过 reconciliation；若同步前置未满足或同步后仍未对齐，指向 `reconciliation-sync` 或 `manual-reconciliation`；其他 closeout 缺口继续指向 `merge` |
+
+补充纪律：
+
+- `fallback` 结果只用于 Loom 内部前序 checkpoint / flow 的回退，不用于 closeout 或 reconciliation
+- `warn` 与 `fix-needed` 只作为 `reconciliation audit` 的顶层结果存在
+- `fallback_to` 是下一步去向，不等价于把 `result` 改写成 `fallback`
+- 宿主动作不得把 branch / PR / worktree 的真实生命周期命令当作 `fallback_to`
+
+## 5. Ownership Boundary
+
+Loom 当前承接：
+
+- workspace execution semantics
+- required checks / validation / review / risk rollback 的放行消费
+- 对宿主对象绑定、drift 与 absorbed 结论的读取和校验
+- closeout 前后的控制面对齐判断
+
+宿主平台当前承接：
+
+- branch / PR / git worktree 的真实生命周期动作
+- 实际 merge / close / status UI 与策略
+- CI 产品实现与 required checks 配置机制
+
+因此，Loom 可以报告、消费、阻断或要求回退，但不会在这里扩展成新的宿主自动化产品。
+
+## 6. 专题文件分工
+
+- [host-lifecycle-boundary.md](./host-lifecycle-boundary.md)
+  - 只定义 workspace、branch、PR、git worktree 的 ownership boundary
+- [merge-checkpoint.md](./merge-checkpoint.md)
+  - 只定义 merge control 的执行侧放行输入、结果与回退承接
+- [automation-frontload.md](./automation-frontload.md)
+  - 只定义适合前置机械化的 checks surface
+- [reconciliation-audit.md](./reconciliation-audit.md)
+  - 只定义 drift finding taxonomy 与 audit 结果语义
+- [closeout-gate.md](./closeout-gate.md)
+  - 只定义 closeout check / sync 的最小链路与 fail-closed 顺序
+
+这些宿主动作在 installed-skills / `.loom/bin` carrier 下，都必须先消费 `runtime-state`。
+若 runtime/layout/resources 漂移，入口必须直接 `block`，不得继续读取或写入 GitHub 控制面。
+
+这些文件共同表达一条统一宿主动作链路，但本文件是结果词表、`fallback_to` 与 ownership 收口的唯一主落点。