From 08a1e72a7f6e0552a731e886deedec88fd2dd7bb Mon Sep 17 00:00:00 2001 From: ework-agent Date: Sun, 27 Sep 2026 12:10:48 +0800 Subject: [PATCH] =?UTF-8?q?docs(agents):=20configuration=20surface=20disci?= =?UTF-8?q?pline=20=E2=80=94=20owner-gated=20additions,=20explicit=20repor?= =?UTF-8?q?ting,=20no=20self-initiated=20config=20shapes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 993a0b4bbe..fa64628e55 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -238,6 +238,16 @@ Rules: - The fixture MUST bring its own registry instance — never point it at an external (even internal) registry service. +### Configuration Surface Discipline (owner-gated) + +The config surface — every field of `~/.config/billion-context/config.json`, every `BILI_*` env var, every CLI flag, mirrored across CONFIGURATION.md en/zh — is **owner-design territory**. Hard rules: + +1. **Any change that adds, renames, or re-semantics a config field MUST report it explicitly** in the PR description under a "config surface" heading: what is added/changed, why the existing surface cannot express it, which existing mechanisms were considered (providers table and its key species, the three-level `compress` hierarchy, env-var conventions, launcher↔extension channels), and the compat/migration story. A PR touching config without this section is incomplete by definition. +2. **Agents do NOT invent new config shapes on their own initiative.** A new section/field proposed merely because it is locally convenient — without mapping it onto the existing system — is rejected on principle: **don't even build it**. File the proposal (issue, with the mapping above) and wait. +3. **The only exception is explicit owner sign-off in the issue/PR thread, given BEFORE implementation**, recorded alongside the design rationale. "The agent thought it was a good idea" is never sufficient reason. + +Canonical cautionary case (#1437 → #1469): a one-off `plugin.nonHttpProviders` section was drafted alongside the existing `providers` table instead of inside it, collided with the table's design, and had to be reworked into `providers[].compactionOptIn`. The first shape should never have existed. + ### Code Quality - **No `as any`**, **No `@ts-ignore`**