tenbo-dashboard 0.4.1 → 0.6.0

package/bin/tenbo-dashboard.mjs

@@ -39,6 +39,7 @@ const commands = {
   metrics: 'scripts/compute-metrics.ts',
   'init-check': 'scripts/init-check.ts',
   sync: 'scripts/sync.ts',
+  archive: 'scripts/archive.ts',
 };
 
 // Documented aliases for the bare-launch behavior. Users (and agents) reading
@@ -79,6 +80,8 @@ Usage:
   tenbo-dashboard init-check       Strict completeness check for fresh init (errors on missing skeletons, file_count:0, etc)
   tenbo-dashboard next-id <prefix> Allocate next roadmap item ID
   tenbo-dashboard metrics --all    Compute scope metrics
+  tenbo-dashboard archive          Move old done/dropped items to roadmap-archive.yaml
+                                   [--scope <id>] [--days 30] [--max 20]
   tenbo-dashboard --version        Print package version
   tenbo-dashboard help             Show this help
 

package/package.json

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

package/scripts/archive.ts

@@ -0,0 +1,88 @@
+/**
+ * archive.ts — CLI to move done/dropped roadmap items to roadmap-archive.yaml.
+ *
+ * Usage:
+ *   npx tenbo-dashboard archive [--scope <id>] [--days 30] [--max 20]
+ *
+ * --days  (default 30): only archive done/dropped items whose doc_update is older than N days.
+ * --max   (default 20): only trigger if done+dropped count exceeds this threshold per scope.
+ * --scope: limit to one scope (default: all scopes).
+ */
+import { findRepoRoot } from '../src/api/lib/repoRoot';
+import { readState, archiveItems } from '../src/api/lib/tenboFs';
+import type { Item } from '../src/types';
+import path from 'node:path';
+
+function parseArgs(argv: string[]): { scope?: string; days: number; max: number } {
+  let scope: string | undefined;
+  let days = 30;
+  let max = 20;
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--scope' && argv[i + 1]) {
+      scope = argv[++i];
+    } else if (argv[i] === '--days' && argv[i + 1]) {
+      days = parseInt(argv[++i], 10);
+    } else if (argv[i] === '--max' && argv[i + 1]) {
+      max = parseInt(argv[++i], 10);
+    }
+  }
+  return { scope, days, max };
+}
+
+function isOlderThanDays(docUpdate: string | undefined, days: number): boolean {
+  if (!docUpdate) return false;
+  const match = docUpdate.match(/^\d{4}-\d{2}-\d{2}$/);
+  if (!match) return false;
+  const itemDate = new Date(docUpdate);
+  const cutoff = new Date();
+  cutoff.setDate(cutoff.getDate() - days);
+  return itemDate <= cutoff;
+}
+
+function getArchivableIds(items: Item[], days: number, maxThreshold: number): string[] {
+  const doneDropped = items.filter(i => i.status === 'done' || i.status === 'dropped');
+  if (doneDropped.length <= maxThreshold) return [];
+  return doneDropped
+    .filter(i => isOlderThanDays(i.doc_update, days))
+    .map(i => i.id);
+}
+
+function isMain(): boolean {
+  try {
+    const invoked = process.argv[1] ? path.resolve(process.argv[1]) : '';
+    const here = path.resolve(new URL(import.meta.url).pathname);
+    return invoked === here;
+  } catch {
+    return false;
+  }
+}
+
+if (isMain()) {
+  const args = parseArgs(process.argv.slice(2));
+  const cwd = process.cwd();
+  const repoRoot = findRepoRoot(cwd) ?? path.resolve(cwd, '..', '..');
+
+  const state = readState(repoRoot);
+  const scopesToProcess = args.scope
+    ? state.scopes.filter(s => s.id === args.scope)
+    : state.scopes;
+
+  if (args.scope && scopesToProcess.length === 0) {
+    process.stderr.write(`Error: scope '${args.scope}' not found.\n`);
+    process.exit(1);
+  }
+
+  let totalArchived = 0;
+  for (const scope of scopesToProcess) {
+    const ids = getArchivableIds(scope.items, args.days, args.max);
+    if (ids.length > 0) {
+      archiveItems(repoRoot, scope.id, ids);
+      console.log(`Archived ${ids.length} items from scope '${scope.id}' to roadmap-archive.yaml`);
+      totalArchived += ids.length;
+    }
+  }
+
+  if (totalArchived === 0) {
+    console.log('No items eligible for archiving.');
+  }
+}

