@alpsckr/unitycli 0.4.0

package/schemas/error-code.schema.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unitycli.local/schemas/error-code.schema.json",
+  "title": "UnityCLI Error Code",
+  "description": "Structured error object used in the response envelope. Every failure includes stable retry and recovery fields; blocker observations use a sanitized public DTO.",
+  "x-unityCliTaxonomy": ["E_DIALOG_OBSERVATION_FAILED", "E_DIALOG_NOT_FOUND", "E_DIALOG_STALE", "E_DIALOG_BUTTON_NOT_FOUND", "E_DIALOG_BUTTON_AMBIGUOUS", "E_DIALOG_CLICK_UNPROVEN"],
+  "type": "object",
+  "required": ["code", "message", "transient", "retryAfterMs", "nextActions"],
+  "properties": {
+    "code": {
+      "type": "string",
+      "pattern": "^[A-Z][A-Z0-9_]*(\\.[A-Z][A-Z0-9_]*)?$",
+      "description": "Machine-readable error code from the taxonomy. Examples: E_UNITY_BUSY, E_EXECUTION_TIMEOUT, BRIDGE_CONNECTION_FAILED."
+    },
+    "message": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Human-readable error description."
+    },
+    "details": {
+      "type": "object",
+      "description": "Additional structured business context. Transport endpoints, listener identity and native window handles are never public.",
+      "properties": {
+        "blockers": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/blocker" }
+        },
+        "observedBlockers": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/blocker" }
+        }
+      },
+      "additionalProperties": true
+    },
+    "nextActions": {
+      "type": "array",
+      "items": { "type": "string" },
+      "default": [],
+      "description": "Suggested recovery actions the caller (Agent or user) can take."
+    },
+    "retryAfterMs": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "When the error is transient (e.g. E_UNITY_BUSY), suggested minimum retry delay in milliseconds. 0 = no specific recommendation."
+    },
+    "transient": {
+      "type": "boolean",
+      "default": false,
+      "description": "True if the error is transient (compiling, domain reload, import) and the same request may succeed after retry."
+    }
+  },
+  "$defs": {
+    "blocker": {
+      "type": "object",
+      "required": ["type", "dialogId", "title", "message", "buttons", "requiresUserAction", "source", "confidence"],
+      "properties": {
+        "type": { "const": "dialog" },
+        "dialogId": { "type": "string", "pattern": "^dialog_[a-f0-9]{64}$" },
+        "title": { "type": "string" },
+        "message": { "type": "string" },
+        "buttons": { "type": "array", "items": { "type": "string" } },
+        "requiresUserAction": { "const": true },
+        "source": { "const": "windows-ui" },
+        "confidence": { "const": "exact" }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/extension-descriptor.schema.json

@@ -0,0 +1,88 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unitycli.local/schemas/extension-descriptor.schema.json",
+  "title": "UnityCLI Extension Descriptor",
+  "description": "Describes an optional capability pack (extension) for the UnityCLI. Extensions depend on optional Unity packages and provide additional tools.",
+  "type": "object",
+  "required": ["id", "title", "description", "kind", "source", "status", "installMode"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Extension identifier, e.g. 'probuilder'. Must be unique."
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Short human-readable title."
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "description": "One-paragraph explanation of what the extension provides."
+    },
+    "kind": {
+      "type": "string",
+      "const": "extension",
+      "description": "Discriminator: always 'extension' for ExtensionMetadata."
+    },
+    "source": {
+      "type": "string",
+      "enum": ["built-in", "package"],
+      "description": "Origin: 'built-in' (declared in core metadata) or 'package' (separate npm/Unity package)."
+    },
+    "version": {
+      "type": "string",
+      "description": "Semantic version of the extension."
+    },
+    "status": {
+      "type": "string",
+      "enum": ["installed", "available", "unavailable"],
+      "description": "Current install status."
+    },
+    "providesTools": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Tools provided by this extension (dotted names)."
+    },
+    "requiresUnityPackages": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Unity packages required for this extension to work."
+    },
+    "installMode": {
+      "type": "string",
+      "enum": ["auto", "manual", "copy-if-package-present"],
+      "description": "How the extension is installed: 'auto' (detected during init) or 'manual' (explicit install command)."
+    },
+    "copyRoot": {
+      "type": "string",
+      "enum": ["extension-directory", "unitypkg"],
+      "description": "Unity-side copy root. New extensions use extension-directory under Packages/com.alpsckr.unitycli/Extensions/<id>; unitypkg is legacy."
+    },
+    "unityInstall": {
+      "type": "object",
+      "properties": {
+        "layout": { "type": "string", "const": "directory" },
+        "include": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false,
+      "description": "Unity-side directory install projection."
+    },
+    "installCommand": {
+      "type": "string",
+      "description": "CLI command to install this extension."
+    },
+    "equivalentMcpGroup": {
+      "type": "string",
+      "description": "Mapping to equivalent unity-mcp group name, for parity tracking."
+    },
+    "nextActions": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Suggested next actions after listing/describing the extension."
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/extension-manifest.schema.json

@@ -0,0 +1,125 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unitycli.local/schemas/extension-manifest.schema.json",
+  "title": "UnityCLI Extension Manifest",
+  "description": "Describes a CLI extension package: identity, Unity package prerequisites, contribution IDs, C# entries, and Unity-side install projection. Detailed AI-facing tool metadata lives in extension tool metadata files.",
+  "type": "object",
+  "required": ["id", "name", "description", "version", "unityPackages", "contributions"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$",
+      "description": "Unique extension identifier in kebab-case, e.g. 'probuilder', 'vfx-graph'."
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Human-readable extension name, e.g. 'ProBuilder'."
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "description": "One-paragraph explanation of the extension."
+    },
+    "version": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Extension version, usually semver."
+    },
+    "unityPackages": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["packageId", "displayName"],
+        "properties": {
+          "packageId": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Unity package identifier, e.g. 'com.unity.probuilder'."
+          },
+          "versionRange": {
+            "type": "string",
+            "description": "Optional version range constraint."
+          },
+          "displayName": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Human-readable package name, e.g. 'ProBuilder'."
+          }
+        },
+        "additionalProperties": false
+      },
+      "description": "Required Unity packages for this extension to be available."
+    },
+    "contributions": {
+      "type": "object",
+      "properties": {
+        "tools": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name"],
+            "properties": {
+              "name": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Tool name contributed by the extension. Full descriptor lives in extension TS metadata."
+              },
+              "requiresPackages": {
+                "type": "array",
+                "items": { "type": "string" },
+                "description": "Unity packages required by this specific tool. Omitted means use extension-level package prerequisites."
+              }
+            },
+            "additionalProperties": false
+          },
+          "description": "Tool capability IDs contributed by this extension."
+        },
+        "csharpEntries": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["type", "description"],
+            "properties": {
+              "type": { "type": "string", "minLength": 1 },
+              "method": { "type": "string" },
+              "description": { "type": "string", "minLength": 1 }
+            },
+            "additionalProperties": false
+          },
+          "description": "C# implementation entries included in the extension bundle."
+        }
+      },
+      "additionalProperties": false,
+      "description": "Capabilities contributed by this extension."
+    },
+    "unityInstall": {
+      "type": "object",
+      "properties": {
+        "layout": {
+          "type": "string",
+          "const": "directory",
+          "description": "Install this extension as a subdirectory under Packages/com.alpsckr.unitycli/Extensions/<id>."
+        },
+        "include": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Source paths relative to extensions/<id>/ projected into the Unity extension directory."
+        }
+      },
+      "additionalProperties": false,
+      "description": "Unity-side directory install projection."
+    },
+    "tags": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Tags for categorization."
+    },
+    "homepage": {
+      "type": "string",
+      "description": "Homepage or documentation URL."
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/request-envelope.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unitycli.local/schemas/request-envelope.schema.json",
+  "title": "UnityCLI Bridge Request v2",
+  "description": "Exact immutable request envelope sent by the CLI session supervisor to one verified Live Editor instance.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["protocolVersion", "instanceId", "command", "requestId", "input", "execution"],
+  "properties": {
+    "protocolVersion": { "const": 2 },
+    "instanceId": { "type": "string", "pattern": "^unity-[0-9a-f]{64}$" },
+    "command": { "type": "string", "minLength": 1 },
+    "requestId": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[A-Za-z0-9._-]+$" },
+    "input": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#/$defs/anyJson" }
+    },
+    "execution": { "$ref": "#/$defs/execution" }
+  },
+  "$defs": {
+    "anyJson": { "x-unityCliAnyJson": true },
+    "execution": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["absoluteDeadlineUtc", "completionContractVersion", "requestDigestVersion"],
+      "properties": {
+        "absoluteDeadlineUtc": { "type": "string", "format": "date-time" },
+        "completionContractVersion": { "const": 1 },
+        "requestDigestVersion": { "const": 1 },
+        "dryRun": { "type": "boolean" }
+      }
+    }
+  }
+}

