[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6P6090ZSW3N7315ZC0Q67XT":3,"skill-same:01M6P6090ZSW3N7315ZC0Q67XT":87},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":38,"linkOnly":39,"markdownContent":40,"markdownBody":41,"frontMatter":42,"refName":66,"commitSha":67,"skillDirectory":68,"forksCount":69,"repositoryHtmlUrl":70,"repositoryHomepageUrl":6,"ownerHtmlUrl":71,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":72,"install":73,"resources":86},"01M6P6090ZSW3N7315ZC0Q67XT","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.","clodoaldoperito-droid\u002FARQUITETURA_JARVIS","clodoaldoperito-droid","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F259241428?v=4","01M6P1D7567KGD4J875631AZDY","01M6P1D7A0ZZDC72AG333YNZ7E",1,"CC-BY-4.0","https:\u002F\u002Fgithub.com\u002Fclodoaldoperito-droid\u002FARQUITETURA_JARVIS\u002Fblob\u002Fmain\u002Fagent_skills\u002Fclarity-gate\u002FSKILL.md",[],[18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37],"clarity","gate","clarity gate","document","unknown","source","for","can","epistemic","verify document","document-verification","community","review","files","ingestion","read","knowledge","verification","rag","documents","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":22,"author":43,"source":29,"license":14,"outputs":44,"version":49,"triggers":50,"repository":58,"description":59,"capabilities":60,"spec_version":65},"Francesco Marinoni Moretto",[45],{"spec":46,"type":47,"extension":48},"docs\u002FCLARITY_GATE_FORMAT_SPEC.md","cgd",".cgd.md","2.1.3",[20,51,52,53,54,55,56,57],"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",[28,61,62,63,64],"epistemic-quality","rag-preparation","cgd-generation","sot-validation","2.1","main","cd2930847fb1ada3557e9207d3be0a1a1ed08f24","agent_skills\u002Fclarity-gate",0,"https:\u002F\u002Fgithub.com\u002Fclodoaldoperito-droid\u002FARQUITETURA_JARVIS","https:\u002F\u002Fgithub.com\u002Fclodoaldoperito-droid","2026-07-22 10:13:36",{"source":8,"skillName":5,"commands":74,"prompt":84,"zipAvailable":85},[75,78,81],{"tool":76,"command":77},"npx","npx skills add clodoaldoperito-droid\u002FARQUITETURA_JARVIS --skill clarity-gate",{"tool":79,"command":80},"bunx","bunx skills add clodoaldoperito-droid\u002FARQUITETURA_JARVIS --skill clarity-gate",{"tool":82,"command":83},"pnpm","pnpm dlx skills add clodoaldoperito-droid\u002FARQUITETURA_JARVIS --skill clarity-gate","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fclodoaldoperito-droid\u002FARQUITETURA_JARVIS\u002Fblob\u002Fmain\u002Fagent_skills\u002Fclarity-gate\u002FSKILL.md",true,[],[88,118,152,172,187,210],{"skillNo":89,"name":90,"nameZh":6,"description":91,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":92,"licenseFileUrl":6,"sourceHtmlUrl":93,"categories":94,"keywords":100,"publishedAt":38},"01M6Q6BV6JFVC1CHDVW58F63AB","plotly","Interactive visualization library. Use when you need hover info, zoom, pan, or web-embeddable charts. Best for dashboards, exploratory analysis, and presentations. For static publication figures use matplotlib or scientific-visualization.","MIT","https:\u002F\u002Fgithub.com\u002Fclodoaldoperito-droid\u002FARQUITETURA_JARVIS\u002Fblob\u002Fmain\u002Fskills_extracted\u002Fskills\u002Fskills\u002Fplotly\u002FSKILL.md",[95],{"categoryNo":96,"categoryName":97,"taxonomyType":98,"taxonomyTypeDesc":99},"01JBSEEDCAT000000000000013","分析与可视化","SCENARIO","使用场景",[90,101,102,24,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117],"static","Charts","you","figures","zoom","scientific","info","use","interactive","dashboards","matplotlib","analysis","library","visualization","presentations","hover","web",{"skillNo":119,"name":120,"nameZh":6,"description":121,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":92,"licenseFileUrl":6,"sourceHtmlUrl":122,"categories":123,"keywords":132,"publishedAt":38},"01M6Q5YRJC1RTZ8A8FK6Q80SH1","native-data-fetching","Use when implementing or debugging ANY network request, API call, or data fetching. Covers fetch API, React Query, SWR, error handling, caching, offline support, and Expo Router data loaders (useLoaderData).","https:\u002F\u002Fgithub.com\u002Fclodoaldoperito-droid\u002FARQUITETURA_JARVIS\u002Fblob\u002Fmain\u002Fskills_extracted\u002Fskills\u002Fskills\u002Fnative-data-fetching\u002FSKILL.md",[124,127],{"categoryNo":125,"categoryName":126,"taxonomyType":98,"taxonomyTypeDesc":99},"01JBSEEDCAT000000000000009","前端开发",{"categoryNo":128,"categoryName":129,"taxonomyType":130,"taxonomyTypeDesc":131},"01JBSEEDCAT000000000000033","数据分析师","PROFESSION","适用职业",[133,134,135,136,137,138,139,140,141,142,143,144,145,146,147,108,148,149,150,151],"native","data fetching","data","native data fetching","react","fetch","debugging","error","caching","error handling","query","call","router","swr","api","expo router","request","implementing","support",{"skillNo":153,"name":154,"nameZh":6,"description":155,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":92,"licenseFileUrl":6,"sourceHtmlUrl":156,"categories":157,"keywords":159,"publishedAt":38},"01M6Q4PFYVRE7AE05V883QFD55","expo-tailwind-setup","Set up Tailwind CSS v4 in Expo with react-native-css and NativeWind v5 for universal styling","https:\u002F\u002Fgithub.com\u002Fclodoaldoperito-droid\u002FARQUITETURA_JARVIS\u002Fblob\u002Fmain\u002Fskills_extracted\u002Fskills\u002Fskills\u002Fexpo-tailwind-setup\u002FSKILL.md",[158],{"categoryNo":125,"categoryName":126,"taxonomyType":98,"taxonomyTypeDesc":99},[160,161,162,163,137,24,164,165,133,166,167,168,169,170,171],"setup","expo tailwind setup","Tailwind","expo","with","nativewind","Tailwind CSS","react-native","styling","up","SET","css",{"skillNo":173,"name":174,"nameZh":6,"description":175,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":92,"licenseFileUrl":6,"sourceHtmlUrl":176,"categories":177,"keywords":178,"publishedAt":38},"01M6Q4PD3AAXFEKXEW225X0K00","expo-dev-client","Build and distribute Expo development clients locally or via TestFlight","https:\u002F\u002Fgithub.com\u002Fclodoaldoperito-droid\u002FARQUITETURA_JARVIS\u002Fblob\u002Fmain\u002Fskills_extracted\u002Fskills\u002Fskills\u002Fexpo-dev-client\u002FSKILL.md",[],[179,180,163,181,182,183,184,185,186],"expo dev client","dev","client","clients","via","distribute","build","development",{"skillNo":188,"name":189,"nameZh":6,"description":190,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":92,"licenseFileUrl":6,"sourceHtmlUrl":191,"categories":192,"keywords":196,"publishedAt":38},"01M6Q4P6HYVP8WJK2YTSHDZGWB","expo-cicd-workflows","Helps understand and write EAS workflow YAML files for Expo projects. Use this skill when the user asks about CI\u002FCD or workflows in an Expo or EAS context, mentions .eas\u002Fworkflows\u002F, or wants help with EAS build pipelines or deployment automation.","https:\u002F\u002Fgithub.com\u002Fclodoaldoperito-droid\u002FARQUITETURA_JARVIS\u002Fblob\u002Fmain\u002Fskills_extracted\u002Fskills\u002Fskills\u002Fexpo-cicd-workflows\u002FSKILL.md",[193],{"categoryNo":194,"categoryName":195,"taxonomyType":98,"taxonomyTypeDesc":99},"01JBSEEDCAT000000000000023","Skill与智能体开发",[163,197,198,199,200,201,202,185,31,108,33,203,204,205,164,206,207,208,24,209],"cicd","expo cicd workflows","workflows","help","about","CI\u002FCD","projects","Bash","ci","deployment","automation","workflow","deployment automation",{"skillNo":211,"name":212,"nameZh":6,"description":213,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":92,"licenseFileUrl":6,"sourceHtmlUrl":214,"categories":215,"keywords":222,"publishedAt":38},"01M6Q4P2ZHG9BFXPT680RJ6ZVG","expo-api-routes","Guidelines for creating API routes in Expo Router with EAS Hosting","https:\u002F\u002Fgithub.com\u002Fclodoaldoperito-droid\u002FARQUITETURA_JARVIS\u002Fblob\u002Fmain\u002Fskills_extracted\u002Fskills\u002Fskills\u002Fexpo-api-routes\u002FSKILL.md",[216,219],{"categoryNo":217,"categoryName":218,"taxonomyType":98,"taxonomyTypeDesc":99},"01JBSEEDCAT000000000000010","后端与接口",{"categoryNo":220,"categoryName":221,"taxonomyType":130,"taxonomyTypeDesc":131},"01JBSEEDCAT000000000000030","开发工程师",[223,147,163,224,24,225,164,148,226,145],"expo api routes","guidelines","eas hosting","hosting"]