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>
This commit is contained in:
Florian BRUNIAUX
parent
0bdb34b2a4
commit
2b9c654f0f
5 changed files with 180 additions and 8 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
|
||||
---
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue