jfl 0.2.5 → 0.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (133) hide show
  1. package/README.md +308 -28
  2. package/dist/commands/context-hub.d.ts.map +1 -1
  3. package/dist/commands/context-hub.js +428 -27
  4. package/dist/commands/context-hub.js.map +1 -1
  5. package/dist/commands/eval.d.ts +6 -0
  6. package/dist/commands/eval.d.ts.map +1 -0
  7. package/dist/commands/eval.js +236 -0
  8. package/dist/commands/eval.js.map +1 -0
  9. package/dist/commands/flows.d.ts +4 -1
  10. package/dist/commands/flows.d.ts.map +1 -1
  11. package/dist/commands/flows.js +160 -1
  12. package/dist/commands/flows.js.map +1 -1
  13. package/dist/commands/init.d.ts.map +1 -1
  14. package/dist/commands/init.js +272 -145
  15. package/dist/commands/init.js.map +1 -1
  16. package/dist/commands/peter.d.ts.map +1 -1
  17. package/dist/commands/peter.js +220 -1
  18. package/dist/commands/peter.js.map +1 -1
  19. package/dist/commands/pi.d.ts +21 -0
  20. package/dist/commands/pi.d.ts.map +1 -0
  21. package/dist/commands/pi.js +154 -0
  22. package/dist/commands/pi.js.map +1 -0
  23. package/dist/commands/portfolio.d.ts +6 -0
  24. package/dist/commands/portfolio.d.ts.map +1 -0
  25. package/dist/commands/portfolio.js +249 -0
  26. package/dist/commands/portfolio.js.map +1 -0
  27. package/dist/commands/predict.d.ts +6 -0
  28. package/dist/commands/predict.d.ts.map +1 -0
  29. package/dist/commands/predict.js +234 -0
  30. package/dist/commands/predict.js.map +1 -0
  31. package/dist/commands/scope.d.ts +1 -0
  32. package/dist/commands/scope.d.ts.map +1 -1
  33. package/dist/commands/scope.js +189 -2
  34. package/dist/commands/scope.js.map +1 -1
  35. package/dist/commands/synopsis.d.ts +44 -0
  36. package/dist/commands/synopsis.d.ts.map +1 -1
  37. package/dist/commands/synopsis.js +1 -1
  38. package/dist/commands/synopsis.js.map +1 -1
  39. package/dist/commands/update.d.ts.map +1 -1
  40. package/dist/commands/update.js +49 -1
  41. package/dist/commands/update.js.map +1 -1
  42. package/dist/commands/viz.d.ts +7 -0
  43. package/dist/commands/viz.d.ts.map +1 -0
  44. package/dist/commands/viz.js +460 -0
  45. package/dist/commands/viz.js.map +1 -0
  46. package/dist/commands/voice.js.map +1 -1
  47. package/dist/dashboard/index.d.ts +4 -5
  48. package/dist/dashboard/index.d.ts.map +1 -1
  49. package/dist/dashboard/index.js +57 -119
  50. package/dist/dashboard/index.js.map +1 -1
  51. package/dist/dashboard-static/assets/index-B6kRK9Rq.js +116 -0
  52. package/dist/dashboard-static/assets/index-BpdKJPLu.css +1 -0
  53. package/dist/dashboard-static/index.html +16 -0
  54. package/dist/index.js +120 -20
  55. package/dist/index.js.map +1 -1
  56. package/dist/lib/eval-store.d.ts +15 -0
  57. package/dist/lib/eval-store.d.ts.map +1 -0
  58. package/dist/lib/eval-store.js +179 -0
  59. package/dist/lib/eval-store.js.map +1 -0
  60. package/dist/lib/flow-engine.d.ts +13 -0
  61. package/dist/lib/flow-engine.d.ts.map +1 -1
  62. package/dist/lib/flow-engine.js +164 -3
  63. package/dist/lib/flow-engine.js.map +1 -1
  64. package/dist/lib/hub-client.d.ts +80 -0
  65. package/dist/lib/hub-client.d.ts.map +1 -0
  66. package/dist/lib/hub-client.js +46 -0
  67. package/dist/lib/hub-client.js.map +1 -0
  68. package/dist/lib/predictor.d.ts +99 -0
  69. package/dist/lib/predictor.d.ts.map +1 -0
  70. package/dist/lib/predictor.js +394 -0
  71. package/dist/lib/predictor.js.map +1 -0
  72. package/dist/lib/service-gtm.d.ts +88 -44
  73. package/dist/lib/service-gtm.d.ts.map +1 -1
  74. package/dist/lib/service-gtm.js +451 -243
  75. package/dist/lib/service-gtm.js.map +1 -1
  76. package/dist/lib/telemetry-agent.d.ts +57 -0
  77. package/dist/lib/telemetry-agent.d.ts.map +1 -0
  78. package/dist/lib/telemetry-agent.js +268 -0
  79. package/dist/lib/telemetry-agent.js.map +1 -0
  80. package/dist/lib/telemetry-digest.d.ts.map +1 -1
  81. package/dist/lib/telemetry-digest.js +17 -17
  82. package/dist/lib/telemetry-digest.js.map +1 -1
  83. package/dist/lib/telemetry.d.ts +1 -0
  84. package/dist/lib/telemetry.d.ts.map +1 -1
  85. package/dist/lib/telemetry.js +14 -6
  86. package/dist/lib/telemetry.js.map +1 -1
  87. package/dist/lib/trajectory-loader.d.ts +82 -0
  88. package/dist/lib/trajectory-loader.d.ts.map +1 -0
  89. package/dist/lib/trajectory-loader.js +406 -0
  90. package/dist/lib/trajectory-loader.js.map +1 -0
  91. package/dist/mcp/context-hub-mcp.js +60 -0
  92. package/dist/mcp/context-hub-mcp.js.map +1 -1
  93. package/dist/mcp/service-registry-mcp.js +0 -0
  94. package/dist/types/eval.d.ts +18 -0
  95. package/dist/types/eval.d.ts.map +1 -0
  96. package/dist/types/eval.js +5 -0
  97. package/dist/types/eval.js.map +1 -0
  98. package/dist/types/journal.d.ts +133 -0
  99. package/dist/types/journal.d.ts.map +1 -0
  100. package/dist/types/journal.js +59 -0
  101. package/dist/types/journal.js.map +1 -0
  102. package/dist/types/map.d.ts +1 -1
  103. package/dist/types/map.d.ts.map +1 -1
  104. package/dist/types/map.js.map +1 -1
  105. package/dist/ui/service-dashboard.js.map +1 -1
  106. package/dist/utils/jfl-paths.d.ts +1 -0
  107. package/dist/utils/jfl-paths.d.ts.map +1 -1
  108. package/dist/utils/jfl-paths.js +1 -0
  109. package/dist/utils/jfl-paths.js.map +1 -1
  110. package/dist/utils/wallet.js.map +1 -1
  111. package/package.json +7 -2
  112. package/scripts/generate-changesets.sh +113 -0
  113. package/scripts/migrate-to-branch-sessions.sh +201 -0
  114. package/scripts/pp-branch-pr.sh +115 -0
  115. package/scripts/session/session-cleanup.sh +29 -14
  116. package/scripts/session/session-end.sh +0 -10
  117. package/scripts/session/session-init.sh +0 -16
  118. package/scripts/session/session-sync.sh +0 -10
  119. package/template/.jfl/flows-self-driving.yaml +170 -0
  120. package/template/THEORY.md +26 -0
  121. package/template/scripts/session/session-cleanup.sh +28 -10
  122. package/dist/dashboard/components.d.ts +0 -7
  123. package/dist/dashboard/components.d.ts.map +0 -1
  124. package/dist/dashboard/components.js +0 -163
  125. package/dist/dashboard/components.js.map +0 -1
  126. package/dist/dashboard/pages.d.ts +0 -7
  127. package/dist/dashboard/pages.d.ts.map +0 -1
  128. package/dist/dashboard/pages.js +0 -742
  129. package/dist/dashboard/pages.js.map +0 -1
  130. package/dist/dashboard/styles.d.ts +0 -7
  131. package/dist/dashboard/styles.d.ts.map +0 -1
  132. package/dist/dashboard/styles.js +0 -497
  133. package/dist/dashboard/styles.js.map +0 -1
package/README.md CHANGED
@@ -55,26 +55,37 @@ That's it. SessionStart hooks handle repo sync, session branching, Context Hub s
55
55
 
56
56
  ## Architecture
57
57
 
58
- JFL workspaces are **context layers**, not code repos. Product code lives in separate service repos that register with the GTM.
58
+ JFL supports a three-level hierarchy: **Portfolio > GTM > Services**. Portfolios coordinate multiple products. GTMs are context layers for individual products. Services are the repos that do the actual work.
59
59
 
60
60
  ```
61
- my-project/ <- GTM workspace (strategy, context, orchestration)
61
+ visa-portfolio/ <- Portfolio (strategy, cross-product RL, data flow)
62
62
  ├── .jfl/
63
- │ ├── config.json <- Project config (team, services, ports)
64
- │ ├── journal/ <- Session journals (JSONL, one file per session)
65
- │ ├── memory.db <- Indexed memory (TF-IDF + embeddings)
66
- ├── service-events.jsonl <- Event bus file-drop
67
- └── services.json <- Registered services
68
- ├── knowledge/ <- Strategy docs (VISION, ROADMAP, THESIS, etc.)
69
- ├── content/ <- Generated content
70
- ├── suggestions/ <- Per-contributor workspaces
71
- ├── .claude/
72
- │ ├── settings.json <- Claude Code hooks (SessionStart, Stop, etc.)
73
- │ ├── agents/ <- Service agent definitions
74
- └── skills/ <- Slash commands (/hud, /content, etc.)
75
- ├── scripts/session/ <- Session management (init, sync, cleanup)
76
- ├── CLAUDE.md <- AI instructions
77
- └── .mcp.json <- MCP server config (Context Hub)
63
+ │ ├── config.json <- type: "portfolio", registered child GTMs
64
+ │ ├── eval.jsonl <- Aggregated eval data from all children
65
+ │ ├── flows.yaml <- Cross-product event routing
66
+ └── journal/ <- Portfolio-level + synced child journals
67
+
68
+ ├── productrank-gtm/ <- GTM workspace (registered as child)
69
+ ├── .jfl/
70
+ │ │ ├── config.json <- type: "gtm", portfolio_parent, registered services
71
+ │ │ ├── eval.jsonl <- Eval entries from arena competitions
72
+ ├── journal/ <- Session journals + synced service journals
73
+ ├── agents/ <- Agent manifests + policies
74
+ │ ├── flows/ <- Per-agent flow definitions
75
+ │ │ └── service-events.jsonl
76
+ ├── knowledge/ <- Strategy docs (VISION, ROADMAP, THESIS, etc.)
77
+ │ ├── content/ <- Generated content
78
+ │ ├── suggestions/ <- Per-contributor workspaces
79
+ │ ├── .claude/
80
+ │ │ ├── settings.json <- Claude Code hooks
81
+ │ │ ├── agents/ <- Service agent definitions
82
+ │ │ └── skills/ <- Slash commands (/hud, /content, etc.)
83
+ │ ├── scripts/session/ <- Session management
84
+ │ ├── CLAUDE.md <- AI instructions
85
+ │ └── .mcp.json <- MCP server config
86
+
87
+ └── seo-agent/ <- Another GTM (registered as child)
88
+ └── ...
78
89
 
79
90
  my-api/ <- Service repo (registered in GTM)
80
91
  ├── src/
@@ -87,7 +98,8 @@ my-api/ <- Service repo (registered in GTM)
87
98
  - Services work independently
88
99
  - Multiple services register to one GTM
89
100
  - `jfl update` updates tooling without touching service code
90
- - Journal entries sync from services to parent GTM
101
+ - Eval data dual-writes up the chain (service > GTM > portfolio)
102
+ - Cross-product event routing at portfolio level
91
103
 
92
104
  ---
93
105
 
@@ -104,14 +116,14 @@ jfl context-hub stop # Stop daemon
104
116
  jfl context-hub restart # Restart daemon
105
117
  jfl context-hub doctor # Diagnose all projects (OK/ZOMBIE/DOWN/STALE)
106
118
  jfl context-hub ensure-all # Start for all GTM projects
107
- jfl context-hub dashboard # Live event + context dashboard
119
+ jfl context-hub dashboard # Open web dashboard (opens browser)
108
120
  jfl context-hub install-daemon # Auto-start on boot (launchd/systemd)
109
121
  jfl context-hub uninstall-daemon # Remove auto-start
110
122
  jfl context-hub query # Query context from CLI
111
123
  jfl context-hub serve # Run in foreground (daemon mode)
112
124
  ```
