dw-kit 1.9.0-rc.1 → 1.9.1

package/src/commands/task-migrate.mjs

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import chalk from 'chalk';
 import { parseFrontmatter, stringifyFrontmatter } from '../lib/frontmatter.mjs';
 import { logEvent } from '../lib/telemetry.mjs';
+import { bareSchemaVersion } from '../lib/task-store.mjs';
 
 const TASKS_DIR = '.dw/tasks';
 
@@ -72,7 +73,7 @@ function mergeFrontmatter(specFm, trackingFm) {
     depth: specFm.depth || 'standard',
     related_adr: String(specFm.related_adr || 'none').match(/^(ADR-\d{4}|none)$/) ? specFm.related_adr : 'none',
     target_ship: specFm.target_ship || 'TBD',
-    schema_version: 'v3.0',
+    schema_version: 'task@v3.0',
     blockers: trackingFm.blockers || 'none',
   };
 }
@@ -308,7 +309,7 @@ function findV3Tasks(rootDir, targetSchemaVersion = 'v3.0') {
         const taskFile = join(e.path, 'task.md');
         if (!existsSync(taskFile)) return false;
         const fm = parseFrontmatter(readFileSync(taskFile, 'utf8'));
-        return fm.schema_version === targetSchemaVersion;
+        return bareSchemaVersion(fm.schema_version) === bareSchemaVersion(targetSchemaVersion);
       } catch { return false; }
     });
 }
@@ -321,16 +322,16 @@ async function migrateOneToV31(taskDir, opts) {
   }
   const content = readFileSync(taskFile, 'utf8');
   const fm = parseFrontmatter(content);
