{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://twinethos.com/schemas/rule-v0.3.schema.json", "title": "AI-Integration Compliance Rule (v0.3)", "description": "A single detectable rule governing how software integrates with AI. Rule-centric. v0.3 adds a structured applicability block (does this authority govern this system?) kept separate from detection (does the governed system contain the construct?), and moves source text to a source-anchor model (rules anchor into a separate source store rather than embedding text). P2: detection is now a list of detectors (detections[]) each with its own lifecycle and precision status, so improving a detector does not bump the legal rule version. P3: the rule points to a canonical condition via condition_ref; convergence is computed from shared conditions.", "type": "object", "required": [ "id", "schema_version", "rule_version", "title", "summary", "rule_kind", "assessed_unit", "ai_integration_patterns", "obligation_type", "detection_surfaces", "instrument_ref", "source_anchors", "enforceability_tier", "extraterritorial", "domains", "lifecycle", "detections", "condition_ref" ], "additionalProperties": false, "$defs": { "source_anchor": { "type": "object", "additionalProperties": false, "required": [ "source_artifact_id", "instrument_version", "citation", "citation_path", "selector_type" ], "properties": { "source_artifact_id": { "type": "string" }, "instrument_version": { "type": "string" }, "citation": { "type": "string" }, "citation_path": { "type": "string" }, "selector_type": { "type": "string", "enum": [ "char_offset", "citation_path", "xpath", "page_span", "citation_only" ] }, "start_offset": { "type": "integer", "minimum": 0 }, "end_offset": { "type": "integer", "minimum": 0 }, "quoted_text_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "source_document_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "source_url": { "type": "string", "format": "uri" }, "retrieved_at": { "type": "string", "format": "date" }, "language": { "type": "string" }, "translation_status": { "type": "string", "enum": [ "authoritative", "official_translation", "unofficial_translation" ] }, "tier_c_note": { "type": "string" } }, "allOf": [ { "if": { "properties": { "selector_type": { "const": "citation_only" } }, "required": [ "selector_type" ] }, "then": { "required": [ "source_url", "retrieved_at", "language", "translation_status", "tier_c_note" ], "not": { "required": [ "quoted_text_hash" ] } } }, { "if": { "properties": { "selector_type": { "not": { "const": "citation_only" } } } }, "then": { "required": [ "citation_path", "quoted_text_hash", "source_document_hash", "source_url", "retrieved_at", "language", "translation_status" ] } } ] } }, "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]+(?:[._-][a-z0-9]+)*$", "description": "Stable globally-unique rule id, dotted namespace. Never changes once published." }, "schema_version": { "type": "string", "const": "0.3" }, "rule_version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$", "description": "Semver of this rule's content. Bumped when meaning changes (evergreen lineage)." }, "title": { "type": "string", "minLength": 4, "maxLength": 160 }, "summary": { "type": "string", "minLength": 10, "description": "ENRICHMENT (our words, never copied). Plain-language statement of the requirement." }, "rule_kind": { "type": "string", "enum": [ "legal", "standard", "best_practice", "ethics", "recommended_guardrail" ], "description": "SELECTOR. Where the rule comes from; unlocks the matching kind-block. legal=law/regulation with force; standard=published standard or government framework (may be voluntary); best_practice=community/vendor/our own guidance; ethics=values/principle guideline." }, "assessed_unit": { "type": "string", "enum": [ "model", "system", "ai_integration", "agent_action", "organization", "individual" ], "description": "PRIMARY. What the rule assesses. 'ai_integration' = the code wiring AI into an app (default focus). 'agent_action' = an agent's tool/permission/authority surface." }, "ai_integration_patterns": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": [ "chat", "rag", "agentic", "embeddings", "decision_pipeline", "content_generation", "classification", "recommendation", "any" ] }, "description": "PRIMARY. Which AI integration architectures this rule applies to." }, "obligation_type": { "type": "string", "enum": [ "prohibition", "obligation", "right", "disclosure", "retention", "outcome", "principle", "authorization", "runtime_authorization", "validation", "certification" ], "description": "The shape of the duty. Drives how a consumer interprets severity and pass/fail semantics." }, "compliance_flexibility": { "type": "string", "enum": [ "required", "addressable" ], "description": "HIPAA-style modality. 'addressable' = implement, OR substitute an equivalent, OR document why not. Absent = required." }, "detection_surfaces": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "integer", "minimum": 1, "maximum": 15 }, "description": "Which of the 15 code surfaces the rule inspects. 7/8/9/13/15 are AI-class." }, "ai_specific": { "type": "boolean", "description": "DERIVED by the compiler: true if any surface is AI-class (7,8,9,13,15) or assessed_unit is model/ai_integration/agent_action." }, "instrument_ref": { "type": "object", "description": "Which instrument this rule comes from. Links to the master registry.", "required": [ "slug", "short_name", "type", "source_text_license" ], "additionalProperties": false, "properties": { "slug": { "type": "string" }, "short_name": { "type": "string" }, "type": { "type": "string", "enum": [ "law", "regulation", "standard", "framework", "ethics", "guidance", "treaty", "case_law", "recommended_guardrail" ] }, "authority": { "type": "string" }, "source_text_license": { "type": "string", "enum": [ "A", "B", "C", "S" ], "description": "GATES DISTRIBUTION. A=government edict (verbatim OK); B=standard incorporated into law (contested, flag); C=sold standard (NO verbatim text)." } } }, "provenance": { "type": "object", "description": "Authoring-side provenance. Source TEXT and offsets now live in source_anchors[]; this holds the rule's own citation summary and retrieval context. No verbatim text is stored on the rule.", "additionalProperties": false, "properties": { "primary_citation": { "type": "string", "description": "The headline citation for display, e.g. 'Article 50(1)'. Full anchor detail is in source_anchors[]." }, "instrument_version": { "type": "string" }, "retrieved_date": { "type": "string", "format": "date" } } }, "enforceability_tier": { "type": "string", "enum": [ "pure_ethics", "best_practice", "soft_law", "certifiable_standard", "contractual", "adopted_by_regulator", "binding_law", "recommended_guardrail" ], "description": "How much teeth the rule has. Lets law and ethics coexist and powers exposure ranking." }, "jurisdictions": { "type": "array", "items": { "type": "string", "pattern": "^(\\*|INTL|EU|[A-Z]{2}(-[A-Z0-9]{1,3}(-[A-Z]{2,5})?)?)$", "description": "ISO 3166-1 alpha-2 country, ISO 3166-2 subdivision (US-CA, CA-QC), optional locality suffix (US-NY-NYC), EU, INTL (issued by an international body, no single jurisdiction), or * (publisher guardrail: applies wherever the system operates)." } }, "extraterritorial": { "type": "boolean" }, "domains": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": [ "AI", "Data", "Cyber", "Payment", "Health", "Financial", "Employment", "Insurance", "Ethics", "Accessibility" ] } }, "lifecycle": { "type": "object", "required": [ "status" ], "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "proposed", "enacted", "in_force", "enjoined", "superseded", "withdrawn", "dead", "sunset", "recommended" ], "description": "Legal lifecycle of the obligation. 'recommended' is reserved for publisher guardrails (no legal lifecycle)." }, "enforcement_status": { "type": "string", "enum": [ "enforced", "grace_period", "not_yet_enforced", "unenforced", "unknown", "stayed" ] }, "litigation_flag": { "type": "boolean" }, "published": { "type": "string", "format": "date" }, "in_force": { "type": "string", "format": "date" }, "obligations_apply": { "type": "array", "items": { "type": "string", "format": "date" } }, "best_practice_until": { "type": "string", "format": "date" }, "mandatory_from": { "type": "string", "format": "date" }, "sunset": { "type": "string", "format": "date" }, "grace_period_basis": { "type": "object", "additionalProperties": false, "required": [ "source_artifact_id", "citation_path", "started" ], "description": "Sourced basis for enforcement_status=grace_period when the grace period is set by policy rather than by a dated legal provision. Anchored to a stored official statement; validator G11 accepts a passed application date while the grace period has no published end (or its end is still ahead).", "properties": { "source_artifact_id": { "type": "string" }, "citation_path": { "type": "string" }, "started": { "type": "string", "format": "date" }, "stated_minimum_end": { "type": [ "string", "null" ], "description": "Earliest end implied by the official statement (e.g. 'at least one year'); not an end date." }, "official_end": { "type": [ "string", "null" ], "description": "End date only when an official source publishes one." }, "note": { "type": "string" } } } } }, "treaty": { "type": "object", "description": "Treaty-specific lifecycle and adoption facts. Use for instruments whose legal force depends on ratification and domestic implementation rather than a single enactment date.", "additionalProperties": false, "required": [ "status", "status_as_of", "domestic_implementation_required" ], "properties": { "status": { "type": "string", "enum": [ "open_for_signature", "ratification_threshold_pending", "in_force", "withdrawn" ] }, "status_as_of": { "type": "string", "format": "date" }, "ratification_count": { "type": "integer", "minimum": 0 }, "minimum_ratifications": { "type": "integer", "minimum": 1 }, "minimum_member_state_ratifications": { "type": "integer", "minimum": 0 }, "entry_into_force_after_days": { "type": "integer", "minimum": 0 }, "party_jurisdictions": { "type": "array", "items": { "type": "string" } }, "domestic_implementation_required": { "type": "boolean" }, "notes": { "type": "string" } } }, "legal": { "type": "object", "description": "KIND BLOCK (rule_kind=legal). Fields that only make sense for enforceable law.", "additionalProperties": false, "properties": { "liability_basis": { "type": "string", "enum": [ "impact", "intent", "strict", "not_applicable" ], "description": "What triggers liability. TX TRAIGA=intent; EU/CO=impact." }, "enforcement_body": { "type": "string" }, "penalties": { "type": "object", "additionalProperties": false, "properties": { "description": { "type": "string" }, "max_amount": { "type": "string", "description": "Free text to allow formulations like '€35M or 7% global turnover'." }, "currency": { "type": "string" }, "per_violation": { "type": "boolean" }, "per_day": { "type": "boolean" } } }, "private_right_of_action": { "type": "boolean", "description": "Can an individual sue directly? Dramatically changes real-world risk." }, "cure_period_days": { "type": "integer", "minimum": 0, "description": "Grace window to fix after notice, if the law provides one." }, "enforcement_profile": { "type": "object", "description": "Structured enforcement metadata supplementing the concise legal fields above. It informs exposure ranking without making a legal conclusion.", "additionalProperties": false, "properties": { "enforcement_bodies": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } }, "administrative_enforcement": { "type": "boolean" }, "private_action": { "type": "string", "enum": [ "none", "limited", "general", "unknown" ] }, "cure_period_days": { "type": "integer", "minimum": 0 }, "monetary_penalties": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "basis", "description" ], "properties": { "basis": { "type": "string", "enum": [ "per_violation", "per_day", "percentage_of_revenue", "other" ] }, "description": { "type": "string", "minLength": 1 }, "amount": { "type": "number", "minimum": 0 }, "currency": { "type": "string" }, "cap_description": { "type": "string" } } } } } } } }, "standard": { "type": "object", "description": "KIND BLOCK (rule_kind=standard). Published standards and government frameworks, which may be voluntary and/or certifiable.", "additionalProperties": false, "properties": { "issuing_body": { "type": "string" }, "certifiable": { "type": "boolean", "description": "Can an organisation be formally certified against it? (ISO 42001 yes; NIST AI RMF no.)" }, "certification_body": { "type": "string" }, "conformance_levels": { "type": "array", "items": { "type": "string" }, "description": "Graded conformance if applicable, e.g. ['A','AA','AAA'] or CMMC levels." }, "normative_strength": { "type": "string", "enum": [ "shall", "should", "may" ], "description": "RFC 2119-style strength of this specific provision." }, "voluntary": { "type": "boolean" } } }, "best_practice": { "type": "object", "description": "KIND BLOCK (rule_kind=best_practice). Community, vendor, research, or our own guidance.", "additionalProperties": false, "properties": { "origin": { "type": "string", "enum": [ "community", "vendor", "research", "internal" ], "description": "Who originated it. 'internal' = authored by us." }, "origin_org": { "type": "string", "description": "e.g. 'OWASP', 'CSA'." }, "adoption_signal": { "type": "string", "description": "Evidence of how widely followed, e.g. 'referenced by NIST and most cloud vendor guidance'." }, "maturity": { "type": "string", "enum": [ "emerging", "established", "de_facto_standard" ] } } }, "ethics": { "type": "object", "description": "KIND BLOCK (rule_kind=ethics). Values/principle guidance with no direct enforcement.", "additionalProperties": false, "properties": { "principle_family": { "type": "string", "enum": [ "fairness", "transparency", "accountability", "privacy", "safety", "human_agency", "wellbeing", "sustainability", "contestability" ], "description": "The values family this expresses. The join key for mapping ethics across frameworks." }, "ethical_concern": { "type": "string", "description": "The harm the principle guards against, in plain terms." }, "adherents": { "type": "string", "description": "Who has adopted/signed on, e.g. '47 countries'." }, "contestable": { "type": "boolean", "description": "True if reasonable people disagree on application — flags candidates for the open-source ethics subset." } } }, "agentic": { "type": "object", "description": "Required when assessed_unit=agent_action.", "additionalProperties": false, "properties": { "agent_artifact_type": { "type": "array", "items": { "type": "string", "enum": [ "agent_identity", "agent_registry", "action_log", "human_approval_gate", "override_control", "scope_declaration" ] } }, "trigger_condition": { "type": "string", "description": "For runtime_authorization: the live condition under which the agent must stop and seek approval." } } }, "relationships": { "type": "array", "description": "Typed relationships to other rules/instruments, using precise legal-strength vocabulary. CONVERGENCE POLICY (RF-18, locked 2026-09-01): cross-authority CONVERGENCE is COMPUTED from shared condition_ref and is the primary signal — two rules that share a condition_ref already converge and do NOT require an explicit relationship edge to prove it. Explicit typed edges are added ONLY where a material difference needs explaining: a strength comparison (stronger_than/weaker_than), a safe-harbor (has_safe_harbor/safe_harbor_for), an implementation dependency (implements/supports), an amendment lineage (amends/repeals_and_reenacts), or an equivalence assertion beyond mere shared-condition convergence (equivalent/substantially_equivalent). A shared-condition pair with NO explanatory edge is intentional, not an omission. TWO-LEVEL CONVERGENCE: report (1) direct condition convergence = 'which authorities name the same control?' and (2) qualified relationship convergence = 'how similar are their duties?'. Do NOT walk arbitrary partially_overlaps edges and imply the connected rules are equivalent. target.kind ∈ rule|condition|instrument must resolve locally; external_authority is a forward/outside reference requiring a citation.", "items": { "type": "object", "required": [ "type", "target" ], "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "equivalent", "substantially_equivalent", "partially_overlaps", "stronger_than", "weaker_than", "implements", "supports", "conflicts_with", "supersedes", "superseded_by", "amends", "amended_by", "repeals_and_reenacts", "safe_harbor_for", "has_safe_harbor", "relocated_from", "parent_instrument", "jurisdiction_delta_of" ] }, "target": { "description": "Reference to another entity. STRING form is DEPRECATED (v0.3 legacy). Prefer the TYPED object form {kind,id,citation?}. kind=rule|condition|instrument require local resolution by a validator; kind=external_authority is a forward/outside reference that requires a citation and is NOT expected to resolve locally.", "oneOf": [ { "type": "string", "description": "DEPRECATED legacy string target (a rule id, condition id, or instrument slug)." }, { "type": "object", "additionalProperties": false, "required": [ "kind", "id" ], "properties": { "kind": { "type": "string", "enum": [ "rule", "condition", "instrument", "external_authority" ] }, "id": { "type": "string", "description": "For rule/condition/instrument: the local id/slug (validator must resolve). For external_authority: a stable token or identifier for the outside/future reference." }, "citation": { "type": "string", "description": "REQUIRED when kind=external_authority: the official citation or description of the external/future authority." } } } ] }, "note": { "type": "string" } } } }, "remediation": { "type": "object", "additionalProperties": false, "description": "Rule-level remediation (v0.3.5, DQ-1). The reusable guard lives on the condition (condition `remediation`) and every rule inherits it; a rule adds only what is specific to it and stated in its own encoded text (`specifics`). Engineering guidance, never legal advice or a statement of compliance.", "properties": { "summary": { "type": "string", "description": "Optional rule-specific one-line guard; when present it replaces the condition's summary for this rule." }, "specifics": { "type": "array", "minItems": 1, "description": "What this rule adds to the condition's guard (a cadence, trigger, deadline, named resource, required notice element). Each item is traceable to a field of this rule (`basis`); nothing the rule's text does not state.", "items": { "type": "object", "additionalProperties": false, "required": [ "text", "basis" ], "properties": { "text": { "type": "string", "minLength": 10, "maxLength": 300 }, "basis": { "type": "string", "enum": [ "summary", "title", "detections", "applicability", "applicability_schedule", "lifecycle", "legal" ], "description": "The field of this rule the specific is taken from (validator E07 checks the field exists)." } } } }, "examples": { "type": "array", "description": "Rule-specific examples, served after the condition's examples.", "items": { "type": "object", "additionalProperties": false, "properties": { "language": { "type": "string" }, "stack": { "type": "string" }, "before": { "type": "string" }, "after": { "type": "string" } } } } } }, "llm_explanation_context": { "type": "object", "description": "Grounding context for a downstream LLM explaining a finding, so it reasons from intent rather than pattern.", "additionalProperties": false, "properties": { "regulation_intent": { "type": "string" }, "common_misunderstandings": { "type": "array", "items": { "type": "string" } } } }, "tags": { "type": "array", "items": { "type": "string" } }, "review": { "type": "object", "description": "Our own chain of custody, distinct from the instrument's provenance.", "additionalProperties": false, "properties": { "authored_by": { "type": "string" }, "authored_date": { "type": "string", "format": "date" }, "reviewed_by": { "type": "string" }, "reviewed_date": { "type": "string", "format": "date" }, "next_review_due": { "type": "string", "format": "date" }, "review_status": { "type": "string", "enum": [ "draft", "human_reviewed", "legal_reviewed", "published" ] }, "provenance_status": { "type": "string", "enum": [ "memory_authored_draft", "primary_source_derived", "legal_reviewed", "tier_c_citation_only", "publisher_authored" ], "description": "Tracks whether this rule's sourced fields were derived from the actual source document (primary_source_derived) or are a first-draft placeholder from model knowledge (memory_authored_draft). The redo effort promotes rules from the former to the latter." }, "legal_review": { "type": "object", "description": "Named legal-review attestation required to promote a rule to legal_reviewed.", "additionalProperties": false, "required": [ "reviewer", "reviewed_date", "disposition", "source_anchors_read" ], "properties": { "reviewer": { "type": "string", "minLength": 1 }, "reviewed_date": { "type": "string", "format": "date" }, "disposition": { "type": "string", "enum": [ "approved", "approved_with_edits", "rejected" ] }, "source_anchors_read": { "type": "boolean", "const": true }, "notes": { "type": "string" } } }, "translation_review": { "type": "object", "description": "Review record for reliance on an unofficial translation of a binding authority.", "additionalProperties": false, "required": [ "reviewer", "reviewed_date", "disposition", "translation_source" ], "properties": { "reviewer": { "type": "string", "minLength": 1 }, "reviewed_date": { "type": "string", "format": "date" }, "disposition": { "type": "string", "enum": [ "approved", "restricted", "rejected" ] }, "translation_source": { "type": "string", "minLength": 1 }, "authoritative_language": { "type": "string" }, "notes": { "type": "string" } } } } }, "source_anchors": { "type": "array", "minItems": 1, "description": "One or more immutable anchors into the separate source store (see source-object schema). A requirement can derive from multiple clauses, so this is an array. The rule NEVER embeds source text; it points at it. Verbatim text lives once in the source store and is resolved at build time for Tier A/B only.", "items": { "$ref": "#/$defs/source_anchor", "type": "object", "required": [ "source_artifact_id", "instrument_version", "citation" ], "additionalProperties": false, "properties": { "source_artifact_id": { "type": "string", "description": "Stable id of the source document in the source store." }, "instrument_version": { "type": "string", "description": "Version/date of the instrument this anchor targets." }, "citation": { "type": "string", "description": "Human citation, e.g. 'Article 50(1)'." }, "citation_path": { "type": "string", "description": "Machine path into the structure, e.g. 'article-50/paragraph-1'." }, "selector_type": { "type": "string", "enum": [ "char_offset", "citation_path", "xpath", "page_span", "citation_only" ], "description": "How the excerpt is located within the source artifact. Default char_offset." }, "start_offset": { "type": "integer", "minimum": 0, "description": "Start character offset into the source artifact (#3 char_span). Exact, because the hash depends on it." }, "end_offset": { "type": "integer", "minimum": 0, "description": "End character offset into the source artifact." }, "quoted_text_hash": { "type": "string", "description": "sha256 of the exact quoted provision text. The deterministic change-detection substrate: if the provision text changes, this changes, and the rule flags for review.", "pattern": "^[a-f0-9]{64}$" }, "source_document_hash": { "type": "string", "description": "sha256 of the ENTIRE official source document at retrieval. Distinguishes 'this clause changed' from 'the document was reissued'." }, "source_url": { "type": "string", "format": "uri" }, "retrieved_at": { "type": "string", "format": "date" }, "language": { "type": "string", "description": "BCP-47 language tag of the anchored text, e.g. 'en', 'zh'." }, "translation_status": { "type": "string", "enum": [ "authoritative", "official_translation", "unofficial_translation" ], "description": "Whether the anchored text is the authoritative language version or a translation. Matters for legal reliance." }, "tier_c_note": { "type": "string", "description": "Tier C note: why no verbatim text is stored." } }, "allOf": [ { "if": { "properties": { "selector_type": { "not": { "const": "citation_only" } } } }, "then": { "required": [ "quoted_text_hash" ] } } ] } }, "applicability": { "type": "object", "description": "P1. Whether a given organisation/system is SUBJECT TO this requirement — distinct from whether the code contains the defect (that is detection). Without this, findings are legally noisy. All dimensions are optional; absent = 'not constrained on this dimension'. requires_human_determination flags rules whose applicability cannot be settled from code/config alone.", "additionalProperties": false, "properties": { "duty_bearers": { "type": "array", "description": "#4. WHO bears the duty. Legal applicability often turns on this.", "items": { "type": "string", "enum": [ "organization", "provider", "developer", "deployer", "operator", "importer", "distributor", "processor", "controller", "employer", "insurer", "individual_professional", "state_party" ] } }, "system_roles": { "type": "array", "items": { "type": "string", "enum": [ "provider", "deployer", "operator", "importer", "distributor", "third_party" ] }, "description": "The system's role in the AI value chain, where the authority distinguishes them (EU AI Act does)." }, "system_classifications": { "type": "array", "items": { "type": "string", "enum": [ "high_risk", "limited_risk", "minimal_risk", "prohibited", "gpai", "consequential_decision", "automated_decision", "general_purpose", "companion_chatbot" ] }, "description": "The risk/class of system the requirement targets." }, "affected_person_locations": { "type": "array", "items": { "type": "string" }, "description": "Where the affected natural persons are, e.g. ['EU','US-IL']. Drives extraterritorial reach." }, "deployment_locations": { "type": "array", "items": { "type": "string" }, "description": "Where the system is deployed/operated." }, "sectors": { "type": "array", "items": { "type": "string", "enum": [ "employment", "insurance", "lending", "healthcare", "housing", "education", "government", "essential_services", "any", "energy", "transportation", "critical_infrastructure", "public_services", "telecommunications" ] }, "description": "Sector scope, where the authority is sector-specific." }, "organization_thresholds": { "type": "object", "additionalProperties": false, "description": "Size/scale thresholds that gate applicability (e.g. SME carve-outs, revenue floors, user counts).", "properties": { "description": { "type": "string" }, "dimension": { "type": "string", "enum": [ "employees", "revenue", "users", "records_processed", "none" ] }, "operator": { "type": "string", "enum": [ ">=", ">", "<=", "<", "==" ] }, "value": { "type": "string", "description": "Threshold value as string to allow units, e.g. '50', '10000000 EUR'." } } }, "system_thresholds": { "type": "object", "additionalProperties": false, "description": "System-scale thresholds (e.g. GPAI compute FLOP thresholds, user-reach floors).", "properties": { "description": { "type": "string" }, "dimension": { "type": "string" }, "operator": { "type": "string", "enum": [ ">=", ">", "<=", "<", "==" ] }, "value": { "type": "string" } } }, "excluded_uses": { "type": "array", "items": { "type": "string" }, "description": "Uses explicitly carved OUT of scope (e.g. 'purely personal use', 'anti-malware', 'spellcheck')." }, "exceptions": { "type": "array", "items": { "type": "string" }, "description": "Named statutory exceptions (e.g. 'law-enforcement authorised use')." }, "effective_window": { "type": "object", "additionalProperties": false, "description": "When applicability is active for this class of duty-bearer (can differ from the instrument's overall dates).", "properties": { "from": { "type": "string", "format": "date" }, "until": { "type": "string", "format": "date" } } }, "applicability_expression": { "type": "string", "description": "Plain-language statement of who is in scope, for human reading. The structured dimensions above are the machine version; P4 will add a typed predicate form later." }, "requires_human_determination": { "type": "boolean", "description": "True if applicability cannot be settled from code/config alone (e.g. depends on the org's headcount or filed status). Routes the finding to human review rather than auto-asserting applicability." } } }, "applicability_schedule": { "type": "array", "description": "Time-bounded applicability slices. Use when lifecycle.obligations_apply alone cannot say which scope is effective on a date.", "items": { "type": "object", "additionalProperties": false, "required": [ "effective_from", "scope_summary" ], "properties": { "effective_from": { "type": "string", "format": "date" }, "effective_until": { "type": "string", "format": "date" }, "scope_summary": { "type": "string", "minLength": 10 }, "source_citation_path": { "type": "string" } } } }, "parameterization": { "type": "object", "description": "#5. When the rule's threshold/boundary is set by a customer-specific artifact rather than a universal value (FDA PCCP; agentic declared scopes). Rare but real.", "additionalProperties": false, "properties": { "parameterized_by": { "type": "string", "enum": [ "customer_artifact", "none" ], "description": "Whether a customer-filed/declared artifact sets the boundary." }, "boundary_source": { "type": "string", "description": "What artifact defines the boundary, e.g. 'the agent's declared tool-scope manifest', 'a filed predetermined change-control plan'." } } }, "condition_ref": { "type": "string", "pattern": "^cond\\.[a-z0-9]+(?:[._-][a-z0-9]+)*$", "description": "P3. The canonical control condition this rule implements (see condition schema). Convergence is COMPUTED across rules sharing a condition_ref — replacing the hand-maintained convergence{} block." }, "detections": { "type": "array", "minItems": 1, "description": "P2. One or more detectors for this rule's condition. Multiple languages/engines, each versioned and precision-rated independently of the legal rule.", "items": { "type": "object", "required": [ "detector_id", "detection_shape", "precision_status" ], "additionalProperties": false, "properties": { "detector_id": { "type": "string", "description": "Stable id for this detector, e.g. 'py.taint.v1'. Lets one condition have many detectors across languages/engines." }, "detector_version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$", "description": "Semver of the DETECTOR — independent of rule_version. A detector fix does not touch the legal rule version." }, "detection_shape": { "type": "string", "enum": [ "data_flow", "pattern_match", "artifact_presence", "config_check" ], "description": "SELECTOR. How the rule is found in code; unlocks the matching detection block. Orthogonal to rule_kind." }, "detectability": { "type": "string", "enum": [ "direct", "presence_absence", "contextual", "manual" ], "description": "Trust indicator. direct=a pattern reliably matches; contextual=needs data-flow understanding (higher false-positive risk); presence_absence=an artifact must exist; manual=human attestation only." }, "detection_hint": { "type": "string", "description": "Plain-language description of what a scanner or reviewer looks for." }, "false_positive_notes": { "type": "string", "description": "Known conditions that look like violations but are not." }, "languages": { "type": "array", "items": { "type": "string" }, "description": "Target languages/frameworks this detector supports, e.g. ['python','typescript']." }, "min_engine_version": { "type": "string", "description": "Minimum scanner/engine version required." }, "precision_status": { "type": "string", "enum": [ "experimental", "validated", "production" ], "description": "P6-lite: a detector can be experimental while the underlying obligation is legally reviewed. Production requires fixtures (added fully in P6)." }, "known_blind_spots": { "type": "array", "items": { "type": "string" } }, "data_flow": { "type": "object", "description": "DETECTION BLOCK (detection_shape=data_flow). Follow a value from where it enters to where it matters. Replaces prose signal lists with explicit source -> sink -> safe-handler structure.", "required": [ "sources", "sinks", "violation_condition" ], "additionalProperties": false, "properties": { "sources": { "type": "array", "minItems": 1, "description": "Where the risky value originates.", "items": { "type": "object", "required": [ "category", "examples" ], "additionalProperties": false, "properties": { "category": { "type": "string", "description": "e.g. 'protected_attribute', 'proxy_attribute', 'untrusted_external_content', 'model_selected_action'." }, "examples": { "type": "array", "items": { "type": "string" }, "description": "Concrete field/function names a scanner looks for." }, "description": { "type": "string" } } } }, "sinks": { "type": "array", "minItems": 1, "description": "Where the value becomes dangerous.", "items": { "type": "object", "required": [ "category", "examples" ], "additionalProperties": false, "properties": { "category": { "type": "string", "description": "e.g. 'llm_prompt', 'instruction_context', 'high_impact_tool_execution'." }, "examples": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" } } } }, "safe_handlers": { "type": "array", "description": "Controls that neutralise the risk between source and sink. Presence of one on the path means no violation.", "items": { "type": "object", "required": [ "category", "examples" ], "additionalProperties": false, "properties": { "category": { "type": "string", "description": "e.g. 'redaction', 'allowlist', 'human_approval_gate', 'data_instruction_separation', 'least_privilege_scoping'." }, "examples": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" } } } }, "violation_condition": { "type": "string", "description": "Plain statement of what constitutes the violation, e.g. 'a source reaches a sink with no safe_handler on the path'." } } }, "pattern_match": { "type": "object", "description": "DETECTION BLOCK (detection_shape=pattern_match). A code pattern is present or absent.", "required": [ "patterns" ], "additionalProperties": false, "properties": { "match_mode": { "type": "string", "enum": [ "any", "all" ], "description": "How the violation patterns combine. 'any' (default): each matching pattern is a finding. 'all': a finding only when every violation pattern matches the same file (for example a coding-agent action AND pull_request_target)." }, "patterns": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "engine", "language", "pattern" ], "additionalProperties": false, "properties": { "engine": { "type": "string", "enum": [ "semgrep", "regex", "ast", "opa", "manual" ] }, "language": { "type": "string", "description": "Target language, or '*' for language-agnostic." }, "pattern": { "type": "string" }, "match_means": { "type": "string", "enum": [ "violation", "compliance" ], "description": "Whether matching this pattern indicates the problem or the fix. Default: violation." }, "notes": { "type": "string" } } } } } }, "artifact_presence": { "type": "object", "description": "DETECTION BLOCK (detection_shape=artifact_presence). A required artifact must exist in the repo/system.", "required": [ "required_artifacts" ], "additionalProperties": false, "properties": { "required_artifacts": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "name", "description" ], "additionalProperties": false, "properties": { "name": { "type": "string", "description": "e.g. 'agent_registry', 'bias_audit', 'model_card', 'training_data_disclosure'." }, "description": { "type": "string" }, "accepted_evidence": { "type": "array", "items": { "type": "string" }, "description": "Filenames, config keys, code constructs, or endpoints that satisfy it." }, "search_locations": { "type": "array", "items": { "type": "string" }, "description": "Where to look, e.g. 'repo root', 'docs/', 'IaC config', 'logging pipeline'." } } } }, "absence_is_violation": { "type": "boolean", "default": true, "description": "True (default): missing artifact = violation. False: presence is the violation." } } }, "config_check": { "type": "object", "description": "DETECTION BLOCK (detection_shape=config_check). A setting holds a risky value.", "required": [ "checks" ], "additionalProperties": false, "properties": { "checks": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "setting", "description" ], "additionalProperties": false, "properties": { "setting": { "type": "string", "description": "Setting name, e.g. 'temperature', 'top_p', 'max_retries', 'tool_scope'." }, "description": { "type": "string" }, "unsafe_values": { "type": "array", "items": { "type": "string" }, "description": "Values or expressions that constitute the violation, e.g. '> 0', 'true', '\"*\"'." }, "safe_values": { "type": "array", "items": { "type": "string" } }, "applies_when": { "type": "string", "description": "Scope condition, e.g. 'the call is on a consequential-decision path'." } } } } } }, "file_globs": { "type": "array", "items": { "type": "string" }, "description": "Repository paths/globs where this detector looks, e.g. ['**/.mcp.json', 'docker-compose*.yml']. Narrows scanner and LLM-reviewer search." }, "evidence_scope": { "type": "string", "enum": [ "code", "organizational" ], "default": "code", "description": "Where the evidence for this detector lives. 'code': a repository can show the defect. 'organizational': the evidence is a document, assessment, or process outside the code (management system, impact assessment, published audit or framework), so a code review can only report it as not verifiable from code." } }, "allOf": [ { "if": { "properties": { "detection_shape": { "const": "data_flow" } }, "required": [ "detection_shape" ] }, "then": { "required": [ "data_flow" ] } }, { "if": { "properties": { "detection_shape": { "const": "pattern_match" } }, "required": [ "detection_shape" ] }, "then": { "required": [ "pattern_match" ] } }, { "if": { "properties": { "detection_shape": { "const": "artifact_presence" } }, "required": [ "detection_shape" ] }, "then": { "required": [ "artifact_presence" ] } }, { "if": { "properties": { "detection_shape": { "const": "config_check" } }, "required": [ "detection_shape" ] }, "then": { "required": [ "config_check" ] } } ] } }, "jurisdiction_variants": { "type": "array", "description": "RF-12 (v0.3.1): for jurisdictional-family rules (one legal baseline adopted near-identically across many jurisdictions). Each variant carries its OWN primary-source anchor and the legally-material deltas for that jurisdiction. The base rule's source_anchors hold the canonical/originating text; each variant records how that jurisdiction differs. A variant is not 'primary_source_derived' for its jurisdiction until it has its own source_anchor.", "items": { "type": "object", "additionalProperties": false, "required": [ "jurisdiction", "provenance_status" ], "properties": { "jurisdiction": { "type": "string", "description": "ISO-ish jurisdiction code, e.g. US-CO, US-TX." }, "instrument_citation": { "type": "string", "description": "The local statute/section for this jurisdiction, e.g. 'Colo. Rev. Stat. 6-1-1306(1)(a)'." }, "source_anchors": { "type": "array", "description": "This jurisdiction's own primary-source anchors (same shape as rule.source_anchors). Empty until derived.", "items": { "$ref": "#/$defs/source_anchor" } }, "provenance_status": { "type": "string", "enum": [ "memory_authored_draft", "primary_source_derived", "indicative_unverified", "legal_reviewed" ], "description": "Per-jurisdiction provenance. 'indicative_unverified' = named as adopting the baseline but not yet primary-source-anchored." }, "applicability_delta": { "type": "string", "description": "How this jurisdiction's applicability differs (threshold, scope)." }, "lifecycle_delta": { "type": "object", "description": "Per-jurisdiction effective dates / status overrides." }, "legal_delta": { "type": "string", "description": "Per-jurisdiction enforcement/remedy/right differences (GPC duty, correction right, private action, penalties)." }, "adoption": { "type": "object", "description": "How this jurisdiction adopts, ratifies, or otherwise gives force to a shared baseline or model instrument.", "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "adopted", "ratified", "in_force", "pending", "not_adopted", "unknown" ] }, "adopting_authority": { "type": "string" }, "adopting_instrument": { "type": "string" }, "enforcement_basis": { "type": "string" } } }, "notes": { "type": "string" } }, "allOf": [ { "if": { "properties": { "provenance_status": { "const": "primary_source_derived" } }, "required": [ "provenance_status" ] }, "then": { "required": [ "source_anchors" ], "properties": { "source_anchors": { "minItems": 1 } } } } ] } }, "recommended_guardrail": { "type": "object", "additionalProperties": false, "description": "KIND BLOCK (rule_kind=recommended_guardrail). TwinEthos's OWN recommended guardrail — explicitly NOT law, NOT a standard. Derived from the gap between what binding law requires and what responsible AI integration needs. Every enriched rule must state why it exists (rationale), what evidence supports it (convergence + incidents), and the gap it fills. v0.3.2.", "required": [ "rationale", "priority_set", "guardrail_class", "gap_evidence", "confidence", "no_authority_claim", "gap_note", "maturity" ], "properties": { "rationale": { "type": "string", "minLength": 40, "description": "Why a responsible AI integration should implement this control even though no (or little) binding law requires it." }, "priority_set": { "type": "string", "enum": [ "agent_containment", "output_integrity", "human_review_substance", "universal_baseline", "operational_integrity", "ethical_use" ], "description": "Which enriched set this rule belongs to (the four sets from the regulatory analysis, plus operational_integrity and the advisory ethical_use profile)." }, "guardrail_class": { "type": "string", "enum": [ "law_derived", "agent_security", "operational_integrity", "ethical_use" ], "description": "What kind of control this is (docs/OVERVIEW.md §7). law_derived: makes a legal duty work in code. agent_security: agent containment and AI-specific security. operational_integrity: controls lost under cost, latency, or model-switch pressure. ethical_use: advisory, opt-in profile; never reported as a violation." }, "convergence_evidence": { "type": "array", "description": "Corpus rules/conditions showing where this control already exists (often soft-law only). Must resolve locally.", "items": { "type": "object", "additionalProperties": false, "required": [ "kind", "id" ], "properties": { "kind": { "type": "string", "enum": [ "rule", "condition" ] }, "id": { "type": "string" } } } }, "gap_evidence": { "type": "string", "minLength": 20, "description": "GENERATED by tools/gap_analysis.py from gap_metrics plus gap_note. Never hand-edit." }, "incident_evidence": { "type": "array", "description": "Incidents from incidents/registry.json where the absence of this control plausibly contributed to harm. The registry holds the graded sources; the rule states the relevance.", "items": { "type": "object", "additionalProperties": false, "required": [ "incident_ref", "relevance" ], "properties": { "incident_ref": { "type": "string", "pattern": "^inc\\." }, "relevance": { "type": "string", "minLength": 20 } } } }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ], "description": "TwinEthos's confidence the control is the right guardrail (not a legal probability)." }, "no_authority_claim": { "const": true, "description": "Hard guarantee: this rule makes no claim to legal or standards authority. Must be true." }, "gap_note": { "type": "string", "minLength": 20, "description": "AUTHORED qualitative statement of the gap (no counts; counts are computed into gap_metrics/gap_evidence)." }, "gap_metrics": { "type": "object", "additionalProperties": false, "description": "GENERATED by tools/gap_analysis.py. Coverage of this guardrail's control in the external corpus (guardrails excluded).", "required": [ "as_of", "condition_ref", "binding_in_force", "binding_not_yet_in_force", "non_binding_instruments" ], "properties": { "as_of": { "type": "string", "format": "date" }, "condition_ref": { "type": "string" }, "family_ref": { "type": "string" }, "binding_in_force": { "type": "array", "items": { "type": "string" }, "description": "Jurisdictions where binding law on this control is in force and not stayed." }, "binding_not_yet_in_force": { "type": "array", "items": { "type": "string" }, "description": "Jurisdictions with binding law enacted but not yet applicable, or stayed." }, "non_binding_instruments": { "type": "array", "items": { "type": "string" }, "description": "Soft-law, standard, best-practice and ethics instrument slugs." }, "family_binding_in_force": { "type": "array", "items": { "type": "string" }, "description": "Same measure across every control in the condition family." } } }, "maturity": { "type": "string", "enum": [ "proposed", "reviewed", "stable" ], "description": "proposed: authored, not yet red-team reviewed. reviewed: passed guardrail-red-team-review with findings resolved. stable: reviewed, and every detector has positive and negative fixtures with measured precision (no detector left experimental)." } } }, "extraterritorial_basis": { "type": "string", "description": "Why the extraterritorial flag has its value: the scope provision relied on (citation) and any ambiguity. Proposed determinations are confirmed by the legal reviewer (see review/legal-review-flags.json)." }, "coverage_group": { "type": "string", "enum": [ "core_ai", "ai_adjacent" ], "default": "core_ai", "description": "Owner decision D-9 (2026-09-30). 'core_ai' (the default when absent): law, standards and guardrails about AI integration. 'ai_adjacent': general privacy or biometric law (e.g. Illinois BIPA, GDPR articles) encoded only for the articles that AI data flows (prompts, inference, embeddings, telemetry of model inputs/outputs, biometric templates from face models) trigger and whose guard can be checked in code. Tagged and documented apart (docs/AI-ADJACENT.md) so it supplements core AI coverage rather than diluting it. An ai_adjacent rule must carry `adjacency`." }, "adjacency": { "type": "object", "additionalProperties": false, "required": [ "ai_synergy", "review_value" ], "description": "Required on coverage_group=ai_adjacent (and only there): how the rule passes each prong of the D-9 litmus test.", "properties": { "ai_synergy": { "type": "string", "minLength": 40, "description": "Prong 1: which typical AI data flow triggers or shapes the obligation." }, "review_value": { "type": "string", "minLength": 40, "description": "Prong 2: the guard a reviewer can check in application code (requirement X, guard Y)." } } } }, "allOf": [ { "$comment": "D-9: an ai_adjacent rule carries its litmus rationale; the rationale is never attached to a core rule", "if": { "properties": { "coverage_group": { "const": "ai_adjacent" } }, "required": [ "coverage_group" ] }, "then": { "required": [ "adjacency" ], "properties": { "rule_kind": { "not": { "const": "recommended_guardrail" } } } }, "else": { "not": { "required": [ "adjacency" ] } } }, { "$comment": "rule_kind selects its block", "if": { "properties": { "rule_kind": { "const": "legal" } }, "required": [ "rule_kind" ] }, "then": { "required": [ "legal" ], "not": { "anyOf": [ { "required": [ "standard" ] }, { "required": [ "best_practice" ] }, { "required": [ "ethics" ] }, { "required": [ "recommended_guardrail" ] } ] } } }, { "if": { "properties": { "rule_kind": { "const": "standard" } }, "required": [ "rule_kind" ] }, "then": { "required": [ "standard" ], "not": { "anyOf": [ { "required": [ "legal" ] }, { "required": [ "best_practice" ] }, { "required": [ "ethics" ] }, { "required": [ "recommended_guardrail" ] } ] } } }, { "if": { "properties": { "rule_kind": { "const": "best_practice" } }, "required": [ "rule_kind" ] }, "then": { "required": [ "best_practice" ], "not": { "anyOf": [ { "required": [ "legal" ] }, { "required": [ "standard" ] }, { "required": [ "ethics" ] }, { "required": [ "recommended_guardrail" ] } ] } } }, { "if": { "properties": { "rule_kind": { "const": "ethics" } }, "required": [ "rule_kind" ] }, "then": { "required": [ "ethics" ], "not": { "anyOf": [ { "required": [ "legal" ] }, { "required": [ "standard" ] }, { "required": [ "best_practice" ] }, { "required": [ "recommended_guardrail" ] } ] } } }, { "$comment": "rule_kind recommended_guardrail selects its block and pins its honesty labels (v0.3.2)", "if": { "properties": { "rule_kind": { "const": "recommended_guardrail" } }, "required": [ "rule_kind" ] }, "then": { "required": [ "recommended_guardrail" ], "not": { "anyOf": [ { "required": [ "legal" ] }, { "required": [ "standard" ] }, { "required": [ "best_practice" ] }, { "required": [ "ethics" ] } ] }, "properties": { "enforceability_tier": { "const": "recommended_guardrail" }, "instrument_ref": { "properties": { "type": { "const": "recommended_guardrail" }, "source_text_license": { "const": "S" } } } } } }, { "$comment": "the recommended_guardrail tier is reserved for recommended_guardrail rules", "if": { "properties": { "enforceability_tier": { "const": "recommended_guardrail" } }, "required": [ "enforceability_tier" ] }, "then": { "properties": { "rule_kind": { "const": "recommended_guardrail" } } } }, { "$comment": "treaty instruments carry treaty-specific lifecycle facts", "if": { "properties": { "instrument_ref": { "properties": { "type": { "const": "treaty" } }, "required": [ "type" ] } }, "required": [ "instrument_ref" ] }, "then": { "required": [ "treaty" ] } }, { "$comment": "legal_reviewed rules require a legal attestation", "if": { "properties": { "review": { "properties": { "provenance_status": { "const": "legal_reviewed" } }, "required": [ "provenance_status" ] } }, "required": [ "review" ] }, "then": { "properties": { "review": { "required": [ "legal_review" ] } } } }, { "$comment": "agentic rules must carry the agentic block", "if": { "properties": { "assessed_unit": { "const": "agent_action" } }, "required": [ "assessed_unit" ] }, "then": { "required": [ "agentic" ] } }, { "$comment": "runtime_authorization must specify its trigger", "if": { "properties": { "obligation_type": { "const": "runtime_authorization" } }, "required": [ "obligation_type" ] }, "then": { "required": [ "agentic" ], "properties": { "agentic": { "required": [ "trigger_condition" ] } } } } ] }