Audit de compétence Clerk CLI

Cross-vérifiez skills/core/clerk-cli/ dans ce référentiel par rapport à la source Clerk CLI réelle et proposez des modifications précises là où la compétence a divergé. La CLI est la source de vérité ; la compétence est la documentation du mainteneur qui doit la suivre.

Cette tâche nécessite un inventaire complet des commandes, pas un passage rapide avec grep. Construisez d'abord le modèle source, puis comparez-le aux affirmations actuelles de la compétence.

Entrées

Source CLI de vérité : un checkout clerk/cli contenant packages/cli-core/src/commands/**, plus packages/cli-core/src/cli.ts, cli-program.ts, mode.ts, et tout fichier référencé dans packages/cli-core/src/lib/.
Compétence cible : skills/core/clerk-cli/SKILL.md et skills/core/clerk-cli/references/*.md.

Résolution du checkout source

Résolvez le checkout source CLI dans cet ordre :

Utilisez --source <path> quand fourni. Le chemin doit contenir packages/cli-core/src/commands/.
Si le référentiel courant contient lui-même packages/cli-core/src/commands/, utilisez la racine du référentiel courant.
Si CLERK_CLI_REPO est défini, utilisez ce chemin. N'imprimez pas la valeur de la variable si elle contient des fragments de chemin sensibles.
Dans Conductor, recherchez exactement un espace de travail frère correspondant à ../cli/*/packages/cli-core/src/commands/. Si plusieurs correspondent, demandez lequel utiliser.
Si aucun checkout n'est disponible et l'accès réseau est acceptable pour la tâche, clonez le référentiel CLI public dans .context/clerk-cli-source :

mkdir -p .context
cd .context
git clone --depth 1 https://github.com/clerk/cli.git clerk-cli-source

Si aucun de ces éléments ne fonctionne, arrêtez et demandez à l'utilisateur un chemin source CLI. Ne faites pas d'audit contre le binaire clerk installé seul, car le binaire peut être obsolète et n'expose pas toutes les branches au niveau source.

Flux de travail

1. Inventorier la CLI

Parcourez packages/cli-core/src/commands/ et construisez un inventaire structuré. Pour chaque commande de niveau supérieur et sous-commande, capturez :

Chemin complet de la commande, tel que clerk config patch ou clerk api ls.
Objectif, à partir de la description de la commande ou de la chaîne d'aide en source.
Drapeaux, incluant la forme courte, le type, la valeur par défaut, et le comportement destructeur.
Codes de sortie au-delà de la valeur par défaut si la commande les modifie.
Branches de mode agent contrôlées par isAgentMode(), CLERK_MODE, détection TTY, ou aides connexes.
Si la commande modifie l'état distant et nécessite --dry-run, --yes, ou guidance ciblant la production.

Lisez packages/cli-core/src/commands/<name>/README.md comme contexte secondaire uniquement. Utilisez ces fichiers pour signaler les commandes simulées ou stub et pour recouper les affirmations de endpoint API dans references/recipes.md. Ne proposez pas de copier les READMEs de commande dans ce référentiel ; ils incluent des détails d'implémentation interne et gonflent la compétence.

Capturez aussi le comportement transversal :

Logique de préférence du runner, incluant mappage lockfile vers package-runner.
Auth, résolution de clé, ciblage --app et --instance.
Vérifications doctor et forme de sortie --json.
Comportement en mode agent pour les prompts, defaults JSON, ouverture de navigateur, callbacks OAuth, handoff de déploiement, et avertissements sandbox.
Comportement de handoff clerk init --prompt ou équivalent si la compétence le mentionne.

Préférez lire la source plutôt que d'exécuter le binaire. Quand le comportement runtime est peu clair, utilisez les tests sous packages/cli-core/src/**/*.test.ts ou packages/cli-core/src/test/ comme preuve complémentaire.

2. Extraire les affirmations de la compétence

Lisez skills/core/clerk-cli/SKILL.md et chaque fichier sous skills/core/clerk-cli/references/. Extrayez chaque affirmation concrète :

