ztrack

The real definition of done.

A typechecker for your issue tracker.

>npm i -D ztrack && npx ztrack init

Node ≥ 22.18 · Apache-2.0

ztrack — zsh

user@machine ~/acme-platform $ ztrack init ✓ Initialized ztrack team LOCAL • preset simple-sdlc user@machine ~/acme-platform $ ztrack check 18 closed issues checked ✓ 13 backed by verified evidence ✗ 5 closed on prose — no real commit cited ✗ ACME-318 "ship billing v2" marked Done · 0 evidence ✗ ACME-456 "fix payment gateway race condition" marked Done · 0 evidence ✗ ACME-591 "update privacy policy link" marked Done · 0 evidence ztrack: 5 of 18 "done" tickets are unverifiable. exit 1

How it works

Evidence-gated “done”

A checked box has to cite a commit that's actually in git — or the ticket fails.

ztrack — check

$ ztrack check ✓ ACME-140 api auth 7d4f1e2 · PR #88 ✓ ACME-141 rate limiter a2e8a2d · PR #91 ✗ ACME-142 dashboard widget cites a1b2c3d — not in git ✗ 1 failed exit 1

GitHub Issues, two-way

Two-way GitHub Issues sync built in. Linear/Jira stay the human surface you already use — sync there is on the roadmap.

ztrack — sync

$ ztrack sync github --repo acme/platform --pull ✓ pull: 1 created, 0 updated locally $ ztrack sync github --repo acme/platform --push ✓ push: 1 created, 0 updated on GitHub

Presets, not config sprawl

Green on day one with the default preset. Swap in a stricter one, or edit preset.mts, when you're ready.

ztrack — check

$ ztrack check ✓ ztrack check passed issues 1 • errors 0 • warnings 0

You cite it — ztrack doesn't guess

An acceptance criterion only turns green when you attach the SHA yourself: ztrack ac patch <issue> <ac> --json '{evidence:[…]}'. There's no inference step — ztrack checks the commit you cited exists, nothing more, nothing less. Same gate everywhere: ztrack check locally, the same command in CI (exit 1 blocks the merge), or ztrack loop plus the agent Stop-hook holding the turn until it's green.

ztrack — ac patch

$ ztrack ac patch LOCAL-1 dev/01 --json \ '{"checked":true,"status":"passed", "evidence":[{"id":"ev1","commit":"7d4f1e2","acVersion":1}]}' { "issue": "LOCAL-1", "acId": "dev/01", "changed": true, "dryRun": false } $ ztrack check ✓ ztrack check passed

Works with the tools you already use

Two-way GitHub Issues sync built in. Linear and Jira stay your human surface — sync there is on the roadmap.

Linear (roadmap)

Jira (roadmap)

GitHub

agents

claim done

dev/01 done

"implemented…"

ztrack

verify

commit ✓

PR head ✓

evidence ✓

your tracker

verified state

✓ verified

Pick your rigor as a preset

Four ready-made presets install a real Zod schema + rules file — plus a fifth: edit that file and write your own.

simple-sdlc

commit + proof, PR-free

default

simple-gh-sdlc

+ a merged GitHub PR

PR review

spec

specs, commit-backed evidence

minimal

speckit

GitHub Spec Kit, read-only

spec-kit

custom

edit preset.mts

your rules

Every ztrack check ends with a real count — e.g. issues 1 · errors 0 · warnings 0 — nothing silently dropped.

Built for agents

Agents fix-and-retry a typechecker until it passes — turns out that's the right loop.

ztrack — loop

$ ztrack loop start LOCAL-1 ✓ loop armed → LOCAL-1 (max 8) agent> marking dev/01 done — "implemented the endpoint" ztrack stop-hook → check… ✗ evidence_commit_not_found (turn blocked) agent> committed 7d4f1e2, opened PR #88, re-checking… ✓ all acceptance criteria verified ✓ turn may end

MCP server CI gate ztrack loop

Holds the agent's turn until check passes — fix-and-retry like a typechecker. Wire it as a CI gate, or drive it over MCP.

Track or verify — ztrack does both

Every other tool records what the agent claims, or scores outputs and forgets. ztrack is the system of record where “done” is verified.

	Records claim	Validates structure	Verifies evidence of done
Linear / Jira	✓	shape only	✗
Beads	✓	—	✗
spec-kit / OpenSpec	✓	✓	✗
Eval / observability	—	—	scores output
ztrack	✓	✓	✓

Credibility

It's not a mockup.

ztrack runs our own autonomous agent fleet in production.

CI re-proves a fabricated SHA fails — every release

Deterministic checks — no LLM judge

Apache-2.0

FAQ

Does it replace Linear/Jira?

No — it's a verification layer. Today, validated state syncs back two-way with GitHub Issues; Linear/Jira stay the tracker you already use, with sync on the roadmap.

Do I need new infrastructure?

No. The default is green with just git + a PR host. Screenshots and video are opt-in higher tiers.

Won't agents game it?

The hard checks are zero-false-positive facts — a SHA that's actually in git, a file that resolves. You can't pass without doing the work.

How is it different from spec-kit?

spec-kit validates the shape of spec prose. ztrack verifies evidence of completion, deterministically.

Is it just for AI agents?

It shines with agents (MCP, stop-hook), but the checks work for any team that wants “done” to mean something.

Open source?

Apache-2.0, local-first, no SaaS dependency.