@peterxiaoyang/superspec 0.1.10 → 0.1.12

package/templates/workflow/skills/superspec-explore/SKILL.md

@@ -10,7 +10,7 @@ metadata:
 
 ## 语言规则 / Language
 
-- 默认使用简体中文写人类可读内容；命令、路径、字段名、gate 名、task/test id、代码标识符保留原文。
+- 默认使用简体中文写人类可读内容；命令、路径、字段名、阶段门名、task/test id、代码标识符保留原文。
 - 用户可见文案不得使用“裁决”描述用户动作；统一说“确认”“范围取舍”“处理方式选择”或“用户确认记录”。
 - 不把内部证据种类、reason code、JSON 字段大全直接转述给用户；需要诊断时才引用原文。
 - 普通 workflow 命令使用 `--format agent`；`--format json` 只用于诊断，不作为默认上下文。
@@ -24,14 +24,12 @@ metadata:
 
 Explore 只做需求澄清、代码事实调查、范围边界和风险记录。产物是 `openspec/changes/<change>/.superspec/artifacts/discovery.md`；不写 `proposal.md`、`specs/**`、`design.md`、`tasks.md`，也不改实现代码。
 
-## 第一条必跑命令
+## 产物格式
 
-先尝试建立当前 change 的 SuperSpec hook session。R-1/provenance 未通过时该命令只会记录 audit-only lease 和降级诊断，不代表 mechanical enforcement 已启用：
+- discovery.md 必须按 SuperSpec discovery 模板的结构填写，保留全部段落：`调查范围` / `现有实现事实` / `隐性合约` / `风险与歧义` / `待确认问题` / `Subagent Evidence`；不得自创或删减段落骨架。
+- 第一条必跑命令 `superspec check workflow-packet --change "<change>" --gate explore_complete --format agent` 的返回里带 `discovery_template` 与 `discovery_rules`：按其中的模板骨架和填写规则产出，而不是自由发挥，这样无论哪个模型产物结构都一致。
 
-```text
-superspec guard hook-session-begin --change "<change>" --workflow superspec-explore --entrypoint-token "<fresh-entrypoint-token>" --format agent
-superspec guard hook-session-status --change "<change>" --format agent
-```
+## 第一条必跑命令
 
 ```text
 superspec init --scope project --format agent
@@ -42,11 +40,11 @@ superspec init --scope project --format agent
 ```text
 openspec list --json
 openspec status --change "<change>" --json
-superspec guard check-init --change "<change>" --format agent
-superspec guard workflow-packet --change "<change>" --gate explore_complete --format agent
+superspec check check-init --change "<change>" --format agent
+superspec check workflow-packet --change "<change>" --gate explore_complete --format agent
 ```
 
-遇到任何 guard `block` 就停止，按 packet 的 `next_action` 处理；不要绕过 guard。
+遇到 `block` 就停止，按检查结果的下一步提示处理；不要绕过检查。
 
 ## OpenSpec 边界
 
@@ -55,32 +53,33 @@ superspec guard workflow-packet --change "<change>" --gate explore_complete --fo
 - OpenSpec 负责 change 结构和后续 artifact 语义；本阶段只补 SuperSpec discovery 证据。
 - 如果发现需要正式方案、规格、设计或任务，先写入 discovery，再交给 `superspec-propose`。
 
-## Native Subagent 边界
+## 专用代理边界
 
-需求 critique 必须来自 repo-local `critic` native subagent。生成 prompt 时使用 packet，而不是把 disclosure 协议常驻在 skill 正文：
+需求审查由本仓库的 `critic` 专用代理完成。生成审查提示时使用检查命令的输出，而不是把披露协议常驻在 skill 正文：
 
 ```text
-superspec guard review-packet --change "<change>" --gate explore_complete --role critic --round 1 --format prompt
+superspec check review-packet --change "<change>" --gate explore_complete --role critic --round 1 --format prompt
 ```
 
-主流程整理审查问题时读取 main-thread packet：
+主流程整理审查问题时读取主线程提示信息：
 
 ```text
-superspec guard review-packet --change "<change>" --gate explore_complete --role main-thread --round 1 --format agent
+superspec check review-packet --change "<change>" --gate explore_complete --role main-thread --round 1 --format agent
 ```
 
-round > 1 的 reviewer prompt 必须使用 packet/ledger 注入；不要手写历史问题清单。
+第二轮及以后的审查，必须由检查命令把上一轮的问题注入提示；不要手写历史问题清单。
 
 ## 用户确认边界
 
 - 关键范围、非目标、验收标准、业务语义或设计边界问题必须面向用户说明并等待明确确认。
 - 探索结论、范围边界和进入 propose 的授权必须等待用户确认后再记录 evidence。
+- discovery.md 必须含 `## 待确认问题` 段（标题含「确认」字样即可，如「待确认问题」「需要用户确认的问题」）。每条问题用 `- [ ]`（未决）或 `- [x]`（已确认）标记；也可在已确认项写「已确认：」。**该段只要还有 `- [ ]` 或「仍需确认/待确认」项，`explore_complete` 检查就不会通过**，不得记录人工确认，也不得进入 propose。
 - 用户看到的文字要用中文业务语言；内部 JSON 名只写进证据、命令输出或诊断片段。
 
 ## 完成检查
 
 ```text
-superspec guard workflow-packet --change "<change>" --gate explore_complete --format agent
+superspec check workflow-packet --change "<change>" --gate explore_complete --format agent
 ```
 
