@cr1992/agentkit 1.0.0

package/core/digest.mjs

@@ -0,0 +1,67 @@
+// canonical JSON 与 envelope 摘要。
+//
+// 三个 Skill 此前各带一份实现，行为并不完全相同：
+// - orchestrate 版不校验 UTF-16 代理对，也不拒绝非有限 number；
+// - verify 与 loop 版两者都校验，并各自抛自己的 ValidationError 子类。
+// 直接统一会改变其中一侧的失败面，而 canonicalJson 是所有 content_digest 的基础，
+// 摘要语义受方案 §7 保护。因此这里只做实现去重：错误类与严格度由调用方注入，
+// 各 Skill 的可观察行为保持不变。严格度的收敛是一次独立决策，不在本次搬迁里顺手做。
+import { createHash } from 'node:crypto';
+
+/** @param {string|Buffer} value */
+export function sha256(value) {
+  return `sha256:${createHash('sha256').update(value).digest('hex')}`;
+}
+
+/** @param {Buffer|string} value */
+export function digestBytes(value) {
+  return sha256(value);
+}
+
+/**
+ * @param {{ ValidationError: new (message: string) => Error, strict?: boolean, defaultDigestField?: string }} options
+ *   strict=true 时校验未配对代理对并拒绝非有限 number（verify / loop 的现有行为）。
+ */
+export function createDigestKit({ ValidationError, strict = false, defaultDigestField }) {
+  const assertValidUnicode = (value) => {
+    for (let index = 0; index < value.length; index += 1) {
+      const code = value.charCodeAt(index);
+      if (code >= 0xd800 && code <= 0xdbff) {
+        const next = value.charCodeAt(index + 1);
+        if (!(next >= 0xdc00 && next <= 0xdfff)) throw new ValidationError('字符串含未配对 high surrogate');
+        index += 1;
+      } else if (code >= 0xdc00 && code <= 0xdfff) {
+        throw new ValidationError('字符串含未配对 low surrogate');
+      }
+    }
+  };
+
+  /** @param {unknown} value */
+  function canonicalJson(value) {
+    if (value === null) return 'null';
+    if (typeof value === 'boolean') return value ? 'true' : 'false';
+    if (typeof value === 'number') {
+      if (strict && !Number.isFinite(value)) throw new ValidationError('canonical JSON 不接受非有限 number');
+      return JSON.stringify(Object.is(value, -0) ? 0 : value);
+    }
+    if (typeof value === 'string') {
+      if (strict) assertValidUnicode(value);
+      return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+    if (typeof value === 'object') {
+      const object = /** @type {Record<string, unknown>} */ (value);
+      return `{${Object.keys(object).sort().map((key) => `${canonicalJson(key)}:${canonicalJson(object[key])}`).join(',')}}`;
+    }
+    throw new ValidationError(`canonical JSON 不支持 ${typeof value}`);
+  }
+
+  /** @param {Record<string, unknown>} object @param {string} [digestField] */
+  function envelopeDigest(object, digestField = defaultDigestField) {
+    const clone = { ...object };
+    delete clone[digestField];
+    return sha256(Buffer.from(canonicalJson(clone), 'utf8'));
+  }
+
+  return { canonicalJson, envelopeDigest, sha256, assertValidUnicode };
+}

package/core/json-schema-lite.mjs

@@ -0,0 +1,60 @@
+// 极简 JSON Schema 子集校验。verify 与 loop 此前各带一份：verify 版收集全部错误后抛第一个，
+// loop 版遍历中遇错即抛。两者遍历顺序相同，抛出的都是同一个「第一个错误」，
+// 因此合并到收集式实现对两侧都是零行为变化；collectJsonSchemaErrors 仅 verify 使用。
+// @ts-check
+
+function kind(value) {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'array';
+  if (Number.isInteger(value)) return 'integer';
+  return typeof value;
+}
+
+function resolveRef(root, ref) {
+  if (!ref.startsWith('#/')) throw new Error(`只支持本地 JSON Schema ref: ${ref}`);
+  return ref.slice(2).split('/').reduce((value, part) => value?.[part.replaceAll('~1', '/').replaceAll('~0', '~')], root);
+}
+
+function collect(value, schema, root, path, errors) {
+  if (schema.$ref) return collect(value, resolveRef(root, schema.$ref), root, path, errors);
+  if (Object.hasOwn(schema, 'const') && !Object.is(value, schema.const)) errors.push(`${path} 必须等于 ${JSON.stringify(schema.const)}`);
+  if (schema.enum && !schema.enum.some((item) => Object.is(item, value))) errors.push(`${path} 不在允许枚举中`);
+  if (schema.type) {
+    const allowed = Array.isArray(schema.type) ? schema.type : [schema.type];
+    const actual = kind(value);
+    if (!allowed.includes(actual) && !(actual === 'integer' && allowed.includes('number'))) {
+      errors.push(`${path} 类型应为 ${allowed.join('|')}，实际 ${actual}`);
+      return;
+    }
+  }
+  if (typeof value === 'string') {
+    if (schema.minLength !== undefined && value.length < schema.minLength) errors.push(`${path} 长度不足`);
+    if (schema.pattern && !new RegExp(schema.pattern, 'u').test(value)) errors.push(`${path} 格式不匹配`);
+  }
+  if (typeof value === 'number' && schema.minimum !== undefined && value < schema.minimum) errors.push(`${path} 小于最小值`);
+  if (Array.isArray(value)) {
+    if (schema.minItems !== undefined && value.length < schema.minItems) errors.push(`${path} 项数不足`);
+    if (schema.items) value.forEach((item, index) => collect(item, schema.items, root, `${path}[${index}]`, errors));
+  }
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    for (const field of schema.required ?? []) if (!Object.hasOwn(value, field)) errors.push(`${path} 缺少 ${field}`);
+    const properties = schema.properties ?? {};
+    for (const [field, child] of Object.entries(value)) {
+      if (properties[field]) collect(child, properties[field], root, `${path}.${field}`, errors);
+      else if (schema.additionalProperties === false) errors.push(`${path} 包含未知字段 ${field}`);
+      else if (schema.additionalProperties && typeof schema.additionalProperties === 'object') collect(child, schema.additionalProperties, root, `${path}.${field}`, errors);
+    }
+  }
+}
+
+export function collectJsonSchemaErrors(value, schema, label = '$') {
+  const errors = [];
+  collect(value, schema, schema, label, errors);
+  return errors;
+}
+
+export function validateJsonSchema(value, schema, label = '$') {
+  const errors = collectJsonSchemaErrors(value, schema, label);
+  if (errors.length > 0) throw new Error(errors[0]);
+  return value;
+}

