@goodandready/dsh-goal 0.1.1 → 0.1.3

package/README.md

@@ -1,47 +1,143 @@
-# @goodandready/dsh-goal
+# 📦 @goodandready/dsh-goal
 
-> **Goal Mode & Autonomous Execution Plugin for DeepSeek Harness (DSH)**
+<div align="center">
 
-`dsh-goal` adds an autonomous goal-tracking loop with a sticky top status banner, milestone decomposition, live timer, and interactive controls (pause, resume, cancel, modal details).
+<h3>Autonomous Goal Execution & Multi-Turn Task Tracking Engine with Sticky Header for DeepSeek Harness</h3>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@goodandready/dsh-goal"><img src="https://img.shields.io/npm/v/@goodandready/dsh-goal.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/GooDAnDReaDY/dsh-goal.svg?style=for-the-badge&color=10b981&labelColor=064e3b" alt="license"></a>
+  <a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065" alt="DSH Plugin"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03" alt="Node version"></a>
+</p>
+
+<!-- Author Showcase Link -->
+<p align="center">
+  <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/All_Author_Projects-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="GoodAndReady Showcase"></a>
+</p>
+
+<p align="center">
+  <a href="README.md"><b>🇬🇧 English</b></a> •
+  <a href="docs/README.ru.md"><b>🇷🇺 Русский</b></a> •
+  <a href="docs/README.zh.md"><b>🇨🇳 中文说明</b></a>
+</p>
+
+</div>
+
+---
+
+## ⚡ Overview & The Problem
+
+Complex engineering tasks require multi-step autonomy: decomposing high-level objectives into milestones, executing successive iterations without manual user re-prompting, and maintaining clear visibility into task progress.
+
+**`@goodandready/dsh-goal`** brings autonomous goal execution to DeepSeek Harness via the `/goal` command:
+* 🎯 **Sticky Top Goal Banner**: Pinned status header with live timer (`• 2s`, `• 1m 45s`), active goal title, and interactive control buttons.
+* ⏸️ **Play / Pause / Cancel**: Instantly pause the autonomous loop or resume execution on demand.
+* 📋 **Milestone Breakdown Drawer**: Interactive checklist showing sub-tasks, percentage completion, and iteration logs.
+* 🤖 **Autonomous Agent Tools**: Provides `goal_set_milestones`, `goal_update_progress`, and `goal_finish` tools directly to the agent.
+* 🛡️ **Safety Guardrails**: Configurable `maxIterations` limit to prevent runaway loops.
+
+---
+
+## 🏛️ Architecture
+
+```mermaid
+graph TD
+    subgraph Input ["User Interaction"]
+        Cmd["Slash Command: /goal &lt;objective&gt;"]
+        API["REST API: POST /dsh-goal/action"]
+    end
+
+    subgraph GoalEngine ["Goal Lifecycle Engine (lib/index.js)"]
+        State["State Manager (IDLE, RUNNING, PAUSED, COMPLETED)"]
+        Milestones["Milestone Tracker & Decomposition"]
+        Disk["Persistence Store (~/.dsh/goal-state.json)"]
+    end
+
+    subgraph AgentLoop ["Autonomous Agent Drive"]
+        ToolSet["goal_set_milestones"]
+        ToolProgress["goal_update_progress"]
+        ToolFinish["goal_finish"]
+        LimitGuard{"maxIterations Guard"}
+    end
+
+    subgraph UI ["DSH Web Interface"]
+        Banner["Sticky Top Goal Banner"]
+        Timer["Live Elapsed Timer"]
+        Drawer["Milestone Checklist Modal"]
+        Settings["Settings Card (Schemastery)"]
+    end
+
+    Cmd --> GoalEngine
+    API --> GoalEngine
+    GoalEngine --> State
+    State --> Disk
+    State --> Banner
+    State --> Drawer
+    GoalEngine --> AgentLoop
+    AgentLoop --> LimitGuard
+    ToolSet --> GoalEngine
+    ToolProgress --> GoalEngine
+    ToolFinish --> GoalEngine
+```
 
 ---
 
-## Features
+## 📦 Installation
 
-- 🎯 **Sticky Top Goal Banner**: Minimalist header pinned above the chat showing the active goal, elapsed timer (`• 2s`, `• 1m 45s`), and controls.
-- ⏸️ **Play / Pause / Cancel**: Instantly halt autonomous multi-turn loops or resume whenever ready.
-- ⛶ **Milestone Modal Drawer**: Interactive checklist of sub-tasks with progress bar and execution logs.
-- 🤖 **Agent Tools**:
-  - `goal_set_milestones`: Autonomous breakdown of high-level goals into step-by-step tasks.
-  - `goal_update_progress`: Step-by-step milestone completion tracking.
-  - `goal_finish`: Goal completion with deliverable summary.
-- ⚙️ **Safety Limit & Settings**: Max iterations guardrail to prevent infinite agent loops.
-- 🌐 **Bilingual**: Full English and Russian localization.
+```bash
+dsh plugin --profile web add @goodandready/dsh-goal
+```
+
+Restart your DeepSeek Harness instance and refresh the browser.
 
 ---
 
-## Installation
+## 💬 Usage & Quick Start
+
+Start a goal directly in chat:
+
+```text
+/goal Refactor the authentication middleware and add integration tests
+```
+
+Or trigger via REST API:
 
 ```bash
-dsh plugin add @goodandready/dsh-goal
+curl -X POST http://localhost:3080/dsh-goal/action \
+  -H "Content-Type: application/json" \
+  -d '{"action":"start","title":"Optimize database queries"}'
+```
+
+---
+
+## ⚙️ Configuration Reference (`settings.yaml`)
+
+```yaml
+dsh-goal:
+  maxIterations: 25
+  autoDrive: true
+  enableSound: true
 ```
 
-## Quick Start
+| Parameter | Type | Default | Description |
+|:---|:---|:---|:---|
+| `maxIterations` | `number` | `25` | Safety limit: maximum autonomous iterations per goal |
+| `autoDrive` | `boolean` | `true` | Keep the autonomous agent loop running between turns |
+| `enableSound` | `boolean` | `true` | Play completion audio chime when a goal finishes |
+
+---
 
-1. Start a goal in chat:
-   ```text
-   /goal Refactor auth tokens and write integration tests
-   ```
-2. Or use the REST API:
-   ```bash
-   curl -X POST http://localhost:3080/dsh-goal/action \
-     -H "Content-Type: application/json" \
-     -d '{"action":"start","title":"Optimize database queries"}'
-   ```
-3. Watch the sticky top banner update with live timer and milestones in real-time.
+## 🧪 Testing
+
+Run the automated test suite:
+
+```bash
+npm test
+```
 
 ---
 
-## License
+## 📄 License
 
-MIT © [goodandready](https://goodandready.app)
+MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)

package/docs/README.ru.md

@@ -0,0 +1,143 @@
+# 📦 @goodandready/dsh-goal
+
+<div align="center">
+
+<h3>Движок автономного выполнения целей и многошагового трекинга задач для DeepSeek Harness</h3>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@goodandready/dsh-goal"><img src="https://img.shields.io/npm/v/@goodandready/dsh-goal.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>
+  <a href="../LICENSE"><img src="https://img.shields.io/github/license/GooDAnDReaDY/dsh-goal.svg?style=for-the-badge&color=10b981&labelColor=064e3b" alt="license"></a>
+  <a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065" alt="DSH Plugin"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03" alt="Node version"></a>
+</p>
+
+<!-- Обязательная кнопка перехода на витрину всех проектов -->
+<p align="center">
+  <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/Все_проекты_автора-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="Все проекты автора"></a>
+</p>
+
+<p align="center">
+  <a href="../README.md"><b>🇬🇧 English</b></a> •
+  <a href="README.ru.md"><b>🇷🇺 Русский</b></a> •
+  <a href="README.zh.md"><b>🇨🇳 中文说明</b></a>
+</p>
+
+</div>
+
+---
+
+## ⚡ Обзор и решаемая проблема
+
+Решение комплексных инженерных задач требует автономного многошагового выполнения: декомпозиции целей на майлстоуны, непрерывного выполнения итераций без ручного подталкивания пользователя и наглядного отслеживания прогресса.
+
+**`@goodandready/dsh-goal`** внедряет автономный режим достижения целей в DeepSeek Harness через команду `/goal`:
+* 🎯 **Плавающий баннер в шапке**: зафиксированный статус-бар над чатом с таймером выполнения (`• 2s`, `• 1m 45s`), заголовком цели и кнопками управления.
+* ⏸️ **Управление циклом (Play / Pause / Cancel)**: мгновенная приостановка автономного цикла агента или его возобновление в любой момент.
+* 📋 **Интерактивная панель майлстоунов**: модальное окно со списком подзадач, прогресс-баром и журналом выполнения.
+* 🤖 **Инструменты агента**: `goal_set_milestones`, `goal_update_progress` и `goal_finish` для самостоятельной работы ИИ.
+* 🛡️ **Защитные лимиты**: настраиваемое ограничение `maxIterations` для предотвращения бесконечных циклов.
+
+---
+
+## 🏛️ Архитектура
+
+```mermaid
+graph TD
+    subgraph Input ["Взаимодействие"]
+        Cmd["Слеш-команда: /goal &lt;цель&gt;"]
+        API["REST API: POST /dsh-goal/action"]
+    end
+
+    subgraph GoalEngine ["Движок целей (lib/index.js)"]
+        State["Менеджер состояний (IDLE, RUNNING, PAUSED, COMPLETED)"]
+        Milestones["Трекер и декомпозиция майлстоунов"]
+        Disk["Хранилище состояний (~/.dsh/goal-state.json)"]
+    end
+
+    subgraph AgentLoop ["Автономный цикл агента"]
+        ToolSet["goal_set_milestones"]
+        ToolProgress["goal_update_progress"]
+        ToolFinish["goal_finish"]
+        LimitGuard{"Ограничение maxIterations"}
+    end
+
+    subgraph UI ["Интерфейс DSH"]
+        Banner["Баннер цели над чатом"]
+        Timer["Таймер выполнения"]
+        Drawer["Модальное окно задач"]
+        Settings["Карточка настроек (Schemastery)"]
+    end
+
+    Cmd --> GoalEngine
+    API --> GoalEngine
+    GoalEngine --> State
+    State --> Disk
+    State --> Banner
+    State --> Drawer
+    GoalEngine --> AgentLoop
+    AgentLoop --> LimitGuard
+    ToolSet --> GoalEngine
+    ToolProgress --> GoalEngine
+    ToolFinish --> GoalEngine
+```
+
+---
+
+## 📦 Установка
+
+```bash
+dsh plugin --profile web add @goodandready/dsh-goal
+```
+
+Перезапустите экземпляр DeepSeek Harness и обновите вкладку в браузере.
+
+---
+
+## 💬 Быстрый старт
+
+Запустите цель прямо в чате:
+
+```text
+/goal Провести рефакторинг middleware авторизации и написать интеграционные тесты
+```
+
+Или через REST API:
+
+```bash
+curl -X POST http://localhost:3080/dsh-goal/action \
+  -H "Content-Type: application/json" \
+  -d '{"action":"start","title":"Оптимизация SQL-запросов"}'
+```
+
+---
+
+## ⚙️ Таблица конфигурации (`settings.yaml`)
+
+```yaml
+dsh-goal:
+  maxIterations: 25
+  autoDrive: true
+  enableSound: true
+```
+
+| Параметр | Тип | По умолчанию | Описание |
+|:---|:---|:---|:---|
+| `maxIterations` | `number` | `25` | Защитный лимит: максимум автономных итераций на цель |
+| `autoDrive` | `boolean` | `true` | Автоматически продолжать автономный цикл между тактами |
+| `enableSound` | `boolean` | `true` | Звуковое уведомление при успешном завершении цели |
+
+---
+
+## 🧪 Тестирование
+
+Запуск набора юнит-тестов:
+
+```bash
+npm test
+```
+
+---
+
+## 📄 Лицензия
+
+MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)

package/docs/README.zh.md

