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

package/payload/plugin/loom/skills/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/plugin/loom/skills/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 收口的唯一主落点。

package/payload/plugin/loom/skills/shared/references/harness/host-issue-binding.md

@@ -0,0 +1,90 @@
+# Host Issue Binding
+
+本文件定义 Loom 当前消费 `active issue` 与宿主 branch、`git worktree`、PR、merge commit 之间绑定关系的最小合同。
+
+`active issue` 的主定义不在本文件。
+本文件只承接 Loom 为了执行、定位、放行与收口而必须消费的绑定事实。
+
+## 1. 能力定位
+
+本文件回答：
+
+- Loom 在执行侧最少需要读取哪些 host 绑定关系
+- 哪些绑定关系可用于判断实现是否已被 host merge 吸收
+- 单个 host PR 吸收多个 issue 时最少要能表达什么
+- 哪些结论仍不能直接等同于 `closed_out`
+
+## 2. 最小绑定对象
+
+当某正式事项进入实现与收口链路时，Loom 只消费以下绑定关系：
+
+- `active issue -> host branch`
+- `active issue -> git worktree`
+- `active issue -> host PR`
+- `host PR -> merge commit`
+
+这些绑定关系都属于 host control truth 或其派生读取结果。
+Loom 可以读取、校验、汇总并据此阻断，但不在仓内 authored 第二套主定义。
+
+## 3. 最小消费规则
+
+Loom 至少消费这些绑定关系用于以下动作：
+
+- `workspace locate` / recovery
+  - 判断当前执行现场是否仍服务同一正式事项
+- merge-ready / closeout check
+  - 判断实现载体、合并结果与主干事实是否一致
+- cleanup / retire
+  - 判断某 host branch 或 `git worktree` 是否仍被正式事项占用
+
+若绑定关系缺失、指向冲突或无法证明当前实现属于同一事项，结果必须返回 `block` 或显式 drift。
+
+## 4. 单 PR 吸收多事项
+
+单个 host PR 可以吸收多个 issue，但前提是这些 issue 的实现缺口确实都被该 PR 对应的 merge 结果覆盖。
+
+Loom 最少需要能机械回答两件事：
+
+- 这个 host PR 吸收了哪些 issue
+- 哪些相关 issue 仍保留独立剩余缺口，不能被一起判定为 `absorbed`
+
+因此：
+
+- PR body、closing rationale、merge commit 或等价宿主证据中，至少要有一处能稳定表达 issue 与 merged work 的对应关系
+- 若同一 PR 同时涉及 parent / child issue，默认只吸收被明确证明已覆盖的 issue，不得把整棵 tree 一并视为已吸收
+
+## 5. `absorbed`
+
+`absorbed` 是 Loom 在 harness 层定义的实现吸收结论。
+
+它只表示：
+
+- 某正式事项对应的实现已经通过 host merge 进入主干
+- 这一结论可以被宿主事实证明，而不是凭口头判断
+
+最小证明面至少包括：
+
+- 对应 host PR 已 merged
+- 对应 merge commit 可定位
+- merge commit 已被目标主干吸收
+
+`absorbed` 不等于：
+
+- `closed_out`
+- issue 已关闭
+- project 状态已同步完成
+- 恢复主入口或现场已清理完毕
+
+在 issue tree 中：
+
+- child issue
+  - 可以因自身缺口已被其他 merged work 覆盖而形成 `absorbed`
+- parent issue
+  - 可以消费 child 的 `absorbed` 结果，但不得仅因某个 child 被吸收就自动视为自身已 `closed_out`
+
+## 6. 边界约束
+
+- 本文件不主定义 `active issue` 的语义、生命周期或 authored 字段
+- 本文件不把 `workspace` 写成 `git worktree`
+- 本文件不要求每个宿主都必须暴露同名字段；只要求绑定关系可被稳定证明
+- 本文件不接管 branch、PR、`git worktree` 或 merge 的宿主生命周期动作

package/payload/plugin/loom/skills/shared/references/harness/host-lifecycle-boundary.md

