create-yss-spec 3.1.3 → 3.2.0

package/template/.trae/skills/yss-technical-design/scripts/generate-schema.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+const load = ref => JSON.parse(readFileSync(new URL(ref, import.meta.url), 'utf8'));
+const schema = load('../references/technical-design-common.schema.json');
+const branches = [
+  ['domain-driven', '../../yss-tactical-design/references/tactical-design.schema.json'],
+  ['layered-mvc', '../../yss-mvc-design/references/mvc-design.schema.json']
+];
+schema.$comment = 'Generated by scripts/generate-schema.mjs from common and specialist schemas. Do not hand-edit.';
+schema.allOf = branches.map(([family, ref]) => {
+  const branch = load(ref); delete branch.$id; delete branch.$schema;
+  return { if: { properties: { architecture: { properties: { family: { const: family } } } } }, then: { properties: { design: branch } } };
+});
+const output = fileURLToPath(new URL('../references/technical-design.schema.json', import.meta.url));
+const bytes = `${JSON.stringify(schema, null, 2)}\n`;
+if (process.argv.includes('--check')) {
+  if (readFileSync(output, 'utf8') !== bytes) throw new Error('技术设计 Schema 投影漂移，请运行 generate-schema.mjs');
+} else writeFileSync(output, bytes);
+process.stdout.write('技术设计分支 Schema 已同步\n');

package/template/.trae/skills/yss-technical-design/scripts/validate-technical-design.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { parseArgs } from 'node:util';
+import { assertScaffoldUserDecision } from '../../../../scripts/lib/user-decision.mjs';
+import { validateJsonSchema } from '../../../../scripts/lib/json-schema.mjs';
+import { read, safe, hash, digest, ensure } from '../../../../scripts/lib/strategic-handoff-io.mjs';
+import { validate as validateDdd } from '../../yss-tactical-design/scripts/validate-tactical-design.mjs';
+import { designTargets } from '../../../../scripts/lib/strategic-handoff-design-targets.mjs';
+import { verifyConsumption } from '../../../../scripts/lib/strategic-handoff-consumption.mjs';
+
+const schema = fileURLToPath(new URL('../references/technical-design.schema.json', import.meta.url));
+const text = x => typeof x === 'string' && x.trim().length > 0;
+const nonempty = xs => Array.isArray(xs) && xs.length > 0 && xs.every(text);
+export const technicalDigest = data => digest(Object.fromEntries(Object.entries(data).filter(([key]) => key !== 'digest')));
+
+
+function validateMvc(design) {
+  const modules = new Map(design.module_catalog.map(item => [item.module_id, item]));
+  const cases = new Map(design.use_case_catalog.map(item => [item.use_case_id, item]));
+  const rules = new Set(design.rule_catalog.map(item => item.rule_id));
+  const permitted = {
+    server: ['service','core','client'], service: ['repository','adapter'], core: ['repository','adapter'],
+    repository: [], adapter: ['client','feign-client'], client: [], 'feign-client': ['client']
+  };
+  for (const module of modules.values()) for (const ref of module.depends_on) {
+    ensure(modules.has(ref) && permitted[module.layer].includes(modules.get(ref).layer), `模块依赖越界: ${module.module_id} -> ${ref}`);
+  }
+  for (const item of cases.values()) {
+    ensure(['service','core'].includes(modules.get(item.module_ref)?.layer), `用例必须属于 service/core: ${item.use_case_id}`);
+    ensure(item.rule_refs.every(ref => rules.has(ref)), `用例引用未声明规则: ${item.use_case_id}`);
+  }
+  for (const rule of design.rule_catalog) ensure(rule.use_case_refs.every(ref => cases.has(ref) && cases.get(ref).rule_refs.includes(rule.rule_id)), `规则与用例未双向关联: ${rule.rule_id}`);
+  for (const item of design.state_transition_catalog) ensure(cases.has(item.use_case_ref), '状态转换引用未声明用例');
+  if (!design.state_transition_catalog.length) ensure(text(design.state_not_applicable_reason), '无状态转换必须说明原因');
+  for (const item of design.persistence_mapping) ensure(cases.has(item.use_case_ref) && modules.get(item.repository_ref)?.layer === 'repository', '持久化映射的用例或 Repository 引用无效');
+  for (const item of design.integration_catalog) ensure(modules.get(item.adapter_ref)?.layer === 'adapter', '外部集成必须关联 Adapter');
+  if (!design.integration_catalog.length) ensure(text(design.integration_not_applicable_reason), '无外部集成必须说明原因');
+}
+
+export function verifyArchitecture(data, root) {
+  const binding = data.architecture;
+  const file = safe(root, binding.decision_ref);
+  ensure(hash(readFileSync(file)) === binding.decision_digest, '架构来源摘要漂移');
+  const record = read(file);
+  if (binding.source_kind === 'scaffold-decision') {
+    const decision = record.decisions?.find(item => item.project_id === binding.project_id);
+    ensure(record.status === 'current' && record.template === false, '架构选择记录必须为当前正式记录');
+    ensure(decision && ['user-confirmed','lifecycle-approved','consumed'].includes(decision.status), '分支设计前必须确认项目架构');
+    ensure(decision.confirmed_architecture === binding.family, '技术设计与确认架构不匹配');
+    ensure(text(decision.user_confirmation?.confirmation_ref) && text(decision.user_confirmation?.confirmed_by), '缺少真实架构确认引用');
+    assertScaffoldUserDecision(decision, { root });
+  } else {
+    // Registration formats differ by repository; bind the actual registered identity,
+    // never infer architecture from a directory or a design's self-declaration.
+    const entry = record.repositories?.find(item => item.project_id === binding.project_id) ?? record;
+    ensure(entry.project_id === binding.project_id && entry.architecture_identity?.architecture_family === binding.family, '技术设计与既有工程登记架构不匹配');
+    ensure(!['stale','blocked'].includes(record.status) && !['stale','blocked'].includes(entry.status), '工程登记已失效');
+  }
+}
+
+function validateLocalTraceability(data, root, sliceRef) {
+  const { ids, seams } = designTargets(data);
+  const sources = new Map(data.source_items.map(item => [item.source_id, item]));
+  ensure(sources.size === data.source_items.length, '源规则或场景 ID 重复');
+  const rows = new Map(data.traceability.map(item => [item.source_id, item]));
+  ensure(rows.size === data.traceability.length, '承接记录重复');
+  ensure(data.strategic_handoff || sources.size > 0, '无战略包时必须列出需求规则与场景');
+  for (const source of sources.values()) ensure(data.inputs.some(item => item.ref === source.source_ref), '源规则或场景未绑定当前输入');
+  for (const id of rows.keys()) ensure(sources.has(id), `未知承接来源: ${id}`);
+  for (const [id, source] of sources) {
+    const row = rows.get(id);
+    ensure(row, `缺少规则或场景承接: ${id}`);
+    if (row.disposition === 'implemented') {
+      ensure(nonempty(row.tactical_refs) && row.tactical_refs.every(ref => ids.has(ref)), `设计落点悬空: ${id}`);
+      ensure(nonempty(row.test_seam_refs) && row.test_seam_refs.every(ref => seams.has(ref) && row.tactical_refs.includes(seams.get(ref).subject_ref)), `测试 seam 未关联设计落点: ${id}`);
+      if (source.kind === 'scenario' && source.critical) ensure(['success','failure'].every(outcome => row.scenario_tests?.some(test => test.outcome === outcome && row.test_seam_refs.includes(test.seam_ref))), `关键场景缺少成功/失败测试: ${id}`);
+      ensure(nonempty(row.evidence_refs), `缺少承接证据: ${id}`);
+    } else if (row.disposition === 'not-applicable') {
+      ensure(text(row.reason) && nonempty(row.evidence_refs), `不适用缺少依据: ${id}`);
+    } else {
+      if (row.disposition === 'deferred') for (const key of ['reason','risk','owner','followup_ticket_ref','verification_plan','target_version']) ensure(text(row[key]), `延期缺少 ${key}: ${id}`);
+      ensure(sliceRef && row.dependency_status === 'known' && nonempty(row.dependent_slice_refs) && !row.dependent_slice_refs.includes(sliceRef), `未闭合承接阻断当前范围: ${id}`);
+    }
+    for (const ref of row.evidence_refs || []) safe(root, ref);
+  }
+}
+
+export async function validateTechnicalDesign(data, { root = process.cwd(), sliceRef, legacyDdd = false } = {}) {
+  if (data?.schema_version === 1) {
+    ensure(legacyDdd, '旧 v1 合同需要显式 --legacy-ddd，仅按 DDD 兼容读取');
+    const errors = validateDdd(data);
+    ensure(!errors.length, errors.join('; '));
+    if (sliceRef) ensure(data.status === 'approved', '切片只能消费 approved 设计');
+    if (data.strategic_handoff || data.strategic_context_import_ref || data.upstream_impact?.source_kind === 'strategic-handoff') {
+      const result = await verifyConsumption(data, { root, sliceRef });
+      ensure(result.result === 'verified', JSON.stringify(result));
+    }
+    return { result: 'legacy-ddd-read-only', architecture_family: 'domain-driven', status: data.status };
+  }
+  validateJsonSchema(data, schema, { label: '技术设计合同' });
+  ensure(data.digest === technicalDigest(data), '技术设计合同摘要不匹配');
+  ensure(!['stale','blocked','drift','new_impacts'].includes(data.status), '设计状态不可消费');
+  if (sliceRef) ensure(data.status === 'approved', '切片只能消费 approved 设计');
+  verifyArchitecture(data, root);
+  ensure(data.inputs.some(item => item.kind === 'context' && item.ref === 'CONTEXT.md') && data.inputs.some(item => item.kind === 'spec'), '共同输入缺少根 CONTEXT.md 或 Spec');
+  for (const input of data.inputs) ensure(hash(readFileSync(safe(root, input.ref))) === input.digest, `输入摘要漂移: ${input.ref}`);
+  for (const ref of data.evidence_refs) safe(root, ref);
+  if (data.status === 'approved') ensure(data.evidence_refs.length > 0, '已批准设计缺少评审证据');
+  if (data.architecture.family === 'domain-driven') {
+    const errors = validateDdd(data.design);
+    ensure(!errors.length, errors.join('; '));
+    ensure(data.design.status === data.status, 'DDD 分支状态与共同合同不一致');
+    ensure(data.inputs.some(item => item.kind === 'strategic'), 'DDD 分支缺少战略领域输入');
+    ensure(!data.design.strategic_handoff && !data.design.strategic_context_import_ref, '战略绑定只允许在共同合同中维护');
+  } else validateMvc(data.design);
+  const { ids, seams } = designTargets(data);
+  for (const seam of seams.values()) ensure(ids.has(seam.subject_ref), `测试 seam 设计对象悬空: ${seam.seam_id}`);
+  validateLocalTraceability(data, root, sliceRef);
+  if (data.strategic_handoff) {
+    const result = await verifyConsumption(data, { root, sliceRef });
+    ensure(result.result === 'verified', JSON.stringify(result));
+  }
+  return { result: 'ready-for-lifecycle-review', technical_design_id: data.technical_design_id, architecture_family: data.architecture.family, status: data.status, digest: data.digest };
+}
+
+async function main() {
+  const { values, positionals } = parseArgs({ allowPositionals: true, options: { root: { type: 'string', default: process.cwd() }, slice: { type: 'string' }, 'legacy-ddd': { type: 'boolean', default: false } } });
+  ensure(positionals.length === 1, '用法: validate-technical-design.mjs <合同> --root <项目根> [--slice <ID>] [--legacy-ddd]');
+  const result = await validateTechnicalDesign(read(path.resolve(positionals[0])), { root: values.root, sliceRef: values.slice, legacyDdd: values['legacy-ddd'] });
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main().catch(error => { process.stderr.write(`${JSON.stringify({ result: 'blocked', errors: [error.message] })}\n`); process.exitCode = 1; });

package/template/.trae/skills/yss-technical-design/tests/fixtures.mjs

@@ -0,0 +1,32 @@
+import { writeFileSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { hash } from '../../../../scripts/lib/strategic-handoff-io.mjs';
+import { technicalDigest } from '../scripts/validate-technical-design.mjs';
+export function mvcFixture(root) {
+  const files = {
+    'CONTEXT.md': '# 业务上下文\n',
+    'spec.md': '# 需求\nrule.valid: 必填材料完整。scenario.submit: 提交成功或校验失败。\n',
+    'registration.json': JSON.stringify({ project_id: 'example', status: 'current', architecture_identity: { architecture_family: 'layered-mvc' } }),
+    'review.md': '设计评审测试证据；不构成真实批准。\n'
+  };
+  for (const [ref, bytes] of Object.entries(files)) writeFileSync(path.join(root, ref), bytes);
+  const data = {
+    schema_version: 2, technical_design_id: 'technical-design.example', version: 'v1', status: 'ready-for-human', context_ref: 'CONTEXT.md',
+    architecture: { family: 'layered-mvc', project_id: 'example', source_kind: 'existing-registration', decision_ref: 'registration.json', decision_digest: hash(readFileSync(path.join(root, 'registration.json'))) },
+    inputs: ['CONTEXT.md','spec.md'].map((ref,index) => ({ kind: index ? 'spec' : 'context', ref, version: 'v1', digest: hash(readFileSync(path.join(root,ref))) })),
+    source_items: [{ source_id: 'rule.valid', kind: 'rule', critical: false, source_ref: 'spec.md' }, { source_id: 'scenario.submit', kind: 'scenario', critical: true, source_ref: 'spec.md' }],
+    traceability: ['rule.valid','scenario.submit'].map(source_id => ({ source_id, disposition: 'implemented', tactical_refs: ['use-case.submit'], test_seam_refs: ['test-seam.success','test-seam.failure'], evidence_refs: ['spec.md'], dependency_status: 'known', dependent_slice_refs: ['slice.submit'], scenario_tests: [{ outcome: 'success', seam_ref: 'test-seam.success' }, { outcome: 'failure', seam_ref: 'test-seam.failure' }] })),
+    design: {
+      module_catalog: [{ module_id: 'module.server', layer: 'server', responsibility: 'HTTP 适配', depends_on: ['module.service'] }, { module_id: 'module.service', layer: 'service', responsibility: '提交用例和事务', depends_on: ['module.repository'] }, { module_id: 'module.repository', layer: 'repository', responsibility: '数据持久化', depends_on: [] }],
+      use_case_catalog: [{ use_case_id: 'use-case.submit', module_ref: 'module.service', flow: ['校验材料','保存申请'], rule_refs: ['rule.valid'], failure_handling: '材料不完整拒绝提交，写入失败回滚' }],
+      rule_catalog: [{ rule_id: 'rule.valid', statement: '材料必须完整', use_case_refs: ['use-case.submit'] }],
+      state_transition_catalog: [], state_not_applicable_reason: '本范围只登记申请，无状态流转',
+      consistency_policy: { transaction_boundary: '一次提交同一事务', rollback: '写入失败整体回滚', concurrency: '唯一约束拒绝竞争提交', idempotency: '请求键唯一' },
+      persistence_mapping: [{ mapping_id: 'mapping.application', use_case_ref: 'use-case.submit', repository_ref: 'module.repository', storage_model: 'application', notes: '请求键唯一' }],
+      integration_catalog: [], integration_not_applicable_reason: '无外部集成',
+      test_seams: [{ seam_id: 'test-seam.success', kind: 'service', subject_ref: 'use-case.submit', assertion: '完整材料保存成功' }, { seam_id: 'test-seam.failure', kind: 'service', subject_ref: 'use-case.submit', assertion: '缺材料时不写入' }]
+    }, evidence_refs: ['review.md']
+  };
+  data.digest = technicalDigest(data);
+  return data;
+}

package/template/.trae/skills/yss-technical-design/tests/run-scenarios.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+import assert from 'node:assert/strict';
+import { mkdtempSync, readFileSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { attachScaffoldDecisionFixture } from '../../../../scripts/fixtures/user-decision/build-fixture.mjs';
+import { mvcFixture } from './fixtures.mjs';
+import { technicalDigest, validateTechnicalDesign } from '../scripts/validate-technical-design.mjs';
+import { hash, read } from '../../../../scripts/lib/strategic-handoff-io.mjs';
+import { enforceTechnicalDesign } from '../../../../scripts/lib/technical-design-boundary.mjs';
+import { compileDefaultImplementationContract, evaluateContractFreshness, loadCompilerContract } from '../../../../scripts/lib/implementation-contract-compiler.mjs';
+import { loadSkillRegistry } from '../../../../scripts/lib/skill-registry.mjs';
+const root = mkdtempSync(path.join(tmpdir(), 'yss-technical-design-'));
+let checks = 0;
+try {
+  const mvc = mvcFixture(root);
+  const validate = data => validateTechnicalDesign(data, { root });
+  assert.equal((await validate(mvc)).architecture_family, 'layered-mvc'); checks++;
+  async function rejected(change, pattern) {
+    const data = structuredClone(mvc); change(data); data.digest = technicalDigest(data);
+    await assert.rejects(() => validate(data), pattern); checks++;
+  }
+  await rejected(d => { d.architecture.family = 'mixed'; }, /not one of/);
+  await rejected(d => { d.architecture.project_id = 'wrong'; }, /登记架构不匹配/);
+  await rejected(d => { d.architecture.decision_digest = `sha256:${'0'.repeat(64)}`; }, /来源摘要漂移/);
+  await rejected(d => { d.traceability.pop(); }, /缺少规则或场景承接/);
+  await rejected(d => { d.traceability[1].scenario_tests.pop(); }, /成功\/失败测试/);
+  await rejected(d => { d.traceability[0].tactical_refs = ['aggregate.fake']; }, /设计落点悬空/);
+  await rejected(d => { d.design.module_catalog[0].depends_on = ['module.repository']; }, /模块依赖越界/);
+  await rejected(d => { d.design.consistency_policy.transaction_boundary = ''; }, /non-empty/);
+  await rejected(d => { d.design.aggregate_catalog = []; }, /Additional properties/);
+  await rejected(d => { d.design.test_seams[0].subject_ref = 'missing'; }, /设计对象悬空/);
+  await rejected(d => { d.status = 'stale'; }, /状态不可消费/);
+  await rejected(d => { d.traceability[0].disposition = 'conflict'; }, /未闭合承接/);
+  const deferred = structuredClone(mvc); deferred.status = 'approved';
+  Object.assign(deferred.traceability[0], { disposition: 'deferred', reason: '下一版', risk: '提交不可用', owner: '维护者', followup_ticket_ref: 'ticket.next', verification_plan: '回归提交', target_version: 'v2' });
+  deferred.digest = technicalDigest(deferred);
+  await assert.rejects(() => validateTechnicalDesign(deferred, { root, sliceRef: 'slice.submit' }), /未闭合承接/); checks++;
+  assert.equal((await validateTechnicalDesign(deferred, { root, sliceRef: 'slice.other' })).architecture_family, 'layered-mvc'); checks++;
+  deferred.traceability[0].dependency_status = 'unknown'; deferred.digest = technicalDigest(deferred);
+  await assert.rejects(() => validateTechnicalDesign(deferred, { root, sliceRef: 'slice.other' }), /未闭合承接/); checks++;
+  writeFileSync(path.join(root, 'spec.md'), 'changed');
+  await assert.rejects(() => validate(mvc), /输入摘要漂移/); checks++;
+  mvcFixture(root);
+  const old = read(fileURLToPath(new URL('../../yss-tactical-design/tests/fixtures/valid-tactical-design.yaml', import.meta.url)));
+  await assert.rejects(() => validate(old), /显式 --legacy-ddd/); checks++;
+  assert.equal((await validateTechnicalDesign(old, { root, legacyDdd: true })).result, 'legacy-ddd-read-only'); checks++;
+  const ddd = structuredClone(mvc); ddd.architecture.family = 'domain-driven';
+  writeFileSync(path.join(root, 'registration.json'), JSON.stringify({ project_id: 'example', status: 'current', architecture_identity: { architecture_family: 'domain-driven' } }));
+  ddd.architecture.decision_digest = hash(readFileSync(path.join(root, 'registration.json'))); ddd.design = old;
+  ddd.inputs.push({ kind: 'strategic', ref: 'spec.md', version: 'v1', digest: hash(readFileSync(path.join(root, 'spec.md'))) });
+  for (const row of ddd.traceability) Object.assign(row, { tactical_refs: [old.test_seams[0].subject_ref], test_seam_refs: [old.test_seams[0].seam_id], scenario_tests: ['success','failure'].map(outcome => ({ outcome, seam_ref: old.test_seams[0].seam_id })) });
+  ddd.digest = technicalDigest(ddd);
+  assert.equal((await validate(ddd)).architecture_family, 'domain-driven'); checks++;
+  ddd.design.aggregate_catalog[0].api_exposure = 'public'; ddd.digest = technicalDigest(ddd);
+  await assert.rejects(() => validate(ddd), /internal-only/); checks++;
+  const scaffold = mvcFixture(root);
+  const decision = attachScaffoldDecisionFixture(path.join(root, 'decision-evidence'), { project_id: 'example', status: 'user-confirmed', confirmed_architecture: 'layered-mvc', decision_inputs_digest: `sha256:${'1'.repeat(64)}`, user_confirmation: { confirmation_ref: 'user-message', confirmed_by: 'user' } });
+  const record = { status: 'current', template: false, decisions: [decision] };
+  const recordFile = path.join(root, 'decision.json');
+  writeFileSync(recordFile, JSON.stringify(record));
+  scaffold.architecture = { ...scaffold.architecture, source_kind: 'scaffold-decision', decision_ref: 'decision.json', decision_digest: hash(readFileSync(recordFile)) }; scaffold.digest = technicalDigest(scaffold);
+  assert.equal((await validate(scaffold)).architecture_family, 'layered-mvc'); checks++;
+  record.decisions[0].status = 'awaiting-user-decision'; writeFileSync(recordFile, JSON.stringify(record)); scaffold.architecture.decision_digest = hash(readFileSync(recordFile)); scaffold.digest = technicalDigest(scaffold);
+  await assert.rejects(() => validate(scaffold), /分支设计前必须确认/); checks++;
+  record.decisions[0].status = 'user-confirmed'; record.decisions[0].user_confirmation.user_decision_ref = 'missing-user-decision.json'; writeFileSync(recordFile, JSON.stringify(record)); scaffold.architecture.decision_digest = hash(readFileSync(recordFile)); scaffold.digest = technicalDigest(scaffold);
+  await assert.rejects(() => validate(scaffold), /user-decision/); checks++;
+  const current = mvcFixture(root); current.status = 'approved'; current.digest = technicalDigest(current);
+  const file = path.join(root, 'design.json'); writeFileSync(file, JSON.stringify(current));
+  const technical_design = { ref: 'design.json', version: 'v1', digest: hash(readFileSync(file)) };
+  const identity = { architecture_family: 'layered-mvc', architecture_profile: 'layered-mvc-service', generator_skill: 'yss-layered-mvc-scaffold-generator', requested_capabilities: [], resolved_modules: ['server','service','repository'], verification_database: 'h2', production_database: 'not-bound', contract_digest: 'a'.repeat(64) };
+  const state = { technical_design, slice_id: 'slice.submit', architecture_identity: identity, conditions: ['backend-technical-design-impact'] };
+  enforceTechnicalDesign(state, { root }); checks++;
+  assert.throws(() => enforceTechnicalDesign({ ...state, technical_design: undefined }, { root }), /缺少已批准技术设计/); checks++;
+  assert.throws(() => enforceTechnicalDesign({ ...state, architecture_identity: { architecture_family: 'domain-driven' } }, { root }), /架构不匹配/); checks++;
+  const resolution = compileDefaultImplementationContract({ ...state, root, requiredCapabilities: ['contract.request-validation'], architecture_evidence: { engineering_baseline: identity, repository_registration: identity, manifest: identity } });
+  assert.deepEqual(resolution.technical_design, technical_design); assert(!resolution.required_skills.includes('yss-domain')); checks++;
+  writeFileSync(path.join(root, 'spec.md'), 'changed again');
+  assert.equal(evaluateContractFreshness({ schema_version: 2, resolution }, { registry: loadSkillRegistry(), compilerContract: loadCompilerContract(), root }).freshness, 'stale'); checks++;
+} finally { rmSync(root, { recursive: true, force: true }); }
+process.stdout.write(`技术设计场景通过：${checks} 项（MVC、DDD、兼容、架构、承接、切片与漂移）\n`);

package/template/CONTEXT.md

@@ -72,7 +72,8 @@ context_schema_version: 1
 | 战略交接快照包 | 将批准的战略资产及证据冻结为可离线验证的完整目录或 ZIP，并提供规则和场景的派生索引。 | — | 源规则由战略方维护；包内快照与索引不成为目标仓词汇权威。 |
 | 后端交付包 | 将后端当前切片的战略基线、冻结接口、批准合同及构建、部署和验证证据绑定为可独立接收的交付快照。 | — | 验包通过不代表真实服务当前可用，也不代表前端已获准实现。 |
 | 前端联合接收 | 前端对战略交接快照与后端交付包进行版本、词汇、场景、接口和运行条件核验的过程。 | — | 输入就绪允许准备实现计划和合同；写代码仍需批准且当前的 Slice Implementation Contract。 |
-| 战术承接记录 | 将源规则和关键场景关联到战术落点、测试 seam、处置结论及依赖切片的结构化记录。 | — | 延期登记不等于依赖切片可实现；冲突回交战略方，未知依赖扩大阻断。 |
+| 技术设计合同 | 按已确认架构统一记录共同输入、规则与场景承接、对应设计及审查证据的合同。 | — | 技术设计由通用入口组织，领域建模与传统分层是可选分支，生命周期负责批准。 |
+| 战术承接记录 | 将源规则和关键场景关联到所选架构的设计落点、测试 seam、处置结论及依赖切片的结构化记录。 | — | 延期登记不等于依赖切片可实现；冲突回交战略方，未知依赖扩大阻断。 |
 | 流程模板资产 | 可被不同项目复用的文档模板、技能说明、校验脚本、流程规范和目录占位文件。 | — | 不包含某个具体产品的 Spec、设计、OpenAPI 或 Ticket。 |
 | 模板维护流程 | 用于评估影响、修改权威资产、同步投影、执行压力验证并审查模板演进的工作流。 | — | 面向模板源仓库，不默认生成具体产品的 Spec、原型、OpenAPI 或垂直切片 Ticket。 |
 | 模板发布门禁 | 模板源发布前必须通过的结构、技能同步、流程语义和压力场景验证集合。 | — | 不等同于只检查文件存在、Markdown 链接或 YAML 语法。 |

package/template/docs/agents/digital-human-roles.yaml

@@ -152,8 +152,8 @@ roles:
     contract_version: 1
     title: YSS 后端工程师
     stages: [stage.system-data-engineering, stage.ticket-formalization, stage.vertical-slice-implementation, stage.verification-release-retrospective]
-    draft_artifact_ids: [artifact.openapi-draft, artifact.data-architecture]
-    core_skills: [yss-implementation-contract-compiler, yss-tactical-design, yss-domain, yss-application, yss-repository, yss-mybatis, yss-web-controller, yss-dto, mapstruct, lombok, alibaba-java-code-style, yss-exception, yss-validation, tdd, yss-ddd-scaffold-generator, yss-layered-mvc-scaffold-generator]
+    draft_artifact_ids: [artifact.openapi-draft, artifact.data-architecture, artifact.technical-design]
+    core_skills: [yss-implementation-contract-compiler, yss-technical-design, yss-tactical-design, yss-mvc-design, yss-domain, yss-application, yss-repository, yss-mybatis, yss-web-controller, yss-dto, mapstruct, lombok, alibaba-java-code-style, yss-exception, yss-validation, tdd, yss-ddd-scaffold-generator, yss-layered-mvc-scaffold-generator]
     forbidden_skills: [yss-ui, yss-ui-business-page-generation, yss-formily, yss-frontend-scaffold-generator, yss-antd-design, yss-antdv-next-design, page-list-module, page-form-module]
     description: >-
       Own OpenAPI Draft, data-architecture contributions, and backend tests.

package/template/docs/agents/yss-skill-registry.yaml

@@ -57,12 +57,14 @@ capability_contract:
     preserve_all_reasons: true
   deterministic_order: [recipe-declaration, dependency-topology, skill-id]
 capabilities:
+  - { id: architecture.technical-design, primary_skill: yss-technical-design, task_modes: [guidance, integration, review-input] }
+  - { id: architecture.mvc-design, primary_skill: yss-mvc-design, architecture_family: layered-mvc, task_modes: [guidance, integration, review-input] }
   - { id: layer.mvc-service, primary_skill: yss-application, architecture_family: layered-mvc, task_modes: [guidance, integration, slice-implementation, troubleshooting, review-input] }
   - { id: layer.mvc-persistence, primary_skill: yss-repository, architecture_family: layered-mvc, task_modes: [guidance, integration, slice-implementation, troubleshooting, review-input] }
   - { id: layer.mvc-web, primary_skill: yss-web-controller, architecture_family: layered-mvc, task_modes: [guidance, integration, slice-implementation, troubleshooting, review-input] }
   - { id: governance.implementation-contract, primary_skill: yss-implementation-contract-compiler, task_modes: [contract-compilation, reroute, result-validation] }
   - { id: maintenance.skill-source-index, primary_skill: yss-skill-source-index-refresh, task_modes: [component-maintenance, source-index-refresh] }
-  - { id: architecture.tactical-domain, primary_skill: yss-tactical-design, task_modes: [guidance, integration, slice-implementation, review-input] }
+  - { id: architecture.tactical-domain, primary_skill: yss-tactical-design, architecture_family: domain-driven, task_modes: [guidance, integration, slice-implementation, review-input] }
   - { id: layer.domain, primary_skill: yss-domain, task_modes: [guidance, integration, slice-implementation, troubleshooting, review-input] }
   - { id: layer.application, primary_skill: yss-application, task_modes: [guidance, integration, slice-implementation, troubleshooting, review-input] }
   - { id: layer.persistence, primary_skill: yss-repository, task_modes: [guidance, integration, slice-implementation, troubleshooting, review-input] }
@@ -121,6 +123,11 @@ skill_dependencies:
     - { skill: domain-modeling, type: coordination-only }
     - { skill: yss-tactical-design, type: context-conditional, when: tactical-domain }
     - { skill: lombok, type: context-conditional, when: pojo }
+  yss-technical-design:
+    - { skill: yss-tactical-design, type: coordination-only, when: domain-driven }
+    - { skill: yss-mvc-design, type: coordination-only, when: layered-mvc }
+  yss-mvc-design:
+    - { skill: yss-openapi-draft-review, type: review-only, when: api-impact }
   yss-tactical-design:
     - { skill: domain-modeling, type: coordination-only }
     - { skill: yss-openapi-draft-review, type: review-only, when: api-impact }
@@ -479,6 +486,18 @@ skills:
     instance_default_discoverable: false
     aliases: []
     impacts: [backend]
+  - id: yss-technical-design
+    layer: core
+    maturity: draft
+    instance_default_discoverable: true
+    aliases: []
+    impacts: [backend, lifecycle]
+  - id: yss-mvc-design
+    layer: specialist
+    maturity: draft
+    instance_default_discoverable: false
+    aliases: []
+    impacts: [backend, lifecycle]
   - id: yss-tactical-design
     layer: specialist
     maturity: draft

package/template/docs/architecture/templates/architecture-review-checklist.md

@@ -19,7 +19,7 @@
 
 - [ ] 若为小改动，已完成 DDD impact check，并确认不影响统一语言、上下文边界、聚合、API、数据或风险 / 回滚约束。
 - [ ] Strategic DDD Check 已完成或明确不适用：统一语言、核心/支撑/通用子域、限界上下文、上下文映射和非目标范围清楚。
-- [ ] Tactical DDD Check 已完成或明确不适用：聚合根、Entity、Value Object、领域服务、不变量、一致性边界和 Repository / Gateway seam 清楚。
+- [ ] 技术设计使用已确认的 DDD / MVC 架构，规则与关键场景承接完整，合同及输入摘要当前。DDD 审查聚合、不变量、一致性和 Gateway；MVC 审查分层、用例、业务规则、事务和持久化映射。两者均需成功/失败测试 seam；无相关影响须明确理由。
 - [ ] OpenAPI 契约使用上下文的公开语言，不直接暴露内部聚合、Repository 或持久化表结构。
 - [ ] 领域行为测试、Application 用例测试、契约测试和必要 E2E 已与 DDD 边界对齐。
 

package/template/docs/architecture/templates/system-overview-design-template.md

@@ -64,10 +64,21 @@ owner: ai
 |----------|-------------|-------------|-------------|------------------|
 |  |  |  |  | 是 / 否 |
 
-## 8. Tactical DDD Check（轻量）
+## 8. 技术设计（按已确认架构）
 
-> 本节嵌入系统概要设计 / 数据架构，不新增独立阶段。只有当聚合边界、状态机、一致性或持久化映射复杂到无法在本节说明时，才升级为 `docs/.scratch/<feature>/architecture/<feature>-tactical-design.md`。
-> 战术设计优先引用结构化 `tactical-design` contract（含 `version`、`digest` 和 `evidence.tactical-design-review`）；独立文档只承载复杂场景的展开，不成为第二套事实源。
+引用 `artifact.technical-design` 的版本、digest 和 `evidence.technical-design-review`。`yss-technical-design` 先核对逐项目架构决定；新项目与脚手架共用确认来源，既有项目沿用登记。仅填写适用分支，未命中技术设计影响时记录原因。
+
+### 8.1 传统 MVC
+
+| 模块 / 层 | 用例与业务规则 | 状态转换 | 事务 / 并发 / 幂等 | 持久化 / 外部适配 | 测试 seam |
+|---|---|---|---|---|---|
+|  |  |  |  |  |  |
+
+检查规则和关键场景逐条承接、成功/失败测试、分层依赖及事务回滚。MVC 不填写聚合、值对象或 DDD Gateway；详细规则消费 `yss-mvc-design`。
+
+### 8.2 DDD Tactical Check
+
+以下仅用于 domain-driven，由 `yss-tactical-design` 细化。复杂场景可附独立说明，结构化技术设计合同仍是事实源；旧 `artifact.tactical-design` 只读兼容。
 
 | 限界上下文 | 聚合根 | 业务不变量 | Entity / Value Object | 一致性边界 | Gateway / Repository | 主要测试 seam |
 |------------|--------|------------|-----------------------|------------|----------------------|----------------|
@@ -121,7 +132,7 @@ owner: ai
 - [ ] API 影响记录 / 契约草案 / OpenAPI Draft 的路径、schema、错误结构、分页和契约测试已被架构反审，且可落地或已列出回改项。
 - [ ] 状态流、失败路径、幂等、并发和回滚策略清楚。
 - [ ] 数据架构需求已明确；涉及持久化、元模型、版本或血缘时已有数据架构。
-- [ ] Tactical DDD Check 已完成，或明确说明本次变更不影响领域模型 / 聚合 / 持久化边界。
+- [ ] 技术设计合同的适用 DDD / MVC 分支已完成、架构确认与承接证据当前；无相关影响有明确理由。
 - [ ] 已明确的认证、授权、租户隔离、敏感数据或合规行为已写入普通架构约束、契约与验证 seam；未触发时不额外登记。
 - [ ] 风险与人工审查点已标记。
 - [ ] 需要 ADR 的决策已列出。

package/template/docs/process/lifecycle-artifact-map.md

@@ -66,6 +66,7 @@
 | `artifact.data-architecture` | 数据架构 | `stage.system-data-engineering` | 数据模型、存储或一致性变化。 |
 | `artifact.engineering-baseline` | 工程基线记录 | `stage.system-data-engineering` | 后端、前端或高风险工程变化。 |
 | `artifact.architecture-review` | 架构审查记录 | `stage.system-data-engineering` | 高风险或跨边界变化。 |
+| `artifact.technical-design` | 技术设计合同 | `stage.system-data-engineering` | 后端技术设计需要按已确认 DDD 或 MVC 架构明确行为、分层、一致性或数据映射。 |
 | `artifact.tactical-design` | DDD 战术设计 | `stage.system-data-engineering` | 聚合边界、状态机、一致性或持久化映射复杂到无法在系统概要设计的 Tactical DDD Check 中清楚表达。 |
 | `artifact.spec-delta` | Spec Delta | `stage.spec-architecture` | 已有冻结 Spec 的高风险行为变化。 |
 | `artifact.parent-ticket` | 功能父 Ticket | `stage.ticket-formalization` | 每个进入追踪的功能。 |
@@ -82,6 +83,7 @@
 | `evidence.context-reconciliation` | Context Reconciliation 证据 | 工作单元在批准或流转前对根目录唯一 CONTEXT.md 的稳定术语回写、作用域解析和双摘要核对结果；不新增门禁。 |
 | `evidence.impact-assessment` | 影响面分析记录 | 受影响仓库、资产、风险与最近可信阶段。 |
 | `evidence.domain-strategy-review` | 业务边界与规则评审证据 | 业务板块、业务责任区、统一业务词汇、协作与交接关系、关键场景和不可违反规则的结构化评审结果。 |
+| `evidence.technical-design-review` | 技术设计评审证据 | 按已确认 DDD 或 MVC 架构审查规则与场景承接、分层、行为、一致性和测试边界。 |
 | `evidence.tactical-design-review` | DDD 战术设计评审证据 | 聚合、Entity、Value Object、不变量、状态机、一致性、Gateway 与 API 隔离的结构化评审结果。 |
 | `evidence.stage-decision-package` | 阶段决策包验证证据 | 阶段决策包的 Schema、引用、语义一致性、影响传播和下游消费验证结果。 |
 | `evidence.maintenance-intensity-checkpoint` | 模板维护强度 checkpoint | template-source 变更的 L1 / L2 / L3 分级、触发项、最低验证证据、review 模式和升级记录。 |

package/template/docs/process/lifecycle-registry-baseline.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "registry_id": "yss.lifecycle",
-  "semantic_sha256": "7757565261e3290046cd31d6b4287fc1e5ec8bdf7fae4735b0be8ac882e87b8d",
+  "semantic_sha256": "4eadc734957c5112dad60ec9fe4d844ac8790cbe798fbd8177ee60eae6dbe1fa",
   "published_ids": [
     "artifact.architecture-review",
     "artifact.data-architecture",
@@ -29,6 +29,7 @@
     "artifact.stage-decision-package",
     "artifact.state-matrix",
     "artifact.tactical-design",
+    "artifact.technical-design",
     "artifact.vertical-slice-ticket",
     "evidence.antd-cli-validation",
     "evidence.approval-record",
@@ -50,6 +51,7 @@
     "evidence.repository-identity-check",
     "evidence.stage-decision-package",
     "evidence.tactical-design-review",
+    "evidence.technical-design-review",
     "evidence.yss-skill-execution-result",
     "gate.architecture-reviewed",
     "gate.design-reviewed",

package/template/docs/process/lifecycle-registry.yaml

@@ -56,6 +56,9 @@ evidence:
     description: 子域、限界上下文、统一语言、Context Map、场景和不变量的结构化评审结果。
     public_name: 业务边界与规则评审证据
     public_description: 业务板块、业务责任区、统一业务词汇、协作与交接关系、关键场景和不可违反规则的结构化评审结果。
+  - id: evidence.technical-design-review
+    name: 技术设计评审证据
+    description: 按已确认 DDD 或 MVC 架构审查规则与场景承接、分层、行为、一致性和测试边界。
   - id: evidence.tactical-design-review
     name: DDD 战术设计评审证据
     description: 聚合、Entity、Value Object、不变量、状态机、一致性、Gateway 与 API 隔离的结构化评审结果。
@@ -278,6 +281,10 @@ artifacts:
     name: 架构审查记录
     stage: stage.system-data-engineering
     trigger: 高风险或跨边界变化。
+  - id: artifact.technical-design
+    name: 技术设计合同
+    stage: stage.system-data-engineering
+    trigger: 后端技术设计需要按已确认 DDD 或 MVC 架构明确行为、分层、一致性或数据映射。
   - id: artifact.tactical-design
     name: DDD 战术设计
     stage: stage.system-data-engineering
@@ -406,8 +413,8 @@ work_units:
     name: 技术分析与契约冻结
     scope: project-instance
     input: Spec、原型、API/数据/工程影响面。
-    output: OpenAPI、数据架构、Tactical DDD Check、工程基线、架构审查和 Slice 合同草案。
-    completion: 命中契约已冻结；无 API 影响有可读记录；命中领域影响时战术模型无未解释冲突；工程基线通过。
+    output: OpenAPI、数据架构、按确认架构形成的 DDD / MVC 技术设计合同、工程基线、架构审查和 Slice 合同草案。
+    completion: 命中契约已冻结；无 API 影响有可读记录；命中技术设计影响时架构已确认、规则与场景承接无未解释冲突；工程基线通过。
   - id: work-unit.service-project-initialization
     name: 独立服务项目初始化
     scope: project-instance

package/template/docs/process/schemas/strategic-design-handoff.schema.json

@@ -117,7 +117,10 @@
           "const": "docs/process/schemas/context-reconciliation.schema.json"
         },
         "required_before_skill": {
-          "const": "yss-tactical-design"
+          "enum": [
+            "yss-technical-design",
+            "yss-tactical-design"
+          ]
         },
         "status": {
           "const": "pending"
@@ -137,10 +140,16 @@
           "const": "downstream-rd-team"
         },
         "skill": {
-          "const": "yss-tactical-design"
+          "enum": [
+            "yss-technical-design",
+            "yss-tactical-design"
+          ]
         },
         "output": {
-          "const": "tactical-design-contract"
+          "enum": [
+            "technical-design-contract",
+            "tactical-design-contract"
+          ]
         }
       }
     },
@@ -666,5 +675,69 @@
         }
       }
     }
