@peterxiaoyang/superspec 0.1.15-alpha → 0.1.17-alpha

package/README.md

@@ -77,17 +77,16 @@ npm install -g @peterxiaoyang/superspec@latest
 进入你的项目根目录，然后运行：
 
 ```bash
-superspec init --scope project
+superspec install
 ```
 
 这条命令的意思是：把 SuperSpec 当前可用的工作流入口安装到项目里。
-
-初始化还会安装托管的 `.codex/hooks.json`。默认 manifest 只在子智能体启动和停止时调用 SuperSpec，记录 best-effort 审计信息；它不会拦截普通文件写入，也不会在测试命令后自动记录结果。
+当前 beta 会安装 `.superspec/` 引擎目录、`.codex/skills/superspec-*` 阶段入口、`.codex/prompts/*.md` 角色 prompt、`.codex/agents/*.toml` 子智能体配置，并补齐 `.codex/config.toml` 的多 agent 开关。`superspec init --scope project` 仍作为兼容别名可用。
 
 Windows PowerShell 如果拦截 npm 的 `.ps1` 脚本，请改用：
 
 ```powershell
-superspec.cmd init --scope project
+superspec.cmd install
 ```
 
 ### 3. 按步骤使用
@@ -136,6 +135,8 @@ superspec.cmd init --scope project
 
 你日常主要记住这五个入口就够了。
 
+CLI 不带 `--risk` 时默认走完整审查路径；需要轻量路径时显式传 `--risk normal` 或 `--risk minimal`。探索阶段会创建 `critic` 工作项审查需求澄清记录；计划阶段会创建 `critic`、`architect` 和 `test-engineer` 工作项后再进入实现准备。
+
 ## 它会多保存哪些记录
 
 SuperSpec 会在每次变更下面保存一些辅助记录，方便后续追溯。
@@ -200,59 +201,76 @@ superspec --version
 安装到当前项目：
 
 ```bash
-superspec init --scope project
+superspec install
 ```
 
-更新当前项目里的 SuperSpec 入口：
+`superspec init --scope project` 是兼容别名，也会执行同一套安装逻辑。
 
-```bash
-superspec update --scope project
+### OpenSpec 中文输出
+
+OpenSpec 生成文档的语言应通过官方项目配置控制。在 `openspec/config.yaml` 中使用 `context`：
+
+```yaml
+schema: spec-driven
+
+context: |
+  语言：中文（简体）
+  所有产出物必须用简体中文撰写。
 ```
 
-这条命令会先通过 npm 更新全局 `@peterxiaoyang/superspec`，再用新版本更新当前项目里的入口文件。只想使用当前已安装包更新项目文件时，可以运行：
+`superspec install` 会创建缺失的 `openspec/config.yaml`，或在没有顶层 `context` 时追加这段官方中文 context。如果文件已经有顶层 `context`，SuperSpec 不会覆盖它。
+
+可以用下面的命令检查生成的 instructions 是否包含语言上下文：
 
 ```bash
-superspec update --scope project --local-only
+openspec instructions proposal --change <change>
 ```
 
-卸载当前项目里的 SuperSpec 入口：
+检查当前项目的 OpenSpec 探测结果：
 
 ```bash
-superspec uninstall --scope project
+superspec status
 ```
 
-这些命令默认不会删除已经生成的 `.superspec/` 过程记录。
-
-诊断全局安装、PATH、OpenSpec 依赖和 npm bin 指向问题：
+更新当前 beta CLI：
 
 ```bash
-superspec doctor
+superspec update
 ```
 
+这条命令只检查当前 `.superspec/changes` 运行时是否已经是新引擎布局；真正升级全局 npm 包仍需使用 `npm install -g @peterxiaoyang/superspec@<version>`。
+
 ## 进阶信息
 
 以当前内置的 Codex 适配器为例，初始化后项目里会出现这些入口文件：
 
 ```text
 .codex/
