create-yss-spec 3.2.0 → 3.3.1

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

@@ -1,86 +1,44 @@
 ---
 name: yss-repository
-description: Use when generating or refactoring YSS Infrastructure persistence models, repositories, MapStruct convertors, Domain Gateway implementations, or metadata/DDL-backed queries.
+description: 用于按批准的 YSS 架构与持久化合同实现或重构 PO、Repository、Convertor、Domain Gateway/Query Adapter；负责结构路由、分层边界和验证，不内置可照抄的业务代码模板。
 ---
 
 # yss-repository
 
-## 架构分流（先执行）
+本 Skill 消费批准合同，将持久化责任落到选定架构 Profile。它不是完整脚手架，也不从 DDL、表名或示例反向创造领域/API 合同。
 
-读取当前合同的 architecture_identity 并与工程基线、仓库登记及 Manifest 核对；再且只读取 `references/profiles/<architecture_profile>.md`。支持的分支为 target-domain-model、layered-mvc-service、mvc-data-analysis-v1；成熟度以注册表为准，不能把 draft 称为受支持。MVC 不执行下文 DDD 专属规则，也不加载其旧分层 guide；组件、安全、批准合同、允许路径及执行证据规则仍共用。
+## 架构分流
 
-以下 Application / Domain Gateway / Infrastructure / Web module 叙述仅适用于 target-domain-model；MVC 的 service/core/repository/server/client 所有权由所选 Profile 引用定义。
+1. 读取当前 Slice Implementation Contract 的 `architecture_identity`、`persistence_profile`、实现仓登记、数据合同、`allowed_write_paths` 和预期证据。
+2. 将架构身份与工程基线、Manifest 和 `docs/agents/yss-skill-registry.yaml` 核对；成熟度以注册表为准，不能把 `draft` 称为已支持。
+3. 根据 `architecture_profile` **且只**加载一个文件：
+   - [target-domain-model](references/profiles/target-domain-model.md)
+   - [layered-mvc-service](references/profiles/layered-mvc-service.md)
+   - [mvc-data-analysis-v1](references/profiles/mvc-data-analysis-v1.md)
+4. Profile 缺失、身份冲突、Manifest 漂移或数据输入不完整时返回 `blocked` / `drift` / `new_impacts`，不得选择“最像”的分支继续。
 
-这是一个偏代码生成和结构补全的 skill，适合在已有工程里补 Repository 层，不适合替代完整脚手架。
+## 共用规则
 
-## 何时使用
+- 只实现批准合同已有的结构与 seam，不创建或改写 Domain Gateway、Application Query Port、service/core 接口或 Web/API DTO。
+- 持久化 Profile 命中 MyBatis 时加载 `yss-mybatis`，以当前组件能力索引核验基类、分页、批量、扫描、XML 和数据源行为；本 Skill 不复制这些规则。
+- POJO、转换和 Java 规范分别消费 Registry 编译出的 `lombok`、`mapstruct`、`alibaba-java-code-style`；不在此重复其注解和处理器规则。
+- 数据合同必须显式覆盖主键、逻辑删除、审计字段、空值、枚举/值对象映射和敏感字段；动态排序、分组与过滤必须使用批准白名单和参数绑定。
+- 事务归所选 Profile 的用例边界。Repository/Gateway Adapter 不临时新增业务事务，也不把数据库异常原文或凭据暴露给上层。
+- 基础机械结构只有在合同标记 `controlled-generation`、metadata 完整且目标文件不存在时才可受控生成；查询语义、分页、并发、事务和迁移行为使用 `behavior-tdd`。
+- 发现 SQL、DDL、索引、数据模型或 API schema 新影响时立即暂停并返回 `new_impacts`，不能以 TODO 代替合同重编译。
 
-- 用户要生成 `PO / Repository / Convertor / GatewayImpl`。
-- 用户已有 Domain 模型，缺基础设施持久层落地。
-- 用户要基于表结构、DDL、metadata 补齐持久层代码。
+## 产物与证据
 
-## 不适用
+实际产物由所选 Profile 和合同共同决定，不以固定示例类名或固定包路径推断。完成前至少证明：
 
