fix(go-migration): apply Crane parity gate fixes

[mrjf]

fix(go-migration): apply Crane parity gate fixes

TL;DR

This PR applies the real Go-migration fixes that Crane attempted to push, without the protected workflow edits that made the safe-output step fail. It brings in the Iteration 81/82 behavior fixes, repairs the option-parity surface, and tightens the Python contract extractor so hidden Click options do not get counted as public help requirements.

Note

This is intentionally scoped to Go CLI/parity-gate files only; it does not modify .github/workflows/*, so gh aw compile is not required for this PR.

Problem (WHY)

• Crane’s failed output included protected workflow changes, so the useful Go-migration patch could not be pushed automatically.
• Several Go commands still needed real state/functional behavior from the migration branch before the deterministic cutover gate could be trusted for issue Crane Migration: Python to Go -- Full APM CLI Rewrite #78.
• The strict option gate counted hidden Python Click options as public help requirements, which conflicted with exact stdout parity for apm update --help.
• [!] The migration needs reviewer-visible, command-backed evidence rather than another “complete” label based on partial scaffolding; in PROSE terms, "Grounding outputs in deterministic tool execution transforms probabilistic generation into verifiable action."

Approach (WHAT)

#	Fix	Principle
1	Apply the Crane Iteration 81 behavior fixes for real command/state-diff contracts.	"do the work, run a validator (a script, a reference checklist, or a self-check), fix any issues, and repeat until validation passes."
2	Apply the Iteration 82 contract coverage and manifest compression changes.	"Context arrives just-in-time, not just-in-case."
3	Finish missing public option-help parity across deps, marketplace, mcp, plugin, policy, runtime, simple commands, and pack/update metadata.	"agents pattern-match well against concrete structures"
4	Record hidden Click options in the contract extractor and skip them in visible-help parity.	"Add what the agent lacks, omit what it knows"

Implementation (HOW)

• cmd/apm/cmd_config.go and cmd/apm/cmd_lockfile.go — add helper behavior needed by the state-diff contract tests so config and lockfile operations mutate/read real project files.
• cmd/apm/cmd_marketplace.go — carries the Iteration 81 marketplace remove/validate behavior plus the public help flags needed for browse/init/check/doctor/list/add parity.
• cmd/apm/cmd_mcp.go and cmd/apm/cmd_runtime.go — make mcp list and runtime remove satisfy the functional/state-diff contracts, and expose the Python CLI’s visible options.
• cmd/apm/cmd_deps.go, cmd/apm/cmd_plugin.go, cmd/apm/cmd_policy.go, cmd/apm/cmd_simple.go, cmd/apm/cmd_update.go, and cmd/apm/cmdmeta.go — close visible option parity gaps and preserve the hidden apm update --check shim behavior without advertising it in --help.
• cmd/apm/python_behavior_contracts_test.go and scripts/ci/python_behavior_contracts.py — teach the contract inventory about hidden parameters so strict option parity tests public help, not hidden Click compatibility shims.
• cmd/apm/testdata/go_cutover/python_test_coverage.json and tests/parity/python_contract_coverage.yml — refresh the Python-test-to-Go/parity mapping so the cutover gate accounts for the current Python corpus and the PR fix(crane): require up-to-date PR checks before completion #118 Crane scheduler test.

Diagrams

Legend: the diagram shows how the Crane-generated work and the final manual parity fix flow into the gates reviewers should care about first.

flowchart LR
    subgraph Crane["Crane output"]
        A["Iteration 81 behavior fixes"]
        B["Iteration 82 coverage fixes"]
    end
    subgraph GoCLI["Go CLI"]
        C["Real command state changes"]
        D["Visible option surface"]
        E["Hidden shim behavior"]
    end
    subgraph Gates["Deterministic gates"]
        F["Functional and state-diff contracts"]
        G["Python test coverage manifest"]
        H["Exact stdout and benchmark parity"]
    end
    A --> C
    B --> F
    C --> F
    D --> H
    E --> H
    F --> G
    G --> H
    classDef new stroke-dasharray: 5 5;
    class C,D,E,F,G,H new;

Loading

Trade-offs

• Human PR instead of replaying the failed bot output. Chose a clean branch from main; rejected pushing the bot patch wholesale because that patch included protected workflow files from the base merge.
• Hidden option support without visible help drift. Chose to support apm update --check in Go while omitting it from --help; rejected advertising it because Python marks the option hidden and exact stdout parity must remain authoritative.
• Manifest refresh included. Chose to include the regenerated coverage artifacts from the Crane patch; rejected hand-editing only the failing row because the gate should see the same corpus Crane generated.
• No workflow source edits. Chose not to change .github/workflows/*; the previous safe-output failure was about workflow edits, not about needing a workflow fix in this PR.

Benefits

1. go test ./cmd/apm -count=1 passes locally with APM_PYTHON_BIN set, including the completion, contract, and benchmark gates.
2. Strict option parity now tests 272 visible Python options and passes without leaking hidden Click shims into Go help.
3. Exact stdout parity for apm update --help stays aligned with Python while the hidden compatibility behavior still exists.
4. The coverage manifest accounts for the current Python test corpus, including the new Crane scheduler head-gate test from PR fix(crane): require up-to-date PR checks before completion #118.

Validation

APM_ENFORCE_COMPLETION_GATES=1 APM_PYTHON_BIN="$PWD/.venv/bin/apm" go test ./cmd/apm -run '^TestParityPythonOptionsFromSource$' -count=1

ok  	github.com/githubnext/apm/cmd/apm	6.160s

APM_PYTHON_BIN="$PWD/.venv/bin/apm" go test ./cmd/apm -run '^TestParityStdoutUpdateHelp$' -count=1

ok  	github.com/githubnext/apm/cmd/apm	1.632s

APM_PYTHON_BIN="$PWD/.venv/bin/apm" go test ./cmd/apm -count=1

ok  	github.com/githubnext/apm/cmd/apm	181.158s

Python contract and lint checks

APM_ENFORCE_PYTHON_BEHAVIOR_CONTRACTS=1 ~/.local/bin/uv run --extra dev pytest tests/parity/test_python_behavior_contracts.py::test_python_contract_coverage_manifest_is_complete -q --tb=short

.                                                                        [100%]
1 passed in 11.40s

~/.local/bin/uv run --extra dev ruff check scripts/ci/python_behavior_contracts.py

All checks passed!

git diff --check

Scenario Evidence

#	Scenario (user promise)	Principle(s)	Test(s) proving it	Type
1	Run migrated Go commands and see real project state change, not a success-shaped facade.	DevX, Governed by policy	cmd/apm/real_behavior_test.go::TestGoCutoverRealFunctionalAndStateDiffContracts	integration
2	Treat the Python test corpus as the migration checklist, with every test mapped to Go or parity coverage.	Governed by policy, OSS / community-driven	cmd/apm/go_cutover_coverage_test.go::TestGoCutoverPythonTestConversionCoverage tests/parity/test_python_behavior_contracts.py::test_python_contract_coverage_manifest_is_complete	integration
3	Show the same public CLI options as Python while keeping hidden compatibility shims hidden.	DevX	cmd/apm/python_behavior_contracts_test.go::TestParityPythonOptionsFromSource cmd/apm/parity_stdout_test.go::TestParityStdoutUpdateHelp	integration
4	Compare realistic migration benchmark scenarios before declaring the Go port complete.	DevX, Governed by policy	cmd/apm/parity_completion_test.go::TestParityCompletionBenchmarks	integration
5	Prove the Go cutover gate can run the Go fixture corpus without importing the Python CLI at runtime.	Portability by manifest, Governed by policy	cmd/apm/go_cutover_coverage_test.go::TestGoCutoverNoPythonRuntimeDependency	integration

How to test

• Run APM_PYTHON_BIN="$PWD/.venv/bin/apm" go test ./cmd/apm -count=1 and expect the package to pass.
• Run APM_ENFORCE_COMPLETION_GATES=1 APM_PYTHON_BIN="$PWD/.venv/bin/apm" go test ./cmd/apm -run '^TestParityPythonOptionsFromSource$' -count=1 and expect option parity to pass.
• Run APM_ENFORCE_PYTHON_BEHAVIOR_CONTRACTS=1 ~/.local/bin/uv run --extra dev pytest tests/parity/test_python_behavior_contracts.py::test_python_contract_coverage_manifest_is_complete -q --tb=short and expect one passing test.
• Run go run ./cmd/apm update --help and confirm --check is not shown.
• Run go run ./cmd/apm update --check and confirm the deprecated self-update shim still exits successfully.

Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com

[github-actions]

Migration Benchmark Results

• Commit: d376b93b76c7644a90d0890cbc5c717948081d95
• Run: https://github.com/githubnext/apm/actions/runs/27325744470

Migration CLI Benchmark

Includes fixture-backed commands that must read, write, execute, or fail against real project state. The installed-project fixture contains apm.yml, apm.lock.yaml, apm_modules packages, local .apm primitives, target directories, deployed prompt files, and sample source files.
The harness checks return-code parity for each command. Detailed stdout/stderr byte counts are kept in the JSON samples, but this is not an output-parity test.

Max allowed Go/Python median ratio: 5.00

Benchmark	Command	Fixture	Python median	Go median	Go/Python	Result	Return codes
init scaffold	init --yes	empty-project	0.4721s	0.0014s	0.00x	334.61x faster	{'python': [0], 'go': [0]}
targets json	targets --json	installed-project	0.4587s	0.0014s	0.00x	327.87x faster	{'python': [0], 'go': [0]}
script list	list	installed-project	0.4522s	0.0014s	0.00x	319.42x faster	{'python': [0], 'go': [0]}
deps list	deps list	installed-project	0.4548s	0.0015s	0.00x	311.78x faster	{'python': [0], 'go': [0]}
deps tree	deps tree	installed-project	0.4592s	0.0014s	0.00x	336.60x faster	{'python': [0], 'go': [0]}
install local package	install --no-policy ./packages/local-tools	local-install-project	0.4895s	0.0017s	0.00x	283.49x faster	{'python': [0], 'go': [0]}
compile copilot target	compile --target copilot	compilation-project	0.4733s	0.0015s	0.00x	319.08x faster	{'python': [0], 'go': [0]}
pack output	pack --output dist	installed-project	0.4722s	0.0014s	0.00x	326.76x faster	{'python': [0], 'go': [0]}
run script	run stamp	runnable-project	0.4473s	0.0022s	0.00x	201.64x faster	{'python': [0], 'go': [0]}
audit hidden unicode	audit --ci	audit-finding-project	0.4581s	0.0017s	0.00x	268.82x faster	{'python': [1], 'go': [1]}

Workloads

• init scaffold: Creates a new apm.yml in an otherwise empty project directory.
• targets json: Reads configured project targets from apm.yml and emits machine output.
• script list: Reads apm.yml scripts and renders the runnable script inventory.
• deps list: Scans apm_modules package directories and apm.lock.yaml metadata.
• deps tree: Builds a dependency tree from apm.lock.yaml and installed package metadata.
• install local package: Installs a local package and materializes lock/module state.
• compile copilot target: Discovers local primitives and writes the Copilot target artifact.
• pack output: Resolves local package contents and writes a distributable artifact.
• run script: Executes a project script and writes the script's side-effect file.
• audit hidden unicode: Scans a real installed file and fails on planted hidden Unicode.