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

package/payload/skills/loom-handoff/references/shared/templates/pull-request.md

@@ -0,0 +1,44 @@
+# Pull Request
+
+本文件定义 Loom 当前最小 PR 模板规则。
+
+本文件当前承接：
+
+- `EXT-0008`
+- `EXT-0028`
+
+## 1. PR 模板必须服务判断
+
+PR 模板的目标是提供最小必要事实，不是把作者变成填表机器。
+
+## 2. 基础必填块
+
+Loom 的基础 PR 模板至少应包含：
+
+- 本次改动解决什么问题
+- 改动范围是什么
+- 如何验证
+- 有哪些风险或未决项
+- 关联事项是什么
+
+## 3. 条件触发块
+
+PR 模板可以有扩展块，但不应默认强加给所有 PR。
+
+默认要求：
+
+- 只有在当前改动确实涉及对应主题时，才启用额外区块
+- 扩展块应围绕特定风险、迁移、回滚、数据变更等主题展开
+
+## 4. Loom 当前约束
+
+Loom 支持结构化 PR 模板，但必须满足：
+
+- 基础模板保持短小
+- 条件块按需触发
+- 模板内容直接服务 review 与 merge 判断
+
+不允许：
+
+- 用超重模板制造机械性噪音
+- 把长期规则真相写死在 PR 模板里

package/payload/skills/loom-handoff/references/shared/templates/review-record.md

@@ -0,0 +1,35 @@
+# Review Record
+
+正式 review record 至少应表达：
+
+- `item_id`
+- `kind`
+- `reviewed_head`
+- `reviewed_validation_summary`
+- `decision`
+- `summary`
+- `reviewer`
+- `fallback_to`
+- `findings`
+- `blocking_issues`
+- `follow_ups`
+- `consumed_inputs`
+
+允许结果：
+
+- `allow`
+- `block`
+- `fallback`
+
+约束：
+
+- `fallback_to` 只在 `decision: fallback` 时使用
+- `reviewed_head` 与 `reviewed_validation_summary` 必须对应本次审查基线
+- merge checkpoint 允许 review 之后只新增 Loom 自身的 `review_entry` / recovery / status carriers 提交；除此之外的 `HEAD` 漂移仍视为 stale
+- `findings` 是权威 findings / rebuttal / disposition 数组；每条至少包含 `id`、`summary`、`severity`、`rebuttal`、`disposition`
+- `severity` 当前稳定值为 `warn`、`block`
+- `rebuttal` 当前稳定值为 `null` 或非空字符串
+- `disposition` 当前稳定值为 `null` 或对象；对象内的 `status` 只允许 `accepted`、`rejected`、`deferred`
+- `blocking_issues` / `follow_ups` 仅作为兼容字段保留，默认从 `findings` 投影，不应被当作独立 authored 真相
+- `consumed_inputs.engine_adapter`、`consumed_inputs.engine_evidence`、`consumed_inputs.normalized_findings` 只记录 evidence 来源，不构成第二 authored truth
+- review record 是 merge checkpoint 的正式输入之一，不得只留在会话或 PR 评论里

package/payload/skills/loom-handoff/references/shared/templates/spec-suite.md

@@ -0,0 +1,57 @@
+# Spec Suite
+
+本文件定义 Loom 当前最小正式规约套件。
+
+本文件当前承接：
+
+- `EXT-0015`
+- `EXT-0016`
+- `EXT-0017`
+
+## 1. 正式规约套件的最小边界
+
+Loom 当前把正式规约套件的最小内核定义为：
+
+- `spec.md`
+- `plan.md`
+
+这两个工件分别承担不同职责，不得混写。
+
+## 2. `spec.md` 最小要求
+
+`spec.md` 至少应表达：
+
+- 目标
+- 范围
+- 关键场景，优先使用 `GWT`
+- 异常与边界
+- 验收标准
+
+## 3. `plan.md` 最小要求
+
+`plan.md` 至少应表达：
+
+- 实施目标
+- 阶段拆分
+- 约束
+- 验证方式
+- `TDD` 或测试策略
+- 依赖关系
+- 进入实现前条件
+
+## 4. 套件边界规则
+
+Loom 必须区分：
+
+- 正式契约工件
+- 执行或进度工件
+
+默认要求：
+
+- `spec.md` 与 `plan.md` 属于正式最小套件
+- 进度跟踪类工件是否存在，可以按项目需要扩展
+
+Loom 当前不固化：
+
+- 所有项目都必须有同一组附加工件
+- `TODO.md` 或同类文件是永恒必选项

package/payload/skills/loom-handoff/scripts/loom-handoff.py

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

package/payload/skills/loom-init/.loom-runtime/install-layout.json

