Skip to content

feat: persist structured workflow handoffs across workers - #260

Open
eshulman2 wants to merge 3 commits into
mainfrom
feature/structured-handoffs
Open

feat: persist structured workflow handoffs across workers#260
eshulman2 wants to merge 3 commits into
mainfrom
feature/structured-handoffs

Conversation

@eshulman2

Copy link
Copy Markdown
Collaborator

Summary

  • persist one bounded, semantic handoff record per repository in workflow state
  • materialize only .forge/handoff.md when a workspace is created or recreated
  • capture handoffs after task implementation, review fixes, and CI fixes
  • prevent stale handoff resurrection by removing saved state when the file is deleted
  • avoid persisting transient review plans, CI plans, or arbitrary .forge/ files

Design

This replaces the generic artifact-store approach from #44. Workflow state contains a typed handoff envelope (content, producing task, capture timestamp), while the workspace adapter owns conversion to and from the fixed handoff path. Content is capped at 64 KiB and materialization uses an atomic replacement.

Validation

  • ruff check passes for changed files
  • git diff --check passes
  • 54 core handoff/state/workspace/implementation tests pass
  • 30 CI-attempt and cleanup tests pass

Closes #44

@eshulman2

Copy link
Copy Markdown
Collaborator Author

Added edge-case hardening in 934453c:

  • first iteration with no saved handoff is a clean no-op
  • missing handoff removes stale checkpoint state
  • malformed checkpoint shapes and entries are ignored safely
  • oversized, symlinked, non-regular, unreadable, and invalid handoffs do not break the workflow
  • container-returned failures preserve partial/blocker handoffs
  • runner exceptions/timeouts capture a handoff already flushed before failure
  • review and CI fix runners use the same best-effort mid-flight capture boundary

Focused validation: 47 tests passed; Ruff and diff checks pass.

A hard worker/process crash before the container flushes a handoff or before the node can checkpoint remains outside this mechanism; handling that requires an external durable streaming/artifact service.

@eshulman2
eshulman2 force-pushed the feature/structured-handoffs branch from 934453c to 2bf21a4 Compare August 6, 2026 18:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant