2026-05-05 22:37:23 +02:00
1 changed files with 219 additions and 0 deletions
--- a/documentation/MISTRAL-AUTONOMOUS-PATTERN.md
+++ b/documentation/MISTRAL-AUTONOMOUS-PATTERN.md
@@ -0,0 +1,219 @@
+# Mistral Vibe Autonomous Pattern
+
+**Document ID:** MISTRAL-AUTONOMOUS-PATTERN  
+**Date:** 2026-05-05  
+**Status:** Active  
+**Author:** Mistral Vibe (batch10-task-mistral-pattern-doc)  
+**Audience:** Project contributors, future trainers
+
+---
+
+## 1. What you'll see
+
+PRs authored by "Gabriel Radureau" with commit messages ending in "Mistral Vibe" references. PR titles start with gitmoji. Branch names follow `vibe/<slug>` pattern.
+
+| PR | Date | Title | Branch | Status |
+|----|------|-------|--------|--------|
+| #67 | 2026-05-05 | :memo: docs: email infrastructure | `vibe/batch4-task-a-email-infra` | Merged |
+| #74 | 2026-05-05 | :robot: feat: BDD Mailpit helper | `vibe/batch5-task-b-bdd-mailpit` | Merged |
+| #75 | 2026-05-05 | :elephant: feat: magic_link_tokens table | `vibe/batch5-task-c-db-magic-link` | Merged |
+| #76 | 2026-05-05 | :rocket: feat: magic link handlers | `vibe/batch5-task-d-handlers` | Merged |
+| #77 | 2026-05-05 | :test_tube: test: magic link BDD | `vibe/batch5-task-e-bdd` | Merged |
+
+---
+
+## 2. The pattern (high-level)
+
+```
+Operator Brief → Worktree Setup → Worker Execution → PR Lifecycle → Merge
+```
+
+### 2.1 Operator brief
+Human or trainer (Claude) writes a `CONTEXT.md` brief in a workspace under `~/Work/Vibe/workspaces/<slug>/`. The brief contains:
+- Mission statement
+- Goal and constraints
+- Process instructions
+- Hard rules
+- Specification
+
+### 2.2 Worktree setup
+A `vibe-workspace.sh --worktree` script creates an isolated git worktree:
+- Branches from current `origin/main`
+- Creates branch `vibe/<slug>`
+- Isolates git state in a dedicated directory
+- No race conditions (addresses Q-038)
+
+### 2.3 Worker execution
+A Mistral Vibe worker (`vibe -p`) runs end-to-end:
+1. Reads the brief from `CONTEXT.md`
+2. Executes coding tasks (codes, builds, tests)
+3. Commits changes with appropriate messages
+4. Pushes to remote branch
+5. Opens PR via Gitea API
+6. Attempts auto-merge
+
+### 2.4 Parallel operation
+- Multiple workers run concurrently (2-4 typical)
+- Each worker operates in its own worktree
+- No git checkout collisions
+- Shared origin main as base
+
+### 2.5 Dispatch orchestration
+A `dispatch-batch.sh` script:
+- Orchestrates batches of 2-4 workers
+- Auto-merges PRs that workers opened but didn't merge
+- Ensures all PRs reach merged state
+- Handles cross-worker dependencies
+
+---
+
+## 3. Why this works
+
+### 3.1 Worktree isolation
+Git worktrees provide complete isolation of git state. Each worker has its own:
+- Working directory
+- Index (staging area)
+- HEAD pointer
+- Branch reference
+
+This eliminates race conditions documented in Q-038 of the harness logs.
+
+### 3.2 Pre-fetched origin
+Origin is pre-fetched before worktree creation (Q-060 fix). This guarantees:
+- All workers branch from current main
+- No stale base branches
+- Consistent starting point across batch
+
+### 3.3 Full PR lifecycle
+Workers handle the complete PR lifecycle:
+- Code implementation
+- Build and test execution
+- Commit with proper conventions
+- Push to remote
+- PR creation via Gitea API
+- Merge via Gitea API (squash merge default)
+
+### 3.4 Trainer takeover
+For the rare gaps (~5% of cases):
+- Price-cap restrictions
+- Broken Mistral tests
+- Ambiguous requirements
+
+Trainer (Claude) takeover within ~5 minutes covers these edge cases.
+
+---
+
+## 4. How to read PR provenance
+
+### 4.1 Commit message markers
+Look for these patterns in commit messages:
+
+| Marker | Meaning |
+|--------|---------|
+| `Mostly Mistral Vibe authored` | Mixed human + AI authorship |
+| `100% Mistral autonomous` | Fully autonomous workflow |
+| `batch<N>-task-<X>` | Brief slug reference |
+| `Q-058 trainer takeover` | Specific quirk reference |
+| `Q-062 fix applied` | Quirk mitigation applied |
+
+### 4.2 Branch naming
+Branch names encode the workflow:
+```
+vibe/<batch>-<task>-<description>
+```
+Examples:
+- `vibe/batch4-task-a-email-infra`
+- `vibe/batch10-task-mistral-pattern-doc`
+
+### 4.3 PR title conventions
+PR titles use gitmoji prefix:
+- `:memo:` - Documentation
+- `:robot:` - AI/automation
+- `:elephant:` - Database
+- `:rocket:` - Feature
+- `:test_tube:` - Testing
+
+---
+
+## 5. Reproducing the pattern
+
+### 5.1 Quickstart guide
+See `~/.vibe/scripts/QUICKSTART-DISPATCH-BATCH.md` for complete how-to guide.
+
+### 5.2 Resources
+
+| Resource | Path | Description |
+|----------|------|-------------|
+| Brief template | `~/.vibe/skills/prompt-builder/examples/dispatch-batch-task.md` | Standardized brief format |
+| Mistral quirks | `~/.vibe/memory/reference/mistral-quirks.md` | Accumulated lessons (Q-001 through Q-063 as of 2026-05-05) |
+| Architecture doc | `~/.vibe/memory/reference/architecture-mapreduce-orchestration.md` | Design rationale |
+| Budget history | `~/.vibe/memory/reference/budget-history.jsonl` | Empirical cost data |
+
+---
+
+## 6. Numbers (2026-05-05 reference)
+
+### 6.1 Throughput
+| Metric | Value | Notes |
+|--------|-------|-------|
+| PRs merged (one day) | 20 | Mistral autonomous |
+| Wall-clock parallel (2 PRs) | ~2 minutes | vs ~3-4 minutes serial |
+| Wall-clock parallel (4 PRs) | ~2-3 minutes | Batch efficiency |
+
+### 6.2 Cost
+| PR Type | Cost Range | Notes |
+|---------|------------|-------|
+| Simple PR | $0.5-1.5 | Documentation, minor changes |
+| Code-heavy PR | $2-3 | Complex logic, multiple files |
+| Complex PR | $3-5 | Architecture changes, deep refactoring |
+
+### 6.3 Autonomy rate
+| Metric | Value |
+|--------|-------|
+| Autonomy rate per batch | 95-100% |
+| Trainer takeover rate | 5% |
+| Takeover reasons | Price-cap (2%), broken tests (2%), ambiguity (1%) |
+
+---
+
+## 7. Future evolution
+
+### 7.1 Phase 1bis (current)
+- Multi-process workers operating in parallel
+- Claude trainer reduces observations
+- Improves harness reliability
+- Current state as of 2026-05-05
+
+### 7.2 Phase 2 (target)
+- Mistral meta-agent performs reduce phase
+- Full autonomy loop without Claude
+- Self-improving pattern
+- Target: Q3 2026
+
+### 7.3 Long-term vision
+- Fully autonomous feature development
+- Self-healing test failures
+- Cost-optimized batch dispatch
+- Multi-repository orchestration
+
+---
+
+## 8. Cross-references
+
+### 8.1 Related ADRs
+| ADR | Description |
+|-----|-------------|
+| [ADR-0001](../adr/0001-go-1.26.1-standard.md) | Go 1.26.1 standard |
+| [ADR-0008](../adr/0008-bdd-testing.md) | BDD with Godog |
+| [ADR-0028](../adr/0028-passwordless-auth-migration.md) | Passwordless auth (Phase A complete) |
+
+### 8.2 Related documentation
+| Document | Description |
+|----------|-------------|
+| [CONTRIBUTING.md](../CONTRIBUTING.md) | Contribution guidelines |
+| [AGENTS.md](../AGENTS.md) | Agent documentation |
+| [PHASE_B_ROADMAP.md](PHASE_B_ROADMAP.md) | Phase B OIDC roadmap |
+
+---
+
+*Developer onboarding doc — see QUICKSTART-DISPATCH-BATCH.md for implementation details.*