@leanspec/ui 0.2.7 → 0.2.9-dev.20251205030455

package/.next/standalone/packages/ui/dist/standalone/specs/076-programmatic-spec-relationships/README.md

@@ -1,301 +0,0 @@
----
-status: complete
-created: '2025-11-13'
-tags:
-  - cli
-  - mcp
-  - dx
-  - ai-agents
-  - relationships
-priority: high
-created_at: '2025-11-13T09:03:06.741Z'
-updated_at: '2025-11-17T01:11:50.008Z'
-completed_at: '2025-11-17T01:11:49.548Z'
-completed: '2025-11-17'
-transitions:
-  - status: complete
-    at: '2025-11-17T01:11:49.548Z'
-related:
-  - 085-cli-relationship-commands
----
-
-# Programmatic Spec Relationship Management
-
-> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-11-13 · **Tags**: cli, mcp, dx, ai-agents, relationships
-
-**Project**: lean-spec  
-**Team**: Core Development
-
-## Overview
-
-**Problem**: AI agents cannot efficiently manage spec relationships (`depends_on`, `related` fields) because there's no programmatic interface.
-
-**Current State**:
-- `lean-spec deps <spec>` - Views relationships ✅
-- Manual frontmatter editing - Only way to add/remove relationships ❌
-- **No CLI command** to add/modify relationships
-- **No MCP tool** to manage dependencies
-
-**Pain Points**:
-1. **AI agents must manually edit YAML frontmatter** - error-prone, fragile
-2. **No validation** - can add invalid spec references, typos
-3. **Asymmetric workflow** - can update `status`, `priority`, `tags` via CLI, but not `depends_on`/`related`
-4. **Documented as manual-only** - AGENTS.md explicitly says "must currently be edited manually"
-
-**Example AI workflow today** (broken):
-```bash
-# AI agent creating spec with dependencies
-lean-spec create new-feature --priority high
-# Now AI must:
-# 1. Read the file
-# 2. Parse YAML frontmatter
-# 3. Edit YAML manually
-# 4. Write back
-# Risk: YAML corruption, validation bypass, inefficient
-```
-
-**Goal**: Provide programmatic interface for managing spec relationships via CLI and MCP.
-
-**Related Specs**:
-- `073-template-engine-agents-md` - AI-first design principles
-- `072-ai-agent-first-use-workflow` - AI agent UX optimization
-
-## Design
-
-### Proposed CLI Commands
-
-#### Add Relationships
-```bash
-# Add dependency (blocks creation)
-lean-spec deps add 076 --depends-on 073,074
-
-# Add related specs (informational)
-lean-spec deps add 076 --related 072,025
-
-# Combined
-lean-spec deps add 076 --depends-on 073 --related 072,074
-```
-
-#### Remove Relationships
-```bash
-# Remove specific dependency
-lean-spec deps remove 076 --depends-on 073
-
-# Remove specific related
-lean-spec deps remove 076 --related 072
-
-# Remove all dependencies
-lean-spec deps remove 076 --depends-on --all
-
-# Remove all relationships
-lean-spec deps remove 076 --all
-```
-
-#### View Relationships (already exists)
-```bash
-lean-spec deps 076  # Already implemented ✅
-```
-
-### Proposed MCP Tools
-
-#### Add to MCP Server
-```typescript
-{
-  name: "mcp_lean-spec_deps-add",
-  description: "Add dependencies or related specs to a specification",
-  inputSchema: {
-    specPath: string,     // Spec to modify
-    dependsOn?: string[], // Dependencies to add
-    related?: string[]    // Related specs to add
-  }
-}
-
-{
-  name: "mcp_lean-spec_deps-remove", 
-  description: "Remove dependencies or related specs from a specification",
-  inputSchema: {
-    specPath: string,
-    dependsOn?: string[],
-    related?: string[],
-    all?: boolean         // Remove all relationships
-  }
-}
-```
-
-### Implementation Details
-
-**Validation Requirements**:
-- Verify target specs exist before adding
-- Prevent circular dependencies in `depends_on`
-- Allow bidirectional `related` (auto-inferred)
-- Validate spec path format (number, name, or full path)
-
-**Behavior**:
-- `depends_on`: Directional, must be explicit on both sides
-- `related`: Bidirectional, shown from both sides automatically (already implemented in `deps` view)
-
-**Edge Cases**:
-- Adding duplicate relationships: Deduplicate silently
-- Adding non-existent spec: Error with suggestion
-- Self-reference: Error
-- Circular `depends_on`: Detect and error
-
-### Alternative Approaches Considered
-
-**1. Generic `lean-spec update` extension**:
-```bash
-lean-spec update 076 --depends-on 073,074
-```
-- ❌ Doesn't distinguish add vs set vs remove
-- ❌ Unclear if it appends or replaces
-- ✅ Consistent with existing `update` command
-
-**2. Separate add/remove/set commands**:
-```bash
-lean-spec deps-add 076 --depends-on 073
-lean-spec deps-remove 076 --related 072
-```
-- ❌ Clutters command namespace
-- ✅ Very explicit
-
-**3. Chosen approach: Subcommands under `deps`**:
-```bash
-lean-spec deps add 076 --depends-on 073
-lean-spec deps remove 076 --related 072
-```
-- ✅ Namespaced under existing `deps` command
-- ✅ Explicit add/remove semantics
-- ✅ Matches `deps` for viewing
-
-## Plan
-
-- [ ] **CLI Implementation**
-  - [ ] Add `deps add` subcommand to CLI
-  - [ ] Add `deps remove` subcommand to CLI
-  - [ ] Implement relationship validation logic
-  - [ ] Detect circular dependencies in `depends_on`
-  - [ ] Add unit tests for validation
-  - [ ] Add integration tests for CLI commands
-
-- [ ] **MCP Implementation**
-  - [ ] Add `mcp_lean-spec_deps-add` tool
-  - [ ] Add `mcp_lean-spec_deps-remove` tool
-  - [ ] Wire up to CLI functionality
-  - [ ] Add MCP tool tests
-
-- [ ] **Documentation**
-  - [ ] Update AGENTS.md: Remove "manual edit only" note
-  - [ ] Add relationship management to CLI docs
-  - [ ] Add examples to guide docs
-  - [ ] Update spec 073 to reference this capability
-
-- [ ] **Validation**
-  - [ ] Test with AI agents (verify workflow improvement)
-  - [ ] Verify `deps` view shows changes correctly
-  - [ ] Test circular dependency detection
-  - [ ] Test non-existent spec error messages
-
-## Test
-
-**CLI Tests**:
-
-```bash
-# 1. Add dependencies
-lean-spec deps add 076 --depends-on 073,074
-lean-spec deps 076
-# Expected: Shows "Depends On: 073, 074"
-
-# 2. Add related specs
-lean-spec deps add 076 --related 072,025
-lean-spec deps 076
-# Expected: Shows "Related Specs: 072, 025"
-
-# 3. Remove specific dependency
-lean-spec deps remove 076 --depends-on 073
-lean-spec deps 076
-# Expected: Shows "Depends On: 074" (073 removed)
-
-# 4. Validation: Non-existent spec
-lean-spec deps add 076 --depends-on 999
-# Expected: Error "Spec 999 not found. Did you mean: ..."
-
-# 5. Validation: Circular dependency
-lean-spec deps add 073 --depends-on 076
-# Expected: Error "Circular dependency detected: 076 → 073 → 076"
-
-# 6. Validation: Self-reference
-lean-spec deps add 076 --depends-on 076
-# Expected: Error "Cannot depend on self"
-```
-
-**MCP Tests**:
-
-```typescript
-// 1. Add via MCP
-await mcp_lean_spec_deps_add({
-  specPath: "076",
-  dependsOn: ["073", "074"],
-  related: ["072"]
-});
-
-// 2. Verify via deps view
-await mcp_lean_spec_deps({ specPath: "076" });
-// Expected: Shows all relationships
-
-// 3. Remove via MCP
-await mcp_lean_spec_deps_remove({
-  specPath: "076",
-  dependsOn: ["073"]
-});
-```
-
-**AI Agent Workflow Test**:
-
-```
-Scenario: AI agent creating spec with dependencies
-
-Before (manual edit):
-1. Create spec: lean-spec create new-feature
-2. Read README.md
-3. Parse YAML
-4. Edit frontmatter
-5. Write back
-Risk: YAML corruption
-
-After (programmatic):
-1. Create spec: lean-spec create new-feature  
-2. Add deps: lean-spec deps add new-feature --depends-on 073,074
-Done. Safe, validated, efficient.
-```
-
-## Notes
-
-### Why This Matters
-
-**Root Cause**: Spec relationships are documented in AGENTS.md as "manual edit only" because no programmatic interface exists. This is:
-- **Inconsistent**: Other frontmatter fields have CLI commands (`update` for status, priority, tags)
-- **Error-prone**: Manual YAML editing bypasses validation
-- **AI-unfriendly**: Agents must parse/edit YAML instead of using structured commands
-
-**Impact**: AI agents struggle with relationship management, leading to:
-- Missed dependencies
-- Incorrect relationships
-- Manual intervention required
-
-### Future Enhancements
-
-1. **Bulk operations**: `lean-spec deps add 076 --depends-on $(lean-spec list --status planned --format ids)`
-2. **Dependency graph validation**: Detect longer circular chains
-3. **Relationship suggestions**: "Spec 076 imports from 073, add dependency?"
-4. **Dependency impact analysis**: "Completing 073 unblocks 076, 077"
-
-### Success Criteria
-
-- AI agents can manage relationships without manual YAML editing
-- AGENTS.md updated to reflect programmatic interface
-- Validation prevents invalid relationships
-- Workflow parity with other frontmatter fields (`status`, `priority`, `tags`)
-
-## Notes
-
-<!-- Optional: Research findings, alternatives considered, open questions -->

