tenbo-dashboard 0.1.0

package/src/api/lib/relationships.ts

@@ -0,0 +1,65 @@
+import type { Item, TenboState } from '../../types';
+
+export interface ItemRef {
+  item: Item;
+  scopeId?: string;
+}
+
+/**
+ * Flatten every roadmap item across all scopes plus the cross-cutting roadmap
+ * into a single array of `{ item, scopeId }` references. `scopeId` is undefined
+ * for cross-cutting items. Order: scope-by-scope (in `state.scopes` order),
+ * then cross-cutting at the end.
+ */
+export function allItems(state: TenboState): ItemRef[] {
+  const out: ItemRef[] = [];
+  for (const scope of state.scopes) {
+    for (const item of scope.items) out.push({ item, scopeId: scope.id });
+  }
+  for (const item of state.crossCuttingRoadmap ?? []) out.push({ item });
+  return out;
+}
+
+/** Find an item by id anywhere in the workspace. Returns null if missing. */
+export function findItemById(state: TenboState, id: string): ItemRef | null {
+  for (const ref of allItems(state)) {
+    if (ref.item.id === id) return ref;
+  }
+  return null;
+}
+
+/**
+ * Given a flat list of items, return all items whose `spawned_from` equals `parentId`.
+ * Pure function — extracted so it can be tested without constructing a full TenboState.
+ */
+export function childrenOf(items: Item[], parentId: string): Item[] {
+  return items.filter((it) => it.spawned_from === parentId);
+}
+
+/**
+ * Compute the full set of items related to `target` (deduplicated by id):
+ *   - Forward edges: every id in `target.related` that resolves to a known item.
+ *   - Reverse edges: every other item whose `related` array contains `target.id`.
+ * The target itself is excluded. Order: forward refs first (preserving target.related
+ * order), then reverse refs in workspace-iteration order.
+ */
+export function relatedItems(state: TenboState, target: Item): ItemRef[] {
+  const seen = new Set<string>([target.id]);
+  const out: ItemRef[] = [];
+  for (const ref of target.related ?? []) {
+    if (seen.has(ref)) continue;
+    const found = findItemById(state, ref);
+    if (found) {
+      seen.add(ref);
+      out.push(found);
+    }
+  }
+  for (const candidate of allItems(state)) {
+    if (seen.has(candidate.item.id)) continue;
+    if ((candidate.item.related ?? []).includes(target.id)) {
+      seen.add(candidate.item.id);
+      out.push(candidate);
+    }
+  }
+  return out;
+}

package/src/api/lib/repoRoot.ts

@@ -0,0 +1,12 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+export function findRepoRoot(start: string): string | null {
+  let cur = path.resolve(start);
+  while (true) {
+    if (existsSync(path.join(cur, '.git'))) return cur;
+    const parent = path.dirname(cur);
+    if (parent === cur) return null;
+    cur = parent;
+  }
+}

package/src/api/lib/tenboFs.layerContent.test.ts

@@ -0,0 +1,36 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { readLayerContent } from './tenboFs.js';
+
+let dir: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(path.join(tmpdir(), 'tenbo-lc-'));
+  const layer = path.join(dir, '.tenbo', 'scopes', 'editor', 'layers', 'foo');
+  mkdirSync(layer, { recursive: true });
+  writeFileSync(path.join(layer, 'README.md'), '# Foo\n');
+  writeFileSync(path.join(layer, 'intent.md'), '# Intent\n');
+  writeFileSync(path.join(layer, 'code-map.md'), '# Code Map\n');
+});
+
+afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+describe('readLayerContent', () => {
+  it('returns the three layer files', () => {
+    const r = readLayerContent(dir, 'editor', 'foo');
+    expect(r.scope).toBe('editor');
+    expect(r.layer).toBe('foo');
+    expect(r.readme).toContain('Foo');
+    expect(r.intentMd).toContain('Intent');
+    expect(r.codeMapMd).toContain('Code Map');
+  });
+
+  it('returns empty strings when files are missing', () => {
+    const r = readLayerContent(dir, 'editor', 'missing');
+    expect(r.readme).toBe('');
+    expect(r.intentMd).toBe('');
+    expect(r.codeMapMd).toBe('');
+  });
+});

package/src/api/lib/tenboFs.ts

