📝 docs(restructure): split AGENTS.md (1296 → 130 lines) + 9 focused guides #17

Open
arcodange wants to merge 7 commits from feature/restructure-agents-md into main

7 Commits

Author SHA1 Message Date
29272b8fba 🔀 merge: integrate origin/main (PR #16 JSON logging fix) into restructure branch
Some checks failed
CI/CD Pipeline / Build Docker Cache (push) Successful in 26s
CI/CD Pipeline / CI Pipeline (push) Failing after 5m46s
CI/CD Pipeline / Trigger Docker Push (push) Has been skipped
PR #16 (commit c17fb4f) introduced 2 things while this restructure branch
was in flight:
1. A fix in pkg/config/config.go (peekJSONLogging) so the very first log
   line is JSON when DLC_LOGGING_JSON=true.
2. Its own attempt to shorten AGENTS.md (1296 → 191 lines).

Resolution:
- Code/scripts changes from #16 (config.go, server.go, scripts/*,
  gitea-client.sh) accepted as-is via auto-merge.
- AGENTS.md conflict resolved by keeping our version (130 lines,
  fully externalized to documentation/*.md). Our approach goes further
  in the lazy-loading direction (D-004, 128k context constraint),
  externalizing every detail instead of keeping minimal inline content.

Caught up the missing /api/version endpoint in documentation/API.md
(commit acebea3 just before this merge) so we don't regress on the
new endpoint introduced by #16.

Pre-commit hooks already validated each upstream commit. Re-running
on the merge to confirm.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-03 00:02:19 +02:00
acebea353b 📝 docs(api): add /api/version endpoint reference
Endpoint introduced in PR #16 (commit c17fb4f) was missing from our
restructured documentation/API.md. Catching up before merging origin/main
into this feature branch.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-03 00:01:43 +02:00
732eee7586 🐛 fix(adr): correct ADR 0018-0019 dates (2024 → 2026) — Tâche 6 Phase D
Friction documentaire identifiée pendant l'audit Phase A : les ADRs
0018 (User Management) et 0019 (PostgreSQL Integration) avaient des
dates 2024-04-XX dans leur header, alors que le projet a démarré
le 2026-04-01 (cf. CHANGELOG.md, première entrée).

C'est un typo. Implementation Date était bien à 2026-04-08 dans les
deux fichiers, ce qui confirme le diagnostic.

Fix :
- adr/0018-user-management-auth-system.md : 2024-04-06 → 2026-04-06
- adr/0019-postgresql-integration.md     : 2024-04-07 → 2026-04-07

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-02 23:28:34 +02:00
88a934dfd2 📝 docs(restructure): rewrite AGENTS.md as short directive (Tâche 6 Phase C)
AGENTS.md passe de 1296 → 130 lignes, sous la cible 200 fixée en
D-004 (lazy loading 128k). Ne contient plus que :
- Project overview (court)
- Tools & technologies (table)
- Project structure (tree)
- Tableau "Detailed Guides" pointant vers documentation/*.md
  (12 entrées, tous liens vérifiés valides)
- Index des ADR-clés avec liens (13 entrées, tous valides)
- AI agent info (court, pointe vers AGENT_USAGE_GUIDE)
- Commit conventions (court, pointe vers .vibe/skills/commit-message/)
- BDD feature structure (court, pointe vers ADR-0008 + BDD_GUIDE)
- Retention policy (gardée intégralement, directive ARCODANGE)
- Support (procédure escalade en 5 étapes)

Section Version Management (ex-928-1076, ~150 lignes) entièrement
SUPPRIMÉE — totalement redondante avec documentation/version-management-
guide.md (cf. analyse Phase A `~/.vibe/plans/task-6-phase-a-results.md`).

Lien cassé ligne 1277 corrigé : `0019-bdd-feature-structure.md`
(inexistant) remplacé par référence à ADR-0008 (bdd-testing) + ADR-0025
(scenario-isolation) qui sont les vraies sources autoritaires.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-02 23:28:24 +02:00
41ee8c56ac 📝 docs(restructure): split AGENTS.md into focused guides (Tâche 6 Phase B)
Création de 9 fichiers neufs pour décharger AGENTS.md (1296 lignes →
~130) en documents lazy-loadables, compatibles avec la limite de
contexte 128k de Mistral Vibe (cf. ARCODANGE migration Phase 1,
Tâche 6 du curriculum).

Sept guides ciblés sous documentation/ :
- HISTORY.md            : phases historiques 1-9 du développement
- CLI.md                : commandes CLI, server lifecycle, config DLC_*
- API.md                : endpoints REST, OpenAPI, Greet v1/v2
- OBSERVABILITY.md      : OpenTelemetry + Jaeger, sampler types, test
- TROUBLESHOOTING.md    : issues connues + pointeurs vers guides spé
- CODE_EXAMPLES.md      : snippets endpoint/logging/context, pointeurs ADR
- ROADMAP.md            : potential features, architectural improvements

Deux fichiers racine :
- CHANGELOG.md          : user-facing, format Keep a Changelog
- AGENT_CHANGELOG.md    : décisions structurantes des agents AI
                          (référencé par AGENTS.md, n'existait pas)

Le contenu est extrait fidèlement d'AGENTS.md sans réinterprétation.
Phase C (réécriture AGENTS.md court) suit dans le commit suivant.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-02 23:28:10 +02:00
73a3af1552 📝 docs: audit and correct all ADR statuses and content
Full pass over all 25 ADRs to align documentation with actual
implementation state. Changes by ADR:

README index: completely rewritten — previous table mapped numbers to
wrong titles from 0010 onward.

0008 (BDD Testing): added note that flat features/ structure and godog
CLI invocation are superseded by ADR-0024; framework decision stands.

0009 (Hybrid Testing): renamed from "Combine BDD and Swagger-based
testing" to "BDD Testing with OpenAPI Documentation"; clarified that
the SDK-testing layer was never built and has no open issue.

0013 (OpenAPI/Swagger): removed leftover merge conflict artifact
(=======) and duplicated 60-line block.

0015 (Cobra CLI): fixed status contradiction — body said "Implemented"
while footer said "Proposed". Now Accepted.

0018 (User Management): status Proposed → Accepted; system is fully
implemented (JWT, bcrypt, GORM repos all present).

0019 (PostgreSQL): status Proposed → Accepted (Partial); added warning
that sqlite_repository.go and gorm/driver/sqlite still present contrary
to ADR intent.

0021 (JWT Retention): fixed wrong cross-reference (previously cited
ADR-0009 "Hybrid Testing" as source of JWT multi-secret support); fixed
title number from "10" to "21"; clarified that base JWT is implemented
but the retention cleanup job is not.

0022 (Rate Limiting/Cache): added warning block linking to open Gitea
issue #13; changed all 20 false  implementation checkboxes to .

0023 (Config Hot Reloading): added note that BDD scenarios exist for
this feature but the feature itself is not yet implemented.

0024 (BDD Organization): status Proposed → Accepted; modular domain
structure is fully built.

0025 (BDD Scenario Isolation): status Proposed → Accepted (Partial);
Phase 1 done, Phase 2 blocked on ADR-0022.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-12 23:26:09 +02:00
8bae62c28e 📝 docs: add two missing ADR files (0011 validation, 0014 gRPC)
ADR 0011 and 0014 were referenced in the README list but their files
were absent from the repository. Reconstruct them from available context:

- 0011: go-playground/validator selection (already implemented in go.mod)
- 0014: gRPC adoption strategy (evaluated and deferred/rejected)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-12 23:25:25 +02:00