management/docs/sources/upstream/neckbeard-v0.3.1/schema.yaml

# schema.yaml — single source of truth for artifact frontmatter.
# Stage 1 of ADR-0004: scripts/validate.py checks generically against this
# file. Extending the framework's metadata means editing THIS file, not code.
# Agents: never invent fields or status values; propose a schema change.

version: 1

scope:
  # Files considered artifacts. Templates and raw sources are exempt.
  include:
    - "PROJECT.md"
    - "docs/**/*.md"
  exclude:
    - "**/template.md"
    - "docs/sources/**"
    - "vendor/**"
  # Files whose inline links are checked, but which need no frontmatter
  # (root-level prose: README, AGENTS, WORKFLOW, generated STATUS, ...).
  link_only:
    - "*.md"

# Files an adopting project holds byte-identical against its vendored
# baseline (AGENTS.md §5). They are copied into repositories that do not
# have this repo's docs/, so they must carry no repo-relative link — a
# link that resolves here and nowhere else makes the adoption path
# unfollowable. Mention an ADR by its identifier instead.
vendored:
  - "AGENTS.md"
  - "WORKFLOW.md"
  - "CLAUDE.md"

# An adopting project appends its own always-on rules below a marker in a
# vendored file (AGENTS.md §5). Everything from the marker on belongs to
# that project, is never copied anywhere, and may link freely — the rule
# above applies only to the upstream part. Adopters set their own marker.
project_section_marker: "<!-- project-section -->"

# Frontmatter fields whose values are links. Values starting with
# http://, https:// or mailto: are treated as external and only
# format-checked; everything else must be a repo-root-relative path
# to an existing file.
link_fields: [related, sources, supersedes, superseded_by, judged]

types:
  project:
    dir: "."
    filename: "^PROJECT\\.md$"
    required: [type, language, size_s_exception, purpose, audience]
    fields:
      language: { enum: [de, en] }
      size_s_exception: { kind: bool }
      purpose: { kind: str }
      audience: { kind: str }

  adr:
    dir: "docs/adr"
    filename: "^\\d{4}-[a-z0-9-]+\\.md$"
    required: [type, id, status, date]
    fields:
      id: { pattern: "^\\d{4}$" }
      status: { enum: [proposed, accepted, superseded] }
      date: { kind: date }
      supersedes: { kind: link, nullable: true }
      superseded_by: { kind: link, nullable: true }
      related: { kind: links }
    rules:
      # status: superseded requires superseded_by to point at the successor.
      - superseded_requires_pointer

  design:
    dir: "docs/design"
    filename: "^\\d{4}-\\d{2}-\\d{2}-[a-z0-9-]+\\.md$"
    required: [type, status, date, size]
    fields:
      status: { enum: [gate-1, gate-2, gate-3, gate-4, gate-5, done] }
      size: { enum: [L] }
      date: { kind: date }
      related: { kind: links }
    rules:
      # status: done if and only if the file lives under docs/design/done/.
      - done_iff_in_done_dir

  aar:
    dir: "docs/aar"
    filename: "^\\d{4}-\\d{2}-\\d{2}-[a-z0-9-]+\\.md$"
    required: [type, status, date]
    fields:
      status: { enum: [open, harvested] }
      date: { kind: date }
      related: { kind: links }

  issue:
    dir: "docs/issues"
    filename: "^\\d{4}-[a-z0-9-]+\\.md$"
    required: [type, id, status, created]
    fields:
      id: { pattern: "^\\d{4}$" }
      status: { enum: [open, in-progress, done, rejected] }
      created: { kind: date }
      related: { kind: links }

  # One per session. The envelope is validated here; the gate rows and
  # ladder entries in the body are outside what this engine can express
  # (it has no notion of a list of records) and belong to scripts/judge.py.
  # That seam is deliberate — see ADR-0010.
  ledger:
    dir: "docs/ledger"
    filename: "^\\d{4}-\\d{2}-\\d{2}-[a-z0-9-]+\\.md$"
    required: [type, date, size, status]
    fields:
      date: { kind: date }
      size: { enum: [S, M, L] }
      status: { enum: [open, closed] }
      related: { kind: links }

  # The output of a judged run. Categories are the two-bucket
  # classification the harvest assessment established: a finding is either
  # the model not following a clear rule, or a gap in the framework.
  verdict:
    dir: "docs/verdict"
    filename: "^\\d{4}-\\d{2}-\\d{2}-[a-z0-9-]+\\.md$"
    required: [type, date, outcome, judged]
    fields:
      date: { kind: date }
      outcome: { enum: [clean, model-failure, framework-gap, both] }
      related: { kind: links }

  wiki-page:
    dir: "docs/wiki"
    filename: "^[a-z0-9-]+\\.md$"
    required: [type, area]
    fields:
      area:
        enum:
          - index
          - architecture
          - admin
          - deployment
          - user-guide
          - requirements
          - faq
          - stolpersteine
      # Optional, and meaningful on a page that records a recurring failure
      # class (area: stolpersteine). `harvested` means a released framework
      # version covers the pattern — handed over is not harvested, and
      # `harvested_in` names that version (ADR-0009).
      status: { enum: [open, partly, harvested] }
      harvested_in: { kind: str }
      sources: { kind: links }
      related: { kind: links }
    rules:
      # Pages other than the index should be linked from somewhere
      # (reported as WARNING, not error — see validate.py).
      - warn_if_orphan