[plan][feat]: Implement lol rebase command and fix FSM rebase-to-review transition

[ayazhankadessova]

Description

The FSM implementation flow currently routes successful rebase to STAGE_IMPL (re-implementation), which is wasteful since the code is already implemented and only needs re-review after rebasing. Additionally, there is no standalone lol rebase CLI command for direct git rebase operations (distinct from the AI-assisted wt rebase).

This plan addresses both issues: fixing the FSM transition from rebase→impl to rebase→review, and adding a standalone lol rebase CLI command.

Modules affected:

• python/agentize/workflow/impl/ — FSM transition table and rebase stage kernel
• python/agentize/cli.py — Python CLI entrypoint
• src/cli/lol/ — Shell CLI dispatch, parser, commands, completion

Proposed Solution

Consensus Summary

This plan balances the bold proposer's full-featured approach with the reducer's minimalism and incorporates the critique's risk findings. The FSM transition fix (rebase→review) is the highest-value change and is paired with review counter resets. The standalone lol rebase CLI is included per the user's explicit request, but uses a thin handle_rebase() in cli.py (modeled after _sync_branch()) instead of reusing rebase_kernel() which requires ImplState. All missing integration files identified by the critique are addressed.

Goal

Fix the FSM transition so successful rebase routes to review (not impl), and add a standalone lol rebase CLI command for direct git rebase operations.

Success criteria:

• FSM transition (STAGE_REBASE, EVENT_REBASE_OK) routes to STAGE_REVIEW
• Review counters are reset after successful rebase
• lol rebase [--target-branch <branch>] works as a standalone command
• All existing tests pass, new tests cover the transition and counter reset

Out of scope:

• Modifying wt rebase (separate AI-assisted rebase command with different scope)
• Interactive conflict resolution
• Changes to other FSM transitions
• ✅ Good to have in the future: A --force-with-lease push flag for lol rebase to push after rebasing, useful for quick rebase-and-push workflows.

Codebase Analysis

Files verified (docs/code checked by agents):

• python/agentize/workflow/impl/transition.py line 52: Confirmed (STAGE_REBASE, EVENT_REBASE_OK): STAGE_IMPL
• python/agentize/workflow/impl/kernels.py lines 261-298: Confirmed rebase_stage_kernel() with 3-attempt retry guard
• python/agentize/workflow/impl/kernels.py lines 1361-1437: Confirmed rebase_kernel() requires ImplState
• python/agentize/workflow/impl/impl.py lines 287-302: Confirmed _sync_branch() pattern (fetch + rebase without ImplState)
• python/agentize/workflow/impl/impl.md line 86: Confirmed Mermaid diagram shows rebase -->|rebase_ok| impl
• python/agentize/cli.py: Confirmed existing subparser pattern (handle_impl(), handle_simp())
• src/cli/lol/dispatch.sh: Confirmed dispatch case pattern
• src/cli/lol/parsers.sh: Confirmed _lol_parse_impl() parser pattern
• src/cli/lol/commands/impl.sh: Confirmed shell-to-Python delegation pattern
• src/cli/wt/commands.sh line 420: Confirmed cmd_rebase() is AI-assisted (different from lol rebase)

File changes:

File	Level	Purpose
python/agentize/workflow/impl/transition.py	minor	Change rebase_ok target from STAGE_IMPL to STAGE_REVIEW
python/agentize/workflow/impl/kernels.py	minor	Reset review counters on EVENT_REBASE_OK
python/agentize/cli.py	medium	Add handle_rebase() and rebase subparser
src/cli/lol/commands/rebase.sh (new)	major	New shell command delegating to Python CLI (Est: 15 LOC)
src/cli/lol/parsers.sh	medium	Add _lol_parse_rebase function
src/cli/lol/dispatch.sh	minor	Add rebase) case and help text
src/cli/lol/commands.sh	minor	Source commands/rebase.sh
src/cli/lol/completion.sh	minor	Add rebase to completion
python/agentize/workflow/impl/impl.md	minor	Update Mermaid diagram rebase→review
python/agentize/workflow/impl/transition.md	minor	Update transition coverage text
python/agentize/workflow/impl/kernels.md	minor	Document review counter reset
src/cli/lol/commands/README.md	minor	Add rebase.sh to file map
python/tests/test_impl_fsm.py	medium	Add transition assertion and counter reset test

