Merge branch 'main' into feature/windsurf-target

Author: yoelabril

.apm/instructions/linting.instructions.md

@@ -0,0 +1,46 @@
+---
+description: "Lint contract: run BEFORE pushing or producing artifacts that claim green CI. Mirrors the CI Lint job."
+---
+
+# Linting (canonical contract)
+
+The CI `Lint` job is a hard gate. Mirror it locally before `git push`
+and before producing any artifact (PR body, release note, audit
+report) that claims CI is green.
+
+## CI-mirror commands
+
+The `Lint` job runs:
+
+- `uv run --extra dev ruff check src/ tests/`
+- `uv run --extra dev ruff format --check src/ tests/`
+
+Both must be silent.
+
+## Local workflow
+
+- **Auto-fix style+imports:** `uv run --extra dev ruff check src/ tests/ --fix`
+- **Apply formatter:** `uv run --extra dev ruff format src/ tests/`
+- **Verify (must be silent):** `uv run --extra dev ruff check src/ tests/ && uv run --extra dev ruff format --check src/ tests/`
+
+Always run the verify pair before `git push` -- the CI Lint job
+fails on any remaining diagnostic.
+
+## Common surprises
+
+- `RUF043` -- use `match=r"..."` for `pytest.raises` patterns with
+  regex metacharacters (`(`, `)`, `[`, etc.).
+- `UP006` / `UP045` -- use `list` / `dict` / `X | None` instead of
+  `List` / `Dict` / `Optional`.
+- `RUF100` -- drop stale `# noqa` directives.
+- `F401` / `F841` -- remove unused imports / unused locals.
+- `SIM103` -- inline negated returns where the body is one line.
+- `I001` -- import sort order (auto-fixable).
+
+## Lifecycle binding
+
+This is the canonical lint contract for the repo. Skills that
+produce artifacts asserting green CI -- notably `pr-description-skill`
+(whose "Validation evidence" row covers CI checks) -- inherit this
+gate transitively. Do NOT redefine ruff commands inside individual
+skills; honor this instruction before invoking them.

.apm/skills/pr-description-skill/SKILL.md

@@ -216,8 +216,7 @@ Run these steps in order. Tick each before moving on.
 1. [ ] Confirm every row of the activation contract is filled in.
    Defense-in-depth gate: before drafting the body, confirm the
    repo's lint contract is green (canonical commands and lifecycle
-   binding live in the project's `copilot-instructions.md` Linting
-   block - do NOT inline or restate them here). If lint is red,
+   binding live in `.apm/instructions/linting.instructions.md`). If lint is red,
    STOP, fix, re-run; a PR body claiming green CI while lint fails
    is a credibility tax we refuse to take on.
 2. [ ] Read the diff in full. Identify per-file change summary,

.github/copilot-instructions.md

@@ -1,33 +1,52 @@
-- This project uses uv to manage Python environments and dependencies.
-    - Use `uv sync` to create the virtual environment and install all dependencies automatically.
-    - Use `uv run <command>` to run commands in the uv-managed environment.
-    - For development dependencies, use `uv sync --extra dev`.
-- **Running tests**: Use pytest via `uv run`. Prefer targeted test runs during development:
-    - **Targeted (fastest, use during iteration):** `uv run pytest tests/unit/path/to/relevant_test.py -x`
-    - **Unit suite (default validation):** `uv run pytest tests/unit tests/test_console.py -x` (~2,400 tests, matches CI)
-    - **Full suite (only before final commit):** `uv run pytest`
-    - When modifying a specific module, run only its corresponding test file(s) first. Run the full unit suite once as final validation before considering your work done.
-- **Test coverage principle**: When modifying existing code, add tests for the code paths you touch, on top of tests for the new functionality.
-- **Linting (run BEFORE pushing - CI gate fails otherwise)**: The `Lint` job runs `uv run --extra dev ruff check src/ tests/` AND `uv run --extra dev ruff format --check src/ tests/`. Mirror it locally:
-    - **Auto-fix style+imports:** `uv run --extra dev ruff check src/ tests/ --fix`
-    - **Apply formatter:** `uv run --extra dev ruff format src/ tests/`
-    - **Verify (must be silent):** `uv run --extra dev ruff check src/ tests/ && uv run --extra dev ruff format --check src/ tests/`
-    - Always run the verify pair before `git push` -- the CI Lint job fails on any remaining diagnostic. Common surprises: `RUF043` (use `match=r"..."` for regex with metacharacters), `UP006/UP045` (use `list`/`dict`/`X | None` instead of `List`/`Dict`/`Optional`), `RUF100` (drop stale `# noqa`), `F401`/`F841` (unused import / unused local).
-    - **Lifecycle binding**: this rule is the canonical lint contract for the repo. Any skill that produces an artifact claiming green CI -- notably `pr-description-skill` (whose "Validation evidence" row covers CI checks) -- inherits this gate transitively. Do NOT redefine ruff commands inside individual skills; honor this rule before invoking them.
-- **Development Workflow**: To run APM from source while working in other directories:
-    - Install in development mode: `cd /path/to/awd-cli && uv run pip install -e .`
-    - Use absolute path: `/Users/danielmeppiel/Repos/awd-cli/.venv/bin/apm compile --verbose --dry-run`
-    - Or create alias: `alias apm-dev='/Users/danielmeppiel/Repos/awd-cli/.venv/bin/apm'`
-    - Changes to source code are immediately reflected (no reinstall needed)
-- The solution must meet the functionality as explained in the [README.md](README.md) file.
-- The general high-level basis to the solution is depicted in [APPROACH.md](../../APPROACH.md). 
-- When developing functionality, we need to respect our own [CONTRIBUTING.md](../../CONTRIBUTING.md) file.
-The architectural decisions and basis for the project in that document are only the inspiring foundation. It can and should always be challenged when needed and is not meant as the only truth, but a very useful context and grounding research.
-- The project is meant for the Open Source community and should be open to contributions and follow the standards of the community.
-- The project is meant to be used by developers and should be easy to use, with a focus on developer experience.
-- The philosophy when architecting and implementing the project is to prime speed and simplicity over complexity. Do NOT over-engineer, but rather build a solid foundation that can be iterated on.
-- APM is an active OSS project under the `microsoft` org with a growing community (250+ stars, external contributors). Breaking changes should be communicated clearly (CHANGELOG.md), but we still favor shipping fast over lengthy deprecation cycles.
-- The goal is to deliver a solid and scalable architecture but simple starting implementation. Not building something complex from the start and then having to simplify it later. Remember we are delivering a new tool to the developer community and we will need to rapidly adapt to what's really useful, evolving standards, etc.
-- **Cross-platform encoding rule**: All source code and CLI output must stay within printable ASCII (U+0020–U+007E). Do NOT use emojis, Unicode symbols, box-drawing characters, em dashes, or any character outside the ASCII range in source files or CLI output strings. Use bracket notation for status symbols: `[+]` success, `[!]` warning, `[x]` error, `[i]` info, `[*]` action, `[>]` running. This is required to prevent `charmap` codec errors on Windows cp1252 terminals.
-- **Path safety rule**: Any code that builds filesystem paths from user input or external data (marketplace names, plugin paths, lockfile entries, bundle contents) **must** use the centralized guards in `src/apm_cli/utils/path_security.py`. Use `validate_path_segments(value, context=)` at parse time to reject traversal sequences (`.`, `..`) with cross-platform backslash normalization, and `ensure_path_within(path, base_dir)` after resolution to assert containment (resolves symlinks). Never write ad-hoc `".." in x` checks.
-- **Expert review panel**: For any non-trivial change (cross-cutting refactor, new CLI surface, dependency/auth/lockfile work, release or positioning decision), invoke the [APM Review Panel skill](skills/apm-review-panel/SKILL.md). It orchestrates seven personas (Python Architect, CLI Logging Expert, DevX UX Expert, Supply Chain Security Expert, APM CEO, OSS Growth Hacker) with explicit routing: specialists raise findings, the CEO arbitrates disagreements and strategic calls, the Growth Hacker side-channels conversion / `WIP/growth-strategy.md` insights to the CEO. Individual per-persona skills (`devx-ux`, `supply-chain-security`, `apm-strategy`, `oss-growth`) auto-activate on relevant edits even outside the panel.
+<!-- Generated by APM CLI from .apm/ primitives -->
+<!-- Build ID: 3a5991d7ca52 -->
+<!-- APM Version: 0.11.0 -->
+
+<!-- Source: .apm/instructions/linting.instructions.md -->
+# Linting (canonical contract)
+
+The CI `Lint` job is a hard gate. Mirror it locally before `git push`
+and before producing any artifact (PR body, release note, audit
+report) that claims CI is green.
+
+## CI-mirror commands
+
+The `Lint` job runs:
+
+- `uv run --extra dev ruff check src/ tests/`
+- `uv run --extra dev ruff format --check src/ tests/`
+
+Both must be silent.
+
+## Local workflow
+
+- **Auto-fix style+imports:** `uv run --extra dev ruff check src/ tests/ --fix`
+- **Apply formatter:** `uv run --extra dev ruff format src/ tests/`
+- **Verify (must be silent):** `uv run --extra dev ruff check src/ tests/ && uv run --extra dev ruff format --check src/ tests/`
+
+Always run the verify pair before `git push` -- the CI Lint job
+fails on any remaining diagnostic.
+
+## Common surprises
+
+- `RUF043` -- use `match=r"..."` for `pytest.raises` patterns with
+  regex metacharacters (`(`, `)`, `[`, etc.).
+- `UP006` / `UP045` -- use `list` / `dict` / `X | None` instead of
+  `List` / `Dict` / `Optional`.
+- `RUF100` -- drop stale `# noqa` directives.
+- `F401` / `F841` -- remove unused imports / unused locals.
+- `SIM103` -- inline negated returns where the body is one line.
+- `I001` -- import sort order (auto-fixable).
+
+## Lifecycle binding
+
+This is the canonical lint contract for the repo. Skills that
+produce artifacts asserting green CI -- notably `pr-description-skill`
+(whose "Validation evidence" row covers CI checks) -- inherit this
+gate transitively. Do NOT redefine ruff commands inside individual
+skills; honor this instruction before invoking them.
+<!-- End source: .apm/instructions/linting.instructions.md -->
+
+---
+*This file was generated by APM CLI. Do not edit manually.*
+*To regenerate: `specify apm compile`*

