feature(#1101): idempotent Foundry portal-tracking agent ensure (all 52) (#1101)

Adds scripts/ops/ensure_foundry_tracking_agents.py: an idempotent upsert script that scans apps/<svc>/agent.yaml for direct-model tracking agents, composes published instructions (prompt + hardening block, byte-identical to holiday_peak_lib.agents.prompt_loader), and POSTs create-or-update against the Foundry assistants API for both -fast and -rich roles.

Wires the script into deploy-azd-core as a new ensure-foundry-agents job that runs after provision/deploy-foundry-models and self-heals on every deploy. Idempotent: re-running produces noop=52 errors=0.

Closes the gap exposed when the truth-* and search-enrichment-agent services were added: those 10 agents had never been registered in Foundry. Also realigns the 42 stale agents (created 2026-02-26 with phi-4-mini-instruct and empty instructions) onto gpt-5-nano/gpt-5 with populated instructions, matching the workflow env.

Validation: pre-push gate (8 checks, 705+ tests, 206s) PASSED. New unit tests (11) green. Live dev Foundry reconcile applied -- now shows 52 agents (26 gpt-5-nano + 26 gpt-5); re-run yields noop=52.

Author: Cataldir

.github/workflows/deploy-azd.yml

@@ -1753,6 +1753,49 @@ jobs:
           AZURE_RESOURCE_GROUP: ${{ inputs.projectName }}-${{ inputs.environment }}-rg
           AI_SERVICES_NAME: ${{ needs.provision.outputs.AI_SERVICES_NAME }}
 
+  ensure-foundry-agents:
+    runs-on: ubuntu-latest
+    needs:
+      - provision
+      - deploy-foundry-models
+    if: ${{ always() && !inputs.uiOnly && !inputs.skipProvision && needs.provision.result == 'success' && (needs.deploy-foundry-models.result == 'success' || needs.deploy-foundry-models.result == 'skipped') && needs.provision.outputs.PROJECT_ENDPOINT != '' }}
+    environment: ${{ inputs.githubEnvironment }}
+    env:
+      AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
+      AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}
+      AZURE_SUBSCRIPTION_ID: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+      PROJECT_ENDPOINT: ${{ needs.provision.outputs.PROJECT_ENDPOINT }}
+      MODEL_DEPLOYMENT_NAME_FAST: gpt-5-nano
+      MODEL_DEPLOYMENT_NAME_RICH: gpt-5
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ env.DEPLOY_SOURCE_CHECKOUT_REF }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install ensure script dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install "azure-identity>=1.17" "PyYAML>=6.0"
+
+      - name: Azure login (OIDC)
+        uses: azure/login@v2
+        with:
+          client-id: ${{ env.AZURE_CLIENT_ID }}
+          tenant-id: ${{ env.AZURE_TENANT_ID }}
+          subscription-id: ${{ env.AZURE_SUBSCRIPTION_ID }}
+
+      - name: Ensure Foundry portal-tracking agents (idempotent)
+        run: |
+          python scripts/ops/ensure_foundry_tracking_agents.py \
+            --project-endpoint "$PROJECT_ENDPOINT" \
+            --fast-model "$MODEL_DEPLOYMENT_NAME_FAST" \
+            --rich-model "$MODEL_DEPLOYMENT_NAME_RICH"
+
   deploy-crud:
     runs-on: ubuntu-latest
     needs:

memories/repo/workflow-permission-cap-linter.md

@@ -0,0 +1,29 @@
+# Workflow permission-cap linter (`scripts/ci/lint_workflow_permissions.py`)
+
+## What it enforces
+GitHub Actions rule: in a `workflow_call` chain, callee permissions can only be **maintained or reduced** by the caller. Violations → `startup_failure` before runner allocation.
+
+## How effective permissions are computed (CRITICAL)
+For each callee job, effective permissions = **per-job `permissions:` if present, else workflow-level `permissions:`**. The linter MUST seed the required-set from callee workflow-level perms; per-job maps override per-key. This was missing pre-PR #1100 and caused a false-negative on `deploy-azd-truth.yml`.
+
+## Caller-side fallback
+Same semantics: caller workflow-level `permissions:` are the fallback for jobs that omit `permissions:`. Already implemented.
+
+## Failure mode if you miss the fallback
+- Linter passes locally + in PR CI
+- GitHub orchestrator rejects with `startup_failure` (7s run, no logs)
+- Looks identical to a transient queue issue
+- PR #1097 → 2 days undetected → issue #1099
+
+## Tests
+`scripts/ci/tests/test_lint_workflow_permissions.py` — 5 cases:
+1. Caller grants required perms → pass
+2. Caller missing `pull-requests: write` (PR #1097 regression) → flag
+3. Caller `contents: read` vs callee per-job `contents: write` → flag
+4. Callee with no per-job perms → pass
+5. **Callee workflow-level `contents: write` (no per-job override), caller `contents: read` → flag** ← prevents recurrence of deploy-azd-truth.yml class
+
+## Operational notes
+- Required check `Permission-cap lint (cross-file nested-workflow rule)` in `.github/workflows/lint-actions.yml`
+- Emits `::error file=...::` GitHub annotations, exit 1 on violation
+- `actionlint` used with `-shellcheck=` to disable shellcheck (catches unrelated pre-existing SC2034/SC2129/SC2153)