@@ -0,0 +1,56 @@
+# Host Lifecycle Boundary
+
+本文件定义 Loom 与宿主平台在 `workspace`、branch、PR、git worktree 之间的生命周期边界。
+
+宿主动作入口、结果词表与 `fallback_to` 纪律的统一主落点见 [host-action-contract.md](./host-action-contract.md)。
+
+稳定命名与对象分类见 [../governance/host-object-taxonomy.md](../governance/host-object-taxonomy.md)。
+`active issue` 与 branch / `git worktree` / PR / merge commit 的绑定消费见 [host-issue-binding.md](./host-issue-binding.md)。
+
+## 1. 结论
+
+- `workspace`
+  - 属于 Loom execution object，进入 Loom 执行层
+- branch
+  - 属于 host control object，保留给宿主平台
+- PR
+  - 属于 host control object，保留给宿主平台
+- git worktree
+  - 属于 host control object，保留给宿主平台
+
+## 2. Loom 承接什么
+
+Loom 固定承接：
+
+- `workspace_entry` 对应的执行现场语义
+- 对 `active issue -> branch / git worktree / PR / merge commit` 绑定关系的读取与校验
+- recovery 与 checkpoint 对执行现场的绑定
+- branch / PR / worktree 是否已经影响执行正确性的边界检查结果
+- merge 前对 host merge 的统一放行判断
+- host merge 后实现是否已被 `absorbed` 的可证明结论
+
+## 3. Loom 不承接什么
+
+Loom 当前不提供以下原生命令：
+
+- branch create / rename / retire
+- PR create / update / merge / close
+- git worktree create / remove
+
+这些动作继续留给 Git / GitHub 或其他宿主平台。
+
+## 4. 边界读取入口
+
+- `python3 skills/shared/scripts/loom_flow.py host-lifecycle --target <repo> [--item <id>]`
+- `python3 skills/shared/scripts/loom_flow.py workspace create|locate|cleanup|retire --target <repo> [--item <id>]`
+- `python3 skills/shared/scripts/loom_flow.py purity-check --target <repo> [--item <id>]`
+
+更广的 host-facing actions，例如 `checkpoint merge`、`flow merge-ready`、`reconciliation audit|sync`、`closeout check|sync`，统一由 [host-action-contract.md](./host-action-contract.md) 索引。
+
+## 5. 边界约束
+
+- branch / PR purity 可以被 Loom 报告和消费，但不意味着 Loom 接管其生命周期
+- `workspace` 是执行现场抽象，不等于 git worktree
+- Loom 只消费 `active issue` 与宿主对象的绑定，不在这里主定义 `active issue`
+- 宿主对象的 UI、命名、按钮与策略不进入 Loom 默认内核
+- `host-lifecycle` 正常只读边界，不把宿主动作缺口伪装成 `fallback`；回退纪律由 [host-action-contract.md](./host-action-contract.md) 统一承接

package/payload/plugin/loom/skills/shared/references/harness/merge-checkpoint.md

@@ -0,0 +1,95 @@
+# Merge Checkpoint
+
+本文件定义 Loom 当前 merge checkpoint 的执行侧合同。
+
+本文件当前承接：
+
+- `#27` 的稳定落点
+- harness 侧放行承接语义
+
+## 1. 能力定位
+
+merge checkpoint 是执行侧的最终放行层。
+
+它只回答三类问题：
+
+- 当前 head 是否仍在已批准范围内
+- 当前执行材料是否已经完整到足以进入主干
+- 当前自动检查、验证摘要与运行证据是否支持放行
+
+它不承担第一次高质量语义判断，也不替代 governance 的前置准入与 reviewer 的审查职责。
+字段归属以 [fact-chain-contract.md](./fact-chain-contract.md) 为准。
+
+## 2. 放行前必读输入
+
+进入 merge checkpoint 前，至少应能读取以下事实：
+
+- 当前变更范围与目标
+- 关联事项、规格或等价正式工件
+- 自动检查结果
+- 正式 review record
+- 最近验证摘要
+- 运行时证据或 `not_applicable` 声明
+- 风险与回滚边界
+- 未决阻断项
+- 当前 head 是否仍在批准范围内
+
+这些事实通常分别来自：
+
+- [work-item-contract.md](./work-item-contract.md)
+- [recovery-model.md](./recovery-model.md)
+- [status-surface.md](./status-surface.md)
+- [review-execution.md](./review-execution.md)
+- [automation-frontload.md](./automation-frontload.md)
+
+其中：
+
+- 范围、目标、执行路径、验证入口定位
+  - 只能从 `work item` 读取
+- 当前 checkpoint、停点、下一步、阻断项、最近验证摘要、回退边界
+  - 只能从恢复主入口读取
+- 正式 review 结论
+  - 只能从 `work item.review_entry` 指向的 review record 读取
+  - 其中 `findings` 是 review/disposition 的权威字段；`blocking_issues` / `follow_ups` 只作兼容投影
+  - 即使 formal review 由默认 engine 产出，merge checkpoint 也只消费回写后的 review record，不直接读取 engine raw output 或 evidence 文件
+- 状态面
+  - 只允许作为派生汇总读面，不得替代上述主真相
+
+## 3. 唯一允许结果
+
+merge checkpoint 只允许输出以下三类结果：
+
+- `允许放行`
+  - 执行材料完整，自动检查与验证结果足以承接进入主干
+- `阻断待补`
+  - 仍有未补齐材料，但不必回退到更早 checkpoint 重做方向判断
+- `退回前序 checkpoint`
+  - 当前 head 已超出批准范围，或关键事实缺失到必须回退到前序 checkpoint 重新收口
+
+不允许输出模糊结果，例如“基本可以”“先合再说”“口头同意”。
+
+## 4. 回退承接
+
+当 merge checkpoint 给出非放行结果时，回退方向必须清晰：
+
+- 缺自动检查、结构检查或基础状态一致性
+  - 回到 [automation-frontload.md](./automation-frontload.md) 对应检查面
+- 缺验证摘要、运行证据或 `not_applicable` 声明
+  - 回到 [status-surface.md](./status-surface.md) 与实际验证入口
+- 缺 formal review、review stale 或 reviewer 明确要求回退
+  - 回到 [review-execution.md](./review-execution.md) 或 `build checkpoint`
+  - 若 review 之后只提交了 `review_entry`、recovery 主入口或状态面这类 Loom carrier 更新，不应误判成 stale
+- 缺停点、下一步、风险或回滚边界
+  - 回到 [recovery-model.md](./recovery-model.md)
+- head 已超出批准范围或事项边界失真
+  - 退回前序 checkpoint，重新做范围与方向收口
+
+## 5. 边界约束
+
+- merge checkpoint 消费 reviewer、自动检查和运行证据的结果，不重新发明第二套审查体系
+- merge checkpoint 只消费单一 review record，不为 findings / disposition 再引入第二 authored artifact
+- merge checkpoint 不直接消费 Codex output、prompt、logs 或其他 review evidence 文件
+- merge checkpoint 只回答“是否可进入 host merge”，进入主干后的 issue / project / main 收口由 [closeout-gate.md](./closeout-gate.md) 承接
+- merge checkpoint 不负责定义成熟度、关闭语义或事项是否值得做；这些属于 `governance/`
+- merge checkpoint 不得补读另一份 authored 状态摘要来替代恢复主入口
+- 本文件不规定宿主平台的按钮、合并策略或 CI 产品，只定义 Loom 必须承接的最小放行语义

