Add directive: Client Intake ↔ Audit Record alignment + human-verification rules

2026-08-11 17:31:38 +00:00
parent 470d0ba76e
commit 003820f92c
1 changed files with 113 additions and 0 deletions
@@ -0,0 +1,113 @@
+# 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.*