AirCoding/AirPlan/docs/architecture/scope-escalation-v1.md

AirCoding Scope Escalation Model V1

Date: 2026-05-27 Status: Canonical scope escalation model for V1.0.0 Alpha skeleton

This document defines when agents may continue silently, when Scheduler must route to Architecture Designer, and when Main Agent/user confirmation is required.

1. Core Principle

Implementation-level changes that do not conflict with existing requirements, interfaces, architecture, or permissions may continue silently.

Architecture-level, product-level, safety-sensitive, or user-visible requirement changes require assessment and may require user confirmation depending on permission mode and impact.

2. Escalation Levels

type ScopeImpactLevel =
  | "implementation"
  | "interface"
  | "architecture"
  | "product"
  | "permission"
  | "environment"
  | "policy"

Level	Meaning	Default action
implementation	internal code details within accepted scope	silent continue
interface	public API/schema/module boundary changes	Architecture Designer assessment
architecture	component responsibility/data flow/runtime model changes	Architecture Designer + likely user-visible summary
product	changes user-facing goal, behavior, UX, or acceptance criteria	Main Agent/user confirmation
permission	action exceeds current permission grant	PermissionEngine/Main Agent
environment	dependency/toolchain/platform blocker	Doctor/Debugger, then Main Agent if unresolved
policy	safety/security/legal/project policy issue	block until explicit decision or refuse

3. Silent Continue Criteria

An agent may continue without escalation when all are true:

1. Change is inside TaskSpec scope/write area.
2. Acceptance criteria remain unchanged.
3. Public interfaces and architecture decisions remain unchanged.
4. No denied path, credential, system-sensitive, or unapproved network access is needed.
5. Verification plan remains valid.
6. Change does not contradict project rules or latest user instructions.
7. Risk is low or normal for the task type.

Examples:

rename local variable
adjust private helper implementation
fix compile error without API change
add missing test for accepted behavior
change internal algorithm with same contract

4. Architecture Designer Assessment Criteria

Route to Architecture Designer when any are true:

1. Public function/class/module interface must change.
2. DB schema or persisted data shape must change.
3. IPC/event/tool contract must change.
4. Dependency graph or component responsibility changes.
5. Task requires new subsystem/capability not in plan.
6. Multiple tasks conflict semantically, not just textually.
7. A user requirement change may affect architecture.
8. Repeated failures indicate the plan itself is wrong.

Architecture Designer outputs architecture.impact.completed:

interface ArchitectureImpactCompletedPayload {
  assessment_id: string
  requirement_change_id?: string
  impact_level: "implementation" | "interface" | "architecture" | "product"
  decision: "silent_continue" | "requires_user_confirmation" | "requires_replan" | "reject_or_escalate"
  summary: string
  affected_task_ids?: string[]
  evidence_refs?: EvidenceLink[]
}

5. User Confirmation Criteria

Main Agent asks the user when any are true:

1. Product behavior or acceptance criteria changes.
2. Architecture Designer marks requires_user_confirmation.
3. Low-permission mode requires approval for the planned action.
4. Credentials or system-sensitive operations are involved.
5. Migration or destructive/shared-state operation is involved.
6. Safety/policy boundary requires explicit authorization.
7. Failure cannot be resolved without user preference or external input.

High-permission mode may auto-execute many actions after visible announce_then_run, but cannot bypass:

credentials
system_sensitive
migration confirmation
policy refusal boundary
destructive/shared-state actions requiring explicit confirmation

6. Environment Escalation

Environment/toolchain issues follow:

worker detects issue
  → Doctor/Debugger evidence
  → if fix is allowlisted and permission mode allows: announce_then_run or ask
  → if fix fails or unsupported platform: Main Agent blocker report
  → if architecture assumptions invalid: Architecture Designer assessment

Examples requiring environment escalation:

missing compiler/toolchain
kernel feature unavailable
package manager unavailable
insufficient disk space
X/display backend missing for GUI evidence

7. Permission Escalation

PermissionEngine returns an action plus a grant scope:

action: allow | deny | ask_user | block | refuse | announce_then_run
grant_scope: none | once | session | project | global

Routes:

Action	Route
allow	execute according to grant_scope; create backup first when backup_required is true
announce_then_run	visible notice, auto-execute if not interrupted; grant is bounded by grant_scope
ask_user	Main Agent/UI prompt
deny	do not execute this request; caller may choose another safe path
block	task.blocked
refuse	policy_error and cancellation/blocker

8. Requirement Change Handling

When the user changes requirements during execution:

Main Agent records requirement.changed
Scheduler pauses affected dispatch/merge decisions
Architecture Designer assesses if needed
Scheduler cancels, interrupts, replans, or continues affected tasks
Main Agent reports visible impact summary

Classification:

Change	Handling
clarification only	update context; continue
implementation detail	Scheduler updates pending tasks; running tasks may continue if unaffected
scope change	interrupt affected tasks and replan
architecture change	Architecture Designer assessment
cancellation	cancel affected tasks and preserve workspaces/artifacts

9. Worker Self-Escalation Contract

Workers return blocked instead of improvising when they detect:

architecture/interface mismatch
permission denial
missing product decision
unsupported environment condition
unsafe requested behavior
verification cannot be run and acceptance depends on it
TaskSpec scope insufficient for necessary change

WorkerResult blocker fields:

interface BlockerReport {
  impact_level: ScopeImpactLevel
  reason: string
  required_decision: string
  options?: Array<{ label: string; tradeoff: string }>
  evidence_refs?: EvidenceLink[]
  suggested_default?: string
}

10. Scheduler Escalation Decision

Scheduler maps task/agent/tool events to one of:

continue
retry
retry_serial
debug
ask_permission
architecture_assessment
ask_user
cancel
refuse

Decision inputs:

error kind
failure signature repetition
TaskSpec scope
permission result
architecture impact
verification evidence
resource/environment state
user permission mode

11. User-Facing Reports

Escalation reports should be short and actionable:

What changed or failed
Why AirCoding cannot safely continue silently
Evidence summary
Recommended default action
Alternatives if meaningful

Do not show implementation noise when the decision is product-level. Do show precise evidence when the decision affects architecture, data loss, security, or environment setup.

12. Examples

Silent implementation fix

A C++ build fails because a private helper has a mismatched parameter type. Executor edits the helper and reruns build/tests. No escalation.

Interface-level escalation

A task discovers the accepted API cannot support required streaming. Executor returns blocked. Architecture Designer assesses interface change and updates plan/ADR before Scheduler continues.

Product-level escalation

User asked for local-only storage, but implementation requires cloud sync to meet a new requirement. Main Agent asks user; no silent change.

Environment escalation

Build requires a missing compiler. Doctor can install it. In high-permission mode this may be announced and run if allowlisted; credentials/system-sensitive steps still ask.

Policy escalation

Requested behavior would steal credentials or hide persistence. AirCoding refuses; no architecture workaround.

13. V1.0.0 Alpha Cut Line

V1.0.0 Alpha skeleton must implement:

1. ScopeImpactLevel contract.
2. Silent continue checks for workers.
3. Worker blocked report schema.
4. Architecture impact event route.
5. PermissionEngine route integration.
6. Scheduler escalation decision table.
7. Main Agent blocker/confirmation presentation.

Post-MVP:

learned escalation classifier
risk scoring by code ownership/history
interactive impact visualization
automated ADR draft generation from repeated escalations