create-yss-spec 3.3.0 → 3.3.1

package/template/.claude/skills/yss-product-lifecycle/references/orchestration-contract.yaml

@@ -48,6 +48,34 @@ modes:
   orchestrate: bounded_write
   resume: rebuild_then_bounded_write
 
+execution_efficiency:
+  context_query:
+    strategy: combine-mode-stage-work-unit-and-required-includes
+    read_scope: current-work-unit-and-triggered-impacts
+    reuse: already-read-unchanged-sources-within-current-task
+    refresh_on: [source-changed, new-impact, evidence-conflict, resume, handoff]
+  verification:
+    scope: current-artifacts-and-triggered-contracts
+    timing: after-artifact-write-before-approval-or-transition
+    duplicate_check: reuse-only-within-same-boundary-and-unchanged-inputs
+    unchanged_inputs: [artifact-bytes, upstream-bytes, validator-and-schema, command-and-options, repository-root]
+    freshness_unknown: rerun
+    always_revalidate_on: [resume, handoff, implementation-entry, merge, release]
+    template_regression_suite: template-maintenance-or-explicit-regression-task
+    per_work_unit_context_reconciliation: required
+    skip_triggered_gates: forbidden
+  interaction:
+    questions: batch-independent-current-stage-questions
+    user_decision_policy_ref: docs/agents/digital-human-roles.yaml#user_decision_policy
+    decision_evidence_ref: references/user-decisions.md
+    dependent_future_approvals: forbidden
+    checkpoint_policy_ref: checkpoint_policy
+  timing_evidence:
+    location: existing-checkpoint-verification-evidence
+    script_fields: [command, duration_ms, exit_code]
+    distinguish: [script-execution, agent-orchestration, human-wait]
+    unmeasured_duration: unknown
+
 # 有效的 YSS 仓库必须先由生命周期编排器接管入口；Matt flow 只负责选择工作方式。
 entry_routing:
   manifest: yss-project.yaml
@@ -210,7 +238,7 @@ lifecycle_native_entries:
     implement: lifecycle-validate-and-accept
 
 work_unit_routes:
-  work-unit.discovery-opportunity:
+  work-unit.plan-opportunity:
     native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
     primary_skill: yss-product-lifecycle
     supporting_skills: [competitive-intelligence, yss-research]
@@ -218,7 +246,7 @@ work_unit_routes:
     route_by: {market_or_competitor_fact: competitive-intelligence, technical_or_standard_fact: yss-research:technical-evidence, strategy_fact: yss-research:strategy-evidence, no_external_fact: yss-product-lifecycle}
     applies_when: opportunity_or_external_fact_requires_validation
     not_applicable_reason: no_external_fact
-  work-unit.discovery-requirements:
+  work-unit.plan-requirements:
     native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
     primary_skill: yss-product-lifecycle
     supporting_skills: [grilling, domain-modeling]
@@ -241,7 +269,7 @@ work_unit_routes:
     skills: [yss-stage-decision, domain-modeling, yss-research]
     research_contract: {profile: strategy-evidence, mode_before_gate: evidence-audited, artifact_owner: yss-research, downstream_owner: yss-stage-decision}
     human_gate: stage-decision-package-approved
-    applies_when: discovery_to_spec_requires_stable_decision_package
+    applies_when: plan_to_spec_requires_stable_decision_package
     not_applicable_reason: existing_approved_stage_decision_current
   work-unit.spec-synthesis:
     native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
@@ -484,6 +512,10 @@ transition_graph:
     work-unit.intensity-aware-verification: [work-unit.intensity-aware-review]
     work-unit.intensity-aware-review: [work-unit.release-and-rollback]
     work-unit.release-and-rollback: []
