create-yss-spec 3.0.1 → 3.1.0

package/template/scripts/lib/scenario-checks.mjs

@@ -1,5 +1,7 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, mkdtempSync, rmSync } from "node:fs";
 import path from "node:path";
+import os from "node:os";
+import { buildDecisionFixture, buildImplementationFixture } from "../fixtures/user-decision/build-fixture.mjs";
 import { fileURLToPath } from "node:url";
 import { spawnSync } from "node:child_process";
 import { parseDocument } from "../vendor/yaml.mjs";
@@ -15,10 +17,8 @@ const virtualTicketDecompositionRef = "docs/.scratch/demo/evidence/ticket-decomp
 const virtualTicketDecomposition = "result_schema: workflow-execution-result-v1\nwork_unit: work-unit.ticket-decomposition\nresult: completed\nevidence_refs:\n  - docs/.scratch/demo/evidence/ticket-decomposition-result.yaml\n";
 
 function validateMattContract(data) {
-  const direct = data.entry_routing?.direct_matt_entry;
-  ensure(direct?.skill === "ask-matt" && direct?.delegate_to === "yss-product-lifecycle" && direct?.requires_valid_manifest === true && direct?.action === "navigate-only" && direct?.lifecycle_state_mutation === "forbidden" && direct?.lifecycle_artifact_write === "forbidden" && direct?.return_to_orchestrator === "required", "ask-matt 导航入口尚未形成验明身份、只导航、禁止生命周期写入并强制回交主控的完整契约");
   const formal = data.entry_routing?.formal_user_entry;
-  ensure(includesAll(formal?.skills, ["setup-matt-pocock-skills", "grill-with-docs", "to-spec", "to-tickets", "implement"]) && formal?.action === "lifecycle-validate-and-accept" && formal?.lifecycle_artifact_write === "conditional-explicit-user-entry" && formal?.return_to_orchestrator === "required", "正式用户入口未区分于 ask-matt 导航入口");
+  ensure(includesAll(formal?.skills, ["setup-matt-pocock-skills", "grill-with-docs", "to-spec", "to-tickets", "implement"]) && formal?.action === "lifecycle-validate-and-accept" && formal?.lifecycle_artifact_write === "conditional-explicit-user-entry" && formal?.return_to_orchestrator === "required", "正式用户入口缺少生命周期预检与回交约束");
   const setup = data.setup_readiness;
   ensure(setup?.missing_action === "needs-human" && setup?.requested_skill === "setup-matt-pocock-skills" && setup?.resume_route === "setup-readiness" && setup?.lifecycle_may_invoke_setup === false, "setup 缺失时未限制为显式用户入口暂停");
   ensure(includesAll(setup?.preserves, ["lifecycle.status", "gate.status", "ticket.role"]) && setup?.legacy_artifacts_detected?.action === "migration-check" && setup.legacy_artifacts_detected.setup === "forbidden" && setup.legacy_artifacts_detected.write === "paused", "setup 暂停或旧资产迁移暂停契约不完整");
@@ -39,8 +39,8 @@ function validateMattContract(data) {
 
 function validateInvocationBoundary(data) {
   const boundary = data.matt_invocation_boundary;
-  const expectedUserInvoked = ["ask-matt", "grill-me", "grill-with-docs", "handoff", "implement", "improve-codebase-architecture", "loop-me", "setup-matt-pocock-skills", "setup-ts-deep-modules", "teach", "to-questionnaire", "to-spec", "to-tickets", "triage", "wait-what", "wayfinder", "writing-beats", "writing-fragments", "writing-shape"];
-  const expectedModelInvoked = ["code-review", "codebase-design", "diagnosing-bugs", "domain-modeling", "grilling", "migrate-to-shoehorn", "prototype", "resolving-merge-conflicts", "scaffold-exercises", "setup-pre-commit", "tdd", "writing-for-agents", "yss-research"];
+  const expectedUserInvoked = ["grill-me", "grill-with-docs", "handoff", "implement", "improve-codebase-architecture", "setup-matt-pocock-skills", "to-questionnaire", "to-spec", "to-tickets", "triage", "wait-what", "wayfinder"];
+  const expectedModelInvoked = ["code-review", "codebase-design", "diagnosing-bugs", "domain-modeling", "grilling", "prototype", "resolving-merge-conflicts", "tdd", "writing-for-agents", "yss-research"];
   const expectedLifecycleModelInvoked = ["code-review", "codebase-design", "diagnosing-bugs", "domain-modeling", "grilling", "prototype", "tdd", "yss-research"];
   ensure(JSON.stringify(boundary?.user_invoked_skills) === JSON.stringify(expectedUserInvoked), "Matt user-invoked skills 清单不完整或已漂移");
   ensure(JSON.stringify(boundary?.lifecycle_managed_user_entries) === JSON.stringify(["setup-matt-pocock-skills", "grill-with-docs", "to-spec", "to-tickets", "implement"]), "生命周期管理的显式用户入口清单不完整");
@@ -53,10 +53,10 @@ function validateInvocationBoundary(data) {
   const result = data.workflow_execution_result;
   ensure(data.matt_skill_result?.status === "compatibility-read-only" && data.matt_skill_result?.may_influence_routing === false && data.matt_skill_result?.normalize_to === "workflow-execution-result-v1", "旧 Matt Skill Result 未限制为只读兼容 adapter");
   ensure(result?.canonical_output_schema === "workflow-execution-result-v1" && JSON.stringify(result?.accepted_input_schemas) === JSON.stringify(["workflow-execution-result-v1"]) && result?.legacy?.["matt-skill-result-v1"]?.status === "compatibility-read-only" && result.legacy["matt-skill-result-v1"].may_influence_routing === false && result.legacy["matt-skill-result-v1"].normalize_to === "workflow-execution-result-v1", "Workflow Execution Result 未将旧 Matt Skill Result 限制为只读兼容");
-  ensure(includesAll(result?.required, ["result_schema", "work_unit", "workflow_reference", "result", "evidence_refs", "changed_artifacts", "new_impacts", "stale_candidates", "next_route", "blocking_signals"]) && includesAll(result?.result_values, ["completed", "blocked", "needs-human", "failed"]) && includesAll(result?.blocking_signals, ["drift", "new_impacts", "violation", "missing_evidence", "stale_candidates"]) && includesAll(result?.completed_requires_empty, ["new_impacts", "stale_candidates"]) && includesAll(result?.completed_requires_non_empty, ["evidence_refs"]) && result?.completed_requires_readable_evidence_refs === true && result?.evidence_ref_validation === "readable-or-resolvable" && result?.completed_requires_no_blocking_signals === true && includesAll(result?.workflow_reference?.required, ["source", "skill", "invocation_mode"]), "Workflow Execution Result 的完成态证据、阻断信号或 workflow_reference 契约不完整");
+  ensure(includesAll(result?.required, ["result_schema", "work_unit", "workflow_reference", "result", "context_reconciliation", "evidence_refs", "changed_artifacts", "new_impacts", "stale_candidates", "next_route", "blocking_signals"]) && includesAll(result?.result_values, ["completed", "blocked", "needs-human", "failed"]) && includesAll(result?.blocking_signals, ["drift", "new_impacts", "violation", "missing_evidence", "stale_candidates"]) && includesAll(result?.completed_requires_empty, ["new_impacts", "stale_candidates"]) && includesAll(result?.completed_requires_non_empty, ["evidence_refs"]) && result?.completed_requires_readable_evidence_refs === true && result?.evidence_ref_validation === "readable-or-resolvable" && result?.completed_requires_no_blocking_signals === true && result?.context_reconciliation?.creates_gate === false && includesAll(result?.workflow_reference?.required, ["source", "skill", "invocation_mode"]), "Workflow Execution Result 的完成态证据、阻断信号、context_reconciliation 或 workflow_reference 契约不完整");
   const native = data.lifecycle_native_entries;
   ensure(native?.default_entry === "yss-product-lifecycle" && native?.formal_artifact_owner === "yss-product-lifecycle", "生命周期原生入口未持有默认正式资产所有权");
-  ensure(JSON.stringify(native?.user_confirmation_required_at) === JSON.stringify(["spec-baseline", "prototype-confirmation", "openapi-freeze", "merge-or-release"]), "生命周期人工门禁集合已漂移");
+  ensure(native?.user_confirmation_policy_ref === "docs/agents/digital-human-roles.yaml#user_decision_policy", "生命周期人工门禁集合已漂移");
   const routes = data.work_unit_routes;
   ensure(routes?.["work-unit.discovery-requirements"]?.skills?.includes("grilling") && routes?.["work-unit.discovery-requirements"]?.skills?.includes("domain-modeling"), "需求分析工作单元缺少 grilling/domain-modeling");
   ensure(routes?.["work-unit.discovery-opportunity"]?.route_by?.market_or_competitor_fact === "competitive-intelligence" && routes["work-unit.discovery-opportunity"].route_by.technical_or_standard_fact === "yss-research:technical-evidence" && routes["work-unit.discovery-opportunity"].route_by.strategy_fact === "yss-research:strategy-evidence", "机会调研事实路由不准确");
@@ -69,7 +69,7 @@ function validateInvocationBoundary(data) {
   ensure(JSON.stringify(Object.keys(prototypeRoute?.profile_contract?.profiles ?? {})) === JSON.stringify(["H1", "H2"]) && prototypeRoute?.version_boundary?.prototype_must_not_call === "yss-ui", "原型档位必须仅包含 H1/H2 并明确 yss-ui 边界");
   ensure(routes?.["work-unit.slice-implementation"]?.skills?.includes("tdd") && routes?.["work-unit.slice-implementation"]?.skills?.includes("yss-ui") && routes?.["work-unit.slice-implementation"]?.skills?.includes("yss-ui-business-page-generation"), "原生实现工作单元缺少 TDD、UI 或业务页面生成路由");
   const frontendRoute = routes?.["work-unit.slice-implementation"]?.frontend_route;
-  ensure(frontendRoute?.primary_skill === "yss-ui" && frontendRoute?.page_generation_skill === "yss-ui-business-page-generation" && frontendRoute?.page_orchestration_skill === "yss-page-module-development", "前端实现路由缺少 yss-ui 主入口、业务页面生成或页面编排技能");
+  ensure(frontendRoute?.primary_skill === "yss-ui" && frontendRoute?.page_generation_skill === "yss-ui-business-page-generation" && frontendRoute?.page_orchestration_skill === "yss-ui-business-page-generation", "前端实现路由缺少 yss-ui 主入口或统一业务页面技能");
   for (const impact of ["api_impact", "formily_impact", "table_impact", "tree_impact", "height_impact", "export_impact", "theme_impact"]) {
     ensure(Array.isArray(frontendRoute?.conditional_skills?.[impact]) && frontendRoute.conditional_skills[impact].length > 0 && typeof frontendRoute.not_applicable_reasons?.[impact] === "string", `前端条件专项路由缺少 ${impact}`);
   }
@@ -105,8 +105,10 @@ function validateWorkflowExecutionResult(payload, contract, workUnitRoutes) {
   const workUnit = workUnitRoutes?.[payload.work_unit];
   ensure(workUnit, `未知 Workflow Execution Result work_unit: ${payload.work_unit}`);
   if (payload.result === "completed") {
-    const routeResult = validateNextRoute(payload.work_unit, payload.next_route);
+    const routeResult = validateNextRoute(payload.work_unit, payload.next_route, payload);
     ensure(routeResult.result === "allowed", `Workflow Execution Result next_route 非法: ${routeResult.blocking_signals.join(", ")}`);
+    ensure(payload.context_reconciliation?.status === "reconciled", "project-instance 完成态必须具有 reconciled context_reconciliation");
+    ensure(hasText(payload.context_reconciliation?.ref) && payload.evidence_refs.includes(payload.context_reconciliation.ref) && exists(payload.context_reconciliation.ref), "context_reconciliation.ref 必须可读并包含在 evidence_refs 中");
   }
   const accepted = [workUnit.native, workUnit.compatibility].filter(Boolean);
   ensure(contract.workflow_reference.allowed_sources.includes(payload.workflow_reference.source) && accepted.some((route) => route.source === payload.workflow_reference.source && route.skill === payload.workflow_reference.skill && route.invocation_mode === payload.workflow_reference.invocation_mode), "Workflow Execution Result workflow_reference 与 work_unit route 不匹配");
@@ -121,6 +123,8 @@ function validateWorkflowExecutionResult(payload, contract, workUnitRoutes) {
   }
   if (payload.work_unit === "work-unit.slice-implementation" && payload.result === "completed") {
     const implementationState = {
+      user_decisions: payload.user_decisions,
+      slice_contract_ref: payload.slice_contract_ref,
       tracker_kind: payload.tracker_kind,
       predecessor_work_unit: payload.predecessor_work_unit,
       ready_for_agent: payload.ready_for_agent,
@@ -141,7 +145,7 @@ function validateWorkflowExecutionResult(payload, contract, workUnitRoutes) {
       // The scenario uses one explicit virtual fixture; arbitrary local refs
       // must still pass the real readability check and cannot use a fallback.
       exists: (ref) => exists(ref) || ref === "docs/.scratch/demo/issues/01-valid-slice.md" || ref === virtualTicketDecompositionRef,
-      read: (ref) => ref === virtualTicketDecompositionRef ? virtualTicketDecomposition : readFileSync(path.join(root, ref), "utf8"),
+      read: (ref) => ref === virtualTicketDecompositionRef ? virtualTicketDecomposition : readFileSync(path.resolve(root, ref), "utf8"),
     });
     ensure(semantic.result === "allowed", `Workflow Execution Result implementation Ticket 语义非法: ${semantic.blocking_signals.join(", ")}`);
   }
@@ -256,11 +260,17 @@ export function runScenario(name) {
     const data = contract.toJS({ maxAliasCount: 0 });
     validateMattContract(data);
     validateInvocationBoundary(data);
+    const decisionTemp = mkdtempSync(path.join(os.tmpdir(), "matt-decision-test-"));
+    process.on("exit", () => rmSync(decisionTemp, { recursive: true, force: true }));
+    const specDecision = buildDecisionFixture(path.join(decisionTemp, "spec"));
+    const implementationDecision = buildImplementationFixture(path.join(decisionTemp, "implementation"), "docs/.scratch/demo/issues/01-valid-slice.md");
     const validResult = {
+      user_decisions: [specDecision.requirement],
       result_schema: "workflow-execution-result-v1",
       work_unit: "work-unit.spec-synthesis",
       workflow_reference: { source: "yss-product-lifecycle", skill: "yss-product-lifecycle", invocation_mode: "model-invoked" },
       result: "completed",
+      context_reconciliation: { status: "reconciled", ref: "docs/process/lifecycle-registry.yaml" },
       evidence_refs: ["docs/process/lifecycle-registry.yaml"],
       changed_artifacts: [],
       new_impacts: [],
@@ -279,6 +289,7 @@ export function runScenario(name) {
     validateWorkflowExecutionResult(validTicketResult, data.workflow_execution_result, data.work_unit_routes);
     const validImplementationResult = {
       ...validResult,
+      ...implementationDecision.state,
       evidence_refs: [virtualTicketDecompositionRef, "docs/process/lifecycle-registry.yaml"],
       work_unit: "work-unit.slice-implementation",
       next_route: "work-unit.code-review",
@@ -324,6 +335,8 @@ export function runScenario(name) {
     validateWorkflowExecutionResult(compatibleResult, data.workflow_execution_result, data.work_unit_routes);
     for (const mutate of [
       (item) => { delete item.workflow_reference; },
+      (item) => { delete item.context_reconciliation; },
+      (item) => { item.context_reconciliation.status = "blocked"; },
       (item) => { item.evidence_refs = []; },
       (item) => { item.evidence_refs = ["docs/process/not-found.md"]; },
       (item) => { item.blocking_signals = ["drift"]; },
@@ -344,7 +357,7 @@ export function runScenario(name) {
     } catch { metadataRejected = true; }
     ensure(metadataRejected, "user-invoked front matter 变异未被 baseline oracle 拒绝");
     const mutations = [
-      (item) => { delete item.entry_routing.direct_matt_entry.return_to_orchestrator; },
+      (item) => { delete item.entry_routing.formal_user_entry.return_to_orchestrator; },
       (item) => { item.entry_routing.formal_user_entry.lifecycle_artifact_write = "forbidden"; },
       (item) => { item.matt_invocation_boundary.user_invoked_skills.push("unexpected-user-entry"); },
       (item) => { item.setup_readiness.lifecycle_may_invoke_setup = true; },

package/template/scripts/lib/skill-governance.mjs

@@ -14,7 +14,19 @@ function fail(message) {
 export function validateSkillGovernance({ read = (relative) => readFileSync(path.join(ROOT, relative), "utf8"), exists = (relative) => existsSync(path.join(ROOT, relative)) } = {}) {
   const globalRules = read(".agents/rules/yss-ai-skills.md");
   const tableSkill = read(".agents/skills/ytable-usage/SKILL.md");
-  const pageSkill = read(".agents/skills/yss-page-module-development/SKILL.md");
+  const pageSkill = read(".agents/skills/yss-ui-business-page-generation/SKILL.md");
+
+  for (const marker of ["trigger: always_on", "docs/agents/yss-skill-registry.yaml", ".agents/skills/yss-ui/SKILL.md", "原型阶段"]) {
+    if (!globalRules.includes(marker)) fail(`YSS UI 薄入口缺少路由标记: ${marker}`);
+  }
+  for (const staleHeading of ["## Available Skills", "## Mandatory Workflow"]) {
+    if (globalRules.includes(staleHeading)) fail(`YSS UI 薄入口不得回流技能清单或实现步骤: ${staleHeading}`);
+  }
+  const cursorRules = read(".cursorrules");
+  for (const marker of ["yss-project.yaml", "docs/agents/yss-skill-registry.yaml", "yss-ui-business-page-generation", ".cursor/skills"]) {
+    if (!cursorRules.includes(marker)) fail(`Cursor 薄入口缺少路由标记: ${marker}`);
+  }
+  if (cursorRules.includes("YSS AI SKILLS START")) fail("Cursor 薄入口不得回流技能清单");
 
   if (/toolbar-config\.custom.{0,30}(必须|必需)|必须.{0,30}toolbar-config\.custom/.test(globalRules)) {
     fail("全局规则不得把 toolbar-config.custom 作为无条件要求");
@@ -25,8 +37,8 @@ export function validateSkillGovernance({ read = (relative) => readFileSync(path
   for (const marker of ["无需配置 `:toolbar-config=\"{ custom: true }\"`", "仅在业务明确需要列设置时才传入"]) {
     if (!tableSkill.includes(marker)) fail(`YTable 专项技能缺少条件化工具栏规则: ${marker}`);
   }
-  if (!pageSkill.includes("只有确实需要列设置时才启用 `toolbar-config.custom`")) {
-    fail("页面模块 canonical 技能缺少条件化 toolbar-config 规则");
+  if (!pageSkill.includes("仅在业务明确需要列设置时才传入")) {
+    fail("业务页面 canonical 技能缺少条件化 toolbar-config 规则");
   }
 
   const yssUiManifest = validateYssUiSkillManifest(JSON.parse(read(".agents/skills/.yss-skills-manifest.json")));
@@ -64,9 +76,9 @@ export function validateSkillGovernance({ read = (relative) => readFileSync(path
   }
 
   const strategicManifest = validateStrategicDesignSkillManifest(JSON.parse(read(".agents/skills/.strategic-design-skills-manifest.json")));
-  const strategicIds = ["prototype-review", "yss-prototype-stage", "yss-design-system", "yss-antd-design", "yss-stage-decision"];
+  const strategicIds = ["prototype-review", "yss-prototype-stage", "yss-design-system", "yss-antd-design", "yss-antdv-next-design", "yss-stage-decision"];
   if (JSON.stringify(strategicManifest.skills.map(({ canonical }) => canonical).sort()) !== JSON.stringify(strategicIds.slice().sort())) {
-    fail("战略设计 skills 清单必须恰好覆盖五项公共技能");
+    fail("战略设计 skills 清单必须恰好覆盖六项公共技能");
   }
   for (const skill of strategicManifest.skills) {
     if (isTemplateSource(ROOT)) {
@@ -86,11 +98,14 @@ export function validateSkillGovernance({ read = (relative) => readFileSync(path
   const registry = loadSkillRegistry();
   const canonicalIds = new Set(registry.skills.map((skill) => skill.id));
   const aliases = new Map(registry.skills.flatMap((skill) => skill.aliases.map((alias) => [alias, skill.id])));
-  const legacy = new Set(["api-integration", "page-module-development", "use-table-height", "use-tree-height"]);
+  const legacy = new Set(["api-integration", "use-table-height", "use-tree-height"]);
   for (const alias of legacy) {
     if (exists(`.agents/skills/${alias}`)) fail(`legacy alias 不得存在独立 canonical 目录: ${alias}`);
     if (!aliases.has(alias)) fail(`legacy alias 未登记: ${alias}`);
   }
+  if (exists(".agents/skills/page-module-development") || exists(".agents/skills/yss-page-module-development") || aliases.has("page-module-development")) {
+    fail("page-module-development / yss-page-module-development 已退役，不得保留物理目录或运行时 alias");
+  }
   if (exists(".agents/skills/high-fidelity-html-prototype") || aliases.has("high-fidelity-html-prototype")) {
     fail("high-fidelity-html-prototype 已退役，不得保留物理目录或运行时 alias");
   }
@@ -99,14 +114,14 @@ export function validateSkillGovernance({ read = (relative) => readFileSync(path
   const prototypeEvidence = read("docs/design/templates/prototype-evidence-template.yaml");
   const projectDesign = read("docs/design/design.md");
   const antdvCompatibility = read(".agents/skills/yss-ui/references/antdv-compatibility.md");
-  for (const marker of ["product-design-adapter.md", "schema v3", "H1", "H2", "原型阶段不得调用 `yss-ui`"]) {
+  for (const marker of ["product-design-adapter.md", "Prototype Evidence schema v4", "Visual Baseline schema v1", "H1", "H2", "原型阶段不得调用 `yss-ui`"]) {
     if (!prototypeStage.includes(marker)) fail(`原型阶段合同缺少 YSS adapter 标记: ${marker}`);
   }
-  for (const marker of ["prepare-static", "prepare-flow", "fact pack", "ConfigProvider", "1440x900", "390x844"]) {
+  for (const marker of ["prepare-static", "prepare-flow", "vue-antdv-next", "react-antd-6", "fact pack", "ConfigProvider", "1440x900", "390x844"]) {
     if (!prototypeAdapter.includes(marker)) fail(`Product Design adapter 缺少执行约束: ${marker}`);
   }
-  for (const marker of ["schema_version: 3", "prototype_profile", "visual_review", "flow_review", "implementation_handoff", "project_token_baseline_digest", "verification/design-qa.md"]) {
-    if (!prototypeEvidence.includes(marker)) fail(`原型证据模板缺少 schema v3 字段: ${marker}`);
+  for (const marker of ["schema_version: 4", "visual_baseline", "prototype_profile", "visual_review", "flow_review", "implementation_handoff", "project_token_baseline_digest", "verification/design-qa.md"]) {
+    if (!prototypeEvidence.includes(marker)) fail(`原型证据模板缺少 schema v4 字段: ${marker}`);
   }
   if (prototypeEvidence.includes("与官方 #1677ff / Inter / 8px")) fail("原型证据模板仍把 Inter/8px 误写为官方 v6 默认差异");
   if (projectDesign.includes("`antdv6-design.md`")) fail("design.md 仍引用不存在的 antdv6-design.md");

package/template/scripts/lib/skill-registry.mjs

@@ -359,7 +359,7 @@ export function validateSkillRegistry(registry, { lock, compilerContract, lifecy
     for (const mode of capability.task_modes) if (!TASK_MODES.has(mode)) fail(`${capability.id} 使用未知 task mode: ${mode}`);
     capabilitySkills.add(capability.primary_skill);
   }
-  for (const skill of skills.filter((item) => item.impacts.includes("backend"))) {
+  for (const skill of skills.filter((item) => item.impacts.includes("backend") && item.maturity !== "deprecated")) {
     if (!capabilitySkills.has(skill.id)) fail(`backend skill 缺少 capability: ${skill.id}`);
   }
 

package/template/scripts/lib/skill-supply-chain.mjs

@@ -10,7 +10,7 @@ const LOCK_PATH = path.join(ROOT, "skills-lock.json");
 const YSS_UI_MANIFEST_PATH = path.join(SOURCE_ROOT, ".yss-skills-manifest.json");
 const STRATEGIC_DESIGN_MANIFEST_PATH = path.join(SOURCE_ROOT, ".strategic-design-skills-manifest.json");
 export const PROJECTION_ROOTS = [".claude/skills", ".codex/skills", ".cursor/skills", ".pi/skills", ".qoder/skills", ".trae/skills"];
-export const OBSOLETE = new Set(["to-" + "prd", "to-" + "issues", "design-an-interface", "qa", "request-refactor-plan", "ubiquitous-language", "edit-article", "obsidian-vault", "writing-great-skills", "code-review-process", "yss-domain-modeling", "yss-dir", "yss-duckdb", "yss-file", "yss-filerunner", "yss-db2mybatis", "yss-mail", "yss-mapper-dynamic", "yss-quality", "yss-sql-condition", "yss-sql-tpl", "yss-valuation", "yss-variable", "yss-openapi", "web-design-engineer", "web-video-presentation", "wireframe-prototype", "wizard", "git-guardrails-claude-code", "claude-handoff", "batch-grill-me", "product-design-prototype", "research", "yss-dictionary", "yss-jdbc", "yss-log", "yss-taskflow", "yss-backend-scaffold-application", "yss-backend-scaffold-domain", "yss-backend-scaffold-infrastructure", "yss-backend-scaffold-web", "yss-router", "yss-source-index"]);
+export const OBSOLETE = new Set(["to-" + "prd", "to-" + "issues", "design-an-interface", "qa", "request-refactor-plan", "ubiquitous-language", "edit-article", "obsidian-vault", "writing-great-skills", "code-review-process", "yss-domain-modeling", "yss-dir", "yss-duckdb", "yss-file", "yss-filerunner", "yss-db2mybatis", "yss-mail", "yss-mapper-dynamic", "yss-quality", "yss-sql-condition", "yss-sql-tpl", "yss-valuation", "yss-variable", "yss-openapi", "web-design-engineer", "web-video-presentation", "wireframe-prototype", "wizard", "git-guardrails-claude-code", "claude-handoff", "batch-grill-me", "product-design-prototype", "research", "ask-matt", "dispatching-parallel-agents", "loop-me", "migrate-to-shoehorn", "prototype-page-acceptance", "scaffold-exercises", "setup-pre-commit", "setup-ts-deep-modules", "teach", "writing-beats", "writing-fragments", "writing-shape", "yss-microapp-commit", "yss-page-module-development", "yss-dictionary", "yss-jdbc", "yss-log", "yss-taskflow", "yss-backend-scaffold-application", "yss-backend-scaffold-domain", "yss-backend-scaffold-infrastructure", "yss-backend-scaffold-web", "yss-router", "yss-source-index"]);
 export function obsoleteCanonicalResidues(names, obsolete = OBSOLETE) {
   return names.filter((name) => obsolete.has(name)).sort();
 }

package/template/scripts/lib/strategic-handoff-consumption.mjs

@@ -0,0 +1,76 @@
+import { existsSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { openBundle } from './strategic-handoff.mjs';
+import { read, safe, ensure, ROOT, digest, project } from './strategic-handoff-io.mjs';
+import { parseContextContract } from './context-contract.mjs';
+const present=x=>typeof x==='string'&&x.trim();
+const list=x=>Array.isArray(x)&&x.length&&x.every(present);
+const without=(value,keys)=>Object.fromEntries(Object.entries(value).filter(([key])=>!keys.includes(key)));
+const strategyBasis=value=>({
+  ...without(value,['domain_version','approval','rule_catalog','scenarios','invariants']),
+  invariants:(value.invariants||[]).map(item=>without(item,['statement'])),
+});
+export async function verifyConsumption(data,{root=process.cwd(),sliceRef}={}) {
+  project(root);
+  if (sliceRef) ensure(data.status === "approved", "切片只能消费 approved 战术合同");
+  const binding=data.strategic_handoff;
+  ensure(binding && present(binding.import_receipt_ref) && present(binding.context_reconciliation_ref),'缺少战略交接导入收据与目标对账引用');
+  const receipt=read(safe(root,binding.import_receipt_ref));
+  const expectedBase=`docs/handoffs/${receipt.bundle_id}/${receipt.version}`;
+  ensure(binding.import_receipt_ref===`${expectedBase}/import-receipt.json` && receipt.package_ref===`${expectedBase}/package`,'导入收据路径与包身份不一致');
+  ensure(binding.bundle_digest===receipt.bundle_digest,'战术绑定与导入收据摘要不一致');
+  const result=spawnSync(process.execPath,[path.join(ROOT,'scripts/verify-context-reconciliation'),'--root',root,safe(root,binding.context_reconciliation_ref)],{encoding:'utf8'});
+  ensure(result.status===0,`目标术语对账未通过: ${result.error?.message || result.stderr}`);
+  const context=parseContextContract({root});
+  const parent=safe(root,`docs/handoffs/${receipt.bundle_id}`);
+  const versions=readdirSync(parent).filter(x=>/^v[1-9][0-9]*$/.test(x)&&existsSync(path.join(parent,x,'import-receipt.json'))).sort((a,b)=>Number(b.slice(1))-Number(a.slice(1)));
+  const latestReceipt=read(safe(root,`docs/handoffs/${receipt.bundle_id}/${versions[0]}/import-receipt.json`));
+  ensure(latestReceipt.version===versions[0]&&latestReceipt.package_ref===`docs/handoffs/${receipt.bundle_id}/${versions[0]}/package`,'最新收据路径无效');
+  return openBundle(safe(root,receipt.package_ref),async original=>{
+    ensure(original.manifest.bundle_digest===receipt.bundle_digest,'导入收据与包不一致');
+    return openBundle(safe(root,latestReceipt.package_ref),async current=>{
+      ensure(current.manifest.bundle_id===receipt.bundle_id && current.manifest.bundle_digest===latestReceipt.bundle_digest,'最新导入收据无效');
+      for(const op of ['added','updated'])for(const term of current.handoff.context_delta[op]) {
+        const actual=context.terms_by_ref.get(term.term_ref);ensure(actual,`目标缺少术语: ${term.term_ref}`);
+        for(const key of ['term','meaning','english_identifier','context_id','forbidden_aliases'])ensure(digest(actual[key])===digest(term[key]),`目标术语未对账: ${term.term_ref}`);
+      }
+      for(const term of current.handoff.context_delta.deprecated)ensure(!context.terms_by_ref.has(term.term_ref),`目标尚未处理废弃术语: ${term.term_ref}`);
+      ensure(Array.isArray(binding.rows),'缺少逐条承接 rows');
+      const known=new Map([...current.indexes.rules.map(x=>[x.rule_id,x]),...current.indexes.scenarios.filter(x=>x.critical).map(x=>[x.scenario_id,x])]);
+      const rows=new Map();for(const row of binding.rows){ensure(!rows.has(row.source_id),`重复承接: ${row.source_id}`);rows.set(row.source_id,row);}
+      const issues=[], blocked=new Set();let all=false;
+      const mark=(id,reason,row)=>{issues.push({source_id:id,reason});if(row?.dependency_status!=='known'||!list(row.dependent_slice_refs))all=true;else row.dependent_slice_refs.forEach(x=>blocked.add(x));};
+      const catalogs=['aggregate_catalog','entity_catalog','value_object_catalog','behavior_catalog','invariant_catalog','state_transition_catalog','domain_event_catalog','gateway_catalog'];
+      const ids=new Set(catalogs.flatMap(k=>(data[k]||[]).flatMap(x=>Object.entries(x).filter(([k])=>k.endsWith('_id')).map(([,v])=>v))));
+      const seams=new Map((data.test_seams||[]).map(x=>[x.seam_id,x]));
+      for(const[id,source]of known){
+        const row=rows.get(id);
+        if(!row){mark(id,'missing-mapping');continue;}
+        ensure(['known','unknown'].includes(row.dependency_status) && Array.isArray(row.dependent_slice_refs),'缺少切片依赖判定');
+        if(row.source_digest!==source.source_digest){mark(id,'stale-source',row);continue;}
+        if(row.disposition==='implemented'){
+          ensure(list(row.tactical_refs)&&row.tactical_refs.every(x=>ids.has(x)),`战术落点悬空: ${id}`);
+          ensure(list(row.test_seam_refs)&&row.test_seam_refs.every(x=>seams.has(x)&&row.tactical_refs.includes(seams.get(x).subject_ref)),`测试 seam 未关联战术落点: ${id}`);
+          if(id.startsWith('scenario.'))ensure(['success','failure'].every(outcome=>(row.scenario_tests||[]).some(x=>x.outcome===outcome&&row.test_seam_refs.includes(x.seam_ref))),`关键场景缺少成功/失败测试: ${id}`);
+          ensure(list(row.evidence_refs),`缺少落实证据: ${id}`);row.evidence_refs.forEach(ref=>safe(root,ref));
+        }else if(row.disposition==='deferred'){
+          for(const key of ['reason','risk','owner','followup_ticket_ref','verification_plan','target_version'])ensure(present(row[key]),`延期缺少 ${key}: ${id}`);
+          mark(id,'deferred',row);
+        }else if(row.disposition==='not-applicable'){
+          ensure(present(row.reason)&&list(row.evidence_refs),`不适用缺少依据: ${id}`);row.evidence_refs.forEach(ref=>safe(root,ref));
+        }else {ensure(['pending','conflict'].includes(row.disposition),`非法承接状态: ${id}`);mark(id,row.disposition,row);}
+      }
+      for(const[id,row]of rows)if(!known.has(id))mark(id,'removed-or-unknown-source',row);
+      for(const key of ['spec_ref','prototype_ref','visual_baseline_ref','business_ticket_set_ref'])if(original.handoff.source[key].digest!==current.handoff.source[key].digest){all=true;issues.push({source_id:key,reason:'upstream-asset-stale'});}
+      // Rule changes can be scoped to declared dependencies. Boundary/decision or
+      // runnable-prototype changes need the tactical contract rebound as a whole.
+      const stageKeys=['package_version','approval','domain_strategy_ref'];
+      if(digest(strategyBasis(original.strategy))!==digest(strategyBasis(current.strategy)) || digest(without(original.stage,stageKeys))!==digest(without(current.stage,stageKeys)) || digest(original.config.prototype)!==digest(current.config.prototype)) {
+        all=true;issues.push({source_id:'strategic-design-basis',reason:'upstream-design-stale'});
+      }
+      const blockedHere=all||(sliceRef?blocked.has(sliceRef):issues.length>0);
+      return {result:blockedHere?'blocked':'verified',bundle_digest:current.manifest.bundle_digest,consumed_bundle_digest:receipt.bundle_digest,tactical_digest:digest(data),scope:sliceRef||'whole-tactical-design',coverage_complete:[...known.keys()].every(id=>rows.has(id)),block_all:all,blocked_slice_refs:[...blocked].sort(),issues};
+    });
+  });
+}

package/template/scripts/lib/strategic-handoff-io.mjs

@@ -0,0 +1,75 @@
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, readdirSync, readFileSync, mkdirSync, writeFileSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { parseDocument } from '../vendor/yaml.mjs';
+export const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+export const ensure = (condition, message) => { if (!condition) throw new TypeError(message); };
+export const canonical = value => Array.isArray(value) ? value.map(canonical) : value && typeof value === 'object' ? Object.fromEntries(Object.keys(value).sort().map(k => [k, canonical(value[k])])) : value;
+export const hash = bytes => `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+export const digest = value => hash(JSON.stringify(canonical(value)));
+export const json = value => `${JSON.stringify(canonical(value), null, 2)}\n`;
+export function parse(bytes) {
+  const doc = parseDocument(String(bytes), { uniqueKeys: true, maxAliasCount: 0 });
+  ensure(!doc.errors.length, `YAML/JSON 无效: ${doc.errors[0]?.message}`);
+  return doc.toJS({ maxAliasCount: 0 });
+}
+export const read = file => parse(readFileSync(file, 'utf8'));
+export function relative(ref) {
+  ensure(typeof ref === 'string' && ref.length > 0 && !/[\\\x00-\x1f:#?]/.test(ref) && !path.posix.isAbsolute(ref) && !ref.split('/').some(x => !x || x === '.' || x === '..') && !/[. ]$/.test(ref), `非法相对路径: ${ref}`);
+  return ref;
+}
+export function safe(root, ref, { missing = false } = {}) {
+  relative(ref);
+  let current = path.resolve(root);
+  ensure(!existsSync(current) || !lstatSync(current).isSymbolicLink(), `根目录不能是 symlink: ${root}`);
+  for (const part of ref.split('/')) {
+    current = path.join(current, part);
+    if (existsSync(current)) ensure(!lstatSync(current).isSymbolicLink(), `禁止 symlink: ${ref}`);
+    else ensure(missing, `文件不可读: ${ref}`);
+  }
+  return current;
+}
+export function files(root, prefix = '') {
+  const base = prefix ? safe(root, prefix) : root;
+  return readdirSync(base).sort().flatMap(name => {
+    const ref = prefix ? `${prefix}/${name}` : name;
+    const full = safe(root, ref), st = lstatSync(full);
+    ensure(st.isFile() || st.isDirectory(), `不支持的文件类型: ${ref}`);
+    return st.isDirectory() ? files(root, ref) : [ref];
+  });
+}
+export const treeDigest = (root, prefix) => digest(files(root, prefix).map(ref => ({ path: path.posix.relative(prefix, ref), sha256: hash(readFileSync(safe(root, ref))) })));
+export function write(root, ref, bytes) {
+  const file = safe(root, ref, { missing: true });
+  mkdirSync(path.dirname(file), { recursive: true }); writeFileSync(file, bytes, { flag: 'wx' });
+}
+export function project(root) {
+  const value = read(safe(root, 'yss-project.yaml'));
+  ensure(value.schema_version === 1 && value.repository_mode === 'project-instance', '只允许 project-instance 导出或导入业务包');
+  return realpathSync(root);
+}
+export function schema(value, ref) {
+  const program = 'import json,sys; from jsonschema import Draft202012Validator; s=json.load(open(sys.argv[1])); v=json.load(sys.stdin); errors=list(Draft202012Validator(s).iter_errors(v)); print("\\n".join(str(e) for e in errors)); sys.exit(bool(errors))';
+  const out = spawnSync('python3', ['-c', program, safe(ROOT, ref)], { input: JSON.stringify(value), encoding: 'utf8', maxBuffer: 4 * 1024 * 1024 });
+  ensure(out.status === 0, `schema 校验失败: ${out.error?.message || out.stdout || out.stderr}`);
+}
+export function archive(command, source, destination) {
+  const out = spawnSync('python3', [path.join(ROOT, 'scripts/lib/strategic-handoff-zip.py'), command, source, destination], { encoding: 'utf8' });
+  ensure(out.status === 0, `ZIP 操作失败: ${out.error?.message || out.stderr}`);
+}
+
+// Preserve the source profile's legacy product-confirmation semantics when a newer
+// receiver no longer has that bucket. This does not change source bytes or gates.
+export function sourceApprovalPolicy(source) {
+  const roles=structuredClone(source);
+  roles.user_decision_policy ||= {gates:[]};
+  const policy=roles.gate_policy;
+  for(const gate of policy.product_digital_human_with_biological_veto || []) {
+    if(!(policy.biological_human||[]).includes(gate) && !(policy.digital_human_review||[]).some(x=>x.gate===gate) && !(policy.dual_digital_human||[]).some(x=>x.gate===gate)) {
+      policy.digital_human_review ||= [];policy.digital_human_review.push({gate,countersigners:['role.product-manager']});
+    }
+  }
+  return roles;
+}

package/template/scripts/lib/strategic-handoff-rules.mjs

@@ -0,0 +1,37 @@
+import { ensure, digest } from './strategic-handoff-io.mjs';
+const nonempty = value => typeof value === 'string' && value.trim();
+const strings = value => Array.isArray(value) && value.length && value.every(nonempty);
+export function extractTraceability(strategy) {
+  ensure(strategy.traceability_version === 1, 'migration-required: 导出前必须补齐 traceability_version: 1、稳定规则 ID 与场景关联并重新批准');
+  ensure(Array.isArray(strategy.rule_catalog) && strategy.rule_catalog.length, 'rule_catalog 不能为空');
+  const contexts = new Set((strategy.contexts || []).map(x => x.context_id));
+  const rules = new Map(), scenarios = new Map(), used = new Set();
+  for (const rule of strategy.rule_catalog) {
+    ensure(/^rule\.[a-z0-9][a-z0-9-]*$/.test(rule.rule_id) && !rules.has(rule.rule_id), `规则 ID 无效或重复: ${rule.rule_id}`);
+    ensure(nonempty(rule.statement) && contexts.has(rule.responsible_context) && rule.status === 'confirmed', `规则未确认或责任区无效: ${rule.rule_id}`);
+    rules.set(rule.rule_id, { ...rule, source_digest: digest(rule) });
+  }
+  ensure(Array.isArray(strategy.scenarios) && strategy.scenarios.length, 'scenarios 不能为空');
+  for (const scenario of strategy.scenarios) {
+    const id = scenario.scenario_id;
+    ensure(/^scenario\.[a-z0-9][a-z0-9-]*$/.test(id) && !scenarios.has(id), `场景 ID 无效或重复: ${id}`);
+    ensure(scenario.status === 'confirmed' && typeof scenario.critical === 'boolean' && contexts.has(scenario.responsible_context), `场景必须已确认并明确 critical 与责任区: ${id}`);
+    ensure(strings(scenario.rule_refs) && new Set(scenario.rule_refs).size === scenario.rule_refs.length, `场景缺少唯一 rule_refs: ${id}`);
+    ensure(strings(scenario.commands) && strings(scenario.success_results) && strings(scenario.failure_results), `场景缺成功/失败路径: ${id}`);
+    for (const ref of scenario.rule_refs) { ensure(rules.has(ref), `场景规则悬空: ${ref}`); used.add(ref); }
+    ensure(JSON.stringify([...(scenario.rules || [])].sort()) === JSON.stringify(scenario.rule_refs.map(ref => rules.get(ref).statement).sort()), `场景规则正文与 rule_refs 不一致: ${id}`);
+    scenarios.set(id, { ...scenario, source_digest: digest(scenario) });
+  }
+  for (const inv of strategy.invariants || []) {
+    ensure(rules.has(inv.rule_ref) && rules.get(inv.rule_ref).statement === inv.statement, `不变量必须关联一致的源规则: ${inv.invariant_id}`);
+    ensure(strings(inv.scenario_refs) && inv.scenario_refs.every(ref => scenarios.has(ref) && scenarios.get(ref).rule_refs.includes(inv.rule_ref)), `不变量场景引用未覆盖规则: ${inv.invariant_id}`);
+    used.add(inv.rule_ref);
+  }
+  ensure([...rules.keys()].every(ref => used.has(ref)), '存在未关联场景/不变量的规则');
+  return { rules: [...rules.values()].sort((a,b) => a.rule_id.localeCompare(b.rule_id)), scenarios: [...scenarios.values()].sort((a,b) => a.scenario_id.localeCompare(b.scenario_id)) };
+}
+export function compareIndexes(current, previous) {
+  const index = data => new Map([...data.rules.map(x => [x.rule_id, x.source_digest]), ...data.scenarios.map(x => [x.scenario_id, x.source_digest])]);
+  const now = index(current), old = index(previous || { rules: [], scenarios: [] });
+  return { added: [...now.keys()].filter(k => !old.has(k)).sort(), updated: [...now.keys()].filter(k => old.has(k) && now.get(k) !== old.get(k)).sort(), removed: [...old.keys()].filter(k => !now.has(k)).sort() };
+}

package/template/scripts/lib/strategic-handoff-zip.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+"""ZIP transport only; no package-supplied code is executed."""
+import os, stat, sys, zipfile
+from pathlib import Path, PurePosixPath
+MAX_BYTES = 512 * 1024 * 1024
+MAX_FILES = 20000
+
+def checked(name):
+    if not name or '\\' in name or ':' in name or any(ord(c) < 32 for c in name) or name.startswith('/') or any(p in ('', '.', '..') for p in name.split('/')):
+        raise ValueError('invalid ZIP path: ' + name)
+    return name
+
+def main():
+    command, source, destination = sys.argv[1:]
+    source, destination = Path(source), Path(destination)
+    if command == 'pack':
+        with zipfile.ZipFile(destination, 'x', compression=zipfile.ZIP_DEFLATED) as z:
+            for file in sorted(source.rglob('*')):
+                if file.is_symlink(): raise ValueError('symlink is forbidden')
+                if not file.is_file(): continue
+                info = zipfile.ZipInfo(checked(file.relative_to(source).as_posix()), (1980, 1, 1, 0, 0, 0))
+                info.external_attr = (stat.S_IFREG | 0o644) << 16
+                info.compress_type = zipfile.ZIP_DEFLATED
+                z.writestr(info, file.read_bytes())
+    elif command == 'unpack':
+        with zipfile.ZipFile(source) as z:
+            entries = z.infolist()
+            if len(entries) > MAX_FILES or sum(i.file_size for i in entries) > MAX_BYTES: raise ValueError('ZIP size limit')
+            seen = set()
+            for item in entries:
+                name = checked(item.filename)
+                folded = name.casefold()
+                if folded in seen: raise ValueError('duplicate/case-colliding ZIP entry')
+                seen.add(folded)
+                mode = item.external_attr >> 16
+                if item.is_dir() or stat.S_ISLNK(mode) or (stat.S_IFMT(mode) not in (0, stat.S_IFREG)): raise ValueError('only regular files allowed')
+                if item.flag_bits & 1: raise ValueError('encrypted ZIP not supported')
+            for item in entries:
+                file = destination.joinpath(*PurePosixPath(item.filename).parts)
+                file.parent.mkdir(parents=True, exist_ok=True)
+                with file.open('xb') as out, z.open(item) as incoming:
+                    total = 0
+                    while chunk := incoming.read(1024 * 1024):
+                        total += len(chunk)
+                        if total > item.file_size or total > MAX_BYTES: raise ValueError('ZIP expanded size limit')
+                        out.write(chunk)
+    else: raise ValueError('unknown ZIP command')
+if __name__ == '__main__':
+    try: main()
+    except Exception as error:
+        print(str(error), file=sys.stderr)
+        sys.exit(1)