-  }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "target": {
+            "properties": {
+              "skill": {
+                "const": "yss-technical-design"
+              }
+            }
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "target": {
+            "properties": {
+              "output": {
+                "const": "technical-design-contract"
+              }
+            }
+          },
+          "target_context_reconciliation": {
+            "properties": {
+              "required_before_skill": {
+                "const": "yss-technical-design"
+              }
+            }
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "target": {
+            "properties": {
+              "skill": {
+                "const": "yss-tactical-design"
+              }
+            }
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "target": {
+            "properties": {
+              "output": {
+                "const": "tactical-design-contract"
+              }
+            }
+          },
+          "target_context_reconciliation": {
+            "properties": {
+              "required_before_skill": {
+                "const": "yss-tactical-design"
+              }
+            }
+          }
+        }
+      }
+    }
+  ]
 }

package/template/docs/process/strategic-handoff-package.md

@@ -31,7 +31,7 @@ scripts/strategic-handoff import --bundle <目录或ZIP> --target-root <研发
 
 导入落盘到 `docs/handoffs/<handoff-id>/<version>/`，包含不可变 `package/`、`import-receipt.json`、`context-reconciliation-draft.json`、`tactical-traceability-draft.json`、`upstream-change-impact.json`。仅写快照与草案，不自动更新根词汇表或批准状态。目标侧确认增量后更新唯一根 `CONTEXT.md`，生成既有 schema 的正式 reconciliation 并校验。
 
