Merge branch 'main' into feat/1243

Author: danielmeppiel

.github/workflows/ci.yml

@@ -127,10 +127,13 @@ jobs:
         retention-days: 30
         if-no-files-found: error
 
-  # Dogfood the two CI gates we ship and document to users:
-  #   - Gate A (consumer-side): `apm audit --ci` -- lockfile / install fidelity.
-  #   - Gate B (producer-side): regeneration drift -- did someone hand-edit
-  #     a regenerated file under .github/ without updating canonical .apm/?
+  # Dogfood the audit-only CI gate we ship and document to users:
+  #   - Gate A (consumer-side): `apm audit --ci --no-drift` -- lockfile /
+  #     content-integrity check. setup-only: true keeps managed files
+  #     untouched so the SHA-256 content-integrity check can detect tampered
+  #     files. The drift check (install-replay comparison) is skipped
+  #     via --no-drift because there is no warm cache in a setup-only
+  #     run; content-integrity covers the same tamper signal.
   # See microsoft/apm#883 for context. Tier 1 (no secrets needed).
   apm-self-check:
     name: APM Self-Check
@@ -140,32 +143,30 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      # Installs the APM CLI (latest stable) and runs `apm install` against
-      # this repo's apm.yml. Auto-detects target from the existing .github/
-      # directory and re-integrates local .apm/ content, regenerating
-      # .github/instructions/, .github/agents/, .github/skills/, etc.
-      # Adds `apm` to PATH for subsequent steps.
+      # Installs the APM CLI (latest stable) and adds `apm` to PATH.
+      # setup-only: true skips `apm install` so managed files on disk are
+      # not overwritten before the audit runs. This preserves the committed
+      # state so content-integrity can detect any tampered file hashes.
       - uses: microsoft/apm-action@v1
+        with:
+          setup-only: true
 
       # Gate A: lockfile / install fidelity (consumer-side).
       # Verifies every file in lockfile.deployed_files exists, ref consistency
       # between apm.yml and apm.lock.yaml, no orphan packages, and