package/core/legacy-entry.mjs

@@ -0,0 +1,37 @@
+// @ts-check
+// 1.x 兼容入口的唯一实现。Skill 目录下的旧入口只允许调用它，不得包含任何自己的逻辑。
+//
+// domain 模块已经被兼容入口的 `export *` 加载；直接复用其 runCli，避免父子进程各加载一次。
+// 不打印迁移提示：本阶段的门禁是新旧入口完全等价，提示会污染 stderr 比对。
+import { realpathSync } from 'node:fs';
+import { basename, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { assertPublicCommandCompatibility, RuntimeBundleError } from './runtime-bundle.mjs';
+
+/** @param {string} moduleUrl 调用方的 import.meta.url */
+export function isProcessEntry(moduleUrl) {
+  try { return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(moduleUrl)); }
+  catch { return false; }
+}
+
+/**
+ * 作为进程入口被直接执行时转发给 domain 运行时；被 import 时什么都不做。
+ * @param {string} moduleUrl @param {(argv:string[]) => number|undefined} runCli
+ * @returns {number|undefined}
+ */
+export function forwardLegacyEntry(moduleUrl, runCli) {
+  if (!isProcessEntry(moduleUrl)) return undefined;
+  const argv = process.argv.slice(2);
+  const entryPath = fileURLToPath(moduleUrl);
+  const skill = basename(dirname(dirname(entryPath)));
+  const entryName = basename(entryPath);
+  try {
+    assertPublicCommandCompatibility({ skill, entryName, command: argv[0] });
+  } catch (error) {
+    if (!(error instanceof RuntimeBundleError)) throw error;
+    process.stderr.write(`agentkit runtime compatibility error: ${error.message}\n`);
+    return 3;
+  }
+  return runCli(argv);
+}

package/core/reflection.mjs