.github/instructions/linting.instructions.md

@@ -0,0 +1,46 @@
+---
+description: "Lint contract: run BEFORE pushing or producing artifacts that claim green CI. Mirrors the CI Lint job."
+---
+
+# Linting (canonical contract)
+
+The CI `Lint` job is a hard gate. Mirror it locally before `git push`
+and before producing any artifact (PR body, release note, audit
+report) that claims CI is green.
+
+## CI-mirror commands
+
+The `Lint` job runs:
+
+- `uv run --extra dev ruff check src/ tests/`
+- `uv run --extra dev ruff format --check src/ tests/`
+
+Both must be silent.
+
+## Local workflow
+
+- **Auto-fix style+imports:** `uv run --extra dev ruff check src/ tests/ --fix`
+- **Apply formatter:** `uv run --extra dev ruff format src/ tests/`
+- **Verify (must be silent):** `uv run --extra dev ruff check src/ tests/ && uv run --extra dev ruff format --check src/ tests/`
+
+Always run the verify pair before `git push` -- the CI Lint job
+fails on any remaining diagnostic.
+
+## Common surprises
+
+- `RUF043` -- use `match=r"..."` for `pytest.raises` patterns with
+  regex metacharacters (`(`, `)`, `[`, etc.).
+- `UP006` / `UP045` -- use `list` / `dict` / `X | None` instead of
+  `List` / `Dict` / `Optional`.
+- `RUF100` -- drop stale `# noqa` directives.
+- `F401` / `F841` -- remove unused imports / unused locals.
+- `SIM103` -- inline negated returns where the body is one line.
+- `I001` -- import sort order (auto-fixable).
+
+## Lifecycle binding
+
+This is the canonical lint contract for the repo. Skills that
+produce artifacts asserting green CI -- notably `pr-description-skill`
+(whose "Validation evidence" row covers CI checks) -- inherit this
+gate transitively. Do NOT redefine ruff commands inside individual
+skills; honor this instruction before invoking them.

.github/skills/pr-description-skill/SKILL.md

@@ -216,8 +216,7 @@ Run these steps in order. Tick each before moving on.
 1. [ ] Confirm every row of the activation contract is filled in.
    Defense-in-depth gate: before drafting the body, confirm the
    repo's lint contract is green (canonical commands and lifecycle
-   binding live in the project's `copilot-instructions.md` Linting
-   block - do NOT inline or restate them here). If lint is red,
+   binding live in `.apm/instructions/linting.instructions.md`). If lint is red,
    STOP, fix, re-run; a PR body claiming green CI while lint fails
    is a credibility tax we refuse to take on.
 2. [ ] Read the diff in full. Identify per-file change summary,

.github/workflows/notice-drift.yml

