jfl 0.3.0 → 0.4.3

package/README.md

@@ -1,8 +1,10 @@
 # JFL - Just Fucking Launch
 
-**The context layer for AI-native teams.**
+[![npm version](https://img.shields.io/npm/v/jfl.svg)](https://www.npmjs.com/package/jfl)
 
-JFL provides persistent context for AI workflows. Agents read what happened in previous sessions, understand decisions made, and access project knowledge — eliminating the cold-start problem where each AI interaction begins from zero.
+**The engineering intelligence platform.**
+
+JFL provides persistent context, autonomous agents, and self-driving improvement loops for any project. Agents read past sessions, understand decisions, track eval scores, and propose improvements — all backed by structured files in git.
 
 Context lives in git as structured files (markdown, JSONL). Any AI tool can integrate via MCP.
 
@@ -16,8 +18,9 @@ AI agents are stateless. Each session starts from scratch:
 - Previous decisions aren't remembered
 - Work from other sessions isn't visible
 - Context has to be re-explained every time
+- Agent improvements aren't measured or tracked
 
-JFL provides a shared context layer that accumulates over time and is accessible to any AI tool.
+JFL provides a shared context layer that accumulates over time, measures agent performance, and enables autonomous improvement loops — accessible to any AI tool.
 
 ---
 
@@ -55,28 +58,37 @@ That's it. SessionStart hooks handle repo sync, session branching, Context Hub s
 
 ## Architecture
 
-JFL workspaces are **context layers**, not code repos. Product code lives in separate service repos that register with the GTM.
+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.
 
 ```
-my-project/                    <- GTM workspace (strategy, context, orchestration)
+visa-portfolio/                <- Portfolio (strategy, cross-product RL, data flow)
 ├── .jfl/
-│   ├── config.json           <- Project config (team, services, ports)
-│   ├── journal/              <- Session journals (JSONL, one file per session)
-│   ├── memory.db             <- Indexed memory (TF-IDF + embeddings)
-│   ├── agents/              <- Narrowly-scoped agent manifests + policies
-│   ├── flows/               <- Per-agent flow definitions (auto-loaded)
-│   ├── service-events.jsonl  <- Event bus file-drop
-│   └── services.json         <- Registered services
-├── knowledge/                <- Strategy docs (VISION, ROADMAP, THESIS, etc.)
-├── content/                  <- Generated content
-├── suggestions/              <- Per-contributor workspaces
-├── .claude/
-│   ├── settings.json         <- Claude Code hooks (SessionStart, Stop, etc.)
-│   ├── agents/               <- Service agent definitions
-│   └── skills/               <- Slash commands (/hud, /content, etc.)
-├── scripts/session/          <- Session management (init, sync, cleanup)
-├── CLAUDE.md                 <- AI instructions
-└── .mcp.json                 <- MCP server config (Context Hub)
+│   ├── config.json           <- type: "portfolio", registered child GTMs
+│   ├── eval.jsonl            <- Aggregated eval data from all children
+│   ├── flows.yaml            <- Cross-product event routing
+│   └── journal/              <- Portfolio-level + synced child journals
+│
+├── productrank-gtm/           <- GTM workspace (registered as child)
+│   ├── .jfl/
+│   │   ├── config.json       <- type: "gtm", portfolio_parent, registered services
+│   │   ├── eval.jsonl        <- Eval entries from arena competitions
+│   │   ├── journal/          <- Session journals + synced service journals
+│   │   ├── agents/           <- Agent manifests + policies
+│   │   ├── flows/            <- Per-agent flow definitions
+│   │   └── service-events.jsonl
+│   ├── knowledge/            <- Strategy docs (VISION, ROADMAP, THESIS, etc.)
+│   ├── content/              <- Generated content
+│   ├── suggestions/          <- Per-contributor workspaces
+│   ├── .claude/
+│   │   ├── settings.json     <- Claude Code hooks
+│   │   ├── agents/           <- Service agent definitions
+│   │   └── skills/           <- Slash commands (/hud, /content, etc.)
+│   ├── scripts/session/      <- Session management
+│   ├── CLAUDE.md             <- AI instructions
+│   └── .mcp.json             <- MCP server config
+│
+└── seo-agent/                 <- Another GTM (registered as child)
+    └── ...
 
 my-api/                        <- Service repo (registered in GTM)
 ├── src/
@@ -89,7 +101,8 @@ my-api/                        <- Service repo (registered in GTM)
 - Services work independently
 - Multiple services register to one GTM
 - `jfl update` updates tooling without touching service code
-- Journal entries sync from services to parent GTM
+- Eval data dual-writes up the chain (service > GTM > portfolio)
+- Cross-product event routing at portfolio level
 
 ---
 
@@ -106,14 +119,14 @@ jfl context-hub stop          # Stop daemon
 jfl context-hub restart       # Restart daemon
 jfl context-hub doctor        # Diagnose all projects (OK/ZOMBIE/DOWN/STALE)
 jfl context-hub ensure-all    # Start for all GTM projects
-jfl context-hub dashboard     # Live event + context dashboard
+jfl context-hub dashboard     # Open web dashboard (opens browser)
 jfl context-hub install-daemon  # Auto-start on boot (launchd/systemd)
 jfl context-hub uninstall-daemon  # Remove auto-start
 jfl context-hub query         # Query context from CLI
 jfl context-hub serve         # Run in foreground (daemon mode)
 ```
 
-**Per-project ports** assigned automatically (or set in `.jfl/config.json` → `contextHub.port`).
+**Per-project ports** assigned automatically (or set in `.jfl/config.json` > `contextHub.port`).
 
 **MCP Tools** (available to Claude Code and any MCP client):
 
@@ -126,9 +139,38 @@ jfl context-hub serve         # Run in foreground (daemon mode)
 | `memory_search` | Search indexed journal memories |
 | `memory_status` | Memory system statistics |
 | `memory_add` | Add manual memory entry |
+| `events_publish` | Publish event to MAP event bus |
+| `events_recent` | Get recent events (with pattern filter) |
+| `query_experiment_history` | Query RL trajectories for agent experiments |
 
 **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.
 
+### Dashboard
+
+A pre-built Vite + Preact + Tailwind SPA served by Context Hub at `/dashboard/`. Auto-detects workspace type and adapts layout.
+
+**Pages:**
+
+| Page | What It Shows |
+|------|--------------|
+| **Overview** | Activity charts, product cards, metric cards |
+| **Journal** | Searchable journal entries with type filters |
+| **Events** | Live event feed with pattern filter presets (eval, session, flow, etc.) |
+| **Services** | Registered services with type badges, context scope visualization, data flows |
+| **Flows** | Flow definitions and execution history |
+| **Health** | System metrics, context sources, memory index, tracked projects |
+| **Agents** | Eval leaderboards grouped by product domain |
+| **Experiments** | Experiment runs with dot plots — green (improved) / gray (no change) / red (regression) |
+| **Telemetry** | Cost breakdown, command usage, error rates, hub health metrics |
+| **Topology** | Service dependency graph and event flow visualization |
+
+**Features:** Sidebar with structured sections (Workspace / Infra / Eval), inline SVG icons, agent leaderboard in sidebar, sparkline charts, real-time polling.
+
+```bash
+jfl context-hub dashboard     # Opens /dashboard/ in browser
+jfl viz dash                  # Terminal equivalent (no browser needed)
+```
+
 ### MAP Event Bus
 
 Metrics, Agents, Pipeline — an in-process event bus inside Context Hub.
@@ -138,10 +180,207 @@ Metrics, Agents, Pipeline — an in-process event bus inside Context Hub.
 - **Journal bridge** — watches `.jfl/journal/`, emits events on new entries
 - **Pattern-matching subscriptions** (glob support)
 - **Transports:** SSE, WebSocket, HTTP polling
-- **Event types:** `session:started`, `session:ended`, `task:completed`, `journal:entry`, `service:healthy`, `custom`, and more
+- **Cross-product routing** — portfolio flows route events between child GTMs
+- **Event types:** `session:started`, `session:ended`, `eval:scored`, `journal:entry`, `flow:triggered`, `agent:iteration-complete`, `portfolio:phone-home`, `review:findings`, `telemetry:insight`, `peter:pr-proposed`, and more
 
 Services emit events by appending to `.jfl/service-events.jsonl` — no auth needed, Context Hub watches the file automatically.
 
+### Eval Framework
+
+Track agent performance over time. Eval entries dual-write up the parent chain (service > GTM > portfolio) so every level has visibility.
+
+```bash
+jfl eval list                 # List recent eval entries
+jfl eval list -a shadow       # Filter by agent
+jfl eval trajectory -a shadow # Composite score over time (with sparkline)
+jfl eval log -a shadow -m '{"composite":0.69}' # Log an eval entry
+jfl eval compare              # Side-by-side agent comparison
+jfl eval tuples               # Extract (state, action, reward) training tuples
+```
+
+**Eval entries** are JSONL with agent name, metrics, composite score, model version, and deltas:
+
+```json
+{
+  "v": 1, "ts": "2026-03-05T15:22:47Z",
+  "agent": "productrank-shadow",
+  "dataset": "vibe-50-v1",
+  "model_version": "shadow-0.3.1",
+  "metrics": {"ndcg@10": 0.59, "mrr": 0.77, "precision@5": 0.43},
+  "composite": 0.6935,
+  "delta": {"composite": -0.029}
+}
+```
+
+**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.
+
+**Training tuples** extracted from journals for fine-tuning: `(state, action, reward)` — maps codebase state + experiment action to eval score delta.
+
+**API endpoints** on Context Hub:
+- `GET /api/eval/leaderboard` — all agents ranked by composite
+- `GET /api/eval/trajectory?agent=X&metric=composite` — score trajectory with timestamps
+
+### Self-Driving Loop
+
+The autonomous improvement cycle. Agents detect issues, create fixes, and the system auto-merges if eval scores improve.
+
+```
+Telemetry Agent detects issue
+  → telemetry:insight event
+    → Flow engine routes to Peter Parker
+      → PP creates fix PR (pp/ branch)
+        → GitHub Action runs eval + AI review
+          → eval:scored event posted to hub
+            → Auto-merge if improved / flag if regressed
+              → Training tuple logged
+                → Cycle repeats
+```
+
+**9 declarative flows** in `.jfl/flows/self-driving.yaml`:
+
+| Flow | Trigger | Action |
+|------|---------|--------|
+| `auto-merge-on-improvement` | `eval:scored` (improved) | `gh pr merge` + journal milestone |
+| `flag-regression` | `eval:scored` (regressed) | `gh pr review --request-changes` |
+| `log-training-tuple` | `eval:scored` | Log (state, action, reward) to journal |
+| `log-quality-training-tuple` | `eval:scored` | Enriched tuple with AI quality dimensions |
+| `block-merge-on-blockers` | `review:findings` (red) | `gh pr review --request-changes` |
+| `log-review-training-data` | `review:findings` | Log review results as training data |
+| `pp-address-review-blockers` | `review:findings` (red) | Spawn PP to fix (gated, max 3 iterations) |
+| `insight-triggers-pp` | `telemetry:insight` (high) | Spawn PP to create fix PR |
+| `predict-before-pr` | `peter:pr-proposed` | Run Stratus prediction before acting |
+
+**Review gate:** Eval checks for AI review blockers before auto-merging. If the AI review requested changes (red findings), eval holds the merge even if tests improved. PRs must pass both eval AND review to auto-merge.
+
+**CI Workflows** that close the loop:
+
+- **`jfl-eval.yml`** — Runs on PP pull requests (`pp/` prefix). Checks out main for baseline, runs tests on PR, computes delta, runs AI quality assessment, posts `eval:scored` event to hub, comments on PR with eval results.
+- **`jfl-review.yml`** — Context-aware AI code review on PP PRs. Gathers project context + knowledge docs, reviews diff for bugs/security/architecture, extracts structured findings (red/yellow/blue severity), posts `review:findings` event to hub.
+
+### Stratus Prediction Engine
+
+Predict eval score deltas before executing changes using the Stratus world model (JEPA rollout + chat ensemble).
+
+```bash
+jfl predict run --proposal "Fix auth timeout" --goal "improve test pass rate" --type fix --scope small
+jfl predict resolve --id <id> --actual-delta 0.05 --actual-score 0.92 --eval-run <run-id>
+jfl predict accuracy            # Direction accuracy, mean delta error, calibration
+jfl predict history             # Recent predictions with sparkline trend
+```
+
+**Dual Stratus strategy:**
+- **Rollout API** (`/v1/rollout`) — JEPA world model, ~1.6s, ~$0.001. Fast state prediction for health trajectory.
+- **Chat API** (`/v1/chat/completions`) — Full reasoning, ~28s, ~$0.05. Human-readable insights when patterns detected.
+
+### RL Infrastructure
+
+JFL generalizes the Karpathy nanochat pattern: structured journals are the replay buffer, eval scores are rewards, agents learn in-context from past trajectories.
+
+```
+Agent LLM (Policy)        > reads trajectories, proposes experiments
+Stratus (World Model)     > predicts outcomes, filters bad proposals
+Journals (Replay Buffer)  > structured experiment history
+Eval Framework (Reward)   > composite scores, score deltas
+Event Bus (Nervous System) > connects everything
+Telemetry Agent           > autonomous health monitoring + anomaly detection
+```
+
+**JournalEntry type** — canonical schema with 6 RL fields: `hypothesis`, `outcome`, `score_delta`, `eval_snapshot`, `diff_hash`, `context_entries`.
+
+**TrajectoryLoader** — query, filter, and render experiment trajectories for agent context windows. Supports filtering by session, agent, outcome, score range.
+
+**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. Creates PRs on `pp/` branches.
+
+**Flow Engine** — declarative trigger-action automation in `.jfl/flows.yaml` and `.jfl/flows/*.yaml`:
+
+```yaml
+- name: eval-scored-trigger-analysis
+  trigger:
+    pattern: "eval:scored"
+  gate:
+    requires_approval: true
+  actions:
+    - type: spawn
+      command: "claude -p 'Analyze the latest eval results'"
+```
+
+Flow actions: `log`, `emit`, `journal`, `webhook`, `command`, `spawn`. Gates: `after` (time-gated), `before` (deadline), `requires_approval`.
+
+**MCP tool:** `query_experiment_history` — agents query past experiment trajectories to inform next proposals.
+
+### Telemetry Agent
+
+Autonomous monitoring agent that runs inside Context Hub on a configurable interval.
+
+- Analyzes local telemetry events for patterns
+- Detects anomalies: cost spikes (2x baseline), error spikes (3x baseline)
+- Calls Stratus rollout API for JEPA health trajectory prediction
+- Tracks `brain_goal_proximity` over time (product health score)
+- Emits `telemetry:insight` events that trigger the self-driving loop
+- State persisted at `.jfl/telemetry-agent-state.json`
+
+**Insight types:** `anomaly`, `regression`, `cost_spike`, `pattern`, `stratus_prediction`
+
+### Terminal Visualizations
+
+Headless dashboard data rendered in the terminal via `jfl viz`. No browser needed — same data as the web dashboard.
+
+```bash
+jfl viz dash                  # Composite: leaderboard + flows + events + status
+jfl viz experiments           # Experiment runs with dot plot and sparklines
+jfl viz leaderboard           # Ranked agents with bar chart
+jfl viz flows                 # Flow definitions and pending executions
+jfl viz events                # Recent event stream with type coloring
+jfl viz status                # Hub health and sources
+```
+
+All subcommands support `--json` for programmatic consumption. Uses kuva for rich terminal plots with ASCII fallback.
+
+### Portfolio Management
+
+Coordinate multiple GTM workspaces under one portfolio.
+
+```bash
+jfl portfolio register /path/to/gtm   # Register a GTM in this portfolio
+jfl portfolio list                     # List child GTMs with health
+jfl portfolio unregister <name>        # Remove a GTM
+jfl portfolio status                   # Portfolio health + eval summary
+jfl portfolio phone-home               # Report GTM health to portfolio parent
+```
+
+**Portfolio Context Hub** operates in fan-out mode:
+- Connects to child GTM hubs via SSE
+- Bridges child events into portfolio event bus
+- Fans out search queries across all child hubs
+- Aggregates eval leaderboard across products
+- Enforces context scope (produces/consumes/denied) between GTMs
+
+**Cross-product flows** defined in `.jfl/flows.yaml`:
+
+```yaml
+- name: tool-trends-to-seo
+  trigger:
+    pattern: "discovery:tool-trend"
+    source: "productrank-gtm"
+  actions:
+    - type: webhook
+      url: "http://localhost:{{child.seo-agent.port}}/api/events"
+```
+
+Template variables: `{{child.NAME.port}}`, `{{child.NAME.token}}`
+
+**Context scope** — each child GTM declares what events it produces and consumes. Portfolio enforces boundaries:
+
+```json
+{
+  "context_scope": {
+    "produces": ["discovery:tool-trend", "eval:*"],
+    "consumes": ["strategy:*", "seo:serp-data"],
+    "denied": []
+  }
+}
+```
+
 ### Memory System
 
 Hybrid search over all journal entries with TF-IDF (40%) + semantic embeddings (60%).
@@ -164,6 +403,7 @@ Automatic session isolation for parallel work:
 - **Multiple concurrent sessions:** Isolated git worktrees prevent conflicts
 - **Auto-commit:** Saves work every 2 minutes (knowledge, journal, suggestions)
 - **Crash recovery:** Detects uncommitted work in stale sessions, auto-commits on next start
+- **Cleanup guard:** Prevents `rm -rf` on main branch when no worktrees exist
 
 ```bash
 # Hooks handle everything automatically. Manual control:
@@ -212,6 +452,18 @@ jfl services                  # Interactive TUI (no args)
 - Service entry in `.jfl/services.json`
 - Config in service repo (`.jfl/config.json` with `gtm_parent`)
 
+**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.
+
+```json
+{
+  "context_scope": {
+    "produces": ["eval:submission", "journal:my-team*"],
+    "consumes": ["eval:scored", "leaderboard:updated"],
+    "denied": ["journal:other-team*"]
+  }
+}
+```
+
 **Phone-home on session end:** When a service session ends, it syncs to the parent GTM:
 - Journal entries copied to `GTM/.jfl/journal/service-{name}-*.jsonl`
 - Comprehensive sync payload (git stats, health, environment)
@@ -242,6 +494,7 @@ jfl services                  # Interactive TUI (no args)
 | `jfl validate-settings [--fix] [--json]` | Validate and repair .claude/settings.json |
 | `jfl preferences [--clear-ai] [--show]` | Manage JFL preferences |
 | `jfl profile [action]` | Manage profile (show, edit, export, import, generate) |
+| `jfl ci setup` | Deploy eval + review CI workflows to project |
 | `jfl test` | Test onboarding flow (isolated environment) |
 
 ### Context Hub
@@ -254,12 +507,52 @@ jfl services                  # Interactive TUI (no args)
 | `jfl context-hub status` | Health check |
 | `jfl context-hub doctor [--clean]` | Diagnose all projects |
 | `jfl context-hub ensure-all` | Start for all GTM projects |
-| `jfl context-hub dashboard` | Live event/context dashboard |
+| `jfl context-hub dashboard` | Open web dashboard in browser |
 | `jfl context-hub query` | Query context from CLI |
 | `jfl context-hub serve` | Run in foreground (daemon mode) |
 | `jfl context-hub install-daemon` | Auto-start on boot |
 | `jfl context-hub uninstall-daemon` | Remove auto-start |
 
+### Eval Framework
+
+| Command | Description |
+|---------|-------------|
+| `jfl eval list [-a agent] [-l limit]` | List recent eval entries |
+| `jfl eval trajectory -a <agent>` | Composite score trajectory with sparkline |
+| `jfl eval log -a <agent> -m <metrics>` | Log an eval entry |
+| `jfl eval compare --agents <a,b>` | Side-by-side agent comparison |
+| `jfl eval tuples [--team N] [--since date]` | Extract training tuples from journals |
+
+### Prediction
+
+| Command | Description |
+|---------|-------------|
+| `jfl predict run --proposal <text> --goal <text>` | Predict eval delta for proposed change |
+| `jfl predict resolve --id <id> --actual-delta <n>` | Resolve prediction with actual results |
+| `jfl predict accuracy` | Prediction accuracy stats (direction, delta error, calibration) |
+| `jfl predict history [--limit N]` | Recent predictions with sparkline |
+
+### Visualization
+
+| Command | Description |
+|---------|-------------|
+| `jfl viz dash` | Composite terminal dashboard (default) |
+| `jfl viz experiments [--agent name]` | Experiment runs with dot plot and sparklines |
+| `jfl viz leaderboard` | Ranked agent leaderboard with bar chart |
+| `jfl viz flows [--pending]` | Flow definitions and pending executions |
+| `jfl viz events [--pattern glob] [--limit N]` | Recent events with type coloring |
+| `jfl viz status` | Hub health, children, sources |
+
+### Portfolio
+
+| Command | Description |
+|---------|-------------|
+| `jfl portfolio register <path>` | Register GTM workspace in portfolio |
+| `jfl portfolio list` | List child GTMs with health status |
+| `jfl portfolio unregister <name>` | Remove GTM from portfolio |
+| `jfl portfolio status` | Portfolio health and eval summary |
+| `jfl portfolio phone-home` | Report GTM health to portfolio parent |
+
 ### Memory
 
 | Command | Description |
@@ -296,12 +589,35 @@ jfl services                  # Interactive TUI (no args)
 | `jfl agent init <name> [-d desc]` | Scaffold agent (manifest + policy + lifecycle flows) |
 | `jfl agent list` | List registered agents |
 | `jfl agent status <name>` | Show agent health and config |
+| `jfl peter setup [--cost\|--balanced\|--quality]` | Configure model routing profile |
+| `jfl peter run [--task text]` | Run orchestrator (interactive or headless) |
+| `jfl peter pr --task <text>` | Run agent, create PR on pp/ branch, emit event |
+| `jfl peter experiment` | Proactive: analyze trajectory, pick highest-value task, execute |
+| `jfl peter status` | Show config and recent events |
+| `jfl peter dashboard` | Live event stream TUI |
 | `jfl ralph [args]` | Ralph-tui agent loop orchestrator |
-| `jfl peter [action]` | Peter Parker model-routed orchestrator (setup, run, status) |
 | `jfl orchestrate [name] [--list] [--create <n>]` | Multi-service orchestration workflows |
 | `jfl dashboard` | Interactive service monitoring TUI |
 | `jfl events [-p pattern]` | Live MAP event bus dashboard |
 
+### Hooks & Flows
+
+| Command | Description |
+|---------|-------------|
+| `jfl hooks init` | Generate HTTP hooks + default flows |
+| `jfl hooks status` | Check hooks and hub connectivity |
+| `jfl hooks remove` | Remove HTTP hooks |
+| `jfl hooks deploy` | Deploy hooks to all registered services |
+| `jfl flows list` | List configured event-action flows |
+| `jfl flows add` | Interactive flow builder |
+| `jfl flows test <name>` | Test a flow with synthetic event |
+| `jfl flows enable/disable <name>` | Toggle flows |
+| `jfl flows approve [--flow name] [--all]` | Approve gated flow executions |
+| `jfl scope list` | View service context scopes |
+| `jfl scope set` | Set scope declarations |
+| `jfl scope test` | Test scope enforcement |
+| `jfl scope viz` | ASCII scope graph with access matrix |
+
 ### Platform
 
 | Command | Description |
@@ -312,6 +628,8 @@ jfl services                  # Interactive TUI (no args)
 | `jfl deploy [-f]` | Deploy to JFL platform |
 | `jfl agents [action]` | Manage parallel agents (list, create, start, stop, destroy) |
 | `jfl feedback [action]` | Rate session (0-5), view or sync |
+| `jfl pi [--yolo] [--mode interactive\|rpc\|headless]` | Launch JFL in Pi runtime |
+| `jfl pi agents run [--team yaml]` | Spawn agent team as Pi subprocesses |
 
 ### Telemetry & Intelligence
 
@@ -319,7 +637,7 @@ jfl services                  # Interactive TUI (no args)
 |---------|-------------|
 | `jfl telemetry status` | Show telemetry status |
 | `jfl telemetry show` | Show queued events |
-| `jfl telemetry digest [--hours N] [--format json] [--platform]` | Cost breakdown, health analysis, suggestions |
+| `jfl telemetry digest [--hours N] [--format json] [--plots]` | Cost breakdown, health analysis, terminal charts |
 | `jfl telemetry reset` | Reset install ID |
 | `jfl telemetry track --category <c> --event <e>` | Emit event from shell scripts |
 | `jfl improve [--dry-run] [--auto] [--hours N]` | Self-improvement loop: analyze, suggest, create issues |
@@ -327,7 +645,7 @@ jfl services                  # Interactive TUI (no args)
 
 **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.
 
-**`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.
+**`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).
 
 **`jfl improve`** generates actionable suggestions from the digest. `--dry-run` previews, `--auto` creates GitHub issues tagged `[jfl-improve]`.
 
@@ -418,6 +736,7 @@ Pre-installed slash commands for Claude Code:
 | `/remotion-best-practices` | Remotion video creation in React |
 | `/geo` | GEO-first SEO analysis for AI search engines |
 | `/geo-audit` | Full website GEO+SEO audit with parallel agents |
+| `/viz` | Terminal data visualization via kuva |
 
 ```bash
 # Install more skills
@@ -461,14 +780,16 @@ Every session MUST write journal entries. Hooks enforce this.
   "summary": "Built jfl onboard command that registers service repos in GTM",
   "detail": "Creates agent definition, skill wrapper, services.json entry...",
   "files": ["src/commands/onboard.ts"],
-  "incomplete": ["peer sync not wired"],
-  "next": "Wire phone-home on session end"
+  "hypothesis": "Structured onboarding reduces setup errors",
+  "outcome": "confirmed",
+  "score_delta": 0.12,
+  "eval_snapshot": {"composite": 0.85}
 }
 ```
 
 **Write entries when:** Feature completed, decision made, bug fixed, milestone reached, session ending.
 
-Entries become searchable via `jfl memory search` and MCP `memory_search` tool.
+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.
 
 ---
 
@@ -482,19 +803,78 @@ SessionStart hook fires          You work normally                Stop hook fire
 ├─ Create session branch         ├─ Journal entries auto-tracked  ├─ Auto-commit changes
 ├─ Recover crashed sessions      ├─ Auto-commit every 2 min       ├─ Merge to main
 ├─ Health-check Context Hub      ├─ Events flow to MAP bus        └─ Cleanup branch
-└─ Start auto-commit             └─ Memory indexes continuously
+└─ Start auto-commit             ├─ Memory indexes continuously
+                                 ├─ Telemetry agent monitors
+                                 └─ Flows react to events
 
                     Context Hub (always running)
                     ├─ Serves MCP tools to Claude Code
                     ├─ Aggregates journal + knowledge + code
                     ├─ Bridges service events from file-drop
-                    └─ Watches journal/ for live entries
+                    ├─ Watches journal/ for live entries
+                    ├─ Portfolio mode: fans out to child hubs
+                    ├─ Flow engine: reactive trigger→action
+                    ├─ Telemetry agent: health monitoring
+                    └─ Web dashboard at /dashboard/
 ```
 
 **Everything is files.** No proprietary database. No lock-in. Context is git-native — version controlled, portable, model-agnostic.
 
 ---
 
+## CI/CD
+
+Two GitHub Actions workflows handle quality and releases. Two additional workflows close the self-driving loop.
+
+### CI — `.github/workflows/ci.yml`
+
+Runs on every push and PR to `main`:
+
+- TypeScript strict mode type checking
+- Full test suite (~365 tests across 17 test files)
+- Coverage report uploaded as artifact
+
+### Release — `.github/workflows/release.yml`
+
+Fires after CI passes on `main`. Two paths:
+
+1. **Version bumped** (package.json differs from npm): Build, publish with provenance, create git tag, create GitHub Release with auto-generated notes.
+2. **Version matches npm**: Generate changesets from conventional commits, create "Version Packages" PR via changesets/action.
+
+```bash
+# Option A: Manual changeset
+npx changeset         # pick bump level, write summary
+
+# Option B: Just use conventional commits — auto-generated on CI
+# feat: = minor, fix: = patch, feat!: = major
+
+# Push to main → CI runs → Release publishes or creates Version PR
+```
+
+**Secrets required:** `NPM_TOKEN` (granular access token scoped to jfl package). Provenance attestation via npm Trusted Publisher (OIDC).
+
+### Eval — `.github/workflows/jfl-eval.yml`
+
+Runs on PRs from Peter Parker (`pp/` prefix) or `run-eval` label:
+
+- Baseline test pass rate from `main`
+- PR test pass rate
+- AI quality assessment (correctness, coverage, architecture, value)
+- Posts `eval:scored` event to Context Hub
+- Comments on PR with eval results
+
+### AI Review — `.github/workflows/jfl-review.yml`
+
+Runs on PRs from Peter Parker (`pp/` prefix) or `ai-review` label:
+
+- Gathers project context (config, knowledge docs, journal)
+- Context-aware diff review (bugs, security, architecture, tests)
+- Structured findings with severity (red/yellow/blue)
+- Posts `review:findings` event to Context Hub
+- Comments on PR with findings
+
+---
+
 ## Auto-Update
 
 JFL checks for npm updates on session start (24-hour cache):
@@ -530,6 +910,58 @@ jfl wallet                    # Wallet and day pass status
 
 ## What's New
 
+**0.4.3**
+- Feat: **Self-driving loop proven end-to-end** — eval CI auto-merges improved PRs, requests changes on regressions. First auto-merged PP PR (#16) in 90 seconds
+- Feat: **`jfl peter experiment`** — proactive experiment selection. Analyzes trajectory history + eval trends, uses Stratus to rank proposals (heuristic fallback), picks highest-value task, spawns PP to execute
+- Feat: **`jfl ci setup`** — deploys eval + review CI workflows to any project with secret setup instructions
+- Feat: **Review gate** — eval checks for AI review blockers before auto-merging. PRs must pass both eval AND review
+- Feat: **Cron triggers** in flow engine — `cron:daily`, `cron:hourly`, `cron:every-30-minutes` patterns for proactive flows
+- Feat: **`jfl update` syncs flows** — new flow files deployed on update (merge-only, never overwrites customizations)
+- Fix: Eval CI self-sufficient — commits eval entries + service events to PR branch, no hub dependency for core loop
+- Test: 274 tests (up from 266)
+
+**0.4.2**
+- Fix: HTTP hook port correction — `jfl init` and `jfl update` now detect and fix hooks pointing to wrong Context Hub port
+- Fix: Release pipeline — direct publish when version bumped, changeset generation when version matches npm
+- Fix: npm auth — NPM_TOKEN required (OIDC trusted publisher is for provenance only)
+- Feat: Telemetry archive path fix — telemetry data properly flows to digest
+
+**0.4.1**
+- Feat: **Self-driving loop** — 9 declarative flows in `self-driving.yaml` for autonomous improvement (auto-merge, flag regression, training tuples, review response, telemetry-to-PP dispatch, Stratus prediction gate)
+- Feat: **`jfl predict`** — Stratus prediction engine with run/resolve/accuracy/history subcommands
+- Feat: **`jfl viz`** — terminal visualizations (experiments, leaderboard, flows, events, status, dash)
+- Feat: **`jfl-eval.yml`** — CI workflow for eval on Peter Parker PRs (baseline comparison, AI quality scoring, event posting)
+- Feat: **`jfl-review.yml`** — CI workflow for context-aware AI code review (structured findings, severity levels, event posting)
+- Feat: **Telemetry agent** — autonomous monitoring in Context Hub (anomaly detection, Stratus JEPA health prediction, insight events)
+- Feat: **`spawn` action type** in flow engine — spawn detached subprocesses with cleaned environment
+- Feat: **`flows approve`** subcommand — approve gated flow executions (interactive or batch)
+- Feat: Dashboard pages: **Experiments** (dot plots, sparklines), **Telemetry** (cost/usage/health), **Topology** (service dependency graph)
+- Feat: **`jfl pi`** — Pi AI runtime integration with extensions, skills, and agent team spawning
+- Feat: MCP tools: `events_publish`, `events_recent` for MAP event bus interaction
+
+**0.4.0**
+- Feat: **Peter Parker `pr` subcommand** — run agent, commit, push `pp/` branch, create PR, emit `pr:created` event
+- Feat: **Peter Parker `dashboard`** — live event stream TUI
+- Feat: Richer eval composite with AI quality dimensions (correctness, coverage, architecture, value)
+- Feat: `scope viz` — ASCII scope graph with access matrix and flow visualization
+- Feat: Context-aware AI review with structured findings + severity levels
+- Fix: Baseline eval uses clean checkout (git checkout --force + clean)
+- Test: Predictor unit tests, hub-client test coverage
+
+**0.3.0**
+- 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
+- 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)
+- 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)
+- Feat: **RL infrastructure (Phase 1)** — `JournalEntry` type with 6 RL fields, `TrajectoryLoader` for querying experiment history, `query_experiment_history` MCP tool
+- 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}}`
+- Feat: **HTTP hooks** — Claude Code lifecycle hooks (PostToolUse, Stop, PreCompact, SubagentStart/Stop) POST to Context Hub. `jfl hooks init/status/remove/deploy`
+- Feat: **Context scope enforcement** — produces/consumes/denied patterns. Event bus filters by scope declarations. `jfl scope list/set/test`
+- Feat: CI/CD pipeline — GitHub Actions CI (strict TypeScript + Jest gate) + CD via Changesets with auto-generation from conventional commits
+- Feat: Service agent templates (CLAUDE.md, settings.json, knowledge docs)
+- Feat: Session cleanup guard — prevents `rm -rf` on main when no worktrees exist
+- Fix: TypeScript strict mode build errors resolved
+- Test: ~365 tests across 17 test files (up from 237)
+
 **0.2.5**
 - Feat: Docker-style grouped `jfl --help` — 5 groups (Getting Started, Daily Use, Management, Platform, Advanced), ~30 lines down from 52
 - 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`
@@ -583,6 +1015,7 @@ jfl wallet                    # Wallet and day pass status
 
 ```bash
 OPENAI_API_KEY=sk-...         # Optional: enables semantic embeddings for memory search
+STRATUS_API_KEY=stratus_...   # Optional: enables Stratus prediction engine + telemetry agent
 CONTEXT_HUB_PORT=4242         # Override per-project port
 CRM_SHEET_ID=your-sheet-id    # Google Sheets CRM integration
 JFL_PLATFORM_URL=...          # JFL platform URL (default: jfl.run)
@@ -600,4 +1033,4 @@ MIT License - see LICENSE file.
 
 Built by [@tagga](https://x.com/taggaoyl) (Alec Taggart)
 
-Powered by [Claude](https://claude.ai) (Anthropic), [x402](https://x402.org) (crypto micropayments), Commander.js, sql.js, and more.
+Powered by [Claude](https://claude.ai) (Anthropic), [Stratus](https://stratus.run) (JEPA world model), [x402](https://x402.org) (crypto micropayments), Commander.js, sql.js, and more.