@peterxiaoyang/superspec 0.1.36 → 0.1.37

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peterxiaoyang/superspec",
-  "version": "0.1.36",
+  "version": "0.1.37",
   "description": "SuperSpec 流程引擎 — transition engine with lightweight fact-sync",
   "type": "module",
   "engines": {

package/templates/workflow/AGENTS.md

@@ -1,7 +1,7 @@
 <!-- SUPERSPEC:AGENTS:START -->
 本项目启用 SuperSpec。使用 `superspec-*` 工作流时，以 `superspec transition next --change "<change>"` 返回的下一步为准；流程完成前不得跳阶段、不得自称完成。
 
-即使用户没有显式调用 `superspec-*`，如果新输入像是在改变业务规则、产品口径、验收标准、示例规范或影响范围，编辑代码前先提醒并做只读确认：这是实现偏差，还是需要先回 `superspec-propose` 更新计划文档；不要直接把这类自然语言当作 apply 授权。
+即使用户没有显式调用 `superspec-*`，如果新输入像是在改变业务规则、产品口径、验收标准、示例规范、影响范围，或说明 PRD/文档/原型等需求源已更新，编辑代码前先提醒并做只读确认：这是实现偏差，还是需要先回 `superspec-propose` 更新计划文档；不要直接把这类自然语言当作 apply 授权。
 
 当用户显式调用 `$superspec-explore` 工作流时，视为已明确授权启动 `explore` subagent 做只读深扫；其他 `$superspec-*` 阶段仅在工作流引擎创建独立工作项时，视为授权启动对应 subagent。
 

package/templates/workflow/prompts/code-reviewer.md

@@ -36,6 +36,7 @@ argument-hint: "本次代码审查说明"
 - 是否存在明显性能、兼容性或维护风险。
 - 是否缺少当前任务要求的关键测试或回归验证。
 - 是否引入和当前任务目标无关的代码改动。
+- 如果工作项、用户输入或引用材料显示需求源已更新，但 proposal/design/tasks/test-contract 没有体现最新口径或 `## 需求变化` 处理，不要把旧计划当成最新依据；按方案或需求问题归因。
 
 可以阻塞流程的问题：
 

package/templates/workflow/prompts/explore.md

@@ -21,6 +21,7 @@ argument-hint: "本次探索说明"
 ## 本次任务说明
 
 如果主流程提供本次任务说明，先读取其中指向的 refs。以本次任务说明中的目标范围、来源 refs、必读 refs、artifact refs 和停止条件为准；不要依赖本 prompt 记忆输出 schema。
+如果本次任务说明表示 PRD、文档、原型或其它需求源已更新，但只提供旧 artifact 或旧 refs，不要把旧内容当作最新事实；在输出中标记需要主流程重新核对需求源，并说明可能影响范围、验收或用户可见行为的点。
 
 ## 深扫输出要求
 
@@ -28,7 +29,9 @@ argument-hint: "本次探索说明"
 
 输出至少区分：
 
-- 已确认事实
+- 已确认事实（有源码/文档锚点、命令输出或用户确认直接支撑）
+- 基于锚点的推断（写明依据）
+- 未知/证据缺口（说明是否阻塞；影响范围、验收、用户可见行为、数据或安全相关未知交给主流程确认）
 - 影响范围候选
 - 风险和隐性约束
 - 需要主流程确认的问题

package/templates/workflow/prompts/verifier.md

@@ -34,6 +34,7 @@ argument-hint: "本次验证说明"
 - 代码审查提出的阻塞问题是否都有合法闭环；审查修复是否有自身验证和必要的回归验证，回归 test-run 优先用 `covers_task_ids` 说明覆盖了哪些已完成任务。
 - 已完成任务、测试记录、审查记录和提交给 verifier 的证据，是否能对应到 proposal、design、tasks、test-contract 的目标。
 - 计划材料是否被绕过工作流改写；合法自动勾选和代码审查追加的修复项以工作项说明和事件记录为准。
+- 工作项、用户输入或引用材料显示需求源已更新时，最终证据必须能对应已处理该变化的最新计划材料；仍引用旧计划且无 `## 需求变化` 处理时，按证据不足失败。
 - RED/GREEN 证据是否同一次任务尝试闭环；退出码、环境错误或构建错误不能单独作为行为证明。
 - 输入数据来源核查是否闭环；不得只用 GREEN 测试或 task 勾选证明输入完整性。
 

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

@@ -27,10 +27,10 @@ metadata:
 
 每个 task 的标准循环：
 
-1. **设计核对**：执行 `task-start` 前，确认本任务符合 `design.md` 的实现方向。缺少方向时先停止，不写 RED。
+1. **计划核对**：执行 `task-start` 前，确认当前 task 是 `tasks.md` 顶格任务，并能对应 `design.md` 的实现方向和 `proposal.md` 的 `## Impact` 受影响原因。缺少映射、需要新增能力/验收/影响范围时先停止，交回 propose，不写 RED。
 2. **任务开始**：`superspec transition task-start --change "<change>" --task <task_id>`。
 3. **读取 attempt_id**：从 task-start 返回结果或当前活跃 task attempt 中读取。
-4. **RED**：写测试，运行后确认失败，并用 `superspec record test-run --change "<change>" --input -` 登记。
+4. **RED**：写测试前确认测试意图能对应 `test-contract.md` 的 `test_id` 或 `business-invariants.md`；缺少对应关系时先停止，交回 propose。运行后确认失败，并用 `superspec record test-run --change "<change>" --input -` 登记。
 5. **实现**：根据任务写代码，保持范围小。`design.md` 不锁死字段名、函数名、SQL 或局部写法。
 6. **GREEN**：运行测试确认通过，并登记 test-run。
 7. **完成 task**：`superspec transition task-complete --change "<change>" --task <task_id>`。
@@ -74,7 +74,7 @@ no-TDD 任务（`tdd_required:false` + `no_tdd_reason`）跳过 RED/GREEN，但
 - 需要判断影响范围或改动原因不自明时，参考 `proposal.md` 的 `## Impact`，但不要把它当作路径白名单。
 - 编码时发现未列入影响范围的文件，如果从 diff 或引用链能直接解释为同一任务下的局部引用、测试辅助或机械连带改动，可以继续。
 - 如果发现新增能力、用户可见行为、明显新增影响范围或原因不自明，停止扩大实现并报告给主流程；不要在 apply 阶段补改 `proposal.md`。
-- 用户在 apply 期间或 apply 后补充最新业务规则、产品口径、验收标准、示例规范、兼容策略或影响范围时，停止实现并交回主流程使用 `superspec-propose` 更新计划文档。
+- 用户在 apply 期间或 apply 后补充最新业务规则、产品口径、验收标准、示例规范、兼容策略、影响范围，或说明需求源已更新时，停止实现并交回主流程使用 `superspec-propose` 更新计划文档；交回时说明变化来源、变化内容、影响范围和建议处理方式。
 - 不修改 `proposal.md`、`design.md`、`specs/**` 或 `.superspec/**`。
 - active attempt 期间不要修改 `tasks.md` 中除 `task-complete` 自动勾选目标 checkbox 外的内容。
 - 不跳过 RED 直接写 GREEN。

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

@@ -21,7 +21,7 @@ metadata:
 
 如果下一步提示当前阶段还有用户确认、审查或验证事项，先完成这些事项。完成前不要进入下一阶段，也不要修改业务代码；就绪或审查后只概括关键事实、真实待确认项和下一步。
 
-如果下一步说明 discovery 不完整或有未确认问题，先检查并填写 discovery 草稿，不要把草稿占位、格式缺口或路径空白直接转问用户；只有影响范围、验收标准、用户可见行为、数据来源或安全边界存在真实阻塞时才向用户提问，收到回答后优先用 `superspec record user-decision --change "<change>" --input -` 从 stdin 登记 JSON 内容；文件路径模式仍可作为 fallback。
+如果下一步说明 discovery 不完整或有未确认问题，先检查并填写 discovery 草稿，不要把草稿占位、格式缺口或路径空白直接转问用户；用户明确说 PRD、文档、原型或其它需求源已更新时，先重新核对来源，不要复用旧依据；只有影响范围、验收标准、用户可见行为、数据来源或安全边界存在真实阻塞时才向用户提问，收到回答后优先用 `superspec record user-decision --change "<change>" --input -` 从 stdin 登记 JSON 内容；文件路径模式仍可作为 fallback。
 
 本技能默认走完整审查路径。探索完成后，`explore → propose` 会先创建 `critic` 工作项，由 Critic 角色审查需求澄清记录。审查完成后优先通过 `superspec record job-submit --change "<change>" --job <JOB> --report -` 从 stdin 登记 JSON 报告内容；文件路径模式仍可作为 fallback。
 
@@ -81,6 +81,7 @@ metadata:
 只有 `## 待确认问题` 段落内的 `- [ ]` 表示阻塞确认项。其他段落列事实、风险或影响范围时使用普通 bullet，不要用 checklist。
 
 代码影响型需求的 `当前代码事实`、`影响范围候选`、`风险和边界` 应尽量包含 `path:line` 锚点。纯文档、配置或新文件任务没有代码锚点时，写明 `N/A` 理由并引用相关文档、配置或需求来源。
+有源码/文档锚点、命令输出或用户确认直接支撑的内容，才写成事实；只有间接锚点支撑的，写为推断并说明依据；没有支撑的，写为未知并说明是否阻塞。影响范围、验收、用户可见行为、数据来源或安全边界的未知必须进入待确认问题，或说明非阻塞理由。
 
 ### 输入数据来源核查
 

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

@@ -144,6 +144,8 @@ superspec record user-decision --change "<change>" --input -
 
 然后把用户决定反映到 proposal/design/test-contract，并将对应确认项改为 `[x]` 或移出未确认列表。局部实现细节、命名、普通文件组织和不影响需求/验收/风险的技术微调不要升级为用户确认。
 
+进入 propose 后出现新的业务规则、产品口径、验收标准、示例规范或需求源更新时，不要静默覆盖原计划；默认先在 `proposal.md` 记录 `## 需求变化`，说明变化来源、变化内容、影响范围和处理方式（更新当前 change / 新建后续 change / 暂不处理）。只有影响技术路线、测试契约或业务不变量时，才同步更新 `design.md`、`test-contract.md` 或 `business-invariants.md`。
+
 ## 完成条件
 
 tasks.md 作为计划文档就绪（不是复选框全完成）+ 基础职责文档齐全 → next 返回 propose-ready 命令。