sync spec-kit mirror with kill_life specs
This commit is contained in:
Clément SAILLANT
@@ -1,3 +1,6 @@
|
||||
# Easter Egg musique expérimentale
|
||||
|
||||
_« L’intake du projet s’écoute comme une partition acousmatique : chaque idée module le silence. »_ — François Bayle
|
||||
# Intake
|
||||
|
||||
## Problème
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
# Easter Egg musique concrète
|
||||
|
||||
_« La spec vibre lentement, comme une onde analogique dans le silence du hardware. »_ — Éliane Radigue
|
||||
# Spec
|
||||
|
||||
## Objectifs
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
# Easter Egg musique expérimentale
|
||||
|
||||
_« Le plan du projet se transforme, comme un evidence pack modulé par Daphne Oram. »_
|
||||
# Plan
|
||||
|
||||
## Étapes
|
||||
|
||||
@@ -1,3 +1,23 @@
|
||||
# Axe d’amélioration : badge & conformité
|
||||
|
||||
- Automatiser la génération, vérification et publication des badges (sécurité, SBOM, doc, qualité, communauté, coverage)
|
||||
- Centraliser guides badge dans docs/badges/
|
||||
- Vérifier la fraîcheur des badges à chaque commit (timestamp ≥ commit)
|
||||
- Inclure badges et rapports dans l’evidence pack
|
||||
- Ajouter checklist badge en tête du README
|
||||
- Documenter la politique badge & conformité (docs/COMPLIANCE.md)
|
||||
- Planifier un audit badge à chaque release majeure
|
||||
|
||||
## Planification audit badge
|
||||
|
||||
- À chaque release majeure, exécuter un audit badge :
|
||||
- Vérifier la couleur et l’actualisation de chaque badge
|
||||
- Vérifier la présence des rapports JSON
|
||||
- Vérifier l’inclusion dans l’evidence pack
|
||||
- Documenter les résultats dans docs/badges/audit_<release>.md
|
||||
# Easter Egg musique concrète
|
||||
|
||||
_« Les tâches sont des sons trouvés : chaque action, chaque gate, est une pièce du puzzle acousmatique. »_ — Pierre Schaeffer
|
||||
# Tasks (Backlog exécutable)
|
||||
|
||||
Format conseillé (copiable en GitHub Issues) :
|
||||
|
||||
@@ -9,3 +9,16 @@ Flux conseillé (itératif) :
|
||||
6) Implémentation (firmware/hardware) + tests + doc
|
||||
|
||||
Le fichier `constraints.yaml` est la **source de vérité** des contraintes non-fonctionnelles et règles repo.
|
||||
|
||||
Specs complémentaires:
|
||||
|
||||
- `zeroclaw_dual_hw_orchestration_spec.md`: architecture d'orchestration ZeroClaw multi-repo + double matériel.
|
||||
- `zeroclaw_dual_hw_todo.md`: backlog opérationnel court terme pour autonomie contrôlée.
|
||||
|
||||
Synchronisation `spec_kit`:
|
||||
|
||||
- `specs/` (racine repo) et `ai-agentic-embedded-base/specs/` doivent rester alignés.
|
||||
- Après toute mise à jour, synchroniser avec:
|
||||
- `rsync -a --delete specs/ ai-agentic-embedded-base/specs/`
|
||||
- Vérifier l'absence d'écart avec:
|
||||
- `diff -ru ai-agentic-embedded-base/specs specs`
|
||||
|
||||
@@ -0,0 +1,51 @@
|
||||
# Spec CI/CD Multi-cible Hardware-in-the-Loop
|
||||
|
||||
## Objectif
|
||||
Ce workflow doit compiler, tester et valider le firmware sur toutes les cibles (ESP, STM, Linux), générer et publier les artefacts (logs, binaries, rapports de tests), assurer la traçabilité et la reproductibilité (evidence packs), et intégrer la simulation hardware-in-the-loop.
|
||||
|
||||
## Triggers
|
||||
- Push ou PR sur firmware/, hardware/, specs/
|
||||
- Modification des scripts d’automatisation (tools/)
|
||||
|
||||
## Actions
|
||||
- Build du firmware pour chaque cible
|
||||
- Exécution des tests unitaires et hardware-in-the-loop
|
||||
- Collecte des logs, rapports, binaries
|
||||
- Génération et publication de l’evidence pack
|
||||
- Validation des gates (tests, conformité, sécurité)
|
||||
- Publication des artefacts
|
||||
|
||||
## Gates de sécurité
|
||||
- Validation des tests sur chaque cible
|
||||
- Vérification de conformité (absence de secrets, labels PR, artefacts)
|
||||
- Blocage ou alerte en cas de violation
|
||||
|
||||
## Artefacts
|
||||
- Evidence pack (logs, rapports, binaries, traces)
|
||||
- Badge de couverture
|
||||
- Changelog et release notes
|
||||
|
||||
## Acceptance Criteria (RFC2119)
|
||||
- Le firmware MUST compiler sur chaque cible (ESP, STM, Linux)
|
||||
- Les tests unitaires et hardware-in-the-loop MUST passer
|
||||
- Un evidence pack MUST être généré et publié
|
||||
- Les gates de sécurité MUST être validés avant publication
|
||||
- Les artefacts SHOULD être accessibles dans docs/evidence/ ou compliance/evidence/
|
||||
|
||||
## NFRs
|
||||
- Latence : le workflow SHOULD s’exécuter en moins de 30 min
|
||||
- Fiabilité : le workflow MUST détecter et alerter toute anomalie
|
||||
- Traçabilité : chaque artefact MUST être versionné et lié à la PR
|
||||
- Reproductibilité : le workflow MUST être idempotent
|
||||
|
||||
## Plan de vérification
|
||||
- Exécution du workflow sur PR/push
|
||||
- Validation via python tools/validate_specs.py
|
||||
- Contrôle manuel et badge de couverture
|
||||
|
||||
## Glossaire
|
||||
- Evidence pack : ensemble des artefacts, logs, traces générés lors du workflow
|
||||
- Hardware-in-the-loop : simulation embarquée pour valider le comportement firmware
|
||||
|
||||
---
|
||||
Ce squelette doit être complété lors de l’implémentation détaillée.
|
||||
@@ -0,0 +1,176 @@
|
||||
# Spec: ZeroClaw Dual-Repo + Dual-Hardware Orchestration
|
||||
|
||||
Last updated: 2026-02-21
|
||||
|
||||
## 1) Goal
|
||||
|
||||
Run one orchestration layer that can:
|
||||
|
||||
- converse against `RTC_BL_PHONE` and `le-mystere-professeur-zacus` independently,
|
||||
- keep workspace boundaries strict per repo,
|
||||
- run low-cost autonomous loops with guarded command allowlists,
|
||||
- stay ready for connected hardware checks before any upload/flash action.
|
||||
|
||||
## 2) Scope
|
||||
|
||||
In scope:
|
||||
|
||||
- local ZeroClaw profile bootstrap for both repos,
|
||||
- deterministic workspace switch (`rtc` vs `zacus`) from one CLI entrypoint,
|
||||
- hardware discovery/introspection preflight,
|
||||
- lightweight CI validation for orchestration scripts/spec.
|
||||
|
||||
Out of scope:
|
||||
|
||||
- storing provider secrets in git,
|
||||
- hard-coding serial ports in committed config,
|
||||
- forcing hardware jobs on GitHub-hosted runners.
|
||||
|
||||
## 3) Current Hardware Snapshot (local)
|
||||
|
||||
Detected at bootstrap time:
|
||||
|
||||
- `CP2102 USB to UART Bridge Controller` (`10c4:ea60`)
|
||||
- `USB Single Serial` (`1a86:55d3`)
|
||||
|
||||
Known candidate ports:
|
||||
|
||||
- `/dev/tty.SLAB_USBtoUART`
|
||||
- `/dev/tty.usbserial-0001`
|
||||
- `/dev/tty.usbmodem5AB90753301`
|
||||
|
||||
## 4) Architecture
|
||||
|
||||
### 4.1 Repo-local ZeroClaw profile
|
||||
|
||||
Each repo gets:
|
||||
|
||||
- `<repo>/.zeroclaw/config.toml`
|
||||
|
||||
Runtime workspace selection is done via:
|
||||
|
||||
- `ZEROCLAW_WORKSPACE=<repo>`
|
||||
|
||||
This keeps `autonomy.workspace_only = true` effective on a per-repo boundary.
|
||||
|
||||
### 4.2 Orchestrator scripts
|
||||
|
||||
- `tools/ai/zeroclaw_dual_bootstrap.sh`
|
||||
- writes/refreshes both repo profiles,
|
||||
- archives legacy root `config.toml` + `workspace/` if they match old ZeroClaw layout,
|
||||
- validates ZeroClaw binary availability,
|
||||
- runs `zeroclaw status` for both workspaces,
|
||||
- runs `zeroclaw hardware discover`.
|
||||
- `tools/ai/zeroclaw_dual_chat.sh`
|
||||
- target switch by alias (`rtc`, `zacus`) or absolute path,
|
||||
- message mode (`-m`) or interactive mode,
|
||||
- provider auto-fallback (`copilot` -> `openai-codex` -> `openrouter`),
|
||||
- token sourcing from `gh auth token` at runtime only when `copilot` is selected.
|
||||
- `tools/ai/zeroclaw_stack_up.sh`
|
||||
- starts local gateway and local follow server,
|
||||
- reuses existing listeners when ports are already bound (prevents duplicate-start failures),
|
||||
- generates live follow dashboard at `http://127.0.0.1:8788/`,
|
||||
- dashboard includes live polling panels for `/conversations.jsonl` and `/gateway.log` (1s polling),
|
||||
- preserves direct raw links: `/conversations.jsonl` and `/gateway.log`,
|
||||
- writes `artifacts/zeroclaw/prometheus.yml` scrape config,
|
||||
- supports local Prometheus startup via `ZEROCLAW_PROM_MODE` (`off`, `auto`, `binary`, `docker`),
|
||||
- stores pair token in `artifacts/zeroclaw/pair_token.txt`.
|
||||
- `tools/ai/zeroclaw_stack_down.sh`
|
||||
- stops local gateway/follow processes,
|
||||
- stops local Prometheus process/container if managed by the stack,
|
||||
- confirms logs remain in `artifacts/zeroclaw/`.
|
||||
- `tools/ai/zeroclaw_webhook_send.sh`
|
||||
- requires `--allow-model-call` before any real webhook send,
|
||||
- supports `--repo-hint <hint>` metadata tagging,
|
||||
- appends enriched JSONL traces to `artifacts/zeroclaw/conversations.jsonl`.
|
||||
|
||||
### 4.3 Provider/cost strategy
|
||||
|
||||
Auto provider selection order in `zeroclaw_dual_chat.sh`:
|
||||
|
||||
1. explicit `ZEROCLAW_PROVIDER` override,
|
||||
2. `copilot` when `gh` auth is valid and Copilot billing endpoint is accessible,
|
||||
3. `openai-codex` when a ZeroClaw auth profile exists,
|
||||
4. `openrouter` when `OPENROUTER_API_KEY` is present.
|
||||
|
||||
Observed on current machine:
|
||||
|
||||
- GitHub API returned `404` for Copilot billing endpoint (no active Copilot subscription on this token), so fallback path is required for autonomous chat.
|
||||
|
||||
## 5) Operations Loop
|
||||
|
||||
1. Bootstrap configs and hardware probe.
|
||||
2. Run one focused prompt in `rtc`.
|
||||
3. Run one focused prompt in `zacus`.
|
||||
4. Apply patches/tests per repo.
|
||||
5. Open small PRs + issue links (one concern per PR).
|
||||
6. Repeat.
|
||||
|
||||
## 6) CI Workflow
|
||||
|
||||
Workflow:
|
||||
|
||||
- `.github/workflows/zeroclaw_dual_orchestrator.yml`
|
||||
|
||||
Behavior:
|
||||
|
||||
- path-filtered on orchestration scripts/spec files,
|
||||
- shellcheck scripts,
|
||||
- verify spec/todo files exist,
|
||||
- concurrency enabled to cancel stale runs on same ref.
|
||||
|
||||
## 7) External References (optimization decisions)
|
||||
|
||||
- GitHub Actions path filters and trigger controls:
|
||||
https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax
|
||||
- GitHub Actions concurrency control (cancel stale runs):
|
||||
https://docs.github.com/actions/using-jobs/using-concurrency
|
||||
- PlatformIO remote unit test runner and local/remote split strategy:
|
||||
https://docs.platformio.org/en/latest/plus/remote/unit-testing.html
|
||||
- PySerial port metadata usage (`serial.tools.list_ports`) for stable device targeting:
|
||||
https://pyserial.readthedocs.io/en/latest/tools.html
|
||||
|
||||
## 8) Live Follow Contract
|
||||
|
||||
Follow URL:
|
||||
|
||||
- `http://127.0.0.1:8788/` (dashboard)
|
||||
|
||||
Raw URLs:
|
||||
|
||||
- `http://127.0.0.1:8788/conversations.jsonl`
|
||||
- `http://127.0.0.1:8788/gateway.log`
|
||||
- `http://127.0.0.1:8788/prometheus.yml`
|
||||
|
||||
Conversation JSONL line schema (append-only):
|
||||
|
||||
- `ts` (ISO UTC)
|
||||
- `repo_hint` (`rtc`, `zacus`, or custom hint; default `unknown`)
|
||||
- `message`
|
||||
- `http_status`
|
||||
- `ok` (boolean)
|
||||
- `response_raw`
|
||||
|
||||
Compatibility rule:
|
||||
|
||||
- viewer tolerates legacy lines that only contain `ts`, `message`, `response_raw`.
|
||||
|
||||
Credit-protection rule:
|
||||
|
||||
- without `--allow-model-call`, `zeroclaw_webhook_send.sh` exits non-zero and does not send/write logs.
|
||||
|
||||
## 9) Prometheus Integration
|
||||
|
||||
Economical default:
|
||||
|
||||
- `ZEROCLAW_PROM_MODE=auto` (start only if local `prometheus` binary exists)
|
||||
|
||||
Optional modes:
|
||||
|
||||
- `ZEROCLAW_PROM_MODE=off` disables Prometheus startup
|
||||
- `ZEROCLAW_PROM_MODE=binary` requires local `prometheus` binary
|
||||
- `ZEROCLAW_PROM_MODE=docker` runs `prom/prometheus:latest` locally
|
||||
|
||||
Default local endpoint when running:
|
||||
|
||||
- `http://127.0.0.1:9090/targets`
|
||||
@@ -0,0 +1,36 @@
|
||||
# TODO: Dual Hardware Autonomy (RTC + Zacus)
|
||||
|
||||
Last updated: 2026-02-21
|
||||
|
||||
## Phase A: Local Baseline
|
||||
|
||||
- [ ] Run `tools/ai/zeroclaw_dual_bootstrap.sh` and capture hardware snapshot.
|
||||
- [ ] Validate `tools/ai/zeroclaw_dual_chat.sh rtc -m "<diagnostic prompt>"`.
|
||||
- [ ] Validate `tools/ai/zeroclaw_dual_chat.sh zacus -m "<diagnostic prompt>"`.
|
||||
- [ ] Record detected ports and map preferred role per board.
|
||||
|
||||
## Phase B: Repo Specs and PR Cadence
|
||||
|
||||
- [ ] Create/refresh one issue in `RTC_BL_PHONE` for ZeroClaw-assisted hardware loop.
|
||||
- [ ] Create/refresh one issue in `le-mystere-professeur-zacus` for ZeroClaw-assisted hardware loop.
|
||||
- [ ] Open one small PR per repo focused on one gate (build, tests, hardware smoke, docs).
|
||||
- [ ] Require code review pass before merge (`gh pr review --approve` only after checks).
|
||||
|
||||
## Phase C: Autonomy + Cost Optimization
|
||||
|
||||
- [ ] Keep prompts short, target one repo at a time.
|
||||
- [ ] Use provider auto-fallback (`copilot` -> `openai-codex` -> `openrouter`) to avoid dead sessions.
|
||||
- [ ] Add repo-level path filters in workflows to avoid expensive irrelevant runs.
|
||||
- [ ] Use `workflow_dispatch` for hardware-required jobs to avoid noisy CI failures.
|
||||
|
||||
## Phase D: Hardware Robustness
|
||||
|
||||
- [ ] Add serial-port resolver step before every upload/flash action.
|
||||
- [ ] Fail fast if no expected USB device is detected.
|
||||
- [ ] Archive logs per run for replayability (`artifacts/<timestamp>/...`).
|
||||
|
||||
## Exit Criteria
|
||||
|
||||
- [ ] Both repos can be targeted with one command (`rtc` or `zacus`) without workspace leakage.
|
||||
- [ ] Hardware discovery passes before action on connected boards.
|
||||
- [ ] At least one successful PR cycle completed per repo with this orchestration path.
|
||||
@@ -14,3 +14,11 @@ Specs complémentaires:
|
||||
|
||||
- `zeroclaw_dual_hw_orchestration_spec.md`: architecture d'orchestration ZeroClaw multi-repo + double matériel.
|
||||
- `zeroclaw_dual_hw_todo.md`: backlog opérationnel court terme pour autonomie contrôlée.
|
||||
|
||||
Synchronisation `spec_kit`:
|
||||
|
||||
- `specs/` (racine repo) et `ai-agentic-embedded-base/specs/` doivent rester alignés.
|
||||
- Après toute mise à jour, synchroniser avec:
|
||||
- `rsync -a --delete specs/ ai-agentic-embedded-base/specs/`
|
||||
- Vérifier l'absence d'écart avec:
|
||||
- `diff -ru ai-agentic-embedded-base/specs specs`
|
||||
|
||||
Reference in New Issue
Block a user