package/schemas/response-envelope.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unitycli.local/schemas/response-envelope.schema.json",
+  "title": "UnityCLI Response Envelope",
+  "description": "Unified response envelope for CLI commands. Field names are camelCase; successful command payloads live under data, structured failures live under error.",
+  "oneOf": [
+    {
+      "title": "Success Response",
+      "type": "object",
+      "required": ["ok", "requestId", "data"],
+      "properties": {
+        "ok": { "const": true, "description": "The command succeeded." },
+        "requestId": { "type": "string", "description": "Echoes the request requestId." },
+        "data": {
+          "type": "object",
+          "description": "Command-specific result payload. For C# tools this is serialized from the Result DTO."
+        },
+        "warnings": {
+          "type": "array",
+          "items": { "type": "string" },
+          "default": [],
+          "description": "Non-fatal warnings encountered during execution."
+        }
+      },
+      "additionalProperties": false
+    },
+    {
+      "title": "Error Response",
+      "type": "object",
+      "required": ["ok", "requestId", "error"],
+      "properties": {
+        "ok": { "const": false, "description": "The command failed." },
+        "requestId": { "type": "string", "description": "Echoes the request requestId." },
+        "error": {
+          "$ref": "./error-code.schema.json",
+          "description": "Structured error details. Recovery guidance is nested under error.nextActions and transient retry delay under error.retryAfterMs."
+        }
+      },
+      "additionalProperties": false
+    }
+  ]
+}

