[bug] policy inheritance: child without unmanaged_files block silently downgrades parent's action: deny

[danielmeppiel]

Summary

When a child policy declares extends: org but does NOT redeclare an unmanaged_files: block, the merged policy's unmanaged_files.action is silently downgraded to the model's default (ignore) instead of inheriting the parent's deny.

The _escalate(_UNMANAGED_ACTION_LEVELS, parent.action, child.action) call at src/apm_cli/policy/inheritance.py:198 correctly takes the max, but the child.unmanaged_files for a child that omits the block is not "no opinion" — it's UnmanagedFilesPolicy(action='ignore', directories=()). So max('deny', 'ignore') == 'deny' should hold but the resulting merged check reports as disabled.

Repro

org/.github/apm-policy.yml:

name: org
version: "1.0.0"
enforcement: block
unmanaged_files:
  action: deny
  directories:
    - .github/instructions
    - .github/agents
    - .github/hooks

repo/apm-policy.yml:

name: child
version: "1.0.0"
extends: org
enforcement: block
dependencies:
  deny:
    - "**/some-pattern"
# (no unmanaged_files block)

Add an unmanaged file (e.g. .github/hooks/sneaky.hook.md) and run:

apm audit --ci --policy ./apm-policy.yml

Expected: unmanaged-files check fails with action deny inherited from org.

Actual: [+] unmanaged-files | Unmanaged files check disabled (action: ignore) and the audit passes.

Workaround

Redeclare the unmanaged_files block in every override that should preserve the parent's posture:

extends: org
unmanaged_files:
  action: deny
  directories:
    - .github/agents
    - .github/instructions
    - .github/hooks

This loses the value proposition of extends: (single source of truth at the org root) — the override has to mirror the parent's directory list verbatim, which is exactly what the inheritance feature is supposed to avoid.

Suggested fix

Two routes:

1. Make the model field on UnmanagedFilesPolicy distinguish "default" from "explicitly set". A child that did NOT declare unmanaged_files: should be treated as transparent in _merge_unmanaged_files, returning parent unchanged. (Mirrors how _intersect_allow treats None as "no opinion".)
2. Or: at parse time, propagate parent values into any child block fields the child did not explicitly set, before invoking the merge.

The first is cleaner because it matches the rest of the inheritance.py contract.

Affected versions

Reproduced with apm v0.x (current main). Same logic at src/apm_cli/policy/inheritance.py:194-200.

Impact

Org-wide governance posture silently weakens whenever a team adds a repo override for an unrelated policy area (e.g. extra dependency deny patterns). Hard to detect — apm audit --policy org shows the right floor, but apm audit --policy ./apm-policy.yml (which the consumer typically runs in CI for layered enforcement) silently ignores the floor for unmanaged_files.

[github-actions]

Triage decision

accept

Proposed labels

theme/governance
area/audit-policy
area/content-security
type/bug
status/accepted
priority/high

Milestone

0.12.5 (recommended; unable to apply programmatically -- milestone number not resolvable without authenticated CLI)

Suggested next action

Fix UnmanagedFilesPolicy in inheritance.py to distinguish an omitted unmanaged_files: block (transparent -- inherit parent) from an explicitly set action: ignore (override), mirroring how _intersect_allow treats None as "no opinion."

Suggested issue comment

Thanks for the detailed repro and the two proposed fix routes -- this is a confirmed bug in the policy inheritance merge logic.

The root cause is that `UnmanagedFilesPolicy(action='ignore', directories=())` is the Python default for an omitted `unmanaged_files:` block, and the merge code cannot distinguish "child said nothing" from "child explicitly set action: ignore." So the escalation call never has a chance to win.

**Accepted.** Route 1 (make the field sentinel-aware -- treat a missing block as "no opinion" and return parent unchanged) is the right fix. It mirrors the pattern `_intersect_allow` already uses for allow-list fields and avoids requiring callers to redeclare the entire parent block.

The fix lives in `src/apm_cli/policy/inheritance.py` around lines 194-200. Any place that constructs `UnmanagedFilesPolicy` from YAML input (the parser) will also need to distinguish "key absent" from "key present with value ignore."

Target: 0.12.5 patch. If you would like to send a PR, that would be very welcome -- the fix is narrowly scoped and the test harness for `inheritance.py` is solid. A regression test reproducing the org+child fixture from this report would make a good addition.

See the governance policy reference for the documented behavior: (microsoft.github.io/redacted)

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

