create-yss-spec 2.2.10 → 3.0.0

package/template/.cursor/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/.cursor/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/.cursor/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/.cursor/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/.cursor/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/.cursor/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/.cursor/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/.cursor/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/.cursor/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/.cursor/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/.cursor/skills/yss-research/agents/openai.yaml

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

package/template/.cursor/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/.cursor/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/.cursor/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/.cursor/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;
+}