[FEATURE] Make missing targets a hard error instead of silently autodetecting

[vlsi]

Is your feature request related to a problem? Please describe.

There is no way to make apm install / apm compile fail when targets are not declared explicitly. When apm.yml has no targets: field and no --target flag is passed, both commands fall back to autodetecting harness targets by scanning the working tree for marker directories and files (.claude/CLAUDE.md, .codex, .gemini/GEMINI.md, .cursor, .github/copilot-instructions.md, .opencode, .windsurf, .kiro). The resolution chain is --target flag > apm.yml target:/targets: > autodetect (resolve_targets in src/apm_cli/core/target_detection.py, signal list in SIGNAL_WHITELIST).

In CI this is the wrong default. I want a build to fail loudly when a contributor forgets to commit targets:, not to quietly pick targets from whatever directories happen to exist on the runner. The silent fallback defeats reproducibility: a check that runs apm install && apm compile && git diff --exit-code to assert that committed compiled files match apm.yml is not stable, because the resolved set depends on uncommitted, machine-local state rather than on apm.yml alone.

The existing guard does not cover this case. Autodetect only fails when it finds zero markers — resolve_targets raises NoHarnessError (exit 2) on an empty repo. With exactly one marker present (a committed .claude/, or a throwaway local .gemini/ from an unfinished prototype) it silently resolves to that target and proceeds. So the absence of a declared targets: field is never reported as an error as long as the working tree contains at least one harness directory. That is precisely when I most want it reported.

