Files

T

naudachu 62c8ff976d feat: tick in-body checkboxes from a domain script

A checkbox is the one part of a body that is state and not prose.
Everything else is written once; boxes get ticked as the work goes, and
until now the only ways to tick one were a human with an editor or a
model rewriting the whole body. The second is worse: the rewrite re-flows
lines and re-words sentences, so the issue's diff swells around a change
that means one character. Progress was invisible too — issue_index.py
builds INDEX.md from metadata and never looked inside a body, so "3 of 7
done" required opening the file.

All three pieces are domain: a checkbox is body syntax, which is part of
the answer to "what is an issue". The parser goes in issue.py so the sync
layer can reuse it instead of redefining the format on its own side.

issue.py gains checkboxes(text) -> [Checkbox(index, line, end_line,
checked, text, section)], plus set_checkbox(text, item, checked) and
checkbox_progress(text). All pure, no I/O, importable from another layer.
The scan covers the whole text, in any section: the type/feature template
keeps child issues as checkboxes under `## Issues`, so binding the parser
to `## Acceptance criteria` would silently lose half of them; the heading
is recorded, never required. Only a marker line opens an item, so a
wrapped continuation line belongs to the item above it rather than
counting as one of its own. A `- [ ]` inside a code fence is an example
of the markup and is skipped. Line numbers are relative to the text
given, which is what lets a caller work on a body or on a whole file.

issue_ac.py lists the items numbered, grouped by heading, and ticks one
by number or by substring. An ambiguous substring is an error that prints
the matches — a coin flip would tick the wrong box and look like it
worked. It patches the file rather than round-tripping through
Issue.to_text(), so exactly one character changes: metadata order,
wording, wrapping, trailing whitespace and CRLF endings all come back
byte for byte, proven by a diff in the tests.

INDEX.md gains a progress column: `3/7` for an issue with checkboxes,
blank for one without. Counted off the body at build time and stored in
no field — a second copy of the state would be wrong by the next edit.

issue_check.py is unchanged and stays that way on purpose: an unticked
box is work not done yet, not a malformed issue, and validate() carries a
comment saying so.

Delivering a tick to the tracker is out of scope — that is push.py
--update in /tea:sync.

format.md gets one clarifying bullet. It said acceptance criteria are
checkboxes but never said what a checkbox is, so the parser had to settle
questions the format left open: any section, wrapped items, fenced
examples. Those rules are now written down where the parser and the sync
layer can both point at them.

tests/ is new, and is the convention: plain stdlib unittest, no pytest
and no third-party deps, since the code under test may not have
dependencies either. Scripts are imported via sys.path.insert and every
fixture is built in a TemporaryDirectory, never in tmp/.

    python3 -m unittest discover -s tests -v     32 tests, OK

skills/issue/scripts/ still imports stdlib only, with no subprocess.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-08-10 15:41:15 +05:00

4.6 KiB

Raw Blame History

AGENTS.md

Project goals

Unify and systematize issue workflow for the development team with minimal context usage. Issue operations are wrapped in scripts so agents spend tokens on the task, not on re-deriving commands and formats.
Keep the tracker out of the work. An issue is a unit of work first and a Gitea row second. The two are separate layers, and the first one does not know the second exists.
Route all Gitea interaction through the tea CLI via scripts instead of direct ad-hoc calls wherever possible. Scripts give deterministic, reviewable behavior; the tea-guard hook enforces that every tea invocation runs under the operator-pinned login.

Layers

The hard rule of this repo. Knowledge flows one way only:

skills/issue    DOMAIN     what an issue is: format, validation, dependency graph
      ▲                    offline — no tracker, no network, stdlib imports only
      │ imports
skills/sync     BRIDGE     map.py    md <-> Gitea JSON, pure functions, no I/O
                           _gitea.py login pin, tea api, pagination, filters
skills/use      REFERENCE  tea CLI docs for everything that is not an issue
skills/auth     IDENTITY   pin the login the whole tracker side runs under
      ▲
      │ calls
agents/         EXECUTION  tea-runner: runs the scripts, reports a receipt

skills/issue never imports from skills/sync. Delete skills/sync and the domain layer keeps working. The check is mechanical — every import under skills/issue/scripts/ is stdlib, and subprocess is not among them:

grep -rh '^import \|^from ' skills/issue/scripts/ | sort -u

If a tracker concept (issue number, login, HTTP call, label color) shows up in the domain layer, it is in the wrong place.

Repo layout

skills/auth — pin the Gitea login used by tea (/tea:auth)
skills/issue — issues as units of work (/tea:issue), entirely offline
- references/format.md — canonical issue format; single source of truth
- scripts/issue.py — domain module: slug identity, parse/render, validation, taxonomy, dependency graph, body checkboxes
- scripts/issue_new.py — create a local issue from its type template
- scripts/issue_check.py — validate against the format
- scripts/issue_ac.py — list the body's checkboxes; tick one by number or substring, changing exactly one character of the file
- scripts/issue_tree.py — draw the dependency graph
- scripts/issue_index.py — rebuild tmp/issues/INDEX.md
skills/sync — move issues between the local store and Gitea (/tea:sync)
- scripts/map.py — md ↔ Gitea JSON, pure, no I/O; label colors live here
- scripts/_gitea.py — transport: login pin, tea api, pagination, filters, label ids, the remote-id map
- scripts/pull.py, push.py, remote.py, comment.py
skills/use — tea CLI reference for everything that is not an issue (/tea:use); references/tea/ holds the command docs
agents/tea-runner.md — subagent on Haiku that executes the scripts and returns a compact receipt. Delegate batches (bulk pull, push a named set, bootstrap labels, rebuild the index), never the thinking: it has no Edit and no Write, may not --force, and may not decide what an issue says. Delegating a single call costs more than running it inline — the win is the loop, the retry, and the error triage.
hooks/ — PreToolUse hooks: tea-guard blocks or rewrites tea invocations that don't use the pinned login; agents-sync keeps every directory canonical (AGENTS.md real file, CLAUDE.md symlink to it)
tests/ — stdlib unittest, no pytest and no third-party deps: the scripts under test may not have dependencies, so neither may their tests. Scripts are imported via sys.path.insert (skills/*/scripts/ are not packages), and fixtures are built in a tempfile.TemporaryDirectory() — never in tmp/.
```
python3 -m unittest discover -s tests -v
```

Local issue store

tmp/issues/ (gitignored) is the store, not a cache of Gitea. One flat markdown file per issue, named by its slug, with one metadata field per line so plain grep works without a parser.

Identity is the slug (wire-sqlc-appclick.md), never a tracker number. Numbers live in the gitea: field.
origin: local is a durable state. An issue that never leaves this machine is complete and valid, not a draft.
Pushing is additive: the file is never deleted, it gains gitea: / url: / synced:.
Pulling overwrites the body — a fetch, not a merge.
No drift tracking. synced: tells you how old your copy is; re-pull when it matters.