hzl-cli 1.20.0 → 1.21.0

package/README.md

@@ -367,20 +367,26 @@ If your coding agent supports an instruction file (for example `CLAUDE.md`, `AGE
 <!-- START [code:md] docs/snippets/agent-policy.md -->
 <!-- ⚠️ DO NOT EDIT - Auto-generated from docs/snippets/agent-policy.md -->
 ```md
-### HZL task ledger (external task tracking for multi-session/multi-agent work)
+### HZL task ledger (external task tracking)
 
-HZL is an external task database. Use it when work outlives this session or involves other agents.
-Built-in task tracking (if available) is fine for single-session work you'll complete now.
+HZL is an external task database. Use it whenever external tracking would help clarity, handoff, or auditability.
+Multi-session or multi-agent work are common reasons to use HZL, not requirements.
+Use HZL for single-session, single-agent work when the task is non-trivial.
 
-**When to use HZL:**
-- Work spanning multiple sessions or days
-- Coordination with other agents (Claude Code ↔ Codex ↔ Gemini)
-- Delegating to sub-agents with explicit handoff
-- User explicitly asks to track work in HZL
+**Prefer using HZL when:**
+- Work may outlive this session or is likely to be paused/resumed
+- You want a durable record of decisions, progress, or ownership
+- You expect handoff or review by another agent/person
+- The user asks to track work in HZL
+- The task is non-trivial (multiple steps, ~30+ minutes, or risky changes)
 
-**When NOT to use HZL:**
-- Single-session work you'll complete in this conversation
-- User hasn't mentioned persistence or multi-agent needs
+**You can skip HZL when:**
+- The work is small, clearly scoped, and will be completed immediately
+- The user asks for a quick one-off answer or tiny change
+
+**Rule of thumb:** If you feel tempted to make a multi-step plan or there is any chance you will not finish in this session, use HZL.
+
+Example: "Investigate failing tests and fix root cause" -> use HZL because it likely involves multiple subtasks, even if you expect to finish within a session.
 
 **Structure:**
 - **Project** = stable container (one per repo). Check `hzl project list` before creating.
@@ -415,7 +421,7 @@ hzl task add "Fix N+1" --parent <parent-id>    # Subtask
 | Create (ready to work) | `hzl task add "title" -P project -s ready` |
 | Create and claim | `hzl task add "title" -P project -s in_progress --assignee <name>` |
 | Create (planning) | `hzl task add "title" -P project` |
-| Claim | `hzl task claim <id> --assignee <name>` |
+| Claim (start work) | `hzl task claim <id>` (or `start`) |
 | Complete | `hzl task complete <id>` |
 
 **⚠️ DESTRUCTIVE - Never run without explicit user request:**
@@ -563,8 +569,8 @@ hzl task list --project <project>             # List tasks (--available for clai
 hzl task next --project <project>             # Get highest priority available task
 
 # Working
-hzl task claim <id> --assignee <name>         # Claim task (--lease <minutes> for expiry)
-hzl task claim <id> --agent-id <id>           # Claim as AI agent (machine identifier)
+hzl task claim <id> --assignee <name>         # Claim task (or: hzl task start <id>)
+hzl task claim <id> --agent-id <id>           # --lease <minutes> for expiry
 hzl task checkpoint <id> "<message>"          # Save progress snapshot
 hzl task progress <id> <value>                # Set progress (0-100)
 hzl task complete <id>                        # Mark done

package/dist/commands/task/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/task/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA0BpC,wBAAgB,iBAAiB,IAAI,OAAO,CA6B3C"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/task/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA2BpC,wBAAgB,iBAAiB,IAAI,OAAO,CA8B3C"}

package/dist/commands/task/index.js

@@ -19,6 +19,7 @@ import { createCheckpointCommand } from './checkpoint.js';
 import { createHistoryCommand } from './history.js';
 import { createSearchCommand } from './search.js';
 import { createNextCommand } from './next.js';
+import { createStartCommand } from './start.js';
 import { createBlockCommand } from './block.js';
 import { createUnblockCommand } from './unblock.js';
 import { createProgressCommand } from './progress.js';
