feat(core): State Integrity (Hashing) & Semantic Reviewer

[Alejandro-M-P]

Summary

Implement SHA-256 hashing to ensure the diff has not changed between START and APPLY phases, and add a mandatory Semantic Reviewer pass for COMMIT and RELEASE operations to verify message fidelity.

Problem

Currently there is no integrity check between the START and APPLY phases. The user may:

1. Generate a commit message during START
2. Modify files while waiting for confirmation
3. Apply the commit with a stale preview

Additionally, we need a reviewer pass to verify that generated messages accurately reflect the code changes, catching hallucinations or missing Breaking Changes.

Objectives

1. Implement SHA-256 hashing to ensure the diff has not changed between phases
2. Add a mandatory Semantic Reviewer pass for COMMIT and RELEASE operations
3. Ensure routine operations like BRANCH, TAG, or SWITCH skip the review to remain fast

Current State

The DiffHash field already exists in domain/plan.go but is never populated or checked:

type OperationPlan struct {
    // ... existing fields
    DiffHash string json:"diff_hash"   // Fingerprint of the diff at START time - UNUSED
}

Implementation Steps

Phase 1: Fingerprinting (START Phase)

In internal/delivery/mcp/handlers.go, during COMMIT_START or RELEASE_START:

1. Get the staged diff via git.DiffStaged()
2. Calculate SHA-256 hash of the diff content
3. Save this hash in domain.OperationPlan.DiffHash

Implementation:

import "crypto/sha256"

// In handleCommitOperation for "start" phase:
diffContent, _ := s.git.DiffStaged("")
hash := sha256.Sum256([]byte(diffContent))
plan.DiffHash = hex.EncodeToString(hash[:])

Phase 2: Integrity Check (APPLY Phase)

In the APPLY phase:

1. Recalculate the current diff hash before execution
2. Compare it with the stored DiffHash in the plan
3. If they differ, block the operation and notify the user

Implementation:

// In handleCommitOperation for "apply" phase:
currentDiff, _ := s.git.DiffStaged("")
currentHash := sha256.Sum256([]byte(currentDiff))
currentHashStr := hex.EncodeToString(currentHash[:])

if currentHashStr != plan.DiffHash {
    // Block operation, notify user
    return mcpgo.NewToolResultError(
        "Diff has changed since START. The staged files are different. " +
        "Run COMMIT_START again or use COMMIT_REGENERATE."
    ), nil
}

The user sees:

• Which files changed
• A hint to run COMMIT_START again
• Option to ABORT and restart

Phase 3: Semantic Reviewer Skill

For commit and release workflows, implement a second pass call to the LLM:

Current flow (1 pass):

DiffChunks → LLM → Commit Messages

New flow (2 passes):

DiffChunks → LLM → Commit Messages → LLM (Reviewer) → Quality Check

The reviewer:

1. Takes the generated messages + the diff
2. Checks for hallucinations (message does not match diff)
3. Checks for missing Breaking Changes
4. Verifies consistent language/style

Prompt for reviewer:

You are a code reviewer. Verify that the commit messages 
accurately reflect the changes in the diff.

Check for:
1. Hallucinations - message mentions code not in diff
2. Missing important changes - breaking changes not mentioned
3. Language consistency - same style as conventional commits

Reply with ONE of:
- APPROVED - messages are accurate
- REGENERATE: <specific feedback>

Only COMMIT and RELEASE use this pass. BRANCH, TAG, SWITCH skip it for speed.

Phase 4: Operational Filtering

Update handleGitWriteReview to bypass reviewer for fast operations:

• BRANCH_CREATE - bypass
• BRANCH_DELETE - bypass
• TAG_CREATE - bypass
• TAG_DELETE - bypass
• SWITCH - bypass

Only these use the reviewer:

• COMMIT_START/APPLY
• RELEASE_START/APPLY
• MERGE_START/APPLY

Affected Files

File	Change
internal/core/domain/plan.go	DiffHash exists, ensure field is used
internal/delivery/mcp/handlers.go	Add hashing in START, validation in APPLY
internal/workflow/commit.go	Add semantic reviewer pass
internal/workflow/release.go	Add semantic reviewer pass

Related Issues

• Depends on: feat(core): LLM Infrastructure Decoupling (Backend-Agnostic Layer) #34 (LLM Infrastructure Decoupling) - Semantic Reviewer needs an abstracted LLM port
• Related: Research: Improving Prompting & Elicitation Flow #17 (Research: Improving Prompting) - the reviewer improves prompting quality

Notes

• This is NOT about secrets scanning - that is handled by the deterministic scanner
• Only COMMIT and RELEASE operations require the reviewer
• BRANCH, TAG, SWITCH bypass it to maintain low latency

Acceptance Criteria

1. START phase calculates and stores SHA-256 hash of staged diff
2. APPLY phase validates hash before execution
3. Different hash blocks the operation with clear error message
4. Semantic Reviewer pass validates message accuracy
5. Fast operations (BRANCH, TAG, SWITCH) bypass reviewer
6. Existing workflow remains unchanged for non-review operations