Memory and ledger

Keep LEDGER/BOARD/RESUME current, claim ledger items so two sessions don't collide, and condense oversized memory files.

Goal#

Use the workshop's on-disk memory files — .workflow/LEDGER*.md, .workflow/BOARD.md, .workflow/RESUME.md, .orch/LAST_SESSION.md — as the source of truth across sessions, claim ledger checklist items so two agents don't work the same item, and shrink files that grew too large without losing what's still open.

Steps#

  1. Validate a ledger file before spawning work against it:

    orch ledger check [dir]

    Walks upward from dir (default: workspace root) looking for .workflow/LEDGER*.md, and fails if it's missing a ## Clarified section or its checkbox items are malformed.

  2. Claim one checklist item atomically, so a second session sees it's taken:

    orch task claim <ledger-file> <item-number> --holder <session-id>

    This is a shared_locks row keyed ledger:<path>#<N> with a TTL (--ttl-min, default 15). Release it when done:

    orch task release <ledger-file> <item-number> --holder <session-id>

  3. Print the ledger with claim markers next to items another live session already holds (never rewrites the file):

    orch ledger board <ledger-file>

  4. Shrink an oversized memory file through the gateway, on demand — nothing in orch triggers this automatically outside the opt-in pre_compact hook (see hooks-and-guards.md):

    orch memory condense

    Targets default to .workflow/BOARD.md and .orch/LAST_SESSION.md. ## Clarified, ## Ownership, and every open checkbox item are kept byte-for-byte; only narration and finished notes get summarized. The original file is kept beside the condensed one. Requires a running gateway (orch gateway) with a working upstream. Add --dry-run to see the before/after byte counts without writing, --threshold-bytes to change the size that triggers it (default 16384), or --file to target a different path.

  5. Regenerate the workshop's root AGENTS.md — the doctrine file Codex, Copilot, and Gemini read directly — from the live ledger/board instead of leaving it as orch init's one-time static seed:

    orch agents-md refresh

    Rebuilds the Tools section from the registered MCP tools and the Ledger/Board sections from .workflow/LEDGER.md and .workflow/BOARD.md. Non-clobber like every other seed: an existing non-empty AGENTS.md is left alone unless you pass --force. --dry-run previews the path it would write.

Verify#

orch ledger check
orch ledger board .workflow/LEDGER.md

ledger check prints ok (or the specific failures); ledger board shows (claimed: <session>) next to any item currently held.

Undo#

orch task release <ledger-file> <item-number> --holder <session-id>

An expired claim (past its TTL) is also free for anyone to reclaim without release. A condensed file can be restored from the backup path orch memory condense printed.

  • hooks-and-guards.md — context.hooks.pre_compact runs the same condenser automatically before compaction.
  • worktrees.md — each claimed task typically runs in its own worktree.