GLOSSARY: mark Check-system as LATER horizon; operating truth is Playbook + ledger
This commit is contained in:
+39
-55
@@ -1,9 +1,17 @@
|
||||
# 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.
|
||||
**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.
|
||||
|
||||
---
|
||||
|
||||
@@ -55,7 +63,7 @@ Machine value: `local_competitive_awareness`
|
||||
|
||||
### 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`.
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
@@ -63,41 +71,33 @@ The initial commercial offering defined by the current Contract Scope, evidence
|
||||
|
||||
### Verified Evidence (Tier 1)
|
||||
|
||||
A Finding that meets **all** of the following:
|
||||
**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, measured from capture time to the moment of client-facing use (default 7 days unless the Check specifies otherwise via `freshness_days`)
|
||||
- Current within the defined freshness window (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.
|
||||
|
||||
Findings produced by `llm_sample` or any other non-deterministic method are Indicative by definition, regardless of artifact quality.
|
||||
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 the full Verified criteria, including the deterministic-method requirement.
|
||||
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
|
||||
### Finding / Run / Client / Agent
|
||||
|
||||
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.
|
||||
**NOW:** Practical artifacts are Data Inventory rows, Threat Register entries, and scored agent drafts under the Playbook.
|
||||
|
||||
### 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.
|
||||
**LATER:** Machine schema (Finding with `check_id`, Run against check catalog, structured Client profile) applies when the Check system exists.
|
||||
|
||||
---
|
||||
|
||||
@@ -119,7 +119,7 @@ A surface that the client's customers or the public can see or interact with: GB
|
||||
|
||||
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.
|
||||
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
|
||||
|
||||
@@ -141,52 +141,41 @@ Any of the following occurring after an approved change has been published, dete
|
||||
|
||||
Any Post-Publish Defect immediately revokes graduation for that Task Type.
|
||||
|
||||
### Shadow-Mode Graduation
|
||||
### Shadow-Mode Graduation (**LATER** until ADR + Check system)
|
||||
|
||||
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.
|
||||
**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).
|
||||
|
||||
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.
|
||||
**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
|
||||
|
||||
A unique pair of `check_id` + `remediation_class`. Graduation and revocation operate at this granularity only.
|
||||
**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.
|
||||
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.
|
||||
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
|
||||
## 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`.
|
||||
A declarative test defined in `specifications/checks/checks.yaml` (planned).
|
||||
|
||||
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 |
|
||||
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`. Must match the ownership table.
|
||||
One of: `customer_path_integrity`, `ai_visibility_integrity`, `local_competitive_awareness`.
|
||||
|
||||
### Method
|
||||
|
||||
@@ -196,12 +185,7 @@ 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
|
||||
One of: `low_risk_fix`, `recommendation`, `manual_only`, `out_of_scope`.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user