clawvault 2.4.3 → 2.4.4

package/bin/register-task-commands.js

@@ -80,6 +80,8 @@ export function registerTaskCommands(
     .option('--priority <priority>', 'New priority')
     .option('--blocked-by <blocker>', 'What is blocking this task')
     .option('--due <date>', 'New due date')
+    .option('--confidence <value>', 'Transition confidence (0-1)', parseFloat)
+    .option('--reason <reason>', 'Reason for status change')
     .action(async (slug, options) => {
       try {
         const vaultPath = resolveVaultPath(options.vault);
@@ -92,7 +94,9 @@ export function registerTaskCommands(
             project: options.project,
             priority: options.priority,
             blockedBy: options.blockedBy,
-            due: options.due
+            due: options.due,
+            confidence: options.confidence,
+            reason: options.reason
           }
         });
       } catch (err) {
@@ -106,11 +110,45 @@ export function registerTaskCommands(
     .command('done <slug>')
     .description('Mark a task as done')
     .option('-v, --vault <path>', 'Vault path')
+    .option('--confidence <value>', 'Transition confidence (0-1)', parseFloat)
+    .option('--reason <reason>', 'Reason for completion')
     .action(async (slug, options) => {
       try {
         const vaultPath = resolveVaultPath(options.vault);
         const { taskCommand } = await import('../dist/commands/task.js');
-        await taskCommand(vaultPath, 'done', { slug });
+        await taskCommand(vaultPath, 'done', {
+          slug,
+          options: {
+            confidence: options.confidence,
+            reason: options.reason
+          }
+        });
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exit(1);
+      }
+    });
+
+  // task transitions
+  taskCmd
+    .command('transitions [task_id]')
+    .description('Show transition history')
+    .option('-v, --vault <path>', 'Vault path')
+    .option('--agent <id>', 'Filter by agent')
+    .option('--failed', 'Show only regression transitions')
+    .option('--json', 'Output as JSON')
+    .action(async (taskId, options) => {
+      try {
+        const vaultPath = resolveVaultPath(options.vault);
+        const { taskCommand } = await import('../dist/commands/task.js');
+        await taskCommand(vaultPath, 'transitions', {
+          slug: taskId,
+          options: {
+            agent: options.agent,
+            failed: options.failed,
+            json: options.json
+          }
+        });
       } catch (err) {
         console.error(chalk.red(`Error: ${err.message}`));
         process.exit(1);
@@ -221,6 +259,7 @@ export function registerTaskCommands(
     .description('View blocked tasks')
     .option('-v, --vault <path>', 'Vault path')
     .option('--project <project>', 'Filter by project')
+    .option('--escalated', 'Show only escalated tasks (3+ blocked transitions)')
     .option('--json', 'Output as JSON')
     .action(async (options) => {
       try {
@@ -228,6 +267,7 @@ export function registerTaskCommands(
         const { blockedCommand } = await import('../dist/commands/blocked.js');
         await blockedCommand(vaultPath, {
           project: options.project,
+          escalated: options.escalated,
           json: options.json
         });
       } catch (err) {

package/dist/chunk-UMMCYTJV.js

@@ -0,0 +1,105 @@
+// src/lib/transition-ledger.ts
+import * as fs from "fs";
+import * as path from "path";
+var REGRESSION_PAIRS = [
+  ["done", "open"],
+  ["done", "blocked"],
+  ["in-progress", "blocked"]
+];
+function isRegression(from, to) {
+  return REGRESSION_PAIRS.some(([f, t]) => f === from && t === to);
+}
+function getLedgerDir(vaultPath) {
+  return path.join(path.resolve(vaultPath), "ledger", "transitions");
+}
+function getTodayLedgerPath(vaultPath) {
+  const date = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  return path.join(getLedgerDir(vaultPath), `${date}.jsonl`);
+}
+function appendTransition(vaultPath, event) {
+  const ledgerDir = getLedgerDir(vaultPath);
+  if (!fs.existsSync(ledgerDir)) {
+    fs.mkdirSync(ledgerDir, { recursive: true });
+  }
+  const filePath = getTodayLedgerPath(vaultPath);
+  fs.appendFileSync(filePath, JSON.stringify(event) + "\n");
+}
+function buildTransitionEvent(taskId, fromStatus, toStatus, options = {}) {
+  const agentId = process.env.OPENCLAW_AGENT_ID || "manual";
+  const costTokensRaw = process.env.OPENCLAW_TOKEN_ESTIMATE;
+  const costTokens = costTokensRaw ? parseInt(costTokensRaw, 10) : null;
+  return {
+    task_id: taskId,
+    agent_id: agentId,
+    from_status: fromStatus,
+    to_status: toStatus,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    confidence: options.confidence ?? (agentId === "manual" ? 1 : 1),
+    cost_tokens: costTokens !== null && !isNaN(costTokens) ? costTokens : null,
+    reason: options.reason || null
+  };
+}
+function readAllTransitions(vaultPath) {
+  const ledgerDir = getLedgerDir(vaultPath);
+  if (!fs.existsSync(ledgerDir)) return [];
+  const files = fs.readdirSync(ledgerDir).filter((f) => f.endsWith(".jsonl")).sort();
+  const events = [];
+  for (const file of files) {
+    const lines = fs.readFileSync(path.join(ledgerDir, file), "utf-8").split("\n").filter((l) => l.trim());
+    for (const line of lines) {
+      try {
+        events.push(JSON.parse(line));
+      } catch {
+      }
+    }
+  }
+  return events;
+}
+function queryTransitions(vaultPath, filters = {}) {
+  let events = readAllTransitions(vaultPath);
+  if (filters.taskId) {
+    events = events.filter((e) => e.task_id === filters.taskId);
+  }
+  if (filters.agent) {
+    events = events.filter((e) => e.agent_id === filters.agent);
+  }
+  if (filters.failed) {
+    events = events.filter((e) => isRegression(e.from_status, e.to_status));
+  }
+  return events;
+}
+function countBlockedTransitions(vaultPath, taskId) {
+  const events = readAllTransitions(vaultPath);
+  return events.filter((e) => e.task_id === taskId && e.to_status === "blocked").length;
+}
+function formatTransitionsTable(events) {
+  if (events.length === 0) return "No transitions found.\n";
+  const headers = ["TIMESTAMP", "TASK", "FROM\u2192TO", "AGENT", "REASON"];
+  const widths = [20, 20, 24, 16, 30];
+  let output = headers.map((h, i) => h.padEnd(widths[i])).join("  ") + "\n";
+  output += "-".repeat(widths.reduce((a, b) => a + b + 2, 0)) + "\n";
+  for (const e of events) {
+    const ts = e.timestamp.replace("T", " ").slice(0, 19);
+    const taskId = e.task_id.length > widths[1] ? e.task_id.slice(0, widths[1] - 3) + "..." : e.task_id;
+    const transition = `${e.from_status} \u2192 ${e.to_status}`;
+    const reason = e.reason ? e.reason.length > widths[4] ? e.reason.slice(0, widths[4] - 3) + "..." : e.reason : "-";
+    output += [
+      ts.padEnd(widths[0]),
+      taskId.padEnd(widths[1]),
+      transition.padEnd(widths[2]),
+      e.agent_id.padEnd(widths[3]),
+      reason
+    ].join("  ") + "\n";
+  }
+  return output;
+}
+
+export {
+  isRegression,
+  appendTransition,
+  buildTransitionEvent,
+  readAllTransitions,
+  queryTransitions,
+  countBlockedTransitions,
+  formatTransitionsTable
+};

package/dist/commands/blocked.d.ts

@@ -8,6 +8,7 @@ import { Task } from '../lib/task-utils.js';
 interface BlockedOptions {
     project?: string;
     json?: boolean;
+    escalated?: boolean;
 }
 /**
  * Get blocked tasks

package/dist/commands/blocked.js

@@ -11,7 +11,11 @@ function toDateStr(val) {
   return s;
 }
 function blockedList(vaultPath, options = {}) {
-  return getBlockedTasks(vaultPath, options.project);
+  let tasks = getBlockedTasks(vaultPath, options.project);
+  if (options.escalated) {
+    tasks = tasks.filter((t) => t.frontmatter.escalation === true);
+  }
+  return tasks;
 }
 function formatBlockedList(tasks) {
   if (tasks.length === 0) {

package/dist/commands/task.d.ts

@@ -27,6 +27,13 @@ interface TaskUpdateOptions {
     priority?: TaskPriority;
     blockedBy?: string;
     due?: string;
+    confidence?: number;
+    reason?: string;
+}
+interface TaskTransitionsOptions {
+    agent?: string;
+    failed?: boolean;
+    json?: boolean;
 }
 interface TaskShowOptions {
     json?: boolean;
@@ -40,13 +47,20 @@ declare function taskAdd(vaultPath: string, title: string, options?: TaskAddOpti
  */
 declare function taskList(vaultPath: string, options?: TaskListOptions): Task[];
 /**
- * Update a task
+ * Update a task (with transition logging when status changes)
  */
 declare function taskUpdate(vaultPath: string, slug: string, options: TaskUpdateOptions): Task;
 /**
- * Mark a task as done
+ * Mark a task as done (with transition logging)
+ */
+declare function taskDone(vaultPath: string, slug: string, options?: {
+    confidence?: number;
+    reason?: string;
+}): Task;
+/**
+ * Query task transitions
  */
-declare function taskDone(vaultPath: string, slug: string): Task;
+declare function taskTransitions(vaultPath: string, taskId?: string, options?: TaskTransitionsOptions): string;
 /**
  * Show task details
  */
@@ -62,10 +76,10 @@ declare function formatTaskDetails(task: Task): string;
 /**
  * Task command handler for CLI
  */
-declare function taskCommand(vaultPath: string, action: 'add' | 'list' | 'update' | 'done' | 'show', args: {
+declare function taskCommand(vaultPath: string, action: 'add' | 'list' | 'update' | 'done' | 'show' | 'transitions', args: {
     title?: string;
     slug?: string;
-    options?: TaskAddOptions & TaskListOptions & TaskUpdateOptions & TaskShowOptions;
+    options?: TaskAddOptions & TaskListOptions & TaskUpdateOptions & TaskShowOptions & TaskTransitionsOptions;
 }): Promise<void>;
 
-export { type TaskAddOptions, type TaskListOptions, type TaskShowOptions, type TaskUpdateOptions, formatTaskDetails, formatTaskList, taskAdd, taskCommand, taskDone, taskList, taskShow, taskUpdate };
+export { type TaskAddOptions, type TaskListOptions, type TaskShowOptions, type TaskTransitionsOptions, type TaskUpdateOptions, formatTaskDetails, formatTaskList, taskAdd, taskCommand, taskDone, taskList, taskShow, taskTransitions, taskUpdate };

package/dist/commands/task.js

@@ -1,3 +1,10 @@
+import {
+  appendTransition,
+  buildTransitionEvent,
+  countBlockedTransitions,
+  formatTransitionsTable,
+  queryTransitions
+} from "../chunk-UMMCYTJV.js";
 import {
   completeTask,
   createTask,
@@ -9,6 +16,8 @@ import {
 } from "../chunk-DEFBIVQ3.js";
 
 // src/commands/task.ts
+import matter from "gray-matter";
+import * as fs from "fs";
 function taskAdd(vaultPath, title, options = {}) {
   return createTask(vaultPath, title, {
     owner: options.owner,
@@ -32,7 +41,9 @@ function taskList(vaultPath, options = {}) {
   return listTasks(vaultPath, filters);
 }
 function taskUpdate(vaultPath, slug, options) {
-  return updateTask(vaultPath, slug, {
+  const before = readTask(vaultPath, slug);
+  const oldStatus = before?.frontmatter.status;
+  const task = updateTask(vaultPath, slug, {
     status: options.status,
     owner: options.owner,
     project: options.project,
@@ -40,9 +51,52 @@ function taskUpdate(vaultPath, slug, options) {
     blocked_by: options.blockedBy,
     due: options.due
   });
+  if (options.status && oldStatus && options.status !== oldStatus) {
+    emitTransition(vaultPath, slug, oldStatus, options.status, options);
+  }
+  return task;
+}
+function taskDone(vaultPath, slug, options = {}) {
+  const before = readTask(vaultPath, slug);
+  const oldStatus = before?.frontmatter.status;
+  const task = completeTask(vaultPath, slug);
+  if (oldStatus && oldStatus !== "done") {
+    emitTransition(vaultPath, slug, oldStatus, "done", options);
+  }
+  return task;
 }
-function taskDone(vaultPath, slug) {
-  return completeTask(vaultPath, slug);
+function emitTransition(vaultPath, slug, fromStatus, toStatus, options = {}) {
+  const event = buildTransitionEvent(slug, fromStatus, toStatus, {
+    confidence: options.confidence,
+    reason: options.reason
+  });
+  appendTransition(vaultPath, event);
+  if (toStatus === "blocked") {
+    const blockedCount = countBlockedTransitions(vaultPath, slug);
+    if (blockedCount >= 3) {
+      markEscalation(vaultPath, slug);
+    }
+  }
+}
+function markEscalation(vaultPath, slug) {
+  const task = readTask(vaultPath, slug);
+  if (!task) return;
+  const raw = fs.readFileSync(task.path, "utf-8");
+  const { data, content } = matter(raw);
+  if (data.escalation) return;
+  data.escalation = true;
+  fs.writeFileSync(task.path, matter.stringify(content, data));
+}
+function taskTransitions(vaultPath, taskId, options = {}) {
+  const events = queryTransitions(vaultPath, {
+    taskId,
+    agent: options.agent,
+    failed: options.failed
+  });
+  if (options.json) {
+    return JSON.stringify(events, null, 2);
+  }
+  return formatTransitionsTable(events);
 }
 function taskShow(vaultPath, slug) {
   return readTask(vaultPath, slug);
@@ -154,10 +208,22 @@ async function taskCommand(vaultPath, action, args) {
       if (!args.slug) {
         throw new Error("Task slug is required for done");
       }
-      const task = taskDone(vaultPath, args.slug);
+      const task = taskDone(vaultPath, args.slug, {
+        confidence: options.confidence,
+        reason: options.reason
+      });
       console.log(`\u2713 Completed task: ${task.slug}`);
       break;
     }
+    case "transitions": {
+      const output = taskTransitions(vaultPath, args.slug, {
+        agent: options.agent,
+        failed: options.failed,
+        json: options.json
+      });
+      console.log(output);
+      break;
+    }
     case "show": {
       if (!args.slug) {
         throw new Error("Task slug is required for show");
@@ -185,5 +251,6 @@ export {
   taskDone,
   taskList,
   taskShow,
+  taskTransitions,
   taskUpdate
 };

package/dist/index.d.ts

@@ -14,6 +14,7 @@ export { MigrateObservationsOptions, MigrateObservationsResult, migrateObservati
 export { SyncBdCommandOptions, registerSyncBdCommand, syncBdCommand } from './commands/sync-bd.js';
 export { SessionRecapFormat, SessionRecapOptions, SessionRecapResult, SessionTurn, buildSessionRecap, formatSessionRecapMarkdown, sessionRecapCommand } from './commands/session-recap.js';
 export { findNearestVaultPath, getVaultPath, resolveVaultPath } from './lib/config.js';
+import { TaskStatus } from './lib/task-utils.js';
 export { CLAWVAULT_SERVE_PATH, DEFAULT_SERVE_PORT, ServeInstance, TailscalePeer, TailscaleServeConfig, TailscaleStatus, TailscaleSyncOptions, TailscaleSyncResult, VaultFileEntry, VaultManifest, checkPeerClawVault, compareManifests, configureTailscaleServe, discoverClawVaultPeers, fetchRemoteFile, fetchRemoteManifest, findPeer, generateVaultManifest, getOnlinePeers, getTailscaleStatus, getTailscaleVersion, hasTailscale, pushFileToRemote, resolvePeerIP, serveVault, stopTailscaleServe, syncWithPeer } from './lib/tailscale.js';
 export { TailscaleDiscoverCommandOptions, TailscaleServeCommandOptions, TailscaleStatusCommandOptions, TailscaleSyncCommandOptions, registerTailscaleCommands, registerTailscaleDiscoverCommand, registerTailscaleServeCommand, registerTailscaleStatusCommand, registerTailscaleSyncCommand, tailscaleDiscoverCommand, tailscaleServeCommand, tailscaleStatusCommand, tailscaleSyncCommand } from './commands/tailscale.js';
 export { TemplateVariables, buildTemplateVariables, renderTemplate } from './lib/template-engine.js';
@@ -344,6 +345,54 @@ declare function getMemoryGraph(vaultPath: string, options?: {
     refresh?: boolean;
 }): Promise<MemoryGraph>;
 
+/**
+ * Transition Ledger for ClawVault
+ * Logs task status transitions to JSONL files and supports querying.
+ */
+
+interface TransitionEvent {
+    task_id: string;
+    agent_id: string;
+    from_status: TaskStatus;
+    to_status: TaskStatus;
+    timestamp: string;
+    confidence: number;
+    cost_tokens: number | null;
+    reason: string | null;
+}
+declare function isRegression(from: TaskStatus, to: TaskStatus): boolean;
+/**
+ * Append a transition event to the ledger
+ */
+declare function appendTransition(vaultPath: string, event: TransitionEvent): void;
+/**
+ * Build a transition event from context
+ */
+declare function buildTransitionEvent(taskId: string, fromStatus: TaskStatus, toStatus: TaskStatus, options?: {
+    confidence?: number;
+    reason?: string;
+}): TransitionEvent;
+/**
+ * Read all transition events from all ledger files
+ */
+declare function readAllTransitions(vaultPath: string): TransitionEvent[];
+/**
+ * Query transitions with filters
+ */
+declare function queryTransitions(vaultPath: string, filters?: {
+    taskId?: string;
+    agent?: string;
+    failed?: boolean;
+}): TransitionEvent[];
+/**
+ * Count blocked transitions for a task
+ */
+declare function countBlockedTransitions(vaultPath: string, taskId: string): number;
+/**
+ * Format transitions as a table string
+ */
+declare function formatTransitionsTable(events: TransitionEvent[]): string;
+
 interface ObserverCompressor {
     compress(messages: string[], existingObservations: string): Promise<string>;
 }
@@ -548,4 +597,4 @@ declare function runReflection(options: ReflectOptions): Promise<ReflectResult>;
 declare const VERSION: string;
 declare function registerCommanderCommands(program: Command): Command;
 
-export { type ArchiveObservationsOptions, type ArchiveObservationsResult, Category, ClawVault, Compressor, type CompressorOptions, Document, HandoffDocument, MEMORY_GRAPH_SCHEMA_VERSION, type MemoryGraph, type MemoryGraphEdge, type MemoryGraphEdgeType, type MemoryGraphIndex, type MemoryGraphNode, type MemoryGraphNodeType, type MemoryGraphStats, MemoryType, Observer, type ObserverCompressor, type ObserverOptions, type ObserverReflector, QMD_INSTALL_COMMAND, QMD_INSTALL_URL, QmdUnavailableError, type ReflectOptions, type ReflectResult, Reflector, type ReflectorOptions, SearchEngine, SearchOptions, SearchResult, SessionRecap, SessionWatcher, type SessionWatcherOptions, StoreOptions, SyncOptions, SyncResult, VERSION, VaultConfig, archiveObservations, buildOrUpdateMemoryGraphIndex, createVault, extractTags, extractWikiLinks, findVault, getMemoryGraph, hasQmd, loadMemoryGraphIndex, parseSessionFile, qmdEmbed, qmdUpdate, registerCommanderCommands, runReflection };
+export { type ArchiveObservationsOptions, type ArchiveObservationsResult, Category, ClawVault, Compressor, type CompressorOptions, Document, HandoffDocument, MEMORY_GRAPH_SCHEMA_VERSION, type MemoryGraph, type MemoryGraphEdge, type MemoryGraphEdgeType, type MemoryGraphIndex, type MemoryGraphNode, type MemoryGraphNodeType, type MemoryGraphStats, MemoryType, Observer, type ObserverCompressor, type ObserverOptions, type ObserverReflector, QMD_INSTALL_COMMAND, QMD_INSTALL_URL, QmdUnavailableError, type ReflectOptions, type ReflectResult, Reflector, type ReflectorOptions, SearchEngine, SearchOptions, SearchResult, SessionRecap, SessionWatcher, type SessionWatcherOptions, StoreOptions, SyncOptions, SyncResult, type TransitionEvent, VERSION, VaultConfig, appendTransition, archiveObservations, buildOrUpdateMemoryGraphIndex, buildTransitionEvent, countBlockedTransitions, createVault, extractTags, extractWikiLinks, findVault, formatTransitionsTable, getMemoryGraph, hasQmd, isRegression, loadMemoryGraphIndex, parseSessionFile, qmdEmbed, qmdUpdate, queryTransitions, readAllTransitions, registerCommanderCommands, runReflection };

package/dist/index.js

@@ -35,6 +35,15 @@ import {
   syncWithPeer
 } from "./chunk-4GBPTBFJ.js";
 import "./chunk-CLE2HHNT.js";
+import {
+  appendTransition,
+  buildTransitionEvent,
+  countBlockedTransitions,
+  formatTransitionsTable,
+  isRegression,
+  queryTransitions,
+  readAllTransitions
+} from "./chunk-UMMCYTJV.js";
 import {
   buildTemplateVariables,
   renderTemplate
@@ -179,12 +188,14 @@ export {
   SessionWatcher,
   TYPE_TO_CATEGORY,
   VERSION,
+  appendTransition,
   archiveCommand,
   archiveObservations,
   buildContext,
   buildOrUpdateMemoryGraphIndex,
   buildSessionRecap,
   buildTemplateVariables,
+  buildTransitionEvent,
   checkOpenClawCompatibility,
   checkPeerClawVault,
   compareManifests,
@@ -192,6 +203,7 @@ export {
   compatibilityExitCode,
   configureTailscaleServe,
   contextCommand,
+  countBlockedTransitions,
   createVault,
   discoverClawVaultPeers,
   extractTags,
@@ -203,6 +215,7 @@ export {
   findVault,
   formatContextMarkdown,
   formatSessionRecapMarkdown,
+  formatTransitionsTable,
   generateVaultManifest,
   getMemoryGraph,
   getOnlinePeers,
@@ -214,6 +227,7 @@ export {
   hasQmd,
   hasTailscale,
   inferContextProfile,
+  isRegression,
   loadMemoryGraphIndex,
   migrateObservations,
   migrateObservationsCommand,
@@ -223,6 +237,8 @@ export {
   pushFileToRemote,
   qmdEmbed,
   qmdUpdate,
+  queryTransitions,
+  readAllTransitions,
   rebuildCommand,
   reflectCommand,
   registerArchiveCommand,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawvault",
-  "version": "2.4.3",
+  "version": "2.4.4",
   "description": "Structured memory system for AI agents — typed storage, knowledge graph, context profiles, canvas dashboards, neural graph themes, and Obsidian-native task views. An elephant never forgets. 🐘",
   "type": "module",
   "main": "dist/index.cjs",