docs(entire-cli): enrich 4 guide files with production diagrams from issue #802

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 <noreply@anthropic.com>
2026-03-05 15:11:32 +01:00 · 2026-03-05 15:11:32 +01:00 · 2b9c654f0f
commit 2b9c654f0f
parent 0bdb34b2a4
5 changed files with 180 additions and 8 deletions
--- 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
--- 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
--- 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:
--- 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
--- 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).

 ---