@goodandready/dsh-kanban 0.2.35 → 0.2.37

package/lib/config.js

@@ -94,6 +94,8 @@ export const CONFIG_DEFAULTS = {
   watchdogEnabled: true,
   watchdogStallTimeoutMin: 15,
   watchdogMaxConsecutiveErrors: 5,
+  timeMachineEnabled: true,
+  timeMachineAutoSnapshot: true,
 }
 
 /** Field descriptions reused in schema and settings card. */
@@ -147,6 +149,8 @@ export const CONFIG_HINTS = {
   watchdogEnabled: 'Enable background watchdog timer and circuit breaker for stalled agent tasks.',
   watchdogStallTimeoutMin: 'Minutes of inactivity before active task is marked stalled by watchdog (default: 15).',
   watchdogMaxConsecutiveErrors: 'Number of consecutive execution errors before tripping circuit breaker (default: 5).',
+  timeMachineEnabled: 'Enable integration with @goodandready/dsh-time-machine for task checkpoints and rollback.',
+  timeMachineAutoSnapshot: 'Automatically create inception snapshot when task transitions to in-progress.',
 }
 
 /** Setting key for column WIP limit; not all columns have limits. */

package/lib/dependencies.js

@@ -0,0 +1,175 @@
+// Directed Acyclic Graph (DAG) task dependency validation and auto-unblocking logic.
+// Enforces that tasks with unresolved blockers cannot transition to in-progress.
+// Cycle detection prevents circular dependencies (e.g. A -> B -> A).
+
+/**
+ * Check if targetId is reachable from startId following blockedBy links.
+ *
+ * @param {string} startId starting task identifier
+ * @param {string} targetId target task identifier
+ * @param {Function|object} getTaskFn task getter function or store
+ * @param {Set<string>} [visited] visited set to break cycles during traversal
+ * @returns {boolean} true if targetId is reachable
+ */
+function canReach(startId, targetId, getTaskFn, visited = new Set()) {
+  if (startId === targetId) return true
+  if (visited.has(startId)) return false
+  visited.add(startId)
+
+  const task = typeof getTaskFn === 'function' ? getTaskFn(startId) : getTaskFn?.getTask?.(startId)
+  if (!task) return false
+
+  const blockers = Array.isArray(task.blockedBy) ? task.blockedBy : []
+  for (const nextId of blockers) {
+    if (typeof nextId === 'string' && nextId.trim() !== '') {
+      if (canReach(nextId, targetId, getTaskFn, visited)) return true
+    }
+  }
+  return false
+}
+
+/**
+ * Validate proposed dependencies for a task against cycles and self-references.
+ *
+ * @param {string} taskId task identifier
+ * @param {string[]} newBlockedBy proposed array of blocking task IDs
+ * @param {Function|object} getTaskFn task getter function or store
+ * @returns {{valid: boolean, error?: string}}
+ */
+export function validateDependencies(taskId, newBlockedBy, getTaskFn) {
+  if (!Array.isArray(newBlockedBy)) {
+    return { valid: true }
+  }
+
+  // 1. Check self-dependency
+  if (newBlockedBy.includes(taskId)) {
+    return {
+      valid: false,
+      error: `Self-dependency: task "${taskId}" cannot depend on itself.`,
+    }
+  }
+
+  // 2. Check for circular dependency
+  for (const blockerId of newBlockedBy) {
+    if (typeof blockerId !== 'string' || blockerId.trim() === '') continue
+    if (canReach(blockerId, taskId, getTaskFn)) {
+      return {
+        valid: false,
+        error: `Circular dependency detected: task "${blockerId}" already depends on "${taskId}".`,
+      }
+    }
+  }
+
+  return { valid: true }
+}
+
+/**
+ * Compute reverse mapping (blocks) from blockedBy relations across tasks.
+ *
+ * @param {Array<object>} tasks list of all tasks
+ * @returns {Record<string, string[]>} mapping of taskId to list of tasks it blocks
+ */
+export function computeBlocksMap(tasks) {
+  const blocks = {}
+  if (!Array.isArray(tasks)) return blocks
+
+  for (const task of tasks) {
+    if (task && typeof task.id === 'string') {
+      blocks[task.id] = []
+    }
+  }
+
+  for (const task of tasks) {
+    if (!task || typeof task.id !== 'string') continue
+    const blockedBy = Array.isArray(task.blockedBy) ? task.blockedBy : []
+    for (const bId of blockedBy) {
+      if (typeof bId === 'string' && bId.trim() !== '') {
+        if (!blocks[bId]) blocks[bId] = []
+        if (!blocks[bId].includes(task.id)) {
+          blocks[bId].push(task.id)
+        }
+      }
+    }
+  }
+
+  return blocks
+}
+
+/**
+ * Check whether a task is blocked by unfinished tasks.
+ *
+ * @param {object} task task object
+ * @param {Function|object} getTaskFn task getter function or store
+ * @returns {{isBlocked: boolean, pendingBlockers: Array<object>}}
+ */
+export function checkTaskBlocked(task, getTaskFn) {
+  const blockedBy = Array.isArray(task?.blockedBy) ? task.blockedBy : []
+  if (blockedBy.length === 0) {
+    return { isBlocked: false, pendingBlockers: [] }
+  }
+
+  const pending = []
+  for (const bId of blockedBy) {
+    if (typeof bId !== 'string' || bId.trim() === '') continue
+    const bTask = typeof getTaskFn === 'function' ? getTaskFn(bId) : getTaskFn?.getTask?.(bId)
+    if (bTask && bTask.column !== 'done') {
+      pending.push(bTask)
+    }
+  }
+
+  return {
+    isBlocked: pending.length > 0,
+    pendingBlockers: pending,
+  }
+}
+
+/**
+ * Check if moving a task to a target column is allowed under dependency constraints.
+ *
+ * @param {object} task task object
+ * @param {string} targetColumn target column
+ * @param {Function|object} getTaskFn task getter function or store
+ * @returns {{allowed: boolean, reason?: string, pendingBlockers?: Array<object>}}
+ */
+export function checkMoveAllowed(task, targetColumn, getTaskFn) {
+  if (targetColumn === 'in-progress') {
+    const check = checkTaskBlocked(task, getTaskFn)
+    if (check.isBlocked) {
+      const names = check.pendingBlockers.map((b) => b.title || b.id).join(', ')
+      return {
+        allowed: false,
+        reason: `Cannot move card to in-progress: task is blocked by unfinished tasks (${names}). All blockers must be in done before starting.`,
+        pendingBlockers: check.pendingBlockers,
+      }
+    }
+  }
+  return { allowed: true }
+}
+
+/**
+ * Find all tasks that were blocked by completedTaskId and are now unblocked.
+ *
+ * @param {string} completedTaskId ID of task moving to done
+ * @param {Function|object} getTaskFn task getter function or store
+ * @param {Function} listTasksFn function returning all tasks
+ * @returns {Array<object>} tasks that transitioned from blocked to unblocked
+ */
+export function findUnblockedDependents(completedTaskId, getTaskFn, listTasksFn) {
+  const allTasks = typeof listTasksFn === 'function' ? listTasksFn() : []
+  const unblocked = []
+
+  for (const task of allTasks) {
+    if (!task || task.column === 'done') continue
+    const blockedBy = Array.isArray(task.blockedBy) ? task.blockedBy : []
+    if (!blockedBy.includes(completedTaskId)) continue
+
+    // Check if task is still blocked by any other unfinished task
+    const check = checkTaskBlocked(task, getTaskFn)
+    if (!check.isBlocked) {
+      unblocked.push(task)
+    }
+  }
+
+  return unblocked
+}
+

