──────

### Summary of Changes 1. Documentation Consolidation: • Relocated the docs/ folder and all repository .md files (README.md, DEPLOYMENT.md, DOCKER_README.md, DOMAINS_README.md, GETTING_STARTED.md, CI_CD_PORTAINER_GUIDE.md, ADMIN_DEPLOYMENT_SUMMARY.md, SECURITY_PRIVATE_FILES.md, handoff.md, azure-project-plan.md, plus service-specific READMEs) into . • Updated document links in README.md. 2. AI Agent Project Map: • Created PROJECT_MAP.md in the project root containing complete architecture diagrams, service specs, ports, DB schemas, environment variables, and developer workflows. • Added PROJECT_MAP.md to .gitignore. 3. Monitoring UI & Infrastructure Integration: • Added monitoring_ui service to docker-compose.yml (port 5175). • Configured Gitea workflow docker-build.yml for monitoring_ui builds. • Added CORS middleware headers in index.js. • Added nginx.conf copy step in Dockerfile. ────── ### Recommended Commit Message docs: consolidate project documentation into monitoring_ui and add agent project map - Move all markdown documentation files and docs/ folder into monitoring_ui/docs/ - Update documentation hub index (monitoring_ui/docs/README.md) with relative paths - Generate comprehensive AI agent reference map (PROJECT_MAP.md) in repository root - Add PROJECT_MAP.md and monitoring_ui build output/env overrides to .gitignore - Integrate monitoring_ui service into docker-compose.yml and Gitea CI workflow - Configure CORS handling in employee_api for monitoring dashboard access ────── ### Alternative Short Commit Message refactor(docs): move docs to monitoring_ui and create AI agent PROJECT_MAP.md
2026-09-20 23:33:55 +02:00
parent f935bbeb8c
commit 635a130f0b
195 changed files with 28309 additions and 957 deletions
@@ -0,0 +1,89 @@
+<!-- azure-cor-disclaimer -->
+> **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](../../references/pipeline-rules.md).
+
+Run these checks directly. All must pass.
+
+**11a. Bicep compilation:**
+```powershell
+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](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:
+```json
+{
+  "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`](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](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`](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`](scaffold-schemas.ts)). Null = incomplete scaffold.
+
+**You MUST also update `context.json`** per `AppOnboardContext` in [`session-schemas.ts`](../../references/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`](../../prepare/references/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`](../../prepare/references/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`](../../deploy/references/deploy-checklist-template.md) — fill in real values from `prepare-plan.json`, delete unrelated compute sections.