2027a/auroscope

Watch

Fork 0

Décision — Recentrer v1 sur un wrapper minimal LLM-first #19

New issue

Closed

opened 2026-08-31 02:40:01 +00:00 by hephaistos · 4 comments

hephaistos commented

2026-08-31 02:40:01 +00:00

Owner

MODE: DECISION

Constat

L’architecture actuelle a perdu le produit de vue. Le LLM y est traité comme un enrichissement optionnel autour d’un moteur de règles, d’un protocole d’approbation, d’une fermeture de dépendances et d’une infrastructure de reprise. Or le produit a un seul rôle : faire auditer par un LLM les recettes AUR que Paru va construire, montrer l’audit à l’utilisateur, recueillir une décision par paquet, puis laisser Paru/Pacman exécuter la transaction.

Cette décision repart de ce flux et remplace les ADR qui ont transformé AURoscope en quasi-gestionnaire de paquets.

Flux produit minimal

arguments utilisateur
        │
        ▼
AURoscope transmet à Paru la sélection/résolution
        │
        ▼
liste des pkgbase AUR + worktrees exacts
        │
        ▼
pour chaque pkgbase : diff depuis le dernier commit approuvé
        │               (première utilisation : recette complète)
        ▼
Codex CLI audite le diff et les fichiers pertinents
        │
        ▼
AURoscope présente résumé, risques, preuves et diff
        │
        ▼
approve | inspect | edit+reaudit | skip | cancel
        │
        ▼
Paru exécute les paquets approuvés; Pacman reste natif

Pour une mise à jour système, l’ordre est strict :

mise à jour officielle native — AURoscope lance la phase dépôts officiels de Paru/Pacman (paru -Syu --repo ou l’équivalent exact prouvé pour la version supportée), avec stdin/stdout/stderr et code de sortie inchangés;
aucun audit des paquets officiels — aucune collecte, aucun appel Codex, aucun rapport et aucune décision AURoscope pour un paquet provenant des dépôts Pacman;
audit AUR intermédiaire — seulement après succès de la phase officielle, AURoscope demande à Paru les mises à jour AUR, prépare les recettes exactes, appelle Codex et recueille les choix par pkgbase;
installation AUR native — AURoscope relance Paru avec les paquets approuvés et les exclusions demandées; Paru refait sa résolution normale, appelle makepkg et Pacman, et conserve sa confirmation finale.

AURoscope n’appelle jamais makepkg ou Pacman pour remplacer Paru et n’implémente aucune logique de build/install. Il ajoute uniquement la phase d’audit entre la mise à jour officielle et la relance Paru pour les paquets AUR.

Pour une installation explicite, le même principe s’applique : les paquets officiels restent un flux Paru/Pacman natif sans audit; seuls les pkgbase AUR entrent dans l’audit.

Recherche et installation

Le wrapper couvre aussi les usages ordinaires de Paru, pas seulement la mise à jour :

auroscope <termes>          # recherche/sélection interactive native de Paru
auroscope -S <paquets>      # installation explicite
auroscope <autres options>  # passthrough pour les opérations non auditées

AURoscope délègue la recherche, l’affichage et la sélection numérotée à l’interface native de Paru; il ne maintient aucun index de recherche.
Après sélection, Paru fournit les noms et origines. Un résultat provenant des dépôts officiels est installé par Paru/Pacman sans audit Codex ni décision AURoscope.
Un résultat AUR entre dans la même phase intermédiaire : recette exacte, diff ou audit complet, Codex, puis décision par pkgbase.
Pour une sélection mixte, seuls les pkgbase AUR sont audités. La relance finale de Paru reçoit les cibles officielles sélectionnées et les cibles AUR approuvées; Paru refait toute la résolution, construit l’AUR et installe l’ensemble via Pacman.
Les opérations Paru qui ne peuvent pas construire une recette AUR (requêtes, informations, suppressions, cache, etc.) sont transmises sans audit et conservent leur terminal et leur code de sortie.

AURoscope ne remplace donc ni la recherche Paru, ni la sélection, ni la résolution, ni l’installation. Il interpose seulement l’audit Codex lorsqu’une cible sélectionnée vient de l’AUR.

Architecture recommandée

Un exécutable Go et un seul package interne au départ :

