feat: add delete subcommand for tasks and sections

Adds `steroids tasks delete <id|title>` and `steroids sections delete <id>`
commands with --force (skip in-progress guard / cascade tasks) and --dry-run
support. Cascades nullify references and clean all dependent rows atomically.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: rafiki270

src/commands/sections-delete.ts

@@ -0,0 +1,99 @@
+import { parseArgs } from 'node:util';
+import { withDatabase } from '../database/connection.js';
+import { getSection, deleteSection } from '../database/queries.js';
+import type { GlobalFlags } from '../cli/flags.js';
+import { createOutput } from '../cli/output.js';
+import { invalidArgumentsError, sectionNotFoundError } from '../cli/errors.js';
+import { ErrorCode, getExitCode } from '../cli/errors.js';
+
+export async function deleteSectionCmd(args: string[], flags: GlobalFlags): Promise<void> {
+  const out = createOutput({ command: 'sections', subcommand: 'delete', flags });
+
+  const { values, positionals } = parseArgs({
+    args,
+    options: {
+      force: { type: 'boolean', short: 'f', default: false },
+    },
+    allowPositionals: true,
+  });
+
+  if (flags.help) {
+    out.log(`
+steroids sections delete <id> - Permanently delete a section
+
+USAGE:
+  steroids sections delete <id> [options]
+
+ARGUMENTS:
+  id    Section ID or prefix (min 4 chars)
+
+OPTIONS:
+  -f, --force   Also delete all tasks belonging to the section
+  --dry-run     Show what would be deleted without making changes
+
+GLOBAL OPTIONS:
+  -j, --json    Output as JSON
+  -h, --help    Show help
+
+DESCRIPTION:
+  Permanently deletes a section and removes all its dependency edges.
+  By default, the command fails if the section still has tasks.
+  Use --force to delete the section along with all its tasks.
+
+EXAMPLES:
+  steroids sections delete abc123
+  steroids sections delete abc123 --force
+`);
+    return;
+  }
+
+  if (positionals.length === 0) {
+    throw invalidArgumentsError('Section ID required');
+  }
+
+  const sectionIdInput = positionals[0];
+  const projectPath = process.cwd();
+
+  withDatabase(projectPath, (db: any) => {
+    const section = getSection(db, sectionIdInput);
+    if (!section) {
+      throw sectionNotFoundError(sectionIdInput);
+    }
+
+    if (flags.dryRun) {
+      const taskCount = (db.prepare('SELECT COUNT(*) as n FROM tasks WHERE section_id = ?').get(section.id) as { n: number }).n;
+      out.log(`Would delete section: ${section.name} (${section.id})`);
+      if (taskCount > 0) {
+        if (values.force) {
+          out.log(`  Would also delete ${taskCount} task(s)`);
+        } else {
+          out.log(`  Section has ${taskCount} task(s) — add --force to delete them too`);
+        }
+      }
+      return;
+    }
+
+    let deletedTaskCount: number;
+    try {
+      deletedTaskCount = deleteSection(db, section.id, { force: values.force });
+    } catch (err: any) {
+      out.error(ErrorCode.GENERAL_ERROR, err.message);
+      process.exit(getExitCode(ErrorCode.GENERAL_ERROR));
+    }
+
+    if (flags.json) {
+      out.success({
+        deleted: {
+          id: section.id,
+          name: section.name,
+          deletedTaskCount,
+        },
+      });
+    } else {
+      out.log(`Deleted section: ${section.name} (${section.id})`);
+      if (deletedTaskCount > 0) {
+        out.log(`  Also deleted ${deletedTaskCount} task(s)`);
+      }
+    }
+  });
+}

src/commands/sections.ts

@@ -24,6 +24,7 @@ import {
   updateSection,
   resetSectionPr,
 } from './sections-commands.js';
+import { deleteSectionCmd } from './sections-delete.js';
 import { generateHelp } from '../cli/help.js';
 import { createOutput } from '../cli/output.js';
 import { ErrorCode, getExitCode } from '../cli/errors.js';
