Codewalkers/docs/deviation-rules.md

Deviation Rules

During execution, agents discover work not in the original plan. These rules define how to handle deviations automatically, without asking for permission (except Rule 4).

The Four Rules

Rule 1: Auto-Fix Bugs

No permission needed.

Fix immediately when encountering:

• Broken code (syntax errors, runtime errors)
• Logic errors (wrong conditions, off-by-one)
• Security issues (injection vulnerabilities, exposed secrets)
• Type errors (TypeScript violations)

deviation:
  rule: 1
  type: bug_fix
  description: "Fixed null reference in user lookup"
  location: src/services/auth.ts:45
  original_code: "user.email.toLowerCase()"
  fixed_code: "user?.email?.toLowerCase() ?? ''"
  reason: "Crashes when user not found"

Rule 2: Auto-Add Missing Critical Functionality

No permission needed.

Add immediately when clearly required:

• Error handling (try/catch for external calls)
• Input validation (user input, API boundaries)
• Authentication checks (protected routes)
• CSRF protection
• Rate limiting (if pattern exists in codebase)

deviation:
  rule: 2
  type: missing_critical
  description: "Added input validation to createUser"
  location: src/api/users.ts:23
  added: "Zod schema validation for email, password length"
  reason: "API accepts any input without validation"

Rule 3: Auto-Fix Blocking Issues

No permission needed.

Fix immediately when blocking task completion:

• Missing dependencies (npm install)
• Broken imports (wrong paths, missing exports)
• Configuration errors (env vars, tsconfig)
• Build failures (compilation errors)

deviation:
  rule: 3
  type: blocking_issue
  description: "Added missing zod dependency"
  command: "npm install zod"
  reason: "Import fails without package"

Rule 4: ASK About Architectural Changes

Permission required.

Stop and ask user before:

• New database tables or major schema changes
• New services or major component additions
• Changes to API contracts
• New external dependencies (beyond obvious needs)
• Authentication/authorization model changes

deviation:
  rule: 4
  type: architectural_change
  status: PENDING_APPROVAL
  description: "Considering adding Redis for session storage"
  current: "Sessions stored in SQLite"
  proposed: "Redis for distributed session storage"
  reason: "Multiple server instances need shared sessions"
  question: "Should we add Redis, or use sticky sessions instead?"

---

Decision Tree

Encountered unexpected issue
         │
         ▼
    Is it broken code?
    (errors, bugs, security)
         │
    YES ─┴─ NO
     │      │
     ▼      ▼
   Rule 1   Is critical functionality missing?
   Auto-fix (validation, auth, error handling)
              │
         YES ─┴─ NO
          │      │
          ▼      ▼
        Rule 2   Is it blocking task completion?
        Auto-add (deps, imports, config)
                   │
              YES ─┴─ NO
               │      │
               ▼      ▼
             Rule 3   Is it architectural?
             Auto-fix (tables, services, contracts)
                        │
                   YES ─┴─ NO
                    │      │
                    ▼      ▼
                  Rule 4   Ignore or note
                  ASK      for future

---

Documentation Requirements

All deviations MUST be documented in SUMMARY.md:

# 2-3-SUMMARY.md
phase: 2
plan: 3

deviations:
  - rule: 1
    type: bug_fix
    description: "Fixed null reference in auth service"
    location: src/services/auth.ts:45

  - rule: 2
    type: missing_critical
    description: "Added Zod validation to user API"
    location: src/api/users.ts:23-45

  - rule: 3
    type: blocking_issue
    description: "Installed missing jose dependency"
    command: "npm install jose"

  - rule: 4
    type: architectural_change
    status: APPROVED
    description: "Added refresh_tokens table"
    approved_by: user
    approved_at: 2024-01-15T10:30:00Z

---

Deviation Tracking in Tasks

When a deviation is significant, create tracking:

Minor Deviations

Log in SUMMARY.md, no separate task.

Major Deviations (Rule 4)

Create a decision record:

INSERT INTO task_history (
  task_id,
  field,
  old_value,
  new_value,
  changed_by
) VALUES (
  'current-task-id',
  'deviation',
  NULL,
  '{"rule": 4, "description": "Added Redis", "approved": true}',
  'worker-123'
);

Deviations That Spawn Work

If fixing a deviation requires substantial work:

1. Complete current task
2. Create new task for deviation work
3. Link new task as dependency if blocking
4. Continue with original plan

---

Examples by Category

Rule 1: Bug Fixes

Issue	Fix	Documentation
Undefined property access	Add optional chaining	Note in summary
SQL injection vulnerability	Use parameterized query	Note + security flag
Race condition in async code	Add proper await	Note in summary
Incorrect error message	Fix message text	Note in summary

Rule 2: Missing Critical

Gap	Addition	Documentation
No input validation	Add Zod/Yup schema	Note in summary
No error handling	Add try/catch + logging	Note in summary
No auth check	Add middleware	Note in summary
No CSRF token	Add csrf protection	Note + security flag

Rule 3: Blocking Issues

Blocker	Resolution	Documentation
Missing npm package	npm install	Note in summary
Wrong import path	Fix path	Note in summary
Missing env var	Add to .env.example	Note in summary
TypeScript config issue	Fix tsconfig	Note in summary

Rule 4: Architectural (ASK FIRST)

Change	Why Ask	Question Format
New DB table	Schema is contract	"Need users_sessions table. Create it?"
New service	Architectural decision	"Extract auth to separate service?"
API contract change	Breaking change	"Change POST /users response format?"
New external dep	Maintenance burden	"Add Redis for caching?"

---

Integration with Verification

Deviations are inputs to verification:

1. Verifier loads SUMMARY.md with deviation list
2. Bug fixes (Rule 1) verify the fix doesn't break tests
3. Critical additions (Rule 2) verify they're properly integrated
4. Blocking fixes (Rule 3) verify build/tests pass
5. Architectural changes (Rule 4) verify they match approved design

---

Escalation Path

If unsure which rule applies:

1. Default to Rule 4 (ask) rather than making wrong assumption
2. Document uncertainty in deviation notes
3. Include reasoning for why you're asking

deviation:
  rule: 4
  type: uncertain
  description: "Adding caching layer to API responses"
  reason: "Could be Rule 2 (performance is critical) or Rule 4 (new infrastructure)"
  question: "Is Redis caching appropriate here, or should we use in-memory?"