# YAML Schema for instruction type
type: object
properties:
  type:
    type: string
    const: "types/instruction.md"
    description: Must reference the instruction type-spec
  name:
    type: string
    minLength: 1
    description: Short identifier, matching the filename stem
  description:
    type: string
    minLength: 1
    description: >-
      The retrieval wire - the question an agent would ask when it needs this
      procedure, written to match that query rather than to label the file
  manual:
    type: boolean
    description: >-
      True for a rare, deliberate procedure that must never run implicitly.
      Exempts it from `instructions verify`'s reference requirement - and,
      symmetrically, `verify` then requires it NOT be linked from AGENTS.md
      or a skill (the paths an agent loads automatically), since a link
      there is exactly how it would stop being deliberate. A mention in a
      CONTRACT.md, a COLLECTION.md, or another instruction's prose is fine -
      that is documentation a reader opts into, not automatic pickup.
      Invoked only by explicit name on request.
  migrates_to:
    type: string
    pattern: "^[0-9]+\\.[0-9]+\\.[0-9]+$"
    description: >-
      Present on a migration document under `instructions/migrations/`: the
      stack version whose content shape this migration produces. `wikitool
      migrate status` builds the outstanding chain from these, so the value is
      the migration's identity as much as its label. Plain `x.y.z` - no
      pre-release suffixes anywhere in this stack.
  migration_kind:
    type: string
    enum: [mechanical, assisted]
    description: >-
      How the migration is carried out. `mechanical` is deterministic and
      scriptable; `assisted` needs a judgment call per page and is therefore an
      agent procedure. Today this is a description rather than an execution
      promise - there is no `migrate run`.
  obligation:
    type: string
    enum: [required, offered]
    default: required
    description: >-
      Whether the migration must run at all - a separate axis from
      `migration_kind`, which says only how the work is done. `required`
      (the default) is the original meaning: the content must reach the new
      shape or it no longer fits the machinery, so `migrate status` counts it
      as outstanding and `migrate done` advances `kb_version` through it.
      `offered` is an upgrade the instance may decline: a file it owns still
      works as it is, and the stack is proposing a better default. An offered
      migration never blocks, never appears in the outstanding chain, and is
      not a link in the version chain - it is listed separately so an operator
      can take it when they want it.
required:
  - type
  - name
  - description
additionalProperties: false