-- 只做 Controller 时，优先 `yss-web-controller`。
-- 只做领域建模时，优先 `yss-domain`。
-- 从零建多模块工程时，优先 `yss-ddd-scaffold-generator`。
+- 每个实现类对应已批准的端口或用例调用方；
+- Mapper/Repository、XML、扫描和转换实现可编译且被运行时发现；
+- 保存/重载、查询、分页、空结果、排序白名单和回滚等命中行为有测试；
+- 所有写入位于 `allowed_write_paths`；
+- 使用各后端项目根的 `./mvnw ...` 记录实际命令、退出码和时间。
 
-## 工作方式
+按 [YSS Skill Execution Result v2](../yss-implementation-contract-compiler/references/yss-skill-execution-result.md) 返回实际文件、测试、约束结果、`seam_deferred`、`deviations`、`new_impacts`、`drift` 和 `violation`。
 
-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. 加载并遵守固定 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 骨架，把复杂查询留给手工实现。
+## Review 输入
 
-## 产物范围
-
-- `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 证据。
-- MapStruct 与 Lombok 同时使用时，必须确认注解处理器顺序和 `lombok-mapstruct-binding` 配置；构建命令使用项目根目录 `./mvnw ...`。
-- 逻辑删除、审计字段、主键策略要显式处理，不要隐式略过。
-- 事务放在批准的 Application 用例边界；检测到旧 GatewayImpl 事务布局时返回 `unsupported`，不在 scaffold 链路内迁移。
-
-## 质量门禁
-
-- 生成代码必须可编译。
-- 命名、包路径、注解要与工程现有规范一致。
-- Convertor 必须有 MapStruct 接口 / 抽象类、生成实现可编译，必要时补 mapper 单测或覆盖核心字段转换的行为测试。
-- POJO 使用 Lombok 时不得引入 `@Data` 造成实体 equals / toString 风险；有关系字段、敏感字段或懒加载字段时按 `lombok` skill 排除。
-- 遇到无法自动判断的字段、映射或查询规则时返回 `new_impacts` / `drift` 并暂停，不要把 TODO 当作已完成实现。
-
-## 协同顺序
-
-- metadata / DDL 输入准备：确认输入完整
-- 领域建模：`yss-domain`
-- 用例编排：`yss-application`
-- POJO 样板代码：`lombok`
-- 对象转换：`mapstruct`
-- Web 补齐：`yss-web-controller`
-
-## 分层开发规范
-
-实现 PO / Repository / GatewayImpl 前，必须加载 `references/infrastructure-layer-guide.md`：其中定义持久化对象、Repository、Convertor 与 Gateway 实现的结构与示例。
-
-## 阶段 7 合同
-
-- 前置条件：数据架构、领域元数据、实现仓库和批准后的 `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 变化时暂停并重路由。
+`code-review` 仅对本体项目及合同/实现仓登记的后端研发项目执行本 Skill。候选命中持久化结构或数据访问时，Standards 轴必须读取所选 Profile 并引用规则与代码证据；未命中时记录带原因的 `not-applicable`。Reviewer 只报告 finding，不写实现。

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

@@ -1,5 +1,5 @@
 version: 1
 interface:
   display_name: "YSS Repository"
-  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."
+  short_description: "按架构 Profile 实现并验证 YSS 持久层结构"
+  default_prompt: "Use $yss-repository to route and implement persistence structures from an approved architecture profile and contract without inventing domain, service, or API contracts."

package/template/.cursor/skills/yss-repository/references/profiles/layered-mvc-service.md

@@ -1,3 +1,21 @@
 # layered-mvc-service
 
-先读仓库 `docs/agents/backend-architecture-profiles.md`。依据批准的数据合同写入 repository 的 po/repository/convertor 及 Mapper XML；无需领域模型或 Gateway。使用 `yss-mybatis` 的 MyBatis-Plus 体系；保留 cause，避免向上暴露原始 SQL/凭据。事务由 service 用例拥有。测试覆盖查询、分页、回滚与字段转换；H2 不证明生产方言。生产驱动/数据源接入须另有批准的存储工作单元。
+仅适用于注册表中 `architecture_family=layered-mvc`、用例层为 `service` 的当前合同。先读仓库 `docs/agents/backend-architecture-profiles.md`；Profile 的成熟度沿用注册表。
+
+## 前置与所有权
+
+- 已有批准的 service 用例接口、数据合同和查询/写入语义；不得从表结构反推 service 或 HTTP API。
+- repository module 拥有 PO、Repository/Mapper、XML 和持久化 Convertor；不生成 DDD Domain Gateway、Application Query Port 或 Web DTO。
+- repository 不反向依赖 service、server、client；事务、业务规则和幂等归 service 用例。
+
+## 结构决策
+
+- 包、module、Mapper 扫描和 XML 路径来自 `architecture_identity`、当前工程基线及合同，不使用 DDD Infrastructure 固定布局。
+- MyBatis-Plus 基类、分页、批量和数据源能力由 `yss-mybatis` 当前能力矩阵决定。
+- repository 输出 service 已批准的内部模型或结果，不泄漏 PO、原始 SQL、数据库异常原文或凭据。
+
+## 必须验证
+
+- service 是唯一业务事务边界，Controller 不直连 Repository。
+- Repository/Mapper 覆盖查询、写入、分页、回滚、字段转换和批准数据库 fixture。
+- H2 仅作为验证数据库；生产驱动和数据源必须由单独批准的存储工作单元接入。

