@cr1992/agentkit 1.1.0 → 1.2.0

package/domains/loop/loop-runtime.mjs

@@ -28,8 +28,9 @@ import { validateJsonSchema } from '../../core/json-schema-lite.mjs';
 import { atomicWriteJson, atomicWriteText, writeNewJson } from '../../core/atomic-fs.mjs';
 import { createDigestKit } from '../../core/digest.mjs';
 import { distributionDigest, skillDistributionRoots } from '../../core/content-digest.mjs';
+import { contractSubstance, coverageSubstance, formatSubstanceErrors, profileSubstance, substanceWarnings } from '../../core/contract-substance.mjs';
 
-export const RUNTIME_VERSION = '1.0.0';
+export const RUNTIME_VERSION = '1.1.0';
 const SKILL_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', 'run-agent-verify-loop');
 // 摘要覆盖 Skill 目录 + 共享 core + canonical schemas：执行真正依赖的全部分发内容。
 // PACKAGE_ROOT 是模块常量，传入自定义 root 只替换 Skill 目录那一段，便于测试摘要与安装路径无关。
@@ -715,6 +716,10 @@ function initialize(options, flags) {
   const profile = readJson(required(options, 'profile'));
   const ids = validateContract(contract);
   validateProfile(profile, ids);
+  // 实质性只在 init 这个冻结点判定；adopt-root、record-embedded-review、validate 等续跑入口不重判。
+  const contractReport = contractSubstance(contract);
+  const substance = [...contractReport.errors, ...profileSubstance(profile).errors, ...coverageSubstance(contract, profile).errors];
+  if (substance.length) throw new LoopValidationError(formatSubstanceErrors(substance));
   const contentDigest = skillContentDigest();
   validateSkillBinding(contract, contentDigest);
   const provider = required(options, 'provider');
@@ -774,7 +779,7 @@ function initialize(options, flags) {
     initialEvent.event_digest = envelopeDigest(initialEvent, 'event_digest');
     writeFileSync(join(loopDir, 'events.ndjson'), `${canonicalJson(initialEvent)}\n`, { flag: 'wx', mode: 0o600 });
     atomicWriteJson(join(loopDir, 'snapshot.json'), snapshot);
-    return { loop_id: loopId, loop_dir: loopDir, revision: 0, state: 'active', provider };
+    return { loop_id: loopId, loop_dir: loopDir, revision: 0, state: 'active', provider, ...(contractReport.warnings.length ? { warnings: contractReport.warnings } : {}) };
   });
 }
 
