@thincoder/core 0.9.1

package/agent-tools/review-facts.mjs

@@ -0,0 +1,31 @@
+/**
+ * review-facts.mjs — design-review 事实面（纯事实：路径归一 + 评审范围键）。
+ *
+ * 本档前身 = 第 33 批（2026-09-11）的失败计数护栏档；其计数载体 / 停止谓词 / 两级检查点随
+ * 「撤除全部会话级轮次计数器」**整体退场**（2026-09-18 用户裁定；设计权威 =
+ * `docs/core/design/ADVISOR-CONVERGENCE.md` §3.1/§3.4 + `ADVISOR-GUARDS.md` §7）。
+ * 结算分类迁出为纯函数（输出判据名、零状态）= `thincoder-core/advisor/notice.mjs`。
+ *
+ * 本档 = 中立模块（**不 import 任何 src/ 模块**——打断潜在环）：
+ *  - `normAbs` 自 advisor-settle.mjs 迁入（原处 re-export——既有 import 面零变；陈旧判定 /
+ *    冻结拦截 / 评审范围键同源）；
+ *  - `docSetKey` 自 advisor-async.mjs 迁入（原为私有——零 import 面）。
+ */
+import { join } from "node:path"
+
+/** ABS 归一（cwd 相对 → cwd 拼接）——陈旧判定 / 冻结拦截 / 评审范围键同源（§14.14 E-4）。 */
+export function normAbs(p, cwd) {
+  const s = String(p)
+  return /^[a-zA-Z]:[\\/]/.test(s) || s.startsWith("/") || s.startsWith("\\\\") ? s : join(cwd, s)
+}
+
+/** Canonical scope key for design reviews — the document multi-set
+ *  (order-insensitive, ABS-path normalized — launch 与 continuation 的写法差异
+ *  ("./docs/x.md" vs "docs/x.md"、反斜杠) 不误建新实例).
+ *  第 33 批自 advisor-async.mjs 逐字迁入（实例续跑与事实面同锚单源）。 */
+export function docSetKey(documents, cwd) {
+  const list = [...new Set((documents ?? [])
+    .filter((d) => typeof d === "string" && d.trim())
+    .map((d) => normAbs(d, cwd)))]
+  return JSON.stringify(list.sort())
+}

package/agent-tools/settings.mjs