package/template/.cursor/skills/yss-repository/references/profiles/mvc-data-analysis-v1.md

@@ -1,3 +1,21 @@
 # mvc-data-analysis-v1
 
-遵守 `layered-mvc-service.md`，但事务所有者为 `core`。repository 不依赖 core/client/server，不生成 DDD Gateway。数据分析的动态排序、分组、过滤均须白名单及参数绑定；只消费批准的数据和查询合同。
+仅适用于注册表中的数据分析 MVC Profile。先读仓库 `docs/agents/backend-architecture-profiles.md`；Profile 的成熟度沿用注册表。
+
+## 前置与所有权
+
+- 已有批准的数据合同、查询语义和 core 用例接口；不得从 DDL 或报表字段反推对外 API。
+- repository module 拥有 PO、Repository/Mapper、XML 和持久化 Convertor；不生成 DDD Gateway，也不依赖 core、client、server。
+- 事务、业务规则和查询编排归 core；repository 只实现批准的数据访问 seam。
+
+## 数据分析约束
+
+- 动态排序、分组、过滤、聚合字段和表来源必须来自批准白名单并使用参数绑定；客户端输入不得直接拼接 SQL 标识符或表达式。
+- MyBatis-Plus 基类、分页、批量和数据源能力由 `yss-mybatis` 当前能力矩阵决定，不假设组件提供动态数据源路由。
+- repository 不返回 HTTP DTO，不暴露原始 SQL、数据库错误原文或连接凭据。
+
+## 必须验证
+
+- 查询覆盖白名单边界、空值、空结果、分页 total、稳定排序和大数据量限制。
+- 数据库 fixture 验证实际 Mapper/XML 与方言；H2 不能证明生产数据库的函数、排序或执行计划。
+- core 是唯一业务事务边界，server 不直连 Repository。

package/template/.cursor/skills/yss-repository/references/profiles/target-domain-model.md

@@ -1,3 +1,23 @@
 # target-domain-model
 
-完整执行规则见 `../infrastructure-layer-guide.md`。Domain Gateway 和 Application Query Port 必须已存在；本 Skill 只在 Infrastructure 实现，不反向创建领域端口。事务归 Application。
+仅适用于注册表中 `architecture_family=domain-driven` 的当前合同。Profile 的成熟度沿用注册表，不因加载本文件而升级。
+
+## 前置与所有权
+
+- 写模型必须已有批准的 Domain Gateway；读模型必须已有批准的 Application Query Port。缺失或需要改变签名时返回 `new_impacts`，由 `yss-domain` / `yss-application` 和实现合同编译器处理。
+- Infrastructure 实现既有端口，拥有 PO、Repository/Mapper、XML、持久化 Convertor、GatewayImpl 和 QueryAdapter；不拥有领域规则、HTTP DTO 或业务事务。
+- Domain Gateway 只交换 Aggregate、Domain Model、领域值和标识；分页、列表和读模型走 Application Query Port，`PageQuery` 不进入 Domain。
+
+## 结构决策
+
+- 包与 module 必须来自 `architecture_identity` 和现有工程基线；新脚手架的持久化责任位于 Infrastructure，既有工程不得因本 Skill 自动迁移目录。
+- 写模型转换覆盖 `PO <-> Domain Model`；读模型转换只到 Application Result。Infrastructure 不生成或返回 Web VO/CMD。
+- Repository 基类、Mapper/XML、分页与批量能力由 `yss-mybatis` 当前能力矩阵决定，不把组件版本方法名写成领域规则。
+- 事务归 Application 用例。GatewayImpl/QueryAdapter 只执行端口语义，不新增业务编排。
+
+## 必须验证
+
+- Domain 不反向依赖 Infrastructure、Mapper、PO 或组件类型。
+- 经 Domain Gateway 保存后可重新加载语义等价的 Aggregate。
+- Query Port 覆盖分页 total、空结果、排序/过滤白名单和字段转换。
+- Mapper/Repository 使用批准数据库 fixture；H2 不能证明生产方言。

