@goodandready/dsh-kanban 0.2.19 → 0.2.20

package/lib/sync.js

@@ -1,8 +1,8 @@
-// Сверка задач с Gitea и применение автопереходов.
+// Task synchronization with Gitea and automated column transitions.
 //
-// Ни таймера, ни планировщика здесь нет: когда сверять — решает `lib/index.js`.
-// Здесь только «сверить вот эти задачи и применить, что выведется». Поэтому
-// модуль проверяется тестами с заглушкой клиента, без сети и без ожиданий.
+// Timing and scheduling are managed by `lib/index.js`.
+// This module provides the pure synchronization logic, testable with mock clients
+// without network dependencies or wait timers.
 
 import { deriveColumn, resolveTransition, branchOfTask, pullsOfTask, resolveConflict } from './transitions.js'
 import { watchedRepos, shouldTake, archiveBefore, isWatched } from './intake.js'
@@ -10,9 +10,9 @@ import { colorsOfIssue } from './filters.js'
 import { issueToTask, issueBornAt, issueAuthor, issueAssignee, issueMilestone } from './import.js'
 
 /**
- * Выполнить операцию с экспоненциальной задержкой (exponential backoff) при сбоях сети.
+ * Execute an async operation with exponential backoff on network failures.
  * @template T
- * @param {() => Promise<T>} fn асинхронная операция
+ * @param {() => Promise<T>} fn async operation
  * @param {{retries?: number, baseMs?: number, maxMs?: number}} [opts]
  * @returns {Promise<T>}
  */