@@ -0,0 +1,77 @@
+{
+  "required_paths": [
+    "registry.json",
+    "upgrade-contract.json",
+    "install-layout.json",
+    "route-matrix.md",
+    "shared/scripts",
+    "shared/assets",
+    "shared/references",
+    "shared/scripts/runtime_paths.py",
+    "shared/scripts/runtime_state.py",
+    "shared/scripts/loom_init.py",
+    "shared/scripts/fact_chain_support.py",
+    "shared/scripts/governance_surface.py",
+    "shared/scripts/loom_flow.py",
+    "shared/scripts/loom_check.py",
+    "shared/assets/review/loom-review-result-schema.json",
+    "shared/assets/templates/scaffold/spec.md",
+    "shared/assets/templates/scaffold/plan.md",
+    "shared/assets/github/PULL_REQUEST_TEMPLATE.md",
+    "shared/references/governance/principles.md",
+    "shared/references/governance/review-model.md",
+    "shared/references/governance/maturity-and-closing.md",
+    "shared/references/governance/state-machine.md",
+    "shared/references/governance/issue-model.md",
+    "shared/references/governance/host-object-taxonomy.md",
+    "shared/references/governance/truth-and-sync-boundary.md",
+    "shared/references/harness/recovery-model.md",
+    "shared/references/harness/fact-chain-contract.md",
+    "shared/references/harness/status-surface.md",
+    "shared/references/harness/runtime-state.md",
+    "shared/references/harness/work-item-contract.md",
+    "shared/references/harness/workspace-model.md",
+    "shared/references/harness/automation-frontload.md",
+    "shared/references/harness/workspace-and-purity.md",
+    "shared/references/harness/execution-context.md",
+    "shared/references/harness/execution-chain.md",
+    "shared/references/harness/merge-checkpoint.md",
+    "shared/references/harness/closeout-gate.md",
+    "shared/references/harness/host-action-contract.md",
+    "shared/references/harness/host-issue-binding.md",
+    "shared/references/harness/host-lifecycle-boundary.md",
+    "shared/references/harness/reconciliation-audit.md",
+    "shared/references/harness/review-execution.md",
+    "shared/references/templates/spec-suite.md",
+    "shared/references/templates/pull-request.md",
+    "shared/references/templates/review-record.md",
+    "shared/references/adoption/lightweight-retrofit-default.md",
+    "shared/references/adoption/deep-existing-repo-default.md",
+    "shared/references/adoption/routing-and-checkpoints.md",
+    "loom-init",
+    "loom-init/scripts/loom-init.py"
+  ],
+  "root": ".",
+  "runtime_state": {
+    "error_surface": "return stable runtime_state.missing_inputs instead of reporting unknown runtime status",
+    "fail_closed_on": [
+      "shared runtime missing",
+      "shared references missing",
+      "shared assets missing",
+      "install layout missing",
+      "registry contract drift",
+      "upgrade contract drift",
+      "skill executable missing",
+      "scene marker conflicts with carrier"
+    ],
+    "installed_runtime": {
+      "evidence": "required_paths"
+    },
+    "recognized_states": [
+      "installed-runtime",
+      "repo-local-demo",
+      "upgrade-rehearsal"
+    ]
+  },
+  "schema_version": "loom-install-layout/v1"
+}

package/payload/skills/loom-init/.loom-runtime/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`，并要求最小补充信号。
+
+完整场景路由规则见 [../route-matrix.md](../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 核心规则：
+  - `skills/shared/references/governance/principles.md`
+  - `skills/shared/references/governance/review-model.md`
+  - `skills/shared/references/governance/maturity-and-closing.md`
+  - `skills/shared/references/adoption/routing-and-checkpoints.md`
+  - `skills/shared/references/adoption/lightweight-retrofit-default.md`
+  - `skills/shared/references/adoption/deep-existing-repo-default.md`
+- `skills/shared/references/harness/recovery-model.md`
+- `skills/shared/references/harness/fact-chain-contract.md`
+- `skills/shared/references/harness/status-surface.md`
+- `skills/shared/references/harness/work-item-contract.md`
+- `skills/shared/references/harness/workspace-model.md`
+- `skills/route-matrix.md`
+- `skills/loom-init/references/input-signals.md`
+- `skills/shared/references/harness/automation-frontload.md`
+- `skills/shared/references/harness/workspace-and-purity.md`
+- `skills/shared/references/harness/execution-context.md`
+- `skills/shared/references/templates/spec-suite.md`
+- `skills/shared/references/templates/pull-request.md`
+- `skills/loom-init/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 小型既有仓库
+
+当仓库满足 [../shared/references/adoption/lightweight-retrofit-default.md](../shared/references/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/.loom-runtime/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/.loom-runtime/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": "../install-layout.json",
+    "registry": "../registry.json",
+    "upgrade_contract": "../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": "../route-matrix.md"
+  }
+}

package/payload/skills/loom-init/.loom-runtime/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