@@ -29,6 +30,7 @@ export function createTaskCommand() {
     command.addCommand(createListCommand());
     command.addCommand(createShowCommand());
     command.addCommand(createClaimCommand());
+    command.addCommand(createStartCommand());
     command.addCommand(createCompleteCommand());
     command.addCommand(createReleaseCommand());
     command.addCommand(createArchiveCommand());

package/dist/commands/task/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/commands/task/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/commands/task/index.ts"],"names":[],"mappings":"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"}

package/dist/commands/task/start.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function createStartCommand(): Command;
+//# sourceMappingURL=start.d.ts.map

package/dist/commands/task/start.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start.d.ts","sourceRoot":"","sources":["../../../src/commands/task/start.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAapC,wBAAgB,kBAAkB,IAAI,OAAO,CA0B5C"}

package/dist/commands/task/start.js

@@ -0,0 +1,37 @@
+// Alias for 'claim' - more intuitive for "starting work on a task"
+import { Command } from 'commander';
+import { resolveDbPaths } from '../../config.js';
+import { initializeDb, closeDb } from '../../db.js';
+import { handleError } from '../../errors.js';
+import { GlobalOptionsSchema } from '../../types.js';
+import { runClaim } from './claim.js';
+export function createStartCommand() {
+    return new Command('start')
+        .description('Start working on a task (alias for claim)')
+        .argument('<taskId>', 'Task ID')
+        .option('--assignee <name>', 'Who to assign the task to')
+        .option('--agent-id <id>', 'Agent ID (machine/AI identifier)')
+        .option('-l, --lease <minutes>', 'Lease duration in minutes')
+        .action(function (taskId, opts) {
+        const globalOpts = GlobalOptionsSchema.parse(this.optsWithGlobals());
+        const { eventsDbPath, cacheDbPath } = resolveDbPaths(globalOpts.db);
+        const services = initializeDb({ eventsDbPath, cacheDbPath });
+        try {
+            runClaim({
+                services,
+                taskId,
+                assignee: opts.assignee,
+                agentId: opts.agentId,
+                leaseMinutes: opts.lease ? parseInt(opts.lease, 10) : undefined,
+                json: globalOpts.json ?? false,
+            });
+        }
+        catch (e) {
+            handleError(e, globalOpts.json);
+        }
+        finally {
+            closeDb(services);
+        }
+    });
+}
+//# sourceMappingURL=start.js.map

package/dist/commands/task/start.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"start.js","sourceRoot":"","sources":["../../../src/commands/task/start.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAQtC,MAAM,UAAU,kBAAkB;IAChC,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC;SACxB,WAAW,CAAC,2CAA2C,CAAC;SACxD,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC;SAC/B,MAAM,CAAC,mBAAmB,EAAE,2BAA2B,CAAC;SACxD,MAAM,CAAC,iBAAiB,EAAE,kCAAkC,CAAC;SAC7D,MAAM,CAAC,uBAAuB,EAAE,2BAA2B,CAAC;SAC5D,MAAM,CAAC,UAAyB,MAAc,EAAE,IAAyB;QACxE,MAAM,UAAU,GAAG,mBAAmB,CAAC,KAAK,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC,CAAC;QACrE,MAAM,EAAE,YAAY,EAAE,WAAW,EAAE,GAAG,cAAc,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;QACpE,MAAM,QAAQ,GAAG,YAAY,CAAC,EAAE,YAAY,EAAE,WAAW,EAAE,CAAC,CAAC;QAC7D,IAAI,CAAC;YACH,QAAQ,CAAC;gBACP,QAAQ;gBACR,MAAM;gBACN,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,YAAY,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS;gBAC/D,IAAI,EAAE,UAAU,CAAC,IAAI,IAAI,KAAK;aAC/B,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,WAAW,CAAC,CAAC,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC;QAClC,CAAC;gBAAS,CAAC;YACT,OAAO,CAAC,QAAQ,CAAC,CAAC;QACpB,CAAC;IACH,CAAC,CAAC,CAAC;AACP,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hzl-cli",
-  "version": "1.20.0",
+  "version": "1.21.0",
   "description": "CLI for HZL - External task ledger for coding agents and OpenClaw.",
   "type": "module",
   "bin": {
@@ -60,8 +60,8 @@
     "libsql": "^0.5.0",
     "commander": "^14.0.0",
     "zod": "^3.23.8",
-    "hzl-core": "1.20.0",
-    "hzl-web": "1.20.0"
+    "hzl-core": "1.21.0",
+    "hzl-web": "1.21.0"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",