@peterxiaoyang/superspec 0.1.12 → 0.1.14

package/adapters/codex/agents/explore.toml

@@ -0,0 +1,13 @@
+# oh-my-codex agent: explore
+name = "explore"
+description = "Repo-local read-only factual scan for SuperSpec discovery"
+model_reasoning_effort = "xhigh"
+developer_instructions = """
+Role: Explore. Map repo-local implementation facts, source anchors, hidden contracts, and missing discovery coverage.
+
+Prompt binding: load `.codex/prompts/explore.md` first, then read the task prompt, `workflow-packet`, or `prompt_ref`. Packet refs and stop conditions override static prompt memory.
+
+Boundary: read-only. Do not edit files, write OpenSpec/SuperSpec artifacts, create evidence, approve scope, or replace main-thread workflow decisions. Report findings upward with concrete anchors.
+
+Output: concise Simplified Chinese. Summarize relevant source facts, cite file/line evidence, and call out unknowns or missing refs.
+"""

package/adapters/codex/install-map.json

@@ -52,6 +52,11 @@
       "source": "templates/workflow/prompts/executor.md",
       "target": ".codex/prompts/executor.md"
     },
+    {
+      "kind": "prompt",
+      "source": "templates/workflow/prompts/explore.md",
+      "target": ".codex/prompts/explore.md"
+    },
     {
       "kind": "prompt",
       "source": "templates/workflow/prompts/test-runner.md",
@@ -82,6 +87,11 @@
       "source": "adapters/codex/agents/critic.toml",
       "target": ".codex/agents/critic.toml"
     },
