rekursiv-ai/trackinizer/trax

trax -- Trackinizer CLI Skill

Use trax as the task and inquiry tracker for Trackinizer-backed work.

Core rule: grammar.lark, GRAMMAR.md and trax help are the source of truth. If this skill disagrees with live help, trust live help. The CLI is deterministic left-to-right prefix parsing: existing refs end at seq/UUID, inline creates consume fields until a non-field token, edge metadata ends at the first non-metadata token, and del/help are terminal. Do not guess ownership from prose; apply these boundaries.

Rules

1. Run commands as trax ...; assume it is on PATH.
2. Run trax <kind> help before the first write to a kind each session.

Field cheat-sheet: Issue takes title/description/status/priority/owner; Paper takes source (not url); note/valence are EDGE metadata, not row fields -- there is no bare note verb on a row.

1. Use trax for task/inquiry tracking, not git operations.
2. Take ownership of substantial multi-agent work before editing. Prefer

trax next owner to Agent --as Agent, which selects and claims in one atomic step -- safe under concurrent agents, since no two callers can land on the same Issue. Only use trax issue 7 owner to Agent when you already know the specific Issue you want (e.g. one the user pointed you at); doing that on an Issue found via trax next/board recreates the race the atomic form exists to close. An active row with no owner is open; with an owner it is in progress.

1. Every trax write must include --as ACTOR, where ACTOR is your current

agent self name (for this session, Agent). Add --reason TEXT when the audit log needs context; --reason is optional.

1. Record useful verification on tracked work: trax issue 7 validation to "...".

Long-lived issues: append dated progress sections to the description. Append recipe (no append primitive exists): read the current body (trax issue 7 description), add a dated section locally, write it back with description to @file or to -.

1. Link durable outputs as first-class artifact rows with produced; do not bury

commit SHAs, experiment results, papers, web pages, searches, or beliefs in an issue description.

1. Record agent-cost as marginal spend on the most granular issue that directly

consumed the work. Prefer leaf issues; do not add parent totals when children already carry costs because trax cost ... --deep aggregates them.

1. Reference row ids in commit messages only when the user asks you to write one.
2. Triage server errors by class: connection-refused/5xx = outage --

probe trax profile, tell the user, keep working; HTTP 422 = your payload is wrong -- fix the command, do not retry verbatim; auth = ask the user how the deployment is configured.

Ownership, actors, and priorities

owner means the person or agent currently responsible for the row. For multi-agent work, set each child issue owner to the subagent actually doing that leaf; the coordinator owns only the coordination issue.

Use --as <name> on every write so the audit log reflects who did the work. Use your current agent self name for your own writes. Use another actor only when recording work on behalf of that actor. Add --reason TEXT only when the changelog needs extra audit context. --reason is stored on the change log; it is not row state and is not part of normal trax queries. Example:

trax issue 64 owner to issue63-runtime-agent --as Agent
trax issue 64 validation to "pytest ... passed" --as issue63-runtime-agent
trax issue 64 status to abandoned --as Agent --reason "superseded by Issue#72"

Issue priority is an integer (lower = more urgent). The CLI also accepts a named alias per band, which is what examples use (priority to high):

Intermediate integers exist for rare tie-breaking inside a band, but avoid them by default so priority retains a clear dynamic range.

Status model

Statuses are active|complete|abandoned|invalid. active with no owner is open; with an owner it is in progress. trax next, board, and blocked operate over active rows. abandoned = work stopped before completion; invalid = should not have been opened. Prefer either over del when history matters.

Kinds and artifacts

issue is the only schedulable kind; every other kind is an artifact (evidence or output) that issues produce and beliefs cite. grammar.lark (and GRAMMAR.md) owns the current kind list, and types/inquiries.py owns the kind meanings and fields; do not hand-maintain them in this skill. When an issue produces an output, create/link the most specific artifact row with produced; do not append the evidence as prose to the issue body.

Two artifact boundaries are easy to get wrong:

• A codechange row must use the full 40-character SHA from git rev-parse,

never an abbreviated SHA.

• An agentsession row is the captured session envelope; its transcript lives

in session_records, outside normal inquiry edges and change logs.

Every kind also has app: one JSON object where an app layered on trackinizer keeps its own fields about the row, under one key named for the app (trax issue 7 app to '{"<app>": {...}}'). Trackinizer never reads it, and it is not a filter field: an app finds its rows by labels and edges, and app holds only what the app knows about each one. Write the whole object; a write that must keep another writer's key compares and sets through the API.

Editing Trackinizer/trax

When changing Trackinizer, keep the skill aligned with the owning contracts:

• Keep the CLI grammar minimal. trax/docs/{grammar.lark,GRAMMAR.md} and

trax/grammar.py define accepted forms; prefer one deterministic production or deleting a form over adding a special case.

• Do not hand-maintain kind, token, field, or route lists in this skill. Point

to the owning source instead.