113
125
 
114
- **Per-project ports** assigned automatically (or set in `.jfl/config.json` `contextHub.port`).
126
+ **Per-project ports** assigned automatically (or set in `.jfl/config.json` > `contextHub.port`).
115
127
 
116
128
  **MCP Tools** (available to Claude Code and any MCP client):
117
129
 
@@ -124,9 +136,32 @@ jfl context-hub serve # Run in foreground (daemon mode)
124
136
  | `memory_search` | Search indexed journal memories |
125
137
  | `memory_status` | Memory system statistics |
126
138
  | `memory_add` | Add manual memory entry |
139
+ | `query_experiment_history` | Query RL trajectories for agent experiments |
127
140
 
128
141
  **Resilience:** 5-layer system — MCP auto-recovery on ECONNREFUSED, health-check-before-ensure hooks, `ensure-all` for batch startup, `doctor` diagnostics, launchd/systemd daemon with keepalive.
129
142
 
143
+ ### Dashboard V2
144
+
145
+ A pre-built Vite + Preact + Tailwind SPA served by Context Hub at `/dashboard/`. Auto-detects workspace type and adapts layout.
146
+
147
+ **Pages:**
148
+
149
+ | Page | What It Shows |
150
+ |------|--------------|
151
+ | **Overview** | Activity charts, product cards, metric cards |
152
+ | **Journal** | Searchable journal entries with type filters |
153
+ | **Events** | Live event feed with pattern filter presets (eval, session, flow, etc.) |
154
+ | **Services** | Registered services with type badges, context scope visualization, data flows |
155
+ | **Flows** | Flow definitions and execution history |
156
+ | **Health** | System metrics, context sources, memory index, tracked projects |
157
+ | **Agents** | Eval leaderboards grouped by product domain |
158
+
159
+ **Features:** Sidebar with structured sections (Workspace / Infra / Eval), inline SVG icons, agent leaderboard in sidebar, sparkline charts, real-time polling.
160
+
161
+ ```bash
162
+ jfl context-hub dashboard # Opens /dashboard/ in browser
163
+ ```
164
+
130
165
  ### MAP Event Bus
