@synity/bitrix-skills 1.3.0

package/src/features/bx-task/assets/references/init-templates/npm-package.md

@@ -0,0 +1,40 @@
+[B]{{PACKAGE_NAME}}[/B] — {{ONE_LINE_VALUE_PROP}}
+
+[B]Install[/B]
+[code]
+{{INSTALL_COMMANDS}}
+[/code]
+
+[B]Commands[/B]
+[code]
+{{KEY_COMMANDS_OR_USAGE}}
+[/code]
+
+[B]Architecture[/B]
+[code]
+{{ASCII_DIAGRAM}}
+[/code]
+
+[B]Feature Matrix[/B]
+[table]
+[tr][th]Feature[/th][th]Target[/th][th]Trigger[/th][th]Lifecycle[/th][/tr]
+{{FEATURE_MATRIX_ROWS}}
+[/table]
+
+[B]Phase Timeline[/B]
+{{PHASE_TIMELINE}}
+
+[B]Open Issues[/B]
+{{OPEN_ISSUES}}
+
+[B]Success Criteria[/B]
+{{SUCCESS_CRITERIA}}
+
+[B]Liên kết[/B]
+• Repo: [URL={{REPO_URL}}]{{REPO_SHORT}}[/URL]
+• npm: [URL=https://www.npmjs.com/package/{{PACKAGE_NAME}}]{{PACKAGE_NAME}}[/URL]
+• Plan dir: {{PLAN_DIR}}
+• Active phase: {{ACTIVE_PHASE_PATH}}
+• Docs: docs/project-overview-pdr.md, docs/system-architecture.md, docs/codebase-summary.md
+• README: README.md
+• CHANGELOG: CHANGELOG.md

package/src/features/bx-task/assets/references/init-templates/web-app.md

@@ -0,0 +1,46 @@
+[B]{{PACKAGE_NAME}}[/B] — {{ONE_LINE_VALUE_PROP}}
+
+[B]Dev / Build / Deploy[/B]
+[code]
+{{INSTALL_COMMANDS}}
+[/code]
+
+[B]Routes / Pages[/B]
+[table]
+[tr][th]Path[/th][th]Component[/th][th]Purpose[/th][/tr]
+{{ROUTES_ROWS}}
+[/table]
+
+[B]Architecture[/B]
+[code]
+{{ASCII_DIAGRAM}}
+[/code]
+
+[B]Components & State[/B]
+[table]
+[tr][th]Module[/th][th]Role[/th][/tr]
+{{FEATURE_MATRIX_ROWS}}
+[/table]
+
+[B]API Endpoints[/B]
+{{API_ENDPOINTS_OR_NONE}}
+
+[B]Deploy Targets[/B]
+{{DEPLOY_TARGETS}}
+
+[B]Phase Timeline[/B]
+{{PHASE_TIMELINE}}
+
+[B]Open Issues[/B]
+{{OPEN_ISSUES}}
+
+[B]Success Criteria[/B]
+{{SUCCESS_CRITERIA}}
+
+[B]Liên kết[/B]
+• Repo: [URL={{REPO_URL}}]{{REPO_SHORT}}[/URL]
+• Live: [URL={{LIVE_URL}}]{{LIVE_URL_SHORT}}[/URL]
+• Plan dir: {{PLAN_DIR}}
+• Active phase: {{ACTIVE_PHASE_PATH}}
+• Docs: docs/project-overview-pdr.md, docs/system-architecture.md, docs/codebase-summary.md
+• README: README.md

package/src/features/bx-task/assets/references/init.md

@@ -0,0 +1,107 @@
+# /bx:task init — Initialize TASK_ID in CLAUDE.md
+
+Detect or insert a `TASK_ID` block into the nearest `CLAUDE.md`. No Bitrix API calls — filesystem only.
+
+## When to use
+
+- Starting a new AI session in a project that hasn't set `TASK_ID` yet
+- Switching to a different Bitrix task mid-project
+- Setting up a new feature branch with its own task context
+
+## Args
+
+```
+/bx:task init [--task-id N]
+```
+
+- `--task-id N` — skip interactive prompt, use this value directly
+
+## Algorithm
+
+### Step 1 — Locate CLAUDE.md
+
+Walk up from `$PWD` looking for `CLAUDE.md`:
+
+```bash
+dir="$PWD"
+CLAUDE_MD=""
+while [[ "$dir" != "/" ]]; do
+  if [[ -f "$dir/CLAUDE.md" ]]; then
+    CLAUDE_MD="$dir/CLAUDE.md"
+    break
+  fi
+  dir="$(dirname "$dir")"
+done
+```
+
+If not found → will create `$PWD/CLAUDE.md`.
+
+### Step 2 — Check existing TASK_ID
+
+```bash
+EXISTING_ID=$(grep -m1 '^TASK_ID:' "${CLAUDE_MD:-}" 2>/dev/null | awk '{print $2}')
+```
+
+If `EXISTING_ID` found:
+- Show: `Current TASK_ID: {EXISTING_ID} in {CLAUDE_MD}`
+- Ask via `AskUserQuestion`: "TASK_ID đã tồn tại. Bạn muốn làm gì?"
+  - "Giữ nguyên #{EXISTING_ID}" → exit 0
+  - "Đổi sang task khác" → continue to Step 3
+  - "Cancel" → exit 0
+
+### Step 3 — Get TASK_ID value
+
+If `--task-id N` was passed → `NEW_ID=N`, skip prompt.
+
+Otherwise use `AskUserQuestion`:
+- question: "Nhập TASK_ID (số) cho project này:"
+- options: leave as free-text (user types the number)
+
+Validate: must be a positive integer. If invalid → error + re-prompt (max 3 attempts).
+
+### Step 4 — Insert or update TASK_ID block
+
+**If CLAUDE.md exists and has existing `## Bitrix Task` section:**
+
+Find the section and update/insert `TASK_ID: N` line:
+
+```bash
+# Check if ## Bitrix Task section exists
+if grep -q '^## Bitrix Task' "$CLAUDE_MD"; then
+  # Update existing TASK_ID line if present
+  if grep -q '^TASK_ID:' "$CLAUDE_MD"; then
+    sed -i '' "s/^TASK_ID:.*/TASK_ID: ${NEW_ID}/" "$CLAUDE_MD"
+  else
+    # Insert TASK_ID after "## Bitrix Task" line
+    sed -i '' "/^## Bitrix Task/a\\
+TASK_ID: ${NEW_ID}" "$CLAUDE_MD"
+  fi
+else
+  # Append full block at end of file
+  printf '\n## Bitrix Task\nTASK_ID: %s\n' "$NEW_ID" >> "$CLAUDE_MD"
+fi
+```
+
+**If CLAUDE.md does not exist:**
+
+```bash
+printf '## Bitrix Task\nTASK_ID: %s\n' "$NEW_ID" > "$PWD/CLAUDE.md"
+CLAUDE_MD="$PWD/CLAUDE.md"
+```
+
+### Step 5 — Confirm result
+
+Print:
+```
+✓ TASK_ID set to #{NEW_ID} in {CLAUDE_MD}
+  Hooks will now sync AI activity to: https://{portal}/workgroups/group/{GROUP_ID}/tasks/task/view/{NEW_ID}/
+```
+
+If `BITRIX_WEBHOOK_URL` is set, extract portal domain from the URL for the confirmation link.
+Otherwise: `✓ TASK_ID: {NEW_ID} saved to {CLAUDE_MD}`
+
+## Error handling
+
+- Invalid TASK_ID (non-integer) → `ERROR: TASK_ID must be a positive integer.`
+- CLAUDE.md not writable → `ERROR: Cannot write to {path}. Check permissions.`
+- No CLAUDE.md found and CWD not a git repo → warn "No CLAUDE.md found and CWD is not a git root. Creating {PWD}/CLAUDE.md anyway." → proceed

package/src/features/bx-task/assets/references/roadmap.md

@@ -0,0 +1,93 @@
+# /bx:task roadmap — Manage Done/Doing/Plan checklist groups on main task
+
+Two actions:
+
+| Action | Effect |
+|--------|--------|
+| `add <group> <item>` | Append a new item to a group (Done/Doing/Plan) |
+| `move <item> <from> <to>` | Mark item complete in `<from>`, add (possibly checked) in `<to>` |
+
+`<group>` ∈ `done | doing | plan`. `<item>` = exact title text used during add/move.
+
+## Args
+
+```
+/bx:task roadmap add  <group> <item-title>
+/bx:task roadmap move <item-title> <from-group> <to-group>
+```
+
+Item title supports spaces (quote in shell or pass as-is from skill arg parser).
+
+## Prerequisite
+
+State must have all 3 `checklists.{done,doing,plan}.parentId` set. If missing → run
+`/bx:task bootstrap` first.
+
+## Algorithm — `add`
+
+```bash
+source ~/.claude/skills/bx-task/lib/bx-api.sh
+source ~/.claude/skills/bx-task/lib/bx-state.sh
+source ~/.claude/skills/bx-task/lib/bx-checklist.sh
+source ~/.claude/skills/bx-task/lib/bx-tasks.sh
+
+bx_preflight || exit 1
+MAIN_ID=$(bx_state_get "mainTaskId")
+PARENT=$(bx_state_get "checklists.${GROUP}.parentId")
+if [[ -z "$MAIN_ID" || -z "$PARENT" ]]; then
+  echo "⛔ State not bootstrapped, or unknown group '$GROUP'." >&2
+  echo "   Valid groups: done, doing, plan." >&2
+  exit 1
+fi
+
+# Confirm before POST (AskUserQuestion: "Add '$ITEM' to $GROUP on task #$MAIN_ID?")
+
+NEW_ID=$(bx_checklist_add "$MAIN_ID" "$GROUP" "$ITEM")
+[[ "$GROUP" == "done" ]] && bx_checklist_toggle "$MAIN_ID" "$NEW_ID" "Y"
+
+echo "✓ Added '$ITEM' to $GROUP (item #$NEW_ID)"
+```
+
+## Algorithm — `move`
+
+```bash
+bx_preflight || exit 1
+MAIN_ID=$(bx_state_get "mainTaskId")
+
+FROM_PID=$(bx_state_get "checklists.${FROM}.parentId")
+TO_PID=$(bx_state_get "checklists.${TO}.parentId")
+if [[ -z "$MAIN_ID" || -z "$FROM_PID" || -z "$TO_PID" ]]; then
+  echo "⛔ State not bootstrapped, or unknown group." >&2
+  exit 1
+fi
+
+# Confirm before POST
+
+NEW_ID=$(bx_checklist_move "$MAIN_ID" "$ITEM" "$FROM" "$TO")
+if [[ -z "$NEW_ID" ]]; then
+  echo "ERROR: move failed — item '$ITEM' may not exist in $FROM" >&2
+  exit 1
+fi
+
+echo "✓ Moved '$ITEM' from $FROM → $TO (new item #$NEW_ID)"
+```
+
+## Behavior notes
+
+- **`add` to `done`** auto-toggles complete (`IS_COMPLETE=Y`).
+- **`move`** preserves history by keeping the source item (marked complete) and creating a
+  new item in destination. This matches Bitrix UX (struck-through old + fresh new).
+- **Title match in `move`** is exact (case-sensitive). If item title was renamed since add,
+  use `add` in target group + manually toggle source.
+
+## Errors / UX
+
+- Unknown group → exit 1 with valid list
+- Item not found in source for `move` → exit 1, suggest `add` instead
+- No state → exit 1, hint `bootstrap`
+
+## What NOT to do
+
+- ❌ Use `move` to undo a completion (instead: `bx_checklist_toggle <main> <itemId> N`)
+- ❌ Add duplicate items to the same group (Bitrix allows it, but UX gets confusing)
+- ❌ Skip the confirmation step (every POST goes through `AskUserQuestion`)

package/src/features/bx-task/assets/references/summary.md

@@ -0,0 +1,269 @@
+# /bx:task summary — Curated KB Result
+
+Post a curated knowledge-base summary as a Bitrix Task Result entry (visible in task UI tab "Kết quả" / "Result"). Designed for moments worth pinning: releases, discoveries, bug post-mortems, ADRs, failed experiments.
+
+## When to use
+
+- After shipping a release → `summary release`
+- After investigating a bug → `summary bug-postmortem`
+- After making an architecture decision → `summary adr`
+- After learning something non-obvious → `summary discovery`
+- After confirming a hypothesis is wrong → `summary failed-experiment`
+
+If the user just wants to leave a chat note, the existing `bitrix-task-sync` hook auto-posts comments. This skill is for **persistent, structured KB entries** only.
+
+## Args
+
+```
+/bx:task summary [type] [--task-id N]
+```
+
+| Arg | Required | Notes |
+|-----|----------|-------|
+| `type` | optional | One of: `release`, `discovery`, `bug-postmortem`, `adr`, `failed-experiment`. Omit → picker. |
+| `--task-id N` | optional | Override CLAUDE.md walk-up. Useful when running outside a Bitrix project or targeting a different task. |
+
+## Algorithm (Claude follows step by step)
+
+```
+1. Source helpers + pre-flight:
+     source ~/.claude/skills/bx-task/lib/bx-resolve-task.sh
+     source ~/.claude/skills/bx-task/lib/bx-api.sh
+     bx_preflight || abort
+
+2. Parse args:
+     - extract --task-id N if present, store in EXPLICIT_TASK_ID
+     - first positional = type (may be empty)
+
+3. Resolve TASK_ID:
+     TASK_ID=$(bx_resolve_task_id "$EXPLICIT_TASK_ID") || abort
+
+4. If type empty → AskUserQuestion picker (5 type options).
+   If type invalid → error: list valid types, exit 1.
+
+5. Look up the field list for the chosen type (table below).
+
+6. Collect each field via AskUserQuestion (one question per field).
+   Field labels in the table are the prompt wording.
+   Multi-line fields: ask user to write content as one paragraph; preserve newlines as-is.
+
+7. Render BB content by substituting collected values into the template
+   for that type (templates below).
+
+8. Show preview + confirm via AskUserQuestion:
+     Question: "Post this summary to Bitrix task #$TASK_ID?"
+     Preview field: raw BB code (KISS — exact text fidelity)
+     Options: [Confirm + Post (Recommended), Edit fields, Cancel]
+
+9. On Confirm → POST:
+     PAYLOAD=$(jq -n --argjson tid "$TASK_ID" --arg txt "$BB_CONTENT" \
+       '{fields:{taskId:$tid, text:$txt}}')
+     RESP=$(bx_call_v3 "tasks.task.result.add" "$PAYLOAD")
+     # Extract result.id via grep — DO NOT use jq on the full response.
+     # Bitrix v3 returns malformed JSON (literal newlines inside string values),
+     # which strict jq rejects. The id field appears early and is safe to grep.
+     RESULT_ID=$(echo "$RESP" | grep -oE '"id":[[:space:]]*[0-9]+' | head -1 | grep -oE '[0-9]+')
+     if [[ -n "$RESULT_ID" ]]; then
+       echo "✅ Posted result #${RESULT_ID} to task #${TASK_ID}"
+     else
+       echo "❌ POST failed: $RESP" >&2
+       exit 1
+     fi
+
+10. On Edit → loop back to step 6 (re-prompt fields, keep prior answers visible if AskUserQuestion supports defaults; otherwise re-ask).
+    On Cancel → exit 0 cleanly, no POST, no side effects.
+```
+
+**Important:**
+- Use `jq -n --arg txt "$BB_CONTENT"` for the REQUEST payload — NEVER string-concatenate user content into JSON. `jq --arg` handles quotes, newlines, and special chars (including `[/]`) safely.
+- Do NOT use `jq` to parse the RESPONSE. Bitrix v3 returns JSON with literal (unescaped) newlines inside the `text` string value, which strict jq rejects. Use `grep -oE '"id":[[:space:]]*[0-9]+'` to extract the result id robustly.
+
+## Type → Template (BB code)
+
+All templates below render in Bitrix UI as bold headings + plain text body. **No markdown**. Use literal `\n` line breaks (real newlines in the rendered string).
+
+### `release` 🚀
+
+Fields: `VERSION`, `HIGHLIGHTS` (multi-line), `BREAKING`, `MIGRATION`
+
+```
+🚀 [b]Release {VERSION}[/b]
+
+[b]Highlights:[/b]
+{HIGHLIGHTS}
+
+[b]Breaking changes:[/b]
+{BREAKING}
+
+[b]Migration:[/b]
+{MIGRATION}
+```
+
+### `discovery` 💡
+
+Fields: `TOPIC`, `INSIGHT`, `APPLICATION`, `SOURCE`
+
+```
+💡 [b]Discovery: {TOPIC}[/b]
+
+[b]Insight:[/b]
+{INSIGHT}
+
+[b]Application:[/b]
+{APPLICATION}
+
+[b]Source:[/b]
+{SOURCE}
+```
+
+### `bug-postmortem` 🪲
+
+Fields: `SYMPTOM`, `SYMPTOM_DETAIL`, `ROOT_CAUSE`, `FIX`, `PREVENTION`
+
+```
+🪲 [b]Bug post-mortem: {SYMPTOM}[/b]
+
+[b]Triệu chứng:[/b]
+{SYMPTOM_DETAIL}
+
+[b]Nguyên nhân:[/b]
+{ROOT_CAUSE}
+
+[b]Fix:[/b]
+{FIX}
+
+[b]Phòng ngừa:[/b]
+{PREVENTION}
+```
+
+### `adr` 📐
+
+Fields: `DECISION`, `CONTEXT`, `DECISION_DETAIL`, `CONSEQUENCES`, `STATUS`
+
+```
+📐 [b]ADR: {DECISION}[/b]
+
+[b]Context:[/b]
+{CONTEXT}
+
+[b]Decision:[/b]
+{DECISION_DETAIL}
+
+[b]Consequences:[/b]
+{CONSEQUENCES}
+
+[b]Status:[/b] {STATUS}
+```
+
+`STATUS` ∈ {`Proposed`, `Accepted`, `Deprecated`, `Superseded`}.
+
+### `failed-experiment` 🧪
+
+Fields: `HYPOTHESIS`, `HYPOTHESIS_DETAIL`, `RESULT`, `LEARNING`
+
+```
+🧪 [b]Failed experiment: {HYPOTHESIS}[/b]
+
+[b]Hypothesis:[/b]
+{HYPOTHESIS_DETAIL}
+
+[b]Result:[/b]
+{RESULT}
+
+[b]Learning:[/b]
+{LEARNING}
+```
+
+## Field-list quick reference
+
+| Type | Fields (prompt order) |
+|------|-----------------------|
+| `release` | VERSION, HIGHLIGHTS, BREAKING, MIGRATION |
+| `discovery` | TOPIC, INSIGHT, APPLICATION, SOURCE |
+| `bug-postmortem` | SYMPTOM, SYMPTOM_DETAIL, ROOT_CAUSE, FIX, PREVENTION |
+| `adr` | DECISION, CONTEXT, DECISION_DETAIL, CONSEQUENCES, STATUS |
+| `failed-experiment` | HYPOTHESIS, HYPOTHESIS_DETAIL, RESULT, LEARNING |
+
+## API payload shape
+
+```json
+{
+  "fields": {
+    "taskId": 2776,
+    "text": "🚀 [b]Release v0.0.1[/b]\n\n[b]Highlights:[/b]\n• ..."
+  }
+}
+```
+
+Endpoint: `tasks.task.result.add` on the v3 path (`/rest/api/<user>/<token>/`). `bx_call_v3` rewrites the URL automatically.
+
+Response shape (success):
+
+```json
+{
+  "result": {
+    "item": {
+      "id": 123,
+      "taskId": 2776,
+      "createdBy": 614,
+      "messageId": null,
+      "text": "...",
+      "status": "open"
+    }
+  },
+  "time": {...}
+}
+```
+
+`messageId` is `null` because we use direct `result.add` (no comment-pin chain).
+
+## Error handling
+
+| Failure | Behaviour |
+|---------|-----------|
+| `bx_preflight` fails | Exit 1, print env hint |
+| `bx_resolve_task_id` fails | Exit 1, print "TASK_ID not found" hint |
+| Invalid `type` arg | Exit 1, list 5 valid types |
+| Network/HTTP error from `bx_call_v3` | Print raw response to stderr, exit 1 (NO retry — fail-fast, user re-runs) |
+| User cancels at confirm | Exit 0, no POST, no side effects |
+
+## Live test plan (Phase 2 verification)
+
+Run on task #2776 (this repo's SSOT) once with each type, verify in Bitrix UI tab "Kết quả", capture each `result.id`, then cleanup:
+
+```bash
+# After each test posts, capture result.id from output, accumulate in $IDS array.
+# Cleanup script:
+for id in "${IDS[@]}"; do
+  bx_call_v3 "tasks.task.result.delete" "$(jq -n --argjson id "$id" '{id:$id}')"
+done
+```
+
+## Examples
+
+### Skip picker (advanced)
+
+```
+/bx:task summary release
+```
+→ Goes directly to release-type field prompts (VERSION, HIGHLIGHTS, ...).
+
+### Picker mode (default)
+
+```
+/bx:task summary
+```
+→ AskUserQuestion shows 5 type options + Cancel.
+
+### Override task
+
+```
+/bx:task summary adr --task-id 9999
+```
+→ Posts ADR to task #9999 instead of CLAUDE.md walk-up.
+
+## Notes
+
+- Webhook user 614 ("Claude") owns each posted result (`createdBy: 614`) → has `rights.edit/remove = true`. Cleanup is allowed.
+- `tasks.task.result.list` filter shape on v3 is unknown (multiple shapes returned "Unknown filter condition" in research). v1 of this skill does NOT support listing; if needed, view results in Bitrix UI directly.
+- Extending to a 6th type: add row to "Type → Template" + "Field-list" tables, add picker option in step 4.

package/src/features/bx-task/assets/references/sync.md

@@ -0,0 +1,104 @@
+# /bx:task sync — Session Digest to Task Comment
+
+Post a manual session digest as a comment to the Bitrix task chat. Use when you want to sync progress mid-session or after a coding session without waiting for the Stop hook.
+
+## When to use
+
+- After completing a significant chunk of work in a session
+- When Stop hook didn't fire (e.g. session crash, manual exit)
+- When working in a project that hasn't set up bitrix-task-sync hooks yet
+- When you want to sync a specific context note manually
+
+## Args
+
+```
+/bx:task sync [--task-id N]
+```
+
+- `--task-id N` — override TASK_ID resolution
+
+## Pre-flight
+
+```bash
+source ~/.claude/skills/bx-task/lib/bx-resolve-task.sh
+source ~/.claude/skills/bx-task/lib/bx-api.sh
+bx_preflight || exit 1
+TASK_ID=$(bx_resolve_task_id "${EXPLICIT_TASK_ID:-}") || exit 1
+```
+
+## Algorithm
+
+### Step 1 — Collect context
+
+Run these bash commands silently (no output to user yet):
+
+```bash
+# Recent commits (last 5, format: hash subject)
+GIT_LOG=$(git log --oneline -5 2>/dev/null || echo "(no git history)")
+
+# Files changed in last commit
+GIT_FILES=$(git diff --name-only HEAD~1 HEAD 2>/dev/null | head -10 || echo "")
+
+# Current branch
+GIT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
+
+# CWD project name (last dir component)
+PROJECT=$(basename "$PWD")
+```
+
+### Step 2 — Ask user for session note (optional)
+
+Use `AskUserQuestion`:
+- question: "Thêm ghi chú cho session này? (optional — Enter để bỏ qua)"
+- options: 3-4 common options like "Bỏ qua", "Đã xong feature X", "Đang debug issue Y", "Other..."
+
+If user picks "Bỏ qua" or empty → `SESSION_NOTE=""`
+
+### Step 3 — Build BB comment
+
+```
+[b]⚡ Manual sync — {PROJECT}[/b]
+
+[b]Branch:[/b] {GIT_BRANCH}
+
+[b]Recent commits:[/b]
+{GIT_LOG formatted as bullet list with • prefix}
+
+{if GIT_FILES not empty:}
+[b]Files changed:[/b]
+{GIT_FILES formatted as • list}
+{endif}
+
+{if SESSION_NOTE not empty:}
+[b]Ghi chú:[/b] {SESSION_NOTE}
+{endif}
+
+[i]Synced via /bx:task sync[/i]
+```
+
+Rules:
+- Use `•` for bullet lists (not `-`)
+- No markdown headers, no `**bold**` — BB only
+- Max 2000 chars total; truncate git log lines to 72 chars each
+
+### Step 4 — Confirm + POST
+
+Show the BB text in an `AskUserQuestion`:
+- question: "Post comment này lên task #{TASK_ID}?"
+- options: "Yes, post it", "No, cancel"
+
+If Yes:
+
+```bash
+bx_call_v1 "task.commentitem.add" \
+  "TASK_ID=${TASK_ID}&POST_MESSAGE=$(python3 -c "import urllib.parse,sys; print(urllib.parse.quote(sys.stdin.read()))" <<< "${BB_TEXT}")" \
+  || exit 1
+```
+
+On success: print `✓ Comment posted to task #${TASK_ID}`
+
+## Error handling
+
+- No git repo → skip git sections, post with note only
+- Empty note + no git → warn "Nothing to sync. Add a --message or run from a git repo."
+- API 5xx → fail-fast, print error, suggest retry