create-yss-spec 3.4.7 → 3.4.9

package/template/scripts/lib/first-slice-artifacts.mjs

@@ -0,0 +1,47 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** Declarations bind responsibilities to compiled types, not naming conventions. */
+export function inspectFirstSliceArtifacts(contract, projectRoot) {
+  const declaration = contract.backend?.first_slice;
+  const failures = [], properties = { 'yss.firstSlice': 'true' };
+  if (!declaration || !Array.isArray(declaration.artifacts) || !declaration.artifacts.length) {
+    return { failures: ['backend.first_slice.artifacts-required'], properties };
+  }
+  const roles = new Map(), types = [], seen = new Set();
+  const root = fs.realpathSync(projectRoot);
+  for (const item of declaration.artifacts) {
+    const label = item?.type || item?.path || 'unknown';
+    try {
+      if (!['domain','application','infrastructure','web','test'].includes(item.role)) throw Error('invalid-role');
+      if (!/^[a-zA-Z_$][\w$]*(\.[a-zA-Z_$][\w$]*)+$/.test(item.type || '')) throw Error('qualified-type-required');
+      if (seen.has(item.type)) throw Error('duplicate-type');
+      seen.add(item.type);
+      if (!item.path || path.isAbsolute(item.path) || item.path.split(/[\\/]/).includes('..')) throw Error('relative-path-required');
+      const file = fs.realpathSync(path.resolve(root, item.path));
+      if (!file.startsWith(`${root}${path.sep}`)) throw Error('path-escape');
+      const source = fs.readFileSync(file, 'utf8');
+      const pkg = source.match(/^\s*package\s+([\w.]+)\s*;/m)?.[1];
+      const name = item.type.slice(item.type.lastIndexOf('.') + 1);
+      if (`${pkg}.${name}` !== item.type || !new RegExp(`\\b(class|interface|enum|record)\\s+${name}\\b`).test(source)) throw Error('declared-type-mismatch');
+      if (item.role === 'test') {
+        if (!item.path.includes('/src/test/java/')) throw Error('test-source-required');
+      } else {
+        if (!item.path.includes('/src/main/java/')) throw Error('main-source-required');
+        types.push(item.type);
+        const packages = roles.get(item.role) || new Set(); packages.add(pkg); roles.set(item.role, packages);
+      }
+    } catch (error) { failures.push(`${label}:${error.message}`); }
+  }
+  const aliases = { service: 'application', core: 'application', repository: 'infrastructure', server: 'web' };
+  for (const layer of contract.backend.affected_layers || []) {
+    const role = aliases[layer] || layer;
+    if (['domain','application','infrastructure','web'].includes(role) && !roles.has(role)) failures.push(`affected-role-empty:${role}`);
+  }
+  if (!declaration.artifacts.some(item => item.role === 'test')) failures.push('behavior-test-binding-required');
+  if ((contract.backend.affected_layers || []).some(layer => ['web','server'].includes(layer))) properties['yss.arch.requireController'] = 'true';
+  if (!types.length) failures.push('business-type-required');
+  properties['yss.arch.requiredTypes'] = types.join(',');
+  for (const [role, packages] of roles) properties[`yss.arch.${role}`] = [...packages].join(',');
+  return { failures, properties };
+}

package/template/scripts/lib/first-slice-tests.mjs

@@ -0,0 +1,24 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { parseXmlDocument } from '../vendor/xml.mjs';
+const array = value => value === undefined ? [] : Array.isArray(value) ? value : [value];
+
+export function verifyFirstSliceTests(contract, projectRoot, startedAt, architectureType) {
+  const declarations = contract.backend.first_slice.artifacts.filter(item => item.role === 'test');
+  const required = [...declarations.map(item => ({ type: item.type, module: item.path.split('/src/test/java/')[0] })), architectureType];
+  const evidence = [], failures = [];
+  for (const item of required) {
+    try {
+      const candidates = ['surefire-reports','failsafe-reports'].map(folder => path.join(projectRoot,item.module,'target',folder,`TEST-${item.type}.xml`));
+      const ref = candidates.find(file => fs.existsSync(file) && fs.statSync(file).mtimeMs >= startedAt);
+      if (!ref) throw Error('fresh execution report missing');
+      const bytes = fs.readFileSync(ref), suite = parseXmlDocument(bytes.toString()).testsuite;
+      const cases = array(suite?.testcase);
+      if (!cases.length || cases.some(c => ['failure','error','skipped'].some(key => Object.hasOwn(c,key)))) throw Error('test not executed successfully');
+      if (cases.some(c => c['@_classname'] !== item.type)) throw Error('test class does not match contract');
+      evidence.push({type:item.type,ref,sha256:createHash('sha256').update(bytes).digest('hex'),test_count:cases.length});
+    } catch(error) { failures.push(`${item.type}:${error.message}`); }
+  }
+  return { status: failures.length ? 'failed' : 'passed', evidence, failures };
+}

