Roadmap 3.11.4: complete OrthoConfig precedence-ladder regression tests

[coderabbitai]

Context

Roadmap item 3.11.4 (Add OrthoConfig precedence-ladder regression tests) has three sub-items that remain open after PR #327 (closes #291) delivered exhaustive rstest and proptest coverage of the explicit config-path selector precedence (--config > NETSUKE_CONFIG).

The following sub-items are still unaddressed:

• Depend on OrthoConfig 5.2.3 for consumer boundary guidance.
• Preserve Netsuke-specific precedence expectations for manifest path, display policies, locale, and profile selection.
• Verify that CLI flags override environment, profile, project, user, system, and default configuration layers.

Required constraint for any PR closing this issue

Important

The environment selector set is closed at one variable. Any regression tests added here must not introduce, assert, or assume NETSUKE_CONFIG_PATH or any second environment selector.

• Precedence tests assert the two-selector ladder only: --config > NETSUKE_CONFIG > automatic discovery.
• No test sets NETSUKE_CONFIG_PATH expecting it to select a configuration file.
• The existing legacy_config_path_variable_is_not_a_selector test (in src/cli/config_path_precedence_tests.rs) still passes unmodified.

Rationale: ADR-004 (Accepted 2026-05-31) records NETSUKE_CONFIG as the only environment selector, and the legacy NETSUKE_CONFIG_PATH alias was removed in #427. Reintroducing it would require superseding ADR-004 and updating docs/users-guide.md, docs/developers-guide.md, and docs/netsuke-design.md together — that is a separate, deliberate decision, not something to add incidentally while writing regression tests.

Out of scope for PR #327

These items require changes beyond the explicit config-path selector subset and are tracked here for a future PR.

Note: selector ladder narrowed (2026-07-30)

This issue was originally filed describing a three-selector ladder, --config > NETSUKE_CONFIG > NETSUKE_CONFIG_PATH. That is no longer accurate. The current ladder is:

--config             (CLI flag)
NETSUKE_CONFIG       (env var)
automatic discovery  (fallback)

The three open sub-items above are unaffected — none of them depend on the legacy alias — so this issue remains valid work. Only the precedence framing needed correcting.

References

• Roadmap item 3.11.4: docs/roadmap.md line 125
• PR Verify config precedence invariant (#291) #327: Verify config precedence invariant (#291) #327
• Closed issue Add property-based tests (proptest) exhaustively verifying config-precedence invariant across all 8 selector combinations #291: Add property-based tests (proptest) exhaustively verifying config-precedence invariant across all 8 selector combinations #291
• ADR-004: docs/adr-004-explicit-config-selection-outside-orthoconfig.md

/cc @leynos

Aggregation (2026-08-12)

This issue now also absorbs #317 (closed), whose property-based scope substantially overlapped the sub-items above — both demand invariant coverage of the same merge pipeline, and keeping them separate risked two people writing the same tests. Additional sub-items carried over from #317:

• Generate arbitrary CliConfig layer values with proptest strategies and verify merge ordering is consistently respected (a CLI value always beats a file value for the same field; defaults → file → environment → CLI).
• Verify list-appending semantics (cmds.build.targets appended in discovery order) under arbitrary target lists.
• Verify cross-field validation rules (theme/no_emoji, spinner_mode/progress, output_format restriction) fire correctly across the full domain of enum combinations.

The closed-selector constraint above applies to these carried-over items equally: no property strategy may introduce or assume a second environment selector. The stale June draft PR #368 (filed against #317) predates the env-seam series and should be treated as reference material only.

[coderabbitai]

🔗 Related PRs

#327 - Verify config precedence invariant (#291) [merged]
#329 - Instrument config path resolution (#292) [merged]
#330 - Inject config environment access (#293) [merged]
#548 - Cache config file layer discovery (#319) [open]
#558 - Adopt OrthoConfig v0.9.0 [open]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[leynos]

Important

Constraint added 2026-08-01: no in-process environment mutation.

AGENTS.md now forbids in-process environment mutation in tests and disqualifies process-wide locks as a fallback.

This issue's remaining sub-item — "verify that CLI flags override environment, profile, project, user, system, and default configuration layers" — requires controlling NETSUKE_CONFIG. There is no injection point today: src/cli/discovery.rs:111 reads it via std::env::var_os, which is why the existing suites (tests/cli_tests/config_selection.rs, config_discovery.rs, config_discovery_scopes.rs, config_discovery_overrides.rs) all serialize behind EnvLock.

This issue is blocked on #483, which threads &impl mockable::Env through the discovery functions.

The closed-selector constraint recorded in this issue is unaffected and still binds: the ladder remains --config > NETSUKE_CONFIG > automatic discovery, per ADR-004, and legacy_config_path_variable_is_not_a_selector must still pass unmodified. Injecting an Env changes how the selector is read, not which selectors exist.

[leynos]

Aggregation: this issue now absorbs #317 (closed) — its proptest scope over the merge pipeline substantially overlapped the open sub-items here, so the property-based items are carried over as an explicit checklist (see the aggregation section appended to the description). ADR-004's closed-selector constraint applies to them equally.

[leynos]

Transitively blocked on PR #558 (via #483, per #496's checklist). The precedence-ladder regression tests — including the proptest items folded in from #317 — would exercise the discovery machinery #558 rewrites onto OrthoConfig v0.9.0's environment adapters, so writing them against main's v0.8.0 shape now would be churn. Start after #558 merges.