# RFC Schema — Layer 3 Specialized Document Type
# KNO Schema Version: 0.6.0
# CHANGELOG:
#   0.6.0 (M52 P4.1, #2139): Add `visibility: public` collection default per REQ-18.
#                            RFCs are public reference knowledge consumed via the
#                            four-surface contract.
#
# Layer 3 schema that extends document-schema.kno for RFCs (Request for Comments).
# RFCs are normative documents that establish standards and design decisions.
#
# KEY DISTINCTION from spec-schema.kno:
# - spec-schema.kno: Defines schemas (field structures, validation)
# - rfc-schema.kno: Defines standards (normative requirements, MUST/SHOULD/MAY)
#
# EXTENDS: document-schema.kno (which composes identity, history, quality)
# ENABLES: RFC instances (rfc-001.kno, rfc-002.kno, etc.)

# =============================================================================
# SCHEMA DECLARATION (RFC-007)
# =============================================================================
$schema: kno@0.0.9

# =============================================================================
# IDENTITY (composed from identity-schema.kno)
# =============================================================================
id: 01KGK3V73KBJKZWKHTZ29C9NJV
slug: rfc-schema
type: spec
version: 0.1.0

# =============================================================================
# VISIBILITY DECLARATION (REQ-18) — collection default
# =============================================================================
# RFC entities (content/rfcs/*.kno) are public reference knowledge by default.
# Per REQ-18, individual entities MAY override with their own `visibility:` field
# (last-write-wins at the entity level). Drives the four-surface contract per
# kno-system_architecture.md § Agent Surface Integration and
# public-surface-parity.instructions.md.
visibility: public

# =============================================================================
# STANDARD TIER (inherited from document-schema.kno)
# =============================================================================
title: "RFC Schema"
purpose: |
  Define the schema for Request for Comments (RFC) documents.

  **What is an RFC?** An RFC is a normative document that proposes or
  establishes standards, specifications, and architectural decisions.
  RFCs use RFC 2119 keywords (MUST, SHOULD, MAY) for requirements.

  **RFC vs Spec**:
  | Aspect | RFC | Spec |
  |--------|-----|------|
  | Purpose | Propose/establish standards | Define data structures |
  | Keywords | MUST, SHOULD, MAY | type, required, pattern |
  | Audience | Decision makers, implementers | Developers, validators |
  | Example | RFC-001: KNO Format | user.kno |

  **Layer 3 Position**: RFC extends document (Layer 2), which composes
  identity, history, and quality (Layer 1). RFCs particularly benefit
  from the history primitive for tracking specification evolution.

# =============================================================================
# RICH TIER — Relationships (Edge Maximization)
# =============================================================================
provenance:
  origin:
    id: 01KGK3V73KBJKZWKHTZ29C9NJV
    timestamp: "2026-02-04T01:47:56Z"
    tool: manual-migration
taxonomy:
  topics:
    - standards
    - proposals
    - specifications
    - normative-documents
    - design-decisions
  keywords:
    - rfc
    - request-for-comments
    - standard
    - proposal
    - normative
    - requirement
    - must
    - should
    - may

relationships:
  extends:
    - xri: "kno://specs/document-schema"
      reason: "Layer 2 base type"

  depends_on:
    - xri: "kno://specs/kno-spec"
      reason: "RFC-001 defines kno@0.0.9 schema"

  composes:
    # Inherited through document-schema.kno:
    - xri: "kno://specs/identity-schema"
      reason: "Layer 1: id, canonical_id, local_ids, equiv_ids"
    - xri: "kno://specs/history-schema"
      reason: "Layer 1: _history, changelog (CRITICAL for RFCs)"
    - xri: "kno://specs/quality-schema"
      reason: "Layer 1: quality, validation, confidence"

  enables:
    - xri: "kno://rfcs/RFC-001"
      reason: "KNO Format RFC"
    - xri: "kno://rfcs/RFC-002"
      reason: "Entity Resolution RFC"

  related_to:
    - xri: "kno://specs/spec-schema"
      reason: "Sibling Layer 3 type (schema definitions)"
    - xri: "kno://specs/glossary-schema"
      reason: "Sibling Layer 3 type (terminology)"
    - xri: "kno://specs/guide-schema"
      reason: "Sibling Layer 3 type (how-to)"

quality:
  completeness: 0.9
  last_reviewed: "2026-01-06"
  review_status: draft
  reviewed_by: "claude"

