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

package/payload/skills/loom-review/.loom-runtime/shared/scripts/runtime_paths.py

@@ -0,0 +1,116 @@
+#!/usr/bin/env python3
+"""Resolve installed-skills runtime paths without assuming a repo-local layout."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def caller_path(caller_file: str) -> Path:
+    return Path(caller_file).resolve()
+
+
+def installed_skills_root(caller_file: str) -> Path | None:
+    env_root = os.environ.get("LOOM_INSTALLED_SKILLS_ROOT")
+    if env_root:
+        return Path(env_root).expanduser().resolve()
+
+    path = caller_path(caller_file)
+    if path.parent.name == "scripts" and path.parent.parent.name == "shared":
+        return path.parents[2]
+    if path.parent.name == "scripts" and path.parents[2].name == "skills":
+        return path.parents[2]
+    return None
+
+
+def source_repo_root() -> Path | None:
+    env_root = os.environ.get("LOOM_SOURCE_REPO_ROOT")
+    if not env_root:
+        return None
+    return Path(env_root).expanduser().resolve()
+
+
+def repo_local_root(caller_file: str) -> Path | None:
+    hinted = source_repo_root()
+    if hinted is not None:
+        return hinted
+
+    path = caller_path(caller_file)
+    if path.parent.name == "bin" and path.parent.parent.name == ".loom":
+        return path.parents[2]
+    return None
+
+
+def bootstrap_runtime_root(caller_file: str) -> Path | None:
+    path = caller_path(caller_file)
+    if path.parent.name == "bin" and path.parent.parent.name == ".loom":
+        return path.parent
+    return None
+
+
+def bootstrap_manifest_path(caller_file: str) -> Path | None:
+    runtime_root = bootstrap_runtime_root(caller_file)
+    if runtime_root is None:
+        return None
+    return runtime_root.parent / "bootstrap" / "manifest.json"
+
+
+def shared_root(caller_file: str) -> Path:
+    skills_root = installed_skills_root(caller_file)
+    if skills_root is None:
+        raise RuntimeError("installed skills root is not available for this runtime")
+    shared = skills_root / "shared"
+    if not shared.exists():
+        raise RuntimeError(f"shared runtime root is missing: {shared}")
+    return shared
+
+
+def shared_script(caller_file: str, script_name: str) -> Path:
+    script_path = shared_root(caller_file) / "scripts" / script_name
+    if not script_path.exists():
+        raise RuntimeError(f"shared runtime script is missing: {script_path}")
+    return script_path
+
+
+def shared_asset(caller_file: str, relative_path: str) -> Path:
+    asset_path = shared_root(caller_file) / "assets" / relative_path
+    if not asset_path.exists():
+        raise RuntimeError(f"shared runtime asset is missing: {asset_path}")
+    return asset_path
+
+
+def shared_reference(caller_file: str, relative_path: str) -> Path:
+    reference_path = shared_root(caller_file) / "references" / relative_path
+    if not reference_path.exists():
+        raise RuntimeError(f"shared reference is missing: {reference_path}")
+    return reference_path
+
+
+def registry_path(caller_file: str) -> Path:
+    skills_root = installed_skills_root(caller_file)
+    if skills_root is not None:
+        return skills_root / "registry.json"
+
+    path = caller_path(caller_file)
+    if path.parent.name == "bin" and path.parent.parent.name == ".loom":
+        return path.parent.parent / "skills" / "registry.json"
+
+    raise RuntimeError("registry path is unavailable outside installed-skills or .loom/bin runtime")
+
+
+def install_layout_path(caller_file: str) -> Path:
+    skills_root = installed_skills_root(caller_file)
+    if skills_root is None:
+        raise RuntimeError("install layout path is unavailable outside installed-skills runtime")
+    return skills_root / "install-layout.json"
+
+
+def installed_skill_script(caller_file: str, skill_id: str) -> Path:
+    skills_root = installed_skills_root(caller_file)
+    if skills_root is None:
+        raise RuntimeError("installed skills root is not available for skill entry lookup")
+    script_path = skills_root / skill_id / "scripts" / f"{skill_id}.py"
+    if not script_path.exists():
+        raise RuntimeError(f"installed skill entry script is missing: {script_path}")
+    return script_path

package/payload/skills/loom-review/.loom-runtime/shared/scripts/runtime_state.py

@@ -0,0 +1,405 @@
+#!/usr/bin/env python3
+"""Detect Loom runtime scene/carrier and enforce fail-closed runtime checks."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+from runtime_paths import (
+    bootstrap_manifest_path,
+    bootstrap_runtime_root,
+    caller_path,
+    installed_skills_root,
+    repo_local_root,
+    shared_root,
+    source_repo_root,
+)
+
+SUPPORTED_SCENES = {"repo-local-demo", "installed-runtime", "upgrade-rehearsal"}
+SUPPORTED_CARRIERS = {
+    "repo-local-wrapper",
+    "installed-skills-root",
+    "bootstrapped-target-runtime",
+}
+SUPPORTED_ENTRY_FAMILIES = {"loom-init", "loom-flow"}
+
+EXPECTED_SHARED_RUNTIME_SCRIPTS = (
+    "runtime_paths.py",
+    "runtime_state.py",
+    "loom_init.py",
+    "fact_chain_support.py",
+    "governance_surface.py",
+    "loom_flow.py",
+    "loom_check.py",
+)
+
+EXPECTED_BOOTSTRAP_RUNTIME_SOURCES = {
+    ".loom/bin/loom_init.py": "skills/shared/scripts/loom_init.py",
+    ".loom/bin/fact_chain_support.py": "skills/shared/scripts/fact_chain_support.py",
+    ".loom/bin/governance_surface.py": "skills/shared/scripts/governance_surface.py",
+    ".loom/bin/loom_flow.py": "skills/shared/scripts/loom_flow.py",
+    ".loom/bin/runtime_paths.py": "skills/shared/scripts/runtime_paths.py",
+    ".loom/bin/runtime_state.py": "skills/shared/scripts/runtime_state.py",
+    ".loom/bin/loom_check.py": "skills/shared/scripts/loom_check.py",
+}
+
+
+def _path_text(path: Path | None) -> str | None:
+    return str(path) if path is not None else None
+
+
+def _load_json(path: Path) -> tuple[dict[str, Any] | None, str | None]:
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return None, f"missing `{path}`"
+    except json.JSONDecodeError as exc:
+        return None, f"`{path}` is invalid JSON: {exc.msg}"
+    if not isinstance(payload, dict):
+        return None, f"`{path}` must be a JSON object"
+    return payload, None
+
+
+def _check(status: str, summary: str, *, evidence: object | None = None) -> dict[str, Any]:
+    payload: dict[str, Any] = {
+        "status": status,
+        "summary": summary,
+    }
+    if evidence is not None:
+        payload["evidence"] = evidence
+    return payload
+
+
+def detect_carrier(caller_file: str) -> str | None:
+    if source_repo_root() is not None:
+        return "repo-local-wrapper"
+    if bootstrap_runtime_root(caller_file) is not None:
+        return "bootstrapped-target-runtime"
+    if installed_skills_root(caller_file) is not None:
+        return "installed-skills-root"
+    return None
+
+
+def _default_scene_for_carrier(carrier: str) -> str:
+    if carrier == "repo-local-wrapper":
+        return "repo-local-demo"
+    return "installed-runtime"
+
+
+def _scene_check(carrier: str | None) -> tuple[str | None, dict[str, Any], list[str]]:
+    marker = os.environ.get("LOOM_RUNTIME_SCENE")
+    errors: list[str] = []
+    if carrier is None:
+        return None, _check("block", "runtime carrier could not be determined."), ["runtime carrier is unknown"]
+
+    if marker is None or not marker.strip():
+        scene = _default_scene_for_carrier(carrier)
+        return scene, _check("pass", f"scene defaults to `{scene}` for carrier `{carrier}`."), []
+
+    marker = marker.strip()
+    if marker not in SUPPORTED_SCENES:
+        errors.append(f"unsupported LOOM_RUNTIME_SCENE `{marker}`")
+        return None, _check("block", "scene marker is not part of the stable runtime-state vocabulary."), errors
+
+    scene = marker
+    if scene == "repo-local-demo" and carrier != "repo-local-wrapper":
+        errors.append(f"`repo-local-demo` scene conflicts with carrier `{carrier}`")
+    elif scene == "upgrade-rehearsal" and carrier not in {"installed-skills-root", "bootstrapped-target-runtime"}:
+        errors.append(f"`upgrade-rehearsal` scene conflicts with carrier `{carrier}`")
+    elif scene == "installed-runtime" and carrier == "repo-local-wrapper":
+        errors.append("`installed-runtime` scene cannot be asserted from a repo-local wrapper")
+
+    if errors:
+        return scene, _check("block", "scene marker conflicts with the detected runtime carrier."), errors
+    return scene, _check("pass", f"scene marker `{scene}` is consistent with carrier `{carrier}`."), []
+
+
+def _validate_install_layout(skills_root: Path) -> tuple[dict[str, Any], list[str], Path | None]:
+    errors: list[str] = []
+    layout_path = skills_root / "install-layout.json"
+    layout, error = _load_json(layout_path)
+    if error:
+        return _check("block", "install layout manifest is missing or invalid."), [error], layout_path
+
+    required_paths = layout.get("required_paths")
+    if not isinstance(required_paths, list) or not required_paths:
+        errors.append("`install-layout.json` must declare a non-empty `required_paths`")
+    else:
+        missing = []
+        for relative in required_paths:
+            if not isinstance(relative, str) or not relative:
+                errors.append("`install-layout.json` required paths must be non-empty strings")
+                continue
+            if not (skills_root / relative).exists():
+                missing.append(relative)
+        if missing:
+            errors.append("install layout is missing required paths: " + ", ".join(sorted(missing)))
+
+    status = "pass" if not errors else "block"
+    summary = (
+        "install layout manifest and required paths are present."
+        if status == "pass"
+        else "install layout manifest is incomplete or points to missing paths."
+    )
+    return _check(status, summary, evidence={"path": str(layout_path)}), errors, layout_path
+
+
+def _validate_registry_contract(skills_root: Path) -> tuple[dict[str, Any], list[str], Path]:
+    errors: list[str] = []
+    registry_path = skills_root / "registry.json"
+    registry, error = _load_json(registry_path)
+    if error:
+        return _check("block", "registry contract is missing or invalid."), [error], registry_path
+
+    if registry.get("install_layout") != "install-layout.json":
+        errors.append("`registry.json` must point `install_layout` to `install-layout.json`")
+    if registry.get("upgrade_contract") != "upgrade-contract.json":
+        errors.append("`registry.json` must point `upgrade_contract` to `upgrade-contract.json`")
+
+    entries = registry.get("entries")
+    if not isinstance(entries, list) or not entries:
+        errors.append("`registry.json` must declare a non-empty `entries` list")
+    else:
+        for entry in entries:
+            if not isinstance(entry, dict):
+                errors.append("registry entries must be JSON objects")
+                continue
+            skill_id = entry.get("id")
+            executable = entry.get("executable")
+            manifest = entry.get("manifest")
+            if not isinstance(skill_id, str) or not skill_id:
+                errors.append("registry entry is missing a non-empty `id`")
+                continue
+            if not isinstance(executable, str) or not executable:
+                errors.append(f"registry entry `{skill_id}` must declare a non-empty `executable`")
+            elif not (skills_root / executable).exists():
+                errors.append(f"registry entry `{skill_id}` points to missing executable `{executable}`")
+            if not isinstance(manifest, str) or not manifest:
+                errors.append(f"registry entry `{skill_id}` must declare a non-empty `manifest`")
+            elif not (skills_root / manifest).exists():
+                errors.append(f"registry entry `{skill_id}` points to missing manifest `{manifest}`")
+
+    upgrade_path = skills_root / "upgrade-contract.json"
+    upgrade_contract, upgrade_error = _load_json(upgrade_path)
+    if upgrade_error:
+        errors.append(upgrade_error)
+    else:
+        refresh_required = upgrade_contract.get("upgrade_policy", {}).get("refresh_required")
+        if not isinstance(refresh_required, list) or "layout_manifest" not in refresh_required:
+            errors.append("`upgrade-contract.json` must require refreshing `layout_manifest`")
+
+    status = "pass" if not errors else "block"
+    summary = (
+        "registry, upgrade contract, and skill entrypoints are consistent."
+        if status == "pass"
+        else "registry or upgrade contract drifted from the installed runtime layout."
+    )
+    return _check(status, summary, evidence={"path": str(registry_path)}), errors, registry_path
+
+
+def _validate_shared_runtime(skills_root: Path) -> tuple[dict[str, Any], list[str], Path]:
+    errors: list[str] = []
+    scripts_root = skills_root / "shared" / "scripts"
+    if not scripts_root.exists():
+        errors.append(f"missing shared runtime scripts root `{scripts_root}`")
+    else:
+        for script_name in EXPECTED_SHARED_RUNTIME_SCRIPTS:
+            if not (scripts_root / script_name).exists():
+                errors.append(f"missing shared runtime script `shared/scripts/{script_name}`")
+    status = "pass" if not errors else "block"
+    summary = (
+        "shared runtime scripts are present and executable roots can be resolved."
+        if status == "pass"
+        else "shared runtime scripts are missing or incomplete."
+    )
+    return _check(status, summary, evidence={"path": str(scripts_root)}), errors, scripts_root
+
+
+def _validate_referenced_resources(skills_root: Path) -> tuple[dict[str, Any], list[str]]:
+    errors: list[str] = []
+    required_resources = (
+        "shared/assets/templates/scaffold/spec.md",
+        "shared/assets/templates/scaffold/plan.md",
+        "shared/assets/github/PULL_REQUEST_TEMPLATE.md",
+        "shared/references/harness/status-surface.md",
+        "shared/references/harness/runtime-state.md",
+    )
+    for relative in required_resources:
+        if not (skills_root / relative).exists():
+            errors.append(f"missing referenced resource `{relative}`")
+    status = "pass" if not errors else "block"
+    summary = (
+        "shared references and assets required by the installed runtime are present."
+        if status == "pass"
+        else "shared references or assets required by the runtime are missing."
+    )
+    return _check(status, summary), errors
+
+
+def _validate_bootstrapped_runtime(caller_file: str) -> tuple[dict[str, Any], list[str], Path | None]:
+    errors: list[str] = []
+    runtime_root = bootstrap_runtime_root(caller_file)
+    manifest_path = bootstrap_manifest_path(caller_file)
+    if runtime_root is None or manifest_path is None:
+        errors.append("bootstrap runtime root or manifest path is unavailable")
+        return _check("block", "bootstrapped target runtime is missing its bootstrap carrier."), errors, manifest_path
+
+    if not runtime_root.exists():
+        errors.append(f"missing bootstrapped runtime root `{runtime_root}`")
+    manifest, manifest_error = _load_json(manifest_path)
+    if manifest_error:
+        errors.append(manifest_error)
+        return _check("block", "bootstrap manifest is missing or invalid."), errors, manifest_path
+
+    artifacts = manifest.get("artifacts")
+    if not isinstance(artifacts, list) or not artifacts:
+        errors.append("bootstrap manifest must declare a non-empty `artifacts` list")
+        return _check("block", "bootstrap manifest does not describe runtime artifacts."), errors, manifest_path
+
+    artifact_by_path = {
+        artifact.get("path"): artifact
+        for artifact in artifacts
+        if isinstance(artifact, dict) and isinstance(artifact.get("path"), str)
+    }
+    for relative, expected_source in EXPECTED_BOOTSTRAP_RUNTIME_SOURCES.items():
+        artifact = artifact_by_path.get(relative)
+        if artifact is None:
+            errors.append(f"bootstrap manifest is missing runtime artifact `{relative}`")
+            continue
+        if artifact.get("source") != expected_source:
+            errors.append(
+                f"bootstrap runtime artifact `{relative}` must point to `{expected_source}`, got `{artifact.get('source')}`"
+            )
+        runtime_file = runtime_root / Path(relative).name
+        if not runtime_file.exists():
+            errors.append(f"bootstrapped runtime file is missing: `{relative}`")
+
+    status = "pass" if not errors else "block"
+    summary = (
+        "bootstrap manifest and .loom/bin runtime files are aligned."
+        if status == "pass"
+        else "bootstrap manifest or .loom/bin runtime files drifted from the expected bundled runtime."
+    )
+    return _check(status, summary, evidence={"path": str(manifest_path)}), errors, manifest_path
+
+
+def detect_runtime_state(caller_file: str, entry_family: str, *, target_root: Path | None = None) -> dict[str, Any]:
+    if entry_family not in SUPPORTED_ENTRY_FAMILIES:
+        raise RuntimeError(f"unsupported entry family `{entry_family}`")
+
+    caller = caller_path(caller_file)
+    carrier = detect_carrier(caller_file)
+    scene, scene_check, scene_errors = _scene_check(carrier)
+    install_root = installed_skills_root(caller_file)
+    runtime_root = bootstrap_runtime_root(caller_file) or caller.parent
+    layout_or_manifest_path: Path | None = None
+    registry_location: Path | None = None
+    checks: dict[str, dict[str, Any]] = {
+        "scene_marker": scene_check,
+    }
+    errors = list(scene_errors)
+
+    if carrier is None:
+        checks["carrier_layout"] = _check("block", "runtime carrier cannot be classified from the current entrypoint.")
+        checks["registry_contract"] = _check("not_applicable", "no carrier-specific registry contract is available.")
+        checks["shared_runtime"] = _check("not_applicable", "no carrier-specific runtime root is available.")
+        checks["referenced_resources"] = _check("not_applicable", "no carrier-specific resources can be inspected.")
+    elif carrier in {"repo-local-wrapper", "installed-skills-root"}:
+        if install_root is None:
+            checks["carrier_layout"] = _check("block", "installed skills root is unavailable for the active carrier.")
+            errors.append("installed skills root is unavailable")
+        else:
+            carrier_errors: list[str] = []
+            try:
+                shared = shared_root(caller_file)
+            except RuntimeError as exc:
+                carrier_errors.append(str(exc))
+                shared = install_root / "shared"
+            if carrier == "repo-local-wrapper":
+                repo_root = repo_local_root(caller_file)
+                if repo_root is None:
+                    carrier_errors.append("repo-local wrapper is missing `LOOM_SOURCE_REPO_ROOT`")
+                elif not str(install_root).startswith(str(repo_root)):
+                    carrier_errors.append("repo-local wrapper install root must stay inside the source repository")
+            if not shared.exists():
+                carrier_errors.append(f"shared runtime root is missing: {shared}")
+            checks["carrier_layout"] = _check(
+                "pass" if not carrier_errors else "block",
+                (
+                    "carrier layout exposes an installed skills root and shared runtime tree."
+                    if not carrier_errors
+                    else "carrier layout does not expose the expected installed skills root or shared runtime tree."
+                ),
+                evidence={"install_root": str(install_root)},
+            )
+            errors.extend(carrier_errors)
+
+            registry_check, registry_errors, registry_location = _validate_registry_contract(install_root)
+            layout_check, layout_errors, layout_or_manifest_path = _validate_install_layout(install_root)
+            shared_check, shared_errors, _ = _validate_shared_runtime(install_root)
+            resources_check, resources_errors = _validate_referenced_resources(install_root)
+            checks["registry_contract"] = registry_check
+            checks["shared_runtime"] = shared_check
+            checks["referenced_resources"] = resources_check
+            if layout_check["status"] == "block":
+                if checks["carrier_layout"]["status"] == "pass":
+                    checks["carrier_layout"] = _check(
+                        "block",
+                        "carrier layout is present but its install layout manifest is incomplete.",
+                        evidence=layout_check.get("evidence"),
+                    )
+                errors.extend(layout_errors)
+            errors.extend(registry_errors)
+            errors.extend(shared_errors)
+            errors.extend(resources_errors)
+    else:
+        carrier_check, carrier_errors, layout_or_manifest_path = _validate_bootstrapped_runtime(caller_file)
+        checks["carrier_layout"] = carrier_check
+        checks["registry_contract"] = _check(
+            "not_applicable",
+            "bootstrapped target runtime does not consume `skills/registry.json`; it uses `.loom/bootstrap/manifest.json`.",
+        )
+        checks["shared_runtime"] = carrier_check
+        checks["referenced_resources"] = _check(
+            "not_applicable",
+            "bootstrapped target runtime validates copied runtime artifacts via the bootstrap manifest instead of shared references.",
+        )
+        errors.extend(carrier_errors)
+
+    unique_errors: list[str] = []
+    for message in errors:
+        if message not in unique_errors:
+            unique_errors.append(message)
+
+    result = "pass" if not unique_errors else "block"
+    if result == "pass":
+        summary = f"runtime carrier `{carrier}` is executing as `{scene}` with a consistent bundled runtime."
+    else:
+        summary = "runtime state is inconsistent with the expected carrier/layout contract."
+
+    if carrier == "installed-skills-root":
+        fallback_to = "refresh-install" if unique_errors else None
+    elif carrier == "bootstrapped-target-runtime":
+        fallback_to = "rebootstrap-runtime" if unique_errors else None
+    else:
+        fallback_to = "manual-runtime-reconciliation" if unique_errors else None
+
+    return {
+        "result": result,
+        "summary": summary,
+        "missing_inputs": unique_errors,
+        "fallback_to": fallback_to,
+        "scene": scene,
+        "carrier": carrier,
+        "entry_family": entry_family,
+        "install_root": _path_text(install_root),
+        "runtime_root": _path_text(runtime_root),
+        "registry_path": _path_text(registry_location),
+        "layout_or_manifest_path": _path_text(layout_or_manifest_path),
+        "source_repo_root": _path_text(source_repo_root()),
+        "target_root": _path_text(target_root.resolve() if target_root is not None else None),
+        "checks": checks,
+    }

