Skip to content

refactor(targets): route every manifest target reader through one owner - #3791

Merged
Daniel Meppiel (danielmeppiel) merged 18 commits into
mainfrom
danielmeppiel-0361-t2-target-declaration
Nov 18, 2026
Merged

Daniel Meppiel (danielmeppiel) merged 18 commits into
mainfrom
danielmeppiel-0361-t2-target-declaration

Conversation

@danielmeppiel

Copy link
Copy Markdown
Collaborator

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-parsed apm.yml with 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

Scenario Before After
apm install with target: intellij or target: copilot-app in apm.yml writes .github/, .gitignore, apm.lock.yaml, then exits 2 "Unknown target" exits 2 with the same error before writing anything (project and -g)
apm install with target: all deploys to every target, then also prints "'all' ... is deprecated ... treating the field as omitted" deploys to every target; no contradictory warning (targets: [all] still warns, correctly)
apm init --yes re-run in a project with target: all rewrites it to targets: [all], which narrows deployment to auto-detect; the next install can fail "Multiple harnesses detected" writes the explicit expansion, so the deployment set is unchanged
compilation.target in apm.yml documented as the output target, silently ignored documented as ignored; use top-level targets:

Everything else is behavior-neutral: same accepted spellings per key, same MCP destinations (vscode still writes .vscode/mcp.json), same lockfile reconciliation, compile and pack selections.