131
166
 
132
167
  Metrics, Agents, Pipeline — an in-process event bus inside Context Hub.
@@ -136,10 +171,126 @@ Metrics, Agents, Pipeline — an in-process event bus inside Context Hub.
136
171
  - **Journal bridge** — watches `.jfl/journal/`, emits events on new entries
137
172
  - **Pattern-matching subscriptions** (glob support)
138
173
  - **Transports:** SSE, WebSocket, HTTP polling
139
- - **Event types:** `session:started`, `session:ended`, `task:completed`, `journal:entry`, `service:healthy`, `custom`, and more
174
+ - **Cross-product routing** portfolio flows route events between child GTMs
175
+ - **Event types:** `session:started`, `session:ended`, `eval:scored`, `journal:entry`, `flow:triggered`, `agent:iteration-complete`, `portfolio:phone-home`, and more
140
176
 
141
177
  Services emit events by appending to `.jfl/service-events.jsonl` — no auth needed, Context Hub watches the file automatically.
142
178
 
179
+ ### Eval Framework
180
+
181
+ Track agent performance over time. Eval entries dual-write up the parent chain (service > GTM > portfolio) so every level has visibility.
182
+
183
+ ```bash
184
+ jfl eval list # List recent eval entries
185
+ jfl eval list -a shadow # Filter by agent
186
+ jfl eval trajectory -a shadow # Composite score over time (with sparkline)
187
+ jfl eval log -a shadow -m '{"composite":0.69}' # Log an eval entry
188
+ jfl eval compare # Side-by-side agent comparison
189
+ jfl eval tuples # Extract (state, action, reward) training tuples
190
+ ```
191
+
192
+ **Eval entries** are JSONL with agent name, metrics, composite score, model version, and deltas:
193
+
194
+ ```json
195
+ {
196
+ "v": 1, "ts": "2026-03-05T15:22:47Z",
197
+ "agent": "productrank-shadow",
198
+ "dataset": "vibe-50-v1",
199
+ "model_version": "shadow-0.3.1",
200
+ "metrics": {"ndcg@10": 0.59, "mrr": 0.77, "precision@5": 0.43},
201
+ "composite": 0.6935,
202
+ "delta": {"composite": -0.029}
203
+ }
204
+ ```
205
+
206
+ **Leaderboard:** Agents grouped by metric domain. ProductRank agents scored on ndcg@10, mrr, precision@5. SEO agents scored on avg_rank, keywords_ranked. Dashboard Agents page shows leaderboards per domain.
207
+
208
+ **Training tuples** extracted from journals for fine-tuning: `(state, action, reward)` — maps codebase state + experiment action to eval score delta.
209
+
210
+ **API endpoints** on Context Hub:
211
+ - `GET /api/eval/leaderboard` — all agents ranked by composite
212
+ - `GET /api/eval/trajectory?agent=X&metric=composite` — score trajectory with timestamps
213
+
214
+ ### RL Infrastructure
215
+
216
+ JFL generalizes the Karpathy nanochat pattern: structured journals are the replay buffer, eval scores are rewards, agents learn in-context from past trajectories.
217
+
218
+ ```
219
+ Agent LLM (Policy) > reads trajectories, proposes experiments
220
+ Stratus (World Model) > predicts outcomes, filters bad proposals
221
+ Journals (Replay Buffer) > structured experiment history
222
+ Eval Framework (Reward) > composite scores, score deltas
223
+ Event Bus (Nervous System) > connects everything
224
+ ```
225
+
226
+ **JournalEntry type** — canonical schema with 6 RL fields: `hypothesis`, `outcome`, `score_delta`, `eval_snapshot`, `diff_hash`, `context_entries`.
227
+
228
+ **TrajectoryLoader** — query, filter, and render experiment trajectories for agent context windows. Supports filtering by session, agent, outcome, score range.
229
+
230
+ **Peter Parker** — model-routed orchestrator with cost/balanced/quality profiles. Routes tasks to haiku/sonnet/opus based on complexity. Subscribes to event bus for reactive dispatch.
231
+
232
+ **Flow Engine** — declarative trigger-action automation in `.jfl/flows.yaml`:
233
+
234
+ ```yaml
235
+ - name: eval-scored-trigger-analysis
236
+ trigger:
237
+ pattern: "eval:scored"
238
+ gate:
239
+ requires_approval: true
240
+ actions:
241
+ - type: spawn
242
+ command: "claude -p 'Analyze the latest eval results'"
243
+ ```
244
+
245
+ Flow actions: `log`, `emit`, `journal`, `webhook`, `command`, `spawn`. Gates: `after` (time-gated), `before` (deadline), `requires_approval`.
246
+
247
+ **MCP tool:** `query_experiment_history` — agents query past experiment trajectories to inform next proposals.
248
+
249
+ ### Portfolio Management
250
+
251
+ Coordinate multiple GTM workspaces under one portfolio.
252
+
253
+ ```bash
254
+ jfl portfolio register /path/to/gtm # Register a GTM in this portfolio
255
+ jfl portfolio list # List child GTMs with health
256
+ jfl portfolio unregister <name> # Remove a GTM
257
+ jfl portfolio status # Portfolio health + eval summary
258
+ jfl portfolio phone-home # Report GTM health to portfolio parent
259
+ ```
260
+
261
+ **Portfolio Context Hub** operates in fan-out mode:
262
+ - Connects to child GTM hubs via SSE
263
+ - Bridges child events into portfolio event bus
264
+ - Fans out search queries across all child hubs
265
+ - Aggregates eval leaderboard across products
266
+ - Enforces context scope (produces/consumes/denied) between GTMs
267
+
268
+ **Cross-product flows** defined in `.jfl/flows.yaml`:
269
+
270
+ ```yaml
271
+ - name: tool-trends-to-seo
272
+ trigger:
273
+ pattern: "discovery:tool-trend"
274
+ source: "productrank-gtm"
275
+ actions:
276
+ - type: webhook
277
+ url: "http://localhost:{{child.seo-agent.port}}/api/events"
278
+ ```
279
+
280
+ Template variables: `{{child.NAME.port}}`, `{{child.NAME.token}}`
281
+
282
+ **Context scope** — each child GTM declares what events it produces and consumes. Portfolio enforces boundaries:
283
+
284
+ ```json
285
+ {
286
+ "context_scope": {
287
+ "produces": ["discovery:tool-trend", "eval:*"],
288
+ "consumes": ["strategy:*", "seo:serp-data"],
289
+ "denied": []
290
+ }
291
+ }
292
+ ```
293
+
143
294
  ### Memory System
