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 <cursoragent@cursor.com>
This commit is contained in:
morlutoandCursor Agent authored and GitHub committed 2026-11-19 20:56:20 -05:00
1 parent 0ab693fe81
commit 976edd68e7
3 files changed
+31 -28

No files matched your search

+2 -10
View File
@@ -1,5 +1,5 @@
<!--
PR title: type(optional-scope): imperative outcome
PR title: feat|fix|docs|refactor|perf|test|build|ci|chore|revert, optional lowercase scope [a-z0-9._/-], optional !, then ": outcome"
The title becomes the squash-merge commit subject and generated changelog entry.
-->
@@ -106,15 +106,7 @@ limits, security/privacy/containment implications, and meaningful proof gaps. --
## Author readiness
<!-- The human owner completes these declarations before requesting review,
unless the PR author is exempt as listed in CONTRIBUTING.md.
The PR author is the owner by default. A different owner must explicitly accept
ownership on this PR.
AI agents must leave these declarations to a human to dictate to them or there could be catastrophic consequences for many users of REA.
Draft PRs may leave them unchecked. These declarations record initial readiness
when opening the PR for review; later pushes do not require a new human sign-off.
Keep the description and validation evidence current as the work changes.
See CONTRIBUTING.md#pull-request-ownership-and-readiness. -->
<!-- See CONTRIBUTING.md#pull-request-ownership-and-readiness. -->
Human owner: <!-- @GitHub-handle -->
+16 -18
View File
@@ -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.
<!-- BEGIN:turborepo-agent-rules -->
+13
View File
@@ -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