• Treat types/inquiries.py, types/edges.py, types/change_log.py, and

types/session_records.py as the DB/domain source of truth. API docs explain the wire surface; types win on names and structure. The record VOCABULARY is not trackinizer's: it is trackinizer.sagent.session.types.

• Follow docs/api.md and docs/api_session_records.md for API naming.

Do not invent aliases or parallel names.

• Preserve the session_records asymmetry: it is deliberately outside

inquiries and change_log; simplifying trax must not collapse that boundary.

Minimal grammar

Refs are kind seq, a bare seq under a leading kind, or a UUID:

trax issue 7
trax issue 5 6 12
trax issue 1 belief 3

Common row forms:

trax                              # list all kinds
trax issue                        # list issues
trax issue status is active       # filter; ops: is ne re nre lt le gt ge isnull notnull
trax issue 7                      # show row
trax issue 7 --changes            # show row with audit history
trax issue title to "Title"      # create row
trax issue 7 title              # show field
trax issue 7 priority to high     # replace field
trax issue 7 label to backend     # overwrite list field
trax issue 7 label add urgent     # append list value
trax issue 7 label del old        # remove list value
trax issue 7 agent-cost add 1.25  # signed cost delta
trax issue 1..50 owner to jvd --makeitso  # bulk edit every matched row

A field to value mutation on a range/filter is a BULK edit applied to every matched row. When it matches more than one row it requires --makeitso; without it the matches are previewed and nothing is written (a zero- or one-row match applies directly).

A value that starts with `-` needs a `--` end-of-options marker, else argparse reads it as an unknown flag and fails with "unrecognized arguments" (the write silently no-ops). This bites Google Scholar cluster_ids, which are base64-ish and ~1/64 lead with - (e.g. -n5NzXb4b5sJ). Put -- after the last real flag / after the seq, before the positional SVO:

trax paper 176 -- google_scholar_cluster_id to -n5NzXb4b5sJ   # value leads with -
trax paper --format json -- 5 title to -weird                  # flags stay before --

Harmless on safe values, so trax <kind> [--flags] -- ... is a fine default.

Use FIELD to - to read one field value from stdin. Use FIELD to @path to read any number of field values from files or shell process substitutions:

trax issue title to "Clear title" description to - <<'EOF'
## Problem
The retry path drops timeout context.
 
## Validation
Run the retry regression test.
EOF

trax issue title to "Clear title" description to @body.md
trax issue title to "Clear title" description to @<(printf '%s\n' '# Body')

Every edge is stored child -> parent (from = younger/dependent, to = older parent), and there are exactly seven stored kinds: narrows, requires, produced_by, supersedes, proves, favors, cites_paper. The CLI offers reverse-voice aliases so either endpoint can anchor the same stored edge.

Use requires / required_by for Issue prerequisites -- they are unambiguous:

• A requires B -- B is a prerequisite of A; B must be done before A.
• A required_by B -- the inverse; A must be done before B.

The two spellings are the same stored edge from opposite ends (A requires B == B required_by A). The blocks / blocked_by aliases name the same edge but read backwards -- A blocks B == A required_by B, and A blocked_by B == A requires B -- so they are easy to misread; prefer requires/required_by. A produced B means A spawned B (stored produced_by, B -> A); A narrows B / A broadens B is taxonomy.

Citations store Artifact -> {Belief, Experiment} (the citing artifact is the child pointing up to the claim): paper Q proves belief P stores the edge with the Artifact on the from-side, meaning Q is load-bearing evidence for P. When reading the claim, the same edge appears as proved_by; the reverse alias belief P proved_by paper Q stores the identical edge. favors is the same shape but contextual (does not vote in the proof predicate).

For-vs-against is the SIGN of the edge's valence ([-1, 1]: positive supports, negative argues against, default 0.5), not a separate edge kind. The CLI disproves / disfavors spellings are aliases for proves / favors that negate the valence (default -0.5), so they store the same two kinds with a negative sign.

trax issue 7 requires issue 8 --as Agent
trax issue 7 required_by issue 9 --as Agent
trax issue 7 produced codechange sha to $(git rev-parse HEAD) \
  title to "Implement retry policy" --as Agent
trax paper 5 proves belief 3 valence to 0.9 --as Agent
trax issue 7 requires             # list related rows; no --as for reads
trax issue 7 produced             # list produced artifacts; no --as for reads
trax issue 7 requires 1           # inspect one related edge/row; no --as for reads

Create commands mix row fields, list actions, and edge actions. Two composition rules cover most needs (full rules: GRAMMAR.md section 4):

• Descent: an existing-ref edge target (requires issue 125) does not

move the cursor -- later fields bind to the leading row. An INLINE-create edge target (requires issue title to ...) becomes the cursor -- later fields and edges bind to the NEW node, so consecutive inline creates chain.

• Siblings: wrap each child in begin ... end to pop the cursor back to

the anchor.