g3/g3-plan/completed_requirements_2025-12-10_16-55-05.md

{{CURRENT REQUIREMENTS}}

These requirements refine planner history handling in g3-planner, focusing on ensuring that planner_history.txt consistently records git commit entries before the actual git commit is executed, and on understanding how this invariant was previously lost.

1. Guarantee GIT COMMIT History Entry Precedes the Commit

Goal: In planning mode, every successful git commit initiated by the planner must have a corresponding GIT COMMIT (<MESSAGE>) line written to <codepath>/g3-plan/planner_history.txt before the commit is attempted.

Current behavior (as of this revision):

• crates/g3-planner/src/planner.rs, function stage_and_commit() already contains:
  • A call to history::write_git_commit(&config.plan_dir(), summary)?; immediately before calling git::commit(&config.codepath, summary, description)?;
• This matches the intended ordering, but a previous version had the history write after the commit. That bug was later “fixed” and then reintroduced once during refactors.

Required behavior:

1. Treat the ordering as a strict invariant for all planner-driven commits:
   • planner_history.txt must always be updated with a GIT COMMIT (<MESSAGE>) line before calling any function that performs the actual git commit.
2. If the commit fails (e.g. git returns error), the GIT COMMIT history entry must still remain in planner_history.txt to reflect the attempted commit.
3. The summary string written to history must match the actual commit summary used in git::commit().

Acceptance criteria:

• Static inspection: in stage_and_commit() (and in any future helper functions that might wrap it), the call order is unambiguous and there is no path where git::commit can run without the preceding write_git_commit call.
• Behavioral: in a test/planning run, intentionally cause the commit to fail (e.g. by breaking git config) and verify that:
  • A new GIT COMMIT (<MESSAGE>) line appears in planner_history.txt.
  • No commit is created in git.

2. Identify How the Ordering Bug Was Previously Undone

Goal: Understand how the previously-correct ordering was lost so that future changes avoid reintroducing the same bug.

Investigation requirements:

1. Use git history to find the commit that originally moved history::write_git_commit to after git::commit inside stage_and_commit():
   • Search for changes to crates/g3-planner/src/planner.rs, function stage_and_commit.
   • Identify the commit SHA, author, and commit message where the order became incorrect.
2. Identify the later commit that restored the correct order (writing history before commit):
   • Record the SHA and message for the fix.
3. Summarize in one short paragraph (kept outside of the code, e.g. in a planning note or as a comment in planner_history.txt via a dedicated entry) why the ordering regressed. Possible root causes to look for:
   • Refactorings that moved staging/commit logic but did not preserve history semantics.
   • Changes that tried to “simplify” logging and accidentally rearranged calls.
   • Copy‑paste from an older version of stage_and_commit.

Output expectations (for the human operator, not the code):

• A concise explanation along the lines of:
  • “Commit <SHA1> refactored stage_and_commit and inadvertently moved write_git_commit after git::commit. Commit <SHA2> later corrected this by restoring the original order. The regression was caused by copying the older implementation from <file/branch> without re‑applying the earlier fix.”

3. Guardrails to Prevent Future Regression

Goal: Make it harder to accidentally reintroduce the wrong ordering of history vs. commit.

Required changes:

1. Add a short, explicit comment directly above the write_git_commit call in stage_and_commit() explaining the ordering requirement, for example:
   • // IMPORTANT: Write GIT COMMIT entry to planner_history BEFORE actually running git commit.
   • // This is relied on for audit trail and for post‑mortem analysis when commits fail.
2. Add a lightweight test around stage_and_commit() (or a thin wrapper) that asserts the intended behavior at a higher level, such as:
   • Using a fake or test double for git::commit and history::write_git_commit to ensure write_git_commit is invoked first.
   • This test should live in crates/g3-planner/tests/ and not depend on a real git repo.
3. Document the invariant in planner‑mode requirements (this document) so that future requirement refinements and implementations continue to emphasize:
   • “Always write GIT COMMIT (<MESSAGE>) to planner_history.txt before performing the actual git commit.”

---

{{ORIGINAL USER REQUIREMENTS -- THIS SECTION WILL BE IGNORED BY THE IMPLEMENTATION}}

The bug you previously fixed has reappeared. Make SURE the "COMMIT" line to the planner_history is added BEFORE you make the commit.

Check the history for the previous fix, and identify why the fix was undone?