provenance-agent-spec

Agent Specification: Provenance Agent

1. Agent Overview

| Attribute | Value | |-----------|-------| | **Name** | Provenance Agent | | **ID** | research-provenance-agent | | **Purpose** | Track research operations with W3C PROV compliance, maintain lineage graphs, verify integrity, and enable reproducibility | | **Lifecycle Stage** | Cross-cutting (monitors all research operations) | | **Model** | sonnet | | **Version** | 1.0.0 | | **Status** | Draft |

Description

The Provenance Agent operates transparently across all research operations, capturing metadata using the W3C PROV standard. It logs entities (artifacts), activities (operations), and agents (actors), maintains lineage graphs showing artifact dependencies, computes checksums for integrity verification, and generates reproducibility packages for publication supplements. The agent enables external researchers to replicate findings exactly and provides complete audit trails for research integrity.

2. Capabilities

Primary Capabilities

| Capability | Description | NFR Reference | |------------|-------------|---------------| | W3C PROV Logging | Record entities, activities, agents, and relationships | NFR-RF-P-04 | | Lineage Tracking | Build and query dependency graphs | NFR-RF-P-03 | | Integrity Verification | Compute and validate SHA-256 checksums | NFR-RF-P-05 | | Reproducibility Packages | Generate publication supplements | NFR-RF-P-06 | | Git Integration | Correlate provenance with version control | UC-RF-005 Alt-4 | | Time-Travel Queries | Reconstruct provenance at historical points | UC-RF-005 Alt-4 |

Secondary Capabilities

| Capability | Description | |------------|-------------| | Natural Language Queries | "Where did REF-025 come from?" | | Provenance Visualization | Generate lineage graphs in DOT format | | Log Rotation | Manage log files with rotation and compression | | Privacy Redaction | Remove sensitive data before export |

3. Tools

Required Tools

| Tool | Purpose | Permission | |------|---------|------------| | Bash | File operations, checksum computation, git commands | Execute | | Read | Access artifacts for checksum verification | Read | | Write | Save provenance logs, lineage graphs | Write | | Glob | Discover artifacts for tracking | Read |

System Tools

| Tool | Purpose | Required | |------|---------|----------| | `sha256sum` | Checksum computation | Yes | | `git` | Version control integration | Optional | | `jq` | JSON processing | Optional |

4. Triggers

Automatic Triggers (Intercepted Operations)

| Operation | Source Agent | Provenance Captured | |-----------|--------------|---------------------| | Discovery Search | Discovery Agent | Query, results, API version | | Paper Acquisition | Acquisition Agent | URL, checksum, timestamp | | Documentation | Documentation Agent | LLM model, prompts (hash only) | | Citation | Citation Agent | Claim, source, document | | Archival | Archival Agent | Package ID, checksums |

Manual Triggers

| Trigger | Command | Description | |---------|---------|-------------| | Export Package | `aiwg research provenance export` | Reproducibility package | | Validate Integrity | `aiwg research provenance verify` | Checksum validation | | Query Lineage | `aiwg research provenance query "..."` | Trace artifact origin | | Time-Travel | `aiwg research provenance query --at DATE` | Historical state |

5. Inputs/Outputs

Inputs

| Input | Format | Source | Validation | |-------|--------|--------|------------| | Operation Metadata | JSON object | Research operations | Valid operation type | | Entities Involved | Array of entity IDs | Operation context | Valid entity references | | Checksums | SHA-256 hashes | Artifact files | Valid hex string |

Outputs

| Output | Format | Location | Retention | |--------|--------|----------|-----------| | Provenance Log | W3C PROV-JSON | `.aiwg/research/provenance/prov-{timestamp}.json` | 5 years | | Lineage Graph | JSON graph | `.aiwg/research/provenance/lineage-graph.json` | Permanent | | Checksums File | Text | `.aiwg/research/sources/checksums.txt` | Permanent | | Reproducibility Package | ZIP | `.aiwg/research/provenance/reproducibility-package-{timestamp}.zip` | Permanent |

Output Schema: W3C PROV-JSON Record

{
  "prefix": {
    "prov": "http://www.w3.org/ns/prov#",
    "aiwg": "https://aiwg.io/research#"
  },
  "entity": {
    "aiwg:search-results-2026-01-25": {
      "prov:type": "prov:Entity",
      "aiwg:entityType": "SearchResults",
      "aiwg:filePath": ".aiwg/research/discovery/search-results-2026-01-25T10-30-00.json",
      "aiwg:checksum": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "prov:generatedAtTime": "2026-01-25T10:30:00Z"
    }
  },
  "activity": {
    "aiwg:discovery-search-001": {
      "prov:type": "prov:Activity",
      "aiwg:activityType": "DiscoverySearch",
      "aiwg:command": "aiwg research search \"OAuth2 security best practices\"",
      "prov:startTime": "2026-01-25T10:29:50Z",
      "prov:endTime": "2026-01-25T10:30:05Z"
    }
  },
  "agent": {
    "aiwg:user-jmagly": {
      "prov:type": "prov:Agent",
      "aiwg:agentType": "HumanUser"
    },
    "aiwg:discovery-agent": {
      "prov:type": "prov:SoftwareAgent",
      "aiwg:agentType": "DiscoveryAgent",
      "aiwg:version": "1.0.0"
    }
  },
  "wasGeneratedBy": {
    "_:wgb1": {
      "prov:entity": "aiwg:search-results-2026-01-25",
      "prov:activity": "aiwg:discovery-search-001"
    }
  },
  "used": {
    "_:u1": {
      "prov:activity": "aiwg:discovery-search-001",
      "prov:entity": "aiwg:search-query-oauth2"
    }
  },
  "wasAssociatedWith": {
    "_:waw1": {
      "prov:activity": "aiwg:discovery-search-001",
      "prov:agent": "aiwg:discovery-agent"
    }
  }
}

Output Schema: Lineage Graph JSON

{
  "nodes": [
    {
      "id": "aiwg:search-query-oauth2",
      "type": "SearchQuery",
      "label": "OAuth2 security best practices",