create-yss-spec 3.3.0 → 3.3.1

package/template/docs/process/lifecycle-registry-baseline.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "registry_id": "yss.lifecycle",
-  "semantic_sha256": "68c053060bb837fe4bc2b40d7a6ffcea1a53fc6b5e6b929eb0858824c657a15d",
+  "semantic_sha256": "96fcbcb858eed45ba228d87c75804f28ccb464b1963c0d23be348ade094bac01",
   "published_ids": [
     "artifact.architecture-review",
     "artifact.data-architecture",
@@ -19,6 +19,7 @@
     "artifact.openapi-draft",
     "artifact.openapi-freeze-record",
     "artifact.parent-ticket",
+    "artifact.plan-record",
     "artifact.product-overview",
     "artifact.project-scaffold-contract",
     "artifact.prototype-confirmation",
@@ -76,6 +77,7 @@
     "gate.user-confirmation",
     "stage.discovery",
     "stage.entry-triage",
+    "stage.plan",
     "stage.product-design",
     "stage.spec-architecture",
     "stage.system-data-engineering",
@@ -94,6 +96,8 @@
     "work-unit.independent-review",
     "work-unit.intensity-aware-review",
     "work-unit.intensity-aware-verification",
+    "work-unit.plan-opportunity",
+    "work-unit.plan-requirements",
     "work-unit.prototype-design",
     "work-unit.release-and-retrospective",
     "work-unit.release-and-rollback",

package/template/docs/process/lifecycle-registry.yaml

@@ -8,17 +8,22 @@ id_policy:
   pattern: '^(stage|gate|artifact|work-unit|evidence)\.[a-z0-9][a-z0-9-]*$'
   published_ids_immutable: true
   baseline: docs/process/lifecycle-registry-baseline.json
-  deprecated_ids: [artifact.high-fidelity-html-prototype, work-unit.fresh-verification, work-unit.independent-review]
+  deprecated_ids: [artifact.high-fidelity-html-prototype, work-unit.fresh-verification, work-unit.independent-review, stage.discovery, artifact.discovery-record, work-unit.discovery-opportunity, work-unit.discovery-requirements]
 
 stages:
   - id: stage.entry-triage
     name: 入口分诊
     goal: 确认仓库身份、问题范围和影响面。
     exit_criteria: yss-project.yaml 合法，影响面和最近可信阶段可解释。
-  - id: stage.discovery
-    name: Discovery
-    goal: 澄清问题、用户、约束和机会。
-    exit_criteria: 问题边界、关键假设和待确认项已记录。
+  - id: stage.plan
+    name: Plan（战略规划）
+    goal: 确认目标、业务边界、关键规则、MVP / 非目标、优先级和交接责任，为 Spec 提供战略输入；按影响面探索并复用仍有效的结论。
+    exit_criteria: 用户确认规划结论，命中的战略与阶段决策门禁通过；影响业务边界、关键规则或 MVP 的问题已解决，其他未决项有责任人和解决时点；下游可进入 Spec，不代表可实现。
+    spec_entry:
+      required_checks: [goals, scope_and_priority, boundaries_and_rules, open_questions, handoff, context_reconciliation, grill_exit]
+      gate_impacts:
+        gate.domain-strategy-approved: domain_strategy
+        gate.stage-decision-package-approved: stage_decision
   - id: stage.spec-architecture
     name: Spec / 功能架构
     goal: 固化解决方案和功能边界。
@@ -130,15 +135,15 @@ gates:
     evidence: [evidence.repository-identity-check]
   - id: gate.domain-strategy-approved
     name: DDD 战略设计批准
-    stage: stage.discovery
+    stage: stage.plan
     trigger: 存在 DDD 战略设计影响或需要确定领域边界、统一语言和核心规则。
     public_name: 业务边界与规则确认
     public_trigger: 需要确定业务板块、业务责任区、统一业务词汇、协作关系或关键规则。
     evidence: [evidence.domain-strategy-review, evidence.approval-record]
   - id: gate.stage-decision-package-approved
     name: 阶段决策包批准
-    stage: stage.discovery
-    trigger: Discovery 到 Spec 入口需要稳定的阶段决策合同。
+    stage: stage.plan
+    trigger: Plan 到 Spec 入口需要稳定的阶段决策合同。
     evidence: [evidence.stage-decision-package, evidence.approval-record]
     requires_gates: [gate.domain-strategy-approved]
   - id: gate.spec-baseline-approved
@@ -221,18 +226,18 @@ artifacts:
     trigger: 每次变更。
   - id: artifact.domain-strategy
     name: DDD 战略设计
-    stage: stage.discovery
+    stage: stage.plan
     trigger: 新产品/模块、跨上下文功能、统一语言冲突、服务边界或核心规则变化。
     public_name: 业务边界与规则设计
     public_trigger: 新产品/模块、跨责任区协作、业务词汇冲突、责任边界或关键规则变化。
   - id: artifact.stage-decision-package
     name: 阶段决策包
-    stage: stage.discovery
-    trigger: Discovery 到 Spec 入口需要结构化上游决策。
+    stage: stage.plan
+    trigger: Plan 到 Spec 入口需要结构化上游决策。
     public_name: 方案决策包
-  - id: artifact.discovery-record
-    name: Discovery 记录
-    stage: stage.discovery
+  - id: artifact.plan-record
+    name: Plan 记录
+    stage: stage.plan
     trigger: 新问题或边界不清。
   - id: artifact.spec
     name: Spec
@@ -384,13 +389,13 @@ work_units:
     input: 已审查 commit。
     output: release note、观察信号、回滚点。
     completion: 两仓库顺序和恢复动作明确。
-  - id: work-unit.discovery-opportunity
+  - id: work-unit.plan-opportunity
     name: 机会调研
     scope: project-instance
     input: 用户问题、市场/竞品事实需求和现有上下文。
-    output: Discovery 机会结论、证据、替代方案和关键假设。
+    output: Plan 机会结论、证据、替代方案和关键假设。
     completion: 机会继续/停止建议可审查；事实已 research 或记录为假设。
-  - id: work-unit.discovery-requirements
+  - id: work-unit.plan-requirements
     name: 需求分析
     scope: project-instance
     input: 机会结论、用户反馈和领域词汇。
@@ -408,16 +413,16 @@ work_units:
   - id: work-unit.stage-decision
     name: 阶段决策包综合
     scope: project-instance
-    input: Discovery、DDD 战略设计以及产品经理负责的商业约束输入。
+    input: Plan、DDD 战略设计以及产品经理负责的商业约束输入。
     output: 带版本、digest、证据和下游映射的阶段决策包。
     completion: 必填字段、引用、影响面和下游消费验证通过；批准门禁完成。
     public_name: 方案决策包综合
-    public_input: Discovery、业务边界与规则设计以及产品经理负责的商业约束输入。
+    public_input: Plan、业务边界与规则设计以及产品经理负责的商业约束输入。
     public_output: 带版本、digest、证据和下游映射的方案决策包。
   - id: work-unit.spec-synthesis
     name: Spec 综合
     scope: project-instance
-    input: 已确认的 Discovery 记录和测试 seam。
+    input: 已确认的 Plan 记录和测试 seam。
     output: Spec、产品总体设计和功能架构。
     completion: Spec 内容完整并进入 ready-for-human；下游推进仍需 gate.spec-baseline-approved。
   - id: work-unit.prototype-design

package/template/docs/process/plan-migration.md

@@ -0,0 +1,13 @@
+# Plan 阶段切换说明
+
+新流程仅使用 `stage.plan`、`artifact.plan-record`、`work-unit.plan-opportunity` 和 `work-unit.plan-requirements`。不提供 Discovery 阶段别名、旧标识解析或兼容入口；旧 ID 在注册表中仅作为弃用清单保留，以防重新分配，不可执行。
+
+新工作从 `docs/plan/templates/plan-template.md` 起草，工作目录为 `docs/.scratch/<feature>/plan/`。问题、机会和事实探索是 Plan 内按影响面执行的活动。
+
+历史冻结文档、批准记录和摘要保持原字节。旧状态不能直接恢复执行；如需继续，按当前 Plan 模板重新整理输入并核查当前退出条件，不把旧批准自动视为新流程批准。已有事实和结论可引用，但须记录当前版本、适用范围和复用理由。
+
+综合模板和战略设计模板共同采用 Plan。它为 Spec 提供战略输入；后续 Spec、页面原型、契约、Ticket 及交接边界仍由各自 profile 和生命周期注册表定义。Plan 不等同于实现合同中的 Context Plan。
+
+影响业务边界、关键规则或 MVP 的未决项必须在进入 Spec 前解决；其他细节须经用户确认延期，并具备不影响当前决定的依据、责任人、解决时点和接收方。既有 runnable blocker 不得降为普通延期项。
+
+Plan 是借鉴 AI-DLC 前置规划职责的本地名称，不宣称是 AWS 官方阶段名称或完整 Inception。

package/template/docs/process/schemas/digital-human-task-package.schema.json

@@ -6,6 +6,8 @@
   "additionalProperties": false,
   "required": ["schema_version", "task_id", "work_unit_id", "actor_id", "role_id", "runtime_id", "execution_state", "workflow_status", "skill_source", "contract", "inputs", "objective", "allowed_write_paths", "forbidden_actions", "expected_outputs", "expected_evidence_files", "verification_commands", "verification_results", "downstream_consumers", "convergence"],
   "properties": {
+    "plan_review_ref": { "type": "string", "minLength": 1 },
+    "plan_user_decision_ref": { "type": "string", "minLength": 1 },
     "schema_version": { "const": 1 },
     "frontend_delivery": {
       "type": "object", "additionalProperties": false, "required": ["acceptance_ref"],

package/template/docs/process/schemas/lifecycle-checkpoint.schema.json

@@ -6,6 +6,9 @@
   "additionalProperties": false,
   "required": ["schema_version", "repository_mode", "mode", "status", "stage", "artifacts", "gates", "context_reconciliation", "next_work_unit", "ticket_sync", "verification", "human_review", "git_checkpoint", "blockers", "rollback"],
   "properties": {
+    "plan_review_ref": { "type": "string", "minLength": 1 },
+    "plan_user_decision_ref": { "type": "string", "minLength": 1 },
+    "feature_id": { "type": "string", "minLength": 1 },
     "schema_version": { "const": 1 },
     "repository_mode": { "enum": ["template-source", "project-instance"] },
     "mode": { "enum": ["route", "orchestrate", "resume", "audit"] },

package/template/docs/process/schemas/lifecycle-registry.schema.json

@@ -27,7 +27,7 @@
   },
   "$defs": {
     "id": { "type": "string", "pattern": "^(stage|gate|artifact|work-unit|evidence)\\.[a-z0-9][a-z0-9-]*$" },
-    "stages": { "type": "array", "minItems": 1, "items": { "type": "object", "additionalProperties": false, "required": ["id", "name", "goal", "exit_criteria"], "properties": { "id": { "$ref": "#/$defs/id" }, "name": { "type": "string", "minLength": 1 }, "goal": { "type": "string", "minLength": 1 }, "exit_criteria": { "type": "string", "minLength": 1 }, "public_name": { "type": "string", "minLength": 1 }, "public_goal": { "type": "string", "minLength": 1 }, "public_exit_criteria": { "type": "string", "minLength": 1 } } } },
+    "stages": { "type": "array", "minItems": 1, "items": { "type": "object", "additionalProperties": false, "required": ["id", "name", "goal", "exit_criteria"], "properties": { "spec_entry": {"type":"object","required":["required_checks","gate_impacts"],"additionalProperties":false,"properties":{"required_checks":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","minLength":1}},"gate_impacts":{"type":"object","minProperties":1,"additionalProperties":{"type":"string","minLength":1}}}}, "id": { "$ref": "#/$defs/id" }, "name": { "type": "string", "minLength": 1 }, "goal": { "type": "string", "minLength": 1 }, "exit_criteria": { "type": "string", "minLength": 1 }, "public_name": { "type": "string", "minLength": 1 }, "public_goal": { "type": "string", "minLength": 1 }, "public_exit_criteria": { "type": "string", "minLength": 1 } } } },
     "objects": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["id", "name", "stage", "trigger"], "properties": { "id": { "$ref": "#/$defs/id" }, "name": { "type": "string", "minLength": 1 }, "stage": { "type": "string", "pattern": "^stage\\." }, "trigger": { "type": "string", "minLength": 1 }, "public_name": { "type": "string", "minLength": 1 }, "public_trigger": { "type": "string", "minLength": 1 }, "evidence": { "type": "array", "minItems": 1, "items": { "type": "string", "pattern": "^evidence\\." } }, "requires_gates": { "type": "array", "uniqueItems": true, "items": { "type": "string", "pattern": "^gate\\." } } } } },
     "workUnits": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["id", "name", "scope", "input", "output", "completion"], "properties": { "id": { "$ref": "#/$defs/id" }, "name": { "type": "string", "minLength": 1 }, "scope": { "enum": ["template-source", "project-instance"] }, "input": { "type": "string", "minLength": 1 }, "output": { "type": "string", "minLength": 1 }, "completion": { "type": "string", "minLength": 1 }, "public_name": { "type": "string", "minLength": 1 }, "public_input": { "type": "string", "minLength": 1 }, "public_output": { "type": "string", "minLength": 1 }, "public_completion": { "type": "string", "minLength": 1 } } } },
     "evidence": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["id", "name", "description"], "properties": { "id": { "$ref": "#/$defs/id" }, "name": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "public_name": { "type": "string", "minLength": 1 }, "public_description": { "type": "string", "minLength": 1 } } } }

package/template/docs/process/template-engineering-overview.md

@@ -22,7 +22,7 @@ YSS 模板工程是一套可版本化的研发治理系统。它用仓库身份
 | 身份 | 用途 | 允许的主要工作 | 边界 |
 |---|---|---|---|
 | `template-source` | 维护通用模板与治理规则 | 更新单一事实来源、同步技能投影、构建 CLI 快照、验证与审查 | 不生成具体产品的 Spec、原型、OpenAPI 或垂直切片 Ticket |
-| `project-instance` | 承载具体产品或模块的研发管理资产 | 执行 Discovery、Spec、设计、工程契约、Ticket、实现、验证和发布流程 | 不反向成为通用模板的权威来源 |
+| `project-instance` | 承载具体产品或模块的研发管理资产 | 执行 Plan、Spec、设计、工程契约、Ticket、实现、验证和发布流程 | 不反向成为通用模板的权威来源 |
 
 身份只由 `yss-project.yaml` 声明。目录结构、Git remote 和占位符都不能替代该清单。
 
@@ -32,7 +32,7 @@ YSS 模板工程是一套可版本化的研发治理系统。它用仓库身份
 
 | 产品线 | 模板源 | 实例化 CLI | 生命周期边界 |
 |---|---|---|---|
-| 全产品生命周期 | `yss-spec-project-template` | `create-yss-spec` | 从 Discovery 到发布与复盘 |
+| 全产品生命周期 | `yss-spec-project-template` | `create-yss-spec` | 从 Plan 到发布与复盘 |
 | DDD 战略设计交接 | `yss-harness-design-agent` | `create-yss-harness-design` | 从机会、需求和战略设计到 Strategic Design Handoff |
 | 开发落地 | `yss-harness-dev-agent` | `create-yss-harness-dev` | 从已批准 Spec 或战略设计交接包到 Tactical Design、Slice Contract、实现与验证 |
 

package/template/docs/process/template-verification-profiles.yaml

@@ -318,6 +318,7 @@ groups:
       - { run: "scripts/verify-context-contract-scenarios" }
       - { run: "node scripts/verify-business-language-scenarios" }
       - { run: "scripts/verify-context-reconciliation-scenarios" }
+      - { run: "node scripts/verify-script-performance-scenarios" }
       - { run: "scripts/verify-grill-with-docs-context-scenarios" }
       - { run: "scripts/verify-strategic-context-import-scenarios" }
       - { run: "scripts/verify-lifecycle-registry" }
@@ -330,6 +331,7 @@ groups:
       - { run: "scripts/verify-scaffold-architecture-decision-scenarios" }
       - { run: "scripts/verify-lifecycle-scenarios" }
       - { run: "scripts/verify-lifecycle-transition-scenarios" }
+      - { run: "node scripts/verify-plan-spec-entry-scenarios" }
       - { run: "scripts/verify-frontend-scaffold-generator-scenarios" }
   maintenance:
     commands:

package/template/docs/process/templates/context-reconciliation-template.yaml

@@ -1,7 +1,7 @@
 schema_version: 1
 repository_mode: project-instance
-stage: stage.discovery
-work_unit: work-unit.discovery-requirements
+stage: stage.plan
+work_unit: work-unit.plan-requirements
 status: reconciled
 context_snapshot:
   context_ref: CONTEXT.md

package/template/docs/process/templates/lifecycle-checkpoint-template.yaml

@@ -10,7 +10,7 @@ context_reconciliation:
   ref: null
   reason: 等待当前工作单元完成稳定术语回写与核对
   evidence_refs: []
-next_work_unit: work-unit.discovery-opportunity
+next_work_unit: work-unit.plan-opportunity
 phase_boundary:
   decision: continue
   reason: initial routing

package/template/docs/requirements/README.md

@@ -1,6 +1,6 @@
 # 需求定义 (Requirements) — 从想法到可执行定义
 
-> **Phase: Requirements | 输入: Discovery | 输出: Spec + Stories + 验收条件**
+> **Phase: Requirements | 输入: Plan | 输出: Spec + Stories + 验收条件**
 
 ---
 
@@ -79,7 +79,7 @@ delegate_task(
 ## AI-Human Loop
 
 ```
-Discovery报告 → AI生成Spec → PM审核
+Plan报告 → AI生成Spec → PM审核
 → AI补充边界 → PM确认 → AI拆解Stories
 → 团队估算 → AI标注风险 → TechLead确认 → 进入Architecture
 ```

package/template/docs/templates/local-parent-ticket-template.md

@@ -37,7 +37,7 @@ Status: ready-for-human
 
 ## 资产与证据
 
-- Discovery：`docs/.scratch/<feature>/discovery/`
+- Plan：`docs/.scratch/<feature>/plan/`
 - Spec Delta：`docs/.scratch/<feature>/spec-delta/`
 - Design：`docs/.scratch/<feature>/design/`
 - API：`docs/.scratch/<feature>/api/`

package/template/docs/templates/subagent-task-package-template.md

@@ -35,7 +35,7 @@ owner: ai
 
 | 输入 | 路径 / 链接 | 用途 |
 |---|---|---|
-| Spec / Discovery |  |  |
+| Spec / Plan |  |  |
 | Product / Interaction Design |  |  |
 | OpenAPI Draft / Freeze |  |  |
 | Architecture / ADR / CONTEXT |  |  |

package/template/docs/user-guide//347/224/250/346/210/267/346/211/213/345/206/214.md

@@ -67,7 +67,7 @@ init 只创建不存在或空目录；attach / sync 默认只预览，写入要
 
 ## 按路线推进
 
-综合模板按本仓生命周期从分诊、Discovery、Spec/功能架构、产品设计、工程契约、Ticket、切片推进到验证与发布。战略模板在业务交接停止；通用研发从批准上游接入；专职两端按交付合同接力。
+综合模板按本仓生命周期从分诊、Plan、Spec/功能架构、产品设计、工程契约、Ticket、切片推进到验证与发布。战略模板在业务交接停止；通用研发从批准上游接入；专职两端按交付合同接力。
 
 每一步都让 Agent 说明：消费了哪些当前输入、准备了什么、缺谁确认、怎样检查结果。具体阶段和门禁从本仓注册表读取，不把别的模板阶段编号复制进本仓。
 

package/template/scripts/cache-template-commit

@@ -3,9 +3,9 @@ import { parseArgs } from "node:util";
 import { acquireTemplateCommit } from "./lib/template-commit-cache.mjs";
 
 try {
-  const { values } = parseArgs({ options: { repository: { type: "string" }, commit: { type: "string" }, "cache-root": { type: "string" } }, strict: true });
+  const { values } = parseArgs({ options: { repository: { type: "string" }, commit: { type: "string" }, "cache-root": { type: "string" }, "timeout-ms": { type: "string" } }, strict: true });
   if (!values.repository || !values.commit) throw new TypeError("用法: scripts/cache-template-commit --repository <remote-url> --commit <40位commit> [--cache-root <path>]");
-  const result = acquireTemplateCommit({ repository: values.repository, commit: values.commit, cacheRoot: values["cache-root"] });
+  const result = acquireTemplateCommit({ repository: values.repository, commit: values.commit, cacheRoot: values["cache-root"], timeoutMs: Number(values["timeout-ms"] || 0) });
   process.stdout.write(`${JSON.stringify(result)}\n`);
 } catch (error) {
   process.stderr.write(`模板 commit 缓存失败: ${error.message}\n`);

package/template/scripts/fixtures/strategic-handoff/source-roles.json

@@ -73,7 +73,7 @@
     ],
     "stages": [
       "stage.entry-triage",
-      "stage.discovery",
+      "stage.plan",
       "stage.spec-architecture",
       "stage.product-design",
       "stage.system-data-engineering",
@@ -103,11 +103,11 @@
       "contract_version": 1,
       "title": "YSS 需求经理",
       "stages": [
-        "stage.discovery",
+        "stage.plan",
         "stage.spec-architecture"
       ],
       "draft_artifact_ids": [
-        "artifact.discovery-record",
+        "artifact.plan-record",
         "artifact.spec"
       ],
       "core_skills": [
@@ -137,7 +137,7 @@
       "contract_version": 1,
       "title": "YSS 产品经理",
       "stages": [
-        "stage.discovery",
+        "stage.plan",
         "stage.spec-architecture",
         "stage.product-design",
         "stage.verification-release-retrospective"
@@ -177,7 +177,7 @@
       "title": "YSS 项目经理",
       "stages": [
         "stage.entry-triage",
-        "stage.discovery",
+        "stage.plan",
         "stage.spec-architecture",
         "stage.product-design",
         "stage.system-data-engineering",
@@ -346,9 +346,9 @@
   ],
   "stage_groups": [
     {
-      "id": "group.discovery",
+      "id": "group.plan",
       "name": "Discovery",
-      "stage": "stage.discovery",
+      "stage": "stage.plan",
       "members": [
         "role.lifecycle-orchestrator",
         "role.requirements-manager",

package/template/scripts/fixtures/user-decision/plan-fixture.mjs

@@ -0,0 +1,30 @@
+// Synthetic test evidence only; never import to produce real project approval.
+import { mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { ROOT } from '../../lib/lifecycle-registry.mjs';
+import { parseContextContract, resolveContextTermRefs } from '../../lib/context-contract.mjs';
+import { decisionDigest } from '../../lib/user-decision.mjs';
+import { planEntryPolicy } from '../../lib/plan-spec-entry.mjs';
+import { buildDecisionFixture } from './build-fixture.mjs';
+
+export function buildPlanFixture(root) {
+  mkdirSync(path.join(root, 'docs/process'), { recursive: true });
+  const write = (ref, value) => writeFileSync(path.resolve(root, ref), typeof value === 'string' ? value : JSON.stringify(value, null, 2));
+  write('yss-project.yaml', 'schema_version: 1\nrepository_mode: project-instance\n');
+  for (const ref of ['CONTEXT.md', 'docs/process/lifecycle-registry.yaml']) write(ref, readFileSync(path.join(ROOT, ref), 'utf8'));
+  write('plan.md', '测试规划：小范围修订，不改变业务边界或关键规则。\n');
+  const c = parseContextContract({ root });
+  write('reconciliation.json', { schema_version: 1, repository_mode: 'project-instance', stage: 'stage.plan', work_unit: 'work-unit.plan-requirements', status: 'reconciled', context_snapshot: { context_ref: c.context_ref, context_schema_version: c.context_schema_version, document_digest: c.document_digest, referenced_terms_digest: resolveContextTermRefs(c, []).referenced_terms_digest, term_refs: [] }, changes: { added: [], updated: [], deprecated: [] }, unresolved_terms: [], evidence_refs: ['CONTEXT.md'] });
+  const policy = planEntryPolicy({ root });
+  const review = { schema_version: 1, kind: 'plan-entry-review', feature_id: 'feature.demo', plan_ref: 'plan.md', context_reconciliation_ref: 'reconciliation.json', basis: ['plan.md', 'CONTEXT.md', 'docs/process/lifecycle-registry.yaml', 'reconciliation.json'].map(ref => ({ ref, digest: decisionDigest(readFileSync(path.join(root, ref))) })), checks: Object.fromEntries(policy.required_checks.map(id => [id, { status: 'passed', evidence_refs: ['plan.md'] }])), open_items: [], impacts: { domain_strategy: false, stage_decision: false }, gates: Object.fromEntries(Object.keys(policy.gate_impacts).map(id => [id, { status: 'not-applicable', reason: '本次仅修订已确认范围内的细节，不改变边界、规则或阶段合同', evidence_refs: ['plan.md'] }])) };
+  const reviewRef = path.join(root, 'review.json');
+  const save = () => write(reviewRef, review);
+  save();
+  const approval = buildDecisionFixture(path.join(root, 'approval'), { boundary: 'plan-conclusion', subjectRef: reviewRef });
+  const reapprove = () => {
+    save();
+    approval.record.request.items[0].subject.digest = decisionDigest(readFileSync(reviewRef));
+    approval.present(); approval.record.responses = []; approval.respond(); approval.save();
+  };
+  return { root, review, save, write, approval, reapprove, state: { feature_id: review.feature_id, plan_review_ref: reviewRef, plan_user_decision_ref: approval.ref, user_decisions: [approval.requirement] } };
+}

package/template/scripts/lib/backend-delivery.mjs

@@ -81,10 +81,13 @@ function validManifest(manifest,root) {
   ensure(manifest.files.reduce((total,file)=>total+file.size_bytes,0)<=512*1024*1024,'后端包大小超限');
   const originals=manifest.files.filter(x=>x.original_ref).map(x=>x.original_ref);
   ensure(new Set(originals.map(x=>x.toLowerCase())).size===originals.length,'后端包源路径重复');
+  const captured = new Map();
   for(const file of manifest.files) {
     const bytes=readFileSync(safe(root,file.path));
     ensure(bytes.length===file.size_bytes&&hash(bytes)===file.sha256,`后端包文件摘要不一致: ${file.path}`);
+    captured.set(file.path, bytes);
   }
+  return captured;
 }
 
 export async function openBackendDelivery(input, action) {
@@ -93,9 +96,9 @@ export async function openBackendDelivery(input, action) {
     ensure(existsSync(input)&&!lstatSync(input).isSymbolicLink(),'后端交付包不存在或是 symlink');
     let root=path.resolve(input);
     if(lstatSync(root).isFile()) { root=path.join(temporary,'unpacked');mkdirSync(root);archive('unpack',path.resolve(input),root); }
-    const manifest=read(safe(root,'manifest.json'));validManifest(manifest,root);
+    const manifest=read(safe(root,'manifest.json'));const captured=validManifest(manifest,root);
     const source=path.join(temporary,'source');mkdirSync(source);
-    for(const file of manifest.files)if(file.original_ref)write(source,file.original_ref,readFileSync(safe(root,file.path)));
+    for(const file of manifest.files)if(file.original_ref)write(source,file.original_ref,captured.get(file.path));
     const inspected=await inspectBackendDelivery(source,manifest.delivery_ref);
     ensure(manifest.delivery_id===inspected.delivery.delivery_id&&manifest.version===inspected.delivery.version,'后端包身份不一致');
     return await action({root,source,manifest,...inspected});

package/template/scripts/lib/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/template/scripts/lib/context-reconciliation.mjs

@@ -0,0 +1,34 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { parseDocument } from "../vendor/yaml.mjs";
+import { resolveContextTermRefs, verifyContextSnapshot } from "./context-contract.mjs";
+import { validateJsonSchema } from "./json-schema.mjs";
+const schemaPath = path.resolve(import.meta.dirname, "../../docs/process/schemas/context-reconciliation.schema.json");
+export function parseReconciliationFile(file) {
+  const document = parseDocument(readFileSync(file, "utf8"), { maxAliasCount: 0, uniqueKeys: true });
+  if (document.errors.length) throw new TypeError(document.errors[0].message);
+  return document.toJS({ maxAliasCount: 0 });
+}
+
+export function verifyContextReconciliation(file, { root = process.cwd() } = {}) {
+  root = path.resolve(root);
+  const value = parseReconciliationFile(path.resolve(file));
+  validateJsonSchema(value, schemaPath, { formatChecker: false });
+  const manifest = parseReconciliationFile(path.join(root, "yss-project.yaml"));
+  if (value.repository_mode !== manifest.repository_mode) throw new TypeError("repository_mode 必须与根目录 yss-project.yaml 一致");
+  const contract = verifyContextSnapshot(value.context_snapshot, { root });
+  const changedRefs = [...value.changes.added, ...value.changes.updated, ...value.changes.deprecated];
+  resolveContextTermRefs(contract, changedRefs);
+  if (new Set(changedRefs).size !== changedRefs.length) throw new TypeError("changes 中的术语引用不得跨分类重复");
+  if (value.repository_mode === "project-instance" && value.status !== "reconciled") throw new TypeError("project-instance 工作单元只有 status=reconciled 才允许批准或进入下一步");
+  if (value.status === "reconciled" && value.unresolved_terms.length) throw new TypeError("reconciled 不得包含 unresolved_terms");
+  if (value.status === "blocked" && value.unresolved_terms.length === 0) throw new TypeError("blocked 必须说明 unresolved_terms");
+  if (value.status === "not-applicable" && (value.repository_mode !== "template-source" || !value.reason)) throw new TypeError("not-applicable 只适用于 template-source 且必须说明 reason");
+  for (const ref of value.evidence_refs) {
+    if (/^https?:\/\//.test(ref)) continue;
+    const resolved = path.resolve(root, ref);
+    if (!resolved.startsWith(`${root}${path.sep}`) && resolved !== root) throw new TypeError(`evidence_ref 越出仓库: ${ref}`);
+    if (!existsSync(resolved)) throw new TypeError(`evidence_ref 不可读: ${ref}`);
+  }
+  return contract;
+}