-  hooks.json
   skills/superspec-explore/
   skills/superspec-propose/
   skills/superspec-apply/
   skills/superspec-review/
   skills/superspec-archive/
+  prompts/architect.md
+  prompts/code-reviewer.md
+  prompts/critic.md
+  prompts/executor.md
+  prompts/explore.md
+  prompts/test-engineer.md
+  prompts/test-runner.md
+  prompts/verifier.md
+  agents/architect.toml
+  agents/code-reviewer.toml
+  agents/critic.toml
+  agents/executor.toml
+  agents/explore.toml
+  agents/test-engineer.toml
+  agents/test-runner.toml
+  agents/verifier.toml
+  config.toml
 ```
 
-SuperSpec 内部还有一些检查命令，例如：
-
-```bash
-superspec check check-init --change <变更ID>
-superspec check check-apply-ready --change <变更ID>
-superspec check check-review-ready --change <变更ID>
-superspec check check-archive-ready --change <变更ID>
-```
-
-普通使用者通常不需要手动运行这些命令；对应的阶段入口会在需要时使用它们。
+当前 beta 的阶段入口由 `superspec transition next --change <变更ID>` 驱动，不再提供旧版 `superspec check ...` surface。
 
 如果你要开发 SuperSpec 本身：
 
@@ -260,14 +278,13 @@ superspec check check-archive-ready --change <变更ID>
 npm run build
 npm run typecheck
 npm test
-npm run pack:dry-run
+npm pack --dry-run
 ```
 
 更多细节见：
 
-- `docs/SPEC.md`：完整设计和规则
-- `docs/DISTRIBUTION.md`：安装、升级、卸载和分发说明
-- `.codex/skills/superspec-*/SKILL.md`：当前 Codex 适配器使用的阶段入口说明
+- `docs/plans/SUPERSPEC_TRANSITION_ENGINE_SPEC_LITE.md`：transition engine 设计
+- `templates/workflow/skills/superspec-*/SKILL.md`：当前 Codex 适配器使用的阶段入口说明
 
 ## 致谢与灵感来源
 

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // SuperSpec 流程引擎 — CLI 入口
-import { writeFileSync, mkdirSync, existsSync } from "node:fs";
 import { join } from "node:path";
+import { installProject } from "./install.js";
 import { writeSnapshot } from "./store.js";
 import { rebuildSnapshot } from "./sync.js";
 import { next as nextCmd } from "./next.js";
