create-yss-spec 3.4.7 → 3.4.8

package/template/.cursor/skills/yss-ddd-scaffold-generator/scripts/first-slice-verification.test.mjs

@@ -126,19 +126,18 @@ const environment = { ...process.env, JAVA_HOME: "/fixture/java", YSS_MAVEN_REPO
 
 test("refuses first-slice promotion when a required persistence seam is absent", async () => {
   const data = await fixture({ omitGatewayImpl: true });
-  const report = await runFirstSliceVerification(data.project, data.evidence, data.contractPath, environment);
+  const report = await runFirstSliceVerification(data.project, data.evidence, data.contractPath, environment, { contractRoot: data.root });
   assert.equal(report.status, "failed");
-  assert.ok(report.missing_artifacts.includes("infrastructure-gateway-implementation"));
+  assert.ok(report.missing_artifacts.includes("backend.first_slice.artifacts-required"));
   const manifest = JSON.parse(await readFile(data.manifestPath, "utf8"));
   assert.equal(manifest.completion_level, "empty-scaffold-verified");
 });
 
-test("refuses first-slice promotion when downstream skill or contract digests are absent", async () => {
+test("missing generation provenance does not substitute for current approved contract", async () => {
   const data = await fixture({ omitReadiness: true });
-  const report = await runFirstSliceVerification(data.project, data.evidence, data.contractPath, environment);
+  const report = await runFirstSliceVerification(data.project, data.evidence, data.contractPath, environment, { contractRoot: data.root });
   assert.equal(report.status, "failed");
-  assert.ok(report.downstream_skill_drift.includes("yss-domain:digest-missing"));
-  assert.ok(report.downstream_skill_drift.includes("compiler_contract:digest-missing"));
+  assert.ok(report.contract_failures.includes("slice-execution-not-authorized"));
   const manifest = JSON.parse(await readFile(data.manifestPath, "utf8"));
   assert.equal(manifest.completion_level, "empty-scaffold-verified");
 });
@@ -148,20 +147,17 @@ test("refuses first-slice promotion when a work unit references a stale contract
   const contract = JSON.parse(await readFile(data.contractPath, "utf8"));
   contract.work_units[0].contract_version = 0;
   await writeFile(data.contractPath, JSON.stringify(contract));
-  const report = await runFirstSliceVerification(data.project, data.evidence, data.contractPath, environment);
+  const report = await runFirstSliceVerification(data.project, data.evidence, data.contractPath, environment, { contractRoot: data.root });
   assert.equal(report.status, "failed");
   assert.ok(report.contract_failures.includes("work-unit-contract-version-mismatch:slice-backend"));
 });
 
-test("promotes a complete approved slice only after all root wrapper commands pass", async () => {
+test("fake wrapper success and an approved status cannot promote an incomplete v2 contract", async () => {
   const data = await fixture();
-  const report = await runFirstSliceVerification(data.project, data.evidence, data.contractPath, environment);
-  assert.equal(report.status, "passed");
-  assert.equal(report.completion_level, "first-slice-verified");
-  assert.deepEqual(report.commands.map((item) => item.exit_code), [0, 0, 0]);
+  const report = await runFirstSliceVerification(data.project, data.evidence, data.contractPath, environment, { contractRoot: data.root });
+  assert.equal(report.status, "failed");
+  assert.ok(report.contract_failures.includes("slice-execution-not-authorized"));
+  assert.deepEqual(report.commands, []);
   const manifest = JSON.parse(await readFile(data.manifestPath, "utf8"));
-  assert.equal(manifest.completion_level, "first-slice-verified");
-  assert.equal(manifest.first_slice_contract.contract_id, "slice-1");
-  assert.equal(manifest.first_slice_contract.slice_id, "quality-rule-first-slice");
-  assert.equal(JSON.parse(await readFile(path.join(data.evidence, "first-slice-verification.json"), "utf8")).status, "passed");
+  assert.equal(manifest.completion_level, "empty-scaffold-verified");
 });

package/template/.cursor/skills/yss-ddd-scaffold-generator/scripts/run_first_slice_verification.mjs

@@ -8,33 +8,15 @@ import { fileURLToPath } from "node:url";
 
 import { run as runScaffoldVerification } from "./run_scaffold_verification.mjs";
 import { assertArchitectureAgreement } from "../../../../scripts/lib/backend-architecture.mjs";
-import { mvcFirstSliceProfile } from "../../../../scripts/lib/first-slice-architecture.mjs";
+import { inspectSliceContract } from "../../../../scripts/lib/slice-execution-preflight.mjs";
+import { selectSliceWorkUnit } from "../../../../scripts/lib/slice-contract.mjs";
+import { verifyFirstSliceTests } from "../../../../scripts/lib/first-slice-tests.mjs";
+import { inspectFirstSliceArtifacts } from "../../../../scripts/lib/first-slice-artifacts.mjs";
 
 const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
 const REPOSITORY_ROOT = path.resolve(SCRIPT_DIR, "../../../..");
 const REQUIRED_SKILLS = ["yss-domain", "yss-application", "yss-repository", "yss-mybatis", "yss-web-controller", "yss-dto", "yss-exception", "yss-validation", "mapstruct", "lombok", "alibaba-java-code-style"];
 const REQUIRED_LAYERS = ["domain", "application", "infrastructure", "web"];
-const ARTIFACT_CHECKS = [
-  ["domain-model", /-domain\/src\/main\/java\/.+\/domain\/.+\/model\/.+\.java$/],
-  ["domain-gateway", /-domain\/src\/main\/java\/.+\/domain\/.+\/gateway\/.+Gateway\.java$/],
-  ["domain-behavior-test", /-domain\/src\/test\/java\/.+(?:Test|Tests)\.java$/],
-  ["application-command-or-query", /-application\/src\/main\/java\/.+\/application\/(?:command|query)\/.+\.java$/],
-  ["application-result", /-application\/src\/main\/java\/.+\/application\/result\/.+Result\.java$/],
-  ["application-service", /-application\/src\/main\/java\/.+\/application\/service\/.+Service\.java$/],
-  ["application-service-implementation", /-application\/src\/main\/java\/.+\/application\/service\/impl\/.+ServiceImpl\.java$/],
-  ["application-behavior-test", /-application\/src\/test\/java\/.+(?:Test|Tests)\.java$/],
-  ["infrastructure-po", /-infrastructure\/src\/main\/java\/.+\/infrastructure\/persistence\/po\/.+PO\.java$/],
-  ["infrastructure-repository", /-infrastructure\/src\/main\/java\/.+\/infrastructure\/persistence\/repository\/.+Repository\.java$/],
-  ["infrastructure-convertor", /-infrastructure\/src\/main\/java\/.+\/infrastructure\/persistence\/convertor\/.+Convertor\.java$/],
-  ["infrastructure-gateway-implementation", /-infrastructure\/src\/main\/java\/.+\/infrastructure\/persistence\/gateway\/.+GatewayImpl\.java$/],
-  ["infrastructure-query-adapter", /-infrastructure\/src\/main\/java\/.+\/infrastructure\/query\/adapter\/.+QueryAdapter\.java$/],
-  ["infrastructure-integration-test", /-infrastructure\/src\/test\/java\/.+(?:Test|Tests)\.java$/],
-  ["web-controller", /-adapter\/.+-web\/src\/main\/java\/.+\/rest\/.+Controller\.java$/],
-  ["web-convertor", /-adapter\/.+-web\/src\/main\/java\/.+\/rest\/convertor\/.+WebConvertor\.java$/],
-  ["web-request", /-adapter\/.+-web\/src\/main\/java\/.+\/rest\/dto\/request\/.+Request\.java$/],
-  ["web-response", /-adapter\/.+-web\/src\/main\/java\/.+\/rest\/dto\/response\/.+Response\.java$/],
-  ["web-contract-test", /-adapter\/.+-web\/src\/test\/java\/.+(?:Test|Tests)\.java$/]
-];
 
 const isoNow = () => new Date().toISOString();
 const sha256 = (content) => createHash("sha256").update(content).digest("hex");
@@ -62,59 +44,7 @@ async function writeJsonAtomic(target, value) {
   await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, "utf8");
   await rename(temporary, target);
 }
-function invalidContractReasons(contract, requiredSkills = REQUIRED_SKILLS, requiredLayers = REQUIRED_LAYERS) {
-  const reasons = [];
-  if (contract.schema_version !== 2) reasons.push("slice-contract-schema");
-  if (contract.status !== "approved") reasons.push("slice-contract-not-approved");
-  for (const field of ["contract_id", "contract_version", "slice_id"]) if (contract[field] === undefined || contract[field] === null || contract[field] === "") reasons.push(`slice-contract-${field}-missing`);
-  if (contract.readiness?.blockers?.length) reasons.push("slice-contract-has-blockers");
-  if (contract.readiness?.stale_inputs?.length) reasons.push("slice-contract-has-stale-inputs");
-  const actualSkills = new Set([...(contract.common?.required_skills ?? []), ...(contract.backend?.required_skills ?? [])]);
-  for (const skill of requiredSkills) if (!actualSkills.has(skill)) reasons.push(`required-skill-missing:${skill}`);
-  const actualLayers = new Set(contract.backend?.affected_layers ?? []);
-  for (const layer of requiredLayers) if (!actualLayers.has(layer)) reasons.push(`required-layer-missing:${layer}`);
-  if (!Array.isArray(contract.work_units) || !contract.work_units.length) reasons.push("slice-contract-work-units-missing");
-  else for (const [index, unit] of contract.work_units.entries()) {
-    const id = unit.id || `index-${index}`;
-    if (unit.contract_id !== contract.contract_id) reasons.push(`work-unit-contract-id-mismatch:${id}`);
-    if (unit.contract_version !== contract.contract_version) reasons.push(`work-unit-contract-version-mismatch:${id}`);
-    if (!unit.work_unit?.primary_skill) reasons.push(`work-unit-primary-skill-missing:${id}`);
-  }
-  return reasons;
-}
-async function downstreamDrift(manifest, requiredSkills = REQUIRED_SKILLS) {
-  const drift = [];
-  const recordedSkills = manifest.readiness?.downstream_skills ?? {};
-  for (const skill of requiredSkills) {
-    const expected = recordedSkills[skill];
-    if (typeof expected !== "string" || !/^[a-f0-9]{64}$/.test(expected)) {
-      drift.push(`${skill}:digest-missing`);
-      continue;
-    }
-    const root = path.join(REPOSITORY_ROOT, ".agents", "skills", skill);
-    if (!await isFile(path.join(root, "SKILL.md"))) drift.push(`${skill}:unavailable`);
-    else if (await treeDigest(root) !== expected) drift.push(`${skill}:digest-mismatch`);
-  }
-  const contracts = manifest.readiness?.contracts ?? {};
-  const contractFiles = {
-    compiler_contract: path.join(REPOSITORY_ROOT, ".agents", "skills", "yss-implementation-contract-compiler", "references", "compiler-contract.yaml")
-  };
-  if (manifest.architecture_family === "layered-mvc") {
-    contractFiles.architecture_profiles = path.join(REPOSITORY_ROOT, "docs/agents/backend-architecture-profiles.md");
-  } else contractFiles.engineering_baseline = path.join(REPOSITORY_ROOT, ".agents", "skills", "yss-ddd-scaffold-generator", "references", "engineering-baseline.md");
-  for (const [name, target] of Object.entries(contractFiles)) {
-    const expected = contracts[name];
-    if (typeof expected !== "string" || !/^[a-f0-9]{64}$/.test(expected)) {
-      drift.push(`${name}:digest-missing`);
-      continue;
-    }
-    if (!await isFile(target)) drift.push(`${name}:unavailable`);
-    else if (sha256(await readFile(target)) !== expected) drift.push(`${name}:digest-mismatch`);
-  }
-  return drift;
-}
-
-export async function runFirstSliceVerification(projectRoot, evidenceDir, sliceContractFile, environment = process.env) {
+export async function runFirstSliceVerification(projectRoot, evidenceDir, sliceContractFile, environment = process.env, options = {}) {
   projectRoot = path.resolve(projectRoot);
   evidenceDir = path.resolve(evidenceDir);
   sliceContractFile = path.resolve(sliceContractFile);
@@ -123,20 +53,33 @@ export async function runFirstSliceVerification(projectRoot, evidenceDir, sliceC
   if (!await isFile(manifestPath)) throw new Error(`missing scaffold manifest: ${manifestPath}`);
   if (!await isFile(sliceContractFile)) throw new Error(`missing Slice Implementation Contract: ${sliceContractFile}`);
   const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
-  const contract = JSON.parse(await readFile(sliceContractFile, "utf8"));
+  const contractRoot = path.resolve(options.contractRoot || projectRoot);
+  let contract, preflight;
+  try {
+    const loaded = inspectSliceContract(path.relative(contractRoot, sliceContractFile), {
+      root: contractRoot, approval_ref: options.approvalRef, work_unit_id: options.workUnit
+    });
+    preflight = loaded.report;
+    contract = selectSliceWorkUnit(loaded.contract, options.workUnit);
+  } catch (error) {
+    preflight = { execution_allowed: false, blockers: [error.message] };
+    contract = {};
+  }
   if (manifest.platform_verification === "candidate") throw new Error("backend-platform: candidate scaffold cannot become first-slice-verified");
-  const adapter = manifest.architecture_family === "layered-mvc" ? mvcFirstSliceProfile(manifest.architecture_identity ?? {}) : { skills: REQUIRED_SKILLS, layers: REQUIRED_LAYERS, artifacts: ARTIFACT_CHECKS };
-  const contractFailures = invalidContractReasons(contract, adapter.skills, adapter.layers);
+  const contractFailures = [...preflight.blockers];
+  if (!preflight.execution_allowed) contractFailures.push("slice-execution-not-authorized");
+  if (!(contract.common?.project_roots || []).some(ref => path.resolve(contractRoot, ref) === projectRoot)) contractFailures.push("slice-project-root-mismatch");
   try {
     const identity = contract.architecture_identity ?? contract.resolution?.architecture_identity;
-    assertArchitectureAgreement(identity, { manifest });
+    if (identity?.source_kind !== "existing-registration") assertArchitectureAgreement(identity, { manifest });
     for (const unit of contract.work_units ?? []) assertArchitectureAgreement(identity, { work_unit: unit.architecture_identity });
   } catch (error) { contractFailures.push(`architecture-identity:${error.message}`); }
   if (![2, 3, 4].includes(manifest.schema_version) || manifest.completion_level !== "empty-scaffold-verified") contractFailures.push("scaffold-not-empty-scaffold-verified");
   if (manifest.schema_version === 3 && manifest.legacy_reconciliation?.status !== "approved") contractFailures.push("legacy-scaffold-reconciliation-required");
-  const projectFiles = await files(projectRoot);
-  const missingArtifacts = adapter.artifacts.filter(([, pattern]) => !projectFiles.some((file) => pattern.test(file))).map(([name]) => name);
-  const skillDrift = await downstreamDrift(manifest, adapter.skills);
+  const artifacts = inspectFirstSliceArtifacts(contract, projectRoot);
+  const missingArtifacts = artifacts.failures;
+  // Generation-time Skill hashes are provenance. Current authority was checked by execution preflight.
+  const skillDrift = [];
   if (contractFailures.length || missingArtifacts.length || skillDrift.length) {
     const report = { verification_mode: "first-slice", project_root: projectRoot, slice_contract_ref: sliceContractFile, scaffold_manifest_ref: manifestPath, generated_at: isoNow(), status: "failed", completion_level: manifest.completion_level, contract_failures: contractFailures, missing_artifacts: missingArtifacts, downstream_skill_drift: skillDrift, commands: [] };
     await writeJsonAtomic(reportPath, report);
@@ -144,9 +87,15 @@ export async function runFirstSliceVerification(projectRoot, evidenceDir, sliceC
   }
 
   const mavenEvidence = path.join(evidenceDir, "maven");
-  const wrapper = await runScaffoldVerification(projectRoot, mavenEvidence, environment, { firstSlice: true });
-  const passed = wrapper.status === "passed";
-  const report = { verification_mode: "first-slice", project_root: projectRoot, slice_contract_ref: sliceContractFile, scaffold_manifest_ref: manifestPath, generated_at: isoNow(), status: passed ? "passed" : "failed", failure_category: wrapper.failure_category, completion_level: passed ? "first-slice-verified" : manifest.completion_level, contract_failures: [], missing_artifacts: [], downstream_skill_drift: [], commands: wrapper.commands };
+  const startedAt = Date.now();
+  const wrapper = await runScaffoldVerification(projectRoot, mavenEvidence, environment, { firstSlice: true, systemProperties: artifacts.properties });
+  const mvc = manifest.architecture_family === "layered-mvc";
+  const tests = wrapper.status === "passed" ? verifyFirstSliceTests(contract, projectRoot, startedAt, {
+    module: `${manifest.project_name}-${mvc ? "server" : "bootstrap"}`,
+    type: `${manifest.base_package}.${mvc ? "architecture.LayeredMvcArchitectureTest" : "ArchitectureRulesTest"}`
+  }) : { status: "not-executed", failures: [], evidence: [] };
+  const passed = wrapper.status === "passed" && tests.status === "passed";
+  const report = { verification_mode: "first-slice", project_root: projectRoot, slice_contract_ref: sliceContractFile, scaffold_manifest_ref: manifestPath, generated_at: isoNow(), status: passed ? "passed" : "failed", test_execution: tests, failure_category: wrapper.failure_category || (tests.status === "failed" ? "first-slice-tests" : null), completion_level: passed ? "first-slice-verified" : manifest.completion_level, contract_failures: [], missing_artifacts: [], downstream_skill_drift: [], commands: wrapper.commands };
   await writeJsonAtomic(reportPath, report);
   if (passed) {
     manifest.completion_level = "first-slice-verified";
@@ -162,7 +111,7 @@ function parseArgs(argv) {
   const result = {};
   for (let index = 0; index < argv.length; index += 2) {
     const flag = argv[index], value = argv[index + 1];
-    if (!["--project-root", "--evidence-dir", "--slice-contract-file"].includes(flag) || !value) throw new Error("usage: run_first_slice_verification.mjs --project-root DIR --evidence-dir DIR --slice-contract-file FILE");
+    if (!["--project-root", "--evidence-dir", "--slice-contract-file", "--contract-root", "--approval-ref", "--work-unit"].includes(flag) || !value) throw new Error("usage: run_first_slice_verification.mjs --project-root DIR --evidence-dir DIR --slice-contract-file FILE");
     result[flag.slice(2).replaceAll(/-([a-z])/g, (_, letter) => letter.toUpperCase())] = value;
   }
   if (!result.projectRoot || !result.evidenceDir || !result.sliceContractFile) throw new Error("project root, evidence dir, and slice contract file are required");
@@ -172,7 +121,7 @@ function parseArgs(argv) {
 async function main() {
   try {
     const args = parseArgs(process.argv.slice(2));
-    const report = await runFirstSliceVerification(args.projectRoot, args.evidenceDir, args.sliceContractFile);
+    const report = await runFirstSliceVerification(args.projectRoot, args.evidenceDir, args.sliceContractFile, process.env, args);
     process.stdout.write(`${report.status}: ${path.join(path.resolve(args.evidenceDir), "first-slice-verification.json")}\n`);
     return report.status === "passed" ? 0 : 1;
   } catch (error) {

package/template/.cursor/skills/yss-ddd-scaffold-generator/scripts/run_scaffold_verification.mjs

@@ -62,7 +62,7 @@ function validateManifest(manifest) {
   if (manifest.schema_version === 4 ? manifest.current_version !== true : manifest.current_version !== manifest.contract_version) throw new Error("脚手架生成元数据清单不是当前合同版本");
   if (JSON.stringify(manifest.verification_commands) !== JSON.stringify(COMMANDS)) throw new Error("脚手架生成元数据清单验证命令不符合固定合同");
 }
-export async function run(projectRoot, evidenceDir, environment = process.env, { timeoutMs = 0, signal, platformOptions = {}, firstSlice = false } = {}) {
+export async function run(projectRoot, evidenceDir, environment = process.env, { timeoutMs = 0, signal, platformOptions = {}, firstSlice = false, systemProperties = {} } = {}) {
   const wrapper = path.join(projectRoot, "mvnw"), manifestPath = path.join(projectRoot, ".yss", "scaffold-generation.json");
   if (!await isFile(wrapper)) throw new Error(`项目根目录缺少 Maven wrapper: ${wrapper}`);
   if (!await isFile(manifestPath)) throw new Error(`项目根目录缺少脚手架生成元数据清单: ${manifestPath}`);
@@ -114,13 +114,14 @@ export async function run(projectRoot, evidenceDir, environment = process.env, {
     const stderrPath = path.join(evidenceDir, `mvnw-${phase}.stderr.log`);
     const startedAt = isoNow();
     const started = process.hrtime.bigint();
-    const execution = await runCommand(wrapper, [phase], { cwd: projectRoot, env: environment, timeoutMs, signal, stdoutFile: stdoutPath, stderrFile: stderrPath, secrets: [environment.MAVEN_REPO_USERNAME, environment.MAVEN_REPO_PASSWORD], progress: true });
+    const args = [phase, ...Object.entries(systemProperties).map(([key, value]) => `-D${key}=${value}`)];
+    const execution = await runCommand(wrapper, args, { cwd: projectRoot, env: environment, timeoutMs, signal, stdoutFile: stdoutPath, stderrFile: stderrPath, secrets: [environment.MAVEN_REPO_USERNAME, environment.MAVEN_REPO_PASSWORD], progress: true });
     const outcome = { ...execution, exitCode: execution.status };
     const durationMs = Number(process.hrtime.bigint() - started) / 1e6;
     await writeText(stdoutPath, redactSecrets(outcome.stdout, environment));
     await writeText(stderrPath, redactSecrets(outcome.stderr, environment));
     commands.push({
-      command: `./mvnw ${phase}`,
+      command: `./mvnw ${args.join(" ")}`,
       phase,
       exit_code: outcome.exitCode,
       failure_category: outcome.termination || classifyFailure(phase, outcome),

package/template/.cursor/skills/yss-domain/references/domain-layer-guide.md

@@ -62,7 +62,7 @@ public interface QualityTemplateGateway {
 - `*VO`、`PageResult`、Repository PO。
 - MyBatis、Spring MVC、Jackson、Swagger 类型。
 
-分页、列表和投影查询由 Application Query Port 定义，Infrastructure 实现。
+展示分页、列表和投影查询由 Application Query Port 定义，Infrastructure 实现。
 
 ## 5. Domain Error
 
@@ -99,3 +99,10 @@ Web Exception Translator 再将它映射为批准的状态码、错误码和消
 - 返回 YSS Skill Execution Result，包含 Domain 文件、行为测试、ArchUnit 结果及实际 `./mvnw ...` 证据。
 - 新聚合、不变量、状态机或跨上下文影响进入 `new_impacts` 并暂停。
 - 检测到旧架构时返回 `unsupported`；如需现代化，退出 scaffold 工作流并单独立项评估。
+
+## 聚合创建与重建
+
+- 创建入口执行当前创建规则；持久化重建入口恢复已批准状态并校验结构不变量，不重复发送创建事件、生成身份或执行外部调用。两者不得通过公开任意 setter 混为一体。
+- 值对象按值相等；聚合按稳定身份相等。集合对外只读，修改经业务方法；Java 8 使用普通类与防御性复制，不从示例推导 record 等高版本语法。
+- 领域错误携带稳定标识与参数；公开消息和 HTTP 状态由 Web 翻译。测试通过公开行为覆盖非法状态、重复动作和重建后语义一致性。
+- 为业务决策加载一个或一组聚合仍可使用 Domain Gateway；展示列表、分页、排序、统计和投影走 Application Query Port。返回 List 本身不是违规，须按调用目的判定。

package/template/.cursor/skills/yss-implementation-contract-compiler/references/boundaries.md

@@ -18,6 +18,7 @@
 
 | Capability | Primary skill | Task modes |
 | --- | --- | --- |
+| `governance.backend-spec-conformance` | `yss-backend-spec-review` | `guidance`, `troubleshooting`, `review-input` |
 | `writing.lifecycle-document` | `i-have-adhd` | `guidance` |
 | `architecture.technical-design` | `yss-technical-design` | `guidance`, `integration`, `review-input` |
 | `architecture.mvc-design` | `yss-technical-design` | `guidance`, `integration`, `review-input` |
@@ -57,6 +58,7 @@
 
 | Recipe | Capabilities |
 | --- | --- |
+| `backend.spec-conformance` | `governance.backend-spec-conformance`, `quality.java-code-style` |
 | `backend.ddd-domain-behavior` | `layer.domain`, `layer.application`, `quality.java-code-style` |
 | `backend.ddd-persistence-mybatis` | `layer.persistence`, `framework.mybatis`, `codegen.mapstruct`, `codegen.lombok`, `quality.java-code-style` |
 | `backend.ddd-http-api` | `layer.web-adapter`, `contract.dto-wire`, `contract.request-validation`, `contract.error-mapping`, `codegen.mapstruct`, `codegen.lombok`, `quality.java-code-style` |
@@ -106,6 +108,9 @@
 
 | Skill | Dependency | Type | Condition |
 | --- | --- | --- | --- |
+| `yss-backend-spec-review` | `alibaba-java-code-style` | `context-required` | — |
+| `yss-backend-spec-review` | `yss-implementation-contract-compiler` | `coordination-only` | — |
+| `yss-backend-spec-review` | `code-review` | `review-only` | — |
 | `prototype-review` | `i-have-adhd` | `context-conditional` | `lifecycle-document-output` |
 | `yss-implementation-contract-compiler` | `i-have-adhd` | `context-conditional` | `lifecycle-document-output` |
 | `yss-openapi-governance` | `i-have-adhd` | `context-conditional` | `lifecycle-document-output` |

package/template/.cursor/skills/yss-layered-mvc-scaffold-generator/assets/templates/architecture-rules-test.java.template

@@ -0,0 +1,66 @@
+package {{base_package}}.architecture;
+
+import com.tngtech.archunit.core.domain.JavaClass;
+import com.tngtech.archunit.core.domain.JavaClasses;
+import com.tngtech.archunit.core.domain.Dependency;
+import com.tngtech.archunit.core.importer.ImportOption;
+import com.tngtech.archunit.junit.AnalyzeClasses;
+import com.tngtech.archunit.junit.ArchTest;
+
+/** 空骨架可无业务类型；首切片由批准合同传入职责包和必须加载的实际类型。 */
+@AnalyzeClasses(packages = "{{base_package}}", importOptions = ImportOption.DoNotIncludeTests.class)
+class LayeredMvcArchitectureTest {
+    private static boolean inPackage(JavaClass type, String prefixes) {
+        for (String prefix : prefixes.split(",")) {
+            if (!prefix.isEmpty() && (type.getPackageName().equals(prefix)
+                    || type.getPackageName().startsWith(prefix + "."))) return true;
+        }
+        return false;
+    }
+
+    private static boolean role(JavaClass type, String name, String defaults) {
+        return inPackage(type, defaults) || inPackage(type, System.getProperty("yss.arch." + name, ""));
+    }
+
+    private static boolean controller(JavaClass type) {
+        return type.isAnnotatedWith("org.springframework.web.bind.annotation.RestController")
+                || type.isAnnotatedWith("org.springframework.stereotype.Controller")
+                || type.isMetaAnnotatedWith("org.springframework.stereotype.Controller");
+    }
+
+    private static void reject(boolean forbidden, Dependency dependency) {
+        if (forbidden) throw new AssertionError(dependency.getDescription());
+    }
+
+    @ArchTest
+    static void boundaries(JavaClasses classes) {
+        for (JavaClass origin : classes) {
+            boolean application = role(origin, "application", "{{base_package}}.service,{{base_package}}.core");
+            boolean infrastructure = role(origin, "infrastructure", "{{base_package}}.repository");
+            for (Dependency dependency : origin.getDirectDependenciesFromSelf()) {
+                JavaClass target = dependency.getTargetClass();
+                boolean targetWeb = controller(target) || role(target, "web",
+                        "{{base_package}}.server,{{base_package}}.rest,{{base_package}}.adapter.web");
+                boolean targetInfrastructure = role(target, "infrastructure", "{{base_package}}.repository");
+                reject(application && targetWeb, dependency);
+                reject(infrastructure && (targetWeb || role(target, "application",
+                        "{{base_package}}.service,{{base_package}}.core")), dependency);
+                reject(controller(origin) && targetInfrastructure, dependency);
+            }
+        }
+        if (Boolean.getBoolean("yss.firstSlice")) {
+            if (Boolean.getBoolean("yss.arch.requireController")) {
+                boolean foundController = false;
+                for (JavaClass type : classes) if (controller(type)) foundController = true;
+                if (!foundController) throw new AssertionError("Web slice did not load an actual Controller");
+            }
+            String required = System.getProperty("yss.arch.requiredTypes", "");
+            if (required.isEmpty()) throw new AssertionError("first slice requires contract-bound types");
+            for (String name : required.split(",")) {
+                boolean found = false;
+                for (JavaClass type : classes) if (type.getName().equals(name)) found = true;
+                if (!found) throw new AssertionError("architecture scope did not load " + name);
+            }
+        }
+    }
+}

package/template/.cursor/skills/yss-layered-mvc-scaffold-generator/scripts/generate_scaffold.mjs

@@ -120,7 +120,7 @@ function parentPom(contract, modules, platform) {
   <properties><java.version>${v.java_version}</java.version><spring-boot.version>${v.boot_version}</spring-boot.version><maven.compiler.source>${v.java_version}</maven.compiler.source><maven.compiler.target>${v.java_version}</maven.compiler.target><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding><yss-components.version>${xml(c.yss_components_version)}</yss-components.version></properties>
   <modules>${modules.map((module) => `<module>${contract.project_name}-${module}</module>`).join("")}</modules>
   <dependencyManagement><dependencies>${dependency("org.springframework.boot", "spring-boot-dependencies", v.boot_version, "import").replace("</dependency>", "<type>pom</type></dependency>")}${dependency("com.yss.cloud", "yss-components-bom", "${yss-components.version}", "import").replace("</dependency>", "<type>pom</type></dependency>")}</dependencies></dependencyManagement>
-  <build><plugins><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-enforcer-plugin</artifactId><version>${v.enforcer_version}</version><executions><execution><id>enforce-platform</id><goals><goal>enforce</goal></goals><configuration><rules><requireJavaVersion><version>${v.java_range}</version></requireJavaVersion><requireMavenVersion><version>[3.6.3,)</version></requireMavenVersion><dependencyConvergence/></rules></configuration></execution></executions></plugin></plugins><pluginManagement><plugins><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId><version>${v.boot_version}</version><executions><execution><goals><goal>repackage</goal></goals></execution></executions></plugin><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-surefire-plugin</artifactId><version>${v.surefire_version}</version></plugin><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId><version>${v.compiler_version}</version><configuration><source>${v.java_version}</source><target>${v.java_version}</target><parameters>true</parameters><annotationProcessorPaths><path><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><version>${v.lombok_version}</version></path><path><groupId>org.mapstruct</groupId><artifactId>mapstruct-processor</artifactId><version>${v.mapstruct_version}</version></path><path><groupId>org.projectlombok</groupId><artifactId>lombok-mapstruct-binding</artifactId><version>0.2.0</version></path></annotationProcessorPaths></configuration></plugin></plugins></pluginManagement></build>
+  <build><plugins><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-enforcer-plugin</artifactId><version>${v.enforcer_version}</version><executions><execution><id>enforce-platform</id><goals><goal>enforce</goal></goals><configuration><rules><requireJavaVersion><version>${v.java_range}</version></requireJavaVersion><requireMavenVersion><version>[3.6.3,)</version></requireMavenVersion><dependencyConvergence/></rules></configuration></execution></executions></plugin></plugins><pluginManagement><plugins><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId><version>${v.boot_version}</version><executions><execution><goals><goal>repackage</goal></goals></execution></executions></plugin><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-surefire-plugin</artifactId><version>${v.surefire_version}</version></plugin><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId><version>${v.compiler_version}</version><configuration><source>${v.java_version}</source><target>${v.java_version}</target><parameters>true</parameters><annotationProcessorPaths><path><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><version>${v.lombok_version}</version></path><path><groupId>org.mapstruct</groupId><artifactId>mapstruct-processor</artifactId><version>${v.mapstruct_version}</version></path><path><groupId>org.projectlombok</groupId><artifactId>lombok-mapstruct-binding</artifactId><version>${v.lombok_mapstruct_binding_version}</version></path></annotationProcessorPaths></configuration></plugin></plugins></pluginManagement></build>
 </project>`;
 }
 
@@ -130,6 +130,7 @@ function modulePom(contract, module, modules, platform) {
   const dependencies = [];
   if (module === "server") {
     dependencies.push(own(applicationModule), dependency("org.springframework.boot", platform.web_starter), dependency("org.springframework.boot", "spring-boot-starter-validation"), dependency("org.springframework.boot", "spring-boot-starter-test", null, "test"), dependency("com.tngtech.archunit", "archunit-junit5", platform.versions.archunit, "test"));
+    dependencies.push(dependency("org.projectlombok", "lombok", platform.versions.lombok, "test"));
     if (platform.web_test_starter !== "spring-boot-starter-test") dependencies.push(dependency("org.springframework.boot", platform.web_test_starter, null, "test"));
     if (modules.includes("client")) dependencies.push(own("client"));
     dependencies.push(dependency("com.h2database", "h2", null, "test"), dependency("org.mapstruct", "mapstruct", platform.versions.mapstruct), dependency("com.yss.cloud", "yss-component-dto"));
@@ -263,7 +264,8 @@ export async function generate(options, { skillId = SKILL_ID, architectureProfil
     await put(projectRoot, `${serverRoot}/src/main/resources/application-scaffold-local.yml`, localDatabaseConfiguration(options.projectName));
     await put(projectRoot, `${serverRoot}/src/test/resources/application-scaffold-test.yml`, localDatabaseConfiguration(`${options.projectName}_test`));
     await put(projectRoot, `${serverRoot}/src/test/java/${packagePath}/${applicationClass}Test.java`, `package ${options.basePackage};\n\nimport org.junit.jupiter.api.Test;\nimport org.springframework.boot.test.context.SpringBootTest;\nimport org.springframework.test.context.ActiveProfiles;\n\n@SpringBootTest\n@ActiveProfiles("scaffold-test")\nclass ${applicationClass}Test {\n    @Test\n    void contextLoads() {\n    }\n}`);
-    await put(projectRoot, `${serverRoot}/src/test/java/${packagePath}/architecture/LayeredMvcArchitectureTest.java`, `package ${options.basePackage}.architecture;\n\nimport static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses;\n\nimport com.tngtech.archunit.core.importer.ImportOption;\nimport com.tngtech.archunit.junit.AnalyzeClasses;\nimport com.tngtech.archunit.junit.ArchTest;\nimport com.tngtech.archunit.lang.ArchRule;\n\n@AnalyzeClasses(packages = "${options.basePackage}", importOptions = ImportOption.DoNotIncludeTests.class)\nclass LayeredMvcArchitectureTest {\n    @ArchTest\n    static final ArchRule repositoryDoesNotDependOnUpperLayers = noClasses().that().resideInAPackage("..repository..").should().dependOnClassesThat().resideInAnyPackage("..service..", "..server..");\n}`);
+    const architectureTemplate = await readFile(path.join(SKILL_ROOT, "assets/templates/architecture-rules-test.java.template"), "utf8");
+    await put(projectRoot, `${serverRoot}/src/test/java/${packagePath}/architecture/LayeredMvcArchitectureTest.java`, architectureTemplate.replaceAll("{{base_package}}", options.basePackage));
     await put(projectRoot, `${serverRoot}/src/test/java/${packagePath}/PlatformIntegrationTest.java`, platformSmokeTest(options.basePackage, platform, contract.module_profile.requested_capabilities));
     const wrapper = path.join(REPOSITORY_ROOT, ".agents/skills/yss-ddd-scaffold-generator/assets/wrapper");
     await cp(wrapper, projectRoot, { recursive: true });

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

@@ -55,3 +55,7 @@ description: 用于 YSS MyBatis / MyBatis-Plus 组件能力核验、接入决策
 ## 平台与源码门禁
 
 接入、修改、代码生成或给出精确类名/配置前，读取 [后端组件平台与源码门禁](../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-mybatis --platform-line <line> --source-root <matching-root>` 运行统一 freshness 校验。平台线与源码根不匹配、组件 tree 不一致、组件子树 dirty、索引缺少平台信号，或 Manifest / 组件 GAV 缺少 verified 兼容证据时返回 `blocked`；不得回退另一代索引，也不在业务实现中升级、降级或替换 YSS 组件。既有工程只读分诊可继续，但不得据此宣称跨 Boot/JDK 兼容。
+
+## 持久化选择记录
+
+在已有数据合同 / persistence_strategy 中记录：实际 Mapper 基类、组件源码与平台绑定、分页唯一责任者、主键与审计填充，以及命中批量时的 SQL 入口、分批大小和方言证据。`BaseMapper` 与组件扩展基类按所需能力选择，不因命名不同判违规；依赖存在和循环 insert 均不证明批量能力。未命中的能力不强制生成。

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

@@ -4,9 +4,9 @@
 
 ## 前置与所有权
 
-- 写模型必须已有批准的 Domain Gateway；读模型必须已有批准的 Application Query Port。缺失或需要改变签名时返回 `new_impacts`，由 `yss-domain` / `yss-application` 和实现合同编译器处理。
+- 写模型必须已有批准的 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。
+- Domain Gateway 只交换 Aggregate、Domain Model、领域值和标识；展示分页、列表和读模型走 Application Query Port，`PageQuery` 不进入 Domain。
 
 ## 结构决策
 
@@ -21,3 +21,11 @@
 - 经 Domain Gateway 保存后可重新加载语义等价的 Aggregate。
 - Query Port 覆盖分页 total、空结果、排序/过滤白名单和字段转换。
 - Mapper/Repository 使用批准数据库 fixture；H2 不能证明生产方言。
+
+## 持久化决策与映射
+
+- 在既有 persistence_strategy / 数据合同中明确 Mapper 基类及源码依据、主键、逻辑删除、审计填充、并发版本、敏感字段、分页责任和命中时的批量策略。未命中分页或批量时写明理由，不创建空适配器。
+- 多表聚合按同一 Application 事务保存，重载后比较身份、值对象、集合与业务状态；并发写入按批准策略验证冲突或幂等结果。
+- 机械字段使用 Spring MapStruct Bean；聚合重建可通过显式工厂或自定义映射方法。业务状态校验由领域入口拥有，禁止为了映射而开放破坏不变量的 setter。
+- 创建与更新的 null 语义、枚举未知值和审计字段保留必须有测试；转换器不得静默创造业务默认值或吞掉非法持久化状态。
+- 包名与类型后缀来自批准工程基线；Mapper 与 Repository 的命名不能替代职责、运行时发现和行为验证。

package/template/.cursor/skills/yss-web-controller/references/web-adapter-layer-guide.md

@@ -84,3 +84,11 @@ public interface QualityRuleWebConvertor {
 - Wire forbidden fields 无法绑定。
 - OpenAPI 3 注解、YSS Result wrapper、Validation namespace 与平台 Profile 一致。
 - 执行项目根 `./mvnw test/package`，并保留 HTTP/serialization/exception 证据。
+
+## 非 CRUD 适配
+
+认证、OAuth 回调、Cookie、流式响应及协议端点可以手工实现，不强行套 CRUD metadata；仍消费批准的 wire 合同、Application seam 和平台配置。Controller 不直连 Domain Gateway，也不自行编排登录、撤销或持久化。
+
+协议转换、Cookie/Header 处理归 Web；业务决策归 Application/Domain。异常翻译器可以依赖领域错误类型，不能据此允许 Controller 调用领域端口。MapStruct 处理机械字段映射，协议编码及显式领域工厂适配使用有测试的自定义方法。
+
+生成器推荐 rest 布局；已登记的 adapter.web 等布局通过合同绑定识别。审查按模块、实际 Controller 类型和依赖方向进行，包名偏离不能让检查空匹配通过。

package/template/.pi/skills/code-review/references/yss-review-standards.md

@@ -59,3 +59,25 @@ YSS 页面模块约定（YTable、YFormily、页面骨架等）走 Standards，
 | `drift`、`new_impacts`、`required_skills` 与真实影响不一致 | 合同标 `stale`，回 实现合同编译器 或更早生命周期阶段；禁止在旧合同上继续编码 |
 
 `not-applicable` 仅当影响面未命中。命中后的 mandatory 不得豁免；只允许修复，或写完整 `seam-deferred`（风险、责任人、后续 Ticket、验证计划、目标版本或发布日期）。禁止为日常 Alibaba / YSS 新增生物人豁免门禁；安全 / 公共 API 仍走既有 `TODO-HUMAN-REVIEW` 与生物人门禁。
+
+
+## 可执行后端审查结果
+
+后端 `work-unit.code-review` 到交付的流转由 `scripts/lib/backend-review.mjs` 检查。
+`decision_state.review_input` 绑定 `slice_contract_ref`、`approval_ref`、跨仓时的 `work_unit_id`、`project_root`、既有候选的 `review_mode`、
+`candidate_snapshot_ref`、`implementation_candidate_ref`、`candidate_digest`、
+`implementation_actor_id`、`implementation_instance_id` 和 `actual_skill_impacts`（无新增影响为 `[]`）。
+`review_result_ref` 指向唯一 `code-review` 结果；记录 `result: completed`、合同原始字节的
+`contract_digest`、候选摘要、`reviewer` / `implementer` 的 actor_id / runtime_id / instance_id，
+并分别记录 `axes.Standards` 和 `axes.Spec`。自审不能用不同角色名替代不同执行实例。
+
+复用 `constraint_results`，每个适用技能至少一项包含 `axis: Standards`、`skill`、`constraint`、
+`status`、`rule_ref`、规则文件 SHA-256 `rule_digest`、`code_ref`、`evidence_ref`、证据 SHA-256
+`evidence_digest`。按原文定位具体规则，禁止仅写“符合规范”。无持久化影响时 Repository/MyBatis
+可写有原因的 not-applicable；合同必需技能不得豁免。`findings` 的阻断项必须关闭；建议可绑定
+`follow_up_ref` 进入待办。修复后重新捕获候选，重验受影响规则及依赖，并显式重绑复用证据。
+
+工作树候选复用现有 packed candidate 工具；审查证据可排除，业务文件不可排除。已提交候选绑定
+不可变 tree ID，并核对当前清洁 checkout。读取结构化结果不会代替 Reviewer 的实际规则判断。
+
+`verification_results` 必须包含实际 command、executed_at、exit_code=0、candidate_digest，以及日志 evidence_ref/evidence_digest。缺少本次机器检查或日志漂移不能完成审查。

package/template/.pi/skills/lombok/SKILL.md

@@ -6,7 +6,7 @@ description: "配置或排查 Lombok 注解、构造器、Builder 和注解处
 
 ## YSS 阶段 7 执行结果
 
-- 消费工程 Java 与处理器基线；三个新后端 Profile 为 Java 8。MapStruct binding 进入 annotationProcessorPaths，不作为业务依赖单独引入；示例不授权升级依赖。MVC PO 的身份/敏感字段风险与 DDD 相同，不能默认全量 @Data。
+- 消费工程 Java 与处理器基线；Java 语法、API、处理器与测试工具消费批准的精确平台配置。MapStruct binding 进入 annotationProcessorPaths，不作为业务依赖单独引入；示例不授权升级依赖。MVC PO 的身份/敏感字段风险与 DDD 相同，不能默认全量 @Data。
 - 消费批准后的 Slice Contract/work unit，只在允许路径内调整 POJO 样板和注解处理器配置。
 - 受控生成必须记录对象类型、选用/排除注解、实体关系和敏感字段风险、编译/测试实际结果。
 - 按 `yss-implementation-contract-compiler` 的统一 Execution Result 返回 changed files、证据、偏离和新增影响；`@Data` 实体风险、处理器配置缺失或越界路径返回 `violation`。

package/template/.pi/skills/mapstruct/SKILL.md

@@ -6,7 +6,7 @@ description: "实现或排查 MapStruct DTO、PO、Domain 映射及 Lombok 集
 
 ## YSS 阶段 7 执行结果
 
-- Java、依赖与处理器版本来自工程基线，不从下面通用示例推断。三个新后端 Profile 为 Java 8；MVC 的 wire/internal 转换在 server，core/service 不依赖 client，Repository 不依赖上层 DTO。采用 Spring Bean 和构造器注入，显式映射或忽略字段；禁止通过全局 IGNORE 掩盖合同字段遗漏。
+- Java、依赖与处理器版本来自工程基线，不从下面通用示例推断。Java 语法、API、处理器与测试工具均消费批准的精确平台配置；MVC 的 wire/internal 转换在 server，core/service 不依赖 client，Repository 不依赖上层 DTO。采用 Spring Bean 和构造器注入，显式映射或忽略字段；禁止通过全局 IGNORE 掩盖合同字段遗漏。
 - 消费批准后的 Slice Contract/work unit，只为合同中的 DTO/VO/PO/Domain 转换生成 Mapper/Convertor。
 - 受控生成必须记录 source/target、忽略字段、更新语义、Lombok processor 配置和 mapper 行为测试。
 - 按 `yss-implementation-contract-compiler` 的统一 Execution Result 返回生成/源文件、测试和实际验证；未映射字段、反射/BeanUtils 退化或越界路径返回 `violation`。
@@ -26,3 +26,5 @@ description: "实现或排查 MapStruct DTO、PO、Domain 映射及 Lombok 集
 按变更验证字段覆盖、null、更新和边界值；处理器调整需实际编译。不要把所有参考示例当作必跑清单。
 
 查第三方行为时使用 `yss-research`，来源为 [MapStruct 官方文档](https://mapstruct.org/documentation/stable/reference/html/)；不假定某个 MCP 工具已安装。
+
+聚合重建使用领域工厂或有测试的显式映射方法；MapStruct 只承担机械映射，不得为处理器增加破坏不变量的 setter。该方式不豁免字段覆盖、null 语义和往返一致性验证。

package/template/.pi/skills/yss-application/references/application-layer-guide.md

@@ -85,3 +85,10 @@ public interface QualityTemplateApplicationConvertor {
 ## 8. 旧架构边界
 
 检测到 AppService 接收 client Cmd、返回 client VO、调用返回 VO 的 Domain Gateway 或位于 `core/service` 时，返回 `unsupported`，不得由新 scaffold 或本指南自动改写。旧项目继续按原工程维护；现代化改造必须单独立项、先评估再逐切片迁移。
+
+## 事务与外部副作用
+
+- 合同标明需要原子提交的数据库写入及所属用例；事务从 Application 公共代理 seam 进入。无需原子写入的查询或纯计算不强制增加事务注解。
+- Repository 参与既有事务，不另行决定业务提交边界。多表聚合保存的回滚测试从用例入口注入中途失败，不能只验证单个 Mapper。
+- Redis、邮件、HTTP 调用不因数据库事务自动获得原子性。按批准合同选择提交后缓存失效、可重试事件或 outbox；需要持久重试时不能只依赖内存事件。
+- 幂等键、重复请求结果、重试范围及失败恢复来自合同；不在技能中默认引入分布式事务或通用重试。测试覆盖回滚不发布、提交后失败及重复消费。

package/template/.pi/skills/yss-backend-spec-review/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: yss-backend-spec-review
+description: 审计既有 Java 后端工程对 YSS 技能规范和已批准业务 Spec 的符合性，并在授权范围内编排整改、独立审查和复验直至达标。适用于历史工程规范补齐、全工程体检和持续整改；普通 PR 审查使用 code-review。
+---
+
+# 既有后端工程规格审查与整改
+
+这是既有工程的符合性与整改入口，不是第二个通用代码审查器。用户要求“修复直到符合规范”时持续推进已授权整改；要求“只审查”时仅输出差距与整改建议。仅创建本 Skill 不代表获准修改某个业务工程。
+
+## 输入与事实来源
+
+- 明确工程根、审查范围与读写授权；记录 HEAD、已有工作区改动、当前实现仓登记及回滚点。不能将“当前系统”解释为所有子项目，也不以固定 `apps/backend` 目录替代登记。
+- 读取治理仓身份、根 `CONTEXT.md`、工程基线、架构身份、精确平台、业务 Spec / ADR / OpenAPI、已有 Slice 合同与批准记录。未纳管工程可以先做只读盘点；修改前按所属 Harness 的实现接入流程补齐输入。
+- 规范来自当前工程适用且已锁定的 canonical YSS Skill、版本/hash 和组件源码索引。当前最新 Skill 与工程锁定版本有差异时单列迁移差距，不能静默改锁或追着浮动版本整改。
+- 技能规范属于 **Standards**；业务行为属于 **Spec**。技能文件不能冒充产品 Spec，测试全绿也不能替代任一轴。
+
+## 执行闭环
+
+1. **盘点完整范围**：按模块、责任类型、入口、持久化和组件建立覆盖清单。初次审计包含未修改的既有代码、手工适配器、配置/XML 和测试，不局限于 diff；登记未检查项及原因。详细步骤见 [审计与整改流程](references/remediation-workflow.md)。
+2. **编译适用规则**：以合同 `required_skills` 加实际影响形成 Skill 清单，按 [检查输入](references/check-inputs.md) 加载适用规则。每项 finding 关联规则、适用原因、代码位置、证据和验收方法；复用 `constraint_results`，不另建规范注册表。
+3. **形成可执行整改单元**：按业务路径和风险拆窄切片，保护现有行为，明确允许写路径、回归 seam 与回滚方式。已有授权且批准合同当前时直接推进；缺合同则由实现合同编译器起草、所属编排器批准，本 Skill 不自批、不设置 `ready-for-agent`。现有违规是修复输入，不能要求违规先消失才能提出整改。
+4. **逐单元修复并验证**：调用适用 YSS 分层/组件技能。业务行为按 `tdd`；纯配置或机械修改记录不适用原因与可执行验证。优先工程根 `./mvnw`，保留实际命令、退出码、测试执行数量和证据摘要。禁止为通过检查删除测试、缩小检查包、改弱规则或恢复退役组件。
+5. **独立复审**：修复者不能自审。由独立 Reviewer 使用唯一 `code-review`，消费当前合同、技能集、候选摘要、所有未关闭 finding 及修复影响的依赖，分别给出 Standards / Spec 结论。Reviewer 只报告，不写实现；缺独立执行条件时记录阻塞，不能自行替代签字。
+6. **继续闭环**：`violation` 返回实施者修复；`drift` / `new_impacts` 使合同 stale 并回编译器；缺凭据或外部组件证据明确 blocked。更新候选，复验受影响项及依赖；其他项只有证据仍适用才可显式复用。同一原因连续未收敛时诊断根因、拆小整改单元，不以无限重试或增加审查轮数绕过既有 review_round 合同。
+7. **全范围对账后退出**：回到最初覆盖清单，确认没有遗漏、未解决强制违规或未经验证的整改，且当前候选上的适用机器检查和独立审查通过。阶段修复完成不等于整个系统达标；残留项必须继续或报告具体阻塞。
+
+## 必须保留的边界
+
+- 保留已登记 DDD / Layered MVC 架构及目标 JDK / Boot；Java 8 合规不要求升级 Java 17。环境 JDK 不决定工程平台；架构转换、平台迁移、组件替换须另行路由。
+- 规范含糊、规则冲突或合理工程实践与 Skill 不符时，记录规则所有者与证据，回模板维护评估；不能直接修改 Skill 让当前工程“合规”，也不能把启发式建议升为强制规则。
+- 业务 Spec 缺失或相互矛盾时，可完成有证据的 Standards 盘点；Spec 轴保留 `missing_evidence`，不从实现倒推并伪造批准。行为保持式整改也须有已确认的验收 seam。
+- 生成 Manifest 是历史来源，当前状态与迁移通过工程基线对账；不得重写生成历史。既有工程不重跑脚手架覆盖代码。
+- `not-applicable` 仅用于未触发的规则。延期 seam 必须满足原合同，但尚未满足的强制规范不能因此记成已达标。非阻断建议进入待办。
+- 不自动提交、推送、发布、迁移生产数据或修改只读参考仓。关键决定只在实际新增影响或已有边界命中时回用户，不对每个 Skill 重复请求批准。
+
+## 输出与完成依据
+
+复用 `docs/templates/review-report-template.md`、当前 Slice 的 YSS Skill Execution Result 和 [审计与整改流程中的记录要求](references/remediation-workflow.md#证据与交接)。报告列明审查覆盖、Standards / Spec 分轴结论、修复前后 finding、候选/规则摘要、实际验证、独立 Reviewer 身份和剩余阻塞。只对本次覆盖且有证据的范围声明符合规范，不自动证明平台已认证或允许发布。