@peterxiaoyang/superspec 0.1.57 → 0.1.58

package/dist/cli.js

@@ -591,10 +591,12 @@ function commandHelp(command, subcommand) {
         return `用法：superspec record job-submit --change <C> --job <J> --report <F|->
 
 提交 reviewer JSON 报告；--report - 表示从 stdin 读取。报告契约以 jobs packet 返回的 report_schema 为准。
+需要落盘时写到 packet 的 report_file_path（.superspec/changes/<C>/jobs/<J>.report.json），不要放进 openspec/changes 计划材料目录。
 
 示例：
   superspec jobs packet --change <C> --job <J>
-  superspec record job-submit --change <C> --job <J> --report report.json
+  superspec record job-submit --change <C> --job <J> --report -
+  superspec record job-submit --change <C> --job <J> --report .superspec/changes/<C>/jobs/<J>.report.json
 `;
     }
     if (command === "record" && subcommand === "test-run") {

package/dist/record.d.ts

@@ -1,4 +1,6 @@
 import type { RecordResult, Job, JobPacket } from "./types.ts";
+/** 报告文件的推荐落盘位置：工作流记录目录，不进入计划材料。 */
+export declare function jobReportFilePath(change: string, jobId: string): string;
 /** record job-submit：登记工作项结果 */
 export declare function recordJobSubmit(projectRoot: string, change: string, changeRoot: string, jobId: string, reportFile: string): RecordResult;
 /** record job-submit：从 JSON 内容登记工作项结果 */

package/dist/record.js

@@ -679,10 +679,23 @@ function recordJobSubmitLoaded(projectRoot, change, changeRoot, jobId, job, even
     return {
         event_type: "job_accepted",
         accepted: true,
-        message: `工作项 ${jobId}（${job.role}）已接受`,
+        message: `工作项 ${jobId}（${job.role}）已接受${misplacedReportFileNote(change, reportPath)}`,
         job_state: "accepted",
     };
 }
+/** 报告文件的推荐落盘位置：工作流记录目录，不进入计划材料。 */
+export function jobReportFilePath(change, jobId) {
+    return `.superspec/changes/${change}/jobs/${jobId}.report.json`;
+}
+/** 报告内容已存入 raw 记录；文件若写在 openspec change 目录里会跟计划材料一起进版本库，提示清理。 */
+function misplacedReportFileNote(change, reportPath) {
+    if (!reportPath)
+        return "";
+    const normalized = reportPath.replace(/\\/g, "/");
+    if (!normalized.startsWith(`openspec/changes/${change}/`))
+        return "";
+    return `；报告内容已存入工作流记录，${normalized} 位于计划材料目录，请删除该文件（落盘位置见 packet 的 report_file_path）`;
+}
 /** record job-submit：登记工作项结果 */
 export function recordJobSubmit(projectRoot, change, changeRoot, jobId, reportFile) {
     return withLock(projectRoot, change, () => {
@@ -1185,6 +1198,7 @@ function packetFieldDescriptions() {
         approved_refs: "指向当前 change 已批准材料的引用；引擎只检查能否解析，apply 漏做还需要 TEST 或 spec Requirement。",
         unknown_attribution_tasks: "因为缺少边界快照或提交段 diff 失败而无法完整计算改动归属的任务（task）。",
         coverage_exemption_refs: "测试覆盖豁免引用：说明某个 TEST 为什么没有绑定到任务（task）。",
+        report_file_path: "报告需要落盘时的文件位置（项目相对路径），位于工作流记录目录；报告内容登记后由引擎存入 raw 记录，不属于计划材料。",
         code_review_gate: "最终验证读取的代码审查门禁事实：passed 指向已接受的代码审查工作项，skipped 表示本轮没有代码类改动。",
         code_state_check: "代码状态检查：最终验证时用于判断代码审查后代码是否又发生变化。",
         event_id: "事件 ID，用于追溯证据来源。",
@@ -1237,6 +1251,7 @@ export function jobsPacket(projectRoot, change, jobId) {
             submission_command: `superspec record job-submit --change "${change}" --job "${job.job_id}" --report -`,
             submission_argv: jobSubmitArgv(change, job.job_id),
             file_fallback: true,
+            report_file_path: jobReportFilePath(change, job.job_id),
             output_contract_fields: isCodeReviewer
                 ? [...REVIEW_REPORT_REQUIRED_FIELDS, "reviewer", "review_scope"]
                 : [
@@ -1252,7 +1267,7 @@ export function jobsPacket(projectRoot, change, jobId) {
                 (job.review_evidence_digest ? `本工作项对应的执行证据版本为 ${job.review_evidence_digest}，` : "") +
                 (isReviewer ? genericReviewCoverageInstruction(job) + proposalIncrementalReviewInstruction(job) + previousRejectionInstruction(job) : "") +
                 (requiresReviewer(job.role) ? `必须由独立 ${recommendedAgentForRole(job.role)} 审查角色执行，并在审查者来源字段（reviewer.kind/id）中记录来源，` : "") +
-                `产出 JSON 报告内容并优先通过 --report - 从 stdin 登记；文件路径模式仅作备用。${recordInputInstruction(job)}协议字段含义见 packet 顶层“字段说明”，普通对话不要原样复述 JSON。` +
+                `产出 JSON 报告内容并优先通过 --report - 从 stdin 登记；需要落盘时写到 report_file_path，不要写进 openspec/changes 或 .superspec/artifacts 等计划材料目录。${recordInputInstruction(job)}协议字段含义见 packet 顶层“字段说明”，普通对话不要原样复述 JSON。` +
                 (isCodeReviewer
                     ? `格式骨架：{"role":"code-reviewer","verdict":"pass","review_scope":{"job_id":"${job.job_id}","packet_digest":"${job.packet_digest}","checked_paths":[],"checked_docs":[],"unchecked":[]},"findings":[],"reviewer":{"kind":"subagent","id":"<thread-or-agent-id>"}}。提交前按真实审查结果填写数组；不得从 boundFiles 自动复制 checked_paths。verdict 只能为 pass 或 fail；审查覆盖范围（review_scope）用来说明本次审查覆盖了哪些文件和文档，已检查路径（checked_paths）与未检查项（unchecked）必须合起来覆盖全部绑定文件（boundFiles），unchecked 条目格式为 {"path":"<path>","reason":"<reason>"}；pass 不允许仍有未检查的绑定文件。`
                         + `报告结论为 fail 时，问题列表（findings）至少包含一个可处理、可追溯的阻塞问题，字段为 {"id":"<stable-id>","blocking":true,"type":"implementation|spec|mixed","claim_kind":"missing_approved|breaks_existing|unjustified_addition","approved_refs":["TEST-001"],"description":"<what>","evidence":"<why>","source_refs":["<path:line>"],"impact":"<impact>","suggested_action":"apply|propose"}。问题类型（type）中 implementation 表示纯代码实现问题，spec 表示方案/需求文档问题，mixed 表示需要使用者判断的混合问题；claim_kind 与 approved_refs 见字段说明。`

package/dist/types.d.ts

@@ -162,6 +162,8 @@ export interface JobPacket {
     submission_command?: string;
     submission_argv?: string[];
     file_fallback?: boolean;
+    /** 需要落盘时的报告文件位置（项目相对路径），位于工作流记录目录而非计划材料目录。 */
+    report_file_path?: string;
     output_contract_fields?: string[];
     output_contract_optional_fields?: string[];
     字段说明?: Record<string, string>;

package/package.json

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

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

@@ -172,7 +172,7 @@ metadata:
 
 - [ ] 1.1 <可独立验证的行为或明确的非行为改动>
   执行依据:
-  - 测试: test-contract.md#TEST-001
+  - 测试: test-contract.md#TEST-001, TEST-002
   - 设计: design.md#<对应实现方案>
   - 来源: proposal.md#Impact；specs/<capability>/spec.md#<对应规则>
   - 验收: <完成后可检查的结果>
@@ -189,7 +189,7 @@ metadata:
   - 边界: <不改业务行为>
 ```
 
-`验收` 与 `边界` 必须能针对该 task 对照实现，不写可套用到任何 task 的空话；引用必须能定位到真正支持该 task 的材料。行为 task 的测试引用相应场景；纯非行为 task 才可留空并在验收/边界说明原因。`交付` 和 `依赖` 用于开始实现前的阅读摘要：只写真实前置交付，不能把纯排列顺序写成依赖。验证要求由工作流决定，计划不预设执行步骤。
+`验收` 与 `边界` 必须能针对该 task 对照实现，不写可套用到任何 task 的空话；引用必须能定位到真正支持该 task 的材料。行为 task 的测试引用相应场景，一个 task 覆盖多个场景时把它们都列在同一 `测试` 字段里；纯非行为 task 才可留空并在验收/边界说明原因。`交付` 和 `依赖` 用于开始实现前的阅读摘要：只写真实前置交付，不能把纯排列顺序写成依赖。验证要求由工作流决定，计划不预设执行步骤。
 
 ### test-contract.md