@@ -0,0 +1,237 @@
+import { readFileSync, writeFileSync, readdirSync, existsSync, renameSync, statSync, type Stats } from 'node:fs';
+import path from 'node:path';
+import { parse as parseSimple } from 'yaml';
+import { parseYaml, stringifyYaml, patchSeqItem, reorderSeqItems } from './yamlOrdered';
+import type { TenboState, Scope, Item, Layer, CrossCutting, LayerDocs, ScopeMetrics, WorkspaceContent, LayerContent } from '../../types';
+
+function tenboDir(repoRoot: string) { return path.join(repoRoot, '.tenbo'); }
+
+function readMaybeFile(p: string): { content: string; mtime: number | null } {
+  if (!existsSync(p)) return { content: '', mtime: null };
+  const content = readFileSync(p, 'utf8');
+  const mtime = statSync(p).mtimeMs;
+  return { content, mtime };
+}
+
+export function readWorkspaceContent(repoRoot: string): WorkspaceContent {
+  const tenbo = tenboDir(repoRoot);
+  const ov = readMaybeFile(path.join(tenbo, 'overview.md'));
+  const p = readMaybeFile(path.join(tenbo, 'principles.md'));
+  const g = readMaybeFile(path.join(tenbo, 'glossary.md'));
+  const o = readMaybeFile(path.join(tenbo, 'observations.md'));
+  return {
+    overviewMd: ov.content,
+    principlesMd: p.content,
+    glossaryMd: g.content,
+    observationsMd: o.content,
+    overviewMtime: ov.mtime,
+    principlesMtime: p.mtime,
+    glossaryMtime: g.mtime,
+    observationsMtime: o.mtime,
+  };
+}
+
+export function readLayerContent(repoRoot: string, scopeId: string, layerId: string): LayerContent {
+  const layerDir = path.join(tenboDir(repoRoot), 'scopes', scopeId, 'layers', layerId);
+  return {
+    scope: scopeId,
+    layer: layerId,
+    readme: readMaybeFile(path.join(layerDir, 'README.md')).content,
+    intentMd: readMaybeFile(path.join(layerDir, 'intent.md')).content,
+    codeMapMd: readMaybeFile(path.join(layerDir, 'code-map.md')).content,
+  };
+}
+
+export function tenboExists(repoRoot: string): boolean {
+  return existsSync(path.join(tenboDir(repoRoot), 'workspace.yaml'));
+}
+
+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;
+  return {
+    scopeRefs: data?.scopes ?? [],
+    crossCutting: data?.cross_cutting ?? [],
+  };
+}
+
+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;
+  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;
+  return data?.items ?? [];
+}
+
+function readNarratives(repoRoot: string, scopeId: string): Record<string, string> {
+  const dir = path.join(tenboDir(repoRoot), 'scopes', scopeId, 'layers');
+  if (!existsSync(dir)) return {};
+  const out: Record<string, string> = {};
+  for (const entry of readdirSync(dir)) {
+    const full = path.join(dir, entry);
+    if (!statSync(full).isDirectory()) continue;
+    const readme = path.join(full, 'README.md');
+    if (existsSync(readme)) {
+      out[`${scopeId}/${entry}`] = readFileSync(readme, 'utf8');
+    }
+  }
+  return out;
+}
+
+export interface LayerDocEntry {
+  filename: string;
+  title: string | null;
+}
+
+export function listLayerDocs(repoRoot: string, scopeId: string, layerId: string): LayerDocEntry[] {
+  const layerDir = path.join(tenboDir(repoRoot), 'scopes', scopeId, 'layers', layerId);
+  if (!existsSync(layerDir) || !statSync(layerDir).isDirectory()) return [];
+  const out: LayerDocEntry[] = [];
+  for (const entry of readdirSync(layerDir)) {
+    if (!entry.endsWith('.md')) continue;
+    if (entry === 'README.md') continue;
+    const full = path.join(layerDir, entry);
+    if (!statSync(full).isFile()) continue;
+    const text = readFileSync(full, 'utf8');
+    const m = text.match(/^#\s+(.+)$/m);
+    out.push({ filename: entry, title: m ? m[1].trim() : null });
+  }
+  out.sort((a, b) => a.filename.localeCompare(b.filename));
+  return out;
+}
+
+function tryStat(p: string): Stats | null {
+  try { return statSync(p); } catch { return null; }
+}
+
+function readLayerDocs(repoRoot: string, scopeId: string): Record<string, LayerDocs> {
+  const dir = path.join(tenboDir(repoRoot), 'scopes', scopeId, 'layers');
+  if (!existsSync(dir)) return {};
+  const out: Record<string, LayerDocs> = {};
+  for (const entry of readdirSync(dir)) {
+    const full = path.join(dir, entry);
+    const entryStat = tryStat(full);
+    if (!entryStat?.isDirectory()) continue;
+    const intentPath = path.join(full, 'intent.md');
+    const intentStat = tryStat(intentPath);
+    const codeMapStat = tryStat(path.join(full, 'code-map.md'));
+    let intentEmpty = false;
+    if (intentStat) {
+      try {
+        const stripped = readFileSync(intentPath, 'utf8')
+          .replace(/<!--[\s\S]*?-->/g, '')
+          .replace(/^#.*$/gm, '')
+          .trim();
+        intentEmpty = stripped.length === 0;
+      } catch {
+        // Read failure (race, permission, broken symlink): treat as non-empty;
+        // higher layers will surface a different error if the file is unusable.
+        intentEmpty = false;
+      }
+    }
+    out[`${scopeId}/${entry}`] = {
+      hasIntent: !!intentStat,
+      hasCodeMap: !!codeMapStat,
+      intentMtime: intentStat?.mtimeMs ?? null,
+      codeMapMtime: codeMapStat?.mtimeMs ?? null,
+      intentEmpty,
+    };
+  }
+  return out;
+}
+
+function readCrossCuttingRoadmap(repoRoot: string): Item[] {
+  const file = path.join(tenboDir(repoRoot), 'roadmap.yaml');
+  if (!existsSync(file)) return [];
+  const data = parseSimple(readFileSync(file, 'utf8')) as any;
+  return data?.items ?? [];
+}
+
+function readMetrics(repoRoot: string, scopeId: string): ScopeMetrics | undefined {
+  const file = path.join(tenboDir(repoRoot), 'scopes', scopeId, 'metrics.json');
+  if (!existsSync(file)) return undefined;
+  try {
+    return JSON.parse(readFileSync(file, 'utf8')) as ScopeMetrics;
+  } catch (err) {
+    console.warn(`tenbo: failed to parse ${file}: ${(err as Error).message}`);
+    return undefined;
+  }
+}
+
+/**
+ * List spec markdown files under `.tenbo/specs/` and `.tenbo/specs/archive/`.
+ * Returns a Set of repo-relative paths (e.g. `.tenbo/specs/x-001-foo.md`).
+ * Returns undefined if `.tenbo/specs/` does not exist.
+ */
+export function readSpecFiles(repoRoot: string): Set<string> | undefined {
+  const specsDir = path.join(tenboDir(repoRoot), 'specs');
+  if (!existsSync(specsDir)) return undefined;
+  const out = new Set<string>();
+  for (const entry of readdirSync(specsDir)) {
+    if (entry.endsWith('.md')) out.add(`.tenbo/specs/${entry}`);
+  }
+  const archiveDir = path.join(specsDir, 'archive');
+  if (existsSync(archiveDir) && statSync(archiveDir).isDirectory()) {
+    for (const entry of readdirSync(archiveDir)) {
+      if (entry.endsWith('.md')) out.add(`.tenbo/specs/archive/${entry}`);
+    }
+  }
+  return out;
+}
+
+export function readState(repoRoot: string): TenboState {
+  const ws = readWorkspace(repoRoot);
+  const scopes: Scope[] = ws.scopeRefs.map(ref => ({
+    id: ref.id,
+    path: ref.path,
+    description: ref.description,
+    layers: readArchitecture(repoRoot, ref.id),
+    items: readRoadmap(repoRoot, ref.id),
+  }));
+  const narratives = scopes.reduce<Record<string, string>>((acc, s) => {
+    return Object.assign(acc, readNarratives(repoRoot, s.id));
+  }, {});
+  const layerDocs = scopes.reduce<Record<string, LayerDocs>>((acc, s) => {
+    return Object.assign(acc, readLayerDocs(repoRoot, s.id));
+  }, {});
+  const crossCuttingRoadmap = readCrossCuttingRoadmap(repoRoot);
+  const metrics: Record<string, ScopeMetrics> = {};
+  for (const s of scopes) {
+    const m = readMetrics(repoRoot, s.id);
+    if (m) metrics[s.id] = m;
+  }
+  const workspaceContent = readWorkspaceContent(repoRoot);
+  const state: TenboState = { scopes, crossCutting: ws.crossCutting, narratives, workspaceContent };
+  state.layerDocs = layerDocs;
+  state.crossCuttingRoadmap = crossCuttingRoadmap;
+  if (Object.keys(metrics).length > 0) state.metrics = metrics;
+  const specFiles = readSpecFiles(repoRoot);
+  if (specFiles) state.specFiles = specFiles;
+  return state;
+}
+
+function atomicWrite(filePath: string, content: string): void {
+  const tmp = `${filePath}.tmp.${process.pid}.${Date.now()}`;
+  writeFileSync(tmp, content, 'utf8');
+  renameSync(tmp, filePath);
+}
+
+export function patchItem(repoRoot: string, scopeId: string, itemId: string, patch: Partial<Item>): void {
+  const file = path.join(tenboDir(repoRoot), 'scopes', scopeId, 'roadmap.yaml');
+  const text = readFileSync(file, 'utf8');
+  const doc = parseYaml(text);
+  patchSeqItem(doc, 'items', itemId, patch as Record<string, unknown>);
+  atomicWrite(file, stringifyYaml(doc));
+}
+
+export function reorderItems(repoRoot: string, scopeId: string, idsInOrder: string[]): void {
+  const file = path.join(tenboDir(repoRoot), 'scopes', scopeId, 'roadmap.yaml');
+  const text = readFileSync(file, 'utf8');
+  const doc = parseYaml(text);
+  reorderSeqItems(doc, 'items', idsInOrder);
+  atomicWrite(file, stringifyYaml(doc));
+}

package/src/api/lib/tenboFs.v2.test.ts

@@ -0,0 +1,86 @@
+import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { describe, it, expect, vi } from 'vitest';
+import { readState } from './tenboFs';
+
+function makeTenbo(structure: Record<string, string>) {
+  const root = mkdtempSync(path.join(tmpdir(), 'tenbo-v2-'));
+  for (const [rel, content] of Object.entries(structure)) {
+    const full = path.join(root, rel);
+    mkdirSync(path.dirname(full), { recursive: true });
+    writeFileSync(full, content);
+  }
+  return root;
+}
+
+describe('readState v2 extensions', () => {
+  it('reports layerDocs.hasIntent and hasCodeMap when present', () => {
+    const root = makeTenbo({
+      '.tenbo/workspace.yaml': 'scopes:\n  - id: e\n    path: .\n    description: ok\ncross_cutting: []\n',
+      '.tenbo/scopes/e/architecture.yaml': 'layers:\n  - id: l\n    name: L\n    description: a layer here\n    files: ["**/*"]\n',
+      '.tenbo/scopes/e/roadmap.yaml': 'items: []\n',
+      '.tenbo/scopes/e/layers/l/README.md': '# L\n',
+      '.tenbo/scopes/e/layers/l/intent.md': '# L\n',
+      '.tenbo/scopes/e/layers/l/code-map.md': '# L\n',
+    });
+    const state = readState(root);
+    expect(state.layerDocs?.['e/l'].hasIntent).toBe(true);
+    expect(state.layerDocs?.['e/l'].hasCodeMap).toBe(true);
+    expect(typeof state.layerDocs?.['e/l'].intentMtime).toBe('number');
+  });
+
+  it('reads cross-cutting roadmap from .tenbo/roadmap.yaml', () => {
+    const root = makeTenbo({
+      '.tenbo/workspace.yaml': 'scopes: []\ncross_cutting: []\n',
+      '.tenbo/roadmap.yaml': 'items:\n  - id: x-001\n    title: cross thing\n    layers: []\n    status: later\n    description: spans many things across the system\n',
+    });
+    const state = readState(root);
+    expect(state.crossCuttingRoadmap?.length).toBe(1);
+    expect(state.crossCuttingRoadmap?.[0].id).toBe('x-001');
+  });
+
+  it('reports absent v2 files cleanly', () => {
+    const root = makeTenbo({
+      '.tenbo/workspace.yaml': 'scopes:\n  - id: e\n    path: .\n    description: ok\ncross_cutting: []\n',
+      '.tenbo/scopes/e/architecture.yaml': 'layers:\n  - id: l\n    name: L\n    description: a small layer for testing\n    files: ["**/*"]\n',
+      '.tenbo/scopes/e/roadmap.yaml': 'items: []\n',
+      '.tenbo/scopes/e/layers/l/README.md': '# L\n',
+    });
+    const state = readState(root);
+    expect(state.layerDocs?.['e/l'].hasIntent).toBe(false);
+    expect(state.crossCuttingRoadmap).toEqual([]);
+    expect(state.metrics).toBeUndefined();
+  });
+
+  it('reads metrics.json when present', () => {
+    const root = makeTenbo({
+      '.tenbo/workspace.yaml': 'scopes:\n  - id: e\n    path: .\n    description: ok\ncross_cutting: []\n',
+      '.tenbo/scopes/e/architecture.yaml': 'layers:\n  - id: l\n    name: L\n    description: a layer here\n    files: ["**/*"]\n',
+      '.tenbo/scopes/e/roadmap.yaml': 'items: []\n',
+      '.tenbo/scopes/e/layers/l/README.md': '# L\n',
+      '.tenbo/scopes/e/metrics.json': JSON.stringify({
+        generated_at: '2026-04-26T00:00:00Z',
+        layers: { l: { file_count: 3, total_lines: 42, outbound_deps: 0, deep_dive_count: 0, intent_age_days: null, pct_roadmap_in_now: 0 } },
+      }),
+    });
+    const state = readState(root);
+    expect(state.metrics?.['e'].layers.l.file_count).toBe(3);
+    expect(state.metrics?.['e'].generated_at).toBe('2026-04-26T00:00:00Z');
+  });
+
+  it('tolerates malformed metrics.json without crashing readState', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const root = makeTenbo({
+      '.tenbo/workspace.yaml': 'scopes:\n  - id: e\n    path: .\n    description: ok\ncross_cutting: []\n',
+      '.tenbo/scopes/e/architecture.yaml': 'layers:\n  - id: l\n    name: L\n    description: a layer here\n    files: ["**/*"]\n',
+      '.tenbo/scopes/e/roadmap.yaml': 'items: []\n',
+      '.tenbo/scopes/e/layers/l/README.md': '# L\n',
+      '.tenbo/scopes/e/metrics.json': '{ not valid json',
+    });
+    const state = readState(root);
+    expect(state.metrics).toBeUndefined();
+    expect(warn).toHaveBeenCalled();
+    warn.mockRestore();
+  });
+});

package/src/api/lib/tenboFs.workspaceContent.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync, utimesSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { readWorkspaceContent } from './tenboFs.js';
+
+let dir: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(path.join(tmpdir(), 'tenbo-ws-'));
+  mkdirSync(path.join(dir, '.tenbo'), { recursive: true });
+});
+
+afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+describe('readWorkspaceContent', () => {
+  it('returns empty strings and null mtimes when files are missing', () => {
+    const r = readWorkspaceContent(dir);
+    expect(r.principlesMd).toBe('');
+    expect(r.glossaryMd).toBe('');
+    expect(r.observationsMd).toBe('');
+    expect(r.principlesMtime).toBeNull();
+    expect(r.glossaryMtime).toBeNull();
+    expect(r.observationsMtime).toBeNull();
+  });
+
+  it('reads contents and mtimes when files exist', () => {
+    const fixedTime = new Date('2026-01-01T00:00:00Z');
+    const tenbo = path.join(dir, '.tenbo');
+    writeFileSync(path.join(tenbo, 'principles.md'), '# Principles\n');
+    writeFileSync(path.join(tenbo, 'glossary.md'), '# Glossary\n');
+    writeFileSync(path.join(tenbo, 'observations.md'), '# Observations\n');
+    for (const f of ['principles.md', 'glossary.md', 'observations.md']) {
+      utimesSync(path.join(tenbo, f), fixedTime, fixedTime);
+    }
+    const r = readWorkspaceContent(dir);
+    expect(r.principlesMd).toContain('Principles');
+    expect(r.glossaryMd).toContain('Glossary');
+    expect(r.observationsMd).toContain('Observations');
+    expect(r.principlesMtime).toBe(fixedTime.getTime());
+  });
+});

