Risk Classification

Table of Contents

• Overview
• When to Use
• 4-Tier Risk Model
• Hybrid Routing
• Task Metadata Extension
• Module Reference
• Integration Pattern
• Exit Criteria

Risk Classification

Overview

Provides inline risk classification for agent tasks using a 4-tier model (GREEN/YELLOW/RED/CRITICAL). Uses fast heuristic file-pattern matching for low-risk tiers and delegates to Skill(attune:war-room-checkpoint) for high-risk tiers requiring full reversibility scoring.

When To Use

• Assessing risk of tasks before agent assignment
• Determining verification requirements for task completion
• Deciding parallel execution safety between tasks
• Adding risk markers to task checklists

When NOT To Use

• Single-file trivial changes (assume GREEN)
• Strategic architecture decisions (use full Skill(attune:war-room) instead)
• Non-code tasks (documentation-only, configuration comments)

4-Tier Risk Model

Hybrid Routing

Task received
    |
    v
Heuristic classifier (file patterns)
    |
    ├── GREEN/YELLOW → Apply tier, continue
    |
    └── RED/CRITICAL → Invoke Skill(attune:war-room-checkpoint)
                        for reversibility scoring (RS)
                        |
                        └── RS confirms or adjusts tier

Why hybrid: GREEN/YELLOW classification is fast and deterministic (file pattern matching). RED/CRITICAL tasks warrant the overhead of full reversibility analysis because the cost of getting them wrong is high.

Task Metadata Extension

Add risk tier to task metadata for downstream consumption:

{
  "id": "5",
  "subject": "Add user authentication",
  "metadata": {
    "risk_tier": "YELLOW",
    "risk_reason": "Modifies src/components/LoginForm.tsx (user-visible component)",
    "classified_at": "2026-02-07T22:00:00Z"
  }
}

Tasks without risk_tier metadata default to GREEN (backward compatible).

Readiness Levels

The 4-tier Readiness Levels system provides clear risk classification with required controls per tier:

See modules/readiness-levels.md for full level definitions, selection decision tree, and integration guidance.

Graduated Autonomy

Risk classification sets how carefully a change is verified. Automation tiers set how autonomously the agent acts and when it must hand control back. Each risk tier carries a default automation tier (GREEN to A3 autonomous, CRITICAL to A0 manual), and a pre-licensed downgrade trigger drops the agent one tier on repeated failure, confidence loss, a stakes spike, or repo-state mismatch rather than re-prompting at the same level. See modules/automation-tiers.md for the tier table and the downgrade trigger, and imbue:assisted-mastery for the explain/produce mode selection that reads from it.

Module Reference

• tier-definitions.md: Detailed tier criteria, boundaries, and override mechanism
• heuristic-classifier.md: File-pattern rules for automated classification
• verification-gates.md: Per-tier verification requirements and parallel safety matrix
• readiness-levels.md: 4-tier risk system with required controls per level
• automation-tiers.md: Per-tier autonomy defaults and the downgrade trigger

Integration Pattern

# In your skill's frontmatter
dependencies: [leyline:risk-classification]

For Task Generators

Append [R:TIER] marker to task format:

- [ ] T012 [P] [US1] [R:YELLOW] Create LoginForm component in src/components/LoginForm.tsx

For Orchestrators

Check risk tier before task assignment:

if task.risk_tier in ["RED", "CRITICAL"]:
    invoke Skill(attune:war-room-checkpoint) for RS scoring
    if CRITICAL: require human approval before proceeding

Exit Criteria

• Every task has a risk tier assigned (explicit or default GREEN)
• RED/CRITICAL tasks have war-room-checkpoint RS scores
• Verification gates passed for the assigned tier
• No parallel execution of prohibited tier combinations
• Each task carries an automation tier; downgrades are recorded

with a reason when a trigger fires

Automation Tiers

Risk classification answers "how carefully must this be verified." Automation tiers answer a second, distinct question: "how much should the agent do on its own, and when must it hand control back." A task can be correctly classified RED and still fail because the agent acted at full autonomy when it should have proposed and paused.

Why Graduated Autonomy

