feat: rename apm.lock to apm.lock.yaml for IDE syntax highlighting

CHANGELOG.md

@@ -8,6 +8,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- Lockfile renamed from `apm.lock` to `apm.lock.yaml` for IDE syntax highlighting; existing `apm.lock` files are automatically migrated to `apm.lock.yaml` on the next `apm install` (#280)
+
 ## [0.7.8] - 2026-03-13
 
 ### Added

docs/src/content/docs/enterprise/adoption-playbook.md

@@ -40,7 +40,7 @@ Confirm these prerequisites before kicking off Phase 1:
    ```
 
 5. Run `apm install` to deploy files.
-6. Commit `apm.yml` and `apm.lock` to the repository.
+6. Commit `apm.yml` and `apm.lock.yaml` to the repository.
 
 ### Verification
 
@@ -61,7 +61,7 @@ single command.
 ### What to Watch
 
 - Installation friction (missing runtimes, network issues).
-- Unexpected file placement -- review `apm.lock` to confirm paths.
+- Unexpected file placement -- review `apm.lock.yaml` to confirm paths.
 - Authentication errors when pulling private packages.
 
 ---
@@ -98,7 +98,7 @@ automatically.
 
 ### What to Watch
 
-- Version pinning: confirm that `apm.lock` captures the exact version
+- Version pinning: confirm that `apm.lock.yaml` captures the exact version
   installed.
 - File collisions: if the shared package deploys a file that already exists,
   decide whether to force-overwrite or skip.
@@ -129,7 +129,7 @@ reach production.
    ```
 
 2. Make the audit step a **required status check** on pull requests.
-3. Ensure `apm.lock` is committed. Any version drift will cause the audit
+3. Ensure `apm.lock.yaml` is committed. Any version drift will cause the audit
    to fail, surfacing the problem before merge.
 
 ### Success Metric
@@ -229,7 +229,7 @@ application. Maintenance cost is limited to updating package versions in
 
 ### "What if we stop using it?"
 
-Delete `apm.yml` and `apm.lock`. The native configuration files APM
+Delete `apm.yml` and `apm.lock.yaml`. The native configuration files APM
 deployed remain in place and continue to work exactly as they did before.
 There is no lock-in.
 
@@ -246,7 +246,7 @@ go back to manual configuration.
 
 At any phase, you can reverse course:
 
-1. Remove `apm.yml` and `apm.lock` from the repository.
+1. Remove `apm.yml` and `apm.lock.yaml` from the repository.
 2. The configuration files APM deployed remain on disk and continue to
    function. Your tools read native files, not APM-specific formats.
 3. Optionally, remove APM from CI steps.

docs/src/content/docs/enterprise/governance.md

@@ -23,13 +23,13 @@ APM addresses these by treating agent configuration as auditable infrastructure,
 Agent governance in APM follows a four-stage pipeline:
 
 ```
-apm.yml (declare) -> apm.lock (pin) -> apm audit (verify) -> CI gate (enforce)
+apm.yml (declare) -> apm.lock.yaml (pin) -> apm audit (verify) -> CI gate (enforce)
 ```
 
 | Stage | Purpose | Artifact |
 |-------|---------|----------|
 | **Declare** | Define dependencies and their sources | `apm.yml` |
-| **Pin** | Resolve every dependency to an exact commit | `apm.lock` |
+| **Pin** | Resolve every dependency to an exact commit | `apm.lock.yaml` |
 | **Verify** | Confirm on-disk state matches the lock file | `apm audit` output |
 | **Enforce** | Block merges when verification fails | Required status check |
 
@@ -39,7 +39,7 @@ Each stage builds on the previous one. The lock file provides the audit trail, t
 
 ## Lock file as audit trail
 
-The `apm.lock` file is the single source of truth for what agent configuration is deployed. Every dependency is pinned to an exact commit SHA, making the lock file a complete, point-in-time record of agent state.
+The `apm.lock.yaml` file is the single source of truth for what agent configuration is deployed. Every dependency is pinned to an exact commit SHA, making the lock file a complete, point-in-time record of agent state.
 
 ### What the lock file captures
 
@@ -77,23 +77,23 @@ Key fields for governance:
 
 ### Using git history for auditing
 
-Because `apm.lock` is a committed file, standard git operations answer governance questions directly:
+Because `apm.lock.yaml` is a committed file, standard git operations answer governance questions directly:
 
 ```bash
 # Full history of every agent configuration change
-git log --oneline apm.lock
+git log --oneline apm.lock.yaml
 
 # Who changed agent config, and when
-git log --format="%h %ai %an: %s" apm.lock
+git log --format="%h %ai %an: %s" apm.lock.yaml
 
 # What was the exact agent configuration at release v4.2.1
-git show v4.2.1:apm.lock
+git show v4.2.1:apm.lock.yaml
 
 # Diff agent config between two releases
-git diff v4.1.0..v4.2.1 -- apm.lock
+git diff v4.1.0..v4.2.1 -- apm.lock.yaml
 
 # Find the commit that introduced a specific dependency
-git log -p --all -S 'contoso/agent-standards' -- apm.lock
+git log -p --all -S 'contoso/agent-standards' -- apm.lock.yaml
 ```
 
 No additional tooling is required. The lock file turns git into an agent configuration audit log.
@@ -122,7 +122,7 @@ on:
   pull_request:
     paths:
       - 'apm.yml'
-      - 'apm.lock'
+      - 'apm.lock.yaml'
       - '.github/agents/**'
       - '.github/skills/**'
       - '.copilot/agents/**'
@@ -217,7 +217,7 @@ Combine with GitHub's CODEOWNERS to require security team approval for changes t
 ```
 # CODEOWNERS
 apm.yml    @contoso/platform-engineering
-apm.lock   @contoso/platform-engineering
+apm.lock.yaml   @contoso/platform-engineering
 ```
 
 ### Version pinning policy
@@ -303,9 +303,9 @@ For detailed setup instructions, see the [CI/CD integration guide](../../integra
 
 SOC 2 audits require evidence that configuration changes are authorized and traceable. APM's lock file provides this:
 
-- **Change authorization.** Every `apm.lock` change goes through a PR, requiring review and approval.
-- **Change history.** `git log apm.lock` produces a complete, tamper-evident history of every agent configuration change with author, timestamp, and diff.
-- **Point-in-time state.** `git show <tag>:apm.lock` reconstructs the exact agent configuration active at any release.
+- **Change authorization.** Every `apm.lock.yaml` change goes through a PR, requiring review and approval.
+- **Change history.** `git log apm.lock.yaml` produces a complete, tamper-evident history of every agent configuration change with author, timestamp, and diff.
+- **Point-in-time state.** `git show <tag>:apm.lock.yaml` reconstructs the exact agent configuration active at any release.
 
 Link auditors directly to the lock file history in your repository. No separate audit system is needed.
 
@@ -315,13 +315,13 @@ When a security review requires understanding what instructions agents were foll
 
 ```bash
 # What agent configuration was active at the time of the incident
-git show <commit-at-incident-time>:apm.lock
+git show <commit-at-incident-time>:apm.lock.yaml
 
 # What files were deployed by a specific package
-grep -A 10 'contoso/agent-standards' apm.lock
+grep -A 10 'contoso/agent-standards' apm.lock.yaml
 
 # Full diff of agent config changes in the last 90 days
-git log --since="90 days ago" -p -- apm.lock
+git log --since="90 days ago" -p -- apm.lock.yaml
 ```
 
 The lock file answers "what was running" without requiring access to the original package repositories. The `resolved_commit` field points to the exact source code that was deployed.
@@ -331,9 +331,9 @@ The lock file answers "what was running" without requiring access to the origina
 APM enforces change management by design:
 
 1. **Declaration.** Changes start in `apm.yml`, which is a committed, reviewable file.
-2. **Resolution.** `apm install` resolves declarations to exact commits in `apm.lock`.
+2. **Resolution.** `apm install` resolves declarations to exact commits in `apm.lock.yaml`.
 3. **Review.** Both files are included in the PR diff for peer review.
-4. **Verification.** `apm audit --ci` confirms consistency before merge (planned — currently achieved through PR review of `apm.lock` diffs).
+4. **Verification.** `apm audit --ci` confirms consistency before merge (planned — currently achieved through PR review of `apm.lock.yaml` diffs).
 5. **Traceability.** Git history provides a permanent record of who changed what and when.
 
 No agent configuration change can reach a protected branch without passing through this pipeline.
@@ -344,8 +344,8 @@ No agent configuration change can reach a protected branch without passing throu
 
 | Capability | Mechanism | Status |
 |---|---|---|
-| Dependency pinning | `apm.lock` with exact commit SHAs | Available |
-| Audit trail | Git history of `apm.lock` | Available |
+| Dependency pinning | `apm.lock.yaml` with exact commit SHAs | Available |
+| Audit trail | Git history of `apm.lock.yaml` | Available |
 | Constitution injection | `memory/constitution.md` with hash verification | Available |
 | Transitive MCP trust control | `--trust-transitive-mcp` flag | Available |
 | CI enforcement | `apm audit --ci` as required status check | Planned |

docs/src/content/docs/enterprise/making-the-case.md

@@ -23,11 +23,11 @@ An internal advocacy toolkit for APM. Each section is self-contained and designe
 
 - **Developer productivity.** Eliminate manual setup of AI agent configurations. New developers run `apm install` and get a working environment in seconds instead of following multi-step setup guides.
 - **Consistency across teams.** A single shared package ensures every team uses the same coding standards, prompts, and tool configurations. Updates propagate with a version bump, not a Slack message.
-- **Audit trail for compliance.** Every change to agent configuration is tracked through `apm.lock` and git history. You can answer "what changed, when, and why" for any audit.
+- **Audit trail for compliance.** Every change to agent configuration is tracked through `apm.lock.yaml` and git history. You can answer "what changed, when, and why" for any audit.
 
 ### For Security and Compliance
 
-- **Lock file integrity.** `apm.lock` pins exact versions and commit SHAs for every dependency. No silent updates, no supply chain surprises.
+- **Lock file integrity.** `apm.lock.yaml` pins exact versions and commit SHAs for every dependency. No silent updates, no supply chain surprises.
 - **Dependency provenance.** Every package resolves to a specific git repository and commit. The full dependency tree is inspectable before installation.
 - **No code execution, no runtime.** APM is a dev-time tool only. It copies configuration files — it does not execute code, run background processes, or modify your application at runtime.
 - **Full audit trail.** All configuration changes are committed to git. Compliance teams can review agent setup changes through standard code review processes.
@@ -76,7 +76,7 @@ Installation is a single binary with no system dependencies. Updates are a binar
 
 APM outputs native configuration formats: `.github/instructions/`, `.github/prompts/`, `.claude/`, `AGENTS.md`. These are standard files that your AI tools read directly.
 
-If you stop using APM, delete `apm.yml` and `apm.lock`. Your configuration files remain and continue to work. Zero lock-in by design.
+If you stop using APM, delete `apm.yml` and `apm.lock.yaml`. Your configuration files remain and continue to work. Zero lock-in by design.
 
 ### "We only use one AI tool, not multiple."
 
@@ -115,7 +115,7 @@ This is a deliberate design choice. APM adds value on top of native formats rath
 
 The following is ready to copy into an internal proposal or RFC:
 
-> We propose adopting APM (Agent Package Manager) to manage AI agent configuration across our repositories. APM is an open-source, dev-time tool that provides a declarative manifest (`apm.yml`) and lock file (`apm.lock`) for AI coding agent setup — instructions, prompts, skills, plugins, and MCP servers. It resolves dependencies, generates native configuration files for each AI platform, and produces reproducible installs from locked versions. APM has zero runtime footprint: it runs during setup and CI, outputs standard config files, and introduces no vendor lock-in. Adopting APM will eliminate manual agent setup for new developers, enforce consistent configuration across teams, and provide an auditable record of all agent configuration changes through git history. The tool is MIT-licensed, maintained under the Microsoft GitHub organization, and supports GitHub, GitLab, Bitbucket, and Azure DevOps as package sources.
+> We propose adopting APM (Agent Package Manager) to manage AI agent configuration across our repositories. APM is an open-source, dev-time tool that provides a declarative manifest (`apm.yml`) and lock file (`apm.lock.yaml`) for AI coding agent setup — instructions, prompts, skills, plugins, and MCP servers. It resolves dependencies, generates native configuration files for each AI platform, and produces reproducible installs from locked versions. APM has zero runtime footprint: it runs during setup and CI, outputs standard config files, and introduces no vendor lock-in. Adopting APM will eliminate manual agent setup for new developers, enforce consistent configuration across teams, and provide an auditable record of all agent configuration changes through git history. The tool is MIT-licensed, maintained under the Microsoft GitHub organization, and supports GitHub, GitLab, Bitbucket, and Azure DevOps as package sources.
 
 ---
 
@@ -131,7 +131,7 @@ For stakeholders familiar with existing tools, this comparison clarifies where A
 | Dependency resolution | Manual | None | Automatic, transitive |
 | CI enforcement | Custom scripts | Not available | Planned (`apm audit --ci`) |
 | Shared org standards | Wiki pages, copy-paste | Not available | Versioned packages |
-| Audit trail | Implicit via git | Varies by vendor | Explicit via `apm.lock` |
+| Audit trail | Implicit via git | Varies by vendor | Explicit via `apm.lock.yaml` |
 | Lock-in | To manual process | To specific vendor | None (native output files) |
 
 ---
@@ -172,7 +172,7 @@ With APM, setup reduces to `apm install` (under 30 seconds). Standards updates r
 | New developer onboarding | Follow a setup doc, troubleshoot differences | `git clone && apm install` |
 | CI reproducibility | "Worked locally" debugging | Locked versions, identical environments |
 | Adding a new MCP server to all repos | Manual config in each repo, inconsistent rollout | Add to shared package, teams pull on next install |
-| Auditing agent configuration | Grep across repos, compare manually | Review `apm.lock` diffs in git history |
+| Auditing agent configuration | Grep across repos, compare manually | Review `apm.lock.yaml` diffs in git history |
 
 ---
 

docs/src/content/docs/enterprise/security.md

@@ -14,7 +14,7 @@ APM is a build-time dependency manager for AI prompts and configuration. It perf
 1. **Resolves git repositories** — clones or sparse-checks-out packages from GitHub or Azure DevOps.
 2. **Deploys static files** — copies markdown, JSON, and YAML files into project directories (`.github/`, `.claude/`).
 3. **Generates compiled output** — produces `AGENTS.md`, `CLAUDE.md`, and similar files from templates and prompts.
-4. **Records a lock file** — writes `apm.lock` with exact commit SHAs for every resolved dependency.
+4. **Records a lock file** — writes `apm.lock.yaml` with exact commit SHAs for every resolved dependency.
 
 ## What APM does NOT do
 
@@ -33,7 +33,7 @@ APM resolves dependencies directly from git repositories. There is no intermedia
 
 ### Exact commit pinning
 
-Every resolved dependency is recorded in `apm.lock` with its full commit SHA:
+Every resolved dependency is recorded in `apm.lock.yaml` with its full commit SHA:
 
 ```yaml
 lockfile_version: "1"
@@ -55,7 +55,7 @@ APM does not use a package registry. Dependencies are specified as git repositor
 
 ### Reproducible installs
 
-Given the same `apm.lock`, `apm install` produces identical file output regardless of when or where it runs. The lock file is the single source of truth for dependency state.
+Given the same `apm.lock.yaml`, `apm install` produces identical file output regardless of when or where it runs. The lock file is the single source of truth for dependency state.
 
 ## Path security
 
@@ -133,7 +133,7 @@ APM authenticates to git hosts using personal access tokens (PATs) read from env
 
 ### Security properties
 
-- **Never stored in files.** Tokens are read from the environment at runtime. They are never written to `apm.yaml`, `apm.lock`, or any generated file.
+- **Never stored in files.** Tokens are read from the environment at runtime. They are never written to `apm.yaml`, `apm.lock.yaml`, or any generated file.
 - **Never logged.** Token values are not included in console output, error messages, or debug logs.
 - **Scoped to their git host.** A GitHub token is only sent to GitHub. An Azure DevOps token is only sent to Azure DevOps. Tokens are never transmitted to any other endpoint.
 
@@ -157,17 +157,17 @@ APM's design eliminates several supply chain attack vectors common in traditiona
 
 ### Auditing dependency changes
 
-Because `apm.lock` is a plain YAML file checked into version control, standard git tooling provides a full audit trail:
+Because `apm.lock.yaml` is a plain YAML file checked into version control, standard git tooling provides a full audit trail:
 
 ```bash
 # View all dependency changes over time
-git log --oneline apm.lock
+git log --oneline apm.lock.yaml
 
 # See exactly what changed in a specific commit
-git diff HEAD~1 -- apm.lock
+git diff HEAD~1 -- apm.lock.yaml
 
 # Find when a specific dependency was added
-git log --all -p -- apm.lock | grep -A5 "owner/repo"
+git log --all -p -- apm.lock.yaml | grep -A5 "owner/repo"
 ```
 
 ### Pinning and updates
@@ -196,7 +196,7 @@ Not by default. Transitive MCP server declarations are blocked unless you explic
 
 ### How do I audit what APM installed?
 
-The `apm.lock` file records every dependency (with exact commit SHA) and every file deployed. It is a plain YAML file suitable for automated policy checks, diff review, and compliance tooling.
+The `apm.lock.yaml` file records every dependency (with exact commit SHA) and every file deployed. It is a plain YAML file suitable for automated policy checks, diff review, and compliance tooling.
 
 ### Is the APM binary signed?