@@ -0,0 +1,268 @@
+/**
+ * settings tool — agent-side configuration adjustment (SETTINGS-TOOL.md, 2026-09-05).
+ * 用户裁定：全量 config.json 任意键（点分路径）+ 单工具多动作 list/get/set + 双端同批。
+ * 语义：set = 写盘（config.json——磁盘真相最小化：只写被设的键——默认值不固化）+
+ * 热应用（ctx.agent.config 内存对象立即更新——回合边界键下回合生效）。
+ * 护栏：敏感键（路径段命中词表 apiKey/key/token/secret/password/authorization/auth/cookie/credential，
+ * 或段名 headers/env 整族）回显/错误文本永不出现明文
+ * （••••（masked）——防密钥泄漏进会话历史/trace）；已知键类型校验——非 null 叶子类型表
+ * 自动派生自 config.mjs DEFAULTS（不手写防漂移——F-S1.5/N-S1.5）；null 默认值键与同族键
+ * 走显式形状表（_NULL_LEAF_SHAPES 相等面 / _SIBLING_SHAPES 存在性面——按各自真实消费形态
+ * 校验，完备性机械锁 + 一次性警告；SETTINGS-TOOL.md §8）；set 侧效走审批门（dispatch 动作级分类）。
+ */
+import { DEFAULTS, configPath, writeConfigAtomic } from "../config.mjs"
+
+/** 敏感键段判定（完整点分路径的段级匹配——两句取或：词表段 ∨ 开口键族段；SETTINGS-TOOL.md §2.4） */
+const SENSITIVE_SEGMENT = /(^|[._-])(api[_-]?key|key|token|secret|password|authorization|auth|cookie|credential)($|[._-])/i
+/** 开口键族段判定（headers / env——段名命中 ⇒ 其下全部子键整族遮罩：头名 / 变量名不可枚举） */
+const SENSITIVE_FAMILY = /(^|[._-])(headers|env)($|[._-])/i
+const MASKED = "••••（masked）"
+
+function isSensitiveKey(path) {
+  return SENSITIVE_SEGMENT.test(path) || SENSITIVE_FAMILY.test(path)
+}
+
+/* ─── 形状层（第 8 批 2026-09-11——SETTINGS-TOOL.md §8.3；两表结构：相等面 / 存在性面） ─── */
+
+/**
+ * null 叶子形状表——唯一「逐键手写形状」面（完备性锁的**相等面**：键集 == _nullLeafPaths(DEFAULTS)）。
+ * 表值 = 形状规格：接受集 = 该键真实消费形态 ∪ `null`（显式清除——消费面均有「未设置」态）；
+ * 不可消费形态（应用侧读不出写入值）→ 拒绝（违例抛错，磁盘/内存零变化）。
+ */
+const _NULL_LEAF_SHAPES = {
+  defaultModel: { kind: "nonEmptyString", providerModel: true, expects: 'non-empty string ("provider:model" composite)' },
+  "agent.subagentModel": { kind: "nonEmptyString", expects: "non-empty string" },
+  shell: { kind: "nonEmptyString", expects: "non-empty string" },
+  "memory.team": { kind: "team", expects: "object { repo: string, name?, dir? }" },
+}
+
+/** 同族/跨端形状表（**存在性断言面**——不参与完备性锁的集合相等）。W3 同族：`agent.subagentModels`
+ *  默认 `{}` ⇒ 派生表零条目 ⇒ 零约束（字符串被静默忽略——回落 subagentModel）。 */
+const _SIBLING_SHAPES = {
+  "agent.subagentModels": { kind: "roleMap", expects: "object of role→non-empty string" },
+}
+
+/** 派生：递归遍历默认值对象——叶子（非对象/数组值）记 `路径 → typeof 默认值`（旧语义逐字保留：
+ *  null 叶子记 "object"，其约束由形状表接管）；数组不递归（下标元素无类型约束——全量域）。 */
+function _deriveTypes(obj, prefix = "", out = {}) {
+  for (const [k, v] of Object.entries(obj)) {
+    const p = prefix ? `${prefix}.${k}` : k
+    if (v !== null && typeof v === "object" && !Array.isArray(v)) _deriveTypes(v, p, out)
+    else out[p] = Array.isArray(v) ? "array" : typeof v
+  }
+  return out
+}
+
+/** 类型表 = 派生 + 可选 `patch` 覆盖（测试缝——非 null 叶子逐键与派生结果相等；T-S2.15）。 */
+function _buildShapeTable(obj, patch = null) {
+  const out = _deriveTypes(obj)
+  return patch ? Object.assign(out, patch) : out
+}
+const TYPE_MAP = _buildShapeTable(DEFAULTS)
+
+/** null 叶子路径枚举（数组不递归——与派生表同域）。 */
+function _nullLeafPaths(obj, prefix = "", out = []) {
+  for (const [k, v] of Object.entries(obj)) {
+    const p = prefix ? `${prefix}.${k}` : k
+    if (v === null) out.push(p)
+    else if (typeof v === "object" && !Array.isArray(v)) _nullLeafPaths(v, p, out)
+  }
+  return out
+}
+
+/** 完备性锁（N-S1.5）：未声明的 null 叶子 = 形状表漂移——返回键名 + 一次性警告列出键名。 */
+let _shapeWarned = false
+function _checkShapeCompleteness(defaults, warn = console.warn) {
+  const declared = new Set(Object.keys(_NULL_LEAF_SHAPES))
+  const missing = _nullLeafPaths(defaults).filter((p) => !declared.has(p))
+  if (missing.length && !_shapeWarned) {
+    _shapeWarned = true
+    warn(`[settings] null-default keys missing from _NULL_LEAF_SHAPES: ${missing.join(", ")} — declare their real consumption shape`)
+  }
+  return missing
+}
+_checkShapeCompleteness(DEFAULTS) // 装载自检——形状表必须覆盖全部 null 叶子（漂移即警告）
+
+/** 值位渲染（错误文本——敏感键命中时遮罩：N-S1.2 / D-S2.4——明文零进错误句）。 */
+function _shownValue(path, value) {
+  return isSensitiveKey(path) ? MASKED : JSON.stringify(value)
+}
+
+function _kindOf(value) {
+  return value === null ? "null" : Array.isArray(value) ? "array" : typeof value
+}
+
+function _expectsError(path, expects, value) {
+  return new Error(`settings set: "${path}" expects ${expects} — got ${_kindOf(value)} (${_shownValue(path, value)})`)
+}
+
+/** 形状校验（形状表命中键——`null` 在 _checkKnownKeyValue 已放行）。 */
+function _checkShape(path, spec, value) {
+  if (spec.kind === "team") {
+    if (!value || typeof value !== "object" || Array.isArray(value)) throw _expectsError(path, spec.expects, value)
+    if (typeof value.repo !== "string" || !value.repo.trim()) {
+      throw new Error(`settings set: "${path}" requires a non-empty "repo" (team layer stays off without it) — got ${_shownValue(path, value)}`)
+    }
+    for (const k of ["name", "dir"]) {
+      if (value[k] !== undefined && (typeof value[k] !== "string" || !value[k].trim())) throw _expectsError(path, spec.expects, value)
+    }
+    return
+  }
+  if (spec.kind === "roleMap") {
+    if (!value || typeof value !== "object" || Array.isArray(value)) throw _expectsError(path, spec.expects, value)
+    for (const v of Object.values(value)) {
+      if (typeof v !== "string" || !v.trim()) throw _expectsError(path, spec.expects, value)
+    }
+    return
+  }
+  // nonEmptyString —— defaultModel 另加 provider:model 形态面（与 model-ref.mjs:25-36 同判据；
+  // 存在性面不查——D-S2.5）
+  if (typeof value !== "string" || !value.trim()) throw _expectsError(path, spec.expects, value)
+  if (spec.providerModel) {
+    const sep = value.indexOf(":")
+    if (sep <= 0 || !value.slice(sep + 1)) throw _expectsError(path, spec.expects, value)
+  }
+}
+
+/**
+ * 已知键值校验（set 写盘前；违例抛错——磁盘/内存零变化）：
+ * ① 形状表命中键（`_NULL_LEAF_SHAPES` / `_SIBLING_SHAPES` **两表都查**——表值 = 形状规格）→ 形状校验
+ *    （`null` = 显式清除，放行）；② 非 null 叶子（派生表值 = `typeof` 串）→ 既有语义逐字保留
+ *    （`want === "array"` 跳过 / `null` + `want === "object"` 放行）；③ 未知键 → 原样通过（全量域）。
+ */
+function _checkKnownKeyValue(path, value) {
+  const spec = _NULL_LEAF_SHAPES[path] ?? _SIBLING_SHAPES[path]
+  if (spec) {
+    if (value === null) return // 显式清除 = 有效动作（消费面均有「未设置」态——D-S2.3）
+    return _checkShape(path, spec, value)
+  }
+  const want = TYPE_MAP[path]
+  if (want && want !== "array") {
+    const got = value === null ? "null" : typeof value
+    if (got !== want && !(value === null && want === "object")) throw _expectsError(path, want, value)
+  }
+}
+
+/* ─── 既有工具面 helpers（第 8 批零改动） ─── */
+
+/** 点分路径解析（含数组数字段）——逐段下钻；返回 { ok, value } 或缺失段信息 */
+function resolvePath(obj, path) {
+  const segs = String(path).split(".")
+  let cur = obj
+  for (let i = 0; i < segs.length; i++) {
+    if (cur === null || typeof cur !== "object" || !(segs[i] in cur)) {
+      return { ok: false, reached: segs.slice(0, i).join("."), missing: segs[i], depth: i }
+    }
+    cur = cur[segs[i]]
+  }
+  return { ok: true, value: cur }
+}
+
+/** 点分路径写入（自动建中间对象——cmd-config 数值项同款）；返回旧值 */
+function setKeyPath(obj, path, value) {
+  const segs = String(path).split(".")
+  let cur = obj
+  for (let i = 0; i < segs.length - 1; i++) {
+    if (cur[segs[i]] === null || typeof cur[segs[i]] !== "object") cur[segs[i]] = {}
+    cur = cur[segs[i]]
+  }
+  const last = segs[segs.length - 1]
+  const old = cur[last]
+  cur[last] = value
+  return old
+}
+
+/** 递归展平 config 对象（数组下标段形态）→ 排序的 { path, value } 列表 */
+function flatten(obj, prefix = "", out = []) {
+  for (const [k, v] of Object.entries(obj)) {
+    const p = prefix ? `${prefix}.${k}` : k
+    if (v !== null && typeof v === "object") flatten(v, p, out)
+    else out.push({ path: p, value: v })
+  }
+  return out.sort((a, b) => (a.path < b.path ? -1 : 1))
+}
+
+/** 行格式化：`key = value (type)`——敏感键值遮罩 */
+function formatLine({ path, value }) {
+  const shown = isSensitiveKey(path) ? MASKED : value
+  return `${path} = ${shown} (${Array.isArray(value) ? "array" : typeof value})`
+}
+
+function parseValue(raw) {
+  const s = String(raw)
+  try {
+    const v = JSON.parse(s)
+    // JSON 顶层标量都接受；解析失败（裸字符串）→ 字符串字面
+    if (typeof v === "number" || typeof v === "boolean" || v === null || Array.isArray(v) || typeof v === "object") return v
+    // "abc"（带引号传的字符串）——JSON.parse 成功但返回字符串：返回**解析值**（去引号）
+    // ——两端统一 ①（2026-09-11 用户裁定；SETTINGS-TOOL.md §9.3）。
+    return v
+  } catch {
+    return s // 裸 abc → 字符串字面
+  }
+}
+
+export function settingsTool(opts = {}) {
+  const cfgPath = opts.configPath ?? configPath // 测试注入 tmp 文件；默认全局 configPath
+
+  return {
+    name: "settings",
+    description:
+      "Adjust ThinCoder runtime configuration — persisted to config.json AND hot-applied to the live agent config.\n" +
+      "Actions: list (all keys + values, flattened) | get <key> | set <key> <value> — dot paths into config.json (agent.maxTurns, traces.enabled, providers.0.model, any nesting).\n" +
+      "set persists to disk (only the set key is written — defaults are never baked in) and takes effect in the running session immediately (turn-boundary keys apply next turn); the value survives restarts.\n" +
+      "Known keys are type-checked: scalar keys against the built-in defaults (agent.maxTurns a number, traces.enabled a boolean); keys whose default is null against their real consumption shape — defaultModel \"provider:model\", agent.subagentModel / shell non-empty string, memory.team object with a repo — so a value the app would silently drop is refused (null clears the key). Unknown keys under a known section are stored as given. Values parse as JSON first (true/false/numbers/objects/arrays), else stay strings.\n" +
+      "SENSITIVE keys (path segment matching apiKey/key/token/secret/password/authorization/auth/cookie/credential, or any key under a headers/env segment) are NEVER echoed in plaintext — list/get/set replies show ••••（masked）; setting a sensitive key is allowed and stored, but never echoed back.\n" +
+      "list/get are read-only (planMode ok, no approval); set is a side effect (approval gate). The /config TUI command is the human equivalent.",
+    parameters: {
+      type: "object",
+      properties: {
+        action: { type: "string", enum: ["list", "get", "set"], description: "list — full key/value inventory; get <key> — one value; set <key> <value> — persist + hot-apply" },
+        key: { type: "string", description: "Dot path into config.json, e.g. agent.maxTurns / traces.enabled / providers.0.model" },
+        value: { type: "string", description: "New value for set — parsed as JSON first (true/5/{...}/[...]), otherwise kept as string" },
+      },
+      required: ["action"],
+    },
+    readonly: false, // set 是侧效——dispatch 动作级分类放行 list/get
+    async execute(args, ctx) {
+      const action = args?.action
+      if (!["list", "get", "set"].includes(action)) throw new Error(`settings: action must be one of list/get/set — got ${JSON.stringify(action)}`)
+      const config = ctx?.agent?.config ?? null
+      if (!config) throw new Error("settings: no live agent config (ctx.agent.config missing)")
+      if (action === "list") {
+        const rows = flatten(config)
+        if (rows.length === 0) return "（空配置——无已设置键）"
+        return rows.map(formatLine).join("\n")
+      }
+      if (action === "get") {
+        if (!args.key) throw new Error("settings get: key is required (dot path, e.g. agent.maxTurns)")
+        const r = resolvePath(config, args.key)
+        if (!r.ok) {
+          const hint = r.depth === 0 ? "（config 顶层无此键——顶层可用键见 settings list）" : `（父键 ${r.reached || "顶层"} 存在——无 ${r.missing} 子键）`
+          throw new Error(`settings get: no such key "${args.key}" ${hint}`)
+        }
+        return formatLine({ path: args.key, value: r.value })
+      }
+      // set
+      if (!args.key || args.value === undefined) throw new Error("settings set: key and value are required")
+      const value = parseValue(args.value)
+      // 已知键校验（形状表两表都查 + 派生类型表——SETTINGS-TOOL.md §8.3；未知键 JSON 原样）
+      _checkKnownKeyValue(String(args.key), value)
+      // 写盘（D-F5b：磁盘真相最小化——writeConfigAtomic 磁盘新鲜读 + 只改被设键 + mtime
+      // 门控——默认不固化；冲突/畸形抛错，内存不热应用（零虚假成功））+ 热应用（内存对象）
+      const r = await writeConfigAtomic(cfgPath, (disk) => {
+        setKeyPath(disk, args.key, value)
+      })
+      if (!r.ok) throw new Error("config changed on disk concurrently — retry (settings set not applied)")
+      setKeyPath(config, args.key, value)
+      const shown = isSensitiveKey(String(args.key)) ? MASKED : value
+      return `settings set: ${args.key} = ${shown} (${Array.isArray(value) ? "array" : typeof value})${isSensitiveKey(String(args.key)) ? " — stored（值不回显）" : " — persisted + hot-applied（运行中已生效）"}`
+    },
+  }
+}
+
+/**
+ * 测试缝导出（`_` 前缀——config.mjs `_setConfigPathForTest` 先例；SETTINGS-TOOL.md §8.3 第 6 条）：
+ * `_checkShapeCompleteness` = 完备性锁的运行时面（T-S2.14「一次性警告列出键名」的机械断言缝）。
+ */
+export { _buildShapeTable, _nullLeafPaths, _NULL_LEAF_SHAPES, _SIBLING_SHAPES, _checkKnownKeyValue, _checkShapeCompleteness }

package/agent-tools/skill.mjs

@@ -0,0 +1,63 @@
+import { loadSkills, readSkill } from "../skills.mjs"
+import { escapeXml } from "../agent.mjs"
+
+// ─── skill loader 注入缝（#88——「同步 loader 面按核内结构归一」的端侧覆盖面）──────────
+/**
+ * skill loader 注入位（**缺省不覆盖** = 核内异步 loader——CLI 语义，零行为变；端装配层
+ * 可覆盖为端形态（如核内同步面 `loadSkillsSync` / `readSkillSync` 的绑定）。核内零端名分支
+ * （契约 5——本档只认 `loadSkills` / `readSkill` 两函数名）。
+ * 契约：两键均可选；给了就用，缺键回核内默认；同步 / 异步返回值均可（内部 await）。
+ */
+let injectedLoader = null
+export function configureSkillLoader(impl) {
+  injectedLoader = impl && typeof impl === "object" ? impl : null
+}
+/** 撤销注入（测试与端装配生命周期用——缺省态 = 核内异步 loader）。 */
+export function resetSkillLoader() { injectedLoader = null }
+
+/**
+ * skill tool: load project skill files on demand (.thincoder/skills/*.md).
+ * After loading, skill content is injected into the conversation wrapped in <skill-loaded> for subsequent reference.
+ * Use action="list" to see all available skills.
+ */
+export const skillTool = {
+  name: "skill",
+  description:
+    "Load a project skill from .thincoder/skills/. Skills contain reusable instructions, workflows, or reference material. Use this when the user references a skill by name, or when a task matches a known skill's description. Call with action='list' to see available skills; call with action='load' and name=<skill> to activate one. " +
+    "Returns the skill list ('list'), the load confirmation ('load' — instructions arrive in the next message), or Error: ... with the available skills.",
+  parameters: {
+    type: "object",
+    properties: {
+      action: { type: "string", enum: ["list", "load"], description: "'list' to see available skills, 'load' to activate one" },
+      name: { type: "string", description: "Skill name (for 'load' action)" },
+    },
+    required: ["action"],
+  },
+  readonly: true,
+  async execute(args, ctx) {
+    const loadSkillsFn = typeof injectedLoader?.loadSkills === "function" ? injectedLoader.loadSkills : loadSkills
+    const readSkillFn = typeof injectedLoader?.readSkill === "function" ? injectedLoader.readSkill : readSkill
+    const skills = await loadSkillsFn(ctx.agent.cwd)
+    if (args.action === "list") {
+      if (skills.length === 0) return "No project skills found in .thincoder/skills/."
+      return skills.map((s) => `- ${s.name}: ${s.description}`).join("\n")
+    }
+    if (!args.name) return "Error: skill name required for 'load' action."
+    // Dedup: skip reloading if history already contains an <skill-loaded> block with the same name
+    // (history is the ledger; if it got compacted away we naturally won't find it here — correct behavior)
+    if (ctx.agent.history?.some((m) => typeof m.content === "string" && m.content.includes(`<skill-loaded name="${args.name}"`))) {
+      return `Skill "${args.name}" is already loaded in this conversation — follow the instructions in the existing <skill-loaded> block above. Do not reload it.`
+    }
+    const content = await readSkillFn(ctx.agent.cwd, args.name)
+    if (!content) {
+      const available = skills.map((s) => s.name).join(", ")
+      return `Error: skill "${args.name}" not found. Available: ${available || "(none)"}`
+    }
+    // Inject skill content into history (will appear as the next user message)
+    ctx.agent._pendingReminders = ctx.agent._pendingReminders ?? []
+    ctx.agent._pendingReminders.push(
+      `<skill-loaded name="${args.name}" source=".thincoder/skills/${args.name}.md">\n${escapeXml(content)}\n</skill-loaded>\n\nFollow the skill's instructions above for the current task.`
+    )
+    return `Skill "${args.name}" loaded. Instructions will appear in the next message.`
+  },
+}

