feat: implement archiving functionality with frontmatter updates and add frontmatter reading helper

Author: Marvin Zhang

…tool-redesign-first-principles/README.md …tool-redesign-first-principles/README.mdspecs/050-tool-redesign-first-principles/README.md renamed to specs/archived/050-tool-redesign-first-principles/README.md specs/050-tool-redesign-first-principles/README.md renamed to specs/archived/050-tool-redesign-first-principles/README.md

@@ -1,5 +1,5 @@
 ---
-status: planned
+status: archived
 created: '2025-11-05'
 tags:
   - architecture
@@ -15,12 +15,15 @@ related:
   - 048-spec-complexity-analysis
   - 043-official-launch-02
 created_at: '2025-11-05T00:00:00Z'
-updated_at: '2025-11-05T05:03:54.951Z'
+updated_at: '2025-11-10T07:50:03.476Z'
+transitions:
+  - status: archived
+    at: '2025-11-10T07:50:03.476Z'
 ---
 
 # Tool Redesign: First Principles Application
 
-> **Status**: 🗓️ Planned · **Priority**: Medium · **Created**: 2025-11-05 · **Tags**: architecture, cli, mcp, redesign, first-principles, dx, v0.3.0
+> **Status**: 📦 Archived · **Priority**: Medium · **Created**: 2025-11-05 · **Tags**: architecture, cli, mcp, redesign, first-principles, dx, v0.3.0
 
 **Project**: lean-spec  
 **Team**: Core Development
@@ -380,3 +383,18 @@ We'll know this succeeded when:
 ---
 
 **Remember**: We're not just building better tools. We're proving that LeanSpec philosophy creates superior user experiences when applied systematically.
+
+---
+
+## Archive Note
+
+**Archived**: 2025-11-10
+
+**Reason**: Spec was too broad and many of its proposed improvements have already been implemented incrementally through other specs:
+- Spec 039: simplify-viewer-commands
+- Spec 045: unified-dashboard  
+- Spec 046: stats-dashboard-refactor
+- Spec 051: docs-system-prompt-principles
+- Spec 049: leanspec-first-principles
+
+**Key Learning**: The 7-week comprehensive redesign plan conflicted with LeanSpec's own "Progressive Disclosure" principle. Better to make incremental improvements as pain is felt rather than big-bang redesigns. The current CLI is already well-organized with grouped commands, and the MCP server functions effectively. This spec itself demonstrates why we should practice what we preach: start simple, add complexity when needed.

src/commands.test.ts

@@ -8,6 +8,7 @@ import {
   initTestProject,
   createTestSpec,
   readSpecFile,
+  readSpecFrontmatter,
   dirExists,
   getTestDate,
   type TestContext,
@@ -136,23 +137,29 @@ describe('archiveSpec', () => {
     await expect(archiveSpec(nonExistentPath)).rejects.toThrow();
   });
 
-  it('should preserve spec content when archiving', async () => {
+  it('should update metadata when archiving', async () => {
     const date = getTestDate();
     const specName = '001-test-feature';
-    const content = '# Test Feature\n\nTest content';
     const specDir = await createTestSpec(ctx.tmpDir, date, specName, {
       status: 'complete',
       created: '2024-11-01',
-    }, content);
-
-    const originalContent = await readSpecFile(specDir);
+    });
 
     await archiveSpec(specDir);
 
     const archivedPath = path.join(ctx.tmpDir, 'specs', 'archived', specName);
-    const archivedContent = await readSpecFile(archivedPath);
+    const fm = await readSpecFrontmatter(archivedPath);
 
-    expect(archivedContent).toBe(originalContent);
+    // Verify status was updated to archived
+    expect(fm.status).toBe('archived');
+    
+    // Verify updated_at was set
+    expect(fm.updated_at).toBeDefined();
+    
+    // Verify transitions includes the status change
+    expect(fm.transitions).toBeDefined();
+    const archiveTransition = fm.transitions?.find(t => t.status === 'archived');
+    expect(archiveTransition).toBeDefined();
   });
 });
 

src/commands/archive.ts

@@ -5,6 +5,7 @@ import { loadConfig } from '../config.js';
 import { resolveSpecPath } from '../utils/path-helpers.js';
 import { autoCheckIfEnabled } from './check.js';
 import { sanitizeUserInput } from '../utils/ui.js';
+import { getSpecFile, updateFrontmatter } from '../frontmatter.js';
 
 export async function archiveSpec(specPath: string): Promise<void> {
   // Auto-check for conflicts before archive
@@ -21,6 +22,12 @@ export async function archiveSpec(specPath: string): Promise<void> {
     throw new Error(`Spec not found: ${sanitizeUserInput(specPath)}`);
   }
 
+  // Update frontmatter to archived status before moving
+  const specFile = await getSpecFile(resolvedPath, config.structure.defaultFile);
+  if (specFile) {
+    await updateFrontmatter(specFile, { status: 'archived' });
+  }
+
   // Archive to flat structure in specs/archived/ regardless of original pattern
   const archiveDir = path.join(specsDir, 'archived');
   await fs.mkdir(archiveDir, { recursive: true });

src/test-helpers.ts

@@ -1,7 +1,10 @@
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import * as os from 'node:os';
+import matter from 'gray-matter';
+import * as yaml from 'js-yaml';
 import type { LeanSpecConfig } from './config.js';
+import type { SpecFrontmatter } from './frontmatter.js';
 
 /**
  * Test helpers for setting up isolated test environments
@@ -165,6 +168,19 @@ export async function readSpecFile(specDir: string): Promise<string> {
   return await fs.readFile(specFile, 'utf-8');
 }
 
+/**
+ * Read spec frontmatter
+ */
+export async function readSpecFrontmatter(specDir: string): Promise<SpecFrontmatter> {
+  const content = await readSpecFile(specDir);
+  const parsed = matter(content, {
+    engines: {
+      yaml: (str) => yaml.load(str, { schema: yaml.FAILSAFE_SCHEMA }) as Record<string, unknown>
+    }
+  });
+  return parsed.data as SpecFrontmatter;
+}
+
 /**
  * Check if directory exists
  */