@@ -43,6 +44,7 @@ Sections help structure large projects and track high-level progress.`,
     { name: 'priority', args: '<id> <value>', description: 'Set section priority (0-100 or high/medium/low)' },
     { name: 'depends-on', args: '<id> <depends-on-id>', description: 'Add section dependency' },
     { name: 'no-depends-on', args: '<id> <dep-id>', description: 'Remove section dependency' },
+    { name: 'delete', args: '<id>', description: 'Permanently delete a section' },
     { name: 'graph', args: '[options]', description: 'Show dependency graph (ASCII, Mermaid, image)' },
   ],
   options: [
@@ -67,6 +69,8 @@ Sections help structure large projects and track high-level progress.`,
     { command: 'steroids sections priority abc123 25', description: 'Set numeric priority (0-100)' },
     { command: 'steroids sections depends-on abc123 def456', description: 'Add dependency' },
     { command: 'steroids sections no-depends-on abc123 def456', description: 'Remove dependency' },
+    { command: 'steroids sections delete abc123', description: 'Delete empty section' },
+    { command: 'steroids sections delete abc123 --force', description: 'Delete section and all its tasks' },
     { command: 'steroids sections graph', description: 'ASCII tree view (default)' },
     { command: 'steroids sections graph --json', description: 'JSON output' },
     { command: 'steroids sections graph --mermaid', description: 'Mermaid flowchart syntax' },
@@ -128,6 +132,9 @@ export async function sectionsCommand(args: string[], flags: GlobalFlags): Promi
     case 'no-depends-on':
       await removeDependency(subArgs, flags);
       break;
+    case 'delete':
+      await deleteSectionCmd(subArgs, flags);
+      break;
     case 'graph':
       await showGraph(subArgs, flags);
       break;

src/commands/tasks-reset.ts

@@ -3,7 +3,7 @@ import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { openDatabase, withDatabase } from '../database/connection.js';
-import { getTask, getTaskByTitle, listTasks, getSectionDependencies, type Task } from '../database/queries.js';
+import { getTask, getTaskByTitle, listTasks, getSectionDependencies, deleteTask, type Task } from '../database/queries.js';
 import { createOutput } from '../cli/output.js';
 import { ErrorCode, getExitCode } from '../cli/errors.js';
 import type { GlobalFlags } from '../cli/flags.js';
@@ -289,3 +289,76 @@ function killRunnerAndRevokeLease(taskId: string, projDb: any, out: any) {
     closeGlobal();
   }
 }
+
+export async function deleteTaskCmd(args: string[], flags: GlobalFlags): Promise<void> {
+  const out = createOutput({ command: 'tasks', subcommand: 'delete', flags });
+
+  const { values, positionals } = parseArgs({
+    args,
+    options: {
+      force: { type: 'boolean', short: 'f', default: false },
+    },
+    allowPositionals: true,
+  });
+
+  if (flags.help) {
+    out.log(`
+steroids tasks delete <id|title> - Permanently delete a task
+
+USAGE:
+  steroids tasks delete <id|title> [options]
+
+ARGUMENTS:
+  id|title    Task ID (or prefix) or title
+
+OPTIONS:
+  -f, --force   Delete even if the task is currently in progress
+  --dry-run     Show what would be deleted without making changes
+
+GLOBAL OPTIONS:
+  -j, --json    Output as JSON
+  -h, --help    Show help
+
+EXAMPLES:
+  steroids tasks delete abc123
+  steroids tasks delete "Build login page"
+  steroids tasks delete abc123 --force
+`);
+    return;
+  }
+
+  if (positionals.length === 0) {
+    out.error(ErrorCode.INVALID_ARGUMENTS, 'Task ID or title required');
+    process.exit(getExitCode(ErrorCode.INVALID_ARGUMENTS));
+  }
+
+  const identifier = positionals.join(' ');
+  const projectPath = process.cwd();
+
+  withDatabase(projectPath, (db: any) => {
+    const task = getTask(db, identifier) || getTaskByTitle(db, identifier);
+    if (!task) {
+      out.error(ErrorCode.TASK_NOT_FOUND, `Task not found: ${identifier}`);
+      process.exit(getExitCode(ErrorCode.TASK_NOT_FOUND));
+    }
+
+    if (task.status === 'in_progress' && !values.force) {
+      out.error(ErrorCode.GENERAL_ERROR, `Task is currently in progress. Use --force to delete it anyway.`);
+      process.exit(1);
+    }
+
+    if (flags.dryRun) {
+      out.log(`Would delete task: ${task.title} (${task.id})`);
+      out.log(`  Status: ${task.status}`);
+      return;
+    }
+
+    deleteTask(db, task.id);
+
+    if (flags.json) {
+      out.success({ deleted: { id: task.id, title: task.title } });
+    } else {
+      out.log(`Deleted task: ${task.title} (${task.id})`);
+    }
+  });
+}