144
295
 
145
296
  Hybrid search over all journal entries with TF-IDF (40%) + semantic embeddings (60%).
@@ -162,6 +313,7 @@ Automatic session isolation for parallel work:
162
313
  - **Multiple concurrent sessions:** Isolated git worktrees prevent conflicts
163
314
  - **Auto-commit:** Saves work every 2 minutes (knowledge, journal, suggestions)
164
315
  - **Crash recovery:** Detects uncommitted work in stale sessions, auto-commits on next start
316
+ - **Cleanup guard:** Prevents `rm -rf` on main branch when no worktrees exist
165
317
 
166
318
  ```bash
167
319
  # Hooks handle everything automatically. Manual control:
@@ -210,6 +362,18 @@ jfl services # Interactive TUI (no args)
210
362
  - Service entry in `.jfl/services.json`
211
363
  - Config in service repo (`.jfl/config.json` with `gtm_parent`)
212
364
 
365
+ **Context scoping:** Each service declares what events it produces and consumes. The GTM enforces scope — teams can't read each other's journals unless explicitly granted.
366
+
367
+ ```json
368
+ {
369
+ "context_scope": {
370
+ "produces": ["eval:submission", "journal:my-team*"],
371
+ "consumes": ["eval:scored", "leaderboard:updated"],
372
+ "denied": ["journal:other-team*"]
373
+ }
374
+ }
375
+ ```
376
+
213
377
  **Phone-home on session end:** When a service session ends, it syncs to the parent GTM:
214
378
  - Journal entries copied to `GTM/.jfl/journal/service-{name}-*.jsonl`
215
379
  - Comprehensive sync payload (git stats, health, environment)
@@ -233,6 +397,7 @@ jfl services # Interactive TUI (no args)
233
397
  | `jfl init -n <name>` | Create new GTM workspace |
234
398
  | `jfl status` | Project status and auth |
235
399
  | `jfl hud [-c\|--compact]` | Campaign dashboard (ship date, phases, pipeline) |
400
+ | `jfl doctor [--fix]` | Check project health, auto-repair fixable issues |
236
401
  | `jfl update [--dry]` | Pull latest skills, scripts, templates (preserves CLAUDE.md, .mcp.json) |
237
402
  | `jfl synopsis [hours] [author]` | Work summary (journal + commits + file headers) |
238
403
  | `jfl repair` | Fix corrupted .jfl/config.json |
@@ -251,12 +416,32 @@ jfl services # Interactive TUI (no args)
251
416
  | `jfl context-hub status` | Health check |
252
417
  | `jfl context-hub doctor [--clean]` | Diagnose all projects |
253
418
  | `jfl context-hub ensure-all` | Start for all GTM projects |
254
- | `jfl context-hub dashboard` | Live event/context dashboard |
419
+ | `jfl context-hub dashboard` | Open web dashboard in browser |
255
420
  | `jfl context-hub query` | Query context from CLI |
256
421
  | `jfl context-hub serve` | Run in foreground (daemon mode) |
257
422
  | `jfl context-hub install-daemon` | Auto-start on boot |
258
423
  | `jfl context-hub uninstall-daemon` | Remove auto-start |
259
424
 
425
+ ### Eval Framework
426
+
427
+ | Command | Description |
428
+ |---------|-------------|
429
+ | `jfl eval list [-a agent] [-l limit]` | List recent eval entries |
430
+ | `jfl eval trajectory -a <agent>` | Composite score trajectory with sparkline |
431
+ | `jfl eval log -a <agent> -m <metrics>` | Log an eval entry |
432
+ | `jfl eval compare` | Side-by-side agent comparison |
433
+ | `jfl eval tuples [--limit N] [--format json]` | Extract training tuples from journals |
434
+
435
+ ### Portfolio
436
+
437
+ | Command | Description |
438
+ |---------|-------------|
439
+ | `jfl portfolio register <path>` | Register GTM workspace in portfolio |
440
+ | `jfl portfolio list` | List child GTMs with health status |
441
+ | `jfl portfolio unregister <name>` | Remove GTM from portfolio |
442
+ | `jfl portfolio status` | Portfolio health and eval summary |
443
+ | `jfl portfolio phone-home` | Report GTM health to portfolio parent |
444
+
260
445
  ### Memory
261
446
 
262
447
  | Command | Description |
@@ -290,12 +475,31 @@ jfl services # Interactive TUI (no args)
290
475
 
291
476
  | Command | Description |
292
477
  |---------|-------------|
478
+ | `jfl agent init <name> [-d desc]` | Scaffold agent (manifest + policy + lifecycle flows) |
479
+ | `jfl agent list` | List registered agents |
480
+ | `jfl agent status <name>` | Show agent health and config |
293
481
  | `jfl ralph [args]` | Ralph-tui agent loop orchestrator |
294
482
  | `jfl peter [action]` | Peter Parker model-routed orchestrator (setup, run, status) |
295
483
  | `jfl orchestrate [name] [--list] [--create <n>]` | Multi-service orchestration workflows |
296
484
  | `jfl dashboard` | Interactive service monitoring TUI |
297
485
  | `jfl events [-p pattern]` | Live MAP event bus dashboard |
298
486
 
487
+ ### Hooks & Flows
488
+
489
+ | Command | Description |
490
+ |---------|-------------|
491
+ | `jfl hooks init` | Generate HTTP hooks + default flows |
492
+ | `jfl hooks status` | Check hooks and hub connectivity |
493
+ | `jfl hooks remove` | Remove HTTP hooks |
494
+ | `jfl hooks deploy` | Deploy hooks to all registered services |
495
+ | `jfl flows list` | List configured event-action flows |
496
+ | `jfl flows add` | Interactive flow builder |
497
+ | `jfl flows test <name>` | Test a flow with synthetic event |
498
+ | `jfl flows enable/disable <name>` | Toggle flows |
499
+ | `jfl scope list` | View service context scopes |
500
+ | `jfl scope set` | Set scope declarations |
501
+ | `jfl scope test` | Test scope enforcement |
502
+
299
503
  ### Platform
300
504
 
301
505
  | Command | Description |
@@ -313,7 +517,7 @@ jfl services # Interactive TUI (no args)
313
517
  |---------|-------------|
314
518
  | `jfl telemetry status` | Show telemetry status |
315
519
  | `jfl telemetry show` | Show queued events |
316
- | `jfl telemetry digest [--hours N] [--format json] [--platform]` | Cost breakdown, health analysis, suggestions |
520
+ | `jfl telemetry digest [--hours N] [--format json] [--plots]` | Cost breakdown, health analysis, terminal charts |
317
521
  | `jfl telemetry reset` | Reset install ID |
318
522
  | `jfl telemetry track --category <c> --event <e>` | Emit event from shell scripts |
319
523
  | `jfl improve [--dry-run] [--auto] [--hours N]` | Self-improvement loop: analyze, suggest, create issues |
@@ -321,7 +525,7 @@ jfl services # Interactive TUI (no args)
321
525
 
322
526
  **Model cost tracking:** Every Stratus API call emits token counts and estimated cost. Covers claude-opus-4-6, claude-sonnet-4-6, claude-sonnet-4-5, claude-haiku-3-5, gpt-4o.
323
527
 
324
- **`jfl telemetry digest`** analyzes local events: per-model cost tables, command stats, error rates, hub/memory/session health. Flags issues like high MCP latency, cost concentration, crash rates.
528
+ **`jfl telemetry digest`** analyzes local events: per-model cost tables, command stats, error rates, hub/memory/session health. `--plots` renders bar charts via kuva (falls back to ASCII).
325
529
 
326
530
  **`jfl improve`** generates actionable suggestions from the digest. `--dry-run` previews, `--auto` creates GitHub issues tagged `[jfl-improve]`.
327
531
 
@@ -455,14 +659,16 @@ Every session MUST write journal entries. Hooks enforce this.
455
659
  "summary": "Built jfl onboard command that registers service repos in GTM",
456
660
  "detail": "Creates agent definition, skill wrapper, services.json entry...",
457
661
  "files": ["src/commands/onboard.ts"],
458
- "incomplete": ["peer sync not wired"],
459
- "next": "Wire phone-home on session end"
662
+ "hypothesis": "Structured onboarding reduces setup errors",
663
+ "outcome": "confirmed",
664
+ "score_delta": 0.12,
665
+ "eval_snapshot": {"composite": 0.85}
460
666
  }
461
667
  ```
