11 KiB
GLOSSARY.md
Status: Mixed — see horizon labels below
Last Updated: 2026-08-02
Owner: Tony
Rule: Core mission terms below remain the shared vocabulary. Operating process for Version 1 is defined by the Agent Charter, Audit Playbook, Path to PoC, task reliability ledger, and employee onboarding manual — not by unimplemented Check machinery.
| Section | Horizon |
|---|---|
| Core Mission Terms, Evidence Model (Tier 1/2), Approval Gate, Client-Facing Surface, Low-Risk Fix, PoC Fix, Before/After | NOW — aligns with operating docs |
Check system (checks.yaml), SHA-256 evidence store, Finding/Run machine schema, Shadow-Mode Graduation via ADR |
LATER — specified here only; not built; do not treat as current SOP |
Until specifications/checks/checks.yaml exists and is adopted by ADR, task graduation uses docs/operations/task-reliability-ledger.md (≥100 error-free runs per task_type). That ledger is the measurable gate. ADR-based Shadow-Mode Graduation remains a future refinement, not a second conflicting current rule.
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 operating tooling (Playbook, Path to PoC, ledger). A future check catalog in specifications/checks/checks.yaml is LATER and does not exist yet.
Evidence Model
Verified Evidence (Tier 1)
Operating definition (NOW): concrete, timestamped, observable, or instrument-backed findings approved by a human for client-facing use. Prefer reproducibility and dated snapshots.
LATER (when Check system ships): A Finding that meets all of the following may use the stricter machine definition:
- 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 (default 7 days unless the Check specifies otherwise via
freshness_days)
Findings produced by llm_sample or any other non-deterministic method are Indicative by definition.
May be presented to clients as a confirmed issue only after human tier approval in Version 1.
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 Tier 1 criteria.
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 / Run / Client / Agent
NOW: Practical artifacts are Data Inventory rows, Threat Register entries, and scored agent drafts under the Playbook.
LATER: Machine schema (Finding with check_id, Run against check catalog, structured Client profile) applies when the Check system exists.
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 (LATER until ADR + Check system)
NOW: Graduation is tracked only in docs/operations/task-reliability-ledger.md (≥100 error-free runs per task_type; reliability does not transfer across types).
LATER: A Task Type may move from gated to auto-approved after a documented reliability window of human reviews meeting an agreement threshold with zero Post-Publish Defects, with window size set in an ADR. Until that ADR exists, no Task Type may graduate under the machine Check model; the Approval Gate applies universally.
Task Type
NOW: A named row in the task reliability ledger (e.g. gbp_snapshot_ingest_r1_r3).
LATER: A unique pair of check_id + remediation_class once checks.yaml exists.
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 dated evidence (hashed artifacts when the LATER evidence store exists).
Check System Terms (LATER — not built)
The following defines a future declarative check catalog. specifications/checks/checks.yaml does not exist in the repository. Do not implement agents against this section as if it were live.
Check
A declarative test defined in specifications/checks/checks.yaml (planned).
Every Check must declare: id, domain, method, owner_surface, client_facing, requires_approval, default_tier, remediation_class, evidence_fields, freshness_days.
Domain
One of: customer_path_integrity, ai_visibility_integrity, local_competitive_awareness.
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
One of: low_risk_fix, recommendation, manual_only, out_of_scope.
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