package/src/api/lib/health/agingSuperseded.ts

@@ -0,0 +1,76 @@
+import type { Item, Scope } from '../../../types';
+import type { Finding } from './types';
+
+const THIRTY_DAYS_MS = 30 * 24 * 3600 * 1000;
+
+/**
+ * Surfaces `later` items that are >30 days old and reference at least one
+ * done/dropped item (via spawned_from, superseded_by, or related).
+ * These are likely stale — either they should be dropped, completed, or
+ * explicitly re-justified with an updated note.
+ */
+export function analyzeAgingSuperseded(
+  scope: Scope,
+  allItems: Map<string, Item>,
+  now: number = Date.now(),
+): Finding[] {
+  const findings: Finding[] = [];
+
+  for (const item of scope.items) {
+    if (item.status !== 'later') continue;
+
+    const ageDays = itemAgeDays(item, now);
+    if (ageDays < 30) continue;
+
+    const refs = collectReferences(item);
+    if (refs.length === 0) continue;
+
+    const referencedDoneOrDropped = refs
+      .map(id => allItems.get(id))
+      .filter((ref): ref is Item => ref !== undefined && (ref.status === 'done' || ref.status === 'dropped'))
+      .map(ref => ({ id: ref.id, status: ref.status }));
+
+    if (referencedDoneOrDropped.length === 0) continue;
+
+    findings.push({
+      id: `${item.layer ?? scope.id}.aging-superseded.${item.id}`,
+      signal: 'aging-superseded',
+      severity: ageDays > 90 ? 'warning' : 'info',
+      confidence: 'medium',
+      layer: item.layer ?? scope.layers[0]?.id ?? scope.id,
+      target: item.id,
+      headline: `"${item.title}" is ${ageDays}d old in later, references ${referencedDoneOrDropped.length} done/dropped item(s)`,
+      suggestion: {
+        summary: 'Mark dropped, mark done, or update with a note explaining the delay',
+        rationale: `This item has been in "later" for ${ageDays} days and references items that have already shipped or been dropped. It may be stale.`,
+        action_kind: 'triage-item',
+      },
+      details: {
+        kind: 'aging-superseded',
+        item_id: item.id,
+        item_title: item.title,
+        age_days: ageDays,
+        referenced_items: referencedDoneOrDropped,
+      },
+    });
+  }
+
+  return findings;
+}
+
+function collectReferences(item: Item): string[] {
+  const refs: string[] = [];
+  if (item.spawned_from) refs.push(item.spawned_from);
+  if (item.superseded_by) refs.push(item.superseded_by);
+  if (item.related) refs.push(...item.related);
+  return refs;
+}
+
+function itemAgeDays(item: Item, now: number): number {
+  const docUpdate = item.doc_update;
+  if (docUpdate && /^\d{4}-\d{2}-\d{2}$/.test(docUpdate)) {
+    const ts = new Date(docUpdate).getTime();
+    return Math.floor((now - ts) / (24 * 3600 * 1000));
+  }
+  return THIRTY_DAYS_MS / (24 * 3600 * 1000) + 1; // assume old enough if no date
+}

package/src/api/lib/health/collectAll.ts

@@ -1,4 +1,4 @@
-import type { Scope } from '../../../types';
+import type { Item, Scope } from '../../../types';
 import type { Finding, Signal } from './types';
 import type { HealthConfig } from './config';
 import { resolveLayerFiles } from './layerFiles';
@@ -12,10 +12,12 @@ import type { ImportGraph } from './importGraph';
 import { analyzeDeadCode } from './deadCode';
 import { analyzeCoupling } from './coupling';
 import { analyzeRedundancy } from './redundancy';
+import { analyzeAgingSuperseded } from './agingSuperseded';
 
 interface AnalyzerArgs {
   repoRoot: string;
   scopeId: string;
+  scopePath?: string;
   layerId: string;
   files: string[];
   config: HealthConfig;
@@ -26,7 +28,8 @@ type AnalyzerFn = (args: AnalyzerArgs) => Finding[];
 const ANALYZERS: Record<Signal, AnalyzerFn | null> = {
   'hotspot-files':            ({ repoRoot, layerId, files, config }) => analyzeHotspotFiles(repoRoot, layerId, files, config),
   'aging-todos':              ({ repoRoot, layerId, files, config }) => analyzeAgingTodos(repoRoot, layerId, files, config),
-  'doc-drift':                ({ repoRoot, scopeId, layerId, files }) => analyzeDocDrift(repoRoot, scopeId, layerId, files),
+  'aging-superseded':         null, // scope-wide item analyzer, dispatched after the layer loop
+  'doc-drift':                ({ repoRoot, scopeId, layerId, files, scopePath }) => analyzeDocDrift(repoRoot, scopeId, layerId, files, scopePath),
   'test-coverage':            ({ repoRoot, layerId, files }) => analyzeTestCoverage(repoRoot, layerId, files),
   'architecture-compliance':  ({ layerId, files }) => analyzeArchCompliance(layerId, files),
   'dead-code':                ({ repoRoot, layerId, files, graph }) => graph ? analyzeDeadCode(repoRoot, layerId, files, graph) : [],
@@ -34,7 +37,7 @@ const ANALYZERS: Record<Signal, AnalyzerFn | null> = {
   'redundancy':               null, // Phase 4
 };
 
-export async function collectAll(repoRoot: string, scope: Scope, config: HealthConfig): Promise<Finding[]> {
+export async function collectAll(repoRoot: string, scope: Scope, config: HealthConfig, allItems?: Map<string, Item>): Promise<Finding[]> {
   const filesByLayer = resolveLayerFiles(repoRoot, scope);
   const allTsFiles = Object.values(filesByLayer).flat().filter(f => /\.tsx?$/.test(f));
   let graph: ImportGraph | undefined;
@@ -51,7 +54,7 @@ export async function collectAll(repoRoot: string, scope: Scope, config: HealthC
       if (!fn) continue;
       if (opted.has(signal)) continue;
       try {
-        out.push(...fn({ repoRoot, scopeId: scope.id, layerId: layer.id, files, config, graph }));
+        out.push(...fn({ repoRoot, scopeId: scope.id, scopePath: scope.path, layerId: layer.id, files, config, graph }));
       } catch (e) {
         // Analyzer failures don't break the whole report. Log and continue.
         console.error(`[health] analyzer ${signal} failed for layer ${layer.id}:`, e);
@@ -74,5 +77,15 @@ export async function collectAll(repoRoot: string, scope: Scope, config: HealthC
     return [] as Finding[];
   });
   out.push(...redundancyFindings.filter(f => !(config.ignore.layer_signals[f.layer] ?? []).includes('redundancy')));
+
+  // Aging-superseded is item-based (not file-based) — run once per scope
+  try {
+    const itemMap = allItems ?? new Map(scope.items.map(i => [i.id, i]));
+    const agingFindings = analyzeAgingSuperseded(scope, itemMap);
+    out.push(...agingFindings.filter(f => !(config.ignore.layer_signals[f.layer] ?? []).includes('aging-superseded')));
+  } catch (e) {
+    console.error('[health] aging-superseded failed:', e);
+  }
+
   return out;
 }

package/src/api/lib/health/docDrift.test.ts

@@ -31,6 +31,24 @@ describe('analyzeDocDrift', () => {
     rmSync(root, { recursive: true, force: true });
   });
 
+  it('does NOT emit missing-ref when file exists under the scope path', () => {
+    const root = mkdtempSync(path.join(tmpdir(), 'drift-'));
+    const scopePath = 'tenbo-dashboard';
+    mkdirSync(path.join(root, scopePath, 'src'), { recursive: true });
+    writeFileSync(path.join(root, scopePath, 'src/main.tsx'), 'export default 1;\n');
+    mkdirSync(path.join(root, '.tenbo/scopes/dashboard/layers/lyr'), { recursive: true });
+    writeFileSync(
+      path.join(root, '.tenbo/scopes/dashboard/layers/lyr/code-map.md'),
+      'Entry point: `src/main.tsx`.\n',
+    );
+    const findings = analyzeDocDrift(root, 'dashboard', 'lyr', [], scopePath);
+    const broken = findings.find(f =>
+      f.details.kind === 'doc-drift' && f.details.drift_type === 'missing-ref'
+    );
+    expect(broken).toBeUndefined();
+    rmSync(root, { recursive: true, force: true });
+  });
+
   it('emits unreferenced-file info finding when a layer file is not mentioned in code-map.md', () => {
     const root = mkdtempSync(path.join(tmpdir(), 'drift-'));
     mkdirSync(path.join(root, 'apps/editor/src'), { recursive: true });

package/src/api/lib/health/docDrift.ts

@@ -22,6 +22,7 @@ export function analyzeDocDrift(
   scopeId: string,
   layerId: string,
   layerFiles: string[],
+  scopePath?: string,
 ): Finding[] {
   const docPath = path.join(repoRoot, '.tenbo/scopes', scopeId, 'layers', layerId, 'code-map.md');
   if (!existsSync(docPath)) return [];
@@ -34,7 +35,9 @@ export function analyzeDocDrift(
   // 1. missing-ref: file in code-map.md doesn't exist on disk
   const broken: string[] = [];
   for (const ref of refs) {
-    if (!existsSync(path.join(repoRoot, ref))) broken.push(ref);
+    const existsAtRoot = existsSync(path.join(repoRoot, ref));
+    const existsAtScope = scopePath ? existsSync(path.join(repoRoot, scopePath, ref)) : false;
+    if (!existsAtRoot && !existsAtScope) broken.push(ref);
   }
   if (broken.length > 0) {
     const severity = broken.length >= 3 ? 'critical' : 'warning';

package/src/api/lib/health/layerFiles.test.ts

@@ -8,16 +8,16 @@ describe('resolveLayerFiles', () => {
 
   it('returns repo-relative paths bucketed by layer', () => {
     if (!repoRoot) throw new Error('Could not find repo root');
-    // Use a real fixture: this repo's editor scope.
+    // Use a real fixture: this repo's health directory which has known .ts files.
     const scope: Scope = {
-      id: 'editor',
-      path: 'apps/editor',
+      id: 'dashboard',
+      path: 'tenbo-dashboard/src/api/lib/health',
       description: '',
       layers: [{
         id: 'visual-canvas',
         name: 'Visual Canvas',
         description: '',
-        files: ['src/domains/canvas/**'],
+        files: ['*.ts'],
         dependencies: { inbound: [], outbound: [], external: [] },
       }],
       items: [],
@@ -26,7 +26,7 @@ describe('resolveLayerFiles', () => {
     expect(result['visual-canvas']).toBeDefined();
     expect(result['visual-canvas'].length).toBeGreaterThan(0);
     // Paths are repo-relative
-    expect(result['visual-canvas'][0]).toMatch(/^apps\/editor\/src\/domains\/canvas\//);
+    expect(result['visual-canvas'][0]).toMatch(/^tenbo-dashboard\/src\/api\/lib\/health\//);
   });
 
   it('returns empty array for layer with no matching files', () => {

package/src/api/lib/health/types.ts

@@ -9,6 +9,7 @@ export type Signal =
   | 'doc-drift'
   | 'test-coverage'
   | 'aging-todos'
+  | 'aging-superseded'
   | 'architecture-compliance'
   | 'redundancy';
 
@@ -20,7 +21,8 @@ export type ActionKind =
   | 'move-file'
   | 'update-doc'
   | 'add-test'
-  | 'resolve-todo';
+  | 'resolve-todo'
+  | 'triage-item';
 
 export interface Suggestion {
   summary: string;       // imperative one-liner
@@ -36,6 +38,7 @@ export type FindingDetails =
   | { kind: 'doc-drift'; drift_type: 'missing-ref' | 'unreferenced-file' | 'stale-section'; doc_path: string; doc_mtime_iso: string | null; code_mtime_iso: string | null; affected_files: string[] }
   | { kind: 'test-coverage'; suggested_test_path: string }
   | { kind: 'aging-todos'; line: number; age_days: number; commit_hash: string; author: string; text: string; context: string }
+  | { kind: 'aging-superseded'; item_id: string; item_title: string; age_days: number; referenced_items: { id: string; status: string }[] }
   | { kind: 'architecture-compliance'; expected_path_pattern: string; actual_path: string; rule: string }
   | { kind: 'redundancy'; copies: { path: string; lines: [number, number] }[]; similarity_pct: number };
 
@@ -66,6 +69,7 @@ export const SIGNAL_WEIGHTS_DEFAULT: Signal[] = [
   'doc-drift',
   'test-coverage',
   'aging-todos',
+  'aging-superseded',
 ];
 
 export const CONFIDENCE_RANK: Record<Confidence, number> = {

package/src/api/lib/tenboFs.ts

@@ -1,9 +1,9 @@
 import { readFileSync, writeFileSync, readdirSync, existsSync, renameSync, statSync, type Stats } from 'node:fs';
 import path from 'node:path';
-import { parse as parseSimple } from 'yaml';
+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'); }
 
@@ -70,6 +70,13 @@ function readRoadmap(repoRoot: string, scopeId: string): Item[] {
   return data?.items ?? [];
 }
 
+export function readRoadmapArchive(repoRoot: string, scopeId: string): Item[] {
+  const file = path.join(tenboDir(repoRoot), 'scopes', scopeId, 'roadmap-archive.yaml');
+  if (!existsSync(file)) return [];
+  const data = getCached(file, 'roadmap-archive-yaml', (text) => 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 {};
@@ -186,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 => ({
@@ -194,6 +238,7 @@ export function readState(repoRoot: string): TenboState {
     description: ref.description,
     layers: readArchitecture(repoRoot, ref.id),
     items: readRoadmap(repoRoot, ref.id),
+    archivedItems: readRoadmapArchive(repoRoot, ref.id),
   }));
   const narratives = scopes.reduce<Record<string, string>>((acc, s) => {
     return Object.assign(acc, readNarratives(repoRoot, s.id));
@@ -214,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;
 }
 
@@ -242,3 +289,39 @@ export function reorderItems(repoRoot: string, scopeId: string, idsInOrder: stri
   reorderSeqItems(doc, 'items', idsInOrder);
   atomicWrite(file, stringifyYaml(doc));
 }
+
+/**
+ * Move items from roadmap.yaml to roadmap-archive.yaml for the given scope.
+ * Creates the archive file if it doesn't exist. Uses atomic writes for both files.
+ */
+export function archiveItems(repoRoot: string, scopeId: string, itemIds: string[]): void {
+  if (itemIds.length === 0) return;
+
+  const roadmapFile = path.join(tenboDir(repoRoot), 'scopes', scopeId, 'roadmap.yaml');
+  const archiveFile = path.join(tenboDir(repoRoot), 'scopes', scopeId, 'roadmap-archive.yaml');
+
+  // Read roadmap and find matching items
+  const roadmapText = readFileSync(roadmapFile, 'utf8');
+  const roadmapData = parseSimple(roadmapText) as any;
+  const allItems: Item[] = roadmapData?.items ?? [];
+
+  const idsToArchive = new Set(itemIds);
+  const itemsToArchive = allItems.filter(i => idsToArchive.has(i.id));
+  const remainingItems = allItems.filter(i => !idsToArchive.has(i.id));
+
+  if (itemsToArchive.length === 0) return;
+
+  // Read existing archive
+  let archiveItems: Item[] = [];
+  if (existsSync(archiveFile)) {
+    const archiveData = parseSimple(readFileSync(archiveFile, 'utf8')) as any;
+    archiveItems = archiveData?.items ?? [];
+  }
+
+  // Append archived items
+  archiveItems.push(...itemsToArchive);
+
+  // Write both files atomically
+  atomicWrite(roadmapFile, yamlStringify({ items: remainingItems }, { lineWidth: 0, blockQuote: 'literal' }));
+  atomicWrite(archiveFile, yamlStringify({ items: archiveItems }, { lineWidth: 0, blockQuote: 'literal' }));
+}

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', () => {