The extends: org mechanism is positioned as the single-source-of-truth governance primitive -- a repo override should inherit every parent field unless it explicitly overrides it. The silent downgrade of unmanaged_files: action: deny to ignore breaks this contract: a team adding an unrelated deny pattern for dependencies now unwittingly removes the org's unmanaged-file floor. This is exactly the failure mode extends: is meant to prevent. The mental model is clear and the bug is well-scoped.

Supply Chain Security Expert -- Risk-Surface Reviewer

unmanaged_files: action: deny is APM's primary guardrail against unauthorized content in .github/instructions/, .github/agents/, and .github/hooks/. A silent downgrade at the inheritance merge step means org-level policy can be quietly eroded by any repo that adds an override for an unrelated dimension. The affected surfaces are area/audit-policy (the policy engine merge logic) and area/content-security (the governance directories the check protects). theme/governance is required.

OSS Growth Hacker -- Contributor-Tone Reviewer

Not activated -- danielmeppiel is a COLLABORATOR with extensive prior interactions; tone adjustment for a new contributor is not needed.

Python Architect -- Architecture Reviewer

The fix is feasible and narrowly scoped to inheritance.py. Route 1 (Optional/sentinel semantics on UnmanagedFilesPolicy.action) is cleaner than Route 2 (pre-propagation at parse time) because it localizes the "no opinion" concept to the merge layer, matching the existing _intersect_allow pattern. Cross-cutting impact: the YAML parser for UnmanagedFilesPolicy must emit None (or a sentinel) when the block is absent, rather than constructing the default instance. Any callers that assume action is always a string will need a null-guard. The scope is narrow enough for status/accepted without a prior design doc.

Doc Writer -- Documentation Reviewer

Not activated -- the fix is an internal inheritance merge logic change with no new user-facing CLI surface. The existing policy reference page already documents the intended extends: behavior; no new pages are required. A brief note in CHANGELOG.md about the bug fix is sufficient.

APM CEO -- Triage Arbiter

This is a confirmed, reproducible governance regression with a clear fix path and no design ambiguity. The silent downgrade of a security-enforcing policy field is exactly the kind of quiet failure that erodes trust in the governance layer. Accepting at priority/high for the 0.12.5 patch. The Python Architect's Route 1 recommendation aligns with the existing codebase conventions; no design doc needed. The fix for #1198 and #1201 likely lives in the same PR since they share the same root cause.

{
  "decision": "accept",
  "decision_detail": "",
  "theme": "theme/governance",
  "areas": ["area/audit-policy", "area/content-security"],
  "type": "type/bug",
  "status": "status/accepted",
  "priority": "priority/high",
  "preserved_labels": [],
  "milestone": "0.12.5",
  "next_action": "Fix UnmanagedFilesPolicy in inheritance.py to treat an absent unmanaged_files block as transparent (inherit parent), not as action: ignore.",
  "comment_markdown": "Thanks for the detailed repro and the two proposed fix routes -- this is a confirmed bug in the policy inheritance merge logic.\n\nThe root cause is that `UnmanagedFilesPolicy(action='ignore', directories=())` is the Python default for an omitted `unmanaged_files:` block, and the merge code cannot distinguish \"child said nothing\" from \"child explicitly set action: ignore.\" So the escalation call never has a chance to win.\n\n**Accepted.** Route 1 (make the field sentinel-aware -- treat a missing block as \"no opinion\" and return parent unchanged) is the right fix. It mirrors the pattern `_intersect_allow` already uses for allow-list fields and avoids requiring callers to redeclare the entire parent block.\n\nThe fix lives in `src/apm_cli/policy/inheritance.py` around lines 194-200. Any place that constructs `UnmanagedFilesPolicy` from YAML input (the parser) will also need to distinguish \"key absent\" from \"key present with value ignore.\"\n\nTarget: 0.12.5 patch. If you would like to send a PR, that would be very welcome -- the fix is narrowly scoped and the test harness for `inheritance.py` is solid. A regression test reproducing the org+child fixture from this report would make a good addition.\n\nSee the governance policy reference for the documented behavior: (microsoft.github.io/redacted)
}

---

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.

Note

🔒 Integrity filter blocked 12 items

The following items were blocked because they don't meet the GitHub integrity level.

• #1120 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1122 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1130 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1138 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1156 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1157 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1195 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1203 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1209 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1210 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1220 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1222 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".

To allow these resources, lower min-integrity in your GitHub frontmatter:

tools:
  github:
    min-integrity: approved  # merged | approved | unapproved | none

Generated by Triage Panel · ● 1.1M · ◷