@leanspec/ui 0.2.7 → 0.2.9-dev.20251205030455

package/.next/standalone/packages/ui/dist/standalone/specs/095-pr-migration-verification/README.md

@@ -1,339 +0,0 @@
----
-status: complete
-created: '2025-11-17'
-tags:
-  - migration
-  - docs
-  - verification
-priority: high
-created_at: '2025-11-17T06:39:54.583Z'
-updated_at: '2025-11-17T06:41:25.954Z'
-completed: '2025-11-17'
----
-
-# PR Migration Verification: docs-site → lean-spec-docs
-
-> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-11-17 · **Tags**: migration, docs, verification
-
-**Project**: lean-spec  
-**Team**: Core Development
-
-## Overview
-
-Successfully migrated PRs #66-69 from the old `lean-spec` repository to the new `lean-spec-docs` repository using cherry-pick approach (Option 1). These PRs contained substantial documentation improvements that were created before the docs-site migration to a separate repository.
-
-**Problem**: After migrating docs-site to lean-spec-docs repo, discovered 4 unmerged PRs (#66-69) with ~4,500+ lines of documentation improvements that needed to be migrated.
-
-**Solution**: Used git cherry-pick approach to extract and apply docs-site changes from each PR to the new repository, preserving all work without losing any content.
-
-## Migration Summary
-
-### Total Changes
-- **21 files changed**: 4,032 insertions(+), 7 deletions(-)
-- **4 PRs migrated**: #66, #67, #68, #69
-- **Branch created**: `migrate-prs-66-69` in lean-spec-docs repo
-- **Branch pushed**: Successfully pushed to origin
-
-### PR #66: Terminology Glossary (295 lines)
-**Spec**: 088-core-concepts-terminology-only  
-**Status**: Complete  
-**Commit**: ae12682
-
-**Changes**:
-- Created `docs/guide/terminology.mdx` with 16 essential SDD terms
-- Updated sidebar positions for all Core Concepts files (1→2, 2→3, 3→4, 4→5, 5→6, 4→7)
-- Added terminology as first item in Core Concepts sidebar
-- Added terminology note to `first-principles.mdx`
-- Added Quick Start tip to `understanding.mdx`
-- Added terminology links to `getting-started.mdx` and `understanding.mdx`
-
-**Files modified**: 9 files
-- New: `docs/guide/terminology.mdx`
-- Updated: ai-agent-memory.mdx, context-engineering.mdx, first-principles.mdx, getting-started.mdx, limits-and-tradeoffs.mdx, philosophy.mdx, understanding.mdx, sidebars.ts
-
-### PR #67: Step-by-Step SDD Tutorials (1,676 lines)
-**Spec**: 089-sdd-practical-tutorials  
-**Status**: Complete  
-**Commit**: 808a141
-
-**Changes**:
-- Created 4 progressive tutorials:
-  - `docs/tutorials/your-first-spec.mdx` (326 lines)
-  - `docs/tutorials/sdd-workflow-feature-development.mdx` (369 lines)
-  - `docs/tutorials/managing-multiple-specs.mdx` (454 lines)
-  - `docs/tutorials/working-with-teams.mdx` (527 lines)
-- Added Tutorials section to sidebar (after Introduction, before Core Concepts)
-- Added Quick Start button on homepage linking to first tutorial
-- Changed existing Get Started button to secondary style
-
-**Files modified**: 6 files
-- New: 4 tutorial files in `docs/tutorials/`
-- Updated: sidebars.ts, src/pages/index.tsx
-
-### PR #68: Dogfooding Case Studies (~2,500 lines)
-**Spec**: 090-leanspec-sdd-case-studies  
-**Status**: Complete  
-**Commit**: d8c6955
-
-**Changes**:
-- Created 5 case study pages:
-  - `docs/case-studies/index.mdx` (113 lines) - Overview
-  - `docs/case-studies/simple-feature-token-validation.mdx` (254 lines) - Spec 071
-  - `docs/case-studies/complex-feature-web-sync.mdx` (375 lines) - Spec 082
-  - `docs/case-studies/refactoring-monorepo-core.mdx` (580 lines) - Spec 067
-  - `docs/case-studies/cross-team-official-launch.mdx` (513 lines) - Spec 043
-- Added Case Studies section to sidebar (before roadmap/faq)
-- Added case studies CTA section on homepage
-- Chinese translations for homepage elements in `i18n/zh-Hans/code.json`
-
-**Files modified**: 8 files
-- New: 5 case study files in `docs/case-studies/`
-- Updated: sidebars.ts, src/pages/index.tsx, i18n/zh-Hans/code.json
-
-### PR #69: Chinese Localization (149 lines)
-**Spec**: 091-chinese-localization-strategy  
-**Status**: Complete (docs-site portion)  
-**Commit**: 3b059ef
-
-**Changes**:
-- Created `i18n/zh-Hans/TERMINOLOGY_GLOSSARY.md` with standardized Chinese translations
-- Comprehensive glossary for consistent terminology across all translations
-- Includes core concepts, first principles, status/priority terms, CLI commands, etc.
-
-**Note**: Web app i18n infrastructure (packages/web locales, hooks, components) from PR #69 applies to main lean-spec repo, not docs-site, so only the terminology glossary was migrated.
-
-**Files modified**: 1 file
-- New: `i18n/zh-Hans/TERMINOLOGY_GLOSSARY.md`
-
-### Post-Migration QA Fix (ee70869, 2025-11-17)
-
-After verification we found zh-Hans anchor references missing for the new terminology links. Commit `ee70869` adds:
-- Explicit anchor IDs on `guide/first-principles` translation so cross-links resolve
-- Translated `lean-spec tokens` reference section to surface `/reference/cli#lean-spec-tokens`
-- FAQ link update to reuse the new anchor slug
-- `pnpm build` now passes without broken-anchor warnings for en + zh-Hans
-
-This commit is part of the same `migrate-prs-66-69` branch and must be included in the docs-site PR.
-
-## Design
-
-### Migration Approach
-
-**Method**: Git cherry-pick with manual file extraction
-
-**Process**:
-1. Added old lean-spec repo as remote in docs-site submodule
-2. Fetched PR branches from old repo
-3. For each PR:
-   - Extracted files from specific commits using `git show <commit>:<path>`
-   - Applied changes manually to avoid path conflicts
-   - Updated references (sidebar positions, links)
-   - Tested build after each PR
-   - Committed with descriptive message and PR reference
-4. Pushed all commits to new branch in lean-spec-docs repo
-
-**Why manual extraction vs direct cherry-pick?**
-- Path differences: PR commits had `docs-site/` prefix, new repo doesn't
-- Merge conflicts: PRs were based on different base branches
-- Selective migration: Some PRs had non-docs changes (specs/, packages/)
-- Build verification: Could test incrementally
-
-### Branch Structure
-
-```
-lean-spec-docs (new repo)
-├── main (0f0522f)
-└── migrate-prs-66-69 (3b059ef) ← Migration branch
-    ├── ae12682 - PR #66: Terminology glossary
-    ├── 808a141 - PR #67: Tutorials
-    ├── d8c6955 - PR #68: Case studies
-    └── 3b059ef - PR #69: Chinese glossary
-
-lean-spec (old repo)
-└── docs-site/ (submodule)
-    └── pointing to lean-spec-docs @ migrate-prs-66-69
-```
-
-## Plan
-
-- [x] **Step 1**: Analyze unmerged PRs #66-69 in old repo
-- [x] **Step 2**: Set up git remotes (add old-repo remote)
-- [x] **Step 3**: Fetch PR branches from old repo
-- [x] **Step 4**: Create migration branch `migrate-prs-66-69`
-- [x] **Step 5**: Migrate PR #66 (terminology glossary)
-  - [x] Extract terminology.mdx file
-  - [x] Update sidebar positions for Core Concepts files
-  - [x] Add terminology references and notes
-  - [x] Test build
-  - [x] Commit changes
-- [x] **Step 6**: Migrate PR #67 (tutorials)
-  - [x] Extract 4 tutorial files
-  - [x] Update sidebar with Tutorials section
-  - [x] Update homepage with Quick Start button
-  - [x] Test build
-  - [x] Commit changes
-- [x] **Step 7**: Migrate PR #68 (case studies)
-  - [x] Extract 5 case study files
-  - [x] Update sidebar with Case Studies section
-  - [x] Update homepage with case studies CTA
-  - [x] Add Chinese translations
-  - [x] Test build
-  - [x] Commit changes
-- [x] **Step 8**: Migrate PR #69 (Chinese localization)
-  - [x] Extract terminology glossary
-  - [x] Test build
-  - [x] Commit changes
-- [x] **Step 9**: Push migration branch to lean-spec-docs repo
-- [x] **Step 10**: Document migration for verification
-
-## Test
-
-### Build Verification
-- [x] Build succeeds with PR #66 changes (terminology)
-- [x] Build succeeds with PR #67 changes (tutorials)
-- [x] Build succeeds with PR #68 changes (case studies)
-- [x] Build succeeds with PR #69 changes (Chinese glossary)
-- [x] Final build succeeds with all changes
-- [x] Both English and Chinese locales build successfully
-- [x] `pnpm build` (2025-11-17) after `ee70869` → no broken anchors; warning resolved by zh-Hans fixes
-
-### Content Verification
-- [x] All 21 files present in migration branch
-- [x] Terminology glossary accessible from sidebar
-- [x] 4 tutorials accessible from Tutorials section
-- [x] 5 case studies accessible from Case Studies section
-- [x] Homepage Quick Start button links to first tutorial
-- [x] Homepage case studies CTA section present
-- [x] Chinese translations present in i18n files
-
-### Git Verification
-- [x] 5 commits on migrate-prs-66-69 branch (includes QA fix `ee70869`)
-- [x] Each commit references source PR
-- [x] Commit messages descriptive and detailed
-- [x] Branch successfully pushed to origin
-- [x] No merge conflicts
-
-## Next Steps for Verification Session
-
-### 0. Update docs-site Submodule Pointer
-```bash
-cd /home/marvin/projects/codervisor/lean-spec
-git add docs-site
-git commit -m "chore: point docs-site to ee70869 (spec 095 QA fix)"
-```
-
-Verify:
-- Root repo references `ee70869`
-- Include this commit with any follow-up PR in main repo
-
-### 1. Review Migration Branch
-```bash
-cd docs-site
-git checkout migrate-prs-66-69
-git log --oneline --stat
-```
-
-Verify:
-- 4 commits present
-- Commit messages reference PRs
-- File changes match summary above
-
-### 2. Test Documentation Build
-```bash
-npm run build
-npm run serve
-```
-
-Verify:
-- Build completes without errors
-- Navigate to Terminology (/docs/guide/terminology)
-- Navigate to Tutorials section (/docs/tutorials/your-first-spec)
-- Navigate to Case Studies section (/docs/case-studies)
-- Check homepage Quick Start button
-- Check homepage case studies section
-- Test Chinese locale (zh-Hans)
-
-### 3. Create Pull Request
-```bash
-# Visit: https://github.com/codervisor/lean-spec-docs/pull/new/migrate-prs-66-69
-```
-
-PR Description Template:
-```
-## Migrate PRs #66-69 from lean-spec to lean-spec-docs
-
-Migrates documentation improvements from 4 unmerged PRs that were created before docs-site migration.
-
-### Changes Summary
-- **PR #66**: Terminology glossary (295 lines)
-- **PR #67**: Step-by-step tutorials (1,676 lines)  
-- **PR #68**: Dogfooding case studies (2,500 lines)
-- **PR #69**: Chinese terminology glossary (149 lines)
-
-**Total**: 21 files changed, 4,032 insertions(+), 7 deletions(-)
-
-### Verification
-- ✅ All builds pass (EN + zh-Hans) — confirmed via `pnpm build` on 2025-11-17 after `ee70869`
-- ✅ No breaking changes
-- ✅ All links functional
-- ✅ Each PR tracked in separate commit
-
-### Original PRs
-- codervisor/lean-spec#66 (spec 088)
-- codervisor/lean-spec#67 (spec 089)
-- codervisor/lean-spec#68 (spec 090)
-- codervisor/lean-spec#69 (spec 091)
-
-Closes #[issue-number-if-exists]
-```
-
-### 4. After Merge: Update Main Repo
-```bash
-cd /home/marvin/projects/codervisor/lean-spec
-git checkout main
-git submodule update --remote docs-site
-git add docs-site
-git commit -m "chore: update docs-site submodule to include migrated PRs #66-69"
-git push origin main
-```
-
-### 5. Close Old PRs in lean-spec Repo
-
-For each PR #66, #67, #68, #69, add comment:
-```
-This PR has been successfully migrated to the new docs repository at:
-https://github.com/codervisor/lean-spec-docs/pull/[new-pr-number]
-
-All documentation changes from this PR are now tracked in lean-spec-docs.
-
-Closing as the docs-site has been migrated to its own repository.
-```
-
-Then close each PR.
-
-## Notes
-
-### Migration Success Factors
-- **Incremental approach**: Migrated one PR at a time with testing
-- **Build verification**: Tested after each PR to catch issues early
-- **Descriptive commits**: Each commit explains what was migrated and references source PR
-- **Manual extraction**: Avoided complex merge conflicts by extracting files manually
-- **Preserved content**: Zero content loss, all 4,500+ lines migrated successfully
-
-### Challenges Encountered
-1. **Path differences**: PRs had `docs-site/` prefix, required manual path adjustment
-2. **Base branch differences**: PRs based on different branches, some included/excluded prior changes
-3. **Web app vs docs-site**: PR #69 had both web app and docs-site changes, needed separation
-
-### Technical Details
-- **Remote added**: `git remote add old-repo https://github.com/codervisor/lean-spec.git`
-- **PR fetch pattern**: `git fetch old-repo pull/{N}/head:pr-{N}`
-- **File extraction**: `git show <commit>:<path> > <target>`
-- **Build tool**: Docusaurus with i18n support
-- **Languages**: English (en), Chinese (zh-Hans)
-
-### Repository Links
-- **Old repo**: https://github.com/codervisor/lean-spec
-- **New repo**: https://github.com/codervisor/lean-spec-docs  
-- **Migration branch**: https://github.com/codervisor/lean-spec-docs/tree/migrate-prs-66-69
-- **Create PR**: https://github.com/codervisor/lean-spec-docs/pull/new/migrate-prs-66-69