living-ai-documentation 1.2.0 → 1.4.0

package/dist/starter-doc/AI/PROJECT-INSTRUCTIONS.md

@@ -54,8 +54,11 @@ Do not create durable documentation for trivial fixes, mechanical renames, or fo
 ## Progress Tracking
 
 The `DOCS_FOLDER/WORKLOG/` folder holds the operational state of in-progress tasks and the resume points between AI assistants. It does not replace ADRs.
+The `DOCS_FOLDER/WORKLOG/` folder contains three complementary kinds of files; none of them replaces the durable ADRs that live under `DOCS_FOLDER/ADRS/`.
 
-`DOCS_FOLDER/WORKLOG/current-task.md` is the shared resume point. Every assistant must read it before resuming a task and update it before handing over when it has started, finished, interrupted, or left a known follow-up.
+### 1. `DOCS_FOLDER/WORKLOG/current-task.md` — shared resume point
+
+Every assistant must read it before resuming a task and update it before handing over when it has started, finished, interrupted, or left a known follow-up.
 
 The worklog must stay factual and useful for the next agent:
 
@@ -67,7 +70,50 @@ The worklog must stay factual and useful for the next agent:
 - remaining verifications;
 - next recommended action.
 
-Create a dedicated document under `DOCS_FOLDER/WORKLOG/` for an MVP ticket when more detailed tracking becomes necessary. Durable decisions stay in ADRs.
+### 2. `DOCS_FOLDER/WORKLOG/ROADMAP.md` — ticket backlog
+
+Ordered list of tickets needed to ship the product (or a major milestone). Format close to an ADR: frontmatter (`date`, `status`, `description`, `tags`) + Markdown body.
+
+The starter ships an example roadmap — the user must replace it with the project's real tickets.
+
+When a ticket is done, the agent:
+
+1. checks and strikes through the ticket's line in `ROADMAP.md`;
+2. creates a dedicated document under `DOCS_FOLDER/WORKLOG/` recording the realization (see section 3).
+
+Checking convention inside the "Recommended order" section:
+
+- `[ ]` or `[]` — ticket not started;
+- `[x] ~~Ticket XX - ...~~` — ticket done, struck through for quick scanning.
+
+### 3. `DOCS_FOLDER/WORKLOG/YYYY_MM_DD_HH_mm_[WORKLOG]_ticket_XX_<slug>.md` — per-ticket realization record
+
+Every time a roadmap ticket is completed, create a dedicated document under `DOCS_FOLDER/WORKLOG/`. The format looks like an ADR (same frontmatter) but the **semantics differ**:
+
+- ADRs (`DOCS_FOLDER/ADRS/`) document the project's **durable decisions**: architecture, public contracts, structural conventions. They describe the **WHAT** and the **WHY**.
+- per-ticket WORKLOG documents record the **realization** of a roadmap ticket: what was done, what choices were made during execution, what verifications were run. They describe **WHAT THE AGENT DID** for that specific ticket.
+
+If a durable choice is made during a ticket (for example, picking a folder-structure convention), create an architectural ADR under `DOCS_FOLDER/ADRS/` and point the WORKLOG document to that ADR — do not duplicate the reasoning.
+
+Recommended frontmatter for a per-ticket WORKLOG document:
+
+```markdown
+---
+**date:** YYYY-MM-DD
+**status:** To Be Validated
+**description:** One sentence summarizing what was done for this ticket.
+**tags:** worklog, ticket, <domain slugs>
+---
+```
+
+Recommended sections in the body:
+
+- **Context** — short reminder of the ticket and its goal (one paragraph, link to `ROADMAP.md`);
+- **Realization** — factual list of what was done;
+- **Choices made** — technical decisions taken during the ticket. Point to an ADR if the decision is durable;
+- **Verifications** — tests passed, manual validations;
+- **Follow-ups** — points of attention for the next tickets;
+- **Related documents** — link to `ROADMAP.md` and any ADR(s).
 
 ## ADRs
 

package/dist/starter-doc/AI/default/AGENTS.md

@@ -9,7 +9,7 @@ Before making changes:
 3. Read `DOCS_FOLDER/AI/PROJECT-USEFUL-COMMANDS.md` to know the development, build, test, lint, and setup commands.
 4. Read `memory/MEMORY.md` and load only useful memory files.
 5. Read rules in `DOCS_FOLDER/AI/rules/*.md`.