Aviation learned this the hard way. When automation does not do what is needed, the safe move is to downgrade the level of automation (autopilot to flight director to hand-flying) rather than re-issue the same command at the same level. Crews who could not or would not downgrade are the "children of the magenta line"; automation dependency was implicated in a large share of accidents. Classifying the flight as risky was never the gap. Failing to drop a tier when the automation drifted was.

The transfer to coding agents: pair every risk tier with a default automation tier, and make downgrading an explicit, pre-licensed move rather than something the agent has to be talked into.

The Tiers

The mapping is a default, not a floor. A human may raise autonomy when they have strong context, and must be able to lower it freely.

The Downgrade Trigger

Drop one automation tier, do not re-prompt at the same tier, when any of these fire:

• Repeated failure: two consecutive failed attempts of the same

shape (same file, same error class, same tool). This is the two-challenge rule: no third blind retry.

• Confidence drop: the agent cannot state its assumptions, the

alternatives it considered, or why the change is correct.

• Stakes spike: the change reaches into auth, migrations, money,

concurrency, or a destructive operation mid-task.

• Mode mismatch: the agent's stated model of the repo state does

not match reality (the coding analog of cockpit mode confusion).

On a downgrade, switch to the lower tier's division of labor, run a read-only diagnostic, and have the human (or an independent checker) re-establish what is actually true before proceeding.

Relationship to Verification Gates

Verification gates (see verification-gates.md) and automation tiers are complementary. The gate says what must pass before the change is accepted; the automation tier says who holds the pen while it is produced. A RED change runs both: A1 assisted authorship and the RED verification gate, including independent verification (see imbue:proof-of-work module independent-verification.md).

Integration

For orchestrators, carry the automation tier alongside the risk tier in task metadata:

{
  "metadata": {
    "risk_tier": "RED",
    "automation_tier": "A1",
    "downgrade_reason": null
  }
}

When a downgrade trigger fires, record the new tier and the reason, so the audit trail shows where autonomy was reduced and why. Mode selection in imbue:assisted-mastery reads the automation tier: A0/A1 imply explain mode, A2/A3 imply produce mode.

Heuristic Classifier

Pattern-Based Classification Rules

The classifier evaluates task risk by matching affected file paths against pattern rules. Higher-tier matches take precedence.

CRITICAL Patterns

migrations/*delete*        # Destructive migration
migrations/*drop*          # Table/column drops
*.sql DROP                 # Raw SQL drops
*.sql TRUNCATE             # Data truncation
security/credentials*      # Credential management
**/secrets*                # Secret files
deploy/production*         # Production deployment
infrastructure/prod*       # Production infrastructure
**/data-deletion*          # Data deletion scripts

RED Patterns

migrations/*               # Any database migration
auth/*                     # Authentication modules
**/authentication*         # Auth-related files
**/authorization*          # Authorization logic
*.env*                     # Environment configuration
database/*schema*          # Database schema definitions
**/encryption*             # Encryption modules
**/security/*              # Security directory
**/permissions*            # Permission definitions
**/api/schema*             # API schema (breaking changes)
**/shared/types*           # Shared type definitions (cross-module)

YELLOW Patterns

