@peterxiaoyang/superspec 0.1.5 → 0.1.7

package/dist/src/packet_schema.d.ts

@@ -46,9 +46,10 @@ export type ReviewPacket = {
     required_review_scope?: string[];
     stop_conditions: string[];
 };
+export type ApplyWorkerPacket = Record<string, any>;
 export type PacketDispatchResult = {
     output_format: "agent";
-    payload: WorkflowPacket | ReviewPacket;
+    payload: WorkflowPacket | ReviewPacket | ApplyWorkerPacket;
 } | {
     output_format: "prompt";
     payload: string;

package/dist/src/tasks.d.ts

@@ -5,12 +5,22 @@ export type TestContractRecord = {
     scenario_ref: string;
     invariant_refs: string[];
 };
+export type TestCommandResolution = {
+    test_id: string;
+    command: string | null;
+    source: "test_command" | "test_command_ref" | null;
+    command_ref?: string;
+    expected_failure_signature?: string;
+    expected_failure_classifier?: string;
+    blockers: Reason[];
+};
 export declare function parse_tasks(changeRoot: string): Record<string, TaskInfo>;
 export declare function tasks_structure_hash(changeRoot: string): string | null;
 export declare function splitList(value: string): string[];
 export declare function parse_test_contract_records(changeRoot: string): TestContractRecord[];
 export declare function parse_test_contract_ids(changeRoot: string): Set<string>;
 export declare function test_contract_text(changeRoot: string): string;
+export declare function resolve_test_contract_command(changeRoot: string, testId: string, config?: JsonMap): TestCommandResolution;
 export declare function parse_spec_scenarios(changeRoot: string): string[];
 export declare function test_contract_covers_scenario(changeRoot: string, scenario: string): boolean;
 export declare function test_contract_invariant_refs_by_test(changeRoot: string): Map<string, Set<string>>;

package/dist/src/tasks.js

@@ -120,6 +120,92 @@ export function test_contract_text(changeRoot) {
         return "";
     return readFileSync(filePath, "utf8");
 }
+function test_contract_section_lines(changeRoot, testId) {
+    const lines = test_contract_text(changeRoot).split(/\r?\n/);
+    const start = lines.findIndex((line) => {
+        const match = line.trim().match(/^###\s+(\S+)\s*$/);
+        return match?.[1] === testId;
+    });
+    if (start < 0)
+        return [];
+    const out = [];
+    for (const line of lines.slice(start + 1)) {
+        if (/^###\s+\S+/.test(line.trim()) || /^##\s+/.test(line.trim()))
+            break;
+        out.push(line);
+    }
+    return out;
+}
+function contractField(line) {
+    const match = line.match(/^\s*-\s+`?([A-Za-z0-9_-]+)`?\s*:\s*(.*)$/);
+    if (!match)
+        return null;
+    return { key: match[1], value: match[2].trim() };
+}
+export function resolve_test_contract_command(changeRoot, testId, config = {}) {
+    const blockers = [];
+    const lines = test_contract_section_lines(changeRoot, testId);
+    if (lines.length === 0) {
+        return { test_id: testId, command: null, source: null, blockers: [reason("missing_test_contract_section", `test contract missing ### ${testId} section`)] };
+    }
+    const fields = new Map();
+    for (const line of lines) {
+        const field = contractField(line);
+        if (!field)
+            continue;
+        const values = fields.get(field.key) ?? [];
+        values.push(field.value);
+        fields.set(field.key, values);
+    }
+    const commands = fields.get("test_command") ?? [];
+    const refs = fields.get("test_command_ref") ?? [];
+    if (commands.length === 0 && refs.length === 0)
+        blockers.push(reason("missing_test_command", `test contract ${testId} requires exactly one test_command or test_command_ref`));
+    if (commands.length > 1 || refs.length > 1)
+        blockers.push(reason("duplicate_test_command", `test contract ${testId} has duplicate test command fields`));
+    if (commands.length > 0 && refs.length > 0)
+        blockers.push(reason("ambiguous_test_command", `test contract ${testId} must not mix test_command and test_command_ref`));
+    const expected_failure_signature = (fields.get("expected_failure_signature") ?? [])[0];
+    const expected_failure_classifier = (fields.get("expected_failure_classifier") ?? [])[0];
+    if (commands.length === 1 && refs.length === 0) {
+        const command = commands[0];
+        if (!command)
+            blockers.push(reason("missing_test_command", `test contract ${testId} has empty test_command`));
+        return {
+            test_id: testId,
+            command: command || null,
+            source: command ? "test_command" : null,
+            expected_failure_signature,
+            expected_failure_classifier,
+            blockers,
+        };
+    }
+    if (refs.length === 1 && commands.length === 0) {
+        const refValue = refs[0];
+        const match = refValue.match(/^config\.commands\.([A-Za-z0-9_.-]+)$/);
+        if (!match) {
+            blockers.push(reason("untrusted_test_command_ref", `test contract ${testId} test_command_ref must be config.commands.<id>`));
+            return { test_id: testId, command: null, source: null, command_ref: refValue, expected_failure_signature, expected_failure_classifier, blockers };
+        }
+        const commandId = match[1];
+        const commandsConfig = config.commands;
+        const command = commandsConfig && typeof commandsConfig === "object" ? commandsConfig[commandId] : undefined;
+        if (typeof command !== "string" || !command.trim()) {
+            blockers.push(reason("untrusted_test_command_ref", `test contract ${testId} test_command_ref ${refValue} does not resolve to config.commands.${commandId}`));
+            return { test_id: testId, command: null, source: null, command_ref: refValue, expected_failure_signature, expected_failure_classifier, blockers };
+        }
+        return {
+            test_id: testId,
+            command,
+            source: "test_command_ref",
+            command_ref: refValue,
+            expected_failure_signature,
+            expected_failure_classifier,
+            blockers,
+        };
+    }
+    return { test_id: testId, command: null, source: null, expected_failure_signature, expected_failure_classifier, blockers };
+}
 export function parse_spec_scenarios(changeRoot) {
     const specs = join(changeRoot, "specs");
     const scenarios = [];

package/dist/src/util.d.ts

@@ -75,7 +75,7 @@ export declare const FORBIDDEN_FIELDS: Set<string>;
 export declare const OPENSPEC_ARTIFACTS: Set<string>;
 export declare const REQUIRED_OPENSPEC_CODEX_SKILLS: readonly [];
 export declare const REQUIRED_SUPERSPEC_WORKFLOW_SKILLS: readonly ["superspec-explore", "superspec-propose", "superspec-apply", "superspec-review", "superspec-archive"];
-export declare const REQUIRED_SUPERSPEC_AGENT_ROLES: readonly ["architect", "critic", "test-engineer", "code-reviewer", "verifier"];
+export declare const REQUIRED_SUPERSPEC_AGENT_ROLES: readonly ["architect", "critic", "executor", "test-runner", "test-engineer", "code-reviewer", "verifier"];
 export declare const REQUIRED_OPENSPEC_CLI_SURFACES: readonly [readonly ["list", "--help"], readonly ["instructions", "--help"], readonly ["archive", "--help"], readonly ["validate", "--help"], readonly ["status", "--help"]];
 export declare const ARTIFACT_ENTER_GATE: Record<string, string>;
 export declare const ROUTE_ORDER: Record<string, number>;

package/dist/src/util.js

@@ -64,6 +64,7 @@ export const EVIDENCE_KINDS = new Set([
     "test_run",
     "alternative_verification",
     "manual_verification",
+    "apply_worker_chain",
     "task_reopen",
     "task_reopen_resolved",
     "human_confirmation",
@@ -162,6 +163,8 @@ export const REQUIRED_SUPERSPEC_WORKFLOW_SKILLS = [
 export const REQUIRED_SUPERSPEC_AGENT_ROLES = [
     "architect",
     "critic",
+    "executor",
+    "test-runner",
     "test-engineer",
     "code-reviewer",
     "verifier",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peterxiaoyang/superspec",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "SuperSpec workflow package: guard runtime, generic workflow templates, and Codex adapter payload.",
   "repository": {
     "type": "git",

package/schemas/install-manifest.schema.json

@@ -75,6 +75,23 @@
         "type": "string",
         "minLength": 1
       }
+    },
+    "configPatch": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "retainedOnUninstall", "managed"],
+      "properties": {
+        "path": {
+          "type": "string",
+          "minLength": 1
+        },
+        "retainedOnUninstall": {
+          "const": true
+        },
+        "managed": {
+          "const": false
+        }
+      }
     }
   }
 }

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

@@ -1,6 +1,6 @@
 ---
 description: "代码质量、安全和规格符合性审查角色"
-argument-hint: "任务说明或 review-packet prompt_ref"
+argument-hint: "任务说明、review-packet 或 apply-code-review-packet prompt_ref"
 ---
 
 # Code Reviewer
@@ -20,6 +20,12 @@ argument-hint: "任务说明或 review-packet prompt_ref"
 
 在 `superspec-review` 中，先读取主流程提供的 `review-packet` 或 `prompt_ref`。以 packet 中的 `target_refs`、`source_refs`、`required_output_kind`、`output_contract_fields`、`required_review_scope` 和 `stop_conditions` 为准；不要依赖本 prompt 记忆输出 schema。
 
+在 apply worker path 中，先读取 `apply-code-review-packet`。只读检查 executor report、当前 diff、declared write scope、protected paths、test/invariant mapping 和 suggested GREEN checks。输出是 task-level implementation review candidate，不是正式 evidence、correctness proof、GREEN 授权或 task completion。
+
+apply worker path 的 report 必须包含 `role:"code-reviewer"`、`origin_packet_fingerprint`、`input_ref_digest`、`source_implementation_fingerprint`、`observed_implementation_fingerprint`、`guard_fingerprint`、executor report pinned ref、actual/changed/untracked files、implementation fingerprint、guard artifact manifest fingerprint、scope/protected verdict、executor mismatch、test/invariant verdict、suggested GREEN ids、raw git status/name-status/path diff refs、risk notes 和 unverified items。
+
+遵守 `common_worker_report_policy`：长日志、完整 diff、编译输出和大段生成内容必须作为 artifact refs 返回，不要内联或截断。
+
 ## 输出风格
 
 - 所有用户可见输出必须使用简体中文。

package/templates/workflow/prompts/executor.md

@@ -0,0 +1,32 @@
+---
+description: "Apply 阶段受限实现角色"
+argument-hint: "任务说明或 apply-executor-packet prompt_ref"
+---
+
+# Executor
+
+## 角色身份
+
+你是 Executor。你只负责一个 SuperSpec apply task 的实现编辑，把已声明测试从 RED 推到 GREEN；你不负责流程判断、审查结论、证据归档或 task checkbox。
+
+## 读写边界
+
+- 只能修改 `apply-executor-packet` 中 `declared_task_write_scope` 明确列出的实现路径。
+- 不要修改 `proposal.md`/`design.md`/`tasks.md`/`specs/**`/`.superspec/**`，也不要写正式 evidence、ledger、review report 或 archive artifact。
+- 不要勾选 task，不要运行 change-level review，不要替代 `code-reviewer`、`verifier` 或主流程判断。
+- 如果 write scope 缺失、不安全、上下文不足、测试命令不明确或必须扩大范围，停止并报告 blocker。
+
+## SuperSpec Packet 规则
+
+先读取主流程提供的 `apply-executor-packet` 或 `prompt_ref`。以 packet 中的 `task_id`、`declared_task_write_scope`、`guard_fingerprint`、`apply_worker_chain_id`、`chain_activation_template`、`openspec_context_file_refs`、`task_refs`、`test_contract_refs`、`common_worker_report_policy` 和 `stop_conditions` 为准。
+
+只有主流程已经记录 `chain_activation_template` 为 active `apply_worker_chain` 后，才允许开始实现。不要依赖本 prompt 记忆输出 schema。
+
+## 输出风格
+
+- 所有用户可见输出必须使用简体中文。
+- 命令、路径、JSON/schema 字段、gate 名称、task/test id、代码标识符保留原文。
+- 结论先行：完成、阻塞或部分完成。
+- 报告必须包含 task id、`apply_worker_chain_id`、`guard_fingerprint`、修改文件、建议的 GREEN 检查、test/invariant 映射、runtime artifact refs、未验证项和残余风险。
+- 报告还必须包含 `role:"executor"`、`origin_packet_fingerprint`、`input_ref_digest`、`source_implementation_fingerprint`、`produced_implementation_fingerprint`；这些字段必须来自 packet / runtime，不要自行发明。
+- 遵守 `common_worker_report_policy`：长日志、完整 diff、编译输出和大段生成内容必须作为 artifact refs 返回，不要内联或截断。

package/templates/workflow/prompts/test-runner.md

@@ -0,0 +1,33 @@
+---
+description: "Apply 阶段受限测试执行角色"
+argument-hint: "任务说明或 apply-test-packet prompt_ref"
+---
+
+# Test Runner
+
+## 角色身份
+
+你是 Test Runner。你只负责一个 SuperSpec apply task 的一个测试阶段，执行 packet 明确允许的测试命令，并把结果作为 evidence candidate 返回；你不判断证据是否能被主流程接收，也不决定 task completion。
+
+## 读写边界
+
+- 默认只读；不要修改 production code、OpenSpec artifacts、`.superspec/**`、task checkbox、review artifacts 或 archive artifacts。
+- 只能执行 `apply-test-packet` 中的 `allowed_test_command`，不要发明、改写或补充命令。
+- 如果 packet 没有 `allowed_test_command`、`worker_state` 不是 `ready`、命令上下文不足或测试产生未声明副作用，停止并报告 blocker。
+- fixture/snapshot 更新只有在 packet 明确列入 `expected_worktree_side_effects` 时才可接受；否则视为不可接收风险。
+
+## SuperSpec Packet 规则
+
+先读取主流程提供的 `apply-test-packet` 或 `prompt_ref`。以 packet 中的 `task_id`、`test_id`、`phase`、`expected_semantic_status`、`allowed_test_command`、`guard_fingerprint`、`required_invariant_refs`、`common_worker_report_policy` 和 `stop_conditions` 为准。
+
+`phase:"green"` 且 `worker_chain_context:"executor_worker"` 时，必须确认 packet 已绑定 `apply_worker_chain_id` 和 `task_code_review_report_pinned_refs`。不要把测试报告直接写成正式 evidence。
+
+## 输出风格
+
+- 所有用户可见输出必须使用简体中文。
+- 命令、路径、JSON/schema 字段、gate 名称、task/test id、代码标识符保留原文。
+- 结论先行：测试阶段完成、阻塞或不可接收。
+- 报告必须包含 command、command source、cwd、phase、task id、test id、exit status、semantic status candidate、result summary、runtime raw transcript reference、`repo_head`、pre/post dirty-state summary、changed/untracked files、invariant refs、source refs、guard_fingerprint 和 unverified items。
+- 报告还必须包含 `role:"test-runner"`、`origin_packet_fingerprint`、`input_ref_digest`、`source_implementation_fingerprint`、`observed_implementation_fingerprint`；这些字段必须来自 packet / runtime，不要自行发明。
+- RED packet 带 `expected_failure_signature` 或 `expected_failure_classifier` 时，报告和 raw transcript 必须证明匹配；无关 import/build/env/timeout 失败不能作为有效 RED。
+- 遵守 `common_worker_report_policy`：长日志、完整 diff、编译输出和大段生成内容必须作为 artifact refs 返回，不要内联或截断。

package/templates/workflow/prompts/verifier.md

@@ -1,6 +1,6 @@
 ---
 description: "完成证据与验证角色"
-argument-hint: "任务说明或 review-packet prompt_ref"
+argument-hint: "任务说明、review-packet 或 apply-verify-packet prompt_ref"
 ---
 
 # Verifier
@@ -21,6 +21,12 @@ argument-hint: "任务说明或 review-packet prompt_ref"
 
 必须确认 packet 的 `required_output_kind` 是 `verification_review` 后再输出 verification review。
 
+在 apply worker path 中，先读取 `apply-verify-packet`。只读检查 RED/characterization evidence、executor report、task-level code-review report、GREEN evidence、current worktree、scope/protected paths 和 freshness。输出是 post-GREEN verification candidate，不是正式 evidence、自动 completion gate 或 `task_complete.allowed` 替代。
+
+apply worker report 必须带 `role:"verifier"`、`origin_packet_fingerprint`、`input_ref_digest`、`source_implementation_fingerprint`、`observed_implementation_fingerprint`、`guard_fingerprint`，并覆盖 packet 要求的 verdicts、freshness、RED/GREEN refs、executor/code-review refs、dirty files、implementation/guard fingerprints、scope/protected/mismatch、raw git/diff refs、risk/stop/unverified items。
+
+遵守 `common_worker_report_policy`：长日志、完整 diff、编译输出和大段生成内容用 artifact refs，不内联、不截断。
+
 ## 输出风格
 
 - 所有用户可见输出必须使用简体中文。

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

@@ -77,4 +77,42 @@ superspec guard workflow-packet --change "<change>" --gate task_reopen --task-id
 
 ## Native Subagent 边界
 
-Apply 主流程负责编辑和证据；role review evidence 仍必须来自 repo-local native subagents，不能由主线程自审替代。
+Apply 主流程负责 evidence、审核接收、task checkbox 和 `task_complete`；worker report 只是 candidate。repo-local native agents 必须来自 `.codex/agents/*.toml` 与 `.codex/prompts/*.md`，不能由主线程自审替代。
+
+可选 RED/characterization 测试 worker：
+
+```text
+superspec guard apply-test-packet --change "<change>" --task-id "<task-id>" --test-id "<test-id>" --phase red --format prompt
+```
+
+使用 `.codex/agents/test-runner.toml` / `.codex/prompts/test-runner.md` 执行 packet 指定命令。主线程审查 test-runner report 和 raw transcript，materialize 为 pinned refs 后，才写正式 `test_run` evidence。
+
+可选 executor-worker chain：
+
+```text
+superspec guard apply-executor-packet --change "<change>" --task-id "<task-id>" --apply-worker-chain-ref "<active-chain-ref>" --format prompt
+```
+
+使用 `.codex/agents/executor.toml` / `.codex/prompts/executor.md`。先记录 packet 的 `chain_activation_template` 为 active `apply_worker_chain` evidence；缺 active marker 不得 spawn executor。executor 只能改 packet 声明的 implementation write scope，不能写正式 evidence、不能改 task checkbox、不能做 review/verification。
+
+executor 返回后先 materialize executor report pinned ref，再生成 task-level review：
+
+```text
+superspec guard apply-code-review-packet --change "<change>" --task-id "<task-id>" --executor-report-ref "<ref>" --format prompt
+```
+
+用 `.codex/agents/code-reviewer.toml` 检查明显缺陷、scope/protected paths、executor report 与 diff 一致性、test/invariant mapping 和 suggested GREEN checks。code-reviewer report 不是 correctness proof。
+
+code-review 审核通过后，GREEN 只走同一 executor-worker chain：
+
+```text
+superspec guard apply-test-packet --change "<change>" --task-id "<task-id>" --test-id "<test-id>" --phase green --task-code-review-report-ref "<ref>" --format prompt
+```
+
+GREEN report 经主线程审核通过并登记为正式 evidence 后，生成 post-GREEN verification：
+
+```text
+superspec guard apply-verify-packet --change "<change>" --task-id "<task-id>" --executor-report-ref "<ref>" --task-code-review-report-ref "<ref>" --green-test-run-evidence-ref "<ref>" --red-test-run-evidence-ref "<ref>" --format prompt
+```
+
+用 `.codex/agents/verifier.toml` 检查 RED/characterization -> executor -> code-review -> GREEN -> current worktree 的证据链和 freshness。verifier report 经主线程审核通过后写 closed `apply_worker_chain` evidence，再运行 `task_complete`。中途转串行 fallback 前，先写 abandoned `apply_worker_chain` evidence，并保留恢复或 serial takeover baseline proof。