create-yss-spec 3.5.2 → 3.5.4

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

@@ -0,0 +1,150 @@
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import { StringDecoder } from 'node:string_decoder';
+import { parseDocument } from '../vendor/yaml.mjs';
+
+const digest = (value) => createHash('sha256').update(value).digest('hex');
+
+// Hash the complete resource tree, including executable bits. Never follow an
+// escaping resource link or a cycle; an incomplete digest cannot establish equality.
+export function resourceIdentity(directory) {
+  const root = realpathSync(directory), files = [], active = new Set();
+  function walk(file, relative) {
+    const real = realpathSync(file);
+    if (real !== root && !real.startsWith(root + path.sep)) throw new Error(`resource link escapes skill: ${relative}`);
+    if (active.has(real)) throw new Error(`resource cycle: ${relative}`);
+    const stat = lstatSync(real);
+    if (stat.isDirectory()) {
+      active.add(real);
+      for (const name of readdirSync(real).sort()) {
+        if (['.DS_Store', '__pycache__', '.git'].includes(name)) continue;
+        walk(path.join(real, name), relative ? `${relative}/${name}` : name);
+      }
+      active.delete(real);
+    } else if (stat.isFile()) files.push({ path: relative, executable: Boolean(stat.mode & 0o111), sha256: digest(readFileSync(real)) });
+    else throw new Error(`unsupported resource: ${relative}`);
+  }
+  walk(root, '');
+  return { sha256: digest(JSON.stringify(files)), files };
+}
+
+function yaml(source) {
+  const doc = parseDocument(source, { uniqueKeys: true, maxAliasCount: 0 });
+  if (doc.errors.length) throw new Error(doc.errors[0].message);
+  return doc.toJS({ maxAliasCount: 0 });
+}
+
+export function inspectSkill(file) {
+  try {
+    const source = readFileSync(file, 'utf8');
+    const match = source.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+    if (!match) throw new Error('missing frontmatter');
+    const header = yaml(match[1]);
+    if (!header || typeof header.name !== 'string') throw new Error('missing name');
+    const metadataPath = path.join(path.dirname(file), 'agents/openai.yaml');
+    const metadata = existsSync(metadataPath) ? yaml(readFileSync(metadataPath, 'utf8')) : {};
+    return { name: header.name, path: path.resolve(file), real_path: realpathSync(file), resource: resourceIdentity(path.dirname(file)),
+      declared_policy: { codex_allow_implicit_invocation: metadata?.policy?.allow_implicit_invocation ?? null, disable_model_invocation: header['disable-model-invocation'] ?? null }, status: 'observed-filesystem' };
+  } catch (error) { return { path: path.resolve(file), status: 'unknown', reason: error.message }; }
+}
+
+export function assessDiscovery({ registered, observation, required = [], selections = [], expected }) {
+  const findings = [];
+  const bound = observation.runtime === expected.runtime && observation.version === expected.version && observation.cwd === expected.cwd;
+  if (!bound) findings.push({ severity: 'block', code: 'observation-binding-mismatch' });
+  const entries = bound && observation.status === 'observed' ? observation.entries : [];
+  for (const name of required) {
+    if (!registered.some((item) => item.name === name)) findings.push({ name, severity: 'block', code: 'required-skill-unregistered' });
+    if (observation.status !== 'observed') findings.push({ name, severity: 'block', code: 'required-catalog-unknown' });
+  }
+  for (const selection of selections) {
+    if (!registered.some((item) => item.name === selection.name)) findings.push({ name: selection.name, severity: 'block', code: 'selected-skill-unregistered' });
+  }
+  for (const wanted of registered) {
+    const matches = entries.filter((entry) => entry.name === wanted.name && entry.enabled !== false);
+    const identities = matches.map((entry) => ({ entry, identity: inspectSkill(entry.path) }));
+    if (identities.length > 1) findings.push({ name: wanted.name, severity: 'warning', code: identities.every(({ identity }) => identity.resource?.sha256 && identity.resource.sha256 === wanted.resource?.sha256) ? 'equivalent-resource-duplicates' : 'catalog-source-conflict', scope: 'resource bytes only; dependency and effective-policy equality are not established' });
+    const selected = selections.filter((entry) => entry.name === wanted.name);
+    if (!required.includes(wanted.name) && !selected.length) continue;
+    if (!selected.length) { findings.push({ name: wanted.name, severity: 'block', code: 'required-selection-unknown' }); continue; }
+    for (const selection of selected) {
+      // Selection must be supplied by a trace with the same host, version and cwd.
+      if (!bound || selection.runtime !== expected.runtime || selection.version !== expected.version || selection.cwd !== expected.cwd || !selection.evidence) {
+        findings.push({ name: wanted.name, severity: 'block', code: 'selection-binding-mismatch' }); continue;
+      }
+      const actual = inspectSkill(selection.path);
+      if (!actual.resource?.sha256 || actual.resource.sha256 !== wanted.resource?.sha256) findings.push({ name: wanted.name, severity: 'block', code: 'selected-unregistered-source' });
+      else if (selection.dependency_digest !== wanted.dependency_digest || !wanted.dependency_digest || selection.effective_policy_digest !== wanted.effective_policy_digest || !wanted.effective_policy_digest) findings.push({ name: wanted.name, severity: 'block', code: 'effective-environment-unknown-or-different' });
+    }
+  }
+  return { status: findings.some((item) => item.severity === 'block') ? 'blocked' : (bound && observation.status === 'observed' ? 'catalog-observed-only' : 'unknown'), findings };
+}
+
+export async function codexCatalog(binary, cwd, timeout = 30000) {
+  return new Promise((resolve, reject) => {
+    const process = spawn(binary, ['app-server', '--stdio'], { cwd, stdio: ['pipe', 'pipe', 'pipe'] });
+    let buffer = '', bytes = 0, settled = false;
+    const decoder = new StringDecoder('utf8');
+    const finish = (error, result) => {
+      if (settled) return;
+      settled = true; clearTimeout(timer); process.kill('SIGTERM');
+      const kill = setTimeout(() => process.kill('SIGKILL'), 1000); kill.unref();
+      error ? reject(error) : resolve(result);
+    };
+    const timer = setTimeout(() => finish(new Error('skills/list timed out')), timeout);
+    const send = (value) => process.stdin.write(JSON.stringify(value) + '\n');
+    process.on('error', (error) => finish(error));
+    process.stdin.on('error', (error) => finish(error));
+    process.on('close', () => finish(new Error('app-server exited before skills/list')));
+    process.stderr.on('data', () => {}); // No user config, credentials or diagnostics dumped.
+    process.stdout.on('data', (chunk) => {
+      bytes += chunk.length;
+      if (bytes > 16 * 1024 * 1024) return finish(new Error('skills/list response exceeds limit'));
+      buffer += decoder.write(chunk);
+      let index;
+      while ((index = buffer.indexOf('\n')) >= 0) {
+        const line = buffer.slice(0, index); buffer = buffer.slice(index + 1);
+        if (!line.trim()) continue;
+        try {
+          const event = JSON.parse(line);
+          if (event.id === 1) {
+            if (event.error) throw new Error('app-server initialization rejected');
+            send({ method: 'initialized', params: {} });
+            send({ id: 2, method: 'skills/list', params: { cwds: [cwd], forceReload: true } });
+          }
+          if (event.id === 2) {
+            const row = event.result?.data?.find((item) => item.cwd === cwd);
+            if (!row || !Array.isArray(row.skills) || !Array.isArray(row.errors)) throw new Error('invalid skills/list response');
+            if (row.skills.some((item) => typeof item.name !== 'string' || typeof item.path !== 'string' || !path.isAbsolute(item.path))) throw new Error('invalid skill identity');
+            finish(null, { entries: row.skills.map((item) => ({ name: item.name, path: item.path, enabled: item.enabled, scope: item.scope, effective_policy: 'unknown' })), errors: row.errors, method: 'codex-app-server/skills-list', scope: 'configured catalog; selection and truncation unknown' });
+          }
+        } catch (error) { finish(error); }
+      }
+    });
+    send({ id: 1, method: 'initialize', params: { clientInfo: { name: 'yss-skill-discovery', version: '1' }, capabilities: { experimentalApi: true } } });
+  });
+}
+
+export async function observeRuntime({ runtime, binary, cwd, piLoader, piAgentDir }) {
+  cwd = path.resolve(cwd);
+  const result = spawnSync(binary, ['--version'], { encoding: 'utf8', timeout: 10000, maxBuffer: 1024 * 1024 });
+  const version = result.status === 0 ? result.stdout.trim() : null;
+  const base = { runtime, version, cwd, observed_at: new Date().toISOString(), entries: [], status: 'unknown', selection: 'unknown', truncation: 'unknown', configuration: 'not-inspected' };
+  if (!version) return { ...base, reason: 'runtime-version-unavailable' };
+  try {
+    if (runtime === 'codex') return { ...base, ...await codexCatalog(binary, cwd), status: 'observed', configuration: 'current host configuration used by app-server' };
+    if (runtime === 'pi') {
+      if (!piLoader || !piAgentDir) throw new Error('Pi requires its installed core/skills.js and explicit agent directory');
+      // Use the installed loader without package resolution, extension execution or writes.
+      const probe = "import {pathToFileURL} from 'node:url'; const {loadSkills}=await import(pathToFileURL(process.argv[1]).href); process.stdout.write(JSON.stringify(loadSkills(JSON.parse(process.argv[2]))));";
+      const loaded = spawnSync(process.execPath, ['--input-type=module', '-e', probe, path.resolve(piLoader), JSON.stringify({ cwd, agentDir: path.resolve(piAgentDir), skillPaths: [], includeDefaults: true })], { encoding: 'utf8', timeout: 30000, maxBuffer: 16 * 1024 * 1024 });
+      if (loaded.status !== 0) throw new Error('Pi loader failed or exceeded its observation limit');
+      const found = JSON.parse(loaded.stdout);
+      return { ...base, status: 'observed', method: 'installed-pi-core/loadSkills', scope: 'default directories only; configured packages/extensions and CLI session unknown', loader_sha256: digest(readFileSync(piLoader)), entries: found.skills.map((item) => ({ name: item.name, path: item.filePath, enabled: true, scope: item.source, effective_policy: { allow_implicit: !item.disableModelInvocation, provenance: 'observed-loader' } })), errors: found.diagnostics };
+    }
+    if (runtime === 'cursor') return { ...base, reason: 'No read-only catalog API verified; use a version-bound actual invocation trace for required skills' };
+    throw new Error('unsupported runtime');
+  } catch (error) { return { ...base, reason: error.message }; }
+}

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

