` pages in the source — read far enough. - Preserve exact technical values (resolutions, distances, quantities) without rephrasing. - Do not invent a document number if the source uses an em dash placeholder. ### Section §-linking in formal HTML docs When building or editing formal project HTML documents, all internal section references (`§1.2`, `§7.0`, `§9`, etc.) must be clickable anchor links that match the document's section IDs. Use: ```html §7.0 ``` The `text-decoration:none;color:inherit` keeps the link invisible — no visual change from plain text, but clickable in digital format. Apply this to ALL CRP section references (not ROADMAP §, ER §, SoW §, or Contract § — those point to other documents). ## 5d. Verifying RFI/TQ Submission Status Against Registers **Trigger:** User asks "have we sent this RFI?" or "check RFI against project info" — verifying whether drafted RFIs were formally submitted as TQs (Technical Queries). ### The Core Problem RFI registers (.xlsx) frequently go **stale** — showing RFIs as "Open" or "Draft (HOLD)" long after they've been formally issued as TQ documents with Rev A status through Aconex. Never trust the register alone. ### Workflow 1. **Read the markdown drafts** — `FORMAL_RFI_NNN_*.md` files in the subcontractor's `06_RFIs/` folder. Note the questions, references, and "ready to submit" markers. 2. **Scan for issued PDFs** — Look for PDFs in the same `06_RFIs/` folder matching the RFI topic. Issued TQ PDFs follow the pattern: `طلب XXX - وصف · MOC-MUS-ASE-1A0-TQ-NNNN Rev A.pdf` 3. **Extract PDF metadata** — Use pdftotext to check the document header block: ```bash pdftotext "path/to/TQ-NNNN Rev A.pdf" - 2>/dev/null | head -30 ``` Look for: doc ref (`MOC-MUS-ASE-1A0-TQ-NNNN Rev A`), issue date, status line (`Issued to CG` / `Issued to Employer`), document control block with `Rev A`. 4. **Compare draft vs submitted content** — Extract the PDF body and compare against the markdown draft: ```bash pdftotext "path/TQ-NNNN Rev A.pdf" - 2>/dev/null | tail -100 ``` Match question headings, numbered items, and reference citations (SOW, ER, Briefing Pack references). Bilingual PDFs embed English alongside Arabic — search for unique English phrases. 5. **Cross-reference against RFI Register** — Read the register data sheet: Check status column, linked TQ column, and dates against actual submission. 6. **Report discrepancies** — Compact table with: Draft RFI, TQ Issued, Register Status, Accurate? (Y/N). ### Key Detection Patterns | Register Status | PDF Evidence | Conclusion | |----------------|-------------|------------| | "Open" / "Draft" | TQ-NNNN Rev A, "Issued to" | Register stale — update to Issued/Awaiting Response | | "Open" / "Draft" | No matching TQ PDF | Not yet sent — draft is still internal | | Blank TQ column | TQ-NNNN Rev A exists | Register missing linked TQ ref | ### Pitfalls - Register mtime is not reliable — recent changes may be formatting, not status - TQ PDFs may be in `05_Returned_Submittals/` or master archive, not `06_RFIs/` - TQ numbers may skip — don't assume gaps - Bilingual PDFs confuse text extraction — search for unique English identifiers - Internal RFIs never get TQ numbers - Master register copy vs per-subcontractor copy may have different column structures ### June 2026 Example (Graphics Contractor) - RFI-003 Scope Boundary → TQ-0027 Rev A PDF existed in folder, register showed "Open" — **NOT actually issued via Aconex.** PDF was a prepared draft awaiting PM approval. - RFI-004 MoC Content → TQ-0028 Rev A PDF existed, register showed "Draft (HOLD)" — **NOT actually issued.** Drafted but never submitted. - Folder `03_Graphics_Contractor` but docs all reference "Sub-08" - **Lesson: Rev A on a PDF does not mean formally issued.** Verify through Aconex trail or PM confirmation before marking as Issued. ## 5e. Pre-Issue QA Review of Formal RFIs/TQs **Trigger:** User asks to review draft RFI/TQ before issue — or corrects a mistake in one (invented citation, wrong route, missing doc ref). Before any formal RFI/TQ is submitted via Aconex, run a 3-domain quality review using the template at `references/rfi-tq-qa-review-template.md`: ### Domain 1 — Format & Document Control Check: fonts (Noto Naskh Arabic / Carlito / JetBrains Mono), RTL, bilingual labels, logo strip (all 4 parties), doc-control block, RFI ref number, revision history, QC sign-off, footer pagination, status consistency. ### Domain 2 — Content vs Project Information **Critical: Verify every contractual quotation against the source document.** This session found Evidence D (ER §1.3) contained entirely invented text. Check: - SOW §2.2, §8.1, §8.14, p.17 against the actual SOW PDF - ER citations — especially §1.3 (scope overview, NOT scenographer coordination) - Briefing Pack M2 — AR primary, native typographer, curator-reviewer sign-off - Programme dates against current baseline - Gallery codes against official list (G6=Saudi Art, G8=Al Qatt) ### Domain 3 — Communication & Stakeholder Plan Routing, distribution, POCs, response deadline, register logging, WITHOUT PREJUDICE clause. ### Output Findings table (Pass/Fail/Flag per check) + verdict (Issue / Issue-with-corrections / Do-not-issue). ### Pitfalls - **ER §1.3 does NOT contain scenographer coordination language** — confirmed in June 2026 review, invented text - **RFI ref numbers often missing** — HTML covers lack formal TQ-XXXX ref - **"High priority" ≠ response deadline** — required-by date must be stated - **Distribution often omits the Curator** — content RFIs need Curator on distribution per ER §2.2 - **No WITHOUT PREJUDICE clause** — scope-boundary RFIs need rights-reservation language per Comm Plan - **Response deadlines may not carry from markdown to HTML** — check the HTML before calling review done ## 6. Verifying Plan Document References Against the Register Log **Trigger:** Before publishing or submitting any plan/procedure revision, verify all document references (doc numbers, revisions, statuses) against the Register Log. ### Workflow 1. **Open the Register Log** — located at the project's `_MANAGER_DASHBOARD/` area or shared drive. The log has multiple sheets (tabs). 2. **Navigate to the `Document Submittals` tab** — this is the authoritative list of all submitted documents with their official document numbers, titles, and types. 3. **Extract the log's doc reference data** using Python/openpyxl (or delegate to a subagent). Get all rows with their doc numbers, descriptions, and types. 4. **Cross-reference every doc ref in the plan** against the log: - Match plan's cited doc ref → log entry by number - Verify the title/description matches (confirm it's the same document, not just same prefix) - If the plan says `MOC-ASEER-GN-DS-006` and log says the same → correct - If the plan says `PL-0010` and log says `PL-0010` → correct 5. **Check HSE/plan refs carefully** — The main HSE Plan (PL-0010) is different from individual HSE Plans (e.g., `1KH-PL-0040` = Site Security Management Plan, not the HSE Plan). Verify the description matches. 6. **Fix discrepancies** — If a doc ref in the plan doesn't match the log, update the plan to use the log's number. ### Key Patterns from the Aseer Register Log | Pattern | Meaning | Examples | |---------|---------|---------| | `MOC-MUS-ASE-1K0-PL-NNNN` | Current convention (multi-discipline Plans) | PL-0029 = DMP | | `MOC-ASEER-SIC-1K0-PL-NNNN` | Older convention (still valid, used for earlier docs) | PL-0010 = HSE Plan, PL-0015 = BEP | | `MOC-MUS-ASE-1KH-PL-NNNN` | HSE-specific Plans | PL-0040 = Site Security Plan | | `MOC-ASEER-GN-DS-006` | Master Programme (Time Schedule) — NOT PL- series | | ### Old vs Current Naming Convention Documents numbered before ~PL-0028 use `MOC-ASEER-SIC-1K0-...` (older convention). Documents numbered after ~PL-0028 use `MOC-MUS-ASE-1K0-...` (current convention). Both are valid — use what the Register Log says for each document. ### Pitfalls - The Register Log does NOT contain plan/procedure document numbers until they've been submitted. Unsubmitted plans use `—` (em dash) as their reference. - The Document Submittals tab only covers documents that have been formally submitted to the CDE. Internal documents won't appear. - Some document numbers from the Register Log may not match filenames on the filesystem — the log is authoritative for the plan's reference section. - The HSE Plan (`PL-0010`) and individual HSE specialist plans (`1KH-PL-0040` onwards) are different documents. Don't conflate them. ## 5d. Verifying RFI/TQ Submission Status Against Registers **Trigger:** User asks "have we sent this RFI?" or "check RFI against project info" — verifying whether drafted RFIs were formally submitted as TQs (Technical Queries). ### The Core Problem RFI registers (.xlsx) frequently go **stale** — showing RFIs as "Open" or "Draft (HOLD)" long after they've been formally issued as TQ documents with Rev A status through Aconex. Never trust the register alone. ### Workflow 1. **Read the markdown drafts** — `FORMAL_RFI_NNN_*.md` files in the subcontractor's `06_RFIs/` folder. Note the questions, references, and "ready to submit" markers. 2. **Scan for issued PDFs** — Look for PDFs in the same `06_RFIs/` folder matching the RFI topic. Issued TQ PDFs follow the pattern: `طلب XXX - وصف · MOC-MUS-ASE-1A0-TQ-NNNN Rev A.pdf` 3. **Extract PDF metadata** — Use pdftotext to check the document header block: ```bash pdftotext "path/to/TQ-NNNN Rev A.pdf" - 2>/dev/null | head -30 ``` Look for: doc ref (`MOC-MUS-ASE-1A0-TQ-NNNN Rev A`), issue date, status line (`Issued to CG` / `Issued to Employer`), document control block with `Rev A`. 4. **Compare draft vs submitted content** — Extract the PDF body and compare against the markdown draft: ```bash pdftotext "path/TQ-NNNN Rev A.pdf" - 2>/dev/null | tail -100 ``` Match question headings, numbered items, and reference citations (SOW, ER, Briefing Pack references). Bilingual PDFs embed English alongside Arabic — search for unique English phrases. 5. **Cross-reference against RFI Register** — Read the register data sheet: Check status column, linked TQ column, and dates against actual submission. 6. **Report discrepancies** — Compact table with: Draft RFI, TQ Issued, Register Status, Accurate? (Y/N). ### Key Detection Patterns | Register Status | PDF Evidence | Conclusion | |----------------|-------------|------------| | "Open" / "Draft" | TQ-NNNN Rev A, "Issued to" | Register stale — update to Issued/Awaiting Response | | "Open" / "Draft" | No matching TQ PDF | Not yet sent — draft is still internal | | Blank TQ column | TQ-NNNN Rev A exists | Register missing linked TQ ref | ### Pitfalls - Register mtime is not reliable — recent changes may be formatting, not status - TQ PDFs may be in `05_Returned_Submittals/` or master archive, not `06_RFIs/` - TQ numbers may skip — don't assume gaps - Bilingual PDFs confuse text extraction — search for unique English identifiers - Internal RFIs never get TQ numbers - Master register copy vs per-subcontractor copy may have different column structures ### June 2026 Example (Graphics Contractor) - RFI-003 Scope Boundary → TQ-0027 Rev A PDF existed in folder, register showed "Open" — **NOT actually issued via Aconex.** PDF was a prepared draft awaiting PM approval. - RFI-004 MoC Content → TQ-0028 Rev A PDF existed, register showed "Draft (HOLD)" — **NOT actually issued.** Drafted but never submitted. - Folder `03_Graphics_Contractor` but docs all reference "Sub-08" - **Lesson: Rev A on a PDF does not mean formally issued.** Verify through Aconex trail or PM confirmation before marking as Issued. ## 5e. Pre-Issue QA Review of Formal RFIs/TQs **Trigger:** User asks to review draft RFI/TQ before issue — or corrects a mistake in one (invented citation, wrong route, missing doc ref). Before any formal RFI/TQ is submitted via Aconex, run a 3-domain quality review using the template at `references/rfi-tq-qa-review-template.md`: ### Domain 1 — Format & Document Control Check: fonts (Noto Naskh Arabic / Carlito / JetBrains Mono), RTL, bilingual labels, logo strip (all 4 parties), doc-control block, RFI ref number, revision history, QC sign-off, footer pagination, status consistency. ### Domain 2 — Content vs Project Information **Critical: Verify every contractual quotation against the source document.** This session found Evidence D (ER §1.3) contained entirely invented text. Check: - SOW §2.2, §8.1, §8.14, p.17 against the actual SOW PDF - ER citations — especially §1.3 (scope overview, NOT scenographer coordination) - Briefing Pack M2 — AR primary, native typographer, curator-reviewer sign-off - Programme dates against current baseline - Gallery codes against official list (G6=Saudi Art, G8=Al Qatt) ### Domain 3 — Communication & Stakeholder Plan Routing, distribution, POCs, response deadline, register logging, WITHOUT PREJUDICE clause. ### Output Findings table (Pass/Fail/Flag per check) + verdict (Issue / Issue-with-corrections / Do-not-issue). ### Pitfalls - **ER §1.3 does NOT contain scenographer coordination language** — confirmed in June 2026 review, invented text - **RFI ref numbers often missing** — HTML covers lack formal TQ-XXXX ref - **"High priority" ≠ response deadline** — required-by date must be stated - **Distribution often omits the Curator** — content RFIs need Curator on distribution per ER §2.2 - **No WITHOUT PREJUDICE clause** — scope-boundary RFIs need rights-reservation language per Comm Plan - **Response deadlines may not carry from markdown to HTML** — check the HTML before calling review done ## 6. Verifying Plan Document References Against the Register Log **Trigger:** Before publishing or submitting any plan/procedure revision, verify all document references (doc numbers, revisions, statuses) against the Register Log. ### Workflow 1. **Open the Register Log** — located at the project's `_MANAGER_DASHBOARD/` area or shared drive. The log has multiple sheets (tabs). 2. **Navigate to the `Document Submittals` tab** — this is the authoritative list of all submitted documents with their official document numbers, titles, and types. 3. **Extract the log's doc reference data** using Python/openpyxl (or delegate to a subagent). Get all rows with their doc numbers, descriptions, and types. 4. **Cross-reference every doc ref in the plan** against the log: - Match plan's cited doc ref → log entry by number - Verify the title/description matches (confirm it's the same document, not just same prefix) - If the plan says `MOC-ASEER-GN-DS-006` and log says the same → correct - If the plan says `PL-0010` and log says `PL-0010` → correct 5. **Check HSE/plan refs carefully** — The main HSE Plan (PL-0010) is different from individual HSE Plans (e.g., `1KH-PL-0040` = Site Security Management Plan, not the HSE Plan). Verify the description matches. 6. **Fix discrepancies** — If a doc ref in the plan doesn't match the log, update the plan to use the log's number. ### Key Patterns from the Aseer Register Log | Pattern | Meaning | Examples | |---------|---------|---------| | `MOC-MUS-ASE-1K0-PL-NNNN` | Current convention (multi-discipline Plans) | PL-0029 = DMP | | `MOC-ASEER-SIC-1K0-PL-NNNN` | Older convention (still valid, used for earlier docs) | PL-0010 = HSE Plan, PL-0015 = BEP | | `MOC-MUS-ASE-1KH-PL-NNNN` | HSE-specific Plans | PL-0040 = Site Security Plan | | `MOC-ASEER-GN-DS-006` | Master Programme (Time Schedule) — NOT PL- series | | ### Old vs Current Naming Convention Documents numbered before ~PL-0028 use `MOC-ASEER-SIC-1K0-...` (older convention). Documents numbered after ~PL-0028 use `MOC-MUS-ASE-1K0-...` (current convention). Both are valid — use what the Register Log says for each document. ### Pitfalls - The Register Log does NOT contain plan/procedure document numbers until they've been submitted. Unsubmitted plans use `—` (em dash) as their reference. - The Document Submittals tab only covers documents that have been formally submitted to the CDE. Internal documents won't appear. - Some document numbers from the Register Log may not match filenames on the filesystem — the log is authoritative for the plan's reference section. - The HSE Plan (`PL-0010`) and individual HSE specialist plans (`1KH-PL-0040` onwards) are different documents. Don't conflate them. ## 7. Document Content Rules & Style Guardrails When authoring or editing project documents (plans, reports, method statements), always follow `references/document-content-rules.md`. Key rules to keep in mind: ### Cover Page & Front Matter - **Document Number**: Leave as `—` (em dash) until the Document Controller assigns it. Never use placeholder "XX" or "TBD" as a doc ref on the cover. - **REF line**: Omit entirely if no number has been assigned. Do not write `REF: MOC-...-XX`. - **Revision/CG Review text**: Keep on the cover's content card (e.g., "Issued for CG Review" + "REVISION C02"), not as a standalone footer block. - **Logos**: Center them full-width at the bottom of the cover, using `justify-content:space-between` on a `width:100%` flex container. Labels should be short ("Consultant" not "Consultant (CG)"). ### Self-Incriminating Language Never write anything that could be used to claim Samaya is failing an obligation: - ❌ `TBC — ⚠ CRITICAL PATH` - ✅ `TBC` - Avoid: "CRITICAL PATH", "delayed", "behind schedule", "at risk", "failure", "deficiency", "problem" re Samaya's own performance. - Use neutral terms: "pending", "in progress", "to be confirmed", "awaiting". ### Named Persons & Firms - Unless a name/firm appears in an approved KPR or approved submittal, use `—` or a generic description. - Never name unapproved consultants: ❌ "Dr. Ehab Foda — LEED / Mostadam", ❌ "Lumotion". - ✅ Generic: "Sustainability Strategy — per ER", "Interactive Applications — prequalification in progress". - If the user corrects you once on a name, persist that correction — don't reintroduce the name later in the same session. ### Materials Section Use only generic material descriptions — no brand names: - ❌ `Porcelain & mosaic tiles (Ceramiche Piemme), carpet (Tarkett), acoustic panels (Kvadrat)` - ✅ `Porcelain & mosaic tiles, carpet, acoustic panels` Exception: Specialist subcontractor firm names in Tier 2/Appendix B tables are fine for scope identification. ### Role Accuracy - Mohamed Mostafa = **Technical Office Mechanical Engineer**, not BIM modeler - Electrical Engineer = on site (not HO) — drop "(HO)" suffix - Junior engineer names should not appear in the plan **Use the canonical workflow in `samaya-technical-office/references/subcontractor-creation-workflow.md`** — it is the single source of truth and is more detailed than what's below. The summary here is a quick reference; defer to the canonical workflow for the full process. ### Quick reference 1. Find next available number (check `Subcontractors/` folder listing) 2. Create 9 standard subdirs: `01_Schedule_and_BOQ/`, `02_Reference_Drawings/`, `03_Specifications_and_Standards/`, `04_Reference_Imagery/`, `05_Returned_Submittals/`, `06_RFIs/`, `07_Approvals/`, `Email_Data_Extraction/`, `_MANAGER_DASHBOARD/` 3. Write `_MANAGER_DASHBOARD/SCOPE_REQUEST.md` using the **Samaya standard 10-section template** (see canonical workflow for exact structure) 4. Generate `SCOPE_REQUEST.docx` at sub root using `samaya-docx-template` (SamayaDoc class) 5. Create `_MANAGER_DASHBOARD/SITUATION_REPORT.md` + `_MANAGER_DASHBOARD/_Email_Draft_to_find_lab.md` 6. Search entire project for related docs and **copy** them into the appropriate subdirs 7. Verify every file path referenced in the SOW actually exists in the subfolder 8. Update `README.md` register with new row ### Key rules (from canonical workflow) - **All `.md` files go in `_MANAGER_DASHBOARD/`** — never at sub root. Only root file is `SCOPE_REQUEST.docx`. - **Status docs require physical file verification** — A claim of "submitted" in a status doc (CG_STATUS.md, any _STATUS.md) is NOT ground truth. Always check for the actual PDF submission package in `01_Source_Files/02_PDFs/`. Sidecar status files can be prematurely written or incorrect. - **SCOPE_REQUEST.md must be original** — structure is reusable, content is trade-specific. - **Reference files must exist** — SOW can only list files actually in the subfolder. - **Duplicate numbering**: keep first sub at `NN_Name`, suffix the newer one (`NNa_` trade, `NNb_` vendor). - **Formal DOCX uses SamayaDoc template** — import from `samaya_doc_template.py`. - **SOW cites only approved source docs** — never infer scope. Omit or flag TBC. - **Supplier cert ≠ independent test** — flag this distinction. ## 2b. Standardizing a plan document folder structure **Pattern:** `02_Plans_and_Procedures/02.{NN}_{Name}/` Use when setting up or expanding a plan/procedure document folder (e.g., 02.17_Risk_Management_Plan). Follow the canonical structure in `references/plan-document-folder-structure.md`. ### Quick steps 1. Identify the next `02.{NN}` number from sibling folders 2. Create the 11-standard-entry hierarchy (see reference) 3. Write `README.md` with folder-purpose table and key-documents list 4. If source files already exist (`01_Source_Files/`), leave them in place — just add the missing subfolders ### Template README format ```markdown # 02.{NN} {Name} — Aseer Museum ## Folder Structure | Folder | Description | |--------|-------------| | `00_Master_Index/` | Index & version control | | `01_Source_Files/01_HTML/` | HTML master document | | `01_Source_Files/02_PDFs/` | Signed/stamped PDF copies | | ... | ... ## Key Documents - **Master Source:** `01_Source_Files/aseer_{name}.md` - **HTML Render:** `01_Source_Files/01_HTML/aseer_{name}.html` ``` ## 3. Drafting project correspondence ### Email rules - **NRS emails**: only items NRS must act on. Remove any mention of Samaya-internal actions. When forwarding a CRS, filter out contractor-side items (cloud survey, mock-ups, demolition, BIM coordination) — only send design-scope items (title blocks, showcase design, missing dimensions, space labeling). - **PM emails**: separate NRS-action list from Samaya-team-action list clearly. - Save drafts as `.md` in `Correspondence/draft_email_{recipient}_{topic}.md` for review before sending. - Never ask NRS to decide something the contract/spec already defines — NRS suggestions are flags, not decision requests. ### Subcontractor quotation review workflow When reviewing a quotation/proposal against contract documents (ER, SOW, DMP), see `subcontractor-folder-setup/references/subcontractor-quotation-review.md` for the full 7-phase workflow: extract quote from email → cross-reference → baseline selection → gap classification → payment alignment → document pack → correspondence. ## 4a. Batch-Processing Prequalification Submittals (PQ Files) **Trigger:** User sends multiple PQ PDFs at once (via chat, drag-drop, or email) — typically 5–20 files in a batch. ### Workflow 1. **Extract all PDFs to text** in parallel: ```bash for f in *.pdf; do pdftotext -layout "$f" "/tmp/${f%.pdf}.txt" 2>&1 | tail -1; done ``` 2. **Read the cover page** (first 30 lines) of each text file to identify: - Subcontractor/supplier name - Discipline code (1A0=Arch, 1C0=Civil, 1E0=Elec, 1M0=Mech, 1K0=General) - CG status code (A/B/C/D) — look for the status stamp near the top - Submittal date - Description/scope - **Contract number** — verify it matches the project (Aseer = 0010003521). Flag mismatches. 3. **Detect CG status unreadability**: If pdftotext produces garbled/encoded text (Arabic glyphs rendered as Latin characters, or the status line is unreadable), the CG code may be embedded in a non-extractable font. Flag to user: *"CG status unreadable via text extraction — open PDF visually to confirm A/B/C/D."* 4. **Detect duplicates and near-duplicates**: - Same scope from different suppliers (e.g., Rajhi Steel + ALSSAD Steel both for "Reinforcement steel") — both are valid, file both - Same submittal number with different content — flag as potential duplicate - Same date + same description — likely duplicate upload 5. **Detect incomplete downloads**: Files ending in `.crdownload` or with suspicious sizes (e.g., 113MB for a PQ) — check with `file` command. If it's a PDF but pdftotext fails, it's incomplete. Advise user to re-download. 6. **Determine filing location** per discipline code: | Code | Discipline | OneDrive Target | Doc Control Mirror | |------|-----------|-----------------|-------------------| | `1A0` | Architecture | `02_Submittals/09_Prequalifications/` | `04_Submittals/Architecture/` | | `1C0` | Civil/Structural | `02_Submittals/09_Prequalifications/` | `04_Submittals/Structure/` | | `1E0` | Electrical | `02_Submittals/09_Prequalifications/` | `04_Submittals/Electrical/` | | `1M0` | Mechanical | `02_Submittals/09_Prequalifications/` | `04_Submittals/Mechanical/` | | `1K0` | General | `02_Submittals/09_Prequalifications/` | `04_Submittals/General/` | **Note**: All PQ files go to the same OneDrive folder (`09_Prequalifications/`). The discipline subfolder in Doc Control is for quick-reference mirroring only. 7. **Cross-reference against existing registers** before filing: - Check if the supplier already has a PQ entry in the relevant register - Check if the same PQ number already exists in the target folder - If a PQ file already exists in the target folder with the same number, compare sizes and dates — the newer one may be a resubmission 8. **File the PDFs** — copy to OneDrive target first, then mirror to Doc Control working copy 9. **Update registers** — append rows to the relevant submittal register (Arch, Elec, Mech, Structural, or General) with: PQ number, supplier, scope, date, CG status (or "TBC" if unreadable) 10. **Update memory** with a compact summary table of all processed PQs ### Prequal Compliance Assessment & Gap-Filling **Trigger:** User sends prequal documents for a supplier and asks "are they compliant?" or "can they pass?" — evaluating a supplier against a specific SOW's prequalification requirements (§5). #### Workflow 1. **Read the SOW prequal requirements** (§5 of the relevant SOW) — extract mandatory certifications, experience minimums, technical capabilities, and submittal package items. 2. **Map supplier's submitted docs** against each requirement in a compliance table: - ✅ Pass — requirement met - ❌ Missing — not provided - ⚠️ Partial — partially met or TBC 3. **Classify gaps into three tiers:** | Tier | Description | Verdict | |------|-------------|---------| | **Waivable** | ISO certs, BIM capability, fire/GREENGUARD knowledge — common for KSA establishments, CG may accept track record instead | Likely pass with conditions | | **Negotiable** | Museum project count (2 of 3 if cultural venues), team CVs if strong lead | Partial — needs framing | | **Blocker** | Missing methodology, programme, team CVs per SOW §5.4 | Must provide | 4. **Give a practical verdict** — not just pass/fail, but "can they pass with conditions" and what's needed. 5. **Offer to generate missing docs** — if the supplier lacks methodology and/or programme, generate them using the SOW as reference: - **Methodology doc**: Map each SOW scope section to a technical approach section. Use the supplier's actual equipment, tools, and team where known from their profile. Cover: assessment methodology, design methodology, commissioning, quality management, team capabilities. - **Programme doc**: Extract deliverables from SOW §3 (Deliverables by Stage), map to phases with dates from the project's Design Phase Master Programme. Include: programme summary table, deliverable schedule, coordination dependencies, assumptions. - **Format**: Generate as DOCX (user preference — editable) using SamayaDoc template. PDF also acceptable as secondary format. 6. **File both docs** in the supplier's prequal folder and update the register's "Docs Filed" column. #### Pitfalls - **Don't overstate compliance** — If the supplier has 0 museum projects, say so. Don't soften the gap. - **Methodology must use the supplier's actual tools** — Don't invent equipment they don't have. Extract from their profile. - **Programme dates must align with project baseline** — Use the Design Phase Master Programme (MOC-ASEER-0PS-SH-006), not invented T+X durations. - **DOCX is preferred over PDF** for editable documents the supplier may need to modify. Generate both if time allows. - **The generated docs are for the supplier to submit** — they are not Samaya deliverables. Mark them as draft/pending supplier review. - **CRITICAL: Subcontractor-facing DOCX must NOT use Samaya branding.** When generating methodology/programme docs FOR a subcontractor to submit TO Samaya, do NOT use the SamayaDoc template. Use standalone DOCX generation (raw python-docx) with the subcontractor's own logo and color scheme. The cover should say "Submitted to: Samaya Investment" and "Prepared by: [Subcontractor Name]". The user will correct you if you put Samaya branding on a subcontractor's submission document — it's their document, not Samaya's. ### Pitfalls - **CG status is often unreadable** — Many PQ PDFs use embedded fonts that pdftotext cannot decode. The status line (A/B/C/D) may appear as garbled text. Always flag this to the user rather than guessing. - **Contract number mismatch** — PQ-0006 in this session had contract 4800000960 instead of 0010003521 (Aseer). This may belong to a different Samaya project. Flag for verification. - **Same-scope PQs from different suppliers are both valid** — Don't deduplicate by scope alone. Multiple suppliers may be prequalified for the same material category (e.g., Rajhi Steel + ALSSAD Steel for reinforcement). - **Same submittal number + same date = duplicate** — Keep only one copy. The `(1)` suffix in filenames is a browser download artifact. - **Incomplete downloads** — `.crdownload` files that are PDFs but fail text extraction are incomplete. Delete and re-download. - **OneDrive sync blocks file operations** — Write to `/tmp/` first, then copy to OneDrive path. See section 1c for the workaround. - **Registers may not have a dedicated PQ column** — Some registers track PQs under "Submittal No." or "Type" columns. Check the register structure before appending. ## 4c. Processing Aconex Metadata Template Exports **Trigger:** User provides an Aconex Metadata Template export (.xlsx) or asks to check actual document statuses from Aconex. Aconex email notifications (WTRAN transmittals) are **notification-only** — they carry transmittal numbers but NO status codes. The actual A/B/C/D status is only available from: 1. CG response PDFs attached to the transmittal 2. The **Aconex Metadata Template export** — a system-generated .xlsx that lists every document registered in Aconex with its current status code ### Workflow 1. **Read the Metadata Template export** using `read_file` (auto-extracts openpyxl content to readable text) 2. **Identify the MetadataTemplate sheet** — contains columns: Document No, Revision, Title, Type, Status, Discipline, Floor, File, Revision Date, etc. 3. **Extract status codes** for each document — map the `Status` column value: - `A - Approved` / `B - Approved with Comments` / `C - Revise and Resubmit` / `D - Rejected` - `For Review` = pending CG assessment - `E - Review Not Required` = administrative only 4. **Cross-reference against WTRAN transmittal numbers** from Outlook notifications: - The Metadata Template export does NOT contain WTRAN numbers — it contains document numbers (e.g., MOC-MUS-ASE-1E0-ZD-0074) - To map WTRAN → status, match the document subject/description between the email notification and the Metadata Template - Example: CGP-WTRAN-000050 "Evaluation & Assessment for Master Clock" → MOC-MUS-ASE-1E0-ZD-0074 = **B — Approved w/ comments** 5. **Update the submittal register** with the actual status codes (replacing "—" placeholders) ### When to Request a Metadata Export - After a batch of WTRAN notifications arrives (10+ in a day) - When the user asks "what's the status on these submittals?" and you only have notification emails - Before building a status report or management plans Excel ### User Preference: Latest Status Only When presenting plan/submittal status data, show **only the latest revision per document** — not the full revision history. A single row per plan with its current status, date, and key notes. History is internal reference only. ### Status Color Coding for Excel Reports When building status Excel files in openpyxl: | Status | Color | Fill | |--------|-------|------| | A — Approved | Green | `C6EFCE` | | B — Approved w/ comments | Yellow | `FFEB9C` | | C — Revise & Resubmit | Orange | `FCD5B4` | | D — Disapproved | Red | `FFC7CE` | | For Review / Submitted | Blue | `BDD7EE` | | No CG response / Unknown | Gray | `D9D9D9` | ### Pitfalls - **Demo/test entries** — The Metadata Template may contain test data (e.g., `MOC-MUS-ASE-DEMO-0000`, `MOS-MUS-ASE-TEST`). Skip these by checking for `DEMO` or `TEST` in the doc number. - **Contract number mismatches** — Some PQs may belong to a different Samaya project (contract 4800000960 instead of 0010003521). Flag for verification. - **Status is unreadable via pdftotext** — Some CG response PDFs use embedded fonts that cannot be extracted. The Metadata Template is the fallback source. - **Metadata Template is a snapshot** — It reflects status at the time of export. New WTRAN notifications after the export date may have different statuses. - **Export file naming** — The file is typically named `TemplateMetadata-{DDMMMYYYY}_HH-MM-SS.xlsx` and comes from the user's Downloads folder. ## 4b. Processing Incoming Email Submissions (Batch Workflow) Trigger: user asks to process project emails — read, extract attachments, route to folders, update registers. ### Full workflow per email For each email with attachments: 1. **Read body** via `SELECT Message_Preview FROM Mail WHERE Record_RecordID = ` 2. **Extract attachments** via AppleScript (reliable — always use this, skip .olk15MsgAttachment binary parsing): ```bash osascript -e " tell application \"Microsoft Outlook\" set theMsg to message id $ID set atts to (every attachment of theMsg) set outFolder to \"/tmp/outlook_extracts/\" repeat with att in atts set attName to name of att set savePath to outFolder & \"${ID}_\" & attName do shell script \"touch \" & quoted form of savePath set saveFile to POSIX file savePath as alias save att in saveFile end repeat end tell" ``` 3. **Read attachment content** with `pdftotext` (poppler) — identify doc code, revision, approval status (Code A/B/C/D), CG reviewer 4. **Determine routing** from doc code prefix + discipline code (see routing table below) 5. **Save** to destination folder 6. **Update SITREP** in `_MANAGER_DASHBOARD/SITUATION_REPORT.md` if applicable 7. **Log** to `Email_Archive/_email_processing_log.md` ### Batch processing pattern For 10+ emails, use parallel sub-agents in batches of 3: ```python # Pattern: get IDs, extract all at once via shell loop, then route in Python # Step 1: Extract all in one batch for id in ID_LIST; do osascript ... done # Step 2: Read each PDF, determine routing # Step 3: Copy to destination folders ``` ### Aseer Document Code Routing Table Parse the doc code `MOC-MUS-ASE-{disc}{num}-{type}-{seq}`: | Discipline Code | Discipline | Default Routing | |----------------|------------|-----------------| | `1A0` | Architecture | `02_Submittals/Architecture/` or `Design Files/` | | `1C0` | Civil | Per doc-type prefix (default: `Docs/03_Inspection_Requests/`) | | `1E0` | Electrical | `Design Files/Electrical/` or `09_Correspondence/` | | `1KH` | HSE | `Docs/02_Plans_and_Procedures/02.5_HSE_Plan/` | | `1K0` | General/Multi | Per doc type (see below) | | `1M0` | Mechanical | `Docs/02_Plans_and_Procedures/02.16_Mobilization_Plan/` or per type | | `1KN` | Security/ICT | `Docs/05_SIs/05.1_Issued_by_CG/` | | Doc Type Prefix | Document Type | Routing Pattern | |----------------|--------------|-----------------| | `PL-` | Plan | `02_Plans_and_Procedures/02.{NN}_{Name}/` | | `ZD-` | General/Methodology | Per discipline folder or `09_Correspondence/` | | `MS-` | Method Statement | `02_Submittals/08_Method_Statements/` (create if missing) | | `IR-` | Inspection Request | `Docs/03_Inspection_Requests/` | | `NC-` | Non-Conformance Report | `Docs/10_Test_and_Inspection/10.3_NCRs/` | | `SI-` | Site Instruction | `Docs/05_SIs/05.1_Issued_by_CG/` | | `JSI-` | Joint Site Instruction | `Docs/05_SIs/05.1_Issued_by_CG/` | | `PQ-` | Prequalification | `Docs/09_Registers/27_Subcontractor_Prequalification_Register/` | | `MI-` | Mobilization Items | `02_Plans_and_Procedures/02.16_Mobilization_Plan/` | | `TQ-` | Technical Query | `Design Files/` per discipline | | `RP-` | Report | `02_Submittals/10_Reports/` (create if missing) | | `SC-` | HSE Compliance | `02.5_HSE_Plan/01_Source_Files/` | **CG Responses** (Code B or C status): copy to `02_CG_Responses/` subfolder within the parent document folder. The original submission goes to `01_Source_Files/`. **Daily Reports**: always to `07_Daily_Reports/` with filename `Daily Report {DD-MM-YYYY}.pdf`. **Weekly Reports**: to `07_Daily_Reports/Weekly_Reports/`. **Invoices**: to `Docs/04_Financial/Invoices/`. ### Updating SITREP on email processing When a key submission arrives (prequal, CG response, new appointment), update the relevant `_MANAGER_DASHBOARD/SITUATION_REPORT.md`: - Bump date stamp - Update `Status:` line - Update `Prequal Register Status:` if applicable - Check/uncheck action items - Update `Subcontractor:` line if new firm ### Prequal register — handling all intake methods **Location:** `Docs/09_Registers/27_Subcontractor_Prequalification_Register/` Prequal submissions arrive via three paths — email attachments, direct chat file uploads (WhatsApp/Telegram), or SharePoint links. Each path converges on the same workflow below. #### Common prequal intake workflow 1. **Identify the supplier** — If filenames are generic ("prequalification.pdf", "Company Profile -A.pdf"), extract PDF text with `python3 -c "import fitz; doc=fitz.open('path'); print(doc[0].get_text()[:2000])"` or `pdftotext` to find company name, address, and scope. 2. **Determine the PQ number** — Check the last row in `_status.md`: - If the last entry is `PQ-NNNN`, the next PQ number is `PQ-NNNN + 1` - If the last entry is a non-PQ entry (e.g., `C-05`), the next PQ number is the last PQ-NNNN + 1 - Format: `PQ-` followed by 4 digits, zero-padded 3. **Create supplier folder** — `{Prequal_Register}/{Supplier_Name}/` (PascalCase, no spaces beyond underscore). No subfolder hierarchy — all files flat in the supplier folder. 4. **File documents** — Rename each PDF with a descriptive prefix: - Prequal ISO certs: `{Supplier}_Prequalification_ISO_Certs.pdf` - Company profile: `{Supplier}_Company_Profile.pdf` - TDS documents: `{Supplier}_{ProductCode}_{ProductName}_TDS.pdf` - Test reports: `{Supplier}_{ReportType}_Test.pdf` - Keep original product codes (e.g., WT73X0, WB711) in filenames for traceability 5. **Update `_status.md`** — Append a new table row: ``` | PQ-XXXX | {Supplier Name} | {Package Description} | Received {DD-Mmm} | {YYYY-MM-DD} | {comma-separated key filenames} | ``` Also append an update note below the table: `*Updated {YYYY-MM-DD} — Added {Supplier Name} ({Package}) prequal*` 6. **Create Odoo subtask** under package 3011 (00 — Pre-Qualification & Procurement) as a Tier 2 task (see `odoo-task-injection` skill for exact API). Assign to Sultan Issa (ID 151), tag 140 (Prequalification), stage 35 (Initiation), progress 20%. Include description listing all filed docs and their folder path. 7. **Log session time** to `account.analytic.line` with task ID, project 219, and estimated hours. #### Handling mixed document packages A single prequal submission often includes multiple document types: ISO certificates, company profile, product TDS (technical data sheets), test reports (VOC, LEED, etc.), and material safety data sheets. File ALL documents in the supplier folder — not just the certs. The TDS and test reports are supporting evidence the reviewer will need. Name each file descriptively so the register's "Docs Filed" column gives a genuine inventory. #### Direct chat uploads (WhatsApp/Telegram/Files) When the user sends files directly (not via email): 1. Files are passed as paths in the conversation — copy from the provided temp location 2. No email body to extract context from — rely entirely on PDF text extraction to identify content 3. No SITREP or email log update needed (no email was processed) 4. Otherwise follow the common intake workflow above #### Email-attachment prequal submissions Follow section 4b (Processing Incoming Email Submissions) for extraction, then apply the common intake workflow for filing and register updates. ### SharePoint link handling (no direct attachment) Some emails reference a file shared via OneDrive/SharePoint link rather than including it as a direct attachment. Signs: - Email body contains a `https://...sharepoint.com/...` or `https://...my.sharepoint.com/...` URL - `Mail_OwnedBlocks` only has image attachments (signatures), no PDF/document blocks - The sender used Outlook's "Share" or "Attach → Share link" feature These links require corporate authentication and cannot be downloaded programmatically. Do not waste iterations trying to curl/wget them (HTTP 401). Instead: 1. Confirm it's a SharePoint link by checking the email body 2. Create a **routing memo** `.md` file in the target folder documenting the link, document code, and sender 3. Log to `Email_Archive/` with a note that manual download is needed 4. Flag it to the user: the file path + that it's behind auth Example memo content: ```markdown # MOC-MUS-ASE-1K0-MI-0001 — SharePoint Link **From:** Hossam Mabrouk (hmabrouk@cg.com.sa) **Date:** 2026-06-11 **Link:** https://cgksa-my.sharepoint.com/... (requires CG KSA auth) **Routing destination:** `Docs/02_Plans_and_Procedures/02.16_Mobilization_Plan/01_Source_Files/` **Action:** Open link while authenticated to CG KSA tenant, download PDF, save to destination. ``` ## 5. Maintaining PROJECT_MEMORY.md from Email Archives Trigger: user asks to extract findings from an email archive (N.md) and update PROJECT_MEMORY.md. ### Workflow 1. **Read both files fully** - Read the email archive (`N.md`) — use `read_file` with offset pagination for large files. The archives are typically 5,000–17,000 lines. - Read the existing `PROJECT_MEMORY.md` — identify the latest section 0 entries and the most recent Session Update date. 2. **Cross-reference and identify delta** - Scan emails for: - Document references (`PL-XXXX`, `ZD-XXXX`, `IFC-XXXX`, `TQ-XXXX`, `PQ-XXXX`, `SI-XXXX`, `IR-XXXX`, `NCR-XXX`, `RP-XXXX`) - CG response codes (Code A/B/C/D from CG reviewers: `melbaz@cg.com.sa`, `hmabrouk@cg.com.sa`, `salfeer@cg.com.sa`, `asadat@cg.com.sa`) - PMC communications from `mohamed.elmahlawy@ace-mb.com` (meetings, MOMs) - NRS activities from Jim Richards, Francesco Bitelli, etc. - Subcontractor progress (Studio ZNA, ITC, Bluehaus, Leica/SITML, Artec/3DME, Heritage Sites) - Meeting references (Progress Meeting No., MOM No.) - Structural/technical developments (core tests, as-built drawings, quotations) - Check which items are ALREADY in section 0 — don't duplicate. - Identify items that are NEW or need updated detail. 3. **Apply updates to section 0 (LATEST STATUS UPDATES)** - Section 0 is a table with two columns: `Change` and `Detail`. - New entries go before the closing `|---` separator. - Use `patch` with multi-line context to ensure uniqueness (section 0 table rows have repeating `|| Change | Detail |` patterns). - Each entry follows the format: ``` || **{Short Title (Date)}** | {Full detail including doc ref, outcome, filing location}. | ``` - For CG code progressions, show both the initial and final status: e.g., "Originally Code C on 25-May, resubmitted 31-May, approved Code B 2-Jun." - Enhanced entries (adding detail to existing rows) can be done via targeted patch on the row's Detail column. 4. **Append Session Update section at end** - Location: after section 12 (or last numbered section, before any previous Session Updates). - Format: ``` |## Session Update — {Date} ({Short label}) | || Item | Detail | ||------|--------| || **Action** | {What was processed} | || **Source** | {Path to archive file} | || **Key Update** | {Brief summary of changes made} | | |### {Subsection} (e.g., CG Consultant Responses) |{Tables or bullet lists with structured findings} ``` - Group findings into subsections: CG Consultant Responses, Progress Meetings, Lighting Design, 3D Scanning Evaluation, Structural Design, ICT Security, Core Test Data, etc. 5. **Update the date header** at the top of the file: `> آخر تحديث: **{date}**` ### Information Sources in Email Archives (N.md) | Source | What to Look For | |--------|------------------| | **CG (melbaz@cg.com.sa)** | Response codes, review comments, SI issuances | | **CG (hmabrouk@cg.com.sa)** | HSE plan responses, NCR closeout | | **PMC (mohamed.elmahlawy@ace-mb.com)** | Meeting minutes (MOM No.), schedule updates, PMC directives | | **NRS (Jim Richards, Francesco Bitelli)** | Design direction, RFIs, drawing comments | | **Samaya (Hesham Abdelhameed)** | Submittals sent to CG, daily reports | | **Samaya (Mohammed Hakami)** | Lighting, AV, ICT Security coordination | | **Samaya (Abdelmohaymen Farag)** | Structural/technical coordination, quotation forwarding | | **Samaya (Fahad Hassan)** | 3D scanning procurement evaluation | | **Subcontractors** | Fee proposals, scope documents, CVs (Studio ZNA, Heritage Sites, SITML) | ### Pitfalls - The `|---` separator after section 0 is not unique — always include surrounding table rows for context when patching. - CG codes can change between email rounds (Code C → Code B for PL-0043, PL-0046). Track the initial AND final status. - Some entries already exist in section 0 under different wording. Check for doc ref numbers, not just titles. - The project memory already has a "Week 23 Email & Document Activity" section (section 12) that is separate from the Session Update. Session Updates go below it. - NRS "outside our scope" = outside NRS scope, not outside Samaya scope. Check T2 allocation table first. - Patinated brass finish concerns from NRS are advisory — the spec stands unless CG changes it. - When a document has both CG comments and an NRS comment sheet, treat them as separate review layers.