-战术合同的 `strategic_handoff` 绑定 `import_receipt_ref`、`bundle_digest`、`context_reconciliation_ref` 和 `rows`。逐条覆盖全部规则与 `critical: true` 的成功/失败场景；行字段如下：
+Technical Design Contract v2（DDD / MVC 共用）的 `strategic_handoff` 绑定 `import_receipt_ref`、`bundle_digest`、`context_reconciliation_ref` 和 `rows`。逐条覆盖全部规则与 `critical: true` 的成功/失败场景；行字段如下：
 
 - `source_id`、源对象 `source_digest`、`disposition`、`dependency_status: known | unknown`、`dependent_slice_refs`。
 - `implemented`：`tactical_refs`、`test_seam_refs`、`evidence_refs` 必须可解析；关键场景另用 `scenario_tests` 分别绑定 `outcome: success | failure` 与 `seam_ref`。
@@ -42,9 +42,11 @@ scripts/strategic-handoff import --bundle <目录或ZIP> --target-root <研发
 ```bash
 scripts/verify-strategic-handoff-consumption --root <研发项目根> <战术合同>
 scripts/verify-strategic-handoff-consumption --root <研发项目根> --slice <切片ID> <已批准战术合同>
-node .agents/skills/yss-tactical-design/scripts/validate-tactical-design.mjs <战术合同> --root <研发项目根>
+node .agents/skills/yss-technical-design/scripts/validate-technical-design.mjs <技术设计合同> --root <研发项目根>
 ```
 
+新交接的 target 使用 `yss-technical-design` / `technical-design-contract`，对账必须在通用入口前完成；旧 `yss-tactical-design` / `tactical-design-contract` 成对只读兼容，不修改已冻结包。`tactical_refs` 在 v2 可指向 `design` 中的 MVC 模块、用例、规则或 DDD 对象，测试 seam 同样在对应分支解析。无战略交接包的 MVC 项目直接消费批准需求，不要求补造战略 DDD。
+
 整体验证有未落实项时返回 blocked；按切片验证可放行有证据证明不依赖这些项的切片。输出 `block_all`、`blocked_slice_refs`、`issues`、实际消费包摘要与战术摘要。通过只证明结构化映射完整和引用可核验，业务语义仍需独立评审；不能代替 Slice Contract 批准。
 
 每版完整快照可独立消费，差异区分 added / updated / removed。更新须提升交接版本，内容变化的源资产也须提升其版本。接收新版本后，消费校验比较最新已导入源对象摘要；规则变化按行依赖阻断，未映射的新规则扩大阻断，战略责任边界、方案决策、Spec/视觉/原型源码等变化未重新绑定时整体阻断。`upstream-change-impact.json` 是生命周期处理 stale 的证据输入，不直接改 Tracker 或覆盖战术合同。