feat(compat): support nested subcommand paths in Runner.WithSubcommand (#12)

Liftoff-export's data-producing leaves live two levels deep
(`liftoff-export workouts stats`, `liftoff-export bodyweights list`).
The pre-existing Runner.WithSubcommand passed the value as a single
argv entry, so a nested path arrived at cobra as one literal
"workouts stats" command name and was rejected as unknown.

Switch the internal representation to []string, split via
strings.Fields on WithSubcommand intake, and prepend each segment as
its own argv entry. Single-word callers (crono's `biometrics`,
`exercises`, ...) keep working unchanged because Fields("biometrics")
returns ["biometrics"]. The empty string still clears the path, so
the API stays reversible without an extra method.

Subcommand() returns the path joined with single spaces, which is
what callers passed in. Section bundles already use it for
t.Run("subcommand="+sub, ...) names, so nested-path failures surface
as `subcommand=workouts stats/...` subtests instead of masking.

Two new self-tests in compat_test.go lock in the split-on-whitespace
and empty-clear behaviors via the existing argecho helper:

- TestWithSubcommand_NestedPathSplitsOnWhitespace exercises the
  liftoff shape end-to-end (two segments + flag args).
- TestWithSubcommand_EmptyStringClears asserts the reset path.

README + CONTRIBUTING gain a one-paragraph note pointing partial-
codec exporters at the nested-path usage, so future onboarding
heartbeats don't trip on the same surprise.

Unblocks QUA-16 (liftoff onboarding as second consumer of
compat/formats).

Co-authored-by: LeadGoEngineer <leadgoengineer@quantcli.local>
Co-authored-by: Paperclip <noreply@paperclip.ing>

Author: 3 people

CONTRIBUTING.md

@@ -76,7 +76,7 @@ Rules:
 - Anyone changing `CONTRACT.md` is also expected to update or add tests under `compat/` that exercise the new behavior against every `*-export-cli`.
 - The harness is deliberately black-box: it shells out to the binary and asserts on stdout, stderr, and exit code only. It must not import a CLI's internal packages.
 - One subpackage per contract section. The naming convention is `compat/<section>` where `<section>` is the CONTRACT.md section being attested — currently `compat/dates` (§2–§3) and `compat/formats` (§4); `compat/auth` (§5) and `compat/prime` (§6) are expected to follow. Each subpackage exposes a single entry point — `RunContract(t, runner)` — that exporters call from one build-tagged `_test.go` file.
-- Cobra-based exporters whose contract surface lives on subcommands set `compat.Runner.Subcommands`; section bundles dispatch per-subcommand under a `subcommand=NAME/...` subtree. Flat CLIs leave the field empty and the bundle runs against the root binary.
+- Cobra-based exporters whose contract surface lives on subcommands set `compat.Runner.Subcommands`; section bundles dispatch per-subcommand under a `subcommand=NAME/...` subtree. Flat CLIs leave the field empty and the bundle runs against the root binary. Nested paths (e.g. `liftoff-export workouts stats`) are passed as a single space-separated entry — the dispatcher splits on whitespace so each segment is its own argv entry.
 - A PR that changes the contract without touching `compat/` is incomplete. Either update the tests in the same PR or open a follow-up issue and link it from the PR body before merging — the Lead Go Engineer holds the line on this.
 - Compat tests run in CI on every PR and on `main`. A failing compat test on `main` means at least one shipped CLI no longer matches the contract, and that's a release-blocker incident, not a flake.
 - The Status table in `CONTRACT.md` distinguishes **machine-attested** rows (covered by `compat/`) from **human-attested** rows (still verified by reviewer judgment). Promoting a row from human to machine attestation is itself a worthwhile PR.

compat/README.md

@@ -67,6 +67,20 @@ func TestContractDates(t *testing.T) {
 
 Each subcommand is verified under a `subcommand=NAME/...` subtree, so a regression in any single one fails as a named subtest instead of masking the rest.
 
+Nested-path subcommands are supported by passing a space-separated string. The dispatcher splits on whitespace so each segment becomes its own argv entry, which is what cobra's command tree resolves against:
+
+```go
+dates.RunContract(t, compat.Runner{
+    Binary: bin,
+    Subcommands: []string{
+        "bodyweights list", "bodyweights stats",
+        "workouts list", "workouts stats",
+    },
+})
+```
+
+This is the pattern liftoff-export uses, where `--since`/`--until` live on two-level leaves (`liftoff-export workouts stats`) rather than top-level subcommands.
+
 ### CI workflow
 
 ```yaml

compat/compat.go

@@ -18,6 +18,7 @@ import (
 	"errors"
 	"fmt"
 	"os/exec"
+	"strings"
 	"testing"
 	"time"
 )
@@ -44,6 +45,14 @@ type Runner struct {
 	// `exercises`, `nutrition`, `servings`, `notes` each accept their
 	// own --since/--until.
 	//
+	// Each entry is one space-separated subcommand path. Single-word
+	// entries like "biometrics" target a top-level subcommand; nested
+	// paths like "workouts stats" target a leaf under a parent (as in
+	// liftoff's `liftoff-export workouts stats`). The dispatcher splits
+	// on whitespace before invoking the binary, so the cobra command
+	// tree receives separate argv entries rather than one space-joined
+	// argument.
+	//
 	// Empty means the surface is on the root binary; section bundles
 	// invoke the binary directly. Non-empty means each section's
 	// RunContract iterates the list and verifies the contract once per
@@ -109,11 +118,13 @@ type Runner struct {
 	// SkipDataPath: true is the typical liftoff/crono shape today.
 	SkipDataPath bool
 
-	// subcommand, when non-empty, is prepended to args on every Run
-	// call. Set via WithSubcommand; section bundles use it to dispatch
-	// per-subcommand. Callers do not need to set it directly — set
-	// Subcommands instead and let the bundle compose the dispatch.
-	subcommand string
+	// subcommandParts, when non-empty, is prepended to args on every Run
+	// call as separate argv entries. Set via WithSubcommand from a
+	// space-separated path (e.g. "workouts stats"); section bundles use
+	// it to dispatch per-subcommand. Callers do not need to set it
+	// directly — set Subcommands instead and let the bundle compose the
+	// dispatch.
+	subcommandParts []string
 }
 
 // Result captures everything observable about one CLI invocation. All
@@ -147,8 +158,8 @@ func (r Runner) Run(ctx context.Context, args ...string) (Result, error) {
 	defer cancel()
 
 	fullArgs := args
-	if r.subcommand != "" {
-		fullArgs = append([]string{r.subcommand}, args...)
+	if len(r.subcommandParts) > 0 {
+		fullArgs = append(append([]string(nil), r.subcommandParts...), args...)
 	}
 	cmd := exec.CommandContext(runCtx, r.Binary, fullArgs...)
 	// Default to an empty env so tests are hermetic. Callers opt into
@@ -207,24 +218,33 @@ func (r Runner) WithEnv(kv ...string) Runner {
 	return out
 }
 
-// WithSubcommand returns a copy of r whose Run prepends sub as the
-// first command-line argument. Section bundles use this internally to
-// dispatch per-subcommand when Runner.Subcommands is non-empty;
-// integrators normally set Subcommands and let the bundle do it.
+// WithSubcommand returns a copy of r whose Run prepends sub as a
+// command-line path before the caller's args. Section bundles use this
+// internally to dispatch per-subcommand when Runner.Subcommands is
+// non-empty; integrators normally set Subcommands and let the bundle
+// do it.
+//
+// sub is a space-separated path: "biometrics" targets a single
+// top-level subcommand; "workouts stats" targets a leaf under a parent
+// (each whitespace-separated word becomes its own argv entry, so the
+// cobra command tree resolves them as separate names rather than one
+// space-joined argument). Leading/trailing whitespace is ignored; the
+// empty string clears any previously-set path.
 //
 // Calling WithSubcommand again replaces (not stacks) the previous
-// value; nested subcommand paths are out of scope for the current
-// contract.
+// path.
 func (r Runner) WithSubcommand(sub string) Runner {
 	out := r
-	out.subcommand = sub
+	out.subcommandParts = strings.Fields(sub)
 	return out
 }
 
-// Subcommand returns the subcommand that Run will prepend to args, or
-// the empty string if none is set. Section bundles use this in subtest
-// names so failures point at the offending subcommand.
-func (r Runner) Subcommand() string { return r.subcommand }
+// Subcommand returns the subcommand path that Run will prepend to
+// args, or the empty string if none is set. Nested paths come back
+// joined with single spaces (e.g. "workouts stats"). Section bundles
+// use this in subtest names so failures point at the offending
+// subcommand.
+func (r Runner) Subcommand() string { return strings.Join(r.subcommandParts, " ") }
 
 // SupportsFormat reports whether name is one of the §4 codecs the
 // exporter declares it implements.

compat/compat_test.go

@@ -34,6 +34,52 @@ func TestWithSubcommand_PrependsArg(t *testing.T) {
 	}
 }
 
+// TestWithSubcommand_NestedPathSplitsOnWhitespace covers liftoff-style
+// CLIs whose data-producing leaves live two levels deep
+// (e.g. `liftoff-export workouts stats`). Without the split, the cobra
+// resolver would receive one literal "workouts stats" argv entry and
+// reject it as an unknown command. The argecho-based assertion locks
+// in that each whitespace-separated word is its own argv entry, in
+// order, before the caller's args.
+func TestWithSubcommand_NestedPathSplitsOnWhitespace(t *testing.T) {
+	bin := buildArgEcho(t)
+	r := compat.Runner{Binary: bin}.WithSubcommand("workouts stats")
+
+	res, err := r.Run(context.Background(), "--format", "json")
+	if err != nil {
+		t.Fatalf("run: %v", err)
+	}
+	if res.ExitCode != 0 {
+		t.Fatalf("exit %d; stderr=%q", res.ExitCode, res.StderrString())
+	}
+	got := strings.TrimRight(res.StdoutString(), "\n")
+	want := "workouts\nstats\n--format\njson"
+	if got != want {
+		t.Errorf("argv mismatch:\n got:\n%s\nwant:\n%s", got, want)
+	}
+	if r.Subcommand() != "workouts stats" {
+		t.Errorf("Subcommand() = %q; want %q", r.Subcommand(), "workouts stats")
+	}
+}
+
+// TestWithSubcommand_EmptyStringClears asserts that passing the empty
+// string (or whitespace-only) clears any previously-set path, which
+// keeps the API reversible without an extra method.
+func TestWithSubcommand_EmptyStringClears(t *testing.T) {
+	bin := buildArgEcho(t)
+	r := compat.Runner{Binary: bin}.WithSubcommand("biometrics").WithSubcommand("")
+	if r.Subcommand() != "" {
+		t.Errorf("Subcommand() = %q; want empty after clear", r.Subcommand())
+	}
+	res, err := r.Run(context.Background(), "--help")
+	if err != nil {
+		t.Fatalf("run: %v", err)
+	}
+	if got := strings.TrimRight(res.StdoutString(), "\n"); got != "--help" {
+		t.Errorf("argv mismatch: got %q want %q", got, "--help")
+	}
+}
+
 // TestRun_NoSubcommandPassthrough checks that the default zero
 // subcommand leaves args untouched.
 func TestRun_NoSubcommandPassthrough(t *testing.T) {