package/template/scripts/lib/lifecycle-transition.mjs

@@ -9,6 +9,7 @@ import { validatePlanSpecEntry } from "./plan-spec-entry.mjs";
 import path from "node:path";
 import { validateApiContractDecision } from "./api-contract-decision.mjs";
 import { loadApprovalRecord, validateApprovalRecord } from "./approval-record.mjs";
+import { validateBackendReview } from "./backend-review.mjs";
 import { ROOT } from "./lifecycle-registry.mjs";
 
 const IMPLEMENTATION_WORK_UNIT = "work-unit.slice-implementation";
@@ -248,6 +249,14 @@ function validateTicketReference(ref, trackerKind) {
  * by `validateWorkflowExecutionResult` before this function is called.
  */
 export function validateNextRoute(currentWorkUnit, nextRoute, decisionState, options = {}) {
+  if (currentWorkUnit === "work-unit.code-review" && nextRoute === "work-unit.release-and-retrospective") {
+    try {
+      if (decisionState?.review_input?.scope_kind !== "change") throw new Error("只读基线审计不能关闭实现审查");
+      validateBackendReview(decisionState, { root: options.root || ROOT });
+    }
+    catch (error) { return blockedResult(["backend-review-incomplete"], [error.message]); }
+  }
+
 
   if (["work-unit.technical-analysis", TICKET_DECOMPOSITION_WORK_UNIT, IMPLEMENTATION_WORK_UNIT, "work-unit.frontend-implementation-verification"].includes(nextRoute)) {
     try { enforceFrontendDelivery(decisionState, { root: options.root, phase: nextRoute === IMPLEMENTATION_WORK_UNIT ? "implementation" : "inputs" }); }

package/template/scripts/lib/maintenance-candidate.mjs

@@ -0,0 +1,160 @@
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { parseDocument, stringify } from "../vendor/yaml.mjs";
+
+const MAGIC = Buffer.from("YSS-WORKTREE-CANDIDATE-V1\0", "ascii");
+const MAX_BUFFER = 512 * 1024 * 1024;
+const MAINTENANCE_EVIDENCE_ROOT = ".template-source/evidence/maintenance";
+const CANDIDATE_FILES = ["candidate-manifest.yaml", "candidate.bin", "tracked.diff"];
+
+function fail(message) { throw new TypeError(message); }
+function ensure(condition, message) { if (!condition) fail(message); }
+function git(args, root, encoding = "utf8") {
+  const result = spawnSync("git", args, { cwd: root, encoding, maxBuffer: MAX_BUFFER });
+  if (result.status !== 0) fail((typeof result.stderr === "string" ? result.stderr : result.stderr?.toString()).trim() || `git ${args.join(" ")} 执行失败`);
+  return result.stdout;
+}
+function uint64(value) { const buffer = Buffer.alloc(8); buffer.writeBigUInt64BE(BigInt(value)); return buffer; }
+function uint32(value) { const buffer = Buffer.alloc(4); buffer.writeUInt32BE(value >>> 0); return buffer; }
+function splitNull(buffer) {
+  const result = [];
+  let start = 0;
+  for (let index = 0; index < buffer.length; index += 1) if (buffer[index] === 0) { if (index > start) result.push(buffer.subarray(start, index)); start = index + 1; }
+  if (start < buffer.length) result.push(buffer.subarray(start));
+  return result;
+}
+function normalizeRelative(value, label) {
+  ensure(typeof value === "string" && value.trim(), `${label} 不能为空`);
+  const normalized = value.replaceAll("\\", "/").replace(/^\.\//, "").replace(/\/$/, "");
+  ensure(normalized && !path.posix.isAbsolute(normalized) && path.posix.normalize(normalized) === normalized && normalized !== ".." && !normalized.startsWith("../"), `${label} 必须是规范的仓库内相对路径`);
+  return normalized;
+}
+function isMaintenanceEvidencePath(value) {
+  return value === MAINTENANCE_EVIDENCE_ROOT || value.startsWith(`${MAINTENANCE_EVIDENCE_ROOT}/`);
+}
+function readLength(buffer, offset, bytes, label) {
+  ensure(offset + bytes <= buffer.length, `packed candidate 缺少 ${label}`);
+  const value = bytes === 8 ? buffer.readBigUInt64BE(offset) : BigInt(buffer.readUInt32BE(offset));
+  ensure(value <= BigInt(Number.MAX_SAFE_INTEGER), `packed candidate ${label} 过大`);
+  return { value: Number(value), offset: offset + bytes };
+}
+
+export function captureMaintenanceCandidate({ root, outputDir, baseRef = "HEAD", excludePaths = [] }) {
+  const repositoryRoot = path.resolve(root);
+  const outputPath = path.resolve(repositoryRoot, outputDir);
+  const outputRelative = normalizeRelative(path.relative(repositoryRoot, outputPath).replaceAll(path.sep, "/"), "outputDir");
+  ensure(isMaintenanceEvidencePath(outputRelative), `outputDir 必须位于 ${MAINTENANCE_EVIDENCE_ROOT}`);
+  ensure(!existsSync(outputPath), "outputDir 必须不存在，禁止复用可能含残留文件的候选目录");
+  ensure(Array.isArray(excludePaths), "excludePaths 必须是数组");
+  const explicitExclusions = excludePaths.map((value) => normalizeRelative(value, "excludePaths"));
+  for (const exclusion of explicitExclusions) ensure(isMaintenanceEvidencePath(exclusion), `excludePaths 只允许 ${MAINTENANCE_EVIDENCE_ROOT} 下的维护证据`);
+  const exclusions = [...new Set([outputRelative, ...explicitExclusions])];
+  const mergeBase = git(["merge-base", baseRef, "HEAD"], repositoryRoot).trim();
+  const trackedDiff = git(["diff", "--no-ext-diff", "--binary", "--full-index", mergeBase], repositoryRoot, null);
+  const rawPaths = splitNull(git(["ls-files", "-z", "--others", "--exclude-standard"], repositoryRoot, null))
+    .filter((rawPath) => {
+      const value = rawPath.toString();
+      return !exclusions.some((exclusion) => value === exclusion || value.startsWith(`${exclusion}/`));
+    })
+    .sort(Buffer.compare);
+  ensure(trackedDiff.length > 0 || rawPaths.length > 0, "维护候选不能为空");
+
+  const parts = [MAGIC, Buffer.from([0x54]), uint64(trackedDiff.length), trackedDiff];
+  const untrackedFiles = [];
+  const untrackedPathBytes = [];
+  for (const rawPath of rawPaths) {
+    ensure(!rawPath.includes(0) && rawPath.length > 0, "untracked path 无效");
+    const relative = rawPath.toString();
+    const absolute = path.resolve(repositoryRoot, relative);
+    ensure(!path.relative(repositoryRoot, absolute).startsWith(".."), `untracked path 越界: ${relative}`);
+    const stat = lstatSync(absolute);
+    let kind;
+    let content;
+    if (stat.isFile()) { kind = 0x52; content = readFileSync(absolute); }
+    else if (stat.isSymbolicLink()) { kind = 0x4c; content = readlinkSync(absolute, { encoding: "buffer" }); }
+    else fail(`候选包含不支持的 untracked 类型: ${relative}`);
+    parts.push(Buffer.from([0x55]), uint64(rawPath.length), rawPath, uint32(stat.mode), Buffer.from([kind]), uint64(content.length), content);
+    untrackedFiles.push(relative);
+    untrackedPathBytes.push(rawPath.toString("base64"));
+  }
+  const stream = Buffer.concat(parts);
+  const digest = createHash("sha256").update(stream).digest("hex");
+  const streamRef = `${outputRelative}/candidate.bin`;
+  const diffRef = `${outputRelative}/tracked.diff`;
+  const manifestRef = `${outputRelative}/candidate-manifest.yaml`;
+  const manifest = {
+    schema_version: 1,
+    candidate_kind: "yss-worktree-candidate-v1",
+    storage: "packed-stream",
+    review_mode: "worktree",
+    review_base_ref: baseRef,
+    merge_base: mergeBase,
+    implementation_candidate_ref: "working-tree",
+    candidate_snapshot_ref: manifestRef,
+    candidate_digest: digest,
+    tracked_diff_command: `git diff --no-ext-diff --binary --full-index ${mergeBase}`,
+    untracked_inventory_command: "git ls-files -z --others --exclude-standard",
+    untracked_diff_command: "packed in candidate.bin",
+    untracked_files: untrackedFiles,
+    untracked_path_bytes: untrackedPathBytes,
+    excluded_paths: exclusions,
+    snapshot_stream_ref: streamRef,
+    tracked_diff_ref: diffRef,
+    commit_list_command: `git log ${baseRef}..HEAD --oneline`
+  };
+  const outputParent = path.dirname(outputPath);
+  mkdirSync(outputParent, { recursive: true });
+  const stagingPath = mkdtempSync(path.join(outputParent, ".candidate-staging-"));
+  try {
+    writeFileSync(path.join(stagingPath, "candidate.bin"), stream);
+    writeFileSync(path.join(stagingPath, "tracked.diff"), trackedDiff);
+    writeFileSync(path.join(stagingPath, "candidate-manifest.yaml"), stringify(manifest, { lineWidth: 0 }));
+    renameSync(stagingPath, outputPath);
+  } finally {
+    if (existsSync(stagingPath)) rmSync(stagingPath, { recursive: true, force: true });
+  }
+  return { candidate_digest: digest, manifest, manifest_ref: manifestRef, files: [manifestRef, streamRef, diffRef] };
+}
+
+export function inspectMaintenanceCandidate({ manifestPath }) {
+  const absoluteManifest = path.resolve(manifestPath);
+  const document = parseDocument(readFileSync(absoluteManifest, "utf8"), { uniqueKeys: true });
+  ensure(document.errors.length === 0, document.errors[0]?.message || "candidate manifest 无法解析");
+  const manifest = document.toJS({ maxAliasCount: 0 });
+  ensure(manifest.storage === "packed-stream", "只支持 packed-stream candidate");
+  const candidateDir = path.dirname(absoluteManifest);
+  ensure(JSON.stringify(readdirSync(candidateDir).sort()) === JSON.stringify([...CANDIDATE_FILES].sort()), `packed candidate 目录必须恰好包含 ${CANDIDATE_FILES.join("、")}`);
+  const root = path.resolve(path.dirname(absoluteManifest), ...Array(manifest.candidate_snapshot_ref.split("/").length - 1).fill(".."));
+  ensure(path.resolve(root, manifest.candidate_snapshot_ref) === absoluteManifest, "candidate_snapshot_ref 未绑定当前 manifest");
+  const streamPath = path.resolve(root, manifest.snapshot_stream_ref);
+  const diffPath = path.resolve(root, manifest.tracked_diff_ref);
+  ensure(streamPath === path.join(candidateDir, "candidate.bin") && diffPath === path.join(candidateDir, "tracked.diff"), "packed candidate 引用必须绑定同目录规范文件");
+  const stream = readFileSync(streamPath);
+  ensure(createHash("sha256").update(stream).digest("hex") === manifest.candidate_digest.replace(/^sha256:/, ""), "candidate_digest 与 packed stream 不一致");
+  ensure(stream.subarray(0, MAGIC.length).equals(MAGIC), "packed stream magic 无效");
+  let offset = MAGIC.length;
+  ensure(stream[offset] === 0x54, "packed stream 缺少 tracked record");
+  offset += 1;
+  let length = readLength(stream, offset, 8, "tracked length");
+  offset = length.offset;
+  const trackedDiff = stream.subarray(offset, offset + length.value);
+  offset += length.value;
+  ensure(readFileSync(diffPath).equals(trackedDiff), "tracked.diff 与 packed stream 不一致");
+  const entries = [];
+  while (offset < stream.length) {
+    ensure(stream[offset] === 0x55, "packed stream record kind 无效");
+    offset += 1;
+    length = readLength(stream, offset, 8, "path length"); offset = length.offset;
+    const rawPath = stream.subarray(offset, offset + length.value); offset += length.value;
+    length = readLength(stream, offset, 4, "mode"); offset = length.offset;
+    const mode = length.value;
+    const kind = stream[offset]; offset += 1;
+    length = readLength(stream, offset, 8, "content length"); offset = length.offset;
+    const content = stream.subarray(offset, offset + length.value); offset += length.value;
+    entries.push({ path: rawPath.toString(), path_bytes: rawPath.toString("base64"), mode, kind: kind === 0x52 ? "regular" : "symlink", content });
+  }
+  ensure(JSON.stringify(entries.map((entry) => entry.path_bytes)) === JSON.stringify(manifest.untracked_path_bytes), "manifest inventory 与 packed stream 不一致");
+  return { manifest, trackedDiff, entries };
+}

package/template/scripts/lib/profile-skill-sync.mjs

@@ -31,6 +31,8 @@ function files(directory, prefix = "") {
   if (!info.isDirectory()) fail(`技能源必须是目录: ${directory}`);
   const result = new Map();
   for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    // Match the skill supply-chain inventory: interpreter caches are not source.
+    if (entry.name === "__pycache__" || entry.name === ".DS_Store" || /\.(iml|pyc|pyo)$/.test(entry.name)) continue;
     if (entry.isSymbolicLink()) fail(`跨仓同步不接受符号链接: ${path.join(directory, entry.name)}`);
     const absolute = path.join(directory, entry.name);
     const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
@@ -103,6 +105,29 @@ function dirtyMatch(dirty, relative) {
   return [...dirty].some((entry) => entry === relative || entry.startsWith(`${relative}/`) || relative.startsWith(`${entry}/`));
 }
 
+function checkEntryReferences(profile, profileRoot, definition, changes, issues) {
+  const overlay = new Map(changes.filter((item) => item.profile === profile).map((item) => [path.resolve(profileRoot, item.path), item.content]));
+  const entries = new Set();
+  for (const relative of [".agents/skills", ...(definition.reference_roots ?? [])]) {
+    const directory = safe(profileRoot, relative, "reference root");
+    for (const name of files(directory).keys()) if (name.endsWith("/SKILL.md")) entries.add(path.join(directory, name));
+  }
+  for (const [file, content] of overlay) if (content !== null && file.endsWith("/SKILL.md")) entries.add(file);
+  for (const file of entries) {
+    const content = overlay.has(file) ? overlay.get(file) : readFileSync(file);
+    if (content === null) continue;
+    const prose = content.toString("utf8").replace(/```[\s\S]*?```/g, "").replace(/`[^`]*`/g, "");
+    for (const match of prose.matchAll(/\]\(([^\s)]+)\)/g)) {
+      const link = match[1].split("#")[0];
+      if (!link || /^[a-z][a-z\d+.-]*:/i.test(link) || link.includes("<")) continue;
+      const target = path.resolve(path.dirname(file), link);
+      const inside = target.startsWith(`${path.resolve(profileRoot)}${path.sep}`);
+      const present = inside && (overlay.has(target) ? overlay.get(target) !== null : existsSync(target));
+      if (!present) issues.push({ profile, status: "missing_reference", path: `${definition.target}/${path.relative(profileRoot, file)}`, message: `Skill 引用无法解析: ${link}` });
+    }
+  }
+}
+
 function transformedSource(root, profile, item) {
   const source = safe(root, item.source ?? `.agents/skills/${item.id}`, "source");
   const sourceFiles = files(source);
@@ -262,22 +287,38 @@ export function planProfileSkillSync({ root, config, selectedProfiles, dirtyProv
     const targetSkillRoot = safe(profileRoot, ".agents/skills", "profile skill root");
     if (existsSync(targetSkillRoot)) {
       for (const entry of readdirSync(targetSkillRoot, { withFileTypes: true })) {
-        if (!entry.isDirectory() || classified.has(entry.name)) continue;
-        const sourceSkill = path.join(canonicalRoot, entry.name);
-        if (!existsSync(sourceSkill) || !lstatSync(sourceSkill).isDirectory()) continue;
-        if (!sameTree(files(sourceSkill), files(path.join(targetSkillRoot, entry.name)))) {
+        if (!entry.isDirectory() || !existsSync(path.join(targetSkillRoot, entry.name, "SKILL.md"))) continue;
+        const classification = classified.get(entry.name);
+        if (classification === "excluded") {
+          issues.push({ profile, skill: entry.name, status: "active_excluded", path: `${definition.target}/.agents/skills/${entry.name}`, message: "活跃 Skill 不能用 excluded 跳过维护；登记 exact、adapted、local_only 或 upstream" });
+        } else if (!classification) {
           issues.push({
             profile,
             skill: entry.name,
             status: "unregistered_difference",
             path: `${definition.target}/.agents/skills/${entry.name}`,
-            message: "同名 Skill 内容不同但未登记同步分类",
+            message: "实际 Skill 入口未登记同步分类（包括内容相同及 profile 独有入口）",
           });
         }
       }
     }
 
+    // Platform packages are source directories, unlike generated shared projections.
+    // Register them using exact/adapted source and target paths; keep schema v1 readable.
+    for (const platformRoot of config.platform_roots ?? []) {
+      const directory = safe(profileRoot, platformRoot, "platform root");
+      if (!existsSync(directory)) continue;
+      for (const entry of readdirSync(directory, { withFileTypes: true })) {
+        if (!entry.isDirectory() || existsSync(path.join(targetSkillRoot, entry.name, "SKILL.md"))) continue;
+        const relative = `${platformRoot}/${entry.name}`;
+        if (![...files(path.join(directory, entry.name)).keys()].some((name) => name === "SKILL.md" || name.endsWith("/SKILL.md"))) continue;
+        const owners = [...(definition.exact ?? []), ...(definition.adapted ?? [])].filter((item) => item.target === relative);
+        if (owners.length !== 1) issues.push({ profile, skill: entry.name, status: "unregistered_platform_package", path: `${definition.target}/${relative}`, message: "平台技能包必须按完整包路径登记唯一来源" });
+      }
+    }
+
     const changedPaths = [...new Set(changes.filter((item) => item.profile === profile).map((item) => item.path))];
+    if (config.verify_entry_references) checkEntryReferences(profile, profileRoot, definition, changes, issues);
     const dirty = dirtyProvider(profileRoot, changedPaths);
     for (const change of changes.filter((item) => item.profile === profile && dirtyMatch(dirty, item.path))) {
       issues.push({ profile, skill: change.skill, status: "adaptation_conflict", path: `${definition.target}/${change.path}`, message: "目标含未提交改动" });

package/template/scripts/lib/slice-execution-preflight.mjs

@@ -0,0 +1,43 @@
+import { readSliceContract } from './slice-contract.mjs';
+import { createApprovedExecutionContext } from './approved-execution-context.mjs';
+import { evaluateContractFreshness, loadCompilerContract } from './implementation-contract-compiler.mjs';
+import { loadSkillRegistry } from './skill-registry.mjs';
+
+/** Readability, structure and execution approval are different levels of evidence. */
+export function inspectSliceContract(ref, { root = process.cwd(), approval_ref, work_unit_id } = {}) {
+  const loaded = readSliceContract(ref, { root });
+  const { contract, binding } = loaded;
+  const checks = { readable: 'passed', structure: 'passed', approval: 'not-checked', freshness: 'not-checked' };
+  const blockers = [];
+  if (loaded.raw.schema_version === 2) {
+    for (const [section, fields] of Object.entries(loadCompilerContract().slice_contract_required)) {
+      const target = section === 'root' ? contract : contract[section];
+      for (const field of fields) if (!target || !Object.hasOwn(target, field)) blockers.push(`missing:${section}.${field}`);
+    }
+    for (const section of ['common', 'resolution', 'backend']) {
+      if (!Array.isArray(contract[section]?.required_skills)) blockers.push(`invalid:${section}.required_skills`);
+    }
+    if (!Array.isArray(contract.work_units) || !contract.work_units.length) blockers.push('slice-contract-work-units-missing');
+    for (const unit of contract.work_units || []) {
+      if (unit.contract_id !== contract.contract_id) blockers.push(`work-unit-contract-id-mismatch:${unit.id}`);
+      if (unit.contract_version !== contract.contract_version) blockers.push(`work-unit-contract-version-mismatch:${unit.id}`);
+      if (!unit.work_unit?.primary_skill) blockers.push(`work-unit-primary-skill-missing:${unit.id}`);
+    }
+    if (blockers.length) checks.structure = 'failed';
+  }
+  if (approval_ref && !blockers.length) {
+    try {
+      const approved_slice = { ...binding, approval_ref };
+      const context = createApprovedExecutionContext(approved_slice, { root, contract, work_unit_id });
+      checks.approval = 'passed';
+      const current = evaluateContractFreshness(contract, { root, registry: loadSkillRegistry(), compilerContract: loadCompilerContract(), approved_slice, work_unit_id }, context);
+      checks.freshness = current.freshness === 'current' ? 'passed' : 'failed';
+      blockers.push(...current.reasons);
+    } catch (error) {
+      checks.approval = 'failed';
+      blockers.push(error.code || error.message);
+    }
+  }
+  return { ...loaded, report: { read_only: true, ...binding, checks, approval_validity: checks.approval,
+    execution_allowed: !!approval_ref && !blockers.length && checks.freshness === 'passed', blockers } };
+}

package/template/scripts/slice-contract

@@ -4,13 +4,14 @@ import path from 'node:path';
 import { prepareSliceImplementationContract, migrateSliceContractV2, persistSliceDraft } from './lib/slice-contract-preparation.mjs';
 import { renderSliceContractView, diffSliceContracts } from './lib/slice-contract-views.mjs';
 import { parseSliceYaml, readSliceContract } from './lib/slice-contract.mjs';
+import { inspectSliceContract } from './lib/slice-execution-preflight.mjs';
 
 try {
   const args=process.argv.slice(2),mode=args.shift(),options={},positional=[];
   for(let i=0;i<args.length;i++) {
     if(args[i]==='--json'){options.json=true;continue;}
     if(args[i].startsWith('--')) {
-      const key=args[i].slice(2);if(!['root','input','output','unit','before-root'].includes(key)||!args[i+1])throw new Error(`未知或缺值参数 ${args[i]}`);
+      const key=args[i].slice(2);if(!['root','input','output','unit','before-root','approval-ref'].includes(key)||!args[i+1])throw new Error(`未知或缺值参数 ${args[i]}`);
       options[key]=args[++i];
     }else positional.push(args[i]);
   }
@@ -24,7 +25,10 @@ try {
     if(result.report.blockers.length)process.exitCode=1;
   }else if(mode==='view')result=renderSliceContractView(positional[0],{root,unit_id:options.unit});
   else if(mode==='diff')result=diffSliceContracts(positional[0],positional[1],{root,beforeRoot:options['before-root']?path.resolve(options['before-root']):root});
-  else if(mode==='verify')result={read_only:true,approval_validity:'not-checked',...readSliceContract(positional[0],{root}).binding};
-  else throw new Error('用法: scripts/slice-contract prepare <ticket> --input <补充.yaml> --output <新合同.yaml> | migrate <v2.yaml> --input <补充.yaml> --output <新合同.yaml> | view <合同.yaml> [--unit <id>] | diff <旧合同> <新合同> | verify <合同> [--root <项目根>]');
+  else if(mode==='verify') {
+    result=inspectSliceContract(positional[0],{root,approval_ref:options['approval-ref'],work_unit_id:options.unit}).report;
+    if(result.blockers.length)process.exitCode=1;
+  }
+  else throw new Error('用法: scripts/slice-contract prepare <ticket> --input <补充.yaml> --output <新合同.yaml> | migrate <v2.yaml> --input <补充.yaml> --output <新合同.yaml> | view <合同.yaml> [--unit <id>] | diff <旧合同> <新合同> | verify <合同> [--root <项目根>] [--approval-ref <批准记录>] [--unit <工作单元>]');
   process.stdout.write(options.json||!result.markdown?`${JSON.stringify(result,null,2)}\n`:`${result.markdown}\n`);
 }catch(error){process.stderr.write(`${error.message}\n`);process.exitCode=1;}

package/template/scripts/verify-backend-platform-matrix

@@ -10,7 +10,7 @@ import { ScaffoldGenerator, parseArgs as dddArgs } from "../.agents/skills/yss-d
 import { generate, validateContract as validateMvcContract, parseArgs as mvcArgs } from "../.agents/skills/yss-layered-mvc-scaffold-generator/scripts/generate_scaffold.mjs";
 import { run } from "../.agents/skills/yss-ddd-scaffold-generator/scripts/run_scaffold_verification.mjs";
 
-const { values } = parseArgs({ options: { "evidence-dir": { type: "string" }, inputs: { type: "string" }, resume: { type: "boolean", default: false } }, strict: true });
+const { values } = parseArgs({ options: { "evidence-dir": { type: "string" }, inputs: { type: "string" }, resume: { type: "boolean", default: false }, "require-combination": { type: "string", multiple: true } }, strict: true });
 if (!values["evidence-dir"]) throw new Error("--evidence-dir is required; optional --inputs points to real approved contracts and candidate catalog");
 const evidence = path.resolve(values["evidence-dir"]);
 await mkdir(evidence, { recursive: true });
@@ -24,9 +24,15 @@ for (const item of input.combinations ?? []) {
   if (keys.has(key) || !catalog.profiles.some(p => p.id === item.profile_id && p.spring_boot_version === item.spring_boot_version) || !["domain-driven", "layered-mvc"].includes(item.architecture_family)) throw new Error("duplicate or unknown exact matrix combination");
   keys.add(key);
 }
+const allKeys = loadBackendPlatforms().profiles.flatMap(profile => ["domain-driven", "layered-mvc"].map(family => `${profile.id}:${profile.spring_boot_version}:${family}`));
+const requested = values["require-combination"] || input.required_combinations || allKeys;
+if (!Array.isArray(requested) || !requested.length || new Set(requested).size !== requested.length || requested.some(key => !allKeys.includes(key))) throw new Error("required combinations must be unique exact profile_id:spring_boot_version:architecture_family keys");
+const required = new Set(requested);
 const rows = [];
 for (const profile of loadBackendPlatforms().profiles) for (const family of ["domain-driven", "layered-mvc"]) {
   const row = { profile_id: profile.id, spring_boot_version: profile.spring_boot_version, java_version: profile.java_version, architecture_family: family, status: "blocked", blockers: [], commands: [], executed_at: new Date().toISOString() };
+  row.required = required.has(`${profile.id}:${profile.spring_boot_version}:${family}`);
+  if (!row.required) { row.status = "not-executed"; row.reason = "outside explicitly requested matrix"; rows.push(row); continue; }
   const configuration = input.combinations?.find(item => item.profile_id === profile.id && item.spring_boot_version === profile.spring_boot_version && item.architecture_family === family);
   for (const key of ["YSS_MAVEN_REPOSITORY_URL", "MAVEN_REPO_USERNAME", "MAVEN_REPO_PASSWORD"]) if (!process.env[key]) row.blockers.push(`missing environment: ${key}`);
   if (!configuration?.contract_ref) row.blockers.push("missing real approved scaffold contract/YSS compatibility coordinates");
@@ -63,7 +69,7 @@ for (const profile of loadBackendPlatforms().profiles) for (const family of ["do
   }
   rows.push(row);
 }
-const report = { schema_version: 1, kind: "backend-platform-matrix", generated_at: new Date().toISOString(), status: rows.every(row => row.status === "passed") ? "passed" : "blocked", combinations: rows };
+const report = { schema_version: 1, kind: "backend-platform-matrix", generated_at: new Date().toISOString(), scope: requested.length === allKeys.length ? "full-matrix" : "required-combinations", required_combinations: requested, certification_policy: "each platform and architecture still requires complete independently validated compatibility evidence", status: rows.filter(row => row.required).every(row => row.status === "passed") ? "passed" : "blocked", combinations: rows };
 await writeFile(path.join(evidence, "platform-matrix.json"), JSON.stringify(report, null, 2));
 process.stdout.write(`${report.status}: ${path.join(evidence, "platform-matrix.json")}\n`);
 if (report.status !== "passed") process.exitCode = 1;