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.
- package/README.md +308 -28
- package/dist/commands/context-hub.d.ts.map +1 -1
- package/dist/commands/context-hub.js +428 -27
- package/dist/commands/context-hub.js.map +1 -1
- package/dist/commands/eval.d.ts +6 -0
- package/dist/commands/eval.d.ts.map +1 -0
- package/dist/commands/eval.js +236 -0
- package/dist/commands/eval.js.map +1 -0
- package/dist/commands/flows.d.ts +4 -1
- package/dist/commands/flows.d.ts.map +1 -1
- package/dist/commands/flows.js +160 -1
- package/dist/commands/flows.js.map +1 -1
- package/dist/commands/init.d.ts.map +1 -1
- package/dist/commands/init.js +272 -145
- package/dist/commands/init.js.map +1 -1
- package/dist/commands/peter.d.ts.map +1 -1
- package/dist/commands/peter.js +220 -1
- package/dist/commands/peter.js.map +1 -1
- package/dist/commands/pi.d.ts +21 -0
- package/dist/commands/pi.d.ts.map +1 -0
- package/dist/commands/pi.js +154 -0
- package/dist/commands/pi.js.map +1 -0
- package/dist/commands/portfolio.d.ts +6 -0
- package/dist/commands/portfolio.d.ts.map +1 -0
- package/dist/commands/portfolio.js +249 -0
- package/dist/commands/portfolio.js.map +1 -0
- package/dist/commands/predict.d.ts +6 -0
- package/dist/commands/predict.d.ts.map +1 -0
- package/dist/commands/predict.js +234 -0
- package/dist/commands/predict.js.map +1 -0
- package/dist/commands/scope.d.ts +1 -0
- package/dist/commands/scope.d.ts.map +1 -1
- package/dist/commands/scope.js +189 -2
- package/dist/commands/scope.js.map +1 -1
- package/dist/commands/synopsis.d.ts +44 -0
- package/dist/commands/synopsis.d.ts.map +1 -1
- package/dist/commands/synopsis.js +1 -1
- package/dist/commands/synopsis.js.map +1 -1
- package/dist/commands/update.d.ts.map +1 -1
- package/dist/commands/update.js +49 -1
- package/dist/commands/update.js.map +1 -1
- package/dist/commands/viz.d.ts +7 -0
- package/dist/commands/viz.d.ts.map +1 -0
- package/dist/commands/viz.js +460 -0
- package/dist/commands/viz.js.map +1 -0
- package/dist/commands/voice.js.map +1 -1
- package/dist/dashboard/index.d.ts +4 -5
- package/dist/dashboard/index.d.ts.map +1 -1
- package/dist/dashboard/index.js +57 -119
- package/dist/dashboard/index.js.map +1 -1
- package/dist/dashboard-static/assets/index-B6kRK9Rq.js +116 -0
- package/dist/dashboard-static/assets/index-BpdKJPLu.css +1 -0
- package/dist/dashboard-static/index.html +16 -0
- package/dist/index.js +120 -20
- package/dist/index.js.map +1 -1
- package/dist/lib/eval-store.d.ts +15 -0
- package/dist/lib/eval-store.d.ts.map +1 -0
- package/dist/lib/eval-store.js +179 -0
- package/dist/lib/eval-store.js.map +1 -0
- package/dist/lib/flow-engine.d.ts +13 -0
- package/dist/lib/flow-engine.d.ts.map +1 -1
- package/dist/lib/flow-engine.js +164 -3
- package/dist/lib/flow-engine.js.map +1 -1
- package/dist/lib/hub-client.d.ts +80 -0
- package/dist/lib/hub-client.d.ts.map +1 -0
- package/dist/lib/hub-client.js +46 -0
- package/dist/lib/hub-client.js.map +1 -0
- package/dist/lib/predictor.d.ts +99 -0
- package/dist/lib/predictor.d.ts.map +1 -0
- package/dist/lib/predictor.js +394 -0
- package/dist/lib/predictor.js.map +1 -0
- package/dist/lib/service-gtm.d.ts +88 -44
- package/dist/lib/service-gtm.d.ts.map +1 -1
- package/dist/lib/service-gtm.js +451 -243
- package/dist/lib/service-gtm.js.map +1 -1
- package/dist/lib/telemetry-agent.d.ts +57 -0
- package/dist/lib/telemetry-agent.d.ts.map +1 -0
- package/dist/lib/telemetry-agent.js +268 -0
- package/dist/lib/telemetry-agent.js.map +1 -0
- package/dist/lib/telemetry-digest.d.ts.map +1 -1
- package/dist/lib/telemetry-digest.js +17 -17
- package/dist/lib/telemetry-digest.js.map +1 -1
- package/dist/lib/telemetry.d.ts +1 -0
- package/dist/lib/telemetry.d.ts.map +1 -1
- package/dist/lib/telemetry.js +14 -6
- package/dist/lib/telemetry.js.map +1 -1
- package/dist/lib/trajectory-loader.d.ts +82 -0
- package/dist/lib/trajectory-loader.d.ts.map +1 -0
- package/dist/lib/trajectory-loader.js +406 -0
- package/dist/lib/trajectory-loader.js.map +1 -0
- package/dist/mcp/context-hub-mcp.js +60 -0
- package/dist/mcp/context-hub-mcp.js.map +1 -1
- package/dist/mcp/service-registry-mcp.js +0 -0
- package/dist/types/eval.d.ts +18 -0
- package/dist/types/eval.d.ts.map +1 -0
- package/dist/types/eval.js +5 -0
- package/dist/types/eval.js.map +1 -0
- package/dist/types/journal.d.ts +133 -0
- package/dist/types/journal.d.ts.map +1 -0
- package/dist/types/journal.js +59 -0
- package/dist/types/journal.js.map +1 -0
- package/dist/types/map.d.ts +1 -1
- package/dist/types/map.d.ts.map +1 -1
- package/dist/types/map.js.map +1 -1
- package/dist/ui/service-dashboard.js.map +1 -1
- package/dist/utils/jfl-paths.d.ts +1 -0
- package/dist/utils/jfl-paths.d.ts.map +1 -1
- package/dist/utils/jfl-paths.js +1 -0
- package/dist/utils/jfl-paths.js.map +1 -1
- package/dist/utils/wallet.js.map +1 -1
- package/package.json +7 -2
- package/scripts/generate-changesets.sh +113 -0
- package/scripts/migrate-to-branch-sessions.sh +201 -0
- package/scripts/pp-branch-pr.sh +115 -0
- package/scripts/session/session-cleanup.sh +29 -14
- package/scripts/session/session-end.sh +0 -10
- package/scripts/session/session-init.sh +0 -16
- package/scripts/session/session-sync.sh +0 -10
- package/template/.jfl/flows-self-driving.yaml +170 -0
- package/template/THEORY.md +26 -0
- package/template/scripts/session/session-cleanup.sh +28 -10
- package/dist/dashboard/components.d.ts +0 -7
- package/dist/dashboard/components.d.ts.map +0 -1
- package/dist/dashboard/components.js +0 -163
- package/dist/dashboard/components.js.map +0 -1
- package/dist/dashboard/pages.d.ts +0 -7
- package/dist/dashboard/pages.d.ts.map +0 -1
- package/dist/dashboard/pages.js +0 -742
- package/dist/dashboard/pages.js.map +0 -1
- package/dist/dashboard/styles.d.ts +0 -7
- package/dist/dashboard/styles.d.ts.map +0 -1
- package/dist/dashboard/styles.js +0 -497
- 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
|
|
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
|
-
|
|
61
|
+
visa-portfolio/ <- Portfolio (strategy, cross-product RL, data flow)
|
|
62
62
|
├── .jfl/
|
|
63
|
-
│ ├── config.json <-
|
|
64
|
-
│ ├──
|
|
65
|
-
│ ├──
|
|
66
|
-
│
|
|
67
|
-
│
|
|
68
|
-
├──
|
|
69
|
-
├──
|
|
70
|
-
├──
|
|
71
|
-
├── .
|
|
72
|
-
│ ├──
|
|
73
|
-
│ ├── agents/
|
|
74
|
-
│
|
|
75
|
-
|
|
76
|
-
├──
|
|
77
|
-
|
|
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
|
-
-
|
|
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 #
|
|
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`
|
|
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
|
-
- **
|
|
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` |
|
|
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] [--
|
|
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.
|
|
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
|
-
"
|
|
459
|
-
"
|
|
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
|
-
|
|
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;
|
|
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"}
|