jfl 0.7.2 → 0.8.0

package/packages/pi/extensions/pivot-tool.ts

@@ -0,0 +1,59 @@
+/**
+ * Pivot Tool Extension
+ *
+ * Registers jfl_pivot tool and /pivot command.
+ * Checkpoints current work to journals/memory without ending the session.
+ *
+ * @purpose Pivot tool — flush context to durable stores, stay on same branch
+ */
+
+import type { PiContext } from "./types.js"
+import { pivot } from "./session.js"
+
+export function setupPivotTool(ctx: PiContext): void {
+  ctx.registerTool({
+    name: "jfl_pivot",
+    description:
+      "Checkpoint current work — commit, write pivot journal entry, index memory. " +
+      "Stays on the same branch. Use when switching topics or the context window is full.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        summary: {
+          type: "string",
+          description: "Summary of what was being worked on (required for good handoff)",
+        },
+      },
+      required: ["summary"],
+    },
+    async handler(args: { summary?: string }) {
+      const result = await pivot(ctx, args.summary)
+      if (!result.ok) {
+        return "Pivot failed. Work is still safe on the current branch."
+      }
+      const lines = [
+        `Pivot #${result.pivotNumber} complete.`,
+        result.committed ? `Committed: ${result.commitHash} (${result.filesChanged} files)` : "No uncommitted changes.",
+        `Journal entry written.`,
+        result.indexed ? "Memory indexed." : "Memory index skipped (hub unavailable).",
+        "",
+        "Context has been saved. Ready for a new topic.",
+      ]
+      return lines.join("\n")
+    },
+  })
+
+  ctx.registerCommand({
+    name: "pivot",
+    description: "Checkpoint current work and reset context — same branch, no restart hooks",
+    async handler(args, ctx) {
+      const summary = args || "Topic transition"
+      const result = await pivot(ctx, summary)
+      if (result.ok) {
+        ctx.ui.notify(`Pivot #${result.pivotNumber} saved. Ready for new topic.`, { level: "info" })
+      } else {
+        ctx.ui.notify("Pivot failed — work is still safe on current branch.", { level: "warn" })
+      }
+    },
+  })
+}

package/packages/pi/extensions/session.ts

@@ -88,6 +88,64 @@ export function getSessionBranch(): string {
   return sessionBranch
 }
 
+export async function pivot(ctx: PiContext, summary?: string): Promise<{
+  ok: boolean
+  pivotNumber: number
+  committed: boolean
+  commitHash: string | null
+  filesChanged: number
+  indexed: boolean
+}> {
+  const root = ctx.session.projectRoot
+
+  try {
+    const resp = await fetch(`${hubUrl}/api/session/pivot`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...(authToken ? { Authorization: `Bearer ${authToken}` } : {}),
+      },
+      body: JSON.stringify({ summary }),
+      signal: AbortSignal.timeout(30000),
+    })
+
+    if (resp.ok) {
+      const data = await resp.json() as any
+      ctx.emit("hook:session-pivot", {
+        session: ctx.session.id,
+        branch: sessionBranch,
+        pivotNumber: data.pivotNumber,
+        summary: summary || "",
+        ts: new Date().toISOString(),
+      })
+      ctx.log(`Pivot #${data.pivotNumber} via Hub`, "debug")
+      return data
+    }
+  } catch {
+    ctx.log("Hub unavailable for pivot, falling back to CLI", "debug")
+  }
+
+  // Fallback: shell out to jfl pivot
+  try {
+    const result = execSync(
+      `jfl pivot --json${summary ? ` --summary "${summary.replace(/"/g, '\\"')}"` : ""}`,
+      { cwd: root, encoding: "utf-8", timeout: 30000, stdio: ["pipe", "pipe", "pipe"] },
+    )
+    const parsed = JSON.parse(result)
+    ctx.emit("hook:session-pivot", {
+      session: ctx.session.id,
+      branch: sessionBranch,
+      pivotNumber: parsed.pivotNumber,
+      summary: summary || "",
+      ts: new Date().toISOString(),
+    })
+    return parsed
+  } catch (err) {
+    ctx.log(`Pivot fallback failed: ${err}`, "warn")
+    return { ok: false, pivotNumber: 0, committed: false, commitHash: null, filesChanged: 0, indexed: false }
+  }
+}
+
 export async function onShutdown(ctx: PiContext): Promise<void> {
   const root = ctx.session.projectRoot
 

package/packages/pi/extensions/types.ts

@@ -158,6 +158,8 @@ export interface JflConfig {
     disable_footer?: boolean
     disable_shortcuts?: boolean
     disable_notifications?: boolean
+    disable_onboarding?: boolean
+    onboarding_variant?: "v1" | "v2" | "v3"
     auto_start?: boolean
   }
 }

