create-yss-spec 3.4.10 → 3.5.2

package/template/.cursor/skills/yss-implementation-contract-compiler/references/compiler-contract.yaml

@@ -2,12 +2,12 @@ schema_version: 2
 slice_contract_versions:
   default: 3
   accepted: [2, 3]
-  v3_schema: docs/process/schemas/slice-implementation-contract-v3.schema.json
+  v3_schema: .template-spec/process/schemas/slice-implementation-contract-v3.schema.json
   normalization: scripts/lib/slice-contract.mjs
   v2_migration: explicit-new-draft-no-inherited-approval
 backend_architecture:
-  registry_source: docs/agents/yss-skill-registry.yaml
-  identity_schema: docs/process/schemas/backend-architecture-identity.schema.json
+  registry_source: .template-spec/agents/yss-skill-registry.yaml
+  identity_schema: .template-spec/process/schemas/backend-architecture-identity.schema.json
   required_evidence: [engineering_baseline, repository_registration, manifest]
   evidence_loading: original-references-and-raw-sha256
   existing_identity: {schema_version: 2, source_kind: existing-registration, profiles_source: existing_project_profiles}
@@ -18,8 +18,8 @@ backend_architecture:
   readiness: supported-profile-and-current-identical-evidence
 compiled_by: yss-implementation-contract-compiler
 approved_by: yss-product-lifecycle
-capability_source: docs/agents/yss-skill-registry.yaml
-recipe_source: docs/agents/yss-skill-registry.yaml
+capability_source: .template-spec/agents/yss-skill-registry.yaml
+recipe_source: .template-spec/agents/yss-skill-registry.yaml
 digest_algorithm: sha256
 unsupported_inputs:
   registry_schema_v1: reject-with-migration-guidance
@@ -73,7 +73,7 @@ readiness:
   cross_repo: [repository_registry, delivery_order, integration_verification, rollback_order]
   frontend_delivery:
     when: specialized-frontend-profile-or-explicit-frontend-delivery-binding
-    source: docs/process/frontend-backend-delivery.md
+    source: .template-spec/process/frontend-backend-delivery.md
     verifier: scripts/verify-frontend-delivery
     output_binding: frontend.delivery
     inputs_verified_is_implementation_approval: false
@@ -146,7 +146,7 @@ resolution_contract:
   component_bindings:
     when: any-required-capability-provider-kind-is-yss-component
     platform_configuration: required-v2
-    catalog_source: docs/engineering/backend-platforms.json
+    catalog_source: .template-spec/engineering/backend-platforms.json
     required_fields: [component_bindings, component_bindings_digest]
     exact_artifact_binding: [group_id, artifact_id, declared_version, resolved_version, pom_sha256, jar_sha256, source_tree]
     digest_change_status: stale
@@ -159,7 +159,7 @@ context_plan:
 
 project_scaffold_contract_schema:
   schema_version: 4
-  schema_ref: docs/process/schemas/project-scaffold-contract.schema.json
+  schema_ref: .template-spec/process/schemas/project-scaffold-contract.schema.json
   identity: project-engineering-baseline
   discriminant: delivery_role
   delivery_roles:
@@ -440,7 +440,7 @@ strategic_handoff_consumption:
 
 backend_platform_contract:
   schema_version: 2
-  catalog_ref: docs/engineering/backend-platforms.json
+  catalog_ref: .template-spec/engineering/backend-platforms.json
   configuration_field: platform_configuration
   selection_owner: yss-product-lifecycle
   new_generation_requires: [exact-boot-java, confirmed-decision, matching-yss-coordinates, verified-compatibility-entry]

package/template/.cursor/skills/yss-implementation-contract-compiler/references/slice-implementation-contract-v2.md

@@ -4,11 +4,11 @@
 
 # Slice Implementation Contract
 
-后端合同还必须绑定 `architecture_identity`（schema 见 `docs/process/schemas/backend-architecture-identity.schema.json`），并与工程基线、登记和 Manifest 一致。将同一身份复制到 `resolution`、backend 工作单元和执行结果；Profile 的成熟度/Recipe 来源是技能注册表，draft 不得 ready-for-agent。旧 backend.domain-behavior/persistence-mybatis/http-api Recipe 只读退役，重新编译时显式选择 backend.ddd-* 或 backend.mvc-*。
+后端合同还必须绑定 `architecture_identity`（schema 见 `.template-spec/process/schemas/backend-architecture-identity.schema.json`），并与工程基线、登记和 Manifest 一致。将同一身份复制到 `resolution`、backend 工作单元和执行结果；Profile 的成熟度/Recipe 来源是技能注册表，draft 不得 ready-for-agent。旧 backend.domain-behavior/persistence-mybatis/http-api Recipe 只读退役，重新编译时显式选择 backend.ddd-* 或 backend.mvc-*。
 
 `yss-implementation-contract-compiler` 生成草案；`yss-product-lifecycle` 核验、批准并持久化。合同缺少必填字段时状态为 `blocked`。schema v1 已停止支持，必须重新编译为 v2，不提供自动升级。
 
