create-yss-spec 3.5.2 → 3.5.4

package/template/README.md

@@ -9,27 +9,15 @@
 ## 项目结构
 
 ```text
-├── .agents/                 ← 跨 Agent 共享 skills 的权威内容
-├── .codex/                  ← Codex skills 投影与平台专属 skills
-├── .cursor/                 ← Cursor skills 投影
-├── .pi/                     ← Pi skills 投影与平台专属 skills
-├── AGENTS.md                ← AI 指令
-├── CONTEXT.md               ← 领域词汇表
-├── yss-project.yaml         ← 仓库身份清单
-├── docs/
-│   ├── api/                 ← OpenAPI 3.1 契约
-│   ├── adr/                 ← 架构决策记录
-│   ├── requirements/        ← Spec / 用户故事 / 需求草案 / 垂直切片
-│   ├── plan/                ← 战略规划与 Spec 上游输入
-│   ├── design/              ← 产品设计、原型、交互说明和状态矩阵
-│   ├── architecture/        ← 架构设计与审查模板
-│   ├── releases/            ← 发布说明
-│   ├── implementation/      ← 实施方案、上线记录和回滚方案
-│   ├── testing/             ← 测试策略和验证记录
-│   ├── agents/              ← Agent 协作规范、Ticket/Triage/领域文档约定
-│   ├── templates/           ← 通用文档模板
-│   └── process/             ← 生命周期、裁剪、Scrum 和技能治理说明
-└── scripts/                 ← 模板轻量校验脚本
+├── .agents/skills/          ← 共享技能权威内容
+├── .codex/、.cursor/、.pi/  ← 技能投影与平台专属能力
+├── AGENTS.md                ← Agent 入口规则
+├── CONTEXT.md               ← 唯一业务词汇表
+├── yss-project.yaml         ← 仓库身份
+├── .template-spec/          ← 可复用流程、门禁、契约与文档模板
+├── .template-source/        ← 模板维护、分发工具和历史证据（不进入实例）
+├── docs/                    ← 项目实例按需创建的 Plan、Spec、设计、Ticket 与交付证据
+└── scripts/                 ← 合同与流程验证工具
 ```
 
 项目需要生成度量、外部实现仓库记录或其他临时产物时再按需创建对应目录。前后端实现仓库接入规则见 `.template-spec/process/implementation-repo-integration.md`。
@@ -37,9 +25,9 @@
 ## Quickstart
 
 1. 先读取 `yss-project.yaml`，按 `repository_mode` 选择模板维护或产品研发生命周期。
-2. 必读入口为 `AGENTS.md` 与 `CONTEXT.md`；流程事实分别以生命周期映射和裁剪指南为准。
+2. 必读入口为 `AGENTS.md` 与 `CONTEXT.md`；流程事实以生命周期注册表和裁剪指南为准。
 3. `template-source` 修改后先按 `maintenance-intensity.yaml` 判定 L1 / L2 / L3，默认用 `scripts/verify-template-fast` 达到 `implementation-ready`；L3 日常采用维护者自检，正式发布前执行完整门禁；只有共享 skill 变更才运行 `scripts/sync-skills` 和 `scripts/update-skill-lock`。
-4. `project-instance` 默认从 `yss-product-lifecycle` 的 `route` 模式开始，再由原生 `work-unit.*` 推进 Plan、Spec、产品设计、工程契约和 Ticket 正式化；`grill-with-docs`、`to-spec`、`to-tickets`、`implement` 仅作为用户显式调用的兼容入口。
+4. `project-instance` 默认从 `yss-product-lifecycle` 的 `route` 模式开始，再由原生 `work-unit.*` 推进 Plan、Spec、产品设计、工程契约和 Ticket 正式化；`to-spec`、`to-tickets`、`implement` 仅作为用户显式调用的兼容入口。
 5. 实现仓库接入、YSS 路由、独立审查、fresh verification 和 Git checkpoint 以 `AGENTS.md` 的硬门禁为准。
 
 
@@ -94,7 +82,7 @@ scripts/verify-template-fast
 - 示例 OpenAPI YAML 是否可解析。
 - Git diff 是否存在空白错误。
 
-显式准备审查候选时执行 `scripts/verify-template-candidate`；首次正式冻结前和最终发布前执行不可裁剪的 `scripts/verify-template`。
+PR 执行 `scripts/verify-template-candidate`；main 与正式发布前执行不可裁剪的 `scripts/verify-template`。独立审查和候选冻结仅在显式采用旧兼容协议时执行。
 
 ## 关键文档
 

package/template/scripts/contract

@@ -1,13 +1,25 @@
 #!/usr/bin/env node
 import path from 'node:path';