package/template/.cursor/skills/yss-repository/tests/profile-routing.test.mjs

@@ -0,0 +1,59 @@
+import assert from "node:assert/strict";
+import { access, readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+const repositorySkillRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const skillsRoot = path.resolve(repositorySkillRoot, "..");
+const projectRoot = path.resolve(skillsRoot, "../..");
+
+async function text(target) {
+  return readFile(target, "utf8");
+}
+
+test("repository router exposes exactly the registered profile entry points", async () => {
+  const profilesRoot = path.join(repositorySkillRoot, "references/profiles");
+  const profiles = (await readdir(profilesRoot)).filter((name) => name.endsWith(".md")).sort();
+  assert.deepEqual(profiles, ["layered-mvc-service.md", "mvc-data-analysis-v1.md", "target-domain-model.md"]);
+
+  const skill = await text(path.join(repositorySkillRoot, "SKILL.md"));
+  for (const profile of profiles) assert.match(skill, new RegExp(`references/profiles/${profile.replace(".md", "")}`));
+  assert.match(skill, /且只.*加载一个文件/);
+  assert.doesNotMatch(skill, /infrastructure-layer-guide/);
+});
+
+test("normative persistence skills do not contain business-specific templates or production source mirrors", async () => {
+  const normativeFiles = [
+    path.join(repositorySkillRoot, "SKILL.md"),
+    ...["layered-mvc-service.md", "mvc-data-analysis-v1.md", "target-domain-model.md"]
+      .map((name) => path.join(repositorySkillRoot, "references/profiles", name)),
+  ];
+  for (const target of normativeFiles) {
+    const contents = await text(target);
+    assert.doesNotMatch(contents, /QualityTemplate|id\.value\(\)|insertOrUpdate\(/);
+  }
+
+  const mybatisAssets = path.join(skillsRoot, "yss-mybatis/assets");
+  try {
+    const javaMirrors = (await readdir(mybatisAssets)).filter((name) => name.endsWith(".java"));
+    assert.deepEqual(javaMirrors, []);
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+});
+
+test("code review wires Repository and MyBatis with registered backend scope", async () => {
+  const standards = await text(path.join(skillsRoot, "code-review/references/yss-review-standards.md"));
+  const report = await text(path.join(projectRoot, "docs/templates/review-report-template.md"));
+  const lifecycle = await text(path.join(skillsRoot, "yss-product-lifecycle/references/orchestration-contract.yaml"));
+
+  for (const source of [standards, report, lifecycle]) {
+    assert.match(source, /yss-repository/);
+    assert.match(source, /yss-mybatis/);
+  }
+  assert.match(standards, /本体项目和已登记后端研发项目/);
+  assert.match(report, /<review-root\.\.\.>/);
+  assert.match(lifecycle, /registered-backend-development-projects/);
+  await access(path.join(skillsRoot, "yss-mybatis/references/source-index.md"));
+});

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

@@ -1,6 +1,6 @@
 ---
 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.
+description: Research technical or product-strategy questions with traceable evidence before YSS Plan, 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

package/template/.cursor/skills/yss-skill-source-index-refresh/SKILL.md

@@ -28,10 +28,11 @@ node "$YSS_SKILLS_ROOT/yss-skill-source-index-refresh/scripts/refresh-yss-skill-
 ```
 
 Backend-only refreshes may set `YSS_REFRESH_FRONTEND=false` to avoid unrelated frontend timestamp churn.
+Use `YSS_REFRESH_BACKEND_SKILLS=yss-mybatis` (comma-separated) to refresh only selected backend indexes and avoid unrelated component churn.
 
 The script updates `references/source-index.md` for backend component skills and `references/frontend-docs.md` for frontend YSS UI skills. Read `references/source-map-config.md` for the full skill-to-source mapping.
 
-中文说明：脚本不会复制大段源码，只会生成可追踪的文档路径、模块路径和关键 Java 入口类，方便 Agent 后续精准读取。
+中文说明：脚本不会复制大段源码；通用组件生成可追踪的入口索引，持久化组件额外生成公开 API、配置开关和能力边界矩阵，方便 Agent 按需读取真实源码。
 
 If `YSS_SOURCE_ROOT` is omitted, the script tries to find a repository containing `yss-microservice-components` from the current workspace and common local project folders. If it cannot find one, set `YSS_SOURCE_ROOT` explicitly.
 
@@ -39,18 +40,20 @@ If `YSS_SOURCE_ROOT` is omitted, the script tries to find a repository containin
 
 Generated source indexes should contain:
 
-- source root and generated timestamp
-- exact source Git commit and worktree state
+- generated timestamp and trace-only source Git commit
+- component-relative tree hashes and component-scoped worktree state
 - component directories and documentation files
 - Maven modules
-- key Java classes matched by names such as annotations, auto configurations, properties, aspects, interceptors, handlers, repositories, DTOs, and result objects
+- source file hashes and relocatable paths
+- for capability-sensitive components, concise public signatures, configuration keys/defaults, conditional activation and capability boundaries extracted from source
+- for other components, key Java classes matched by names such as annotations, auto configurations, properties, aspects, interceptors, handlers, repositories, DTOs, and result objects
 - recommended next reads for Agent when performing implementation or troubleshooting
 
 Do not paste full component source into `SKILL.md`. Keep `SKILL.md` short and let specialists read generated indexes or targeted assets only when needed.
 
 ## Freshness Gate
 
-Before exact class/config/security guidance, compare the index `Source commit` with `git -C "$YSS_SOURCE_ROOT" rev-parse HEAD`. A mismatch or `dirty` indexed state means `stale`: refresh the index or return `blocked`; do not silently rely on the old snapshot. Historical path hints may still be used only to locate current source.
+Before exact class/config/security guidance, compare each indexed `Component tree` with `git -C "$YSS_SOURCE_ROOT" rev-parse HEAD:<component-path>` and check `git status --porcelain -- <component-path>`. A tree mismatch or component-local dirty state means `stale`: refresh the index or return `blocked`; do not silently rely on the old snapshot. A repository commit difference alone is trace metadata and does not make the index stale when the component tree is unchanged. Historical path hints may still be used only to locate current source.
 
 中文说明：`SKILL.md` 保持短小，细节放到 `references/`，这是为了降低每次触发技能时的上下文成本。
 

package/template/.cursor/skills/yss-skill-source-index-refresh/references/source-location.md

@@ -6,7 +6,7 @@ YSS skill references may mention paths such as `yss-microservice-components/yss-
 
 1. Check the current workspace first. If `.codegraph/` exists, use `codegraph explore "<class, module, or path hint>"` before text search.
 2. If the component source is outside the workspace, use `YSS_SOURCE_ROOT` when it is set. It should point to the repository root that contains `yss-microservice-components`.
-   Compare `git -C "$YSS_SOURCE_ROOT" rev-parse HEAD` with the selected index `Source commit`; mismatch is `stale` and blocks exact implementation guidance until refresh.
+   Compare every indexed `Component tree` with `git -C "$YSS_SOURCE_ROOT" rev-parse HEAD:<component-path>` and check `git status --porcelain -- <component-path>`. A tree mismatch or component-local dirty state is `stale` and blocks exact implementation guidance until refresh. `Source commit` is trace metadata only; unrelated monorepo changes do not stale an unchanged component tree.
 3. If `YSS_SOURCE_ROOT` is not set, search common local roots such as the current repository parents, `~/Projects`, `~/Documents`, and `~/Documents/yss-project`.
 4. If the source still cannot be found, use the generated `references/source-index.md` as a stale-but-useful map of module names, package names, class names, and Maven artifacts. Do not assume listed files exist locally.
 
@@ -15,4 +15,5 @@ YSS skill references may mention paths such as `yss-microservice-components/yss-
 - Say "source path hints" instead of "source root" unless you have verified the directory in the current environment.
 - Keep generated indexes useful for search, but do not require agents to open those exact paths.
 - Prefer symbols, package names, Maven artifact names, and annotations in instructions; they survive repository relocation better than absolute paths.
+- Keep full production source out of skill `assets/`; generate concise signatures, activation conditions and file hashes instead.
 - When refreshing indexes, export `YSS_SOURCE_ROOT=/absolute/path/to/yss-cloud-microservice` if auto-detection cannot find the component repository.