aiwg/agentic/code/frameworks/sdlc-complete/schemas/flows/artifact-indexing.yaml

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.

# Artifact Indexing and Addressing Schema
# Based on REF-009 Neural Turing Machines
# Issues: #186, #187

$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "https://aiwg.io/schemas/artifact-indexing/v1"
title: "Artifact Indexing and Hybrid Addressing Schema"
description: |
  Schema for optimizing .aiwg/ directory structure with metadata indexing
  and hybrid location/content-based addressing per REF-009 Neural Turing Machines.

type: object
required:
  - version
  - index_config
  - addressing

properties:
  version:
    type: string
    pattern: "^\\d+\\.\\d+\\.\\d+$"
    default: "1.0.0"

  index_config:
    $ref: "#/$defs/IndexConfig"

  addressing:
    $ref: "#/$defs/AddressingConfig"

$defs:
  IndexConfig:
    type: object
    description: "Artifact index configuration"
    properties:
      enabled:
        type: boolean
        default: true

      storage:
        type: object
        properties:
          index_path:
            type: string
            default: ".aiwg/.index/"
          metadata_file:
            type: string
            default: "metadata.json"
          embeddings_path:
            type: string
            default: "embeddings/"

      auto_update:
        type: object
        properties:
          enabled:
            type: boolean
            default: true
          watch_paths:
            type: array
            items:
              type: string
            default:
              - ".aiwg/requirements/"
              - ".aiwg/architecture/"
              - ".aiwg/testing/"
              - ".aiwg/security/"
          debounce_ms:
            type: integer
            default: 1000

      performance_targets:
        type: object
        properties:
          query_time_ms:
            type: integer
            default: 50
          index_build_time_per_100:
            type: integer
            default: 500

  AddressingConfig:
    type: object
    description: "Hybrid addressing configuration"
    properties:
      modes:
        type: array
        items:
          type: string
          enum: [location, semantic, tag, dependency]
        default: [location, semantic, tag, dependency]

      syntax:
        type: object
        properties:
          location:
            type: string
            default: "@path/to/file.md"
            description: "Direct file path"
          semantic:
            type: string
            default: "@?\"query text\""
            description: "Semantic search query"
          tag:
            type: string
            default: "@#tag1,tag2"
            description: "Tag-based filter"
          hybrid:
            type: string
            default: "@path/**/?\"query\""
            description: "Location + semantic combined"

      semantic_search:
        type: object
        properties:
          embedding_model:
            type: string
            default: "text-embedding-3-small"
          similarity_threshold:
            type: number
            default: 0.7
          max_results:
            type: integer
            default: 10

# Index structure schema
index_structure:
  description: "Directory structure for artifact index"
  paths:
    root: ".aiwg/.index/"
    metadata: ".aiwg/.index/metadata.json"
    by_phase:
      requirements: ".aiwg/.index/requirements.json"
      architecture: ".aiwg/.index/architecture.json"
      testing: ".aiwg/.index/testing.json"
      security: ".aiwg/.index/security.json"
      deployment: ".aiwg/.index/deployment.json"
    by_type: ".aiwg/.index/by-type.json"
    tags: ".aiwg/.index/tags.json"
    dependencies: ".aiwg/.index/dependencies.json"
    embeddings: ".aiwg/.index/embeddings/"

# Metadata entry schema
metadata_entry:
  type: object
  required:
    - path
    - type
    - phase
  properties:
    path:
      type: string
      description: "Relative path from project root"
    type:
      type: string
      enum:
        - use-case
        - user-story
        - nfr
        - adr
        - sad
        - component-design
        - test-plan
        - test-case
        - threat-model
        - risk-entry
        - deployment-plan
        - runbook
    phase:
      type: string
      enum: [requirements, architecture, construction, testing, deployment]
    title:
      type: string
    tags:
      type: array
      items:
        type: string
    created:
      type: string
      format: date-time
    updated:
      type: string
      format: date-time
    author:
      type: string
    dependencies:
      type: array
      items:
        type: string
      description: "Paths to artifacts this depends on"
    dependents:
      type: array
      items:
        type: string
      description: "Paths to artifacts that depend on this"
    checksum:
      type: string
      description: "SHA256 hash for change detection"
    embedding_id:
      type: string
      description: "Reference to semantic embedding"
    summary:
      type: string
      maxLength: 500
      description: "Brief content summary for search"

