17 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.
From Unified Framework v1 Convergence (2026-08-06)
These entries formalize terminology decided across Decisions 1–8 of DOP-AI-Visibility-Unified-Framework-v1.md.
Artifact A — Diagnostic Record
Layer 1/2 deliverable. Contains diagnosis only. No solution language in authored narrative fields (executive summary, observation narrative, competitor observation summaries). Raw evidence (prompt text, engine output, source titles, quoted business names) is exempt from the banned-word gate. Does not duplicate data-inventory-v1.md or threat-register-v1.md — feeds findings into those files' existing schemas instead. Never reaches a client raw — internal evidentiary backing only. Governed by field-scoped banned-language QA gate + human review.
Artifact B — Strategy and Remediation Brief
Layer 3+ deliverable. Translates threat-register-v1.md findings (via the Opportunity Matrix) into revenue scenarios, package recommendation, and measurement windows. Does not duplicate requirements-v1.md or workflows-v1.md — feeds action items into those by entry ID instead. Prescriptive by design — the only place solution/recommendation language belongs.
Severity
A diagnostic classification of how serious a problem is. Lives in Artifact A. Values: Critical, Major, Minor.
Priority
A prescriptive classification of how urgently an action should be taken. Lives in Artifact B. Values: Fix Now, Fix Soon, Monitor. Do not conflate with Severity — a Critical diagnosis and a Fix Now priority are different fields answering different questions.
Tier 1 — Verified
⚠️ PENDING RECONCILIATION (2026-08-06) — See
## Evidence Modelabove. That pre-existing section states Findings produced byllm_sampleor any other non-deterministic method are "Indicative by definition" and "Cannot be upgraded to Verified without additional concrete evidence." This entry distinguishes audit-run facts (Tier 1-eligible via stored artifacts) from Findings (Tier 2). Until the side-by-side extraction is done and Tony resolves it, this entry is not fully authoritative; when the two sections appear to disagree, the pre-existing Evidence Model rule governs (ambiguous findings default to Indicative).
A fact verified by the appropriate authority. Verification authority differs by fact class:
- Business-entity facts (name, phone, address, hours, services, categories): requires owner confirmation or owner-access verification.
- Audit-run facts (prompt executed, engine captured, timestamp, raw output stored): requires stored filesystem/git/database evidence. Verifies the audit event occurred, not that a business fact inside it is true.
- Public claims inside AI outputs: default Tier 2 until owner confirmation upgrades it (see Tier 2).
Same terminology as "Verified" in Module A — one scale, no separate axis.
Tier 2 — Indicative
A fact or observation derived from public sources, inference, or unverified signals. Public observation defaults to Tier 2 until upgraded by stronger verification. Same terminology as "Indicative" in Module A.
Core Visibility Index
Quantitative component of the Visibility Score, 0–70 points, lives in Artifact A. Composed of directly countable audit observations only: Mention rate (35), Mention strength/position (20), Description accuracy (15). Never blended with qualitative indicators into a single false-precision number without disclosure.
Directional Context Indicators
Tier 2 qualitative signals reported separately from the Core Visibility Index: Source/citation quality, Competitor observation share, Engine variance. Disclosed as indicative, not measured market share.
Owner-Verified Correction Plan
A Layer 1b (owner-access verification) artifact, not Layer 4 — corrected after cross-check against path-to-poc-sequencing.md and requirements-template.md. Layer 4's actual deliverable is requirements-v1.md (outcome statements, linked Threat ID, pricing-band ceiling). The Correction Plan fills a documentation gap in Layer 1b's exit criteria: canonical business name and public name, canonical NAP/service-area definition, primary + secondary geography, canonical phone/website, owner-verified service list, high-ticket priority services, capacity constraints, access matrix, access method and expiry, approval boundaries, no-change zones, change intake channel, V1 platform scope, definition of "setup complete." Definition of done: all fields Tier 1, access tested not just requested, approval boundaries acknowledged in writing.
Execution Card
A constrained agent task definition with fixed trigger conditions, allowed inputs, forbidden actions, deterministic output format, human approval gate, and required completion evidence. No free-form reasoning permitted unless a skill has been explicitly promoted (see Promotion Gate). Working precedent: the GBP cold-audit pattern (Leonard fires only fixed rules R1–R3).
Promotion Gate
The measurable threshold a skill must clear before moving from execution-card-constrained to higher autonomy: ≥5 scored runs in the task reliability ledger, ≥80% at Benchmark quality (9–10, zero scope violations), ≥4 consecutive weeks with zero fabrication/self-report incidents, and ≥3 clients engaged (i.e., past pure PoC). Evaluated per-skill, never as a blanket switch.
Restraint Principle
A design principle: stable signals should not be changed unnecessarily. Freshness is not the same as activity. Over-editing has a cost — applies especially to Phase B / ongoing monitoring work.
Exposure Craft
In-scope V1 work: platform category selection, attributes, service listing fields, structured short descriptions constrained by platform fields, Q&A seeded from owner-verified facts, schema properties from owner-verified data, canonical NAP enforcement, listing-field language matching customer search terms. Explicitly distinct from Content Marketing (out of scope per README V1 Scope Exclusions): open-ended copywriting, blog content, content strategy, brand narrative, social media production, paid ad copy, website redesign copy.
Path to PoC vs. Client Lifecycle Stages
Path to PoC (Layers 1–7) is the authoritative internal engagement sequence, verified against path-to-poc-sequencing.md (pulled from main 2026-08-06). Client Lifecycle Stages (0–10) is client-facing narrative language layered on top. Bridge map (verified, no longer a working hypothesis):
| Stage | Layer(s) |
|---|---|
| 0–1 | Pre-Layer 1 |
| 2 | Layer 1a + 2 |
| 3 | Layer 3 (non-skippable) |
| 4 | Layer 1b + Layer 4 (owner-access verification and requirements — both land here) |
| 5 | Layer 5 + 6 + 7 (POC Delivery belongs here, not Stage 6) |
| 6 | Re-run of Layer 1–2 tooling (second diagnostic pass, not delivery) |
| 7–10 | Post-PoC operations |
End of Glossary