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.
281 lines (257 loc) • 7.02 kB
YAML
# Derivation Graph Schema
# Based on REF-062 W3C PROV-DM (wasDerivedFrom)
# Issues: #106, #118
$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "https://aiwg.io/schemas/derivation-graph/v1"
title: "Derivation Graph Schema"
description: |
Graph structure for tracking artifact derivation chains following W3C PROV-DM.
Enables queries like "show all tests derived from UC-042".
type: object
required:
- graph_id
- nodes
- edges
properties:
graph_id:
type: string
format: uuid
description: "Unique graph identifier"
generated_at:
type: string
format: date-time
scope:
type: object
properties:
root_path:
type: string
default: "."
include_patterns:
type: array
items:
type: string
default: ["**/*.md", "**/*.ts", "**/*.yaml"]
exclude_patterns:
type: array
items:
type: string
default: ["node_modules/**", ".git/**"]
description: "What files to include in graph"
nodes:
type: array
items:
$ref: "#/$defs/Node"
description: "Artifact nodes"
edges:
type: array
items:
$ref: "#/$defs/Edge"
description: "Derivation relationships"
statistics:
type: object
properties:
total_nodes:
type: integer
total_edges:
type: integer
orphan_nodes:
type: integer
description: "Nodes with no incoming edges"
leaf_nodes:
type: integer
description: "Nodes with no outgoing edges"
max_depth:
type: integer
cycles_detected:
type: boolean
description: "Graph statistics"
$defs:
Node:
type: object
required:
- id
- path
- type
properties:
id:
type: string
description: "Unique node identifier"
path:
type: string
description: "File path"
type:
type: string
enum:
- requirement # UC-*, US-*, REQ-*
- use_case # UC-*
- user_story # US-*
- architecture # SAD, ADR-*
- design # Design documents
- source_code # *.ts, *.py, etc.
- test # *.test.ts, *.spec.ts
- research # REF-*
- schema # *.yaml, *.json schemas
- rule # .claude/rules/*
- template # templates/*
- other
description: "Artifact type"
metadata:
type: object
properties:
title:
type: string
created_at:
type: string
format: date-time
hash:
type: string
ref_id:
type: string
description: "REF-XXX, UC-XXX, etc."
status:
type: string
enum:
- active
- deprecated
- orphaned
- untracked
default: active
Edge:
type: object
required:
- source
- target
- relationship
properties:
source:
type: string
description: "Source node ID"
target:
type: string
description: "Target node ID"
relationship:
type: string
enum:
# Implementation
- implements
- implemented_by
- tests
- tested_by
# Structural
- extends
- extended_by
- depends
- dependency_of
# Derivation
- derives_from
- source_of
- references
- related
# Semantic
- contradicts
- supersedes
- superseded_by
- validates
description: "Relationship type (from qualified-references rule)"
confidence:
type: number
minimum: 0
maximum: 1
default: 1
description: "Confidence in the relationship"
evidence:
type: object
properties:
mention_line:
type: integer
mention_text:
type: string
inferred:
type: boolean
default: false
description: "How relationship was detected"
# Query patterns
queries:
forward_trace:
description: "Find all artifacts derived from a source"
example: "Show all tests derived from UC-042"
traversal: "BFS from source following outgoing edges"
backward_trace:
description: "Find all sources an artifact is derived from"
example: "What requirements does auth.ts implement?"
traversal: "BFS from target following incoming edges"
gap_detection:
description: "Find artifacts missing coverage"
example: "Find requirements with no test coverage"
algorithm: "Find requirement nodes with no 'tested_by' outgoing edges"
orphan_detection:
description: "Find artifacts with no derivation"
example: "Find code not linked to any requirement"
algorithm: "Find code nodes with no 'implements' incoming edges"
impact_analysis:
description: "Find all artifacts affected by a change"
example: "If UC-042 changes, what needs review?"
traversal: "Full forward trace from changed node"
# Output formats
output_formats:
text:
description: "Human-readable text tree"
example: |
UC-042: User Authentication
├── @implemented-by src/auth/login.ts
│ └── @tested-by test/auth/login.test.ts
└── @implemented-by src/auth/session.ts
└── @tested-by test/auth/session.test.ts
json:
description: "Structured JSON for programmatic use"
mermaid:
description: "Mermaid diagram syntax"
example: |
graph TD
UC042[UC-042: User Auth]
SRC1[src/auth/login.ts]
TEST1[test/auth/login.test.ts]
UC042 -->|implements| SRC1
SRC1 -->|tested_by| TEST1
dot:
description: "GraphViz DOT format"
example: |
digraph G {
UC042 [label="UC-042: User Auth"];
SRC1 [label="src/auth/login.ts"];
UC042 -> SRC1 [label="implements"];
}
# Agent protocol
agent_protocol:
build_graph:
description: "How agents build derivation graph"
steps:
- scan_files_for_mentions
- parse_qualified_references
- build_node_list
- build_edge_list
- detect_cycles
- compute_statistics
query_graph:
description: "How agents query the graph"
operations:
- forward_trace
- backward_trace
- gap_detection
- orphan_detection
- impact_analysis
# Storage
storage:
location: ".aiwg/provenance/derivation-graph.json"
cache_ttl: 3600 # Rebuild after 1 hour
incremental_update: true
# References
references:
research:
- "@.aiwg/research/findings/REF-062-w3c-prov.md"
implementation:
- "#106"
- "#118"
related:
- "@agentic/code/frameworks/sdlc-complete/schemas/provenance/prov-record.yaml"
- "@.claude/rules/qualified-references.md"