@@ -0,0 +1,142 @@
+// @ts-check
+// Reflection / Improvement Proposal 的共享构造与校验。
+//
+// 此前 orchestrate 一份、verify 与 loop 各一份（后两者字节相同）。两版不是简单重复，
+// orchestrate 版是严格超集：Bearer 脱敏用 \S+、拒绝输入未知字段、evidence ref 额外做
+// realpath 越界检查。统一到严格版会让 verify/loop 拒绝此前接受的输入，属于行为变更。
+// 这里只做实现去重，严格度由调用方注入并保持各自现状；收敛严格度是一次独立决策。
+import { randomUUID } from 'node:crypto';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { isAbsolute, join, normalize, relative, sep } from 'node:path';
+
+import { digestBytes } from './digest.mjs';
+
+const DIGEST = /^sha256:[0-9a-f]{64}$/u;
+const TRIGGERS = new Set(['repeated_failure', 'undecidable', 'user_correction', 'runtime_abort', 'workaround', 'protocol_conflict', 'unexpected_outcome', 'terminal_retrospective']);
+const CLASSIFICATIONS = new Set(['contract_gap', 'skill_gap', 'verification_gap', 'tool_gap', 'environment_gap', 'false_positive', 'false_negative', 'inefficiency']);
+const IMPACTS = new Set(['low', 'medium', 'high', 'safety']);
+const CONFIDENCE = new Set(['low', 'medium', 'high']);
+const DISPOSITIONS = new Set(['continue', 'undecidable', 'abort', 're_contract', 'human_gate']);
+const REF_TYPES = new Set(['artifact', 'evidence', 'event', 'diagnostic']);
+const PROBLEM_TYPES = new Set(['skill_gap', 'false_positive', 'false_negative', 'inefficiency']);
+const REFLECTION_INPUT_KEYS = new Set(['contract_digest', 'trigger', 'classification', 'observation', 'evidence_refs', 'impact', 'confidence', 'recommended_disposition']);
+const PROPOSAL_INPUT_KEYS = new Set(['problem_type', 'proposed_change', 'affected_scope', 'counterexamples', 'validation_plan', 'lifecycle']);
+const VALIDATION_PLAN_KEYS = new Set(['replay_cases', 'regression_suites', 'independent_review', 'canary']);
+
+// 宽松版只匹配 token 字符类，遇到 `Bearer hidden%token|suffix` 会漏脱敏；严格版用 \S+ 覆盖到空白为止。
+const BEARER_STRICT = /\bBearer\s+\S+/giu;
+const BEARER_LENIENT = /\bBearer\s+[A-Za-z0-9._~+/=-]+/giu;
+
+export function safeRelative(id) {
+  if (typeof id !== 'string' || !id || isAbsolute(id) || id.includes('\\')) throw new Error('evidence ref id 必须是相对路径');
+  const normalized = normalize(id);
+  if (normalized === '..' || normalized.startsWith(`..${sep}`)) throw new Error('evidence ref 不能越出 state 目录');
+  return normalized;
+}
+
+/** @param {{ strict?: boolean }} [options] strict 对应 orchestrate 侧此前的行为。 */
+export function createReflectionKit({ strict = false } = {}) {
+  const redact = (text) => {
+    if (typeof text !== 'string' || !text.trim()) throw new Error('反思文本不能为空');
+    return text
+      .replace(strict ? BEARER_STRICT : BEARER_LENIENT, 'Bearer [REDACTED]')
+      .replace(/\b(?:ghp|glpat|sk)-[A-Za-z0-9_-]{12,}\b/gu, '[REDACTED]')
+      .replace(/\/(?:Users|home)\/[^\s"']+/gu, '[LOCAL_PATH]');
+  };
+
+  const eventDigest = (stateDir, id, parseJsonStrict, canonicalJson) => {
+    const match = /^events\.ndjson#revision=(\d+)$/u.exec(id);
+    if (!match) return null;
+    const lines = readFileSync(join(stateDir, 'events.ndjson'), 'utf8').split('\n').filter(Boolean);
+    const event = lines.map((line) => parseJsonStrict(line)).find((candidate) => candidate.revision === Number(match[1]));
+    if (!event) throw new Error(`event revision 不存在: ${match[1]}`);
+    return digestBytes(Buffer.from(canonicalJson(event), 'utf8'));
+  };
+
+  function verifyEvidenceRefs(stateDir, refs, parseJsonStrict, canonicalJson) {
+    if (!Array.isArray(refs)) throw new Error('evidence_refs 必须是数组');
+    return refs.map((ref) => {
+      if (!ref || !REF_TYPES.has(ref.type) || typeof ref.id !== 'string' || !DIGEST.test(String(ref.digest ?? ''))) throw new Error('evidence ref 结构无效');
+      const event = ref.type === 'event' ? eventDigest(stateDir, ref.id, parseJsonStrict, canonicalJson) : null;
+      const actual = event ?? (() => {
+        const relativeId = safeRelative(ref.id);
+        const path = join(stateDir, relativeId);
+        if (!existsSync(path)) throw new Error(`evidence ref 不存在: ${ref.id}`);
+        if (!strict) return digestBytes(readFileSync(path));
+        // 严格版额外解引用 symlink，防止 evidence ref 经软链越出 state 目录。
+        const root = realpathSync(stateDir);
+        const resolved = realpathSync(path);
+        const fromRoot = relative(root, resolved);
+        if (fromRoot === '..' || fromRoot.startsWith(`..${sep}`) || isAbsolute(fromRoot)) throw new Error(`evidence ref 越出 state 目录: ${ref.id}`);
+        return digestBytes(readFileSync(resolved));
+      })();
+      if (actual !== ref.digest) throw new Error(`evidence ref digest 不匹配: ${ref.id}`);
+      return { type: ref.type, id: ref.id, digest: ref.digest };
+    });
+  }
+
+  function buildReflection({ input, stateDir, runDir, scope, skill, parseJsonStrict, canonicalJson, envelopeDigest }) {
+    const root = stateDir ?? runDir;
+    if (strict) {
+      const unknown = Object.keys(input).filter((key) => !REFLECTION_INPUT_KEYS.has(key));
+      if (unknown.length) throw new Error(`Reflection 未知字段: ${unknown.sort().join(', ')}`);
+    }
+    for (const forbidden of ['chain_of_thought', 'reasoning', 'scratchpad']) if (Object.hasOwn(input, forbidden)) throw new Error(`Reflection 禁止字段: ${forbidden}`);
+    if (!TRIGGERS.has(input.trigger) || !CLASSIFICATIONS.has(input.classification) || !IMPACTS.has(input.impact) || !CONFIDENCE.has(input.confidence) || !DISPOSITIONS.has(input.recommended_disposition)) throw new Error('Reflection 枚举字段无效');
+    const evidenceRefs = verifyEvidenceRefs(root, input.evidence_refs ?? [], parseJsonStrict, canonicalJson);
+    if (evidenceRefs.length === 0 && input.confidence !== 'low') throw new Error('无稳定证据的 Reflection 只能是 low confidence');
+    const record = {
+      schema_version: 1,
+      reflection_id: randomUUID(),
+      trigger: input.trigger,
+      scope,
+      affected_skill: skill,
+      classification: input.classification,
+      observation: redact(input.observation),
+      evidence_refs: evidenceRefs,
+      impact: input.impact,
+      confidence: input.confidence,
+      recommended_disposition: input.recommended_disposition,
+      recorded_at: new Date().toISOString(),
+    };
+    record.reflection_digest = envelopeDigest(record, 'reflection_digest');
+    return record;
+  }
+
+  function readAndValidateReflection(path, expectedSkill, parseJsonStrict, envelopeDigest) {
+    const reflection = parseJsonStrict(readFileSync(path, 'utf8'));
+    if (reflection?.schema_version !== 1 || reflection.affected_skill?.name !== expectedSkill || !DIGEST.test(String(reflection.reflection_digest ?? '')) || envelopeDigest(reflection, 'reflection_digest') !== reflection.reflection_digest) throw new Error('Reflection 文件无效或目标 Skill 不匹配');
+    return reflection;
+  }
+
+  function buildProposal({ input, reflections, skill, envelopeDigest }) {
+    if (strict) {
+      const unknown = Object.keys(input).filter((key) => !PROPOSAL_INPUT_KEYS.has(key));
+      if (unknown.length) throw new Error(`Proposal 未知字段: ${unknown.sort().join(', ')}`);
+    }
+    if (input.lifecycle !== undefined && input.lifecycle !== 'proposed') throw new Error('执行 Skill 只能创建 proposed proposal');
+    if (!PROBLEM_TYPES.has(input.problem_type)) throw new Error('proposal problem_type 无效');
+    if (!Array.isArray(reflections) || reflections.length === 0) throw new Error('proposal 至少绑定一个 Reflection');
+    const evidenceRefs = reflections.flatMap((item) => item.evidence_refs ?? []);
+    if (evidenceRefs.length === 0) throw new Error('proposal 必须来自带证据的 Reflection');
+    const validationPlan = input.validation_plan;
+    if (strict && validationPlan && (typeof validationPlan !== 'object' || Array.isArray(validationPlan) || Object.keys(validationPlan).some((key) => !VALIDATION_PLAN_KEYS.has(key)))) throw new Error('proposal validation_plan 含未知字段');
+    if (!validationPlan || !Array.isArray(validationPlan.replay_cases) || !Array.isArray(validationPlan.regression_suites) || validationPlan.independent_review !== 'required') throw new Error('proposal validation_plan 无效');
+    const proposal = {
+      schema_version: 1,
+      proposal_id: randomUUID(),
+      target_skill: { name: skill.name, based_on_version: skill.version, based_on_digest: skill.content_digest },
+      source_reflections: reflections.map((item) => ({ reflection_id: item.reflection_id, reflection_digest: item.reflection_digest })),
+      problem: { type: input.problem_type, evidence_refs: evidenceRefs },
+      proposed_change: redact(input.proposed_change),
+      affected_scope: Array.isArray(input.affected_scope) ? input.affected_scope.map(redact) : [],
+      counterexamples: Array.isArray(input.counterexamples) ? input.counterexamples.map(redact) : [],
+      validation_plan: { ...validationPlan },
+      lifecycle: 'proposed',
+    };
+    proposal.proposal_digest = envelopeDigest(proposal, 'proposal_digest');
+    return proposal;
+  }
+
+  return { buildProposal, buildReflection, readAndValidateReflection, safeRelative, verifyEvidenceRefs };
+}

package/core/runtime-bundle.mjs

@@ -0,0 +1,101 @@
+// @ts-check
+// 安装身份真源：把 PATH 上的 CLI、四个 Skill shell 与随包 domain 绑定在一起。
+// 域级 content_digest 负责状态漂移；本模块负责安装不完整或 CLI/shell 版本错配。
+import { existsSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { distributionDigest } from './content-digest.mjs';
+
+const DEFAULT_PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+const MANIFEST_NAME = 'shell-manifest.json';
+const SKILLS = ['orchestrate-subagents', 'manage-worktrees', 'verify-agent-output', 'run-agent-verify-loop'];
+const HELP_COMMANDS = new Set([undefined, '--help', '-h', 'help', 'capabilities']);
+
+export class RuntimeBundleError extends Error {}
+
+function readJson(path, label) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); }
+  catch (error) { throw new RuntimeBundleError(`${label} 无法解析：${error instanceof Error ? error.message : String(error)}`); }
+}
+
+function safeExistingPath(packageRoot, value, label) {
+  if (typeof value !== 'string' || !value || isAbsolute(value)) throw new RuntimeBundleError(`${label} 必须是包内相对路径`);
+  const absolute = resolve(packageRoot, value);
+  const lexical = relative(packageRoot, absolute);
+  if (!lexical || lexical === '..' || lexical.startsWith(`..${sep}`) || isAbsolute(lexical)) throw new RuntimeBundleError(`${label} 越出包根`);
+  if (!existsSync(absolute)) throw new RuntimeBundleError(`${label} 不存在：${value}`);
+  const realRoot = realpathSync(packageRoot);
+  const real = realpathSync(absolute);
+  const resolved = relative(realRoot, real);
+  if (resolved === '..' || resolved.startsWith(`..${sep}`) || isAbsolute(resolved)) throw new RuntimeBundleError(`${label} 通过符号链接越出包根`);
+  return absolute;
+}
+
+export function readShellManifest(packageRoot = DEFAULT_PACKAGE_ROOT) {
+  return readJson(resolve(packageRoot, MANIFEST_NAME), MANIFEST_NAME);
+}
+
+export function validateShellManifest(packageRoot = DEFAULT_PACKAGE_ROOT) {
+  const manifest = readShellManifest(packageRoot);
+  const pkg = readJson(resolve(packageRoot, 'package.json'), 'package.json');
+  if (manifest.schema_version !== 1) throw new RuntimeBundleError('shell manifest schema_version 必须为 1');
+  if (manifest.package_name !== pkg.name || manifest.package_version !== pkg.version) {
+    throw new RuntimeBundleError(`CLI/shell 版本不匹配：package ${pkg.name}@${pkg.version}，manifest ${manifest.package_name}@${manifest.package_version}`);
+  }
+  if (manifest.cli?.command !== 'agentkit') throw new RuntimeBundleError('shell manifest CLI 命令必须为 agentkit');
+  safeExistingPath(packageRoot, manifest.cli?.entry, 'shell manifest cli.entry');
+
+  const names = Object.keys(manifest.skills ?? {}).sort();
+  if (JSON.stringify(names) !== JSON.stringify([...SKILLS].sort())) throw new RuntimeBundleError('shell manifest 必须且只能声明四件套 Skill');
+  for (const skill of SKILLS) {
+    const descriptor = manifest.skills[skill];
+    if (!descriptor || typeof descriptor.domain !== 'string' || !descriptor.domain) throw new RuntimeBundleError(`${skill} 缺少 domain`);
+    safeExistingPath(packageRoot, descriptor.shell, `${skill}.shell`);
+    const scriptsDir = resolve(packageRoot, skill, 'scripts');
+    safeExistingPath(packageRoot, `${skill}/scripts`, `${skill}.scripts`);
+    const actualEntries = readdirSync(scriptsDir).filter((name) => name.endsWith('.mjs')).sort();
+    const declaredEntries = Object.keys(descriptor.entries ?? {}).sort();
+    if (JSON.stringify(actualEntries) !== JSON.stringify(declaredEntries)) throw new RuntimeBundleError(`${skill} 的兼容入口与 shell manifest 不一致`);
+    for (const entryName of declaredEntries) {
+      const entry = descriptor.entries[entryName];
+      safeExistingPath(packageRoot, entry?.target, `${skill}.${entryName}.target`);
+      if (entry.mutates_state !== false && (!Array.isArray(entry.read_only_commands) || entry.read_only_commands.some((item) => typeof item !== 'string' || !item))) {
+        throw new RuntimeBundleError(`${skill}.${entryName} 必须声明 read_only_commands 或 mutates_state:false`);
+      }
+    }
+  }
+  return { package_name: pkg.name, package_version: pkg.version, manifest };
+}
+
+function entryDescriptor(packageRoot, skill, entryName) {
+  const manifest = readShellManifest(packageRoot);
+  const entry = manifest.skills?.[skill]?.entries?.[entryName];
+  if (!entry) throw new RuntimeBundleError(`shell manifest 未声明 ${skill}/scripts/${entryName}`);
+  return entry;
+}
+
+export function commandMutatesState({ packageRoot = DEFAULT_PACKAGE_ROOT, skill, entryName, command }) {
+  if (HELP_COMMANDS.has(command)) return false;
+  const entry = entryDescriptor(packageRoot, skill, entryName);
+  if (entry.mutates_state === false) return false;
+  return !Array.isArray(entry.read_only_commands) || !entry.read_only_commands.includes(command);
+}
+
+export function assertPublicCommandCompatibility({ packageRoot = DEFAULT_PACKAGE_ROOT, skill, entryName, command }) {
+  if (!commandMutatesState({ packageRoot, skill, entryName, command })) return;
+  validateShellManifest(packageRoot);
+}
+
+export function runtimeBundleDigest(packageRoot = DEFAULT_PACKAGE_ROOT) {
+  const roots = [
+    { prefix: 'package', path: packageRoot, entries: ['package.json', 'LICENSE', MANIFEST_NAME] },
+    { prefix: 'bin', path: resolve(packageRoot, 'bin') },
+    { prefix: 'core', path: resolve(packageRoot, 'core') },
+    { prefix: 'schemas', path: resolve(packageRoot, 'schemas') },
+    { prefix: 'domains', path: resolve(packageRoot, 'domains') },
+  ];
+  for (const domain of ['orchestrate', 'worktree', 'verify', 'loop']) roots.push({ prefix: `docs/${domain}`, path: resolve(packageRoot, 'docs', domain) });
+  for (const skill of SKILLS) roots.push({ prefix: `skills/${skill}`, path: resolve(packageRoot, skill), entries: ['SKILL.md', 'agents', 'scripts'] });
+  return distributionDigest(roots);
+}

