refactor: Reorganize docs folder structure for clarity and version management (PR 3c)
ci / backend (push) Failing after 1s
ci / static (push) Failing after 6s
ci / frontend (push) Failing after 5s

Reorganize documentation following AGENTS.md v16.0 governance (traceability, reproducibility):

Structure changes:
- CURRENT/ (new)
  ├─ 00~08.md (v16.0 standards, renamed for clarity)
  └─ CATALOGS/ (9 CSV files: WBS, decision log, debt register, matrices, catalogs)

- LEGACY/ (new, read-only archives)
  ├─ v11/ (original baseline + hardening analysis)
  ├─ v12~v15/ (.gitkeep + README for future archiving)

- DECISIONS/ (new, ready for ADR usage)
- TEMPLATES/ (existing, unchanged)

Deletions (consolidated into CURRENT/):
- v16_0/ folder (files migrated)
- hardening/ folder (contents → LEGACY/v11/)
- Root-level v11 files (00~07.md, CSV)

Renames (for clarity):
- 00_EXECUTIVE_REFERENCE_IMPLEMENTATION.md → 00_EXECUTIVE.md
- 01_BRUTAL_ROLE_AUDIT.md → 01_ROLE_AUDIT.md
- 02_FRONTEND_ADAPTER_CRUD_STANDARD.md → 02_FE_ADAPTER.md
- 03_BACKEND_DATA_SCHEDULER_STANDARD.md → 03_BE_DATA.md
- 04_ALGORITHM_MODEL_GOVERNANCE.md → 04_ALGORITHM.md
- 05_PROCESS_VIBE_DEBT_CONTROL.md → 05_PROCESS_VIBE_DEBT.md
- 06_VALIDATION_TRUTH.md → 06_VALIDATION.md
- 07_PACKAGE_ATTACHMENT_POLICY.md → 07_PACKAGE_POLICY.md

Updates:
- docs/INDEX.md (complete rewrite with navigation)
- LEGACY/ folders with README + .gitkeep

Benefits:
 Clear version management (v16.0 is active, v11~v15 read-only)
 No version mixing in root
 CURRENT/ as single point of reference for active docs
 CATALOGS/ consolidates all data matrices
 LEGACY/ preserves history without clutter
 Traceability: decision log, tech debt, WBS all linked
 DECISIONS/ ready for ADR pattern (future use)