# Query interface schema
query_interface:
  type: object
  properties:
    find_artifacts:
      description: "Primary query method"
      parameters:
        path:
          type: string
          description: "Glob pattern for location-based"
        semantic_query:
          type: string
          description: "Natural language query"
        type:
          type: string
          description: "Artifact type filter"
        phase:
          type: string
          description: "SDLC phase filter"
        tags:
          type: array
          items:
            type: string
        updated_after:
          type: string
          format: date
        depends_on:
          type: string
          description: "Find artifacts depending on this path"
        depended_by:
          type: string
          description: "Find artifacts this depends on"
        limit:
          type: integer
          default: 20
        offset:
          type: integer
          default: 0

    get_dependencies:
      description: "Traverse dependency graph"
      parameters:
        path:
          type: string
          required: true
        direction:
          type: string
          enum: [upstream, downstream, both]
          default: both
        depth:
          type: integer
          default: 3

# Query result schema
query_result:
  type: object
  properties:
    query:
      type: object
      description: "Original query parameters"
    results:
      type: array
      items:
        type: object
        properties:
          path:
            type: string
          type:
            type: string
          title:
            type: string
          relevance:
            type: number
            description: "Relevance score (0-1)"
          match_type:
            type: string
            enum: [location, semantic, tag, dependency, hybrid]
          snippet:
            type: string
            description: "Relevant content excerpt"
    total:
      type: integer
    query_time_ms:
      type: number

# Agent protocol
agent_protocol:
  build_index:
    description: "Build or rebuild artifact index"
    triggers:
      - startup
      - manual_request
      - artifact_created
      - artifact_modified
    steps:
      - scan_aiwg_directories
      - for_each_artifact:
          - extract_metadata
          - compute_checksum
          - generate_embedding
          - extract_dependencies
      - build_phase_indexes
      - build_type_index
      - build_tag_index
      - build_dependency_graph
      - persist_indexes

  query_artifacts:
    description: "Execute artifact query"
    steps:
      - parse_query_syntax
      - determine_addressing_modes
      - if_location_mode:
          - resolve_glob_patterns
          - filter_by_existence
      - if_semantic_mode:
          - generate_query_embedding
          - compute_similarities
          - rank_by_relevance
      - if_tag_mode:
          - lookup_tag_index
      - if_dependency_mode:
          - traverse_dependency_graph
      - combine_results
      - apply_additional_filters
      - sort_and_limit
      - return_results

  update_on_change:
    description: "Incremental index update"
    triggers:
      - file_created
      - file_modified
      - file_deleted
    steps:
      - identify_changed_artifact
      - if_deleted:
          - remove_from_indexes
          - update_dependents
      - else:
          - reindex_artifact
          - update_dependency_links
      - persist_changes

# CLI commands
cli_commands:
  index_build:
    command: "aiwg index build"
    description: "Build artifact index"
    options:
      - name: "--force"
        description: "Force full rebuild"
      - name: "--verbose"
        description: "Show indexing progress"

  index_query:
    command: "aiwg index query <query>"
    description: "Query artifact index"
    options:
      - name: "--type"
        description: "Filter by artifact type"
      - name: "--phase"
        description: "Filter by SDLC phase"
      - name: "--tags"
        description: "Filter by tags"
      - name: "--semantic"
        description: "Use semantic search"
      - name: "--json"
        description: "Output as JSON"

  index_deps:
    command: "aiwg index deps <path>"
    description: "Show dependency graph"
    options:
      - name: "--direction"
        description: "upstream, downstream, or both"
      - name: "--depth"
        description: "Maximum traversal depth"

  index_stats:
    command: "aiwg index stats"
    description: "Show index statistics"

# Performance targets (from REF-009)
research_targets:
  content_addressable: "Enable retrieval by content similarity"
  location_addressable: "Support direct path navigation"
  hybrid_queries: "Combine both addressing modes"
  query_performance: "<50ms for indexed queries"

# Storage
storage:
  index_root: ".aiwg/.index/"
  backup_path: ".aiwg/.index/backup/"
  cache_path: ".aiwg/.index/cache/"

# References
references:
  research:
    - "@.aiwg/research/findings/REF-009-neural-turing-machines.md"
  implementation:
    - "#186"
    - "#187"
  related:
    - "@agentic/code/frameworks/sdlc-complete/schemas/flows/semantic-agent-discovery.yaml"
    - "@.claude/rules/mention-wiring.md"