@@ -0,0 +1,143 @@
+# 📦 @goodandready/dsh-goal
+
+<div align="center">
+
+<h3>面向 DeepSeek Harness 的自主目标执行、任务里程碑分解与顶部常驻状态条引擎</h3>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@goodandready/dsh-goal"><img src="https://img.shields.io/npm/v/@goodandready/dsh-goal.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>
+  <a href="../LICENSE"><img src="https://img.shields.io/github/license/GooDAnDReaDY/dsh-goal.svg?style=for-the-badge&color=10b981&labelColor=064e3b" alt="license"></a>
+  <a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065" alt="DSH Plugin"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03" alt="Node version"></a>
+</p>
+
+<!-- 作者所有项目展示页面链接 -->
+<p align="center">
+  <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/作者所有开源项目-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="所有项目"></a>
+</p>
+
+<p align="center">
+  <a href="../README.md"><b>🇬🇧 English</b></a> •
+  <a href="README.ru.md"><b>🇷🇺 Русский</b></a> •
+  <a href="README.zh.md"><b>🇨🇳 中文说明</b></a>
+</p>
+
+</div>
+
+---
+
+## ⚡ 概述与核心解决痛点
+
+复杂的软件工程任务往往需要多步骤的自主循环：将宏观目标分解为里程碑子任务、多轮自动连续推进而无需用户反复手动下发指令，以及对执行过程保持清晰的可视化监控。
+
+**`@goodandready/dsh-goal`** 通过 `/goal` 指令为 DeepSeek Harness 带来原生的目标自主执行系统：
+* 🎯 **顶部常驻状态条**：固定在聊天窗口顶部的状态横幅，显示实时运行计时器（`• 2s`, `• 1m 45s`）、当前目标标题与控制按钮。
+* ⏸️ **自主循环控制 (Play / Pause / Cancel)**：可随时暂停智能体自主多轮循环，或根据需要一键恢复。
+* 📋 **里程碑任务抽屉**：交互式子任务清单，展示完成百分比进度条与执行日志。
+* 🤖 **智能体原生工具**：提供 `goal_set_milestones`, `goal_update_progress`, `goal_finish` 工具。
+* 🛡️ **安全防护机制**：支持配置 `maxIterations` 最大循环轮次，杜绝死循环消耗。
+
+---
+
+## 🏛️ 架构设计
+
+```mermaid
+graph TD
+    subgraph Input ["用户交互与输入"]
+        Cmd["聊天斜杠指令: /goal &lt;目标描述&gt;"]
+        API["REST API 路由: POST /dsh-goal/action"]
+    end
+
+    subgraph GoalEngine ["目标生命周期引擎 (lib/index.js)"]
+        State["状态机 (IDLE, RUNNING, PAUSED, COMPLETED)"]
+        Milestones["里程碑分解与进度追踪器"]
+        Disk["状态持久化存储 (~/.dsh/goal-state.json)"]
+    end
+
+    subgraph AgentLoop ["智能体自主执行驱动"]
+        ToolSet["goal_set_milestones"]
+        ToolProgress["goal_update_progress"]
+        ToolFinish["goal_finish"]
+        LimitGuard{"maxIterations 熔断防护"}
+    end
+
+    subgraph UI ["DSH Web 前端界面"]
+        Banner["顶部常驻状态横幅"]
+        Timer["实时执行计时器"]
+        Drawer["里程碑清单详情模态框"]
+        Settings["设置面板卡片 (Schemastery)"]
+    end
+
+    Cmd --> GoalEngine
+    API --> GoalEngine
+    GoalEngine --> State
+    State --> Disk
+    State --> Banner
+    State --> Drawer
+    GoalEngine --> AgentLoop
+    AgentLoop --> LimitGuard
+    ToolSet --> GoalEngine
+    ToolProgress --> GoalEngine
+    ToolFinish --> GoalEngine
+```
+
+---
+
+## 📦 快速安装
+
+```bash
+dsh plugin --profile web add @goodandready/dsh-goal
+```
+
+重启 DeepSeek Harness 实例并刷新浏览器页面。
+
+---
+
+## 💬 快速上手
+
+在聊天框中直接启动自主目标：
+
+```text
+/goal 重构身份验证中间件并编写端到端集成测试
+```
+
+或通过 REST 接口调用：
+
+```bash
+curl -X POST http://localhost:3080/dsh-goal/action \
+  -H "Content-Type: application/json" \
+  -d '{"action":"start","title":"优化数据库查询性能"}'
+```
+
+---
+
+## ⚙️ 配置参数参考 (`settings.yaml`)
+
+```yaml
+dsh-goal:
+  maxIterations: 25
+  autoDrive: true
+  enableSound: true
+```
+
+| 参数项 | 类型 | 默认值 | 说明 |
+|:---|:---|:---|:---|
+| `maxIterations` | `number` | `25` | 安全熔断阈值：单目标允许的最大自主轮次 |
+| `autoDrive` | `boolean` | `true` | 是否在轮次结束后自动驱动智能体继续推进 |
+| `enableSound` | `boolean` | `true` | 目标完成时是否播放提示音效 |
+
+---
+
+## 🧪 自动化测试
+
+运行自动化测试套件：
+
+```bash
+npm test
+```
+
+---
+
+## 📄 许可证
+
+MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)

