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"
- 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.
- 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.
- 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.
- 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.
1---2name: work-tracker3description: Reads, files, claims and closes records in the ledger tracker. Use to plan work, check what is ready, file a bug, or claim a record before work starts.4metadata:5 source: https://skillmd.com/skills/niksavis/work-tracker6---78<!-- Generated by `basicly skills-build` from skill.yaml. Do not edit; edit the source. -->910# Work Tracker1112The 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.13The 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.1415## Steps1617```sh18python3 .basicly/core/kit/tracker/cli.py ready .basicly/ledger19python3 .basicly/core/kit/tracker/cli.py create .basicly/ledger --title "Fix the flaky clock test" \20 --field issue_type=task --field size=small \21 --description "## Context22When the suite runs in parallel, the clock test fails." \23 --acceptance "When the suite runs with -n 8, the clock test shall pass."24python3 .basicly/core/kit/tracker/cli.py claim .basicly/ledger RECORD-ID25python3 .basicly/core/kit/tracker/cli.py confirm .basicly/ledger RECORD-ID --evidence JSON26python3 .basicly/core/kit/tracker/cli.py close .basicly/ledger RECORD-ID --reason "why"27```28291. **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.302. **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.313. **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.324. **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.3334When `basicly` is on PATH, `basicly tracker write -- ...` runs the writes through the engine with the grammar in [write](references/write.md); a claim there is `update RECORD-ID --status in_progress`.3536## Rules3738- **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.39- **Name a record by its title, with the id as the address.** A person cannot read a bare id.40- **Never edit, delete or reorder a line in an event file.** Append the write that supersedes the wrong one.41- **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.42- **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`.43- **Use one ledger per repository, never one per worktree.** The git-ignored `.basicly/ledger/redirect` points every worktree at the same log.4445## Read when needed4647- For selective reads, history or the served page, read [read](references/read.md).48- Before a write, review or close, read [write](references/write.md) for the grammar and the Context, Acceptance and evidence contracts.49- For imports, shard folding or bulk queries, read [maintenance](references/maintenance.md).