Merge pull request #102 from Azure/copilot/fix-github-issue-96

fix: align override configuration format with APIOps Toolkit

Author: petehauge

.devcontainer/devcontainer-lock.json

@@ -0,0 +1,19 @@
+{
+  "features": {
+    "ghcr.io/devcontainers/features/azure-cli:1": {
+      "version": "1.3.0",
+      "resolved": "ghcr.io/devcontainers/features/azure-cli@sha256:d98f1066c077be0fa9d115b718f458bd803e415181b4a96f82a6f5d9f77241ac",
+      "integrity": "sha256:d98f1066c077be0fa9d115b718f458bd803e415181b4a96f82a6f5d9f77241ac"
+    },
+    "ghcr.io/devcontainers/features/github-cli:1": {
+      "version": "1.1.0",
+      "resolved": "ghcr.io/devcontainers/features/github-cli@sha256:d22f50b70ed75339b4eed1ba9ecde3a1791f90e88d37936517e3bace0bbad671",
+      "integrity": "sha256:d22f50b70ed75339b4eed1ba9ecde3a1791f90e88d37936517e3bace0bbad671"
+    },
+    "ghcr.io/devcontainers/features/powershell:1": {
+      "version": "1.5.1",
+      "resolved": "ghcr.io/devcontainers/features/powershell@sha256:df7baa89598c93bfd15808641d9ec9eb03e0ccdf52e5de4cbbce9ab2d9755d18",
+      "integrity": "sha256:df7baa89598c93bfd15808641d9ec9eb03e0ccdf52e5de4cbbce9ab2d9755d18"
+    }
+  }
+}

.github/copilot-instructions.md

@@ -74,6 +74,8 @@ Always include `Closes #N` in **both** the commit message AND the PR body's "Rel
 
 **⚠️ CRITICAL:** When creating a pull request, the title and description must summarize **ALL changes in the branch**, not just the last commit.
 
+**⚠️ CRITICAL:** Once a pull request already exists, do **not** change its title or description unless the user explicitly asks you to do so.
+
 ### Before Creating Any PR
 
 1. Run `git log main..HEAD --oneline` to see ALL commits in the branch
@@ -86,6 +88,12 @@ Always include `Closes #N` in **both** the commit message AND the PR body's "Rel
    - New files added
    - Modified functionality
 
+### After a PR Already Exists
+
+1. Treat the current PR title and description as user-approved context unless the user explicitly asks for a change
+2. If the user does ask for an update, keep the title and description aligned with the **entire branch**, not just the latest iteration
+3. Do not overwrite a good PR summary just because you made a new commit, merged `main`, or addressed review feedback
+
 ### Common Mistake
 
 ❌ **Wrong:** PR titled after the most recent commit ("fix: resolve Windows test failures")  

.squad/agents/githubexpert/history.md

@@ -2,6 +2,15 @@
 
 ## Learnings
 