package/schemas/tool-metadata.schema.json

@@ -0,0 +1,111 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unitycli.local/schemas/tool-metadata.schema.json",
+  "title": "UnityCLI Public Tool Descriptor",
+  "description": "Public direct Tool descriptor used for discovery and first-call routing.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "name",
+    "summary",
+    "description",
+    "group",
+    "inputSchema",
+    "outputSchema",
+    "destructiveHint",
+    "supportsDryRun",
+    "target",
+    "availabilityScope",
+    "playModeSupport",
+    "contractProfile",
+    "source",
+    "available"
+  ],
+  "properties": {
+    "name": {
+      "type": "string",
+      "minLength": 1
+    },
+    "summary": { "type": "string", "minLength": 1 },
+    "description": { "type": "string", "minLength": 1 },
+    "group": { "type": "string", "minLength": 1 },
+    "inputSchema": { "type": "object" },
+    "outputSchema": { "type": "object" },
+    "destructiveHint": { "type": "boolean" },
+    "sideEffects": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "playModeSupport": {
+      "type": "string",
+      "enum": ["supported", "runtime-only", "session-affecting", "editor-only", "unknown"]
+    },
+    "supportsDryRun": { "type": "boolean" },
+    "permissions": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "examples": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["description", "argv"],
+        "properties": {
+          "description": { "type": "string", "minLength": 1 },
+          "argv": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "type": "string" }
+          }
+        }
+      }
+    },
+    "source": {
+      "type": "string",
+      "enum": ["built-in", "project", "extension"]
+    },
+    "contractProfile": {
+      "type": "string",
+      "enum": ["native", "official-attribute"]
+    },
+    "target": {
+      "type": "string",
+      "enum": ["editor", "runtime", "both"]
+    },
+    "availabilityScope": {
+      "type": "string",
+      "enum": ["editorSession", "playModeSession", "always"]
+    },
+    "available": { "type": "boolean" },
+    "unavailableReason": { "type": "string", "minLength": 1 },
+    "requiresPackages": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "extensionId": { "type": "string", "minLength": 1 }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": { "contractProfile": { "const": "official-attribute" } },
+        "required": ["contractProfile"]
+      },
+      "then": {
+        "properties": {
+          "name": { "pattern": "^UnityPipeline_[^\\s]+$" },
+          "group": { "const": "UnityPipeline" }
+        }
+      },
+      "else": {
+        "properties": {
+          "name": { "pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)*$" },
+          "group": { "not": { "const": "UnityPipeline" } }
+        }
+      }
+    }
+  ]
+}

