jog
Immediate serial task queue execution engine and conversational capture skill. Use when an operator wants to queue, prioritize, inspect, or execute a sequence of tasks one at a time today without mara
SKILL.mdskills/2-daily/jog/SKILL.md
GitHub/jog — Serial Immediate-Queue Execution Engine
jog manages a serial queue of tasks for immediate execution today. It provides conversational task intake and runs tasks one by one with zero concurrency overhead, using releases.db (jog_queue table), the outer relay-driver.lock, and swarm-preflight. Since the GH-280 recalibration, per-task execution defaults to Marathon's reviewed one-phase driver (--executor marathon); --executor relay keeps the legacy single-phase relay-drive path as the documented rollback during a bounded compatibility window.
Conversational Triggers
When the operator speaks naturally:
"jog GH-123":- Validates the issue via
gh issue view 123. - Ensures a capture doc exists (in
PROJECT/1-INBOX/orPROJECT/2-WORKING/). - Ensures the issue is parked in the roadmap ledger (
releases roadmap add). - Enqueues the issue into
jog_queue(releases jog add GH-123). - Echoes:
jog: enqueued GH-123 at position N.
- Validates the issue via
"jog task above":- Extracts the immediate task/bug discussion from recent context.
- Creates the tracking GitHub issue via
gh issue create(issue-first SOP). - Writes the initial capture doc to
PROJECT/1-INBOX/GH-<num>-<title>.md. - Parks the issue in the roadmap ledger (
releases roadmap add). - Enqueues into
jog_queue(releases jog add <num>). - Confirms the newly created issue number and queue position with the operator.
CLI Commands
All commands run through python3 utils/py/releases_app.py jog <subcommand> (or releases jog <subcommand> when aliased):
releases jog add <GH-NUM|doc-path> [--pos N] [--dry-run]
Enqueue a task at the end of the queue (or at a specific position).
releases jog list [--all] [--json]
Display active queue items (or all historical items with --all).
releases jog bump <GH-NUM>
Move an active task to position 1 (head of line). Refuses terminal rows.
releases jog drop <GH-NUM> --reason "<text>" [--force]
Mark a task as dropped with an auditable reason. Refuses already-completed items without --force.
releases jog retry <GH-NUM>
Reset a failed, parked, or dropped task back to pending.
releases jog skip <GH-NUM> [--reason "<text>"]
Park the current head task and advance to the next item.
releases jog clear
Archive completed/dropped/parked terminal items.
releases jog to-marathon
Export active jog items to marathon format.
releases jog resume <GH-NUM>
Reconcile durable Marathon state for an item (spends no token).
releases jog retry-gate <GH-NUM>
Re-run ONLY the gate against the same head SHA (no builder turn).
releases jog retry-build <GH-NUM> --target-root <disposable-full-clone>
Fresh Marathon attempt on a fresh execution id (history preserved).
releases jog land <GH-NUM> [--pr N]
Verify committed delivery after hosted reconciliation and complete the primary queue row.
releases jog reconcile <GH-NUM>
Idempotent replay entry for jog land (same verification and steps).
releases jog run --target-root <disposable-full-clone> [--executor relay|marathon] [--reviewer <agent>] [--builder agy|codex|aider] [--auto-merge] [--max-tasks N] [--simulate] [--dry-run]
Execute the serial jog runner loop. Default executor is marathon (GH-280); --reviewer is
required (builder and reviewer must differ). --executor relay selects the legacy rollback
path during its compatibility window.
Runner Execution Lifecycle (jog run)
Outer Driver Lock & Hermetic Dry-Run:
--dry-run: Hermetic simulation with zero locks and zero mutations (leaves queue and DB untouched).- Real run: Acquires
relay-driver.lockviartl.driver_lock_path(), setsRELAY_DRIVER_LOCKED=1, and registers a clean exit handler. Concurrently running marathons or relays in the same clone are safely excluded (GH-42 / GH-354).
Receipt-Backed State Transitions: Every runner transition (lease acquisition, status changes, orphan reconciliation) goes strictly through
perform_writeinreleases_app.py, ensuring full journal, receipt-chain, and dump integrity.lease_pidis excluded from the committedreleases.sqldump to eliminate merge conflicts.Startup Lease Reconciliation: Inspects
jog_queuefor orphanedrunningrows (deadlease_pid). Resets them topending(orparkedifattempt_count >= 3).Fire-Time Promotion & Probe Linting: If a task's capture doc is in
PROJECT/1-INBOX/,jog runpromotes it toPROJECT/2-WORKING/, formats the status table, and lints itsfix_probes:- Rejects trivial or dummy probe patterns (e.g.
exit 0,true). - Requires referenced probe scripts/globs to resolve to actual files.
- In interactive mode, prompts operator to approve drafted probes before running preflight.
- In unattended mode, unreviewed auto-scaffolding without verified probes is parked with
unreviewed-probe-contractto prevent false-green runs.
- Rejects trivial or dummy probe patterns (e.g.
Swarm Preflight: Runs
swarm-preflight --gh-issue <n>:ready(exit 0) -> fires the executor (Marathon one-phase drive by default).already-landed(exit 4) -> markscompletedwith auto-drop receipt.not-ready-> marksparked, records error, and prompts operator.
Marathon Executor Dispatch (default; GH-280): Per-task execution is delegated to Marathon's reviewed one-phase driver: Jog validates the preflight packet's
marathon-invocation@1contract, invokes the drive, and projects the validatedmarathon-drive/result@1receipt. Attempts, review, gates, branch/commit, and PR identity are Marathon-owned; Jog records a receipt-backed projection, never a guess. Builder and reviewer are separated:--builderdefaults to the cost-blind lanes (agy;codex/aiderselectable) while--reviewer <agent>is required, must differ from the builder, and has no silent default.--executor relaykeeps the legacy single-phaserelay-drive.shdispatch as the explicit rollback path during a documented compatibility window; it will be removed in its own dedicated commit one release cycle after the flip — do not build new usage on it.Receipt-Backed Landing &
--auto-merge: A row is never markedcompletedon a self-report.jog landverifies GitHub truth first — merged state, merge-SHA reachability, PR identity (repo, base, head, head SHA), and qualifying gate evidence after hostedwave_reconcilehas completed issue/doc lifecycle — then completes the primary row and records its landing proof.- Default (Interactive): Pauses at each landing boundary for human confirmation. On confirm: merges PR into
developmentand re-anchors the checkout. On decline: marks rowparked(awaiting-landing) so unmerged tasks are never misrepresented ascompleted. - Unattended without
--auto-merge: Parks row asparked(awaiting-landing (unattended run without --auto-merge)) and halts advance. --auto-merge(verified, GH-300): Verifies GitHub truth against the receipt BEFORE merging — the PR must still be OPEN on the receipt's base/head/head SHA in this repo with the gate green on that head — and refuses (parking the row) instead of merging blind; on pass, merges intodevelopmentand re-anchors the checkout before advancing.
- Default (Interactive): Pauses at each landing boundary for human confirmation. On confirm: merges PR into
Teardown Cleanliness: Verifies clean worktree disposal, clean working tree status, and gate receipts between serial items. At campaign end, point the operator at
/merge-cleanupto retire the task clone (GH-690).
Primary writer and committed evidence (GH-1108, delivery 1)
Invoke mutating Jog commands in the canonical primary on development. Bind that primary
explicitly once for its origin; task clones do not configure themselves as primaries:
# Run in the checkout the operator selected as the primary.
key="$(PYTHONPATH=utils/py python3 -c 'from harness_paths import primary_config_key; print(primary_config_key("."))')"
git config --global "$key" "$PWD"
The origin-specific pin is shared with merge-cleanup's explicit --primary: a mismatched
path refuses. Jog also refuses unconfigured writers and non-development primaries before
queue/cache writes. Read-only list/export/dry-run do not need a primary pin.
Pass a separate full clone with the same origin to jog run --target-root <clone> or
jog retry-build --target-root <clone>. It must have no pre-existing ledger delta. Preflight,
Marathon, Tick and builder/reviewer work run in that clone. The primary retains the queue,
lease and restart cache. Execution must leave the clone's releases.db/releases.sql unchanged;
contract promotion commits only its doc pair there. The primary roadmap is repointed by
normal reconciliation after that document movement lands.
After approval, Jog commits and pushes exactly one portable evidence bundle on the lane:
TESTS-RESULTS/<date>+GH-<n>/jog/<execution-id>/. It contains the original Marathon result,
copied gate receipt, provenance and receipt.json with relative pointers and content hashes.
The original result's historical absolute paths are retained as source data; landing reads
the committed bundle pointers instead. Publication failure parks the item; resume can retry
publication without another builder turn. .tick/jog remains a local restart cache, never a
landing prerequisite.
Interim publication checkpoint: delivery 1 does not automatically push queue transitions.
Before merge-cleanup, inspect the primary's status, index and local supervisor commits. Commit
only owned Jog ledger/view paths explicitly, then normally push development. Confirm a clean,
published, fast-forward-ready primary. Unrelated changes, divergence or rejected push stop and
preserve state for reconciliation; do not bypass Phase 0. The automatic direct-push/rebuild
path is a separate PR so it can be reverted independently. --auto-merge on native Jog dispatch/retry refuses before leasing during this interim;
it cannot skip the publication checkpoint. Use merge-cleanup for actual landing;
its mapped Jog hook runs after hosted reconciliation and before the existing final post-merge
commit/push. A direct jog land call likewise needs that final publication checkpoint.
Landing requires merged GitHub truth, a green gate on the original approved SHA, clean
releases check, green hosted reconciliation and merge reachability from freshly fetched
origin/<integration>. A moved head may contain the exact validated receipt publication,
ledger-only changes in B1's six-path set, or mechanically proven upstream merges. For each
upstream merge, both parent trees and the recorded tree have those six paths stripped; a
conflict-free git merge-tree --write-tree must reproduce exactly the recorded stripped tree.
Any remaining conflict or extra/missing blob refuses. The committed landing.json records
both approved/delivery heads, tree IDs, exclusions and hosted run. No manual override or broad
document-directory exception exists. Replay uses canonical queue truth and emits no duplicate
completion transition.
Recovery Verbs
After an interrupted or failed item, pick the verb that matches what actually needs redoing:
jog resume <GH-NUM>— the crash/restart remedy: reconciles the durable Marathon state and re-projects a valid terminal receipt without spending a token (parks instead of silently re-firing when state is missing or contradictory).jog retry-gate <GH-NUM>— the "approved relay, red gate" remedy: re-runs ONLY the gate against the same head SHA with no builder turn, for failures fixed outside the build (e.g. operator intake-hygiene fixes).jog retry-build <GH-NUM>— the real rebuild: a fresh Marathon attempt on a fresh execution id when the build itself must be redone; all prior Tick history and execution records are preserved.