@@ -1,10 +1,10 @@
-# NOTICE Drift Check -- guards the third-party attribution file (NOTICE.md)
+# NOTICE Drift Check -- guards the third-party attribution file (NOTICE)
 # against silent drift on every PR and every merge-queue entry. Also runs
 # a license-policy gate (dependency-review-action) on PR-time only.
 #
 # Why this gate exists
 # --------------------
-# `NOTICE.md` is a legally significant artifact: it lists every third-party
+# `NOTICE` is a legally significant artifact: it lists every third-party
 # OSS component shipped inside the apm-cli wheel, with verbatim license
 # texts. Microsoft CELA's "Manual NOTICE Generation" process makes this
 # file *normative* -- if it drifts from the actual install graph (someone
@@ -81,7 +81,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      # Pinned to the same Python version as ci.yml. NOTICE.md content
+      # Pinned to the same Python version as ci.yml. NOTICE content
       # depends on which dist-info layout the installed wheels use, and
       # different interpreters can resolve different conditional deps
       # (e.g. tomli is only installed under python_version<'3.11').
@@ -101,14 +101,14 @@ jobs:
         # --extra dev brings in ruamel.yaml that the generator imports.
         # --frozen guarantees we resolve to the exact versions that the
         # maintainer locked, so the LICENSE text read from dist-info
-        # matches what NOTICE.md was generated against locally.
+        # matches what NOTICE was generated against locally.
         run: uv sync --frozen --extra dev
 
-      # Drift check: regenerate NOTICE.md to memory and diff against the
+      # Drift check: regenerate NOTICE to memory and diff against the
       # committed copy. Exit 1 with a unified diff to stderr if they
       # differ -- the diff lands in the GitHub Actions log so the PR
       # author can see exactly what to regenerate.
-      - name: Verify NOTICE.md is up to date
+      - name: Verify NOTICE is up to date
         run: uv run python scripts/generate-notice.py --check
 
       # Supply-chain hygiene: surface any newly-introduced dep whose

CHANGELOG.md

@@ -10,6 +10,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **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`](https://github.com/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](https://json.schemastore.org/claude-code-plugin.json) 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)
 
@@ -49,29 +51,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **`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)
 
-### Maintainer tooling
-
-- **NOTICE.md** added at repo root per CELA template -- one entry per direct dependency with verbatim license text. (#1043)
-- **NOTICE.md is self-maintaining**: a CI drift gate fails with an exact diff + a `make notice` fix command, plus `dependency-review-action` denies GPL/AGPL/SSPL additions on PR. (#1045, closes #1044)
-- `shared/apm.md` ships a `repair_string_array` helper to unblock `apm-prep` on gh-aw's `[a b]` Go-default formatting (paper-cut filed upstream). (#1033)
-- PR-review-panel and triage-panel skip cleanly (gray ⊘) on unmatched labels instead of failing -- no failed check, no quota burn. Bumps `gh-aw` to v0.71.1. (#1030)
-- `shared/apm.md` recompiled against `microsoft/apm-action@v1.5.0` for the new `bundles-file:` matrix restore (used by #982). (#1026)
-- Review-panel: true matrix fan-out per reviewer persona, binary `approve` / `request-changes` aggregation, label-driven merge gate. (#1022)
-- **Dev Container Feature scaffolded** under `devcontainer/` (closes #717) -- `install.sh` + 37 bats unit tests + 6-distro integration matrix. Not yet published to `ghcr.io`; will be announced in the release that publishes the OCI artifact. (#861)
-
-### Security
-
-- `apm audit --ci` and `apm install` now fail-closed when `apm.yml` is malformed YAML or not a mapping -- previously, policy and baseline checks were silently skipped (severity: medium -- policy bypass). **Migration:** repos with latently malformed `apm.yml` will go from CI-pass to CI-fail on upgrade. Validate before upgrading with `python -c "import yaml; yaml.safe_load(open('apm.yml'))"` or run `apm audit --ci` locally. Fix any YAML syntax errors in `apm.yml` (stray tabs, unquoted colons, non-mapping root). (#936)
-
-### Changed
-
-- Replace `black` + `isort` with Ruff for linting and formatting; add deterministic CI lint gate (~3s), configure 10 rule sets with strangler-fig complexity thresholds, and fix a Python 3.10 f-string compatibility bug in `audit_report.py` -- by @sergio-sisternes-epam (#999)
-
 ## [0.10.0] - 2026-04-27
 
 ### Added