npm - create-yss-spec - Versions diffs - 2.2.10 → 3.0.1 - Mend

create-yss-spec 2.2.10 → 3.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1721) hide show

package/template/.trae/skills/yss-prototype-stage/tests/run-scenarios.mjs CHANGED Viewed

@@ -3,152 +3,105 @@ import assert from "node:assert/strict";
 import { mkdtemp, mkdir, readFile, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import {
-  preparePrototype,
-  validatePrototypeEvidence,
-  validatePrototypeProject
-} from "../scripts/prototype-contract.mjs";
+import { prepareFlowPrototype, prepareStaticPrototype, validatePrototypeEvidence, validatePrototypeProject } from "../scripts/prototype-contract.mjs";
 const tempRoot = await mkdtemp(path.join(os.tmpdir(), "yss-prototype-contract-"));
 const projectRoot = path.join(tempRoot, "project");
 const feature = "order-review";
-const prototypeRoot = path.join(projectRoot, "docs/.scratch", feature, "design/prototypes");
-await mkdir(path.join(prototypeRoot, "src"), { recursive: true });
 await mkdir(path.join(projectRoot, "docs/design/tokens"), { recursive: true });
-await writeFile(path.join(prototypeRoot, "package.json"), JSON.stringify({
-  name: "order-review-prototype",
-  private: true,
-  type: "module",
-  scripts: { build: "vite build" },
-  dependencies: { react: "19.2.0", "react-dom": "19.2.0", vite: "6.4.2" }
-}, null, 2));
-await writeFile(path.join(projectRoot, "docs/design/tokens/theme.json"), JSON.stringify({
-  algorithm: "default",
-  token: {
-    colorPrimary: "#3371ff",
-    borderRadius: 6,
-    controlHeight: 32,
-    layoutHeaderHeight: 64
-  }
-}, null, 2));
+await writeFile(path.join(projectRoot, "docs/design/tokens/theme.json"), JSON.stringify({ token: { colorPrimary: "#3371ff", borderRadius: 6, controlHeight: 32 } }, null, 2));
-const before = await validatePrototypeProject({ root: prototypeRoot, targetAntdVersion: "6.6.2" });
-assert(before.errors.some((message) => message.includes("antd")), "RED: starter without antd must fail");
-assert(before.errors.some((message) => message.includes("pnpm-lock.yaml")), "RED: missing pnpm lockfile must fail");
+const h1Root = path.join(projectRoot, "docs/.scratch", feature, "design/prototypes");
+await prepareStaticPrototype({ projectRoot, root: h1Root, feature });
+assert.match(await readFile(path.join(h1Root, "index.html"), "utf8"), /H1 · visual-review/);
+assert.deepEqual((await validatePrototypeProject({ root: h1Root, profile: "H1" })).errors, []);
+await writeFile(path.join(h1Root, "package.json"), "{}\n");
+assert((await validatePrototypeProject({ root: h1Root, profile: "H1" })).errors.some((message) => message.includes("package.json")), "H1 必须拒绝伪构建依赖");
-await preparePrototype({ projectRoot, root: prototypeRoot, feature, targetAntdVersion: "6.6.2", pnpmVersion: "10.15.0" });
-const pkg = JSON.parse(await readFile(path.join(prototypeRoot, "package.json"), "utf8"));
-assert.equal(pkg.dependencies.antd, "6.6.2");
-assert.equal(pkg.packageManager, "pnpm@10.15.0");
-assert.match(await readFile(path.join(prototypeRoot, "src/yss-theme.js"), "utf8"), /compactAlgorithm/);
+const h2Feature = "approval-flow";
+const h2Root = path.join(projectRoot, "docs/.scratch", h2Feature, "design/prototypes");
+await mkdir(path.join(h2Root, "src"), { recursive: true });
+await writeFile(path.join(h2Root, "index.html"), "<!doctype html><div id=app></div>\n");
+await writeFile(path.join(h2Root, "package.json"), JSON.stringify({ name: "approval-flow-prototype", private: true, type: "module", scripts: { build: "vite build" }, dependencies: { react: "19.2.0", "react-dom": "19.2.0", vite: "6.4.2" } }, null, 2));
+await prepareFlowPrototype({ projectRoot, root: h2Root, feature: h2Feature, targetAntdVersion: "6.6.2", pnpmVersion: "10.15.0" });
+await writeFile(path.join(h2Root, "pnpm-lock.yaml"), "lockfileVersion: '9.0'\n");
+await writeFile(path.join(h2Root, "src/App.jsx"), 'import { ConfigProvider } from "antd"; import { yssTheme } from "./yss-theme.js"; export function App(){return <ConfigProvider theme={yssTheme}/>;}\n');
+assert.deepEqual((await validatePrototypeProject({ root: h2Root, profile: "H2", targetAntdVersion: "6.6.2" })).errors, []);
+assert((await validatePrototypeProject({ root: h2Root, profile: "H2", targetAntdVersion: "6.6.1" })).errors.some((message) => message.includes("精确锁定")));
-await writeFile(path.join(prototypeRoot, "pnpm-lock.yaml"), "lockfileVersion: '9.0'\n");
-await writeFile(path.join(prototypeRoot, "src/App.jsx"), [
-  'import { ConfigProvider, Button } from "antd";',
-  'import { yssTheme } from "./yss-theme.js";',
-  'export function App() { return <ConfigProvider theme={yssTheme}><Button type="primary">提交</Button></ConfigProvider>; }'
-].join("\n"));
-const after = await validatePrototypeProject({ root: prototypeRoot, targetAntdVersion: "6.6.2" });
-assert.deepEqual(after.errors, []);
-const wrongTarget = await validatePrototypeProject({ root: prototypeRoot, targetAntdVersion: "6.6.1" });
-assert(wrongTarget.errors.some((message) => message.includes("精确锁定 antd 6.6.1")), "target 与实际 antd 版本不一致必须失败");
-const npmPackage = structuredClone(pkg);
-npmPackage.packageManager = "npm@11.0.0";
-await writeFile(path.join(prototypeRoot, "package.json"), JSON.stringify(npmPackage, null, 2));
-const npmProject = await validatePrototypeProject({ root: prototypeRoot, targetAntdVersion: "6.6.2" });
-assert(npmProject.errors.some((message) => message.includes("packageManager")), "原型包管理器漂移到 npm 必须失败");
-await writeFile(path.join(prototypeRoot, "package.json"), JSON.stringify(pkg, null, 2));
-await assert.rejects(
-  preparePrototype({
-    projectRoot,
-    root: path.join(projectRoot, "prototypes", feature),
+function common(profile, kind, block) {
+  return {
+    schema_version: 3,
     feature,
-    targetAntdVersion: "6.6.2",
-    pnpmVersion: "10.15.0"
-  }),
-  /docs\/.scratch/,
-  "非标准原型目录必须被拒绝"
-);
-const validEvidence = {
-  schema_version: 2,
-  feature,
-  prototype_ref: `docs/.scratch/${feature}/design/prototypes/index.html`,
-  prototype_stack: {
-    framework: "react",
-    package_manager: "pnpm",
-    package_manifest_ref: `docs/.scratch/${feature}/design/prototypes/package.json`,
-    lockfile_ref: `docs/.scratch/${feature}/design/prototypes/pnpm-lock.yaml`,
-    source_entry_ref: `docs/.scratch/${feature}/design/prototypes/src/App.jsx`,
-    build_entry_ref: `docs/.scratch/${feature}/design/prototypes/dist/index.html`,
-    build_command: "pnpm build",
-    build_result: "passed",
-    actual_antd_version: "6.6.2"
-  },
-  design_baseline: {
-    design_standard: "ant-design-v6",
-    project_design_ref: "docs/design/design.md",
-    project_token_refs: ["docs/design/tokens/theme.json"],
-    theme_adapter_ref: `docs/.scratch/${feature}/design/prototypes/src/yss-theme.js`,
-    project_override_reviewed: true
-  },
-  visual_semantic_mapping: {
-    runtime_component_library: "ant-design-vue-4.x",
-    runtime_version_source: "implementation-lockfile",
-    components: [{
-      semantic_role: "primary-action",
-      antd_v6_component: "Button",
-      project_token_refs: ["colorPrimary"],
-      yss_or_antdv_target: "YButton",
-      state_mapping: ["default", "hover", "active", "disabled", "loading"],
-      react_only_api_not_copied: true,
-      verification_ref: "verification/button-states.png"
-    }]
-  },
-  antd: { target_antd_version: "6.6.2", queries: { design_md: "verification/antd-design.json", components: [] } },
-  browser_verification: { rendered_nonblank: true, viewports: [], main_flow_result: "passed", failure_permission_or_conflict_result: "passed", console_error_ref: "verification/console.txt" },
-  design_qa: { report_ref: `docs/.scratch/${feature}/verification/design-qa.md`, result: "passed" },
-  accessibility_verification: {
-    contrast_results_ref: "verification/contrast.json",
-    keyboard_navigation_result: "passed",
-    focus_visible_and_order_result: "passed",
-    semantic_label_dialog_result: "passed",
-    zoom_200_result: "passed",
-    reduced_motion_result: "passed",
-    target_size_result: "passed",
-    automated_scan: { tool: "axe", version: "4", result: "passed", ref: "verification/axe.json" }
-  },
-  review: { prototype_review_ref: "design/review.md", result: "approved" },
-  user_confirmation: { confirmation_ref: "design/confirmation.md", result: "approved" },
-  blockers: []
-};
-assert.deepEqual(validatePrototypeEvidence(validEvidence).errors, []);
-const missingMapping = structuredClone(validEvidence);
-delete missingMapping.visual_semantic_mapping;
-assert(validatePrototypeEvidence(missingMapping).errors.some((message) => message.includes("visual_semantic_mapping")));
+    prototype_ref: `docs/.scratch/${feature}/design/prototypes/index.html`,
+    prototype_profile: profile,
+    profile_kind: kind,
+    profile_decision: {
+      decision_to_inform: "确认审批交互与状态",
+      risk_assumptions: ["状态必须可理解"],
+      trigger_results: [{ trigger: "visual-only", matched: profile === "H1", evidence_ref: "design/review.md" }],
+      calculated_profile: profile,
+      override: { applied: false, direction: "none", reason: "not-applicable", evidence_ref: "not-applicable" }
+    },
+    upstream_refs: { spec_ref: "spec.md", interaction_spec_ref: "interaction.md", low_fidelity_ref: "low.md", state_matrix_ref: "states.md", prototype_review_ref: "review.md" },
+    source_visual: { ideation_status: "not-applicable", selected_ref: "approved-pattern.md", reuse_reason: "复用已批准模式" },
+    design_baseline: { project_design_ref: "docs/design/design.md", project_token_refs: ["docs/design/tokens/theme.json"], project_token_baseline_digest: "sha256:tokens", project_override_reviewed: true },
+    browser_delivery: {
+      delivery_kind: "static-directory", entry_ref: `docs/.scratch/${feature}/design/prototypes/index.html`, rendered_nonblank: true, prototype_digest: "sha256:prototype",
+      viewports: [
+        { name: "desktop", size: "1440x900", result: "passed", screenshot_ref: "desktop.png" },
+        { name: "narrow", size: "390x844", result: "passed", screenshot_ref: "narrow.png" }
+      ],
+      console_result: "passed", console_ref: "console.txt"
+    },
+    design_qa: { report_ref: `docs/.scratch/${feature}/verification/design-qa.md`, result: "passed", axes: { visual: "passed", layout: "passed", interaction: "passed", content: "passed", accessibility: "passed", cross_platform: "passed" } },
+    profile_evidence: block,
+    implementation_handoff: {
+      prototype_code_reusable: false,
+      production_component_assumptions: ["YSS 组件可以表达已确认的交互语义"],
+      verification_targets: [{ behavior: "核验目标组件的真实 props/slots/events 与状态", target_stage: "frontend-implementation-plan" }]
+    },
+    review: { result: "approved", review_ref: "review.md" },
+    user_confirmation: { result: "approved", confirmation_ref: "confirmation.md", confirmed_decision: "接受当前设计", operable_scope: ["主操作"], simulations_or_gaps: [] },
+    gaps: [], blockers: []
+  };
+}
-const copiedReactApi = structuredClone(validEvidence);
-copiedReactApi.visual_semantic_mapping.components[0].react_only_api_not_copied = false;
-assert(validatePrototypeEvidence(copiedReactApi).errors.some((message) => message.includes("React-only")));
+const h1Evidence = common("H1", "visual-review", { visual_review: {
+  runtime_build_required: false, key_interactions_result: "passed", keyboard_result: "passed", focus_result: "passed", contrast_result: "passed",
+  zoom_200: { applicable: false, result: "not-applicable", evidence_ref: "not-applicable" },
+  reduced_motion: { applicable: false, result: "not-applicable", evidence_ref: "not-applicable" }
+} });
+assert.deepEqual(validatePrototypeEvidence(h1Evidence).errors, []);
+const fakeH1 = structuredClone(h1Evidence);
+fakeH1.profile_evidence.visual_review.lockfile_ref = "pnpm-lock.yaml";
+assert(validatePrototypeEvidence(fakeH1).errors.some((message) => message.includes("H1 禁止字段")));
-const inaccessible = structuredClone(validEvidence);
-inaccessible.accessibility_verification.contrast_results_ref = "";
-assert(validatePrototypeEvidence(inaccessible).errors.some((message) => message.includes("contrast_results_ref")));
+const h2Evidence = common("H2", "flow-review", { flow_review: {
+  implementation: { framework: "react", runtime_build_required: true, package_manager: "pnpm", package_manifest_ref: "package.json", lockfile_ref: "pnpm-lock.yaml", build_command: "pnpm build", build_result: "passed" },
+  main_flow_result: "passed", exceptional_state_result: "passed", exceptional_state_ref: "conflict.png", keyboard_result: "passed", focus_result: "passed", contrast_result: "passed", zoom_200_result: "passed", reduced_motion_result: "passed",
+  visual_regression: { applicable: true, result: "passed", evidence_ref: "visual.json" },
+  prototype_library_facts: { applicable: true, component_basis: "react-antd-6", source: "fact-pack", actual_antd_version: "6.6.2", manifest_ref: "docs/design/facts/antd/6.6.2/manifest.json", manifest_digest: "sha256:facts", components_covered: ["Button"], project_token_baseline_digest: "sha256:tokens", new_api_uncertainty: false }
+} });
+assert.deepEqual(validatePrototypeEvidence(h2Evidence).errors, []);
+const staleFacts = structuredClone(h2Evidence);
+staleFacts.profile_evidence.flow_review.prototype_library_facts.project_token_baseline_digest = "sha256:old";
+assert(validatePrototypeEvidence(staleFacts).errors.some((message) => message.includes("Token digest")));
+const fakeH3Claim = structuredClone(h2Evidence);
+fakeH3Claim.profile_evidence.flow_review.real_component_verified = true;
+assert(validatePrototypeEvidence(fakeH3Claim).errors.some((message) => message.includes("禁止生产组件字段")));
-const wrongQaRoot = structuredClone(validEvidence);
-wrongQaRoot.design_qa.report_ref = "docs/design/design-qa.md";
-assert(validatePrototypeEvidence(wrongQaRoot).errors.some((message) => message.includes("design_qa.report_ref")));
+const h3Evidence = common("H3", "component-contract", { component_contract: {
+  implementation_repo_ref: "repo:frontend", lockfile_ref: "pnpm-lock.yaml", framework: "vue-3", component_library: "@yss-ui/components", component_library_version: "4.2.1", harness_ref: "storybook-static/index.html", story_refs: ["stories/approval.stories.ts"], real_component_verified: true,
+  main_flow_result: "passed", exceptional_state_result: "passed", keyboard_result: "passed", focus_result: "passed", contrast_result: "passed", zoom_200_result: "passed", reduced_motion_result: "passed", automated_visual_regression: { result: "passed", evidence_ref: "visual-regression.json" }
+} });
+assert(validatePrototypeEvidence(h3Evidence).errors.some((message) => message.includes("H1/H2")), "H3 必须被原型合同拒绝");
-const versionMismatch = structuredClone(validEvidence);
-versionMismatch.antd.target_antd_version = "6.6.1";
-assert(validatePrototypeEvidence(versionMismatch).errors.some((message) => message.includes("target_antd_version")));
+const invalidHandoff = structuredClone(h2Evidence);
+invalidHandoff.implementation_handoff.verification_targets[0].target_stage = "prototype";
+assert(validatePrototypeEvidence(invalidHandoff).errors.some((message) => message.includes("前端实现阶段")));
-const unresolvedBlocker = structuredClone(validEvidence);
-unresolvedBlocker.blockers = ["缺少权限失败态"];
-assert(validatePrototypeEvidence(unresolvedBlocker).errors.some((message) => message.includes("blockers")));
+assert(validatePrototypeEvidence({ schema_version: 2 }).errors.some((message) => message.includes("只读旧证据")));
+assert.deepEqual(validatePrototypeEvidence({ schema_version: 2 }, { allowLegacy: true }).errors, []);
-process.stdout.write("YSS prototype contract scenarios passed\n");
+process.stdout.write("YSS prototype profile contract scenarios passed\n");

package/template/.trae/skills/yss-repository/SKILL.md CHANGED Viewed

@@ -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`，由 实现合同编译器 回到 `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 当作已完成实现。
 ## 协同顺序
@@ -72,7 +74,7 @@ description: Use when generating or refactoring YSS persistence models, BaseRepo
 ## 阶段 7 合同
-- 前置条件：数据架构、领域元数据、实现仓库和批准后的 `Slice Implementation Contract` 均可用；否则不执行本 skill，由 Router 返回 `blocked`。
+- 前置条件：数据架构、领域元数据、实现仓库和批准后的 `Slice Implementation Contract` 均可用；否则不执行本 skill，由 实现合同编译器 返回 `blocked`。
 - PO/Repository/Convertor 骨架可使用 `controlled-generation`；复杂过滤、分页语义、并发、事务和迁移行为必须拆为 `behavior-tdd`。
 - 写入仅限合同 `allowed_write_paths`，证据必须包含实际 PO、Repository、Convertor、GatewayImpl、测试和 `./mvnw ...` 结果。
 - 按统一 `YSS Skill Execution Result` 返回 `seam_deferred/deviations/new_impacts`；发现数据模型、DDL、SQL、索引或 API schema 变化时暂停并重路由。

package/template/.trae/skills/yss-repository/agents/openai.yaml CHANGED Viewed

@@ -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/.trae/skills/yss-repository/references/infrastructure-layer-guide.md CHANGED Viewed

@@ -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/.trae/skills/yss-research/SKILL.md ADDED Viewed

@@ -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/.trae/skills/yss-research/agents/openai.yaml ADDED Viewed

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

package/template/.trae/skills/yss-research/assets/evidence-template.yaml ADDED Viewed

@@ -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/.trae/skills/yss-research/assets/research-brief-template.md ADDED Viewed

@@ -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/.trae/skills/yss-research/references/evidence-contract.md ADDED Viewed

@@ -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.