Skip to content
Repos

blackcat

Markdown 6.1 KB143 lines Opens in site

Directory Raw Download

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/ (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 <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 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; 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_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
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.
275.9ms