-采用专职前端 profile 时，`frontend.delivery` 绑定 `{acceptance_ref, digest}`，来自 `scripts/verify-frontend-delivery` 的当前结果；也可由 `resolution.frontend_delivery` 承载，两处并存时必须一致。正式执行从持久化合同读取并重验输入。细则见 `docs/process/frontend-backend-delivery.md`。
+采用专职前端 profile 时，`frontend.delivery` 绑定 `{acceptance_ref, digest}`，来自 `scripts/verify-frontend-delivery` 的当前结果；也可由 `resolution.frontend_delivery` 承载，两处并存时必须一致。正式执行从持久化合同读取并重验输入。细则见 `.template-spec/process/frontend-backend-delivery.md`。
 
 ```yaml
 slice_contract:
@@ -55,7 +55,7 @@ slice_contract:
     recipe_ids: []
     conditions: []
     reason_chains: {}
-    registry_digest: # sha256 of normalized docs/agents/yss-skill-registry.yaml
+    registry_digest: # sha256 of normalized .template-spec/agents/yss-skill-registry.yaml
     compiler_contract_digest: # sha256 of normalized compiler-contract.yaml
     compiled_at:
     freshness: current # digest 变化后为 stale

package/template/.cursor/skills/yss-implementation-contract-compiler/references/slice-implementation-contract.md

@@ -2,7 +2,7 @@
 
 YAML 是唯一权威合同。Agent 从已确认上游整理草案；用户确认目标、范围、验收和关键取舍；独立专业审查核验工程约束，生命周期主控关闭 `gate.slice-contract-approved`。新合同使用 schema v3；[v2](slice-implementation-contract-v2.md) 保留原规则读取和校验，schema v1 继续拒绝。
 
-结构权威为 `docs/process/schemas/slice-implementation-contract-v3.schema.json`。Registry、编译规则与 Execution Result 继续使用各自版本；Slice v3 不要求它们一同升级。
+结构权威为 `.template-spec/process/schemas/slice-implementation-contract-v3.schema.json`。Registry、编译规则与 Execution Result 继续使用各自版本；Slice v3 不要求它们一同升级。
 
 ## 只保存一次
 

package/template/.cursor/skills/yss-implementation-contract-compiler/references/strategic-handoff-routing.md

@@ -1,6 +1,6 @@
 ## 战略交接快照包
 
-跨仓交接使用 `scripts/strategic-handoff export / verify / import`。正式导出前补齐源战略的稳定规则 ID、关键场景和当前批准绑定；源资产原字节冻结、包内路径通过清单解析。目标导入只产生快照和对账/承接草案，正式 reconciliation 通过后才能进入战术设计。流程与字段见 `docs/process/strategic-handoff-package.md`。
+跨仓交接使用 `scripts/strategic-handoff export / verify / import`。正式导出前补齐源战略的稳定规则 ID、关键场景和当前批准绑定；源资产原字节冻结、包内路径通过清单解析。目标导入只产生快照和对账/承接草案，正式 reconciliation 通过后才能进入战术设计。流程与字段见 `.template-spec/process/strategic-handoff-package.md`。
 
 来自战略交接包的技术设计合同（DDD / MVC）必须绑定 `strategic_handoff` 导入收据、包摘要、正式目标对账及逐条承接 rows。来自导入包时禁止仅填 `upstream_current: true`。批准前执行 `scripts/verify-strategic-handoff-consumption --root <target> <tactical>`；存在受控延期时按切片执行 `--slice <slice-id>`，实际核验通过且合同批准后才可继续相关切片。最新源规则、关键场景或资产变化使依赖项 stale；未知依赖扩大阻断，业务冲突回交战略方。结果绑定当前包与战术摘要，不能复用旧输出宣布 ready-for-agent。
 

package/template/.cursor/skills/yss-layered-mvc-scaffold-generator/SKILL.md

@@ -11,7 +11,7 @@ description: 在生命周期已批准的脚手架合同下生成通用 YSS 分
 
 - backend `scaffold_status=required`，目标目录已确认且不存在。
 - `scaffold-architecture-decisions.yaml` 中对应项目已达到 `lifecycle-approved`，确认架构为 `layered-mvc`。
-- `yss-implementation-contract-compiler` 已编译统一 Project Scaffold Contract schema v4，并绑定批准且当前的 Technical Design、Data Architecture Decision v1、API Contract Decision v1 和真实工程合同批准记录。API `required` 时 Draft、Validation、独立 Review、Freeze 与工程批准必须绑定同一 OpenAPI YAML 字节；`not-applicable` 时必须有评估、原因和证据且不得携带占位资产。合同须由生命周期批准并持久化。
+- `yss-implementation-contract-compiler` 已编译统一 Project Scaffold Contract schema v4，并绑定批准且当前的 Technical Design、Data Architecture Decision v1、API Contract Decision（新建 v2；历史 v1 只读兼容，准备与迁移见 `.template-spec/process/contract-reading.md`） 和真实工程合同批准记录。API `required` 时 Draft、Validation、独立 Review、Freeze 与工程批准必须绑定同一 OpenAPI YAML 字节；`not-applicable` 时必须有评估、原因和证据且不得携带占位资产。合同须由生命周期批准并持久化。
 - 合同中的 `decision_id`、文件 digest、Profile、能力闭包、写路径和验证命令仍为当前版本。
 
 任一条件缺失时返回 `blocked`。本生成器无交互、无默认回退；用户选择由 `yss-product-lifecycle` 在 `work-unit.technical-analysis` 的工程基线内完成。
@@ -27,7 +27,7 @@ description: 在生命周期已批准的脚手架合同下生成通用 YSS 分
 - Spring MVC、Servlet、Validation、Jackson 和 starter 坐标消费共享平台清单；Java 下限和允许组合由当前平台条目决定。Jakarta 转换不包括 `javax.sql` 等 Java SE API。
 - 平台候选维护验证产物标记 `platform_verification=candidate`，不能交给业务生成、升级完成等级或进入首切片验证。测试夹具不证明 YSS 兼容。
 
-版本清单、合同字段、候选验证和支持晋级规则见 仓库共享合同 `docs/engineering/backend-platforms.md`。
+版本清单、合同字段、候选验证和支持晋级规则见 仓库共享合同 `.template-spec/engineering/backend-platforms.md`。
 
 ## 架构与 Profile
 

package/template/.cursor/skills/yss-layered-mvc-scaffold-generator/scripts/data-analysis-profile.mjs

@@ -32,7 +32,7 @@ async function sharedTools(outputDir, contract) {
   }
   const staging = await mkdtemp(path.join(outputDir, ".skillUtils.staging-"));
   try {
-    for (const relative of [".agents/skills", ".codex/skills", ".cursor/skills", ".pi/skills", "scripts", "docs/agents", "docs/process", "AGENTS.md", "skills-lock.json"]) {
+    for (const relative of [".agents/skills", ".codex/skills", ".cursor/skills", ".pi/skills", "scripts", ".template-spec/agents", ".template-spec/process", "AGENTS.md", "skills-lock.json"]) {
       await mkdir(path.dirname(path.join(staging, relative)), { recursive: true });
       await cp(path.join(REPOSITORY_ROOT, relative), path.join(staging, relative), { recursive: true });
     }
@@ -55,7 +55,7 @@ export async function finalizeDataAnalysisProfile({ projectRoot, contract, archi
   if (digest(context) !== contract.context_handoff_digest || !/^---\r?\ncontext_schema_version: 1\r?\n---/m.test(context.toString())) throw new Error("CONTEXT handoff schema/digest 不匹配");
   if (spawnSync("git", ["--version"]).status !== 0) throw new Error("Git 不可用");
 
-  for (const relative of ["docs/agents", "docs/process", "docs/templates", "docs/architecture/templates"]) {
+  for (const relative of [".template-spec/agents", ".template-spec/process", ".template-spec/templates", ".template-spec/architecture/templates"]) {
     await mkdir(path.dirname(path.join(projectRoot, relative)), { recursive: true });
     await cp(path.join(REPOSITORY_ROOT, relative), path.join(projectRoot, relative), { recursive: true });
   }
@@ -73,9 +73,9 @@ export async function finalizeDataAnalysisProfile({ projectRoot, contract, archi
   }
   const lockDigest = await sharedTools(path.resolve(options.outputDir), contract);
   await put(path.join(projectRoot, "skills-lock.json"), JSON.stringify({ version: 1, distribution: { mode: "sibling-directory", skillUtilsDir: "../skillUtils", required: true, compatibility: "skill-utils-v1", lock_digest: lockDigest } }, null, 2));
-  await put(path.join(projectRoot, "docs/process/engineering-baseline.json"), JSON.stringify({ schema_version: 1, architecture_identity: architectureIdentity, platform_profile: contract.profiles.platform, scaffold_completion: "generated" }, null, 2));
-  await put(path.join(projectRoot, "docs/process/implementation-repo-registry.yaml"), JSON.stringify({ schema_version: 1, projects: [{ project_type: "backend", project_name: options.projectName, project_root: ".", git_root: ".", repository_scope: "external-repository", scaffold_status: "initialized", default_branch: "main", architecture_identity: architectureIdentity, allowed_write_paths: ["."], verification_commands: contract.verification_commands, expected_evidence_files: contract.expected_evidence_files, ci: "not-configured", rollback_point: "initial-empty-repository" }] }, null, 2));
-  await put(path.join(projectRoot, "docs/process/service-initialization.json"), JSON.stringify({ work_unit: "work-unit.service-project-initialization", context_handoff_ref: contract.context_handoff_ref, context_handoff_digest: contract.context_handoff_digest, contract_id: contract.contract_id, architecture_identity: architectureIdentity, status: "generated" }, null, 2));
+  await put(path.join(projectRoot, ".template-spec/process/engineering-baseline.json"), JSON.stringify({ schema_version: 1, architecture_identity: architectureIdentity, platform_profile: contract.profiles.platform, scaffold_completion: "generated" }, null, 2));
+  await put(path.join(projectRoot, ".template-spec/process/implementation-repo-registry.yaml"), JSON.stringify({ schema_version: 1, projects: [{ project_type: "backend", project_name: options.projectName, project_root: ".", git_root: ".", repository_scope: "external-repository", scaffold_status: "initialized", default_branch: "main", architecture_identity: architectureIdentity, allowed_write_paths: ["."], verification_commands: contract.verification_commands, expected_evidence_files: contract.expected_evidence_files, ci: "not-configured", rollback_point: "initial-empty-repository" }] }, null, 2));
+  await put(path.join(projectRoot, ".template-spec/process/service-initialization.json"), JSON.stringify({ work_unit: "work-unit.service-project-initialization", context_handoff_ref: contract.context_handoff_ref, context_handoff_digest: contract.context_handoff_digest, contract_id: contract.contract_id, architecture_identity: architectureIdentity, status: "generated" }, null, 2));
   await put(path.join(projectRoot, ".gitignore"), "target/\n**/target/\n.idea/\n*.iml\n.env\n.env.*\n.local/");
   const git = spawnSync("git", ["init", "--initial-branch=main"], { cwd: projectRoot, encoding: "utf8" });
   if (git.status !== 0) throw new Error(`Git 初始化失败: ${git.stderr}`);

package/template/.cursor/skills/yss-layered-mvc-scaffold-generator/scripts/generate_scaffold.mjs

@@ -166,7 +166,7 @@ export async function validateContract(options, skillId, architectureProfile, pl
     if (contract.init_git !== true) fail("mvc-data-analysis-v1 必须由合同显式要求独立 Git 初始化");
     if (!contract.context_handoff_ref || !contract.context_handoff_digest) fail("mvc-data-analysis-v1 缺少批准的 CONTEXT handoff");
   }
-  validateJsonSchema(contract, path.join(REPOSITORY_ROOT, "docs/process/schemas/project-scaffold-contract.schema.json"), { label: "Project Scaffold Contract v4" });
+  validateJsonSchema(contract, path.join(REPOSITORY_ROOT, ".template-spec/process/schemas/project-scaffold-contract.schema.json"), { label: "Project Scaffold Contract v4" });
   const required = ["contract_id", "contract_version", "scaffold_request_id", "status", "compiler_draft_ref", "lifecycle_approval_ref", "persisted_ref", "current_version", "implementation_repository", "backend_repository", "scaffold_status", "project_name", "target_output_dir", "base_package", "architecture_family", "generator_skill", "decision_ref", "decision_id", "decision_digest", "maven_coordinates", "profiles", "module_profile", "allowed_write_paths", "expected_evidence_files", "verification_commands", "approval", "work_unit", "generation_policy"];
   const missing = required.filter((field) => !isPresent(contract[field]));
   if (missing.length) fail(`脚手架合同缺少字段: ${missing.join(", ")}`);
@@ -319,7 +319,7 @@ export async function generate(options, { skillId = SKILL_ID, architectureProfil
       verification_commands: COMMANDS,
       generator: { id: skillId, template_digest: await treeDigest(SKILL_ROOT) },
       ownership: { generated_files: generatedFiles, user_owned_globs: ["**/src/main/java/**", "**/src/test/java/**", "db/**"] },
-      readiness: { downstream_skills: downstream, contracts: { architecture_profiles: rawSha256(await readFile(path.join(REPOSITORY_ROOT, "docs/agents/backend-architecture-profiles.md"))), compiler_contract: rawSha256(await readFile(path.join(REPOSITORY_ROOT, ".agents/skills/yss-implementation-contract-compiler/references/compiler-contract.yaml"))) }, architecture_ruleset: rawSha256(await readFile(path.join(projectRoot, architectureRuleset))) },
+      readiness: { downstream_skills: downstream, contracts: { architecture_profiles: rawSha256(await readFile(path.join(REPOSITORY_ROOT, ".template-spec/agents/backend-architecture-profiles.md"))), compiler_contract: rawSha256(await readFile(path.join(REPOSITORY_ROOT, ".agents/skills/yss-implementation-contract-compiler/references/compiler-contract.yaml"))) }, architecture_ruleset: rawSha256(await readFile(path.join(projectRoot, architectureRuleset))) },
       generated_at: new Date().toISOString()
     };
     await put(projectRoot, ".yss/scaffold-generation.json", JSON.stringify(manifest, null, 2));

package/template/.cursor/skills/yss-layered-mvc-scaffold-generator/scripts/scaffold-generator.test.mjs

@@ -8,6 +8,7 @@ import path from "node:path";
 import test from "node:test";
 import { fileURLToPath } from "node:url";
 import { attachDesignPrerequisites } from "../../../../scripts/fixtures/backend-scaffold/design-prerequisites.mjs";
+import { validateNextRoute } from "../../../../scripts/lib/lifecycle-transition.mjs";
 
 const script = path.join(path.dirname(fileURLToPath(import.meta.url)), "generate_scaffold.mjs");
 const digest = (value) => `sha256:${createHash("sha256").update(value).digest("hex")}`;
@@ -80,8 +81,27 @@ test("数据分析初始化生成 H2 六模块和独立治理信封", async (t)
   data.contract.context_handoff_ref = "context-handoff.md";
   data.contract.context_handoff_digest = digest(context);
   await writeFile(data.contractFile, JSON.stringify(data.contract));
+  const contractBytes = await readFile(data.contractFile);
+  const state = { service_project_initialization: {
+    project_id: "demo-service", contract_ref: data.contractFile, contract_digest: digest(contractBytes),
+    project_root: data.project, context_handoff_digest: digest(context)
+  } };
+  const edge = (from, to, value = state) => validateNextRoute(from, to, value, { root: data.root });
+  assert.equal(edge("work-unit.implementation-repository-preparation", "work-unit.service-project-initialization").result, "allowed", JSON.stringify(edge("work-unit.implementation-repository-preparation", "work-unit.service-project-initialization")));
+  const missingContract = structuredClone(state); missingContract.service_project_initialization.contract_ref = path.join(data.root, "missing-contract.json");
+  assert.equal(edge("work-unit.implementation-repository-preparation", "work-unit.service-project-initialization", missingContract).result, "blocked");
+  const changedContract = structuredClone(state); changedContract.service_project_initialization.contract_digest = digest("stale");
+  assert.equal(edge("work-unit.implementation-repository-preparation", "work-unit.service-project-initialization", changedContract).result, "blocked");
+  const approvedContract = structuredClone(data.contract);
+  data.contract.design_prerequisites.engineering_contract_approval_ref = "missing-approval.json";
+  await writeFile(data.contractFile, JSON.stringify(data.contract));
+  const missingApproval = structuredClone(state); missingApproval.service_project_initialization.contract_digest = digest(await readFile(data.contractFile));
+  assert.equal(edge("work-unit.implementation-repository-preparation", "work-unit.service-project-initialization", missingApproval).result, "blocked");
+  await writeFile(data.contractFile, JSON.stringify(approvedContract));
+  assert.equal(edge("work-unit.service-project-initialization", "work-unit.implementation-repository-preparation").result, "blocked");
   const result = spawnSync(process.execPath, [path.resolve(path.dirname(script), "../../../../scripts/fixtures/backend-scaffold/generate-candidate.mjs"), script, ...data.args], { encoding: "utf8" });
   assert.equal(result.status, 0, result.stderr);
+  assert.equal(edge("work-unit.implementation-repository-preparation", "work-unit.service-project-initialization").result, "blocked", "重复初始化不得放行");
   const manifest = JSON.parse(await readFile(path.join(data.project, ".yss/scaffold-generation.json"), "utf8"));
   assert.equal(manifest.architecture_identity.architecture_profile, "mvc-data-analysis-v1");
   assert.equal(manifest.generator_skill, "yss-layered-mvc-scaffold-generator");
@@ -89,6 +109,28 @@ test("数据分析初始化生成 H2 六模块和独立治理信封", async (t)
   await stat(path.join(data.project, ".git"));
   await stat(path.join(data.output, "skillUtils/skills-lock.json"));
   assert.ok(!manifest.ownership.generated_files.some((entry) => entry.path.startsWith(".git/")));
+  const manifestRef = path.join(data.project, ".yss/scaffold-generation.json");
+  const verificationRef = path.join(data.root, "scaffold-verification.json");
+  const resultRef = path.join(data.root, "service-result.json");
+  manifest.completion_level = "empty-scaffold-verified";
+  await writeFile(manifestRef, JSON.stringify(manifest));
+  const commands = [];
+  for (const phase of ["validate", "test", "package"]) {
+    const stdout_ref = path.join(data.root, `${phase}.stdout.log`), stderr_ref = path.join(data.root, `${phase}.stderr.log`);
+    await writeFile(stdout_ref, "synthetic route fixture"); await writeFile(stderr_ref, "");
+    commands.push({ phase, command: `./mvnw ${phase}`, exit_code: 0, stdout_ref, stderr_ref });
+  }
+  await writeFile(verificationRef, JSON.stringify({ status: "passed", completion_level: "empty-scaffold-verified", project_root: data.project, commands }));
+  await writeFile(resultRef, JSON.stringify({ result_schema: "workflow-execution-result-v1", work_unit: "work-unit.service-project-initialization", result: "completed", evidence_refs: [manifestRef, verificationRef] }));
+  Object.assign(state.service_project_initialization, { manifest_ref: manifestRef, verification_ref: verificationRef, result_ref: resultRef });
+  assert.equal(edge("work-unit.service-project-initialization", "work-unit.implementation-repository-preparation").result, "allowed");
+  const stale = structuredClone(state); stale.service_project_initialization.context_handoff_digest = digest("stale");
+  assert.equal(edge("work-unit.service-project-initialization", "work-unit.implementation-repository-preparation", stale).result, "blocked");
+  commands[0].exit_code = 1; await writeFile(verificationRef, JSON.stringify({ status: "passed", completion_level: "empty-scaffold-verified", project_root: data.project, commands }));
+  assert.equal(edge("work-unit.service-project-initialization", "work-unit.implementation-repository-preparation").result, "blocked", "Wrapper 非零退出不得放行");
+  commands[0].exit_code = 0;
+  commands.pop(); await writeFile(verificationRef, JSON.stringify({ status: "passed", completion_level: "empty-scaffold-verified", project_root: data.project, commands }));
+  assert.equal(edge("work-unit.service-project-initialization", "work-unit.implementation-repository-preparation").result, "blocked", "缺失 Wrapper 命令不得放行");
   const core = await readFile(path.join(data.project, "demo-service-core/pom.xml"), "utf8");
   assert.doesNotMatch(core, /demo-service-client|spring-web|ojdbc|mysql-connector/);
 });

package/template/.cursor/skills/yss-mybatis/SKILL.md

@@ -33,6 +33,18 @@ description: 用于 YSS MyBatis / MyBatis-Plus 组件能力核验、接入决策
 <!-- yss-rule {"id":"mybatis.transaction","when":"mybatis","level":"mandatory","evidence":"code-and-verification"} -->
 - 事务边界归批准的 Application 用例或 MVC service/core；Repository 不临时声明新的业务事务。
 
+## 能力选择记录
+
+| 既有工程调用 seam | 选择与核验 |
+|---|---|
+| `PageQuery` 经组件切面进入 Repository/Gateway | 核对代理切点、参数位置、PageHelper 开关、实际 SQL 与 `tempTotalCount`；不能因 Bean 注册就认定切面命中。 |
+| Mapper 使用 MyBatis-Plus `IPage` | 核对 MP 分页开关、方言、实际 SQL 与 total；同一次查询不得叠加 PageHelper 上下文。两插件都注册不等于查询已双分页。 |
+| 原生 Mapper/Example/ListMapper | 按当前源码和实体映射选择 `BaseRepository<T,D>`；与完整 MP `BasePlusRepository<T>` 不可直接互换，混用或复合键须验证主键方法、XML 与映射。 |
+| SQL 级批量写入 | 核对公开入口、分片大小、目标方言生成的单批 SQL、审计填充和 ID；多个分片整体回滚由上层用例事务保证。若 batch size 存在进程级可变状态，多 Spring Context 不得据此宣称配置隔离。 |
+| 命名数据源 | Holder 中有多个 DataSource 不证明动态路由；记录实际 Mapper 的 `SqlSessionFactory`/DataSource、主池与自建池所有权，以及事务绑定。 |
+
+以上仅对命中的能力记录，不改变两套分页插件的当前默认注册行为；选择由批准 Profile、消费工程配置和运行测试共同证明。
+
 ## 任务分流
 
 | 请求 | 本 Skill 动作 | 后续路由 |
@@ -48,8 +60,8 @@ description: 用于 YSS MyBatis / MyBatis-Plus 组件能力核验、接入决策
 2. 装配与开关：自动配置、条件属性、Mapper 扫描和 XML location 是否真实生效。
 3. 调用 seam：代理是否命中、分页参数位置/类型、分页插件链和 total 回填责任。
 4. 映射：接口签名、XML namespace、resultMap、字段、逻辑删除和主键策略。
-5. 批量：是否调用当前公开批量入口、分批与方言是否匹配、是否退化为循环单条。
-6. 数据源：先确认组件只提供了什么，再检查上层路由与事务进入顺序；不得假设存在当前线程数据源上下文。
+5. 批量：是否调用当前公开批量入口、分批与方言是否匹配、是否退化为循环单条；核对 batch size 在多个应用上下文中的作用域。
+6. 数据源：先确认组件只提供了什么，再检查 Mapper 实际绑定的会话工厂、上层路由与事务进入顺序；不得假设存在当前线程数据源上下文。
 7. 最后检查 SQL、绑定参数、数据库方言与执行计划。
 
 ## Review 输入

package/template/.cursor/skills/yss-openapi-draft-review/SKILL.md

@@ -5,7 +5,7 @@ description: "审查 YSS OpenAPI Draft 的需求覆盖、页面动作、响应
 
 # YSS OpenAPI Draft Review
 
-已有生命周期资产优先用 `scripts/contract view <资产> --kind <类型>` 阅读；执行任务用 `--profile task --unit <ID>`，绑定与校验明细用 `--profile full`。视图不授予执行权限，仍按本 Skill 的原始来源和批准门禁处理。类型、准备和迁移见 `docs/process/contract-reading.md`。
+已有生命周期资产优先用 `scripts/contract view <资产> --kind <类型>` 阅读；执行任务用 `--profile task --unit <ID>`，绑定与校验明细用 `--profile full`。视图不授予执行权限，仍按本 Skill 的原始来源和批准门禁处理。类型、准备和迁移见 `.template-spec/process/contract-reading.md`。
 
 Use this skill after OpenAPI Draft creation and before Engineering Baseline / YSS DDD Review. It is a fail-closed contract review skill for design-time OpenAPI files under `docs/.scratch/<feature>/api/`; it does not bundle JSON or generate Orval clients.
 
@@ -96,4 +96,4 @@ Block if any of these are true:
 
 `Review Result` 只有在 `Structural Validation` 与 `Semantic Review` 均为 `Passed` 时才能是 `Approved`；不使用 `Conditionally Approved` 或 `Semantic Approved` 作为顶层结论。
 
-Prefer `docs/api/templates/openapi-draft-review-checklist.md` when a tabular checklist is useful.
+Prefer `.template-spec/api/templates/openapi-draft-review-checklist.md` when a tabular checklist is useful.

package/template/.cursor/skills/yss-openapi-governance/SKILL.md

@@ -5,7 +5,7 @@ description: "维护、校验、冻结或导出 YSS OpenAPI 3.1 设计合同；
 
 # YSS OpenAPI Governance
 
-已有生命周期资产优先用 `scripts/contract view <资产> --kind <类型>` 阅读；执行任务用 `--profile task --unit <ID>`，绑定与校验明细用 `--profile full`。视图不授予执行权限，仍按本 Skill 的原始来源和批准门禁处理。类型、准备和迁移见 `docs/process/contract-reading.md`。
+已有生命周期资产优先用 `scripts/contract view <资产> --kind <类型>` 阅读；执行任务用 `--profile task --unit <ID>`，绑定与校验明细用 `--profile full`。视图不授予执行权限，仍按本 Skill 的原始来源和批准门禁处理。类型、准备和迁移见 `.template-spec/process/contract-reading.md`。
 
 本 skill 负责 YSS OpenAPI 的 **YAML-first** 工作流：
 
@@ -17,11 +17,11 @@ Spec / 设计输入 → OpenAPI YAML Draft → 审查与 Freeze → JSON 派生
 
 YSS DTO 的可复用 HTTP/JSON 映射由 `.agents/skills/yss-dto/references/openapi-wire-profile.yaml` 单一维护。它描述公开 wire shape，不是 Java 字段或 getter 清单；本 skill 必须消费 profile，不能在治理文档、feature YAML 和 JSON 中各自发明 `SingleResult`、`PageResult` 或 `PageQuery` 字段表。
 
-文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `docs/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
+文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `.template-spec/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
 
 ## 文档写作
 
-编写接口说明和契约评审交接正文前，读取 `docs/process/document-writing.md` 的共用写法及工程契约指引；协议标识、schema、冻结状态和验证记录按原合同保存。
+编写接口说明和契约评审交接正文前，读取 `.template-spec/process/document-writing.md` 的共用写法及工程契约指引；协议标识、schema、冻结状态和验证记录按原合同保存。
 
 ## 边界与职责
 
@@ -34,7 +34,7 @@ YSS DTO 的可复用 HTTP/JSON 映射由 `.agents/skills/yss-dto/references/open
 - 在 `docs/.scratch/<feature>/api/<feature>-validation.yaml` 持久化结构校验记录，并用 `scripts/verify-openapi-draft-validation-record` 复核当前 YAML SHA-256、锁定的 Redocly 版本、实际命令、退出码、执行时间和证据引用。
 - 在 OpenAPI Freeze 后，用锁定的 Redocly CLI 将 YAML bundle 为 JSON，并记录可重现证据。
 - 维护治理记录、Freeze 记录和 JSON 派生记录。
