chore: finalize repository closeout

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: LessUp

.clang-tidy

@@ -1,6 +1,7 @@
 ---
 # Clang-tidy configuration for SGEMM Optimization Project
-# Focuses on correctness and performance issues, avoids style nitpicks
+# Focuses on correctness/performance issues and avoids naming rules that fight
+# CUDA, cuBLAS, WMMA, and Google Test conventions.
 
 Checks: >
   -*,
@@ -11,7 +12,6 @@ Checks: >
   -modernize-use-trailing-return-type,
   -modernize-use-nodiscard,
   performance-*,
-  readability-identifier-naming,
   -readability-function-cognitive-complexity,
   -readability-identifier-length,
   -readability-magic-numbers
@@ -21,27 +21,5 @@ WarningsAsErrors: ''
 HeaderFilterRegex: '.*'
 
 CheckOptions:
-  - key: readability-identifier-naming.NamespaceCase
-    value: lower_case
-  - key: readability-identifier-naming.FunctionCase
-    value: lower_case
-  - key: readability-identifier-naming.VariableCase
-    value: lower_case
-  - key: readability-identifier-naming.ConstantCase
-    value: UPPER_CASE
-  - key: readability-identifier-naming.ConstantPrefix
-    value: 'k'
-  - key: readability-identifier-naming.ParameterCase
-    value: lower_case
-  - key: readability-identifier-naming.StructCase
-    value: lower_case
-  - key: readability-identifier-naming.ClassCase
-    value: lower_case
-  - key: readability-identifier-naming.EnumConstantCase
-    value: lower_case
-  - key: readability-identifier-naming.MemberCase
-    value: lower_case
-  - key: readability-identifier-naming.PrivateMemberSuffix
-    value: '_'
   - key: performance-move-const-arg.CheckTriviallyCopyableMove
     value: '0'

.clangd

@@ -5,4 +5,6 @@ Index:
   Background: Build
 
 Diagnostics:
+  # CUDA toolkit headers and generated compile flags vary across machines; keep
+  # clangd focused on semantic navigation rather than noisy include hygiene.
   UnusedIncludes: None

.github/copilot-instructions.md

@@ -1,17 +1,10 @@
 # Copilot Instructions
 
-This repository is in a **closeout-oriented** phase. Optimize for consolidation, clarity, and archive-ready stability.
+Use `AGENTS.md` for shared repository rules and `openspec/AGENTS.md` for OpenSpec workflow details. This file only records Copilot-specific deltas.
 
-## Repository Rules
+## Copilot Defaults
 
-- Treat `openspec/specs/*` as the authoritative stable spec source.
-- Use active change artifacts under `openspec/changes/<change>/` as the implementation contract.
-- Prefer deleting or merging redundant docs, workflows, and configs over preserving duplicate files.
-- Keep `README.md` as the repo entry point and `index.md` + `docs/` as the public landing/documentation surface.
-
-## Working Preferences
-
-- Prefer CMake-based validation and `openspec validate --all` for repository-wide changes.
-- Use `gh` for repository metadata and GitHub-side operations.
-- Assume `clangd` + `compile_commands.json` is the shared LSP baseline.
-- Avoid adding project-level instructions unless they are specific to this repository and do not duplicate existing guidance.
+- Prefer concise, surgical changes on `master`; do not create release/version branch automation.
+- Use `gh` for repository metadata, Actions inspection, and GitHub-side maintenance.
+- Prefer CMake/OpenSpec validation commands already documented in `AGENTS.md`; do not invent extra tooling.
+- Keep generated guidance repository-specific to CUDA SGEMM, GitHub Pages, and OpenSpec closeout work.

.github/workflows/openspec-validation.yml

@@ -13,9 +13,14 @@ on:
       - 'README.md'
       - 'README.zh-CN.md'
       - '_config.yml'
+      - '_includes/**'
+      - '_sass/**'
+      - 'assets/**'
       - 'docs/**'
+      - 'index.md'
       - 'openspec/**'
       - 'specs.md'
+      - 'zh/**'
   push:
     branches: [master]
     paths:
@@ -28,9 +33,14 @@ on:
       - 'README.md'
       - 'README.zh-CN.md'
       - '_config.yml'
+      - '_includes/**'
+      - '_sass/**'
+      - 'assets/**'
       - 'docs/**'
+      - 'index.md'
       - 'openspec/**'
       - 'specs.md'
+      - 'zh/**'
   workflow_dispatch:
 
 jobs:
