create-yss-spec 2.2.10 → 3.0.0

package/template/.agents/skills/yss-research/assets/evidence-template.yaml

@@ -0,0 +1,68 @@
+{
+  "schema_version": 1,
+  "profile": "strategy-evidence",
+  "mode": "evidence-audited",
+  "scope": {
+    "topic": "<topic>",
+    "audience": "<audience>",
+    "time_horizon": "<time horizon>",
+    "research_questions": ["<question>"],
+    "inclusion_criteria": ["<criterion>"],
+    "exclusion_criteria": ["<criterion>"]
+  },
+  "ownership": {
+    "research_owner": "yss-research",
+    "downstream_owner": "<lifecycle skill or role>",
+    "decision_ref": null
+  },
+  "search_log": [
+    {
+      "id": "search-001",
+      "channel": "<channel or corpus>",
+      "query_or_corpus": "<query or inspected material>",
+      "searched_at": "YYYY-MM-DD",
+      "result": "results-found"
+    },
+    {
+      "id": "search-002",
+      "channel": "<counter-signal channel>",
+      "query_or_corpus": "<counter-signal query>",
+      "searched_at": "YYYY-MM-DD",
+      "result": "none-found"
+    }
+  ],
+  "evidence_items": [
+    {
+      "id": "evidence-001",
+      "source_level": "direct-experience",
+      "visibility": "internal",
+      "source_class": "<interview, support, ticket, docs, specification, source-code, dataset, report>",
+      "source_ref": "<URL or repository reference>",
+      "locator": "<line, section, record, timestamp, or comment>",
+      "stance": "support",
+      "observed_at": "YYYY-MM-DD",
+      "evidence_date": "YYYY-MM-DD",
+      "observation": "<what the source directly shows>",
+      "limitations": ["<sampling, recency, access, or independence limit>"]
+    }
+  ],
+  "claims": [
+    {
+      "id": "claim-001",
+      "claim_kind": "user-problem",
+      "statement": "<decision-bearing claim>",
+      "decision_bearing": true,
+      "evidence_refs": ["evidence-001"],
+      "counter_signal_refs": ["search-002"],
+      "audit_status": "supported",
+      "confidence": "medium",
+      "disposition": "publish"
+    }
+  ],
+  "source_gaps": [],
+  "audit_summary": {
+    "status": "complete",
+    "audited_claim_ids": ["claim-001"],
+    "notes": []
+  }
+}

package/template/.agents/skills/yss-research/assets/research-brief-template.md

@@ -0,0 +1,36 @@
+# <Topic> Research Brief
+
+## Research Scope
+
+- Profile: `technical-evidence` or `strategy-evidence`
+- Mode: `evidence-audited`
+- Decision informed:
+- Audience:
+- Time horizon:
+- Inclusion criteria:
+- Exclusion criteria:
+- Access limitations:
+
+## Executive Read
+
+Summarize the evidence-backed answer and its decision boundary.
+
+## Findings
+
+For every decision-bearing finding, cite its `claim-*` ID and source links. Separate observation, inference, hypothesis, and recommendation.
+
+## Counter-Signals
+
+Describe conflicting evidence and unsuccessful counterexample searches without treating `none-found` as proof of absence.
+
+## Source Map
+
+Explain what each source class contributed, exclusions, access failures, and weak areas.
+
+## Decision Handoff
+
+Identify the downstream owner and asset. State explicitly that this research does not approve or mutate that asset.
+
+## Evidence Limitations
+
+List sampling, recency, independence, access, and provenance limits plus any `needs-deeper-research` claims.

package/template/.agents/skills/yss-research/references/evidence-contract.md