package/payload/skills/loom-review/.loom-runtime/upgrade-contract.json

@@ -0,0 +1,29 @@
+{
+  "compatibility_questions": [
+    "Which root entry is current?",
+    "Which contract versions are installed for each declared entry?",
+    "Which executable path should the host invoke?",
+    "Which install layout manifest defines the minimum bundled runtime/resources?",
+    "Which runtime_state does the host currently observe?",
+    "If the runtime is blocked, what fail-closed reason is visible to the operator?",
+    "Should the host assert LOOM_RUNTIME_SCENE=upgrade-rehearsal for this run?",
+    "Does the host need to refresh referenced resources after upgrade?",
+    "Did the registry gain or retire scenario entries that the host must rediscover?"
+  ],
+  "current_contract_version": "1.4.0",
+  "registry_version": "1.3.0",
+  "root_entry": "loom-review",
+  "schema_version": "loom-skill-upgrade/v1",
+  "upgrade_policy": {
+    "failure_visibility": "fail closed and keep the previously known-good install state",
+    "mode": "explicit",
+    "refresh_required": [
+      "registry",
+      "manifest",
+      "executable",
+      "referenced_resources",
+      "layout_manifest"
+    ],
+    "version_source": "skills/registry.json"
+  }
+}

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

@@ -0,0 +1,95 @@
+---
+name: loom-review
+description: 负责正式 review 执行层。Use when Codex needs to run semantic review after pre-review and produce a formal review verdict without replacing merge-ready.
+---
+
+# Loom Review
+
+这个 skill 承接正式 review 执行层。
+
+它不等于 `loom-pre-review`，也不替代 `loom-merge-ready`：
+
+- `loom-pre-review` 负责进入 review 前的统一机械预检
+- `loom-review` 负责执行正式语义审查并产出审查结论
+- `loom-merge-ready` 负责 merge 前统一放行聚合
+
+对执行者来说，正式 review 的首层入口仍是 `loom-review` 这个场景 skill。repo-local 自动化、验证、调试和宿主编排可以统一调用 repo-local `loom CLI`，但这不替代场景 skill 的用户入口，也不改变 review / merge-ready 的边界。
+
+## 1. 使用时机
+
+当任务满足以下任一条件时，进入 `loom-review`：
+
+- 明确要求正式 review
+- 明确要求语义审查或审查结论
+- 明确要求输出 findings、风险和是否通过的判断
+- 明确要求在 pre-review 通过后进入审查执行
+
+如果任务其实是在做初始化、恢复执行、review 前预检、handoff、retire 或 merge-ready，应回到 root route matrix，让 `loom-init` 路由到对应场景：
+
+- [references/route-matrix.md](references/route-matrix.md)
+
+## 2. 固定入口
+
+统一入口固定为：
+
+- `loom flow review --target <repo> [--item <id>]`
+- `loom review run --target <repo> [--item <id>]`
+- `loom review record --target <repo> [--item <id>] --decision <allow|block|fallback> --kind <general_review|code_review|spec_review> --summary <text> --reviewer <id>`
+
+补充约束：
+
+- 若需要写入结构化 findings / disposition，使用 `--findings-file <path>`
+- `--blocking-issue` / `--follow-up` 仅保留兼容 authored 入口，不得与 `--findings-file` 混用
+- 无论通过哪种入口，最终都只允许写回单一 `review_entry` 指向的 review record
+
+这个 skill 先用 `flow review` 读取正式 review 的机械基线，再用 `review run` 触发默认 Codex reviewer 并生成 Loom-normalized findings，最后用 `review record` 把审查结论写成可消费载体。
+
+安装态或 repo-local 开发态可以把这些 `loom ...` 动作映射到底层 `scripts/...` 或共享 runtime carrier；但 `loom-review` 自身的场景合同、进入时机和输出责任保持不变。
+
+## 3. 固定编排
+
+`loom-review` 固定按以下顺序编排：
+
+1. 运行 `flow review`，确认当前事项是否具备进入正式审查的最小条件
+2. 若 `flow review` 非 `pass`，直接返回 `block` 或 `fallback`，不伪造审查结论
+3. 运行 `review run`，用默认 Codex adapter 执行 formal review，并把 raw output 收敛为 Loom evidence 与 normalized findings
+4. 若 `review run` fail-closed，显式回到 manual review 写回同一 `review record`
+5. 用 `review record` 写入正式 review 结论，让 merge checkpoint 可机械消费
+
+这个 skill 不做以下事情：
+
+- 不替代 pre-review 预检
+- 不替代 merge-ready 放行判断
+- 不直接执行 merge 或平台动作
+- 不回写 recovery entry、status surface 或其他 authored 真相载体
+- 不跳过 review record，直接把口头结论交给 merge checkpoint
+- 不把 engine raw output 升级成第二 authored truth
+
+## 4. 输出要求
+
+输出必须是统一 review 摘要 JSON，至少要让执行者能读出：
+
+- 当前事项是什么
+- review 机械基线结果
+- build checkpoint 是否允许进入正式审查
+- review artifact 的定位与已记录结论
+- 默认 engine 的执行结果、evidence 定位与 fail-closed 原因
+- manual review 的回退写回入口
+- review record 中的权威 findings / disposition 摘要
+- 审查结论（`allow` / `block` / `fallback`）
+- 若当前不能继续，应回退到哪里
+
+## 5. 完成标准
+
+只有当以下条件同时满足时，`loom-review` 才算完成：
+
+- 显式调用 `loom-review` 与 root 隐式路由都能稳定命中
+- 审查执行严格以 `flow review -> review run -> review record` 为前置，而不是绕过预检
+- 输出 JSON 与 review record 都能直接支撑 merge checkpoint 消费
+- skill 不创建第二 authored 真相源，不替代 merge-ready 聚合
+- review/disposition contract 只扩展 review record 内部字段，不新增第二 artifact 或新状态机
+
+输入信号与输出合同见：
+
+- [references/input-signals.md](references/input-signals.md)
+- [references/output-contract.md](references/output-contract.md)

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Loom Review"
+  short_description: "正式 review 语义审查入口"
+  default_prompt: "先运行 Loom 的 flow review 读取正式审查基线；若基线通过，再运行 review run 触发默认 Codex reviewer 并产出结构化 findings，最后用 review record 写入单一 review record。"