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

package/payload/skills/loom-adopt/references/shared/harness/workspace-model.md

@@ -0,0 +1,56 @@
+# Workspace Model
+
+本文件定义 Loom 当前最小工作现场模型。
+
+本文件当前承接：
+
+- `EXT-0025`
+- `EXT-0012`
+- `EXT-0037` 的 clean state 部分
+
+## 1. 能力定位
+
+工作现场用于承接正式执行，而不是临时试探。
+
+它负责：
+
+- 为单一正式事项提供隔离现场
+- 为恢复动作提供可定位目标
+- 为该事项消费的 host branch / `git worktree` / PR 绑定提供执行侧锚点
+- 为初始化后的 clean state 提供承载边界
+
+## 2. 最小现场规则
+
+正式执行链路默认使用隔离工作现场，并满足：
+
+- 单现场单事项
+- 同一现场只服务一个主要目标
+- 恢复动作应能回到同一现场
+- 新事项不得默认复用脏现场继续推进
+
+现场标识可以参数化，但必须由稳定输入确定性生成，不能只依赖人工记忆。
+
+## 3. clean state 要求
+
+初始化或现场创建完成后，应处于可继续执行的 clean state。
+
+最小要求：
+
+- 现场与目标事项已明确绑定
+- 进入执行所需的初始工件已经落位
+- 当前现场不存在未分流的无关正式改动
+- 后续恢复不需要重新猜测应进入哪个现场
+
+## 4. 边界约束
+
+Loom 只固化现场隔离、单事项和可恢复定位。
+必要时，Loom 会读取 `active issue` 与 host branch / `git worktree` / PR 的绑定来校验现场是否仍服务同一事项。
+
+Loom 当前不固化：
+
+- 具体目录命名格式
+- 是否必须使用 worktree
+- 具体命令、脚本或平台命名约定
+
+branch、PR 与 git worktree 的宿主边界见 [host-lifecycle-boundary.md](host-lifecycle-boundary.md)。
+`active issue` 绑定消费见 [host-issue-binding.md](host-issue-binding.md)。

package/payload/skills/loom-adopt/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-adopt/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-adopt/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-adopt/scripts/loom-adopt.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-adopt")
+sys.path.insert(0, str(RUNTIME_ROOT / "shared/scripts"))
+runpy.run_path(RUNTIME_ROOT / "shared/scripts/loom_init.py", run_name="__main__")

package/payload/skills/loom-handoff/.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-handoff",
+    "loom-handoff/scripts/loom-handoff.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-handoff/.loom-runtime/loom-handoff/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: loom-handoff
+description: 负责交接当前事项。Use when Codex needs to prepare a handoff package before ending the current execution round.
+---
+
+# Loom Handoff
+
+这个 skill 承接 handoff 场景。
+
+优先入口：
+
+- `python3 scripts/loom-handoff.py flow handoff --target <repo> [--item <id>]`
+
+执行要求：
+
+- 只读取现有事实链、状态检查和现场定位结果
+- 只输出 handoff 所需的最小回写清单与载体定位
+- 不直接写 recovery entry、status surface 或其他 authored 载体
+
+输入信号与输出合同见：
+
+- [references/input-signals.md](./references/input-signals.md)
+- [references/output-contract.md](./references/output-contract.md)

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Loom Handoff"
+  short_description: "生成交接前最小回写清单"
+  default_prompt: "读取当前 Loom 事项状态，只输出 handoff 所需的最小回写清单和定位信息，不直接回写任何 authored 载体。"

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

@@ -0,0 +1,53 @@
+{
+  "contract_version": "1.3.0",
+  "description": "Produce the minimum handoff writeback checklist and locator set without creating a second authored truth source.",
+  "display_name": "Loom Handoff",
+  "entrypoint": {
+    "adapter_metadata": "agents/openai.yaml",
+    "orchestration_cli": "scripts/loom-handoff.py",
+    "skill_markdown": "SKILL.md"
+  },
+  "id": "loom-handoff",
+  "input_contract": {
+    "reference": "references/input-signals.md",
+    "required_fields": [
+      "target_repository",
+      "current_item_or_active_item",
+      "handoff_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",
+      "workspace",
+      "checkpoint",
+      "state_check",
+      "steps",
+      "recovery_entry",
+      "status_surface",
+      "current_stop",
+      "next_step",
+      "blockers",
+      "latest_validation_summary",
+      "fallback_target",
+      "writeback_fields"
+    ]
+  },
+  "role": "scenario/handoff",
+  "root_entry": true,
+  "routing": {
+    "explicit_name": "loom-handoff",
+    "reference": "../route-matrix.md"
+  }
+}

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

@@ -0,0 +1,7 @@
+# Loom Handoff Input Signals
+
+当任务满足以下任一信号时，进入 `loom-handoff`：
+
+- 交接当前事项
+- 回写停点
+- 移交给下一个执行者

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

@@ -0,0 +1,42 @@
+# Loom Handoff Output Contract
+
+输出固定为 handoff 摘要 JSON，至少需要给出：
+
+- `item`
+  - 当前事项编号、目标、范围、执行路径
+- `result`
+  - `pass` 或 `block`
+- `summary`
+  - 对当前 handoff 可移交状态的单句结论
+- `missing_inputs`
+  - 当前仍需补齐的阻断项；无阻断时为空数组
+- `fallback_to`
+  - 若当前状态不适合直接移交，应回退到哪个 checkpoint；无回退时为 `null`
+- `runtime_state`
+  - 当前 Loom 入口自己的 scene / carrier 判定，以及 fail-closed 原因
+- `workspace`
+  - `workspace_entry`、解析后的现场路径、现场是否存在
+- `checkpoint`
+  - 原始 checkpoint 文本与归一化后的 checkpoint
+- `state_check`
+  - `state-check` 的结果、摘要、阻断项与检查分项
+- `recovery_entry`
+  - 当前 recovery entry 的定位字符串
+- `status_surface`
+  - 当前 status surface 的定位字符串
+- `current_stop`
+  - 当前执行停点，供交接前回写
+- `next_step`
+  - 下一个执行动作，供交接前回写
+- `blockers`
+  - 当前阻断项，供交接前回写
+- `latest_validation_summary`
+  - 最近验证摘要，供交接前回写
+- `fallback_target`
+  - 若当前未准备好移交，应优先回退到的目标；无回退时为 `null`
+- `writeback_fields`
+  - 固定为 `current_stop`、`next_step`、`blockers`、`latest_validation_summary`
+- `steps`
+  - 固定按 `runtime-state -> fact-chain -> state-check -> workspace-locate` 顺序列出
+
+这个 skill 只生成回写清单和定位，不直接写文件，也不创建新的 authored 真相源。

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

package/payload/skills/loom-handoff/.loom-runtime/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/references/adoption/lightweight-retrofit-default.md](../../shared/references/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/references/adoption/lightweight-retrofit-default.md](../../shared/references/adoption/lightweight-retrofit-default.md)。
+
+这意味着：
+
+- `companion docs` 接入是默认动作，不是可有可无的建议
+- 默认装配项、默认不装配项、`checkpoint-lite` 都必须进入入口层判断逻辑
+- 若判断结果偏离该默认策略，必须显式写出偏离原因与升级信号