Merge pull request #121 from morluto/feature/hunk-semantic-plan

feat(commitplan): add hunk-aware semantic commit planning

Author: morluto

README.md

@@ -663,6 +663,13 @@ gitcontribute tui owner/repo
 `diff` returns the patch, changed files, and suggested review order. The TUI is
 local-only; add `--json` to emit a non-interactive snapshot.
 
+MCP's `code` toolset also exposes a read-only semantic commit workflow. An
+agent first calls `workspace.inspect_commit_changes` for stable file/hunk IDs,
+then submits its proposed groups to `workspace.plan_semantic_commits`. The
+second tool verifies exact one-to-one coverage and reports ambiguous, mixed,
+generated, binary, formatting-only, and untracked changes. It does not stage or
+commit anything.
+
 </details>
 
 <details>

docs/architecture.md

@@ -455,6 +455,19 @@ Database and WAL bytes remain whole-file measurements because SQLite pages are
 shared. Logical observation-payload and code-content bytes are reported
 separately rather than attributed to individual database pages.
 
+Semantic commit preparation is a two-step local read. First,
+`workspace.inspect_commit_changes` asks Git for a binary/full-index patch and
+untracked blob identities, then uses the maintained `sourcegraph/go-diff`
+parser to expose stable file and hunk units. Second, the agent supplies semantic
+grouping judgment to `workspace.plan_semantic_commits`; deterministic code
+rejects stale inventories, unknown or duplicate unit assignments, and invalid
+dependency graphs. Ambiguous units remain explicit. A verified reconstruction
+record binds one-to-one unit coverage to the exact source patch and untracked
+content identities. Neither operation stages files, applies patches, creates
+commits, changes refs, executes repository code, or contacts GitHub. Applying a
+plan is intentionally a separate future capability with an explicit mutation
+boundary.
+
 Storage changes should include tests for upgrade behavior, rollback when
 supported, stale-write rejection, transaction atomicity, and deterministic
 query ordering.

go.mod