+    work-unit.plan-opportunity: [work-unit.plan-requirements, work-unit.domain-strategy-design, work-unit.stage-decision, work-unit.spec-synthesis]
+    work-unit.plan-requirements: [work-unit.domain-strategy-design, work-unit.stage-decision, work-unit.spec-synthesis]
+    work-unit.domain-strategy-design: [work-unit.stage-decision, work-unit.spec-synthesis]
+    work-unit.stage-decision: [work-unit.spec-synthesis]
     work-unit.spec-synthesis: [work-unit.prototype-design, work-unit.technical-analysis, work-unit.implementation-repository-preparation]
     work-unit.prototype-design: [work-unit.technical-analysis, work-unit.implementation-repository-preparation]
     work-unit.technical-analysis: [work-unit.implementation-repository-preparation]
@@ -495,6 +527,25 @@ transition_graph:
     - {from: work-unit.technical-analysis, to: work-unit.slice-implementation}
     - {from: work-unit.technical-analysis, to: work-unit.ticket-decomposition}
 
+planning:
+  entry_validator: scripts/verify-plan-spec-entry
+  review_contract: docs/plan/entry-review.md
+  check_policy: docs/process/lifecycle-registry.yaml
+  default_check_status: pending
+  formal_spec_draft_requires_passed_entry: true
+  stage: stage.plan
+  record: artifact.plan-record
+  template: docs/plan/templates/plan-template.md
+  exit_policy: docs/process/lifecycle-registry.yaml
+  migration_policy: docs/process/plan-migration.md
+  critical_open_questions: block-before-spec
+  deferred_details_require: [noncritical_reason, owner, resolution_point, downstream_recipient]
+  reuse_requires: [source_ref, current_version, applicable_scope, reason]
+  downstream: work-unit.spec-synthesis
+  implementation_authorized: false
+  frontier_scope: current-plan-decisions
+  deferred_details: excluded-from-frontier-only-after-user-confirms-deferral
+
 grill_exit:
   required: [frontier_empty, facts_resolved_or_routed, decisions_confirmed, shared_understanding_confirmed, no_unresolved_runnable_blocker]
   facts_resolved_or_routed:
@@ -502,7 +553,7 @@ grill_exit:
     runnable_question: handoff-prototype-handoff
     external_decision: external-input-required
   user_confirmation_required: true
-  output: discovery-evidence
+  output: plan-evidence
 
 ticket_role_transition:
   yss_active:
@@ -761,7 +812,7 @@ tracker:
   local_markdown:
     root: docs/.scratch
     legacy_roots: [.scratch, docs/requirements/tickets]
-    feature_layout: [map.md, discovery, spec.md, spec-delta, parent-ticket.md, design, api, architecture, gates, verification, issues]
+    feature_layout: [map.md, plan, spec.md, spec-delta, parent-ticket.md, design, api, architecture, gates, verification, issues]
     primary_sync: local
     remote_ticket_required: false
     remote_mirror: optional
@@ -817,7 +868,7 @@ wayfinder_mode:
     - multi-session-or-multi-agent-work
     - unclear-decision-frontier
     - cross-domain-dependency-map-needed
-  lifecycle_position: discovery-to-spec-planning
+  lifecycle_position: plan-to-spec-planning
   completion_route: wayfinder -> handoff -> to-spec
   does_not_replace: [lifecycle-gates, spec-baseline, ticket-formalization]
   forbidden_state_mutations: [ready-for-agent, gate-approval, ticket-role]

package/template/.claude/skills/yss-product-lifecycle/references/orchestration.md

@@ -13,6 +13,16 @@
 
 连续阶段自动推进时累积 Ticket 同步和 Git 判断证据，在人工暂停、handoff、进入实现、合并或发布边界集中 checkpoint。发生阻塞、责任人变化或资产需要单独批准时立即落 checkpoint，不因合并记录而丢失阶段因果关系。
 
+## 执行成本
+
+执行策略以 `orchestration-contract.yaml.execution_efficiency` 为准，通过同一次 `query-lifecycle-context` 查询取得。Plan → Spec → Ticket 的耗时应分清脚本执行、Agent 读取与编排、人工等待；没有计时记录时不把总时长归因于摘要计算。
+
+同一工作单元把 mode、stage、work-unit 和必要 include 放进一次查询。查询已给出的内容不再整份读取；已读资料在当前任务内未变化时复用，变化、新影响或恢复时重新加载。只问当前阶段尚缺且会影响判断的问题，独立问题可合并；依赖尚未形成资产的后续批准仍按用户决定协议逐边界取得。
+
+资产写入稳定后、批准或流转前执行当前合同要求的验证。同一边界内，只有输入字节、上游、验证器/schema、参数和仓库根均已确认未变化且实际结果可读时，才引用已执行结果；不确定就重跑。每个工作单元仍生成并校验自己的 context reconciliation；恢复、交接、实现、合并和发布边界重新执行适用验证。`verify-*-scenarios` 与模板全量核验用于模板维护或明确的回归任务，不因产品阶段切换而重复执行；实例合同显式要求的检查仍须执行。
+
+脚本命令、实际退出码和 duration_ms 记入已有 checkpoint 的验证证据；Agent 编排和人工等待仅在有计时来源时记录，否则标为 unknown。无需为耗时再建一套阶段产物。
+
 ## 阶段边界
 
 Matt phase boundary 是工作阶段之间的上下文决策，不是新的生命周期状态。按以下顺序判断，第一项适用即停止判断：
@@ -59,7 +69,7 @@ tracker 选择和冲突按 `docs/agents/issue-tracker.md` 裁决：已持久化
 
 - `work-unit.technical-analysis` 由 `yss-technical-design` 组织后端技术设计，先按项目确认架构，再调用 DDD `yss-tactical-design` 或传统 MVC `yss-mvc-design`。状态、规则、一致性、持久化影响本身不意味着选择 DDD。无后端技术设计影响记录带原因的 `not-applicable`，其他 API / 前端技术分析继续各自路由。新合同使用 `artifact.technical-design`，通过 `evidence.technical-design-review` 回交现有架构审查；旧 DDD 稳定 ID 只读兼容。批准仍由生命周期维护，编译器消费批准且当前的设计起草实现合同；`stale`、`drift` 或 `new_impacts` 时不得继续 Ticket 正式化。
 
-- `work-unit.discovery-requirements` 实际调用 `grilling` 和 `domain-modeling`；`work-unit.discovery-opportunity` 按事实类型路由 `competitive-intelligence` 或 `yss-research`。`yss-research:quick` 只用于探索；外部证据进入领域战略、阶段决策或其他生命周期批准输入前必须升级为 `evidence-audited`。生命周期原生工作单元默认负责 Spec、Ticket 和实现资产；`to-spec`、`to-tickets`、`implement` 仅保留为显式兼容入口，结果必须回交生命周期验收。
+- `work-unit.plan-requirements` 实际调用 `grilling` 和 `domain-modeling`；`work-unit.plan-opportunity` 按事实类型路由 `competitive-intelligence` 或 `yss-research`。`yss-research:quick` 只用于探索；外部证据进入领域战略、阶段决策或其他生命周期批准输入前必须升级为 `evidence-audited`。生命周期原生工作单元默认负责 Spec、Ticket 和实现资产；`to-spec`、`to-tickets`、`implement` 仅保留为显式兼容入口，结果必须回交生命周期验收。
 - 原生 `work-unit.ticket-decomposition` 只能在 OpenAPI Freeze 或无 API 影响记录后创建垂直切片，初始 Ticket 状态统一为 `ready-for-human`；生命周期复算完整公式后才能提升 `ready-for-agent`。该工作单元必须返回 `ticket_decomposition_result_ref` 和垂直切片引用，并作为实现的必经前置证据。
 - 原生 `work-unit.slice-implementation` 必须在生命周期批准并持久化 Slice Implementation Contract 和 Build Architecture Checklist 后执行；用户显式 `implement` 仍走兼容入口，不得绕过生命周期。
 - `Workflow Execution Result.next_route` 必须通过生命周期转换校验；Spec、原型和技术分析不得直接跳转到 Ticket 正式化或实现，必须先完成 `work-unit.implementation-repository-preparation`，再进入 `work-unit.ticket-decomposition`。