cmd/auroscope/main.go
internal/app/run.go       # orchestration et passthrough argv
internal/app/paru.go      # appels Paru strictement nécessaires
internal/app/recipe.go    # worktree, manifest, diff, aucun sourcing
internal/app/codex.go     # un backend Codex CLI
internal/app/review.go    # rendu terminal et choix utilisateur
internal/app/state.go     # SQLite minimal
internal/app/guard.go     # vérification finale depuis PreBuildCommand

Pas d’interface générique, de framework CLI, de moteur de règles, de système de plugins ni d’autre package tant qu’un besoin concret ne l’impose.

Responsabilités

1. Wrapper Paru transparent

Les arguments non détenus par AURoscope sont transmis tels quels.
Paru reste responsable de la sélection, de la résolution, des dépendances, du téléchargement, du build et de Pacman.
AURoscope utilise une seule sortie machine de Paru, sur une version minimale explicitement supportée, pour obtenir les pkgbase AUR à auditer.
Aucun parseur général de la CLI Paru et aucun resolver parallèle.

2. Recette et comparaison

Auditer le worktree exact que Paru utilisera, ou prouver par un spike étroit comment le worktree audité est réutilisé par l’exécution finale.
Ne jamais sourcer ni exécuter PKGBUILD, .install, patches ou sources pendant l’audit.
Baseline : dernier commit approuvé et construit avec succès pour ce pkgbase.
Si aucune baseline n’existe, envoyer la recette complète.
Construire un bundle borné : diff Git, fichiers modifiés complets, .SRCINFO comme donnée, métadonnées minimales et manifeste/hachage.

3. Audit LLM — cœur du produit

Backend v1 unique : Codex CLI. Aucun backend HTTP en v1.
Le modèle reste configurable; aucun mécanisme automatique de fallback.
Codex s’exécute hors du dépôt de recette, dans un répertoire privé contenant seulement le bundle d’audit.
Une seule réponse JSON structurée : résumé, niveau de risque, constats avec fichier/ligne/preuve, incertitudes et points à vérifier.
Si Codex échoue ou renvoie une réponse invalide, l’audit échoue : retry, skip ou cancel. Il n’existe pas de mode produit « LLM disabled ».
Aucun moteur déterministe concurrent. Les seules vérifications locales sont mécaniques : bornes, chemins, hachages, encodage et validation du JSON.

4. Décision utilisateur

Pour chaque pkgbase :

approve : accepter cette identité exacte;
inspect : ouvrir le rapport/diff puis redemander;
edit : ouvrir la recette, recalculer l’identité, relancer Codex, puis redemander;
skip : exclure ce paquet de la transaction finale;
cancel : annuler la phase AUR.

Paru conserve sa confirmation finale normale. Si un paquet approuvé dépend d’un paquet ignoré, Paru reste l’autorité et explique/refuse la transaction; AURoscope ne calcule pas sa propre fermeture.

5. Exécution et garde minimale

AURoscope relance/exécute Paru avec les paquets approuvés et les exclusions demandées.
Un PreBuildCommand minimal vérifie pkgbase, commit et manifeste/hachage du worktree réel.
Un pkgbase inattendu ou une identité modifiée arrête la phase AUR et retourne à l’audit.
L’état courant tient dans un fichier de transaction privé sous XDG_RUNTIME_DIR; pas de protocole armed/claimed/consumed, PID/inode ou anti-replay contre le même utilisateur.
Le compte local est de confiance; la garde protège seulement contre le drift normal entre audit et build.

6. Persistance minimale

SQLite avec deux concepts, créés par un schéma simple versionné avec PRAGMA user_version :

packages(pkgbase, last_successful_commit, last_manifest_digest, updated_at)
audits(pkgbase, commit, previous_commit, codex_json, decision, created_at)

La baseline n’avance qu’après succès de Paru. Les rapports texte sont régénérables. Pas de journal d’événements, table de processus, approbation durable, artefact réutilisable, backup automatique ou politique de rétention complexe en v1.

Spike unique avant implémentation

Question : quelle commande/surface Paru minimale permet d’obtenir les pkgbase et worktrees exacts, puis de réutiliser ces mêmes worktrees — y compris après édition — pour le build final avec PreBuildCommand ?

Le spike doit prouver sur Arch jetable :