package/docs/design/DESIGN.md

@@ -30,12 +30,14 @@
 - **Футер**: Кнопки ручного добавления шага, паузы и закрытия.
 
 ### 2.3 Settings Card (`settings.plugin.item`)
-- Размещение во вкладке «Настройки → Плагины».
-- Параметры:
+- Размещение во вкладке «Настройки → Плагины → Настройки плагинов», свёрнута по умолчанию, раскрытие по клику по заголовку (`aria-expanded`).
+- Ключ слота (`key`) — пространство настроек `dsh-goal`; пока снимок пространства не в статусе `ready`, карточка не рисуется; при `writable: false` поля и кнопки заблокированы.
+- Параметры (фактический набор, регистрируется schemastery-схемой):
   - `maxIterations`: максимальное число автономных шагов до принудительной остановки (дефолт: 25);
-  - `autoDrive`: автоматически вызывать следующий шаг модели (дефолт: true);
-  - `enableSound`: звуковой сигнал по завершении цели (дефолт: true);
-  - `promptTemplate`: шаблон системного инжекта в контекст модели.
+  - `autoDrive`: автоматически продолжать цикл после каждого хода (дефолт: true);
+  - `enableSound`: звуковой сигнал по завершении цели (дефолт: true).
+- Поля читаются из живого снимка пространства (`ctx.settingsScope.bind({ namespace })`), кнопки «Сбросить» / «Сохранить» в футере; сохраняются только изменённые поля, все записи выполняются подряд (не до первой ошибки), результат сверяется обратным чтением; неудачная запись не стирает введённые значения.
+- `Changed in ядро 0.1.2-rc.1`: поле `promptTemplate` никогда не было реализовано в коде и из схемы удалено из описания; контракт карточки переехал на встроенные службы ядра (`slots` / `locale` / `settingsScope`), `dsh.client.inject` пуст.
 
 ---
 
@@ -70,3 +72,5 @@
 1. **Единый префикс классов**: `.dsh-goal-*` во всех CSS-правилах во избежание конфликтов стилей.
 2. **Точный макет баннера**: скругление углов 8–10px, шапка с отступами `8px 16px`, выравнивание по центру, кнопки действий справа с `gap: 10px`.
 3. **Безопасность импортов**: все `require('@deepseek-ai/dsh-client-ui-primitives')` обёрнуты в `try/catch` с SVG-фоллбеками.
