td-ai-tools 1.1.2 → 1.1.4

package/bin/cli.js

@@ -238,6 +238,18 @@ function buildDeleteMenu() {
   return [...skills, ...agents];
 }
 
+function buildUpdateMenu() {
+  const availableSkills = new Set(getAvailable(SKILLS_DIR));
+  const availableAgents = new Set(getAvailable(AGENTS_DIR));
+  const skills = getInstalled('skills')
+    .filter(name => availableSkills.has(name))
+    .map(name => ({ type: 'skill', name }));
+  const agents = getInstalled('agents')
+    .filter(name => availableAgents.has(name))
+    .map(name => ({ type: 'agent', name }));
+  return [...skills, ...agents];
+}
+
 function toGroupOptions(menu, { hintForInstalled = false } = {}) {
   const skillItems = menu.filter(i => i.type === 'skill').map(i => {
     const hint = hintForInstalled ? '' : getSkillHint(i.name);
@@ -275,9 +287,11 @@ function deleteItems(items) {
 }
 
 async function interactiveInstall(mode = 'install') {
-  const menu = buildMenu();
+  const menu = mode === 'update' ? buildUpdateMenu() : buildMenu();
   if (menu.length === 0) {
-    status('info', 'No skills or agent packs available.');
+    status('info', mode === 'update'
+      ? 'No installed skills or agent packs match the catalog.'
+      : 'No skills or agent packs available.');
     return;
   }
   if (!IS_TTY) {
@@ -369,6 +383,26 @@ function resolveNames(names) {
   return items;
 }
 
+function resolveUpdateNames(names) {
+  const availableSkills = new Set(getAvailable(SKILLS_DIR));
+  const availableAgents = new Set(getAvailable(AGENTS_DIR));
+  const installedSkills = getInstalled('skills');
+  const installedAgents = getInstalled('agents');
+  const items = [];
+  for (const name of names) {
+    if (installedSkills.includes(name) && availableSkills.has(name)) {
+      items.push({ type: 'skill', name });
+    } else if (installedAgents.includes(name) && availableAgents.has(name)) {
+      items.push({ type: 'agent', name });
+    } else if (!installedSkills.includes(name) && !installedAgents.includes(name)) {
+      status('error', `"${name}" is not installed.`);
+    } else {
+      status('error', `"${name}" is installed but not in the catalog.`);
+    }
+  }
+  return items;
+}
+
 function resolveDeleteNames(names) {
   const installedSkills = getInstalled('skills');
   const installedAgents = getInstalled('agents');
@@ -391,9 +425,9 @@ const HELP_TEXT = `Usage:
   npx td-ai-tools install             Interactive install
   npx td-ai-tools install --all       Install everything
   npx td-ai-tools install <name...>   Install specific skills or agent packs
-  npx td-ai-tools update              Interactive update (replaces existing items)
-  npx td-ai-tools update --all        Update everything
-  npx td-ai-tools update <name...>    Update specific skills or agent packs
+  npx td-ai-tools update              Interactive update (installed items in the catalog)
+  npx td-ai-tools update --all        Update all installed items found in the catalog
+  npx td-ai-tools update <name...>    Update specific installed skills or agent packs
   npx td-ai-tools delete              Interactive delete
   npx td-ai-tools delete --all        Delete everything
   npx td-ai-tools delete <name...>    Delete specific skills or agent packs
@@ -450,9 +484,14 @@ async function main() {
       return;
     }
     if (rest[0] === '--all') {
-      installItems(buildMenu(), { replaceExisting: true });
+      const menu = buildUpdateMenu();
+      if (menu.length === 0) {
+        status('info', 'No installed skills or agent packs match the catalog.');
+        return;
+      }
+      installItems(menu, { replaceExisting: true });
     } else {
-      installItems(resolveNames(rest), { replaceExisting: true });
+      installItems(resolveUpdateNames(rest), { replaceExisting: true });
     }
     return;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "td-ai-tools",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "Install agent skills and packs into your project",
   "type": "module",
   "scripts": {

package/skills/README.md

@@ -1,6 +1,7 @@
 # skills
 
 ## Available Skills
+- `barrage`: Convert a group of Basecamp todos or cards into a td-barrage queue.json task file.
 - `cache-reset`: Clear and warm Laravel and Statamic caches after content/template changes.
 - `horizon-component-migration`: Bundle Horizon components and recursive dependencies into a migration package for another theme.
 - `pr-solver`: Resolve unresolved GitHub PR review threads with GraphQL-driven workflow.

package/skills/barrage/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: barrage
+description: |
+  Convert a group of Basecamp todos or cards into a td-barrage queue.json task
+  file. Fetches the items via the Basecamp CLI, maps each title -> task id and
+  description -> prompt, and writes queue.json into this skill's directory. Use
+  when the user wants to turn Basecamp work into a barrage queue, build a
+  td-barrage queue from Basecamp, or run a todolist/card table through td-barrage.
+invocable: true
+argument-hint: "[basecamp todolist/card-table/column URL] [--timeout-mins N]"
+---
+
+# /barrage — Basecamp → td-barrage queue builder
+
+Turns a user-specified group of Basecamp todos or cards into a `queue.json` in the
+format consumed by **td-barrage**, a batch task runner (see
+[Output: the td-barrage queue.json format](#output-the-td-barrage-queuejson-format)
+below for the full schema — this skill emits that format directly and needs no
+other repo installed).
+
+## Input: the expected Basecamp item shape
+
+This skill is designed for Basecamp items whose **titles carry a trailing `[Nh]`
+estimate suffix** — e.g. `Build the checkout page [2h]` or `Fix nav [1.5h]`. That
+convention comes from an estimation workflow (the **td-augury** generator produces
+titles in exactly this shape), but nothing here requires that tool: any Basecamp
+todo or card works. Titles *without* a suffix are used verbatim; titles *with* one
+have it stripped from the task id by default (see `--keep-estimate`).
+
+Concretely, each item is read from the Basecamp CLI's JSON output, which exposes:
+
+- `title` — the display title (todos and cards)
+- `content` — for todos this equals the title; for cards it holds the card body (HTML)
+- `description` — the long-form body when present (preferred for the prompt)
+
+## What it produces
+
+Each Basecamp item becomes one td-barrage task:
+
+| td-barrage field | Source | Notes |
+|------------------|--------|-------|
+| `id`        | item **title** | trailing `[Nh]` estimate suffix stripped; deduped if needed |
+| `prompt`    | item **description** | HTML flattened to plain text |
+| `success`   | constant | always `{ "strategy": "default" }` |
+| `timeoutMs` | constant | `35` minutes → `2100000` ms, unless the user specifies otherwise |
+| `maxAttempts` | constant | `2` |
+
+> The user may refer to these as `barrage_id`, `success_criteria`, `timeout`, and
+> `max_attempts`. The actual td-barrage schema uses `id`, `success.strategy`,
+> `timeoutMs` (**milliseconds**), and `maxAttempts` — this skill emits the real
+> field names (documented in full below).
+
+The file is written to **this skill's directory** as `queue.json`
+(`build_queue.py` resolves that path from its own location, so it lands next to the
+script regardless of which skills copy is invoked).
+
+## Workflow
+
+### 1. Determine the group and item type
+
+Ask the user (if not already clear) for the Basecamp group to convert and whether
+it is **todos** or **cards**. A "group" is normally one of:
+
+- a **todolist** URL  → its todos
+- a **card table** URL → all its cards
+- a **column** URL     → the cards in that column
+- a whole **project**  → all todos or all cards in it
+
+### 2. Resolve IDs from the URL
+
+Always parse a URL first to extract the project and recording IDs:
+
+```bash
+basecamp url parse "<url>" --json
+```
+
+This returns `project_id`, `type`, and `recording_id`.
+
+### 3. Fetch the items as JSON
+
+Use the matching list command. **Always pass `--json`.**
+
+```bash
+# Todos in a specific todolist
+basecamp todos list --list <todolist_id> --in <project_id> --json > items.json
+
+# All todos in a project
+basecamp todos list --in <project_id> --json > items.json
+
+# Cards in a specific card table (required flag if a project has >1 table)
+basecamp cards list --card-table <table_id> --in <project_id> --json > items.json
+
+# Cards in a single column
+basecamp cards list --column <column_id> --in <project_id> --json > items.json
+```
+
+The CLI returns an envelope `{ ok, data, ... }`; the converter reads `data`
+automatically (it also accepts a bare array or `--agent` raw output). By default
+all (non-completed) items are returned — add `--all` for large lists, or filter
+(e.g. `--status`) if the user only wants some.
+
+### 4. Convert to queue.json
+
+Pipe the fetched JSON into the converter (or pass `--input`):
+
+```bash
+python3 "$SKILL_DIR/scripts/build_queue.py" --input items.json
+# or
+basecamp todos list --list <id> --in <proj> --json \
+  | python3 "$SKILL_DIR/scripts/build_queue.py"
+```
+
+`$SKILL_DIR` is the directory containing this `SKILL.md`. The script writes
+`queue.json` into that directory and prints a summary plus any per-item warnings
+(skipped items with no description, deduped ids, etc.).
+
+Options:
+
+- `--timeout-mins N` — override the 35-minute default (the script converts to ms).
+- `--max-attempts N` — override the default of 2.
+- `--keep-estimate` — keep the `[Nh]` suffix in the id instead of stripping it.
+- `--output PATH` — write somewhere other than `<skill>/queue.json`.
+
+### 5. Report
+
+Tell the user where `queue.json` was written, how many tasks it contains, and
+surface any warnings the script printed (skipped or renamed items).
+
+## Output: the td-barrage queue.json format
+
+td-barrage validates the file with a Zod schema. This skill emits the minimal
+valid subset; the runner fills in the rest with the defaults shown below. The full
+task schema is:
+
+```jsonc
+{
+  "tasks": [
+    {
+      "id": "string",              // required, non-empty; must be unique across the file
+      "prompt": "string",          // required, non-empty
+      "dependsOn": ["string"],     // optional, default []  (ids of prerequisite tasks)
+      "maxAttempts": 2,            // optional, integer >= 1
+      "timeoutMs": 2100000,        // optional, positive integer (MILLISECONDS)
+      "success": {                 // optional, default { "strategy": "default" }
+        "strategy": "default"      //   one of: "default" | "file_exists" | "result_json"
+        // "file_exists" also needs: "path": "string"
+        // "result_json" also needs: "path": "string"
+      },
+      "cwd": "string",             // optional, working directory for the task
+      "resultPath": "string"       // optional, where the task writes its result
+    }
+  ]
+}
+```
+
+The top-level value may be either `{ "tasks": [...] }` (what this skill writes) or a
+bare `[...]` array of tasks. Runtime-managed fields (`status`, `attempts`, `error`,
+`startedAt`, `finishedAt`, `recoveryNotes`) are set by td-barrage and should not be
+authored here.
+
+Validation rules enforced by the runner:
+
+- **Unique ids** — duplicate `id` values are rejected (`Duplicate task id`). The
+  converter pre-empts this by renaming collisions to `"<title> (2)"`.
+- **No self-dependency** — a task cannot list its own id in `dependsOn`.
+- **No dangling dependencies** — every id in `dependsOn` must match another task's id.
+
+## Notes & caveats
+
+- **Empty descriptions are skipped.** td-barrage requires a non-empty `prompt`, so
+  items with no description cannot become tasks. The script warns for each one —
+  relay this so the user can add descriptions in Basecamp and re-run if needed.
+- **Duplicate titles** would make td-barrage reject the whole file
+  (`Duplicate task id`). The script renames collisions to `"<title> (2)"` and
+  warns; prefer fixing the source titles when that happens.
+- **No dependencies are emitted.** Every task is independent (`dependsOn` defaults
+  to `[]`). If the user wants an execution order, edit `queue.json` afterward to add
+  `dependsOn` arrays referencing other task ids.
+- The Basecamp CLI is already authenticated; verify with
+  `basecamp auth status --json` if a fetch fails.

package/skills/barrage/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Barrage"
+  short_description: "Build a td-barrage queue.json from Basecamp todos or cards"
+  default_prompt: "Use $barrage to convert a group of Basecamp todos or cards into a td-barrage queue.json task file."

package/skills/barrage/scripts/build_queue.py

@@ -0,0 +1,276 @@
+#!/usr/bin/env python3
+"""Convert Basecamp todos/cards into a td-barrage queue.json.
+
+Reads the JSON emitted by the Basecamp CLI (`basecamp todos list ... --json`,
+`basecamp cards list ... --json`, or their `--agent` raw form) and writes a
+td-barrage task file. The only runtime dependency is the Basecamp CLI that
+produced the input; the queue.json format it writes is documented in ../SKILL.md
+("Output: the td-barrage queue.json format") so no other repo need be installed.
+
+Field mapping (see ../SKILL.md):
+  - id        <- the item title, with any trailing `[Nh]` estimate suffix stripped
+  - prompt    <- the item description (HTML stripped to plain text)
+  - success   <- {"strategy": "default"} on every item
+  - timeoutMs <- --timeout-mins * 60 * 1000   (default 35 minutes)
+  - maxAttempts <- --max-attempts             (default 2)
+
+The Basecamp CLI normalizes both todos and cards to expose `title`, `content`,
+and `description`. For todos `content == title`; for cards the body lives in
+`content` (HTML). We therefore prefer `description` for the prompt and only fall
+back to `content` when it differs from the title.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from html.parser import HTMLParser
+from pathlib import Path
+from typing import Any
+
+# Skill root is the parent of this script's directory (scripts/ -> <skill>/).
+SKILL_DIR = Path(__file__).resolve().parent.parent
+
+# Matches a trailing estimate suffix like " [2h]" or " [1.5h]" (case-insensitive).
+# Basecamp titles produced by an estimation workflow carry this suffix (the
+# td-augury generator appends "[<hours>h]"); we strip it from the task id so the
+# id reads as a plain title. Titles without a suffix are unaffected.
+ESTIMATE_SUFFIX_RE = re.compile(r"\s*\[\d+(?:\.\d+)?h\]\s*$", re.IGNORECASE)
+
+# Block-level tags whose close (or self-close) should become a line break when
+# flattening an HTML card body to plain text.
+_BLOCK_TAGS = {
+    "p", "div", "br", "li", "ul", "ol", "tr", "h1", "h2", "h3", "h4", "h5", "h6",
+    "blockquote", "pre", "section", "article", "header", "footer",
+}
+
+
+class _TextExtractor(HTMLParser):
+    """Collapse an HTML fragment to readable plain text, preserving line breaks."""
+
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self._parts: list[str] = []
+
+    def handle_data(self, data: str) -> None:
+        self._parts.append(data)
+
+    def handle_starttag(self, tag: str, attrs: Any) -> None:
+        if tag == "br":
+            self._parts.append("\n")
+
+    def handle_endtag(self, tag: str) -> None:
+        if tag in _BLOCK_TAGS:
+            self._parts.append("\n")
+
+    def text(self) -> str:
+        return "".join(self._parts)
+
+
+def html_to_text(value: str) -> str:
+    """Strip HTML tags/entities and normalize whitespace.
+
+    Plain-text input passes through unchanged apart from whitespace cleanup, so
+    it is safe to run on both todo descriptions (plain) and card bodies (HTML).
+    """
+    parser = _TextExtractor()
+    parser.feed(value)
+    text = parser.text()
+    # Collapse runs of blank lines and trim trailing spaces on each line.
+    lines = [line.strip() for line in text.splitlines()]
+    out: list[str] = []
+    blank = False
+    for line in lines:
+        if line:
+            out.append(line)
+            blank = False
+        elif not blank and out:
+            out.append("")
+            blank = True
+    return "\n".join(out).strip()
+
+
+def first_nonempty(record: dict[str, Any], keys: tuple[str, ...]) -> str:
+    for key in keys:
+        value = record.get(key)
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+    return ""
+
+
+def extract_title(record: dict[str, Any]) -> str:
+    """The display title (before estimate-suffix stripping)."""
+    return first_nonempty(record, ("title", "content", "name"))
+
+
+def extract_description(record: dict[str, Any], title: str) -> str:
+    """The prompt body, HTML-flattened.
+
+    Prefer the dedicated `description` field. Fall back to `content` only when it
+    differs from the title, so a todo (where content == title) does not get its
+    own title echoed back as the prompt.
+    """
+    desc = first_nonempty(record, ("description",))
+    if not desc:
+        content = first_nonempty(record, ("content",))
+        if content and content != title:
+            desc = content
+    return html_to_text(desc)
+
+
+def make_id(title: str, keep_estimate: bool) -> str:
+    if keep_estimate:
+        return title
+    return ESTIMATE_SUFFIX_RE.sub("", title).strip()
+
+
+def unwrap_items(payload: Any) -> list[dict[str, Any]]:
+    """Accept the CLI envelope, the --agent raw form, a bare array, or one item."""
+    if isinstance(payload, dict):
+        if "data" in payload:  # standard --json envelope: {ok, data, ...}
+            payload = payload["data"]
+        elif "tasks" in payload:  # already a queue file
+            payload = payload["tasks"]
+        else:  # a single recording object
+            return [payload]
+    if isinstance(payload, list):
+        return [item for item in payload if isinstance(item, dict)]
+    raise SystemExit("Unrecognized input JSON: expected an envelope, array, or object.")
+
+
+def build_tasks(
+    items: list[dict[str, Any]],
+    *,
+    timeout_ms: int,
+    max_attempts: int,
+    keep_estimate: bool,
+) -> tuple[list[dict[str, Any]], list[str]]:
+    tasks: list[dict[str, Any]] = []
+    warnings: list[str] = []
+    seen: dict[str, int] = {}
+
+    for index, record in enumerate(items):
+        title = extract_title(record)
+        if not title:
+            warnings.append(f"Item #{index} (id={record.get('id')}): no title; skipped.")
+            continue
+
+        prompt = extract_description(record, title)
+        if not prompt:
+            warnings.append(
+                f"Item #{index} {title!r}: empty description; skipped "
+                "(td-barrage requires a non-empty prompt)."
+            )
+            continue
+
+        task_id = make_id(title, keep_estimate)
+        if not task_id:
+            task_id = title  # estimate-only title edge case
+
+        # De-duplicate ids so the file stays loadable (td-barrage rejects dupes).
+        if task_id in seen:
+            seen[task_id] += 1
+            deduped = f"{task_id} ({seen[task_id]})"
+            warnings.append(f"Duplicate id {task_id!r}; renamed to {deduped!r}.")
+            task_id = deduped
+        else:
+            seen[task_id] = 1
+
+        tasks.append(
+            {
+                "id": task_id,
+                "prompt": prompt,
+                "timeoutMs": timeout_ms,
+                "maxAttempts": max_attempts,
+                "success": {"strategy": "default"},
+            }
+        )
+
+    return tasks, warnings
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--input",
+        type=Path,
+        help="Path to the Basecamp CLI JSON. Reads stdin if omitted.",
+    )
+    parser.add_argument(
+        "--output",
+        type=Path,
+        default=SKILL_DIR / "queue.json",
+        help="Where to write the queue file (default: <skill>/queue.json).",
+    )
+    parser.add_argument(
+        "--timeout-mins",
+        type=float,
+        default=35.0,
+        help="Per-task timeout in minutes (default: 35).",
+    )
+    parser.add_argument(
+        "--max-attempts",
+        type=int,
+        default=2,
+        help="Per-task max attempts (default: 2).",
+    )
+    parser.add_argument(
+        "--keep-estimate",
+        action="store_true",
+        help="Keep the trailing [Nh] estimate suffix in the id (stripped by default).",
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+
+    raw = args.input.read_text() if args.input else sys.stdin.read()
+    if not raw.strip():
+        print("No input JSON provided.", file=sys.stderr)
+        return 1
+
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        print(f"Failed to parse input JSON: {exc}", file=sys.stderr)
+        return 1
+
+    if isinstance(payload, dict) and payload.get("ok") is False:
+        print(f"Basecamp CLI returned an error: {payload.get('error')}", file=sys.stderr)
+        return 1
+
+    items = unwrap_items(payload)
+    if not items:
+        print("Input contained no items.", file=sys.stderr)
+        return 1
+
+    timeout_ms = int(round(args.timeout_mins * 60 * 1000))
+    tasks, warnings = build_tasks(
+        items,
+        timeout_ms=timeout_ms,
+        max_attempts=args.max_attempts,
+        keep_estimate=args.keep_estimate,
+    )
+
+    for warning in warnings:
+        print(f"warning: {warning}", file=sys.stderr)
+
+    if not tasks:
+        print("No usable tasks produced (every item lacked a title or description).", file=sys.stderr)
+        return 1
+
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    args.output.write_text(json.dumps({"tasks": tasks}, indent=2) + "\n")
+
+    print(
+        f"Wrote {len(tasks)} task(s) to {args.output} "
+        f"(timeout={args.timeout_mins}m / {timeout_ms}ms, maxAttempts={args.max_attempts})."
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/barrage/tests/test_build_queue.py

@@ -0,0 +1,135 @@
+"""Tests for build_queue.py — verifies the Basecamp -> td-barrage mapping.
+
+Run: python3 -m pytest .agents/skills/barrage/tests/  (or just `python3 test_build_queue.py`).
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import sys
+from pathlib import Path
+
+_SCRIPT = Path(__file__).resolve().parent.parent / "scripts" / "build_queue.py"
+_spec = importlib.util.spec_from_file_location("build_queue", _SCRIPT)
+assert _spec and _spec.loader
+bq = importlib.util.module_from_spec(_spec)
+_spec.loader.exec_module(bq)
+
+
+# Shapes mirror what the Basecamp CLI actually returns (verified against the live
+# CLI): todos expose title == content plus a separate description; cards carry the
+# body in an HTML `content` field.
+TODO = {
+    "id": 1,
+    "title": "Design — Search [2h]",
+    "content": "Design — Search [2h]",
+    "description": "Build the search UI and wire it to the API.",
+}
+CARD = {
+    "id": 2,
+    "title": "Implement parser [1.5h]",
+    "content": "<div>Parse the file.</div><div>Emit JSON.</div>",
+    "description": "",
+}
+
+
+def build(items, **kw):
+    defaults = {"timeout_ms": 2_100_000, "max_attempts": 2, "keep_estimate": False}
+    defaults.update(kw)
+    return bq.build_tasks(items, **defaults)
+
+
+def test_todo_mapping():
+    tasks, warnings = build([TODO])
+    assert warnings == []
+    assert tasks == [
+        {
+            "id": "Design — Search",  # [2h] stripped
+            "prompt": "Build the search UI and wire it to the API.",
+            "timeoutMs": 2_100_000,
+            "maxAttempts": 2,
+            "success": {"strategy": "default"},
+        }
+    ]
+
+
+def test_card_html_body_becomes_prompt():
+    tasks, _ = build([CARD])
+    assert tasks[0]["id"] == "Implement parser"
+    # HTML flattened, block tags -> line breaks.
+    assert tasks[0]["prompt"] == "Parse the file.\nEmit JSON."
+
+
+def test_default_success_timeout_attempts():
+    tasks, _ = build([TODO], timeout_ms=999, max_attempts=5)
+    assert tasks[0]["success"] == {"strategy": "default"}
+    assert tasks[0]["timeoutMs"] == 999
+    assert tasks[0]["maxAttempts"] == 5
+
+
+def test_keep_estimate_suffix():
+    tasks, _ = build([TODO], keep_estimate=True)
+    assert tasks[0]["id"] == "Design — Search [2h]"
+
+
+def test_empty_description_is_skipped_with_warning():
+    item = {"id": 9, "title": "No body", "content": "No body", "description": ""}
+    tasks, warnings = build([item])
+    assert tasks == []
+    assert any("empty description" in w for w in warnings)
+
+
+def test_todo_title_not_echoed_as_prompt():
+    # content == title and no description -> must NOT use title as the prompt.
+    item = {"id": 9, "title": "Echo", "content": "Echo", "description": ""}
+    tasks, _ = build([item])
+    assert tasks == []
+
+
+def test_duplicate_ids_are_renamed():
+    a = {"id": 1, "title": "Same", "content": "Same", "description": "first"}
+    b = {"id": 2, "title": "Same", "content": "Same", "description": "second"}
+    tasks, warnings = build([a, b])
+    ids = [t["id"] for t in tasks]
+    assert ids == ["Same", "Same (2)"]
+    assert any("Duplicate" in w for w in warnings)
+
+
+def test_unwrap_envelope_array_and_object():
+    assert bq.unwrap_items({"ok": True, "data": [TODO]}) == [TODO]
+    assert bq.unwrap_items([TODO]) == [TODO]
+    assert bq.unwrap_items(TODO) == [TODO]
+    assert bq.unwrap_items({"tasks": [TODO]}) == [TODO]
+
+
+def test_end_to_end_via_main(tmp_path):
+    src = tmp_path / "items.json"
+    src.write_text(json.dumps({"ok": True, "data": [TODO, CARD]}))
+    out = tmp_path / "queue.json"
+    rc = bq.main(["--input", str(src), "--output", str(out)])
+    assert rc == 0
+    data = json.loads(out.read_text())
+    assert [t["id"] for t in data["tasks"]] == ["Design — Search", "Implement parser"]
+    assert all(t["success"] == {"strategy": "default"} for t in data["tasks"])
+    assert all(t["timeoutMs"] == 2_100_000 for t in data["tasks"])
+
+
+if __name__ == "__main__":
+    failures = 0
+    for name, fn in sorted(globals().items()):
+        if name.startswith("test_") and callable(fn):
+            try:
+                # crude tmp_path for direct (non-pytest) runs
+                if "tmp_path" in fn.__code__.co_varnames[: fn.__code__.co_argcount]:
+                    import tempfile
+
+                    with tempfile.TemporaryDirectory() as d:
+                        fn(Path(d))
+                else:
+                    fn()
+                print(f"ok   {name}")
+            except AssertionError as exc:
+                failures += 1
+                print(f"FAIL {name}: {exc}")
+    sys.exit(1 if failures else 0)