-import {viewContract,diffContract} from './lib/contract-views.mjs';
+import {readFileSync,writeFileSync} from 'node:fs';
+import {safe} from './lib/strategic-handoff-io.mjs';
+import {renderReadingBundle,checkReadingViews,readingCheckpointsForAsset,saveReadingComparison,planEnableReading,applyEnableReading} from './lib/reading-view-bundle.mjs';
+import {viewContract,diffContract,prepareContractReview} from './lib/contract-views.mjs';
 try{
  const args=process.argv.slice(2),mode=args.shift(),options={},positional=[];
- for(let i=0;i<args.length;i++){const arg=args[i];if(arg==='--json')options.json=true;else if(arg.startsWith('--')){const key=arg.slice(2);if(!['kind','profile','unit','root','before-root'].includes(key)||!args[i+1]||args[i+1].startsWith('--'))throw Error(`未知或缺值参数 ${arg}`);options[key]=args[++i];}else positional.push(arg);}
- const config={kind:options.kind,root:path.resolve(options.root||process.cwd()),profile:options.profile||'review',unit_id:options.unit,beforeRoot:options['before-root']?path.resolve(options['before-root']):undefined};
+ for(let i=0;i<args.length;i++){const arg=args[i];if(arg==='--json')options.json=true;else if(arg==='--model')options.model=true;else if(arg.startsWith('--')){const key=arg.slice(2);if(!['kind','profile','unit','root','before-root','decision','task-layout','checkpoint','output'].includes(key)||!args[i+1]||args[i+1].startsWith('--'))throw Error(`未知或缺值参数 ${arg}`);options[key]=args[++i];}else positional.push(arg);}
+ const config={kind:options.kind,include_reading_model:options.model===true,root:path.resolve(options.root||process.cwd()),profile:options.profile||'review',unit_id:options.unit,task_layout:options['task-layout']||'legacy',beforeRoot:options['before-root']?path.resolve(options['before-root']):undefined,decision_ref:options.decision};
+ if(['render','check-views','plan-enable','apply-enable'].includes(mode)){
+  if(mode==='apply-enable'?positional.length!==1:!options.checkpoint||positional.length)throw Error('reading-command-arguments-invalid');
+  const result=mode==='render'?renderReadingBundle(config.root,options.checkpoint):mode==='check-views'?checkReadingViews(config.root,options.checkpoint):mode==='plan-enable'?planEnableReading(config.root,options.checkpoint):applyEnableReading(config.root,JSON.parse(readFileSync(safe(config.root,positional[0]),'utf8')));
+  if(mode==='plan-enable'&&options.output)writeFileSync(safe(config.root,options.output,{missing:true}),JSON.stringify(result,null,2)+'\n',{flag:'wx'});
+  process.stdout.write(JSON.stringify(result,null,2)+'\n');if(result.blockers?.length||result.reading_update?.status==='failed')process.exitCode=1;
+ }else{
  if(!options.kind)throw Error('必须用 --kind 明确资产类型');
- if(!['view','diff'].includes(mode)||positional.length!==(mode==='view'?1:2))throw Error('用法: contract view <资产> --kind <类型> [--profile review|task|full] [--unit <ID>] [--json] | diff <旧资产> <新资产> --kind <类型>');
- const result=mode==='view'?viewContract(positional[0],config):diffContract(positional[0],positional[1],config);
+ if(!['view','diff','prepare-review'].includes(mode)||positional.length!==(mode==='view'?1:2))throw Error('用法: contract view <资产> --kind <类型> [--profile review|task|full] [--unit <ID>] [--json] | diff|prepare-review <旧资产> <新资产> --kind <类型> [--decision <原决定>]');
+ if(mode==='prepare-review')for(const checkpoint of readingCheckpointsForAsset(config.root,positional[1],config.kind))renderReadingBundle(config.root,checkpoint);
+ const result=mode==='view'?viewContract(positional[0],config):mode==='prepare-review'?prepareContractReview(positional[0],positional[1],config):diffContract(positional[0],positional[1],config);
+ if(mode==='prepare-review'&&options.checkpoint&&!result.blockers?.length)result.saved_comparison=saveReadingComparison(config.root,options.checkpoint,result);
  process.stdout.write(options.json||!result.markdown?JSON.stringify(result,null,2)+'\n':result.markdown);
  if(result.blockers?.length)process.exitCode=1;
+ }
 }catch(error){process.stderr.write(error.message+'\n');process.exitCode=1;}

package/template/scripts/feature-assets

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { inspectAssets, planAssets, applyAssets, restoreAssets } from './lib/feature-assets.mjs';
+try {
+  const {values,positionals}=parseArgs({allowPositionals:true,strict:true,options:{root:{type:'string'},checkpoint:{type:'string'},candidate:{type:'string',multiple:true},'archive-dir':{type:'string'},plan:{type:'string'},receipt:{type:'string'},json:{type:'boolean'},help:{type:'boolean'}}});
+  if(values.help) process.stdout.write('feature-assets inspect|plan --root <project> --checkpoint <ref> [--candidate <ref> ... --archive-dir <external-dir>] [--json]\nfeature-assets apply --root <project> --plan <external-plan.json>\nfeature-assets restore --root <project> --receipt <external-receipt.json>\nplan writes JSON to stdout only; apply never grants lifecycle approval.\n');
+  else {
+    if(!values.root||positionals.length!==1)throw Error('explicit-root-and-command-required');
+    const root=path.resolve(values.root),command=positionals[0];let result;
+    if(command==='inspect') result=inspectAssets({root,checkpoint:values.checkpoint});
+    else if(command==='plan')result=planAssets({root,checkpoint:values.checkpoint,candidates:values.candidate,archiveDir:values['archive-dir']});
+    else if(command==='apply'){
+      const ref=fs.realpathSync(values.plan),realRoot=fs.realpathSync(root);
+      if(ref===realRoot||ref.startsWith(realRoot+path.sep))throw Error('plan-must-be-outside-project');
+      result=applyAssets({root,plan:JSON.parse(fs.readFileSync(ref,'utf8'))});
+    } else if(command==='restore')result=restoreAssets({root,receiptRef:values.receipt});
+    else throw Error('unknown-command');
+    process.stdout.write(JSON.stringify(result,null,2)+'\n');
+    if(result.status==='partial')process.exitCode=1;
+  }
+} catch(error) {process.stderr.write(error.message+'\n');process.exitCode=2;}

