agentpack-cli 0.1.12 → 0.1.14

package/docs/TASK-PASSPORT.md

@@ -150,10 +150,10 @@ active -> parked            task park
 parked -> active            task switch/resume
 active -> blocked           task block
 blocked -> active           task unblock/resume
-active -> verifying         task update-verification
+active -> verifying         task verify
 verifying -> active         verification found more work
-verifying -> completed      verification passed
-active -> completed         small/docs task accepted directly
+verifying -> completed      task finalize
+active -> completed         task finalize --status accepted
 active -> abandoned         task abandon
 parked -> abandoned         stale parked task is discarded
 blocked -> abandoned        blocked task is discarded
@@ -163,7 +163,7 @@ Closed statuses are `completed` and `abandoned`. Closed passports remain inspect
 
 ## CLI Shape
 
-Target first CLI surface:
+Current CLI surface:
 
 ```bash
 agentpack task start "Fix checkout discount bug" \
@@ -173,6 +173,7 @@ agentpack task start "Fix checkout discount bug" \
 
 agentpack task list
 agentpack task status
+agentpack task handoff
 agentpack task passport
 agentpack task switch task_20260518_source_cleanup
 agentpack task update --next "Run focused regression tests" --write-scope tests/checkout.test.ts --risk medium
@@ -180,21 +181,28 @@ agentpack task audit
 agentpack task park
 agentpack task block --reason "Waiting for API decision"
 agentpack task verify --status passed --evidence evt_... --summary "Focused checks passed"
-agentpack task close
+agentpack task finalize
+agentpack task --help
 ```
 
 `resume` and MCP `load_context` read the current passport automatically when one exists, then show the broader repo-level ledger below it.
 
+The normal human-facing sequence is: start the task, keep status/scope/next actions current, record verification with evidence, print a handoff when another agent or chat may continue, then finalize only after verification is final.
+
 `task start` creates a new current passport only when there is no current task, the current task is closed, or the current task is parked. If the current task is active, blocked, or verifying, Agentpack asks you to park or close it first so unrelated work does not silently overwrite the handoff pointer. Invalid risk values are rejected instead of being treated as unknown.
 
 `task status` prints a short current-task view without scanning source-cache status. Use it for a quick human check before reaching for `task audit`.
 
+`task handoff` prints a compact current-passport handoff for switching chats, clients, worktrees, or agents. It includes objective, constraints, write scope, next actions, verification, drift, and audit summary without dumping the full passport JSON.
+
 `task audit` is a diagnostic pass for continuity risk. It checks the current passport for branch/head drift, missing next actions, open verification, closed-current-task anomalies, and source-cache metadata drift. Metadata warnings are shown separately so stale source records do not look like action-required task failures.
 
 `task update` patches the current passport without changing lifecycle status. It can add objective, constraints, write scope, next actions, tags, and risk after the task has already started. List fields append and deduplicate; omitted fields are preserved. Empty or no-op updates fail, and unknown risk values are rejected.
 
 `task verify` updates the verification state. Without flags it marks verification as `pending`; with `--status`, `--evidence`, and `--summary` it links verification to recorded evidence so the audit warning can become a reviewed result. `task update-verification` remains available as a compatibility alias.
 
+`task finalize` is the compact end-of-task ritual. It closes the current task only after verification is already `passed`, `failed`, or `accepted`, or when that final status is passed explicitly with `--status`. It refuses to close unknown or pending verification by default. `task close` remains available for explicit manual closure.
+
 ## Role Lanes
 
 Roles are coordination lanes inside one passport, not separate tasks.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentpack-cli",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "Local task-state ledger for AI coding agents.",
   "type": "module",
   "repository": {

package/scripts/mcp-smoke.mjs

@@ -29,7 +29,7 @@ try {
 
   const toolsResponse = await client.request("tools/list", {});
   const toolNames = toolsResponse.result?.tools?.map((tool) => tool.name).sort() || [];
-  for (const expected of ["load_context", "record_decision", "record_source", "resume", "source_status", "task_audit", "task_update", "task_update_verification"]) {
+  for (const expected of ["load_context", "record_decision", "record_source", "resume", "source_status", "task_audit", "task_finalize", "task_handoff", "task_update", "task_update_verification"]) {
     assertIncludes(toolNames, expected, `tools/list includes ${expected}`);
   }
 
@@ -71,6 +71,12 @@ try {
     "Complete smoke verification"
   ]);
 
+  const taskHandoff = await client.request("tools/call", {
+    name: "task_handoff",
+    arguments: {}
+  });
+  assertMatch(taskHandoff.result?.content?.[0]?.text || "", /MCP smoke verification \[active\]/, "task_handoff reports the active task");
+
   const evidence = await client.request("tools/call", {
     name: "attach_evidence",
     arguments: {
@@ -102,6 +108,12 @@ try {
   });
   assertMatch(taskUpdate.result?.content?.[0]?.text || "", /Updated task .*/, "task_update updates the current passport");
 
+  const taskFinalize = await client.request("tools/call", {
+    name: "task_finalize",
+    arguments: {}
+  });
+  assertMatch(taskFinalize.result?.content?.[0]?.text || "", /Finalized task .* \(passed\)/, "task_finalize closes a verified task");
+
   const resume = await client.request("tools/call", {
     name: "resume",
     arguments: {
@@ -114,7 +126,7 @@ try {
 
   console.log("MCP server OK");
   console.log(`Tools: ${toolNames.join(", ")}`);
-  console.log("Flow: initialize -> tools/list -> record_decision -> record_source -> source_status -> task_audit -> task_update_verification -> task_update -> resume");
+  console.log("Flow: initialize -> tools/list -> record_decision -> record_source -> source_status -> task_audit -> task_handoff -> task_update_verification -> task_update -> task_finalize -> resume");
 } catch (error) {
   console.error("MCP smoke failed");
   console.error(error instanceof Error ? error.message : String(error));