-只有 packet 显示 allowed 后，才进入 `superspec-propose`。
+只有检查结果显示通过后，才进入 `superspec-propose`。

package/templates/workflow/skills/superspec-propose/SKILL.md

@@ -10,7 +10,7 @@ metadata:
 
 ## 语言规则 / Language
 
-- 默认使用简体中文写人类可读内容；命令、路径、字段名、gate 名、task/test id、代码标识符保留原文。
+- 默认使用简体中文写人类可读内容；命令、路径、字段名、阶段门名、task/test id、代码标识符保留原文。
 - 用户可见文案不得使用“裁决”描述用户动作；统一说“确认”“范围取舍”“处理方式选择”或“用户确认记录”。
 - 不把内部证据种类、reason code、JSON 字段大全直接转述给用户；需要诊断时才引用原文。
 - 普通 workflow 命令使用 `--format agent`；`--format json` 只用于诊断，不作为默认上下文。
@@ -26,18 +26,11 @@ Propose 把 discovery 转成 OpenSpec proposal package，并补 SuperSpec 业务
 
 ## 第一条必跑命令
 
-先尝试建立当前 change 的 SuperSpec hook session。R-1/provenance 未通过时该命令只会记录 audit-only lease 和降级诊断，不代表 mechanical enforcement 已启用：
-
-```text
-superspec guard hook-session-begin --change "<change>" --workflow superspec-propose --entrypoint-token "<fresh-entrypoint-token>" --format agent
-superspec guard hook-session-status --change "<change>" --format agent
-```
-
 ```text
-superspec guard workflow-packet --change "<change>" --gate explore_complete --format agent
+superspec check workflow-packet --change "<change>" --gate explore_complete --format agent
 ```
 
-遇到任何 guard `block` 就停止，回 explore 补事实或确认。
+遇到 `block` 就停止，回 explore 阶段补事实或确认。
 
 ## OpenSpec 边界
 
@@ -49,39 +42,50 @@ superspec guard workflow-packet --change "<change>" --gate explore_complete --fo
 openspec instructions <artifact-id> --change "<change>" --json
 ```
 
+## 执行步骤
+
+把 discovery 整理成 OpenSpec proposal package，每个正本 artifact 都通过 OpenSpec 产出引擎生成：
+
+1. 运行 `openspec status --change "<change>" --json`，取 artifact 顺序、状态和 `resolvedOutputPath`。
+2. 每个 artifact（proposal/specs/design/tasks）运行 `openspec instructions <artifact-id> --change "<change>" --json`，取回 template/rules/context/instruction/dependencies。
+3. 先读 dependencies 列出的已完成 artifact，再按 template 写到 `resolvedOutputPath`；context/rules 是对作者的约束，不写进产出文件。
+4. sidecar（`.superspec/artifacts/business-invariants.md`、`.superspec/artifacts/test-contract.md`）用 SuperSpec 内置模板，写到 change 内 `.superspec/artifacts/`。
+
 ## Packet 驱动的阶段门
 
-按 artifact 依赖顺序工作，每个门都先读 packet，allowed 后才进入下一段：
+按 artifact 依赖顺序工作，每个门都先读检查结果，通过后才进入下一段：
 
 ```text