package/template/scripts/inspect-plan-spec

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+import { inspectPlanSpec, renderReport } from './lib/plan-spec-quality.mjs';
+const help = `只读 Plan / Spec 诊断（不改变阶段、批准或就绪状态）
+inspect-plan-spec check --root <项目根> [--plan <Plan>] [--spec <Spec>] [--slice <Slice YAML>] [--json]
+inspect-plan-spec diff --root <项目根> --before <旧Spec> --after <新Spec> [--json]
+check 至少指定 Plan、Spec 之一；--slice 可重复。路径相对项目根，来源不联网、不扫描。
+退出码 0：诊断执行完成（可有发现）；2：输入、解析或新鲜度不足。
+`;
+const argv = process.argv.slice(2);
+if (argv.includes('--help') || argv.includes('-h')) { process.stdout.write(help); }
+else {
+  const options = { command: argv.shift(), slices: [] };
+  try {
+    while (argv.length) {
+      const flag = argv.shift();
+      if (flag === '--json') { options.json = true; continue; }
+      if (!['--root', '--plan', '--spec', '--before', '--after', '--slice'].includes(flag)) throw new Error(`不支持参数 ${flag}`);
+      const value = argv.shift();
+      if (!value || value.startsWith('--')) throw new Error(`${flag} 缺少值`);
+      if (flag === '--slice') options.slices.push(value);
+      else { const key = flag.slice(2); if (options[key]) throw new Error(`${flag} 不允许重复`); options[key] = value; }
+    }
+    if (options.command === 'check' && (options.before || options.after) || options.command === 'diff' && (options.plan || options.spec || options.slices.length)) throw new Error('参数不适用于当前命令');
+    const { report, exitCode } = await inspectPlanSpec(options);
+    process.stdout.write(options.json ? `${JSON.stringify(report, null, 2)}\n` : renderReport(report));
+    process.exitCode = exitCode;
+  } catch (error) {
+    const message = { tool: 'inspect-plan-spec', tool_version: '1.0.0', diagnostic_only: true, execution: 'incomplete', findings: [{ code: 'INPUT_ARGUMENT', location: { file: '.', line: 1, column: 1 }, item_id: null, message: error.message, recovery: '查看 --help 并修正参数。' }] };
+    process.stdout.write(process.argv.includes('--json') ? `${JSON.stringify(message, null, 2)}\n` : `${error.message}\n${help}`);
+    process.exitCode = 2;
+  }
+}

package/template/scripts/inspect-skill-discovery

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import { readFileSync } from 'node:fs';
+import { inspectSkill, observeRuntime, assessDiscovery } from './lib/skill-discovery.mjs';
+import { parseDocument } from './vendor/yaml.mjs';
+
+try {
+  const args = {};
+  for (let index = 2; index < process.argv.length; index += 2) {
+    const key = process.argv[index], value = process.argv[index + 1];
+    if (!['--runtime', '--binary', '--cwd', '--pi-loader', '--pi-agent-dir', '--selections', '--required'].includes(key) || !value || value.startsWith('--')) throw new Error(`invalid argument: ${key}`);
+    args[key.slice(2)] = value;
+  }
+  if (!['codex', 'pi', 'cursor'].includes(args.runtime) || !args.binary) throw new Error('--runtime codex|pi|cursor and --binary are required');
+  const cwd = path.resolve(args.cwd ?? '.');
+  const document = parseDocument(readFileSync(path.join(cwd, '.template-spec/agents/yss-skill-registry.yaml'), 'utf8'), { uniqueKeys: true, maxAliasCount: 0 });
+  if (document.errors.length) throw new Error('invalid registry');
+  const registry = document.toJS({ maxAliasCount: 0 });
+  const registered = registry.skills.map((item) => inspectSkill(path.join(cwd, '.agents/skills', item.id, 'SKILL.md')));
+  const observation = await observeRuntime({ runtime: args.runtime, binary: args.binary, cwd, piLoader: args['pi-loader'], piAgentDir: args['pi-agent-dir'] });
+  const assessment = assessDiscovery({ registered, observation, expected: { runtime: args.runtime, version: observation.version, cwd }, required: (args.required ?? '').split(',').filter(Boolean), selections: args.selections ? JSON.parse(readFileSync(args.selections, 'utf8')) : [] });
+  process.stdout.write(JSON.stringify({ schema_version: 1, registered, observation, assessment }, null, 2) + '\n');
+  if (assessment.status === 'blocked' || observation.status !== 'observed' || observation.errors?.some((item) => args.runtime === 'codex' || item.type === 'error')) process.exitCode = 2;
+} catch (error) { process.stderr.write(error.message + '\n'); process.exitCode = 2; }

package/template/scripts/lib/business-ticket-lifecycle.mjs

@@ -0,0 +1,34 @@
+import fs from 'node:fs';
+import {businessAuthoringEnabled,businessPath,businessSetRef,checkBusinessTickets,assertBusinessDeferredApprovals} from './business-tickets.mjs';
+import {yamlValue} from './plan-spec-markdown.mjs';
+import {loadApprovalRecord,validateApprovalRecord} from './approval-record.mjs';
+
+// Reuse existing approval protocols; this function creates no approval boundary.
+export function assertBusinessApprovalBasis(root,state,{required=false}={}) {
+  if(!businessAuthoringEnabled(root))return;
+  if(state?.checkpoint_ref)state=yamlValue(fs.readFileSync(businessPath(root,state.checkpoint_ref),'utf8'));
+  if(!required)return;
+  const report=checkBusinessTickets({root,setRef:businessSetRef(state),mode:'formal'});
+  if(report.status!=='passed')throw Error(`BUSINESS_FORMALIZATION_BLOCKED: ${report.diagnostics.map(x=>x.code).join(', ')}`);
+  const rolesDoc=yamlValue(fs.readFileSync(businessPath(root,'.template-spec/agents/digital-human-roles.yaml'),'utf8'));
+  const proofRefs=[];
+  for(const id of ['gate.spec-baseline-approved','gate.product-design-approved']) {
+    const gate=state.gates?.[id];
+    if(id==='gate.product-design-approved'&&gate?.status==='not-applicable'&&gate.reason?.trim()&&gate.evidence_refs?.length){for(const ref of gate.evidence_refs)fs.readFileSync(businessPath(root,ref));continue;}
+    if(gate?.status!=='approved'||!gate.approval_ref)throw Error(`BUSINESS_APPROVAL_REQUIRED: ${id}`);
+    const record=loadApprovalRecord(businessPath(root,gate.approval_ref),id);
+    if(record.gate_id!==id||record.subject_ref!==gate.subject_ref||!gate.approval_scope?.length||JSON.stringify([...gate.approval_scope].sort())!==JSON.stringify([...(record.approval_scope||[])].sort()))throw Error(`BUSINESS_APPROVAL_SCOPE_MISMATCH: ${id}`);
+    validateApprovalRecord(record,{root,rolesDoc,requireApproved:true});
+    if(id==='gate.spec-baseline-approved'&&record.subject_ref!==report.spec.ref) {
+      // Existing approvals may cover a review package instead of the Spec itself.
+      // Its signed bytes, rather than a mutable checkpoint label, bind the baseline.
+      let subject;
+      try {subject=yamlValue(fs.readFileSync(businessPath(root,record.subject_ref),'utf8'));}
+      catch {throw Error('BUSINESS_SPEC_APPROVAL_MISMATCH: 批准主体不是当前 Spec 或可核验审阅包');}
+      const bindings=[...(Array.isArray(subject?.basis)?subject.basis:[]),...(Array.isArray(subject?.assets)?subject.assets:[])];
+      if(!bindings.some(x=>(x.ref||x.persisted_ref)===report.spec.ref&&String(x.digest).replace(/^sha256:/,'')===report.spec.digest.slice(7)))throw Error('BUSINESS_SPEC_APPROVAL_MISMATCH');
+    }
+    proofRefs.push(gate.approval_ref,record.user_decision_ref,record.continuation_ref);
+  }
+  assertBusinessDeferredApprovals(report,proofRefs);
+}

