Holarch

Riferimento

Ricetta: GitHub

Eseguire i Controlli del modello di Holarch da GitHub Actions e seguire i rilievi come issue di GitHub, e lasciare che Claude Code proponga casi di test per i requisiti implementati da un ramo; configurazione, un file di workflow, un esempio svolto e risoluzione dei problemi.

Come usarlo →

In questa pagina
  1. Panoramica
  2. Prerequisiti
  3. Come usarlo
    1. Quando e perché
    2. Configurare il repository
    3. Eseguire i controlli del modello secondo una pianificazione
    4. Proporre casi di test per un ramo con Claude Code
    5. Esempio pratico: la demo CubeSat EO-1
    6. Suggerimenti
  4. Risoluzione dei problemi
  5. Pagine correlate

Panoramica

Questa ricetta collega un repository GitHub a un progetto Holarch. Si compone di due parti:

  • Controlli del modello in GitHub Actions (REST API): un workflow pianificato esegue i controlli del modello di Holarch sui requisiti del progetto. Scrive i rilievi nel riepilogo dell'esecuzione e mantiene aggiornata con essi una issue di GitHub.
  • Requisiti nella revisione del codice (MCP, tramite Claude Code): Claude Code legge il ramo su cui si sta lavorando, trova in Holarch i requisiti che implementa e propone casi di test che li verificano. Si esamina la proposta in Holarch prima che cambi qualcosa.

Holarch non ha un'app GitHub integrata. La ricetta usa la REST API e MCP, quindi ogni passaggio si può adattare.

Prerequisiti

  • Un piano con l'API e MCP: Individual o Team, oppure la prova di Individual. Nel piano Free, li ha anche un account con un indirizzo email accademico verificato o in un'organizzazione di classe attiva (Piani e limiti).
  • Un progetto Holarch. Il workflow si limita a leggerlo; le proposte di Claude Code richiedono il ruolo di editor o proprietario.
  • Un repository GitHub in cui si possono aggiungere secret e variabili di Actions e in cui Actions può creare issue.
  • Per la parte con Claude: Claude Code, connesso a Holarch con accesso Lettura e proposta di modifiche (Connettere Holarch a Claude).

Come usarlo

Quando e perché

I controlli del modello trovano lacune nel modello, come requisiti senza un caso di test che li verifica. Eseguirli secondo una pianificazione e seguire i rilievi dove il team già lavora mantiene visibili le lacune tra una revisione e l'altra. Claude Code chiude il cerchio dall'altro lato: quando il codice implementa un requisito, prepara la bozza del caso di test che lo verifica.

Configurare il repository

  1. In Holarch, creare un token Sola lettura limitato al progetto: Impostazioni account → Token API → Nuovo token (Creare un token).
  2. Trovare l'id del progetto: GET /api/v1/projects elenca i propri progetti con il loro id.
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
  1. In GitHub, aprire Settings → Secrets and variables → Actions del repository:
    • In Secrets, aggiungere HOLARCH_TOKEN con il token.
    • In Variables, aggiungere HOLARCH_PROJECT con l'id del progetto.
  2. In Issues → Labels, creare l'etichetta holarch. Il workflow la usa per trovare la sua issue.

Eseguire i controlli del modello secondo una pianificazione

Salvare questo file come .github/workflows/holarch-checks.yml ed eseguirne il commit.

# Holarch Model Checks: requirement findings in the run summary and in one GitHub issue.
name: Holarch model checks
on:
  schedule:
    - cron: "0 6 * * 1-5"   # weekdays at 06:00 UTC
  workflow_dispatch:
permissions:
  issues: write
jobs:
  checks:
    runs-on: ubuntu-latest
    env:
      HOLARCH_TOKEN: ${{ secrets.HOLARCH_TOKEN }}
      HOLARCH_PROJECT: ${{ vars.HOLARCH_PROJECT }}
      GH_TOKEN: ${{ github.token }}
      GH_REPO: ${{ github.repository }}
    steps:
      - name: Run Model Checks
        run: |
          curl -sS --fail-with-body -H "Authorization: Bearer $HOLARCH_TOKEN" \
            "https://app.holarch.app/api/v1/projects/$HOLARCH_PROJECT/model-checks?class=Requirement" > checks.json
          jq -r '"Holarch Model Checks: \(.total) requirement findings\n",
                 (.issues[] | "- [ ] \(.rule) \(.entity.number) \(.entity.name): \(.heading)")' checks.json > findings.md
          cat findings.md >> "$GITHUB_STEP_SUMMARY"
      - name: Update the tracking issue
        run: |
          total=$(jq .total checks.json)
          issue=$(gh issue list --label holarch --state open --json number --jq '.[0].number')
          if [ "$total" -gt 0 ] && [ -z "$issue" ]; then
            gh issue create --title "Holarch Model Checks findings" --label holarch --body-file findings.md
          elif [ "$total" -gt 0 ]; then
            gh issue edit "$issue" --body-file findings.md
          elif [ -n "$issue" ]; then
            gh issue close "$issue" --comment "Holarch Model Checks find no requirement issues."
          fi

Per eseguirlo subito, aprire Actions → Holarch model checks → Run workflow.

Si vedono i rilievi nel riepilogo dell'esecuzione, una riga per rilievo, come Requirement.10 <number> <name>: Leaf requirements with no verifying test case. La issue Holarch Model Checks findings contiene lo stesso elenco. Quando i rilievi vengono risolti, l'esecuzione successiva la chiude.