package/skills/unitycli/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: unitycli
+description: 所有涉及 Unity 或 Unity Editor 或 UnityPipeline 的任务都优先使用本 Skill，以便发现唯一可用的 `unitycli` 控制入口。适用于 Scene、GameObject、Prefab、Asset、Package、Build、Test、GameView、SceneView、日志、截图、Bridge、instance、Editor/PlayMode 状态和项目自定义能力；纯源码或文本工作可直接处理，但需要观察、操作或验证已打开 Editor 时必须使用 CLI。
+---
+
+# UnityCLI
+
+FeedbackMode: off
+
+`unitycli` 是 AI 操作已打开 Unity Editor 的能力目录。不要记忆或猜能力：先发现，再读 descriptor，最后调用。
+
+## 路由
+
+- 所有Unity动作与观察能力都属于Tool；读取型Tool必须纯只读并准确声明空副作用。
+- 纯 `.cs`、JSON、YAML、manifest 或文档编辑可直接使用文件工具。需要 Unity 内存状态、导入结果、编译、物理、渲染或业务效果证明时使用 CLI。
+- 公开顶层只有`tools`、`command`、`init`、`extensions`、`target`、`instances`、`doctor`；Unity能力域不作为顶层命令。
+- auth、Unity Hub、Editor安装或打开、Cloud、License、proxy配置属于外部控制面；直接使用系统或官方工具，不在catalog中猜测替代Tool。
+- Extension 管理只用 `extensions list`、`extensions install`、`extensions remove`、`extensions doctor`。
+- 已连接实例的目录同时包含 built-in、Extension、project、Editor 和 Runtime 能力，不按 `source` 或当前模式过滤。
+- 完全兼容 Unity 官方 CLI 特性体系：项目与第三方 Package 中以官方 `[CliCommand]`/`[CliArg]`/`IStructuredCommandInput` 声明的命令直接进入同一 catalog，固定投影为 `UnityPipeline_<原名>`、group `UnityPipeline`，用 `command <原名>` 或完整前缀名调用；`com.unity.pipeline` 包自身命令已由 native 能力吸收并按 provider identity 抑制。native 精确重名优先。
+
+## 执行骨架
+
+```powershell
+# 默认隐藏 offline；仅审计完整历史集合时使用 instances list --all
+unitycli instances list
+unitycli tools group --instance <id|projectPath|alias>
+unitycli tools group list <group> --instance <id|projectPath|alias>
+unitycli tools search '<k1|k2|...>' --instance <id|projectPath|alias>
+unitycli tools describe <tool> --instance <id|projectPath|alias>
+unitycli tools run <tool> --input '<json>' --instance <id|projectPath|alias>
+
+# 同一catalog的schema参数调用；省略name时列出command投影
+unitycli command --project-path <projectPath>
+unitycli command <name> --field <value> --instance <id|projectPath|alias>
+```
+
+显式`--instance`优先；`command --project-path <path>`绑定同一canonical项目实例；未传时只能从当前Unity项目CWD解析。没有连接实例时discovery返回稳定instance error，不返回静态或空目录。`instances list`逐文件隔离旧格式、损坏或不可读记录，合法Registry v3实例继续返回；`invalidRecordCount`出现时先运行`doctor`，不得读取、转换、移动或删除内部记录。显式选择对应坏instanceId仍会严格失败。
+
+执行不了解的Tool前必须`tools describe`，输入和行为以当前descriptor为准。PowerShell中必须用单引号包住`tools search '<k1|k2|...>'`的整个关键词，否则`|`会被shell解释为管道。schema default 与 `examples[].input` 描述合法默认业务值，按需 `examples[].execution` 描述 dry-run/timeout 控制；任务明确要求的业务值优先，不能把default/example当作连通性或probe调用。`tools group list`/`tools search`返回的Tool `name`就是exact调用名；group只用于筛选，不能拼到name前。
+
+`command`不建立第二套目录：native Tool使用完整精确名；Unity官方`[CliCommand]`完全兼容，项目或其他Package的`[CliCommand("test")]`在`tools`中固定名为`UnityPipeline_test`、group为`UnityPipeline`，可由`command test`或完整前缀名选择。`com.unity.pipeline` package自身命令已由native能力吸收并按provider identity抑制，不应期待其attribute原名存在。native精确重名优先；不得把不存在的名称映射到相似Tool。业务参数支持`--field value`、`--field=value`、boolean裸开关和按schema声明顺序的positional。
+
+## 使用说明
+
+- 调用即授权。`destructiveHint`、`sideEffects`、`supportsDryRun`只描述效果；仅在确需预览时使用`--dry-run`。Skill不增加确认、意图复核或预定义操作范围；产品的cross-session mutation fence仍必须遵守。
+- 建议通过 `instances`、`doctor`、`tools run editor.state` 观察状态，不读取内部 Bridge 注册文件、端口或 URL，也不直接 ping transport。
+- CLI会在发送Unity业务请求前自行等待target session任务池放行；不得手工每100毫秒循环调用，也不得读取或操作内部准入identity。`--timeout-ms T`分别提供最多`T`的准入等待与放行后最多`T`的业务执行。
+- 准入deadline返回的`E_UNITY_BUSY`会明确证明`no business request was sent`，effect未开始，可以稍后提交新root。已进入池后的mutation lease busy不得解释为effect未开始。
+- `E_EXECUTION_TIMEOUT`、放行后连接丢失或缺少可信terminal envelope只表示没有可信终态。先用只读Tool或业务readback观察并形成新的业务决策；CLI不自动重放，首次mutation POST后Editor session改变时也不会向新session重投。`transient:true`与`nextActions`仍是建议，不构成额外授权门。
+- 运行公开CLI时必须等待该进程退出，不得后台分离。传入`--timeout-ms T`时，命令host至少等待`2 * T + 5000`毫秒；CLI在stdout完成或最多1秒后退出。host提前超时不等于CLI、准入grant或Unity effect已经停止。
+- `available:false`、`unavailableReason` 和 `playModeSupport` 说明当前可执行性；`source` 不参与路由。
+- blocker 在 `error.details.blockers` 时，可先读 `editor.dialogs`，再按返回的 dialogId 与 enabled button 调用 `editor.dialog.click`。
+- 大输出、envelope、artifact、分页、host等待预算和 session 说明见 `references/operation-protocol.md`。
+- 内置能力不足时，一次性操作可使用 `code.exec`；反复需要再读 `references/custom-tools.md`。`code.exec`不限制提交的同步C#，也不会拒绝死循环、长时间sleep、阻塞等待、锁等待或长期占用Unity API的代码。提交这类代码前必须先判断它对当前结果是否确有必要，并考虑有界写法或现有Tool能否达到同一结果；确有必要时可以原样执行。代码一旦在Unity主线程开始，`--timeout-ms`只能停止CLI等待，不能中止代码；Unity可能无响应、mutation owner不能收尾、业务状态部分改变或未知，恢复可能需要结束Editor进程。timeout不证明代码已停止，重试前必须观察业务状态。`--dry-run`只预览source hash，不编译、不执行，也不证明代码会结束。
+
+## 问题反馈
+
+仅当上方 marker 为 `on` 且本次实际遇到失败、歧义、缺失、误导或成功绕过的坑点时，读取 `references/feedback.md` 并调用 `scripts/record-feedback.ps1`。正常无摩擦调用不记录；marker 为 `off` 时不得运行脚本。
+
+记录时只传简短结构化摘要，不传原始 prompt、完整 CLI 输入输出、源码、日志、绝对路径、URL、token、endpoint 或秘密。记录成功后才在正常回复末尾追加一段简短反馈摘要，包含类别、问题、workaround（如有）、recordId 和本地路径；这不是通用最终回复格式。脚本失败不改变 Unity 任务结论，但要说明反馈未写入。

