Work Tracker

The tracker is an append-only event log in .basicly/ledger/, committed with the code. Each write appends an event. A record is its events read in order. The kit is python3 .basicly/core/kit/tracker/cli.py, which needs nothing installed. The engine is basicly tracker, which works when basicly is on PATH.

Steps

python3 .basicly/core/kit/tracker/cli.py ready .basicly/ledger
python3 .basicly/core/kit/tracker/cli.py create .basicly/ledger --title "Fix the flaky clock test" \
  --field issue_type=task --field size=small \
  --description "## Context
When the suite runs in parallel, the clock test fails." \
  --acceptance "When the suite runs with -n 8, the clock test shall pass."
python3 .basicly/core/kit/tracker/cli.py claim .basicly/ledger RECORD-ID
python3 .basicly/core/kit/tracker/cli.py confirm .basicly/ledger RECORD-ID --evidence JSON
python3 .basicly/core/kit/tracker/cli.py close .basicly/ledger RECORD-ID --reason "why"

1. Find or file the record before the work. Give it a ## Context and at least one acceptance criterion; a record bigger than size=small also needs review --evidence before the claim. Run create alone and read the id from its reply; the tracker-commit-msg hook refuses a commit that names an id the ledger does not hold.
2. Claim it before the first edit, then push, because others see a claim only after they pull. A refused claim prints a refused key and exits 1; fix what it names, then claim again.
3. Confirm, then close it once the whole task is done: confirm records each criterion with its command and result, as {"checks": [{"criterion": "...", "command": ["argv"], "result": "what you saw", "exit_code": 0}]}, and close refuses without it.
4. Commit the code and the staged .basicly/ledger together, with the id in the subject; the hooks read the Git index. Make no separate close commit.

When basicly is on PATH, basicly tracker write -- ... runs the writes through the engine with the grammar in write; a claim there is update RECORD-ID --status in_progress.

Rules

• Never take a record that someone holds. ready names each holder; --take is for an agreed handover only. The holder is --to, else BASICLY_HOLDER, else git config basicly.holder, else your git name; set basicly.holder to a pseudonym, because the ledger is committed.
• Name a record by its title, with the id as the address. A person cannot read a bare id.
• Never edit, delete or reorder a line in an event file. Append the write that supersedes the wrong one.
• Probe against a scratch ledger directory, never the live one: python3 .basicly/core/kit/tracker/cli.py create "$(mktemp -d)" --prefix probe --title probe. The log has no undo.
• Check the output shape before you parse it. show on an absent record prints {"found": false}. The kit create prints JSON; read its record field. The engine create prints created: RECORD-ID, or JSON with --json.
• Use one ledger per repository, never one per worktree. The git-ignored .basicly/ledger/redirect points every worktree at the same log.

Read when needed

• For selective reads, history or the served page, read read.
• Before a write, review or close, read write for the grammar and the Context, Acceptance and evidence contracts.
• For imports, shard folding or bulk queries, read maintenance.