create-yss-spec 3.3.0 → 3.3.3

package/template/scripts/instantiate-harness

@@ -1,69 +0,0 @@
-#!/usr/bin/env node
-// Repository-local distribution for the two dedicated Harness templates.
-import { existsSync, readFileSync, mkdirSync, mkdtempSync, renameSync, rmSync, statSync, lstatSync, readlinkSync, realpathSync, symlinkSync, chmodSync } from 'node:fs';
-import { execFileSync } from 'node:child_process';
-import path from 'node:path';
-import { ROOT, read, safe, ensure, hash, digest, write, json } from './lib/strategic-handoff-io.mjs';
-
-try {
-  const args=process.argv.slice(2),options={};
-  while(args.length) {
-    const key=args.shift();
-    if(key==='--allow-working-tree')options.working=true;
-    else if(['--target','--project-name'].includes(key)) {ensure(args.length&&!args[0].startsWith('--'),`${key} 缺少值`);options[key.slice(2)]=args.shift();}
-    else throw new Error(`未知参数 ${key}；使用 --target <新目录> [--project-name <名称>]`);
-  }
-  ensure(options.target,'必须指定 --target <新目录>');
-  const identity=read(safe(ROOT,'yss-project.yaml'));
-  ensure(identity.schema_version===1&&identity.repository_mode==='template-source','仅模板源可初始化新项目');
-  const profile=read(safe(ROOT,'docs/process/harness-profile.yaml'));
-  ensure(['harness.backend-delivery','harness.frontend-delivery'].includes(profile.profile_id),'仅支持后端/前端专职模板');
-  const target=path.resolve(options.target);
-  ensure(!target.startsWith(ROOT+path.sep)&&!ROOT.startsWith(target+path.sep)&&target!==ROOT,'目标不得包含模板源或位于模板源内');
-  ensure(!existsSync(target),'目标已存在；不覆盖或静默转换既有项目 profile');
-  const git=args=>execFileSync('git',args,{cwd:ROOT,encoding:'utf8',maxBuffer:16*1024*1024}).trim();
-  const commit=git(['rev-parse','HEAD']);
-  ensure(/^[0-9a-f]{40}$/.test(commit),'模板必须有不可变 Git 提交');
-  const dirty=Boolean(git(['status','--porcelain','--untracked-files=all']));
-  ensure(!dirty||options.working,'模板工作树未提交；维护测试可显式使用 --allow-working-tree，正式分发须先提交');
-  const manifest=read(safe(ROOT,profile.instantiation.distribution_manifest));
-  const names=execFileSync('git',['ls-files','-co','--exclude-standard','-z'],{cwd:ROOT,encoding:'utf8',maxBuffer:16*1024*1024}).split('\0').filter(Boolean);
-  const prefix=(ref,base)=>ref===base||ref.startsWith(base+'/');
-  const selected=[...new Set(names)].filter(ref=>{
-    const top=ref.split('/')[0];
-    const allowed=(manifest.allowRootEntries||[]).includes(top)||(manifest.allowRootFiles||[]).includes(ref)||(manifest.allowFiles||[]).includes(ref);
-    return allowed&&![...(manifest.excludeRootEntries||[]),...(manifest.initExcludeRootEntries||[])].includes(top)
-      &&![...(manifest.excludeRootFiles||[]),...(manifest.initExcludeRootFiles||[])].includes(ref)
-      &&![...(manifest.excludePaths||[]),...(manifest.initExcludePaths||[])].some(excluded=>prefix(ref,excluded));
-  }).sort();
-  ensure(selected.includes('yss-project.yaml')&&selected.includes('AGENTS.md')&&selected.includes('CONTEXT.md'),'分发缺少入口合同');
-  const capture=ref=>{
-    const file=path.join(ROOT,ref);if(path.dirname(ref)!=='.')safe(ROOT,path.dirname(ref));
-    if(lstatSync(file).isSymbolicLink()) {
-      const link=readlinkSync(file),resolved=realpathSync(file);
-      ensure(!path.isAbsolute(link)&&resolved.startsWith(path.join(ROOT,'.agents/skills')+path.sep),'仅允许指向本仓 canonical skills 的相对投影链接');
-      return {ref,link,bytes:Buffer.from(`symlink:${link}`),mode:0o777};
-    }
-    return {ref,bytes:readFileSync(safe(ROOT,ref)),mode:statSync(file).mode&0o777};
-  };
-  const captured=selected.map(capture);
-  const sourceFiles=captured.map(({ref,bytes,mode})=>({ref,digest:hash(bytes),mode}));
-  const sourceDigest=digest(sourceFiles);
-  mkdirSync(path.dirname(target),{recursive:true});
-  const staging=mkdtempSync(path.join(path.dirname(target),'.harness-init-'));
-  try {
-    const managed={};
-    for(const file of captured) {
-      let bytes=file.bytes;
-      if(file.ref==='yss-project.yaml') bytes=Buffer.from('schema_version: 1\nrepository_mode: project-instance\n');
-      if(file.ref==='README.md') bytes=Buffer.from(`# ${options['project-name']||path.basename(target)}\n\n本仓是 \`${profile.profile_id}\` 的 \`project-instance\`。先读 [AGENTS.md](AGENTS.md)、根 CONTEXT.md 与 [profile](docs/process/harness-profile.yaml)。接力输入与执行条件见 [交付合同](docs/process/frontend-backend-delivery.md)。\n`);
-      if(file.link) {mkdirSync(path.dirname(path.join(staging,file.ref)),{recursive:true});symlinkSync(file.link,path.join(staging,file.ref));}
-      else {write(staging,file.ref,bytes);chmodSync(path.join(staging,file.ref),file.mode);}
-      managed[file.ref]={digest:hash(bytes),mode:file.mode};
-    }
-    write(staging,profile.instantiation.metadata_file,json({schema_version:1,profile_id:profile.profile_id,template_source:profile.instantiation.template_source,template_commit:commit,source_tree_digest:sourceDigest,source_files:sourceFiles,source_working_tree:dirty,release_snapshot:!dirty,managed_files:managed}));
-    for(const {ref,bytes} of captured)ensure(hash(capture(ref).bytes)===hash(bytes),`初始化期间模板变化: ${ref}`);
-    ensure(!existsSync(target),'目标目录并发冲突');renameSync(staging,target);
-    process.stdout.write(json({result:'initialized',profile_id:profile.profile_id,target,template_commit:commit,source_tree_digest:sourceDigest,release_snapshot:!dirty}));
-  } finally {rmSync(staging,{recursive:true,force:true});}
-} catch(error) {process.stderr.write(`${error.message}\n`);process.exitCode=1;}

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