package/docs/loop/embedded-review-adapter.md

@@ -0,0 +1,41 @@
+# Embedded reviewer adapter
+
+本 adapter 只在 freeze 前明确选择 `provider: embedded` 时使用。它定义 standalone Loop 如何准备
+最小 reviewer 输入、绑定共享 Review Result，以及 embedded assurance 的缺口；不复制完整 verifier
+行为协议。
+
+## 前置条件
+
+1. 当前 iteration 已绑定完整 Git Artifact Ref；
+2. workdir clean 且 `HEAD == artifact_sha`；
+3. `run-embedded-l0` 已完成；
+4. reviewer 是宿主新上下文，或由用户中继的第二会话；
+5. reviewer 不可读取实现者过程对话、自述和期待通过的暗示。
+
+只有当前实现者上下文时停止。L2 自查不能满足 embedded L1，也不能产生 pass record。
+
+## Reviewer 输入
+
+只提供冻结 Contract、Profile 中的 L1 lenses、Artifact、L0 入口/结果与去污染 acceptance view。
+reviewer 按 canonical verifier protocol 主动证伪，输出 Review Result v1。
+
+`record-embedded-review` 必须校验：
+
+- Contract/Profile digest；
+- 当前 loop ID、iteration 与 Artifact；
+- 当前 iteration 的 `challenge_nonce`，拒绝跨轮重放；
+- acceptance ID、finding class 与 evidence；
+- `no_defect_found` forensics；
+- Review Result digest；
+- `host_reported | user_relayed` assurance 和 opaque reviewer run ID。
+
+## 保证边界
+
+生成物固定为 `record_type: embedded_verification_record`，使用 `record_digest`。它缺少标准 verifier 的
+smoke/final 双阶段、内容寻址 Evidence 消费协议和可移植 run provenance，只能推进创建它的 Loop。
+
+必要的结构 schema 位于 [schemas/](../../schemas/)；其中 Review Result v1 schema 必须与 verifier Skill 的
+同版本文件逐字节兼容，但本目录不复制 reviewer 行为协议。
+
+任何 consumer 必须拒绝把 embedded record 当 Evidence Package；不得添加 `evidence_digest`，也不得
+通过字段重命名或 wrapper 转换提高 assurance。