package/skills/unitycli/agents/interface.yaml

@@ -0,0 +1,30 @@
+interface:
+  display_name: "UnityCLI"
+  short_description: "Discover and operate an opened Unity Editor through the public unitycli catalog"
+  default_prompt: "Use $unitycli for every Unity task so the available CLI is known. Use direct file tools for pure source/text work, and use the connected Editor catalog whenever live Unity state, effects, or verification are needed."
+compatibility:
+  canonical_format: "agent-skills"
+  adapter_targets:
+    - "openai"
+    - "claude"
+    - "generic"
+  activation:
+    mode: "automatic"
+    paths: []
+  execution:
+    context: "inline"
+    shell: "powershell"
+  trust:
+    source_tier: "local"
+    remote_inline_execution: "forbid"
+    remote_metadata_policy: "allow-metadata-only"
+  permissions:
+    network: "deny"
+    file_write:
+      - "%LOCALAPPDATA%\\UnityCli\\feedback\\feedback*.jsonl"
+    subprocess:
+      - "powershell.exe for the opt-in feedback recorder"
+  degradation:
+    openai: "runtime-bundle-with-deferred-references"
+    claude: "runtime-bundle-with-deferred-references"
+    generic: "agent-skills-compatible-runtime-bundle"

package/skills/unitycli/evals/history/2026-08-05-governed-baseline.json

