@caddis/cli 0.4.14 → 0.4.15

package/bundles/antigravity-plugin/skills/pr-merge/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: pr-merge
+description: End-to-end pull request and merge lane — push feature branch, open or update PR, monitor CI to green, merge to default branch, and clean up the feature branch.
+---
+
+# /pr-merge — the unified reviewed lane: branch → PR → green → merged → cleaned up
+
+End-to-end delivery of feature-branch work through the reviewed lane in one shot: run preflight checks,
+push safely, create or update the Pull Request, monitor CI checks to green, merge into the default
+branch, validate the deployment, and clean up the feature branch.
+
+For a hotfix straight to the default branch with no PR ceremony, use `/ship` (the express lane) instead.
+To open a PR and stop at green for human review without merging, use `/ship-pr`.
+To merge an already-opened PR, use `/ship-merge`.
+
+Optional argument: **$ARGUMENTS** (PR title override; default = derived from the branch's
+conventional-commit summary). An optional strategy override (`squash` | `merge` | `rebase`)
+can be provided.
+
+## Step 0 — Detect the lane (before anything else)
+
+- **Gitea lane** — `.gitea/workflows/` exists. PR creation, CI monitoring, and merge via the Gitea API
+  (token loading and job-polling procedure: the `deploy-local` skill).
+- **GitHub lane** — `.github/workflows/` exists (and no `.gitea/`). PR creation, checks monitoring,
+  and merge via the `gh` CLI (`gh pr create`, `gh pr checks --watch`, `gh pr merge` — see the `gh-cli` skill).
+- **Local-only lane** — neither exists, or there is no push remote. There is no forge and no PR concept:
+  **refuse early**, tell the user to use `/ship`, and stop. Do not fabricate a PR flow.
+
+Read `AGENTS.md` + the detected workflow file(s) first for the repo's real gate names, default
+branch, and merge conventions — never assume `main`, never assume job names.
+
+## Step 1 — Refuse on the default branch
+
+A PR is *branch → default*. If HEAD **is** the default branch, stop and point at `/ship` — there is
+nothing to open a PR from. (Offer to create a feature branch from the current work if the changes
+are uncommitted.)
+
+## Step 2 — Preflight (local gates mirroring CI)
+
+- Backend: `ruff check .` clean (or repository linter).
+- Frontend: `npm run typecheck && npm run build` if `frontend/` exists.
+- Fix failures first. **Never open a PR over red preflight** — a PR that arrives red wastes CI resources
+  and reviewer time.
+
+## Step 3 — Scope-guard pre-check (before the PR exists)
+
+- If the repo has a **named scope-guard workflow** (e.g. a Gitea `pr-scope-guard` that blocks PRs
+  mixing infra `.gitea/`/`.github/` changes with product `src/`/`frontend/`/`tests/` changes): read
+  the workflow's own rule and check the branch diff against exactly that rule **before** creating
+  the PR. On a violation, **refuse with the specific offending files** — do not let the guard fail
+  the PR after the fact.
+- Without a named guard, apply the generic infra-vs-product mixed-diff heuristic as a **warning
+  only** — surface it and proceed (repos without a guard allow mixed PRs by construction).
+
+## Step 3b — Cross-review trigger (before anything is pushed)
+
+<!-- shared:cross-review-trigger — keep byte-identical across commands; a test pins it -->
+**Run the trigger, do not eyeball the diff:**
+
+```bash
+python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_gate.py" review-trigger --range <base>...HEAD
+```
+
+Exit **0** — say nothing, carry on. Exit **2** — it prints which rule fired and on which files.
+Run `/caddis:cross-review`, show the findings, and let the user decide. It **never blocks**: this
+picks when to ask for a second opinion, it is not a verdict, and a review gate that blocks a ship
+gets switched off inside a week.
+
+It fires on SQL and repositories, `services/`, caches and refresh jobs, auth and RBAC, or a diff
+over 400 changed lines. No judgement in any of those — deliberately, because judgement is exactly
+what failed.
+<!-- /shared:cross-review-trigger -->
+
+## Step 4 — Rebase-safe currency
+
+- If the branch is **behind** the default branch, offer to rebase onto it (stale branches are how
+  merges rot). Only when behind — never rebase gratuitously.
+- If the branch was already pushed, a rebase rewrites history. **Snapshot first, then push safely:**
+  ```
+  git branch backup/<branch>-preship          # recovery ref BEFORE any rewrite
+  git rebase <default-branch>
+  git push --force-with-lease origin <branch> # never bare --force
+  ```
+
+## Step 5 — Push + create or update the PR
+
+- Push the branch to remote (plain push if no rewrite happened).
+- Create the PR: title from the branch's conventional-commit summary (or `$ARGUMENTS`); body = the
+  commit list + a "generated by /pr-merge" note.
+- **Idempotent:** if a PR for this branch **already exists**, reuse it, update its title/body, and
+  report it — never error, never open a duplicate.
+
+## Step 6 — Monitor PR CI checks
+
+Watch the PR's checks job-by-job until completion:
+- Gitea lane: poll the run for the PR's head SHA via the API (`deploy-local` skill procedure).
+- GitHub lane: `gh pr checks <pr> --watch` / `gh run watch` (`gh-cli` skill).
+- If any check fails (red check): report the failure, classify the cause, and **stop before merging**.
+  Do not merge a failing PR. Apply the minimum source fix and re-push.
+
+## Step 7 — Merge to default branch
+
+Once all required checks are **green**, there are no merge conflicts, and review requirements are satisfied:
+- Use the repo's configured **merge strategy** — read it from repo settings (Gitea repo settings API /
+  `gh repo view --json squashMergeAllowed,mergeCommitAllowed,rebaseMergeAllowed`) and `AGENTS.md`;
+  an explicit argument wins. Options: **squash**, **merge-commit**, rebase-merge. **Don't assume** —
+  if detection is inconclusive, use merge-commit (never silently squash someone's history without evidence).
+- Execute merge:
+  - GitHub: `gh pr merge <pr> --<strategy>` (e.g. `gh pr merge <pr> --squash`).
+  - Gitea: call the Gitea PR merge API with the chosen strategy.
+- Record the merge SHA.
+
+## Step 8 — Monitor deployment & validate (if applicable)
+
+If the default branch triggers an automated deployment pipeline:
+- Gitea: `lint_and_test` → `deploy_prod` → `release_metadata` (`deploy-local` skill).
+- GitHub: `gh run watch <run-id> --exit-status` on the default branch. If CI-only, note that no deploy occurs.
+- Validate health and deployed SHA if a live service is deployed. If deploy validation fails, report
+  immediately and **skip cleanup** (Step 9).
+
+## Step 9 — Close feature-branch lifecycle (Clean up)
+
+**Only after** the merge is complete and deployment (if any) is validated green:
+- Switch to the default branch: `git switch <default-branch>`.
+- Fast-forward to the merge commit: `git pull --ff-only origin <default-branch>`.
+- Delete the **local** feature branch: `git branch -d <branch>` (use `-D` only if squashed after verifying tree contents match).
+- Delete the **remote** feature branch: `git push origin --delete <branch>` (if not deleted by forge).
+- Drop the temporary `backup/<branch>-preship` ref if one was created in Step 4.
+
+If deploy validation failed: **skip cleanup** entirely and report why — never delete a branch whose
+work may need re-work.
+
+## Step 10 — Report
+
+```
+PR:            #<n> <title> — merged (<strategy>) as <merge-sha>
+Checks:        <check ✓ per check>
+Deploy:        <job ✓ / ✗ per job | n/a>
+Prod SHA:      matches merge ✓ | n/a
+Cleanup:       remote branch deleted / local branch deleted / backup ref dropped | SKIPPED (<why>)
+```
+
+## Rules
+
+- Never merge a PR whose required checks are red or absent.
+- Never delete a feature branch before its merge is confirmed and any deploy validated.
+- Never `git add -A` without reviewing `git status` first (stage named files only).
+- Never force-push without a `backup/*-preship` recovery ref; force pushes are `--force-with-lease` only.
+- Never edit a workflow file (`.gitea/workflows/`, `.github/workflows/`) to make a gate pass — fix the source.
+- Local-only lane: refuse + point at `/ship`. On the default branch: stop + point at `/ship`.
+
+## Skill reference
+
+Gitea API monitoring, deploy tracking, failure triage: the `deploy-local` skill (ships in optional `caddis-extras`).
+GitHub `gh pr create`, `gh pr checks`, `gh pr merge`: the `gh-cli` skill.

package/bundles/codex/.codex/skills/docs/confluence-hla/SKILL.md

@@ -0,0 +1,375 @@
+---
+name: confluence-hla
+description: Author enterprise High-Level Architecture (HLA) documents in Simplified Technical English and generate Confluence Storage Format XHTML with self-contained PlantUML diagrams, wrapped tables, and zero AI fingerprints. Use when creating high-level architecture designs, architecture documentation for Confluence, or converting markdown architecture to Confluence storage format.
+---
+
+# Confluence High-Level Architecture (HLA) Authoring Skill
+
+A cross-agent skill for **Claude Code**, **OpenAI Codex CLI**, and **Antigravity (`agy`)** to research systems, discover data pipelines, author enterprise-grade High-Level Architecture (HLA) documents, and export them directly into clean, self-contained **Confluence Storage Format XHTML** with native PlantUML macros.
+
+---
+
+## 1. Core Principles
+
+1. **Simplified Technical English (ASD-STE100 Style):**
+   - Short sentences (under 20 words where possible).
+   - Active voice ("The worker queries telemetry" rather than "Telemetry is queried by the worker").
+   - Clear, everyday technical words; one concept per sentence.
+   - **CRITICAL:** Apply this style naturally. **NEVER** write notices, disclaimers, or metadata banners into the document stating that it was written in Simplified Technical English or ASD-STE100.
+2. **Zero AI Fingerprints, Zero Em-Dashes & Anti-Slop Discipline:**
+   - **NEVER use em-dashes (`—`) or en-dashes (`–`):** Em-dashes are the single most prominent dead giveaway of LLM-generated prose. Enterprise solutions architects do not write em-dashes. Use standard colons (`:`), hyphens (`-`), parentheses (`(...)`), or separate sentences instead.
+     - *Banned:* `High-Level Architecture (HLA) — AppointmentAssist`
+     - *Required:* `High-Level Architecture (HLA): AppointmentAssist`
+     - *Banned:* `- **Cancel Appointment — Area Outage:** ...`
+     - *Required:* `- **Cancel Appointment (Area Outage):** ...`
+     - *Banned:* `The system — which runs on Windows Server — polls telemetry.`
+     - *Required:* `The system runs on Windows Server. It polls telemetry.`
+   - **Absolute Ban on AI Slop Buzzwords and Hyperbolic Clichés:**
+     - *Banned verbs & nouns:* `delve`, `tapestry`, `plethora`, `beacon`, `game-changer`, `testament`, `revolutionize`, `cornerstone`, `leverage` (use `use`, `read`, or `query`), `foster`, `streamline`, `harnessing`, `embark`, `landscape` (in non-geographical contexts).
+     - *Banned adjectives:* `pivotal`, `crucial`, `meticulous`, `seamless`, `holistic`, `robust`, `comprehensive`, `cutting-edge`, `paramount`, `vibrant`.
+     - *Banned transitions & framing:* `Furthermore`, `Moreover`, `In conclusion`, `It is important to note`, `Let's explore`, `Here is a breakdown:`, `Key takeaways:`, `Summary:`.
+   - **Clean ASCII Punctuation:**
+     - Never use curly / smart quotes (`“`, `”`, `‘`, `’`) — always use straight ASCII quotes (`"`, `'`).
+     - Never use unicode bullet symbols (`•`) — always use standard markdown hyphens (`-`).
+     - Never use backtick formatting on ordinary English nouns.
+   - **Zero Meta-Commentary & Self-Referential Announcements:**
+     - Never write phrases announcing what the document is doing (e.g., "In this document we delve into...", "As requested by the user...").
+     - Start immediately with the title, status, metadata block, and executive overview.
+   - **Zero Tool / Agent / Assistant / Model Self-Attribution:**
+     - The final Confluence export must **NEVER** contain YAML frontmatter, agent attribution tags, model names, preparation notices, or document references that expose internal repository paths or harness tooling (`caddis`, `claude code`, `codex`, `antigravity`, `asd-ste100`).
+     - Note: Production application components (such as a local LLM daemon running on an on-premises GPU server) are documented as objective production system components, but the HLA itself must never attribute its own authorship to AI.
+   - **Automated Converter Enforcement:**
+     - The converter script (`convert_hla_to_confluence.py`) enforces this automatically by stripping all em-dashes, en-dashes, smart quotes, and AI buzzwords during HTML export.
+3. **Confluence Native Compatibility (Self-Contained PlantUML):**
+   - Uses native Confluence Storage Format XHTML.
+   - All tables wrapped with `<table class="wrapped">` and explicit `<colgroup>`.
+   - Table of contents generated via `<ac:structured-macro ac:name="toc" ac:schema-version="1"/>`.
+   - **Pure PlantUML:** Diagrams are rendered natively via Confluence PlantUML macros. No image uploads, attachments, or base64 data URIs are required—the generated HTML is 100% self-contained and ready for a single copy-paste into the Confluence Source Editor.
+   - Guaranteed 100% valid XML parseable by the Confluence Source Editor.
+4. **Mermaid & PlantUML Full-Text Fidelity (Zero Truncation Rule):**
+   - In Markdown (`.md`), always wrap Mermaid text lines using explicit `<br/>` tags (maximum ~35 to 45 characters per line) across actors, notes, messages, node labels, and edge transitions.
+   - Never allow unwrapped single-line strings to blow out diagram dimensions (>1200px) or truncate text in Git viewers, VS Code, or Confluence viewports.
+   - The converter (`convert_hla_to_confluence.py`) dynamically maps `<br/>` to `\n` in PlantUML so that both formats render complete, untruncated text cleanly.
+
+---
+
+## 2. Standard High-Level Architecture (HLA) Sections
+
+When authoring an HLA, strictly adhere to the following 7-section structure:
+
+```
+1. Executive Summary
+   1.1 Initiative Goal
+   1.2 Solution Architecture Summary (Functional layers)
+   1.3 Business Value & Operational Outcomes
+2. Project Context and Scope
+   2.1 Background
+   2.2 Scope (In Scope / Out of Scope)
+   2.3 Architecture Boundaries and Assumptions
+3. Solution Approach and Workflow
+   3.1 Operational Process Flow (Step-by-step numbers)
+   3.2 End-to-End Sequence Diagram (PlantUML sequence diagram with autonumber)
+4. Solution Architecture Landscape
+   4.1 Solution Design and Architecture (Compact topology and system boundary diagram)
+   4.2 Applications and Components Overview (Wrapped table: ID, Name, Function, Technology, Hosting)
+   4.3 Telemetry and Health Information APIs (Apigee / REST / RPC interfaces with target systems)
+   4.4 Multi-Stage Summarization and Recommendation Pipeline (PlantUML multi-track data flow)
+   4.5 End-to-End Database and Data Processing Pipeline (Mandatory discovery: Source DB -> Staging -> Input -> LLM -> Recs -> UI -> RLHF)
+   4.6 Screener Feedback Service and Continuous Learning (RLHF) (Capturing human decisions, notes, and ground truth)
+5. Security Architecture and Controls
+   5.1 Identity and Access Management (Authentication protocols, RBAC, loopback binding)
+   5.2 Network Boundaries and Perimeter Controls (Internal subnets, API gateway mediation, service accounts)
+   5.3 Data Protection and Privacy (TLS 1.2+ transit, TDE at rest, payload minimization)
+   5.4 Auditability and Operational Visibility (Trace logging, read-back verification, health checks)
+6. Target State Roadmap (Work In Progress)
+   6.1 Identity Evolution (e.g. Migration from NTLM to SAML 2.0 / OIDC SSO)
+   6.2 Compute / Intelligence Evolution (e.g. Cloud API to On-Premises GPU / Gemma model)
+7. Appendix
+   7.1 Terms and Definitions (Wrapped table: Term, Definition)
+   [Note: 7.2 References is kept in working Markdown but STRICTLY OMITTED from Confluence HTML]
+```
+
+---
+
+## 3. High-Level Database and Data Processing Pipeline Discovery
+
+Every application in the fleet follows an end-to-end data processing pipeline connecting operational database systems to machine learning intelligence and human screener decisions.
+
+### 3.1 Formal Database Asset & Lineage Hierarchy Notation
+
+Do not reference database tables in isolation. In enterprise architectures, tables reside within database catalogs hosted on specific physical or virtual servers, and are transformed or moved by explicit stored procedures or ETL engines running on designated hosts.
+
+Always identify data pipeline entities using the full hierarchy:
+
+```
+Host[Server] -> Database[DB] -> Schema.Table[Table/View]
+```
+
+Every lineage stage must explicitly specify:
+1. **Host Server:** The physical server, cluster, or virtual machine hosting the database engine (e.g., `IEROXAPP2`, `DBUATL01`).
+2. **Database Catalog:** The database name (e.g., `DERBY`, `Customer_FeedBack_JIT`).
+3. **Schema & Table / View:** The object namespace and name (e.g., `dbo.CASE_FAULTS`, `dbo.AppScreen_Pending_Calls`).
+4. **Population / Transformation Mechanism:** The exact script, worker process, SSIS package, or stored procedure (`sp_...`) that populates or updates the table.
+5. **Executing Host:** The exact machine where the ETL process, worker loop, or stored procedure runs (e.g., on the source database server itself, on a dedicated ETL host, or on the application server).
+6. **Trigger / Cadence:** The execution trigger (e.g., scheduled cron, continuous polling loop, SQL Agent job, or UI event).
+7. **Operational Payload:** The specific attributes, signals, or features passed through the stage.
+8. **Downstream Consumer:** The next service, worker, or human actor reading the entity.
+
+---
+
+### 3.2 Active Database Discovery Protocol (Do NOT Rely Solely on Documentation)
+
+Architecture documents and blueprints frequently become outdated or retain deprecated table names. The authoring agent must **actively inspect live configuration, code implementations, and database metadata**:
+
+1. **Configuration & Credential Discovery Protocol:**
+   - Scan `.env.*`, `config/.env*`, settings files, and connection strings.
+   - **Credential Priority:**
+     - **Priority 1 (Standard Fleet User):** Check for database credentials in `.env*`. The default enterprise user across fleet applications is typically `LinkedUser` (extract user, password, and port from config).
+     - **Priority 2 (Ambient Windows Auth Fallback):** If `LinkedUser` is absent or connection fails, use ambient Windows Integrated Authentication (`Trusted_Connection=yes;` with the executing user's ambient Windows context). Never hardcode or pin personal usernames so that all team members can execute the skill seamlessly.
+   - **Table Exclusion Rule:** Never map backup (`_BU`), partition (`_P1`, `_P2`, `_P\d+`), or historical replica tables. Exclude these during catalog queries and pipeline lineage synthesis to prevent noise.
+   - Extract primary database host (`DB_HOST`), secondary/telemetry host (`DERBY_SERVER`), database names (`DB_NAME`, `DERBY_DATABASE`), ODBC driver, and trust settings.
+   - Inspect Linked Server definitions (`sys.servers`) on connected hosts to identify cross-database federations and distributed queries.
+
+2. **Active Database Metadata Catalog Querying & Job Discovery:**
+   - When database connectivity or credentials exist, query the live database catalog:
+     - `INFORMATION_SCHEMA.TABLES` & `sys.tables`: Verify that referenced tables physically exist and identify current row counts and schemas. Distinguish active production tables from retired, backup, or partition tables.
+     - `INFORMATION_SCHEMA.ROUTINES` & `sys.procedures`: Identify active stored procedures (e.g., `dbo.usp_LoadCustomerTimeline`, `dbo.usp_CustomerTimeline_ApplyStage`, `dbo.sp_CASE_FAULTS`) that load, clean, or move data.
+     - `INFORMATION_SCHEMA.VIEWS`: Inspect view definitions (`OBJECT_DEFINITION` / `VIEW_DEFINITION`) to understand joined tables and upstream dependencies.
+     - `msdb.dbo.sysjobs` & `sysjobsteps`: Query live SQL Server Agent jobs to uncover exact scheduled batch loaders, step execution commands, and pipeline schedules.
+     - Linked Server Probes (`sys.servers`): Inspect remote data sources and linked gateways (e.g. `SNOWFLAKE_GENESYS`).
+
+3. **Pipeline Worker & Codebase Usage Verification:**
+   - Trace background batch scripts, CLI runners, and worker loops (e.g., `run_e2e_now.py`, `appscreen_diagnostics_processor.py`, `pipeline_service.py`, `Run_Genesys_Core_Daily.ps1`).
+   - Identify SQL queries, ORM models, and YAML query definitions (`queries_insights.yaml`, etc.) to verify which tables are actually active in application code.
+   - **Purge Unreferenced Tables:** Do NOT map tables that merely exist in the database catalog if code analysis shows they are unreferenced by the application (e.g., legacy order tables, obsolete staging tables, or test fixtures).
+
+4. **External ETL Bridges & Cross-Host Script Mapping:**
+   - If data originates from an external SaaS/Cloud datashare (e.g., Snowflake, Genesys Cloud, Salesforce) and traverses an ETL gateway server, document the exact bridge scripts (e.g. `C:\Scripts\Genesys\*.py`, `.ps1`), schedule triggers, and target upsert mechanisms.
+
+5. **User Consultation Rule for Remaining Gaps:**
+   - If an upstream ETL or batch trigger cannot be confirmed from code or live database catalogs, do not invent names.
+   - Summarize the verified facts and ask the user targeted questions to confirm the remaining operational links.
+
+---
+
+### 3.3 Fluid & Dynamic Pipeline Architecture Across Fleet Applications
+
+Pipeline stages are **fluid, adaptive, and application-specific**. The authoring agent must **NOT** hardcode or assume the stage names of AppointmentAssist ("Source Trouble Tickets", "Appointment Staging", "Diagnostic Enrichment") across other fleet repositories. 
+
+The pipeline stage count typically varies between **3 and 8 stages**, depending on the operational archetype of the system:
+
+1. **Decision Support & Triage Systems (e.g., AppointmentAssist):**
+   ```
+   [1. Source Trouble Tickets] -> [2. Appointment Staging] -> [3. Diagnostic Enrichment] -> [4. AI Model Inference] -> [5. Recommendation Storage] -> [6. Dispatcher Review Queue] -> [7. RLHF Feedback Capture]
+   ```
+2. **Entity Resolution & Customer Profile Systems (e.g., Customer Profile Service / Timeline Engine):**
+   - Must trace: Raw Telephony / CRM Staging -> Staging Swap Jobs -> Canonical Event Table (`dbo.CustomerTimelineEvent` / `EventDigest`) -> LLM Context Assembly (`dbo.CustomerLLMContext`) -> Standalone Inference Engine (Ollama / Local GPU) -> Summary Persistence -> Application UI.
+3. **Real-Time Telemetry & Probing Systems (e.g., Telemetry Monitor / Probe Service):**
+   ```
+   [1. Network Telemetry Probing] -> [2. Time-Series Raw DB] -> [3. Threshold Rule Engine] -> [4. Anomaly Prediction Model] -> [5. Incident Dispatch Queue] -> [6. Operator Acknowledgment]
+   ```
+4. **ELT Data Warehouses & Analytics Marts:**
+   ```
+   [1. Operational DB Replicas] -> [2. CDC Staging Tables] -> [3. Conformance & Cleaning Mart] -> [4. Dimensional & Fact Tables] -> [5. BI Reporting Views]
+   ```
+5. **Document & Audio AI Processing Systems:**
+   ```
+   [1. Multi-Channel Document Ingest] -> [2. Raw File Object Store] -> [3. OCR & Audio Transcription] -> [4. Entity & Feature Extraction] -> [5. LLM Synthesis Engine] -> [6. Verification UI] -> [7. Ground Truth Annotation Store]
+   ```
+
+---
+
+### 3.4 Standard Lineage Documentation Format (Section 4.5)
+
+Section 4.5 of the High-Level Architecture must include:
+1. **Narrative Overview:** Explanation of the end-to-end data lifecycle from input inception to output consumption or model fine-tuning.
+2. **Horizontal Stacked Lineage Diagram (STRICT MAX 4 LAYERS):**
+   - Mermaid in `.md`, PlantUML in Confluence HTML, showing Host, DB, Table, and Execution context.
+   - **CRITICAL READABILITY CONSTRAINT:** Do NOT stack 7 or 8 vertical layers. Group stages into **at most 4 logical layers** (e.g., Layer 1: Upstream Ingestion & Raw Staging, Layer 2: Canonical Event Spine & Context Assembly, Layer 3: AI Inference & Persistence, Layer 4: Application Presentation Layer).
+   - In each layer, arrange components horizontally (`direction LR` in Mermaid, `-right->` in PlantUML).
+   - Connect layers with clean orthogonal, 90-degree lines.
+3. **Structured 7-Column Lineage Table:**
+   While the stage count and names adapt fluidly to the application, the table schema strictly maintains all 7 standard columns:
+
+| Stage | Host Server | Database | Schema & Table / Entity | Population / Transformation Mechanism & Executing Host | Trigger / Schedule Cadence | Operational Payload & Downstream Consumer |
+|---|---|---|---|---|---|---|
+| **1. <Fluid Stage Name>** | Discovered host (`DB_HOST` or source) | Discovered DB / Catalog | Discovered tables or entities (`dbo.TABLE_NAME`) | Stored Procedure `dbo.usp_...` or ETL worker with executing host | Execution trigger (Continuous, Batch, Polling, Event) | Business data payload and the downstream consumer. |
+| **2. <Fluid Stage Name>** | Discovered host | Discovered DB | Discovered staging table or queue | Ingestion worker or service with executing host | Polling interval or event stream | Staged records awaiting enrichment or transformation. |
+| **3. <Fluid Stage Name>** | Processing host | Processing DB | Discovered feature table or dataset | Background worker, rule engine, or ETL script | Continuous polling loop or worker batch | Enriched attributes, normalized features, telemetry signals. |
+| **4. <Fluid Stage Name>** | Inference host | Model Runtime | AI model or scoring service | Scoring engine or LLM service with executing host | Pipeline batch or on-demand event | Input prompts / features, outputs scores or recommendations. |
+| **5. <Fluid Stage Name>** | Storage host | Output DB | Discovered results table or data mart | Persistence worker or database write | Post-processing transactional write | Final predictions, calculated indicators, alert records. |
+| **6. <Fluid Stage Name>** | App Host / Browser | UI / App DB | User dashboard or operational queue | Web dashboard and backend REST API | User interaction or session lifecycle | Interactive record presentation, claim locks, advisory state. |
+| **7. <Fluid Stage Name>** | Storage host | Target DB | Audit table, feedback store, or ground truth | Feedback API or audit worker with executing host | User action or system audit event | Operational decisions, override justifications, RLHF ground truth. |
+
+> **Critical Rule:** Never copy AppointmentAssist stage names or tables into an HLA for another application. Inspect the application's actual tables, stored procedures, worker scripts, and `.env*` configurations to formulate domain-accurate stages.
+
+---
+
+### 3.5 Standalone Database Lineage Discovery Tool & CLI Switches
+
+When you need to discover, map, or render the database lineage without executing a full HLA document generation cycle, use the dedicated lineage switches:
+
+1. **Automated Repository Lineage Discovery (`discover_db_lineage.py`):**
+   ```powershell
+   python scripts/discover_db_lineage.py --target-dir <path-to-repo> [--output <report.md>] [--format md|json]
+   ```
+   - Automatically parses `.env*` files in the target repository.
+   - Connects using `LinkedUser` or Windows Auth fallback.
+   - Queries `INFORMATION_SCHEMA`, `sys.procedures`, and `sys.servers`.
+   - Analyzes local codebase ORM models and background worker scripts.
+   - Outputs the standardized 7-column lineage table and Mermaid diagram.
+
+2. **Standalone Lineage Confluence Export (`--lineage-only` switch):**
+   ```powershell
+   python scripts/convert_hla_to_confluence.py <path-to-hla.md> --lineage-only [--output <lineage.html>]
+   ```
+   - Extracts only Section 4.5 from the HLA markdown file.
+   - Emits self-contained Confluence Storage Format XHTML with the horizontal stacked PlantUML diagram and wrapped 7-column table.
+   - Ideal for pasting solely the database pipeline architecture into team documentation.
+
+---
+
+## 4. PlantUML Diagram Standards & Material Design Palette
+
+Confluence natively renders PlantUML without external image dependencies. Follow these styling and layout rules:
+
+### 4.1 Google Material Design Corporate Palette
+
+Never use default bright or garish PlantUML colors. Use muted corporate Material tones:
+
+| Layer / Role | Hex Stroke | Hex Fill | Hex Text | Skinparam Target |
+|---|---|---|---|---|
+| **Client / User Web Browser** | `#3949AB` | `#E8EAF6` | `#1A237E` | `skinparam rectangle<<user>>` / `skinparam actor` |
+| **Web Server / Reverse Proxy** | `#455A64` | `#ECEFF1` | `#263238` | `skinparam rectangle<<proxy>>` |
+| **App Services / Worker** | `#00695C` | `#E0F2F1` | `#004D40` | `skinparam rectangle<<service>>` |
+| **API Gateway (Apigee)** | `#E65100` | `#FFF3E0` | `#BF360C` | `skinparam queue<<gateway>>` |
+| **Databases / Staging Queues** | `#0277BD` | `#E1F5FE` | `#01579B` | `skinparam database<<db>>` |
+| **External Core Telemetry APIs** | `#C2185B` | `#FCE4EC` | `#880E4F` | `skinparam rectangle<<telemetry>>` |
+| **Artificial Intelligence / LLM** | `#6A1B9A` | `#F3E5F5` | `#4A148C` | `skinparam rectangle<<model>>` |
+| **Feedback / RLHF Audit** | `#2E7D32` | `#E8F5E9` | `#1B5E20` | `skinparam database<<rlhf_db>>` |
+
+### 4.2 Layout Rules: 90-Degree Orthogonal Routing & Horizontal Stacked Layers
+
+1. **Mandate 90-Degree Orthogonal Connections (`skinparam linetype ortho`):**
+   - Always include `skinparam linetype ortho` in structural PlantUML diagrams (Topology, DB Lineage, Summarization Pipeline).
+   - Standard Graphviz splines create curved diagonal arcs that slice through package boundaries. Orthogonal routing forces clean Manhattan routing: all connections consist strictly of horizontal and vertical segments with 90° bends.
+   - Do NOT use `skinparam handwritten false` (triggers an unwanted yellow warning banner in modern PlantUML).
+
+2. **Horizontal Flow Stacked in Functional Layers (DB Lineage Pipeline):**
+   - Do NOT draw the DB Lineage pipeline as a single, tall vertical strip.
+   - Structure the pipeline as horizontal flows stacked in functional layers:
+     - **Layer 1 (Upstream Ingestion & Telemetry Enrichment):** `SourceDB` -> `PendingDB` -> `InputDB` connected via `-right->`.
+     - **Layer 2 (AI Summarization & Triage Inference):** `LLM` -> `RecDB` connected via `-right->`.
+     - **Layer 3 (Screener Review & Continuous Learning / RLHF):** `UI` -> `FeedbackDB` connected via `-right->`.
+     - Stack layers vertically using `L1 -[hidden]down- L2` and `L2 -[hidden]down- L3`.
+     - Connect inter-layer steps vertically: `InputDB -down-> LLM : 3. Case Prompts` and `RecDB -down-> UI : 5. Present to Queue`.
+     - Keep edge labels concise (`1. Extract`, `2. Ingest`, `4. Predict`, `6. Feedback`) with `skinparam nodesep 80` to prevent label collision with box borders.
+
+3. **Horizontal Flow with Stacked Multi-Track Inputs (Summarization Pipeline):**
+   - Do NOT draw summarization pipelines as single vertical columns.
+   - Structure as a 3-stage left-to-right pipeline:
+     - **Stage 1 (Left):** Multiple input tracks (e.g., Track A: Network Health, Track B: Case History, Track C: Account Profile) stacked vertically (`TrackA -[hidden]down- TrackB`), with each track flowing horizontally left-to-right (`N1 -right-> N2 -right-> NSum`).
+     - **Stage 2 (Middle):** Language Model Synthesis Engine (`LLMEngine`), receiving 90-degree orthogonal connections from each track's summary node (`NSum -right-> LLMEngine`, etc.).
+     - **Stage 3 (Right):** Action Recommendation & Justification (`RecOutput`), receiving a horizontal connection from `LLMEngine`.
+
+4. **Component-to-Component Connections in System Topology:**
+   - Connect internal component nodes directly (e.g., `Worker -down-> SQL`, `Worker -down-> Apigee`, `Worker -right-> LLM`).
+   - Do NOT connect package boundaries (e.g., `HostLayer -down-> MidLayer`), which inflates diagram bounding boxes and distorts routing.
+   - Use `skinparam nodesep 60` and `skinparam ranksep 50` for comfortable whitespace.
+
+5. **Diagram Parity: Mermaid in Markdown, PlantUML in Confluence:**
+   - Source `.md` documents MUST use standard Mermaid diagrams (`flowchart LR/TD`, `sequenceDiagram`) with subgraphs reflecting the horizontal/stacked layout so they render natively in Git repositories and Markdown viewers.
+   - The conversion tool (`convert_hla_to_confluence.py`) translates the diagrams into native Confluence PlantUML macros with orthogonal routing.
+
+6. **Mermaid Diagram Text Wrapping & Truncation Prevention in Markdown Documents:**
+   - **The Problem:** Standard Markdown viewers (GitHub, Azure DevOps, GitLab, VS Code, browsers) do NOT automatically wrap text inside Mermaid SVG elements (nodes, participant boxes, sequence notes, or message arrows). Long unwrapped strings stretch the SVG viewport to over 1500px, causing the diagram to truncate, hide labels off-screen, or force horizontal scrollbars.
+   - **The Rule:** In all Mermaid diagrams within `.md` documents, **always enforce explicit linebreaks using `<br/>`** to keep lines compact (maximum ~35 to 45 characters per line):
+     - **Sequence Participants & Actors:** Wrap role and system names across lines:
+       ```mermaid
+       actor Agent as Contact Center<br/>Agent
+       participant UI as React 19 UI<br/>(Port 5701)
+       database DB as SQL Server<br/>(IEGEW3CCDR01)
+       ```
+     - **Sequence Notes:** Wrap multi-line explanations:
+       ```mermaid
+       Note over DB: UiPath bot inbox loads Pega & ServiceNow<br/>reports into dbo.L30D* tables
+       ```
+     - **Sequence Message Labels:** Break long method descriptions, endpoints, or query details:
+       ```mermaid
+       ETL->>SF: Query Genesys calls & NPS<br/>via SNOWFLAKE_GENESYS (06:00 UTC)
+       ```
+     - **Flowchart Node Labels:** Structure host, database, tables, and jobs onto distinct lines:
+       ```mermaid
+       PegaStaging["Pega & ServiceNow via UiPath Inbox<br/>DB: SERVSIGHT<br/>dbo.L30DInteractions, Cases,<br/>dbo.L30DSNOW, Webforms<br/>[SQL Agent: Daily_AI_*_L30D]"]:::srcStyle
+       ```
+     - **Flowchart Edge Labels:** Wrap action descriptions to avoid wide gaps and node label collisions:
+       ```mermaid
+       LLMContext -->|"5. Poll Queue &<br/>Context (TDS 1433)"| AISummaryGen
+       ```
+   - **Converter Parity:** The Confluence converter (`convert_hla_to_confluence.py`) dynamically translates `<br/>` and `<br>` into `\n` in PlantUML sequence notes, messages, nodes, and edge labels, guaranteeing that both Markdown and Confluence XHTML display full, untruncated text with zero literal `<br/>` syntax errors.
+
+7. **Legacy PlantUML Engine Compatibility (Stereotypes After Aliases):**
+   - **The Problem:** Enterprise Confluence installations commonly run older PlantUML plugin versions (such as PlantUML 1.2022.1). In these versions, placing stereotypes immediately after element types (e.g. `rectangle<<user_ui>> "Label" as Alias`) triggers a fatal `Syntax Error?` on render.
+   - **The Rule:** In all generated PlantUML code, **always place the stereotype at the very end after the alias**:
+     ```plantuml
+     rectangle "Contact Center Agent Browser\n(Customer Care & Retention Teams)" as Browser <<user_ui>>
+     database "SQL Server Database (SERVSIGHT)\nEvent Spine & Context Store" as ServSightDB <<staging_db>>
+     queue "Linked Server Gateway\n(SNOWFLAKE_GENESYS / MSDASQL)" as LinkedServer <<gateway>>
+     ```
+8. **Anti-Slop and Em-Dash Prohibition in PlantUML and Text:**
+   - **Zero Em-Dashes (`—`) or En-Dashes (`–`):** Never include em-dashes in sequence diagram step descriptions, participant names, note boxes, flowchart nodes, or edge labels. Use colons (`:`) or hyphens (`-`).
+   - **Clean ASCII Strings:** Do not use unicode bullet points (`•`), curved apostrophes (`’`), or fancy quotation marks (`“”`). Use ASCII straight apostrophes and quotes.
+   - **No Markdown Wildcard Collisions:** Protect code identifiers containing asterisks (`*`) so they do not collide with italic formatting during export.
+
+---
+
+## 5. End-to-End Execution Workflow
+
+### Step 1: Research the Target Codebase
+Inspect the target codebase across five dimensions:
+1. **User Interface:** Framework (React, Vue, Vite), authentication flow, role capabilities.
+2. **Backend Services & Gateways:** Endpoints, worker tasks, integration gateway (Apigee, reverse proxy, loopback ports).
+3. **Data & Pipeline Layer:** Discover the 7-stage DB pipeline (Source Host.DB.Table -> Staging -> Feature Input -> LLM -> Recommendations -> UI -> Feedback/RLHF). If unverified, ask the user.
+4. **Integration APIs:** Telemetry endpoints, external incident checkers, OAuth2 flows.
+5. **Security & Perimeter:** Authentication mechanism, RBAC groups, network boundaries, data minimization.
+
+### Step 2: Author Markdown HLA (`docs/hla/<slug>/<slug>-hla.md`)
+- Write using the 7-section canonical structure in Simplified Technical English.
+- Author PlantUML (or Mermaid) diagram blocks for:
+  1. Sequence diagram
+  2. System topology diagram
+  3. Multi-track summarization pipeline
+  4. End-to-end database and processing pipeline (Section 4.5)
+- Document the Screener Feedback Service and RLHF loop (Section 4.6).
+- Maintain internal working references under section 7.2.
+- **Do NOT add any Document Notice or STE preamble.**
+- **Strictly eliminate all em-dashes (`—`), en-dashes (`–`), smart quotes, and AI buzzwords.**
+
+### Step 3: Convert to Confluence XHTML (`docs/hla/<slug>/<slug>-hla.html`)
+Run the bundled converter script:
+```powershell
+python scripts/convert_hla_to_confluence.py docs/hla/<slug>/<slug>-hla.md
+```
+Or execute the script from the skill directory:
+```powershell
+python <path-to-skill>/scripts/convert_hla_to_confluence.py docs/hla/<slug>/<slug>-hla.md
+```
+
+The converter automatically:
+1. Strips YAML frontmatter completely.
+2. Strips `7.2 Reference Documents` and any internal repository paths.
+3. Purges all preparation notices, STE statements, and AI/agent metadata.
+4. Escapes all XML entities (`&amp;`, `&lt;`, `&gt;`) inside table cells and text.
+5. Replaces Markdown TOC with native `<ac:structured-macro ac:name="toc"/>`.
+6. Wraps tables in `<table class="wrapped">` with explicit column specifications.
+7. Translates diagrams into self-contained PlantUML macros with Google Material Design corporate styling.
+8. Converts all em-dashes (`—`) and en-dashes (`–`) to colons (`:`) or hyphens (`-`).
+9. Normalizes smart quotes (`“”‘’`) and unicode bullets (`•`) to clean ASCII.
+10. Scrubs prohibited AI buzzwords, hyperbolic clichés, and meta-commentary.
+11. Validates XML well-formedness before saving.
+
+### Step 4: Verification and Confluence Import
+1. Verify terminal reports: `XHTML validation successful: Content is well-formed XML.`
+2. Copy the entire contents of the `.html` file.
+3. Open Confluence, create or edit the target architecture page, open the **Confluence Source Editor** (`< >` icon), paste the XHTML, and click **Apply**.
+4. The page immediately renders all tables and PlantUML diagrams natively—zero attachments or extra setup required.