docs: require agent, model, and settings in AI disclosure (#4512)

* docs: require agent, model, and settings in AI disclosure

Make AI-assistance disclosure a hard requirement: when AI was used, the
author must name the agent/tool, the model(s), the settings/mode
(reasoning effort; autonomous vs. human-supervised), and the extent.

This is stricter than the prior "model optional" stance and is a
deliberate maintainer policy choice. It is framed as transparency, not a
quality lever: disclosure does not change the level of scrutiny a
contribution receives — the same evidence bar applies to everyone. It
gives maintainers visibility into which models/settings are used and to
what extent, which helps judge whether AGENTS.md guidance needs
refinement over time.

- CONTRIBUTING.md: upgrade the requirement, extend the PR
  responses/comments clause, refresh the example disclosures, and add the
  transparency rationale. Keep the trivial-fix exception.
- PULL_REQUEST_TEMPLATE.md: add structured Agent/tool, Model(s),
  Settings/mode, and Extent fields prefilled with N/A.
- bug_report, feature_request, agent_request issue forms: add a required
  AI Disclosure field defaulted to N/A.

Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* docs: align disclosure clauses across CONTRIBUTING and AGENTS

Address review feedback on the AI-disclosure policy for consistency:

- CONTRIBUTING.md: require the extent dimension in the AI-generated PR
  responses/comments clause too, so all four disclosure dimensions are
  listed consistently.
- CONTRIBUTING.md: explicitly exempt the catalog-submission issue forms
  (extension/preset/bundle), which feed content-neutral validation
  automation and carry no disclosure field, so the "any issue" wording is
  no longer contradicted.
- CONTRIBUTING.md: make the detailed example show the supervision mode.
- AGENTS.md: drop "if applicable" from the PR-comment model disclosure so
  it matches the new hard requirement to name the model.

Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* docs: name concrete model in AGENTS.md disclosure examples

Align AGENTS.md agent-disclosure guidance with the new hard requirement
to name the model (this PR's CONTRIBUTING.md change):

- Fix the awkward "name the agent and model and the human" phrasing in the
  PR-comment bullet to "name the agent, its model, and the human you are
  acting for".
- Replace the "<name-if-known>" placeholders in both the Assisted-by commit
  trailer example and the PR-comment example with a concrete model, so the
  examples no longer undercut the hard requirement.
- Keep a single, explicitly scoped exception (model: unknown) for the rare
  case where an agent genuinely cannot determine its own model.

Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* docs: name settings/mode and extent in AGENTS.md comment disclosure

CONTRIBUTING.md now requires every AI-generated PR response/comment to
name the agent, model(s), settings/mode, and extent. Align the AGENTS.md
"Comments" guidance and its example, which previously named only the
agent, model, and human — so an agent following AGENTS.md would still fall
short of the public policy. The example now shows the mode and the extent
of AI involvement, and links back to CONTRIBUTING.md.

Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* docs: exempt Spec Kit's own bundled agentic workflows from disclosure

The hard AI-disclosure requirement targets human-authored contributions.
The repository's own automated prompts under .github/workflows/ (bug-fix and
community-catalog PR/commit generators) run as a fixed, known agent and open
draft PRs for maintainer review, so their agent identity is inherent to the
workflow rather than self-declared per contribution. State this exemption
explicitly alongside the existing catalog-submission exemption so the policy
and the repo's own automation don't contradict each other.

Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: mnriem

.github/ISSUE_TEMPLATE/agent_request.yml

@@ -139,3 +139,16 @@ body:
       label: Additional Context
       description: Any other relevant information about this agent
       placeholder: Screenshots, community links, comparison to existing agents, etc.
+
+  - type: textarea
+    id: ai-disclosure
+    attributes:
+      label: AI Disclosure
+      description: >-
+        Per our [Contributing guidelines](https://github.com/github/spec-kit/blob/main/CONTRIBUTING.md#ai-contributions-in-spec-kit),
+        any AI assistance used to create this issue must be disclosed. If you used AI, name the agent/tool, model(s),
+        settings/mode (reasoning effort; autonomous vs. human-supervised), and extent. Otherwise leave this as "N/A".
+        This does not change how your issue is handled — it just gives maintainers visibility into model/agent usage.
+      value: "N/A"
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -138,3 +138,16 @@ body:
       label: Additional Context
       description: Add any other context about the problem
       placeholder: Screenshots, related issues, workarounds attempted, etc.
+
+  - type: textarea
+    id: ai-disclosure
+    attributes:
+      label: AI Disclosure
+      description: >-
+        Per our [Contributing guidelines](https://github.com/github/spec-kit/blob/main/CONTRIBUTING.md#ai-contributions-in-spec-kit),
+        any AI assistance used to create this issue must be disclosed. If you used AI, name the agent/tool, model(s),
+        settings/mode (reasoning effort; autonomous vs. human-supervised), and extent. Otherwise leave this as "N/A".
+        This does not change how your issue is handled — it just gives maintainers visibility into model/agent usage.
+      value: "N/A"
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -124,3 +124,16 @@ body:
       label: Additional Context
       description: Add any other context, screenshots, or examples
       placeholder: Links to similar features, mockups, related discussions, etc.
+
+  - type: textarea
+    id: ai-disclosure
+    attributes:
+      label: AI Disclosure
+      description: >-
+        Per our [Contributing guidelines](https://github.com/github/spec-kit/blob/main/CONTRIBUTING.md#ai-contributions-in-spec-kit),
+        any AI assistance used to create this issue must be disclosed. If you used AI, name the agent/tool, model(s),
+        settings/mode (reasoning effort; autonomous vs. human-supervised), and extent. Otherwise leave this as "N/A".
+        This does not change how your issue is handled — it just gives maintainers visibility into model/agent usage.
+      value: "N/A"
+    validations:
+      required: true

.github/PULL_REQUEST_TEMPLATE.md

@@ -16,6 +16,8 @@
 <!-- See: https://github.com/github/spec-kit/blob/main/CONTRIBUTING.md#ai-contributions-in-spec-kit -->
 
 - [ ] I **did not** use AI assistance for this contribution
-- [ ] I **did** use AI assistance (describe below)
+- [ ] I **did** use AI assistance (fill in the disclosure below)
 
-<!-- If you used AI, briefly describe how (e.g., "Code generated by Copilot", "Consulted ChatGPT for approach"): -->
+<!-- If you used AI assistance, replace "N/A" below with a free-form disclosure that names the agent/tool, model(s), settings/mode (reasoning effort; autonomous vs. human-supervised), and extent (docs vs. code generation). This does not change how much scrutiny your PR receives — the same evidence bar applies to everyone. It just gives maintainers visibility into model/agent usage. -->
+
+**AI disclosure:** N/A

AGENTS.md

@@ -514,16 +514,17 @@ Disclosure is **continuous**, not a one-time event. A single AI-disclosure parag
 - **Every commit you author must carry an `Assisted-by:` trailer** identifying the agent and whether it acted autonomously or under direct human supervision, for example:
 
   ```
-  Assisted-by: GitHub Copilot (model: <name-if-known>, autonomous)
+  Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous)
   ```
 
+  Name the actual model you are running as — the same hard requirement contributors are held to in [CONTRIBUTING.md](./CONTRIBUTING.md#ai-contributions-in-spec-kit). Only in the rare case where an agent genuinely cannot determine its own model may it write `model: unknown` instead.
   Use `supervised` instead of `autonomous` only when a human actually authored or line-by-line reviewed the change before it was committed.
 - **Never push solo-authored commits that hide agent authorship behind the operator's git identity.** If an agent generated the change, the trailer must say so even when the commit is attributed to a human account.
 - Preserve any tool-generated `Co-authored-by:` trailers (e.g. Copilot Autofix) — do not strip them to make a commit look hand-written.
 
 ### Comments
 
-- If you are an agent working on behalf of a human, **disclose your identity in your PR comment** — name the agent (and model, if applicable) and the human you are acting for (e.g., "Posted on behalf of @user by GitHub Copilot (model: &lt;name-if-known&gt;)").
+- If you are an agent working on behalf of a human, **disclose your identity in your PR comment** — name the agent, its model, the settings/mode (e.g. autonomous vs. human-supervised), the extent of AI involvement in the comment, and the human you are acting for (e.g., "Posted on behalf of @user by GitHub Copilot (model: Claude Opus 4.8, autonomous); comment fully AI-drafted."). This matches the disclosure the public [CONTRIBUTING.md](./CONTRIBUTING.md#ai-contributions-in-spec-kit) policy requires for AI-generated PR responses and comments.
 - **Re-state agent identity in each review-round summary comment.** A prior PR-body disclosure does not cover later comments or commits.
 - Post **one** top-level summary comment per review round listing what changed and the commit SHA. Do not reply on every individual comment.
 - Reply inline only when context is needed (disagreement, deferral, non-obvious fix). Keep it to a sentence or two.

CONTRIBUTING.md

@@ -336,23 +336,31 @@ Number each test sequentially (T1, T2, ...). List prerequisite tests first.
 We welcome and encourage the use of AI tools to help improve Spec Kit! Many valuable contributions have been enhanced with AI assistance for code generation, issue detection, and feature definition.
 
 That being said, if you are using any kind of AI assistance (e.g., agents, ChatGPT) while contributing to Spec Kit,
-**this must be disclosed in the pull request or issue**, along with the extent to which AI assistance was used (e.g., documentation comments vs. code generation).
+**this must be disclosed in the pull request or issue**. When AI assistance was used, the disclosure must name:
 
-If your PR responses or comments are being generated by an AI, disclose that as well.
+- **The agent/tool** — e.g., GitHub Copilot, Claude Code, ChatGPT.
+- **The model(s)** — e.g., Claude Opus 4.x, GPT-5.
+- **The settings/mode** — e.g., reasoning effort, and whether it ran autonomously or under human supervision.
+- **The extent** — e.g., documentation comments vs. code generation.
 
-As an exception, trivial spacing or typo fixes don't need to be disclosed, so long as the changes are limited to small parts of the code or short phrases.
+If your PR responses or comments are being generated by an AI, disclose that as well, naming the same agent, model(s), settings/mode, and extent.
+
+As an exception, trivial spacing or typo fixes don't need to be disclosed, so long as the changes are limited to small parts of the code or short phrases. The catalog-submission issue forms (extension, preset, and bundle submissions) feed content-neutral validation automation rather than code review, so they carry no disclosure field and are exempt from this requirement. Spec Kit's own bundled agentic workflows (the automated bug-fix and community-catalog prompts under `.github/workflows/`) are likewise exempt: they run as a fixed, known agent and open draft PRs for maintainer review, so their agent identity is inherent to the workflow rather than self-declared per contribution.
 
 An example disclosure:
 
-> This PR was written primarily by GitHub Copilot.
+> Implemented with GitHub Copilot using Claude Opus 4.x in agent/autonomous mode; code generation.
 
 Or a more detailed disclosure:
 
-> I consulted ChatGPT to understand the codebase but the solution
+> I consulted ChatGPT (GPT-5, default settings, human-supervised) to understand the codebase, but the solution
 > was fully authored manually by myself.
 
-Failure to disclose this is first and foremost rude to the human operators on the other end of the pull request, but it also makes it difficult to
-determine how much scrutiny to apply to the contribution.
+Failure to disclose this is first and foremost rude to the human operators on the other end of the pull request.
+
+To be clear, this disclosure does not change the level of scrutiny a contribution receives — the same evidence bar applies to
+everyone, human and AI-assisted alike. It simply gives maintainers visibility into which models and settings are being used and to
+what extent, which in turn helps us judge whether our [`AGENTS.md`](./AGENTS.md) guidance needs refinement over time.
 
 In a perfect world, AI assistance would produce equal or higher quality work than any human. That isn't the world we live in today, and in most cases
 where human supervision or expertise is not in the loop, it's generating code that cannot be reasonably maintained or evolved.
@@ -361,7 +369,7 @@ where human supervision or expertise is not in the loop, it's generating code th
 
 When submitting AI-assisted contributions, please ensure they include:
 
-- **Clear disclosure of AI use** - You are transparent about AI use and degree to which you're using it for the contribution
+- **Clear disclosure of AI use** - You are transparent about AI use, naming the agent/tool, model(s), settings/mode, and the degree to which you're using it for the contribution
 - **Human understanding and testing** - You've personally tested the changes and understand what they do
 - **Clear rationale** - You can explain why the change is needed and how it fits within Spec Kit's goals
 - **Concrete evidence** - Include test cases, scenarios, or examples that demonstrate the improvement