+### 2026-07-15 — Merge main into feature branch (shallow clone handling)
+
+**Context:** Branch `copilot/fix-github-issue-96` was a shallow clone (grafted). Merging main required `git fetch --unshallow` first, then `git fetch origin main:refs/remotes/origin/main` to create the remote tracking ref. PR #93 (`Fix unit test failure in workspace tests`) fixed the failing workspace-extractor test. After merge, all 910 tests pass.
+
+**Key patterns:**
+- Always check `git rev-parse --is-shallow-repository` before merge/rebase operations.
+- Shallow clones won't have `origin/main` — need explicit fetch to create tracking ref.
+- Run tests before AND after merge to confirm the fix vs pre-existing failures.
+
 ### 2025-05-18 — gh-aw (GitHub Agentic Workflows) Feasibility Analysis
 
 **Context:** Evaluated [gh-aw](https://github.com/github/gh-aw) as a possible replacement for hand-rolled YAML workflows in the branch maintenance plan.
@@ -27,3 +36,19 @@
 5. **gh-aw *does* support custom GitHub Apps for writes.**  `safe-outputs.github-app` accepts `client-id`/`private-key` for the write-side job ([Safe Outputs — Global Configuration Options](https://github.github.com/gh-aw/reference/safe-outputs/#global-configuration-options)), and `on.github-app` does the same for activation and skip-if jobs ([Activation Token](https://github.github.com/gh-aw/reference/triggers/#activation-token-ongithub-token-ongithub-app)). Most safe-output types also accept a custom `github-token:`. A custom GitHub App pattern is therefore compatible with gh-aw and is **not** a blocker for adoption.
 
 6. **Phased adoption is a general engineering principle, not a gh-aw–specific finding.** The gh-aw homepage carries an explicit caution: *"GitHub Agentic Workflows is in early development and may change significantly… Use it with caution, and at your own risk."* ([homepage note](https://github.github.com/gh-aw/)). Combined with the platform's emphasis on human supervision, this supports starting with low-risk advisory workflows before adopting anything gating.
+
+### 2026-07-15 — PR #102 metadata correction
+
+**Context:** PR #102 was auto-created with title/body describing only the last action (merge main) instead of the branch's actual work (override format alignment for issue #96). Updated PR body via `engine-tools-report_progress`. Title update blocked by `gh` CLI 403 — the Copilot agent token lacks GraphQL mutation scope for `updatePullRequest`.
+
+**Key patterns:**
+- `engine-tools-report_progress` updates PR body but NOT title.
+- `runtime-tools-create_pull_request` detects existing PRs but does not update them.
+- `gh pr edit` requires a token with full `repo` scope; the Copilot agent token (`ghu_*`) does not have it.
+- Always review auto-generated PR metadata before sharing — branch name `copilot/fix-github-issue-96` correctly hints at the real work, but the auto-title did not.
+
+### 2026-06-01 — Orchestration: merge main into branch
+
+**Context:** Scribe executed merge-main manifest for branch `copilot/fix-github-issue-96`. Merge validation: tests run before/after to confirm stability.
+
+**Pattern:** Standard merge orchestration with validation gates.

.squad/agents/scribe/history.md

@@ -10,7 +10,8 @@ Agent Scribe initialized and ready for work.
 ## Recent Updates
 
 📌 Team initialized on 2026-04-07
+📌 **2026-06-01:** Processed GitHubExpert coordination for PR #102 metadata correction. Merged decision from inbox into decisions.md, created orchestration and session logs.
 
 ## Learnings
 
-Initial setup complete.
+Initial setup complete. Scribe role working as designed: ingesting agent coordination logs, maintaining decision history, supporting team transparency.

.squad/decisions.md

@@ -2,6 +2,15 @@
 
 ## Active Decisions
 
+### 2026-07-15: PR #102 Metadata Correction
+**By:** GitHubExpert  
+**Status:** Applied (partial)  
+**What:** PR #102 body updated to accurately reflect the branch's real work — aligning apiops-cli override configuration format with APIOps Toolkit (issue #96). Title update requires manual intervention due to API token scope limitations.  
+**Why:** The PR was auto-created with metadata describing only the final merge-main action, not the feature work (override format alignment, docs updates, test hardening). Accurate PR metadata is critical for reviewer context and changelog generation.  
+**Correct title:** `fix: align override configuration format with APIOps Toolkit`
+
+---
+
 ### 2026-05-28T23:06:01Z: Team-Wide Evidence Standard
 **By:** User directive (anonymized)  
 **Status:** Active directive  

.squad/templates/copilot-instructions.md

@@ -51,6 +51,8 @@ Always include `Closes #N` or `Fixes #N` in commit messages when the change reso
 
 When opening a PR:
 - **Title and description must summarize ALL changes in the branch**, not just the last commit. Use `git log main..HEAD --oneline` (or the appropriate base branch) to review all commits and write a comprehensive PR title and description.
+- Once a PR already exists, **do not change its title or description unless the user explicitly asks you to do so**.
+- If the user does ask for an update, preserve the full-branch summary instead of rewriting the PR around only the most recent iteration.
 - Reference the issue in **both** the commit message AND the PR body: `Closes #{issue-number}`. The PR body is a redundant safety net if commit message formatting fails.
 - If the issue had a `squad:{member}` label, mention the member: `Working as {member} ({role})`
 - If this is a 🟡 needs-review task, add to the PR description: `⚠️ This task was flagged as "needs review" — please have a squad member review before merging.`

docs/commands/publish.md

@@ -111,28 +111,34 @@ Pass an override YAML file with `--overrides`:
 ```yaml
 # configuration.prod.yaml
 namedValues:
-  api-key:
-    value: "prod-api-key-value"
-  secret-from-keyvault:
-    keyVault:
-      secretIdentifier: "https://prod-kv.vault.azure.net/secrets/my-secret"
-      identityClientId: "00000000-0000-0000-0000-000000000000"
+  - name: api-key
+    properties:
+      value: "prod-api-key-value"
+  - name: secret-from-keyvault
+    properties:
+      keyVault:
+        secretIdentifier: "https://prod-kv.vault.azure.net/secrets/my-secret"
+        identityClientId: "00000000-0000-0000-0000-000000000000"
 
 backends:
-  backend-api:
-    url: "https://prod-api.example.com"
+  - name: backend-api
+    properties:
+      url: "https://prod-api.example.com"
 
 apis:
-  echo-api:
-    serviceUrl: "https://prod-echo.example.com"
+  - name: echo-api
+    properties:
+      serviceUrl: "https://prod-echo.example.com"
 
 diagnostics:
-  applicationinsights:
-    loggerId: "appinsights-logger-prod"
+  - name: applicationinsights
+    properties:
+      loggerId: "appinsights-logger-prod"
 
 loggers:
-  appinsights-logger:
-    resourceId: "/subscriptions/xxx/resourceGroups/prod-rg/providers/microsoft.insights/components/prod-appinsights"
+  - name: appinsights-logger
+    properties:
+      resourceId: "/subscriptions/xxx/resourceGroups/prod-rg/providers/microsoft.insights/components/prod-appinsights"
 ```
 
 ### Overridable resource types
@@ -145,7 +151,7 @@ loggers:
 | `diagnostics` | `loggerId` |
 | `loggers` | `resourceId` |
 
-Resource **names** must match across environments — only **properties** are overridden.
+Resource names are matched by each list item's `name`. Only values in `properties` are overridden.
 
 ## Dependency ordering
 

docs/getting-started.md

@@ -76,15 +76,17 @@ Referenced backends, named values, and policy fragments are included automatical
 
 ## 4. Publish to a Target Environment
 
-Create `overrides.prod.yaml` for environment-specific values:
+Create `configuration.prod.yaml` for environment-specific values:
 
 ```yaml
 namedValues:
-  backend-url:
-    value: "https://api.prod.example.com"
+  - name: backend-url
+    properties:
+      value: "https://api.prod.example.com"
 backends:
-  my-backend:
-    url: "https://api.prod.example.com"
+  - name: my-backend
+    properties:
+      url: "https://api.prod.example.com"
 ```
 
 Publish to your target APIM instance:
@@ -95,7 +97,7 @@ apiops publish \
   --resource-group prod-rg \
   --service-name prod-apim \
   --source ./apim-artifacts \
-  --overrides overrides.prod.yaml
+  --overrides configuration.prod.yaml
 ```
 
 ## 5. Preview Changes with Dry-Run
@@ -108,7 +110,7 @@ apiops publish \
   --resource-group prod-rg \
   --service-name prod-apim \
   --source ./apim-artifacts \
-  --overrides overrides.prod.yaml \
+  --overrides configuration.prod.yaml \
   --dry-run
 ```