dominds 1.22.1 → 1.23.1

package/dist/tools/ctrl.js

@@ -18,7 +18,7 @@
  * - change_mind: Main Dialog only; update a `.tsk/` Taskdoc section without starting a new course
  * - mind_more: Main Dialog only; append entries to a `.tsk/` Taskdoc section without starting a new course
  * - never_mind: Main Dialog only; delete a `.tsk/` Taskdoc section file without starting a new course
- * - recall_taskdoc: Read a Taskdoc section from `*.tsk/` by (category, selector)
+ * - recall_taskdoc: Read a Taskdoc section from `*.tsk/` by selector and optional category
  *
  * USAGE CONTEXT:
  * Can both be triggered by an agent autonomously, or by human with role='user' msg,
@@ -370,13 +370,21 @@ function getCtrlMessages(language) {
             invalidReminderPosition: (positionHuman, totalPlusOne) => `位置 ${positionHuman} 无效。有效范围：1-${totalPlusOne}`,
             invalidFormatUpdate: '参数格式不对。用法：update_reminder({ reminder_id: string, content: string })',
             invalidFormatDoMind: '参数格式不对。用法：do_mind({ selector: string, category?: string, content: string })',
-            invalidFormatChangeMind: '参数格式不对。用法：change_mind({ selector: string, category?: string, content: string })',
-            tooManyArgsChangeMind: '参数格式不对。用法：change_mind({ selector: string, category?: string, content: string })',
+            invalidFormatChangeMind: '参数格式不对。用法：change_mind({ selector: string, category?: string, content: string, previous_content_hash: string })',
+            tooManyArgsChangeMind: '参数格式不对。用法：change_mind({ selector: string, category?: string, content: string, previous_content_hash: string })',
+            taskDocPreviousContentHashRequired: '错误：change_mind 需要 previous_content_hash。请先调用 recall_taskdoc 显式取得当前章节的 content_hash，合并原有内容后再整段替换；没有把握时用 mind_more 追加小条目。',
+            taskDocPreviousContentHashInvalid: '错误：previous_content_hash 格式无效。它必须是 recall_taskdoc 返回的 crc32:<8位十六进制> content_hash。',
+            taskDocContentHashMismatch: (relativePath, currentContentHash) => `错误：${relativePath} 的内容哈希不匹配，说明该章节已变化或你没有基于当前内容改写。\n` +
+                `当前 content_hash：${currentContentHash}\n\n` +
+                `请重新读取/回顾当前章节内容，并只在已充分合并原有内容后重试。若新内容会冲掉、删除或实质替换原有内容，必须满足其一：\n` +
+                `- 获得人类对该替换的直接、针对性确认；或\n` +
+                `- 依据人类认可的明确 SOP/验收标准，已经充分考虑原有内容且该替换合规。\n` +
+                `否则不要覆盖；优先使用 mind_more 追加或向人类确认。`,
             invalidFormatMindMore: '参数格式不对。用法：mind_more({ items: string[], sep?: string, selector?: string, category?: string })（selector 默认 progress）',
             invalidFormatNeverMind: '参数格式不对。用法：never_mind({ selector: string, category?: string })',
             mindMoreItemsRequired: '需要提供要追加的条目（items），且每一项都必须是非空字符串。\n' +
                 '示例：mind_more({"items":["- 下一步：复核验证结果（详见 <文档路径>#<章节>）","- 阻塞：等待 API 验收口径确认"]})',
-            invalidFormatRecallTaskdoc: '参数格式不对。用法：recall_taskdoc({ category: string, selector: string })',
+            invalidFormatRecallTaskdoc: '参数格式不对。用法：recall_taskdoc({ selector: string, category?: string })',
             taskDocContentRequired: '需要提供差遣牒内容（content）。\n' +
                 '示例：\n' +
                 '```json\n' +
@@ -389,15 +397,14 @@ function getCtrlMessages(language) {
             pathMustBeWithinWorkspace: '路径必须位于 rtws（运行时工作区）内',
             invalidTaskDocPath: (taskDocPath) => `差遣牒路径 '${taskDocPath}' 无效。应为 *.tsk/ 目录。`,
             selectorRequired: '需要提供选择器（selector）。',
-            categoryRequired: '需要提供章节目录（category）。',
             invalidSelector: (selector) => `选择器 '${selector}' 无效。可用：顶层 goals | constraints | progress；bearinmind 下 contracts | acceptance | grants | runbook | decisions | risks；或任意标识符（如 ux.checklist）。`,
             invalidCategory: (category) => `目录名 '${category}' 无效。需匹配 ^[a-zA-Z][a-zA-Z0-9_-]*(\\.[a-zA-Z0-9_-]*)*$。`,
             invalidCategorySelector: (selector) => `选择器 '${selector}' 无效。需匹配 ^[a-zA-Z][a-zA-Z0-9_-]*(\\.[a-zA-Z0-9_-]*)*$。`,
             topLevelSelectorRequiresNoCategory: (category, selector) => `选择器 '${selector}' 是顶层保留分段（goals/constraints/progress），不能与 category='${category}' 一起用。`,
             bearInMindSelectorRequiresBearInMindCategory: (category, selector) => `选择器 '${selector}' 只能在 category='bearinmind' 下用（当前 category='${category}'）。`,
-            taskDocSectionAlreadyExists: (relativePath) => `无法新增：${relativePath} 已存在。若确有把握要改写已有章节，请使用 change_mind({ ... })。`,
+            taskDocSectionAlreadyExists: (relativePath) => `无法新增：${relativePath} 已存在。若确有把握要改写已有章节，请先用 recall_taskdoc 取得当前 content_hash，再使用 change_mind({"selector":"<selector>","content":"...","previous_content_hash":"crc32:..."})。`,
             taskDocSectionChangeMissing: (relativePath) => `无法修改：${relativePath} 不存在。若要新增章节，请使用 do_mind({ ... })。`,
-            taskDocSectionMissing: (relativePath) => `未找到：${relativePath}。\n\n新增章节请使用 do_mind；已有章节追加小条目用 mind_more；改写已有章节用 change_mind：\n- do_mind({"category":"<category>","selector":"<selector>","content":"..."})\n- mind_more({"category":"<category>","selector":"<selector>","items":["..."]})\n- change_mind({"category":"<category>","selector":"<selector>","content":"..."})`,
+            taskDocSectionMissing: (relativePath) => `未找到：${relativePath}。\n\n新增章节请使用 do_mind；已有章节追加小条目用 mind_more；改写已有章节时先用 recall_taskdoc 取得当前 content_hash，再用 change_mind 带上它：\n- do_mind({"category":"<category>","selector":"<selector>","content":"..."})\n- mind_more({"category":"<category>","selector":"<selector>","items":["..."]})\n- recall_taskdoc({"category":"<category>","selector":"<selector>"})\n- change_mind({"category":"<category>","selector":"<selector>","content":"...","previous_content_hash":"crc32:..."})`,
             taskDocSectionDeleteMissing: (relativePath) => `无法删除：${relativePath} 不存在。请先确认要删除的差遣牒章节。`,
             clearedCoursePrompt: (nextCourse) => (0, driver_messages_1.formatNewCourseStartPrompt)('zh', { nextCourse, source: 'clear_mind' }),
         };
@@ -412,13 +419,21 @@ function getCtrlMessages(language) {
         invalidReminderPosition: (positionHuman, totalPlusOne) => `Error: Invalid reminder position ${positionHuman}. Valid range: 1-${totalPlusOne}`,
         invalidFormatUpdate: 'Error: Invalid args. Use: update_reminder({ reminder_id: string, content: string })',
         invalidFormatDoMind: 'Error: Invalid args. Use: do_mind({ selector: string, category?: string, content: string })',
-        invalidFormatChangeMind: 'Error: Invalid args. Use: change_mind({ selector: string, category?: string, content: string })',
-        tooManyArgsChangeMind: 'Error: Invalid args. Use: change_mind({ selector: string, category?: string, content: string })',
+        invalidFormatChangeMind: 'Error: Invalid args. Use: change_mind({ selector: string, category?: string, content: string, previous_content_hash: string })',
+        tooManyArgsChangeMind: 'Error: Invalid args. Use: change_mind({ selector: string, category?: string, content: string, previous_content_hash: string })',
+        taskDocPreviousContentHashRequired: 'Error: change_mind requires previous_content_hash. Call recall_taskdoc first to get the current section content_hash, merge the existing content, then replace the full section. If unsure, use mind_more for small append-only updates.',
+        taskDocPreviousContentHashInvalid: 'Error: invalid previous_content_hash. It must be the crc32:<8 hex chars> content_hash returned by recall_taskdoc.',
+        taskDocContentHashMismatch: (relativePath, currentContentHash) => `Error: content hash mismatch for \`${relativePath}\`; the section changed or your replacement was not based on the current content.\n` +
+            `Current content_hash: ${currentContentHash}\n\n` +
+            `Re-read/review the current section and retry only after fully merging existing content. If the new content would overwrite, delete, or materially replace existing content, one of these must be true:\n` +
+            `- A human gave direct, targeted confirmation for this replacement; or\n` +
+            `- A human-approved explicit SOP/acceptance standard authorizes the replacement, and you have considered the existing content under that standard.\n` +
+            `Otherwise do not overwrite; prefer mind_more or ask the human to confirm.`,
         invalidFormatMindMore: 'Error: Invalid args. Use: mind_more({ items: string[], sep?: string, selector?: string, category?: string }) (selector defaults to progress).',
         invalidFormatNeverMind: 'Error: Invalid args. Use: never_mind({ selector: string, category?: string })',
         mindMoreItemsRequired: 'Error: items are required, and every item must be a non-empty string.\n' +
             'Example: mind_more({"items":["- Next: review verification results (details: <doc-path>#<section>)","- Blocker: API acceptance criteria pending"]})',
-        invalidFormatRecallTaskdoc: 'Error: Invalid args. Use: recall_taskdoc({ category: string, selector: string })',
+        invalidFormatRecallTaskdoc: 'Error: Invalid args. Use: recall_taskdoc({ selector: string, category?: string })',
         taskDocContentRequired: 'Error: Taskdoc content is required (content).\n' +
             'Copy/paste example:\n' +
             '```json\n' +
@@ -431,15 +446,14 @@ function getCtrlMessages(language) {
         pathMustBeWithinWorkspace: 'Error: Path must be within rtws (runtime workspace)',
         invalidTaskDocPath: (taskDocPath) => `Error: Invalid Taskdoc path '${taskDocPath}'. Expected a \`*.tsk/\` directory.`,
         selectorRequired: 'Error: selector is required.',
-        categoryRequired: 'Error: category is required.',
         invalidSelector: (selector) => `Error: Invalid selector '${selector}'. Use: top-level goals|constraints|progress; under bearinmind: contracts|acceptance|grants|runbook|decisions|risks; or any identifier (e.g. \`ux.checklist\`).`,
         invalidCategory: (category) => `Error: Invalid category '${category}'. Must match \`^[a-zA-Z][a-zA-Z0-9_-]*(\\.[a-zA-Z0-9_-]+)*$\`.`,
         invalidCategorySelector: (selector) => `Error: Invalid category selector '${selector}'. Must match \`^[a-zA-Z][a-zA-Z0-9_-]*(\\.[a-zA-Z0-9_-]+)*$\`.`,
         topLevelSelectorRequiresNoCategory: (category, selector) => `Error: Selector '${selector}' is reserved for top-level sections (goals/constraints/progress) and must not be used with category='${category}'.`,
         bearInMindSelectorRequiresBearInMindCategory: (category, selector) => `Error: Selector '${selector}' is only valid under category='bearinmind' (got category='${category}').`,
-        taskDocSectionAlreadyExists: (relativePath) => `Cannot add: \`${relativePath}\` already exists. If you are sure you need to rewrite an existing section, use \`change_mind({ ... })\`.`,
+        taskDocSectionAlreadyExists: (relativePath) => `Cannot add: \`${relativePath}\` already exists. If you are sure you need to rewrite an existing section, call \`recall_taskdoc\` for the current content_hash first, then use \`change_mind({"selector":"<selector>","content":"...","previous_content_hash":"crc32:..."})\`.`,
         taskDocSectionChangeMissing: (relativePath) => `Cannot change: \`${relativePath}\` does not exist. To create a new section, use \`do_mind({ ... })\`.`,
-        taskDocSectionMissing: (relativePath) => `Not found: \`${relativePath}\`.\n\nUse \`do_mind\` to create a section, \`mind_more\` for small append-only updates to existing sections, and \`change_mind\` to rewrite existing sections:\n- \`do_mind({\"category\":\"<category>\",\"selector\":\"<selector>\",\"content\":\"...\"})\`\n- \`mind_more({\"category\":\"<category>\",\"selector\":\"<selector>\",\"items\":[\"...\"]})\`\n- \`change_mind({\"category\":\"<category>\",\"selector\":\"<selector>\",\"content\":\"...\"})\``,
+        taskDocSectionMissing: (relativePath) => `Not found: \`${relativePath}\`.\n\nUse \`do_mind\` to create a section, \`mind_more\` for small append-only updates to existing sections, and \`recall_taskdoc\` then \`change_mind\` with the current content_hash to rewrite existing sections:\n- \`do_mind({\"category\":\"<category>\",\"selector\":\"<selector>\",\"content\":\"...\"})\`\n- \`mind_more({\"category\":\"<category>\",\"selector\":\"<selector>\",\"items\":[\"...\"]})\`\n- \`recall_taskdoc({\"category\":\"<category>\",\"selector\":\"<selector>\"})\`\n- \`change_mind({\"category\":\"<category>\",\"selector\":\"<selector>\",\"content\":\"...\",\"previous_content_hash\":\"crc32:...\"})\``,
         taskDocSectionDeleteMissing: (relativePath) => `Cannot delete: \`${relativePath}\` does not exist. Check the Taskdoc section target first.`,
         clearedCoursePrompt: (nextCourse) => (0, driver_messages_1.formatNewCourseStartPrompt)('en', { nextCourse, source: 'clear_mind' }),
     };
@@ -721,7 +735,7 @@ exports.changeMindTool = {
     parameters: {
         type: 'object',
         additionalProperties: false,
-        required: ['selector', 'content'],
+        required: ['selector', 'content', 'previous_content_hash'],
         properties: {
             selector: {
                 type: 'string',
@@ -732,6 +746,10 @@ exports.changeMindTool = {
                 description: 'Optional category directory within the Taskdoc package. When present, selector targets <category>/<selector>.md.',
             },
             content: { type: 'string', description: 'New section content.' },
+            previous_content_hash: {
+                type: 'string',
+                description: 'Content hash of the current section being replaced. Call recall_taskdoc first and use the returned content_hash.',
+            },
         },
     },
     argsValidation: 'dominds',
@@ -760,6 +778,13 @@ exports.changeMindTool = {
         const newTaskDocContent = typeof contentValue === 'string' ? contentValue.trim() : '';
         if (!newTaskDocContent)
             return (0, tool_1.toolFailure)(t.taskDocContentRequired);
+        const previousContentHashValue = args['previous_content_hash'];
+        const previousContentHash = typeof previousContentHashValue === 'string' ? previousContentHashValue.trim() : '';
+        if (!previousContentHash)
+            return (0, tool_1.toolFailure)(t.taskDocPreviousContentHashRequired);
+        if (!/^crc32:[0-9a-f]{8}$/u.test(previousContentHash)) {
+            return (0, tool_1.toolFailure)(t.taskDocPreviousContentHashInvalid);
+        }
         // Taskdoc path is immutable for the dialog lifecycle.
         const taskDocPath = dlg.taskDocPath;
         if (!taskDocPath)
@@ -799,6 +824,7 @@ exports.changeMindTool = {
             taskPackageDirFullPath: fullPath,
             target: parsed.target,
             content: newTaskDocContent,
+            previousContentHash,
             updatedBy: caller.id,
         });
         switch (result.kind) {
@@ -806,6 +832,8 @@ exports.changeMindTool = {
                 return (0, tool_result_messages_1.formatToolActionResult)(language, 'mindChanged');
             case 'missing':
                 return (0, tool_1.toolFailure)(t.taskDocSectionChangeMissing((0, task_package_1.taskPackageRelativePathForChangeMindTarget)(parsed.target)));
+            case 'content_hash_mismatch':
+                return (0, tool_1.toolFailure)(t.taskDocContentHashMismatch((0, task_package_1.taskPackageRelativePathForChangeMindTarget)(parsed.target), result.currentContentHash));
             default: {
                 const _exhaustive = result;
                 return _exhaustive;
@@ -1136,18 +1164,24 @@ exports.mindMoreTool = {
 exports.recallTaskdocTool = {
     type: 'func',
     name: 'recall_taskdoc',
-    description: 'Read one Taskdoc section by (category, selector).',
+    description: 'Read one Taskdoc section and return its content_hash.',
     descriptionI18n: {
-        en: 'Read one Taskdoc section by (category, selector).',
-        zh: '按 (category, selector) 读取一段差遣牒章节。',
+        en: 'Read one Taskdoc section and return its content_hash.',
+        zh: '读取一段差遣牒章节并返回 content_hash。',
     },
     parameters: {
         type: 'object',
         additionalProperties: false,
-        required: ['category', 'selector'],
+        required: ['selector'],
         properties: {
-            category: { type: 'string', description: 'Category directory within the Taskdoc.' },
-            selector: { type: 'string', description: 'Section selector within the category.' },
+            category: {
+                type: 'string',
+                description: 'Optional category directory within the Taskdoc. Omit for top-level goals|constraints|progress.',
+            },
+            selector: {
+                type: 'string',
+                description: 'Section selector. Top-level: goals|constraints|progress. With category: selector within that category.',
+            },
         },
     },
     argsValidation: 'dominds',
@@ -1155,9 +1189,10 @@ exports.recallTaskdocTool = {
         const language = (0, work_language_1.getWorkLanguage)();
         const t = getCtrlMessages(language);
         const categoryValue = args['category'];
-        const category = typeof categoryValue === 'string' ? categoryValue.trim() : '';
-        if (category === '')
-            return (0, tool_1.toolFailure)(t.categoryRequired);
+        if (categoryValue !== undefined && typeof categoryValue !== 'string') {
+            return (0, tool_1.toolFailure)(t.invalidFormatRecallTaskdoc);
+        }
+        const category = typeof categoryValue === 'string' ? categoryValue.trim() : undefined;
         const selectorValue = args['selector'];
         const selector = typeof selectorValue === 'string' ? selectorValue.trim() : '';
         if (selector === '')
@@ -1198,9 +1233,6 @@ exports.recallTaskdocTool = {
             }
         }
         const target = parsed.target;
-        if (target.kind === 'top_level') {
-            return (0, tool_1.toolFailure)(t.invalidFormatRecallTaskdoc);
-        }
         const relPath = (0, task_package_1.taskPackageRelativePathForChangeMindTarget)(target);
         const sectionPath = path.resolve(fullPath, relPath);
         if (!isPathWithinDirectory(sectionPath, fullPath)) {
@@ -1221,7 +1253,14 @@ exports.recallTaskdocTool = {
             }
             throw err;
         }
-        const content = await fs.promises.readFile(sectionPath, 'utf8');
+        const current = await (0, task_package_1.readTaskPackageByChangeMindTarget)({
+            taskPackageDirFullPath: fullPath,
+            target,
+        });
+        if (current.kind === 'missing') {
+            return (0, tool_1.toolFailure)(t.taskDocSectionMissing(relPath));
+        }
+        const content = current.content;
         const bytes = Buffer.byteLength(content, 'utf8');
         const maxSize = 100 * 1024;
         const clipped = bytes > maxSize ? content.slice(0, maxSize) : content;
@@ -1231,6 +1270,6 @@ exports.recallTaskdocTool = {
                 : `\n\n⚠️ Truncated: content is too large (${bytes} bytes); showing first ${maxSize} bytes.`
             : '';
         const closingSeparatorPrefix = clipped.endsWith('\n') ? '' : '\n';
-        return (0, tool_1.toolSuccess)(`**recall_taskdoc:** \`${relPath}\`\n\n---\n${clipped}${closingSeparatorPrefix}---${note}`);
+        return (0, tool_1.toolSuccess)(`**recall_taskdoc:** \`${relPath}\`\ncontent_hash: \`${current.contentHash}\`\n\n---\n${clipped}${closingSeparatorPrefix}---${note}`);
     },
 };

package/dist/tools/prompts/control/en/principles.md

@@ -132,8 +132,8 @@ Taskdoc is a **task contract** and the task's **team-shared source of current tr
 
 - Keep concise: reminders are often 1-3 items; prefer `update_reminder` to compress/merge
 - Separate carriers: information that must synchronize the team's current effective state, key decisions, next steps, or still-active blockers belongs in `progress`, the quasi-real-time task bulletin board; reminders keep local resume details
-- Team-facing: keep `progress` scannable and centered on what is still effective now; do not let it degrade into a personal log, raw chronology, scratchpad, or stale history pile. Use `mind_more` for small additions and `change_mind` when cleanup/reordering/compression is needed
-- Condense when needed: `mind_more` is not the default bookkeeping move. If one topic already has several phase notes, prefer `change_mind` to merge them into the current summary; put the detailed expansion in formal rtws documentation and keep a document pointer in Taskdoc
+- Team-facing: keep `progress` scannable and centered on what is still effective now; do not let it degrade into a personal log, raw chronology, scratchpad, or stale history pile. Use `mind_more` for small additions; when cleanup/reordering/compression is needed, call `recall_taskdoc` first and then use `change_mind` with the returned `content_hash` as `previous_content_hash`
+- Condense when needed: `mind_more` is not the default bookkeeping move. If one topic already has several phase notes, prefer `change_mind` to merge them into the current summary; put the detailed expansion in formal rtws documentation and keep a document pointer in Taskdoc. If the replacement would overwrite existing content, proceed only with direct human confirmation or after applying a human-approved SOP/acceptance standard that considers the existing content
 - Collapse before clearing: the Main Dialog first records undocumented discussion details the next course needs to know into the appropriate Taskdoc sections, then creates a structured continuation-package reminder; a Side Dialog must not maintain Taskdoc or draft Taskdoc update proposals, and should directly maintain sufficiently detailed continuation-package reminders. If the current course is already under system remediation, rough multi-reminder carry-over is acceptable but must be reconciled first in the new course
 - Avoid raw-material dumps: do not paste long logs or large tool outputs into reminders
 - Documentation layering: Taskdoc says “what the team should sync on / do next now”; formal rtws documentation carries “why, how, detailed evidence, and the full process”. When Taskdoc references formal rtws documentation, use a stable path/section name/relevant command instead of copying the full content
@@ -156,7 +156,7 @@ Taskdoc is a **task contract** and the task's **team-shared source of current tr
 ## Limitations and Notes
 
 1. `dialog` reminders end with the dialog; `personal` reminders stay visible in all later dialogs you lead
-2. Use `do_mind` to create missing Taskdoc sections; use `mind_more` for small Taskdoc additions; use `change_mind` for full-section replacement of existing sections and merge existing content first; use `never_mind` when a whole section file should be deleted. Do not treat `mind_more` as a chronology tool; when cleanup, stale-entry removal, or same-topic consolidation is needed, use `change_mind`
+2. Use `do_mind` to create missing Taskdoc sections; use `mind_more` for small Taskdoc additions; use `change_mind` for full-section replacement of existing sections only after merging existing content and calling `recall_taskdoc` for the current `content_hash`; use `never_mind` when a whole section file should be deleted. Do not treat `mind_more` as a chronology tool; when cleanup, stale-entry removal, or same-topic consolidation is needed, use `recall_taskdoc` then `change_mind`
 3. `do_mind` / `mind_more` / `change_mind` / `never_mind` do not start a new course
 4. A continuation-package reminder should keep only details still not covered by Taskdoc but easy to lose during resume; in the Main Dialog, undocumented discussion details from current dialog history that the next course needs to know should be written to the appropriate Taskdoc sections first; in a Side Dialog under caution/critical remediation, maintain sufficiently detailed continuation-package reminders only
 5. Do not turn `personal` reminders into a long-term fact dump; move durable knowledge into `personal_memory`

package/dist/tools/prompts/control/en/scenarios.md

@@ -130,10 +130,15 @@ mind_more({
 });
 
 // Full-section replacement when cleanup, reordering, same-topic consolidation, or chronology compression is needed
+recall_taskdoc({
+  selector: 'progress',
+});
+
 change_mind({
   selector: 'progress',
   content:
     '## Progress\n\n### Current Effective State\n- The memory-carrier boundary cleanup is complete; next we strengthen the Taskdoc bulletin-board semantics; details: <doc-path>#<section>\n\n### Decisions In Effect\n- `personal_memory` is no longer treated as a short-term junk drawer\n- `team_memory` now carries only long-lived team conventions and invariants\n\n### Next Step\n- Add stronger `progress` bulletin-board guidance in control / team_mgmt manuals\n\n### Still-Active Blockers\n- None',
+  previous_content_hash: 'crc32:...',
 });
 ```
 
@@ -146,10 +151,15 @@ Update task objectives.
 ### Example
 
 ```typescript
+recall_taskdoc({
+  selector: 'goals',
+});
+
 change_mind({
   selector: 'goals',
   content:
     '## Goals\n\n- [ ] Create all toolset manuals\n  - [x] ws_mod\n  - [x] team_mgmt\n  - [x] personal_memory\n  - [ ] control (In Progress)\n- [ ] Write tool descriptions',
+  previous_content_hash: 'crc32:...',
 });
 ```
 
@@ -162,10 +172,15 @@ Update task constraints.
 ### Example
 
 ```typescript
+recall_taskdoc({
+  selector: 'constraints',
+});
+
 change_mind({
   selector: 'constraints',
   content:
     '## Constraints\n\n- man function must dynamically filter toolsets based on team.yaml\n- Runtime effective: Changes to team.yaml immediately visible\n- Toolset names use underscore format\n- New constraint: Each toolset needs 5 topics × 2 languages',
+  previous_content_hash: 'crc32:...',
 });
 ```
 
@@ -178,6 +193,11 @@ Read taskdoc chapter content.
 ### Example
 
 ```typescript
+// Top-level sections are injected as content, but recall_taskdoc returns their content_hash
+recall_taskdoc({
+  selector: 'progress',
+});
+
 // Read bearinmind runbook
 recall_taskdoc({
   category: 'bearinmind',
@@ -201,9 +221,14 @@ Maintain taskdoc integrity and consistency, and keep `progress` as a team-scanna
 
 ```typescript
 // Update progress (keep goals / constraints / progress consistent)
+recall_taskdoc({
+  selector: 'progress',
+});
+
 change_mind({
   selector: 'progress',
   content:
     '## Progress\n\n### Current Effective State\n- The boundary wording has been propagated into handbook sources and tests; details: <doc-path>#<section>\n\n### Decisions In Effect\n- role assets / personal_memory / team_memory / Taskdoc-progress / reminders now have separated responsibilities\n\n### Next Step\n- Re-verify control manual wording, Taskdoc display text, and boundary tests\n\n### Still-Active Blockers\n- None',
+  previous_content_hash: 'crc32:...',
 });
 ```

package/dist/tools/prompts/control/en/tools.md

@@ -150,7 +150,7 @@ Create a new Taskdoc section. It fails if the target section already exists.
 
 - Create-only: it does not overwrite existing content
 - Use this for missing resident sections or new extra sections that preserve details without touching existing Taskdoc text
-- If the target already exists and only needs small additions, use `mind_more`; if it needs a full rewrite/merge, use `change_mind`
+- If the target already exists and only needs small additions, use `mind_more`; if it needs a full rewrite/merge, call `recall_taskdoc` first and then use `change_mind` with the returned `content_hash` as `previous_content_hash`
 - Does not start a new course
 - Changes visible to all teammates
 
@@ -163,6 +163,7 @@ Update taskdoc chapter.
 - `selector` (required): Chapter selector (goals/constraints/progress)
 - `category` (optional): Extra section directory; with `selector`, targets `<category>/<selector>.md`
 - `content` (required): New content (full section replacement)
+- `previous_content_hash` (required): The current section `content_hash` returned by `recall_taskdoc`
 
 **Returns:**
 
@@ -175,6 +176,7 @@ updated_at: <update timestamp>
 **Characteristics:**
 
 - Each call replaces an existing entire chapter; it does not create missing sections
+- The replacement is rejected if `previous_content_hash` does not match the current section content hash
 - Does not start a new course
 - Changes visible to all teammates
 - Constraint rule: `constraints` must include only task-specific hard requirements; do not repeat global rules. If a duplicate is found, delete it and inform the user
@@ -206,7 +208,7 @@ mind_more({
 - Append-only: it does not deduplicate, rewrite, or compress old content
 - Good for adding one or two still-effective states, decisions, next steps, or blockers to `progress`
 - Not for appending every investigation step, long log, full plan, or acceptance record as a chronology; those details belong in formal rtws documentation, while Taskdoc keeps the summary and document pointer
-- If stale entries must be removed, reordered, or compressed, use `change_mind` for a full-section replacement; if a whole section file should be deleted, use `never_mind`
+- If stale entries must be removed, reordered, or compressed, call `recall_taskdoc` first and then use `change_mind` with the returned `content_hash` as `previous_content_hash` for a full-section replacement; if a whole section file should be deleted, use `never_mind`
 - When one topic already has several phase notes, prefer `change_mind` to merge them into a concise current announcement instead of continuing to call `mind_more`
 
 ### 8. never_mind
@@ -221,7 +223,7 @@ Delete a Taskdoc section file.
 **Characteristics:**
 
 - Deletes only the whole section file; it does not edit content
-- Use it only when the whole section is no longer valid. If you only need to remove stale entries or compress structure, prefer `change_mind` with the cleaned full section
+- Use it only when the whole section is no longer valid. If you only need to remove stale entries or compress structure, prefer `recall_taskdoc` followed by `change_mind` with the cleaned full section and returned `content_hash` as `previous_content_hash`
 - Does not start a new course
 
 ### 9. recall_taskdoc
@@ -230,15 +232,16 @@ Read taskdoc chapter.
 
 **Parameters:**
 
-- `category` (required): Category directory
-- `selector` (required): Chapter selector
+- `selector` (required): Chapter selector. Omit `category` for top-level sections (`goals` / `constraints` / `progress`)
+- `category` (optional): Category directory. Use `bearinmind` for fixed bear-in-mind sections, or an extra section directory
 
 **Returns:**
 
 ```yaml
 status: ok|error
-category: <category>
 selector: <selector>
+category: <category, when supplied>
+content_hash: <crc32 checksum>
 content: <chapter content>
 retrieved_at: <retrieval timestamp>
 ```
@@ -305,16 +308,25 @@ mind_more({
 ### Replace Taskdoc Progress
 
 ```typescript
+recall_taskdoc({
+  selector: 'progress',
+});
+
 change_mind({
   selector: 'progress',
   content:
     '## Progress\n\n### Current Effective State\n- The handbook boundary split is now agreed: role assets / personal long-lived experience / Taskdoc-progress / reminders; details: <doc-path>#<section>\n\n### Decisions In Effect\n- `persona / knowhow / pitfalls` no longer absorb daily member experience\n- `personal_memory` is reserved for one member\\'s reusable long-lived experience\n\n### Next Step\n- Strengthen the bulletin-board semantics of Taskdoc `progress`\n\n### Still-Active Blockers\n- None',
+  previous_content_hash: 'crc32:...',
 });
 ```
 
 ### Read Taskdoc Chapter
 
 ```typescript
+recall_taskdoc({
+  selector: 'progress',
+});
+
 recall_taskdoc({
   category: 'bearinmind',
   selector: 'runbook',

package/dist/tools/prompts/control/zh/principles.md

@@ -132,8 +132,8 @@
 
 - 保持简洁：默认提醒项常见 1–3 条，优先 `update_reminder` 压缩/合并
 - 区分载体：需要向全队同步的当前有效状态、关键决策、下一步与仍成立阻塞，写入 `progress` 这一准实时任务公告牌；提醒项只留个人/当前对话恢复所需细节
-- 面向全队：`progress` 应保持可扫读、以“当前仍有效”为准，不要退化成个人日志、流水账、临时便签或历史残影堆积；少量新增用 `mind_more`，需要清旧/重排/压缩时用 `change_mind`
-- 按需整理：`mind_more` 不是默认记账动作。若同一主题已有多条阶段性记录，优先用 `change_mind` 合并成当前摘要；把细节放进 rtws 正式文档，并在差遣牒里保留文档定位 pointer
+- 面向全队：`progress` 应保持可扫读、以“当前仍有效”为准，不要退化成个人日志、流水账、临时便签或历史残影堆积；少量新增用 `mind_more`，需要清旧/重排/压缩时先调用 `recall_taskdoc`，再用 `change_mind` 并携带返回的 `content_hash` 作为 `previous_content_hash`
+- 按需整理：`mind_more` 不是默认记账动作。若同一主题已有多条阶段性记录，优先用 `change_mind` 合并成当前摘要；把细节放进 rtws 正式文档，并在差遣牒里保留文档定位 pointer。若会冲掉原有内容，必须有直接人类确认，或已按人类认可 SOP/验收标准充分考虑原有内容后再改写
 - 换程前收束：主线对话先把尚未落实到文档、且下一程需要知会的讨论细节写入差遣牒合适章节，再整理结构化接续包提醒项；支线对话不要维护差遣牒，也不要整理差遣牒更新提案，直接维护足够详尽的接续包提醒项。若系统已把当前程切到吃紧/告急处置态，则先保留多条粗略提醒项过桥也可以；当前程只做落文档/保信息 + `clear_mind`（支线只做保信息 + `clear_mind`），系统真正开启新一程后第一步再收敛
 - 拒绝原料堆积：不要把长日志/大段 tool output 直接塞进提醒项
 - 文档分层：差遣牒写“现在应如何同步/推进”，正式文档写“为什么、怎么做、详细证据和完整过程”。差遣牒需要引用正式文档时，写稳定路径/章节名/相关命令，而不是复制整段内容
@@ -156,7 +156,7 @@
 ## 限制与注意事项
 
 1. `dialog` 提醒会随对话结束而结束；`personal` 提醒会在所有由你主理的后续对话里继续可见
-2. 缺失差遣牒章节用 `do_mind` 创建；差遣牒少量新增可用 `mind_more` 追加；已有章节整段替换用 `change_mind`，请确保合并已有内容；确需删除整章文件时用 `never_mind`。不要把 `mind_more` 当流水账工具；需要整理、去旧、合并同主题记录时直接 `change_mind`
+2. 缺失差遣牒章节用 `do_mind` 创建；差遣牒少量新增可用 `mind_more` 追加；已有章节整段替换用 `change_mind`，请确保合并已有内容，并先调用 `recall_taskdoc` 取得当前 `content_hash` 作为 `previous_content_hash`；确需删除整章文件时用 `never_mind`。不要把 `mind_more` 当流水账工具；需要整理、去旧、合并同主题记录时先 `recall_taskdoc` 再 `change_mind`
 3. `do_mind` / `mind_more` / `change_mind` / `never_mind` 不开启新 course
 4. 接续包提醒项只保留差遣牒仍未覆盖、但恢复工作容易丢的细节；主线对话应先把当前对话历史中应由下一程知会的未落文档讨论细节写入差遣牒合适章节；支线对话在吃紧/告急时只维护足够详尽的接续包提醒项
 5. 不要把 `personal` 提醒堆成长期事实仓库；耐久知识应迁到 `personal_memory`

package/dist/tools/prompts/control/zh/scenarios.md

@@ -127,10 +127,15 @@ mind_more({
 });
 
 // 需要清理旧项、重排、同主题合并或压缩流水账时，整章替换
+recall_taskdoc({
+  selector: 'progress',
+});
+
 change_mind({
   selector: 'progress',
   content:
     '## Progress\n\n### 当前有效状态\n- 已完成三类记忆载体边界收口，准备补 Taskdoc 公告牌属性；细节见 <文档路径>#<章节>\n\n### 已生效决策\n- `personal_memory` 不再作为短期杂物柜\n- `team_memory` 只承接团队长期共识与不变量\n\n### 下一步\n- 在 control / team_mgmt 手册中补强 `progress` 的公告牌语义\n\n### 仍成立阻塞\n- 无',
+  previous_content_hash: 'crc32:...',
 });
 ```
 
@@ -143,10 +148,15 @@ change_mind({
 ### 示例
 
 ```typescript
+recall_taskdoc({
+  selector: 'goals',
+});
+
 change_mind({
   selector: 'goals',
   content:
     '## Goals\n\n- [ ] 创建所有工具集手册\n  - [x] ws_mod\n  - [x] team_mgmt\n  - [x] personal_memory\n  - [ ] control (进行中)\n- [ ] 编写工具描述',
+  previous_content_hash: 'crc32:...',
 });
 ```
 
@@ -159,10 +169,15 @@ change_mind({
 ### 示例
 
 ```typescript
+recall_taskdoc({
+  selector: 'constraints',
+});
+
 change_mind({
   selector: 'constraints',
   content:
     '## Constraints\n\n- man 函数必须根据 team.yaml 动态过滤工具集\n- 运行时生效：team.yaml 配置变更后立即可见\n- 工具集名称使用下划线格式\n- 新增约束：每个工具集需要 5 个 topic × 2 个语言',
+  previous_content_hash: 'crc32:...',
 });
 ```
 
@@ -175,6 +190,11 @@ change_mind({
 ### 示例
 
 ```typescript
+// 顶层章节正文会自动注入，但 content_hash 由 recall_taskdoc 返回
+recall_taskdoc({
+  selector: 'progress',
+});
+
 // 读取 bearinmind/runbook
 recall_taskdoc({
   category: 'bearinmind',
@@ -198,9 +218,14 @@ recall_taskdoc({
 
 ```typescript
 // 更新 progress（保持 goals / constraints / progress 一致）
+recall_taskdoc({
+  selector: 'progress',
+});
+
 change_mind({
   selector: 'progress',
   content:
     '## Progress\n\n### 当前有效状态\n- 边界口径已统一到手册源头与测试；细节见 <文档路径>#<章节>\n\n### 已生效决策\n- 角色级资产 / personal_memory / team_memory / Taskdoc-progress / reminders 的职责已经切开\n\n### 下一步\n- 复验 control 手册、Taskdoc 展示文案与边界测试\n\n### 仍成立阻塞\n- 无',
+  previous_content_hash: 'crc32:...',
 });
 ```

package/dist/tools/prompts/control/zh/tools.md

@@ -150,7 +150,7 @@ status: ok|error
 
 - 只创建，不覆盖已有内容
 - 适合创建缺失的常驻章节，或新增额外章节来保留细节，同时不触碰已有差遣牒正文
-- 若目标已存在且只需少量补充，用 `mind_more`；若需要整章改写/合并，用 `change_mind`
+- 若目标已存在且只需少量补充，用 `mind_more`；若需要整章改写/合并，先调用 `recall_taskdoc`，再用 `change_mind` 并带上返回的 `content_hash` 作为 `previous_content_hash`
 - 不开启新 course
 - 变更对所有队友可见
 
@@ -163,6 +163,7 @@ status: ok|error
 - `selector`（必需）：章节选择器（goals/constraints/progress）
 - `category`（可选）：额外章节目录；与 `selector` 组合定位 `<category>/<selector>.md`
 - `content`（必需）：新内容（整段替换）
+- `previous_content_hash`（必需）：`recall_taskdoc` 返回的当前章节 `content_hash`
 
 **返回：**
 
@@ -175,6 +176,7 @@ updated_at: <更新时间戳>
 **特点：**
 
 - 每次调用替换已有的整个章节；不会创建缺失章节
+- 若 `previous_content_hash` 与当前章节内容哈希不匹配，替换会被拒绝
 - 不开启新 course
 - 变更对所有队友可见
 - 约束规则：`constraints` 只写任务特有硬要求，不得重复系统提示/工具文档中的全局规则；一经发现重复，必须删除并告知用户
@@ -203,7 +205,7 @@ mind_more({
 - 只追加，不会自动去重、改写或压缩旧内容
 - 适合给 `progress` 补一两条当前仍有效的状态、决策、下一步或阻塞
 - 不适合把每一步调查过程、长日志、完整方案或验收记录当流水账追加进去；这些细节应写入 rtws 正式文档，差遣牒只写摘要和文档定位 pointer
-- 若需要删除陈旧项、重排结构或压缩公告牌，仍使用 `change_mind` 做整章替换；若要删除整个章节文件，使用 `never_mind`
+- 若需要删除陈旧项、重排结构或压缩公告牌，先调用 `recall_taskdoc`，再使用带返回 `content_hash` 作为 `previous_content_hash` 的 `change_mind` 做整章替换；若要删除整个章节文件，使用 `never_mind`
 - 当同一主题已经有多条阶段记录时，优先 `change_mind` 合并成当前仍有效的简明公告，而不是继续 `mind_more`
 
 ### 8. never_mind
@@ -218,7 +220,7 @@ mind_more({
 **特点：**
 
 - 只删除整章文件，不做内容编辑
-- 仅用于章节整体不再成立；如果只是删除几条陈旧项或压缩结构，优先用 `change_mind` 写回整理后的全文
+- 仅用于章节整体不再成立；如果只是删除几条陈旧项或压缩结构，优先先 `recall_taskdoc`，再用带返回 `content_hash` 作为 `previous_content_hash` 的 `change_mind` 写回整理后的全文
 - 不开启新 course
 
 ### 9. recall_taskdoc
@@ -227,15 +229,16 @@ mind_more({
 
 **参数：**
 
-- `category`（必需）：类别目录
-- `selector`（必需）：章节选择器
+- `selector`（必需）：章节选择器。顶层章节（`goals` / `constraints` / `progress`）省略 `category`
+- `category`（可选）：类别目录。固定 bear-in-mind 章节使用 `bearinmind`，其他额外章节使用对应目录
 
 **返回：**
 
 ```yaml
 status: ok|error
-category: <类别>
 selector: <选择器>
+category: <传入 category 时返回>
+content_hash: <crc32 校验值>
 content: <章节内容>
 retrieved_at: <读取时间戳>
 ```
@@ -298,16 +301,25 @@ mind_more({
 ### 整章替换差遣牒进度
 
 ```typescript
+recall_taskdoc({
+  selector: 'progress',
+});
+
 change_mind({
   selector: 'progress',
   content:
     '## Progress\n\n### 当前有效状态\n- 手册边界方案已确定：角色级资产 / 个人长期经验 / Taskdoc-progress / reminders 分流；细节见 <文档路径>#<章节>\n\n### 已生效决策\n- `persona / knowhow / pitfalls` 不承接成员日常经验\n- `personal_memory` 只承接成员自己的长期可复用经验\n\n### 下一步\n- 补齐 Taskdoc `progress` 的公告牌属性说明\n\n### 仍成立阻塞\n- 无',
+  previous_content_hash: 'crc32:...',
 });
 ```
 
 ### 读取差遣牒章节
 
 ```typescript
+recall_taskdoc({
+  selector: 'progress',
+});
+
 recall_taskdoc({
   category: 'bearinmind',
   selector: 'runbook',

package/dist/tools/team_mgmt-manual.js

@@ -114,7 +114,7 @@ async function renderTeamMgmtGuideContent(language, topicsRaw = []) {
                     '`model_param_options` 可选：用于记录该 provider 支持的 `.minds/team.yaml model_params` 选项（文档用途）。',
                     '`apiQuirks` 可选：写在 `providers.<providerKey>.apiQuirks`，类型是 `string|string[]`；需要多个 quirk 时用数组，例如 `apiQuirks: [same-context-empty-response]`。它是 provider 级 transport / 网关兼容开关，用来描述“这个供应商/网关的 API 有非标准行为”，不是 `.minds/team.yaml` 的成员参数，也不是 `model_params`。',
                     '使用原则：只有在你确认某个上游网关确实偏离了标准协议，而且 Dominds 已为这个偏差实现了命名 quirk 时才配置；不要把它当作随意调参入口。当前实现里，未知 quirk 值通常不会报错，但也不会带来任何效果。',
-                    '当前已知示例：OpenAI Responses 包装层支持 `apiQuirks: xcode.best`（或数组里包含它），用于识别 vendor keepalive、处理 xcode.best 特有的失败模式，以及把网关返回的 HTML 版 502 Bad Gateway 错误页和 `500 auth_unavailable: no auth available` 这类基础设施失败归类为 conservative 策略重试。OpenAI-compatible Chat Completions 包装层支持 `apiQuirks: same-context-empty-response`，用于“同一对话 generation 上下文连续返回 empty response”时先做少量临时重试；如果在同一 generation 上下文里连续达到阈值，就判定为 provider 侧 same-context deadlock，并停止继续沿用同一上下文自动重试。最小示例：\n```yaml\nproviders:\n  my_gateway:\n    apiType: openai-compatible\n    baseUrl: https://example.invalid/v1\n    apiKeyEnvVar: MY_GATEWAY_API_KEY\n    apiQuirks: same-context-empty-response\n    models:\n      my_model: { name: "upstream-model-id" }\n```',
+                    '当前已知示例：OpenAI Responses 包装层支持 `apiQuirks: xcode.best`（或数组里包含它），用于识别 vendor keepalive、处理 xcode.best 特有的失败模式，以及把网关返回的 HTML 版 502 Bad Gateway 错误页和 `500 auth_unavailable: no auth available` 这类基础设施失败归类为 conservative 策略重试。OpenAI-compatible Chat Completions 包装层支持 `apiQuirks: same-context-empty-response`，用于“同一对话 generation 上下文连续返回 empty response”时先做少量临时重试；也支持内置 `kimi-code` provider 使用的 `apiQuirks: kimi-code`，用于 Kimi Code 专用 User-Agent、`prompt_cache_key` 和 `thinking`/`reasoning_effort` 请求整形。最小示例：\n```yaml\nproviders:\n  my_gateway:\n    apiType: openai-compatible\n    baseUrl: https://example.invalid/v1\n    apiKeyEnvVar: MY_GATEWAY_API_KEY\n    apiQuirks: same-context-empty-response\n    models:\n      my_model: { name: "upstream-model-id" }\n```',
                     '边界提醒：`apiQuirks` 只影响实现里显式消费它的 provider/generator。就当前实现看，OpenAI Responses 与 OpenAI-compatible 路径会读取它；不要假设所有 `apiType` 都支持或需要它。若配置后行为仍异常，应继续检查上游网关文档、抓流事件类型，并结合 `team_mgmt_check_provider(...)` / 运行日志排查。',
                 ])
             : fmtHeader('.minds/llm.yaml') +
@@ -128,7 +128,7 @@ async function renderTeamMgmtGuideContent(language, topicsRaw = []) {
                     'Optional: `model_param_options` documents `.minds/team.yaml model_params` knobs (documentation only).',
                     '`apiQuirks` is optional under `providers.<providerKey>.apiQuirks`, with type `string|string[]`; use an array for multiple quirks, for example `apiQuirks: [same-context-empty-response]`. It is a provider-level transport / gateway compatibility switch for non-standard upstream API behavior. It is not a `.minds/team.yaml` member field and not part of `model_params`.',
                     'Use it only when you have confirmed that an upstream gateway deviates from the expected protocol and Dominds has an explicitly named quirk for that deviation. Do not treat it as a generic tuning field. In the current implementation, unknown quirk values are usually ignored rather than rejected, so a typo may silently do nothing.',
-                    'Known current example: the OpenAI Responses wrapper supports `apiQuirks: xcode.best` (or an array containing it) for vendor keepalive recognition, xcode.best-specific failures, and gateway-returned HTML 502 Bad Gateway plus `500 auth_unavailable: no auth available` infrastructure failures. The OpenAI-compatible Chat Completions wrapper supports `apiQuirks: same-context-empty-response` for repeated empty responses in the same dialog generation context: it tries a short burst first, then treats the streak as a provider-side same-context deadlock and stops repeating the same automatic retry path. Minimal example:\n```yaml\nproviders:\n  my_gateway:\n    apiType: openai-compatible\n    baseUrl: https://example.invalid/v1\n    apiKeyEnvVar: MY_GATEWAY_API_KEY\n    apiQuirks: same-context-empty-response\n    models:\n      my_model: { name: "upstream-model-id" }\n```',
+                    'Known current example: the OpenAI Responses wrapper supports `apiQuirks: xcode.best` (or an array containing it) for vendor keepalive recognition, xcode.best-specific failures, and gateway-returned HTML 502 Bad Gateway plus `500 auth_unavailable: no auth available` infrastructure failures. The OpenAI-compatible Chat Completions wrapper supports `apiQuirks: same-context-empty-response` for repeated empty responses in the same dialog generation context, and `apiQuirks: kimi-code` for the built-in Kimi Code provider request shaping: Dominds User-Agent, `prompt_cache_key`, and `thinking`/`reasoning_effort`. Minimal example:\n```yaml\nproviders:\n  my_gateway:\n    apiType: openai-compatible\n    baseUrl: https://example.invalid/v1\n    apiKeyEnvVar: MY_GATEWAY_API_KEY\n    apiQuirks: same-context-empty-response\n    models:\n      my_model: { name: "upstream-model-id" }\n```',
                     'Boundary reminder: `apiQuirks` only affects providers/generators that explicitly read it in code. In the current implementation, the OpenAI Responses and OpenAI-compatible paths consume it; do not assume every `apiType` supports or needs it. If behavior is still wrong after setting it, continue with upstream gateway docs, raw stream event inspection, and `team_mgmt_check_provider(...)` / runtime logs.',
                 ]);
     }