@kairyou/agent-tools 0.22.0 → 0.23.1

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

@@ -78,6 +78,12 @@ node <skill-root>/scripts/zentao-cli.mjs hours task <id>
 `get` downloads token-gated inline images and attachments into a temporary
 directory by default and returns only local paths. Inspect those local files;
 never pass the original ZenTao URL to an image tool.
+For Bugs and Tasks, a configured `zentao.commentPrompt` is returned as
+`writeback.commentPrompt`. Use it only when drafting a write-back comment; it
+is not item data or an existing comment. `get` also returns safe `comments`
+from action history, keeping only id, actor, action, date, and non-empty
+comment. An omitted `comments` means actions were unavailable; an empty array
+means actions were available but contained no comments.
 
 Write commands require JSON on stdin and are allowed only after the explicit
 confirmation steps below:
@@ -98,11 +104,11 @@ Input shapes:
 
 ```json
 {"comment":"Root cause and result."}
-{"resolution":"fixed","resolvedBuild":"trunk","comment":"Root cause and result, commit abc1234."}
+{"resolution":"fixed","resolvedBuild":"trunk","comment":"Root cause: stale session cache; Fix: refresh it during renewal; 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"}
+{"currentConsumed":1.5,"realStarted":"2026-08-11 09:00:00","finishedDate":"2026-08-11 10:30:00","comment":"Completed: implemented session renewal; Commit: abc1234."}
 ```
 
 For `duplicate`, also pass `"duplicateBug": <id>`. Send JSON through stdin,