package/docs/loop/loop-state-machine.md

@@ -0,0 +1,43 @@
+# Loop State v1
+
+## 状态
+
+```text
+active
+├─ pass + no H gate ───────────────→ completed
+├─ pass + H gate ──────────────────→ waiting_human
+├─ fail + 未熔断 ──────────────────→ active（下一 iteration）
+├─ fail + max/fuse/policy stop ────→ stopped
+├─ undecidable / blocked_safety ───→ stopped
+└─ verification abort / drift ─────→ stopped
+
+waiting_human
+├─ approved ───────────────────────→ completed
+└─ rejected / explicit stop ───────→ stopped
+```
+
+`completed` 与 `stopped` 是 Loop 终态，不表示外部 Goal 或全局任务完成。
+
+## Iteration
+
+每个 iteration 固定绑定：
+
+- 从 1 开始的 index；
+- 完整 Artifact Ref；
+- full provider 的唯一 verification run ID，或 embedded provider 的 L0/Review Result；
+- terminal outcome；
+- Evidence digest 或 embedded record digest；
+- fail 时的稳定 failure signature。
+
+一个 active iteration 尚未终结时不能登记新 Artifact。fail 后由 controller 执行 `next`，再为修复后的
+新 Artifact 调用 `record-artifact`。
+
+## H gate
+
+H gate 与 verification verdict 正交。`pass` 只能把 required gate 推到 `waiting_human`；只有
+`human-gate --decision approved` 能进入 completed。rejected 进入 stopped。
+
+## Verification abort
+
+operational abort 不写入 `iterations`，不增加 index，也不生成 failure signature。controller 修复前置
+条件后，可用 `resume --verification-run-id <new-id>` 为同一 Artifact 创建新 verification run。

