create-yss-spec 3.5.3 → 3.5.5

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

@@ -1,8 +1,12 @@
+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';
 import { parseDocument } from '../vendor/yaml.mjs';
 import { safeTrackingPath, trackingDrift } from './stage-tracking.mjs';
+import { loadLifecyclePresenter } from './lifecycle-presentation.mjs';
 
 const sha = bytes => `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
 function parse(bytes) {
@@ -22,7 +26,7 @@ export function lifecycleStatus({ root, checkpointRef, taskPackageRef }) {
   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 身份或版本无效');
@@ -49,7 +53,7 @@ export function lifecycleStatus({ root, checkpointRef, taskPackageRef }) {
   if (value.next_work_unit && !workUnit) issue('unknown-work-unit', `未知下一工作单元: ${value.next_work_unit}`, registryRef, '按注册表核对下一工作单元');
   if (workUnit && workUnit.id !== 'work-unit.entry-triage' && !contract.value.work_unit_routes?.[workUnit.id]) issue('missing-route', `缺少执行路由: ${workUnit.id}`, contractRef, '修复当前合同路由后重验');
   check('stage-and-route', diagnostics.some(x => ['unknown-stage', 'unknown-work-unit', 'missing-route'].includes(x.code)) ? 'failed' : 'passed', [registryRef, contractRef], '仅检查身份与路由存在，不计算完整 frontier');
-  if (value.context_reconciliation?.status === 'blocked') issue('context-blocked', 'Context reconciliation blocked', checkpointRef, '修复词汇对账并执行适用校验');
+  if (value.context_reconciliation?.status === 'blocked') issue('context-blocked', '术语对账受阻', checkpointRef, '修复词汇对账并执行适用校验');
   check('context-reconciliation', value.context_reconciliation?.status === 'blocked' ? 'failed' : 'not-checked', [value.context_reconciliation?.ref].filter(Boolean), '读取登记状态；当前对账内容和摘要仍须由原验证器核验');
   for (const [id, gate] of Object.entries(value.gates ?? {})) {
     if (['blocked', 'stale'].includes(gate?.status)) issue('gate-blocked', `${id}: ${gate.status}`, checkpointRef, '核对受影响依据和当前批准');
@@ -102,6 +106,15 @@ export function lifecycleStatus({ root, checkpointRef, taskPackageRef }) {
       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,
@@ -128,10 +141,28 @@ export function lifecycleStatus({ root, checkpointRef, taskPackageRef }) {
     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;
+  const presenter = loadLifecyclePresenter(root);
+  const statusNames = { routing: '正在确定下一步', running: '正在推进', blocked: '受阻', 'paused-human-gate': '等待会签', completed: '记录为已完成，仍需核验' };
+  const readable = text => presenter.text(text, {trace: false}).replace(/: (blocked|stale)$/, (_, status) => status === 'blocked' ? '：受阻' : '：依据已过期，需重新核验');
+  const presentation = {
+    read_only: true, execution_allowed: false, approval_validity: 'not-checked',
+    stage: value.stage ? presenter.label(value.stage, {trace: false}) : '未登记',
+    checkpoint_status: Object.hasOwn(statusNames, value.status) ? statusNames[value.status] : `未识别状态（${value.status ?? '未登记'}）`,
+    work_unit: value.next_work_unit ? presenter.label(value.next_work_unit, {trace: false}) : '未登记',
+    owner: presenter.text(owner, {trace: false}), blockers: blockers.map(readable),
+    expected_output: workUnit ? readable(workUnit.public_output ?? workUnit.output ?? '产出说明未登记') : null,
+    next_action: readable(next_action), sources: presenter.sources, warnings: presenter.warnings,
+    names: presenter.catalog({stage: value.stage, work_unit: value.next_work_unit, owner, gates: value.gates, artifacts: value.artifacts}),
+  };
   return {
+    presentation,
+    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, 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.
@@ -43,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],
@@ -321,6 +325,10 @@ export function validateNextRoute(currentWorkUnit, nextRoute, decisionState, opt
       }
     } 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); }
@@ -501,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/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 };
+  });
+}

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

@@ -0,0 +1,289 @@
+import { readFile, realpath, stat } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { PROFILE, ID_PATTERN, requiredFields, ids, parseContent, sourceRefs, yamlValue } from './plan-spec-markdown.mjs';
+
+export const TOOL_VERSION = '1.0.0';
+const digest = bytes => `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+const noValue = value => !value || /^(?:[-—]|TBD|TODO|待填写|<[^>]*>)$/i.test(value.trim());
+const placeholder = value => /<[^>\n]+>|\b(?:TODO|TBD)\b|待填写/.test(value);
+const unknown = value => /未知|待确认|待定|unknown|TBD/i.test(value ?? '');
+const notApplicable = value => /^(?:not-applicable|不适用|N\/A)(?:\s|[：:]|$)/i.test(value ?? '');
+const naReason = value => /^(?:not-applicable|不适用|N\/A)\s*[：:]\s*\S.+/i.test(value ?? '') && !placeholder(value);
+const field = (entry, name) => entry.fields[name] ?? '';
+const location = (file, position) => ({ file, line: position?.start?.line ?? 1, column: position?.start?.column ?? 1 });
+
+export async function inspectPlanSpec(options, hooks = {}) {
+  const report = {
+    tool: 'inspect-plan-spec', tool_version: TOOL_VERSION, content_profile: PROFILE,
+    mode: options.command, diagnostic_only: true, execution: 'completed', inputs: [],
+    scope: { documents: [], sources: ['来源引用', '数据来源', '权威引用'], slices: options.slices ?? [], network: '不读取', state_changes: '无', prose: '正文语义未自动评估，需保留全文人工审阅' },
+    findings: [], unevaluated: [], manual_review: [
+      '问题真实性、方案优劣、目标合理性、场景充分性和规则语义等价性需人工审查。',
+      '诊断不改变生命周期批准、就绪状态或验证范围。'
+    ]
+  };
+  const cache = new Map(), parsed = new Map();
+  let root;
+  function issue(code, file, position, item_id, message, recovery, incomplete = false) {
+    report.findings.push({ code, location: location(file, position), item_id: item_id || null, message, recovery });
+    if (incomplete) report.execution = 'incomplete';
+  }
+  function unassessed(code, file, message, item_id = null, position = null) {
+    report.unevaluated.push({ code, location: location(file, position), item_id, message, recovery: '人工审阅原文；按需明确选择范围并补齐可定位输入后重跑。' });
+  }
+  try { root = await realpath(path.resolve(options.root ?? '.')); }
+  catch (error) { issue('INPUT_ROOT', options.root ?? '.', null, null, error.message, '提供可读项目根目录。', true); }
+  function target(ref) {
+    const absolute = path.resolve(root, ref), relative = path.relative(root, absolute);
+    if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) throw new Error('路径越过项目根目录');
+    return { absolute, relative: relative.replaceAll(path.sep, '/') };
+  }
+  async function load(ref, role, caller = {}) {
+    if (!root) return null;
+    try {
+      const { absolute, relative } = target(ref);
+      if (cache.has(relative)) { cache.get(relative).roles.add(role); return cache.get(relative); }
+      const resolved = await realpath(absolute);
+      target(resolved);
+      const info = await stat(absolute);
+      if (!info.isFile()) throw new Error('输入不是普通文件');
+      if (info.size > 8 * 1024 * 1024) throw new Error('输入超过 8 MiB，需显式提供较小快照');
+      const bytes = await readFile(absolute);
+      const text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+      const item = { absolute, resolved, file: relative, bytes, text, sha256: digest(bytes), roles: new Set([role]) };
+      cache.set(relative, item);
+      return item;
+    } catch (error) {
+      issue('INPUT_UNREADABLE', caller.file ?? ref, caller.position, caller.id, `无法读取 ${ref}: ${error.message}`, '补齐或修正显式输入路径；不得猜测替代来源。', true);
+      return null;
+    }
+  }
+  function markdown(input) {
+    if (!input) return null;
+    if (parsed.has(input.file)) return parsed.get(input.file);
+    try { const doc = parseContent(input.text, input.file); parsed.set(input.file, doc); return doc; }
+    catch (error) {
+      issue('PARSE_ERROR', input.file, null, null, error.message, '修复 Markdown frontmatter / YAML 解析问题后重跑。', true);
+      parsed.set(input.file, null); return null;
+    }
+  }
+  async function resolveSource(reference, entry, name) {
+    if (reference.invalid) {
+      issue('SOURCE_FORMAT', entry.file, entry.cells[name]?.position ?? entry.position, entry.id, `来源缺少可定位表达：${reference.invalid}`, '使用 项目根相对路径 :: id:已有ID 或 :: heading:准确章节名。'); return null;
+    }
+    if (/^[a-z][a-z0-9+.-]*:/i.test(reference.path)) {
+      unassessed('EXTERNAL_SOURCE', entry.file, `未联网读取外部来源 ${reference.path}；需要可审阅的本地证据快照。`, entry.id); return null;
+    }
+    const input = await load(reference.path, 'source', entry);
+    if (!input) return null;
+    let matches;
+    try {
+      if (/\.(?:ya?ml|json)$/i.test(input.file)) {
+        const value = /\.json$/i.test(input.file) ? JSON.parse(input.text) : yamlValue(input.text);
+        matches = [];
+        const walk = node => {
+          if (!node || typeof node !== 'object') return;
+          if (node.id === reference.locator && reference.type === 'id') matches.push(node);
+          for (const [key, child] of Object.entries(node)) {
+            if (key === reference.locator && reference.type === 'id') matches.push(child);
+            walk(child);
+          }
+        };
+        walk(value);
+      } else if (/\.md$/i.test(input.file)) {
+        const doc = markdown(input);
+        if (!doc) return null;
+        matches = (reference.type === 'heading' ? doc.headings : doc.locators).filter(x => x.value === reference.locator);
+      } else { unassessed('SOURCE_FORMAT_UNSUPPORTED', input.file, '来源格式不支持条目定位，只绑定原始摘要。', entry.id); return null; }
+    } catch (error) {
+      issue('PARSE_ERROR', input.file, null, entry.id, error.message, '修复显式来源解析后重跑。', true); return null;
+    }
+    if (matches.length !== 1) {
+      issue('SOURCE_LOCATOR', entry.file, entry.cells[name]?.position ?? entry.position, entry.id, `来源 ${input.file} 的 ${reference.type}:${reference.locator} 匹配 ${matches.length} 处`, '修正已有条目 ID 或准确章节名；歧义定位不能自动选择。'); return null;
+    }
+    return { file: input.file, type: reference.type, locator: reference.locator, sha256: input.sha256 };
+  }
+  async function checkDocument(input, role) {
+    const doc = markdown(input);
+    if (!doc) return null;
+    report.scope.documents.push({ file: input.file, role, profile: doc.frontmatter.content_profile ?? null, extracted_items: doc.entries.length });
+    if (!doc.supported) unassessed('LEGACY_OR_UNKNOWN_PROFILE', input.file, '未声明支持的 content_profile；仅尽力检查已识别 ID 与显式引用，缺字段不解释为缺陷或内容合格。');
+    if (doc.supported) for (const condition of doc.conditions) {
+      if (notApplicable(condition.value) && !naReason(condition.value)) issue('NA_REASON', input.file, condition.position, condition.id, '条件项声明不适用但缺少原因', '补充 not-applicable：具体原因。');
+    }
+    const groups = new Map();
+    for (const entry of doc.entries) {
+      const group = groups.get(entry.id) ?? []; group.push(entry); groups.set(entry.id, group);
+      if (!ID_PATTERN.test(entry.id) || !(entry.id.startsWith(`${entry.kind}-`) || entry.kind === 'SC' && entry.id.startsWith('success-criterion.'))) {
+        if (doc.supported) issue('INVALID_ID', entry.file, entry.position, entry.id, 'ID 与所属条目类型不一致或尚未填写。', '使用功能内稳定 ID，重排不改号，删除不复用。');
+      }
+      if (!doc.supported) continue;
+      const required = entry.kind === 'SC' && '权威引用' in entry.fields ? ['权威引用'] : requiredFields[entry.kind];
+      for (const name of required) {
+        const value = field(entry, name);
+        if (noValue(value)) issue('REQUIRED_FIELD', entry.file, entry.cells[name]?.position ?? entry.position, entry.id, `${name} 为空或占位符`, '填写已有依据；未知值关联未决项及补齐动作。');
+        else if (placeholder(value)) issue('PLACEHOLDER', entry.file, entry.cells[name]?.position, entry.id, `${name} 尚有占位符`, '替换为真实输入或明确未决项。');
+      }
+      if ((entry.kind === 'NFR' || entry.kind === 'SC') && !('权威引用' in entry.fields)) {
+        if (unknown(field(entry, '目标')) && !ids(field(entry, '未决项'), ['Q']).length) issue('UNKNOWN_TARGET', entry.file, entry.position, entry.id, '目标未知且未关联未决项', '关联 Q ID，保留候选状态、负责人和补齐动作。');
+        if (unknown(field(entry, '目标')) && field(entry, '确认状态') === '已确认') issue('TARGET_STATUS', entry.file, entry.position, entry.id, '未知目标标记为已确认', '核对真实决定；未知目标保持候选状态。');
+        if (entry.kind === 'SC' && unknown(field(entry, '基线或未知原因')) && !ids(field(entry, '未决项'), ['Q']).length) issue('UNKNOWN_BASELINE', entry.file, entry.position, entry.id, '基线未知且没有补齐项', '关联 Q ID，说明未知原因、负责人和补齐动作。');
+      }
+    }
+    for (const [id, entries] of groups) if (entries.length > 1) for (const entry of entries) issue('DUPLICATE_ID', entry.file, entry.position, id, `ID 重复 ${entries.length} 次`, '消除重复并修复所有关联；不要因排序重编号。');
+    if (doc.supported) {
+      for (const kind of role === 'spec' ? ['FR', 'NFR', 'AC'] : ['SC']) {
+        if (!doc.sections.some(section => section.kind === kind)) issue('SECTION_MISSING', input.file, null, null, `${kind} 缺少可识别章节`, '使用权威模板；未命中条件项注明不适用及原因。');
+      }
+      for (const section of doc.sections) if (!section.count && section.kind !== 'Q') {
+        if (notApplicable(section.text.trim())) {
+          // The paragraph-level condition check records missing reasons once.
+        } else {
+          issue('SECTION_UNPARSED', input.file, section.position, null, `${section.kind} 未提取到 ID 表`, '使用权威模板中的 ID 表，或为条件项明确不适用原因。');
+          unassessed('SECTION_UNPARSED', input.file, `${section.kind} 正文未进行结构诊断。`);
+        }
+      }
+    }
+    for (const entry of doc.entries) {
+      const refFields = { '验收引用': ['AC', 'Q'], '需求引用': ['FR', 'NFR'], '未决项': ['Q'] };
+      for (const [name, allowed] of Object.entries(refFields)) {
+        const refs = ids(field(entry, name));
+        for (const id of refs) {
+          if (!allowed.includes(id.split('-')[0])) issue('REFERENCE_KIND', entry.file, entry.cells[name]?.position, entry.id, `${name} 引用了不支持的类型 ${id}`, '修正字段中的关联类型。');
+          else if (!groups.has(id)) issue('DANGLING_REFERENCE', entry.file, entry.cells[name]?.position, entry.id, `${name} 指向不存在的 ${id}`, '恢复条目或修正引用；不得猜测映射。');
+          else if (groups.get(id).length > 1) unassessed('AMBIGUOUS_REFERENCE', entry.file, `引用 ${id} 重复，无法唯一追溯。`, entry.id);
+        }
+      }
+      if (['FR', 'NFR'].includes(entry.kind)) {
+        const ac = ids(field(entry, '验收引用'), ['AC']);
+        const pending = ids(field(entry, '验收引用'), ['Q']);
+        if (!ac.length && !pending.length && (doc.supported || '验收引用' in entry.fields)) issue('AC_MISSING', entry.file, entry.position, entry.id, '需求没有验收引用或明确待补项', '关联 AC 或待补 Q，并由原有门禁处理未决项。');
+        if (pending.length) unassessed('AC_DEFERRED', entry.file, `验收待补 ${pending.join(', ')}，尚未评估验收覆盖。`, entry.id);
+        for (const id of ac) {
+          const targetEntry = groups.get(id)?.length === 1 ? groups.get(id)[0] : null;
+          if (targetEntry && !ids(field(targetEntry, '需求引用')).includes(entry.id)) issue('REFERENCE_MISMATCH', entry.file, entry.position, entry.id, `${id} 没有反向关联本需求`, '核对需求与验收引用并同时修正。');
+        }
+      }
+      if (entry.kind === 'AC') {
+        const requirements = ids(field(entry, '需求引用'), ['FR', 'NFR']);
+        if (!requirements.length && (doc.supported || '需求引用' in entry.fields)) issue('REQUIREMENT_MISSING', entry.file, entry.position, entry.id, '验收缺少需求来源', '关联已有 FR/NFR，不由验收示例反推新规则。');
+        for (const id of requirements) {
+          const requirement = groups.get(id)?.length === 1 ? groups.get(id)[0] : null;
+          if (requirement && !ids(field(requirement, '验收引用')).includes(entry.id)) issue('REFERENCE_MISMATCH', entry.file, entry.position, entry.id, `${id} 未引用本验收`, '核对双向关联。');
+        }
+      }
+      for (const name of ['来源引用', '数据来源', '权威引用']) {
+        if (!(name in entry.fields)) continue;
+        const value = entry.cells[name].raw;
+        if (noValue(field(entry, name)) || placeholder(field(entry, name))) continue;
+        for (const ref of sourceRefs(value)) await resolveSource(ref, entry, name);
+        if (name === '权威引用') unassessed('STATEMENT_MANUAL_REVIEW', entry.file, '成功标准复用权威 statement；指标、窗口、未知原因等语义完整性由人工逐项审查。', entry.id);
+      }
+    }
+    return doc;
+  }
+  async function trace(doc) {
+    if (!doc) return;
+    const requirements = doc.entries.filter(e => ['FR', 'NFR'].includes(e.kind));
+    const acs = new Map(doc.entries.filter(e => e.kind === 'AC').map(e => [e.id, e]));
+    report.trace = { links: [], gaps: [], scope: '仅显式 --slice；未提供的依赖未知，不推断未受影响' };
+    for (const ref of options.slices ?? []) {
+      const input = await load(ref, 'slice'); if (!input) continue;
+      let slice;
+      try { slice = yamlValue(input.text); }
+      catch (error) { issue('PARSE_ERROR', input.file, null, null, error.message, '修复显式 Slice YAML 解析问题后重跑。', true); continue; }
+      if (slice?.schema_version !== 3 || !slice.acceptance || typeof slice.acceptance !== 'object' || Array.isArray(slice.acceptance)) {
+        unassessed('SLICE_UNSUPPORTED', input.file, '仅支持现有 Slice schema v3 acceptance mapping'); continue;
+      }
+      for (const [id, acceptance] of Object.entries(slice.acceptance)) {
+        if (!acceptance || typeof acceptance.source !== 'string' || typeof acceptance.locator !== 'string') { unassessed('SLICE_LOCATOR_UNSUPPORTED', input.file, `acceptance ${id} 结构不支持。`); continue; }
+        const locator = acceptance.locator.replace(/^id:/, '');
+        const resolved = await resolveSource({ path: acceptance.source, type: 'id', locator }, { file: input.file, id, cells: {} }, 'source');
+        if (!resolved || resolved.file !== doc.file || !acs.has(locator)) { report.trace.gaps.push({ slice: input.file, acceptance: id, reason: '定位未映射到本次 Spec 的 AC，影响未知' }); continue; }
+        if (doc.entries.filter(e => e.id === locator).length !== 1) { report.trace.gaps.push({ slice: input.file, acceptance: id, reason: 'Spec ID 重复，无法映射' }); continue; }
+        const referring = collection => Object.entries(collection ?? {}).filter(([, item]) => Array.isArray(item?.acceptance_refs) && item.acceptance_refs.includes(id));
+        report.trace.links.push({ spec: doc.file, ac: locator, requirements: ids(field(acs.get(locator), '需求引用'), ['FR', 'NFR']), slice: input.file, acceptance: id,
+          verification: referring(slice.verification).map(([key, value]) => ({ id: key, command: value.command ?? null, expected_evidence: value.expected_evidence ?? null })),
+          work_units: referring(slice.work_units).map(([key]) => key), evidence_status: '引用可见；未执行命令、未验证证据内容或批准' });
+      }
+    }
+    for (const requirement of requirements) if (!report.trace.links.some(link => link.requirements.includes(requirement.id))) report.trace.gaps.push({ requirement: requirement.id, reason: '显式输入内没有下游映射；依赖未知' });
+    for (const link of report.trace.links) if (!link.verification.length) report.trace.gaps.push({ ac: link.ac, slice: link.slice, reason: '未找到 acceptance_refs 对应的 verification' });
+  }
+  if (root && options.command === 'check') {
+    if (!options.plan && !options.spec) issue('INPUT_REQUIRED', '.', null, null, 'check 至少需要 --plan 或 --spec', '显式指定要诊断的文档。', true);
+    if (options.plan) { const input = await load(options.plan, 'plan'); if (input) await checkDocument(input, 'plan'); }
+    if (options.spec) { const input = await load(options.spec, 'spec'); if (input) await trace(await checkDocument(input, 'spec')); }
+    else if (options.slices?.length) issue('INPUT_REQUIRED', '.', null, null, '--slice 需要 --spec', '提供用于追溯的 Spec。', true);
+  } else if (root && options.command === 'diff') {
+    const before = options.before ? await load(options.before, 'before') : null;
+    const after = options.after ? await load(options.after, 'after') : null;
+    report.diff = { status: '无法比较旧内容', entries: [], raw_difference: null };
+    if (!options.before || !options.after) issue('BASELINE_MISSING', options.before ?? '.', null, null, '旧基线或新文档缺失，无法比较', '提供可读的显式 --before 和 --after。', true);
+    if (before && after) {
+      const oldDoc = markdown(before), newDoc = markdown(after);
+      let prefix = 0, suffix = 0;
+      while (prefix < Math.min(before.bytes.length, after.bytes.length) && before.bytes[prefix] === after.bytes[prefix]) prefix++;
+      while (suffix < Math.min(before.bytes.length, after.bytes.length) - prefix && before.bytes[before.bytes.length - 1 - suffix] === after.bytes[after.bytes.length - 1 - suffix]) suffix++;
+      report.diff.raw_difference = { encoding: 'base64', common_prefix_bytes: prefix, common_suffix_bytes: suffix, before_sha256: before.sha256, after_sha256: after.sha256, removed: before.bytes.subarray(prefix, before.bytes.length - suffix).toString('base64'), added: after.bytes.subarray(prefix, after.bytes.length - suffix).toString('base64') };
+      if (oldDoc && newDoc) {
+        report.diff.status = 'compared';
+        const unparsedKinds = new Set();
+        for (const [doc, role] of [[oldDoc, 'before'], [newDoc, 'after']]) {
+          report.scope.documents.push({ file: doc.file, role, profile: doc.frontmatter.content_profile ?? null, extracted_items: doc.entries.length });
+          if (!doc.supported) continue;
+          for (const kind of ['FR', 'NFR', 'AC']) if (!doc.sections.some(section => section.kind === kind)) {
+            unparsedKinds.add(kind);
+            unassessed('SECTION_MISSING', doc.file, `${kind} 缺少可识别章节；该类条目无法可靠比较增删。`);
+          }
+          for (const section of doc.sections) if (!section.count && !notApplicable(section.text.trim()) && section.kind !== 'Q') {
+            unparsedKinds.add(section.kind);
+            unassessed('SECTION_UNPARSED', doc.file, `${section.kind} 未提取到 ID 表；该类条目无法可靠比较增删。`, null, section.position);
+          }
+        }
+        if (!oldDoc.supported || !newDoc.supported || unparsedKinds.size) {
+          report.diff.status = 'partially-compared';
+          unassessed('PARTIAL_DIFF', after.file, '格式或章节存在提取缺口；只比较可识别范围，缺口不判为条目增删。原始字节差异覆盖全部内容。');
+        }
+        const allIds = [...new Set([...oldDoc.entries, ...newDoc.entries].map(e => e.id))].sort();
+        for (const id of allIds) {
+          const oldItems = oldDoc.entries.filter(e => e.id === id), newItems = newDoc.entries.filter(e => e.id === id);
+          if (oldItems.length > 1 || newItems.length > 1) { issue('DUPLICATE_ID', after.file, newItems[0]?.position, id, '差异中的 ID 不唯一，无法比较该条目', '消除歧义，保留原始字节证据。'); report.diff.entries.push({ id, change: 'unassessed' }); continue; }
+          const left = oldItems[0], right = newItems[0];
+          if (unparsedKinds.has(left?.kind) || unparsedKinds.has(right?.kind) || (!left || !right) && (!oldDoc.supported || !newDoc.supported)) {
+            report.diff.entries.push({ id, change: 'unassessed', reason: '所属章节提取不完整，不能据此判断新增或删除', location: location(right ? after.file : before.file, (right ?? left).position) });
+            continue;
+          }
+          const values = item => item && Object.fromEntries(Object.entries(item.cells).map(([key, cell]) => [key, cell.raw]));
+          const oldFields = values(left), newFields = values(right);
+          if (JSON.stringify(oldFields) === JSON.stringify(newFields)) continue;
+          const referenceChanges = ['来源引用', '验收引用', '需求引用', '未决项', '权威引用', '数据来源'].filter(key => oldFields?.[key] !== newFields?.[key]);
+          report.diff.entries.push({ id, change: !left ? 'added' : !right ? 'removed' : 'modified', before: oldFields ?? null, after: newFields ?? null, reference_changes: referenceChanges, location: location(right ? after.file : before.file, (right ?? left).position) });
+        }
+        report.diff.note = '重排无重新编号；未按 ID 展示的变化见原始字节差异。语义等价、ID 历史复用、批准与下游影响未自动判定。';
+      }
+    }
+  } else if (root) issue('COMMAND_INVALID', '.', null, null, '命令必须为 check 或 diff', '查看 --help。', true);
+  // Test hook exercises an actual read/re-read race without changing runtime CLI behavior.
+  if (hooks.beforeFreshnessCheck) await hooks.beforeFreshnessCheck();
+  for (const input of cache.values()) {
+    report.inputs.push({ file: input.file, roles: [...input.roles].sort(), bytes: input.bytes.length, sha256: input.sha256 });
+    try {
+      if (await realpath(input.absolute) !== input.resolved || digest(await readFile(input.absolute)) !== input.sha256) throw new Error('读取期间内容或真实路径变化');
+    } catch (error) { issue('INPUT_DRIFT', input.file, null, null, error.message, '冻结输入并重新运行；本报告不得作为当前证据。', true); }
+  }
+  report.inputs.sort((a, b) => a.file.localeCompare(b.file));
+  report.summary = { findings: report.findings.length, unevaluated: report.unevaluated.length, result: '诊断证据，不是内容合格或流转许可' };
+  return { report, exitCode: report.execution === 'completed' ? 0 : 2 };
+}
+
+export function renderReport(report) {
+  const lines = [`inspect-plan-spec ${report.tool_version} · ${report.mode} · ${report.execution}`, report.summary.result];
+  for (const input of report.inputs) lines.push(`输入 ${input.file} ${input.sha256}`);
+  for (const item of [...report.findings, ...report.unevaluated]) lines.push(`${item.code} ${item.location.file}:${item.location.line}:${item.location.column}${item.item_id ? ` [${item.item_id}]` : ''} ${item.message}\n  恢复：${item.recovery}`);
+  for (const item of report.manual_review) lines.push(`人工审查：${item}`);
+  if (report.diff) { lines.push(`差异：${report.diff.status}`, JSON.stringify(report.diff, null, 2)); }
+  if (report.trace) lines.push(`追溯：${JSON.stringify(report.trace, null, 2)}`);
+  return `${lines.join('\n')}\n`;
+}