src/commands/tasks.ts

@@ -51,7 +51,7 @@ import {
   triggerProjectCompleted,
   triggerHooksSafely,
 } from '../hooks/integration.js';
-import { resetTaskCmd } from './tasks-reset.js';
+import { resetTaskCmd, deleteTaskCmd } from './tasks-reset.js';
 import { addTaskDependencyCmd, removeTaskDependencyCmd, displayTaskDependencies } from './tasks-deps.js';
 import {
   isFileTracked,
@@ -85,6 +85,7 @@ Use this command to add, update, approve, reject, or skip tasks.`,
     { name: 'audit', args: '<id|title>', description: 'View task audit trail' },
     { name: 'promote', args: '<id>', description: 'Enable auto-implementation for a deferred follow-up' },
     { name: 'reset', args: '[<id|title>]', description: 'Reset failed/disputed tasks to pending' },
+    { name: 'delete', args: '<id|title>', description: 'Permanently delete a task' },
     { name: 'depends-on', args: '<id> <dep-id>', description: 'Add task dependency (id depends on dep-id)' },
     { name: 'no-depends-on', args: '<id> <dep-id>', description: 'Remove task dependency' },
   ],
@@ -209,6 +210,9 @@ export async function tasksCommand(args: string[], flags: GlobalFlags): Promise<
     case 'reset':
       await resetTaskCmd(subArgs, flags);
       break;
+    case 'delete':
+      await deleteTaskCmd(subArgs, flags);
+      break;
     case 'depends-on':
       await addTaskDependencyCmd(subArgs, flags);
       break;

src/database/queries.ts

@@ -2063,3 +2063,50 @@ export function returnTaskToPending(
 
   addAuditEntry(db, taskId, task.status, 'pending', actor, notes ?? 'Returned to pending for retry');
 }
+
+// ── Delete operations ──────────────────────────────────────────────────────
+
+/**
+ * Permanently delete a task and all its dependent records.
+ * Callers should check task status and warn about in-progress tasks beforehand.
+ */
+export function deleteTask(db: Database.Database, taskId: string): void {
+  db.transaction(() => {
+    // Nullify self-referential FKs before deleting (foreign_keys = ON)
+    db.prepare('UPDATE tasks SET reference_task_id = NULL WHERE reference_task_id = ?').run(taskId);
+    db.prepare('UPDATE incidents SET task_id = NULL WHERE task_id = ?').run(taskId);
+    // Remove all dependent rows
+    db.prepare('DELETE FROM task_dependencies WHERE task_id = ? OR depends_on_task_id = ?').run(taskId, taskId);
+    db.prepare('DELETE FROM task_locks WHERE task_id = ?').run(taskId);
+    db.prepare('DELETE FROM task_invocations WHERE task_id = ?').run(taskId);
+    db.prepare('DELETE FROM disputes WHERE task_id = ?').run(taskId);
+    db.prepare('DELETE FROM audit WHERE task_id = ?').run(taskId);
+    db.prepare('DELETE FROM task_feedback WHERE task_id = ?').run(taskId);
+    db.prepare('DELETE FROM tasks WHERE id = ?').run(taskId);
+  })();
+}
+
+/**
+ * Permanently delete a section and (with force=true) all its tasks.
+ * Throws if the section has tasks and force is false.
+ * Returns the number of tasks deleted.
+ */
+export function deleteSection(
+  db: Database.Database,
+  sectionId: string,
+  { force = false }: { force?: boolean } = {},
+): number {
+  const tasks = db.prepare('SELECT id FROM tasks WHERE section_id = ?').all(sectionId) as { id: string }[];
+  if (tasks.length > 0 && !force) {
+    throw new Error(`Section has ${tasks.length} task(s). Use --force to delete them along with the section.`);
+  }
+  db.transaction(() => {
+    for (const { id } of tasks) {
+      deleteTask(db, id);
+    }
+    db.prepare('DELETE FROM section_locks WHERE section_id = ?').run(sectionId);
+    db.prepare('DELETE FROM section_dependencies WHERE section_id = ? OR depends_on_section_id = ?').run(sectionId, sectionId);
+    db.prepare('DELETE FROM sections WHERE id = ?').run(sectionId);
+  })();
+  return tasks.length;
+}