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

package/payload/skills/loom-review/.loom-runtime/loom-review/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: loom-review
+description: 负责正式 review 执行层。Use when Codex needs to run semantic review after pre-review and produce a formal review verdict without replacing merge-ready.
+---
+
+# Loom Review
+
+这个 skill 承接正式 review 执行层。
+
+它不等于 `loom-pre-review`，也不替代 `loom-merge-ready`：
+
+- `loom-pre-review` 负责进入 review 前的统一机械预检
+- `loom-review` 负责执行正式语义审查并产出审查结论
+- `loom-merge-ready` 负责 merge 前统一放行聚合
+
+对执行者来说，正式 review 的首层入口仍是 `loom-review` 这个场景 skill。repo-local 自动化、验证、调试和宿主编排可以统一调用 repo-local `loom CLI`，但这不替代场景 skill 的用户入口，也不改变 review / merge-ready 的边界。
+
+## 1. 使用时机
+
+当任务满足以下任一条件时，进入 `loom-review`：
+
+- 明确要求正式 review
+- 明确要求语义审查或审查结论
+- 明确要求输出 findings、风险和是否通过的判断
+- 明确要求在 pre-review 通过后进入审查执行
+
+如果任务其实是在做初始化、恢复执行、review 前预检、handoff、retire 或 merge-ready，应回到 root route matrix，让 `loom-init` 路由到对应场景：
+
+- [../route-matrix.md](../route-matrix.md)
+
+## 2. 固定入口
+
+统一入口固定为：
+
+- `loom flow review --target <repo> [--item <id>]`
+- `loom review run --target <repo> [--item <id>]`
+- `loom review record --target <repo> [--item <id>] --decision <allow|block|fallback> --kind <general_review|code_review|spec_review> --summary <text> --reviewer <id>`
+
+补充约束：
+
+- 若需要写入结构化 findings / disposition，使用 `--findings-file <path>`
+- `--blocking-issue` / `--follow-up` 仅保留兼容 authored 入口，不得与 `--findings-file` 混用
+- 无论通过哪种入口，最终都只允许写回单一 `review_entry` 指向的 review record
+
+这个 skill 先用 `flow review` 读取正式 review 的机械基线，再用 `review run` 触发默认 Codex reviewer 并生成 Loom-normalized findings，最后用 `review record` 把审查结论写成可消费载体。
+
+安装态或 repo-local 开发态可以把这些 `loom ...` 动作映射到底层 `scripts/...` 或共享 runtime carrier；但 `loom-review` 自身的场景合同、进入时机和输出责任保持不变。
+
+## 3. 固定编排
+
+`loom-review` 固定按以下顺序编排：
+
+1. 运行 `flow review`，确认当前事项是否具备进入正式审查的最小条件
+2. 若 `flow review` 非 `pass`，直接返回 `block` 或 `fallback`，不伪造审查结论
+3. 运行 `review run`，用默认 Codex adapter 执行 formal review，并把 raw output 收敛为 Loom evidence 与 normalized findings
+4. 若 `review run` fail-closed，显式回到 manual review 写回同一 `review record`
+5. 用 `review record` 写入正式 review 结论，让 merge checkpoint 可机械消费
+
+这个 skill 不做以下事情：
+
+- 不替代 pre-review 预检
+- 不替代 merge-ready 放行判断
+- 不直接执行 merge 或平台动作
+- 不回写 recovery entry、status surface 或其他 authored 真相载体
+- 不跳过 review record，直接把口头结论交给 merge checkpoint
+- 不把 engine raw output 升级成第二 authored truth
+
+## 4. 输出要求
+
+输出必须是统一 review 摘要 JSON，至少要让执行者能读出：
+
+- 当前事项是什么
+- review 机械基线结果
+- build checkpoint 是否允许进入正式审查
+- review artifact 的定位与已记录结论
+- 默认 engine 的执行结果、evidence 定位与 fail-closed 原因
+- manual review 的回退写回入口
+- review record 中的权威 findings / disposition 摘要
+- 审查结论（`allow` / `block` / `fallback`）
+- 若当前不能继续，应回退到哪里
+
+## 5. 完成标准
+
+只有当以下条件同时满足时，`loom-review` 才算完成：
+
+- 显式调用 `loom-review` 与 root 隐式路由都能稳定命中
+- 审查执行严格以 `flow review -> review run -> review record` 为前置，而不是绕过预检
+- 输出 JSON 与 review record 都能直接支撑 merge checkpoint 消费
+- skill 不创建第二 authored 真相源，不替代 merge-ready 聚合
+- review/disposition contract 只扩展 review record 内部字段，不新增第二 artifact 或新状态机
+
+输入信号与输出合同见：
+
+- [references/input-signals.md](./references/input-signals.md)
+- [references/output-contract.md](./references/output-contract.md)

