# Definition of done A task is done only when every check below holds. No exceptions, no narrowing to get green. The rules live in [AGENTS.md](../AGENTS.md); this file is the executable checklist. Process hub: [README.md](../README.md). Visual spec: [design.md](../design.md). History: [CHANGELOG.md](../CHANGELOG.md). Noob guide: [HOW_TO_USE.md](../HOW_TO_USE.md). ## 1. Request fidelity The request is implemented exactly as asked. Nothing unrequested was added. Every clause counts: error, edge, and negative cases named in the request work, not just the happy path. A fix covers the root cause across every case it implies. ## 2. Tests - New behavior has new tests in `tests/` (stdlib `unittest`, offline, no network). TUI tests skip only through the `HAS_TEXTUAL` guard. - The full suite passes in this session: `.venv/bin/python -m unittest discover -s tests`. - Never narrow, skip, or weaken a failing test to make a run pass; fix the code or state plainly why the test expectation is wrong. - If any part could not be run, the final report names it as unverified, plainly. ## 3. Lint `ruff check blackcat/ tests/` (project `.venv`) reports clean: PTH (pathlib over `os.path`), UP (PEP 585/604, Python floor 3.11), plus the E/F/I/B gates in `pyproject.toml`. ## 4. Retoor header line Every Python file carries exactly one comment line, the header `# retoor `, placed after the module docstring (and any `from __future__` imports). New files start with the docstring (when it has one), the `__future__` import (when needed), and the header. Enforcer, run from the repo root: ```bash .venv/bin/python - <<'EOF' import io, tokenize for path in __import__("pathlib").Path("blackcat").rglob("*.py"): toks = [t for t in tokenize.generate_tokens( io.StringIO(path.read_text(encoding="utf-8")).readline) if t.type == tokenize.COMMENT] assert all(t.string == "# retoor " for t in toks), path print("headers ok") EOF ``` ## 5. No other comments Docstrings are not comments and stay. `#` inside strings is fine; the tokenizer above is the judge, not grep. No commented-out code, no decision-process notes in the source; decisions worth recording go in the final report or the CHANGELOG row. ## 6. Asyncio and cancellation - Blocking work never runs on the event loop: file I/O through `asyncio.to_thread`, subprocesses through `asyncio` transports, CPU work in `@work(thread=True)` workers that post back with `call_from_thread`. - `asyncio.CancelledError` (and `KeyboardInterrupt`) is caught only to convert or clean up, then `settle()` runs when the result is kept, otherwise the error is re-raised. Swallowing a cancel without settling is a bug. - One Ctrl+C cancels the running tool and the turn continues with the next step; the model gets a `cancelled` result that names the user as the cause. Three quick presses abort the whole turn back to user input. - The message history is never left wire-invalid: every assistant `tool_calls` batch keeps its matching `role:tool` answers (`BlackCatBot.validate_wire` returns `None`), including after a cancel. Cancelling `bash` kills its whole process group first. - Enforcers: `tests/test_cancel.py` passes, plus review of every new `except` around an await. ## 7. Object-oriented package code No module-level mutable state and no module-level logic functions anywhere in `blackcat/`, not just `blackcat/tui/`. Shared tables, flags, and session state live on classes (`BlackCatBot`, `FileState`, `CancelTracker`, `GlyphSet`, `CardFactory`, ...). Module-level names are read-only constants, aliases, or thin delegates kept for backward compatibility. Every widget that starts a timer stops it in `on_unmount`. Enforcer: review of the diff. ## 8. DRY and consistency One implementation per behavior; reuse the existing helper instead of adding a parallel one. New code matches sibling API shapes (same types, keys, constructors, error classes with `ok`/`code` fields) and the codebase conventions (stdlib logging with lazy percent-formatting, progress on stderr, results on stdout). No unrequested interfaces, files, or options. Enforcer: review of the diff against the touched area's siblings and call sites. ## 9. Docs - Behavior changes update [README.md](../README.md); TUI visual changes update [design.md](../design.md); rule changes update [AGENTS.md](../AGENTS.md). Research notes and the decision record go in [CHANGELOG.md](../CHANGELOG.md) or [AGENTS.md](../AGENTS.md). - Every edited markdown doc bumps its `` header version and date in the same change. - No orphan docs: every markdown file links to at least one other doc, and new docs are linked from the README table and the AGENTS.md canonical list. - No em-dashes anywhere. Enforcer: `grep -rn $'\u2014' --include='*.md' .` prints nothing. - The upstream prompt strings in `blackcat/agent.py` (`TOOL_SCHEMAS` descriptions, `DSML_NUDGE`, converge/extract prompts) stay byte-identical to upstream. - `SYSTEM_DEFAULT` is operator-owned. A change to it is a deliberate prompt change, never a drive-by edit, and holds these invariants: the documented sections in order, every doctrine clause present, no tool inventory (the wire adds that), no repeated line, ASCII only, within the token cap. Enforcer: `tests/test_system_prompt.py`. ## 10. Version and history `pyproject.toml` is bumped (patch for fixes, minor for scope changes, major for breaking changes) and [CHANGELOG.md](../CHANGELOG.md) gains one ascending row in the same change. The version lives in exactly one place. Enforcer: `.venv/bin/python -m blackcat --version` equals the `pyproject.toml` version. ## 11. Secrets, sandbox, handoff - Never print, copy, or commit secret values; `.env` stays gitignored. The file-tool sandbox and approval model stay intact unless the user asked to change them. - The working tree is left uncommitted for review. - The final report states what was verified by running it and what was not, and names every behavior that was exercised through its real interface.