feat(policy): enforce apm-policy.yml at install time

CHANGELOG.md

@@ -11,16 +11,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - `pr-review-panel` gh-aw workflow that runs `apm-review-panel` on PRs labelled `panel-review` and posts a synthesized verdict via `safe-outputs.add-comment` (#824)
+- `--no-policy` flag on `apm install` / `install <pkg>` / `install --mcp` and `APM_POLICY_DISABLE=1` env var to skip org policy enforcement for a single invocation; loudly logged and does NOT bypass `apm audit --ci` (#827)
+- `apm install --dry-run` previews policy verdicts ("would be blocked by policy") without writing files (#827)
+- `apm install <pkg>` rolls back `apm.yml` to its pre-mutation snapshot when the install pipeline fails a policy check (#827)
+- `policy.fetch_failure: warn|block` schema knob on `apm-policy.yml` and matching project-side `policy.fetch_failure_default` opt-in in `apm.yml`: when set to `block`, install / `apm audit --ci` fail closed if the org policy cannot be fetched, parsed, or returns garbage. Both default to `warn` for backwards compatibility (closes #829)
+- `apm policy status` diagnostic command: prints discovery outcome, source, enforcement, cache age, `extends:` chain, and rule counts in table or `--json` form. Default exit is 0 (safe for human / SIEM use); pass `--check` to exit 1 when no usable policy is resolved, suitable for CI pre-checks. Supports `--policy-source` and `--no-cache` overrides (#827, #832)
+- `apm audit --ci` auto-discovers the org policy when `--policy-source` (alias `--policy`) is not provided, mirroring the install-time discovery path so CI catches sideloaded files via unmanaged-files checks; `--no-policy` flag added to skip discovery for a single invocation (#827)
 
 ### Changed
 
 - Docs site publishes on stable release only, not every push to `main`. Closes #641 (#822)
 - Dogfood APM: moved authored skills, agents, and instructions to `.apm/` as the source of truth; `.github/{skills,agents,instructions}/` are now regenerated by `apm install --target copilot` and remain committed (#823)
+- Install pipeline gains `policy_gate` (after resolve, before targets) and `policy_target_check` (after targets) phases; 9 policy-fetch outcomes routed through shared chain discovery with atomic cache writes and `MAX_STALE_TTL` fallback (#827)
+- Consolidated `PolicyBlockError` and `PolicyViolationError` into a single `PolicyViolationError` class in `apm_cli.install.errors`; `PolicyBlockError` remains a back-compat alias re-exported from `apm_cli.policy.install_preflight` (#832)
+- Extracted the 9-outcome policy-discovery routing table into `apm_cli.policy.outcome_routing.route_discovery_outcome()`; both the install pipeline gate and the MCP preflight now delegate to one shared implementation (#832)
+- Removed the unused `no_policy=` parameter from `discover_policy_with_chain`; callers should use the documented `APM_POLICY_DISABLE=1` env var or the `--no-policy` CLI flag instead (#832)
+- `apm audit --no-policy` help text rewritten to describe the positive behaviour ("Skip org policy discovery and enforcement. Overridden when --policy is passed explicitly.") so `apm audit --help` no longer hides the primary effect behind a negative caveat (#832)
 
 ### Removed
 
 - Legacy `.github/prompts/` and `.github/chatmodes/` that pre-dated the skill/agent primitive model (#823)
 
+### Security
+
+- `apm install` now enforces org `apm-policy.yml` at install time, not only in `apm audit --ci` — covering dependency deny/allow/required lists, MCP server deny/transport/trust-transitive rules, and `compilation.target.allow` constraints; transitive MCP servers from APM packages are checked before runtime config is written (#827)
+  - **Migration**: If your org publishes `enforcement: block`, your next `apm install` may fail where it previously succeeded. Preview verdicts with `apm install --dry-run` before upgrading.
+- `policy.hash` pin in `apm.yml` (with optional `policy.hash_algorithm: sha256|sha384|sha512`) for consumer-side verification of fetched org-policy bytes -- the `pip --require-hashes` equivalent for `apm-policy.yml`. A mismatch is always fail-closed regardless of `policy.fetch_failure` setting and closes the compromised-intermediary / captive-portal / garbage-response vector where a 200 OK with valid-looking but tampered YAML would otherwise install (#827)
+- `apm install` policy cache directory is now validated with `ensure_path_within(_, project_root)` after symlink resolution, closing a path-escape vector where an attacker-controlled `apm_modules` symlink could redirect cache writes outside the project tree (#832)
+
+### Fixed
+
+- Warn-mode policy violations now render in the `apm install` summary (previously recorded but not displayed because logger and install_result used different `DiagnosticCollector` instances) (#827, closes #834)
+- `apm-policy.yml` `extends:` chains now support N-level inheritance up to `MAX_CHAIN_DEPTH=5` with cycle detection and partial-chain warnings; previously only one parent level was resolved (#827, closes #831)
+- `apm install` no longer emits the `[i] No git remote configured -- skipping organization policy discovery` line in non-verbose runs; the message now requires `--verbose`, matching how other discovery-miss outcomes are gated (#832)
+- `apm install` policy violations are surfaced verbatim instead of being double-nested under `Failed to install ... Failed to resolve ... Install blocked by org policy` (#832)
+- Per-dependency policy block messages fall back to `check.name` when `check.details` is empty, preventing rare empty-string blocks (#832)
+
 ## [0.9.0] - 2026-04-21
 
 ### Changed (BREAKING)

docs/src/content/docs/enterprise/governance.md

@@ -133,6 +133,8 @@ For step-by-step setup including SARIF integration and GitHub Code Scanning, see
 
 `apm audit --ci --policy org` enforces organization-wide rules defined in `apm-policy.yml`. This adds 16 policy checks on top of the 6 baseline checks.
 
+Policy enforcement applies at both `apm install` (blocks before files are written) and `apm audit --ci` (CI gate). See [Install-time enforcement](../policy-reference/#install-time-enforcement).
+
 ### How it works
 
 1. **Define policy** — create `apm-policy.yml` in your org's `.github` repository.