@@ -17,6 +17,7 @@ require (
 	github.com/modelcontextprotocol/go-sdk v1.6.1
 	github.com/pelletier/go-toml/v2 v2.4.3
 	github.com/pressly/goose/v3 v3.24.0
+	github.com/sourcegraph/go-diff v0.8.0
 	github.com/zalando/go-keyring v0.2.8
 	golang.org/x/mod v0.37.0
 	golang.org/x/sys v0.46.0

go.sum

@@ -131,6 +131,8 @@ github.com/segmentio/encoding v0.5.4 h1:OW1VRern8Nw6ITAtwSZ7Idrl3MXCFwXHPgqESYfv
 github.com/segmentio/encoding v0.5.4/go.mod h1:HS1ZKa3kSN32ZHVZ7ZLPLXWvOVIiZtyJnO1gPH1sKt0=
 github.com/sethvargo/go-retry v0.3.0 h1:EEt31A35QhrcRZtrYFDTBg91cqZVnFL2navjDrah2SE=
 github.com/sethvargo/go-retry v0.3.0/go.mod h1:mNX17F0C/HguQMyMyJxcnU471gOZGxCLyYaFyAZraas=
+github.com/sourcegraph/go-diff v0.8.0 h1:ipIyu4cTsLbIrln4l0qtHA3r0a7gyK4ntKjtQytHhvY=
+github.com/sourcegraph/go-diff v0.8.0/go.mod h1:hWlcO7Al+UZStZAP8rBumHpCK5ZHQ5BXsMls8p4+F5E=
 github.com/stretchr/objx v0.5.2 h1:xuMeJ0Sdp5ZMRXx/aWO6RZxdr3beISkG5/G/aIRr3pY=
 github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
 github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=

internal/app/commitplan.go

@@ -0,0 +1,55 @@
+package app
+
+import (
+	"context"
+	"errors"
+
+	"github.com/morluto/gitcontribute/internal/commitplan"
+)
+
+// InspectCommitChanges returns stable assignable units for a managed workspace.
+// It reads only the local worktree and Git object database.
+func (s *Service) InspectCommitChanges(ctx context.Context, workspaceID string) (commitplan.Inventory, error) {
+	return s.commitPlanInventory(ctx, workspaceID)
+}
+
+// PlanSemanticCommits validates agent-authored semantic groups against the
+// current workspace snapshot. It never stages changes or rewrites history.
+func (s *Service) PlanSemanticCommits(ctx context.Context, workspaceID, expectedInventorySHA256 string, input commitplan.PlanInput) (commitplan.Plan, error) {
+	inventory, err := s.commitPlanInventory(ctx, workspaceID)
+	if err != nil {
+		return commitplan.Plan{}, err
+	}
+	if expectedInventorySHA256 != "" && expectedInventorySHA256 != inventory.InventorySHA256 {
+		return commitplan.Plan{}, errors.New("workspace diff changed after inspection; inspect again before planning")
+	}
+	return commitplan.Build(ctx, inventory, input)
+}
+
+func (s *Service) commitPlanInventory(ctx context.Context, workspaceID string) (commitplan.Inventory, error) {
+	c, err := s.openReadOnlyCorpus(ctx)
+	if err != nil {
+		return commitplan.Inventory{}, err
+	}
+	ws, err := c.GetWorkspace(ctx, workspaceID)
+	if err != nil {
+		return commitplan.Inventory{}, mapWorkspaceError(err)
+	}
+	mgr, err := s.workspaceReader()
+	if err != nil {
+		return commitplan.Inventory{}, err
+	}
+	patch, err := mgr.DiffByPath(ctx, ws.Path, ws.BaseSHA)
+	if err != nil {
+		return commitplan.Inventory{}, err
+	}
+	untracked, err := mgr.UntrackedFilesByPath(ctx, ws.Path)
+	if err != nil {
+		return commitplan.Inventory{}, err
+	}
+	files := make([]commitplan.UntrackedFile, len(untracked))
+	for index, file := range untracked {
+		files[index] = commitplan.UntrackedFile{Path: file.Path, ObjectID: file.ObjectID}
+	}
+	return commitplan.Inspect(ctx, commitplan.Snapshot{Patch: []byte(patch), Untracked: files})
+}

internal/app/commitplan_test.go

@@ -0,0 +1,59 @@
+package app
+
+import (
+	"context"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"testing"
+
+	"github.com/morluto/gitcontribute/internal/cli"
+	"github.com/morluto/gitcontribute/internal/commitplan"
+)
+
+func TestSemanticCommitPlanUsesFrozenWorkspaceSnapshot(t *testing.T) {
+	if _, err := exec.LookPath("git"); err != nil {
+		t.Skip("git not available")
+	}
+	ctx := context.Background()
+	svc := newLocalService(t)
+	defer func() { _ = svc.Close() }()
+	remote, _, candidateSHA := setupAppGitRemote(t)
+	inv, err := svc.StartInvestigation(ctx, cli.RepoRef{Owner: "owner", Repo: "repo"}, candidateSHA, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	ws, err := svc.CreateWorkspace(ctx, inv.ID, cli.WorkspaceCreateOptions{Remote: remote, BaseRef: "master", CandidateRef: "feature", Name: "commit-plan"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(ws.Path, "untracked.txt"), []byte("proof\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	inventory, err := svc.InspectCommitChanges(ctx, ws.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(inventory.Units) < 2 {
+		t.Fatalf("inventory = %+v", inventory)
+	}
+	ids := make([]string, len(inventory.Units))
+	for index := range inventory.Units {
+		ids[index] = inventory.Units[index].ID
+	}
+	plan, err := svc.PlanSemanticCommits(ctx, ws.ID, inventory.InventorySHA256, commitplan.PlanInput{Groups: []commitplan.GroupInput{{
+		Name: "feature", Intent: "add feature", Type: "feat", UnitIDs: ids,
+	}}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !plan.Reconstruction.Verified {
+		t.Fatalf("plan = %+v", plan)
+	}
+	if err := os.WriteFile(filepath.Join(ws.Path, "changed-after-inspection.txt"), []byte("later\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := svc.PlanSemanticCommits(ctx, ws.ID, inventory.InventorySHA256, commitplan.PlanInput{}); err == nil {
+		t.Fatal("expected stale snapshot rejection")
+	}
+}

internal/app/mcp_commitplan.go

@@ -0,0 +1,81 @@
+package app
+
+import (
+	"context"
+
+	"github.com/morluto/gitcontribute/internal/commitplan"
+	"github.com/morluto/gitcontribute/internal/mcpserver"
+)
+
+// InspectCommitChanges implements the MCP commit-inventory capability.
+func (r *MCPReader) InspectCommitChanges(ctx context.Context, in mcpserver.InspectCommitChangesInput) (mcpserver.CommitInventoryOutput, error) {
+	inventory, err := r.Service.InspectCommitChanges(ctx, in.WorkspaceID)
+	if err != nil {
+		return mcpserver.CommitInventoryOutput{}, err
+	}
+	return commitInventoryToMCP(inventory), nil
+}
+
+// PlanSemanticCommits implements the MCP read-only semantic planning capability.
+func (r *MCPReader) PlanSemanticCommits(ctx context.Context, in mcpserver.PlanSemanticCommitsInput) (mcpserver.SemanticCommitPlanOutput, error) {
+	groups := make([]commitplan.GroupInput, len(in.Groups))
+	for index, group := range in.Groups {
+		groups[index] = commitplan.GroupInput{
+			Name: group.Name, Intent: group.Intent, Type: group.Type, Scope: group.Scope,
+			UnitIDs: group.UnitIDs, DependsOn: group.DependsOn,
+			ValidationCommands: group.ValidationCommands, TestOwners: group.TestOwners,
+		}
+	}
+	unresolved := make([]commitplan.UnresolvedInput, len(in.Unresolved))
+	for index, item := range in.Unresolved {
+		unresolved[index] = commitplan.UnresolvedInput{UnitID: item.UnitID, Reason: item.Reason}
+	}
+	plan, err := r.Service.PlanSemanticCommits(ctx, in.WorkspaceID, in.ExpectedInventorySHA256, commitplan.PlanInput{Groups: groups, Unresolved: unresolved})
+	if err != nil {
+		return mcpserver.SemanticCommitPlanOutput{}, err
+	}
+	return semanticCommitPlanToMCP(plan), nil
+}
+
+func commitInventoryToMCP(inventory commitplan.Inventory) mcpserver.CommitInventoryOutput {
+	out := mcpserver.CommitInventoryOutput{SourcePatchSHA256: inventory.SourcePatchSHA256, InventorySHA256: inventory.InventorySHA256}
+	for _, unit := range inventory.Units {
+		out.Units = append(out.Units, mcpserver.CommitUnitOutput{
+			ID: unit.ID, Kind: unit.Kind, Path: unit.Path, OldPath: unit.OldPath, Operation: unit.Operation,
+			OldStart: unit.OldStart, OldLines: unit.OldLines, NewStart: unit.NewStart, NewLines: unit.NewLines,
+			Patch: unit.Patch, ContentSHA256: unit.ContentHash, Generated: unit.Generated, WhitespaceOnly: unit.WhitespaceOnly,
+		})
+	}
+	out.Warnings = commitWarningsToMCP(inventory.Warnings)
+	return out
+}
+
+func semanticCommitPlanToMCP(plan commitplan.Plan) mcpserver.SemanticCommitPlanOutput {
+	out := mcpserver.SemanticCommitPlanOutput{
+		Warnings: commitWarningsToMCP(plan.Warnings),
+		Reconstruction: mcpserver.CommitReconstructionOutput{
+			SourcePatchSHA256: plan.Reconstruction.SourcePatchSHA256, InventorySHA256: plan.Reconstruction.InventorySHA256,
+			AssignedSHA256: plan.Reconstruction.AssignedSHA256, UnitCount: plan.Reconstruction.UnitCount,
+			AssignedCount: plan.Reconstruction.AssignedCount, Verified: plan.Reconstruction.Verified,
+		},
+	}
+	for _, group := range plan.Groups {
+		out.Groups = append(out.Groups, mcpserver.SemanticCommitGroupOutput{
+			Name: group.Name, Intent: group.Intent, SuggestedSubject: group.SuggestedSubject,
+			UnitIDs: group.UnitIDs, Files: group.Files, DependsOn: group.DependsOn,
+			ValidationCommands: group.ValidationCommands, TestOwners: group.TestOwners,
+		})
+	}
+	for _, item := range plan.Unresolved {
+		out.Unresolved = append(out.Unresolved, mcpserver.UnresolvedCommitUnitOutput{UnitID: item.UnitID, Reason: item.Reason})
+	}
+	return out
+}
+
+func commitWarningsToMCP(warnings []commitplan.Warning) []mcpserver.CommitPlanWarningOutput {
+	out := make([]mcpserver.CommitPlanWarningOutput, len(warnings))
+	for index, warning := range warnings {
+		out[index] = mcpserver.CommitPlanWarningOutput{Code: warning.Code, Message: warning.Message, Path: warning.Path, UnitID: warning.UnitID}
+	}
+	return out
+}

internal/commitplan/models.go

@@ -0,0 +1,109 @@
+// Package commitplan builds verifiable, read-only semantic commit plans from
+// Git-owned patches. It never stages files or changes repository history.
+package commitplan
+
+// Snapshot is the immutable input observed from one workspace.
+type Snapshot struct {
+	Patch     []byte
+	Untracked []UntrackedFile
+}
+
+// UntrackedFile identifies exact untracked content without embedding it.
+type UntrackedFile struct {
+	Path     string
+	ObjectID string
+}
+
+// Unit is the smallest assignable file or hunk change.
+type Unit struct {
+	ID             string `json:"id"`
+	Kind           string `json:"kind"`
+	Path           string `json:"path"`
+	OldPath        string `json:"old_path,omitempty"`
+	Operation      string `json:"operation"`
+	OldStart       int32  `json:"old_start,omitempty"`
+	OldLines       int32  `json:"old_lines,omitempty"`
+	NewStart       int32  `json:"new_start,omitempty"`
+	NewLines       int32  `json:"new_lines,omitempty"`
+	Patch          string `json:"patch,omitempty"`
+	ContentHash    string `json:"content_sha256"`
+	Generated      bool   `json:"generated"`
+	WhitespaceOnly bool   `json:"whitespace_only"`
+}
+
+// Warning describes a condition requiring human or agent judgment.
+type Warning struct {
+	Code    string `json:"code"`
+	Message string `json:"message"`
+	Path    string `json:"path,omitempty"`
+	UnitID  string `json:"unit_id,omitempty"`
+}
+
+// Inventory is a bounded, deterministic view of one source patch.
+type Inventory struct {
+	Units             []Unit    `json:"units"`
+	Warnings          []Warning `json:"warnings,omitempty"`
+	SourcePatchSHA256 string    `json:"source_patch_sha256"`
+	InventorySHA256   string    `json:"inventory_sha256"`
+}
+
+// GroupInput supplies semantic judgment while deterministic code verifies
+// coverage and dependencies.
+type GroupInput struct {
+	Name               string
+	Intent             string
+	Type               string
+	Scope              string
+	UnitIDs            []string
+	DependsOn          []string
+	ValidationCommands []string
+	TestOwners         []string
+}
+
+// UnresolvedInput explains why a unit cannot yet be assigned safely.
+type UnresolvedInput struct {
+	UnitID string
+	Reason string
+}
+
+// PlanInput is the agent-authored semantic layer over a frozen inventory.
+type PlanInput struct {
+	Groups     []GroupInput
+	Unresolved []UnresolvedInput
+}
+
+// Group is one proposed semantic commit.
+type Group struct {
+	Name               string   `json:"name"`
+	Intent             string   `json:"intent"`
+	SuggestedSubject   string   `json:"suggested_subject"`
+	UnitIDs            []string `json:"unit_ids"`
+	Files              []string `json:"files"`
+	DependsOn          []string `json:"depends_on,omitempty"`
+	ValidationCommands []string `json:"validation_commands,omitempty"`
+	TestOwners         []string `json:"test_owners,omitempty"`
+}
+
+// Unresolved records an unassigned or ambiguous unit.
+type Unresolved struct {
+	UnitID string `json:"unit_id"`
+	Reason string `json:"reason"`
+}
+
+// Reconstruction binds exact source bytes to one-to-one unit coverage.
+type Reconstruction struct {
+	SourcePatchSHA256 string `json:"source_patch_sha256"`
+	InventorySHA256   string `json:"inventory_sha256"`
+	AssignedSHA256    string `json:"assigned_sha256"`
+	UnitCount         int    `json:"unit_count"`
+	AssignedCount     int    `json:"assigned_count"`
+	Verified          bool   `json:"verified"`
+}
+
+// Plan is a read-only semantic proposal plus deterministic coverage proof.
+type Plan struct {
+	Groups         []Group        `json:"groups"`
+	Unresolved     []Unresolved   `json:"unresolved,omitempty"`
+	Warnings       []Warning      `json:"warnings,omitempty"`
+	Reconstruction Reconstruction `json:"reconstruction"`
+}