@@ -73,9 +83,9 @@ jobs:
       - name: Validate ID uniqueness
         run: |
           # Match complete IDs only, exclude sub-IDs like REQ-KERNEL-001.1
-          req_dups=$(grep -rh "REQ-" openspec/specs/ 2>/dev/null | grep -oE "REQ-[A-Z]+-[0-9]+(?!\.[0-9])" | sort | uniq -d)
-          dec_dups=$(grep -rh "DEC-" openspec/specs/ 2>/dev/null | grep -oE "DEC-[A-Z]+-[0-9]+(?!\.[0-9])" | sort | uniq -d)
-          con_dups=$(grep -rh "CON-" openspec/specs/ 2>/dev/null | grep -oE "CON-[A-Z]+-[0-9]+(?!\.[0-9])" | sort | uniq -d)
+          req_dups=$(grep -rhPo "REQ-[A-Z]+-[0-9]+(?!\.[0-9])" openspec/specs/ 2>/dev/null | sort | uniq -d)
+          dec_dups=$(grep -rhPo "DEC-[A-Z]+-[0-9]+(?!\.[0-9])" openspec/specs/ 2>/dev/null | sort | uniq -d)
+          con_dups=$(grep -rhPo "CON-[A-Z]+-[0-9]+(?!\.[0-9])" openspec/specs/ 2>/dev/null | sort | uniq -d)
 
           test -z "$req_dups" || (echo "::error::Duplicate REQ IDs found: $req_dups" && exit 1)
           test -z "$dec_dups" || (echo "::error::Duplicate DEC IDs found: $dec_dups" && exit 1)
@@ -85,7 +95,7 @@ jobs:
         run: |
           legacy_files=$(grep -RInE '(^|[[:space:]`(])specs/(product|rfc|testing)/' \
             AGENTS.md CLAUDE.md CHANGELOG.md CONTRIBUTING.md README.md README.zh-CN.md \
-            specs.md openspec/README.md openspec/AGENTS.md docs .github/workflows 2>/dev/null || true)
+            specs.md zh/specs.md openspec/README.md openspec/AGENTS.md docs zh/docs .github/workflows 2>/dev/null || true)
           if [ -n "$legacy_files" ]; then
             echo "::error::Legacy spec path references found:"
             echo "$legacy_files"
@@ -100,3 +110,10 @@ jobs:
             echo "$nav_orders"
             exit 1
           fi
+
+          zh_nav_orders=$(grep -rh "nav_order:" zh/docs/ 2>/dev/null | sort | uniq -d)
+          if [ -n "$zh_nav_orders" ]; then
+            echo "::error::Duplicate nav_order values found in zh/docs/:"
+            echo "$zh_nav_orders"
+            exit 1
+          fi

.github/workflows/pages.yml

@@ -1,6 +1,5 @@
 # GitHub Pages Deployment
-# Builds and deploys the project documentation site to GitHub Pages
-# Uses Jekyll with just-the-docs theme
+# Builds and deploys the public documentation portal.
 
 name: Deploy to GitHub Pages
 
@@ -40,16 +39,6 @@ jobs:
       - name: Setup Pages
         uses: actions/configure-pages@v5
 
-      - name: Cache Jekyll build
-        uses: actions/cache@v4
-        with:
-          path: |
-            .jekyll-cache
-            _site
-          key: ${{ runner.os }}-jekyll-${{ hashFiles('**/*.md', '**/*.yml') }}
-          restore-keys: |
-            ${{ runner.os }}-jekyll-
-
       - name: Build with Jekyll
         uses: actions/jekyll-build-pages@v1
         with:

AGENTS.md

@@ -31,6 +31,13 @@ If two files say the same thing, keep one and remove the other.
 4. `/review` before large deletions, workflow changes, or archive
 5. `/opsx:archive` only after specs, docs, workflows, and validation agree
 
+## Branch and Worktree Policy
+
+- `master` is the only long-lived branch.
+- Short-lived local branches or worktrees are allowed only as temporary isolation for a specific task.
+- Before closeout, merge completed work back to `master`, delete temporary branches/worktrees, and ensure local and remote branch lists contain no stale task branches.
+- Do not add release/version branch automation; this repository favors a single-mainline closeout flow.
+
 ## Repository Boundaries
 
 ### Code

CLAUDE.md

@@ -1,36 +1,15 @@
 # CLAUDE.md
 
-Claude-specific operating notes for this repository.
+Claude-specific deltas for this repository. Shared repository rules live in `AGENTS.md`; OpenSpec rules live in `openspec/AGENTS.md`.
 
