From 976edd68e7ab2d47439529bbbd3f6064fadb29e0 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Thu, 19 Nov 2026 20:56:20 -0500 Subject: [PATCH] docs(agents): state limit, test, verifier and feature-record conventions and list PR title types (#12652) * docs(agents): state limit, test, verifier and feature-record conventions Record ceiling, runtime-setting, assertion, verifier, and feature-record rules for agents, and make the pull request title pattern explicit. * docs(agents): defer limit controls to their owning guide --------- Co-authored-by: Cursor Agent --- .github/pull_request_template.md | 12 ++--------- AGENTS.md | 34 +++++++++++++++----------------- CONTRIBUTING.md | 13 ++++++++++++ 3 files changed, 31 insertions(+), 28 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index e222ed4c38..a8f6e166bf 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,5 +1,5 @@ @@ -106,15 +106,7 @@ limits, security/privacy/containment implications, and meaningful proof gaps. -- ## Author readiness - + Human owner: diff --git a/AGENTS.md b/AGENTS.md index 6c7e63cd37..0ebefd17db 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -96,6 +96,12 @@ Coordinate expensive checks across agents. If a test unexpectedly consumes heavy For tool design, follow [docs/development/tool-design.md](docs/development/tool-design.md): start from the analyst question, reuse existing contracts, preserve caller choices, and return useful evidence inline. Limits must follow real format, protocol, authority, or resource constraints. Account for representation expansion before allocation; derive completeness from examined coverage. +Choose the scope of a new limit from [analysis settings, limits, and recovery](docs/design/limits-and-recovery.md). +A registered runtime setting may have an optional launch seed. Per-call and +launch-only controls have their own contracts. Report the effective limit and +recovery for the control that stopped the work, and document the setting ID +and `update_analysis_settings` for changes that apply at runtime. + For user- or agent-facing tool problems, prioritize fixing the owning behavior, contract, and actionable result or recovery at the point of use. Document the result in product docs when explanation is needed. Add skill guidance only for @@ -104,7 +110,15 @@ a skill as the primary repair for a discoverability or contract defect. For test changes or provider claims, use [docs/development/testing.md](docs/development/testing.md). Select applicable [boundary regressions](docs/development/testing.md#boundary-regressions) for parser, inventory, snapshot, and projection fixes. Prefer real public CLI/MCP workflows, then production-boundary integration, then producer goldens. Keep module tests for distinct semantics stronger workflows cannot reliably reproduce. Preserve malformed-input, cancellation, cleanup, permission, capacity, and target-identity coverage when pruning. Report unverified coverage explicitly; simulated providers do not establish real-provider behavior. -Use Conventional Commit subjects and PR titles. Mark breaking changes with `!` or a `BREAKING CHANGE:` footer. Describe behavior changes, relevant validation, and real-provider verification scope. +Use structured facts to test behavior and assert wording when wording is part +of the contract. Follow [test design and pruning](docs/development/testing.md#test-design-and-pruning) +and use the [supervised command owner](docs/development/testing.md#verifier-scripts) +for commands launched by a verifier. + +Follow the [feature lifecycle](docs/development/documentation.md#feature-lifecycle) +to decide when a new capability needs a feature record. + +Use Conventional Commit subjects and PR titles as specified under [pull request ownership and readiness](CONTRIBUTING.md#pull-request-ownership-and-readiness). Mark breaking changes with `!` or a `BREAKING CHANGE:` footer. Describe behavior changes, relevant validation, and real-provider verification scope. ## Issue Reports @@ -120,23 +134,7 @@ required to open an issue. ## Pull Request Readiness Follow [human ownership and readiness](CONTRIBUTING.md#pull-request-ownership-and-readiness) -when preparing a PR. AI-assisted contributions are welcome; a human must review -and own the final diff, check the validation evidence and its limitations, and -explicitly declare the PR ready for initial maintainer review. - -Keep the PR body concise and current, with the concrete problem, observable -outcome, approach, and evidence. Report only checks that actually ran as executed; -distinguish source-derived conclusions, proposed checks, and unavailable coverage. -Address actionable automated review findings and explain disagreements. - -Leave the template's **Author readiness** declarations unchecked for the human -owner to complete. Never attest to human review on their behalf. Draft status -is optional; preserve the PR's current draft status unless the user asks to change -it. Later pushes do not invalidate the readiness declaration or require another -human sign-off. Keep the PR body and affected validation current as work changes. -Maintainers review the declaration and honor the author exemptions in -CONTRIBUTING.md. CI and automated review results do not establish that human -review occurred, maintainer scope approval, or merge permission. +when preparing a PR. Leave human readiness declarations to the human owner. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index db75cdbe7e..a3c9e66b46 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -113,6 +113,19 @@ Human ownership and review remain required when CI or an automated reviewer reports success. Readiness requests maintainer review; it does not grant scope approval or permission to merge. +Pull request titles must match the Conventional Commits check in +[`.github/workflows/pr-title.yml`](.github/workflows/pr-title.yml): + +```text +/^(?:feat|fix|docs|refactor|perf|test|build|ci|chore|revert)(?:\([a-z0-9._/-]+\))?!?: .+/u +``` + +The type is `feat`, `fix`, `docs`, `refactor`, `perf`, `test`, `build`, `ci`, +`chore`, or `revert`. An optional scope, in parentheses, uses only lowercase +`[a-z0-9._/-]`. An optional `!` may precede the colon. The title then has `: ` +and a non-empty outcome, for example `feat: add historical source import`. +The type `style` fails, and an uppercase scope fails. + Draft status is optional. Draft PRs may request early feedback with open questions and incomplete checks. Agents preserve the current draft status unless asked to change it; missing readiness declarations or later updates do not require a PR