@@ -0,0 +1,42 @@
+# YSS Research Evidence Contract
+
+This contract defines the persisted `evidence-audited` package. The Markdown brief is the readable narrative; the adjacent evidence file is the source of truth for search execution, provenance, claim mapping, audit state, and downstream ownership.
+
+## Evidence levels
+
+| Level | Meaning | Allowed use |
+|---|---|---|
+| `primary` | Official specification, official documentation, first-party API, source code, filing, or original dataset | Required for decision-bearing `technical-evidence` claims |
+| `direct-experience` | Interview, support record, ticket, direct observation, telemetry, or original user report | May support `strategy-evidence`; state sampling and access limits |
+| `near-primary` | Dated review, vendor case study, marketplace record, or a report with inspectable methodology | May support strategy claims with qualification |
+| `secondary` | Reputable synthesis that identifies its underlying evidence | Context or corroboration; avoid as the sole basis for high-impact decisions |
+| `lead-only` | Aggregator snippet, unattributed repost, or AI-generated summary | Search lead only; never a supporting evidence reference |
+
+## Search and counter-signals
+
+Each material query or corpus inspection has a stable `search-*` ID, execution date, channel, query/corpus, and result. Allowed results are `results-found`, `none-found`, `access-failed`, and `excluded`.
+
+Each claim must name supporting evidence and at least one counter-signal. A counter-signal is either an `evidence-*` item marked `counter` or a `search-*` entry with `none-found`. A `none-found` search only proves that the declared search did not find a counterexample.
+
+## Claim audit
+
+Allowed outcomes:
+
+- `supported`: the evidence directly supports the wording;
+- `partially-supported`: only a narrower, qualified wording is supportable;
+- `unsupported`: the source does not support the claim;
+- `not-audited`: temporary state, forbidden when the package says audit is complete.
+
+`partially-supported` requires disposition `qualify`. `unsupported` requires `needs-deeper-research`. `lead-only` items cannot be cited as support. In `technical-evidence`, every decision-bearing claim needs at least one `primary` supporting item.
+
+In `strategy-evidence`, decision-bearing kinds are `user-problem`, `business-constraint`, `domain-boundary`, `business-rule`, `mvp`, `non-goal`, `success-criterion`, and `stage-decision-basis`. These claims must all be present in `audit_summary.audited_claim_ids` before downstream lifecycle consumption.
+
+## Ownership and failure
+
+The package names its downstream owner and optional decision reference. It does not change the owned artifact or gate. Structure errors, unresolved references, decision-bearing unaudited claims, or a false `complete` declaration fail validation. Access gaps and conflicting evidence are recorded in `source_gaps`; they do not fail the entire brief unless they leave a decision-bearing claim unsupported.
+
+The evidence file uses JSON syntax, which is valid YAML 1.2, so validation is portable and dependency-free.
+
+## Design provenance
+
+The Search Log, evidence passport, and claim-source alignment concepts are adapted from [Academic Research Skills](https://github.com/Imbad0202/academic-research-skills). This YSS contract omits academic writing, publication, fixed agent teams, and cross-model review machinery, and retains YSS lifecycle ownership boundaries.

package/template/.agents/skills/yss-research/scripts/validate-research-package.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+const PROFILE_VALUES = ["technical-evidence", "strategy-evidence"];
+const SOURCE_LEVELS = ["primary", "direct-experience", "near-primary", "secondary", "lead-only"];
+const CLAIM_KINDS = ["technical-fact", "user-problem", "business-constraint", "domain-boundary", "business-rule", "mvp", "non-goal", "success-criterion", "stage-decision-basis", "background"];
+const STRATEGY_DECISION_KINDS = new Set(["user-problem", "business-constraint", "domain-boundary", "business-rule", "mvp", "non-goal", "success-criterion", "stage-decision-basis"]);
+
+function fail(message) { throw new TypeError(message); }
+function requireString(value, label) { if (typeof value !== "string" || !value.trim()) fail(`${label} must be a non-empty string`); }
+function requireArray(value, label, nonEmpty = false) { if (!Array.isArray(value) || (nonEmpty && value.length === 0)) fail(`${label} must be ${nonEmpty ? "a non-empty" : "an"} array`); }
+function requireChoice(value, choices, label) { if (!choices.includes(value)) fail(`${label} must be one of: ${choices.join(", ")}`); }
+
+function indexed(items, label) {
+  const result = new Map();
+  items.forEach((item, index) => {
+    requireString(item?.id, `${label}[${index}].id`);
+    if (result.has(item.id)) fail(`${label} contains duplicate id: ${item.id}`);
+    result.set(item.id, item);
+  });
+  return result;
+}
+
+function readEvidence(file) {
+  try {
+    const value = JSON.parse(readFileSync(file, "utf8"));
+    if (!value || typeof value !== "object" || Array.isArray(value)) fail("evidence root must be an object");
+    return value;
+  } catch (error) {
+    if (error instanceof TypeError && error.message === "evidence root must be an object") throw error;
+    fail(`${path.basename(file)} must use JSON-compatible YAML 1.2 syntax: ${error.message}`);
+  }
+}
+
+function validate(briefFile, evidenceFile) {
+  if (!briefFile || !evidenceFile) fail("usage: validate-research-package.mjs <brief.md> <evidence.yaml>");
+  const briefPath = path.resolve(briefFile);
+  const evidencePath = path.resolve(evidenceFile);
+  if (path.dirname(briefPath) !== path.dirname(evidencePath)) fail("brief and evidence files must be adjacent");
+  if (!briefPath.endsWith("-research-brief.md") || !evidencePath.endsWith("-evidence.yaml")) fail("expected <slug>-research-brief.md and <slug>-evidence.yaml");
+  const briefSlug = path.basename(briefPath, "-research-brief.md");
+  if (!briefSlug || briefSlug !== path.basename(evidencePath, "-evidence.yaml")) fail("brief and evidence files must use the same non-empty slug");
+
+  const brief = readFileSync(briefPath, "utf8");
+  ["Research Scope", "Executive Read", "Findings", "Counter-Signals", "Source Map", "Decision Handoff", "Evidence Limitations"].forEach((heading) => {
+    if (!brief.includes(`## ${heading}`)) fail(`brief is missing heading: ## ${heading}`);
+  });
+
+  const data = readEvidence(evidencePath);
+  if (data.schema_version !== 1) fail("schema_version must be 1");
+  requireChoice(data.profile, PROFILE_VALUES, "profile");
+  if (data.mode !== "evidence-audited") fail("mode must be evidence-audited");
+  ["topic", "audience", "time_horizon"].forEach((field) => requireString(data.scope?.[field], `scope.${field}`));
+  ["research_questions", "inclusion_criteria", "exclusion_criteria"].forEach((field) => requireArray(data.scope?.[field], `scope.${field}`, true));
+  if (data.ownership?.research_owner !== "yss-research") fail("ownership.research_owner must be yss-research");
+  requireString(data.ownership?.downstream_owner, "ownership.downstream_owner");
+  if (data.ownership.decision_ref !== null && (typeof data.ownership.decision_ref !== "string" || !data.ownership.decision_ref.trim())) fail("ownership.decision_ref must be null or a non-empty string");
+
+  requireArray(data.search_log, "search_log", true);
+  const searches = indexed(data.search_log, "search_log");
+  data.search_log.forEach((entry, index) => {
+    ["channel", "query_or_corpus", "searched_at"].forEach((field) => requireString(entry[field], `search_log[${index}].${field}`));
+    requireChoice(entry.result, ["results-found", "none-found", "access-failed", "excluded"], `search_log[${index}].result`);
+  });
+
+  requireArray(data.evidence_items, "evidence_items", true);
+  const evidence = indexed(data.evidence_items, "evidence_items");
+  data.evidence_items.forEach((item, index) => {
+    requireChoice(item.source_level, SOURCE_LEVELS, `evidence_items[${index}].source_level`);
+    requireChoice(item.visibility, ["public", "internal"], `evidence_items[${index}].visibility`);
+    requireChoice(item.stance, ["support", "counter"], `evidence_items[${index}].stance`);
+    ["source_class", "source_ref", "locator", "observed_at", "observation"].forEach((field) => requireString(item[field], `evidence_items[${index}].${field}`));
+    requireArray(item.limitations, `evidence_items[${index}].limitations`);
+  });
+
+  requireArray(data.claims, "claims", true);
+  const claims = indexed(data.claims, "claims");
+  data.claims.forEach((claim, index) => {
+    requireChoice(claim.claim_kind, CLAIM_KINDS, `claims[${index}].claim_kind`);
+    requireString(claim.statement, `claims[${index}].statement`);
+    if (typeof claim.decision_bearing !== "boolean") fail(`claims[${index}].decision_bearing must be boolean`);
+    requireArray(claim.evidence_refs, `claims[${index}].evidence_refs`, true);
+    requireArray(claim.counter_signal_refs, `claims[${index}].counter_signal_refs`, true);
+    requireChoice(claim.audit_status, ["supported", "partially-supported", "unsupported", "not-audited"], `claims[${index}].audit_status`);
+    requireChoice(claim.confidence, ["low", "medium", "high"], `claims[${index}].confidence`);
+    requireChoice(claim.disposition, ["publish", "qualify", "needs-deeper-research"], `claims[${index}].disposition`);
+
+    const supporting = claim.evidence_refs.map((ref) => {
+      if (!evidence.has(ref)) fail(`${claim.id} has unresolved evidence ref: ${ref}`);
+      const item = evidence.get(ref);
+      if (item.stance !== "support") fail(`${claim.id} support ref is not marked support: ${ref}`);
+      if (item.source_level === "lead-only") fail(`${claim.id} uses lead-only evidence as support: ${ref}`);
+      return item;
+    });
+    claim.counter_signal_refs.forEach((ref) => {
+      if (!evidence.has(ref) && !searches.has(ref)) fail(`${claim.id} has unresolved counter-signal ref: ${ref}`);
+      if (evidence.has(ref) && evidence.get(ref).stance !== "counter") fail(`${claim.id} counter-signal evidence is not marked counter: ${ref}`);
+      if (searches.has(ref) && searches.get(ref).result !== "none-found") fail(`${claim.id} counter-signal search must have result none-found: ${ref}`);
+    });
+    if (data.profile === "technical-evidence" && claim.decision_bearing && !supporting.some((item) => item.source_level === "primary")) fail(`${claim.id} is a decision-bearing technical claim without primary evidence`);
+    if (data.profile === "strategy-evidence" && STRATEGY_DECISION_KINDS.has(claim.claim_kind) && claim.decision_bearing !== true) fail(`${claim.id} strategy claim kind must be decision-bearing: ${claim.claim_kind}`);
+    if (claim.audit_status === "partially-supported" && claim.disposition !== "qualify") fail(`${claim.id} is partially supported and must use qualify`);
+    if (claim.audit_status === "unsupported" && claim.disposition !== "needs-deeper-research") fail(`${claim.id} is unsupported and must use needs-deeper-research`);
+    if (claim.decision_bearing && claim.audit_status === "unsupported") fail(`${claim.id} is decision-bearing and cannot remain unsupported`);
+    if (!brief.includes(claim.id)) fail(`brief does not reference claim: ${claim.id}`);
+  });
+
+  requireArray(data.source_gaps, "source_gaps");
+  if (data.audit_summary?.status !== "complete") fail("audit_summary.status must be complete");
+  requireArray(data.audit_summary.audited_claim_ids, "audit_summary.audited_claim_ids", true);
+  requireArray(data.audit_summary.notes, "audit_summary.notes");
+  const audited = new Set(data.audit_summary.audited_claim_ids);
+  audited.forEach((id) => { if (!claims.has(id)) fail(`audit_summary has unknown claim: ${id}`); });
+  claims.forEach((claim, id) => {
+    if (claim.decision_bearing && !audited.has(id)) fail(`audit_summary is missing decision-bearing claim: ${id}`);
+    if (claim.decision_bearing && claim.audit_status === "not-audited") fail(`${id} remains not-audited`);
+  });
+  return { claims: claims.size, evidence: evidence.size, searches: searches.size, profile: data.profile };
+}
+
+try {
+  const result = validate(process.argv[2], process.argv[3]);
+  process.stdout.write(`YSS research package valid (${result.profile}, ${result.claims} claims, ${result.evidence} evidence items, ${result.searches} searches)\n`);
+} catch (error) {
+  process.stderr.write(`YSS research package invalid: ${error.message}\n`);
+  process.exitCode = 1;
+}

package/template/.agents/skills/yss-research/tests/run-scenarios.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const validator = path.join(root, "scripts/validate-research-package.mjs");
+const template = JSON.parse(readFileSync(path.join(root, "assets/evidence-template.yaml"), "utf8"));
+const directory = mkdtempSync(path.join(tmpdir(), "yss-research-"));
+const brief = path.join(directory, "sample-research-brief.md");
+const evidence = path.join(directory, "sample-evidence.yaml");
+const headings = ["Research Scope", "Executive Read", "Findings", "Counter-Signals", "Source Map", "Decision Handoff", "Evidence Limitations"];
+
+function run(payload, status, expected) {
+  writeFileSync(brief, `${headings.map((heading) => `## ${heading}`).join("\n\n")}\n\n${payload.claims.map((claim) => claim.id).join(" ")}\n`);
+  writeFileSync(evidence, `${JSON.stringify(payload, null, 2)}\n`);
+  const result = spawnSync(process.execPath, [validator, brief, evidence], { encoding: "utf8" });
+  if (result.status !== status || !`${result.stdout}${result.stderr}`.includes(expected)) throw new Error(`expected ${status}/${expected}, got ${result.status}: ${result.stdout}${result.stderr}`);
+}
+
+try {
+  template.scope.topic = "Example strategy question";
+  template.scope.audience = "Product team";
+  template.scope.time_horizon = "Last 12 months";
+  template.scope.research_questions = ["Which problem should the domain address?"];
+  template.scope.inclusion_criteria = ["Direct experience in scope"];
+  template.scope.exclusion_criteria = ["Untraceable reposts"];
+  template.ownership.downstream_owner = "yss-stage-decision";
+  template.search_log[0].channel = "Support records";
+  template.search_log[0].query_or_corpus = "failed approval workflow";
+  template.search_log[0].searched_at = "2026-09-03";
+  template.search_log[1].channel = "Support records";
+  template.search_log[1].query_or_corpus = "successful approval workflow";
+  template.search_log[1].searched_at = "2026-09-03";
+  template.evidence_items[0].source_class = "support";
+  template.evidence_items[0].source_ref = "support-case-001";
+  template.evidence_items[0].locator = "event-3";
+  template.evidence_items[0].observed_at = "2026-09-03";
+  template.evidence_items[0].evidence_date = "2026-08-30";
+  template.evidence_items[0].observation = "The approval stopped when the owner was missing.";
+  template.evidence_items[0].limitations = ["Single support case"];
+  template.claims[0].statement = "A missing owner can block the approval workflow.";
+  run(template, 0, "YSS research package valid");
+
+  const falseStrategyBackground = structuredClone(template);
+  falseStrategyBackground.claims[0].decision_bearing = false;
+  run(falseStrategyBackground, 1, "strategy claim kind must be decision-bearing");
+
+  const unsupported = structuredClone(template);
+  unsupported.claims[0].audit_status = "unsupported";
+  unsupported.claims[0].disposition = "publish";
+  run(unsupported, 1, "must use needs-deeper-research");
+
+  const unsupportedDecision = structuredClone(template);
+  unsupportedDecision.claims[0].audit_status = "unsupported";
+  unsupportedDecision.claims[0].disposition = "needs-deeper-research";
+  run(unsupportedDecision, 1, "decision-bearing and cannot remain unsupported");
+
+  const falseCounter = structuredClone(template);
+  falseCounter.claims[0].counter_signal_refs = ["search-001"];
+  run(falseCounter, 1, "counter-signal search must have result none-found");
+
+  const technicalWithoutPrimary = structuredClone(template);
+  technicalWithoutPrimary.profile = "technical-evidence";
+  technicalWithoutPrimary.claims[0].claim_kind = "technical-fact";
+  run(technicalWithoutPrimary, 1, "technical claim without primary evidence");
+
+  const leadOnly = structuredClone(template);
+  leadOnly.evidence_items[0].source_level = "lead-only";
+  run(leadOnly, 1, "uses lead-only evidence as support");
+
+  const unaudited = structuredClone(template);
+  unaudited.audit_summary.audited_claim_ids = [];
+  run(unaudited, 1, "must be a non-empty array");
+
+  process.stdout.write("YSS research scenarios passed (8)\n");
+} finally {
+  rmSync(directory, { recursive: true, force: true });
+}

package/template/.agents/skills/yss-router/references/router-contract.yaml

@@ -5,6 +5,7 @@ skill_aliases:
   api-integration: yss-api-integration
   microapp-commit: yss-microapp-commit
   page-module-development: yss-page-module-development
+  research: yss-research
   use-table-height: yss-use-table-height
   use-tree-height: yss-use-tree-height
 implementation_path_policy:
@@ -197,10 +198,10 @@ dependency_closure:
     always: [alibaba-java-code-style]
     when_conversion: [mapstruct, lombok]
   yss-repository:
-    always: [mapstruct, lombok, alibaba-java-code-style]
-    when_mybatis: [yss-mybatis]
+    always: [yss-mybatis, mapstruct, lombok, alibaba-java-code-style]
   yss-web-controller:
-    always: [yss-dto, mapstruct, lombok, alibaba-java-code-style]
+    always: [yss-dto, yss-validation, mapstruct, lombok, alibaba-java-code-style]
+    when_error_mapping: [yss-exception]
   yss-userinfo:
     always: [yss-dto]
     when_cache_lookup: [yss-cache]
@@ -245,8 +246,11 @@ end_to_end_backend_required:
   - yss-domain
   - yss-application
   - yss-repository
+  - yss-mybatis
   - yss-web-controller
   - yss-dto
+  - yss-exception
+  - yss-validation
   - mapstruct
   - lombok
   - alibaba-java-code-style

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

@@ -17,7 +17,7 @@ description: 编排 Discovery 到 Spec 入口的阶段决策与 DDD 战略设计
 ## 执行顺序
 
 1. 读取 `yss-project.yaml`、`CONTEXT.md`、既有 Discovery/Spec、ADR 和父 Ticket/checkpoint。
-2. 分离事实、决策、假设、约束和未决项；技术事实走 `research`，市场/竞品事实走 `competitive-intelligence`。
+2. 分离事实、决策、假设、约束和未决项；技术事实走 `yss-research` 的 `technical-evidence`，领域边界、业务规则、MVP、非目标、成功标准或阶段推进依据等决策证据走 `strategy-evidence`，市场/竞品事实走 `competitive-intelligence`。
 3. 从业务场景、事件、规则、责任人和失败路径识别子域及限界上下文，不从数据库表或调用链直接反推边界。
 4. 为每个上下文建立本地统一语言；为跨上下文关系记录语义上游/下游、业务决策权、技术传输方向和翻译责任。
 5. 记录核心领域概念候选，不提前锁定 Entity 或 Aggregate。
@@ -31,6 +31,7 @@ description: 编排 Discovery 到 Spec 入口的阶段决策与 DDD 战略设计
 ## 产物与批准
 
 - DDD 资产是事实源，阶段决策包只通过 `domain_strategy_ref` 引用它们。
+- 进入 `gate.domain-strategy-approved` 或 `gate.stage-decision-package-approved` 的外部决策证据必须引用通过校验的 `yss-research` `evidence-audited` 研究包；研究包只提供证据，不得直接修改本技能资产或批准门禁。
 - `stage_decision_package` 必须经过 `draft → ready-for-human → approved`；起草者不得自签。
 - 建议门禁为 `gate.domain-strategy-approved` 和 `gate.stage-decision-package-approved`，实际状态由 `yss-product-lifecycle` 维护；阶段包批准引用必须通过 `scripts/verify-approval-record`，不得用不可读路径或聊天确认替代。
 - 下游只能消费批准且版本当前的包；发现语义冲突返回 `drift` / `new_impacts`，不得静默修改上游。

package/template/.agents/skills/yss-web-controller/SKILL.md

@@ -16,16 +16,17 @@ description: Use when generating or refactoring YSS Web Adapter Controllers, req
 ## 不适用
 
 - 用户只是要新增一个手写复杂接口，不一定要用脚本。
-- 用户还没有稳定的领域模型或 metadata，先补 `yss-domain` 并准备完整的 metadata 输入。
+- 用户还没有稳定的 Application Service、冻结 OpenAPI 或 metadata，先回 Router 补 `yss-application` / `yss-domain` 和相应合同输入。
 
 ## 优先流程
 
-1. 先确认冻结 OpenAPI、批准的 Web generation contract、Application Service 接口、metadata、基础包、模块名、领域 segment 和 web 落盘目录；合同中的 `base_package`、`module_name`、`domain_segment` 必须与 CLI 一致。
-2. 涉及 DTO / VO / CMD / Query POJO 样板代码时，加载并遵守 `lombok`。
-3. 涉及 Domain / Application Result 到 VO / DTO 或 CMD / Query 到输入模型的转换时，加载并遵守 `mapstruct`。
-4. 运行 `node scripts/generate_controller.mjs`。
-5. 生成后检查路径、命名、返回值包装、Application Service 引用、`@Valid`、Lombok 注解和 MapStruct WebConvertor 是否对齐项目。
-6. 对复杂接口做少量手工修正，不在 skill 中承诺自动覆盖全部业务逻辑。
+1. 先确认冻结 OpenAPI、批准且版本当前的 Web generation contract schema v2、Application Service 接口、metadata、基础包、模块名、领域 segment 和 web 落盘目录；合同必须绑定 Slice `contract_id` / `contract_version` / `slice_id`、`yss-dto` wire profile 引用与 digest、允许写路径、证据与验证命令。
+2. 加载并遵守 `yss-dto` 与 `yss-validation`；错误映射影响命中时再加载 `yss-exception`。
+3. 涉及 DTO / VO / CMD / Query POJO 样板代码时，加载并遵守 `lombok`。
+4. 涉及 Domain / Application Result 到 VO / DTO 或 CMD / Query 到输入模型的转换时，加载并遵守 `mapstruct`。
+5. 运行 `node scripts/generate_controller.mjs`。
+6. 生成后检查路径、命名、返回值包装、Application Service 引用、`@Valid`、Lombok 注解和 MapStruct WebConvertor 是否对齐项目。
+7. 对复杂接口做少量手工修正，不在 skill 中承诺自动覆盖全部业务逻辑。
 
 ## 推荐命令
 
@@ -33,6 +34,8 @@ description: Use when generating or refactoring YSS Web Adapter Controllers, req
 node scripts/generate_controller.mjs \
   --metadata-file /path/metadata.json \
   --contract-file /path/approved-web-generation-contract.json \
+  --dto-wire-profile-file /path/to/yss-dto/references/openapi-wire-profile.yaml \
+  --scaffold-manifest-file /path/service/.yss/scaffold-generation.json \
   --base-package com.yss.demo \
   --module-name demo \
   --domain-segment example \
@@ -53,18 +56,21 @@ node scripts/generate_controller.mjs \
 ## 约束
 
 - 生成代码只依赖既有 Application Service；读写操作都禁止绕过 Application。复杂查询经 Application Query Port 接入 Infrastructure。
-- 返回结构保持项目既有 `SingleResult`、`PageResult`、`MultiResult` 体系。
+- 返回包装类、分页默认值、允许字段与 `PageResult.of(...)` 参数语义必须消费合同绑定的 `yss-dto/references/openapi-wire-profile.yaml`；Web skill 不复制或自行维护第二套协议。
 - DTO / VO / CMD / Query 默认用 Lombok 处理 getter/setter、constructor、builder 和日志样板；不要在 Controller 内部类或非约定包临时定义主要 DTO / VO。
 - `WebConvertor` 使用 `@Mapper(componentModel = "spring")` 和构造器注入；禁止静态 `INSTANCE`、在 Controller / Application 中大段手写字段赋值、使用 `BeanUtils.copyProperties` 或反射式通用拷贝。
 - HTTP Request 不继承会暴露内部协作字段的 `PageQuery`；只生成冻结 OpenAPI allowlist 字段，禁止把 `offset`、`needTotalCount`、`tempTotalCount` 变成客户端输入。
+- `fields.<table>.pagination` 必须显式列出 `yss-dto` wire profile 允许暴露的字段子集；模板不得无条件生成字段或自行定义默认值。
 - 先跑脚本，再按项目规范做少量手调。
 - `javax` / `jakarta` validation namespace 必须来自工程基线，不得按记忆选择。
 - 若用户只是要改单个 Controller，先看现有代码，不要盲覆盖整个目录。
-- 脚本是 initialize-only；写入前先规划全部目标，任一目标已存在或传入 `--force` 时整体返回 `unsupported` 且不得留下部分文件。旧项目迁移不属于该生成器。
+- 脚本是 initialize-only；写入前先规划全部目标并校验 `allowed_write_paths`，任一目标已存在或传入 `--force` 时整体返回 `unsupported`。落盘使用排他创建和失败回滚，不得留下部分文件；旧项目迁移不属于该生成器。
+- `integration_mode=existing-project` 保留已登记工程的 Boot 2/Boot 3 能力；`integration_mode=scaffold-v2` 必须提供 `--scaffold-manifest-file`，且 Manifest 已达到 `empty-scaffold-verified`，Profile、基础包和标准 Web module 路径全部一致。
 
 ## 按需读取
 
 - 分层开发规范：`references/web-adapter-layer-guide.md`
+- Web 生成合同 schema：`references/web-generation-contract.schema.json`
 - 生成脚本：`scripts/generate_controller.mjs`
 - Controller 模板：`assets/templates/Controller.java.template`
 - Convertor 模板：`assets/templates/WebConvertor.java.template`
@@ -73,7 +79,7 @@ node scripts/generate_controller.mjs \
 
 ## 阶段 7 合同
 
-- 只消费已批准合同和冻结 OpenAPI/no-impact record；不得用 Controller 或半成品 backend 反向定义产品契约。
+- 只消费已批准且当前的 schema v2 Web generation contract 和冻结 OpenAPI/no-impact record；schema v1 为 `unsupported`，不得自动升级，也不得用 Controller 或半成品 backend 反向定义产品契约。
 - DTO/VO/WebConvertor 机械骨架可用 `controlled-generation`；权限、错误映射、校验语义和接口行为必须使用 `behavior-tdd`。
 - 写入必须位于合同 `allowed_write_paths`，并提供 Controller、DTO/VO、WebConvertor、契约/API 测试和实际验证结果。
 - 按统一 `YSS Skill Execution Result` 返回偏离与新增影响；出现新 API/schema、权限或响应包装变化时暂停并回到 Router/生命周期。

package/template/.agents/skills/yss-web-controller/agents/openai.yaml

@@ -1,5 +1,5 @@
 version: 1
 interface:
   display_name: "YSS Web Controller"
-  short_description: "Web Controller、DTO、VO 与响应封装规范"
-  default_prompt: "Use $yss-web-controller to generate or refactor a YSS REST controller, request DTO, and response VO."
+  short_description: "按批准 Slice/Web 合同生成 Controller、Wire DTO 与 Convertor"
+  default_prompt: "Use $yss-web-controller with an approved schema v2 Web generation contract, frozen OpenAPI, stable Application interfaces, and allowed write paths to generate YSS REST adapters atomically."

package/template/.agents/skills/yss-web-controller/assets/templates/Controller.java.template

@@ -3,8 +3,8 @@ package ${base_package}.rest;
 ${application_service_import}
 ${dto_imports}
 ${web_convertor_import}
-import com.yss.cloud.dto.result.PageResult;
-import com.yss.cloud.dto.result.SingleResult;
+import ${page_result_type};
+import ${single_result_type};
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.*;
 import io.swagger.v3.oas.annotations.Operation;
@@ -30,7 +30,7 @@ public class ${domain_class}Controller {
      */
     @PostMapping("/page")
     @Operation(summary = "分页查询")
-    public PageResult<${response_class}> page(@Valid @RequestBody ${page_request_class} request) {
+    public ${page_result_simple_name}<${response_class}> page(@Valid @RequestBody ${page_request_class} request) {
         return webConvertor.toResponsePage(${query_call});
     }
 
@@ -39,8 +39,8 @@ public class ${domain_class}Controller {
      */
     @GetMapping("/{id}")
     @Operation(summary = "详情查询")
-    public SingleResult<${response_class}> detail(@PathVariable Long id) {
-        return SingleResult.of(webConvertor.toResponse(${detail_call}));
+    public ${single_result_simple_name}<${response_class}> detail(@PathVariable Long id) {
+        return ${single_result_simple_name}.${single_result_factory_method}(webConvertor.toResponse(${detail_call}));
     }
 
     /**
@@ -48,8 +48,8 @@ public class ${domain_class}Controller {
      */
     @PostMapping
     @Operation(summary = "新增")
-    public SingleResult<Long> add(@Valid @RequestBody ${create_request_class} request) {
-        return SingleResult.of(${add_call});
+    public ${single_result_simple_name}<Long> add(@Valid @RequestBody ${create_request_class} request) {
+        return ${single_result_simple_name}.${single_result_factory_method}(${add_call});
     }
 
     /**
@@ -57,8 +57,8 @@ public class ${domain_class}Controller {
      */
     @PutMapping
     @Operation(summary = "更新")
-    public SingleResult<Boolean> update(@Valid @RequestBody ${update_request_class} request) {
-        return SingleResult.of(${update_call});
+    public ${single_result_simple_name}<Boolean> update(@Valid @RequestBody ${update_request_class} request) {
+        return ${single_result_simple_name}.${single_result_factory_method}(${update_call});
     }
 
     /**
@@ -66,7 +66,7 @@ public class ${domain_class}Controller {
      */
     @DeleteMapping("/{id}")
     @Operation(summary = "删除")
-    public SingleResult<Boolean> delete(@PathVariable Long id) {
-        return SingleResult.of(${delete_call});
+    public ${single_result_simple_name}<Boolean> delete(@PathVariable Long id) {
+        return ${single_result_simple_name}.${single_result_factory_method}(${delete_call});
     }
 }

package/template/.agents/skills/yss-web-controller/assets/templates/WebConvertor.java.template

@@ -1,6 +1,6 @@
 package ${base_package}.rest.convertor;
 
-import com.yss.cloud.dto.result.PageResult;
+import ${page_result_type};
 ${application_type_imports}
 import ${base_package}.rest.dto.request.${domain_class}CreateRequest;
 import ${base_package}.rest.dto.request.${domain_class}UpdateRequest;
@@ -22,12 +22,9 @@ public interface ${web_convertor_class} {
 
     List<${domain_class}Response> toResponses(List<${domain_class}Result> source);
 
-    default PageResult<${domain_class}Response> toResponsePage(PageResult<${domain_class}Result> source) {
-        return PageResult.of(
-                toResponses(source.getData()),
-                source.getTotalCount(),
-                source.getPageSize(),
-                source.getPageIndex()
+    default ${page_result_simple_name}<${domain_class}Response> toResponsePage(${page_result_simple_name}<${domain_class}Result> source) {
+        return ${page_result_simple_name}.${page_result_factory_method}(
+${page_result_factory_arguments}
         );
     }
 }

package/template/.agents/skills/yss-web-controller/assets/templates/web/dto/CreateRequest.java.template

@@ -1,6 +1,6 @@
 package ${base_package}.rest.dto.request;
 
-import com.yss.cloud.dto.CommandDTO;
+import ${command_dto_type};
 import lombok.Getter;
 import lombok.Setter;
 import ${validation_namespace}.validation.constraints.NotBlank;
@@ -13,7 +13,7 @@ import java.time.LocalDate;
 /** ${domain_desc}新增请求。字段来自批准的 OpenAPI allowlist。 */
 @Getter
 @Setter
-public class ${domain_class}CreateRequest extends CommandDTO {
+public class ${domain_class}CreateRequest extends ${command_dto_simple_name} {
 
 ${field_declarations}
 }

package/template/.agents/skills/yss-web-controller/assets/templates/web/dto/PageRequest.java.template

@@ -1,8 +1,9 @@
 package ${base_package}.rest.dto.request;
 
-import com.yss.cloud.dto.QueryDTO;
+import ${query_dto_type};
 import lombok.Getter;
 import lombok.Setter;
+import ${validation_namespace}.validation.constraints.Pattern;
 import java.util.Date;
 import java.math.BigDecimal;
 import java.time.LocalDateTime;
@@ -13,12 +14,8 @@ import java.time.LocalDate;
  */
 @Getter
 @Setter
-public class ${domain_class}PageRequest extends QueryDTO {
-    private int pageIndex = 1;
-    private int pageSize = 20;
-    private String orderBy;
-    private String orderDirection;
-    private String groupBy;
+public class ${domain_class}PageRequest extends ${query_dto_simple_name} {
+${pagination_field_declarations}
 
 ${field_declarations}
 }

package/template/.agents/skills/yss-web-controller/assets/templates/web/dto/UpdateRequest.java.template

@@ -1,6 +1,6 @@
 package ${base_package}.rest.dto.request;
 
-import com.yss.cloud.dto.CommandDTO;
+import ${command_dto_type};
 import lombok.Getter;
 import lombok.Setter;
 import ${validation_namespace}.validation.constraints.NotBlank;
@@ -13,7 +13,7 @@ import java.time.LocalDate;
 /** ${domain_desc}更新请求。字段来自批准的 OpenAPI allowlist。 */
 @Getter
 @Setter
-public class ${domain_class}UpdateRequest extends CommandDTO {
+public class ${domain_class}UpdateRequest extends ${command_dto_simple_name} {
 
 ${field_declarations}
 }