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.
464 lines (427 loc) • 12.3 kB
YAML
# Structured Revision History Schema
# Based on REF-061 OAIS (Open Archival Information System)
# Issue: #205
$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "https://aiwg.io/schemas/revision-history/v1"
title: "OAIS-Compliant Structured Revision History Schema"
description: |
Schema for structured, machine-readable revision history implementing
OAIS Preservation Description Information (PDI) per REF-061.
type: object
required:
- version
- revision_config
- pdi_mapping
properties:
version:
type: string
pattern: "^\\d+\\.\\d+\\.\\d+$"
default: "1.0.0"
revision_config:
$ref: "#/$defs/RevisionConfig"
pdi_mapping:
$ref: "#/$defs/PDIMapping"
frontmatter_schema:
$ref: "#/$defs/FrontmatterSchema"
$defs:
RevisionConfig:
type: object
description: "Revision history configuration"
properties:
enabled:
type: boolean
default: true
auto_update:
type: boolean
default: true
description: "Automatically update on file changes"
storage:
type: object
properties:
location:
type: string
enum: [frontmatter, sidecar, embedded]
default: "frontmatter"
sidecar_extension:
type: string
default: ".revisions.yaml"
versioning:
type: object
properties:
scheme:
type: string
enum: [semver, calver, sequential]
default: "semver"
auto_increment:
type: string
enum: [patch, minor, none]
default: "patch"
PDIMapping:
type: object
description: "OAIS PDI category mapping"
properties:
provenance:
type: object
description: "Processing history and chain of custody"
properties:
fields:
type: array
items:
type: string
default:
- created_by
- modified_by
- processing_history
- derivation_chain
context:
type: object
description: "Relationships and environment"
properties:
fields:
type: array
items:
type: string
default:
- related_artifacts
- dependencies
- project_phase
- domain_context
reference:
type: object
description: "Identifiers and versioning"
properties:
fields:
type: array
items:
type: string
default:
- artifact_id
- version
- previous_versions
- canonical_url
fixity:
type: object
description: "Integrity verification"
properties:
fields:
type: array
items:
type: string
default:
- checksum
- checksum_algorithm
- last_verified
FrontmatterSchema:
type: object
description: "YAML frontmatter schema for revision history"
properties:
revision_history:
type: object
required:
- artifact_id
- current_version
- revisions
properties:
artifact_id:
type: string
description: "Unique artifact identifier"
pattern: "^[A-Z]{2,4}-\\d{3,4}(-[a-z0-9-]+)?$"
current_version:
type: string
description: "Current version string"
pattern: "^v?\\d+\\.\\d+\\.\\d+$"
created:
type: object
properties:
date:
type: string
format: date-time
author:
type: string
agent:
type: string
description: "AI agent if generated"
revisions:
type: array
items:
$ref: "#/$defs/RevisionEntry"
provenance:
type: object
properties:
derived_from:
type: array
items:
type: string
description: "@-mention references to source artifacts"
generates:
type: array
items:
type: string
description: "@-mention references to derived artifacts"
fixity:
type: object
properties:
checksum:
type: string
algorithm:
type: string
enum: [sha256, sha512, md5]
default: "sha256"
verified:
type: string
format: date-time
RevisionEntry:
type: object
required:
- version
- date
- summary
properties:
version:
type: string
description: "Version string"
date:
type: string
format: date-time
author:
type: string
description: "Human author (if applicable)"
agent:
type: string
description: "AI agent (if applicable)"
summary:
type: string
description: "Brief description of changes"
changes:
type: array
items:
type: object
properties:
type:
type: string
enum: [added, changed, removed, fixed, deprecated]
description:
type: string
section:
type: string
description: "Section affected"
rationale:
type: string
description: "Why changes were made"
review:
type: object
properties:
status:
type: string
enum: [draft, reviewed, approved]
reviewer:
type: string
date:
type: string
format: date-time
prov_activity:
type: string
description: "Link to PROV activity record"
# Frontmatter template
frontmatter_template: |
---
revision_history:
artifact_id: "{artifact_id}"
current_version: "{version}"
created:
date: "{created_date}"
author: "{author}"
agent: "{agent}"
revisions:
- version: "{version}"
date: "{date}"
author: "{author}"
agent: "{agent}"
summary: "{summary}"
changes:
- type: added
description: "Initial creation"
rationale: "{rationale}"
review:
status: draft
provenance:
derived_from:
- "@{source_artifact}"
generates: []
fixity:
checksum: "{checksum}"
algorithm: sha256
verified: "{date}"
---
# Example frontmatter
example_frontmatter: |
---
revision_history:
artifact_id: "SAD-001-architecture"
current_version: "1.2.0"
created:
date: "2026-01-20T10:00:00Z"
author: "jmagly"
agent: "architecture-designer"
revisions:
- version: "1.2.0"
date: "2026-01-25T14:30:00Z"
author: "jmagly"
agent: "architecture-designer"
summary: "Added security architecture section"
changes:
- type: added
description: "Security architecture section 5.0"
section: "5. Security"
- type: changed
description: "Updated component diagram"
section: "3.1 Component Diagram"
rationale: "Security review identified missing security documentation"
review:
status: approved
reviewer: "security-auditor"
date: "2026-01-25T15:00:00Z"
prov_activity: "aiwg:activity/mod-sad-003"
- version: "1.1.0"
date: "2026-01-22T09:15:00Z"
agent: "architecture-designer"
summary: "Added deployment architecture"
changes:
- type: added
description: "Deployment view section"
section: "4. Deployment"
rationale: "Construction phase requires deployment guidance"
review:
status: approved
reviewer: "devops-engineer"
date: "2026-01-22T11:00:00Z"
- version: "1.0.0"
date: "2026-01-20T10:00:00Z"
author: "jmagly"
agent: "architecture-designer"
summary: "Initial architecture document"
changes:
- type: added
description: "Initial creation"
rationale: "Elaboration phase kickoff"
review:
status: approved
reviewer: "tech-lead"
date: "2026-01-20T12:00:00Z"
provenance:
derived_from:
- "@.aiwg/requirements/use-cases/UC-001-authentication.md"
- "@.aiwg/requirements/nfr-modules/security.md"
generates:
- "@src/components/auth/"
- "@.aiwg/testing/integration-test-plan.md"
fixity:
checksum: "a1b2c3d4e5f6..."
algorithm: sha256
verified: "2026-01-25T15:00:00Z"
---
# Sidecar file schema
sidecar_schema:
type: object
description: "Standalone revision history sidecar file"
properties:
artifact_path:
type: string
description: "Path to the artifact this tracks"
revision_history:
$ref: "#/$defs/FrontmatterSchema/properties/revision_history"
# CLI commands
cli_commands:
revision_show:
command: "aiwg revision show <artifact>"
description: "Show revision history for artifact"
options:
- name: "--format"
description: "Output format (text, json, yaml)"
- name: "--limit"
description: "Number of revisions to show"
revision_add:
command: "aiwg revision add <artifact>"
description: "Add revision entry"
options:
- name: "--version"
description: "Version string (auto-increment if omitted)"
- name: "--summary"
description: "Change summary"
- name: "--author"
description: "Author name"
revision_verify:
command: "aiwg revision verify <artifact>"
description: "Verify artifact fixity"
revision_report:
command: "aiwg revision report"
description: "Generate revision history report"
options:
- name: "--since"
description: "Show revisions since date"
- name: "--author"
description: "Filter by author"
- name: "--agent"
description: "Filter by agent"
# Agent protocol
agent_protocol:
update_revision:
description: "Update revision history on artifact change"
triggers:
- artifact_modified
steps:
- load_current_revision_history
- determine_version_increment
- create_revision_entry
- calculate_fixity_checksum
- update_frontmatter
- link_to_prov_record
- persist_changes
query_revisions:
description: "Query revision history"
steps:
- parse_query_parameters
- load_revision_history
- filter_by_criteria
- format_output
- return_results
verify_fixity:
description: "Verify artifact integrity"
steps:
- load_revision_history
- get_stored_checksum
- calculate_current_checksum
- compare_checksums
- update_verified_timestamp
- return_verification_result
# Integration with PROV system
prov_integration:
on_revision_add:
- create_prov_activity
- link_revision_to_activity
- update_derivation_relations
on_verification:
- log_verification_activity
- update_fixity_record
# Storage
storage:
frontmatter_artifacts: ".aiwg/**/*.md"
sidecar_path: ".aiwg/revisions/"
index_path: ".aiwg/revisions/index.json"
# Research targets (from REF-061 OAIS)
research_targets:
pdi_compliance: "Full OAIS PDI category coverage"
machine_readable: "Structured YAML vs informal text"
queryable: "Filter and report on revision metadata"
integrated: "Links to PROV provenance system"
# References
references:
research:
- "@.aiwg/research/findings/REF-061-oais.md"
- "@.aiwg/research/findings/15-provenance-lineage.md"
implementation:
- "#205"
related:
- "@agentic/code/frameworks/sdlc-complete/schemas/flows/provenance-system.yaml"
- "@agentic/code/addons/voice-framework/voices/templates/"
- "@agentic/code/frameworks/sdlc-complete/templates/"