-  if (fm.schema_version === 'v3.1') {
+  if (bareSchemaVersion(fm.schema_version) === 'v3.1') {
     console.log(chalk.dim(`  · ${taskDir} — already v3.1`));
     return { ok: true, noop: true };
   }
-  if (fm.schema_version !== 'v3.0') {
+  if (bareSchemaVersion(fm.schema_version) !== 'v3.0') {
     console.log(chalk.yellow(`  ⚠  ${taskDir} — schema_version=${fm.schema_version || 'missing'}, expected v3.0 — skipping`));
     return { ok: false, skipped: true };
   }
 
-  const updated = { ...fm, schema_version: 'v3.1' };
+  const updated = { ...fm, schema_version: 'task@v3.1' };
   if (!('parent_goal_id' in updated)) updated.parent_goal_id = null;
   if (!('contributing_goal_ids' in updated)) updated.contributing_goal_ids = [];
   if (!('summary' in updated)) updated.summary = null;
@@ -457,6 +458,16 @@ export async function taskMigrateCommand(taskName, opts = {}) {
     dry_run: !!opts.dryRun,
   }, rootDir);
 
+  // Keep tasks-index@v1 current after a real migration (ADR-0017 doc contract).
+  if (!opts.dryRun && !opts.diff) {
+    try {
+      const { syncTaskIndexEntry } = await import('../lib/task-store.mjs');
+      for (const r of results) {
+        if (r.ok && !r.noop && !r.skipped) syncTaskIndexEntry(r.name, rootDir);
+      }
+    } catch { /* best-effort; `dw task index` rebuilds authoritatively */ }
+  }
+
   console.log();
   if (opts.dryRun) {
     console.log(chalk.cyan(`  Dry-run complete. Re-run without --dry-run to apply.`));

package/src/commands/task-new.mjs

@@ -76,6 +76,12 @@ export async function taskNewCommand(taskName, opts = {}) {
   const target = join(taskDir, 'task.md');
   writeFileSync(target, filled, 'utf8');
 
+  // Keep tasks-index@v1 current on creation (ADR-0017 doc contract).
+  try {
+    const { syncTaskIndexEntry } = await import('../lib/task-store.mjs');
+    syncTaskIndexEntry(slug, rootDir);
+  } catch { /* index is best-effort here; `dw task index` rebuilds authoritatively */ }
+
   logEvent({ event: 'task', action: 'new', name: slug, depth }, rootDir);
 
   console.log();

package/src/commands/task-summary.mjs

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import chalk from 'chalk';
 import { parseFrontmatter, stringifyFrontmatter } from '../lib/frontmatter.mjs';
 import { logEvent } from '../lib/telemetry.mjs';
+import { bareSchemaVersion } from '../lib/task-store.mjs';
 
 const TASKS_DIR = '.dw/tasks';
 const MAX_SUMMARY_CHARS = 1000;
@@ -38,7 +39,7 @@ export async function taskSummaryCommand(taskName, opts = {}) {
       process.exit(1);
     }
     const updated = { ...fm, summary: opts.write || null, last_updated: todayIso() };
-    if (updated.schema_version === 'v3.0') updated.schema_version = 'v3.1';
+    if (bareSchemaVersion(updated.schema_version) === 'v3.0') updated.schema_version = 'task@v3.1';
     const body = content.replace(/^---\n[\s\S]*?\n---\n?/, '');
     writeFileSync(file, stringifyFrontmatter(updated) + body, 'utf8');
 
@@ -46,8 +47,8 @@ export async function taskSummaryCommand(taskName, opts = {}) {
 
     console.log();
     console.log(chalk.green(`  ✓  Summary updated for ${chalk.bold(taskName)} (${(opts.write || '').length}/${MAX_SUMMARY_CHARS} chars)`));
-    if (fm.schema_version === 'v3.0') {
-      console.log(chalk.dim(`     Auto-bumped schema_version v3.0 → v3.1`));
+    if (bareSchemaVersion(fm.schema_version) === 'v3.0') {
+      console.log(chalk.dim(`     Auto-bumped schema_version v3.0 → task@v3.1`));
     }
     console.log();
     return;

package/src/lib/decision-store.mjs

@@ -0,0 +1,146 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { parseFrontmatter } from './frontmatter.mjs';
+
+// DW Document Schema + Index v1.0 — decisions (ADR) half (ADR-0017 v1.1).
+// ADRs use TWO metadata styles in the wild:
+//   - YAML frontmatter (early ADRs, e.g. ADR-0001)
+//   - markdown headers `# ADR-NNNN: Title` + `## Status:` / `## Date:` / ...
+// The parser tolerates both so external adapters consume one normalized index.
+
+const DECISIONS_DIR = '.dw/decisions';
+const INDEX_FILE = '.dw/decisions/decisions-index.json';
+const SCHEMA_VERSION = 'decisions-index@v1';
+const STATUS_KEYWORDS = ['Proposed', 'Accepted', 'Deprecated', 'Superseded'];
+
+export function decisionsDir(rootDir = process.cwd()) {
+  return join(rootDir, DECISIONS_DIR);
+}
+
+export function decisionIndexFile(rootDir = process.cwd()) {
+  return join(rootDir, INDEX_FILE);
+}
+
+function nowUtc() {
+  return new Date().toISOString().replace(/\.\d+Z$/, 'Z');
+}
+
+function emptyIndex() {
+  return { schema_version: SCHEMA_VERSION, last_updated: nowUtc(), decisions: {} };
+}
+
+export function readDecisionIndex(rootDir = process.cwd()) {
+  const file = decisionIndexFile(rootDir);
+  if (!existsSync(file)) return emptyIndex();
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf8'));
+    if (!parsed || typeof parsed !== 'object' || !parsed.decisions) return emptyIndex();
+    return parsed;
+  } catch {
+    return emptyIndex();
+  }
+}
+
+export function writeDecisionIndex(index, rootDir = process.cwd()) {
+  const file = decisionIndexFile(rootDir);
+  const dir = dirname(file);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const updated = { ...index, schema_version: SCHEMA_VERSION, last_updated: nowUtc() };
+  writeFileSync(file, JSON.stringify(updated, null, 2) + '\n', 'utf8');
+}
+
+// .dw/decisions/NNNN-slug.md → { id: 'ADR-NNNN', num: 'NNNN', file }
+export function listDecisionFiles(rootDir = process.cwd()) {
+  const dir = decisionsDir(rootDir);
+  if (!existsSync(dir)) return [];
+  const out = [];
+  for (const name of readdirSync(dir)) {
+    if (!name.endsWith('.md')) continue;
+    if (name.startsWith('_')) continue; // _template.md
+    const m = name.match(/^(\d{3,4})-/);
+    if (!m) continue;
+    out.push({ id: `ADR-${m[1]}`, num: m[1], file: join(dir, name), rel: `${DECISIONS_DIR}/${name}` });
+  }
+  return out;
+}
+
+function firstDate(s) {
+  if (!s) return null;
+  const m = String(s).match(/\d{4}-\d{2}-\d{2}/);
+  return m ? m[0] : null;
+}
+
+function normalizeStatus(raw) {
+  if (!raw) return { status: 'Proposed', superseded_by: null };
+  const text = String(raw);
+  const kw = STATUS_KEYWORDS.find((k) => new RegExp(`^\\s*${k}`, 'i').test(text));
+  const status = kw || (/superseded/i.test(text) ? 'Superseded' : 'Proposed');
+  const sb = text.match(/superseded by\s+(ADR-\d{3,4})/i);
+  return { status, superseded_by: sb ? sb[1] : null };
+}
+
+function adrRefs(s, selfId) {
+  if (!s) return [];
+  const refs = [...String(s).matchAll(/ADR-\d{3,4}/g)].map((m) => m[0]);
+  return [...new Set(refs)].filter((r) => r !== selfId);
+}
+
+function mdHeader(content, label) {
+  const m = content.match(new RegExp(`^##\\s+${label}:\\s*(.+)$`, 'm'));
+  return m ? m[1].trim() : null;
+}
+
+// Tolerant extractor: YAML frontmatter wins; falls back to markdown headers.
+export function parseDecisionMeta(id, content) {
+  const fm = parseFrontmatter(content);
+  const hasFm = fm && (fm.status || fm.title || fm.id);
+
+  const title = (hasFm && fm.title)
+    || (content.match(/^#\s+ADR-\d{3,4}:\s*(.+?)\s*$/m)?.[1])
+    || (content.match(/^#\s+(.+?)\s*$/m)?.[1])
+    || id;
+
+  const rawStatus = (hasFm && fm.status) || mdHeader(content, 'Status');
+  const { status, superseded_by } = normalizeStatus(rawStatus);
+
+  const date = firstDate((hasFm && fm.date) || mdHeader(content, 'Date'));
+  const deciders = ((hasFm && fm.deciders) || mdHeader(content, 'Deciders') || null);
+
+  const relatedSrc = `${(hasFm && fm.related) || mdHeader(content, 'Related') || ''} ${rawStatus || ''}`;
+  const related = adrRefs(relatedSrc, id);
+  const supersedes = hasFm && fm.supersedes && fm.supersedes !== 'null'
+    ? adrRefs(String(fm.supersedes), id)
+    : [];
+
+  return {
+    title: String(title).trim(),
+    status,
+    status_raw: rawStatus ? String(rawStatus).trim() : null,
+    date,
+    deciders: deciders ? String(deciders).trim() : null,
+    related,
+    supersedes,
+    superseded_by: superseded_by || (hasFm && fm['superseded-by'] && fm['superseded-by'] !== 'null' ? String(fm['superseded-by']) : null),
+  };
+}
+
+function decisionEntry(file, id, rootDir) {
+  if (!existsSync(file)) return null;
+  const content = readFileSync(file, 'utf8');
+  const meta = parseDecisionMeta(id, content);
+  return { ...meta, file: `${DECISIONS_DIR}/${file.split(/[\\/]/).pop()}` };
+}
+
+export function rebuildDecisionIndex(rootDir = process.cwd()) {
+  const index = emptyIndex();
+  for (const d of listDecisionFiles(rootDir)) {
+    const entry = decisionEntry(d.file, d.id, rootDir);
+    if (entry) index.decisions[d.id] = entry;
+  }
+  const existing = readDecisionIndex(rootDir);
+  if (JSON.stringify(existing.decisions) === JSON.stringify(index.decisions)) {
+    return existing;
+  }
+  writeDecisionIndex(index, rootDir);
+  return index;
+}

package/src/lib/goal-store.mjs

@@ -1,6 +1,7 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { parseFrontmatter, stringifyFrontmatter } from './frontmatter.mjs';
+import { parseSubtaskTracker } from './timeline-parser.mjs';
 
 const GOALS_DIR = '.dw/goals';
 const INDEX_FILE = '.dw/goals/goals-index.json';
@@ -38,15 +39,35 @@ export function readGoalIndex(rootDir = process.cwd()) {
   }
 }
 
+// Stable key order so the same goal set serializes byte-identically regardless
+// of writer path (syncIndexEntry appends; rebuilds use readdirSync order) (#21).
+function sortGoals(goals) {
+  const sorted = {};
+  for (const id of Object.keys(goals || {}).sort()) sorted[id] = goals[id];
+  return sorted;
+}
+
 export function writeGoalIndex(index, rootDir = process.cwd()) {
   const file = goalIndexFile(rootDir);
   const dir = dirname(file);
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const goals = sortGoals(index.goals);
+  // Skip the write when the goal set is byte-identical to disk: preserves the
+  // on-disk last_updated (freshness signal, ADR-0017/0018) and yields zero diff.
+  const prior = readGoalIndex(rootDir);
+  if (existsSync(file) && JSON.stringify(sortGoals(prior.goals)) === JSON.stringify(goals)) {
+    return prior;
+  }
+  // Spread `index` first so non-payload top-level fields ($schema_note,
+  // schema_version) and their order are preserved; override goals (sorted) +
+  // last_updated in place.
   const updated = {
     ...index,
     last_updated: new Date().toISOString().replace(/\.\d+Z$/, 'Z'),
+    goals,
   };
   writeFileSync(file, JSON.stringify(updated, null, 2) + '\n', 'utf8');
+  return updated;
 }
 
 export function readGoal(goalId, rootDir = process.cwd()) {
@@ -125,7 +146,7 @@ export function computeGoalProgress(goalId, rootDir = process.cwd(), linkedTasks
     if (!existsSync(taskFile)) continue;
     const content = readFileSync(taskFile, 'utf8');
     const tracker = extractTrackerSection(content);
-    for (const row of parseTrackerRows(tracker)) {
+    for (const row of parseSubtaskTracker(tracker)) {
       total++;
       if (row.status.includes('✅') || /Done/i.test(row.status)) done++;
       else if (row.status.includes('🟡') || /In Progress/i.test(row.status)) inProgress++;
@@ -143,19 +164,6 @@ function extractTrackerSection(content) {
   return m ? m[0] : '';
 }
 
-function parseTrackerRows(section) {
-  const rows = [];
-  const lines = section.split('\n');
-  for (const line of lines) {
-    // Match table rows like: | ST-N | Description | Status | Date | Notes |
-    if (!/^\|\s*(ST|WS)-/.test(line)) continue;
-    const cells = line.split('|').map((c) => c.trim());
-    if (cells.length < 4) continue;
-    // cells[0] = "" (before first |), [1] = ID, [2] = subtask, [3] = status
-    rows.push({ id: cells[1], subtask: cells[2], status: cells[3] || '', date: cells[4] || '', notes: cells[5] || '' });
-  }
-  return rows;
-}
 
 export function removeIndexEntry(goalId, rootDir = process.cwd()) {
   const index = readGoalIndex(rootDir);
@@ -181,7 +189,9 @@ export function findLinkedTaskIds(goalId, rootDir = process.cwd()) {
       else if (Array.isArray(fm.contributing_goal_ids) && fm.contributing_goal_ids.includes(goalId)) linked.push(entry);
     } catch { /* skip */ }
   }
-  return linked;
+  // Sort for determinism — readdirSync order is filesystem-dependent and would
+  // otherwise churn linked_task_ids in the committed index (#21).
+  return linked.sort();
 }
 
 function extractTitle(content) {
@@ -200,3 +210,20 @@ export function nowUtc() {
 export function validateGoalId(goalId) {
   return /^G-[A-Za-z0-9](?:[A-Za-z0-9.-]{0,31}[A-Za-z0-9])?$/.test(goalId);
 }
+
+// Single source for the goal lifecycle status enum (#20). Reads the project's
+// schema (consumer-vendored via `dw init`) and falls back to the canonical set
+// when absent, so the status command works in a stripped install.
+const FALLBACK_GOAL_STATUSES = ['Draft', 'Active', 'Achieved', 'Abandoned', 'Pivoted'];
+
+export function goalStatusEnum(rootDir = process.cwd()) {
+  const schemaFile = join(rootDir, '.dw/core/schemas/goal-frontmatter.schema.json');
+  if (!existsSync(schemaFile)) return [...FALLBACK_GOAL_STATUSES];
+  try {
+    const schema = JSON.parse(readFileSync(schemaFile, 'utf8'));
+    const enumVals = schema?.properties?.status?.enum;
+    return Array.isArray(enumVals) && enumVals.length ? enumVals : [...FALLBACK_GOAL_STATUSES];
+  } catch {
+    return [...FALLBACK_GOAL_STATUSES];
+  }
+}

package/src/lib/lint-rules.mjs

@@ -44,10 +44,19 @@ export function lintTimeline(taskDir, opts = {}) {
     const result = validateFrontmatter(fm, schema);
     if (!result.ok) {
       for (const e of result.errors) {
+        let message = `${e.path}: ${e.message}${e.keyword ? ` (${e.keyword})` : ''}`;
+        // #22: the raw ajv enum error for schema_version is opaque. Teach the
+        // allowed values + the namespaced-vs-bare convention right at the error.
+        if (e.path === '/schema_version' && e.keyword === 'enum') {
+          const allowed = (e.params?.allowedValues || []).map((v) => `"${v}"`).join(', ');
+          message = `schema_version: must be one of ${allowed}. Canonical is namespaced `
+            + `(task@v3.x) to match goal@v1 / tasks-index@v1; bare v3.x stays valid for `
+            + `back-compat. See docs/specs/dw-document-schema-v1.0.md §2.1.`;
+        }
         violations.push({
           severity: 'error',
           rule: 'frontmatter-schema',
-          message: `${e.path}: ${e.message}${e.keyword ? ` (${e.keyword})` : ''}`,
+          message,
           file: timelineFile,
         });
       }

package/src/lib/task-store.mjs

@@ -0,0 +1,164 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { parseFrontmatter } from './frontmatter.mjs';
+
+// DW Document Schema + Index v1.0 (ADR-0017) — task half.
+// Mirrors goal-store.mjs / goals-index@v1: a committed manifest so external
+// adapters read task state from one O(1) file instead of reverse-engineering
+// every task.md.
+
+const TASKS_DIR = '.dw/tasks';
+const INDEX_FILE = '.dw/tasks/tasks-index.json';
+const SCHEMA_VERSION = 'tasks-index@v1';
+
+export function tasksDir(rootDir = process.cwd()) {
+  return join(rootDir, TASKS_DIR);
+}
+
+export function taskFile(taskId, rootDir = process.cwd()) {
+  return join(rootDir, TASKS_DIR, taskId, 'task.md');
+}
+
+export function taskIndexFile(rootDir = process.cwd()) {
+  return join(rootDir, INDEX_FILE);
+}
+
+function nowUtc() {
+  return new Date().toISOString().replace(/\.\d+Z$/, 'Z');
+}
+
+// Stable key order so the same task set always serializes byte-identically,
+// regardless of writer path (syncTaskIndexEntry appends; rebuildTaskIndex uses
+// readdirSync order, which is filesystem-dependent). Without this the two paths
+// disagree and the post-commit hook refresh churns the file (#21).
+function sortTasks(tasks) {
+  const sorted = {};
+  for (const id of Object.keys(tasks || {}).sort()) sorted[id] = tasks[id];
+  return sorted;
+}
+
+// schema_version naming (#22): task frontmatter accepts both the legacy bare
+// form (v3.0/v3.1) and the canonical namespaced form (task@v3.0/task@v3.1) that
+// matches the repo-wide @v convention (goal@v1, *-index@v1). New writes emit the
+// namespaced form; readers tolerate both. `bareSchemaVersion` strips the prefix
+// for version-comparison logic; `canonicalSchemaVersion` adds it for emission.
+export function bareSchemaVersion(v) {
+  if (!v || typeof v !== 'string') return v;
+  return v.startsWith('task@') ? v.slice('task@'.length) : v;
+}
+
+export function canonicalSchemaVersion(v) {
+  if (!v || typeof v !== 'string') return v;
+  return v.startsWith('task@') ? v : `task@${v}`;
+}
+
+function emptyIndex() {
+  return { schema_version: SCHEMA_VERSION, last_updated: nowUtc(), tasks: {} };
+}
+
+export function readTaskIndex(rootDir = process.cwd()) {
+  const file = taskIndexFile(rootDir);
+  if (!existsSync(file)) return emptyIndex();
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf8'));
+    if (!parsed || typeof parsed !== 'object' || !parsed.tasks) return emptyIndex();
+    return parsed;
+  } catch {
+    return emptyIndex();
+  }
+}
+
+export function writeTaskIndex(index, rootDir = process.cwd()) {
+  const file = taskIndexFile(rootDir);
+  const dir = dirname(file);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const tasks = sortTasks(index.tasks);
+  // Skip the write entirely when the task set is byte-identical to disk: this
+  // keeps the on-disk `last_updated` (the spec freshness signal, ADR-0017) and
+  // guarantees zero git diff. `last_updated` advances only on a real change.
+  const prior = readTaskIndex(rootDir);
+  if (existsSync(file) && JSON.stringify(sortTasks(prior.tasks)) === JSON.stringify(tasks)) {
+    return prior;
+  }
+  const updated = { schema_version: SCHEMA_VERSION, last_updated: nowUtc(), tasks };
+  writeFileSync(file, JSON.stringify(updated, null, 2) + '\n', 'utf8');
+  return updated;
+}
+
+export function listTaskIds(rootDir = process.cwd()) {
+  const dir = tasksDir(rootDir);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter((entry) => {
+    if (entry === 'archive' || entry === 'ACTIVE.md') return false;
+    try {
+      const path = join(dir, entry);
+      return statSync(path).isDirectory() && existsSync(join(path, 'task.md'));
+    } catch {
+      return false;
+    }
+  });
+}
+
+export function readTask(taskId, rootDir = process.cwd()) {
+  const file = taskFile(taskId, rootDir);
+  if (!existsSync(file)) return null;
+  const content = readFileSync(file, 'utf8');
+  return { fm: parseFrontmatter(content), content, file };
+}
+
+export function extractTaskTitle(content) {
+  const m = content.match(/^#\s+(?:Timeline:|Spec:)?\s*(.+?)\s*$/m);
+  return m ? m[1].trim() : null;
+}
+
+// doc@v1 task projection — consumer-facing fields only (no body text).
+function taskEntry(taskId, rootDir) {
+  const task = readTask(taskId, rootDir);
+  if (!task) return null;
+  const fm = task.fm || {};
+  return {
+    title: extractTaskTitle(task.content) || taskId,
+    status: fm.status || 'Draft',
+    phase: fm.phase || null,
+    owner: fm.owner || 'unknown',
+    depth: fm.depth || null,
+    related_adr: fm.related_adr || null,
+    target_ship: fm.target_ship || null,
+    parent_goal_id: fm.parent_goal_id && fm.parent_goal_id !== 'none' ? fm.parent_goal_id : null,
+    contributing_goal_ids: Array.isArray(fm.contributing_goal_ids) ? fm.contributing_goal_ids : [],
+    summary: fm.summary || null,
+    schema_version: fm.schema_version || null,
+    last_updated: fm.last_updated || new Date().toISOString().slice(0, 10),
+  };
+}
+
+export function syncTaskIndexEntry(taskId, rootDir = process.cwd()) {
+  const entry = taskEntry(taskId, rootDir);
+  if (!entry) return null;
+  const index = readTaskIndex(rootDir);
+  index.tasks[taskId] = entry;
+  writeTaskIndex(index, rootDir);
+  return entry;
+}
+
+export function removeTaskIndexEntry(taskId, rootDir = process.cwd()) {
+  const index = readTaskIndex(rootDir);
+  if (index.tasks[taskId]) {
+    delete index.tasks[taskId];
+    writeTaskIndex(index, rootDir);
+    return true;
+  }
+  return false;
+}
+
+// Authoritative full rebuild — scans .dw/tasks/ and rewrites the index.
+// Idempotency (sorted keys + skip-when-identical) lives in writeTaskIndex, so an
+// unchanged task set produces zero git diff and the stop-check refresh is safe.
+export function rebuildTaskIndex(rootDir = process.cwd()) {
+  const index = emptyIndex();
+  for (const taskId of listTaskIds(rootDir)) {
+    const entry = taskEntry(taskId, rootDir);
+    if (entry) index.tasks[taskId] = entry;
+  }
+  return writeTaskIndex(index, rootDir);
+}

package/src/lib/timeline-parser.mjs

@@ -29,29 +29,68 @@ export function parseTimeline(content) {
   };
 }
 
+// Header-driven so the column ORDER is not load-bearing (#24): the §3 tracker
+// may be `# | Subtask | Status | Date | Notes` (legacy) or
+// `# | Subtask | Acceptance | Est | Status | Notes` (current) — we read columns
+// by name. Falls back to legacy positional mapping when no header row is found,
+// so older / hand-written tables keep parsing.
+const TRACKER_COLS = {
+  id: ['#', 'id'],
+  name: ['subtask', 'task', 'name'],
+  status: ['status'],
+  date: ['date'],
+  notes: ['notes'],
+  acceptance: ['acceptance'],
+  est: ['est', 'estimate'],
+};
+const LEGACY_POS = { id: 0, name: 1, status: 2, date: 3, notes: 4 };
+
+function splitRow(line) {
+  // Drop the empty cells produced by the leading/trailing pipes.
+  return line.split('|').map((c) => c.trim()).filter((_, i, arr) => i > 0 && i < arr.length - 1);
+}
+
 export function parseSubtaskTracker(sectionText) {
   if (!sectionText) return [];
   const lines = sectionText.split('\n').map((l) => l.trim()).filter(Boolean);
+  let colMap = null; // canonical-name -> column index
   const rows = [];
-  let inTable = false;
   for (const line of lines) {
-    if (line.startsWith('|---') || line.match(/^\|[\s|:-]+\|$/)) { inTable = true; continue; }
-    if (!line.startsWith('|')) { inTable = false; continue; }
-    const cells = line.split('|').map((c) => c.trim()).filter((_, i, arr) => i > 0 && i < arr.length - 1);
+    if (!line.startsWith('|')) continue;
+    if (line.match(/^\|[\s|:-]+\|$/)) continue; // separator row
+    const cells = splitRow(line);
     if (cells.length < 2) continue;
-    if (!inTable && (cells[0].toLowerCase().startsWith('#') || cells[0].toLowerCase() === 'ws' || cells[0].toLowerCase() === 'st')) {
-      // header row
+
+    const low = cells.map((c) => c.toLowerCase());
+    // Header row: first cell is '#'/'id', or it names known columns. Detect once.
+    const looksLikeHeader = low[0] === '#' || low[0] === 'id'
+      || low.includes('status') || low.includes('subtask');
+    if (!colMap && looksLikeHeader) {
+      colMap = {};
+      for (const [canon, aliases] of Object.entries(TRACKER_COLS)) {
+        const idx = low.findIndex((c) => aliases.includes(c));
+        if (idx >= 0) colMap[canon] = idx;
+      }
       continue;
     }
-    if (cells.length >= 3) {
-      rows.push({
-        id: cells[0],
-        name: cells[1],
-        status: cells[2],
-        date: cells[3] || '',
-        notes: cells[4] || '',
-      });
-    }
+
+    // Data row. Skip stray non-subtask rows when using positional fallback.
+    if (!colMap && !/^(ST|WS)-/i.test(cells[0]) && !/^\d/.test(cells[0])) continue;
+    if (cells.length < 3 && !colMap) continue;
+
+    const get = (canon) => {
+      const idx = colMap ? colMap[canon] : LEGACY_POS[canon];
+      return idx != null && idx >= 0 ? (cells[idx] ?? '') : '';
+    };
+    rows.push({
+      id: get('id'),
+      name: get('name'),
+      status: get('status'),
+      date: get('date'),
+      notes: get('notes'),
+      acceptance: get('acceptance'),
+      est: get('est'),
+    });
   }
   return rows;
 }