@@ -44,7 +44,7 @@ function parseFlags(args) {
 async function main(argv) {
     // --help / 无参数 → 打印用法
     if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {
-        console.log(`SuperSpec 流程引擎 0.1.15-alpha
+        console.log(`SuperSpec 流程引擎 0.1.16-alpha
 
 用法：superspec <命令> [选项]
 
@@ -53,7 +53,8 @@ async function main(argv) {
   transition <子命令> --change <C>  状态流转（见下）
   record <子命令> --change <C>      登记证据（见下）
   jobs <子命令> --change <C>        工作项管理（见下）
-  install [--global]               安装到项目或全局
+  install                           安装项目工作流入口
+  init --scope project              install 的兼容别名
   update                           更新 SuperSpec
   version                          版本号
 
@@ -74,36 +75,31 @@ jobs 子命令：
     }
     // version
     if (argv[0] === "version" || argv[0] === "--version" || argv[0] === "-v") {
-        console.log("SuperSpec 0.1.15-alpha");
+        console.log("SuperSpec 0.1.16-alpha");
         return 0;
     }
     const { command, subcommand, opts } = parseArgs(argv);
     const projectRoot = process.cwd();
-    // install / update 不需要 --change
-    if (command === "install") {
-        const { mkdirSync, writeFileSync, existsSync, readdirSync, readFileSync } = await import("node:fs");
-        const engineDir = join(projectRoot, ".superspec");
-        // 检测老版残留（0.x 的 superspec-state.json / superspec-state.lock）
-        const oldStateFiles = ["superspec-state.json", "superspec-state.lock", "ledger.jsonl"];
-        const foundOld = oldStateFiles.some(f => existsSync(join(projectRoot, "openspec", "changes")) &&
-            readdirSync(join(projectRoot, "openspec", "changes")).some(c => existsSync(join(projectRoot, "openspec", "changes", c, ".superspec", f))));
-        if (foundOld) {
+    // install / init / update 不需要 --change
+    if (command === "install" || command === "init") {
+        if (command === "init" && opts.scope && opts.scope !== "project") {
             console.log(JSON.stringify({
                 ok: false,
-                message: "检测到老版 SuperSpec (0.x) 的状态文件。\n" +
-                    "SuperSpec 0.1.15-alpha 是全新引擎，不兼容 0.x 的状态格式。\n" +
-                    "请先用老版（0.1.x）完成或归档现有 change，再安装 0.1.15-alpha。\n" +
-                    "或在全新项目目录中安装。",
+                message: "当前 beta 只支持 init --scope project",
+            }));
+            return 1;
+        }
+        try {
+            console.log(JSON.stringify(installProject(projectRoot)));
+            return 0;
+        }
+        catch (err) {
+            console.log(JSON.stringify({
+                ok: false,
+                message: err.message,
             }));
             return 1;
         }
-        if (!existsSync(engineDir))
-            mkdirSync(join(engineDir, "changes"), { recursive: true });
-        const gitignorePath = join(engineDir, ".gitignore");
-        if (!existsSync(gitignorePath))
-            writeFileSync(gitignorePath, "changes/\n*.log\n*.tmp\n");
-        console.log(JSON.stringify({ ok: true, message: "SuperSpec 0.1.15-alpha 已安装" }));
-        return 0;
     }
     if (command === "update") {
         // 检测是否从老版 update 过来
@@ -112,13 +108,13 @@ jobs 子命令：
         if (isLegacyUpdate) {
             console.log(JSON.stringify({
                 ok: false,
-                message: "SuperSpec 0.1.15-alpha 是全新引擎，不能从 0.x 直接 update。\n" +
-                    "请用 npm install -g @peterxiaoyang/superspec@0.1.15-alpha 手动安装。\n" +
+                message: "SuperSpec 0.1.16-alpha 是全新引擎，不能从 0.x 直接 update。\n" +
+                    "请用 npm install -g @peterxiaoyang/superspec@0.1.16-alpha 手动安装。\n" +
                     "现有 change 请先用 0.1.x 完成归档。",
             }));
             return 1;
         }
-        console.log(JSON.stringify({ ok: true, message: "已是最新版本 0.1.15-alpha" }));
+        console.log(JSON.stringify({ ok: true, message: "已是最新版本 0.1.16-alpha" }));
         return 0;
     }
     const change = opts.change;
@@ -138,12 +134,20 @@ jobs 子命令：
                 const cr = changeRoot(projectRoot, change);
                 const snapshot = rebuildSnapshot(projectRoot, change, cr);
                 const jobs = jobsList(projectRoot, change);
+                const staleAcceptedJobs = Math.max(0, jobs.accepted.length - snapshot.accepted_jobs.length);
                 console.log(JSON.stringify({
                     change,
                     state: snapshot.state,
-                    open_jobs: jobs.open.length,
-                    accepted_jobs: jobs.accepted.length,
+                    open_jobs: snapshot.open_jobs.length,
+                    accepted_jobs: snapshot.accepted_jobs.length,
+                    historical_accepted_jobs: jobs.accepted.length,
+                    stale_accepted_jobs: staleAcceptedJobs,
                     rejected_jobs: jobs.rejected.length,
+                    active_task_attempts: snapshot.active_task_attempts.map(a => ({
+                        attempt_id: a.attempt_id,
+                        task_id: a.task_id,
+                        state: a.state,
+                    })),
                     document_digests: snapshot.document_digests,
                     last_transition: snapshot.last_transition,
                 }, null, 2));
@@ -156,7 +160,10 @@ jobs 子命令：
                         console.log(JSON.stringify(transitionInit(projectRoot, change, cr), null, 2));
                         return 0;
                     case "explore":
-                        console.log(JSON.stringify(transitionExplore(projectRoot, change, cr), null, 2));
+                        {
+                            const risk = opts.risk ?? "strict";
+                            console.log(JSON.stringify(transitionExplore(projectRoot, change, cr, risk), null, 2));
+                        }
                         return 0;
                     case "sync": {
                         const snapshot = rebuildSnapshot(projectRoot, change, cr, openspecStatus(projectRoot, change));
@@ -170,13 +177,13 @@ jobs 子命令：
                         return 0;
                     }
                     case "next": {
-                        const risk = opts.risk ?? "normal";
+                        const risk = opts.risk ?? "strict";
                         const result = nextCmd(projectRoot, change, cr, risk);
                         console.log(JSON.stringify(result, null, 2));
                         return 0;
                     }
                     case "propose-ready": {
-                        const risk = opts.risk ?? "normal";
+                        const risk = opts.risk ?? "strict";
                         const result = proposeReady(projectRoot, change, cr, risk);
                         console.log(JSON.stringify(result, null, 2));
                         return result.events_written === 0 && result.message.includes("不能") ? 1 : 0;
@@ -207,7 +214,7 @@ jobs 子命令：
                         return result.events_written === 0 ? 1 : 0;
                     }
                     case "review-ready": {
-                        const risk = opts.risk ?? "normal";
+                        const risk = opts.risk ?? "strict";
                         const result = reviewReady(projectRoot, change, cr, risk);
                         console.log(JSON.stringify(result, null, 2));
                         return result.events_written === 0 ? 1 : 0;
@@ -289,7 +296,7 @@ jobs 子命令：
                 }
             }
             default:
-                console.error(`未知命令：${command}。可用：status, transition, record, jobs`);
+                console.error(`未知命令：${command}。可用：status, transition, record, jobs, install, init, update, version`);
                 return 1;
         }
     }

package/dist/format.d.ts

@@ -6,6 +6,15 @@ export declare function validateDiscovery(changeRoot: string): {
     message: string;
     openCount: number;
 };
+export interface ProposeOpenQuestionFile {
+    path: string;
+    openCount: number;
+}
+export declare function countProposeOpenQuestionsInContent(content: string): number;
+export declare function collectProposeOpenQuestions(changeRoot: string): {
+    openCount: number;
+    files: ProposeOpenQuestionFile[];
+};
 export interface ParsedTask {
     taskId: string;
     lineIdx: number;

package/dist/format.js

@@ -12,10 +12,12 @@ import { join } from "node:path";
 //   - [ ] 问题2的描述
 //
 // 引擎只解析"待确认问题"段内的 `- [ ]`，不误判正常 checklist。
-/** 从 discovery.md 提取"待确认问题"段内的未确认项数量 */
-export function countDiscoveryOpenQuestions(content) {
-    // 找"待确认问题"标题（中英文兼容）
-    const sectionMatch = content.match(/^#{1,6}\s*(待确认问题|Open Questions|Pending Questions)\s*$/im);
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function countOpenChecklistItemsInSection(content, headings) {
+    const headingPattern = headings.map(escapeRegex).join("|");
+    const sectionMatch = new RegExp(`^#{1,6}\\s*(?:${headingPattern})\\s*$`, "im").exec(content);
     if (!sectionMatch)
         return 0;
     const sectionStart = sectionMatch.index + sectionMatch[0].length;
@@ -24,9 +26,13 @@ export function countDiscoveryOpenQuestions(content) {
     const nextHeadingMatch = restContent.match(/^#{1,6}\s+/m);
     const sectionBody = nextHeadingMatch ? restContent.slice(0, nextHeadingMatch.index) : restContent;
     // 数未确认项
-    const matches = sectionBody.match(/- \[ \]/g);
+    const matches = sectionBody.match(/^\s*-\s+\[ \]/gm);
     return matches ? matches.length : 0;
 }
+/** 从 discovery.md 提取"待确认问题"段内的未确认项数量 */
+export function countDiscoveryOpenQuestions(content) {
+    return countOpenChecklistItemsInSection(content, ["待确认问题", "Open Questions", "Pending Questions"]);
+}
 /** 完整校验 discovery.md：存在 + 非空 + 无未确认问题 */
 export function validateDiscovery(changeRoot) {
     const path = join(changeRoot, ".superspec", "artifacts", "discovery.md");
@@ -40,6 +46,30 @@ export function validateDiscovery(changeRoot) {
         return { ok: false, message: `discovery.md 有 ${openCount} 个未确认问题`, openCount };
     return { ok: true, message: "discovery.md 就绪", openCount: 0 };
 }
+const PROPOSE_CONFIRMATION_DOCS = [
+    "proposal.md",
+    "design.md",
+    ".superspec/artifacts/test-contract.md",
+];
+const PROPOSE_CONFIRMATION_HEADINGS = ["待用户确认", "待确认问题", "Open Questions", "Pending Questions"];
+export function countProposeOpenQuestionsInContent(content) {
+    return countOpenChecklistItemsInSection(content, PROPOSE_CONFIRMATION_HEADINGS);
+}
+export function collectProposeOpenQuestions(changeRoot) {
+    const files = [];
+    for (const path of PROPOSE_CONFIRMATION_DOCS) {
+        const fullPath = join(changeRoot, path);
+        if (!existsSync(fullPath))
+            continue;
+        const openCount = countProposeOpenQuestionsInContent(readFileSync(fullPath, "utf8"));
+        if (openCount > 0)
+            files.push({ path, openCount });
+    }
+    return {
+        openCount: files.reduce((sum, file) => sum + file.openCount, 0),
+        files,
+    };
+}
 const TASK_LINE_RE = /^(- \[([ xX])\])\s+(\S+)/;
 /** 解析 tasks.md 的全部任务行 */
 export function parseTasksMd(content) {

package/dist/install.d.ts

@@ -0,0 +1,19 @@
+export declare const WORKFLOW_SKILLS: readonly ["superspec-explore", "superspec-propose", "superspec-apply", "superspec-review", "superspec-archive"];
+export declare const WORKFLOW_PROMPTS: readonly ["architect.md", "code-reviewer.md", "critic.md", "executor.md", "explore.md", "test-engineer.md", "test-runner.md", "verifier.md"];
+export declare const WORKFLOW_AGENTS: readonly ["architect.toml", "code-reviewer.toml", "critic.toml", "executor.toml", "explore.toml", "test-engineer.toml", "test-runner.toml", "verifier.toml"];
+export interface InstallResult {
+    ok: boolean;
+    message: string;
+    installed: {
+        engine_dir: string;
+        skills: string[];
+        prompts: string[];
+        agents: string[];
+        config: string;
+        openspec_config: string;
+    };
+}
+export interface InstallOptions {
+    templateRoot?: string;
+}
+export declare function installProject(projectRoot: string, options?: InstallOptions): InstallResult;

package/dist/install.js

@@ -0,0 +1,185 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+export const WORKFLOW_SKILLS = [
+    "superspec-explore",
+    "superspec-propose",
+    "superspec-apply",
+    "superspec-review",
+    "superspec-archive",
+];
+export const WORKFLOW_PROMPTS = [
+    "architect.md",
+    "code-reviewer.md",
+    "critic.md",
+    "executor.md",
+    "explore.md",
+    "test-engineer.md",
+    "test-runner.md",
+    "verifier.md",
+];
+export const WORKFLOW_AGENTS = [
+    "architect.toml",
+    "code-reviewer.toml",
+    "critic.toml",
+    "executor.toml",
+    "explore.toml",
+    "test-engineer.toml",
+    "test-runner.toml",
+    "verifier.toml",
+];
+function defaultTemplateRoot() {
+    return join(import.meta.dirname, "..", "templates", "workflow");
+}
+function legacyStateFound(projectRoot) {
+    const changesRoot = join(projectRoot, "openspec", "changes");
+    if (!existsSync(changesRoot))
+        return false;
+    const oldStateFiles = ["superspec-state.json", "superspec-state.lock", "ledger.jsonl"];
+    return oldStateFiles.some(file => readdirSync(changesRoot).some(change => existsSync(join(changesRoot, change, ".superspec", file))));
+}
+function assertWorkflowTemplates(templateRoot) {
+    const missing = [];
+    for (const skill of WORKFLOW_SKILLS) {
+        const file = join(templateRoot, "skills", skill, "SKILL.md");
+        if (!existsSync(file))
+            missing.push(file);
+    }
+    for (const prompt of WORKFLOW_PROMPTS) {
+        const file = join(templateRoot, "prompts", prompt);
+        if (!existsSync(file))
+            missing.push(file);
+    }
+    for (const agent of WORKFLOW_AGENTS) {
+        const file = join(templateRoot, "agents", agent);
+        if (!existsSync(file))
+            missing.push(file);
+    }
+    if (missing.length > 0) {
+        throw new Error(`workflow templates missing: ${missing.join(", ")}`);
+    }
+}
+function copySkills(templateRoot, projectRoot) {
+    const skillsDest = join(projectRoot, ".codex", "skills");
+    const installedSkills = [];
+    for (const skill of WORKFLOW_SKILLS) {
+        const src = join(templateRoot, "skills", skill, "SKILL.md");
+        mkdirSync(join(skillsDest, skill), { recursive: true });
+        copyFileSync(src, join(skillsDest, skill, "SKILL.md"));
+        installedSkills.push(skill);
+    }
+    return installedSkills;
+}
+function copyPrompts(templateRoot, projectRoot) {
+    const promptsDest = join(projectRoot, ".codex", "prompts");
+    const installedPrompts = [];
+    for (const prompt of WORKFLOW_PROMPTS) {
+        const src = join(templateRoot, "prompts", prompt);
+        mkdirSync(promptsDest, { recursive: true });
+        copyFileSync(src, join(promptsDest, prompt));
+        installedPrompts.push(prompt);
+    }
+    return installedPrompts;
+}
+function copyAgents(templateRoot, projectRoot) {
+    const agentsDest = join(projectRoot, ".codex", "agents");
+    const installedAgents = [];
+    for (const agent of WORKFLOW_AGENTS) {
+        const src = join(templateRoot, "agents", agent);
+        mkdirSync(agentsDest, { recursive: true });
+        copyFileSync(src, join(agentsDest, agent));
+        installedAgents.push(agent);
+    }
+    return installedAgents;
+}
+function insertMissingTableEntries(content, table, entries) {
+    const tablePattern = new RegExp(`^\\[${table}\\]\\s*$`, "m");
+    const tableMatch = tablePattern.exec(content);
+    const lines = Object.entries(entries).map(([key, value]) => `${key} = ${value}`);
+    if (!tableMatch) {
+        const separator = content.trim().length === 0 ? "" : "\n\n";
+        return `${content.trimEnd()}${separator}[${table}]\n${lines.join("\n")}\n`;
+    }
+    const tableStart = tableMatch.index;
+    const headerEnd = tableStart + tableMatch[0].length;
+    const nextTable = /^\[[^\]]+\]\s*$/m.exec(content.slice(headerEnd));
+    const tableEnd = nextTable ? headerEnd + nextTable.index : content.length;
+    const tableBody = content.slice(headerEnd, tableEnd);
+    const missing = lines.filter(line => {
+        const key = line.split(" = ", 1)[0];
+        return !new RegExp(`^\\s*${key}\\s*=`, "m").test(tableBody);
+    });
+    if (missing.length === 0)
+        return content;
+    return `${content.slice(0, headerEnd)}\n${missing.join("\n")}${content.slice(headerEnd)}`;
+}
+function ensureCodexConfig(projectRoot) {
+    const codexDir = join(projectRoot, ".codex");
+    const configPath = join(codexDir, "config.toml");
+    mkdirSync(codexDir, { recursive: true });
+    const current = existsSync(configPath) ? readFileSync(configPath, "utf8") : "";
+    let next = insertMissingTableEntries(current, "features", {
+        multi_agent: "true",
+        child_agents_md: "true",
+    });
+    next = insertMissingTableEntries(next, "agents", {
+        max_threads: "12",
+        max_depth: "1",
+    });
+    if (next !== current)
+        writeFileSync(configPath, next);
+    return ".codex/config.toml";
+}
+const OPENSPEC_CONFIG_PATH = "openspec/config.yaml";
+const OPENSPEC_CHINESE_CONTEXT_BLOCK = "context: |\n" +
+    "  语言：中文（简体）\n" +
+    "  所有产出物必须用简体中文撰写。\n";
+const OPENSPEC_DEFAULT_CONFIG = "schema: spec-driven\n\n" +
+    OPENSPEC_CHINESE_CONTEXT_BLOCK;
+function hasTopLevelContext(content) {
+    return /^context\s*:/m.test(content);
+}
+function ensureOpenSpecChineseContext(projectRoot) {
+    const openspecDir = join(projectRoot, "openspec");
+    const configPath = join(projectRoot, OPENSPEC_CONFIG_PATH);
+    mkdirSync(openspecDir, { recursive: true });
+    if (!existsSync(configPath)) {
+        writeFileSync(configPath, OPENSPEC_DEFAULT_CONFIG);
+        return OPENSPEC_CONFIG_PATH;
+    }
+    const current = readFileSync(configPath, "utf8");
+    if (hasTopLevelContext(current))
+        return OPENSPEC_CONFIG_PATH;
+    const trimmed = current.trimEnd();
+    const next = trimmed.length > 0
+        ? `${trimmed}\n\n${OPENSPEC_CHINESE_CONTEXT_BLOCK}`
+        : OPENSPEC_DEFAULT_CONFIG;
+    writeFileSync(configPath, next);
+    return OPENSPEC_CONFIG_PATH;
+}
+export function installProject(projectRoot, options = {}) {
+    if (legacyStateFound(projectRoot)) {
+        throw new Error("检测到老版 SuperSpec (0.x) 的状态文件。\n" +
+            "SuperSpec 0.1.16-alpha 是全新引擎，不兼容 0.x 的状态格式。\n" +
+            "请先用老版（0.1.x）完成或归档现有 change，再安装 0.1.16-alpha。\n" +
+            "或在全新项目目录中安装。");
+    }
+    const templateRoot = options.templateRoot ?? defaultTemplateRoot();
+    assertWorkflowTemplates(templateRoot);
+    const engineDir = join(projectRoot, ".superspec");
+    mkdirSync(join(engineDir, "changes"), { recursive: true });
+    const gitignorePath = join(engineDir, ".gitignore");
+    if (!existsSync(gitignorePath))
+        writeFileSync(gitignorePath, "changes/\n*.log\n*.tmp\n");
+    return {
+        ok: true,
+        message: "SuperSpec 0.1.16-alpha 已安装",
+        installed: {
+            engine_dir: ".superspec/",
+            skills: copySkills(templateRoot, projectRoot),
+            prompts: copyPrompts(templateRoot, projectRoot),
+            agents: copyAgents(templateRoot, projectRoot),
+            config: ensureCodexConfig(projectRoot),
+            openspec_config: ensureOpenSpecChineseContext(projectRoot),
+        },
+    };
+}