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

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

@@ -0,0 +1,208 @@
+# Output Contract
+
+使用本文件约束 `loom-init` 的输出。
+
+输出目标不是给出泛建议，而是形成可继续执行的初始化产物模型。
+
+## 必须输出的区块
+
+### 1. 项目判断
+
+必须说明：
+
+- 初始化场景：
+  - `新项目`
+  - `小型既有仓库`
+  - `复杂既有仓库`
+- 装配强度：
+  - `轻量`
+  - `标准`
+  - `强化`
+- 当前最主要的结构性问题是什么
+- 为什么推荐这条路径，而不是另外两条路径
+
+### 2. 推荐装配
+
+至少列出：
+
+- 本轮启用的能力清单
+- 每项能力分别映射到哪些 `governance`、`harness`、`templates`、`adoption` 规则
+- 这次采用的是最小装配、轻量 retrofit 还是更完整装配
+- 若命中成熟治理重仓 attach path，必须显式写出 `recommended_adoption.path = deep-existing-repo`
+- 接入方式是根级重写还是 `repo companion`（历史表述：`companion docs`）
+- 恢复形态是 `checkpoint-lite` 还是标准恢复形态
+
+### 3. 暂不引入
+
+必须显式写出：
+
+- 当前不引入哪些 Loom 能力
+- 不引入的原因是什么
+- 这些能力未来的升级触发条件是什么
+
+### 4. 首批工件
+
+至少说明：
+
+- 初始能力清单的承载位置
+- 首批 work item 或等价事项清单的承载位置
+- 恢复主入口是什么
+- progress / checkpoint 载体是什么
+- 验证入口是什么
+- 状态读取入口是什么
+- `Runtime Evidence` 区块的落位方式是什么，且至少覆盖：
+  - `Run Entry`
+  - `Logs Entry`
+  - `Diagnostics Entry`
+  - `Verification Entry`
+  - `Lane Entry`
+- 初始 clean state 的定义是什么
+- 首个稳定提交或等价回退边界是什么
+- 事实链 carrier 如何定位
+- 统一事实链读取入口是什么
+- `governance_surface` 是什么，并至少稳定给出：
+  - `repository_mode`
+  - `loom_state`
+  - `carrier_summary`
+    - `work_item`
+    - `recovery`
+    - `review`
+    - `status_surface`
+    - `spec_path`
+    - `plan_path`
+  - `execution_entry`
+  - `validation_entry`
+  - `review_merge_surface`
+    - `pr_template`
+    - `validation_surface`
+    - `merge_surface`
+  - `github_control_plane`
+    - `repository`
+    - `default_branch`
+    - `branch_protection`
+    - `required_checks`
+    - `pr_reviews`
+  - `repo_interface`
+    - `availability`
+    - `manifest`
+    - `companion_entry`
+    - `repo_specific_requirements`
+    - `specialized_gates`
+    - `summary`
+    - `missing_inputs`
+  - `summary`
+  - `missing_inputs`
+
+若本轮不装配标准恢复或状态面，也必须写清现有载体如何承接这些职责。
+
+若本轮走 `deep-existing-repo`，还必须显式写出：
+
+- attach-only 必备工件是什么
+- 哪些 repo-native carriers 继续保留
+- 哪些 Loom-owned carriers 本轮不会生成
+
+`init-result` 只允许承接 locator-only 信息，不并行复制实时停点、下一步、阻断项或最近验证摘要。
+
+`Runtime Evidence` 的五个字段必须逐项给出 locator 或 `not_applicable`，不得留空；若使用 `not_applicable`，必须给出可复核原因。
+
+### 4.1 `runtime_state`
+
+初始化输出还必须显式给出当前 Loom 入口自己的 `runtime_state`，至少包含：
+
+- `scene`
+  - `repo-local-demo | installed-runtime | upgrade-rehearsal`
+- `carrier`
+  - `repo-local-wrapper | installed-skills-root | bootstrapped-target-runtime`
+- `failure_reason`
+  - 当前无法继续运行时的稳定阻断原因数组
+- `evidence`
+  - 判定依据来自 `install-layout.json`、`upgrade-contract.json`、bootstrap manifest 或当前入口解析结果
+
+这里的 `runtime_state` 只回答 Loom 入口自身处于什么安装/运行场景，不是 `governance_surface.loom_state` 的别名。
+`governance_surface.loom_state` 回答的是仓库 Loom 装配程度；`runtime_state` 回答的是当前入口能否被视为 installed runtime 并继续运行。
+
+### 5. 首批事项
+
+至少拆出：
+
+- 每个事项的：
+  - 事项标识
+  - 目标
+  - 范围
+  - 执行路径
+  - 关联工件
+  - 关闭条件
+- 恢复主入口与工作现场入口
+- 若事项已进入轻量跨轮承接，必须说明谁负责回写停点、下一步、阻断项与最近验证摘要
+
+## `governance_surface` 的公共约束
+
+`governance_surface` 是 `loom-init`、`loom-adopt` 与 `loom-resume` 共享的稳定公共读面。
+
+它只回答“当前仓库属于哪种执行模式、Loom 装配到什么程度、治理载体和宿主控制面分别位于哪里”，不复制实时 authored 状态。
+
+固定要求：
+
+- 字段命名保持 `governance_surface`
+- 字段命名保持：
+  - `repository_mode`
+  - `loom_state`
+  - `carrier_summary`
+  - `execution_entry`
+  - `validation_entry`
+  - `review_merge_surface`
+  - `github_control_plane`
+  - `repo_interface`
+  - `summary`
+  - `missing_inputs`
+- `carrier_summary` 的 6 个子项固定为：
+  - `work_item`
+  - `recovery`
+  - `review`
+  - `status_surface`
+  - `spec_path`
+  - `plan_path`
+- `carrier_summary` 每个子项固定为 `{status, locator, source}`，`status` 只允许 `present | missing | planned`
+- `github_control_plane` 缺失时允许用 `unknown`，但不得猜测
+- `repo_interface` 只允许承接 `repo companion` 的 locator 和机读 requirements / gates 摘要，不得复制 authored state
+- `repo_interface.availability` 只允许：
+  - `absent`
+  - `companion_docs_only`
+  - `incomplete`
+  - `present`
+- `repo_interface.manifest`、`repo_interface.companion_entry`、`repo_interface.repo_specific_requirements`、`repo_interface.specialized_gates` 固定为 `{status, locator, source}`
+
+禁止事项：
+
+- 把 `governance_surface` 写成第二套事项进度真相
+- 改名或拆出并行的治理读面字段
+- 在 `governance_surface` 中并行复制实时停点、下一步、阻断项或验证摘要
+- 用 `governance_surface` 覆盖 `work item`、恢复入口、PR 或规则文档的 authored 事实
+- 把 `repo_interface` 变成第二套 review / recovery / closeout authored state
+
+### 6. 验证与收口
+
+至少说明：
+
+- 如何验证初始化输出已经可直接承接执行
+- 三个 checkpoint 的承接关系是什么（固定命名为 `admission -> build -> merge`，不再使用 `commit checkpoint` 命名）
+- 什么状态算“说明已清楚”
+- 什么状态算“已进入主干并收口”
+- 何时 issue 可以关闭
+
+## 初始化产物模型的最低要求
+
+无论场景轻重，初始化输出都必须让后续执行者能直接回答以下问题：
+
+- 当前属于哪条初始化路径
+- 当前启用了哪些能力，暂不启用哪些能力
+- 首批执行从哪里进入
+- 恢复主入口在哪里
+- 验证入口在哪里
+- 当前 clean state 如何识别
+- 首个稳定提交或等价回退边界如何识别
+- 相关信息分别落在哪个载体上
+
+若这些问题仍需要靠临场解释补齐，说明输出合同未达标。
+
+对 `deep-existing-repo` 而言，这组问题的答案允许由 attach metadata、repo companion 入口与 repo-native carriers 共同承接；它不要求第一轮就生成 Loom-owned `work-item` / `progress` / `status-surface`。

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

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

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