-- 在技术分析中生成 `api-contract-decision-v1`：有 API 影响时以原始字节摘要闭包绑定权威 YAML、Validation、独立 Draft Review 和 Freeze；无 API 影响时绑定影响评估、明确原因和至少一项可读证据，且不得生成空占位资产。
+- 在技术分析中生成 API Contract Decision（版本与历史兼容见下文第 3 步）：有 API 影响时以原始字节摘要闭包绑定权威 YAML、Validation、独立 Draft Review 和 Freeze；无 API 影响时绑定影响评估、明确原因和至少一项可读证据，且不得生成空占位资产。
 - Spec Delta 影响存在时，在 `docs/.scratch/<feature>/spec-delta/` 记录与冻结 YAML 的关系；没有影响时明确记录 `not-applicable`。
 
 不使用本 skill 来替代：
@@ -72,7 +72,7 @@ pnpm exec redocly bundle \
 2. **运行结构与治理校验**
    - 先执行项目 lockfile 锁定版本的 `pnpm exec redocly lint`；CI 可以包装调用，但 validation record 必须记录这条实际命令与退出码。
    - 检查 YAML 可解析、`$ref` 可解析、路径参数完整、operationId 唯一、examples 合法、schema 命名稳定。
-   - 从 `docs/api/templates/openapi-draft-validation-record-template.yaml` 创建 `<feature>-validation.yaml`，记录 YAML SHA-256 与 lint 工具链；运行 `scripts/verify-openapi-draft-validation-record --root <project-root> <record>`。自定义解析脚本可以补充诊断，但不能代替锁定的 Redocly lint evidence。
+   - 从 `.template-spec/api/templates/openapi-draft-validation-record-template.yaml` 创建 `<feature>-validation.yaml`，记录 YAML SHA-256 与 lint 工具链；运行 `scripts/verify-openapi-draft-validation-record --root <project-root> <record>`。自定义解析脚本可以补充诊断，但不能代替锁定的 Redocly lint evidence。
    - 对每个 P0 写模型、配置模型及影响关键交互的读模型建立字段级追踪：`Spec/交互来源 → operationId → request/response schema → property path → 类型与嵌套形状 → create/update requiredness → nullable/default/enum/format → error/test seam`。数组元素使用 `items[].property` 一类稳定 property path。
    - create/update 或其他不同生命周期操作复用同一写 schema 时，逐操作证明 requiredness 与省略语义一致；若不一致，拆分 schema 或明确条件契约。凭据类字段还要说明创建、更新、掩码回显、省略保留与显式清空语义，不能仅凭字段名统一设为必填。
    - 先运行 `scripts/verify-yss-dto-openapi-profile`，并记录 profile 版本；检查 `/api/v1/` 版本策略（或记录例外）、`x-yss-response-wrapper`、`YssResultMeta` + `allOf` 具体 schema、统一错误结构、分页、幂等 / 乐观锁和契约测试 seam。