+    {
+      "kind": "agent",
+      "source": "adapters/codex/agents/explore.toml",
+      "target": ".codex/agents/explore.toml"
+    },
     {
       "kind": "agent",
       "source": "adapters/codex/agents/executor.toml",

package/dist/src/init_cli.js

@@ -1,5 +1,5 @@
 import { block, commandExists, GuardError, printDecision, reason, runCommand, openspec_cli_probe, parseDecisionOutputFormat, REQUIRED_OPENSPEC_MIN_VERSION, } from "./core.js";
-import { forced_openspec_install_plan, project_init, recommended_openspec_install_plan } from "./project_init.js";
+import { ensure_openspec_chinese_context, forced_openspec_install_plan, project_init, recommended_openspec_install_plan } from "./project_init.js";
 import { install_workflow, uninstall_workflow, update_workflow } from "./install_engine.js";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
@@ -320,6 +320,11 @@ function run_init(args, scope) {
         summary = engineDecision(`${gatePrefix}_update`, targetRoot, update_workflow(targetRoot, { scope }), [
             scope === "project" ? "review *.new files for user-modified surfaces, then rerun superspec check check-init" : "review *.new files for user-modified user-level surfaces",
         ]);
+        if (scope === "project" && summary.allowed) {
+            const act = ensure_openspec_chinese_context(targetRoot);
+            if (Array.isArray(summary.actions))
+                summary.actions.push(act);
+        }
     }
     else if (scope === "user") {
         summary = engineDecision("user_install", targetRoot, install_workflow(targetRoot, { force: args.force, scope: "user" }), [

package/dist/src/packet_render.js

@@ -10,7 +10,7 @@ import { final_verification_evidences, index_evidence, live_pass, live_user_conf
 import { file_blob_sha, dirty_worktree_paths } from "./git.js";
 import { preset_upgrade_reasons, preset_upgrade_required_from_context } from "./archive.js";
 import { state_corrupt_reasons, state_stale_reasons } from "./state.js";
-import { parse_tasks, resolve_test_contract_command, splitList, task_apply_execution_surface, task_apply_execution_surface_reasons, test_contract_invariant_refs_by_test, } from "./tasks.js";
+import { parse_tasks, resolve_test_contract_command, splitList, task_apply_execution_surface, task_apply_execution_surface_reasons, tasks_structure_hash, test_contract_invariant_refs_by_test, } from "./tasks.js";
 import { APPLY_CODE_REVIEW_REPORT_REQUIRED_FIELDS, APPLY_EXECUTOR_REPORT_REQUIRED_FIELDS, APPLY_TEST_RUNNER_REPORT_REQUIRED_FIELDS, APPLY_VERIFIER_REPORT_REQUIRED_FIELDS, apply_worker_implementation_fingerprint, apply_worker_executor_input_ref_digest, apply_worker_protected_path_refs, compute_apply_worker_freshness, fingerprint_digest, fingerprint_matches, pinned_artifact_ref_reasons as shared_pinned_artifact_ref_reasons, pre_edit_evidence_ref_reasons, pre_edit_worker_test_run_reasons, read_pinned_artifact_json, worker_input_ref_digest, worker_test_run_reasons, } from "./apply_worker_chain.js";
 import { apply_worker_chain_lifecycle_state } from "./apply_worker_chain_lifecycle.js";
 import { PACKAGE_ROOT } from "./install_engine.js";
@@ -400,6 +400,14 @@ function workflow_packet(ctx, gateRaw, taskId) {
         diagnostic_command: gate_recheck_command(ctx.change, gate, taskId, true),
         must_read_refs: workflow_gate_refs(ctx, gate),
     };
+    // Surface tasks_structure_hash directly in the agent-facing packet so apply_isolation and
+    // scope_expansion human confirmations can be constructed without a second status/json detour
+    // or source-code inspection to find the current tasks.md structural fingerprint.
+    if (gate === "apply_ready" || gate === "task_edit" || gate === "task_complete" || gate === "task_reopen") {
+        const currentTasksStructureHash = tasks_structure_hash(ctx.changeRoot);
+        if (currentTasksStructureHash)
+            packet.tasks_structure_hash = currentTasksStructureHash;
+    }
     const cliSurfaces = openspec_cli_surfaces_for_gate(ctx.change, gate);
     if (cliSurfaces.length > 0)
         packet.openspec_cli_surfaces = cliSurfaces;

package/dist/src/packet_schema.d.ts

@@ -1,6 +1,6 @@
 export type PacketOutputFormat = "agent" | "prompt";
 export type PinnedRef = {
-    root: "repo" | "change";
+    root: "repo" | "change" | "superspec";
     path: string;
     blob_sha: string;
 };
@@ -19,6 +19,7 @@ export type WorkflowPacket = {
     current_gate: string;
     task_id?: string;
     status: "allowed" | "blocked";
+    tasks_structure_hash?: string;
     top_blockers?: string[];
     blocker_count?: number;
     has_more_blockers?: boolean;

package/dist/src/project_init.d.ts

@@ -1,4 +1,5 @@
 import { type JsonMap, type OpenspecCliProbe } from "./core.ts";
+import { type EngineAction } from "./install_engine.ts";
 export declare const OPENSPEC_NPM_PACKAGE = "@fission-ai/openspec";
 export declare const OPENSPEC_INSTALL_DOC_URL = "https://github.com/Fission-AI/OpenSpec#readme";
 export type OpenspecInstallPlan = {
@@ -26,6 +27,7 @@ export declare function openspec_cli_requirement_message(probe: OpenspecCliProbe
         cwd?: string;
     }) => boolean;
 }): string;
+export declare function ensure_openspec_chinese_context(repoRoot: string): EngineAction;
 export declare function project_init(repoRootRaw?: string, opts?: {
     force?: boolean;
 }): JsonMap;

package/dist/src/project_init.js

@@ -1,5 +1,5 @@
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { REQUIRED_SUPERSPEC_AGENT_ROLES, REQUIRED_OPENSPEC_MIN_VERSION, block, commandExists, openspec_cli_probe, reason, read_agent_toml_name, } from "./core.js";
 import { install_workflow } from "./install_engine.js";
 export const OPENSPEC_NPM_PACKAGE = "@fission-ai/openspec";
@@ -136,9 +136,33 @@ function ensureSuperSpecWorkflow(repoRoot, actions, force) {
     }
     return result.problems;
 }
+const OPENSPEC_CONFIG_REL = "openspec/config.yaml";
+const ZH_CTX = '所有文档必须使用中文编写。需求描述应使用"应当"或"必须"等词汇。';
+export function ensure_openspec_chinese_context(repoRoot) {
+    const p = join(repoRoot, OPENSPEC_CONFIG_REL);
+    if (existsSync(p) && statSync(p).isFile()) {
+        const t = readFileSync(p, "utf8");
+        if (/context:[\s\S]*?所有文档必须使用中文/u.test(t))
+            return { action: `configure ${OPENSPEC_CONFIG_REL}`, status: "ok", detail: "OpenSpec 中文语境已存在" };
+        if (/^context:/mu.test(t)) {
+            const u = t.replace(/^context:\s*[|>]?\s*\n(?:[ \t].*\n)*/mu, `context: |\n  ${ZH_CTX}\n`);
+            mkdirSync(dirname(p), { recursive: true });
+            writeFileSync(p, u, "utf8");
+            return { action: `configure ${OPENSPEC_CONFIG_REL}`, status: "updated", detail: "OpenSpec context 已替换为简体中文语境" };
+        }
+        const s = t.endsWith("\n") ? "\ncontext: |\n" : "\n\ncontext: |\n";
+        mkdirSync(dirname(p), { recursive: true });
+        writeFileSync(p, `${t}${s}  ${ZH_CTX}\n`, "utf8");
+        return { action: `configure ${OPENSPEC_CONFIG_REL}`, status: "updated", detail: "OpenSpec context 已追加简体中文语境" };
+    }
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, `context: |\n  ${ZH_CTX}\n`, "utf8");
+    return { action: `configure ${OPENSPEC_CONFIG_REL}`, status: "created", detail: "OpenSpec 输出语言已设为简体中文" };
+}
 export function project_init(repoRootRaw = process.cwd(), opts = {}) {
     const repoRoot = resolve(repoRootRaw);
     const actions = [];
+    actions.push(ensure_openspec_chinese_context(repoRoot));
     const problems = [
         ...ensureOpenSpecCliSurface(repoRoot, actions),
         ...ensureSuperSpecWorkflow(repoRoot, actions, opts.force === true),

package/package.json

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

package/templates/workflow/prompts/explore.md

@@ -0,0 +1,27 @@
+---
+description: "仓库代码事实扫描与 discovery 覆盖辅助角色"
+argument-hint: "任务说明、workflow-packet 或 prompt_ref"
+---
+
+# Explore
+
+## 角色身份
+
+你是 Explore。你负责 repo-local 只读事实扫描：定位实现入口、源码锚点、隐性合约、相邻风险和 discovery 可能遗漏的事实。你不批准范围，不写正式证据，也不替代主流程决策。
+
+## 读写边界
+
+- 默认只读；不要修改文件。
+- 优先使用 repo search 和文件读取验证事实，结论必须绑定可读源码或文档锚点。
+- 不要写 `proposal.md`/`design.md`/`tasks.md`/`specs/**`/`.superspec/**`。
+- 不能作为 `explore_complete` 的 role evidence；需要门禁审查时交给 `critic`。
+
+## SuperSpec Packet 规则
+
+如果主流程提供 `workflow-packet` 或 `prompt_ref`，先读取 packet 指向的 refs。以 packet 中的 `target_refs`、`source_refs`、`required_load_refs`、`artifact_refs` 和 `stop_conditions` 为准；不要依赖本 prompt 记忆输出 schema。
+
+## 输出风格
+
+- 所有用户可见输出必须使用简体中文。
+- 命令、路径、JSON/schema 字段、gate 名称、任务/测试 id、代码标识符保留原文。
+- 结论先行；列出最相关文件/行号、已确认事实、仍缺的来源或需要主流程确认的问题。

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

@@ -35,10 +35,21 @@ Explore 只做需求澄清、代码事实调查、范围边界和风险记录。
 superspec init --scope project --format agent
 ```
 
-随后创建或打开 OpenSpec change，并读取当前上下文：
+随后用 `openspec list --json` 查找匹配 change；若已有则复用，若没有则直接创建，不要先跑 `openspec --help` / `openspec change --help` / `openspec new --help` 探测语法（命令失败或版本报错时才查 help 诊断）。
 
 ```text
 openspec list --json
+```
+
+仅当 `openspec list --json` 没有匹配 change 时运行：
+
+```text
+openspec new change "<change>" --description "<用户需求摘要>"
+```
+
+然后读取当前上下文：
+
+```text
 openspec status --change "<change>" --json
 superspec check check-init --change "<change>" --format agent
 superspec check workflow-packet --change "<change>" --gate explore_complete --format agent
@@ -52,6 +63,7 @@ superspec check workflow-packet --change "<change>" --gate explore_complete --fo
 - 用 `openspec list --json` 和 `openspec status --change "<change>" --json` 确认 change 结构、artifactPaths 和当前状态。
 - OpenSpec 负责 change 结构和后续 artifact 语义；本阶段只补 SuperSpec discovery 证据。
 - 如果发现需要正式方案、规格、设计或任务，先写入 discovery，再交给 `superspec-propose`。
+- 代码事实扫描可由主线程直接完成；若并行创建只读子代理，使用 repo-local `.codex/agents/explore.toml`。该角色只辅助 discovery 覆盖，不能替代 `critic` 审查证据。
 
 ## 专用代理边界
 

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

@@ -22,7 +22,7 @@ metadata:
 
 ## 阶段职责
 
-Propose 把 discovery 转成 OpenSpec proposal package，并补 SuperSpec 业务约束和测试契约。负责的文件是 `proposal.md`、`specs/**/*.md`、`design.md`、`tasks.md`、`.superspec/artifacts/business-invariants.md`、`.superspec/artifacts/test-contract.md`。本阶段不改实现代码。
+Propose 把 discovery 转成 OpenSpec proposal package，并按阶段生成 SuperSpec 业务约束和测试契约辅助文档。负责产出 `proposal.md`、`specs/**/*.md`、`design.md`、`tasks.md`，以及在需要时新建或更新 `.superspec/artifacts/business-invariants.md`、`.superspec/artifacts/test-contract.md`。本阶段不改实现代码。
 
 ## 第一条必跑命令
 
@@ -49,7 +49,10 @@ openspec instructions <artifact-id> --change "<change>" --json
 1. 运行 `openspec status --change "<change>" --json`，取 artifact 顺序、状态和 `resolvedOutputPath`。
 2. 每个 artifact（proposal/specs/design/tasks）运行 `openspec instructions <artifact-id> --change "<change>" --json`，取回 template/rules/context/instruction/dependencies。
 3. 先读 dependencies 列出的已完成 artifact，再按 template 写到 `resolvedOutputPath`；context/rules 是对作者的约束，不写进产出文件。
-4. sidecar（`.superspec/artifacts/business-invariants.md`、`.superspec/artifacts/test-contract.md`）用 SuperSpec 内置模板，写到 change 内 `.superspec/artifacts/`。
+4. 辅助文档（`.superspec/artifacts/business-invariants.md`、`.superspec/artifacts/test-contract.md`）如果尚不存在，就按 SuperSpec 内置模板在 change 内 `.superspec/artifacts/` 新建；已存在则基于当前阶段要求更新。
+5. `invariants_reviewed` 的 `workflow-packet` 会下发 `business_invariants_template` 与 `business_invariants_rules`；必须按该骨架直接填写，不得改成段落/列表。
+6. `test_contract_drafted` 的 `workflow-packet` 会下发 `test_contract_template` 与 `test_contract_rules`；必须按该骨架直接填写，不得改成段落/列表。
+7. `business-invariants.md` 的 `## Invariants` / `## Mapping` 和 `test-contract.md` 的 `## 测试覆盖矩阵` 必须保持 Markdown 表格，列名原样保留。
 
 ## Packet 驱动的阶段门