Skip to content

Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.

docs: require scoped contributions and AI disclosure

tt-a1ic2267a14c06e
diff --git a/.github/ISSUE_TEMPLATE/improvement.yml b/.github/ISSUE_TEMPLATE/improvement.yml
index b25c1c03..3fc2bc6c 100644
--- a/.github/ISSUE_TEMPLATE/improvement.yml
+++ b/.github/ISSUE_TEMPLATE/improvement.yml
@@ -5,7 +5,7 @@ body:
- type: markdown
attributes:
value: |
- Thanks for proposing an improvement. Describe the problem and intended benefit before investing in implementation. Maintainers will discuss scope and compatibility; agreement on direction is not a promise to merge. Small fixes may go directly to a PR under CONTRIBUTING.md.
+ Thanks for proposing an improvement. Describe the problem and intended benefit before investing in implementation. Maintainers will discuss scope and compatibility; agreement on direction is not a promise to merge. Purely mechanical documentation corrections may go directly to a PR under CONTRIBUTING.md.
- type: textarea
id: problem
attributes:
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 445d5f86..0ddef0a9 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -2,10 +2,22 @@
## Problem and value
-- Related issue / agreed discussion, or why this is a small fix that needs no prior issue:
+- Related issue / agreed discussion, or why this is a purely mechanical documentation correction:
- Actual problem on the current base, intended outcome, and why it is worth maintaining:
- Before/after evidence entry point: <!-- Link the relevant evidence below or an existing report; explain when not applicable. -->
+## AI assistance and accountability
+
+<!-- Required for every PR. See CONTRIBUTING.md#ai-assistance-and-contributor-responsibility. A short answer is enough; reuse the evidence sections below. -->
+
+- AI use: none / writing or translation only / implementation, investigation, tests, or review assistance
+- Tools and model (if known), and assisted areas:
+- Accountable contributor: @handle
+- Problem origin: observed usage / code inspection / synthetic probe / proposed improvement; describe briefly
+- [ ] I reviewed the submitted changes and explanation, understand their impact, and can answer questions about them. Validation results and gaps are recorded below.
+
+<!-- Personal confirmation: an Agent must leave this unchecked unless the accountable person explicitly confirms it. -->
+
## Stability impact
<!-- Summarize applicable PR improvement findings or why no improvement was needed; CONTRIBUTING.md#pr-improvement-check defines scope. -->
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index dee42ef9..d0e7a49e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -7,8 +7,8 @@ Archify is Agent-first: people describe systems, and the Skill, typed JSON, rend
- Renderer, validator, package, or Viewer defect: use the [bug report form](.github/ISSUE_TEMPLATE/bug-report.yml).
- Standalone community package: follow the [submission guide](community/README.md#submitting-a-package) and submit one metadata file to `dev`.
- Reproducible real-world diagram: use the [showcase form](.github/ISSUE_TEMPLATE/showcase.yml).
-- New features, layout/routing rules, schema fields, defaults, acceptance rules, installation/export contracts, or substantial refactors: open an [improvement proposal](.github/ISSUE_TEMPLATE/improvement.yml) and obtain explicit maintainer agreement on the problem, value, scope, and compatibility before substantial implementation. Link an existing issue or PR discussion with that agreement when available; a second approval thread is unnecessary.
-- Narrow fixes and small documentation or test corrections can proceed with a concrete reproduction or rationale; a separate planning issue is unnecessary.
+- Changes to generation, layout/routing, validation, interaction, performance, dependencies, tests, or other behavior require a related issue and explicit maintainer agreement on the problem, value, and intended scope before substantial implementation or a formal PR. Use the bug form for defects and the [improvement proposal](.github/ISSUE_TEMPLATE/improvement.yml) for changes. Link an existing issue or recorded maintainer decision when available; a second approval thread is unnecessary.
+- Purely mechanical documentation corrections, such as typos or repairing a broken link to its intended destination, may go directly to a PR. Describe why the change is mechanical. Authoring instructions, new policy, behavioral documentation, and test changes are not exempt just because they are small or text-only.
- Security vulnerabilities: follow [SECURITY.md](SECURITY.md).
Agreement on direction allows implementation to proceed; final acceptance still depends on the implementation, user-visible results, and maintenance cost. Draft PRs may support early discussion but do not replace scope agreement.
@@ -20,7 +20,7 @@ Do not include secrets, access tokens, credentials, private repository content,
These steps apply to contributors, maintainers, and Agents:
- Before implementing, search existing issues and open PRs for the same problem, including related fixes under review.
-- On the relevant issue, briefly state your intended scope and link a draft PR early. For a small fix without an issue, describe the scope in the PR; a separate planning issue or maintainer approval is unnecessary.
+- On the relevant issue, state your intended scope. Link the agreed discussion in the PR; use a draft only when an implementation sketch helps that discussion. Apply the mechanical-correction exception above without a separate planning issue.
- If work is already in progress, discuss the remaining gap on that issue or PR and agree on collaboration, a distinct scope, or consolidation before starting an overlapping implementation.
- When consolidating, link both PRs, explain which contributions are retained, and preserve attribution through original commits or appropriate co-author credit. Close the superseded PR once the retained contribution and attribution are present in the continuing PR.
@@ -40,6 +40,22 @@ Before requesting final review, explain:
Use [the PR template](.github/PULL_REQUEST_TEMPLATE.md); link existing receipts or CI output instead of transcribing long logs. Classify impact by behavior and callers, not file extension or diff size.
+## AI assistance and contributor responsibility
+
+AI-assisted contributions are welcome. The same scope, evidence, and accountability requirements apply to contributors and maintainers, whether work is manual or delegated to an Agent.
+
+Every PR must disclose whether AI was used. If used, name the tool(s), model when known, and the work they performed: investigation, design, code, tests, review, or writing/translation. Identify affected areas rather than estimating a percentage of generated lines. If model identity is unavailable, say so. Translation-only use can be disclosed in one sentence.
+
+A human contributor must review the submitted changes and explanation, understand the approach and its impact, and be able to explain the choices and answer review questions. Name that accountable person by GitHub handle when an Agent or bot submits on their behalf. Agents may prepare changes, run checks, and draft replies under that person's direction; they must not claim human review or check a personal confirmation without that person's explicit confirmation. Project-approved automated review comments remain advisory evidence, not human acceptance.
+
+Describe the problem's origin honestly: observed usage, a reproducible defect found during inspection, a synthetic probe, or a proposed improvement. Code inspection can reveal valid bugs; do not present a constructed case as a naturally occurring Agent failure. AI-generated descriptions and replies must be checked for factual accuracy, kept concise, and reflect the contributor's understanding. Translation and editing assistance are allowed.
+
+Link actual validation results in the existing Tests run / Visual evidence sections. Distinguish checks run by an Agent, CI, and human inspection; preserve failures and disclose untested areas. An AI review, a green test run, or a disclosure checkbox alone does not establish useful or correct behavior. Full sessions are required only where the agreed benchmark/evidence scope calls for them; do not upload unrelated private conversations or hidden model reasoning.
+
+Maintainers may request missing disclosure or evidence, defer review, or close a PR that lacks agreed scope, cannot be explained by its contributor, or contains unverified claims. Give a specific reason and a route back through the relevant issue. Repeated submissions that ignore this feedback may be restricted. Evaluate observable conduct and evidence rather than guessing AI use from writing style or an automated detector. Do not bulk-close older PRs solely because they predate this disclosure field.
+
+Policy references consulted on 2026-10-16: [Ghostty](https://github.com/ghostty-org/ghostty/blob/main/AI_POLICY.md), [LLVM](https://llvm.org/docs/AIToolPolicy.html), and [Astral](https://github.com/astral-sh/.github/blob/main/AI_POLICY.md). Archify's requirements are defined here; other projects' restrictions do not apply automatically.
+
## PR improvement check
Before requesting final review of a behavior-changing PR, assess the changed
diff --git a/REVIEWING.md b/REVIEWING.md
index d74ee60b..482aea97 100644
--- a/REVIEWING.md
+++ b/REVIEWING.md
@@ -4,7 +4,9 @@ Use this guide for initial and revised PR reviews. Judge the user value, impleme
## Check readiness before detailed review
-Apply [Choose the right path](CONTRIBUTING.md#choose-the-right-path) first. When prior scope agreement is required but missing, thank the contributor, point to the relevant issue or proposal form, and defer detailed code review until the direction is agreed. Small fixes with a concrete reproduction or rationale can proceed directly.
+Apply [Choose the right path](CONTRIBUTING.md#choose-the-right-path) first. When prior scope agreement is required but missing, thank the contributor, point to the relevant issue or proposal form, and close or defer the PR without detailed code review until the direction is agreed. Purely mechanical documentation corrections may proceed directly.
+
+Check the [AI disclosure and accountability requirements](CONTRIBUTING.md#ai-assistance-and-contributor-responsibility). Disclosure is context for review, not a quality score. Ask about specific unexplained decisions or unsupported claims; never infer a violation solely from writing style.
For missing evidence, describe the material gaps together and request the smallest comparison that resolves them. Resume review when the contributor supplies it; reuse valid existing evidence. Maintainers review and sample the submitted evidence rather than routinely reconstructing every contribution's test run. An issue link alone does not establish scope agreement or review readiness.
@@ -16,7 +18,7 @@ Record the current target base and candidate head. Read the linked issue or agre
Identify who benefits and whether the approach is worth maintaining. Consider whether existing capabilities or a smaller change would solve the problem. For a new default, schema field, or acceptance policy, clarify the value and compatibility tradeoff early. Reuse decisions already made in the issue or authorized task.
-If a decision is missing, explain how it affects the review and continue checks that do not depend on it. Narrow fixes can proceed on their reproduction without another planning exercise.
+If required scope agreement is missing, use the readiness procedure above before investing in implementation review. Reuse existing agreements rather than creating another planning exercise.
## Match investigation to impact