@thincoder/core 0.10.7 → 0.10.9

package/agent-tools/spawn-gates.mjs

@@ -1,52 +1,40 @@
 /**
  * spawn-gates.mjs — M5 委派与 spawn 门新门禁统一落点（ENGINEERING-MODE-V2-MODULE-DELEGATION §2.3）：
  * 全部新增门禁逻辑集中于此——装配点（buildSpawnChild / normalizeFileList）只加 import 调用。
- * 已实现：F2（round 结构化参数 + 任务书五段文本字段校验）· F6（files 声明面拦截谓词）。
+ * 已实现：F2（round 枚举 + 任务书参数校验/拼装——四项核心 + 第五项按角色）· F6（files 声明面拦截谓词）。
  * 裁撤（2026-09-17 主 agent 裁定——不落代码）：
- *   - F4 修复轮窄带：全量勘察散文 marker 不可机判（误拒风险不可接受）→ 由 F2 五段字段覆盖；
+ *   - F4 修复轮窄带：全量勘察散文 marker 不可机判（误拒风险不可接受）→ 由 F2 的 round 参数承载轮次语义；
  *   - 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")
+/** 任务书样例内容（供人照抄；不是门的判据——门只判存在 / 类型 / 非空）：核心四项一份，
+ *  第五项按角色各一份（工程角色 = `designPoints` ∥ explore / plan / coder = `scope`）。 */
+const TASK_BOOK_CORE_MIN = {
+  goal: "实现批准设计（样例任务书——四项核心 + 角色第五项齐备）。",
+  knownFacts: "设计已评审通过、token 已签发、批次档在册。",
+  acceptance: "设计档的验收口径逐条可机验、项目验证链全绿。",
+  reportFormat: "交付表 + 文件路径 + 验证命令与结果。",
+}
+
+/** 工程角色样例（核心四项 + `designPoints`）。 */
+export const ENG_TASK_BOOK_MIN = { ...TASK_BOOK_CORE_MIN, designPoints: "仅落设计档受影响文件清单；禁夹带新语义。" }
+
+/** 非工程角色样例（核心四项 + `scope`）——explore / plan / coder。 */
+export const PLAIN_TASK_BOOK_MIN = { ...TASK_BOOK_CORE_MIN, scope: "只读：相关源 / 设计档；不写任何文件、不碰 bench/。" }
 
 /**
- * F2 任务书六强制字段校验（ENGINEERING-MODE-V2-MODULE-DELEGATION §2.2）：
- * round 枚举（initial|fix，必带集合 = eng-coder/eng-designer）+ 五段文本字段在场。
- * 缺任一 → 抛错（派单缺陷——spawn 机械拒）。scan 面 = args.task ∪ args.context
- * （context 是任务书背景段的携带参数——字段落在任一面均算在场）。
+ * F2 round 结构化参数校验（ENGINEERING-MODE-V2-MODULE-DELEGATION §2.2）：
+ * round 枚举（initial|fix，必带集合 = eng-coder/eng-designer）。
+ * 缺 / 非法 → 抛错（派单缺陷——spawn 机械拒）。
  */
