feat: enforce validation gates on phase/plan → resolved transition

Add internal/gate package that enforces delivery_completeness + gates
checks for phases and plan_coverage for plans when transitioning to
resolved status. Blocked transitions exit with code 2 and return
EntityUpdateGateResponse JSON.

--force flag bypasses the gate (requires --reason). Warnings are
emitted to stderr and force=true is recorded in entity history.

New files:
- internal/gate/gate.go (Enforce entry point)
- internal/gate/policy.go (transition → check mapping)
- internal/gate/report.go (Report type)
- internal/gate/gate_test.go (13 subtests)

Modified:
- internal/cli/entity.go (gate wiring + --force flag)
- internal/cli/entity_test.go (5 integration tests)
- internal/jsoncontract/responses.go (EntityUpdateGateResponse type)

Author: tyeongkim

internal/cli/entity.go

@@ -7,6 +7,7 @@ import (
 	"time"
 
 	"github.com/spf13/cobra"
+	"github.com/tyeongkim/spec-graph/internal/gate"
 	"github.com/tyeongkim/spec-graph/internal/index"
 	"github.com/tyeongkim/spec-graph/internal/jsoncontract"
 	"github.com/tyeongkim/spec-graph/internal/model"
@@ -186,6 +187,8 @@ var entityUpdateCmd = &cobra.Command{
 			handleError(cmd, err)
 		}
 
+		var oldStatus model.EntityStatus
+
 		if cmd.Flags().Changed("title") {
 			v, _ := cmd.Flags().GetString("title")
 			ef.Title = v
@@ -195,6 +198,7 @@ var entityUpdateCmd = &cobra.Command{
 			ef.Description = v
 		}
 		if cmd.Flags().Changed("status") {
+			oldStatus = ef.Status
 			v, _ := cmd.Flags().GetString("status")
 			schema := spectoml.DefaultSchema()
 			if err := schema.ValidateEntity(ef.ID, string(ef.Type), v); err != nil {
@@ -233,6 +237,87 @@ var entityUpdateCmd = &cobra.Command{
 			ef.Metadata = meta
 		}
 
+		// Gate enforcement
+		forceFlag, _ := cmd.Flags().GetBool("force")
+		if cmd.Flags().Changed("status") {
+			target := gate.Target{
+				EntityID:   id,
+				EntityType: ef.Type,
+				FromStatus: oldStatus,
+				ToStatus:   ef.Status,
+			}
+			if policy := gate.LookupPolicy(target); policy != nil {
+				efAdapter := &indexValidateEntityFetcher{idx: queryIndex}
+				rfAdapter := &validateRelationAdapter{fetcher: &indexRelationFetcher{idx: queryIndex}}
+
+				report, err := gate.Enforce(target, rfAdapter, efAdapter)
+				if err != nil {
+					handleError(cmd, fmt.Errorf("gate enforce: %w", err))
+				}
+
+				if report.Blocked {
+					if forceFlag {
+						reason, _ := cmd.Flags().GetString("reason")
+						if reason == "" {
+							handleError(cmd, &model.ErrInvalidInput{Message: "--force requires --reason"})
+						}
+						if len(report.Warnings) > 0 || len(report.BlockingIssues) > 0 {
+							allIssues := append(report.BlockingIssues, report.Warnings...)
+							warningOutput := make([]jsoncontract.ValidateIssue, len(allIssues))
+							for i, issue := range allIssues {
+								warningOutput[i] = jsoncontract.ValidateIssue{
+									Check:    issue.Check,
+									Severity: string(issue.Severity),
+									Entity:   issue.Entity,
+									Message:  issue.Message,
+								}
+							}
+							warningJSON, _ := json.Marshal(warningOutput)
+							fmt.Fprintf(os.Stderr, "%s\n", warningJSON)
+						}
+					} else {
+						issues := make([]jsoncontract.ValidateIssue, len(report.BlockingIssues))
+						for i, issue := range report.BlockingIssues {
+							issues[i] = jsoncontract.ValidateIssue{
+								Check:    issue.Check,
+								Severity: string(issue.Severity),
+								Entity:   issue.Entity,
+								Message:  issue.Message,
+							}
+						}
+						warnings := make([]jsoncontract.ValidateIssue, len(report.Warnings))
+						for i, issue := range report.Warnings {
+							warnings[i] = jsoncontract.ValidateIssue{
+								Check:    issue.Check,
+								Severity: string(issue.Severity),
+								Entity:   issue.Entity,
+								Message:  issue.Message,
+							}
+						}
+						bySeverity := make(map[string]int)
+						for _, issue := range report.BlockingIssues {
+							bySeverity[string(issue.Severity)]++
+						}
+						response := jsoncontract.EntityUpdateGateResponse{
+							Blocked:    true,
+							EntityID:   report.EntityID,
+							EntityType: string(report.EntityType),
+							FromStatus: string(report.FromStatus),
+							ToStatus:   string(report.ToStatus),
+							Issues:     issues,
+							Warnings:   warnings,
+							Summary: jsoncontract.ValidateSummary{
+								TotalIssues: len(report.BlockingIssues),
+								BySeverity:  bySeverity,
+							},
+						}
+						writeJSON(cmd, response)
+						os.Exit(2)
+					}
+				}
+			}
+		}
+
 		ef.UpdatedAt = time.Now()
 
 		if err := tomlStore.WriteEntity(ef); err != nil {
@@ -243,11 +328,16 @@ var entityUpdateCmd = &cobra.Command{
 		actor, _ := cmd.Flags().GetString("actor")
 		source, _ := cmd.Flags().GetString("source")
 
+		detail := source
+		if forceFlag {
+			detail = "force=true; " + detail
+		}
+
 		if err := tomlStore.AppendHistory(id, spectoml.HistoryEntry{
 			Action:    model.ActionUpdate,
 			Reason:    reason,
 			Actor:     actor,
-			Detail:    source,
+			Detail:    detail,
 			Timestamp: time.Now(),
 		}); err != nil {
 			handleError(cmd, fmt.Errorf("append history: %w", err))
@@ -469,6 +559,7 @@ func init() {
 	entityUpdateCmd.Flags().String("reason", "", "reason for update")
 	entityUpdateCmd.Flags().String("actor", "", "actor performing the change")
 	entityUpdateCmd.Flags().String("source", "", "source of the change")
+	entityUpdateCmd.Flags().Bool("force", false, "bypass gate checks (requires --reason)")
 
 	entityDeprecateCmd.Flags().String("reason", "", "reason for deprecation")
 	entityDeprecateCmd.Flags().String("actor", "", "actor performing the change")

internal/cli/entity_test.go

@@ -595,3 +595,174 @@ func TestEntityFullLifecycle(t *testing.T) {
 		t.Fatalf("expected exit 1 after delete, got %d", r.exitCode)
 	}
 }
+
+func setupGatedPhaseWithUnresolvedQuestion(t *testing.T, dir, dbFile string) {
+	t.Helper()
+	cmds := [][]string{
+		{"--db", dbFile, "entity", "add", "--type", "phase", "--id", "PHS-001", "--title", "Phase 1", "--status", "active"},
+		{"--db", dbFile, "entity", "add", "--type", "question", "--id", "QST-001", "--title", "Unresolved question", "--status", "active"},
+		{"--db", dbFile, "relation", "add", "--from", "PHS-001", "--to", "QST-001", "--type", "covers"},
+	}
+	for _, args := range cmds {
+		r := runCLI(t, dir, args...)
+		if r.exitCode != 0 {
+			t.Fatalf("setup failed (%v): exit=%d stderr=%s", args, r.exitCode, r.stderr)
+		}
+	}
+}
+
+func TestGateBlocksPhaseResolution(t *testing.T) {
+	dbFile := initTestProject(t)
+	dir := t.TempDir()
+	setupGatedPhaseWithUnresolvedQuestion(t, dir, dbFile)
+
+	r := runCLI(t, dir, "--db", dbFile, "entity", "update", "PHS-001", "--status", "resolved")
+	if r.exitCode != 2 {
+		t.Fatalf("expected exit 2 (gate blocked), got %d; stdout=%s stderr=%s", r.exitCode, r.stdout, r.stderr)
+	}
+
+	var resp jsoncontract.EntityUpdateGateResponse
+	if err := json.Unmarshal([]byte(r.stdout), &resp); err != nil {
+		t.Fatalf("unmarshal gate response: %v\nraw: %s", err, r.stdout)
+	}
+	if !resp.Blocked {
+		t.Error("expected blocked=true")
+	}
+	if resp.EntityID != "PHS-001" {
+		t.Errorf("entity_id = %q; want PHS-001", resp.EntityID)
+	}
+	if resp.EntityType != "phase" {
+		t.Errorf("entity_type = %q; want phase", resp.EntityType)
+	}
+	if resp.FromStatus != "active" {
+		t.Errorf("from_status = %q; want active", resp.FromStatus)
+	}
+	if resp.ToStatus != "resolved" {
+		t.Errorf("to_status = %q; want resolved", resp.ToStatus)
+	}
+	if len(resp.Issues) == 0 {
+		t.Fatal("expected at least one blocking issue")
+	}
+	foundGatesIssue := false
+	for _, iss := range resp.Issues {
+		if iss.Check == "gates" && iss.Entity == "QST-001" {
+			foundGatesIssue = true
+			break
+		}
+	}
+	if !foundGatesIssue {
+		t.Errorf("expected gates issue for QST-001; got issues: %+v", resp.Issues)
+	}
+	if resp.Summary.TotalIssues < 1 {
+		t.Errorf("summary.total_issues = %d; want >= 1", resp.Summary.TotalIssues)
+	}
+}
+
+func TestGateForceBypassWithReason(t *testing.T) {
+	dbFile := initTestProject(t)
+	dir := t.TempDir()
+	setupGatedPhaseWithUnresolvedQuestion(t, dir, dbFile)
+
+	r := runCLI(t, dir, "--db", dbFile, "entity", "update", "PHS-001",
+		"--status", "resolved", "--force", "--reason", "override for testing")
+	if r.exitCode != 0 {
+		t.Fatalf("expected exit 0 (force bypass), got %d; stdout=%s stderr=%s", r.exitCode, r.stdout, r.stderr)
+	}
+
+	var resp jsoncontract.EntityResponse
+	if err := json.Unmarshal([]byte(r.stdout), &resp); err != nil {
+		t.Fatalf("unmarshal entity response: %v\nraw: %s", err, r.stdout)
+	}
+	if resp.Entity.ID != "PHS-001" {
+		t.Errorf("entity.id = %q; want PHS-001", resp.Entity.ID)
+	}
+	if resp.Entity.Status != model.EntityStatusResolved {
+		t.Errorf("entity.status = %q; want resolved", resp.Entity.Status)
+	}
+
+	if r.stderr == "" {
+		t.Fatal("expected warnings on stderr")
+	}
+	var warnings []jsoncontract.ValidateIssue
+	if err := json.Unmarshal([]byte(r.stderr), &warnings); err != nil {
+		t.Fatalf("unmarshal stderr warnings: %v\nraw: %s", err, r.stderr)
+	}
+	if len(warnings) == 0 {
+		t.Error("expected at least one warning in stderr")
+	}
+}
+
+func TestGateForceWithoutReasonFails(t *testing.T) {
+	dbFile := initTestProject(t)
+	dir := t.TempDir()
+	setupGatedPhaseWithUnresolvedQuestion(t, dir, dbFile)
+
+	r := runCLI(t, dir, "--db", dbFile, "entity", "update", "PHS-001",
+		"--status", "resolved", "--force")
+	if r.exitCode != 3 {
+		t.Fatalf("expected exit 3 (INVALID_INPUT), got %d; stdout=%s stderr=%s", r.exitCode, r.stdout, r.stderr)
+	}
+
+	var errResp jsoncontract.ErrorResponse
+	if err := json.Unmarshal([]byte(r.stderr), &errResp); err != nil {
+		t.Fatalf("unmarshal error response: %v\nraw: %s", err, r.stderr)
+	}
+	if errResp.Error.Code != "INVALID_INPUT" {
+		t.Errorf("error.code = %q; want INVALID_INPUT", errResp.Error.Code)
+	}
+}
+
+func TestGateNotAppliedForNonResolvedTransition(t *testing.T) {
+	dbFile := initTestProject(t)
+	dir := t.TempDir()
+
+	setupGatedPhaseWithUnresolvedQuestion(t, dir, dbFile)
+
+	r := runCLI(t, dir, "--db", dbFile, "entity", "update", "PHS-001", "--status", "draft")
+	if r.exitCode != 0 {
+		t.Fatalf("expected exit 0 for non-gated transition, got %d; stdout=%s stderr=%s", r.exitCode, r.stdout, r.stderr)
+	}
+
+	var resp jsoncontract.EntityResponse
+	if err := json.Unmarshal([]byte(r.stdout), &resp); err != nil {
+		t.Fatalf("unmarshal: %v\nraw: %s", err, r.stdout)
+	}
+	if resp.Entity.Status != model.EntityStatusDraft {
+		t.Errorf("status = %q; want draft", resp.Entity.Status)
+	}
+}
+
+func TestGatePassesWhenNoIssues(t *testing.T) {
+	dbFile := initTestProject(t)
+	dir := t.TempDir()
+
+	cmds := [][]string{
+		{"--db", dbFile, "entity", "add", "--type", "phase", "--id", "PHS-001", "--title", "Phase 1", "--status", "active"},
+		{"--db", dbFile, "entity", "add", "--type", "question", "--id", "QST-001", "--title", "Resolved question", "--status", "active"},
+		{"--db", dbFile, "entity", "add", "--type", "decision", "--id", "DEC-001", "--title", "Answer", "--status", "active"},
+		{"--db", dbFile, "relation", "add", "--from", "PHS-001", "--to", "QST-001", "--type", "covers"},
+		{"--db", dbFile, "relation", "add", "--from", "DEC-001", "--to", "QST-001", "--type", "answers"},
+	}
+	for _, args := range cmds {
+		r := runCLI(t, dir, args...)
+		if r.exitCode != 0 {
+			t.Fatalf("setup failed (%v): exit=%d stderr=%s", args, r.exitCode, r.stderr)
+		}
+	}
+
+	r := runCLI(t, dir, "--db", dbFile, "entity", "update", "PHS-001", "--status", "resolved")
+	if r.exitCode != 0 {
+		t.Fatalf("expected exit 0 (gate passes), got %d; stdout=%s stderr=%s", r.exitCode, r.stdout, r.stderr)
+	}
+
+	var resp jsoncontract.EntityResponse
+	if err := json.Unmarshal([]byte(r.stdout), &resp); err != nil {
+		t.Fatalf("unmarshal: %v\nraw: %s", err, r.stdout)
+	}
+	if resp.Entity.ID != "PHS-001" {
+		t.Errorf("entity.id = %q; want PHS-001", resp.Entity.ID)
+	}
+	if resp.Entity.Status != model.EntityStatusResolved {
+		t.Errorf("entity.status = %q; want resolved", resp.Entity.Status)
+	}
+}