@@ -33,17 +33,11 @@ export async function withBackoff(fn, { retries = 2, baseMs = 50, maxMs = 500 }
 }
 
 /**
- * Наблюдения по одному репозиторию.
+ * Observations for a single repository (pull requests and branches).
  *
- * Читается ОДИН раз на репозиторий, а не на задачу: у десяти задач одного
- * репозитория наблюдения общие, и десять одинаковых запросов — это просто
- * десятикратная нагрузка на инстанс.
- *
- * Ошибка НЕ проглатывается. Неполное наблюдение хуже отсутствующего: не
- * прочитались PR — доска решит, что их нет, и увезёт карточку из ревью назад в
- * работу. Не прочитались ветки — сочтёт, что cleanup сделан, и объявит задачу
- * завершённой. Поэтому репозиторий с неудачным чтением пропускается до
- * следующей сверки целиком.
+ * Read once per repository rather than per task to minimize API calls.
+ * Failures are not silently swallowed: incomplete observations (missing PRs or branches)
+ * would lead to erroneous column transitions. If reading fails, the repository is skipped.
  */
 async function readRepo({ gitea, owner, repo }) {
   const [pulls, branches] = await Promise.all([
@@ -54,7 +48,7 @@ async function readRepo({ gitea, owner, repo }) {
 }
 
 /**
- * Что Gitea говорит про одну задачу.
+ * Observed state from Gitea for a single task.
  *
  * @returns {{column: string|undefined, branch: string|undefined, pull: object|undefined}}
  */
@@ -67,31 +61,24 @@ export function observeTask(task, repoState, issue) {
   return { column, branch, pull }
 }
 
-/** Пояснение к переходу — чтобы журнал читался, а не расшифровывался. */
+/** Human-readable explanation for automated column transitions. */
 export function explain({ column, branch, pull }) {
   switch (column) {
-    case 'review': return pull?.number ? `PR #${pull.number} снят с WIP` : 'PR готов к ревью'
-    case 'deploy': return pull?.number ? `PR #${pull.number} влит` : 'PR влит'
-    case 'cleanup': return branch ? `issue закрыт, ветка ${branch} ещё есть` : 'issue закрыт'
-    case 'done': return 'issue закрыт, ветка удалена'
-    case 'in-progress': return branch ? `появилась ветка ${branch}` : 'работа началась'
+    case 'review': return pull?.number ? `PR #${pull.number} ready for review` : 'PR ready for review'
+    case 'deploy': return pull?.number ? `PR #${pull.number} merged` : 'PR merged'
+    case 'cleanup': return branch ? `issue closed, branch ${branch} still exists` : 'issue closed'
+    case 'done': return 'issue closed, branch deleted'
+    case 'in-progress': return branch ? `branch ${branch} appeared` : 'work started'
     default: return ''
   }
 }
 
 /**
- * Поля, которые доска забирает у Gitea при каждой сверке.
- *
- * Метки и заголовок — источник правды в Gitea: переименовали issue или сменили
- * `priority/high` на `priority/critical` — доска обязана это увидеть, иначе
- * отбор по меткам работает по вчерашней разметке и молча врёт.
+ * Remote fields synced from Gitea on each reconciliation run.
  *
- * **Тело НЕ забираем.** Его правит и человек — заметкой из чипа, — и сверка,
- * затирающая тело каждые две минуты, съедала бы заметки. Тело обновляется по
- * кнопке «обновить», где это осознанное решение человека.
- *
- * Возвращаем только изменившееся: лишняя запись поднимает `updatedAt`, а по
- * нему разрешается спор о том, кто двигал задачу позже.
+ * Title, labels, author, assignee, milestone are updated if changed.
+ * Task body is deliberately NOT overwritten to preserve user notes made from the UI chip.
+ * Returns only modified fields to minimize unnecessary database writes.
  */
 function remoteFields(task, issue) {
   const patch = {}
@@ -103,22 +90,19 @@ function remoteFields(task, issue) {
     const same = names.length === (task.labels ?? []).length
       && names.every((n) => (task.labels ?? []).includes(n))
     if (!same) patch.labels = names
-    // Цвет метки в Gitea меняют реже имени, но меняют: сверка обязана
-    // подхватывать и его, иначе карточка красится по позавчерашней палитре.
+    // Label colors are updated if modified in Gitea.
     const colors = colorsOfIssue(issue.labels)
     const before = task.labelColors ?? {}
     const sameColors = Object.keys(colors).length === Object.keys(before).length
       && Object.entries(colors).every(([k, v]) => before[k] === v)
     if (!sameColors) patch.labelColors = colors
   }
-  // Дату заведения тоже подхватываем: карточки, приехавшие до этой правки,
-  // помнят день подхвата, и починить их может только сверка.
+  // Issue creation timestamp is updated to fix tasks imported prior to timestamp tracking.
   const born = issueBornAt(issue)
   if (born !== undefined && born !== task.createdAt) patch.createdAt = born
   const author = issueAuthor(issue)
   if (author !== '' && author !== task.author) patch.author = author
-  // Ответственного сверка подхватывает В ОБЕ стороны: назначили в Gitea —
-  // видно на доске, сняли — тоже видно.
+  // Assignee changes are synced bidirectionally (assigned or unassigned).
   if (issue?.assignee !== undefined || Array.isArray(issue?.assignees)) {
     const assignee = issueAssignee(issue)
     if (assignee !== (task.assignee ?? '')) patch.assignee = assignee
@@ -131,17 +115,13 @@ function remoteFields(task, issue) {
 }
 
 /**
- * Свести наблюдения и применить переход, если он нужен.
- *
- * Наблюдённые ветка и PR записываются в карточку независимо от того, случился
- * перевод или нет: это наблюдение о задаче, полезное само по себе.
+ * Apply observations and transition column if needed.
  *
- * Если обе стороны двигались с последней сверки, побеждает более позднее
- * изменение, а проигравшее ОБЯЗАТЕЛЬНО попадает в журнал задачи. Синхронизация,
- * тихо отменяющая правку человека, хуже отсутствующей: расхождение остаётся, а
- * узнать о нём неоткуда.
+ * Observed branch and PR are updated on the task regardless of whether column changes.
+ * Conflicts between local board edits and remote Gitea updates are resolved by timestamp,
+ * recording overridden changes in the transition history.
  *
- * @returns {object|undefined} применённый переход либо undefined
+ * @returns {object|undefined} applied transition or undefined
  */
 export function applyObservation({ store, task, observation, issue, remoteUpdatedAt, now = Date.now() }) {
   const patch = { syncedAt: now, ...remoteFields(task, issue) }
@@ -157,14 +137,14 @@ export function applyObservation({ store, task, observation, issue, remoteUpdate
   })
 
   if (verdict.winner === 'local') {
-    // Доска победила, но если Gitea говорил другое — молчать нельзя.
+    // Board won the conflict; log transition note if Gitea had a different column.
     if (verdict.overridden !== undefined) {
       store.addTransition({
         taskId: task.id,
         fromCol: task.column,
         toCol: task.column,
         source: 'gitea',
-        detail: `расхождение: Gitea считает «${verdict.overridden}», доска правилась позже`,
+        detail: `conflict: Gitea has "${verdict.overridden}", board edited later`,
       })
     }
     return undefined
@@ -183,20 +163,17 @@ export function applyObservation({ store, task, observation, issue, remoteUpdate
     toCol: move.column,
     source: move.source,
     detail: verdict.overridden !== undefined
-      ? `${move.detail} (перекрыто: на доске было «${verdict.overridden}»)`
+      ? `${move.detail} (overridden: board had "${verdict.overridden}")`
       : move.detail,
   })
   return move
 }
 
 /**
- * Сверить все задачи, за которыми стоит issue.
+ * Reconcile all tasks backed by an active Gitea issue.
  *
- * Ошибка по одной задаче не останавливает остальные: недоступный репозиторий —
- * причина пропустить его до следующей сверки, а не бросить всю доску.
- *
- * Отчёт называет НЕ ТОЛЬКО числа, но и причину первой неудачи: «сверено ноль
- * из пяти» человеку ничего не говорит, а «репозиторий не найден» говорит всё.
+ * A failure on one repository does not abort others; report identifies total counts
+ * and specific problem details.
  *
  * @returns {{checked: number, moved: number, failed: number,
  *   repos: number, reposFailed: number, problem: {where: string, message: string}|undefined}}
@@ -214,12 +191,10 @@ export async function syncAll({ gitea, store, logger, only, now = Date.now() })
   let moved = 0
   let failed = 0
   let reposFailed = 0
-  // Первая беда важнее последней: при протухшем токене все репозитории
-  // отвалятся одинаково, и показывать надо причину, а не последний по счёту
-  // репозиторий.
+  // Record first failure detail for clear error reporting.
   let problem
   const note = (where, error) => {
-    if (problem === undefined) problem = { where, message: String(error?.message ?? error ?? 'без причины') }
+    if (problem === undefined) problem = { where, message: String(error?.message ?? error ?? 'unknown error') }
   }
 
   for (const group of byRepo.values()) {
@@ -230,7 +205,7 @@ export async function syncAll({ gitea, store, logger, only, now = Date.now() })
       failed += group.tasks.length
       reposFailed += 1
       note(`${group.owner}/${group.repo}`, error)
-      logger?.warn?.(`dsh-kanban: репозиторий ${group.owner}/${group.repo} не прочитан: ${error?.message}`)
+      logger?.warn?.(`dsh-kanban: repository ${group.owner}/${group.repo} read failed: ${error?.message}`)
       continue
     }
 
@@ -246,7 +221,7 @@ export async function syncAll({ gitea, store, logger, only, now = Date.now() })
       } catch (error) {
         failed += 1
         note(`${task.owner}/${task.repo}#${task.issueNumber}`, error)
-        logger?.warn?.(`dsh-kanban: задача ${task.id} не сверена: ${error?.message}`)
+        logger?.warn?.(`dsh-kanban: task ${task.id} sync failed: ${error?.message}`)
       }
     }
   }
@@ -255,15 +230,10 @@ export async function syncAll({ gitea, store, logger, only, now = Date.now() })
 }
 
 /**
- * Какие репозитории опрашивать.
- *
- * Названные поимённо — их и берём. Пустой список означает ВСЕ репозитории
- * владельца: доска обязана показывать то, что есть в Gitea, а не то, что ей
- * перечислили руками.
+ * Resolve repositories to monitor for intake.
  *
- * Из всех берутся только те, где есть открытые задачи. Число приходит в том же
- * ответе, и отсев бесплатен: полсотни запросов впустую каждые две минуты — это
- * не осторожность, а расточительство.
+ * Returns explicitly configured repositories, or all organization repos with open issues
+ * if no explicit list is configured.
  *
  * @returns {Promise<Array<{owner: string, repo: string}>>}
  */
@@ -271,7 +241,7 @@ async function resolveRepos({ gitea, config, owner }) {
   const named = watchedRepos({ config, owner })
   if (named.length > 0) return named
   if (owner === undefined || owner === '') {
-    throw new Error('владелец не определён: назовите организацию в настройках')
+    throw new Error('owner not specified: set organization in settings')
   }
   const rows = await gitea.listOrgRepos({ owner })
   return rows
@@ -280,11 +250,7 @@ async function resolveRepos({ gitea, config, owner }) {
 }
 
 /**
- * Забрать из отслеживаемых репозиториев задачи, которых на доске ещё нет.
- *
- * Отказ по одному репозиторию не останавливает остальные — как и в сверке:
- * недоступный репозиторий это повод пропустить его до следующего прохода, а не
- * бросить всю доску.
+ * Ingest new issues from tracked repositories that do not yet exist on the board.
  *
  * @returns {{added: number, skipped: number, failed: number, problem: object|undefined}}
  */
@@ -294,8 +260,7 @@ export async function intakeAll({ gitea, store, config, owner, logger, only, rep
   let failed = 0
   let problem
 
-  // `only` сужает проход до одного репозитория: событие вебхука говорит про
-  // один, и полный обход означал бы обращение ко всем при каждом чихе в любом.
+  // Filter by single repository if requested (e.g. from webhook event).
   let repos
   try {
     repos = (given ?? await resolveRepos({ gitea, config, owner }))
@@ -303,7 +268,7 @@ export async function intakeAll({ gitea, store, config, owner, logger, only, rep
   } catch (error) {
     return {
       added, skipped, failed: 1,
-      problem: { where: 'список репозиториев', message: String(error?.message ?? error) },
+      problem: { where: 'repository list', message: String(error?.message ?? error) },
     }
   }
 
@@ -316,7 +281,7 @@ export async function intakeAll({ gitea, store, config, owner, logger, only, rep
       if (problem === undefined) {
         problem = { where: `${pair.owner}/${pair.repo}`, message: String(error?.message ?? error) }
       }
-      logger?.warn?.(`dsh-kanban: задачи из ${pair.owner}/${pair.repo} не забраны: ${error?.message}`)
+      logger?.warn?.(`dsh-kanban: tasks from ${pair.owner}/${pair.repo} fetch failed: ${error?.message}`)
       continue
     }
 
@@ -324,9 +289,7 @@ export async function intakeAll({ gitea, store, config, owner, logger, only, rep
       const verdict = shouldTake({ store, owner: pair.owner, repo: pair.repo, issue })
       if (!verdict.take) { skipped += 1; continue }
       store.createTask(issueToTask(issue, {
-        // Подхват всегда идёт на проектную доску: импорт issue на простую
-        // осознанно отвергается (README «Две доски»), и параметра доски здесь
-        // нет — он был мёртвым.
+        // Imported issues always go to the 'main' project board in the 'backlog' column.
         board: 'main', column: 'backlog', owner: pair.owner, repo: pair.repo,
       }))
       added += 1
@@ -337,10 +300,9 @@ export async function intakeAll({ gitea, store, config, owner, logger, only, rep
 }
 
 /**
- * Убрать в архив то, что достояло в «Выполнено» свой срок.
+ * Archive tasks that have remained in 'done' past the retention threshold.
  *
- * Не удаляет: удаление — отдельное решение человека, и оно на доске уже есть.
- * Архив обязан быть обратимым, иначе им не станут пользоваться из страха.
+ * Archiving is reversible (does not hard-delete).
  */
 export function archiveOverdue({ store, config, now = Date.now() }) {
   const before = archiveBefore({ now, afterDays: config?.archiveAfterDays })
@@ -351,14 +313,10 @@ export function archiveOverdue({ store, config, now = Date.now() }) {
 }
 
 /**
- * Состояние сверки для показа человеку.
- *
- * Живёт в памяти процесса, а не в базе: это положение текущего запуска, а не
- * свойство задач. После перезапуска честнее сказать «сверки ещё не было», чем
- * показать вчерашний успех как сегодняшний.
+ * In-memory sync status for UI telemetry.
  *
- * Неудача НЕ затирает время последнего успеха. Иначе теряется ответ на главный
- * вопрос — когда доска последний раз видела правду.
+ * Stored in process memory rather than SQLite to reflect current run state.
+ * Sync failures do not wipe the last successful sync timestamp.
  */
 export function createSyncState() {
   let okAt
@@ -369,7 +327,7 @@ export function createSyncState() {
   return {
     started() { running = true },
 
-    /** Записать итог прохода. */
+    /** Record sync run outcome. */
     finished(report) {
       running = false
       if (report?.problem === undefined) {
@@ -382,11 +340,11 @@ export function createSyncState() {
       problem = report.problem
     },
 
-    /** Сверка не начиналась вовсе — тоже беда, и своя. */
+    /** Record failure when sync cannot start. */
     failedToStart(where, message) {
       running = false
       failedAt = Date.now()
-      problem = { where, message: String(message ?? 'без причины') }
+      problem = { where, message: String(message ?? 'unknown error') }
     },
 
     snapshot() {

package/lib/time.js

@@ -1,24 +1,18 @@
-// Относительное время для доски.
-//
-// Формат относительный, потому что «третий день» читается мгновенно, а точная
-// дата требует чтения и сравнения с сегодняшним числом. Скорость чтения тут и
-// есть смысл: на доску смотрят, чтобы за секунду понять, что застряло.
-//
-// Модуль отдаёт числа и единицу, а не готовую строку: собирает и переводит её
-// браузерная половина.
+// Relative time formatting for board.
+// Returns duration values; frontend translates and renders them.
 
 const MINUTE = 60_000
 const HOUR = 60 * MINUTE
 const DAY = 24 * HOUR
 
 /**
- * Насколько давно это было.
+ * How long ago the timestamp occurred.
  *
- * Будущее (расхождение часов между машинами) не выдумываем «через N минут», а
- * считаем настоящим моментом: показывать доске будущее незачем.
+ * Future timestamps are clamped to present moment.
+ * Board does not project future timestamps.
  *
  * @returns {{unit: 'now'|'min'|'hour'|'day', value: number}|undefined}
- *   `undefined` — отметки времени нет.
+ *   `undefined` - no timestamp.
  */
 export function relativeParts(now, then) {
   if (typeof then !== 'number' || !Number.isFinite(then) || then <= 0) return undefined
@@ -30,11 +24,8 @@ export function relativeParts(now, then) {
 }
 
 /**
- * Пора ли тревожиться о молчании задачи.
- *
- * Отдельного опроса живости сессий не заводим: это второй источник правды и
- * лишняя нагрузка. Смотрим на то, что и так знаем, — когда задачу последний
- * раз трогали.
+ * Whether task has been idle past threshold.
+ * Relies on last activity timestamp rather than active pinging.
  */
 export function isStale({ now, updatedAt, sessionId, afterMinutes }) {
   const limit = Number(afterMinutes)

package/lib/transitions.js

@@ -1,46 +1,36 @@
-// Автоперемещение карточек: вывод колонки из наблюдений и приоритет источников.
-//
-// Модуль чистый — ни сети, ни хранилища, ни харнесса. Наблюдения приходят
-// готовыми, решение возвращается значением. Поэтому вся логика переходов
-// проверяется тестами, а места, где она вызывается, остаются тонкими.
+// Card auto-movement: derive column from observations and source priority.
+// Pure module without network, storage, or harness dependencies.
+// Observations arrive as data, verdicts return as values.
 
 /**
- * Приоритет источников. Без него «PR влит → deploy» через секунду перебивалось
- * бы «ход завершился → in-progress», и карточка прыгала бы туда-сюда.
- *
- * Меньше число — сильнее источник.
+ * Source priority.
+ * Lower number indicates higher priority source.
  */
 const PRIORITY = { gitea: 0, tool: 1, session: 2, manual: 3 }
 
-/** Pull request считается черновиком, пока с него не снят признак WIP. */
+/** Pull request is draft while marked with WIP prefix or draft flag. */
 export function isDraftPull(pull) {
   if (pull?.draft === true) return true
   return /^\s*(wip|draft)\b[:\s-]/i.test(String(pull?.title ?? ''))
 }
 
 /**
- * Колонка, которую диктуют наблюдения в Gitea.
- *
- * Порядок проверок идёт от самого позднего состояния к самому раннему: задача
- * не может «вернуться» в in-progress только потому, что ветка ещё цела, если
- * issue уже закрыт.
- *
- * WIP PR намеренно НЕ двигает карточку в review: он открывается рано и означает
- * «работа идёт», а не «смотрите».
- *
- * @param {object} obs наблюдения
- * @param {object} [obs.issue] issue из Gitea (`state`)
- * @param {Array}  [obs.pulls] pull request-ы, связанные с задачей
- * @param {boolean} [obs.branchExists] существует ли ветка задачи
- * @returns {string|undefined} колонка либо undefined, если наблюдения молчат
+ * Target column derived from forge observations.
+ * Evaluated from latest lifecycle state to earliest.
+ * WIP PR intentionally does NOT move card to review.
+ * @param {object} obs observations
+ * @param {object} [obs.issue] issue from Gitea (`state`)
+ * @param {Array}  [obs.pulls] pull requests related to task
+ * @param {boolean} [obs.branchExists] whether task branch exists
+ * @returns {string|undefined} column or undefined if observations silent
  */
 export function deriveColumn(obs) {
   const issueClosed = obs?.issue?.state === 'closed'
   const pulls = Array.isArray(obs?.pulls) ? obs.pulls : []
   const branchExists = obs?.branchExists === true
 
-  // Задача завершена, только когда cleanup сделан: issue закрыт И ветки нет.
-  // Пока ветка цела, работа не закончена, сколько бы issue ни был закрыт.
+  // Task is finished only when cleanup is done: issue closed AND branch deleted.
+  // Task is finished only when cleanup is done: issue closed AND branch deleted.
   if (issueClosed && !branchExists) return 'done'
   if (issueClosed) return 'cleanup'
 
@@ -51,12 +41,10 @@ export function deriveColumn(obs) {
 }
 
 /**
- * Выбрать перевод из нескольких предложений разных источников.
+ * Select candidate transition from multiple sources.
  *
- * Предложение, совпадающее с текущей колонкой, отбрасывается: перевод в ту же
- * колонку — не перевод, а лишняя строка в журнале.
  *
- * @param {string} current текущая колонка
+ * @param {string} current current column
  * @param {Array<{column: string, source: string, detail?: string}>} candidates
  * @returns {{column: string, source: string, detail: string}|undefined}
  */
@@ -70,14 +58,10 @@ export function resolveTransition(current, candidates) {
 }
 
 /**
- * Нужен ли человек по событию сессии.
+ * Whether human intervention is required.
  *
- * Колонки «Блокировано» в согласованном наборе нет, поэтому запрос разрешения и
- * вопрос агента не двигают карточку, а поднимают на ней признак ожидания.
- * Двигать в несуществующую колонку нельзя, а прятать «агент стоит и ждёт» —
- * значит терять главное, ради чего смотрят на доску.
  *
- * @returns {boolean|undefined} true — поднять, false — снять, undefined — событие не про это
+ * @returns {boolean|undefined} true - raise, false - clear, undefined - not applicable
  */
 export function waitingFromEvent(type) {
   switch (type) {
@@ -93,20 +77,20 @@ export function waitingFromEvent(type) {
   }
 }
 
-/** Имя ветки, по которому задача узнаёт свою: то, что наблюдалось, либо ничего. */
+/** Branch name identified for task: observed branch or undefined. */
 export function branchOfTask(task, branches) {
   const known = typeof task?.branch === 'string' && task.branch !== '' ? task.branch : undefined
   const names = (branches ?? []).map((b) => (typeof b === 'string' ? b : b?.name)).filter(Boolean)
   if (known !== undefined) return names.includes(known) ? known : undefined
 
-  // Ветку задачи заводит агент и называет как хочет, но номер issue в имени —
-  // общее правило воркфлоу. Ищем по номеру, а не по угаданному шаблону.
+  // Agent creates branch matching workflow conventions with issue number.
+  // Look up by issue number rather than fixed string template.
   if (typeof task?.issueNumber !== 'number') return undefined
   const marker = String(task.issueNumber)
   return names.find((n) => new RegExp(`(^|[^0-9])${marker}([^0-9]|$)`).test(n))
 }
 
-/** Pull request-ы, относящиеся к задаче: по ветке либо по упоминанию issue. */
+/** Pull requests related to task: matched by branch or issue reference. */
 export function pullsOfTask(task, pulls, branch) {
   const number = typeof task?.issueNumber === 'number' ? task.issueNumber : undefined
   return (pulls ?? []).filter((p) => {
@@ -118,20 +102,16 @@ export function pullsOfTask(task, pulls, branch) {
 }
 
 /**
- * Кто победил, когда обе стороны изменились с последней сверки.
- *
- * Правило простое: побеждает более позднее изменение. Важно другое —
- * проигравшая сторона НЕ исчезает молча, а возвращается в поле `overridden`,
- * чтобы вызывающий записал её в журнал задачи. Синхронизация, которая тихо
- * отменяет правку человека, хуже синхронизации, которой нет: расхождение
- * остаётся, а узнать о нём неоткуда.
+ * Conflict resolution when both local and remote changed since last sync.
+ * Rule: latest timestamp wins, and overridden side is reported in `overridden`
+ * to record the conflict explicitly in task history.
  *
  * @param {object} state
- * @param {string} state.localColumn колонка на доске
- * @param {string} [state.remoteColumn] колонка, выведенная из Gitea
- * @param {number} state.localUpdatedAt когда правили на доске
- * @param {number} state.remoteUpdatedAt когда правили в Gitea
- * @param {number} state.syncedAt время последней удачной сверки
+ * @param {string} state.localColumn board column
+ * @param {string} [state.remoteColumn] column derived from forge
+ * @param {number} state.localUpdatedAt local update timestamp
+ * @param {number} state.remoteUpdatedAt remote update timestamp
+ * @param {number} state.syncedAt last successful sync timestamp
  * @returns {{winner: 'local'|'remote'|'none', column?: string, overridden?: string}}
  */
 export function resolveConflict({ localColumn, remoteColumn, localUpdatedAt, remoteUpdatedAt, syncedAt }) {
@@ -140,22 +120,21 @@ export function resolveConflict({ localColumn, remoteColumn, localUpdatedAt, rem
 
   const since = Number(syncedAt) || 0
 
-  // До первой сверки «изменилось с прошлого раза» не имеет смысла: прошлого
-  // раза не было. Карточку только что завели или импортировали, защищать в ней
-  // нечего, и первая сверка обязана принять положение дел, а не спорить с ним.
+  // Prior to first sync, 'changed since last time' has no prior baseline;
+  // accept remote state initially.
   const firstSync = since === 0
   const localChanged = !firstSync && (Number(localUpdatedAt) || 0) > since
   const remoteChanged = firstSync || (Number(remoteUpdatedAt) || 0) > since
 
   if (localChanged && remoteChanged) {
-    // Обе стороны двигались. Побеждает более позднее, проигравшее называется.
+    // Both sides modified: latest wins, overridden is recorded.
     if ((Number(localUpdatedAt) || 0) > (Number(remoteUpdatedAt) || 0)) {
       return { winner: 'local', overridden: remoteColumn }
     }
     return { winner: 'remote', column: remoteColumn, overridden: localColumn }
   }
 
-  // Двигалась только доска — Gitea не имеет права тянуть карточку назад.
+  // Only board moved: remote sync does not pull card backward.
   if (localChanged) return { winner: 'local' }
 
   return { winner: 'remote', column: remoteColumn }