Current architecture notes:

• lol commands follow a shell→Python delegation pattern: dispatch.sh → parsers.sh → commands/X.sh → python -m agentize.cli X
• FSM uses a TRANSITIONS dict mapping (Stage, Event) → Stage in transition.py
• Each stage kernel is a function that returns an event; the orchestrator loops through transitions
• wt rebase is AI-assisted (Claude Code session); lol rebase will be a direct git operation

Interface Design

New interfaces:

1. handle_rebase(args) in python/agentize/cli.py:

   • Exposed as lol rebase [--target-branch <branch>] CLI command
   • Internal implementation:
     • Step 1: Determine remote (default origin) and base branch (default from --target-branch or detect main/master)
     • Step 2: Run git fetch <remote>
     • Step 3: Run git rebase <remote>/<branch>
     • Step 4: Print result (success / conflict / already-up-to-date) based on return code
     • Step 5: If conflict, run git rebase --abort and exit 1
   • No data structures needed; stateless function

2. _lol_parse_rebase in src/cli/lol/parsers.sh:

   • Parses --target-branch <branch> flag
   • Delegates to _lol_cmd_rebase with parsed arguments

3. _lol_cmd_rebase in src/cli/lol/commands/rebase.sh:

   • Delegates to python -m agentize.cli rebase with --target-branch passthrough

Modified interfaces:

# python/agentize/workflow/impl/transition.py line 52
-    (STAGE_REBASE, EVENT_REBASE_OK): STAGE_IMPL,
+    (STAGE_REBASE, EVENT_REBASE_OK): STAGE_REVIEW,

# python/agentize/workflow/impl/kernels.py in rebase_stage_kernel()
# After the EVENT_REBASE_OK branch (around line 295):
     if event == EVENT_REBASE_OK:
         state.iteration += 1
+        context.data["review_fail_streak"] = 0
+        context.data["review_attempts"] = 0
+        context.data["last_review_score"] = None

Documentation changes:

• impl.md Mermaid diagram: rebase -->|rebase_ok| impl → rebase -->|rebase_ok| review
• transition.md coverage: rebase -> impl/fatal → rebase -> review/fatal
• kernels.md: Add note about review counter reset on rebase success

Documentation Planning

Folder READMEs:

• src/cli/lol/commands/README.md — add rebase.sh / _lol_cmd_rebase row to file map table

Interface docs:

• python/agentize/workflow/impl/impl.md — update Mermaid diagram line 86
• python/agentize/workflow/impl/transition.md — update transition coverage line 34
• python/agentize/workflow/impl/kernels.md — document review counter reset on rebase success

Test Strategy

Test modifications:

• python/tests/test_impl_fsm.py - FSM transition and kernel tests
  • Test case: test_next_stage_resolves_expected_edges — add assertion next_stage(STAGE_REBASE, EVENT_REBASE_OK) == STAGE_REVIEW
  • Test case: test_rebase_ok_resets_review_counters — new test in TestRebaseStageKernel verifying counter reset
  • Test case: test_fsm_rebase_ok_reaches_review_then_finish — orchestrator test for full pr → rebase → review → simp → pr → finish path

Test data required:

• Mock context.data with pre-existing review_fail_streak=2, review_attempts=3, last_review_score=50 to verify reset

Implementation Steps

Step 1: Update documentation (Estimated: 8 LOC)

• python/agentize/workflow/impl/impl.md: Change line 86 rebase -->|rebase_ok| impl to rebase -->|rebase_ok| review
• python/agentize/workflow/impl/transition.md: Change rebase -> impl/fatal to rebase -> review/fatal
• python/agentize/workflow/impl/kernels.md: Add note about review counter reset
• src/cli/lol/commands/README.md: Add rebase.sh row

