@peterxiaoyang/superspec 0.1.39 → 0.1.40

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/package.json +1 -1
  2. package/templates/workflow/agents/explore.toml +1 -1
  3. package/templates/workflow/prompts/explore.md +2 -2
  4. package/templates/workflow/skills/superspec-explore/SKILL.md +5 -4
  5. package/templates/workflow/skills/superspec-propose/SKILL.md +6 -4
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@peterxiaoyang/superspec",
3
- "version": "0.1.39",
3
+ "version": "0.1.40",
4
4
  "description": "SuperSpec 流程引擎 — transition engine with lightweight fact-sync",
5
5
  "type": "module",
6
6
  "engines": {
package/templates/workflow/agents/explore.toml CHANGED
@@ -9,5 +9,5 @@ Task binding: load `.codex/prompts/explore.md` first, then read the current task
9
9
 
10
10
  Boundary: read-only. Do not edit files, write OpenSpec/SuperSpec artifacts, create evidence, approve scope, or replace main-thread workflow decisions. Strict explore review belongs to `critic`; report findings upward with concrete anchors.
11
11
 
12
- Output: concise Simplified Chinese. Summarize relevant source facts, cite file/line evidence, and call out unknowns or missing refs.
12
+ Output: concise Simplified Chinese. Summarize relevant source facts, cite short anchors like ClassName.java:123 or file.ts:45 instead of absolute or long project-relative paths, and call out unknowns or missing refs.
13
13
  """
package/templates/workflow/prompts/explore.md CHANGED
@@ -12,7 +12,7 @@ argument-hint: "本次探索说明"
12
12
  ## 边界
13
13
 
14
14
  - 只读；不要修改文件。
15
- - 必须用 repo search 和文件读取验证事实，结论绑定 `path:line` 或文档锚点。
15
+ - 必须用 repo search 和文件读取验证事实，结论绑定短锚点（类名/文件名:行号）或文档锚点。
16
16
  - 不写 `proposal.md` / `design.md` / `tasks.md` / `specs/**` / `.superspec/**`。
17
17
  - 不作为 `explore_complete` evidence；门禁审查交给 `critic`。
18
18
  - 输出事实、推断、未知、影响范围候选、风险和需要主流程确认的问题；不写实现方案。
@@ -34,7 +34,7 @@ argument-hint: "本次探索说明"
34
34
 
35
35
  不要把自己的理解当成用户需求。用户没有明确说、代码/文档也不能证明的业务语义、验收口径、默认值、边界条件和优先级，只能写为推断或未知；影响实现或验收的未知交给主流程确认。
36
36
 
37
- 代码影响型需求尽量提供 `path:line`。纯文档/配置/新文件没有代码锚点时，写明 `N/A` 理由。
37
+ 代码影响型需求尽量提供短锚点，格式为 `ClassName.java:123`、`file.ts:45` 或 `ClassName#method:123`；不要写绝对路径，也不要反复写项目相对长路径。只有短名在当前仓库无法唯一定位时，才加最短必要目录前缀。纯文档/配置/新文件没有代码锚点时，写明 `N/A` 理由。
38
38
 
39
39
  ## 链路广度探查
40
40
 
package/templates/workflow/skills/superspec-explore/SKILL.md CHANGED
@@ -34,7 +34,7 @@ metadata:
34
34
  ```text
35
35
  目标：<本次要回答的探查问题，一句话>
36
36
  需求原话：<用户原话或 PRD 关键句，不转述>
37
- 已知锚点：<已确认的 path:line 或文档锚点；没有写“无”>
37
+ 已知锚点：<已确认的短锚点（类名/文件名:行号）或文档锚点；没有写“无”>
38
38
  参考：<PRD/需求文档/artifact 路径；没有写“无”>
39
39
  必查：<正向搜索的具体搜索词（字段名/枚举/路由/文案）> + 反向调用/入口面检查；
40
40
  按链路五要素枚举上游来源、规则变形、持久化语义、下游消费者、视图差异；
@@ -43,7 +43,7 @@ metadata:
43
43
  边界：只读，不写方案；“未发现”只能写按哪些发现方式未发现
44
44
  ```
45
45
 
46
- subagent 结论写入 discovery 前，抽验决定影响范围判断的关键 `path:line` 锚点；核验不了的降级为推断或未知，不写成事实。
46
+ subagent 结论写入 discovery 前，抽验决定影响范围判断的关键短锚点；核验不了的降级为推断或未知，不写成事实。
47
47
 
48
48
  ## discovery.md 契约
49
49
 
@@ -63,7 +63,7 @@ subagent 结论写入 discovery 前，抽验决定影响范围判断的关键 `p
63
63
  ## 链路五要素
64
64
  | ID | 发现方式 | 上游来源 | 规则变形 | 持久化语义 | 下游消费者 | 视图差异 | 未知/排除 | 证据 | 状态 |
65
65
  |---|---|---|---|---|---|---|---|---|---|
66
- | CHAIN-001 | rg 字段名 + 调用方反查 | 配置/输入/历史数据 | 计算/过滤/兜底/无 | 落库含义/不落库 | 详情/APP/报表/导出/定时任务/无 | 计算/展示/统计/回放是否一致 | 未知项或排除理由 | src/path.ts:10 | 已确认 |
66
+ | CHAIN-001 | rg 字段名 + 调用方反查 | 配置/输入/历史数据 | 计算/过滤/兜底/无 | 落库含义/不落库 | 详情/APP/报表/导出/定时任务/无 | 计算/展示/统计/回放是否一致 | 未知项或排除理由 | path.ts:10 | 已确认 |
67
67
 
68
68
  ## 风险和边界
69
69
  - 技术风险、依赖、兼容性，绑定代码或文档锚点
@@ -85,7 +85,8 @@ subagent 结论写入 discovery 前，抽验决定影响范围判断的关键 `p
85
85
 
86
86
  - 事实必须有源码/文档锚点、命令输出或用户确认支撑；推断要写依据；未知要说明是否阻塞。
87
87
  - 不要把自己的理解当成用户需求：用户没有明确说、代码/文档也不能证明的业务语义、验收口径、默认值、边界条件和优先级，只能写为“推断”或“未知”。
88
- - 代码影响型需求尽量提供 `path:line`；纯文档/配置/新文件无代码锚点时写明 `N/A` 理由。
88
+ - Discovery 正文默认使用短锚点，格式为 `ClassName.java:123`、`file.ts:45` 或 `ClassName#method:123`；不要写绝对路径，也不要反复写项目相对长路径。只有短名在当前仓库无法唯一定位时，才加最短必要目录前缀（如 `meta/ShiftBlockMatchStrategyType.java:8`）。该规则只适用于人类可读的 discovery 正文；CLI 参数、job packet、JSON 报告字段（如 `source_refs`）和真实文件参数仍按协议保留原始路径。
89
+ - 代码影响型需求尽量提供短锚点；纯文档/配置/新文件无代码锚点时写明 `N/A` 理由。
89
90
  - `## 链路五要素` 防止只看局部方法：`发现方式` 必须具体；代码影响型需求至少包含一个正向搜索和一个反向/入口面检查；声称“无规则变形 / 不落库 / 单一消费者 / 无视图差异”必须写证据和排除理由。表格单元格内的字面竖线写成 `\|`（如 `rg "a\|b"`）。
90
91
  - 链路五要素 `状态` 列只写枚举值 `已确认` / `未知阻塞` / `未知非阻塞`，不附加说明（引擎按该列判定阻塞）；解决痕迹写在 `未知/排除` 列或对应问题行。
91
92
  - `## 输入数据来源核查` 默认必做。`数据来源` 必须追到 producer 侧目标字段最后一次变形处；`区分依据` 必须可证伪。停在 consumer/validator/DTO，或写“代码审查/见上/对照实现”，不合格。
package/templates/workflow/skills/superspec-propose/SKILL.md CHANGED
@@ -27,6 +27,8 @@ metadata:
27
27
 
28
28
  人类可读正文默认使用简体中文；OpenSpec 结构标题、规范关键字、命令、路径、JSON 字段、代码标识符保留原文。OpenSpec 生成文档语言不符合预期时，先检查 `openspec/config.yaml` 的官方 `context` 设置；不要在变更文档里添加自定义 `language` 字段。
29
29
 
30
+ 路径/锚点写法：proposal/design/tasks/test-contract 正文里的代码区域和源码证据默认使用短写法，例如 `MatchingProcessor`、`AttendanceReportCalculationRuleController#getSelectShiftBlockStrategy`、`ShiftBlockMatchStrategyType.java:8`。不要写绝对路径，也不要反复写项目相对长路径；只有短名在当前仓库无法唯一定位时，才加最短必要目录前缀（如 `meta/ShiftBlockMatchStrategyType.java:8`）。文档引用仍须带文件名前缀，例如 `design.md#实现路线`、`test-contract.md#TEST-001`、`specs/review/spec.md#verifier 绑定`；CLI 参数、job packet、JSON 报告字段和 `.superspec/artifacts/...` 补充材料路径仍按协议保留原始路径。
31
+
30
32
  ## 本阶段做什么
31
33
 
32
34
  ### proposal.md
@@ -35,11 +37,11 @@ metadata:
35
37
  ```markdown
36
38
  | Area | Reason |
37
39
  |---|---|
38
- | src/review.ts | 需要核对 review verifier 如何绑定文档和执行证据 |
40
+ | review.ts | 需要核对 verifier 如何绑定文档和执行证据 |
39
41
  ```
40
42
 
41
43
  规则：
42
- - `Area` 可以写代码区域、API、依赖、系统、配置或文档；不作为路径白名单
44
+ - `Area` 可以写代码区域、API、依赖、系统、配置或文档；优先用模块/类/接口名等短代码区域，不作为路径白名单
43
45
  - `Reason` 只解释为什么该范围受影响，不写详细实现方案
44
46
  - discovery 含 `## 输入数据来源核查` 的 IDC 项时，相关 `Reason` 须引用对应 `IDC-xxx` 状态（`已证明` / `未知阻塞` / `未知非阻塞`）
45
47
  - discovery 含 `## 链路五要素` 时，`## Impact` 须与非 `未知阻塞` 链路行中已确证的下游消费者/视图差异对账：受本次改动影响的写入 Area/Reason 并引用对应 `CHAIN-xxx`；不受影响的在 `## Impact` 中写明排除理由（可按组书写，排除理由不回写 discovery.md）。对账不要求逐行进入 Impact；同一链路已由 `IDC-xxx` 覆盖时，引用其一并注明对应即可
@@ -96,7 +98,7 @@ OpenSpec 能力规范增量（`openspec instructions specs` 格式）。
96
98
  规则：
97
99
  - 每个普通 TDD task（`tdd_required:true`）必须紧跟一个 `执行依据:` 块，包含五个字段：`测试`（该 task 必须兑现的 test-contract 场景，引用 `test-contract.md#TEST-xxx`，多个用逗号合并）、`设计`（执行路线在 `design.md` 的位置或短摘录）、`来源`（task 产生依据，如 `proposal.md#Impact`、spec delta、`discovery.md#CHAIN-xxx,IDC-xxx`，已有明确文件路径的补充材料用 `.superspec/artifacts/...`）、`原因`（为什么单独拆出这个 task）、`边界`（执行时需要保护的边界）
98
100
  - `执行依据:` 必须紧跟所属 task 行（中间最多允许一个空行）；字段不得重复；块内不得出现 checkbox（`- [ ]` / `- [x]`），否则会变成无人执行的暗任务并被引擎拒绝
99
- - 引用使用带文件前缀的可定位格式；`设计`、`来源`、`边界` 的标题或短摘录引用逐项写完整文件前缀，只有 ID 型引用（TEST/CHAIN/IDC）可以逗号合并
101
+ - 引用使用带文件名前缀的可定位格式；`设计`、`来源`、`边界` 的标题或短摘录引用逐项写明 `design.md#...`、`proposal.md#...`、`specs/.../spec.md#...` 等文档前缀，只有 ID 型引用（TEST/CHAIN/IDC）可以逗号合并
100
102
  - 声明的每个 `TEST-xxx` 必须存在于 `test-contract.md`，否则 `propose-ready` 和 `start-apply` 会被阻断
101
103
  - 五个字段的内容必须针对该 task 具体可核验，执行者和审查者要拿它们对照实现：`边界` 写出改动不应触碰的具体行为、模块或语义（能对着 diff 判断有没有越界），不写"不破坏现有功能"这类放在任何 task 上都成立的套话；`原因` 说明这个 task 独立存在的理由，不写"需要单独实现"；不同 task 的执行依据不应互相复制
102
104
  - 写不出可定位的 `设计` 引用时，说明 `design.md` 缺少该 task 的实现方向——先补设计，不编造引用
@@ -144,7 +146,7 @@ scenario 写到能推导断言的程度：给定什么条件、发生什么动
144
146
 
145
147
  | 核查ID | 验证方式 | 输入链路声明 | 证据或计划 |
146
148
  |---|---|---|---|
147
- | IDC-001 | 源码锚点 + 聚焦测试 | producer 产生的目标输入会进入 consumer | src/path.ts:10 + TEST-001 |
149
+ | IDC-001 | 源码锚点 + 聚焦测试 | producer 产生的目标输入会进入 consumer | path.ts:10 + TEST-001 |
148
150
 
149
151
  证明方式可用源码锚点、fixture、targeted test、日志或 trace，须说明证明力；不强制集成测试。只证 consumer 算法、没证 producer→consumer 输入完整性，测试契约不足。
150
152