Remove obsolete files and documentation related to Git write operations and ESP-NOW contract
- Deleted SVG diagram for repository structure: `repo-map 3.svg` - Removed Git write operations implementation documentation: `GIT_WRITE_OPS_IMPLEMENTATION.md`, `QUICK_REF_GIT_WRITE_OPS.md`, `README_GIT_WRITE_OPS.md`, and `GIT_WRITE_OPS.md` - Deleted ESP-NOW contract documentation: `espnow_contract 3.md` - Removed YAML scene specifications: `scene_la_detect 3.yaml` and `scene_test_lab 3.yaml` - Deleted font file: `IBMPlexMono-Italic 3.ttf` - Cleared compiled Python cache files from test directory
This commit is contained in:
Clément SAILLANT
@@ -1,12 +0,0 @@
|
||||
|
||||
## [2026-02-26] In progress - bascule textes scene vers backend LovyanGFX
|
||||
|
||||
- Checkpoint securite:
|
||||
- `/tmp/zacus_checkpoint/20260226_110721_wip.patch`
|
||||
- `/tmp/zacus_checkpoint/20260226_110721_status.txt`
|
||||
- Demande: afficher tous les textes de scene via LovyanGFX (et non labels LVGL) pour eviter regressions d'affichage.
|
||||
- Plan d'execution:
|
||||
1) auditer le chemin rendu texte actuel (LVGL labels vs direct FX/LGFX)
|
||||
2) implementer un overlay texte LGFX pour toutes les scenes runtime
|
||||
3) desactiver/neutraliser les labels LVGL titre/sous-titre/symbole
|
||||
4) build + upload Freenove + verification serie
|
||||
@@ -1,233 +0,0 @@
|
||||
# Git Write Operations Implementation - Summary
|
||||
|
||||
## ✅ Implementation Complete
|
||||
|
||||
### Objective
|
||||
Save token credits by executing git write operations through shell scripts instead of agents, with:
|
||||
- Safe guards (require `ZACUS_GIT_ALLOW_WRITE=1`)
|
||||
- Confirmation prompts (skippable with `ZACUS_GIT_NO_CONFIRM=1`)
|
||||
- Evidence integration
|
||||
- Cockpit registry management
|
||||
|
||||
---
|
||||
|
||||
## 📦 Livrables
|
||||
|
||||
### 1. Implementation in agent_utils.sh
|
||||
**File**: `tools/dev/agent_utils.sh`
|
||||
|
||||
Added functions:
|
||||
```bash
|
||||
git_write_check() # Validates safeguards (env vars + confirmation)
|
||||
git_add() # Stage files (requires ZACUS_GIT_ALLOW_WRITE=1)
|
||||
git_commit() # Commit changes (requires ZACUS_GIT_ALLOW_WRITE=1)
|
||||
git_stash() # Stash working tree (requires ZACUS_GIT_ALLOW_WRITE=1)
|
||||
git_push() # Push to remote (requires ZACUS_GIT_ALLOW_WRITE=1)
|
||||
```
|
||||
|
||||
### 2. Implementation in cockpit.sh
|
||||
**File**: `tools/dev/cockpit.sh`
|
||||
|
||||
Extended `run_git()` function to support:
|
||||
- Read actions: status, diff, log, branch, show ✓ (existing)
|
||||
- Write actions: add, commit, stash, push ✓ (NEW)
|
||||
|
||||
All git actions dispatch through `cockpit.sh git <action> [args...]`
|
||||
|
||||
### 3. Cockpit Command Registry
|
||||
**File**: `tools/dev/cockpit_commands.yaml`
|
||||
|
||||
Added entries:
|
||||
```yaml
|
||||
- id: git-add # Stage files
|
||||
- id: git-commit # Commit staged changes
|
||||
- id: git-stash # Stash working tree
|
||||
- id: git-push # Push to remote
|
||||
```
|
||||
|
||||
Also updated main `git` entry to list all supported actions (read + write)
|
||||
|
||||
### 4. Generated Documentation
|
||||
**File**: `docs/_generated/COCKPIT_COMMANDS.md`
|
||||
|
||||
Auto-generated from cockpit_commands.yaml:
|
||||
- Full command registry table (ID, Description, Entrypoint, Args, Runbook, Evidence)
|
||||
- Includes all 4 new git write commands
|
||||
- Runbook references to Git Operations Policy
|
||||
|
||||
### 5. Core Documentation Updates
|
||||
**File**: `docs/TEST_SCRIPT_COORDINATOR.md`
|
||||
|
||||
Enhanced "Git Operations Policy" section with:
|
||||
- Clear separation: read vs. write operations
|
||||
- Safeguard explanation (`ZACUS_GIT_ALLOW_WRITE=1`)
|
||||
- Confirmation prompt details
|
||||
- Usage examples for common scenarios
|
||||
- Script integration patterns
|
||||
|
||||
### 6. Complete Git Write Operations Guide
|
||||
**File**: `docs/GIT_WRITE_OPS.md` (NEW)
|
||||
|
||||
Comprehensive guide covering:
|
||||
- Quick start (3 steps)
|
||||
- Architecture diagram
|
||||
- All files modified
|
||||
- Environment variables reference
|
||||
- 3 usage patterns (interactive, CI/CD, evidence)
|
||||
- Safeguards & error handling
|
||||
- Evidence integration details
|
||||
- 5 use cases with code examples
|
||||
- Testing instructions
|
||||
- Limitations & design notes
|
||||
- Token credit savings benefits
|
||||
- Troubleshooting guide
|
||||
|
||||
### 7. Usage Examples Script
|
||||
**File**: `tools/dev/examples_git_write_ops.sh` (NEW)
|
||||
|
||||
8 runnable examples:
|
||||
1. Stage files with git add
|
||||
2. Commit with confirmation prompt (interactive)
|
||||
3. Commit silently for CI/CD
|
||||
4. Stash changes
|
||||
5. Push to remote
|
||||
6. Git operations with evidence tracking
|
||||
7. Error case - missing ZACUS_GIT_ALLOW_WRITE
|
||||
8. Release automation pattern
|
||||
|
||||
---
|
||||
|
||||
## 🔧 How It Works
|
||||
|
||||
### Safeguards
|
||||
```
|
||||
User wants to run: ./tools/dev/cockpit.sh git add .
|
||||
↓
|
||||
run_git() dispatches to git_add()
|
||||
↓
|
||||
git_write_check() validates:
|
||||
├─ ZACUS_GIT_ALLOW_WRITE=1 ? (fail if not)
|
||||
└─ ZACUS_GIT_NO_CONFIRM=1 ? (skip prompt if yes)
|
||||
↓
|
||||
If confirmation needed: prompt user
|
||||
↓
|
||||
git_cmd add . (records in evidence, executes)
|
||||
```
|
||||
|
||||
### Evidence Logging
|
||||
```
|
||||
When evidence_init() is called:
|
||||
EVIDENCE_COMMANDS = artifacts/<phase>/<timestamp>/commands.txt
|
||||
|
||||
Then git_cmd() automatically appends to EVIDENCE_COMMANDS:
|
||||
git add .
|
||||
git commit -m "message"
|
||||
git push origin main
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Feature Matrix
|
||||
|
||||
| Feature | Read Ops | Write Ops |
|
||||
|---------|----------|-----------|
|
||||
| Environment var required | No | `ZACUS_GIT_ALLOW_WRITE=1` |
|
||||
| Confirmation prompt | No | Yes (unless `ZACUS_GIT_NO_CONFIRM=1`) |
|
||||
| Logged in evidence | Yes | Yes |
|
||||
| Cockpit.sh supported | Yes | Yes |
|
||||
| Registry documented | Yes | Yes |
|
||||
| Examples provided | Yes | Yes |
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Usage Quick Reference
|
||||
|
||||
### Read operations (no restrictions)
|
||||
```bash
|
||||
./tools/dev/cockpit.sh git status
|
||||
./tools/dev/cockpit.sh git diff
|
||||
./tools/dev/cockpit.sh git log 10
|
||||
./tools/dev/cockpit.sh git branch
|
||||
./tools/dev/cockpit.sh git show HEAD
|
||||
```
|
||||
|
||||
### Write operations (require ZACUS_GIT_ALLOW_WRITE=1)
|
||||
```bash
|
||||
export ZACUS_GIT_ALLOW_WRITE=1
|
||||
|
||||
# Interactive (with confirmation)
|
||||
./tools/dev/cockpit.sh git add src/
|
||||
./tools/dev/cockpit.sh git commit -m "My changes"
|
||||
|
||||
# Automated (skip prompts)
|
||||
export ZACUS_GIT_NO_CONFIRM=1
|
||||
./tools/dev/cockpit.sh git commit -m "Auto commit"
|
||||
./tools/dev/cockpit.sh git push origin main
|
||||
```
|
||||
|
||||
### In scripts with evidence
|
||||
```bash
|
||||
source tools/dev/agent_utils.sh
|
||||
evidence_init "my_phase"
|
||||
|
||||
export ZACUS_GIT_ALLOW_WRITE=1
|
||||
export ZACUS_GIT_NO_CONFIRM=1
|
||||
|
||||
git_add src/
|
||||
git_commit -m "staged changes"
|
||||
|
||||
# Verify logged commands
|
||||
cat "$EVIDENCE_COMMANDS"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📋 Verification Checklist
|
||||
|
||||
- ✅ agent_utils.sh: git_add(), git_commit(), git_stash(), git_push() implemented
|
||||
- ✅ agent_utils.sh: git_write_check() validates safeguards
|
||||
- ✅ cockpit.sh: run_git() extended with write actions
|
||||
- ✅ cockpit_commands.yaml: 4 new git-* entries added
|
||||
- ✅ docs/_generated/COCKPIT_COMMANDS.md: Auto-regenerated successfully
|
||||
- ✅ docs/TEST_SCRIPT_COORDINATOR.md: Git Operations Policy section updated
|
||||
- ✅ docs/GIT_WRITE_OPS.md: Complete guide created
|
||||
- ✅ examples_git_write_ops.sh: 8 usage examples provided
|
||||
- ✅ cockpit_registry.py: Fixed YAML parsing (handles multiline content)
|
||||
- ✅ gen_cockpit_docs.py: Python 3.8+ compatible (uses List[str] not list[str])
|
||||
- ✅ PyYAML: Installed in .venv for robust YAML parsing
|
||||
- ✅ All functions tested and verified working
|
||||
|
||||
---
|
||||
|
||||
## 💾 Token Credit Savings
|
||||
|
||||
By executing git operations via cockpit shell scripts instead of agents:
|
||||
|
||||
| Operation | Without Script | Via Cockpit |
|
||||
|-----------|----------------|------------|
|
||||
| git add + commit | ~4-5 agent calls | 1 shell command |
|
||||
| Release: tag + push | ~6-8 agent calls | 1-2 shell commands |
|
||||
| Per operation | 50-200 tokens | ~5-10 tokens |
|
||||
|
||||
**Estimated savings**: 80-90% reduction in tokens for git workflows
|
||||
|
||||
---
|
||||
|
||||
## 🔗 References
|
||||
|
||||
- **Main guide**: [docs/GIT_WRITE_OPS.md](docs/GIT_WRITE_OPS.md)
|
||||
- **Policy**: [docs/TEST_SCRIPT_COORDINATOR.md#git-operations-policy](docs/TEST_SCRIPT_COORDINATOR.md#git-operations-policy)
|
||||
- **Command registry**: [docs/_generated/COCKPIT_COMMANDS.md](docs/_generated/COCKPIT_COMMANDS.md)
|
||||
- **Implementation**: `tools/dev/agent_utils.sh`, `tools/dev/cockpit.sh`
|
||||
- **Examples**: `tools/dev/examples_git_write_ops.sh`
|
||||
|
||||
---
|
||||
|
||||
## Next Steps (Optional Enhancements)
|
||||
|
||||
- [ ] Add git branch/tag creation commands
|
||||
- [ ] Git merge/rebase operations with safeguards
|
||||
- [ ] Automated diff preview before commit
|
||||
- [ ] Git workflow templates (release, hotfix, feature)
|
||||
- [ ] Integration with CI/CD systems (GitHub Actions, etc.)
|
||||
|
||||
@@ -1,121 +0,0 @@
|
||||
# Quick Reference: Git Write Ops via Cockpit
|
||||
|
||||
## 🎯 One-Liner Commands
|
||||
|
||||
### Basic Operations
|
||||
|
||||
```bash
|
||||
# Enable write mode
|
||||
export ZACUS_GIT_ALLOW_WRITE=1
|
||||
|
||||
# Stage all changes
|
||||
./tools/dev/cockpit.sh git add .
|
||||
|
||||
# Commit with message
|
||||
./tools/dev/cockpit.sh git commit -m "Your commit message"
|
||||
|
||||
# Stash changes
|
||||
./tools/dev/cockpit.sh git stash save "description"
|
||||
|
||||
# Push to remote
|
||||
./tools/dev/cockpit.sh git push origin main
|
||||
```
|
||||
|
||||
### CI/CD Automation (no prompts)
|
||||
|
||||
```bash
|
||||
export ZACUS_GIT_ALLOW_WRITE=1
|
||||
export ZACUS_GIT_NO_CONFIRM=1
|
||||
|
||||
./tools/dev/cockpit.sh git add .
|
||||
./tools/dev/cockpit.sh git commit -m "Auto-commit"
|
||||
./tools/dev/cockpit.sh git push origin main
|
||||
```
|
||||
|
||||
### With Evidence Tracking
|
||||
|
||||
```bash
|
||||
source tools/dev/agent_utils.sh
|
||||
evidence_init "my_phase"
|
||||
|
||||
export ZACUS_GIT_ALLOW_WRITE=1
|
||||
export ZACUS_GIT_NO_CONFIRM=1
|
||||
|
||||
git_add .
|
||||
git_commit -m "changes"
|
||||
|
||||
# All logged to: $EVIDENCE_COMMANDS
|
||||
```
|
||||
|
||||
## 📖 Read Operations (no guards needed)
|
||||
|
||||
```bash
|
||||
./tools/dev/cockpit.sh git status
|
||||
./tools/dev/cockpit.sh git diff
|
||||
./tools/dev/cockpit.sh git log 20
|
||||
./tools/dev/cockpit.sh git branch
|
||||
./tools/dev/cockpit.sh git show HEAD
|
||||
```
|
||||
|
||||
## 🔒 Safeguard Errors
|
||||
|
||||
```bash
|
||||
# Error: Missing ZACUS_GIT_ALLOW_WRITE
|
||||
$ ./tools/dev/cockpit.sh git add .
|
||||
[AGENT][FAIL] Git write operation requires ZACUS_GIT_ALLOW_WRITE=1
|
||||
|
||||
# Solution:
|
||||
export ZACUS_GIT_ALLOW_WRITE=1
|
||||
./tools/dev/cockpit.sh git add .
|
||||
```
|
||||
|
||||
## 🧪 Test Examples
|
||||
|
||||
```bash
|
||||
./tools/dev/examples_git_write_ops.sh 1 # Stage files
|
||||
./tools/dev/examples_git_write_ops.sh 2 # Commit interactive
|
||||
./tools/dev/examples_git_write_ops.sh 3 # Commit silent
|
||||
./tools/dev/examples_git_write_ops.sh 4 # Stash
|
||||
./tools/dev/examples_git_write_ops.sh 5 # Push
|
||||
./tools/dev/examples_git_write_ops.sh 6 # With evidence
|
||||
./tools/dev/examples_git_write_ops.sh 7 # Error demo
|
||||
./tools/dev/examples_git_write_ops.sh 8 # Release pattern
|
||||
```
|
||||
|
||||
## 📚 Full Documentation
|
||||
|
||||
- **Main Guide**: `docs/GIT_WRITE_OPS.md`
|
||||
- **Policy**: `docs/TEST_SCRIPT_COORDINATOR.md#git-operations-policy`
|
||||
- **Registry**: `docs/_generated/COCKPIT_COMMANDS.md`
|
||||
- **Implementation**: `GIT_WRITE_OPS_IMPLEMENTATION.md`
|
||||
|
||||
## 🚀 Key Points
|
||||
|
||||
1. **Always set**: `export ZACUS_GIT_ALLOW_WRITE=1` for write ops
|
||||
2. **Get prompted**: By default (unless `ZACUS_GIT_NO_CONFIRM=1`)
|
||||
3. **Check status**: `./tools/dev/cockpit.sh git status`
|
||||
4. **In scripts**: Use `git_add()`, `git_commit()`, etc. from `agent_utils.sh`
|
||||
5. **Evidence**: All commands auto-logged when evidence is initialized
|
||||
|
||||
## 💡 Pro Tips
|
||||
|
||||
- Use `git status` before committing to verify changes
|
||||
- Test with `ZACUS_GIT_NO_CONFIRM=1` in isolated branch first
|
||||
- Review `docs/GIT_WRITE_OPS.md` for full examples
|
||||
- Run `examples_git_write_ops.sh` to see all patterns
|
||||
- Check `EVIDENCE_COMMANDS` file after operations
|
||||
|
||||
## 🔗 Related Commands
|
||||
|
||||
```bash
|
||||
# Other cockpit commands
|
||||
./tools/dev/cockpit.sh rc # RC live gate
|
||||
./tools/dev/cockpit.sh flash # Flash firmware
|
||||
./tools/dev/cockpit.sh build # Build all
|
||||
./tools/dev/cockpit.sh ports # Watch ports
|
||||
|
||||
# Git read operations
|
||||
./tools/dev/cockpit.sh git log 10
|
||||
./tools/dev/cockpit.sh git diff HEAD~1
|
||||
./tools/dev/cockpit.sh git branch -vv
|
||||
```
|
||||
@@ -1,395 +0,0 @@
|
||||
# 🚀 Git Write Operations via Cockpit - COMPLETED
|
||||
|
||||
## Status: ✅ FULLY IMPLEMENTED & TESTED
|
||||
|
||||
All git write operations (add, commit, stash, push) are now available via `cockpit.sh` with safeguards and evidence integration.
|
||||
|
||||
---
|
||||
|
||||
## 📋 What's New
|
||||
|
||||
### New Features
|
||||
- **git add** - Stage files via `./tools/dev/cockpit.sh git add <pathspec>`
|
||||
- **git commit** - Commit via `./tools/dev/cockpit.sh git commit -m "<msg>"`
|
||||
- **git stash** - Stash changes via `./tools/dev/cockpit.sh git stash [action]`
|
||||
- **git push** - Push commits via `./tools/dev/cockpit.sh git push [remote] [branch]`
|
||||
|
||||
### Safeguards
|
||||
- **Required**: `ZACUS_GIT_ALLOW_WRITE=1` for all write operations
|
||||
- **Confirmation prompt**: Shown by default (skip with `ZACUS_GIT_NO_CONFIRM=1`)
|
||||
- **Evidence integration**: All commands logged to `commands.txt`
|
||||
|
||||
### Token Credit Savings
|
||||
- **Before**: 4-8 agent calls for git operations (200-400+ tokens)
|
||||
- **After**: 1-2 shell commands via cockpit (5-10 tokens)
|
||||
- **Savings**: ~95% reduction in token usage
|
||||
|
||||
---
|
||||
|
||||
## 📦 Deliverables (7 items)
|
||||
|
||||
### 1️⃣ Core Implementation
|
||||
**File**: `tools/dev/agent_utils.sh`
|
||||
|
||||
Added functions:
|
||||
```bash
|
||||
git_write_check() # Guard: requires ZACUS_GIT_ALLOW_WRITE=1 + confirmation
|
||||
git_add(pathspec) # Stage files
|
||||
git_commit(-m "msg") # Commit changes
|
||||
git_stash([action]) # Stash working tree
|
||||
git_push([remote] [br]) # Push to remote
|
||||
```
|
||||
|
||||
**Verification**: ✅ All functions tested and working
|
||||
|
||||
---
|
||||
|
||||
### 2️⃣ Cockpit Dispatcher Update
|
||||
**File**: `tools/dev/cockpit.sh`
|
||||
|
||||
Extended `run_git()` function to handle:
|
||||
- Read actions (status, diff, log, branch, show) - existing ✓
|
||||
- Write actions (add, commit, stash, push) - NEW ✓
|
||||
|
||||
Uses same guard pattern for all write operations.
|
||||
|
||||
**Verification**: ✅ Dispatcher properly routes all actions
|
||||
|
||||
---
|
||||
|
||||
### 3️⃣ Command Registry
|
||||
**File**: `tools/dev/cockpit_commands.yaml`
|
||||
|
||||
Added entries:
|
||||
```yaml
|
||||
- id: git-add
|
||||
- id: git-commit
|
||||
- id: git-stash
|
||||
- id: git-push
|
||||
```
|
||||
|
||||
Each entry includes: description, args, runbook reference, safety notes.
|
||||
|
||||
**Verification**: ✅ Registry validated and parsed
|
||||
|
||||
---
|
||||
|
||||
### 4️⃣ Generated Documentation
|
||||
**File**: `docs/_generated/COCKPIT_COMMANDS.md`
|
||||
|
||||
Auto-generated table with:
|
||||
- 18 total cockpit commands (5 new git entries)
|
||||
- ID | Description | Entrypoint | Args | Runbook | Evidence
|
||||
- All git commands with safeguard notes
|
||||
|
||||
**Verification**: ✅ Successfully generated from YAML registry
|
||||
|
||||
---
|
||||
|
||||
### 5️⃣ Policy Documentation
|
||||
**File**: `docs/TEST_SCRIPT_COORDINATOR.md`
|
||||
|
||||
Updated "Git Operations Policy" section with:
|
||||
- Clear read vs. write command lists
|
||||
- Safeguard explanation (`ZACUS_GIT_ALLOW_WRITE=1`)
|
||||
- Confirmation flow description
|
||||
- Usage examples:
|
||||
- Interactive (with confirmation)
|
||||
- Silent (for CI/CD)
|
||||
- With evidence tracking
|
||||
- Script integration patterns
|
||||
|
||||
**Verification**: ✅ Section expanded and documented
|
||||
|
||||
---
|
||||
|
||||
### 6️⃣ Complete Usage Guide
|
||||
**File**: `docs/GIT_WRITE_OPS.md` (8.9 KB)
|
||||
|
||||
Comprehensive manual covering:
|
||||
- Quick start (3 steps)
|
||||
- Architecture diagram
|
||||
- Implementation details
|
||||
- 4 environment variables reference
|
||||
- 3 usage patterns (interactive, CI/CD, evidence)
|
||||
- Safeguards & error handling with examples
|
||||
- Evidence integration workflow
|
||||
- 5 real-world use cases with code
|
||||
- Testing instructions
|
||||
- Design notes & limitations
|
||||
- Token credit savings calculation
|
||||
- Troubleshooting guide
|
||||
|
||||
**Verification**: ✅ Complete guide created
|
||||
|
||||
---
|
||||
|
||||
### 7️⃣ Usage Examples Script
|
||||
**File**: `tools/dev/examples_git_write_ops.sh` (5.9 KB)
|
||||
|
||||
8 runnable examples:
|
||||
```bash
|
||||
./tools/dev/examples_git_write_ops.sh 1 # Stage files
|
||||
./tools/dev/examples_git_write_ops.sh 2 # Commit with prompt
|
||||
./tools/dev/examples_git_write_ops.sh 3 # Commit silently
|
||||
./tools/dev/examples_git_write_ops.sh 4 # Stash changes
|
||||
./tools/dev/examples_git_write_ops.sh 5 # Push to remote
|
||||
./tools/dev/examples_git_write_ops.sh 6 # With evidence tracking
|
||||
./tools/dev/examples_git_write_ops.sh 7 # Error case
|
||||
./tools/dev/examples_git_write_ops.sh 8 # Release automation
|
||||
```
|
||||
|
||||
Each example is documented and runnable.
|
||||
|
||||
**Verification**: ✅ Script created and ready to run
|
||||
|
||||
### 8️⃣ Implementation Summary
|
||||
**File**: `GIT_WRITE_OPS_IMPLEMENTATION.md`
|
||||
|
||||
Summary document covering:
|
||||
- Implementation objectives
|
||||
- Complete deliverables checklist
|
||||
- Architecture explanation
|
||||
- Feature matrix
|
||||
- Quick reference
|
||||
- Verification checklist
|
||||
- Token credit savings
|
||||
- Next steps for enhancement
|
||||
|
||||
**Verification**: ✅ Summary document complete
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Quick Verification
|
||||
|
||||
All components verified working:
|
||||
|
||||
```bash
|
||||
✅ Helper functions loaded
|
||||
✅ All git write functions exist
|
||||
✅ cockpit.sh has git dispatcher
|
||||
✅ Registry has 5 git entries
|
||||
✅ Documentation generated
|
||||
✅ Guide created
|
||||
✅ Examples provided
|
||||
✅ PyYAML installed for robust YAML parsing
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Key Features
|
||||
|
||||
### 1. Safeguarded Operations
|
||||
```bash
|
||||
# Fails without ZACUS_GIT_ALLOW_WRITE=1
|
||||
$ ./tools/dev/cockpit.sh git add .
|
||||
[AGENT][FAIL] Git write operation requires ZACUS_GIT_ALLOW_WRITE=1
|
||||
|
||||
# Works with safeguard
|
||||
$ export ZACUS_GIT_ALLOW_WRITE=1
|
||||
$ ./tools/dev/cockpit.sh git add .
|
||||
[WARN] git add .
|
||||
Continue? (y/N): _
|
||||
```
|
||||
|
||||
### 2. CI/CD Automation
|
||||
```bash
|
||||
export ZACUS_GIT_ALLOW_WRITE=1
|
||||
export ZACUS_GIT_NO_CONFIRM=1
|
||||
|
||||
./tools/dev/cockpit.sh git commit -m "automated commit"
|
||||
./tools/dev/cockpit.sh git push origin main
|
||||
```
|
||||
|
||||
### 3. Evidence Integration
|
||||
```bash
|
||||
source tools/dev/agent_utils.sh
|
||||
evidence_init "release"
|
||||
|
||||
git_add src/
|
||||
git_commit -m "release changes"
|
||||
git_push origin main
|
||||
|
||||
# All logged to: artifacts/release/<timestamp>/commands.txt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Usage Statistics
|
||||
|
||||
### File Changes
|
||||
- Modified: 3 files (agent_utils.sh, cockpit.sh, cockpit_commands.yaml, TEST_SCRIPT_COORDINATOR.md)
|
||||
- Created: 4 files (GIT_WRITE_OPS.md, examples_git_write_ops.sh, GIT_WRITE_OPS_IMPLEMENTATION.md, this README)
|
||||
- Generated: 1 file (docs/_generated/COCKPIT_COMMANDS.md)
|
||||
|
||||
### Code Lines
|
||||
- agent_utils.sh: +65 lines (git write operations)
|
||||
- cockpit.sh: +15 lines (extended dispatcher)
|
||||
- cockpit_commands.yaml: +20 lines (new entries + descriptions)
|
||||
- Documentation: 1000+ lines (guides + examples)
|
||||
|
||||
### Dependencies
|
||||
- PyYAML: Installed (robust YAML parsing)
|
||||
- Python 3.8+: Compatible (uses List[str] not list[str])
|
||||
- Shell: Standard bash (no new dependencies)
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Getting Started
|
||||
|
||||
### 1. Read the Guide
|
||||
```bash
|
||||
cat docs/GIT_WRITE_OPS.md
|
||||
```
|
||||
|
||||
### 2. Try an Example
|
||||
```bash
|
||||
./tools/dev/examples_git_write_ops.sh 1
|
||||
```
|
||||
|
||||
### 3. Use in Your Script
|
||||
```bash
|
||||
export ZACUS_GIT_ALLOW_WRITE=1
|
||||
export ZACUS_GIT_NO_CONFIRM=1
|
||||
./tools/dev/cockpit.sh git add .
|
||||
./tools/dev/cockpit.sh git commit -m "changes"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📖 Documentation Map
|
||||
|
||||
```
|
||||
docs/
|
||||
├── GIT_WRITE_OPS.md ← Start here (usage guide)
|
||||
├── TEST_SCRIPT_COORDINATOR.md ← Policy section updated
|
||||
└── _generated/
|
||||
└── COCKPIT_COMMANDS.md ← Auto-generated registry table
|
||||
|
||||
tools/dev/
|
||||
├── agent_utils.sh ← Git write functions
|
||||
├── cockpit.sh ← Dispatcher updated
|
||||
├── cockpit_commands.yaml ← Registry with new entries
|
||||
├── examples_git_write_ops.sh ← 8 runnable examples
|
||||
├── cockpit_registry.py ← Fixed YAML parser
|
||||
└── gen_cockpit_docs.py ← Doc generator (Python 3.8+)
|
||||
|
||||
Root:
|
||||
└── GIT_WRITE_OPS_IMPLEMENTATION.md ← Full implementation summary
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ Acceptance Criteria
|
||||
|
||||
All requirements met:
|
||||
|
||||
- ✅ **Git write actions**: add, commit, stash, push implemented
|
||||
- ✅ **Safeguards**: Require `ZACUS_GIT_ALLOW_WRITE=1`
|
||||
- ✅ **Confirmation prompts**: Shown by default, skippable
|
||||
- ✅ **Evidence integration**: Commands logged to evidence
|
||||
- ✅ **Cockpit integration**: All via `cockpit.sh` dispatcher
|
||||
- ✅ **Registry updated**: cockpit_commands.yaml with new entries
|
||||
- ✅ **Docs generated**: Automated from registry
|
||||
- ✅ **Documentation**: Complete guide + examples
|
||||
- ✅ **Testing**: Smoke tests passed
|
||||
- ✅ **Token savings**: ~95% reduction for git workflows
|
||||
|
||||
---
|
||||
|
||||
## 🔗 Related Commands
|
||||
|
||||
### Cockpit Git Commands
|
||||
```bash
|
||||
./tools/dev/cockpit.sh git status # Read
|
||||
./tools/dev/cockpit.sh git diff # Read
|
||||
./tools/dev/cockpit.sh git log 10 # Read
|
||||
./tools/dev/cockpit.sh git branch # Read
|
||||
./tools/dev/cockpit.sh git show HEAD # Read
|
||||
./tools/dev/cockpit.sh git add . # Write (needs safeguard)
|
||||
./tools/dev/cockpit.sh git commit -m "" # Write (needs safeguard)
|
||||
./tools/dev/cockpit.sh git stash # Write (needs safeguard)
|
||||
./tools/dev/cockpit.sh git push origin # Write (needs safeguard)
|
||||
```
|
||||
|
||||
### Other Cockpit Commands
|
||||
```bash
|
||||
./tools/dev/cockpit.sh rc # RC live gate
|
||||
./tools/dev/cockpit.sh flash # Flash firmware
|
||||
./tools/dev/cockpit.sh build # Build all
|
||||
./tools/dev/cockpit.sh audit # Full audit
|
||||
...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💡 Design Principles
|
||||
|
||||
1. **Save tokens**: Shell scripts instead of agent calls
|
||||
2. **Safe by default**: Guards prevent accidental modifications
|
||||
3. **Auditable**: All operations logged to evidence
|
||||
4. **Automated**: CI/CD friendly with bypass options
|
||||
5. **Documented**: Complete guides and examples
|
||||
6. **Testable**: Smoke tests + usage examples
|
||||
7. **Integrated**: Single cockpit.sh dispatcher
|
||||
8. **Extensible**: Easy to add more git commands
|
||||
|
||||
---
|
||||
|
||||
## 🎓 Learning Resources
|
||||
|
||||
### For Users
|
||||
- Start: `docs/GIT_WRITE_OPS.md`
|
||||
- Examples: `./tools/dev/examples_git_write_ops.sh`
|
||||
- Policy: `docs/TEST_SCRIPT_COORDINATOR.md`
|
||||
|
||||
### For Developers
|
||||
- Implementation: `tools/dev/agent_utils.sh` (git functions)
|
||||
- Dispatcher: `tools/dev/cockpit.sh` (run_git function)
|
||||
- Registry: `tools/dev/cockpit_commands.yaml` (metadata)
|
||||
- Summary: `GIT_WRITE_OPS_IMPLEMENTATION.md`
|
||||
|
||||
---
|
||||
|
||||
## 🐛 Debugging
|
||||
|
||||
### "Git write operation requires ZACUS_GIT_ALLOW_WRITE=1"
|
||||
→ Set: `export ZACUS_GIT_ALLOW_WRITE=1`
|
||||
|
||||
### "Cancelled by user"
|
||||
→ Confirm with `y` or set: `export ZACUS_GIT_NO_CONFIRM=1`
|
||||
|
||||
### "Command not found" for git_add, etc.
|
||||
→ Source agent_utils: `source tools/dev/agent_utils.sh`
|
||||
|
||||
### Check registry loading
|
||||
→ Run: `python3 tools/dev/gen_cockpit_docs.py`
|
||||
|
||||
---
|
||||
|
||||
## 📝 Notes
|
||||
|
||||
- All git write operations require explicit `ZACUS_GIT_ALLOW_WRITE=1` for safety
|
||||
- Confirmation prompts are shown unless suppressed for CI/CD
|
||||
- All operations are recorded in evidence when evidence tracking is initialized
|
||||
- PyYAML is installed for robust YAML parsing (fallback simple parser available)
|
||||
- Python 3.8+ compatibility ensured (using `List[str]` instead of `list[str]`)
|
||||
|
||||
---
|
||||
|
||||
## 🎉 Summary
|
||||
|
||||
Git write operations are now available via cockpit.sh with:
|
||||
- **Full safeguards** (requires explicit environment variables)
|
||||
- **Evidence integration** (all commands logged)
|
||||
- **Token savings** (~95% reduction)
|
||||
- **Complete documentation** (guides + examples)
|
||||
- **Cockpit integration** (single entry point)
|
||||
|
||||
Ready for production use! 🚀
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2026-02-16
|
||||
**Status**: ✅ COMPLETE & TESTED
|
||||
**Ready for**: Production, CI/CD, Evidence-tracked scripts
|
||||
@@ -1,57 +0,0 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="680" viewBox="0 0 1200 680" role="img" aria-labelledby="title desc">
|
||||
<title id="title">Le Mystère du Professeur Zacus - Vue d'ensemble du dépôt</title>
|
||||
<desc id="desc">Schéma des trois piliers du dépôt: Kit Maître du jeu, Printables et Hardware.</desc>
|
||||
<defs>
|
||||
<style>
|
||||
.bg{fill:#f7f7f7}
|
||||
.panel{fill:#fff;stroke:#222;stroke-width:2}
|
||||
.h{font:700 32px 'Segoe UI',Arial,sans-serif;fill:#111}
|
||||
.t{font:600 22px 'Segoe UI',Arial,sans-serif;fill:#111}
|
||||
.s{font:400 18px 'Segoe UI',Arial,sans-serif;fill:#333}
|
||||
.cap{font:700 20px 'Segoe UI',Arial,sans-serif;fill:#111}
|
||||
.line{stroke:#222;stroke-width:2}
|
||||
</style>
|
||||
</defs>
|
||||
|
||||
<rect class="bg" x="0" y="0" width="1200" height="680"/>
|
||||
|
||||
<text class="h" x="600" y="62" text-anchor="middle">Le Mystère du Professeur Zacus</text>
|
||||
<text class="s" x="600" y="92" text-anchor="middle">Structure actuelle du dépôt</text>
|
||||
|
||||
<rect class="panel" x="70" y="150" rx="12" ry="12" width="320" height="430"/>
|
||||
<text class="t" x="230" y="195" text-anchor="middle">Kit Maître du jeu</text>
|
||||
<text class="s" x="95" y="240">• script minute-par-minute</text>
|
||||
<text class="s" x="95" y="272">• solution complète</text>
|
||||
<text class="s" x="95" y="304">• checklist matériel</text>
|
||||
<text class="s" x="95" y="336">• distribution des rôles</text>
|
||||
<text class="s" x="95" y="368">• guide anti-chaos</text>
|
||||
<text class="s" x="95" y="400">• stations modulaires</text>
|
||||
<text class="s" x="95" y="446">Path: kit-maitre-du-jeu/</text>
|
||||
|
||||
<rect class="panel" x="440" y="150" rx="12" ry="12" width="320" height="430"/>
|
||||
<text class="t" x="600" y="195" text-anchor="middle">Printables</text>
|
||||
<text class="s" x="465" y="240">• invitations</text>
|
||||
<text class="s" x="465" y="272">• cartes / feuille d'enquête</text>
|
||||
<text class="s" x="465" y="304">• badges / règles 1 page</text>
|
||||
<text class="s" x="465" y="336">• ordre d'impression</text>
|
||||
<text class="s" x="465" y="384">Sous-structure:</text>
|
||||
<text class="s" x="465" y="416"> - src/</text>
|
||||
<text class="s" x="465" y="448"> - export/pdf/</text>
|
||||
<text class="s" x="465" y="480"> - export/png/</text>
|
||||
<text class="s" x="465" y="526">Path: printables/</text>
|
||||
|
||||
<rect class="panel" x="810" y="150" rx="12" ry="12" width="320" height="430"/>
|
||||
<text class="t" x="970" y="195" text-anchor="middle">Hardware (optionnel)</text>
|
||||
<text class="s" x="835" y="240">• BOM</text>
|
||||
<text class="s" x="835" y="272">• câblage</text>
|
||||
<text class="s" x="835" y="304">• firmware Arduino / ESP32</text>
|
||||
<text class="s" x="835" y="336">• boîtier</text>
|
||||
<text class="s" x="835" y="384">Firmware ESP32:</text>
|
||||
<text class="s" x="835" y="416"> U_LOCK → U-SON → MP3</text>
|
||||
<text class="s" x="835" y="462">Path: hardware/</text>
|
||||
|
||||
<line class="line" x1="390" y1="365" x2="440" y2="365"/>
|
||||
<line class="line" x1="760" y1="365" x2="810" y2="365"/>
|
||||
|
||||
<text class="cap" x="600" y="635" text-anchor="middle">Objectif: documentation cohérente, livrables imprimables et firmware stable</text>
|
||||
</svg>
|
||||
|
Before Width: | Height: | Size: 3.1 KiB |
Reference in New Issue
Block a user