# =============================================================================
# HISTORY (P9 Temporal — CRITICAL for RFCs)
# =============================================================================
_history:
  retention: full # RFCs MUST retain full history
  format: snapshot

  versions:
    - version: "0.5.0"
      date: "2026-01-06"
      author: "claude"
      summary: "Layer 3 refactor; extends document-schema.kno"
      changes:
        - "Refactored as Layer 3 schema extending document-schema.kno"
        - "Added composes/extends/enables relationships"
        - "Full history retention mandated for RFCs"
        - "Added RFC-specific fields (rfc_number, normative_sections)"
    - version: "0.2.0"
      date: "2025-12-16"
      author: "pspace-core-team"
      summary: "Added superseded status"
      changes:
        - "Extended status enum: added 'historical' and 'superseded'"
        - "Added superseded_by field"
    - version: "0.1.0"
      date: "2025-12-05"
      author: "pspace-core-team"
      summary: "Initial RFC schema"

# =============================================================================
# SPECIFICATION CONTENT
# =============================================================================
spec:
  status: Active

  description: |
    ## What is an RFC?

    An **RFC (Request for Comments)** is a normative document that proposes
    or establishes standards, specifications, and architectural decisions.

    ## RFC Lifecycle

    ```
    Draft → Active → Deprecated/Historical/Superseded
    ```

    | Status | Meaning |
    |--------|---------|
    | `draft` | Work in progress, open for comment |
    | `active` | Implemented and normative |
    | `historical` | Was implemented, architecture changed |
    | `superseded` | Replaced by newer RFC |

    ## RFC 2119 Keywords

    RFCs use normative keywords per RFC 2119:
    - **MUST** / **REQUIRED** / **SHALL** — Absolute requirement
    - **MUST NOT** / **SHALL NOT** — Absolute prohibition
    - **SHOULD** / **RECOMMENDED** — Strong recommendation
    - **SHOULD NOT** / **NOT RECOMMENDED** — Strong discouragement
    - **MAY** / **OPTIONAL** — Truly optional

    ## Layer 3 Inheritance

    RFC extends document, which composes Layer 1 primitives:

    ```
    rfc-schema.kno
    └── extends: document-schema.kno
        └── composes: identity-schema.kno, history-schema.kno, quality-schema.kno
    ```

    History is particularly important for RFCs — full version history
    MUST be retained to track specification evolution.

  # ===========================================================================
  # SCHEMA DEFINITION
  # ===========================================================================
  schema:
    # -------------------------------------------------------------------------
    # Required Fields
    # -------------------------------------------------------------------------
    required:
      - id # From identity-schema.kno (format: rfc-XXX)
      - rfc_number # RFC-specific: three-digit number
      - title # From document-schema.kno
      - status # RFC lifecycle state
      - content # Full RFC content

    # -------------------------------------------------------------------------
    # Field Definitions
    # -------------------------------------------------------------------------
    properties:
      # --- INHERITED FROM IDENTITY.KNO (Layer 1) ---
      id:
        type: string
        description: "RFC identifier in format 'rfc-XXX'"
        pattern: "^rfc-\\d{3}$"
        examples:
          - "rfc-001"
          - "rfc-011"

      # --- RFC-SPECIFIC IDENTITY ---
      rfc_number:
        type: string
        description: "Three-digit RFC number as string"
        pattern: "^\\d{3}$"
        examples:
          - "001"
          - "011"

      # --- INHERITED FROM DOCUMENT.KNO (Layer 2) ---
      type:
        type: string
        const: rfc
        description: "Entity type, always 'rfc' for RFC documents"

      version:
        type: string
        description: "Semantic version of this RFC"
        pattern: "^\\d+\\.\\d+\\.\\d+$"

      title:
        type: string
        description: "Human-readable title"
        examples:
          - "Knowledge Notation Object (KNO) Format Specification"
          - "Entity Resolution Standard"

      purpose:
        type: string
        description: "Brief description of what this RFC establishes"

      # REMOVED: audience field (DC-1: all .kno files serve all audiences)
      # REMOVED: facets (DC-2: domain/category are inferred, not declared)

      # --- RFC LIFECYCLE ---
      status:
        type: string
        enum: [draft, active, historical, superseded]
        description: |
          RFC lifecycle status:
          - draft: Work in progress
          - active: Implemented and normative
          - historical: Was implemented, architecture changed
          - superseded: Replaced by newer RFC

      supersedes:
        type: string
        description: "RFC ID this one supersedes"
        pattern: "^rfc-\\d{3}$"

      superseded_by:
        type: string
        description: "RFC ID that supersedes this"
        pattern: "^rfc-\\d{3}$"

      # --- RFC METADATA ---
      created:
        type: string
        format: date
        description: "RFC creation date"

      authors:
        type: array
        items:
          type: string
        description: "RFC authors"

      depends_on:
        type: array
        items:
          type: string
        description: "RFC IDs this depends on"

      # --- RFC CONTENT ---
      abstract:
        type: string
        description: "Brief summary (1-3 paragraphs)"

      content:
        type: string
        description: "Full RFC content (markdown with RFC 2119 keywords)"

      normative_sections:
        type: array
        description: "Sections containing normative requirements"
        items:
          type: object
          properties:
            title:
              type: string
            requirements:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                    description: "Requirement ID (e.g., REQ-01)"
                  level:
                    type: string
                    enum: [MUST, SHOULD, MAY]
                  text:
                    type: string

      # --- INHERITED FROM HISTORY.KNO (Layer 1) ---
      _history:
        type: object
        description: "Version history (MUST use retention: full for RFCs)"
        properties:
          retention:
            type: string
            const: full
            description: "RFCs MUST retain full history"
          format:
            type: string
            enum: [snapshot, diff]
          versions:
            type: array
            items:
              type: object

      # --- INHERITED FROM QUALITY.KNO (Layer 1) ---
      quality:
        type: object
        properties:
          completeness:
            type: number
          last_reviewed:
            type: string
            format: date
          review_status:
            type: string
            enum: [draft, review, approved, deprecated]

      # --- RELATIONSHIPS ---
      relationships:
        type: object
        properties:
          extends:
            type: array
            items:
              type: string
          depends_on:
            type: array
            items:
              type: string
          related_to:
            type: array
            items:
              type: string

      taxonomy:
        type: object

  # ===========================================================================
  # EXAMPLES
  # ===========================================================================
  examples:
    - title: "Minimal RFC"
      description: "Minimum required fields for a valid RFC"
      code: |
        $schema: kno@0.0.9

        id: rfc-099
        rfc_number: "099"
        title: "Example RFC"
        status: draft

        content: |
          ## Summary
          This RFC proposes...
          
          ## Requirements
          Implementations MUST support...

    - title: "RFC with Full History"
      description: "RFC demonstrating P9 temporal history"
      code: |
        $schema: kno@0.0.9

        id: rfc-001
        rfc_number: "001"
        version: 0.5.1

        title: "KNO Format Specification"
        status: active
        created: "2025-12-02"
        authors:
          - "Possibility Contributors"

        abstract: |
          This RFC establishes KNO (Knowledge Notation Object),
          a schema for structured knowledge documents.

        _history:
          retention: full
          format: snapshot
          versions:
            - version: "0.5.1"
              date: "2026-01-06"
              author: "claude"
              summary: "Derived connectivity"
            - version: "0.5.0"
              date: "2026-01-05"
              author: "claude"
              summary: "Added kno_containment"

        content: |
          ## 1. Introduction
          ...

  # ===========================================================================
  # NOTES (Design Decisions)
  # ===========================================================================
  notes: |
    ## Design Decisions

    1. **History Retention Mandate**: RFCs MUST use `retention: full`
       because specification evolution is critical for understanding
       design decisions and backward compatibility.

    2. **Normative Sections**: The `normative_sections` field enables
       machine-readable extraction of requirements for compliance
       checking and test generation.

    3. **RFC 2119 Integration**: RFCs should use standard RFC 2119
       keywords in their content. The `requirements` array in
       `normative_sections` captures these for tooling.

    4. **Supersession Chain**: When an RFC is superseded, both
       `supersedes` and `superseded_by` create a bidirectional
       chain for tracing specification evolution.

# =============================================================================
# CONTAINER TIER — Navigation Index
# =============================================================================
_index:
  - path: "identity"
    line: 18
    keywords: [id, type, version, rfc-schema]
  - path: "spec/fields"
    line: 80
    keywords: [title, status, authors, abstract, motivation]
  - path: "spec/status"
    line: 150
    keywords: [draft, proposed, accepted, implemented, deprecated]
  - path: "spec/normative"
    line: 220
    keywords: [normative_sections, MUST, SHOULD, MAY]
  - path: "spec/examples"
    line: 320
    keywords: [minimal, full, supersession]
  - path: "notes"
    line: 400
    keywords: [status-transitions, normative, supersession-chain]

contains:
  - xri: "#identity"
    role: section
    title: "Schema Metadata"
    keywords: [id, type, version]
  - xri: "#spec"
    role: section
    title: "RFC Schema"
    keywords: [status, normative, supersession]
  - xri: "#notes"
    role: section
    title: "Design Notes"
    keywords: [transitions, chains]