myxce/.kiro/specs/eliminate-frontend-makefile/research.md

Summary

• Feature: eliminate-frontend-makefile
• Discovery Scope: Extension (existing build system, light discovery — brief.md's own Path C investigation already covered most of the ground; this pass verified currency and filled architecture-level gaps)
• Key Findings:
  • Only one live automated caller of src/frontend/Makefile exists today: xce-build.sh's two cd frontend && make test call sites (apiserver and all cases). build-cli/build-server/test-backend/test-integration have no live automated caller — they are developer-manual-only.
  • apiserver/meson.build already computes the exact CGO flags (apiserver_cgo_deps: librtti, c-capnproto, openssl, tinylog, math, rt) the Makefile's test-backend independently re-derives via pkg-config. A shared derivation is directly reusable for a new test() target — no new mechanism needed.
  • xcecli's case in xce-build.sh already bypasses Make entirely (direct go test invocation) — this is a live, working precedent for the apiserver unit-test migration, not a hypothetical pattern.
  • run-resource-verify.sh already has an established $BUILD_DIR/<component>/<binary> discovery convention for its other three binaries (BINARY, SCHED_BIN, XT); only APISERVER_BIN is the odd one out still hardcoded to /tmp/apiserver.
  • tests/regression/run.sh is already a standalone, fully-parameterized script (XCE/URL env vars). The Makefile's test-integration target added zero logic beyond an env-var rename (XCE_BIN→XCE, SRV_URL→URL) plus a build-cli prerequisite. No new script is needed for Requirement 4 — only documentation of the direct invocation.

Research Log

Live automation dependency surface

• Context: requirements.md's Boundary Context needed to state precisely what currently depends on the Makefile, to scope the coverage-preservation requirements accurately.
• Sources Consulted: grep -rn --include="*.sh" -E '\bmake\b' src/tools/ .claude/skills/, direct read of xce-build.sh lines 255-328.
• Findings: Exactly 2 live make invocations exist in the whole repo's live automation (xce-build.sh:275, :322, both cd frontend && make test). deploy-ha.sh and run-resource-verify.sh reference the Makefile only in human-facing strings (error/log messages) or by checking for its output path, never by executing make.
• Implications: The coverage-preservation requirements (2, 3, 4) protect manual developer workflows and documentation accuracy, not any existing automated pipeline — this made scope smaller and safer than it might first appear, and confirmed as a direct answer to a user clarifying question during the requirements phase.

CGO backend test flag derivation reuse

• Context: requirements.md 3.2 requires the new backend test path to derive CGO flags from "the same single source" as Meson's existing apiserver build, not a second independent derivation (the exact failure mode this whole spec exists to eliminate).
• Sources Consulted: apiserver/meson.build (full read), src/meson.build (go_compiler = find_program('go'), pkgconfig = find_program('pkg-config')), src/frontend/Makefile's own test-backend recipe (FRONTEND_CGO_PKGS := librtti c-capnproto openssl tinylog, -lm -lrt).
• Findings: apiserver/meson.build's apiserver_cgo_deps loop already produces cgo_cflags/cgo_ldflags covering the identical dependency set the Makefile independently re-derives via pkg-config. go_compiler (the raw go program object) is already available at top-level scope — no new find_program() call needed.
• Implications: A new test() in the same file can read the same cgo_cflags/cgo_ldflags variables the existing custom_target already computes — genuinely one derivation, not two, satisfying 3.2 directly rather than by convention/discipline.

run-resource-verify.sh's own established discovery pattern

• Context: requirements.md 5.1-5.3 needed a concrete replacement for run-resource-verify.sh's /tmp/apiserver default.
• Sources Consulted: full grep of _BIN=/BUILD_DIR in run-resource-verify.sh.
• Findings: BINARY, SCHED_BIN, XT already resolve as "${ENV_VAR_OVERRIDE:-$BUILD_DIR/<component>/<binary>}", each independently overridable, with $BUILD_DIR defaulting to $REPO/src/xce.build. Only APISERVER_BIN deviates, hardcoded to /tmp/apiserver with no $BUILD_DIR-relative default at all.
• Implications: the correct fix is not "mirror deploy-ha.sh's dual-path pattern" as brief.md's Downstream section literally suggested, but "match this script's own sibling convention exactly" — see Design Decision below.

Architecture Pattern Evaluation

Option	Description	Strengths	Risks / Limitations	Notes
Meson test() reusing apiserver_cgo_deps	New backend test target shares the existing custom_target's CGO derivation	Single source of truth (satisfies 3.2 directly); no wrapper script	Requires the derivation to be readable by both a custom_target and a test() in the same meson.build — confirmed straightforward, both are just Meson variables in scope	Selected
Standalone shell script re-deriving CGO flags via pkg-config	Keep a Makefile-free script mirroring the Makefile's own test-backend pkg-config derivation	Avoids touching apiserver/meson.build	Reintroduces exactly the duplicate-derivation risk this spec exists to eliminate	Rejected (brief.md's own "not recommended" option 2)

