refactor: comprehensive project cleanup and normalization

## Version
- Sync version to 2.1.0 across CMakeLists.txt and openspec.yaml

## Code Changes
- Remove dead code (empty src/core/force_calculator.cpp)
- Fix CUDA stack overflow risk (STACK_SIZE: 128 → 256)

## Documentation
- Consolidate changelog/ directory into single CHANGELOG.md
- Fix duplicate links in docs/zh-CN/README.md
- Remove QWEN.md and FINAL_CHECKLIST.md (obsolete)
- Archive legacy specs to specs-archived/

## CI/CD Optimization
- Add paths filtering for pull_request events in ci.yml
- Optimize pages.yml paths (remove '**.md' wildcard)
- Reduce fetch-depth from 0 to 1 in pages.yml
- Simplify docs-consistency job in ci.yml

## Configuration
- Fix CODEOWNERS case sensitivity (@LessUp → @LessUp)
- Add .omc/ to .gitignore

Author: shijiashuai

.github/CODEOWNERS

@@ -19,7 +19,7 @@
 /CMakeLists.txt @LessUp
 
 # Documentation
-/docs/ @Lessup
+/docs/ @LessUp
 /README.md @LessUp
 /README.zh-CN.md @LessUp
 /CHANGELOG.md @LessUp

.github/copilot-instructions.md

@@ -4,7 +4,7 @@
 
 - Treat `openspec/specs/` as the only active specification source.
 - Use or update an OpenSpec change before implementing behavior, workflow, documentation-policy, automation, or structure changes.
-- Ignore `specs-legacy/` for active development.
+- Ignore `specs-archived/` for active development.
 - Prefer deleting or consolidating duplicate docs instead of keeping mirrored content.
 
 ## Current Project Priorities

.github/project-status.md

@@ -1,31 +1,45 @@
-# Project Status: Closeout Phase
+# Project Status: Closeout Phase Complete
 
 ## Current State
 
-This project is in **closeout and maintenance** phase. All core features are complete and stable.
+This project is in **final closeout phase**. All core features are complete and stable. The repository has been comprehensively stabilized for maintenance and archival readiness.
 
 ### Last Major Release
 - **Version**: v2.0.0 (2026-03-13)
 - **Status**: Stable
-- **Next Phase**: Archive-ready
+- **Phase**: Archive-ready
 
 ---
 
-## Repository Status Checklist
+## Repository Health Metrics
+
+| Metric | Value | Status |
+|--------|-------|--------|
+| Total Commits | 43+ | ✅ Clear history |
+| Markdown Files | ~80 | ✅ Curated, no duplicates |
+| C++ Source Files | 16 | ✅ Stable codebase |
+| CUDA Source Files | 5 | ✅ GPU kernels |
+| AI Instruction Files | 3 aligned | ✅ Single source |
+| OpenSpec Capabilities | 6 registered | ✅ Complete registry |
+| Build Configurations | CPU + GPU | ✅ Flexible |
+
+---
+
+## Closeout Checklist
 
 ### ✅ OpenSpec Governance
 - [x] Unified `openspec/` as single source of truth
 - [x] All bilingual specifications in parity
 - [x] Clear capability registration in `openspec.yaml`
-- [x] All legacy specs marked as historical-only
+- [x] Legacy specs archived to `specs-archived/` with historical markers
 
 ### ✅ Documentation
 - [x] README.md focused on value and canonical links
-- [x] AGENTS.md streamlined to 60 lines
+- [x] AGENTS.md streamlined to 68 lines
 - [x] CLAUDE.md created with Claude-specific guidance
 - [x] .github/copilot-instructions.md for Copilot
 - [x] CONTRIBUTING.md aligned to OpenSpec workflow
-- [x] Stale docs (QWEN.md, etc.) updated to stubs
+- [x] Stale docs and duplicates removed
 - [x] Changelog consolidated to canonical directory
 
 ### ✅ Build System
