tenbo-dashboard 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tenbo-dashboard",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Local-first architecture dashboard and CLI tools for .tenbo/ repos",
   "type": "module",
   "license": "MIT",

package/src/api/lib/tenboFs.ts

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { parse as parseSimple, stringify as yamlStringify } 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';
+import type { TenboState, Scope, Item, Layer, CrossCutting, LayerDocs, ScopeMetrics, WorkspaceContent, LayerContent, DecisionRecord } from '../../types';
 
 function tenboDir(repoRoot: string) { return path.join(repoRoot, '.tenbo'); }
 
@@ -193,6 +193,43 @@ export function readSpecFiles(repoRoot: string): Set<string> | undefined {
   return out;
 }
 
+/**
+ * Read project-level decision records from `.tenbo/decisions/*.md`.
+ * Returns undefined if the directory does not exist (graceful no-op).
+ * Frontmatter is parsed leniently — malformed entries are still returned
+ * with whatever fields could be parsed; the validator surfaces issues.
+ */
+export function readDecisions(repoRoot: string): Record<string, DecisionRecord> | undefined {
+  const dir = path.join(tenboDir(repoRoot), 'decisions');
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) return undefined;
+  const out: Record<string, DecisionRecord> = {};
+  for (const entry of readdirSync(dir)) {
+    if (!entry.endsWith('.md')) continue;
+    const full = path.join(dir, entry);
+    if (!statSync(full).isFile()) continue;
+    const text = readFileSync(full, 'utf8');
+    const slug = entry.replace(/\.md$/, '');
+    const fmMatch = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+    let frontmatter: Record<string, unknown> = {};
+    let body = text;
+    if (fmMatch) {
+      try {
+        frontmatter = (parseSimple(fmMatch[1]) as Record<string, unknown>) ?? {};
+      } catch {
+        frontmatter = {};
+      }
+      body = fmMatch[2] ?? '';
+    }
+    out[slug] = {
+      path: `.tenbo/decisions/${entry}`,
+      slug,
+      frontmatter: frontmatter as DecisionRecord['frontmatter'],
+      body,
+    };
+  }
+  return out;
+}
+
 export function readState(repoRoot: string): TenboState {
   const ws = readWorkspace(repoRoot);
   const scopes: Scope[] = ws.scopeRefs.map(ref => ({
@@ -222,6 +259,8 @@ export function readState(repoRoot: string): TenboState {
   if (Object.keys(metrics).length > 0) state.metrics = metrics;
   const specFiles = readSpecFiles(repoRoot);
   if (specFiles) state.specFiles = specFiles;
+  const decisions = readDecisions(repoRoot);
+  if (decisions) state.decisions = decisions;
   return state;
 }
 

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

@@ -0,0 +1,76 @@
+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: 'now',
+  description: 'a roadmap item used for goal_ref tests now',
+  done_when: ['it works'],
+  ...over,
+});
+
+const warningsFor = (state: TenboState, id: string) =>
+  validate(state).warnings.filter((w) => w.itemId === id).map((w) => w.message);
+
+describe('validator — goal_ref shape (sk-025)', () => {
+  it('warns when goal_ref is missing on an active item', () => {
+    const state = stateWithItems([baseItem()]);
+    const msgs = warningsFor(state, 'ed-001');
+    expect(msgs.some((m) => m.includes('has no goal_ref'))).toBe(true);
+  });
+
+  it('does not warn when goal_ref is missing on a done or dropped item', () => {
+    for (const status of ['done', 'dropped'] as const) {
+      const state = stateWithItems([baseItem({ status })]);
+      const msgs = warningsFor(state, 'ed-001');
+      expect(msgs.some((m) => m.includes('has no goal_ref'))).toBe(false);
+    }
+  });
+
+  it('does not warn when goal_ref is a non-empty string array', () => {
+    const state = stateWithItems([baseItem({ goal_ref: ['g1', 'g3'] })]);
+    const msgs = warningsFor(state, 'ed-001');
+    expect(msgs.some((m) => m.includes('goal_ref'))).toBe(false);
+  });
+
+  it('does not warn when goal_ref is the literal "exploratory"', () => {
+    const state = stateWithItems([baseItem({ goal_ref: 'exploratory' })]);
+    const msgs = warningsFor(state, 'ed-001');
+    expect(msgs.some((m) => m.includes('goal_ref'))).toBe(false);
+  });
+
+  it('warns when goal_ref is an empty array', () => {
+    const state = stateWithItems([baseItem({ goal_ref: [] })]);
+    const msgs = warningsFor(state, 'ed-001');
+    expect(msgs.some((m) => m.includes('empty array'))).toBe(true);
+  });
+
+  it('warns when goal_ref is a malformed value (string other than "exploratory")', () => {
+    const state = stateWithItems([baseItem({ goal_ref: 'g1' as any })]);
+    const msgs = warningsFor(state, 'ed-001');
+    expect(msgs.some((m) => m.includes('must be a string array or the literal "exploratory"'))).toBe(true);
+  });
+
+  it('warns when goal_ref array contains a non-string entry', () => {
+    const state = stateWithItems([baseItem({ goal_ref: [1 as any, 'g2'] as any })]);
+    const msgs = warningsFor(state, 'ed-001');
+    expect(msgs.some((m) => m.includes('must be a string array'))).toBe(true);
+  });
+});

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

@@ -29,7 +29,13 @@ const baseItem = (over: Partial<Item> = {}): Item => ({
 const errMsgsFor = (state: TenboState, id: string) =>
   validate(state).errors.filter((e) => e.itemId === id).map((e) => e.message);
 const warnMsgsFor = (state: TenboState, id: string) =>
-  validate(state).warnings.filter((e) => e.itemId === id).map((e) => e.message);
+  validate(state).warnings
+    .filter((e) => e.itemId === id)
+    .map((e) => e.message)
+    // Exclude goal_ref warnings — sk-025 added a missing-goal_ref warning that
+    // fires on every active item without one. Tests in this file predate
+    // goal_ref and assert "no warnings" for unrelated relationship cases.
+    .filter((m) => !m.includes('goal_ref'));
 
 describe('validator — relationships', () => {
   it('accepts well-formed spawned_from + related with no errors or warnings', () => {

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

@@ -28,7 +28,11 @@ const baseItem = (over: Partial<Item> = {}): Item => ({
 });
 
 const warnMsgsFor = (state: TenboState, id: string) =>
-  validate(state).warnings.filter((w) => w.itemId === id).map((w) => w.message);
+  validate(state).warnings
+    .filter((w) => w.itemId === id)
+    .map((w) => w.message)
+    // Exclude goal_ref warnings (sk-025) — orthogonal to spec-link tests.
+    .filter((m) => !m.includes('goal_ref'));
 
 describe('validator — spec links (Phase 6)', () => {
   it('warns when a .tenbo/specs/ link points to a missing file', () => {

package/src/api/lib/validator.ts

@@ -277,6 +277,52 @@ export function validate(state: TenboState): ValidateResult {
         }
       }
 
+      // Goal-ref shape validation (sk-025). Optional field; warn (do not error)
+      // when missing or malformed. Shape-check only — does NOT cross-reference
+      // against `overview.md` Product goals (deferred per sk-022 risks).
+      // Skip the missing-warning for done/dropped items: no value in nagging
+      // about completed work.
+      if (item.goal_ref === undefined) {
+        if (item.status !== 'done' && item.status !== 'dropped') {
+          warnings.push({
+            level: 'warning',
+            message: `item ${item.id} has no goal_ref — backfill with cited goals or "exploratory"`,
+            scope: scope.id,
+            itemId: item.id,
+          });
+        }
+      } else if (item.goal_ref === 'exploratory') {
+        // Valid literal — no warning.
+      } else if (Array.isArray(item.goal_ref)) {
+        if (item.goal_ref.length === 0) {
+          warnings.push({
+            level: 'warning',
+            message: `item ${item.id}.goal_ref is an empty array — use "exploratory" if no goals identified, or remove the field`,
+            scope: scope.id,
+            itemId: item.id,
+          });
+        } else {
+          for (const ref of item.goal_ref) {
+            if (typeof ref !== 'string') {
+              warnings.push({
+                level: 'warning',
+                message: `item ${item.id}.goal_ref must be a string array or the literal "exploratory" — got: ${typeof ref} entry`,
+                scope: scope.id,
+                itemId: item.id,
+              });
+              break;
+            }
+          }
+        }
+      } else {
+        warnings.push({
+          level: 'warning',
+          message: `item ${item.id}.goal_ref must be a string array or the literal "exploratory" — got: ${typeof item.goal_ref}`,
+          scope: scope.id,
+          itemId: item.id,
+        });
+      }
+
       // Phase schema validation (Phase 3 of x-001).
       if (item.phases !== undefined) {
         if (!Array.isArray(item.phases)) {
@@ -324,6 +370,48 @@ export function validate(state: TenboState): ValidateResult {
     }
   }
 
+  // Decision records (sk-020). Validate frontmatter shape on every file under
+  // `.tenbo/decisions/`. Additive: state.decisions is undefined when the
+  // directory does not exist, so existing repos without decisions/ stay quiet.
+  if (state.decisions) {
+    const VALID_DECISION_STATUSES = new Set(['accepted', 'superseded']);
+    const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+    const decisions = state.decisions;
+    for (const slug of Object.keys(decisions)) {
+      const rec = decisions[slug];
+      const fm = rec.frontmatter ?? {};
+      const where = rec.path;
+      // Required fields → errors.
+      for (const field of ['id', 'date', 'status', 'title'] as const) {
+        const v = fm[field];
+        if (v === undefined || v === null || (typeof v === 'string' && v.trim() === '')) {
+          errors.push({ level: 'error', message: `decision ${where} is missing required frontmatter field "${field}"` });
+        }
+      }
+      if (typeof fm.status === 'string' && !VALID_DECISION_STATUSES.has(fm.status)) {
+        errors.push({ level: 'error', message: `decision ${where} has invalid status "${fm.status}" (expected accepted|superseded)` });
+      }
+      if (fm.date !== undefined && typeof fm.date === 'string' && fm.date.trim() !== '' && !ISO_DATE_RE.test(fm.date.trim())) {
+        warnings.push({ level: 'warning', message: `decision ${where} date "${fm.date}" is not YYYY-MM-DD` });
+      }
+      if (fm.status === 'superseded') {
+        const sb = fm.superseded_by;
+        if (typeof sb !== 'string' || sb.trim() === '') {
+          errors.push({ level: 'error', message: `decision ${where} has status:superseded but no superseded_by` });
+        } else if (!state.decisions[sb]) {
+          errors.push({ level: 'error', message: `decision ${where} superseded_by "${sb}" does not match a sibling decision file` });
+        } else if (sb === slug) {
+          errors.push({ level: 'error', message: `decision ${where} superseded_by cannot reference itself` });
+        }
+      } else if (fm.superseded_by !== undefined && fm.status !== 'superseded') {
+        warnings.push({ level: 'warning', message: `decision ${where} has superseded_by but status is "${fm.status ?? 'unset'}"` });
+      }
+      if (fm.related_items !== undefined && !Array.isArray(fm.related_items)) {
+        warnings.push({ level: 'warning', message: `decision ${where} related_items should be a list` });
+      }
+    }
+  }
+
   const allRefs = new Set(state.scopes.flatMap(s => s.layers.map(l => `${s.id}:${l.id}`)));
   for (const item of state.crossCuttingRoadmap ?? []) {
     const refs = [...(item.layers ?? []), ...(item.affects ?? [])];

package/src/api/routes/watch.ts

@@ -40,6 +40,8 @@ const IGNORE_GLOBS = [
   '**/*.swx',     // vim
   '**/*~',        // many editors' backup
   '**/4913',      // vim's pre-write probe
+  '**/*.tmp',     // simple atomic-rename staging
+  '**/*.tmp.*',   // tenboFs.ts atomic writes use `<file>.tmp.<PID>.<ts>` suffix
   '**/.DS_Store', // macOS
   '**/.git/**',
   '**/node_modules/**',

package/src/hooks/useApiPatch.ts

@@ -3,7 +3,8 @@ import type { Item } from '../types';
 import { tenboApi } from '../api/client';
 
 export function useApiPatch() {
-  return useCallback((scopeId: string, itemId: string, patch: Partial<Item>) => {
-    return tenboApi.patchItem(scopeId, itemId, patch);
+  return useCallback(async (scopeId: string, itemId: string, patch: Partial<Item>): Promise<Item> => {
+    const { item } = await tenboApi.patchItem(scopeId, itemId, patch);
+    return item;
   }, []);
 }

package/src/router/routes.ts

@@ -2,7 +2,7 @@ export type WorkspaceTab = typeof WORKSPACE_TABS[number];
 export type LayerTab = typeof LAYER_TABS[number];
 export type Mode = 'docs' | 'roadmap' | 'health';
 
-const WORKSPACE_TABS = ['overview', 'principles', 'glossary'] as const;
+const WORKSPACE_TABS = ['overview', 'principles', 'glossary', 'decisions'] as const;
 const LAYER_TABS = ['overview', 'purpose', 'files', 'docs'] as const;
 
 export type Route =

package/src/types.ts

@@ -55,6 +55,15 @@ export interface Item {
   risks?: string[];
   type?: 'feature' | 'bug' | 'refactor' | 'spike';
   priority?: Priority;
+  /**
+   * Goals this item advances. Either a list of goal IDs (e.g. ["g1", "g3"])
+   * matching IDs declared in `overview.md` Product goals section, or the
+   * literal string "exploratory" for items captured without a clear goal
+   * connection. Items lacking goal_ref entirely produce a validator warning
+   * (not an error) — they're surfaced for backfill but don't block anything.
+   * See sk-022 for context.
+   */
+  goal_ref?: string[] | 'exploratory';
   /** Optional multi-phase progress. When present, item-level `status` is derived. */
   phases?: Phase[];
   /**
@@ -161,6 +170,11 @@ export interface TenboState {
    * resolve to a real file. Absent when `.tenbo/specs/` does not exist.
    */
   specFiles?: Set<string>;
+  /**
+   * Decision records loaded from `.tenbo/decisions/`. Absent if the directory
+   * does not exist. Keyed by slug for `superseded_by` resolution.
+   */
+  decisions?: Record<string, DecisionRecord>;
 }
 
 export type ValidateLevel = 'error' | 'warning';
@@ -200,6 +214,30 @@ export interface WorkspaceContent {
   observationsMtime: number | null;
 }
 
+/**
+ * Project-level decision record loaded from `.tenbo/decisions/<slug>.md`.
+ * Only created when a future audit would re-suggest the same thing without
+ * the rationale. See `skill/templates/decision.md.tmpl` for the shape.
+ */
+export interface DecisionRecord {
+  /** repo-relative path, e.g. `.tenbo/decisions/foo.md` */
+  path: string;
+  /** filename slug without extension */
+  slug: string;
+  /** parsed frontmatter — values may be missing on malformed files */
+  frontmatter: {
+    id?: string;
+    date?: string;
+    status?: 'accepted' | 'superseded' | string;
+    title?: string;
+    related_items?: string[];
+    superseded_by?: string;
+    [k: string]: unknown;
+  };
+  /** body content after frontmatter (markdown) */
+  body: string;
+}
+
 export interface LayerContent {
   scope: string;
   layer: string;

package/src/ui/WorkspacePage/WorkspacePage.tsx

@@ -3,14 +3,16 @@ import type { TenboState } from '../../types';
 import { OverviewTab } from './tabs/OverviewTab';
 import { PrinciplesTab } from './tabs/PrinciplesTab';
 import { GlossaryTab } from './tabs/GlossaryTab';
+import { DecisionsTab } from './tabs/DecisionsTab';
 import styles from './WorkspacePage.module.css';
 
-const TABS: WorkspaceTab[] = ['overview', 'principles', 'glossary'];
+const TABS: WorkspaceTab[] = ['overview', 'principles', 'glossary', 'decisions'];
 
 const TAB_LABELS: Record<WorkspaceTab, string> = {
   'overview': 'Project overview',
   'principles': 'Principles',
   'glossary': 'Glossary',
+  'decisions': 'Decisions',
 };
 
 export function WorkspacePage(props: { tab: WorkspaceTab; navigate: (r: Route) => void; state: TenboState }) {
@@ -30,6 +32,7 @@ export function WorkspacePage(props: { tab: WorkspaceTab; navigate: (r: Route) =
         {props.tab === 'overview' && <OverviewTab state={props.state} navigate={props.navigate} />}
         {props.tab === 'principles' && <PrinciplesTab state={props.state} />}
         {props.tab === 'glossary' && <GlossaryTab state={props.state} />}
+        {props.tab === 'decisions' && <DecisionsTab state={props.state} />}
       </div>
     </div>
   );

package/src/ui/WorkspacePage/tabs/DecisionsTab.module.css

@@ -0,0 +1,176 @@
+.layout {
+  display: grid;
+  grid-template-columns: 280px 1fr;
+  gap: 24px;
+  align-items: start;
+}
+
+.list {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  border-right: 1px solid var(--console-mist);
+  padding-right: 12px;
+  max-height: calc(100vh - 200px);
+  overflow-y: auto;
+}
+
+.listItem {
+  display: block;
+  width: 100%;
+  text-align: left;
+  background: transparent;
+  border: 1px solid transparent;
+  border-radius: 4px;
+  padding: 8px 10px;
+  cursor: pointer;
+  font: inherit;
+  color: inherit;
+}
+.listItem:hover {
+  background: var(--console-mist, #f0f0f0);
+}
+.listItemActive {
+  background: var(--console-mist, #f0f0f0);
+  border-color: var(--console-fog, #ccc);
+}
+.listItemSuperseded {
+  opacity: 0.6;
+}
+
+.itemTitleRow {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  margin-bottom: 4px;
+}
+.itemTitle {
+  font-size: 13px;
+  font-weight: 600;
+  line-height: 1.3;
+  flex: 1;
+  min-width: 0;
+}
+
+.itemMeta {
+  display: flex;
+  justify-content: space-between;
+  gap: 8px;
+  font-size: 11px;
+  color: var(--console-fog, #888);
+}
+.itemSlug {
+  font-family: ui-monospace, SFMono-Regular, monospace;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.itemDate {
+  flex-shrink: 0;
+}
+.itemDateMissing {
+  color: #b58900;
+  flex-shrink: 0;
+}
+
+.badge {
+  font-size: 10px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  padding: 2px 6px;
+  border-radius: 3px;
+  flex-shrink: 0;
+}
+.badgeAccepted {
+  background: #d4edda;
+  color: #155724;
+}
+.badgeSuperseded {
+  background: #e2e3e5;
+  color: #495057;
+  text-decoration: line-through;
+}
+.badgeUnknown {
+  background: #fff3cd;
+  color: #856404;
+}
+
+.detail {
+  min-width: 0;
+}
+.detailHeader {
+  border-bottom: 1px solid var(--console-mist);
+  padding-bottom: 12px;
+  margin-bottom: 16px;
+}
+.detailTitleRow {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  margin-bottom: 4px;
+}
+.detailTitle {
+  font-size: 20px;
+  font-weight: 700;
+  margin: 0;
+  line-height: 1.3;
+}
+.detailMeta {
+  display: flex;
+  gap: 12px;
+  font-size: 12px;
+  color: var(--console-fog, #888);
+  font-family: ui-monospace, SFMono-Regular, monospace;
+}
+
+.supersededBanner {
+  margin-top: 10px;
+  padding: 8px 10px;
+  background: #fff3cd;
+  border-left: 3px solid #ffc107;
+  color: #5c4a00;
+  font-size: 13px;
+  border-radius: 2px;
+  text-align: left;
+}
+.successorLink {
+  background: none;
+  border: none;
+  padding: 0;
+  font: inherit;
+  color: var(--link, #0366d6);
+  text-decoration: underline;
+  cursor: pointer;
+}
+.successorLink:hover {
+  text-decoration: none;
+}
+
+.warn {
+  color: #b58900;
+}
+
+.emptyOuter {
+  max-width: 600px;
+  padding: 16px 0;
+}
+.emptyHeading {
+  font-size: 16px;
+  font-weight: 600;
+  margin: 0 0 12px;
+}
+.emptyBody {
+  font-size: 14px;
+  line-height: 1.5;
+  color: var(--console-fog, #555);
+  margin: 0 0 12px;
+}
+.emptyBody code {
+  font-family: ui-monospace, SFMono-Regular, monospace;
+  font-size: 12px;
+  background: var(--console-mist, #f0f0f0);
+  padding: 1px 4px;
+  border-radius: 3px;
+}

package/src/ui/WorkspacePage/tabs/DecisionsTab.tsx

@@ -0,0 +1,194 @@
+import { useState, useMemo } from 'react';
+import { Markdown } from '../../Markdown';
+import type { TenboState, DecisionRecord } from '../../../types';
+import styles from './DecisionsTab.module.css';
+
+function statusOf(d: DecisionRecord): 'accepted' | 'superseded' | 'unknown' {
+  const s = d.frontmatter.status;
+  if (s === 'accepted' || s === 'superseded') return s;
+  return 'unknown';
+}
+
+function titleOf(d: DecisionRecord): string {
+  const t = d.frontmatter.title;
+  if (typeof t === 'string' && t.trim()) return t;
+  return d.slug;
+}
+
+function dateOf(d: DecisionRecord): string | null {
+  const v = d.frontmatter.date;
+  if (typeof v === 'string' && v.trim()) return v;
+  if (v && typeof v === 'object' && Object.prototype.toString.call(v) === '[object Date]') {
+    return (v as Date).toISOString().slice(0, 10);
+  }
+  return null;
+}
+
+export function DecisionsTab({ state }: { state: TenboState }) {
+  const decisions = state.decisions;
+
+  const sorted = useMemo(() => {
+    if (!decisions) return [];
+    const list = Object.values(decisions);
+    // Sort: accepted before superseded, then by date desc, then by slug.
+    list.sort((a, b) => {
+      const sa = statusOf(a);
+      const sb = statusOf(b);
+      const supA = sa === 'superseded' ? 1 : 0;
+      const supB = sb === 'superseded' ? 1 : 0;
+      if (supA !== supB) return supA - supB;
+      const da = dateOf(a) ?? '';
+      const db = dateOf(b) ?? '';
+      if (da !== db) return db.localeCompare(da);
+      return a.slug.localeCompare(b.slug);
+    });
+    return list;
+  }, [decisions]);
+
+  const [selectedSlug, setSelectedSlug] = useState<string | null>(null);
+  const selected = selectedSlug ? decisions?.[selectedSlug] ?? null : sorted[0] ?? null;
+  const activeSlug = selected?.slug ?? null;
+
+  if (!decisions) {
+    return (
+      <div className={styles.emptyOuter}>
+        <h2 className={styles.emptyHeading}>No decision records yet</h2>
+        <p className={styles.emptyBody}>
+          Decision records capture project-level choices that a future audit
+          would otherwise re-suggest without context — &ldquo;we considered X, declined
+          because Y.&rdquo; They live in <code>.tenbo/decisions/&lt;slug&gt;.md</code>.
+        </p>
+        <p className={styles.emptyBody}>
+          See <code>skill/templates/decision.md.tmpl</code> for the file shape
+          (frontmatter + Context / Decision / Consequences / When to revisit).
+        </p>
+      </div>
+    );
+  }
+
+  if (sorted.length === 0) {
+    return (
+      <div className={styles.emptyOuter}>
+        <p className={styles.emptyBody}>
+          The <code>.tenbo/decisions/</code> directory exists but contains no
+          records yet.
+        </p>
+      </div>
+    );
+  }
+
+  return (
+    <div className={styles.layout}>
+      <aside className={styles.list} aria-label="Decision records">
+        {sorted.map((d) => {
+          const status = statusOf(d);
+          const date = dateOf(d);
+          const isActive = d.slug === activeSlug;
+          return (
+            <button
+              key={d.slug}
+              type="button"
+              className={`${styles.listItem} ${isActive ? styles.listItemActive : ''} ${status === 'superseded' ? styles.listItemSuperseded : ''}`}
+              onClick={() => setSelectedSlug(d.slug)}
+              aria-pressed={isActive}
+            >
+              <div className={styles.itemTitleRow}>
+                <span className={styles.itemTitle}>{titleOf(d)}</span>
+                <span
+                  className={`${styles.badge} ${
+                    status === 'accepted' ? styles.badgeAccepted :
+                    status === 'superseded' ? styles.badgeSuperseded :
+                    styles.badgeUnknown
+                  }`}
+                >
+                  {status === 'unknown' ? '?' : status}
+                </span>
+              </div>
+              <div className={styles.itemMeta}>
+                <span className={styles.itemSlug}>{d.slug}</span>
+                {date ? (
+                  <span className={styles.itemDate}>{date}</span>
+                ) : (
+                  <span className={styles.itemDateMissing} title="Missing date in frontmatter">
+                    no date
+                  </span>
+                )}
+              </div>
+            </button>
+          );
+        })}
+      </aside>
+
+      <section className={styles.detail}>
+        {selected ? (
+          <DecisionDetail decision={selected} all={decisions} onSelect={setSelectedSlug} />
+        ) : (
+          <p>Select a decision to view its body.</p>
+        )}
+      </section>
+    </div>
+  );
+}
+
+function DecisionDetail({
+  decision,
+  all,
+  onSelect,
+}: {
+  decision: DecisionRecord;
+  all: Record<string, DecisionRecord>;
+  onSelect: (slug: string) => void;
+}) {
+  const status = statusOf(decision);
+  const date = dateOf(decision);
+  const supersededBy = decision.frontmatter.superseded_by;
+  const successor = typeof supersededBy === 'string' ? all[supersededBy] : undefined;
+
+  return (
+    <article>
+      <header className={styles.detailHeader}>
+        <div className={styles.detailTitleRow}>
+          <h1 className={styles.detailTitle}>{titleOf(decision)}</h1>
+          <span
+            className={`${styles.badge} ${
+              status === 'accepted' ? styles.badgeAccepted :
+              status === 'superseded' ? styles.badgeSuperseded :
+              styles.badgeUnknown
+            }`}
+          >
+            {status === 'unknown' ? '?' : status}
+          </span>
+        </div>
+        <div className={styles.detailMeta}>
+          <span>{decision.path}</span>
+          {date ? <span>{date}</span> : <span className={styles.warn}>no date in frontmatter</span>}
+        </div>
+        {status === 'superseded' && (
+          <div className={styles.supersededBanner}>
+            Superseded
+            {typeof supersededBy === 'string' ? (
+              <>
+                {' by '}
+                {successor ? (
+                  <button
+                    type="button"
+                    className={styles.successorLink}
+                    onClick={() => onSelect(successor.slug)}
+                  >
+                    {titleOf(successor)} ({successor.slug})
+                  </button>
+                ) : (
+                  <code>{supersededBy}</code>
+                )}
+                {!successor && <span className={styles.warn}> — successor not found</span>}
+              </>
+            ) : (
+              <span className={styles.warn}> — no superseded_by reference</span>
+            )}
+          </div>
+        )}
+      </header>
+      <Markdown source={decision.body} />
+    </article>
+  );
+}