@kairyou/agent-tools 0.18.0 → 0.20.0

package/README.md

@@ -56,7 +56,7 @@ Usage:
 
 ### at-zentao
 
-Work ZenTao (禅道) bugs/tasks end to end, read linked story context, or log task hours; asks before committing and before writing back.
+Work ZenTao (禅道) bugs/tasks end to end, manage task status and hours, or read linked story context; asks before committing and before writing back.
 
 ```bash
 npx -y skills@latest add kairyou/agent-tools --skill at-zentao -g -y
@@ -67,7 +67,7 @@ Usage:
 - `/at-zentao bugs` — list bugs assigned to you (the configured account); pick one or several (several = batch mode)
 - `/at-zentao tasks` — same, for tasks
 - `/at-zentao bug <id>` — work a specific bug
-- `/at-zentao task <id> [request]` — work a specific task or log hours with a natural-language request
+- `/at-zentao task <id> [request]` — work a task, start/pause/resume it, or log hours with a natural-language request
 - `/at-zentao story <id>` — read requirement scope and acceptance context without writing back
 
 Config: `~/.agent-tools/config.jsonc` → `"zentao": { "url", "account", "password" }`. The password can be entered directly or referenced with `"password": { "env": "ZENTAO_PASSWORD" }`; never paste credentials or tokens into chat.

package/README.zh-CN.md

@@ -56,7 +56,7 @@ npx -y skills@latest add kairyou/agent-tools --skill at-simplify -g -y
 
 ### at-zentao
 
-读取禅道 bug/task 并端到端处理, 补充关联 story 上下文, 或记录任务工时; 提交和回写前均需确认.
+读取禅道 bug/task 并端到端处理, 管理任务状态和工时, 或补充关联 story 上下文; 提交和回写前均需确认.
 
 ```bash
 npx -y skills@latest add kairyou/agent-tools --skill at-zentao -g -y
@@ -67,7 +67,7 @@ npx -y skills@latest add kairyou/agent-tools --skill at-zentao -g -y
 - `/at-zentao bugs` — 列出指派给你(配置的账号)的 bug, 挑一个或多个(多个 = 批量模式)
 - `/at-zentao tasks` — 同上, 任务清单
 - `/at-zentao bug <id>` — 直接处理指定 bug
-- `/at-zentao task <id> [请求]` — 处理指定 task, 或用自然语言记录工时
+- `/at-zentao task <id> [请求]` — 处理指定 task, 用自然语言开始/暂停/继续或记录工时
 - `/at-zentao story <id>` — 只读查看研发需求范围和验收信息
 
 配置: `~/.agent-tools/config.jsonc` → `"zentao": { "url", "account", "password" }`. 密码可以直接填写, 也可以使用 `"password": { "env": "ZENTAO_PASSWORD" }` 引用环境变量; 不要在对话中粘贴凭据或 token.

package/docs/en/repository-structure.md

@@ -14,7 +14,7 @@ agent-tools/
 │   │   ├── at-review/   # Review local or hosted changes for bugs and regressions.
 │   │   └── at-simplify/ # Reduce complexity and duplication in changes.
 │   └── systems/       # Self-contained Skills for external systems.
-│       └── at-zentao/   # Self-contained ZenTao development and time-entry workflow.
+│       └── at-zentao/   # Self-contained ZenTao development and task-lifecycle workflow.
 ├── docs/              # Advanced guides and contributor reference.
 ├── tools/             # Maintainer-only upstream sync and repository tooling.
 └── scripts/           # Install, sync, validation, and maintenance scripts.

package/docs/zh-CN/repository-structure.md

@@ -14,7 +14,7 @@ agent-tools/
 │   │   ├── at-review/   # 审查本地或托管改动中的 bug 与回归风险.
 │   │   └── at-simplify/ # 减少改动中的冗余和复杂度.
 │   └── systems/       # 面向外部系统的自包含 Skills.