package/template/.claude/skills/yss-research/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yss-research
-description: Research technical or product-strategy questions with traceable evidence before YSS Discovery, Spec, domain-strategy, API, architecture, or implementation decisions. Use for current facts, standards, third-party APIs, business constraints, user problems, domain-boundary evidence, or when the deprecated `research` alias is invoked.
+description: Research technical or product-strategy questions with traceable evidence before YSS Plan, Spec, domain-strategy, API, architecture, or implementation decisions. Use for current facts, standards, third-party APIs, business constraints, user problems, domain-boundary evidence, or when the deprecated `research` alias is invoked.
 ---
 
 # YSS Research

package/template/.claude/skills/yss-stage-decision/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yss-stage-decision
-description: 编排 Discovery 到 Spec 入口的方案决策与业务边界、协作和规则设计；当需求、业务责任区、统一业务词汇或下游影响尚未稳定时使用。
+description: 编排 Plan 到 Spec 入口的方案决策与业务边界、协作和规则设计；当需求、业务责任区、统一业务词汇或下游影响尚未稳定时使用。
 ---
 
 # YSS Stage Decision
@@ -9,14 +9,16 @@ description: 编排 Discovery 到 Spec 入口的方案决策与业务边界、
 
 ## 适用边界
 
-- 适用于 `project-instance` 的 Discovery → Spec 入口。
+- 适用于 `project-instance` 的 Plan → Spec 入口。
 - `template-source` 只维护本技能、Schema、验证器和合成 Fixture，不生成具体产品领域资产。
 - 业务边界与协作工作单元只回答：有哪些业务板块、每个业务责任区负责什么、不同责任区如何交接、使用哪些统一业务词汇、发生哪些业务事实、有哪些待确认的关键业务对象和不可违反的业务规则。
 - Entity、Aggregate、Repository、Java 类、数据库表和 OpenAPI Freeze 留给下游工作单元。
 
 ## 执行顺序
 
-1. 读取 `yss-project.yaml`、`CONTEXT.md`、既有 Discovery/Spec、ADR 和父 Ticket/checkpoint。
+Plan 的目标与退出条件由 `docs/process/lifecycle-registry.yaml` 持有；从 `docs/plan/templates/plan-template.md` 汇总输入。旧资产按 `docs/process/plan-migration.md` 重新整理并核查，关键未决项不得延期到 Spec，非关键项记录责任人、解决时点与接收方。
+
+1. 读取 `yss-project.yaml`、`CONTEXT.md`、既有 Plan/Spec、ADR 和父 Ticket/checkpoint。
 2. 分离事实、决策、假设、约束和未决项；技术事实走 `yss-research` 的 `technical-evidence`，领域边界、业务规则、MVP、非目标、成功标准或阶段推进依据等决策证据走 `strategy-evidence`，市场/竞品事实走 `competitive-intelligence`。
 3. 从业务故事、已发生的事实、规则、责任人和失败路径识别业务板块与业务责任区，不从数据库表或调用链直接反推边界。
 4. 为每个业务责任区建立统一业务词汇；对跨责任区协作记录规则提供方、规则使用方、业务决策权、信息传递方向和口径转换负责人。

package/template/.claude/skills/yss-stage-decision/references/stage-decision-package-contract.md

@@ -1,6 +1,6 @@
 # 方案决策包合同
 
-内部对象 `stage_decision_package` 是 Discovery、需求/产品/商务决策与业务边界和规则设计之间的冻结入口。它记录“做什么、为什么做、范围是什么、哪些仍未决”，不复制业务边界与规则事实。
+内部对象 `stage_decision_package` 是 Plan、需求/产品/商务决策与业务边界和规则设计之间的冻结入口。它记录“做什么、为什么做、范围是什么、哪些仍未决”，不复制业务边界与规则事实。
 
 ## 必须包含
 

package/template/.codex/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/.codex/skills/domain-modeling/CONTEXT-FORMAT.md

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

package/template/.codex/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/.codex/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/.codex/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/.codex/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/.codex/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/.codex/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/.codex/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/.codex/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/.codex/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/.codex/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` |