create-yss-spec 3.5.0 → 3.5.2

package/template/scripts/lib/openapi-draft-validation.mjs

@@ -83,7 +83,7 @@ function verifyOperations(document, resolveReference) {
   }
 }
 
-export function validateOpenApiDraftValidationRecord(recordFile, { root = TEMPLATE_ROOT, allowTemplate = false, schemaPath = path.join(TEMPLATE_ROOT, "docs/process/schemas/openapi-draft-validation-record.schema.json") } = {}) {
+export function validateOpenApiDraftValidationRecord(recordFile, { root = TEMPLATE_ROOT, allowTemplate = false, schemaPath = path.join(TEMPLATE_ROOT, ".template-spec/process/schemas/openapi-draft-validation-record.schema.json") } = {}) {
   const projectRoot = path.resolve(root);
   const recordDocument = parseDocument(readFileSync(recordFile, "utf8"), { uniqueKeys: true, maxAliasCount: 0 });
   ensure(!recordDocument.errors.length, `validation record YAML 无效: ${recordDocument.errors[0]?.message}`);

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

@@ -0,0 +1,48 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { parseDocument } from '../vendor/yaml.mjs';
+import { safeTrackingPath } from './stage-tracking.mjs';
+
+const digest = bytes => `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+const read = (root, ref) => readFileSync(safeTrackingPath(root, ref));
+const parse = bytes => {
+  const document = parseDocument(String(bytes), { uniqueKeys: true, maxAliasCount: 0 });
+  if (document.errors.length) throw new TypeError(document.errors[0].message);
+  return document.toJS({ maxAliasCount: 0 });
+};
+
+/** Draft data only: no checks, impacts, approvals or user decisions are inferred. */
+export function preparePlanSpecEntry({ root, featureId, planRef, contextRef }) {
+  if (![root, featureId, planRef, contextRef].every(value => typeof value === 'string' && value.trim())) throw new TypeError('root, feature, plan and context-reconciliation are required');
+  const identity = parse(read(root, 'yss-project.yaml'));
+  if (identity.schema_version !== 1 || identity.repository_mode !== 'project-instance') throw new TypeError('Plan 入口仅适用于 project-instance');
+  const registryRef = '.template-spec/process/lifecycle-registry.yaml';
+  const registry = parse(read(root, registryRef));
+  const policy = registry.stages?.find(stage => stage.id === 'stage.plan')?.spec_entry;
+  if (!policy?.required_checks?.length) throw new TypeError('Plan 入口检查合同缺失');
+  const refs = [...new Set([planRef, 'CONTEXT.md', registryRef, contextRef])];
+  const basis = refs.map(ref => ({ ref, digest: digest(read(root, ref)) }));
+  const review_candidate = {
+    schema_version: 1, kind: 'plan-entry-review', gate_id: 'gate.plan-approved', feature_id: featureId,
+    plan_ref: planRef, context_reconciliation_ref: contextRef, basis,
+    checks: Object.fromEntries(policy.required_checks.map(id => [id, { status: 'pending', evidence_refs: [] }])),
+    open_items: [],
+    impacts: Object.fromEntries(Object.values(policy.check_impacts ?? {}).map(impact => [impact, null])),
+    internal_checks: Object.fromEntries(Object.keys(policy.check_impacts ?? {}).map(id => [id, { status: 'pending', evidence_refs: [] }])),
+  };
+  return { schema_version: 1, status: 'draft', review_candidate, missing_requirements: ['补齐检查证据与影响判断', '展示当前审阅包并提供真实用户决定，或按用户决定协议核验绑定当前范围的 plan_continuation_ref；未知或实质变化须重新决定'], approval_created: false };
+}
+
+export function diffPlanSpecEntry({ root, reviewRef }) {
+  if (!root || !reviewRef) throw new TypeError('root and review are required');
+  const review = parse(read(root, reviewRef));
+  if (review.kind !== 'plan-entry-review' || review.schema_version !== 1 || !Array.isArray(review.basis)) throw new TypeError('不是 Plan 入口审阅包');
+  const changed_refs = [], missing_refs = [];
+  for (const item of review.basis) {
+    if (!item?.ref || !item?.digest) throw new TypeError('basis 缺少 ref 或 digest');
+    try { if (digest(read(root, item.ref)) !== item.digest) changed_refs.push(item.ref); }
+    catch { missing_refs.push(item.ref); }
+  }
+  return { schema_version: 1, review_ref: reviewRef, status: changed_refs.length || missing_refs.length ? 'stale' : 'current', changed_refs, missing_refs, approval_created: false };
+}

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

@@ -7,7 +7,7 @@ const fail = message => { throw new TypeError(`plan-spec-entry-blocked: ${messag
 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 registry = decisionIO(options).document('.template-spec/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();
@@ -33,7 +33,7 @@ export function assertPlanSpecEntry(state, options = {}) {
   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]) {
+  for (const ref of [review.plan_ref, 'CONTEXT.md', '.template-spec/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('检查项缺失或存在未知项');
@@ -62,7 +62,7 @@ export function assertPlanSpecEntry(state, options = {}) {
     } else if (gate.status !== 'not-applicable' || !text(gate.reason)) fail(`未命中门禁须有原因和依据: ${gateId}`);
   }
   // 门禁依赖不能通过将上游标成 N/A 来跳过。
-  const registry = io.document('docs/process/lifecycle-registry.yaml');
+  const registry = io.document('.template-spec/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}`);

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

@@ -3,7 +3,7 @@ import path from "node:path";
 import { parseDocument } from "../vendor/yaml.mjs";
 import { nestedSkillPaths, OBSOLETE, PROJECTION_ROOTS, ROOT, unregisteredNestedSkillPaths } from "./skill-supply-chain.mjs";
 
-export const DEFAULT_REGISTRY = path.join(ROOT, "docs/agents/yss-skill-registry.yaml");
+export const DEFAULT_REGISTRY = path.join(ROOT, ".template-spec/agents/yss-skill-registry.yaml");
 const LOCK_PATH = path.join(ROOT, "skills-lock.json");
 const COMPILER_CONTRACT = path.join(ROOT, ".agents/skills/yss-implementation-contract-compiler/references/compiler-contract.yaml");
 const LIFECYCLE_CONTRACT = [
@@ -11,7 +11,7 @@ const LIFECYCLE_CONTRACT = [
   path.join(ROOT, ".agents/skills/harness-orchestrator/references/orchestration-contract.yaml"),
 ].find((candidate) => existsSync(candidate))
   ?? path.join(ROOT, ".agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml");
-const BACKEND_PLATFORMS = path.join(ROOT, "docs/engineering/backend-platforms.json");
+const BACKEND_PLATFORMS = path.join(ROOT, ".template-spec/engineering/backend-platforms.json");
 const LAYERS = new Set(["core", "specialist", "compatibility", "maintainer-only"]);
 const MATURITIES = new Set(["draft", "verified", "supported", "deprecated"]);
 const INVOCATION_MODES = new Set(["user", "model", "both"]);
@@ -73,7 +73,7 @@ export function resolveSkillForNewUse(registry, requestedId) {
         : `${requestedId} 已硬退役；按迁移 tombstone 重新路由`,
       {
         skill: requestedId,
-        migration_ref: "docs/agents/skill-migrations.md",
+        migration_ref: ".template-spec/agents/skill-migrations.md",
         ...(replacementSkill ? { replacement_skill: replacementSkill } : {})
       }
     );
@@ -379,7 +379,7 @@ export function validateSkillRegistry(registry, { lock, compilerContract, lifecy
   requireStringSet(registry.retirement_contract.stages, ["deprecated", "retired"], "retirement_contract.stages");
   if (registry.retirement_contract.deprecated_new_use !== "forbidden") fail("retirement_contract.deprecated_new_use 必须为 forbidden");
   requireStringSet(registry.retirement_contract.cleanup_statuses, [...CLEANUP_STATUSES], "retirement_contract.cleanup_statuses");
-  if (registry.retirement_contract.hard_retirement_tombstone !== "docs/agents/skill-migrations.md") fail("retirement_contract.hard_retirement_tombstone 必须指向技能迁移说明");
+  if (registry.retirement_contract.hard_retirement_tombstone !== ".template-spec/agents/skill-migrations.md") fail("retirement_contract.hard_retirement_tombstone 必须指向技能迁移说明");
   if (registry.retirement_contract.retired_id_source !== "scripts/lib/skill-supply-chain.mjs#OBSOLETE") fail("retirement_contract.retired_id_source 必须指向统一 OBSOLETE 集");
   requireObject(registry.retirement_contract.failure_codes, "retirement_contract.failure_codes");
   if (registry.retirement_contract.failure_codes.deprecated !== SKILL_LIFECYCLE_FAILURE_CODES.deprecated || registry.retirement_contract.failure_codes.retired !== SKILL_LIFECYCLE_FAILURE_CODES.retired) {
@@ -469,7 +469,7 @@ export function validateSkillRegistry(registry, { lock, compilerContract, lifecy
     fail("capability_contract.deterministic_order 必须固定为 recipe-declaration、dependency-topology、skill-id");
   }
   requireObject(capabilityContract.platform_component_binding, "capability_contract.platform_component_binding");
-  if (capabilityContract.platform_component_binding.marker !== "provider" || capabilityContract.platform_component_binding.required_kind !== "yss-component" || capabilityContract.platform_component_binding.catalog_source !== "docs/engineering/backend-platforms.json") {
+  if (capabilityContract.platform_component_binding.marker !== "provider" || capabilityContract.platform_component_binding.required_kind !== "yss-component" || capabilityContract.platform_component_binding.catalog_source !== ".template-spec/engineering/backend-platforms.json") {
     fail("capability_contract.platform_component_binding 必须绑定中央后端平台目录");
   }
   requireStringSet(capabilityContract.provider_kinds, [...PROVIDER_KINDS], "capability_contract.provider_kinds");
@@ -615,8 +615,8 @@ export function validateSkillRegistry(registry, { lock, compilerContract, lifecy
     if (deprecatedCompilerRefs.length) fail(`实现合同编译器合同仍引用 deprecated skill: ${deprecatedCompilerRefs.join(", ")}`);
     if (compilerContract.schema_version !== 2) fail("compiler-contract.yaml schema_version 必须为 2；v1 已停止支持");
     if (compilerContract.compiled_by !== "yss-implementation-contract-compiler") fail("compiler-contract.yaml compiled_by 无效");
-    if (compilerContract.capability_source !== "docs/agents/yss-skill-registry.yaml") fail("compiler-contract.yaml capability_source 必须指向技能注册表");
-    if (compilerContract.recipe_source !== "docs/agents/yss-skill-registry.yaml") fail("compiler-contract.yaml recipe_source 必须指向技能注册表");
+    if (compilerContract.capability_source !== ".template-spec/agents/yss-skill-registry.yaml") fail("compiler-contract.yaml capability_source 必须指向技能注册表");
+    if (compilerContract.recipe_source !== ".template-spec/agents/yss-skill-registry.yaml") fail("compiler-contract.yaml recipe_source 必须指向技能注册表");
     requireObject(compilerContract.impact_to_capabilities, "compiler-contract.impact_to_capabilities");
     for (const [impact, mapped] of Object.entries(compilerContract.impact_to_capabilities)) {
       requireStringArray(mapped, `compiler-contract.impact_to_capabilities.${impact}`, { nonEmpty: true });
@@ -669,7 +669,7 @@ export function validateSkillRegistry(registry, { lock, compilerContract, lifecy
           fail(`${routeId}.frontend_route 主入口引用了未登记技能`);
         }
       }
-      if (routeId === "work-unit.prototype-design") {
+      if (routeId === "work-unit.prototype-design-v2") {
         if (!route.skills.includes("prototype-review") || !route.supporting_skills.includes("prototype-review")) {
           fail("原型工作单元必须包含独立 prototype-review supporting skill");
         }

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

@@ -261,7 +261,7 @@ function metadata(name, skillPath, directory, previous, canonical = false, sourc
     result.upstreamHash = treeHash(upstreamDirectory);
   } else if (old.upstreamHash ?? old.computedHash) result.upstreamHash = old.upstreamHash ?? old.computedHash;
   if (result.upstreamHash && result.effectiveHash !== result.upstreamHash) {
-    const adaptationRef = old.adaptationRef ?? (result.source === "mattpocock/skills" ? "docs/process/MATT-POCOCK-ENGINEERING-SKILLS.md" : null);
+    const adaptationRef = old.adaptationRef ?? (result.source === "mattpocock/skills" ? ".template-source/process/MATT-POCOCK-ENGINEERING-SKILLS.md" : null);
     if (adaptationRef) result.adaptationRef = adaptationRef;
   }
   return result;

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

@@ -31,7 +31,7 @@ function markdownAcceptance(text) {
 }
 function lifecycleSources(checkpoint,report) {
   const result={};
-  for(const [artifact,key]of Object.entries({'artifact.spec':'spec','artifact.engineering-baseline':'engineering_baseline','artifact.architecture-review':'architecture_review','artifact.technical-design':'technical_design','artifact.data-architecture':'data_architecture','artifact.state-matrix':'state_matrix','artifact.prototype-deliverable':'prototype_deliverable','artifact.prototype-review':'prototype_review','artifact.prototype-confirmation':'prototype_confirmation','artifact.openapi-freeze-record':'openapi_freeze'})) {
+  for(const [artifact,key]of Object.entries({'artifact.spec':'spec','artifact.engineering-baseline':'engineering_baseline','artifact.architecture-review':'architecture_review','artifact.technical-design':'technical_design','artifact.data-architecture':'data_architecture','artifact.state-matrix':'state_matrix','artifact.prototype-deliverable':'prototype_deliverable','artifact.prototype-review-v2':'prototype_review','artifact.prototype-confirmation-v2':'prototype_confirmation','artifact.openapi-freeze-record':'openapi_freeze'})) {
     const value=checkpoint.artifacts?.[artifact];if(value===undefined)continue;
     if(typeof value==='string')result[key]={ref:value};
     else if(object(value)&&typeof value.ref==='string')result[key]=Object.fromEntries(['ref','version','digest','approval_ref'].filter(k=>value[k]!==undefined).map(k=>[k,value[k]]));
@@ -72,7 +72,7 @@ function prepare({root=process.cwd(),ticket_ref,checkpoint_ref,sources={},refine
     const selected=mergeFacts(lifecycleSources(saved,report),mergeFacts(input.sources || {},sources,'sources',report),'sources',report);
     if(selected.ticket && (typeof selected.ticket==='string'?selected.ticket:selected.ticket.ref)!==ticket_ref)throw new TypeError('Ticket 来源冲突');
     selected.ticket=selected.ticket || {ref:ticket_ref};
-    if(input.scope?.risk_level){selected.lifecycle_registry??={ref:'docs/process/lifecycle-registry.yaml'};selected.process_tailoring??={ref:'docs/process/harness-process-tailoring.md'};}
+    if(input.scope?.risk_level){selected.lifecycle_registry??={ref:'.template-spec/process/lifecycle-registry.yaml'};selected.process_tailoring??={ref:'.template-spec/process/harness-process-tailoring.md'};}
     if(!selected.context&&fs.existsSync(safe(root,'CONTEXT.md',{missing:true})))selected.context={ref:'CONTEXT.md'};
     const basis={},seen=new Map();
     for(const [key,value] of Object.entries(selected)) {
@@ -136,7 +136,7 @@ function prepare({root=process.cwd(),ticket_ref,checkpoint_ref,sources={},refine
     for(const reason of compiled.readiness_blockers||[])report.blockers.push({reason});
     normalizeSliceContract(contract,{root});
     report.checks.push({check:'structure-sources-scope-acceptance',result:'pass'});
-    report.provenance.push({target:'resolution',source_ref:'docs/agents/yss-skill-registry.yaml',digest:compiled.registry_digest,rule:'existing-capability-compiler'});
+    report.provenance.push({target:'resolution',source_ref:'.template-spec/agents/yss-skill-registry.yaml',digest:compiled.registry_digest,rule:'existing-capability-compiler'});
     for(const field of ['scope','acceptance','verification','work_units','applicability','extensions'])if(contract[field]) {
       const origins=[];
       if(saved.slice_implementation?.[field]!==undefined)origins.push({kind:'checkpoint',ref:checkpoint_ref});

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

@@ -113,7 +113,7 @@ export function normalizeSliceContract(document, options = {}) {
     }
     return structuredClone(raw);
   }
-  schema(raw,'docs/process/schemas/slice-implementation-contract-v3.schema.json');
+  schema(raw,'.template-spec/process/schemas/slice-implementation-contract-v3.schema.json');
   const sources=readSliceSources(raw,options), refs=Object.fromEntries(Object.entries(sources).map(([key,item])=>[key,item.ref]));
   requireKeys(refs,['spec','ticket','engineering_baseline','implementation_repository','build_architecture_checklist'],'依据');
   const ticketHeader = sources.ticket.text.match(/^---\r?\n([\s\S]*?)\r?\n---/);

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

@@ -10,7 +10,7 @@ export function sliceRepositories(contract,sources,{root=process.cwd()}={}) {
  check(lifecycle.SLICE_REPOSITORY_PREPARATION_PROTOCOL===1&&typeof lifecycle.validateImplementationRepositoriesReady==='function','接收端不支持当前来源的多项目准备协议，不能套用本地默认规则');
  check(sources.repository_preparation,'缺少多项目准备结果');
  const preparation=parseSliceYaml(sources.repository_preparation.text);
- schema(preparation,'docs/process/schemas/implementation-repository-preparation-result.schema.json');
+ schema(preparation,'.template-spec/process/schemas/implementation-repository-preparation-result.schema.json');
  const ready=lifecycle.validateImplementationRepositoriesReady({implementation_repository_preparation:preparation,delivery_impacts:Object.fromEntries(['backend','frontend'].map(role=>[role,preparation.projects.some(p=>p.delivery_role===role&&p.status!=='not-applicable')]))},{root,exists:ref=>fs.existsSync(path.resolve(root,ref)),read:ref=>fs.readFileSync(path.resolve(root,ref),'utf8')});
  check(ready.result!=='blocked',`多项目准备未就绪: ${ready.missing_requirements.join('; ')}`);
  check(new Set(Object.keys(bindings).map(p=>path.resolve(p))).size===Object.keys(bindings).length,'工程根存在路径别名，不能重复登记');

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

@@ -10,13 +10,13 @@ const fail=message=>{throw new TypeError(message);};
 const equalArrays=(a,b)=>Array.isArray(a)&&a.length===b.length&&a.every((x,i)=>x===b[i]);
 function generateTaskPackageDefaults(roleId,overrides,{rolesDoc}={}) {
   const defaults=taskPackageDefaults(roleId,rolesDoc||loadDigitalHumanRoles());
-  return {schema_version:1,role_id:roleId,skill_source:{registry_ref:'docs/agents/digital-human-roles.yaml',defaults_ref:`taskPackageDefaults(${roleId})`,core_skills:defaults.core_skills,forbidden_skills:defaults.forbidden_skills},...overrides};
+  return {schema_version:1,role_id:roleId,skill_source:{registry_ref:'.template-spec/agents/digital-human-roles.yaml',defaults_ref:`taskPackageDefaults(${roleId})`,core_skills:defaults.core_skills,forbidden_skills:defaults.forbidden_skills},...overrides};
 }
 
 /** Compile dispatch from the approved YAML. Only runtime identity and task ID come from the caller. */
 export function compileSliceTaskPackage(binding,options={}) {return withValidationPhase({root:options.root||ROOT,purpose:'slice-dispatch',slice_id:binding.ref,work_unit_id:options.work_unit_id,readOnly:false,signal:options.signal},()=>compile(binding,options));}
 function compile(binding,{root=ROOT,work_unit_id,task_id,actor_id,runtime_id,execution_state='Worker',rolesDoc,user_decisions}={}) {
-  const actualRoles=parseSliceYaml(readFileSync(safe(root,'docs/agents/digital-human-roles.yaml')));
+  const actualRoles=parseSliceYaml(readFileSync(safe(root,'.template-spec/agents/digital-human-roles.yaml')));
   if(rolesDoc&&digest(rolesDoc)!==digest(actualRoles))fail('调用方不能替换接收端角色能力');
   rolesDoc=actualRoles;
   if(!actualRoles.runtimes.some(runtime=>runtime.id===runtime_id))fail('接收端不支持该 runtime_id');
@@ -46,7 +46,7 @@ export function assertSliceV3TaskPackage(value,slice,{root=ROOT}={}) {
   enforceHarnessTaskScope(value,{root});
   const contract=value.contract;
   const current=normalizeSliceContract(slice,{root});
-  const roles=parseSliceYaml(readFileSync(safe(root,'docs/agents/digital-human-roles.yaml'))),defaults=taskPackageDefaults(value.role_id,roles);
+  const roles=parseSliceYaml(readFileSync(safe(root,'.template-spec/agents/digital-human-roles.yaml'))),defaults=taskPackageDefaults(value.role_id,roles);
   if(!roles.runtimes.some(runtime=>runtime.id===value.runtime_id)||!defaults.stages.includes(value.stage_id))fail('接收端角色或运行时不支持当前任务');
   if(!equalArrays(value.skill_source.core_skills,defaults.core_skills)||!equalArrays(value.skill_source.forbidden_skills,defaults.forbidden_skills))fail('任务角色能力与接收端不一致');
   const unit=current.work_units.find(item=>item.id===value.work_unit_id);

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

@@ -46,12 +46,12 @@ export function planTracking(root, { checkpoint_ref, items = [], refresh = false
     watch(ref);
     if (!observed[ref] || sha256(after) !== observed[ref].digest) changes.push({ ref, before: observed[ref], after, after_digest: sha256(after) });
   }
-  for (const ref of ['yss-project.yaml', 'CONTEXT.md', TRACKER_REF, 'docs/process/lifecycle-registry.yaml', 'docs/process/schemas/stage-tracking.schema.json', 'docs/process/harness-profile.yaml', checkpoint_ref]) watch(ref);
+  for (const ref of ['yss-project.yaml', 'CONTEXT.md', TRACKER_REF, '.template-spec/process/lifecycle-registry.yaml', '.template-spec/process/schemas/stage-tracking.schema.json', '.template-spec/process/harness-profile.yaml', checkpoint_ref]) watch(ref);
   const exists = observed[checkpoint_ref] !== null;
   let checkpoint;
   if (exists) checkpoint = parseYaml(readTracking(root, checkpoint_ref));
   else {
-    const template = 'docs/process/templates/lifecycle-checkpoint-template.yaml'; watch(template);
+    const template = '.template-spec/process/templates/lifecycle-checkpoint-template.yaml'; watch(template);
     checkpoint = parseYaml(readTracking(root, template));
     checkpoint.feature_id = feature;
     checkpoint.mode = 'orchestrate'; checkpoint.status = 'running';

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

@@ -4,14 +4,14 @@ import { createHash } from 'node:crypto';
 import { parseDocument } from '../vendor/yaml.mjs';
 import { validateJsonSchema } from './json-schema.mjs';
 
-export const TRACKER_REF = 'docs/agents/issue-tracker.md';
+export const TRACKER_REF = '.template-spec/agents/issue-tracker.md';
 export const STAGE_WORK_UNITS = Object.freeze({
   'work-unit.plan-opportunity': 'stage.plan',
   'work-unit.plan-requirements': 'stage.plan',
   'work-unit.domain-strategy-design': 'stage.plan',
   'work-unit.stage-decision': 'stage.plan',
   'work-unit.spec-synthesis': 'stage.spec-architecture',
-  'work-unit.prototype-design': 'stage.product-design',
+  'work-unit.prototype-design-v2': 'stage.product-design',
 });
 export const sha256 = bytes => `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
 export function parseYaml(bytes) {
@@ -43,7 +43,7 @@ export function trackerConfig(root) {
   return config;
 }
 export function trackingProfile(root) {
-  const ref = 'docs/process/harness-profile.yaml';
+  const ref = '.template-spec/process/harness-profile.yaml';
   return existsSync(safeTrackingPath(root, ref)) ? parseYaml(readTracking(root, ref)) : null;
 }
 export const isDesign = root => trackingProfile(root)?.profile_id === 'harness.business-ddd-strategy-handoff';
@@ -81,7 +81,7 @@ export function assertStageTracking(checkpoint, { root, checkpointRef, currentWo
     if (identity.repository_mode === 'project-instance' && config.lifecycle_tracking_version === 1 && relevant) throw new Error('stage-tracking-required');
     return { status: 'not-applicable', stale_item_ids: [] };
   }
-  validateJsonSchema(tracking, path.join(root, 'docs/process/schemas/stage-tracking.schema.json'));
+  validateJsonSchema(tracking, path.join(root, '.template-spec/process/schemas/stage-tracking.schema.json'));
   const feature = checkpoint.feature_id;
   if (feature !== tracking.feature_id || typeof feature !== 'string' || !feature.trim()) throw new Error('tracking-feature-mismatch');
   const location = /^(docs\/\.scratch\/[a-z0-9][a-z0-9-]*\/)[^/]+\.(yaml|json)$/.exec(tracking.checkpoint_ref);
@@ -94,7 +94,7 @@ export function assertStageTracking(checkpoint, { root, checkpointRef, currentWo
   } else if (tracking.entry.kind !== 'parent-ticket' || tracking.entry.ref !== `${base}parent-ticket.md`) throw new Error('tracking-parent-required');
   const entry = readTracking(root, tracking.entry.ref);
   if (tracking.entry.kind === 'parent-ticket' && !entry.includes(tracking.checkpoint_ref)) throw new Error('tracking-parent-checkpoint-link-required');
-  const registry = parseYaml(readTracking(root, 'docs/process/lifecycle-registry.yaml'));
+  const registry = parseYaml(readTracking(root, '.template-spec/process/lifecycle-registry.yaml'));
   const stages = new Set(registry.stages.map(x => x.id));
   const units = new Set(registry.work_units.map(x => x.id));
   if (!stages.has(tracking.entry_stage)) throw new Error('tracking-entry-stage-invalid');

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

@@ -4,7 +4,7 @@ import { read, safe, ensure, hash, schema, project } from './strategic-handoff-i
 
 export async function verifyConsumerFeedback({root=process.cwd(),feedbackRef}={}) {
   project(root);const file=safe(root,feedbackRef),feedback=read(file);
-  schema(feedback,'docs/process/schemas/strategic-consumer-feedback.schema.json');
+  schema(feedback,'.template-spec/process/schemas/strategic-consumer-feedback.schema.json');
   const receipt=read(safe(root,feedback.import_receipt_ref));
   ensure([2,3].includes(receipt.schema_version),'Consumer Feedback v1 只接受 route-aware Import Receipt v2/v3');
   const base=`docs/handoffs/${receipt.bundle_id}/${receipt.version}`;
@@ -22,7 +22,7 @@ export async function verifyConsumerFeedback({root=process.cwd(),feedbackRef}={}
 
 export async function verifyFeedbackAdjudication({root=process.cwd(),adjudicationRef}={}) {
   project(root);const file=safe(root,adjudicationRef),adjudication=read(file);
-  schema(adjudication,'docs/process/schemas/strategic-feedback-adjudication.schema.json');
+  schema(adjudication,'.template-spec/process/schemas/strategic-feedback-adjudication.schema.json');
   const feedbackFile=safe(root,adjudication.feedback.ref);ensure(hash(readFileSync(feedbackFile))===adjudication.feedback.digest,'Feedback Adjudication 绑定的 feedback digest 已失效');
   const verified=await verifyConsumerFeedback({root,feedbackRef:adjudication.feedback.ref});
   for(const ref of adjudication.evidence_refs)ensure(readFileSync(safe(root,ref)).length>0,`Feedback Adjudication evidence 为空: ${ref}`);

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

@@ -5,13 +5,13 @@ import { read, safe, ensure } from './strategic-handoff-io.mjs';
 // Wire work-unit IDs belong to the immutable source package. Only target routing is adapted.
 export function consumerEntry(root, capability, sourceWorkUnit) {
   const scope = existsSync(path.join(root, '.yss-execution-scope.yaml')) ? read(safe(root, '.yss-execution-scope.yaml')) : null;
-  const profile = existsSync(path.join(root, 'docs/process/harness-profile.yaml')) ? read(safe(root, 'docs/process/harness-profile.yaml')) : null;
+  const profile = existsSync(path.join(root, '.template-spec/process/harness-profile.yaml')) ? read(safe(root, '.template-spec/process/harness-profile.yaml')) : null;
   const contractRef = scope || !profile ? '.agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml' : '.agents/skills/harness-orchestrator/references/orchestration-contract.yaml';
   const contract = read(safe(root, contractRef));
   const target = scope?.scope_id || profile?.profile_id || 'yss-full-lifecycle';
   const policy = contract.consumer_entry_routes?.[target]?.[capability];
   ensure(policy && policy.source_work_unit === sourceWorkUnit, `consumer-entry-unmapped: ${target}/${capability}/${sourceWorkUnit}`);
-  const registry = read(safe(root, 'docs/process/lifecycle-registry.yaml'));
+  const registry = read(safe(root, '.template-spec/process/lifecycle-registry.yaml'));
   ensure(registry.work_units.some(unit => unit.id === policy.target_work_unit), 'consumer-entry-unknown-target');
   if (scope) {
     ensure(scope.schema_version === 1, 'consumer-entry-invalid-scope');

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

@@ -14,11 +14,11 @@ const MAX_BYTES = 512 * 1024 * 1024;
 const own = (a,b) => JSON.stringify(canonical(a)) === JSON.stringify(canonical(b));
 const nonempty = x => typeof x === 'string' && x.trim();
 const bytesDigest = (bytes, kind) => kind === 'canonical-json' ? digest(parse(bytes)) : kind === 'sha256-bytes' ? hash(bytes) : (() => { throw new TypeError(`未知摘要算法: ${kind}`); })();
-const HANDOFF_SCHEMAS = new Map([[3,'docs/process/schemas/strategic-design-handoff-v3.schema.json'],[4,'docs/process/schemas/strategic-design-handoff-v4.schema.json'],[5,'docs/process/schemas/strategic-design-handoff-v5.schema.json']]);
+const HANDOFF_SCHEMAS = new Map([[3,'.template-spec/process/schemas/strategic-design-handoff-v3.schema.json'],[4,'.template-spec/process/schemas/strategic-design-handoff-v4.schema.json'],[5,'.template-spec/process/schemas/strategic-design-handoff-v5.schema.json']]);
 const SOURCE_SCHEMAS = new Map([
-  [3,['docs/process/schemas/strategic-handoff-domain-strategy.schema.json','docs/process/schemas/strategic-handoff-stage-decision-package.schema.json']],
-  [4,['docs/process/schemas/strategic-handoff-domain-strategy-v3.schema.json','docs/process/schemas/strategic-handoff-stage-decision-package-v3.schema.json']],
-  [5,['docs/process/schemas/strategic-handoff-domain-strategy-v3.schema.json','docs/process/schemas/strategic-handoff-stage-decision-package-v3.schema.json']],
+  [3,['.template-spec/process/schemas/strategic-handoff-domain-strategy.schema.json','.template-spec/process/schemas/strategic-handoff-stage-decision-package.schema.json']],
+  [4,['.template-spec/process/schemas/strategic-handoff-domain-strategy-v3.schema.json','.template-spec/process/schemas/strategic-handoff-stage-decision-package-v3.schema.json']],
+  [5,['.template-spec/process/schemas/strategic-handoff-domain-strategy-v3.schema.json','.template-spec/process/schemas/strategic-handoff-stage-decision-package-v3.schema.json']],
 ]);
 const CAPABILITIES=['backend-technical-design','frontend-engineering-design','delivery-coordination'];
 
@@ -167,7 +167,7 @@ export async function inspectSource(root, handoffRef) {
   schema(handoff,versionSchema(handoff?.schema_version,HANDOFF_SCHEMAS,'Strategic Handoff'));
   ensure(handoff.status==='approved', '交接包尚未批准');
   const config=handoff.package_export;
-  schema(config,handoff.schema_version===5?'docs/process/schemas/strategic-handoff-export-v2.schema.json':'docs/process/schemas/strategic-handoff-export.schema.json');
+  schema(config,handoff.schema_version===5?'.template-spec/process/schemas/strategic-handoff-export-v2.schema.json':'.template-spec/process/schemas/strategic-handoff-export.schema.json');
   if(handoff.schema_version===5)ensure(config.ui_baseline_kind===uiBaselineKind(handoff),'交接与导出 UI 基线类型不一致');
   const source=parseContextSource(readFileSync(safe(root,'CONTEXT.md'),'utf8'));
   snapshot(handoff.source_context_snapshot,source); checkDelta(handoff,source);
@@ -184,7 +184,7 @@ export async function inspectSource(root, handoffRef) {
   validateConsumerRoutes(handoff,stage);
   if(uiBaselineKind(handoff)==='existing-ui-baseline')ensure(stage.impact_assessment?.ui===false,'existing-ui-baseline 不支持 UI 影响，返回产品设计');
   const indexes=extractTraceability(strategy);
-  const sourceRoles=read(safe(root,'docs/agents/digital-human-roles.yaml'));
+  const sourceRoles=read(safe(root,'.template-spec/agents/digital-human-roles.yaml'));
   const roles=sourceApprovalPolicy(sourceRoles);
   for (const [artifact, version, gateId] of [[strategy,strategy.domain_version,'check.domain-strategy-approved'],[stage,stage.package_version,'check.stage-decision-package-approved']]) {
     if(artifact.approval) { const record=sourceApprovalRecord(read(safe(root,artifact.approval.approval_ref)),gateId);await sourceApproval(record,roles,root);ensure(artifact.approval.current_version===version,'资产内置批准版本过期'); }
@@ -237,7 +237,7 @@ export async function inspectSource(root, handoffRef) {
 }
 
 function collect(root, handoffRef, handoff, config) {
-  const collected=new Map(), queue=[handoffRef,'CONTEXT.md','docs/agents/digital-human-roles.yaml',...Object.values(handoff.source).map(x=>x.persisted_ref),...Object.values(config.approvals).map(x=>x.record_ref),...handoff.evidence_and_version_digests,...config.additional_files];
+  const collected=new Map(), queue=[handoffRef,'CONTEXT.md','.template-spec/agents/digital-human-roles.yaml',...Object.values(handoff.source).map(x=>x.persisted_ref),...Object.values(config.approvals).map(x=>x.record_ref),...handoff.evidence_and_version_digests,...config.additional_files];
   if(config.prototype)queue.push(config.prototype.preview_root,config.prototype.verification_ref);
   if(config.prototype?.profile==='H2')queue.push(config.prototype.source_root,config.prototype.lock_ref);
   const symbolic=config.reference_map || {};
@@ -273,7 +273,7 @@ export async function openBundle(input, action, {readOnly=false}={}) {
     let root=path.resolve(input);
     if(lstatSync(root).isFile()){ ensure(!readOnly,'readonly-extraction-required: 只读验证需要已展开目录');root=path.join(temp,'unpacked');mkdirSync(root);archive('unpack',path.resolve(input),root); }
     const manifest=read(safe(root,'manifest.json'));
-    schema(manifest,'docs/process/schemas/strategic-handoff-package.schema.json');
+    schema(manifest,'.template-spec/process/schemas/strategic-handoff-package.schema.json');
     const {bundle_digest,...body}=manifest;ensure(bundle_digest===digest(body),'包清单摘要不一致');
     const paths=manifest.files.map(x=>x.path);
     ensure(new Set(paths.map(x=>x.toLowerCase())).size===paths.length,'包文件路径重复');
@@ -352,8 +352,8 @@ export async function openDelivery(input, action) {
   ensure(isDeliveryDirectory(root),'交付目录缺少 delivery-record.json');
   ensure(!lstatSync(root).isSymbolicLink(),'交付目录不能是 symlink');
   const recordBytes=readFileSync(safe(root,'delivery-record.json'));
-  const record=parse(recordBytes);schema(record,'docs/process/schemas/strategic-handoff-delivery.schema.json');
-  const verification=read(safe(root,record.verification_ref));schema(verification,'docs/process/schemas/strategic-handoff-delivery-verification.schema.json');
+  const record=parse(recordBytes);schema(record,'.template-spec/process/schemas/strategic-handoff-delivery.schema.json');
+  const verification=read(safe(root,record.verification_ref));schema(verification,'.template-spec/process/schemas/strategic-handoff-delivery-verification.schema.json');
   const packageRoot=safe(root,record.package_ref);
   ensure(lstatSync(packageRoot).isDirectory()&&!lstatSync(packageRoot).isSymbolicLink(),'package_ref 必须指向普通目录');
   if(record.zip){const archiveRef=safe(root,record.zip.ref);ensure(lstatSync(archiveRef).isFile()&&hash(readFileSync(archiveRef))===record.zip.sha256,'ZIP 摘要不一致');}
@@ -389,11 +389,11 @@ export async function finalizeDelivery({sourceRoot,handoffRef,zip=false,previous
     const handoffEntry=await openBundle(path.join(stage,'package'),bundle=>bundle.manifest.files.find(file=>file.original_ref===handoffRef));
     ensure(handoffEntry,'交付包缺少 Handoff 源文件');
     const verification={schema_version:1,kind:'strategic-delivery-verification-v1',result:'verified',command:`scripts/strategic-handoff verify --bundle docs/deliveries/strategic/${current.handoff.handoff_id}/${current.handoff.handoff_version}`,exit_code:0,executed_at:new Date().toISOString(),package_ref:'package',manifest_ref:'package/manifest.json',bundle_digest:exported.bundle_digest};
-    schema(verification,'docs/process/schemas/strategic-handoff-delivery-verification.schema.json');write(stage,'verification.json',json(verification));
+    schema(verification,'.template-spec/process/schemas/strategic-handoff-delivery-verification.schema.json');write(stage,'verification.json',json(verification));
     const sourceAssets=Object.entries(current.handoff.source).sort(([a],[b])=>a.localeCompare(b)).map(([sourceKey,value])=>({source_key:sourceKey,id:value.id||value.baseline_id,version:value.version,ref:value.persisted_ref,digest:value.digest}));
     const previousDelivery=await openBundle(path.join(stage,'package'),bundle=>bundle.manifest.previous_bundle?{handoff_id:bundle.manifest.previous_bundle.bundle_id,version:bundle.manifest.previous_bundle.version,bundle_digest:bundle.manifest.previous_bundle.digest}:null);
     const record={schema_version:1,kind:'strategic-handoff-delivery-v1',status:'packaged',handoff:{id:current.handoff.handoff_id,version:current.handoff.handoff_version,ref:handoffRef,sha256:handoffEntry.sha256,schema_version:5},source_assets:sourceAssets,package_ref:'package',manifest_ref:'package/manifest.json',bundle_digest:exported.bundle_digest,verification_ref:'verification.json',consumer_routes:current.handoff.consumer_routes.map(({route_id,capability,activation})=>({route_id,capability,activation})),...(zip?{zip:{ref:'package.zip',sha256:exported.zip_sha256}}:{}),previous_delivery:previousDelivery};
-    schema(record,'docs/process/schemas/strategic-handoff-delivery.schema.json');write(stage,'delivery-record.json',json(record));
+    schema(record,'.template-spec/process/schemas/strategic-handoff-delivery.schema.json');write(stage,'delivery-record.json',json(record));
     await openDelivery(stage,()=>null);
     if(existsSync(delivery)){
       const existing=await openDelivery(delivery,value=>value.record);
@@ -432,7 +432,7 @@ export async function importBundle({bundle,targetRoot}) {
         write(stage,'tactical-traceability-draft.json',json({schema_version:1,import_receipt_ref:`${rel}/import-receipt.json`,bundle_digest:b.manifest.bundle_digest,rows}));
         write(stage,'upstream-change-impact.json',json({schema_version:1,previous_bundle:b.manifest.previous_bundle,changed_source_ids:[...b.changes.updated,...b.changes.removed],added_source_ids:b.changes.added,status:'requires-lifecycle-reconciliation',policy:'mark-dependent-tactical-and-slice-contracts-stale; unknown-dependency-blocks-all'}));
       }else{
-        const profileRef=path.join(target,'docs/process/harness-profile.yaml');
+        const profileRef=path.join(target,'.template-spec/process/harness-profile.yaml');
         const profile=existsSync(profileRef)?read(profileRef):null;
         const capabilities=scopedConsumerCapabilities(target,profile?.handoff?.consumer_capabilities||CAPABILITIES);
         ensure(Array.isArray(capabilities)&&capabilities.length&&capabilities.every(capability=>CAPABILITIES.includes(capability)),'目标 profile 未声明受支持的消费者能力');
@@ -449,7 +449,7 @@ export async function importBundle({bundle,targetRoot}) {
         const fromDelivery=Boolean(b.recordBytes);
         if(fromDelivery)write(stage,'source-delivery-record.json',b.recordBytes);
         receipt={schema_version:fromDelivery?3:2,bundle_id:b.manifest.bundle_id,version:b.manifest.version,bundle_digest:b.manifest.bundle_digest,package_ref:`${rel}/package`,...(fromDelivery?{source_delivery_record_ref:`${rel}/source-delivery-record.json`,source_delivery_record_sha256:hash(b.recordBytes),ready_for_agent:false}:{}),target_context_digest:context.document_digest,target_profile_id:profile?.profile_id||'yss-full-lifecycle',selected_consumer_capabilities:capabilities,routes:routeRecords,status:'pending-context-reconciliation'};
-        schema(receipt,fromDelivery?'docs/process/schemas/strategic-handoff-import-receipt-v3.schema.json':'docs/process/schemas/strategic-handoff-import-receipt.schema.json');
+        schema(receipt,fromDelivery?'.template-spec/process/schemas/strategic-handoff-import-receipt-v3.schema.json':'.template-spec/process/schemas/strategic-handoff-import-receipt.schema.json');
         write(stage,'import-receipt.json',json(receipt));
         write(stage,'context-reconciliation-draft.json',json({schema_version:2,status:'draft',import_receipt_ref:`${rel}/import-receipt.json`,target_context_digest:context.document_digest,route_ids:selected.map(route=>route.route_id),terms}));
         write(stage,'upstream-change-impact.json',json({schema_version:2,previous_bundle:b.manifest.previous_bundle,routes:selected.map(route=>({route_id:route.route_id,capability:route.capability,activation:route.activation,changed_source_ids:[...b.changes.updated,...b.changes.removed],added_source_ids:b.changes.added,status:'requires-lifecycle-reconciliation'})),policy:'mark-only-known-dependent-contracts-stale; unknown-dependency-or-design-basis-change-blocks-all'}));
@@ -459,7 +459,7 @@ export async function importBundle({bundle,targetRoot}) {
         if(capabilities.includes('backend-technical-design')&&backendRoute.activation!=='not-applicable')write(stage,'backend-technical-traceability-draft.json',json({schema_version:2,route_id:backendRoute.route_id,import_receipt_ref:`${rel}/import-receipt.json`,bundle_digest:b.manifest.bundle_digest,rows}));
         if(capabilities.includes('frontend-engineering-design')&&frontendRoute.activation!=='not-applicable'){
           const preflight={schema_version:b.handoff.schema_version===5?2:1,status:'draft',route_id:frontendRoute.route_id,capability:frontendRoute.capability,import_receipt_ref:`${rel}/import-receipt.json`,bundle_digest:b.manifest.bundle_digest,context_reconciliation_ref:'',...(b.handoff.schema_version===5?{ui_baseline_kind:uiBaselineKind(b.handoff),ui_baseline_ref:`${rel}/package/payload/files/${uiBaselineRef(b.handoff).persisted_ref}/${uiBaselineRef(b.handoff).manifest_ref}`}:{visual_baseline_ref:`${rel}/package/payload/files/${uiBaselineRef(b.handoff).persisted_ref}/${uiBaselineRef(b.handoff).manifest_ref}`}),source_rule_refs:rows.map(row=>row.source_id),backend_dependency:{mode:backendRoute.activation==='not-applicable'?'not-applicable':'required',route_id:backendRoute.route_id,...(backendRoute.activation==='not-applicable'?{reason:backendRoute.reason,impact_refs:backendRoute.impact_refs,evidence_refs:backendRoute.evidence_refs}:{})},ready_for_agent:false};
-          schema(preflight,b.handoff.schema_version===5?'docs/process/schemas/frontend-strategic-preflight-v2.schema.json':'docs/process/schemas/frontend-strategic-preflight.schema.json');
+          schema(preflight,b.handoff.schema_version===5?'.template-spec/process/schemas/frontend-strategic-preflight-v2.schema.json':'.template-spec/process/schemas/frontend-strategic-preflight.schema.json');
           write(stage,'frontend-strategic-preflight-draft.json',json(preflight));write(stage,'frontend-traceability-draft.json',json({schema_version:1,route_id:frontendRoute.route_id,import_receipt_ref:`${rel}/import-receipt.json`,bundle_digest:b.manifest.bundle_digest,rows:rows.map(({tactical_refs,test_seam_refs,...row})=>({...row,frontend_case_refs:[]}))}));
         }
         if(capabilities.includes('delivery-coordination')&&coordinationRoute.activation!=='not-applicable')write(stage,'consumer-status-index-draft.json',json({schema_version:1,status:'draft',import_receipt_ref:`${rel}/import-receipt.json`,routes:b.handoff.consumer_routes.map(route=>({route_id:route.route_id,capability:route.capability,activation:route.activation,consumer_status:route.activation==='not-applicable'?'not-applicable':'pending',receipt_refs:[],acceptance_refs:[],feedback_refs:[]}))}));

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

@@ -2,8 +2,8 @@ import path from "node:path";
 import { ROOT } from "./lifecycle-registry.mjs";
 import { validateJsonSchema } from "./json-schema.mjs";
 
-export const TASK_PACKAGE_SCHEMA = path.join(ROOT, "docs/process/schemas/digital-human-task-package.schema.json");
-export const LEGACY_TASK_PACKAGE_SCHEMA = path.join(ROOT, "docs/process/schemas/subagent-task-package.schema.json");
+export const TASK_PACKAGE_SCHEMA = path.join(ROOT, ".template-spec/process/schemas/digital-human-task-package.schema.json");
+export const LEGACY_TASK_PACKAGE_SCHEMA = path.join(ROOT, ".template-spec/process/schemas/subagent-task-package.schema.json");
 
 export function validateTaskPackageSchema(value, schemaPath = TASK_PACKAGE_SCHEMA) {
   const effectiveSchema = path.resolve(schemaPath) === path.resolve(LEGACY_TASK_PACKAGE_SCHEMA) ? TASK_PACKAGE_SCHEMA : schemaPath;

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

@@ -16,7 +16,7 @@ import { enforceFrontendDelivery } from "./frontend-delivery-boundary.mjs";
 import { LEGACY_TASK_PACKAGE_SCHEMA, TASK_PACKAGE_SCHEMA, validateTaskPackageSchema } from "./task-package-schema.mjs";
 
 export { LEGACY_TASK_PACKAGE_SCHEMA, TASK_PACKAGE_SCHEMA, validateTaskPackageSchema };
-export const TASK_PACKAGE_REGISTRY_REF = "docs/agents/digital-human-roles.yaml";
+export const TASK_PACKAGE_REGISTRY_REF = ".template-spec/agents/digital-human-roles.yaml";
 export const CONTRACT_KINDS = new Set(["lifecycle-work-unit", "slice-implementation", "template-maintenance"]);
 export const EXECUTION_STATES = new Set(["Explorer", "Drafter", "Worker", "Reviewer", "Verifier"]);
 export const WORKFLOW_STATUSES = new Set(["not-started", "active", "paused", "resolved", "failed"]);

package/template/scripts/lib/technical-design-boundary.mjs

@@ -30,5 +30,5 @@ export function enforceTechnicalDesign(state = {}, { root = ROOT, execution, rea
   if(inValidationPhase())args.push('--validation-dependencies');
   const verified = spawnSync(process.execPath, args, { cwd: root, encoding: 'utf8', timeout: 60000, maxBuffer: 2 * 1024 * 1024 });
   ensure(verified.status === 0, `技术设计不可消费: ${verified.error?.message || verified.stderr}`);
-  if(inValidationPhase()){let output;try{output=JSON.parse(verified.stdout);}catch{throw new TypeError('VALIDATION_RECEIPT_INVALID: 技术设计子进程未返回依赖');}const dependencies=output.validation_dependencies;const required=[file,...(execution?[path.resolve(root,approvedExecutionBinding(execution).ref),path.resolve(root,approvedExecutionBinding(execution).approval_ref),path.resolve(root,'docs/agents/digital-human-roles.yaml')]:[])];ensure(required.every(ref=>dependencies?.files?.some(row=>row.file===ref)),'VALIDATION_RECEIPT_INVALID: 技术设计依赖报告缺少必要原始资产');acceptValidationDependencies(dependencies);}
+  if(inValidationPhase()){let output;try{output=JSON.parse(verified.stdout);}catch{throw new TypeError('VALIDATION_RECEIPT_INVALID: 技术设计子进程未返回依赖');}const dependencies=output.validation_dependencies;const required=[file,...(execution?[path.resolve(root,approvedExecutionBinding(execution).ref),path.resolve(root,approvedExecutionBinding(execution).approval_ref),path.resolve(root,'.template-spec/agents/digital-human-roles.yaml')]:[])];ensure(required.every(ref=>dependencies?.files?.some(row=>row.file===ref)),'VALIDATION_RECEIPT_INVALID: 技术设计依赖报告缺少必要原始资产');acceptValidationDependencies(dependencies);}
 }

package/template/scripts/lib/user-decision.mjs

@@ -81,7 +81,7 @@ function checkAsset(asset, io) {
 export function validateUserDecision(record, options = {}) {
   const io = decisionIO(options);
   const policy = (options.rolesDoc || loadDigitalHumanRoles()).user_decision_policy;
-  validateJsonSchema(record, path.join(ROOT, "docs/process/schemas/user-decision.schema.json"), { label: "用户决定记录" });
+  validateJsonSchema(record, path.join(ROOT, ".template-spec/process/schemas/user-decision.schema.json"), { label: "用户决定记录" });
   const { request, responses } = record;
   const originalRequest = messageFromSource(request.requester_source, io, policy);
   if (originalRequest.actor_kind !== "biological-human" || originalRequest.principal_ref !== request.requester_ref) decisionError("user-decision-responder-mismatch", "提问者来源不匹配");
@@ -164,6 +164,7 @@ export function verifyUserDecisionFile(ref, options = {}) {
 
 export function assertUserDecisionRequirement(requirement, options = {}) {
   if (!requirement) decisionError("user-decision-response-required", "缺少当前决定及其范围");
+  if (requirement.user_decision_ref && requirement.continuation_ref) decisionError("user-decision-proof-conflict", "当前决定与批准延续是两种证明路径，不得同时提供");
   if (requirement.continuation_ref) return assertDecisionContinuation(requirement, options.rolesDoc || loadDigitalHumanRoles(), options);
   return verifyUserDecisionFile(requirement.user_decision_ref, { ...options, expected: [requirement] });
 }

package/template/scripts/lifecycle-status

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import path from 'node:path';
+import { lifecycleStatus } from './lib/lifecycle-status.mjs';
+
+try {
+  const { values } = parseArgs({ strict: true, options: { root: { type: 'string' }, checkpoint: { type: 'string' } } });
+  const result = lifecycleStatus({ root: path.resolve(values.root ?? '.'), checkpointRef: values.checkpoint });
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  if (result.blockers.length) process.exitCode = 1;
+} catch (error) {
+  process.stdout.write(`${JSON.stringify({ schema_version: 1, read_only: true, blockers: [error.message], owner: '未登记', next_action: `核查状态输入：${error.message}`, execution_authorization: 'not-evaluated', verification_scope: [{ id: 'status-input', status: 'failed', refs: [], reason: error.message }], diagnostics: [{ code: 'status-input-invalid', severity: 'error', message: error.message, source_ref: null, owner: '未登记', recovery: '修复输入后重新读取状态' }], next_step: { action_type: 'repair', command: null, input_refs: [], prerequisites: ['提供有效项目根和 checkpoint 引用'] } }, null, 2)}\n`);
+  process.exitCode = 1;
+}

package/template/scripts/plan-spec-entry

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import path from 'node:path';
+import { preparePlanSpecEntry, diffPlanSpecEntry } from './lib/plan-spec-entry-view.mjs';
+
+try {
+  const [operation, ...args] = process.argv.slice(2);
+  const { values } = parseArgs({ args, strict: true, options: {
+    root: { type: 'string' }, feature: { type: 'string' }, plan: { type: 'string' },
+    'context-reconciliation': { type: 'string' }, review: { type: 'string' },
+  } });
+  const root = path.resolve(values.root ?? '.');
+  let result;
+  if (operation === 'prepare') result = preparePlanSpecEntry({ root, featureId: values.feature, planRef: values.plan, contextRef: values['context-reconciliation'] });
+  else if (operation === 'diff') result = diffPlanSpecEntry({ root, reviewRef: values.review });
+  else throw new TypeError('用法: scripts/plan-spec-entry prepare --root <项目> --feature <id> --plan <ref> --context-reconciliation <ref> | diff --root <项目> --review <ref>');
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+} catch (error) {
+  process.stdout.write(`${JSON.stringify({ schema_version: 1, status: 'blocked', blocking_signals: ['plan-spec-entry-input-unavailable'], missing_requirements: [error.message], approval_created: false }, null, 2)}\n`);
+  process.exitCode = 1;
+}

package/template/scripts/strategic-consumer-entry

@@ -27,7 +27,7 @@ try {
   }
   const receipt = read(safe(root, receiptRef));
   ensure([2, 3].includes(receipt.schema_version), 'design-entry-receipt-version');
-  schema(receipt, receipt.schema_version === 3 ? 'docs/process/schemas/strategic-handoff-import-receipt-v3.schema.json' : 'docs/process/schemas/strategic-handoff-import-receipt.schema.json');
+  schema(receipt, receipt.schema_version === 3 ? '.template-spec/process/schemas/strategic-handoff-import-receipt-v3.schema.json' : '.template-spec/process/schemas/strategic-handoff-import-receipt.schema.json');
   const base = `docs/handoffs/${receipt.bundle_id}/${receipt.version}`;
   ensure(receiptRef === `${base}/import-receipt.json` && receipt.package_ref === `${base}/package`, 'design-entry-receipt-path');
   const entry = await openBundle(safe(root, receipt.package_ref), inspect);

package/template/scripts/strategic-handoff

@@ -8,7 +8,7 @@ import { read, safe, ensure } from './lib/strategic-handoff-io.mjs';
 async function preflightExport(values) {
   const root=path.resolve(values['source-root']),handoff=read(safe(root,values.handoff));
   const required=handoff.schema_version===5&&handoff.ui_baseline_kind==='existing-ui-baseline';
-  ensure(!required||values['preflight-input'],'preflight-required: 既有 UI 战略导出必须提供 --preflight-input <file>；先按 docs/process/delivery-preflight.md 准备源资产清单并执行 export 阶段只读预检');
+  ensure(!required||values['preflight-input'],'preflight-required: 既有 UI 战略导出必须提供 --preflight-input <file>；先按 .template-spec/process/delivery-preflight.md 准备源资产清单并执行 export 阶段只读预检');
   if(!values['preflight-input'])return;
   const {preflightDelivery}=await import('./lib/delivery-preflight.mjs');
   const input=read(path.resolve(values['preflight-input']));

package/template/scripts/verify-frontend-implementation-evidence

@@ -9,7 +9,7 @@ import { validateVisualBaseline } from "../.agents/skills/yss-prototype-stage/sc
 import { enforceFrontendDelivery } from "./lib/frontend-delivery-boundary.mjs";
 
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
-const schemaPath = path.join(repoRoot, "docs/process/schemas/frontend-implementation-evidence.schema.json");
+const schemaPath = path.join(repoRoot, ".template-spec/process/schemas/frontend-implementation-evidence.schema.json");
 const validator = String.raw`
 import json
 import sys