aiwg
Version:
Cognitive architecture for AI-augmented software development with structured memory, ensemble validation, and closed-loop correction. FAIR-aligned artifacts, 84% cost reduction via human-in-the-loop, standards adopted by 100+ organizations.
525 lines (472 loc) • 15.4 kB
YAML
# Provenance Framework Schema
# Based on REF-062 W3C PROV
# Issues: #243 (PROV-JSON Export), #244 (Provenance Trace)
$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "https://aiwg.io/schemas/provenance-framework/v1"
title: "Provenance Framework Schema"
description: |
Provenance tracking and export framework implementing W3C PROV standard
for PROV-JSON export and derivation tracing per REF-062.
type: object
required:
- version
- prov_export
- provenance_trace
properties:
version:
type: string
pattern: "^\\d+\\.\\d+\\.\\d+$"
default: "1.0.0"
prov_export:
$ref: "#/$defs/PROVExport"
provenance_trace:
$ref: "#/$defs/ProvenanceTrace"
$defs:
PROVExport:
type: object
description: "PROV-JSON export per W3C PROV standard"
properties:
enabled:
type: boolean
default: true
standard:
type: string
default: "https://www.w3.org/TR/prov-json/"
namespaces:
type: object
properties:
aiwg:
type: string
default: "https://aiwg.io/ns/"
prov:
type: string
default: "http://www.w3.org/ns/prov#"
prov_document_schema:
type: object
description: "W3C PROV-JSON document structure"
properties:
prefix:
type: string
default: "Namespace prefixes"
entity:
type: object
description: "Things with some fixed aspects"
properties:
schema:
type: object
properties:
prov_type: { type: string, default: "Entity type" }
aiwg_path: { type: string, default: "File path" }
aiwg_hash: { type: string, default: "Content hash (sha256)" }
aiwg_created_at: { type: string, default: "Creation timestamp" }
entity_types:
type: array
items: { type: string }
default:
- "aiwg:SourceCode"
- "aiwg:Requirement"
- "aiwg:Test"
- "aiwg:Architecture"
- "aiwg:Documentation"
- "aiwg:Research"
activity:
type: object
description: "Something that occurs over a period of time"
properties:
schema:
type: object
properties:
prov_type: { type: string, default: "Activity type" }
prov_start_time: { type: string, default: "Start timestamp" }
prov_end_time: { type: string, default: "End timestamp" }
aiwg_agent: { type: string, default: "Agent that performed activity" }
activity_types:
type: array
items: { type: string }
default:
- "aiwg:Implementation"
- "aiwg:Testing"
- "aiwg:Review"
- "aiwg:Documentation"
- "aiwg:Refactoring"
agent:
type: object
description: "Something that bears responsibility"
properties:
schema:
type: object
properties:
prov_type: { type: string, default: "Agent type" }
aiwg_role: { type: string, default: "Agent role" }
aiwg_model: { type: string, default: "LLM model used" }
agent_types:
type: array
items: { type: string }
default:
- "prov:Agent"
- "aiwg:AIAgent"
- "aiwg:HumanAgent"
relations:
type: object
properties:
wasGeneratedBy:
type: object
properties:
description: { type: string, default: "Entity was generated by Activity" }
schema:
type: object
properties:
prov_entity: { type: string }
prov_activity: { type: string }
wasDerivedFrom:
type: object
properties:
description: { type: string, default: "Entity was derived from another Entity" }
schema:
type: object
properties:
prov_generated_entity: { type: string }
prov_used_entity: { type: string }
prov_type: { type: string, default: "Derivation type (aiwg:implements, etc.)" }
wasAssociatedWith:
type: object
properties:
description: { type: string, default: "Activity was associated with Agent" }
schema:
type: object
properties:
prov_activity: { type: string }
prov_agent: { type: string }
used:
type: object
properties:
description: { type: string, default: "Activity used Entity" }
schema:
type: object
properties:
prov_activity: { type: string }
prov_entity: { type: string }
output_formats:
type: array
items: { type: string }
default:
- "json"
- "jsonld"
- "xml"
discovery:
type: object
properties:
entity_sources:
type: array
items: { type: string }
default:
- ".aiwg/**/*.md"
- "src/**/*.ts"
- "test/**/*.ts"
- "docs/**/*.md"
activity_source:
type: string
default: "git log"
agent_source:
type: string
default: ".aiwg/frameworks/registry.json"
derivation_source:
type: string
default: "@-mentions in files"
ProvenanceTrace:
type: object
description: "Derivation query interface per REF-062"
properties:
enabled:
type: boolean
default: true
directions:
type: object
properties:
forward:
type: object
properties:
description: { type: string, default: "What depends on this artifact?" }
query: { type: string, default: "Find all entities derived from source" }
backward:
type: object
properties:
description: { type: string, default: "Where did this artifact come from?" }
query: { type: string, default: "Find all entities source was derived from" }
options:
type: object
properties:
depth:
type: object
properties:
type: { type: string, default: "integer" }
default: { type: string, default: "unlimited" }
description: { type: string, default: "Maximum traversal depth" }
relationship:
type: object
properties:
type: { type: string, default: "array" }
description: { type: string, default: "Filter by relationship types" }
examples:
type: array
default:
- "implements"
- "tests"
- "extends"
- "documents"
format:
type: object
properties:
type: { type: string, default: "string" }
enum:
type: array
default: ["text", "json", "mermaid", "dot"]
default: { type: string, default: "text" }
graph_building:
type: object
properties:
sources:
type: array
items: { type: string }
default:
- "@-mentions in files"
- "git history (renames, moves)"
- "explicit provenance markers"
caching:
type: object
properties:
enabled: { type: boolean, default: true }
path: { type: string, default: ".aiwg/provenance/graph-cache.json" }
invalidate_on_change: { type: boolean, default: true }
cycle_detection:
type: boolean
default: true
description: "Detect and report circular dependencies"
# Trace result schema
trace_result:
type: object
properties:
root:
type: string
description: "Starting artifact path"
direction:
type: string
enum: [forward, backward]
dependencies:
type: array
items:
type: object
properties:
artifact:
type: string
relationship:
type: string
depth:
type: integer
metadata:
type: object
properties:
created_at: { type: string }
agent: { type: string }
hash: { type: string }
cycle_detected:
type: boolean
cycle_path:
type: array
items: { type: string }
# CLI commands
cli_commands:
provenance_export:
command: "aiwg provenance export"
description: "Export workspace provenance as PROV-JSON"
options:
- name: "--output"
description: "Output file path"
- name: "--format"
description: "json, jsonld, xml"
- name: "--filter"
description: "Entity type filter (source, test, requirement)"
provenance_trace:
command: "aiwg provenance trace <path>"
description: "Trace derivation chain for artifact"
options:
- name: "--forward"
description: "Find what depends on this"
- name: "--backward"
description: "Find what this came from"
- name: "--depth"
description: "Maximum depth (default: unlimited)"
- name: "--relationship"
description: "Filter by relationship type"
- name: "--format"
description: "text, json, mermaid, dot"
provenance_graph:
command: "aiwg provenance graph"
description: "Generate full provenance graph"
options:
- name: "--format"
description: "mermaid, dot, json"
- name: "--output"
description: "Output file path"
# Agent protocol
agent_protocol:
build_prov_document:
description: "Build PROV-JSON document from workspace"
steps:
- initialize_namespaces
- discover_entities
- for_each_entity:
- extract_metadata
- calculate_hash
- determine_type
- extract_activities_from_git
- for_each_commit:
- map_to_activity
- extract_timestamps
- load_agent_metadata
- extract_derivations_from_mentions
- for_each_mention:
- resolve_target_entity
- determine_relationship_type
- create_derivation_record
- link_entities_to_activities
- link_activities_to_agents
- assemble_prov_document
- validate_against_schema
- return_prov_document
trace_derivations:
description: "Trace derivation chain"
steps:
- load_or_build_derivation_graph
- initialize_visited_set
- initialize_result
- traverse:
- check_depth_limit
- check_visited
- mark_visited
- get_edges_by_direction
- filter_by_relationship
- for_each_edge:
- add_to_result
- recurse_if_depth_allows
- check_for_cycles
- format_by_output_type
- return_trace_result
export_graph_format:
description: "Export graph in visualization format"
steps:
- build_derivation_graph
- select_format_template
- if_mermaid:
- generate_mermaid_header
- generate_node_definitions
- generate_edge_definitions
- if_dot:
- generate_dot_header
- generate_dot_nodes
- generate_dot_edges
- return_formatted_graph
# Storage
storage:
prov_documents: ".aiwg/provenance/exports/"
graph_cache: ".aiwg/provenance/graph-cache.json"
trace_logs: ".aiwg/logs/provenance-trace/"
# Research targets (from REF-062)
research_targets:
prov_json_export: "W3C PROV-JSON standard export"
derivation_trace: "Bidirectional derivation queries"
graph_visualization: "Mermaid/DOT graph output"
interoperability: "Import into graph databases and analysis tools"
# Example PROV-JSON output
example_prov_json: |
{
"prefix": {
"aiwg": "https://aiwg.io/ns/",
"prov": "http://www.w3.org/ns/prov#"
},
"entity": {
"aiwg:src/auth/login.ts": {
"prov:type": "aiwg:SourceCode",
"aiwg:path": "src/auth/login.ts",
"aiwg:hash": "sha256:abc123...",
"aiwg:createdAt": "2026-01-15T10:00:00Z"
},
"aiwg:requirements/UC-001.md": {
"prov:type": "aiwg:Requirement",
"aiwg:path": ".aiwg/requirements/UC-001-user-authentication.md"
}
},
"activity": {
"aiwg:activity/impl-login": {
"prov:type": "aiwg:Implementation",
"prov:startTime": "2026-01-15T10:00:00Z",
"prov:endTime": "2026-01-15T11:30:00Z",
"aiwg:agent": "Test-Engineer"
}
},
"wasGeneratedBy": {
"_:wgb1": {
"prov:entity": "aiwg:src/auth/login.ts",
"prov:activity": "aiwg:activity/impl-login"
}
},
"wasDerivedFrom": {
"_:wdf1": {
"prov:generatedEntity": "aiwg:src/auth/login.ts",
"prov:usedEntity": "aiwg:requirements/UC-001.md",
"prov:type": "aiwg:implements"
}
},
"agent": {
"aiwg:agent/test-engineer": {
"prov:type": ["prov:Agent", "aiwg:AIAgent"],
"aiwg:role": "Test-Engineer",
"aiwg:model": "claude-sonnet-4.5"
}
},
"wasAssociatedWith": {
"_:waw1": {
"prov:activity": "aiwg:activity/impl-login",
"prov:agent": "aiwg:agent/test-engineer"
}
}
}
# Example trace output
example_trace_output: |
$ aiwg provenance trace --forward .aiwg/requirements/UC-001.md
Tracing forward dependencies from: UC-001-user-authentication.md
1. src/auth/login.ts
Relationship: @implements
Created: 2026-01-15T10:30:00Z
Agent: Test-Engineer
2. test/unit/auth/login.test.ts
Relationship: @tests
Created: 2026-01-15T09:15:00Z
Agent: Test-Engineer
3. docs/api/authentication.md
Relationship: @documents
Created: 2026-01-16T14:00:00Z
Agent: Technical-Writer
Total: 3 artifacts depend on UC-001
# Example mermaid output
example_mermaid_output: |
graph TD
UC001[UC-001: User Authentication]
LOGIN[src/auth/login.ts]
TEST[test/unit/auth/login.test.ts]
DOC[docs/api/authentication.md]
UC001 -->|implements| LOGIN
UC001 -->|tests| TEST
LOGIN -->|documents| DOC
# References
references:
research:
- "@.aiwg/research/findings/REF-062-w3c-prov.md"
- "@.aiwg/research/findings/REF-058-r-lam.md"
implementation:
- "#243"
- "#244"
related:
- "@.claude/rules/mention-wiring.md"
- "@agentic/code/frameworks/sdlc-complete/schemas/flows/fair-extensions.yaml"
- "https://www.w3.org/TR/prov-json/"