create-yss-spec 3.3.0 → 3.3.3

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

@@ -0,0 +1,88 @@
+import path from 'node:path';
+import { verifyContextReconciliation } from './context-reconciliation.mjs';
+import { decisionIO, decisionDigest, assertUserDecisionRequirement } from './user-decision.mjs';
+import { validateApprovalRecord } from './approval-record.mjs';
+
+const fail = message => { throw new TypeError(`plan-spec-entry-blocked: ${message}`); };
+const text = value => typeof value === 'string' && value.trim().length > 0;
+
+export function planEntryPolicy(options = {}) {
+  const registry = decisionIO(options).document('docs/process/lifecycle-registry.yaml');
+  const policy = registry.stages.find(stage => stage.id === 'stage.plan')?.spec_entry;
+  if (!policy?.required_checks?.length || !policy?.gate_impacts) fail('缺少 Plan 入口策略');
+  const gateIds = registry.gates.filter(gate => gate.stage === 'stage.plan').map(gate => gate.id).sort();
+  if (JSON.stringify(gateIds) !== JSON.stringify(Object.keys(policy.gate_impacts).sort())) fail('Plan 门禁触发策略覆盖不完整');
+  const checkIds = registry.checks.filter(check => check.stage === 'stage.plan').map(check => check.id).sort();
+  if (JSON.stringify(checkIds) !== JSON.stringify(Object.keys(policy.check_impacts || {}).sort())) fail('Plan 内部检查触发策略覆盖不完整');
+  return policy;
+}
+
+// 自动加载只产生 pending；持久化审阅包、证据新鲜度和真实回复共同决定放行。
+export function assertPlanSpecEntry(state, options = {}) {
+  if (!text(state?.plan_review_ref) || !text(state?.feature_id)) fail('缺少 plan_review_ref / feature_id');
+  const io = decisionIO(options);
+  const policy = planEntryPolicy(options);
+  const review = io.document(state.plan_review_ref);
+  if (review.schema_version !== 1 || review.kind !== 'plan-entry-review' || review.gate_id !== 'gate.plan-approved' || review.feature_id !== state.feature_id) fail('审阅包身份或范围不匹配');
+  if (!Array.isArray(review.basis) || !review.basis.length) fail('缺少带摘要依据');
+  const basis = new Map();
+  for (const asset of review.basis) {
+    if (!text(asset.ref) || basis.has(asset.ref) || decisionDigest(io.bytes(asset.ref)) !== asset.digest) fail(`依据缺失、重复或已变更: ${asset.ref}`);
+    basis.set(asset.ref, asset);
+  }
+  const evidence = refs => {
+    if (!Array.isArray(refs) || !refs.length || refs.some(ref => !basis.has(ref))) fail('检查项缺少当前依据');
+  };
+  for (const ref of [review.plan_ref, 'CONTEXT.md', 'docs/process/lifecycle-registry.yaml', review.context_reconciliation_ref]) {
+    if (!basis.has(ref)) fail(`必需依据未绑定: ${ref}`);
+  }
+  if (Object.keys(review.checks || {}).length !== policy.required_checks.length) fail('检查项缺失或存在未知项');
+  for (const id of policy.required_checks) {
+    const check = review.checks[id];
+    if (check?.status !== 'passed') fail(`检查未通过: ${id}`);
+    evidence(check.evidence_refs);
+  }
+  if (!Array.isArray(review.open_items)) fail('必须显式列出未决项');
+  for (const item of review.open_items) {
+    if (!text(item.id) || typeof item.critical !== 'boolean' || typeof item.runnable_blocker !== 'boolean') fail('未决项分类不完整');
+    if (item.status === 'resolved') { evidence(item.evidence_refs); continue; }
+    if (item.status !== 'deferred' || item.critical || item.runnable_blocker) fail(`关键问题或可执行阻塞未解决: ${item.id}`);
+    for (const field of ['noncritical_reason', 'owner', 'resolution_point', 'downstream_recipient']) if (!text(item[field])) fail(`延期项缺少 ${field}`);
+    evidence(item.evidence_refs);
+  }
+  for (const [gateId, impact] of Object.entries(policy.check_impacts)) {
+    if (typeof review.impacts?.[impact] !== 'boolean') fail(`未评估影响面: ${impact}`);
+    const gate = review.internal_checks?.[gateId];
+    evidence(gate?.evidence_refs);
+    if (review.impacts[impact]) {
+      if (gate.status !== 'approved' || !basis.has(gate.approval_ref) || !basis.has(gate.subject_ref)) fail(`命中门禁未批准或未绑定依据: ${gateId}`);
+      const record = io.document(gate.approval_ref);
+      if (record.gate_id !== gateId || record.subject_ref !== gate.subject_ref || !gate.approval_scope?.includes(state.feature_id) || JSON.stringify([...(gate.approval_scope || [])].sort()) !== JSON.stringify([...(record.approval_scope || [])].sort())) fail(`会签资产或范围不匹配: ${gateId}`);
+      validateApprovalRecord(record, { ...options, requireApproved: true });
+    } else if (gate.status !== 'not-applicable' || !text(gate.reason)) fail(`未命中门禁须有原因和依据: ${gateId}`);
+  }
+  // 门禁依赖不能通过将上游标成 N/A 来跳过。
+  const registry = io.document('docs/process/lifecycle-registry.yaml');
+  for (const gate of registry.checks.filter(gate => gate.stage === 'stage.plan')) {
+    if (review.internal_checks[gate.id]?.status === 'approved') {
+      for (const dependency of gate.requires_checks || []) if (review.internal_checks[dependency]?.status !== 'approved') fail(`门禁依赖未批准: ${dependency}`);
+    }
+  }
+  const reconciliation = io.document(review.context_reconciliation_ref);
+  if (reconciliation.status !== 'reconciled' || reconciliation.repository_mode !== 'project-instance') fail('Context 未调和');
+  try { verifyContextReconciliation(path.resolve(io.root, review.context_reconciliation_ref), { root: io.root }); }
+  catch (error) { fail(`Context reconciliation 验证失败: ${error.message}\n`); }
+  assertUserDecisionRequirement({ boundary: 'gate.plan-approved', subject_ref: state.plan_review_ref, scope: [state.feature_id], user_decision_ref: state.plan_user_decision_ref }, options);
+  return { result: 'allowed', blocking_signals: [], missing_requirements: [], evidence_refs: [state.plan_review_ref, ...basis.keys()], next_work_unit: null };
+}
+
+export function validatePlanSpecEntry(state, options = {}) {
+  try { return assertPlanSpecEntry(state, options); }
+  catch (error) { return { result: 'blocked', blocking_signals: ['plan-spec-entry-blocked'], missing_requirements: [error.message], evidence_refs: [], next_work_unit: null }; }
+}
+
+export function assertPlanCheckpoint(checkpoint, options = {}) {
+  if (checkpoint.repository_mode !== 'project-instance') return;
+  const entering = checkpoint.next_work_unit === 'work-unit.spec-synthesis' || checkpoint.stage === 'stage.spec-architecture' || checkpoint.stage_trace?.completed_work_unit === 'work-unit.spec-synthesis';
+  if (entering) assertPlanSpecEntry(checkpoint, options);
+}

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