462
668
 
463
669
  **Write entries when:** Feature completed, decision made, bug fixed, milestone reached, session ending.
464
670
 
465
- Entries become searchable via `jfl memory search` and MCP `memory_search` tool.
671
+ Entries become searchable via `jfl memory search` and MCP `memory_search` tool. RL fields (`hypothesis`, `outcome`, `score_delta`, `eval_snapshot`, `diff_hash`, `context_entries`) enable trajectory-based learning.
466
672
 
467
673
  ---
468
674
 
@@ -482,13 +688,63 @@ SessionStart hook fires You work normally Stop hook fire
482
688
  ├─ Serves MCP tools to Claude Code
483
689
  ├─ Aggregates journal + knowledge + code
484
690
  ├─ Bridges service events from file-drop
485
- └─ Watches journal/ for live entries
691
+ ├─ Watches journal/ for live entries
692
+ ├─ Portfolio mode: fans out to child hubs
693
+ ├─ Flow engine: reactive trigger→action
694
+ └─ Web dashboard at /dashboard/
486
695
  ```
487
696
 
488
697
  **Everything is files.** No proprietary database. No lock-in. Context is git-native — version controlled, portable, model-agnostic.
489
698
 
490
699
  ---
491
700
 
701
+ ## CI/CD
702
+
703
+ Two GitHub Actions workflows handle quality and releases.
704
+
705
+ ### CI — `.github/workflows/ci.yml`
706
+
707
+ Runs on every push and PR to `main`:
708
+
709
+ - TypeScript strict mode type checking
710
+ - Full test suite (~365 tests across 17 test files)
711
+ - Coverage report uploaded as artifact
712
+
713
+ ### CD — `.github/workflows/release.yml`
714
+
715
+ Fires after CI passes on `main`. Uses [Changesets](https://github.com/changesets/changesets) for version management and npm Trusted Publisher (OIDC) for secretless publishing.
716
+
717
+ **Auto-changeset generation:** `scripts/generate-changesets.sh` converts conventional commit messages into changesets automatically:
718
+ - `feat:` = minor bump
719
+ - `fix:` = patch bump
720
+ - `feat!:` = major bump
721
+
722
+ No manual `npx changeset` needed for most changes.
723
+
724
+ **Release flow:**
725
+
726
+ ```bash
727
+ # Option A: Manual changeset
728
+ npx changeset # pick bump level, write summary
729
+
730
+ # Option B: Just use conventional commits — auto-generated on CI
731
+
732
+ # Push to main — CI runs, then release.yml fires
733
+ # → changesets/action creates a "Version Packages" PR
734
+
735
+ # Merge the Version PR
736
+ # → release.yml fires again → npm publish --provenance --access public
737
+ ```
738
+
739
+ No `NPM_TOKEN` needed. Publishing uses OIDC provenance via npm Trusted Publisher.
740
+
741
+ **One-time setup (per package):**
742
+ > npmjs.com > `jfl` package > Settings > Publish Access > Add Provenance
743
+ > - Repository: `402goose/jfl-cli`
744
+ > - Workflow: `.github/workflows/release.yml`
745
+
746
+ ---
747
+
492
748
  ## Auto-Update
493
749
 
494
750
  JFL checks for npm updates on session start (24-hour cache):
@@ -524,6 +780,30 @@ jfl wallet # Wallet and day pass status
524
780
 
525
781
  ## What's New
526
782
 
783
+ **0.3.0**
784
+ - Feat: **Portfolio workspace type** — `jfl portfolio register/list/unregister/status/phone-home`. Portfolios contain multiple GTM workspaces with cross-product event routing via SSE, context scope enforcement (produces/consumes/denied), fan-out queries to child hubs, and portfolio-level leaderboard aggregation
785
+ - Feat: **Dashboard V2** — pre-built Vite + Preact + Tailwind SPA served at `/dashboard/`. Pages: Overview (activity charts, metric cards), Journal (search + type filters), Events (pattern filter presets), Services (type badges, context scope, data flows), Flows (definitions + execution history), Health (system metrics, memory index), Agents (eval leaderboards grouped by domain)
786
+ - Feat: **Eval framework** — `jfl eval list/trajectory/log/compare/tuples`. Track agent metrics over time with composite scores, dual-write up parent chain, extract (state, action, reward) training tuples. Agents grouped by metric domain (ProductRank: ndcg@10/mrr/precision@5, SEO: avg_rank/keywords_ranked)
787
+ - Feat: **RL infrastructure (Phase 1)** — `JournalEntry` type with 6 RL fields, `TrajectoryLoader` for querying experiment history, `query_experiment_history` MCP tool
788
+ - Feat: **Flow engine** — declarative trigger-action automation in `.jfl/flows.yaml`. Actions: log, emit, journal, webhook, command, spawn. Gates: time-gated, deadline, requires_approval. Template interpolation with `{{child.NAME.port}}`
789
+ - Feat: **HTTP hooks** — Claude Code lifecycle hooks (PostToolUse, Stop, PreCompact, SubagentStart/Stop) POST to Context Hub. `jfl hooks init/status/remove/deploy`
790
+ - Feat: **Context scope enforcement** — produces/consumes/denied patterns. Event bus filters by scope declarations. `jfl scope list/set/test`
791
+ - Feat: CI/CD pipeline — GitHub Actions CI (strict TypeScript + Jest gate) + CD via Changesets with auto-generation from conventional commits. npm Trusted Publisher with OIDC provenance
792
+ - Feat: Service agent templates (CLAUDE.md, settings.json, knowledge docs)
793
+ - Feat: Session cleanup guard — prevents `rm -rf` on main when no worktrees exist
794
+ - Fix: TypeScript strict mode build errors resolved
795
+ - Test: ~365 tests across 17 test files (up from 237)
796
+
797
+ **0.2.5**
798
+ - Feat: Docker-style grouped `jfl --help` — 5 groups (Getting Started, Daily Use, Management, Platform, Advanced), ~30 lines down from 52
799
+ - Feat: `jfl doctor [--fix]` — unified project health checker (9 checks: .jfl dir, config, Context Hub, hooks, memory, journal, agents, flows, git). Auto-repairs hooks, config, and journal with `--fix`
800
+ - Feat: `jfl agent init|list|status` — scaffold narrowly-scoped agents with manifest, policy, and lifecycle flows
801
+ - Feat: Flow engine scans `.jfl/flows/*.yaml` for per-agent flow definitions
802
+ - Feat: Kuva terminal plots + spawn action type in flow engine
803
+ - Fix: Stop committing JFL runtime files (.jfl/logs/, memory.db, *.pid) — gitignore + untrack ([@hathbanger](https://github.com/hathbanger) [#5](https://github.com/402goose/jfl-cli/pull/5))
804
+ - Fix: Enforce `jfl update --auto` on session start with 24h cache ([@hathbanger](https://github.com/hathbanger) [#5](https://github.com/402goose/jfl-cli/pull/5))
805
+ - Test: 31 new tests (agent-manifest, doctor, agent command, flow-engine directory scan)
806
+
527
807
  **0.2.4**
528
808
  - Feat: `jfl telemetry digest` — per-model cost tables, command stats, health analysis, improvement suggestions
529
809
  - Feat: `jfl improve` — self-improvement loop with GitHub issue creation (`--auto`)
@@ -1 +1 @@
1
- {"version":3,"file":"context-hub.d.ts","sourceRoot":"","sources":["../../src/commands/context-hub.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAoiCH,wBAAgB,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,CAiBjF;AA2ND,wBAAsB,qBAAqB,CAAC,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAiHxF;AAMD,wBAAsB,iBAAiB,CACrC,MAAM,CAAC,EAAE,MAAM,EACf,OAAO,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,iBAwenE"}
1
+ {"version":3,"file":"context-hub.d.ts","sourceRoot":"","sources":["../../src/commands/context-hub.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAg8CH,wBAAgB,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,CAiBjF;AA2ND,wBAAsB,qBAAqB,CAAC,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAiHxF;AAMD,wBAAsB,iBAAiB,CACrC,MAAM,CAAC,EAAE,MAAM,EACf,OAAO,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,iBA+fnE"}