Dependencies: None
Correspondence:

• Docs: Establishes expected behavior for transition fix and CLI command
• Tests: N/A

Step 2: Write tests for FSM transition fix (Estimated: 45 LOC)

• python/tests/test_impl_fsm.py:
  1. Add next_stage(STAGE_REBASE, EVENT_REBASE_OK) == STAGE_REVIEW assertion
  2. Add test_rebase_ok_resets_review_counters test
  3. Add test_fsm_rebase_ok_reaches_review_then_finish orchestrator test

Dependencies: Step 1
Correspondence:

• Docs: Tests verify the documented rebase → review transition
• Tests: New transition assertion, counter reset test, orchestrator path test

Step 3: Fix FSM transition and kernel (Estimated: 5 LOC)

• python/agentize/workflow/impl/transition.py line 52: STAGE_IMPL → STAGE_REVIEW
• python/agentize/workflow/impl/kernels.py in rebase_stage_kernel(): reset review counters

# transition.py
-    (STAGE_REBASE, EVENT_REBASE_OK): STAGE_IMPL,
+    (STAGE_REBASE, EVENT_REBASE_OK): STAGE_REVIEW,

# kernels.py rebase_stage_kernel()
     if event == EVENT_REBASE_OK:
         state.iteration += 1
+        context.data["review_fail_streak"] = 0
+        context.data["review_attempts"] = 0
+        context.data["last_review_score"] = None

Dependencies: Step 2
Correspondence:

• Docs: Implements rebase → review transition documented in Step 1
• Tests: Makes Step 2 transition and counter reset tests pass

Step 4: Add Python CLI rebase handler (Estimated: 35 LOC)

• python/agentize/cli.py:
  1. Add handle_rebase(args) function (fetch + rebase + abort-on-conflict)
  2. Add rebase subparser with --target-branch argument
  3. Add dispatch case

Dependencies: None (independent of FSM changes)
Correspondence:

• Docs: Implements standalone lol rebase command
• Tests: Can be verified manually with python -m agentize.cli rebase --help

Step 5: Add shell CLI integration (Estimated: 51 LOC)

• src/cli/lol/commands/rebase.sh (new): _lol_cmd_rebase delegating to Python
• src/cli/lol/parsers.sh: Add _lol_parse_rebase with --target-branch parsing
• src/cli/lol/dispatch.sh: Add rebase) case and help text
• src/cli/lol/commands.sh: Source commands/rebase.sh
• src/cli/lol/completion.sh: Add rebase command and rebase-flags case

Dependencies: Step 4 (Python handler must exist)
Correspondence:

• Docs: Completes CLI integration documented in README
• Tests: Verifiable via lol rebase --help

Total estimated complexity: ~144 LOC (Small-Medium)
Recommended approach: Single session

Success Criteria

• (STAGE_REBASE, EVENT_REBASE_OK) routes to STAGE_REVIEW in transition table
• Review counters reset on EVENT_REBASE_OK in rebase_stage_kernel()
• lol rebase [--target-branch <branch>] works as standalone CLI command
• python -m pytest python/tests/test_impl_fsm.py -v passes with new tests
• Mermaid diagram in impl.md shows rebase → review
• Shell completion includes rebase command

Risks and Mitigations

Risk	Likelihood	Impact	Mitigation
Silent semantic conflicts after rebase go undetected by review	Low	Medium	Review stage analyzes code against requirements; add note in transition docs
rebase → review → simp → pr re-runs simp on already-simplified code	Low	Low	Simp is idempotent; running it again is harmless
User confusion between lol rebase and wt rebase	Medium	Low	Document distinction: lol rebase = direct git, wt rebase = AI-assisted
Force-push not included in standalone command	Low	Low	Deferred to future --push flag; users can run git push --force-with-lease manually

Dependencies

• Git CLI (already required by the project)
• No new external dependencies

Related PR

TBD - will be updated when PR is created