Skip to content

work-item-execution-tracking.md

Latest commit

 

History

History
136 lines (98 loc) · 5.73 KB

work-item-execution-tracking.md

File metadata and controls

136 lines (98 loc) · 5.73 KB

Work-Item Execution Tracking

This runbook describes the operator path for tracking real agent work in Orchestrarium task memory.

Use it when a repository keeps active task memory under work-items/active/<slug>/ and the lead or main session must prove which roles ran, what they accepted, and which gates remain open.

Files

Each active work item should keep these files together:

File Purpose
status.md Human-readable recovery state: current stage, active agents, completed agents, next action.
agent-runs.jsonl Machine-readable append-only ledger for each launched or accepted role result.
reviews/, design.md, plan.md, or role artifacts Accepted artifacts referenced by ledger events.

status.md remains the readable recovery surface. agent-runs.jsonl is the state that validators can inspect.

Initialize A Work Item

Use the helper before the first ledger event, or when migrating a legacy work item that already has status.md.

python scripts/agent-run-ledger.py --work-item work-items/active/<slug> init --primary-task "Implement accepted plan" --stage "Plan"
.\scripts\agent-run-ledger.ps1 --work-item work-items\active\<slug> init --primary-task "Implement accepted plan" --stage "Plan"

The init command creates missing status sections and agent-runs.jsonl without replacing existing task-memory content.

Append A Gate Event

Append exactly one event for one role result or main-session gate action.

python scripts/agent-run-ledger.py --work-item work-items/active/<slug> append \
  --role qa-engineer \
  --execution-role internal \
  --status completed \
  --gate PASS \
  --scope tests/test_work_items_state_checker.py \
  --artifact reviews/qa.md \
  --evidence "command:pytest -q"
.\scripts\agent-run-ledger.ps1 --work-item work-items\active\<slug> append `
  --role qa-engineer `
  --execution-role internal `
  --status completed `
  --gate PASS `
  --scope tests/test_work_items_state_checker.py `
  --artifact reviews/qa.md `
  --evidence "command:pytest -q"

The append command validates the work item after writing the event. If the new event makes the ledger invalid, the helper rolls agent-runs.jsonl back.

Validate One Work Item

Run this before stage closeout or archive movement.

python scripts/validate-work-item-state.py --work-item work-items/active/<slug>
.\scripts\validate-work-item-state.ps1 --work-item work-items\active\<slug>

Validation fails for duplicate run IDs, running agents, missing ledger files, missing evidence for PASS, missing accepted artifacts, artifact paths that escape the work item, and inconsistent BLOCKED or REVISE gates.

Check All Active Work Items

Run the periodic checker at handoff boundaries, before publication review, or when resuming after interruption.

python scripts/check-work-items-state.py --root . --stale-hours 24
.\scripts\check-work-items-state.ps1 --root . --stale-hours 24

--root points to the repository root. --active-dir defaults to work-items/active. --stale-hours 0 disables age checks; any positive value reports running events older than that threshold.

For deterministic automation, pass --now:

python scripts/check-work-items-state.py --root . --stale-hours 24 --now 2026-05-03T12:00:00Z

Installed Runtime Paths

Global installs copy the helper surface into the production provider runtime.

Provider Installed helper directory
Codex ~/.codex/skills/lead/scripts/
Claude Code ~/.claude/agents/scripts/

Project installs copy to the matching project-local runtime:

Provider Project-local helper directory
Codex <repo>/.agents/skills/lead/scripts/
Claude Code <repo>/.claude/agents/scripts/

Use the installed equivalent when the source checkout is not available in the target repository.

Operator Rules

  • Do not trust a subagent report without a matching ledger event and independent verification evidence.
  • Do not close a stage while agent-runs.jsonl contains a running event.
  • Do not accept PASS without evidence and an artifact when the role contract requires one.
  • Do not hand-edit JSONL unless no helper is available; prefer agent-run-ledger.*.
  • Run check-work-items-state.* --root . before broad closeout so stale active work items are visible, not silently skipped.

Terms and Abbreviations

  • agent-run-ledger.*: helper script family that initializes work-item ledger files and appends validated agent-runs.jsonl events.
  • agent-runs.jsonl: JSONL execution ledger stored beside status.md for machine-readable work-item state.
  • artifact: accepted output of a role or gate, such as a review file, design note, patch, or report.
  • BLOCKED: gate state for a real external blocker or missing prerequisite.
  • check-work-items-state.*: helper script family that checks every active work item under a repository root.
  • Codex: OpenAI Codex runtime and production provider line.
  • gate: acceptance result recorded for a scoped artifact, commonly PASS, REVISE, BLOCKED, or none.
  • JSONL: JSON Lines; one JSON object per line, used here for append-only ledger events.
  • PASS: gate state meaning a scoped artifact passed the relevant checks.
  • REVISE: gate state meaning the artifact must return to the same role for bounded correction.
  • stale running agent: a ledger event still marked running after the configured age threshold.
  • status.md: human-readable task-memory recovery summary.
  • validate-work-item-state.*: helper script family that validates one work-item ledger and its referenced artifacts.
  • work-item: one admitted task directory under task memory, usually work-items/active/<slug>/.