-6. Read `DOCS_FOLDER/WORKLOG/current-task.md` if present to resume the state of the current task.
+6. Read `DOCS_FOLDER/WORKLOG/current-task.md` if present to resume the state of the current task, and `DOCS_FOLDER/WORKLOG/ROADMAP.md` if present to know which ticket to pick up next.
 7. Inspect ADRs in `DOCS_FOLDER/ADRS/` by reading `description` and `tags` first, then open the full ADR only when relevant.
 8. Check whether the `living-ai-documentation` MCP is available and use it to create, update, and keep documentation reliable when the task touches a decision, rule, command, stack, or technical document.
 

package/dist/starter-doc/AI/default/CLAUDE.md

@@ -9,7 +9,7 @@ Before making changes:
 3. Read `DOCS_FOLDER/AI/PROJECT-USEFUL-COMMANDS.md` to know the development, build, test, lint, and setup commands.
 4. Read `memory/MEMORY.md` and load only useful memory files.
 5. Read rules in `DOCS_FOLDER/AI/rules/*.md`.
-6. Read `DOCS_FOLDER/WORKLOG/current-task.md` if present to resume the state of the current task.
+6. Read `DOCS_FOLDER/WORKLOG/current-task.md` if present to resume the state of the current task, and `DOCS_FOLDER/WORKLOG/ROADMAP.md` if present to know which ticket to pick up next.
 7. Inspect ADRs in `DOCS_FOLDER/ADRS/` by reading `description` and `tags` first, then open the full ADR only when relevant.
 8. Check whether the `living-ai-documentation` MCP is available and use it to create, update, and keep documentation reliable when the task touches a decision, rule, command, stack, or technical document.
 

package/dist/starter-doc/WORKLOG/ROADMAP.md

@@ -0,0 +1,41 @@
+---
+**date:** 2026-01-01
+**description:** Example ticket roadmap — an ordered backlog used to deliver the product incrementally, with a visible acceptance criterion per ticket. This roadmap is written by the user; it is shipped only as an example.
+**tags:** roadmap, tickets, mvp, planning
+---
+
+# Tickets (example)
+
+> This is an example roadmap shipped by the Living Documentation starter. Replace the tickets below with the project's real backlog. AI agents must rely on this roadmap to decide which ticket to pick up next.
+
+## Checking convention
+
+- `[ ]` or `[]` — ticket not started;
+- `[x] ~~Ticket XX - ...~~` — ticket done, struck through for quick scanning.
+
+## Recommended order
+
+1. [x] ~~Ticket 01 - Initialize the project~~
+2. [ ] Ticket 02 - First screen of the nominal flow
+
+> This is an example ticket for the user (remove this line once the real roadmap is written)
+
+## Ticket 01 - Initialize the project
+
+Goal: lay down the application foundations, ready to evolve.
+
+Tasks:
+
+- create the project structure (folder layout, baseline dependencies);
+- configure linting and formatting;
+- add a minimal layout and a routing system;
+- verify that the application starts locally.
+
+Acceptance criteria:
+
+- the application starts locally without errors;
+- the main routes exist;
+- the code is typed if the stack allows it;
+- no backend is required at this stage.
+
+## Ticket 02 - Complete me ...

package/dist/starter-doc-fr/AI/PROJECT-INSTRUCTIONS.md

@@ -54,8 +54,11 @@ Ne pas créer de documentation durable pour les corrections triviales, renommage
 ## Suivi de progression
 
 Le dossier `DOCS_FOLDER/WORKLOG/` contient l'état opérationnel des tâches en cours et les points de reprise entre assistants IA. Il ne remplace pas les ADR.
+Le dossier `DOCS_FOLDER/WORKLOG/` contient trois types de fichiers complémentaires, aucun d'entre eux ne remplace les ADR durables qui vivent dans `DOCS_FOLDER/ADRS/`.
 
-`DOCS_FOLDER/WORKLOG/current-task.md` est le point de reprise partagé. Tout assistant doit le lire avant de reprendre une tâche et le mettre à jour avant de rendre la main lorsqu'il a commencé, terminé, interrompu ou laissé une suite connue.
+### 1. `DOCS_FOLDER/WORKLOG/current-task.md` — point de reprise partagé
+
+Tout assistant doit le lire avant de reprendre une tâche et le mettre à jour avant de rendre la main lorsqu'il a commencé, terminé, interrompu ou laissé une suite connue.
 
 Le worklog doit rester factuel et utile pour l'agent suivant :
 
@@ -67,7 +70,50 @@ Le worklog doit rester factuel et utile pour l'agent suivant :
 - vérifications restantes ;
 - prochaine action recommandée.
 
-Créer un document dédié dans `DOCS_FOLDER/WORKLOG/` pour un ticket MVP lorsqu'un suivi plus détaillé devient nécessaire. Les décisions durables restent dans les ADR.
+### 2. `DOCS_FOLDER/WORKLOG/ROADMAP.md` — backlog de tickets
+
+Liste ordonnée des tickets à réaliser pour livrer le produit (ou une grande étape). Format proche d'un ADR : frontmatter (`date`, `status`, `description`, `tags`) + corps Markdown.
+
+Le starter livre une roadmap d'exemple — l'utilisateur doit la remplacer par les tickets réels du projet.
+
+Quand un ticket est terminé, l'agent :
+
+1. coche et barre la ligne du ticket dans `ROADMAP.md` ;
+2. crée un document dédié dans `DOCS_FOLDER/WORKLOG/` qui consigne la réalisation (voir point 3).
+
+Convention de cochage dans la section « Ordre recommandé » :
+
+- `[ ]` ou `[]` — ticket non démarré ;
+- `[x] ~~Ticket XX - ...~~` — ticket terminé, barré pour visualisation rapide.
+
+### 3. `DOCS_FOLDER/WORKLOG/YYYY_MM_DD_HH_mm_[WORKLOG]_ticket_XX_<slug>.md` — trace de réalisation par ticket
+
+À chaque fois qu'un ticket de roadmap est terminé, créer un document dédié dans `DOCS_FOLDER/WORKLOG/`. Le format ressemble à un ADR (même frontmatter) mais la **sémantique est différente** :
+
+- les ADR (`DOCS_FOLDER/ADRS/`) documentent les **décisions durables** du projet : architecture, contrats publics, conventions structurantes. Ils décrivent le **QUOI** et le **POURQUOI**.
+- les documents WORKLOG par ticket documentent la **réalisation** d'un ticket de roadmap : ce qui a été fait, les choix retenus pendant l'exécution, les vérifications passées. Ils décrivent **CE QUE L'AGENT A FAIT** pour ce ticket précis.
+
+Si un choix durable est pris pendant la réalisation d'un ticket (par exemple, le choix d'une convention de structure de dossiers), créer un ADR architectural dans `DOCS_FOLDER/ADRS/` et faire pointer le document WORKLOG vers cet ADR — ne pas dupliquer le raisonnement.
+
+Frontmatter recommandé du document WORKLOG par ticket :
+
+```markdown
+---
+**date:** YYYY-MM-DD
+**status:** To Be Validated
+**description:** Une phrase qui résume ce qui a été fait pour ce ticket.
+**tags:** worklog, ticket, <slugs métiers>
+---
+```
+
+Sections recommandées dans le corps :
+
+- **Contexte** — rappel du ticket et de son objectif (un paragraphe court, lien vers `ROADMAP.md`) ;
+- **Réalisation** — liste factuelle de ce qui a été fait ;
+- **Choix retenus** — décisions techniques prises pendant le ticket. Pointer vers un ADR si la décision est durable ;
+- **Vérifications** — tests passés, validations manuelles ;
+- **Suites éventuelles** — points de vigilance pour les tickets suivants ;
+- **Documents liés** — lien vers `ROADMAP.md` et ADR(s) éventuel(s).
 
 ## ADR
 

package/dist/starter-doc-fr/AI/default/AGENTS.md

@@ -9,7 +9,7 @@ Avant toute modification :
 3. Lire `DOCS_FOLDER/AI/PROJECT-USEFUL-COMMANDS.md` pour connaître les commandes de développement, build, test, lint et setup.
 4. Lire `memory/MEMORY.md` et charger seulement les fichiers mémoire utiles à la tâche.
 5. Lire toutes les règles dans `DOCS_FOLDER/AI/rules/*.md`.
-6. Lire `DOCS_FOLDER/WORKLOG/current-task.md` si présent pour reprendre l'état de la tâche courante.
+6. Lire `DOCS_FOLDER/WORKLOG/current-task.md` si présent pour reprendre l'état de la tâche courante, et `DOCS_FOLDER/WORKLOG/ROADMAP.md` si présent pour savoir quel ticket attaquer ensuite.
 7. Inspecter les ADR dans `DOCS_FOLDER/ADRS/` en lisant d'abord `description` et `tags`, puis ouvrir l'ADR complet seulement s'il est pertinent.
 8. Vérifier si le MCP `living-ai-documentation` est disponible et l'utiliser pour créer, mettre à jour et fiabiliser la documentation lorsque la tâche touche une décision, une règle, une commande, la stack ou un document technique.
 

package/dist/starter-doc-fr/AI/default/CLAUDE.md

@@ -9,7 +9,7 @@ Avant toute modification :
 3. Lire `DOCS_FOLDER/AI/PROJECT-USEFUL-COMMANDS.md` pour connaître les commandes de développement, build, test, lint et setup.
 4. Lire `memory/MEMORY.md` et charger seulement les fichiers mémoire utiles à la tâche.
 5. Lire toutes les règles dans `DOCS_FOLDER/AI/rules/*.md`.
-6. Lire `DOCS_FOLDER/WORKLOG/current-task.md` si présent pour reprendre l'état de la tâche courante.
+6. Lire `DOCS_FOLDER/WORKLOG/current-task.md` si présent pour reprendre l'état de la tâche courante, et `DOCS_FOLDER/WORKLOG/ROADMAP.md` si présent pour savoir quel ticket attaquer ensuite.
 7. Inspecter les ADR dans `DOCS_FOLDER/ADRS/` en lisant d'abord `description` et `tags`, puis ouvrir l'ADR complet seulement s'il est pertinent.
 8. Vérifier si le MCP `living-ai-documentation` est disponible et l'utiliser pour créer, mettre à jour et fiabiliser la documentation lorsque la tâche touche une décision, une règle, une commande, la stack ou un document technique.
 

package/dist/starter-doc-fr/WORKLOG/ROADMAP.md

@@ -0,0 +1,41 @@
+---
+**date:** 2026-01-01
+**description:** Exemple de roadmap de tickets — backlog ordonné pour livrer progressivement le produit, avec un critère d'acceptation visible par ticket. Cette roadmap est écrite par l'utilisateur, elle est fournie à titre d'exemple.
+**tags:** roadmap, tickets, mvp, planning
+---
+
+# Tickets (exemple)
+
+> Ceci est une roadmap d'exemple fournie par le starter Living Documentation. Remplacer les tickets ci-dessous par le backlog réel du projet. Les agents IA doivent se baser sur cette roadmap pour savoir quel ticket attaquer ensuite.
+
+## Convention de cochage
+
+- `[ ]` ou `[]` — ticket non démarré ;
+- `[x] ~~Ticket XX - ...~~` — ticket terminé, barré pour la lisibilité.
+
+## Ordre recommandé
+
+1. [x] ~~Ticket 01 - Initialiser le projet~~
+2. [ ] Ticket 02 - Premier écran du parcours nominal
+
+> Ceci est un exemple de ticket pour l'utilisateur (supprimer cette ligne une fois la vraie roadmap écrite)
+
+## Ticket 01 - Initialiser le projet
+
+Objectif : poser la base applicative, prête à évoluer.
+
+Tâches :
+
+- créer la structure du projet (arborescence, dépendances de base) ;
+- configurer le linting et le formatage ;
+- ajouter un layout minimal et un système de routes ;
+- valider que l'application démarre localement.
+
+Critères d'acceptation :
+
+- l'application démarre localement sans erreur ;
+- les routes principales existent ;
+- le code est typé si la stack le permet ;
+- aucun backend n'est requis à ce stade.
+
+## Ticket 02 - Complétez ...

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "living-ai-documentation",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Local Markdown documentation hub with a built-in MCP server — coding agents create ADRs, draw diagrams and detect drift while you code.",
   "main": "dist/src/server.js",
   "bin": {
@@ -57,6 +57,9 @@
     "express": "5.2.1",
     "marked": "12.0.2"
   },
+  "overrides": {
+    "glob": "^13.0.0"
+  },
   "devDependencies": {
     "@playwright/test": "^1.59.1",
     "@types/archiver": "^7.0.0",