src/components/*           # UI components (user-visible)
routes/*                   # Route definitions
views/*                    # View layer
**/api/endpoints*          # API endpoints
**/api/routes*             # API route handlers
**/services/*              # Service layer
**/middleware/*            # Middleware (request handling)
**/config/*                # Application configuration
**/templates/*             # Templates (user-visible)
**/styles/*                # Stylesheets (user-visible)

GREEN (Default)

Everything not matching above patterns, including:

tests/*                    # Test files
docs/*                     # Documentation
**/*.md                    # Markdown files
**/utils/*                 # Utility functions
**/helpers/*               # Helper functions
**/types/*                 # Type definitions (module-local)
**/constants*              # Constants
**/__tests__/*             # Test directories
**/fixtures/*              # Test fixtures
**/mocks/*                 # Mock files

Additional Classification Dimensions

Change Type Multiplier

File Count Escalation

Dependency Depth

If the changed file is imported by many other files (high fan-out), escalate:

Classification Algorithm

function classify(task):
    tier = GREEN

    for file in task.affected_files:
        pattern_tier = match_patterns(file.path)
        tier = max(tier, pattern_tier)

    # Apply change type multiplier (escalate by 1 tier, capped at CRITICAL)
    if any(file.change_type == DELETE for file in task.affected_files):
        TIERS = [GREEN, YELLOW, RED, CRITICAL]
        tier = TIERS[min(TIERS.index(tier) + 1, len(TIERS) - 1)]

    # Apply file count escalation
    if len(task.affected_files) >= 11:
        tier = max(tier, RED)
    elif len(task.affected_files) >= 6:
        tier = max(tier, YELLOW)

    # Apply dependency depth (if analyzable)
    max_importers = max(count_importers(f) for f in task.affected_files)
    if max_importers >= 16:
        tier = max(tier, RED)
    elif max_importers >= 6:
        tier = max(tier, YELLOW)

    return tier

Readiness Levels: 4-Tier Risk Classification

A graduated risk system with required controls at each level.

Purpose

Readiness Levels classify tasks by risk level before execution. Higher levels require more controls, verification, and oversight. This prevents high-risk changes from being treated casually and ensures appropriate safeguards are in place.

Quick Classification

Ask these questions in order. Stop at the first "yes":

1. Is the action irreversible? → Level 3 (Critical) 2. Does it involve security/compliance/data integrity? → Level 2 (Elevated) 3. Is it user-visible or affects multiple files? → Level 1 (Watch) 4. Otherwise → Level 0 (Routine)

When to Apply

Apply Readiness Levels when:

• Starting any task that modifies code or configuration
• Planning parallel agent work (determine verification needs)
• Reviewing PRs (check that controls match the level)
• Before executing any task marked in an implementation plan

Do NOT apply when:

• The change is documentation-only with no code implications
• The work is purely exploratory with no production impact
• You're just reading files (no modification)

Getting Started

1. Assess the task using the Quick Classification questions 2. Find the matching level in Level Definitions below 3. Check all required controls listed for that level 4. Document any additional controls you choose to add 5. Never skip required controls; you may add optional ones

Why Four Levels

Four levels balance granularity with usability:

• Too few levels: Can't distinguish between "needs review" and

"needs human approval"

• Too many levels: People stop using the system because it's

too complex

The 0-3 scale maps naturally to: Routine/Watch/Elevated/Critical. Each level has a clear escalation trigger and distinct required controls. The gap between levels is meaningful, not arbitrary.

This pattern emerged from observing that teams with simple, actionable risk frameworks actually use them, while teams with complex matrices create work that everyone ignores.

Level Definitions

Level 0: Routine

When to use:

• Low blast radius (changes affect single file or function)
• Easy rollback (simple git revert or file restore)
• No user-visible changes
• No data integrity implications

Required controls:

• [ ] Basic validation (tests pass, lint clean)
• [ ] Rollback step documented (even if trivial)

Example tasks:

• Adding a new utility function
• Updating internal documentation
• Refactoring a single function's internals
• Adding a new test case

Level 1: Watch

When to use:

• User-visible changes (UI, API, behavior)
• Moderate impact (affects multiple files or users)
• Configuration changes
• Dependency version updates

Required controls:

• [ ] Independent review (code review or pair programming)
• [ ] Negative test (verify what shouldn't happen doesn't happen)
• [ ] Rollback note (how to revert, estimated impact)
• [ ] Risk assessment checklist completed

Example tasks:

• Adding a new API endpoint
• Changing error messages
• Updating a dependency
• Modifying configuration files

Level 2: Elevated

When to use:

• Security implications (auth, encryption, permissions)
• Compliance requirements (audit logging, data retention)
• Data integrity (migrations, schema changes)
• Performance-critical paths

Required controls:

• [ ] Adversarial review (challenge the approach)
• [ ] Risk assessment checklist completed and reviewed
• [ ] Go/no-go checkpoint (explicit approval before proceeding)
• [ ] Staged rollout plan (canary, gradual, or feature flag)
• [ ] Monitoring/alerting in place for production

Example tasks:

• Changing authentication flow
• Database schema migration
• Adding audit logging
• Performance optimization in hot path

Level 3: Critical

When to use:

• Irreversible actions (data deletion, contract changes)
• Regulated domains (healthcare, finance, PII)
• Safety-sensitive systems (infrastructure, access control)
• Major architectural changes

Required controls:

• [ ] Minimal scope (smallest possible change)
• [ ] Human confirmation (explicit user approval, not automated)
• [ ] Two-step verification (separate approval and execution)
• [ ] Contingency plan (what if it goes wrong despite controls)
• [ ] Dry run or simulation if possible
• [ ] Stakeholder notification

Example tasks:

• Deleting user data
• Changing payment processing
• Modifying access control rules
• Infrastructure changes affecting production

Level Selection Decision Tree

START
  │
  ├─ Is the action irreversible? ────────────────── YES ─→ Level 3
  │
  ├─ Does it involve security/compliance/data? ─── YES ─→ Level 2
  │
  ├─ Is it user-visible or multi-file? ─────────── YES ─→ Level 1
  │
  └─ Otherwise ──────────────────────────────────────────→ Level 0

Risk Assessment Checklist

Required for Level 1 and above. Answer these questions before proceeding:

1. What could fail in production?

• List specific failure scenarios

2. How would we detect it quickly?

• Monitoring, alerts, user reports

3. What is the fastest safe rollback?

• Specific commands or steps

4. What dependency could invalidate this plan?

• External services, data sources, assumptions

5. What assumption is least certain?

• What might we be wrong about

Document answers in the task notes or commit message.

Integration Points

With attune:war-room-checkpoint

Tasks classified as Level 2 or 3 should trigger a war-room checkpoint before execution:

if readiness_level >= 2:
    invoke Skill(attune:war-room-checkpoint)

With leyline:damage-control

Level 1+ tasks should have risk assessment checklist answers documented before marking complete:

if readiness_level >= 1:
    require risk_assessment_checklist in task_notes

With egregore:quality-gate

Quality gates should verify controls are present based on level:

verify_controls(readiness_level):
    if level >= 0: require basic_validation
    if level >= 1: require review, negative_test, rollback_note
    if level >= 2: require adversarial_review, go_no_go
    if level >= 3: require human_confirmation, two_step

Level Escalation

Tasks may be escalated to a higher level if:

• New information reveals higher risk
• Scope expands beyond original assessment
• Dependencies introduce complexity
• User requests additional caution

Never de-escalate without explicit user approval.

Quick Reference Card

┌─────────────────────────────────────────────────────────────┐
│ READINESS LEVELS QUICK REFERENCE                            │
├─────────┬──────────────────────────────────────────────────┤
│ Level   │ 0 Routine   │ 1 Watch    │ 2 Elevated│ 3 Critical│
├─────────┼──────────────┼────────────┼───────────┼───────────┤
│ Blast   │ Low          │ Moderate   │ High      │ Critical  │
│ Rollback│ Easy         │ Possible   │ Complex   │ Difficult │
│ Review  │ Self         │ Peer       │ Adversary │ Stakehold │
│ Approve │ Auto         │ Reviewer   │ Checkpt   │ Human 2stp│
└─────────┴──────────────┴────────────┴───────────┴───────────┘

Mapping to Existing Risk Tiers

Use Readiness Levels for new documentation. The existing GREEN/YELLOW/RED/CRITICAL system remains for backward compatibility.

Tier Definitions

Tier Table

GREEN: Safe

Scope: Single file, trivially reversible (git checkout -- <file>)

Criteria:

• Changes confined to a single file
• No user-visible behavior change (or change is additive-only)
• Easily reverted with a single git operation
• No security, data, or infrastructure implications

Typical files: Tests, documentation, utility functions, comments, type annotations, formatting

Verification: None required

---

YELLOW: Caution

Scope: Module-level changes, user-visible modifications

Criteria:

• Changes affect multiple files within a single module
• User-visible behavior changes (UI, API responses, CLI output)
• Revertible but requires coordination (multiple files to revert)
• No security or data integrity implications

Typical files: Components, routes, views, service layer methods, configuration

Verification: Conflict check and test pass

---

RED: Danger

Scope: Cross-module changes, security-sensitive, data-affecting

Criteria:

• Changes span multiple modules or architectural boundaries
• Security implications (authentication, authorization, encryption)
• Data integrity implications (schema changes, data transformations)
• Complex revert requiring migration or data recovery

Typical files: Database migrations, authentication modules, encryption, API schemas, shared types

Verification: War-room-checkpoint RS scoring, full test suite, and code review

---

CRITICAL: Stop

Scope: Irreversible changes, regulated operations, production impact

Criteria:

• Destructive operations that cannot be undone (data deletion, table drops)
• Production deployment or infrastructure changes
• Regulatory or compliance implications
• Changes to security credentials or access controls

Typical files: Production configs, data deletion scripts, deployment manifests, security credentials, compliance-related code

Verification: War-room-checkpoint RS scoring and human approval before execution

File Pattern Heuristics per Tier

See heuristic-classifier.md for the full pattern-to-tier mapping.

Override Mechanism

Manual Escalation

Any task can be manually escalated to a higher tier:

{
  "metadata": {
    "risk_tier": "RED",
    "risk_override": {
      "original_tier": "YELLOW",
      "escalated_by": "team-lead",
      "reason": "This component handles PII data"
    }
  }
}

Rules:

• Escalation (lower → higher) is always permitted
• De-escalation (higher → lower) requires explicit justification
• CRITICAL can only be de-escalated by human decision
• Override reason is mandatory and logged

Automatic Escalation

The classifier automatically escalates when:

• File count exceeds module boundary (YELLOW → RED)
• Security-sensitive imports detected in any file (→ RED minimum)
• Destructive operations detected in any file (→ CRITICAL)
• Task modifies files across 3+ top-level directories (→ RED minimum)

Verification Gates

Per-Tier Requirements

GREEN: No Gates

No verification required. Agent completes task and marks as done.

Task complete → Mark completed

YELLOW: Standard Gates

Task complete
    → Conflict check (git status, no uncommitted conflicts)
    → Test pass (affected test files + related tests)
    → Mark completed

Conflict check: Verify no merge conflicts exist with other in-progress tasks. If agent-teams are active, check team inbox for conflict alerts.

Test pass: Run tests directly related to changed files. Full test suite not required.

RED: Enhanced Gates

Task complete
    → Invoke Skill(attune:war-room-checkpoint) for RS scoring
    → Full test suite pass
    → Code review (lead agent or human)
    → Mark completed (only after review approval)

War-room-checkpoint: Produces a Reversibility Score (RS) confirming the risk assessment. If RS is lower than expected, the task may be downgraded.

Full test suite: All tests must pass, not just those related to changed files.

Code review: Lead agent reviews changes for correctness, security implications, and architectural alignment. For tasks touching auth/security, human review is strongly recommended.

CRITICAL: Maximum Gates

Task complete
    → Invoke Skill(attune:war-room-checkpoint) for RS scoring
    → Human approval REQUIRED (explicit confirmation)
    → Full test suite pass
    → Deployment review (if applicable)
    → Mark completed (only after human approval)

Human approval: The system must pause and present changes to the human for explicit approval before marking the task complete. No automated bypass.

Parallel Execution Safety Matrix

Risk tiers constrain which tasks can execute in parallel:

Prohibited Combinations

RED and RED: Two high-risk tasks running simultaneously create compounding risk. Merge conflicts between RED tasks could produce dangerous states. Execute sequentially.

Any and CRITICAL: CRITICAL tasks require dedicated oversight. Only GREEN tasks may run in parallel, since they cannot interfere. All YELLOW, RED, and CRITICAL tasks must wait.

Conflict Monitoring for Mixed-Tier Parallel

When running YELLOW and RED in parallel:

• Lead monitors for file overlap continuously
• RED task has priority in any conflict
• YELLOW task pauses if conflict detected
• Lead resolves before either continues

Gate Failure Handling

When a verification gate fails:

Gate failures do not automatically escalate the risk tier. The task remains at its classified tier but cannot complete until gates pass.