package/payload/plugin/loom/skills/shared/references/harness/reconciliation-audit.md

@@ -0,0 +1,64 @@
+# Reconciliation Audit
+
+本文件定义 Loom 当前 `reconciliation audit` 的最小执行合同。
+
+本文件当前承接：
+
+- `#177`
+
+## 1. 能力定位
+
+`reconciliation audit` 用来回答三件事：
+
+- merged PR 是否已经吸收了仍然 open 的 issue
+- parent issue 是否仍与 child 的真实状态一致
+- issue / PR / project 的控制面状态是否已经漂移
+
+它只读 GitHub 控制面真相并输出审计结论，不做任何写回。
+
+## 2. 稳定入口
+
+- `python3 skills/shared/scripts/loom_flow.py reconciliation audit --target <repo> [--issue <n>] [--pr <n>] [--project <n>]`
+
+## 3. 稳定 findings
+
+第一版固定三类 finding：
+
+- `absorbed_but_open`
+  - merged PR 已进入主干，但 issue 仍 open
+- `parent_drift`
+  - parent issue 的开关状态与 child 的真实剩余缺口不一致
+- `project_drift`
+  - issue / PR 的 Project 状态与当前控制面结论不一致
+
+每条 finding 至少表达：
+
+- `kind`
+- `severity`
+- `subject`
+- `evidence`
+- `recommended_action`
+
+## 4. 结果语义
+
+`reconciliation audit` 只允许以下结果：
+
+- `pass`
+  - 没有 drift finding
+- `warn`
+  - 只有低严重度观察结论
+- `fix-needed`
+  - 已发现必须同步但尚未阻断的 drift
+- `block`
+  - 已发现不能继续视为 closeout-ready 的 drift，或必需输入缺失
+
+## 5. 边界约束
+
+- 本入口只生成审计结论，不执行 GitHub 修改
+- issue tree 关系通过 GitHub GraphQL 读取，不回写到仓内 docs
+- `absorbed` 的宿主证明继续由 [host-issue-binding.md](./host-issue-binding.md) 承接
+- 修复 drift 的正式入口由后续 reconciliation sync 承接，本文件不提前定义写路径
+
+## 6. 一句话结论
+
+Loom 先用 `reconciliation audit` 明确报出 absorbed-but-open、parent drift 和 project drift，再决定是否允许后续 closeout 或进入专门 sync。