package/payload/skills/loom-review/.loom-runtime/loom-review/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Loom Review"
+  short_description: "正式 review 语义审查入口"
+  default_prompt: "先运行 Loom 的 flow review 读取正式审查基线；若基线通过，再运行 review run 触发默认 Codex reviewer 并产出结构化 findings，最后用 review record 写入单一 review record。"

package/payload/skills/loom-review/.loom-runtime/loom-review/contract.json

@@ -0,0 +1,49 @@
+{
+  "contract_version": "1.4.0",
+  "description": "Run the formal semantic review layer on top of pre-review and return authoritative review findings plus a verdict without replacing merge-ready.",
+  "display_name": "Loom Review",
+  "entrypoint": {
+    "adapter_metadata": "agents/openai.yaml",
+    "orchestration_cli": "scripts/loom-review.py",
+    "skill_markdown": "SKILL.md"
+  },
+  "id": "loom-review",
+  "input_contract": {
+    "reference": "references/input-signals.md",
+    "required_fields": [
+      "target_repository",
+      "current_item_or_active_item",
+      "review_intent"
+    ]
+  },
+  "installation": {
+    "layout_manifest": "../install-layout.json",
+    "registry": "../registry.json",
+    "upgrade_contract": "../upgrade-contract.json"
+  },
+  "output_contract": {
+    "reference": "references/output-contract.md",
+    "required_sections": [
+      "item",
+      "result",
+      "summary",
+      "missing_inputs",
+      "fallback_to",
+      "runtime_state",
+      "steps",
+      "state_check",
+      "runtime_evidence",
+      "build_checkpoint",
+      "review",
+      "engine",
+      "manual_review",
+      "current_checkpoint"
+    ]
+  },
+  "role": "scenario/review",
+  "root_entry": true,
+  "routing": {
+    "explicit_name": "loom-review",
+    "reference": "../route-matrix.md"
+  }
+}

package/payload/skills/loom-review/.loom-runtime/loom-review/references/input-signals.md

@@ -0,0 +1,15 @@
+# Loom Review Input Signals
+
+当任务满足以下任一信号时，进入 `loom-review`：
+
+- 正式 review
+- 语义审查
+- 输出审查结论
+- 输出 findings 和风险等级
+- pre-review 通过后进入审查执行
+
+最小输入：
+
+- 目标仓库
+- 当前事项编号，或允许从事实链定位活跃事项
+- review 意图与关注面（例如正确性、回归风险、合同一致性）

package/payload/skills/loom-review/.loom-runtime/loom-review/references/output-contract.md

@@ -0,0 +1,57 @@
+# Loom Review Output Contract
+
+输出固定为正式 review 摘要 JSON，至少需要给出：
+
+- `item`
+  - 当前事项编号、目标、范围、执行路径
+- `result`
+  - `pass`、`block` 或 `fallback`
+- `summary`
+  - 当前是否已具备正式 review 条件的单句结论
+- `missing_inputs`
+  - 当前阻断正式 review 的缺口；无阻断时为空数组
+- `fallback_to`
+  - 若当前不能继续正式 review，应回退到哪个 checkpoint；无回退时为 `null`
+- `runtime_state`
+  - 当前 Loom 入口自己的 scene / carrier 判定，以及 fail-closed 原因
+- `steps`
+  - 固定按 `runtime-state -> fact-chain -> state-check -> runtime-evidence -> checkpoint-build -> review-entry` 顺序列出
+- `state_check`
+  - 活跃状态、checkpoint 完整性与范围信号
+- `runtime_evidence`
+  - 当前 review 可读的运行时证据入口
+- `build_checkpoint`
+  - build checkpoint 的结果、摘要、缺失输入与回退语义
+- `review`
+  - 唯一 `review_entry` review record 的定位、已记录结论，以及权威 findings / disposition 摘要
+- `engine`
+  - 默认 reviewer adapter、evidence 路径、运行结果与 fail-closed 原因
+- `manual_review`
+  - engine block 时如何继续写回同一 `review record`
+- `current_checkpoint`
+  - 当前 recovery checkpoint 的原始值与归一化值
+
+`review` 段至少应让执行者读出：
+
+- 读取的是哪一个 `review_entry`
+- review record 中的 `decision`
+- review record 中的权威 `findings`
+- 每条 finding 的 `id`、`severity`、`rebuttal` 与 `disposition`
+- `blocking_issues` / `follow_ups` 只是兼容字段，而不是第二份审查工件
+
+`engine` 段至少应让执行者读出：
+
+- 当前默认 engine 是什么
+- 当前 adapter 标识是什么
+- 当前结果是 `pass`、`block` 还是 `not_run`
+- 若 fail-closed，稳定 failure reason 是什么
+- raw result、normalized findings、prompt 与元数据 evidence 在哪里
+
+`manual_review` 段至少应让执行者读出：
+
+- engine block 时仍应写回哪一个 `review record`
+- 推荐沿用哪个 `kind`
+- 若已有 normalized findings，应从哪个 `findings_file` 继续
+- 最小 `review record` 写回命令骨架是什么
+
+这个 skill 负责正式 review 执行层，不替代 `loom-pre-review` 的机械预检，也不替代 `loom-merge-ready` 的 merge 前聚合放行判断。

