Add AILint Provenance Specification document

This document outlines the AILint Provenance Specification, detailing the purpose, scope, core principles, required and optional fields for provenance statements, transport mechanisms, and validity requirements.

spec/provenance.md

@@ -0,0 +1,211 @@
+AILint Provenance Specification (v1.0)
+1. Purpose
+
+This specification defines a standard, explicit, machine-readable way to declare AI involvement in content.
+
+The goal is not attribution, enforcement, or monitoring, but transparent provenance signaling so that downstream systems—human or automated—can reason correctly about content origin and handling.
+
+2. Scope
+
+This specification applies to:
+
+Source code
+
+Documentation
+
+Configuration
+
+Structured or unstructured text
+
+Generated or AI-assisted artifacts
+
+It does not:
+
+Attempt to prove authorship
+
+Attempt to infer intent
+
+Replace legal or contractual attribution
+
+Mandate monitoring or telemetry
+
+3. Core Principle
+
+Explicit declaration always supersedes inference.
+
+If valid provenance metadata is present, no heuristic or probabilistic analysis should override it.
+
+4. Provenance Statement (Normative)
+
+A Provenance Statement is a declarative record asserting whether and how AI systems contributed to the content.
+
+4.1 Required Fields
+{
+  "ai_involved": true,
+  "role": "generated"
+}
+
+Field Definitions
+Field	Type	Description
+ai_involved	boolean	Indicates whether AI systems contributed to the content
+role	enum	Nature of AI involvement
+4.2 Role Enumeration (Normative)
+
+Valid values for role:
+
+generated – content produced primarily by an AI system
+
+assisted – AI used for drafting, suggestions, or partial output
+
+edited – AI used to modify or refine existing human content
+
+summarized – AI used to condense or abstract content
+
+translated – AI used to translate content between languages
+
+reviewed – AI used for analysis, linting, or feedback only
+
+5. Optional Fields (Non-Normative but Recommended)
+{
+  "confidence": 0.85,
+  "reference": "prov-2025-01-001"
+}
+
+Field	Type	Description
+confidence	number (0–1)	Self-reported confidence in declaration accuracy
+reference	string	Pointer to extended provenance metadata
+
+Notes:
+
+confidence is informational only.
+
+Absence of optional fields does not invalidate the statement.
+
+6. Transport Mechanisms
+
+The Provenance Statement may be transported using one or more of the following mechanisms.
+
+6.1 Inline Declaration (Preferred for Readability)
+
+Examples:
+
+Source code comment
+
+Markdown frontmatter
+
+Header block
+
+Example (Markdown frontmatter):
+
+ai_provenance:
+  ai_involved: true
+  role: assisted
+
+6.2 Git Metadata (Highly Robust)
+
+Example Git trailer:
+
+AILint-Provenance: ai_involved=true; role=generated; ref=prov-2025-01-001
+
+6.3 Sidecar Manifest (Authoritative Source)
+
+Example file:
+
+.ailint/provenance.jsonl
+
+
+Each entry binds:
+
+content hash
+
+file path
+
+provenance statement
+
+optional metadata
+
+optional cryptographic signature
+
+This manifest is the recommended system of record.
+
+6.4 Embedded / Invisible Markers (Optional)
+
+Invisible or steganographic markers:
+
+MAY be used as transport carriers
+
+MUST NOT be the sole source of truth
+
+MUST be removable without semantic loss
+
+Invisible markers are non-authoritative and non-normative.
+
+7. Precedence Rules
+
+When multiple provenance signals exist:
+
+Sidecar manifest
+
+Git metadata
+
+Inline declaration
+
+Embedded marker
+
+Heuristic inference (fallback only)
+
+8. Validity Requirements
+
+A Provenance Statement is considered valid if:
+
+Required fields are present
+
+Values conform to the defined schema
+
+Transport format preserves semantic meaning
+
+No cryptographic signing is required for validity, but it is recommended for trust.
+
+9. Privacy and Ethics Considerations
+
+This specification:
+
+Prohibits behavioral telemetry requirements
+
+Does not encode personal identifiers
+
+Avoids surveillance or performance monitoring implications
+
+Provenance is content-centric, not person-centric.
+
+10. Compatibility and Forward Evolution
+
+Unknown fields MUST be ignored
+
+Unknown roles SHOULD be treated as assisted
+
+Backward compatibility MUST be preserved
+
+Future versions may extend:
+
+role taxonomy
+
+trust assertions
+
+cryptographic binding methods
+
+11. Non-Goals (Explicit)
+
+This specification does not:
+
+Detect AI usage
+
+Enforce disclosure
+
+Judge content quality
+
+Establish copyright ownership
+
+12. Summary
+
+AILint Provenance is a voluntary, explicit signal of AI involvement—designed for clarity, interoperability, and trust.