From 3cd83b6b727092b3e49834975090a06a1cbdb637 Mon Sep 17 00:00:00 2001 From: os-zhuang Date: Fri, 12 Jun 2026 08:05:22 +0500 Subject: [PATCH] =?UTF-8?q?docs(adr-0040):=20=C2=A75=20build-scope=20rule?= =?UTF-8?q?=20=E2=80=94=20phased=20module=20decomposition=20+=20perception?= =?UTF-8?q?=20rule?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Records the scope-guard design shipped in cloud#242: soft design-time SCALE rule in propose_blueprint, hard apply-time cap (blueprint_too_large) with one per-context limit as the plan-entitlement read point, and the advice-vs-refusal perception rule for how limits surface to users. Co-Authored-By: Claude Fable 5 --- docs/adr/0040-unified-assistant-and-agent-binding.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/adr/0040-unified-assistant-and-agent-binding.md b/docs/adr/0040-unified-assistant-and-agent-binding.md index dd2782a113..1c4ef3fc8b 100644 --- a/docs/adr/0040-unified-assistant-and-agent-binding.md +++ b/docs/adr/0040-unified-assistant-and-agent-binding.md @@ -89,6 +89,17 @@ Today `chatWithTools` offers the **whole tool registry** to every agent; skills - Until then, a "read-only analyst" custom agent is a *persona*, not a *boundary* — documented as such wherever custom agents are exposed. - This incident is also why scoping matters beyond security: the Data Assistant failed precisely because it could reach tools whose disciplines it didn't carry. +### 5. Build-scope rule — oversized goals decompose into phased modules + +A "build me a whole ERP, hundreds of tables" goal must not become one mass-generated blueprint: it is unreviewable in the blueprint-confirm step (ADR-0033's safety valve), unbuildable inside the agent's per-turn runtime budget, and design coherence collapses at that scale. The platform's answer is **consultative decomposition**, in two layers sharing one limit: + +- **Soft (design-time)** — `propose_blueprint` carries a SCALE rule: a single blueprint never exceeds the per-build object cap (aim ≤10). Larger goals blueprint ONLY the core module (smallest object set with end-to-end value); the remaining modules are emitted as a phased roadmap in `assumptions`. Later phases are ordinary follow-up blueprints in the same environment, referencing earlier objects via lookups. +- **Hard (apply-time)** — `apply_blueprint` rejects an oversized blueprint **before staging anything** (`code: 'blueprint_too_large'`), returning the same decomposition guidance so the agent re-proposes instead of retrying. The cap defaults to 20 and is read from one per-context limit (`BlueprintToolContext.limits.maxBlueprintObjects`) — the designated read point for plan-tier entitlements (a free tier is the same code path with a smaller N and the upsell moment built into the roadmap). + +**Perception rule**: limits that can manifest as *advice* stay invisible — the agent frames phasing as professional delivery methodology, never as a system or plan limitation. Limits that can only manifest as *refusal* (quota exhausted) must be stated honestly at the moment of impact, with a recovery path. An invisible wall the user can hit reads as "the AI is broken," which is the most expensive failure mode. + +Verified by the L5 suite's `golden_erp_scope` case: an "entire ERP" prompt must yield a bounded core-module build plus a roadmap, never dozens of staged objects. + ## Non-goals - **Not** removing the multi-agent system — binding, API selection, eval, and channels all need it.