create-yss-spec 3.5.2 → 3.5.4

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

@@ -1,3 +1,6 @@
+import { businessTicketVersion, businessAuthoringEnabled, businessSetRef, checkBusinessTickets, businessSyncDiagnostics, summarizeBusinessImplementation } from './business-tickets.mjs';
+import { orchestrationRef } from './governance-io.mjs';
+import {checkReadingViews} from './reading-view-bundle.mjs';
 import { createHash } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
@@ -16,13 +19,13 @@ function source(root, ref) {
 }
 
 /** Read-only projection; checkpoint, registry and orchestration remain authoritative. */
-export function lifecycleStatus({ root, checkpointRef }) {
+export function lifecycleStatus({ root, checkpointRef, taskPackageRef }) {
   if (!root || !checkpointRef) throw new TypeError('root and checkpoint are required');
   root = path.resolve(root);
   const identity = source(root, 'yss-project.yaml').value;
   if (identity.schema_version !== 1 || identity.repository_mode !== 'project-instance') throw new TypeError('生命周期状态仅适用于 project-instance');
   const registryRef = '.template-spec/process/lifecycle-registry.yaml';
-  const contractRef = '.agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml';
+  const contractRef = orchestrationRef(root);
   const checkpoint = source(root, checkpointRef), registry = source(root, registryRef), contract = source(root, contractRef);
   const value = checkpoint.value;
   if (value.schema_version !== 1 || value.repository_mode !== 'project-instance') throw new TypeError('checkpoint 身份或版本无效');
@@ -76,10 +79,45 @@ export function lifecycleStatus({ root, checkpointRef }) {
     check('stage-tracking', 'not-checked', [checkpointRef], '未登记追踪；按实例既有兼容或显式迁移入口处理，不自动补建');
   }
   if (value.status === 'blocked' && !diagnostics.some(x => x.severity === 'error')) issue('reason-missing', 'checkpoint 已标 blocked，原因未登记', checkpointRef, '补齐真实阻塞原因');
+  let taskSource, task, contractSource;
+  const recovery = {sequence: ['read-status', 'inspect-actual-result', 'verify-current-inputs', 'continue-or-reroute'], task_package_ref: taskPackageRef ?? null, contract_view: null, result_refs: [], prechecks: [], verification_items: [], checks: 'read-only; execution and approval not evaluated'};
+  if(taskPackageRef) {
+    try {
+      taskSource=source(root,taskPackageRef);task=taskSource.value;
+      if(task.work_unit_id!==value.next_work_unit && task.convergence?.parent_work_unit!==value.next_work_unit)throw Error('任务包与 checkpoint 工作单元不一致');
+      if(!['not-started','active','paused','resolved','failed'].includes(task.workflow_status))throw Error('任务运行状态未知');
+      recovery.prechecks.push({status:'not-checked',cwd:root,command:['node','scripts/verify-digital-human-task-package',taskPackageRef]});
+      if(task.contract?.kind==='slice-implementation') {
+        contractSource=source(root,task.contract.slice_contract_ref);
+        const c=contractSource.value.slice_contract||contractSource.value;
+        if(c.contract_id!==task.contract.contract_id||c.contract_version!==task.contract.contract_version)throw Error('任务与当前合同版本不一致');
+        recovery.contract_view={cwd:root,command:['node','scripts/contract','view',task.contract.slice_contract_ref,'--kind','slice','--profile','task','--unit',task.work_unit_id]};
+        const approval=task.contract.gate_refs?.[0];
+        recovery.prechecks.push({status:'not-checked',cwd:root,command:['node','scripts/slice-contract','verify',task.contract.slice_contract_ref,'--unit',task.work_unit_id,...(approval?['--approval-ref',approval]:[])],approval_scope:approval?'current-approval-required':'not-checked: approval reference missing'});
+        if(c.schema_version===3){
+          const unit=c.work_units?.find(x=>x.id===task.work_unit_id);
+          if(!unit)throw Error('当前合同不存在该工作单元');
+          recovery.verification_items=Object.entries(c.verification||{}).filter(([id,check])=>unit.verification_refs?.includes(id)||check.required_for_all===true).map(([id,check])=>({id,...check,status:'not-checked'}));
+        }
+      }
+      recovery.result_refs=[...new Set([...(task.result?.evidence_refs||[]),...(task.verification_results||[]).map(x=>x.evidence_ref)].filter(Boolean))];
+      for(const ref of recovery.result_refs)readFileSync(safeTrackingPath(root,ref));
+      check('task-recovery','passed',[taskPackageRef,...recovery.result_refs],'仅读取任务身份、状态和结果引用；继续前仍须正式验收');
+    } catch(error) {issue('task-recovery-invalid',error.message,taskPackageRef,'核对任务身份与实际结果，再执行适用预检');}
+  }
+  const setRef=businessSetRef(value);
+  const business = setRef ? checkBusinessTickets({root,setRef,mode:'draft'}) : {status:businessTicketVersion(root)===1?(businessAuthoringEnabled(root)?'missing':'strategic-consumption-not-checked'):'legacy-unassessed',tickets:[],diagnostics:[]};
+  for(const item of business.diagnostics)issue(item.code,item.message,item.source_ref,item.recovery);
+  for(const item of businessSyncDiagnostics(root,setRef,business))issue(item.code,'已声明同步的业务集合引用或摘要过期',item.ref,'重新核对视图引用，不自动修复历史批准');
+  const registered=value.artifacts?.['artifact.business-ticket-set'];
+  const actual=business.inputs?.find(item=>item.ref===setRef)?.digest;
+  if(registered?.digest && registered.digest!==actual)issue('business-sync-stale','业务集合已登记同步但摘要过期',setRef,'重验受影响来源与引用，保留历史批准');
+  if(business.status==='missing'&&!['stage.entry-triage','stage.plan','stage.spec-architecture'].includes(value.stage))issue('business-decomposition-missing','Spec 后业务拆分尚未登记',checkpointRef,'补齐业务草案与覆盖，并回到业务正式化');
+  check('business-decomposition',business.status,[setRef].filter(Boolean),'结构与来源只读检查；不证明批准或实现资格');
   const blockers = [...new Set(diagnostics.filter(x => x.severity === 'error').map(x => x.message))];
   const next_step = {
     action_type: 'verify', work_unit: value.next_work_unit ?? null, cwd: root,
-    command: null, input_refs: [checkpointRef],
+    command: null, input_refs: [checkpointRef,...(taskPackageRef?[taskPackageRef]:[])],
     prerequisites: ['核验当前来源、Context、适用门禁与决定或延续', '核对当前范围、任务结果和允许写路径；输入变化时重验'],
   };
   let next_action;
@@ -89,10 +127,10 @@ export function lifecycleStatus({ root, checkpointRef }) {
   } else if (value.status === 'paused-human-gate') {
     next_step.action_type = 'wait';
     next_action = '核对当前会签责任方、资产与决定范围；满足已登记恢复条件后复验';
-  } else if (activeItems.some(item => item.progress === 'running')) {
+  } else if (activeItems.some(item => item.progress === 'running') || task?.workflow_status === 'active') {
     next_step.action_type = 'inspect';
     next_action = '核对运行中任务身份与实际结果；状态未知时不得重复派发';
-  } else if (activeItems.length && activeItems.every(item => item.progress === 'completed')) {
+  } else if ((activeItems.length && activeItems.every(item => item.progress === 'completed')) || task?.workflow_status === 'resolved') {
     next_step.action_type = 'inspect';
     next_action = '核验已有完成证据并重算下一工作单元，不直接重做';
   } else {
@@ -102,10 +140,14 @@ export function lifecycleStatus({ root, checkpointRef }) {
     try { readFileSync(safeTrackingPath(root, script)); next_step.command = ['node', script, checkpointRef]; }
     catch { issue('precheck-unavailable', `预检入口不可读: ${script}`, script, '补齐当前实例工具后执行预检', 'warning'); }
   }
+  const implementationArtifact=value.artifacts?.['artifact.vertical-slice-ticket'];
+  const implementationCoverage=setRef && implementationArtifact?.ref?.endsWith('.md')?summarizeBusinessImplementation({root,setRef,sliceRefs:[implementationArtifact.ref]}):null;
   return {
+    decomposition: {business, implementation: {status:implementationArtifact?'recorded':'not-recorded',recorded_status:implementationArtifact?.status??null,ref:implementationArtifact?.ref??null,coverage:implementationCoverage}, readiness:{status:'not-evaluated',reason:'阶段工作完成不替代批准与实现就绪校验'}},
     schema_version: 1, read_only: true, stage: value.stage, checkpoint_status: value.status,
     work_unit: value.next_work_unit ?? null, owner, blockers, next_action,
-    execution_authorization: 'not-evaluated', verification_scope, diagnostics, next_step,
-    source_digests: { checkpoint: { ref: checkpointRef, digest: checkpoint.digest }, registry: { ref: registryRef, digest: registry.digest }, orchestration: { ref: contractRef, digest: contract.digest } },
+    execution_authorization: 'not-evaluated', verification_scope, diagnostics, next_step, recovery,
+    reading_views: checkReadingViews(root,checkpointRef),
+    source_digests: { checkpoint: { ref: checkpointRef, digest: checkpoint.digest }, registry: { ref: registryRef, digest: registry.digest }, orchestration: { ref: contractRef, digest: contract.digest }, ...(taskSource?{task:{ref:taskPackageRef,digest:taskSource.digest}}:{}), ...(contractSource?{slice_contract:{ref:task.contract.slice_contract_ref,digest:contractSource.digest}}:{}) },
   };
 }

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

@@ -1,3 +1,6 @@
+import { assertBusinessApprovalBasis } from './business-ticket-lifecycle.mjs';
+import { assertBusinessTicketTransition, assertImplementationTicket } from './business-tickets.mjs';
+import {assertReadingTransition} from './reading-view-bundle.mjs';
 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.
@@ -14,6 +17,8 @@ import { loadApprovalRecord, validateApprovalRecord } from "./approval-record.mj
 import { validateBackendReview } from "./backend-review.mjs";
 import { validateJsonSchema } from "./json-schema.mjs";
 import { ROOT } from "./lifecycle-registry.mjs";
+import { readRepositoryMode } from './repository-mode.mjs';
+import { validateResearchCompletion } from './maintenance-research.mjs';
 
 const IMPLEMENTATION_WORK_UNIT = "work-unit.slice-implementation";
 const TICKET_DECOMPOSITION_WORK_UNIT = "work-unit.ticket-decomposition";
@@ -28,6 +33,7 @@ function deepFreeze(value) {
 }
 
 const NEXT_ROUTES = deepFreeze({
+  "work-unit.maintenance-research": ["work-unit.ssot-update"],
   "work-unit.entry-triage": ["work-unit.plan-opportunity", "work-unit.plan-requirements"],
   "work-unit.ssot-update": ["work-unit.skill-projection-sync", "work-unit.intensity-aware-verification-v2"],
   "work-unit.skill-projection-sync": ["work-unit.template-snapshot-build", "work-unit.intensity-aware-verification-v2"],
@@ -40,8 +46,9 @@ const NEXT_ROUTES = deepFreeze({
   "work-unit.plan-requirements": ["work-unit.domain-strategy-design", "work-unit.stage-decision", "work-unit.spec-synthesis"],
   "work-unit.domain-strategy-design": ["work-unit.stage-decision", "work-unit.spec-synthesis"],
   "work-unit.stage-decision": ["work-unit.spec-synthesis"],
-  "work-unit.spec-synthesis": ["work-unit.prototype-design-v2", "work-unit.technical-analysis"],
-  "work-unit.prototype-design-v2": ["work-unit.technical-analysis"],
+  "work-unit.spec-synthesis": ["work-unit.prototype-design-v2", "work-unit.business-ticket-formalization", "work-unit.technical-analysis"],
+  "work-unit.prototype-design-v2": ["work-unit.business-ticket-formalization", "work-unit.technical-analysis"],
+  "work-unit.business-ticket-formalization": ["work-unit.technical-analysis"],
   "work-unit.technical-analysis": [REPOSITORY_PREPARATION_WORK_UNIT],
   [REPOSITORY_PREPARATION_WORK_UNIT]: [SERVICE_INITIALIZATION_WORK_UNIT, TICKET_DECOMPOSITION_WORK_UNIT],
   [SERVICE_INITIALIZATION_WORK_UNIT]: [REPOSITORY_PREPARATION_WORK_UNIT],
@@ -303,6 +310,25 @@ function validateTicketReference(ref, trackerKind) {
  * by `validateWorkflowExecutionResult` before this function is called.
  */
 export function validateNextRoute(currentWorkUnit, nextRoute, decisionState, options = {}) {
+  let entryRoutes;
+  if (currentWorkUnit === 'work-unit.entry-triage' || currentWorkUnit === 'work-unit.maintenance-research' || nextRoute === 'work-unit.maintenance-research') {
+    try {
+      const mode = readRepositoryMode(options.root || ROOT);
+      if (currentWorkUnit === 'work-unit.entry-triage') entryRoutes = mode === 'template-source'
+        ? ['work-unit.maintenance-research', 'work-unit.ssot-update'] : NEXT_ROUTES[currentWorkUnit];
+      if ((currentWorkUnit === 'work-unit.maintenance-research' || nextRoute === 'work-unit.maintenance-research') && mode !== 'template-source') throw Error('template-research-requires-template-source');
+      if (currentWorkUnit === 'work-unit.maintenance-research') {
+        assertScopeTransition(currentWorkUnit, nextRoute, decisionState, options);
+        if (nextRoute !== null && nextRoute !== 'work-unit.ssot-update') return blockedResult([BLOCKING_SIGNALS.invalidRoute]);
+        validateResearchCompletion(decisionState, {root: options.root || ROOT, continuing: nextRoute !== null});
+        return allowedResult(decisionState.evidence_refs);
+      }
+    } catch (error) { return blockedResult(['maintenance-research-boundary'], [error.message]); }
+  }
+  try { assertBusinessTicketTransition(options.root || ROOT, currentWorkUnit, nextRoute, decisionState); assertBusinessApprovalBasis(options.root || ROOT, decisionState, {required:currentWorkUnit === 'work-unit.business-ticket-formalization'}); }
+  catch(error) { return blockedResult(["business-ticket-blocked"],[error.message]); }
+  try { assertReadingTransition(options.root || ROOT, decisionState, currentWorkUnit); }
+  catch(error){ return blockedResult(['reading-views-stale'],[error.message]); }
   try { assertTrackingTransition(currentWorkUnit, nextRoute, decisionState, { root: options.root || ROOT }); }
   catch (error) { return blockedResult(['stage-tracking-blocked'], [error.message]); }
   try { assertScopeTransition(currentWorkUnit, nextRoute, decisionState, options); }
@@ -320,7 +346,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] && scopedNextRoutes(currentWorkUnit, NEXT_ROUTES[currentWorkUnit], options);
+  const routes = NEXT_ROUTES[currentWorkUnit] && scopedNextRoutes(currentWorkUnit, entryRoutes || NEXT_ROUTES[currentWorkUnit], options);
   if (!routes) return blockedResult([BLOCKING_SIGNALS.invalidRoute], ["known_current_work_unit"]);
   if (nextRoute === REPOSITORY_PREPARATION_WORK_UNIT && !["work-unit.technical-analysis", SERVICE_INITIALIZATION_WORK_UNIT].includes(currentWorkUnit)) {
     return blockedResult([BLOCKING_SIGNALS.technicalAnalysisRequired], ["work-unit.technical-analysis predecessor"]);
@@ -483,10 +509,11 @@ function validateDecisionBoundary(workUnit, state, options) {
 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 {
+      assertImplementationTicket(read(state.vertical_slice_ticket.ref),state.vertical_slice_ticket.ref);
       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"]); }
+    } catch(error) { return blockedResult([error.message.includes("stage-work-item")?"stage-work-item-not-implementable":error.message.includes("business-ticket")?"business-ticket-not-implementable":"ticket-content-unreadable"], [error.message]); }
   }
   try { enforceFrontendDelivery(state, { root: decisionOptions.root, phase: "implementation" }); }
   catch (error) { return blockedResult(["frontend-delivery-blocked"], [error.message]); }

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

@@ -0,0 +1,63 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {spawnSync} from 'node:child_process';
+import {safe, hash, parse, ensure} from './strategic-handoff-io.mjs';
+import {assertUserDecisionRequirement} from './user-decision.mjs';
+
+export const RESEARCH_VALIDATOR = '.agents/skills/yss-research/scripts/validate-research-package.mjs';
+const binding = (root, ref) => ({ref, digest: hash(fs.readFileSync(safe(root, ref)))});
+function readBound(root, bound) {
+  ensure(bound && binding(root, bound.ref).digest === bound.digest, 'research-evidence-stale');
+  return fs.readFileSync(safe(root, bound.ref));
+}
+function execute(root, brief, evidence) {
+  return spawnSync(process.execPath, [safe(root, RESEARCH_VALIDATOR), safe(root, brief), safe(root, evidence)], {
+    cwd: root, encoding: 'utf8', timeout: 30000, maxBuffer: 2 * 1024 * 1024,
+    env: {...process.env, NODE_OPTIONS: '', NODE_PATH: ''},
+  });
+}
+
+/** Capture actual validator output; never overwrite a historical run. */
+export function recordResearchVerification(root, brief, evidence, output) {
+  const inputs = {brief: binding(root, brief), evidence: binding(root, evidence), validator: binding(root, RESEARCH_VALIDATOR)};
+  const dir = safe(root, output, {missing: true});
+  ensure(!fs.existsSync(dir), '研究验证输出目录必须不存在');
+  const started_at = new Date().toISOString(), result = execute(root, brief, evidence);
+  fs.mkdirSync(dir, {recursive: true});
+  fs.writeFileSync(path.join(dir, 'stdout.log'), result.stdout || '');
+  fs.writeFileSync(path.join(dir, 'stderr.log'), result.stderr || result.error?.message || '');
+  const record = {schema_version: 1, kind: 'maintenance-research-verification', inputs,
+    command: ['node', RESEARCH_VALIDATOR, brief, evidence], started_at, completed_at: new Date().toISOString(),
+    exit_code: result.status, stdout: binding(root, `${output}/stdout.log`), stderr: binding(root, `${output}/stderr.log`)};
+  for (const value of Object.values(inputs)) readBound(root, value);
+  fs.writeFileSync(path.join(dir, 'verification.json'), JSON.stringify(record, null, 2) + '\n');
+  return {binding: binding(root, `${output}/verification.json`), exit_code: result.status};
+}
+
+export function validateResearchCompletion(state, {root, continuing = false}) {
+  ensure(state?.context_reconciliation?.status === 'not-applicable' && state.context_reconciliation.reason?.trim(), 'research-context-reason-missing');
+  fs.readFileSync(safe(root, state.context_reconciliation.ref));
+  for (const key of ['blocking_signals', 'drift', 'violation', 'new_impacts', 'stale_candidates']) {
+    ensure(Array.isArray(state[key]) && state[key].length === 0, `research-${key}-unresolved`);
+  }
+  const record = parse(readBound(root, state.research_verification));
+  ensure(record.schema_version === 1 && record.kind === 'maintenance-research-verification', 'research-verification-invalid');
+  for (const key of ['brief', 'evidence', 'validator']) readBound(root, record.inputs?.[key]);
+  ensure(record.inputs.validator.ref === RESEARCH_VALIDATOR, 'research-validator-mismatch');
+  ensure(record.exit_code === 0 && Number.isFinite(Date.parse(record.started_at)) && Date.parse(record.completed_at) >= Date.parse(record.started_at), 'research-verification-not-passed');
+  ensure(JSON.stringify(record.command) === JSON.stringify(['node', RESEARCH_VALIDATOR, record.inputs.brief.ref, record.inputs.evidence.ref]), 'research-command-mismatch');
+  readBound(root, record.stdout); readBound(root, record.stderr);
+  for (const ref of [state.context_reconciliation.ref, state.research_verification.ref, record.inputs.brief.ref, record.inputs.evidence.ref]) {
+    ensure(state.evidence_refs?.includes(ref), `research-evidence-unreferenced: ${ref}`);
+  }
+  const current = execute(root, record.inputs.brief.ref, record.inputs.evidence.ref);
+  ensure(!current.error && current.status === 0, 'research-current-validation-failed');
+  readBound(root, state.research_verification);
+  for(const value of Object.values(record.inputs))readBound(root,value);
+  if (continuing) {
+    const authorization = parse(readBound(root, state.maintenance_authorization));
+    ensure(authorization.boundary === 'template-maintenance-scope' && authorization.scope?.includes('work-unit.ssot-update'), 'maintenance-authorization-required');
+    assertUserDecisionRequirement(authorization, {root});
+  }
+  return record;
+}

package/template/scripts/lib/plan-spec-markdown.mjs

@@ -0,0 +1,97 @@
+import { parseMarkdown } from '../vendor/markdown.mjs';
+import { parseDocument } from '../vendor/yaml.mjs';
+
+export const PROFILE = 'plan-spec-v1';
+export const ID_PATTERN = /^(?:FR|NFR|AC|Q|SC)-[A-Za-z0-9][A-Za-z0-9._-]*$|^success-criterion\.[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const sectionKinds = new Map([
+  ['功能需求', 'FR'], ['Functional Requirements', 'FR'],
+  ['非功能需求', 'NFR'], ['Non-functional Requirements', 'NFR'],
+  ['验收标准', 'AC'], ['Acceptance Criteria', 'AC'],
+  ['未决项', 'Q'], ['Open Questions', 'Q'], ['成功标准', 'SC']
+]);
+export const requiredFields = {
+  FR: ['需求', '优先级', '来源引用', '验收引用', '未决项'],
+  NFR: ['需求', '适用条件/负载', '指标及单位', '目标', '确认状态', '验证方法', '来源引用', '验收引用', '未决项'],
+  AC: ['需求引用', '前提', '触发', '可观察结果', '场景类型', '未决项'],
+  Q: ['问题', '判断依据', '责任人', '解决时点', '接收方 / 解决证据'],
+  SC: ['指标定义', '基线或未知原因', '目标', '确认状态', '观测窗口', '数据来源', '验证方式', '未决项']
+};
+export function plain(node) {
+  if (node.value !== undefined) return node.value;
+  return (node.children ?? []).map(plain).join('');
+}
+export function ids(value, kinds = ['FR', 'NFR', 'AC', 'Q', 'SC']) {
+  return [...new Set((value ?? '').match(/\b(?:FR|NFR|AC|Q|SC)-[A-Za-z0-9][A-Za-z0-9._-]*\b/g) ?? [])].filter(id => kinds.includes(id.split('-')[0]));
+}
+export function yamlValue(text) {
+  const doc = parseDocument(text, { uniqueKeys: true });
+  if (doc.errors.length) throw new Error(doc.errors.map(e => e.message).join('; '));
+  return doc.toJS({ maxAliasCount: 0 });
+}
+export function parseContent(text, file) {
+  let frontmatter = {}, body = text;
+  if (/^\uFEFF?---\r?\n/.test(text)) {
+    const match = text.match(/^\uFEFF?---\r?\n([\s\S]*?)\r?\n(?:---|\.\.\.)(?:\r?\n|$)/);
+    if (!match) throw new Error('frontmatter 未闭合');
+    frontmatter = yamlValue(match[1]);
+    if (!frontmatter || Array.isArray(frontmatter) || typeof frontmatter !== 'object') throw new Error('frontmatter 必须为 mapping');
+    body = match[0].replace(/[^\r\n]/g, ' ') + text.slice(match[0].length);
+  }
+  const tree = parseMarkdown(body), entries = [], sections = [], locators = [], headings = [], conditions = [];
+  let section = null, exampleDepth = null;
+  for (const node of tree.children) {
+    if (node.type === 'heading') {
+      const title = plain(node).trim();
+      if (exampleDepth !== null && node.depth <= exampleDepth) exampleDepth = null;
+      if (/示例|虚构|example/i.test(title)) exampleDepth = node.depth;
+      if (exampleDepth !== null) { section = null; continue; }
+      headings.push({ value: title, position: node.position });
+      const kind = sectionKinds.get(title.replace(/^\d+[.、]\s*/, ''));
+      if (kind) {
+        section = { kind, position: node.position, count: 0, depth: node.depth, text: '' };
+        sections.push(section);
+      } else if (section && node.depth <= section.depth) section = null;
+      continue;
+    }
+    if (exampleDepth !== null) continue;
+    // Root tables only: quoted, fenced and nested examples are not requirements.
+    if (node.type === 'paragraph') {
+      conditions.push({ value: plain(node).trim(), position: node.position });
+      if (section) section.text += `${plain(node)}\n`;
+    }
+    if (node.type !== 'table') continue;
+    const headers = node.children[0].children.map(cell => plain(cell).trim());
+    for (const row of node.children.slice(1)) {
+      const values = row.children.map(cell => plain(cell).trim());
+      row.children.forEach((cell, index) => conditions.push({ value: values[index], position: cell.position, id: values[0] }));
+      if (values[0]) locators.push({ value: values[0], position: row.position });
+      if (!section || headers[0] !== 'ID') continue;
+      const cells = Object.fromEntries(headers.map((header, i) => [header, {
+        text: values[i] ?? '',
+        raw: row.children[i]?.children.length ? text.slice(row.children[i].children[0].position.start.offset, row.children[i].children.at(-1).position.end.offset).trim() : '',
+        position: row.children[i]?.position ?? row.position
+      }]));
+      section.count++;
+      entries.push({ id: values[0] ?? '', kind: section.kind, fields: Object.fromEntries(headers.map((header, i) => [header, values[i] ?? ''])), cells, file, position: row.position });
+    }
+  }
+  return { file, frontmatter, supported: frontmatter.content_profile === PROFILE, entries, sections, headings, locators, conditions };
+}
+
+// Explicit references only; paths here are relative to --root, never discovered by scanning.
+export function sourceRefs(value) {
+  if (!value?.trim()) return [];
+  return value.split(/\s*[;；]\s*/).map(part => {
+    const explicit = part.match(/^`?(.+?)`?\s*::\s*(id|heading):(.+)$/);
+    if (explicit) return { path: explicit[1].replace(/^`|`$/g, '').trim(), type: explicit[2], locator: explicit[3].replace(/^`|`$/g, '').trim() };
+    const link = part.match(/^\[([^\]]+)\]\(([^\s)]+)\)$/);
+    if (link) {
+      const [target, ...fragment] = link[2].split('#');
+      let locator;
+      try { locator = decodeURIComponent(fragment.join('#') || link[1]); } catch { return { invalid: part }; }
+      const kind = locator.startsWith('heading:') ? 'heading' : 'id';
+      return { path: target, type: kind, locator: locator.replace(/^(?:id|heading):/, '') };
+    }
+    return { invalid: part };
+  });
+}