package/docs/loop/recovery-and-fuses.md

@@ -0,0 +1,34 @@
+# 恢复、防重放与熔断
+
+## Journal 与 revision
+
+- 每次 mutation 在 state-root lock 内检查 `expected_revision`；
+- event journal 先 fsync 追加完整 next snapshot，再原子替换 snapshot cache；
+- snapshot 缺失或落后时，以最后一个完整 event 为真源恢复；
+- `doctor` 只报告 snapshot、lock 与 Skill drift，不删除或猜测修复状态。
+
+## Evidence 防重放
+
+`record-evidence` 持有 state-root 级锁，扫描该 root 下所有 Loop journal 的
+`consumed_verification_run_ids`。run ID 已出现时拒绝；新消费与 Loop next snapshot 写在同一 event，
+因此 snapshot 写入前崩溃仍能从 journal 发现消费记录。
+
+Evidence 还必须绑定当前 Contract digest、Profile digest、Artifact、iteration verification run ID 和
+自身 digest。只复制 Evidence 文件但未成功追加 event 不构成消费；重试时内容必须一致。
+
+## 失败指纹
+
+只把以下稳定 ID 排序去重后做 canonical JSON SHA-256：
+
+- failed L0 `check_id`；
+- L1 `{contract_item_id, class}`。
+
+自然语言 evidence、expected、actual 和 summary 不进入指纹。runtime 不猜测不同文本是否语义同因。
+
+连续相同指纹达到冻结阈值、达到 max iterations、policy=stop、undecidable 或 safety finding 时确定性
+停止。阈值不能由 implementer 或 reviewer 在运行中提高。
+
+## Skill drift
+
+init 冻结本 Skill tree manifest 的 content digest。非终态 mutation 前重算；不一致进入 stopped
+`operational_abort(skill_drift)`，必须由 controller re-contract，不能在旧 Loop 内接受新规则。

