Summary

Teaches the gstack build orchestrator's plan synthesizer that Go package main shim phases need their cmd-directory included in the per-phase <!-- testCmd: --> hint, not just the conventional test/ tree. Without this, verify-red exercises the wrong directory, sees existing unit tests all-pass, and halts with Gemini could not produce failing tests after N attempts (GSTACK_BUILD_RED_MAX_ITER) — the exact failure mode that stuck the polis-mesh-gap4-adapter run on 2026-05-25.

Three commits, bisectable:

• 117429e feat(build): teach synthesizer to emit cmd-dir testCmd for package main shims — initial bullet added to the planSynthesizer prompt section in build/SKILL.md.tmpl (+ autoregen build/SKILL.md).
• fdabbc2 test(build): pin synthesizer package-main testCmd hint with static-grep regression — new test/build-synthesizer-package-main-hint.test.ts (3 tests) pinning the anchor phrase, failure-mode reference, concrete example, and section placement.
• 0fdebfb refactor(build): apply codex review findings + bump skill version — addresses Codex pre-landing findings: dropped misleading Python/Rust path-union over-generalization, clarified the rule applies even in monoglot Go repos, strengthened tests with two additional assertions for command shape and anti-generalization. Bumped build/SKILL.md.tmpl frontmatter version: 1.29.0 → 1.30.0 per the fork versioning rule.

Fork-local skill release: per the "Fork versioning rule" in CLAUDE.md, the top-level VERSION, package.json, and CHANGELOG.md are intentionally untouched. The skill-internal version: frontmatter is the release marker for custom-skill work in this fork.

Test Coverage

5 tests pinning the prompt change, 14 expects, 20ms:

Parser/resolver side of <!-- testCmd: --> is already pinned in build/orchestrator/__tests__/per-phase-testcmd.test.ts and not extended here.

Tests: 0 → 1 (+1 new file). Coverage gate: PASS (100%, 0 gaps for a prompt-only change).

Pre-Landing Review

Inline checklist: no blocking findings. SQL/data safety and LLM-output-trust-boundary are both N/A (the diff is a change to an LLM prompt, not consumption of LLM output).

Codex Adversarial Review

Codex found 3 actionable findings on commit fdabbc21, all addressed in 0fdebfb2:

1. Python/Rust over-generalization (Codex's recommended-changes finding) — the original bullet generalized the unioned-path syntax to "any phase whose tests can't live in test/" with Python and Rust examples. pytest does not take Go-style ./... paths and cargo test discovers tests via the crate, so that generalization could push Gemini toward invalid commands for those ecosystems. Fix: scoped the bullet to Go package main only, with an explicit "do not generalize" sentence calling out Python's and Rust's different runner mechanics.

2. Conflict with prior conditional bullet — the existing "Polyglot repo test-runner hint" says emit <!-- testCmd: --> only when the per-phase runner differs from the repo root. The new bullet's "MUST include" implied an unconditional emit, creating ambiguity. Fix: explicit phrasing "emit even in a monoglot Go repo where the previous bullet would otherwise let you skip it" so the synthesizer knows the cmd-dir override is required regardless.

3. Test doesn't pin command shape — original 3 assertions caught wording-level drift but not changes to the actual unioned-go-test pattern. Fix: added 2 new assertions for the literal go test ./.../cmd/.../... ./test/... shape and for the presence of the anti-generalization wording.

Two additional Codex findings (line 477 test-writer prompt coupling, line 426 phase skeleton lacks testCmd placement) were deferred as out-of-scope for this branch.

Plan Completion

Plan file: ~/.claude/plans/polis-mesh-gap4-adapter-20260525-074215-frolicking-frog.md

• Step 1: Fresh branch off main (parent bb465b6f v1.45.0.0)
• Step 2: build/SKILL.md.tmpl gains package main co-location bullet
• Step 3: build/SKILL.md regenerated via bun run gen:skill-docs
• Step 4: Static-grep regression test
• Step 5: bun test green (exit 0, both pre-fix and post-fix runs)
• Step 6: This handoff

TODOS

No TODOS.md items completed by this PR.

Verification Note: Eval-Store Fixture Noise

Reviewers running bun test may see this in the output:

Eval Results — ... — e2e
  test-1                                PASS    $0.10           2s
  test-2                                FAIL    $0.05           1s
  Total: 1/2 passed                     $0.15  3s
  ...
  Status: 2 unchanged

This is not a real eval failure. It is the EvalCollector printing its real-looking report while processing fixture data inside the passing test test/helpers/eval-store.test.ts:85 ('written JSON has correct schema fields'). That test deliberately constructs one passing entry (test-1) and one failing entry (test-2) to verify the failure-counting logic via expect(data.failed).toBe(1). Running the file in isolation: 31 pass / 0 fail / 67 expects / 537ms.

Filed as a separate DX cleanup candidate: the EvalCollector could suppress its real-looking report when invoked from a unit-test fixture context (e.g., NODE_ENV=test gate). Not in scope for this PR.

Documentation

No documentation files needed updating. This is an internal refinement to the planSynthesizer's prompt rules — no new public surface (no CLI flag, no env var, no command), so README/ARCHITECTURE/CONTRIBUTING/CLAUDE.md/build/README are unchanged. The fork-local rule blocks CHANGELOG/VERSION/package.json changes.

Test plan

• bun test passes (exit 0) on both pre-fix and post-fix commits
• bun test test/build-synthesizer-package-main-hint.test.ts passes (5/5, 20ms)
• bun run gen:skill-docs succeeds; build/SKILL.md mirrors build/SKILL.md.tmpl
• Manual: next time gstack-build hits a Go package main phase via planSynthesizer, the emitted living plan's testCmd hint includes the binary directory (will be observable on the next polis-mesh-style run)

🤖 Generated with Claude Code