create-yss-spec 2.2.10 → 3.0.0

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

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+/** Promote a generated backend only after a complete, approved first vertical slice passes real Wrapper verification. */
+import { createHash } from "node:crypto";
+import { mkdir, readFile, readdir, rename, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+import { run as runScaffoldVerification } from "./run_scaffold_verification.mjs";
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const REPOSITORY_ROOT = path.resolve(SCRIPT_DIR, "../../../..");
+const REQUIRED_SKILLS = ["yss-domain", "yss-application", "yss-repository", "yss-mybatis", "yss-web-controller", "yss-dto", "yss-exception", "yss-validation", "mapstruct", "lombok", "alibaba-java-code-style"];
+const REQUIRED_LAYERS = ["domain", "application", "infrastructure", "web"];
+const ARTIFACT_CHECKS = [
+  ["domain-model", /-domain\/src\/main\/java\/.+\/domain\/.+\/model\/.+\.java$/],
+  ["domain-gateway", /-domain\/src\/main\/java\/.+\/domain\/.+\/gateway\/.+Gateway\.java$/],
+  ["domain-behavior-test", /-domain\/src\/test\/java\/.+(?:Test|Tests)\.java$/],
+  ["application-command-or-query", /-application\/src\/main\/java\/.+\/application\/(?:command|query)\/.+\.java$/],
+  ["application-result", /-application\/src\/main\/java\/.+\/application\/result\/.+Result\.java$/],
+  ["application-service", /-application\/src\/main\/java\/.+\/application\/service\/.+Service\.java$/],
+  ["application-service-implementation", /-application\/src\/main\/java\/.+\/application\/service\/impl\/.+ServiceImpl\.java$/],
+  ["application-behavior-test", /-application\/src\/test\/java\/.+(?:Test|Tests)\.java$/],
+  ["infrastructure-po", /-infrastructure\/src\/main\/java\/.+\/infrastructure\/persistence\/po\/.+PO\.java$/],
+  ["infrastructure-repository", /-infrastructure\/src\/main\/java\/.+\/infrastructure\/persistence\/repository\/.+Repository\.java$/],
+  ["infrastructure-convertor", /-infrastructure\/src\/main\/java\/.+\/infrastructure\/persistence\/convertor\/.+Convertor\.java$/],
+  ["infrastructure-gateway-implementation", /-infrastructure\/src\/main\/java\/.+\/infrastructure\/persistence\/gateway\/.+GatewayImpl\.java$/],
+  ["infrastructure-query-adapter", /-infrastructure\/src\/main\/java\/.+\/infrastructure\/query\/adapter\/.+QueryAdapter\.java$/],
+  ["infrastructure-integration-test", /-infrastructure\/src\/test\/java\/.+(?:Test|Tests)\.java$/],
+  ["web-controller", /-adapter\/.+-web\/src\/main\/java\/.+\/rest\/.+Controller\.java$/],
+  ["web-convertor", /-adapter\/.+-web\/src\/main\/java\/.+\/rest\/convertor\/.+WebConvertor\.java$/],
+  ["web-request", /-adapter\/.+-web\/src\/main\/java\/.+\/rest\/dto\/request\/.+Request\.java$/],
+  ["web-response", /-adapter\/.+-web\/src\/main\/java\/.+\/rest\/dto\/response\/.+Response\.java$/],
+  ["web-contract-test", /-adapter\/.+-web\/src\/test\/java\/.+(?:Test|Tests)\.java$/]
+];
+
+const isoNow = () => new Date().toISOString();
+const sha256 = (content) => createHash("sha256").update(content).digest("hex");
+async function isFile(target) { try { return (await stat(target)).isFile(); } catch (error) { if (error.code === "ENOENT") return false; throw error; } }
+async function files(root) {
+  const output = [];
+  async function visit(directory) {
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+      const absolute = path.join(directory, entry.name);
+      if (entry.isDirectory()) await visit(absolute);
+      else if (entry.isFile()) output.push(path.relative(root, absolute).split(path.sep).join("/"));
+    }
+  }
+  await visit(root);
+  return output.sort();
+}
+async function treeDigest(root) {
+  const hash = createHash("sha256");
+  for (const relative of await files(root)) hash.update(relative).update("\0").update(await readFile(path.join(root, relative))).update("\0");
+  return hash.digest("hex");
+}
+async function writeJsonAtomic(target, value) {
+  await mkdir(path.dirname(target), { recursive: true });
+  const temporary = `${target}.${process.pid}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+  await rename(temporary, target);
+}
+function invalidContractReasons(contract) {
+  const reasons = [];
+  if (contract.schema_version !== 1) reasons.push("slice-contract-schema");
+  if (contract.status !== "approved") reasons.push("slice-contract-not-approved");
+  for (const field of ["contract_id", "contract_version", "slice_id"]) if (contract[field] === undefined || contract[field] === null || contract[field] === "") reasons.push(`slice-contract-${field}-missing`);
+  if (contract.readiness?.blockers?.length) reasons.push("slice-contract-has-blockers");
+  if (contract.readiness?.stale_inputs?.length) reasons.push("slice-contract-has-stale-inputs");
+  const actualSkills = new Set([...(contract.common?.required_skills ?? []), ...(contract.backend?.required_skills ?? [])]);
+  for (const skill of REQUIRED_SKILLS) if (!actualSkills.has(skill)) reasons.push(`required-skill-missing:${skill}`);
+  const actualLayers = new Set(contract.backend?.affected_layers ?? []);
+  for (const layer of REQUIRED_LAYERS) if (!actualLayers.has(layer)) reasons.push(`required-layer-missing:${layer}`);
+  if (!Array.isArray(contract.work_units) || !contract.work_units.length) reasons.push("slice-contract-work-units-missing");
+  else for (const [index, unit] of contract.work_units.entries()) {
+    const id = unit.id || `index-${index}`;
+    if (unit.contract_id !== contract.contract_id) reasons.push(`work-unit-contract-id-mismatch:${id}`);
+    if (unit.contract_version !== contract.contract_version) reasons.push(`work-unit-contract-version-mismatch:${id}`);
+    if (!unit.work_unit?.primary_skill) reasons.push(`work-unit-primary-skill-missing:${id}`);
+  }
+  return reasons;
+}
+async function downstreamDrift(manifest) {
+  const drift = [];
+  const recordedSkills = manifest.readiness?.downstream_skills ?? {};
+  for (const skill of REQUIRED_SKILLS) {
+    const expected = recordedSkills[skill];
+    if (typeof expected !== "string" || !/^[a-f0-9]{64}$/.test(expected)) {
+      drift.push(`${skill}:digest-missing`);
+      continue;
+    }
+    const root = path.join(REPOSITORY_ROOT, ".agents", "skills", skill);
+    if (!await isFile(path.join(root, "SKILL.md"))) drift.push(`${skill}:unavailable`);
+    else if (await treeDigest(root) !== expected) drift.push(`${skill}:digest-mismatch`);
+  }
+  const contracts = manifest.readiness?.contracts ?? {};
+  const contractFiles = {
+    scaffold_parent: path.join(REPOSITORY_ROOT, ".agents", "skills", "yss-ddd-scaffold-generator", "references", "yss-backend-scaffold-parent", "SKILL.md"),
+    router_contract: path.join(REPOSITORY_ROOT, ".agents", "skills", "yss-router", "references", "router-contract.yaml")
+  };
+  for (const [name, target] of Object.entries(contractFiles)) {
+    const expected = contracts[name];
+    if (typeof expected !== "string" || !/^[a-f0-9]{64}$/.test(expected)) {
+      drift.push(`${name}:digest-missing`);
+      continue;
+    }
+    if (!await isFile(target)) drift.push(`${name}:unavailable`);
+    else if (sha256(await readFile(target)) !== expected) drift.push(`${name}:digest-mismatch`);
+  }
+  return drift;
+}
+
+export async function runFirstSliceVerification(projectRoot, evidenceDir, sliceContractFile, environment = process.env) {
+  projectRoot = path.resolve(projectRoot);
+  evidenceDir = path.resolve(evidenceDir);
+  sliceContractFile = path.resolve(sliceContractFile);
+  const manifestPath = path.join(projectRoot, ".yss", "scaffold-generation.json");
+  const reportPath = path.join(evidenceDir, "first-slice-verification.json");
+  if (!await isFile(manifestPath)) throw new Error(`missing scaffold manifest: ${manifestPath}`);
+  if (!await isFile(sliceContractFile)) throw new Error(`missing Slice Implementation Contract: ${sliceContractFile}`);
+  const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+  const contract = JSON.parse(await readFile(sliceContractFile, "utf8"));
+  const contractFailures = invalidContractReasons(contract);
+  if (manifest.schema_version !== 2 || manifest.completion_level !== "empty-scaffold-verified") contractFailures.push("scaffold-not-empty-scaffold-verified");
+  const projectFiles = await files(projectRoot);
+  const missingArtifacts = ARTIFACT_CHECKS.filter(([, pattern]) => !projectFiles.some((file) => pattern.test(file))).map(([name]) => name);
+  const skillDrift = await downstreamDrift(manifest);
+  if (contractFailures.length || missingArtifacts.length || skillDrift.length) {
+    const report = { verification_mode: "first-slice", project_root: projectRoot, slice_contract_ref: sliceContractFile, scaffold_manifest_ref: manifestPath, generated_at: isoNow(), status: "failed", completion_level: manifest.completion_level, contract_failures: contractFailures, missing_artifacts: missingArtifacts, downstream_skill_drift: skillDrift, commands: [] };
+    await writeJsonAtomic(reportPath, report);
+    return report;
+  }
+
+  const mavenEvidence = path.join(evidenceDir, "maven");
+  const wrapper = await runScaffoldVerification(projectRoot, mavenEvidence, environment);
+  const passed = wrapper.status === "passed";
+  const report = { verification_mode: "first-slice", project_root: projectRoot, slice_contract_ref: sliceContractFile, scaffold_manifest_ref: manifestPath, generated_at: isoNow(), status: passed ? "passed" : "failed", failure_category: wrapper.failure_category, completion_level: passed ? "first-slice-verified" : manifest.completion_level, contract_failures: [], missing_artifacts: [], downstream_skill_drift: [], commands: wrapper.commands };
+  await writeJsonAtomic(reportPath, report);
+  if (passed) {
+    manifest.completion_level = "first-slice-verified";
+    manifest.first_slice_verification_ref = reportPath;
+    manifest.first_slice_verified_at = isoNow();
+    manifest.first_slice_contract = { contract_id: contract.contract_id, contract_version: contract.contract_version, slice_id: contract.slice_id, sha256: sha256(await readFile(sliceContractFile)) };
+    await writeJsonAtomic(manifestPath, manifest);
+  }
+  return report;
+}
+
+function parseArgs(argv) {
+  const result = {};
+  for (let index = 0; index < argv.length; index += 2) {
+    const flag = argv[index], value = argv[index + 1];
+    if (!["--project-root", "--evidence-dir", "--slice-contract-file"].includes(flag) || !value) throw new Error("usage: run_first_slice_verification.mjs --project-root DIR --evidence-dir DIR --slice-contract-file FILE");
+    result[flag.slice(2).replaceAll(/-([a-z])/g, (_, letter) => letter.toUpperCase())] = value;
+  }
+  if (!result.projectRoot || !result.evidenceDir || !result.sliceContractFile) throw new Error("project root, evidence dir, and slice contract file are required");
+  return result;
+}
+
+async function main() {
+  try {
+    const args = parseArgs(process.argv.slice(2));
+    const report = await runFirstSliceVerification(args.projectRoot, args.evidenceDir, args.sliceContractFile);
+    process.stdout.write(`${report.status}: ${path.join(path.resolve(args.evidenceDir), "first-slice-verification.json")}\n`);
+    return report.status === "passed" ? 0 : 1;
+  } catch (error) {
+    process.stderr.write(`first-slice verification failed: ${error.message}\n`);
+    return 1;
+  }
+}
+
+if (process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href) process.exitCode = await main();

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

@@ -1,5 +1,6 @@
 import assert from "node:assert/strict";
 import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
 import { chmod, mkdtemp, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import os from "node:os";
@@ -15,6 +16,18 @@ const generator = path.join(scripts, "generate_scaffold.mjs");
 const workflow = path.join(scripts, "generate_and_verify_scaffold.mjs");
 const command = (args, options = {}) => new Promise((resolve) => execFile(process.execPath, [generator, ...args], { encoding: "utf8", ...options }, (error, stdout, stderr) => resolve({ code: error?.code ?? 0, stdout, stderr })));
 const workflowCommand = (args, options = {}) => new Promise((resolve) => execFile(process.execPath, [workflow, ...args], { encoding: "utf8", ...options }, (error, stdout, stderr) => resolve({ code: error?.code ?? 0, stdout, stderr })));
+async function treeDigest(root) {
+  const hash = createHash("sha256");
+  async function visit(directory) {
+    for (const entry of (await readdir(directory, { withFileTypes: true })).sort((left, right) => left.name.localeCompare(right.name))) {
+      const absolute = path.join(directory, entry.name);
+      if (entry.isDirectory()) await visit(absolute);
+      else if (entry.isFile()) hash.update(path.relative(root, absolute).split(path.sep).join("/")).update("\0").update(await readFile(absolute)).update("\0");
+    }
+  }
+  await visit(root);
+  return hash.digest("hex");
+}
 function contract(outputDir, overrides = {}) {
   return {
     schema_version: 2,
@@ -99,7 +112,7 @@ async function prepareVerifierProject(project, manifest = targetManifest()) {
   await writeFile(path.join(project, ".yss", "scaffold-generation.json"), `${JSON.stringify(manifest)}\n`);
 }
 
-test("生成批准的服务级 target profile 骨架，并写入可追溯 Manifest v2", async (t) => { const data = await fixture(); t.after(() => rm(data.root, { recursive: true, force: true })); const result = await command(data.args); assert.equal(result.code, 0, result.stderr); const project = path.join(data.output, "demo-service"); const manifest = JSON.parse(await readFile(path.join(project, ".yss/scaffold-generation.json"), "utf8")); assert.equal(manifest.schema_version, 2); assert.equal(manifest.scaffold_request_id, "scaffold-request-1"); assert.equal(manifest.slice_id, undefined); assert.equal(manifest.completion_level, "generated"); assert.equal(manifest.profiles.architecture, "target-domain-model"); assert.deepEqual(manifest.generation_policy, { mode: "initialize-only", existing_target: "unsupported", old_project_migration: "unsupported", template_upgrade: "unsupported" }); assert.match(manifest.generator.template_digest, /^[a-f0-9]{64}$/); assert.match(manifest.contract_digest, /^[a-f0-9]{64}$/); assert.ok(manifest.ownership.generated_files.length > 8); assert.ok(manifest.ownership.generated_files.every((item) => item.owner === "generator" && /^[a-f0-9]{64}$/.test(item.sha256))); assert.equal(manifest.generation_mode, "controlled-generation"); assert.deepEqual(manifest.verification_commands, ["./mvnw validate", "./mvnw test", "./mvnw package"]); assert.equal(manifest.bootstrap_main_class, "com.yss.demo.DemoServiceApplication"); assert.equal(manifest.bootstrap_main_source, "demo-service-bootstrap/src/main/java/com/yss/demo/DemoServiceApplication.java"); assert.match(await readFile(path.join(project, manifest.bootstrap_main_source), "utf8"), /class DemoServiceApplication/); assert.match(await readFile(path.join(project, "pom.xml"), "utf8"), /demo-service/); });
+test("生成批准的服务级 target profile 骨架，并写入可追溯 Manifest v2", async (t) => { const data = await fixture(); t.after(() => rm(data.root, { recursive: true, force: true })); const result = await command(data.args); assert.equal(result.code, 0, result.stderr); const project = path.join(data.output, "demo-service"); const manifest = JSON.parse(await readFile(path.join(project, ".yss/scaffold-generation.json"), "utf8")); assert.equal(manifest.schema_version, 2); assert.equal(manifest.scaffold_request_id, "scaffold-request-1"); assert.equal(manifest.slice_id, undefined); assert.equal(manifest.completion_level, "generated"); assert.equal(manifest.profiles.architecture, "target-domain-model"); assert.deepEqual(manifest.generation_policy, { mode: "initialize-only", existing_target: "unsupported", old_project_migration: "unsupported", template_upgrade: "unsupported" }); assert.match(manifest.generator.template_digest, /^[a-f0-9]{64}$/); assert.match(manifest.contract_digest, /^[a-f0-9]{64}$/); assert.ok(manifest.ownership.generated_files.length > 8); assert.ok(manifest.ownership.generated_files.every((item) => item.owner === "generator" && /^[a-f0-9]{64}$/.test(item.sha256))); assert.equal(manifest.generation_mode, "controlled-generation"); assert.deepEqual(manifest.verification_commands, ["./mvnw validate", "./mvnw test", "./mvnw package"]); assert.equal(manifest.bootstrap_main_class, "com.yss.demo.DemoServiceApplication"); assert.equal(manifest.bootstrap_main_source, "demo-service-bootstrap/src/main/java/com/yss/demo/DemoServiceApplication.java"); assert.match(await readFile(path.join(project, manifest.bootstrap_main_source), "utf8"), /class DemoServiceApplication/); assert.match(await readFile(path.join(project, "pom.xml"), "utf8"), /demo-service/); assert.equal(manifest.readiness.downstream_skills["yss-domain"], await treeDigest(path.resolve(scripts, "../../yss-domain"))); assert.match(manifest.readiness.contracts.scaffold_parent, /^[a-f0-9]{64}$/); assert.match(manifest.readiness.contracts.router_contract, /^[a-f0-9]{64}$/); });
 
 test("schema v1 scaffold contract is unsupported and is never upgraded", async (t) => {
   const data = await fixture({ schema_version: 1 });

package/template/.agents/skills/yss-domain/SKILL.md

@@ -47,7 +47,8 @@ description: 用于构建或重构 YSS 领域层代码。当用户要求设计
 
 - 命名体现业务语义，不照抄表名缩写。
 - 生成代码应可编译，且没有跨层依赖泄漏。
-- 对不确定规则写出假设或 TODO，不要伪装成已确认事实。
+- Domain Gateway interface 由本 skill 唯一拥有；Infrastructure 只能实现，不得由 `yss-repository` 反向创建或改写其签名。
+- 对不确定规则返回 `new_impacts` / `drift` 并暂停；不要把未批准假设或 TODO 写进实现冒充已确认事实。
 
 ## 协同顺序
 

package/template/.agents/skills/yss-domain/agents/openai.yaml

@@ -1,5 +1,5 @@
 version: 1
 interface:
   display_name: "YSS Domain"
-  short_description: "领域建模、聚合根、规则与网关设计实践落地标准化规范"
-  default_prompt: "Use $yss-domain to design aggregates, entities, domain gateways, and business rules for a YSS domain model."
+  short_description: "按批准战术模型实现聚合、规则与 Domain Gateway 接口"
+  default_prompt: "Use $yss-domain to implement approved aggregates, entities, business rules, domain tests, and the sole Domain Gateway interfaces; reroute instead of inventing unresolved rules."

package/template/.agents/skills/yss-domain/references/domain-layer-guide.md

@@ -41,6 +41,8 @@ DTO/VO 位于 `{base_package}.rest.dto`。独立 client Maven module 对当前 T
 
 Gateway 描述领域能力，只交换 Domain Model、领域值和领域标识。例如：
 
+Gateway interface 的签名由批准战术模型决定，并由 `yss-domain` 唯一创建和维护；Infrastructure / `yss-repository` 只能实现该接口。若实现所需能力超出既有签名，返回 `new_impacts` 并重路由，不得从 DDL 反向扩写 Domain 合同。
+
 ```java
 package com.yss.quality.domain.template.gateway;
 

package/template/.agents/skills/yss-dto/SKILL.md

@@ -9,6 +9,12 @@ description: Use when YSS `Result`, `SingleResult`, `MultiResult`, `PageResult`,
 
 本 skill 同时负责把中台 DTO 映射到公开 HTTP/JSON 边界。`references/openapi-wire-profile.yaml` 是可复用的机器可读映射源；OpenAPI 治理和 Draft Review 必须消费它，不得各自复制一份 wrapper 或分页字段表。
 
+## 所有权边界
+
+- `Result` / `SingleResult` / `MultiResult` / `PageResult`、`CommandDTO` / `QueryDTO` / `PageQuery` 的 canonical package、工厂方法、字段语义、默认值、枚举和禁用字段由本 skill 及 `references/openapi-wire-profile.yaml` 唯一持有。
+- Web skill 只生成 endpoint-specific Page Request、Request/Response 与 Convertor，并通过批准合同中的 profile 引用和 digest 消费上述协议；不得生成 wrapper/page base，也不得维护分页字段或默认值副本。
+- OpenAPI skill 只把该 profile 组合进 endpoint schema；不得从 Java getter 或本地常量反向建立第二份 wire 协议。
+
 ## 何时使用
 
 - 用户要定义新的分页查询对象。

package/template/.agents/skills/yss-dto/references/openapi-wire-profile.yaml

@@ -54,6 +54,9 @@ wrappers:
   SingleResult:
     java_type: com.yss.cloud.dto.result.SingleResult<T>
     response_kind: single
+    java_factory:
+      method: of
+      arguments: [data]
     data:
       direction: response
       wire_shape: endpoint-schema-or-null
@@ -72,6 +75,9 @@ wrappers:
   PageResult:
     java_type: com.yss.cloud.dto.result.PageResult<T>
     response_kind: page
+    java_factory:
+      method: of
+      arguments: [data, totalCount, pageSize, pageIndex]
     fields:
       totalCount:
         direction: response

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

@@ -31,7 +31,7 @@ Matt 的 `grill-with-docs`、`to-spec`、`to-tickets`、`implement` 等保留为
 | 主阶段 | 必需产物/门禁 | 原生工作单元与技能 | 通过条件 |
 |---|---|---|---|
 | 入口分诊 `stage.entry-triage` | 身份、影响面、最近可信阶段 | `work-unit.entry-triage`；`yss-product-lifecycle` | `yss-project.yaml` 合法且影响面可解释 |
-| Discovery `stage.discovery` | Discovery、用户/MVP/非目标/成功标准、测试 seam；命中 DDD 影响时补充领域战略设计与阶段决策包 | `work-unit.discovery-opportunity` + `work-unit.discovery-requirements` + `work-unit.domain-strategy-design` + `work-unit.stage-decision`；市场/竞品事实用 `competitive-intelligence`，技术/标准事实用 `research`；需求澄清用 `grilling`，领域建模用 `domain-modeling` / `yss-stage-decision`；`grill-with-docs` 为兼容入口 | 未决事实已 research 或 handoff，领域边界和统一语言可审查，阶段决策包完成必要批准；`gate.domain-strategy-approved`、`gate.stage-decision-package-approved` |
+| Discovery `stage.discovery` | Discovery、用户/MVP/非目标/成功标准、测试 seam；命中 DDD 影响时补充领域战略设计与阶段决策包 | `work-unit.discovery-opportunity` + `work-unit.discovery-requirements` + `work-unit.domain-strategy-design` + `work-unit.stage-decision`；市场/竞品事实用 `competitive-intelligence`，技术/标准事实用 `yss-research:technical-evidence`，领域战略与阶段决策证据用 `yss-research:strategy-evidence`；需求澄清用 `grilling`，领域建模用 `domain-modeling` / `yss-stage-decision`；`grill-with-docs` 为兼容入口 | 未决事实已由 `yss-research` 核验或 handoff，进入战略 / 阶段门禁的决策证据已 `evidence-audited`，领域边界和统一语言可审查，阶段决策包完成必要批准；`gate.domain-strategy-approved`、`gate.stage-decision-package-approved` |
 | Spec / 功能架构 `stage.spec-architecture` | Spec、产品总体设计、功能架构；必要时 Spec Delta | 原生 `work-unit.spec-synthesis`；`to-spec` 为兼容入口 | 初稿先为 `ready-for-human`；只有 Spec baseline 会签批准后资产才为 `approved` 并进入下游 |
 | 产品设计 `stage.product-design` | 交互说明、低保真、状态矩阵、高保真 HTML、评审记录 | `work-unit.prototype-design`；`yss-prototype-stage` 为主合同，依次消费 `yss-design-system`、独立 `prototype-review`、`yss-antd-design` pre-build facts、Codex `product-design:index` focused workflow、post-build/浏览器/无障碍验证（非 Codex 交付等价合同）。前端落地改用 `yss-ui` | `gate.prototype-reviewed`、`gate.prototype-verified`、`gate.user-confirmation` 均有 schema v2 证据 |
 | 系统 / 数据架构与工程契约 `stage.system-data-engineering` | OpenAPI Draft/Freeze、数据架构、工程基线、架构审查；按领域影响执行 Tactical DDD Check | `work-unit.technical-analysis`；`yss-router` + `yss-openapi-governance` / `yss-openapi-draft-review`、`codebase-design`、`implementation-repo-onboarding`、`yss-tactical-design`；用户或合同明确要求架构可视化时条件追加 `archify` | API/架构契约冻结；无 API 影响有明确记录；战术模型无未解释冲突；脚手架策略满足；Archify 图只作派生审查证据；`gate.openapi-draft-reviewed`、`gate.design-reviewed`、`gate.openapi-frozen`、`gate.engineering-baseline-accepted`、`gate.architecture-reviewed` |

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

@@ -20,7 +20,7 @@ Matt skills 决定如何工作；YSS 生命周期决定是否允许推进；YSS
 | 需求澄清 | `grill-with-docs`（用户显式）或 `grilling`、`domain-modeling`（生命周期原语） | 按退出判定检查未决项和回流 |
 | 信息在其他人手中 | `to-questionnaire` | 使用 `external-input-required` 暂停；答案回流后记录 response、重新分类影响面，再进入 `grill-with-docs` 或 `to-spec` |
 | 大型模糊工作 | `wayfinder`（可选） | 仅在跨会话 / 跨 Agent 或 frontier 不清晰时启用；map 真正完成后 `handoff → to-spec` |
-| 技术事实 | `research` | 一手资料回填 Spec/OpenAPI/架构/ADR |
+| 技术或战略事实 | `yss-research`（`research` 为 deprecated alias） | `technical-evidence` 核验一手技术资料；`strategy-evidence` 为领域战略和阶段决策提供可审计证据；研究包不得自行修改或批准下游资产 |
 | runnable 问题 | `prototype` | 生成单文件可分享 HTML，保留 `prototype/<name>` 分支作为主来源；必须 source/return handoff 和结论回填，不得替代阶段 4 的低保真评审、Ant Design v6 高保真 HTML、AntD CLI 证据和用户确认 |
 | Spec 综合 | 原生 `work-unit.spec-synthesis`；`to-spec`（用户显式兼容） | 初稿进入 `ready-for-human`，不得直接实现 |
 | 切片 | 原生 `work-unit.ticket-decomposition`；`to-tickets`（用户显式兼容） | 仅在冻结/无影响记录后拆垂直切片，初始 Ticket 状态为 `ready-for-human` |
@@ -72,7 +72,7 @@ Router 状态映射为：`draft → completed`、`blocked → blocked`、`ready-
 | `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` |
 
-`grill_exit` 不是“已经聊过”的自然语言声明。它必须同时证明 frontier 为空、事实已解决或分别路由到 `research` / prototype / external input、用户决策已确认、双方共同理解已确认，并且没有未回流的 runnable blocker。
+`grill_exit` 不是“已经聊过”的自然语言声明。它必须同时证明 frontier 为空、事实已解决或分别路由到 `yss-research` / prototype / external input、用户决策已确认、双方共同理解已确认，并且没有未回流的 runnable blocker。
 
 ## Review 候选与 Git 授权
 

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

@@ -172,8 +172,8 @@ task_package:
 matt_invocation_boundary:
   user_invoked_skills: [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]
   lifecycle_managed_user_entries: [setup-matt-pocock-skills, grill-with-docs, to-spec, to-tickets, implement]
-  model_invoked_skills: [code-review, codebase-design, diagnosing-bugs, domain-modeling, grilling, migrate-to-shoehorn, prototype, research, resolving-merge-conflicts, scaffold-exercises, setup-pre-commit, tdd, writing-for-agents]
-  lifecycle_allowed_model_invoked_skills: [code-review, codebase-design, diagnosing-bugs, domain-modeling, grilling, prototype, research, tdd]
+  model_invoked_skills: [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]
+  lifecycle_allowed_model_invoked_skills: [code-review, codebase-design, diagnosing-bugs, domain-modeling, grilling, prototype, tdd, yss-research]
   lifecycle_may_invoke_user_invoked: false
   formal_artifact_owner: explicit-user-entry
   continuous_orchestration: compatibility-prepare-and-validate-only
@@ -199,9 +199,9 @@ work_unit_routes:
   work-unit.discovery-opportunity:
     native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
     primary_skill: yss-product-lifecycle
-    supporting_skills: [competitive-intelligence, research]
-    skills: [competitive-intelligence, research]
-    route_by: {market_or_competitor_fact: competitive-intelligence, technical_or_standard_fact: research, no_external_fact: yss-product-lifecycle}
+    supporting_skills: [competitive-intelligence, yss-research]
+    skills: [competitive-intelligence, yss-research]
+    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:
@@ -214,16 +214,18 @@ work_unit_routes:
   work-unit.domain-strategy-design:
     native: {source: yss-product-lifecycle, skill: yss-stage-decision, invocation_mode: model-invoked}
     primary_skill: yss-stage-decision
-    supporting_skills: [domain-modeling, research, grilling]
-    skills: [yss-stage-decision, domain-modeling, research, grilling]
+    supporting_skills: [domain-modeling, yss-research, grilling]
+    skills: [yss-stage-decision, domain-modeling, yss-research, grilling]
+    research_contract: {profile: strategy-evidence, mode_before_gate: evidence-audited, artifact_owner: yss-research, downstream_owner: yss-stage-decision}
     human_gate: domain-strategy-approved
     applies_when: domain_boundary_or_language_or_core_rule_impact
     not_applicable_reason: no_domain_strategy_impact
   work-unit.stage-decision:
     native: {source: yss-product-lifecycle, skill: yss-stage-decision, invocation_mode: model-invoked}
     primary_skill: yss-stage-decision
-    supporting_skills: [domain-modeling]
-    skills: [yss-stage-decision, domain-modeling]
+    supporting_skills: [domain-modeling, yss-research]
+    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
     not_applicable_reason: existing_approved_stage_decision_current
@@ -420,7 +422,7 @@ transition_graph:
 grill_exit:
   required: [frontier_empty, facts_resolved_or_routed, decisions_confirmed, shared_understanding_confirmed, no_unresolved_runnable_blocker]
   facts_resolved_or_routed:
-    technical_fact: research
+    technical_fact: yss-research
     runnable_question: handoff-prototype-handoff
     external_decision: external-input-required
   user_confirmation_required: true

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

@@ -53,7 +53,7 @@ tracker 选择和冲突按 `docs/agents/issue-tracker.md` 裁决：已持久化
 
 - `work-unit.technical-analysis` 命中聚合、状态机、不变量、一致性、Domain Event、Gateway 或持久化映射影响时，先调度 `yss-tactical-design` 完成 Tactical DDD Check；默认嵌入系统概要设计 / 数据架构，复杂场景才生成 `artifact.tactical-design`。无领域影响记录 `not-applicable`。该 skill 只返回设计合同和验证结果，批准仍由生命周期编排器维护，发现 `stale`、`drift` 或 `new_impacts` 时不得继续 Ticket 正式化。
 
-- `work-unit.discovery-requirements` 实际调用 `grilling` 和 `domain-modeling`；`work-unit.discovery-opportunity` 按事实类型路由 `competitive-intelligence` 或 `research`。生命周期原生工作单元默认负责 Spec、Ticket 和实现资产；`to-spec`、`to-tickets`、`implement` 仅保留为显式兼容入口，结果必须回交生命周期验收。
+- `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.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、原型和技术分析不得直接跳转到 `work-unit.slice-implementation`，只能先进入 `work-unit.ticket-decomposition`。
@@ -105,7 +105,7 @@ Decision ticket 产生决策，不是实现切片，不得标记 `ready-for-agen
 
 ## `grill-with-docs` 退出判定
 
-进入 `to-spec` 前必须区分已确认项与未决项，并确认用户、问题、MVP、非目标、成功标准、术语/ADR 候选和测试 seam。事实问题走 `research`；需 runnable 反馈的问题走 `handoff → prototype → handoff`。存在未回流 blocker 时不得进入 Spec baseline。
+进入 `to-spec` 前必须区分已确认项与未决项，并确认用户、问题、MVP、非目标、成功标准、术语/ADR 候选和测试 seam。事实问题走 `yss-research`；需 runnable 反馈的问题走 `handoff → prototype → handoff`。存在未回流 blocker 时不得进入 Spec baseline。
 
 Prototype 回流必须有可核验证据：来源 handoff、prototype 资产或运行记录、结论、被更新的 Spec/设计/ADR/Ticket 引用、剩余未决项和返回 handoff。仅在对话中声称“已验证”不算回流完成。
 

package/template/.agents/skills/yss-repository/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yss-repository
-description: Use when generating or refactoring YSS persistence models, BaseRepository/MyBatis repositories, MapStruct convertors, Domain Gateway implementations, or metadata/DDL-backed queries.
+description: Use when generating or refactoring YSS Infrastructure persistence models, repositories, MapStruct convertors, Domain Gateway implementations, or metadata/DDL-backed queries.
 ---
 
 # yss-repository
@@ -21,27 +21,29 @@ description: Use when generating or refactoring YSS persistence models, BaseRepo
 
 ## 工作方式
 
-1. 先确认输入来源：领域模型、metadata、数据库表、DDL。
+1. 先确认批准且版本当前的 Slice Implementation Contract、数据架构、领域模型和既有 Domain Gateway/Application Query Port；缺任一前置项即返回 `blocked` / `new_impacts`，不得从 DDL 反向猜测领域端口。
 2. 确认持久化 Profile 为 `mybatis-plus` 与 `PO <-> Domain Model`；`Entity + BaseRepository + DTO/VO GatewayImpl` 等旧架构对新脚手架为 `unsupported`。
 3. 如果 metadata 不完整，先补齐 metadata、数据库表结构或 DDL 输入。
-4. 涉及 POJO 字段、getter/setter、constructor、builder 或日志时，必须加载并遵守 `lombok`。
-5. 涉及持久化模型与 Domain/Application Result 转换时，必须加载并遵守 `mapstruct`；Infrastructure 不生成 Web VO/CMD 转换。
-6. 生成代码时严格保持 Domain 与 Infrastructure 分层边界。
-7. 默认先生成基础 CRUD 骨架，把复杂查询留给手工实现。
+4. 加载并遵守固定 Profile 的 `yss-mybatis`，不得在本 skill 内维护第二套 Mapper、分页或 SQL 安全规则。
+5. 涉及 POJO 字段、getter/setter、constructor、builder 或日志时，必须加载并遵守 `lombok`。
+6. 涉及持久化模型与 Domain/Application Result 转换时，必须加载并遵守 `mapstruct`；Infrastructure 不生成 Web VO/CMD 转换。
+7. 生成代码时严格保持 Domain 与 Infrastructure 分层边界。
+8. 默认先生成基础 CRUD 骨架，把复杂查询留给手工实现。
 
 ## 产物范围
 
-- `domain/{segment}/gateway/*Gateway.java`
-- `repository/entity/*PO.java`
-- `repository/*Repository.java`
-- `repository/convertor/*Convertor.java`
-- `repository/gateway/impl/*GatewayImpl.java`
-- `query/adapter/*QueryAdapter.java`（实现 Application Query Port）
+- `infrastructure/persistence/po/*PO.java`
+- `infrastructure/persistence/repository/*Repository.java`
+- `infrastructure/persistence/convertor/*Convertor.java`
+- `infrastructure/persistence/gateway/*GatewayImpl.java`
+- `infrastructure/query/adapter/*QueryAdapter.java`（实现 Application Query Port）
+- `infrastructure/query/convertor/*QueryConvertor.java`
 
 ## 约束
 
 - Domain 不依赖 Infrastructure。
 - Gateway 定义在 Domain，实现放在 Infrastructure。
+- `yss-repository` 不创建或改写 Domain Gateway interface；缺少或需要改变 Gateway 时返回 `new_impacts`，由 Router 回到 `yss-domain` / `yss-tactical-design`。
 - Domain Gateway 只交换 Domain Model、领域值和标识；分页、列表和读模型走 Application Query Port，禁止返回 Web VO 或把 `PageQuery` 带入 Domain。
 - PO / Domain Model 等 POJO 样板代码优先使用 Lombok；不要成片手写 getter/setter、constructor、builder 或 logger。
 - Convertor 必须优先使用 `@Mapper(componentModel = "spring")` 和构造器注入；禁止静态 `INSTANCE`、`BeanUtils.copyProperties`、反射式通用拷贝和重复手写字段赋值，除非实现合同记录受控例外、测试和 review 证据。
@@ -55,7 +57,7 @@ description: Use when generating or refactoring YSS persistence models, BaseRepo
 - 命名、包路径、注解要与工程现有规范一致。
 - Convertor 必须有 MapStruct 接口 / 抽象类、生成实现可编译，必要时补 mapper 单测或覆盖核心字段转换的行为测试。
 - POJO 使用 Lombok 时不得引入 `@Data` 造成实体 equals / toString 风险；有关系字段、敏感字段或懒加载字段时按 `lombok` skill 排除。
-- 遇到无法自动判断的字段或规则时，写 TODO 或向用户说明，不要假装已确认。
+- 遇到无法自动判断的字段、映射或查询规则时返回 `new_impacts` / `drift` 并暂停，不要把 TODO 当作已完成实现。
 
 ## 协同顺序
 

package/template/.agents/skills/yss-repository/agents/openai.yaml

@@ -1,5 +1,5 @@
 version: 1
 interface:
   display_name: "YSS Repository"
-  short_description: "Repository、Convertor 与 gateway 实现规范"
-  default_prompt: "Use $yss-repository to generate or refactor YSS repository, convertor, and gateway implementation code."
+  short_description: "Infrastructure Repository、Mapper、Convertor 与端口实现规范"
+  default_prompt: "Use $yss-repository to implement Infrastructure persistence and query adapters against existing Domain Gateway and Application Query Port interfaces without creating domain contracts."

package/template/.agents/skills/yss-repository/references/infrastructure-layer-guide.md

@@ -4,7 +4,7 @@
 
 ## 1. 职责
 
-- 实现 Domain Gateway，负责 Aggregate 持久化。
+- 实现既有 Domain Gateway，负责 Aggregate 持久化；不创建或改写 Gateway interface。
 - 实现 Application Query Port，负责分页、列表和读模型。
 - 定义 PO、MyBatis-Plus Repository/Mapper、XML 和数据源适配。
 - 通过 Spring MapStruct Bean 完成 `PO <-> Domain Model`、`PO -> Application Result`。

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

@@ -0,0 +1,73 @@
+---
+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.
+---
+
+# YSS Research
+
+Investigate facts that a YSS decision depends on. Produce evidence and bounded conclusions; do not make or approve the downstream product, domain, architecture, or release decision.
+
+`research` is a deprecated compatibility alias. Use `yss-research` in new assets and routing.
+
+## Profiles
+
+- `technical-evidence`: standards, official documentation, source code, third-party APIs, framework behavior, protocols, or implementation constraints. Decision-bearing claims must trace to primary sources.
+- `strategy-evidence`: user problems, business constraints, MVP/non-goal evidence, success criteria, domain-boundary signals, core business-rule evidence, and stage-decision inputs. This profile may consume direct-experience and near-primary evidence with explicit limitations.
+
+Route competitor, pricing, category, and market-position research to `competitive-intelligence`; consume its cited result rather than duplicating it. Route product UI and workflow-friction scans to `product-design:research` when that platform skill is available. `yss-research` may synthesize their outputs but does not replace their specialist contracts.
+
+## Modes
+
+- `quick` is the default for exploratory fact finding. Return an in-chat brief unless the user asks to persist it.
+- `evidence-audited` is required when research directly informs a persisted Spec, domain strategy, stage decision, OpenAPI, architecture decision, or another lifecycle approval input. It is also used when the user explicitly asks for deep, strict, reproducible, or auditable research.
+
+Do not silently promote an exploratory request solely because more rigor would be nice. State the active profile and mode before searching; explain when a downstream lifecycle use requires promotion.
+
+## Source policy
+
+1. Start from the decision, audience, time horizon, scope, and questions the research must answer.
+2. Search user-provided or registered material first, using the same inclusion and exclusion criteria as external material. Record exclusions and access failures.
+3. For `technical-evidence`, follow each decision-bearing claim to the official specification, official docs, source code, or first-party API that owns it.
+4. For `strategy-evidence`, classify sources as primary, direct experience, near-primary, secondary, or lead-only. Interviews, tickets, support records, dated reviews, surveys, and credible industry reports are allowed with their sampling and access limits.
+5. Treat untraceable reposts, aggregator snippets, and AI-generated summaries as leads only. They cannot support a published claim.
+6. Seek counter-signals and conflicting evidence. Source count alone is not frequency or confidence.
+
+## Delegation
+
+Use a background Agent when the runtime supports it and the reading can proceed independently while other useful work continues. Otherwise research in the current Agent. Delegation is an execution optimization, not a trust signal.
+
+Lifecycle dispatches must use the repository's structured task package, write isolation, role binding, and handoff contract. The owner receiving the result remains responsible for verifying material claims before consuming them.
+
+## Evidence-audited workflow
+
+Follow [evidence-contract.md](references/evidence-contract.md):
+
+1. Predeclare the research scope, source classes, inclusion/exclusion criteria, and known access limits.
+2. Maintain a reproducible Search Log and independently locatable Evidence Ledger.
+3. Separate observations, inference, hypotheses, and decisions.
+4. Audit each decision-bearing claim against the evidence it cites, including counter-signals.
+5. Narrow partially supported claims; mark unsupported claims `needs-deeper-research`.
+6. Persist `<slug>-research-brief.md` with adjacent `<slug>-evidence.yaml` and run the bundled validator.
+
+For `strategy-evidence`, every claim that determines a user problem, MVP/non-goal, domain boundary, core business rule, success criterion, important business constraint, or stage-decision basis is decision-bearing and must be audited. Background context may be sampled only when explicitly marked non-decision-bearing.
+
+## Ownership boundary
+
+- Research output is evidence, not approval.
+- `domain-modeling` owns glossary changes; `yss-stage-decision` owns domain strategy and the stage-decision package.
+- The lifecycle orchestrator and designated reviewers own gate state.
+- Do not modify `CONTEXT.md`, Spec, domain-strategy, OpenAPI, architecture, Ticket status, or approval records unless a separately authorized owning work unit performs that change.
+
+## Output
+
+A quick brief includes scope, findings, sources, inference, confidence, counter-signals, gaps, and the next decision it informs.
+
+For persisted `evidence-audited` work, start from [research-brief-template.md](assets/research-brief-template.md) and [evidence-template.yaml](assets/evidence-template.yaml). Run from this skill directory:
+
+```bash
+node scripts/validate-research-package.mjs <slug>-research-brief.md <slug>-evidence.yaml
+```
+
+In `template-source`, save reusable maintenance research under the existing `.template-source/evidence/maintenance/` convention. In `project-instance`, use the project research/evidence convention and bind any decision-bearing output from the lifecycle asset that consumes it.
+
+If sources are unavailable or conflict, state the limitation. Ordinary gaps lower confidence; a missing or mismatched source for a decision-bearing claim prevents that claim from being treated as established.

package/template/.agents/skills/yss-research/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "YSS Research"
+  short_description: "Research technical and strategy evidence"