package/docs/orchestrate/dispatch-contract.md

@@ -0,0 +1,92 @@
+# 节点派发合同
+
+在派发写 worker、使用完整档、要求独立 Evidence，或进行失败后重派时读取。简单的轻量只读节点只需
+使用 `SKILL.md` 中的最小合同，不必加载本文件。
+
+## 完整节点 envelope
+
+```yaml
+objective: 唯一目标
+role: scout | worker | critic | judge
+scope:
+  include: 允许范围
+  exclude: 明确不处理的行动
+inputs: 已知事实、依赖产物与允许假设
+output_contract: 结论格式与交付物
+acceptance: 可观察完成标准
+evidence: 文件、测试、来源或复现步骤
+permissions:
+  mode: read_only | write
+  writable_paths: []
+environment:
+  repository: 主仓绝对路径
+  isolation: shared_tree | worktree
+  workdir: worker 工作目录绝对路径
+  branch: controller 已确认的分支
+  runtime: 按需填写共享资源
+dependencies: 前置节点与下游消费者
+required_capabilities: []
+verification:
+  requirement: worker_self_check | controller_recheck | independent_evidence | not_applicable
+  provider: none | verify-agent-output
+  artifact_scope: node_output | integration_candidate | not_applicable
+extensions:
+  verification:
+    provider: none | verify-agent-output | run-agent-verify-loop
+  worktree:
+    provider: none | manage-worktrees
+execution:
+  orchestration_mode: lightweight | full
+  attempt_id: 不透明唯一 ID
+  attempt: 从 1 开始
+  previous_attempt_id: 首次为 null
+  tier: 本地 tier | host-default
+  model: 精确模型 ID | inherited | host-default
+  reasoning_effort: 精确值 | inherited | unsupported
+  adjustment_action: initial | retry_same | raise_effort | switch_model | promote_tier | fresh_context | change_strategy
+  failure_kind: null | implementation_defect | reasoning_gap | context_gap | strategy_gap
+  failure_ref: null | 前序稳定失败证据摘要
+  selection_reason: 模型、强度与节点需求的匹配理由
+  config_source: [session | user-host:<path> | host-default]
+  configuration_state: user-explicit | session-inferred | session-confirmed | persisted-config | host-default
+  model_resolution_state: discovered-and-validated | user-explicit-unverifiable | host-default-unexposed
+  capability_source: live-schema | live-schema+effective:<ref> | cache:<path>+live-validation
+  capability_fingerprint: 当前宿主能力描述 sha256
+  effective_capability_ref: 匹配当前 binding 的记录 | null
+  capability_cache_status: fresh | refreshed | absent-write-blocked | stale-write-blocked | not-required-lightweight
+  dispatch_provenance: explicit | inherited-controller | host-default
+  token_budget: 明确预算 | unsupported
+  max_attempts: 包含首次派发的最大尝试数
+stop_conditions: 阻塞、中止和预算退出条件
+```
+
+完整档先通过 `contract-tool.mjs normalize / validate / digest / review-view / diff` 冻结公共 Task
+Contract，再把实际宿主派发回执写入 `dispatch-record`。schema 和 runtime 命令见
+[orchestration-runtime.md](orchestration-runtime.md)。
+
+## 合同不变量
+
+- `objective / scope / output_contract / acceptance / evidence / verification` 不得缺失；写任务还必须有
+  `permissions / writable_paths / environment`。
+- `inputs` 中的已知事实必须由 controller 亲自核实并能指出证据；单一来源解析、模式匹配或记忆值属于
+  允许假设，并注明 worker 使用前必须验证。
+- `exclude` 禁止未申报行动，不禁止带理由上报越界方案；外部可变状态在动作前重查。
+- `not_applicable` 只给 `role: critic | scout` 的只读评审节点，必须搭配 `provider: none` 与
+  `artifact_scope: not_applicable`；这类节点验收时附一份 report 即可，不冒充实现交付。
+- `independent_evidence` 只使用 `verify-agent-output`，且 provider 与 Skill identity 必须在公共合同
+  freeze 前声明。通常只对最终冻结的高风险候选启用，不给普通 worker 预先升级。
+- 修复类 acceptance 写从裁决真源推导的预期态，不把 reviewer 处方或修复手段本身当标准。
+- 重派的 `attempt` 连续，绑定直接前序 attempt 与稳定失败证据，不得覆盖旧节点。
+
+## Worker 状态包
+
+```yaml
+status: completed | partial | blocked
+conclusion: 核心结论
+evidence: 可核验证据
+changes: 实际变更
+risks: 未解决风险
+next_action: 建议后续动作
+```
+
+该状态包只是 controller 的验收输入，不是业务交付，也不能自行宣布全局完成。