package/packages/pi/skills/pivot/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: pivot
+description: Checkpoint current work to journals/memory and reset context — same branch, no restart hooks. Use when switching topics mid-session or context window is getting full.
+triggers:
+  - /pivot
+  - let's switch gears
+  - new topic
+  - context reset
+  - pivot
+  - change of plans
+  - let's do something else
+  - fresh start
+---
+
+# /pivot - Session Checkpoint & Context Reset
+
+Save everything you're working on to durable stores (journal, git, memory), then start fresh on a new topic — without ending the session or triggering startup hooks.
+
+---
+
+## When to Use
+
+| Situation | Use /pivot? |
+|-----------|------------|
+| Switching from feature work to bug fixing | ✅ Yes |
+| Context window getting full, need to continue | ✅ Yes |
+| Done with topic A, starting topic B | ✅ Yes |
+| Done for the day | ❌ Use /end instead |
+| Just finished one file, continuing same feature | ❌ No, keep going |
+
+## What It Does
+
+1. **Writes pivot journal entry** — captures what you were working on, files touched
+2. **Commits all work** — `git add -A && git commit` on the SAME branch
+3. **Indexes to memory** — makes the pivot entry searchable for future context
+4. **Emits event** — `session:pivoted` so other systems know
+5. **Tracks pivot count** — stored in `.jfl/session-state.json`
+
+## What It Does NOT Do
+
+- ❌ Merge to working branch (stays on session branch)
+- ❌ Create a new branch
+- ❌ Push to remote (unless `--push` flag)
+- ❌ Stop auto-commit or Context Hub
+- ❌ Run session-sync or doctor
+- ❌ Trigger SessionStart hooks
+
+## How to Invoke
+
+**As a tool** (agent calls it):
+```
+jfl_pivot({ summary: "Finished agent service type integration" })
+```
+
+**As a command** (user types it):
+```
+/pivot Finished agent service type integration
+```
+
+**From CLI**:
+```bash
+jfl pivot --summary "Finished agent service type integration"
+jfl pivot --summary "switching to bug fixes" --push
+jfl pivot --json
+```
+
+## After Pivot
+
+The agent should:
+1. Show the pivot summary to the user
+2. Ask "What do you want to work on next?"
+3. Use the pivot journal entry as primary context (not full startup reload)
+4. Continue on the same branch
+
+## Journal Entry Format
+
+Pivot entries use type `"pivot"`:
+
+```json
+{
+  "v": 1,
+  "ts": "2026-03-17T10:30:00.000Z",
+  "session": "session-hath-20260317-1000-abc123",
+  "type": "pivot",
+  "status": "complete",
+  "title": "Pivot #1: Finished agent service type integration",
+  "summary": "Finished agent service type integration",
+  "files": ["src/lib/service-detector.ts", "src/commands/services-create.ts"],
+  "pivot_number": 1
+}
+```

package/template/.claude/settings.json

@@ -60,6 +60,15 @@
             "command": "BRANCH=$(cat .jfl/current-session-branch.txt 2>/dev/null || git branch --show-current); echo ''; echo '═══════════════════════════════════════════════════════════'; echo '📝 JOURNAL CHECK: User approved/confirmed something'; echo '═══════════════════════════════════════════════════════════'; echo 'If a decision or feature was just approved, write journal entry.'; echo 'File: .jfl/journal/'\"${BRANCH}\"'.jsonl'; echo '═══════════════════════════════════════════════════════════'"
           }
         ]
+      },
+      {
+        "matcher": "pivot|switch gears|new topic|context reset|change of plans|let's do something else|fresh start|different topic",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo ''; echo '═══════════════════════════════════════════════════════════'; echo '🔄 PIVOT DETECTED: Run jfl pivot to checkpoint current work'; echo '═══════════════════════════════════════════════════════════'; echo 'Save current context before switching topics:'; echo '  jfl pivot --summary \"<what you were working on>\"'; echo '═══════════════════════════════════════════════════════════'"
+          }
+        ]
       }
     ],
     "Stop": [