How

  • Owner: ManifestTargetDeclaration in models/manifest_targets.py (spelling, per-spelling validation, legacy all, selection, canonical, restriction(), explicit, validate_for_install(), prefill_names()), exposed as APMPackage.target_declaration, package_target_declaration(), read_manifest_target_declaration(path, lenient=) and manifest_target_restriction(mapping).
  • Routed readers: compile CLI, install targets phase (_read_yaml_targets, _package_field removed), 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.
  • Install pre-write check: run_install_pipeline calls validate_for_install() before any write (decision C1).
  • Guard: registry-delegation-target-vocabulary is widened from a 3-file allowlist to deny-by-default AST scanning of src/apm_cli/**: raw .target/.targets on package receivers, getattr/.get/subscript/in on 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.
  • Registry: new owner manifest-target-declaration with guard registry-delegation-manifest-target-declaration (same rule). The mutation_writes.mcp_target_selection rule now pins the owner calls. MutationCase plus four extra mutation tests (audit raw .get, install-gate getattr, compile re-parse, unknown exemption concept).

0.37 follow-ups (owned by the 0.37 captain, not here): the target: deprecation warning and apm manifest migrate. The declaration exposes spelling, source_path, legacy_all and explicit as 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.target docs).

Type of change

  • Bug fix
  • New feature
  • Documentation
  • Maintenance / refactor

Testing

  • Tested locally
  • All existing tests pass
  • Added tests for new functionality (if applicable)

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), the all warning, MCP destination by spelling, user-scope reads, dependency targets: 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.
  • Broader pre-merge batch over the MCP/LSP integration, targets, reconcile, compile and pack tests -- 3165 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, and bash scripts/lint-architecture-boundaries.sh -- all clean.

Spec conformance (OpenAPM v0.1)

  • Spec edit
  • Manifest edit
  • Test edit
  • CONFORMANCE.{md,json} regenerated
  • N/A -- manifest acceptance is unchanged; install now rejects, before writing, tokens it already rejected after writing (closer to the spec's "reject before target-scoped deployment").

apm-spec-waiver: routes existing manifest target readers through one owner; OpenAPM-observable acceptance is unchanged

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
@danielmeppiel Daniel Meppiel (danielmeppiel) added this to the 0.36.1 milestone Nov 17, 2026
Copilot AI balanced review requested due to automatic review settings November 17, 2026 17:20
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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 ManifestTargetDeclaration and routes install, compile, MCP, reconciliation, and re-init readers through it.
  • Adds early install validation, preserves legacy all behavior, 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

Comment thread src/apm_cli/install/pipeline.py Resolved
Comment thread src/apm_cli/models/manifest_targets.py Resolved
@danielmeppiel

Copy link
Copy Markdown
Collaborator Author

APM Review Panel: ship_with_followups

PR #3791 puts manifest target reads behind one owner and rejects undeployable targets before install writes anything. One reader still bypasses that owner, and guard exemptions cover more code than intended.

panel-mode=lean; personas=python-architect,test-coverage-expert,apm-ceo

cc Sergio Sisternes (@sergio-sisternes-epam) -- a fresh advisory pass is ready for your review.

Scope reviewed: the PR-2 delta only (18fbe820a0..456a637dbc); #3774's commits were reviewed on that PR.

The two panelists agree on the main points. The owner design (ManifestTargetDeclaration and its helpers) holds up, and install now validates before it writes. Three of the claimed scenarios have passing real-binary regression tests. Two gaps fall inside the approved PR-2 scope, so they should be fixed in this PR rather than deferred. First, the approved scope says every reader goes through the owner and that target: all stops warning. But apm compile -g still uses core/apm_yml.read_declared_target_names, which reloads apm.yml itself and, with target: all, still prints the "deprecated, treating the field as omitted" warning this PR removes from install. Four other modules also load apm.yml themselves, while read_manifest_target_declaration has no callers in src/. Second, the deny-by-default guard's exemption marker covers whole blocks: adding leaked = package.targets inside an exempted if-block in commands/_helpers.py produced 0 violations, while the same line outside the block was flagged. Whole-file owner exemptions, the canonical_targets normalization drift and extra detector shapes are real but can wait for a tracked follow-up. apm targets ignoring the manifest, the target: deprecation and apm manifest migrate stay out of scope.

Aligned with: Portable by manifest -- one owner now interprets declared targets, and install, init and pack agree on target: all; compile -g still diverges. Governed by policy -- deny-by-default only counts once an exemption covers just the marked statement. Secure by default -- install with target: intellij / copilot-app exits 2 before writing anything. Pragmatic as npm -- target: all deploys everything without a contradictory warning, and init re-runs keep what the user wrote.

Panel summary

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

  1. [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:365 and :487) through read_manifest_target_declaration, with one leniency parameter. Add an e2e test: apm compile -g with target: all prints no deprecation warning. -- One command still prints the warning this PR removes, so the PR's main claim is only partly true.
  2. [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.
  3. [Test Coverage Expert] Fold now (small). Parametrize test_undeployable_singular_target_is_rejected_before_any_write over project and -g scope. -- Scenario 1 claims both scopes; only project scope has a regression trap (the -g path passes an ad-hoc probe today).
  4. [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; derive APMPackage.canonical_targets from target_declaration.canonical (for targets=['all'] they give ('all',) vs ()); guard canonical_targets reads in hook_integrator.py:1962, uninstall/engine.py:1151, uninstall/cli.py:705. -- Real drift risk, but no user scenario is broken on this commit.
  5. [Python Architect] Defer (or fold if cheap with item 2). Extend _raw_target_read to catch k == "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_read does not flag k == "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 by apm compile -g) skips the owner and still prints the singular 'all' warning this PR removes elsewhere at src/apm_cli/core/apm_yml.py:191
    Verified with target: all: prints "'all' in apm.yml targets is deprecated ... treating the field as omitted". read_manifest_target_declaration has no callers in src/; target_detection.read_manifest_target:1027, manifest_reconcile.declared_target_profiles:396, build_orchestrator.py:365 and :487 each load apm.yml with different leniency.
    Suggested: Rebuild read_declared_target_names on read_manifest_target_declaration(...).restriction(); route the other readers through it; add an e2e apm compile -g step.
  • [recommended] The owner exemption covers whole files, and APMPackage.canonical_targets is still a second projection read raw by 3 call sites at src/apm_cli/models/apm_package.py:536
    _TARGET_DECLARATION_OWNERS exempts all of core/target_detection.py and core/apm_yml.py. __post_init__ derives canonical_targets with its own normalization; for targets=['all'] it gives ('all',) while the declaration folds to ().
    Suggested: FunctionDef-scoped exemption; derive canonical_targets from target_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 via run_selected_rules with source_overrides: leaked = package.targets inside the bootstrap-writer-exempt if-block in commands/_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 -g with target: intellij or copilot-app in ~/.apm/apm.yml exits 2 before any write at tests/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.json changed. 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 -g with 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 the stacked base PR 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>
@danielmeppiel

Copy link
Copy Markdown
Collaborator Author

APM Review Panel: ship_with_followups

PR #3791 makes one module the single owner of the manifest's target declaration. Since the first advisory, every in-scope fold has landed and been checked by deliberately breaking each guard and watching its test fail.

panel-mode=delta; personas=python-architect,test-coverage-expert,apm-ceo

cc Sergio Sisternes (@sergio-sisternes-epam) -- a fresh advisory pass is ready for your review.

Since the first advisory, which recommended ship_with_followups with three in-scope folds, all three folds landed in 19488ec, and the delta panel's three remaining findings landed in 80f6976. Python-architect raised two of them. First, a comment-only marker above a block's first statement could exempt raw reads in the enclosing header; header ranges now exclude trailing comment lines, match headers end at the first case, and a new mutation case enforces this. Second, apm compile -g silently compiled every harness for a singular target: all,<x>; the strict restriction now raises TargetResolutionError, matching how apm install -g already rejects that value. Test-coverage-expert raised the third: no test exercised run_install_pipeline's own pre-write gate. A direct test now asserts that intellij and copilot-app exit 2 with no writes. For each fold, the guard was removed, the test confirmed to fail, then the guard restored. Both Copilot inline threads were real defects; both are fixed and resolved. A CHANGELOG auto-merge that had duplicated a Fixed section is repaired, and head 60c8939 is mergeable with CI at 23 passing and 3 skipping. What remains is deferred hardening of owner scope, outside the #3732 scope.

Aligned with: Portable by manifest -- every reader of the target declaration goes through one owner, and target: all behaves the same in install, init and compile -g. Secure by default -- unsupported targets are rejected before install writes anything, at project and -g scope. Governed by policy -- the guard denies by default, with exemptions from a closed list of named concepts, each bound to the statement it marks. Pragmatic as npm -- the contradictory all warning is gone and re-init keeps the declared intent.

Panel summary

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

  1. [Python Architect] Narrow the whole-file owner exemptions on core/target_detection.py and core/apm_yml.py to the parser functions only. -- A new raw target read added to either file would pass the deny-by-default guard unnoticed.
  2. [Python Architect] Derive APMPackage.canonical_targets from target_declaration.canonical, and move its raw readers (hook_integrator, uninstall engine and CLI) onto the owner. -- For targets: [all] it gives ('all',) while the owner gives ().
  3. [Python Architect] Detect comparison-shaped reads (k == "targets") without false positives on CLI key names, and route build_orchestrator's two apm.yml loads through read_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's read_manifest_target and install's declared_target_profiles read through read_manifest_target_declaration; read_declared_target_names removed; compile -g no longer prints the all warning -- 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 -g pre-write rejection e2e -- resolved in 19488ec.
  • (CI, T2 captain) install/pipeline.py LOC budget: pre-write check moved to reject_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; direct run_install_pipeline gate test -- resolved in 80f6976.

Copilot signals reviewed

  • src/apm_cli/install/pipeline.py:443 -- LEGIT: a legacy apm.lock was renamed before the rejection; the check now also runs before migrate_lockfile_if_needed (resolved in 19488ec).
  • src/apm_cli/models/manifest_targets.py:155 -- LEGIT: re-init rewrote target: all with 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)

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 the commands/install.py pre-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_set and test_manifest_targets.py::test_reinit_prefill_expands_singular_all_with_install_spellings -- restored the old prefill_names; tests FAILED as expected; guard restored.
  • test_manifest_targets.py::test_strict_restriction_rejects_singular_all_combined_with_targets -- disabled the strict mixed-all check; 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>
@danielmeppiel
Daniel Meppiel (danielmeppiel) merged commit dfb6a83 into main Nov 18, 2026
26 checks passed
@danielmeppiel
Daniel Meppiel (danielmeppiel) deleted the danielmeppiel-0361-t2-target-declaration branch November 18, 2026 02:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

compilation-target policy check ignores the plural targets: key

2 participants