package/payload/skills/loom-review/.loom-runtime/loom-review/scripts/loom-review.py

@@ -0,0 +1,14 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import os
+import runpy
+import sys
+from pathlib import Path
+
+SCRIPT_PATH = Path(__file__).resolve()
+SKILLS_ROOT = SCRIPT_PATH.parents[2]
+
+os.environ.setdefault("LOOM_INSTALLED_SKILLS_ROOT", str(SKILLS_ROOT))
+sys.path.insert(0, str(SKILLS_ROOT / "shared/scripts"))
+runpy.run_path(SKILLS_ROOT / "shared/scripts/loom_flow.py", run_name="__main__")

package/payload/skills/loom-review/.loom-runtime/registry.json

@@ -0,0 +1,15 @@
+{
+  "entries": [
+    {
+      "contract_version": "1.4.0",
+      "executable": "loom-review/scripts/loom-review.py",
+      "id": "loom-review",
+      "manifest": "loom-review/contract.json",
+      "role": "scenario/review"
+    }
+  ],
+  "install_layout": "install-layout.json",
+  "registry_version": "1.3.0",
+  "root_entry": "loom-review",
+  "upgrade_contract": "upgrade-contract.json"
+}

package/payload/skills/loom-review/.loom-runtime/route-matrix.md

@@ -0,0 +1,63 @@
+# Skills Route Matrix
+
+本文定义 `loom-init` 作为 root entry 时的显式 / 隐式路由矩阵。
+
+## 1. 优先级
+
+1. 显式 skill 名称调用优先
+2. 若无显式 skill，则按任务信号做隐式路由
+3. 若无法稳定判断，回退到 `loom-init`，输出最小补充信号
+
+## 2. 场景矩阵
+
+| 场景 | 任务信号 | 目标 skill | 依赖 CLI |
+| --- | --- | --- | --- |
+| 初始化 / retrofit | 初始化、新项目接入、既有仓库 retrofit、引入 Loom | `loom-adopt` | `loom-init/scripts/loom-init.py bootstrap\|verify\|fact-chain` |
+| 恢复执行 | 接手当前事项、恢复上下文、问下一步、继续推进 | `loom-resume` | `loom-resume/scripts/loom-resume.py flow resume` |
+| review 前统一检查 | review 前检查、进入 review、确认是否可 review | `loom-pre-review` | `loom-pre-review/scripts/loom-pre-review.py flow pre-review` |
+| 正式 review | 正式 review、语义审查、输出 review 结论、code review、spec review | `loom-review` | `loom-review/scripts/loom-review.py flow review` + `shared/scripts/loom_flow.py review run` + `loom-review/scripts/loom-review.py review record` |
+| 交接 | 交接、回写停点、移交当前事项 | `loom-handoff` | `loom-handoff/scripts/loom-handoff.py flow handoff` |
+| 清理 / retire | 清理现场、退休现场、结束当前事项现场 | `loom-retire` | `loom-retire/scripts/loom-retire.py workspace cleanup\|retire` |
+| merge 前放行 | merge-ready、最终放行前预检、确认是否可合并 | `loom-merge-ready` | `loom-merge-ready/scripts/loom-merge-ready.py flow merge-ready` |
+
+## 3. `governance_surface` 公共合同
+
+以下三类入口对外暴露的公共治理读面固定命名为 `governance_surface`：
+
+- `loom-init`
+  - 输出初始化后的治理承接面，说明 Issue、PR、规则、规格、执行工件分别由谁承接
+- `loom-adopt`
+  - 不另造新合同，直接复用 `loom-init` 的 `governance_surface`
+- `loom-resume`
+  - 输出当前事项的治理承接面摘要，但不回写或复制 authored 真相
+
+稳定约束：
+
+- 只读，不新增第二套治理状态源
+- 字段名保持：
+  - `repository_mode`
+  - `loom_state`
+  - `carrier_summary`
+  - `execution_entry`
+  - `validation_entry`
+  - `review_merge_surface`
+  - `github_control_plane`
+  - `summary`
+  - `missing_inputs`
+- `carrier_summary` 子项固定为 `work_item`、`recovery`、`review`、`status_surface`、`spec_path`、`plan_path`
+- 只回答 locator 与职责边界，不复制实时停点、下一步、阻断项、验证摘要
+
+## 4. fallback 语义
+
+出现以下任一情况时，root skill 不做猜测，直接回退到 `loom-init`：
+
+- 没有明确 skill 名称，也没有稳定任务信号
+- 同时命中多个场景，且无法根据任务语义收敛为单一路由
+- 目标仓库或事项标识缺失，无法稳定执行下游入口
+
+回退输出必须至少包含：
+
+- `selected_skill: "loom-init"`
+- `result: "fallback"`
+- `missing_inputs`
+- `fallback_to: "loom-init"`