@@ -83,12 +83,12 @@ pnpm exec redocly bundle \
    - 将通过 verifier 且 SHA-256 与当前 YAML 一致的 validation record 交给 `yss-openapi-draft-review`。缺锁定 lint 时可以先做语义预审，但独立 Review 总结果必须为 `Blocked`；不能用“Freeze 前补 lint”支持 `Approved`。
    - YAML、validation record 或 lint ruleset 变化后，旧结构证据与旧 Review 立即失效，必须重新校验和审查。阻断项未关闭前，YAML 仍是 review-only Draft，不得生成生产客户端。
    - Freeze 记录必须引用 YAML 路径、Git ref（如适用）和 YAML SHA-256。冻结后 API 行为变更必须先回到 YAML Draft 与审查。
-   - 将同一 YAML 的版本与摘要、validation record、独立 Review 和 Freeze 写入 API Contract Decision v1。`gate.engineering-contract-approved` 一次批准同时绑定 Technical Design、Data Architecture Decision、API Contract Decision；API `required` 时还必须直接绑定冻结 YAML。不得另造字符串 URI 或仅凭 `status: approved` 关闭门禁。
+   - 将同一 YAML 的版本与摘要、validation record、独立 Review 和 Freeze 写入 API Contract Decision（新建 v2；历史 v1 只读兼容，准备与迁移见 `.template-spec/process/contract-reading.md`）。`gate.engineering-contract-approved` 一次批准同时绑定 Technical Design、Data Architecture Decision、API Contract Decision；API `required` 时还必须直接绑定冻结 YAML。不得另造字符串 URI 或仅凭 `status: approved` 关闭门禁。
 
 4. **从冻结 YAML 派生 JSON**
    - 使用上面的锁定 `redocly bundle` 命令生成 `docs/.scratch/<feature>/api/<feature>.json`，JSON 不纳入人工编辑面。
    - 对输出 JSON 重新执行解析 / lint（按项目工具链），确认 bundle 未产生组件重名冲突或无法解析的引用。