package/template/scripts/lib/business-tickets.mjs

@@ -0,0 +1,273 @@
+import nativeFs from 'node:fs';
+import {readFileSync,existsSync,lstatSync} from './validation-phase.mjs';
+const fs={...nativeFs,readFileSync,existsSync,lstatSync};
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { parseContent, yamlValue, ids as sourceIds } from './plan-spec-markdown.mjs';
+import { fileURLToPath } from 'node:url';
+import { validateJsonSchemas } from './json-schema.mjs';
+import { sourceContextRef, withSourceContextSnapshot } from './strategic-handoff-io.mjs';
+
+export const BUSINESS_TICKET_PROTOCOL = 1;
+export const BUSINESS_TICKET_CAPABILITY = 'business-ticket-approval-v1';
+const hash = bytes => `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+const nonempty = value => typeof value === 'string' && Boolean(value.trim());
+const list = value => Array.isArray(value) && value.every(nonempty);
+const fail = message => { throw new Error(message); };
+export function businessPath(root, ref) {
+  if (!nonempty(ref) || path.isAbsolute(ref) || ref.includes('\\') || ref.split('/').some(x => !x || x === '.' || x === '..')) fail(`BUSINESS_PATH_INVALID: ${ref}`);
+  ref = sourceContextRef(root, ref);
+  let file = fs.realpathSync(root);
+  for (const part of ref.split('/')) {
+    file = path.join(file, part);
+    try { if (fs.lstatSync(file).isSymbolicLink()) fail(`BUSINESS_SYMLINK_FORBIDDEN: ${ref}`); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+  return file;
+}
+export function ticketMetadata(text) {
+  const match = String(text).match(/^\uFEFF?---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  if(match)return yamlValue(match[1]);
+  try {const data=yamlValue(String(text));return data&&typeof data==='object'&&!Array.isArray(data)?data:{};}catch{return {};}
+}
+export function businessTicketVersion(root) {
+  const identity = businessPath(root, 'yss-project.yaml');
+  if (fs.existsSync(identity) && yamlValue(fs.readFileSync(identity,'utf8'))?.repository_mode === 'template-source') return null;
+  const ref = '.template-spec/agents/issue-tracker.md';
+  const file = businessPath(root, ref);
+  if (!fs.existsSync(file)) return null;
+  const value = ticketMetadata(fs.readFileSync(file, 'utf8'))?.tracker?.business_ticket_version;
+  if (value !== undefined && value !== 1) fail('BUSINESS_TICKET_VERSION_UNSUPPORTED');
+  return value ?? null;
+}
+export function businessAuthoringEnabled(root) {
+  if(businessTicketVersion(root)!==1)return false;
+  const profile=businessPath(root,'.template-spec/process/harness-profile.yaml');
+  const id=fs.existsSync(profile)?yamlValue(fs.readFileSync(profile,'utf8'))?.profile_id:null;
+  return !['harness.backend-delivery','harness.frontend-delivery'].includes(id);
+}
+export function assertImplementationTicket(text, ref = '') {
+  const kind = ticketMetadata(text)?.kind;
+  if (kind === 'stage-work-item' || /(^|\/)work-items\//.test(ref)) fail('stage-work-item 不能作为实现 Ticket');
+  if (['business-ticket', 'business-ticket-set'].includes(kind) || /(^|\/)business-tickets\//.test(ref)) fail('business-ticket-not-implementable: 业务 Ticket 不能作为实现 Slice');
+}
+
+/** Structural evidence only. Business semantics and approval remain with lifecycle reviewers. */
+export function checkBusinessTickets({root, setRef, mode = 'draft', reviewRef} = {}) {
+  // Imported v5 sources retain root-relative bindings inside the immutable payload.
+  const imported=typeof setRef==='string'&&setRef.match(/^(docs\/handoffs\/[^/]+\/v[1-9][0-9]*\/package\/payload\/files\/)(.+)$/);
+  if(imported) {
+    const prefix=imported[1], sourceRoot=businessPath(root,prefix.slice(0,-1));
+    const result=withSourceContextSnapshot(sourceRoot,()=>checkBusinessTickets({root:sourceRoot,setRef:imported[2],mode,reviewRef:reviewRef?.startsWith(prefix)?reviewRef.slice(prefix.length):reviewRef}));
+    const mapped=ref=>typeof ref==='string'?prefix+(ref==='CONTEXT.md'?'source-context.snapshot.md':ref):ref;
+    result.inputs=result.inputs.map(x=>({...x,ref:mapped(x.ref)}));
+    result.diagnostics=result.diagnostics.map(x=>({...x,source_ref:mapped(x.source_ref)}));
+    result.tickets=result.tickets.map(x=>({...x,ref:mapped(x.ref)}));
+    if(result.spec)result.spec={...result.spec,ref:mapped(result.spec.ref)};
+    if(result.semantic_review)result.semantic_review={...result.semantic_review,ref:mapped(result.semantic_review.ref)};
+    return result;
+  }
+  const report = {schema_version:1, read_only:true, execution_authorization:'not-evaluated', mode, status:'passed', diagnostics:[], inputs:[], tickets:[], uncovered:[], unassessed:['business-granularity','semantic-fidelity','approval-validity']};
+  const observed = new Map();
+  const schemaInputs = [];
+  const schemaPath = fileURLToPath(new URL('../../.template-spec/process/schemas/business-tickets-v1.schema.json',import.meta.url));
+  const issue = (code, message, ref = setRef, locator = null) => report.diagnostics.push({code,message,source_ref:ref,locator,recovery:'核对来源、补齐引用或重新审查当前业务 Ticket 集'});
+  const read = ref => {
+    const bytes = fs.readFileSync(businessPath(root,ref)), digest = hash(bytes);
+    if (observed.has(ref) && observed.get(ref) !== digest) fail(`INPUT_DRIFT: ${ref}`);
+    observed.set(ref,digest); return bytes.toString('utf8');
+  };
+  const binding = value => {
+    if (!value || !nonempty(value.ref) || !/^v[1-9][0-9]*$/.test(value.version ?? '') || !/^sha256:[a-f0-9]{64}$/.test(value.digest ?? '')) fail('BINDING_INVALID: 需要 ref/version/digest');
+    const text = read(value.ref);
+    if (observed.get(value.ref) !== value.digest) issue('SOURCE_STALE','来源原始字节已变化',value.ref);
+    return text;
+  };
+  try {
+    if (!['draft','formal'].includes(mode)) fail('MODE_INVALID');
+    const set = yamlValue(read(setRef));
+    schemaInputs.push({value:set,schemaPath,label:setRef});
+    if (set?.schema_version !== 1 || set.kind !== 'business-ticket-set' || !nonempty(set.id) || !/^v[1-9][0-9]*$/.test(set.version ?? '') || !['draft','ready-for-human'].includes(set.status)) fail('BUSINESS_SET_INVALID');
+    report.id=set.id; report.version=set.version; report.spec=set.spec; report.coverage_deferred=set.coverage_deferred ?? [];
+    const spec = parseContent(binding(set.spec),set.spec.ref);
+    if (!spec.supported) issue('SPEC_FORMAT_UNASSESSED','Spec 需显式采用 plan-spec-v1；旧格式不推断覆盖',set.spec.ref);
+    const entries = spec.entries.filter(x => ['FR','NFR','AC'].includes(x.kind));
+    const ids = new Set();
+    for (const entry of entries) {
+      if (ids.has(entry.id)) issue('DUPLICATE_ID',`Spec ID 重复: ${entry.id}`,set.spec.ref,entry.position.start.line);
+      ids.add(entry.id);
+    }
+    if (!entries.some(x => x.kind === 'FR') || !entries.some(x => x.kind === 'AC')) issue('SPEC_COVERAGE_UNASSESSED','缺少可机械读取的 FR/AC',set.spec.ref);
+    if (!Array.isArray(set.tickets) || !set.tickets.length) fail('BUSINESS_TICKETS_REQUIRED');
+    const tickets = new Map(), covered = new Set(), seenPaths = new Set();
+    for (const entry of set.tickets) {
+      const text = binding(entry), ticket = ticketMetadata(text);
+      schemaInputs.push({value:ticket,schemaPath,label:entry.ref});
+      if (tickets.has(entry.id) || seenPaths.has(entry.ref)) issue('DUPLICATE_ID',`Ticket ID 或路径重复: ${entry.id}`,entry.ref);
+      seenPaths.add(entry.ref);
+      if (ticket.schema_version !== 1 || ticket.kind !== 'business-ticket' || !/^BT-[A-Za-z0-9][A-Za-z0-9._-]*$/.test(ticket.id ?? '') || ticket.id !== entry.id || ticket.version !== entry.version) issue('BUSINESS_TICKET_INVALID','类型、稳定 ID 或版本不匹配',entry.ref);
+      if (!['draft','ready-for-human'].includes(ticket.status)) issue('BUSINESS_READINESS_FORBIDDEN','业务票不得声明实现就绪',entry.ref);
+      if (!entry.ref.startsWith(`${path.posix.dirname(setRef)}/business-tickets/`) || !entry.ref.endsWith('.md')) issue('BUSINESS_TICKET_LOCATION','业务票需独立放在 business-tickets/',entry.ref);
+      if (['ref','version','digest'].some(key=>ticket.spec?.[key]!==set.spec?.[key])) issue('SPEC_BINDING_MISMATCH','票据与集合的 Spec 依据不一致',entry.ref);
+      for (const field of ['requirement_refs','acceptance_refs','dependencies']) if (!list(ticket[field])) issue('REQUIRED_FIELD',`缺少 ${field}`,entry.ref);
+      if (!ticket.requirement_refs?.length || !ticket.acceptance_refs?.length) issue('COVERAGE_REQUIRED','需要需求与验收引用',entry.ref);
+      for (const [field, pattern] of [['requirement_refs',/^(FR|NFR)-/],['acceptance_refs',/^AC-/]]) {
+        for (const id of Array.isArray(ticket[field]) ? ticket[field] : []) {
+          if (!ids.has(id) || !pattern.test(id)) issue('DANGLING_REFERENCE',`无效引用 ${id}`,entry.ref);
+          else covered.add(id);
+        }
+      }
+      for(const ac of Array.isArray(ticket.acceptance_refs)?ticket.acceptance_refs:[]) {
+        const requirementIds=sourceIds(entries.find(x=>x.id===ac)?.fields?.['需求引用'],['FR','NFR']);
+        if(!requirementIds.length || requirementIds.some(id=>!ticket.requirement_refs?.includes(id)))issue('AC_REQUIREMENT_MISMATCH',`验收 ${ac} 与本票需求来源不一致`,entry.ref,ac);
+      }
+      for (const source of ticket.source_refs ?? []) {
+        const sourceText = binding(source);
+        if (source.locator) {
+          let found;
+          if (/\.(yaml|yml|json)$/.test(source.ref)) {
+            const ids=[];
+            const walk=value=>{if(Array.isArray(value))value.forEach(walk);else if(value&&typeof value==='object')for(const [key,item]of Object.entries(value)){if((key==='id'||key.endsWith('_id'))&&typeof item==='string')ids.push(item);else walk(item);}};
+            walk(yamlValue(sourceText));found=source.locator_kind!=='heading'&&ids.filter(x=>x===source.locator).length===1;
+          } else {const parsed=parseContent(sourceText,source.ref);found=(source.locator_kind==='heading'?parsed.headings:parsed.locators).filter(x=>x.value===source.locator).length===1;}
+          if(!found)issue('DANGLING_REFERENCE',`来源定位缺失或不唯一: ${source.locator}`,source.ref,source.locator);
+        }
+      }
+      for (const heading of ['业务结果','范围','非目标','验收','风险']) if (!new RegExp(`^## ${heading}\\s*$`,'m').test(text)) issue('REQUIRED_SECTION',`缺少 ${heading}`,entry.ref);
+      for (const question of ticket.open_questions ?? []) {
+        if (![question.id,question.question,question.owner,question.resolve_by].every(nonempty) || typeof question.blocking !== 'boolean') issue('QUESTION_INCOMPLETE','未决项需问题、责任人、时点及阻断判断',entry.ref);
+        if (mode === 'formal' && question.blocking) issue('OPEN_BLOCKER',question.question,entry.ref);
+      }
+      if (mode === 'formal' && ticket.status !== 'ready-for-human') issue('TICKET_DRAFT','正式化仍有草案票',entry.ref);
+      tickets.set(entry.id,ticket);
+      report.tickets.push({id:entry.id,ref:entry.ref,version:entry.version,source_digest:entry.digest,source_refs:ticket.source_refs,requirement_refs:ticket.requirement_refs,acceptance_refs:ticket.acceptance_refs,dependencies:ticket.dependencies});
+    }
+    const visiting = new Set(), visited = new Set();
+    const visit = id => {
+      if (visiting.has(id)) { issue('DEPENDENCY_CYCLE',`依赖环包含 ${id}`); return; }
+      if (visited.has(id)) return;
+      visiting.add(id);
+      for (const dep of tickets.get(id)?.dependencies ?? []) {
+        if (!tickets.has(dep)) issue('DANGLING_DEPENDENCY',`${id} 依赖未知票 ${dep}`);
+        else visit(dep);
+      }
+      visiting.delete(id); visited.add(id);
+    };
+    tickets.forEach((_,id)=>visit(id));
+    const deferred = new Set();
+    for (const item of set.coverage_deferred ?? []) {
+      if (!ids.has(item.id) || deferred.has(item.id) || covered.has(item.id)) issue('DEFERRED_COVERAGE_INVALID',`延期引用无效或重复: ${item.id}`);
+      if (!['reason','risk','owner','target_version','followup_ticket_ref','verification_plan'].every(k=>nonempty(item[k]))) issue('DEFERRED_INCOMPLETE',`延期缺少责任或处理计划: ${item.id}`);
+      if (mode === 'formal') {
+        if (!item.decision) issue('DEFERRED_DECISION_REQUIRED',`延期缺少既有决定绑定: ${item.id}`);
+        else binding(item.decision);
+      }
+      deferred.add(item.id);
+    }
+    report.uncovered = [...ids].filter(id=>!covered.has(id)&&!deferred.has(id));
+    for (const id of report.uncovered) issue('COVERAGE_MISSING',`未覆盖 ${id}`,set.spec.ref,id);
+    if (mode === 'formal') {
+      if (set.status !== 'ready-for-human') issue('SET_DRAFT','业务集合尚未正式化');
+      const review = yamlValue(read(reviewRef || set.review_ref));
+      schemaInputs.push({value:review,schemaPath,label:reviewRef || set.review_ref});
+      if (review.kind !== 'business-ticket-review' || review.schema_version !== 1 || review.result !== 'passed' || review.subject_ref !== setRef || review.subject_digest !== observed.get(setRef) || !nonempty(review.reviewer) || !nonempty(review.drafter) || review.reviewer === review.drafter || !Array.isArray(review.evidence) || !review.evidence.length) issue('REVIEW_REQUIRED','需要独立且绑定当前集合的专业审查');
+      for (const ref of review.evidence ?? []) binding(ref);
+      report.semantic_review={status:'recorded',ref:reviewRef||set.review_ref,result:review.result,subject_digest:review.subject_digest};
+      report.unassessed = ['approval-validity','semantic-review-truth'];
+    }
+  } catch (error) { issue(error.message.split(':')[0],error.message); }
+  try { validateJsonSchemas(schemaInputs).forEach((result,index)=>{if(!result.valid)issue('SCHEMA_INVALID',result.error,schemaInputs[index].label);}); }
+  catch(error) {issue('SCHEMA_UNAVAILABLE',error.message);}
+  for (const [ref,digest] of observed) {
+    try { if (hash(fs.readFileSync(businessPath(root,ref))) !== digest) issue('INPUT_DRIFT','读取期间来源变化',ref); }
+    catch { issue('INPUT_DRIFT','读取期间来源消失',ref); }
+  }
+  report.inputs = [...observed].map(([ref,digest])=>({ref,digest}));
+  report.status = report.diagnostics.length ? 'blocked' : 'passed';
+  return report;
+}
+
+export function businessSetRef(state) { return state?.artifacts?.['artifact.business-ticket-set']?.ref || state?.business_ticket_set_ref; }
+export function assertBusinessTicketTransition(root, current, next, state = {}) {
+  if (!businessAuthoringEnabled(root)) return;
+  if (state.checkpoint_ref) state=yamlValue(fs.readFileSync(businessPath(root,state.checkpoint_ref),'utf8'));
+  const spec = current === 'work-unit.spec-synthesis';
+  const design = ['work-unit.prototype-design','work-unit.prototype-design-v2'].includes(current);
+  const formal = current === 'work-unit.business-ticket-formalization';
+  if (!spec && !design && !formal) return;
+  if ((spec || design) && next === 'work-unit.technical-analysis') fail('BUSINESS_FORMALIZATION_REQUIRED');
+  const report = checkBusinessTickets({root,setRef:businessSetRef(state),mode:formal?'formal':'draft'});
+  if (report.status !== 'passed') fail(`business-ticket-blocked: ${report.diagnostics.map(x=>x.code).join(', ')}`);
+}
+
+export function assertSliceBusinessSources({root,ticketText,setBinding,acceptance,specBinding}) {
+  const ticket = ticketMetadata(ticketText);
+  if (businessTicketVersion(root) !== 1 && !ticket.business_ticket_refs && !setBinding) return;
+  if(ticket.kind!=='vertical-slice-ticket')fail('IMPLEMENTATION_TICKET_KIND_REQUIRED');
+  if(ticket.business_ticket_set_ref && ticket.business_ticket_set_ref!==setBinding?.ref)fail('BUSINESS_SET_REFERENCE_MISMATCH');
+  if (!setBinding?.ref || !setBinding.digest) fail('BUSINESS_SET_BINDING_REQUIRED');
+  const bytes = fs.readFileSync(businessPath(root,setBinding.ref));
+  if (hash(bytes) !== setBinding.digest) fail('BUSINESS_SET_STALE');
+  const result = checkBusinessTickets({root,setRef:setBinding.ref,mode:'formal'});
+  if (result.status !== 'passed') fail(`BUSINESS_SOURCE_BLOCKED: ${result.diagnostics.map(x=>x.code).join(', ')}`);
+  if (!list(ticket.business_ticket_refs) || !ticket.business_ticket_refs.length || ticket.business_ticket_refs.some(id=>!result.tickets.some(t=>t.id===id))) fail('BUSINESS_TICKET_REFERENCE_REQUIRED');
+  const selected=result.tickets.filter(t=>ticket.business_ticket_refs.includes(t.id));
+  const allowed=new Set(selected.flatMap(t=>t.acceptance_refs));
+  if (!list(ticket.acceptance_refs) || !ticket.acceptance_refs.length || ticket.acceptance_refs.some(id=>!allowed.has(id))) fail('BUSINESS_ACCEPTANCE_REFERENCE_REQUIRED');
+  if(acceptance) {
+    if(!specBinding || ['ref','digest'].some(key=>result.spec[key]!==specBinding[key]))fail('BUSINESS_SPEC_BINDING_MISMATCH');
+    for(const item of Object.values(acceptance))if(item.source!=='spec'||!ticket.acceptance_refs.includes(item.locator))fail('BUSINESS_ACCEPTANCE_SOURCE_MISMATCH');
+    if(ticket.acceptance_refs.some(id=>!Object.values(acceptance).some(item=>item.locator===id)))fail('BUSINESS_ACCEPTANCE_UNCOVERED');
+  }
+}
+
+export function assertBusinessCheckpoint(root,state) {
+  if (!businessAuthoringEnabled(root)) return;
+  const stage=state.stage;
+  const pastSpec=['stage.product-design','stage.system-data-engineering','stage.ticket-formalization','stage.vertical-slice-implementation','stage.verification-release-retrospective'].includes(stage);
+  // Design uses ticket-formalization for business drafting, while the full
+  // lifecycle uses that stage for engineering Slices. Entering the business
+  // work unit must remain possible with drafts; its exit requires formal proof.
+  const finalized=['work-unit.technical-analysis','work-unit.strategic-design-handoff','work-unit.implementation-repository-preparation','work-unit.ticket-decomposition','work-unit.slice-implementation'].includes(state.next_work_unit) || ['stage.system-data-engineering','stage.vertical-slice-implementation','stage.verification-release-retrospective'].includes(stage) || (stage==='stage.ticket-formalization'&&state.next_work_unit!=='work-unit.business-ticket-formalization');
+  const artifact=state.artifacts?.['artifact.business-ticket-set'];
+  const completedSpec=['work-unit.prototype-design','work-unit.prototype-design-v2','work-unit.business-ticket-formalization'].includes(state.next_work_unit)||state.stage_trace?.completed_work_unit==='work-unit.spec-synthesis'||(stage==='stage.spec-architecture'&&['completed','paused-human-gate'].includes(state.status));
+  if(!pastSpec && !finalized && !artifact?.ref && !completedSpec)return;
+  const report=checkBusinessTickets({root,setRef:businessSetRef(state),mode:finalized?'formal':'draft'});
+  if(report.status!=='passed')fail(`BUSINESS_CHECKPOINT_BLOCKED: ${report.diagnostics.map(x=>x.code).join(', ')}`);
+  if(artifact?.digest && report.inputs.find(x=>x.ref===artifact.ref)?.digest!==artifact.digest)fail('BUSINESS_SYNC_STALE');
+  const sync=businessSyncDiagnostics(root,businessSetRef(state),report);if(sync.length)fail('BUSINESS_SYNC_STALE: '+sync.map(x=>x.ref).join(', '));
+}
+
+// Only inspect explicit synchronization declarations in the two feature views.
+export function businessSyncDiagnostics(root,setRef,report) {
+  if(!setRef)return [];
+  const digest=report.inputs?.find(x=>x.ref===setRef)?.digest,diagnostics=[];
+  for(const name of ['map.md','parent-ticket.md']) {
+    const ref=path.posix.join(path.posix.dirname(setRef),name),file=businessPath(root,ref);
+    if(!fs.existsSync(file))continue;
+    const m=ticketMetadata(fs.readFileSync(file,'utf8'));
+    if(m.business_ticket_set_ref && (m.business_ticket_set_ref!==setRef||m.business_ticket_set_digest!==digest))diagnostics.push({code:'BUSINESS_SYNC_STALE',ref});
+  }
+  return diagnostics;
+}
+
+export function assertBusinessDeferredApprovals(report,verifiedRefs) {
+  for(const item of report.coverage_deferred||[])if(!verifiedRefs.includes(item.decision?.ref))fail(`BUSINESS_DEFERRED_APPROVAL_UNBOUND: ${item.id}`);
+}
+
+export function summarizeBusinessImplementation({root,setRef,sliceRefs=[]}) {
+  const business=checkBusinessTickets({root,setRef,mode:'formal'});
+  const result={status:'not-recorded',execution_authorization:'not-evaluated',implementation_completion:'not-evaluated',tickets:[],diagnostics:[]};
+  if(business.status!=='passed'){result.status='blocked';result.diagnostics=business.diagnostics;return result;}
+  const mapped=new Map(business.tickets.map(t=>[t.id,new Map()]));
+  for(const ref of [...new Set(sliceRefs)])try {
+    const text=fs.readFileSync(businessPath(root,ref),'utf8');assertImplementationTicket(text,ref);const ticket=ticketMetadata(text);
+    if(ticket.kind!=='vertical-slice-ticket'||ticket.business_ticket_set_ref!==setRef||!list(ticket.business_ticket_refs)||!ticket.business_ticket_refs.length||!list(ticket.acceptance_refs)||!ticket.acceptance_refs.length)fail('SLICE_BUSINESS_BINDING_INVALID');
+    const allowed=new Set(business.tickets.filter(t=>ticket.business_ticket_refs.includes(t.id)).flatMap(t=>t.acceptance_refs));
+    if(ticket.business_ticket_refs.some(id=>!mapped.has(id))||ticket.acceptance_refs.some(id=>!allowed.has(id)))fail('SLICE_COVERAGE_INVALID');
+    for(const id of ticket.business_ticket_refs)for(const ac of ticket.acceptance_refs)if(business.tickets.find(t=>t.id===id).acceptance_refs.includes(ac)){const rows=mapped.get(id);rows.set(ac,[...(rows.get(ac)||[]),ref]);}
+  }catch(error){result.diagnostics.push({code:'SLICE_MAPPING_INVALID',source_ref:ref,message:error.message});}
+  result.tickets=business.tickets.map(t=>({id:t.id,acceptance_mappings:Object.fromEntries(mapped.get(t.id)),unmapped_acceptance:t.acceptance_refs.filter(ac=>!mapped.get(t.id).has(ac))}));
+  result.status=result.diagnostics.length?'blocked':!sliceRefs.length?'not-recorded':result.tickets.some(t=>t.unmapped_acceptance.length)?'partial':'covered';
+  return result;
+}