-      # content-integrity (hidden Unicode) on deployed package content.
-      # Does NOT verify deployed-file content vs lockfile (see #684).
-      - name: apm audit --ci
-        run: apm audit --ci
-
-      # Gate B: regeneration drift (producer-side).
-      # NOTE: Once `apm-action` ships a CLI version that includes the
-      # default-on `apm audit` drift detection (issue #1071), this entire
-      # step becomes redundant -- Gate A above already catches the same
-      # divergence via install-replay. Keep this bash check until then as
-      # a defense-in-depth fallback.
-      #
-      # The action's `apm install` step re-integrated local .apm/ into
-      # .github/ via target auto-detection. If anything in the governed
-      # integration directories changed, someone edited the regenerated
-      # output without updating the canonical .apm/ source.
+      # content-integrity (SHA-256 hashes against deployed_file_hashes in the
+      # lockfile) on deployed package content. --no-drift skips the
+      # install-replay because there is no warm cache (setup-only did not
+      # run apm install); content-integrity still catches tampered files.
+      - name: apm audit --ci --no-drift
+        run: apm audit --ci --no-drift
+
+      # Gate B: regeneration drift (producer-side) -- legacy bash fallback.
+      # NOTE: With setup-only: true this step is a guaranteed no-op.
+      # apm install did not run and the working tree is unchanged, so the
+      # git status check always finds nothing. It is kept so the pattern is
+      # visible; a full install+audit workflow would rely on this step to
+      # detect hand-edits to regenerated .github/ files.
       - name: Check APM integration drift (legacy bash fallback, see #1071)
         run: |
           if [ -n "$(git status --porcelain -- .github/ .claude/ .cursor/ .opencode/)" ]; then

CHANGELOG.md

@@ -13,12 +13,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- Non-skill integrators (agent, instruction, prompt, command, hook script-copy) silently adopt byte-identical pre-existing files so a degraded `deployed_files=[]` lockfile no longer permanently blocks installs gated by `required-packages-deployed`. (#1313)
+- `apm audit` drift check now returns skip-with-info (`passed=True`) when the install cache is cold, instead of failing the audit; bare `apm audit` surfaces the skip reason on stderr so CI pipelines that have not yet run `apm install` are not incorrectly red-marked. (#1289)
+- `extends: org` now correctly layers `dependencies.require` and `dependencies.deny` from the parent policy when the child omits the `dependencies:` block entirely; `None` signals "no opinion" (transparent) while `[]` signals explicit override. (#1290)
+- CI self-check job now uses `setup-only: true` + `apm audit --ci --no-drift` so managed files are not overwritten by `apm install` before `content-integrity` runs; documented the audit-only CI pattern and the install-before-audit blind spot in the enterprise and CI/CD guides. (#1291)
 - Pin `Path.home()` under unit tests via a session-scoped autouse conftest fixture, fixing 56 Windows runner failures on the new `windows-2025-vs2026` GitHub-hosted image where `USERPROFILE`/`HOMEDRIVE`+`HOMEPATH` are not seeded for pytest workers; also patch the `_check_and_notify_updates` import binding in the disabled-self-update test so it no longer races on the version-check cache. (#1270)
 - `apm install` now works on macOS git 2.53.0 (Homebrew): bare-cache commands switch to `--git-dir` to satisfy the `safe.bareRepository=explicit` default; fetched SHAs are pinned as synthetic refs so `git clone --local --shared` no longer silently omits them. (#1268)
 - Set the unit-test hermetic HOME at conftest import time so a single xdist worker on the `windows-2025-vs2026` runner can no longer race fixture setup and re-trigger the 53 `Path.home()` failures the session-scoped autouse fixture was supposed to prevent. (#1271)
 - Override `Path.home()` itself in the root test conftest so the 46 remaining Windows `RuntimeError: Could not determine home directory` failures on xdist worker `gw2` cannot recur regardless of which conftest the worker imports first; per-test `monkeypatch.setenv("HOME", ...)` continues to work because the override consults env vars before falling back to the hermetic tmp dir. (#1272)
 - Retry the `apm mcp search` and `apm mcp show` integration tests on the documented "Could not reach MCP registry" transient (with backoff and a final skip) so a brief `api.mcp.github.com` outage no longer red-marks the Windows integration job. (#1274)
 - Also wrap `Path.expanduser()` in the root test conftest so the `windows-2025-vs2026` runner cannot raise `RuntimeError("Could not determine home directory.")` from `ntpath.expanduser` when production code (e.g. `install.package_resolution.user_scope_rejection_reason`) calls `Path("~/pkg").expanduser()`. Falls back to the hermetic tmp dir; assertions about `~/pkg` being absolute still hold. (#1276)
+- `apm install` from marketplaces registered on `*.ghe.com` (GHE Cloud) hosts now routes auth at the registered enterprise host instead of silently defaulting to `github.com` and failing with 401; the marketplace resolver backfills the enterprise host onto the canonical so downstream `DependencyReference.parse` recovers it, and the resulting `apm.yml` entry records the correct enterprise `git:` URL instead of `https://github.com/...`. (#1292)
+- `apm view --help` and the `view` row in `apm --help` now render in release binaries; PyInstaller's `optimize=2` was stripping `__doc__` from every Click command, and `view` was the only command that relied on its docstring instead of the explicit `help=` kwarg every other command defensively sets. Lowered the spec to `optimize=1` so asserts are still removed but docstrings survive, restoring Click's documented help-from-docstring fallback for all current and future commands. (#1298)
 
 ## [0.13.0] - 2026-05-11
 
@@ -33,6 +39,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `apm install --frozen` performs a CI-safe, read-only install that fails fast (exit 1) when `apm.lock.yaml` is missing or out of sync with `apm.yml`; mutually exclusive with `--update`. (#1244)
 - Zero-config private-package auth on github.com, `*.ghe.com`, and GHES when the `gh` CLI is logged in: APM uses `gh auth token --hostname <host>` before falling back to `git credential fill`. (#630)
 - GitLab marketplace and install support: `gitlab.com` and self-managed instances (via `GITLAB_HOST` / `APM_GITLAB_HOSTS`) use GitLab REST v4 for `marketplace.json` and raw file reads; nested group paths are disambiguated via object-form `git:` + `path:`. (#1149)
+- **Windows installer parity:** CI and GHES/air-gapped runners can **pin `VERSION`**, set **`GITHUB_URL`** (https only) and **`APM_REPO`**, and use **`APM_INSTALL_DIR`** like `install.sh`. Pinned installs verify the release **`.sha256`** unless **`APM_SKIP_CHECKSUM=1`** or **`-SkipChecksum`** (emergency only); `GITHUB_URL` drives GitHub.com (`api.github.com`) vs GHES (`{host}/api/v3`) for latest discovery. (#668)
 - Virtual subdirectory and raw-file packages now resolve from self-hosted Git services (Gitea, Gogs) via raw URL with API v1/v3 fallback. (#587)
 - `git: parent` lets packages in a git monorepo reference sibling paths via `{ git: parent, path: ... }` without repeating the full `git:` URL; the lockfile stores expanded host, repo, and resolved ref like every other virtual git dependency. (#1149)
 - `shared/apm.md` gh-aw workflow exposes a `target:` import input (default `all`) so consumer workflows can ship slim, single-harness bundles. (#1184)

build/apm.spec

@@ -271,7 +271,7 @@ a = Analysis(
     win_private_assemblies=False,
     cipher=None,
     noarchive=False,
-    optimize=2,  # Python optimization level for smaller, faster binaries
+    optimize=1,  # -O: strip asserts; keep __doc__ so Click reads command help from docstrings (#1298)
 )
 
 # Exclude bundled OpenSSL shared libraries on Linux.

docs/src/content/docs/enterprise/drift-detection.md

@@ -42,9 +42,12 @@ lockfile-exists -> ref-consistency -> deployed-files-present
 After the baseline passes, it replays the install in a scratch directory
 from the cache and diffs against the working tree to surface
 `unintegrated`, `modified`, and `orphaned` files. Pass `--no-drift` to
-skip the replay. With `--policy <source>` it also evaluates the
-discovered policy against the lockfile. Source:
-`src/apm_cli/commands/audit.py`, `src/apm_cli/policy/ci_checks.py`.
+skip the replay. When the install cache has not been warmed yet (fresh
+checkout before the first `apm install`), the drift check is skipped
+with an informational message rather than failing; run `apm install` to
+warm the cache and enable the check on the next run. With `--policy
+<source>` it also evaluates the discovered policy against the lockfile.
+Source: `src/apm_cli/commands/audit.py`, `src/apm_cli/policy/ci_checks.py`.
 
 ### `apm audit` (default)
 
@@ -92,6 +95,40 @@ as either eviction-and-refetch (silent self-heal) or a hard failure
 when the cache cannot be repopulated -- never as wrong content under
 the right name.
 
+## Install before audit and tamper detection
+
+Running `apm install` before `apm audit --ci` is the correct pattern when
+the goal is detecting a developer who forgot to run `apm install` after
+editing `apm.yml`. The install step regenerates deployed files so the
+subsequent audit can compare them against the lockfile.
+
+That sequence has a blind spot: `apm install` overwrites every managed file
+with a clean copy before the audit runs. If a deployed file was modified on
+disk after the last install -- for example a hand-edit to
+`.github/instructions/` -- the install step restores the original bytes.
+The `content-integrity` check then compares the restored file against a
+matching hash and reports no finding.
+
+To detect post-install modification, use `setup-only: true` on the action
+so it only provides the CLI without running `apm install`, then audit with
+`--no-drift`:
+
+```yaml
+- uses: microsoft/apm-action@v1
+  with:
+    setup-only: true
+- run: apm audit --ci --no-drift
+```
+
+`--no-drift` skips the install-replay (which requires a warm cache that
+`setup-only` does not populate). The `content-integrity` check verifies
+SHA-256 hashes of every deployed file against `deployed_file_hashes` in
+`apm.lock.yaml` without needing to replay the install. Any byte-level
+change to a deployed file since the last install is caught by this check.
+
+See [Enforce in CI](../enforce-in-ci/#audit-only-ci-pattern) for the full
+recipe and a comparison table of the two patterns.
+
 ## Org-wide sweeps
 
 APM runs per repository. There is no built-in fleet console. The

docs/src/content/docs/enterprise/enforce-in-ci.md

@@ -77,6 +77,54 @@ jobs:
 Make this job a required status check via
 [GitHub Rulesets](../github-rulesets/) and a violating PR cannot merge.
 
+## Audit-only CI pattern
+
+The default `microsoft/apm-action@v1` runs `apm install` before any
+subsequent steps. That is the right default for most workflows: it ensures
+the lockfile and deployed files are present before the audit reads them.
+
+However, `apm install` overwrites every managed file with a fresh copy
+before `apm audit --ci` runs. If a managed file was modified on disk after
+the last install -- its bytes changed without updating the lockfile hash --
+the install step silently restores the clean copy. The `content-integrity`
+check then compares the freshly restored file against a hash that matches,
+and the tampering goes undetected.
+
+To detect post-install file modification, run the action in setup-only mode
+so it only adds the CLI to `PATH` without touching deployed files:
+
+```yaml
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: microsoft/apm-action@v1
+        with:
+          setup-only: true     # CLI only; does not run apm install
+      - run: apm audit --ci --no-drift
+        env:
+          GITHUB_APM_PAT: ${{ secrets.APM_PAT }}
+```
+
+`setup-only: true` leaves every deployed file exactly as checked out.
+`--no-drift` skips the install-replay check because no warm cache exists;
+the `content-integrity` check still verifies that every deployed file's
+SHA-256 hash matches the `deployed_file_hashes` recorded in `apm.lock.yaml`.
+Any file whose bytes were changed after the last install fails this check.
+
+The two patterns serve different goals:
+
+| Pattern | Use when |
+|---|---|
+| Full install then audit | Catching developers who skipped `apm install` after editing `apm.yml`; ensuring deployed files are present on a fresh runner |
+| Audit-only (`setup-only: true`) | Detecting modification of deployed files after install; committed files and lockfile are the ground truth |
+
+Both patterns enforce policy and the eight baseline lockfile checks. The
+difference is only in whether content-integrity can see tampered bytes.
+
 ## Recipe: SARIF for GitHub Code Scanning
 
 Emit SARIF and upload it so each violation appears inline on the PR

docs/src/content/docs/getting-started/installation.md

@@ -11,6 +11,8 @@ sidebar:
 - [git](https://git-scm.com/) for dependency management
 - Python 3.10+ (only for pip or from-source installs)
 
+On **Windows ARM64**, the one-line installer currently downloads the **x86_64** ZIP (same as the GitHub Release asset); it runs via emulation. Native ARM64 Windows binaries are not selected yet.
+
 ## Quick install (recommended)
 
 **macOS / Linux:**
@@ -29,7 +31,7 @@ The installer automatically detects your platform (macOS/Linux/Windows, Intel/AR
 
 ### Installer options
 
-The Unix installer supports environment variables for custom environments:
+**macOS / Linux (`install.sh`):**
 
 ```bash
 # Install a specific version
@@ -42,15 +44,60 @@ curl -sSL https://aka.ms/apm-unix | APM_INSTALL_DIR=$HOME/.local/bin sh
 GITHUB_URL=https://github.corp.com VERSION=v1.2.3 sh install.sh
 ```
 
+**Windows (`install.ps1` in PowerShell):**
+
+Air-gapped hosts should **save `install.ps1` locally** (the `irm` one-liner needs reachability to the script URL).
+
+```powershell
+# Pin a version (skips GitHub API - required for many air-gapped / GHES setups)
+# Pinned installs verify SHA256 from the matching .sha256 unless you set:
+#   $env:APM_SKIP_CHECKSUM = "1"   # emergency only
+$env:VERSION = "v1.2.3"; irm https://aka.ms/apm-windows | iex
+
+# Saved script: pass -SkipChecksum only when the release has no .sha256 sidecar (not recommended).
+# .\install.ps1 v1.2.3 -SkipChecksum
+
+# Custom directory for apm.cmd (default: %LOCALAPPDATA%\Programs\apm\bin)
+$env:APM_INSTALL_DIR = "$env:LOCALAPPDATA\Programs\apm\bin"; irm https://aka.ms/apm-windows | iex
+
+# Fork, enterprise host, or internal mirror (GITHUB_URL must be https://)
+$env:GITHUB_URL = "https://github.corp.com"
+$env:APM_REPO = "my-org/apm"
+$env:VERSION = "v1.2.3"
+irm https://aka.ms/apm-windows | iex
+```
+
+**GitHub Actions (`windows-latest`):**
+
+```yaml
+jobs:
+  install-apm:
+    runs-on: windows-latest
+    steps:
+      - name: Install APM (pinned, CI-safe)
+        shell: pwsh
+        env:
+          VERSION: v0.13.0
+          # For GHES or a mirror, set GITHUB_URL (https only) and APM_REPO as needed.
+        run: |
+          irm https://aka.ms/apm-windows | iex
+          apm --version
+      - uses: actions/checkout@v4
+      - run: apm install --frozen
+```
+
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `APM_INSTALL_DIR` | `/usr/local/bin` | Directory for the `apm` symlink |
-| `APM_LIB_DIR` | `$(dirname APM_INSTALL_DIR)/lib/apm` | Directory for the full binary bundle |
-| `GITHUB_URL` | `https://github.com` | Base URL for downloads (mirrors, GHE) |
-| `APM_REPO` | `microsoft/apm` | GitHub repository |
-| `VERSION` | *(latest)* | Pin a specific release (skips GitHub API) |
-
-> **Note:** When using `GITHUB_URL` for a GitHub Enterprise or air-gapped mirror, set `VERSION` as well. The GitHub API call for latest-release discovery still targets `api.github.com`; `VERSION` bypasses it entirely.
+| `APM_INSTALL_DIR` | `/usr/local/bin` (Unix) / `%LOCALAPPDATA%\Programs\apm\bin` (Windows) | Directory for the `apm` symlink / `apm.cmd` shim |
+| `APM_LIB_DIR` | `$(dirname APM_INSTALL_DIR)/lib/apm` | *(Unix only)* Directory for the full binary bundle |
+| `GITHUB_URL` | `https://github.com` | Base GitHub URL (asset downloads **and** API host: `api.github.com` on github.com, `{GITHUB_URL}/api/v3` on GHES). Must be `https://`. |
+| `APM_REPO` | `microsoft/apm` | Repository as `owner/name` |
+| `VERSION` | *(latest)* | Pin a release tag (skips the **releases/latest** HTTP API). Must look like `v1.2.3` or `1.2.3`. |
+| `APM_SKIP_CHECKSUM` | *(unset)* | Windows only: set to `1` to skip `.sha256` verification on **pinned** installs (emergency only). |
+
+> **Note - Unix (`install.sh`):** Latest-release discovery still calls `https://api.github.com/repos/.../releases/latest` unless `VERSION` is set. For GHES or mirrors with no access to `api.github.com`, pin `VERSION` so the script never hits that endpoint.
+>
+> **Note - Windows (`install.ps1`):** The **releases/latest** URL is derived from `GITHUB_URL`: `https://api.github.com` for GitHub.com, or `{GITHUB_URL}/api/v3` for GitHub Enterprise Server. Air-gapped runners should still set `VERSION` so the installer does not need the API at all. When `VERSION` is pinned, the release **`.sha256`** file is required unless you set **`APM_SKIP_CHECKSUM=1`** (emergency only).
 
 ## Package managers