The-transit-Project/.github/agents/azure-deploy/scaffold/references/validation-and-manifest.md

Important: This skill provides guidance and recommended instructions to assist the AI system. Outputs are not guaranteed to be complete, correct, secure, or applicable to every scenario. Results should be reviewed and validated by a human before being applied. The AI model may choose not to follow all instructions exactly, and additional verification may be required.

Validation, Manifest & Approval — Steps 10–12.5

Step 10 — CI/CD

Do NOT auto-generate workflow files or create branches/PRs. Scaffold only writes IaC files. This step activates only when context.json.repo.remote is non-null AND user explicitly requests branch/PR creation. When repo.remote is absent or user declines, write IaC directly to working tree. If the user asks for CI/CD, or after deploy completes, suggest it as a follow-up: call mcp_azure_mcp_deploy → deploy_pipeline_guidance_get with is-azd-project: false, pipeline-platform: "github-actions", deploy-option: "provision-and-deploy" and present the guidance for the user to apply.

Step 11 — Validate Generated IaC

⛔ Validation MUST happen BEFORE the manifest is written. The manifest requires validationResult — you cannot write it without completing validation first. Do NOT write scaffold-manifest.json until validation has run.

⛔ Do NOT call other agents during scaffold/deploy — see pipeline-rules.md.

Run these checks directly. All must pass.

11a. Bicep compilation:

az bicep build --file infra/main.bicep --stdout > $null

(Bash: redirect to /dev/null instead of $null.) This discards the compiled ARM JSON; diagnostics still arrive on stderr, so read stderr — do not just check the exit code.

⛔ Exit 0 does NOT mean the template is valid. az bicep build exits 0 on Warning BCP* diagnostics, and those warnings describe a template that will not do what it says. Measured on bicep 0.46.1: a resource missing its required location, sku and kind compiles with exit 0 and only Warning BCP035. An agent that trusts the exit code ships a resource with no SKU and reports it as validated.

Pass criteria — all three must hold:

Signal	Verdict
Non-zero exit, or any Error BCP*	Fail — fix and retry
Warning BCP* (e.g. BCP035 missing required property, BCP036 wrong property type)	Fail — fix and retry
BCP081 "does not have types available"	Advisory only — see below
Linter warnings (no-unused-params, prefer-interpolation, …)	Pass — do not block

BCP081 is carved out because bicep ships a bundled type index that lags ARM, so it also fires on API versions that are real and current. It cannot distinguish an invented resource type from a merely newer one. Do not treat it as a failure, but do read it — if the resource type is genuinely misspelled, that is a real bug.

Fail: fix errors and retry.

11b. Static RBAC review — review generated Bicep for correct role assignments per rbac-roles.md. Every managed identity ↔ resource pair must have a Microsoft.Authorization/roleAssignments resource with the correct role GUID.

11c. Write validationResult — after all checks pass, write:

{
  "validationResult": {
    "status": "Validated",
    "checks": [
      { "name": "bicep build", "passed": true, "detail": "<the command you ran and what it reported>" },
      { "name": "RBAC review", "passed": true, "detail": "<which identity/resource pairs you checked>" }
    ]
  }
}

⛔ Field names are fixed — copy them exactly. validationResult MUST match ValidationResult in scaffold-schemas.ts: status + checks[], where each check is { name, passed: boolean, detail?: string }.

• passed is a boolean — not "result": "PASS", not "status".
• The array is checks — not notes, warnings, or errors.
• Do NOT use ConformanceResult ({ passed, failures[], source }) here. That is a different type for a different gate (the Step 3c plan-conformance script). validationResult is never shaped like it.

⛔ detail must describe what you actually observed — the command you ran and its real output. Do not copy the placeholder text above, and never write a detail claiming a command succeeded unless you ran it and it did.

Terraform path: Replace 11a with terraform init -backend=false && terraform validate.

• If validation finds FIXABLE errors: edit IaC → re-run self-review (L1–L4) → re-validate (max 3 attempts). ⛔ You MUST read scaffold-healing-rules.md before entering the healing loop — it defines error classification (FIXABLE vs BLOCKING) and auto-fix strategies.
• If BLOCKING errors remain after 3 attempts: surface to user and halt.

Step 12 — Write scaffold-manifest.json

⛔ You MUST read scaffold-schemas.ts to get the exact ScaffoldManifest interface. Write to the session folder with ALL fields populated: files[], selfReview.findings[], AND validationResult (from Step 11). This is a single write — validation is already complete.

⛔ Phase exit gate: scaffold-manifest.json.validationResult MUST NOT be null. If validation ran: { status: 'Validated'/'Partial'/'Failed', checks: [{ name, passed, detail? }] } (per ValidationResult in scaffold-schemas.ts). Null = incomplete scaffold.

You MUST also update context.json per AppOnboardContext in session-schemas.ts: append "scaffold" to completedPhases, set currentPhase to "deploy", update lastModifiedUtc.

Step 12.5 — Deploy Approval Gate

Present the user with: files generated, selfReview findings, validation results (pass/fail per check from Step 11), services + SKUs, secure-defaults applied. End with: "Ready to deploy? (Yes / Run manually / Edit plan / Cancel)" — do not continue until the user approves.

⛔ Self-check before presenting the deploy gate. Does scaffold-manifest.json contain a validationResult field with status set? If NO → you skipped Step 11. Go back and run validation. Do NOT present the deploy gate with validationResult: null.

⛔ Quota gate — MANDATORY. Read prepare-plan.json.quotaValidation. If verified == false, method == "unverifiable", or method is not "cli" for quota-constrained services: read sku-quota-validation.md § Deploy Gate Re-Validation and follow the procedure. ⛔ Do NOT use az vm list-usage, az appservice list-locations, or mcp_azure_mcp_quota for quota checks — see Anti-Patterns in sku-quota-validation.md.

⛔ Azure service compatibility warnings. Read prereq-output.json.warnings[] for any warnings with fixPhase: "deploy-gate". Surface EACH at the deploy gate: "⚠️ Azure compatibility: {warning.summary}. Fix: {warning.fix}. Approve? (Yes / Skip / Cancel)". If the user skips, add to postDeployRecommendations[].

⛔ Phase exit — NOT complete until ALL done:

1. scaffold-manifest.json written with files[], selfReview.findings[], AND validationResult
2. context.json: "scaffold" appended to completedPhases, currentPhase → "deploy", lastModifiedUtc updated
3. deploy-checklist.md exists in session folder — written by the parallel checklist subagent at scaffold Step 5b (before IaC gen completes). Verify it exists. If missing (subagent failed), write it now from deploy-checklist-template.md — fill in real values from prepare-plan.json, delete unrelated compute sections.