@@ -48,12 +62,48 @@ This project is in **closeout and maintenance** phase. All core features are com
 - [x] Workflows simplified and noise-reduced
 
 ### ✅ GitHub Presentation
-- [x] Description: "High-performance N-body particle simulation..."
+- [x] Description: "High-performance N-body particle simulation with Barnes-Hut algorithm, GPU acceleration, and real-time visualization"
 - [x] Homepage: https://lessup.github.io/n-body/
 - [x] Topics: n-body-simulation, cuda, barnes-hut, gpu-acceleration, particle-physics
 
 ---
 
+## Key Decisions & Rationale
+
+1. **Keep unstaged work as baseline** ← Allows continuous progress without reverts
+2. **Single instruction source** ← Reduces maintenance burden of parallel guidance
+3. **CPU-first build validation** ← Supports diverse development environments
+4. **Minimal LSP stack** ← Avoids context-heavy MCP overhead; clangd is sufficient
+5. **Aggressive duplication removal** ← Sharper, more maintainable docs
+
+---
+
+## Files Changed Summary (Closeout Phase)
+
+### Created (~35 files)
+- OpenSpec specs: `simulation-core.md`, `force-computation.md`, `visualization.md`, `simulation-control.md`, `quality-attributes.md`, `repository-governance.md` + Chinese versions
+- AI Instructions: `AGENTS.zh-CN.md`, `CLAUDE.md`, `.github/copilot-instructions.md`
+- Build & Tooling: `.vscode/settings.json`, `.vscode/extensions.json`, `.githooks/pre-commit`, `scripts/setup-hooks.sh`
+- Guidance: `.copilot-init.md`, `openspec/changes/archive/2026-04-23-project-closeout-stabilization/`
+- OpenSpec config: `openspec.yaml`
+
+### Modified (~20 files)
+- `CMakeLists.txt` (added CUDA option, conditional builds)
+- `scripts/build.sh` (CUDA auto-detection)
+- `README.md`, `README.zh-CN.md` (complete rewrites)
+- `CONTRIBUTING.md` (4-principle restructure)
+- `.github/workflows/pages.yml` (simplified triggers)
+- `CHANGELOG.md` (consolidated to navigation)
+
+### Deleted (~25 files)
+- `specs/` and `specs-legacy/` directories (consolidated to `specs-archived/`)
+- `docs/tutorials/README.md` and `docs/zh-CN/tutorials/README.md` (empty placeholders)
+- `FINAL_CHECKLIST.md` (merged into this file)
+- `QWEN.md` (compatibility stub)
+- Duplicate site content from legacy Jekyll
+
+---
+
 ## Future Development (If Needed)
 
 If further work is required, use the OpenSpec workflow:
@@ -94,5 +144,5 @@ If further work is required, use the OpenSpec workflow:
 
 ---
 
-Last Updated: 2024-04-24
+Last Updated: 2026-04-27
 Status: ✅ Ready for Archive

.github/workflows/ci.yml

@@ -13,6 +13,14 @@ on:
       - '.clang-format'
   pull_request:
     branches: [main, master]
+    paths:
+      - '**.cpp'
+      - '**.cu'
+      - '**.cuh'
+      - '**.hpp'
+      - 'CMakeLists.txt'
+      - 'cmake/**'
+      - '.clang-format'
   workflow_dispatch:
 
 permissions:
@@ -75,66 +83,6 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
-      - name: Verify executable name consistency
-        run: |
-          echo "Checking executable name consistency..."
-
-          # Check nbody_sim appears in key files
-          if grep -rq 'nbody_sim' README.md README.zh-CN.md index.md docs/; then
-            echo "✓ Executable name 'nbody_sim' found in documentation"
-          else
-            echo "⚠ Executable name 'nbody_sim' not found in some docs"
-          fi
-
-          # Check CMakeLists.txt has correct target
-          if grep -q 'add_executable(nbody_sim' CMakeLists.txt; then
-            echo "✓ CMakeLists.txt defines 'nbody_sim' target"
-          else
-            echo "✗ CMakeLists.txt missing 'nbody_sim' target"
-            exit 1
-          fi
-
-      - name: Verify keyboard controls documentation
-        run: |
-          echo "Checking keyboard controls documentation..."
-
-          # Check controls are documented
-          controls_found=0
-          if grep -q 'Space' README.md; then
-            echo "✓ Space key documented"
-            controls_found=$((controls_found + 1))
-          fi
-          if grep -q 'Pause\|pause' README.md; then
-            echo "✓ Pause action documented"
-            controls_found=$((controls_found + 1))
-          fi
-          if grep -q 'Reset\|reset' README.md; then
-            echo "✓ Reset action documented"
-            controls_found=$((controls_found + 1))
-          fi
-
-          if [ $controls_found -ge 2 ]; then
-            echo "✓ Controls documentation check passed"
-          else
-            echo "⚠ Some controls may be missing"
-          fi
-
-      - name: Verify test framework configuration
-        run: |
-          echo "Checking test framework configuration..."
-
-          if grep -q 'googletest' CMakeLists.txt || grep -q 'GoogleTest' CMakeLists.txt; then
-            echo "✓ Google Test configured in CMakeLists.txt"
-          else
-            echo "⚠ Google Test may not be configured"
-          fi
-
-          if grep -q 'rapidcheck' CMakeLists.txt || grep -q 'RapidCheck' CMakeLists.txt; then
-            echo "✓ RapidCheck configured in CMakeLists.txt"
-          else
-            echo "⚠ RapidCheck may not be configured"
-          fi
-
       - name: Verify project structure
         run: |
           echo "Checking project structure..."
@@ -159,6 +107,22 @@ jobs:
             fi
           done
 
+      - name: Verify test framework configuration
+        run: |
+          echo "Checking test framework configuration..."
+
+          if grep -q 'googletest' CMakeLists.txt || grep -q 'GoogleTest' CMakeLists.txt; then
+            echo "✓ Google Test configured in CMakeLists.txt"
+          else
+            echo "⚠ Google Test may not be configured"
+          fi
+
+          if grep -q 'rapidcheck' CMakeLists.txt || grep -q 'RapidCheck' CMakeLists.txt; then
+            echo "✓ RapidCheck configured in CMakeLists.txt"
+          else
+            echo "⚠ RapidCheck may not be configured"
+          fi
+
       - name: Summary
         run: |
           echo ""
@@ -183,68 +147,5 @@ jobs:
           globs: |
             *.md
             docs/**/*.md
-            changelog/**/*.md
             examples/**/*.md
 
-  build-info:
-    name: Build Information
-    runs-on: ubuntu-latest
-    needs: [format-check, docs-consistency]
-    env:
-      FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
-    steps:
-      - name: Display build requirements
-        run: |
-          echo "# N-Body Simulation Build Requirements"
-          echo ""
-          echo "This project requires a CUDA-enabled environment for building."
-          echo ""
-          echo "## Hardware Requirements"
-          echo ""
-          echo "| Component | Minimum | Recommended |"
-          echo "|-----------|---------|-------------|"
-          echo "| GPU | NVIDIA CC 7.0+ | NVIDIA CC 8.0+ |"
-          echo "| VRAM | 4GB | 8GB+ |"
-          echo "| RAM | 8GB | 16GB+ |"
-          echo ""
-          echo "## Software Requirements"
-          echo ""
-          echo "| Component | Version |"
-          echo "|-----------|---------|"
-          echo "| CUDA Toolkit | 11.0+ |"
-          echo "| CMake | 3.18+ |"
-          echo "| OpenGL | 3.3+ |"
-          echo "| GLFW | 3.3+ |"
-          echo "| GLEW | 2.1+ |"
-          echo "| GLM | 0.9.9+ |"
-          echo ""
-          echo "## Build Commands"
-          echo ""
-          echo '```bash'
-          echo "# Clone repository"
-          echo "git clone https://github.com/LessUp/n-body.git"
-          echo "cd n-body"
-          echo ""
-          echo "# Build"
-          echo "mkdir build && cd build"
-          echo "cmake .. -DCMAKE_BUILD_TYPE=Release"
-          echo "cmake --build . -j\$(nproc)"
-          echo '```'
-          echo ""
-          echo "## Run Tests"
-          echo ""
-          echo '```bash'
-          echo "ctest --output-on-failure"
-          echo "./nbody_tests"
-          echo '```'
-          echo ""
-          echo "## Run Simulation"
-          echo ""
-          echo '```bash'
-          echo "./nbody_sim 10000  # 10K particles"
-          echo "./nbody_sim 100000 # 100K particles"
-          echo '```'
-          echo ""
-          echo "---"
-          echo "CI validates formatting and documentation consistency."
-          echo "For full build verification, use a local CUDA environment."