-## Preferred Command Flow
+## Command Flow
 
-1. Use `/opsx:explore` if the cleanup scope or trade-offs are not clear.
-2. Use `/opsx:propose` and `/opsx:apply` for any non-trivial repo-wide cleanup.
-3. Use `/review` before:
-   - deleting multiple files
-   - changing workflow topology
-   - archiving an OpenSpec change
-4. Use `/opsx:archive` only after specs, docs, workflows, and validation are aligned.
+1. Use `/opsx:explore`, `/opsx:propose`, `/opsx:apply`, `/review`, and `/opsx:archive` for non-trivial repository-wide changes.
+2. Use `/review` before deleting multiple files, changing workflow topology, or archiving an OpenSpec change.
+3. Avoid `/fleet` unless the work is genuinely independent and will not create branch/worktree cleanup debt.
 
-## How to Work Here
+## Claude Operating Notes
 
-- The repository is in a **finish-and-stabilize** phase, not a feature-expansion phase.
-- Prefer one longer implementation pass over many small speculative branches.
-- Use subagents for bounded research or log inspection, not for broad uncontrolled fan-out.
-- Avoid `/fleet` by default; only use it when tasks are truly independent and parallelizable.
-
-## Tooling Baseline
-
-- Regenerate `compile_commands.json` through the normal CMake configure step.
-- Treat `clangd` as the shared C/CUDA navigation baseline across tools.
-- Prefer `gh` for About/topics/homepage, Actions, issues, and PR metadata.
-- Prefer skills/native CLI over heavyweight MCP integration unless a concrete gain is obvious.
-- Use `/review` as the primary quality gate before major cleanup milestones.
-- Use `/research` or remote-only assistance sparingly, mainly when repository-local evidence is insufficient.
-
-## Repository-Specific Reminders
-
-- `openspec/specs/*` is the stable source of truth.
-- `README.md` is the repository entry point; `index.md` + `docs/` are the public landing/documentation surface.
-- Remove or merge redundant docs instead of preserving decorative placeholders.
-- Keep instructions concise and repository-specific; do not re-import generic AI handbook content.
+- Keep one long-running closeout pass on `master` unless isolation is necessary; temporary worktrees must be merged and removed before completion.
+- Prefer repository-local evidence, OpenSpec artifacts, `gh`, and clangd/compile commands over remote-only research.
+- Do not duplicate `AGENTS.md` content here; update the shared guide if a rule applies to all AI tools.

CONTRIBUTING.md

@@ -28,6 +28,10 @@ Stable specs live under `openspec/specs/`. Active changes live under `openspec/c
 4. `/review` before major deletions, workflow changes, or archive
 5. `/opsx:archive` once tasks, docs, specs, and validation all agree
 
+## Branch model
+
+`master` is the only long-lived branch. Use a short-lived local branch or worktree only when a task needs isolation, then merge it back to `master` and delete the temporary branch/worktree before closeout. Do not introduce release/version branch automation for routine changes.
+
 ## Validation
 
 ```bash

README.md

