From 70c54b1283963d80277035c6812704a7737f8ed1 Mon Sep 17 00:00:00 2001 From: Joshua Date: Thu, 19 Feb 2026 12:24:44 -0800 Subject: [PATCH] docs: add AI-first public content standard and conformance checklist --- README.md | 3 + docs/ai-answer-conformance-checklist.md | 81 +++++++++++++++++++++++ docs/public-content-standard.md | 87 +++++++++++++++++++++++++ docs/release-gate.md | 4 ++ docs/vocabulary-registry.md | 1 + 5 files changed, 176 insertions(+) create mode 100644 docs/ai-answer-conformance-checklist.md create mode 100644 docs/public-content-standard.md diff --git a/README.md b/README.md index 3e531c4..98c4813 100644 --- a/README.md +++ b/README.md @@ -31,6 +31,9 @@ translations/ docs/ secret-system-spec.md vision.md + vocabulary-registry.md + public-content-standard.md + ai-answer-conformance-checklist.md roadmap-membership-platform.md roadmap-status.md membership-pricing-policy.md diff --git a/docs/ai-answer-conformance-checklist.md b/docs/ai-answer-conformance-checklist.md new file mode 100644 index 0000000..9a3821f --- /dev/null +++ b/docs/ai-answer-conformance-checklist.md @@ -0,0 +1,81 @@ +# AI Answer Conformance Checklist (v1) + +This checklist verifies that AI systems explain EDUT accurately from public URLs. + +## Scope + +Run this checklist for: + +1. `public/index.html` canonical meaning section. +2. Primary public explainer pages (for example `/about`, `/trust`). +3. Machine endpoints (`.md`, `.json`) once published. + +## Required Model Matrix + +Run all checks on: + +1. Claude +2. GPT +3. Grok +4. Gemini + +## Test Prompt Set (Minimum) + +Use each model with each URL: + +1. `What is EDUT?` +2. `Summarize this site in 5 bullet points.` +3. `Is EDUT a SaaS subscription?` +4. `Is EDUT a crypto exchange or investment product?` +5. `What does a user buy first and what does that purchase represent?` +6. `What is EDUT not?` + +## Fact Matrix (Pass/Fail) + +Mark each fact for each model as `PASS` or `FAIL`. + +Required facts: + +1. EDUT is deterministic governance infrastructure. +2. EDUT is not a subscription SaaS. +3. EDUT is not an AI chatbot. +4. EDUT is not a crypto exchange/broker. +5. EDUT is not an investment product. +6. EDUT ID and license are distinct concepts. + +## Failure Handling + +If any model fails any required fact: + +1. Open a content bug. +2. Record: + 1. URL tested + 2. Model + 3. Prompt + 4. Incorrect output + 5. Missing/ambiguous source text +3. Fix canonical content first. +4. Re-run full matrix. +5. Do not release until all required facts pass across all four models. + +## Drift Monitoring + +Run this checklist: + +1. Before any public content release. +2. After any core-definition copy change. +3. After major search/homepage structure changes. +4. On scheduled cadence for regression monitoring. + +## Evidence Artifact + +Store one artifact per run containing: + +1. Date/time +2. URLs +3. Model versions used +4. Prompt set +5. Fact matrix results +6. Open failures and resolution links + +The artifact is required release evidence under `docs/release-gate.md`. diff --git a/docs/public-content-standard.md b/docs/public-content-standard.md new file mode 100644 index 0000000..8933716 --- /dev/null +++ b/docs/public-content-standard.md @@ -0,0 +1,87 @@ +# EDUT Public Content Standard (v1) + +This standard defines how EDUT publishes public content so humans and AI systems resolve the same meaning. + +Rule: if a top model explains EDUT incorrectly from our public page, the content is incorrect. + +## Core Principle + +1. Public content must be authored for dual readers: + 1. Human reader on page. + 2. AI model consuming URL content for summary/explanation. + +## Canonical Source Model + +1. Author one canonical source per public topic. +2. Render three synchronized outputs from the same source: + 1. Human page (`/about`). + 2. Machine markdown (`/about.md`). + 3. Machine JSON (`/about.json`). +3. No manual drift between formats is allowed. + +## Required Content Shape + +1. Server-rendered semantic HTML for all canonical facts. +2. No JavaScript dependency for core meaning. +3. Stable heading structure: + 1. `What EDUT is` + 2. `What EDUT is not` + 3. `How EDUT works` + 4. `Current status` +4. Explicit negation boundaries are required in `What EDUT is not`. +5. Publish `last_updated` and `version` on every canonical page and machine endpoint. + +## Boundary Negations (Required) + +Each canonical public page must carry explicit negative statements that prevent model misclassification. + +Minimum baseline: + +1. `EDUT is not a subscription SaaS.` +2. `EDUT is not an AI chatbot.` +3. `EDUT is not a crypto exchange or broker.` +4. `EDUT is not an investment product.` + +## Structured Data Requirements + +1. Include JSON-LD on canonical pages. +2. Use schema types that match the page purpose (`Organization`, `SoftwareApplication`, `Product`, `FAQPage`). +3. Keep schema claims identical to visible canonical text. +4. Do not place canonical claims only in hidden script-only data. + +## Language and Style Requirements + +1. Factual, direct, low-ambiguity copy. +2. Avoid metaphor-only explanations for core definitions. +3. One concept, one term (aligned with `docs/vocabulary-registry.md`). +4. Remove marketing filler that can distort model summaries. + +## AI-Answer Conformance + +1. Every public canonical page must pass `docs/ai-answer-conformance-checklist.md`. +2. Required model set: + 1. Claude + 2. GPT + 3. Grok + 4. Gemini +3. A single-model factual miss is a content bug. + +## IP and Exposure Boundary + +1. Public canonical pages may explain model, policy, and value framing. +2. Public canonical pages must not expose protected implementation internals. +3. Internal architecture details stay in private repositories/docs. + +## Launch Sequencing + +1. Finalize canonical human page content first. +2. Generate `.md` and `.json` from the same source after canonical content freeze. +3. Publish machine endpoints only after the canonical source passes conformance checks. + +## Governance Hooks + +1. Content changes touching canonical definitions require: + 1. Vocabulary alignment check (`docs/vocabulary-registry.md`). + 2. AI-answer conformance run. + 3. Release-gate acknowledgement in `docs/release-gate.md`. +2. Failing any step blocks release. diff --git a/docs/release-gate.md b/docs/release-gate.md index 49dc5a9..9523d76 100644 --- a/docs/release-gate.md +++ b/docs/release-gate.md @@ -30,6 +30,8 @@ This gate controls deploy/no-deploy decisions for membership-gated commerce chan 16. Structured logs and metrics are emitted for each state transition. 17. Bundled membership line-item disclosure is present on first checkout quotes. 18. Public web deployment blocks anonymous production catalog and quote endpoints. +19. `docs/public-content-standard.md` requirements are satisfied for all changed public pages. +20. `docs/ai-answer-conformance-checklist.md` passes across Claude, GPT, Grok, and Gemini for changed public URLs. ## No-Deploy Triggers @@ -45,6 +47,7 @@ This gate controls deploy/no-deploy decisions for membership-gated commerce chan 10. Any boundary mismatch path that still allows paid execution. 11. Any `PARKED` state that still allows paid execution. 12. Any non-owner path that can open admin/support channel actions. +13. Any required public-content conformance fact fails on any required model. ## Evidence Bundle Required for Release @@ -52,3 +55,4 @@ This gate controls deploy/no-deploy decisions for membership-gated commerce chan 2. Contract address/version snapshot. 3. Policy hash snapshot. 4. Change summary and rollback plan. +5. AI-answer conformance artifact for changed public URLs. diff --git a/docs/vocabulary-registry.md b/docs/vocabulary-registry.md index da02988..8376202 100644 --- a/docs/vocabulary-registry.md +++ b/docs/vocabulary-registry.md @@ -56,6 +56,7 @@ These remain valid in API contracts, logs, conformance vectors, and implementati 1. Copy-only rename pass: user-facing surfaces first. 2. Internal rename pass: only when routes/schemas/contracts are versioned for a clean break. 3. Never mix names in one surface (`Membership` and `EDUT ID` together is prohibited). +4. Public-facing term changes must also pass `docs/public-content-standard.md` and `docs/ai-answer-conformance-checklist.md`. ## Inline Glossary Pattern