package/agent-tools/spawn-gates.mjs

@@ -0,0 +1,109 @@
+/**
+ * spawn-gates.mjs — M5 委派与 spawn 门新门禁统一落点（ENGINEERING-MODE-V2-MODULE-DELEGATION §2.3）：
+ * 全部新增门禁逻辑集中于此——装配点（buildSpawnChild / normalizeFileList）只加 import 调用。
+ * 已实现：F2（round 结构化参数 + 任务书五段文本字段校验）· F6（files 声明面拦截谓词）。
+ * 裁撤（2026-09-17 主 agent 裁定——不落代码）：
+ *   - F4 修复轮窄带：全量勘察散文 marker 不可机判（误拒风险不可接受）→ 由 F2 五段字段覆盖；
+ *   - F5 advisor 角色：advisor 不入 spawn 通道（评审走 advisor 工具）——enum 收正为
+ *     explore/eng-designer/eng-coder。
+ * 零依赖：本模块零 import（叶子——纯谓词层，无环、无反向依赖）。
+ */
+
+/**
+ * F2 任务书五段文本字段（六强制字段中 round 之外的五段——ENGINEERING-MODE-V2-MODULE-DELEGATION §1.2 F2）。
+ * 判据 = 段标题在场（标题行或行内 marker——summaryEngTaskBook 同款手法：marker 正则命中
+ * task ∪ context 文本即可）；内容够不够由执行者拒收兜底（需求 §1.14 #9 行为面——不做内容校验）。
+ * 双语 marker：中文标题（主 agent 派单形）与英文标题（交付报告格式模板形）同收。
+ */
+const TASK_BOOK_FIELDS = [
+  { label: "目标与理由 (goal & why)", markers: [/目标与理由/, /goal\s*&\s*why/i, /goal\s+and\s+why/i] },
+  { label: "已知事实 (known facts)", markers: [/已知事实/, /known\s+facts/i] },
+  { label: "设计要点与禁止范围 (design points & forbidden scope)", markers: [/设计要点/, /design\s+points/i] },
+  { label: "验收标准 (acceptance criteria)", markers: [/验收标准/, /acceptance\s+criteria/i] },
+  { label: "交付报告格式 (delivery-report format)", markers: [/交付报告格式/, /交付报告/, /delivery[- ]report\s+format/i] },
+]
+
+/** F2 round 合法值（初始轮 / 修正轮——「派单必带」= 无默认值）。
+ * 单源：本档为唯一字面量处——schema 面（`agent-tools/subagent.mjs`）与谓词面（本档）同引用（D2）。
+ */
+export const ROUND_VALUES = ["initial", "fix"]
+
+/**
+ * 五段任务书最小合法样例（F2 契约的正面样例——跨仓测试夹具共用单源；段落名 = 父侧
+ * 任务书五段模板）。文本字段判据 = 在场性（内容质量由执行者拒收兜底——需求 §1.14 #9）。
+ */
+export const ENG_TASK_BOOK_MIN = [
+  "目标与理由：实现批准设计（夹具任务书——五段文本字段齐备）。",
+  "已知事实：设计已评审通过、token 已签发、批次档在册。",
+  "设计要点与禁止范围：仅落设计档受影响文件清单；禁夹带新语义。",
+  "验收标准：设计档验收标准逐条可机验、项目验证链全绿。",
+  "交付报告格式：交付表 + 文件路径 + 验证命令与结果。",
+].join("\n")
+
+/**
+ * F2 任务书六强制字段校验（ENGINEERING-MODE-V2-MODULE-DELEGATION §2.2）：
+ * round 枚举（initial|fix，必带集合 = eng-coder/eng-designer）+ 五段文本字段在场。
+ * 缺任一 → 抛错（派单缺陷——spawn 机械拒）。scan 面 = args.task ∪ args.context
+ * （context 是任务书背景段的携带参数——字段落在任一面均算在场）。
+ */
+export function validateTaskBookFields(args) {
+  const a = args ?? {}
+  const missing = []
+  if (!ROUND_VALUES.includes(a.round)) {
+    missing.push(a.round === undefined || a.round === null
+      ? `round (${ROUND_VALUES.join("|")}) — the structured round parameter`
+      : `round ∈ {${ROUND_VALUES.join(", ")}} (got ${JSON.stringify(a.round)})`)
+  }
+  const text = [a.context, a.task].filter((s) => typeof s === "string").join("\n")
+  for (const f of TASK_BOOK_FIELDS) {
+    if (!f.markers.some((m) => m.test(text))) missing.push(f.label)
+  }
+  if (missing.length === 0) return
+  throw new Error(
+    `Engineering spawn task book is missing mandatory field(s): ${missing.join(" · ")}. ` +
+    `The six-field task book — 目标与理由 (goal & why), round (initial|fix), 已知事实 (known facts), ` +
+    `设计要点与禁止范围 (design points & forbidden scope), 验收标准 (acceptance criteria), ` +
+    `交付报告格式 (delivery-report format) — is the spawn contract; a missing field is a dispatch ` +
+    `defect and the spawn is refused.`)
+}
+
+/**
+ * F6 过程档 basename 族（父侧维护文件——AGENT-LOOP.md §28 R26 F-R26b 同族扩展）：
+ * CHANGELOG.md。（台账 = 用户数据目录键控库——项目内无文件，不再入族；老台账族 todo.md /
+ * todo-archive.md / checklist 族随 M2 SQLite 化 + M7 checklist 废除退役。）
+ * 大小写不敏感全名匹配（路径任意层——归一化在调用点 normalizeFileList 已做）。
+ */
+const PROCESS_BASENAMES = new Set(["changelog.md"])
+
+/**
+ * 工程模式写入面 basename（#33 二道防线——设计 docs/core/design/MANIFEST.md §2.5 / KD-M1-14）：
+ * PROJECT-MANIFEST.json = M1 项目状态档——写门唯主 agent（`manifest.mjs` `writeManifest` 的
+ * `writer` 闸，fail-closed）；本常量 = `files` 声明面**第二道防线**（子代理无法把该路径声明为
+ * 写域）。字面量（匹配前已大小写归一；**不** import `MANIFEST_REL`——保本模块「叶子·零 import」
+ * 性质；单源指针 = `thincoder-core/manifest.mjs`）。**不入** `PROCESS_BASENAMES`：两族理由不同
+ * ——过程档 = 父侧对账职责；本档 = 写门唯主 agent。
+ */
+const MANIFEST_BASENAME = "project-manifest.json"
+
+/**
+ * F6 files 声明面拦截谓词（ENGINEERING-MODE-V2-MODULE-DELEGATION §2.2）：
+ * scripts/**（工程工具面不入域——内容产物 only）与过程档（父侧职责）→ 收集全部违规
+ * 后抛合并错误（fail-closed——错误即工具结果 JSON——无排队残留）。目录声明不在本
+ * 谓词（normalizeFileList 循环内先行拒——错误序不变）。调用点 = normalizeFileList
+ * （subagent-scheduler.mjs——本谓词在循环后跑——目录错误先于过程档错误）。
+ */
+export function rejectEngineeringFilePaths(files) {
+  const violations = []
+  for (const f of Array.isArray(files) ? files : []) {
+    const segs = String(f).replace(/\\/g, "/").split("/").filter((s) => s)
+    const base = (segs[segs.length - 1] ?? "").toLowerCase()
+    if (segs.some((s) => s.toLowerCase() === "scripts")) {
+      violations.push(`engineering tool path ${f} must not be listed in files — scripts/** is the engineering-tool face, not a content product (files carries source/test/design-doc paths only)`)
+    } else if (PROCESS_BASENAMES.has(base)) {
+      violations.push(`Parent-side maintained file ${f} must not be listed in files — reconciliation is the parent's duty; use the design-doc path if you need to edit a design doc`)
+    } else if (base === MANIFEST_BASENAME) {
+      violations.push(`Manifest file ${f} must not be listed in files — PROJECT-MANIFEST.json is the project state manifest and the main agent is its only writer (M1 write gate); this files-domain check is the second line of defense`)
+    }
+  }
+  if (violations.length > 0) throw new Error(violations.join("\n"))
+}