create-yss-spec 3.3.0 → 3.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-yss-spec",
-  "version": "3.3.0",
+  "version": "3.3.1",
   "description": "Initialize a YSS spec project template repository",
   "main": "src/api/index.js",
   "repository": {
@@ -28,7 +28,8 @@
     "test:contracts": "node --test tests/contracts.test.js tests/error-output.test.js tests/apply-result-contract.test.js",
     "test:unit": "node --test tests/*planner*.test.js tests/filesystem-*.test.js tests/validation-modules.test.js tests/doctor-checks.test.js tests/ownership-policy.test.js tests/lifecycle-policy.test.js tests/lifecycle-metadata.test.js tests/verification-runtime.test.js tests/cli-modules.test.js tests/cli-entrypoint.test.js tests/self-update.test.js tests/plan-schema.test.js tests/contracts.test.js tests/error-output.test.js tests/apply-result-contract.test.js tests/programmatic-api-unit.test.js",
     "test:integration": "npm run sync-template && node --test tests/init-cli.test.js tests/sync-command-modular.test.js tests/attach-command-modular.test.js tests/doctor-diff-command.test.js tests/programmatic-api.test.js tests/family-identity.test.js",
-    "prepack": "npm run sync-template"
+    "prepack": "npm run sync-template",
+    "test:prepared": "node --test --test-concurrency=1 tests/*.test.js"
   },
   "devDependencies": {
     "ajv": "^8.17.1"

package/src/command-runner.mjs

@@ -0,0 +1,107 @@
+import { spawn, spawnSync } from "node:child_process";
+import { appendFileSync, rmSync, writeFileSync } from "node:fs";
+import { StringDecoder } from "node:string_decoder";
+import { fileURLToPath } from "node:url";
+
+function killTree(child, signal) {
+  if (!child.pid) return;
+  try {
+    if (process.platform === "win32") spawnSync("taskkill", ["/PID", String(child.pid), "/T", "/F"], { stdio: "ignore" });
+    else process.kill(-child.pid, signal);
+  } catch (error) { if (error.code !== "ESRCH") throw error; }
+}
+
+/** Bounded lifetime for external tools; stdout is never mixed with progress. */
+export function runCommand(command, args, { cwd, env = process.env, timeoutMs = 0, signal, stdoutFile, stderrFile, secrets = [], progress = false } = {}) {
+  if (!Number.isFinite(timeoutMs) || timeoutMs < 0) throw new TypeError("timeoutMs 必须是非负毫秒数");
+  if (signal?.aborted) return Promise.resolve({ status: 1, stdout: "", stderr: "command cancelled", termination: "cancelled", duration_ms: 0 });
+  return new Promise(resolve => {
+    const started = performance.now();
+    const argumentSecrets = args.flatMap(value => { try { const url = new URL(value); return url.password ? [url.password, decodeURIComponent(url.password)] : []; } catch { return []; } });
+    const secretNames = new Map(Object.entries(env).filter(([key]) => /(?:PASSWORD|TOKEN|SECRET)$/.test(key) || key === "MAVEN_REPO_USERNAME").map(([key,value]) => [value,key]));
+    const replacement = secret => secretNames.has(secret) ? `[REDACTED:${secretNames.get(secret)}]` : "[REDACTED]";
+    const sensitive = [...secrets, ...argumentSecrets, ...secretNames.keys()].filter(value => typeof value === "string" && value.length > 0).sort((a, b) => b.length - a.length);
+    const redact = text => sensitive.reduce((value, secret) => value.replaceAll(secret, replacement(secret)), text);
+    if (progress) process.stderr.write(`[开始] ${redact(command + " " + args.join(" "))}\n`);
+    for (const file of [stdoutFile, stderrFile]) if (file) writeFileSync(file, "");
+    const child = spawn(command, args, { cwd, env, detached: process.platform !== "win32", stdio: ["ignore", "pipe", "pipe"] });
+    let termination = null, escalation, timer, errorMessage;
+    const makeStream = file => {
+      const decoder = new StringDecoder("utf8");
+      let pending = "", captured = "";
+      const emit = text => { captured += text; if (file) appendFileSync(file, text); };
+      function consume(final = false) {
+        let output = "", cursor = 0;
+        while (cursor < pending.length) {
+          const match = sensitive.find(secret => pending.startsWith(secret, cursor));
+          if (match) { output += replacement(match); cursor += match.length; continue; }
+          if (!final && sensitive.some(secret => secret.startsWith(pending.slice(cursor)))) break;
+          output += pending[cursor++];
+        }
+        pending = pending.slice(cursor);
+        emit(output);
+      }
+      return { write(bytes) { pending += decoder.write(bytes); consume(); }, end() { pending += decoder.end(); consume(true); return captured; } };
+    };
+    const stdout = makeStream(stdoutFile), stderr = makeStream(stderrFile);
+    function cancel(reason) {
+      if (termination) return;
+      termination = reason;
+      killTree(child, "SIGTERM");
+      escalation = setTimeout(() => killTree(child, "SIGKILL"), 1000);
+    }
+    const abort = () => cancel("cancelled");
+    const onInterrupt = () => cancel("cancelled");
+    signal?.addEventListener("abort", abort, { once: true });
+    process.on("SIGINT", onInterrupt); process.on("SIGTERM", onInterrupt);
+    if (timeoutMs) timer = setTimeout(() => cancel("timeout"), timeoutMs);
+    child.stdout.on("data", bytes => stdout.write(bytes));
+    child.stderr.on("data", bytes => stderr.write(bytes));
+    child.on("error", error => { errorMessage = redact(error.message); });
+    child.on("close", (code, exitSignal) => {
+      clearTimeout(timer); clearTimeout(escalation);
+      // A group leader can exit before its descendants close redirected streams.
+      if (termination) killTree(child, "SIGKILL");
+      signal?.removeEventListener("abort", abort);
+      process.off("SIGINT", onInterrupt); process.off("SIGTERM", onInterrupt);
+      const duration_ms = performance.now() - started;
+      const status = termination === "timeout" ? 124 : termination ? 1 : code ?? 1;
+      if (progress) process.stderr.write(`[${status === 0 ? "完成" : "失败"}] ${command} (${Math.round(duration_ms)}ms, exit=${status}${termination ? `, ${termination}` : ""})\n`);
+      resolve({ status, stdout: stdout.end(), stderr: stderr.end() + (errorMessage || ""), signal: exitSignal, termination, duration_ms });
+    });
+  });
+}
+
+// Synchronous API compatibility for existing generators/cache consumers. The worker
+// owns the process group and streams logs; it never updates project metadata.
+export function runCommandSync(command, args, options = {}) {
+  const result = spawnSync(process.execPath, [fileURLToPath(import.meta.url), "--worker"], {
+    input: JSON.stringify({ command, args, options }), encoding: "utf8", maxBuffer: 64 * 1024 * 1024,
+    stdio: ["pipe", "pipe", "inherit"], env: options.env ?? process.env,
+  });
+  if (result.error || result.status !== 0) throw new TypeError(result.error?.message || "command worker failed");
+  return JSON.parse(result.stdout);
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url) && process.argv[2] === "--worker") {
+  const parent = process.ppid;
+  let input = "";
+  for await (const bytes of process.stdin) input += bytes;
+  const { command, args, options } = JSON.parse(input);
+  const controller = new AbortController();
+  const watchParent = setInterval(() => {
+    if (process.ppid !== parent) controller.abort();
+    else {
+      try { process.kill(parent, 0); } catch (error) { if (error.code === "ESRCH") controller.abort(); }
+    }
+  }, 100);
+  try {
+    const result = await runCommand(command, args, { ...options, signal: controller.signal });
+    if (result.status !== 0) {
+      // Only caller-created temporary resources are supplied here. The worker
+      // also owns this cleanup when a terminated synchronous caller cannot run finally.
+      for (const directory of options.cleanupPathsOnFailure || []) rmSync(directory, { recursive: true, force: true });
+    }
+    if (process.ppid === parent) process.stdout.write(JSON.stringify(result));
+  } finally { clearInterval(watchParent); }
+}

