Skip to content

Commit 76d8620

Browse files
LessUpLessUp
committed
merge: final-repo-hardening - repository cleanup and normalization
- Remove empty directories (_bmad/, _bmad-output/, changelog/) - Create docs/TRANSLATION_SCOPE.md for bilingual policy - Delete zh exercises/ and reference/api/ (English-only by design) - Fix VitePress config.ts (remove invalid zh links) - Add OpenSpec specs for AI, CI, docs, governance - Update CI workflow (remove cache from macOS job) - Update AGENTS.md and CLAUDE.md with clangd guidance # Conflicts: # .github/copilot-instructions.md
2 parents b878021 + 0c18a16 commit 76d8620

12 files changed

Lines changed: 505 additions & 6 deletions

File tree

‎.gitignore‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -210,10 +210,6 @@ build_errors.txt
210210
.vscode/settings.json.user
211211
.vscode/launch.json.user
212212

213-
# BMad Method V6
214-
_bmad/
215-
_bmad-output/
216-
217213
# Local git worktrees
218214
.worktrees/
219215

‎AGENTS.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -87,10 +87,14 @@ cmake --preset=release && cmake --build build/release
8787
- **AGENTS.md**: shared repo guidance for Codex-style agents and terminal copilots.
8888
- **CLAUDE.md**: Claude Code specific guidance.
8989
- **`.github/copilot-instructions.md`**: GitHub Copilot repository instructions.
90-
- **LSP**: prefer `clangd` backed by `compile_commands.json`.
90+
- **LSP**: prefer `clangd` backed by `compile_commands.json`. The `.clangd` config at the repo root points `CompilationDatabase` to `build/debug`; all CMake presets export `compile_commands.json` via `CMAKE_EXPORT_COMPILE_COMMANDS=ON`.
9191
- **Review model**: use `/review` before merge or after major cleanup phases.
9292
- **Autopilot strategy**: prefer a longer single-session implementation flow over `/fleet` unless the task is truly parallelizable.
9393

94+
## Editor integration
95+
96+
The `.vscode/` directory is **gitignored** and does not exist in the repository. Workspace settings live only in local developer environments. Do not commit `.vscode/` content — use the `.clangd`, `.editorconfig`, and `CMakePresets.json` files for machine-readable project conventions instead.
97+
9498
## Things to avoid reintroducing
9599

96100
- HonKit / GitBook-era configuration

