[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6CSFDEV5N50FJQ33VC4P9BA":3,"skill-same:01M6CSFDEV5N50FJQ33VC4P9BA":123},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":39,"linkOnly":40,"markdownContent":41,"markdownBody":42,"frontMatter":43,"refName":69,"commitSha":70,"skillDirectory":71,"forksCount":72,"repositoryHtmlUrl":73,"repositoryHomepageUrl":73,"ownerHtmlUrl":74,"ownerBlogUrl":6,"ownerDescription":75,"updatedAt":76,"install":77,"resources":90},"01M6CSFDEV5N50FJQ33VC4P9BA","clarity-gate",null,"Pre-ingestion verification for epistemic quality in RAG systems. Ensures documents are properly qualified before entering knowledge bases. Produces CGD (Clarity-Gated Documents) and validates SOT (Source of Truth) files.","Sam-06060\u002Fjarvis-assistant","Sam-06060","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F208600848?v=4","01M6CRKT7C7FXD21V6HXF293S0","Samson Frank Ganta","01M6CRKTBEKYFD8YX5Z1GT99EE",6,"CC-BY-4.0","https:\u002F\u002Fgithub.com\u002FSam-06060\u002Fjarvis-assistant\u002Fblob\u002Fmain\u002Fmodules\u002Fagent_skills\u002Fawesome-skills\u002Fplaybooks\u002Fclarity-gate\u002FSKILL.md",[],[19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38],"clarity gate","gate","clarity","check","gated","community","document","files","bases","ingestion","read","review","quality","format","knowledge","verify","verification","rag","documents","github","2026-11-10 10:12:30",false,"---\n# agentskills.io compliant frontmatter\nname: clarity-gate\nrisk: unknown\nsource: community\nversion: 2.1.3\ndescription: >\n  Pre-ingestion verification for epistemic quality in RAG systems.\n  Ensures documents are properly qualified before entering knowledge bases.\n  Produces CGD (Clarity-Gated Documents) and validates SOT (Source of Truth) files.\nauthor: Francesco Marinoni Moretto\nlicense: CC-BY-4.0\nrepository: https:\u002F\u002Fgithub.com\u002Ffrmoretto\u002Fclarity-gate\ntriggers:\n  - clarity gate\n  - check for hallucination risks\n  - can an LLM read this safely\n  - review for equivocation\n  - verify document clarity\n  - pre-ingestion check\n  - cgd verify\n  - sot verify\ncapabilities:\n  - document-verification\n  - epistemic-quality\n  - rag-preparation\n  - cgd-generation\n  - sot-validation\noutputs:\n  - type: cgd\n    extension: .cgd.md\n    spec: docs\u002FCLARITY_GATE_FORMAT_SPEC.md\nspec_version: \"2.1\"\n---\n\n# Clarity Gate v2.1\n\n**Purpose:** Pre-ingestion verification system that enforces epistemic quality before documents enter RAG knowledge bases. Produces Clarity-Gated Documents (CGD) compliant with the Clarity Gate Format Specification v2.1.\n\n**Core Question:** \"If another LLM reads this document, will it mistake assumptions for facts?\"\n\n**Core Principle:** *\"Detection finds what is; enforcement ensures what should be. In practice: find the missing uncertainty markers before they become confident hallucinations.\"*\n\n---\n\n## What's New in v2.1\n\n| Feature | Description |\n|---------|-------------|\n| **Claim Completion Status** | PENDING\u002FVERIFIED determined by field presence (no explicit status field) |\n| **Source Field Semantics** | Actionable source (PENDING) vs. what-was-found (VERIFIED) |\n| **Claim ID Format Guidance** | Hash-based IDs preferred, collision analysis for scale |\n| **Body Structure Requirements** | HITL Verification Record section mandatory when claims exist |\n| **New Validation Codes** | E-ST10, W-ST11, W-HC01, W-HC02, E-SC06 (FORMAT_SPEC); E-TB01-07 (SOT validation) |\n| **Bundled Scripts** | `claim_id.py` and `document_hash.py` for deterministic computations |\n\n---\n\n## Specifications\n\nThis skill implements and references:\n\n| Specification | Version | Location |\n|---------------|---------|----------|\n| Clarity Gate Format (Unified) | v2.1 | docs\u002FCLARITY_GATE_FORMAT_SPEC.md |\n\n**Note:** v2.0 unifies CGD and SOT into a single `.cgd.md` format. SOT is now a CGD with an optional `tier:` block.\n\n---\n\n## Validation Codes\n\nClarity Gate defines validation codes for structural and semantic checks per FORMAT_SPEC v2.1:\n\n### HITL Claim Validation (§1.3.2-1.3.3)\n| Code | Check | Severity |\n|------|-------|----------|\n| **W-HC01** | Partial `confirmed-by`\u002F`confirmed-date` fields | WARNING |\n| **W-HC02** | Vague source (e.g., \"industry reports\", \"TBD\") | WARNING |\n| **E-SC06** | Schema error in `hitl-claims` structure | ERROR |\n\n### Body Structure (§1.2.1)\n| Code | Check | Severity |\n|------|-------|----------|\n| **E-ST10** | Missing `## HITL Verification Record` when claims exist | ERROR |\n| **W-ST11** | Table rows don't match `hitl-claims` count | WARNING |\n\n### SOT Table Validation (§3.1)\n| Code | Check | Severity |\n|------|-------|----------|\n| **E-TB01** | No `## Verified Claims` section | ERROR |\n| **E-TB02** | Table has no data rows | ERROR |\n| **E-TB03** | Required columns missing | ERROR |\n| **E-TB04** | Column order wrong | ERROR |\n| **E-TB05** | Empty cell in required column | ERROR |\n| **E-TB06** | Invalid date format in Verified column | ERROR |\n| **E-TB07** | Verified date in future (beyond 24h grace) | ERROR |\n\n**Note:** Additional validation codes may be defined in RFC-001 (clarification document) but are not part of the normative FORMAT_SPEC.\n\n---\n\n## Bundled Scripts\n\nThis skill includes Python scripts for deterministic computations per FORMAT_SPEC.\n\n### scripts\u002Fclaim_id.py\n\nComputes stable, hash-based claim IDs for HITL tracking (per §1.3.4).\n\n```bash\n# Generate claim ID\npython scripts\u002Fclaim_id.py \"Base price is $99\u002Fmo\" \"api-pricing\u002F1\"\n# Output: claim-75fb137a\n\n# Run test vectors\npython scripts\u002Fclaim_id.py --test\n```\n\n**Algorithm:**\n1. Normalize text (strip + collapse whitespace)\n2. Concatenate with location using pipe delimiter\n3. SHA-256 hash, take first 8 hex chars\n4. Prefix with \"claim-\"\n\n**Test vectors:**\n- `claim_id(\"Base price is $99\u002Fmo\", \"api-pricing\u002F1\")` → `claim-75fb137a`\n- `claim_id(\"The API supports GraphQL\", \"features\u002F1\")` → `claim-eb357742`\n\n### scripts\u002Fdocument_hash.py\n\nComputes document SHA-256 hash per FORMAT_SPEC §2.2-2.4 with full canonicalization.\n\n```bash\n# Compute hash\npython scripts\u002Fdocument_hash.py my-doc.cgd.md\n# Output: 7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded97730\n\n# Verify existing hash\npython scripts\u002Fdocument_hash.py --verify my-doc.cgd.md\n# Output: PASS: Hash verified: 7d865e...\n\n# Run normalization tests\npython scripts\u002Fdocument_hash.py --test\n```\n\n**Algorithm (per §2.2-2.4):**\n1. Extract content between opening `---\\n` and `\u003C!-- CLARITY_GATE_END -->`\n2. Remove `document-sha256` line from YAML frontmatter ONLY (with multiline continuation support)\n3. Canonicalize:\n   - Strip trailing whitespace per line\n   - Collapse 3+ consecutive newlines to 2\n   - Normalize final newline (exactly 1 LF)\n   - UTF-8 NFC normalization\n4. Compute SHA-256\n\n**Cross-platform normalization:**\n- BOM removed if present\n- CRLF to LF (Windows)\n- CR to LF (old Mac)\n- Boundary detection (prevents hash computation on content outside CGD structure)\n- Whitespace variations produce identical hashes (deterministic across platforms)\n\n---\n\n## The Key Distinction\n\nExisting tools like UnScientify and HedgeHunter (CoNLL-2010) **detect** uncertainty markers already present in text (\"Is uncertainty expressed?\").\n\nClarity Gate **enforces** their presence where epistemically required (\"Should uncertainty be expressed but isn't?\").\n\n| Tool Type | Question | Example |\n|-----------|----------|---------|\n| **Detection** | \"Does this text contain hedges?\" | UnScientify\u002FHedgeHunter find \"may\", \"possibly\" |\n| **Enforcement** | \"Should this claim be hedged but isn't?\" | Clarity Gate flags \"Revenue will be $50M\" |\n\n---\n\n## Critical Limitation\n\n> **Clarity Gate verifies FORM, not TRUTH.**\n>\n> This skill checks whether claims are properly marked as uncertain—it cannot verify if claims are actually true. \n>\n> **Risk:** An LLM can hallucinate facts INTO a document, then \"pass\" Clarity Gate by adding source markers to false claims.\n>\n> **Solution:** HITL (Human-In-The-Loop) verification is **MANDATORY** before declaring PASS.\n\n---\n\n## When to Use\n- Before ingesting documents into RAG systems\n- Before sharing documents with other AI systems\n- After writing specifications, state docs, or methodology descriptions\n- When a document contains projections, estimates, or hypotheses\n- Before publishing claims that haven't been validated\n- When handing off documentation between LLM sessions\n\n---\n\n## The 9 Verification Points\n\n### Relationship to Spec Suite\n\nThe 9 Verification Points guide **semantic review** — content quality checks that require judgment (human or AI). They answer questions like \"Should this claim be hedged?\" and \"Are these numbers consistent?\"\n\nWhen review completes, output a CGD file conforming to CLARITY_GATE_FORMAT_SPEC.md. The C\u002FS rules in CLARITY_GATE_FORMAT_SPEC.md validate **file structure**, not semantic content.\n\n**The connection:**\n1. Semantic findings (9 points) determine what issues exist\n2. Issues are recorded in CGD state fields (`clarity-status`, `hitl-status`, `hitl-pending-count`)\n3. State consistency is enforced by structural rules (C7-C10)\n\n*Example: If Point 5 (Data Consistency) finds conflicting numbers, you'd mark `clarity-status: UNCLEAR` until resolved. Rule C7 then ensures you can't claim `REVIEWED` while still `UNCLEAR`.*\n\n---\n\n### Epistemic Checks (Core Focus: Points 1-4)\n\n**1. HYPOTHESIS vs FACT LABELING**\nEvery claim must be clearly marked as validated or hypothetical.\n\n| Fails | Passes |\n|-------|--------|\n| \"Our architecture outperforms competitors\" | \"Our architecture outperforms competitors [benchmark data in Table 3]\" |\n| \"The model achieves 40% improvement\" | \"The model achieves 40% improvement [measured on dataset X]\" |\n\n**Fix:** Add markers: \"PROJECTED:\", \"HYPOTHESIS:\", \"UNTESTED:\", \"(estimated)\", \"~\", \"?\"\n\n---\n\n**2. UNCERTAINTY MARKER ENFORCEMENT**\nForward-looking statements require qualifiers.\n\n| Fails | Passes |\n|-------|--------|\n| \"Revenue will be $50M by Q4\" | \"Revenue is **projected** to be $50M by Q4\" |\n| \"The feature will reduce churn\" | \"The feature is **expected** to reduce churn\" |\n\n**Fix:** Add \"projected\", \"estimated\", \"expected\", \"designed to\", \"intended to\"\n\n---\n\n**3. ASSUMPTION VISIBILITY**\nImplicit assumptions that affect interpretation must be explicit.\n\n| Fails | Passes |\n|-------|--------|\n| \"The system scales linearly\" | \"The system scales linearly [assuming \u003C1000 concurrent users]\" |\n| \"Response time is 50ms\" | \"Response time is 50ms [under standard load conditions]\" |\n\n**Fix:** Add bracketed conditions: \"[assuming X]\", \"[under conditions Y]\", \"[when Z]\"\n\n---\n\n**4. AUTHORITATIVE-LOOKING UNVALIDATED DATA**\nTables with specific percentages and checkmarks look like measured data.\n\n**Red flag:** Tables with specific numbers (89%, 95%, 100%) without sources\n\n**Fix:** Add \"(guess)\", \"(est.)\", \"?\" to numbers. Add explicit warning: \"PROJECTED VALUES - NOT MEASURED\"\n\n---\n\n### Data Quality Checks (Complementary: Points 5-7)\n\n**5. DATA CONSISTENCY**\nScan for conflicting numbers, dates, or facts within the document.\n\n**Red flag:** \"500 users\" in one section, \"750 users\" in another\n\n**Fix:** Reconcile conflicts or explicitly note the discrepancy with explanation.\n\n---\n\n**6. IMPLICIT CAUSATION**\nClaims that imply causation without evidence.\n\n**Red flag:** \"Shorter prompts improve response quality\" (plausible but unproven)\n\n**Fix:** Reframe as hypothesis: \"Shorter prompts MAY improve response quality (hypothesis, not validated)\"\n\n---\n\n**7. FUTURE STATE AS PRESENT**\nDescribing planned\u002Fhoped outcomes as if already achieved.\n\n**Red flag:** \"The system processes 10,000 requests per second\" (when it hasn't been built)\n\n**Fix:** Use future\u002Fconditional: \"The system is DESIGNED TO process...\" or \"TARGET: 10,000 rps\"\n\n---\n\n### Verification Routing (Points 8-9)\n\n**8. TEMPORAL COHERENCE**\nDocument dates and timestamps must be internally consistent and plausible.\n\n| Fails | Passes |\n|-------|--------|\n| \"Last Updated: December 2024\" (when current is 2026) | \"Last Updated: January 2026\" |\n| v1.0.0 dated 2024-12-23, v1.1.0 dated 2024-12-20 | Versions in chronological order |\n\n**Sub-checks:**\n1. Document date vs current date\n2. Internal chronology (versions, events in order)\n3. Reference freshness (\"current\", \"now\", \"today\" claims)\n\n**Fix:** Update dates, add \"as of [date]\" qualifiers, flag stale claims\n\n---\n\n**9. EXTERNALLY VERIFIABLE CLAIMS**\nSpecific numbers that could be fact-checked should be flagged for verification.\n\n| Type | Example | Risk |\n|------|---------|------|\n| Pricing | \"Costs ~$0.005 per call\" | API pricing changes |\n| Statistics | \"Papers average 15-30 equations\" | May be wildly off |\n| Rates\u002Fratios | \"40% of researchers use X\" | Needs citation |\n| Competitor claims | \"No competitor offers Y\" | May be outdated |\n\n**Fix options:**\n1. Add source with date\n2. Add uncertainty marker\n3. Route to HITL or external search\n4. Generalize (\"low cost\" instead of \"$0.005\")\n\n---\n\n## The Verification Hierarchy\n\n```\nClaim Extracted --> Does Source of Truth Exist?\n                           |\n           +---------------+---------------+\n           YES                             NO\n           |                               |\n   Tier 1: Automated              Tier 2: HITL\n   Consistency & Verification     Two-Round Verification\n           |                               |\n   PASS \u002F BLOCK                   Round A → Round B → APPROVE \u002F REJECT\n```\n\n### Tier 1: Automated Verification\n\n**A. Internal Consistency**\n- Figure vs. Text contradictions\n- Abstract vs. Body mismatches\n- Table vs. Prose conflicts\n- Numerical consistency\n\n**B. External Verification (Extension Interface)**\n- User-provided connectors to structured sources\n- Financial systems, Git commits, CRM, etc.\n\n### Tier 2: Two-Round HITL Verification — MANDATORY\n\n**Round A: Derived Data Confirmation**\n- Claims from sources found in session\n- Human confirms interpretation, not truth\n\n**Round B: True HITL Verification**\n- Claims needing actual verification\n- No source found, human's own data, extrapolations\n\n---\n\n## CGD Output Format\n\nWhen producing a Clarity-Gated Document, use this format per CLARITY_GATE_FORMAT_SPEC.md v2.1:\n\n```yaml\n---\nclarity-gate-version: 2.1\nprocessed-date: 2026-01-12\nprocessed-by: Claude + Human Review\nclarity-status: CLEAR\nhitl-status: REVIEWED\nhitl-pending-count: 0\npoints-passed: 1-9\nrag-ingestable: true          # computed by validator - do not set manually\ndocument-sha256: 7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded97730\nhitl-claims:\n  - id: claim-75fb137a\n    text: \"Revenue projection is $50M\"\n    value: \"$50M\"\n    source: \"Q3 planning doc\"\n    location: \"revenue-projections\u002F1\"\n    round: B\n    confirmed-by: Francesco\n    confirmed-date: 2026-01-12\n---\n\n# Document Title\n\n[Document body with epistemic markers applied]\n\nClaims like \"Revenue will be $50M\" become \"Revenue is **projected** to be $50M *(unverified projection)*\"\n\n---\n\n## HITL Verification Record\n\n### Round A: Derived Data Confirmation\n- Claim 1 (source) ✓\n- Claim 2 (source) ✓\n\n### Round B: True HITL Verification\n| # | Claim | Status | Verified By | Date |\n|---|-------|--------|-------------|------|\n| 1 | [claim] | ✓ Confirmed | [name] | [date] |\n\n\u003C!-- CLARITY_GATE_END -->\nClarity Gate: CLEAR | REVIEWED\n```\n\n**Required CGD Elements (per spec):**\n- YAML frontmatter with all required fields:\n  - `clarity-gate-version` — Tool version (no \"v\" prefix)\n  - `processed-date` — YYYY-MM-DD format\n  - `processed-by` — Processor name\n  - `clarity-status` — CLEAR or UNCLEAR\n  - `hitl-status` — PENDING, REVIEWED, or REVIEWED_WITH_EXCEPTIONS\n  - `hitl-pending-count` — Integer ≥ 0\n  - `points-passed` — e.g., `1-9` or `1-4,7,9`\n  - `hitl-claims` — List of verified claims (may be empty `[]`)\n- End marker (HTML comment + status line):\n  ```\n  \u003C!-- CLARITY_GATE_END -->\n  Clarity Gate: \u003Cclarity-status> | \u003Chitl-status>\n  ```\n- HITL verification record (if status is REVIEWED)\n\n**Optional\u002FComputed Fields:**\n- `rag-ingestable` — **Computed by validators**, not manually set. Shows `true` only when `CLEAR | REVIEWED` with no exclusion blocks.\n- `document-sha256` — Required. 64-char lowercase hex hash for integrity verification. See spec §2 for computation rules.\n- `exclusions-coverage` — Optional. Fraction of body inside exclusion blocks (0.0–1.0).\n\n**Escape Mechanism:** To write about markers like `*(estimated)*` without triggering parsing, wrap in backticks: `` `*(estimated)*` ``\n\n### Claim Completion Status (v2.1)\n\nClaim verification status is determined by field **presence**, not an explicit status field:\n\n| State | `confirmed-by` | `confirmed-date` | Meaning |\n|-------|----------------|------------------|----------|\n| **PENDING** | absent | absent | Awaiting human verification |\n| **VERIFIED** | present | present | Human has confirmed |\n| *(invalid)* | present | absent | W-HC01: partial fields |\n| *(invalid)* | absent | present | W-HC01: partial fields |\n\n**Why no explicit status field?** Field presence is self-enforcing—you can't accidentally set status without providing who\u002Fwhen.\n\n### Source Field Semantics (v2.1)\n\nThe `source` field meaning changes based on claim state:\n\n| State | `source` Contains | Example |\n|-------|-------------------|----------|\n| **PENDING** | Where to verify (actionable) | `\"Check Q3 planning doc\"` |\n| **VERIFIED** | What was found (evidence) | `\"Q3 planning doc, page 12\"` |\n\n**Vague source detection (W-HC02):** Sources like `\"industry reports\"`, `\"research\"`, `\"TBD\"` trigger warnings.\n\n### Claim ID Format (v2.1)\n\n**General pattern:** `claim-[a-z0-9._-]{1,64}` (alphanumeric, dots, underscores, hyphens)\n\n| Approach | Pattern | Example | Use Case |\n|----------|---------|---------|----------|\n| **Hash-based** (preferred) | `claim-[a-f0-9]{8,}` | `claim-75fb137a` | Deterministic, collision-resistant |\n| **Sequential** | `claim-[0-9]+` | `claim-1`, `claim-2` | Simple documents |\n| **Semantic** | `claim-[a-z0-9-]+` | `claim-revenue-q3` | Human-friendly |\n\n**Collision probability:** At 1,000 claims with 8-char hex IDs: ~0.012%. For >1,000 claims, use 12+ hex characters.\n\n**Recommendation:** Use hash-based IDs generated by `scripts\u002Fclaim_id.py` for consistency and collision resistance.\n\n---\n\n## Exclusion Blocks\n\nWhen content cannot be resolved (no SME available, legacy prose, etc.), mark it as excluded rather than leaving it ambiguous:\n\n```markdown\n\u003C!-- CG-EXCLUSION:BEGIN id=auth-legacy-1 -->\nLegacy authentication details that require SME review...\n\u003C!-- CG-EXCLUSION:END id=auth-legacy-1 -->\n```\n\n**Rules:**\n- IDs must match: `[A-Za-z0-9][A-Za-z0-9._-]{0,63}`\n- No nesting or overlapping blocks\n- Each ID used only once\n- Requires `hitl-status: REVIEWED_WITH_EXCEPTIONS`\n- Must document `exceptions-reason` and `exceptions-ids` in frontmatter\n\n**Important:** Documents with exclusion blocks are **not RAG-ingestable**. They're rejected entirely (no partial ingestion).\n\nSee CLARITY_GATE_FORMAT_SPEC.md §4 for complete rules.\n\n---\n\n## SOT Validation\n\nWhen validating a Source of Truth file, the skill checks both **format compliance** (per CLARITY_GATE_FORMAT_SPEC.md) and **content quality** (the 9 points).\n\n### Format Compliance (Structural Rules)\n\nSOT documents are CGDs with a `tier:` block. They require a `## Verified Claims` section with a valid table.\n\n| Code | Check | Severity |\n|------|-------|----------|\n| E-TB01 | No `## Verified Claims` section | ERROR |\n| E-TB02 | Table has no data rows | ERROR |\n| E-TB03 | Required columns missing (Claim, Value, Source, Verified) | ERROR |\n| E-TB04 | Column order wrong (Claim not first or Verified not last) | ERROR |\n| E-TB05 | Empty cell in required column | ERROR |\n| E-TB06 | Invalid date format in Verified column | ERROR |\n| E-TB07 | Verified date in future (beyond 24h grace) | ERROR |\n\n### Content Quality (9 Points)\n\nThe 9 Verification Points apply to SOT content:\n\n| Point | SOT Application |\n|-------|-----------------|\n| 1-4 | Check claims in `## Verified Claims` are actually verified |\n| 5 | Check for conflicting values across tables |\n| 6 | Check claims don't imply unsupported causation |\n| 7 | Check table doesn't state futures as present |\n| 8 | Check dates are chronologically consistent |\n| 9 | Flag specific numbers for external check |\n\n### SOT-Specific Requirements\n\n- **Tier block required:** SOT is a CGD with `tier:` block containing `level`, `owner`, `version`, `promoted-date`, `promoted-by`\n- **Structured claims table:** `## Verified Claims` section with columns: Claim, Value, Source, Verified\n- **Table outside exclusions:** The verified claims table must NOT be inside an exclusion block\n- **Staleness markers:** Use `[STABLE]`, `[CHECK]`, `[VOLATILE]`, `[SNAPSHOT]` in content\n  - `[STABLE]` — Safe to cite without rechecking\n  - `[CHECK]` — Verify before citing\n  - `[VOLATILE]` — Changes frequently; always verify\n  - `[SNAPSHOT]` — Point-in-time data; include date when citing\n\n---\n\n## Output Format\n\nAfter running Clarity Gate, report:\n\n```\n## Clarity Gate Results\n\n**Document:** [filename]\n**Issues Found:** [number]\n\n### Critical (will cause hallucination)\n- [issue + location + fix]\n\n### Warning (could cause equivocation)  \n- [issue + location + fix]\n\n### Temporal (date\u002Ftime issues)\n- [issue + location + fix]\n\n### Externally Verifiable Claims\n| # | Claim | Type | Suggested Verification |\n|---|-------|------|------------------------|\n| 1 | [claim] | Pricing | [where to verify] |\n\n---\n\n## Round A: Derived Data Confirmation\n\n- [claim] ([source])\n\nReply \"confirmed\" or flag any I misread.\n\n---\n\n## Round B: HITL Verification Required\n\n| # | Claim | Why HITL Needed | Human Confirms |\n|---|-------|-----------------|----------------|\n| 1 | [claim] | [reason] | [ ] True \u002F [ ] False |\n\n---\n\n**Would you like me to produce an annotated CGD version?**\n\n---\n\n**Verdict:** PENDING CONFIRMATION\n```\n\n---\n\n## Severity Levels\n\n| Level | Definition | Action |\n|-------|------------|--------|\n| **CRITICAL** | LLM will likely treat hypothesis as fact | Must fix before use |\n| **WARNING** | LLM might misinterpret | Should fix |\n| **TEMPORAL** | Date\u002Ftime inconsistency detected | Verify and update |\n| **VERIFIABLE** | Specific claim that could be fact-checked | Route to HITL or external search |\n| **ROUND A** | Derived from witnessed source | Quick confirmation |\n| **ROUND B** | Requires true verification | Cannot pass without confirmation |\n| **PASS** | Clearly marked, no ambiguity, verified | No action needed |\n\n---\n\n## Quick Scan Checklist\n\n| Pattern | Action |\n|---------|--------|\n| Specific percentages (89%, 73%) | Add source or mark as estimate |\n| Comparison tables | Add \"PROJECTED\" header |\n| \"Achieves\", \"delivers\", \"provides\" | Use \"designed to\", \"intended to\" if not validated |\n| Checkmarks | Verify these are confirmed |\n| \"100%\" anything | Almost always needs qualification |\n| \"Last Updated: [date]\" | Check against current date |\n| Version numbers with dates | Verify chronological order |\n| \"$X.XX\" or \"~$X\" (pricing) | Flag for external verification |\n| \"averages\", \"typically\" | Flag for source\u002Fcitation |\n| Competitor capability claims | Flag for external verification |\n\n---\n\n## What This Skill Does NOT Do\n\n- Does not classify document types (use Stream Coding for that)\n- Does not restructure documents \n- Does not add deep links or references\n- Does not evaluate writing quality\n- **Does not check factual accuracy autonomously** (requires HITL)\n\n---\n\n## Related Projects\n\n| Project | Purpose | URL |\n|---------|---------|-----|\n| Source of Truth Creator | Create epistemically calibrated docs | github.com\u002Ffrmoretto\u002Fsource-of-truth-creator |\n| Stream Coding | Documentation-first methodology | github.com\u002Ffrmoretto\u002Fstream-coding |\n| ArXiParse | Scientific paper verification | arxiparse.org |\n\n---\n\n## Changelog\n\n### v2.1.3 (2026-03-02)\n- **FIXED:** `document_hash.py` now implements full FORMAT_SPEC §2.1-2.4 compliance\n- **FIXED:** Fence-aware end marker detection (Quine Protection per §2.3\u002F§8.5)\n- **FIXED:** All 4 deployment copies converged to single canonical implementation\n- **ADDED:** `canonicalize()` function: trailing whitespace stripping, newline collapsing, NFC normalization\n- **ADDED:** YAML-aware `document-sha256` removal with multiline continuation support (§2.2)\n- **ADDED:** Fence-tracking test vectors (7 new tests, 15 total)\n\n### v2.1.0 (2026-01-27)\n- **ADDED:** Claim Completion Status semantics (PENDING\u002FVERIFIED by field presence)\n- **ADDED:** Source Field Semantics (actionable vs. what-was-found)\n- **ADDED:** Claim ID Format guidance with collision analysis\n- **ADDED:** Body Structure Requirements (HITL Verification Record mandatory when claims exist)\n- **ADDED:** New validation codes: E-ST10, W-ST11, W-HC01, W-HC02, E-SC06 (FORMAT_SPEC §1.2-1.3)\n- **ADDED:** Bundled scripts: `claim_id.py`, `document_hash.py`\n- **UPDATED:** References to FORMAT_SPEC v2.1\n- **UPDATED:** CGD output example to version 2.1\n\n### v2.0.0 (2026-01-13)\n- **ADDED:** agentskills.io compliant YAML frontmatter\n- **ADDED:** Clarity Gate Format Specification v2.0 compliance (unified CGD\u002FSOT)\n- **ADDED:** SOT validation support with E-TB* error codes\n- **ADDED:** Validation rules mapping (9 points → rule codes)\n- **ADDED:** CGD output format template with `\u003C!-- CLARITY_GATE_END -->` markers\n- **ADDED:** Quine Protection note (§2.3 fence-aware marker detection)\n- **ADDED:** Redacted Export feature (§8.11)\n- **UPDATED:** `hitl-claims` format to v2.0 schema (id, text, value, source, location, round)\n- **UPDATED:** End marker format to HTML comment style\n- **UPDATED:** Unified format spec v2.0 (single `.cgd.md` extension)\n- **RESTRUCTURED:** For multi-platform skill discovery\n\n### v1.6 (2025-12-31)\n- Added Two-Round HITL verification system\n- Round A: Derived Data Confirmation\n- Round B: True HITL Verification\n\n### v1.5 (2025-12-28)\n- Added Point 8: Temporal Coherence\n- Added Point 9: Externally Verifiable Claims\n\n### v1.4 (2025-12-23)\n- Added CGD annotation output mode\n\n### v1.3 (2025-12-21)\n- Restructured points into Epistemic (1-4) and Data Quality (5-7)\n\n### v1.2 (2025-12-21)\n- Added Source of Truth request step\n\n### v1.1 (2025-12-21)\n- Added HITL Fact Verification (mandatory)\n\n### v1.0 (2025-11)\n- Initial release with 6-point verification\n\n---\n\n**Version:** 2.1.3\n**Spec Version:** 2.1\n**Author:** Francesco Marinoni Moretto\n**License:** CC-BY-4.0\n","# Clarity Gate v2.1\n\n**Purpose:** Pre-ingestion verification system that enforces epistemic quality before documents enter RAG knowledge bases. Produces Clarity-Gated Documents (CGD) compliant with the Clarity Gate Format Specification v2.1.\n\n**Core Question:** \"If another LLM reads this document, will it mistake assumptions for facts?\"\n\n**Core Principle:** *\"Detection finds what is; enforcement ensures what should be. In practice: find the missing uncertainty markers before they become confident hallucinations.\"*\n\n---\n\n## What's New in v2.1\n\n| Feature | Description |\n|---------|-------------|\n| **Claim Completion Status** | PENDING\u002FVERIFIED determined by field presence (no explicit status field) |\n| **Source Field Semantics** | Actionable source (PENDING) vs. what-was-found (VERIFIED) |\n| **Claim ID Format Guidance** | Hash-based IDs preferred, collision analysis for scale |\n| **Body Structure Requirements** | HITL Verification Record section mandatory when claims exist |\n| **New Validation Codes** | E-ST10, W-ST11, W-HC01, W-HC02, E-SC06 (FORMAT_SPEC); E-TB01-07 (SOT validation) |\n| **Bundled Scripts** | `claim_id.py` and `document_hash.py` for deterministic computations |\n\n---\n\n## Specifications\n\nThis skill implements and references:\n\n| Specification | Version | Location |\n|---------------|---------|----------|\n| Clarity Gate Format (Unified) | v2.1 | docs\u002FCLARITY_GATE_FORMAT_SPEC.md |\n\n**Note:** v2.0 unifies CGD and SOT into a single `.cgd.md` format. SOT is now a CGD with an optional `tier:` block.\n\n---\n\n## Validation Codes\n\nClarity Gate defines validation codes for structural and semantic checks per FORMAT_SPEC v2.1:\n\n### HITL Claim Validation (§1.3.2-1.3.3)\n| Code | Check | Severity |\n|------|-------|----------|\n| **W-HC01** | Partial `confirmed-by`\u002F`confirmed-date` fields | WARNING |\n| **W-HC02** | Vague source (e.g., \"industry reports\", \"TBD\") | WARNING |\n| **E-SC06** | Schema error in `hitl-claims` structure | ERROR |\n\n### Body Structure (§1.2.1)\n| Code | Check | Severity |\n|------|-------|----------|\n| **E-ST10** | Missing `## HITL Verification Record` when claims exist | ERROR |\n| **W-ST11** | Table rows don't match `hitl-claims` count | WARNING |\n\n### SOT Table Validation (§3.1)\n| Code | Check | Severity |\n|------|-------|----------|\n| **E-TB01** | No `## Verified Claims` section | ERROR |\n| **E-TB02** | Table has no data rows | ERROR |\n| **E-TB03** | Required columns missing | ERROR |\n| **E-TB04** | Column order wrong | ERROR |\n| **E-TB05** | Empty cell in required column | ERROR |\n| **E-TB06** | Invalid date format in Verified column | ERROR |\n| **E-TB07** | Verified date in future (beyond 24h grace) | ERROR |\n\n**Note:** Additional validation codes may be defined in RFC-001 (clarification document) but are not part of the normative FORMAT_SPEC.\n\n---\n\n## Bundled Scripts\n\nThis skill includes Python scripts for deterministic computations per FORMAT_SPEC.\n\n### scripts\u002Fclaim_id.py\n\nComputes stable, hash-based claim IDs for HITL tracking (per §1.3.4).\n\n```bash\n# Generate claim ID\npython scripts\u002Fclaim_id.py \"Base price is $99\u002Fmo\" \"api-pricing\u002F1\"\n# Output: claim-75fb137a\n\n# Run test vectors\npython scripts\u002Fclaim_id.py --test\n```\n\n**Algorithm:**\n1. Normalize text (strip + collapse whitespace)\n2. Concatenate with location using pipe delimiter\n3. SHA-256 hash, take first 8 hex chars\n4. Prefix with \"claim-\"\n\n**Test vectors:**\n- `claim_id(\"Base price is $99\u002Fmo\", \"api-pricing\u002F1\")` → `claim-75fb137a`\n- `claim_id(\"The API supports GraphQL\", \"features\u002F1\")` → `claim-eb357742`\n\n### scripts\u002Fdocument_hash.py\n\nComputes document SHA-256 hash per FORMAT_SPEC §2.2-2.4 with full canonicalization.\n\n```bash\n# Compute hash\npython scripts\u002Fdocument_hash.py my-doc.cgd.md\n# Output: 7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded97730\n\n# Verify existing hash\npython scripts\u002Fdocument_hash.py --verify my-doc.cgd.md\n# Output: PASS: Hash verified: 7d865e...\n\n# Run normalization tests\npython scripts\u002Fdocument_hash.py --test\n```\n\n**Algorithm (per §2.2-2.4):**\n1. Extract content between opening `---\\n` and `\u003C!-- CLARITY_GATE_END -->`\n2. Remove `document-sha256` line from YAML frontmatter ONLY (with multiline continuation support)\n3. Canonicalize:\n   - Strip trailing whitespace per line\n   - Collapse 3+ consecutive newlines to 2\n   - Normalize final newline (exactly 1 LF)\n   - UTF-8 NFC normalization\n4. Compute SHA-256\n\n**Cross-platform normalization:**\n- BOM removed if present\n- CRLF to LF (Windows)\n- CR to LF (old Mac)\n- Boundary detection (prevents hash computation on content outside CGD structure)\n- Whitespace variations produce identical hashes (deterministic across platforms)\n\n---\n\n## The Key Distinction\n\nExisting tools like UnScientify and HedgeHunter (CoNLL-2010) **detect** uncertainty markers already present in text (\"Is uncertainty expressed?\").\n\nClarity Gate **enforces** their presence where epistemically required (\"Should uncertainty be expressed but isn't?\").\n\n| Tool Type | Question | Example |\n|-----------|----------|---------|\n| **Detection** | \"Does this text contain hedges?\" | UnScientify\u002FHedgeHunter find \"may\", \"possibly\" |\n| **Enforcement** | \"Should this claim be hedged but isn't?\" | Clarity Gate flags \"Revenue will be $50M\" |\n\n---\n\n## Critical Limitation\n\n> **Clarity Gate verifies FORM, not TRUTH.**\n>\n> This skill checks whether claims are properly marked as uncertain—it cannot verify if claims are actually true. \n>\n> **Risk:** An LLM can hallucinate facts INTO a document, then \"pass\" Clarity Gate by adding source markers to false claims.\n>\n> **Solution:** HITL (Human-In-The-Loop) verification is **MANDATORY** before declaring PASS.\n\n---\n\n## When to Use\n- Before ingesting documents into RAG systems\n- Before sharing documents with other AI systems\n- After writing specifications, state docs, or methodology descriptions\n- When a document contains projections, estimates, or hypotheses\n- Before publishing claims that haven't been validated\n- When handing off documentation between LLM sessions\n\n---\n\n## The 9 Verification Points\n\n### Relationship to Spec Suite\n\nThe 9 Verification Points guide **semantic review** — content quality checks that require judgment (human or AI). They answer questions like \"Should this claim be hedged?\" and \"Are these numbers consistent?\"\n\nWhen review completes, output a CGD file conforming to CLARITY_GATE_FORMAT_SPEC.md. The C\u002FS rules in CLARITY_GATE_FORMAT_SPEC.md validate **file structure**, not semantic content.\n\n**The connection:**\n1. Semantic findings (9 points) determine what issues exist\n2. Issues are recorded in CGD state fields (`clarity-status`, `hitl-status`, `hitl-pending-count`)\n3. State consistency is enforced by structural rules (C7-C10)\n\n*Example: If Point 5 (Data Consistency) finds conflicting numbers, you'd mark `clarity-status: UNCLEAR` until resolved. Rule C7 then ensures you can't claim `REVIEWED` while still `UNCLEAR`.*\n\n---\n\n### Epistemic Checks (Core Focus: Points 1-4)\n\n**1. HYPOTHESIS vs FACT LABELING**\nEvery claim must be clearly marked as validated or hypothetical.\n\n| Fails | Passes |\n|-------|--------|\n| \"Our architecture outperforms competitors\" | \"Our architecture outperforms competitors [benchmark data in Table 3]\" |\n| \"The model achieves 40% improvement\" | \"The model achieves 40% improvement [measured on dataset X]\" |\n\n**Fix:** Add markers: \"PROJECTED:\", \"HYPOTHESIS:\", \"UNTESTED:\", \"(estimated)\", \"~\", \"?\"\n\n---\n\n**2. UNCERTAINTY MARKER ENFORCEMENT**\nForward-looking statements require qualifiers.\n\n| Fails | Passes |\n|-------|--------|\n| \"Revenue will be $50M by Q4\" | \"Revenue is **projected** to be $50M by Q4\" |\n| \"The feature will reduce churn\" | \"The feature is **expected** to reduce churn\" |\n\n**Fix:** Add \"projected\", \"estimated\", \"expected\", \"designed to\", \"intended to\"\n\n---\n\n**3. ASSUMPTION VISIBILITY**\nImplicit assumptions that affect interpretation must be explicit.\n\n| Fails | Passes |\n|-------|--------|\n| \"The system scales linearly\" | \"The system scales linearly [assuming \u003C1000 concurrent users]\" |\n| \"Response time is 50ms\" | \"Response time is 50ms [under standard load conditions]\" |\n\n**Fix:** Add bracketed conditions: \"[assuming X]\", \"[under conditions Y]\", \"[when Z]\"\n\n---\n\n**4. AUTHORITATIVE-LOOKING UNVALIDATED DATA**\nTables with specific percentages and checkmarks look like measured data.\n\n**Red flag:** Tables with specific numbers (89%, 95%, 100%) without sources\n\n**Fix:** Add \"(guess)\", \"(est.)\", \"?\" to numbers. Add explicit warning: \"PROJECTED VALUES - NOT MEASURED\"\n\n---\n\n### Data Quality Checks (Complementary: Points 5-7)\n\n**5. DATA CONSISTENCY**\nScan for conflicting numbers, dates, or facts within the document.\n\n**Red flag:** \"500 users\" in one section, \"750 users\" in another\n\n**Fix:** Reconcile conflicts or explicitly note the discrepancy with explanation.\n\n---\n\n**6. IMPLICIT CAUSATION**\nClaims that imply causation without evidence.\n\n**Red flag:** \"Shorter prompts improve response quality\" (plausible but unproven)\n\n**Fix:** Reframe as hypothesis: \"Shorter prompts MAY improve response quality (hypothesis, not validated)\"\n\n---\n\n**7. FUTURE STATE AS PRESENT**\nDescribing planned\u002Fhoped outcomes as if already achieved.\n\n**Red flag:** \"The system processes 10,000 requests per second\" (when it hasn't been built)\n\n**Fix:** Use future\u002Fconditional: \"The system is DESIGNED TO process...\" or \"TARGET: 10,000 rps\"\n\n---\n\n### Verification Routing (Points 8-9)\n\n**8. TEMPORAL COHERENCE**\nDocument dates and timestamps must be internally consistent and plausible.\n\n| Fails | Passes |\n|-------|--------|\n| \"Last Updated: December 2024\" (when current is 2026) | \"Last Updated: January 2026\" |\n| v1.0.0 dated 2024-12-23, v1.1.0 dated 2024-12-20 | Versions in chronological order |\n\n**Sub-checks:**\n1. Document date vs current date\n2. Internal chronology (versions, events in order)\n3. Reference freshness (\"current\", \"now\", \"today\" claims)\n\n**Fix:** Update dates, add \"as of [date]\" qualifiers, flag stale claims\n\n---\n\n**9. EXTERNALLY VERIFIABLE CLAIMS**\nSpecific numbers that could be fact-checked should be flagged for verification.\n\n| Type | Example | Risk |\n|------|---------|------|\n| Pricing | \"Costs ~$0.005 per call\" | API pricing changes |\n| Statistics | \"Papers average 15-30 equations\" | May be wildly off |\n| Rates\u002Fratios | \"40% of researchers use X\" | Needs citation |\n| Competitor claims | \"No competitor offers Y\" | May be outdated |\n\n**Fix options:**\n1. Add source with date\n2. Add uncertainty marker\n3. Route to HITL or external search\n4. Generalize (\"low cost\" instead of \"$0.005\")\n\n---\n\n## The Verification Hierarchy\n\n```\nClaim Extracted --> Does Source of Truth Exist?\n                           |\n           +---------------+---------------+\n           YES                             NO\n           |                               |\n   Tier 1: Automated              Tier 2: HITL\n   Consistency & Verification     Two-Round Verification\n           |                               |\n   PASS \u002F BLOCK                   Round A → Round B → APPROVE \u002F REJECT\n```\n\n### Tier 1: Automated Verification\n\n**A. Internal Consistency**\n- Figure vs. Text contradictions\n- Abstract vs. Body mismatches\n- Table vs. Prose conflicts\n- Numerical consistency\n\n**B. External Verification (Extension Interface)**\n- User-provided connectors to structured sources\n- Financial systems, Git commits, CRM, etc.\n\n### Tier 2: Two-Round HITL Verification — MANDATORY\n\n**Round A: Derived Data Confirmation**\n- Claims from sources found in session\n- Human confirms interpretation, not truth\n\n**Round B: True HITL Verification**\n- Claims needing actual verification\n- No source found, human's own data, extrapolations\n\n---\n\n## CGD Output Format\n\nWhen producing a Clarity-Gated Document, use this format per CLARITY_GATE_FORMAT_SPEC.md v2.1:\n\n```yaml\n---\nclarity-gate-version: 2.1\nprocessed-date: 2026-01-12\nprocessed-by: Claude + Human Review\nclarity-status: CLEAR\nhitl-status: REVIEWED\nhitl-pending-count: 0\npoints-passed: 1-9\nrag-ingestable: true          # computed by validator - do not set manually\ndocument-sha256: 7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded97730\nhitl-claims:\n  - id: claim-75fb137a\n    text: \"Revenue projection is $50M\"\n    value: \"$50M\"\n    source: \"Q3 planning doc\"\n    location: \"revenue-projections\u002F1\"\n    round: B\n    confirmed-by: Francesco\n    confirmed-date: 2026-01-12\n---\n\n# Document Title\n\n[Document body with epistemic markers applied]\n\nClaims like \"Revenue will be $50M\" become \"Revenue is **projected** to be $50M *(unverified projection)*\"\n\n---\n\n## HITL Verification Record\n\n### Round A: Derived Data Confirmation\n- Claim 1 (source) ✓\n- Claim 2 (source) ✓\n\n### Round B: True HITL Verification\n| # | Claim | Status | Verified By | Date |\n|---|-------|--------|-------------|------|\n| 1 | [claim] | ✓ Confirmed | [name] | [date] |\n\n\u003C!-- CLARITY_GATE_END -->\nClarity Gate: CLEAR | REVIEWED\n```\n\n**Required CGD Elements (per spec):**\n- YAML frontmatter with all required fields:\n  - `clarity-gate-version` — Tool version (no \"v\" prefix)\n  - `processed-date` — YYYY-MM-DD format\n  - `processed-by` — Processor name\n  - `clarity-status` — CLEAR or UNCLEAR\n  - `hitl-status` — PENDING, REVIEWED, or REVIEWED_WITH_EXCEPTIONS\n  - `hitl-pending-count` — Integer ≥ 0\n  - `points-passed` — e.g., `1-9` or `1-4,7,9`\n  - `hitl-claims` — List of verified claims (may be empty `[]`)\n- End marker (HTML comment + status line):\n  ```\n  \u003C!-- CLARITY_GATE_END -->\n  Clarity Gate: \u003Cclarity-status> | \u003Chitl-status>\n  ```\n- HITL verification record (if status is REVIEWED)\n\n**Optional\u002FComputed Fields:**\n- `rag-ingestable` — **Computed by validators**, not manually set. Shows `true` only when `CLEAR | REVIEWED` with no exclusion blocks.\n- `document-sha256` — Required. 64-char lowercase hex hash for integrity verification. See spec §2 for computation rules.\n- `exclusions-coverage` — Optional. Fraction of body inside exclusion blocks (0.0–1.0).\n\n**Escape Mechanism:** To write about markers like `*(estimated)*` without triggering parsing, wrap in backticks: `` `*(estimated)*` ``\n\n### Claim Completion Status (v2.1)\n\nClaim verification status is determined by field **presence**, not an explicit status field:\n\n| State | `confirmed-by` | `confirmed-date` | Meaning |\n|-------|----------------|------------------|----------|\n| **PENDING** | absent | absent | Awaiting human verification |\n| **VERIFIED** | present | present | Human has confirmed |\n| *(invalid)* | present | absent | W-HC01: partial fields |\n| *(invalid)* | absent | present | W-HC01: partial fields |\n\n**Why no explicit status field?** Field presence is self-enforcing—you can't accidentally set status without providing who\u002Fwhen.\n\n### Source Field Semantics (v2.1)\n\nThe `source` field meaning changes based on claim state:\n\n| State | `source` Contains | Example |\n|-------|-------------------|----------|\n| **PENDING** | Where to verify (actionable) | `\"Check Q3 planning doc\"` |\n| **VERIFIED** | What was found (evidence) | `\"Q3 planning doc, page 12\"` |\n\n**Vague source detection (W-HC02):** Sources like `\"industry reports\"`, `\"research\"`, `\"TBD\"` trigger warnings.\n\n### Claim ID Format (v2.1)\n\n**General pattern:** `claim-[a-z0-9._-]{1,64}` (alphanumeric, dots, underscores, hyphens)\n\n| Approach | Pattern | Example | Use Case |\n|----------|---------|---------|----------|\n| **Hash-based** (preferred) | `claim-[a-f0-9]{8,}` | `claim-75fb137a` | Deterministic, collision-resistant |\n| **Sequential** | `claim-[0-9]+` | `claim-1`, `claim-2` | Simple documents |\n| **Semantic** | `claim-[a-z0-9-]+` | `claim-revenue-q3` | Human-friendly |\n\n**Collision probability:** At 1,000 claims with 8-char hex IDs: ~0.012%. For >1,000 claims, use 12+ hex characters.\n\n**Recommendation:** Use hash-based IDs generated by `scripts\u002Fclaim_id.py` for consistency and collision resistance.\n\n---\n\n## Exclusion Blocks\n\nWhen content cannot be resolved (no SME available, legacy prose, etc.), mark it as excluded rather than leaving it ambiguous:\n\n```markdown\n\u003C!-- CG-EXCLUSION:BEGIN id=auth-legacy-1 -->\nLegacy authentication details that require SME review...\n\u003C!-- CG-EXCLUSION:END id=auth-legacy-1 -->\n```\n\n**Rules:**\n- IDs must match: `[A-Za-z0-9][A-Za-z0-9._-]{0,63}`\n- No nesting or overlapping blocks\n- Each ID used only once\n- Requires `hitl-status: REVIEWED_WITH_EXCEPTIONS`\n- Must document `exceptions-reason` and `exceptions-ids` in frontmatter\n\n**Important:** Documents with exclusion blocks are **not RAG-ingestable**. They're rejected entirely (no partial ingestion).\n\nSee CLARITY_GATE_FORMAT_SPEC.md §4 for complete rules.\n\n---\n\n## SOT Validation\n\nWhen validating a Source of Truth file, the skill checks both **format compliance** (per CLARITY_GATE_FORMAT_SPEC.md) and **content quality** (the 9 points).\n\n### Format Compliance (Structural Rules)\n\nSOT documents are CGDs with a `tier:` block. They require a `## Verified Claims` section with a valid table.\n\n| Code | Check | Severity |\n|------|-------|----------|\n| E-TB01 | No `## Verified Claims` section | ERROR |\n| E-TB02 | Table has no data rows | ERROR |\n| E-TB03 | Required columns missing (Claim, Value, Source, Verified) | ERROR |\n| E-TB04 | Column order wrong (Claim not first or Verified not last) | ERROR |\n| E-TB05 | Empty cell in required column | ERROR |\n| E-TB06 | Invalid date format in Verified column | ERROR |\n| E-TB07 | Verified date in future (beyond 24h grace) | ERROR |\n\n### Content Quality (9 Points)\n\nThe 9 Verification Points apply to SOT content:\n\n| Point | SOT Application |\n|-------|-----------------|\n| 1-4 | Check claims in `## Verified Claims` are actually verified |\n| 5 | Check for conflicting values across tables |\n| 6 | Check claims don't imply unsupported causation |\n| 7 | Check table doesn't state futures as present |\n| 8 | Check dates are chronologically consistent |\n| 9 | Flag specific numbers for external check |\n\n### SOT-Specific Requirements\n\n- **Tier block required:** SOT is a CGD with `tier:` block containing `level`, `owner`, `version`, `promoted-date`, `promoted-by`\n- **Structured claims table:** `## Verified Claims` section with columns: Claim, Value, Source, Verified\n- **Table outside exclusions:** The verified claims table must NOT be inside an exclusion block\n- **Staleness markers:** Use `[STABLE]`, `[CHECK]`, `[VOLATILE]`, `[SNAPSHOT]` in content\n  - `[STABLE]` — Safe to cite without rechecking\n  - `[CHECK]` — Verify before citing\n  - `[VOLATILE]` — Changes frequently; always verify\n  - `[SNAPSHOT]` — Point-in-time data; include date when citing\n\n---\n\n## Output Format\n\nAfter running Clarity Gate, report:\n\n```\n## Clarity Gate Results\n\n**Document:** [filename]\n**Issues Found:** [number]\n\n### Critical (will cause hallucination)\n- [issue + location + fix]\n\n### Warning (could cause equivocation)  \n- [issue + location + fix]\n\n### Temporal (date\u002Ftime issues)\n- [issue + location + fix]\n\n### Externally Verifiable Claims\n| # | Claim | Type | Suggested Verification |\n|---|-------|------|------------------------|\n| 1 | [claim] | Pricing | [where to verify] |\n\n---\n\n## Round A: Derived Data Confirmation\n\n- [claim] ([source])\n\nReply \"confirmed\" or flag any I misread.\n\n---\n\n## Round B: HITL Verification Required\n\n| # | Claim | Why HITL Needed | Human Confirms |\n|---|-------|-----------------|----------------|\n| 1 | [claim] | [reason] | [ ] True \u002F [ ] False |\n\n---\n\n**Would you like me to produce an annotated CGD version?**\n\n---\n\n**Verdict:** PENDING CONFIRMATION\n```\n\n---\n\n## Severity Levels\n\n| Level | Definition | Action |\n|-------|------------|--------|\n| **CRITICAL** | LLM will likely treat hypothesis as fact | Must fix before use |\n| **WARNING** | LLM might misinterpret | Should fix |\n| **TEMPORAL** | Date\u002Ftime inconsistency detected | Verify and update |\n| **VERIFIABLE** | Specific claim that could be fact-checked | Route to HITL or external search |\n| **ROUND A** | Derived from witnessed source | Quick confirmation |\n| **ROUND B** | Requires true verification | Cannot pass without confirmation |\n| **PASS** | Clearly marked, no ambiguity, verified | No action needed |\n\n---\n\n## Quick Scan Checklist\n\n| Pattern | Action |\n|---------|--------|\n| Specific percentages (89%, 73%) | Add source or mark as estimate |\n| Comparison tables | Add \"PROJECTED\" header |\n| \"Achieves\", \"delivers\", \"provides\" | Use \"designed to\", \"intended to\" if not validated |\n| Checkmarks | Verify these are confirmed |\n| \"100%\" anything | Almost always needs qualification |\n| \"Last Updated: [date]\" | Check against current date |\n| Version numbers with dates | Verify chronological order |\n| \"$X.XX\" or \"~$X\" (pricing) | Flag for external verification |\n| \"averages\", \"typically\" | Flag for source\u002Fcitation |\n| Competitor capability claims | Flag for external verification |\n\n---\n\n## What This Skill Does NOT Do\n\n- Does not classify document types (use Stream Coding for that)\n- Does not restructure documents \n- Does not add deep links or references\n- Does not evaluate writing quality\n- **Does not check factual accuracy autonomously** (requires HITL)\n\n---\n\n## Related Projects\n\n| Project | Purpose | URL |\n|---------|---------|-----|\n| Source of Truth Creator | Create epistemically calibrated docs | github.com\u002Ffrmoretto\u002Fsource-of-truth-creator |\n| Stream Coding | Documentation-first methodology | github.com\u002Ffrmoretto\u002Fstream-coding |\n| ArXiParse | Scientific paper verification | arxiparse.org |\n\n---\n\n## Changelog\n\n### v2.1.3 (2026-03-02)\n- **FIXED:** `document_hash.py` now implements full FORMAT_SPEC §2.1-2.4 compliance\n- **FIXED:** Fence-aware end marker detection (Quine Protection per §2.3\u002F§8.5)\n- **FIXED:** All 4 deployment copies converged to single canonical implementation\n- **ADDED:** `canonicalize()` function: trailing whitespace stripping, newline collapsing, NFC normalization\n- **ADDED:** YAML-aware `document-sha256` removal with multiline continuation support (§2.2)\n- **ADDED:** Fence-tracking test vectors (7 new tests, 15 total)\n\n### v2.1.0 (2026-01-27)\n- **ADDED:** Claim Completion Status semantics (PENDING\u002FVERIFIED by field presence)\n- **ADDED:** Source Field Semantics (actionable vs. what-was-found)\n- **ADDED:** Claim ID Format guidance with collision analysis\n- **ADDED:** Body Structure Requirements (HITL Verification Record mandatory when claims exist)\n- **ADDED:** New validation codes: E-ST10, W-ST11, W-HC01, W-HC02, E-SC06 (FORMAT_SPEC §1.2-1.3)\n- **ADDED:** Bundled scripts: `claim_id.py`, `document_hash.py`\n- **UPDATED:** References to FORMAT_SPEC v2.1\n- **UPDATED:** CGD output example to version 2.1\n\n### v2.0.0 (2026-01-13)\n- **ADDED:** agentskills.io compliant YAML frontmatter\n- **ADDED:** Clarity Gate Format Specification v2.0 compliance (unified CGD\u002FSOT)\n- **ADDED:** SOT validation support with E-TB* error codes\n- **ADDED:** Validation rules mapping (9 points → rule codes)\n- **ADDED:** CGD output format template with `\u003C!-- CLARITY_GATE_END -->` markers\n- **ADDED:** Quine Protection note (§2.3 fence-aware marker detection)\n- **ADDED:** Redacted Export feature (§8.11)\n- **UPDATED:** `hitl-claims` format to v2.0 schema (id, text, value, source, location, round)\n- **UPDATED:** End marker format to HTML comment style\n- **UPDATED:** Unified format spec v2.0 (single `.cgd.md` extension)\n- **RESTRUCTURED:** For multi-platform skill discovery\n\n### v1.6 (2025-12-31)\n- Added Two-Round HITL verification system\n- Round A: Derived Data Confirmation\n- Round B: True HITL Verification\n\n### v1.5 (2025-12-28)\n- Added Point 8: Temporal Coherence\n- Added Point 9: Externally Verifiable Claims\n\n### v1.4 (2025-12-23)\n- Added CGD annotation output mode\n\n### v1.3 (2025-12-21)\n- Restructured points into Epistemic (1-4) and Data Quality (5-7)\n\n### v1.2 (2025-12-21)\n- Added Source of Truth request step\n\n### v1.1 (2025-12-21)\n- Added HITL Fact Verification (mandatory)\n\n### v1.0 (2025-11)\n- Initial release with 6-point verification\n\n---\n\n**Version:** 2.1.3\n**Spec Version:** 2.1\n**Author:** Francesco Marinoni Moretto\n**License:** CC-BY-4.0\n",{"name":5,"risk":44,"author":45,"source":24,"license":15,"outputs":46,"version":51,"triggers":52,"repository":60,"description":61,"capabilities":62,"spec_version":68},"unknown","Francesco Marinoni Moretto",[47],{"spec":48,"type":49,"extension":50},"docs\u002FCLARITY_GATE_FORMAT_SPEC.md","cgd",".cgd.md","2.1.3",[19,53,54,55,56,57,58,59],"check for hallucination risks","can an LLM read this safely","review for equivocation","verify document clarity","pre-ingestion check","cgd verify","sot verify","https:\u002F\u002Fgithub.com\u002Ffrmoretto\u002Fclarity-gate","Pre-ingestion verification for epistemic quality in RAG systems. Ensures documents are properly qualified before entering knowledge bases. Produces CGD (Clarity-Gated Documents) and validates SOT (Source of Truth) files.\n",[63,64,65,66,67],"document-verification","epistemic-quality","rag-preparation","cgd-generation","sot-validation","2.1","main","a50a3aa6b39fb0e1b7db88bef1bfc9c93606e126","modules\u002Fagent_skills\u002Fawesome-skills\u002Fplaybooks\u002Fclarity-gate",0,"https:\u002F\u002Fgithub.com\u002FSam-06060\u002Fjarvis-assistant","https:\u002F\u002Fgithub.com\u002FSam-06060","Mobile Application Developer | Kotlin | Flutter, KMP, Swfit, Android,Swift UI | Building at Saar It Resources | Creator of Jarvis (AI Assistant)","2026-06-23 05:13:38",{"source":8,"skillName":5,"commands":78,"prompt":88,"zipAvailable":89},[79,82,85],{"tool":80,"command":81},"npx","npx skills add Sam-06060\u002Fjarvis-assistant --skill clarity-gate",{"tool":83,"command":84},"bunx","bunx skills add Sam-06060\u002Fjarvis-assistant --skill clarity-gate",{"tool":86,"command":87},"pnpm","pnpm dlx skills add Sam-06060\u002Fjarvis-assistant --skill clarity-gate","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FSam-06060\u002Fjarvis-assistant\u002Fblob\u002Fmain\u002Fmodules\u002Fagent_skills\u002Fawesome-skills\u002Fplaybooks\u002Fclarity-gate\u002FSKILL.md",true,[91,97,103,107,111,115,119],{"path":92,"resourceType":93,"resourceTypeDesc":94,"sizeBytes":95,"sourceHtmlUrl":96},"Docs\u002FSecurityClassification.md","REFERENCE","参考文档",5819,"https:\u002F\u002Fgithub.com\u002Ffadrienne\u002FMyGitHub\u002Fblob\u002Fmain\u002FPersonal_AI_Infrastructure\u002FLifeOS\u002Finstall\u002Fskills\u002FDaemon\u002FDocs\u002FSecurityClassification.md",{"path":98,"resourceType":99,"resourceTypeDesc":100,"sizeBytes":101,"sourceHtmlUrl":102},"Tools\u002FDaemonAggregator.ts","SCRIPT","脚本",24218,"https:\u002F\u002Fgithub.com\u002Ffadrienne\u002FMyGitHub\u002Fblob\u002Fmain\u002FPersonal_AI_Infrastructure\u002FLifeOS\u002Finstall\u002Fskills\u002FDaemon\u002FTools\u002FDaemonAggregator.ts",{"path":104,"resourceType":99,"resourceTypeDesc":100,"sizeBytes":105,"sourceHtmlUrl":106},"Tools\u002FSecurityFilter.ts",11695,"https:\u002F\u002Fgithub.com\u002Ffadrienne\u002FMyGitHub\u002Fblob\u002Fmain\u002FPersonal_AI_Infrastructure\u002FLifeOS\u002Finstall\u002Fskills\u002FDaemon\u002FTools\u002FSecurityFilter.ts",{"path":108,"resourceType":93,"resourceTypeDesc":94,"sizeBytes":109,"sourceHtmlUrl":110},"Workflows\u002FDeployDaemon.md",1266,"https:\u002F\u002Fgithub.com\u002Ffadrienne\u002FMyGitHub\u002Fblob\u002Fmain\u002FPersonal_AI_Infrastructure\u002FLifeOS\u002Finstall\u002Fskills\u002FDaemon\u002FWorkflows\u002FDeployDaemon.md",{"path":112,"resourceType":93,"resourceTypeDesc":94,"sizeBytes":113,"sourceHtmlUrl":114},"Workflows\u002FPreviewDaemon.md",1220,"https:\u002F\u002Fgithub.com\u002Ffadrienne\u002FMyGitHub\u002Fblob\u002Fmain\u002FPersonal_AI_Infrastructure\u002FLifeOS\u002Finstall\u002Fskills\u002FDaemon\u002FWorkflows\u002FPreviewDaemon.md",{"path":116,"resourceType":93,"resourceTypeDesc":94,"sizeBytes":117,"sourceHtmlUrl":118},"Workflows\u002FReadDaemon.md",1252,"https:\u002F\u002Fgithub.com\u002Ffadrienne\u002FMyGitHub\u002Fblob\u002Fmain\u002FPersonal_AI_Infrastructure\u002FLifeOS\u002Finstall\u002Fskills\u002FDaemon\u002FWorkflows\u002FReadDaemon.md",{"path":120,"resourceType":93,"resourceTypeDesc":94,"sizeBytes":121,"sourceHtmlUrl":122},"Workflows\u002FUpdateDaemon.md",2899,"https:\u002F\u002Fgithub.com\u002Ffadrienne\u002FMyGitHub\u002Fblob\u002Fmain\u002FPersonal_AI_Infrastructure\u002FLifeOS\u002Finstall\u002Fskills\u002FDaemon\u002FWorkflows\u002FUpdateDaemon.md",[124,138,154,181,200,227],{"skillNo":125,"name":126,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":127,"licenseFileUrl":6,"sourceHtmlUrl":128,"categories":129,"keywords":135,"publishedAt":39},"01M6GDRVS6FXX3ESH0C9DW01C0","test_skill","Apache-2.0","https:\u002F\u002Fgithub.com\u002FSam-06060\u002Fjarvis-assistant\u002Fblob\u002Fmain\u002Fscratch\u002Ftest_skill\u002FSKILL.md",[130],{"categoryNo":131,"categoryName":132,"taxonomyType":133,"taxonomyTypeDesc":134},"01JBSEEDCAT000000000000008","测试与质量","SCENARIO","使用场景",[136,137],"Test Skill","test",{"skillNo":139,"name":140,"nameZh":6,"description":141,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":127,"licenseFileUrl":6,"sourceHtmlUrl":142,"categories":143,"keywords":144,"publishedAt":39},"01M6GDRQ40HX22MA6XWC31RHHK","zustand-store-ts","Create Zustand stores following established patterns with proper TypeScript types and middleware.","https:\u002F\u002Fgithub.com\u002FSam-06060\u002Fjarvis-assistant\u002Fblob\u002Fmain\u002Fmodules\u002Fagent_skills\u002Fawesome-skills\u002Fplaybooks\u002Fzustand-store-ts\u002FSKILL.md",[],[145,146,147,148,149,150,151,24,152,153],"zustand store ts","zustand","store","with","types","middleware","patterns","create","typescript",{"skillNo":155,"name":156,"nameZh":6,"description":157,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":127,"licenseFileUrl":6,"sourceHtmlUrl":158,"categories":159,"keywords":163,"publishedAt":39},"01M6GDRKEA0WE670SPFWX5GKCN","zoom-automation","Automate Zoom meeting creation, management, recordings, webinars, and participant tracking via Rube MCP (Composio). Always search tools first for current schemas.","https:\u002F\u002Fgithub.com\u002FSam-06060\u002Fjarvis-assistant\u002Fblob\u002Fmain\u002Fmodules\u002Fagent_skills\u002Fawesome-skills\u002Fplaybooks\u002Fzoom-automation\u002FSKILL.md",[160],{"categoryNo":161,"categoryName":162,"taxonomyType":133,"taxonomyTypeDesc":134},"01JBSEEDCAT000000000000023","Skill与智能体开发",[164,165,166,167,168,169,170,171,172,173,174,175,176,177,24,178,179,180],"automation","zoom automation","zoom","first","Tools","search","MCP","via","meeting","automate","critical","creation","webinars","composio","recordings","management","tracking",{"skillNo":182,"name":183,"nameZh":6,"description":184,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":127,"licenseFileUrl":6,"sourceHtmlUrl":185,"categories":186,"keywords":188,"publishedAt":39},"01M6GDRFS1452PC71JQ38S24HR","zoho-crm-automation","Automate Zoho CRM tasks via Rube MCP (Composio): create\u002Fupdate records, search contacts, manage leads, and convert leads. Always search tools first for current schemas.","https:\u002F\u002Fgithub.com\u002FSam-06060\u002Fjarvis-assistant\u002Fblob\u002Fmain\u002Fmodules\u002Fagent_skills\u002Fawesome-skills\u002Fplaybooks\u002Fzoho-crm-automation\u002FSKILL.md",[187],{"categoryNo":161,"categoryName":162,"taxonomyType":133,"taxonomyTypeDesc":134},[189,164,190,191,192,193,194,24,169,195,177,196,174,173,168,197,152,198,170,199],"crm automation","zoho crm","crm","zoho crm automation","zoho","leads","contacts","records","update","tasks","manage",{"skillNo":201,"name":202,"nameZh":6,"description":203,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":127,"licenseFileUrl":6,"sourceHtmlUrl":204,"categories":205,"keywords":209,"publishedAt":39},"01M6GDRCKQBAVTGHX5XBH26KPZ","zod-validation-expert","Expert in Zod — TypeScript-first schema validation. Covers parsing, custom errors, refinements, type inference, and integration with React Hook Form, Next.js, and tRPC.","https:\u002F\u002Fgithub.com\u002FSam-06060\u002Fjarvis-assistant\u002Fblob\u002Fmain\u002Fmodules\u002Fagent_skills\u002Fawesome-skills\u002Fplaybooks\u002Fzod-validation-expert\u002FSKILL.md",[206],{"categoryNo":207,"categoryName":208,"taxonomyType":133,"taxonomyTypeDesc":134},"01JBSEEDCAT000000000000009","前端开发",[210,211,212,213,214,153,215,216,217,218,219,220,148,221,222,223,224,24,225,226],"expert","zod","zod validation expert","validation","react","safe","parsing","errors","schema validation","react hook form","hook","trpc","form","type","next","schema","Next.js",{"skillNo":228,"name":229,"nameZh":6,"description":230,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":127,"licenseFileUrl":6,"sourceHtmlUrl":231,"categories":232,"keywords":234,"publishedAt":39},"01M6GDR658B08K4MY0RWD4A6EH","zeroize-audit","Detects missing zeroization of sensitive data in source code and identifies zeroization removed by compiler optimizations, with assembly-level analysis, and control-flow verification. Use for auditing C\u002FC++\u002FRust code handling secrets, keys, passwords, or other sensitive data.","https:\u002F\u002Fgithub.com\u002FSam-06060\u002Fjarvis-assistant\u002Fblob\u002Fmain\u002Fmodules\u002Fagent_skills\u002Fawesome-skills\u002Fplaybooks\u002Fzeroize-audit\u002FSKILL.md",[233],{"categoryNo":161,"categoryName":162,"taxonomyType":133,"taxonomyTypeDesc":134},[235,236,237,238,239,240,241,242,24,243,29,244,245,246,247,248,35,249,250,170],"zeroize audit","audit","write","passwords","get","project","c++","activate","assembly","Bash","secrets","analysis","data","flow","code","rust"]