create-yss-spec 3.4.8 → 3.4.10

package/template/scripts/lib/json-schema.mjs

@@ -1,7 +1,8 @@
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync, validationCache } from './validation-phase.mjs';
 import { spawnSync } from "node:child_process";
 import path from "node:path";
 
+const schemaCache=Symbol('schema-results');
 const validator = String.raw`
 import json
 import sys
@@ -21,8 +22,7 @@ for item in jobs:
     try:
         key = (item['schemaPath'], item['formatChecker'])
         if key not in validators:
-            with open(item['schemaPath'], encoding='utf-8') as source:
-                schema = json.load(source)
+            schema = json.loads(item['schemaText'])
             validators[key] = Draft202012Validator(schema, format_checker=FormatChecker() if key[1] else None)
         errors = list(validators[key].iter_errors(item['value']))
         if item['errorStyle'] == 'verbose':
@@ -45,10 +45,11 @@ export function validateJsonSchemas(items, { cwd = process.cwd(), timeoutMs = 30
     const effectiveSchema = path.resolve(schemaPath);
     if (!existsSync(effectiveSchema)) throw new TypeError(`缺少 ${label}: ${effectiveSchema}`);
     if (!["compact", "verbose"].includes(errorStyle)) throw new TypeError(`未知 schema errorStyle: ${errorStyle}`);
-    return { value, schemaPath: effectiveSchema, formatChecker, errorStyle };
+    return { value, schemaPath: effectiveSchema, schemaText: readFileSync(effectiveSchema, 'utf8'), formatChecker, errorStyle };
   });
   // readall waits for EOF even after the complete JSON has arrived. A known UTF-8
   // byte frame lets the validator finish when a transport keeps its write end open.
+  const run = jobs => {
   const input = Buffer.from(JSON.stringify(jobs), "utf8");
   const result = spawnSync("python3", ["-c", validator, String(input.length)], { cwd, encoding: "utf8", input, timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024 });
   if (result.error?.code === "ETIMEDOUT") throw new TypeError(`JSON_SCHEMA_TIMEOUT: schema validation exceeded ${timeoutMs}ms`);
@@ -58,6 +59,20 @@ export function validateJsonSchemas(items, { cwd = process.cwd(), timeoutMs = 30
   if (!Array.isArray(results) || results.some(item => !item || typeof item.valid !== "boolean" || typeof item.error !== "string")) throw new TypeError("JSON_SCHEMA_PROTOCOL: validator returned invalid result records");
   if (results.length !== jobs.length) throw new TypeError("schema batch 返回数量不匹配");
   return results;
+  };
+  // Batch identical jobs once and reuse only deterministic checks within this operation.
+  // External references retain the uncached path: their dependency closure is not local here.
+  const keys=jobs.map(job=>JSON.stringify([job.schemaPath,job.schemaText,job.value,job.formatChecker,job.errorStyle,path.resolve(cwd),timeoutMs]));
+  const pending=new Map(),cached=new Map();
+  for(let i=0;i<jobs.length;i++){
+    if(/"\$(?:ref|dynamicRef)"\s*:\s*"(?!#)/.test(jobs[i].schemaText)){pending.set(`${i}:${keys[i]}`,{job:jobs[i],indices:[i],cache:false});continue;}
+    const existing=validationCache(schemaCache,keys[i]);
+    if(existing!==undefined)cached.set(i,existing);
+    else {const item=pending.get(keys[i])||{job:jobs[i],indices:[],key:keys[i],cache:true};item.indices.push(i);pending.set(keys[i],item);}
+  }
+  const entries=[...pending.values()],computed=entries.length?run(entries.map(x=>x.job)):[];
+  entries.forEach((entry,index)=>{const result=computed[index];if(entry.cache&&!result.error.includes('Traceback (most recent call last)'))validationCache(schemaCache,entry.key,result);for(const i of entry.indices)cached.set(i,result);});
+  return jobs.map((_,i)=>structuredClone(cached.get(i)));
 }
 
 export function validateJsonSchema(value, schemaPath, options = {}) {

package/template/scripts/lib/lifecycle-context-query.mjs

@@ -1,3 +1,4 @@
+import { loadExecutionScope, assertScopeWorkUnit, scopedNextRoutes } from './lifecycle-execution-scope.mjs';
 import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import path from "node:path";
@@ -67,6 +68,8 @@ export function queryLifecycleContext({ mode, stageId, workUnitId, include = []
     throw new TypeError("至少提供 --mode、--stage、--work-unit 或 --include 之一");
   }
 
+  const scope = loadExecutionScope();
+  if (workUnitId) assertScopeWorkUnit(workUnitId, { readOnly: true });
   const lifecycle = validateRegistry(loadRegistry());
   const orchestration = loadYaml(ORCHESTRATION_CONTRACT_REF, "生命周期编排合同");
   const skillRegistry = loadSkillRegistry();
@@ -91,7 +94,7 @@ export function queryLifecycleContext({ mode, stageId, workUnitId, include = []
   const evidenceIds = new Set([...gates, ...checks].flatMap((gate) => gate.evidence ?? []));
   const selected = Object.fromEntries(normalizedIncludes.map((key) => [key, orchestration[key]]));
   const transition = workUnitId ? {
-    next: orchestration.transition_graph?.routes?.[workUnitId] ?? [],
+    next: scopedNextRoutes(workUnitId, orchestration.transition_graph?.routes?.[workUnitId] ?? []),
     forbidden_shortcuts: (orchestration.transition_graph?.forbidden_shortcuts ?? [])
       .filter((edge) => edge.from === workUnitId || edge.to === workUnitId),
   } : null;
@@ -129,6 +132,7 @@ export function queryLifecycleContext({ mode, stageId, workUnitId, include = []
       work_unit: workUnit,
     },
     execution: {
+      ...(scope ? { responsibility_scope: scope } : {}),
       mode: mode ? orchestration.modes[mode] : null,
       selected,
       ...(loadPlan ? { plan_checks: lifecycle.stages.find(stage => stage.id === 'stage.plan').spec_entry.required_checks.map(id => ({ id, status: 'pending', evidence_refs: [] })) } : {}),

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

@@ -1,4 +1,4 @@
-import { readFileSync } from 'node:fs';
+import { readFileSync } from './validation-phase.mjs';
 import { createHash } from 'node:crypto';
 import path from 'node:path';
 import { parseDocument } from '../vendor/yaml.mjs';

package/template/scripts/lib/lifecycle-execution-scope.mjs

@@ -0,0 +1,92 @@
+import { existsSync, readFileSync } from './validation-phase.mjs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { safe } from './strategic-handoff-io.mjs';
+import { ROOT } from './lifecycle-registry.mjs';
+import { parseDocument } from '../vendor/yaml.mjs';
+
+export const SCOPE_REF = '.yss-execution-scope.yaml';
+export const TERMINAL_REF = '.yss-backend-delivery.json';
+const read = (root, ref) => {
+  const file = safe(root, ref);
+  const doc = parseDocument(readFileSync(file, 'utf8'), { uniqueKeys: true });
+  if (doc.errors.length) throw new TypeError(doc.errors[0].message);
+  return doc.toJS({ maxAliasCount: 0 });
+};
+const check = (ok, message) => { if (!ok) throw new TypeError(`execution-scope-blocked: ${message}`); };
+
+/** The project opt-in selects a policy; callers cannot supply a replacement policy. */
+export function loadExecutionScope(root = ROOT) {
+  const marker = path.join(root, '.yss-plugin.json');
+  const plugin = existsSync(marker) ? read(root, '.yss-plugin.json') : null;
+  const file = path.join(root, SCOPE_REF);
+  if (!existsSync(file)) {
+    check(!['yss-plan-to-backend', 'yss-backend-delivery'].includes(plugin?.plugin), '插件项目缺少职责范围；迁移后才能继续');
+    return null;
+  }
+  const config = read(root, SCOPE_REF), identity = read(root, 'yss-project.yaml');
+  check(identity.schema_version === 1 && identity.repository_mode === 'project-instance', '职责范围仅适用于项目实例');
+  check(config.schema_version === 1 && config.scope_id === 'plan-to-backend'
+    && Object.keys(config).every(key => ['schema_version', 'scope_id'].includes(key)), '未知或被扩大的职责配置');
+  if (plugin) check(['yss-plan-to-backend', 'yss-backend-delivery'].includes(plugin.plugin) && plugin.execution_scope === config.scope_id, '插件与项目职责绑定不一致');
+  const contract = read(root, '.agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml');
+  const policy = contract.execution_scopes?.[config.scope_id];
+  check(policy?.terminal_work_unit === 'work-unit.backend-delivery' && Array.isArray(policy.allowed_work_units), '匹配版本的主控合同缺少职责策略');
+  return { ...policy, scope_id: config.scope_id };
+}
+
+export function verifyDeliveryTerminal(root = ROOT) {
+  check(existsSync(path.join(root, TERMINAL_REF)), '缺少正式后端交付终点记录');
+  const result = spawnSync(process.execPath, [path.join(root, 'scripts/complete-backend-delivery'), 'verify', '--root', root], {
+    cwd: root, encoding: 'utf8', input: '', timeout: 120000, maxBuffer: 8 * 1024 * 1024,
+    env: { ...process.env, NODE_OPTIONS: '', NODE_PATH: '' },
+  });
+  check(!result.error && result.status === 0, result.error?.message || result.stderr || '后端交付终点复验失败');
+  return JSON.parse(result.stdout);
+}
+
+export function assertScopeWorkUnit(workUnit, { root = ROOT, readOnly = false } = {}) {
+  const scope = loadExecutionScope(root);
+  if (!scope) { check(workUnit !== 'work-unit.backend-delivery', '后端终点需要显式职责范围'); return null; }
+  check(scope.allowed_work_units.includes(workUnit), `职责范围不允许 ${workUnit}`);
+  if (existsSync(path.join(root, TERMINAL_REF))) {
+    verifyDeliveryTerminal(root);
+    check(readOnly, '后端交付已完成；不能恢复实现或自动发布');
+  }
+  return scope;
+}
+
+export function scopedNextRoutes(workUnit, routes, { root = ROOT } = {}) {
+  const scope = loadExecutionScope(root);
+  if (!scope) return routes.filter(id => id !== 'work-unit.backend-delivery');
+  assertScopeWorkUnit(workUnit, { root, readOnly: true });
+  if (existsSync(path.join(root, TERMINAL_REF))) return [];
+  return (scope.route_overrides[workUnit] || routes).filter(id => scope.allowed_work_units.includes(id));
+}
+
+export function assertScopeTransition(current, next, state, { root = ROOT } = {}) {
+  const scope = loadExecutionScope(root);
+  if (!scope) { check(current !== 'work-unit.backend-delivery' && next !== 'work-unit.backend-delivery', '后端终点需要显式职责范围'); return; }
+  if (current === scope.terminal_work_unit && next === null) { verifyDeliveryTerminal(root); return; }
+  assertScopeWorkUnit(current, { root });
+  if (next) assertScopeWorkUnit(next, { root });
+  check(next !== null, '不能把中间阶段声明为后端交付完成');
+  assertScopeImpacts(state, { root });
+}
+
+export function assertScopeImpacts(state, { root = ROOT } = {}) {
+  if (!loadExecutionScope(root)) return;
+  check(state?.delivery_impacts?.frontend !== true, '产品 UI 设计保留，生产前端实现必须交给下游');
+  if (state?.ui_impact === true) {
+    const deferred = state.downstream_frontend;
+    check(deferred && ['owner', 'ticket_ref', 'verification_plan', 'target_version'].every(key => typeof deferred[key] === 'string' && deferred[key].trim()), 'UI 产品须明确下游前端责任、Ticket、验证计划和目标版本');
+  }
+}
+
+export function assertScopeSlice(contract, { root = ROOT } = {}) {
+  if (!loadExecutionScope(root)) return;
+  check(contract.backend?.status === 'required' && contract.frontend?.status === 'not-applicable', '本职责仅允许后端 Slice；产品 UI 设计不能混作前端实现批准');
+  check(!(contract.common?.impacted_areas || []).some(x => ['ui', 'frontend'].includes(x)), 'Slice 仍包含生产前端实现影响');
+  const roles = (contract.work_units || []).map(unit => unit.role_id);
+  check(!roles.includes('role.frontend-engineer'), '禁止派发前端实现');
+}

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

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
-import { readFileSync, writeFileSync } from "node:fs";
+import { writeFileSync } from 'node:fs';
+import { readFileSync } from './validation-phase.mjs';
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseDocument } from "../vendor/yaml.mjs";

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

@@ -1,3 +1,5 @@
+import { assertTrackingTransition } from './stage-tracking.mjs';
+import { assertScopeTransition, assertScopeImpacts, assertScopeWorkUnit, scopedNextRoutes } from './lifecycle-execution-scope.mjs';
 // Wire capability marker: profile-local readiness rules are not interchangeable.
 export const SLICE_REPOSITORY_PREPARATION_PROTOCOL = 1;
 import { createHash } from "node:crypto";
@@ -43,7 +45,8 @@ const NEXT_ROUTES = deepFreeze({
   [TICKET_DECOMPOSITION_WORK_UNIT]: [IMPLEMENTATION_WORK_UNIT],
   [IMPLEMENTATION_WORK_UNIT]: ["work-unit.frontend-implementation-verification", "work-unit.code-review"],
   "work-unit.frontend-implementation-verification": ["work-unit.code-review"],
-  "work-unit.code-review": ["work-unit.release-and-retrospective", IMPLEMENTATION_WORK_UNIT],
+  "work-unit.code-review": ["work-unit.release-and-retrospective", IMPLEMENTATION_WORK_UNIT, "work-unit.backend-delivery"],
+  "work-unit.backend-delivery": [],
   "work-unit.release-and-retrospective": [],
 });
 
@@ -249,8 +252,15 @@ 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 { validateBackendReview(decisionState, { root: options.root || ROOT }); }
+  try { assertTrackingTransition(currentWorkUnit, nextRoute, decisionState, { root: options.root || ROOT }); }
+  catch (error) { return blockedResult(['stage-tracking-blocked'], [error.message]); }
+  try { assertScopeTransition(currentWorkUnit, nextRoute, decisionState, options); }
+  catch (error) { return blockedResult(['execution-scope-blocked'], [error.message]); }
+  if (currentWorkUnit === "work-unit.code-review" && ["work-unit.release-and-retrospective", "work-unit.backend-delivery"].includes(nextRoute)) {
+    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]); }
   }
 
@@ -259,7 +269,7 @@ export function validateNextRoute(currentWorkUnit, nextRoute, decisionState, opt
     try { enforceFrontendDelivery(decisionState, { root: options.root, phase: nextRoute === IMPLEMENTATION_WORK_UNIT ? "implementation" : "inputs" }); }
     catch (error) { return blockedResult(["frontend-delivery-blocked"], [error.message]); }
   }
-  const routes = NEXT_ROUTES[currentWorkUnit];
+  const routes = NEXT_ROUTES[currentWorkUnit] && scopedNextRoutes(currentWorkUnit, NEXT_ROUTES[currentWorkUnit], options);
   if (!routes) return blockedResult([BLOCKING_SIGNALS.invalidRoute], ["known_current_work_unit"]);
   if (nextRoute === REPOSITORY_PREPARATION_WORK_UNIT && currentWorkUnit !== "work-unit.technical-analysis") {
     return blockedResult([BLOCKING_SIGNALS.technicalAnalysisRequired], ["work-unit.technical-analysis predecessor"]);
@@ -296,6 +306,8 @@ export function validateNextRoute(currentWorkUnit, nextRoute, decisionState, opt
  * generated and verified scaffold. Unaffected roles need an explicit reason.
  */
 export function validateImplementationRepositoriesReady(state, { exists = existsSync, read = (ref) => readFileSync(ref, "utf8"), root = ROOT } = {}) {
+  try { assertScopeImpacts(state, { root }); }
+  catch (error) { return blockedResult(['execution-scope-blocked'], [error.message]); }
   const preparation = state?.implementation_repository_preparation;
   const impacts = state?.delivery_impacts;
   const signals = [];
@@ -408,6 +420,13 @@ function validateDecisionBoundary(workUnit, state, options) {
  * `exists` is injectable so external adapters can resolve their own tracker refs.
  */
 export function validateTicketFormalization(state, { exists = existsSync, read = (ref) => readFileSync(ref, "utf8"), ...decisionOptions } = {}) {
+  if ((state?.tracker_kind ?? "local-markdown") === "local-markdown" && state?.vertical_slice_ticket?.ref && isReadable(state.vertical_slice_ticket.ref, exists)) {
+    try {
+      const header = read(state.vertical_slice_ticket.ref).match(/^---\r?\n([\s\S]*?)\r?\n---/);
+      const kind = header ? parseDocument(header[1], { uniqueKeys: true }).toJS({ maxAliasCount: 0 })?.kind : null;
+      if (kind === "stage-work-item") return blockedResult(["stage-work-item-not-implementable"], ["vertical-slice-ticket required"]);
+    } catch { return blockedResult(["ticket-content-unreadable"], ["readable vertical slice content"]); }
+  }
   try { enforceFrontendDelivery(state, { root: decisionOptions.root, phase: "implementation" }); }
   catch (error) { return blockedResult(["frontend-delivery-blocked"], [error.message]); }
   const repositoryResult = validateImplementationRepositoriesReady(state, { exists, read, ...decisionOptions });
@@ -529,6 +548,8 @@ export function validateTicketFormalization(state, { exists = existsSync, read =
  * Validate the complete implementation entry seam after ready-for-agent promotion.
  */
 export function validateImplementationEntry(state, options = {}) {
+  try { assertScopeWorkUnit(IMPLEMENTATION_WORK_UNIT, options); assertScopeImpacts(state, options); }
+  catch (error) { return blockedResult(['execution-scope-blocked'], [error.message]); }
   const ticketResult = validateTicketFormalization(state, options);
   if (ticketResult.result === "blocked") return ticketResult;
   if (state?.predecessor_work_unit !== TICKET_DECOMPOSITION_WORK_UNIT) {

package/template/scripts/lib/openapi-draft-validation.mjs

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
-import { existsSync, lstatSync, readFileSync, realpathSync } from "node:fs";
+import { realpathSync } from "node:fs";
+import { existsSync, lstatSync, readFileSync } from "./validation-phase.mjs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseAllDocuments, parseDocument } from "../vendor/yaml.mjs";

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/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";

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;