-   - 写入 `docs/.scratch/<feature>/api/<feature>-json-export.md`，可从 `docs/api/templates/openapi-json-export-record-template.md` 创建。
+   - 写入 `docs/.scratch/<feature>/api/<feature>-json-export.md`，可从 `.template-spec/api/templates/openapi-json-export-record-template.md` 创建。
    - 记录 YAML SHA-256、JSON SHA-256、OAS 版本、Redocly CLI 版本与 lockfile 引用、完整命令、metafile、`$ref` 例外以及结果。
 
 5. **交给下游前端**

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

@@ -5,11 +5,11 @@ description: 编排 YSS 研发全生命周期；当阶段、产物、门禁或 S
 
 # YSS Product Lifecycle
 
-合同阅读：`scripts/contract view`；见 `docs/process/contract-reading.md`。
+合同阅读：`scripts/contract view`；见 `.template-spec/process/contract-reading.md`。
 
-主控识别请求、仓库身份和可信阶段，计算 frontier、派发与验收工作单元；专项 Skill 负责设计、实现和独立审查。
+主控识别请求、身份及可信阶段，计算 frontier 并派发、验收工作单元；专项 Skill 执行与独立审查。
 
-文档按 `document_writing` 条件调用 `i-have-adhd`，并传递 `docs/process/document-writing.md` 规范。
+文档按 `document_writing` 条件调用 `i-have-adhd`，并传递 `.template-spec/process/document-writing.md` 规范。
 
 ## 事实源与按需加载
 
