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

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

@@ -0,0 +1,26 @@
+---
+name: loom-retire
+description: 负责清理并退休当前事项现场。Use when Codex needs to clean up Loom-owned residue and retire a workspace without discarding user changes.
+---
+
+# Loom Retire
+
+这个 skill 承接 cleanup / retire 场景。
+
+优先入口：
+
+- `python3 scripts/loom-retire.py purity-check --target <repo> [--item <id>]`
+- `python3 scripts/loom-retire.py workspace cleanup --target <repo> --item <id>`
+- `python3 scripts/loom-retire.py workspace retire --target <repo> --item <id>`
+
+执行要求：
+
+- 默认先解释 retire 前置条件，再按 `purity-check -> workspace cleanup -> workspace retire` 顺序执行
+- 若当前事项刚完成 host merge 后 closeout，先确认 `reconciliation audit|sync` 与 `closeout check|sync` 已消费完主干 / issue / PR / project 事实，再退休现场
+- 不自动丢弃用户改动，不默认删除现场目录
+- 退休完成后，以 recovery 主入口的 `current_checkpoint: retired` 作为终态依据
+
+输入信号与输出合同见：
+
+- [references/input-signals.md](./references/input-signals.md)
+- [references/output-contract.md](./references/output-contract.md)

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Loom Retire"
+  short_description: "清理并退休当前 Loom 现场"
+  default_prompt: "在不丢弃用户改动的前提下，执行 purity-check、cleanup 和 retire 链路。"

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

@@ -0,0 +1,41 @@
+{
+  "contract_version": "1.3.0",
+  "description": "Run purity-check, cleanup Loom-owned residue, and retire the current workspace without deleting user work by default.",
+  "display_name": "Loom Retire",
+  "entrypoint": {
+    "adapter_metadata": "agents/openai.yaml",
+    "orchestration_cli": "scripts/loom-retire.py",
+    "skill_markdown": "SKILL.md"
+  },
+  "id": "loom-retire",
+  "input_contract": {
+    "reference": "references/input-signals.md",
+    "required_fields": [
+      "target_repository",
+      "current_item_or_active_item",
+      "retire_intent"
+    ]
+  },
+  "installation": {
+    "layout_manifest": "../install-layout.json",
+    "registry": "../registry.json",
+    "upgrade_contract": "../upgrade-contract.json"
+  },
+  "output_contract": {
+    "reference": "references/output-contract.md",
+    "required_sections": [
+      "preconditions",
+      "purity_result",
+      "cleanup_result",
+      "retire_result",
+      "final_checkpoint",
+      "workspace_policy"
+    ]
+  },
+  "role": "scenario/retire",
+  "root_entry": true,
+  "routing": {
+    "explicit_name": "loom-retire",
+    "reference": "../route-matrix.md"
+  }
+}

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

@@ -0,0 +1,7 @@
+# Loom Retire Input Signals
+
+当任务满足以下任一信号时，进入 `loom-retire`：
+
+- 清理现场
+- retire 当前事项
+- 结束当前事项现场

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

@@ -0,0 +1,13 @@
+# Loom Retire Output Contract
+
+输出至少需要给出：
+
+- `runtime_state`
+  - 当前 Loom 入口自己的 scene / carrier 判定
+  - 若安装态运行时、shared 资源或 bootstrap carrier 漂移，必须直接 `block`
+- retire 前置条件说明
+- `purity-check` 的结果
+- `workspace cleanup` 的结果
+- `workspace retire` 的结果
+- 最终 checkpoint，固定以 `retired` 为终态
+- 现场策略说明：不自动丢弃用户改动，不默认删除目录

package/payload/skills/loom-retire/.loom-runtime/loom-retire/scripts/loom-retire.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-retire/.loom-runtime/registry.json

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

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

package/payload/skills/loom-retire/.loom-runtime/shared/references/adoption/routing-and-checkpoints.md

@@ -0,0 +1,88 @@
+# Routing And Checkpoints
+
+本文件定义 Loom 当前的事项分流与 checkpoint 策略。
+
+本文件当前承接：
+
+- `EXT-0007`
+- `EXT-0024`
+- `EXT-0019`
+- `EXT-0022`
+
+## 1. 事项分流
+
+Loom 当前默认把事项分成三条入口：
+
+- 轻量事项
+  - 不改变正式契约、上位边界或高风险链路
+- 中等事项
+  - 需要冻结目标、范围、验证与回滚，但不一定进入完整正式规约
+- 正式规约事项
+  - 涉及共享边界、共享契约、共享数据模型、高风险链路或核心实现承诺
+
+## 2. 当前默认路径
+
+- 轻量事项
+  - 直接进入实现 PR
+- 中等事项
+  - 先形成简化设计说明，再进入实现
+- 正式规约事项
+  - 先完成实现前审查，再进入实现
+
+## 3. 不应过早固化分层体系
+
+Loom 当前保留分流思想，但不先把它固化为 profile 体系。
+
+原因是：
+
+- 事项分类必须服务执行
+- 不应反过来要求用户先理解复杂分类学
+- 初始化 `SKILL` 应负责把用户场景映射到合适入口
+
+## 4. checkpoint 策略
+
+Loom 当前至少应支持三类正式判断点：
+
+- `admission checkpoint`
+  - 判断事项是否具备进入实现承诺的条件
+- `build checkpoint`
+  - 判断当前实现是否仍在已批准轨道上
+- `merge checkpoint`
+  - 判断当前 head 是否满足进入主干的条件
+
+其中：
+
+- 本文保留三类 checkpoint 的治理与采用语义
+- 执行侧的最小承接链路见 [../harness/execution-chain.md](../harness/execution-chain.md)
+- `merge checkpoint` 的执行侧输入、结果与回退去向见 [../harness/merge-checkpoint.md](../harness/merge-checkpoint.md)
+
+`admission checkpoint` 在 adoption 语义上表达“进入实现承诺前的正式判断”。
+治理内核中的稳定命名与审查分工，见 [../governance/review-model.md](../governance/review-model.md)。
+
+## 5. Loom 当前约束
+
+- 不允许只有 `merge checkpoint` 足够强，而前两者长期虚化
+- 不允许 merge 前 review 承担第一次高质量语义判断
+- 不允许中等事项长期在“轻量事项”和“正式规约事项”之间无明确入口
+- 不允许把三类 checkpoint 的执行侧输入、回写和放行规则继续留给读者自行拼装
+
+## 6. 与 `skills/` 的关系
+
+这些分流和 checkpoint 规则，最终应由初始化 `SKILL` 转化成实际提问、决策与装配逻辑。
+
+## 7. 与 `harness/` 的关系
+
+`adoption/` 只保留：
+
+- 为什么需要三类 checkpoint
+- 哪类事项默认进入哪条路径
+- checkpoint 之间的治理不变量
+
+以下执行侧细节不再由本文展开：
+
+- 初始化产物如何进入正式执行
+- 每轮开始前必须读取哪些事实
+- 每轮结束后必须回写哪些事实
+- merge checkpoint 放行前必须可读取哪些验证与状态事实
+
+这些内容统一由 `harness/` 中的稳定合同承接。