@@ -0,0 +1,44 @@
+{
+  "captured_at": "2026-08-05",
+  "release": "0.1.9",
+  "status": "baseline",
+  "trigger_eval": {
+    "case_count": 29,
+    "precision": 1.0,
+    "recall": 1.0,
+    "false_positives": 0,
+    "false_negatives": 0,
+    "evidence": "DIR-003 trigger-eval.json"
+  },
+  "output_eval": {
+    "case_count": 5,
+    "file_backed_case_count": 2,
+    "baseline_pass_rate": 0.0,
+    "with_skill_pass_rate": 100.0,
+    "regression_count": 0,
+    "evidence": "DIR-003 output-eval.json"
+  },
+  "repository_tests": {
+    "passed": 876,
+    "failed": 0,
+    "evidence": "DIR-003 full-tests.log"
+  },
+  "targeted_skill_tests": {
+    "passed": 61,
+    "failed": 0,
+    "evidence": "DIR-003 targeted-regression.log"
+  },
+  "dev_live": {
+    "agents": ["pi", "claude", ".agents"],
+    "install_update_check": "pass",
+    "compile_errors": 0,
+    "compile_warnings": 0
+  },
+  "clean_agent_gate": "pass",
+  "missing evidence": [
+    "production trigger telemetry",
+    "longitudinal feedback quality",
+    "human blind-review adjudication",
+    "native permission enforcement"
+  ]
+}

package/skills/unitycli/evals/output/cases.jsonl

