create-yss-spec 3.5.5 → 3.5.8

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

@@ -0,0 +1,270 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { competitiveVerificationFiles, validateCompetitiveAnalysis } from '../scripts/lib/competitive-analysis.mjs';
+
+const skillRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const validator = path.join(skillRoot, 'scripts/validate-research-package.mjs');
+const renderer = path.join(skillRoot, 'scripts/render-competitive-outputs.mjs');
+const repoRoot = path.resolve(skillRoot, '../../..');
+const headings = ['Research Scope', 'Executive Read', 'Findings', 'Counter-Signals', 'Source Map', 'Decision Handoff', 'Evidence Limitations'];
+
+test('竞品扩展的非法状态必须由完整 Schema 拒绝', () => {
+  const directory = mkdtempSync(path.join(tmpdir(), 'yss-competitive-'));
+  try {
+    const data = JSON.parse(readFileSync(path.join(skillRoot, 'assets/evidence-template.yaml'), 'utf8'));
+    data.competitive_analysis = { schema_version: 1, output_selection: 'matrix', as_of: '2026-10-02', comparison_scope: '固定产品资料', competitors: [{ id: 'alpha', name: 'Alpha', type: 'direct', product: 'Alpha', version: '1', edition: 'Pro', region: 'CN' }], capabilities: [{ id: 'export', module: '数据', name: '导出', definition: '用户导出 CSV', user_value: '复用数据' }], assessments: [{ competitor_id: 'alpha', capability_id: 'export', status: 'invented', claim_refs: ['claim-001'], limitations: [], gap: null }], artifacts: { matrix: 'sample-competitive-matrix.md' } };
+    const brief = path.join(directory, 'sample-research-brief.md');
+    const evidence = path.join(directory, 'sample-evidence.yaml');
+    writeFileSync(brief, `${headings.map(heading => `## ${heading}`).join('\n\n')}\nclaim-001\n`);
+    writeFileSync(evidence, JSON.stringify(data));
+    const result = spawnSync(process.execPath, [validator, brief, evidence], { encoding: 'utf8' });
+    assert.equal(result.status, 1, `非法竞品状态被接受：${result.stdout}${result.stderr}`);
+    assert.match(result.stderr, /competitive_analysis.*status|assessments.*status/s);
+  } finally {
+    rmSync(directory, { recursive: true, force: true });
+  }
+});
+
+function payload(selection = 'both') {
+  const data = JSON.parse(readFileSync(path.join(skillRoot, 'assets/evidence-template.yaml'), 'utf8'));
+  data.scope.topic = '固定资料 CSV 导出比较';
+  data.scope.audience = '产品规划负责人';
+  data.scope.time_horizon = '2026-10-02 截至资料';
+  data.scope.research_questions = ['哪些产品在本次版本、套餐与地区内支持 CSV 导出？'];
+  data.scope.inclusion_criteria = ['固定的一手产品说明'];
+  data.scope.exclusion_criteria = ['无日期的转载'];
+  data.ownership.downstream_owner = 'yss-stage-decision';
+  data.search_log[0] = { id: 'search-001', channel: 'fixture-docs', query_or_corpus: 'Alpha 产品说明', searched_at: '2026-10-02', result: 'results-found' };
+  data.search_log[1] = { id: 'search-002', channel: 'fixture-docs', query_or_corpus: 'Alpha 导出限制与 Beta 导出说明', searched_at: '2026-10-02', result: 'none-found' };
+  data.evidence_items[0] = { id: 'evidence-001', source_level: 'primary', visibility: 'internal', source_class: 'official-docs', source_ref: 'fixture://alpha/v1/pro/cn', locator: 'section CSV', stance: 'support', observed_at: '2026-10-02', evidence_date: '2026-10-01', observation: 'Alpha v1 Pro CN supports CSV export.', limitations: ['固定资料不代表其他版本、套餐或地区'] };
+  data.claims[0].claim_kind = 'business-constraint';
+  data.claims[0].statement = 'Alpha v1 Pro CN 支持 CSV 导出。';
+  data.competitive_analysis = {
+    schema_version: 1, output_selection: selection, as_of: '2026-10-02', comparison_scope: 'Alpha 与 Beta，v1 Pro CN，CSV 导出；仅固定资料',
+    competitors: [{ id: 'alpha', name: 'Alpha', type: 'direct', product: 'Alpha', version: '1', edition: 'Pro', region: 'CN' }, { id: 'beta', name: 'Beta', type: 'adjacent', product: 'Beta', version: '1', edition: 'Pro', region: 'CN' }],
+    capabilities: [{ id: 'csv-export', module: '数据', name: 'CSV 导出', definition: '用户将所选数据导出为 CSV 文件', user_value: '在下游工具中复用数据' }],
+    assessments: [{ competitor_id: 'alpha', capability_id: 'csv-export', status: 'supported', claim_refs: ['claim-001'], limitations: ['仅固定资料中的 v1 Pro CN'], gap: null }, { competitor_id: 'beta', capability_id: 'csv-export', status: 'unknown', claim_refs: [], limitations: [], gap: { reason: 'Beta 的导出说明不可获得', next_step: '获取 Beta v1 Pro CN 官方功能说明后重验' } }],
+    artifacts: { ...(selection !== 'report' ? { matrix: 'sample-competitive-matrix.md' } : {}), ...(selection !== 'matrix' ? { report: 'sample-competitive-analysis.md' } : {}) }
+  };
+  return data;
+}
+function fixture(t, data = payload()) {
+  const directory = mkdtempSync(path.join(tmpdir(), 'yss-competitive-'));
+  t.after(() => rmSync(directory, { recursive: true, force: true }));
+  const brief = path.join(directory, 'sample-research-brief.md');
+  const evidence = path.join(directory, 'sample-evidence.yaml');
+  writeFileSync(brief, `${headings.map(heading => `## ${heading}`).join('\n\n')}\n${data.claims.map(claim => claim.id).join(' ')}\n`);
+  writeFileSync(evidence, JSON.stringify(data, null, 2));
+  return { directory, brief, evidence, data };
+}
+function execute(file, args, status = 0, expected = '') {
+  const result = spawnSync(process.execPath, [file, ...args], { encoding: 'utf8' });
+  assert.equal(result.status, status, `${result.stdout}${result.stderr}`);
+  if (expected) assert.match(`${result.stdout}${result.stderr}`, expected);
+  return result;
+}
+function reject(data, evidence, expected) {
+  assert.throws(() => validateCompetitiveAnalysis(data, evidence, { checkArtifacts: false }), expected);
+}
+
+test('旧无扩展研究入口保留两参数，独立副本无需加载新库', t => {
+  const data = payload();
+  delete data.competitive_analysis;
+  const f = fixture(t, data);
+  const isolated = path.join(f.directory, 'validator.mjs');
+  copyFileSync(validator, isolated);
+  execute(isolated, [f.brief, f.evidence], 0, /research package valid/);
+  assert.deepEqual(competitiveVerificationFiles(f.evidence), []);
+  execute(path.join(skillRoot, 'tests/run-scenarios.mjs'), [], 0, /scenarios passed \(8\)/);
+});
+
+for (const selection of ['matrix', 'report', 'both']) test(`${selection} 输出生成后通过研究包校验`, t => {
+  const f = fixture(t, payload(selection));
+  execute(renderer, [f.evidence], 0, /outputs rendered/);
+  execute(validator, [f.brief, f.evidence], 0, /research package valid/);
+  const files = competitiveVerificationFiles(f.evidence);
+  assert.equal(files.length, (selection === 'both' ? 2 : 1) + 7);
+  assert.ok(files.every(path.isAbsolute));
+  if (selection !== 'matrix') {
+    const content = readFileSync(path.join(f.directory, 'sample-competitive-analysis.md'), 'utf8');
+    if (selection === 'both') assert.match(content, /完整功能矩阵：\[sample-competitive-matrix.md\]\(<sample-competitive-matrix.md>\)/);
+    else assert.match(content, /### 功能比较/);
+    assert.match(content, /❓ 未知/);
+    assert.match(content, /Alpha v1 Pro CN 支持 CSV 导出/);
+  }
+});
+
+test('扩展完整 Schema 执行嵌套必填、额外字段、日期格式和输出选择', t => {
+  const f = fixture(t);
+  const invalids = [
+    [data => delete data.competitive_analysis.capabilities[0].user_value, /Schema.*user_value/s],
+    [data => { data.competitive_analysis.competitors[0].unregistered = true; }, /Schema.*Additional properties/s],
+    [data => { data.competitive_analysis.as_of = '2026-02-30'; }, /Schema.*date/s],
+    [data => { data.competitive_analysis.output_selection = 'matrix'; }, /Schema.*False schema/s],
+    [data => { data.competitive_analysis.schema_version = 2; }, /Schema.*1 was expected/s]
+  ];
+  for (const [mutate, expected] of invalids) { const data = payload(); mutate(data); reject(data, f.evidence, expected); }
+});
+
+test('稳定 ID 和比较覆盖必须完整且唯一', t => {
+  const f = fixture(t);
+  const invalids = [
+    [data => data.competitive_analysis.competitors.push(structuredClone(data.competitive_analysis.competitors[0])), /duplicate id: alpha/],
+    [data => data.competitive_analysis.capabilities.push(structuredClone(data.competitive_analysis.capabilities[0])), /duplicate id: csv-export/],
+    [data => data.competitive_analysis.assessments.push(structuredClone(data.competitive_analysis.assessments[0])), /duplicate pair/],
+    [data => data.competitive_analysis.assessments.pop(), /missing assessment coverage: beta\/csv-export/],
+    [data => { data.competitive_analysis.assessments[0].competitor_id = 'missing'; }, /unknown competitor_id/],
+    [data => { data.competitive_analysis.assessments[0].capability_id = 'missing'; }, /unknown capability_id/]
+  ];
+  for (const [mutate, expected] of invalids) { const data = payload(); mutate(data); reject(data, f.evidence, expected); }
+});
+
+test('确定状态要求已审计且可解析的支持 Claim', t => {
+  const f = fixture(t);
+  const invalids = [
+    [data => { data.competitive_analysis.assessments[0].claim_refs = ['missing']; }, /unresolved claim ref/],
+    [data => { data.audit_summary.audited_claim_ids = []; }, /audited supported claim/],
+    [data => { data.audit_summary.status = 'incomplete'; }, /audited supported claim/],
+    [data => { data.claims[0].audit_status = 'not-audited'; }, /audited supported claim/],
+    [data => { data.claims[0].audit_status = 'partially-supported'; }, /must use qualify/],
+    [data => { data.evidence_items[0].source_level = 'lead-only'; }, /invalid supporting evidence/],
+    [data => { data.evidence_items[0].stance = 'counter'; }, /invalid supporting evidence/]
+  ];
+  for (const [mutate, expected] of invalids) { const data = payload(); mutate(data); reject(data, f.evidence, expected); }
+});
+
+test('策略包引用技术 Claim 的确定状态也要求一手支持，独立于 decision_bearing', t => {
+  const f = fixture(t);
+  for (const decisionBearing of [true, false]) {
+    const data = payload();
+    data.claims[0].claim_kind = 'technical-fact';
+    data.claims[0].decision_bearing = decisionBearing;
+    data.evidence_items[0].source_level = 'secondary';
+    reject(data, f.evidence, /technical-fact claim requires primary supporting evidence/);
+    data.evidence_items[0].source_level = 'primary';
+    assert.equal(validateCompetitiveAnalysis(data, f.evidence, { checkArtifacts: false }).enabled, true);
+  }
+  const unknown = payload();
+  unknown.claims[0].claim_kind = 'technical-fact';
+  unknown.evidence_items[0].source_level = 'secondary';
+  unknown.competitive_analysis.assessments[0].status = 'unknown';
+  unknown.competitive_analysis.assessments[0].gap = { reason: '技术 Claim 缺少一手材料', next_step: '获取相应官方说明后重新确认状态' };
+  assert.equal(validateCompetitiveAnalysis(unknown, f.evidence, { checkArtifacts: false }).enabled, true);
+});
+
+test('部分支持和未知适用范围保留限定条件', t => {
+  const f = fixture(t);
+  const partial = payload();
+  partial.competitive_analysis.assessments[0].status = 'partial';
+  partial.claims[0].audit_status = 'partially-supported';
+  partial.claims[0].disposition = 'qualify';
+  assert.equal(validateCompetitiveAnalysis(partial, f.evidence, { checkArtifacts: false }).enabled, true);
+  partial.competitive_analysis.assessments[0].limitations = [];
+  reject(partial, f.evidence, /Schema.*limitations/s);
+  const unknownScope = payload();
+  unknownScope.competitive_analysis.competitors[0].version = 'unknown';
+  unknownScope.competitive_analysis.assessments[0].limitations = [];
+  reject(unknownScope, f.evidence, /unknown version\/edition\/region requires limitations/);
+});
+
+test('未知允许空 Claim，但必须有来源缺口和补证计划', t => {
+  const f = fixture(t);
+  assert.equal(validateCompetitiveAnalysis(f.data, f.evidence, { checkArtifacts: false }).enabled, true);
+  for (const mutate of [data => { data.competitive_analysis.assessments[1].gap = null; }, data => { data.competitive_analysis.assessments[1].gap.next_step = ' '; }]) {
+    const data = payload(); mutate(data); reject(data, f.evidence, /Schema.*gap/s);
+  }
+});
+
+test('不支持要求明确证据，none-found 与搜索记录不能冒充', t => {
+  const f = fixture(t);
+  const absent = payload();
+  absent.competitive_analysis.assessments[0].status = 'absent';
+  absent.claims[0].statement = 'Alpha v1 Pro CN 明确不支持 CSV。';
+  absent.evidence_items[0].observation = 'Alpha v1 Pro CN: CSV is explicitly unavailable.';
+  assert.equal(validateCompetitiveAnalysis(absent, f.evidence, { checkArtifacts: false }).enabled, true);
+  absent.evidence_items[0].source_ref = 'search-002';
+  reject(absent, f.evidence, /absent cannot use none-found/);
+  absent.evidence_items[0].source_ref = 'fixture://search';
+  absent.evidence_items[0].source_class = 'search-log';
+  reject(absent, f.evidence, /absent cannot use none-found/);
+});
+
+test('缺失输出、表格漂移和证据摘要漂移均拒绝', t => {
+  const f = fixture(t);
+  assert.throws(() => validateCompetitiveAnalysis(f.data, f.evidence), /missing output artifact/);
+  execute(renderer, [f.evidence]);
+  const matrix = path.join(f.directory, 'sample-competitive-matrix.md');
+  writeFileSync(matrix, readFileSync(matrix, 'utf8').replace('✅ 明确支持；Claim:', '❌ 明确不支持；Claim:'));
+  assert.throws(() => validateCompetitiveAnalysis(f.data, f.evidence), /managed content drift/);
+  execute(renderer, [f.evidence]);
+  f.data.claims[0].statement = '修改后的 Claim 正文';
+  assert.throws(() => validateCompetitiveAnalysis(f.data, f.evidence), /managed content drift/);
+});
+
+test('渲染仅修改管理区并保留人工正文，第二份非法时不写第一份', t => {
+  const f = fixture(t);
+  const matrix = path.join(f.directory, 'sample-competitive-matrix.md');
+  const report = path.join(f.directory, 'sample-competitive-analysis.md');
+  const original = '人工前言\n<!-- YSS-COMPETITIVE:START -->\n旧受控内容\n<!-- YSS-COMPETITIVE:END -->\n人工结论\n';
+  writeFileSync(matrix, original);
+  writeFileSync(report, '没有标记的历史报告\n');
+  execute(renderer, [f.evidence], 1, /refusing to overwrite an unmarked legacy file/);
+  assert.equal(readFileSync(matrix, 'utf8'), original);
+  assert.equal(readFileSync(report, 'utf8'), '没有标记的历史报告\n');
+  rmSync(report);
+  execute(renderer, [f.evidence]);
+  const content = readFileSync(matrix, 'utf8');
+  assert.ok(content.startsWith('人工前言\n'));
+  assert.ok(content.endsWith('\n人工结论\n'));
+  validateCompetitiveAnalysis(f.data, f.evidence);
+  writeFileSync(report, readFileSync(report, 'utf8').replace('<!-- YSS-COMPETITIVE:END -->', '<!-- YSS-COMPETITIVE:END -->\n<!-- YSS-COMPETITIVE:END -->'));
+  execute(renderer, [f.evidence], 1, /exactly one complete managed region/);
+});
+
+test('路径越界、错误 slug 和符号链接输出直接拒绝', t => {
+  const f = fixture(t, payload('matrix'));
+  for (const filename of ['../sample-competitive-matrix.md', 'other-competitive-matrix.md', 'nested\\sample-competitive-matrix.md']) {
+    const data = payload('matrix'); data.competitive_analysis.artifacts.matrix = filename;
+    reject(data, f.evidence, /Schema|adjacent same-slug filename/);
+  }
+  const outside = path.join(f.directory, 'outside.md');
+  writeFileSync(outside, '外部文件');
+  symlinkSync(outside, path.join(f.directory, 'sample-competitive-matrix.md'));
+  execute(renderer, [f.evidence], 1, /symbolic link is not allowed/);
+  assert.equal(readFileSync(outside, 'utf8'), '外部文件');
+});
+
+test('输出文本转义不会注入管理标记或破坏 Markdown 表格', t => {
+  const data = payload('matrix');
+  data.competitive_analysis.competitors[0].name = 'Alpha | <tag>\n<!-- YSS-COMPETITIVE:START -->';
+  const f = fixture(t, data);
+  execute(renderer, [f.evidence]);
+  const content = readFileSync(path.join(f.directory, 'sample-competitive-matrix.md'), 'utf8');
+  assert.equal(content.split('<!-- YSS-COMPETITIVE:START -->').length, 2);
+  assert.match(content, /Alpha \\\| &lt;tag&gt;<br>/);
+  validateCompetitiveAnalysis(data, f.evidence);
+});
+
+test('验证依赖可绑定指定 repo 根，缺依赖不能跳过', t => {
+  const f = fixture(t, payload('matrix'));
+  execute(renderer, [f.evidence]);
+  const files = competitiveVerificationFiles(f.evidence);
+  const fixtureRoot = path.join(f.directory, 'root');
+  for (const dependency of files.slice(1)) {
+    const target = path.join(fixtureRoot, path.relative(repoRoot, dependency));
+    mkdirSync(path.dirname(target), { recursive: true });
+    copyFileSync(dependency, target);
+  }
+  const bound = competitiveVerificationFiles(f.evidence, { root: fixtureRoot });
+  assert.equal(bound[0], path.join(f.directory, 'sample-competitive-matrix.md'));
+  assert.ok(bound.slice(1).every(file => file.startsWith(`${fixtureRoot}${path.sep}`)));
+  const schema = path.join(fixtureRoot, '.agents/skills/yss-research/references/competitive-analysis.schema.json');
+  assert.ok(existsSync(schema));
+  rmSync(schema);
+  assert.throws(() => competitiveVerificationFiles(f.evidence, { root: fixtureRoot }), /ENOENT/);
+});

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

@@ -5,46 +5,40 @@ description: "接入或排查 YSS Resilience4j starter、网关熔断、限流
 
 # yss-resilience4j
 
-Use this skill for YSS Resilience4j 组件. Keep implementation grounded in the local project and resolvable YSS backend component source.
+处理 YSS 网关断路器、fallback 响应和韧性配置；阈值、状态与恢复行为按服务 SLO 和当前 API 契约核验。
 
-中文说明：本技能用于 YSS Resilience4j 组件。执行时优先读取源码索引，避免凭记忆猜类名、配置项或接入方式。
-
-## Source Index First
-
-- Backend source location is environment-specific; resolve it with `yss-skill-source-index-refresh/references/source-location.md`.
-- Generated index: `references/source-index.md`
-- Component path hints: `yss-microservice-components/yss-component-resilience4j-starter`
+## 平台与源码门禁
 
-Read `references/source-index.md` as a path-hint index whenever the task depends on exact modules, annotations, auto configuration, properties, controllers, clients, repositories, DTOs, handlers, or troubleshooting.
+接入、修改、代码生成或提供精确类名/配置前，必须读取并执行 [共享平台与源码门禁](../yss-skill-source-index-refresh/references/backend-component-platform-compatibility.md)，以 `--skill yss-resilience4j` 校验批准的平台线及匹配源码根。缺失、错配或漂移返回 `blocked`；不跨代回退，不在业务实现中升级、降级或替换组件。只读分诊可继续，但须标注未完成源码核验，不能据此宣称跨 Boot/JDK 兼容。
 
-## Workflow
+## 源码定位
 
-1. Read `references/source-index.md`, then read component `readme.md`.
-2. Identify whether the task is gateway circuit breaker configuration, fallback response, global circuit exception handling, or resilience troubleshooting.
-3. Inspect `GatewayConfiguration` for route/filter wiring and `GlobalCircuitExceptionAdvice` for exception response behavior.
-4. Tune thresholds/timeouts in configuration rather than hardcoding resilience behavior in business handlers.
-5. Keep fallback responses consistent with gateway/API response contracts.
+按 [源码定位策略](../yss-skill-source-index-refresh/references/source-location.md) 确认真实位置，再从 [平台索引](references/source-index.md) 定位当前任务需要的源码。`yss-microservice-components/yss-component-resilience4j-starter` 仅是模块路径提示。
 
-## Capability Split
+## 工作流
 
-- Gateway resilience wiring: `GatewayConfiguration`.
-- Circuit exception mapping: `GlobalCircuitExceptionAdvice`.
-- Operational guidance: README "轻量微服务断路器".
+1. 按平台索引定位当前组件源码与 `readme.md`。
+2. 区分网关断路器配置、fallback 响应、全局 circuit 异常映射与韧性排障。
+3. 装配问题核验 `GatewayConfiguration` 的 route/filter；异常响应核验 `GlobalCircuitExceptionAdvice`。
+4. 阈值和超时在配置中调整，不硬编码到业务 handler。
+5. fallback 状态和正文与网关/API 合同一致。
 
-## Checklist
+## 能力边界
 
-- Required dependency or starter module is present.
-- Circuit breaker names and route IDs match gateway configuration.
-- Fallback status/body are acceptable for frontend/API consumers.
-- Timeout, slow-call, and failure thresholds match service SLOs.
-- Logs/metrics make open/half-open/recovered states diagnosable.
+- 网关韧性装配：`GatewayConfiguration`。
+- Circuit 异常映射：`GlobalCircuitExceptionAdvice`。
+- 运行指引：README“轻量微服务断路器”。
 
-## Do Not
+## 验收
 
-- Do not invent class names or configuration keys without checking the source index.
-- Do not replace component extension points with business-local framework code.
-- Do not broaden the task into unrelated YSS components unless the user asks.
+- 核验所需依赖或 starter 已进入实际工程。
+- 断路器名称和 route ID 与网关配置一致。
+- fallback 状态/正文符合前端与 API 消费方契约。
+- 超时、慢调用与失败阈值符合服务 SLO。
+- 日志/指标可诊断 open、half-open 和 recovered 状态。
 
-## 平台与源码门禁
+## 修改边界
 
-接入、修改、代码生成或给出精确类名/配置前，读取 [后端组件平台与源码门禁](../yss-skill-source-index-refresh/references/backend-component-platform-compatibility.md)，从批准的 `platform_configuration.component_platform_line` 选择 `source-index.boot2-java8.md` 或 `source-index.boot3-java17.md`，并以 `--skill yss-resilience4j --platform-line <line> --source-root <matching-root>` 运行统一 freshness 校验。平台线与源码根不匹配、组件 tree 不一致、组件子树 dirty、索引缺少平台信号，或 Manifest / 组件 GAV 缺少 verified 兼容证据时返回 `blocked`；不得回退另一代索引，也不在业务实现中升级、降级或替换 YSS 组件。既有工程只读分诊可继续，但不得据此宣称跨 Boot/JDK 兼容。
+- 类名和配置 key 先核验当前索引与源码，不凭记忆补造。
+- 使用组件已有扩展 seam，不以业务本地框架代码替换。
+- 保持当前组件任务范围；扩展到其他组件须有用户要求或重新路由依据。

package/template/.agents/skills/yss-security-algorithm/SKILL.md

@@ -5,17 +5,7 @@ description: "审查、迁移或排查既有 YSS 加解密、JWT/JWK、密码编
 
 # yss-security-algorithm
 
-Use this skill as the governance, migration, and troubleshooting entry for the existing YSS 安全算法组件. Keep conclusions grounded in the local project, the approved platform catalog, and resolvable component source.
-
-中文说明：本技能用于 YSS 安全算法组件。执行时优先读取源码索引，避免凭记忆猜类名、配置项或接入方式。
-
-## Source Index First
-
-- Backend source location is environment-specific; resolve it with `yss-skill-source-index-refresh/references/source-location.md`.
-- Generated index: `references/source-index.md`
-- Component path hints: `yss-microservice-components/yss-component-security-algorithm`
-
-Read `references/source-index.md` as a path-hint index whenever the task depends on exact modules, annotations, auto configuration, properties, controllers, clients, repositories, DTOs, handlers, or troubleshooting.
+作为既有 YSS 安全算法组件的盘点、分诊、风险收敛和迁移入口。当前组件禁止新生产接入；准入结论不因源码可读或可编译而改变。
 
 ## 当前准入结论
 
@@ -25,7 +15,15 @@ Read `references/source-index.md` as a path-hint index whenever the task depends
 - 只有平台目录中的 `component.security-algorithm` 对目标架构为 `verified`，精确构件绑定仍有效，并且外部 KMS / Secret Manager、轮换撤销、兼容迁移、行为测试和安全责任人审查全部闭合后，才能通过独立决策重新开放新接入；本 Skill 不自行修改该状态。
 - 新接入请求返回 `component-new-adoption-forbidden` / `blocked-for-production`，并给出迁移或外部密钥服务方案；不得生成基于遗留工具类的生产代码。
 
-## Workflow
+## 平台与源码门禁
+
+接入、修改、代码生成或提供精确类名/配置前，必须读取并执行 [共享平台与源码门禁](../yss-skill-source-index-refresh/references/backend-component-platform-compatibility.md)，以 `--skill yss-security-algorithm` 校验批准的平台线及匹配源码根。缺失、错配或漂移返回 `blocked`；不跨代回退，不在业务实现中升级、降级或替换组件。只读分诊可继续，但须标注未完成源码核验，不能据此宣称跨 Boot/JDK 兼容。
+
+## 源码定位
+
+按 [源码定位策略](../yss-skill-source-index-refresh/references/source-location.md) 确认真实位置，再从 [平台索引](references/source-index.md) 定位当前任务需要的源码。`yss-microservice-components/yss-component-security-algorithm` 仅是模块路径提示。
+
+## 工作流
 
 1. 识别任务是新接入、既有故障、风险止血还是迁移；新接入直接按上述准入结论阻断。
 2. 读取 `references/source-index.md`，再按需检查 `CryptoType`、`SecurityCryptoUtil`、`KeyGeneratorUtils` 和 `DefaultJwtConfiguration`，记录实际算法、模式、编码、key id、密钥来源、调用方和持久化数据范围。
@@ -39,38 +37,34 @@ Read `references/source-index.md` as a path-hint index whenever the task depends
 10. JWT 必须验证 signature、issuer、audience、expiry 和允许算法，payload parsing 不能充当认证。
 11. 输出迁移清单、数据/调用方影响、回滚点、验证结果和安全审查引用；缺任一生产前提时保持 `blocked-for-production`。
 
-## Security Notes
+## 安全与兼容
 
 - Boot 2 历史实现中的硬编码 RSA 私钥、固定 key id、临时 JWK 与 noop 默认值必须视为已暴露风险并进入轮换/撤销盘点；不得把这些历史事实误写成 Boot 3 当前实现。
 - Boot 3 `Jwks` fail closed，`DefaultJwtConfiguration` 只提供 `PasswordEncoderFactories` 的 delegating encoder；JWT/JWK 必须由应用安全层或外部 KMS 提供。
 - 兼容适配器只保留公开类型和方法契约，不恢复旧密钥、旧密文解密或隐式 provider。存量兼容仍需代表性 ciphertext/JWT/password fixtures、回滚点和安全责任人审查。
-- Verify whether callers need encryption for storage, transport, signing, or compatibility; choose algorithm and key lifecycle accordingly.
-- Prefer environment/config/secret-manager backed keys for deployable code.
-- Keep plaintext, ciphertext, encoding format, and key type explicit in API contracts.
-
-## Checklist
-
-- Required dependency or starter module is present.
-- Algorithm choice is explicit and compatible with the caller.
-- Key source and rotation story are documented for production code.
-- JWT signatures are verified with issuer/audience/expiry policy; payload parsing alone is never authentication.
-- Encoding format is clear: Base64, hex, UTF-8 string, or raw bytes.
-- Decrypt path uses the matching algorithm/key type.
-- No passwords, private keys, or long-lived secrets are added to source files.
-- If external key storage, rotation/revocation, algorithm parameters, compatibility tests, or security-owner review is missing, return `blocked-for-production` instead of generating crypto code.
-- `Jwks` without a managed source and `SecurityCryptoUtil` without an approved `SecurityCryptoProvider` both fail closed.
-- Deprecated compatibility adapters delegate to the approved provider and preserve public signatures only; they do not make the component eligible for new adoption.
-- Existing ciphertext/JWT/password compatibility is demonstrated with representative fixtures before disabling an old key or encoder.
-- Logs and verification evidence contain only key references and redacted metadata, never plaintext, private keys, seeds, shared secrets, or complete tokens.
-
-## Do Not
-
-- Do not invent class names or configuration keys without checking the source index.
-- Do not replace component extension points with business-local framework code.
-- Do not broaden the task into unrelated YSS components unless the user asks.
-- Do not approve a new integration because the component compiles, a source index is fresh, or an existing project already depends on it.
-- Do not copy, print, rotate in place, or reissue any key material through Agent output.
-
-## 平台与源码门禁
-
-接入、修改、代码生成或给出精确类名/配置前，读取 [后端组件平台与源码门禁](../yss-skill-source-index-refresh/references/backend-component-platform-compatibility.md)，从批准的 `platform_configuration.component_platform_line` 选择 `source-index.boot2-java8.md` 或 `source-index.boot3-java17.md`，并以 `--skill yss-security-algorithm --platform-line <line> --source-root <matching-root>` 运行统一 freshness 校验。平台线与源码根不匹配、组件 tree 不一致、组件子树 dirty、索引缺少平台信号，或 Manifest / 组件 GAV 缺少 verified 兼容证据时返回 `blocked`；不得回退另一代索引，也不在业务实现中升级、降级或替换 YSS 组件。既有工程只读分诊可继续，但不得据此宣称跨 Boot/JDK 兼容。
+- 区分存储加密、传输、签名与兼容需要，再按批准合同选择算法和密钥生命周期。
+- 可部署实现消费批准的受控密钥服务和 key reference，不从示例推导密钥来源。
+- API 合同明确明文/密文、编码格式和密钥类型。
+
+## 验收
+
+- 核验所需依赖或 starter 已进入实际工程。
+- 算法选择明确并与调用方兼容。
+- 生产前提包含密钥来源与轮换方案。
+- JWT 验签覆盖 issuer/audience/expiry 策略，payload 解析不构成认证。
+- 编码格式明确区分 Base64、hex、UTF-8 string 和 raw bytes。
+- 解密使用匹配算法与密钥类型。
+- 源码不新增密码、私钥或长期 secret。
+- 外部密钥存储、轮换撤销、算法参数、兼容测试或安全责任人审查缺任一项时，返回 `blocked-for-production`，不生成生产加密代码。
+- `Jwks` 缺 managed source、`SecurityCryptoUtil` 缺批准的 `SecurityCryptoProvider` 时均 fail closed。
+- Deprecated 兼容适配器只保留公开签名并委派批准 provider，不恢复新接入资格。
+- 禁用旧 key 或 encoder 前，用代表性 fixture 证明存量 ciphertext/JWT/password 兼容。
+- 日志与证据只包含 key reference 和脱敏 metadata，不包含明文、私钥、seed、shared secret 或完整 token。
+
+## 修改边界
+
+- 类名和配置 key 先核验当前索引与源码，不凭记忆补造。
+- 使用组件已有扩展 seam，不以业务本地框架代码替换。
+- 保持当前组件任务范围；扩展到其他组件须有用户要求或重新路由依据。
+- 组件编译、索引 fresh 或既有工程依赖不解除新接入禁令。
+- Agent 输出不得复制、打印、就地轮换或重新签发密钥材料。

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

@@ -1,25 +1,23 @@
 ---
 name: yss-skill-source-index-refresh
-description: Use when YSS backend component source or frontend UI documentation changes and skill source indexes need refreshing.
+description: 后端组件源码或前端 YSS UI 文档变化后，刷新技能来源索引并核验平台线、组件摘要与引用。
 ---
 
-# YSS Skill Source Index Refresh
+# YSS 技能来源索引维护
 
-Use this maintenance skill to keep YSS skills grounded in current source and documentation.
+本 Skill 维护后端组件与前端文档的来源索引；索引用于定位和核验，不代替组件兼容认证。只读取或排障时使用现有索引及 freshness 门禁，不因每次调用自动刷新。
 
-中文说明：这个技能用于维护 YSS skills 的“源码索引”。后端组件库或前端文档入口变化后，运行脚本刷新引用文件。
+## 来源定位
 
-## Source Location Policy
+- 后端源码按平台线区分，信任生成路径前读取 [源码定位策略](references/source-location.md)。
+- 刷新时设置 `YSS_SOURCE_ROOT_BOOT2_JAVA8` 与 `YSS_SOURCE_ROOT_BOOT3_JAVA17`，分别指向匹配平台的干净源码树；不能使用同一 checkout 或从分支名推断平台线。
+- 前端 YSS UI 组件： `http://192.168.164.27:3200/components`
+- 前端 YSS UI hooks： `http://192.168.164.27:3200/hooks`
+- 前端 YSS UI 技能文档： `http://192.168.164.27:3200/skills`
 
-- Backend component source is generation-specific. Use `references/source-location.md` before trusting any generated path.
-- Set both `YSS_SOURCE_ROOT_BOOT2_JAVA8` and `YSS_SOURCE_ROOT_BOOT3_JAVA17` to clean source trees. Do not point both variables at the same checkout or infer a platform line from a branch name.
-- Frontend YSS UI components: `http://192.168.164.27:3200/components`
-- Frontend YSS UI hooks: `http://192.168.164.27:3200/hooks`
-- Frontend YSS UI skill docs: `http://192.168.164.27:3200/skills`
+## 刷新
 
-## Refresh Workflow
-
-Run:
+源码输入与刷新范围确定后运行：
 
 ```bash
 export YSS_SKILLS_ROOT="/path/to/.agents/skills"
@@ -28,42 +26,37 @@ export YSS_SOURCE_ROOT_BOOT3_JAVA17="/path/to/boot3-java17/yss-cloud-microservic
 node "$YSS_SKILLS_ROOT/yss-skill-source-index-refresh/scripts/refresh-yss-skill-index.mjs"
 ```
 
-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.
+仅后端刷新时设置 `YSS_REFRESH_FRONTEND=false`，避免无关前端时间戳变化；用 `YSS_REFRESH_BACKEND_SKILLS=yss-mybatis`（多个 ID 逗号分隔）限定组件范围。所选组件仍刷新两条平台线，因此两个源码根都必须齐备。
 
-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.
+后端输出稳定选择页 `references/source-index.md` 与两条平台生成索引；前端输出 `references/frontend-docs.md`。需要新增或调整技能到来源的映射时读取 [映射配置](references/source-map-config.md)。
 
 所有后端组件 Skill 共用 [平台与源码门禁](references/backend-component-platform-compatibility.md)。`references/source-index.md` 是稳定选择页；真实生成索引分别为 `source-index.boot2-java8.md` 与 `source-index.boot3-java17.md`。刷新后使用批准的 `platform_configuration.component_platform_line` 运行 `scripts/check-backend-skill-source-index.mjs --skill <skill-id> --platform-line <line> --source-root <matching-root>`，确认组件 tree、组件子树状态和 v2 平台信号与所选源码行一致。
 
-中文说明：脚本不会复制大段源码；通用组件生成可追踪的入口索引，持久化组件额外生成公开 API、配置开关和能力边界矩阵，方便 Agent 按需读取真实源码。
-
-The refresh command requires both generation-specific roots. A targeted refresh may still use `YSS_REFRESH_BACKEND_SKILLS`, but it updates both platform tracks for every selected Skill.
+脚本不复制大段源码；通用组件生成入口索引，持久化组件另生成公开 API、配置开关和能力边界矩阵，供按需定位真实源码。
 
-## Output Contract
+## 输出合同
 
-Generated source indexes should contain:
+生成索引保留以下来源与定位信息：
 
-- explicit platform line, generated timestamp and trace-only source Git commit
-- component-relative tree hashes and component-scoped worktree state
-- component directories and documentation files
-- Maven modules
-- 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
+- 明确的平台线、生成时间与仅作追踪的 source Git commit
+- 组件相对 tree hash 与组件子树工作区状态
+- 组件目录与文档文件
+- Maven 模块
+- 源文件 hash 与可重定位路径
+- 能力敏感组件的公开签名、配置 key/默认值、启用条件与能力边界，均从源码提取
+- 其他组件的关键 Java 入口，包括注解、自动配置、属性、切面、拦截器、handler、Repository、DTO 和结果类型
 - local Maven lineage、精确组件 GAV，以及继承的 Java/Spring Boot、`javax`/`jakarta` 和自动配置注册信号；这些是源码观察，不是兼容认证
-- 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
+`SKILL.md` 保留任务入口，不粘贴完整组件源码；专项任务按需读取生成索引或对应资产。
 
-Before exact class/config/security guidance, choose the index track from the approved platform configuration, compare each indexed `Component tree` with `git -C "$MATCHING_SOURCE_ROOT" rev-parse HEAD:<component-path>` and check `git status --porcelain -- <component-path>`. A missing platform line, wrong-generation root, tree mismatch or component-local dirty state means `stale`: refresh the matching track or return `blocked`; do not fall back to the other generation. 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.
+## Freshness 门禁
 
-中文说明：`SKILL.md` 保持短小，细节放到 `references/`，这是为了降低每次触发技能时的上下文成本。
+提供精确类名、配置或安全结论前，必须执行 [共享平台与源码门禁](references/backend-component-platform-compatibility.md)，按批准平台选择索引与干净源码根。平台缺失或错配、组件 tree 漂移、子树 dirty 返回 `stale` / `blocked`，不回退另一代；历史路径提示只能定位。仅仓库 commit 不同但组件 tree 未变，不使索引过期。
 
-## After Refresh
+## 刷新后验证
 
-Validate the migrated Node helper with:
+修改刷新器或完成索引刷新后，运行现有 Node 检查：
 
 ```bash
 node --test "$YSS_SKILLS_ROOT/yss-skill-source-index-refresh/scripts/refresh-yss-skill-index.test.mjs"

package/template/.agents/skills/yss-skill-source-index-refresh/references/backend-component-platform-compatibility.md

@@ -4,7 +4,7 @@
 
 ## 执行入口
 
-1. 接入、修改、代码生成或给出精确类名/配置前，从批准的 `platform_configuration.component_platform_line` 选择目标 Skill 的 `references/source-index.boot2-java8.md` 或 `references/source-index.boot3-java17.md`，并执行：
+1. 接入、修改、代码生成或给出精确类名/配置前，从批准的 `platform_configuration.component_platform_line` 选择目标 Skill 的 `references/source-index.boot2-java8.md` 或 `references/source-index.boot3-java17.md`。以下命令从目标组件 Skill 根目录执行：
 
    ```bash
      node ../yss-skill-source-index-refresh/scripts/check-backend-skill-source-index.mjs \

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

@@ -9,11 +9,9 @@ description: 编排 Plan 到 Spec 入口的方案决策与业务边界、协作
 
 `yss-stage-decision` 是由生命周期主控调度的上游决策技能，负责把需求、产品、商务输入和业务边界与规则设计结果整理成可审查、可版本化、可被下游消费的方案决策包。它不替代生命周期主控，也不生成产品代码、原型、OpenAPI 或垂直切片 Ticket。
 
-文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `.template-spec/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
-
 ## 文档写作
 
-撰写方案决策包和业务边界说明前，读取 `.template-spec/process/document-writing.md` 的共用写法及 Plan 指引；原业务规则、决定依据和未决项完整保留。
+撰写方案决策包和业务边界说明时，按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `.template-spec/process/document-writing.md` 的共用写法及 Plan 指引；原业务规则、决定依据和未决项完整保留。作用域仅限当前产物，派发时传递条件及引用。
 
 ## 适用边界
 
@@ -41,10 +39,9 @@ Plan 成功标准在既有 `success_criteria[].statement` 细化指标定义、
 - 新建领域战略、阶段决策包使用 JSON；存量 YAML 保持只读兼容，显式迁移见 `.template-spec/process/structured-assets.md`。使用 `scripts/contract plan-write/apply-write` 结构化落盘，不对合同作字符串拼接。校验器必须执行权威 Schema 后再检查跨文件语义。
 - 复用 Plan 原始决定编号，不自行重排；批准前用 `scripts/check-plan-stage-coverage` 生成绑定 Plan、决定记录和阶段包摘要的逐项对照证据，非目标使用显式映射。无法提取、缺项或映射歧义必须补齐；语义等价仍由独立评审确认，覆盖检查不构成批准。
 
-- 用户决定遵循 [用户决定协议](../yss-product-lifecycle/references/user-decisions.md)：决定必须绑定资产、版本、范围和证据；范围、风险、摘要或失效条件变化后重新确认。
+- 用户决定遵循 [用户决定协议](../yss-product-lifecycle/references/user-decisions.md)：决定绑定资产、版本、范围和证据。字节摘要变化先使旧验证过期，再核验差异；决定依据与授权范围未变时，按协议延续原回复并重新绑定当前审查和验证。实质范围、关键规则、风险接受或失效条件变化时，展示差异后取得新的真实回复。
 - checkpoint 是唯一机器状态源，业务 Ticket 只保存追踪引用，不复制阶段状态。
 - 每次批准、重发和消费者流转前执行 `context_reconciliation`，核验 `CONTEXT.md` 的全文与引用术语双摘要。
-- 技术事实与第三方行为走 `yss-research` 的 `technical-evidence`；产品策略依据走 `strategy-evidence`；市场与竞品判断走 `competitive-intelligence`。
 - 修改本 Skill 时只编辑 `.agents/skills` 权威副本，再由 `maintaining-skills` 生成投影和 `skills-lock.json`。
 - 本 Skill 只能标记影响、提出待解决问题和选择消费者能力；不得预选后端架构族，不得进入技术设计或实现流程，也不得授权实现。
 

package/template/.agents/skills/yss-tactical-design/SKILL.md

@@ -34,7 +34,7 @@ description: 在 YSS 技术分析阶段将批准的战略领域输入细化为
 
 批准且版本当前的战术设计合同由 `Slice Implementation Contract` 引用，再由 `yss-domain` 使用 `behavior-tdd` 实现。`yss-domain` 不得静默重新定义聚合或不变量；发现新的 API、状态、数据或架构影响时必须返回 `new_impacts` / `drift` 并重新路由。
 
-合同、Schema、校验规则和示例见 `references/`；使用 `scripts/validate-tactical-design.mjs` 做只读验证。该 skill 不生成 Java、Repository、Controller、DTO、OpenAPI Freeze、实现 Ticket 或生产代码。
+起草 DDD `design` 时读取 [战术合同](references/tactical-design-contract.md)，按 [验证规则](references/validation-rules.md) 执行 `scripts/validate-tactical-design.mjs` 的只读校验；需要正文结构时读取 [输出模板](references/output-template.md)，不批量加载整个 references 目录。该 Skill 不生成 Java、Repository、Controller、DTO、OpenAPI Freeze、实现 Ticket 或生产代码。
 
 ## 战略交接快照包
 

package/template/.agents/skills/yss-tactical-design/references/output-template.md

@@ -5,7 +5,7 @@ owner: ai
 
 # <功能名称> Tactical DDD Design
 
-仅用于已确认 domain-driven 分支的阅读视图；引用 Technical Design Contract v2 的 design，不复制共同输入与审批状态。MVC 使用 `yss-technical-design` 的 `layered-mvc` 分支。
+仅用于已确认 domain-driven 分支的阅读视图；引用 Technical Design Contract v2 的 design，不复制共同输入与审批状态。交接来源及可接受版本按 [输入合同](tactical-design-contract.md) 核对并绑定实际 ref/version/digest。MVC 使用 `yss-technical-design` 的 `layered-mvc` 分支。
 
 ## 上游引用
 
@@ -13,8 +13,8 @@ owner: ai
 |---|---|---|---|
 | Spec |  |  |  |
 | Strategic DDD |  |  |  |
-| Strategic Design Handoff v3 |  |  |  |
-| Visual Baseline Bundle v1 |  |  |  |
+| Strategic Design Handoff / 交付包（适用时） |  |  |  |
+| 原型或 existing UI baseline（按交接来源） |  |  |  |
 | Strategic Context Import / Context Reconciliation |  |  |  |
 | 状态矩阵 |  |  |  |
 | OpenAPI / 无 API 影响记录 |  |  |  |