@rpamis/comet 0.3.9 → 0.4.0-beta.10

package/assets/skills-zh/comet-any/reference/authored-zone-example.md

@@ -0,0 +1,105 @@
+# Authored 区质量标尺（样例）
+
+这是你编写的 **Authored 区**（entry 的 `## Decision Core`、node 的 `## Guidance`）的具体质量标尺。生成器把你的 Authored 区组装到确定性 **Auto 区**（frontmatter、路由表、Entry/Exit Check、证据格式、Recovery）之上。**你只写 Authored 区**。请按本样例校准，而不是写一行套话。
+
+## "Auto" 与 "Authored" 的含义
+
+- **Auto 区（模板，不要重写）**：不变的控制面。node 的 Auto 区包括 `## Node Goal`、`## Entry Check`、`## Skill Implementation`、`## Required Skill Calls`、`## Output Schemas`、`## Evidence Record`、`## Guardrails`、`## Exit Check`、`## Recovery`。entry 的 Auto 区包括 `## Workflow Nodes`、`## Skill Bindings`、`## Guardrails And Evidence`、`## Runtime And Recovery`。
+- **Authored 区（你写）**：Auto 区无法得知的领域决策。这是让 Skill "好用"而非"只是能跑"的关键。
+
+## 样例：`substance` 节点的 Guidance 区（workflow-kernel）
+
+下面是 research-writer workflow 中"Research"生产者节点的 `## Guidance` 正文。注意它是**决策内容**：前提、有序的领域步骤、超出机械 Exit Check 的完成判断、Red flags。它按名引用绑定的 Skill，但不复制其正文。
+
+```markdown
+## Prerequisites
+
+- entry 的 Decision Core 已确认研究主题与范围。
+- `research-skill` 在项目 Skill 池中可解析；若缺失，先停下询问用户，不要临时替代。
+
+## Steps
+
+1. 加载 `research-skill` 并按其发现方法处理已确认主题。当项目 Skill 定义了特定来源顺序时，不要用通用网络搜索替代。
+2. 按优先级收集来源；为每个来源记录来源、日期和你要复用的论点。不通过项目可信度门槛的来源应直接剔除，而不是标注为"偏弱"。
+3. 把发现提炼到 `notes/*.md` 笔记文件——每条独立论点一份，含逐字引用与来源指针。综合写在 writer 节点，不在这里。
+4. 记录 `research.notes.v1` 的 `summary` evidence：一段提炼 + 产出的笔记数量。
+
+## Completion reasoning
+
+本节点完成当且仅当两条同时成立：(a) 已记录 `summary` evidence；(b) 至少一个 artifact 匹配 `notes/*.md`。不要仅仅因为步骤清单走完就退出——如果相对主题范围笔记仍偏稀疏，应继续研究而非宣布完成。Exit Check 脚本会机械地强制 artifact + evidence 要求；你的职责是判断研究是否真正充分。
+
+## Red flags
+
+- 记录了 `summary` 却没有产出任何 `notes/*.md` 就退出（guardrail 会阻塞——不要试图绕过）。
+- 把来源原文复制进笔记却不加引用标记或来源指针。
+- 某来源仍"待核实"就推进到 Write 节点——核实属于本节点。
+- 对需要多视角的主题，仅凭单一来源就认为充分。
+```
+
+用 `###` 子标题，使其嵌套在 `## Guidance` 之下。上述四段（Prerequisites / Steps / Completion reasoning / Red flags）是 `substance` 节点的预期形态。
+
+## 样例：entry Decision Core（workflow-entry）
+
+下面是 entry SKILL.md 的 `## Decision Core` 正文。entry 是**每次调用最先读取的文件**——一个薄 Decision Core（"跑 next，照做"）会让整个 Skill 感觉机械。一个富 Decision Core 是 comet 级 Skill "好用"的核心。
+
+Decision Core 应建模 Auto 区不处理的三件事：(1) **语义化当前节点检测**（如何判断用户在哪个 Node，而非只看脚本输出），(2) **resume 与 drift 规则**（上下文恢复或状态与文件冲突时怎么办），(3) **决策点与 Red flags**（何时暂停等用户，以及什么是假进展）。
+
+```markdown
+### 自动节点检测
+
+**Step 0：确定当前节点与意图**
+
+1. 检查 workflow protocol 的有序 Node 列表。第一个未完成（无 Exit evidence 记录）的 Node 是候选当前节点。
+2. 若用户描述的工作明显属于更后面的 Node（如"验证结果"但研究尚未完成），暂停并说明：前序 Node 必须先完成。不要跳过。
+3. 若用户描述的工作属于已标记完成的更早 Node，视为纠正——重置该 Node 的完成状态并重新进入。
+
+**Step 1：读取 workflow 状态**
+
+运行 `node "$WORKFLOW_STATE" status` 确认检测到的节点。若脚本的 `NEXT:` 输出与文件证据冲突（如脚本说 DONE 但无 artifact），以文件为准，先纠正状态再继续。
+
+**Resume 规则**：
+- 每次上下文恢复，重新执行 Step 0 和 Step 1。不要信任对话历史做节点检测。
+- 若状态显示某 Node 已完成但预期 artifact 缺失，视为未完成并重新进入。
+- 若用户在某个 Node 中途恢复但话题变了，确认是继续当前 Node 还是开始新的。
+
+### 决策分类与决策点
+
+先分类再行动：有两个或以上会改变范围、行为、风险接受或不可逆结果的合法选项才是用户决策；唯一安全下一步直接执行；缺少依赖、状态损坏或无法继续的 guard 失败是停止条件；`NEXT: manual` 只是交还控制权。只有第一类必须暂停。
+
+| 情况 | 处理 |
+|------|------|
+| 首次调用且主题/范围明确 | 自动初始化状态并进入第一个 Node；不得为了确认已知信息而停顿 |
+| 主题、范围或目标 Node 存在两个以上互斥且合法的解释 | 合并为一个问题，让用户选择；不要猜测 |
+| Node 需要用户确认输出才能推进 | 记录 evidence 后停下；等待明确确认 |
+| WARNING/偏差接受或不可逆发布存在真实取舍 | 只展示当前可执行选项，并记录用户选择 |
+
+Node guard 失败时先自动读取证据并执行唯一安全修复；若缺少依赖或状态损坏导致无法继续，报告停止条件和恢复要求。只有恢复方式存在多个会改变范围或风险的合法选项时，才升级为上表中的用户决策。
+
+### Red Flags
+
+| Agent 想法 | 实际风险 |
+|-----------|---------|
+| "首次调用都应该再确认一次" | 清晰输入不需要重复批准；只有互斥解释仍会改变范围时才询问。 |
+| "脚本返回 NEXT: auto，应该立即加载下一个 Skill" | `NEXT: auto` 表示 Node 完成，不是跳过确认。检查下一个 Node 是否有决策点。 |
+| "guard 失败，所以让用户决定怎么办" | 先自动诊断并执行唯一安全修复；无合法动作时报告停止条件，不要发明选项。 |
+| "看起来和上次一样的话题，从上次断点继续" | 始终重新读取状态。对话记忆在上下文压缩后不可靠。 |
+| "Exit Check 通过了，所以工作够好了" | Exit Check 是机械的。你的职责是判断检查之外的质量——稀疏笔记、浅层分析、缺失视角，脚本抓不到。 |
+```
+
+此样例以精简形式建模了 comet 的 Decision Core：语义检测（Step 0 读 Node 顺序，非只看脚本输出）、状态忠实（文件优先于过期状态）、resume 规则（每次恢复重新检测）、阻塞决策点（显式表格）、Red flags（"想法 → 风险"模式，抓 agent 自欺）。
+
+## substance 与 delegates
+
+- **substance** 节点（workflow-kernel）：上面的样例就是标尺。必须有富 Guidance；缺失时该节点渲染为 `AUTHORING PENDING`，Bundle 不得 ready。
+- **delegates** 节点（comet-five-phase-overlay，委托给已安装的富 Skill）：富执行内容由被委托 Skill 承载，**不要复制**。但如果该节点声明了 **Required Skill Calls**（如 execute 节点要求 `elementui`），请写一段聚焦的整合说明——在被委托流程的什么时机必须加载该 Skill、它补充什么 evidence——而不是泛泛一句"加载 X"。例如要求 `elementui` 的 delegates execute 节点：
+
+```markdown
+本节点用 `comet-build` 执行。在其流程之外，每当改动涉及组件库时加载 `elementui`，并在记录 `required-skill:execute.elementui` 检查前确认改动使用了项目认可的组件。不要重复实现 `comet-build` 已做的事。
+```
+
+## 反模式（不要写）
+
+- 一行式 Guidance，如"运行本节点并记录 evidence。"——Auto 区已隐含此意，毫无增量。
+- 整段复制被绑定 Skill 的正文。
+- 重述路由表或 Output Schema 列表（Auto 区已有）。
+- substance 节点没有 `### Red flags`——Red flags 是大部分真实价值所在。

package/assets/skills-zh/comet-any/reference/authoring-protocol.json

@@ -0,0 +1,91 @@
+{
+  "schemaVersion": 1,
+  "description": "/comet-any 的确定性创作契约。主会话解释执行本协议，对称于运行时脚本解释 workflow-protocol.json。后端（domains/bundle/authoring.ts）以同构常量镜像本契约。",
+  "depth": {
+    "quick": { "voters": 1, "maxRounds": 1, "evidenceSource": "llm-single" },
+    "full": { "voters": 3, "maxRounds": 4, "evidenceSource": "llm-multivote" },
+    "dryThreshold": 2
+  },
+  "dag": {
+    "wave1": ["script", "reference", "pause-points"],
+    "wave2": ["workflow-entry", "skill-core"],
+    "barrier": ["skill-review"]
+  },
+  "lanes": {
+    "script": {
+      "brief": "reference/subagents/script-author.md",
+      "claims": [
+        "script:workflow-state",
+        "script:workflow-guard",
+        "script:workflow-handoff",
+        "script:comet-plan",
+        "script:comet-check",
+        "script:comet-hook-guard"
+      ],
+      "producesContentLeaves": []
+    },
+    "reference": {
+      "brief": "reference/subagents/reference-author.md",
+      "claims": [
+        "reference:workflow-protocol",
+        "reference:resolved-skills",
+        "reference:composition-report",
+        "reference:authoring-lanes"
+      ],
+      "producesContentLeaves": []
+    },
+    "pause-points": {
+      "brief": "reference/subagents/pause-points-author.md",
+      "claims": ["pause:decision-points", "pause:recovery"],
+      "producesContentLeaves": [
+        "reference/decision-points.md",
+        "reference/recovery.md"
+      ]
+    },
+    "workflow-entry": {
+      "brief": "reference/subagents/workflow-entry-author.md",
+      "claims": ["workflow-entry"],
+      "producesContentLeaves": ["SKILL.md"]
+    },
+    "skill-core": {
+      "brief": "reference/subagents/skill-core-author.md",
+      "claims": [],
+      "producesContentLeaves": ["../<node-skill>/SKILL.md"]
+    },
+    "skill-review": {
+      "brief": "reference/subagents/skill-reviewer.md",
+      "claims": ["review:skill-review"],
+      "producesContentLeaves": ["reference/skill-review.md"]
+    }
+  },
+  "verify": {
+    "lenses": ["contract-fit", "usability", "evidence-trace", "self-consistency"],
+    "loopUntilDry": true
+  },
+  "merge": {
+    "deterministicBackbone": [
+      "reference/workflow-protocol.json",
+      "scripts/workflow-state.mjs",
+      "scripts/workflow-guard.mjs",
+      "scripts/workflow-handoff.mjs",
+      "scripts/comet-plan.mjs",
+      "scripts/comet-check.mjs",
+      "scripts/comet-hook-guard.mjs",
+      "bundle.yaml",
+      "comet/skill.yaml",
+      "comet/guardrails.yaml",
+      "comet/checks.yaml",
+      "comet/eval.yaml",
+      "reference/resolved-skills.json",
+      "reference/composition-report.md",
+      "reference/authoring-lanes.json"
+    ],
+    "contentLeaves": [
+      "SKILL.md",
+      "../<node-skill>/SKILL.md",
+      "reference/decision-points.md",
+      "reference/recovery.md",
+      "reference/skill-review.md"
+    ]
+  }
+}

package/assets/skills-zh/comet-any/reference/authoring-subagents.md

@@ -0,0 +1,107 @@
+# Authoring Subagents 总览
+
+## 核心原则
+
+`/comet-any` 的创作成果应由平台原生 subagent 分工产出，再交给主会话组装和后端 CLI 记录状态。
+Claude Code、Codex、Gemini、Copilot 等平台的 subagent 调用方式不同，本参考只定义职责、输入和输出；
+具体派发方式使用当前平台提供的原生 subagent 机制。
+
+`reference/subagents/*.md` 是跨平台 lane brief；Claude Code custom agent 必须单独生成到平台 agent 资源，并带 `name`、`description`、`tools`、`model` frontmatter。不要把这些 portable lane brief 直接当作 platform-native custom agent 安装。
+
+先读取本总览，再只把对应角色 brief 交给对应 subagent。不要把六个角色 brief 合并成一个大 prompt；
+主会话负责保留全局上下文、汇总成果、调用 `comet bundle` 和 `comet publish`，subagent 只产出可审查草稿。
+
+平台支持 subagent 时必须调度。没有平台 subagent 能力时，主会话可以使用同一份 brief 以内联方式完成，
+但必须在用户可读摘要和 `reference/authoring-lanes.json` 中标记为 fallback。
+
+所有 subagent 只返回 Markdown 成果和结构化审查结论，不得直接写入 Bundle state，不得执行候选 Skill 的脚本，
+不得运行发布、安装或分发命令。CLI 状态仍由主会话维护。
+
+## 角色 brief
+
+在用户确认 Skill Creator 方案后、运行 `comet creator generate` 或生成源码前，主会话按以下顺序读取并派发：
+
+1. 脚本作者 subagent：`comet-any/reference/subagents/script-author.md`
+2. reference 作者 subagent：`comet-any/reference/subagents/reference-author.md`
+3. workflow entry 作者 subagent：`comet-any/reference/subagents/workflow-entry-author.md`
+4. Skill 核心作者 subagent：`comet-any/reference/subagents/skill-core-author.md`
+5. 停顿点作者 subagent：`comet-any/reference/subagents/pause-points-author.md`
+6. Skill 审查 subagent：`comet-any/reference/subagents/skill-reviewer.md`
+
+角色文件在本 Skill 内的相对路径是：
+
+- `reference/subagents/script-author.md`
+- `reference/subagents/reference-author.md`
+- `reference/subagents/workflow-entry-author.md`
+- `reference/subagents/skill-core-author.md`
+- `reference/subagents/pause-points-author.md`
+- `reference/subagents/skill-reviewer.md`
+
+这些 subagent 的成果先落为可审查草稿，再进入 `reference/authoring-lanes.json`、`reference/skill-review.md`
+和最终 Bundle draft。若任一 subagent 报告 blocking finding，必须停在草稿修复，不得继续 ready。
+
+## 按 DAG 派发
+
+上面的角色 brief 顺序只是创作 DAG 的线性展开，并非要求严格串行。权威 DAG 在 `reference/authoring-protocol.json` 与 `comet creator authoring-plan <name> --depth quick|full --json`：
+
+- **wave1**（`script`、`reference`、`pause-points`）：彼此无依赖。在支持子代理的平台上并发派发这三个。每个只拿到自己的角色 brief、通用输入和 protocol/resolved-skills 路径（文件交接，不共享历史）。
+- **wave2**（`workflow-entry`、`skill-core`）：依赖 script 契约（`NEXT:`/`SKILL:` 输出）。仅在 script lane DONE 后开始。两者之间可并发。
+- **barrier**（`skill-review`）：唯一同步点。仅在 wave1 与 wave2 全部 DONE 后运行；审查者必须读取所有 artifact 与 claim。
+
+无论平台如何：
+
+- 编排遵循 DAG 依赖；只有 barrier 真正等待此前所有 lane。
+- 不支持子代理的平台，主会话按依赖顺序内联执行同样的 lane——语义完全一致，仅延迟不同。在 `reference/authoring-lanes.json` 中按 lane 记录 `dispatchMode: "subagent"` 或 `"inline"`。
+- Claude Code 可把某个 wave 的扇出委托给其 `Workflow` 工具作为可选加速器；这是实现选择，不是契约的一部分。契约是 protocol + schemas + DAG，任何平台都能解释。
+- 每个 lane 产出在下一个依赖 wave 开始前，必须经 `comet creator authoring-record <name> --lane <id> --file <out.json> --json` 校验并记录。
+
+## 通用输入
+
+每个 subagent 都必须拿到同一组上下文：
+
+- 用户确认的目标、起点和语言。
+- `plan.json` 中的 `goal`、`workflow.kind`、`workflow.nodes`、`engineMode`、`runnerMode`，以及规范化后的 `workflow-protocol.json`。
+- `reference/resolved-skills.json` 或等价的真实 Skill 来源摘要。
+- `reference/workflow-protocol.json` 或即将写入该文件的 workflow protocol。
+- `/comet-classic` 定制场景下的受保护边界：`open / design / build / verify / archive`、`.comet.yaml`、decision point、verify-result-transition、archive-delta-sync。
+- 项目级偏好、缺失/歧义候选处理结果、偏离原因、scripts/hooks 可执行披露。
+
+## 输出格式
+
+每个 subagent 返回：
+
+```json
+{
+  "lane": "<lane-name>",
+  "artifacts": [
+    {
+      "path": "reference/example.md",
+      "kind": "reference",
+      "content": "..."
+    }
+  ],
+  "claims": [
+    {
+      "id": "reference:example",
+      "kind": "reference",
+      "paths": ["reference/example.md"],
+      "summary": "说明该成果保证了什么"
+    }
+  ],
+  "findings": []
+}
+```
+
+`claims` 是审查依据，不是装饰字段。缺少关键 claim 时，Skill 审查 subagent 必须阻塞。
+
+## 派发注意事项
+
+- 每次派发必须创建新的 subagent，不得继承主会话历史。主会话只提供该角色需要的 brief、输入路径和必要背景。
+- 必须显式指定 model；平台不支持 model 选择时，在 `reference/authoring-lanes.json` 记录为 platform-default。
+- 使用文件交接：主会话提供路径，不粘贴大段全文。通用输入、来源 Skill 摘要、草稿 artifact 和报告都应以路径交接。
+- 每个 subagent 只接收自己的角色 brief、通用输入和必要 artifact，不接收其他角色的完整 brief。
+- Skill 审查 subagent 必须在其他五个作者角色产出后运行，并读取所有 artifacts 与 claims。
+- 主会话可以要求某个角色返工，但返工结果仍必须回到 `reference/authoring-lanes.json` 和 `reference/skill-review.md`。
+- subagent 不能调用 `comet bundle`、`comet publish`、`comet skill`，也不能执行候选 Skill 的脚本。
+- 如果状态是 `BLOCKED` 或 `NEEDS_CONTEXT`，主会话必须补上下文、拆小任务、换更强模型或询问用户；不得继续组装。
+- 没有平台 subagent 能力时，内联 fallback 必须保留相同的 lane、claim 和 finding 结构。

package/assets/skills-zh/comet-any/reference/bundle-authoring.md

@@ -0,0 +1,166 @@
+# Bundle Authoring 参考
+
+`comet creator` 是 `/comet-any` 的普通 CLI 表面，背后复用 `comet bundle` 的确定性后端。普通用户不需要记忆 Bundle 子命令；Skill Creator 负责把用户确认的 Workflow Contract 写成 plan，再调用 CLI 维护状态。
+
+## Workflow Contract 输入
+
+新的 `plan.json` 使用 `workflow` 作为主输入：
+
+```json
+{
+  "goal": "基于 /comet-classic 的五阶段定制，要求组件库和白盒审查。",
+  "skillCreatorIntent": "customize-comet",
+  "workflow": {
+    "kind": "comet-five-phase-overlay",
+    "name": "team-comet",
+    "goal": "要求组件库和白盒审查。",
+    "nodes": {
+      "execute": {
+        "requiredSkillCalls": [
+          {
+            "skill": "elementui",
+            "reason": "Use project component library during direct implementation."
+          }
+        ]
+      },
+      "subagent-execute": {
+        "requiredSkillCalls": [
+          {
+            "skill": "elementui",
+            "scope": "handoff"
+          }
+        ]
+      },
+      "review": {
+        "requiredSkillCalls": [
+          {
+            "skill": "whitebox-code-standard",
+            "scope": "review"
+          }
+        ]
+      }
+    }
+  },
+  "engineMode": "deterministic",
+  "runnerMode": "standalone"
+}
+```
+
+字段约定：
+
+- `workflow.kind`: `comet-five-phase-overlay` 或 `workflow-kernel`。
+- `workflow.nodes`: 按 Node id 覆盖或增强 Workflow Node。
+- `implementation`: 替换 Node implementation。只能用于允许 override 的 Node。
+- `requiredSkillCalls`: Required Skill Call，要求 Node 内必须调用 Skill。
+- `augmentations`: 增强 Node，不替换主 implementation。每个新增 binding 或 schema 都必须声明 enforcement：`guarded`、`handoff-guarded`、`evidence-only` 或 `advisory`。
+- `satisfies`: producer override 满足的 Output Schema id。
+- `outputSchemas`: 高级 `workflow-kernel` 可以声明自定义 Output Schema。Output Schema 必须挂到具体 Workflow Node 才算生效；只定义在 `workflow.outputSchemas` 里不会触发 guard、eval 或 readiness。
+- `customNodes[].responsibility`: 自定义 Node 必须声明它在 Agent workflow 中承担的职责。
+- `customNodes[].requiredSkillCalls`: 自定义 Node 可直接声明必须调用的 Skill，生成脚本会按 evidence 阻断。
+
+## 内置 Comet Nodes
+
+`comet-five-phase-overlay` 内置这些 Workflow Node：
+
+- `comet-five-phase-overlay` 的主状态只来自 Classic layout resolver 绑定的 `<classic-change-dir>/.comet.yaml`；没有 active change 或多个 active changes 时必须阻塞并请用户选择。
+- 不得创建 `.comet/runs/<workflow>/state.json` 作为 Comet overlay 主状态；overlay 脚本只能读取并推进 `.comet.yaml`，其他文件只能作为 draft、eval 或 publish evidence。
+- `open`: control，保留 Comet intake 和 `.comet.yaml` 初始化。
+- `design`: producer，可 override，但必须满足 `comet.design.v1`。
+- `plan`: producer，可 override，但必须满足 `comet.plan.v1`。
+- `execute`: control，可 require / augment，例如要求 `elementui`。
+- `subagent-execute`: Handoff，可要求子代理使用 `elementui` 并回传 evidence。
+- `review`: Guardrail，可要求 `whitebox-code-standard`。
+- `verify`: control，保留验证和分支收尾。
+- `archive`: control，保留 OpenSpec archive 和 delta sync。
+
+自定义 `workflow-kernel` Node 示例：
+
+```json
+{
+  "id": "delegate-notes",
+  "label": "Delegate Notes",
+  "kind": "handoff",
+  "responsibility": "Delegate release note drafting and require returned evidence.",
+  "implementation": {
+    "skill": "handoff-coordinator",
+    "scope": "handoff"
+  },
+  "requiredSkillCalls": [
+    {
+      "skill": "release-notes",
+      "scope": "handoff"
+    }
+  ],
+  "operations": ["require", "augment"],
+  "outputSchemas": ["release.notes.v1"],
+  "guardrails": [
+    {
+      "id": "handoff-returned",
+      "label": "Handoff returned evidence",
+      "validation": "semantic"
+    }
+  ]
+}
+```
+
+## 生成物
+
+Factory 必须生成：
+
+- entry `SKILL.md`
+- 每个 Workflow Node 对应的 internal Skill
+- `reference/workflow-protocol.json`
+- `reference/resolved-skills.json`
+- `reference/decision-points.md`
+- `reference/recovery.md`
+- `reference/authoring-lanes.json`
+- `reference/skill-review.md`
+- `scripts/workflow-state.mjs`
+- `scripts/workflow-guard.mjs`
+- `scripts/workflow-handoff.mjs`
+- `scripts/comet-plan.mjs`
+- `scripts/comet-check.mjs`
+- `scripts/comet-hook-guard.mjs`
+- `comet/eval.yaml`
+
+三个 `workflow-*.mjs` 按 workflow 契约创作；三个 `comet-*.mjs` 由 factory 确定性生成（plan 别名、必需文件检查、hook guard），同样读取 `workflow-protocol.json`。
+
+`workflow-protocol.json` 是 runtime、eval、review、publish readiness 的共同事实源。
+
+## CLI 生命周期
+
+常用 Creator 命令：
+
+```bash
+comet creator guide --project . --json
+comet creator candidates --json
+comet creator propose <name> --file <plan.json> --json
+comet creator init <name> --file <plan.json> --confirmed-proposal --json
+comet creator resolve <name> --candidate <query> --source <root-or-hash> --json
+comet creator generate <name> --json
+comet bundle compile <name> --platform <id> --json
+comet eval <generated-skill>/comet/eval.yaml --quick --html
+comet eval <generated-skill>/comet/eval.yaml --full --html
+comet publish review <name> --platform <reference-platform> --json
+comet publish approve <name> --reviewer <reviewer> --json
+comet publish run <name> --platform <reference-platform> --json
+comet publish distribute <name> --platform <id> --scope project --preview --json
+```
+
+`<generated-skill>` 是 compile 后生成 Skill 的目录。eval 结果必须登记为当前 draft hash 的 eval evidence；readiness 只读取该 hash 对应的证据，旧 hash 证据只能保留作审计，不能推进 ready。
+
+## Readiness
+
+readiness 必须检查：
+
+- resolved Skills 无 missing / ambiguous。
+- proposal 已确认。
+- `workflow-protocol.json` 可加载。
+- control Node 没有普通 override。
+- producer override 满足 Output Schema。
+- 每个新增 binding 或 schema 都有 `guarded`、`handoff-guarded`、`evidence-only` 或 `advisory` enforcement。
+- 当前 draft hash 的 eval evidence 已存在且未过期。
+- 人工 review 已批准当前 hash。
+- capability gap 和 executable disclosure 已展示。
+
+非 JSON 输出也必须向用户展示 `Readiness:`、`Blockers:`、`Warnings:`、`Evidence:`。

package/assets/skills-zh/comet-any/reference/eval-provider.md

@@ -0,0 +1,66 @@
+# Eval Evidence 参考
+
+## Eval 选择
+
+在任何验证动作前，必须展示：
+
+- `quick` 的预计运行次数、覆盖组件和 token 消耗。
+- `full` 的预计运行次数、覆盖组件和 token 消耗。
+- `skip / quick / full eval` 三个选择。
+
+skip、eval 失败或证据 hash 过期时不得进入 ready；也不得 publish 或 distribute。
+
+普通用户的验证路径保持单一：日常评估统一走 `comet eval`。`/comet-any` 可以在内部登记 eval evidence，但不要把内部登记步骤包装成面向普通用户的替代命令。对普通用户，解释时优先使用“验证”，不要把 `Publish readiness:` 当成第一层概念。
+
+## 结果记录
+
+eval evidence 必须输出结构化 JSON，至少包含：
+
+- 当前 draft hash。
+- 覆盖的 entry Skill 和 internal Node Skill。
+- `workflow-protocol.json` hash。
+- quick 或 full 的选择、token 消耗和结果摘要。
+- Bundle 编译、安全检查和 capability evidence。
+
+只有当前 draft hash 的 eval evidence 可以推进状态。旧 hash 证据可以保留在磁盘用于审计，但不能让当前 draft 进入 ready。
+
+## 人工评审
+
+eval 通过后仍必须人工批准。评审摘要至少包含：
+
+先运行 `comet publish review <name> --platform <reference-platform> --json`，再基于其输出展示：
+
+- Bundle 名称、版本、hash。
+- 多个 entry 与 internal Skill 列表。
+- `planHash`、`preferenceHash` 与 `reference/resolved-skills.json` 真实 Skill 证据，包括项目级偏好模式、required Skill、`sourceSummaries` 与“整理后的工作方式”摘要。
+- 推荐调用顺序与 `preferenceIndex`。
+- 偏离偏好顺序的项和原因。
+- `.comet/skill-preferences.yaml` 是否在 Factory 初始化后发生漂移；`advisory` 模式给出 warning，`strict` 模式阻塞。
+- 稳定组合 Skill Bundle 的 required capability set（必需能力集合）`skills/scripts/rules/hooks/references` 是否声明完整，且 `scripts/rules/hooks` 是否继续作为 required control plane。
+- 是否生成 `comet/skill.yaml`、`comet/guardrails.yaml`、`comet/checks.yaml` 与 `comet/eval.yaml`。
+- `hooks/*.yaml` 是否仅被当作 portable hook descriptor，等待 `comet publish distribute` 编译到目标平台。
+- 能力缺口和可执行披露。
+- eval 选择、token 消耗和结果摘要。
+- `Validate this Skill` 与下一步提示，让用户知道 readiness 为什么可发布或被阻塞。
+
+readiness blockers 会阻止 publish。只要存在当前 draft hash 的 eval evidence 缺失、人工 approval 缺失、required capability gap 或 executable disclosure 未确认，就必须停在评审阶段，不能继续发布。
+
+只有用户显式批准后，才能运行 `comet publish approve` 并发布。
+
+## 分发预览
+
+执行真实分发前，必须先跑 preview：
+
+```bash
+comet publish distribute <name> --platform <id> --scope project --preview --json
+```
+
+preview 是强制检查，不是可选附加项。它应向用户展示：
+
+- `Install preview`
+- planned files
+- unsupported capability
+- executable disclosures
+- `No files were written`
+
+只有当用户确认 preview 结果后，才可以移除 `--preview` 执行真实分发。

package/assets/skills-zh/comet-any/reference/subagents/pause-points-author.md

@@ -0,0 +1,81 @@
+# 停顿点作者 subagent
+
+本文件是 portable lane brief，不是 platform-native custom agent；如需 Claude Code custom agent，必须另行生成平台 agent 资源和 frontmatter。
+
+## 职责
+
+设计用户在 Skill 中真正必须选择的位置，以及跨设备断点恢复方式。必须先区分四类情况：用户决策、自动处理、停止条件和手动衔接。只有存在两个或以上会改变范围、行为、风险接受或不可逆结果的合法选项时，才创建用户停顿点；单一安全动作直接执行，缺少依赖或状态损坏只报告停止条件，手动衔接只交还控制权。真正的用户决策不能被默认推荐、历史偏好或自动推进绕过。
+
+必须覆盖：
+
+- `reference/decision-points.md`
+- `reference/recovery.md`
+
+## 输入
+
+读取主会话提供的通用输入，尤其关注：
+
+- Skill Creator 方案确认页中的 `confirm-generate`、`revise-proposal`、`cancel`：这是会改变生成结果的用户决策。
+- eval 工作量选择 `skip / quick / full eval` 和安装前人工批准：只有确实存在多个合法选项时才是用户决策。
+- 当前 draft hash 的 eval evidence 缺失或过期、unresolved、ambiguous、capability gap、executable disclosure：逐项判断是可自动修复、无路可走的停止条件，还是确有多个恢复选项的用户决策；不得统一写成停顿点。
+- runner 恢复状态和跨设备恢复入口：复用仍有效的持久化选择，不得在恢复时重复询问。
+
+使用文件交接：主会话提供路径，不粘贴大段全文。不要继承主会话历史；只使用本 brief、通用输入、
+workflow protocol 和已有草稿。
+
+## 派发模板
+
+主会话派发时使用当前平台的 subagent 机制，形状应包含：
+
+```text
+description: "设计 <bundle-name> 的用户停顿点和恢复"
+model: <必须显式指定 model>
+prompt:
+  你是停顿点作者 subagent。
+  先读取本 brief、通用输入路径、workflow protocol 路径、Skill 草稿路径和报告文件路径。
+  开始前先把候选节点分类为用户决策、自动处理、停止条件或手动衔接。如果分类所需事实缺失，先返回 NEEDS_CONTEXT。
+  不要猜测缺失选择，也不要把自动修复、guard 失败、能力缺口、单一合法动作或手动衔接伪装成用户停顿点。
+  只产出 decision-points 和 recovery 草稿，不写 Bundle state，不执行候选脚本。
+  把完整停顿点草稿写入报告文件路径，并只返回 15 行以内状态摘要。
+```
+
+## 输出要求
+
+返回草稿时先列分类表，再说明真正的用户停顿点：
+
+- 每个候选节点属于用户决策、自动处理、停止条件还是手动衔接，以及判定依据。
+- 每个停顿点的触发条件。
+- 用户可选择项。
+- 每个选择会进入哪个阶段。
+- 停顿点证据写入哪里。
+- 自动处理如何直接推进；停止条件如何报告恢复条件而不发明选项。
+- 恢复时如何显示当前阶段、阻塞原因、建议下一步和真实可选项，并复用已持久化选择。
+
+停顿点必须适配当前 workflow protocol，不得只列 Comet 原始停顿点。
+
+## 自检
+
+返回前逐项检查：
+
+- 每个用户停顿点都有触发条件、选项、下一阶段和证据位置。
+- 每个停顿点至少有两个当前可执行的合法选项；相邻且可同时回答的选择已合并，单一合法值不会制造停顿。
+- guard 失败、确定性重试、状态对账、能力缺口和 `NEXT: manual` 已按实际情况归入自动处理、停止条件或手动衔接，而不是默认询问用户。
+- 默认推荐、历史偏好和自动推进都不能绕过必须停顿点。
+- 恢复摘要能显示当前阶段、阻塞原因、建议下一步和真实可选项，且不会重复询问仍有效的选择。
+- 跨设备恢复不依赖当前会话记忆。
+- 停顿点适配当前组合 Skill，不只是照列 Comet 原始停顿点。
+
+## 必须返回的 claim
+
+- `pause:decision-points`
+- `pause:recovery`
+
+缺少任一 claim 时，Skill 审查必须阻塞。
+
+## 状态返回
+
+状态必须是 `DONE`、`DONE_WITH_CONCERNS`、`NEEDS_CONTEXT`、`BLOCKED`。
+
+完整报告写入报告文件路径。返回给主会话的摘要只返回 15 行以内状态摘要，包含状态、报告文件路径、
+claim 列表、未解决疑虑和恢复风险。若状态是 `BLOCKED` 或 `NEEDS_CONTEXT`，必须直接说明缺什么上下文、
+尝试过什么、需要主会话如何处理。