package/src/self-update.js

@@ -46,11 +46,14 @@ function compareSemver(left, right) {
 }
 
 function defaultSpawn(command, args, options = {}) {
-  return spawnSync(command, args, {
-    encoding: "utf8",
-    timeout: 120000,
-    ...options,
+  const result = spawnSync(process.execPath, [path.join(__dirname, "command-runner.mjs"), "--worker"], {
+    input: JSON.stringify({ command, args, options: { cwd: options.cwd, env: options.env || process.env, timeoutMs: options.timeout ?? 120000 } }),
+    encoding: "utf8", maxBuffer: 64 * 1024 * 1024,
   });
+  if (result.error || result.status !== 0) return result;
+  const outcome = JSON.parse(result.stdout);
+  if (outcome.termination) outcome.stderr = outcome.termination + ": " + outcome.stderr;
+  return outcome;
 }
 
 function spawnFailed(result) {

package/src/template/instance-runtime.js

@@ -168,7 +168,7 @@ function renderTemplateFile(relativePath, content, variables) {
 
     if (!variables.includeExampleDocs) {
       return renderedContent.replace(
-        /^\| \[docs\/discovery\/IDEATION\.md\]\(\.\/docs\/discovery\/IDEATION\.md\) \|.*\r?\n/m,
+        /^\| \[docs\/plan\/IDEATION\.md\]\(\.\/docs\/plan\/IDEATION\.md\) \|.*\r?\n/m,
         "",
       );
     }

package/template/.agents/skills/.strategic-design-skills-manifest.json

@@ -3,7 +3,7 @@
   "source": "iloveZzz/yss-harness-design-agent",
   "source_type": "git-submodule",
   "source_root": ".agents/skills",
-  "source_revision": "8a67e0f5a56aa5085d18c2b42bb540c8f36c2fab",
+  "source_revision": "3a358684c5684ada433dca4fd97ee187050ca6d8",
   "adaptation_ref": "docs/agents/strategic-design-skills-integration.md",
   "skills": [
     {
@@ -34,7 +34,7 @@
     {
       "upstream": "yss-stage-decision",
       "canonical": "yss-stage-decision",
-      "upstream_hash": "1eadf230f0e17bf6d209c1df1249acef3520ab29c26a80c476a2a557a224c10a"
+      "upstream_hash": "2ec63f66aaf799d693cec0f0b5d71b8c4917e4e2822e0ddd519bc9b711fa3c95"
     }
   ]
 }

package/template/.agents/skills/competitive-intelligence/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: competitive-intelligence
-description: Use when researching competitors, market positioning, pricing, feature gaps, customer sentiment, or category trends before Discovery, Spec, product strategy, or roadmap decisions.
+description: Use when researching competitors, market positioning, pricing, feature gaps, customer sentiment, or category trends before Plan, Spec, product strategy, or roadmap decisions.
 ---
 
 # Competitive Intelligence
 
 Source requested for this project: `anthropics/knowledge-work-plugins`, `sales/skills/competitive-intelligence`.
 
-Use this skill when competitive or market facts are needed to shape product Discovery, Spec scope, positioning, differentiation, pricing assumptions, or roadmap tradeoffs.
+Use this skill when competitive or market facts are needed to shape product Plan, Spec scope, positioning, differentiation, pricing assumptions, or roadmap tradeoffs.
 
 ## Core Rules
 
@@ -45,8 +45,8 @@ Use this skill when competitive or market facts are needed to shape product Disc
    - Risks if we copy the competitor too closely.
    - Product opportunities for Spec or roadmap.
 5. Hand off to lifecycle assets:
-   - Update Discovery findings in `docs/.scratch/<feature>/discovery/`.
-   - Create or update a competitor matrix in `docs/.scratch/<feature>/discovery/reports/`.
+   - Update Plan findings in `docs/.scratch/<feature>/plan/`.
+   - Create or update a competitor matrix in `docs/.scratch/<feature>/plan/reports/`.
    - Feed stable user, pain, MVP, non-goal, and success criteria into `grill-with-docs` and `to-spec`.
    - Record uncertain claims as assumptions, not requirements.
 

package/template/.agents/skills/domain-modeling/CONTEXT-FORMAT.md

@@ -45,7 +45,7 @@ context_schema_version: 1
 
 ## 内容边界
 
-- 只写已经确认、稳定且未来资产需要复用的业务语言。候选、猜测和未决术语保留在 Discovery、业务边界与规则设计或 `context_delta`。
+- 只写已经确认、稳定且未来资产需要复用的业务语言。候选、猜测和未决术语保留在 Plan、业务边界与规则设计或 `context_delta`。
 - 定义保持一到两句，说明概念是什么；不要写类全名、表名、接口路径、实现步骤或计划。
 - 禁用别名使用 `避免：别名一、别名二`；需要补充说明时追加 `；备注：...`。
 - 术语稳定时立即回写。工作单元完成、门禁批准或阶段转换前仍须执行 context reconciliation。

package/template/.agents/skills/grill-with-docs/SKILL.md

@@ -11,7 +11,7 @@ Call the Skill tool with `grilling`, then call it separately with `domain-modeli
 1. Read `yss-project.yaml` and the root glossary before the first round, then run `scripts/verify-context-contract --root . --json`. Missing or lowercase root files, nested `CONTEXT.md`, `CONTEXT-MAP.md`, unsupported schema, absolute/cross-repository references, and Markdown pseudo-anchors are `blocked` or `migration-required`.
 2. Separate discoverable facts from user decisions; investigate facts instead of asking the user.
 3. Ask the entire current decision frontier, with a recommendation for every question, then wait.
-4. Keep candidate or disputed terms in the Discovery decision frontier. Only after confirmation, use `domain-modeling` to record true stable glossary entries in the repository root's single, case-sensitive `CONTEXT.md`; business rows use the five-column format and `<ContextId>/<EnglishIdentifier>` identity. Non-`Global` Context IDs must come from the approved business responsibility areas in the business-boundary asset.
+4. Keep candidate or disputed terms in the Plan decision frontier. Only after confirmation, use `domain-modeling` to record true stable glossary entries in the repository root's single, case-sensitive `CONTEXT.md`; business rows use the five-column format and `<ContextId>/<EnglishIdentifier>` identity. Non-`Global` Context IDs must come from the approved business responsibility areas in the business-boundary asset.
 5. Create an ADR only when the decision is hard to reverse, surprising without context, and a real trade-off.
 6. Persist factual research/validation records in the repository's existing review or research convention.
 7. For `project-instance`, before requesting approval or returning a next work unit, generate and validate `context_reconciliation` with a readable ref, `document_digest`, `referenced_terms_digest`, and `term_refs`. Unresolved candidates, scope conflicts, aliases, or digest drift are `blocked`; reconciliation does not create another gate. For `template-source`, do not add fictional business terms and return a reasoned `not-applicable` after validating the template contract.

package/template/.agents/skills/setup-matt-pocock-skills/issue-tracker-local.md

@@ -31,7 +31,7 @@ When `yss-product-lifecycle` is active, the same `docs/.scratch/<feature-slug>/`
 ```text
 docs/.scratch/<feature-slug>/
 ├── map.md
-├── discovery/
+├── plan/
 ├── spec.md
 ├── spec-delta/
 ├── parent-ticket.md

package/template/.agents/skills/yss-ddd-scaffold-generator/scripts/run_scaffold_verification.mjs

@@ -3,7 +3,7 @@
 import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import process from "node:process";
-import { spawn } from "node:child_process";
+import { runCommand } from "../../../../scripts/lib/command-runner.mjs";
 import { assertArchitectureAgreement } from "../../../../scripts/lib/backend-architecture.mjs";
 import { assertLocalDatabaseProfile, scaffoldArchitectureIdentity } from "../../../../scripts/lib/scaffold-local-database.mjs";
 
@@ -37,7 +37,7 @@ function classifyFailure(phase, outcome) {
   if (phase === "package") return "packaging";
   return "maven-execution";
 }
-function parseArgs(argv) { const result = {}; for (let index = 0; index < argv.length; index += 1) { let token = argv[index]; if (token === "--help" || token === "-h") { result.help = true; continue; } const equals = token.indexOf("="); let value; if (equals !== -1) { value = token.slice(equals + 1); token = token.slice(0, equals); } if (!["--project-root", "--evidence-dir"].includes(token)) throw new Error(`不支持的参数: ${token}`); if (value === undefined) value = argv[++index]; if (!value || value.startsWith("--")) throw new Error(`参数 ${token} 缺少值`); result[token === "--project-root" ? "projectRoot" : "evidenceDir"] = path.resolve(value); } if (result.help) return result; if (!result.projectRoot || !result.evidenceDir) throw new Error("必须提供 --project-root 和 --evidence-dir"); return result; }
+function parseArgs(argv) { const result = {}; for (let index = 0; index < argv.length; index += 1) { let token = argv[index]; if (token === "--help" || token === "-h") { result.help = true; continue; } const equals = token.indexOf("="); let value; if (equals !== -1) { value = token.slice(equals + 1); token = token.slice(0, equals); } if (!["--project-root", "--evidence-dir", "--timeout-ms"].includes(token)) throw new Error(`不支持的参数: ${token}`); if (value === undefined) value = argv[++index]; if (!value || value.startsWith("--")) throw new Error(`参数 ${token} 缺少值`); if (token === "--timeout-ms") result.timeoutMs = Number(value); else result[token === "--project-root" ? "projectRoot" : "evidenceDir"] = path.resolve(value); } if (result.help) return result; if (!result.projectRoot || !result.evidenceDir) throw new Error("必须提供 --project-root 和 --evidence-dir"); return result; }
 function validateManifest(manifest) {
   if (![2, 3, 4].includes(manifest.schema_version)) throw new Error(`unsupported: scaffold Manifest schema_version=${manifest.schema_version}；只读兼容 v2，并验证当前 v3/v4`);
   const required = ["schema_version", "contract_id", "contract_version", "scaffold_request_id", "contract_digest", "profiles", "ownership", "readiness", "generation_policy", "completion_level", "approval_ref", "approver", "lifecycle_approval_ref", "compiler_draft_ref", "persisted_ref", "contract_file_ref", "current_version", "allowed_write_paths", "expected_evidence_files", "verification_commands", "generation_mode"];
@@ -57,8 +57,7 @@ function validateManifest(manifest) {
   if (manifest.current_version !== manifest.contract_version) throw new Error("脚手架生成元数据清单不是当前合同版本");
   if (JSON.stringify(manifest.verification_commands) !== JSON.stringify(COMMANDS)) throw new Error("脚手架生成元数据清单验证命令不符合固定合同");
 }
-function execute(wrapper, phase, cwd, environment) { return new Promise((resolve) => { const child = spawn(wrapper, [phase], { cwd, env: environment, stdio: ["ignore", "pipe", "pipe"] }); let stdout = "", stderr = ""; child.stdout.on("data", (chunk) => { stdout += chunk; }); child.stderr.on("data", (chunk) => { stderr += chunk; }); child.on("error", (error) => resolve({ exitCode: 127, stdout: "", stderr: String(error) })); child.on("close", (code) => resolve({ exitCode: code ?? 1, stdout, stderr })); }); }
-export async function run(projectRoot, evidenceDir, environment = process.env) {
+export async function run(projectRoot, evidenceDir, environment = process.env, { timeoutMs = 0, signal } = {}) {
   const wrapper = path.join(projectRoot, "mvnw"), manifestPath = path.join(projectRoot, ".yss", "scaffold-generation.json");
   if (!await isFile(wrapper)) throw new Error(`项目根目录缺少 Maven wrapper: ${wrapper}`);
   if (!await isFile(manifestPath)) throw new Error(`项目根目录缺少脚手架生成元数据清单: ${manifestPath}`);
@@ -91,7 +90,8 @@ export async function run(projectRoot, evidenceDir, environment = process.env) {
     const stderrPath = path.join(evidenceDir, `mvnw-${phase}.stderr.log`);
     const startedAt = isoNow();
     const started = process.hrtime.bigint();
-    const outcome = await execute(wrapper, phase, projectRoot, environment);
+    const execution = await runCommand(wrapper, [phase], { cwd: projectRoot, env: environment, timeoutMs, signal, stdoutFile: stdoutPath, stderrFile: stderrPath, secrets: [environment.MAVEN_REPO_USERNAME, environment.MAVEN_REPO_PASSWORD], progress: true });
+    const outcome = { ...execution, exitCode: execution.status };
     const durationMs = Number(process.hrtime.bigint() - started) / 1e6;
     await writeText(stdoutPath, redactSecrets(outcome.stdout, environment));
     await writeText(stderrPath, redactSecrets(outcome.stderr, environment));
@@ -99,7 +99,7 @@ export async function run(projectRoot, evidenceDir, environment = process.env) {
       command: `./mvnw ${phase}`,
       phase,
       exit_code: outcome.exitCode,
-      failure_category: classifyFailure(phase, outcome),
+      failure_category: outcome.termination || classifyFailure(phase, outcome),
       duration_ms: Number(durationMs.toFixed(3)),
       started_at: startedAt,
       executed_at: isoNow(),
@@ -120,5 +120,5 @@ export async function run(projectRoot, evidenceDir, environment = process.env) {
     commands
   };
 }
-async function main() { let args; try { args = parseArgs(process.argv.slice(2)); if (args.help) { console.log("运行 YSS 脚手架真实验证命令\n用法: node scripts/run_scaffold_verification.mjs --project-root <dir> --evidence-dir <dir>"); return 0; } const reportPath = path.join(args.evidenceDir, "scaffold-verification.json"); try { const report = await run(args.projectRoot, args.evidenceDir); await writeText(reportPath, `${JSON.stringify(report, null, 2)}\n`); console.log(`${report.status}: ${reportPath}`); return report.status === "passed" ? 0 : 1; } catch (error) { const report = { verification_mode: "controlled-generation", project_root: args.projectRoot, generated_at: isoNow(), status: "failed", failure_category: "verification-preflight", error: error.message, commands: [] }; await writeText(reportPath, `${JSON.stringify(report, null, 2)}\n`); process.stderr.write(`❌ 脚手架验证无法执行: ${error.message}\n`); return 1; } } catch (error) { process.stderr.write(`❌ 脚手架验证无法执行: ${error.message}\n`); return 1; } }
+async function main() { let args; try { args = parseArgs(process.argv.slice(2)); if (args.help) { console.log("运行 YSS 脚手架真实验证命令\n用法: node scripts/run_scaffold_verification.mjs --project-root <dir> --evidence-dir <dir>"); return 0; } const reportPath = path.join(args.evidenceDir, "scaffold-verification.json"); try { const report = await run(args.projectRoot, args.evidenceDir, process.env, { timeoutMs: args.timeoutMs ?? 0 }); await writeText(reportPath, `${JSON.stringify(report, null, 2)}\n`); console.log(`${report.status}: ${reportPath}`); return report.status === "passed" ? 0 : 1; } catch (error) { const report = { verification_mode: "controlled-generation", project_root: args.projectRoot, generated_at: isoNow(), status: "failed", failure_category: "verification-preflight", error: error.message, commands: [] }; await writeText(reportPath, `${JSON.stringify(report, null, 2)}\n`); process.stderr.write(`❌ 脚手架验证无法执行: ${error.message}\n`); return 1; } } catch (error) { process.stderr.write(`❌ 脚手架验证无法执行: ${error.message}\n`); return 1; } }
 if (process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href) process.exitCode = await main();

package/template/.agents/skills/yss-frontend-scaffold-generator/SKILL.md

@@ -36,7 +36,7 @@ branch: template
 1. 确认当前任务已经通过 Harness 入口分诊、逐项目脚手架决定已由真实用户确认，且 schema v4 合同已由生命周期批准、持久化并保持当前。
 2. 确认目标是外部实现仓库；只有用户明确选择时才输出到 Harness 仓库的 `apps/frontend/<project>/`。`apps/frontend/` 只能作为项目容器，`app/frontend/`、`app/backend/` 及其子路径禁止作为输出位置。`git-submodule` 只能在已初始化且附加分支的子仓工作树生成；空 gitlink、detached HEAD、`--force` 覆盖挂载点不得当成普通目录。
 3. 只读检查模板分支和合同锁定的 40 位 commit 是否可访问；生成时使用精确 commit，不跟随浮动分支。
-4. 使用 `scripts/generate_and_verify_scaffold.mjs` 从已核验 checkout 复制工作树，排除模板 `.git`；目标必须不存在或为空。不得默认写入 Harness、不得 `--force`。仅合同 `init_git=true` 时初始化目标 Git。
+4. 使用 `scripts/generate_and_verify_scaffold.mjs` 从已核验 checkout 的批准 commit 导出模板，排除模板 `.git` 及未提交的工作树内容；目标必须不存在或为空。不得默认写入 Harness、不得 `--force`。仅合同 `init_git=true` 时初始化目标 Git。
 5. 替换应用名、微应用名、路由、`micro-config.json`、环境变量和 README 中的模板占位。
 6. 有 API 影响时核验 OpenAPI Freeze 记录和 JSON 派生记录，将摘要一致的 JSON 原样物化到 `<frontend>/openapi/openapi.json`；`openapi_impact=not-applicable` 时必须有原因并禁止生成 API client。
 7. 保持模板既有的前端代码生成配置不变；本 Harness 只将 SHA-256 一致的 JSON 原样交给既有前端代码生成流程，不修改该配置、不在此仓库执行生成，也不设置生成 CI 门禁。目标前端项目在需要时手动运行其既有命令。

package/template/.agents/skills/yss-frontend-scaffold-generator/scripts/generate_scaffold.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import { createHash } from "node:crypto";
-import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import path from "node:path";
+import { tmpdir } from "node:os";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { validateJsonSchema } from "../../../../scripts/lib/json-schema.mjs";
@@ -22,7 +23,7 @@ function git(cwd, ...args) {
 function walk(root) {
   return readdirSync(root, { withFileTypes: true }).flatMap((entry) => {
     const item = path.join(root, entry.name);
-    return entry.isDirectory() ? walk(item) : entry.isFile() ? [item] : [];
+    return entry.isDirectory() ? walk(item) : entry.isFile() || entry.isSymbolicLink() ? [item] : [];
   });
 }
 function validate(contract, outputDir) {
@@ -47,7 +48,15 @@ export function generate({ contractFile, templateCheckout, outputDir }) {
   if (git(templateCheckout, "config", "--get", "remote.origin.url") !== contract.frontend.template.repository) fail("template repository differs from approved source");
   if (existsSync(outputDir) && readdirSync(outputDir).length > 0) fail("target directory must not exist or must be empty");
   mkdirSync(outputDir, { recursive: true });
-  cpSync(templateCheckout, outputDir, { recursive: true, filter: (source) => path.basename(source) !== ".git" });
+  const scratch = mkdtempSync(path.join(tmpdir(), "yss-frontend-source-"));
+  try {
+    // Read the approved Git tree, never dependency caches or edits in the checkout.
+    const archive = spawnSync("git", ["archive", contract.frontend.template.commit], { cwd: templateCheckout, maxBuffer: 256 * 1024 * 1024 });
+    if (archive.error || archive.status !== 0) fail(archive.error?.message || String(archive.stderr));
+    const unpack = spawnSync("tar", ["-xf", "-", "-C", scratch], { input: archive.stdout });
+    if (unpack.error || unpack.status !== 0) fail(unpack.error?.message || String(unpack.stderr));
+    cpSync(scratch, outputDir, { recursive: true, verbatimSymlinks: true });
+  } finally { rmSync(scratch, { recursive: true, force: true }); }
 
   const replacements = {
     "__APP_NAME__": contract.frontend.app_name,
@@ -55,10 +64,14 @@ export function generate({ contractFile, templateCheckout, outputDir }) {
     "__BASE_ROUTE__": contract.frontend.base_route,
     ...(contract.frontend.replacements || {}),
   };
-  for (const file of walk(outputDir)) {
-    if (statSync(file).size > 2_000_000) continue;
-    let text;
-    try { text = readFileSync(file, "utf8"); } catch { continue; }
+  const generatedFiles = walk(outputDir).map(file => path.relative(outputDir, file));
+  for (const ref of generatedFiles) {
+    const file = path.join(outputDir, ref);
+    const info = lstatSync(file);
+    if (info.isSymbolicLink() || info.size > 2_000_000) continue;
+    const bytes = readFileSync(file);
+    if (bytes.includes(0) || !Buffer.from(bytes.toString("utf8")).equals(bytes)) continue;
+    const text = bytes.toString("utf8");
     const replaced = Object.entries(replacements).reduce((value, [from, to]) => value.split(from).join(to), text);
     if (replaced !== text) writeFileSync(file, replaced);
   }
@@ -67,9 +80,10 @@ export function generate({ contractFile, templateCheckout, outputDir }) {
     if (sha256(bytes) !== contract.frontend.openapi_json_digest) fail("OpenAPI JSON digest mismatch");
     mkdirSync(path.join(outputDir, "openapi"), { recursive: true });
     writeFileSync(path.join(outputDir, "openapi", "openapi.json"), bytes);
+    if (!generatedFiles.includes("openapi/openapi.json")) generatedFiles.push("openapi/openapi.json");
   }
   if (contract.init_git === true) git(outputDir, "init");
-  const generatedFiles = walk(outputDir).map((file) => path.relative(outputDir, file)).filter((file) => file !== ".yss/scaffold-generation.json").sort();
+  generatedFiles.sort();
   const manifest = {
     schema_version: 4,
     kind: "frontend-scaffold",

package/template/.agents/skills/yss-frontend-scaffold-generator/scripts/run_scaffold_verification.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
-import { spawnSync } from "node:child_process";
+import { runCommandSync } from "../../../../scripts/lib/command-runner.mjs";
 
 const ALLOWED = new Map([
   ["pnpm install --frozen-lockfile", ["install", "--frozen-lockfile"]],
@@ -10,7 +10,7 @@ const ALLOWED = new Map([
   ["pnpm build", ["build"]],
 ]);
 function argsOf(argv) { const args = {}; for (let i = 0; i < argv.length; i += 2) args[argv[i].replace(/^--/, "")] = argv[i + 1]; return args; }
-export function verify(projectRoot, evidenceDir) {
+export function verify(projectRoot, evidenceDir, { timeoutMs = 0 } = {}) {
   projectRoot = path.resolve(projectRoot); evidenceDir = path.resolve(evidenceDir);
   const manifestPath = path.join(projectRoot, ".yss", "scaffold-generation.json");
   const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
@@ -23,10 +23,9 @@ export function verify(projectRoot, evidenceDir) {
     const argv = ALLOWED.get(command);
     if (!argv) throw new TypeError(`unsupported verification command: ${command}`);
     const started = Date.now();
-    const result = spawnSync("pnpm", argv, { cwd: projectRoot, encoding: "utf8" });
     const stdoutRef = path.join(evidenceDir, `${index + 1}-stdout.log`), stderrRef = path.join(evidenceDir, `${index + 1}-stderr.log`);
-    writeFileSync(stdoutRef, result.stdout || ""); writeFileSync(stderrRef, result.stderr || "");
-    return { command, exit_code: result.status ?? 1, duration_ms: Date.now() - started, stdout_ref: stdoutRef, stderr_ref: stderrRef, executed_at: new Date().toISOString() };
+    const result = runCommandSync("pnpm", argv, { cwd: projectRoot, timeoutMs, stdoutFile: stdoutRef, stderrFile: stderrRef, progress: true });
+    return { command, exit_code: result.status ?? 1, duration_ms: Date.now() - started, ...(result.termination ? { termination: result.termination } : {}), stdout_ref: stdoutRef, stderr_ref: stderrRef, executed_at: new Date().toISOString() };
   });
   const passed = results.every((item) => item.exit_code === 0);
   const report = { schema_version: 1, kind: "frontend-scaffold-verification", status: passed ? "passed" : "failed", project_root: projectRoot, scaffold_manifest_ref: manifestPath, commands: results };
@@ -36,6 +35,6 @@ export function verify(projectRoot, evidenceDir) {
   return report;
 }
 if (import.meta.url === `file://${process.argv[1]}`) {
-  try { const args = argsOf(process.argv.slice(2)); const report = verify(args["project-root"], args["evidence-dir"]); process.stdout.write(`${report.status}\n`); if (report.status !== "passed") process.exitCode = 1; }
+  try { const args = argsOf(process.argv.slice(2)); const report = verify(args["project-root"], args["evidence-dir"], { timeoutMs: Number(args["timeout-ms"] || 0) }); process.stdout.write(`${report.status}\n`); if (report.status !== "passed") process.exitCode = 1; }
   catch (error) { process.stderr.write(`${error.message}\n`); process.exitCode = 1; }
 }

package/template/.agents/skills/yss-frontend-scaffold-generator/scripts/scaffold-generator.test.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import assert from "node:assert/strict";
-import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readlinkSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
@@ -12,10 +12,19 @@ mkdirSync(template); mkdirSync(bin);
 writeFileSync(path.join(template, "package.json"), JSON.stringify({ name: "__APP_NAME__", scripts: { lint: "noop", "type-check": "noop", build: "noop" } }));
 writeFileSync(path.join(template, "pnpm-lock.yaml"), "lockfileVersion: '9.0'\n");
 writeFileSync(path.join(template, "micro-config.json"), JSON.stringify({ name: "__MICROAPP_NAME__", route: "__BASE_ROUTE__" }));
+mkdirSync(path.join(template, "assets"));
+writeFileSync(path.join(template, "assets/binary.bin"), Buffer.from([0, 255, 95, 95, 65, 80, 80, 95, 78, 65, 77, 69, 95, 95]));
+writeFileSync(path.join(template, "assets/large.txt"), "__APP_NAME__".repeat(200_000));
+writeFileSync(path.join(template, "assets/run.sh"), "#!/bin/sh\necho __APP_NAME__\n");
+chmodSync(path.join(template, "assets/run.sh"), 0o755);
+symlinkSync("run.sh", path.join(template, "assets/current"));
 for (const args of [["init"], ["config", "user.email", "test@example.com"], ["config", "user.name", "test"], ["remote", "add", "origin", template], ["add", "."], ["commit", "-m", "fixture"]]) {
   const result = spawnSync("git", args, { cwd: template, encoding: "utf8" }); assert.equal(result.status, 0, result.stderr);
 }
 const commit = spawnSync("git", ["rev-parse", "HEAD"], { cwd: template, encoding: "utf8" }).stdout.trim();
+mkdirSync(path.join(template, "node_modules"));
+writeFileSync(path.join(template, "node_modules/cache.txt"), "not approved");
+writeFileSync(path.join(template, "micro-config.json"), "uncommitted edit");
 const contract = {
   schema_version: 4, kind: "project-scaffold-contract", contract_id: "frontend.demo.v1", contract_version: "1", status: "approved", persisted_ref: "docs/.scratch/demo/scaffold-contract.json", current_version: true,
   delivery_role: "frontend", scaffold_kind: "frontend-yss-vue3", generator_skill: "yss-frontend-scaffold-generator", implementation_repository: output, target_output_dir: output, repository_scope: "external-repository", init_git: false,
@@ -31,6 +40,15 @@ assert.equal(existsSync(path.join(output, ".git")), false);
 assert.equal(JSON.parse(readFileSync(path.join(output, "package.json"))).name, "demo-app");
 assert.equal(JSON.parse(readFileSync(path.join(output, ".yss", "scaffold-generation.json"))).completion_level, "empty-scaffold-verified");
 assert.equal(JSON.parse(readFileSync(path.join(evidence, "scaffold-verification.json"))).commands.length, 4);
+assert.equal(existsSync(path.join(output, "node_modules")), false);
+assert.equal(JSON.parse(readFileSync(path.join(output, "micro-config.json"))).name, "demo");
+assert.deepEqual(readFileSync(path.join(output, "assets/binary.bin")), readFileSync(path.join(template, "assets/binary.bin")));
+assert.deepEqual(readFileSync(path.join(output, "assets/large.txt")), readFileSync(path.join(template, "assets/large.txt")));
+assert.equal(readlinkSync(path.join(output, "assets/current")), "run.sh");
+assert.equal(statSync(path.join(output, "assets/run.sh")).mode & 0o777, 0o755);
+assert.match(readFileSync(path.join(output, "assets/current"), "utf8"), /echo demo-app/);
+const generated = JSON.parse(readFileSync(path.join(output, ".yss/scaffold-generation.json"))).generated_files;
+assert.deepEqual(generated, ["assets/binary.bin", "assets/current", "assets/large.txt", "assets/run.sh", "micro-config.json", "package.json", "pnpm-lock.yaml"]);
 const second = spawnSync(process.execPath, [runner, "--contract-file", contractFile, "--template-checkout", template, "--output-dir", output, "--evidence-dir", evidence], { encoding: "utf8", env: { ...process.env, PATH: `${bin}:${process.env.PATH}` } });
 assert.notEqual(second.status, 0);
 assert.match(second.stderr, /must not exist or must be empty/);

package/template/.agents/skills/yss-product-lifecycle/SKILL.md

@@ -22,14 +22,13 @@ description: 编排 YSS 产品或模块从机会调研到 Spec、原型、技术
 使用 `scripts/query-lifecycle-context` 获取确定性 JSON 投影，不要为普通路由整份读取编排合同：
 
 ```bash
-scripts/query-lifecycle-context --mode route
-scripts/query-lifecycle-context --stage stage.discovery
-scripts/query-lifecycle-context --work-unit work-unit.discovery-requirements
-scripts/query-lifecycle-context --work-unit work-unit.slice-implementation --include ready_for_agent --include ticket_formalization
+scripts/query-lifecycle-context --mode route --stage stage.plan --work-unit work-unit.plan-requirements --include execution_efficiency
 ```
 
 `--include` 接受编排合同的顶层键；非法模式、ID 或合同键必须失败。查询结果只是带摘要的权威事实投影，不成为新的事实源。解释性细节按需读取 `references/orchestration.md`、`references/state-model.md`、`references/artifact-dependencies.md`、`references/user-decisions.md` 和 `references/matt-yss-adapter.md`，达到最小充分证据后停止扩展上下文。
 
+按 `execution_efficiency` 合并查询、复用未变资料并验证当前资产；产品流转不重跑模板套件。词汇对账、恢复核验及门禁不变，执行细节见 `references/orchestration.md`。
+
 ## 入口与模式
 
 1. 严格解析 `yss-project.yaml`，不得按目录、Git remote 或占位符猜仓库身份。
@@ -37,6 +36,8 @@ scripts/query-lifecycle-context --work-unit work-unit.slice-implementation --inc
 3. 模式为 `route`、`orchestrate`、`resume`、`audit`；未明确时使用只读 `route`。具体写入边界从编排合同的 `modes` 子树读取。
 4. `project-instance` 按生命周期注册表推进；`template-source` 只走模板维护流程。
 
+Plan 入口读取 `docs/plan/README.md` 和 `docs/process/plan-migration.md`，按注册表的退出条件核查战略输入。关键未决项阻断进入 Spec；非关键细节须有责任人、解决时点和下游接收方。只使用 Plan 标识；旧阶段不提供兼容解析，历史批准不自动成为 Plan 批准。
+
 ## 不可越过的边界
 
 ### 仓库身份
@@ -74,6 +75,8 @@ scripts/query-lifecycle-context --work-unit work-unit.slice-implementation --inc
 
 先问清用户与结果、通常流程、责任交接、规则与例外、可独立交付的最小范围、证明结果正确的例子和证据。每轮可生成一页“业务方案总览”，只引用权威资产并显示状态、未决问题、责任人和下一步；不复制正文、不成为新的事实源、不新增门禁。
 
+Plan → Spec（含正式草稿、恢复与显式 `to-spec`）写入前，按 `docs/plan/entry-review.md` 持久化审阅包并运行 `node scripts/verify-plan-spec-entry <state.yaml>`。检查默认 pending，缺项、过期或无真实回复即阻断；独立调研可继续。
+
 ## 结果与暂停
 
 输出至少包含：模式、仓库身份、当前阶段和工作单元、影响面、资产与门禁状态、证据、新鲜度、Ticket/垂直切片/合同状态、`ready-for-agent` 结论、阻塞项、本轮动作、下一工作单元、暂停或继续理由、Ticket 同步和 Git checkpoint 判断。

package/template/.agents/skills/yss-product-lifecycle/references/artifact-dependencies.md

@@ -3,7 +3,7 @@
 ## 基础依赖
 
 ```text
-Discovery → Spec → Product Overview / Functional Architecture
+Plan → Spec → Product Overview / Functional Architecture
 Root CONTEXT.md + current work-unit changes → Context Reconciliation → approval / next work unit
 Spec + Product Overview → Product Design / Requirement Freeze
 Spec + Product Overview → API Impact / OpenAPI Draft

package/template/.agents/skills/yss-product-lifecycle/references/matt-yss-adapter.md

@@ -10,7 +10,7 @@ Matt skills 决定如何工作；YSS 生命周期决定是否允许推进；YSS
 - **直接调用生命周期管理的 Matt user-invoked skill**（`setup-matt-pocock-skills`、`grill-with-docs`、`to-spec`、`to-tickets`、`implement`）时，用户仍是正式资产的创建者；生命周期先校验前置条件，再接受结果并重新计算阶段、门禁和状态。其他 user-invoked skill 同样不得由生命周期自动调用；只有在其专属适配合同存在时才进入 YSS 流程。
 - **直接调用 `yss-product-lifecycle`** 时，不机械嵌套调用任何 Matt user-invoked skill；编排器直接使用原生工作单元和允许的 model-invoked 原语。Matt user-invoked skill 保持显式兼容入口，生命周期负责准备、校验并验收其结果。
 - `template-source` 只允许进入模板维护流程。命中 `to-spec`、`to-tickets`、`implement`、Release 或 Retrospective 时返回 `blocked`，原因是 `template-source-product-artifact-forbidden`；`setup-matt-pocock-skills` 不得为具体产品生成 Spec、prototype、OpenAPI 或垂直切片 Ticket。
-- `project-instance` 才允许进入产品 Discovery → Spec → 设计 → 契约 → Ticket → 实现 → Release / Retrospective 链路。
+- `project-instance` 才允许进入产品 Plan → Spec → 设计 → 契约 → Ticket → 实现 → Release / Retrospective 链路。
 
 | 情形 | Matt flow | 生命周期验收 |
 |---|---|---|
@@ -66,7 +66,7 @@ blocking_signals: []
 
 | Matt flow | 进入条件 | 生命周期结果 |
 |---|---|---|
-| `to-spec`（用户显式） | Discovery work unit 或 `grill-with-docs` 已满足退出条件，且不存在未回流 runnable blocker；用户问题、MVP/非目标、成功标准、测试 seam 和术语审查均有证据 | 生命周期只准备/验收；Spec 初稿为 `ready-for-human`，不等于批准 |
+| `to-spec`（用户显式） | Plan work unit 或 `grill-with-docs` 已满足退出条件，且不存在未回流 runnable blocker；用户问题、MVP/非目标、成功标准、测试 seam 和术语审查均有证据 | 生命周期只准备/验收；Spec 初稿为 `ready-for-human`，不等于批准 |
 | `to-tickets`（用户显式） | OpenAPI Freeze 或 `no-api-impact` 记录、必要门禁、垂直切片范围和阻塞边均已明确 | 生命周期只准备/验收；只能生成垂直切片 Ticket，初始统一为 `ready-for-human`；必须留下 `ticket_decomposition_result_ref` 和 `vertical_slice_ticket_ref` |
 | `implement`（用户显式） | `ready-for-agent` 公式、Ticket 正式化结果、垂直切片引用/类型/状态、Contract 已批准/持久化/版本一致、Build Architecture Checklist、实现仓库/分支/CI/验证命令/回滚点，以及后端 Contract（适用时）均满足 | 生命周期只准备/验收；单会话实现同样适用，不得绕过门禁；父 Ticket、`ready-for-human` 切片或跳过 Ticket 正式化的 `next_route` 必须 `blocked` |
 
@@ -100,7 +100,7 @@ Matt `implement` 的通用提交指令不构成 YSS Git 授权。只有用户明
 
 | Matt 产物 | Local 载体 |
 |---|---|
-| Discovery | `docs/.scratch/<feature>/discovery/` |
+| Plan | `docs/.scratch/<feature>/plan/` |
 | Spec | `docs/.scratch/<feature>/spec.md` |
 | Spec Delta | `docs/.scratch/<feature>/spec-delta/` |
 | 功能父 Ticket | `docs/.scratch/<feature>/parent-ticket.md` |