10 KiB
GLOSSARY.md
Status: Canonical Last Updated: 2026-07-25 Owner: Tony Rule: This is the single source of truth for all core terminology. Other documents must link here instead of redefining terms. Changes require an ADR citing motivating evidence.
Core Mission Terms
Silent Customer Loss
Umbrella term for customer acquisition problems that occur without the business owner clearly seeing or measuring the loss. It comprises two primary modes. A Finding is classified by its primary mode; when both apply, Customer Path Leakage takes precedence if a concrete pathway friction exists.
- Customer Path Leakage — interest/intent exists, but friction prevents contact, booking, or visit.
- Discovery Failure — the customer, search engine, or AI system never finds or accurately represents the business.
Customer Path Leakage
A potential customer has interest or intent but fails to contact, book, visit, or engage because of digital friction (wrong phone, broken booking link, incorrect hours, failed form, confusing service information, inaccurate listing data, etc.).
Discovery Failure
A potential customer never meaningfully encounters the business because customers, search engines, or AI systems do not find, understand, surface, or accurately represent it (weak local visibility, incomplete entity signals, missing service clarity, absence from AI samples, poor structured data, inconsistent citations, etc.).
Customer Path Integrity
Operational domain responsible for ensuring that once a customer is interested, the digital pathway to contact/booking/visit is free of friction.
Machine value: customer_path_integrity
Owned surfaces: Google Business Profile (core fields, hours, phone, booking link, services), website contact paths and booking systems, primary citations for NAP consistency.
AI Visibility Integrity (AEO)
Operational domain responsible for ensuring AI-assisted discovery systems can accurately understand and represent the business.
Machine value: ai_visibility_integrity
Owned surfaces: structured data / schema, FAQ content, entity clarity signals, sampled AI answer testing, GBP consistency as it affects AI understanding.
No promises of placement, recommendation, or citation by any AI system.
Local Competitive Awareness
Supporting capability (not a standalone product) that monitors relevant competitors for changes affecting the client's visibility or customer path. Depth scales with service tier. Built-in for every client at a baseline level; deeper continuous monitoring is tiered.
Machine value: local_competitive_awareness
Mission Scope vs Contract Scope
- Mission Scope: any digital issue that can affect customer acquisition, visibility, trust, or conversion may be identified.
- Contract Scope (Version 1): monitoring, diagnosis, prioritization, reporting, and approved low-risk optimizations only. Social media production, paid ads, website redesign, branding, full SEO campaigns, and CRM/email are excluded.
Version 1
The initial commercial offering defined by the current Contract Scope, evidence model, Approval Gate, and the check catalog in specifications/checks/checks.yaml.
Evidence Model
Verified Evidence (Tier 1)
A Finding that meets all of the following:
- Reproducible and deterministic method (sampling and probabilistic methods are excluded)
- Captured artifact (raw payload or screenshot)
- SHA-256 hash of the artifact
- UTC timestamp of capture
- Current within the defined freshness window, measured from capture time to the moment of client-facing use (default 7 days unless the Check specifies otherwise via
freshness_days)
May be presented to clients as a confirmed issue.
Findings produced by llm_sample or any other non-deterministic method are Indicative by definition, regardless of artifact quality.
Indicative Evidence (Tier 2)
Sampled, directional, or probabilistic findings that suggest risk or opportunity but do not prove direct customer loss. Must always be labeled as directional. Cannot be upgraded to Verified without additional concrete evidence meeting the full Verified criteria, including the deterministic-method requirement.
Evidence Tier Assignment Authority
Agents may propose a tier. The final tier used in any client-facing report requires human approval in Version 1. Ambiguous findings default to Indicative. A rejected Tier 1 proposal defaults to Tier 2 unless the Finding is discarded or more evidence is requested.
Finding
A single structured result produced by a Check against a Client during a Run. Contains check_id, domain, status, proposed_tier, approved_tier, evidence references, and remediation state.
Run
A complete execution of the check catalog (or a defined subset) against one Client at a point in time. Produces a set of Findings and an immutable evidence store.
Client
A local service business enrolled in the service. Represented by a structured profile containing authorized surfaces, contact details, and scope of engagement.
Agent
Any automated or semi-automated system, including language models, that detects, drafts, or proposes actions. A human operating through an Agent remains fully bound by the Approval Gate; the Agent does not create an exception.
Operating Rules
Approval Gate (Reconnaissance vs Execution)
Agents may detect, gather evidence, and draft.
Any change that publishes to a Client-Facing Surface requires explicit human approval before going live.
Client-Facing Surface
A surface that the client's customers or the public can see or interact with: GBP fields, review responses, Q&A, business descriptions, hours, phone numbers, booking links, website content, directory listings, citations.
external_ai is not client-facing.
Owner Surface
The platform or system a Check targets. Permitted values: gbp, website, citations, external_ai.
Owner Surface is used for authorization and routing. It is separate from client_facing and must never be used as a substitute for it — external_ai is a valid Owner Surface but is not a Client-Facing Surface.
Low-Risk Fix
A remediation that meets all of the following:
- Changes a single field or discrete, isolated attribute (e.g., a URL value, phone number, email address, or hours entry)
- Has a documented and tested rollback
- Contains no legal, medical, pricing, or compliance claims
- Does not alter website structure, navigation, or marketing copy. Single-attribute website changes such as replacing a broken booking URL are permitted; structural or content edits are not.
Post-Publish Defect
Any of the following occurring after an approved change has been published, detected within 14 days of publication, or later if the client reports it with clear attribution:
- The change is rejected or reversed by the platform (e.g., Google)
- The change introduces a new Verified error on the same field or a directly dependent field
- A client reports that the published state is incorrect or harmful
- The change violates the Low-Risk Fix criteria
Any Post-Publish Defect immediately revokes graduation for that Task Type.
Shadow-Mode Graduation
A Task Type may only move from gated to auto-approved after a documented reliability window of human reviews meeting an agreement threshold with zero Post-Publish Defects.
The window size and agreement threshold are set in an ADR. Until that ADR exists, no Task Type may graduate and the Approval Gate applies universally.
Graduation is per Task Type and is immediately revoked on any Post-Publish Defect.
Task Type
A unique pair of check_id + remediation_class. Graduation and revocation operate at this granularity only.
Proof-of-Concept Fix
A single, high-leverage, low-risk correction performed with explicit approval during the initial assessment phase, to demonstrate value before a retainer is offered. Typical examples include correcting a broken booking URL or an incorrect GBP phone number.
Before/After Report
A client-facing document that shows the state of specific Findings before and after approved remediations, backed by hashed evidence.
Check System Terms
Check
A declarative test defined in specifications/checks/checks.yaml.
Every Check must declare all of the following fields:
| Field | Type | Notes |
|---|---|---|
| id | string | Unique, stable |
| domain | enum | See Domain |
| method | enum | See Method |
| owner_surface | enum | gbp, website, citations, external_ai |
| client_facing | boolean | Drives the Approval Gate |
| requires_approval | boolean | Must be true wherever client_facing is true |
| default_tier | enum | verified or indicative |
| remediation_class | enum | See Remediation Class |
| evidence_fields | list | Artifacts captured on execution; may not be empty |
| freshness_days | integer | Defaults to 7 |
Domain
One of: customer_path_integrity, ai_visibility_integrity, local_competitive_awareness. Must match the ownership table.
Method
One of: http_head, http_get, dom_query, api_gbp, manual, llm_sample.
Any Check with method: llm_sample must have default_tier: indicative.
Remediation Class
How a failing Check is expected to be addressed. One of:
- low_risk_fix — meets the Low-Risk Fix criteria
- recommendation — reported to the client, not executed by the company
- manual_only — requires human execution, never agent-drafted for publish
- out_of_scope — outside Contract Scope; quoted separately
Domain-to-Surface Ownership (V1)
| Surface | Primary Domain | Machine Value | Notes |
|---|---|---|---|
| GBP core fields | Customer Path Integrity | customer_path_integrity |
Phone, hours, booking, services |
| Website contact paths | Customer Path Integrity | customer_path_integrity |
Forms, CTAs, booking links (single-attribute only for fixes) |
| Primary citations (NAP) | Customer Path Integrity | customer_path_integrity |
Consistency of name/address/phone |
| Structured data / schema | AI Visibility Integrity | ai_visibility_integrity |
FAQ, LocalBusiness, Service |
| Sampled AI answers | AI Visibility Integrity | ai_visibility_integrity |
Indicative only |
| Competitor signals | Local Competitive Awareness | local_competitive_awareness |
Supporting |
Shared surfaces declare a primary owner. Secondary domains may observe but do not own remediation.
End of Glossary