# Client Intake ↔ Audit Record Alignment Directive

**Status:** Active  
**Created:** 2026-08-11  
**Purpose:** Ensure every data point captured during an audit maps cleanly and identically into the client intake form / Google Sheet structure, and that human verification is required wherever automation is unreliable or judgment is needed.

---

## Core Principle

The Google Sheet (or future intake form) is the **operational front door**.  
Gitea is the **versioned source of truth**.

Every field we capture in an audit must either:

1. Map directly to a column in the Clients intake sheet, or
2. Be stored in a structured raw/analysis file in the client’s Gitea repo that can later feed the intake or reports.

No orphan data. No free-form notes that cannot be traced back to a required field.

---

## Required Intake Fields (must stay in sync)

These columns in the **Clients** Google Sheet are the minimum contract:

| Field | Required | Notes |
|-------|----------|-------|
| Client ID | Yes | e.g. VP-001 |
| Business Name | Yes | Exact string |
| Website | Yes | Canonical URL |
| Primary Address | Yes | Street + Suite |
| City | Yes | |
| State | Yes | |
| Phone | Yes | Full digits preferred |
| Contact Email | Yes | |
| Primary Category | Yes | |
| Main Services | Yes | High-level list |
| Competitors | Preferred | |
| Intake Date | Yes | |
| Last Audit Date | Yes (after first audit) | |
| Next Review Date | Yes (after first audit) | |
| Status | Yes | Controlled vocabulary |
| Ground Truth Score | After audit | Human judgment |
| AI Visibility Summary | After interrogation | |
| Priority Issues | After analysis | |
| Report Link | When report exists | |
| Notes | Optional | |
| Last Updated | Yes | |

Any new field added to the Sheet must be reflected here and in the relevant Gitea templates.

---

## Human Verification Rules

**Human eyes are mandatory** before a data point is marked as Ground Truth when any of the following are true:

- Sources conflict (e.g. website hours ≠ Yelp hours ≠ Google hours)
- The value is subjective or requires judgment (score, priority, tone, quality)
- Automation/scraping is known to be unreliable for that source
- The field affects client-facing recommendations or remediation
- The data will be used to generate schema, GBP rewrites, or reports

**Status vocabulary for raw captures** (already in use):

- `NOT_PRESENT` — looked and confirmed absent
- `NOT_OBSERVED` — did not look or could not see
- `Unknown` — looked but signal is ambiguous
- Concrete observed value

Agents may propose values. Humans must approve before the value is written as final Ground Truth into the client repo or the intake Sheet.

---

## Process Flow (current simple version)

1. **Intake** → Client row created in Google Sheet (manual or form)
2. **Raw capture** → Structured snapshots written to the client’s Gitea repo (`raw/`)
3. **Human review** → Conflicts resolved, scores assigned, priority issues named
4. **Ground Truth locked** → Clean values promoted to the intake Sheet + analysis files
5. **Remediation / Report** → Generated only from locked Ground Truth

---

## Hermes / Agent Role

Agents (including any future Hermes Office suite capabilities) may:

- Pull and structure public data
- Fill draft templates
- Flag conflicts
- Propose values

Agents may **not**:

- Mark a conflicting or judgment-based field as final Ground Truth without human confirmation
- Write directly to the live client intake Sheet without an explicit approval step

If Hermes Office suite later gains reliable form-filling ability, it must still respect the human-verification gate defined above.

---

## Immediate Next Actions

- Keep the Clients Google Sheet columns as the source of the field contract
- Continue walking Phoenix Salon + Spa using this alignment
- After each major section is human-verified, write the clean record into `client-data-pss`
- Update this directive if new required fields are added

---

*This directive supersedes informal process notes for client intake and audit record structure.*