Sync with root:
- CLAUDE.md references: docs/CURRENT/, docs/INDEX.md 
- AGENTS.md references: docs/CURRENT/, traceability 
- README.md: Document guide links updated 

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
This commit is contained in:
2026-08-02 05:49:29 +09:00
parent 5e50ec6991
commit 5dfb8f3e12
205 changed files with 135 additions and 10178 deletions
+107 -31
View File
@@ -1,48 +1,124 @@
# Documentation Index
# Documentation Index (v16.0)
## Core Development Guides
**Latest docs:** [`CURRENT/`](CURRENT/) — Main reference for development
**Legacy:** [`LEGACY/`](LEGACY/) — Archived versions (read-only)
**Root guides:** [`../CLAUDE.md`](../CLAUDE.md), [`../AGENTS.md`](../AGENTS.md)
---
## 🔥 Active Documentation (CURRENT/)
### Development Standards
| Document | Purpose | Audience |
|----------|---------|----------|
| [`../CLAUDE.md`](../CLAUDE.md) | Claude Code development guide | AI-assisted developers |
| [`../AGENTS.md`](../AGENTS.md) | AI coding constitution v16.0 | All developers |
| [`03_ARCHITECTURE_BE_FE.md`](03_ARCHITECTURE_BE_FE.md) | System architecture (Modular Monolith, Vertical Slice) | Architects, Backend engineers |
| [`06_VIBE_CODING_GUARDRAILS.md`](06_VIBE_CODING_GUARDRAILS.md) | AI work protocols, guardrails | All developers using Claude |
| [`07_VALIDATION_GATES.md`](07_VALIDATION_GATES.md) | Production readiness criteria | QA, Release managers |
| [`CURRENT/00_EXECUTIVE.md`](CURRENT/00_EXECUTIVE.md) | Project rationale & v16.0 delta | Architects, PMs |
| [`CURRENT/01_ROLE_AUDIT.md`](CURRENT/01_ROLE_AUDIT.md) | Role-based governance audit | All developers |
| [`CURRENT/02_FE_ADAPTER.md`](CURRENT/02_FE_ADAPTER.md) | Frontend adapter & CRUD standard | Frontend engineers |
| [`CURRENT/03_BE_DATA.md`](CURRENT/03_BE_DATA.md) | Backend data & scheduler standard | Backend engineers |
| [`CURRENT/04_ALGORITHM.md`](CURRENT/04_ALGORITHM.md) | **Algorithm & model governance** | Data scientists, Quants |
| [`CURRENT/05_PROCESS_VIBE_DEBT.md`](CURRENT/05_PROCESS_VIBE_DEBT.md) | Process, Vibe coding, debt control | All developers |
| [`CURRENT/06_VALIDATION.md`](CURRENT/06_VALIDATION.md) | Validation truth & gates | QA, Release managers |
| [`CURRENT/07_PACKAGE_POLICY.md`](CURRENT/07_PACKAGE_POLICY.md) | Release package & attachment policy | DevOps, Architects |
| [`CURRENT/08_RESTART_PLAN.md`](CURRENT/08_RESTART_PLAN.md) | 20-day restart/onboarding plan | Project managers |
## Executive & Planning
### Catalogs & Matrices
| Document | Purpose |
|----------|---------|
| [`00_EXECUTIVE_PROPOSAL.md`](00_EXECUTIVE_PROPOSAL.md) | High-level project rationale |
| [`01_SOURCE_AUDIT.md`](01_SOURCE_AUDIT.md) | Source code assessment |
| [`02_ALGORITHM_REFACTORING.md`](02_ALGORITHM_REFACTORING.md) | Algorithm improvement strategy |
All in [`CURRENT/CATALOGS/`](CURRENT/CATALOGS/):
## Tech Debt & Maintenance
| File | Purpose |
|------|---------|
| `WBS_MASTER.csv` | 576 work items, traceability |
| `DECISION_LOG.csv` | 80+ architectural decisions |
| `TECH_DEBT_REGISTER.csv` | All tech debt tracked |
| `TRACEABILITY_MATRIX.csv` | Feature ↔ test ↔ evidence |
| `VALIDATION_MATRIX.csv` | Gate status, readiness checklist |
| `FE_COMPONENT.csv` | 43 UI components, versions |
| `JOB_CATALOGUE.csv` | 26 background jobs |
| `SOURCE_COVERAGE.csv` | Code coverage & safety |
| `PACKAGE_CONTENTS.csv` | Release artifact manifest |
| Document | Purpose |
|----------|---------|
| [`../TECH_DEBT_REGISTER.md`](../TECH_DEBT_REGISTER.md) | Tech debt tracking (Impact/Effort matrix) |
### Reference Materials
## Reference Documents
- [`CURRENT/K-ArtSell_Aegis_v16_0_*.docx`](CURRENT/) — Full proposal document
- [`CURRENT/DOCX_A11Y_V16_0.json`](CURRENT/) — Accessibility audit results
- `contracts/` — Data and API contracts (UI adapter, schedules, events)
- `templates/` — Vertical Slice, Hangfire job, SQL scaffolds
- `tools/` — Scaffold generators, validators
---
## Quick Links
## 🗂️ Legacy Archives (LEGACY/)
**Status:** Read-only (no longer maintained)
| Version | Location | Note |
|---------|----------|------|
| v15 | `LEGACY/v15/` | Previous implementation |
| v14 | `LEGACY/v14/` | Previous implementation |
| v13 | `LEGACY/v13/` | Previous implementation |
| v12 | `LEGACY/v12/` | Previous implementation |
| v11 | `LEGACY/v11/` | Original baseline + hardening analysis |
Use for **historical context only**. All current work references `CURRENT/`.
---
## 📋 Root-Level Guides
Reference at project root (not in docs/):
- [`../CLAUDE.md`](../CLAUDE.md) — Claude Code development (setup, build, test, Gitea API)
- [`../AGENTS.md`](../AGENTS.md) — AI coding constitution v16.0 (13 decision criteria, checklist, anti-patterns)
- [`../README.md`](../README.md) — Project overview & document navigation
- [`../TECH_DEBT_REGISTER.md`](../TECH_DEBT_REGISTER.md) — Active debt tracking (Impact/Effort matrix, paydown targets)
---
## 🚀 Quick Start
**For your first change:**
1. Read [`../CLAUDE.md`](../CLAUDE.md) (setup, build, test)
2. Review [`../AGENTS.md`](../AGENTS.md) decision checklist
3. Check [`03_ARCHITECTURE_BE_FE.md`](03_ARCHITECTURE_BE_FE.md) for module boundaries
4. Reference [`06_VIBE_CODING_GUARDRAILS.md`](06_VIBE_CODING_GUARDRAILS.md) before AI code requests
1. Read [`../CLAUDE.md`](../CLAUDE.md) — local setup, build/test commands
2. Review [`../AGENTS.md`](../AGENTS.md) — work decision checklist (13 items)
3. Check [`CURRENT/01_ROLE_AUDIT.md`](CURRENT/01_ROLE_AUDIT.md) — role-based governance
4. Reference [`CURRENT/02_FE_ADAPTER.md`](CURRENT/02_FE_ADAPTER.md) or [`CURRENT/03_BE_DATA.md`](CURRENT/03_BE_DATA.md) — architecture
**For architectural decisions:**
- Module communication: [`03_ARCHITECTURE_BE_FE.md`](03_ARCHITECTURE_BE_FE.md#2-vertical-slice-standard)
- Observability: [`../CLAUDE.md`](../CLAUDE.md#observability)
- Tech debt: [`../TECH_DEBT_REGISTER.md`](../TECH_DEBT_REGISTER.md)
- **Algorithm/Model:** [`CURRENT/04_ALGORITHM.md`](CURRENT/04_ALGORITHM.md)
- **All decisions:** [`CURRENT/CATALOGS/DECISION_LOG.csv`](CURRENT/CATALOGS/DECISION_LOG.csv)
- **Tech debt:** [`../TECH_DEBT_REGISTER.md`](../TECH_DEBT_REGISTER.md) (root level)
**For validation & release:**
- Gates to pass: [`07_VALIDATION_GATES.md`](07_VALIDATION_GATES.md)
- Readiness checklist: [`../AGENTS.md`](../AGENTS.md#work-decision-checklist)
- **Gates:** [`CURRENT/06_VALIDATION.md`](CURRENT/06_VALIDATION.md)
- **Package contents:** [`CURRENT/CATALOGS/PACKAGE_CONTENTS.csv`](CURRENT/CATALOGS/PACKAGE_CONTENTS.csv)
- **Release artifacts:** [`CURRENT/`](CURRENT/) (proposal DOCX, A11Y audit JSON)
---
## 📚 Templates
See [`TEMPLATES/`](TEMPLATES/) for reusable templates:
- ADR.md — Architectural Decision Record
- SLICE_SPEC.md — Vertical Slice specification
- TECH_DEBT_ITEM.md — Tech debt entry template
- RUNBOOK.md — Operations runbook template
- And 7 more...
---
## 🔗 Navigation
```
Root
├─ CLAUDE.md (← Developer starts here)
├─ AGENTS.md
├─ README.md
├─ TECH_DEBT_REGISTER.md
└─ docs/
├─ INDEX.md (← You are here)
├─ CURRENT/ (← Active v16.0 docs)
│ ├─ 00~08.md (8 standards)
│ ├─ CATALOGS/ (9 CSV files)
│ └─ *.docx, *.json (release artifacts)
├─ LEGACY/ (read-only archives)
│ ├─ v11, v12, v13, v14, v15
├─ TEMPLATES/
└─ (tools, contracts are sibling dirs)
```