[wip] #30 automation: orchestration state machine + run ledger for deterministic recovery

[nutt-adam]

Kickoff PR to guarantee active workstream for #30 within the 8-hour delivery window.\n\nThis PR opens the branch and checklist; subsequent commits will implement the issue proper.

Summary by CodeRabbit

• Chores
  • Added internal project planning documentation for upcoming work.

---

Note: This release contains no user-facing changes.

[coderabbitai]

📝 Walkthrough

Walkthrough

A new Markdown plan document is added at plans/issue-kickoff/issue-30.md that outlines the kickoff details for Issue #30, including the issue title, goal, initial work items (reproduce current behavior, implement minimal end-to-end path, add tests, update documentation/versioning), and a blockers section.

Changes

Cohort / File(s)	Summary
Issue #30 Kickoff Plan plans/issue-kickoff/issue-30.md	New project plan document outlining title, goal, first slice of work items for Issue #30, and blockers section.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

Poem

🐰 A plan takes shape, so neat and bright,
With goals and tasks all set just right,
No blockers yet, we're good to go—
Let's build this feature, watch it grow! ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description is incomplete. It lacks required versioning section, SemVer choice, validation checklist, and release information specified in the template.	Add the required template sections: Versioning (with Cargo.toml and CHANGELOG.md status), SemVer choice, Validation checklist, and Release information.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main feature being introduced: issue #30 work on an orchestration state machine and run ledger for deterministic recovery.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch wren/issue-30-kickoff

📝 Coding Plan

• Generate coding plan for human review comments

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[nutt-adam]

Automation: converted from draft to ready for review to unblock merge checks.

[nutt-adam]

Automation: marked ready for review to unblock CI/review gates.

[coderabbitai]

🧹 Nitpick comments (2)

plans/issue-kickoff/issue-30.md (2)

5-12: Define explicit acceptance criteria for “deterministic recovery.”

The goal references deterministic recovery, but the checklist doesn’t yet define a verifiable condition (e.g., same input/run-id replay yields identical terminal state + ledger entries). Adding that now will reduce ambiguity in the implementation PRs.

Proposed doc update

 ## Goal
 Implement and ship issue `#30` with tests and docs.
+Success criteria:
+- Replaying the same run inputs from the run ledger reproduces the same terminal orchestration state.
+- Recovery after interruption resumes from persisted state without duplicating side effects.
 
 ## First slice (next PR updates)
 - [ ] Reproduce/validate current behavior
 - [ ] Implement minimal end-to-end path
 - [ ] Add tests for success + failure cases
+- [ ] Add deterministic replay/recovery tests (same inputs => same outputs/state)
 - [ ] Update docs/changelog/versioning per policy

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@plans/issue-kickoff/issue-30.md` around lines 5 - 12, Add an explicit,
verifiable acceptance criterion for "deterministic recovery" to the Goal/First
slice checklist in issue-30: state that replaying the same input and run-id must
produce identical terminal state and identical ledger entries (or clearly define
allowed nondeterminism), and add a checkbox under "First slice (next PR
updates)" for "Define and test deterministic recovery: same input/run-id replay
yields identical terminal state and ledger entries" so implementers and tests
have an unambiguous requirement; reference the "Goal" section and the "First
slice (next PR updates)" checklist when updating the document.

---

1-15: Add owner + target checkpoint metadata to make the 8-hour objective auditable.

Since this kickoff is explicitly time-boxed in PR objectives, include owner and target checkpoint in the doc so progress/risk can be assessed quickly.

Proposed doc update

 # Issue `#30` kickoff
 
 Title: automation: orchestration state machine + run ledger for deterministic recovery
+Owner: `@nutt-adam`
+Kickoff date: 2026-03-16
+Target checkpoint: 2026-03-16 + 8h
 
 ## Goal
 Implement and ship issue `#30` with tests and docs.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@plans/issue-kickoff/issue-30.md` around lines 1 - 15, Add explicit owner and
target checkpoint metadata to the kickoff doc so the 8-hour objective is
auditable: under the "Issue `#30` kickoff" or directly beneath "Goal" add fields
labeled "Owner" (person or team responsible) and "Target checkpoint" (date/time
and the concrete checkpoint to verify progress), and mirror those fields in the
"First slice (next PR updates)" checklist items where appropriate so reviewers
can quickly assess progress/risk; ensure the labels "Owner" and "Target
checkpoint" are present and clearly populated in the document.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@plans/issue-kickoff/issue-30.md`:
- Around line 5-12: Add an explicit, verifiable acceptance criterion for
"deterministic recovery" to the Goal/First slice checklist in issue-30: state
that replaying the same input and run-id must produce identical terminal state
and identical ledger entries (or clearly define allowed nondeterminism), and add
a checkbox under "First slice (next PR updates)" for "Define and test
deterministic recovery: same input/run-id replay yields identical terminal state
and ledger entries" so implementers and tests have an unambiguous requirement;
reference the "Goal" section and the "First slice (next PR updates)" checklist
when updating the document.
- Around line 1-15: Add explicit owner and target checkpoint metadata to the
kickoff doc so the 8-hour objective is auditable: under the "Issue `#30` kickoff"
or directly beneath "Goal" add fields labeled "Owner" (person or team
responsible) and "Target checkpoint" (date/time and the concrete checkpoint to
verify progress), and mirror those fields in the "First slice (next PR updates)"
checklist items where appropriate so reviewers can quickly assess progress/risk;
ensure the labels "Owner" and "Target checkpoint" are present and clearly
populated in the document.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: c96f8aef-f66d-4a17-a229-6fb98d319723

📥 Commits

Reviewing files that changed from the base of the PR and between ad4bd03 and 85921a5.

📒 Files selected for processing (1)

• plans/issue-kickoff/issue-30.md