docs(agent): make repository workflow rules adaptive (#6281)

AGENTS.md

@@ -6,7 +6,7 @@ This file is the primary instruction set for all AI agents and LLMs working in t
 
 ## Task-to-Documentation Mapping
 
-Before executing any task, identify the domain and load the corresponding document.
+For work that changes or reviews repository behavior, identify the domains actually touched and load only the applicable documents. Simple factual checks and unrelated domains do not require preloading rule files.
 
 ### Architectural Decisions
 * **Primary Reference:** `docs/rules/05-architecture.md`
@@ -26,8 +26,7 @@ Before executing any task, identify the domain and load the corresponding docume
 
 ### Comments and Documentation
 * **Primary Reference:** `docs/rules/08-comment-styles.md`
-* **Required Constraints:** All public classes and methods require Chinese docstrings. Comments must explain the *why*, not restate the code.
-* **⚠️ MANDATORY GATE:** Code that is missing proper Chinese docstrings on public interfaces is **REJECTED** at review. No exceptions.
+* **Required Constraints:** Public or cross-module contracts and non-obvious business behavior require concise Chinese docstrings. Small self-evident private helpers and test scaffolding may omit them. Comments must explain the *why*, not restate the code.
 
 ### External Communication and Interfaces
 * **Primary Reference:** `docs/rules/09-external-response.md`
@@ -43,11 +42,11 @@ Before executing any task, identify the domain and load the corresponding docume
 
 ### Testing
 * **Primary Reference:** `docs/testing.md`
-* **Required Constraints:** pytest is the only runner; `tests/conftest.py` isolates each run to a temporary `CONFIG_DIR`. Tests must not touch the real database, network, or external services (TMDB, LLM catalogs, downloaders, media servers, MP server) — mock at the boundary or replay recorded responses; the bar is zero real outbound traffic. Tests must restore any process-level state they stub (`sys.modules`, singletons, caches, settings). New tests must be pytest-native (function + `assert` + fixtures); do not add new `unittest.TestCase`. Convert existing `TestCase` files to pytest-native opportunistically when you modify them. Before opening a PR to `v2`, run the full suite locally (`python tests/run.py`) and confirm it is green with zero real network calls; the `.github/workflows/test.yml` gate runs the same suite on every PR/push to `v2`.
+* **Required Constraints:** pytest is the only runner; `tests/conftest.py` isolates each run to a temporary `CONFIG_DIR`. Tests must not touch the real database, network, or external services (TMDB, LLM catalogs, downloaders, media servers, MP server) — mock at the boundary or replay recorded responses; the bar is zero real outbound traffic. Tests must restore any process-level state they stub (`sys.modules`, singletons, caches, settings). New tests must be pytest-native (function + `assert` + fixtures); do not add new `unittest.TestCase`. Convert existing `TestCase` files to pytest-native opportunistically when you modify them. Before opening a PR to `v3` that changes product code, test infrastructure, dependencies, or runtime behavior, run the full suite locally (`python tests/run.py`) with zero real network calls. The changed path must pass; any unrelated failure must be reported and reproduced against the current `upstream/v3` baseline instead of silently expanding the PR. Documentation-only changes use applicable text and structure checks; the `.github/workflows/test.yml` gate still runs the full suite on every PR/push to `v3`.
 
 ### Commands and Development Workflow
 * **Primary Reference:** `docs/rules/03-commands.md`
-* **Required Constraints:** Only suggest or execute commands documented in that file. Do not assume tool defaults or global flags.
+* **Required Constraints:** Use that file as the project command reference. Other standard inspection, Git, GitHub, and focused verification commands are allowed when they are necessary, scoped, and consistent with current authorization.
 
 ---
 
@@ -55,31 +54,22 @@ Before executing any task, identify the domain and load the corresponding docume
 
 ### Pre-Flight Check
 
-Before generating any code or proposing changes, you must:
+Before generating code or proposing changes, identify the domains the task actually touches and load only the corresponding documents from `docs/rules/`. Apply those constraints while designing, implementing, and reviewing the change; do not produce a formal checklist for unrelated domains.
 
-1. Identify the task domain (architecture / business logic / coding style / naming / comments / external interfaces / data / quality).
-2. Load the corresponding document from `docs/rules/`.
-3. Explicitly verify that your proposed solution does not violate the following three mandatory constraints:
-   - **Naming Conventions (07):** Are all files, classes, functions, and constants named correctly?
-   - **Architecture Boundaries (05):** Is the code placed in the correct layer? Are all call directions valid?
-   - **Comment Standards (08):** Do all new public classes and methods include Chinese docstrings?
+Architecture, persistence, security, external protocols, cross-module lifecycle, and public-contract changes require an explicit boundary check before implementation. Local documentation, mechanical maintenance, and narrowly scoped changes use only the rules that materially affect their correctness and reviewability.
 
 ### Implementation Guidelines
 
 * **Pattern Adherence:** Avoid generic boilerplate. If `04-design-patterns.md` defines a project-level pattern for a scenario, you are required to use it.
 * **Documentation Standards:** Docstring style for any new function or module must match `08-comment-styles.md`.
-* **⚠️ MANDATORY GATE:** Public classes, methods, and functions without proper Chinese docstrings are **REJECTED**. No exceptions.
-* **Command Reliance:** Only suggest commands listed in `03-commands.md`. Do not rely on inferred tool defaults.
+* **Documentation Gate:** Public or cross-module contracts and non-obvious business behavior without useful Chinese documentation are rejected. Do not require comments that merely restate self-evident syntax.
+* **Command Reliance:** Prefer commands documented in `03-commands.md`; use other necessary standard commands with explicit, scoped arguments.
 * **Minimal Change Principle:** Prefer the smallest correct change. Do not perform unrelated refactors, mass renames, or formatting-only cleanup.
 * **Output Language:** Summaries, validation results, and risk notes default to Chinese unless the user requests otherwise.
 
 ### Conflict Resolution
 
-If existing code appears to contradict the documentation:
-
-1. Stop implementation immediately.
-2. Identify the specific file and line of the contradiction.
-3. Prompt the user: "The documentation in `[File]` requires Pattern A, but the current implementation uses Pattern B. Which is the current standard?"
+If existing code appears to contradict the documentation, identify the exact contradiction and decide which current-task gate it affects. Stop and ask only when it blocks acceptance, creates a security or data-safety ambiguity, or cannot be resolved from current source and maintained documentation. Otherwise preserve the evidence, continue unaffected work, and report the discrepancy without silently expanding scope.
 
 ---
 

docs/rules/03-commands.md

@@ -1,6 +1,6 @@
 # 03 — Commands
 
-Only suggest or execute commands that appear in this document. Do not assume standard tool defaults, global flags, or operating-system-specific behavior unless explicitly listed here.
+This document is the project command reference, not an exhaustive shell allowlist. Prefer these commands and their documented variants. Standard inspection, Git, GitHub, and focused verification commands may also be used when necessary, scoped to the current task, and allowed by the active workflow and maintainer authorization. Do not assume destructive or environment-specific flags.
 
 ---
 

docs/rules/08-comment-styles.md

@@ -1,16 +1,16 @@
 # 08 — Comments and Documentation Style
 
-## ⚠️ Mandatory Gate
+## Documentation Gate
 
-All **public classes**, **public methods**, and **public functions** in this project must have Chinese docstrings. Code submitted without compliant docstrings on public interfaces will be **rejected at review**. No exceptions.
+Public and cross-module contracts, structured business models, lifecycle behavior, compatibility paths, and non-obvious side effects require useful Chinese documentation. Small self-evident private helpers, temporary test scaffolding, and local structures whose contract is already clear may omit formal docstrings.
 
-"Public" means anything not prefixed with `_`. This includes all methods on `ChainBase` subclasses, `_ModuleBase` subclasses, Pydantic schema classes, and endpoint functions.
+Names without a leading `_` are review candidates, not an automatic documentation requirement. Apply the gate to the behavior and contract actually exposed. Methods on `ChainBase` subclasses, `_ModuleBase` subclasses, Pydantic schema classes, and endpoint functions normally cross a meaningful boundary and should be documented unless the surrounding contract already makes their role self-evident.
 
 ---
 
 ## Docstring Format
 
-Short, label-style docstrings should follow the surrounding code style and must not gain a period mechanically. Complete sentences that explain non-obvious behavior should use normal Chinese punctuation.
+Short, label-style docstrings, field descriptions, and single-line comments should follow the surrounding code style and must not gain a period mechanically. Complete sentences that explain non-obvious behavior should use normal Chinese punctuation.
 
 ### Single-line (for simple, obvious descriptions)
 
@@ -137,6 +137,6 @@ When modifying code, update or remove any comment that no longer accurately desc
 | `# FIXME` left in submitted code | Fix it now or document exactly why it cannot be fixed |
 | `# this is important` | Every line of code is important; this adds nothing |
 | Commented-out dead code | Delete it; git history preserves it |
-| Docstrings in English on new public interfaces | Violation of the mandatory Chinese docstring gate |
+| New contract documentation in English inside an otherwise Chinese file | Breaks the repository's default documentation language and local consistency |
 
-*Last Updated: 2026-05-25*
+*Last Updated: 2026-08-13*

docs/rules/11-quality-and-security.md

@@ -136,6 +136,6 @@ Before marking any task as complete:
 - [ ] If MCP/API behavior changed: `docs/mcp-api.md` and related skill files are updated
 - [ ] If database schema changed: a new Alembic migration exists under `database/versions/`
 - [ ] No secrets are included in code, logs, or committed files
-- [ ] Public classes and methods have Chinese docstrings
+- [ ] Public or cross-module contracts and non-obvious business behavior have useful Chinese documentation
 
-*Last Updated: 2026-05-25*
+*Last Updated: 2026-08-13*

docs/rules/12-collaboration-and-distribution.md

@@ -41,7 +41,7 @@ ci: improve docker build cache
 
 ### Rules
 
-- **Only create a commit when the user explicitly asks for one.**
+- Local commits follow the active workflow, an approved plan, or current user authorization. Existing authorization does not require a second confirmation; push, PR, merge, and release remain separate delivery boundaries.
 - Keep the subject line under 72 characters.
 - Use the imperative mood in the subject line ("add", "fix", "remove", not "added", "fixed", "removed").
 - If a commit introduces a breaking change, append `!` after the type and include `BREAKING CHANGE:` in the footer.
@@ -50,9 +50,10 @@ ci: improve docker build cache
 
 ## Branch Policy
 
-- Do not casually create, rename, or delete branches without user instruction.
+- When review or PR intent is already known, create or switch to a focused topic branch before editing. If that intent appears later, preserve valid work while moving it to a suitable branch.
 - The main development branch is the project default — check `git branch` rather than assuming it is `main` or `master`.
 - Feature work lives on dedicated branches and is merged via pull request.
+- Read-only investigation, throwaway diagnosis, and work explicitly kept local do not require a branch solely for process formality.
 - Do not force-push to shared branches.
 
 ---

docs/testing.md

@@ -139,5 +139,5 @@ def test_recognize_prefers_explicit_identity(sample_meta, monkeypatch):
 ## CI 与 PR
 
 - **门禁**：`.github/workflows/test.yml` 在指向 `v3` 的 `pull_request` / `push` 及手动触发时，用 `python tests/run.py` 跑全量单测。
-- **PR**：`python tests/run.py` 确认全绿、且 socket 探针零真实出站，避免把红的改动推上去空耗门禁。
+- **PR**：产品代码、测试基础设施、依赖或运行行为发生变化时，运行 `python tests/run.py`，确认本次改动涉及的路径通过且 socket 探针零真实出站。若存在无关失败，必须在当前 `upstream/v3` 基线上独立复现并在 PR 中如实说明；不得静默扩大当前 PR 去修复基线问题。纯文档变更按实际内容执行文本、结构和 diff 检查，CI 仍会运行全量门禁。
 - 复现 CI 用仅安装 `requirements-dev.in` 的干净环境；`requirements.in` 只承载运行时依赖，pytest 与覆盖率插件由开发依赖入口提供。