@@ -17,11 +17,11 @@ description: 编排 YSS 研发全生命周期；当阶段、产物、门禁或 S
 
 | 事实 | 权威来源 |
 |---|---|
-| 阶段、聚合门禁、内部检查、产物、工作单元、证据和稳定 ID | `docs/process/lifecycle-registry.yaml` |
+| 阶段、聚合门禁、内部检查、产物、工作单元、证据和稳定 ID | `.template-spec/process/lifecycle-registry.yaml` |
 | 执行模式、流转、readiness、暂停、结果和授权语义 | `references/orchestration-contract.yaml` |
-| Skill 身份、capability、依赖和路由 | `docs/agents/yss-skill-registry.yaml` |
-| 数字人角色、运行时和会签策略 | `docs/agents/digital-human-roles.yaml` |
-| 影响面、裁剪和模板维护强度 | `docs/process/harness-process-tailoring.md`、`docs/process/maintenance-intensity.yaml` |
+| Skill 身份、capability、依赖和路由 | `.template-spec/agents/yss-skill-registry.yaml` |
+| 数字人角色、运行时和会签策略 | `.template-spec/agents/digital-human-roles.yaml` |
+| 影响面、裁剪和模板维护强度 | `.template-spec/process/harness-process-tailoring.md`、`.template-source/process/maintenance-intensity.yaml` |
 
 用 `scripts/query-lifecycle-context` 查询合同：
 
