Fold integration drift gate into 'apm audit --drift' (or 'apm install --check')

[danielmeppiel]

Problem

CI's APM Self-Check job (.github/workflows/ci.yml:160) runs apm install then asserts git status --porcelain -- .github/ .claude/ .cursor/ .opencode/ is empty as a shell-level drift gate. This catches one drift mode that the in-tree apm audit --ci does not:

Drift case	audit --ci catches?	Porcelain catches?
Hand-edited regenerated file (hash mismatch)	Yes (content-integrity SHA-256)	Yes
Lockfile missing file that's on disk	Partial	Yes
New .apm/ source added but never apm installd	No -- lockfile simply omits it; nothing to check	Yes -- only gate

The third row bit PR #1067 (commit a51921e4): adding .apm/instructions/linting.instructions.md without re-running apm install slipped past audit and was only caught by porcelain in CI.

Why this matters

• Porcelain check is shell logic embedded in workflow YAML -- not portable, not testable, not invokable by contributors locally without copy-pasting the bash one-liner.
• commands/audit.py:5 already declares --drift is a planned mode. Folding the integration drift gate into it (or apm install --check) would:
  • give contributors a single apm command to mirror CI locally;
  • let consumers of microsoft/apm-action opt in via drift-check: true instead of templating bash;
  • delete the run: | block from ci.yml.

Proposed shape

Either:

• apm audit --drift -- runs apm install against a scratch directory, diffs the resulting governed paths (.github/, .claude/, .cursor/, .opencode/) against the working tree, exits non-zero with a diff on mismatch.
• apm install --check -- same logic but as a no-write mode of install itself (closer to pip install --dry-run or terraform plan).

Either should:

1. Detect the missing-mirror case (new .apm/ source not yet integrated).
2. Detect lockfile entries not yet in local_deployed_files / local_deployed_file_hashes.
3. Render a diff suitable for CI annotations.

Follow-on

Once shipped, update microsoft/apm-action to expose drift-check: true (companion to existing compile: true), and migrate .github/workflows/ci.yml to call it instead of the inline porcelain script.

Context

• Discovered while shipping apm compile should emit .github/copilot-instructions.md (dogfood gap) #792 (PR fix(compile): emit and clean up copilot root instructions (#792) #1067) -- the dogfood compile work.
• Companion issue audit --ci: verify deployed file content, not just existence #684 already covers the audit gap on deployed-file content vs lockfile.

[github-actions]

Triage decision

needs-design

Proposed labels

theme/governance
area/audit-policy
area/cli
area/ci-cd
type/feature
status/needs-design

Milestone

null

Suggested next action

Draft a design doc that settles: (a) whether drift detection lives in apm audit --drift or apm install --check, (b) the scratch-directory strategy for running install without side-effects, and (c) the diff format suitable for CI annotations -- then link it back here before implementation begins.

Suggested issue comment

