ncly-docs-vault / M99 #12

But

Une extension ncly-docs-vault, appelée ncly docs vault, que chaque entreprise forke dans son tap privé. Elle permet à l'agent de n'importe quel employé de trouver le bon projet, puis le bon fichier, parmi des milliers de dépôts convertis. Les originaux restent intacts. Rien de neuf à part Git, une CI et un skill.

Jalon : M7, après M3 (extensions), M5 (hub de docs) et M6 (fr-CA)

Hors portée : MCP et hébergement, skills de conversion, écriture, recherche vectorielle, RBAC plus fin que la forge Git, Windows

CMO

• Les archives dorment dans SharePoint et les voûtes documentaires
• M5 rassemble seulement les docs/ de tes projets locaux
• M3 ne branche une extension qu'au niveau d'un domaine entier
• Un agent d'entreprise n'a donc aucun chemin fiable vers le savoir archivé

FMO

Décisions

• Sous-extension : une sous-commande inconnue d'un domaine du core retombe sur ncly-<domain>-<sub>, mais une vraie sous-commande du core gagne toujours. C'est une nouvelle décision, implémentée dans M3
• Langage : un script Python uv d'un seul fichier, qui tourne partout depuis le tap et se forke facilement
• Catalogue : partagé, bâti par une CI. Les métadonnées sont visibles par toute l'organisation, et le contenu reste protégé par les droits Git de chaque dépôt
• Contrat de projet : un frontmatter dans README.md, plus un index.md en divulgation progressive. C'est une seule source, et le JSON est toujours généré. On écarte project.json (deux fichiers qui dérivent) et nicely.toml (qui mélangerait deux concepts)
• Facettes et sources : définies dans la config, jamais dans le code

Contrat (publié dans le cli-spec avant l'écriture des skills de conversion)

---
id: "1448"
title: Migration ERP
department: Finances
year: 2019
subjects: [erp, migration]
status: archived
visibility: internal   # ou exclude
original: https://sharepoint.example.com/...
---

Commandes

ncly docs vault build [--dry-run]       # CI, compte de service
ncly docs vault sync                    # employé : tire le catalogue
ncly docs vault list [<facet>] [--json]
ncly docs vault find [<text>] [--facet <k=v>]... [--json]
ncly docs vault view <project> [<path>] [--json]

Chemin heureux

1. La CI lance build, chaque nuit et à chaque push. Elle fait un clone partiel des README et des index, valide le frontmatter, passe gitleaks, puis pousse catalog.json et une page par facette
2. L'employé lance sync, qui se résume à un git pull
3. L'agent, guidé par le skill docs-vault, passe par list, find, puis view. Ce dernier télécharge un seul fichier, avec les droits de l'employé

Cas limites

• Frontmatter invalide → avertissement avec un code, le projet reste listé par son nom de dépôt
• Dépôt illisible → VAULT_NO_ACCESS, avec le propriétaire à contacter
• Titre sensible → visibility: exclude, et le projet reste hors du catalogue
• Original non converti → view donne le lien sans jamais lire le fichier
• Réorganisation → on modifie les facettes dans la config et on relance build
• Catalogue périmé → list affiche built_at
• Document contenant des instructions → le skill le traite comme des données

Corpus : 50 projets fictifs (tests et démo), puis tes dépôts, puis la preuve de concept client.

How we'll know it works

• Scénarios testscript avec un tap fictif et des dépôts en file:// :
  • build génère le catalogue, et --dry-run n'écrit rien
  • Un projet exclude est absent du catalogue
  • Un dépôt illisible renvoie VAULT_NO_ACCESS
  • ncly docs vault résout vers l'extension, mais une sous-commande du core gagne toujours
• just check et just signoff
• Éval agent : au moins 9 bonnes réponses sur 10 (bon projet et bon fichier), sur le corpus fictif puis sur le client
• Tes dépôts : build signale moins de 10 % de projets invalides
• Client : 50 projets démontrés en une semaine

Premortem

1. Métadonnées incohérentes
   • Signe : plus de 10 % de projets invalides
   • Correctif : le contrat est publié avant les skills de conversion, et build le valide
2. La recherche texte rate les vraies questions
   • Signe : l'éval tombe sous 9/10
   • Correctif : les subjects et l'index.md sont curés, et le skill reformule en français et en anglais. Un vrai moteur de recherche va dans M99
3. Le compte de service de la CI fuit
   • Signe : un jeton qui traîne
   • Correctif : lecture seule, jeton de courte durée, gitleaks avant chaque push
4. Un titre confidentiel est visible par tous
   • Signe : une plainte
   • Correctif : exclude, avec une revue au moment de la conversion
5. La règle de sous-extension arrive trop tard
   • Signe : M3 livre sans elle
   • Correctif : une décision prise maintenant (principe 11)
6. Les forks dérivent de la référence
   • Signe : un fork modifie le code
   • Correctif : tout le spécifique passe par la config
7. La synchro de milliers de dépôts bloque
   • Signe : build dépasse 10 minutes, ou une invite d'identifiants apparaît
   • Correctif : clones partiels, parallélisme borné, synchro incrémentale, GIT_TERMINAL_PROMPT=0

👍 Zero questions left. Say "execute" or "go" 🚀

Planning Phase 📐