docs: specify parameter-level annotations

What does this MR do and why?

Adds the OpenSpec change add-parameter-extensions for #32. This MR is planning only; the implementation is the next MR in the stack.

Which REST parameters need which GitLab tier is recorded only as prose in the hand-written API docs, so the generated OpenAPI document can't say it. The change adds config.parameter_annotations, which maps keys of a param's documentation: hash to OpenAPI extensions:

config.parameter_annotations = { tier: 'x-gitlab-tier' }

optional :weight, type: Integer, desc: 'Weight', documentation: { tier: :premium }
# => x-gitlab-tier: premium on the query/path parameter object, or on the request-body property

The change consists of:

• proposal.md
• delta specs for parameters, request-bodies and configuration
• design.md
• tasks.md

All of it is under openspec/changes/add-parameter-extensions/.

Where this departs from #32

• Values are written as JSON values, not with .to_s.
  • true stays true, and an Array stays an Array.
  • Symbols become Strings, and Hash keys become Symbols.
  • nil adds no extension.
  • A Proc, Class or any other value is dropped. When config.warnings is on, it writes a new dropped parameter annotation diagnostic.
• Extension names and Hash keys are emitted as Symbols.
  • The request-body registry sorts every Hash it hashes, and Ruby can't sort a mix of String and Symbol keys.
  • String names, or a value like { min: :premium, 'note' => 'n' }, therefore make it raise ArgumentError.
  • #32's "no registry change is needed" holds only with Symbol keys.
• No 0.4.0 bump or CHANGELOG entry.
  • The gem is already at 0.6.0.
  • Releases go through the Release MR flow.
  • The repository has no CHANGELOG.md.

How to verify

npx -y @fission-ai/openspec@1.13.2 validate add-parameter-extensions --strict
npx -y @fission-ai/openspec@1.13.2 show add-parameter-extensions

Related to #32

Stack

1. !68 (merged): OpenSpec baseline (docs/openspec-baseline → main)
2. !69 (merged): Specification for #32 (32-specify-parameter-annotations → docs/openspec-baseline) (this MR)
3. !70: Implementation for #32 (32-support-parameter-annotations → 32-specify-parameter-annotations)

Merge from the bottom up: !68 (merged), then !69 (merged), then !70.

🤖 Generated with Claude Code