package/payload/skills/loom-review/.loom-runtime/shared/assets/github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,22 @@
+## Summary
+
+- Problem:
+- Scope:
+
+## Validation
+
+- [ ] Verified locally
+- [ ] Verified by automation
+- [ ] Not applicable
+
+Validation details:
+
+## Risks And Follow-ups
+
+- Risks:
+- Follow-ups:
+
+## Related Work
+
+- Issue:
+- Spec / plan:

package/payload/skills/loom-review/.loom-runtime/shared/assets/review/loom-review-result-schema.json

@@ -0,0 +1,93 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "decision",
+    "summary",
+    "findings"
+  ],
+  "properties": {
+    "decision": {
+      "type": "string",
+      "enum": [
+        "allow",
+        "block",
+        "fallback"
+      ]
+    },
+    "summary": {
+      "type": "string",
+      "minLength": 1
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "summary",
+          "severity",
+          "rebuttal",
+          "disposition"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "summary": {
+            "type": "string",
+            "minLength": 1
+          },
+          "severity": {
+            "type": "string",
+            "enum": [
+              "warn",
+              "block"
+            ]
+          },
+          "rebuttal": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "minLength": 1
+          },
+          "disposition": {
+            "type": [
+              "object",
+              "null"
+            ],
+            "required": [
+              "status",
+              "summary"
+            ],
+            "properties": {
+              "status": {
+                "type": "string",
+                "enum": [
+                  "accepted",
+                  "rejected",
+                  "deferred"
+                ]
+              },
+              "summary": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "additionalProperties": true
+          },
+          "details": {
+            "type": "string"
+          },
+          "code_location": {
+            "type": "object"
+          }
+        },
+        "additionalProperties": true
+      }
+    }
+  }
+}

package/payload/skills/loom-review/.loom-runtime/shared/assets/templates/scaffold/plan.md

@@ -0,0 +1,51 @@
+# Plan
+
+## Implementation Goal
+
+- What will be delivered in this change set?
+- What is explicitly deferred?
+
+## Phases
+
+### Phase 1
+
+- Objective:
+- Deliverable:
+- Exit condition:
+
+### Phase 2
+
+- Objective:
+- Deliverable:
+- Exit condition:
+
+## Constraints
+
+- Architectural or governance constraints:
+- Workspace / rollout constraints:
+- Purity or scope constraints:
+
+## Validation
+
+- Automated checks:
+- Manual checks:
+- Runtime evidence:
+
+## Test Strategy
+
+- TDD or test-first expectation:
+- Regression coverage to add or preserve:
+- Cases that are intentionally not automated:
+
+## Dependencies
+
+- Blocking inputs:
+- Required coordination:
+- Rollback boundary:
+
+## Ready For Implementation
+
+- [ ] Spec is stable enough to implement
+- [ ] Scope and non-goals are clear
+- [ ] Validation path is defined
+- [ ] Risks and dependencies are explicit

package/payload/skills/loom-review/.loom-runtime/shared/assets/templates/scaffold/spec.md

@@ -0,0 +1,48 @@
+# Spec
+
+## Goal
+
+- What problem does this change solve?
+- What user or system outcome must become true?
+
+## Scope
+
+- In scope:
+- Out of scope:
+
+## Key Scenarios
+
+### Scenario 1
+
+Given
+- a clear starting state
+
+When
+- the actor performs the target action
+
+Then
+- the expected observable outcome happens
+
+### Scenario 2
+
+Given
+- an important variant or edge condition
+
+When
+- the relevant action occurs
+
+Then
+- the system still behaves within the intended boundary
+
+## Exceptions And Boundaries
+
+- Failure modes:
+- Operational boundaries:
+- Rollback or fallback expectations:
+
+## Acceptance Criteria
+
+- [ ] Target outcome is observable
+- [ ] Key scenarios are covered
+- [ ] Important boundary behavior is defined
+- [ ] Validation evidence is identified

package/payload/skills/loom-review/.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-review/.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
+- 已出现共享契约、共享数据模型或高风险核心抽象
+- 已出现多个运行入口、多个状态入口或明显恢复痛点