From 93185e187e897442183e75661c338b9351b7117a Mon Sep 17 00:00:00 2001 From: aoirint Date: Wed, 28 Oct 2026 01:53:25 +0900 Subject: [PATCH] chore(skills): deploy reviewed source with APM 0.34.0 Preserve the selected Skills while refreshing their source pin and APM ledger. Co-authored-by: Codex --- .agents/skills/apm-workflow/SKILL.md | 404 +++--------------- .../references/apm-bootstrap.json | 18 +- .../references/bootstrap-refresh.md | 41 ++ .../references/cli-acquisition.md | 44 ++ .../apm-workflow/references/cli-selection.md | 122 ++++++ .../references/collection-maintenance.md | 63 +++ .../apm-workflow/references/completion.md | 43 ++ .../references/dependency-deployment.md | 50 +++ .../references/dependency-updates.md | 31 ++ .../references/upstream-sources.md | 15 + .agents/skills/code-quality-check/SKILL.md | 19 +- .../references/avoiding-overengineering.md | 101 +++++ .../commit-message-quality-check/SKILL.md | 84 +--- .agents/skills/git-worktree-workflow/SKILL.md | 17 +- .agents/skills/github-workflow/SKILL.md | 16 +- .../references/remote-commit.md | 142 ++++++ .agents/skills/prose-quality-check/SKILL.md | 36 +- .../references/handoff-notes.md | 53 +++ .agents/skills/python-quality-check/SKILL.md | 22 +- .../references/ci-and-distribution.md | 23 +- .agents/skills/security-check/SKILL.md | 3 + .../references/external-code-execution.md | 11 + .../actions/check-docker-source/action.yml | 2 +- .github/scripts/application-change-scope.sh | 56 +++ .github/workflows/main.yml | 11 + AGENTS.md | 15 +- THIRD_PARTY_NOTICES.md | 8 +- apm.lock.yaml | 174 ++++++-- apm.yml | 2 +- 29 files changed, 1139 insertions(+), 487 deletions(-) create mode 100644 .agents/skills/apm-workflow/references/bootstrap-refresh.md create mode 100644 .agents/skills/apm-workflow/references/cli-acquisition.md create mode 100644 .agents/skills/apm-workflow/references/cli-selection.md create mode 100644 .agents/skills/apm-workflow/references/collection-maintenance.md create mode 100644 .agents/skills/apm-workflow/references/completion.md create mode 100644 .agents/skills/apm-workflow/references/dependency-deployment.md create mode 100644 .agents/skills/apm-workflow/references/dependency-updates.md create mode 100644 .agents/skills/apm-workflow/references/upstream-sources.md create mode 100644 .agents/skills/code-quality-check/references/avoiding-overengineering.md create mode 100644 .agents/skills/github-workflow/references/remote-commit.md create mode 100644 .agents/skills/prose-quality-check/references/handoff-notes.md create mode 100644 .github/scripts/application-change-scope.sh diff --git a/.agents/skills/apm-workflow/SKILL.md b/.agents/skills/apm-workflow/SKILL.md index 8b1ab4b..5d073bb 100644 --- a/.agents/skills/apm-workflow/SKILL.md +++ b/.agents/skills/apm-workflow/SKILL.md @@ -11,354 +11,62 @@ maintainer exception for a specific unmet gate. Filesystem location and local recency do not establish eligibility. Require full commit pins, lockfile hashes, and review for every changed third-party dependency. -## 1. Inspect before changing - -1. Locate `apm.yml`, `apm.lock.yaml`, `apm-policy.yml`, existing agent - directories, and repository guidance. Read `apm_version` and - `lockfile_version` from an existing lockfile before running a mutating APM - command; treat them as compatibility evidence, not an instruction to keep an - older CLI forever. -2. Read [the bootstrap manifest](references/apm-bootstrap.json). Its version is - the newest APM release whose provenance, artifacts, checksums, publication - date, and cooldown status this Skill has reviewed. When - `cooldown_exception` is present, verify that it identifies the specific - unmet gate, reason, approval time, and scope. Do not infer a broader waiver. - Do not prefer a newer local `current`, `PATH`, project-local, or legacy - executable merely because it is easier to find. -3. Keep an unpublished consumer project at `version: 0.0.0` in `apm.yml`. - Change that version only after its distribution and versioning design is - explicitly decided. -4. Inventory `apm` on `PATH`, project-local copies, and locations reported by - the current official installation documentation and the platform's command - resolver. Record each resolved executable and `--version`; path precedence - does not override cooldown eligibility. - - Select the manifest version when it is already installed and invoke an - off-PATH copy by absolute path. Do not modify PATH to satisfy one repository - task. If the selected version is absent, use the verified temporary-artifact - flow in section 2 instead of installing it implicitly. -5. If the lockfile records an older APM version than the selected eligible - version, capture it for comparison and regenerate it from scratch with the - selected executable. Do not edit `apm_version` by hand: remove only the - validated project lockfile, run `apm lock`, review the complete result, and - then run the frozen install and audit checks. Treat substantial lock-format - churn separately from a dependency update. -6. If the lockfile records a newer, not-yet-eligible APM version, do not execute - that CLI merely to preserve its generator version. Report the mismatch and - wait for maintainer direction before the destructive regeneration in step 5. - After that direction, capture and regenerate the lock by the same procedure - as step 5. Selecting the newest normally eligible CLI is not a cooldown - exception. -7. Use the official lockfile migration guidance to understand schema changes, - but do not substitute `apm install` for the from-scratch regeneration in - step 5. Restore and stop if a frozen or allegedly read-only command rewrites - the lockfile unexpectedly. -8. If `apm.yml` exists, preserve it. Do not run `apm init --yes`, because it - overwrites an existing manifest. -9. If no manifest exists, inspect the repository's agent targets and run - interactive `apm init` from the project root. Select only the targets the - project actually uses; review the generated `apm.yml` before adding deps. -10. Treat the CLI and agent dependencies as supply-chain-sensitive code. Check the - repository policy and any organization policy before proceeding. - -### 1.1 Regenerate a lockfile without losing deployment ownership - -When a CLI migration or ledger repair requires deleting and rebuilding the lockfile, -preserve the old lockfile's ownership evidence before removing it. Generated target -files can remain on disk after the ledger is gone; a new resolver may then classify -them as unmanaged local content, skip the collision, and silently omit a requested -Skill or resource from the new lockfile. - -1. From the old lockfile, record the selected packages and Skill subsets, deployment - owners, deployed paths, content hashes, target roots, and generator version. Compare - this snapshot with `apm.yml` and the filesystem before changing anything. -2. Identify collisions in the actual target root. Distinguish paths owned by the old - APM ledger from project-authored Skills, files owned by another package, and unknown - local content. Never move or delete a path whose ownership is ambiguous. -3. Before removing the old lockfile, move only the exact, verified APM-owned generated - collision paths to a task-specific temporary backup outside the repository. Preserve - relative paths and hashes so the old deployment can be restored. Do not use - `--force` to overwrite a collision or clear the entire agent target. -4. Remove only the validated project lockfile, regenerate it with the selected CLI, and - run the frozen install. A skipped-file or collision warning is a blocker, even when - the command exits successfully. -5. Compare the new package list, requested Skill subsets, deployed paths, and target - roots with the manifest and the old snapshot. Every removed or added path needs an - expected dependency or generator explanation; an unexpectedly missing selected - Skill is lock-generation failure. -6. Run `apm audit --ci` and directly verify representative restored files and hashes. - If regeneration, installation, comparison, or audit fails, restore the old lockfile - and backed-up paths instead of accepting a partial deployment. -7. Delete the temporary backup only after the new lockfile, deployed output, diff, and - audit all pass. Record any ownership ambiguity or tool collision behavior in the - handoff. - -## 2. Obtain the selected eligible APM version safely - -Reuse an installed copy only when its exact version matches the selected -reviewed release. Do not run an unpinned installer or `apm self-update` merely -to obtain whatever version is newest upstream. - -Treat installation, self-update, PATH changes, and replacement of the active -APM binary as user-environment changes. A request to maintain one repository -does not authorize them. - -Read [the bootstrap manifest](references/apm-bootstrap.json), then consult the -current [official installation guide](https://microsoft.github.io/apm/getting-started/installation/), -[`apm self-update` reference](https://microsoft.github.io/apm/reference/cli/self-update/), -and installer source in the -[official APM repository](https://github.com/microsoft/apm). Do not reproduce -their commands, paths, environment variables, or installer behavior in this -Skill: those are upstream-owned and may change. The manifest remains this -Skill's source of truth for the reviewed version, release date, artifacts, and -SHA-256 values. - -When the selected version is not installed: - -1. Download the exact official release archive named in the bootstrap manifest - to a unique operating-system temporary directory. Verify its hard-coded - SHA-256 before extraction, extract the complete bundle, and invoke the - packaged executable by absolute path. Do not add it to PATH, copy a shim, - place it in the repository, or alter the active APM installation. -2. Confirm `--version` exactly matches the manifest. If the official artifact - is not portable on the current platform, cannot preserve its adjacent - runtime files, or fails integrity verification, stop instead of inventing an - installation layout or choosing an ineligible version. -3. Remove only the validated task-specific temporary directory after the work - finishes. Record the archive source, expected and observed SHA-256, - executable path, and version in the handoff. -4. If the user explicitly requests a persistent installation, then consult the - current official sources above and use their documented version-pin and - integrity mechanisms. Let the official installer own its layout. Do not - alter PATH or replace an active binary without explicit authorization for - those specific environment changes. -5. For an enterprise mirror, use HTTPS, set `APM_NO_DIRECT_FALLBACK=1`, and - verify that the mirror serves the identical reviewed artifact and checksum. - Do not treat this as a substitute for review of the artifact. - -## 2.1 Propose a bootstrap-version refresh - -Do not change the bootstrap manifest automatically. Use this proposal flow: - -1. Record the current and candidate tags, release URLs, publication dates, - platform assets, SHA-256 values, and the candidate cooldown date. Start with - the newest candidate that has completed the cooldown, not merely the newest - published or locally installed version. A maintainer may instead select one - exact newer release and approve a cooldown exception for a concrete defect - or operational blocker. -2. Treat cooldown as a minimum gate, not adoption approval. Review provenance, - release notes, installer and artifact integrity, and compatibility from the - current official sources. Require explicit maintainer approval. -3. Run - `uv run --no-project --no-config --locked --script /scripts/propose_bootstrap_update.py` - to isolate the locked helper from the consumer repository's uv configuration - and collect an eligible candidate without changing files. Attach its JSON - output to the proposal. -4. After approval, obtain the candidate through section 2's temporary - artifact flow and run representative lock, frozen-install, audit, and - deployed-output checks without changing the active installation or PATH. - A reproducible resolver, lock migration, install, audit, or output failure - rejects the candidate even after cooldown; keep the current bootstrap and - record the evidence instead of trying a newer unreviewed release. -5. If the candidate passes, run the same isolated command with - `--write --confirm-version `. It updates only - `references/apm-bootstrap.json` and refuses an unconfirmed or mismatched - version. Review the manifest diff before committing. - -For a maintainer-approved cooldown exception, pass the exact -`--candidate-version`, `--cooldown-exception-reason`, and deterministic -`--now` approval timestamp first without `--write`, then repeat with -`--write --confirm-version `. The helper records -`cooldown_exception` in the manifest and refuses an exception without an exact -candidate and reason. The exception waives only the time gate for that -bootstrap CLI release; provenance, checksums, artifact inspection, -compatibility tests, and dependency review remain required. - -Do not use `apm self-update` to perform this refresh. +## When to Use + +Use for APM CLI selection, project setup, pinned dependency deployment, packaged +Skill maintenance, or an update proposal. Classify the operation before loading +its detailed procedure. + +## Common requirements + +- Read repository policy, the manifest and lockfile, and the + [reviewed bootstrap manifest](references/apm-bootstrap.json) before mutation. +- Preserve an existing `apm.yml`; do not run `apm init --yes`. Keep an + unpublished consumer at `version: 0.0.0` until its versioning design is decided. +- Apply `security-check` to CLI and dependency code. Require full commit pins, + content hashes, source/license review, and seven-day eligibility or the exact + documented maintainer exception. An exception waives only its named gate. +- Select the reviewed eligible CLI by exact version, not PATH precedence or + local recency. Do not change PATH or the active installation without explicit + authorization for that user-environment change. +- Treat canonical source, generated deployment, ownership ledger, and notices + as one reviewable result. Regenerate managed output rather than hand-editing it. +- Never use `--force`, `--allow-insecure`, or an insecure HTTP source unless an + explicit documented exception authorizes it. +- Keep discovery, approval, and application separate. Do not silently update a + pin, bootstrap version, or deployment while preparing a proposal. + +## Workflow + +1. Read [CLI selection and lockfile migration](references/cli-selection.md) + before running mutating APM commands. Inventory the repository and available + executables, select the eligible exact version, and resolve lockfile-version + compatibility. If no manifest exists, use its interactive setup branch. +2. Select every applicable operation below. Read its procedure before acting; + the table routes detail and does not make an applicable gate optional. + + | Operation or condition | Required procedure | + | --- | --- | + | Selected CLI is absent; temporary artifact or explicitly requested persistent installation | [CLI acquisition](references/cli-acquisition.md) | + | Review or refresh the bootstrap; normally eligible or exact cooldown-exception candidate | [Bootstrap refresh](references/bootstrap-refresh.md) | + | Add or deploy a remote Skill, prompt, agent, plugin, hook, or MCP dependency | [Dependency deployment](references/dependency-deployment.md) | + | Maintain distributed Skill copies, verify actual target/hash parity, rename, consolidate, or remove local Skills | [Collection maintenance](references/collection-maintenance.md) | + | Discover updates, prepare a proposal, or apply only an approved dependency update | [Dependency updates](references/dependency-updates.md) | + | Reconcile notices, remove a third-party dependency, or complete the handoff | [Notices and completion checks](references/completion.md) | + +3. Follow the selected procedure's ordering and stop conditions. Before a + lockfile rebuild, preserve ownership evidence and back up only exact verified + generated collision paths using the migration procedure. A collision, + missing selected output, unexpected lock rewrite, integrity failure, or + unresolved target discrepancy is not a clean deployment. +4. After deployment, review refs, hashes, generated output and staged changes; + run the required frozen-install and audit checks, and verify the actual + installer target. Use [notices and completion checks](references/completion.md) + for every handoff and distinguish completed verification from blockers. ## Reference sources -| Source | Use | -| --- | --- | -| [Official APM repository](https://github.com/microsoft/apm) | Verify supported configuration, CLI behavior, and upstream guidance. | -| [APM documentation](https://microsoft.github.io/apm/) | Consult the maintained usage and reference documentation. | -| [Official installation guide](https://microsoft.github.io/apm/getting-started/installation/) | Use the supported version pin and installer-managed locations. | -| [Official migration guide](https://microsoft.github.io/apm/troubleshooting/migration/) | Handle lockfile schema and CLI upgrades without inventing a migration path. | -| [`apm self-update` reference](https://microsoft.github.io/apm/reference/cli/self-update/) | Distinguish CLI updates from dependency updates and confirm official rollback behavior. | -| [APM releases](https://github.com/microsoft/apm/releases) | Review release tags, publication dates, assets, and release notes. | -| [GitHub Releases API](https://api.github.com/repos/microsoft/apm/releases?per_page=30) | Obtain machine-readable release metadata; this is the endpoint used by the proposal script. | -| [APM security policy](https://github.com/microsoft/apm/security/policy) | Follow the upstream vulnerability-reporting process. | -| [Pinned bootstrap manifest](references/apm-bootstrap.json) | Obtain this skill's reviewed version, eligible date, asset names, and SHA-256 values. | - -## 3. Add an Agent Skill or dependency - -Use this staged workflow for every remote skill, prompt, agent, plugin, hook, -or MCP dependency: - -1. Identify the exact source repository, optional virtual subdirectory, - release/tag, and full 40-character commit SHA. Review the source, its - release history, declared capabilities, transitive dependencies, and changes - that could execute code or add MCP access. -2. Verify from an authoritative source that the adopted content is at least - seven days old. For a virtual subdirectory in a monorepo, identify the last - commit that changed that subdirectory at the selected ref and calculate the - cooldown from that commit, not from an unrelated later commit elsewhere in - the repository. If its age, provenance, or required hash cannot be verified, - stop and report the blocker. Do not bypass the cooldown without a documented - maintainer exception. -3. Before committing a third-party skill, determine its license from an - authoritative upstream license file or policy. Add or update the - repository-root `THIRD_PARTY_NOTICES.md` with its source repository and - virtual path, full commit SHA, license identifier and canonical text or URL, - plus any supplied copyright or NOTICE text. Do not put this record in an - APM-managed target directory such as `.agents/skills/`. Treat a missing or - unclear license or required notice as a blocker unless a maintainer records - an explicit exception. -4. Add the dependency to `apm.yml` with the full commit SHA, never a default - branch, `latest`, or an unbounded range. When selecting multiple Skills from - one repository at one ref, use one object-form dependency with `git`, `ref`, - and `skills`; do not encode each Skill as a separate virtual dependency. - Keep separate entries only when their repository, ref, or dependency policy - differs. Keep MCP entries under the same review gate and do not put tokens - in tracked YAML. -5. Run `apm lock` to resolve and download without deploying to agent targets. - Review `apm.lock.yaml`: each dependency must resolve to the expected commit - and carry its content hash. In PowerShell checks, wrap variable-cardinality - query results in `@(...)` before using `.Count`, indexing, or membership - tests; one result otherwise becomes a scalar while multiple results become - an array. Assert the expected count and element type. Commit the manifest - and lockfile together. -6. Run `apm install --frozen` only after that review. It must reproduce the - reviewed lockfile and must not resolve a new dependency. Never use - `--force`, `--allow-insecure`, or an insecure HTTP source unless an explicit - documented exception authorizes it. -7. Run `apm audit --ci` after deployment. Fix lockfile, integrity, drift, or - policy findings rather than suppressing them. Add `apm install --frozen` and - `apm audit --ci` to the project's existing CI when the user requests CI - enforcement. - -### 3.1 Maintain a packaged Skill collection - -Apply this section only when a repository publishes Skill copies in both an -authoring target such as `.agents/skills/` and a package directory such as -`.apm/skills/`. - -1. Identify the canonical source and each distributed copy. Use a supported - generator when one exists; otherwise update every copy in the same change. -2. Keep validation artifacts out of canonical package trees before locking or - deployment. Run import-based validators with bytecode writes disabled, such as - with `PYTHONDONTWRITEBYTECODE=1`, or against a disposable copy. Inventory ignored - as well as tracked files for transient caches, and remove only exact task-created - artifacts. If a transient file enters a candidate ledger, discard that candidate - and regenerate from a clean canonical tree. Restore the prior reviewed lockfile - first when one exists; for a first lock, remove only the exact uncommitted - task-created candidate. Do not patch, normalize, or publish a contaminated ledger. -3. Compare relative file sets and content hashes before release. A missing, - extra, or different file is a release blocker, not a cosmetic discrepancy. -4. After `apm install --frozen`, record the installer-reported target and - verify the named Skill at that actual target, rather than assuming a - configured or conventional directory was used. -5. If `apm audit --ci` resolves a different target root, do not call the audit - a pass or failure without direct evidence. Record the discrepancy, verify - the installed file and lockfile hashes directly, and report the observed - behavior for follow-up. -6. After deployment, review the staged diff as well as the working tree. An - installer can rewrite unchanged text with a different line ending; stage - only the expected manifest, lockfile, canonical, and deployed outputs, then - use `git diff --cached --check` and a content review to distinguish a real - generated-file delta from line-ending noise. - -### 3.2 Rename or remove packaged local Skills - -Apply this section when a local packaged Skill is renamed, consolidated, or -removed. Treat it as a deployment-ledger change, not a documentation-only -rename. - -1. Before editing, inventory the retiring and destination source folders, - deployed paths, resource moves, README index rows, repository references, - and every matching entry in `apm.lock.yaml` (`deployments`, deployed-file - lists, and local deployed-file hashes). -2. Move or remove canonical content and update callers first. Preserve - deterministic scripts and directly linked references when their behavior - remains supported; do not recreate them gratuitously. Regenerate every - managed deployment from the canonical source rather than hand-editing - `.agents/` output. -3. Regenerate the lockfile from scratch with the selected reviewed APM CLI - whenever the existing ledger still names a retired deployment path, or when - a normal lock/install cycle cannot prove that removed paths left the ledger. - Do not patch lockfile hashes or deployment entries by hand. Review that no - retired path remains before running `apm install --frozen`. -4. Run `apm install --frozen` and `apm audit --ci`. Treat missing expected - files, orphaned retired files, unintegrated outputs, or a source/deployed - file-set mismatch as release blockers. If the available generator cannot - remove a retired generated path, stop and record the tool limitation rather - than claiming the deployment is clean. -5. Review the complete canonical, deployment, and lockfile diff together. - Confirm the installed target contains the destination Skill exactly once and - no retired Skill name, resource, or hash record remains. - -## 4. Propose updates; do not silently apply them - -Pinned dependencies stay unchanged until a maintainer approves an update. -Create an update proposal, issue, or pull request with no deployment changes -first: - -1. Run `apm outdated` and `apm update --dry-run` to discover candidates - without writing files. -2. For each candidate, record the current and proposed tag and full commit - SHA, upstream release URL and date, SHA-256/content-hash changes, source - review summary, new transitive dependencies, and any MCP, hook, permission, - or target-output changes. -3. State the earliest eligible adoption date: release date plus seven full - days. Keep the proposal open until that date and explicit maintainer - approval; a newer upstream release restarts its own cooldown. -4. After approval, run interactive `apm update` for only the approved package. - Review the plan before accepting it, then review the `apm.yml`, - `apm.lock.yaml`, and deployed-file diff. Run `apm audit --ci` and commit the - result. Re-check the upstream license and notices; update the matching - `THIRD_PARTY_NOTICES.md` entry in the same commit when the source, virtual - path, commit, license, or attribution changes. -5. In CI and ordinary repeat installs, keep using `apm install --frozen`. - Update discovery and update application must remain separate actions. - -## 5. Reconcile third-party notices - -Before handoff, reconcile `THIRD_PARTY_NOTICES.md` with the reviewed lockfile: - -1. For every third-party skill whose files are committed from an APM target, - keep one current notice entry with the source, selected virtual path, locked - SHA, license, and required attribution. -2. When removing a dependency, run `apm prune` and confirm its deployed files - are gone before removing its notice entry. Retain the notice when a copy or - derivative remains in the repository. -3. Treat a changed license, copyright, or NOTICE file as an adoption-review - change, not a metadata-only update. Resolve it before deploying the new - version. - -## Completion checklist - -- `apm.yml` is present and was not overwritten accidentally. -- An unpublished project keeps `version: 0.0.0` until its distribution and - versioning design is approved. -- The selected APM CLI was the newest reviewed release that completed the - seven-day cooldown or had a manifest-recorded maintainer exception for the - specific unmet gate; its absolute path and version were recorded. -- No PATH, active APM installation, or other user-environment state changed - without explicit authorization. -- Any lock-format migration was explicit and reviewed separately from resolved - dependency changes; unexpected lockfile writes were restored and reported. -- Every remote dependency is pinned to a reviewed full commit SHA. -- `apm.lock.yaml` is committed and contains the expected resolved commits and - content hashes, and its `apm_version` matches the selected eligible CLI. -- Each adopted release, or the last change to a selected virtual subdirectory, - met the seven-day cooldown or has a documented maintainer-approved exception. -- Each committed APM-deployed third-party skill has one current - `THIRD_PARTY_NOTICES.md` entry, including its license and required notices; - removed skills have no stale entry unless a copy remains. -- Packaged collections have matching canonical and distributed file sets and - content hashes; the named installed Skill was checked at the - installer-reported target. -- Deployment used `apm install --frozen`; `apm audit --ci` passed in the - verified target context, or any target-resolution discrepancy is documented - with direct installation and lockfile evidence. -- Updates have a reviewable, cooldown-aware proposal before application. +Consult [upstream sources](references/upstream-sources.md) for current official +configuration, installation, migration, update, release, and security guidance. +The [bootstrap manifest](references/apm-bootstrap.json) remains this Skill's +source of truth for its reviewed CLI version, artifact names, and checksums. diff --git a/.agents/skills/apm-workflow/references/apm-bootstrap.json b/.agents/skills/apm-workflow/references/apm-bootstrap.json index 7a35928..b27efca 100644 --- a/.agents/skills/apm-workflow/references/apm-bootstrap.json +++ b/.agents/skills/apm-workflow/references/apm-bootstrap.json @@ -1,40 +1,40 @@ { - "version": "v0.28.0", - "published_at": "2026-08-06T09:29:03Z", + "version": "v0.34.0", + "published_at": "2026-10-19T12:00:55Z", "cooldown_days": 7, - "eligible_on": "2026-08-13T09:29:03Z", - "release_url": "https://github.com/microsoft/apm/releases/tag/v0.28.0", + "eligible_on": "2026-10-26T12:00:55Z", + "release_url": "https://github.com/microsoft/apm/releases/tag/v0.34.0", "download_url_template": "https://github.com/microsoft/apm/releases/download/{version}/{asset}", "assets": [ { "platform": "macos-arm64", "archive": "apm-darwin-arm64.tar.gz", "extracted_directory": "apm-darwin-arm64", - "sha256": "9676a6e7bf2bcb3966538a7130faea14ba030baa45f678597cc3fa15c902cb0a" + "sha256": "030b381825799333ac60a369aaf021ffc9f9e92558b375feec656c42e50e8e5a" }, { "platform": "macos-x86_64", "archive": "apm-darwin-x86_64.tar.gz", "extracted_directory": "apm-darwin-x86_64", - "sha256": "a8397925d45edc3dd666ec80c634f09eb9e5030328288aa0b0ca13c31608f0e0" + "sha256": "55b4ab44eaca6f3a56f59a8e9ca84082c9ed3333a76fe255d6bc62c2a14678a9" }, { "platform": "linux-arm64", "archive": "apm-linux-arm64.tar.gz", "extracted_directory": "apm-linux-arm64", - "sha256": "0b3a644d6073106d1a06623e0baa0c4d75a5ae5ffe55c30eed927bba48600119" + "sha256": "bf355449cbb74b960e3a6ebe851a35ec2c1df6f5178fbb36b90c5a3a015d2c2a" }, { "platform": "linux-x86_64", "archive": "apm-linux-x86_64.tar.gz", "extracted_directory": "apm-linux-x86_64", - "sha256": "7edab3baba96658a20120fc8f3012e3223da7924937a8cbf169bf9805853b8d7" + "sha256": "4487af55604b4fa6f4587f3ee6e833b44ce99c491f11069790e4e13e297cde8c" }, { "platform": "windows-x86_64", "archive": "apm-windows-x86_64.zip", "extracted_directory": "apm-windows-x86_64", - "sha256": "b7085454956a8fa60aa61c062c566095bffe6bc1d6c0902f3a6657b1d1d7fc85" + "sha256": "e9b3dd16b8533af681ea70128ceb8baed983c47cd73d0488ff28dbd5df85def0" } ] } diff --git a/.agents/skills/apm-workflow/references/bootstrap-refresh.md b/.agents/skills/apm-workflow/references/bootstrap-refresh.md new file mode 100644 index 0000000..db05ce9 --- /dev/null +++ b/.agents/skills/apm-workflow/references/bootstrap-refresh.md @@ -0,0 +1,41 @@ +# Propose an APM Bootstrap Refresh + +## 2.1 Propose a bootstrap-version refresh + +Do not change the bootstrap manifest automatically. Use this proposal flow: + +1. Record the current and candidate tags, release URLs, publication dates, + platform assets, SHA-256 values, and the candidate cooldown date. Start with + the newest candidate that has completed the cooldown, not merely the newest + published or locally installed version. A maintainer may instead select one + exact newer release and approve a cooldown exception for a concrete defect + or operational blocker. +2. Treat cooldown as a minimum gate, not adoption approval. Review provenance, + release notes, installer and artifact integrity, and compatibility from the + current official sources. Require explicit maintainer approval. +3. Run + `uv run --no-project --no-config --locked --script /scripts/propose_bootstrap_update.py` + to isolate the locked helper from the consumer repository's uv configuration + and collect an eligible candidate without changing files. Attach its JSON + output to the proposal. +4. After approval, obtain the candidate through the [temporary artifact + flow](cli-acquisition.md) and run representative lock, frozen-install, audit, and + deployed-output checks without changing the active installation or PATH. + A reproducible resolver, lock migration, install, audit, or output failure + rejects the candidate even after cooldown; keep the current bootstrap and + record the evidence instead of trying a newer unreviewed release. +5. If the candidate passes, run the same isolated command with + `--write --confirm-version `. It updates only + `references/apm-bootstrap.json` and refuses an unconfirmed or mismatched + version. Review the manifest diff before committing. + +For a maintainer-approved cooldown exception, pass the exact +`--candidate-version`, `--cooldown-exception-reason`, and deterministic +`--now` approval timestamp first without `--write`, then repeat with +`--write --confirm-version `. The helper records +`cooldown_exception` in the manifest and refuses an exception without an exact +candidate and reason. The exception waives only the time gate for that +bootstrap CLI release; provenance, checksums, artifact inspection, +compatibility tests, and dependency review remain required. + +Do not use `apm self-update` to perform this refresh. diff --git a/.agents/skills/apm-workflow/references/cli-acquisition.md b/.agents/skills/apm-workflow/references/cli-acquisition.md new file mode 100644 index 0000000..60c4b47 --- /dev/null +++ b/.agents/skills/apm-workflow/references/cli-acquisition.md @@ -0,0 +1,44 @@ +# Obtain the Reviewed APM CLI + +## 2. Obtain the selected eligible APM version safely + +Reuse an installed copy only when its exact version matches the selected +reviewed release. Do not run an unpinned installer or `apm self-update` merely +to obtain whatever version is newest upstream. + +Treat installation, self-update, PATH changes, and replacement of the active +APM binary as user-environment changes. A request to maintain one repository +does not authorize them. + +Read [the bootstrap manifest](apm-bootstrap.json), then consult the +current [official installation guide](https://microsoft.github.io/apm/getting-started/installation/), +[`apm self-update` reference](https://microsoft.github.io/apm/reference/cli/self-update/), +and installer source in the +[official APM repository](https://github.com/microsoft/apm). Do not reproduce +their commands, paths, environment variables, or installer behavior in this +Skill: those are upstream-owned and may change. The manifest remains this +Skill's source of truth for the reviewed version, release date, artifacts, and +SHA-256 values. + +When the selected version is not installed: + +1. Download the exact official release archive named in the bootstrap manifest + to a unique operating-system temporary directory. Verify its hard-coded + SHA-256 before extraction, extract the complete bundle, and invoke the + packaged executable by absolute path. Do not add it to PATH, copy a shim, + place it in the repository, or alter the active APM installation. +2. Confirm `--version` exactly matches the manifest. If the official artifact + is not portable on the current platform, cannot preserve its adjacent + runtime files, or fails integrity verification, stop instead of inventing an + installation layout or choosing an ineligible version. +3. Remove only the validated task-specific temporary directory after the work + finishes. Record the archive source, expected and observed SHA-256, + executable path, and version in the handoff. +4. If the user explicitly requests a persistent installation, then consult the + current official sources above and use their documented version-pin and + integrity mechanisms. Let the official installer own its layout. Do not + alter PATH or replace an active binary without explicit authorization for + those specific environment changes. +5. For an enterprise mirror, use HTTPS, set `APM_NO_DIRECT_FALLBACK=1`, and + verify that the mirror serves the identical reviewed artifact and checksum. + Do not treat this as a substitute for review of the artifact. diff --git a/.agents/skills/apm-workflow/references/cli-selection.md b/.agents/skills/apm-workflow/references/cli-selection.md new file mode 100644 index 0000000..33cd543 --- /dev/null +++ b/.agents/skills/apm-workflow/references/cli-selection.md @@ -0,0 +1,122 @@ +# APM CLI Selection and Lockfile Migration + +- [Inspect before changing](#1-inspect-before-changing) +- [Preserve deployment ownership](#11-regenerate-a-lockfile-without-losing-deployment-ownership) +- [Complete the deployment ledger](#12-complete-a-new-or-rebuilt-deployment-ledger) + +## 1. Inspect before changing + +1. Locate `apm.yml`, `apm.lock.yaml`, `apm-policy.yml`, existing agent + directories, and repository guidance. Read `apm_version` and + `lockfile_version` from an existing lockfile before running a mutating APM + command; treat them as compatibility evidence, not an instruction to keep an + older CLI forever. +2. Read [the bootstrap manifest](apm-bootstrap.json). Its version is + the newest APM release whose provenance, artifacts, checksums, publication + date, and cooldown status this Skill has reviewed. When + `cooldown_exception` is present, verify that it identifies the specific + unmet gate, reason, approval time, and scope. Do not infer a broader waiver. + Do not prefer a newer local `current`, `PATH`, project-local, or legacy + executable merely because it is easier to find. +3. Keep an unpublished consumer project at `version: 0.0.0` in `apm.yml`. + Change that version only after its distribution and versioning design is + explicitly decided. +4. Inventory `apm` on `PATH`, project-local copies, and locations reported by + the current official installation documentation and the platform's command + resolver. Record each resolved executable and `--version`; path precedence + does not override cooldown eligibility. + + Select the manifest version when it is already installed and invoke an + off-PATH copy by absolute path. Do not modify PATH to satisfy one repository + task. If the selected version is absent, use the verified temporary-artifact + flow in [CLI acquisition](cli-acquisition.md) instead of installing it implicitly. +5. If the lockfile records an older APM version than the selected eligible + version, capture it for comparison and regenerate it from scratch with the + selected executable. Do not edit `apm_version` by hand: remove only the + validated project lockfile, run `apm lock`, review the complete result, and + then complete the deployment ledger as described below before the frozen + install and audit checks. Treat substantial lock-format + churn separately from a dependency update. +6. If the lockfile records a newer, not-yet-eligible APM version, do not execute + that CLI merely to preserve its generator version. Report the mismatch and + wait for maintainer direction before the destructive regeneration in step 5. + After that direction, capture and regenerate the lock by the same procedure + as step 5. Selecting the newest normally eligible CLI is not a cooldown + exception. +7. Use the official lockfile migration guidance to understand schema changes, + but do not substitute `apm install` for the from-scratch regeneration in + step 5. Restore and stop if a frozen or allegedly read-only command rewrites + the lockfile unexpectedly. +8. If `apm.yml` exists, preserve it. Do not run `apm init --yes`, because it + overwrites an existing manifest. +9. If no manifest exists, inspect the repository's agent targets and run + interactive `apm init` from the project root. Select only the targets the + project actually uses; review the generated `apm.yml` before adding deps. +10. Treat the CLI and agent dependencies as supply-chain-sensitive code. Check the + repository policy and any organization policy before proceeding. + +### 1.1 Regenerate a lockfile without losing deployment ownership + +When a CLI migration or ledger repair requires deleting and rebuilding the lockfile, +preserve the old lockfile's ownership evidence before removing it. Generated target +files can remain on disk after the ledger is gone; a new resolver may then classify +them as unmanaged local content, skip the collision, and silently omit a requested +Skill or resource from the new lockfile. + +1. From the old lockfile, record the selected packages and Skill subsets, deployment + owners, deployed paths, content hashes, target roots, and generator version. Compare + this snapshot with `apm.yml` and the filesystem before changing anything. +2. Identify collisions in the actual target root. Distinguish paths owned by the old + APM ledger from project-authored Skills, files owned by another package, and unknown + local content. Never move or delete a path whose ownership is ambiguous. +3. Before removing the old lockfile, move only the exact, verified APM-owned generated + collision paths to a task-specific temporary backup outside the repository. Preserve + relative paths and hashes so the old deployment can be restored. Do not use + `--force` to overwrite a collision or clear the entire agent target. +4. Remove only the validated project lockfile, regenerate it with the selected CLI, + and complete the deployment ledger using section 1.2 before the frozen install. + A skipped-file or collision warning is a blocker, even when the command exits + successfully. +5. Compare the new package list, requested Skill subsets, deployed paths, and target + roots with the manifest and the old snapshot. Every removed or added path needs an + expected dependency or generator explanation; an unexpectedly missing selected + Skill is lock-generation failure. +6. Run `apm audit --ci` and directly verify representative restored files and hashes. + If regeneration, installation, comparison, or audit fails, restore the old lockfile + and backed-up paths instead of accepting a partial deployment. +7. Delete the temporary backup only after the new lockfile, deployed output, diff, and + audit all pass. Record any ownership ambiguity or tool collision behavior in the + handoff. + +### 1.2 Complete a new or rebuilt deployment ledger + +APM 0.34.0 makes `apm install --frozen` strictly read-only for the lockfile. +`apm lock` resolves packages without deploying, so a new or rebuilt lockfile +can lack deployment records. A frozen install then fails **after deploying +files**; failure does not imply that the target is unchanged. See the +[0.34.0 release notes](https://github.com/microsoft/apm/releases/tag/v0.34.0). + +Use this preparation only for an approved new deployment, source change, or +lockfile rebuild. Ordinary repeat installs and CI remain frozen. + +1. Preserve the prior lockfile and exact verified owned output as in section + 1.1. For a first deployment, inventory existing target files and ownership + before installing; do not overwrite unmanaged or ambiguously owned paths. +2. Run `apm lock` and review the resolved full SHAs, selected Skills, targets, + and expected output changes. Record that snapshot. CLI migration alone does + not approve dependency updates; stop on an unapproved resolution change. +3. Run `apm install` once without `--frozen` to populate the deployment ledger, + retaining the reviewed scope and target options. Do not add `--update`, + `--refresh`, or bypass flags. This step writes both output and the lockfile. +4. Compare the complete result with the snapshot, manifest, prior ledger, and + approved source changes. Confirm dependency commits and selections did not + change, every deployed path has the correct owner and hash, and target or + generator differences are explained. A collision, skipped output, unexpected + ref, or unexplained ownership/path change requires restoration and a stop. +5. Run `apm install --frozen`, verify that the lockfile bytes remain unchanged, + then run `apm audit --ci` and verify actual target/file hashes. Review the + complete diff before committing. Keep the backup until all checks pass. +6. On any failure, inspect partial output and restore the prior lockfile and + exact backed-up files; remove only newly created paths whose ownership is + proven by this attempt. If ownership or restoration cannot be established, + stop and report the remaining state rather than clearing the target. diff --git a/.agents/skills/apm-workflow/references/collection-maintenance.md b/.agents/skills/apm-workflow/references/collection-maintenance.md new file mode 100644 index 0000000..de907a6 --- /dev/null +++ b/.agents/skills/apm-workflow/references/collection-maintenance.md @@ -0,0 +1,63 @@ +# Maintain Packaged Skill Deployments + +## 3.1 Maintain a packaged Skill collection + +Apply this section only when a repository publishes Skill copies in both an +authoring target such as `.agents/skills/` and a package directory such as +`.apm/skills/`. + +1. Identify the canonical source and each distributed copy. Use a supported + generator when one exists; otherwise update every copy in the same change. +2. Keep validation artifacts out of canonical package trees before locking or + deployment. Run import-based validators with bytecode writes disabled, such as + with `PYTHONDONTWRITEBYTECODE=1`, or against a disposable copy. Inventory ignored + as well as tracked files for transient caches, and remove only exact task-created + artifacts. If a transient file enters a candidate ledger, discard that candidate + and regenerate from a clean canonical tree. Restore the prior reviewed lockfile + first when one exists; for a first lock, remove only the exact uncommitted + task-created candidate. Do not patch, normalize, or publish a contaminated ledger. +3. Compare relative file sets and content hashes before release. A missing, + extra, or different file is a release blocker, not a cosmetic discrepancy. +4. After `apm install --frozen`, record the installer-reported target and + verify the named Skill at that actual target, rather than assuming a + configured or conventional directory was used. +5. If `apm audit --ci` resolves a different target root, do not call the audit + a pass or failure without direct evidence. Record the discrepancy, verify + the installed file and lockfile hashes directly, and report the observed + behavior for follow-up. +6. After deployment, review the staged diff as well as the working tree. An + installer can rewrite unchanged text with a different line ending; stage + only the expected manifest, lockfile, canonical, and deployed outputs, then + use `git diff --cached --check` and a content review to distinguish a real + generated-file delta from line-ending noise. + +## 3.2 Rename or remove packaged local Skills + +Apply this section when a local packaged Skill is renamed, consolidated, or +removed. Treat it as a deployment-ledger change, not a documentation-only +rename. + +1. Before editing, inventory the retiring and destination source folders, + deployed paths, resource moves, README index rows, repository references, + and every matching entry in `apm.lock.yaml` (`deployments`, deployed-file + lists, and local deployed-file hashes). +2. Move or remove canonical content and update callers first. Preserve + deterministic scripts and directly linked references when their behavior + remains supported; do not recreate them gratuitously. Regenerate every + managed deployment from the canonical source rather than hand-editing + `.agents/` output. +3. Regenerate the lockfile from scratch with the selected reviewed APM CLI + whenever the existing ledger still names a retired deployment path, or when + a normal lock/install cycle cannot prove that removed paths left the ledger. + Do not patch lockfile hashes or deployment entries by hand. Review that no + retired path remains. Complete and review the + [rebuilt deployment ledger](cli-selection.md#12-complete-a-new-or-rebuilt-deployment-ledger) + before running `apm install --frozen`. +4. Run `apm install --frozen` and `apm audit --ci`. Treat missing expected + files, orphaned retired files, unintegrated outputs, or a source/deployed + file-set mismatch as release blockers. If the available generator cannot + remove a retired generated path, stop and record the tool limitation rather + than claiming the deployment is clean. +5. Review the complete canonical, deployment, and lockfile diff together. + Confirm the installed target contains the destination Skill exactly once and + no retired Skill name, resource, or hash record remains. diff --git a/.agents/skills/apm-workflow/references/completion.md b/.agents/skills/apm-workflow/references/completion.md new file mode 100644 index 0000000..5c18f49 --- /dev/null +++ b/.agents/skills/apm-workflow/references/completion.md @@ -0,0 +1,43 @@ +# APM Notices and Completion Checks + +## 5. Reconcile third-party notices + +Before handoff, reconcile `THIRD_PARTY_NOTICES.md` with the reviewed lockfile: + +1. For every third-party skill whose files are committed from an APM target, + keep one current notice entry with the source, selected virtual path, locked + SHA, license, and required attribution. +2. When removing a dependency, run `apm prune` and confirm its deployed files + are gone before removing its notice entry. Retain the notice when a copy or + derivative remains in the repository. +3. Treat a changed license, copyright, or NOTICE file as an adoption-review + change, not a metadata-only update. Resolve it before deploying the new + version. + +## Completion checklist + +- `apm.yml` is present and was not overwritten accidentally. +- An unpublished project keeps `version: 0.0.0` until its distribution and + versioning design is approved. +- The selected APM CLI was the newest reviewed release that completed the + seven-day cooldown or had a manifest-recorded maintainer exception for the + specific unmet gate; its absolute path and version were recorded. +- No PATH, active APM installation, or other user-environment state changed + without explicit authorization. +- Any lock-format migration was explicit and reviewed separately from resolved + dependency changes; unexpected lockfile writes were restored and reported. +- Every remote dependency is pinned to a reviewed full commit SHA. +- `apm.lock.yaml` is committed and contains the expected resolved commits and + content hashes, and its `apm_version` matches the selected eligible CLI. +- Each adopted release, or the last change to a selected virtual subdirectory, + met the seven-day cooldown or has a documented maintainer-approved exception. +- Each committed APM-deployed third-party skill has one current + `THIRD_PARTY_NOTICES.md` entry, including its license and required notices; + removed skills have no stale entry unless a copy remains. +- Packaged collections have matching canonical and distributed file sets and + content hashes; the named installed Skill was checked at the + installer-reported target. +- Deployment used `apm install --frozen`; `apm audit --ci` passed in the + verified target context, or any target-resolution discrepancy is documented + with direct installation and lockfile evidence. +- Updates have a reviewable, cooldown-aware proposal before application. diff --git a/.agents/skills/apm-workflow/references/dependency-deployment.md b/.agents/skills/apm-workflow/references/dependency-deployment.md new file mode 100644 index 0000000..63fd883 --- /dev/null +++ b/.agents/skills/apm-workflow/references/dependency-deployment.md @@ -0,0 +1,50 @@ +# Add and Deploy an APM Dependency + +## 3. Add an Agent Skill or dependency + +Use this staged workflow for every remote skill, prompt, agent, plugin, hook, +or MCP dependency: + +1. Identify the exact source repository, optional virtual subdirectory, + release/tag, and full 40-character commit SHA. Review the source, its + release history, declared capabilities, transitive dependencies, and changes + that could execute code or add MCP access. +2. Verify from an authoritative source that the adopted content is at least + seven days old. For a virtual subdirectory in a monorepo, identify the last + commit that changed that subdirectory at the selected ref and calculate the + cooldown from that commit, not from an unrelated later commit elsewhere in + the repository. If its age, provenance, or required hash cannot be verified, + stop and report the blocker. Do not bypass the cooldown without a documented + maintainer exception. +3. Before committing a third-party skill, determine its license from an + authoritative upstream license file or policy. Add or update the + repository-root `THIRD_PARTY_NOTICES.md` with its source repository and + virtual path, full commit SHA, license identifier and canonical text or URL, + plus any supplied copyright or NOTICE text. Do not put this record in an + APM-managed target directory such as `.agents/skills/`. Treat a missing or + unclear license or required notice as a blocker unless a maintainer records + an explicit exception. +4. Add the dependency to `apm.yml` with the full commit SHA, never a default + branch, `latest`, or an unbounded range. When selecting multiple Skills from + one repository at one ref, use one object-form dependency with `git`, `ref`, + and `skills`; do not encode each Skill as a separate virtual dependency. + Keep separate entries only when their repository, ref, or dependency policy + differs. Keep MCP entries under the same review gate and do not put tokens + in tracked YAML. +5. Run `apm lock` to resolve and download without deploying to agent targets. + Review `apm.lock.yaml`: each dependency must resolve to the expected commit + and carry its content hash. For a new or changed deployment, complete and + review the [deployment ledger](cli-selection.md#12-complete-a-new-or-rebuilt-deployment-ledger) + before the frozen verification below. In PowerShell checks, wrap variable-cardinality + query results in `@(...)` before using `.Count`, indexing, or membership + tests; one result otherwise becomes a scalar while multiple results become + an array. Assert the expected count and element type. Commit the manifest + and lockfile together. +6. Run `apm install --frozen` only after that review. It must reproduce the + reviewed lockfile and must not resolve a new dependency. Never use + `--force`, `--allow-insecure`, or an insecure HTTP source unless an explicit + documented exception authorizes it. +7. Run `apm audit --ci` after deployment. Fix lockfile, integrity, drift, or + policy findings rather than suppressing them. Add `apm install --frozen` and + `apm audit --ci` to the project's existing CI when the user requests CI + enforcement. diff --git a/.agents/skills/apm-workflow/references/dependency-updates.md b/.agents/skills/apm-workflow/references/dependency-updates.md new file mode 100644 index 0000000..0a938d4 --- /dev/null +++ b/.agents/skills/apm-workflow/references/dependency-updates.md @@ -0,0 +1,31 @@ +# Propose and Apply Approved Dependency Updates + +## 4. Propose updates; do not silently apply them + +Pinned dependencies stay unchanged until a maintainer approves an update. +Create an update proposal, issue, or pull request with no deployment changes +first: + +1. Confirm the intended project root contains `apm.yml` before running + `apm outdated` or `apm update --dry-run`. For user scope, verify the existing + user manifest and use `--global` consistently. Stop if the manifest or scope + is unknown: without a project manifest, `apm update` delegates to CLI + self-update, and `--dry-run` does not protect that fallback. In the verified + dependency scope, these commands discover candidates without writing files. +2. For each candidate, record the current and proposed tag and full commit + SHA, upstream release URL and date, SHA-256/content-hash changes, source + review summary, new transitive dependencies, and any MCP, hook, permission, + or target-output changes. +3. State the earliest eligible adoption date: release date plus seven full + days. Keep the proposal open until that date and explicit maintainer + approval; a newer upstream release restarts its own cooldown. +4. After approval, run interactive `apm update` for only the approved package. + Confirm the planned full commit matches the approved candidate before + accepting it; if the CLI cannot select that candidate, stop rather than + adopting a different ref. Then review the `apm.yml`, + `apm.lock.yaml`, and deployed-file diff. Run `apm audit --ci` and commit the + result. Re-check the upstream license and notices; update the matching + `THIRD_PARTY_NOTICES.md` entry in the same commit when the source, virtual + path, commit, license, or attribution changes. +5. In CI and ordinary repeat installs, keep using `apm install --frozen`. + Update discovery and update application must remain separate actions. diff --git a/.agents/skills/apm-workflow/references/upstream-sources.md b/.agents/skills/apm-workflow/references/upstream-sources.md new file mode 100644 index 0000000..a7e033a --- /dev/null +++ b/.agents/skills/apm-workflow/references/upstream-sources.md @@ -0,0 +1,15 @@ +# APM Reference Sources + +## Reference sources + +| Source | Use | +| --- | --- | +| [Official APM repository](https://github.com/microsoft/apm) | Verify supported configuration, CLI behavior, and upstream guidance. | +| [APM documentation](https://microsoft.github.io/apm/) | Consult the maintained usage and reference documentation. | +| [Official installation guide](https://microsoft.github.io/apm/getting-started/installation/) | Use the supported version pin and installer-managed locations. | +| [Official migration guide](https://microsoft.github.io/apm/troubleshooting/migration/) | Handle lockfile schema and CLI upgrades without inventing a migration path. | +| [`apm self-update` reference](https://microsoft.github.io/apm/reference/cli/self-update/) | Distinguish CLI updates from dependency updates and confirm official rollback behavior. | +| [APM releases](https://github.com/microsoft/apm/releases) | Review release tags, publication dates, assets, and release notes. | +| [GitHub Releases API](https://api.github.com/repos/microsoft/apm/releases?per_page=30) | Obtain machine-readable release metadata; this is the endpoint used by the proposal script. | +| [APM security policy](https://github.com/microsoft/apm/security/policy) | Follow the upstream vulnerability-reporting process. | +| [Pinned bootstrap manifest](apm-bootstrap.json) | Obtain this skill's reviewed version, eligible date, asset names, and SHA-256 values. | diff --git a/.agents/skills/code-quality-check/SKILL.md b/.agents/skills/code-quality-check/SKILL.md index 90f0a06..24eaff8 100644 --- a/.agents/skills/code-quality-check/SKILL.md +++ b/.agents/skills/code-quality-check/SKILL.md @@ -17,6 +17,7 @@ description: >- - Avoid comment noise that repeats obvious code behavior. - Run the smallest meaningful executable checks first, then widen only when needed. - Keep verification notes concise and reusable for commit summaries, PR bodies, or handoff notes. +- Pair with `test-quality-check` for test design, coverage policy, or suite-maintenance decisions. - Pair with `skill-quality-check` for Agent Skill changes and `security-check` for security- or supply-chain-sensitive paths. @@ -25,14 +26,17 @@ description: >- 1. Read the changed files and nearby call sites, not just the patch. 2. Identify code that is hard to scan, overly nested, duplicated, misleadingly named, or coupled to hidden assumptions. -3. Make safe local readability refactors where practical. -4. Add or update comments only when the design intent is not obvious from the code and cannot be +3. When a change adds future-facing structure, abstraction, validation, dependencies, tests, or + defensive behavior, use [avoiding overengineering](references/avoiding-overengineering.md) to + check that each addition has a current consumer, contract, failure mode, or evidenced risk. +4. Make safe local readability refactors where practical. +5. Add or update comments only when the design intent is not obvious from the code and cannot be made obvious with a small refactor. -5. Remove stale, redundant, and misleading comments. -6. Use `prose-quality-check` for documentation, comments, release notes, PR text, issue text, +6. Remove stale, redundant, and misleading comments. +7. Use `prose-quality-check` for documentation, comments, release notes, PR text, issue text, and other explanatory prose that needs readability or wording changes. -7. Re-run the project's language-specific quality checks after edits. -8. Summarize which checks ran, which passed, and why any relevant check was skipped. +8. Re-run the project's language-specific quality checks after edits. +9. Summarize which checks ran, which passed, and why any relevant check was skipped. When reviewing an abstract scenario or a proposed change without concrete files, produce a review plan instead of pretending to inspect code. State the assumptions, the readability changes you would @@ -148,6 +152,9 @@ notes, also update the appropriate docs or changelog. - If verification is still impossible after setup, state the concrete blocker and the command that could not run. - Keep verification consistent across local fixes, commits, and review or handoff preparation. +- Report serious findings discovered during normal review even when their repair is outside the + requested change. Distinguish the observed defect and any verification or release blocker from + a proposed unrelated repair; reporting the finding does not expand the implementation scope. - Record skipped checks with a concrete reason, not a generic "not run" note. ## Supply-Chain Baseline diff --git a/.agents/skills/code-quality-check/references/avoiding-overengineering.md b/.agents/skills/code-quality-check/references/avoiding-overengineering.md new file mode 100644 index 0000000..de93ffe --- /dev/null +++ b/.agents/skills/code-quality-check/references/avoiding-overengineering.md @@ -0,0 +1,101 @@ +# Avoiding overengineering + +## Purpose + +Use this reference when a change introduces structure or safeguards beyond the direct feature edit. +The goal is not to minimize lines of code. It is to keep every addition tied to a current need while +preserving correctness, security, and maintainability. + +## Decision rule + +Establish ownership before comparing implementation and maintenance cost. Identify the current +repository requirement that makes a proposed capability belong in the repository at all. A helper's +own tests, coverage contribution, or general usefulness do not create a consumer, contract, failure +mode, or evidenced risk. Without one of those justifications, remove or defer the capability instead +of making its implementation cheaper. + +Before implementing packaging verification, ask whether a distribution is part of the project's +current contract. An installable source layout or configured build backend does not create a +distribution consumer. For a local application operated through its locked project environment, +verify locked setup and actual application or CLI behavior. Do not build a wheel, create a second +environment, reinstall the wheel, and run an import-only smoke check without a current publication, +deployment, or external-install requirement. + +When a distribution is a current deliverable, a reviewed packaging tool still owns wheel-format +validity and ordinary installer compatibility. Installation is test setup, not a meaningful oracle +by itself. Use the exact artifact only when project-owned packaging configuration or an evidenced +failure can change consumer behavior, then exercise that behavior, such as loading required package +data or starting the deployed service. A successful install or import-only smoke check provides no +distinct evidence without such a contract. Archive member counts, generic file-mode rules, and +digest shape likewise remain tool implementation details unless this project has an explicit +reproducibility, publication, or threat-model requirement for them. Do not implement tool-owned +validation; if it already exists, remove the validation behavior and its dedicated tests instead of +refactoring its assertions. + +Keep an addition when at least one concrete justification exists: + +- A current caller, user, or operator needs it. +- A documented contract requires it. +- An observed failure or realistic failure mode requires it. +- An evidenced security, compatibility, data-loss, or operational risk requires it. +- Deferring it would make a known near-term change materially harder or unsafe. + +Do not implement an addition only because it might be useful someday, completes an imagined +framework, or makes the design look more general. Preserve an obvious place for later change when +that is cheap, but do not implement the later change itself. + +Ask these questions during review: + +1. Who or what uses this now? +2. What concrete failure occurs without it? +3. Is that failure reachable in the current system? +4. Can a smaller local change satisfy the same need? +5. Would a comment or maintained document preserve the decision without executable machinery? +6. Would a reasonable internal refactor break the added test despite preserving behavior? +7. If this addition were removed, which current requirement would become unmet? + +An unclear answer is a reason to defer or narrow the addition, not proof that it is unnecessary. +Investigate high-impact correctness and security uncertainty before removing a safeguard. + +## Common review examples + +| Situation | Proportionate change | Likely overengineering | +| --- | --- | --- | +| One implementation exists | Keep direct code behind a clear function or module boundary | Add factories, strategies, providers, and adapters for hypothetical implementations | +| A small duplication appears once | Leave it local until the shared concept and change pattern are clear | Create a generic utility based on superficial similarity | +| A later component is plausible | Reserve a clear ownership boundary or document the extension rule | Add empty modules, placeholder resources, or configuration for the component | +| Access rules may grow | Group current rules by real responsibility and review applicable limits when growth occurs | Pre-create unused rule sets or split every operation into its own unit | +| External input is unsafe | Validate once at the trust boundary and pass a normalized value inward | Revalidate the same guaranteed invariant in every internal layer | +| A concrete attack path exists | Block the reachable path with the smallest complete safeguard | Implement an exhaustive taxonomy of unrelated hazards without a threat model | +| Tests are needed | Assert observable behavior, contracts, effects, or security outcomes | Assert naming patterns, internal categories, or the current object graph | +| A transient failure is expected | Retry that failure with an explicit limit and observable outcome | Catch every exception and add multiple speculative fallback paths | +| A small standard feature is sufficient | Use the language or platform facility directly | Add a dependency or framework for a few straightforward operations | +| A local application uses an installable source layout | Replay its locked environment and exercise actual application or CLI behavior | Build a wheel, install it into a second environment, and run import-only smoke checks without a distribution consumer | +| A delivered artifact has an evidenced project-packaging failure | Use the exact artifact as test setup and exercise the affected user or deployment behavior | Treat successful installation or import alone as evidence, or inspect generic archive internals | +| A rare manual procedure is adequate | Document the bounded procedure and its risks | Build automation before repetition, error rate, or operational cost justifies it | +| Configuration has one current mode | Expose only values that users must choose now | Add flags for imagined modes with no current consumer | +| A non-obvious choice must survive | Record the reason, rejected practical alternative, and revisit condition | Document a detailed roadmap for unapproved future architecture | + +## Boundaries that justify structure + +Splitting code is justified when responsibilities have different owners, callers, change reasons, +permissions, failure handling, or lifecycles. Keeping related behavior together is justified when it +changes and is reviewed as one unit. Neither more files nor fewer files is an independent quality +goal. + +Similarly, defensive code is not overengineering merely because it adds complexity. Keep controls +that address a reachable high-impact failure. Narrow controls whose scope exceeds the evidenced +risk, and remove controls that only restate guarantees already enforced at a stronger boundary. + +## Review outcome + +Classify each questionable addition as one of: + +- **Keep**: a current contract, consumer, failure mode, or evidenced risk justifies it. +- **Narrow**: the need is real, but the implementation covers more cases or layers than necessary. +- **Defer**: the idea may be useful later, but there is no current implementation need. +- **Remove**: it adds maintenance cost without distinct behavior, evidence, or protection. +- **Investigate**: correctness or security impact is plausible but evidence is incomplete. + +Explain the concrete reason for the classification. Do not label code as overengineered only because +it is unfamiliar, detailed, or longer than an alternative. diff --git a/.agents/skills/commit-message-quality-check/SKILL.md b/.agents/skills/commit-message-quality-check/SKILL.md index 2ae23a8..0bdcd25 100644 --- a/.agents/skills/commit-message-quality-check/SKILL.md +++ b/.agents/skills/commit-message-quality-check/SKILL.md @@ -26,12 +26,12 @@ Reference: 1. Read the proposed message and, when available, the staged diff or commit diff it describes. -2. If the message is a GitHub pull request squash-merge commit, obtain the - canonical pull request title and number from GitHub. Require the first line - to be exactly ` (#)`; do not rely - on a CLI default or accept a title that omits the number. Verify that this - exact candidate is passed as the merge command or API payload's subject, - rather than merely being prepared for comparison. +2. For a GitHub squash-merge message, require the exact canonical PR title and + number suffix in the subject and verify it is passed to the merge operation. + Before any squash merge or other remote commit creation, use + `github-workflow` and read its `references/remote-commit.md` contract. Resolve + that resource from the installed Skill, not a presumed sibling directory; + stop the remote operation if the required Skill or resource is unavailable. 3. Verify the first-line format, blank-line structure, body placement, and footer placement. 4. Check that the type, optional scope, breaking-change marker, and short @@ -40,45 +40,11 @@ Reference: of repeating the summary. 6. Check required footer or trailer metadata, including `BREAKING CHANGE` and AI agent `Co-authored-by:` trailers when applicable. -7. For a squash merge or other remote commit creation, determine the complete - applicable trailer set before writing the payload. Include the author of an - implemented issue and every material design or snippet contributor by - default, unless review marks the contributor not applicable. Retain the - GitHub account and exact attributable email used to resolve each human - trailer. Use the contributor's explicitly supplied GitHub-provided noreply - address by default. Use a Public Email only when the contributor explicitly - directs its use and the current GitHub user response exposes that exact - email; record the choice in the PR attribution block. Never synthesize a - noreply address from `@login` or an ID. If the exact email cannot be - resolved, retain `Needs identity` and stop rather than using a legacy - noreply form. Put every expected - `Co-authored-by:` line in the body file passed to the merge command, retain - each full `Token: value` line exactly once, and verify that same set in the - stored commit; do not treat a matching token with a different value as - preserved or permit an unapproved additional `Co-authored-by:` line. - When the associated PR has a proposed-attribution block, require every - payload trailer to match an `Included` exact line there, omit only `Not - applicable` candidates, and stop for `Needs identity` or unreviewed changes. - Any uncertainty about a candidate's contribution, applicability, GitHub - account, numeric ID, resolved trailer, or review status blocks the merge; - do not omit, guess, or downgrade that candidate to proceed. - Apply role precedence before selecting trailers: the PR creator is the - GitHub-squash primary Git author; a final-diff head-commit author, - implemented-issue author, or material design/snippet contributor is a - trailer candidate only when distinct from that primary author. Reviewers and - merge actors are not candidates from those roles alone. Preserve an - independently evidenced existing trailer even when another role would not - create one. - For a GitHub-hosted squash merge, expect GitHub to record the PR creator as - the primary Git author even when another person performs the merge. This is - platform metadata, not proof of contribution: the creator may be neither an - author nor co-author of the PR-head commits. Do not add either the PR creator - or merger as a `Co-authored-by:` solely because of those roles; retain the PR - `mergedBy` value separately and verify the stored GitHub author association - against the PR creator. If the creator is not a material contributor in the - final diff, mark the mismatch `Needs review` and stop until a maintainer - confirms the intentional attribution or selects another authorized - integration path. +7. For a squash merge or other remote commit creation, complete the remote + commit contract's attribution inventory before preparing the payload. Do not + omit unresolved contributors, invent identities, or proceed with unreviewed + attribution. Require the complete expected trailer set in both the validated + payload and the stored commit. 8. Before an operation creates or rewrites a commit, validate the exact candidate message that the operation will receive: - Build it from the same subject and body file or bytes that will be passed @@ -203,24 +169,16 @@ from their account ID and login. Use a Public Email only if the contributor explicitly directs that choice and GitHub currently exposes the exact address as public. An existing trailer is reusable only when its GitHub author association proves the same account. If no exact attributable email is -available, retain `Needs identity` in the PR and stop rather than using a -legacy noreply address or inventing one. Preserve every -resolved line in the same candidate and -stored-message checks used for AI co-authors. - -Reviewing or approving a PR alone is not material authorship. Before squash -merging, inspect every PR-head commit and applied review suggestion. For each -head-only commit whose material change remains in the final diff, carry its Git -author and every existing `Co-authored-by:` identity into the expected trailer -set unless the identity is already the PR creator's primary Git author. -Preserve exact existing trailers where available; otherwise resolve the GitHub -account under the human-trailer rule. GitHub records the suggestion provider and -the person who applies an accepted suggestion as co-authors of its generated -commit; carry both identities when that suggestion remains in the final diff, -except an identity already represented as the PR creator's primary Git author. -Record the source commit SHA or review URL in the PR attribution block. If a -head commit, applied status, contributor set, or final-diff presence is -uncertain, mark it `Needs review` and stop the merge. +available, retain `Needs identity` and stop rather than using a legacy +noreply address or inventing one. Preserve every resolved line in the same +candidate and stored-message checks used for AI co-authors. + +For squash merges and other remote commit creation, use `github-workflow`'s +`references/remote-commit.md` as the detailed attribution contract. It owns +contributor inventory, identity evidence, role precedence, proposed PR +attribution, applied suggestions, blocking uncertainty, and stored-author +verification. Resolve it as required in Workflow step 2 before the remote +operation; local message review alone does not satisfy that contract. ## Type Selection diff --git a/.agents/skills/git-worktree-workflow/SKILL.md b/.agents/skills/git-worktree-workflow/SKILL.md index 443a11f..9081ee2 100644 --- a/.agents/skills/git-worktree-workflow/SKILL.md +++ b/.agents/skills/git-worktree-workflow/SKILL.md @@ -30,14 +30,15 @@ description: 3. Before pushing, review the complete diff, recent commits, scope, and missing verification; run the final relevant checks. 4. Push and create or update the PR with `github-workflow` when requested. -5. Before squash-merging a GitHub pull request, obtain its canonical title and number from GitHub. Explicitly set the - commit subject to ` (#)`; do not rely on a CLI default or omit the number. - Pass that exact subject through the merge command's `--subject` option; constructing it only in a candidate file or - reading the PR title is insufficient. After merging, inspect the stored commit subject and confirm it still contains - that exact number suffix. -6. Before a PR merge command performs local branch cleanup, check every active worktree. Do not let a hosted-PR CLI - switch to the default branch or delete a branch when that branch is checked out by another worktree. Merge first; - then perform any safe remote or local branch cleanup as a separate action. +5. Before a PR merge, use `github-workflow` and read its + `references/remote-commit.md` contract. Resolve the resource from the installed + Skill, not a presumed sibling directory; stop the merge if it is unavailable. + Confirm the authorized target, exact head, validated subject/body and complete + attribution before the irreversible operation, then read back the stored commit. +6. Before merge-related cleanup, check every active worktree. Do not let a + hosted-PR CLI switch to the default branch or delete a branch checked out by + another worktree. Merge first; perform safe cleanup separately. If the merge + result is uncertain, inspect remote state before retrying it or cleaning up. Use documented builds, tests, linters, formatters, or structural validators appropriate to the change. State skipped verification and its reason in the PR body. After a branch is pushed or attached to a PR, add follow-up commits rather diff --git a/.agents/skills/github-workflow/SKILL.md b/.agents/skills/github-workflow/SKILL.md index e7e7043..b018333 100644 --- a/.agents/skills/github-workflow/SKILL.md +++ b/.agents/skills/github-workflow/SKILL.md @@ -171,17 +171,17 @@ create, update, upload, push, or release operation. against the candidate, allowing only terminal-newline normalization. In PowerShell, do not assign line-oriented `--jq` output when verifying multiline bodies. Remove temporary files. -9. Before `gh pr merge` creates a squash or merge commit, resolve and pass the - exact head SHA with `--match-head-commit`. Build and validate the exact - multiline candidate commit message in a file with - `git interpret-trailers --parse`, require each expected trailer exactly - once, test the stored-message JSON parser with a fixture, merge with the - same body file, then verify `commit.message` from - `repos/{owner}/{repo}/commits/{sha}` using raw JSON. Treat post-merge - verification as secondary to pre-mutation validation. +9. Before a squash merge, another PR merge, or other remote commit creation, + read [the remote commit contract](references/remote-commit.md). Confirm the + authorized target, exact head, validated payload and complete attribution, + private-resource preflight, and active-worktree cleanup guard before the + irreversible operation. Read back the stored commit afterward; inspect + remote state before retrying an uncertain outcome. ## Resources +- [remote-commit.md](references/remote-commit.md): required payload, attribution, + exact-head, cleanup, and read-back contract for remote commit operations. - [fallback-pr-body.md](references/fallback-pr-body.md): fallback PR template when no repository template applies. - [repository-settings.md](references/repository-settings.md): repository diff --git a/.agents/skills/github-workflow/references/remote-commit.md b/.agents/skills/github-workflow/references/remote-commit.md new file mode 100644 index 0000000..693fd41 --- /dev/null +++ b/.agents/skills/github-workflow/references/remote-commit.md @@ -0,0 +1,142 @@ +# Remote Commit and Pull Request Merge Contract + +Read this reference before a squash merge, another GitHub pull-request merge, +or other remote commit creation. Ordinary local commits and PR body edits use +their own workflows; they do not require merge preparation. + +## Contents + +- [Confirm the operation](#confirm-the-operation) +- [Resolve attribution](#resolve-attribution) +- [Validate the exact payload](#validate-the-exact-payload) +- [Execute and read back](#execute-and-read-back) +- [Handle an uncertain outcome](#handle-an-uncertain-outcome) + +## Confirm the operation + +1. Confirm the authorized action, target repository and pull request or remote + ref, intended commit method, and exact head SHA before changing remote state. + Preparing a message or reviewing a PR does not authorize merging it. +2. Apply `github-workflow`'s private repository disclosure preflight to the + complete candidate before the first remote write. Include the exact commit + subject, body, trailers, diff, and attached or generated outputs. Do not send + private-resource identifiers or existence disclosures to a public or + potentially public destination. +3. For a GitHub PR squash merge, obtain the canonical PR title and number from + GitHub. Require the subject to be exactly ` (#)`. + Pass that exact value through the merge command's `--subject` option; a + candidate file or CLI default is insufficient. +4. Resolve the exact PR head SHA and pass it with `--match-head-commit` when + `gh pr merge` creates a squash or merge commit. +5. Check every active worktree before a PR merge command performs local branch + cleanup. Do not let a hosted-PR CLI switch to the default branch or delete + a branch checked out by another worktree. Merge first, then perform any safe + remote or local branch cleanup as a separate action. + +## Resolve attribution + +For a squash merge or other remote commit creation, determine the complete +applicable trailer set before writing the payload. Include the author of an +implemented issue and every material design or snippet contributor by +default, unless review marks the contributor not applicable. Retain the +GitHub account and exact attributable email used to resolve each human +trailer. Use the contributor's explicitly supplied GitHub-provided noreply +address by default. Use a Public Email only when the contributor explicitly +directs its use and the current GitHub user response exposes that exact +email; record the choice in the PR attribution block. Never synthesize a +noreply address from `@login` or an ID. If the exact email cannot be +resolved, retain `Needs identity` and stop rather than using a legacy +noreply form. Put every expected +`Co-authored-by:` line in the body file passed to the merge command, retain +each full `Token: value` line exactly once, and verify that same set in the +stored commit; do not treat a matching token with a different value as +preserved or permit an unapproved additional `Co-authored-by:` line. +When the associated PR has a proposed-attribution block, require every +payload trailer to match an `Included` exact line there, omit only `Not +applicable` candidates, and stop for `Needs identity` or unreviewed changes. +Any uncertainty about a candidate's contribution, applicability, GitHub +account, numeric ID, resolved trailer, or review status blocks the merge; +do not omit, guess, or downgrade that candidate to proceed. +Apply role precedence before selecting trailers: the PR creator is the +GitHub-squash primary Git author; a final-diff head-commit author, +implemented-issue author, or material design/snippet contributor is a +trailer candidate only when distinct from that primary author. Reviewers and +merge actors are not candidates from those roles alone. Preserve an +independently evidenced existing trailer even when another role would not +create one. +For a GitHub-hosted squash merge, expect GitHub to record the PR creator as +the primary Git author even when another person performs the merge. This is +platform metadata, not proof of contribution: the creator may be neither an +author nor co-author of the PR-head commits. Do not add either the PR creator +or merger as a `Co-authored-by:` solely because of those roles; retain the PR +`mergedBy` value separately and verify the stored GitHub author association +against the PR creator. If the creator is not a material contributor in the +final diff, mark the mismatch `Needs review` and stop until a maintainer +confirms the intentional attribution or selects another authorized +integration path. + +Before squash merging, inspect every PR-head commit and applied review suggestion. +For each head-only commit whose material change remains in the final diff, carry +its Git author and every existing `Co-authored-by:` identity into the expected +trailer set unless already represented by the PR creator's primary Git author. +Preserve exact existing trailers where available; otherwise resolve the GitHub +account under the human identity rule above. + +GitHub records the suggestion provider and the person who applies an accepted +suggestion as co-authors of its generated commit. Carry both identities when +that suggestion remains in the final diff, except an identity already represented +as the PR creator's primary Git author. Record the source commit SHA or review +URL in the PR attribution block. If a head commit, applied status, contributor +set, or final-diff presence is uncertain, mark it `Needs review` and stop the merge. + +Use the repository's required AI attribution and +`commit-message-quality-check`'s AI identity selection rules for material AI +contributions. Reviewing or approving a PR alone is not material authorship. + +## Validate the exact payload + +Use `commit-message-quality-check` for Conventional Commits format, message +accuracy, breaking changes, and required attribution. Before the operation +creates or rewrites a remote commit: + +1. Build the exact candidate from the same subject and body file or bytes that + will be passed to the command or API. Reject literal `\n` or `\r\n` text + where real line breaks are intended. +2. Write the exact candidate bytes to a temporary file and pass that file + directly to `git interpret-trailers --parse`. Do not pipe a shell string + that may transform line endings. Require every expected full trailer line + exactly once, with no unapproved additional `Co-authored-by:` line. +3. For a structured API payload, perform the literal-escape check before + serialization. Decode the serialized payload and verify that it reproduces + the validated subject and body; JSON escaping on the wire is not itself a + failure. +4. For `gh pr merge`, test the stored-message JSON parser with a fixture before + merging. Use the same validated subject and body file in the merge command. +5. In PowerShell, capture the complete structured response as raw text, decode + it, and assert that the selected value is a `[string]` before comparing it + with the candidate. Do not assign line-oriented native-command output when + verifying multiline text. +6. Do not perform the mutation until the candidate and applicable identity, + approval, head, and worktree guards pass. + +## Execute and read back + +Execute only the reviewed operation. For a PR merge, use the validated subject, +body file, and exact-head guard. After merging, read `commit.message` from +`repos/{owner}/{repo}/commits/{sha}` using raw JSON and compare it with the +validated candidate. Confirm the stored squash subject retains the exact PR +number suffix and the expected full trailer set. Verify the stored GitHub +author association against the PR creator and retain `mergedBy` separately. + +Treat stored-message verification as secondary to pre-mutation validation. +Report an unverified or mismatched field explicitly; a successful command +alone is not evidence that the complete stored payload matches. + +## Handle an uncertain outcome + +If the mutation result is uncertain, inspect the remote PR/ref and resulting +commit before deciding whether another attempt is safe. Do not repeat a merge +or commit-creation request merely because its response was unavailable. Report +the attempted target and operation, observed remote state, and remaining +uncertainty. Preserve the candidate for comparison instead of guessing that the +operation failed or succeeded. diff --git a/.agents/skills/prose-quality-check/SKILL.md b/.agents/skills/prose-quality-check/SKILL.md index d1959b5..fadb49f 100644 --- a/.agents/skills/prose-quality-check/SKILL.md +++ b/.agents/skills/prose-quality-check/SKILL.md @@ -37,8 +37,10 @@ use the applicable documentation-system or domain-specific skill. - User-facing. - Maintainer-facing. - External-contract text. -2. Confirm the intended claim and factual source are known. If ownership or evidence is disputed, - stop prose-only revision at that boundary and report the gap. +2. Confirm the purpose, intended claim, factual source, and destination for this edit. + Reuse context already supplied by the request or document; resolve only missing context that + could change the edit. If ownership or evidence is disputed, stop prose-only revision at that + boundary and report the gap. 3. Identify overloaded prose: - Sentences carrying multiple ideas, conditions, time references, confidence levels, or relationships. @@ -62,22 +64,37 @@ use the applicable documentation-system or domain-specific skill. code comments harder to read. - Do not change wording strength, modality, tense, or voice only to make sentence wrapping work. Keep wording unchanged unless an independent readability issue justifies rewriting it. -6. Preserve the nuance that made the original wording important: +6. Remove negative-space explanations that do not help the reader act or decide. + - Prefer the current valid instruction or example when it is sufficient on its own. + - Do not add a disclaimer that an old or omitted form is rejected merely because the + implementation no longer accepts it. + - Retain compatibility or migration context when the document owns that history or the audience + needs it to update existing usage, interpret a release, or avoid a concrete transition risk. +7. Preserve the nuance that made the original wording important: - Certainty or confidence level. - Scope and applicability. - Timing and sequence. - Exception or limitation status. - Dependency or compatibility relationships. + - Attribution and upstream relationships. Avoid a bare "official" when it + could transfer authority from one project to another. For example, + [uv documents](https://docs.astral.sh/uv/guides/install-python/) that it + uses Astral's `python-build-standalone` distributions because Python does + not publish official distributable binaries. Describe those artifacts as + "Astral-published Python distributions used by uv," not as "official + Python distributions" or "uv's official Python distributions." - Whether a statement is original, backfilled, inferred, superseded, withdrawn, or still unconfirmed. -7. Use as many short sentences or nested bullets as needed. Do not force a fixed sentence count +8. Use as many short sentences or nested bullets as needed. Do not force a fixed sentence count when the content needs a different shape. -8. Re-read the result as a whole and use the domain-specific skill when one owns the document type. +9. Re-read the result as a whole and use the domain-specific skill when one owns the document type. + - Compare the actual edited destination and scope with the request and any wording or meaning + the user asked to retain. - Confirm it still answers the same question as the original wording. - Confirm each list or paragraph has one clear job. - Confirm the structure did not imply a stronger, weaker, broader, or narrower claim than the source material supports. -9. When establishing repository-wide Markdown validation, copy +10. When establishing repository-wide Markdown validation, copy `assets/markdownlint-cli2.yaml` to `.markdownlint-cli2.yaml` without deleting its rationale comments or changing its rule baseline. Add a local ignore or exception only for an evidenced generated, vendored, submodule, @@ -87,11 +104,18 @@ use the applicable documentation-system or domain-specific skill. recreating its exceptions in the consumer. Use `github-actions-quality-check` to wire the repository-owned configuration into CI. +## Optional handoff notes + +For a requested resumable handoff, use [handoff-notes.md](references/handoff-notes.md) to select the +decisions and open questions the next reader needs. Keep the existing factual-ownership boundary +and preserve the user's choice of destination and level of detail. + ## Output checklist - Audience and document type were considered before rewriting. - Factual ownership and evidence gaps were not silently decided through wording changes. - Enumerations are lists unless inline prose is clearer for the local context. - Dense paragraphs or list items were split or intentionally left intact. +- Current instructions do not narrate irrelevant rejected or legacy alternatives. - Important certainty, scope, timing, relationship, and status nuances were preserved. - The final text is easier to scan and still communicates the same claim. diff --git a/.agents/skills/prose-quality-check/references/handoff-notes.md b/.agents/skills/prose-quality-check/references/handoff-notes.md new file mode 100644 index 0000000..5ecef54 --- /dev/null +++ b/.agents/skills/prose-quality-check/references/handoff-notes.md @@ -0,0 +1,53 @@ +# Resumable Handoff Notes + +Use this optional outline when the user requests a handoff or chooses one as a useful output. +Write it in the requested destination, retaining only information needed to resume the work. +An ordinary prose edit does not require a separate handoff or a standing work log. + +## Select the useful context + +- State the current purpose, reader, scope, and canonical source or destination. +- Record consequential decisions as adopted, rejected, or pending. Include exact wording only + when the wording itself matters; otherwise summarize the choice and its reason. +- Describe the changes made and why. Link to their current canonical location rather than + duplicating maintained technical facts. +- Separate verified results from proposals, assumptions, unavailable evidence, and blockers. + Identify the check or decision needed to resolve each remaining item. +- Give the next resumption point, including any prerequisite or approval still needed. + +Use `domain-architecture-docs-workflow` when canonical placement or technical evidence needs to be +decided. Apply `security-check`'s disclosure boundary before sharing the note. Retain the user's +choice to shorten or omit a record; the outline is not a requirement to archive the conversation. + +## Outline + +Use only the sections that help the next reader act: + +```markdown +## Purpose and current sources + + + +## Decisions + + + +## Changes and verification + + + +## Open items + + + +## Resume here + + +``` + +## Resume against current evidence + +Compare the note with the current request, repository instructions, canonical files, and relevant +change state before acting. Identify superseded decisions explicitly. A note can point to earlier +evidence or approval, but does not create authorization or establish that a planned change ran. +Check the actual state before repeating an operation whose earlier outcome is uncertain. diff --git a/.agents/skills/python-quality-check/SKILL.md b/.agents/skills/python-quality-check/SKILL.md index 3c50e13..0ccb170 100644 --- a/.agents/skills/python-quality-check/SKILL.md +++ b/.agents/skills/python-quality-check/SKILL.md @@ -17,6 +17,10 @@ description: >- - Use for installable Python applications, libraries, and CLIs managed with uv in GitHub-hosted repositories. - Use when establishing or reviewing a repository-wide Python quality baseline. +- For a standalone one-off helper outside an installable project, use + `code-quality-check`, `test-quality-check`, and `security-check` for the + applicable code, behavioral, and execution checks. A helper alone does not + require creating an installable project or distribution pipeline. - Pair with a framework-specific Skill for framework architecture, lifecycle, UI, protocol, or target-packaging requirements. The stricter applicable requirement wins. @@ -36,7 +40,10 @@ and external executables, and `github-actions-quality-check` for workflow triggers, workflow-level `permissions:` declarations, runners, and action pins. Use `github-workflow` for repository settings and enforcement. Use `test-quality-check` for language-independent test design, classification, -coverage policy, and overengineering audits. +coverage policy, and overengineering audits. When the repository uses mise, +use `mise-workflow` for mise's own version, managed tool pins, `mise.lock`, and +task composition; this Skill continues to own Python compatibility and the uv, +Ruff, mypy, pytest, coverage, and distribution commands behind those tasks. This Skill owns the Python-specific baseline. Framework Skills should add only their framework contracts and should not redefine weaker uv, Ruff, typing, @@ -72,6 +79,10 @@ testing, coverage, or distribution rules. source, tests, scripts, workflows, build metadata, and release configuration. - Record project type, supported Python range, distribution/import/entry-point identities, build backend, dependency groups, and artifact targets. + - Establish whether publication, deployment, or external installation makes a + distribution a current deliverable. An installable layout or build backend + alone does not establish that requirement. Keep an existing distribution + obligation and its verification gates in scope. - Mark unavailable facts `blocked`; do not copy values from another project. - Run `uv run --no-config --locked --script /scripts/check_project.py ` @@ -107,7 +118,9 @@ testing, coverage, or distribution rules. installed local action but must not carry another editable copy. - Re-run the complete locked validation on pull requests and on the exact protected integration-branch commit. - - Build applicable distributions from a clean reviewed commit. Inspect + - When a distribution is a current deliverable, follow the complete + [distribution verification](references/ci-and-distribution.md#distribution-verification) + procedure from a clean reviewed commit. Inspect archive paths, metadata, entry points, contents, permissions, licenses, and absence of secrets, caches, tests, and unrelated development files. 6. Verify and report. @@ -125,7 +138,10 @@ testing, coverage, or distribution rules. - Add `uv build`, safe archive inspection with `scripts/inspect_distribution.py`, and clean-environment install/import - checks for installable distributions. + checks when distributions are current deliverables. For a local application + with no distribution consumer, verify its locked environment and actual + application or CLI behavior instead; report artifact checks as not applicable + with the concrete reason. - Report exact commands/results, dependency review scope, coverage statements and branches, artifact evidence, blockers, and every skipped check. diff --git a/.agents/skills/python-quality-check/references/ci-and-distribution.md b/.agents/skills/python-quality-check/references/ci-and-distribution.md index 1dad826..865eb18 100644 --- a/.agents/skills/python-quality-check/references/ci-and-distribution.md +++ b/.agents/skills/python-quality-check/references/ci-and-distribution.md @@ -3,6 +3,7 @@ ## Contents - [CI parity](#ci-parity) +- [Applicability](#applicability) - [Distribution verification](#distribution-verification) - [Completion evidence](#completion-evidence) @@ -16,7 +17,8 @@ Use `github-actions-quality-check` and `security-check` while implementing CI. complete lint, format, strict-mypy, coverage, and build gate on the pinned development minor; repeat a gate across the matrix when its result can vary with syntax, typing, dependency markers, native packages, or build output. -- Clean-install and import the built wheel on every advertised Python minor. +- For a current wheel deliverable, clean-install and import the built wheel on + every advertised Python minor. - Keep CI commands equal to documented local commands. Hidden CI-only flags and local-only shortcuts are findings. - Install/select Python from `.python-version` or an explicit matrix consistent @@ -25,9 +27,26 @@ Use `github-actions-quality-check` and `security-check` while implementing CI. - Bind dependency caches to `uv.lock`, runner, and Python identity. Do not cache `.venv`, secrets, credentials, or signing material. +## Applicability + +Apply distribution verification when publication, deployment, or external +installation makes a wheel, sdist, executable, or installer a current deliverable. +Record that consumer and artifact target during the Python contract inventory. +Preserve an existing distribution contract even when the requested source change +does not edit packaging files. Missing evidence of a known distribution target is +a blocker, not a reason to mark its checks not applicable. + +For a local application operated only through its locked project environment, +verify that environment and actual application or CLI behavior. A `src/` layout +or configured build backend alone does not require adding wheel installation or +import-only checks. Use `code-quality-check` for the consumer and risk review +before adding verification machinery. +The strict tooling, coverage, and CI-parity baseline still applies to the +installable project. + ## Distribution verification -For installable applications, libraries, or CLIs: +For applications, libraries, or CLIs with a current distribution deliverable: 1. Run `uv build` from a clean reviewed commit. `uv.lock` does not by itself lock isolated PEP 517 build requirements: review `[build-system].requires`, diff --git a/.agents/skills/security-check/SKILL.md b/.agents/skills/security-check/SKILL.md index 7374e2b..612e175 100644 --- a/.agents/skills/security-check/SKILL.md +++ b/.agents/skills/security-check/SKILL.md @@ -94,6 +94,9 @@ description: >- 7. Inspect repository scripts, lockfiles, and tool configuration so the recommendation is grounded in the project instead of inventing a new ad hoc path. + Use `mise-workflow` when the reviewed surface includes `mise.toml`, + `mise.lock`, mise-managed tool artifacts, or mise tasks; retain this Skill as + the owner of cooldown, provenance, integrity, secret, and execution findings. 8. Record what was checked: - Sources consulted and why they were sufficient or insufficient. - Exact versions, refs, tags, digests, hashes, or lockfile entries reviewed. diff --git a/.agents/skills/security-check/references/external-code-execution.md b/.agents/skills/security-check/references/external-code-execution.md index bdf2a8e..1272d1c 100644 --- a/.agents/skills/security-check/references/external-code-execution.md +++ b/.agents/skills/security-check/references/external-code-execution.md @@ -16,6 +16,17 @@ replace provenance review, immutable pinning, or the seven-day cooldown. candidate distributions by upload time; keep the policy in PEP 723 metadata so the script carries it with the lock. +## mise + +Use `mise-workflow` for repository configuration, exact tool selection, +platform locks, and task composition. Reproduce reviewed tools with +`mise install --locked`; do not use `mise up`, `mise upgrade`, a floating tool +selector, or an unreviewed `mise self-update` during ordinary execution. + +Review both the logical tool release and the final artifact selected by the +mise backend. A checksum-pinned runtime bundle can be newer than the language +release it contains and remains subject to cooldown and artifact inspection. + ## Poetry 1. Require a reviewed `poetry.lock`. Run `poetry check --lock` before install. diff --git a/.github/actions/check-docker-source/action.yml b/.github/actions/check-docker-source/action.yml index 2719d2e..e9d2546 100644 --- a/.github/actions/check-docker-source/action.yml +++ b/.github/actions/check-docker-source/action.yml @@ -7,7 +7,7 @@ runs: - name: Set up reviewed APM CLI uses: microsoft/apm-action@d723bb64ed70c135bbaf87d126b721dd2dae0439 # v1.10.0 with: - apm-version: "0.28.0" + apm-version: "0.34.0" setup-only: "true" - name: Audit APM deployment diff --git a/.github/scripts/application-change-scope.sh b/.github/scripts/application-change-scope.sh new file mode 100644 index 0000000..4b7f20e --- /dev/null +++ b/.github/scripts/application-change-scope.sh @@ -0,0 +1,56 @@ +#!/usr/bin/env bash +# Keep APM-only maintenance on the validation path, without image publishing. +set -euo pipefail + +[[ "${BEFORE_SHA:-}" =~ ^[0-9a-f]{40}$ ]] || exit 1 +[[ "${AFTER_SHA:-}" =~ ^[0-9a-f]{40}$ ]] || exit 1 +git cat-file -e "${BEFORE_SHA}^{commit}" +git cat-file -e "${AFTER_SHA}^{commit}" + +changed_paths="$(mktemp)" +workflow_diff="$(mktemp)" +trap 'rm -f -- "$changed_paths" "$workflow_diff"' EXIT +git diff --no-renames --name-only -z "$BEFORE_SHA" "$AFTER_SHA" > "$changed_paths" + +# A workflow can hold application inputs (for example image variants). Ignore +# only additions made by this scope gate; all other workflow edits still publish. +workflow_adds_only_scope_gate() { + git diff --no-ext-diff --unified=0 "$BEFORE_SHA" "$AFTER_SHA" -- \ + .github/workflows/main.yml > "$workflow_diff" || return 1 + while IFS= read -r line; do + case "$line" in + 'diff --git '*|'index '*|'--- '*|'+++ '*|'@@ '*) ;; + -*) return 1 ;; + +*) + case "${line:1}" in + ''|" publish_application: \${{ steps.scope.outputs.publish_application }}"|\ + ' fetch-depth: 0'|' - name: Classify application changes'|\ + ' id: scope'|' env:'|\ + " BEFORE_SHA: \${{ github.event.before }}"|\ + " AFTER_SHA: \${{ github.sha }}"|\ + ' run: bash .github/scripts/application-change-scope.sh'|\ + ' # APM maintenance still runs Check; image publishing needs application changes.'|\ + " if: needs.plan.outputs.publish_application == 'true'") ;; + *) return 1 ;; + esac + ;; + *) return 1 ;; + esac + done < "$workflow_diff" +} + +publish_application=false +while IFS= read -r -d '' path; do + case "$path" in + .agents/skills/*|apm.yml|apm.lock.yaml|AGENTS.md|THIRD_PARTY_NOTICES.md|\ + .github/actions/check-docker-source/action.yml|\ + .github/scripts/application-change-scope.sh|docs/operations/publish-images.md) + ;; + .github/workflows/main.yml) + workflow_adds_only_scope_gate || publish_application=true + ;; + *) publish_application=true ;; + esac +done < "$changed_paths" + +printf 'publish_application=%s\n' "$publish_application" >> "$GITHUB_OUTPUT" diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 7e42a37..9d90677 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -32,13 +32,22 @@ jobs: runs-on: ubuntu-slim timeout-minutes: 5 outputs: + publish_application: ${{ steps.scope.outputs.publish_application }} release_mode: ${{ steps.version.outputs.release_mode }} tag: ${{ steps.version.outputs.tag }} steps: - name: Checkout integrated source uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: + fetch-depth: 0 persist-credentials: false + - name: Classify application changes + id: scope + env: + BEFORE_SHA: ${{ github.event.before }} + AFTER_SHA: ${{ github.sha }} + run: bash .github/scripts/application-change-scope.sh + - name: Read release version id: version run: |- @@ -59,6 +68,8 @@ jobs: echo "release_mode=${release_mode}" >> "$GITHUB_OUTPUT" build: + # APM maintenance still runs Check; image publishing needs application changes. + if: needs.plan.outputs.publish_application == 'true' needs: [check, plan] runs-on: ubuntu-24.04 permissions: diff --git a/AGENTS.md b/AGENTS.md index b1f5936..0e7bd8a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,16 +22,25 @@ directly. [aoirint/skills](https://github.com/aoirint/skills). This repository only selects, pins, and deploys them. - To update the Skill dependency, review its source, commit pin, license, and - cooldown first. Regenerate the lockfile with APM, then run - `apm install --frozen` and `apm audit --ci`. Commit the manifest, lockfile, + cooldown first. Preserve exact owned outputs before rebuilding the ledger. + Regenerate the lockfile with APM, complete and review its deployment ledger + with `apm install`, then verify with `apm install --frozen` and + `apm audit --ci`. Commit the manifest, lockfile, notices, and generated `.agents/skills/` changes together. ### Approved cooldown exception -Use APM CLI 0.28.0 for lock operations. It is the newest reviewed release +Use APM CLI 0.34.0 for lock operations. It is the newest reviewed release that satisfies the normal seven-day cooldown; using it is not an exception. A maintainer may explicitly waive the normal seven-day wait for the latest `aoirint/skills` main commit. Record the waiver and exact full commit SHA in the pull request. That waiver applies only to the `aoirint/skills` commit; it does not waive review or cooldown requirements for any of its dependencies. + +## APM-only maintenance in CI + +Main retains source checks for APM-only pin, ledger, generated Skill, guide, +and validation-CI changes, while skipping image build and publication. Other +application or workflow-input changes retain the publishing path. An unavailable +push comparison fails closed instead of publishing an unclassified change. diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md index 97d1fbf..91e0313 100644 --- a/THIRD_PARTY_NOTICES.md +++ b/THIRD_PARTY_NOTICES.md @@ -27,7 +27,11 @@ that are present in that checkout. - Source: [aoirint/skills](https://github.com/aoirint/skills), selected from `.apm/skills/` - Pinned commit: - [`0e41c088efb2bdf44ca58564bb5168d119ac9135`](https://github.com/aoirint/skills/tree/0e41c088efb2bdf44ca58564bb5168d119ac9135) + [`22fe4f84018358059adcf7709cb9df28d1260fd8`](https://github.com/aoirint/skills/tree/22fe4f84018358059adcf7709cb9df28d1260fd8) - Deployed paths: `.agents/skills/{apm-workflow,changelog-workflow,code-quality-check,commit-message-quality-check,docker-quality-check,git-worktree-workflow,github-workflow,gitignore-workflow,prose-quality-check,python-quality-check,release-note-workflow,security-check}/` -- License: [MIT](https://github.com/aoirint/skills/blob/0e41c088efb2bdf44ca58564bb5168d119ac9135/LICENSE) +- License: [MIT](https://github.com/aoirint/skills/blob/22fe4f84018358059adcf7709cb9df28d1260fd8/LICENSE) - Copyright: Copyright (c) 2026 aoirint + +- Cooldown: the maintainer requested immediate adoption of this exact direct + `aoirint/skills` commit. This exception waives only its waiting period; + dependencies remain subject to independent review and cooldown. diff --git a/apm.lock.yaml b/apm.lock.yaml index cb1e3b6..50b6e71 100644 --- a/apm.lock.yaml +++ b/apm.lock.yaml @@ -1,12 +1,11 @@ lockfile_version: '1' -generated_at: '2026-08-23T16:38:51.292601+00:00' -apm_version: 0.28.0 +apm_version: 0.34.0 dependencies: - repo_url: aoirint/skills name: skills host: github.com - resolved_commit: f1c9dbd447dd0a446da62267994b3243596990b2 - resolved_ref: f1c9dbd447dd0a446da62267994b3243596990b2 + resolved_commit: 22fe4f84018358059adcf7709cb9df28d1260fd8 + resolved_ref: 22fe4f84018358059adcf7709cb9df28d1260fd8 version: 0.0.0 package_type: apm_package deployed_files: @@ -15,6 +14,14 @@ dependencies: - .agents/skills/apm-workflow/SKILL.md - .agents/skills/apm-workflow/agents/openai.yaml - .agents/skills/apm-workflow/references/apm-bootstrap.json + - .agents/skills/apm-workflow/references/bootstrap-refresh.md + - .agents/skills/apm-workflow/references/cli-acquisition.md + - .agents/skills/apm-workflow/references/cli-selection.md + - .agents/skills/apm-workflow/references/collection-maintenance.md + - .agents/skills/apm-workflow/references/completion.md + - .agents/skills/apm-workflow/references/dependency-deployment.md + - .agents/skills/apm-workflow/references/dependency-updates.md + - .agents/skills/apm-workflow/references/upstream-sources.md - .agents/skills/apm-workflow/scripts/propose_bootstrap_update.py - .agents/skills/apm-workflow/scripts/propose_bootstrap_update.py.lock - .agents/skills/changelog-workflow @@ -25,6 +32,7 @@ dependencies: - .agents/skills/code-quality-check/README.md - .agents/skills/code-quality-check/SKILL.md - .agents/skills/code-quality-check/agents/openai.yaml + - .agents/skills/code-quality-check/references/avoiding-overengineering.md - .agents/skills/commit-message-quality-check - .agents/skills/commit-message-quality-check/README.md - .agents/skills/commit-message-quality-check/SKILL.md @@ -49,6 +57,7 @@ dependencies: - .agents/skills/github-workflow/SKILL.md - .agents/skills/github-workflow/agents/openai.yaml - .agents/skills/github-workflow/references/fallback-pr-body.md + - .agents/skills/github-workflow/references/remote-commit.md - .agents/skills/github-workflow/references/repository-settings.md - .agents/skills/github-workflow/scripts/check_llm_disclosure.py - .agents/skills/gitignore-workflow @@ -60,6 +69,7 @@ dependencies: - .agents/skills/prose-quality-check/SKILL.md - .agents/skills/prose-quality-check/agents/openai.yaml - .agents/skills/prose-quality-check/assets/markdownlint-cli2.yaml + - .agents/skills/prose-quality-check/references/handoff-notes.md - .agents/skills/python-quality-check - .agents/skills/python-quality-check/README.md - .agents/skills/python-quality-check/SKILL.md @@ -87,19 +97,28 @@ dependencies: - .agents/skills/security-check/references/external-code-execution.md deployed_file_hashes: .agents/skills/apm-workflow/README.md: sha256:e346edab06f5ec792cdb77edcaa8042f523af67753dc4fe72498ae1899b87c89 - .agents/skills/apm-workflow/SKILL.md: sha256:f4d7a88ce5919909fb68bc77d6c95723ce8f2d9bffe309aa0e25abef4a8997fa + .agents/skills/apm-workflow/SKILL.md: sha256:e0d74b6166c810e57869ac349e400b73fb6502e46c3b979b9489bd3305b7faa0 .agents/skills/apm-workflow/agents/openai.yaml: sha256:f3c083196472ec9253886b369202ddeb8eb2534fd2da9799798bae2eb33b2e55 - .agents/skills/apm-workflow/references/apm-bootstrap.json: sha256:ae425dc00b981c195e0664ad77b9fed8c4667a45efcdadd382e79fb572d7fc22 + .agents/skills/apm-workflow/references/apm-bootstrap.json: sha256:0b193b2dc7be40069ae30d5efa8f3c1f229cdef044487264e8554f102a6b26a0 + .agents/skills/apm-workflow/references/bootstrap-refresh.md: sha256:e12c66f02ca6b3b56d5679fe2f28b9c23d4ce060cf7f448204da40d7508c0e32 + .agents/skills/apm-workflow/references/cli-acquisition.md: sha256:9274eeaab5ea5d1c6e9ec015ee36a4dcc2dc3e8f2be8bcad3f5cdac5ebde3dd4 + .agents/skills/apm-workflow/references/cli-selection.md: sha256:fb363afd421212d2e19d7e7125e0a49224fbfc329f9f493ad175d055fafe06e6 + .agents/skills/apm-workflow/references/collection-maintenance.md: sha256:e859dd72ea48ea0cad3108e3ca6ac6a4f6b15bb8af93b0e7f86b40c6a24fcb72 + .agents/skills/apm-workflow/references/completion.md: sha256:83ca37b3a24f5d57b374aa5d4d0ede40c9b7879ddb30ee88b1cb3a4f0dce513e + .agents/skills/apm-workflow/references/dependency-deployment.md: sha256:e43aa1dbc4b786d016ff38f9af5c92341950104c1a0bd0fe9a8f52c29a2e1b65 + .agents/skills/apm-workflow/references/dependency-updates.md: sha256:1fbed28f1c6199da029394e26704e0f812b74ffc9a33e2acbf5b227ee1d2d3c9 + .agents/skills/apm-workflow/references/upstream-sources.md: sha256:7507a8ce63d30c2749d1c4f5ba96c6b7d5be829df7d5f542455426499f84e1fd .agents/skills/apm-workflow/scripts/propose_bootstrap_update.py: sha256:878feade115442de0c9c0f23856b1fca0b79cad117a1c1de75467cfd5ac9013c .agents/skills/apm-workflow/scripts/propose_bootstrap_update.py.lock: sha256:76042d39ffdbb675188966b4fc41d312b0ec9374a7aa438d4f5e919adcf04c07 .agents/skills/changelog-workflow/README.md: sha256:7ef8167d26522d95f62b9f11d752487d62b6bfdae05850315189fbe2a19fed83 .agents/skills/changelog-workflow/SKILL.md: sha256:8d9de8e0e3c31c4a2c176a0d14e3f1a45daf3db364ede7dd86983c8c3f571f54 .agents/skills/changelog-workflow/agents/openai.yaml: sha256:6264e6dbd0433ab63370e15033ecb94da8dd131c4edcb1d3f2b9abdeb4f680f1 .agents/skills/code-quality-check/README.md: sha256:b2cfd8bf9c3c7bd16cf86718877fa025396d15a380de88045122c4d162682cc2 - .agents/skills/code-quality-check/SKILL.md: sha256:30d64d4b25d9be96567f3e5f7106609e1a4d9a32b3c3d520d4b3aca459631990 + .agents/skills/code-quality-check/SKILL.md: sha256:7415164c33885676d4b579db0560287762a5c2e0e25001dac0e848af1b6c10b0 .agents/skills/code-quality-check/agents/openai.yaml: sha256:69a8a75579e3b47dc69a176417b97441adf81bc54984d3f6bc114e47a68bc9b3 + .agents/skills/code-quality-check/references/avoiding-overengineering.md: sha256:f35ad2036a18151dc9dfef8a334989d2b88439478505cd5b047f0621dd613098 .agents/skills/commit-message-quality-check/README.md: sha256:c23949080d05f47cce728410ca3190225397aa41ac2015c6f02ee478ec412a24 - .agents/skills/commit-message-quality-check/SKILL.md: sha256:db272bb7467bcb6a6c3d837dec60a34f7081c135fcd40a9e00cf4a84e29ffabe + .agents/skills/commit-message-quality-check/SKILL.md: sha256:cbe89b115e778b2417abf5fb15d98b2d1403c3ea0c99bf5ce9a0a65bef0cd6d7 .agents/skills/commit-message-quality-check/agents/openai.yaml: sha256:faffd948a0989dcfc87dcd3b0580c4a7003d01ef436e66dab9f280df57de652c .agents/skills/docker-quality-check/README.md: sha256:912a73d3de06babc6eed1ecdaf275139ae465797083dc5427affb54d00c57bf0 .agents/skills/docker-quality-check/SKILL.md: sha256:85b24dafab008013de4edada0ab17defd1bd06ac879b3a0342648620b4e56cce @@ -112,27 +131,29 @@ dependencies: .agents/skills/docker-quality-check/references/registry-image-deletion.md: sha256:a02688f52be5fccef96a2f25a70451eb8c579a46aa21ce27ee57ebc3a3f71a7e .agents/skills/docker-quality-check/references/runtime-isolation-validation.md: sha256:7eaadd59b0db06e156e52013e1beafaef8eb04ea47954a8db6e577a224cd8e02 .agents/skills/git-worktree-workflow/README.md: sha256:fa6483b5919a01b84fa0d6ffcbaae20b84ed3807e18029e8807e61b0ee4f9de9 - .agents/skills/git-worktree-workflow/SKILL.md: sha256:67e2474b9878cc6cb209ae30b19c233f65969abe5b5d543f0c9a16e46f1d40d2 + .agents/skills/git-worktree-workflow/SKILL.md: sha256:cb69640580964636669f5f60c0d97a4f1e6c7b20d3466695ffa35ab2efcca450 .agents/skills/git-worktree-workflow/agents/openai.yaml: sha256:3eb9da73e7a041e77d82f0d5c3a8c67e914575cff8651b71d077db30fe3da99a .agents/skills/github-workflow/README.md: sha256:5d23c667c4b4aedfdad8110690ac0a08cb9f91b91b6e75b8769a12f497324bae - .agents/skills/github-workflow/SKILL.md: sha256:fff81418d111a2fe43bdb0a438600d728fba867c129b5d690cf50d4326b840f0 + .agents/skills/github-workflow/SKILL.md: sha256:e48d27f4c7f0fa5ec0efe944994fcad8eb2083e586bfbf720dda19bb3941acc1 .agents/skills/github-workflow/agents/openai.yaml: sha256:1f792d6b510760ad131a4b4d077dfc84da1cdee4c30efc8e47d3e92aac939e6c .agents/skills/github-workflow/references/fallback-pr-body.md: sha256:b98239e7d4cdddd8e267ab155f4e4c38fcc514526d9a32f13fcd5b21a1c07eb2 + .agents/skills/github-workflow/references/remote-commit.md: sha256:0bd592cc388a3e78279a02ee3ba8b78f3eeda3c5591e315b9f9408657c42c5ec .agents/skills/github-workflow/references/repository-settings.md: sha256:4a7ac9d7281c203d84f4ba7ddad6940218194ed3e365ab1c3ff1d1b1519f87e6 .agents/skills/github-workflow/scripts/check_llm_disclosure.py: sha256:bc9c5cbd8efa77095eac42e53da714ed8dff86fa3b0e7870fc3e7eca1ca36e20 .agents/skills/gitignore-workflow/README.md: sha256:0de188ebcdd40ea1aec701410e1c2182049b66bc4ec4d83a3bf55685b4267d47 .agents/skills/gitignore-workflow/SKILL.md: sha256:2ef38f42e418c10e0ba7632e3ba37614df97044dfa8847ad1338e6c4c896c089 .agents/skills/gitignore-workflow/agents/openai.yaml: sha256:f6a9b176003028588ff4c1d9ee4e23c625892d00b65086bf4b6b26a3f896030d .agents/skills/prose-quality-check/README.md: sha256:8e4d9f8f8fdfba1cf7fe71fa88cac6baffa0d3c7616f744c0e3b1add102be5e7 - .agents/skills/prose-quality-check/SKILL.md: sha256:f2e0eca08cdbfb7efe9eadcf352b3ae874c8e8d48c753d0ea27ed3eda135bcff + .agents/skills/prose-quality-check/SKILL.md: sha256:689e54128f766928a5594529c7f7fab4372fff4de42975f98a8eb7698acbceb1 .agents/skills/prose-quality-check/agents/openai.yaml: sha256:b83e0a5d151e6e20df6f7d97f268955c6abfd105d53820f6baad0de8403fc062 .agents/skills/prose-quality-check/assets/markdownlint-cli2.yaml: sha256:1044e29915fe15e9083f808d1170c84cfc0b848123c0da435cabb9512d39c203 + .agents/skills/prose-quality-check/references/handoff-notes.md: sha256:15470b6bb5ad5ad5e618392d7ae1a3939c0c4e63b2f630196f3d4b6ca56c39f7 .agents/skills/python-quality-check/README.md: sha256:20a23003a24a8caf2f03dd5a06bed99c81cf93ab53fe5a196c6a67ab59c53b0e - .agents/skills/python-quality-check/SKILL.md: sha256:bb6e4e3ad15fb89edf77643af0c7ede8a647d6d68a7d71d57da6acad5517206c + .agents/skills/python-quality-check/SKILL.md: sha256:f32a4b7f394e73c3d7ed56cd8c525cc679010573d8586776dbb54b1aff1c6491 .agents/skills/python-quality-check/agents/openai.yaml: sha256:f0b4ad3807e177becec02271314fb32c1ec8d5a7682725ddd4a611a5381084d1 .agents/skills/python-quality-check/assets/github/actions/setup-python-locked/action.yml: sha256:a78b34f3bfdd20cd2624bb093f0a927ea6c2edddc4301a2d60ec8a86e0fa2589 .agents/skills/python-quality-check/assets/github/actions/setup-python-locked/resolve-python-contract.sh: sha256:71e09fff0baf2630e766c8dd32eef32d0735dbc11b4f25fe335cca10f99548e8 - .agents/skills/python-quality-check/references/ci-and-distribution.md: sha256:e52aaf46c28816d6f6262a5421dba8de9f906d2b606987bedcda840d2e687281 + .agents/skills/python-quality-check/references/ci-and-distribution.md: sha256:bfd313b057b0a93518f641bbc1b0f0fa8ada41f06fbb075c8315d00225684784 .agents/skills/python-quality-check/references/tooling-and-testing.md: sha256:dd55defe261fd16e88e9ef4acf2487ec4c05cca160c153db1a0e6746b3e39b44 .agents/skills/python-quality-check/scripts/check_project.py: sha256:8175b500198399a2ce8b79b4fc8d1902f791d163a0d6dfd35b5ce56b41c5ccc5 .agents/skills/python-quality-check/scripts/check_project.py.lock: sha256:76042d39ffdbb675188966b4fc41d312b0ec9374a7aa438d4f5e919adcf04c07 @@ -144,12 +165,12 @@ dependencies: .agents/skills/release-note-workflow/SKILL.md: sha256:518296cb00d1ef181785ea8abd0150b9704b5cdd05a48fc0390284c548ef421c .agents/skills/release-note-workflow/agents/openai.yaml: sha256:30cfe7d4520783cfc8c72f5f81cc3e7a5708a5827e691f0003a665d89558fda0 .agents/skills/security-check/README.md: sha256:d321689b998388180ac852fdb6374ab3b79bec508a53d00461a9db79fb246d2e - .agents/skills/security-check/SKILL.md: sha256:658368991ef988551e192551e7e539a6801f74d587b95039bbc9b36c6ab75345 + .agents/skills/security-check/SKILL.md: sha256:cdc808990ce5eece96a6cb439a389f6611ba8c34ae954789df4ed8936732f63e .agents/skills/security-check/agents/openai.yaml: sha256:b1021ca2df7466813d0a376fc8bdff83603f568b02ef712e236fb2cfeef377c0 .agents/skills/security-check/references/artifact-inspection.md: sha256:9842555f4789e77e6cf3d22b000116497207ecf6fa5587f2b1fe0dc20e7dffda .agents/skills/security-check/references/distributed-software-licensing.md: sha256:dce7c9fbfe665eb875388ab732b63b0226a5fd4592b12a62c42b6d1372c0d025 - .agents/skills/security-check/references/external-code-execution.md: sha256:87ca817baa02ef6b955e5878f0cd79c875abdb0be6e0177cfce158968e628bc3 - content_hash: sha256:23beea8cf3eed1e7200e40c653c069cfbd40b717bd0cd34311c2dd5bae882e36 + .agents/skills/security-check/references/external-code-execution.md: sha256:03d666ef02095acc8b6d5e03d1bb8378f8b38ce01c6f006d2f7934fcfb6bfe4b + content_hash: sha256:5ffd3a54ff67dcb1007f91ce6d29ad72f3859245e41655b26ceb5ec60231e691 skill_subset: - apm-workflow - changelog-workflow @@ -191,7 +212,7 @@ deployments: owners: - aoirint/skills active_owner: aoirint/skills - content_hash: sha256:f4d7a88ce5919909fb68bc77d6c95723ce8f2d9bffe309aa0e25abef4a8997fa + content_hash: sha256:e0d74b6166c810e57869ac349e400b73fb6502e46c3b979b9489bd3305b7faa0 - kind: project-relative target: codex value: .agents/skills/apm-workflow/agents/openai.yaml @@ -209,7 +230,79 @@ deployments: owners: - aoirint/skills active_owner: aoirint/skills - content_hash: sha256:ae425dc00b981c195e0664ad77b9fed8c4667a45efcdadd382e79fb572d7fc22 + content_hash: sha256:0b193b2dc7be40069ae30d5efa8f3c1f229cdef044487264e8554f102a6b26a0 +- kind: project-relative + target: codex + value: .agents/skills/apm-workflow/references/bootstrap-refresh.md + runtime: null + scope: project + owners: + - aoirint/skills + active_owner: aoirint/skills + content_hash: sha256:e12c66f02ca6b3b56d5679fe2f28b9c23d4ce060cf7f448204da40d7508c0e32 +- kind: project-relative + target: codex + value: .agents/skills/apm-workflow/references/cli-acquisition.md + runtime: null + scope: project + owners: + - aoirint/skills + active_owner: aoirint/skills + content_hash: sha256:9274eeaab5ea5d1c6e9ec015ee36a4dcc2dc3e8f2be8bcad3f5cdac5ebde3dd4 +- kind: project-relative + target: codex + value: .agents/skills/apm-workflow/references/cli-selection.md + runtime: null + scope: project + owners: + - aoirint/skills + active_owner: aoirint/skills + content_hash: sha256:fb363afd421212d2e19d7e7125e0a49224fbfc329f9f493ad175d055fafe06e6 +- kind: project-relative + target: codex + value: .agents/skills/apm-workflow/references/collection-maintenance.md + runtime: null + scope: project + owners: + - aoirint/skills + active_owner: aoirint/skills + content_hash: sha256:e859dd72ea48ea0cad3108e3ca6ac6a4f6b15bb8af93b0e7f86b40c6a24fcb72 +- kind: project-relative + target: codex + value: .agents/skills/apm-workflow/references/completion.md + runtime: null + scope: project + owners: + - aoirint/skills + active_owner: aoirint/skills + content_hash: sha256:83ca37b3a24f5d57b374aa5d4d0ede40c9b7879ddb30ee88b1cb3a4f0dce513e +- kind: project-relative + target: codex + value: .agents/skills/apm-workflow/references/dependency-deployment.md + runtime: null + scope: project + owners: + - aoirint/skills + active_owner: aoirint/skills + content_hash: sha256:e43aa1dbc4b786d016ff38f9af5c92341950104c1a0bd0fe9a8f52c29a2e1b65 +- kind: project-relative + target: codex + value: .agents/skills/apm-workflow/references/dependency-updates.md + runtime: null + scope: project + owners: + - aoirint/skills + active_owner: aoirint/skills + content_hash: sha256:1fbed28f1c6199da029394e26704e0f812b74ffc9a33e2acbf5b227ee1d2d3c9 +- kind: project-relative + target: codex + value: .agents/skills/apm-workflow/references/upstream-sources.md + runtime: null + scope: project + owners: + - aoirint/skills + active_owner: aoirint/skills + content_hash: sha256:7507a8ce63d30c2749d1c4f5ba96c6b7d5be829df7d5f542455426499f84e1fd - kind: project-relative target: codex value: .agents/skills/apm-workflow/scripts/propose_bootstrap_update.py @@ -290,7 +383,7 @@ deployments: owners: - aoirint/skills active_owner: aoirint/skills - content_hash: sha256:30d64d4b25d9be96567f3e5f7106609e1a4d9a32b3c3d520d4b3aca459631990 + content_hash: sha256:7415164c33885676d4b579db0560287762a5c2e0e25001dac0e848af1b6c10b0 - kind: project-relative target: codex value: .agents/skills/code-quality-check/agents/openai.yaml @@ -300,6 +393,15 @@ deployments: - aoirint/skills active_owner: aoirint/skills content_hash: sha256:69a8a75579e3b47dc69a176417b97441adf81bc54984d3f6bc114e47a68bc9b3 +- kind: project-relative + target: codex + value: .agents/skills/code-quality-check/references/avoiding-overengineering.md + runtime: null + scope: project + owners: + - aoirint/skills + active_owner: aoirint/skills + content_hash: sha256:f35ad2036a18151dc9dfef8a334989d2b88439478505cd5b047f0621dd613098 - kind: project-relative target: codex value: .agents/skills/commit-message-quality-check @@ -326,7 +428,7 @@ deployments: owners: - aoirint/skills active_owner: aoirint/skills - content_hash: sha256:db272bb7467bcb6a6c3d837dec60a34f7081c135fcd40a9e00cf4a84e29ffabe + content_hash: sha256:cbe89b115e778b2417abf5fb15d98b2d1403c3ea0c99bf5ce9a0a65bef0cd6d7 - kind: project-relative target: codex value: .agents/skills/commit-message-quality-check/agents/openai.yaml @@ -461,7 +563,7 @@ deployments: owners: - aoirint/skills active_owner: aoirint/skills - content_hash: sha256:67e2474b9878cc6cb209ae30b19c233f65969abe5b5d543f0c9a16e46f1d40d2 + content_hash: sha256:cb69640580964636669f5f60c0d97a4f1e6c7b20d3466695ffa35ab2efcca450 - kind: project-relative target: codex value: .agents/skills/git-worktree-workflow/agents/openai.yaml @@ -497,7 +599,7 @@ deployments: owners: - aoirint/skills active_owner: aoirint/skills - content_hash: sha256:fff81418d111a2fe43bdb0a438600d728fba867c129b5d690cf50d4326b840f0 + content_hash: sha256:e48d27f4c7f0fa5ec0efe944994fcad8eb2083e586bfbf720dda19bb3941acc1 - kind: project-relative target: codex value: .agents/skills/github-workflow/agents/openai.yaml @@ -516,6 +618,15 @@ deployments: - aoirint/skills active_owner: aoirint/skills content_hash: sha256:b98239e7d4cdddd8e267ab155f4e4c38fcc514526d9a32f13fcd5b21a1c07eb2 +- kind: project-relative + target: codex + value: .agents/skills/github-workflow/references/remote-commit.md + runtime: null + scope: project + owners: + - aoirint/skills + active_owner: aoirint/skills + content_hash: sha256:0bd592cc388a3e78279a02ee3ba8b78f3eeda3c5591e315b9f9408657c42c5ec - kind: project-relative target: codex value: .agents/skills/github-workflow/references/repository-settings.md @@ -596,7 +707,7 @@ deployments: owners: - aoirint/skills active_owner: aoirint/skills - content_hash: sha256:f2e0eca08cdbfb7efe9eadcf352b3ae874c8e8d48c753d0ea27ed3eda135bcff + content_hash: sha256:689e54128f766928a5594529c7f7fab4372fff4de42975f98a8eb7698acbceb1 - kind: project-relative target: codex value: .agents/skills/prose-quality-check/agents/openai.yaml @@ -615,6 +726,15 @@ deployments: - aoirint/skills active_owner: aoirint/skills content_hash: sha256:1044e29915fe15e9083f808d1170c84cfc0b848123c0da435cabb9512d39c203 +- kind: project-relative + target: codex + value: .agents/skills/prose-quality-check/references/handoff-notes.md + runtime: null + scope: project + owners: + - aoirint/skills + active_owner: aoirint/skills + content_hash: sha256:15470b6bb5ad5ad5e618392d7ae1a3939c0c4e63b2f630196f3d4b6ca56c39f7 - kind: project-relative target: codex value: .agents/skills/python-quality-check @@ -641,7 +761,7 @@ deployments: owners: - aoirint/skills active_owner: aoirint/skills - content_hash: sha256:bb6e4e3ad15fb89edf77643af0c7ede8a647d6d68a7d71d57da6acad5517206c + content_hash: sha256:f32a4b7f394e73c3d7ed56cd8c525cc679010573d8586776dbb54b1aff1c6491 - kind: project-relative target: codex value: .agents/skills/python-quality-check/agents/openai.yaml @@ -677,7 +797,7 @@ deployments: owners: - aoirint/skills active_owner: aoirint/skills - content_hash: sha256:e52aaf46c28816d6f6262a5421dba8de9f906d2b606987bedcda840d2e687281 + content_hash: sha256:bfd313b057b0a93518f641bbc1b0f0fa8ada41f06fbb075c8315d00225684784 - kind: project-relative target: codex value: .agents/skills/python-quality-check/references/tooling-and-testing.md @@ -803,7 +923,7 @@ deployments: owners: - aoirint/skills active_owner: aoirint/skills - content_hash: sha256:658368991ef988551e192551e7e539a6801f74d587b95039bbc9b36c6ab75345 + content_hash: sha256:cdc808990ce5eece96a6cb439a389f6611ba8c34ae954789df4ed8936732f63e - kind: project-relative target: codex value: .agents/skills/security-check/agents/openai.yaml @@ -839,4 +959,4 @@ deployments: owners: - aoirint/skills active_owner: aoirint/skills - content_hash: sha256:87ca817baa02ef6b955e5878f0cd79c875abdb0be6e0177cfce158968e628bc3 + content_hash: sha256:03d666ef02095acc8b6d5e03d1bb8378f8b38ce01c6f006d2f7934fcfb6bfe4b diff --git a/apm.yml b/apm.yml index 75e086d..991f03b 100644 --- a/apm.yml +++ b/apm.yml @@ -8,7 +8,7 @@ targets: dependencies: apm: - git: aoirint/skills - ref: f1c9dbd447dd0a446da62267994b3243596990b2 + ref: 22fe4f84018358059adcf7709cb9df28d1260fd8 skills: - apm-workflow - changelog-workflow