+4. **2026-09-04 — rc.1-совместимость клиента**: `dsh.client.inject: []` — в boot-графе клиента ядра 0.1.2-rc.1 нет package-строк `dsh-client-runtime` (модуля в ядре нет вовсе) и `dsh-client-ui-slots`; `slots`/`locale`/`settingsScope` — встроенные службы ядра. `react`, `@deepseek-ai/dsh-client-ui-slots`, `@deepseek-ai/dsh-client-ui-primitives` отвечаются статической seed-таблицей шелла, но динамических package-строк под них в boot-графе нет — объявлять их в inject нельзя. Условие пересмотра: появление этих package-строк в boot-таблице ядра.
+5. **2026-09-04 — контракт карточки настроек**: key слота = пространство настроек (`dsh-goal`), чтение через `ctx.settingsScope.bind`, решение по статусу снимка (loading/unavailable/ready + writable), сохранение всех изменённых полей с обратной сверкой. Причина: контракт вкладки «Настройки → Плагины» ядра rc.1 (BashCard/AgentLoopCard как эталон). Пересмотр — при изменении контракта слота в ядре.

package/lib/card-form-state.js

@@ -0,0 +1,110 @@
+/**
+ * Чистая логика состояния и валидации формы настроек dsh-goal.
+ * Не зависит от DOM/React, полностью тестируема через node --test.
+ */
+
+export const DEFAULT_SETTINGS = {
+  maxIterations: 25,
+  autoDrive: true,
+  enableSound: true,
+};
+
+/**
+ * Парсинг числового значения настроек:
+ * - пустая строка / null / undefined -> undefined (сброс к базовому значению)
+ * - валидное число >= 1 -> number
+ * - иначе -> NaN (invalid)
+ */
+export function parseNumberField(raw) {
+  if (raw === '' || raw === null || raw === undefined) {
+    return undefined;
+  }
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 1 || !Number.isInteger(n)) {
+    return NaN;
+  }
+  return n;
+}
+
+/**
+ * Вычисление состояния конкретного поля:
+ * @param {string} field
+ * @param {any} draftValue
+ * @param {Object} snap - { value, base, user }
+ */
+export function getFieldStatus(field, draftValue, snap) {
+  const baseVal = snap?.base?.[field] ?? DEFAULT_SETTINGS[field];
+  const userVal = snap?.user?.[field];
+  const effectiveVal = snap?.value?.[field] ?? baseVal;
+
+  const isOverridden = userVal !== undefined && userVal !== null;
+  const currentVal = draftValue !== undefined ? draftValue : effectiveVal;
+
+  let invalid = false;
+  let isDirty = false;
+
+  if (field === 'maxIterations') {
+    if (draftValue !== undefined) {
+      if (draftValue === '') {
+        // Пустая строка = сброс к базовому значению (не ошибка)
+        invalid = false;
+        isDirty = userVal !== undefined; // dirty если было переопределено
+      } else {
+        const parsed = parseNumberField(draftValue);
+        if (Number.isNaN(parsed)) {
+          invalid = true;
+          isDirty = true;
+        } else {
+          isDirty = parsed !== (userVal !== undefined ? userVal : baseVal);
+        }
+      }
+    }
+  } else {
+    // boolean fields (autoDrive, enableSound)
+    if (draftValue !== undefined) {
+      isDirty = draftValue !== (userVal !== undefined ? userVal : baseVal);
+    }
+  }
+
+  return {
+    value: currentVal,
+    baseValue: baseVal,
+    userValue: userVal,
+    isOverridden,
+    isDirty,
+    invalid,
+  };
+}
+
+/**
+ * Вычисление списка операций записи (writes) для scope.set:
+ * @param {Object|null} draft
+ * @param {Object} snap - { value, base, user }
+ * @returns {Array<[string, any]>}
+ */
+export function computeSavePlan(draft, snap) {
+  if (!draft) return [];
+
+  const writes = [];
+  const fields = ['maxIterations', 'autoDrive', 'enableSound'];
+
+  for (const f of fields) {
+    if (draft[f] === undefined) continue;
+
+    const status = getFieldStatus(f, draft[f], snap);
+    if (status.invalid) continue;
+
+    if (status.isDirty) {
+      if (f === 'maxIterations' && draft[f] === '') {
+        // Сброс переопределения
+        writes.push([f, undefined]);
+      } else if (f === 'maxIterations') {
+        writes.push([f, parseNumberField(draft[f])]);
+      } else {
+        writes.push([f, Boolean(draft[f])]);
+      }
+    }
+  }
+
+  return writes;
+}