create-yss-spec 3.4.9 → 3.5.0

package/template/scripts/lib/skill-registry.mjs

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync } from './validation-phase.mjs';
 import path from "node:path";
 import { parseDocument } from "../vendor/yaml.mjs";
 import { nestedSkillPaths, OBSOLETE, PROJECTION_ROOTS, ROOT, unregisteredNestedSkillPaths } from "./skill-supply-chain.mjs";
@@ -65,10 +65,17 @@ export function loadSkillRegistry(filePath = DEFAULT_REGISTRY) {
 export function resolveSkillForNewUse(registry, requestedId) {
   requireString(requestedId, "requested skill id");
   if (OBSOLETE.has(requestedId)) {
+    const replacementSkill = requestedId === "grill-me" ? "grilling" : null;
     throw new SkillLifecycleError(
       SKILL_LIFECYCLE_FAILURE_CODES.retired,
-      `${requestedId} 已硬退役；按迁移 tombstone 重新路由`,
-      { skill: requestedId, migration_ref: "docs/agents/skill-migrations.md" }
+      replacementSkill
+        ? `${requestedId} 已硬退役；请使用 ${replacementSkill}`
+        : `${requestedId} 已硬退役；按迁移 tombstone 重新路由`,
+      {
+        skill: requestedId,
+        migration_ref: "docs/agents/skill-migrations.md",
+        ...(replacementSkill ? { replacement_skill: replacementSkill } : {})
+      }
     );
   }
   const aliases = new Map((registry.skills ?? []).flatMap((skill) => (skill.aliases ?? []).map((alias) => [alias, skill.id])));

package/template/scripts/lib/skill-supply-chain.mjs

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -10,7 +10,7 @@ const LOCK_PATH = path.join(ROOT, "skills-lock.json");
 const YSS_UI_MANIFEST_PATH = path.join(SOURCE_ROOT, ".yss-skills-manifest.json");
 const STRATEGIC_DESIGN_MANIFEST_PATH = path.join(SOURCE_ROOT, ".strategic-design-skills-manifest.json");
 export const PROJECTION_ROOTS = [".codex/skills", ".cursor/skills", ".pi/skills"];
-export const OBSOLETE = new Set(["yss-antd-design", "yss-antdv-next-design", "to-" + "prd", "to-" + "issues", "design-an-interface", "qa", "request-refactor-plan", "ubiquitous-language", "edit-article", "obsidian-vault", "writing-great-skills", "code-review-process", "yss-domain-modeling", "yss-dir", "yss-duckdb", "yss-file", "yss-filerunner", "yss-db2mybatis", "yss-mail", "yss-mapper-dynamic", "yss-quality", "yss-sql-condition", "yss-sql-tpl", "yss-valuation", "yss-variable", "yss-openapi", "web-design-engineer", "web-video-presentation", "wireframe-prototype", "wizard", "git-guardrails-claude-code", "claude-handoff", "batch-grill-me", "product-design-prototype", "research", "ask-matt", "dispatching-parallel-agents", "loop-me", "migrate-to-shoehorn", "prototype-page-acceptance", "scaffold-exercises", "setup-pre-commit", "setup-ts-deep-modules", "teach", "writing-beats", "writing-fragments", "writing-shape", "yss-microapp-commit", "yss-page-module-development", "yss-dictionary", "yss-jdbc", "yss-log", "yss-taskflow", "yss-backend-scaffold-application", "yss-backend-scaffold-domain", "yss-backend-scaffold-infrastructure", "yss-backend-scaffold-web", "yss-router", "yss-source-index"]);
+export const OBSOLETE = new Set(["yss-antd-design", "yss-antdv-next-design", "to-" + "prd", "to-" + "issues", "design-an-interface", "qa", "request-refactor-plan", "ubiquitous-language", "edit-article", "obsidian-vault", "writing-great-skills", "code-review-process", "yss-domain-modeling", "yss-dir", "yss-duckdb", "yss-file", "yss-filerunner", "yss-db2mybatis", "yss-mail", "yss-mapper-dynamic", "yss-quality", "yss-sql-condition", "yss-sql-tpl", "yss-valuation", "yss-variable", "yss-openapi", "web-design-engineer", "web-video-presentation", "wireframe-prototype", "wizard", "git-guardrails-claude-code", "claude-handoff", "batch-grill-me", "grill-me", "product-design-prototype", "research", "ask-matt", "dispatching-parallel-agents", "loop-me", "migrate-to-shoehorn", "prototype-page-acceptance", "scaffold-exercises", "setup-pre-commit", "setup-ts-deep-modules", "teach", "writing-beats", "writing-fragments", "writing-shape", "yss-microapp-commit", "yss-page-module-development", "yss-dictionary", "yss-jdbc", "yss-log", "yss-taskflow", "yss-backend-scaffold-application", "yss-backend-scaffold-domain", "yss-backend-scaffold-infrastructure", "yss-backend-scaffold-web", "yss-router", "yss-source-index"]);
 for (const id of ["component-selection-imports", "page-form-module", "page-list-module", "page-skeleton", "vue3-best-practices", "yss-use-table-height", "yss-use-tree-height", "yss-components", "yss-mvc-scaffold-generator", "yss-mvc-design", "yss-mvc-data-analysis-project-initializer", "yss-backend-scaffold-parent", "yss-backend-scaffold-adapter", "yss-application-layer-reference", "yss-domain-layer-reference", "yss-infrastructure-layer-reference", "yss-web-layer-reference"]) OBSOLETE.add(id);
 export function obsoleteCanonicalResidues(names, obsolete = OBSOLETE) {
   return names.filter((name) => obsolete.has(name)).sort();
@@ -49,6 +49,21 @@ export function treeHash(directory) {
   return digest.digest("hex");
 }
 
+// treeHash is the published, normalized Skill digest. A no-op copy needs the
+// stricter filesystem comparison so modes, links and raw line endings survive.
+function projectionMatchesSource(source, target) {
+  const sourceInfo = lstatSafe(source);
+  const targetInfo = lstatSafe(target);
+  if (!sourceInfo || !targetInfo || (sourceInfo.mode & 0o7777) !== (targetInfo.mode & 0o7777)) return false;
+  if (sourceInfo.isSymbolicLink()) return targetInfo.isSymbolicLink() && readlinkSync(source) === readlinkSync(target);
+  if (sourceInfo.isFile()) return targetInfo.isFile() && readFileSync(source).equals(readFileSync(target));
+  if (!sourceInfo.isDirectory() || !targetInfo.isDirectory()) return false;
+  const sourceNames = readdirSync(source).sort();
+  const targetNames = readdirSync(target).sort();
+  return sourceNames.length === targetNames.length && sourceNames.every((name, index) =>
+    name === targetNames[index] && projectionMatchesSource(path.join(source, name), path.join(target, name)));
+}
+
 /**
  * 校验并返回 YSS UI 前端 skills 与 MCP 的上游集成合同。
  *
@@ -156,13 +171,12 @@ export function unlockedCanonicalEntries(names, allowedNames, hasSkillMd = () =>
   const allowed = new Set(allowedNames);
   return names.filter((name) => !allowed.has(name) && !OBSOLETE.has(name) && hasSkillMd(name)).sort();
 }
-export function syncSkills({ check = false } = {}) {
+export function syncSkills({ check = false, hashCache = new Map() } = {}) {
   let trackedSet;
   const tracked = ref => (trackedSet ??= trackedPaths()).has(ref);
-  const sourceHashes = new Map();
   const sourceHash = source => {
-    if (!sourceHashes.has(source)) sourceHashes.set(source, treeHash(source));
-    return sourceHashes.get(source);
+    if (!hashCache.has(source)) hashCache.set(source, treeHash(source));
+    return hashCache.get(source);
   };
   const lock = parseLock();
   const shared = sharedFromLock(lock);
@@ -192,10 +206,12 @@ export function syncSkills({ check = false } = {}) {
         else if (sourceHash(source) !== treeHash(target)) drift.push(`projection drift: ${relative(target)}`);
       } else if (info?.isSymbolicLink() && existsSync(target) && realpathSync(target) === realpathSync(source)) {
         continue;
+      } else if (info?.isDirectory() && tracked(relative(target)) && projectionMatchesSource(source, target)) {
+        continue;
       } else {
         rmSync(target, { recursive: true, force: true });
         if (!info || !tracked(relative(target))) symlinkSync(path.relative(projection, source), target, "dir");
-        else cpSync(source, target, { recursive: true, preserveTimestamps: true });
+        else cpSync(source, target, { recursive: true, preserveTimestamps: true, verbatimSymlinks: true });
       }
     }
     for (const name of OBSOLETE) {
@@ -230,11 +246,12 @@ function sourceRevisionMap(oldLock, arguments_) {
   }
   return sources;
 }
-function metadata(name, skillPath, directory, previous, canonical = false, sources = {}, upstreamRoot = null) {
+function metadata(name, skillPath, directory, previous, canonical = false, sources = {}, upstreamRoot = null, hashCache = new Map()) {
   const old = previous[name] ?? {};
   let recordedPath = old.skillPath ?? skillPath;
   if (canonical && /^\.(codex|cursor|pi)\/skills\//.test(recordedPath)) recordedPath = skillPath;
-  const result = { source: old.source ?? "project", sourceType: old.sourceType ?? "local", skillPath: recordedPath, effectiveHash: treeHash(directory) };
+  if (!hashCache.has(directory)) hashCache.set(directory, treeHash(directory));
+  const result = { source: old.source ?? "project", sourceType: old.sourceType ?? "local", skillPath: recordedPath, effectiveHash: hashCache.get(directory) };
   const sourceInfo = sources[result.source];
   if (sourceInfo?.revision) result.sourceRevision = sourceInfo.revision;
   let upstreamDirectory = null;
@@ -249,7 +266,7 @@ function metadata(name, skillPath, directory, previous, canonical = false, sourc
   }
   return result;
 }
-export function updateSkillLock(arguments_ = process.argv.slice(2)) {
+export function updateSkillLock(arguments_ = process.argv.slice(2), { hashCache = new Map() } = {}) {
   const oldLock = parseLock(); const previous = priorMetadata(oldLock); const sources = sourceRevisionMap(oldLock, arguments_); const upstreamRoot = option(arguments_, "upstream-root");
   const yssUiManifest = loadYssUiSkillManifest();
   sources[yssUiManifest.source] = { ...(sources[yssUiManifest.source] ?? {}), revision: yssUiManifest.source_revision };
@@ -269,7 +286,7 @@ export function updateSkillLock(arguments_ = process.argv.slice(2)) {
   if (unlocked.length) throw new TypeError(`发现未登记到 skills-lock.json 的已跟踪共享 skills: ${unlocked.join(", ")}\n确认新增后运行 scripts/update-skill-lock --add=<skill-name>`);
   const targets = [".agents/skills", ...PROJECTION_ROOTS];
   const shared = Object.fromEntries(sharedNames.map((name) => {
-    const item = metadata(name, `.agents/skills/${name}/SKILL.md`, path.join(SOURCE_ROOT, name), previous, true, sources, upstreamRoot);
+    const item = metadata(name, `.agents/skills/${name}/SKILL.md`, path.join(SOURCE_ROOT, name), previous, true, sources, upstreamRoot, hashCache);
     const yssUiSkill = yssUiSkills.get(name);
     if (yssUiSkill) {
       item.source = yssUiManifest.source;
@@ -300,10 +317,12 @@ export function updateSkillLock(arguments_ = process.argv.slice(2)) {
     if (!names.length) continue;
     const absentPlatform = names.filter((name) => !lstatSafe(path.join(location, name))?.isDirectory());
     if (absentPlatform.length) throw new TypeError(`锁文件声明的平台 skills 缺少内容 (${root}): ${absentPlatform.join(", ")}`);
-    platform[root] = Object.fromEntries(names.map((name) => { const item = metadata(name, `${root}/${name}/SKILL.md`, path.join(location, name), previous, false, sources, upstreamRoot); item.targets = [root]; return [name, item]; }));
+    platform[root] = Object.fromEntries(names.map((name) => { const item = metadata(name, `${root}/${name}/SKILL.md`, path.join(location, name), previous, false, sources, upstreamRoot, hashCache); item.targets = [root]; return [name, item]; }));
   }
   const manifest = { version: 3, generatedBy: "scripts/update-skill-lock", canonicalRoot: ".agents/skills", projectionRoots: PROJECTION_ROOTS, sources, skills: { shared, platform } };
   const rendered = `${JSON.stringify(manifest, null, 2)}\n`;
-  if (arguments_.includes("--check")) { if (!existsSync(LOCK_PATH) || readFileSync(LOCK_PATH, "utf8") !== rendered) throw new TypeError("skills-lock.json is stale; run scripts/update-skill-lock"); return "skills-lock.json matches distributed skills"; }
-  writeFileSync(LOCK_PATH, rendered); return `updated skills-lock.json with ${sharedNames.length} shared skills and ${Object.values(platform).reduce((sum, group) => sum + Object.keys(group).length, 0)} platform skills`;
+  const current = existsSync(LOCK_PATH) ? readFileSync(LOCK_PATH, "utf8") : null;
+  if (arguments_.includes("--check")) { if (current !== rendered) throw new TypeError("skills-lock.json is stale; run scripts/update-skill-lock"); return "skills-lock.json matches distributed skills"; }
+  if (current !== rendered) writeFileSync(LOCK_PATH, rendered);
+  return `updated skills-lock.json with ${sharedNames.length} shared skills and ${Object.values(platform).reduce((sum, group) => sum + Object.keys(group).length, 0)} platform skills`;
 }

package/template/scripts/lib/slice-contract-preparation.mjs

@@ -1,7 +1,8 @@
+import {readContractSource,contractSourceMetadata} from './contract-source.mjs';
 import {sliceRepositories} from './slice-repositories.mjs';
 import { sliceCheckApplicability } from './slice-applicability.mjs';
 import path from 'node:path';
-import fs from 'node:fs';
+import fs, {withValidationPhase} from './validation-phase.mjs';
 import { stringify } from '../vendor/yaml.mjs';
 import { safe, hash, digest, write } from './strategic-handoff-io.mjs';
 import { compileDefaultImplementationContract, digestDocument, loadCompilerContract } from './implementation-contract-compiler.mjs';
@@ -9,11 +10,7 @@ import { normalizeSliceContract, parseSliceYaml, readSliceSources, resolveSliceB
 
 const object=value=>value && typeof value==='object' && !Array.isArray(value);
 const same=(a,b)=>digest(a)===digest(b);
-function metadata(text) {
-  const front=/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text);
-  if(front)return parseSliceYaml(front[1]);
-  return (/^\s*[{[]/.test(text)||/^[A-Za-z_][\w-]*:\s/m.test(text)&&!/^#/m.test(text))?parseSliceYaml(text):{};
-}
+const metadata=contractSourceMetadata;
 function mergeFacts(left,right,path,report) {
   if(left===undefined)return structuredClone(right);
   if(right===undefined)return structuredClone(left);
@@ -43,7 +40,15 @@ function lifecycleSources(checkpoint,report) {
   return result;
 }
 /** sources select existing assets; refinements contain ONLY new slice facts, never an approved contract. */
-export function prepareSliceImplementationContract({root=process.cwd(),ticket_ref,checkpoint_ref,sources={},refinements={},approved_slice}={}) {
+export function prepareSliceImplementationContract(options={}) {
+ let result;
+ try{return withValidationPhase({root:options.root,purpose:'slice-prepare',slice_id:options.ticket_ref,readOnly:true,signal:options.signal},()=>result=prepare(options));}
+ catch(error){
+  if(!result||!['VALIDATION_INPUT_CHANGED','VALIDATION_CANCELLED'].includes(error.code))throw error;
+  result.slice_contract.status='blocked';result.report.blockers.push({code:error.code==='VALIDATION_INPUT_CHANGED'?'SLICE_INPUT_CONFLICT':error.code,field:'slice',source_ref:null,reason:`${error.message.includes('compiler-contract.yaml')?'编译规则来源冲突':'生成期间来源变化'}: ${error.message}`,responsibility:'professional-review',recovery:'重新读取当前来源并准备新草案'});return result;
+ }
+}
+function prepare({root=process.cwd(),ticket_ref,checkpoint_ref,sources={},refinements={},approved_slice}={}) {
   const started=performance.now();
   const report={read_only:true,blockers:[],sources:{},provenance:[],reason_chains:{},checks:[]};
   const snapshots=new Map();
@@ -52,6 +57,7 @@ export function prepareSliceImplementationContract({root=process.cwd(),ticket_re
   try {
     let ticketText='',ticket={},saved={};
     try {ticketText=read(ticket_ref).toString('utf8');ticket=metadata(ticketText);}catch(error){report.blockers.push({code:'SLICE_SOURCE_UNREADABLE',field:'basis.ticket',source_ref:ticket_ref,reason:error.message});}
+    if (ticket.kind === 'stage-work-item' || /\/work-items\//.test(ticket_ref || '')) report.blockers.push({code:'STAGE_WORK_ITEM_NOT_IMPLEMENTABLE',field:'basis.ticket',reason:'stage-work-item 不能作为实现 Ticket'});
     if(checkpoint_ref)try {saved=parseSliceYaml(read(checkpoint_ref));}catch(error){report.blockers.push({code:'SLICE_SOURCE_UNREADABLE',field:'checkpoint',source_ref:checkpoint_ref,reason:error.message});}
     const fromTicket=ticket.slice_implementation || {};
     const facts=mergeFacts(saved.slice_implementation || {},fromTicket,'slice',report);
@@ -73,13 +79,9 @@ export function prepareSliceImplementationContract({root=process.cwd(),ticket_re
       try {
       if(typeof value==='string' && Object.hasOwn(selected,value)) {basis[key]=value;continue;}
       const binding=typeof value==='string'?{ref:value}:value;
-      const bytes=read(binding.ref),rawDigest=hash(bytes);
-      if(binding.digest&&binding.digest!==rawDigest)throw new TypeError(`stale: 来源 ${key}`);
-      const data=metadata(bytes.toString('utf8'));
-      const sourceVersion=data.requirement_version??data.version??data.contract_version;
-      if(binding.version!==undefined&&sourceVersion!==undefined&&String(binding.version)!==String(sourceVersion))throw new TypeError(`来源版本冲突: ${key}`);
-      const version=binding.version||data.requirement_version||data.version||data.contract_version;
-      basis[key]={ref:binding.ref,digest:rawDigest,...(version?{version:String(version)}:{}),...(binding.approval_ref?{approval_ref:binding.approval_ref}:{})};
+      const source=readContractSource(binding,{root,read});
+      const rawDigest=source.binding.digest;
+      basis[key]=source.binding;
       if(seen.has(binding.ref)) {
         const previous=seen.get(binding.ref);
         if(!same(basis[key],basis[previous]))throw new TypeError(`来源绑定冲突: ${key}/${previous}`);

package/template/scripts/lib/slice-contract-views.mjs

@@ -1,4 +1,4 @@
-import fs from 'node:fs';
+import fs from './validation-phase.mjs';
 import { safe, hash, digest } from './strategic-handoff-io.mjs';
 import { selectSliceWorkUnit, readSliceContract, readSliceSources, sliceAcceptanceText, parseSliceYaml, sourceSliceContract } from './slice-contract.mjs';
 

package/template/scripts/lib/slice-contract.mjs

@@ -1,11 +1,12 @@
 import {validateExistingUiBaseline} from './existing-ui-baseline.mjs';
 import {sliceRepositories} from './slice-repositories.mjs';
 import { sliceCheckApplicability } from './slice-applicability.mjs';
-import fs from 'node:fs';
+import fs, {validationMemo} from './validation-phase.mjs';
 import path from 'node:path';
 import { parseDocument } from '../vendor/yaml.mjs';
 import { safe, hash, digest, schema } from './strategic-handoff-io.mjs';
 
+const parseCache=Symbol('slice-yaml');
 const originals = new WeakMap();
 const sourceSnapshots = new WeakMap();
 const nonempty = value => typeof value === 'string' && value.trim();
@@ -13,7 +14,8 @@ const unique = values => [...new Set(values)];
 const fail = message => { throw new TypeError(`slice-contract-invalid: ${message}`); };
 const requireThat = (ok, message) => { if (!ok) fail(message); };
 export const sourceSliceContract = value => originals.get(value) || value?.slice_contract || value;
-export function parseSliceYaml(bytes) {
+export function parseSliceYaml(bytes) {return validationMemo(parseCache,String(bytes),()=>parseSliceYamlFresh(bytes));}
+function parseSliceYamlFresh(bytes) {
   const doc = parseDocument(String(bytes), { uniqueKeys: true, intAsBigInt: true });
   requireThat(!doc.errors.length, `YAML 无效: ${doc.errors[0]?.message}`);
   const value = doc.toJS({ maxAliasCount: 0 });
@@ -99,10 +101,23 @@ export function sliceAcceptanceText(contract, sources) {
 export function normalizeSliceContract(document, options = {}) {
   const raw = sourceSliceContract(document);
   requireThat(raw && [2,3].includes(raw.schema_version), 'Slice Implementation Contract schema v1 已停止支持；需要 schema v2 或 v3');
-  if (raw.schema_version === 2) return structuredClone(raw);
+  if (raw.schema_version === 2) {
+    const ref = raw.lifecycle_refs?.ticket;
+    if (ref) {
+      requireThat(!/\/work-items\//.test(ref), 'stage-work-item 不能作为实现 Ticket');
+      const file = safe(options.root || process.cwd(), ref, { missing: true });
+      if (fs.existsSync(file)) {
+        const header = fs.readFileSync(file, 'utf8').match(/^---\r?\n([\s\S]*?)\r?\n---/);
+        requireThat(!header || parseSliceYaml(header[1])?.kind !== 'stage-work-item', 'stage-work-item 不能作为实现 Ticket');
+      }
+    }
+    return structuredClone(raw);
+  }
   schema(raw,'docs/process/schemas/slice-implementation-contract-v3.schema.json');
   const sources=readSliceSources(raw,options), refs=Object.fromEntries(Object.entries(sources).map(([key,item])=>[key,item.ref]));
   requireKeys(refs,['spec','ticket','engineering_baseline','implementation_repository','build_architecture_checklist'],'依据');
+  const ticketHeader = sources.ticket.text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  requireThat(!/\/work-items\//.test(refs.ticket) && (!ticketHeader || parseSliceYaml(ticketHeader[1])?.kind !== 'stage-work-item'), 'stage-work-item 不能作为实现 Ticket');
   if(!raw.applicability.checks)requireKeys(refs,['architecture_review'],'依据');
   else {
     requireKeys(refs,['lifecycle_registry','process_tailoring'],'适用性依据');

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

@@ -1,10 +1,14 @@
+import { withValidationPhase } from './validation-phase.mjs';
 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 } = {}) {
+export function inspectSliceContract(ref, options = {}) {
+  return withValidationPhase({root:options.root,purpose:'slice-inspect',slice_id:ref,work_unit_id:options.work_unit_id,readOnly:true,signal:options.signal},()=>inspect(ref,options));
+}
+function inspect(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' };
@@ -28,9 +32,9 @@ export function inspectSliceContract(ref, { root = process.cwd(), approval_ref,
   if (approval_ref && !blockers.length) {
     try {
       const approved_slice = { ...binding, approval_ref };
-      const context = createApprovedExecutionContext(approved_slice, { root, contract, work_unit_id });
+      const context = createApprovedExecutionContext(approved_slice, { root, contract, work_unit_id, readOnly: true });
       checks.approval = 'passed';
-      const current = evaluateContractFreshness(contract, { root, registry: loadSkillRegistry(), compilerContract: loadCompilerContract(), approved_slice, work_unit_id }, context);
+      const current = evaluateContractFreshness(contract, { root, registry: loadSkillRegistry(), compilerContract: loadCompilerContract(), approved_slice, work_unit_id, readOnly: true }, context);
       checks.freshness = current.freshness === 'current' ? 'passed' : 'failed';
       blockers.push(...current.reasons);
     } catch (error) {

package/template/scripts/lib/slice-repositories.mjs

@@ -1,4 +1,4 @@
-import fs from 'node:fs';
+import fs from './validation-phase.mjs';
 import * as lifecycle from './lifecycle-transition.mjs';
 import path from 'node:path';
 import {digest,schema} from './strategic-handoff-io.mjs';

package/template/scripts/lib/slice-task-package.mjs

@@ -1,5 +1,5 @@
 import {enforceHarnessTaskScope} from './harness-execution-scope.mjs';
-import { readFileSync } from 'node:fs';
+import { readFileSync, withValidationPhase } from './validation-phase.mjs';
 import { ROOT, hash, safe, digest } from './strategic-handoff-io.mjs';
 import { normalizeSliceContract, withinSlicePath, parseSliceYaml } from './slice-contract.mjs';
 import { createApprovedExecutionContext, assertApprovedExecutionContext } from './approved-execution-context.mjs';
@@ -14,7 +14,8 @@ function generateTaskPackageDefaults(roleId,overrides,{rolesDoc}={}) {
 }
 
 /** Compile dispatch from the approved YAML. Only runtime identity and task ID come from the caller. */
-export function compileSliceTaskPackage(binding,{root=ROOT,work_unit_id,task_id,actor_id,runtime_id,execution_state='Worker',rolesDoc,user_decisions}={}) {
+export function compileSliceTaskPackage(binding,options={}) {return withValidationPhase({root:options.root||ROOT,purpose:'slice-dispatch',slice_id:binding.ref,work_unit_id:options.work_unit_id,readOnly:false,signal:options.signal},()=>compile(binding,options));}
+function compile(binding,{root=ROOT,work_unit_id,task_id,actor_id,runtime_id,execution_state='Worker',rolesDoc,user_decisions}={}) {
   const actualRoles=parseSliceYaml(readFileSync(safe(root,'docs/agents/digital-human-roles.yaml')));
   if(rolesDoc&&digest(rolesDoc)!==digest(actualRoles))fail('调用方不能替换接收端角色能力');
   rolesDoc=actualRoles;

package/template/scripts/lib/stage-tracking-migration.mjs

@@ -0,0 +1,176 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync, unlinkSync, statSync, openSync, closeSync } from 'node:fs';
+import path from 'node:path';
+import { parseDocument, stringify } from '../vendor/yaml.mjs';
+import { TRACKER_REF, STAGE_WORK_UNITS, sha256, safeTrackingPath, readTracking, parseYaml, trackerConfig, isDesign, binding, assertStageTracking, refreshTracking } from './stage-tracking.mjs';
+
+const descriptor = (root, ref) => { const p = safeTrackingPath(root, ref); return existsSync(p) ? { digest: sha256(readFileSync(p)), mode: statSync(p).mode & 0o777 } : null; };
+const json = x => `${JSON.stringify(x, null, 2)}\n`;
+function featureFrom(ref) {
+  const match = /^docs\/\.scratch\/([a-z0-9][a-z0-9-]*)\/[^/]+\.(yaml|json)$/.exec(ref);
+  if (!match) throw new Error('tracking-checkpoint-path-invalid');
+  return match[1];
+}
+function identity(root) {
+  const value = parseYaml(readTracking(root, 'yss-project.yaml'));
+  if (value?.schema_version !== 1 || value.repository_mode !== 'project-instance') throw new Error('stage-tracking-project-instance-required');
+}
+function enabledTracker(bytes) {
+  const match = bytes.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) throw new Error('tracking-tracker-frontmatter-required');
+  const doc = parseDocument(match[1], { uniqueKeys: true });
+  doc.setIn(['tracker', 'lifecycle_tracking_version'], 1);
+  return `---\n${doc.toString()}---${bytes.slice(match[0].length)}`;
+}
+function definition(item, checkpointRef) {
+  const fields = { kind: item.kind, id: item.id, checkpoint_ref: checkpointRef };
+  return `---\n${stringify(fields)}---\n# ${item.title}\n\n负责人：${item.owner}\n\n${item.scope}\n\n## 验收\n\n${item.acceptance.map(x => `- ${x}`).join('\n')}\n\n当前进度、依赖与完成证据以 ${checkpointRef} 中的 ${item.id} 为准。\n`;
+}
+export function checkTracking(root, checkpointRef) {
+  identity(root);
+  const feature = featureFrom(checkpointRef);
+  const config = trackerConfig(root);
+  if (!existsSync(safeTrackingPath(root, checkpointRef))) return { status: 'missing-checkpoint', feature_id: feature, enabled: config.lifecycle_tracking_version === 1 };
+  const checkpoint = parseYaml(readTracking(root, checkpointRef));
+  try {
+    const result = assertStageTracking(checkpoint, { root, checkpointRef });
+    return { ...result, feature_id: checkpoint.feature_id || feature, enabled: config.lifecycle_tracking_version === 1, migration_required: !checkpoint.stage_tracking };
+  } catch (error) { return { status: 'blocked', feature_id: feature, enabled: config.lifecycle_tracking_version === 1, error: error.message, migration_required: !checkpoint.stage_tracking }; }
+}
+export function planTracking(root, { checkpoint_ref, items = [], refresh = false } = {}) {
+  root = path.resolve(root); identity(root);
+  const feature = featureFrom(checkpoint_ref);
+  trackerConfig(root);
+  const changes = [], observed = {}, gaps = [];
+  function watch(ref) { observed[ref] = descriptor(root, ref); }
+  function change(ref, after) {
+    watch(ref);
+    if (!observed[ref] || sha256(after) !== observed[ref].digest) changes.push({ ref, before: observed[ref], after, after_digest: sha256(after) });
+  }
+  for (const ref of ['yss-project.yaml', 'CONTEXT.md', TRACKER_REF, 'docs/process/lifecycle-registry.yaml', 'docs/process/schemas/stage-tracking.schema.json', 'docs/process/harness-profile.yaml', checkpoint_ref]) watch(ref);
+  const exists = observed[checkpoint_ref] !== null;
+  let checkpoint;
+  if (exists) checkpoint = parseYaml(readTracking(root, checkpoint_ref));
+  else {
+    const template = 'docs/process/templates/lifecycle-checkpoint-template.yaml'; watch(template);
+    checkpoint = parseYaml(readTracking(root, template));
+    checkpoint.feature_id = feature;
+    checkpoint.mode = 'orchestrate'; checkpoint.status = 'running';
+    checkpoint.stage = items[0]?.stage || 'stage.plan';
+    checkpoint.next_work_unit = items[0]?.work_unit || 'work-unit.plan-requirements';
+  }
+  checkpoint.feature_id ??= feature;
+  const design = isDesign(root);
+  checkpoint.stage_tracking ??= { schema_version: 1, feature_id: checkpoint.feature_id, checkpoint_ref, entry_stage: checkpoint.stage,
+    entry: { kind: design ? 'checkpoint' : 'parent-ticket', ref: design ? checkpoint_ref : `docs/.scratch/${feature}/parent-ticket.md` }, items: [] };
+  if (refresh) checkpoint = refreshTracking(root, checkpoint).checkpoint;
+  const tracking = checkpoint.stage_tracking;
+  const ids = new Set(tracking.items.map(x => x.id));
+  for (const seed of items) {
+    if (ids.has(seed.id)) {
+      // Resume never overwrites a live item with an older task definition.
+      const existing = tracking.items.find(x => x.id === seed.id);
+      for (const key of ['title', 'owner', 'scope', 'stage', 'work_unit', 'acceptance', 'dependencies', 'split_reasons']) if (JSON.stringify(seed[key] ?? existing[key]) !== JSON.stringify(existing[key])) throw new Error(`tracking-existing-item-conflict: ${seed.id}.${key}`);
+      continue;
+    }
+    if (seed.progress && seed.progress !== 'pending') throw new Error('tracking-migration-cannot-infer-completion');
+    const item = { id: seed.id, kind: 'stage-work-item', title: seed.title, stage: seed.stage, work_unit: seed.work_unit, owner: seed.owner, scope: seed.scope,
+      acceptance: seed.acceptance, dependencies: seed.dependencies || [], source_refs: (seed.source_refs || []).map(ref => binding(root, typeof ref === 'string' ? ref : ref.ref)),
+      progress: 'pending', split_reasons: seed.split_reasons || [], completion: [] };
+    if (seed.deferred) { item.deferred = seed.deferred; if (!item.split_reasons.includes('cross-stage-deferral')) item.split_reasons.push('cross-stage-deferral'); }
+    tracking.items.push(item); ids.add(item.id);
+  }
+  for (const item of tracking.items) {
+    if (tracking.items.some(other => other.dependencies.includes(item.id)) && !item.split_reasons.includes('blocks-other-work')) item.split_reasons.push('blocks-other-work');
+    if (tracking.items[0]?.owner && item.owner !== tracking.items[0].owner && !item.split_reasons.includes('different-owner')) item.split_reasons.push('different-owner');
+  }
+  if (!tracking.items.length) gaps.push('需要明确当前阶段工作项及负责人、范围和验收条件；不从历史文件推断完成');
+  if (!tracking.items.some(i => i.stage === checkpoint.stage) && ['stage.plan', 'stage.spec-architecture', 'stage.product-design'].includes(checkpoint.stage)) gaps.push('当前阶段缺少工作项');
+  for (const item of tracking.items) {
+    for (const key of ['id', 'title', 'owner', 'scope', 'stage', 'work_unit']) if (typeof item[key] !== 'string' || !item[key].trim()) gaps.push(`${item.id || '?'} 缺少 ${key}`);
+    if (!item.acceptance?.length) gaps.push(`${item.id || '?'} 缺少验收条件`);
+    for (const source of [...item.source_refs, ...item.completion.flatMap(x => x.evidence_refs)]) watch(source.ref);
+    if (item.deferred) watch(item.deferred.decision_ref);
+    if (item.split_reasons?.length && !gaps.length) {
+      const ref = `docs/.scratch/${feature}/work-items/${item.id}.md`;
+      if (!item.definition_ref) {
+        if (descriptor(root, ref)) throw new Error(`tracking-unowned-file-conflict: ${ref}`);
+        item.definition_ref = ref;
+        const content = definition(item, checkpoint_ref);
+        item.definition_digest = sha256(content); change(ref, content);
+      } else watch(item.definition_ref);
+    }
+  }
+  const entryRef = tracking.entry.ref;
+  if (!design) {
+    watch(entryRef);
+    const link = `\n阶段工作进度与证据：${checkpoint_ref}\n`;
+    if (!observed[entryRef]) change(entryRef, `# ${feature}\n\nStatus: needs-triage\n${link}${trackerConfig(root).platform !== 'local-markdown' ? `\npublication: pending\npending_publication_to: ${trackerConfig(root).platform}\n` : ''}`);
+    else if (!readTracking(root, entryRef).includes(checkpoint_ref)) change(entryRef, readTracking(root, entryRef) + link);
+  }
+  const mapRef = `docs/.scratch/${feature}/map.md`; watch(mapRef);
+  if (!observed[mapRef]) change(mapRef, `---\ncheckpoint_ref: ${checkpoint_ref}\n---\n# ${feature}\n\n阶段工作与证据见 ${checkpoint_ref}。\n`);
+  else if (!readTracking(root, mapRef).includes(checkpoint_ref)) change(mapRef, readTracking(root, mapRef) + `\n阶段工作与证据：${checkpoint_ref}\n`);
+  change(checkpoint_ref, checkpoint_ref.endsWith('.json') ? json(checkpoint) : stringify(checkpoint));
+  change(TRACKER_REF, enabledTracker(readTracking(root, TRACKER_REF)));
+  const input = { checkpoint_ref, items, refresh };
+  const payload = { schema_version: 1, root, input, gaps, observed, changes };
+  return { ...payload, plan_id: sha256(JSON.stringify(payload)).slice(7) };
+}
+export function applyTracking(root, plan, { afterWrite } = {}) {
+  root = path.resolve(root); identity(root);
+  if (plan.root !== root || plan.schema_version !== 1 || !/^[a-f0-9]{64}$/.test(plan.plan_id)) throw new Error('tracking-plan-identity-invalid');
+  const { plan_id, ...payload } = plan;
+  if (sha256(JSON.stringify(payload)).slice(7) !== plan_id) throw new Error('tracking-plan-digest-mismatch');
+  const feature = featureFrom(plan.input.checkpoint_ref);
+  const transactionRef = `docs/.scratch/${feature}/verification/stage-tracking-migrations/${plan_id}`;
+  const receiptRef = `${transactionRef}/receipt.json`;
+  if (existsSync(safeTrackingPath(root, receiptRef))) {
+    const receipt = JSON.parse(readTracking(root, receiptRef));
+    if (receipt.plan_id !== plan_id) throw new Error('tracking-receipt-conflict');
+    return { status: 'unchanged', plan_id, receipt_ref: receiptRef };
+  }
+  if (plan.gaps.length) throw new Error(`tracking-migration-needs-info: ${plan.gaps.join('; ')}`);
+  const fresh = planTracking(root, plan.input);
+  if (JSON.stringify(fresh) !== JSON.stringify(plan)) throw new Error('tracking-plan-stale');
+  if (!plan.changes.length) return { status: 'unchanged', plan_id };
+  const transactionPath = safeTrackingPath(root, transactionRef);
+  if (existsSync(transactionPath)) throw new Error(`tracking-transaction-needs-recovery: ${transactionRef}`);
+  mkdirSync(transactionPath, { recursive: true });
+  const backups = plan.changes.map(c => ({ ref: c.ref, before: c.before, bytes: c.before ? readFileSync(safeTrackingPath(root, c.ref)).toString('base64') : null }));
+  writeFileSync(path.join(transactionPath, 'backup.json'), json(backups), { flag: 'wx' });
+  writeFileSync(path.join(transactionPath, 'plan.json'), json(plan), { flag: 'wx' });
+  const written = [], temporary = new Set();
+  try {
+    for (const [ref, before] of Object.entries(plan.observed)) if (JSON.stringify(descriptor(root, ref)) !== JSON.stringify(before)) throw new Error('tracking-concurrent-change');
+    for (const change of plan.changes) {
+      const file = safeTrackingPath(root, change.ref);
+      if (JSON.stringify(descriptor(root, change.ref)) !== JSON.stringify(change.before)) throw new Error('tracking-concurrent-change');
+      mkdirSync(path.dirname(file), { recursive: true });
+      const temp = `${file}.stage-tracking-${plan_id}`;
+      const fd = openSync(temp, 'wx', change.before?.mode || 0o644);
+      temporary.add(temp);
+      try { writeFileSync(fd, change.after); } finally { closeSync(fd); }
+      renameSync(temp, file); temporary.delete(temp); written.push(change);
+      afterWrite?.(change, written.length);
+    }
+    for (const [ref, before] of Object.entries(plan.observed)) {
+      const changed = written.find(x => x.ref === ref);
+      const actual = descriptor(root, ref);
+      if (changed ? actual?.digest !== changed.after_digest : JSON.stringify(actual) !== JSON.stringify(before)) throw new Error('tracking-concurrent-change');
+    }
+    const cp = parseYaml(readTracking(root, plan.input.checkpoint_ref));
+    assertStageTracking(cp, { root, checkpointRef: plan.input.checkpoint_ref });
+    writeFileSync(safeTrackingPath(root, receiptRef), json({ plan_id, status: 'applied', changed_refs: written.map(x => x.ref) }), { flag: 'wx' });
+    return { status: 'applied', plan_id, receipt_ref: receiptRef, changed_refs: written.map(x => x.ref) };
+  } catch (error) {
+    const conflicts = [];
+    for (const temp of temporary) { try { unlinkSync(temp); } catch (cleanupError) { if (cleanupError.code !== 'ENOENT') conflicts.push(temp); } }
+    for (const change of written.reverse()) {
+      if (descriptor(root, change.ref)?.digest !== change.after_digest) { conflicts.push(change.ref); continue; }
+      const backup = backups.find(x => x.ref === change.ref), file = safeTrackingPath(root, change.ref);
+      if (backup.bytes === null) unlinkSync(file); else writeFileSync(file, Buffer.from(backup.bytes, 'base64'), { mode: backup.before.mode });
+    }
+    writeFileSync(path.join(transactionPath, 'failure.json'), json({ error: error.message, recovery_conflicts: conflicts }));
+    throw new Error(`${error.message}; tracking-rollback-${conflicts.length ? `conflict:${conflicts.join(',')}` : 'complete'}`);
+  }
+}