package/lib/launcher.js

@@ -11,6 +11,7 @@
 // are passed as parameters to support unit testing without harness runtime.
 
 import { isAbsolute, join, resolve, sep } from 'node:path'
+import { formatPlanPrompt } from './plan-generator.js'
 import { randomUUID } from 'node:crypto'
 import { createTaskWorktree, registerDshWorkspace, isGitRepo } from './worktree.js'
 import { formatHandoverPreamble, parseProgressDump } from './progress-dump.js'
@@ -90,10 +91,13 @@ export function buildStartMessage(task, config) {
     ? `Task ${vars.repo}#${vars.issueNumber}: ${vars.title}`
     : `Task: ${vars.title}`
 
+  const planBlock = formatPlanPrompt(task)
+
   return joinBlocks([
     head,
     vars.body,
     fromIssue && vars.issueUrl !== '' ? `Link: ${vars.issueUrl}` : '',
+    planBlock,
     fromIssue ? WORKFLOW_TAIL : OWN_TAIL,
     note,
   ])

package/lib/plan-generator.js

@@ -0,0 +1,226 @@
+// Technical specification and execution plan generator for backlog/todo tasks (#376).
+// Zero Cyrillic literals in lib/ per Issue #366.
+
+import { MAX_ITEMS } from './plan.js'
+
+/**
+ * Truncate clean item text to reasonable single-line display length.
+ *
+ * @param {string} text Raw item text
+ * @returns {string} Truncated clean item
+ */
+function cleanItemText(text) {
+  const cleaned = String(text ?? '').replace(/\s+/g, ' ').trim()
+  return cleaned.length > 120 ? cleaned.slice(0, 119) + '…' : cleaned
+}
+
+/**
+ * Infer primary scope category from title, labels or body.
+ *
+ * @param {object} task Task record
+ * @returns {string} Scope name
+ */
+export function inferScope(task) {
+  const title = String(task?.title ?? '').toLowerCase()
+  const labels = Array.isArray(task?.labels) ? task.labels.map((l) => String(l).toLowerCase()) : []
+  for (const label of labels) {
+    if (label.startsWith('scope/')) return label.slice(6)
+  }
+  if (title.includes('ui') || title.includes('view') || title.includes('board') || title.includes('card')) return 'webui'
+  if (title.includes('tool') || title.includes('agent')) return 'agent-tools'
+  if (title.includes('setting') || title.includes('config')) return 'settings'
+  if (title.includes('worktree') || title.includes('branch') || title.includes('git')) return 'worktree'
+  if (title.includes('security') || title.includes('auth')) return 'security'
+  if (title.includes('route') || title.includes('api') || title.includes('server')) return 'routing'
+  return 'core'
+}
+
+/**
+ * Infer candidate files touched from task description and scope.
+ *
+ * @param {object} task Task record
+ * @param {string} scope Inferred or explicit scope
+ * @returns {string[]} List of candidate file paths
+ */
+export function inferCandidateFiles(task, scope) {
+  const body = String(task?.body ?? '')
+  const title = String(task?.title ?? '')
+  const combined = `${title}\n${body}`
+
+  const found = new Set()
+  // Match explicit file paths mentioned in markdown
+  const pathMatches = combined.match(/[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_./-]+\.(js|mjs|json|md|yml|yaml|css|html)/g)
+  if (pathMatches) {
+    for (const p of pathMatches) {
+      if (!p.startsWith('node_modules/') && !p.startsWith('.git/')) {
+        found.add(p)
+      }
+    }
+  }
+
+  // Add scope-based canonical files if set is small
+  if (found.size === 0) {
+    if (scope === 'webui') {
+      found.add('lib/client.js')
+      found.add('test/board-ui.test.mjs')
+    } else if (scope === 'settings') {
+      found.add('lib/config.js')
+      found.add('lib/client.js')
+      found.add('test/config.test.mjs')
+    } else if (scope === 'agent-tools') {
+      found.add('lib/board-tool.js')
+      found.add('test/board-tool.test.mjs')
+    } else if (scope === 'worktree') {
+      found.add('lib/worktree.js')
+      found.add('test/worktree.test.mjs')
+    } else if (scope === 'routing') {
+      found.add('lib/routes.js')
+      found.add('lib/server/route-handlers.js')
+      found.add('test/routes.test.mjs')
+    } else {
+      found.add('lib/store.js')
+      found.add('test/store.test.mjs')
+    }
+    found.add('CHANGELOG.md')
+    found.add('docs/design/DESIGN.md')
+  }
+
+  return Array.from(found).slice(0, 10)
+}
+
+/**
+ * Generate technical specification and structured plan for a backlog task (#376).
+ *
+ * @param {object} task Task object
+ * @param {object} [options]
+ * @param {string} [options.customInstructions]
+ * @param {string[]} [options.additionalFiles]
+ * @returns {{ spec: string, items: string[], summary: string, scope: string }}
+ */
+export function generateTechnicalSpec(task, options = {}) {
+  const title = String(task?.title ?? '').trim()
+  const body = String(task?.body ?? '').trim()
+  const issueNum = typeof task?.issueNumber === 'number' ? task.issueNumber : null
+  const issueTag = issueNum ? ` #${issueNum}` : ''
+  const scope = inferScope(task)
+
+  const candidateFiles = inferCandidateFiles(task, scope)
+  if (Array.isArray(options.additionalFiles)) {
+    for (const f of options.additionalFiles) {
+      if (typeof f === 'string' && f.trim() !== '') candidateFiles.push(f.trim())
+    }
+  }
+
+  const items = [
+    `1. Preflight: inspect requirements and existing files for ${title}`,
+    `2. Domain logic: implement core algorithms and validation rules`,
+    `3. Data layer: update schema, storage methods and routes if needed`,
+    `4. Integration & UI: connect route handlers, client views, and translations`,
+    `5. Verification: run automated test suite and ensure zero regressions`,
+  ]
+
+  const specLines = [
+    `# Technical Specification: ${title}${issueTag}`,
+    '',
+    '## 1. Problem Statement & Context',
+    body ? body : 'No detailed description provided. Analyze issue requirements from title.',
+    '',
+    '## 2. Target Components & Candidate Files',
+    ...candidateFiles.map((f) => `- \`${f}\``),
+    '',
+    '## 3. Step-by-Step Implementation Algorithm',
+    ...items.map((it) => it),
+    '',
+    '## 4. Edge Cases & Validation Rules',
+    '- Validate non-empty inputs and fail-closed error boundaries.',
+    '- Ensure backward compatibility with existing schemas and configs.',
+    '- Keep all handwritten files under 600 lines with zero Cyrillic literals in lib/.',
+    '- Maintain client bundle size strictly under 256,000 bytes limit.',
+    '',
+    '## 5. Verification Plan',
+    '- Unit test coverage covering happy paths and edge cases.',
+    '- Full test suite execution: npm test.',
+    '- Runtime smoke check on live server instance.',
+  ]
+
+  if (typeof options.customInstructions === 'string' && options.customInstructions.trim() !== '') {
+    specLines.push('', '## 6. Special Instructions', options.customInstructions.trim())
+  }
+
+  const spec = specLines.join('\n')
+  const summary = `Spec generated for ${title}${issueTag}: ${candidateFiles.length} files targeted, ${items.length} plan steps.`
+
+  return {
+    spec,
+    items: items.map(cleanItemText).slice(0, MAX_ITEMS),
+    summary,
+    scope,
+  }
+}
+
+/**
+ * Extract step-by-step items from markdown text.
+ *
+ * @param {string} markdown Raw markdown text
+ * @returns {string[]} List of extracted plan items
+ */
+export function extractPlanItems(markdown) {
+  if (typeof markdown !== 'string' || !markdown.trim()) return []
+  const lines = markdown.split('\n')
+  const items = []
+  let inAlgorithmSection = false
+
+  for (const line of lines) {
+    const trimmed = line.trim()
+    if (trimmed.startsWith('#')) {
+      const lower = trimmed.toLowerCase()
+      inAlgorithmSection = lower.includes('algorithm') || lower.includes('step') || lower.includes('plan')
+      continue
+    }
+
+    if (inAlgorithmSection || !items.length) {
+      const hasPrefix = /^(?:\d+\.|\-|\*|\[[\sxX]\])/.test(trimmed)
+      const match = trimmed.match(/^(?:(?:\d+\.|\-|\*)\s+)?(?:\[[\sxX]\]\s+)?(.+)$/)
+      if (hasPrefix && match && match[1]) {
+        const item = cleanItemText(match[1])
+        if (item) items.push(item)
+      }
+    }
+  }
+
+  return items.slice(0, MAX_ITEMS)
+}
+
+/**
+ * Parse markdown specification into structured representation.
+ *
+ * @param {string} markdown Raw markdown spec
+ * @returns {{ spec: string, items: string[] }}
+ */
+export function parseSpecMarkdown(markdown) {
+  const spec = typeof markdown === 'string' ? markdown.trim() : ''
+  const items = extractPlanItems(spec)
+  return { spec, items }
+}
+
+/**
+ * Format technical specification and plan into prompt string for agent.
+ *
+ * @param {object} task Task object
+ * @returns {string} Formatted markdown prompt section or empty string
+ */
+export function formatPlanPrompt(task) {
+  if (!task) return ''
+  const spec = typeof task.spec === 'string' ? task.spec.trim() : ''
+  const items = Array.isArray(task.plan?.items) ? task.plan.items : []
+
+  if (spec) {
+    return `### Approved Technical Specification & Implementation Plan:\n\n${spec}`
+  }
+
+  if (items.length > 0) {
+    return `### Approved Implementation Plan Steps:\n\n${items.map((it, idx) => `${idx + 1}. ${it}`).join('\n')}`
+  }
+
+  return ''
+}