Commandes dans le tableau de commandes principal et guidance d'invocation.
Drapeaux nommés en prose, tableaux, et exemples.
Balles de comportement en mode agent.
Affirmations de code de sortie, format d'erreur, et sortie JSON.
Renvois croisés entre SKILL.md et references/*.md.

3. Diff source contre compétence

Produisez un diff structuré avec quatre catégories :

Manquant de la compétence : commandes, sous-commandes, drapeaux, ou comportements qui existent en source mais ne sont mentionnés nulle part dans la compétence.
Obsolète dans la compétence : affirmations dans la compétence qui ne correspondent plus à la source, incluant drapeaux renommés, defaults changés, commandes supprimées, codes de sortie décalés, ou branches de mode agent retravaillées.
Insuffisamment spécifié dans la compétence : commandes mentionnées mais sous-spécifiées par rapport à leur complexité réelle ou surface de risque.
Sur-spécifié : détails que la compétence encode que clerk <cmd> --help, exemples générés, ou fichiers référencés couvrent mieux.

Pour les catégories 1 à 3, citez à la fois le fichier source et la ligne et l'emplacement de la compétence cible.

4. Décider du placement

Acheminez les changements par valeur de maintenance :

Boucle principale, modèle mental, et sécurité restent dans SKILL.md.
Détails de drapeau par commande, recettes, et cas limites appartiennent à references/recipes.md ou un nouveau fichier de référence.
Branches en mode agent appartiennent à references/agent-mode.md ; SKILL.md obtient seulement un résumé concis.
Auth, résolution de clé, et ciblage appartiennent à references/auth.md.

Préférez clerk <command> --help plutôt que dupliquer l'aide générée. Les drapeaux avec sémantique destructrice, interactions cachées, ou divergence en mode agent méritent une couverture de compétence. Les drapeaux auto-explicatifs devraient généralement être supprimés de la prose et délégués à --help.

Traitez la réduction de compétence comme une proposition valide quand elle réduit le risque de divergence. L'objectif est une compétence précise et durable, pas une plus grande.

5. Proposer des modifications

Émettez une proposition prête pour relecture. Pour chaque changement incluez :

Chemin, tel que skills/core/clerk-cli/SKILL.md ou skills/core/clerk-cli/references/agent-mode.md.
Sévérité : drift, gap, ou polish.
Pourquoi, avec citation source telle que packages/cli-core/src/commands/<cmd>/<file>.ts:<line>.
Emplacement cible dans ce référentiel.
Un diff unifié quand pratique, sinon un bloc before et after concis.

Groupez la proposition par fichier cible. Ne réécrivez pas les sections voisines exactes juste parce qu'elles sont à proximité.

6. Appliquer ou renvoyer

Comportement par défaut : présentez la proposition et arrêtez pour relecture.

S'il est invoqué avec --apply, appliquez les modifications drift et gap directement, puis listez les suggestions polish pour relecture. Après avoir appliqué les modifications, exécutez les commandes de formatage ou validation disponibles pour ce référentiel. S'il n'existe pas de formateur, validez la structure Markdown et JSON avec des vérifications légères.

Garde-fous

Ne jamais inventer de drapeaux. Si un drapeau apparaît dans les tests mais pas dans le parser de commande, marquez-le pour relecture humaine.
Préservez la voix actuelle terse et à la troisième personne de la compétence clerk-cli.
N'utilisez pas de tirets cadratins dans les propositions ou modifications.
Gardez skills/core/clerk-cli/SKILL.md près de la guidance 500 lignes. Déplacez le matériel détaillé vers references/ plutôt que de gonfler la compétence principale.
Ne traitez pas le binaire clerk installé comme autorité sur la source. Utilisez --help seulement pour confirmer la présentation générée quand la source et les tests laissent l'ambiguïté.
Ne committez ni n'imprimez de secrets. Si l'audit touche à la guidance env, préservez les règles 1Password et pas-de-secret-en-clair du référentiel.

Forme de sortie

Retournez la proposition en :

# clerk-cli skill audit - <YYYY-MM-DD>

## Summary
<comptages par catégorie, plus la plus grande divergence>

## skills/core/clerk-cli/SKILL.md
### <section name>
- [drift|gap|polish] <description d'une ligne>
  - source: packages/cli-core/src/commands/<...>:<line>
  - target: skills/core/clerk-cli/SKILL.md:<line>
  - change: <diff ou before/after concis>

## skills/core/clerk-cli/references/<file>.md
...

## New files
...

## Open questions
...

Gardez le résultat lisible à la surface pour qu'un mainteneur puisse approuver, rejeter, ou appliquer chaque entrée indépendamment.

audit-clerk-skill