st

Overview

Maintain a durable plan file in the repo (default: .step/st-plan.jsonl) using in-place JSONL v3 persistence with dual lanes:

• event lane for mutations
• checkpoint lane for periodic full-state snapshots

Plan items use typed dependency edges (deps: [{id,type}]) plus notes and comments, and render deterministically through show/read views.

Zig CLI Iteration Repos

When iterating on the Zig-backed st helper CLI path, use these two repos:

• skills-zig (/Users/tk/workspace/tk/skills-zig): source for the st Zig binary, build/test wiring, and release tags.
• homebrew-tap (/Users/tk/workspace/tk/homebrew-tap): Homebrew formula updates/checksum bumps for released st binaries.

Quick Start (Automatic Zig Binary + Brew Bootstrap)

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
RUN_ST_SCRIPT="$REPO_ROOT/codex/skills/st/scripts/run_st.sh"
if [ ! -x "$RUN_ST_SCRIPT" ]; then
  echo "run_st bootstrap script missing or not executable: $RUN_ST_SCRIPT" >&2
  exit 1
fi

# Always invoke st through RUN_ST_SCRIPT; it auto-installs tkersey/tap/st on macOS when needed.
"$RUN_ST_SCRIPT" --help

Workflow

1. Resolve repository root and set RUN_ST_SCRIPT to codex/skills/st/scripts/run_st.sh; use "$RUN_ST_SCRIPT" for all commands (do not call st directly).
2. If the run has 3+ dependent steps, likely spans turns, or already uses update_plan, adopt $st as the durable source of truth before editing.
3. If the plan came from $select, map selected units into stable $st IDs and dependency edges before execution starts.
4. Initialize plan storage with st init if missing.
5. Rehydrate current state with st show (or focused views via ready / blocked).
6. Run doctor when ingesting an existing plan file or when integrity is in doubt.
7. Apply plan mutations through subcommands (add, set-status, set-deps, set-notes, add-comment, remove, import-plan); do not hand-edit existing JSONL lines.
8. After each mutation command, consume the emitted update_plan: {...} payload and publish update_plan in the same turn.
9. Use emit-update-plan to regenerate the payload from durable state when needed.
10. Export/import snapshots when cross-session handoff is needed.

Commands

Run commands from the target repository root.

"$RUN_ST_SCRIPT" init --file .step/st-plan.jsonl
"$RUN_ST_SCRIPT" add --file .step/st-plan.jsonl --id st-001 --step "Reproduce failing test" --deps ""
"$RUN_ST_SCRIPT" add --file .step/st-plan.jsonl --id st-002 --step "Patch core logic" --deps "st-001"
"$RUN_ST_SCRIPT" set-status --file .step/st-plan.jsonl --id st-001 --status in_progress
"$RUN_ST_SCRIPT" set-deps --file .step/st-plan.jsonl --id st-002 --deps "st-001:blocks,st-003:blocks"
"$RUN_ST_SCRIPT" set-notes --file .step/st-plan.jsonl --id st-002 --notes "Need benchmark evidence"
"$RUN_ST_SCRIPT" add-comment --file .step/st-plan.jsonl --id st-002 --text "Pausing until CI clears" --author tk
"$RUN_ST_SCRIPT" ready --file .step/st-plan.jsonl --format markdown
"$RUN_ST_SCRIPT" blocked --file .step/st-plan.jsonl --format json
"$RUN_ST_SCRIPT" show --file .step/st-plan.jsonl --format markdown
"$RUN_ST_SCRIPT" doctor --file .step/st-plan.jsonl
"$RUN_ST_SCRIPT" doctor --file .step/st-plan.jsonl --repair-seq
"$RUN_ST_SCRIPT" emit-update-plan --file .step/st-plan.jsonl
"$RUN_ST_SCRIPT" export --file .step/st-plan.jsonl --output .step/st-plan.snapshot.json
"$RUN_ST_SCRIPT" import-plan --file .step/st-plan.jsonl --input .step/st-plan.snapshot.json --replace

Operating Rules

• Keep exactly one in_progress item unless --allow-multiple-in-progress is explicitly used.
• Track prerequisites in each item’s typed deps array; dependencies are part of the canonical JSONL schema.
• Parse CLI deps as comma-separated id or id:type tokens; missing type normalizes to blocks, and type must be kebab-case.
• Require dependency integrity:
  • dependency IDs must exist in the current plan,
  • no self-dependencies,
  • no dependency cycles.
• Allow in_progress and completed only when all dependencies are completed.
• Normalize user status terms before writing:
  • open, queued -> pending
  • active, doing -> in_progress
  • done, closed -> completed
• Mutation commands (add, set-status, set-deps, set-notes, add-comment, remove, import-plan) automatically print an update_plan: payload line after durable write.
• Lock sidecar policy: mutating commands require the lock file (<plan-file>.lock, for example .step/st-plan.jsonl.lock) to be gitignored when inside a git repo; add it to .gitignore before first mutation.
• Storage model: not append-only growth. Mutations rewrite the JSONL file atomically (temp + fsync + replace) and compact to a canonical replace event plus checkpoint snapshot at the current seq watermark.
• doctor is the first-line integrity check for seq/checkpoint contract issues; use doctor --repair-seq only when repair is explicitly needed.
• import-plan --replace atomically resets state in the same in-place write model.
• Prefer concise, stable item IDs (st-001, st-002, …).
• Prefer show --format markdown for execution: it groups steps into Ready, Waiting on Dependencies, In Progress, and terminal/manual buckets.

Sync Checklist ($st -> update_plan)

• After each $st mutation (add, set-status, set-deps, set-notes, add-comment, remove, import-plan), parse the emitted update_plan: {...} line and publish update_plan in the same turn.
• If no emitted payload is available (for example after init or shell piping), run:
  • "$RUN_ST_SCRIPT" emit-update-plan --file .step/st-plan.jsonl
• Preserve item ordering from $st in update_plan.
• Map statuses:
  • in_progress -> in_progress
  • completed -> completed
  • pending, blocked, deferred, canceled -> pending
• Keep dependency edges only in $st (deps); do not encode dependencies in update_plan.
• If an item has dep_state=waiting_on_deps, never publish that step as in_progress in update_plan.
• Before final response on turns that mutate $st, re-check no drift by comparing:
  • "$RUN_ST_SCRIPT" show --file .step/st-plan.jsonl --format json
  • the latest emitted update_plan payload.

Validation

• Run lightweight CLI sanity checks:
  • "$RUN_ST_SCRIPT" --help
  • "$RUN_ST_SCRIPT" doctor --file .step/st-plan.jsonl
  • "$RUN_ST_SCRIPT" emit-update-plan --file .step/st-plan.jsonl
  • "$RUN_ST_SCRIPT" show --file .step/st-plan.jsonl --format json

References

• Read references/jsonl-format.md for event schema, status/dependency state vocabulary, and snapshot import/export shapes.