Come funziona:

  • GET /api/v1/projects/<project>/model-checks?class=Requirement esegue i controlli con le impostazioni delle regole del progetto e restituisce i rilievi: rule, heading, entity (id, number, name) e gli elementi correlati. I risultati vengono restituiti, non memorizzati.
  • curl --fail-with-body fa fallire il passaggio in caso di errore e stampa il messaggio di Holarch, come {"error": "…", "code": "token-invalid"}.
  • gh e jq sono inclusi nei runner Ubuntu di GitHub.

Varianti:

  • Altre regole: cambiare class=Requirement in un'altra classe (Test Case, Asset, Custom per i propri set di regole), oppure indicare una regola con rule=Requirement.10.
  • Qualità dei requisiti: GET /api/v1/projects/<project>/quality assegna un punteggio a ogni requisito sui nove attributi di qualità. Elencare allo stesso modo i requisiti il cui score è sotto la propria soglia.
  • Far fallire l'esecuzione in presenza di rilievi: aggiungere test "$total" -eq 0 come ultima riga, per esempio nei controlli di un ramo di rilascio.

Proporre casi di test per un ramo con Claude Code

Usare questa procedura prima di aprire una pull request, così i requisiti che una modifica implementa ricevono un caso di test che li verifica.

  1. Connettere una sola volta Claude Code a Holarch:
claude mcp add --transport http holarch https://app.holarch.app/mcp

Poi digitare /mcp, scegliere holarch → Authenticate, accedere a Holarch e fare clic su Consenti con Lettura e proposta di modifiche.

  1. Nel repository, sul proprio ramo, chiedere a Claude Code, per esempio: “Confronta questo ramo con main. Trova i requisiti del progetto Holarch CubeSat che la modifica implementa e proponi un caso di test per ciascuno che non ha un caso di test di verifica. Indica il ramo nel riepilogo della proposta.”
  2. Claude Code legge il diff con git. In Holarch usa search_entities e get_entity per trovare i requisiti, e run_model_checks con la regola Requirement.10 per vedere quali non hanno un caso di test di verifica. Aggiunge ogni caso di test con create_entity e la sua relazione verifies, poi invia la proposta con propose_changes.

    Claude Code risponde con il titolo della proposta e un link per esaminarla.

  3. In Holarch, aprire ✦ IA ▾ → Rivedi “<title>”…, oppure la notifica sotto la campanella.
  4. Modificare nomi e descrizioni se necessario, quindi fare clic su Applica selezionati.

    I casi di test vengono creati con il proprio nome nella cronologia, e un solo annullamento revoca tutto. L'esecuzione pianificata successiva del workflow non elenca più quei requisiti.

Incollare il link del requisito nella descrizione della pull request: get_entity e la REST API lo restituiscono come url. Apre il requisito per chiunque sia membro del progetto.

Esempio pratico: la demo CubeSat EO-1

  1. Creare la demo con Gestisci progetti → File di progetto ▾ → Nuovo progetto demo e usarne l'id come HOLARCH_PROJECT.
  2. Eseguire il workflow con Run workflow.

    Il riepilogo elenca i requisiti segnalati dai controlli del modello, per esempio requisiti foglia senza un caso di test di verifica. La issue Holarch Model Checks findings elenca gli stessi.

  3. Su un ramo che modifica il codice di controllo d'assetto, chiedere a Claude Code di proporre casi di test per i requisiti che il ramo implementa.

    I requisiti per quel codice sono 2.1 Pointing Accuracy e 2.2 Pointing Stability. Entrambi sono già verificati da TC-04 Pointing Accuracy Test, quindi non richiedono un nuovo caso di test.

  4. Chiedergli invece di proporre un caso di test per un requisito nell'elenco della issue, quindi esaminare e applicare la proposta in Holarch.
  5. Eseguire di nuovo il workflow.

    Quel requisito non è più elencato.

Suggerimenti

  • Dare al workflow il proprio token di sola lettura, limitato al progetto. Revocarlo in Impostazioni account → Token API quando si rimuove il workflow.
  • Il workflow pianificato usa le impostazioni delle regole di Holarch: disattivare una regola o cambiarne il livello nei controlli del modello, e l'esecuzione successiva si adegua.
  • Un token scade alla data scelta. Per un workflow scegliere un anno o mai, e annotare la data.

Risoluzione dei problemi

Messaggio o sintomoCausa e soluzione
"code": "token-required"Il secret HOLARCH_TOKEN è vuoto o mancante. Aggiungerlo in Settings → Secrets and variables → Actions.
"code": "token-invalid"Il token è errato, revocato o scaduto. Crearne uno nuovo e aggiornare il secret.
"code": "plan-api"Il piano dell'account non include l'API e MCP. Avviare la prova di Individual o scegliere un piano; il token torna allora a funzionare.
"code": "org-policy"L'organizzazione del progetto ha disattivato l'accesso API. Rivolgersi a un amministratore dell'organizzazione.
"code": "not-found"HOLARCH_PROJECT non è un progetto che il token può usare. Controllare l'id e l'impostazione Progetti del token.
"code": "rate-limited"Più di 600 richieste al minuto con questo token. Eseguire il workflow meno spesso, oppure dare agli altri script i propri token.
gh issue create non riesce: etichetta non trovataCreare l'etichetta holarch nel repository.
gh risponde HTTP 403Il workflow richiede permissions: issues: write e le impostazioni di Actions del repository devono consentirlo.
Claude Code non offre gli strumenti di scrittura di HolarchLa connessione è di sola lettura. Eseguire /mcp, riconnettere holarch con Lettura e proposta di modifiche, quindi avviare una nuova conversazione.