package/src/api/lib/validator.docUpdate.test.ts

@@ -0,0 +1,99 @@
+import { describe, it, expect } from 'vitest';
+import { validate } from './validator';
+import type { TenboState, Item } from '../../types';
+
+function stateWithItems(items: Item[]): TenboState {
+  return {
+    scopes: [{
+      id: 'e',
+      path: '.',
+      description: 'editor scope description here for tests',
+      layers: [{ id: 'l', name: 'L', description: 'a small layer for testing now', files: ['x'] } as any],
+      items,
+    }],
+    crossCutting: [],
+    narratives: { 'e/l': '# L' },
+  } as any;
+}
+
+const baseItem = (over: Partial<Item> = {}): Item => ({
+  id: 'ed-001',
+  title: 't',
+  layer: 'l',
+  status: 'done',
+  description: 'a roadmap item used for doc_update tests now',
+  ...over,
+});
+
+const issuesFor = (state: TenboState, id: string) => {
+  const r = validate(state);
+  return {
+    warnings: r.warnings.filter((w) => w.itemId === id).map((w) => w.message),
+    errors: r.errors.filter((e) => e.itemId === id).map((e) => e.message),
+  };
+};
+
+describe('validator — doc_update gate (x-003 phase 3)', () => {
+  it('warns when a done feature/refactor/bug item is missing doc_update', () => {
+    for (const type of ['feature', 'refactor', 'bug'] as const) {
+      const state = stateWithItems([baseItem({ id: `ed-00${1}`, type })]);
+      const { warnings } = issuesFor(state, 'ed-001');
+      expect(warnings.some((m) => m.includes('doc_update is not stamped'))).toBe(true);
+    }
+  });
+
+  it('does not warn when doc_update is a valid ISO date', () => {
+    const state = stateWithItems([baseItem({ type: 'feature', doc_update: '2026-04-28' })]);
+    expect(issuesFor(state, 'ed-001').warnings).toEqual([]);
+  });
+
+  it('does not warn when doc_update is a skipped reason with em-dash', () => {
+    const state = stateWithItems([baseItem({ type: 'refactor', doc_update: 'skipped — internal helper rename only' })]);
+    expect(issuesFor(state, 'ed-001').warnings).toEqual([]);
+  });
+
+  it('does not warn when doc_update is a skipped reason with hyphen or colon separator', () => {
+    for (const sep of [' - ', ': ']) {
+      const state = stateWithItems([baseItem({ type: 'bug', doc_update: `skipped${sep}no architecture impact` })]);
+      expect(issuesFor(state, 'ed-001').warnings).toEqual([]);
+    }
+  });
+
+  it('warns when doc_update is malformed (neither date nor skipped reason)', () => {
+    const state = stateWithItems([baseItem({ type: 'feature', doc_update: 'yes I did' })]);
+    const { warnings } = issuesFor(state, 'ed-001');
+    expect(warnings.some((m) => m.includes('is malformed'))).toBe(true);
+  });
+
+  it('errors when doc_update is not a string', () => {
+    const state = stateWithItems([baseItem({ type: 'feature', doc_update: 123 as any })]);
+    const { errors } = issuesFor(state, 'ed-001');
+    expect(errors.some((m) => m.includes('must be a string'))).toBe(true);
+  });
+
+  it('does not warn when item has no type set (exemption for un-typed items)', () => {
+    const state = stateWithItems([baseItem({ /* no type */ })]);
+    const { warnings } = issuesFor(state, 'ed-001');
+    expect(warnings.some((m) => m.includes('doc_update'))).toBe(false);
+  });
+
+  it('does not warn for spike items even when doc_update is missing', () => {
+    const state = stateWithItems([baseItem({ type: 'spike' })]);
+    const { warnings } = issuesFor(state, 'ed-001');
+    expect(warnings.some((m) => m.includes('doc_update'))).toBe(false);
+  });
+
+  it('does not warn for items with status other than done', () => {
+    for (const status of ['now', 'next', 'later'] as const) {
+      const state = stateWithItems([baseItem({ status, type: 'feature', done_when: ['ok'] })]);
+      const { warnings } = issuesFor(state, 'ed-001');
+      expect(warnings.some((m) => m.includes('doc_update'))).toBe(false);
+    }
+  });
+
+  it('warns when doc_update is empty string', () => {
+    const state = stateWithItems([baseItem({ type: 'feature', doc_update: '' })]);
+    const { warnings } = issuesFor(state, 'ed-001');
+    expect(warnings.some((m) => m.includes('doc_update is not stamped'))).toBe(true);
+  });
+});

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

