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;
this file is the executable checklist. Process hub:
README.md. Visual spec: design.md.
History: CHANGELOG.md. Noob guide:
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/(stdlibunittest,
offline, no network). TUI tests skip only through the
HAS_TEXTUALguard. - 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 <retoor@molodetz.nl>, 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:
.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 <retoor@molodetz.nl>" 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 throughasynciotransports,
CPU work in@work(thread=True)workers that post back with
call_from_thread. asyncio.CancelledError(andKeyboardInterrupt) is caught only
to convert or clean up, thensettle()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 acancelledresult 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_callsbatch keeps its matchingrole:toolanswers
(BlackCatBot.validate_wirereturnsNone), including after a
cancel. Cancellingbashkills its whole process group first. - Enforcers:
tests/test_cancel.pypasses, plus review of every
newexceptaround 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; TUI visual
changes update design.md; rule changes update
AGENTS.md. Research notes and the decision record
go in CHANGELOG.md or AGENTS.md. - Every edited markdown doc bumps its
<!-- doc: ... -->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_SCHEMASdescriptions,DSML_NUDGE, converge/extract
prompts) stay byte-identical to upstream. SYSTEM_DEFAULTis 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
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;
.envstays
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.