docs(01): capture phase context
This commit is contained in:
Pierre Martin
90
.planning/phases/01-session-discovery/01-CONTEXT.md
Normal file
90
.planning/phases/01-session-discovery/01-CONTEXT.md
Normal file
@@ -0,0 +1,90 @@
|
||||
# Phase 1: Session Discovery - Context
|
||||
|
||||
**Gathered:** 2026-03-23
|
||||
**Status:** Ready for planning
|
||||
|
||||
<domain>
|
||||
## Phase Boundary
|
||||
|
||||
CLI one-shot (`vmux list`) qui détecte toutes les sessions Claude Code actives sur le poste et affiche leur état, cwd, worktree, branche git et un aperçu de la sortie. Pas de daemon, pas de persistance, pas d'intégration i3.
|
||||
|
||||
</domain>
|
||||
|
||||
<decisions>
|
||||
## Implementation Decisions
|
||||
|
||||
### Détection des sessions
|
||||
- **D-01:** Scanner `/proc` pour trouver les PID des processus Claude Code actifs, puis enrichir avec les fichiers JSONL dans `~/.claude/projects/`. Un JSONL sans PID correspondant = session terminée, ignorée.
|
||||
- **D-02:** Utiliser `sessions-index.json` (présent dans chaque dossier projet sous `~/.claude/projects/`) comme source de métadonnées riches (sessionId, gitBranch, projectPath, summary, created, modified). Format vérifié sur le poste.
|
||||
- **D-03:** Le matching PID → session se fait via le cwd du processus (`/proc/PID/cwd` → readlink) croisé avec le `projectPath` du sessions-index.
|
||||
|
||||
### Détection d'état
|
||||
- **D-04:** Se baser uniquement sur le JSONL (tail-read de la dernière entrée) pour déterminer l'état. Pas de lecture CPU en Phase 1.
|
||||
- **D-05:** Heuristique d'état basée sur le dernier message JSONL :
|
||||
- `type=assistant` + `content_types=['tool_use']` → Working (outil en cours)
|
||||
- `type=progress` avec `hook_progress` → Working (hook en cours)
|
||||
- `type=assistant` + `content_types=['text']` → Needs Input (Claude a fini, attend l'utilisateur)
|
||||
- Dernière activité > seuil → Idle
|
||||
- **D-06:** ATTENTION pitfall recherche : les JSONL peuvent faire > 100 Mo. Toujours tail-read (lire depuis la fin), jamais charger le fichier entier.
|
||||
|
||||
### Format d'affichage
|
||||
- **D-07:** Couleurs activées par défaut pour l'état (vert = Working, rouge/jaune = Needs Input, gris = Idle).
|
||||
|
||||
### Claude's Discretion
|
||||
- Format d'affichage : Claude choisit entre tableau compact ou blocs détaillés selon ce qui est le plus adapté. Libre de proposer un format hybride.
|
||||
- Gestion du `--no-color` pour la compatibilité pipe.
|
||||
|
||||
</decisions>
|
||||
|
||||
<canonical_refs>
|
||||
## Canonical References
|
||||
|
||||
**Downstream agents MUST read these before planning or implementing.**
|
||||
|
||||
### Claude Code session format
|
||||
- `~/.claude/projects/<encoded-cwd>/sessions-index.json` — Index des sessions avec métadonnées (sessionId, gitBranch, projectPath, summary, messageCount, created, modified, isSidechain). Format JSON, champ `version: 1`, tableau `entries`.
|
||||
- `~/.claude/projects/<encoded-cwd>/<uuid>.jsonl` — Messages de session en append-only. Types : `user`, `assistant`, `progress`. Les messages `assistant` ont un champ `message.content[]` avec des objets `{type: "text"|"tool_use"}`. Les messages `progress` ont un champ `data` avec `{type: "hook_progress", hookEvent, hookName}`.
|
||||
|
||||
### Processus
|
||||
- `/proc/PID/cwd` — Symlink vers le cwd du processus. Permet le matching PID → projet.
|
||||
- Les processus Claude Code apparaissent comme `claude` (ou `claude -c`) dans `ps aux`.
|
||||
|
||||
No external specs — requirements fully captured in decisions above.
|
||||
|
||||
</canonical_refs>
|
||||
|
||||
<code_context>
|
||||
## Existing Code Insights
|
||||
|
||||
### Reusable Assets
|
||||
- Aucun code existant (greenfield)
|
||||
|
||||
### Established Patterns
|
||||
- Projet Go stdlib uniquement, cohérent avec piaire (pas de framework CLI, pas de dépendance externe)
|
||||
- NixOS + direnv pour l'environnement de dev
|
||||
|
||||
### Integration Points
|
||||
- Aucun pour la Phase 1 (standalone CLI)
|
||||
|
||||
</code_context>
|
||||
|
||||
<specifics>
|
||||
## Specific Ideas
|
||||
|
||||
- Le `sessions-index.json` contient un champ `summary` généré par Claude Code qui peut servir d'aperçu rapide en complément du tail JSONL
|
||||
- Le champ `isSidechain` permet de filtrer les sessions secondaires (subagents) si besoin
|
||||
- L'encoding du cwd dans le nom de dossier (`-home-pierre-Code-vibe-vmux`) est un remplacement `/` → `-`
|
||||
|
||||
</specifics>
|
||||
|
||||
<deferred>
|
||||
## Deferred Ideas
|
||||
|
||||
None — discussion stayed within phase scope
|
||||
|
||||
</deferred>
|
||||
|
||||
---
|
||||
|
||||
*Phase: 01-session-discovery*
|
||||
*Context gathered: 2026-03-23*
|
||||
69
.planning/phases/01-session-discovery/01-DISCUSSION-LOG.md
Normal file
69
.planning/phases/01-session-discovery/01-DISCUSSION-LOG.md
Normal file
@@ -0,0 +1,69 @@
|
||||
# Phase 1: Session Discovery - Discussion Log
|
||||
|
||||
> **Audit trail only.** Do not use as input to planning, research, or execution agents.
|
||||
> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
|
||||
|
||||
**Date:** 2026-03-23
|
||||
**Phase:** 01-session-discovery
|
||||
**Areas discussed:** Détection sessions, Format d'affichage, Détection d'état
|
||||
|
||||
---
|
||||
|
||||
## Détection des sessions
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| /proc d'abord | Scanner /proc pour trouver les PID Claude Code actifs, puis croiser avec les JSONL pour enrichir | ✓ |
|
||||
| JSONL d'abord | Scanner ~/.claude/projects/ pour trouver les sessions, puis vérifier via /proc si actives | |
|
||||
| Tu décides | Laisser Claude choisir | |
|
||||
|
||||
**User's choice:** /proc + JSONL (après investigation montrant que les JSONL persistent après fin de session et n'ont pas de champ "active")
|
||||
**Notes:** L'utilisateur a demandé à vérifier si les JSONL persistent. Investigation en live : oui, pas de champ status. Le croisement /proc (actif?) + JSONL (données riches) est la seule approche fiable.
|
||||
|
||||
---
|
||||
|
||||
## Format d'affichage
|
||||
|
||||
### Style
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Tableau compact | Une ligne par session, style `docker ps` | |
|
||||
| Blocs détaillés | Un bloc par session sur plusieurs lignes | |
|
||||
| Tu décides | Laisser Claude choisir | ✓ |
|
||||
|
||||
**User's choice:** Claude décide
|
||||
**Notes:** L'utilisateur fait confiance au jugement de Claude pour le format optimal.
|
||||
|
||||
### Couleurs
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Oui, couleurs | Vert/Rouge/Jaune/Gris par état | ✓ |
|
||||
| Texte brut | Pas de couleurs | |
|
||||
| Les deux | Couleurs + --no-color | |
|
||||
|
||||
**User's choice:** Couleurs activées
|
||||
**Notes:** -
|
||||
|
||||
---
|
||||
|
||||
## Détection d'état
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| JSONL + CPU | Croiser JSONL + %CPU processus | |
|
||||
| JSONL seul | Tail-read du dernier message JSONL uniquement | ✓ |
|
||||
| Tu décides | Laisser Claude choisir | |
|
||||
|
||||
**User's choice:** JSONL seul
|
||||
**Notes:** Plus simple. La Phase 3 (hooks) apportera la détection fine.
|
||||
|
||||
---
|
||||
|
||||
## Claude's Discretion
|
||||
|
||||
- Format d'affichage (tableau compact vs blocs détaillés)
|
||||
- Gestion --no-color
|
||||
|
||||
## Deferred Ideas
|
||||
|
||||
None
|
||||
Reference in New Issue
Block a user