@@ -0,0 +1,98 @@
+import { describe, it, expect } from 'vitest';
+import { validate } from './validator';
+import type { TenboState, Item, Phase } from '../../types';
+
+function baseState(items: Item[] = []): TenboState {
+  return {
+    scopes: [{
+      id: 'e', path: '.', description: 'editor scope description here for tests',
+      layers: [{ id: 'l', name: 'L', description: 'a small layer for testing now', files: ['x'] } as any],
+      items,
+    }],
+    crossCutting: [],
+    narratives: { 'e/l': '# L' },
+  } as any;
+}
+
+const baseItem = (over: Partial<Item> = {}): Item => ({
+  id: 'ed-001',
+  title: 't',
+  layer: 'l',
+  status: 'later',
+  description: 'a roadmap item with phases for testing now',
+  ...over,
+});
+
+const ph = (id: number, status: Phase['status'], extra: Partial<Phase> = {}): Phase => ({
+  id,
+  title: `phase ${id}`,
+  status,
+  ...extra,
+});
+
+describe('validator — phase schema', () => {
+  it('accepts a well-formed phases list with no errors', () => {
+    const item = baseItem({
+      phases: [ph(1, 'done', { completed_at: '2026-04-27' }), ph(2, 'now')],
+    });
+    const r = validate(baseState([item]));
+    const phaseErrors = r.errors.filter((e) => e.itemId === 'ed-001');
+    expect(phaseErrors).toEqual([]);
+  });
+
+  it('errors when a phase id does not match its 1-based position', () => {
+    const item = baseItem({ phases: [ph(1, 'done'), ph(3, 'now')] });
+    const r = validate(baseState([item]));
+    expect(r.errors.some((e) => /id 3.*1\.\.N/.test(e.message))).toBe(true);
+  });
+
+  it('errors when a phase has a non-integer id', () => {
+    const item = baseItem({ phases: [{ title: 'p', status: 'later' } as any] });
+    const r = validate(baseState([item]));
+    expect(r.errors.some((e) => /missing an integer id/.test(e.message))).toBe(true);
+  });
+
+  it('errors when a phase is missing title', () => {
+    const item = baseItem({ phases: [{ id: 1, status: 'later' } as any] });
+    const r = validate(baseState([item]));
+    expect(r.errors.some((e) => /missing a title/.test(e.message))).toBe(true);
+  });
+
+  it('errors on invalid phase status', () => {
+    const item = baseItem({ phases: [{ id: 1, title: 'x', status: 'wip' } as any] });
+    const r = validate(baseState([item]));
+    expect(r.errors.some((e) => /invalid status "wip"/.test(e.message))).toBe(true);
+  });
+
+  it('errors when completed_at is not YYYY-MM-DD', () => {
+    const item = baseItem({ phases: [ph(1, 'done', { completed_at: '04/27/2026' })] });
+    const r = validate(baseState([item]));
+    expect(r.errors.some((e) => /completed_at.*YYYY-MM-DD/.test(e.message))).toBe(true);
+  });
+});
+
+describe('validator — phase warnings', () => {
+  it('warns when phase is done but completed_at missing', () => {
+    const item = baseItem({ phases: [ph(1, 'done')] });
+    const r = validate(baseState([item]));
+    expect(r.warnings.some((w) => /done but has no completed_at/.test(w.message))).toBe(true);
+  });
+
+  it('warns when completed_at set but status not done', () => {
+    const item = baseItem({ phases: [ph(1, 'now', { completed_at: '2026-04-27' })] });
+    const r = validate(baseState([item]));
+    expect(r.warnings.some((w) => /has completed_at but status is "now"/.test(w.message))).toBe(true);
+  });
+
+  it('warns when both status and phases are present', () => {
+    const item = baseItem({ status: 'now', phases: [ph(1, 'now')] });
+    const r = validate(baseState([item]));
+    expect(r.warnings.some((w) => /both status and phases/.test(w.message))).toBe(true);
+  });
+
+  it('does not warn for items without phases', () => {
+    const item = baseItem({ status: 'now', done_when: ['x'] });
+    const r = validate(baseState([item]));
+    expect(r.warnings.some((w) => /both status and phases/.test(w.message))).toBe(false);
+  });
+});