Provide AI agent guidance and disallow AI generated content

.github/pull_request_template.md

@@ -21,12 +21,8 @@ Thanks for submitting a pull request, please make sure:
 - [ ] content meets the [license](https://github.com/OWASP/DevGuide/blob/main/license.txt) for this project
 - [ ] you have read the [contribution guide](https://github.com/OWASP/DevGuide/blob/main/contributing.md)
   and agree to the [Code of Conduct](https://github.com/OWASP/DevGuide/blob/main/code_of_conduct.md)
-- [ ] *either* no AI-generated content has been used in this pull request
-- [ ] *or* any [use of AI](https://github.com/OWASP/DevGuide/blob/main/contributing.md#use-of-ai)
-  in this pull request has been disclosed below:
-  - AI Tools: `[e.g. GitHub CoPilot, ChatGPT, JetBrains Junie, etc]`
-  - LLMs and versions: `[e.g. GPT-4.1, Claude Haiku 4.5, Gemini 2.5 Pro, etc]`
-  - Prompts: `[Summarize the key prompts or instructions given to the AI tools]`
+- [ ] no agentic AI was used in creating this pull request
+- [ ] no generative AI was used in creating content under `/docs`
 
 **Other info** :  
 

.wordlist-en.txt

@@ -265,6 +265,7 @@ SDLCs
 SECCOMP
 SELinux
 SFL
+SHA
 SIEM
 SKF
 SL
@@ -489,6 +490,7 @@ lxml
 lychee
 mastg
 maswe
+md
 misconfiguration
 mlsec
 mitigations

AGENTS.md

@@ -0,0 +1,67 @@
+# AGENTS.md
+
+This is the repo-level operating contract for agents working in OWASP Developer Guide.
+***These rules are requirements, not suggestions.***
+
+## Project Goals
+
+The OWASP Developer Guide is a free, open-source OWASP threat modeling tool.
+It is a documentation project that provides software developers and development teams with insights into software security.
+
+## Operating Contracts
+
+### Agents
+
+This is the repo-level operating contract for non-human OWASP Developer Guide contributors.
+These rules are requirements, ***not suggestions***.
+
+### Contributing
+
+The [contributing.md](./contributing.md) file is the operating contract for our human contributors.
+Non-human contributors must read, understand, and respect these contracts.
+
+### Code of Conduct
+
+The [code_of_conduct.md](./code_of_conduct.md) applies to all contributors -
+regardless of whether the contributor is carbon-based, silicon-based, or legally ambiguous.
+
+## Explicit Boundaries
+
+1. Humans are responsible for all contributions, regardless of tooling.
+2. AI should explicitly refuse to take action clearly prohibited by this AGENTS file
+3. Humans write public product docs under `docs/`. Agents must not author docs pages
+4. Humans create issues, comment on issues, submit pull requests, approve releases, publish artifacts
+5. Humans decide roadmap or product policy
+6. Agents may point out docs gaps, but a human must write the final docs text.
+7. Agents may test docs with markdown linting, spellcheck, link checks, and local docs builds
+8. Agents may edit code, tests, configuration, workflows, and maintainer scripts when explicitly asked
+9. Agents must not open issues, comment on GitHub, open pull requests, approve pull requests
+10. Agents must not commit, merge, push, release, or publish
+11. Do not mix unrelated cleanup, dependency updates, formatting churn, or opportunistic refactors into task work
+
+## Supply Chain / Dependencies
+
+- ALL dependencies must have a minimum release age of 10 days
+- No updates to lock-files unless intentionally doing dependency work
+- GitHub Actions must be pinned to a full commit SHA with an inline version comment for Dependabot
+- GitHub Actions have the same 10 day minimum release age requirement
+- Prefer small helper scripts over new dependencies when reasonable
+
+### docs
+
+- Docs checks are for validation only: markdown lint, spellcheck, link check, and docs build where available
+
+### Root level checks
+
+- `npm run markdown:lint`
+- Spellcheck is not available as an npm command. You can run it if:
+  - the user has or approves installing pyspelling
+  - the `en` dictionary is installed
+  - `pyspelling -c .spellcheck.yaml`
+
+## Directory Specific Context
+
+### `docs/`
+
+- Agents do not write public documentation pages.
+- Agents may validate human-authored docs with markdown formatting, spellcheck, link checks, and local docs builds.

contributing.md

@@ -14,8 +14,20 @@ Contributors can [make suggestions][issues] and provide changes via a [pull requ
 
 Feel free to discuss topics in the [project wiki][wiki] and create new discussions.
 
+### Generative AI
+
 Note that you **must** follow the rules for any [use of AI](#use-of-ai).
 
+The use of AI is quick and seems to provide what is needed
+but ultimately it does not deliver true insight into what projects actually are,
+why a developer would want to use them and how they need to be used;
+it can only provide superficial answers
+
+This Developer Guide seeks to provide knowledge about the various OWASP projects.
+This requires human insight that provides a developer with reasons and knowledge that go beyond what can be gleaned by AI.
+Perhaps it is the difference between a Lonely Planet Guide and Google Maps;
+one has human insight and the other is truthful but mechanical
+
 ### Ground rules
 
 When contributing:
@@ -25,16 +37,19 @@ When contributing:
 * ensure that all contributions are within the [license](license.txt)
 * although the use of generative AI is not prohibited, it _must_ be declared in the pull request
 
-The Developer Guide is a documentation project and so there may be differences of opinion on wording or punctuation.
-If you submit a pull request please make it substantive, otherwise
+When you submit a pull request please make it substantive, otherwise
 it will be hard to get attention from the maintainers for trivial changes and it may end up being rejected.
 
+The Developer Guide is a documentation project and so there may be differences of opinion on wording or punctuation.
+
 #### Philosophy
 
 The Developer Guide does not seek to duplicate the information contained in the many OWASP documentation projects;
 these projects address their subject fully and completely.
+
 Instead the Developer Guide is a starting point on a wide range of subjects
 which a developer would need to know at least the basics.
+
 The Developer Guide should supply this basic knowledge only,
 and then refer the developer to further reading for more in-depth treatment of the subject.
 As a rule of thumb, if a section is more than two pages then it is probably too long;
@@ -83,12 +98,12 @@ Sub-sections that describe an individual project should follow the same structur
 3. The 'Why', explaining why developers will want to use the project:
   _provide more context for project that allows developers to determine whether to use it in their team_
 4. The 'How', describe how to get started with the project
-  _give a brief outline of how the project provides value for a web application development team_
+  _give a brief outline of how the project provides value for a web application development team_.
   _Do not repeat the project documentation itself; ideally provide a primer and a pointer to the project documentation_
 5. Further reading or resources, if any, providing links on the project at an advanced/detailed level
 
 Note that the page describing a project should not be the same as the project documentation on the OWASP site,
-the Developer Guide should strive to be a ' TL;DR ' for the project running to one or maybe two pages.
+the Developer Guide should strive to be a ' TL;DR ' for the project in one or maybe two pages.
 
 ### Translations
 
@@ -122,14 +137,12 @@ Note that you **must** follow the rules for any [use of AI](#use-of-ai) in the p
 ### Use of AI
 
 The Developer Guide is a documentation project and so the content must be accurate, informative and concise.
+Generative AI usually produces content that is superficial, generalized and verbose; **do not** use it to create content.
 
-Generative AI can produce content that is general and verbose;
-avoid using it for any issues, pull requests, comments and discussions.
-
-If it is genuinely helpful to use generative AI then it **must** be declared in any pull request or issue,
-failure to do so can result in the contribution being closed or even deleted.
+**Do not** use generative AI for any issues, pull requests, comments and discussions.
+Use of generative AI will result in the contribution being closed or even deleted.
 
-There is no need to use agentic AI to create issues or pull requests;
+**Do not** use agentic AI to create issues or pull requests;
 templates for all issues and pull requests **must** be used.
 Failure to use the templates can result in the issue / pull request being closed or even deleted.