RunDay

RunDay (@rundiffusion/runday) is RunDiffusion's Git-native engineering task, claim, delivery, and accountability system. The lowercase runday binary is its command-line interface. Agents treat “RunDay”, “Runday”, and “runday” as the same product name in natural-language requests.

RunDay stores no company data outside the repository that invokes it:

• Markdown on the default branch is the durable task and shiplog ledger.
• remote Git refs reserve task IDs, arbitrate active claims, and pin handoffs;
• Git history records authorship and evidence;
• repository CI decides what may merge.

There is no database, hosted service, daemon, telemetry, HTTP client, or persistent cache. Any JSON audit output is a disposable CI artifact.

Develop

Use Node 22.15 or newer:

npm ci
npm test

The integration suite creates temporary bare Git remotes and proves fetched snapshot reads, cross-path ID races, exact-SHA leases, immutable handoffs, safe reservation and claim cleanup, rules synchronization, and delivery accountability. Destructive tests never use a consumer repository's remote.

To exercise the CLI from a repository containing accountability.config.json:

npm run build
node /path/to/devapps/ledger/dist/cli.js check

Package safety

Before publishing, run:

npm ci
npm test
npm pack --dry-run --json

The package files allowlist permits only dist/, the generated-rule assets, this README, and the MIT license. Inspect the dry-run JSON and reject the release if it includes tests, fixtures, credentials, repository configuration, tasks, shiplogs, or plans.

The runtime dependency list intentionally contains only the generic YAML parser. Do not add network clients, database drivers, telemetry, or caches.

Queue selection

Online discovery reads one fetched default-branch snapshot, even from a stale checkout or unrelated feature branch. runday next shows one highest-ranked eligible task. runday ready shows a bounded eligible shortlist without claiming anything. runday start remains deterministic: without an ID it atomically claims the highest-ranked task; with an ID it claims that explicit eligible task.

When a human explicitly directs immediate new work, runday start --new creates and validates the packet, atomically publishes reserve/<ID>, work/<ID>, and any optional handoff/<ID>, then creates its worktree. Other clones see it as active-unmerged, while next, ready, and argument-less start continue to distribute only durable default-branch work.

runday new remains the task-only intake path for future shared-queue work. It atomically publishes reserve/<ID> and any optional handoff before writing the local packet. Other clones see the reservation as intake-unmerged, but it is not eligible for ready, next, or ordinary start. Generated IDs retry the next available number after a race. An explicit --id fails if another caller wins it.

Task identity is the ID plus packet path. Matching paths across the default branch, reservation, and claim are one task even when the packet evolves. Different paths using one ID are an identity conflict. Discovery reports the conflict, queue selection excludes it, and targeted mutations fail closed. Legacy work/<ID> claims without a reservation remain valid.

Notification adapters belong outside this package. A Slack, email, or support adapter may consume committed task and shiplog changes, but it must not become task authority or add credentials, network clients, or delivery state to the core CLI.

Safe claim cleanup

runday cleanup [TASK-ID] is always a dry run. It must run from a clean local default branch whose HEAD exactly matches the fetched remote default branch. A reserve/<ID> ref is eligible when the default branch contains the same ID and packet path. A work/<ID> ref remains eligible only when its Markdown and delivery state prove an implementation merge. runday cleanup [TASK-ID] --apply then:

1. archives each exact inspected tip under its archive/reserve/<ID>/... or archive/work/<ID>/... namespace;
2. deletes the matching remote ref with an exact-SHA lease; and
3. for claims, removes only a matching clean local worktree and branch.

Dirty or divergent local work blocks cleanup. handoff/ refs and existing archive/ refs are never deleted. Agents should show the dry-run result and use --apply only when a developer explicitly requests the mutation.

Manual release

The canonical source remains in the private image-ai Bitbucket repository, so releases use a manual public npm publish rather than public-GitHub OIDC:

npm login
npm whoami
npm publish --access public

Never commit an npm token. Publish from a clean commit, with npm 2FA enabled, after reviewing npm pack --dry-run --json. Consumer repositories exact-pin the published version in their lockfiles.

Repository contract

Each consumer supplies accountability.config.json, tasks/, shiplog/, and plans/. runday sync --write installs the package-owned .agents/skills/runday/SKILL.md and docs/agents/runday-core.md; runday sync checks them without writing. Repository-specific guidance belongs in docs/agents/runday.md. The updater never edits that overlay, AGENTS.md, CI, configuration, or dependency files.