Thanks for the detailed write-up, @danielmeppiel -- this is exactly the kind of gap that erodes contributor confidence in CI. The third drift case (new `.apm/` source added but never `apm install`'d) being invisible to `audit --ci` is a real problem, and the dogfood incident in PR #1067 is concrete evidence.

The direction is sound. Before code lands, a design doc needs to resolve:

1. **Command ownership**: `apm audit --drift` (already declared in `commands/audit.py:5`) vs `apm install --check` (closer to `pip install --dry-run` / `terraform plan`). Either is defensible, but the choice has implications for the audit command's mental model ("reporting" vs "checking") and for what `microsoft/apm-action` exposes as a flag.

2. **Scratch-directory strategy**: running `apm install` into a temp location to produce a diff without touching the working tree requires careful isolation -- especially around lockfile reads, auth resolution, and path security. The design must describe how this avoids side-effects.

3. **Diff format for CI annotations**: the output must be CI-composable (exit code, stdout vs stderr, machine-readable diff). The relationship with companion issue #684 (audit gap on deployed-file content vs lockfile) should be made explicit -- these two may share the diff surface.

Once the design is written and linked here, this should move quickly to `status/accepted`. The follow-on work (updating `microsoft/apm-action` with `drift-check: true`) is a natural companion PR.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

The user surface is real and well-articulated. Contributors need a single apm command to mirror the CI drift gate locally -- currently they must copy-paste a bash one-liner from .github/workflows/ci.yml. The apm install --check pattern maps directly to pip install --dry-run / terraform plan, which are well-established in the developer tooling ecosystem. apm audit --drift is also discoverable, but mixing "audit" (a reporting verb) with "drift" (a comparison operation) is slightly less idiomatic. Either surface works if it exits non-zero with a diff on mismatch. The composability requirement (CI annotations, exit codes) is essential and must be part of the design, not an afterthought.

Supply Chain Security Expert -- Risk-Surface Reviewer

No supply-chain risk surface implication. The drift check does not introduce new trust boundaries, does not alter lockfile integrity verification, and does not handle credentials or package downloads. It is a governance/audit tooling feature that strengthens the CI integrity gate by making drift detection a first-class CLI operation. Theme theme/governance is appropriate; theme/security is not required. The scratch-directory strategy does need to reuse the existing path_security guards to avoid any path traversal risk during the temporary install step -- the design doc should call this out explicitly.

OSS Growth Hacker -- Contributor-Tone Reviewer

Not activated -- author is a COLLABORATOR (danielmeppiel) with substantial prior interaction history; tone tuning for new contributors is not warranted here.

Python Architect -- Architecture Reviewer

The issue proposes a cross-cutting design decision between two command shapes. commands/audit.py:5 already declares --drift as a planned mode, which makes apm audit --drift the stronger candidate from a code-continuity standpoint. However, running install logic in a scratch directory to produce a diff touches: the install pipeline (install/pipeline.py), lockfile reads (deps/lockfile.py), path security (utils/path_security.py), and a new diff/compare module that does not yet exist. This is a non-trivial cross-module boundary. The interface (what goes in, what comes out, how errors surface), the data model for representing drift (missing files, modified files, extra files), and the boundary with the existing local_deployed_files / local_deployed_file_hashes schema all need to be settled before code lands safely. status/needs-design is the correct disposition.

Doc Writer -- Documentation Reviewer

A new CLI mode (apm audit --drift or apm install --check) will require updates to docs/src/content/docs/reference/cli-commands.md and likely a new section in the CI/CD integration guide (docs/src/content/docs/integrations/ci-cd.md). The packages/apm-guide/.apm/skills/apm-usage/commands.md resource must also be updated per repo Rule 4. The proposed comment wording is clear and grounded in APM's user vocabulary. An area/docs-site secondary label is recommended for the implementing PR to ensure the doc update is not forgotten -- it is not added here since it is a reminder for the PR, not a classification of this issue.

APM CEO -- Triage Arbiter

Strategic call: needs-design. The direction is aligned with APM's governance positioning -- a first-class drift check command is a strong competitive differentiator (comparable to terraform plan) and directly addresses a CI reliability gap caught in production. The maintainer-applied priority/high label is preserved and correct in spirit; however, per the triage rubric, priority/* labels are not added to needs-design issues, so the existing label stands as a human signal while the panel does not re-apply or remove it. Milestone is null; once the design doc is linked and reviewed, the issue should be accelerated to status/accepted with a milestone assignment at that point.

{
  "decision": "needs-design",
  "decision_detail": "Interface choice (audit --drift vs install --check), scratch-directory strategy, and CI diff format must be designed before implementation.",
  "theme": "theme/governance",
  "areas": ["area/audit-policy", "area/cli", "area/ci-cd"],
  "type": "type/feature",
  "status": "status/needs-design",
  "priority": null,
  "preserved_labels": [],
  "milestone": null,
  "next_action": "Draft a design doc settling command ownership, scratch-directory strategy, and CI diff format, then link it back here.",
  "comment_markdown": "Thanks for the detailed write-up, @danielmeppiel -- this is exactly the kind of gap that erodes contributor confidence in CI. The third drift case (new `.apm/` source added but never `apm install`'d) being invisible to `audit --ci` is a real problem, and the dogfood incident in PR #1067 is concrete evidence.\n\nThe direction is sound. Before code lands, a design doc needs to resolve:\n\n1. **Command ownership**: `apm audit --drift` (already declared in `commands/audit.py:5`) vs `apm install --check` (closer to `pip install --dry-run` / `terraform plan`). Either is defensible, but the choice has implications for the audit command's mental model and for what `microsoft/apm-action` exposes as a flag.\n\n2. **Scratch-directory strategy**: running `apm install` into a temp location to produce a diff without touching the working tree requires careful isolation -- especially around lockfile reads, auth resolution, and path security.\n\n3. **Diff format for CI annotations**: the output must be CI-composable (exit code, stdout vs stderr, machine-readable diff). The relationship with companion issue #684 should be made explicit.\n\nOnce the design is written and linked here, this should move quickly to `status/accepted`."
}

---

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 3 items

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

• [BUG] apm install --update fails for GHES/generic hosts due to pipeline probe blocking credential helpers #1082 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1013 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #998 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 for issue #1071 · ● 1.3M · ◷