package/.next/standalone/packages/ui/dist/standalone/specs/077-archiving-strategy/README.md

@@ -1,235 +0,0 @@
----
-status: planned
-created: '2025-11-13'
-tags:
-  - process
-  - maintenance
-  - workflow
-  - best-practices
-priority: high
-created_at: '2025-11-13T13:08:46.014Z'
-updated_at: '2025-11-13T13:10:19.510Z'
----
-
-# archiving-strategy
-
-> **Status**: 🗓️ Planned · **Priority**: High · **Created**: 2025-11-13 · **Tags**: process, maintenance, workflow, best-practices
-
-**Project**: lean-spec  
-**Team**: Core Development
-
-## Overview
-
-**Problem**: No clear strategy for when to archive completed specs, leading to:
-- Bulk archiving attempts that catch incomplete work (e.g., spec 073 Phase 2 not done)
-- Uncertainty about which completed specs should stay active vs archived
-- Risk of archiving specs that are still referenced or contain living documentation
-- Cluttered active workspace with many completed specs (29 completed specs currently)
-
-**Current State**: 
-- We have `lean-spec archive` command that moves specs to `archived/` directory
-- Specs marked "complete" but unclear when they should be archived
-- No documented criteria or workflow for archiving decisions
-- Dependencies (`depends_on`, `related`) might reference archived specs
-
-**Goal**: Define clear archiving strategy with:
-1. **Criteria**: When a completed spec should be archived
-2. **Process**: How to safely archive specs
-3. **Exceptions**: When to keep completed specs active
-4. **Tooling**: Commands/checks to help with archiving decisions
-
-## Design
-
-### Archiving Criteria
-
-**Archive a completed spec when ALL of:**
-1. ✅ Status is "complete" 
-2. ✅ Work is fully implemented (no pending phases/tasks)
-3. ✅ No longer needs frequent reference
-4. ✅ Not "living documentation" (e.g., philosophy/foundation docs)
-5. ✅ Age > 30 days since completion (optional cooling-off period)
-
-**Keep completed specs active if ANY of:**
-- 🔁 Referenced frequently for context
-- 📚 Contains living documentation (philosophy, core concepts)
-- 🔥 Completed within last 30 days (recent work)
-- 🔗 Multiple active specs depend on it
-- 🎯 Part of current release cycle
-
-### Spec Categories
-
-**Safe to Archive (Historical):**
-- Old launch milestones (v0.1, v0.2 launches)
-- One-time refactors/migrations (fully complete)
-- Completed documentation improvements (not living docs)
-- Infrastructure changes (fully implemented)
-
-**Keep Active (Reference):**
-- Foundation specs (048, 049, 066 - first principles)
-- Core feature documentation (if frequently referenced)
-- Current release work (v0.3.0 related)
-- Recent completions (< 30 days)
-
-**Review Carefully:**
-- Multi-phase specs (ensure all phases done)
-- Specs with dependencies (check if dependents need them)
-- Template/tooling specs (might be referenced)
-
-### Archiving Workflow
-
-**Pre-Archive Checklist:**
-```bash
-# 1. Verify spec is truly complete
-lean-spec view <spec>  # Check plan/tasks
-
-# 2. Check dependencies
-lean-spec deps <spec>  # See what depends on it
-
-# 3. Check age
-lean-spec view <spec> --json | jq '.completed_at'
-
-# 4. Search for references in active specs
-lean-spec search "<spec-name>"
-```
-
-**Archive Command:**
-```bash
-lean-spec archive <spec>
-```
-
-**Batch Archiving (with verification):**
-```bash
-# List candidates (completed > 30 days)
-lean-spec list --status complete
-
-# Review each before archiving
-# Archive individually after verification
-```
-
-### Tooling Enhancements
-
-**Potential CLI improvements:**
-1. `lean-spec archive --candidates` - List archiving candidates with reasons
-2. `lean-spec archive --check <spec>` - Dry-run with safety checks
-3. `lean-spec deps <spec> --check-archived` - Warn if dependencies archived
-4. Filter by completion age: `lean-spec list --completed-before 2025-10-01`
-
-**Safety Features:**
-- Warn if archiving spec with active dependents
-- Show references in active specs before archiving
-- Dry-run mode to preview archive decision
-
-## Plan
-
-### Phase 1: Document Strategy
-- [ ] Define archiving criteria (in this spec)
-- [ ] Document workflow in AGENTS.md
-- [ ] Create archiving best practices guide
-- [ ] Add to official documentation
-
-### Phase 2: Tooling Support
-- [ ] Add `--completed-before <date>` filter to `list` command
-- [ ] Implement `lean-spec archive --candidates` (suggests specs to archive)
-- [ ] Add safety checks to `archive` command:
-  - Warn if active specs depend on it
-  - Show completion age
-  - Check for incomplete tasks
-- [ ] Add `--check` dry-run flag to `archive` command
-
-### Phase 3: Clean Up Current Workspace
-- [ ] Review 29 completed specs with new criteria
-- [ ] Archive truly complete, historical specs
-- [ ] Keep foundation/reference specs active
-- [ ] Document decisions for future reference
-
-### Phase 4: Ongoing Maintenance
-- [ ] Add archiving to monthly/quarterly maintenance checklist
-- [ ] Monitor completion rate and archive rate
-- [ ] Refine criteria based on usage patterns
-
-## Test
-
-### Validation Criteria
-- [ ] Archiving criteria clear and actionable
-- [ ] Workflow documented and easy to follow
-- [ ] Safety checks prevent accidental archiving of needed specs
-- [ ] CLI commands help identify candidates automatically
-
-### Test Scenarios
-- [ ] Archive old completed spec (> 30 days, no dependents)
-- [ ] Attempt to archive recently completed spec (< 30 days) - should warn
-- [ ] Archive spec with active dependents - should show warning
-- [ ] List archiving candidates - should match manual review
-- [ ] Archive spec with incomplete phases - should detect and warn
-
-### Success Metrics
-- [ ] Zero accidental archives of needed specs
-- [ ] < 5 minutes to decide if spec should be archived
-- [ ] Clear rationale documented for each archiving decision
-- [ ] Active workspace stays < 20 specs (excluding archived)
-
-## Notes
-
-### Real-World Example: Nov 13, 2025 Bulk Archive Attempt
-
-**What Happened:**
-- Attempted to archive all 29 completed specs at once
-- Reverted due to concerns (spec 073 Phase 2 incomplete)
-- Realized we needed clear archiving criteria
-
-**Lessons Learned:**
-1. Bulk archiving is risky without verification
-2. "Complete" status doesn't always mean "fully done"
-3. Some specs are reference documentation (shouldn't archive)
-4. Need to check dependencies before archiving
-
-**Specs We're Uncertain About:**
-- 073: Phase 1 done, Phase 2 not started (split into separate spec?)
-- 048, 049, 066: Foundation specs, referenced often (keep active?)
-- 067, 069, 075: Recent core features (keep for context?)
-- 043: Old launch milestone (safe to archive?)
-
-### Dependencies and Archived Specs
-
-**Question**: Is it OK for active specs to depend on archived specs?
-
-**Answer**: Generally yes, since `depends_on` means "required work before starting":
-- If dependency is complete and archived, that's expected
-- `related` links can also point to archived specs (for context)
-- The archive doesn't delete specs, just moves them
-
-**However**, we should warn if:
-- Archiving a spec that many active specs depend on (heavy reference usage)
-- The spec contains living documentation that's frequently consulted
-
-### Alternative Approaches Considered
-
-**Auto-Archive After N Days:**
-- ❌ Too aggressive, doesn't account for reference value
-- ❌ Philosophy/foundation specs should never auto-archive
-- ✅ Could use as suggestion/reminder, not automatic
-
-**Status: "archived" vs Directory Move:**
-- Current: Move to `archived/` directory
-- Alternative: Keep in place, set `status: archived`
-- ✅ Directory move is clearer, easier to browse
-- ✅ Status can be "complete" (in archived/)
-
-**Archive Levels (Hot/Cold):**
-- Hot: Specs completed in last 90 days (keep active)
-- Warm: Specs 90-180 days old (review for archiving)
-- Cold: Specs > 180 days old (archive unless exception)
-- 🤔 Adds complexity, may not be needed for current scale
-
-### Open Questions
-
-1. Should we split multi-phase specs when only Phase 1 is done?
-2. How to handle "living documentation" specs (philosophy, guides)?
-3. Should `lean-spec board` show archived specs in a separate column?
-4. Archive specs individually or in batches (monthly cleanup)?
-5. Should we add `archived_at` timestamp to metadata?
-
-### Related Specs
-
-- 059-programmatic-spec-management: Programmatic access to specs (could help with archiving automation)
-- 065-v03-planning: Current release planning (determines what's "current" vs historical)