@mcptoolshop/housekeeping 1.3.1 → 1.4.0

package/README.it.md

@@ -10,7 +10,8 @@
 
 <p align="center">
   An operational-health warehouse for a GitHub organization.<br>
-  One sweep, one SQLite database, findings you can argue with.
+  One sweep, one SQLite database, findings you can argue with,<br>
+  and the whole-organization view an AI agent needs to coordinate every repository.
 </p>
 
 <p align="center">
@@ -20,39 +21,100 @@
   <a href="https://mcp-tool-shop-org.github.io/housekeeping/handbook/"><img src="https://img.shields.io/badge/Handbook-read-blue" alt="Handbook" /></a>
 </p>
 
-Un singolo ciclo di scansione raccoglie lo stato CI di ogni repository, le issue aperte e le richieste di pull, le release, i tag di versione, i file di workflow, le protezioni dei branch, gli avvisi di sicurezza, i file di blocco e i dati di fatturazione di Actions in SQLite, quindi esegue un controllo completo rispetto alle regole definite.
+Un'unica scansione raccoglie lo stato del CI di ogni repository, le issue aperte e le richieste di pull, le release, i tag di versione, i file di workflow, la protezione dei branch, gli avvisi di sicurezza, i file di blocco e i dati di fatturazione di Actions in SQLite, quindi esegue un controllo completo rispetto alle regole definite.
 
 Fornisce risposte, per l'intera organizzazione contemporaneamente:
 
-- Quali sono i branch predefiniti contrassegnati come problematici e si tratta di una branch principale interrotta o di una cronologia obsoleta?
-- Quali richieste di pull non possono essere unite, perché un controllo richiesto che non produce alcun risultato le sta bloccando?
-- Quali distribuzioni vengono rifiutate dalle impostazioni del repository stesso?
-- Dove sono divergenti `package.json`, i tag Git e il registro npm?
+- Quali branch predefiniti sono contrassegnati come problematici e si tratta di una branch principale interrotta o di una cronologia obsoleta?
+- Quali richieste di pull non possono mai essere unite, perché un controllo richiesto che non produce alcun risultato le sta bloccando?
+- Quali distribuzioni vengono rifiutate dalle impostazioni del repository?
+- Dove `package.json`, i tag Git e il registro npm si sono discostati?
 - Quali workflow violano le regole sui costi di Actions, quanto sono costati e quali job hanno consumato tali costi?
 - Quali repository contengono avvisi che il sistema di avvisi di GitHub non rileva?
 
 È uno strumento di audit, non uno strumento di correzione. Legge i dati di GitHub e non apporta alcuna modifica.
 
-## Perché è strutturato in questo modo:
+## Un agente per ogni repository
 
