# vikunja-tasks

Vikunja task lifecycle beyond `create`: querying status, closing, and
recovering when the tracker is unreachable.

## When to Invoke

- Creating, closing, or checking a Vikunja task
- A spec workflow step needs the task ID or done state
- `vikunja.oblachno.oblachno.fyi` fails to resolve / times out

## Prerequisites

- `.env` with `VIKUNJA_TOKEN`
- Project ID comes from `[tool.devx]` in `pyproject.toml`
  (`DEVX_VIKUNJA_PROJECT_ID`)

## Create

`make create-task` does **not** forward arguments — call the module:

```bash
.venv/bin/python -m devx.tools.create_task \
  --title "Task title (no DEVX-N prefix)" \
  --description "<h2>Context</h2><p>...</p>"
```

Prints `DEVX-N` + next steps. Title must not include the task-ID
prefix (auto-merge prepends it; a manual prefix double-prefixes the
PR title and fails validation).

## Query / Close

```bash
# Task details (ID = numeric part of DEVX-N)
curl -sf -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  "https://vikunja.oblachno.oblachno.fyi/api/v1/tasks/<N>"

# Close: mark done
curl -sf -X POST -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  -H "Content-Type: application/json" -d '{"done":true}' \
  "https://vikunja.oblachno.oblachno.fyi/api/v1/tasks/<N>"
```

Post-merge automation marks the task done when the PR squash-merges —
manual close is only needed for abandoned/superseded tasks.

## Task-ID / Spec Collisions

Vikunja IDs can collide with historical spec files (an old task reused
the number). Convention: preserve the old file as
`docs/specs/<ID>-<topic>-historical.md`, then write the new spec at
`docs/specs/<ID>.md`. Check `git log` on the existing spec before
moving it.

## Tracker Unreachable

If the Vikunja host fails DNS/TLS:

1. Don't block the whole workflow — record the intended task title in
   the spec draft and retry `create_task` before branching.
2. Never invent an ID — branch/PR titles must match a real task or
   `pre_push_check` / auto-merge validation fails.
3. DNS failures observed so far were transient; retry after a few
   minutes before escalating.

## Common Mistakes

- `make create-task -- --title ...` — args are dropped; use the module
  call above (forwarding fix is S11 scope).
- Including `DEVX-N:` in the task title — double prefix breaks
  auto-merge.
- Closing a task whose PR is still open — auto-merge's post-merge
  step handles the close; manual close confuses the audit trail.