From 2b9c654f0f29cc231e3b2b286933b6aeb3682ddb Mon Sep 17 00:00:00 2001 From: Florian BRUNIAUX Date: Thu, 5 Mar 2026 15:11:32 +0100 Subject: [PATCH] docs(entire-cli): enrich 4 guide files with production diagrams from issue #802 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 6 additions across ai-traceability, ai-ecosystem, third-party-tools, security-hardening. - ai-traceability.md: full hook architecture diagram (sans/avec Entire), real checkpoint structure (entire/checkpoints/v1/ tree), orphan branch diagram, Go/No-Go thresholds table with 2h spike commands - ai-ecosystem.md: agent handoffs flow diagram (Claude → Gemini, no cold start) - third-party-tools.md: delta table vs existing setups (JSONL, attribution, handoffs) + evaluation stop criteria - security-hardening.md: approval gate flow diagram (policy check → low/high risk → approve/reject → audit trail) Source: github.com/methode-aristote/app/issues/802 Co-Authored-By: Claude Sonnet 4.6 --- CHANGELOG.md | 6 ++ guide/ai-ecosystem.md | 28 ++++++++++ guide/ai-traceability.md | 108 +++++++++++++++++++++++++++++++++--- guide/security-hardening.md | 22 ++++++++ guide/third-party-tools.md | 24 ++++++++ 5 files changed, 180 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d5b8b71..d81be27 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Added +- **Entire CLI enrichissement (6 sections, 4 fichiers)** — intégration de l'analyse production issue #802 (Méthode Aristote) dans le guide. Contenu ajouté : (1) `guide/ai-traceability.md` — diagramme complet "workflow sans vs avec Entire" montrant les 7 hooks et ce qu'ils capturent (UserPromptSubmit, PreToolUse, PostToolUse, Stop...), structure réelle des checkpoints (`entire/checkpoints/v1/` avec metadata.json + full.jsonl + prompt.txt + context.md), diagramme branche orpheline (pas d'ancêtre commun = zéro merge conflict), tableau Go/No-Go avec seuils mesurables (< 10 MB/session, push < 5s, < 100 MB/semaine) et commandes de spike 2h. (2) `guide/ai-ecosystem.md` — diagramme agent handoffs Claude → Gemini avec préservation de contexte (reasoning trace, fichiers touchés, décisions, approches rejetées), explication du "no cold start". (3) `guide/third-party-tools.md` — tableau delta vs setups existants (JSONL 7j vs checkpoints permanents, attribution humain/IA absente vs % par ligne, handoffs silencieux vs context auto-passé). (4) `guide/security-hardening.md` — diagramme approval gate flow (policy check → low risk auto-OK / high risk → reviewer transcript + diffs → approve/reject → immutable audit trail). Source : [github.com/methode-aristote/app/issues/802](https://github.com/methode-aristote/app/issues/802). + +- **`issue-triage` skill** (`examples/skills/issue-triage/`) — 3-phase issue backlog management for maintainers: automated audit of all open issues (categorization, Jaccard duplicate detection against open + 20 recent closed, risk classification Red/Yellow/Green, staleness 30/90-day thresholds, cross-reference to open PRs), opt-in deep analysis via parallel agents (full body + comments, duplicate verification, missing-info detection, effort estimate), and validated triage actions with mandatory `AskUserQuestion` gate (comment / label / close with close-reason). Jaccard algorithm is self-contained at runtime (no external library: normalize → tokenize → set intersection/union → threshold 0.60). Cross-referenced with `/pr-triage` for PR-side backlog management. + - **`pr-triage` skill** (`examples/skills/pr-triage/`) — 3-phase PR backlog management for maintainers: automated audit of all open PRs (size classification, overlap detection, cluster analysis, staleness, CI status, PR-issue linking), opt-in deep review via parallel `code-reviewer` agents, and validated comment posting with mandatory `AskUserQuestion` gate. Stack-agnostic (Node/TS, Python, Rust, Go checklists included), cross-platform clipboard (pbcopy/xclip/wl-copy/clip.exe), and cross-referenced with `/review-pr` for single-PR use cases. - **External Orchestration Frameworks** (`guide/third-party-tools.md`, nouvelle section) — nouvelle catégorie architecturalement distincte des outils multi-instance existants (Gas Town, multiclaude). Distinction documentée : lancer plusieurs instances Claude Code en parallèle vs. remplacer/augmenter la couche d'orchestration interne avec un runtime complet. Deux outils couverts : (1) **Ruflo** (anciennement claude-flow, 18.9k stars) — framework le plus adopté, swarms hiérarchiques queen + workers, 60+ agents spécialisés, Q-Learning router, 42+ skills, 17 hooks, SQLite persistence. Recommandation d'install via `npx ruflo@latest` (pas curl|bash). Claims de performance (84.8% SWE-Bench, 352x WASM) marqués non vérifiés, rebrand en cours documenté. (2) **Athena Flow** — architecture différente (hooks → UDS → NDJSON → runtime Node.js → TUI), intercept les events hooks plutôt que d'augmenter la couche agent. Premier workflow : builder E2E tests Playwright autonome. Statut "Watch — not recommended yet" (projet trop récent, source audit manquant). Évaluations complètes : `docs/resource-evaluations/073-athena-flow-workflow-runtime.md` (2/5 Watch) et `074-ruflo-multi-agent-orchestration.md` (3/5 Pertinent). @@ -22,6 +26,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Session Auto-Rename pattern** — instruction comportementale dans `~/.claude/CLAUDE.md` qui fait renommer automatiquement les sessions par Claude après 2-3 échanges, sans hook ni script. Format `[action] [subject]` (ex: "fix auth middleware", "refactor hook system"), max 50 chars, verbe d'action en premier. Utile pour retrouver les sessions via `/resume` quand plusieurs tournent en parallèle. Limitation documentée : le tab terminal WebStorm ne peut pas être renommé (ANSI sequences filtrées par JetBrains). Template : `examples/claude-md/session-naming.md`. Guide : nouvelle sous-section "Session Auto-Rename" dans §1.3 Session Continuation. Compteur templates 175→176. +- **Design Reference File pattern** (`examples/claude-md/design-reference-file.md`) — pattern de terrain issu de l'évaluation Boris Paillard / mixt.care (mars 2026). Principe : garder `brand-book.html` et `ui-kit.html` à la racine du projet comme fichiers de contexte permanents — Claude Code les lit avant toute génération UI, ce qui assure la cohérence du design system entre sessions sans re-prompter. Contenu : snippet CLAUDE.md d'activation, 4 prompts complets (brand-book avec WCAG intégré, ui-kit Tailwind, audit couleur WCAG 2.1 + simulation daltonisme, scroll animations Intersection Observer vanilla JS), exemple de palette avec rôles sémantiques CSS (mixt.care), notes de correction WCAG (ex: cuivre #B87333 échoue en texte normal → corriger à #9B5F20). Évaluation : `docs/resource-evaluations/075-paillard-design-system-first-website.md` (3/5). + - **Straude** (`guide/third-party-tools.md`, section Token & Cost Tracking) — fiche complète pour straude.com, dashboard social pour tracker la consommation Claude Code avec leaderboard et streaks. Inclut : description fonctionnelle, tableau des données transmises au serveur (coûts, tokens, modèles, hostname), analyse de sécurité basée sur inspection directe du code source (`npm pack straude@0.1.9`), verdict (pas de malware, réserves sur la maturité et l'absence de privacy policy), recommandation `--dry-run` en première utilisation. Évaluation complète : `docs/resource-evaluations/straude-evaluation.md`. Entrées ajoutées dans `machine-readable/reference.yaml`. ## [3.30.1] - 2026-03-04 diff --git a/guide/ai-ecosystem.md b/guide/ai-ecosystem.md index 6415b9c..b3ac3e1 100644 --- a/guide/ai-ecosystem.md +++ b/guide/ai-ecosystem.md @@ -1643,6 +1643,34 @@ See: `guide/observability.md` for native Claude Code session monitoring - ⚠️ Very new (launched Feb 10-12, 2026) - limited production feedback - 🔗 [GitHub repo](https://github.com/entireio/cli) / [entire.io](https://entire.io) +**Agent handoff flow (how context actually passes between agents):** + +``` +Claude Code Gemini CLI Entire +----------- ---------- ------ + +works on feature +"blocked on X, + delegate to Gemini" ---------> hook PreToolUse[Task] + (captures the handoff) + | + receives full | + context: | + - reasoning trace | + - files touched | + - decisions made | + - rejected approaches| + | + works... | + completes | + v + hook PostToolUse[Task] + (captures result) + +Result: each agent in the chain sees the reasoning of previous agents. +No "cold start" — full context preserved across agent switches. +``` + **When to use Entire CLI:** ```bash diff --git a/guide/ai-traceability.md b/guide/ai-traceability.md index b581bd9..f689778 100644 --- a/guide/ai-traceability.md +++ b/guide/ai-traceability.md @@ -327,6 +327,63 @@ entire init entire capture --agent="claude-code" ``` +**How It Works (Hook Architecture):** + +``` +WITHOUT ENTIRE +============== + + Developer Agent (Claude/Gemini/Codex) Git + --------- --------------------------- --- + prompt ---------> reasons + edits files + tool calls (Bash, Read, Edit...) + prompt ---------> continues... + "looks good" ---> session ends + + git commit -----> ----------------------------------------> commit on feature/branch + (code only, zero context) + + Result: the code is there, but WHY and HOW are lost. + No record of prompts, reasoning, or abandoned approaches. + + +WITH ENTIRE +=========== + + Developer Agent (Claude/Gemini/Codex) Entire Hooks Git + --------- --------------------------- ------------ --- + + entire enable ---> installs 7 hooks automatically (once per repo) + + [SESSION START] -----------------------------------------> hook SessionStart + + prompt ---------> reasons + edits ---------> hook UserPromptSubmit + tool calls... ---------> hook PreToolUse/PostToolUse + + [AGENT ENDS] -------------------------------------------------> hook Stop + | + CHECKPOINT created on + shadow branch: + entire/2b4c177-a5e3f2 + | + Contains: + - full transcript + - user prompts + - file diffs + - tool calls + - token usage + - human vs AI attribution % + + git commit -----> ----------------------------------------> commit on feature/branch + + auto-added trailer: + "Entire-Checkpoint: a3b2c4" + + git push -------> ----------------------------------------> code pushed normally + shadow → entire/checkpoints/v1 + (orphan branch, zero conflicts) + shadow branch auto-deleted +``` + **Workflow with Claude Code:** ```bash @@ -409,18 +466,26 @@ entire approve --approver="jane@company.com" **Architecture:** -Entire stores data in `.entire/` directory with separate git branch: +Entire stores checkpoints on an orphan branch — no common ancestor with `main`, so no merge conflicts and no history pollution: ``` -project/ -├─ .entire/ -│ ├─ config.yaml # Configuration -│ ├─ sessions/ # Session metadata -│ └─ checkpoints/ # Named checkpoints -└─ .git/ - └─ refs/heads/entire/checkpoints/v1 +entire/checkpoints/v1/ ← orphan branch (no common ancestor with main) +├─ a/b2c4d5e6f7/ ← checkpoint ID (random hex) +│ ├─ metadata.json ← summary, attribution %, token count +│ └─ 0/ +│ ├─ full.jsonl ← complete session transcript +│ ├─ prompt.txt ← user prompts +│ └─ context.md ← generated context summary +└─ c/d4e5f6a7b8/ ← another checkpoint + └─ ... + +main ----o----o----o----o----> (normal code history, untouched) + +entire/checkpoints/v1 ----x----x----x----> (no common ancestor = no merge conflicts) ``` +Why orphan branch: `git clone --single-branch` ignores checkpoints (zero overhead for consumers). Multiple devs can push in parallel without conflicts (checkpoint IDs are unique). + **Limitations:** - Very new (launched Feb 10-12, 2026) - limited production feedback @@ -436,6 +501,33 @@ project/ - ✅ Governance gates (approval required before actions) - ⚠️ Personal projects: May be overkill (simple `Co-Authored-By` suffices) +**Go/No-Go evaluation thresholds (run a 2h spike before team rollout):** + +```bash +# Install on a throwaway branch +entire enable + +# After 2-3 normal sessions, measure: +du -sh .git/refs/heads/entire/ # Storage overhead per session +time git push # Push time including condensation +ls .git/hooks/ # Check for conflicts with existing hooks +``` + +| Metric | Green (proceed) | Red (stop) | +|--------|----------------|-----------| +| Checkpoint size | < 10 MB/session | > 10 MB → storage risk | +| Push overhead | < 5s | > 5s → daily friction | +| Repo growth | < 100 MB/week | > 100 MB/week | +| Hook compatibility | No conflicts | Timeout or conflict → blocker | + +**Team size guidance:** + +| Team | Recommendation | +|------|---------------| +| Solo dev | `Co-Authored-By` trailer suffices | +| 2-5 devs | Justified if multi-agent workflows or shared audit trail needed | +| 5+ devs / enterprise | Strong fit (shared checkpoints, governance, compliance) | + ### 5.2 Automated Attribution Hook Add `Assisted-by` trailer automatically when Claude Code commits: diff --git a/guide/security-hardening.md b/guide/security-hardening.md index 006108c..e0dc47e 100644 --- a/guide/security-hardening.md +++ b/guide/security-hardening.md @@ -578,6 +578,28 @@ The agent checks: | **Approvals** | Approver identity, timestamp, checkpoint reference | Permanent | | **Agent handoffs** | Source/target agents, context transferred | Permanent | +**Approval gate flow:** + +``` +Developer --> commit + checkpoint + | + v + [Policy Check] + "Does this touch prisma/schema.prisma?" + "Does this touch src/server/auth*?" + | + +----+----+ + | | + Low risk High risk + | | + Auto-OK Approval Gate + "Reviewer inspects: + transcript + diffs + attribution %" + | + Approve / Reject + (immutable audit trail entry) +``` + **Example compliance workflow:** ```bash diff --git a/guide/third-party-tools.md b/guide/third-party-tools.md index ce349ba..1f7cc27 100644 --- a/guide/third-party-tools.md +++ b/guide/third-party-tools.md @@ -250,6 +250,30 @@ Agent-native platform for Git-integrated session capture with rewindable checkpo - macOS/Linux only (Windows via WSL) - Early stage (v1.x) - expect API changes +**Delta vs common existing setups:** + +| Need | Typical existing setup | What Entire adds | +|------|----------------------|-----------------| +| Tool call logging | Local JSONL (7-day rotation) | Reasoning + attribution %, Git-permanent | +| Human/AI attribution | Nothing | % per file, annotated per line, by model | +| Agent handoffs | Manual context copy | Context checkpoint auto-passed to next agent | +| Inter-dev handoff | Git commits/PRs | Shared readable checkpoints on `entire/checkpoints/v1` | +| Session persistence | Local only, ephemeral | Git-native, permanent, shareable | +| Governance | Custom pre-commit hooks | Policy-based approval gates + configurable audit export | + +**Evaluation (2h spike recommended before team rollout):** + +```bash +entire enable # Install on throwaway branch + +# After 2-3 normal sessions: +du -sh .git/refs/heads/entire/ # Storage per session → flag if > 10 MB +time git push # Push overhead → flag if > 5s +ls .git/hooks/ # Verify no conflict with existing hooks +``` + +Stop criteria: checkpoint > 10 MB/session, push overhead > 5s, or hook conflicts. + > **Cross-ref**: Full Entire workflow with examples at [AI Traceability Guide](./ai-traceability.md#51-entire-cli). For compliance use cases, see [Security Hardening](./security-hardening.md). ---