@@ -236,12 +236,9 @@ export function validateSkillRegistry(registry, { lock, compilerContract, lifecy
   const roots = registry.agent_runtime_roots;
   if (!roots || typeof roots !== "object" || Array.isArray(roots)) fail("缺少 agent_runtime_roots");
   const expected = {
-    claude: ".claude/skills",
     codex: ".codex/skills",
     cursor: ".cursor/skills",
-    pi: ".pi/skills",
-    qoder: ".qoder/skills",
-    trae: ".trae/skills"
+    pi: ".pi/skills"
   };
   for (const [agent, root] of Object.entries(expected)) {
     if (roots[agent] !== root) fail(`agent_runtime_roots.${agent} 必须为 ${root}`);

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

@@ -9,7 +9,7 @@ const SOURCE_ROOT = path.join(ROOT, ".agents/skills");
 const LOCK_PATH = path.join(ROOT, "skills-lock.json");
 const YSS_UI_MANIFEST_PATH = path.join(SOURCE_ROOT, ".yss-skills-manifest.json");
 const STRATEGIC_DESIGN_MANIFEST_PATH = path.join(SOURCE_ROOT, ".strategic-design-skills-manifest.json");
-export const PROJECTION_ROOTS = [".claude/skills", ".codex/skills", ".cursor/skills", ".pi/skills", ".qoder/skills", ".trae/skills"];
+export const PROJECTION_ROOTS = [".codex/skills", ".cursor/skills", ".pi/skills"];
 export const OBSOLETE = new Set(["to-" + "prd", "to-" + "issues", "design-an-interface", "qa", "request-refactor-plan", "ubiquitous-language", "edit-article", "obsidian-vault", "writing-great-skills", "code-review-process", "yss-domain-modeling", "yss-dir", "yss-duckdb", "yss-file", "yss-filerunner", "yss-db2mybatis", "yss-mail", "yss-mapper-dynamic", "yss-quality", "yss-sql-condition", "yss-sql-tpl", "yss-valuation", "yss-variable", "yss-openapi", "web-design-engineer", "web-video-presentation", "wireframe-prototype", "wizard", "git-guardrails-claude-code", "claude-handoff", "batch-grill-me", "product-design-prototype", "research", "ask-matt", "dispatching-parallel-agents", "loop-me", "migrate-to-shoehorn", "prototype-page-acceptance", "scaffold-exercises", "setup-pre-commit", "setup-ts-deep-modules", "teach", "writing-beats", "writing-fragments", "writing-shape", "yss-microapp-commit", "yss-page-module-development", "yss-dictionary", "yss-jdbc", "yss-log", "yss-taskflow", "yss-backend-scaffold-application", "yss-backend-scaffold-domain", "yss-backend-scaffold-infrastructure", "yss-backend-scaffold-web", "yss-router", "yss-source-index"]);
 export function obsoleteCanonicalResidues(names, obsolete = OBSOLETE) {
   return names.filter((name) => obsolete.has(name)).sort();
@@ -117,7 +117,16 @@ function loadStrategicDesignSkillManifest() {
   return validateStrategicDesignSkillManifest(JSON.parse(readFileSync(STRATEGIC_DESIGN_MANIFEST_PATH, "utf8")));
 }
 function git(args) { return spawnSync("git", args, { cwd: ROOT, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }); }
-function tracked(relativePath) { return git(["ls-files", "-z", "--", relativePath]).stdout.length > 0; }
+function trackedPaths() {
+  const result = git(["ls-files", "-z"]);
+  if (result.status !== 0) throw new TypeError("无法读取 Git 受跟踪路径");
+  const paths = new Set();
+  for (const file of result.stdout.split("\0").filter(Boolean)) {
+    let ref = file;
+    while (ref !== ".") { paths.add(ref); ref = path.posix.dirname(ref); }
+  }
+  return paths;
+}
 function parseLock() { return existsSync(LOCK_PATH) ? JSON.parse(readFileSync(LOCK_PATH, "utf8")) : null; }
 function sharedFromLock(lock) {
   const shared = lock?.version === 3 && lock.skills?.shared;
@@ -137,6 +146,13 @@ export function unlockedCanonicalEntries(names, allowedNames, hasSkillMd = () =>
   return names.filter((name) => !allowed.has(name) && !OBSOLETE.has(name) && hasSkillMd(name)).sort();
 }
 export function syncSkills({ check = false } = {}) {
+  let trackedSet;
+  const tracked = ref => (trackedSet ??= trackedPaths()).has(ref);
+  const sourceHashes = new Map();
+  const sourceHash = source => {
+    if (!sourceHashes.has(source)) sourceHashes.set(source, treeHash(source));
+    return sourceHashes.get(source);
+  };
   const lock = parseLock();
   const shared = sharedFromLock(lock);
   const absent = shared.filter((name) => !lstatSafe(path.join(SOURCE_ROOT, name))?.isDirectory());
@@ -162,7 +178,7 @@ export function syncSkills({ check = false } = {}) {
         if (info?.isSymbolicLink()) {
           if (!existsSync(target) || realpathSync(target) !== realpathSync(source)) drift.push(`projection target mismatch: ${relative(target)}`);
         } else if (!info?.isDirectory()) drift.push(`missing projection: ${relative(target)}`);
-        else if (treeHash(source) !== treeHash(target)) drift.push(`projection drift: ${relative(target)}`);
+        else if (sourceHash(source) !== treeHash(target)) drift.push(`projection drift: ${relative(target)}`);
       } else if (info?.isSymbolicLink() && existsSync(target) && realpathSync(target) === realpathSync(source)) {
         continue;
       } else {
@@ -206,7 +222,7 @@ function sourceRevisionMap(oldLock, arguments_) {
 function metadata(name, skillPath, directory, previous, canonical = false, sources = {}, upstreamRoot = null) {
   const old = previous[name] ?? {};
   let recordedPath = old.skillPath ?? skillPath;
-  if (canonical && /^\.(claude|codex|cursor|pi|qoder|trae)\/skills\//.test(recordedPath)) recordedPath = skillPath;
+  if (canonical && /^\.(codex|cursor|pi)\/skills\//.test(recordedPath)) recordedPath = skillPath;
   const result = { source: old.source ?? "project", sourceType: old.sourceType ?? "local", skillPath: recordedPath, effectiveHash: treeHash(directory) };
   const sourceInfo = sources[result.source];
   if (sourceInfo?.revision) result.sourceRevision = sourceInfo.revision;

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

@@ -3,6 +3,7 @@ import { existsSync, lstatSync, readdirSync, readFileSync, mkdirSync, writeFileS
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
+import { validateJsonSchemas } from './json-schema.mjs';
 import { parseDocument } from '../vendor/yaml.mjs';
 export const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
 export const ensure = (condition, message) => { if (!condition) throw new TypeError(message); };
@@ -50,11 +51,11 @@ export function project(root) {
   ensure(value.schema_version === 1 && value.repository_mode === 'project-instance', '只允许 project-instance 导出或导入业务包');
   return realpathSync(root);
 }
-export function schema(value, ref) {
-  const program = 'import json,sys; from jsonschema import Draft202012Validator; s=json.load(open(sys.argv[1])); v=json.load(sys.stdin); errors=list(Draft202012Validator(s).iter_errors(v)); print("\\n".join(str(e) for e in errors)); sys.exit(bool(errors))';
-  const out = spawnSync('python3', ['-c', program, safe(ROOT, ref)], { input: JSON.stringify(value), encoding: 'utf8', maxBuffer: 4 * 1024 * 1024 });
-  ensure(out.status === 0, `schema 校验失败: ${out.error?.message || out.stdout || out.stderr}`);
+export function schemaBatch(items) {
+  const results = validateJsonSchemas(items.map(([value, ref]) => ({ value, schemaPath: safe(ROOT, ref), formatChecker: false, errorStyle: 'verbose' })));
+  for (const result of results) ensure(result.valid, `schema 校验失败: ${result.error}\n`);
 }
+export function schema(value, ref) { schemaBatch([[value, ref]]); }
 export function archive(command, source, destination) {
   const out = spawnSync('python3', [path.join(ROOT, 'scripts/lib/strategic-handoff-zip.py'), command, source, destination], { encoding: 'utf8' });
   ensure(out.status === 0, `ZIP 操作失败: ${out.error?.message || out.stderr}`);

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

@@ -1,7 +1,7 @@
 import { existsSync, lstatSync, readFileSync, mkdirSync, mkdtempSync, renameSync, rmSync, cpSync } from 'node:fs';
 import path from 'node:path';
 import { tmpdir } from 'node:os';
-import { ensure, canonical, digest, hash, json, parse, read, safe, relative, files, write, project, schema, archive, ROOT, sourceApprovalPolicy } from './strategic-handoff-io.mjs';
+import { ensure, canonical, digest, hash, json, parse, read, safe, relative, files, write, project, schema, schemaBatch, archive, ROOT, sourceApprovalPolicy } from './strategic-handoff-io.mjs';
 import { parseContextSource, parseContextContract, resolveContextTermRefs } from './context-contract.mjs';
 import { countersignRuleForGate } from './digital-human-roles.mjs';
 import { validateApprovalRecord } from './approval-record.mjs';
@@ -91,8 +91,7 @@ export async function inspectSource(root, handoffRef) {
   snapshot(handoff.source_context_snapshot,source); checkDelta(handoff,source);
   const strategy=read(safe(root,handoff.source.domain_strategy_ref.persisted_ref));
   const stage=read(safe(root,handoff.source.stage_decision_package_ref.persisted_ref));
-  schema(strategy,'docs/process/schemas/strategic-handoff-domain-strategy.schema.json');
-  schema(stage,'docs/process/schemas/strategic-handoff-stage-decision-package.schema.json');
+  schemaBatch([[strategy,'docs/process/schemas/strategic-handoff-domain-strategy.schema.json'],[stage,'docs/process/schemas/strategic-handoff-stage-decision-package.schema.json']]);
   snapshot(strategy.context_snapshot,source); snapshot(stage.context_snapshot,source);
   ensure(strategy.status==='approved' && stage.status==='approved', '战略合同/方案决策包尚未批准');
   ensure(strategy.domain_strategy_id===handoff.source.domain_strategy_ref.id && strategy.domain_version===handoff.source.domain_strategy_ref.version, '战略身份/版本不一致');
@@ -105,8 +104,10 @@ export async function inspectSource(root, handoffRef) {
   for (const [artifact, version] of [[strategy,strategy.domain_version],[stage,stage.package_version]]) {
     if(artifact.approval) { const record=read(safe(root,artifact.approval.approval_ref));await sourceApproval(record,roles,root);ensure(artifact.approval.current_version===version,'资产内置批准版本过期'); }
   }
-  const terminalGate=countersignRuleForGate(roles.gate_policy,'gate.strategic-design-handoff-approved')?'gate.strategic-design-handoff-approved':'gate.stage-decision-package-approved';
-  const expectedGates={domain_strategy_ref:'gate.domain-strategy-approved',stage_decision_package_ref:'gate.stage-decision-package-approved',spec_ref:'gate.spec-baseline-approved',prototype_ref:'gate.user-confirmation',visual_baseline_ref:'gate.user-confirmation',business_ticket_set_ref:terminalGate,handoff:terminalGate};
+  // Source packages retain their published approval vocabulary. Never promote old approvals into current checkpoint gates.
+  const currentPlan = (roles.gate_policy.dual_digital_human || []).some(rule => rule.gate === 'gate.plan-approved');
+  const terminalGate=currentPlan?'gate.plan-approved':countersignRuleForGate(roles.gate_policy,'gate.strategic-design-handoff-approved')?'gate.strategic-design-handoff-approved':'gate.stage-decision-package-approved';
+  const expectedGates={domain_strategy_ref:currentPlan?'gate.plan-approved':'gate.domain-strategy-approved',stage_decision_package_ref:currentPlan?'gate.plan-approved':'gate.stage-decision-package-approved',spec_ref:'gate.spec-baseline-approved',prototype_ref:currentPlan?'gate.product-design-approved':'gate.user-confirmation',visual_baseline_ref:currentPlan?'gate.product-design-approved':'gate.user-confirmation',business_ticket_set_ref:terminalGate,handoff:terminalGate};
   const bindings={...handoff.source,handoff:{id:handoff.handoff_id,version:handoff.handoff_version,persisted_ref:handoffRef,status:'approved'}};
   for(const [key,ref] of Object.entries(bindings)) {
     const approval=config.approvals[key];
@@ -141,21 +142,22 @@ function collect(root, handoffRef, handoff, config) {
     if(Array.isArray(value)) { if(key==='evidence_refs') value.forEach(enqueue); else value.forEach(v=>refs(v,key)); }
     else if(value && typeof value==='object') for(const [k,v]of Object.entries(value)) { if(['approval_ref','persisted_ref','user_decision_ref'].includes(k)&&typeof v==='string')enqueue(v); else if(k==='ref'&&typeof v==='string'&&!/^[a-z]+:\/\//i.test(v))enqueue(v); else refs(v,k); }
   }
+  let totalBytes = 0;
   while(queue.length) {
     const ref=symbolic[queue[0]]||queue[0]; queue.shift(); if(/^https?:\/\//i.test(ref))continue; relative(ref);
     if(collected.has(ref))continue;
     const full=safe(root,ref),stat=lstatSync(full);
     if(stat.isDirectory()) { queue.push(...files(root,ref)); continue; }
     ensure(stat.isFile() && stat.size<=MAX_BYTES,`源文件类型/大小无效: ${ref}`);
-    const bytes=readFileSync(full); collected.set(ref,bytes);
-    ensure(collected.size<=20000 && [...collected.values()].reduce((n,b)=>n+b.length,0)<=MAX_BYTES,'交接包大小超限');
+    const bytes=readFileSync(full); collected.set(ref,bytes); totalBytes += bytes.length;
+    ensure(collected.size<=20000 && totalBytes<=MAX_BYTES,'交接包大小超限');
     if(/\.(yaml|yml|json)$/.test(ref))refs(parse(bytes));
     queue.push(...documentLinks(ref,bytes));
   }
   return collected;
 }
-function materialize(bundleRoot, manifest, destination) {
-  for(const file of manifest.files.filter(x=>x.original_ref))write(destination,file.original_ref,readFileSync(safe(bundleRoot,file.path)));
+function materialize(captured, manifest, destination) {
+  for(const file of manifest.files.filter(x=>x.original_ref))write(destination,file.original_ref,captured.get(file.path));
 }
 export async function openBundle(input, action) {
   const temp=mkdtempSync(path.join(tmpdir(),'yss-handoff-'));
@@ -170,10 +172,11 @@ export async function openBundle(input, action) {
     ensure(new Set(paths.map(x=>x.toLowerCase())).size===paths.length,'包文件路径重复');
     ensure(own([...paths,'manifest.json'].sort(),files(root).sort()),'包文件缺失或存在未登记文件');
     ensure(manifest.files.length<=20000 && manifest.files.reduce((n,f)=>n+f.size_bytes,0)<=MAX_BYTES,'包大小超限');
-    for(const file of manifest.files){const bytes=readFileSync(safe(root,file.path));ensure(bytes.length===file.size_bytes && hash(bytes)===file.sha256,`文件摘要不一致: ${file.path}`);if(file.original_ref)relative(file.original_ref);}
+    const captured = new Map();
+    for(const file of manifest.files){const bytes=readFileSync(safe(root,file.path));ensure(bytes.length===file.size_bytes && hash(bytes)===file.sha256,`文件摘要不一致: ${file.path}`);if(file.original_ref)relative(file.original_ref);captured.set(file.path,bytes);}
     const originals=manifest.files.filter(x=>x.original_ref).map(x=>x.original_ref);
     ensure(new Set(originals.map(x=>x.toLowerCase())).size===originals.length,'源路径重复');
-    const source=path.join(temp,'source');mkdirSync(source);materialize(root,manifest,source);
+    const source=path.join(temp,'source');mkdirSync(source);materialize(captured,manifest,source);
     const inspected=await inspectSource(source,manifest.handoff_ref);
     ensure(manifest.bundle_id===inspected.handoff.handoff_id && manifest.version===inspected.handoff.handoff_version,'包身份与源交接不一致');
     ensure(own(read(safe(root,'indexes/rules.json')),inspected.indexes.rules) && own(read(safe(root,'indexes/scenarios.json')),inspected.indexes.scenarios),'规则/场景索引与源资产不一致');

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

@@ -3,9 +3,10 @@ import path from "node:path";
 import { parseDocument } from "../vendor/yaml.mjs";
 import { loadDigitalHumanRoles, taskPackageDefaults } from "./digital-human-roles.mjs";
 import { loadRegistry, ROOT } from "./lifecycle-registry.mjs";
-import { loadMaintenanceCheckpoint, validateMaintenanceCheckpoint } from "./maintenance-intensity.mjs";
+import { readRepositoryMode } from "./repository-mode.mjs";
 import { assertImplementationDecision } from "./user-decision.mjs";
 import { validateNextRoute } from "./lifecycle-transition.mjs";
+import { assertPlanSpecEntry } from "./plan-spec-entry.mjs";
 import { enforceHarnessTaskScope } from "./harness-execution-scope.mjs";
 import { enforceFrontendDelivery } from "./frontend-delivery-boundary.mjs";
 import { LEGACY_TASK_PACKAGE_SCHEMA, TASK_PACKAGE_SCHEMA, validateTaskPackageSchema } from "./task-package-schema.mjs";
@@ -16,6 +17,11 @@ export const CONTRACT_KINDS = new Set(["lifecycle-work-unit", "slice-implementat
 export const EXECUTION_STATES = new Set(["Explorer", "Drafter", "Worker", "Reviewer", "Verifier"]);
 export const WORKFLOW_STATUSES = new Set(["not-started", "active", "paused", "resolved", "failed"]);
 
+const repositoryMode = readRepositoryMode(ROOT);
+const maintenanceValidators = repositoryMode === "template-source"
+  ? await import("./maintenance-intensity.mjs")
+  : null;
+
 function fail(message) { throw new TypeError(message); }
 function requireString(value, field) { if (typeof value !== "string" || !value.trim()) fail(`${field} 不能为空`); }
 function equalArrays(actual, expected) { return Array.isArray(actual) && actual.length === expected.length && actual.every((value, index) => value === expected[index]); }
@@ -59,6 +65,7 @@ function validateSkillSource(value, registry) {
 }
 
 function validateCommon(value, registry, lifecycle) {
+  if (value.work_unit_id === 'work-unit.spec-synthesis') assertPlanSpecEntry(value);
   const workUnit = lifecycle.work_units.find((item) => item.id === value.work_unit_id);
   if (!workUnit && value.contract.kind !== "slice-implementation") fail(`未知 work_unit_id: ${value.work_unit_id}`);
   const roleDefaults = taskPackageDefaults(value.role_id, registry);
@@ -141,11 +148,12 @@ function validateContract(value, registry, lifecycle) {
     return;
   }
   if (contract.kind === "template-maintenance") {
+    if (!maintenanceValidators) fail("project-instance 不支持 template-maintenance 任务包");
     if (contract.slice_contract_ref || contract.lifecycle_ref) fail("template-maintenance 不得携带其他合同引用");
     const checkpointPath = assertSafeRelativePath(contract.maintenance_ref, "contract.maintenance_ref");
     if (!existsSync(checkpointPath)) fail(`维护 checkpoint 不存在: ${contract.maintenance_ref}`);
-    const checkpoint = loadMaintenanceCheckpoint(contract.maintenance_ref);
-    validateMaintenanceCheckpoint(checkpoint, {
+    const checkpoint = maintenanceValidators.loadMaintenanceCheckpoint(contract.maintenance_ref);
+    maintenanceValidators.validateMaintenanceCheckpoint(checkpoint, {
       allowPendingReview: value.execution_state === "Reviewer" && value.workflow_status !== "resolved"
     });
     if (checkpoint.schema_version === 2 && value.execution_state === "Reviewer") {

package/template/scripts/verify-context-reconciliation

@@ -1,56 +1,10 @@
 #!/usr/bin/env node
-import { existsSync, readFileSync } from "node:fs";
-import path from "node:path";
-import { spawnSync } from "node:child_process";
 import { parseArgs } from "node:util";
-import { fileURLToPath } from "node:url";
-import { parseDocument } from "./vendor/yaml.mjs";
-import { resolveContextTermRefs, verifyContextSnapshot } from "./lib/context-contract.mjs";
-
-const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
-const schemaPath = path.join(repoRoot, "docs/process/schemas/context-reconciliation.schema.json");
-const pythonValidator = String.raw`
-import json, sys
-from jsonschema import Draft202012Validator
-schema = json.load(open(sys.argv[1], encoding="utf-8"))
-value = json.load(sys.stdin)
-errors = sorted(Draft202012Validator(schema).iter_errors(value), key=lambda error: list(error.absolute_path))
-for error in errors:
-    where = ".".join(str(part) for part in error.absolute_path) or "<root>"
-    print(f"{where}: {error.message}", file=sys.stderr)
-sys.exit(1 if errors else 0)
-`;
-
-function parseFile(file) {
-  const document = parseDocument(readFileSync(file, "utf8"), { maxAliasCount: 0, uniqueKeys: true });
-  if (document.errors.length) throw new TypeError(document.errors[0].message);
-  return document.toJS({ maxAliasCount: 0 });
-}
-
+import { verifyContextReconciliation } from "./lib/context-reconciliation.mjs";
 try {
   const { values, positionals } = parseArgs({ options: { root: { type: "string", default: process.cwd() } }, allowPositionals: true, strict: true });
   if (positionals.length !== 1) throw new TypeError("用法: scripts/verify-context-reconciliation [--root <repo>] <record.yaml|json>");
-  const root = path.resolve(values.root);
-  const file = path.resolve(positionals[0]);
-  const value = parseFile(file);
-  const schemaResult = spawnSync("python3", ["-c", pythonValidator, schemaPath], { encoding: "utf8", input: JSON.stringify(value) });
-  if (schemaResult.status !== 0) throw new TypeError(`${schemaResult.stdout}${schemaResult.stderr}`.trim());
-  const manifest = parseFile(path.join(root, "yss-project.yaml"));
-  if (value.repository_mode !== manifest.repository_mode) throw new TypeError("repository_mode 必须与根目录 yss-project.yaml 一致");
-  const contract = verifyContextSnapshot(value.context_snapshot, { root });
-  const changedRefs = [...value.changes.added, ...value.changes.updated, ...value.changes.deprecated];
-  resolveContextTermRefs(contract, changedRefs);
-  if (new Set(changedRefs).size !== changedRefs.length) throw new TypeError("changes 中的术语引用不得跨分类重复");
-  if (value.repository_mode === "project-instance" && value.status !== "reconciled") throw new TypeError("project-instance 工作单元只有 status=reconciled 才允许批准或进入下一步");
-  if (value.status === "reconciled" && value.unresolved_terms.length) throw new TypeError("reconciled 不得包含 unresolved_terms");
-  if (value.status === "blocked" && value.unresolved_terms.length === 0) throw new TypeError("blocked 必须说明 unresolved_terms");
-  if (value.status === "not-applicable" && (value.repository_mode !== "template-source" || !value.reason)) throw new TypeError("not-applicable 只适用于 template-source 且必须说明 reason");
-  for (const ref of value.evidence_refs) {
-    if (/^https?:\/\//.test(ref)) continue;
-    const resolved = path.resolve(root, ref);
-    if (!resolved.startsWith(`${root}${path.sep}`) && resolved !== root) throw new TypeError(`evidence_ref 越出仓库: ${ref}`);
-    if (!existsSync(resolved)) throw new TypeError(`evidence_ref 不可读: ${ref}`);
-  }
+  verifyContextReconciliation(positionals[0], { root: values.root });
   process.stdout.write("Context reconciliation 验证通过\n");
 } catch (error) {
   process.stderr.write(`Context reconciliation 验证失败: ${error.message}\n`);

package/template/scripts/verify-lifecycle-checkpoint

@@ -6,6 +6,7 @@ import { parseArgs } from "node:util";
 import { fileURLToPath } from "node:url";
 import { parseDocument } from "./vendor/yaml.mjs";
 import { assertCheckpointApprovals, assertCheckpointUserDecisions } from "./lib/approval-record.mjs";
+import { assertPlanCheckpoint } from "./lib/plan-spec-entry.mjs";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const schemaPath = path.join(root, "docs/process/schemas/lifecycle-checkpoint.schema.json");
@@ -32,6 +33,7 @@ try {
   const result = spawnSync("python3", ["-c", validator, schemaPath], { cwd: root, encoding: "utf8", input: JSON.stringify(value) });
   if (result.status !== 0) throw new TypeError(`${result.stdout}${result.stderr}`.trim());
   assertCheckpointApprovals(value, sourcePath);
+  assertPlanCheckpoint(value);
   assertCheckpointUserDecisions(value);
   if (value.repository_mode === "project-instance" && ["paused-human-gate", "completed"].includes(value.status)) {
     if (value.context_reconciliation?.status !== "reconciled" || !value.context_reconciliation?.ref) throw new TypeError("project-instance 在会签或完成前必须具有 reconciled context_reconciliation");

package/template/scripts/verify-openapi-draft-validation-record

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, readFileSync, realpathSync } from "node:fs";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { fileURLToPath } from "node:url";
+import { parseAllDocuments, parseDocument } from "./vendor/yaml.mjs";
+import { validateJsonSchema } from "./lib/json-schema.mjs";
+
+const templateRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const schemaPath = path.join(templateRoot, "docs/process/schemas/openapi-draft-validation-record.schema.json");
+const methods = new Set(["get", "put", "post", "delete", "options", "head", "patch", "trace"]);
+
+function ensure(condition, message) {
+  if (!condition) throw new TypeError(message);
+}
+
+function resolveSafe(root, reference) {
+  ensure(typeof reference === "string" && reference.length > 0, "引用不能为空");
+  ensure(!path.isAbsolute(reference) && !reference.includes("\\") && !reference.split("/").includes(".."), `引用必须位于项目内: ${reference}`);
+  const target = path.resolve(root, reference);
+  ensure(target === root || target.startsWith(`${root}${path.sep}`), `引用越出项目根: ${reference}`);
+  ensure(existsSync(target), `引用不可读取: ${reference}`);
+  ensure(!lstatSync(target).isSymbolicLink(), `引用不能是 symlink: ${reference}`);
+  return target;
+}
+
+function parseOne(file, label) {
+  const source = readFileSync(file, "utf8");
+  const documents = parseAllDocuments(source, { uniqueKeys: true, maxAliasCount: 0 });
+  ensure(documents.length === 1, `${label} 必须是单一 YAML document`);
+  ensure(!documents[0].errors.length, `${label} YAML 无效: ${documents[0].errors[0]?.message}`);
+  return documents[0].toJS({ maxAliasCount: 0 });
+}
+
+function pointer(value, fragment, reference) {
+  if (!fragment || fragment === "#") return value;
+  ensure(fragment.startsWith("#/"), `仅支持 JSON Pointer fragment: ${reference}`);
+  return fragment.slice(2).split("/").reduce((current, part) => {
+    const key = decodeURIComponent(part).replaceAll("~1", "/").replaceAll("~0", "~");
+    ensure(current && Object.hasOwn(current, key), `$ref 无法解析: ${reference}`);
+    return current[key];
+  }, value);
+}
+
+function verifyReferences(rootDocument, draftFile) {
+  const apiRoot = realpathSync(path.dirname(draftFile));
+  const cache = new Map([[realpathSync(draftFile), rootDocument]]);
+  const active = new Set();
+
+  function load(reference, ownerFile) {
+    ensure(!/^[a-z][a-z0-9+.-]*:/i.test(reference) && !path.isAbsolute(reference), `$ref 禁止远程或绝对路径: ${reference}`);
+    const [filePart, fragment = ""] = reference.split("#", 2);
+    const targetFile = filePart ? path.resolve(path.dirname(ownerFile), filePart) : ownerFile;
+    ensure(existsSync(targetFile), `$ref 文件不存在: ${reference}`);
+    const realTarget = realpathSync(targetFile);
+    ensure(realTarget === apiRoot || realTarget.startsWith(`${apiRoot}${path.sep}`), `$ref 越出 feature API 目录: ${reference}`);
+    if (!cache.has(realTarget)) cache.set(realTarget, parseOne(realTarget, `$ref ${reference}`));
+    return { value: pointer(cache.get(realTarget), fragment ? `#${fragment}` : "", reference), file: realTarget };
+  }
+
+  function walk(value, ownerFile) {
+    if (!value || typeof value !== "object") return;
+    if (typeof value.$ref === "string") {
+      const key = `${ownerFile}|${value.$ref}`;
+      if (active.has(key)) return;
+      active.add(key);
+      const resolved = load(value.$ref, ownerFile);
+      walk(resolved.value, resolved.file);
+      active.delete(key);
+    }
+    for (const child of Object.values(value)) walk(child, ownerFile);
+  }
+  walk(rootDocument, realpathSync(draftFile));
+  return (reference, ownerFile = realpathSync(draftFile)) => load(reference, ownerFile);
+}
+
+function verifyOperations(document, resolveReference) {
+  const operationIds = new Set();
+  for (const [route, pathItem] of Object.entries(document.paths ?? {})) {
+    if (!pathItem || typeof pathItem !== "object") continue;
+    const placeholders = [...route.matchAll(/\{([^}]+)\}/g)].map((match) => match[1]);
+    for (const [method, operation] of Object.entries(pathItem)) {
+      if (!methods.has(method) || !operation || typeof operation !== "object") continue;
+      ensure(typeof operation.operationId === "string" && operation.operationId.length > 0, `${method.toUpperCase()} ${route} 缺少 operationId`);
+      ensure(!operationIds.has(operation.operationId), `operationId 重复: ${operation.operationId}`);
+      operationIds.add(operation.operationId);
+      const parameters = [...(pathItem.parameters ?? []), ...(operation.parameters ?? [])].map((item) =>
+        typeof item?.$ref === "string" ? resolveReference(item.$ref).value : item
+      );
+      for (const name of placeholders) {
+        const parameter = parameters.find((item) => item?.in === "path" && item?.name === name);
+        ensure(parameter && parameter.required === true, `${method.toUpperCase()} ${route} 缺少 required path parameter: ${name}`);
+      }
+    }
+  }
+}
+
+try {
+  const { values, positionals } = parseArgs({
+    options: { "allow-template": { type: "boolean" }, root: { type: "string", default: templateRoot } },
+    allowPositionals: true,
+    strict: true
+  });
+  ensure(positionals.length === 1, "用法: scripts/verify-openapi-draft-validation-record [--allow-template] [--root <project>] <record.yaml>");
+  const root = path.resolve(values.root);
+  const recordFile = path.resolve(positionals[0]);
+  const recordDocument = parseDocument(readFileSync(recordFile, "utf8"), { uniqueKeys: true, maxAliasCount: 0 });
+  ensure(!recordDocument.errors.length, `validation record YAML 无效: ${recordDocument.errors[0]?.message}`);
+  const record = recordDocument.toJS({ maxAliasCount: 0 });
+  validateJsonSchema(record, schemaPath, { cwd: templateRoot, label: "OpenAPI Draft validation record schema" });
+
+  if (values["allow-template"]) {
+    ensure(record.template === true, "--allow-template 只接受模板记录");
+    process.stdout.write("OpenAPI Draft validation record 模板验证通过\n");
+    process.exit(0);
+  }
+
+  ensure(record.template === false, "正式 validation record 必须设置 template: false");
+  ensure(record.status === "passed", "正式 validation record 必须达到 status: passed");
+  ensure(record.toolchain.exit_code === 0, "Redocly lint 必须以退出码 0 完成");
+  ensure(Object.values(record.checks).every((result) => result === "passed"), "所有结构与 lint checks 必须为 passed");
+  ensure(record.toolchain.command === `pnpm exec redocly lint ${record.draft.ref}`, "lint command 必须精确指向当前 Draft");
+
+  const draftFile = resolveSafe(root, record.draft.ref);
+  const lockfile = resolveSafe(root, record.toolchain.lockfile_ref);
+  resolveSafe(root, record.toolchain.evidence_ref);
+  const draftBytes = readFileSync(draftFile);
+  const actualDigest = `sha256:${createHash("sha256").update(draftBytes).digest("hex")}`;
+  ensure(actualDigest === record.draft.sha256, `Draft SHA-256 不匹配: record=${record.draft.sha256}, actual=${actualDigest}`);
+  const lock = readFileSync(lockfile, "utf8");
+  const version = record.toolchain.version.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const lockedPackage = new RegExp(`['\"]?@redocly/cli@${version}(?:['\":\\s(]|$)`).test(lock)
+    || new RegExp(`['\"]?@redocly/cli['\"]?:[\\s\\S]{0,240}?\\n\\s+version:\\s*['\"]?${version}(?:\\(|['\"\\s]|$)`).test(lock);
+  ensure(lockedPackage, "pnpm lockfile 未绑定记录中的 @redocly/cli 版本");
+
+  const draft = parseOne(draftFile, "OpenAPI Draft");
+  ensure(draft?.openapi === "3.1.0" && record.draft.oas_version === draft.openapi, "OpenAPI Draft 必须为 OAS 3.1.0");
+  const resolveReference = verifyReferences(draft, draftFile);
+  verifyOperations(draft, resolveReference);
+  process.stdout.write(`OpenAPI Draft validation record 验证通过: ${record.draft.sha256}\n`);
+} catch (error) {
+  process.stderr.write(`OpenAPI Draft validation record 验证失败: ${error.message}\n`);
+  process.exitCode = 1;
+}

package/template/scripts/verify-plan-spec-entry

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { decisionIO } from './lib/user-decision.mjs';
+import { assertPlanSpecEntry } from './lib/plan-spec-entry.mjs';
+try {
+  if (process.argv.length !== 3) throw new TypeError('用法: node scripts/verify-plan-spec-entry <state.yaml|json>');
+  assertPlanSpecEntry(decisionIO().document(process.argv[2]));
+  process.stdout.write('Plan → Spec 入口检查通过（不授权实现）\n');
+} catch (error) {
+  process.stderr.write(`${error.message}\n`);
+  process.exitCode = 1;
+}

package/template/scripts/verify-project-instance

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseDocument } from "./vendor/yaml.mjs";
+import { loadRegistry, validateRegistry } from "./lib/lifecycle-registry.mjs";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const identityPath = path.join(root, "yss-project.yaml");
+const identity = parseDocument(readFileSync(identityPath, "utf8"), {
+  maxAliasCount: 0,
+  uniqueKeys: true,
+}).toJS({ maxAliasCount: 0 });
+if (identity?.schema_version !== 1 || identity?.repository_mode !== "project-instance") {
+  throw new TypeError("verify-project-instance 仅适用于合法 project-instance");
+}
+
+const commands = [
+  ["scripts/sync-skills", ["--check"]],
+  ["scripts/update-skill-lock", ["--check"]],
+  ["scripts/verify-context-contract", ["--root", ".", "--json"]],
+];
+for (const [command, args] of commands) {
+  const executable = path.join(root, command);
+  if (!existsSync(executable)) throw new TypeError(`缺少项目实例校验入口: ${command}`);
+  const result = spawnSync(executable, args, { cwd: root, encoding: "utf8" });
+  if (result.status !== 0) {
+    throw new TypeError(result.stderr.trim() || result.stdout.trim() || `${command} 校验失败`);
+  }
+}
+validateRegistry(loadRegistry());
+process.stdout.write("项目实例校验通过\n");