@@ -0,0 +1,5 @@
+{"id":"caller-controls-timeout","prompt":"A Unity mutation returned E_EXECUTION_TIMEOUT. What may the caller do next?","baseline_output":"Immediately repeat the same mutation because timeout means it did not run.","with_skill_output":"E_EXECUTION_TIMEOUT means there is no trusted terminal result. First inspect business state with a read-only Tool or artifact proof, then make a new submission decision. The CLI does not automatically replay the mutation, and a changed Editor session forbids cross-session redelivery after the first POST.","assertions":[{"id":"states-uncertainty","description":"Timeout meaning remains factual.","required":["no trusted terminal result"],"weight":1,"failure_type":"missing_timeout_fact"},{"id":"observe-before-decision","description":"A fresh decision follows business observation.","required":["inspect business state","new submission decision"],"weight":2,"failure_type":"unsafe_replay"},{"id":"session-fence","description":"Cross-session mutation redelivery is forbidden.","required":["changed Editor session","forbids cross-session redelivery"],"forbidden":["immediately repeat"],"weight":2,"failure_type":"missing_session_fence"}],"human_review":{"expected_winner":"with_skill"},"execution":{"mode":"recorded_fixture","holdout":false}}
+{"id":"feedback-off-is-silent","prompt":"FeedbackMode is off and the Unity task completed normally. What feedback output is required?","baseline_output":"Always write a usage event so maintainers can measure adoption.","with_skill_output":"Produce the normal task response only. There is no feedback record and no feedback summary when FeedbackMode is off.","assertions":[{"id":"no-record","description":"Off mode writes nothing.","required":["no feedback record","no feedback summary"],"forbidden":["usage event"],"weight":2,"failure_type":"off_mode_noise"}],"human_review":{"expected_winner":"with_skill"},"execution":{"mode":"recorded_fixture","holdout":false}}
+{"id":"feedback-workaround-record","prompt":"Use the attached friction event after a successful workaround.","input_files":["fixtures/feedback-scenario.json"],"baseline_output":"Mention the issue informally and include the full CLI output for context.","with_skill_output":"Use the file-backed fixture and call scripts/record-feedback.ps1 once with the bounded category, summary, workaround, capability, errorCode, and phase fields. After ok:true, append a short feedback summary with recordId and the local path. Do not include the raw prompt or complete CLI I/O.","assertions":[{"id":"uses-file-backed-fixture","description":"The eval uses a file-backed fixture.","required":["file-backed fixture"],"weight":1,"failure_type":"missing_file_fixture"},{"id":"calls-recorder","description":"The runtime recorder is selected.","required":["record-feedback.ps1","recordId","local path"],"weight":2,"failure_type":"missing_recorder"},{"id":"protects-content","description":"Raw content is excluded.","required":["Do not include the raw prompt or complete CLI I/O"],"forbidden":["full CLI output for context"],"weight":2,"failure_type":"privacy_leak"}],"human_review":{"expected_winner":"with_skill"},"execution":{"mode":"recorded_fixture","holdout":false}}
+{"id":"direct-file-versus-live-editor","prompt":"How should an Agent handle a pure Unity C# edit versus verifying the compiled behavior in the opened Editor?","baseline_output":"Use unitycli for both the source edit and Editor verification.","with_skill_output":"Use direct file tools for the pure source edit. Use the connected unitycli Tool catalog for live Editor compilation, state, effect, and verification.","assertions":[{"id":"direct-file","description":"Pure source work remains direct.","required":["direct file tools","pure source edit"],"weight":1,"failure_type":"unnecessary_wrapper"},{"id":"live-editor","description":"Live effects use the catalog.","required":["unitycli Tool catalog","live Editor"],"weight":1,"failure_type":"missing_editor_route"}],"human_review":{"expected_winner":"with_skill"},"execution":{"mode":"recorded_fixture","holdout":false}}
+{"id":"governed-release-evidence","prompt":"What evidence must accompany this governed Skill release?","input_files":["fixtures/feedback-scenario.json"],"baseline_output":"Publish the Skill after tests pass.","with_skill_output":"Use the file-backed fixture and declare input_files, the output contract, and the rollback boundary. Include the trust report and reports/output_quality_scorecard.md. Mark unavailable telemetry, human approval, and longitudinal metrics as missing evidence.","assertions":[{"id":"fixture-and-inputs","description":"File-backed inputs are explicit.","required":["file-backed fixture","input_files"],"weight":1,"failure_type":"missing_input_files"},{"id":"contracts","description":"Output and rollback boundaries are explicit.","required":["output contract","rollback boundary"],"weight":1,"failure_type":"missing_boundary"},{"id":"trust-scorecard","description":"Trust and output evidence are named.","required":["trust report","reports/output_quality_scorecard.md"],"weight":1,"failure_type":"missing_reports"},{"id":"missing-evidence","description":"Unavailable evidence is not invented.","required":["missing evidence"],"weight":1,"failure_type":"invented_evidence"}],"human_review":{"expected_winner":"with_skill"},"execution":{"mode":"recorded_fixture","holdout":false}}