chore(skills): deploy reviewed source with APM 0.34.0

.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"
     }
   ]
 }

.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 <apm-workflow-skill>/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 <candidate>`. 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 <candidate>`. 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.

.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.

.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.

.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.