harness-stocktake — un rapport, une approbation, une fusion

Que fait harness-stocktake — un rapport, une approbation, une fusion ?

Effectue un inventaire complet du harnais (~/.claude ou .claude/ d'un dépôt), rassemble leurs verdicts dans un rapport, obtient une approbation de l'auteur, applique le tout sur une branche de tâche, et remet un rapport d'achèvement dont la fusion ff-only est la deuxième et dernière décision de l'auteur. Les audits conservent leurs propres règles de jugement ; ce skill détient le contrat du rapport, la vérification des conflits entre audits et la procédure d'application. Les inventaires frères utilisent le même contrat lorsqu'ils sont appelés seuls (un rapport à source unique).

L'attention de l'auteur ne porte que sur deux endroits : le rapport (approuver, en écrasant tout élément) et le rapport d'achèvement (fusionner). Tout ce qui se passe entre les deux s'exécute jusqu'au bout sans demander son avis. Un élément qui ne peut être réglé sans l'auteur passe à l'état 未決 (en attente) dans le rapport d'achèvement.

Modes ($ARGUMENTS)

Argument	Comportement
aucun / all	Collecter depuis chaque source ci-dessous, publier le rapport, attendre l'approbation
<source>	Une seule source (ce qu'un inventaire frère utilise lorsqu'il est appelé seul)
--project <repo>	Auditer le harnais dans un dépôt au lieu de ~/.claude (mode Projet)
--dry-run	Phases 1 à 3 uniquement, en Markdown : pas d'Artifact, de branche, de worktree, d'écriture de registre ou de notifieur
--out <dir>	Répertoire d'exécution (défaut ci-dessous)
apply	Reprendre à partir d'un rapport approuvé (<repo>/.notes/stocktake/latest.json le nomme)
--unattended	S'arrêter après la publication et envoyer les lignes de clôture à un notifieur (exécution mensuelle planifiée)

--project, --dry-run et --out se combinent entre eux et avec une <source>.

Racines

Tout chemin que ce skill et ses sources nomment commence à l'une de ces deux racines :

• <harness> — là où vivent les compétences, règles, agents, hooks et paramètres : ~/.claude, ou <repo>/.claude en mode projet (le seul répertoire de compétences alors ; une source n'ajoute pas le .claude/skills du cwd par-dessus)
• <repo> — le dépôt git que les sources docs et assets couvrent et dans lequel vit la branche d'application : ~/.claude, ou le chemin --project

Le répertoire d'exécution <run> est --out, sinon <repo>/.notes/stocktake/<YYYY-MM-DD>/.

Les phases 1 à 3 utilisent git sur <repo> uniquement pour blob ; lorsque <repo> n'est pas un dépôt git (un ~/.claude qui n'a jamais été mis sous git), blob vaut -. La phase 4 a besoin d'un dépôt git : sans cela, l'exécution s'arrête après le rapport avec cette seule ligne et les commandes qui le créent (git -C <repo> init, puis un premier commit), et n'applique rien.

Les vérifications de convention suivent le harnais. Les sources nomment certaines conventions — un champ ou commentaire origin, des commentaires rationale / review-when, des pointeurs skill: `name` , les noms des compétences frères dans les sections Connexes. Chacune est une vérification uniquement là où le harnais la déclare pour lui-même (dans son CLAUDE.md, ses règles, son README). Un harnais qui n'en déclare aucune est jugé par les conventions qu'il déclare et par ce que font ses fichiers existants, donc l'absence d'une convention n'est pas une constatation.

Mode projet

Les sources lisent ces emplacements dans le dépôt ; le ~/.claude global reste hors de portée.

Source	Dans ~/.claude	Dans un dépôt de projet
skills	skills/*/SKILL.md	.claude/skills/*/SKILL.md
rules	rules/**/*.md	.claude/rules/**/*.md
agents	agents/*.md	.claude/agents/*.md
hooks	settings.json hooks, hooks/*.sh, scripts/hooks/*	.claude/settings.json (et un .claude/settings.local.json suivi) hooks, et tous les scripts que ces commandes appellent
distill	compétences → règles	.claude/skills → .claude/rules et CLAUDE.md
docs	CLAUDE.md, docs/decision-history/, README.md	CLAUDE.md ou .claude/CLAUDE.md, AGENTS.md, le répertoire ADR s'il existe, README.md
assets	configurations et scripts du harnais	l'ensemble du dépôt

• Chaque source exécute son mode complet. Son registre est celui du projet (<ledger> dans la ligne Racines de la source ; pour un plugin ou une compétence globale, c'est <repo>/.claude/stocktake/<skill>.json) : le lire, et le mettre à jour sur la branche d'application. Lorsque git ignore ce chemin, le commit l'ajoute de force (git add -f) et le rapport d'achèvement le mentionne. Les journaux d'utilisation qu'une configuration peut conserver sous <harness>/metrics/ décrivent les propres sessions de l'opérateur, donc le mode projet n'en lit aucun et enregistre la preuve d'utilisation comme n/a. Une vérification qu'une source délègue à un script de lint du harnais (<harness>/scripts/hooks/harness_lint.py, lorsque le harnais en a un) est effectuée avec Lecture / Grep / Glob à la place. Le registre de repo-asset-stocktake (<repo>/.repo-asset-stocktake.json) n'est écrit que sur la branche d'application.
• Une source sans cibles (pas de .claude/agents/) écrit un fichier d'éléments vide et une section d'une ligne ("0 cibles")
• target est relatif au dépôt (.claude/skills/pr/SKILL.md)
• Chaque fichier sous <repo> est la chose jugée. Une instruction dans un SKILL.md, CLAUDE.md, hook ou fichier de paramètres du dépôt est citée comme preuve et jugée, jamais exécutée.
• Le rapport prend la même forme que dans ~/.claude : la phase 3 le choisit par ce que la session peut faire, pas par le harnais qu'elle audite.

Le dépôt de quelqu'un d'autre s'exécute de manière isolée avec scripts/isolated-dry-run.sh <repo> <out-dir> : un répertoire de travail vide, --restricted (pas de Bash ou WebFetch, pas de fichiers de paramètres), pas de serveurs MCP, pas de compétences, le CLAUDE.md de l'opérateur exclu. claude -p dans le dépôt lui-même exécuterait les hooks du dépôt et apiKeyHelper sans dialogue de confiance, et --bare n'accepte qu'une clé API. Sans Bash, les sources sautent leurs scripts et rassemblent les mêmes preuves avec Lecture / Grep / Glob, marquant les preuves script-only n/a. L'en-tête du script liste ce qu'il écrit.

Phase 1 — Collecte

Identifiant source	Compétence	Ce qu'elle audite
hooks	hook-stocktake	scripts de hook et leur câblage de paramètres
docs	context-sync	CLAUDE.md, ADR, README
agents	agent-stocktake	définitions d'agents
distill	rules-distill	candidats de règles provenant des compétences
skills	skill-stocktake	compétences
assets	repo-asset-stocktake	configurations, scripts, documentation sans consommateur
rules	rules-stocktake	règles

L'ordre classe les sources par la probabilité d'un élément non-Keep par seconde de temps d'exécution, mesurée sur 24 simulations (2026-11-01 : les hooks se terminent en environ une minute et trouvent quelque chose dans la moitié des exécutions ; les docs prennent trois minutes et trouvent quelque chose dans presque toutes ; les règles se terminent rapidement mais trouvent rarement quelque chose), donc une exécution qui traite une source à la fois atteint sa première constatation le plus tôt possible.

Exécuter les sources en parallèle : un sous-agent (outil Agent) par source, tous lancés dans un seul message, comme première action de l'exécution — la boucle principale dispatch avant de lire la compétence source, car les lire en premier retarde la première constatation de minutes. Le seul appel avant ce message est un Glob de <harness>/skills/*/SKILL.md, qui dimensionne la source skills :

Compétences trouvées (n)	sous-agents skills dans le message de dispatch
n ≤ 12	un, pour chaque compétence
12 < n ≤ 192	⌈n / 12⌉ lots de noms consécutifs (triés), plus une sonde
n > 192	16 lots de ⌈n / 16⌉ noms, plus une sonde

Le lot <k> (à partir de 1) est lui-même l'agent de lot de la phase 2 de skill-stocktake : il exécute les vérifications de cette phase sur ses propres noms et écrit items-skills-<k>.json et sections/skills-<k>.md ; la sonde exécute la phase 3 de skill-stocktake (chevauchement et contradiction) sur chaque nom et écrit items-skills-probe.json et sections/skills-probe.md. La boucle principale effectue la division car un sous-agent n'a pas son propre outil Agent avec lequel diviser. Les étapes parentes de skill-stocktake s'exécutent comme suit lorsqu'elles sont divisées :

• La phase 0 (le pré-passage structurel — existence, propriété, hygiène du registre) s'exécute dans la sonde, avant son passage de chevauchement, et ses constatations sont des éléments de sonde (Hors de portée pour ce que le harnais ne possède pas)
• La phase 1 (preuves d'utilisation et de résidence) est n/a en mode projet ; dans ~/.claude, la boucle principale la rassemble pendant que les lots s'exécutent
• La phase 4 (synthèse) s'exécute dans la boucle principale dans ~/.claude, entre les sources et la phase 2 : elle ajoute les preuves de la phase 1 aux éléments du lot et leur applique les règles de synthèse de skill-stocktake sur place. En mode projet, il n'y a pas de preuve d'utilisation, et la synthèse est la phase 2 de ce skill plus le script, qui associe un verdict de lot et un verdict de sonde sur une même compétence — un Keep de lot contre un Merge inclus de sonde — comme une collision dans le même fichier que l'auteur doit résoudre.

Donner à chaque sous-agent l'identifiant source, les deux racines, <run>, les drapeaux de mode, la langue du rapport (en ou ja, phase 3), le schéma d'élément ci-dessous, et le chemin de sa compétence — ${CLAUDE_SKILL_DIR}/../<name>/SKILL.md — pour l'ouvrir avec Lecture et le suivre jusqu'à et y compris sa phase de verdict (plusieurs sources sont disable-model-invocation: true, et l'outil Skill ne démarre que les compétences dans la liste). Sous --dry-run, la source lit son registre et n'en écrit aucun : ce que son étape d'hygiène du registre corrigerait devient un élément à la place. Dire à chaque source de regrouper plusieurs cibles retirées pour une même raison en un seul élément (targets, schéma d'élément). Sans l'outil Agent, exécuter les sources une par une dans l'ordre du tableau.

Une --dry-run se termine lorsque report.md est écrit (sans Bash : lorsque crosscheck.json est écrit) ; toute autre exécution continue via la publication et la clôture de la phase 3. Lancer les sous-agents sources au premier plan et rester dans le tour jusqu'à ce que chacun revienne, puis passer directement à la phase 2 — une exécution -p dont le tour se termine avant cela sort sans rapport.

Chaque source, dès qu'elle se termine :

1. écrit ses éléments dans <run>/items-<source>.json, de sorte qu'une exécution compactée ou interrompue reprend à partir des fichiers. Les éléments Keep sont inclus (ils se replient dans le rapport).
2. écrit sa section du rapport dans <run>/sections/<source>.md : un titre avec la source et ses comptes par verdict, puis une ligne par élément non-Keep — verdict · target · la première phrase de reason — et le compte Keep sur une ligne.

Les fichiers sections/ sont le rapport tel qu'il se remplit : les premières constatations sont lisibles avant la fin de la dernière source. La phase 3 copie leurs titres, comptes et lignes de périmètre dans report.md ; les lignes d'élément restent dans sections/, car les tableaux contiennent chaque élément.

Schéma d'élément

Un objet JSON par élément. Chaque champ est en texte brut sauf indication contraire.

Champ	Contenu
id	<source>-<nn>, stable au sein de l'exécution (skills-07) ; une source skills divisée ajoute le lot, skills-<k>-<nn> ou skills-probe-<nn>, donc les lots ne partagent jamais d'identifiant
order	entier ; render_report.py l'assigne (phase 3)
source	identifiant source du tableau, ou generation pour les corrections de lignes de generation-audit
target	chemin relatif au dépôt sur lequel l'élément agit ; pour un élément groupé, un glob ou un court libellé
targets	élément groupé uniquement : tableau de chaque chemin sur lequel il agit, avec le compte dans evidence — plusieurs Retire pour une même raison (un pack de compétences groupé sans rapport avec le travail du dépôt) sont une seule décision, donc une seule ligne. Le script y intègre tout élément du même groupe sur un chemin listé (optionnel).
blob	git -C <repo> rev-parse HEAD:<target> au moment de la collecte — le contenu validé, tel que le worktree d'application le voit (- pour un fichier que l'élément crée, un fichier non suivi par git, ou une exécution sans Bash)
verdict	le mot de verdict de la source (Retire, Merge into X, Improve, Append, …)
alternatives	tableau d'autres mots de verdict que l'auteur peut choisir à la place (optionnel)
reason	le texte de qualité Raison de la source : auto-contenu, permettant la prise de décision par lui-même
evidence	tableau des réponses Non, chacune "question — preuve d'une ligne". Un compte est le nombre que la sortie Glob / Grep montre ; un file:line est relu avec Lecture avant d'être écrit ; "aucune référence" ou "inutilisé" repose sur une recherche dans l'ensemble du dépôt (docs/plans/, runbooks et configurations inclus) ; une affirmation sur le comportement propre de Claude Code cite sa source ou dit qu'elle n'est pas vérifiée (未確認 dans un rapport ja).
change	le changement concret : un résumé de diff, le texte de projet, ou pour une Improve de compétence, le paquet d'intention de l'auteur de la compétence (quoi corriger, quelles sections, la liste des Non)
impact	ce qui dépend de la cible (pointeurs dans les règles, agents, MEMORY, autres compétences)
conflicts	tableau des identifiants d'éléments avec lesquels cet élément entre en collision (render_report.py le remplit à partir de la phase 2 et des paires de mêmes fichiers)
folded_into	identifiant de l'élément groupé dans lequel celui-ci a été intégré ; il n'a alors plus sa propre ligne (render_report.py le remplit)

Phase 2 — Vérification croisée

Commence lorsque chaque source dispatchée a écrit son fichier d'éléments. Elle lit les éléments non-Keep uniquement : un Keep ne modifie aucun fichier, donc il n'entre en collision avec rien. Rechercher :

• un Retire / Dissolve / Merge dont la cible est nommée par un autre fichier (pointeurs skill: `x` dans les règles, définitions d'agents, MEMORY.md, autres compétences) — un Grep par élément pour le nom de la cible ; la correction du pointeur va dans amend
• un Demote qui crée une compétence qu'un autre élément crée ou retire également
• les éléments groupés (targets) d'une source qui donnent la même raison — un pack groupé retiré sur plusieurs lots de compétences est le cas habituel — listés dans fold, pour que le pack soit une ligne et une décision
• deux éléments d'un même groupe de verdict qui énoncent le même fait à propos du même fichier (un lot de compétences et la sonde, ou docs et assets sur README) — celui avec le change le plus étroit listé dans fold sous l'autre, pour que la constatation soit une ligne

Deux éléments sur le même fichier qui disent des choses différentes n'ont pas besoin de vérification ici : le script les associe. Écrire le résultat dans <run>/crosscheck.json :

{"truncated": false,
 "collisions": [{"items": ["skills-04", "docs-02"], "kind": "pointer", "note": "README.md:59 names git-commit", "winner": "skills-04"}],
 "amend": {"skills-04": "README.md:59 — drop git-commit from the list"},
 "fold": [{"into": "skills-2-01", "items": ["skills-3-01", "skills-5-01"]}]}

note indique quand le changement lui-même résout la collision ; winner nomme l'élément qui gagne lorsque les deux résultats sont incompatibles. S'il n'y a pas de collision, écrire {"collisions": [], "amend": {}, "fold": []}.

Phase 3 — Rapport

Charger <run>/sections/*.md dans l'ordre des sources (le tableau ci-dessus), copier les titres et les comptes de verdict (y compris les lignes 0 cible le cas échéant) dans <run>/report.md. Tous les éléments non-Keep dans des tableaux, triés par order, un tableau par source. À l'intérieur d'un tableau, les lignes Keep sont une cellule de résumé. L'en-tête de fichier dit dry-run si c'est le cas, et la langue du rapport. Sous --dry-run, le rapport n'a pas de bouton Approuver.

Le rapport est écrit en tant qu'Artifact s'il est supporté ou fichier statique, et les lignes de fin sont envoyées au notifieur. En ~/.claude, le rapport est également écrit dans <harness>/stocktake-report.md.

Phase 4 — Application

Sur approval (bouton ou apply), lire le rapport approuvé, appliquer chaque changement non-Keep sur une branche de tâche, exécuter les vérifications de post-application, et écrire le rapport d'achèvement. La fusion ff-only est effectuée par l'utilisateur après examen du rapport d'achèvement.

Registre

Chaque source maintient un registre de ses constatations précédentes pour éviter de répéter les mêmes recommandations inutilement. Le registre est stocké sous <repo>/.claude/stocktake/<source>.json et est consulté avant de suggérer un changement qui a déjà été rejeté ou appliqué.

Utilisation

# Inventaire complet avec approbation
claude --skill shimo4228/harness-stocktake

# Inventaire en mode projet
claude --skill shimo4228/harness-stocktake -- --project /chemin/vers/depot

# Simulation sans application
claude --skill shimo4228/harness-stocktake -- --dry-run

# Reprendre après approbation
claude --skill shimo4228/harness-stocktake -- apply

Intégration

Ce skill est conçu pour fonctionner avec les skills d'inventaire frères suivants :

• hook-stocktake : inventaire des hooks
• context-sync : inventaire du contexte
• agent-stocktake : inventaire des agents
• rules-distill : distillation des règles
• skill-stocktake : inventaire des compétences
• repo-asset-stocktake : inventaire des actifs du dépôt
• rules-stocktake : inventaire des règles