Work Tracker

The tracker is an append-only event log in .basicly/ledger/, committed with the code. A record is the fold of its events. The engine reads and writes the log directly.

Rules

• Prefer the installed engine for writes when basicly is on PATH. Use basicly tracker write -- before create, update, review, confirm, close or comments add; claim with update <id> --status in_progress. These narrow command rules survive Claude auto mode. The Python commands below remain available to standalone consumers, with their normal permission checks.
• Name a record by its title, with the id as the address. A person cannot read a bare id.
• File or find the record before you do the work. The tracker-commit-msg hook refuses a commit that names an id the ledger does not hold.
• Run create alone, then read the id from its reply. The id is random, so a commit chained after it with a guessed id is refused.
• Many people share this tracker. Never take a story that someone holds. ready names the holder of each reserved story, and the supervisor skips stories that another person holds. --take is for an agreed handover only.

• Reserve a story before you plan it, and push at once. Others see a reservation only after they pull:

  python3 .basicly/core/kit/tracker/cli.py assign .basicly/ledger <id>    # reserve it for you
  python3 .basicly/core/kit/tracker/cli.py claim .basicly/ledger <id>     # reserve it and start
  python3 .basicly/core/kit/tracker/cli.py unassign .basicly/ledger <id>  # give it back
  python3 .basicly/core/kit/tracker/cli.py ready .basicly/ledger --mine   # what you hold

  The holder name is git config user.name, or --to. basicly loop records the person who runs it as the holder, and it stops on a story that someone else holds.

• Never edit, delete or reorder a line in an event file. Every derived answer changes and nothing detects it. Append the write that supersedes the wrong one.
• Count from the file, interpret through the engine. Grants, gate results and phases derive from ordered events under rules that a regex cannot see.
• Probe against a scratch ledger directory, never the live one. The log has no undo, and the loop commits every probe event into project history.
• Check the output shape before you parse it. show on an absent record prints {"found": false}. create prints created: <id> unless the argv carries --json.
• Use one ledger per repository, never one per worktree. The git-ignored .basicly/ledger/redirect points every worktree at the same log. A per-worktree ledger loses the writes of a lane at teardown.

Stage the claim with its code. Commit hooks read the Git index. In a shared-ledger worktree, publish the claim on the base and update the lane from that committed base before committing its code.

Read when needed

• For selective reads, standalone kit commands, historical state or the served page, read read. Start with a summary or the existing record and latest handover; use a session summary only when useful.
• Before a write, review or close, read write for the exact grammar, Context/Acceptance/optional Requirements and evidence contracts. Existing approved scope needs no new refinement conversation.
• For imports, shard folding or bulk ledger queries, read maintenance.
• Completion means the actual change and evidence are recorded with attribution and shared history preserved; close only after the whole task is satisfied.