tenbo-dashboard 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tenbo-dashboard",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Local-first architecture dashboard and CLI tools for .tenbo/ repos",
   "type": "module",
   "license": "MIT",
@@ -45,6 +45,7 @@
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/sortable": "^8.0.0",
     "@dnd-kit/utilities": "^3.2.2",
+    "@parcel/watcher": "^2.5.6",
     "@vitejs/plugin-react": "^4.3.1",
     "@xyflow/react": "^12.10.2",
     "chokidar": "^3.6.0",

package/src/App.tsx

@@ -25,7 +25,7 @@ type Overlay =
   | null;
 
 export default function App() {
-  const { state, loadError, reload, generation } = useTenboState();
+  const { state, loadError, reload, mergeItem, generation } = useTenboState();
   const patch = useApiPatch();
   const { route, navigate } = useHashRoute();
 
@@ -60,8 +60,12 @@ export default function App() {
     else navigate({ kind: 'docs-project', tab: 'overview' });
   };
 
+  // After PATCH the server returns the canonical item; merge into local
+  // state immediately rather than waiting for the SSE-triggered full reload
+  // (the SSE echo is filtered by origin token in useTenboState). td-005.
   const handlePatch = async (scopeId: string, itemId: string, p: Partial<Item>) => {
-    await patch(scopeId, itemId, p);
+    const updated = await patch(scopeId, itemId, p);
+    mergeItem(scopeId, updated);
   };
 
   const body = (() => {
@@ -124,12 +128,20 @@ export default function App() {
           relatedDocs={related}
           state={state}
           onClose={() => setOverlay(null)}
-          onPatch={async (p) => { await patch(overlay.scopeId, overlay.item.id, p); }}
+          onPatch={async (p) => {
+            const updated = await patch(overlay.scopeId, overlay.item.id, p);
+            mergeItem(overlay.scopeId, updated);
+            // Refresh the overlay's snapshot of the item so subsequent edits
+            // (and the "keep overlay in sync" effect above) see the latest.
+            setOverlay({ kind: 'modal', scopeId: overlay.scopeId, item: updated });
+          }}
           onOpenFile={(path) => { tenboApi.openFile(path).catch(() => {}); }}
           onPromoteRelated={async (path) => {
             const cur = overlay.item.links ?? [];
             if (!cur.includes(path)) {
-              await patch(overlay.scopeId, overlay.item.id, { links: [...cur, path] });
+              const updated = await patch(overlay.scopeId, overlay.item.id, { links: [...cur, path] });
+              mergeItem(overlay.scopeId, updated);
+              setOverlay({ kind: 'modal', scopeId: overlay.scopeId, item: updated });
             }
           }}
           onSelectItem={(sId, it) => {

package/src/api/client.ts

@@ -1,5 +1,18 @@
 import type { TenboState, RelatedDoc, Item, LayerDoc } from '../types';
 
+/**
+ * Per-instance origin token. Sent with every PATCH so the server can attach it
+ * to the resulting SSE echo, which the SSE handler in useTenboState filters out
+ * (we already merged the change locally from the PATCH response — no need to
+ * trigger a redundant full reload). See td-005.
+ */
+export const TENBO_ORIGIN = (() => {
+  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+    return crypto.randomUUID();
+  }
+  return `o-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+})();
+
 async function http<T>(url: string, init?: RequestInit): Promise<T> {
   const r = await fetch(url, init);
   if (!r.ok) throw new Error(`${init?.method ?? 'GET'} ${url} -> ${r.status}`);
@@ -13,10 +26,13 @@ export const tenboApi = {
   getRelated(): Promise<RelatedDoc[]> {
     return http('/api/related');
   },
-  patchItem(scopeId: string, itemId: string, patch: Partial<Item>): Promise<{ ok: true }> {
+  patchItem(scopeId: string, itemId: string, patch: Partial<Item>): Promise<{ ok: true; item: Item }> {
     return http(`/api/items/${itemId}`, {
       method: 'PATCH',
-      headers: { 'Content-Type': 'application/json' },
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Tenbo-Origin': TENBO_ORIGIN,
+      },
       body: JSON.stringify({ scope: scopeId, patch }),
     });
   },

package/src/api/lib/parseCache.test.ts

@@ -0,0 +1,96 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { getCached, invalidate, clearCache } from './parseCache';
+
+describe('parseCache', () => {
+  let dir: string;
+  let file: string;
+  let parseCount: number;
+
+  beforeEach(() => {
+    dir = mkdtempSync(path.join(tmpdir(), 'tenbo-parsecache-'));
+    file = path.join(dir, 'sample.txt');
+    parseCount = 0;
+    clearCache();
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  function counter(s: string): { value: string } {
+    parseCount += 1;
+    return { value: s.trim() };
+  }
+
+  it('parses on first call, returns cached result on second', () => {
+    writeFileSync(file, 'hello');
+    const a = getCached(file, 'txt', counter);
+    const b = getCached(file, 'txt', counter);
+    expect(a.value).toBe('hello');
+    expect(b).toBe(a);
+    expect(parseCount).toBe(1);
+  });
+
+  it('re-parses when file content changes', () => {
+    writeFileSync(file, 'first');
+    const first = getCached(file, 'txt', counter);
+    expect(first.value).toBe('first');
+
+    // Force a future mtime so the fast-path re-checks the hash.
+    const future = Date.now() / 1000 + 5;
+    writeFileSync(file, 'second');
+    require('node:fs').utimesSync(file, future, future);
+
+    const second = getCached(file, 'txt', counter);
+    expect(second.value).toBe('second');
+    expect(parseCount).toBe(2);
+  });
+
+  it('keeps separate cache slots per signature', () => {
+    writeFileSync(file, 'shared');
+    getCached(file, 'parser-a', counter);
+    getCached(file, 'parser-b', counter);
+    expect(parseCount).toBe(2);
+  });
+
+  it('invalidate(path) drops cache entries for that path', () => {
+    writeFileSync(file, 'hello');
+    getCached(file, 'txt', counter);
+    invalidate(file);
+    getCached(file, 'txt', counter);
+    expect(parseCount).toBe(2);
+  });
+
+  it('serves stale on transient parse failure (does not poison cache)', () => {
+    writeFileSync(file, 'good');
+    const ok = getCached(file, 'txt', (s) => {
+      if (s === 'BAD') throw new Error('parse failed');
+      return { value: s };
+    });
+    expect(ok.value).toBe('good');
+
+    // Force a re-read by bumping mtime; parser will throw on the new content.
+    const future = Date.now() / 1000 + 5;
+    writeFileSync(file, 'BAD');
+    require('node:fs').utimesSync(file, future, future);
+
+    const stillOk = getCached(file, 'txt', (s) => {
+      if (s === 'BAD') throw new Error('parse failed');
+      return { value: s };
+    });
+    expect(stillOk.value).toBe('good'); // returned the previous good value
+  });
+
+  it('throws on first-ever parse failure (no previous good value to fall back to)', () => {
+    writeFileSync(file, 'BAD');
+    expect(() => {
+      getCached(file, 'txt', (s) => {
+        if (s === 'BAD') throw new Error('parse failed');
+        return { value: s };
+      });
+    }).toThrow('parse failed');
+  });
+});

package/src/api/lib/parseCache.ts

@@ -0,0 +1,103 @@
+/**
+ * parseCache.ts — content-hash-keyed memoized file parser.
+ *
+ * Reads a file, hashes its bytes, and returns the parsed result. Subsequent
+ * calls for the same path with the same content return the cached parsed
+ * value without re-reading or re-parsing. When the content changes (any
+ * write through tenboFs, any external editor save), the next call detects
+ * the new hash, re-parses, and caches the new value.
+ *
+ * Why content hash, not just mtime: HFS+ has 1-second mtime resolution, so
+ * two writes within the same second look identical to mtime. Hashing the
+ * bytes is unambiguous.
+ *
+ * Partial-write race handling: a read that catches a YAML/JSON file
+ * mid-write may produce a parse error. The cache retains the previous good
+ * value on transient parse failure (the next read will succeed). Persistent
+ * failures bubble up to the caller on the SECOND attempt; the cache does
+ * not silently mask broken files indefinitely.
+ *
+ * The file watcher (`watch.ts`) also calls `invalidate(absPath)` on file
+ * change events so cache freshness doesn't depend on read frequency.
+ *
+ * Used by tenboFs.ts for the YAML reads that feed `readState` — by far the
+ * hottest read path. Other helpers (markdown narratives, layer content)
+ * could be added if perf measurement justifies it.
+ */
+
+import { readFileSync, statSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+
+interface CacheEntry<T> {
+  hash: string;
+  parsed: T;
+  /** mtime at the time of cache fill — used as a cheap pre-check to skip the hash. */
+  mtimeMs: number;
+}
+
+const cache = new Map<string, CacheEntry<unknown>>();
+
+function safeMtime(absPath: string): number {
+  try { return statSync(absPath).mtimeMs; } catch { return -1; }
+}
+
+function hashBytes(buf: Buffer): string {
+  return createHash('sha1').update(buf).digest('hex');
+}
+
+/**
+ * Read+parse `absPath` with caching. `parser` is called only when the file's
+ * content has changed since the last successful parse.
+ *
+ * `signature` is a short string identifying the parser variant — different
+ * parsers (raw text vs YAML vs JSON) for the same path get separate cache
+ * slots so callers can use the cache for both shapes without collision.
+ */
+export function getCached<T>(absPath: string, signature: string, parser: (text: string) => T): T {
+  const key = `${signature}::${absPath}`;
+  const mtime = safeMtime(absPath);
+
+  const existing = cache.get(key) as CacheEntry<T> | undefined;
+  // mtime fast-path: if the file's mtime hasn't moved AND we have a cached
+  // entry, we can skip re-reading. This is the common case during a single
+  // request that touches the same file twice.
+  if (existing && existing.mtimeMs === mtime && mtime !== -1) {
+    return existing.parsed;
+  }
+
+  // mtime changed (or no cache entry). Read + hash + maybe re-parse.
+  const buf = readFileSync(absPath);
+  const hash = hashBytes(buf);
+
+  if (existing && existing.hash === hash) {
+    // Content actually unchanged (mtime moved without content change — common
+    // when an editor "touches" a file or after `touch -m`). Refresh the
+    // mtime in the entry so the fast-path catches the next read.
+    existing.mtimeMs = mtime;
+    return existing.parsed;
+  }
+
+  // Re-parse. On parse error, retain previous good value (transient
+  // partial-write race). The caller can re-attempt; if it fails twice the
+  // exception propagates so we don't mask persistent corruption.
+  try {
+    const parsed = parser(buf.toString('utf8'));
+    cache.set(key, { hash, parsed, mtimeMs: mtime });
+    return parsed;
+  } catch (err) {
+    if (existing) return existing.parsed; // serve stale on transient failure
+    throw err;
+  }
+}
+
+/** Drop a cached entry. Called by the file watcher on change events. */
+export function invalidate(absPath: string): void {
+  for (const k of cache.keys()) {
+    if (k.endsWith(`::${absPath}`)) cache.delete(k);
+  }
+}
+
+/** For tests — clear everything. */
+export function clearCache(): void {
+  cache.clear();
+}

package/src/api/lib/phases.test.ts

@@ -29,6 +29,20 @@ describe('derivePhaseStatus', () => {
   it('returns later for an empty list', () => {
     expect(derivePhaseStatus([])).toBe('later');
   });
+
+  it('returns dropped when every phase is dropped', () => {
+    expect(derivePhaseStatus([ph(1, 'dropped'), ph(2, 'dropped')])).toBe('dropped');
+  });
+
+  it('returns done when phases mix done and dropped (work shipped, rest abandoned)', () => {
+    expect(derivePhaseStatus([ph(1, 'done'), ph(2, 'dropped')])).toBe('done');
+    expect(derivePhaseStatus([ph(1, 'done'), ph(2, 'done'), ph(3, 'dropped')])).toBe('done');
+  });
+
+  it('still treats a now/next phase as active even if other phases are dropped', () => {
+    expect(derivePhaseStatus([ph(1, 'done'), ph(2, 'now'), ph(3, 'dropped')])).toBe('now');
+    expect(derivePhaseStatus([ph(1, 'done'), ph(2, 'next'), ph(3, 'dropped')])).toBe('next');
+  });
 });
 
 describe('effectiveStatus', () => {

package/src/api/lib/phases.ts

@@ -2,17 +2,23 @@
  * Shared helpers for the optional `phases:` field on roadmap items.
  *
  * Roll-up rule (single source of truth, mirrored in the validator and the viewer):
- *   - `done`  if every phase has status `done`
- *   - `now`   if any phase has status `now`
+ *   - `dropped` if every phase has status `dropped`
+ *   - `done`    if every phase has status `done` OR every phase is in {done, dropped} and at least one is `done`
+ *   - `now`     if any phase has status `now`
  *   - else `next`  if any phase has status `next`
  *   - else `later`
  *
+ * `dropped` phases are skipped during rollup (they don't count toward done/later)
+ * the way they don't count toward in-flight or pending — they're explicit
+ * acknowledgements that work won't be completed. An item where one phase shipped
+ * and one was dropped is conceptually `done`.
+ *
  * Items without `phases:` are unaffected — their explicit `status:` is the source
  * of truth.
  */
 import type { Item, Phase, Status } from '../../types';
 
-export const VALID_PHASE_STATUSES: ReadonlySet<Status> = new Set(['now', 'next', 'later', 'done']);
+export const VALID_PHASE_STATUSES: ReadonlySet<Status> = new Set(['now', 'next', 'later', 'done', 'dropped']);
 
 /** YYYY-MM-DD shape check. Does not validate calendar correctness. */
 export function isIsoDate(s: string): boolean {
@@ -22,7 +28,8 @@ export function isIsoDate(s: string): boolean {
 /** Compute a derived item status from a non-empty phase list. */
 export function derivePhaseStatus(phases: Phase[]): Status {
   if (phases.length === 0) return 'later';
-  if (phases.every((p) => p.status === 'done')) return 'done';
+  if (phases.every((p) => p.status === 'dropped')) return 'dropped';
+  if (phases.every((p) => p.status === 'done' || p.status === 'dropped')) return 'done';
   if (phases.some((p) => p.status === 'now')) return 'now';
   if (phases.some((p) => p.status === 'next')) return 'next';
   return 'later';

package/src/api/lib/priority.test.ts

@@ -0,0 +1,56 @@
+import { describe, it, expect } from 'vitest';
+import { sortByPriority, comparePriority } from './priority';
+import type { Item, Priority } from '../../types';
+
+const item = (id: string, priority?: Priority): Item =>
+  ({ id, title: id, status: 'now', description: '' } as Item) as any && (
+    { id, title: id, status: 'now', description: '', priority } as unknown as Item
+  );
+
+describe('sortByPriority', () => {
+  it('orders p0 → p1 → p2 → p3 → unset', () => {
+    const input = [
+      item('a', 'p3'),
+      item('b'),
+      item('c', 'p0'),
+      item('d', 'p2'),
+      item('e', 'p1'),
+    ];
+    const sorted = sortByPriority(input).map(i => i.id);
+    expect(sorted).toEqual(['c', 'e', 'd', 'a', 'b']);
+  });
+
+  it('preserves file order on ties (stable sort)', () => {
+    const input = [
+      item('first', 'p2'),
+      item('second', 'p2'),
+      item('third', 'p2'),
+      item('zeroth', 'p0'),
+    ];
+    const sorted = sortByPriority(input).map(i => i.id);
+    expect(sorted).toEqual(['zeroth', 'first', 'second', 'third']);
+  });
+
+  it('returns a new array (does not mutate input)', () => {
+    const input = [item('a', 'p3'), item('b', 'p0')];
+    const inputCopy = [...input];
+    sortByPriority(input);
+    expect(input).toEqual(inputCopy);
+  });
+});
+
+describe('comparePriority', () => {
+  it('returns negative when first has higher priority', () => {
+    expect(comparePriority(item('a', 'p0'), item('b', 'p3'))).toBeLessThan(0);
+  });
+  it('returns positive when second has higher priority', () => {
+    expect(comparePriority(item('a', 'p3'), item('b', 'p0'))).toBeGreaterThan(0);
+  });
+  it('returns 0 on equal priority (file-order tiebreaker)', () => {
+    expect(comparePriority(item('a', 'p2'), item('b', 'p2'))).toBe(0);
+  });
+  it('treats unset as the lowest priority', () => {
+    expect(comparePriority(item('a'), item('b', 'p3'))).toBeGreaterThan(0);
+    expect(comparePriority(item('a', 'p0'), item('b'))).toBeLessThan(0);
+  });
+});

package/src/api/lib/priority.ts

@@ -0,0 +1,37 @@
+/**
+ * priority.ts — sort comparator for roadmap items by priority.
+ *
+ * Order: p0 (highest) → p1 → p2 → p3 → unset (last). Equal priorities keep
+ * their original file-order via Array.sort's ES2019 stable-sort guarantee.
+ *
+ * Used by both KanbanColumn and TaskList so the kanban + list views share
+ * the same priority-first ordering. (td-009)
+ *
+ * Note: drag-reorder still modifies roadmap.yaml file order; the priority
+ * sort applies as a presentational layer on top. Items with identical
+ * priority will follow whatever file order the user dragged them into.
+ */
+
+import type { Item, Priority } from '../../types';
+
+const RANK: Record<Priority | 'unset', number> = {
+  p0: 0,
+  p1: 1,
+  p2: 2,
+  p3: 3,
+  unset: 4,
+};
+
+function rank(item: Item): number {
+  return RANK[item.priority ?? 'unset'];
+}
+
+/** Compare two items by priority (lower rank wins). Stable on equal priorities. */
+export function comparePriority(a: Item, b: Item): number {
+  return rank(a) - rank(b);
+}
+
+/** Return a copy of `items` sorted by priority (file order preserved on ties). */
+export function sortByPriority<T extends Item>(items: T[]): T[] {
+  return [...items].sort(comparePriority);
+}

package/src/api/lib/recentWrites.ts

@@ -0,0 +1,48 @@
+/**
+ * recentWrites.ts — short-lived registry of writes the server just made,
+ * keyed by absolute file path with their originating client token.
+ *
+ * Used for SSE echo suppression (td-005): when a chokidar event fires for
+ * a path the server just wrote, the watch route checks this registry; if
+ * the path matches a recent write, the SSE payload includes the originating
+ * client's token. Clients then filter out events carrying their own token,
+ * since they've already merged the change locally from the PATCH response.
+ *
+ * Entries auto-expire after RECENT_WRITE_TTL_MS to bound memory and avoid
+ * stale matches against later external writes to the same path.
+ */
+
+const RECENT_WRITE_TTL_MS = 1000;
+
+interface RecentWrite {
+  origin: string | null;
+  ts: number;
+}
+
+const recent = new Map<string, RecentWrite>();
+
+/** Record a write to `absPath` originating from `origin` (null = unknown source). */
+export function recordRecentWrite(absPath: string, origin: string | null): void {
+  recent.set(absPath, { origin, ts: Date.now() });
+  // Schedule cleanup so the map doesn't grow unbounded across a long session.
+  setTimeout(() => {
+    const cur = recent.get(absPath);
+    if (cur && Date.now() - cur.ts >= RECENT_WRITE_TTL_MS) {
+      recent.delete(absPath);
+    }
+  }, RECENT_WRITE_TTL_MS + 50);
+}
+
+/**
+ * If `absPath` was written within the TTL window by a known origin, return
+ * that origin token. Otherwise null (treat as external/unknown change).
+ */
+export function getRecentOrigin(absPath: string): string | null {
+  const cur = recent.get(absPath);
+  if (!cur) return null;
+  if (Date.now() - cur.ts >= RECENT_WRITE_TTL_MS) {
+    recent.delete(absPath);
+    return null;
+  }
+  return cur.origin;
+}

package/src/api/lib/tenboFs.ts

@@ -2,6 +2,7 @@ import { readFileSync, writeFileSync, readdirSync, existsSync, renameSync, statS
 import path from 'node:path';
 import { parse as parseSimple } from 'yaml';
 import { parseYaml, stringifyYaml, patchSeqItem, reorderSeqItems } from './yamlOrdered';
+import { getCached, invalidate as invalidateCache } from './parseCache';
 import type { TenboState, Scope, Item, Layer, CrossCutting, LayerDocs, ScopeMetrics, WorkspaceContent, LayerContent } from '../../types';
 
 function tenboDir(repoRoot: string) { return path.join(repoRoot, '.tenbo'); }
@@ -47,8 +48,10 @@ export function tenboExists(repoRoot: string): boolean {
 }
 
 export function readWorkspace(repoRoot: string): { scopeRefs: { id: string; path: string; description: string }[]; crossCutting: CrossCutting[] } {
-  const text = readFileSync(path.join(tenboDir(repoRoot), 'workspace.yaml'), 'utf8');
-  const data = parseSimple(text) as any;
+  // Cached parse — re-reads only when workspace.yaml content changes.
+  // See parseCache.ts for the content-hash + transient-failure semantics.
+  const file = path.join(tenboDir(repoRoot), 'workspace.yaml');
+  const data = getCached(file, 'workspace-yaml', (text) => parseSimple(text) as any);
   return {
     scopeRefs: data?.scopes ?? [],
     crossCutting: data?.cross_cutting ?? [],
@@ -56,14 +59,14 @@ export function readWorkspace(repoRoot: string): { scopeRefs: { id: string; path
 }
 
 function readArchitecture(repoRoot: string, scopeId: string): Layer[] {
-  const text = readFileSync(path.join(tenboDir(repoRoot), 'scopes', scopeId, 'architecture.yaml'), 'utf8');
-  const data = parseSimple(text) as any;
+  const file = path.join(tenboDir(repoRoot), 'scopes', scopeId, 'architecture.yaml');
+  const data = getCached(file, 'architecture-yaml', (text) => parseSimple(text) as any);
   return data?.layers ?? [];
 }
 
 function readRoadmap(repoRoot: string, scopeId: string): Item[] {
-  const text = readFileSync(path.join(tenboDir(repoRoot), 'scopes', scopeId, 'roadmap.yaml'), 'utf8');
-  const data = parseSimple(text) as any;
+  const file = path.join(tenboDir(repoRoot), 'scopes', scopeId, 'roadmap.yaml');
+  const data = getCached(file, 'roadmap-yaml', (text) => parseSimple(text) as any);
   return data?.items ?? [];
 }
 
@@ -218,6 +221,10 @@ function atomicWrite(filePath: string, content: string): void {
   const tmp = `${filePath}.tmp.${process.pid}.${Date.now()}`;
   writeFileSync(tmp, content, 'utf8');
   renameSync(tmp, filePath);
+  // Drop any cached parse for this path. The next read will re-parse from
+  // disk; the file watcher's invalidate will cover external edits, this
+  // covers our own writes (no race with the SSE event arriving "later").
+  invalidateCache(filePath);
 }
 
 export function patchItem(repoRoot: string, scopeId: string, itemId: string, patch: Partial<Item>): void {

package/src/api/lib/validator.ts

@@ -8,7 +8,7 @@ const FORBIDDEN_JARGON = [
   'worker', 'daemon',
 ];
 
-const VALID_STATUSES = new Set(['now', 'next', 'later', 'done']);
+const VALID_STATUSES = new Set(['now', 'next', 'later', 'done', 'dropped']);
 const VALID_PRIORITIES = new Set(['p0', 'p1', 'p2', 'p3']);
 const ITEM_ID_RE = /^[a-z]{1,5}-\d{3,}$/;
 const DOC_UPDATE_REQUIRED_TYPES = new Set(['feature', 'refactor', 'bug']);

package/src/api/plugin.ts

@@ -23,7 +23,9 @@ export function tenboApiPlugin(): Plugin {
       server.middlewares.use(reorderRoute(repoRoot));
       server.middlewares.use(relatedRoute(repoRoot));
       server.middlewares.use(openRoute(repoRoot));
-      server.middlewares.use(watchRoute(repoRoot));
+      const watch = watchRoute(repoRoot);
+      server.middlewares.use(watch.handler);
+      server.httpServer?.on('close', () => { void watch.close(); });
       server.middlewares.use(layerDocsRoute(repoRoot));
       server.middlewares.use(layerContentRoute(repoRoot));
     },

package/src/api/routes/items.ts

@@ -1,8 +1,10 @@
 import type { Connect } from 'vite';
-import { patchItem } from '../lib/tenboFs';
+import path from 'node:path';
+import { patchItem, readState } from '../lib/tenboFs';
+import { recordRecentWrite } from '../lib/recentWrites';
 import { readBody, json, error, withErrorHandling } from '../lib/http';
 
-const ALLOWED = new Set(['title', 'description', 'status', 'layer', 'notes', 'links', 'priority', 'done_when', 'files_to_read', 'risks']);
+const ALLOWED = new Set(['title', 'description', 'status', 'layer', 'notes', 'links', 'priority', 'done_when', 'files_to_read', 'risks', 'phases']);
 
 export function itemsRoute(repoRoot: string): Connect.NextHandleFunction {
   return withErrorHandling(async (req, res, next) => {
@@ -19,7 +21,26 @@ export function itemsRoute(repoRoot: string): Connect.NextHandleFunction {
     for (const k of Object.keys(patch)) {
       if (ALLOWED.has(k)) filtered[k] = patch[k];
     }
+
+    // Record the originating client token so the SSE channel can suppress
+    // the echo back to that client (td-005 step 3 — echo suppression).
+    // Clients send X-Tenbo-Origin as a per-instance UUID generated at boot.
+    const origin = (req.headers['x-tenbo-origin'] as string | undefined) ?? null;
+    const filePath = path.join(repoRoot, '.tenbo', 'scopes', scopeId, 'roadmap.yaml');
+    recordRecentWrite(filePath, origin);
+
     patchItem(repoRoot, scopeId, itemId, filtered);
-    json(res, { ok: true });
+
+    // Re-read state and return the canonical post-write item so the client
+    // can merge into its local state immediately (td-005 step 1+2 —
+    // optimistic UI without waiting for SSE). Falls through to a 404 if
+    // the item somehow disappeared during the write (concurrent delete).
+    const state = readState(repoRoot);
+    const scope = state.scopes.find((s) => s.id === scopeId);
+    const item = scope?.items.find((i) => i.id === itemId);
+    if (!item) {
+      return error(res, 404, `item ${itemId} not found in scope ${scopeId} after patch`);
+    }
+    json(res, { ok: true, item });
   });
 }

package/src/api/routes/watch.ts

@@ -1,24 +1,154 @@
 import type { Connect } from 'vite';
-import chokidar from 'chokidar';
+import watcher, { type AsyncSubscription, type Event as WatcherEvent } from '@parcel/watcher';
 import path from 'node:path';
+import fs from 'node:fs';
+import { parse as parseYaml } from 'yaml';
+import { getRecentOrigin } from '../lib/recentWrites';
+import { invalidate as invalidateParseCache } from '../lib/parseCache';
+import type { Item } from '../../types';
 
-export function watchRoute(repoRoot: string): Connect.NextHandleFunction {
-  // One watcher per process; multiple SSE clients share it.
-  const watchPath = path.join(repoRoot, '.tenbo');
+/**
+ * SSE channel — server-pushed events the dashboard subscribes to.
+ *
+ * Two event kinds (td-006, item-level events — Q2=b):
+ *
+ *   {kind: 'roadmap-change', scopeId, items, origin?}
+ *     Fires when a `.tenbo/scopes/<scope>/roadmap.yaml` changes. The full
+ *     post-change items list for that scope is included in the payload —
+ *     the client replaces its local items[] for that scope without a full
+ *     state refetch. Lightest payload that still scales beyond ~100 items.
+ *
+ *   {kind: 'file-change', event, path, origin?}
+ *     Fires for non-roadmap changes (architecture.yaml, narratives,
+ *     workspace files, principles.md, glossary.md, /docs/superpowers/, etc).
+ *     Client triggers its existing debounced full reload — these are rare
+ *     and structural; per-file diffs aren't worth the protocol surface yet.
+ *
+ * Both event types include `origin` when the write was made by a known
+ * client (set via X-Tenbo-Origin header on the originating PATCH); the
+ * client filters echoes of its own writes — see useTenboState.
+ *
+ * File watching uses @parcel/watcher (native FSEvents/inotify directly) —
+ * faster and more reliable than chokidar at scale, with proper atomic-write
+ * handling. Editor swap files are filtered via the ignore globs below.
+ */
+
+// Editor swap-file patterns that should never trigger SSE events.
+const IGNORE_GLOBS = [
+  '**/*.swp',     // vim
+  '**/*.swo',     // vim
+  '**/*.swx',     // vim
+  '**/*~',        // many editors' backup
+  '**/4913',      // vim's pre-write probe
+  '**/.DS_Store', // macOS
+  '**/.git/**',
+  '**/node_modules/**',
+];
+
+interface RoadmapSnapshot {
+  // Per-scope items snapshot keyed by absolute roadmap.yaml path. Used to
+  // serve the latest items[] in `roadmap-change` events without re-reading
+  // on every SSE client subscribe.
+  itemsByPath: Map<string, Item[]>;
+}
+
+function isRoadmapFile(absPath: string, repoRoot: string): { isRoadmap: true; scopeId: string } | { isRoadmap: false } {
+  const tenboScopes = path.join(repoRoot, '.tenbo', 'scopes');
+  if (!absPath.startsWith(tenboScopes + path.sep)) return { isRoadmap: false };
+  if (path.basename(absPath) !== 'roadmap.yaml') return { isRoadmap: false };
+  const rel = absPath.slice(tenboScopes.length + 1);
+  const parts = rel.split(path.sep);
+  if (parts.length !== 2) return { isRoadmap: false }; // expect <scope>/roadmap.yaml
+  return { isRoadmap: true, scopeId: parts[0] };
+}
+
+function readRoadmapItems(absPath: string): Item[] {
+  try {
+    const text = fs.readFileSync(absPath, 'utf8');
+    const doc = parseYaml(text);
+    const items = (doc?.items as Item[]) ?? [];
+    return items;
+  } catch {
+    // Partial-write race or YAML error — skip emitting; client falls back
+    // to debounced full reload via the file-change path.
+    return [];
+  }
+}
+
+export function watchRoute(repoRoot: string): { handler: Connect.NextHandleFunction; close: () => Promise<void> } {
+  const tenboPath = path.join(repoRoot, '.tenbo');
   const docsPath = path.join(repoRoot, 'docs/superpowers');
-  const watcher = chokidar.watch([watchPath, docsPath], {
-    ignoreInitial: true,
-    awaitWriteFinish: { stabilityThreshold: 100, pollInterval: 50 },
-  });
+
+  const snapshot: RoadmapSnapshot = { itemsByPath: new Map() };
 
   type Client = { write: (data: string) => void; end: () => void };
   const clients = new Set<Client>();
-  watcher.on('all', (event, file) => {
-    const payload = `data: ${JSON.stringify({ event, path: path.relative(repoRoot, file) })}\n\n`;
-    for (const c of clients) c.write(payload);
-  });
 
-  return (req, res, next) => {
+  function broadcast(payload: object) {
+    const line = `data: ${JSON.stringify(payload)}\n\n`;
+    for (const c of clients) c.write(line);
+  }
+
+  function emitRoadmapChange(absPath: string, scopeId: string, originHint: string | null) {
+    const items = readRoadmapItems(absPath);
+    snapshot.itemsByPath.set(absPath, items);
+    broadcast({
+      kind: 'roadmap-change',
+      scopeId,
+      items,
+      origin: originHint,
+    });
+  }
+
+  function emitFileChange(absPath: string, type: WatcherEvent['type'], originHint: string | null) {
+    broadcast({
+      kind: 'file-change',
+      event: type, // 'create' | 'update' | 'delete'
+      path: path.relative(repoRoot, absPath),
+      origin: originHint,
+    });
+  }
+
+  function handleEvent(absPath: string, type: WatcherEvent['type']) {
+    // External writes (and our own atomic-rename writes) invalidate the
+    // parsed-file cache so the next read picks up the change.
+    invalidateParseCache(absPath);
+    const origin = getRecentOrigin(absPath);
+    const cls = isRoadmapFile(absPath, repoRoot);
+    if (cls.isRoadmap) {
+      // For deletions, the file may be gone; still emit so the client knows
+      // to clear (or the next full reload picks it up).
+      if (type === 'delete') {
+        snapshot.itemsByPath.delete(absPath);
+        broadcast({ kind: 'roadmap-change', scopeId: cls.scopeId, items: [], origin });
+        return;
+      }
+      emitRoadmapChange(absPath, cls.scopeId, origin);
+    } else {
+      emitFileChange(absPath, type, origin);
+    }
+  }
+
+  // Subscribe to each watch root. @parcel/watcher takes one path per call.
+  const subscriptions: AsyncSubscription[] = [];
+  async function subscribeIfExists(p: string) {
+    try {
+      if (!fs.existsSync(p)) return;
+      const sub = await watcher.subscribe(p, (err, events) => {
+        if (err) return; // best-effort — file watcher errors shouldn't crash the dev server
+        for (const ev of events) handleEvent(ev.path, ev.type);
+      }, { ignore: IGNORE_GLOBS });
+      subscriptions.push(sub);
+    } catch {
+      // Native binary not available for this platform / permissions — degrade gracefully.
+      // (Calls fall through; SSE just won't fire on file changes.)
+    }
+  }
+  // Fire-and-forget; subscribe happens async at startup.
+  void subscribeIfExists(tenboPath);
+  void subscribeIfExists(docsPath);
+
+  const handler: Connect.NextHandleFunction = (req, res, next) => {
     if (req.method !== 'GET' || req.url !== '/api/watch') return next();
     res.setHeader('Content-Type', 'text/event-stream');
     res.setHeader('Cache-Control', 'no-cache');
@@ -28,4 +158,10 @@ export function watchRoute(repoRoot: string): Connect.NextHandleFunction {
     clients.add(client);
     req.on('close', () => clients.delete(client));
   };
+
+  async function close() {
+    await Promise.all(subscriptions.map((s) => s.unsubscribe().catch(() => {})));
+  }
+
+  return { handler, close };
 }

package/src/hooks/useTenboState.ts

@@ -1,6 +1,6 @@
 import { useEffect, useState, useCallback, useRef } from 'react';
-import type { TenboState } from '../types';
-import { tenboApi } from '../api/client';
+import type { TenboState, Item } from '../types';
+import { tenboApi, TENBO_ORIGIN } from '../api/client';
 
 export function useTenboState() {
   const [state, setState] = useState<TenboState | null>(null);
@@ -18,18 +18,79 @@ export function useTenboState() {
     }
   }, []);
 
+  /**
+   * Merge a single canonical item into local state without a full reload.
+   * Used after a PATCH response — the server has already written, returned
+   * the canonical item shape, and our SSE handler will skip the echo for
+   * this client's own origin token. The visible state updates within a
+   * single React frame instead of waiting ~250ms for the SSE round-trip.
+   * See td-005.
+   */
+  const mergeItem = useCallback((scopeId: string, item: Item) => {
+    setState(prev => {
+      if (!prev) return prev;
+      return {
+        ...prev,
+        scopes: prev.scopes.map(s =>
+          s.id !== scopeId
+            ? s
+            : { ...s, items: s.items.map(i => (i.id === item.id ? item : i)) },
+        ),
+      };
+    });
+    // Bump generation so memoized derivations invalidate (kanban groupings,
+    // priority sort, etc.) just as they would after a full reload.
+    setGeneration(n => n + 1);
+  }, []);
+
   useEffect(() => { reload(); }, [reload]);
 
-  // SSE: debounced reload on any file change
+  /**
+   * Replace all items for a single scope without a full state reload.
+   * Used when SSE delivers a `roadmap-change` event (td-006 — item-level
+   * events) carrying the new items list. The rest of the state graph
+   * (scopes, layers, narratives, metrics) is unchanged for roadmap edits,
+   * so we don't refetch any of it.
+   */
+  const replaceScopeItems = useCallback((scopeId: string, items: Item[]) => {
+    setState(prev => {
+      if (!prev) return prev;
+      return {
+        ...prev,
+        scopes: prev.scopes.map(s =>
+          s.id !== scopeId ? s : { ...s, items },
+        ),
+      };
+    });
+    setGeneration(n => n + 1);
+  }, []);
+
+  // SSE handler. Three event kinds, in increasing cost:
+  //   - `roadmap-change`: replace one scope's items[]; no fetch.
+  //   - `file-change` for non-roadmap files: debounced full reload (rare).
+  //   - Echo of our own write (origin matches): ignored entirely.
   useEffect(() => {
     const es = new EventSource('/api/watch');
-    es.onmessage = () => {
+    es.onmessage = (e) => {
+      let data: { kind?: string; scopeId?: string; items?: Item[]; origin?: string | null } | null = null;
+      try {
+        data = JSON.parse(e.data);
+      } catch { /* malformed — fall through and reload as a safety net */ }
+
+      if (data?.origin && data.origin === TENBO_ORIGIN) return; // own write — already merged
+
+      if (data?.kind === 'roadmap-change' && data.scopeId && Array.isArray(data.items)) {
+        replaceScopeItems(data.scopeId, data.items);
+        return;
+      }
+
+      // file-change (non-roadmap) or unknown shape: fall back to debounced full reload.
       if (reloadDebounce.current) window.clearTimeout(reloadDebounce.current);
       reloadDebounce.current = window.setTimeout(() => { reload(); }, 250);
     };
     es.onerror = () => { /* browser auto-reconnects */ };
     return () => es.close();
-  }, [reload]);
+  }, [reload, replaceScopeItems]);
 
-  return { state, loadError, reload, generation };
+  return { state, loadError, reload, mergeItem, generation };
 }

package/src/types.ts

@@ -6,7 +6,7 @@ import type { Finding } from './api/lib/health/types';
 // - camelCase fields are in-memory composed state assembled by the viewer (e.g., `crossCuttingRoadmap`,
 //   `layerDocs`). Renaming these is purely an internal refactor.
 
-export type Status = 'now' | 'next' | 'later' | 'done';
+export type Status = 'now' | 'next' | 'later' | 'done' | 'dropped';
 
 /**
  * Advisory priority marker. Does NOT affect roadmap ordering — items still execute

package/src/ui/ItemCard.module.css

@@ -5,9 +5,21 @@
   margin-bottom: 4px;
   cursor: grab;
   position: relative;
-  transition: background var(--dur-state) var(--ease);
+  transition: background var(--dur-state) var(--ease), opacity var(--dur-state) var(--ease);
 }
 .card:hover { background: var(--console-mist); }
+
+/*
+ * Done cards fade to 60% so live columns (now/next/later) dominate the
+ * visual hierarchy. Hover lifts to full opacity as a subtle affordance
+ * that the card is still interactive. (td-008)
+ */
+.cardDone {
+  opacity: 0.6;
+}
+.cardDone:hover {
+  opacity: 1;
+}
 .card:focus-visible {
   outline: 2px solid var(--signal-cyan);
   outline-offset: 2px;

package/src/ui/ItemCard.tsx

@@ -3,7 +3,7 @@ import { useSortable } from '@dnd-kit/sortable';
 import { CSS } from '@dnd-kit/utilities';
 import { CornerLeftUp, ArrowLeftRight } from 'lucide-react';
 import type { Item } from '../types';
-import { phaseProgress } from '../api/lib/phases';
+import { effectiveStatus, phaseProgress } from '../api/lib/phases';
 import styles from './ItemCard.module.css';
 
 interface Props {
@@ -24,10 +24,15 @@ export function ItemCard({ item, onClick, onTitleEdit, onDescEdit }: Props) {
   const phases = item.phases ?? [];
   const progress = phases.length > 0 ? phaseProgress(phases) : null;
 
+  // Done cards are dimmed in the kanban so the live columns (now/next/later)
+  // own the user's visual attention. Hover restores opacity. The item modal
+  // (rendered separately) is not affected — only the kanban card. (td-008)
+  const isDone = effectiveStatus(item) === 'done';
+
   return (
     <div
       ref={setNodeRef}
-      className={styles.card}
+      className={`${styles.card}${isDone ? ` ${styles.cardDone}` : ''}`}
       style={dragStyle}
       {...attributes}
       {...listeners}

package/src/ui/ItemModal/PhasesSection.tsx

@@ -1,7 +1,7 @@
 import type { Item, Phase, Status } from '../../types';
 import { phaseProgress } from '../../api/lib/phases';
 
-const STATUSES: Status[] = ['now', 'next', 'later', 'done'];
+const STATUSES: Status[] = ['now', 'next', 'later', 'done', 'dropped'];
 
 interface Props {
   item: Item;

package/src/ui/ItemModal/StatusLayerControls.tsx

@@ -1,7 +1,7 @@
 import type { Layer, Priority, Status } from '../../types';
 import styles from './ItemModal.module.css';
 
-const STATUSES: Status[] = ['now', 'next', 'later', 'done'];
+const STATUSES: Status[] = ['now', 'next', 'later', 'done', 'dropped'];
 const PRIORITIES: Priority[] = ['p0', 'p1', 'p2', 'p3'];
 
 interface Props {

package/src/ui/KanbanColumn.tsx

@@ -2,6 +2,7 @@ import { useDroppable } from '@dnd-kit/core';
 import { SortableContext, verticalListSortingStrategy } from '@dnd-kit/sortable';
 import { ItemCard } from './ItemCard';
 import type { Item, Status } from '../types';
+import { sortByPriority } from '../api/lib/priority';
 import styles from './KanbanColumn.module.css';
 
 interface Props {
@@ -13,15 +14,19 @@ interface Props {
   onDescEdit: (id: string, desc: string) => void;
 }
 
-const LABEL: Record<Status, string> = { now: 'NOW', next: 'NEXT', later: 'LATER', done: 'DONE' };
+const LABEL: Record<Status, string> = { now: 'NOW', next: 'NEXT', later: 'LATER', done: 'DONE', dropped: 'DROPPED' };
 
 export function KanbanColumn({ layerId, status, items, onCardClick, onTitleEdit, onDescEdit }: Props) {
   const { setNodeRef, isOver } = useDroppable({ id: `${layerId}::${status}`, data: { layerId, status } });
+  // Sort within the column by priority (p0→p3→unset). Stable on equal
+  // priorities — file order from roadmap.yaml acts as the secondary key,
+  // so drag-reorder still has visible effect within a priority bucket. (td-009)
+  const sorted = sortByPriority(items);
   return (
     <div ref={setNodeRef} className={`${styles.column} ${isOver ? styles.columnOver : ''}`}>
       <div className={styles.label}>{LABEL[status]}</div>
-      <SortableContext items={items.map(i => i.id)} strategy={verticalListSortingStrategy}>
-        {items.map(item => (
+      <SortableContext items={sorted.map(i => i.id)} strategy={verticalListSortingStrategy}>
+        {sorted.map(item => (
           <ItemCard
             key={item.id}
             item={item}

package/src/ui/LayerKanban.tsx

@@ -18,7 +18,11 @@ interface Props {
 
 const STATUSES: Status[] = ['now', 'next', 'later', 'done'];
 
-export function LayerKanban({ layer, items, depth = 0, alwaysOpen = false, onCardClick, onTitleEdit, onDescEdit }: Props) {
+export function LayerKanban({ layer, items: rawItems, depth = 0, alwaysOpen = false, onCardClick, onTitleEdit, onDescEdit }: Props) {
+  // `dropped` items are hidden from the kanban by default — they're still
+  // editable via the item modal, still counted by validators, but they don't
+  // clutter the visual board. (Future: a "show dropped" toggle.)
+  const items = rawItems.filter(i => effectiveStatus(i) !== 'dropped');
   const counts = STATUSES.map(s => items.filter(i => effectiveStatus(i) === s).length);
   const hasActive = counts[0] > 0 || counts[1] > 0;
   const [open, setOpen] = useState(hasActive);

package/src/ui/TaskList.tsx

@@ -1,6 +1,7 @@
 import { CornerLeftUp, ArrowLeftRight } from 'lucide-react';
 import type { Item, Status } from '../types';
 import { effectiveStatus } from '../api/lib/phases';
+import { comparePriority } from '../api/lib/priority';
 import styles from './TaskList.module.css';
 
 export interface FlatItem {
@@ -15,11 +16,18 @@ interface Props {
 }
 
 const STATUS_ORDER: Status[] = ['now', 'next', 'later', 'done'];
-const STATUS_LABEL: Record<Status, string> = { now: 'Now', next: 'Next', later: 'Later', done: 'Done' };
+const STATUS_LABEL: Record<Status, string> = { now: 'Now', next: 'Next', later: 'Later', done: 'Done', dropped: 'Dropped' };
 
-export function TaskList({ items, onRowClick }: Props) {
+export function TaskList({ items: rawItems, onRowClick }: Props) {
+  // Hide `dropped` items from the list view (matches LayerKanban behavior).
+  const items = rawItems.filter(({ item }) => effectiveStatus(item) !== 'dropped');
+  // Group by status (now → next → later → done) and within each status
+  // group by priority (p0 → p3 → unset). Both sorts are stable so file
+  // order acts as the tiebreaker for items at the same priority. (td-009)
   const sorted = STATUS_ORDER.flatMap(s =>
-    items.filter(({ item }) => effectiveStatus(item) === s)
+    items
+      .filter(({ item }) => effectiveStatus(item) === s)
+      .sort((a, b) => comparePriority(a.item, b.item))
   );
 
   if (items.length === 0) {