-superspec guard workflow-packet --change "<change>" --gate proposal_reviewed --format agent
-superspec guard workflow-packet --change "<change>" --gate design_complete --format agent
-superspec guard workflow-packet --change "<change>" --gate invariants_reviewed --format agent
-superspec guard workflow-packet --change "<change>" --gate test_contract_drafted --format agent
-superspec guard workflow-packet --change "<change>" --gate tasks_complete --format agent
-superspec guard workflow-packet --change "<change>" --gate apply_ready --format agent
+superspec check workflow-packet --change "<change>" --gate proposal_reviewed --format agent
+superspec check workflow-packet --change "<change>" --gate design_complete --format agent
+superspec check workflow-packet --change "<change>" --gate invariants_reviewed --format agent
+superspec check workflow-packet --change "<change>" --gate test_contract_drafted --format agent
+superspec check workflow-packet --change "<change>" --gate test_contract_honored --format agent
+superspec check workflow-packet --change "<change>" --gate tasks_complete --format agent
+superspec check workflow-packet --change "<change>" --gate propose_complete --format agent
+superspec check workflow-packet --change "<change>" --gate apply_ready --format agent
 ```
 
-`proposal_reviewed` 不是 advisory note；它是硬门。`propose.proposal_reviewed`、`propose.design_reviewed`、`propose.invariants_reviewed`、`propose.test_plan_drafted`、`propose.tasks_mapped` 是兼容别名，packet 输出中的规范 gate 名为准。
+`proposal_reviewed` 不是 advisory note；它是硬门。`propose.proposal_reviewed`、`propose.design_reviewed`、`propose.invariants_reviewed`、`propose.test_plan_drafted`、`propose.tasks_mapped` 是兼容别名，检查结果输出中的规范阶段门名为准。
 
-## Native Subagent 边界
+## 专用代理边界
 
 - proposal review 使用 repo-local `critic`。
 - design review 使用 repo-local `architect`、`critic`、`test-engineer`。
 - business-invariants 和 test-contract review 使用 repo-local `critic` / `test-engineer`。
 - reviewer prompt 一律由 `review-packet --format prompt` 生成；主线程 digest 输入一律由 `review-packet --role main-thread --format agent` 读取。
-- round > 1 必须使用 packet/ledger 注入，不手写历史 finding 清单。
+- 第二轮及以后的审查，必须由检查命令把上一轮的问题注入提示，不手写历史 finding 清单。
 
 ## 用户确认边界
 
-关键范围、非目标、验收标准、业务语义和设计边界问题必须停止并交给用户确认。主线程不能静默关闭这类 finding；需要回 explore 或回上游 artifact 时，按 packet 和 guard 给出的 route 处理。
+关键范围、非目标、验收标准、业务语义和设计边界问题必须停止并交给用户确认。主线程不能静默关闭这类 finding；需要回 explore 或回上游 artifact 时，按检查结果和阶段检查给出的回退路径处理。
 
 设计选项选择、任务审查确认，以及任何会改变范围或验收标准的处理，都必须等待明确用户确认。
 
 ## 完成检查
 
 ```text
-superspec guard workflow-packet --change "<change>" --gate apply_ready --format agent
+superspec check workflow-packet --change "<change>" --gate apply_ready --format agent
 ```
 
 只有 apply-ready allowed 后，才进入 `superspec-apply`。

package/templates/workflow/skills/superspec-review/SKILL.md

@@ -10,7 +10,7 @@ metadata:
 
 ## 语言规则 / Language
 
-- 默认使用简体中文写人类可读内容；命令、路径、字段名、gate 名、task/test id、代码标识符保留原文。
+- 默认使用简体中文写人类可读内容；命令、路径、字段名、阶段门名、task/test id、代码标识符保留原文。
 - 用户可见文案不得使用“裁决”描述用户动作；统一说“确认”“范围取舍”“处理方式选择”或“用户确认记录”。
 - 不把内部证据种类、reason code、JSON 字段大全直接转述给用户；需要诊断时才引用原文。
 - 普通 workflow 命令使用 `--format agent`；`--format json` 只用于诊断，不作为默认上下文。
@@ -26,28 +26,21 @@ Review 合并实现审查、架构审查、SuperSpec critic、final verification
 
 ## 第一条必跑命令
 
-先尝试建立当前 change 的 SuperSpec hook session。R-1/provenance 未通过时该命令只会记录 audit-only lease 和降级诊断，不代表 mechanical enforcement 已启用：
-
-```text
-superspec guard hook-session-begin --change "<change>" --workflow superspec-review --entrypoint-token "<fresh-entrypoint-token>" --format agent
-superspec guard hook-session-status --change "<change>" --format agent
-```
-
 ```text
-superspec guard check-init --change "<change>" --format agent
+superspec check check-init --change "<change>" --format agent
 ```
 
 然后检查 review readiness：
 
 ```text
-superspec guard check-review-ready --change "<change>" --format agent
+superspec check check-review-ready --change "<change>" --format agent
 ```
 
-遇到任何 guard `block` 就停止。review 不直接回改 `tasks.md` checkbox。
+遇到任何返回状态为 `block` 就停止。review 不直接回改 `tasks.md` checkbox。
 
-## Repo-local Native Subagent 边界
+## 专用代理边界
 
-Review 必须使用 SuperSpec 分发包里的 repo-local native agents，不要调用全局 `$code-review`、OMX workflow、main-thread self-review 或普通 markdown 报告替代。
+Review 必须使用本仓库安装的 repo-local native agents（专用代理），不要调用全局 `$code-review`、OMX workflow、主线程自审或普通 markdown 报告替代。
 
 必需入口：
 
@@ -56,12 +49,12 @@ Review 必须使用 SuperSpec 分发包里的 repo-local native agents，不要
 - `.codex/agents/critic.toml` / `.codex/prompts/critic.md`
 - `.codex/agents/verifier.toml` / `.codex/prompts/verifier.md`
 
-每个 reviewer prompt 都先由 packet 生成：
+每个审查提示都先由检查命令产出：
 
 ```text