@@ -40,7 +40,7 @@ scripts/query-lifecycle-context --mode route --stage stage.plan --work-unit work
 3. 按合同 `request_triage` 选择 `route`、`orchestrate`、`resume`、`audit`；明确行动请求无需模式关键字，意图不明时只读 `route`。`modes`、门禁及授权边界仍适用。
 4. `project-instance` 按生命周期注册表推进；`template-source` 只走模板维护流程。
 
-Plan 入口读取 `docs/plan/README.md` 和 `docs/process/plan-migration.md`，按注册表的退出条件核查战略输入。关键未决项阻断进入 Spec；非关键细节须有责任人、解决时点和下游接收方。只使用 Plan 标识；旧阶段不提供兼容解析，历史批准不自动成为 Plan 批准。
+Plan 入口读取 `.template-spec/plan/README.md` 和 `.template-spec/process/plan-migration.md`，核查战略输入与退出条件。关键未决项阻断 Spec；其他未决项记录责任人、解决时点和接收方。只用 Plan 标识；旧阶段不兼容解析，历史批准不自动沿用。
 
 理解、澄清与纠错见 [请求分诊协议](references/request-triage.md)；用 `scripts/query-lifecycle-context --include request_triage` 查询合同。先查上下文和证据，只问影响下一动作的缺口，不按问题长度追问。
 
@@ -83,9 +83,9 @@ Plan 入口读取 `docs/plan/README.md` 和 `docs/process/plan-migration.md`，
 
 `机会与目标 → 业务故事 → 责任与交接 → 规则、例子与疑问 → 可验收需求 → 页面验证 → 业务任务 → 交接研发`
 
-按当前决策澄清目标、流程、责任、规则、最小范围和验收例子。可生成引用权威资产的“业务方案总览”，展示状态、未决项、责任人和下一步；不复制正文或新增门禁。
+按当前决策澄清目标、流程、责任、规则、范围和验收例子。业务方案总览引用权威资产，展示状态、未决项、责任人和下一步；不复制正文或新增门禁。
 
-Plan → Spec（含正式草稿、恢复与显式 `to-spec`）写入前，按 `docs/plan/entry-review.md` 持久化审阅包并运行 `node scripts/verify-plan-spec-entry <state.yaml>`。检查默认 pending，缺项、过期或无真实回复即阻断；独立调研可继续。
+Plan → Spec（含正式草稿、恢复与显式 `to-spec`）写入前，按 `.template-spec/plan/entry-review.md` 持久化审阅包并运行 `node scripts/verify-plan-spec-entry <state.yaml>`。检查默认 pending，缺项、过期或无真实回复即阻断；独立调研可继续。
 
 ## 结果与暂停
 
