tenbo-dashboard 0.4.1 → 0.5.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.5.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,6 +1,6 @@
 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';
@@ -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 {};
@@ -194,6 +201,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));
@@ -242,3 +250,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.ts

@@ -22,12 +22,38 @@ export function validate(state: TenboState): ValidateResult {
   // Collect every known roadmap-item id across scopes + cross-cutting roadmap.
   // Used by the relationship validator (`spawned_from`, `related`) to flag
   // references that don't resolve to anything in the workspace.
+  // Also includes archived items so references to them don't produce warnings.
   const allItemIds = new Set<string>();
   for (const scope of state.scopes) {
     for (const item of scope.items) allItemIds.add(item.id);
+    for (const item of scope.archivedItems ?? []) allItemIds.add(item.id);
   }
   for (const item of state.crossCuttingRoadmap ?? []) allItemIds.add(item.id);
 
+  const validateSupersededBy = (item: Item, scopeId?: string) => {
+    if (item.superseded_by === undefined) return;
+    const sb = item.superseded_by;
+    if (typeof sb !== 'string' || !ITEM_ID_RE.test(sb)) {
+      errors.push({ level: 'error', message: `item "${item.id}" superseded_by "${sb}" has invalid id format`, scope: scopeId, itemId: item.id });
+      return;
+    }
+    if (sb === item.id) {
+      errors.push({ level: 'error', message: `item "${item.id}" superseded_by cannot reference itself`, scope: scopeId, itemId: item.id });
+      return;
+    }
+    if (!allItemIds.has(sb)) {
+      warnings.push({ level: 'warning', message: `${item.id} superseded_by references unknown id '${sb}'`, scope: scopeId, itemId: item.id });
+    }
+    if (item.status !== 'dropped') {
+      warnings.push({ level: 'warning', message: `${item.id} has superseded_by but status is "${item.status}" (expected "dropped")`, scope: scopeId, itemId: item.id });
+    }
+    // Cycle check: if the superseder also has superseded_by pointing back
+    const superseder = [...state.scopes.flatMap(s => s.items), ...(state.crossCuttingRoadmap ?? [])].find(i => i.id === sb);
+    if (superseder?.superseded_by === item.id) {
+      errors.push({ level: 'error', message: `cycle: "${item.id}" superseded_by "${sb}" which is superseded_by "${item.id}"`, scope: scopeId, itemId: item.id });
+    }
+  };
+
   const validateRelationships = (item: Item, scopeId?: string) => {
     if (item.spawned_from !== undefined) {
       const sf = item.spawned_from;
@@ -213,6 +239,9 @@ export function validate(state: TenboState): ValidateResult {
       // Relationship validation (Phase 5 of x-001).
       validateRelationships(item, scope.id);
 
+      // Superseded-by validation (sk-015).
+      validateSupersededBy(item, scope.id);
+
       // Spec-link lifecycle validation (Phase 6 of x-001).
       validateSpecLinks(item, scope.id);
 
@@ -304,6 +333,7 @@ export function validate(state: TenboState): ValidateResult {
       }
     }
     validateRelationships(item);
+    validateSupersededBy(item);
     validateSpecLinks(item);
   }
 

package/src/api/plugin.ts

@@ -8,6 +8,7 @@ import { openRoute } from './routes/open';
 import { watchRoute } from './routes/watch';
 import { layerDocsRoute } from './routes/layerDocs';
 import { layerContentRoute } from './routes/layerContent';
+import { archiveRoute } from './routes/archive';
 
 export function tenboApiPlugin(): Plugin {
   return {
@@ -28,6 +29,7 @@ export function tenboApiPlugin(): Plugin {
       server.httpServer?.on('close', () => { void watch.close(); });
       server.middlewares.use(layerDocsRoute(repoRoot));
       server.middlewares.use(layerContentRoute(repoRoot));
+      server.middlewares.use(archiveRoute(repoRoot));
     },
   };
 }

package/src/api/routes/archive.ts

@@ -0,0 +1,60 @@
+import type { Connect } from 'vite';
+import { readState, archiveItems } from '../lib/tenboFs';
+import { readBody, json, withErrorHandling } from '../lib/http';
+import type { Item } from '../../types';
+
+interface ArchiveRequest {
+  scopeId?: string;
+  days?: number;
+  maxThreshold?: number;
+}
+
+interface ArchiveResultEntry {
+  archived: string[];
+  scopeId: string;
+}
+
+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);
+}
+
+export function archiveRoute(repoRoot: string): Connect.NextHandleFunction {
+  return withErrorHandling(async (req, res, next) => {
+    if (req.url !== '/api/archive' || req.method !== 'POST') return next();
+
+    const body = await readBody<ArchiveRequest>(req);
+    const days = body.days ?? 30;
+    const maxThreshold = body.maxThreshold ?? 20;
+
+    const state = readState(repoRoot);
+    const results: ArchiveResultEntry[] = [];
+
+    const scopesToProcess = body.scopeId
+      ? state.scopes.filter(s => s.id === body.scopeId)
+      : state.scopes;
+
+    for (const scope of scopesToProcess) {
+      const ids = getArchivableIds(scope.items, days, maxThreshold);
+      if (ids.length > 0) {
+        archiveItems(repoRoot, scope.id, ids);
+        results.push({ archived: ids, scopeId: scope.id });
+      }
+    }
+
+    json(res, results);
+  });
+}

