@leanspec/ui 0.2.4 → 0.2.5-dev.20251118143726

package/dist/standalone/specs/100-release-process-typecheck-failure/README.md

@@ -1,266 +0,0 @@
----
-status: complete
-created: '2025-11-17'
-tags:
-  - process
-  - quality
-  - ci-cd
-  - post-mortem
-priority: high
-created_at: '2025-11-17T21:12:06.305Z'
-completed_at: '2025-11-17T21:12:00.000Z'
-updated_at: '2025-11-17T13:13:28.300Z'
-completed: '2025-11-17'
----
-
-# Post-Mortem: v0.2.3 TypeScript Check Failure
-
-## Overview
-
-On November 17, 2025, we attempted to release v0.2.3 only to discover **30+ TypeScript compilation errors** that should have been caught before the release process began. This spec documents what went wrong, why it happened, and how to prevent it in the future.
-
-**Impact**: Blocked release, required emergency fix session, wasted development time, damaged trust in release process.
-
-## What Went Wrong
-
-### The Problem
-Version 0.2.3 was tagged and released without running `pnpm typecheck`, leading to a published package that:
-- Failed TypeScript compilation (`tsc --noEmit` showed 30+ errors)
-- Had broken MCP SDK integration (signature mismatches)
-- Had type mismatches across packages (core vs CLI)
-- Would break for users with strict TypeScript checking
-
-### Root Causes
-
-1. **No Pre-Release Type Check**
-   - Release process did NOT include `pnpm typecheck` as a required step
-   - Only ran `pnpm build` which uses `tsup` with less strict checking
-   - `tsup` successfully bundles code even with type errors when `noCheck: true` or similar flags
-
-2. **No CI/CD Type Checking**
-   - GitHub Actions publish workflow (`.github/workflows/publish.yml`) does NOT run `pnpm typecheck`
-   - Only runs `pnpm build` before publishing
-   - No gate preventing broken releases
-
-3. **Monorepo Complexity**
-   - Errors were spread across CLI and Core packages
-   - Cross-package type dependencies not validated
-   - Core package exported types used in CLI weren't properly exposed
-
-4. **MCP SDK Version Upgrade**
-   - SDK v1.21.0 changed handler signatures (added `extra` parameter)
-   - No automated check for SDK compatibility
-   - Breaking changes went unnoticed until compilation
-
-### Timeline of Errors
-
-The errors fell into several categories:
-
-**Type Export Issues (1 error)**
-- `isolate.ts` couldn't import `Frontmatter` type from core (not exported)
-
-**Interface Mismatches (2 errors)**  
-- `SpecInfo.date` was required in CLI but optional in core
-- `deps.ts` failed due to this mismatch
-
-**Type Casting Issues (2 errors)**
-- `search.ts` had `unknown` types for `title`/`description` from frontmatter
-- Needed explicit type guards
-
-**MCP SDK Signature Changes (25+ errors)**
-- All tool handlers missing required `extra` parameter
-- Resource callbacks missing `variables` and `extra` parameters  
-- Console capturing code broken by incorrect multi_replace edits
-- Type literal issues (`type: 'text'` vs `type: string`)
-
-## Why Didn't We Catch This?
-
-### Human Factors
-- **Assumption**: "If build passes, types are good"
-- **Habit**: Not running `pnpm typecheck` before releases
-- **Time pressure**: Rush to publish without full validation
-- **Trust**: Assumed CI would catch issues (but it didn't)
-
-### Process Gaps
-- No checklist for releases
-- No automated pre-release validation
-- No CI gate for type checking
-- No cross-package type validation
-
-### Tool Configuration
-- `tsup.config.ts` may have been too lenient
-- Build tool doesn't enforce strict type checking
-- Missing `turbo run typecheck` in release workflow
-
-## What Should Have Happened
-
-### Ideal Pre-Release Checklist
-```bash
-# 1. Type check all packages
-pnpm typecheck
-
-# 2. Run all tests
-pnpm test:run
-
-# 3. Build all packages
-pnpm build
-
-# 4. Validate docs build
-cd docs-site && npm run build
-
-# 5. Run local spec validation
-node bin/lean-spec.js validate
-
-# 6. Update CHANGELOG.md
-
-# 7. Commit and tag
-git add -A
-git commit -m "chore: bump version to X.Y.Z"
-git tag vX.Y.Z
-git push origin main --tags
-
-# 8. Create GitHub release (triggers CI)
-gh release create vX.Y.Z
-```
-
-### Ideal CI/CD Workflow
-```yaml
-# .github/workflows/publish.yml
-jobs:
-  publish:
-    steps:
-      - name: Install dependencies
-        run: pnpm install
-      
-      - name: Type check ⚠️ MISSING
-        run: pnpm typecheck
-      
-      - name: Run tests ⚠️ MISSING  
-        run: pnpm test:run
-      
-      - name: Build
-        run: pnpm build
-      
-      - name: Publish to npm
-        if: all tests pass
-        run: pnpm publish
-```
-
-## Lessons Learned
-
-### What Worked
-- ✅ Fast identification and triage of errors
-- ✅ Systematic fix approach (categorize, prioritize, fix)
-- ✅ Good git practices (committed fix, tagged properly)
-- ✅ Clear documentation of what was fixed
-
-### What Didn't Work
-- ❌ No automated type checking in CI
-- ❌ No pre-release validation checklist
-- ❌ Build tools don't enforce type safety
-- ❌ Assumed "build passes" = "types are correct"
-- ❌ No cross-package type validation
-
-## Action Items
-
-### Immediate (Before Next Release)
-
-**1. Add Type Checking to CI Workflow**
-```yaml
-# .github/workflows/publish.yml
-- name: Type check all packages
-  run: pnpm typecheck
-
-- name: Run tests
-  run: pnpm test:run
-```
-
-**2. Create Release Checklist**
-Add to `CONTRIBUTING.md` or create `RELEASING.md`:
-- [ ] Run `pnpm typecheck`
-- [ ] Run `pnpm test:run`  
-- [ ] Run `pnpm build`
-- [ ] Validate with `node bin/lean-spec.js validate`
-- [ ] Update CHANGELOG.md
-- [ ] Commit, tag, push
-- [ ] Create GitHub release
-
-**3. Add Pre-Push Hook** (Optional)
-```bash
-# .husky/pre-push
-pnpm typecheck || (echo "Type check failed!" && exit 1)
-```
-
-### Short-term (Next Sprint)
-
-**4. Improve Package Scripts**
-Add a `pre-release` script:
-```json
-{
-  "scripts": {
-    "pre-release": "pnpm typecheck && pnpm test:run && pnpm build && pnpm validate"
-  }
-}
-```
-
-**5. Enhanced CI Pipeline**
-- Add separate typecheck job that runs on all PRs
-- Require passing typecheck before merge
-- Add matrix testing across Node versions
-
-**6. Documentation**
-- Document the release process in `AGENTS.md`
-- Add "Why typecheck matters" section
-- Include common type error patterns
-
-### Long-term (Future)
-
-**7. Automated Release Process**
-Consider tools like:
-- `semantic-release` for automated versioning
-- `changesets` for monorepo releases
-- `release-please` for GitHub-native releases
-
-**8. Type Safety Improvements**
-- Enable stricter TypeScript compiler options
-- Add `strict: true` to all `tsconfig.json`
-- Use `exactOptionalPropertyTypes`
-- Enable `noUncheckedIndexedAccess`
-
-**9. Monorepo Type Validation**
-- Add Turbo task for cross-package type checking
-- Validate type exports/imports between packages
-- Add package boundary lint rules
-
-## Metrics to Track
-
-Going forward, track:
-- **Time to catch type errors**: Pre-push vs CI vs post-release
-- **Type error frequency**: Trend over time
-- **Release confidence**: Did we catch issues before release?
-- **Developer friction**: Does strict checking slow development?
-
-## Success Criteria
-
-This post-mortem is successful when:
-- ✅ CI blocks releases with type errors
-- ✅ `pnpm typecheck` is part of standard workflow
-- ✅ Developers run typecheck before PRs
-- ✅ Zero type-related release failures for 3 months
-- ✅ Release checklist is documented and followed
-
-## References
-
-- [TypeScript Handbook - Type Checking](https://www.typescriptlang.org/docs/handbook/2/basic-types.html)
-- [Turbo: Type Checking in Monorepos](https://turbo.build/repo/docs/handbook/linting)
-- [GitHub Actions: Required Status Checks](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/about-protected-branches#require-status-checks-before-merging)
-
-## Conclusion
-
-This was a **preventable failure** caused by process gaps, not technical limitations. The fix is straightforward:
-
-1. **Always run `pnpm typecheck` before releasing**
-2. **Add typecheck to CI/CD pipeline**
-3. **Document and follow release checklist**
-
-The tools exist, we just need to use them consistently. This post-mortem serves as both documentation and action plan to ensure this never happens again.

package/dist/standalone/specs/101-sidebar-scroll-position-drift/README.md

@@ -1,100 +0,0 @@
----
-status: complete
-created: '2025-11-17'
-tags: []
-priority: high
-created_at: '2025-11-17T14:22:14.161Z'
-updated_at: '2025-11-17T14:54:01.282Z'
-completed_at: '2025-11-17T14:54:01.282Z'
-completed: '2025-11-17'
-transitions:
-  - status: complete
-    at: '2025-11-17T14:54:01.282Z'
----
-
-# Fix Sidebar Scroll Position Drift
-
-> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-11-17
-
-**Project**: lean-spec  
-**Team**: Core Development
-
-## Overview
-
-The specs navigation sidebar in the web package experiences scroll position drift when navigating between specs. The list jumps or loses its scroll position during navigation, causing poor UX especially with large spec lists.
-
-**Root Cause**: Multiple performance optimization attempts revealed the issue stems from:
-1. Store design causing unnecessary re-renders - `updateSidebarScrollTop` spreads state, triggering all subscribers even when only `scrollTop` changes
-2. Component subscribing to entire store state rather than specific slices
-3. `cachedSpecs` creating new references on every render before memoization
-4. Complex interaction between react-window's internal scroll management and external state updates
-
-**Why Now**: This affects daily workflow navigation and has resisted multiple quick fixes. Needs proper investigation and testing.
-
-## Design
-
-### Investigation Completed
-- Verified React 19 `useSyncExternalStore` requirements: unstable server snapshot references were causing infinite loops
-- Determined global store broadcasts on every scroll write were the primary source of drift
-- Confirmed `react-window` retains internal scroll state reliably when left to manage DOM scroll positions
-- Observed that auto-anchoring logic was running too late, producing flicker during hydration
-
-### Final Approach
-1. **Selector-driven store reads** – keep existing selector hooks but ensure server snapshots are stable constants
-2. **Isolate scroll persistence** – keep global persistence value, but stop emitting change events when the value updates
-3. **Component-local scroll management** – mirror scrollTop in refs, throttle writes with `requestAnimationFrame`, and restore via `useIsomorphicLayoutEffect`
-4. **Controlled auto-anchoring** – only scroll the virtual list on the first render (when no stored offset exists) and guard future attempts with refs
-
-### Current Optimizations Applied
-- Wrapped List in React.memo
-- Memoized RowComponent with useCallback
-- Memoized cachedSpecs
-- Added selector-based store hooks (useSpecsSidebarSpecs, useSpecsSidebarActiveSpec)
-- Separate listener sets per state slice
-
-## Plan
-
-- [ ] Add detailed logging to track re-render causes (component, store, props changes)
-- [x] Profile with React DevTools to identify actual render triggers
-- [x] Test removing all scroll management code to establish baseline behavior (browser-managed scroll proved stable)
-- [x] Implement proper selector pattern with verified render prevention
-- [x] Test with large spec lists (100+ items) to verify performance
-- [x] Document final solution and architecture decision
-
-### Implementation Summary
-
-- Updated `useSyncExternalStore` server snapshot for specs to return a memoized empty array, eliminating React 19 infinite-loop warnings.
-- Prevented `updateSidebarScrollTop` from emitting global store changes so unrelated subscribers no longer re-render on scroll.
-- Added scroll persistence effect in `SpecsNavSidebar` that restores the cached offset via `useIsomorphicLayoutEffect` and throttled listeners.
-- Introduced guarded auto-anchoring that only runs on the initial render when no stored offset exists, ensuring refreshed pages center the active spec without affecting later interactions.
-- Added retry logic for auto-anchoring to wait until the virtualized list ref is ready, removing flicker.
-
-### Validation
-
-- Navigating between specs preserves scroll position without jumps.
-- Filtering, collapsing, and mobile toggles retain the current offset.
-- Rapid spec changes and scrolling back to the top no longer trigger downward drift.
-- Browser refresh loads with the active spec centered when no previous scroll position was saved.
-- Large spec lists (>100 entries) scroll smoothly with no lag or unexpected reflows.
-
-## Test
-
-- [x] Navigate between specs - scroll position should remain stable
-- [x] Filter specs while scrolled - list should not jump
-- [x] Open/close mobile sidebar - no scroll position loss
-- [x] Rapid navigation (click multiple specs quickly) - no drift or jumping
-- [x] Large spec lists (100+) - smooth scrolling without lag
-- [x] Browser refresh - reasonable scroll restoration behavior
-
-## Notes
-
-**Attempted Fixes (Session 1)**:
-- Removed scroll restoration on navigation
-- Removed scroll tracking callbacks
-- Wrapped List in memo
-- Memoized cachedSpecs to prevent reference changes
-- Implemented selector-based store subscriptions
-
-**Key Learning**: The issue persisted despite multiple optimizations, suggesting the problem is architectural rather than a simple memoization issue. The store design fundamentally causes re-renders when any state changes, even with selector hooks.
-
-**Next Steps**: Monitor for regressions when introducing future sidebar features (e.g., grouping, pinning). Add logging only if new drift reports appear.

package/dist/standalone/specs/archived/001-typescript-cli-migration/README.md

@@ -1,37 +0,0 @@
----
-status: complete
-created: 2025-10-31
-tags: [typescript, cli, migration]
-priority: high
-completed: 2025-10-31
----
-
-# typescript-cli-migration
-
-> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-10-31 · **Tags**: typescript, cli, migration
-
-## Goal
-
-Migrate lean-spec CLI from bash script to TypeScript/pnpm while keeping the methodology language-agnostic. Better tooling for maintainability without sacrificing lean principles.
-
-## Key Points
-
-- CLI commands: `create`, `archive`, `list` with same UX
-- Date-based structure: `specs/YYYYMMDD/NNN-name.md`
-- Modern TS tooling: tsup, Prettier
-- Minimal dependencies: only `chalk` for colors
-- Fast build with pnpm
-
-## Non-Goals
-
-What we're explicitly NOT doing:
-- Adding complex CLI features or frameworks
-- Over-engineering with unnecessary dependencies
-- Making methodology TS-specific (stays language-agnostic)
-- Breaking changes to command interface
-
-## Notes
-
-The bash version worked but lacked type safety and was harder to extend. TS provides better DX while keeping the tool lean (~200 lines of code).
-
-LeanSpec methodology remains framework/language-agnostic - this is just the CLI implementation.

package/dist/standalone/specs/archived/002-template-system-redesign/README.md

@@ -1,60 +0,0 @@
----
-status: complete
-created: 2025-10-31
-tags: [templates, templates-system]
-priority: high
-completed: 2025-10-31
----
-
-# template-system-redesign
-
-> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-10-31 · **Tags**: templates, templates-system
-
-
-**Created**: 2025-10-31  
-**Status**: Complete
-
-## Goal
-
-Expand LeanSpec template system to support multiple working styles, team sizes, and domains. Current single template is too limiting - teams need options without sacrificing lean principles.
-
-## Key Points
-
-- Template bundles: Each template is a directory containing spec.md + supporting files (AGENTS.md, checklists, etc.)
-- Core templates: default (new structured), minimal (current simple), team, enterprise, api
-- CLI support: `--template` flag for selection, `lean-spec templates` to list available
-- New default template: Hybrid structure with Overview, Objectives, Design, Implementation Plan, Success Criteria, Non-Goals, Notes, References
-
-## Non-Goals
-
-What we're explicitly NOT doing:
-- Creating dozens of domain-specific templates (start with 5 core ones)
-- Making templates mandatory or rigid (still adaptable)
-- Losing the lean philosophy (every template stays focused)
-- Complex template inheritance system (keep it simple)
-
-## Notes
-
-Current template (to become "minimal"):
-- Simple: Goal, Key Points, Non-Goals, Notes
-- Works but feels like a form
-
-New default template structure:
-- Status with emoji, spec location link
-- Overview, Objectives, Non-Goals
-- Design, Implementation Plan (numbered)
-- Success Criteria (checkboxes)
-- References, Notes
-- More actionable and structured while staying lean
-
-Template directory structure:
-```
-templates/
-├── default/
-├── minimal/
-├── team/
-├── enterprise/
-└── api/
-```
-
-Each can contain multiple files - not just spec.md.

package/dist/standalone/specs/archived/003-init-system-redesign/README.md

@@ -1,113 +0,0 @@
----
-status: complete
-created: 2025-10-31
-tags: [init, cli, templates]
-priority: high
-completed: 2025-10-31
----
-
-# init-system-redesign
-
-> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-10-31 · **Tags**: init, cli, templates
-
-
-**Status**: ✅ Complete  
-**Created**: 2025-10-31  
-**Spec**: `specs/20251031/003-init-system-redesign.md`
-
-## Overview
-
-LeanSpec should help projects adopt Spec-Driven Development through `lean-spec init`. Current system only manages individual specs. We need project initialization that sets up the entire working model: spec structure, AI agent instructions, examples, and customizable conventions.
-
-## Objectives
-
-- `lean-spec init` command with one interactive question, three paths
-- Templates become full project initialization bundles (not just spec formats)
-- Spec structure uses folders: `specs/YYYYMMDD/NNN-name/README.md` (not flat files)
-- Config system: `.lean-spec/config.json` for project-specific customization
-- Keep it lean: Quick start is zero-friction, customization only when needed
-
-## Non-Goals
-
-- Over-engineering config options (start with minimal, essential settings)
-- Breaking existing projects (migration path or backward compat)
-- Complex template inheritance or plugin system
-- Mandatory interactive prompts (quick start should be fast)
-
-## Design
-
-### Init Flow
-```
-$ lean-spec init
-
-? How would you like to set up?
-  > Quick start (recommended)     - solo-dev defaults, immediate
-    Choose template               - Pick: solo-dev, team, enterprise, api-first
-    Customize everything          - Full control over structure
-```
-
-### Template Structure
-```
-templates/
-├── solo-dev/
-│   ├── config.json           # Default config
-│   ├── files/
-│   │   ├── AGENTS.md
-│   │   └── specs/
-│   │       └── 001-example-spec/
-│   │           └── README.md
-│   └── README.md            # Template documentation
-├── team/
-├── enterprise/
-└── api-first/
-```
-
-### Config System
-`.lean-spec/config.json`:
-```json
-{
-  "template": "solo-dev",
-  "specsDir": "specs",
-  "structure": {
-    "pattern": "{date}/{seq}-{name}/",
-    "dateFormat": "YYYYMMDD",
-    "sequenceDigits": 3
-  }
-}
-```
-
-### Spec Structure Change
-- **Before**: `specs/20251031/001-name.md` (file)
-- **After**: `specs/20251031/001-name/README.md` (folder)
-- Allows multiple files per spec (diagrams, supporting docs, etc.)
-
-## Implementation Plan
-
-1. [ ] Add prompts library (@inquirer/prompts or prompts)
-2. [ ] Implement config loader/writer for .lean-spec/config.json
-3. [ ] Redesign template structure as project bundles
-4. [ ] Implement init command with three paths
-5. [ ] Update create command to use folder structure + read config
-6. [ ] Migrate existing specs to folder structure
-7. [ ] Update archive/list commands for folders
-8. [ ] Update docs (README, AGENTS.md)
-
-## Success Criteria
-
-- [ ] `lean-spec init` works with one question, three paths
-- [ ] Quick start takes <2 seconds, zero additional input
-- [ ] Templates include full working model (AGENTS.md, examples)
-- [ ] Specs created as folders with README.md
-- [ ] Config system allows customization without CLI flags
-- [ ] Existing projects can migrate or continue working
-
-## References
-
-- Previous spec: `002-template-system-redesign.md` (superseded by this)
-- Prompts libraries: @inquirer/prompts, prompts
-
-## Notes
-
-This redesign addresses the real need: LeanSpec as a **project initialization system** for SDD adoption, not just a spec file manager. Templates are working models, not fill-in-the-blank forms.
-
-Key insight: Spec template is just one component of the working model. Full adoption needs AGENTS.md, examples, conventions, and structure.

package/dist/standalone/specs/archived/004-existing-project-integration/README.md

@@ -1,69 +0,0 @@
----
-status: complete
-created: 2025-11-01
-tags: [integration, init, migration]
-priority: high
-completed: 2025-11-01
----
-
-# Existing Project Integration
-
-> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-11-01 · **Tags**: integration, init, migration
-
-## Goal
-
-Support `lean-spec init` on projects with existing `AGENTS.md` or system prompts without clobbering their content.
-
-## Key Scenarios
-
-1. **Merge Mode**: User has `AGENTS.md` → detect, offer to merge LeanSpec section ✅
-2. **Backup Mode**: User chooses not to merge → backup existing, create new ✅
-3. **Skip Mode**: User wants to keep their setup → just add .lean-spec config and specs/ ✅
-
-## Acceptance Criteria
-
-- [x] Detect existing `AGENTS.md`, `.cursorrules`, `.github/copilot-instructions.md`
-- [x] Interactive prompt: merge, backup, or skip
-- [x] If merge: append LeanSpec section with clear delimiter
-- [x] If backup: rename to `AGENTS.md.backup`, create new
-- [x] If skip: don't touch existing files, only add lean-spec structure
-
-## Implementation
-
-Added three helper functions in `src/commands.ts`:
-
-1. `detectExistingSystemPrompts()` - Checks for common system prompt files
-2. `handleExistingFiles()` - Implements merge/backup/skip logic
-3. Updated `copyDirectory()` - Supports skipping specified files
-
-Interactive flow in `initProject()`:
-- Detects existing files before copying templates
-- Prompts user with 3 options: merge, backup, or skip
-- Handles each option appropriately
-- Only copies non-conflicting files from template
-
-## Non-Goals
-
-- Auto-detecting project type from existing files (just handle conflicts) ✓
-- Parsing/understanding existing AGENTS.md content (simple append) ✓
-- Supporting every possible system prompt variant (start with common ones) ✓
-
-## Testing
-
-Basic test script created: `test-integration.sh`
-
-Manual testing:
-```bash
-cd /tmp/lspec-test-existing
-node /path/to/lean-spec init
-# Choose merge/backup/skip and verify behavior
-```
-
-## Notes
-
-Supported system prompt files:
-- `AGENTS.md` (merge supported)
-- `.cursorrules` (backup/skip only)
-- `.github/copilot-instructions.md` (backup/skip only)
-
-Future: Could extend merge support to other file types if needed.