‎CLAUDE.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ This repository is in **closure and hardening mode** (archive-ready for low-freq
3333

3434
- Docs stack: **VitePress**, published via GitHub Pages
3535
- Build system: **CMake + presets**
36-
- Language server: **clangd**
36+
- Language server: **clangd** — configured via `.clangd` at repo root (`CompilationDatabase: build/debug`); all CMake presets export `compile_commands.json` via `CMAKE_EXPORT_COMPILE_COMMANDS=ON`
3737
- Primary maintenance target: **Linux**
3838
- Repo posture: **archive-ready / low-frequency maintenance**
3939

‎docs/TRANSLATION_SCOPE.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Translation Scope Policy
2+
3+
This document defines which documentation surfaces are maintained bilingually
4+
(English + Simplified Chinese) and which are English-only by design.
5+
6+
## Bilingual surfaces
7+
8+
The following directories are fully bilingual. Every page in `docs/en/` has a
9+
corresponding page in `docs/zh/`:
10+
11+
- `getting-started/`
12+
- `guides/`
13+
- `reference/` (top-level pages: `faq.md`, `troubleshooting.md`, `api-reference.md`)
14+
- `contributing/`
15+
16+
## English-only surfaces
17+
18+
The following are maintained in English only. Chinese readers are directed to the
19+
English version:
20+
21+
- `exercises/` — lab exercises and solutions are tightly coupled to code
22+
examples; translating them would increase maintenance cost without proportional
23+
reader benefit.
24+
- `reference/api/` — auto-generated or low-level API detail pages.
25+
26+
## Reader guidance
27+
28+
A note is present in `docs/zh/index.md` directing Chinese readers to the English
29+
exercises section when they reach that part of the learning path.
30+
31+
## Maintenance rule
32+
33+
When adding a new page to a bilingual surface, add it to both `docs/en/` and
34+
`docs/zh/` in the same commit. When adding a page to an English-only surface,
35+
no Chinese counterpart is required.

‎docs/zh/index.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,11 @@
1717
- **参考文档** —— FAQ、故障排查、API 入口
1818
- **贡献流程** —— AI 辅助与 OpenSpec 驱动的开发模式
1919

20+
## 练习与实验室
21+
22+
练习模块（`exercises/`）和 API 参考子页面仅提供英文版本，请直接访问
23+
[英文练习页面](/en/exercises/README)。
24+
2025
## 贡献者提示
2126

2227
如果你要修改仓库本身，请同时参考：

‎openspec/changes/final-repo-hardening/design.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# Design: Final Repository Hardening
2+
3+
## Overview
4+
5+
This change completes the normalization sequence. `project-closure-normalization` established the structural contract. `final-repo-hardening` closes the remaining gaps and brings the repository to a state where it can be maintained infrequently without accumulating drift.
6+
7+
## Design goals
8+
9+
1. Remove every surface that has no content and no expected future content.
10+
2. Make the bilingual docs surface consistent by policy, not just by effort.
11+
3. Confirm every GitHub Actions workflow either provides clear value or is removed.
12+
4. Confirm AI guidance files are internally consistent and non-redundant.
13+
5. Archive completed OpenSpec changes so active paths stay clean.
14+
6. Leave the repository in a state where a returning maintainer can orient quickly.
15+
16+
---
17+
18+
## Surface audit
19+
20+
The table below classifies each surface under review. Quadrants: **Keep**, **Remove**, **Archive**, **Decide**.
21+
22+
| Surface | Classification | Rationale |
23+
|---|---|---|
24+
| `_bmad/` | **Remove** | Empty directory. Artifact of bmad AI-planning tooling used during initial scaffolding. No content, no future use. |
25+
| `_bmad-output/` | **Remove** | Empty directory. Paired artifact with `_bmad/`. Same rationale: no content, no maintenance value. |
26+
| `changelog/` | **Remove** | Empty directory. Historical releases are tracked through Git tags and GitHub Releases. An empty `changelog/` is misleading noise. |
27+
| `docs/en/exercises/` | **Keep** | Active bilingual surface with exercises content. English-side is complete. Chinese translation is absent — requires explicit decision (see bilingual policy below). |
28+
| `docs/zh/` (gap pages) | **Decide → translate or scope-limit** | `docs/zh/` is missing: exercises section (5 files), `reference/api/` subdirectory (3 files). Must be translated or explicitly excluded from the bilingual scope. |
29+
| `docs/en/contributing/ai-workflow.md` + `docs/zh/contributing/ai-workflow.md` | **Keep with alignment check** | User-facing docs explaining the AI workflow. Must stay aligned with `AGENTS.md`, `CLAUDE.md`, and `.github/copilot-instructions.md`. No duplication of canonical guidance. |
30+
| `.vscode/` | **N/A — not present** | No `.vscode/` directory exists in the repository. No action needed. Editor config is intentionally out of scope. |
31+
| `openspec/explorations/` | **Keep (empty, intentional)** | The `.gitkeep` is deliberate scaffolding for future exploratory notes. The directory is low-cost and consistent with the OpenSpec layout. |
32+
| `ci.yml` | **Keep** | Preset-driven CI for debug/release builds on Linux and macOS. Core maintenance value. |
33+
| `pages.yml` | **Keep** | VitePress build and GitHub Pages deployment. Core maintenance value. |
34+
| `sanitizers.yml` | **Keep with verification** | Sanitizer workflow (ASan, TSan, UBSan). High value; must be verified to pass cleanly on the current codebase before this change closes. |
35+
| `benchmark.yml` | **Keep with verification** | Benchmark execution workflow. Must be verified to pass cleanly. If it silently fails or runs no benchmarks, it should be tightened or removed. |
36+
| `openspec/changes/project-closure-normalization/` | **Archive** | All tasks are complete. Move to `openspec/changes/archive/project-closure-normalization/`. |
37+
38+
---
39+
40+
## Bilingual docs policy decision
41+
42+
**Decision:** The bilingual surface (`docs/en/` + `docs/zh/`) covers the following sections for both languages:
43+
- `getting-started/`
44+
- `guides/`
45+
- `reference/` (top-level pages: `api-reference.md`, `faq.md`, `troubleshooting.md`)
46+
- `contributing/`
47+
48+
The following sections are **English-only by design** and do not require Chinese translations:
49+
- `docs/en/exercises/` — Hands-on exercises are primarily consumed in English in this educational context. Adding a note in `docs/zh/index.md` or the navigation pointing to the English exercises is acceptable.
50+
- `docs/en/reference/api/` subdirectory files (`benchmark-utils.md`, `memory-utils.md`, `simd-wrapper.md`) — API reference pages for C++ utilities. Code-heavy content where Chinese translation provides diminishing returns.
51+
52+
This policy must be documented in `docs/.vitepress/config.ts` navigation structure or a `docs/TRANSLATION_SCOPE.md` so future contributors know what is and is not expected to be translated.
53+
54+
---
55+
56+
## AI guidance alignment strategy
57+
58+
Three canonical AI instruction files exist:
59+
- `AGENTS.md` — primary repo guidance for all AI agents
60+
- `CLAUDE.md` — Claude Code-specific workflow guidance
61+
- `.github/copilot-instructions.md` — GitHub Copilot repository instructions
62+
63+
`docs/en/contributing/ai-workflow.md` and `docs/zh/contributing/ai-workflow.md` are **user-facing docs** that explain the AI workflow to human contributors. They should summarize and link to the canonical files rather than duplicating their content. If any of these docs have drifted from the current canonical guidance, they are updated as part of Phase 3.
64+
65+
---
66+
67+
## GitHub Actions rationalization
68+
69+
Each workflow is expected to satisfy the following contract:
70+
71+
| Workflow | Trigger | Pass criteria | Action if failing |
72+
|---|---|---|---|
73+
| `ci.yml` | push/PR to master | All preset builds pass on Linux (GCC, Clang) and macOS | Blocking — fix before merge |
74+
| `pages.yml` | push to master (docs/** changes) | VitePress build succeeds, `index.html` exists | Blocking — fix before merge |
75+
| `sanitizers.yml` | scheduled or manual | ASan/TSan/UBSan presets pass | Verify passes; fix if broken, remove if structurally broken |
76+
| `benchmark.yml` | scheduled or manual | Benchmarks run to completion without error | Verify passes; tighten or remove if silently empty |
77+
78+
---
79+
80+
## OpenSpec archive sequence
81+
82+
1. When Phase 4 tasks are complete, move `openspec/changes/project-closure-normalization/` to `openspec/changes/archive/project-closure-normalization/`.
83+
2. Move `openspec/changes/final-repo-hardening/` to `openspec/changes/archive/final-repo-hardening/`.
84+
3. Confirm `openspec/changes/` contains only the `archive/` subdirectory.
85+
86+
---
87+
88+
## Trade-offs
89+
90+
- The exercises and API reference subdirectory pages are designated English-only rather than translated. This is a scope decision, not a quality compromise. The highest-value bilingual surfaces (getting-started, guides, reference top-level, contributing) remain fully bilingual.
91+
- `openspec/explorations/` is kept as an intentional empty scaffold. Removing it would be equally valid, but the `.gitkeep` pattern is already established in the repo and costs nothing to maintain.
92+
- `benchmark.yml` is verified before removal is considered. If it works, it stays. This avoids a premature removal of a potentially useful signal.

‎openspec/changes/final-repo-hardening/proposal.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Proposal: Final Repository Hardening
2+
3+
## Summary
4+
5+
Complete the normalization effort started by `project-closure-normalization` by resolving the remaining surface drift, removing stale scaffolding artifacts, tightening CI workflows, and confirming the repository is ready for low-frequency maintenance.
6+
7+
## Relationship to project-closure-normalization
8+
9+
`project-closure-normalization` established the structural contract: OpenSpec layout, VitePress docs, preset-driven CI, AI instruction files, and GitHub Pages positioning. All tasks in that change are complete.
10+
11+
This change (`final-repo-hardening`) is the explicit follow-on. It starts from the state that `project-closure-normalization` delivered and addresses the surfaces that still have unresolved drift, are empty/stale, or need verification before the repository enters a quiet maintenance posture.
12+
13+
Work in this change does not reopen or revisit decisions made in `project-closure-normalization`. It extends them.
14+
15+
## Why
16+
17+
After `project-closure-normalization` closed, a targeted audit identified several surfaces that remain inconsistent with the repository's final intended state:
18+
19+
1. **Stale scaffolding directories** — `_bmad/` and `_bmad-output/` are empty artifacts from AI-assisted planning tooling that was used during early development. They have no content or maintenance value and should be removed.
20+
2. **Empty changelog** — `changelog/` contains no entries. Its presence without content is misleading; the directory should be removed or explicitly replaced by the GitHub Releases/tags surface.
21+
3. **Bilingual docs gap** — `docs/en/` has 20 documentation files; `docs/zh/` has 12. The exercises section and the `reference/api/` subdirectory pages are English-only. This asymmetry needs an explicit decision: either translate or formally mark those surfaces as English-only.
22+
4. **Workflow review needed** — `benchmark.yml` and `sanitizers.yml` need verification that they provide clear maintenance value and do not silently fail on the current repository state.
23+
5. **AI guidance drift** — `docs/en/contributing/ai-workflow.md` and `docs/zh/contributing/ai-workflow.md` may have drifted from the canonical guidance in `AGENTS.md`, `CLAUDE.md`, and `.github/copilot-instructions.md`.
24+
6. **openspec/explorations/** — Contains only a `.gitkeep`. The directory should remain if it provides scaffolding value, but its existence should be explicitly confirmed as intentional.
25+
7. **project-closure-normalization archive** — The completed predecessor change has not been moved to `openspec/changes/archive/`, which leaves an active path cluttered with finished work.
26+
27+
## Scope
28+
29+
### In scope
30+
31+
- Remove empty stale directories (`_bmad/`, `_bmad-output/`, `changelog/`)
32+
- Resolve the bilingual docs asymmetry (translate or explicitly limit scope)
33+
- Verify and tighten `benchmark.yml` and `sanitizers.yml`
34+
- Confirm GitHub metadata (description, topics, homepage URL) matches current positioning
35+
- Align `docs/contributing/ai-workflow.md` with canonical AI instruction files
36+
- Archive `openspec/changes/project-closure-normalization/`
37+
- Archive this change itself when all phases are complete
38+
39+
### Out of scope
40+
41+
- New teaching modules or learning content
42+
- Changes to examples, tests, or benchmarks that are not directly caused by surface cleanup
43+
- New CI platforms or toolchains
44+
- Any expansion of MCP, plugin, or automation tooling
45+
46+
## Success criteria
47+
48+
- No empty or orphaned scaffolding directories remain in the active repository tree.
49+
- The bilingual docs surface is consistent: every user-facing page exists in both languages, or a documented policy explicitly limits scope.
50+
- All four GitHub Actions workflows pass cleanly and provide concrete maintenance value.
51+
- GitHub metadata (description, topics, homepage) accurately reflects the repository's purpose.
52+
- AI guidance documents are internally consistent and not duplicating content unnecessarily.
53+
- `openspec/changes/project-closure-normalization/` is archived.
54+
- The repository can be handed off for low-frequency maintenance with no known surface drift.

‎openspec/changes/final-repo-hardening/specs/ai-assisted-development/spec.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# AI-Assisted Development
2+
3+
## ADDED Requirements
4+
5+
### Requirement: AI Instruction File Consistency
6+
7+
THE Repository SHALL keep `AGENTS.md`, `CLAUDE.md`, and `.github/copilot-instructions.md` mutually consistent with no contradictions between them.
8+
9+
#### Scenario: AI tool loads multiple instruction files
10+
11+
- **WHEN** an AI assistant reads both `AGENTS.md` and `.github/copilot-instructions.md`
12+
- **THEN** it does not receive contradictory instructions about the repository's workflow, tools, or conventions
13+
14+
*Application:* Verified in Phase 3 audit. Any contradiction found is resolved by aligning the lower-priority file to the canonical source (`AGENTS.md`).
15+
16+
---
17+
18+
### Requirement: Compile Commands Export Verified
19+
20+
THE Repository SHALL verify that `CMAKE_EXPORT_COMPILE_COMMANDS` is enabled so `clangd` can function correctly without additional configuration.
21+
22+
#### Scenario: Contributor configures clangd
23+
24+
- **WHEN** a contributor runs any CMake preset and opens the project in an editor backed by `clangd`
25+
- **THEN** `compile_commands.json` is present in the build output directory and `clangd` can index the project without manual setup
26+
27+
---
28+
29+
### Requirement: No Editor Config Committed
30+
31+
THE Repository SHALL NOT commit editor-specific configuration directories (e.g., `.vscode/`) to source control.
32+
33+
#### Scenario: Editor config discovered in repository
34+
35+
- **WHEN** a `.vscode/` or equivalent editor-specific directory is found committed to the repository
36+
- **THEN** it is removed and added to `.gitignore`, or its presence is explicitly justified with a documented rationale
37+
38+
*Rationale:* The project documents `clangd` as the LSP choice but does not prescribe a specific editor. Committed editor config creates maintenance surface without broad benefit.

‎openspec/changes/final-repo-hardening/specs/ci-quality-assurance/spec.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# CI and Quality Assurance
2+
3+
## ADDED Requirements
4+
5+
### Requirement: Workflow Verified to Pass
6+
7+
THE Build_System SHALL have all active GitHub Actions workflows verified to pass cleanly before the repository enters a maintenance posture.
8+
9+
#### Scenario: Workflow verification during hardening
10+
11+
- **WHEN** the final hardening phase runs
12+
- **THEN** each of `ci.yml`, `pages.yml`, `sanitizers.yml`, and `benchmark.yml` either passes cleanly or is explicitly tightened or removed with a documented rationale
13+
14+
*Application:* `sanitizers.yml` and `benchmark.yml` are both verified in Phase 2. A workflow that silently exits with success while producing no real output is not considered passing — it is either fixed or removed.
15+
16+
---
17+
18+
### Requirement: No Silent No-Op Workflows
19+
20+
THE Build_System SHALL NOT keep workflows that execute without asserting any meaningful validation outcome.
21+
22+
#### Scenario: Benchmark workflow runs but asserts nothing
23+
24+
- **WHEN** a workflow step completes without checking that it actually ran its intended validation
25+
- **THEN** the step is modified to assert the expected output or the workflow is removed
26+
27+
---
28+
29+
### Requirement: Compiler Matrix Currency
30+
31+
THE Build_System SHALL keep the CI compiler matrix current with non-end-of-life compiler versions and GitHub Actions runner images.
32+
33+
#### Scenario: CI matrix review
34+
35+
- **WHEN** a maintainer reviews `ci.yml`
36+
- **THEN** the GCC version, Clang version, and runner images are not using deprecated or end-of-life configurations that will begin failing without warning

‎openspec/changes/final-repo-hardening/specs/documentation/spec.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Documentation
2+
3+
## ADDED Requirements
4+
5+
### Requirement: Bilingual Scope Policy
6+
7+
THE Documentation SHALL define and maintain an explicit bilingual scope policy rather than leaving the zh/en gap undocumented.
8+
9+
#### Scenario: Contributor notices a missing Chinese translation
10+
11+
- **WHEN** a contributor finds a docs page that exists in `docs/en/` but not in `docs/zh/`
12+
- **THEN** they can determine from the scope policy whether that page is expected to be translated or is English-only by design
13+
14+
*Application:* `docs/en/exercises/` and `docs/en/reference/api/` subdirectory pages are English-only by design. All other sections in `getting-started/`, `guides/`, `reference/` (top-level), and `contributing/` are fully bilingual.
15+
16+
---
17+
18+
### Requirement: Docs Translation Scope Document
19+
20+
THE Documentation SHALL include a translation scope reference so contributors know what is and is not expected to be bilingual.
21+
22+
#### Scenario: New contributor prepares a Chinese translation
23+
24+
- **WHEN** a contributor wants to add or update a Chinese translation
25+
- **THEN** a scope document (in `docs/TRANSLATION_SCOPE.md` or equivalent) tells them exactly which pages are in scope
26+
27+
---
28+
29+
### Requirement: Contributing Docs Non-Duplication
30+
31+
THE Documentation SHALL ensure that `docs/*/contributing/ai-workflow.md` summarizes and links to canonical AI instruction files rather than duplicating their content verbatim.
32+
33+
#### Scenario: AI workflow docs drift from canonical guidance
34+
35+
- **WHEN** `AGENTS.md` or `CLAUDE.md` is updated
36+
- **THEN** `docs/contributing/ai-workflow.md` does not require a parallel rewrite because it links rather than duplicates

0 commit comments

Comments
 (0)