# My Green Robot — Agent Safety & System Invariants

This document establishes the operational guardrails, data contracts, and regression defenses for any AI agent or developer working in this repository.

---

## 1. Automated Verification & Regression Defense (ECC Pattern)
- **Zero Broken Tests**: Every change must maintain a passing test suite (`npm test`).
- **Pre-Commit Hook**: A git hook (`scripts/pre-commit.js` via `.githooks/pre-commit`) automatically executes before every commit to verify:
  1. No restricted personal addresses (e.g., Vernon St) are staged.
  2. All 700+ automated unit and integration tests pass cleanly.

---

## 2. Test Isolation & Production Data Integrity
- **Production Data Files**: `data/managed-properties.json`, `data/service-requests.json`, and `data/claims.json`.
- **Zero Mock Pollution**: Never leave synthetic test fixtures (`Test Customer`, dummy phone numbers) inside production `data/*.json` files.
- **Snapshot & Restore Hook**: Any test that writes to `data/` must create an in-memory snapshot in `before()` and restore it in `after()`:
  ```javascript
  let origProps = '';
  before(() => { if (fs.existsSync(PROPS_FILE)) origProps = fs.readFileSync(PROPS_FILE, 'utf8'); });
  after(() => { if (origProps) fs.writeFileSync(PROPS_FILE, origProps, 'utf8'); });
  ```

---

## 3. Server HTTP Body Stream Safety (`server.js`)
- **Pre-Buffered Body**: `server.js` buffers incoming request streams early into `req._bodyPromise` via `parseBody(req)`.
- **Golden Rule**: **NEVER** attach a raw, unbuffered `req.on('data')` or `req.on('end')` handler inside route handlers or middleware. Always call `await parseBody(req)` or `await readPostBody(req)`.
- Eager raw stream listeners will consume the stream prematurely, leaving subsequent route handlers with empty bodies (`""`).

---

## 4. Pro in Charge & Supabase Sync Schema Contract
To ensure the homeowner dashboard never forgets their assigned or working pro across devices and browser sessions:
- **Dual Schema Mirroring**: Whenever reading or writing `mgr_assigned_crew_v1` in `localStorage`:
  ```javascript
  {
    name: "Silva's Lawn Care",
    phone: "(401) 555-0100",
    email: "silva@example.com",
    city: "Pawtucket, RI",
    crewId: "custom-crew",
    isWorking: true,
    customCrew: {
      name: "Silva's Lawn Care",
      phone: "(401) 555-0100",
      email: "silva@example.com",
      city: "Pawtucket, RI",
      isWorking: true
    }
  }
  ```
- **Sync Core (`yard-sync-core.js`)**: `cleanCrew()` validates and preserves both top-level and nested `customCrew` keys so Supabase `mgr_yard_boards` never receives empty strings.
- **Quote Acceptance**: Accepting a quote in `quote-tracker.js` immediately updates `mgr_assigned_crew_v1`, triggering `yard-sync.js` to persist the winning crew to the user's remote Supabase account.

---

## 5. Privacy, PII & Address Anonymity
- **Address Sanitization**: Never commit real personal homeowner addresses or phone numbers.
- **Town-Level Privacy**: In public cards and shared URLs, only town and state ever leave (e.g., via `townFromAddress(addr)`).
- **Test Fixture Addresses**: Use public street names such as `Benefit St` or `East Ave, Pawtucket, RI`.

---

## 6. Documentation & Existing Code Integrity
- Preserve existing comments, docstrings, and helper functions unrelated to the immediate task.
- When fixing an issue, always diagnose the root cause across both client and server before modifying files.