package/src/router/useHashRoute.test.ts

@@ -2,9 +2,11 @@ import { describe, it, expect } from 'vitest';
 import { parseHash, formatRoute } from './routes.js';
 
 describe('parseHash', () => {
-  it('defaults to docs project overview on empty hash', () => {
-    expect(parseHash('')).toEqual({ kind: 'docs-project', tab: 'overview' });
-    expect(parseHash('#/')).toEqual({ kind: 'docs-project', tab: 'overview' });
+  it('defaults to roadmap on empty hash', () => {
+    expect(parseHash('')).toEqual({ kind: 'roadmap' });
+    expect(parseHash('#/')).toEqual({ kind: 'roadmap' });
+  });
+  it('defaults to docs project overview on #/docs', () => {
     expect(parseHash('#/docs')).toEqual({ kind: 'docs-project', tab: 'overview' });
   });
   it('parses docs project tab', () => {

package/src/types.ts

@@ -64,6 +64,12 @@ export interface Item {
    * the new item should set `spawned_from` to the dispatching item's id.
    */
   spawned_from?: string;
+  /**
+   * The id of the item that replaced/superseded this one. When set, the item's
+   * status should be `dropped`. The validator enforces this constraint and checks
+   * for cycles and dangling references.
+   */
+  superseded_by?: string;
   /**
    * Peer relationships. Any number of ids in the same format. Order is not significant.
    * Not parent–child — for that use `spawned_from`.
@@ -102,6 +108,7 @@ export interface Scope {
   description: string;
   layers: Layer[];
   items: Item[];
+  archivedItems?: Item[];
 }
 
 export interface CrossCutting {

package/src/ui/ArchivedContext.ts

@@ -0,0 +1,12 @@
+import { createContext, useContext } from 'react';
+
+/**
+ * Set of item IDs that came from roadmap-archive.yaml.
+ * Provided by RoadmapPage so any descendant (ItemCard, TaskList row)
+ * can style archived items without prop drilling.
+ */
+export const ArchivedIdsContext = createContext<ReadonlySet<string>>(new Set());
+
+export function useArchivedIds(): ReadonlySet<string> {
+  return useContext(ArchivedIdsContext);
+}

package/src/ui/ItemCard.module.css

@@ -20,6 +20,15 @@
 .cardDone:hover {
   opacity: 1;
 }
+
+/* Archived items are even more subtle — dashed border signals "read-only historical". */
+.cardArchived {
+  opacity: 0.45;
+  border: 1px dashed var(--console-mist);
+}
+.cardArchived:hover {
+  opacity: 0.8;
+}
 .card:focus-visible {
   outline: 2px solid var(--signal-cyan);
   outline-offset: 2px;
@@ -68,6 +77,15 @@
   white-space: nowrap;
 }
 
+.archivedChip {
+  display: inline-flex;
+  align-items: center;
+  color: var(--console-smoke);
+  padding: 1px 4px;
+  border-radius: var(--r-sm);
+  background: var(--console-soot);
+}
+
 .titleInput {
   width: 100%;
   font: inherit;

package/src/ui/ItemCard.tsx

@@ -1,9 +1,10 @@
 import { useState } from 'react';
 import { useSortable } from '@dnd-kit/sortable';
 import { CSS } from '@dnd-kit/utilities';
-import { CornerLeftUp, ArrowLeftRight } from 'lucide-react';
+import { Archive, CornerLeftUp, ArrowLeftRight } from 'lucide-react';
 import type { Item } from '../types';
 import { effectiveStatus, phaseProgress } from '../api/lib/phases';
+import { useArchivedIds } from './ArchivedContext';
 import styles from './ItemCard.module.css';
 
 interface Props {
@@ -18,21 +19,21 @@ export function ItemCard({ item, onClick, onTitleEdit, onDescEdit }: Props) {
   const dragStyle = {
     transform: CSS.Translate.toString(transform),
     transition,
-    opacity: isDragging ? 0.4 : 1,
+    ...(isDragging ? { opacity: 0.4 } : {}),
   };
   const [editing, setEditing] = useState<null | 'title' | 'desc'>(null);
   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';
+  const archivedIds = useArchivedIds();
+  const isArchived = archivedIds.has(item.id);
+  const status = effectiveStatus(item);
+  const isDimmed = status === 'done' || status === 'dropped';
 
   return (
     <div
       ref={setNodeRef}
-      className={`${styles.card}${isDone ? ` ${styles.cardDone}` : ''}`}
+      className={`${styles.card}${isDimmed ? ` ${styles.cardDone}` : ''}${isArchived ? ` ${styles.cardArchived}` : ''}`}
       style={dragStyle}
       {...attributes}
       {...listeners}
@@ -46,6 +47,11 @@ export function ItemCard({ item, onClick, onTitleEdit, onDescEdit }: Props) {
       <div className={styles.id}>
         {item.priority && <span className={`${styles.priority} ${styles[item.priority]}`}>{item.priority.toUpperCase()}</span>}
         {item.id}
+        {isArchived && (
+          <span className={styles.archivedChip} title="Archived item" aria-label="Archived">
+            <Archive size={10} strokeWidth={1.75} />
+          </span>
+        )}
         {item.spawned_from && (
           <span
             className={styles.relChip}

package/src/ui/LayerDetailPage/LayerDetailPage.tsx

@@ -19,6 +19,7 @@ const SIGNAL_LABELS: Record<Signal, string> = {
   'doc-drift': 'Doc drift',
   'test-coverage': 'Test coverage',
   'aging-todos': 'Aging TODOs',
+  'aging-superseded': 'Stale later items',
   'architecture-compliance': 'Architecture compliance',
   'redundancy': 'Redundancy',
 };

package/src/ui/RoadmapPage/RoadmapPage.module.css

@@ -91,3 +91,25 @@
 .viewBtn:hover:not(.viewBtnActive) {
   color: var(--console-snow);
 }
+
+/* Archive toggle — pill style, matches viewBtn feel */
+.archiveBtn {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  padding: 4px 10px;
+  border-radius: var(--r-md);
+  font-size: 12px;
+  font-weight: 500;
+  color: var(--console-fog);
+  background: var(--console-iron);
+  transition: background var(--dur-state) var(--ease), color var(--dur-state) var(--ease);
+  white-space: nowrap;
+}
+.archiveBtn:hover {
+  color: var(--console-snow);
+}
+.archiveBtnActive {
+  background: var(--console-mist);
+  color: var(--signal-cyan);
+}

package/src/ui/RoadmapPage/RoadmapPage.tsx

@@ -1,5 +1,5 @@
 import { useMemo, useState } from 'react';
-import { Columns2, List } from 'lucide-react';
+import { Archive, Columns2, List } from 'lucide-react';
 import { DndContext, type DragEndEvent, PointerSensor, useSensor, useSensors } from '@dnd-kit/core';
 import { LayerKanban } from '../LayerKanban';
 import { TaskList, type FlatItem } from '../TaskList';
@@ -7,6 +7,7 @@ import { effectiveStatus } from '../../api/lib/phases';
 import { tenboApi } from '../../api/client';
 import type { Route } from '../../router/routes';
 import type { Item, Layer, Status, TenboState } from '../../types';
+import { ArchivedIdsContext } from '../ArchivedContext';
 import styles from './RoadmapPage.module.css';
 
 const GENERAL_SCOPE = 'general';
@@ -42,12 +43,25 @@ export function RoadmapPage({ state, scopeFilter, layerFilter, navigate, onCardC
   const sensors = useSensors(useSensor(PointerSensor, { activationConstraint: { distance: 4 } }));
   const [view, setView] = useState<'kanban' | 'list'>('kanban');
   const [search, setSearch] = useState('');
+  const [showArchived, setShowArchived] = useState(false);
+
+  /** IDs of archived items so we can tag them visually. */
+  const archivedIds = useMemo(() => {
+    const s = new Set<string>();
+    for (const scope of state.scopes) for (const i of scope.archivedItems ?? []) s.add(i.id);
+    return s;
+  }, [state]);
+
+  const totalArchived = archivedIds.size;
 
   const itemBySource = useMemo(() => {
     const m = new Map<string, { scopeId: string; item: Item }>();
-    for (const s of state.scopes) for (const i of s.items) m.set(i.id, { scopeId: s.id, item: i });
+    for (const s of state.scopes) {
+      for (const i of s.items) m.set(i.id, { scopeId: s.id, item: i });
+      if (showArchived) for (const i of s.archivedItems ?? []) m.set(i.id, { scopeId: s.id, item: i });
+    }
     return m;
-  }, [state]);
+  }, [state, showArchived]);
 
   const crossCuttingItems = state.crossCuttingRoadmap ?? [];
   const showGeneral = !scopeFilter || scopeFilter === GENERAL_SCOPE;
@@ -63,8 +77,12 @@ export function RoadmapPage({ state, scopeFilter, layerFilter, navigate, onCardC
     item.title.toLowerCase().includes(q) ||
     (item.description ?? '').toLowerCase().includes(q);
 
+  /** Merge active + archived items per scope when toggle is on. */
+  const scopeItems = (s: typeof state.scopes[number]) =>
+    showArchived ? [...s.items, ...(s.archivedItems ?? [])] : s.items;
+
   const allItems = [
-    ...visibleScopes.flatMap((s) => s.items).filter((i) => (!layerFilter || i.layer === layerFilter) && matchesSearch(i)),
+    ...visibleScopes.flatMap((s) => scopeItems(s)).filter((i) => (!layerFilter || i.layer === layerFilter) && matchesSearch(i)),
     ...visibleGeneral.filter(matchesSearch),
   ];
 
@@ -72,7 +90,7 @@ export function RoadmapPage({ state, scopeFilter, layerFilter, navigate, onCardC
     const result: FlatItem[] = [];
     for (const scope of visibleScopes) {
       const layerMap = new Map(scope.layers.map(l => [l.id, l.name]));
-      for (const item of scope.items) {
+      for (const item of scopeItems(scope)) {
         if (layerFilter && item.layer !== layerFilter) continue;
         if (!matchesSearch(item)) continue;
         result.push({ item, scopeId: scope.id, layerName: item.layer ? layerMap.get(item.layer) : undefined });
@@ -83,7 +101,7 @@ export function RoadmapPage({ state, scopeFilter, layerFilter, navigate, onCardC
     }
     return result;
   // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [state, scopeFilter, layerFilter, search]);
+  }, [state, scopeFilter, layerFilter, search, showArchived]);
 
   const handleDragEnd = async (e: DragEndEvent) => {
     const activeId = String(e.active.id);
@@ -109,6 +127,7 @@ export function RoadmapPage({ state, scopeFilter, layerFilter, navigate, onCardC
   };
 
   return (
+    <ArchivedIdsContext.Provider value={archivedIds}>
     <DndContext sensors={sensors} onDragEnd={handleDragEnd}>
       <div className={styles.stickyBar}>
         <RoadmapFilterBar
@@ -121,6 +140,9 @@ export function RoadmapPage({ state, scopeFilter, layerFilter, navigate, onCardC
           allItems={allItems}
           search={search}
           onSearchChange={setSearch}
+          showArchived={showArchived}
+          onToggleArchived={() => setShowArchived((v) => !v)}
+          archivedCount={totalArchived}
         />
       </div>
       <main style={{ padding: view === 'list' ? '16px 0 0' : 16 }}>
@@ -142,7 +164,7 @@ export function RoadmapPage({ state, scopeFilter, layerFilter, navigate, onCardC
                       layer={layer}
                       depth={depth}
                       alwaysOpen={!!layerFilter}
-                      items={scope.items.filter((i) => i.layer === layer.id && matchesSearch(i))}
+                      items={scopeItems(scope).filter((i) => i.layer === layer.id && matchesSearch(i))}
                       onCardClick={(item) => onCardClick(scope.id, item)}
                       onTitleEdit={(id, title) => onPatch(scope.id, id, { title })}
                       onDescEdit={(id, desc) => onPatch(scope.id, id, { description: desc })}
@@ -166,10 +188,11 @@ export function RoadmapPage({ state, scopeFilter, layerFilter, navigate, onCardC
         )}
       </main>
     </DndContext>
+    </ArchivedIdsContext.Provider>
   );
 }
 
-function RoadmapFilterBar({ scopes, scopeFilter, layerFilter, navigate, view, onViewChange, allItems, search, onSearchChange }: {
+function RoadmapFilterBar({ scopes, scopeFilter, layerFilter, navigate, view, onViewChange, allItems, search, onSearchChange, showArchived, onToggleArchived, archivedCount }: {
   scopes: TenboState['scopes'];
   scopeFilter: string | undefined;
   layerFilter: string | undefined;
@@ -179,9 +202,12 @@ function RoadmapFilterBar({ scopes, scopeFilter, layerFilter, navigate, view, on
   allItems: Item[];
   search: string;
   onSearchChange: (v: string) => void;
+  showArchived: boolean;
+  onToggleArchived: () => void;
+  archivedCount: number;
 }) {
   const activeScope = scopeFilter && scopeFilter !== GENERAL_SCOPE ? scopes.find((s) => s.id === scopeFilter) : undefined;
-  const counts = { now: 0, next: 0, later: 0, done: 0 };
+  const counts = { now: 0, next: 0, later: 0, done: 0, dropped: 0 };
   for (const i of allItems) counts[effectiveStatus(i)]++;
 
   return (
@@ -242,6 +268,18 @@ function RoadmapFilterBar({ scopes, scopeFilter, layerFilter, navigate, view, on
         aria-label="Search tasks by title"
       />
 
+      {archivedCount > 0 && (
+        <button
+          className={`${styles.archiveBtn} ${showArchived ? styles.archiveBtnActive : ''}`}
+          onClick={onToggleArchived}
+          aria-pressed={showArchived}
+          title={showArchived ? 'Hide archived items' : `Show ${archivedCount} archived item${archivedCount === 1 ? '' : 's'}`}
+        >
+          <Archive size={13} strokeWidth={1.75} />
+          {archivedCount}
+        </button>
+      )}
+
       {/* Counts — far right */}
       <div className={styles.filterSpacer} />
       <div className={styles.counts}>

package/src/ui/SummaryStrip.tsx

@@ -3,7 +3,7 @@ import { effectiveStatus } from '../api/lib/phases';
 import styles from './SummaryStrip.module.css';
 
 export function SummaryStrip({ items }: { items: Item[] }) {
-  const counts = { now: 0, next: 0, later: 0, done: 0 };
+  const counts = { now: 0, next: 0, later: 0, done: 0, dropped: 0 };
   for (const i of items) counts[effectiveStatus(i)]++;
   return (
     <div className={styles.strip}>