@@ -97,4 +97,4 @@ Plan → Spec（含正式草稿、恢复与显式 `to-spec`）写入前，按 `d
 
 专项合同加载索引见 `references/orchestration.md`。
 
-Plan / Spec / Design 追踪按 `docs/process/stage-tracking.md`。
+Plan / Spec / Design 追踪按 `.template-spec/process/stage-tracking.md`。

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

@@ -19,7 +19,7 @@ Matt skills 决定如何工作；YSS 生命周期决定是否允许推进；YSS
 | 信息在其他人手中 | `to-questionnaire` | 使用 `external-input-required` 暂停；答案回流后记录 response、重新分类影响面，再进入 `grill-with-docs` 或 `to-spec` |
 | 大型模糊工作 | `wayfinder`（可选） | 仅在跨会话 / 跨 Agent 或 frontier 不清晰时启用；map 真正完成后 `handoff → to-spec` |
 | 技术或战略事实 | `yss-research`（`research` 为 deprecated alias） | `technical-evidence` 核验一手技术资料；`strategy-evidence` 为领域战略和阶段决策提供可审计证据；研究包不得自行修改或批准下游资产 |
-| runnable 问题 | `prototype` | 生成单文件可分享 HTML，保留 `prototype/<name>` 分支作为主来源；必须 source/return handoff 和结论回填，只能作为阶段 4 输入，不得替代低保真评审、H1/H2 档位路由、schema v3 验证和用户确认 |
+| runnable 问题 | `prototype` | 生成单文件可分享 HTML，保留 `prototype/<name>` 分支作为主来源；必须 source/return handoff 和结论回填，只能作为阶段 4 输入，不得替代低保真评审、H1/H2 档位路由、schema v4 验证和用户确认 |
 | Spec 综合 | 原生 `work-unit.spec-synthesis`；`to-spec`（用户显式兼容） | 初稿进入 `ready-for-human`，不得直接实现 |
 | 切片 | 原生 `work-unit.ticket-decomposition`；`to-tickets`（用户显式兼容） | 仅在冻结/无影响记录后拆垂直切片，初始 Ticket 状态为 `ready-for-human` |
 | 实现 | 原生 `work-unit.slice-implementation`；`implement`（用户显式兼容） | 当前合同批准并持久化后执行；内部使用 `tdd`，结果回交后再次核验 |
@@ -48,7 +48,7 @@ workflow_reference:
   invocation_mode: reference
 result: completed # completed / blocked / needs-human / failed
 evidence_refs:
-  - docs/process/yss-product-lifecycle-orchestrator-validation.md
+  - .template-spec/process/yss-product-lifecycle-orchestrator-validation.md
 changed_artifacts: []
 new_impacts: []
 stale_candidates: []
@@ -74,7 +74,7 @@ blocking_signals: []
 
 ## Review 候选与 Git 授权
 
-YSS 调用 `code-review` 前必须形成 review input，至少包含 `review_mode`、`review_base_ref`、`implementation_candidate_ref`、`candidate_snapshot_ref`、`candidate_digest`、`spec_ref`、`ticket_ref`、`slice_contract_ref`、`build_architecture_checklist_ref` 和 `yss_execution_result_refs`，并满足 `orchestration-contract.yaml.review_input.manifest_required_by_mode`。Standards 还必须编译 `review_standards_route`：合同 `required_skills`、影响面专项检查输入、报告模板与 `finding_disposition`；机器检查按 `run_if_present` 执行。质量标准只从 `engineering-baseline` 引用，禁止在 review input 或切片中另起一份。命中高风险影响时，review input 还要引用 Doubt-Driven 主张 / 反证记录；缺少反证或残余风险未处理时返回 `blocked`。`committed` 审查 merge-base 到不可变 `HEAD`；`worktree` 一次捕获 merge-base 到 working tree 的 committed、staged、unstaged 和 untracked 内容，使用 `yss-worktree-candidate-v1` 规定的 raw path、uint64 big-endian 长度、tracked/untracked record 和不支持条目阻断规则计算 SHA-256，让两个 Reviewer 消费同一不可变快照，并在返回和完成 checkpoint 复核摘要未变化。缺少输入、候选为空、专项覆盖缺失、未关闭 mandatory `violation`、适用行空白或摘要变化时返回 `blocked`，不能缩小审查范围、另起通用审查 skill、由审查者改实现，或合并不同候选的结论。`violation` 类 finding 交实现者在原合同路径修复后全轴复审；`drift` / `new_impacts` 使合同 `stale` 并回 实现合同编译器。
+YSS 调用 `code-review` 前必须形成 review input，至少包含 `review_mode`、`review_base_ref`、`implementation_candidate_ref`、`candidate_snapshot_ref`、`candidate_digest`、`spec_ref`、`ticket_ref`、`slice_contract_ref`、`build_architecture_checklist_ref` 和 `yss_execution_result_refs`，并满足 `orchestration-contract.yaml.review_input.manifest_required_by_mode`。Standards 还必须编译 `review_standards_route`：合同 `required_skills`、影响面专项检查输入、报告模板与 `finding_disposition`；机器检查按 `run_if_present` 执行。质量标准只从 `engineering-baseline` 引用，禁止在 review input 或切片中另起一份。命中高风险影响时，review input 还要引用 Doubt-Driven 主张 / 反证记录；缺少反证或残余风险未处理时返回 `blocked`。`committed` 审查 merge-base 到不可变 `HEAD`；`worktree` 一次捕获 merge-base 到 working tree 的 committed、staged、unstaged 和 untracked 内容，使用 `yss-worktree-candidate-v1` 规定的 raw path、uint64 big-endian 长度、tracked/untracked record 和不支持条目阻断规则计算 SHA-256，让所有参与审查者（人数按 `orchestration-contract.yaml.gate_consolidation`） 消费同一不可变快照，并在返回和完成 checkpoint 复核摘要未变化。缺少输入、候选为空、专项覆盖缺失、未关闭 mandatory `violation`、适用行空白或摘要变化时返回 `blocked`，不能缩小审查范围、另起通用审查 skill、由审查者改实现，或合并不同候选的结论。`violation` 类 finding 交实现者在原合同路径修复后全轴复审；`drift` / `new_impacts` 使合同 `stale` 并回 实现合同编译器。
 
 Matt `implement` 的通用提交指令不构成 YSS Git 授权。只有用户明确给出 `commit_authorized` 为 `true`、非空 `commit_scope` 和 `commit_authorization_ref` 时才能 commit；只有明确给出 `push_authorized` 为 `true`、非空 `push_scope` 和 `push_authorization_ref` 时才能 push。缺少任一字段时保持工作区不变，只输出 checkpoint 判断；不得把 `orchestrate`、实现授权、当前分支、测试通过或负责人要求解释为隐含授权。`git-submodule` 还必须按仓授权、禁止 detached HEAD 提交，并先推子仓再更新父仓 gitlink。
 
@@ -92,11 +92,11 @@ Matt `implement` 的通用提交指令不构成 YSS Git 授权。只有用户明
 
 当 YSS 生命周期处于 active 状态时，Matt `to-spec` 中独立运行时的 `ready-for-agent` 发布提示由本适配层覆盖为 `ready-for-human`：Spec 必须先经过产品总体设计 / 功能架构、必要的设计与契约门禁，之后才由生命周期编排器决定垂直切片 Ticket 的 `ready-for-agent`。这只约束 YSS 编排下的状态写入，不修改 Matt skill 单独运行时的核心行为。
 
-`setup-matt-pocock-skills` 仅由用户显式启动。readiness=`missing` 时返回 `needs-human`、`requested_skill=setup-matt-pocock-skills` 和 `resume_route=setup-readiness`；仅发现旧路径资产仍进入 migration-check 并暂停写入。`ready` 直接继续，`conflict` 进入迁移裁决，`degraded` 保留待发布草案，`not-applicable` 仅验证模板契约。通用 setup 文案与 YSS tracker 合同冲突时，以 `docs/agents/issue-tracker.md` 和本编排契约为准。
+`setup-matt-pocock-skills` 仅由用户显式启动。readiness=`missing` 时返回 `needs-human`、`requested_skill=setup-matt-pocock-skills` 和 `resume_route=setup-readiness`；仅发现旧路径资产仍进入 migration-check 并暂停写入。`ready` 直接继续，`conflict` 进入迁移裁决，`degraded` 保留待发布草案，`not-applicable` 仅验证模板契约。通用 setup 文案与 YSS tracker 合同冲突时，以 `.template-spec/agents/issue-tracker.md` 和本编排契约为准。
 
 ### Local Markdown 兼容映射
 
-当 `docs/agents/issue-tracker.md` 的 `platform` 为 `local-markdown` 时，Matt flow 的本地输出归一化为以下 YSS 载体：
+当 `.template-spec/agents/issue-tracker.md` 的 `platform` 为 `local-markdown` 时，Matt flow 的本地输出归一化为以下 YSS 载体：
 
 | Matt 产物 | Local 载体 |
 |---|---|