-superspec guard review-packet --change "<change>" --gate review_complete --role code-reviewer --round 1 --format prompt
-superspec guard review-packet --change "<change>" --gate review_complete --role architect --round 1 --format prompt
-superspec guard review-packet --change "<change>" --gate review_complete --role critic --round 1 --format prompt
+superspec check review-packet --change "<change>" --gate review_complete --role code-reviewer --round 1 --format prompt
+superspec check review-packet --change "<change>" --gate review_complete --role architect --round 1 --format prompt
+superspec check review-packet --change "<change>" --gate review_complete --role critic --round 1 --format prompt
 ```
 
 ## Final Verification 边界
@@ -72,11 +65,11 @@ superspec guard review-packet --change "<change>" --gate review_complete --role
 openspec validate "<change>"
 ```
 
-然后执行 test contract 要求的最终测试，启动 repo-local `verifier` 和 `critic` 做 verification review。verification prompt 也必须由 packet 生成：
+然后执行 test contract 要求的最终测试，启动本仓库 `verifier` 和 `critic` 做验证审查。验证提示也必须由检查命令产出：
 
 ```text
-superspec guard review-packet --change "<change>" --gate review_complete --role verifier --round 1 --format prompt
-superspec guard review-packet --change "<change>" --gate review_complete --role critic --round 1 --kind verification_review --format prompt
+superspec check review-packet --change "<change>" --gate review_complete --role verifier --round 1 --format prompt
+superspec check review-packet --change "<change>" --gate review_complete --role critic --round 1 --kind verification_review --format prompt
 ```
 
 verification 只提供 proof/gap，不替代主流程最终判断。
@@ -86,10 +79,10 @@ verification 只提供 proof/gap，不替代主流程最终判断。
 主线程写最终判断前读取：
 
 ```text
-superspec guard review-packet --change "<change>" --gate review_complete --role main-thread --round 1 --format agent
+superspec check review-packet --change "<change>" --gate review_complete --role main-thread --round 1 --format agent
 ```
 
-`review_complete` 是 allow-only gate。allow path 必须由唯一 `main_adjudication` 承载最终判断，作者边界固定为 `execution_mode:"direct"` + `created_by:"main-thread"`；它不能携带 `agent_role`、`agent_id`、`prompt_ref`。
+`review_complete` 是只允许通过的阶段检查。通过路径由主线程写本轮审查结论（主线程直接写，不携带代理字段）。
 
 `request_changes` 不是 review_complete allow。它必须写清 `request_changes_route`：
 
@@ -103,7 +96,7 @@ request-changes round 不生成 allow-path verification，也不调用 `check-re
 仅 allow path 运行：
 
 ```text
-superspec guard workflow-packet --change "<change>" --gate review_complete --format agent
+superspec check workflow-packet --change "<change>" --gate review_complete --format agent
 ```
 
-只有 packet allowed 后，才进入 `superspec-archive`。
+只有检查结果显示通过后，才进入 `superspec-archive`。

package/dist/src/packet_measure.d.ts

@@ -1,43 +0,0 @@
-export type MeasuredTextFile = {
-    path: string;
-    chars: number;
-};
-export type SurfaceMeasure = {
-    total_chars: number;
-    files: MeasuredTextFile[];
-};
-export type RepresentativeScenarioMeasure = {
-    name: string;
-    description: string;
-    total_chars: number;
-    files: MeasuredTextFile[];
-};
-export type MaterializedTextSample = {
-    name: string;
-    description: string;
-    chars: number;
-    matched_markers?: string[];
-};
-export type MaterializedTextMeasure = {
-    total_chars: number;
-    samples: MaterializedTextSample[];
-};
-export type PacketMeasureReport = {
-    fixed_surface_chars_install_upper_bound: SurfaceMeasure;
-    fixed_surface_chars_runtime_required_subset: SurfaceMeasure;
-    materialized_workflow_packet_chars: MaterializedTextMeasure;
-    materialized_review_packet_chars: MaterializedTextMeasure;
-    materialized_review_prompt_chars: MaterializedTextMeasure;
-    ledger_block_chars: MaterializedTextMeasure;
-    representative_loaded_surface_chars: {
-        scenarios: RepresentativeScenarioMeasure[];
-    };
-};
-type ScenarioSpec = {
-    name: string;
-    description: string;
-    files: string[];
-};
-export declare function representative_scenarios(): readonly ScenarioSpec[];
-export declare function measure_packet_surface_report(repoRoot: string): PacketMeasureReport;
-export {};