package/template/scripts/lib/checkpoint-boundary.mjs

@@ -0,0 +1,40 @@
+import { readDocument, fileBinding } from './governance-io.mjs';
+
+/** Validate existing lifecycle context evidence; never grants approval. */
+export function assertCheckpointBoundary(value, {root, history=false}={}) {
+  if(history) return {status:'historical-only',execution_authorization:'not-evaluated'};
+  const canonical='.agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml';
+  const contract=readDocument(root,fileBinding(root,canonical)?canonical:'.template-spec/process/checkpoint-boundary.yaml');
+  const registry=readDocument(root,'.template-spec/process/lifecycle-registry.yaml');
+  const stages=new Set(registry.stages.map(x=>x.id));
+  if(!stages.has(value.stage))throw new Error('checkpoint-boundary: 当前 stage 未登记');
+  if(value.next_work_unit!=null&&!registry.work_units.some(x=>x.id===value.next_work_unit))throw new Error('checkpoint-boundary: next_work_unit 未登记');
+  const required=(v,label)=>{if(typeof v!=='string'||!v.trim())throw new Error(`checkpoint-boundary: 缺少 ${label}`);};
+  const reference=(ref,label)=>{required(ref,label);if(!fileBinding(root,ref))throw new Error(`checkpoint-boundary: 证据不可读 ${label}: ${ref}`);};
+  const boundary=value.phase_boundary;
+  if(boundary!==undefined) {
+    if(!boundary||Array.isArray(boundary)||typeof boundary!=='object')throw new Error('checkpoint-boundary: phase_boundary 必须为对象');
+    for(const key of contract.phase_boundary.evidence.required)required(boundary[key],`phase_boundary.${key}`);
+    if(!contract.phase_boundary.choices.includes(boundary.decision))throw new Error('checkpoint-boundary: decision 非法');
+    for(const key of contract.phase_boundary.evidence.conditional[boundary.decision]||[]) {
+      required(boundary[key],`phase_boundary.${key}`);
+      if(key.endsWith('_ref'))reference(boundary[key],key);
+    }
+    if(boundary.decision==='compact'&&!stages.has(boundary.next_phase))throw new Error('checkpoint-boundary: next_phase 必须为当前阶段 ID');
+  }
+  const atBoundary=['paused-human-gate','completed'].includes(value.status)||['handoff','subagent','compact'].includes(boundary?.decision)||
+    (['orchestrate','resume'].includes(value.mode)&&(value.stage!=='stage.entry-triage'||Boolean(value.stage_trace?.completed_work_unit)));
+  if(atBoundary&&!boundary)throw new Error('checkpoint-boundary: 当前边界缺少 phase_boundary');
+  if(atBoundary&&!value.stage_trace)throw new Error('checkpoint-boundary: 当前边界缺少 stage_trace');
+  if(value.stage_trace!==undefined) {
+    const trace=value.stage_trace;
+    if(!trace||Array.isArray(trace)||typeof trace!=='object')throw new Error('checkpoint-boundary: stage_trace 必须为对象');
+    for(const key of contract.checkpoint_policy.required_stage_trace_fields) {
+      if(key==='stage'){if(!stages.has(trace.stage)||trace.stage!==value.stage)throw new Error('checkpoint-boundary: stage_trace.stage 不一致');}
+      else if(!Array.isArray(trace[key]))throw new Error(`checkpoint-boundary: stage_trace.${key} 必须为数组`);
+    }
+    if(trace.completed_work_unit!==undefined&&!registry.work_units.some(x=>x.id===trace.completed_work_unit))throw new Error('checkpoint-boundary: completed_work_unit 非法');
+    for(const key of ['upstream_refs','artifact_refs'])for(const ref of trace[key])reference(typeof ref==='string'?ref:ref?.ref,key);
+  }
+  return {status:'passed',execution_authorization:'not-evaluated'};
+}