package/template/scripts/lib/plan-stage-coverage.mjs

@@ -0,0 +1,40 @@
+import fs from 'node:fs';
+import { parseMarkdown } from '../vendor/markdown.mjs';
+import { plain } from './plan-spec-markdown.mjs';
+import { parseAsset, byteDigest } from './structured-assets.mjs';
+import { safeFile } from './governance-io.mjs';
+
+function tables(source) {
+  let heading='';const result=[];
+  for(const node of parseMarkdown(source).children) {
+    if(node.type==='heading')heading=plain(node);
+    if(node.type!=='table')continue;
+    const headers=node.children[0].children.map(plain);
+    for(const row of node.children.slice(1))result.push({heading,headers,cells:row.children.map(plain),line:row.position.start.line});
+  }
+  return result;
+}
+/** Coverage is deterministic; equivalence of rewritten business statements requires independent review. */
+export function planStageCoverage(root,{plan_ref,decisions_ref,package_ref,mapping_ref}) {
+  const bytes=ref=>fs.readFileSync(safeFile(root,ref));
+  const plan=bytes(plan_ref),decisions=bytes(decisions_ref),pkgBytes=bytes(package_ref),pkg=parseAsset(pkgBytes,package_ref);
+  const mapping=mapping_ref?parseAsset(bytes(mapping_ref),mapping_ref):{non_goals:[]};
+  const sourceBindings={plan:{ref:plan_ref,digest:byteDigest(plan)},decisions:{ref:decisions_ref,digest:byteDigest(decisions)}};
+  if(mapping_ref && (mapping.plan_digest!==sourceBindings.plan.digest||mapping.package_digest!==byteDigest(pkgBytes)))throw new Error('PLAN_COVERAGE_MAPPING_STALE');
+  const sourceDecisions=tables(decisions.toString()).filter(r=>/^D[0-9]+$/.test(r.cells[0])&&r.headers.includes('决定'));
+  const sourceNonGoals=tables(plan.toString()).filter(r=>r.headers.some(x=>/MVP.*非目标/.test(x))&&/^非目标/.test(r.cells[r.headers.findIndex(x=>/MVP.*非目标/.test(x))]||''));
+  if(!sourceDecisions.length||!sourceNonGoals.length)throw new Error('PLAN_COVERAGE_UNASSESSED: supported decision/non-goal tables were not found');
+  if(new Set(sourceDecisions.map(r=>r.cells[0])).size!==sourceDecisions.length)throw new Error('PLAN_COVERAGE_DUPLICATE_SOURCE_ID');
+  const rows=sourceDecisions.map(row=>{
+    const id=row.cells[0],targets=(pkg.confirmed_decisions||[]).filter(item=>new RegExp(`^decision\\.plan-${id.toLowerCase()}(?:-|$)`).test(item.id));
+    return {source_ref:decisions_ref,source_id:id,source_line:row.line,source_text:row.cells.join(' | '),targets:targets.map(x=>({id:x.id,statement:x.statement})),status:targets.length===1?'mapped':'missing-or-ambiguous',semantic_review:'required'};
+  });
+  const nonGoals=sourceNonGoals.map(row=>{
+    const sourceText=row.cells[0],entry=(mapping.non_goals||[]).find(x=>x.source_text===sourceText&&x.source_line===row.line);
+    const target=Number.isInteger(entry?.target_index)?pkg.non_goals?.[entry.target_index]:undefined;
+    return {source_ref:plan_ref,source_line:row.line,source_text:sourceText,target_index:entry?.target_index??null,target_text:target??null,status:typeof target==='string'&&target===entry.target_text?'mapped':'unmapped',semantic_review:'required'};
+  });
+  const known=new Set(sourceDecisions.map(r=>r.cells[0].toLowerCase()));
+  const undeclared=(pkg.confirmed_decisions||[]).filter(r=>/^decision\.plan-d\d+(?:-|$)/.test(r.id)&&!known.has(r.id.match(/^decision\.plan-(d\d+)/)[1])).map(r=>r.id);
+  return {schema_version:1,kind:'plan-stage-coverage',sources:sourceBindings,subject:{ref:package_ref,digest:byteDigest(pkgBytes)},...(mapping_ref?{mapping:{ref:mapping_ref,digest:byteDigest(bytes(mapping_ref))}}:{}),decisions:rows,non_goals:nonGoals,undeclared_decision_ids:undeclared,coverage_status:rows.every(r=>r.status==='mapped')&&nonGoals.every(r=>r.status==='mapped')&&!undeclared.length?'complete':'incomplete',semantic_review:'required',execution_authorization:'not-granted'};
+}