## Backlog (how we work)

This folder is the **single source of truth** for planned, proposed, completed, and deprecated
engineering work in AbstractVision.

Note:
- `docs/backlog/` is an internal engineering log (design notes + completion reports).
- For current, user-facing docs and install/usage instructions, prefer `docs/README.md` and `README.md`.

### Principles

- **Backlog items are self-contained**: each task includes the outcome of research, key constraints, design choices, and the reasons for those choices (with references).
- **No test-driven special casing**: implementation must be general-purpose logic, not tailored to tests.
- **Keep the public contract stable**: preserve the integrator-facing API (`VisionManager.generate_image/edit_image/generate_angles/generate_video/image_to_video/...`).
- **Artifact-first outputs**: generated images/videos must be representable as small JSON objects (refs), not inlined bytes, to support tool calling + workflows + third-party integrations.
- **Lightweight base install, explicit local runtimes**: the default install supports shared contracts, the capability registry, artifact refs, the OpenAI-compatible HTTP backend, CLI glue, and AbstractCore plugin discovery without installing local inference runtimes. Local Diffusers is explicit through `abstractvision[diffusers]`; stable-diffusion.cpp python bindings are explicit through `abstractvision[sdcpp]`; `abstractvision[local]` installs that Diffusers + `sdcpp` stack; MLX-Gen stays explicit through `abstractvision[mlx-gen]` or the aggregate `all` / `all-apple` profiles. Importing `abstractvision` should not eagerly import heavy runtime stacks unless needed (avoid model loads/weight downloads at import time; defer heavy backend imports until backend construction or first use).
- **Prefer permissive licensing**: only adopt MIT/Apache/BSD-compatible components. If none exist, document feasibility and create a backlog item.

Note: older completed backlog items may describe either a “default Diffusers install” phase or earlier “heavy deps behind extras” plans.
Treat `pyproject.toml` and the latest planned/completed packaging task as the source of truth.

---

## Folder layout

- `docs/backlog/planned/`: work to do next
- `docs/backlog/proposed/`: plausible follow-ups or experiments that should stay out of the
  committed plan
- `docs/backlog/completed/`: finished tasks with a completion report
- `docs/backlog/deprecated/`: superseded, rejected, or intentionally closed items kept for history

### Current inventory

- Planned: 3 items
- Proposed: 0 items
- Completed: 25 items
- Deprecated: 2 items

### Current planned items

- `docs/backlog/planned/020_adapter_aware_model_graph_and_catalog.md`
- `docs/backlog/planned/0022_local_diffusers_image_to_video_backend.md`
- `docs/backlog/planned/0023_local_runtime_capability_quarantine_for_glm_mflux_and_t2v.md`

---

## Naming convention

Create new tasks as:

- `docs/backlog/planned/{NNN}_{short_description}.md`

Rules:
- **NNN**: zero-padded integer (e.g. `017`)
- **short_description**: snake_case, concise

Note: older tasks may use legacy names; do not rename unless a dedicated cleanup task exists.

---

## Task template (required sections)

Every backlog item must include:

- **Title**
- **Date**
- **Status**: Proposed / Planned / Completed / Deprecated
- **Priority**: P0/P1/P2
- **Main goal(s)** and **secondary goal(s)**
- **Context / problem statement**
- **Constraints**
- **Research & references** (links + key findings)
- **Decision** (what we choose + why)
- **Dependencies** (ADRs and other tasks)
- **Implementation plan** (small steps, minimal surface area)
- **Success criteria**
- **Test plan**
- **Report** (for completed tasks only)

See `docs/backlog/template.md`.

---

## Work process (development cycle)

0. **Think, design, and plan** with long-term consequences in mind; prefer the cleanest, simplest, most efficient approach.
1. **Write the task** in `docs/backlog/planned/{NNN}_{short_description}.md` for committed work, or
   `docs/backlog/proposed/{NNN}_{short_description}.md` for speculative follow-ups worth preserving.
2. **Implement** the task.
3. **Test** and fix issues.
4. **Only when all tests pass**, move the task to `docs/backlog/completed/` and add the completion report at the end.
5. For releases, ensure hygiene:
   - update `CHANGELOG.md`
   - bump `abstractvision.__version__` in `src/abstractvision/__init__.py`