Design Decisions

Decision: run-resource-verify.sh's APISERVER_BIN follows its own sibling convention, not deploy-ha.sh's dual-path fallback

• Context: brief.md's Downstream section suggested mirroring deploy-ha.sh's meson-first / /tmp/apiserver-fallback pattern.
• Alternatives Considered:
  1. Mirror deploy-ha.sh's dual-path pattern (meson path first, /tmp/apiserver fallback).
  2. Match run-resource-verify.sh's own existing BINARY/SCHED_BIN/XT convention (single $BUILD_DIR-relative default, no fallback).
• Selected Approach: Option 2.
• Rationale: once src/frontend/Makefile is deleted, nothing in the project's own tooling will ever populate /tmp/apiserver again — a fallback to it is a fallback to a path only a developer's own hand-run go build could produce, which is not a real safety net worth the inconsistency of being the only binary in this script with different default-resolution logic than its three siblings.
• Trade-offs: slightly diverges from the brief's literal suggestion, but produces a more internally consistent script and satisfies requirements.md 5.3 ("shall not require... as its only means") without needing a fallback at all, since the primary path is now proven reliable (Meson always builds apiserver via /xce-build apiserver/all).
• Follow-up: deploy-ha.sh's own /tmp/apiserver fallback becomes similarly vestigial once the Makefile is gone — out of boundary for this spec (already migrated in a prior session per brief.md), but worth flagging as a small future cleanup, not a blocker here.

Decision: No wrapper script for the new backend test target

• Context: Meson test() needs an executable; go test with CGO env and a specific working directory could be wrapped in a small shell script for clarity.
• Alternatives Considered:
  1. A thin wrapper shell script invoking go test with the right env, registered as the test()'s executable.
  2. test() invokes the go_compiler program object directly, with args, env, and workdir kwargs.
• Selected Approach: Option 2.
• Rationale: Meson's test() natively supports workdir and env; no wrapper is needed, and one fewer file avoids exactly the kind of incidental indirection this spec exists to remove elsewhere.
• Trade-offs: revised after an independent adversarial review round (2026-09-03) caught a real one: cgo_cflags/cgo_ldflags contain literal @CURRENT_SOURCE_DIR@/@BUILD_ROOT@ placeholder text that is normally resolved by tools/go_build's own fix_env sed machinery — bypassing go_build means bypassing that resolution too. Fixed by resolving both tokens directly with Meson's own .replace() string method at configure time (cgo_cflags.replace('@CURRENT_SOURCE_DIR@', meson.current_source_dir()).replace('@BUILD_ROOT@', meson.project_build_root())) rather than reintroducing a wrapper script — still net simpler than Option 1, but not the zero-cost choice the first design pass assumed.

Decision: deploy-ha.sh's dead-target message strings are in boundary even though its discovery logic is not

• Context: the first design draft excluded deploy-ha.sh entirely as "already migrated in a prior session," reasoning from the binary-discovery logic (genuinely already meson-first). An independent adversarial review round caught that its three make build-server//tmp/apiserver-referencing echo strings (lines ~157-164) were not part of that prior migration and would still tell a developer to run a target that no longer exists, once src/frontend/Makefile is deleted.
• Selected Approach: split the file's two concerns — discovery logic (out of boundary, unchanged) vs. message text (in boundary, added to File Structure Plan) — rather than treating "already touched once" as "fully out of scope."
• Follow-up: none needed beyond the File Structure Plan entry; this is a 2-string text edit, not a logic change.

Decision: status.md and apiserver-backend-tasks.md are live documentation, not historical spec records