@@ -2,93 +2,56 @@
 
 [![CI](https://github.com/LessUp/sgemm-optimization/actions/workflows/ci.yml/badge.svg)](https://github.com/LessUp/sgemm-optimization/actions/workflows/ci.yml)
 [![Pages](https://github.com/LessUp/sgemm-optimization/actions/workflows/pages.yml/badge.svg)](https://lessup.github.io/sgemm-optimization/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE.md)
 ![CUDA](https://img.shields.io/badge/CUDA-11.0+-76B900?logo=nvidia&logoColor=white)
 ![C++](https://img.shields.io/badge/C%2B%2B-17-00599C?logo=c%2B%2B&logoColor=white)
 
 English | [简体中文](README.zh-CN.md)
 
-Progressive CUDA SGEMM tutorial and reference implementation, from naive kernels to Tensor Core WMMA. Includes cuBLAS-backed verification, benchmark harness, and OpenSpec-governed repository rules.
+A compact CUDA SGEMM learning project that walks from a readable baseline kernel to Tensor Core WMMA, with cuBLAS verification and a CMake-first build.
 
-## Why this repository exists
+## What makes it useful
 
-- **Show the optimization ladder clearly**: naive → tiled → bank-conflict-free → double-buffer → Tensor Core WMMA
-- **Stay readable**: each optimization lives in its own kernel file with a consistent launch interface
-- **Stay verifiable**: kernels are checked against cuBLAS with separate tolerances for FP32 and Tensor Core paths
-- **Stay maintainable**: OpenSpec keeps docs, workflow, and validation rules aligned
-
-## Optimization ladder
-
-| Stage | Kernel | What you learn |
-|------:|--------|----------------|
-| 1 | [Naive](docs/kernel-naive/) | Thread-to-output mapping and baseline cost |
-| 2 | [Tiled](docs/kernel-tiled/) | Shared-memory blocking and data reuse |
-| 3 | [Bank-Free](docs/kernel-bank-free/) | Padding away 32-way bank conflicts |
-| 4 | [Double Buffer](docs/kernel-double-buffer/) | Latency hiding through staged tiles |
-| 5 | [Tensor Core](docs/kernel-tensor-core/) | WMMA usage with guarded FP32 fallback |
+- **One optimization ladder**: naive -> tiled -> bank-conflict-free -> double-buffer -> Tensor Core.
+- **Comparable kernel interfaces**: every FP32 kernel uses the same `(A, B, C, M, K, N, stream)` launcher shape.
+- **Verification-first harness**: kernel output is checked against cuBLAS with separate tolerances for FP32 and Tensor Core paths.
+- **Learning-oriented docs**: GitHub Pages carries the full walkthrough instead of duplicating it in the README.
 
 ## Quick start
 
 ```bash
 git clone https://github.com/LessUp/sgemm-optimization.git
 cd sgemm-optimization
 
-# Recommended: CMake
 cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
 cmake --build build -j$(nproc)
 ./build/bin/sgemm_benchmark -a
 ctest --test-dir build
 ```
 
-```bash
-# Quick local alternative
-make GPU_ARCH=sm_86
-make benchmark
-make test
-```
-
-## Where to start
-
-| If you want to... | Start here |
-|-------------------|------------|
-| Build and run once | [Getting Started](docs/getting-started/) |
-| Learn the optimization path | [Learning Path](docs/learning-path/) |
-| Understand repository structure | [Architecture](docs/architecture/) |
-| See performance context | [Benchmark Results](docs/benchmark-results/) |
-| Inspect governance rules | [Specifications](specs/) |
+Runtime tests and benchmarks require a CUDA-capable local machine. Hosted CI is limited to compile-time, formatting, repository-structure, OpenSpec, and Pages checks.
 
-## Validation boundary
+## Start here
 
-- **Local GPU machine**: runtime tests, correctness checks, benchmarking
-- **GitHub Actions**: format/style, CUDA compile, OpenSpec checks, Pages deployment
+| Goal | Entry point |
+|------|-------------|
+| Use the project site | [GitHub Pages](https://lessup.github.io/sgemm-optimization/) |
+| Build and run once | [Getting Started](docs/getting-started.md) |
+| Follow the kernel ladder | [Learning Path](docs/learning-path.md) |
+| Inspect the source layout | [Architecture](docs/architecture.md) |
+| Read the normative specs | [Specifications](specs.md) |
 
-Standard FP32 kernels: `rtol=1e-3`, `atol=1e-4`. Tensor Core path: `rtol=5e-2`, `atol=1e-2`.
-
-## Repository layout
+## Source map
 
 ```text
-src/
-├── kernels/        # Five SGEMM kernel variants
-├── utils/          # CUDA RAII, verification, benchmark helpers
-└── main.cu         # Benchmark entry point
-tests/
-└── test_sgemm.cu   # Google Test suite
-docs/               # Learning-oriented documentation
-openspec/           # Stable specs, changes, workflow guidance
+src/kernels/   CUDA SGEMM implementations
+src/utils/     CUDA RAII, verification, benchmark helpers
+src/main.cu    benchmark CLI
+tests/         Google Test coverage against cuBLAS
+docs/          learning documentation mirrored on Pages
+openspec/      stable specs and change workflow
 ```
 
-## Project status
-
-This repository is in **archive-ready** state. All kernel implementations are complete, tests pass, and documentation is aligned. Non-trivial changes follow the OpenSpec workflow:
-
-1. `/opsx:explore` — clarify scope and trade-offs
-2. `/opsx:propose "description"` — create change artifacts
-3. `/opsx:apply` — implement tasks
-4. `/review` — quality gate
-5. `/opsx:archive` — merge and close
-
-Stable specs: `openspec/specs/`. Active changes: `openspec/changes/<change>/`.
-
 ## License
 
-MIT. See [LICENSE](LICENSE).
+MIT. See [LICENSE.md](LICENSE.md).