(For context: a non-empty targets: in apm.yml already short-circuits resolution before autodetect, so declared targets are honoured deterministically. The strict precedence chain landed in v0.12.3 (#1165); plural targets: lists are honoured in install since v0.16.1 (#1560). The gap is only the undeclared case, where the fallback is silent rather than fatal.)

Describe the solution you'd like

A way to require explicit targets, so that a missing declaration is a hard error rather than a trigger for autodetection.

When enabled, apm install and apm compile resolve targets from --target and apm.yml targets:/target: only. If neither is present, they exit non-zero with a clear message ("No targets declared: set targets: in apm.yml or pass --target") and never scan the working tree. The working-tree contents — committed or not — must not affect which targets are resolved.

Any of these shapes would work; I have no strong preference:

• A flag, e.g. apm install --require-targets / --no-autodetect.
• An environment variable, e.g. APM_REQUIRE_TARGETS=1, convenient for CI.
• An apm.yml setting, e.g. autodetect: false.
• Making "explicit only" the default and turning autodetect into an opt-in request, e.g. --target auto.

The goal: given a fixed apm.yml, the resolved targets depend only on apm.yml and explicit flags, and an undeclared project fails fast instead of guessing.

Describe alternatives you've considered

• Parse apm.yml in CI and fail if targets: is absent. This works, but it is a workaround: it reimplements outside the tool a guarantee the tool should provide, and it can drift from APM's own parsing rules (singular vs plural form, CSV sugar, validation).
• Always pass --target in CI. This duplicates the target list outside apm.yml, so the two can drift, and it does not protect local developer runs.
• Persist resolved targets to apm.yml on first install. apm init already writes the resolved set into targets: (_resolve_init_targets -> config["targets"] in src/apm_cli/commands/init.py); apm install does not. Writing them back on first use would also make later runs deterministic. It is a softer fix than failing, but it does not give CI the "fail when undeclared" behaviour I want, so I see it as complementary rather than a substitute.

Additional context

• Signal list and resolution: SIGNAL_WHITELIST and resolve_targets in src/apm_cli/core/target_detection.py; install calls it from _resolve_targets_by_scope in src/apm_cli/install/phases/targets.py.
• The existing zero-markers guard: NoHarnessError (exit 2) is raised only when autodetect finds nothing, not when targets: is simply undeclared.
• compile resolves targets through a separate legacy path (detect_target via _resolve_effective_target in src/apm_cli/commands/compile/cli.py), which in the autodetect branch returns "all" on two or more detected folders rather than failing. A --require-targets mode should apply to both commands and resolve this divergence so they behave identically.
• The codebase already moves toward explicitness: the "No harness detected" error notes that APM previously defaulted to copilot and that the default is "now explicit". Requiring declared targets is the next step on that path.

[github-actions]

Triage decision

needs-design

Proposed labels

theme/portability
area/cli
area/multi-target
type/feature
status/needs-design

Milestone

null

Suggested next action

Draft a design brief choosing one of the four proposed implementation shapes (flag, env var, apm.yml key, or inverted default) and specify how the change unifies the divergent target-resolution paths in install and compile.

Suggested issue comment

Thank you for filing this, and for tracing the resolution chain through the source -- you have identified the gap precisely. The existing guard (NoHarnessError on zero markers) does not protect against the case you describe: one stray marker directory silently satisfying resolution in CI.

The feature direction is sound and consistent with APM's lockfile-is-canonical principle. The reproducibility problem you describe -- git diff --exit-code checking compiled files against apm.yml but target resolution depending on machine-local directories -- is exactly the kind of non-determinism that undermines CI value.

Before code can land, we need to answer two design questions:

1. **Which shape ships?** You offer four options (flag, env var, apm.yml key, inverted default). The apm.yml key (autodetect: false) is the most durable for CI teams but requires a schema change; the env var (APM_REQUIRE_TARGETS=1) is the lowest-friction adoption path. The team needs to pick one (or a ranked combination).

2. **How does compile unify with install?** You correctly note that compile resolves targets through _resolve_effective_target (returning all on two+ detections), which diverges from install's path. A strict mode must apply identically to both commands and resolve this divergence.

If you want to drive the design, a short comment here proposing answers to both questions would be the concrete next step. We can mark this accepted and milestone once the design is settled.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

The request maps directly to a real CI use case: teams running apm install && apm compile && git diff --exit-code to assert that compiled files are fully declared in apm.yml. The silent autodetect fallback makes this check non-deterministic (stray .gemini/ or .claude/ directories on the runner change the resolved set). APM's lockfile-is-canonical mental model is undermined if target resolution is not also deterministic. All four proposed shapes are discoverable; the env-var shape is the most natural CI fit (no flag in the command, set once in the CI environment). The primary design choice is ergonomics vs. configuration surface.

Supply Chain Security Expert -- Risk-Surface Reviewer

This feature has a net positive security posture: it prevents CI from silently materializing files for an unintended harness target (e.g., a development .gemini/ prototype directory picked up in a build). Requiring explicit targets: in apm.yml is a fail-closed improvement aligned with APM's threat model. No P/G/S surface is opened by this feature. The apm.yml field shape is not a lockfile change -- the resolved targets are already deterministic once targets: is declared. No supply-chain risk flagged.

OSS Growth Hacker -- Contributor-Tone Reviewer

vlsi has author_association: NONE but filed an exceptionally well-researched issue -- tracing code paths, citing version numbers, and offering alternatives. The reply should match their technical level: acknowledge the codebase research explicitly, validate the CI reproducibility framing without re-explaining the code they already know, and give a concrete design-question answer path. Avoid onboarding language. Story angle: "strict mode for target resolution" is a CI-first feature that positions APM as a serious build tool, not just a dev convenience.

Python Architect -- Architecture Reviewer

The change touches three modules: core/target_detection.py (resolve_targets, SIGNAL_WHITELIST), install/phases/targets.py (_resolve_targets_by_scope), and commands/compile/cli.py (_resolve_effective_target). The compile path returns "all" on two+ detected folders, diverging from install's path -- a strict mode must unify both. The design must choose one implementation shape and specify the unified resolution contract before a PR can land safely. status/needs-design is the correct outcome; the design surface is bounded (one schema key or one env var, plus a unified resolver function) and feasibility is high once the choice is made.

Doc Writer -- Documentation Reviewer

Any implementing PR will need: the new flag or option documented in docs/src/content/docs/reference/cli-commands.md under both install and compile, a section in the CI/CD integration guide on reproducible target resolution, and area/docs-site as a secondary label at that time. For the design phase, no doc work is implied yet.

APM CEO -- Triage Arbiter

Specialists agree: the feature is directionally correct, the design surface is bounded, and status/needs-design is the right outcome. The Python Architect's call to unify install and compile target resolution before code lands is load-bearing -- the current divergence is a latent issue regardless of this feature. Strategically, explicit targets as a CI-first discipline reinforces APM's positioning as an enterprise-grade reproducible package manager. The +1 reaction signals community validation. Priority: medium-high once designed; milestone once accepted.

{
  "decision": "needs-design",
  "decision_detail": "Pick one implementation shape (flag vs env var vs apm.yml key vs inverted default) and specify how install and compile target-resolution paths are unified under strict mode.",
  "theme": "theme/portability",
  "areas": ["area/cli", "area/multi-target"],
  "type": "type/feature",
  "status": "status/needs-design",
  "priority": null,
  "preserved_labels": [],
  "milestone": null,
  "next_action": "Draft a design brief choosing one of the four proposed implementation shapes and specifying how the install and compile resolution paths unify under strict mode.",
  "comment_markdown": "Thank you for filing this. Before code can land, two design questions need answers: (1) which of the four shapes ships (flag, env var, apm.yml key, inverted default)? (2) how does compile unify with install given the divergent _resolve_effective_target path?"
}

---

Triage status: agentic proposal pending human ratification.
Silence is approval. Maintainers can:

• Override any label or milestone above by editing it directly --
  human edits are authoritative and will not be reverted on
  subsequent runs.
• Re-trigger triage by applying the status/needs-triage label, or
  by removing status/triaged to enroll the issue in the next
  daily sweep.

Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

Generated by Triage Panel · sonnet46 3.3M · ◷