• Context: requirements.md 6.3 exempts historical, already-completed spec documents from doc updates. An independent adversarial review round found two files outside .kiro/specs/ (src/frontend/docs/status.md:67, src/docs/apiserver-backend-tasks.md:70,120) stating make test/make test-integration as current fact — missed by the original brief's doc inventory, which only enumerated files already known to be live-authoritative.
• Selected Approach: treat both as live documentation in scope for update, since 6.3's exemption is worded specifically around ".kiro/specs" historical records, not arbitrary status/changelog files elsewhere in the repo.
• Follow-up: added both to File Structure Plan.

Decision: doc-file File Structure Plan entries state a scope rule, not a closed line-number list

• Context: three successive independent adversarial review rounds each found at least one live make-target/fixed-path reference in a file the design already had in scope, in a section/line the enumeration hadn't named (round 1: two new doc files entirely; round 2: xce-test-resources/SKILL.md, run.sh's error message; round 3: tech.md:81-82, testing.md:95, deploy-ha.sh:138-155's comment block, xce-deploy-ha/SKILL.md:294 — all in files already listed). A closed line-number enumeration kept being treated as if it were the completeness boundary, when it was really just a snapshot of what one investigation pass happened to find.
• Selected Approach: reworded every doc/script File Structure Plan entry around a stated scope rule ("every live reference in this file," not just the enumerated lines) and moved the Testing Strategy's live-reference sweep to run per-file BEFORE Phase 4, not only repo-wide after — so a task implementing one file is verifiably complete against that file's own grep, independent of whether this design's own enumeration was exhaustive.
• Rationale: the recurring pattern strongly suggested the enumeration approach itself, not any individual miss, was the actual defect — fixing instances one at a time without changing the underlying acceptance criterion risked a fourth, fifth round finding the same class of gap indefinitely.
• Follow-up: a fourth review round found the sweep's own "zero hits" bar was itself unachievable as worded (several legitimate, deliberately-excluded classes — vendored files, dated historical records, an inert placeholder default, OpenWolf's own logs — all match the same grep). Named each exclusion class explicitly in the Testing Strategy rather than leaving "zero hits" ambiguous; also found two C testsuite files (test_ha_bootstrap.c, test_ha_ctrlhello.c) with comments naming make test-integration by name, outside any doc/script file category considered so far — added to File Structure Plan (a 3-line rename, not a logic change). A fifth review round, specifically scanning .go source-file comments (a category rounds 1-4 never checked), found two more: the ROOT CLAUDE.md's "Key Files" entry (line 42, the single most-visible live reference in the repo — loaded into every session, distinct from the already-covered src/frontend/CLAUDE.md) and both Go modules' cmd/main.go ldflags-injection comments naming the Makefile's build-server/build-cli targets. Both added to File Structure Plan. The recurring lesson across rounds 1, 4, and 5: each round's "fresh eyes, no assumptions" instruction and switch to an unchecked file category (docs → scripts → C test comments → Go source comments) is what surfaces genuinely new gaps — re-reading the same already-covered files more carefully stopped finding anything past round 2.

Risks & Mitigations

• Risk: the new backend test() silently links against backend/stub.go (the //go:build !cgo fallback) instead of the real CGO path, producing a vacuous pass. Mitigation: Testing Strategy's "New capability verification" step deliberately breaks apiserver_cgo_deps and confirms the test fails for the expected linker reason before trusting a green run.
• Risk: deleting the Makefile before all manual-developer-only targets (test-backend, test-integration) have a proven equivalent silently drops coverage nobody notices until someone needs it. Mitigation: Migration Strategy's explicit Phase ordering (1-3 must land and be verified before Phase 4).
• Risk: run-resource-verify.sh's new discovery default assumes $BUILD_DIR ($REPO/src/xce.build, the asan profile dir) always contains a built apiserver — true only after /xce-build apiserver/all has actually been run. Mitigation: this matches the existing behavior/risk profile of the script's other three binaries (BINARY/SCHED_BIN/XT), which already assume the same; no new risk class introduced.

References

• .kiro/specs/eliminate-frontend-makefile/brief.md — original Path C discovery investigation (2026-08-27), the primary source for scope/seam decomposition.
• src/tools/xce-build.sh (lines 255-328) — live call-site evidence.
• src/frontend/apiserver/meson.build, src/meson.build — CGO derivation and program-object reuse evidence.
• .claude/skills/xce-test-resources/run-resource-verify.sh (lines 200-207, 348-351) — existing sibling discovery convention.