sélection/résolution native;
worktree disponible avant tout code de recette;
édition puis réaudit du même worktree;
garde appelée avant le build;
exclusion d’un paquet puis nouvelle résolution par Paru.

Si cette surface n’existe pas, on ajuste uniquement l’intégration Paru ou on reporte edit; on ne recrée pas un resolver ni un protocole de transaction général.

Tests proportionnés

unitaires : validation JSON Codex, construction du bundle, diff/baseline, décisions, garde;
contrats : une version Paru supportée et Codex CLI;
intégration : recette bénigne, recette suspecte, première installation, mise à jour différentielle, edit+reaudit, skip, drift;
un E2E Arch jetable : sélection → audit Codex simulé → décision → garde → build/install;
aucun test automatisé contre le Pacman réel du poste.

Hors périmètre v1

moteur de règles déterministe;
backend HTTP ou sélection automatique de backend;
remplacement du resolver Paru/libalpm;
analyse exhaustive des sources téléchargées ou du binaire produit;
sandbox de build;
réutilisation de paquets déjà construits;
support multi-plateforme;
daemon, Kanban ou orchestration autonome dans le produit;
protocole de sécurité contre un processus du même UID;
historique et rétention de niveau entreprise.

Conséquences et ADR à superséder

Restent valides dans leur intention : Go, Paru/Pacman comme autorités, inspection sans exécution, identité exacte, SQLite local et décision humaine.

Doivent être supersédés ou fortement réduits : orchestration multi-stage exhaustive, séparation « scanner déterministe + LLM optionnel », protocole d’approbation one-shot durable, schéma SQLite étendu, fermeture de dépendances locale, récupération/rétention complexe et architecture en onze packages.

PR #18 reste bloquée et ne doit pas être fusionnée tant que cette décision n’est pas acceptée puis traduite dans la spécification, les ADR et un nouveau plan court.

Recommandation

Accepter cette architecture LLM-first minimale. Elle couvre exactement le besoin exprimé, garde une protection utile contre le drift, et délègue tout le reste à Paru/Pacman.

Risque non résolu

Le seul risque architectural à prouver est la surface Paru permettant d’auditer/éditer le worktree exact avant le build final. C’est le premier travail exécutable et l’unique raison légitime de complexifier l’intégration.

MODE: DECISION ## Constat L’architecture actuelle a perdu le produit de vue. Le LLM y est traité comme un enrichissement optionnel autour d’un moteur de règles, d’un protocole d’approbation, d’une fermeture de dépendances et d’une infrastructure de reprise. Or le produit a un seul rôle : **faire auditer par un LLM les recettes AUR que Paru va construire, montrer l’audit à l’utilisateur, recueillir une décision par paquet, puis laisser Paru/Pacman exécuter la transaction**. Cette décision repart de ce flux et remplace les ADR qui ont transformé AURoscope en quasi-gestionnaire de paquets. ## Flux produit minimal ```text arguments utilisateur │ ▼ AURoscope transmet à Paru la sélection/résolution │ ▼ liste des pkgbase AUR + worktrees exacts │ ▼ pour chaque pkgbase : diff depuis le dernier commit approuvé │ (première utilisation : recette complète) ▼ Codex CLI audite le diff et les fichiers pertinents │ ▼ AURoscope présente résumé, risques, preuves et diff │ ▼ approve | inspect | edit+reaudit | skip | cancel │ ▼ Paru exécute les paquets approuvés; Pacman reste natif ``` Pour une mise à jour système, l’ordre est strict : 1. **mise à jour officielle native** — AURoscope lance la phase dépôts officiels de Paru/Pacman (`paru -Syu --repo` ou l’équivalent exact prouvé pour la version supportée), avec stdin/stdout/stderr et code de sortie inchangés; 2. **aucun audit des paquets officiels** — aucune collecte, aucun appel Codex, aucun rapport et aucune décision AURoscope pour un paquet provenant des dépôts Pacman; 3. **audit AUR intermédiaire** — seulement après succès de la phase officielle, AURoscope demande à Paru les mises à jour AUR, prépare les recettes exactes, appelle Codex et recueille les choix par `pkgbase`; 4. **installation AUR native** — AURoscope relance Paru avec les paquets approuvés et les exclusions demandées; Paru refait sa résolution normale, appelle `makepkg` et Pacman, et conserve sa confirmation finale. AURoscope n’appelle jamais `makepkg` ou Pacman pour remplacer Paru et n’implémente aucune logique de build/install. Il ajoute uniquement la phase d’audit entre la mise à jour officielle et la relance Paru pour les paquets AUR. Pour une installation explicite, le même principe s’applique : les paquets officiels restent un flux Paru/Pacman natif sans audit; seuls les `pkgbase` AUR entrent dans l’audit. ### Recherche et installation Le wrapper couvre aussi les usages ordinaires de Paru, pas seulement la mise à jour : ```console auroscope <termes> # recherche/sélection interactive native de Paru auroscope -S <paquets> # installation explicite auroscope <autres options> # passthrough pour les opérations non auditées ``` - AURoscope délègue la recherche, l’affichage et la sélection numérotée à l’interface native de Paru; il ne maintient aucun index de recherche. - Après sélection, Paru fournit les noms et origines. Un résultat provenant des dépôts officiels est installé par Paru/Pacman sans audit Codex ni décision AURoscope. - Un résultat AUR entre dans la même phase intermédiaire : recette exacte, diff ou audit complet, Codex, puis décision par `pkgbase`. - Pour une sélection mixte, seuls les `pkgbase` AUR sont audités. La relance finale de Paru reçoit les cibles officielles sélectionnées et les cibles AUR approuvées; Paru refait toute la résolution, construit l’AUR et installe l’ensemble via Pacman. - Les opérations Paru qui ne peuvent pas construire une recette AUR (requêtes, informations, suppressions, cache, etc.) sont transmises sans audit et conservent leur terminal et leur code de sortie. AURoscope ne remplace donc ni la recherche Paru, ni la sélection, ni la résolution, ni l’installation. Il interpose seulement l’audit Codex lorsqu’une cible sélectionnée vient de l’AUR. ## Architecture recommandée Un exécutable Go et **un seul package interne au départ** : ```text cmd/auroscope/main.go internal/app/run.go # orchestration et passthrough argv internal/app/paru.go # appels Paru strictement nécessaires internal/app/recipe.go # worktree, manifest, diff, aucun sourcing internal/app/codex.go # un backend Codex CLI internal/app/review.go # rendu terminal et choix utilisateur internal/app/state.go # SQLite minimal internal/app/guard.go # vérification finale depuis PreBuildCommand ``` Pas d’interface générique, de framework CLI, de moteur de règles, de système de plugins ni d’autre package tant qu’un besoin concret ne l’impose. ## Responsabilités ### 1. Wrapper Paru transparent - Les arguments non détenus par AURoscope sont transmis tels quels. - Paru reste responsable de la sélection, de la résolution, des dépendances, du téléchargement, du build et de Pacman. - AURoscope utilise une seule sortie machine de Paru, sur une version minimale explicitement supportée, pour obtenir les `pkgbase` AUR à auditer. - Aucun parseur général de la CLI Paru et aucun resolver parallèle. ### 2. Recette et comparaison - Auditer le worktree exact que Paru utilisera, ou prouver par un spike étroit comment le worktree audité est réutilisé par l’exécution finale. - Ne jamais sourcer ni exécuter `PKGBUILD`, `.install`, patches ou sources pendant l’audit. - Baseline : dernier commit approuvé et construit avec succès pour ce `pkgbase`. - Si aucune baseline n’existe, envoyer la recette complète. - Construire un bundle borné : diff Git, fichiers modifiés complets, `.SRCINFO` comme donnée, métadonnées minimales et manifeste/hachage. ### 3. Audit LLM — cœur du produit - **Backend v1 unique : Codex CLI.** Aucun backend HTTP en v1. - Le modèle reste configurable; aucun mécanisme automatique de fallback. - Codex s’exécute hors du dépôt de recette, dans un répertoire privé contenant seulement le bundle d’audit. - Une seule réponse JSON structurée : résumé, niveau de risque, constats avec fichier/ligne/preuve, incertitudes et points à vérifier. - Si Codex échoue ou renvoie une réponse invalide, l’audit échoue : retry, skip ou cancel. Il n’existe pas de mode produit « LLM disabled ». - Aucun moteur déterministe concurrent. Les seules vérifications locales sont mécaniques : bornes, chemins, hachages, encodage et validation du JSON. ### 4. Décision utilisateur Pour chaque `pkgbase` : - `approve` : accepter cette identité exacte; - `inspect` : ouvrir le rapport/diff puis redemander; - `edit` : ouvrir la recette, recalculer l’identité, relancer Codex, puis redemander; - `skip` : exclure ce paquet de la transaction finale; - `cancel` : annuler la phase AUR. Paru conserve sa confirmation finale normale. Si un paquet approuvé dépend d’un paquet ignoré, Paru reste l’autorité et explique/refuse la transaction; AURoscope ne calcule pas sa propre fermeture. ### 5. Exécution et garde minimale - AURoscope relance/exécute Paru avec les paquets approuvés et les exclusions demandées. - Un `PreBuildCommand` minimal vérifie `pkgbase`, commit et manifeste/hachage du worktree réel. - Un `pkgbase` inattendu ou une identité modifiée arrête la phase AUR et retourne à l’audit. - L’état courant tient dans un fichier de transaction privé sous `XDG_RUNTIME_DIR`; pas de protocole `armed/claimed/consumed`, PID/inode ou anti-replay contre le même utilisateur. - Le compte local est de confiance; la garde protège seulement contre le drift normal entre audit et build. ### 6. Persistance minimale SQLite avec deux concepts, créés par un schéma simple versionné avec `PRAGMA user_version` : ```text packages(pkgbase, last_successful_commit, last_manifest_digest, updated_at) audits(pkgbase, commit, previous_commit, codex_json, decision, created_at) ``` La baseline n’avance qu’après succès de Paru. Les rapports texte sont régénérables. Pas de journal d’événements, table de processus, approbation durable, artefact réutilisable, backup automatique ou politique de rétention complexe en v1. ## Spike unique avant implémentation Question : **quelle commande/surface Paru minimale permet d’obtenir les pkgbase et worktrees exacts, puis de réutiliser ces mêmes worktrees — y compris après édition — pour le build final avec `PreBuildCommand` ?** Le spike doit prouver sur Arch jetable : 1. sélection/résolution native; 2. worktree disponible avant tout code de recette; 3. édition puis réaudit du même worktree; 4. garde appelée avant le build; 5. exclusion d’un paquet puis nouvelle résolution par Paru. Si cette surface n’existe pas, on ajuste uniquement l’intégration Paru ou on reporte `edit`; on ne recrée pas un resolver ni un protocole de transaction général. ## Tests proportionnés - unitaires : validation JSON Codex, construction du bundle, diff/baseline, décisions, garde; - contrats : une version Paru supportée et Codex CLI; - intégration : recette bénigne, recette suspecte, première installation, mise à jour différentielle, edit+reaudit, skip, drift; - un E2E Arch jetable : sélection → audit Codex simulé → décision → garde → build/install; - aucun test automatisé contre le Pacman réel du poste. ## Hors périmètre v1 - moteur de règles déterministe; - backend HTTP ou sélection automatique de backend; - remplacement du resolver Paru/libalpm; - analyse exhaustive des sources téléchargées ou du binaire produit; - sandbox de build; - réutilisation de paquets déjà construits; - support multi-plateforme; - daemon, Kanban ou orchestration autonome dans le produit; - protocole de sécurité contre un processus du même UID; - historique et rétention de niveau entreprise. ## Conséquences et ADR à superséder Restent valides dans leur intention : Go, Paru/Pacman comme autorités, inspection sans exécution, identité exacte, SQLite local et décision humaine. Doivent être supersédés ou fortement réduits : orchestration multi-stage exhaustive, séparation « scanner déterministe + LLM optionnel », protocole d’approbation one-shot durable, schéma SQLite étendu, fermeture de dépendances locale, récupération/rétention complexe et architecture en onze packages. PR #18 reste bloquée et ne doit pas être fusionnée tant que cette décision n’est pas acceptée puis traduite dans la spécification, les ADR et un nouveau plan court. ## Recommandation Accepter cette architecture LLM-first minimale. Elle couvre exactement le besoin exprimé, garde une protection utile contre le drift, et délègue tout le reste à Paru/Pacman. ## Risque non résolu Le seul risque architectural à prouver est la surface Paru permettant d’auditer/éditer le worktree exact avant le build final. C’est le premier travail exécutable et l’unique raison légitime de complexifier l’intégration.

hephaistos referenced this issue

2026-08-31 02:40:16 +00:00

Plan: executable AURoscope v1 implementation sequence #18

hephaistos added the

Agent/Human

label

2026-08-31 02:44:23 +00:00

hephaistos commented

2026-08-31 02:44:23 +00:00

Author

Owner

Ticket classé comme décision humaine. La discussion continue ici, mais aucune implémentation ni ADR accepté ne sera produit tant que Mathieu n’aura pas publié exactement GO DECISION dans un commentaire distinct.

Ticket classé comme décision humaine. La discussion continue ici, mais aucune implémentation ni ADR accepté ne sera produit tant que Mathieu n’aura pas publié exactement `GO DECISION` dans un commentaire distinct.

mathieu commented

2026-08-31 02:51:06 +00:00

Owner

GO DECISION

hephaistos added

Agent/Hermes

and removed

Agent/Human

labels

2026-08-31 02:56:24 +00:00

hephaistos referenced this issue from a pull request that will close it,

2026-08-31 03:00:06 +00:00

Decision: adopt the minimal LLM-first architecture #20

hephaistos commented

2026-08-31 03:01:42 +00:00

Author

Owner

Décision acceptée par Mathieu via GO DECISION (#1314). Finalisation documentaire livrée dans PR #20 : #20

ADR-0015 devient la décision active; les ADR incompatibles sont supersédés et les anciens artefacts archivés. Le suivi autorisé pour le spike Paru et le nouveau plan minimal est l’issue #21 : #21

Décision acceptée par Mathieu via `GO DECISION` (#1314). Finalisation documentaire livrée dans PR #20 : https://git.2027a.net/2027a/auroscope/pulls/20 ADR-0015 devient la décision active; les ADR incompatibles sont supersédés et les anciens artefacts archivés. Le suivi autorisé pour le spike Paru et le nouveau plan minimal est l’issue #21 : https://git.2027a.net/2027a/auroscope/issues/21

hephaistos closed this issue

2026-08-31 03:01:42 +00:00

hephaistos referenced this issue

2026-08-31 03:01:42 +00:00

Plan: executable AURoscope v1 implementation sequence #18

hephaistos referenced this issue

2026-08-31 03:03:12 +00:00

Decision: adopt the minimal LLM-first architecture #20

hephaistos referenced this issue

2026-08-31 03:11:02 +00:00

Fix ADR numbering for decision #19 #22

hephaistos commented

2026-08-31 03:11:20 +00:00

Author

Owner

Correction de finalisation : la décision acceptée dans l’issue #19 doit porter le numéro dérivé de l’issue, donc ADR-0019, et non ADR-0015.

ADR corrigé : docs/decisions/0019-minimal-llm-first-wrapper.md
commit signé de correction : 0f19cdee550bdfa97a9cb3d02873a5c67a83b18b
tête distante vérifiée : df742a470472d637cd76a712df6328dff280bb0d
PR corrective : #22

La PR #20 reste l’historique de la finalisation initiale déjà fusionnée. La PR #22 corrige uniquement la numérotation contractuelle de l’ADR, toutes ses références et l’explicitation options/risques; elle n’ajoute ni code de production ni plan d’implémentation. Validation : liens Markdown relatifs et clôtures de blocs vérifiés, aucune référence ADR-0015 restante, git diff --check propre.

Correction de finalisation : la décision acceptée dans l’issue #19 doit porter le numéro dérivé de l’issue, donc **ADR-0019**, et non ADR-0015. - ADR corrigé : `docs/decisions/0019-minimal-llm-first-wrapper.md` - commit signé de correction : `0f19cdee550bdfa97a9cb3d02873a5c67a83b18b` - tête distante vérifiée : `df742a470472d637cd76a712df6328dff280bb0d` - PR corrective : https://git.2027a.net/2027a/auroscope/pulls/22 La PR #20 reste l’historique de la finalisation initiale déjà fusionnée. La PR #22 corrige uniquement la numérotation contractuelle de l’ADR, toutes ses références et l’explicitation options/risques; elle n’ajoute ni code de production ni plan d’implémentation. Validation : liens Markdown relatifs et clôtures de blocs vérifiés, aucune référence ADR-0015 restante, `git diff --check` propre.