Repository navigation
refactor(targets): route every manifest target reader through one owner - #3791
Daniel Meppiel (danielmeppiel) merged 18 commits into
Conversation
apm audit read only the singular `target:` key, so a manifest using plural `targets:` passed compilation-target policy whatever it listed (#3732). Audit and every install seam now hand the check the EffectiveTargetDecision.canonical_targets projection, and the policy parser canonicalizes compilation.target.allow/enforce through the same owner: - plural `targets:` is judged in audit, matching the install gate; - CSV `target: "claude,copilot"` is split instead of failing as one token; - aliases compare as the profile they deploy (vscode/agents -> copilot, agy -> antigravity, intellij -> copilot) on both sides; - `target: all` is judged as its install expansion; `targets: [all]` stays omitted; `all` in an allow list means unrestricted; - inherited alias allow lists no longer intersect to "allow nothing". normalize_policy_targets is folded into EffectiveTargetDecision and a new registry-delegation-policy-target-projection guard keeps every compilation-target seam on that projection. Fixes #3732. Supersedes #3739 and reuses its plural-key tests. apm-spec-waiver: compilation-target policy evaluation is APM policy behavior; OpenAPM v0.1 does not specify it Co-authored-by: Mohammed Alkindi <alkndymhmd692@gmail.com> Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Mohammed Alkindi <alkndymhmd692@gmail.com> Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Add registry_delegation.policy_target_projection to the frozen rule inventory so test_registered_rule_inventory_matches_frozen_semantic_contract matches the registered rules (Build & Test Shard 2 was red). Add the local-bundle install seam to the policy-target projection mutation test, and scope each case's assertion to a violation in the mutated file so an unrelated violation elsewhere cannot satisfy it. Mutation-break: dropping run_policy_preflight from the guard's seams fails the new case. Addresses panel follow-ups 1 and 3 on #3774. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
The install guarantees said the selection matches both compilation.target.allow and compilation.target.enforce, but the check evaluates enforce first and skips allow when enforce is set, as the policy reference already documents. Addresses Copilot inline review on governance-guide.md:311 and panel follow-up 2 on #3774. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Package-level `target:` / `targets:` is now read only through ManifestTargetDeclaration (models/manifest_targets.py), exposed as APMPackage.target_declaration, package_target_declaration(), read_manifest_target_declaration() and manifest_target_restriction(). Compile, the install targets phase, MCP/LSP integration, lockfile reconciliation, the build orchestrator, the audit target hint, the package-target filter and init re-init no longer re-read or re-parse the raw keys. - `apm install` rejects `target: intellij` / `copilot-app` before writing anything (it used to deploy files and a lockfile, then exit 2). - singular `target: all` no longer prints "treating the field as omitted" while install expands it; `apm init` re-init writes its expansion instead of narrowing it to `targets: [all]`. - docs: `compilation.target` is documented as ignored by `apm compile`. The registry-delegation-target-vocabulary rule is widened to deny-by-default over src/apm_cli with concept-named exemptions, and a new manifest-target-declaration owner record registers its guard. Refs #3732 apm-spec-waiver: routes existing manifest target readers through one owner; OpenAPM-observable acceptance is unchanged Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
# Conflicts: # tests/integration/test_architecture_owner_rule_mutations.py
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
🟡 Changes recommended
Re-initialization redirects MCP configuration for target: all from .vscode/mcp.json to .github/mcp.json, while rejecting target: intellij still renames legacy lockfiles despite the no-write guarantee.
2 open issues
What changed in this PR
This PR builds on #3774 to centralize package-level target declarations across APM. It routes manifest readers through one owner and adds safeguards against inconsistent target handling.
Changes:
- Introduces
ManifestTargetDeclarationand routes install, compile, MCP, reconciliation, and re-init readers through it. - Adds early install validation, preserves legacy
allbehavior, and expands architecture guards. - Adds regression coverage and clarifies manifest and policy documentation.
| File | Description |
|---|---|
| tests/unit/scripts/test_architecture_runner.py | Registers the policy projection guard in the expected inventory. |
| tests/unit/policy/test_run_dependency_policy_checks.py | Updates checks to canonical target tuples. |
| tests/unit/policy/test_policy_checks.py | Covers canonical comparisons and manifest declaration forms. |
| tests/unit/policy/test_parser.py | Expects canonical policy aliases. |
| tests/unit/policy/test_integration_pinned_constraint.py | Updates the target-check input contract. |
| tests/unit/policy/test_inheritance.py | Tests alias-aware policy inheritance. |
| tests/unit/models/test_manifest_targets.py | Tests declaration ownership and validation. |
| tests/unit/install/test_policy_target_check_phase.py | Tests policy checks through shared target decisions. |
| tests/unit/install/test_mcp_preflight_policy.py | Uses canonical tuples in MCP preflight tests. |
| tests/unit/install/phases/test_read_yaml_targets_list_form.py | Exercises parsed packages and invalid target declarations. |
| tests/unit/core/test_target_detection.py | Covers canonical policy projections and runtime distinctions. |
| tests/unit/core/test_build_orchestrator.py | Tests conflicting manifest keys directly. |
| tests/integration/test_wave7_policy_registry_coverage.py | Updates policy integration inputs. |
| tests/integration/test_target_declaration_install_lifecycle.py | Adds install, MCP destination, and user-scope scenarios. |
| tests/integration/test_target_declaration_adjacent_commands_lifecycle.py | Covers adjacent commands, dependency subsets, and re-init. |
| tests/integration/test_architecture_owner_rule_mutations.py | Adds mutations proving target guards reject bypasses. |
| tests/integration/policy/test_compilation_target_policy_e2e.py | Adds real-binary audit and install policy coverage. |
| tests/integration/_target_policy_kit.py | Provides shared isolated target-policy fixtures. |
| tests/fixtures/policy/golden/parsed-policies.json | Updates canonical policy expectations. |
| src/apm_cli/policy/policy_checks.py | Judges canonical target sets and reports their source. |
| src/apm_cli/policy/parser.py | Canonicalizes policy target constraints. |
| src/apm_cli/policy/install_preflight.py | Accepts canonical targets and selection provenance. |
| src/apm_cli/models/manifest_targets.py | Introduces the manifest target declaration owner. |
| src/apm_cli/models/dependency/registry_entry.py | Adds a dependency-subset guard exemption comment. |
| src/apm_cli/models/dependency/object_fields.py | Adds a dependency-subset guard exemption comment. |
| src/apm_cli/models/apm_package.py | Exposes declaration ownership and compatibility helpers. |
| src/apm_cli/integration/mcp_integrator.py | Routes manifest restrictions through the owner. |
| src/apm_cli/integration/mcp_integrator_install.py | Delegates manifest target parsing to the owner. |
| src/apm_cli/install/target_filter.py | Removes local raw-field conflict checking. |
| src/apm_cli/install/pipeline.py | Validates declarations before pipeline writes. |
| src/apm_cli/install/phases/targets.py | Replaces raw manifest reads with declaration views. |
| src/apm_cli/install/phases/policy_target_check.py | Uses the shared decision's canonical projection. |
| src/apm_cli/install/mcp/integration.py | Uses owner-based configuration and validation. |
| src/apm_cli/install/mcp/command.py | Passes canonical target decisions to policy preflight. |
| src/apm_cli/install/manifest_reconcile.py | Delegates declared restrictions to the owner. |
| src/apm_cli/install/local_bundle_handler.py | Projects bundle deployment targets for policy checks. |
| src/apm_cli/core/target_detection.py | Centralizes policy projection and delegates manifest reads. |
| src/apm_cli/core/deployment_ledger.py | Adds ledger-row guard exemption comments. |
| src/apm_cli/core/build_orchestrator.py | Uses owner-provided manifest restrictions. |
| src/apm_cli/compilation/agents_compiler.py | Adds a compilation-field guard exemption comment. |
| src/apm_cli/commands/targets.py | Adds display-row guard exemption comments. |
| src/apm_cli/commands/pack.py | Adds a bundle-metadata guard exemption comment. |
| src/apm_cli/commands/init.py | Uses declaration-based prefill and deduplicates source labels. |
| src/apm_cli/commands/compile/cli.py | Removes duplicate manifest target parsing. |
| src/apm_cli/commands/_helpers.py | Adds bootstrap-writer guard exemption comments. |
| src/apm_cli/bundle/local_bundle.py | Adds a bundle-metadata guard exemption comment. |
| scripts/architecture_linter/checks/registry_owner_guards.py | Expands target-reader scanning and adds policy projection checks. |
| scripts/architecture_linter/checks/mutation_mcp_target_and_scope.py | Updates guards to require declaration-owner calls. |
| packages/apm-guide/.apm/skills/apm-usage/governance.md | Clarifies target policy behavior and remediation. |
| docs/src/content/docs/reference/policy-schema.md | Documents canonical target constraints. |
| docs/src/content/docs/reference/manifest-schema.md | Clarifies legacy all, rejected targets, and ignored configuration. |
| docs/src/content/docs/enterprise/policy-reference.md | Explains canonical comparisons and audit/install selection. |
| docs/src/content/docs/enterprise/governance-guide.md | Corrects target enforcement guarantees. |
| CHANGELOG.md | Records policy and declaration-handling fixes. |
| .apm/architecture/owners/core-runtime.json | Registers declaration ownership and policy projection guards. |
Review effort: Balanced
APM Review Panel:
|
| Persona | B | R | N | Takeaway |
|---|---|---|---|---|
| Python Architect | 0 | 3 | 0 | The owner design holds and install validates before the pipeline writes. Fix the exemption-marker scope, a surviving parallel reader (compile -g still warns on target: all), and whole-file owner exemptions. |
| Test Coverage Expert | 0 | 2 | 0 | Scenarios 1-3 have passing real-binary regression traps. Missing: a test that an exemption on a block does not cover nested reads (probe shows it does), and a -g pre-write rejection trap. |
B = blocking-severity findings, R = recommended, N = nits.
Counts are signal strength, not gates. The maintainer ships.
Top 5 follow-ups
- [Python Architect] Fold now (in approved scope). Route
apm compile -g(compile/cli.py:381-385->core/apm_yml.read_declared_target_names) and the four self-loading readers (target_detection.read_manifest_target,manifest_reconcile.declared_target_profiles,build_orchestrator.py:365and:487) throughread_manifest_target_declaration, with one leniency parameter. Add an e2e test:apm compile -gwithtarget: allprints no deprecation warning. -- One command still prints the warning this PR removes, so the PR's main claim is only partly true. - [Test Coverage Expert] Fold now (in approved scope). Limit an exemption marker to its own statement's lines, or a comment-only line directly above it; stop it covering enclosing headers or the next line. Add mutation cases for a read leaking out of an exempt block, a marker on a block header, Subscript (
data['targets']) and Compare ('targets' in data). -- A reproduced bypass of the deny-by-default guard, with no test bounding exemption reach. - [Test Coverage Expert] Fold now (small). Parametrize
test_undeployable_singular_target_is_rejected_before_any_writeover project and-gscope. -- Scenario 1 claims both scopes; only project scope has a regression trap (the -g path passes an ad-hoc probe today). - [Python Architect] Defer to a follow-up issue. Narrow the whole-file owner exemptions (
core/target_detection.py,core/apm_yml.py) to the parser functions; deriveAPMPackage.canonical_targetsfromtarget_declaration.canonical(fortargets=['all']they give('all',)vs()); guardcanonical_targetsreads inhook_integrator.py:1962,uninstall/engine.py:1151,uninstall/cli.py:705. -- Real drift risk, but no user scenario is broken on this commit. - [Python Architect] Defer (or fold if cheap with item 2). Extend
_raw_target_readto catchk == "targets",.pop/.setdefault, constant-key subscripts and receivers outside the current name list. -- Widens detection rather than closing a reproduced hole.
Recommendation
The design is sound and the claimed install, init and docs scenarios are backed by passing real-binary tests, so this PR should ship in 0.36.1. Before it lands, fold the three in-scope items: route apm compile -g and the self-loading readers through the owner (with an e2e test asserting no warning), limit exemption markers to the marked statement (with mutation tests), and parametrize the pre-write rejection test over -g. Without these, the CHANGELOG line about one owner and a deny-by-default guard would overstate what ships. Track whole-file exemptions, canonical_targets drift and the broader detector shapes in one follow-up issue under #3732, and confirm CI is green on the final head.
Full per-persona findings
Python Architect
- [recommended] Deny-by-default guard: exemption markers are wider than the statement they mark, and several raw-read shapes are never flagged at
scripts/architecture_linter/checks/registry_owner_guards.py:366
_target_exemption(lines 350-372) adds lineno-1 of every enclosing statement to the candidate lines, so a trailing marker on line N also exempts line N+1, and a marker above an if/for/try/with header exempts the whole block. Shipped code relies on block scope (commands/_helpers.py:695,commands/targets.py:138). Concepts are not tied to the read shape._raw_target_readdoes not flagk == "targets",.pop/.setdefault, constant keys, or receivers outside the hard-coded name list.
Suggested: Accept a marker only on the flagged node's own lines or a comment-only line directly above; add Compare/pop/setdefault detection; add mutation cases for trailing-marker leak and block-header marker. - [recommended] A parallel disk reader survives:
core/apm_yml.read_declared_target_names(used byapm compile -g) skips the owner and still prints the singular 'all' warning this PR removes elsewhere atsrc/apm_cli/core/apm_yml.py:191
Verified withtarget: all: prints "'all' in apm.yml targets is deprecated ... treating the field as omitted".read_manifest_target_declarationhas no callers insrc/;target_detection.read_manifest_target:1027,manifest_reconcile.declared_target_profiles:396,build_orchestrator.py:365and:487each loadapm.ymlwith different leniency.
Suggested: Rebuildread_declared_target_namesonread_manifest_target_declaration(...).restriction(); route the other readers through it; add an e2eapm compile -gstep. - [recommended] The owner exemption covers whole files, and
APMPackage.canonical_targetsis still a second projection read raw by 3 call sites atsrc/apm_cli/models/apm_package.py:536
_TARGET_DECLARATION_OWNERSexempts all ofcore/target_detection.pyandcore/apm_yml.py.__post_init__derivescanonical_targetswith its own normalization; fortargets=['all']it gives('all',)while the declaration folds to().
Suggested: FunctionDef-scoped exemption; derivecanonical_targetsfromtarget_declaration.canonical; guard or reroute the three raw call sites.
Test Coverage Expert
- [recommended] A concept-named exemption on a compound statement exempts every raw package-target read inside it; no mutation test limits exemption scope at
scripts/architecture_linter/checks/registry_owner_guards.py:350
Probe viarun_selected_ruleswithsource_overrides:leaked = package.targetsinside the bootstrap-writer-exempt if-block incommands/_helpers.py-> 0 violations; same line outside the block -> flagged; clean baseline -> 0. No case covers the Subscript or Compare branches of_raw_target_read.
Proof (missing at):tests/integration/test_architecture_owner_rule_mutations.py::test_manifest_target_declaration_guard_rejects_raw_readers[exempt-block-does-not-cover-nested-read]-- proves: a new raw read of a package's targets is rejected even inside a block exempted for a different concept. [portability-by-manifest,governed-by-policy] - [recommended] No test checks that
apm install -gwithtarget: intellijorcopilot-appin~/.apm/apm.ymlexits 2 before any write attests/integration/test_target_declaration_install_lifecycle.py:43
Project scope is covered and passes (6 passed, 73.85s). Ad-hoc real-binary -g probe: exit 2, no lockfile, only~/.apm/config.jsonchanged. Without a test, the user-scope path can regress silently.
Proof (missing at):tests/integration/test_target_declaration_install_lifecycle.py::test_undeployable_singular_target_is_rejected_before_any_write[user-intellij|user-copilot-app]-- proves:apm install -gwith an undeployable target exits 2 and leaves the user's home untouched. [portability-by-manifest,multi-harness-support,devx]
This panel is advisory. It does not block merge. Re-apply the
panel-review label after addressing feedback to re-run.
Generated by autopilot-pr-review-worker. This comment is AI-generated and may contain errors.
The deny-by-default target guard let an exemption marker cover a whole block (marker above an if/for/try exempted its body) and the line after a trailing marker, so a raw package.targets read placed inside an exempted block went unflagged. A marker now covers only the innermost statement holding the read (its header for compound statements) or sits alone on the line directly above it. The guard also flags .pop/.setdefault on the target keys. Existing init and compilation.target exemptions are marked per statement. Mutation cases cover a read leaking out of an exempt block, a trailing-marker leak, and the subscript, key-test and pop shapes. Addresses panel follow-up 2 (test-coverage-expert, python-architect) on #3791. apm-spec-waiver: architecture guard and exemption markers only; no OpenAPM-observable behavior change Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…on owner apm compile -g still re-read ~/.apm/apm.yml with its own parser and, for target: all, printed the "treating the field as omitted" warning that install no longer prints. read_manifest_target_declaration is now the one disk reader (strict: refuses symlinks, empty and non-mapping documents; lenient: returns None), and compile -g, audit's read_manifest_target and install's declared_target_profiles go through it. read_declared_target_names is removed; restriction() gains allow_empty_singular for strict readers. The pre-write rejection moves into reject_undeployable_manifest_targets (keeps install/pipeline.py under its LOC budget) and also runs before the CLI renames a legacy apm.lock, so a rejected install writes nothing. Re-init expands singular target: all with the install spellings, so vscode keeps its .vscode/mcp.json destination instead of becoming copilot (.github/mcp.json). Tests: e2e for compile -g without the warning, -g pre-write rejection, legacy lockfile untouched on rejection, and the MCP destination after re-init; unit tests for the strict/lenient reader; drift tests patch the owner's parser. Addresses panel follow-ups 1 and 3 and Copilot inline comments on src/apm_cli/install/pipeline.py:443 and src/apm_cli/models/manifest_targets.py:155. apm-spec-waiver: routes existing manifest target readers through one owner; OpenAPM-observable acceptance is unchanged Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
A marker on a block's first body line still exempted raw reads in the enclosing if/for/with header, because comment lines between a header and its body counted as header lines. Those lines now belong to the body, and match blocks end their header at the first case. compile -g silently compiled every harness for singular target: all,<x>, which install -g rejects; restriction(strict=True) (renamed from allow_empty_singular) now raises the same "all cannot be combined" error. A direct run_install_pipeline test pins the pipeline's own pre-write gate, which the CLI's earlier call otherwise hides. Addresses delta panel findings (python-architect, test-coverage-expert) on #3791. apm-spec-waiver: routes existing manifest target readers through one owner; OpenAPM-observable acceptance is unchanged Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Avoids landing-order conflicts with other queued PRs. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
apm-spec-waiver: merge of main only; no new spec-observable behavior in this commit Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
apm-spec-waiver: merge of main only; no new spec-observable behavior in this commit Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
APM Review Panel:
|
| Persona | B | R | N | Takeaway |
|---|---|---|---|---|
| Python Architect | 0 | 2 | 0 | Folds are correct and behavior-neutral; header-leak and compile -g mixed-all gaps found and since folded in 80f6976. |
| Test Coverage Expert | 0 | 1 | 0 | Both prior gaps closed; the pipeline's own pre-write gate lacked a direct test, since folded in 80f6976. |
B = blocking-severity findings, R = recommended, N = nits.
Counts are signal strength, not gates. The maintainer ships.
Top 3 follow-ups
- [Python Architect] Narrow the whole-file owner exemptions on
core/target_detection.pyandcore/apm_yml.pyto the parser functions only. -- A new raw target read added to either file would pass the deny-by-default guard unnoticed. - [Python Architect] Derive
APMPackage.canonical_targetsfromtarget_declaration.canonical, and move its raw readers (hook_integrator, uninstall engine and CLI) onto the owner. -- Fortargets: [all]it gives('all',)while the owner gives(). - [Python Architect] Detect comparison-shaped reads (
k == "targets") without false positives on CLI key names, and route build_orchestrator's twoapm.ymlloads throughread_manifest_target_declaration. -- Closes the last known unguarded read shape.
Recommendation
Merge once #3774 lands, since this PR is stacked on it. Every in-scope finding from both passes is folded and its test confirmed to catch regressions, CI is green and the branch is mergeable. Track the deferred items in one follow-up issue under #3732, with the whole-file owner exemptions first.
Folded in this run
- (panel FU-1)
apm compile -g, audit'sread_manifest_targetand install'sdeclared_target_profilesread throughread_manifest_target_declaration;read_declared_target_namesremoved; compile -g no longer prints theallwarning -- resolved in 19488ec. - (panel FU-2) Exemption markers cover only the marked statement; guard flags
.pop/.setdefault; mutation cases for block leak, trailing-marker leak, subscript, key test, pop -- resolved in 5f1190b. - (panel FU-3)
apm install -gpre-write rejection e2e -- resolved in 19488ec. - (CI, T2 captain)
install/pipeline.pyLOC budget: pre-write check moved toreject_undeployable_manifest_targets; drift tests patch the owner's parser -- resolved in 19488ec. - (delta panel) Header-leak via comment above the first body line; strict
target: all,<x>rejection in compile -g; directrun_install_pipelinegate test -- resolved in 80f6976.
Copilot signals reviewed
src/apm_cli/install/pipeline.py:443-- LEGIT: a legacyapm.lockwas renamed before the rejection; the check now also runs beforemigrate_lockfile_if_needed(resolved in 19488ec).src/apm_cli/models/manifest_targets.py:155-- LEGIT: re-init rewrotetarget: allwith the policy projection (vscode->copilot), moving MCP to.github/mcp.json; now uses the install spellings (resolved in 19488ec).
Deferred (out-of-scope follow-ups)
- (panel) Whole-file owner exemptions,
canonical_targetssecond derivation, comparison-shaped read detection, build_orchestrator's sharedapm.ymlloads -- scope boundary: hardening beyond the approved compilation-target policy check ignores the plural targets: key #3732 reader routing; no user scenario is broken on this head; suggested follow-up: one issue under compilation-target policy check ignores the plural targets: key #3732.
Regression-trap evidence (mutation-break gate)
test_architecture_owner_rule_mutations.py::test_manifest_target_declaration_guard_rejects_raw_readers[exempt-block|trailing-marker|raw-pop|body-marker]-- deleted the statement-scoped_target_exemption/ pop detection; tests FAILED as expected; guard restored.test_target_declaration_install_lifecycle.py::test_user_scope_singular_all_expands_without_claiming_it_was_omitted-- restored the old compile -g reader; test FAILED as expected; guard restored.test_target_declaration_install_lifecycle.py::test_undeployable_singular_target_is_rejected_before_any_write-- deleted thecommands/install.pypre-migration call; test FAILED as expected; guard restored.test_pipeline_preflight.py::test_pipeline_rejects_undeployable_manifest_target_before_any_write-- deleted the pipeline call; test FAILED as expected; guard restored.test_target_declaration_adjacent_commands_lifecycle.py::test_reinit_keeps_the_singular_all_deployment_setandtest_manifest_targets.py::test_reinit_prefill_expands_singular_all_with_install_spellings-- restored the oldprefill_names; tests FAILED as expected; guard restored.test_manifest_targets.py::test_strict_restriction_rejects_singular_all_combined_with_targets-- disabled the strict mixed-allcheck; test FAILED as expected; guard restored.
Lint contract
uvx ruff@0.15.12 check and format --check on CI paths, pylint R0801 (10.00/10), scripts/lint-auth-signals.sh and scripts/lint-architecture-boundaries.sh all silent at 60c8939.
CI
gh pr checks 3791: 23 pass, 3 skipping, 0 fail at 60c8939 (CI, Merge Gate, Spec conformance) (after 2 CI fix iteration(s)).
This panel is advisory. It does not block merge. Re-apply the
panel-review label after addressing feedback to re-run.
Generated by autopilot-pr-merge-worker. This comment is AI-generated and may contain errors.
…61-t2-target-declaration #3774 landed, so this branch now carries only the PR-2 delta. Kept the PR-2 target-vocabulary mutation test after #3774's projection test, and rebuilt the [Unreleased] CHANGELOG block from main plus the #3791 entry. apm-spec-waiver: merge of main only; no new spec-observable behavior in this commit Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
apm-spec-waiver: merge of main only; no new spec-observable behavior in this commit Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Description
Stacked on #3774 (merge that first; this branch contains it, so until then review commit 6499c3e only).
#3732's root cause was that the package-level
target:/targets:declaration had an owner in name only: six modules re-read or re-parsedapm.ymlwith their own rules, and a static guard only scanned three files. #3774 fixed the policy projection. This PR gives the declaration one real owner, routes every reader through it, and makes the guard deny-by-default so the next raw reader fails lint.User scenarios, before and after
apm installwithtarget: intellijortarget: copilot-appinapm.yml.github/,.gitignore,apm.lock.yaml, then exits 2 "Unknown target"-g)apm installwithtarget: alltargets: [all]still warns, correctly)apm init --yesre-run in a project withtarget: alltargets: [all], which narrows deployment to auto-detect; the next install can fail "Multiple harnesses detected"compilation.targetinapm.ymltargets:Everything else is behavior-neutral: same accepted spellings per key, same MCP destinations (
vscodestill writes.vscode/mcp.json), same lockfile reconciliation, compile and pack selections.How
ManifestTargetDeclarationinmodels/manifest_targets.py(spelling, per-spelling validation, legacyall,selection,canonical,restriction(),explicit,validate_for_install(),prefill_names()), exposed asAPMPackage.target_declaration,package_target_declaration(),read_manifest_target_declaration(path, lenient=)andmanifest_target_restriction(mapping)._read_yaml_targets,_package_fieldremoved), MCP integration and both MCP integrators, lockfile reconciliation, build orchestrator,read_manifest_target(audit replay / drift / scanner), package-target filter (vars()read removed), and init re-init prefill.run_install_pipelinecallsvalidate_for_install()before any write (decision C1).registry-delegation-target-vocabularyis widened from a 3-file allowlist to deny-by-default AST scanning ofsrc/apm_cli/**: raw.target/.targetson package receivers,getattr/.get/subscript/inon the target keys,_package_field, and calls to the target parsers outside the owner modules. Reads of other decisions carry# architecture-authority-exempt: <concept>with a closed concept list (dependency-target-subset,policy-schema,bundle-pack-metadata,ledger-row,display-row,bootstrap-writer,compilation-target-field); an unknown concept is itself a violation.manifest-target-declarationwith guardregistry-delegation-manifest-target-declaration(same rule). Themutation_writes.mcp_target_selectionrule now pins the owner calls. MutationCase plus four extra mutation tests (audit raw.get, install-gategetattr, compile re-parse, unknown exemption concept).0.37 follow-ups (owned by the 0.37 captain, not here): the
target:deprecation warning andapm manifest migrate. The declaration exposesspelling,source_path,legacy_allandexplicitas their seam.Issue and approved scope
Issue: Refs #3732
Human scope-approval comment: #3732 (comment)
Does this PR complete the issue, or what remains? #3774 fixes the reporter's scenario and closes #3732. This PR completes the rest of the approved scope (declaration owner, deny-by-default guard, install pre-write rejection,
compilation.targetdocs).Type of change
Testing
Validation evidence (local, macOS, Python 3.12, real binary for e2e):
APM_E2E_TESTS=1 APM_BINARY_PATH=.venv/bin/apm pytest -p no:xdist tests/integration/test_target_declaration_install_lifecycle.py tests/integration/test_target_declaration_adjacent_commands_lifecycle.py-- 18 passed. These red-team scenarios cover pre-write rejection (project and-g), theallwarning, MCP destination by spelling, user-scope reads, dependencytargets:subsets through compile/deps/view/frozen/update/export-patch/uninstall/prune, and init re-init. Against v0.36.0 the pre-write,all-warning and re-init cells fail.pytest -p no:xdist tests/unit/models tests/unit/install/phases tests/unit/core/test_build_orchestrator.py tests/unit/policy tests/unit/test_target_filter.py tests/unit/integration/test_mcp_integrator.py tests/unit/install/test_policy_target_check_phase.py tests/unit/compilation/test_compile_target_flag.py tests/unit/test_init_command*.py tests/unit/scripts/test_architecture_runner.py tests/unit/scripts/test_architecture_registry.py tests/spec_conformance/test_manifest_reqs.py-- 2396 passed.pytest -p no:xdist tests/integration/test_architecture_owner_rule_mutations.py tests/integration/test_architecture_confirmed_bypass_mutations.py tests/integration/test_architecture_install_compound_mutations.py-- passed.uvx ruff@0.15.12 check/format --check(CI paths), pylint R0801 10.00/10,bash scripts/lint-auth-signals.sh, andbash scripts/lint-architecture-boundaries.sh-- all clean.Spec conformance (OpenAPM v0.1)
CONFORMANCE.{md,json}regeneratedapm-spec-waiver: routes existing manifest target readers through one owner; OpenAPM-observable acceptance is unchanged