-export function validateTaskBookFields(args) {
+export function validateRoundParam(args) {
   const a = args ?? {}
   const missing = []
   if (!ROUND_VALUES.includes(a.round)) {
@@ -54,17 +42,88 @@ export function validateTaskBookFields(args) {
       ? `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.`)
+    `Engineering spawn round gate: ${missing.join(" · ")}. ` +
+    `The spawn contract requires the structured round parameter (initial|fix); ` +
+    `the five task-book parameters are enforced by a separate gate (validateTaskBookParams) — ` +
+    `a missing or invalid round is a dispatch defect and the spawn is refused.`)
+}
+
+/**
+ * F2 任务书名集（**所有 spawn 角色**）：core = 四项核心（全员必带）；fifth = 第五项两名
+ * ——工程角色 = `designPoints` ∥ explore / plan / coder = `scope`。
+ * 单源：本档为唯一名集处——校验 / 拼装 / 探针夹具校验一律经 `taskBookParamsFor(role)` 派生（D2）。
+ * 样例对象 = `ENG_TASK_BOOK_MIN` / `PLAIN_TASK_BOOK_MIN`（供人照抄）。
+ */
+export const TASK_BOOK_PARAMS = {
+  core: ["goal", "knownFacts", "acceptance", "reportFormat"],
+  fifth: { engineering: "designPoints", plain: "scope" },
+}
+
+/** 角色 → 第五项类别（唯一判据；**与模式无关**——工程模式里的 explore 也取 plain）。
+ *  未知角色取 plain：spawn 路径上角色 enum 门先拒收（`agent-tools/subagent.mjs` 的 `ROLES`），到不了本门。 */
+function fifthClassOf(role) {
+  return role === "eng-coder" || role === "eng-designer" ? "engineering" : "plain"
+}
+
+/** 角色 → 该角色的任务书名集（四项核心 + 第五项；序 = 拼装序：第五项插在 `knownFacts` 之后，
+ *  与 C 之前 eng 角色的拼装序逐字相同——审计摘要 marker `/^Design points/i` 不受影响）。 */
+export function taskBookParamsFor(role) {
+  const core = TASK_BOOK_PARAMS.core
+  return [...core.slice(0, 2), TASK_BOOK_PARAMS.fifth[fifthClassOf(role)], ...core.slice(2)]
+}
+
+/** 拼装标签（不导出；仅词面，不是判据——无任何匹配读它）。 */
+const TASK_BOOK_LABELS = {
+  goal: "Goal & why",
+  knownFacts: "Known facts",
+  designPoints: "Design points & forbidden scope",
+  scope: "Scope (what to read / what not to touch)",
+  acceptance: "Acceptance criteria",
+  reportFormat: "Delivery report format",
+}
+
+/**
+ * F2 任务书参数校验（ENGINEERING-MODE-V2-MODULE-DELEGATION §2.2）· **所有 spawn 角色**：
+ * 名集按角色取（`taskBookParamsFor(role)`）。判据只有三条——参数存在 ∧ typeof string ∧
+ * trim() 非空。不读内容：无正则、无标题匹配、无双语 marker。缺 / 空白 / 非字符串 → 合并抛，
+ * 文案逐项点名该参数；第五项缺失而另一名在场时，文案附一句指路（只作文案，不加判据）。
+ */
+export function validateTaskBookParams(args, role) {
+  const a = args ?? {}
+  const names = taskBookParamsFor(role)
+  const fifth = TASK_BOOK_PARAMS.fifth[fifthClassOf(role)]
+  const otherFifth = fifth === "designPoints" ? "scope" : "designPoints"
+  const failed = []
+  for (const name of names) {
+    const v = a[name]
+    if (v === undefined || v === null) {
+      const hint = name === fifth && a[otherFifth] !== undefined && a[otherFifth] !== null
+        ? ` (got ${otherFifth} instead — that name belongs to the ${fifthClassOf(role) === "engineering" ? "explore/plan/coder" : "eng-coder/eng-designer"} spawns)`
+        : ""
+      failed.push(`${name} — missing (the task book is four core parameters + the role's fifth)${hint}`)
+    }
+    else if (typeof v !== "string") failed.push(`${name} — must be a string (got ${typeof v})`)
+    else if (v.trim() === "") failed.push(`${name} — blank (trim() is empty)`)
+  }
+  if (failed.length === 0) return
+  throw new Error(
+    `Spawn task-book gate (role='${role}'): ${failed.join(" · ")}. ` +
+    `The task book is four core parameters (${TASK_BOOK_PARAMS.core.join(" / ")}) plus ${fifth} ` +
+    `(the fifth parameter for role='${role}'); a missing, blank or non-string value is a dispatch defect and the spawn is refused.`)
+}
+
+/** 五参 → 子代理任务书文本（**非门禁**，纯拼装）：按 `taskBookParamsFor(role)` 固定序 + 标签，
+ * 空值跳过，`\n\n` 分隔。拼装单源 = 本函数——子代理 input 与探针判官的「任务书全文」同源。 */
+export function composeTaskBookBrief(args, role) {
+  const a = args ?? {}
+  const parts = []
+  for (const name of taskBookParamsFor(role)) {
+    const v = a[name]
+    if (typeof v === "string" && v.trim() !== "") parts.push(`${TASK_BOOK_LABELS[name]}: ${v.trim()}`)
+  }
+  return parts.join("\n\n")
 }
 
 /**
@@ -87,18 +146,20 @@ 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——本谓词在循环后跑——目录错误先于过程档错误）。
+ * scripts/*（工程工具面不入域——**层级锚定：仅仓根与直接子层**——目录名在深层不携带
+ * face 信息（2026-10-14 收正：#1449——`deployment/<x>/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-tools face path ${f} must not be listed in files — scripts/** is the engineering-tools face, not a content product (applies to every session, not engineering-mode-scoped; files carries source/test/design-doc paths only)`)
+    if (segs.slice(0, 2).some((s) => s.toLowerCase() === "scripts")) {
+      violations.push(`engineering-tools face path ${f} must not be listed in files — scripts/* at the repo root or a direct child package is the engineering-tools face, not a content product (applies to every session, not engineering-mode-scoped; 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) {