Fix .gitattributes writer: quote paths with spaces, dedupe per-batch syncs, deterministic ordering

README.md

@@ -107,22 +107,27 @@ request with a clear description of what changed and why.
 ### 4. Compile to a Pipeline
 
 ```bash
-# Simple form — generates the .yml alongside the source .md
+# Simple form — generates a `.lock.yml` alongside the source `.md`
 ado-aw compile dependency-updater.md
 
 # Or specify a custom output location
-ado-aw compile dependency-updater.md -o path/to/dependency-updater.yml
+ado-aw compile dependency-updater.md -o path/to/dependency-updater.lock.yml
 ```
 
 This generates a complete Azure DevOps pipeline YAML file. The compiler also
 copies the agent markdown body into the output tree so it's available at runtime.
 
+The compiler also writes/updates a `.gitattributes` file at the repository root
+that marks every compiled `.lock.yml` pipeline as `linguist-generated=true merge=ours`,
+so GitHub hides them from PR diffs and merge conflicts in generated YAML resolve
+to the local copy (which can then be rebuilt with `ado-aw compile`).
+
 ### 5. Verify (CI Check)
 
 Ensure pipelines stay in sync with their source:
 
 ```bash
-ado-aw check dependency-updater.yml
+ado-aw check dependency-updater.lock.yml
 ```
 
 This is useful as a CI gate — if someone edits the markdown but forgets to
@@ -134,7 +139,7 @@ recompile, the check will fail.
 
 ### Step 1: Commit both files
 
-Your repo should contain the agent source `.md` and the compiled pipeline `.yml`.
+Your repo should contain the agent source `.md` and the compiled pipeline `.lock.yml`.
 Place them wherever your team's conventions dictate — there is no required directory structure.
 
 Push both files to your Azure DevOps repository.
@@ -144,7 +149,7 @@ Push both files to your Azure DevOps repository.
 1. Go to **Pipelines → New Pipeline**
 2. Select your repository
 3. Choose **Existing Azure Pipelines YAML file**
-4. Point to the compiled `.yml` pipeline file
+4. Point to the compiled `.lock.yml` pipeline file
 5. Save (or Save & Run)
 
 ### Step 3: Set Up ARM Service Connections for Permissions

prompts/create-ado-agentic-workflow.md

@@ -489,14 +489,14 @@ When generating the agent file:
 After creating the agent file, compile it into an Azure DevOps pipeline:
 
 ```bash
-# Simple form — generates the .yml pipeline alongside the .md source
+# Simple form — generates a `.lock.yml` pipeline alongside the `.md` source
 ado-aw compile <path/to/agent.md>
 
 # Or specify a custom output location
-ado-aw compile <path/to/agent.md> -o <path/to/pipeline.yml>
+ado-aw compile <path/to/agent.md> -o <path/to/pipeline.lock.yml>
 ```
 
-This generates a `.yml` pipeline file. Both the source `.md` and generated `.yml` must be committed together.
+This generates a `.lock.yml` pipeline file. Both the source `.md` and generated `.lock.yml` must be committed together. The compiler also writes/updates a `.gitattributes` file at the repository root so compiled pipelines are marked `linguist-generated=true merge=ours`.
 
 If the `ado-aw` CLI is not installed or not available on `PATH`, guide the user to download it from:
 https://github.com/githubnext/ado-aw/releases
@@ -506,8 +506,8 @@ https://github.com/githubnext/ado-aw/releases
 ```
 Next steps:
   1. Review and customize the agent instructions in <filename>.md
-  2. Commit both the .md source and the generated .yml pipeline
-  3. Register the .yml as a pipeline in Azure DevOps
+  2. Commit both the .md source, the generated .lock.yml pipeline, and any .gitattributes changes
+  3. Register the .lock.yml as a pipeline in Azure DevOps
 ```
 
 ---
@@ -595,5 +595,5 @@ safe-outputs:
 - **Minimal permissions**: Default to no permissions; add only what the task requires.
 - **Explicit allow-lists**: Restrict MCP tools to only what the agent needs.
 - **No direct writes**: All mutations go through safe outputs — the agent cannot push code or call write APIs directly.
-- **Compile before committing**: Always compile with `ado-aw compile` and commit both the `.md` source and generated `.yml` together.
+- **Compile before committing**: Always compile with `ado-aw compile` and commit both the `.md` source and generated `.lock.yml` together.
 - **Check validation**: The compiler will error if write safe-outputs are configured without `permissions.write`.

prompts/debug-ado-agentic-workflow.md

@@ -44,7 +44,7 @@ Follow this sequence for every debugging session:
 
 3. **Check for compilation drift** — before deep-diving into runtime errors, verify the pipeline YAML is in sync with its source markdown:
    ```bash
-   ado-aw check <pipeline.yml>
+   ado-aw check <pipeline.lock.yml>
    ```
 
 4. **Apply the fix** — make the targeted change to the agent `.md` source file, then recompile:
@@ -178,17 +178,17 @@ network:
 
 **Diagnosis**:
 ```bash
-ado-aw check <pipeline.yml>
+ado-aw check <pipeline.lock.yml>
 ```
 
 If the check fails, the pipeline YAML is out of sync with the source markdown. This happens when:
 - The `.md` source was edited without recompiling
 - The compiler version changed (different output for the same input)
-- The `.yml` was manually edited
+- The `.lock.yml` was manually edited
 
 **Fix**: Recompile and commit both files together:
 ```bash
-ado-aw compile <agent.md> -o <pipeline.yml>
+ado-aw compile <agent.md> -o <pipeline.lock.yml>
 ```
 
 ---
@@ -350,7 +350,7 @@ If downloads fail:
 
 ```bash
 # Verify pipeline YAML matches its source markdown
-ado-aw check <pipeline.yml>
+ado-aw check <pipeline.lock.yml>
 
 # Recompile a single agent
 ado-aw compile <path/to/agent.md>
@@ -371,7 +371,7 @@ ado-aw configure --dry-run
 
 Use this checklist to systematically rule out common issues:
 
-- [ ] **Compilation in sync**: `ado-aw check <pipeline.yml>` passes
+- [ ] **Compilation in sync**: `ado-aw check <pipeline.lock.yml>` passes
 - [ ] **Correct stage identified**: Know which of the 3 jobs failed
 - [ ] **Network allowlist**: All required domains are in `network.allowed` or built-in
 - [ ] **MCP tools allowed**: Every tool the agent needs is in an `allowed:` list

prompts/update-ado-agentic-workflow.md

@@ -336,7 +336,7 @@ After completing an update:
 Next steps:
   1. Review the changes in <filename>.md
   2. Recompile: ado-aw compile <path/to/agent.md>
-  3. Commit both the updated .md source and regenerated .yml pipeline
+  3. Commit both the updated .md source and regenerated .lock.yml pipeline
 ```
 
 If only agent instructions were changed: