──────

### 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,102 @@
+<!-- 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.
+
+# Readiness Gate — Step 4
+
+## Write Artifacts
+
+⛔ **You MUST read [`prereq-artifacts.md`](prereq-artifacts.md)** for complete artifact write procedures and phase exit checklist.
+
+---
+
+## Severity Tiers
+
+| Verdict | Icon | Meaning |
+|---------|------|---------|
+| Hard Halt | 🛑 | App is intentionally vulnerable — pipeline stops, no fix possible |
+| Major Migration | 🔶 | Large-scope change (EOL runtime, cloud SDK migration, >5 files) — redirect or warn |
+| Critical | ❌ FAIL | Deployment will fail — agent can fix (≤5 files, config-level) |
+| Recommended Fix | 🔧 | App deploys but has quality/security issues — agent offers fix |
+| Warning | ⚠️ WARN | Informational, non-blocking — can proceed with caveats |
+| Pass | ✅ PASS | No issues |
+
+---
+
+## Overall Health Gate
+
+**Compute `overallHealth`:** ALL ✅ PASS → `"ready"` | Any ⚠️ WARN no ❌ FAIL → `"readyWithCaveats"` | ANY ❌ FAIL → `"blocked"`
+
+**Component `readiness.status` alignment:**
+- `"ready"` → `readiness.status: "ready"`
+- `"readyWithCaveats"` → `readiness.status: "ready"` (WARNs aren't "needs fixes")
+- `"blocked"` → `readiness.status: "needsFixes"`
+- After remediation → `readiness.status: "fixesApplied"`
+
+⛔ `readiness.status: "needsFixes"` requires at least one ❌ FAIL. If all ⚠️/✅, use `"ready"`.
+
+---
+
+## Critical Readiness Gate
+
+⛔ **Verdict propagation cross-check** before computing `overallHealth`:
+1. Any finding with `verdict: "FAIL"` → axis verdict MUST be `"FAIL"`.
+2. Any finding with `verdict: "WARN"` + `fixPhase: "prereq"` → escalate to `"FAIL"` (prevents wasting a deploy cycle). ⛔ Escalate only WARNs that would actually break THIS deploy (build/startup failure, or a health probe wired to a route the app lacks). Issues that deploy and run fine — missing trust proxy, README, in-memory sessions — stay `fixPhase: "postdeploy"`/`"scaffold"`; `engines`/health-endpoint escalate only on a real version/probe mismatch (see [completeness-check.md](completeness-check.md) § Stack-Specific Checks).
+
+| Tiers | Reference file |
+|-------|---------------|
+| 🛑 🔶 🔧 ⚠️ | [`dependency-compatibility.md`](dependency-compatibility.md) |
+| ❌ 🔧 | [`completeness-check.md`](completeness-check.md) |
+| ❌ | [`build-check.md`](build-check.md) |
+
+**Post-evaluation HALT cross-check:** Intentionally vulnerable apps (≥2 code signals from dependency-compatibility.md) → `overallHealth: "blocked"` MUST be written to `prereq-output.json` on disk (Step 4) BEFORE any halt message. If the artifact is not on disk when you reach the halt, write it NOW via the `create` tool and read it back — do NOT present the halt until it exists.
+
+---
+
+## Batch-Then-Approve Flow
+
+⛔ **Artifacts before message.** Write AND read back all 3 artifacts (`prereq-output.json`, `context.json`, `readiness-report.md`) to confirm they exist on disk BEFORE presenting any findings, cloud-SDK stop prompt, or 🛑 hard-halt message. Those messages can end the turn, so every artifact MUST already be persisted — NEVER batch artifact writes after the message.
+
+1. **Detect ALL issues first** — full 3-axis scan, all components.
+2. **Present ALL findings at once** — summary: "🔍 Readiness: 2 critical, 1 recommended fix, 3 warnings". Group: 🛑 → 🔶 → ❌ → 🔧 → ⚠️.
+3. **Fix plan** — for ❌, 🔧, 🔶, ⚠️ with `fixPhase: "prereq"`: describe WHAT and WHY. ⛔ Exclude 🔶 with `routeToSkill` set. Never include 🛑.
+4. **User choice** (based on highest severity):
+   - **🛑:** Pipeline stops. No formal gate.
+   - **🔶 + others:** "Fix {N} issues including {M} migration(s) — scope warning" / "Fix blockers only" / "Continue with risks" / "Cancel"
+   - **🔶 only:** "Attempt migration" / "Continue as-is" / "Cancel"
+   - **❌/🔧/⚠️ with fixPhase prereq:** "Fix {N} deployment issues" / "Continue with risks" / "Cancel"
+5. **After approval** → apply fixes per [remediation-protocol.md](remediation-protocol.md).
+
+> ⛔ **Two-gate rule:** Intent approval ≠ fix execution approval. Present the fix prompt here even if user agreed earlier.
+
+---
+
+## Fast-Track
+
+Single-component + no DB + no auth + **no Dockerfile** → `fastTrackEligible: true`.
+
+---
+
+## Present Findings (Step 5)
+
+⛔ Do NOT skip — user must see scan results before pipeline continues.
+
+**Part 1 — Summary:** "🔍 Readiness: {N} critical, {M} fixes, {K} warnings" (or "✅ Ready").
+**Part 2 — Per-axis reasoning:** Verdict icon + 1–2 sentence summary per axis.
+**Part 3 — Findings table:** Grouped by severity. Include warning ID and actionable detail.
+
+**Data-loss warnings** (SQLite, in-memory sessions, local file storage) require explicit acknowledgment. Other ⚠️ are informational.
+
+End with: "📄 Full evaluation saved to `readiness-report.md`."
+
+### Remediation Decision Gate
+
+⛔ **STOP after presenting findings.** Options:
+1. **"Fix deployment issues"** — fix all actionable items (❌, 🔧, ⚠️ with `fixPhase: "prereq"`). Re-evaluate after.
+2. **"I have context — let me guide the fixes"**
+3. **"Continue without fixing — I accept the risks"**
+
+Wait for explicit choice. Generic "Yes"/"Go ahead" ≠ remediation consent — clarify if ambiguous.
+
+> ⛔ **Remediation budget:** Max 3 cycles. See [remediation-protocol.md](remediation-protocol.md) step 7.
+
+> ⛔ **ARTIFACT CHECKPOINT.** After presenting findings, verify all 3 artifacts exist: `context.json`, `prereq-output.json`, `readiness-report.md`. Write any missing ones NOW.