Project Data

Project Data Management

Overview

The data backbone for Foreman_OS. This skill owns the project intelligence store, the report history log, and all operational data. Every other skill reads from and writes to the data layer through the patterns defined here.

Data Files

All JSON files are stored in folder_mapping.ai_output (typically AI - Project Brain/). If folder_mapping is not yet set up, fall back to the user's working directory root.

IMPORTANT — File Location Rule: When searching for these files, always check AI - Project Brain/ first, then fall back to the project root. When saving, always save to folder_mapping.ai_output if available.

File Structure

File Lookup Table

When a skill or command needs specific data, use this table to know which file to read:

Project Intelligence Schema

See references/json-schema-reference.md for the full schema with producer/consumer mapping. Also see references/data-flow-map.md for pipeline architecture and references/cross-reference-patterns.md for reusable cross-referencing patterns. Quick reference:

project-config.json
  ├── project_basics       → Header info, auto-fills every report
  ├── report_tracking      → Last report number, sequential numbering
  ├── folder_mapping       → Where to save each output type
  ├── documents_loaded     → Extraction history with dates and coverage
  ├── version_history      → Change log for key data points
  └── asi_log              → Architect's Supplemental Instructions tracking

plans-spatial.json
  ├── grid_lines           → Column/row identifiers, spacing, orientation notes
  ├── building_areas       → Named zones with grid references and floor ranges
  ├── floor_levels         → Level names, elevations, descriptions
  ├── room_schedule        → Room numbers, names, locations
  ├── site_layout          → North arrow, access points, laydown, trailers
  ├── sheet_cross_references → Drawing index, detail callouts, assembly chains
  ├── quantities           → Measured quantities (rooms, walls, concrete, flooring, piping, counts, PEMB)
  └── site_utilities       → Storm, sanitary, water, fire, gas, telecom utility runs

specs-quality.json
  ├── spec_sections        → CSI sections with requirements and thresholds
  ├── key_materials        → Material specs with testing requirements
  ├── weather_thresholds   → Temperature/wind limits by work type
  ├── hold_points          → Inspection hold points by work type
  ├── tolerances           → Quality tolerances by material/system
  ├── contract             → Dates, LDs, hours, restrictions, documentation reqs
  ├── safety               → Fall protection zones, confined spaces, hot work areas
  ├── swppp               → BMP locations, inspection triggers, requirements
  ├── geotechnical         → Bearing capacity, water table, compaction reqs
  └── mix_designs          → Concrete mix design specifications

schedule.json
  ├── current_phase        → Active construction phase
  ├── percent_complete     → Overall project progress
  ├── milestones           → Key dates with status tracking
  ├── critical_path        → Critical path activities
  ├── near_critical        → Near-critical activities
  ├── weather_sensitive    → Activities affected by weather
  ├── long_lead_items      → Long-lead material items
  ├── material_requirements_by_activity → Activity-to-material mapping
  └── lookahead_history    → Generated lookahead schedule records

directory.json
  ├── subcontractors       → Directory with names, trades, contacts, scopes
  ├── vendor_database      → Supplier directory with capabilities and history
  └── owner_reports        → Weekly owner report archive

Individual log files (rfi-log.json, submittal-log.json, procurement-log.json,
change-order-log.json, inspection-log.json, meeting-log.json, punch-list.json,
pay-app-log.json, delay-log.json)
  ├── rfi-log.json         → RFI log array
  ├── submittal-log.json   → Submittal log array
  ├── procurement-log.json → Procurement log array
  ├── change-order-log.json → Change order log array
  ├── inspection-log.json  → Inspection/permit log array
  ├── meeting-log.json     → Meeting minutes and action items array
  ├── punch-list.json      → Punch list items array
  ├── pay-app-log.json     → Pay applications, SOV, lien waivers, retainage tracking
  └── delay-log.json       → Delay events, weather delays, concurrent delays, claims

daily-report-data.json
  └── Report history — the running record that feeds dashboard and weekly reports

Smart Retrieval

When a skill needs project data, it should only load the specific files it needs — never all 28 files at once.

Retrieval by Work Type

When the user describes work being performed, pull the relevant cross-section:

Retrieval by Location

When the user mentions a location, resolve it from plans-spatial.json:

Retrieval by Subcontractor

When the user mentions a sub (even casually), match from directory.json:

Cross-Referencing

The power of the data layer is connecting related information across files. When serving data, always include cross-references:

Sub → Schedule → Spec

A subcontractor is linked to their scope, which maps to spec sections, which have testing and inspection requirements. When "Walker Construction" is on site doing excavation:

• Pull their scope from directory.json
• Pull the earthwork spec sections from specs-quality.json
• Pull compaction testing requirements from specs-quality.json
• Pull geotechnical requirements from specs-quality.json
• Check schedule from schedule.json for earthwork milestones

Location → Grid → Area → Room

A location mention cascades through spatial data in plans-spatial.json:

• "Room 205" → Room schedule → Level 2 → East Wing → Grid E-G / 3-5
• "East wing foundation" → East Wing → Grid E-G → Level 1 / Below grade → Foundation spec sections (from specs-quality.json)

Work Type → Weather Threshold → Today's Weather

When documenting work, check if today's weather affects that work:

• Concrete placement + today's temp < cold weather threshold (from specs-quality.json) → Flag in report
• Crane operations + today's wind > wind speed limit (from specs-quality.json) → Flag in report

Retrieval by Quantity

When the user asks about quantities, measurements, or progress percentages — read from plans-spatial.json:

Element → Assembly Chain → Multi-Sheet Data

When a specific construction element is referenced, trace its assembly chain in plans-spatial.json:

• "Footing F1" → sheet_cross_references.assembly_chains → S2.1 (plan) + S5.1 (detail) + S1.0 (notes)
• Pull dimensions from each linked sheet, calculate volume, note concrete spec
• Include source priority (DXF exact data > visual estimate > text-parsed value)

Retrieval by RFI/Submittal

When working with RFIs or submittals, pull the full context chain across files:

Retrieval by Procurement

Read from procurement-log.json, cross-reference with other files as needed:

Retrieval by Pay Application

Read from pay-app-log.json, cross-reference with subcontractor and change order tracking:

Retrieval by Delay Event

Read from delay-log.json, cross-reference with schedule and daily report data:

Retrieval for Lookahead

When generating a look-ahead schedule, pull a composite view:

Retrieval for Weekly Owner Report

Cross-Referencing: RFI → Submittal → Procurement

These three log files are interconnected:

• An RFI (rfi-log.json) may trigger a submittal (architect clarifies, resulting in a product change)
• A submittal (submittal-log.json) approval may trigger procurement (approved product can now be ordered)
• A procurement (procurement-log.json) delay may trigger an RFI (need alternate product approval)

When serving data from any of these logs, always check for cross-references:

• RFI's related_submittals[] → pull linked entries from submittal-log.json
• Submittal's related_rfis[] → pull linked entries from rfi-log.json
• Procurement's submittal_id → pull linked submittal status from submittal-log.json (can't order until approved)

Extended reference: Detailed examples, templates, scoring rubrics, and best practices are in references/skill-detail.md.