From a158b54fa06bfedb1ff449a465f3bb56f90b2799 Mon Sep 17 00:00:00 2001 From: Miguel Quintero Date: Tue, 30 Jun 2026 15:01:20 -0400 Subject: [PATCH 1/6] Add AGENTS.md for AI coding agents constrained by contribution+AI guidelines This document provides guidelines for coding agents in the OpenAPI-Specification repository, detailing the purpose, operating principles, editing rules, validation processes, and expectations for pull requests. --- AGENTS.md | 157 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 157 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..b1ec50cd46 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,157 @@ +# AGENTS.md + +This document guides coding agents and AI-assisted contributors working in the [OAI/OpenAPI-Specification](https://github.com/OAI/OpenAPI-Specification) repository. + +It combines the repository's documented contribution and validation workflow with an additional OpenAPI Initiative AI policy constraint supplied for this task. + +## Purpose + +Use this repository carefully. The OpenAPI Specification is standards work, not ordinary product documentation, so contributions must be precise, context-aware, and inexpensive for volunteer maintainers to review. + +## Operating principles + +- Prefer narrow, well-justified edits over broad rewrites. +- Keep maintainers' review effort lower than the effort used to prepare the change. +- Do not invent standards intent, governance outcomes, consensus, or release targets. +- Treat AI output as draft material that a human must understand, verify, and take responsibility for. + +## Repository layout + +- Active specification development happens in `src/oas.md` on versioned development branches, not as routine edits on `main`. +- General repository documentation, scripts, and automation typically belong on `main`. +- Published specification artifacts under `versions/` are not edited directly except in rare maintainer-approved external-link repair cases. +- The repository includes markdown linting and style conventions that should be preserved when editing prose. + +## Branch selection + +Use this routing model before editing files. + +| Request type | Primary files | Target branch | +|---|---|---| +| Active specification text | `src/oas.md` | Earliest relevant active `vX.Y-dev` branch | +| Schema changes tied to active spec work | Relevant schema files | Same active `vX.Y-dev` branch | +| Repository docs, scripts, workflow files, guidance | Non-spec support files on `main` | `main` | +| Historical published specification text | `versions/` | Do not edit directly except approved link-fix exceptions | + +## When to use discussion, issue, proposal, or PR + +- Use a discussion for exploratory ideas, early feedback, unclear requirements, or broad design questions. +- Use an issue for a specific problem or a concrete, scoped change request. +- Use the proposal process for substantial normative changes that need structured review and wider consensus. +- Use a pull request only when the change is concrete, justified, and targeted to the correct branch. + +## AI policy constraints + +The following behavioral rules apply in addition to normal repository rules. + +### Permitted AI use + +- AI may assist with drafting, editing, consistency checking, outlining, or exploring alternatives. +- AI may help prepare candidate wording, implementation notes, or validation checklists. +- AI-assisted output must be treated as tentative until a human has reviewed it line by line. + +### Required human accountability + +- The human submitter is responsible for every statement, edit, and design implication in the final contribution. +- Every claim must be explainable without relying on "the AI suggested it" as justification. +- If the human operator cannot defend a generated section, remove or rewrite it before submission. + +### Disclosure + +- If AI was used beyond autocomplete or spellcheck, disclose that use in the pull request or issue description. +- Keep disclosure short and factual, describing how AI helped rather than delegating responsibility to the tool. + +### Human-only channels + +- Do not use AI to generate issue comments, discussion replies, or pull request descriptions for direct posting. +- Do not use AI to summarize discussion content and then post the summary back into the discussion. +- Discussions are part of the project's design record and should reflect genuine human reasoning. + +### Quality bar + +Do not submit AI-assisted work unless it is all of the following: +- accurate +- concise +- non-repetitive +- grounded in current repository context +- clearly understood by the human submitter +- cheaper for maintainers to review than it was to produce + +Low-effort, inaccurate, overly verbose, or generic contributions should be discarded rather than submitted. + +## Editing rules + +### Spec changes + +- Edit only the relevant `src/oas.md` on the appropriate active development branch for normal specification work. +- Keep patch-line changes editorial or clarifying only; do not introduce schema requirements in patch releases. +- For minor or major work, include related schema updates when the specification change requires them. +- Support changes with realistic use cases and migration awareness, not hypothetical novelty alone.[cite:52] + +### Published versions + +- Do not rewrite `versions/*.md` as part of routine work. +- If asked to modify a published version, redirect the change to the active development branch unless maintainers explicitly approve a narrow exception. + +### Prose and formatting + +- Follow existing repository writing patterns and the style guide when editing specification text or contributor docs. +- Preserve markdown formatting compatible with the repository's markdownlint configuration. +- Avoid unnecessary reflow, reformatting, or terminology churn. + +## Validation + +For changes that affect `src/oas.md`: + +1. Run `npm install` from the repository root. +2. Run `npm run build-src`, which also performs markdown validation first. +3. Review the generated preview at `deploy-preview/oas.html` in a browser. +4. On Windows, prefer Git Bash or WSL for the repository scripts. + +## Pull request expectations + +- Work from a fork and submit changes through a pull request. +- Prefer opening an issue before substantial implementation work unless the change is obviously small. +- Use Draft PRs for incomplete or dependent work. +- Keep each PR focused on a single logical change set. +- Expect one Maintainer or TSC approval for all PRs, and two TSC approvals for PRs that change `src/oas.md`. +- If AI materially assisted the contribution, ensure disclosure is present, but the final PR description itself should be authored by a human under the supplied AI policy. + +## Safe agent behavior + +Agents should: +- make the smallest complete change that addresses the request +- explain branch choice and file choice clearly in handoff notes +- surface uncertainty early when the correct release line or process is unclear +- produce outputs that humans can readily review, trim, and restate in their own words +- prefer concrete diffs, checklists, and validation notes over persuasive prose + +Agents should not: +- generate content meant for direct posting into discussions, issue threads, or PR descriptions +- create filler text or "summary" comments that add no new information +- speculate about approval status or community consensus +- edit `versions/` during routine contribution work +- hide uncertainty behind polished wording + +## Suggested workflow + +1. Classify the request as spec text, schema, docs, automation, or proposal-related work. +2. Decide whether the task belongs in a discussion, issue, proposal, or PR. +3. Select the correct branch: `main` for repository-wide support files, earliest relevant active `vX.Y-dev` for specification and schema work. +4. Draft the smallest complete change. +5. Check the draft against the AI quality bar in this file. +6. Run validation for any `src/oas.md` changes and inspect the generated preview. +7. Hand off for human review, disclosure, and human-authored submission text. + +## Minimal AI disclosure template + +```md +AI assistance disclosure: AI was used to help draft or edit parts of this change and to check consistency. The final content was reviewed by the submitter, who can explain and defend all resulting changes. +``` + +## Stop + +Pause and ask for human guidance when: +- the request conflicts with branch strategy or contribution process rules +- the correct target branch is ambiguous +- the task is to generate a discussion reply, issue comment, or PR description for direct posting From 1b64f0c7e3b5abcfab780b0e7b9bf1c42d167175 Mon Sep 17 00:00:00 2001 From: Miguel Quintero Date: Tue, 7 Jul 2026 10:27:52 -0400 Subject: [PATCH 2/6] Update AGENTS.md minor fixes, also covers style guide guidance --- AGENTS.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b1ec50cd46..e5e3f163cb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,7 +6,7 @@ It combines the repository's documented contribution and validation workflow wit ## Purpose -Use this repository carefully. The OpenAPI Specification is standards work, not ordinary product documentation, so contributions must be precise, context-aware, and inexpensive for volunteer maintainers to review. +Use this repository carefully. The OpenAPI Specification (OAS) is standards work, not ordinary product documentation, so contributions must be precise, context-aware, and inexpensive for volunteer maintainers to review. ## Operating principles @@ -70,6 +70,7 @@ The following behavioral rules apply in addition to normal repository rules. ### Quality bar Do not submit AI-assisted work unless it is all of the following: + - accurate - concise - non-repetitive @@ -86,7 +87,7 @@ Low-effort, inaccurate, overly verbose, or generic contributions should be disca - Edit only the relevant `src/oas.md` on the appropriate active development branch for normal specification work. - Keep patch-line changes editorial or clarifying only; do not introduce schema requirements in patch releases. - For minor or major work, include related schema updates when the specification change requires them. -- Support changes with realistic use cases and migration awareness, not hypothetical novelty alone.[cite:52] +- Support changes with realistic use cases and migration awareness, not hypothetical novelty alone. ### Published versions @@ -114,12 +115,13 @@ For changes that affect `src/oas.md`: - Prefer opening an issue before substantial implementation work unless the change is obviously small. - Use Draft PRs for incomplete or dependent work. - Keep each PR focused on a single logical change set. -- Expect one Maintainer or TSC approval for all PRs, and two TSC approvals for PRs that change `src/oas.md`. +- Expect one Maintainer or Technical Steering Committee (TSC) approval for all PRs, and two TSC approvals for PRs that change `src/oas.md`. - If AI materially assisted the contribution, ensure disclosure is present, but the final PR description itself should be authored by a human under the supplied AI policy. ## Safe agent behavior Agents should: + - make the smallest complete change that addresses the request - explain branch choice and file choice clearly in handoff notes - surface uncertainty early when the correct release line or process is unclear @@ -127,6 +129,7 @@ Agents should: - prefer concrete diffs, checklists, and validation notes over persuasive prose Agents should not: + - generate content meant for direct posting into discussions, issue threads, or PR descriptions - create filler text or "summary" comments that add no new information - speculate about approval status or community consensus @@ -152,6 +155,7 @@ AI assistance disclosure: AI was used to help draft or edit parts of this change ## Stop Pause and ask for human guidance when: -- the request conflicts with branch strategy or contribution process rules -- the correct target branch is ambiguous + +- the request conflicts with branch strategy or contribution process rules +- the correct target branch is ambiguous - the task is to generate a discussion reply, issue comment, or PR description for direct posting From b0c57a37583b79e2dbc8eba2095923b4cbb82abb Mon Sep 17 00:00:00 2001 From: Miguel Quintero Date: Tue, 7 Jul 2026 10:39:31 -0400 Subject: [PATCH 3/6] Update AGENTS.md fix md errors --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index e5e3f163cb..b21496b830 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -27,7 +27,7 @@ Use this repository carefully. The OpenAPI Specification (OAS) is standards work Use this routing model before editing files. | Request type | Primary files | Target branch | -|---|---|---| +| --- | --- | --- | | Active specification text | `src/oas.md` | Earliest relevant active `vX.Y-dev` branch | | Schema changes tied to active spec work | Relevant schema files | Same active `vX.Y-dev` branch | | Repository docs, scripts, workflow files, guidance | Non-spec support files on `main` | `main` | From c29daeffadd85b175c2b1fa8c787d4cc6b20f9b8 Mon Sep 17 00:00:00 2001 From: Miguel Quintero Date: Wed, 15 Jul 2026 09:42:40 -0400 Subject: [PATCH 4/6] Revise agent guidance and editing rules Updated guidance for coding agents, emphasizing the need for human oversight and clarifying editing rules. Adjusted sections on operating principles, branch selection, and AI policy constraints. improve progressive disclosure --- AGENTS.md | 174 +++++++++++++----------------------------------------- 1 file changed, 41 insertions(+), 133 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b21496b830..66c9a212f6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,161 +1,69 @@ # AGENTS.md -This document guides coding agents and AI-assisted contributors working in the [OAI/OpenAPI-Specification](https://github.com/OAI/OpenAPI-Specification) repository. +Guidance for coding agents working in the [OAI/OpenAPI-Specification](https://github.com/OAI/OpenAPI-Specification) repository. This file contains only what agents need at session start. Deeper procedure lives in the linked documents — read them when a task touches their area, and treat them as authoritative if this file ever disagrees. -It combines the repository's documented contribution and validation workflow with an additional OpenAPI Initiative AI policy constraint supplied for this task. +## Stop and ask first -## Purpose +Pause and request human guidance before editing when: -Use this repository carefully. The OpenAPI Specification (OAS) is standards work, not ordinary product documentation, so contributions must be precise, context-aware, and inexpensive for volunteer maintainers to review. +- The correct target branch is ambiguous. +- The request conflicts with the branch strategy or contribution process below. +- The task asks you to draft a discussion reply, issue comment, or PR description for direct posting (prohibited — see Hard rules). +- The request touches `versions/` or asks for a schema requirement on a patch release line. -## Operating principles - -- Prefer narrow, well-justified edits over broad rewrites. -- Keep maintainers' review effort lower than the effort used to prepare the change. -- Do not invent standards intent, governance outcomes, consensus, or release targets. -- Treat AI output as draft material that a human must understand, verify, and take responsibility for. - -## Repository layout - -- Active specification development happens in `src/oas.md` on versioned development branches, not as routine edits on `main`. -- General repository documentation, scripts, and automation typically belong on `main`. -- Published specification artifacts under `versions/` are not edited directly except in rare maintainer-approved external-link repair cases. -- The repository includes markdown linting and style conventions that should be preserved when editing prose. - -## Branch selection - -Use this routing model before editing files. +## Where changes go | Request type | Primary files | Target branch | | --- | --- | --- | | Active specification text | `src/oas.md` | Earliest relevant active `vX.Y-dev` branch | -| Schema changes tied to active spec work | Relevant schema files | Same active `vX.Y-dev` branch | -| Repository docs, scripts, workflow files, guidance | Non-spec support files on `main` | `main` | -| Historical published specification text | `versions/` | Do not edit directly except approved link-fix exceptions | - -## When to use discussion, issue, proposal, or PR - -- Use a discussion for exploratory ideas, early feedback, unclear requirements, or broad design questions. -- Use an issue for a specific problem or a concrete, scoped change request. -- Use the proposal process for substantial normative changes that need structured review and wider consensus. -- Use a pull request only when the change is concrete, justified, and targeted to the correct branch. - -## AI policy constraints - -The following behavioral rules apply in addition to normal repository rules. - -### Permitted AI use - -- AI may assist with drafting, editing, consistency checking, outlining, or exploring alternatives. -- AI may help prepare candidate wording, implementation notes, or validation checklists. -- AI-assisted output must be treated as tentative until a human has reviewed it line by line. - -### Required human accountability - -- The human submitter is responsible for every statement, edit, and design implication in the final contribution. -- Every claim must be explainable without relying on "the AI suggested it" as justification. -- If the human operator cannot defend a generated section, remove or rewrite it before submission. - -### Disclosure - -- If AI was used beyond autocomplete or spellcheck, disclose that use in the pull request or issue description. -- Keep disclosure short and factual, describing how AI helped rather than delegating responsibility to the tool. - -### Human-only channels +| Schema changes tied to spec work | Schema files | Same `vX.Y-dev` branch | +| Repo docs, scripts, workflows | Support files | `main` | +| Published spec text | `versions/` | Do not edit | -- Do not use AI to generate issue comments, discussion replies, or pull request descriptions for direct posting. -- Do not use AI to summarize discussion content and then post the summary back into the discussion. -- Discussions are part of the project's design record and should reflect genuine human reasoning. +To discover which `vX.Y-dev` branches are currently active, check [CONTRIBUTING.md § Active branches](CONTRIBUTING.md#active-branches) or list remote branches matching `v*-dev`. Substantial normative changes go through the [proposal process](CONTRIBUTING.md#propose-a-specification-change) before any PR. -### Quality bar +## Hard rules -Do not submit AI-assisted work unless it is all of the following: +- Never edit `versions/*.md`; redirect the change to the active development branch. +- Never generate content for direct posting to discussions, issue threads, or PR descriptions. Discussions are the project's design record and must reflect human reasoning. Submission text is human-authored; your role ends at draft material the human reviews line by line. +- Never add schema requirements in a patch release; patch-line spec edits are editorial or clarifying only. +- Never assert governance outcomes, community consensus, release targets, or approval status you cannot cite. +- Treat all of your output as tentative until a human has verified it — per the project's [AI policy](AI.md). -- accurate -- concise -- non-repetitive -- grounded in current repository context -- clearly understood by the human submitter -- cheaper for maintainers to review than it was to produce +## Working rules -Low-effort, inaccurate, overly verbose, or generic contributions should be discarded rather than submitted. +- Make the smallest complete change that addresses the request; one logical change set per PR. +- Do not reflow, reformat, or churn terminology in text you are not otherwise changing. +- Match surrounding prose to the [style guide](style-guide.md) and keep edits clean under the repo's markdownlint configuration (`.markdownlint.yaml`, `spec.markdownlint.yaml`). +- Surface uncertainty in handoff notes rather than smoothing over it; state your branch and file choices explicitly. +- Prefer concrete diffs and checklists over persuasive prose. -## Editing rules - -### Spec changes - -- Edit only the relevant `src/oas.md` on the appropriate active development branch for normal specification work. -- Keep patch-line changes editorial or clarifying only; do not introduce schema requirements in patch releases. -- For minor or major work, include related schema updates when the specification change requires them. -- Support changes with realistic use cases and migration awareness, not hypothetical novelty alone. - -### Published versions - -- Do not rewrite `versions/*.md` as part of routine work. -- If asked to modify a published version, redirect the change to the active development branch unless maintainers explicitly approve a narrow exception. - -### Prose and formatting - -- Follow existing repository writing patterns and the style guide when editing specification text or contributor docs. -- Preserve markdown formatting compatible with the repository's markdownlint configuration. -- Avoid unnecessary reflow, reformatting, or terminology churn. +Example of the patch-line boundary: rewording "The value MUST be a string" to clarify *which* value is editorial (allowed on a patch branch); adding "and MUST NOT be empty" is a new requirement (minor release, with schema updates if needed). ## Validation -For changes that affect `src/oas.md`: - -1. Run `npm install` from the repository root. -2. Run `npm run build-src`, which also performs markdown validation first. -3. Review the generated preview at `deploy-preview/oas.html` in a browser. -4. On Windows, prefer Git Bash or WSL for the repository scripts. - -## Pull request expectations +For any change to `src/oas.md`: -- Work from a fork and submit changes through a pull request. -- Prefer opening an issue before substantial implementation work unless the change is obviously small. -- Use Draft PRs for incomplete or dependent work. -- Keep each PR focused on a single logical change set. -- Expect one Maintainer or Technical Steering Committee (TSC) approval for all PRs, and two TSC approvals for PRs that change `src/oas.md`. -- If AI materially assisted the contribution, ensure disclosure is present, but the final PR description itself should be authored by a human under the supplied AI policy. - -## Safe agent behavior - -Agents should: - -- make the smallest complete change that addresses the request -- explain branch choice and file choice clearly in handoff notes -- surface uncertainty early when the correct release line or process is unclear -- produce outputs that humans can readily review, trim, and restate in their own words -- prefer concrete diffs, checklists, and validation notes over persuasive prose - -Agents should not: - -- generate content meant for direct posting into discussions, issue threads, or PR descriptions -- create filler text or "summary" comments that add no new information -- speculate about approval status or community consensus -- edit `versions/` during routine contribution work -- hide uncertainty behind polished wording +```sh +npm install +npm run build-src # runs markdown validation first +``` -## Suggested workflow +Then inspect `deploy-preview/oas.html` in a browser. If markdownlint fails, fix only violations introduced by your change; pre-existing violations get flagged in handoff notes, not fixed opportunistically. On Windows, use Git Bash or WSL. Full local-preview details: [CONTRIBUTING.md § Preview specification HTML locally](CONTRIBUTING.md#preview-specification-html-locally). -1. Classify the request as spec text, schema, docs, automation, or proposal-related work. -2. Decide whether the task belongs in a discussion, issue, proposal, or PR. -3. Select the correct branch: `main` for repository-wide support files, earliest relevant active `vX.Y-dev` for specification and schema work. -4. Draft the smallest complete change. -5. Check the draft against the AI quality bar in this file. -6. Run validation for any `src/oas.md` changes and inspect the generated preview. -7. Hand off for human review, disclosure, and human-authored submission text. +## Disclosure -## Minimal AI disclosure template +If AI assisted beyond autocomplete or spellcheck, the human submitter discloses it in the PR or issue description per [AI.md](AI.md). Suggested wording: ```md -AI assistance disclosure: AI was used to help draft or edit parts of this change and to check consistency. The final content was reviewed by the submitter, who can explain and defend all resulting changes. +AI assistance disclosure: AI was used to help draft or edit parts of this change +and to check consistency. The final content was reviewed by the submitter, who +can explain and defend all resulting changes. ``` -## Stop - -Pause and ask for human guidance when: +## Further reading -- the request conflicts with branch strategy or contribution process rules -- the correct target branch is ambiguous -- the task is to generate a discussion reply, issue comment, or PR description for direct posting +- [AI.md](AI.md) — the OpenAPI Initiative AI policy: permitted use, accountability, disclosure, quality expectations. +- [CONTRIBUTING.md](CONTRIBUTING.md) — active branches, discussions vs. issues vs. proposals, PR process and reviewer counts, release scope. +- [style-guide.md](style-guide.md) — prose conventions for specification text. +- [GOVERNANCE.md](GOVERNANCE.md) — TSC and maintainer roles. From fca4d175b684b99dba42757b37f52a115f66d442 Mon Sep 17 00:00:00 2001 From: Miguel Quintero Date: Wed, 15 Jul 2026 09:56:21 -0400 Subject: [PATCH 5/6] Update AGENTS.md with hard rules and validation steps Added hard rules and validation instructions for coding agents. --- AGENTS.md | 35 ++++++++++++++++++++--------------- 1 file changed, 20 insertions(+), 15 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 66c9a212f6..6fda76537b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,13 +2,21 @@ Guidance for coding agents working in the [OAI/OpenAPI-Specification](https://github.com/OAI/OpenAPI-Specification) repository. This file contains only what agents need at session start. Deeper procedure lives in the linked documents — read them when a task touches their area, and treat them as authoritative if this file ever disagrees. +## Hard rules + +- Never edit `versions/*.md`; redirect the change to the active development branch. +- Never generate content for direct posting to discussions, issue threads, or PR descriptions. Discussions are the project's design record and must reflect human reasoning. Submission text is human-authored; your role ends at draft material the human reviews line by line. +- Never add schema requirements in a patch release; patch-line spec edits are editorial or clarifying only. +- Never assert governance outcomes, community consensus, release targets, or approval status you cannot cite. +- Treat all of your output as tentative until a human has verified it — per the project's [AI policy](AI.md). + ## Stop and ask first Pause and request human guidance before editing when: - The correct target branch is ambiguous. - The request conflicts with the branch strategy or contribution process below. -- The task asks you to draft a discussion reply, issue comment, or PR description for direct posting (prohibited — see Hard rules). +- The task asks you to draft a discussion reply, issue comment, or PR description for direct posting (prohibited above). - The request touches `versions/` or asks for a schema requirement on a patch release line. ## Where changes go @@ -20,36 +28,33 @@ Pause and request human guidance before editing when: | Repo docs, scripts, workflows | Support files | `main` | | Published spec text | `versions/` | Do not edit | -To discover which `vX.Y-dev` branches are currently active, check [CONTRIBUTING.md § Active branches](CONTRIBUTING.md#active-branches) or list remote branches matching `v*-dev`. Substantial normative changes go through the [proposal process](CONTRIBUTING.md#propose-a-specification-change) before any PR. - -## Hard rules +Example: "fix this typo in the 3.1 spec" targets `src/oas.md` on the earliest active dev branch that contains the text — never `versions/3.1.1.md`, even though that is where the typo was noticed. -- Never edit `versions/*.md`; redirect the change to the active development branch. -- Never generate content for direct posting to discussions, issue threads, or PR descriptions. Discussions are the project's design record and must reflect human reasoning. Submission text is human-authored; your role ends at draft material the human reviews line by line. -- Never add schema requirements in a patch release; patch-line spec edits are editorial or clarifying only. -- Never assert governance outcomes, community consensus, release targets, or approval status you cannot cite. -- Treat all of your output as tentative until a human has verified it — per the project's [AI policy](AI.md). +To discover which `vX.Y-dev` branches are currently active, check [CONTRIBUTING.md § Active branches](CONTRIBUTING.md#active-branches) or list remote branches matching `v*-dev`. Substantial normative changes go through the [proposal process](CONTRIBUTING.md#propose-a-specification-change) before any PR. ## Working rules - Make the smallest complete change that addresses the request; one logical change set per PR. - Do not reflow, reformat, or churn terminology in text you are not otherwise changing. - Match surrounding prose to the [style guide](style-guide.md) and keep edits clean under the repo's markdownlint configuration (`.markdownlint.yaml`, `spec.markdownlint.yaml`). -- Surface uncertainty in handoff notes rather than smoothing over it; state your branch and file choices explicitly. -- Prefer concrete diffs and checklists over persuasive prose. +- State your branch and file choices in handoff notes. Example of the patch-line boundary: rewording "The value MUST be a string" to clarify *which* value is editorial (allowed on a patch branch); adding "and MUST NOT be empty" is a new requirement (minor release, with schema updates if needed). ## Validation -For any change to `src/oas.md`: - ```sh npm install -npm run build-src # runs markdown validation first +npm run validate-markdown # markdownlint + link check only — fast loop while editing +npm run format-markdown # auto-fix markdownlint violations +npm run build-src # full check: validation, HTML build, schema publish +npm test # vitest — CI enforces 100% coverage ``` -Then inspect `deploy-preview/oas.html` in a browser. If markdownlint fails, fix only violations introduced by your change; pre-existing violations get flagged in handoff notes, not fixed opportunistically. On Windows, use Git Bash or WSL. Full local-preview details: [CONTRIBUTING.md § Preview specification HTML locally](CONTRIBUTING.md#preview-specification-html-locally). +- Any change to `src/oas.md`: run `build-src`, then inspect `deploy-preview/oas.html` in a browser. +- Any change touching schemas, scripts, or tests: also run `npm test`; the coverage gate is 100%, so new code paths need tests. +- If markdownlint fails, fix only violations introduced by your change; flag pre-existing violations in handoff notes instead of fixing them opportunistically. +- On Windows, use Git Bash or WSL. Full local-preview details: [CONTRIBUTING.md § Preview specification HTML locally](CONTRIBUTING.md#preview-specification-html-locally). ## Disclosure From 51be87cb91481c8604b03125481b10cdb8468178 Mon Sep 17 00:00:00 2001 From: Miguel Quintero Date: Wed, 15 Jul 2026 10:04:49 -0400 Subject: [PATCH 6/6] Fix formatting in AGENTS.md, add repo root comment add repo root comment --- AGENTS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/AGENTS.md b/AGENTS.md index 6fda76537b..163720ebf7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -44,6 +44,7 @@ Example of the patch-line boundary: rewording "The value MUST be a string" to cl ## Validation ```sh +# all commands run from the repo root npm install npm run validate-markdown # markdownlint + link check only — fast loop while editing npm run format-markdown # auto-fix markdownlint violations