-| Livello | Scelta | Motivazione |
+Un'organizzazione con dozzine di repository non dispone di un unico punto in cui sono memorizzati i suoi dati. housekeeping è questo punto, e il suo server MCP, `hk-mcp`, li fornisce a un agente AI. Grazie a questo, un singolo agente può fungere da coordinatore per l'intera organizzazione:
+
+1. **Scansione.** `hk refresh` esegue una singola scansione di ogni repository.
+2. **Smistamento.** L'agente chiede quali elementi sono contrassegnati come problematici, quali sono bloccati e quali sono peggiorati, e riceve risposte che già distinguono una branch principale interrotta da una cronologia obsoleta e una richiesta di pull bloccata da una in conflitto.
+3. **Pianificazione di un'azione.** Una singola query `hk_sql` individua tutti i repository con la stessa struttura, in modo che la correzione diventi una singola richiesta di pull per repository anziché una ricerca.
+4. **Esecuzione del lavoro.** housekeeping non scrive mai. L'agente apre le richieste di pull con i propri strumenti, con le proprie autorizzazioni e previa approvazione.
+5. **Verifica.** Esegue una nuova scansione. L'errore è stato risolto o meno, e la differenza tra due scansioni è una query.
+
+Domande a cui un agente risponde in una o due chiamate:
+
+- Quali branch predefiniti sono contrassegnati come problematici e quale job e quale passaggio hanno causato il problema?
+- Quali richieste di pull non possono mai essere unite e il problema è dovuto al trigger o a un conflitto?
+- Quali repository contengono un avviso di produzione per il quale GitHub non mostra alcun avviso?
+- Quali workflow pianificati violano le regole per le pianificazioni e in che modo?
+- Quanto sono costati Actions e quale job ha consumato tali costi?
+- Cosa è cambiato dall'ultima scansione?
+
+| Strumento | A cosa risponde |
+|---|---|
+| `hk_summary` | Totali per la scansione più recente: repository, issue, richieste di pull, workflow, risultati. |
+| `hk_findings` | Risultati per codice, gravità, categoria o repository; conteggi per codice quando non filtrati. Il risultato di una branch principale contrassegnata come problematica indica il job e il passaggio che hanno causato il problema. |
+| `hk_ci` | Repository la cui branch predefinita è contrassegnata come problematica e i workflow che hanno fallito; anche le pianificazioni non riuscite, le branch delle richieste di pull non riuscite e i repository senza CI. |
+| `hk_repo` | Un singolo repository nel dettaglio: risultati, workflow, richieste di pull e issue aperte. |
+| `hk_backlog` | Richieste di pull o issue aperte in tutta l'organizzazione, ordinate dalla più vecchia alla più recente. |
+| `hk_health` | Un punteggio di salute per repository, ordinato dal peggiore al migliore. |
+| `hk_cost` | Spese di Actions per repository, workflow o job, separate in costi lordi e netti. |
+| `hk_sql` | Una singola istruzione `SELECT` o `WITH` in sola lettura rispetto al data warehouse. |
+| `hk_schema` | Le tabelle e le colonne, per scrivere query `hk_sql`. |
+
+Ogni risposta proviene dalla scansione più recente, aperta in sola lettura. Una chiamata non riuscita restituisce un errore strutturato, mai una traccia dello stack.
+
+### Come connetterlo
+
+```json
+{
+  "mcpServers": {
+    "housekeeping": { "command": "hk-mcp", "env": { "HK_HOME": "/path/to/warehouse" } },
+    "atlas": { "command": "atlas", "args": ["mcp"] }
+  }
+}
+```
+
+`HK_HOME` è la directory da cui si esegue la scansione. Da una copia clonata, utilizzare `"command": "node", "args": ["/path/to/housekeeping/src/mcp.mjs"]`. Il secondo server è [Atlas](https://github.com/dogfood-lab/testing-os/tree/main/packages/atlas), che risponde allo stesso agente su un singolo repository alla volta (vedere di seguito). Su Windows, avviare un comando installato a livello globale tramite `cmd /c`.
+
+## housekeeping e Atlas
+
+[Atlas](https://github.com/dogfood-lab/testing-os/tree/main/packages/atlas) (`@dogfood-lab/atlas`) mappa un singolo repository: le sue parti e le sue "porte", ovvero ogni workflow con ciò che esegue, pubblica e distribuisce. La mappa viene salvata come `atlas/` e verificata nel CI. housekeeping è la vista dell'organizzazione. I due strumenti sono progettati per funzionare insieme.
+
+- **Ogni mappa, sottoposta a scansione.** Una scansione legge la mappa salvata di ciascun repository insieme a tutti gli altri dati e segnala quali repository non ne hanno, quali non eseguono mai `atlas check` e quali contengono un motore diverso da quello utilizzato dal resto dell'organizzazione.
+- **Dove un'esecuzione contrassegnata come problematica ha causato un errore.** Quando una branch predefinita è contrassegnata come problematica, il risultato indica il job e il passaggio che hanno causato l'errore e, tramite la mappa, il comando che quel passaggio esegue, in modo che la correzione inizi nel file corretto.
+- **Informazioni sulla distribuzione dalla mappa.** L'ambiente in cui un job distribuisce è tratto dalla mappa in cui è registrato, in modo che entrambi gli strumenti leggano un workflow nello stesso modo.
+- **Avvisi in tutta l'organizzazione.** Atlas segnala un passaggio del workflow che causerà un errore prima che venga eseguito, ad esempio uno strumento che richiede una versione di runtime più recente di quella installata dal job. Il report elenca questi elementi per tutti i repository contemporaneamente.
+
+Un agente che utilizza entrambi i server passa da "questi dodici repository sono bloccati" (housekeeping) a "questo è il workflow, il job e i file che una modifica raggiungerà" (Atlas), senza dover aprire ogni repository manualmente.
+
+## Perché ha questa struttura
+
+| Livello | Scelta | Motivo |
 |---|---|---|
-| Trasporto | L'interfaccia a riga di comando `gh` | Contiene già il token. Lo strumento non memorizza né richiede credenziali. |
-| Raccolta | GitHub GraphQL, con paginazione | Una singola query restituisce metadati, issue aperte, richieste di pull aperte, release e alberi di file per una pagina di repository. Una pagina che continua a superare il tempo limite viene dimezzata e la richiesta viene ripetuta dallo stesso cursore. |
+| Trasporto | L'interfaccia a riga di comando `gh` | Già contiene il token. Lo strumento non memorizza né richiede mai una credenziale. |
+| Raccolta | GitHub GraphQL, a pagine | Una singola query restituisce metadati, issue aperte, richieste di pull aperte, release e alberi di file per una pagina di repository. Una pagina che continua a superare il timeout viene dimezzata e richiesta nuovamente dallo stesso cursore. |
 | Esecuzioni di Actions | REST | GraphQL non dispone di un'interfaccia per Actions. |
-| Costi di Actions | API di fatturazione più durate per singolo job | La fattura indica il repository; solo i job indicano il workflow. Gli endpoint `/timing` di GitHub restituiscono zeri, quindi la somma per singolo job viene ricostruita e quindi riconciliata con la fattura. |
-| Tariffe dei runner | lettura dalla fattura | Una tariffa fatturata può differire dal prezzo di listino e una costante nel codice sorgente falsificherebbe tutti i numeri. |
-| Archiviazione | SQLite tramite l'implementazione `node:sqlite` integrata | Nessun passaggio di compilazione nativo. |
-| Fonte di verità | `data/snapshots/*.json` | Dati grezzi, modificabili e con aggiunte successive. Il database viene derivato: `npm run rebuild` lo ricostruisce offline. |
-| Log della scansione | `data/sweeps.jsonl` | Una riga per ogni scansione, comprese le scansioni che hanno avuto esito negativo e le scansioni che non hanno trovato nuovi dati. |
+| Le azioni comportano un costo. | API di fatturazione più durata per ogni attività. | Nella fattura è indicato il repository; solo nelle attività è indicato il workflow. Gli endpoint `/timing` di GitHub restituiscono zeri, quindi il totale per ogni attività viene ricostruito e quindi riconciliato con la fattura. |
+| Tariffe per i runner. | Letto dalla fattura. | Una tariffa fatturata può differire dal prezzo di listino e una costante nel codice sorgente falsificherebbe ogni numero. |
+| Archiviazione. | SQLite tramite il `node:sqlite` integrato. | Nessuna fase di compilazione nativa. |
+| Fonte di verità. | `data/snapshots/*.json` | Dati grezzi, modificabili e con possibilità di aggiungere solo dati. Il database viene derivato: `npm run rebuild` lo ricostruisce offline. |
+| Registro delle scansioni. | `data/sweeps.jsonl` | Una riga per ogni scansione, comprese le scansioni non riuscite e le scansioni che non hanno trovato nulla di nuovo. |
 
 Gli snapshot sono immutabili e additivi, quindi la differenza tra due date è un `JOIN`.
 
 ## Requisiti
 
 - Node.js 22.5 o successivo.
-- L'interfaccia a riga di comando di [GitHub](https://cli.github.com/), con accesso (`gh auth status`) come account in grado di leggere l'organizzazione. La lettura dei dati di fatturazione e degli avvisi di sicurezza richiede i permessi corrispondenti; una scansione senza tali permessi registra "non misurato" e continua. Non registra mai un permesso mancante come risultato valido.
-- Windows o Linux. È sviluppato su Windows e i test vengono eseguiti su Linux in CI. macOS dovrebbe funzionare e non è testato.
+- [GitHub CLI](https://cli.github.com/), con accesso effettuato (`gh auth status`) con un
+account che può leggere l'organizzazione. Per leggere le fatture e gli avvisi di sicurezza
+sono necessari i permessi corrispondenti; in caso contrario, la scansione registra "non misurato" e
+prosegue. Non registra mai un permesso mancante come risultato valido.
+- Windows o Linux. È sviluppato su Windows e i suoi test vengono eseguiti su Linux in
+CI. macOS dovrebbe funzionare e non è testato.
 
 ## Utilizzo
 
@@ -62,9 +124,10 @@ mkdir warehouse && cd warehouse            # housekeeping keeps its data here
 hk refresh your-org                        # collect, load, analyze, write reports/AUDIT-<date>.md
 ```
 
-Per conservare le impostazioni tra le diverse esecuzioni, inserire un file `housekeeping.config.json` in quella directory (vedere Configurazione); quindi `hk refresh` non richiede alcun argomento.
+Per mantenere le impostazioni tra le scansioni, inserire un `housekeeping.config.json` in quella
+directory (vedere Configurazione); quindi `hk refresh` non richiede alcun argomento.
 
-Oppure eseguirlo da una copia, che conserva i suoi dati nella copia:
+Oppure eseguirlo da una copia, che mantiene i suoi dati nella copia:
 
 ```bash
 git clone https://github.com/mcp-tool-shop-org/housekeeping.git
@@ -75,7 +138,7 @@ cp housekeeping.config.example.json housekeeping.config.json   # then set "org"
 hk refresh
 ```
 
-Quindi, esegui una query:
+Quindi, eseguite una query:
 
 ```bash
 hk summary               # portfolio totals
@@ -91,13 +154,15 @@ hk sql "SELECT ..."      # one read-only statement
 hk help                  # every command and flag
 ```
 
-In una copia senza il file `npm link`, ogni esecuzione di `hk <command>` è `node src/cli.mjs <command>`.
+In una copia senza `npm link`, ogni `hk <command>` è `node src/cli.mjs <command>`.
 
-`npm run rebuild` ricostruisce il database e il report dagli snapshot già presenti sul disco, senza accesso alla rete.
+`npm run rebuild` deriva nuovamente il database e il report dagli snapshot già
+presenti sul disco, senza accesso alla rete.
 
 Una scansione completa effettua alcune centinaia di chiamate API. Non eseguire `refresh` in un ciclo.
 
-I risultati vengono inviati all'output standard; i progressi e gli errori vengono inviati all'output di errore standard. Ogni errore stampa un codice e un suggerimento. Codici di uscita: 0 (tutto ok), 1 (errore utente), 2 (errore di runtime), 3 (parziale, la scansione è terminata, ma con delle lacune).
+I risultati vengono inviati all'output standard; i progressi e gli errori vengono inviati all'output degli errori standard. Ogni
+errore stampa un codice e un suggerimento. Codici di uscita: 0 ok, 1 errore utente, 2 errore di runtime, 3 parziale (la scansione è terminata, con delle lacune).
 
 ## Configurazione
 
@@ -110,60 +175,56 @@ I risultati vengono inviati all'output standard; i progressi e gli errori vengon
 }
 ```
 
-- `org` è l'organizzazione da sottoporre a scansione. `hk refresh <org>` lo sovrascrive. In assenza di entrambi, la scansione non viene avviata.
-- `metaRepos` sono i repository che contengono le impostazioni predefinite dell'organizzazione, le risorse o gli strumenti, e non un prodotto distribuito. Sono esenti dai risultati che hanno senso solo per un prodotto: mancanza di file README, LICENSE e simili, assenza di workflow e assenza di release.
+- `org` è l'organizzazione da scansionare. `hk refresh <org>` lo sovrascrive. In caso contrario, una scansione si rifiuta di avviarsi.
+- `metaRepos` sono i repository che contengono le impostazioni predefinite dell'organizzazione, le risorse o
+gli strumenti, non un prodotto distribuito. Sono esenti dai risultati che hanno senso solo per un prodotto: mancanza di README, LICENSE e file simili, assenza di workflow e assenza di release.
 
 Un file non valido è un errore, mai un valore predefinito silenzioso: una chiave sconosciuta, un tipo errato o un JSON non valido interrompono l'esecuzione.
 
-Esegui da una copia clonata, housekeeping mantiene `data/`, `reports/` e il file di configurazione nella copia clonata. Esegui come pacchetto installato, li mantiene nella directory da cui lo esegui o in `HK_HOME` quando è impostato.
-
-Ambiente: `HK_HOME` (dove risiedono i dati, i report e la configurazione), `HK_CONFIG` (percorso della configurazione), `HK_DB` (percorso del database), `HK_LOG` (`silent`, `normal`, `verbose` o `debug`), `HK_COST_REPOS` e `HK_COST_BUDGET` (limiti per il costo per singolo job), `GH_PATH` (percorso di `gh`).
-
-## Mantieni i dati privati
-
-**I dati scritti da una scansione sono sensibili. Non inserire `data/` o `reports/` in un repository pubblico.**
-
-Uno snapshot registra i nomi e le descrizioni dei repository privati, ogni avviso di sicurezza aperto con il pacchetto a cui si riferisce, i file di workflow e i dati di fatturazione di Actions. GitHub nasconde deliberatamente gli avvisi di sicurezza di un repository pubblico a tutti tranne che ai suoi manutentori; uno snapshot pubblicato fornirebbe tale elenco.
+Eseguito da una copia, housekeeping mantiene `data/`, `reports/` e il file di configurazione
+nella copia. Eseguito come pacchetto installato, li mantiene nella directory da cui
+lo si esegue o in `HK_HOME` quando è impostato.
 
-Il `.gitignore` di questo repository esclude `data/`, `reports/` e `housekeeping.config.json`. Per mantenere la cronologia, che è lo scopo degli snapshot, esegui lo strumento da un repository **privato** di tua proprietà e inserisci gli snapshot lì.
+Ambiente: `HK_HOME` (dove risiedono i dati, i report e la configurazione),
+`HK_CONFIG` (percorso della configurazione), `HK_DB` (percorso del database), `HK_LOG`
+(`silent`, `normal`, `verbose` o `debug`), `HK_COST_REPOS` e
+`HK_COST_BUDGET` (limiti per il costo per ogni attività), `GH_PATH` (percorso di `gh`).
 
-## Server MCP
+## Mantenere i dati privati
 
-Il file `hk-mcp` (o `npm run mcp` in una copia) gestisce l’accesso al database tramite stdio, quindi un assistente può porre domande senza dover leggere un file di diversi megabyte:
-
-`hk_summary` · `hk_findings` · `hk_ci` · `hk_repo` · `hk_backlog` · `hk_health` · `hk_cost` · `hk_sql` · `hk_schema`
-
-```json
-{
-  "mcpServers": {
-    "housekeeping": { "command": "hk-mcp", "env": { "HK_HOME": "/path/to/warehouse" } }
-  }
-}
-```
+**Ciò che una scansione scrive è sensibile. Non inserire `data/` o `reports/` in un
+repository pubblico.**
 
-`HK_HOME` è la directory da cui si avvia l’esecuzione. In caso di copia, utilizzare invece `"command": "node", "args": ["/path/to/housekeeping/src/mcp.mjs"]`.
+Uno snapshot registra i nomi e le descrizioni dei repository privati, ogni
+avviso di sicurezza aperto con il pacchetto a cui si riferisce, i file di workflow e la fatturazione di Actions. GitHub nasconde deliberatamente gli avvisi di sicurezza di un repository pubblico a tutti tranne che ai suoi manutentori; uno snapshot pubblicato fornirebbe tale elenco.
 
-`hk_sql` accetta una singola istruzione `SELECT` o `WITH` e apre il database in sola lettura. Una chiamata non riuscita restituisce un errore strutturato, mai una traccia dello stack.
+Il `.gitignore` di questo repository esclude `data/`, `reports/` e
+`housekeeping.config.json`. Per mantenere la cronologia, che è lo scopo degli snapshot,
+eseguire lo strumento da un **repository privato** di proprietà e inserirli lì.
 
 ## Risultati
 
-Le regole sono contenute in `src/analyze.mjs`. Ognuna di esse fa riferimento alla regola scritta che applica, in modo che un risultato possa essere contestato rispetto a uno standard e non al gusto personale. Le regole fornite con questo repository sono in [`rules/`](rules/):
+Le regole sono contenute in `src/analyze.mjs`. Ognuna di esse cita la regola scritta che applica,
+quindi un risultato può essere contestato rispetto a uno standard e non al gusto personale. Le regole
+che questo repository distribuisce sono in [`rules/`](rules/):
 
-- [`rules/github-actions.md`](rules/github-actions.md): filtri per i percorsi, runner, dimensione della matrice, limite del file di flusso di lavoro, concorrenza.
-- [`rules/shipcheck-product-standards.md`](rules/shipcheck-product-standards.md): la CI deve essere superata, i controlli di rilascio, le versioni.
-- [`rules/repo-first.md`](rules/repo-first.md): il ramo predefinito.
-- [`rules/atlas-map.md`](rules/atlas-map.md): una mappa registrata di ciascun repository, verificata nella CI.
+- [`rules/github-actions.md`](rules/github-actions.md): filtri dei percorsi, runner, dimensione della matrice, limite del file di workflow, concorrenza.
+- [`rules/shipcheck-product-standards.md`](rules/shipcheck-product-standards.md): il CI deve essere superato, i gate di rilascio, le versioni.
+- [`rules/repo-first.md`](rules/repo-first.md): la branch predefinita.
+- [`rules/atlas-map.md`](rules/atlas-map.md): una mappa impegnata di ogni repository, controllata nel CI.
 
-Questi sono gli standard di un'organizzazione. Se i tuoi sono diversi, modifica il file delle regole e la regola stessa.
+Sono gli standard di un'organizzazione. Se i vostri sono diversi, modificate il file della regola
+e la regola insieme.
 
-Le regole si assicurano di mantenere separate le cose che sembrano simili, perché combinarle genera confusione:
+Le regole si prendono cura di separare le cose che sembrano simili, perché combinarle produce rumore:
 
-- **Un ramo predefinito "rosso" non è un ramo di richiesta di pull "rosso".** Un ramo di Dependabot che fallisce rappresenta un elemento in sospeso; un'esecuzione di `push` che fallisce sul ramo predefinito rappresenta un problema. L'evento dell'esecuzione determina quale sia.
-- **La cronologia non è un problema.** Un flusso di lavoro spostato in un trigger solo per i rilasci mantiene il suo ultimo errore sul ramo predefinito per sempre. Un flusso di lavoro eliminato mantiene le sue esecuzioni. Nessuno dei due è un difetto attivo.
-- **Un controllo obbligatorio che non può emettere nulla non è un controllo che non è stato eseguito qui.** Uno indica di eliminare il requisito; l'altro indica di correggere il trigger. Le correzioni si contraddicono a vicenda.
-- **Un'esecuzione fallita non è un'esecuzione annullata.** `cancel-in-progress` esiste per terminare le esecuzioni obsolete, quindi i minuti annullati sono solitamente la regola di concorrenza in funzione.
-- **Il costo lordo non è il costo netto.** GitHub calcola i costi dei repository pubblici al prezzo pieno e li riduce a zero. Il costo lordo è la potenza di calcolo reale; il costo netto è il denaro reale. Non vengono mai sommati.
-- **Se non viene misurato, non è corretto.** Un repository GitHub che non esegue la scansione segnala zero avvisi. Un repository per il quale il controllo dei costi non è stato raggiunto non ha una riga di costo. Entrambi vengono segnalati come sconosciuti.
+- **Un ramo predefinito rosso non è un ramo di richiesta di pull rosso.** Un ramo di Dependabot che non funziona rappresenta un elemento in sospeso; un'esecuzione `push` non riuscita sul ramo predefinito rappresenta un problema. L'evento dell'esecuzione determina quale sia il caso.
+- **La cronologia non è un problema.** Un flusso di lavoro spostato in una modalità di esecuzione solo per le release mantiene il suo ultimo errore sul ramo predefinito per sempre. Un flusso di lavoro eliminato mantiene le sue esecuzioni. Nessuno dei due rappresenta un difetto attivo.
+- **Un controllo obbligatorio che non può generare alcun risultato non è un controllo che non è stato eseguito qui.** Uno suggerisce di eliminare il requisito; l'altro suggerisce di correggere il trigger. Le correzioni si contraddicono a vicenda.
+- **Una richiesta di pull che il trigger ha saltato non è una richiesta in conflitto.** GitHub non esegue alcun flusso di lavoro per le richieste di pull su una richiesta di pull con conflitti, quindi la sua mancanza di controllo non dice nulla sul trigger. Quest'ultima richiede un rebase.
+- **Un'esecuzione non riuscita non è un'esecuzione annullata.** `cancel-in-progress` esiste per interrompere le esecuzioni obsolete, quindi i minuti annullati rappresentano solitamente la regola di concorrenza in funzione.
+- **Il costo lordo non è il costo netto.** GitHub calcola il costo dei repository pubblici al prezzo pieno e li riduce a zero. Il costo lordo è la potenza di calcolo reale; il costo netto è il denaro reale. Non vengono mai sommati.
+- **Se non viene misurato, non è corretto.** Un repository che GitHub non sta analizzando segnala zero avvisi. Un repository per il quale il controllo dei costi non è stato raggiunto non ha una riga di costo. Entrambi vengono segnalati come sconosciuti.
 
 La gravità determina un punteggio di salute: critico 40, alto 15, medio 6, basso 2, informativo 0, dedotto da 100. Il punteggio classifica l'attenzione, non la qualità.
 
@@ -171,8 +232,8 @@ Il [manuale](https://mcp-tool-shop-org.github.io/housekeeping/handbook/) elenca
 
 ## Sicurezza
 
-- **Solo lettura.** Il raccoglitore invia query GraphQL e richieste REST `GET`. Non esegue mai operazioni di merge, push, rilascio, pubblicazione o modifica di un'impostazione.
-- **Nessuna credenziale.** L'autenticazione è quella già presente in `gh`. Nulla viene scritto su disco al riguardo.
+- **Solo lettura.** Il raccoglitore invia query GraphQL e richieste REST `GET`. Non esegue mai operazioni di merge, push, release, pubblicazione o modifica di un'impostazione.
+- **Nessuna credenziale.** L'autenticazione è quella che `gh` già possiede. Nulla viene scritto su disco al riguardo.
 - **Nessuna telemetria.** Gli unici host contattati sono l'API di GitHub, tramite `gh`, e il registro npm, per la ricerca di versioni e avvisi.
 - **Ciò che memorizza** è la parte sensibile: vedere "Mantenere i dati privati".
 
@@ -184,7 +245,7 @@ Segnala una vulnerabilità come descritto in [SECURITY.md](SECURITY.md).
 npm test
 ```
 
-Ogni regola viene testata in entrambe le direzioni: la forma che deve attivarsi e la forma adiacente che non deve attivarsi. Un verificatore separato deriva nuovamente un campione di risultati da GitHub in tempo reale tramite il proprio trasporto e salta, in modo evidente, quando non è presente un database o una rete.
+Ogni regola viene testata in entrambe le direzioni: la forma che deve essere attivata e la forma adiacente che non deve esserlo. Un verificatore separato deriva nuovamente un campione di risultati da GitHub in tempo reale tramite il proprio canale di comunicazione e, in caso di assenza di database o di rete, lo segnala in modo evidente.
 
 ## Licenza
 

package/README.ja.md

@@ -10,7 +10,8 @@
 
 <p align="center">
   An operational-health warehouse for a GitHub organization.<br>
-  One sweep, one SQLite database, findings you can argue with.
+  One sweep, one SQLite database, findings you can argue with,<br>
+  and the whole-organization view an AI agent needs to coordinate every repository.
 </p>
 
 <p align="center">
@@ -25,28 +26,85 @@
 これにより、組織全体に対して、以下のことが一度に回答されます。
 
 - どのデフォルトブランチが問題があり、それが壊れたメインラインまたは古い履歴ですか？
-- 必須チェックが何も実行されていないために、どのプルリクエストもマージできませんか？
-- リポジトリ自体の設定では、どのデプロイが拒否されますか？
+- 必須のチェックが何も実行されないために、マージできないプルリクエストはどれですか？
+- リポジトリ自体の設定で、どのデプロイが拒否されますか？
 - `package.json`、Gitタグ、およびnpmレジストリは、どこで乖離していますか？
-- どのワークフローがActionsのコストルールに違反し、それらのコストはいくらで、どのジョブがそのコストを消費しましたか？
-- どのリポジトリに、GitHub自体のアラートカウントでは検出されないアドバイザリーが含まれていますか？
+- どのワークフローがActionsのコストルールに違反し、そのコストはいくらで、どのジョブがそのコストを負担しましたか？
+- GitHub自体のアラートカウントでは検出されないアドバイザリを保持しているリポジトリはどれですか？
 
 これは監査ツールであり、修正ツールではありません。GitHubを読み取り、何も変更しません。
 
+## すべてのリポジトリにわたるエージェント
+
+数十のリポジトリを持つ組織では、その状態が保存される単一の場所はありません。housekeepingがその場所であり、そのMCPサーバーである`hk-mcp`が、それをAIエージェントに渡します。これにより、1つのエージェントが組織全体のコーディネーターとして機能できます。
+
+1. **スキャン。** `hk refresh`は、すべてのリポジトリのスナップショットを1つ取得します。
+2. **トリアージ。** エージェントは、何が問題があり、何がブロックされており、何が悪化しているかを尋ね、壊れたメインラインと古い履歴、および競合しているプルリクエストと停止しているプルリクエストを区別する回答を取得します。
+3. **一連の処理を計画。** 1つの`hk_sql`クエリは、同じ形状を持つすべてのリポジトリを見つけ、修正を1つのリポジトリあたり1つのプルリクエストにするようにします。
+4. **作業を実行。** housekeepingは書き込みを行いません。エージェントは、独自のツールと独自の権限の下で、プルリクエストを開き、レビューを行います。
+5. **検証。** 再度スキャンします。問題が解決されているか、またはされていないかを確認し、2つのスナップショット間の変更はクエリになります。
+
+エージェントが1回の呼び出しで回答する質問：
+
+- どのデフォルトブランチが問題があり、どのジョブとステップが原因ですか？
+- どのプルリクエストがマージできず、トリガーまたは競合が原因ですか？
+- GitHubにはアラートが表示されない、本番環境のアドバイザリを保持しているリポジトリはどれですか？
+- スケジュールのルールに違反しているスケジュールされたワークフローはどれで、どのように違反していますか？
+- Actionsのコストはいくらで、どのジョブがそのコストを負担しましたか？
+- 最後のスキャンの後に何が変更されましたか？
+
+| ツール | 回答内容 |
+|---|---|
+| `hk_summary` | 最新のスキャンの合計：リポジトリ、問題、プルリクエスト、ワークフロー、検出結果。 |
+| `hk_findings` | コード、重大度、カテゴリ、またはリポジトリごとの検出結果。フィルターを適用していない場合のコードごとのカウント。問題のあるメインラインの検出結果は、問題を引き起こしたジョブとステップの名前を示します。 |
+| `hk_ci` | デフォルトブランチが問題のあるリポジトリと、失敗したワークフロー。また、失敗したスケジュール、失敗したプルリクエストブランチ、およびCIがないリポジトリ。 |
+| `hk_repo` | 完全な1つのリポジトリ：検出結果、ワークフロー、未解決のプルリクエストと問題。 |
+| `hk_backlog` | 組織全体の未解決のプルリクエストまたは問題（古いものから）。 |
+| `hk_health` | リポジトリごとの健全性スコア（最も低いものから）。 |
+| `hk_cost` | リポジトリ、ワークフロー、またはジョブごとのActionsの消費額（総額と純額）。 |
+| `hk_sql` | ウェアハウスに対する読み取り専用の1つの`SELECT`または`WITH`ステートメント。 |
+| `hk_schema` | `hk_sql`クエリを記述するためのテーブルと列。 |
+
+すべての回答は、開いてある読み取り専用の最新のスナップショットから取得されます。失敗した呼び出しは、構造化されたエラーを返し、スタックトレースは返しません。
+
+### 接続
+
+```json
+{
+  "mcpServers": {
+    "housekeeping": { "command": "hk-mcp", "env": { "HK_HOME": "/path/to/warehouse" } },
+    "atlas": { "command": "atlas", "args": ["mcp"] }
+  }
+}
+```
+
+`HK_HOME`は、スキャンを開始するディレクトリです。クローンから、`"command": "node", "args": ["/path/to/housekeeping/src/mcp.mjs"]`を使用します。2番目のサーバーは[Atlas](https://github.com/dogfood-lab/testing-os/tree/main/packages/atlas)であり、これは1つのリポジトリに対して同じエージェントに回答します（以下を参照）。Windowsでは、グローバルにインストールされたコマンドを`cmd /c`を通じて起動します。
+
+## housekeepingとAtlas
+
+[Atlas](https://github.com/dogfood-lab/testing-os/tree/main/packages/atlas)（`@dogfood-lab/atlas`）は、1つのリポジトリをマッピングします。その構成要素と、すべてのワークフロー、実行内容、公開内容、およびデプロイ内容です。このマップは、`atlas/`としてコミットされ、CIでチェックインされます。housekeepingは組織全体のビューです。これら2つは連携して動作するように構築されています。
+
+- **すべてのマップをスキャン。** スキャンは、各リポジトリのコミットされたマップと、その他のすべての情報を読み取り、マップがないリポジトリ、`atlas check`を実行していないリポジトリ、および組織の残りの部分がピンしているものとは異なるエンジンを保持しているリポジトリを報告します。
+- **問題のある実行がどこで発生したか。** デフォルトブランチが問題がある場合、検出結果は、失敗したジョブとステップの名前を示し、マップを通じて、そのステップが実行するコマンドを示します。したがって、修正は適切なファイルから開始されます。
+- **マップからのデプロイメントの事実。** ジョブがデプロイする環境は、マップに記録されている環境から取得されるため、両方のツールはワークフローを同じように読み取ります。
+- **フリート全体のアラート。** Atlasは、実行前に問題が発生するワークフローステップ（たとえば、ジョブがインストールするよりも新しいランタイムを必要とするツール）をフラグします。レポートは、これらをすべてのリポジトリに対して一度にリストします。
+
+両方のサーバーを持つエージェントは、「これらの12個のリポジトリがブロックされています」（housekeeping）から、「これはワークフロー、ジョブ、および変更が到達するファイルです」（Atlas）へと移行し、各リポジトリを手動で開く必要はありません。
+
 ## この構造になっている理由
 
 | レイヤー | 選択 | 理由 |
 |---|---|---|
-| 転送 | `gh` CLI | すでにトークンを保持しています。このツールは、認証情報を保存したり、要求したりすることはありません。 |
-| 収集 | GitHub GraphQL、ページング | 1つのクエリで、リポジトリの1ページのメタデータ、未解決の問題、未解決のプルリクエスト、リリース、およびファイルツリーが返されます。タイムアウトし続けるページは半分にされ、同じカーソルから再要求されます。 |
+| トランスポート | `gh` CLI | すでにトークンを保持しています。ツールは、認証情報を保存または要求しません。 |
+| 収集 | GitHub GraphQL、ページング | 1つのクエリは、リポジトリのページに対して、メタデータ、未解決の問題、未解決のプルリクエスト、リリース、およびファイルツリーを返します。タイムアウトし続けるページは半分に分割され、同じカーソルから再要求されます。 |
 | Actionsの実行 | REST | GraphQLにはActionsのインターフェースはありません。 |
-| Actionsのコスト | 請求APIと、ジョブごとの期間 | 請求書にはどのリポジトリであるかが記載されています。ジョブにはどのワークフローであるかが記載されています。GitHubの`/timing`エンドポイントはゼロを返すため、ジョブごとの合計を再計算し、次に請求書と照合します。 |
-| ランナーの料金 | 請求書から読み取ります | 請求される料金は、リスト価格と異なる場合があり、ソースに定数を使用すると、すべての数値が誤って表示されます。 |
-| ストレージ | 組み込みの`node:sqlite`を介したSQLite | ネイティブのビルドステップはありません。 |
-| 真実のソース | `data/snapshots/*.json` | 生の、差分化可能で、追加のみのデータ。データベースは派生したものです。`npm run rebuild`は、オフラインで再構築します。 |
-| スキャンログ | `data/sweeps.jsonl` | 1つのスキャンあたり1行。これには、失敗したスキャンと、新しいものが見つからなかったスキャンが含まれます。 |
+| アクションにはコストがかかる | 請求 API に加えて、ジョブごとの実行時間 | 請求書にはどのリポジトリが記載されており、ジョブにはどのワークフローが記載されているか。GitHub の `/timing` エンドポイントは 0 を返すため、ジョブごとの合計が再計算され、その後、請求書と照合される。 |
+| ランナーの料金 | 請求書から読み取る | 請求される料金は、リスト価格と異なる場合があり、ソースコード内の定数はすべての数値を誤って表示する。 |
+| ストレージ | 組み込みの `node:sqlite` を使用した SQLite | ネイティブのビルドステップはない。 |
+| 信頼できる情報源 | `data/snapshots/*.json` | 生のデータで、差分を比較でき、追加のみが可能。データベースはそこから派生する：`npm run rebuild` はオフラインで再構築する。 |
+| スウィープログ | `data/sweeps.jsonl` | 1行に1つのスウィープを記録。失敗したスウィープと、新しいものが見つからなかったスウィープも含む。 |
 
-スナップショットは不変で追加されるため、2つの日付間のドリフトは`JOIN`です。
+スナップショットは不変で累積的であるため、2つの日付間のドリフトは `JOIN` である。
 
 ## 要件
 
@@ -66,9 +124,9 @@ mkdir warehouse && cd warehouse            # housekeeping keeps its data here
 hk refresh your-org                        # collect, load, analyze, write reports/AUDIT-<date>.md
 ```
 
-スキャン間で設定を保持するには、そのディレクトリに`housekeeping.config.json`を配置します（構成を参照）。その後、`hk refresh`には引数は必要ありません。
+スウィープ間で設定を保持するには、そのディレクトリに `housekeeping.config.json` を配置する（構成を参照）。その後、`hk refresh` に引数は不要。
 
-または、クローンから実行すると、そのデータがクローン内に保持されます。
+または、クローンから実行すると、そのデータはクローンに保存される。
 
 ```bash
 git clone https://github.com/mcp-tool-shop-org/housekeeping.git
@@ -79,7 +137,7 @@ cp housekeeping.config.example.json housekeeping.config.json   # then set "org"
 hk refresh
 ```
 
-次に、クエリを実行します。
+次に、クエリを実行する。
 
 ```bash
 hk summary               # portfolio totals
@@ -95,17 +153,17 @@ hk sql "SELECT ..."      # one read-only statement
 hk help                  # every command and flag
 ```
 
-`npm link`がないクローンでは、各`hk <command>`は`node src/cli.mjs <command>`になります。
+`npm link` がないクローンでは、各 `hk <command>` は `node src/cli.mjs <command>` である。
 
-`npm run rebuild`は、ディスクにすでに存在するスナップショットからデータベースとレポートを再構築し、ネットワークアクセスは行いません。
+`npm run rebuild` は、ディスク上の既存のスナップショットからデータベースとレポートを再派生させ、ネットワークアクセスは行わない。
 
-完全なスキャンでは、数百のAPI呼び出しが行われます。`refresh`をループで実行しないでください。
+完全なスウィープでは、数百回の API 呼び出しが行われる。`refresh` をループで実行しないこと。
 
-結果は標準出力に出力され、進行状況とエラーは標準エラーに出力されます。すべてのエラーには、コードとヒントが出力されます。終了コード：0（正常）、1（ユーザーエラー）、2（実行時エラー）、3（部分的（スキャンは完了しましたが、ギャップがあります））。
+結果は標準出力に出力され、進行状況とエラーは標準エラーに出力される。すべてのエラーには、コードとヒントが出力される。終了コード：0（正常）、1（ユーザーエラー）、2（実行時エラー）、3（部分的 - スウィープは完了したが、ギャップがある）。
 
 ## 構成
 
-`housekeeping.config.json`は、ハウスキーピングが機能するディレクトリにあります（以下を参照）。
+`housekeeping.config.json` は、ハウスキーピングが実行されるディレクトリにある（下記参照）。
 
 ```json
 {
@@ -114,73 +172,56 @@ hk help                  # every command and flag
 }
 ```
 
-- `org`は、スキャンする組織です。`hk refresh <org>`でオーバーライドできます。どちらも指定されていない場合、スキャンは開始されません。
-- `metaRepos`は、組織のデフォルト、アセット、またはツールを保持するリポジトリであり、出荷される製品ではありません。これらは、README、LICENSEなどのファイルがない、ワークフローがない、リリースがないなど、製品にのみ意味がある結果から除外されます。
+- `org` は、スウィープする組織である。`hk refresh <org>` でオーバーライドできる。どちらも指定されていない場合、スウィープは開始されない。
+- `metaRepos` は、組織のデフォルト、アセット、またはツールを格納するリポジトリであり、出荷される製品ではない。これらは、製品にのみ意味がある結果（README、LICENSE などのファイルがない、ワークフローがない、リリースがない）から除外される。
 
-形式が正しくないファイルはエラーであり、サイレントなデフォルトになることはありません。不明なキー、誤った型、または破損したJSONは、実行を停止します。
+形式が正しくないファイルはエラーであり、サイレントなデフォルトになることはない。不明なキー、誤った型、または破損した JSON は、実行を停止させる。
 
-クローンから実行する場合、ハウスキーピングは`data/`、`reports/`、および構成ファイルをクローンに保持します。インストールされたパッケージとして実行する場合、それらは実行するディレクトリまたは、設定されている場合は`HK_HOME`に保持されます。
+クローンから実行すると、ハウスキーピングは `data/`、`reports/`、および構成ファイルをクローンに保存する。インストールされたパッケージとして実行すると、実行するディレクトリまたは `HK_HOME`（設定されている場合）に保存する。
 
-環境：`HK_HOME`（データ、レポート、および構成が保存される場所）、`HK_CONFIG`（構成パス）、`HK_DB`（データベースパス）、`HK_LOG`（`silent`、`normal`、`verbose`、または`debug`）、`HK_COST_REPOS`、および`HK_COST_BUDGET`（ジョブごとのコストの範囲）、`GH_PATH`（`gh`へのパス）。
+環境：`HK_HOME`（データ、レポート、および構成が保存される場所）、`HK_CONFIG`（構成パス）、`HK_DB`（データベースパス）、`HK_LOG`（`silent`、`normal`、`verbose`、または `debug`）、`HK_COST_REPOS`、および `HK_COST_BUDGET`（ジョブごとのコストの制限）、`GH_PATH`（`gh` へのパス）。
 
 ## データを非公開に保つ
 
-**スキャンによって書き込まれる内容は機密情報です。`data/`または`reports/`をパブリックリポジトリにコミットしないでください。**
-
-スナップショットには、プライベートリポジトリの名前と説明、パッケージ名を含むすべての未解決のセキュリティアラート、ワークフローファイル、およびActionsの課金が記録されます。GitHubは、パブリックリポジトリのセキュリティアラートを、そのリポジトリのメンテナー以外のすべてのユーザーから意図的に非表示にします。公開されたスナップショットは、そのリストを公開することになります。
-
-このリポジトリの`.gitignore`は、`data/`、`reports/`、および`housekeeping.config.json`を除外します。履歴を保持することがスナップショットの目的であるため、独自の**プライベート**リポジトリからツールを実行し、そこにコミットしてください。
-
-## MCPサーバー
-
-`hk-mcp`（またはクローン内の`npm run mcp`）は、標準入出力（stdio）を介してデータストアにアクセスするため、アシスタントは数メガバイトのデータ全体を読み込むことなく質問をすることができます。
-
-`hk_summary` · `hk_findings` · `hk_ci` · `hk_repo` · `hk_backlog` · `hk_health` · `hk_cost` · `hk_sql` · `hk_schema`
-
-```json
-{
-  "mcpServers": {
-    "housekeeping": { "command": "hk-mcp", "env": { "HK_HOME": "/path/to/warehouse" } }
-  }
-}
-```
+**スウィープによって書き込まれる内容は機密情報である。`data/` または `reports/` をパブリックリポジトリにコミットしないこと。**
 
-`HK_HOME`は、スキャンを開始するディレクトリです。クローンから実行する場合は、代わりに`"command": "node", "args": ["/path/to/housekeeping/src/mcp.mjs"]`を使用します。
+スナップショットには、プライベートリポジトリの名前と説明、パッケージ名を含むすべての開いているセキュリティアラート、ワークフローファイル、および Actions の請求情報が記録される。GitHub は、パブリックリポジトリのセキュリティアラートを、そのリポジトリのメンテナー以外のすべてのユーザーから意図的に非表示にする。公開されたスナップショットは、そのリストを公開することになる。
 
-`hk_sql`は、単一の`SELECT`または`WITH`ステートメントを受け入れ、データベースを読み取り専用で開きます。失敗した呼び出しは、スタックトレースではなく、構造化されたエラーを返します。
+このリポジトリの `.gitignore` は、`data/`、`reports/`、および `housekeeping.config.json` を除外する。履歴を保持することがスナップショットの目的であるため、独自の**プライベート**リポジトリからツールを実行し、そこにコミットすること。
 
 ## 検出結果
 
-ルールは`src/analyze.mjs`にあります。各ルールは、適用する記述されたルールを参照するため、検出結果は、好みに基づいてではなく、標準に対して議論することができます。このリポジトリに付属するルールは、[`rules/`](rules/)にあります。
+ルールは `src/analyze.mjs` にある。各ルールは、適用する書面によるルールを参照するため、検出結果は、好みに基づいてではなく、標準に基づいて議論できる。このリポジトリに同梱されているルールは、[`rules/`](rules/) にある。
 
-- [`rules/github-actions.md`](rules/github-actions.md): パスのフィルター、ランナー、マトリックスのサイズ、ワークフローファイルの制限、同時実行。
-- [`rules/shipcheck-product-standards.md`](rules/shipcheck-product-standards.md): CIに合格していること、出荷ゲート、バージョン。
-- [`rules/repo-first.md`](rules/repo-first.md): デフォルトブランチ。
-- [`rules/atlas-map.md`](rules/atlas-map.md): 各リポジトリのコミットされたマップ。CIでチェックされる。
+- [`rules/github-actions.md`](rules/github-actions.md)：パスフィルター、ランナー、マトリックスサイズ、ワークフローファイルの制限、同時実行。
+- [`rules/shipcheck-product-standards.md`](rules/shipcheck-product-standards.md)：CI はパスする必要がある、出荷ゲート、バージョン。
+- [`rules/repo-first.md`](rules/repo-first.md)：デフォルトブランチ。
+- [`rules/atlas-map.md`](rules/atlas-map.md)：各リポジトリのコミットされたマップ。CI でチェックされる。
 
-これらは、ある組織の標準です。もし貴社の標準と異なる場合は、ルールファイルとルールを合わせて変更してください。
+これらは、ある組織の標準である。異なる場合は、ルールファイルとルールを一緒に変更する。
 
-ルールは、見た目が似ているものを区別するように設計されており、それらをまとめてしまうとノイズが発生するためです。
+ルールは、似たもの同士を区別するように注意している。なぜなら、それらをまとめてしまうとノイズが発生するからである。
 
-- **赤いデフォルトブランチは、赤いプルリクエストブランチではありません。** 失敗したDependabotブランチはバックログであり、デフォルトブランチで失敗した`push`の実行は、問題です。どちらであるかは、実行のイベントによって決まります。
-- **履歴は、問題ではありません。** リリース専用のトリガーに移動したワークフローは、最後のデフォルトブランチでの失敗を永久に保持します。削除されたワークフローは、その実行を保持します。どちらも、現在の欠陥ではありません。
-- **必須チェックで何も出力できない場合、それはここで実行されなかったチェックではありません。** 片方は、要件を削除すると言っています。もう片方は、トリガーを修正すると言っています。これらの修正は、互いに矛盾しています。
-- **失敗した実行は、キャンセルされた実行ではありません。** `cancel-in-progress`は、古い実行を停止するために存在するため、キャンセルされた時間は通常、同時実行ルールの動作によるものです。
-- **総コストは、純コストではありません。** GitHubは、パブリックリポジトリを定価で計測し、割引を適用してゼロにします。総コストは実際の計算量であり、純コストは実際の費用です。これらは決して合計されません。
-- **計測されていないものは、問題ありません。** GitHubがスキャンしていないリポジトリは、0件のアラートを報告します。コストのチェックに達していないリポジトリは、コストの行を持ちません。どちらも、不明として報告されます。
+- **赤いデフォルトブランチは、赤いプルリクエストブランチではありません。** 失敗した Dependabot ブランチはバックログであり、デフォルトブランチで失敗した `push` の実行は問題を引き起こします。どちらであるかは、実行のイベントによって決まります。
+- **履歴は問題ではありません。** リリース専用のトリガーに移動したワークフローは、最後のデフォルトブランチでの失敗を永久に保持します。削除されたワークフローは、その実行を保持します。どちらも現在の欠陥ではありません。
+- **実行できないチェックは、ここで実行されなかったチェックではありません。** 一方は、要件を削除すると言います。もう一方は、トリガーを修正すると言います。これらの修正は互いに矛盾します。
+- **トリガーがスキップしたプルリクエストは、競合しているプルリクエストではありません。** GitHub は、競合のあるプルリクエストに対してプルリクエストワークフローを実行しないため、欠落しているチェックはトリガーについて何も意味しません。これは、リベースが必要です。
+- **失敗した実行は、キャンセルされた実行ではありません。** `cancel-in-progress` は、古い実行を終了させるために存在するため、キャンセルされた時間は通常、同時実行ルールの動作によるものです。
+- **総コストは、純コストではありません。** GitHub は、パブリックリポジトリに対して全額料金を請求し、それをゼロに割引します。総コストは実際の計算量であり、純コストは実際の費用です。これらは決して合計されません。
+- **測定されていないものは、問題ありません。** GitHub がスキャンしていないリポジトリは、アラートをゼロとして報告します。コストの計算に達していないリポジトリは、コストの行を持ちません。どちらも不明として報告されます。
 
-重大度によって、健全性スコアが決まります。重大なものは40、高いものは15、中程度のものは6、低いものは2、情報提供のみのものは0。これらはすべて、100から差し引かれます。スコアは、品質ではなく、注意の優先順位を示します。
+重大度によって健全性スコアが決まります。重大なものは 40、高いものは 15、中程度のものは 6、低いものは 2、情報提供のみのものは 0 で、これらはすべて 100 から差し引かれます。スコアは品質ではなく、優先度を示します。
 
-[ハンドブック](https://mcp-tool-shop-org.github.io/housekeeping/handbook/)には、すべての検出結果、コマンド、エラーコード、およびテーブルがリストされています。
+[ハンドブック](https://mcp-tool-shop-org.github.io/housekeeping/handbook/) には、すべての検出結果、コマンド、エラーコード、およびテーブルがリストされています。
 
 ## セキュリティ
 
-- **読み取り専用。** コレクターは、GraphQLクエリとREST `GET`を発行します。決してマージ、プッシュ、リリース、公開、または設定を編集することはありません。
-- **認証情報なし。** 認証は、`gh`がすでに保持しているものを使用します。それに関する情報はディスクに書き込まれません。
-- **テレメトリーなし。** 連絡するホストは、GitHub API（`gh`経由）と、バージョンおよびアドバイザリの検索のためのnpmレジストリのみです。
-- **保存する内容**が機密性の高い部分です。「データのプライバシーを保護する」を参照してください。
+- **読み取り専用。** コレクターは GraphQL クエリと REST `GET` を発行します。マージ、プッシュ、リリース、公開、または設定の編集は行いません。
+- **認証情報なし。** 認証は、`gh` がすでに保持しているものを使用します。それに関する情報はディスクに書き込まれません。
+- **テレメトリなし。** 連絡するホストは、`gh` を介した GitHub API と、バージョンおよびアドバイザリの検索のための npm レジストリのみです。
+- **保存する内容** が機密性の高い部分です。「データのプライバシーを維持する」を参照してください。
 
-[SECURITY.md]に記載されているように、脆弱性を報告してください。
+[SECURITY.md] に説明されているように、脆弱性を報告してください。
 
 ## テスト
 
@@ -188,12 +229,12 @@ hk help                  # every command and flag
 npm test
 ```
 
-すべてのルールは、両方向でテストされます。つまり、トリガーされるべき形状と、トリガーされるべきでない隣接する形状です。別の検証ツールは、独自のトランスポートを使用して、ライブGitHubから検出結果のサンプルを再構築し、データベースまたはネットワークがない場合は、エラーメッセージを大きく表示します。
+すべてのルールは、両方向でテストされます。つまり、トリガーされるべき形状と、トリガーされるべきでない隣接する形状です。別の検証ツールは、独自のトランスポートを介して、ライブ GitHub から検出結果のサンプルを再計算し、データベースまたはネットワークがない場合は、エラーを発生させます。
 
 ## ライセンス
 
-MIT。 [LICENSE](LICENSE)を参照してください。
+MIT。 [LICENSE](LICENSE) を参照してください。
 
 ---
 
-<a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>によって作成されました。
+<a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a> によって作成されました。