CHANGELOG.md

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

Fixed

• Parallel subdir install race. apm install no longer intermittently fails with RuntimeError: Subdirectory '<path>' not found in repository when multiple dependencies resolve to different subdirectories of the same repo@ref. The shared clone cache now stores subdir-agnostic bare clones and each consumer materializes its own working tree (mirrors the WS3 GitCache pattern). (#1135, fixes #1126)

[0.12.1] - 2026-05-03

Added

• Cursor slash command support (Cursor 1.6+). apm install deploys package .prompt.md files to .cursor/commands/*.md when a .cursor/ directory is present, completing cross-tool slash-command parity with Claude Code, OpenCode, and Gemini CLI. (#1046)
• apm install performance + UX overhaul: WS3 persistent two-tier cache for git + HTTP (with rev-parse HEAD verification on cache hits), parallel level-batched BFS dependency resolution, parallel MCP registry batch lookups with ETag-revalidated HTTP cache, in-install repo clone dedup for subdirectory deps, reflink-aware file copies with write-dedup for cache checkouts, live progress UI for parallel resolution and download, per-phase timing in --verbose, elapsed time on every exit path, and ASCII-only progress bar. (#1116)

Fixed

• gh-aw lock workflows: bump microsoft/apm-action v1.5.0 -> v1.6.0 so packed bundles use the legacy --format apm layout that apm unpack accepts after the v0.12.0 default flip to plugin format. (#1121)
• Windows CI: explicit UTF-8 encoding in the _make_package test helper to unblock Windows runners. (#1124)

[0.12.0] - 2026-05-03

Added

• --target agent-skills deploys skills to .agents/skills/ (cross-client shared directory). The new target writes SKILL.md files to the agentskills.io standard location without tying them to a single client. Excluded from --target all (explicit opt-in only); combine with --target all,agent-skills for both. Deduplicates with Codex when both targets resolve to the same path. User-scope (-g) deploys to ~/.agents/skills/. (closes #737)
• Claude Code as MCP install target. apm install --runtime claude (and auto-detection when .claude/ exists or the claude binary is on PATH) writes MCP server entries to project-scope .mcp.json and user-scope ~/.claude.json per the Claude Code MCP schema. Project writes are opt-in (gated on the presence of .claude/, mirroring Cursor/OpenCode) and user writes are atomic with 0o600 permissions on first creation so concurrent Claude Code sessions cannot truncate the shared config or leak embedded OAuth state. Stdio entries are emitted with explicit type: "stdio" so claude mcp list renders them identically to entries installed via claude mcp add --transport stdio. Schema fidelity is regression-locked by golden fixtures captured live from the upstream claude CLI (see tests/integration/test_claude_mcp_schema_fidelity.py). Stale-cleanup defaults conservatively when the install scope is unspecified -- only the project file is touched without an explicit -g/--global opt-in. Note: Claude Code's third LOCAL scope (per-project private under ~/.claude.json -> projects.<path>.mcpServers) is intentionally not implemented, since APM packages target reproducible team installs (PROJECT/USER), not per-user-per-project private state. (#1104, closes #643) -- by @dmartinol
• apm install <local-bundle-path> deploys a previously packed bundle (directory or .tar.gz) air-gapped, with sha256 integrity verification against the bundle's embedded apm.lock.yaml. Honours --target, --global, --force, --dry-run, plus a new --as ALIAS log/display label flag. Local installs record written paths in the project lockfile (local_deployed_files / local_deployed_file_hashes) and never mutate apm.yml. apm unpack is now [Deprecated] and points at this entrypoint. (#1098)
• apm pack now embeds apm.lock.yaml inside the bundle with two new pack: fields (target, bundle_files: a path -> sha256 manifest) so installs can verify integrity and detect target mismatches before writing any file. (#1098)
• apm compile -t copilot now emits .github/copilot-instructions.md with zero user configuration -- APM's first Copilot-native compile target. Global instructions in .apm/instructions/ are assembled into the file VS Code and GitHub Copilot read automatically; switching targets cleans it up. APM dogfoods this target. (#1048)
• apm marketplace add accepts full HTTPS URLs and nested HOST/group/sub/.../REPO shorthands. You can now paste a repository URL straight from the browser (e.g., apm marketplace add https://github.com/acme/plugin-marketplace) and register marketplaces hosted under nested sub-paths on GitHub Enterprise (ghes.corp.example.com/org/team/repo). Path-traversal sequences in the parsed segments are rejected via validate_path_segments. Non-GitHub hosts (GitLab, Bitbucket, etc.) are explicitly rejected at registration time with an actionable error -- this avoids forwarding GitHub credentials to unintended hosts and the silent fetch-time 404 that previously resulted; native non-GitHub support is tracked separately. (#1034, closes #1027)
• Regression tests for apm compile placement of narrow applyTo patterns: instructions whose matches all live deep inside one subtree are now pinned to the deepest covering directory instead of being hoisted to the project root, across both selective and single-point placement strategies. Also covers the file-walk cache that skips repeated filesystem scans for the same glob. (#871)
• apm pack marketplace builder hardening. Local source paths are now emitted relative to metadata.pluginRoot (fixes double-prefix bug). New pass-through fields: author, license, repository, keywords (alias for tags). Curator-wins override semantics for description/version on remote entries. Security guards reject path traversal and absolute paths post-subtraction. (#1061)
• Plugin manifest schema-conformance tests. tests/unit/test_plugin_exporter_schema.py validates every shape of plugin.json produced by apm pack (synthesized, authored, and authored-with-stale-keys) against the vendored official schema. Companion marketplace conformance lives in tests/unit/marketplace/test_schema_conformance.py. (#1061)
• APM now compiles and integrates to Windsurf/Cascade. New first-class --target windsurf support: instructions deploy as .windsurf/rules/ with trigger frontmatter, agents deploy as .windsurf/skills/<name>/SKILL.md, commands as .windsurf/workflows/, hooks merge into .windsurf/hooks.json, and MCP servers configure via ~/.codeium/windsurf/mcp_config.json. Auto-detection, user-scope deployment, and apm pack all support the new target. (#1066)
• Slash commands installed from APM packages now surface argument hints in Claude Code -- apm install automatically maps prompt input: to Claude's arguments: front-matter, rewrites ${input:name} references to $name, and auto-generates argument-hint. Argument names are validated against an allowlist to prevent YAML injection from third-party packages, and the mapping is reported at install time. (#1039)

Changed

• Skills for Copilot, Cursor, OpenCode, and Codex now deploy to .agents/skills/ by default (skill routing convergence). The four clients whose documentation lists .agents/ as a skill discovery path now share a single deployment directory, eliminating up to 4 redundant copies per skill when --target all is used. Claude retains its native per-client routing (.claude/skills/); Gemini joins the convergence in the entry below. Pass --legacy-skill-paths (or set APM_LEGACY_SKILL_PATHS=1) to restore the previous per-client layout. (closes #1103)
• Gemini CLI joins the .agents/skills/ convergence by default. Gemini CLI docs list .agents/skills/ as the preferred alias over .gemini/skills/, so Gemini now shares the converged deployment directory with Copilot, Cursor, OpenCode, and Codex (5 clients total). Claude remains on its native .claude/skills/ routing. (#737)
• Auto-migration: apm install now migrates legacy per-client skill deployments (.github/skills/, .cursor/skills/, .opencode/skills/, .gemini/skills/) recorded in apm.lock.yaml to .agents/skills/. Foreign / hand-authored skills outside the lockfile are left untouched. Use --legacy-skill-paths to opt out. (#737)
• Renamed NOTICE.md -> NOTICE to follow the Apache / CNCF convention used by upstream third-party-attribution files (e.g. kubernetes-sigs/kro, kubernetes-sigs/headlamp). The generator (scripts/generate-notice.py), make notice target, and NOTICE Drift Check workflow now operate on the extension-less path. (#1073)
• NOTICE: added "Submitted on behalf of a third-party" section crediting five contributors whose pull requests landed before the microsoft-github-policy-service CLA bot recorded a signature on file -- in keeping with the section-7 wording adopted by CNCF NOTICE files. Driven by a new _third_party_submissions block in scripts/notice-metadata.yaml. (#1073)
• BREAKING: apm pack now produces a Claude Code plugin directory by default — zero extra flags, schema-validated plugin.json, convention dirs auto-discovered. The legacy APM bundle layout is preserved under --format apm. Migration: CI workflows and scripts that consume the legacy bundle must add --format apm (the microsoft/apm-action wrapper has been updated accordingly). (#1061)
• Plugin manifest schema conformance. The synthesized/written plugin.json no longer emits agents/skills/commands/instructions keys pointing at the convention directories — these are auto-discovered by Claude Code, and per the official schema those array entries must be ./*.md paths to additional files. The convention dirs themselves are still copied to disk. When stripping such keys from an authored plugin.json, apm pack now emits a warning so authors can clean up their source. (#1061)

Deprecated

• --target agents is deprecated -- it maps to copilot (.github/), not .agents/. Use --target copilot or --target agent-skills. Removal in v1.0. (closes #627, #640, #664)

Removed

• BREAKING: dropped support for .collection.yml / .collection.yaml virtual packages. Dependencies whose paths end in .collection.yml or .collection.yaml now raise a ValueError at parse time with a migration message. Convert any such entry to a regular apm.yml with a dependencies: section under the same subdirectory, then reference the directory itself as a subdirectory virtual package (no extension). The internal VirtualPackageType.COLLECTION enum value, the download_collection_package codepath, the is_virtual_collection() reference helper, and the META_PACKAGE package-type label have been removed -- none were persisted to the lockfile, so existing locks are unaffected. (#1097, closes #1094) Thanks @edenfunf for the original PR.

Fixed

• apm install now anchors transitive local_path deps on the declaring package's directory (npm/pip/cargo parity). Sibling/monorepo layouts (e.g. ../base declared inside packages/specialized/apm.yml) now resolve relative to the declaring package, not the consumer's project root. Security tightening: remote-cloned packages can no longer declare local_path deps -- both relative and absolute paths are rejected at ERROR severity at resolve time. (#1111, closes #857) Thanks @JahanzaibTayyab.
• apm compile no longer silently drops instructions without an applyTo pattern from generated AGENTS.md and CLAUDE.md; globals now render under a ## Global Instructions section, matching the optimizer's existing (global) placement (#1088, closes #1072)
• apm install no longer masks local-bundle install failures with UnboundLocalError. (#1108)
• apm install <pkg>@<marketplace> no longer fails for all marketplace packages. The install resolver now accepts both legacy and current marketplace key names: repository/repo for github sources, url/repo for git-subdir sources, and type/source as the source-type discriminator. A scheme guard rejects full URLs passed through the url fallback. (#1106, closes #1105)
• apm install --update no longer fails for GHES/generic hosts that rely on git credential helpers (e.g., git-credential-manager) for authentication. The preflight auth probe was blocking credential helpers by setting GIT_CONFIG_GLOBAL=/dev/null; it now uses the same relaxed environment as the clone fallback path for non-GitHub/non-ADO hosts. (#1082)
• apm compile --dry-run -t copilot now faithfully simulates the hand-authored file guard: a .github/copilot-instructions.md lacking the APM marker is reported as skipped=1 (matching the real run) instead of as generated=1. Previously dry-run would claim a write that a real run would refuse, giving CI preview gates a false signal. (#1048)
• apm compile -t claude,copilot (and any multi-target list including copilot) now correctly generates .github/copilot-instructions.md; previously it was silently skipped on the multi-target code path. (#1048)
• apm compile no longer overwrites a hand-authored .github/copilot-instructions.md; if the file lacks the APM-generated marker, regeneration is skipped with a warning that names the literal marker line (<!-- Generated by APM CLI from .apm/ primitives -->) so users can self-serve recovery. Migration: to adopt APM management of an existing file, either delete or rename it and re-run apm compile, or prepend the marker line to the top of the file and re-run apm compile. (#1048)
• Generated footer in .github/copilot-instructions.md now reads apm compile (was specify apm compile). (#1048)
• apm compile --targets claude no longer lists @apm_modules/{owner}/{package}/CLAUDE.md dependencies for packages that don't have a CLAUDE.md file on disk (#1047)
• apm prune no longer flags directories it put there itself -- skills installed from a subdirectory path (e.g., owner/repo/.apm/skills/skill-name) no longer cause the parent owner/repo/ clone to appear as an orphan. Fixes spurious removal prompts in multi-skill and monorepo-style setups. The same fix applies to apm deps list and apm compile. A genuinely orphaned owner/repo package is still flagged even when a sibling subdirectory dep shares the same owner/repo root. No changes to apm.yml or the lockfile are required to benefit from this fix. (#1050)

[0.11.0] - 2026-04-29

Added

• apm pack is now the single command for marketplace builds -- with an apm.yml marketplace: block it emits .claude-plugin/marketplace.json directly. New flags: --offline, --include-prerelease, --marketplace-output PATH. (#722)
• Author marketplaces from apm.yml. New top-level marketplace: block, apm marketplace migrate to consolidate legacy marketplace.yml, apm init --marketplace to scaffold, and first-class source: ./local/path package sources. (#1038)
• Codex CLI installs are now project-scoped. MCP config lands in .codex/config.toml for project installs (no more polluting the user-global file); user-scope primitive deployment is also supported. (#803)
• Cross-org private packages in shared/apm.md via a new apps: array (one GitHub App per credential group, matrix fan-out). The single-app shorthand (app-id / private-key / owner / repositories) is preserved. (#982)

Changed

• apm marketplace add preserves the upstream alias -- now defaults to the name declared in the fetched marketplace.json instead of the repo name, so install instructions in third-party READMEs work verbatim. (#1032)
• --policy / --policy-source help is unified across CLI and docs, with lockstep tests pinning all surfaces against drift. (#1000, closes #998 #994)
• BREAKING: invalid target: values now fail loud. CSV strings (target: a,b,c), unknown tokens, empty values, and all mixed with other targets used to silently no-op apm install / apm compile; they now raise a parse error. Omitting target: still auto-detects. (#820)
• Rename DownloadStrategyManager -> DownloadDelegate and fix double-checked-locking bug in marketplace registry _load(). (#918)

Removed

• BREAKING: apm marketplace build removed -- apm pack is the replacement; the old verb exits 2 with a migration hint. The marketplace_authoring experimental flag is also gone (authoring is GA). (#722)

Deprecated

• Standalone marketplace.yml -- still loaded with a deprecation warning, removal slated for v0.13. (#1038)

Fixed

• apm install works with your existing credential chain (SSO, EMU, GHES tokens). Validation now uses the same credentials as the actual clone (PAT header-injected, then git credential helper, then SSH for explicit #ref pins) -- enterprise users whose env-var PAT has narrower SSO/EMU access than their gh auth setup-git / OS keychain are no longer false-rejected by the installer's API probe. Validation logic is now a separate module (github_downloader_validation.py), laying groundwork for future credential-provider extensibility. (#941)
• shared/apm.md single-credential-group runs no longer fail validation with a spurious missing APM bundles: apm-default -- a normalisation step recreates the per-group subdir layout that actions/download-artifact@v5+ flattens away. (#1051)
• apm pack works against GitHub Enterprise and other Git hosts -- honors GITHUB_HOST for GHES auth and accepts GitHub / GHES / GitLab / Bitbucket / ADO / SSH URL forms. (#1008)
• ADO Entra ID auth no longer silently fails. Bearer tokens from az account get-access-token are plumbed through, errors are typed + actionable (4-case diagnostic), and apm install --update pre-flights auth before touching files. (#1015)
• apm marketplace add now uses the name field from the fetched marketplace.json as the default local alias, falling back to the repo name only when the manifest omits it or declares an invalid value. This restores parity with Claude Code install instructions (e.g. addyosmani/agent-skills registers as addy-agent-skills as that repo's README documents). Existing marketplace entries are unaffected; use --name to override explicitly. (#1032)
• GEMINI.md is now only created when explicitly targeted. (#1019)
• Windows-friendly: auto-discovery CLI output uses POSIX paths so apm install / apm compile output is readable on Windows. (#1018)
• Generated-file footer no longer prints stray specify before apm compile. (#996)
• CodeQL clear-text-storage false-positive resolved (variable rename). (#1002)

[0.10.0] - 2026-04-27

Added

• Microsoft 365 Copilot Cowork target works end-to-end: apm install --target cowork --global deploys skills to OneDrive (behind apm experimental enable cowork). (#926)
• [Experimental] apm marketplace authoring CLI: maintainers can scaffold, build, validate, and publish Anthropic-compliant marketplaces from the CLI (init -> package add -> build -> publish). (#790)
• README "Coming from npx skills add?" 30-second migration table for users arriving from the agentskills.io ecosystem. (#980)
• NullCommandLogger class (src/apm_cli/core/null_logger.py) -- null-object pattern for logger injection, eliminating 32 conditional logger forks in MCPIntegrator. (#918)
• Thread-safety infrastructure: _get_console() double-checked locking singleton, marketplace registry cache threading.Lock. (#918)
• 40 characterisation tests for MCPIntegrator methods (install(), remove_stale(), collect_transitive()). (#918)
• _build_children_index() helper in uninstall engine for O(n) reverse-dependency lookups. (#918)
• Performance benchmarks and scaling guards for complexity audit refactors (tests/benchmarks/test_audit_benchmarks.py, test_scaling_guards.py): 16 benchmark tests covering dependency parsing, children index, primitive discovery, registry cache, console singleton, and NullCommandLogger; 3 scaling-ratio guards run in the default test suite to catch O(n^2) regressions. (#918)
• Expanded performance benchmark suite with P0 and P1 hot-path coverage: compute_package_hash, get_all_dependencies, is_semantically_equivalent, flatten_dependencies, to_yaml, compute_deployed_hashes, optimize_instruction_placement, _rewrite_markdown_links, partition_managed_files, LockFile round-trip, and register_contexts -- 52 new benchmark tests plus 2 additional scaling guards. (#918)
• Iteration 2 benchmark coverage: _match_double_star recursive glob matcher, ContentScanner.scan_text and strip_dangerous security scanning, build_dependency_tree BFS resolver, _parse_ls_remote_output and _sort_remote_refs git ref parsing, analyze_directory_structure compiler analysis, and collect_transitive MCP integration -- 77 new benchmark tests plus 1 additional scaling guard. (#918)

Changed

• [Experimental] apm marketplace plugin renamed to apm marketplace package (npm/pip/cargo familiarity); --help grouped into Consumer / Authoring sections. (#722)
• MCPIntegrator logger handling: methods default to NullCommandLogger instead of None, removing 32 if logger: / elif logger: conditional forks (net -91 production lines). (#918)
• Install pipeline lockfile reads reduced from 2x to 1x by caching early lockfile on InstallContext. (#918)
• APMPackage.from_apm_yml(): deduplicated dependency parsing via _parse_dependency_dict() classmethod. (#918)
• Uninstall engine BFS orphan detection: O(n^2) full-scan replaced with O(n) reverse-dep index. (#918)
• Primitive discovery scanning: 9+ glob.glob() calls replaced with single os.walk + fnmatch pass. (#918)
• MCP registry config reads: O(servers x runtimes) reduced to O(runtimes) via function-scoped cache. (#918)
• _get_console(): returns thread-safe singleton instead of creating new Console() per call. (#918)
• Marketplace registry cache: _load(), _save(), _invalidate_cache() protected with threading.Lock. (#918)
• Complexity audit -- decomposed god functions in reference.py, audit.py, deps/cli.py, and script_runner.py into focused single-responsibility helpers (largest: audit() 290 lines split into thin dispatcher + _audit_ci_gate + _audit_content_scan with shared _AuditConfig dataclass). (#918)
• Decomposed github_downloader.py into three modules: git_remote_ops.py (ref parsing), download_strategies.py (backend downloads), and a slimmed orchestrator. (#918)
• Decomposed install() god function (555 lines) into focused helpers with InstallContext parameter bundle. (#918)

Fixed

• Docs site auto-deploys again after bot-cut releases (now triggered on tag push). (#981)
• Bare except: clauses in formatters.py (5) and script_formatters.py (2) now catch Exception instead of BaseException, allowing KeyboardInterrupt and SystemExit to propagate correctly. (#918)
• Silent auth fallback in discovery.py:_get_token_for_host() now logs logger.debug() when the token manager fails, making credential resolution failures visible with --verbose. (#918)
• Silent except Exception: pass handlers in agents_compiler.py (3) now emit _logger.debug() traces for config loading and constitution injection failures. (#918)
• Double iterdir() walk in script_runner.py:_resolve_prompt_file() collapsed to a single pass. (#918)

Documentation

• Clarify NullCommandLogger partial interface and visible-output semantics in docstring. (#918)

Maintainer tooling

• pr-description-skill ships an evals suite so PR-description quality regressions are caught in CI without an LLM API key. (#985)
• pr-description-skill mermaid guidance hardened with assets/mermaid-conventions.md (diagram-type-by-intent + GitHub-renderer gotchas mmdc misses). (#984)
• Cowork tests mock sys.platform so the macOS auto-detection paths don't false-fail on Windows CI. (#989)

[0.9.4] - 2026-04-27

Added

• Day-0 install parity with npx skills add: every public repo that installs cleanly with npx skills add owner/repo now installs with apm install owner/repo. APM recognises bare skills/<name>/SKILL.md (vercel-labs/agent-skills, xixu-me/skills, larksuite/cli, the agentskills.io ecosystem) as a first-class shape (SKILL_BUNDLE); apm.yml is optional. --skill <NAME> (repeatable) selects a subset and persists it to apm.yml + apm.lock.yaml, so bare apm install is reproducible across machines. --skill '*' resets; apm audit --ci flags drift. (#974)
• curl | sh install works in air-gapped, GHE, and internal-mirror setups: install.sh now reads APM_INSTALL_DIR, GITHUB_URL, APM_REPO, and VERSION (or @vX.Y.Z arg) -- pinning a version skips the GitHub API entirely, so corporate runners without api.github.com egress can bootstrap APM. (#660)

Changed

• apm marketplace authoring commands (init, build, check, outdated, doctor, publish, package) ring-fenced behind apm experimental enable marketplace-authoring feature flag (default: disabled) (#790)

Fixed

• apm install no longer fails behind corporate TLS-intercepting proxies: validation now honours REQUESTS_CA_BUNDLE instead of misreporting CA failures as auth errors. (#911)
• apm experimental <subcommand> --help now shows the subcommand's own help; CLI help text and short flags aligned from the 2026-04-24 audit. (#910, #903)

Maintainer tooling

• Untriaged issues are auto-triaged by the apm-triage-panel skill on a daily oldest-first sweep (max 10/run) plus status/needs-triage for on-demand. Decisions are agentic proposals; any maintainer label edit wins. (#954)
• Docs site auto-deploys again after bot-cut releases (workaround for GitHub's GITHUB_TOKEN-suppressed release: published event). Silently broken since v0.9.3. (#953)
• Triage-panel themed issues now reach the PGS project board (dispatches project-sync directly; same GITHUB_TOKEN event-suppression class as #953). (#971)
• Issue templates use canonical APM labels; python-architect agent documents the mermaid classDiagram :::cssClass GitHub-render trap. (#958, #970)

[0.9.3] - 2026-04-26

Added

• Gemini CLI as a supported APM target (--target gemini): auto-detects .gemini/, writes MCP config to .gemini/settings.json, and adds apm runtime setup|remove gemini. (#917)
• Experimental cowork target for Microsoft 365 Copilot Cowork custom-skill deployment via OneDrive (apm experimental enable cowork; apm install --target cowork --global; persisted via apm config set cowork-skills-dir). (#913)
• apm experimental command group (list / enable / disable / reset) lets you opt into new behaviour before it graduates to default. Ships with the verbose-version flag. (#849)
• apm audit --ci now verifies hash integrity of locally deployed .apm/ files so hand-edits and config drift fail CI instead of slipping through. (#887)
• includes: manifest field (auto or list) gives you explicit control over which local .apm/ files are deployed; pair with policy.manifest.require_explicit_includes to block silent expansion. Audit raises an includes-consent advisory while you migrate. (#887)
• apm-triage-panel skill: three-persona issue triage panel (DevX UX, Supply Chain Security, APM CEO) emitting a single labelled-decision comment, mirroring apm-review-panel. (#915)
• apm-primitives-architect persona for designing and critiquing .apm/ skill bundles, plus a pr-description-skill that enforces self-sufficient PR bodies (TL;DR/Problem/Approach/Implementation/Diagrams/Trade-offs/Benefits/Validation/How-to-test) with anchored citations and validated mermaid. (#882, #884)
• New docs guide dev-only-primitives: canonical pattern for maintainer-only primitives that must not ride into your published bundle. (#949)
• Maintainer tooling: PGS project-board sync workflow keeps issues in lockstep with labels/milestones; APM Self-Check CI job dogfoods apm audit --ci and regeneration-drift gates. (#919, #885)

Changed

• HYBRID-skill review pipeline: apm-review-panel now produces a single CEO-synthesized verdict per run (no per-persona spam), with Hybrid E auth-expert routing and python-architect's mandatory three-artifact contract. PRs get one high-signal comment. (#882, #905, #907, #908)
• Faster primitive discovery on large repos: compilation.exclude patterns now prune traversal at the directory level instead of post-filtering. (#870)
• apm-action bumped to v1.4.2 (used by shared/apm.md workflows): fixes restore-mode workspace pollution that was overwriting your tracked apm.lock.yaml / apm.yml / apm_modules. (#904)
• CI release-binary smoke (Linux x64/arm64, Windows) only runs on tag/schedule/dispatch instead of every push, cutting ~15 redundant codex downloads/day; release-time gating unchanged. (#878)
• Branch-protection docs: clarify the required check-run name is gate (not the workflow display string Merge Gate / gate). (#874)

Fixed

• HYBRID packages (apm.yml + SKILL.md, no .apm/) and CLAUDE_SKILL packages with sibling agents//assets//scripts/ dirs now install correctly via the skill-bundle path; previously apm install rejected them silently and looked like a hang. Direct-dependency integration failures now print [x] and exit 1 instead of failing silently. (#946)
• apm update no longer breaks on Debian trixie arm64, Fedora 43, and similar distros where the bundled PyInstaller LD_LIBRARY_PATH was leaking into system curl/tar and triggering libssl.so.3: version 'OPENSSL_3.2.0' not found. Closes #894 (#899)
• apm install at user scope no longer recursive-globs your entire home directory: scan is scoped to ~/.apm/. Fixes #830 (#850)
• apm audit --ci now also catches drift / missing / tampered files for locally-authored .apm/ content (not just installed packages); apm pack strips local-content fields so they can't leak into bundled lockfiles. (#887)
• apm install for ADO orgs that disable PAT creation: error messages on generic git hosts now surface the custom port too. Custom transport types in MCP-server config are validated up front (defaulting to http when missing) instead of writing garbage. Closes #791 (#812)
• Windows: apm install no longer false-positives PathTraversalError on policy cache dirs that don't yet exist (8.3 short-name resolution mismatch). (#895)
• macOS: long inline policy YAML strings (>1023 bytes) no longer crash with OSError [Errno 63] File name too long; they fall back to string-mode parsing. Closes #848 (#860)
• Merge queue: gate check now reports inside the queue (added merge_group trigger), unblocking PRs that were stuck on "Expected -- Waiting for status to be reported". (#921)
• apm-review-panel workflow only runs on PRs labelled panel-review, eliminating spurious panel runs on every PR. (#948)

Removed

• Deleted dead ci-integration-pr-stub.yml workflow stubs left over from the pre-merge-gate model. No user impact; reduces CI noise. (#875)

[0.9.2] - 2026-04-23

Added

• apm install supports Azure DevOps AAD bearer-token auth via az account get-access-token, with PAT-first fallback for orgs that disable PAT creation. Closes #852 (#856)
• New enterprise/governance-guide.md: flagship governance reference for CISO / VPE / Platform Tech Lead audiences; trims duplication across governance.md, apm-policy.md, integrations/github-rulesets.md; adds templates/apm-policy-starter.yml. (#851)
• Enterprise docs IA refactor: hub page + merged team guides, deduped governance content. (#858)
• Landing page rewritten around the three-pillar spine. (#855)
• First-package tutorial rewritten end-to-end; fixes .apm/ anatomy hallucinations. (#866)
• apm install --ssh / --https flags and APM_GIT_PROTOCOL=ssh|https env to pick the initial transport for shorthand dependencies (#778)
• apm install --allow-protocol-fallback flag and APM_ALLOW_PROTOCOL_FALLBACK=1 env as the migration escape hatch for cross-protocol fallback (#778)
• Add APM Review Panel skill (.github/skills/apm-review-panel/) and four new specialist personas (devx-ux-expert, supply-chain-security-expert, apm-ceo, oss-growth-hacker) with auto-activating per-persona skills. Routes specialist findings through an APM CEO arbiter for strategic / breaking-change calls, with the OSS growth hacker side-channeling adoption insights via WIP/growth-strategy.md. Instrumentation per Handbook Ch. 9 (The Instrumented Codebase); PROSE-compliant (thin SKILL.md routers, persona detail lazy-loaded via markdown links, explicit boundaries per persona).
• apm view plugin@marketplace displays marketplace plugin metadata (name, version, source, description) (#514)
• apm outdated checks marketplace plugin refs and shows a "Source" column distinguishing marketplace vs git updates (#514)
• apm marketplace validate command with schema validation and duplicate name detection (#514)
• Ref immutability advisory: caches plugin-to-ref pins and warns when a previously pinned plugin's ref changes (#514)
• Multi-marketplace shadow detection: warns when the same plugin name appears in multiple registered marketplaces (#514)

Changed

• gh-aw workflows now use imports: for shared APM context instead of the deprecated dependencies: field. (#864)
• CI: merge-gate.yml orchestrator turns dropped pull_request webhook deliveries into clear red checks instead of stuck Expected -- Waiting for status to be reported. (#865)
• CI: Merge Gate / gate aggregates all PR-time required checks (Build & Test (Linux) + 4 stubs) into a single verdict; branch protection requires only this one check, decoupling the ruleset from CI workflow topology (Tide / bors pattern). (#867, #868)
• CI: merge-gate.yml simplified to a single pull_request trigger with workflow_dispatch for manual recovery; the dual-trigger redundancy attempt was poisoning the branch-protection rollup with CANCELLED check-runs. (#868)

Fixed

• apm install surfaces the custom port in clone / ls-remote error messages for generic git hosts. (#804)

[0.9.1] - 2026-04-22

Added

• apm install enforces org apm-policy.yml at install time (deps deny/allow/require, MCP deny/transport/trust-transitive, compilation.target.allow, extends: chains, policy.fetch_failure knob, policy.hash pin); --no-policy / APM_POLICY_DISABLE=1 escape hatch; --dry-run previews verdicts; failed package installs roll back apm.yml. New apm policy status diagnostic (table / --json, exit-0 by default, --check for CI). apm audit --ci auto-discovers org policy. Migration: orgs publishing enforcement: block may see installs that previously succeeded now fail -- preview with apm install --dry-run. Closes #827, #829, #831, #834 (#832)
• pr-review-panel gh-aw workflow: runs the apm-review-panel skill on PRs labelled panel-review and posts a synthesized verdict (#824)

Changed

• Docs site publishes only on stable APM releases, not on every push to main. Closes #641 (#822)
• Dogfood APM: authored skills, agents, and instructions live in .apm/; .github/{skills,agents,instructions}/ are regenerated by apm install --target copilot and committed (#823)

Fixed

• pr-review-panel workflow now runs on PRs from forks: switched to pull_request_target with label-only triggering and a workflow-dispatch path (#826, #836, #837)
• Lowercase the host axis of the _fallback_port_warned dedup key so deps that differ only in hostname casing collapse to one cross-protocol fallback warning, matching the AuthResolver._cache convention (RFC 4343). Closes #800 (#815)

[0.9.0] - 2026-04-21

Changed (BREAKING)

• Strict-by-default git transport selection: explicit ssh:///https:// URLs no longer silently cross-fall back; shorthand defaults to HTTPS (consults url.<base>.insteadOf). Opt back into the legacy chain with --allow-protocol-fallback or APM_ALLOW_PROTOCOL_FALLBACK=1. Adds --ssh / --https / APM_GIT_PROTOCOL for explicit shorthand selection. Closes #328 (#778)
• MCP entry validation hardened: names must match ^[a-zA-Z0-9@_][a-zA-Z0-9._@/:=-]{0,127}$, URLs limited to http/https, headers reject CR/LF, stdio commands reject ... Error messages now include a valid positive example. (#807)
• Stdio MCP entries with whitespace in command and no args are rejected at parse time with a fix-it error pointing at the canonical command: <binary>, args: [...] shape. Closes #806 (#809)

Added

• apm install --mcp NAME (and apm mcp install alias) for declaratively adding MCP servers to apm.yml, with --transport / --url / --env / --header / --mcp-version / --registry flags and stdio passthrough. TTY prompts on replace, --force required in CI. Includes --registry URL and MCP_REGISTRY_URL env for custom (enterprise) MCP registries. Closes #807 (#810)
• HTTP dependency support via --allow-insecure + allow_insecure: true dual opt-in; --allow-insecure-host for transitive HTTP from new hosts; credential-helper suppression on HTTP attempts to prevent token leakage; new apm deps list --insecure view with Origin column. Threat model in enterprise/security.md. Thanks @arika0093! (#700)
• Multi-target support: apm.yml target accepts a list ([claude, copilot]) and CLI --target accepts comma-separated values; only specified targets are compiled/installed/packed. Single-string form remains backward compatible. (#628)
• Marketplace UX overhaul: apm view plugin@marketplace, apm outdated Source column, apm marketplace validate, ref-immutability advisory, multi-marketplace shadow detection. (#514)
• New MCP Servers guide (docs/guides/mcp-servers.md) consolidating stdio / registry / remote shapes, flag reference, validation rules, and the conflict matrix in one page; assorted MCP doc drift fixes (#808)
• Build-time update_policy module so package-manager distributions (conda-forge, brew, pixi) can disable apm update and show custom guidance. Thanks @joostsijm! (#675)
• APM Review Panel skill (.github/skills/apm-review-panel/) plus four specialist personas (devx-ux, supply-chain-security, apm-ceo, oss-growth-hacker) routing through an APM CEO arbiter (#777)

Fixed

• Preserve custom git ports across protocols: non-default ports on ssh:// / https:// dependency URLs (e.g. Bitbucket Datacenter SSH 7999, self-hosted GitLab HTTPS 8443) are captured as DependencyReference.port and reused on HTTPS fallback. Closes #661, #731 (#665)
• Token resolution now discriminates by port, fixing credential collisions across multiple self-hosted Git instances on the same host. Thanks @edenfunf! Closes #785 (#788)
• Detect port-like first path segment in SCP shorthand (git@host:7999/path) and raise an actionable error suggesting the ssh:// form. Closes #784 (#787)
• --allow-protocol-fallback emits a one-shot [!] warning when a dependency's custom port is about to be tried across both SSH and HTTPS, recommending pinning the scheme. Closes #786 (#789)
• apm install --global now installs MCP servers to global-capable runtimes (Copilot CLI, Codex CLI) instead of skipping all MCP at user scope; --trust-transitive-mcp no longer ignored under --global. Lockfile-path behavior at --global tracked in #794 (#638)
• apm install no longer silently drops skills/agents/commands when a Claude Code plugin also ships hooks/*.json: detection cascade now classifies plugin-shaped packages as MARKETPLACE_PLUGIN first; emits a [!] warning when a hook-only classification disagrees with package contents (#780)
• apm mcp search / list / show now honour MCP_REGISTRY_URL (previously hardcoded to the public registry), print a Registry: <url> diagnostic when set, and surface the configured URL in network-error messages (#813)
• VS Code adapter defaults to http transport when transport_type is missing from remote registry data, matching Copilot adapter behavior (#654)
• apm init no longer prompts to overwrite three times on Windows CP950 terminals. Closes #602 (#647)
• apm init Next Steps panel surfaces install/marketplace/plugin workflows instead of the dead-end apm run start reference. Closes #603 (#649)

Security

• MCP_REGISTRY_URL validated at startup (schemeless / unsupported schemes rejected; http:// rejected by default, opt in via MCP_REGISTRY_ALLOW_HTTP=1); APM fails closed when a custom registry is unreachable during install pre-flight, instead of silently approving every MCP dep. Default registry keeps assume-valid for transient errors. (#814)
• apm install --mcp defense-in-depth: rejects embedded .. in dep names with a valid positive example, redacts URL credentials in diagnostic output (https://user:token@host/ -> https://host/), warns on --registry / MCP_REGISTRY_URL pointing at loopback / link-local / RFC1918 / cloud-metadata hosts (including decimal-encoded loopback). (#810)
• SimpleRegistryClient applies a (connect=10s, read=30s) timeout on every registry HTTP call, removing the unbounded-hang failure mode. Tunable via MCP_REGISTRY_CONNECT_TIMEOUT / MCP_REGISTRY_READ_TIMEOUT. (#810)

[0.8.12] - 2026-04-19

Added

• apm install now automatically discovers and deploys local .apm/ primitives (skills, instructions, agents, prompts, hooks, commands) to target directories, with local content taking priority over dependencies on collision (#626, #644)
• Deploy primitives from the project root's own .apm/ directory alongside declared dependencies, so single-package projects no longer need a sub-package stub to install their own content (#715)
• Add temp-dir configuration key (apm config set temp-dir PATH) to override the system temporary directory, resolving [WinError 5] Access is denied in corporate Windows environments (#629)

Changed

• Refactor apm install into a modular engine package (apm_cli/install/) with discrete phases and apply Strategy / Template Method / Application Service patterns; public CLI behaviour and the #762 cleanup chokepoint unchanged (#764)
• apm marketplace browse/search/add/update now route through the registry proxy when PROXY_REGISTRY_URL is set; PROXY_REGISTRY_ONLY=1 blocks direct GitHub API calls (#506, #617)
• CI: adopt GitHub Merge Queue with tiered CI (Tier 1 unit + binary on pull_request + merge_group; Tier 2 integration + release-validation on merge_group only) plus an inert pull_request_target stub workflow for required-check satisfaction. CODEOWNERS now requires Lead Maintainer review for any change to .github/workflows/** (#770, #771)
• Bump pytest from 8.4.2 to 9.0.3 (#698)
• Bump dompurify from 3.3.2 to 3.4.0 in /docs (#730)
• Bump lodash-es and langium in /docs (#761)
• Add .editorconfig to standardize charset, line endings, indentation, and trailing whitespace across contributions (#671)
• Add @sergio-sisternes-epam as maintainer (#623)
• Close install/uninstall/update CLI integration coverage gaps surfaced by the #764 review (#767)
• Add 55 unit tests for commands/deps/_utils.py and commands/view.py to address Test Improver backlog items #4 and #5 (#682)

Fixed

• Harden apm install stale-file cleanup to prevent unsafe lockfile deletions, preserve user-edited files via per-file SHA-256 provenance, and improve cleanup reporting during install and --dry-run (#666, #750, #762)
• Local .apm/ stale-cleanup now uses pre-install content hashes for provenance verification. Previously the lockfile was re-read after regeneration, which always yielded empty hashes, causing the user-edit safety gate to be silently skipped for project-local files (#764)
• Fix apm install --target claude not creating .claude/ when the directory does not already exist (auto_create=False targets now get their root directory created when explicitly requested) (#763)
• Fix content hash mismatch on re-install when .git/ is absent from installed packages by falling back to content-hash verification before re-downloading (#763)
• Make apm install idempotent for hook entries: upsert by _apm_source ownership marker instead of unconditionally appending, so re-running install no longer duplicates per-event hook commands (#709)
• Rewrite Windows backslash paths in hook commands' windows key during integration; previously only Unix-style ./ references were rewritten, leaving windows script paths unresolved at runtime (#609)
• Add explicit encoding="utf-8" to .prompt.md open() calls in script_runner to prevent UnicodeDecodeError on Windows non-UTF-8 locales (CP950/CP936/CP932) (#607)
• Validate the project_name argument to apm init and reject / and \ to prevent confusing [WinError 3] and silent path-traversal behaviour (#724)
• Use yaml.safe_dump when generating apm.yml for virtual-file and collection packages, so description values containing : no longer break apm install with a YAML parse error (#707)
• _count_package_files in apm deps list now reads the canonical .apm/context/ (singular) directory; previously it scanned .apm/contexts/ and always reported 0 context files per package (#748)
• apm pack --format plugin no longer emits duplicated skills/skills/ nesting for bare-skill dependencies referenced through virtual paths like skills/<name> (#738)
• Provide an ADO-specific authentication error message for dev.azure.com remotes so users get actionable guidance instead of a generic GitHub-flavored hint (#742)
• Fix apm compile --target codex (and opencode, minimal) being a silent no-op; AgentsCompiler.compile() now routes these through the AGENTS.md compiler instead of returning an empty success result that left stale AGENTS.md files (#766)
• Support codeload.github.com-style archive URLs in Artifactory archive URL generation, unblocking JFrog Artifactory proxies configured against codeload.github.com (#712)
• _parse_artifactory_base_url() now reads PROXY_REGISTRY_URL first (with ARTIFACTORY_BASE_URL fallback + DeprecationWarning), and the virtual-subdirectory download path checks dep_ref.is_artifactory() before falling back to env-var detection, fixing lockfile reinstall failures when proxy config is only on the lockfile entry (#616)
• Fall back to SSH URLs when validating git remotes for generic / self-hosted hosts so apm install no longer fails the pre-install validation step against private SSH-only servers (#584)
• Suppress internal config keys (e.g. default_client) from apm config get output, removing the get/set asymmetry that confused users and was flagged as a Medium security issue (#571)
• Include dependency instructions stored in .github/instructions/ (not only .apm/instructions/) when running apm compile --target claude without --local-only (#631, #642)
• Fix apm marketplace add silently failing for private repos by using credentials when probing marketplace.json (#701)
• Harden marketplace plugin normalization to enforce that manifest-declared agents/skills/commands/hooks paths resolve inside the plugin root (#760)
• Pin codex setup to rust-v0.118.0 for security and reproducibility; update config to wire_api = "responses" (#663)
• Propagate headers and environment variables through OpenCode MCP adapter with defensive copies to prevent mutation (#622)
• Fix apm install hanging indefinitely when corporate firewalls silently drop SSH packets by setting GIT_SSH_COMMAND with ConnectTimeout=30 (#652, #653)
• Stop test_auto_detect_through_proxy from making real api.github.com calls by passing a mock auth_resolver, fixing flaky macOS CI rate-limit failures (#759)
• Fix the Daily Test Improver workflow creating duplicate monthly activity issues; Task 7 now finds and updates the existing month's issue instead of opening a new one each run (#681)

[0.8.11] - 2026-04-06

Added

• Artifactory archive entry download for virtual file packages (#525)
• apm view <package> [field] command for viewing package metadata and remote refs (#613)
• apm view <package> versions field selector lists remote tags and branches via git ls-remote (#613)
• apm outdated command compares locked dependencies against remote refs (#613)
• --parallel-checks (-j) option on apm outdated for concurrent remote checks (default: 4) (#613)
• Rich progress feedback during apm outdated dependency checking (#613)
• --global flag on apm view for inspecting user-scope packages (#613)

Changed

• Rename apm info to apm view for npm convention alignment; apm info kept as hidden alias (#613)
• Scope resolution now happens once via TargetProfile.for_scope() and resolve_targets() -- integrators no longer need scope-aware parameters (#562)
• Unified integration dispatch table in dispatch.py -- both install and uninstall import from one source of truth (#562)
• Hook merge logic deduplicated: three copy-pasted JSON-merge methods replaced with _integrate_merged_hooks() + config dict (#562)
• apm outdated uses SHA comparison for branch-pinned deps instead of reporting them as unknown (#613)

Fixed

• Reject symlinked primitive files in all discovery and resolution paths to prevent symlink-based traversal attacks (#596)
• apm install -g now deploys hooks to the scope-resolved target directory instead of hardcoding .github/hooks/ (#565, #566)
• Hook sync/cleanup derives prefixes dynamically from KNOWN_TARGETS instead of hardcoded paths (#565)
• auto_create=False targets no longer get directories unconditionally created during install (#576)
• apm deps update -g now correctly passes scope, preventing user-scope updates from silently using project-scope paths (#562)
• Subprocess encoding failures on Windows non-UTF-8 consoles (CP950/CP936) -- all subprocess calls now use explicit UTF-8 encoding (#591)
• PowerShell 5.1 compatibility: replace multi-argument Join-Path calls with nested two-argument calls (#593)
• apm marketplace add now respects GITHUB_HOST environment variable for GitHub Enterprise users (#589)
• compilation.exclude patterns now filter primitive discovery, preventing excluded files from leaking into compiled output (#477)
• Runtime detection in script runner now uses anchored patterns to prevent false positives when runtime keywords appear in flag values (#563)
• apm compile now warns when instructions are missing applyTo across all compilation modes (#449)
• Detect remote default branch instead of hardcoding main (#574)
• Warn when two packages deploy a native skill with the same name (#545)

[0.8.10] - 2026-04-03

Fixed

• Hook integrator now processes the windows property in hook JSON files, copying referenced scripts and rewriting paths during install/compile (#311)
• Standardized --target choices, replaced Unicode with ASCII for cp1252 compatibility, and documented missing CLI flags (#519)
• apm install -g now correctly deploys to user-scope directories, skips unsupported primitives, and cleans up on uninstall -- including multi-level paths like ~/.config/opencode/ (#542)
• apm deps update now correctly re-resolves transitive dependencies instead of reusing stale locked SHAs (#548)

Added

• apm install now deploys .instructions.md files to .claude/rules/*.md for Claude Code, converting applyTo: frontmatter to Claude's paths: format (#516)

Changed

• Artifactory virtual file downloads now use the Archive Entry Download API to fetch individual files without downloading the full archive; falls back to full-archive extraction when the entry API is unavailable (#525)

[0.8.9] - 2026-03-31

Fixed

• apm install NAME@MARKETPLACE now respects metadata.pluginRoot from marketplace manifests, fixing resolution of bare-name plugins in marketplaces like awesome-copilot (#512)
• Windows unit test assertion tolerates Rich console line-wrapping on long temp paths (#510)
• Release validation scripts match updated apm deps list scope output (#510)

[0.8.8] - 2026-03-31

Added

• apm install -g/--global for user-scope package installation with per-target support matrix and apm uninstall -g lifecycle (#452)
• Marketplace integration: apm install NAME@MARKETPLACE syntax, apm marketplace add/list/browse/update/remove, apm search across registered marketplaces (#503)
• Codex as integration target: skills to .agents/skills/, agents to .codex/agents/*.toml, hooks to .codex/hooks.json, --target codex on install/compile/pack (#504)
• Lockfile-driven reproducible installs for registry proxies with content_hash verification and RegistryConfig -- by @chkp-roniz (#401)

Changed

• apm deps update skips download when resolved SHA matches lockfile SHA, making the common "nothing changed" case near-instant (#500)

Fixed

• apm install -g ./local-pkg rejects local path dependencies at user scope with a clear error (#452)
• Orphan documentation pages (ci-policy-setup, policy-reference) added to sidebar navigation; stale GitHub Rulesets content updated (#505, #507)

[0.8.7] - 2026-03-30

Fixed

• --target opencode no longer writes prompts/agents to .github/; dispatch loop now only fires primitives declared by the selected target (#488, #494)
• --target cursor now correctly deploys skills to .cursor/skills/ instead of .github/skills/ -- SkillIntegrator respects the explicit target list end-to-end (#482, #494)
• Misleading "transitive dep" error message for direct dependency download failures (#478)
• Sparse checkout using global token instead of per-org token from GITHUB_APM_PAT_<ORG> (#478)
• Duplicate error count when a dependency fails during both resolution and install phases (#478)
• Windows Defender false-positive (Trojan:Win32/Bearfoos.B!ml) mitigation: embed PE version info in Windows binary and disable UPX compression on Windows builds -- by @sergio-sisternes-epam (#490)
• apm deps update was a no-op -- rewrote to delegate to the install engine so lockfile, deployed files, and integration state are all refreshed correctly -- by @webmaxru (#493)

Changed

• Integration dispatch is now data-driven: KNOWN_TARGETS defines each target's primitives and directory layout; adding a target requires zero code changes (#494)
• partition_managed_files() uses O(1) component-based path routing instead of linear prefix scan (#494)
• Uninstall sync uses pre-partitioned buckets via partition_bucket_key() instead of re-scanning the full managed-files set (#494)

Security

• Bump pygments from 2.19.2 to 2.20.0 (#495)

[0.8.6] - 2026-03-27

Added

• apm install --target flag to force deployment to a specific target (copilot, claude, cursor, opencode, all) (#456)
• Global apm install --global / -g and apm uninstall --global flags for user-scope package installation, backed by InstallScope-based scope resolution in core/scope.py; deploys primitives to ~/.copilot/, ~/.claude/, ~/.cursor/, ~/.config/opencode/ and tracks metadata under ~/.apm/ (#452)

Fixed

• Windows antivirus file-lock errors (WinError 32) during apm install with file_ops retry utility (#440)
• Installer fallback to pip in devcontainers, target registry, and lockfile idempotency fixes (#456)
• Reject path traversal sequences in SSH-style Git URLs — by @thakoreh (#458)
• Exclude bundled OpenSSL libs from Linux binary to prevent ABI conflicts (#466)
• Allow spaces in ADO repository names when parsing URLs (#437)
• Gate .claude/commands/ deployment behind integrate_claude flag (#443)
• Sort instruction discovery order for deterministic Build IDs across platforms (#468)
• Share AuthResolver across install to prevent duplicate auth popups (#424)

Changed

• Consolidated path-segment traversal checks into validate_path_segments() in path_security.py (#458)

[0.8.5] - 2026-03-24

Added

• apm audit --ci org-level policy engine -- experimental Phase 1 for enterprise governance over agents in the SDLC; GitHub / GitHub Enterprise only (#365)
• -v shorthand for --verbose, show_default on boolean options, deps clean --dry-run/--yes flags (#303)
• --verbose on apm install now shows auth source diagnostics for virtual package validation failures (#414)
• Nightly runtime inference tests decoupled from release pipeline via ci-runtime.yml (#407)

Changed

• CI pipeline optimization: merged test+build jobs, macOS as root nodes, native setup-uv caching, removed unnecessary setup-node steps (#407)
• Encoding instructions enforce ASCII-only source and CLI output with bracket status symbols (#282)

Fixed

• Windows path hardening: portable_relpath() utility, ~23 relative_to() call-site migrations, CI lint guard (#411, #422)
• Centralized YAML I/O with UTF-8 encoding via yaml_io helpers, preventing Windows cp1252 mojibake, based on prior work by @alopezsanchez (#433, #388)
• SSL certificate verification in PyInstaller binary via certifi runtime hook (#429)
• apm pack --target claude cross-target path mapping for skills/agents installed under .github/ (#426)
• ARTIFACTORY_ONLY enforcement for virtual package types (files, collections, subdirectories) (#418)
• Local path install: descriptive failure messages and Windows drive-letter path recognition (#431, #435)
• Windows test fixes in config command and agents compiler (#410)
• Removed stale WIP folder from tracking, strengthened .gitignore (#420)

[0.8.4] - 2026-03-22

Added

• Centralized AuthResolver with per-(host, org) token resolution, cached and thread-safe — replaces 4 scattered auth implementations (#394)
• CommandLogger and InstallLogger base classes for structured CLI output with validation, resolution, and download phases (#394)
• --verbose flag on uninstall, pack, and unpack commands (#394)
• Verbose output: dependency tree resolution, auth source/type per download, lockfile SHA, package type, inline per-package diagnostics (#394)
• Parent chain breadcrumb in transitive dependency error messages — "root-pkg > mid-pkg > failing-dep" (#394)
• DiagnosticCollector.count_for_package() for inline per-package verbose hints (#394)
• Auth flow diagram and package source behavior matrix in authentication docs (#394)
• Documented ${input:...} variable support in headers and env MCP server fields (#349)

Changed

• All CLI output now uses ASCII symbols ([+], [x], [!]) instead of Unicode characters (#394)
• Migrated _rich_* calls to CommandLogger across install, compile, uninstall, audit, pack, and bundle modules (#394)
• Verbose ref display uses clean #tag @sha format instead of nested parentheses (#394)
• Integration tree lines (└─) no longer have [i] prefix — clean visual hierarchy (#394)
• Global env vars (GITHUB_APM_PAT, GITHUB_TOKEN, GH_TOKEN) apply to all hosts — HTTPS is the security boundary, not host-gating (#394)
• Credential-fill timeout increased from 5s to 60s (configurable via APM_GIT_CREDENTIAL_TIMEOUT, max 180s) — fixes Windows credential picker timeouts (#394)

Fixed

• Bundle lockfile includes non-target deployed_files causing apm unpack verification failure when packing with --target (#394)
• Verbose lockfile iteration crashed with 'str' object has no attribute 'resolved_commit' (#394)
• CodeQL incomplete URL substring sanitization in test assertions (#394)

Security

• Bumped h3 from 1.15.6 to 1.15.9 in docs (#400)

Removed

• Unused image files: copilot-banner.png, copilot-cli-screenshot.png (#391)

[0.8.3] - 2026-03-20

Added

• Plugin authoring — apm pack --format plugin exports APM packages as standalone plugin directories (plugin.json, agents, skills, commands) consumable by Copilot CLI, Claude Code, and Cursor without APM installed (#379)
• apm init --plugin scaffolds a hybrid project with both apm.yml and plugin.json, including a devDependencies section (#379)
• devDependencies in apm.yml — dev deps install normally but are excluded from apm pack output; apm install --dev writes to the dev section (#379)
• VS Code runtime detection now falls back to .vscode/ directory presence when the code binary is not on PATH — by @sergio-sisternes-epam (#359)

Security

• Content integrity hashing — SHA-256 content_hash per dependency in apm.lock.yaml, verified on subsequent installs to detect tampering or force-pushed commits (#315, #379)
• apm audit --strip now preserves a leading BOM while stripping suspicious mid-file BOMs, preventing false negatives — by @dadavidtseng (#372)

Changed

• Install URLs now use short aka.ms/apm-unix and aka.ms/apm-windows redirects across README, docs, and CLI output (#384)
• README highlights link to relevant docs pages; plugin authoring featured as a key value proposition (#385)

Fixed

• DependencyReference preserved through the download pipeline so lockfile records the original ref, not an empty object — by @sergio-sisternes-epam (#383)
• Refactor command and model modules for readability and maintainability — by @sergio-sisternes-epam (#232)
• CLI docs align compile --target opencode, audit --dry-run, and planned audit --drift with current behavior (#373)

[0.8.2] - 2026-03-19

Added

• JFrog Artifactory VCS repository support — explicit FQDN, transparent proxy via ARTIFACTORY_BASE_URL, and air-gapped ARTIFACTORY_ONLY mode (#354)
• GH-AW compatibility gate in release pipeline — gh-aw-compat job tests tokenless install + pack before publishing (#356)
• Release validation now includes test_ghaw_compat scenario (#356)

Fixed

• Credential fill returning garbage token in tokenless CI environments — broke apm install for public repos in GitHub Actions (#356)

Security

• Harden dependency path validation — reject invalid path segments at parse time, enforce install-path containment, safe deletion wrappers across uninstall, prune, and install (#364)

[0.8.1] - 2026-03-17

Added

• Audit hardening — apm unpack content scanning, SARIF/JSON/Markdown --format/--output for CI capture, SecurityGate policy engine, non-zero exits on critical findings (#330)
• Install output now shows resolved git ref alongside package name (e.g. ✓ owner/repo#main (a1b2c3d4)) (#340)
• ${input:...} variable resolution for self-defined MCP server headers and env values — by @sergio-sisternes-epam (#344)

Changed

• Pinning hint moved from inline tip to ── Diagnostics ── section with aggregated count (#347)
• Install ref display uses # separator instead of @ for consistency with dependency syntax (#340)
• Shorthand @alias syntax removed from dependency strings — use the dict format alias: field instead (#340)

Fixed

• File-level downloads from private repos now use OS credential helpers (macOS Keychain, gh auth login, Windows Credential Manager) (#332)
• Lockfile now preserves the host for GitHub Enterprise custom domains so subsequent apm install clones from the correct server (#338)
• MCP registry validation no longer fails on transient network errors (#337)

[0.8.0] - 2026-03-16

Added

• Native Cursor IDE integration — apm install deploys instructions→rules (.mdc), agents, skills, hooks (hooks.json), and MCP (mcp.json) to .cursor/ (#301)
• Native OpenCode integration — apm install deploys agents, commands, skills, and MCP (opencode.json) to .opencode/ — inspired by @timvw (#306)
• Content security scanning with apm audit command — --file, --strip, --dry-run; install-time pre-deployment gate blocks critical hidden Unicode characters (#313)
• Detect variation selectors (Glassworm attack vector), invisible math operators, bidi marks, annotation markers, and deprecated formatting in content scanning — by @raye-deng (#321, #320)
• Context-aware ZWJ detection — emoji joiners preserved by --strip; --strip --dry-run preview mode (#321)
• TargetProfile data layer for scalable multi-target architecture (#301)
• CursorClientAdapter for MCP server management in .cursor/mcp.json (#301)
• OpenCodeClientAdapter for MCP server management in opencode.json (#306)
• Private packages guide and enhanced authentication documentation (#314)

Changed

• Updated docs landing page to include Cursor and OpenCode (#310)
• Updated all doc pages to reflect full Cursor native support (#304)
• Added OpenCode to README headline and compile description (#308)

Fixed

• GitHub API rate-limit 403 responses no longer misdiagnosed as authentication failures — unauthenticated users now see actionable "rate limit exceeded" guidance instead of misleading "private repository" errors

[0.7.9] - 2026-03-13

Added

• Local filesystem path dependencies — install packages from relative/absolute paths with apm install ./my-package (#270)
• Windows native support (Phase 1 & 2) — cross-platform runtime management, PowerShell helpers, and CI parity — by @sergio-sisternes-epam (#227)
• CLI logging UX agent skill for consistent CLI output conventions (#289)

Fixed

• Resolve UnboundLocalError in apm prune crashing all prune operations (#283)
• Restore CWD before TemporaryDirectory cleanup on Windows — by @sergio-sisternes-epam (#281)
• Fix Codex runtime download 404 on Windows — asset naming uses .exe.tar.gz — by @sergio-sisternes-epam (#287)
• Fix UnicodeEncodeError on Windows cp1252 consoles via UTF-8 codepage configuration — by @sergio-sisternes-epam (#287)
• Fix WinError 2 when resolving .cmd/.ps1 shell wrappers via shutil.which() — by @sergio-sisternes-epam (#287)
• Fix GIT_CONFIG_GLOBAL=NUL failure on some Windows git versions — by @sergio-sisternes-epam (#287)
• Improve sub-skill overwrite UX with content skip and collision protection (#289)

Changed

• Lockfile renamed from apm.lock to apm.lock.yaml for IDE syntax highlighting; existing apm.lock files are automatically migrated on the next apm install (#280)
• Add Windows as first-class install option across documentation site (#278)
• Clarify that .github/ deployed files should be committed (#290)

[0.7.8] - 2026-03-13

Added

• Diff-aware apm install — manifest as source of truth: removed packages, ref/version changes, and MCP config drift in apm.yml all self-correct on the next apm install without --update or --force; introduces drift.py with pure helper functions (#260)
• DiagnosticCollector for structured install diagnostics (#267)
• Detailed file-level logging to apm unpack command (#252)
• Astro Starlight documentation site with narrative redesign (#243)

Fixed

• Resolve WinError 32 during sparse-checkout fallback on Windows — by @JanDeDobbeleer (#235)
• CLI consistency: docs alignment, emoji removal, show_default flags (#266)

Changed

• Minimum Python version bumped to 3.10; Black upgraded to 26.3.1 (#269)
• Refactor cli.py and apm_package.py into focused modules — by @sergio-sisternes-epam (#224)
• Revamp README as storefront for documentation site (#251, #256, #258)
• Remove duplicated content from CLI reference page (#261)
• Bump devalue 5.6.3 → 5.6.4 in docs (#263)
• Primitives models coverage 78% → 100%; add discovery and parser coverage tests (#240, #254)

[0.7.7] - 2026-03-10

Added

• copilot as the primary user-facing target name for GitHub Copilot / Cursor / Codex / Gemini output format; vscode and agents remain as aliases (#228)

Changed

• Consolidate pack/unpack documentation into cli-reference, rename Key Commands section

[0.7.6] - 2026-03-10

Added

• apm pack and apm unpack commands for portable bundle creation and extraction with target filtering, archive support, and verification (#218)
• Plugin MCP Server installation — extract, convert, and deploy MCP servers defined in plugin packages (#217)

Fixed

• Plugin agents not deployed due to directory nesting in custom agent paths (#214)
• Skip already-configured self-defined MCP servers on re-install (#191)
• CLI consistency: remove emojis from help strings, fix apm config bare invocation, update descriptions (#212)

Changed

• Extract MCPIntegrator from cli.py — move MCP lifecycle orchestration (~760 lines) into standalone module with hardened error handling (#215)

[0.7.5] - 2026-03-09

Added

• Plugin management system with CLI commands for installing and managing plugins from marketplaces (#83)
• Generic git URL support for GitLab, Bitbucket, and any self-hosted git provider (#150)
• InstructionIntegrator for apm install — deploy .instructions.md files alongside existing integrators (#162)
• Transitive MCP dependency propagation (#123)
• MCP dependency config overlays, transitive trust flag, and related bug fixes (#166)
• Display build commit SHA in CLI version output (#176)
• Documentation: apm.yml manifest schema reference for integrators (#186)

Fixed

• Handle multiple brace groups in applyTo glob patterns (#155)
• Replace substring matching with path-component matching in directory exclusions (#159)
• Handle commit SHA refs in subdirectory package clones (#178)
• Infer registry_name when MCP registry API returns empty values (#181)
• Resolve set() shadowing and sparse checkout ref issues (#184)
• CLI consistency — align help text with docs (#188)
• --update flag now bypasses lockfile SHA to fetch latest content (#192)
• Clean stale MCP servers on install/update/uninstall and prevent .claude folder creation (#201)
• Harden plugin security, validation, tests, and docs (#208)
• Use CREATE_PR_PAT for agentic workflows in Microsoft org (#144)

Changed

• Unified deployed_files manifest for safe integration lifecycle (#163)
• Exclude apm_modules from compilation scanning and cache Set[Path] for performance (#157)
• Performance optimization for deep dependency trees (#173)
• Upgrade GitHub Agentic Workflows to v0.52.1 (#141)
• Fix CLI reference drift from consistency reports (#160, #161)
• Replace CHANGELOG link with roadmap discussion in docs index (#196)
• Update documentation for features from 2026-03-07 (#195)

[0.7.4] - 2025-03-03

Added

• Support hooks as an agent primitive with install-time integration and dependency display (hooks execute at agent runtime, not during apm install) (#97)
• Deploy agents to .claude/agents/ during apm install (#95)
• Promote sub-skills inside packages to top-level .github/skills/ entries (#102)

Fixed

• Fix skill integration bugs, transitive dep cleanup, and simplification (#107)
• Fix transitive dependency handling in compile and orphan detection (#111)
• Fix virtual subdirectory deps marked as orphaned, skipping instruction processing (#100)
• Improve multi-host error guidance when GITHUB_HOST is set (#113, #130)
• Support spaces in Azure DevOps project names (#92)
• Fix GitHub Actions workflow permissions, integration test skip-propagation, and test corrections (#87, #106, #109)

Changed

• Migrated to Microsoft OSS organization (#85, #105)
• Added CODEOWNERS, simplified PR/issue templates, triage labels, and updated CONTRIBUTING.md (#115, #118)
• Added missing version field in the apm.yml README example (#108)
• Slim PR pipelines to Linux-only, auto-approve integration tests, added agentic workflows for maintenance (#98, #103, #104, #119)

[0.7.3] - 2025-02-15

Added

• SUPPORT.md: Added Microsoft repo-template support file directing users to GitHub Issues and Discussions for community support

Changed

• README Rewording: Clarified APM as "an open-source, community-driven dependency manager" to set correct expectations under Microsoft GitHub org
• Microsoft Open Source Compliance: Updated LICENSE, SECURITY.md, CODE_OF_CONDUCT.md, CONTRIBUTING.md, and added Trademark Notice to README
• Source Integrity: Fixed source integrity for all integrators and restructured README

Fixed

• Install Script: Use grep -o for single-line JSON extraction in install.sh
• CI: Fixed integration test script to handle existing venv from CI workflow

Security

• Bumped azure-core 1.35.1 → 1.38.0, aiohttp 3.12.15 → 3.13.3, pip 25.2 → 26.0, urllib3 2.5.0 → 2.6.3

[0.7.2] - 2025-01-23

Added

• Transitive Dependencies: Full dependency resolution with apm.lock lockfile generation

Fixed

• Install Script and apm update: Repaired corrupted header in install.sh. Use awk instead of sed for shell subprocess compatibility. Directed shell output to terminal for password input during update process.

[0.7.1] - 2025-01-22

Fixed

• Collection Extension Handling: Prevent double .collection.yml extension when user specifies full path
• SKILL.md Parsing: Parse SKILL.md directly without requiring apm.yml generation
• Git Host Errors: Actionable error messages for unsupported Git hosts

[0.7.0] - 2024-12-19

Changed

• Native Skills Support: Skills now install to .github/skills/ as the primary target (per agentskills.io standard)
• Skills ≠ Agents: Removed skill → agent transformation; skills and agents are now separate primitives
• Explicit Package Types: Added type field to apm.yml (instructions, skill, hybrid, prompts) for routing control
• Skill Name Validation: Validates and normalizes skill names per agentskills.io spec (lowercase, hyphens, 1-64 chars)
• Claude Compatibility: Skills also copy to .claude/skills/ when .claude/ folder exists

Added

• Auto-creates .github/ directory on install if neither .github/ nor .claude/ exists

[0.6.3] - 2025-12-09

Fixed

• Selective Package Install: apm install <package> now only installs the specified package instead of all packages from apm.yml. Previously, installing a single package would also install unrelated packages. apm install (no args) continues to install all packages from the manifest.

[0.6.2] - 2025-12-09

Fixed

• Claude Skills Integration: Virtual subdirectory packages (like ComposioHQ/awesome-claude-skills/mcp-builder) now correctly trigger skill generation. Previously all virtual packages were skipped, but only virtual files and collections should be skipped—subdirectory packages are complete skill packages.

[0.6.1] - 2025-12-08

Added

• SKILL.md as first-class primitive: meta-description of what an APM Package does for agents to read
• Claude Skills Installation: Install Claude Skills directly as APM Packages
• Bidirectional Format Support:
  • APM packages → SKILL.md (for Claude target)
  • Claude Skills → .agent.md (for VSCode target)
• Skills Documentation: New docs/skills.md guide

[0.6.0] - 2025-12-08

Added

• Claude Integration: First-class support for Claude Code and Claude Desktop

  • CLAUDE.md generation alongside AGENTS.md
  • .claude/commands/ auto-integration from installed packages
  • SKILL.md generation for Claude Skills format
  • Commands get -apm suffix (same pattern as VSCode prompts)

• Target Auto-Detection: Smart compilation based on project structure

  • .github/ only → generates AGENTS.md + VSCode integration
  • .claude/ only → generates CLAUDE.md + Claude integration
  • Both folders → generates all formats
  • Neither folder → generates AGENTS.md only (universal format)

• target field in apm.yml: Persistent target configuration

  target: vscode  # or claude, or all

  Applies to both apm compile and apm install

• --target flag: Override auto-detection

  apm compile --target claude
  apm compile --target vscode
  apm compile --target all

Fixed

• Virtual package uninstall sync: apm uninstall now correctly removes only the specific virtual package's integrated files (uses get_unique_key() for proper path matching)

Changed

• apm compile default: Changed from --target all to auto-detect
• README refactored with npm-style zero-friction onboarding
• Documentation reorganized with Claude integration guide

[0.5.9] - 2025-12-04

Fixed

• ADO Package Commands: compile, prune, and deps list now work correctly with Azure DevOps packages

[0.5.8] - 2025-12-02

Fixed

• ADO Path Structure: Azure DevOps packages now use correct 3-level paths (org/project/repo) throughout install, discovery, update, prune, and uninstall commands
• Virtual Packages: ADO collections and individual files install to correct 3-level paths
• Prune Command: Fixed undefined variable bug in directory cleanup

[0.5.7] - 2025-12-01

Added

• Azure DevOps Support: Install packages from Azure DevOps Services and Server
  • New ADO_APM_PAT environment variable for ADO authentication (separate from GitHub tokens)
  • Supports dev.azure.com/org/project/_git/repo URL format
  • Works alongside GitHub and GitHub Enterprise in mixed-source projects
• Debug Mode: Set APM_DEBUG=1 to see detailed authentication and URL resolution output

Fixed

• GitHub Enterprise Private Repos: Fixed authentication for git ls-remote validation on non-github.com hosts
• Token Selection: Correct token now used per-platform (GitHub vs ADO) in mixed-source installations

[0.5.6] - 2025-12-01

Fixed

• Enterprise GitHub host support: fallback clone now respects GITHUB_HOST env var instead of hardcoding github.com
• Version validation crash when YAML parses version as numeric type (e.g., 1.0 vs "1.0")

Changed

• CI/CD: Updated runner from macos-13 and macos-14 to macos-15 for both x86_64 and ARM64 builds

[0.5.5] - 2025-11-17

Added

• Context Link Resolution: Automatic markdown link resolution for .context.md files across installation and compilation
  • Links in prompts/agents automatically resolve to actual source locations (apm_modules/ or .apm/context/)
  • Works everywhere: IDE, GitHub, all coding agents supporting AGENTS.md
  • No file copying needed—links point directly to source files

[0.5.4] - 2025-11-17

Added

• Agent Integration: Automatic sync of .agent.md files to .github/agents/ with -apm suffix (same pattern as prompt integration)

Fixed

• sync_integration URL normalization bug that caused ALL integrated files to be removed during uninstall instead of only the uninstalled package's files
  • Root cause: Metadata stored full URLs (https://github.com/owner/repo) while dependency list used short form (owner/repo)
  • Impact: Uninstalling one package would incorrectly remove prompts/agents from ALL other packages
  • Fix: Normalize both URL formats to owner/repo before comparison
  • Added comprehensive test coverage for multi-package scenarios
• Uninstall command now correctly removes only apm_modules/owner/repo/ directory (not apm_modules/owner/)

[0.5.3] - 2025-11-16

Changed

• Prompt Naming Pattern: Migrated from @ prefix to -apm suffix for integrated prompts
• GitIgnore Pattern: Updated from .github/prompts/@*.prompt.md to .github/prompts/*-apm.prompt.md

Migration Notes

• Existing Users: Old @-prefixed files will not be automatically removed
• Action Required: Manually delete old @*.prompt.md files from .github/prompts/ after upgrading

[0.5.2] - 2025-11-14

Added

• Prompt Integration with GitHub - Automatically sync downloaded prompts to .github/prompts/ for GitHub Copilot

Changed

• Improved installer UX and console output

[0.5.1] - 2025-11-09

Added

• Package FQDN support - install from any Git host using fully qualified domain names (thanks @richgo for PR #25)

Fixed

• Security: CWE-20 URL validation vulnerability - proper hostname validation using urllib.parse prevents malicious URL bypass attacks
• Package validation HTTPS URL construction for git ls-remote checks
• Virtual package orphan detection in apm deps list command

Changed

• GitHub Enterprise support via GITHUB_HOST environment variable (thanks @richgo for PR #25)
• Build pipeline updates for macOS compatibility

[0.5.0] - 2025-10-30

Added - Virtual Packages

• Virtual Package Support: Install individual files directly from any repository without requiring full APM package structure
  • Individual file packages: apm install owner/repo/path/to/file.prompt.md
• Collection Support: Install curated collections of primitives from Awesome Copilot: apm install github/awesome-copilot/collections/collection-name
  • Collection manifest parser for .collection.yml format
  • Batch download of collection items into organized .apm/ structure
  • Integration with github/awesome-copilot collections

Added - Runnable Prompts

• Auto-Discovery of Prompts: Run installed prompts without manual script configuration
  • apm run <prompt-name> automatically discovers and executes prompts without having to wire a script in apm.yml
  • Search priority: local root → .apm/prompts → .github/prompts → dependencies
  • Qualified path support: apm run owner/repo/prompt-name for disambiguation
  • Collision detection with helpful error messages when multiple prompts found
  • Explicit scripts in apm.yml always take precedence over auto-discovery
• Automatic Runtime Detection: Detects installed runtime (copilot > codex) and generates proper commands
• Zero-Configuration Execution: Install and run prompts immediately without apm.yml scripts section

Changed

• Enhanced dependency resolution to support virtual package unique keys
• Improved GitHub downloader with virtual file and collection package support
• Extended DependencyReference.parse() to detect and validate virtual packages (3+ path segments)
• Script runner now falls back to prompt discovery when script not found in apm.yml

Developer Experience

• Streamlined workflow: apm install <file> → apm run <name> works immediately
• No manual script configuration needed for simple use cases
• Power users retain full control via explicit scripts in apm.yml
• Better error messages for ambiguous prompt names with disambiguation guidance

[0.4.3] - 2025-10-29

Added

• Auto-bootstrap apm.yml when running apm install <package> without existing config
• GitHub Enterprise Server and Data Residency Cloud support via GITHUB_HOST environment variable
• ARM64 Linux support

Changed

• Refactored apm init to initialize projects minimally without templated prompts and instructions
• Improved next steps formatting in project initialization output

Fixed

• GitHub token fallback handling for Codex runtime setup
• Environment variable passing to subprocess in smoke tests and runtime setup

[0.4.2] - 2025-09-25

• Copilot CLI Support

[0.4.1] - 2025-09-18

Fixed

• Fix prompt file resolution for dependencies in org/repo directory structure
• APM dependency prompt files now correctly resolve from apm_modules/org/repo/ paths
• apm run commands can now find and execute prompt files from installed dependencies
• Updated unit tests to match org/repo directory structure for dependency resolution

[0.4.0] - 2025-09-18

• Context Packaging
• Context Dependencies
• Context Compilation
• GitHub MCP Registry integration
• Codex CLI Support