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

package/payload/skills/loom-init/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: loom-init
+description: Loom 的 root entry。负责初始化新项目或既有仓库，并在非初始化任务下根据任务信号把执行者路由到正确场景 skill。Use when Codex needs to start a repository on top of Loom, retrofit Loom into an existing repo, or route a Loom operator to the right scenario skill.
+---
+
+# Loom Init
+
+把本 skill 作为 Loom 的默认入口。
+
+在以下情况先进入 `loom-init`：
+
+- 你要初始化 Loom，或把 Loom retrofit 进既有仓库
+- 你还不知道当前任务应该进入哪个场景 skill
+- 你希望 Loom 先根据任务信号判断下一步入口
+
+不要把 root skill 继续扩成第二套事实真相源。它负责先判断，再导向正确场景。
+
+对执行者的首层说明仍应以 `loom-init` 作为 root entry。repo-local 自动化、验证、调试和宿主编排可以统一落到 repo-local `loom CLI`，但这不改变 `loom-init` 的 route 语义，也不把 CLI 升格成用户第一入口。
+
+## Quick Path
+
+1. 先判断当前任务属于初始化 / retrofit，还是已经进入日常执行场景。
+2. 如果用户已经显式指定场景 skill，显式调用优先，直接进入该 skill。
+3. 如果没有显式指定 skill，由 `loom-init` 根据任务信号做路由。
+4. 如果信号不足、冲突，或缺少稳定执行所需的最小输入，保留在 `loom-init`，并要求最小补充信号。
+
+## Route Summary
+
+显式指定 skill 时，显式调用优先。
+
+未显式指定 skill 时，`loom-init` 按任务信号做隐式路由。
+
+默认场景对应关系如下：
+
+- 初始化 / retrofit / 新项目接入
+  - 路由到 `loom-adopt`
+- 接手事项 / 恢复上下文 / 继续推进
+  - 路由到 `loom-resume`
+- review 前检查 / 进入 review 前预检
+  - 路由到 `loom-pre-review`
+- 正式 review / 语义审查 / review 结论
+  - 路由到 `loom-review`
+- 交接 / 回写停点 / 移交当前事项
+  - 路由到 `loom-handoff`
+- 清理现场 / retire 当前事项
+  - 路由到 `loom-retire`
+- merge-ready / 最终放行前预检
+  - 路由到 `loom-merge-ready`
+
+如果信号不足或同时命中多个场景，不要猜测。回退到 `loom-init`，并要求最小补充信号。
+
+完整场景路由规则见 [references/route-matrix.md](references/route-matrix.md)。
+
+## Installed Entry Surface
+
+当前安装态中的最小可执行入口为：
+
+- `loom init bootstrap --target <repo>`
+- `loom init verify --target <repo>`
+- `loom init fact-chain --target <repo>`
+- `loom route --target <repo> [--skill <id>] [--task "<request>"]`
+
+安装态或 repo-local 开发态可以把这些 `loom ...` 动作映射到底层 `scripts/...` 或 `tools/...` carrier；首层用户入口仍然是 `loom-init` 这个 skill。
+
+## 1. 读取顺序
+
+按以下顺序读取材料：
+
+- 目标仓库中的 `AGENTS.md`、`README`、流程文档、PR 模板、issue 模板
+- Loom 根文档：
+  - `AGENTS.md`
+  - `README.md`
+- Loom 核心规则：
+  - `references/shared/governance/principles.md`
+  - `references/shared/governance/review-model.md`
+  - `references/shared/governance/maturity-and-closing.md`
+  - `references/shared/adoption/routing-and-checkpoints.md`
+  - `references/shared/adoption/lightweight-retrofit-default.md`
+  - `references/shared/adoption/deep-existing-repo-default.md`
+- `references/shared/harness/recovery-model.md`
+- `references/shared/harness/fact-chain-contract.md`
+- `references/shared/harness/status-surface.md`
+- `references/shared/harness/work-item-contract.md`
+- `references/shared/harness/workspace-model.md`
+- `references/route-matrix.md`
+- `references/input-signals.md`
+- `references/shared/harness/automation-frontload.md`
+- `references/shared/harness/workspace-and-purity.md`
+- `references/shared/harness/execution-context.md`
+- `references/shared/templates/spec-suite.md`
+- `references/shared/templates/pull-request.md`
+- `references/output-contract.md`
+
+只有在事项带有明显不确定性、需要进一步分层时，才补读：
+
+- 由宿主额外提供的候选 adoption 材料；不要假设安装态自带候选层全文
+
+## 2. 建立初始化问诊
+
+优先从仓库现状推断答案，只在关键信息缺失时再问用户。
+
+使用 [references/input-signals.md](references/input-signals.md) 组织问诊。必须先完成最小必判字段的收集，再做路径判断。
+
+问诊结果必须收成以下结论，而不是停留在零散观察：
+
+- 初始化场景
+  - `新项目`
+  - `小型既有仓库`
+  - `复杂既有仓库`
+- 装配强度
+  - `轻量`
+  - `标准`
+  - `强化`
+- 默认接入方式
+  - 根级重写
+  - `companion docs`
+- 恢复形态
+  - `checkpoint-lite`
+  - 标准恢复形态
+- 首批执行入口与验证入口
+- 初始 clean state 目标
+
+## 3. 做出装配判断
+
+不要输出抽象“建议采用 Loom”。必须把判断落成“判定信号 -> 默认动作”的装配决策。
+
+### 3.1 新项目
+
+当仓库尚未形成稳定工程基线、目标是建立最小起步结构时，判为 `新项目`。
+
+默认动作：
+
+- 采用最小装配
+- 不预装重 harness
+- 只建立后续可升级入口
+- 只引入当前能支撑持续演进的最小治理、模板与验证入口
+- 恢复形态默认从轻量开始；若当前没有跨多轮承接需求，可以只声明升级条件，不提前铺满恢复工件
+
+### 3.2 小型既有仓库
+
+当仓库满足 [references/shared/adoption/lightweight-retrofit-default.md](references/shared/adoption/lightweight-retrofit-default.md) 的默认条件时，判为 `小型既有仓库`。
+
+默认动作：
+
+- 直接消费 `lightweight retrofit default`
+- 默认采用 `companion docs` 接入
+- 默认装配：
+  - `WORKFLOW`
+  - `code_review`
+  - `spec_review`
+  - 最小 PR 模板
+  - 条件化 `spec.md` / `plan.md`
+- 默认不装配：
+  - 完整 recovery 模型
+  - work item 合同
+  - 状态面
+  - profile 分层
+  - 重 harness
+- 若需要轻量跨轮承接，默认使用 `checkpoint-lite`
+- 即使本轮不装配标准恢复或状态面，也必须写清：
+  - issue / PR 中谁是恢复主入口
+  - 哪个载体承接当前停点、下一步、阻断项与最近验证摘要
+- 只要缺少统一验证入口，或仓库主产物本身是共享 contract、shared skill 或 governance module，就不得继续套用这条轻量路径
+
+### 3.3 复杂既有仓库
+
+既有仓库只要不满足轻量条件，或已经出现明显恢复痛点、共享边界风险、现场混杂、review 过载、统一验证入口缺失中的任一高强度信号，就判为 `复杂既有仓库`。
+
+默认动作：
+
+- 若根规则清晰、验证入口稳定且命中 `merge_review_semantic_overload`，优先进入 `deep-existing-repo` / `recognize-and-attach`
+- 否则进入更完整装配
+- 显式纳入：
+  - 恢复主入口
+  - 执行上下文
+  - work item 或等价执行入口
+  - 状态读取
+  - 隔离现场与纯度规则
+- 对涉及共享契约、运行模型、高风险核心抽象的事项，默认纳入正式规约套件与前移 checkpoint
+- 对恢复成本明显升高的事项，默认从 `checkpoint-lite` 升级到标准恢复形态
+
+当命中 `deep-existing-repo` 时，额外保持以下纪律：
+
+- 保留 root rules
+- 保留 retained host actions
+- 保留 repo-native carriers
+- 第一轮不生成 Loom-owned `work-item` / `progress` / `status-surface` placeholder
+
+## 4. 输出初始化结果
+
+始终使用 [references/output-contract.md](references/output-contract.md) 的结构输出结果。
+
+输出中必须显式写出：
+
+- 初始化场景
+- 装配强度
+- 恢复形态
+- 首批执行入口
+- 验证入口
+- 事实链 carrier 定位
+- 初始 clean state
+- 本轮暂不装配能力的承接方式
+
+如果用户要求实际初始化仓库，按以下顺序执行：
+
+1. 建立根级规则入口或 `companion docs` 入口
+2. 建立治理与 adoption 最小工件
+3. 建立 harness 与模板最小工件
+4. 建立首批 issue / checkpoint / 验证路径
+5. 核对输出是否已经形成可继续执行的初始化产物模型
+
+## 5. 处理三类场景的差异
+
+### 5.1 新项目
+
+- 直接给出最小装配方案
+- 优先保证后续能持续演进
+- 避免把未来可能需要的能力提前全部引入
+- 不默认铺满重 harness，只写清升级入口与触发条件
+
+### 5.2 小型既有仓库
+
+- 默认走 `lightweight retrofit default`
+- 仅当仓库真正满足轻量路径前提时，才沿用该默认策略
+- 先指出当前结构性问题
+- 再给出渐进 adoption 顺序
+- 明确哪些问题先通过规则解决，哪些问题后续再脚本化
+- 不要把 recovery、work-item、status-surface 当成第一轮默认必装项
+- 若走 `checkpoint-lite`，必须写清 issue / PR 对停点、下一步、阻断项、验证摘要的承接方式
+
+### 5.3 复杂既有仓库
+
+- 先指出导致不能走轻量路径的升级信号
+- 再给出更完整装配顺序
+- 必须写清正式执行入口、恢复主入口、状态读取入口与现场绑定方式
+- 若涉及共享边界或高风险实现承诺，必须写清正式规约工件与 checkpoint 承接关系
+
+## 6. 验证标准
+
+只有当以下条件同时满足时，才把初始化视为完成：
+
+- 输出结果能解释为什么是这组能力，而不是另外两条路径
+- 输出结果能映射回 Loom 当前文档中的明确规则
+- 首批工件、首批事项、恢复形态、验证入口与初始 clean state 可以直接承接后续执行
+- 明确保留了“现在不做什么”，且写清升级触发条件
+- 对未装配能力给出了明确承接方式，而不是留给临场经验补齐

