@peterxiaoyang/superspec 0.1.2 → 0.1.4

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

@@ -18,6 +18,8 @@ metadata:
 - 对话窗口里的解释、审查结论、验证结论、提问和下一步说明必须使用中文；除命令、路径、字段名、代码标识符外，不要夹带英文说明词。
 - 对话窗口、AskUserQuestion 文案、进度更新和最终总结不得裸露内部证据种类、字段名或 reason code；用户确认记录、审查问题记录、审查轮次编号、问题唯一标识等都只用中文业务说法。原始协议名只允许写在证据 JSON、代码、测试、精确命令输出或用户明确要求的诊断片段中。
 - 本 skill 文档中的内部协议名只用于落盘证据或运行 guard；写给用户时必须先翻译成中文业务动作，例如“记录用户确认”“记录审查问题”“完成最终审查判断”。
+- 用户可见文案不得使用“裁决”描述用户动作；统一说“确认”“范围取舍”“处理方式选择”或“用户确认记录”。
+- 普通 workflow 命令使用 `--format agent` 读取 guard/init 输出；`--format json` 只用于诊断 evidence/schema/guard 内部，不得作为默认模型上下文或直接转述给用户。
 - 向用户转述 guard / review / verification 输出时，不要直接贴英文 `message`、`next_allowed_actions`、`Summary`、`Justification`、`PASS/FAIL` 等模板词；应改写为中文，并仅在需要定位内部协议时保留英文 code/command 于反引号中。
 
 ## 命令执行 / Shell
@@ -25,6 +27,14 @@ metadata:
 - Windows PowerShell 中执行 npm 全局 bin 时，必须显式使用 `.cmd` shim：`superspec.cmd ...`、`openspec.cmd ...`；不要运行 `superspec.ps1` 或 `openspec.ps1`。
 - macOS、Linux、Git Bash、cmd.exe 或其他不会优先拦截 `.ps1` 的 shell 中，继续使用文档中的 `superspec ...`、`openspec ...` 命令。
 
+## 上下文读取纪律 / Context Budget
+
+- guard 可以在本地读取完整 `.superspec/evidence/**/*.json` 并重算判定；主流程默认不要打开完整 evidence JSON，除非正在排查 guard block、修复 schema，或用户明确要求诊断原文。
+- 主流程默认只读取 guard decision、当前 review 必要 artifact、native subagent `output_ref` 的摘要/结论段、`required_load_refs` 指向的关键 source，以及 final verification 的摘要。
+- `source_refs` 只是可追溯来源，不等于必须读取；只有 `required_load_refs` 是主流程必须亲自读取并写入 `loaded_refs` 的内容。
+- raw log、长报告和历史 superseded evidence 默认只作为引用、hash 或摘要保留；不要把全文复制进对话上下文或新的 evidence。
+- guard-only read 不能替代主流程的 `loaded_refs`：凡进入 `required_load_refs` 的材料，主流程必须真实读取后再写 `main_adjudication`。
+
 ## 硬边界
 
 - `review_complete` 是 allow-only gate。只有 `main_adjudication.review_decision:"allow"` 才允许进入 `check-review-complete` / `archive_ready`。
@@ -47,7 +57,7 @@ metadata:
 Review 前必须确认这些 SuperSpec distribution files 存在；缺失、无效或当前 Codex surface 无法从它们启动 native subagents 时，review gate 必须 block：
 
 ```text
-superspec guard check-init --change "<change>"
+superspec guard check-init --change "<change>" --format agent
 ```
 
 Required project-scope files: `.codex/agents/code-reviewer.toml`、`.codex/prompts/code-reviewer.md`、`.codex/agents/architect.toml`、`.codex/prompts/architect.md`、`.codex/agents/critic.toml`、`.codex/prompts/critic.md`、`.codex/agents/verifier.toml`、`.codex/prompts/verifier.md`。
@@ -56,15 +66,15 @@ Required project-scope files: `.codex/agents/code-reviewer.toml`、`.codex/promp
 
 1. 检查 review readiness：
    ```text
-   superspec guard check-review-ready --change "<change>"
+   superspec guard check-review-ready --change "<change>" --format agent
    ```
-2. 从 `git diff`、OpenSpec artifacts、tasks、business invariants、test contract、red/green evidence 和 `.superspec` evidence 构建审查范围。
+2. 从 guard decision、`git diff`、OpenSpec artifacts、tasks、business invariants、test contract、RED/GREEN 摘要和 live role output 摘要构建审查范围；不要默认打开完整 `.superspec/evidence/**/*.json`。
 3. 运行 repo-local review guidance：
    - 启动 repo-local `code-reviewer` native subagent，记录审查指导证据（内部 JSON kind 为 `source_guidance`）。
    - 启动 repo-local `architect` native subagent，记录审查指导证据（内部 JSON kind 为 `source_guidance`）。
    - 启动独立 repo-local `critic` native subagent，审查 superspec-specific scope drift、隐藏假设、业务不变量是否被测试/实现扭曲、遗漏的 rollback targets 和 evidence 充分性，并记录审查指导证据（内部 JSON kind 为 `source_guidance`）。
 4. 主流程读取关键 source，准备 `main_adjudication` 输入：
-   - 从每条 `source_guidance.source_refs` 中判断哪些内容需要亲自加载。
+   - 从每条 `source_guidance.source_refs` 中判断哪些内容确实需要亲自加载，不要把所有来源自动升级为必须读取。
    - `source_refs` / `required_load_refs` 使用 `pinned_ref = {path, blob_sha}`；其中 `pinned_ref.path` 一律是 repo-root relative path。`required_load_refs` 必须按 `(path, blob_sha)` 精确包含于 `source_refs`。
    - 对所有 `required_load_refs` 做真实读取，并在 `loaded_refs` 中记录同样的 `pinned_ref`；`loaded_refs` 必须按 `(path, blob_sha)` 精确覆盖全部 `required_load_refs`，同一路径不同 blob 不算已加载。
    - 对所有 `required_claim_ids` 写出结构化 `claim_adjudications[] = {claim_id, decision, rationale}`。
@@ -97,7 +107,7 @@ Required project-scope files: `.codex/agents/code-reviewer.toml`、`.codex/promp
    - `request_changes` 只负责给出结构化回退方向，不直接修改 task checkbox。
 8. 仅在 allow path 检查 review completion：
    ```text
-   superspec guard check-review-complete --change "<change>"
+   superspec guard check-review-complete --change "<change>" --format agent
    ```
    - 只有最终 allow path 才应执行并通过这一步。
    - 如果本轮 `main_adjudication.review_decision:"request_changes"`，则本轮 review 的正确出口是停止并回到对应路由；不要把 `request_changes` 轮次伪装成 `review_complete`。