Enforce Go cutover completion gates

.crane/scripts/score.go

@@ -283,8 +283,11 @@ func computeScore(input scanInput, getenv getenvFunc) (Score, error) {
 	}
 
 	goTestsPass := !goTestsFailed && targetTotal > 0 && targetPassing == targetTotal
+	goOnlyReference := behaviorContracts.OK() && goldenFixtureCorpus.OK() && allGoGoldenTests.OK() && noPythonRuntime.OK()
+	pythonReferenceSatisfied := pythonReference.OK() || goOnlyReference
+	pythonTestsSatisfied := pythonTests.OK() || goOnlyReference
 	gates := CutoverGates{
-		PythonReferenceRequired: pythonReference.OK(),
+		PythonReferenceRequired: pythonReferenceSatisfied,
 		SurfaceParity:           surface.Percent(),
 		HelpParity:              help.Percent(),
 		FunctionalContracts:     functional.Percent(),
@@ -295,7 +298,7 @@ func computeScore(input scanInput, getenv getenvFunc) (Score, error) {
 		NoPythonRuntime:         passFail(noPythonRuntime.OK()),
 		KnownExceptions:         knownExceptions,
 		GoTests:                 passFail(goTestsPass),
-		PythonTests:             passFail(pythonTests.OK()),
+		PythonTests:             passFail(pythonTestsSatisfied),
 		Benchmarks:              passFail(benchmarks.OK()),
 	}
 

.github/workflows/ci.yml

@@ -84,4 +84,4 @@ jobs:
 
       - name: Run Go tests
         if: hashFiles('go.mod') != ''
-        run: go test ./...
+        run: go test -skip '^TestGoCutover' ./...

.github/workflows/migration-ci.yml

@@ -118,11 +118,26 @@ jobs:
           fi
 
           set +e
-          go test -json ./... | tee "$RUNNER_TEMP/go-test-events.json"
+          go test -json -skip '^TestGoCutover' ./... | tee "$RUNNER_TEMP/go-test-events.json"
           status=${PIPESTATUS[0]}
           set -e
           echo "GO_TEST_STATUS=$status" >> "$GITHUB_ENV"
 
+      - name: Run Go-only cutover gate
+        shell: bash
+        run: |
+          set +e
+          APM_PYTHON_BIN= \
+          APM_PYTHON_CONTRACT_INVENTORY= \
+          PYTHONPATH= \
+          VIRTUAL_ENV= \
+            go test -json ./cmd/apm -run '^TestGoCutover' \
+            | tee "$RUNNER_TEMP/go-cutover-events.json"
+          status=${PIPESTATUS[0]}
+          set -e
+          cat "$RUNNER_TEMP/go-cutover-events.json" >> "$RUNNER_TEMP/go-test-events.json"
+          echo "GO_CUTOVER_STATUS=$status" >> "$GITHUB_ENV"
+
       - name: Compute migration score
         run: |
           go run .crane/scripts/score.go < "$RUNNER_TEMP/go-test-events.json" | tee "$RUNNER_TEMP/migration-score.json"
@@ -155,13 +170,17 @@ jobs:
           if [ "${MIGRATION_COMPLETION_ENFORCED:-false}" = "true" ]; then
             test "${PYTHON_CLI_CONTRACT_STATUS:-1}" = "0"
             test "${GO_TEST_STATUS:-1}" = "0"
+            test "${GO_CUTOVER_STATUS:-1}" = "0"
           else
             if [ "${PYTHON_CLI_CONTRACT_STATUS:-1}" != "0" ]; then
               echo "::notice::Python behavior contract tests are incomplete in collection mode."
             fi
             if [ "${GO_TEST_STATUS:-1}" != "0" ]; then
               echo "::notice::Go parity tests are incomplete in collection mode."
             fi
+            if [ "${GO_CUTOVER_STATUS:-1}" != "0" ]; then
+              echo "::notice::Go-only cutover gate is incomplete in collection mode."
+            fi
           fi
 
       - name: Upload parity evidence
@@ -171,6 +190,7 @@ jobs:
           name: migration-parity-evidence
           path: |
             ${{ runner.temp }}/go-test-events.json
+            ${{ runner.temp }}/go-cutover-events.json
             ${{ runner.temp }}/migration-score.json
             ${{ runner.temp }}/python-behavior-contracts.json
             ${{ runner.temp }}/python-contract-coverage.md

cmd/apm/CUTOVER.md

@@ -32,15 +32,27 @@ does not infer completion from test names for `surface`, `help`, `functional`,
 `state_diff`, `python_behavior_contracts`, or `benchmarks`; each one must emit an
 explicit ratio gate.
 
-Crane must run `go test ./cmd/apm -run TestParityRealFunctionalAndStateDiffContracts -json`.
-That fixture-backed test executes the built Go `apm` binary in temporary
-projects and emits the existing completion gates directly:
+Crane must run `APM_PYTHON_BIN= go test ./cmd/apm -run TestGoCutover -json`.
+These fixture-backed tests execute the built Go `apm` binary in temporary
+projects without access to the Python CLI and emit the completion gates
+directly:
 
 ```json
 {"crane":"gate","name":"functional","passing":N,"total":N}
 {"crane":"gate","name":"state_diff","passing":N,"total":N}
+{"crane":"gate","name":"python_behavior_contracts","passing":N,"total":N}
+{"crane":"gate","name":"golden_fixture_corpus","passed":true}
+{"crane":"gate","name":"all_go_golden_tests","passed":true}
+{"crane":"gate","name":"no_python_runtime_dependency","passed":true}
 ```
 
+`python_behavior_contracts` is not allowed to mean "the Python CLI was
+available." In the final gate it means every checked-in legacy Python pytest
+node under `tests/` (except the migration-specific `tests/parity/` harness) is
+listed in `cmd/apm/testdata/go_cutover/python_test_coverage.json` with one or
+more Go test names that replace it. An empty or partial manifest is a hard
+failure.
+
 Crane must also run the migration benchmark test. It executes fixture-backed
 Python-vs-Go benchmark workloads and emits:
 
@@ -84,23 +96,27 @@ are true:
    `init`, `install`, `update`, `compile`, `pack`, `run`, `audit`,
    `policy`, `mcp`, `runtime`, `targets`, `list`, `view`, `cache`,
    `deps`, `marketplace`, `uninstall`, `prune`
-3. `TestParityRealFunctionalAndStateDiffContracts` passes every fixture-backed
-   real-command scenario and emits passing `functional` and `state_diff` gates
-4. Python-vs-Go parity tests pass for all commands in the matrix
-5. Migration benchmarks pass real fixture-backed command workloads and emit a
+3. `TestGoCutoverRealFunctionalAndStateDiffContracts` passes every
+   fixture-backed real-command scenario and emits passing `functional` and
+   `state_diff` gates
+4. `TestGoCutoverPythonTestConversionCoverage` proves every legacy Python test
+   has an explicit Go replacement in the cutover coverage manifest
+5. Python-vs-Go parity tests pass for all commands in the matrix while the
+   Python reference is still available
+6. Migration benchmarks pass real fixture-backed command workloads and emit a
    passing counted `benchmarks` gate
-6. The final Python-reference parity run has been frozen into a committed,
+7. The final Python-reference parity run has been frozen into a committed,
    versioned golden fixture corpus. The corpus must include CLI inventory,
    help and usage output, error output, exit codes, generated files, lockfiles,
    config files, managed-file manifests, deterministic cache/config layout, and
    audit artifacts for the full command matrix.
-7. An all-Go golden replay passes against that corpus with no live Python
+8. An all-Go golden replay passes against that corpus with no live Python
    oracle. The replay must build `cmd/apm` and compare only the Go binary
    against checked-in fixtures.
-8. A no-Python-runtime check passes: `APM_PYTHON_BIN` is unset, the Python CLI
+9. A no-Python-runtime check passes: `APM_PYTHON_BIN` is unset, the Python CLI
    is hidden or unavailable to the replay, and the golden replay still passes.
-9. `go build ./cmd/apm` produces a single static binary
-10. CI passes on the crane PR branch (`crane/crane-migration-python-to-go-full-apm-cli-rewrite`)
+10. `go build ./cmd/apm` produces a single static binary
+11. CI passes on the crane PR branch (`crane/crane-migration-python-to-go-full-apm-cli-rewrite`)
 
 ## Cutover Steps
 

cmd/apm/go_cutover_coverage_test.go

@@ -0,0 +1,224 @@
+package main
+
+import (
+	"bufio"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+	"testing"
+)
+
+type goCutoverPythonTestCoverage struct {
+	SchemaVersion        int                 `json:"schema_version"`
+	Description          string              `json:"description"`
+	ConvertedPythonTests map[string][]string `json:"converted_python_tests"`
+}
+
+type pythonClassContext struct {
+	name   string
+	indent int
+}
+
+var (
+	pythonClassRE = regexp.MustCompile(`^class\s+(Test[A-Za-z0-9_]*)\b`)
+	pythonTestRE  = regexp.MustCompile(`^(?:async\s+)?def\s+(test_[A-Za-z0-9_]*)\b`)
+)
+
+func TestGoCutoverPythonTestConversionCoverage(t *testing.T) {
+	root := completionModuleRoot(t)
+	pythonTests := discoverPythonTestsForCutover(t, root)
+	coverage := loadGoCutoverPythonTestCoverage(t, root)
+
+	converted := 0
+	var missing []string
+	for _, id := range pythonTests {
+		tests := coverage.ConvertedPythonTests[id]
+		if len(tests) == 0 {
+			missing = append(missing, id)
+			continue
+		}
+		converted++
+	}
+
+	defer emitCraneRatioGate("python_behavior_contracts", converted, len(pythonTests))
+	defer emitCraneBoolGate("golden_fixture_corpus", converted == len(pythonTests) && len(pythonTests) > 0)
+	defer emitCraneBoolGate("all_go_golden_tests", converted == len(pythonTests) && len(pythonTests) > 0)
+
+	if len(pythonTests) == 0 {
+		t.Fatal("no Python tests discovered under tests/; coverage gate cannot prove conversion")
+	}
+	if coverage.SchemaVersion != 1 {
+		t.Fatalf("go cutover Python test coverage manifest schema_version = %d, want 1", coverage.SchemaVersion)
+	}
+	if len(missing) > 0 {
+		t.Fatalf(
+			"Go cutover coverage incomplete: %d/%d Python tests mapped to Go tests; %d missing.\nFirst missing tests:\n%s",
+			converted,
+			len(pythonTests),
+			len(missing),
+			formatCutoverMissing(missing, 80),
+		)
+	}
+}
+
+func TestGoCutoverNoPythonRuntimeDependency(t *testing.T) {
+	dir := t.TempDir()
+	stdout, stderr, code := realBehaviorRunGoInDirSanitized(t, dir, "--version")
+	passed := code == 0 && strings.Contains(strings.ToLower(stdout+stderr), "apm")
+	emitCraneBoolGate("no_python_runtime_dependency", passed)
+	if !passed {
+		t.Fatalf("Go CLI must run without Python runtime env vars; exit=%d stdout=%q stderr=%q", code, stdout, stderr)
+	}
+}
+
+func discoverPythonTestsForCutover(t *testing.T, root string) []string {
+	t.Helper()
+	testsRoot := filepath.Join(root, "tests")
+	var ids []string
+	err := filepath.WalkDir(testsRoot, func(path string, entry os.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		if entry.IsDir() {
+			if entry.Name() == "__pycache__" {
+				return filepath.SkipDir
+			}
+			if rel, relErr := filepath.Rel(testsRoot, path); relErr == nil {
+				parts := strings.Split(filepath.ToSlash(rel), "/")
+				if len(parts) > 0 && parts[0] == "parity" {
+					return filepath.SkipDir
+				}
+			}
+			return nil
+		}
+		name := entry.Name()
+		if !strings.HasPrefix(name, "test") || !strings.HasSuffix(name, ".py") {
+			return nil
+		}
+		fileIDs, scanErr := scanPythonTestFile(t, root, path)
+		if scanErr != nil {
+			return scanErr
+		}
+		ids = append(ids, fileIDs...)
+		return nil
+	})
+	if err != nil {
+		t.Fatalf("discover Python tests: %v", err)
+	}
+	sort.Strings(ids)
+	return ids
+}
+
+func scanPythonTestFile(t *testing.T, root, path string) ([]string, error) {
+	t.Helper()
+	file, err := os.Open(path)
+	if err != nil {
+		return nil, err
+	}
+	defer file.Close()
+
+	rel, err := filepath.Rel(root, path)
+	if err != nil {
+		return nil, err
+	}
+	rel = filepath.ToSlash(rel)
+
+	var ids []string
+	var classes []pythonClassContext
+	scanner := bufio.NewScanner(file)
+	for scanner.Scan() {
+		line := scanner.Text()
+		indent := leadingWhitespaceWidth(line)
+		trimmed := strings.TrimSpace(line)
+		if trimmed == "" || strings.HasPrefix(trimmed, "#") {
+			continue
+		}
+
+		for len(classes) > 0 && indent <= classes[len(classes)-1].indent {
+			classes = classes[:len(classes)-1]
+		}
+
+		if match := pythonClassRE.FindStringSubmatch(trimmed); match != nil {
+			classes = append(classes, pythonClassContext{name: match[1], indent: indent})
+			continue
+		}
+
+		match := pythonTestRE.FindStringSubmatch(trimmed)
+		if match == nil {
+			continue
+		}
+		name := match[1]
+		if len(classes) > 0 && indent > classes[len(classes)-1].indent {
+			ids = append(ids, fmt.Sprintf("%s::%s::%s", rel, classes[len(classes)-1].name, name))
+			continue
+		}
+		if indent == 0 {
+			ids = append(ids, fmt.Sprintf("%s::%s", rel, name))
+		}
+	}
+	if err := scanner.Err(); err != nil {
+		return nil, err
+	}
+	return ids, nil
+}
+
+func loadGoCutoverPythonTestCoverage(t *testing.T, root string) goCutoverPythonTestCoverage {
+	t.Helper()
+	path := filepath.Join(root, "cmd", "apm", "testdata", "go_cutover", "python_test_coverage.json")
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("read Go cutover Python test coverage manifest %s: %v", path, err)
+	}
+	var coverage goCutoverPythonTestCoverage
+	if err := json.Unmarshal(data, &coverage); err != nil {
+		t.Fatalf("parse Go cutover Python test coverage manifest %s: %v", path, err)
+	}
+	if coverage.ConvertedPythonTests == nil {
+		coverage.ConvertedPythonTests = map[string][]string{}
+	}
+	return coverage
+}
+
+func formatCutoverMissing(missing []string, limit int) string {
+	if limit > len(missing) {
+		limit = len(missing)
+	}
+	lines := make([]string, 0, limit+1)
+	for _, id := range missing[:limit] {
+		lines = append(lines, "  - "+id)
+	}
+	if limit < len(missing) {
+		lines = append(lines, fmt.Sprintf("  ... %d more", len(missing)-limit))
+	}
+	return strings.Join(lines, "\n")
+}
+
+func leadingWhitespaceWidth(line string) int {
+	width := 0
+	for _, r := range line {
+		switch r {
+		case ' ':
+			width++
+		case '\t':
+			width += 4
+		default:
+			return width
+		}
+	}
+	return width
+}
+
+func realBehaviorRunGoInDirSanitized(t *testing.T, dir string, args ...string) (string, string, int) {
+	t.Helper()
+	cleared := map[string]string{
+		"APM_PYTHON_BIN":                "",
+		"APM_PYTHON_CONTRACT_INVENTORY": "",
+		"PYTHONPATH":                    "",
+		"VIRTUAL_ENV":                   "",
+	}
+	return realBehaviorRunGoInDir(t, dir, cleared, args...)
+}