package/payload/skills/loom-init/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Loom Init"
+  short_description: "作为 Loom root entry，负责初始化或路由到正确场景 skill"
+  default_prompt: "如果任务是初始化或 retrofit，就输出 Loom 接入方案；如果任务是日常执行场景，就根据任务信号把执行者路由到正确场景 skill。"

package/payload/skills/loom-init/contract.json

@@ -0,0 +1,76 @@
+{
+  "artifact_mapping": {
+    "default_targets": [
+      ".loom/bootstrap/init-result.json",
+      ".loom/work-items/INIT-0001.md",
+      ".loom/progress/INIT-0001.md",
+      ".loom/status/current.md",
+      ".loom/specs/INIT-0001/spec.md",
+      ".loom/specs/INIT-0001/plan.md"
+    ],
+    "rules": [
+      "../shared/references/governance",
+      "../shared/references/harness",
+      "../shared/references/templates",
+      "../shared/references/adoption"
+    ],
+    "skill_refs": [
+      "references/input-signals.md",
+      "references/intake-signals.md",
+      "references/output-contract.md"
+    ]
+  },
+  "contract_version": "1.3.0",
+  "description": "Bootstrap Loom into a target repository and route operators to the right scenario skill when the task is not a fresh initialization request.",
+  "display_name": "Loom Init",
+  "entrypoint": {
+    "adapter_metadata": "agents/openai.yaml",
+    "bootstrap_cli": "scripts/loom-init.py",
+    "route_cli": "scripts/loom-init.py",
+    "skill_markdown": "SKILL.md"
+  },
+  "id": "loom-init",
+  "input_contract": {
+    "reference": "references/input-signals.md",
+    "required_fields": [
+      "repository_type",
+      "root_boundary_docs",
+      "ci_or_basic_tests",
+      "repository_level_validation_entry",
+      "primary_gap_category",
+      "long_running_recovery_pain",
+      "shared_contract_or_high_risk_boundary",
+      "purity_or_scope_signals",
+      "merge_review_semantic_overload"
+    ]
+  },
+  "installation": {
+    "layout_manifest": ".loom-runtime/install-layout.json",
+    "registry": ".loom-runtime/registry.json",
+    "upgrade_contract": ".loom-runtime/upgrade-contract.json"
+  },
+  "output_contract": {
+    "reference": "references/output-contract.md",
+    "required_sections": [
+      "project_judgment",
+      "recommended_adoption",
+      "deferred_capabilities",
+      "fact_chain",
+      "initial_artifacts",
+      "initial_work_items",
+      "runtime_state",
+      "validation_and_closing"
+    ]
+  },
+  "role": "bootstrap/root",
+  "root_entry": true,
+  "routing": {
+    "fallback_entry": "loom-init",
+    "priority_order": [
+      "explicit skill name",
+      "task signal routing",
+      "fallback to loom-init with missing inputs"
+    ],
+    "reference": "references/route-matrix.md"
+  }
+}

package/payload/skills/loom-init/references/input-signals.md

@@ -0,0 +1,16 @@
+# Loom Init Input Signals
+
+`loom-init` 继续使用现有初始化问诊信号作为 root 入参合同。
+
+稳定输入信号见：
+
+- [intake-signals.md](intake-signals.md)
+
+当任务不是初始化，而是执行中的日常动作时，还必须结合：
+
+- [route-matrix.md](route-matrix.md)
+
+root skill 只在两种情况下继续留在 `loom-init`：
+
+- 任务明确是初始化 / retrofit
+- 任务信号不足，无法稳定路由到单一场景 skill

package/payload/skills/loom-init/references/intake-signals.md

@@ -0,0 +1,155 @@
+# Intake Signals
+
+使用本文件组织 `loom-init` 的初始化问诊与场景判断。
+
+## 1. 输入目标
+
+本合同只负责两件事：
+
+- 把目标仓库稳定判到以下三类场景之一：
+  - `新项目`
+  - `小型既有仓库`
+  - `复杂既有仓库`
+- 基于场景判断导出默认装配路径，而不是停留在零散提示
+
+本合同服务入口判断，不替代 `governance`、`harness`、`templates` 的规则真相。
+
+## 2. 最小必判字段
+
+初始化前，至少要完成以下字段的判断：
+
+- 仓库类型
+  - `新项目`
+  - `既有仓库`
+- 根级边界文档是否清晰
+  - 例如 `AGENTS.md`、同类规则入口或等价边界文档
+- 是否已有 CI / 基础测试
+- 是否已有统一的仓库级验证入口
+- 当前主要缺口属于哪一类：
+  - 治理入口 / review 合同 / 条件化 spec 路径
+  - 恢复 / 状态 / 执行支撑
+- 是否有明显长任务恢复痛点
+- 是否存在共享契约 / 共享数据模型 / 核心抽象 / 高风险链路
+- 是否存在分支混杂、PR 混题、脏现场叠加
+- merge 前是否承担第一次高质量语义判断
+
+若以上任一字段未完成判断，不得直接给出初始化路径结论。
+
+## 3. 每项字段的取证来源
+
+默认按以下顺序取证：
+
+1. 目标仓库现状
+   - 根级规则文档
+   - README、流程文档、模板
+   - CI、测试、统一验证入口、PR 习惯、issue / PR 载体
+2. Loom 现有规则与 adoption 文档
+   - 用于映射信号，不用于替代目标仓库事实
+3. 用户补充信息
+   - 仅在仓库现状不能稳定推断时再问
+
+取证约束：
+
+- 优先从仓库现状读取
+- 缺失时再问用户
+- 不允许靠临场经验补脑
+- 不能把单次会话中的猜测当成稳定信号
+
+## 4. 三类场景判定规则
+
+### 4.1 `新项目`
+
+满足以下条件时，判为 `新项目`：
+
+- 仓库尚未形成稳定工程基线
+- 当前目标是建立最小起步结构，而不是 retrofit 既有流程
+
+默认装配路径：
+
+- 最小装配
+- 不预装重 harness
+- 只建立后续可升级入口
+
+### 4.2 `小型既有仓库`
+
+满足以下条件时，判为 `小型既有仓库`：
+
+- 已有清晰根级边界文档
+- 已有 CI / 基础测试
+- 已有统一的仓库级验证入口
+- 当前缺口主要在治理入口、review 合同、条件化 spec 路径
+- 尚无明显长任务恢复痛点
+- 当前没有需要立即进入更重路径的共享边界或高风险核心抽象信号
+- 当前主产物本身不是共享 contract、shared skill 或 governance module
+
+默认装配路径：
+
+- 直接采用 [shared/adoption/lightweight-retrofit-default.md](shared/adoption/lightweight-retrofit-default.md)
+- 默认 `companion docs` 接入
+- 默认装配最小治理包
+- 默认不装配完整 recovery、work item、状态面与重 harness
+- 若需要轻量跨轮承接，默认 `checkpoint-lite`
+
+### 4.3 `复杂既有仓库`
+
+满足以下任一条件时，判为 `复杂既有仓库`：
+
+- 属于既有仓库，但不满足 `小型既有仓库` 的轻量条件
+- 无可见 CI / workflow 且无统一验证入口
+- 已出现明显长任务恢复痛点
+- 已出现共享契约、共享数据模型、运行模型或高风险核心抽象变化
+- 仓库主产物本身是共享 contract、shared skill 或 governance module
+- 已出现现场混杂、PR 混题、脏现场叠加等明显纯度问题
+- merge 前 review 仍在承担第一次高质量语义判断，且已成为结构性瓶颈
+
+默认装配路径：
+
+- 进入更完整装配
+- 纳入恢复主入口、执行上下文、work item 或等价执行入口、状态读取、隔离现场与纯度规则
+- 对高风险边界事项纳入正式规约套件与前移 checkpoint
+
+若同时满足以下条件，则 `复杂既有仓库` 默认优先走 `deep-existing-repo`：
+
+- 根级边界文档清晰
+- 已有统一的仓库级验证入口
+- 已出现 `merge_review_semantic_overload`
+
+这条路径的含义是：
+
+- 保留 `repository_mode = complex-existing`
+- 保留 root rules、retained host actions 与 repo-native carriers
+- 先做 `recognize-and-attach`
+- 不在第一轮直接写入 Loom-owned recovery/status carriers
+
+## 5. 冲突处理规则
+
+当信号之间出现冲突时，按以下规则处理：
+
+- 若同时满足“小型既有仓库已有基线”和“恢复痛点 / 共享边界风险明显”，优先判为 `复杂既有仓库`
+- 若缺少统一验证入口，或仓库主产物本身是共享 contract、shared skill 或 governance module，优先判为 `复杂既有仓库`
+- 任何共享契约、运行模型或高风险核心抽象变化，优先提升到更重路径
+- 任何多轮恢复成本明显升高或出现多个入口并行记录，优先从 `checkpoint-lite` 升级到标准恢复形态
+- 只有在缺口主要集中于治理入口、review 合同、条件化 spec 路径，且恢复痛点不明显时，才保持轻量路径
+
+## 6. 场景到默认装配映射
+
+- `新项目`
+  - 最小装配
+  - 重点是建立后续可升级入口
+- `小型既有仓库`
+  - 轻量 retrofit 默认策略
+  - 重点是最小治理闭环与 `companion docs` 接入
+- `复杂既有仓库`
+  - 更完整装配
+  - 重点是恢复、执行支撑、状态读取与高风险事项准入
+  - 若同时满足“根规则清晰 + 统一验证入口 + `merge_review_semantic_overload`”，默认优先走 `deep-existing-repo`
+
+## 7. `lightweight retrofit default` 的消费关系
+
+`loom-init` 对小型既有仓库的默认入口不是临场经验，而是直接消费 [shared/adoption/lightweight-retrofit-default.md](shared/adoption/lightweight-retrofit-default.md)。
+
+这意味着：
+
+- `companion docs` 接入是默认动作，不是可有可无的建议
+- 默认装配项、默认不装配项、`checkpoint-lite` 都必须进入入口层判断逻辑
+- 若判断结果偏离该默认策略，必须显式写出偏离原因与升级信号