structguru 0.1.0__tar.gz

structguru-0.1.0/.agents/SCHEMA.yaml

@@ -0,0 +1,1080 @@
+# =============================================================================
+# AI Agent Documentation Schema v2.4
+# =============================================================================
+# Complete field definitions for AI Agent Documentation Standards
+#
+# Enhancements in v2.4:
+# - Patch v2.4.8: optional security_posture (protected paths, SBOM/SLSA posture)
+# - Cross-platform compatibility (AGENTS.md)
+# - MCP (Model Context Protocol) integration
+# - A2A (Agent-to-Agent) protocol support
+# - OASF (Open Agentic Schema Framework) taxonomy
+# - OpenTelemetry GenAI semantic conventions
+# - Context engineering (budgeting, progressive disclosure, retrieval hints)
+#
+# References:
+# - MCP: https://modelcontextprotocol.io/specification/2025-11-25
+# - A2A: https://github.com/a2aproject/A2A
+# - OASF: https://schema.oasf.outshift.com/
+# - OTel GenAI: https://opentelemetry.io/docs/specs/semconv/gen-ai/
+# - AGENTS.md: https://agents.md/
+# - Codex AGENTS.md guide: https://developers.openai.com/codex/guides/agents-md/
+# - Codex security: https://developers.openai.com/codex/security/
+# - Codex rules: https://developers.openai.com/codex/rules
+# - Codex non-interactive mode: https://developers.openai.com/codex/noninteractive
+# - Codex MCP: https://developers.openai.com/codex/mcp
+# - Codex skills: https://developers.openai.com/codex/skills
+# - Claude Code docs: https://code.claude.com/docs/en/overview
+# - Gemini Code Assist agent mode: https://developers.google.com/gemini-code-assist/docs/agent-mode/overview
+# - Gemini Code Assist .aiexclude: https://developers.google.com/gemini-code-assist/docs/exclude-files
+# - Claude Code best practices: https://www.anthropic.com/engineering/claude-code-best-practices
+# - Gemini agent files (Android Studio): https://developer.android.com/studio/gemini/agent-files
+# - GitLab Duo AGENTS.md: https://docs.gitlab.com/user/gitlab_duo/customize_duo/agents_md/
+# - Codex agent loop deep dive: https://openai.com/index/unrolling-the-codex-agent-loop/
+
+# =============================================================================
+
+_meta:
+  schema_version: "2.4"
+  title: Schema Definitions
+  status: active
+  version: "2.4.12"
+  last_updated: "2026-02-06"
+# =============================================================================
+# VALIDATION SEVERITY LEVELS
+# =============================================================================
+
+validation_severities:
+  ERROR: "Document invalid, must not be consumed"
+  WARNING: "Document incomplete, proceed with caution"
+  INFO: "Suggestion only, no action required"
+
+# =============================================================================
+# REQUIRED FIELDS
+# =============================================================================
+
+fields:
+
+  schema_version:
+    type: string
+    required: true
+    validation: ERROR
+    description: Schema version this document conforms to
+    pattern: '^\d+\.\d+$'
+    example: "2.4"
+    notes: |
+      Agents MUST reject documents with a higher major version.
+      Format: MAJOR.MINOR (no patch version)
+
+  title:
+    type: string
+    required: true
+    validation: ERROR
+    description: Human-readable document title
+    max_length: 200
+    example: "Payment Gateway Service Context"
+
+  description:
+    type: string
+    required: false
+    validation: WARNING
+    description: Short summary used for listings and retrieval (1–3 sentences)
+    max_length: 400
+    example: "Context for the Payment Gateway service: purpose, boundaries, and key integrations."
+    notes: |
+      RECOMMENDED for better search and progressive disclosure.
+      Use a quoted string in YAML frontmatter.
+
+
+  category:
+    type: enum
+    required: true
+    validation: ERROR
+    description: Document classification
+    values:
+      - service-context    # Service/application documentation
+      - skill              # Reusable capability or pattern
+      - decision-record    # Architectural decision record (ADR)
+      - runbook            # Operational procedures
+      - agent-config       # AI agent configuration
+      - api-spec           # API documentation
+      - data-model         # Data structure definitions
+      - integration        # Third-party integration docs
+      - security           # Security policies
+      - testing            # Test strategies
+      - specification      # Product/technical specifications
+      - research-report    # Research results with sources/evidence
+      - source-document    # Captured source material / provenance record
+
+  status:
+    type: enum
+    required: true
+    validation: ERROR
+    description: Document lifecycle status
+    values:
+      - active             # Current, authoritative
+      - deprecated         # Being phased out
+      - sunset             # No longer valid
+      - draft              # Work in progress
+    default: active
+    agent_behavior:
+      active: "Consume normally"
+      deprecated: "Warn, suggest alternatives, proceed with caution"
+      sunset: "Do not use, search for replacement"
+      draft: "Use only if explicitly requested"
+
+  last_updated:
+    type: date
+    required: true
+    validation: ERROR
+    description: Date of last modification
+    format: "ISO-8601 (YYYY-MM-DD)"
+    example: "2026-01-02"
+
+    notes: |
+      Prefer quoting the date string in YAML frontmatter:
+      last_updated: "2026-01-02"
+      This avoids YAML 1.1 implicit date parsing differences across parsers.
+
+# =============================================================================
+# RECOMMENDED FIELDS
+# =============================================================================
+
+  version:
+    type: string
+    required: false
+    validation: WARNING
+    description: Document content version (semver)
+    pattern: '^\d+\.\d+\.\d+$'
+    example: "1.2.0"
+
+    notes: |
+      Use a quoted string in YAML frontmatter:
+      version: "1.2.0"
+
+  retrieval_priority:
+    type: enum
+    required: false
+    validation: WARNING
+    description: Importance for retrieval ranking
+    values:
+      - critical           # Must be retrieved
+      - high               # Strong preference
+      - medium             # Standard priority
+      - low                # Only if highly relevant
+    default: medium
+
+  retrieval_scope:
+    type: enum
+    required: false
+    validation: WARNING
+    description: Applicability scope
+    values:
+      - service            # Specific to one service
+      - skill              # Reusable across services
+      - global             # Organization-wide
+    default: service
+    tie_breaker_order: ["service", "skill", "global"]
+
+  last_verified:
+    type: date
+    required: false
+    validation: WARNING
+    description: Date content was verified accurate
+    format: "ISO-8601 (YYYY-MM-DD)"
+
+    notes: |
+      Prefer quoting the date string in YAML frontmatter:
+      last_verified: "2026-01-02"
+      This avoids YAML 1.1 implicit date parsing differences across parsers.
+
+  owner:
+    type: string
+    required: false
+    validation: WARNING
+    description: Team or individual responsible
+    example: "Payments Team"
+
+  verification_owner:
+    type: string
+    required: false
+    validation: INFO
+    description: Team responsible for verification
+    example: "Platform Engineering"
+
+# =============================================================================
+# OPTIONAL - BASIC METADATA
+# =============================================================================
+
+  name:
+    type: string
+    required: false
+    validation: INFO
+    description: |
+      Stable identifier used by agent skill loaders (e.g., Codex `SKILL.md`).
+      RECOMMENDED for `category: skill` documents and REQUIRED for Codex skill compatibility.
+    pattern: '^[a-z0-9][a-z0-9-]{2,64}$'
+    example: "project-conventions"
+    notes: |
+      In `SKILL.md`, Codex requires top-level `name` and `description` fields in YAML frontmatter.
+      Keep `description` a single line (avoid multi-line YAML blocks) for maximum compatibility.
+
+  service_type:
+    type: enum
+    required: false
+    values:
+      - application
+      - library
+      - infrastructure
+      - platform
+      - tool
+      - external
+
+  language:
+    type: enum
+    required: false
+    values:
+      - csharp
+      - python
+      - typescript
+      - javascript
+      - go
+      - rust
+      - java
+      - kotlin
+      - ruby
+      - php
+      - multi
+
+  framework:
+    type: string
+    required: false
+    examples: ["dotnet-9", "fastapi", "nextjs-15", "spring-boot"]
+
+  tags:
+    type: array[string]
+    required: false
+    example: ["payment", "kafka", "microservice"]
+
+  keywords:
+    type: array[string]
+    required: false
+    description: Search terms for retrieval
+    example: ["billing", "transactions", "refunds"]
+
+  audience:
+    type: array[enum]
+    required: false
+    values: [developer, architect, devops, security, product, support, all]
+
+  difficulty:
+    type: enum
+    required: false
+    values: [beginner, intermediate, advanced, expert]
+
+  depends_on:
+    type: array[string]
+    required: false
+    description: Dependencies (services or document paths)
+    example: ["kafka", "postgresql", "./auth-context.md"]
+
+  supersedes:
+    type: string
+    required: false
+    description: Document this replaces
+    example: "./old-payment-context.md"
+
+  superseded_by:
+    type: string
+    required: false
+    description: Document replacing this one
+    example: "./new-payment-context.md"
+
+# =============================================================================
+# KNOWLEDGE CAPTURE: RESEARCH & SOURCES (v2.4.3)
+# =============================================================================
+
+  doc_id:
+    type: string
+    required: false
+    validation: INFO
+    description: Stable identifier for this document (recommended for RAG + renames)
+    pattern: '^[a-z0-9][a-z0-9-]{2,64}$'
+    example: "payments-stripe-refunds"
+
+    notes: |
+      Use a short, stable slug. Do not include dates unless the document is inherently time-bound.
+      Prefer keeping doc_id stable even if the filename/path changes.
+
+  data_handling:
+    type: object
+    required: false
+    validation: INFO
+    description: Data classification and RAG ingestion safety flags
+    properties:
+      classification:
+        type: enum
+        values: [public, internal, confidential, restricted]
+        default: internal
+      pii:
+        type: enum
+        values: [none, low, high]
+        default: none
+      contains_secrets:
+        type: boolean
+        default: false
+      rag_allowed:
+        type: boolean
+        default: true
+        description: Whether this document may be indexed/embedded for RAG
+
+
+
+  # ---------------------------------------------------------------------------
+  # Agent runtime integration (optional)
+  # ---------------------------------------------------------------------------
+
+  execution_policy:
+    type: object
+    required: false
+    validation: INFO
+    description: Declared execution posture (sandbox, approvals, network, web search)
+    properties:
+      default_mode:
+        type: enum
+        values: [read-only, workspace-write, full-auto]
+        default: read-only
+
+      network:
+        type: object
+        properties:
+          default:
+            type: enum
+            values: [off, allowlist, on]
+            default: off
+          allowlist_domains:
+            type: array[string]
+            required: false
+            example:
+              - "docs.example.com"
+
+      approvals:
+        type: object
+        properties:
+          for_workspace_writes:
+            type: enum
+            values: [never, on-request, always]
+            default: on-request
+          for_network:
+            type: enum
+            values: [never, on-request, always]
+            default: on-request
+          for_outside_workspace:
+            type: enum
+            values: [never, on-request, always]
+            default: always
+
+      web_search:
+        type: object
+        properties:
+          mode:
+            type: enum
+            values: [disabled, cached, live]
+            default: cached
+
+    notes: |
+      This is a tool-agnostic declaration that can be mapped to:
+      - Codex sandbox + approval policy + web_search settings
+      - Claude Code permission modes / allowlists
+      - Gemini agent mode tool permissions / plan approvals
+
+  context_exclusion:
+    type: object
+    required: false
+    validation: INFO
+    description: Explicit denylist of files/paths that must not be loaded into agent context
+    properties:
+      aiexclude_file:
+        type: string
+        default: ".aiexclude"
+      patterns:
+        type: array[string]
+        required: false
+        description: Optional explicit patterns (use .gitignore syntax)
+      notes:
+        type: string
+        required: false
+
+  automation:
+    type: object
+    required: false
+    validation: INFO
+    description: Automation/CI settings for agent runs (structured outputs, event logs)
+    properties:
+      output_schema_paths:
+        type: array[string]
+        required: false
+        description: Paths to JSON Schemas used for structured outputs
+        example:
+          - ".agents/schemas/release-metadata.schema.json"
+      event_log:
+        type: object
+        required: false
+        properties:
+          format:
+            type: enum
+            values: [jsonl, json, text]
+            default: jsonl
+          path:
+            type: string
+            required: false
+            example: ".agents/artifacts/codex-exec.events.jsonl"
+
+  project_conventions:
+    type: object
+    required: false
+    validation: INFO
+    description: References to repo-level style and file placement convention docs (and optional exemplars)
+    properties:
+      style_profile_ref:
+        type: string
+        required: false
+        example: ".agents/contexts/conventions/STYLE_PROFILE.md"
+      file_placement_map_ref:
+        type: string
+        required: false
+        example: ".agents/contexts/conventions/FILE_PLACEMENT_MAP.md"
+      exemplars:
+        type: array[string]
+        required: false
+        description: Optional exemplar file paths that define the house style
+        example:
+          - "src/<feature>/<module>.ts"
+          - "tests/<feature>/<module>.spec.ts"
+      enforcement:
+        type: enum
+        values: [advisory, required]
+        default: advisory
+      notes:
+        type: string
+        required: false
+
+  conventions_provenance:
+    type: object
+    required: false
+    validation: INFO
+    description: Provenance for conventions derived from git history or curated examples
+    properties:
+      source:
+        type: enum
+        values: [manual, git-history, mixed]
+        default: manual
+
+      git:
+        type: object
+        required: false
+        properties:
+          range:
+            type: string
+            required: false
+            description: Commit range used (e.g., "HEAD~200..HEAD" or "<sha>..<sha>")
+          since:
+            type: string
+            required: false
+            description: Optional time boundary (e.g., "6 months ago")
+          author:
+            type: string
+            required: false
+            description: Optional author filter (avoid personal identifiers where possible)
+          include_paths:
+            type: array[string]
+            required: false
+          exclude_paths:
+            type: array[string]
+            required: false
+          notes:
+            type: string
+            required: false
+
+      reviewed_by:
+        type: string
+        required: false
+      reviewed_date:
+        type: date
+        required: false
+        description: Date the provenance details were reviewed
+
+  security_posture:
+    type: object
+    required: false
+    validation: INFO
+    description: Machine-readable security posture and review gates for agentic work
+    properties:
+      risk_profile:
+        type: enum
+        values: [low, medium, high, critical]
+        default: medium
+        description: Overall security sensitivity of the repo/service
+
+      threat_model_ref:
+        type: string
+        required: false
+        description: Path to the canonical threat model doc
+        example: ".agents/contexts/security/THREAT_MODEL.md"
+
+      secrets_policy_ref:
+        type: string
+        required: false
+        description: Path to the canonical secrets handling policy
+        example: ".agents/contexts/security/SECRETS_POLICY.md"
+
+      dependency_policy_ref:
+        type: string
+        required: false
+        description: Path to dependency/supply-chain policy
+        example: ".agents/contexts/security/DEPENDENCY_POLICY.md"
+
+      supply_chain:
+        type: object
+        required: false
+        description: Optional supply-chain controls (SBOM, provenance)
+        properties:
+          sbom_required:
+            type: boolean
+            default: false
+          slsa_target:
+            type: string
+            required: false
+            description: Target SLSA level/track (if applicable)
+            example: "SLSA3"
+
+      protected_paths:
+        type: array[string]
+        required: false
+        description: Glob patterns requiring human review/approval
+        example:
+          - ".github/workflows/**"
+          - "infra/**"
+          - "terraform/**"
+          - "k8s/**"
+
+      notes:
+        type: string
+        required: false
+
+  sources:
+    type: array[object]
+    required: false
+    validation: INFO
+    description: |
+      Source list supporting the document (required for research reports).
+      Used for auditability, citations, and RAG metadata.
+    item_properties:
+      source_id:
+        type: string
+        pattern: '^src:[a-z0-9][a-z0-9-_]{2,64}$'
+        example: "src:openai-rag-help"
+      title:
+        type: string
+      kind:
+        type: enum
+        values: [web, pdf, paper, book, repo, issue, dataset, internal, other]
+      url:
+        type: string
+        description: Canonical URL (if external)
+      path:
+        type: string
+        description: Local repo path to stored snapshot/notes (if any)
+        example: ".agents/sources/external/openai-rag-help.md"
+      publisher:
+        type: string
+      authors:
+        type: array[string]
+      published_date:
+        type: date
+      accessed_date:
+        type: date
+      license:
+        type: string
+        description: License or usage note (if known)
+      checksum_sha256:
+        type: string
+        description: SHA-256 of stored snapshot (if stored)
+      notes:
+        type: string
+
+  research:
+    type: object
+    required: false
+    validation: INFO
+    description: Research metadata (required when category=research-report)
+    properties:
+      question:
+        type: string
+        description: Primary research question
+      scope:
+        type: string
+        description: Boundaries (what is and isn't covered)
+      method:
+        type: array[string]
+        description: Methods used (e.g., web search, reading RFCs, experiments)
+      findings:
+        type: array[object]
+        description: Key findings with optional evidence pointers
+        item_properties:
+          finding:
+            type: string
+          confidence:
+            type: enum
+            values: [high, medium, low]
+            default: medium
+          evidence:
+            type: array[object]
+            item_properties:
+              source_id:
+                type: string
+              locator:
+                type: string
+                description: Section/page/paragraph identifier
+              quote:
+                type: string
+                description: Short excerpt (keep brief for copyright)
+      open_questions:
+        type: array[string]
+      next_steps:
+        type: array[string]
+
+  rag:
+    type: object
+    required: false
+    validation: INFO
+    description: Optional overrides for RAG ingestion/indexing
+    properties:
+      collection:
+        type: string
+        description: Target collection/index name
+        example: "engineering"
+      include:
+        type: boolean
+        default: true
+        description: Whether to include in RAG indexing
+      chunking_override:
+        type: object
+        description: Overrides retrieval_hints for ingestion time
+        properties:
+          chunk_size:
+            type: integer
+          chunk_overlap:
+            type: integer
+
+# =============================================================================
+# CROSS-PLATFORM COMPATIBILITY (v2.4)
+# =============================================================================
+
+  agents_md_compatible:
+    type: boolean
+    required: false
+    default: true
+    description: |
+      Document follows AGENTS.md conventions for cross-platform 
+      AI agent compatibility (Copilot, Codex, Gemini, Cursor, etc.)
+
+  cross_platform_aliases:
+    type: array[string]
+    required: false
+    description: Alternative filenames for discovery
+    example: ["CLAUDE.md", "GEMINI.md", "AGENT.md", "COPILOT.md"]
+
+# =============================================================================
+# MCP - MODEL CONTEXT PROTOCOL (v2.4)
+# =============================================================================
+
+  mcp_resource:
+    type: object
+    required: false
+    description: MCP resource metadata for tool/data integration
+    properties:
+      uri:
+        type: string
+        description: MCP resource URI
+        pattern: '^mcp://[a-z0-9-]+/[a-z0-9-/]+$'
+        example: "mcp://payment-gateway/transactions"
+      mime_type:
+        type: string
+        example: "application/json"
+      capabilities:
+        type: array[enum]
+        values: [tools, resources, prompts, sampling]
+      auth_type:
+        type: enum
+        values: [none, bearer, oauth2, api_key]
+      discovery_endpoint:
+        type: string
+        description: OAuth 2.1 discovery URL
+
+  mcp_tools:
+    type: array[object]
+    required: false
+    description: Tools exposed via MCP
+    item_properties:
+      name:
+        type: string
+        example: "getTransaction"
+      description:
+        type: string
+      parameters:
+        type: object
+        description: JSON Schema for parameters
+
+# =============================================================================
+# A2A - AGENT-TO-AGENT PROTOCOL (v2.4)
+# =============================================================================
+
+  agent_card:
+    type: object
+    required: false
+    description: A2A AgentCard for agent discovery
+    properties:
+      agent_name:
+        type: string
+        example: "Payment Processor Agent"
+      agent_id:
+        type: string
+        pattern: '^[a-z0-9-]+$'
+        example: "payment-processor-v1"
+      skills:
+        type: array[string]
+        example: ["process-payment", "handle-refund"]
+      supported_modalities:
+        type: array[enum]
+        values: [text, structured-data, audio, video, file]
+        default: [text, structured-data]
+      auth_schemes:
+        type: array[enum]
+        values: [bearer, oauth2, api_key, mtls]
+      well_known_path:
+        type: string
+        default: "/.well-known/agent.json"
+
+# =============================================================================
+# OASF - OPEN AGENTIC SCHEMA FRAMEWORK (v2.4)
+# =============================================================================
+
+  oasf_skills:
+    type: array[string]
+    required: false
+    description: |
+      Skills from OASF taxonomy (category/skill_name format)
+      Reference: https://schema.oasf.outshift.com/
+    example:
+      - "code_generation/source_code_generation"
+      - "natural_language_processing/semantic_understanding"
+    common_values:
+      - "natural_language_processing/contextual_comprehension"
+      - "natural_language_processing/semantic_understanding"
+      - "natural_language_processing/entity_recognition"
+      - "code_generation/source_code_generation"
+      - "code_generation/code_review"
+      - "code_generation/test_generation"
+      - "data_engineering/data_transformation_pipeline"
+      - "agent_orchestration/task_delegation"
+      - "agent_orchestration/multi_agent_planning"
+      - "evaluation_monitoring/output_evaluation"
+      - "evaluation_monitoring/performance_monitoring"
+
+  oasf_domains:
+    type: array[string]
+    required: false
+    description: |
+      Domains from OASF taxonomy (category/domain_name format)
+    example:
+      - "technology/software_development"
+      - "finance_and_business/payment_services"
+    common_values:
+      - "technology/software_development"
+      - "technology/cloud_computing"
+      - "technology/data_science"
+      - "technology/cybersecurity"
+      - "finance_and_business/payment_services"
+      - "finance_and_business/financial_analysis"
+      - "healthcare/clinical_services"
+
+  oasf_record_id:
+    type: string
+    required: false
+    description: OASF record identifier
+    pattern: '^oasf:[a-z0-9-]+:[a-z0-9.-]+$'
+    example: "oasf:payment-gateway:v1.0.0"
+
+# =============================================================================
+# OPENTELEMETRY GENAI SEMANTIC CONVENTIONS (v2.4)
+# =============================================================================
+
+  observability:
+    type: object
+    required: false
+    description: OpenTelemetry GenAI attributes
+    properties:
+      otel_service_name:
+        type: string
+        description: service.name attribute
+        example: "payment-gateway"
+      gen_ai_agent_name:
+        type: string
+        description: gen_ai.agent.name attribute
+      gen_ai_agent_id:
+        type: string
+        description: gen_ai.agent.id attribute
+      gen_ai_provider:
+        type: enum
+        values: [anthropic, openai, aws.bedrock, azure.openai, google.vertex]
+      custom_attributes:
+        type: object
+        description: Additional OTel attributes
+        example:
+          deployment.environment: "production"
+          service.version: "1.2.0"
+
+  metrics:
+    type: array[string]
+    required: false
+    description: OTel metrics reported
+    common_values:
+      - "gen_ai.client.token.usage"
+      - "gen_ai.client.operation.duration"
+      - "gen_ai.server.request.duration"
+      - "gen_ai.server.time_to_first_token"
+
+# =============================================================================
+# CONTEXT ENGINEERING (v2.4)
+# =============================================================================
+
+  context_budget:
+    type: object
+    required: false
+    description: Token budgeting for context management
+    properties:
+      full_tokens:
+        type: integer
+        description: Tokens for complete document
+        example: 2500
+      summary_tokens:
+        type: integer
+        description: Tokens for metadata only
+        example: 150
+      min_useful_tokens:
+        type: integer
+        description: Minimum for useful context
+        example: 500
+
+  progressive_disclosure:
+    type: object
+    required: false
+    description: Staged content loading
+    properties:
+      level_1:
+        type: array[string]
+        description: Always load (metadata)
+        default: [title, description, category, status]
+      level_2:
+        type: array[string]
+        description: Load on relevance match
+        example: [overview, architecture, key_concepts]
+      level_3:
+        type: array[string]
+        description: Load on explicit request
+        example: [full_content, code_examples, troubleshooting]
+
+  retrieval_hints:
+    type: object
+    required: false
+    description: RAG optimization hints
+    properties:
+      chunk_size:
+        type: integer
+        description: Recommended chunk size (tokens)
+        default: 500
+      chunk_overlap:
+        type: integer
+        description: Token overlap between chunks
+        default: 50
+      key_sections:
+        type: array[string]
+        description: High-value sections
+        example: [overview, api-endpoints, configuration]
+      semantic_anchors:
+        type: array[string]
+        description: Key phrases for semantic search
+        example: ["payment processing", "Stripe integration"]
+      exclude_from_retrieval:
+        type: array[string]
+        description: Sections to exclude
+        example: [changelog, appendix, references]
+
+# =============================================================================
+# AGENT NOTES (Enhanced in v2.4)
+# =============================================================================
+
+  agent_notes:
+    type: object
+    required: false
+    description: Machine-readable hints for AI agents
+    properties:
+      # Core (from v2.3)
+      confidence:
+        type: enum
+        values: [high, medium, low]
+        default: medium
+      safe_for_codegen:
+        type: boolean
+        default: false
+      requires_human_review:
+        type: boolean
+        default: true
+      
+      # Enhanced (v2.4)
+      embedding_hint:
+        type: string
+        description: Alternative text for embedding generation
+        example: "Payment gateway for .NET 9 with Stripe"
+      tool_hints:
+        type: array[string]
+        description: Suggested tools for this document
+        example: ["code-search", "api-tester", "database-query"]
+      agent_capabilities_required:
+        type: array[string]
+        description: Capabilities needed to use effectively
+        example: ["code-execution", "web-fetch", "file-write"]
+      max_context_window:
+        type: integer
+        description: Minimum context window required (tokens)
+        example: 8000
+
+# =============================================================================
+# TIE-BREAKER RULES
+# =============================================================================
+
+tie_breaker_rules:
+  - order: 1
+    field: status
+    direction: "active > deprecated > sunset > draft"
+    description: "Active documents always win"
+
+  - order: 2
+    field: last_verified
+    direction: desc
+    description: "More recently verified wins"
+
+  - order: 3
+    field: retrieval_scope
+    direction: "service > skill > global"
+    description: "More specific scope wins"
+
+  - order: 4
+    field: retrieval_priority
+    direction: "critical > high > medium > low"
+    description: "Higher priority wins"
+
+  - order: 5
+    field: path_depth
+    direction: desc
+    description: "Deeper paths win"
+
+  - order: 6
+    field: filename
+    direction: asc
+    description: "Alphabetical as final tie-breaker"
+
+# =============================================================================
+# VALIDATION RULES
+# =============================================================================
+
+validation_rules:
+  # Required field rules
+  - id: SCHEMA_001
+    severity: ERROR
+    rule: "schema_version must be present and valid"
+    check: "frontmatter.schema_version matches ^\\d+\\.\\d+$"
+
+  - id: SCHEMA_002
+    severity: ERROR
+    rule: "Major schema version must not exceed supported"
+    check: "parseInt(schema_version.split('.')[0]) <= AGENT_MAX_MAJOR_VERSION"
+
+  - id: REQUIRED_001
+    severity: ERROR
+    rule: "Required fields must be present"
+    fields: [schema_version, title, category, status, last_updated]
+
+  - id: ENUM_001
+    severity: ERROR
+    rule: "Enum fields must use defined values"
+
+  # Recommended field rules
+  - id: RECOMMENDED_001
+    severity: WARNING
+    rule: "Recommended fields should be present"
+    fields: [version, retrieval_priority, retrieval_scope, last_verified, owner]
+
+  - id: DATE_001
+    severity: WARNING
+    rule: "Dates should be valid ISO-8601"
+    check: "date fields match YYYY-MM-DD"
+
+  - id: VERIFIED_001
+    severity: WARNING
+    rule: "Active documents should have recent verification"
+    check: "if status=active, last_verified within 90 days"
+
+  - id: DEPRECATED_001
+    severity: WARNING
+    rule: "Deprecated documents should specify replacement"
+    check: "if status=deprecated, superseded_by should be set"
+
+  # v2.4 specific rules
+  - id: MCP_001
+    severity: INFO
+    rule: "MCP URIs should use valid format"
+    check: "mcp_resource.uri matches ^mcp://[a-z0-9-]+/[a-z0-9-/]+$"
+
+  - id: OASF_001
+    severity: INFO
+    rule: "OASF skills should use category/skill format"
+    check: "oasf_skills items contain '/'"
+
+  - id: CONTEXT_001
+    severity: INFO
+    rule: "Context budget should be consistent"
+    check: "summary_tokens < full_tokens"
+
+  - id: CODEGEN_001
+    severity: INFO
+    rule: "Codegen-safe documents should have high confidence"
+    check: "if safe_for_codegen=true, confidence=high"
+
+  - id: SKILL_001
+    severity: WARNING
+    rule: "Skill documents should include a stable `name` for cross-tool skill loaders (Codex)."
+    check: "if category=skill, name should be set"
+
+
+  # v2.4.3 specific rules
+  - id: SOURCES_001
+    severity: WARNING
+    rule: "Sources entries must have source_id"
+    check: "if sources present, each sources[].source_id matches ^src:"
+
+  - id: RESEARCH_001
+    severity: WARNING
+    rule: "Research reports should declare research.question and at least one source"
+    check: "if category=research-report, research.question set AND sources length >= 1"
+
+  - id: SOURCE_DOC_001
+    severity: INFO
+    rule: "Source documents should include at least one sources entry"
+    check: "if category=source-document, sources length >= 1"
+
+  - id: RAG_001
+    severity: WARNING
+    rule: "Documents containing secrets must not be indexed for RAG"
+    check: "if data_handling.contains_secrets=true, rag.include=false AND data_handling.rag_allowed=false"