@@ -65,7 +65,8 @@ 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;
+    const lifecycleOwner = ["harness-orchestrator", "yss-strategic-design", "yss-product-lifecycle"].find(id => registry.skills?.some(skill => skill.id === id));
+    const replacementSkill = ({ "grill-me": "grilling", "wait-what": "i-have-adhd", "grill-with-docs": lifecycleOwner, "to-questionnaire": lifecycleOwner, "improve-codebase-architecture": "codebase-design" })[requestedId] ?? null;
     throw new SkillLifecycleError(
       SKILL_LIFECYCLE_FAILURE_CODES.retired,
       replacementSkill
@@ -155,6 +156,9 @@ function sameStringSet(left, right) {
 function validateInvocationContract(registry, skill) {
   const contract = registry.invocation_contract;
   requireObject(contract, "invocation_contract");
+  if (contract.runtime_metadata_version !== undefined && contract.runtime_metadata_version !== 1) {
+    fail('invocation_contract.runtime_metadata_version 必须为 1；省略时保持历史声明校验');
+  }
   if (contract.schema_version !== 2) fail("invocation_contract.schema_version 必须为 2；v1 已停止支持");
   if (contract.scope !== "discovery-only") fail("invocation_contract.scope 必须限定为 discovery-only");
   requireStringArray(contract.required_fields, "invocation_contract.required_fields", { nonEmpty: true });
@@ -204,6 +208,38 @@ function validateInvocationContract(registry, skill) {
   }
 }
 
+function validateInvocationMetadata(registry, skill, source, skillMd) {
+  // Opt in through the registry so existing instances keep their declared contract.
+  if (registry.invocation_contract.runtime_metadata_version !== 1) return;
+  let metadata = {};
+  if (source !== null && source !== undefined) {
+    const document = parseDocument(source, { maxAliasCount: 0, uniqueKeys: true });
+    if (document.errors.length) fail(`${skill.id} 的 agents/openai.yaml 无效: ${document.errors[0].message}`);
+    metadata = document.toJS({ maxAliasCount: 0 });
+    requireObject(metadata, `${skill.id}.agents/openai.yaml`);
+  }
+  if (metadata.policy !== undefined) requireObject(metadata.policy, `${skill.id}.policy`);
+  const declared = metadata.policy?.allow_implicit_invocation;
+  if (declared !== undefined && typeof declared !== 'boolean') {
+    fail(`${skill.id}.allow_implicit_invocation 必须为布尔值`);
+  }
+  const expected = effectiveInvocationContract(registry, skill).invocation_mode !== 'user';
+  if (skillMd !== undefined) {
+    const match = skillMd.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+    if (!match) fail(`${skill.id} 的 SKILL.md 缺少 frontmatter`);
+    const document = parseDocument(match[1], { maxAliasCount: 0, uniqueKeys: true });
+    if (document.errors.length) fail(`${skill.id} 的 frontmatter 无效`);
+    const header = document.toJS({ maxAliasCount: 0 });
+    requireObject(header, `${skill.id}.frontmatter`);
+    const disabled = header['disable-model-invocation'];
+    if (disabled !== undefined && typeof disabled !== 'boolean') fail(`${skill.id}.disable-model-invocation 必须为布尔值`);
+    if ((disabled ?? false) === expected) fail(`${skill.id}.disable-model-invocation 与注册表调用意图不一致`);
+  }
+  if ((declared ?? true) !== expected) {
+    fail(`${skill.id}.allow_implicit_invocation 与注册表调用意图不一致，应为 ${expected}`);
+  }
+}
+
 function requireStringSet(value, expected, field) {
   if (!Array.isArray(value)) fail(`${field} 必须是数组`);
   const missing = expected.filter((item) => !value.includes(item));
@@ -295,7 +331,7 @@ function validateCodeReviewRoute(route, resolve) {
   validateFindingDisposition(standards.finding_disposition);
 }
 
-export function validateSkillRegistry(registry, { lock, compilerContract, lifecycleContract, skillSource, externalSkillSource, nestedSkillSources, backendPlatforms } = {}) {
+export function validateSkillRegistry(registry, { lock, compilerContract, lifecycleContract, skillSource, skillMetadata, externalSkillSource, nestedSkillSources, backendPlatforms } = {}) {
   if (!registry || typeof registry !== "object" || Array.isArray(registry)) fail("技能路由注册表必须是对象");
   if (registry.schema_version !== 3) fail("schema_version 必须为 3；v1/v2 已停止支持，请迁移 provider 与两阶段退役合同");
   if (registry.registry_id !== "yss.skill-routing") fail("registry_id 必须为 yss.skill-routing");
@@ -365,6 +401,7 @@ export function validateSkillRegistry(registry, { lock, compilerContract, lifecy
       fail(`${skill.id} impacts 不能为空`);
     }
     validateInvocationContract(registry, skill);
+    if (skillMetadata) validateInvocationMetadata(registry, skill, skillMetadata(skill.id), skillSource?.(skill.id));
   }
   for (const skill of skills) {
     if (skill.maturity === "deprecated") {
@@ -700,6 +737,10 @@ export function validateDefaultSkillRegistry() {
     compilerContract,
     lifecycleContract: yamlFromFile(LIFECYCLE_CONTRACT, "生命周期编排合同"),
     skillSource: (id) => readFileSync(path.join(ROOT, ".agents/skills", id, "SKILL.md"), "utf8"),
+    skillMetadata: (id) => {
+      const file = path.join(ROOT, '.agents/skills', id, 'agents/openai.yaml');
+      return existsSync(file) ? readFileSync(file, 'utf8') : null;
+    },
     externalSkillSource: (source) => readFileSync(path.join(ROOT, source), "utf8"),
     nestedSkillSources: nestedSkillPaths().map((source) => `.agents/skills/${source}`)
   });

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

@@ -12,6 +12,10 @@ const STRATEGIC_DESIGN_MANIFEST_PATH = path.join(SOURCE_ROOT, ".strategic-design
 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", "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);
+OBSOLETE.add("grill-with-docs");
+OBSOLETE.add("to-questionnaire");
+OBSOLETE.add("improve-codebase-architecture");
+OBSOLETE.add("wait-what");
 export function obsoleteCanonicalResidues(names, obsolete = OBSOLETE) {
   return names.filter((name) => obsolete.has(name)).sort();
 }
@@ -144,7 +148,7 @@ function loadStrategicDesignSkillManifest() {
 }
 function git(args) { return spawnSync("git", args, { cwd: ROOT, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }); }
 function trackedPaths() {
-  const result = git(["ls-files", "-z"]);
+  const result = git(["ls-files", "-z", "--", ...PROJECTION_ROOTS]);
   if (result.status !== 0) throw new TypeError("无法读取 Git 受跟踪路径");
   const paths = new Set();
   for (const file of result.stdout.split("\0").filter(Boolean)) {

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

@@ -1,3 +1,4 @@
+import { assertImplementationTicket, assertSliceBusinessSources } from './business-tickets.mjs';
 import {readContractSource,contractSourceMetadata} from './contract-source.mjs';
 import {sliceRepositories} from './slice-repositories.mjs';
 import { sliceCheckApplicability } from './slice-applicability.mjs';
@@ -57,6 +58,7 @@ function prepare({root=process.cwd(),ticket_ref,checkpoint_ref,sources={},refine
   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});}
+    try { assertImplementationTicket(ticketText,ticket_ref); } catch(error) { report.blockers.push({code:'TICKET_NOT_IMPLEMENTABLE',field:'basis.ticket',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 || {};
@@ -72,6 +74,7 @@ function prepare({root=process.cwd(),ticket_ref,checkpoint_ref,sources={},refine
     const selected=mergeFacts(lifecycleSources(saved,report),mergeFacts(input.sources || {},sources,'sources',report),'sources',report);
     if(selected.ticket && (typeof selected.ticket==='string'?selected.ticket:selected.ticket.ref)!==ticket_ref)throw new TypeError('Ticket 来源冲突');
     selected.ticket=selected.ticket || {ref:ticket_ref};
+    if (ticket.business_ticket_set_ref) selected.business_ticket_set ??= {ref:ticket.business_ticket_set_ref};
     if(input.scope?.risk_level){selected.lifecycle_registry??={ref:'.template-spec/process/lifecycle-registry.yaml'};selected.process_tailoring??={ref:'.template-spec/process/harness-process-tailoring.md'};}
     if(!selected.context&&fs.existsSync(safe(root,'CONTEXT.md',{missing:true})))selected.context={ref:'CONTEXT.md'};
     const basis={},seen=new Map();
@@ -94,6 +97,7 @@ function prepare({root=process.cwd(),ticket_ref,checkpoint_ref,sources={},refine
     for(const key of ['spec','ticket','engineering_baseline','implementation_repository','build_architecture_checklist',...extraRequired,...(!input.scope?.risk_level?['architecture_review']:[])])if(!selected[key])report.blockers.push({code:'SLICE_SOURCE_MISSING',field:`basis.${key}`,reason:'缺少必要来源',responsibility:'agent',recovery:'绑定已有当前资产；不能用空文档替代'});
     contract.basis=basis;
     if(report.blockers.length){report.checks.push({check:'dependent-compilation',result:'not-executed',reason:'来源或输入存在独立阻断'});throw Object.assign(new Error('依赖未就绪'),{code:'SLICE_DEPENDENCIES_UNAVAILABLE'});}
+    try { assertSliceBusinessSources({root,ticketText,setBinding:basis.business_ticket_set}); } catch(error) { report.blockers.push({code:'BUSINESS_SOURCE_BLOCKED',field:'basis.business_ticket_set',reason:error.message}); }
     const sourceDoc=key=>basis[key]?metadata(read(resolveSliceBasis({basis},key).ref).toString('utf8')):{};
     const registration=sourceDoc('implementation_repository'),baseline=sourceDoc('engineering_baseline');
     const registeredRoot=registration.local_worktree?(registration.project_root&&registration.project_root!=='.'?path.resolve(registration.local_worktree,registration.project_root):registration.local_worktree):undefined;
@@ -131,7 +135,9 @@ function prepare({root=process.cwd(),ticket_ref,checkpoint_ref,sources={},refine
     } else compiled=compileDefaultImplementationContract({...compileBase,recipeIds:input.recipe_ids||[],requiredCapabilities:[...new Set([...(input.required_capabilities||[]),...componentCapabilities])],architecture_identity,architecture_evidence,technical_design:bound('technical_design'),...(bound('frontend_delivery')?{frontend_delivery:{acceptance_ref:bound('frontend_delivery').ref,digest:bound('frontend_delivery').digest}}:{}),...(approved_slice?{approved_slice}:{})});
     if(compiled.compiler_contract_digest!==digest(compilerRules).slice(7))throw new TypeError('编译规则来源冲突：准备期间发生变化');
     const resolution=Object.fromEntries(['required_capabilities','required_skills','recipe_ids','conditions','registry_digest','compiler_contract_digest','architecture_identity','component_bindings','component_bindings_digest'].filter(key=>compiled[key]!==undefined).map(key=>[key,compiled[key]]));
-    contract={schema_version:3,ticket_policy:{mode:'frozen-requirements',state_owner:'tracker-or-task-package'},contract_id:input.contract_id,contract_version:input.contract_version,slice_id:input.slice_id,status:'draft',basis,scope,applicability,resolution,acceptance:input.acceptance||markdownAcceptance(ticketText),verification:input.verification,work_units:input.work_units,...(input.extensions?{extensions:input.extensions}:{})};
+    const businessAcceptance=basis.business_ticket_set&&Array.isArray(ticket.acceptance_refs)
+      ? Object.fromEntries(ticket.acceptance_refs.map(id=>[id,{source:'spec',locator:id}])) : undefined;
+    contract={schema_version:3,ticket_policy:{mode:'frozen-requirements',state_owner:'tracker-or-task-package'},contract_id:input.contract_id,contract_version:input.contract_version,slice_id:input.slice_id,status:'draft',basis,scope,applicability,resolution,acceptance:input.acceptance||businessAcceptance||markdownAcceptance(ticketText),verification:input.verification,work_units:input.work_units,...(input.extensions?{extensions:input.extensions}:{})};
     report.reason_chains=compiled.reason_chains;
     for(const reason of compiled.readiness_blockers||[])report.blockers.push({reason});
     normalizeSliceContract(contract,{root});
@@ -144,7 +150,7 @@ function prepare({root=process.cwd(),ticket_ref,checkpoint_ref,sources={},refine
       if(refinements[field]!==undefined)origins.push({kind:'agent-refinement'});
       if(field==='scope'&&registeredRoot&&!input.scope?.project_roots)origins.push({kind:'repository-registration',ref:resolveSliceBasis({basis},'implementation_repository').ref});
       if(field==='scope'&&input.extensions?.cross_repo?.repository_bindings)for(const keys of Object.values(input.extensions.cross_repo.repository_bindings))origins.push({kind:'repository-registration',ref:resolveSliceBasis({basis},keys.implementation_repository).ref});
-      if(field==='acceptance'&&!input.acceptance)origins.push({kind:'ticket-acceptance',ref:ticket_ref});
+      if(field==='acceptance'&&!input.acceptance)origins.push(businessAcceptance?{kind:'business-spec-acceptance',ref:resolveSliceBasis({basis},'spec').ref,selection_ref:ticket_ref}:{kind:'ticket-acceptance',ref:ticket_ref});
       if(field==='applicability'&&scope.risk_level)origins.push({kind:'lifecycle-rule',ref:resolveSliceBasis({basis},'lifecycle_registry').ref});
       report.provenance.push({target:field,origins,requires_professional_review:true});
     }

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

@@ -1,3 +1,4 @@
+import { assertImplementationTicket, assertSliceBusinessSources, businessTicketVersion } from './business-tickets.mjs';
 import {validateExistingUiBaseline} from './existing-ui-baseline.mjs';
 import {sliceRepositories} from './slice-repositories.mjs';
 import { sliceCheckApplicability } from './slice-applicability.mjs';
@@ -5,6 +6,7 @@ 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';
+import { parseContent } from './plan-spec-markdown.mjs';
 
 const parseCache=Symbol('slice-yaml');
 const originals = new WeakMap();
@@ -86,6 +88,14 @@ function locate(text, locator) {
     requireThat(start>=1&&end>=start&&end<=lines.length,`定位范围无效: ${locator}`);
     return lines.slice(start-1,end).join('\n');
   }
+  if (/^AC-[A-Za-z0-9][A-Za-z0-9._-]*$/.test(locator)) {
+    const parsed=parseContent(text);
+    if(parsed.supported) {
+      const matches=parsed.entries.filter(entry=>entry.kind==='AC'&&entry.id===locator);
+      requireThat(matches.length===1,`验收 ID 缺失或不唯一: ${locator}`);
+      return lines.slice(matches[0].position.start.line-1,matches[0].position.end.line).join('\n');
+    }
+  }
   const body=text.replace(/^---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$)/,'');
   const matches=body.split('\n').filter(line=>line.includes(locator));
   requireThat(matches.length===1, `定位缺失或不唯一: ${locator}`);
@@ -102,11 +112,13 @@ 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) {
+    requireThat(options.historicalReadOnly || businessTicketVersion(options.root || process.cwd())!==1,'BUSINESS_SLICE_V3_REQUIRED: 新业务拆分规则的实现必须使用 v3；v2 保留历史读取');
     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)) {
+        assertImplementationTicket(fs.readFileSync(file,'utf8'),ref);
         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');
       }
@@ -116,6 +128,8 @@ export function normalizeSliceContract(document, options = {}) {
   schema(raw,'.template-spec/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'],'依据');
+  assertImplementationTicket(sources.ticket.text,refs.ticket);
+  assertSliceBusinessSources({root:options.root || process.cwd(),ticketText:sources.ticket.text,setBinding:sources.business_ticket_set,acceptance:raw.acceptance,specBinding:sources.spec});
   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'],'依据');
@@ -211,7 +225,7 @@ export function normalizeSliceContract(document, options = {}) {
 }
 export function readSliceContract(ref,{root=process.cwd(),diagnostic=false}={}) {
   const bytes=fs.readFileSync(safe(root,ref)),raw=sourceSliceContract(parseSliceYaml(bytes));
-  const contract=diagnostic&&raw.status==='blocked'?null:normalizeSliceContract(raw,{root});
+  const contract=diagnostic&&raw.status==='blocked'?null:normalizeSliceContract(raw,{root,historicalReadOnly:diagnostic&&raw.schema_version===2});
   return {contract,raw,sources:structuredClone(sourceSnapshots.get(contract)||{}),binding:{ref,id:raw.contract_id,version:raw.contract_version,digest:hash(bytes)}};
 }
 

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

@@ -31,7 +31,7 @@ function compile(binding,{root=ROOT,work_unit_id,task_id,actor_id,runtime_id,exe
     task_id,work_unit_id,actor_id,runtime_id,execution_state,workflow_status:'not-started',stage_id:'stage.vertical-slice-implementation',
     contract:{kind:'slice-implementation',contract_id:contract.contract_id,contract_version:contract.contract_version,status:'issued',contract_ref:binding.ref,slice_contract_ref:binding.ref,gate_refs:[binding.approval_ref]},
     inputs:[binding.ref,...new Set(Object.values(contract.lifecycle_refs))],
-    objective:`${unit.behavior}（执行目录：${unit.project_root}；完整约束读取 ${binding.ref}）`,
+    objective:`${unit.behavior}（执行目录：${unit.project_root}；默认消费 ${binding.ref} 的 task 视图并指定 ${work_unit_id}，追溯时展开 full）`,
     allowed_write_paths:unit.allowed_write_paths,forbidden_actions:[...unit.work_unit.forbidden_patterns,'来源过期、越界、缺证据、验证失败或新增影响时停止并回交'],
     expected_outputs:[unit.behavior],expected_evidence_files:unit.work_unit.expected_evidence,verification_commands:unit.work_unit.verification_commands,verification_results:[],
     downstream_consumers:unit.downstream_consumers||['role.lifecycle-orchestrator'],convergence:{parent_work_unit:'work-unit.slice-implementation',convergence_ref:unit.convergence_ref||binding.approval_ref,conflict_escalation:'返回生命周期主控'},user_decisions:decisions

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

@@ -1,3 +1,4 @@
+import {finalizeReading} from './reading-view-bundle.mjs';
 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';
@@ -56,6 +57,7 @@ export function planTracking(root, { checkpoint_ref, items = [], refresh = false
     checkpoint.feature_id = feature;
     checkpoint.mode = 'orchestrate'; checkpoint.status = 'running';
     checkpoint.stage = items[0]?.stage || 'stage.plan';
+    if(checkpoint.stage_trace)checkpoint.stage_trace.stage=checkpoint.stage;
     checkpoint.next_work_unit = items[0]?.work_unit || 'work-unit.plan-requirements';
   }
   checkpoint.feature_id ??= feature;
@@ -116,7 +118,7 @@ export function planTracking(root, { checkpoint_ref, items = [], refresh = false
   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 } = {}) {
+function applyTrackingSources(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;
@@ -174,3 +176,9 @@ export function applyTracking(root, plan, { afterWrite } = {}) {
     throw new Error(`${error.message}; tracking-rollback-${conflicts.length ? `conflict:${conflicts.join(',')}` : 'complete'}`);
   }
 }
+
+// Finalize after the source transaction has committed; presentation failure never rolls it back.
+export function applyTracking(root,plan,options={}){
+ const result=applyTrackingSources(root,plan,options);
+ return finalizeReading(root,plan.input.checkpoint_ref,result);
+}

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

@@ -2,6 +2,7 @@ import { readFileSync, existsSync, lstatSync, realpathSync } from 'node:fs';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
 import { parseDocument } from '../vendor/yaml.mjs';
+import { assertCheckpointBoundary } from './checkpoint-boundary.mjs';
 import { validateJsonSchema } from './json-schema.mjs';
 
 export const TRACKER_REF = '.template-spec/agents/issue-tracker.md';
@@ -12,6 +13,8 @@ export const STAGE_WORK_UNITS = Object.freeze({
   'work-unit.stage-decision': 'stage.plan',
   'work-unit.spec-synthesis': 'stage.spec-architecture',
   'work-unit.prototype-design-v2': 'stage.product-design',
+  'work-unit.prototype-design': 'stage.product-design',
+  'work-unit.business-ticket-formalization': 'stage.product-design',
 });
 export const sha256 = bytes => `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
 export function parseYaml(bytes) {
@@ -72,11 +75,13 @@ export function refreshTracking(root, checkpoint) {
   return { checkpoint: next, stale_item_ids: changed };
 }
 export function assertStageTracking(checkpoint, { root, checkpointRef, currentWorkUnit, nextWorkUnit, transition = false, entering = false, now = new Date() } = {}) {
+  const workUnits={...STAGE_WORK_UNITS,...(isDesign(root)?{'work-unit.business-ticket-formalization':'stage.ticket-formalization'}:{})};
   const identity = parseYaml(readTracking(root, 'yss-project.yaml'));
   if (identity?.schema_version !== 1 || !['template-source', 'project-instance'].includes(identity.repository_mode)) throw new Error('tracking-repository-identity-invalid');
+  if ((transition || entering) && checkpoint?.stage) assertCheckpointBoundary(checkpoint, { root });
   const config = trackerConfig(root);
   const tracking = checkpoint?.stage_tracking;
-  const relevant = STAGE_WORK_UNITS[currentWorkUnit] || STAGE_WORK_UNITS[nextWorkUnit] || ['stage.plan', 'stage.spec-architecture', 'stage.product-design'].includes(checkpoint?.stage);
+  const relevant = workUnits[currentWorkUnit] || workUnits[nextWorkUnit] || ['stage.plan', 'stage.spec-architecture', 'stage.product-design'].includes(checkpoint?.stage);
   if (!tracking) {
     if (identity.repository_mode === 'project-instance' && config.lifecycle_tracking_version === 1 && relevant) throw new Error('stage-tracking-required');
     return { status: 'not-applicable', stale_item_ids: [] };
@@ -104,7 +109,7 @@ export function assertStageTracking(checkpoint, { root, checkpointRef, currentWo
   for (const item of tracking.items) {
     if (index.has(item.id)) throw new Error(`tracking-duplicate-id: ${item.id}`);
     index.set(item.id, item);
-    if (!stages.has(item.stage) || !units.has(item.work_unit) || STAGE_WORK_UNITS[item.work_unit] !== item.stage) throw new Error(`tracking-stage-work-unit-mismatch: ${item.id}`);
+    if (!stages.has(item.stage) || !units.has(item.work_unit) || workUnits[item.work_unit] !== item.stage) throw new Error(`tracking-stage-work-unit-mismatch: ${item.id}`);
     if (allowed && !allowed.includes(item.work_unit)) throw new Error(`tracking-profile-work-unit-forbidden: ${item.id}`);
     if (item.split_reasons.length && !item.definition_ref) throw new Error(`tracking-independent-item-required: ${item.id}`);
     if (item.definition_ref) {
@@ -143,12 +148,12 @@ export function assertStageTracking(checkpoint, { root, checkpointRef, currentWo
   }
   const stale = trackingDrift(root, tracking);
   if (stale.some(id => ['running', 'completed'].includes(index.get(id).progress))) throw new Error(`tracking-stale-completion: ${stale.join(',')}`);
-  if (entering && STAGE_WORK_UNITS[nextWorkUnit] && !tracking.items.some(i => i.work_unit === nextWorkUnit)) throw new Error('tracking-entry-work-item-required');
-  if (transition && STAGE_WORK_UNITS[currentWorkUnit]) {
+  if (entering && workUnits[nextWorkUnit] && !tracking.items.some(i => i.work_unit === nextWorkUnit)) throw new Error('tracking-entry-work-item-required');
+  if (transition && workUnits[currentWorkUnit]) {
     const items = tracking.items.filter(i => i.work_unit === currentWorkUnit);
     if (!items.length) throw new Error('tracking-current-work-item-required');
     if (items.some(i => !['completed', 'cancelled'].includes(i.progress) && !i.deferred)) throw new Error('tracking-current-work-incomplete');
-    if (STAGE_WORK_UNITS[currentWorkUnit] !== STAGE_WORK_UNITS[nextWorkUnit] && tracking.items.some(i => i.stage === STAGE_WORK_UNITS[currentWorkUnit] && !['completed', 'cancelled'].includes(i.progress) && !i.deferred)) throw new Error('tracking-stage-incomplete');
+    if (workUnits[currentWorkUnit] !== workUnits[nextWorkUnit] && tracking.items.some(i => i.stage === workUnits[currentWorkUnit] && !['completed', 'cancelled'].includes(i.progress) && !i.deferred)) throw new Error('tracking-stage-incomplete');
   }
   return { status: 'valid', stale_item_ids: stale };
 }

package/template/scripts/lib/strategic-handoff-consumption.mjs

@@ -47,7 +47,7 @@ export async function verifyConsumption(data,{root=process.cwd(),sliceRef,consum
       }
       for(const term of current.handoff.context_delta.deprecated)ensure(!context.terms_by_ref.has(term.term_ref),`目标尚未处理废弃术语: ${term.term_ref}`);
       ensure(Array.isArray(binding.rows),'缺少逐条承接 rows');
-      const known=new Map([...current.indexes.rules.map(x=>[x.rule_id,x]),...current.indexes.scenarios.filter(x=>x.critical).map(x=>[x.scenario_id,x])]);
+      const known=new Map([...current.indexes.rules.map(x=>[x.rule_id,x]),...current.indexes.scenarios.filter(x=>x.critical).map(x=>[x.scenario_id,x]),...(current.business?.tickets||[]).map(x=>[x.id,x])]);
       const rows=new Map();for(const row of binding.rows){ensure(!rows.has(row.source_id),`重复承接: ${row.source_id}`);rows.set(row.source_id,row);}
       const issues=[], blocked=new Set();let all=false;
       const mark=(id,reason,row)=>{issues.push({source_id:id,reason});if(row?.dependency_status!=='known'||!list(row.dependent_slice_refs))all=true;else row.dependent_slice_refs.forEach(x=>blocked.add(x));};
@@ -75,8 +75,20 @@ export async function verifyConsumption(data,{root=process.cwd(),sliceRef,consum
           ensure(present(row.reason)&&list(row.evidence_refs),`不适用缺少依据: ${id}`);row.evidence_refs.forEach(ref=>safe(root,ref));
         }else {ensure(['pending','conflict'].includes(row.disposition),`非法承接状态: ${id}`);mark(id,row.disposition,row);}
       }
+      for(const ticket of current.business?.tickets||[]) {
+        const row=rows.get(ticket.id);
+        for(const source of ticket.source_refs||[])if(known.has(source.locator)) {
+          const mapped=rows.get(source.locator);
+          if(!row||row.dependency_status!=='known'||!mapped||mapped.dependency_status!=='known'||!row.dependent_slice_refs?.every(ref=>mapped.dependent_slice_refs?.includes(ref)))mark(ticket.id,'business-rule-scenario-dependency-incomplete',row);
+        }
+      }
       for(const[id,row]of rows)if(!known.has(id))mark(id,'removed-or-unknown-source',row);
-      for(const key of new Set(['spec_ref','business_ticket_set_ref',...uiBaselineSourceKeys(original.handoff),...uiBaselineSourceKeys(current.handoff)]))if(original.handoff.source[key]?.digest!==current.handoff.source[key]?.digest){all=true;issues.push({source_id:key,reason:'upstream-asset-stale'});}
+      if(current.business && original.business) {
+        const before=new Map(original.business.tickets.map(t=>[t.id,t.source_digest]));
+        for(const ticket of current.business.tickets)if(before.get(ticket.id)!==ticket.source_digest)mark(ticket.id,'business-ticket-stale',rows.get(ticket.id));
+        if(digest(current.business.coverage_deferred)!==digest(original.business.coverage_deferred)){all=true;issues.push({source_id:'business-ticket-coverage',reason:'deferred-scope-stale'});}
+      }
+      for(const key of new Set(['spec_ref','business_ticket_set_ref',...uiBaselineSourceKeys(original.handoff),...uiBaselineSourceKeys(current.handoff)]))if(!(key==='business_ticket_set_ref'&&current.business&&original.business)&&original.handoff.source[key]?.digest!==current.handoff.source[key]?.digest){all=true;issues.push({source_id:key,reason:'upstream-asset-stale'});}
       // Rule changes can be scoped to declared dependencies. Boundary/decision or
       // runnable-prototype changes need the tactical contract rebound as a whole.
       const stageKeys=['package_version','approval','domain_strategy_ref'];

package/template/scripts/lib/strategic-handoff-io.mjs

@@ -17,6 +17,10 @@ export function withSourceContextSnapshot(root, action) {
   roots.add(path.resolve(root));
   return sourceContextSnapshots.run(roots, action);
 }
+export function sourceContextRef(root, ref) {
+  return ref === 'CONTEXT.md' && sourceContextSnapshots.getStore()?.has(path.resolve(root))
+    ? 'source-context.snapshot.md' : ref;
+}
 export const ensure = (condition, message) => { if (!condition) throw new TypeError(message); };
 export const canonical = value => Array.isArray(value) ? value.map(canonical) : value && typeof value === 'object' ? Object.fromEntries(Object.keys(value).sort().map(k => [k, canonical(value[k])])) : value;
 export const hash = bytes => `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
@@ -35,7 +39,7 @@ export function relative(ref) {
 }
 export function safe(root, ref, { missing = false } = {}) {
   relative(ref);
-  if (ref === 'CONTEXT.md' && sourceContextSnapshots.getStore()?.has(path.resolve(root))) ref = 'source-context.snapshot.md';
+  ref = sourceContextRef(root, ref);
   let current = path.resolve(root);
   ensure(!existsSync(current) || !lstatSync(current).isSymbolicLink(), `根目录不能是 symlink: ${root}`);
   for (const part of ref.split('/')) {
@@ -79,7 +83,7 @@ export function archive(command, source, destination) {
 export function sourceApprovalPolicy(source) {
   const roles=structuredClone(source);
   roles.user_decision_policy ||= {gates:[]};
-  ensure(!(roles.user_decision_policy.required_capabilities || []).some(id => id !== 'strategic-decision-reuse-v1'), '接收工具不支持源用户决定策略，请升级工具后验包');
+  ensure(!(roles.user_decision_policy.required_capabilities || []).some(id => !['strategic-decision-reuse-v1','business-ticket-approval-v1'].includes(id)), '接收工具不支持源用户决定策略，请升级工具后验包');
   const policy=roles.gate_policy;
   // Dedicated receivers may predate check_reviews. Mirror source check-review
   // rules into their existing digital review lookup without changing source bytes.