@@ -1005,7 +1010,10 @@ function doctor(options) {
   const drift = currentDigest !== loaded.snapshot.skill_provenance.content_digest;
   const lockPresent = existsSync(join(stateRoot, '.loop-runtime.lock'));
   const findings = identityError ? ['state_root_identity_invalid'] : [];
-  return { healthy: !loaded.needsRepair && !lockPresent && !drift && !identityError, loop_id: loaded.snapshot.loop_id, revision: loaded.snapshot.revision, snapshot_matches_journal: !loaded.needsRepair, lock_present: lockPresent, skill_drift: drift, frozen_content_digest: loaded.snapshot.skill_provenance.content_digest, current_content_digest: currentDigest, state_root_identity_valid: !identityError, findings, diagnostics: identityError, recovery_command: identityError ? `adopt-root --state-root ${stateRoot}` : null };
+  // 实质性问题不进 findings、不参与 healthy：doctor 是只读回看路径，会读到判据出现之前冻结的 loop，
+  // 在这里判 unhealthy 等于让历史结论随 runtime 版本变化。
+  const substance = substanceWarnings(readJson(join(loopDir, 'contract.json')), readJson(join(loopDir, 'profile.json')));
+  return { healthy: !loaded.needsRepair && !lockPresent && !drift && !identityError, loop_id: loaded.snapshot.loop_id, revision: loaded.snapshot.revision, snapshot_matches_journal: !loaded.needsRepair, lock_present: lockPresent, skill_drift: drift, frozen_content_digest: loaded.snapshot.skill_provenance.content_digest, current_content_digest: currentDigest, state_root_identity_valid: !identityError, findings, substance_warnings: substance, diagnostics: identityError, recovery_command: identityError ? `adopt-root --state-root ${stateRoot}` : null };
 }
 
 export function main(argv = process.argv.slice(2)) {

package/domains/orchestrate/contract-interview.mjs

@@ -0,0 +1,448 @@
+// @ts-check
+// `agentkit contract interview-*`：由拒绝清单驱动提问、由自己的完成判据决定何时冻结的状态机。
+//
+// 本模块不调用任何模型，也不对自然语言做启发式判定。它只做三件事：
+// 出题（哪些字段还缺、按什么顺序问）、校验回填（选项合规、写进对应字段）、判定冻结。
+// 选项由调用它的模型填，选哪个由用户定——命令既不生成选项，也不替用户选。
+//
+// 为什么"问什么"和"什么时候算问完"不能合一：
+// core/contract-substance.mjs 的 error 只匹配 scaffold 的字面量，任意填一轮文字就能通过。
+// 拿它当结束条件，interview 就退化成一张一次性表单。所以实质性判据只负责"还缺哪些字段"，
+// 结束条件另立三条完成判据（见 completion）。
+//
+// 交互形态是多次调用、文件往返，不是 TTY 交互：轮次状态就写在契约草稿自己的
+// extensions.interview 里，不另建状态目录——草稿在哪里，进度就在哪里，换机器、换会话都不丢。
+// extensions.interview 会进入 contract_digest，这是预期的：作答记录是契约的一部分，冻结后不可变。
+//
+// 命令检查不了的事：source: "user" 的真伪。它只能检查记录是否存在、是否与字段当前值自洽。
+import { contractSubstance } from '../../core/contract-substance.mjs';
+
+/** 一轮 = 一次"出题 → 回填 → 校验"。第 3 轮回填后仍不满足完成判据就退出，建议拆分任务。 */
+export const MAX_ROUNDS = 3;
+/** 一批最多 4 题：再多，模型给出的选项质量和用户的分辨力都会掉下去。 */
+export const MAX_QUESTIONS_PER_ROUND = 4;
+const MIN_OPTIONS = 2;
+const MAX_OPTIONS = 4;
+
+/**
+ * 提问顺序是固定的，不按"哪条判据先报"排。
+ * permissions 必问且最先问：exclude / stop_conditions 两条判据只在 write 模式下生效，而 scaffold 默认 read_only，
+ * 能悄无声息地通过校验。不先问权限，一个写任务走完整个 interview 也不会被问到边界和刹车。
+ */
+const FIELD_ORDER = ['permissions', 'objective', 'acceptance', 'scope.include', 'scope.exclude', 'stop_conditions'];
+const READ_ONLY_REQUIRED = ['permissions', 'objective', 'acceptance', 'scope.include'];
+const WRITE_REQUIRED = [...READ_ONLY_REQUIRED, 'scope.exclude', 'stop_conditions'];
+
+/** 字段语义：随题一起发给用户，让选项可被判断。不含任何可照抄的合规值。 */
+const FIELD_SEMANTICS = {
+  permissions: 'permissions.mode 决定本次任务能不能写仓库。read_only 只允许读与报告；write 允许改动，并会追加边界与刹车两道必问题。',
+  objective: 'objective 是冻结产物要达成的目标，一句话说清"做完是什么样"，不是过程描述。',
+  acceptance: 'acceptance[].requirement 是可观察的验收要求：第三方只看仓库与命令输出就能判定通过或不通过。',
+  'scope.include': 'scope.include 是本次任务允许触碰的面，按路径或模块写。',
+  'scope.exclude': 'scope.exclude 是明确不可触碰的面。它不是"没想到的地方"，而是"想到了并且禁止"。',
+  stop_conditions: 'stop_conditions 是机械停机点：命中即停止并上报，不由执行方自行判断要不要继续。',
+};
+
+/** 题面。出题词只描述要决定什么，不暗示答案。 */
+const FIELD_QUESTION = {
+  permissions: '本次任务需要写仓库吗？',
+  objective: '本次任务要冻结的产物目标是什么？',
+  acceptance: '用什么可观察的事实判定本次任务做完了？',
+  'scope.include': '允许触碰哪些面？',
+  'scope.exclude': '哪些面明确不可触碰？',
+  stop_conditions: '命中什么条件就必须停下来上报？',
+};
+
+/**
+ * 判据本身留在 core/contract-substance.mjs，这里只把它的 finding 路由到一道题上。
+ * 路由键取 finding 里稳定的字段路径前缀，措辞部分不参与匹配。
+ * 新增判据而这里没跟上时，routeFinding 返回 null，由测试钉死"没有 finding 落空"。
+ */
+const FINDING_ROUTES = [
+  { field: 'objective', match: /^objective = /u },
+  { field: 'acceptance', match: /^acceptance\[\d+\]\.requirement = /u },
+  { field: 'scope.include', match: /^scope\.include\[\d+\] = /u },
+  { field: 'scope.exclude', match: /scope\.exclude 为空/u },
+  { field: 'stop_conditions', match: /stop_conditions 为空/u },
+];
+
+/** @param {string} finding @returns {string|null} */
+export function routeFinding(finding) {
+  return FINDING_ROUTES.find((route) => route.match.test(finding))?.field ?? null;
+}
+
+/**
+ * 可以走 assumption 的字段。
+ *
+ * permissions / objective / acceptance **不在此列**：这三项必须有 source: "user" 的作答记录。
+ * 否则模型可以先把 objective 写进草稿，再记一条"用户说都行"，在没有任何用户选择的情况下把契约冻掉——
+ * 这正是访谈要防的"模型替用户回答"，而且是机制拦得住的那一部分。
+ *
+ * 剩下三项都是列表字段，assumption 的内容能原样落进字段，执行方读得到。
+ */
+const DEFERRABLE_FIELDS = new Set(['scope.include', 'scope.exclude', 'stop_conditions']);
+
+export const INTERVIEW_ANSWER_SPEC = [
+  `每题必须给出 ${MIN_OPTIONS}–${MAX_OPTIONS} 个互不相同的非空选项；0 或 1 个选项按开放式问题拒绝。`,
+  '选项由你根据用户诉求和仓库现状生成，命令不生成选项，也不替用户选。',
+  'selected 是选项下标，或者 "custom" 配 custom_value 写用户原话；source 只能是 "user"。',
+  `permissions / objective / acceptance 必须由用户在给出的选项中作答，不接受 deferred：这三项没有 assumption 这条路。`,
+  `用户回答"都行"或拒答时，只有 ${[...DEFERRABLE_FIELDS].join(' / ')} 可以写成 { field, options, deferred: true, assumed }。`,
+  'assumed 是字符串数组（单条可直接写字符串），命令把它原样写进该字段并记进 assumptions[]；执行方读的是契约字段，不是 extensions。',
+  'assumed 可以是空数组，表示"没有要排除的 / 没有额外终止条件"；此时 write 模式的 warning 保留，不影响冻结。',
+];
+
+/** 单值字段：再次作答会替换上一条记录，而不是并存——并存会让完成判据第 3 条必然不成立。 */
+const SINGLE_VALUED = new Set(['permissions', 'objective']);
+
+const quote = (/** @type {unknown} */ value) => JSON.stringify(value);
+
+/**
+ * 读出草稿里的 interview 状态。缺失即视为尚未开始。
+ * 这里按不可信数据读：草稿可能是手写的，也可能被手改过。
+ * @param {any} contract
+ */
+export function readInterviewState(contract) {
+  const raw = contract?.extensions?.interview;
+  const round = Number.isSafeInteger(raw?.round) && raw.round >= 0 ? raw.round : 0;
+  return {
+    schema_version: 1,
+    round,
+    answers: Array.isArray(raw?.answers) ? raw.answers : [],
+    assumptions: Array.isArray(raw?.assumptions) ? raw.assumptions : [],
+  };
+}
+
+/** @param {any} contract @returns {string[]} 本次权限模式下的必问题清单 */
+export function requiredFields(contract) {
+  return contract?.permissions?.mode === 'write' ? [...WRITE_REQUIRED] : [...READ_ONLY_REQUIRED];
+}
+
+/** 一条作答记录选中的内容。deferred 记录不落在这里，它进 assumptions。 */
+function selectedText(answer) {
+  if (answer?.selected === 'custom') return typeof answer.custom_value === 'string' ? answer.custom_value : null;
+  const options = Array.isArray(answer?.options) ? answer.options : [];
+  return Number.isSafeInteger(answer?.selected) && answer.selected >= 0 && answer.selected < options.length ? options[answer.selected] : null;
+}
+
+/** 三个可 deferred 字段都是列表字段，assumption 整段落在这里。 */
+function fieldList(contract, field) {
+  if (field === 'scope.include') return Array.isArray(contract?.scope?.include) ? contract.scope.include : [];
+  if (field === 'scope.exclude') return Array.isArray(contract?.scope?.exclude) ? contract.scope.exclude : [];
+  if (field === 'stop_conditions') return Array.isArray(contract?.stop_conditions) ? contract.stop_conditions : [];
+  return null;
+}
+
+/**
+ * 完成判据第 3 条对 assumption 同样生效：字段当前值必须与 assumed 逐项相等。
+ * assumption 是整段替换写进字段的，所以这里按顺序全等判定，事后手改字段就不成立。
+ */
+function assumptionHolds(contract, field, assumed) {
+  const current = fieldList(contract, field);
+  if (current === null || !Array.isArray(assumed)) return false;
+  return current.length === assumed.length && current.every((item, index) => item === assumed[index]);
+}
+
+/**
+ * 完成判据第 3 条：记录的 field 在契约里的当前值要与 selected 对应的内容一致。
+ * 列表字段按"包含"判定：同一字段可以多轮追加，每条记录各自对应一个元素。
+ */
+function fieldHolds(contract, field, text) {
+  if (text === null) return false;
+  if (field === 'permissions') return contract?.permissions?.mode === text;
+  if (field === 'objective') return contract?.objective === text;
+  if (field === 'acceptance') return (Array.isArray(contract?.acceptance) ? contract.acceptance : []).some((item) => item?.requirement === text);
+  if (field === 'scope.include') return (Array.isArray(contract?.scope?.include) ? contract.scope.include : []).includes(text);
+  if (field === 'scope.exclude') return (Array.isArray(contract?.scope?.exclude) ? contract.scope.exclude : []).includes(text);
+  if (field === 'stop_conditions') return (Array.isArray(contract?.stop_conditions) ? contract.stop_conditions : []).includes(text);
+  return false;
+}
+
+/**
+ * 三条完成判据，同时满足才允许冻结：
+ * 1. core/contract-substance.mjs 的创建入口判据 error 为零（warning 允许保留：用户可以明确回答"没有要排除的"）；
+ * 2. 每道必问题都有 source: "user" 的作答记录；scope.include / scope.exclude / stop_conditions
+ *    可以改由一条 user_deferred 的 assumption 满足，permissions / objective / acceptance 不行；
+ * 3. 每条作答记录的 field 在契约里的当前值与 selected 对应内容一致，每条 assumption 的字段当前值与
+ *    assumed 逐项相等——事后手改字段而不更新记录则不成立。
+ * @param {any} contract
+ */
+export function completion(contract) {
+  const report = contractSubstance(contract);
+  const state = readInterviewState(contract);
+  const missing = [];
+
+  for (const finding of report.errors) {
+    missing.push({ criterion: 'substance_error', field: routeFinding(finding), detail: finding });
+  }
+
+  const answeredFields = new Set();
+  for (const answer of state.answers) if (answer?.source === 'user' && typeof answer?.field === 'string') answeredFields.add(answer.field);
+  for (const assumption of state.assumptions) if (typeof assumption?.field === 'string' && DEFERRABLE_FIELDS.has(assumption.field)) answeredFields.add(assumption.field);
+  for (const field of requiredFields(contract)) {
+    if (!answeredFields.has(field)) {
+      const detail = DEFERRABLE_FIELDS.has(field)
+        ? `${field}：缺少 source: "user" 的作答记录，也没有 user_deferred 的 assumption`
+        : `${field}：缺少 source: "user" 的作答记录，该字段必须由用户在给出的选项中作答`;
+      missing.push({ criterion: 'missing_answer', field, detail });
+    }
+  }
+
+  state.assumptions.forEach((assumption, index) => {
+    const field = assumption?.field;
+    if (typeof field !== 'string' || !DEFERRABLE_FIELDS.has(field)) {
+      missing.push({ criterion: 'assumption_invalid', field: field ?? null, detail: `extensions.interview.assumptions[${index}].field = ${quote(field ?? null)}：该字段必须由用户在给出的选项中作答，不接受 assumption` });
+      return;
+    }
+    if (assumption?.reason !== 'user_deferred') {
+      missing.push({ criterion: 'assumption_invalid', field, detail: `extensions.interview.assumptions[${index}].reason = ${quote(assumption?.reason ?? null)}：只接受 "user_deferred"` });
+      return;
+    }
+    if (!assumptionHolds(contract, field, assumption.assumed)) {
+      missing.push({ criterion: 'assumption_field_mismatch', field, detail: `extensions.interview.assumptions[${index}]：假定内容 ${quote(assumption.assumed ?? null)} 与 ${field} 的当前值不一致，记录与契约已经脱钩` });
+    }
+  });
+
+  state.answers.forEach((answer, index) => {
+    if (answer?.source !== 'user' || typeof answer?.field !== 'string') {
+      missing.push({ criterion: 'answer_invalid', field: answer?.field ?? null, detail: `extensions.interview.answers[${index}]：source 必须是 "user"，field 必须是字段路径` });
+      return;
+    }
+    const text = selectedText(answer);
+    if (text === null) {
+      missing.push({ criterion: 'answer_invalid', field: answer.field, detail: `extensions.interview.answers[${index}].selected 无法解析为选项内容` });
+      return;
+    }
+    if (!fieldHolds(contract, answer.field, text)) {
+      missing.push({ criterion: 'answer_field_mismatch', field: answer.field, detail: `extensions.interview.answers[${index}]：选中内容 ${quote(text)} 与 ${answer.field} 的当前值不一致，记录与契约已经脱钩` });
+    }
+  });
+
+  return { complete: missing.length === 0, missing, warnings: report.warnings, round: state.round };
+}
+
+/**
+ * 本轮该问哪些字段：必问题里尚未作答的，并上实质性判据仍在报的字段（含 warning 指向的字段）。
+ * 已有作答记录但判据仍然报错的字段会被重新问一遍——填了一轮文字不等于问完了。
+ * @param {any} contract
+ */
+export function outstandingFields(contract) {
+  const state = readInterviewState(contract);
+  const report = contractSubstance(contract);
+  const answered = new Set();
+  for (const answer of state.answers) if (answer?.source === 'user' && typeof answer?.field === 'string') answered.add(answer.field);
+  for (const assumption of state.assumptions) if (typeof assumption?.field === 'string' && DEFERRABLE_FIELDS.has(assumption.field)) answered.add(assumption.field);
+
+  const pending = new Set(requiredFields(contract).filter((field) => !answered.has(field)));
+  // error 指向的字段一律重问：填了一轮文字不等于问完了，占位还在就说明这道题没答。
+  for (const finding of report.errors) { const field = routeFinding(finding); if (field) pending.add(field); }
+  // warning 指向的字段若已有作答记录就不再问：用户可以明确回答"没有要排除的"，
+  // 这时"write 模式 exclude 为空"的 warning 仍在，但该字段已经问过了。
+  for (const finding of report.warnings) { const field = routeFinding(finding); if (field && !answered.has(field)) pending.add(field); }
+  return FIELD_ORDER.filter((field) => pending.has(field));
+}
+
+export class InterviewError extends Error {}
+
+/**
+ * 出题：输入一份契约草稿（可以是原样 scaffold），输出本轮问题批。
+ * 选项槽是空的——命令不生成选项。
+ * @param {any} contract
+ */
+export function ask(contract) {
+  const state = readInterviewState(contract);
+  const status = completion(contract);
+  if (state.round >= MAX_ROUNDS) {
+    throw new InterviewError(renderExhausted(status, state.round));
+  }
+  const fields = outstandingFields(contract).slice(0, MAX_QUESTIONS_PER_ROUND);
+  return {
+    schema_version: 1,
+    round: state.round + 1,
+    max_rounds: MAX_ROUNDS,
+    permissions_mode: contract?.permissions?.mode ?? null,
+    required_fields: requiredFields(contract),
+    complete: status.complete,
+    questions: fields.map((field) => ({
+      field,
+      question: FIELD_QUESTION[field],
+      field_semantics: FIELD_SEMANTICS[field],
+      // deferrable=false 的题只有一条路：用户在选项里选。模型不能替他记一条 assumption。
+      deferrable: DEFERRABLE_FIELDS.has(field),
+      options: [],
+      selected: null,
+      source: 'user',
+    })),
+    answer_spec: [...INTERVIEW_ANSWER_SPEC],
+    remaining_criteria: status.missing,
+    warnings: status.warnings,
+  };
+}
+
+/** 选项校验：只看形状，不对自然语言做判定。 */
+function validateOptions(entry, index) {
+  const options = entry?.options;
+  if (!Array.isArray(options)) throw new InterviewError(`answers[${index}].options 缺失：每题必须带上当时给出的选项原文`);
+  if (options.length < MIN_OPTIONS || options.length > MAX_OPTIONS) {
+    throw new InterviewError(`answers[${index}].options 有 ${options.length} 项：必须是 ${MIN_OPTIONS}–${MAX_OPTIONS} 个选项，0 或 1 个是开放式问题`);
+  }
+  const cleaned = options.map((option, position) => {
+    if (typeof option !== 'string' || !option.trim()) throw new InterviewError(`answers[${index}].options[${position}] 为空：选项必须是非空字符串`);
+    return option.trim();
+  });
+  if (new Set(cleaned).size !== cleaned.length) throw new InterviewError(`answers[${index}].options 存在重复项：选项必须互不相同，否则这道题没有在做选择`);
+  return options;
+}
+
+/**
+ * assumed 的形状：字符串数组，单条可直接写字符串。
+ * 空数组是合法的——它表示"没有要排除的 / 没有额外终止条件"，这时 write 模式的 warning 保留。
+ */
+function normalizeAssumed(entry, index) {
+  const raw = entry?.assumed;
+  const list = typeof raw === 'string' ? [raw] : raw;
+  if (!Array.isArray(list)) {
+    throw new InterviewError(`answers[${index}].assumed = ${quote(raw ?? null)}：deferred 必须写明替用户假定进该字段的内容，字符串数组；空数组表示"没有"`);
+  }
+  list.forEach((item, position) => {
+    if (typeof item !== 'string' || !item.trim()) throw new InterviewError(`answers[${index}].assumed[${position}] 为空：假定内容必须是非空字符串`);
+  });
+  if (new Set(list).size !== list.length) throw new InterviewError(`answers[${index}].assumed 存在重复项`);
+  return [...list];
+}
+
+/** deferred 整段替换字段：assumption 与字段是一一对应的，追加会让完成判据第 3 条无从判定。 */
+function applyDeferral(contract, field, assumed) {
+  if (field === 'scope.include') { contract.scope.include = [...assumed]; return; }
+  if (field === 'scope.exclude') { contract.scope.exclude = [...assumed]; return; }
+  contract.stop_conditions = [...assumed];
+}
+
+/** permissions 是唯一取值受限的字段：它决定后续必问题清单，不能是自由文本。 */
+function applyPermissions(contract, text, index) {
+  if (!['read_only', 'write'].includes(text)) {
+    throw new InterviewError(`answers[${index}] 选中 ${quote(text)}：permissions 的选项内容必须恰好是 permissions.mode 的取值之一，当前值为 ${quote(contract?.permissions?.mode ?? null)}`);
+  }
+  contract.permissions.mode = text;
+  if (text === 'read_only') contract.permissions.writable_paths = [];
+}
+
+/** 把选中的内容写进对应字段。列表字段追加，已存在则不重复写。 */
+function applyToField(contract, field, text, index) {
+  if (field === 'permissions') return applyPermissions(contract, text, index);
+  if (field === 'objective') { contract.objective = text; return; }
+  if (field === 'acceptance') {
+    // 占位条目由 core/contract-substance.mjs 的判据识别，这里不自己比对字面量：
+    // 占位文本改了而这里没跟上，就会变成"在占位条目旁边再加一条"，实质性判据依旧报错。
+    const placeholder = contract.acceptance.findIndex((item) => contractSubstance({ acceptance: [item] }).errors.length > 0);
+    if (placeholder >= 0) { contract.acceptance[placeholder].requirement = text; return; }
+    if (contract.acceptance.some((item) => item?.requirement === text)) return;
+    const ids = new Set(contract.acceptance.map((item) => item?.contract_item_id));
+    let ordinal = contract.acceptance.length + 1;
+    while (ids.has(`acceptance-${ordinal}`)) ordinal += 1;
+    contract.acceptance.push({ contract_item_id: `acceptance-${ordinal}`, requirement: text });
+    return;
+  }
+  if (field === 'scope.include') {
+    // 占位条目在 core/contract-substance.mjs 的判据里，这里靠它识别，不自己比对字面量。
+    const placeholders = contract.scope.include.filter((item) => contractSubstance({ scope: { include: [item] } }).errors.length > 0);
+    contract.scope.include = contract.scope.include.filter((item) => !placeholders.includes(item));
+    if (!contract.scope.include.includes(text)) contract.scope.include.push(text);
+    return;
+  }
+  if (field === 'scope.exclude') { if (!contract.scope.exclude.includes(text)) contract.scope.exclude.push(text); return; }
+  if (field === 'stop_conditions') { if (!contract.stop_conditions.includes(text)) contract.stop_conditions.push(text); return; }
+  throw new InterviewError(`answers[${index}].field = ${quote(field)}：不是本命令认识的字段路径，可选：${FIELD_ORDER.join(' / ')}`);
+}
+
+/**
+ * 回填：输入草稿 + 本轮作答，把选中内容写进对应字段，追加作答记录，重新校验。
+ * 返回更新后的草稿（未签名，签名交给调用方的 normalize）与下一批问题或冻结判定。
+ * @param {any} draft @param {any[]} answers
+ */
+export function answer(draft, answers) {
+  const contract = structuredClone(draft);
+  const state = readInterviewState(contract);
+  if (state.round >= MAX_ROUNDS) {
+    throw new InterviewError(renderExhausted(completion(contract), state.round));
+  }
+  if (!Array.isArray(answers) || !answers.length) throw new InterviewError('本轮作答为空：--answers 必须是 answers 数组或 { answers: [...] }');
+  if (answers.length > MAX_QUESTIONS_PER_ROUND) throw new InterviewError(`本轮作答有 ${answers.length} 条：一轮最多 ${MAX_QUESTIONS_PER_ROUND} 题`);
+
+  const nextAnswers = [...state.answers.map((item) => structuredClone(item))];
+  const nextAssumptions = [...state.assumptions.map((item) => structuredClone(item))];
+  const seen = new Set();
+
+  answers.forEach((entry, index) => {
+    const field = entry?.field;
+    if (typeof field !== 'string' || !FIELD_ORDER.includes(field)) {
+      throw new InterviewError(`answers[${index}].field = ${quote(field ?? null)}：不是本命令认识的字段路径，可选：${FIELD_ORDER.join(' / ')}`);
+    }
+    if (seen.has(field)) throw new InterviewError(`answers[${index}].field = ${quote(field)}：同一轮里重复作答同一个字段`);
+    seen.add(field);
+    validateOptions(entry, index);
+
+    if (entry.deferred === true) {
+      if (!DEFERRABLE_FIELDS.has(field)) {
+        throw new InterviewError(`answers[${index}].field = ${quote(field)}：该字段必须由用户在给出的选项中作答，不接受 deferred；可以 deferred 的只有 ${[...DEFERRABLE_FIELDS].join(' / ')}`);
+      }
+      // 不替用户选，但也不让契约自相矛盾：assumed 原样写进字段。
+      // 执行方读的是契约字段而不是 extensions，字段为空、extensions 里却写着"假定排除 X"，
+      // 是一份自己跟自己打架的契约。
+      const assumed = normalizeAssumed(entry, index);
+      applyDeferral(contract, field, assumed);
+      const record = { field, assumed, reason: 'user_deferred' };
+      const existing = nextAssumptions.findIndex((item) => item?.field === field);
+      if (existing >= 0) nextAssumptions[existing] = record; else nextAssumptions.push(record);
+      // 整段替换会冲掉此前作答写进该字段的值，留着旧记录会让完成判据第 3 条必然不成立。
+      for (let position = nextAnswers.length - 1; position >= 0; position -= 1) if (nextAnswers[position]?.field === field) nextAnswers.splice(position, 1);
+      return;
+    }
+
+    if (entry.source !== 'user') throw new InterviewError(`answers[${index}].source = ${quote(entry?.source ?? null)}：只接受 "user"；命令检查不了它的真伪，但不接受别的取值`);
+    const text = selectedText(entry);
+    if (text === null) {
+      throw new InterviewError(`answers[${index}].selected = ${quote(entry?.selected ?? null)}：必须是 options 的下标，或 "custom" 配非空 custom_value`);
+    }
+    applyToField(contract, field, text, index);
+    const record = { field, options: entry.options.map((option) => option), selected: entry.selected, source: 'user' };
+    if (entry.selected === 'custom') record.custom_value = text;
+    // 单值字段再次作答替换旧记录：两条记录只有一条能与字段当前值一致，留着另一条只会让判据 3 永远不成立。
+    const duplicate = SINGLE_VALUED.has(field) ? nextAnswers.findIndex((item) => item?.field === field) : -1;
+    if (duplicate >= 0) nextAnswers[duplicate] = record; else nextAnswers.push(record);
+    // 字段被真正作答后，之前的 deferral 不再成立。
+    const deferred = nextAssumptions.findIndex((item) => item?.field === field);
+    if (deferred >= 0) nextAssumptions.splice(deferred, 1);
+  });
+
+  contract.extensions.interview = { schema_version: 1, round: state.round + 1, answers: nextAnswers, assumptions: nextAssumptions };
+  const status = completion(contract);
+  if (!status.complete && contract.extensions.interview.round >= MAX_ROUNDS) {
+    throw new InterviewError(renderExhausted(status, contract.extensions.interview.round));
+  }
+  return { contract, status };
+}
+
+/** @param {{ missing: { criterion: string, field: string|null, detail: string }[] }} status @param {number} round */
+function renderExhausted(status, round) {
+  const lines = status.missing.map((item) => `- ${item.detail}`);
+  return [
+    `interview 已用满 ${round}/${MAX_ROUNDS} 轮，完成判据仍未满足（${status.missing.length} 项）:`,
+    ...lines,
+    '建议把任务拆开：一份契约要问到第 4 轮还定不下来，通常说明它同时在做两件事。',
+  ].join('\n');
+}
+
+/**
+ * 冻结判定。满足三条完成判据才返回，否则抛出并列出仍缺的判据。
+ * 真正的签名交给调用方的 normalize：摘要口径只有一个出处。
+ * @param {any} contract
+ */
+export function assertFreezable(contract) {
+  const status = completion(contract);
+  if (status.complete) return status;
+  throw new InterviewError([
+    `interview 完成判据未满足（${status.missing.length} 项），不能冻结:`,
+    ...status.missing.map((item) => `- ${item.detail}`),
+  ].join('\n'));
+}

package/domains/orchestrate/contract-tool.mjs

@@ -1,13 +1,17 @@
 #!/usr/bin/env node
 // @ts-check
 
-import { createHash, randomBytes } from 'node:crypto';
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import { realpathSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { isHelpRequest, renderCliHelp } from '../../core/cli-help.mjs';
 import { createDigestKit } from '../../core/digest.mjs';
+import { contractSubstance, formatSubstanceErrors } from '../../core/contract-substance.mjs';
+import { buildScaffoldContract } from '../../core/contract-scaffold.mjs';
+import { ORCHESTRATION_RUNTIME_VERSION, skillContentDigest } from './orchestration-metadata.mjs';
+import { InterviewError, MAX_ROUNDS, answer as interviewAnswer, ask as interviewAsk, assertFreezable } from './contract-interview.mjs';
 
 export class ContractError extends Error {}
 
@@ -47,7 +51,13 @@ class Parser {
 }
 
 export function parseJsonStrict(text) { return new Parser(text).parse(); }
-export function validateContract(contract, { requireDigest = true } = {}) {
+// substance 只由创建入口打开（contract validate、ledger init）。add-node、doctor、投影等
+// 在已冻结契约上的操作保持形状校验：契约冻结后不可变，实质性只在冻结那一刻判定一次；
+// doctor 这类只读回看路径还会读到判据出现之前冻结的 ledger，在那里拒绝等于让历史结论随
+// runtime 版本变化。
+// warnings 是出参数组：warning 不改变 valid 结论也不改变退出码，只能由调用方带进输出，
+// 因此不能走抛异常这条路，也不适合改 validateContract 的返回值（返回的是契约本身）。
+export function validateContract(contract, { requireDigest = true, substance = false, warnings = null } = {}) {
   const required = ['schema_version', 'contract_id', 'objective', 'scope', 'acceptance', 'permissions', 'environment', 'skill_set', 'stop_conditions', 'extensions'];
   if (contract?.schema_version !== 1) throw new ContractError('Task Contract schema_version 必须为 1');
   for (const field of required) if (!Object.hasOwn(contract, field)) throw new ContractError(`Task Contract 缺少 ${field}`);
@@ -87,6 +97,11 @@ export function validateContract(contract, { requireDigest = true } = {}) {
   const common = new Set(required.concat('contract_digest'));
   for (const key of Object.keys(contract.extensions)) if (common.has(key)) throw new ContractError(`extension 覆盖公共字段: ${key}`);
   if (requireDigest && (!/^sha256:[0-9a-f]{64}$/u.test(String(contract.contract_digest ?? '')) || envelopeDigest(contract) !== contract.contract_digest)) throw new ContractError('contract_digest 无效');
+  if (substance) {
+    const report = contractSubstance(contract);
+    if (report.errors.length) throw new ContractError(formatSubstanceErrors(report.errors));
+    if (warnings) warnings.push(...report.warnings);
+  }
   return contract;
 }
 
@@ -122,6 +137,21 @@ export function projectContract(parent, itemIds, { contractId = null } = {}) {
   return validateContract(projected);
 }
 
+// scaffold 别名：骨架本身住在 core/contract-scaffold.mjs，与 verify scaffold --kind contract 同源。
+// 两边只有 skill_set 不同——各自冻结自己域的 content digest：ledger init 要求契约里有当前
+// orchestrate-subagents 的摘要，verify 侧则绑 verify-agent-output。把对方的摘要算进来就得跨域取路径，
+// 所以这一条差异是有意的，其余字段逐字段一致，由测试钉住。
+export function scaffoldContract({ workdir = process.cwd() } = {}) {
+  const contract = buildScaffoldContract({
+    workdir,
+    contractId: randomUUID(),
+    skillSet: [{ name: 'orchestrate-subagents', version: ORCHESTRATION_RUNTIME_VERSION, content_digest: skillContentDigest(), provider_mode: 'primary' }],
+  });
+  validateContract(contract, { requireDigest: false });
+  contract.contract_digest = envelopeDigest(contract);
+  return contract;
+}
+
 export function contractDiff(left, right) {
   const changed = [];
   for (const key of [...new Set([...Object.keys(left), ...Object.keys(right)])].sort()) if (canonicalJson(left[key]) !== canonicalJson(right[key])) changed.push(key);
@@ -131,27 +161,68 @@ export function contractDiff(left, right) {
 
 // CLI 命令与参数的唯一真源：`--help` 清单和未知命令错误信息都从这里推导。
 const CLI_SPEC = {
+  scaffold: { optional: ['workdir'] },
   normalize: { required: ['input'] },
   validate: { required: ['input'] },
   digest: { required: ['input'] },
   'review-view': { required: ['input'] },
   diff: { required: ['left', 'right'] },
   project: { required: ['input', 'items'], optional: ['contract-id'] },
+  'interview-ask': { required: ['input'] },
+  'interview-answer': { required: ['input', 'answers'] },
+  'interview-freeze': { required: ['input'] },
   capabilities: {},
 };
-const CLI_NOTES = ['--items 是逗号分隔的 acceptance contract_item_id 列表，投影合同只能收窄这些条目。'];
+const CLI_NOTES = [
+  '--items 是逗号分隔的 acceptance contract_item_id 列表，投影合同只能收窄这些条目。',
+  'interview 是"多次调用、文件往返"的状态机：ask 出题 → 你把选项填进题目并交给用户选 → answer 回填 → freeze 冻结。',
+  'interview-answer 的 --answers 是 { "answers": [...] } 或裸数组；每题 2–4 个互不相同的非空选项，selected 为下标或 "custom"。',
+  'permissions / objective / acceptance 必须由用户在选项中作答；只有 scope.include / scope.exclude / stop_conditions 可以 deferred，assumed 会原样写进字段。',
+  '轮次与作答记录写在契约草稿自己的 extensions.interview 里，会进入 contract_digest；上限 3 轮。',
+  '用法与完成判据见 agentkit docs orchestrate contract-interview。',
+];
 function parseCli(argv) { const command = argv[0]; const options = {}; for (let i = 1; i < argv.length; i += 2) { if (!argv[i]?.startsWith('--') || argv[i + 1] === undefined) throw new ContractError('参数必须是 --name value'); options[argv[i].slice(2)] = argv[i + 1]; } return { command, options }; }
 function read(path) { return parseJsonStrict(readFileSync(resolve(path), 'utf8')); }
 export function main(argv = process.argv.slice(2)) {
   if (isHelpRequest(argv)) return { help: renderCliHelp('contract-tool.mjs', CLI_SPEC, CLI_NOTES) };
   const { command, options } = parseCli(argv);
+  if (command === 'scaffold') return scaffoldContract({ workdir: options.workdir ?? process.cwd() });
   if (command === 'normalize') return normalizeContract(read(options.input));
-  if (command === 'validate') { const value = validateContract(read(options.input)); return { valid: true, contract_id: value.contract_id, contract_digest: value.contract_digest }; }
+  if (command === 'validate') { const warnings = []; const value = validateContract(read(options.input), { substance: true, warnings }); return { valid: true, contract_id: value.contract_id, contract_digest: value.contract_digest, ...(warnings.length ? { warnings } : {}) }; }
   if (command === 'digest') return { contract_digest: envelopeDigest(read(options.input)) };
   if (command === 'review-view') { const value = validateContract(read(options.input)); return { schema_version: 1, contract_id: value.contract_id, objective: value.objective, scope: value.scope, acceptance: value.acceptance, contract_permissions: value.permissions, reviewer_permissions: { mode: 'read_only', writable_paths: [] }, environment: value.environment, contract_digest: value.contract_digest }; }
   if (command === 'diff') return contractDiff(read(options.left), read(options.right));
   if (command === 'project') return projectContract(read(options.input), String(options.items ?? '').split(',').map((item) => item.trim()).filter(Boolean), { contractId: options['contract-id'] ?? null });
-  if (command === 'capabilities') return { tool: 'contract-tool', runtime_version: '1.1.0', task_contract_versions: [1], features: ['strict-json', 'canonical-digest', 'review-view', 'resign-diff', 'contract-projection'] };
+  // interview 的三个入口都先做形状校验、不要求 digest：草稿在往返途中是未签名的，
+  // 只有 freeze 那一次才重新签名。实质性判据由 interview 自己按完成判据取用，不在这里提前拒绝。
+  if (command === 'interview-ask') { const draft = read(options.input); validateContract(draft, { requireDigest: false }); return interviewAsk(draft); }
+  if (command === 'interview-answer') {
+    const draft = read(options.input);
+    validateContract(draft, { requireDigest: false });
+    const payload = read(options.answers);
+    const entries = Array.isArray(payload) ? payload : payload?.answers;
+    const { contract, status } = interviewAnswer(draft, entries);
+    const signed = normalizeContract(contract);
+    return {
+      round: signed.extensions.interview.round,
+      max_rounds: MAX_ROUNDS,
+      complete: status.complete,
+      remaining_criteria: status.missing,
+      warnings: status.warnings,
+      next: status.complete ? null : interviewAsk(signed),
+      contract: signed,
+    };
+  }
+  if (command === 'interview-freeze') {
+    const draft = read(options.input);
+    validateContract(draft, { requireDigest: false });
+    assertFreezable(draft);
+    const frozen = normalizeContract(draft);
+    const warnings = [];
+    validateContract(frozen, { substance: true, warnings });
+    return { frozen: true, contract_id: frozen.contract_id, contract_digest: frozen.contract_digest, ...(warnings.length ? { warnings } : {}), contract: frozen };
+  }
+  if (command === 'capabilities') return { tool: 'contract-tool', runtime_version: '1.2.0', task_contract_versions: [1], features: ['strict-json', 'canonical-digest', 'review-view', 'resign-diff', 'contract-projection', 'contract-scaffold', 'contract-interview'] };
   throw new ContractError(`命令必须是 ${Object.keys(CLI_SPEC).join('/')}`);
 }
 
@@ -162,7 +233,8 @@ export function runCli(argv = process.argv.slice(2)) {
     process.stdout.write(typeof result?.help === 'string' ? result.help : `${JSON.stringify(result, null, 2)}\n`);
     return 0;
   } catch (error) {
-    process.stderr.write(`${JSON.stringify({ error: 'invalid_contract', message: error.message })}\n`);
+    // interview 的拒绝不是"契约非法"，而是"还没问完 / 这轮作答不合规"，单独标记以便调用方分流。
+    process.stderr.write(`${JSON.stringify({ error: error instanceof InterviewError ? 'interview_rejected' : 'invalid_contract', message: error.message })}\n`);
     return 2;
   }
 }