@@ -1,160 +0,0 @@
-import { spawnSync } from "node:child_process";
-import { createHash } from "node:crypto";
-import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import path from "node:path";
-import { parseDocument, stringify } from "../vendor/yaml.mjs";
-
-const MAGIC = Buffer.from("YSS-WORKTREE-CANDIDATE-V1\0", "ascii");
-const MAX_BUFFER = 512 * 1024 * 1024;
-const MAINTENANCE_EVIDENCE_ROOT = ".template-source/evidence/maintenance";
-const CANDIDATE_FILES = ["candidate-manifest.yaml", "candidate.bin", "tracked.diff"];
-
-function fail(message) { throw new TypeError(message); }
-function ensure(condition, message) { if (!condition) fail(message); }
-function git(args, root, encoding = "utf8") {
-  const result = spawnSync("git", args, { cwd: root, encoding, maxBuffer: MAX_BUFFER });
-  if (result.status !== 0) fail((typeof result.stderr === "string" ? result.stderr : result.stderr?.toString()).trim() || `git ${args.join(" ")} 执行失败`);
-  return result.stdout;
-}
-function uint64(value) { const buffer = Buffer.alloc(8); buffer.writeBigUInt64BE(BigInt(value)); return buffer; }
-function uint32(value) { const buffer = Buffer.alloc(4); buffer.writeUInt32BE(value >>> 0); return buffer; }
-function splitNull(buffer) {
-  const result = [];
-  let start = 0;
-  for (let index = 0; index < buffer.length; index += 1) if (buffer[index] === 0) { if (index > start) result.push(buffer.subarray(start, index)); start = index + 1; }
-  if (start < buffer.length) result.push(buffer.subarray(start));
-  return result;
-}
-function normalizeRelative(value, label) {
-  ensure(typeof value === "string" && value.trim(), `${label} 不能为空`);
-  const normalized = value.replaceAll("\\", "/").replace(/^\.\//, "").replace(/\/$/, "");
-  ensure(normalized && !path.posix.isAbsolute(normalized) && path.posix.normalize(normalized) === normalized && normalized !== ".." && !normalized.startsWith("../"), `${label} 必须是规范的仓库内相对路径`);
-  return normalized;
-}
-function isMaintenanceEvidencePath(value) {
-  return value === MAINTENANCE_EVIDENCE_ROOT || value.startsWith(`${MAINTENANCE_EVIDENCE_ROOT}/`);
-}
-function readLength(buffer, offset, bytes, label) {
-  ensure(offset + bytes <= buffer.length, `packed candidate 缺少 ${label}`);
-  const value = bytes === 8 ? buffer.readBigUInt64BE(offset) : BigInt(buffer.readUInt32BE(offset));
-  ensure(value <= BigInt(Number.MAX_SAFE_INTEGER), `packed candidate ${label} 过大`);
-  return { value: Number(value), offset: offset + bytes };
-}
-
-export function captureMaintenanceCandidate({ root, outputDir, baseRef = "HEAD", excludePaths = [] }) {
-  const repositoryRoot = path.resolve(root);
-  const outputPath = path.resolve(repositoryRoot, outputDir);
-  const outputRelative = normalizeRelative(path.relative(repositoryRoot, outputPath).replaceAll(path.sep, "/"), "outputDir");
-  ensure(isMaintenanceEvidencePath(outputRelative), `outputDir 必须位于 ${MAINTENANCE_EVIDENCE_ROOT}`);
-  ensure(!existsSync(outputPath), "outputDir 必须不存在，禁止复用可能含残留文件的候选目录");
-  ensure(Array.isArray(excludePaths), "excludePaths 必须是数组");
-  const explicitExclusions = excludePaths.map((value) => normalizeRelative(value, "excludePaths"));
-  for (const exclusion of explicitExclusions) ensure(isMaintenanceEvidencePath(exclusion), `excludePaths 只允许 ${MAINTENANCE_EVIDENCE_ROOT} 下的维护证据`);
-  const exclusions = [...new Set([outputRelative, ...explicitExclusions])];
-  const mergeBase = git(["merge-base", baseRef, "HEAD"], repositoryRoot).trim();
-  const trackedDiff = git(["diff", "--no-ext-diff", "--binary", "--full-index", mergeBase], repositoryRoot, null);
-  const rawPaths = splitNull(git(["ls-files", "-z", "--others", "--exclude-standard"], repositoryRoot, null))
-    .filter((rawPath) => {
-      const value = rawPath.toString();
-      return !exclusions.some((exclusion) => value === exclusion || value.startsWith(`${exclusion}/`));
-    })
-    .sort(Buffer.compare);
-  ensure(trackedDiff.length > 0 || rawPaths.length > 0, "维护候选不能为空");
-
-  const parts = [MAGIC, Buffer.from([0x54]), uint64(trackedDiff.length), trackedDiff];
-  const untrackedFiles = [];
-  const untrackedPathBytes = [];
-  for (const rawPath of rawPaths) {
-    ensure(!rawPath.includes(0) && rawPath.length > 0, "untracked path 无效");
-    const relative = rawPath.toString();
-    const absolute = path.resolve(repositoryRoot, relative);
-    ensure(!path.relative(repositoryRoot, absolute).startsWith(".."), `untracked path 越界: ${relative}`);
-    const stat = lstatSync(absolute);
-    let kind;
-    let content;
-    if (stat.isFile()) { kind = 0x52; content = readFileSync(absolute); }
-    else if (stat.isSymbolicLink()) { kind = 0x4c; content = readlinkSync(absolute, { encoding: "buffer" }); }
-    else fail(`候选包含不支持的 untracked 类型: ${relative}`);
-    parts.push(Buffer.from([0x55]), uint64(rawPath.length), rawPath, uint32(stat.mode), Buffer.from([kind]), uint64(content.length), content);
-    untrackedFiles.push(relative);
-    untrackedPathBytes.push(rawPath.toString("base64"));
-  }
-  const stream = Buffer.concat(parts);
-  const digest = createHash("sha256").update(stream).digest("hex");
-  const streamRef = `${outputRelative}/candidate.bin`;
-  const diffRef = `${outputRelative}/tracked.diff`;
-  const manifestRef = `${outputRelative}/candidate-manifest.yaml`;
-  const manifest = {
-    schema_version: 1,
-    candidate_kind: "yss-worktree-candidate-v1",
-    storage: "packed-stream",
-    review_mode: "worktree",
-    review_base_ref: baseRef,
-    merge_base: mergeBase,
-    implementation_candidate_ref: "working-tree",
-    candidate_snapshot_ref: manifestRef,
-    candidate_digest: digest,
-    tracked_diff_command: `git diff --no-ext-diff --binary --full-index ${mergeBase}`,
-    untracked_inventory_command: "git ls-files -z --others --exclude-standard",
-    untracked_diff_command: "packed in candidate.bin",
-    untracked_files: untrackedFiles,
-    untracked_path_bytes: untrackedPathBytes,
-    excluded_paths: exclusions,
-    snapshot_stream_ref: streamRef,
-    tracked_diff_ref: diffRef,
-    commit_list_command: `git log ${baseRef}..HEAD --oneline`
-  };
-  const outputParent = path.dirname(outputPath);
-  mkdirSync(outputParent, { recursive: true });
-  const stagingPath = mkdtempSync(path.join(outputParent, ".candidate-staging-"));
-  try {
-    writeFileSync(path.join(stagingPath, "candidate.bin"), stream);
-    writeFileSync(path.join(stagingPath, "tracked.diff"), trackedDiff);
-    writeFileSync(path.join(stagingPath, "candidate-manifest.yaml"), stringify(manifest, { lineWidth: 0 }));
-    renameSync(stagingPath, outputPath);
-  } finally {
-    if (existsSync(stagingPath)) rmSync(stagingPath, { recursive: true, force: true });
-  }
-  return { candidate_digest: digest, manifest, manifest_ref: manifestRef, files: [manifestRef, streamRef, diffRef] };
-}
-
-export function inspectMaintenanceCandidate({ manifestPath }) {
-  const absoluteManifest = path.resolve(manifestPath);
-  const document = parseDocument(readFileSync(absoluteManifest, "utf8"), { uniqueKeys: true });
-  ensure(document.errors.length === 0, document.errors[0]?.message || "candidate manifest 无法解析");
-  const manifest = document.toJS({ maxAliasCount: 0 });
-  ensure(manifest.storage === "packed-stream", "只支持 packed-stream candidate");
-  const candidateDir = path.dirname(absoluteManifest);
-  ensure(JSON.stringify(readdirSync(candidateDir).sort()) === JSON.stringify([...CANDIDATE_FILES].sort()), `packed candidate 目录必须恰好包含 ${CANDIDATE_FILES.join("、")}`);
-  const root = path.resolve(path.dirname(absoluteManifest), ...Array(manifest.candidate_snapshot_ref.split("/").length - 1).fill(".."));
-  ensure(path.resolve(root, manifest.candidate_snapshot_ref) === absoluteManifest, "candidate_snapshot_ref 未绑定当前 manifest");
-  const streamPath = path.resolve(root, manifest.snapshot_stream_ref);
-  const diffPath = path.resolve(root, manifest.tracked_diff_ref);
-  ensure(streamPath === path.join(candidateDir, "candidate.bin") && diffPath === path.join(candidateDir, "tracked.diff"), "packed candidate 引用必须绑定同目录规范文件");
-  const stream = readFileSync(streamPath);
-  ensure(createHash("sha256").update(stream).digest("hex") === manifest.candidate_digest.replace(/^sha256:/, ""), "candidate_digest 与 packed stream 不一致");
-  ensure(stream.subarray(0, MAGIC.length).equals(MAGIC), "packed stream magic 无效");
-  let offset = MAGIC.length;
-  ensure(stream[offset] === 0x54, "packed stream 缺少 tracked record");
-  offset += 1;
-  let length = readLength(stream, offset, 8, "tracked length");
-  offset = length.offset;
-  const trackedDiff = stream.subarray(offset, offset + length.value);
-  offset += length.value;
-  ensure(readFileSync(diffPath).equals(trackedDiff), "tracked.diff 与 packed stream 不一致");
-  const entries = [];
-  while (offset < stream.length) {
-    ensure(stream[offset] === 0x55, "packed stream record kind 无效");
-    offset += 1;
-    length = readLength(stream, offset, 8, "path length"); offset = length.offset;
-    const rawPath = stream.subarray(offset, offset + length.value); offset += length.value;
-    length = readLength(stream, offset, 4, "mode"); offset = length.offset;
-    const mode = length.value;
-    const kind = stream[offset]; offset += 1;
-    length = readLength(stream, offset, 8, "content length"); offset = length.offset;
-    const content = stream.subarray(offset, offset + length.value); offset += length.value;
-    entries.push({ path: rawPath.toString(), path_bytes: rawPath.toString("base64"), mode, kind: kind === 0x52 ? "regular" : "symlink", content });
-  }
-  ensure(JSON.stringify(entries.map((entry) => entry.path_bytes)) === JSON.stringify(manifest.untracked_path_bytes), "manifest inventory 与 packed stream 不一致");
-  return { manifest, trackedDiff, entries };
-}

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

@@ -1,168 +0,0 @@
-import { readFileSync } from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { parseDocument } from "../vendor/yaml.mjs";
-import { validateMaintenanceReviewEvidence } from "./maintenance-review.mjs";
-
-const LEVELS = ["L1", "L2", "L3"];
-const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
-const INTENSITY_POLICY = path.join(root, "docs/process/maintenance-intensity.yaml");
-
-const REQUIRED_EVIDENCE = {
-  L1: ["relevant-check"],
-  L2: ["counterexample", "fresh-verification", "focused-independent-review"],
-  L3: ["fresh-verification", "self-check"]
-};
-
-const REVIEW_MODES = {
-  L1: new Set(["self-check", "human-checkpoint"]),
-  L2: new Set(["focused-independent"]),
-  L3: new Set(["self-check", "formal-independent"])
-};
-
-function ensure(condition, message) {
-  if (!condition) throw new TypeError(message);
-}
-
-function loadTriggerLevels() {
-  const document = parseDocument(readFileSync(INTENSITY_POLICY, "utf8"), { uniqueKeys: true });
-  ensure(document.errors.length === 0, document.errors[0]?.message || "维护强度策略无法解析");
-  const policy = document.toJS({ maxAliasCount: 0 });
-  ensure(policy?.schema_version === 1 && LEVELS.includes(policy.default_level) && policy.levels && typeof policy.levels === "object", "维护强度策略 schema 无效");
-  const pairs = [];
-  for (const level of LEVELS) {
-    const triggers = policy.levels[level]?.triggers;
-    ensure(Array.isArray(triggers) && triggers.length > 0, `维护强度策略缺少 ${level} triggers`);
-    for (const trigger of triggers) {
-      ensure(typeof trigger === "string" && trigger.trim(), `${level} 包含无效 trigger`);
-      pairs.push([trigger, level]);
-    }
-  }
-  const map = new Map(pairs);
-  ensure(map.size === pairs.length, "维护强度策略包含重复 trigger");
-  return { defaultLevel: policy.default_level, map };
-}
-
-const triggerLevels = loadTriggerLevels();
-
-function levelRank(level) {
-  return LEVELS.indexOf(level);
-}
-
-export function minimumIntensity(triggers) {
-  ensure(Array.isArray(triggers), "triggers 必须是数组");
-  if (triggers.length === 0) return triggerLevels.defaultLevel;
-  let required = "L1";
-  for (const trigger of triggers) {
-    ensure(triggerLevels.map.has(trigger), `未知 trigger: ${trigger}`);
-    const candidate = triggerLevels.map.get(trigger);
-    if (levelRank(candidate) > levelRank(required)) required = candidate;
-  }
-  return required;
-}
-
-export function validateMaintenanceCheckpoint(data, options = {}) {
-  ensure(data && typeof data === "object" && !Array.isArray(data), "checkpoint 必须是对象");
-  const v1Fields = ["schema_version", "intensity", "classification_reason", "triggers", "changed_assets", "verification_evidence", "review_mode", "escalation"];
-  const v2Fields = [...v1Fields, "target_state", "current_state", "verification_profile", "review_round", "candidate_digest"];
-  const exactFields = data.schema_version === 2 ? v2Fields : v1Fields;
-  const unknown = Object.keys(data).filter((key) => !exactFields.includes(key));
-  ensure(unknown.length === 0, `checkpoint 包含未知字段: ${unknown.join(", ")}`);
-  ensure([1, 2].includes(data.schema_version), "schema_version 必须为 1 或 2");
-  ensure(LEVELS.includes(data.intensity), "intensity 必须是 L1、L2 或 L3");
-  ensure(typeof data.classification_reason === "string" && data.classification_reason.trim(), "classification_reason 不能为空");
-  ensure(Array.isArray(data.changed_assets) && data.changed_assets.length > 0 && data.changed_assets.every((item) => typeof item === "string" && item.trim()), "changed_assets 必须包含至少一个路径或资产引用");
-  const minimum = minimumIntensity(data.triggers);
-  ensure(levelRank(data.intensity) >= levelRank(minimum), `${data.triggers.join(", ") || "默认"} 至少要求 ${minimum}，不得声明为 ${data.intensity}`);
-  ensure(typeof data.escalation === "string" && data.escalation.trim(), "escalation 必须说明 none 或升级原因");
-  ensure(Array.isArray(data.verification_evidence), "verification_evidence 必须是数组");
-  const kinds = new Set();
-  for (const evidence of data.verification_evidence) {
-    ensure(evidence && typeof evidence === "object" && !Array.isArray(evidence), "verification_evidence 条目必须是对象");
-    ensure(typeof evidence.kind === "string" && evidence.kind.trim(), "verification_evidence.kind 不能为空");
-    ensure(typeof evidence.command === "string" && evidence.command.trim(), "verification_evidence.command 不能为空");
-    ensure(evidence.result === "pass", `验证证据必须是本轮实际通过结果: ${evidence.kind ?? "unknown"}`);
-    if (["focused-independent-review", "formal-independent-review"].includes(evidence.kind)) {
-      validateMaintenanceReviewEvidence(evidence, options);
-    }
-    kinds.add(evidence.kind);
-  }
-  const legacyFormalL3 = data.intensity === "L3" && data.review_mode === "formal-independent";
-  const reviewKind = data.intensity === "L2" ? "focused-independent-review" : data.intensity === "L3" ? (legacyFormalL3 ? "formal-independent-review" : "self-check") : null;
-  if (data.schema_version === 2) validateCheckpointState(data, kinds, reviewKind);
-  const requiredEvidence = legacyFormalL3
-    ? ["red", "green", "refactor", "pressure-scenario", "fresh-verification", "formal-independent-review"]
-    : REQUIRED_EVIDENCE[data.intensity];
-  for (const required of requiredEvidence) {
-    const pendingByV2State = data.schema_version === 2 && data.current_state !== "release-ready" && required === reviewKind;
-    if ((options.allowPendingReview === true || pendingByV2State) && required === reviewKind) continue;
-    ensure(kinds.has(required), `${data.intensity} 缺少 ${required} 证据`);
-  }
-  ensure(REVIEW_MODES[data.intensity].has(data.review_mode), `${data.intensity} 不允许 review_mode=${data.review_mode}`);
-  return { intensity: data.intensity, minimum_intensity: minimum, current_state: data.schema_version === 2 ? data.current_state : "release-ready" };
-}
-
-function validateCheckpointState(data, evidenceKinds, reviewKind) {
-  const states = ["implementation-ready", "review-ready", "release-ready", "needs-human"];
-  const targets = ["implementation-ready", "review-ready", "release-ready"];
-  const profiles = ["fast", "candidate", "release"];
-  ensure(targets.includes(data.target_state), "target_state 无效");
-  ensure(states.includes(data.current_state), "current_state 无效");
-  ensure(profiles.includes(data.verification_profile), "verification_profile 无效");
-  ensure(Number.isInteger(data.review_round) && data.review_round >= 0 && data.review_round <= 2, "review_round 必须为 0、1 或 2");
-  ensure(data.candidate_digest === null || /^(?:sha256:)?[a-f0-9]{64}$/.test(data.candidate_digest), "candidate_digest 必须为 null 或 SHA-256");
-  const targetRank = targets.indexOf(data.target_state);
-  const currentRank = targets.indexOf(data.current_state);
-  if (data.current_state !== "needs-human") ensure(currentRank <= targetRank, "current_state 不得越过 target_state");
-
-  if (data.current_state === "implementation-ready") {
-    ensure(data.verification_profile === "fast", "implementation-ready 必须使用 fast profile");
-    ensure(data.review_round === 0, "implementation-ready 的 review_round 必须为 0");
-    ensure(data.candidate_digest === null, "implementation-ready 不得冻结 candidate_digest");
-    return;
-  }
-
-  const selfCheckL3 = data.intensity === "L3" && data.review_mode === "self-check";
-  if (!selfCheckL3) {
-    ensure(data.candidate_digest !== null, `${data.current_state} 必须绑定 candidate_digest`);
-    ensure(data.review_round >= 1, `${data.current_state} 的 review_round 必须为 1 或 2`);
-    for (const required of ["candidate-verification", "initial-release-verification", "review-task-packages"]) {
-      ensure(evidenceKinds.has(required), `${data.current_state} 缺少 ${required} 证据`);
-    }
-    validateReleaseVerificationCommand(data, "initial-release-verification");
-  } else {
-    ensure(data.review_round === 0, "L3 self-check 不需要审查轮次");
-    ensure(data.candidate_digest === null, "L3 self-check 不得冻结 candidate_digest");
-  }
-  if (data.current_state === "review-ready") {
-    if (selfCheckL3) {
-      ensure(data.verification_profile === "fast", "L3 self-check 的 review-ready 必须使用 fast profile");
-    } else {
-      ensure(data.verification_profile === "candidate", "review-ready 必须使用 candidate profile");
-    }
-    return;
-  }
-  if (data.current_state === "needs-human") {
-    ensure(data.target_state === "release-ready", "needs-human 必须保留 release-ready 目标");
-    ensure(data.review_round === 2, "needs-human 只允许在第二轮审查后进入");
-    ensure(["candidate", "release"].includes(data.verification_profile), "needs-human 必须来自 candidate 或 release profile");
-    return;
-  }
-  ensure(data.verification_profile === "release", "release-ready 必须使用 release profile");
-  ensure(evidenceKinds.has("final-release-verification"), "release-ready 缺少 final-release-verification 证据");
-  validateReleaseVerificationCommand(data, "final-release-verification");
-  if (reviewKind) ensure(evidenceKinds.has(reviewKind), `release-ready 缺少 ${reviewKind} 证据`);
-}
-
-function validateReleaseVerificationCommand(data, kind) {
-  const evidence = data.verification_evidence.filter((item) => item.kind === kind);
-  ensure(evidence.length === 1, `${kind} 必须恰好提供一条完整门禁证据`);
-  ensure(evidence[0].command === "scripts/verify-template", `${kind}.command 必须为 scripts/verify-template`);
-}
-
-export function loadMaintenanceCheckpoint(source) {
-  const raw = source === "-" ? readFileSync(0, "utf8") : readFileSync(source, "utf8");
-  const document = parseDocument(raw, { uniqueKeys: true });
-  ensure(document.errors.length === 0, document.errors[0]?.message || "checkpoint 无法解析");
-  return document.toJS({ maxAliasCount: 0 });
-}

package/template/scripts/lib/maintenance-review-workflow.mjs

@@ -1,107 +0,0 @@
-import { existsSync, readFileSync } from "node:fs";
-import path from "node:path";
-import { parseDocument } from "../vendor/yaml.mjs";
-import { generateTaskPackageDefaults } from "./task-package.mjs";
-import { loadMaintenanceCheckpoint, validateMaintenanceCheckpoint } from "./maintenance-intensity.mjs";
-import { ROOT } from "./template-verification.mjs";
-
-function fail(message) { throw new TypeError(message); }
-function ensure(condition, message) { if (!condition) fail(message); }
-function safeRef(value, field) {
-  ensure(typeof value === "string" && value.trim(), `${field} 不能为空`);
-  ensure(!path.isAbsolute(value), `${field} 必须是仓库相对路径`);
-  const resolved = path.resolve(ROOT, value);
-  ensure(!path.relative(ROOT, resolved).startsWith(".."), `${field} 不得越出仓库`);
-  return resolved;
-}
-function loadYaml(ref, label) {
-  const document = parseDocument(readFileSync(safeRef(ref, label), "utf8"), { uniqueKeys: true });
-  ensure(document.errors.length === 0, document.errors[0]?.message || `${label} 无法解析`);
-  return document.toJS({ maxAliasCount: 0 });
-}
-function readableRef(value) {
-  if (typeof value !== "string" || !value || /\s/.test(value) || path.isAbsolute(value)) return null;
-  const resolved = path.resolve(ROOT, value);
-  if (path.relative(ROOT, resolved).startsWith("..") || !existsSync(resolved)) return null;
-  return value;
-}
-function slug(value) { return value.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-|-$/g, "").toLowerCase(); }
-
-const AXES = [
-  { axis: "standards", role: "role.test-engineer", objective: "验证工程标准、可执行门禁和候选完整性" },
-  { axis: "spec", role: "role.requirements-manager", objective: "验证流程语义、范围与单一事实来源一致性" },
-  { axis: "lead", role: "role.lifecycle-orchestrator", objective: "汇总独立审查并裁决候选是否收敛" }
-];
-
-export function generateReviewerTaskPackages({ checkpointRef, candidateRef, outputDir, candidateKind, candidateRequirement, implementationActorId, round }) {
-  const checkpoint = loadMaintenanceCheckpoint(safeRef(checkpointRef, "checkpointRef"));
-  validateMaintenanceCheckpoint(checkpoint);
-  ensure(checkpoint.schema_version === 2 && checkpoint.current_state === "review-ready", "只能为 review-ready checkpoint 生成审查任务包");
-  ensure(round === checkpoint.review_round && [1, 2].includes(round), "round 必须与 checkpoint.review_round 一致且最多为 2");
-  ensure(typeof candidateRequirement === "string" && candidateRequirement.trim(), "candidateRequirement 不能为空");
-  ensure(typeof implementationActorId === "string" && implementationActorId.trim(), "implementationActorId 不能为空");
-  const candidate = loadYaml(candidateRef, "candidateRef");
-  ensure(typeof candidate.candidate_kind === "string" && candidate.candidate_kind.trim(), "candidate manifest 缺少 candidate_kind");
-  if (candidateKind !== undefined) ensure(candidateKind === candidate.candidate_kind, "candidateKind 必须与 candidate manifest 一致");
-  ensure(candidate.candidate_digest === checkpoint.candidate_digest, "候选 manifest 与 checkpoint 的 candidate_digest 不一致");
-  safeRef(outputDir, "outputDir");
-  const stem = slug(path.basename(checkpointRef, path.extname(checkpointRef)));
-  const applicableRuleRefs = ["AGENTS.md", "CONTEXT.md", "docs/process/harness-process-tailoring.md", ".agents/skills/maintaining-skills/SKILL.md"];
-  const candidateByteRefs = [candidateRef, candidate.snapshot_stream_ref, candidate.tracked_diff_ref].map(readableRef).filter(Boolean);
-  const sourceEvidenceRefs = (checkpoint.verification_evidence || []).flatMap((evidence) => [readableRef(evidence.command), readableRef(evidence.evidence_ref)]).filter(Boolean);
-  const allowedReadPaths = [...new Set([...candidateByteRefs, checkpointRef, ...sourceEvidenceRefs, ...applicableRuleRefs])];
-  const upstreamVerificationResults = (checkpoint.verification_evidence || []).flatMap((evidence) => {
-    const evidenceRef = readableRef(evidence.evidence_ref);
-    if (!evidenceRef || typeof evidence.executed_at !== "string" || typeof evidence.command !== "string") return [];
-    return [{ command: evidence.command, exit_code: 0, duration_ms: Number.isInteger(evidence.duration_ms) ? evidence.duration_ms : 0, executed_at: evidence.executed_at, evidence_ref: evidenceRef }];
-  });
-  const verificationCommands = [...new Set([...upstreamVerificationResults.map((result) => result.command), "git diff --check"])];
-  return AXES.map(({ axis, role, objective }) => {
-    const reportRef = `${outputDir}/${stem}-${axis}-review-round${round}.md`;
-    const packageRef = `${outputDir}/${stem}-${axis}-review-task-round${round}.yaml`;
-    const taskPackage = generateTaskPackageDefaults(role, {
-      task_id: `${stem}-${axis}-review-round${round}`,
-      work_unit_id: "work-unit.intensity-aware-review",
-      actor_id: `reviewer.${stem}.${axis}.r${round}`,
-      runtime_id: "runtime.skill-projection",
-      execution_state: "Reviewer",
-      workflow_status: "active",
-      contract: {
-        kind: "template-maintenance",
-        contract_id: stem,
-        contract_version: round,
-        status: "issued",
-        contract_ref: checkpointRef,
-        maintenance_ref: checkpointRef,
-        candidate_kind: candidate.candidate_kind,
-        candidate_requirement: candidateRequirement,
-        candidate_digest: checkpoint.candidate_digest,
-        review_axis: axis,
-        review_round: round,
-        applicable_rule_refs: applicableRuleRefs
-      },
-      inputs: [...allowedReadPaths],
-      allowed_read_paths: [...allowedReadPaths],
-      objective: `${objective}；${candidateRequirement}`,
-      allowed_write_paths: [reportRef],
-      forbidden_actions: ["修改实现资产", "修改候选快照", "commit", "push", "批准发布"],
-      expected_outputs: [`${axis} 审查结论`, "findings", "candidate_digest"],
-      expected_evidence_files: [reportRef],
-      verification_commands: verificationCommands,
-      verification_results: upstreamVerificationResults,
-      review_context: { implementation_actor_id: implementationActorId, implementation_task_id: `${stem}-implementation` },
-      downstream_consumers: axis === "lead" ? ["role.lifecycle-orchestrator"] : [`reviewer.${stem}.lead.r${round}`],
-      convergence: { parent_work_unit: "work-unit.intensity-aware-review", convergence_ref: checkpointRef, conflict_escalation: "violation 交实现者修复；drift/new_impacts 重新路由；第二轮仍阻断则 needs-human" }
-    });
-    return { axis, packageRef, reportRef, package: taskPackage };
-  });
-}
-
-export function evaluateMaintenanceReviewRound({ review_round: round, candidate_digest: digest, findings = [] }) {
-  ensure([1, 2].includes(round), "正式审查最多允许两轮");
-  ensure(/^(?:sha256:)?[a-f0-9]{64}$/.test(digest), "candidate_digest 必须是 SHA-256");
-  ensure(Array.isArray(findings), "findings 必须是数组");
-  const blocking = findings.filter((finding) => ["violation", "drift", "new_impacts"].includes(finding?.disposition) && finding.status !== "resolved" && finding.status !== "not-applicable");
-  const backlog = findings.filter((finding) => finding?.disposition === "judgement-call" && finding.status !== "resolved" && finding.status !== "not-applicable");
-  return { review_round: round, candidate_digest: digest, current_state: blocking.length > 0 && round === 2 ? "needs-human" : "review-ready", action: blocking.length === 0 ? "eligible-for-final-verification" : round === 1 ? "repair-and-refreeze" : "stop-automatic-review", blocking_findings: blocking, backlog_findings: backlog };
-}