-│       └── at-zentao/   # 自包含的禅道研发事项与工时工作流.
+│       └── at-zentao/   # 自包含的禅道研发事项与任务生命周期工作流.
 ├── docs/              # 高级指南和贡献者参考.
 ├── tools/             # 仅供维护者使用的上游同步和仓库工具.
 └── scripts/           # 安装, 同步, 校验和仓库维护脚本.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kairyou/agent-tools",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "Reusable Agent Skills, plus runtime capabilities (statusline, provider usage, vision) for Codex, Claude Code, and opencode.",
   "license": "MIT",
   "repository": {

package/skills/systems/at-zentao/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: at-zentao
-description: "Work ZenTao bugs/tasks end to end, log task hours, or read a linked story as development context: fetch details, handle the user's request, verify changes, and ask before committing or writing back to ZenTao. Supports single items and sequential batches. Use when the user references ZenTao (禅道) bugs, tasks, stories, requirements, or task hours."
+description: "Work ZenTao bugs/tasks end to end, manage task lifecycle and hours, or read a linked story as development context: fetch details, handle the user's request, verify changes, and ask before committing or writing back to ZenTao. Supports single items and sequential batches. Use when the user references ZenTao (禅道) bugs, tasks, stories, requirements, task status, or task hours."
 argument-hint: "bug <id> [request] | task <id> [request] | story <id> | bugs | tasks | export bug|task <id>"
 ---
 
@@ -72,6 +72,7 @@ node <skill-root>/scripts/zentao-cli.mjs get bug <id>
 node <skill-root>/scripts/zentao-cli.mjs get task <id>
 node <skill-root>/scripts/zentao-cli.mjs get story <id>
 node <skill-root>/scripts/zentao-cli.mjs get bug <id> --download-dir <path>
+node <skill-root>/scripts/zentao-cli.mjs hours task <id>
 ```
 
 `get` downloads token-gated inline images and attachments into a temporary
@@ -85,7 +86,11 @@ confirmation steps below:
 node <skill-root>/scripts/zentao-cli.mjs comment bug <id>
 node <skill-root>/scripts/zentao-cli.mjs comment task <id>
 node <skill-root>/scripts/zentao-cli.mjs resolve bug <id>
+node <skill-root>/scripts/zentao-cli.mjs start task <id>
+node <skill-root>/scripts/zentao-cli.mjs pause task <id>
+node <skill-root>/scripts/zentao-cli.mjs resume task <id>
 node <skill-root>/scripts/zentao-cli.mjs log-hours task <id>
+node <skill-root>/scripts/zentao-cli.mjs edit-hours task <id> <effort-id>
 node <skill-root>/scripts/zentao-cli.mjs finish task <id>
 ```
 
@@ -94,15 +99,22 @@ Input shapes:
 ```json
 {"comment":"Root cause and result."}
 {"resolution":"fixed","resolvedBuild":"trunk","comment":"Root cause and result, commit abc1234."}
+{"realStarted":"2026-08-11 09:00:00","comment":"Started implementation."}
 {"date":"2026-08-11","consumed":2,"left":14,"work":"Implemented the first part of the task."}
+{"work":"Corrected work description, commit abc1234."}
 {"currentConsumed":1.5,"realStarted":"2026-08-11 09:00:00","finishedDate":"2026-08-11 10:30:00"}
 ```
 
 For `duplicate`, also pass `"duplicateBug": <id>`. Send JSON through stdin,
 not as a command-line argument. The CLI handles UTF-8 form encoding and
 computes a task's total consumed hours from its current ZenTao value.
+`start`, `pause`, and `resume` accept an optional `comment`; `start` also
+accepts `realStarted` and otherwise uses the current time. The CLI preserves
+the task's current hours when starting or resuming it.
 `log-hours` defaults `date` to today, requires positive remaining hours,
-and keeps the task open. Use `finish` when the task is complete.
+and keeps the task open. `hours` is read-only. `edit-hours` preserves omitted
+fields from the existing record and updates it through ZenTao's native effort
+workflow. Use `finish` when the task is complete.
 
 ## Usage
 
@@ -116,10 +128,14 @@ and keeps the task open. Use `finish` when the task is complete.
 - `/at-zentao export bug <id>` or `export task <id>` — create a read-only,
   self-contained handoff bundle.
 
-Treat text after an item id as a natural-language request. Phrases such as
-`填工时`, `记录工时`, `log hours`, and `worklog` enter task time-entry mode;
-users do not need to know the internal `log-hours` CLI command. Reuse any date,
-hours, or work description already supplied instead of asking twice.
+Treat text after an item id as a natural-language request. Recognize task
+lifecycle requests such as `开始`, `暂停`, `继续`, `start`, `pause`, and
+`resume`, and time-entry requests such as `填工时`, `记录工时`, `log hours`,
+and `worklog`. Users do not need to know the internal CLI commands. Reuse any
+date, hours, or work description already supplied instead of asking twice.
+Recognize corrections to an existing time entry. Run `hours`, identify the
+record from returned ids and values, and ask when more than one record could
+match; never guess or call `log-hours` again to compensate for a mistake.
 
 If a list response includes pager data showing more items than returned, tell
 the user the shown and total counts. Do not silently imply the list is complete.
@@ -131,6 +147,14 @@ planning the implementation. Use its `spec` and `verify` fields to identify
 scope, acceptance criteria, constraints, and non-goals. Keep the Bug or Task as
 the unit of work: never change, close, activate, or comment on the Story.
 
+For a Task in `wait`, offer `start` when the user is about to work on it. For a
+Task in `pause`, offer `resume`; the CLI maps this to ZenTao's `restart`
+operation. Invoke `pause` only when the user explicitly asks or confirms that
+the work itself is paused; the end of a session or workday is not enough. These
+are status writes, so show the transition and optional comment and obtain
+explicit confirmation before invoking the CLI. Starting or resuming preserves
+the current hours and never implies new consumed time.
+
 ## Per-item workflow
 
 Follow these steps in order:
@@ -164,6 +188,11 @@ Bug resolutions are `fixed`, `notrepro`, `duplicate`, `bydesign`, `external`,
 write-back comment is one sentence containing root cause, change summary, and
 the commit hash when committed.
 
+Immediately before confirming any ZenTao write that cites the latest commit,
+run `git rev-parse HEAD` and `git log -1 --format=%h`. Do not reuse a hash from
+earlier conversation. If HEAD is not the item-specific commit, identify the
+relevant commit and tell the user instead of blindly citing HEAD.
+
 For tasks, ask whether to record the current work after the verified result.
 For an incomplete task, collect the actual `consumed` hours and work date. When
 the task has a numeric current `left`, suggest the new `left` by subtracting the
@@ -175,6 +204,19 @@ collect `currentConsumed` and draft a `finish` write. Never infer consumed
 hours. Show all submitted values and require the same explicit ZenTao
 confirmation before either write.
 
+To correct an existing time entry, use `hours` to select its effort id. Show
+the current and proposed `date`, `consumed`, `left`, and `work`, then obtain
+explicit confirmation and call `edit-hours` once. Preserve every field the
+user did not change. Stop when ownership cannot be verified or the edit route
+is unsupported. If the proposed `left` is zero, explicitly warn that ZenTao
+may change the task status as part of its native recalculation. Never edit an
+action comment as a substitute for correcting the underlying work-hour record,
+and never delete a record.
+
+When the user wants to record hours and pause, show both exact writes in one
+confirmation, then run `log-hours` before `pause`. Stop if the hour write fails.
+Do not add lifecycle support for `activate`, `cancel`, or `close`.
+
 ## Export mode
 
 Export is read-only and never fixes code, commits, or writes back:

package/skills/systems/at-zentao/scripts/zentao-cli.mjs

@@ -459,10 +459,13 @@ async function readInput() {
   return value;
 }
 
-function formBody(fields) {
+function formBody(fields, includeEmpty = []) {
   const body = new URLSearchParams();
+  const keepEmpty = new Set(includeEmpty);
   for (const [key, value] of Object.entries(fields)) {
-    if (value !== undefined && value !== null && value !== "") body.set(key, String(value));
+    if (value !== undefined && value !== null && (value !== "" || keepEmpty.has(key))) {
+      body.set(key, String(value));
+    }
   }
   return body;
 }
@@ -484,8 +487,8 @@ async function workhourVariant(client, id) {
   ];
   for (const variant of variants) {
     try {
-      decodeLegacy(await client.json(variant.route));
-      return variant;
+      const form = decodeLegacy(await client.json(variant.route));
+      return { ...variant, form };
     } catch (error) {
       const unavailable = error instanceof CliError && (
         (error.code === "http_error" && error.status === 404) ||
@@ -500,6 +503,88 @@ async function workhourVariant(client, id) {
   );
 }
 
+function effortRecords(form) {
+  const candidates = [
+    form?.efforts,
+    form?.estimates,
+    form?.workhours,
+    form?.taskEfforts,
+    form?.task?.efforts,
+    form?.task?.estimates,
+  ];
+  const collection = candidates.find((value) => value && typeof value === "object");
+  if (!collection) return [];
+  const entries = Array.isArray(collection)
+    ? collection.map((value) => [null, value])
+    : Object.entries(collection);
+  const records = entries
+    .filter(([, value]) => value && typeof value === "object")
+    .map(([key, value]) => ({
+      ...(value.id === undefined && /^\d+$/.test(key || "") ? { id: Number(key) } : {}),
+      ...pick(value, ["id", "date", "consumed", "left", "work"]),
+    }));
+  return records;
+}
+
+function effortFromEditForm(form) {
+  const effort = form?.effort || form?.estimate || form?.workhour ||
+    (form?.id !== undefined ? form : null);
+  if (!effort || typeof effort !== "object") {
+    throw new CliError("response_error", "ZenTao returned no editable work-hour record");
+  }
+  return effort;
+}
+
+function verifyEffortTask(effort, taskId) {
+  if (effort.objectType !== undefined && effort.objectType !== "task") {
+    throw new CliError("ownership_error", "The work-hour record does not belong to a task");
+  }
+  const owner = effort.objectID ?? effort.task ?? effort.taskID;
+  if (owner === undefined || String(owner) !== String(taskId)) {
+    throw new CliError("ownership_error", "The work-hour record does not belong to the requested task");
+  }
+}
+
+async function editableEffortVariant(client, effortId) {
+  const variants = [
+    { route: `task-editeffort-${effortId}.json`, legacy: false },
+    { route: `task-editestimate-${effortId}.json`, legacy: true },
+  ];
+  for (const variant of variants) {
+    try {
+      const form = decodeLegacy(await client.json(variant.route));
+      return { ...variant, effort: effortFromEditForm(form) };
+    } catch (error) {
+      const unavailable = error instanceof CliError && (
+        (error.code === "http_error" && error.status === 404) ||
+        error.code === "response_error"
+      );
+      if (!unavailable) throw error;
+    }
+  }
+  throw new CliError(
+    "unsupported_version",
+    "ZenTao exposes neither editEffort nor editEstimate for this work-hour record"
+  );
+}
+
+function effortFields(effort, input) {
+  const date = effortDate(input.date ?? effort.date);
+  const consumed = Number(input.consumed ?? effort.consumed);
+  const left = Number(input.left ?? effort.left);
+  const work = input.work ?? effort.work ?? "";
+  if (!Number.isFinite(consumed) || consumed <= 0) {
+    throw new CliError("usage_error", "consumed must be positive");
+  }
+  if (!Number.isFinite(left) || left < 0) {
+    throw new CliError("usage_error", "left must be zero or positive");
+  }
+  if (typeof work !== "string") {
+    throw new CliError("usage_error", "work must be a string");
+  }
+  return { date, consumed, left, work: work.trim() };
+}
+
 function localDateTime(date = new Date()) {
   const part = (value) => String(value).padStart(2, "0");
   return `${date.getFullYear()}-${part(date.getMonth() + 1)}-${part(date.getDate())} ${part(date.getHours())}:${part(date.getMinutes())}:${part(date.getSeconds())}`;
@@ -534,7 +619,12 @@ function help() {
   zentao-cli.mjs get <bug|task|story> <id> [--download-dir <path>]
   zentao-cli.mjs resolve bug <id>          # JSON on stdin
   zentao-cli.mjs comment <bug|task> <id>   # {"comment":"..."} on stdin
+  zentao-cli.mjs start task <id>           # JSON on stdin
+  zentao-cli.mjs pause task <id>           # JSON on stdin
+  zentao-cli.mjs resume task <id>          # JSON on stdin
+  zentao-cli.mjs hours task <id>
   zentao-cli.mjs log-hours task <id>       # JSON on stdin
+  zentao-cli.mjs edit-hours task <id> <effort-id> # JSON on stdin
   zentao-cli.mjs finish task <id>          # JSON on stdin`;
 }
 
@@ -614,6 +704,59 @@ export async function run(argv, { env = process.env } = {}) {
     return legacyResult(response);
   }
 
+  if (["start", "pause", "resume"].includes(command)) {
+    if (args[0] !== "task") throw new CliError("usage_error", `${command} supports tasks only`);
+    const id = positiveId(args[1]);
+    const input = await readInput();
+    if (input.comment !== undefined && typeof input.comment !== "string") {
+      throw new CliError("usage_error", "comment must be a string when provided");
+    }
+    if (input.realStarted !== undefined && (
+      command !== "start" ||
+      typeof input.realStarted !== "string" ||
+      !input.realStarted.trim()
+    )) {
+      throw new CliError("usage_error", "realStarted is accepted only for start and must be a non-empty string");
+    }
+
+    const method = command === "resume" ? "restart" : command;
+    const route = `task-${method}-${id}.json`;
+    const form = decodeLegacy(await client.json(route));
+    const task = form?.task || form;
+    const fields = { comment: input.comment?.trim() };
+
+    if (command !== "pause") {
+      const consumed = Number(task?.consumed);
+      const left = Number(task?.left);
+      if (!Number.isFinite(consumed) || consumed < 0 || !Number.isFinite(left) || left <= 0) {
+        throw new CliError("response_error", "ZenTao task has no safe current consumed/left values for this transition");
+      }
+      const assignedTo = typeof task.assignedTo === "string" && task.assignedTo
+        ? task.assignedTo
+        : config.account;
+      const existingStarted = typeof task.realStarted === "string" &&
+        task.realStarted.trim() &&
+        !task.realStarted.startsWith("0000-00-00")
+        ? task.realStarted
+        : null;
+      Object.assign(fields, {
+        assignedTo,
+        consumed,
+        left,
+        realStarted: command === "start"
+          ? input.realStarted?.trim() || localDateTime()
+          : existingStarted || localDateTime(),
+      });
+    }
+
+    const response = await client.json(route, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: formBody(fields),
+    });
+    return legacyResult(response);
+  }
+
   if (command === "log-hours") {
     if (args[0] !== "task") throw new CliError("usage_error", "log-hours supports tasks only");
     const id = positiveId(args[1]);
@@ -646,6 +789,36 @@ export async function run(argv, { env = process.env } = {}) {
     return legacyResult(response);
   }
 
+  if (command === "hours") {
+    if (args[0] !== "task") throw new CliError("usage_error", "hours supports tasks only");
+    const id = positiveId(args[1]);
+    const variant = await workhourVariant(client, id);
+    return { records: effortRecords(variant.form) };
+  }
+
+  if (command === "edit-hours") {
+    if (args[0] !== "task") throw new CliError("usage_error", "edit-hours supports tasks only");
+    const taskId = positiveId(args[1]);
+    const effortId = positiveId(args[2]);
+    const input = await readInput();
+    const allowed = ["date", "consumed", "left", "work"];
+    if (!allowed.some((field) => Object.hasOwn(input, field))) {
+      throw new CliError("usage_error", "at least one work-hour field is required");
+    }
+    if (input.work !== undefined && typeof input.work !== "string") {
+      throw new CliError("usage_error", "work must be a string when provided");
+    }
+    const variant = await editableEffortVariant(client, effortId);
+    verifyEffortTask(variant.effort, taskId);
+    const fields = effortFields(variant.effort, input);
+    const response = await client.json(variant.route, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: formBody(fields, ["work"]),
+    });
+    return legacyResult(response);
+  }
+
   if (command === "finish") {
     if (args[0] !== "task") throw new CliError("usage_error", "finish supports tasks only");
     const id = positiveId(args[1]);