.github/workflows/pages.yml

@@ -6,9 +6,9 @@ on:
     paths:
       - 'site/**'
       - 'docs/**'
-      - 'changelog/**'
-      - 'examples/**'
-      - '**.md'
+      - 'README.md'
+      - 'README.zh-CN.md'
+      - 'CHANGELOG.md'
       - '.github/workflows/pages.yml'
   workflow_dispatch:
 
@@ -29,7 +29,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
         with:
-          fetch-depth: 0
+          fetch-depth: 1
 
       - name: Setup Pages
         uses: actions/configure-pages@v5

.gitignore

@@ -68,3 +68,6 @@ __pycache__/
 .Python
 venv/
 .venv/
+
+# AI tools
+.omc/

AGENTS.md

@@ -11,7 +11,7 @@ Maintain and stabilize a CUDA/OpenGL N-body simulation project that is now in a
 | `openspec/specs/` | Active requirements and repository rules |
 | `openspec/changes/` | Active proposals, designs, delta specs, and task lists |
 | `openspec/changes/archive/` | Completed changes |
-| `specs-legacy/` | Historical-only material; never use as the active source of truth |
+| `specs-archived/` | Historical-only material; never use as the active source of truth |
 | `docs/` | Repository-local reader and contributor documentation |
 | `site/` | GitHub Pages showcase surface |
 | `.github/` | CI, Pages, issue/PR templates, and Copilot instructions |
@@ -37,6 +37,7 @@ Maintain and stabilize a CUDA/OpenGL N-body simulation project that is now in a
 ## Project-Specific Rules
 
 - Treat `openspec/` as the only active specification system.
+- Historical specs in `specs-archived/` are for reference only.
 - During the current cleanup effort, treat existing unstaged repository edits as the working baseline unless the user explicitly says otherwise.
 - Prefer deletion, consolidation, or redirection over keeping duplicate docs and site mirrors.
 - Do not add generic engineering or AI boilerplate; every file must be specific to this project.

AGENTS.zh-CN.md

@@ -11,7 +11,7 @@
 | `openspec/specs/` | 当前活跃需求与仓库规则 |
 | `openspec/changes/` | 活跃提案、设计、变更规格与任务清单 |
 | `openspec/changes/archive/` | 已完成变更 |
-| `specs-legacy/` | 仅供历史参考，绝不能作为当前事实来源 |
+| `specs-archived/` | 仅供历史参考，绝不能作为当前事实来源 |
 | `docs/` | 仓库内读者与贡献者文档 |
 | `site/` | GitHub Pages 展示表面 |
 | `.github/` | CI、Pages、Issue/PR 模板与 Copilot 指令 |
@@ -36,7 +36,7 @@
 
 ## 项目特定规则
 
-- 将 `openspec/` 视为唯一活跃规格系统。
+- 将 `openspec/` 视为唯一活跃规格系统。历史规格在 `specs-archived/` 中仅供参考。
 - 在当前清理阶段，把仓库里现有未提交改动视为工作基线，除非用户明确要求其他处理方式。
 - 遇到重复文档或重复站点内容时，优先删除、合并或重定向，而不是继续并存。
 - 不要添加通用化、无项目针对性的工程文档或 AI 提示模板。