team-toon-tack 3.10.3 → 3.11.0

package/.claude-plugin/marketplace.json

@@ -13,7 +13,7 @@
 			"name": "team-toon-tack",
 			"source": "./",
 			"description": "Linear/Trello task sync & management CLI with commands and skills",
-			"version": "3.10.3"
+			"version": "3.11.0"
 		}
 	]
 }

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
 	"name": "team-toon-tack",
 	"description": "Linear/Trello task sync & management CLI for Claude Code - saves tokens vs MCP",
-	"version": "3.10.3",
+	"version": "3.11.0",
 	"author": {
 		"name": "wayne930242",
 		"email": "wayne930242@gmail.com"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "team-toon-tack",
-	"version": "3.10.3",
+	"version": "3.11.0",
 	"description": "透過 ttt CLI 同步與管理 Linear、Trello 任務。",
 	"author": {
 		"name": "wayne930242"

package/README.md

@@ -58,7 +58,7 @@ During init, you'll be prompted to select your task source (Linear or Trello) an
 |------|----------|
 | `simple` | Mark task as Done + parent as Done. Default when no QA team configured. |
 | `strict_review` | Mark task to dev testing + parent to QA testing. |
-| `upstream_strict` | Mark task as Done + parent to Testing. Falls back to dev testing if no parent. Default when QA team configured. |
+| `upstream_strict` | Mark task as Done + parent to Testing. Falls back to dev testing if no parent (the task then goes straight to testing, without a Done step). Default when QA team configured. |
 | `upstream_not_strict` | Mark task as Done + parent to Testing. No fallback if no parent. |
 
 > **Note:** Trello always uses simple completion mode as it doesn't support parent issues.
@@ -181,9 +181,13 @@ ttt done                         # Auto-select if only one in-progress
 ttt done MP-123                  # Specific issue
 ttt done -m "Fixed the bug"      # With completion message
 ttt done MP-123 --from-remote    # Fetch from remote (bypasses local data check)
+ttt done MP-123 --commit 1a2b3c4 # Record this commit instead of HEAD
+ttt done MP-123 --commit 1a2b3c4 --repo ~/projects/app   # ...read from another repository
 ```
 
-Use `--from-remote` (or `-r`) when the issue exists in remote but not in local sync data.
+Use `--from-remote` (or `-r`) when the issue exists in remote but not in local sync data, or when the ticket is still Todo and you want to complete it without `ttt claim` (no extra In Progress transition). `ttt done` without it only accepts in-progress tasks.
+
+Use `--commit <sha>` (and `--repo <path>` when the commit lives in another checkout) to close a ticket whose commit was merged earlier. Without it, the current HEAD is recorded.
 
 ### `ttt status`
 

package/README.zh-TW.md

@@ -58,7 +58,7 @@ ttt init
 |------|------|
 | `simple` | 任務標記為 Done，parent 也標記為 Done。未設定 QA 團隊時的預設值。 |
 | `strict_review` | 任務標記到開發團隊的 testing 狀態，parent 標記到 QA 團隊的 testing 狀態。 |
-| `upstream_strict` | 任務標記為 Done，parent 移動到 Testing。若無 parent，fallback 到開發團隊的 testing 狀態。設定 QA 團隊時的預設值。 |
+| `upstream_strict` | 任務標記為 Done，parent 移動到 Testing。若無 parent，fallback 到開發團隊的 testing 狀態（此時任務直接進 testing，不會先寫 Done）。設定 QA 團隊時的預設值。 |
 | `upstream_not_strict` | 任務標記為 Done，parent 移動到 Testing。若無 parent 不做 fallback。 |
 
 > **注意**：Trello 因不支援 parent issue，一律使用簡單完成模式。
@@ -181,9 +181,13 @@ ttt done                         # 若只有一個進行中，自動選擇
 ttt done MP-123                  # 指定 issue
 ttt done -m "修復了錯誤"           # 附上完成說明
 ttt done MP-123 --from-remote    # 從遠端取得（略過本地資料檢查）
+ttt done MP-123 --commit 1a2b3c4 # 記錄指定 commit，而非目前 HEAD
+ttt done MP-123 --commit 1a2b3c4 --repo ~/projects/app   # ...從另一個 repository 讀取
 ```
 
-當 issue 存在於遠端但未同步到本地資料時，使用 `--from-remote`（或 `-r`）。
+當 issue 存在於遠端但未同步到本地資料，或 ticket 仍是 Todo、想不經 `ttt claim`（不多一次 In Progress 轉換）直接完成時，使用 `--from-remote`（或 `-r`）。不加此參數時，`ttt done` 只接受進行中的任務。
+
+要關閉 commit 早已合併的 ticket，用 `--commit <sha>`（commit 在另一個 checkout 時再加 `--repo <path>`）。未指定時記錄目前的 HEAD。
 
 ### `ttt status`
 

package/commands/ttt-create.md

@@ -45,7 +45,7 @@ Options:
   -d, --description <text> Description
   -a, --assignee <key>     Assignee user key from config
   -p, --priority <0-4>     Priority (0=none, 1=urgent, 2=high, 3=medium, 4=low)
-  -l, --label <names>      Label names (comma-separated)
+  -l, --label <names>      Label names (comma-separated; config first, then looked up live in Linear)
   -s, --status <name>      Initial status name
   --parent <id>            Parent issue identifier (e.g., MP-100)
   --no-interactive         Skip interactive prompts

package/commands/ttt-done.md

@@ -11,6 +11,12 @@ arguments:
   - name: from-remote
     description: Fetch issue from Linear (bypass local data check)
     required: false
+  - name: commit
+    description: Commit to record instead of HEAD (e.g., an already merged commit)
+    required: false
+  - name: repo
+    description: Git repository to read the commit from (default - cwd)
+    required: false
 ---
 
 <law>
@@ -24,7 +30,7 @@ DO NOT skip this command — it updates both local and remote status, posts a co
 ## Execution
 
 ```bash
-ttt done {{ issue-id }} {{ "-m \"" + message + "\"" if message }} {{ "--from-remote" if from-remote }}
+ttt done {{ issue-id }} {{ "-m \"" + message + "\"" if message }} {{ "--from-remote" if from-remote }} {{ "--commit " + commit if commit }} {{ "--repo " + repo if repo }}
 ```
 
 ### Common Examples
@@ -34,20 +40,24 @@ ttt done                                # Complete current in-progress task
 ttt done MP-624                         # Complete specific task
 ttt done -m "Fixed null check"          # With completion message
 ttt done MP-624 -m "Refactored auth"    # Specific task with message
-ttt done MP-624 --from-remote           # Issue not in local data
+ttt done MP-624 --from-remote           # Issue not in local data, or still Todo (no claim needed)
+ttt done MP-624 --commit 1a2b3c4        # Record an earlier commit, not HEAD
 ```
 
 ## Full CLI Reference
 
 ```
-Usage: ttt done [issue-id] [-m message] [--from-remote]
+Usage: ttt done [issue-id] [-m message] [--from-remote] [--commit <sha>] [--repo <path>]
 
 Arguments:
   issue-id              Optional. Issue ID if multiple tasks in-progress
 
 Options:
   -m, --message         Completion message describing what was done
-  -r, --from-remote     Fetch issue from Linear (bypass local data check)
+  -r, --from-remote     Fetch issue from Linear (bypass local data check;
+                        also completes a Todo ticket without `ttt claim`)
+  --commit <sha>        Record this commit instead of HEAD
+  --repo <path>         Git repository to read the commit from (default: cwd)
 ```
 
 ## Before Running
@@ -64,7 +74,7 @@ Based on configured completion mode:
 |------|-------------|---------------|
 | `simple` | → Done | → Done |
 | `strict_review` | → Testing | → QA Testing |
-| `upstream_strict` | → Done | → Testing |
+| `upstream_strict` | → Done | → Testing (no valid parent: task goes straight to Testing) |
 | `upstream_not_strict` | → Done | → Testing (no fallback) |
 
 Additionally:
@@ -79,4 +89,5 @@ Additionally:
 | `No in-progress task` | Specify issue-id explicitly |
 | `Multiple in-progress` | Specify issue-id to disambiguate |
 | `Issue not found` | Use `--from-remote` flag |
+| `不在進行中狀態` (task is Todo) | `ttt claim <id>` first, or `ttt done <id> --from-remote` |
 | `No commits found` | Commit your changes first |

package/dist/scripts/create.d.ts

@@ -1,2 +1,10 @@
 #!/usr/bin/env bun
+import type { SourceLabel } from "./lib/adapters/types.js";
+import { type Config } from "./utils.js";
+/**
+ * Resolve `-l` names to label ids. Config is checked first (key or display
+ * name); anything it does not know is looked up live in the source, so a
+ * label added after `ttt init` still works.
+ */
+export declare function resolveLabelIds(config: Config, labelArg: string | undefined, fetchSourceLabels: () => Promise<SourceLabel[]>): Promise<string[] | undefined>;
 export declare function create(args?: string[]): Promise<void>;

package/dist/scripts/create.js

@@ -95,20 +95,50 @@ async function resolveStatusId(config, adapter, teamId, statusName) {
     }
     return target.id;
 }
-function resolveLabelIds(config, labelArg) {
-    if (!labelArg || !config.labels)
+/**
+ * Resolve `-l` names to label ids. Config is checked first (key or display
+ * name); anything it does not know is looked up live in the source, so a
+ * label added after `ttt init` still works.
+ */
+export async function resolveLabelIds(config, labelArg, fetchSourceLabels) {
+    if (!labelArg)
         return undefined;
-    const names = labelArg.split(",").map((n) => n.trim());
+    const names = labelArg
+        .split(",")
+        .map((n) => n.trim())
+        .filter(Boolean);
     const ids = [];
+    const unresolved = [];
     for (const name of names) {
         const lower = name.toLowerCase();
         // Match by config key (e.g. "backend_v3") OR display name (e.g. "Backend-v3")
-        const entry = Object.entries(config.labels).find(([key, l]) => key.toLowerCase() === lower || l.name.toLowerCase() === lower);
+        const entry = Object.entries(config.labels ?? {}).find(([key, l]) => key.toLowerCase() === lower || l.name.toLowerCase() === lower);
         if (entry) {
             ids.push(entry[1].id);
         }
         else {
-            console.error(`Warning: label "${name}" not found in config, skipping.`);
+            unresolved.push(name);
+        }
+    }
+    if (unresolved.length > 0) {
+        let sourceLabels;
+        try {
+            sourceLabels = await fetchSourceLabels();
+        }
+        catch {
+            // Fall through to the config-only warning below
+        }
+        for (const name of unresolved) {
+            const found = sourceLabels?.find((l) => l.name.toLowerCase() === name.toLowerCase());
+            if (found) {
+                ids.push(found.id);
+            }
+            else if (sourceLabels) {
+                console.error(`Warning: label "${name}" not found in config or in the source, skipping. Available: ${sourceLabels.map((l) => l.name).join(", ")}`);
+            }
+            else {
+                console.error(`Warning: label "${name}" not found in config (source lookup failed), skipping.`);
+            }
         }
     }
     return ids.length > 0 ? ids : undefined;
@@ -216,7 +246,7 @@ Examples:
     }
     const assigneeId = resolveAssigneeId(config, assigneeKey);
     const statusId = await resolveStatusId(config, adapter, teamId, sourceType === "trello" && !statusName ? "todo" : statusName);
-    const labelIds = resolveLabelIds(config, labelArg);
+    const labelIds = await resolveLabelIds(config, labelArg, () => adapter.getLabels(teamId));
     const parentSourceId = await resolveParentSourceId(adapter, parentId);
     const currentCycle = await adapter.getCurrentCycle(teamId);
     const options = {

package/dist/scripts/done-job.js

@@ -5,6 +5,7 @@
  */
 import { input, select } from "@inquirer/prompts";
 import { handleLinearCompletion, handleTrelloCompletion, parseArgs, printHelp, } from "./lib/done/index.js";
+import { describeNotInProgress, syncUntilStatus, } from "./lib/done/status-check.js";
 import { getLatestCommit } from "./lib/git.js";
 import { fetchIssueDetail, syncSingleIssue } from "./lib/sync.js";
 import { findTaskByIssueId, getSourceType, loadConfig, loadCycleData, loadLocalConfig, saveCycleData, } from "./utils.js";
@@ -14,7 +15,7 @@ async function doneJob() {
         printHelp();
         process.exit(0);
     }
-    const { issueId: argIssueId, message: argMessage, fromRemote, } = parseArgs(args);
+    const { issueId: argIssueId, message: argMessage, fromRemote, commit: commitRef, repo, } = parseArgs(args);
     let issueId = argIssueId;
     const config = await loadConfig();
     const localConfig = await loadLocalConfig();
@@ -45,7 +46,9 @@ async function doneJob() {
         }
         // Find in-progress tasks
         const inProgressTasks = data.tasks.filter((t) => t.localStatus === "in-progress");
-        if (inProgressTasks.length === 0) {
+        // With an explicit issue ID, fall through so the status guard below can
+        // say why that ticket cannot be completed
+        if (inProgressTasks.length === 0 && !issueId) {
             console.log("沒有進行中的任務");
             process.exit(0);
         }
@@ -87,13 +90,17 @@ async function doneJob() {
             process.exit(1);
         }
         if (localTask.localStatus !== "in-progress") {
-            console.log(`⚠️ 任務 ${localTask.id} 不在進行中狀態 (目前: ${localTask.localStatus})`);
+            console.error(describeNotInProgress(localTask));
             process.exit(1);
         }
         task = localTask;
     }
-    // Get latest commit
-    const commit = getLatestCommit();
+    // Get the commit to record: HEAD by default, or the one named with --commit
+    const commit = getLatestCommit({ ref: commitRef, cwd: repo });
+    if ((commitRef || repo) && !commit) {
+        console.error(`Cannot read commit ${commitRef ?? "HEAD"} from ${repo ?? "the current directory"}. Nothing was changed.`);
+        process.exit(1);
+    }
     // Get AI summary message
     let promptMessage = argMessage || "";
     if (!promptMessage && process.stdin.isTTY) {
@@ -135,16 +142,18 @@ async function doneJob() {
     }
     // Sync full issue data from remote (including new comment)
     if (sourceType === "linear") {
-        const syncedTask = await syncSingleIssue(task.id, {
+        // Let remote status determine local status; wait out read-after-write lag
+        // so a stale read is not recorded as the local state
+        const syncedTask = await syncUntilStatus(() => syncSingleIssue(task.id, {
             config,
             localConfig,
-            preserveLocalStatus: false, // Let remote status determine local status
-        });
+            preserveLocalStatus: false,
+        }), completionResult?.status);
         if (syncedTask) {
             console.log(`Synced: ${syncedTask.id} → ${syncedTask.status} (local: ${syncedTask.localStatus})`);
             if (completionResult?.status &&
                 syncedTask.status !== completionResult.status) {
-                console.error(`Remote status verification failed for ${task.id}: expected ${completionResult.status}, got ${syncedTask.status}.`);
+                console.error(`Remote status verification failed for ${task.id}: expected ${completionResult.status}, got ${syncedTask.status}. Another actor (e.g. a Git integration or automation) may have changed it; check the issue in Linear.`);
                 process.exit(1);
             }
         }
@@ -177,4 +186,7 @@ async function doneJob() {
     }
     console.log(`\n🎉 任務完成！`);
 }
-doneJob().catch(console.error);
+doneJob().catch((error) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exitCode = 1;
+});

package/dist/scripts/lib/adapters/linear-adapter.js

@@ -54,8 +54,13 @@ export class LinearAdapter {
         }));
     }
     async getLabels(teamId) {
+        // Workspace-level labels have no team, so a team-only filter misses them
+        // even though they can be attached to this team's issues
         const labelsData = await this.client.issueLabels({
-            filter: { team: { id: { eq: teamId } } },
+            filter: {
+                or: [{ team: { id: { eq: teamId } } }, { team: { null: true } }],
+            },
+            first: 250,
         });
         return labelsData.nodes.map((label) => ({
             id: label.id,

package/dist/scripts/lib/display.d.ts

@@ -2,11 +2,18 @@ import type { Task } from "../utils.js";
 export declare const PRIORITY_LABELS: Record<number, string>;
 export declare function getStatusIcon(localStatus: Task["localStatus"]): string;
 export declare function displayTaskHeader(task: Task, icon?: string): void;
-export declare function displayTaskInfo(task: Task): void;
+export interface TaskDisplayOptions {
+    /** Print the source status (and local status when `local` is set) and assignee even if empty */
+    status?: {
+        local: boolean;
+    };
+}
+export declare function formatStatusLine(task: Task, includeLocal: boolean): string;
+export declare function displayTaskInfo(task: Task, options?: TaskDisplayOptions): void;
 export declare function displayTaskStatus(task: Task): void;
 export declare function displayTaskDescription(task: Task): void;
 export declare function displayTaskAttachments(task: Task): void;
 export declare function displayTaskComments(task: Task): void;
 export declare function displayTaskFooter(): void;
-export declare function displayTaskFull(task: Task, icon?: string): void;
+export declare function displayTaskFull(task: Task, icon?: string, options?: TaskDisplayOptions): void;
 export declare function displayTaskWithStatus(task: Task): void;

package/dist/scripts/lib/display.js

@@ -25,11 +25,21 @@ export function displayTaskHeader(task, icon) {
     console.log(`${icon || getStatusIcon(task.localStatus)} ${task.id}: ${task.title}`);
     console.log(separator);
 }
-export function displayTaskInfo(task) {
+export function formatStatusLine(task, includeLocal) {
+    return includeLocal
+        ? `Status: ${task.status} (Local: ${task.localStatus})`
+        : `Status: ${task.status}`;
+}
+export function displayTaskInfo(task, options = {}) {
+    if (options.status) {
+        console.log(formatStatusLine(task, options.status.local));
+    }
     console.log(`Priority: ${PRIORITY_LABELS[task.priority] || "None"}`);
     console.log(`Labels: ${task.labels.join(", ")}`);
     if (task.assignee)
         console.log(`Assignee: ${task.assignee}`);
+    else if (options.status)
+        console.log("Assignee: Unassigned");
     if (task.estimate) {
         const suffix = task.estimate.note ? ` (${task.estimate.note})` : "";
         console.log(`Estimate: ${task.estimate.hours}h${suffix}`);
@@ -82,9 +92,9 @@ export function displayTaskComments(task) {
 export function displayTaskFooter() {
     console.log(`\n${"─".repeat(50)}`);
 }
-export function displayTaskFull(task, icon) {
+export function displayTaskFull(task, icon, options = {}) {
     displayTaskHeader(task, icon);
-    displayTaskInfo(task);
+    displayTaskInfo(task, options);
     displayTaskDescription(task);
     displayTaskAttachments(task);
     displayTaskComments(task);

package/dist/scripts/lib/done/args.js

@@ -5,6 +5,8 @@ export function parseArgs(args) {
     let issueId;
     let message;
     let fromRemote = false;
+    let commit;
+    let repo;
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
         if (arg === "-m" || arg === "--message") {
@@ -13,14 +15,24 @@ export function parseArgs(args) {
         else if (arg === "--from-remote" || arg === "-r") {
             fromRemote = true;
         }
+        else if (arg === "--commit" || arg === "--repo") {
+            const value = args[++i];
+            if (!value || value.startsWith("-")) {
+                throw new Error(`${arg} requires a value.`);
+            }
+            if (arg === "--commit")
+                commit = value;
+            else
+                repo = value;
+        }
         else if (!arg.startsWith("-")) {
             issueId = arg;
         }
     }
-    return { issueId, message, fromRemote };
+    return { issueId, message, fromRemote, commit, repo };
 }
 export function printHelp() {
-    console.log(`Usage: ttt done [issue-id] [-m message] [--from-remote]
+    console.log(`Usage: ttt done [issue-id] [-m message] [--from-remote] [--commit <sha>] [--repo <path>]
 
 Arguments:
   issue-id          Issue ID (e.g., MP-624). Optional if only one task is in-progress
@@ -28,12 +40,19 @@ Arguments:
 Options:
   -m, --message     AI summary message describing the fix
   -r, --from-remote Fetch issue directly from Linear (bypasses local data check)
-                    Use when issue exists in Linear but not in local sync data
+                    Use when issue exists in Linear but not in local sync data.
+                    Also completes a ticket that is still Todo without 'ttt claim'
+                    (no extra In Progress transition)
+  --commit <sha>    Record this commit instead of the current HEAD
+                    (for closing a ticket whose commit was merged earlier)
+  --repo <path>     Git repository to read the commit from (default: cwd)
 
 Examples:
   ttt done                         # Complete current in-progress task
   ttt done MP-624                  # Complete specific task
   ttt done -m "Fixed null check"   # With completion message
   ttt done MP-624 -m "Refactored"  # Specific task with message
-  ttt done MP-624 --from-remote    # Complete issue fetched directly from Linear`);
+  ttt done MP-624 --from-remote    # Complete issue fetched directly from Linear
+  ttt done MP-624 --commit 1a2b3c4 # Record an earlier commit, not HEAD
+  ttt done MP-624 --commit 1a2b3c4 --repo ~/projects/app`);
 }

package/dist/scripts/lib/done/linear-handler.d.ts

@@ -1,7 +1,19 @@
 /**
  * Linear completion handler
  */
+import { updateIssueStatus } from "../linear.js";
+import { updateParentToTesting } from "./parent-issue.js";
 import type { CompletionContext, CompletionResult } from "./types.js";
+/** Linear calls the completion handlers make; injectable so tests need no network. */
+export interface CompletionDeps {
+    updateIssueStatus: typeof updateIssueStatus;
+    updateParentToTesting: typeof updateParentToTesting;
+}
+/**
+ * Handle upstream completion modes (upstream_strict and upstream_not_strict)
+ * Mark as done, then update parent to testing
+ */
+export declare function handleUpstreamCompletion(context: CompletionContext, isStrict: boolean, deps?: CompletionDeps): Promise<CompletionResult>;
 /**
  * Handle Linear task completion with complex completion modes
  */

package/dist/scripts/lib/done/linear-handler.js

@@ -4,6 +4,11 @@
 import { buildCompletionComment } from "../git.js";
 import { addComment, getStatusTransitions, updateIssueStatus, } from "../linear.js";
 import { updateParentStatus, updateParentToTesting } from "./parent-issue.js";
+const defaultDeps = {
+    updateIssueStatus,
+    updateParentToTesting,
+};
+const STRICT_FALLBACK_HINT = 'completion_mode is upstream_strict; set it to "upstream_not_strict" or "simple" (ttt config) to keep Done';
 function logParentUnchanged(parentIssueId, unfinishedChildren) {
     console.log(`Linear: Parent ${parentIssueId} unchanged (unfinished sub-issues: ${unfinishedChildren.join(", ")})`);
 }
@@ -90,13 +95,31 @@ async function handleStrictReview(context) {
  * Handle upstream completion modes (upstream_strict and upstream_not_strict)
  * Mark as done, then update parent to testing
  */
-async function handleUpstreamCompletion(context, isStrict) {
+export async function handleUpstreamCompletion(context, isStrict, deps = defaultDeps) {
     const { task, config, localConfig } = context;
     const transitions = getStatusTransitions(config);
     // Get the testing status to use (from dev team)
     const devTestingStatus = localConfig.dev_testing_status || transitions.testing;
+    const canUpdateParent = Boolean(task.parentIssueId && localConfig.qa_pm_teams?.length);
+    // upstream_strict with nothing to hand off to ends in testing anyway, so go
+    // there directly instead of writing Done and overwriting it a moment later
+    if (isStrict && !canUpdateParent && devTestingStatus) {
+        const reason = task.parentIssueId
+            ? "qa_pm_teams is not configured"
+            : "no parent issue";
+        const success = await deps.updateIssueStatus(task.linearId, devTestingStatus, config, localConfig.team);
+        if (success) {
+            console.log(`Linear: ${task.id} → ${devTestingStatus} (${reason}; ${STRICT_FALLBACK_HINT})`);
+            return { success: true, status: devTestingStatus };
+        }
+        return {
+            success: false,
+            status: task.status,
+            message: `Failed to move ${task.id} to ${devTestingStatus}`,
+        };
+    }
     // First, mark as done
-    const doneSuccess = await updateIssueStatus(task.linearId, transitions.done, config, localConfig.team);
+    const doneSuccess = await deps.updateIssueStatus(task.linearId, transitions.done, config, localConfig.team);
     if (doneSuccess) {
         console.log(`Linear: ${task.id} → ${transitions.done}`);
     }
@@ -105,8 +128,8 @@ async function handleUpstreamCompletion(context, isStrict) {
     let parentTestingStatus;
     // Parent is valid but waits for its other sub-issues; it moves when the last one completes
     let parentAwaitingSiblings = false;
-    if (task.parentIssueId && localConfig.qa_pm_teams?.length) {
-        const result = await updateParentToTesting(task.parentIssueId, task.id, localConfig.qa_pm_teams, config, devTestingStatus);
+    if (task.parentIssueId && canUpdateParent) {
+        const result = await deps.updateParentToTesting(task.parentIssueId, task.id, localConfig.qa_pm_teams ?? [], config, devTestingStatus);
         parentUpdateSuccess = result.success;
         parentTestingStatus = result.testingStatus;
         if (parentUpdateSuccess) {
@@ -122,10 +145,10 @@ async function handleUpstreamCompletion(context, isStrict) {
         !parentUpdateSuccess &&
         !parentAwaitingSiblings &&
         devTestingStatus) {
-        // No parent or parent update failed, fallback to testing
-        const fallbackSuccess = await updateIssueStatus(task.linearId, devTestingStatus, config, localConfig.team);
+        // Parent could not be moved to testing, fallback to testing
+        const fallbackSuccess = await deps.updateIssueStatus(task.linearId, devTestingStatus, config, localConfig.team);
         if (fallbackSuccess) {
-            console.log(`Linear: ${task.id} → ${devTestingStatus} (fallback, no valid parent)`);
+            console.log(`Linear: ${task.id} → ${devTestingStatus} (fallback: parent ${task.parentIssueId} could not be moved to testing - its team is not in qa_pm_teams or the update failed; ${STRICT_FALLBACK_HINT})`);
             return { success: true, status: devTestingStatus };
         }
         return {

package/dist/scripts/lib/done/status-check.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Guards and post-update checks for `ttt done`
+ */
+import type { Task } from "../../utils.js";
+/**
+ * Explain why a task cannot be completed from its local status, and what to
+ * do instead. `ttt done` completes in-progress work only, so the guard stays;
+ * the message names the two ways forward.
+ */
+export declare function describeNotInProgress(task: Pick<Task, "id" | "localStatus">): string;
+export interface SyncUntilStatusOptions {
+    attempts?: number;
+    delayMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Sync a task until the remote reports the status we just wrote. Linear reads
+ * can lag a write by a moment; syncing once would record the stale status
+ * as the local state and then report a false mismatch.
+ */
+export declare function syncUntilStatus(sync: () => Promise<Task | null>, expectedStatus: string | undefined, options?: SyncUntilStatusOptions): Promise<Task | null>;

package/dist/scripts/lib/done/status-check.js

@@ -0,0 +1,37 @@
+/**
+ * Guards and post-update checks for `ttt done`
+ */
+/**
+ * Explain why a task cannot be completed from its local status, and what to
+ * do instead. `ttt done` completes in-progress work only, so the guard stays;
+ * the message names the two ways forward.
+ */
+export function describeNotInProgress(task) {
+    const lines = [
+        `⚠️ 任務 ${task.id} 不在進行中狀態 (目前: ${task.localStatus})`,
+    ];
+    if (task.localStatus === "completed" || task.localStatus === "in-review") {
+        lines.push(`   已經完成或送審；若要再次執行完成流程，請用 'ttt done ${task.id} --from-remote'。`);
+    }
+    else {
+        lines.push(`   - 'ttt claim ${task.id}' 先領取（Linear 會多一次 In Progress 轉換），或`, `   - 'ttt done ${task.id} --from-remote' 直接從 Linear 完成（不需要先 claim）。`);
+    }
+    return lines.join("\n");
+}
+/**
+ * Sync a task until the remote reports the status we just wrote. Linear reads
+ * can lag a write by a moment; syncing once would record the stale status
+ * as the local state and then report a false mismatch.
+ */
+export async function syncUntilStatus(sync, expectedStatus, options = {}) {
+    const { attempts = 4, delayMs = 1000, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), } = options;
+    let task = await sync();
+    for (let attempt = 1; task &&
+        expectedStatus &&
+        task.status !== expectedStatus &&
+        attempt < attempts; attempt++) {
+        await sleep(delayMs);
+        task = await sync();
+    }
+    return task;
+}

package/dist/scripts/lib/done/types.d.ts

@@ -7,6 +7,10 @@ export interface DoneArgs {
     issueId?: string;
     message?: string;
     fromRemote: boolean;
+    /** Commit-ish to record instead of HEAD */
+    commit?: string;
+    /** Git repository to read the commit from */
+    repo?: string;
 }
 export interface CompletionContext {
     task: Task;

package/dist/scripts/lib/git.d.ts

@@ -5,6 +5,18 @@ export interface CommitInfo {
     diffStat: string;
     commitUrl: string | null;
 }
-export declare function getLatestCommit(): CommitInfo | null;
+export interface CommitLookupOptions {
+    /** Commit-ish to describe (default: HEAD of the repository). */
+    ref?: string;
+    /** Repository directory to read from (default: the process cwd). */
+    cwd?: string;
+}
+/**
+ * Describe a commit. Without `ref` this is HEAD, and the diff stat is taken
+ * against the working tree like before; with `ref` the stat is that commit's
+ * own change (`<ref>~1..<ref>`), so a past commit can be recorded from any
+ * checkout. Returns null when the commit cannot be resolved.
+ */
+export declare function getLatestCommit(options?: CommitLookupOptions): CommitInfo | null;
 export declare function formatCommitLink(commit: CommitInfo): string;
 export declare function buildCompletionComment(commit: CommitInfo, promptMessage?: string): string;

package/dist/scripts/lib/git.js

@@ -1,9 +1,14 @@
-import { execSync } from "node:child_process";
-function getRemoteUrl() {
+import { execFileSync } from "node:child_process";
+function git(args, cwd) {
+    return execFileSync("git", args, {
+        cwd,
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+}
+function getRemoteUrl(cwd) {
     try {
-        return execSync("git remote get-url origin", {
-            encoding: "utf-8",
-        }).trim();
+        return git(["remote", "get-url", "origin"], cwd);
     }
     catch {
         return null;
@@ -27,22 +32,31 @@ function buildCommitUrl(remoteUrl, fullHash) {
     }
     return null;
 }
-export function getLatestCommit() {
+/**
+ * Describe a commit. Without `ref` this is HEAD, and the diff stat is taken
+ * against the working tree like before; with `ref` the stat is that commit's
+ * own change (`<ref>~1..<ref>`), so a past commit can be recorded from any
+ * checkout. Returns null when the commit cannot be resolved.
+ */
+export function getLatestCommit(options = {}) {
+    const { ref, cwd } = options;
+    const target = ref ?? "HEAD";
     try {
-        const shortHash = execSync("git rev-parse --short HEAD", {
-            encoding: "utf-8",
-        }).trim();
-        const fullHash = execSync("git rev-parse HEAD", {
-            encoding: "utf-8",
-        }).trim();
-        const message = execSync("git log -1 --format=%s", {
-            encoding: "utf-8",
-        }).trim();
-        const diffStat = execSync("git diff HEAD~1 --stat --stat-width=60", {
-            encoding: "utf-8",
-        }).trim();
+        const fullHash = git(["rev-parse", "--verify", `${target}^{commit}`], cwd);
+        const shortHash = git(["rev-parse", "--short", fullHash], cwd);
+        const message = git(["log", "-1", "--format=%s", fullHash], cwd);
+        // A root commit has no parent to diff against; keep the commit anyway.
+        let diffStat = "";
+        try {
+            diffStat = git(ref
+                ? ["diff", `${fullHash}~1`, fullHash, "--stat", "--stat-width=60"]
+                : ["diff", "HEAD~1", "--stat", "--stat-width=60"], cwd);
+        }
+        catch {
+            diffStat = "";
+        }
         let commitUrl = null;
-        const remoteUrl = getRemoteUrl();
+        const remoteUrl = getRemoteUrl(cwd);
         if (remoteUrl) {
             commitUrl = buildCommitUrl(remoteUrl, fullHash);
         }

package/dist/scripts/show.js

@@ -3,12 +3,12 @@ import { displayTaskFull, getStatusIcon, PRIORITY_LABELS, } from "./lib/display.
 import { getStatusTransitions } from "./lib/linear.js";
 import { getSyncStatuses } from "./lib/status-helpers.js";
 import { getSourceType, getUserEmails, loadConfig, loadCycleData, loadLocalConfig, } from "./utils.js";
-function taskToMarkdown(task) {
+function taskToMarkdown(task, includeLocal = true) {
     const lines = [];
     const priority = PRIORITY_LABELS[task.priority] || "None";
     lines.push(`## ${task.id}: ${task.title}`);
     lines.push("");
-    lines.push(`- **Status**: ${task.status} (Local: ${task.localStatus})`);
+    lines.push(`- **Status**: ${task.status}${includeLocal ? ` (Local: ${task.localStatus})` : ""}`);
     lines.push(`- **Priority**: ${priority}`);
     lines.push(`- **Labels**: ${task.labels.length > 0 ? task.labels.join(", ") : "-"}`);
     lines.push(`- **Assignee**: ${task.assignee || "Unassigned"}`);
@@ -380,18 +380,20 @@ Examples:
             process.exit(1);
         }
         // Check local data for local status
+        let hasLocal = false;
         const data = await loadCycleData();
         if (data) {
             const localTask = data.tasks.find((t) => t.id === issueId);
             if (localTask) {
                 task.localStatus = localTask.localStatus;
+                hasLocal = true;
             }
         }
         if (exportMarkdown) {
-            console.log(taskToMarkdown(task));
+            console.log(taskToMarkdown(task, hasLocal));
         }
         else {
-            displayTaskFull(task, "📋");
+            displayTaskFull(task, "📋", { status: { local: hasLocal } });
         }
         return;
     }
@@ -411,7 +413,7 @@ Examples:
         console.log(taskToMarkdown(task));
     }
     else {
-        displayTaskFull(task, "📋");
+        displayTaskFull(task, "📋", { status: { local: true } });
     }
 }
 show().catch(console.error);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "team-toon-tack",
-	"version": "3.10.3",
+	"version": "3.11.0",
 	"description": "Linear & Trello task sync & management CLI with TOON format",
 	"type": "module",
 	"bin": {

package/skills/managing-linear-tasks/SKILL.md

@@ -58,6 +58,8 @@ ttt status MP-624 --set +1  # Advance status
 ttt comment MP-624 -m "msg" # Add comment to issue
 ttt comment -m "msg"        # Comment on current task
 ttt done -m "summary"       # Complete with message
+ttt done MP-624 --commit <sha> [--repo <path>]  # Close a ticket with an earlier commit
+ttt done MP-624 --from-remote  # Complete a Todo ticket without claiming it first
 ```
 
 ## Prerequisites