@@ -114,7 +120,7 @@ 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. `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.
+workflow. Use `finish` when the task is complete; its `comment` is optional.
 
 ## Usage
 
@@ -159,9 +165,11 @@ the current hours and never implies new consumed time.
 
 Follow these steps in order:
 
-1. **Fetch details** — use the CLI `get` command. Read every downloaded image
-   now so screenshots inform the fix. If no image-inspection tool is available,
-   continue from text and state that screenshots were skipped.
+1. **Fetch details** — use the CLI `get` command. Review every returned comment,
+   including comments attached to resolution, activation, and lifecycle actions.
+   Read every downloaded image now so screenshots inform the fix. If no
+   image-inspection tool is available, continue from text and state that
+   screenshots were skipped.
 2. **Restate and confirm** — explain the problem and intended fix in your own
    words. Ask before editing when the item is ambiguous.
 3. **Locate the code** — search the current project and explain how the relevant
@@ -185,8 +193,20 @@ Follow these steps in order:
 
 Bug resolutions are `fixed`, `notrepro`, `duplicate`, `bydesign`, `external`,
 `postponed`, and `willnotfix`. Choose what matches the verified outcome. A
-write-back comment is one sentence containing root cause, change summary, and
-the commit hash when committed.
+write-back comment follows the current user request, then
+`writeback.commentPrompt`. Otherwise use the item or user's language and these
+defaults:
+
+- For a fixed Bug, use `Root cause`, `Fix`, optional `Verification`, and the
+  real `Commit`.
+- For a finished Task, use `Completed`, optional `Verification`, and `Commit`
+  only when the work has a related commit.
+- For other Bug resolutions, use `Conclusion` and applicable `Reason` or
+  `Evidence`.
+- Keep standalone and lifecycle comments free-form but concise.
+
+Formatting controls wording and layout only. Never invent missing facts;
+surface required gaps and put `Commit: <hash>` last.
 
 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
@@ -200,9 +220,10 @@ current entry and make that estimate editable in the confirmation; ask only
 when no reliable suggestion is possible. Draft `work` from the verified result
 when context is available. It is optional, so mention the omission without
 blocking the write when there is nothing useful to add. For a completed task,
-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.
+collect `currentConsumed`, draft the completion comment from established facts,
+and include both in the `finish` write. Never infer consumed hours or a
+verification result. 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

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

@@ -9,6 +9,8 @@ import { fileURLToPath } from "node:url";
 const JSON_LIMIT = 4 * 1024 * 1024;
 const BINARY_LIMIT = 20 * 1024 * 1024;
 const INPUT_LIMIT = 1024 * 1024;
+// Keep write-back guidance compact enough to remain useful in an agent response.
+const COMMENT_PROMPT_LIMIT = 1000;
 const SECRET_KEYS = /^(?:password|token|authorization|cookie|set-cookie)$/i;
 const RESOLUTIONS = new Set([
   "fixed",
@@ -148,6 +150,7 @@ export function loadConfig({ env = process.env, file = configFile(env) } = {}) {
   const rawAccount = env.ZENTAO_ACCOUNT || section.account;
   const rawPassword = env.ZENTAO_PASSWORD || section.password;
   const rawToken = env.ZENTAO_TOKEN;
+  const rawCommentPrompt = section.commentPrompt;
   const urlText = resolveValue(rawUrl, env, "zentao.url");
   let parsedUrl;
   try {
@@ -171,12 +174,23 @@ export function loadConfig({ env = process.env, file = configFile(env) } = {}) {
   const token = resolveValue(rawToken, env, "zentao.token", { required: false });
   const account = resolveValue(rawAccount, env, "zentao.account", { required: !token });
   const password = resolveValue(rawPassword, env, "zentao.password", { required: !token });
+  if (rawCommentPrompt !== undefined && typeof rawCommentPrompt !== "string") {
+    throw new CliError("config_error", "zentao.commentPrompt must be a string");
+  }
+  const commentPrompt = rawCommentPrompt?.trim() || null;
+  if (commentPrompt && commentPrompt.length > COMMENT_PROMPT_LIMIT) {
+    throw new CliError(
+      "config_error",
+      `zentao.commentPrompt must not exceed ${COMMENT_PROMPT_LIMIT} characters`
+    );
+  }
   return {
     url: parsedUrl.href.replace(/\/$/, ""),
     account,
     password,
     token,
     tokenOnly: Boolean(token),
+    commentPrompt,
     secrets: [account, password, token].filter(Boolean),
   };
 }
@@ -385,6 +399,23 @@ function pick(source, keys) {
   return output;
 }
 
+function normalizeComments(actions) {
+  const entries = Array.isArray(actions) ? actions : Object.values(actions || {});
+  const comments = [];
+  for (const entry of entries) {
+    if (!entry || typeof entry !== "object" || typeof entry.comment !== "string") continue;
+    const comment = entry.comment.trim();
+    if (!comment) continue;
+    const output = {};
+    for (const key of ["id", "actor", "action", "date"]) {
+      if (typeof entry[key] === "string" || typeof entry[key] === "number") output[key] = entry[key];
+    }
+    output.comment = comment;
+    comments.push(output);
+  }
+  return comments;
+}
+
 function normalizeDetail(kind, response) {
   const container = response?.data && typeof response.data === "object" ? response.data : response;
   const detail = container?.[kind] || container;
@@ -414,7 +445,12 @@ function normalizeDetail(kind, response) {
   } else if (kind === "story") {
     fields.push("stage", "category", "plan", "estimate", "spec", "verify", "source", "sourceNote");
   }
-  return { raw: detail, safe: pick(detail, fields) };
+  const safe = pick(detail, fields);
+  const actions = detail.actions ?? container?.actions;
+  if ((kind === "bug" || kind === "task") && actions && typeof actions === "object") {
+    safe.comments = normalizeComments(actions);
+  }
+  return { raw: detail, safe };
 }
 
 function attachmentUrls(detail) {
@@ -682,7 +718,13 @@ export async function run(argv, { env = process.env } = {}) {
     const resource = kind === "story" ? "stories" : `${kind}s`;
     const detail = normalizeDetail(kind, await client.json(`api.php/v1/${resource}/${id}`));
     const attachments = await downloadAttachments(client, detail.raw, directory);
-    return { item: detail.safe, attachments };
+    return {
+      item: detail.safe,
+      attachments,
+      ...(kind !== "story" && config.commentPrompt
+        ? { writeback: { commentPrompt: config.commentPrompt } }
+        : {}),
+    };
   }
 
   if (command === "comment") {
@@ -842,6 +884,9 @@ export async function run(argv, { env = process.env } = {}) {
     const input = await readInput();
     const current = Number(input.currentConsumed);
     if (!Number.isFinite(current) || current <= 0) throw new CliError("usage_error", "currentConsumed must be positive");
+    if (input.comment !== undefined && typeof input.comment !== "string") {
+      throw new CliError("usage_error", "comment must be a string when provided");
+    }
     const form = decodeLegacy(await client.json(`task-finish-${id}.json`));
     const task = form?.task || {};
     const previous = Number(task.consumed || 0);
@@ -855,6 +900,7 @@ export async function run(argv, { env = process.env } = {}) {
         consumed: previous + current,
         realStarted,
         finishedDate: input.finishedDate || localDateTime(),
+        comment: input.comment?.trim(),
       }),
     });
     return legacyResult(response);