Skip to content

docs(governance): state who may author normative text - #271

Merged
imran-siddique merged 1 commit into
mainfrom
docs/normative-authorship-policy
Aug 4, 2026
Merged

docs(governance): state who may author normative text#271
imran-siddique merged 1 commit into
mainfrom
docs/normative-authorship-policy

Conversation

@imran-siddique

Copy link
Copy Markdown
Contributor

Mirrors agentrust-io/trace-spec#120, with the wording as drafted there.

Why

The rule that normative spec changes need an organizational sponsor is applied in review but written down nowhere. GOVERNANCE.md covers who may merge and how long comment periods run, CONTRIBUTING.md covers the mechanics, and neither says who may author a MUST. Contributors meet the rule for the first time on their own PR, after doing the work.

#270 is the live example: a normative MUST binding agent_id to OCSF ai_agent.instance_uid, authored individually, where the authorship question only surfaced at review time. The technical review of that PR stands on its own merits, but the process question should not have been a surprise.

This changes nothing in practice. It writes down what already happens.

What it says

  • Normative text is anything with an uppercase RFC 2119 keyword, and a normative change needs an organizational sponsor willing to be named as accountable for the requirement.
  • The reason is maintenance cost rather than merit: a MUST is a promise the project keeps for every future version, and assessing implementability across platforms needs an organization that will implement it and answer for it later.
  • Anyone may propose a normative change, proposals are judged on the technical argument alone, and where an accepted proposal has no sponsor a Maintainer carries the PR with the proposer credited in the CHANGELOG.
  • No sponsor is needed for bug fixes, SDK work, examples, conformance tests, tooling, schema changes tracking a merged spec change, or informative additions. It says so explicitly for crosswalks and mappings to external schemas such as OCSF, because that is the route a proposal like spec_change: agent_id as the correlation key for OCSF ai_agent.instance_uid (§3.1, §5.2) #270 can take today: a field correspondence is useful as guidance long before anyone should be required to follow it.
  • An unsponsored normative PR is not rejected on that basis. Reviewers either identify a sponsor or convert it to an informative change.

CONTRIBUTING.md gets a pointer at the top of the spec-change process so it is read before the work starts.

Process

GOVERNANCE.md amendments require a PR, a 14-day comment period, and Project Lead approval, per the Amendments section of that same document. Not merging this.

One thing to decide: if you edit the wording on trace-spec#120 during its comment period, this needs the same edit so the two repos do not drift.

🤖 Generated with Claude Code

Mirrors agentrust-io/trace-spec#120. The rule that normative spec changes
need an organizational sponsor is applied in review but written down
nowhere, so contributors meet it for the first time on their own PR,
after doing the work. #270 is a live example: a normative MUST binding
agent_id to OCSF ai_agent.instance_uid, authored individually, where the
authorship question only surfaced at review.

No change in practice. It also writes down that anyone may propose a
normative change, that proposals are judged on the argument alone, and
that a Maintainer carries the PR when an accepted proposal has no
sponsor, all of which was already true and equally unwritten.

Calls out explicitly that informative crosswalks and mappings to external
schemas need no sponsor, since that is the path a proposal like #270 can
take today.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@imran-siddique
imran-siddique merged commit d3eb829 into main Aug 4, 2026
2 checks passed
@imran-siddique
imran-siddique deleted the docs/normative-authorship-policy branch August 4, 2026 23:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant