Define agent failure taxonomy with structured error codes

[snipcodeit]

Description

Create a formal taxonomy of GSD agent failure modes: timeout (agent exceeded turn limit), malformed-output (agent returned unparseable result), partial-completion (agent completed some but not all tasks), hallucination (agent claimed success but artifacts missing), permission-denied (agent blocked by hook or sandbox). Each failure type gets a structured error code, severity level, and recommended recovery action. Store taxonomy in lib/agent-errors.cjs.

Acceptance Criteria

• Define agent failure taxonomy with structured error codes

Milestone Context

Milestone	v8 — Agent Reliability & Failure Recovery
Phase	Phase 44: Agent Failure Taxonomy & Diagnostic Logging
GSD Route	plan-phase
Phase Position	Phase 1 of 3 in milestone

Milestone Goal

Build automated fallback strategies, retry policies, structured diagnostic logging, and checkpoint/resume capabilities for GSD agent failures

Phase Goal

Define the classification system for agent failure modes and build structured diagnostic logging

Dependencies

none

Scope Hints

• Estimated route: plan-phase
• Labels: reliability,architecture

[snipcodeit]

MGW · milestone-start · 2026-03-06T06:32:57Z

Milestone Started: v8 — Agent Reliability & Failure Recovery

Issues	9
Phases	3 (44: Taxonomy & Logging, 45: Retry Policies, 46: Checkpoint & Resume)
Mode	Autonomous

Execution Order

#	Issue	Phase	Depends On
1	#229 — Define agent failure taxonomy	44	—
2	#230 — Build structured diagnostic logger	44	#229
3	#231 — Add diagnostic capture hooks	44	#230
4	#232 — Implement retry policy engine	45	#229
5	#233 — Add model fallback strategy	45	#232
6	#234 — Implement graceful degradation	45	#232
7	#235 — Design checkpoint schema	46	—
8	#236 — Implement checkpoint writes	46	#235
9	#237 — Add resume detection/auto-resume	46	#236

[snipcodeit]

MGW · work-started · 2026-03-06T06:33:39Z
Milestone: v8 — Agent Reliability & Failure Recovery | Phase 44: Agent Failure Taxonomy & Diagnostic Logging

Work Started

Issue	#229 — Define agent failure taxonomy with structured error codes
Route	plan-phase
Phase	44 of 46 — Agent Failure Taxonomy & Diagnostic Logging
Milestone	v8 — Agent Reliability & Failure Recovery

Milestone Progress (0/9 complete)

#	Issue	Status	PR
229	Define agent failure taxonomy	◆ In Progress	—
230	Build structured diagnostic logger	○ Pending	—
231	Add diagnostic capture hooks	○ Pending	—
232	Implement retry policy engine	○ Pending	—
233	Add model fallback strategy	○ Pending	—
234	Implement graceful degradation	○ Pending	—
235	Design checkpoint schema	○ Pending	—
236	Implement checkpoint writes	○ Pending	—
237	Add resume detection/auto-resume	○ Pending	—

[snipcodeit]

---

phase: quick-8
plan: 1
type: feature
wave: 1
depends_on: []
files_modified:

• lib/agent-errors.cjs
  autonomous: true
  requirements:
• Define 5 agent failure types with structured error codes
• Each failure type has severity level and recommended recovery action
• Integrate with existing error hierarchy (lib/errors.cjs)
• Follow existing code patterns from lib/retry.cjs
  must_haves:
  truths:
  • agent-errors.cjs exports AGENT_FAILURE_TYPES object with all 5 failure types
  • Each failure type has code, name, severity, description, and recovery fields
  • Error codes follow pattern AGENT_ERR_XXX
  • Severity levels are critical, high, medium, low
  • Module exports classifyAgentFailure() function
  • Module exports getRecoveryAction() function
  • Module exports AgentFailureError class extending MgwError
    artifacts:
  • lib/agent-errors.cjs
    key_links:
  • lib/errors.cjs (MgwError base class)
  • lib/retry.cjs (failure taxonomy pattern reference)

---

Quick Task 8: Define Agent Failure Taxonomy

Objective

Create lib/agent-errors.cjs with a formal taxonomy of GSD agent failure modes, structured error codes, severity levels, and recommended recovery actions.

Context

The MGW pipeline spawns GSD agents (planner, executor, verifier, plan-checker) via Task() calls. These agents can fail in several distinct ways that require different handling strategies. Currently, failures are classified generically via lib/retry.cjs (transient/permanent/needs-info). This task creates an agent-specific failure taxonomy that sits alongside the existing retry infrastructure.

The existing lib/errors.cjs provides the MgwError base class and typed error hierarchy. The new AgentFailureError class will extend MgwError following the same patterns.

Tasks

Task 1: Create lib/agent-errors.cjs with failure taxonomy

• files: lib/agent-errors.cjs
• action: Create the module with:
  1. AGENT_FAILURE_TYPES — frozen object defining 5 failure types:
     • timeout (AGENT_ERR_TIMEOUT) — agent exceeded turn limit; severity: high; recovery: retry with reduced scope
     • malformed-output (AGENT_ERR_MALFORMED_OUTPUT) — agent returned unparseable result; severity: high; recovery: retry with explicit format instructions
     • partial-completion (AGENT_ERR_PARTIAL_COMPLETION) — agent completed some but not all tasks; severity: medium; recovery: spawn continuation agent for remaining tasks
     • hallucination (AGENT_ERR_HALLUCINATION) — agent claimed success but artifacts missing; severity: critical; recovery: reject results, retry with verification-first approach
     • permission-denied (AGENT_ERR_PERMISSION_DENIED) — agent blocked by hook or sandbox; severity: high; recovery: escalate to human, check sandbox config
  2. SEVERITY_LEVELS — ordered severity enum (critical > high > medium > low)
  3. AgentFailureError class extending MgwError with agentType, failureType, artifacts fields
  4. classifyAgentFailure(error, context) — classify raw errors into agent failure types
  5. getRecoveryAction(failureType) — return the recommended recovery action for a failure type
  6. isRetryable(failureType) — return whether a failure type is safe to auto-retry
• verify: node -e "const m = require('./lib/agent-errors.cjs'); console.log(Object.keys(m.AGENT_FAILURE_TYPES).length === 5); console.log(typeof m.classifyAgentFailure === 'function'); console.log(typeof m.getRecoveryAction === 'function');"
• done: lib/agent-errors.cjs exists with all 5 failure types, error class, and utility functions

Verification

• All 5 failure types defined with code, name, severity, description, recovery
• AgentFailureError extends MgwError correctly
• classifyAgentFailure returns valid failure type for each known error pattern
• getRecoveryAction returns actionable recovery for each failure type
• Module follows existing coding patterns from lib/errors.cjs and lib/retry.cjs
• No external dependencies added

Success Criteria

• require('./lib/agent-errors.cjs') loads without error
• All 5 failure types are defined and frozen
• Error class properly extends MgwError
• Classification function handles all 5 failure patterns
• Recovery actions are specific and actionable

Output

• lib/agent-errors.cjs — Agent failure taxonomy module

[snipcodeit]

Quick Task 8 Summary: Agent Failure Taxonomy

One-liner

Created lib/agent-errors.cjs with a formal taxonomy of 5 GSD agent failure modes, structured error codes, severity levels, and recovery actions.

What was done

Task 1: Create lib/agent-errors.cjs with failure taxonomy

• Status: Complete
• Files created: lib/agent-errors.cjs (384 lines)
• Commit: feat(lib): define agent failure taxonomy with structured error codes

Key files

File	Action	Description
lib/agent-errors.cjs	Created	Agent failure taxonomy module

Technical details

Failure Types Defined

Code	Name	Severity	Retryable
AGENT_ERR_TIMEOUT	timeout	high	yes
AGENT_ERR_MALFORMED_OUTPUT	malformed-output	high	yes
AGENT_ERR_PARTIAL_COMPLETION	partial-completion	medium	yes
AGENT_ERR_HALLUCINATION	hallucination	critical	no
AGENT_ERR_PERMISSION_DENIED	permission-denied	high	no

Exports

• AGENT_FAILURE_TYPES — frozen object with all 5 failure type definitions
• SEVERITY_LEVELS — ordered severity enum (critical > high > medium > low)
• AgentFailureError — Error class extending MgwError with agentType, failureType, artifacts fields
• classifyAgentFailure(error, context) — pattern + context-based classification (returns null for unrecognized errors so caller can fall back to lib/retry.cjs)
• getRecoveryAction(failureType) — recommended recovery action lookup
• isRetryable(failureType) — retry eligibility check
• compareSeverity(a, b) — severity comparison utility
• getFailureByCode(code) — reverse lookup by error code

Integration points

• Extends MgwError from lib/errors.cjs for unified error hierarchy
• Complements lib/retry.cjs which handles pipeline-level retry (transient/permanent/needs-info)
• classifyAgentFailure() returns null for unrecognized errors, allowing fallback to classifyFailure() from retry.cjs

Verification

• All 5 failure types defined with complete fields (code, name, severity, description, recovery, retryable)
• AgentFailureError correctly extends MgwError
• 12/12 classification test cases passed (message patterns + context-based)
• Recovery actions return correct retryable/severity for all types
• Module loads without errors, no external dependencies added

Decisions

• Hallucination is classified as critical severity (not high) because it represents agents producing misleading results — the most dangerous failure mode
• Only timeout, malformed-output, and partial-completion are auto-retryable; hallucination and permission-denied require human intervention
• classifyAgentFailure() returns null (not a default type) for unrecognized errors to avoid false classifications
• Context-based classification (artifact mismatch, task counts) takes priority over message patterns for higher confidence

[snipcodeit]

Quick Task 8 Verification: Agent Failure Taxonomy

VERIFICATION PASSED

All must_haves from the plan have been verified against the actual codebase.

Must-Have Verification

#	Must-Have	Status	Evidence
1	agent-errors.cjs exports AGENT_FAILURE_TYPES with all 5 failure types	PASS	Object.keys(AGENT_FAILURE_TYPES).length === 5: timeout, malformed-output, partial-completion, hallucination, permission-denied
2	Each failure type has code, name, severity, description, recovery	PASS	All 5 types verified with complete field sets
3	Error codes follow AGENT_ERR_XXX pattern	PASS	AGENT_ERR_TIMEOUT, AGENT_ERR_MALFORMED_OUTPUT, AGENT_ERR_PARTIAL_COMPLETION, AGENT_ERR_HALLUCINATION, AGENT_ERR_PERMISSION_DENIED
4	Severity levels are critical, high, medium, low	PASS	SEVERITY_LEVELS defines all 4 with numeric weights
5	Module exports classifyAgentFailure()	PASS	Function exists, 12/12 test cases passed
6	Module exports getRecoveryAction()	PASS	Returns { action, retryable, severity } for all 5 types
7	AgentFailureError extends MgwError	PASS	new AgentFailureError() instanceof MgwError === true

Artifact Verification

Artifact	Path	Exists	Valid
Agent errors module	lib/agent-errors.cjs	Yes	Yes — loads without errors

Key Link Verification

File	Referenced	Exists
lib/errors.cjs	MgwError base class	Yes
lib/retry.cjs	Failure taxonomy patterns	Yes

Functional Tests

Test	Result
Module loads without errors	PASS
All 5 failure types frozen	PASS
classifyAgentFailure — timeout patterns	PASS (2/2)
classifyAgentFailure — malformed-output patterns	PASS (2/2)
classifyAgentFailure — partial-completion patterns	PASS (2/2)
classifyAgentFailure — hallucination patterns	PASS (2/2)
classifyAgentFailure — permission-denied patterns	PASS (3/3)
classifyAgentFailure — unknown returns null	PASS
classifyAgentFailure — context-based artifact mismatch	PASS
classifyAgentFailure — context-based partial tasks	PASS
getRecoveryAction — all types	PASS
isRetryable — correct for all types	PASS
AgentFailureError extends MgwError	PASS
AgentFailureError.getSeverity()	PASS
AgentFailureError.isRetryable()	PASS

Summary

All 7 must-haves verified. All artifacts exist and are valid. All 15 functional tests passed. The agent failure taxonomy is complete and ready for use by downstream issues (#230 diagnostic logger, #232 retry policy engine).

[snipcodeit]

MGW · execution-complete · 2026-03-06T06:40:04Z
Milestone: v8 — Agent Reliability & Failure Recovery | Phase 44: Agent Failure Taxonomy & Diagnostic Logging

Execution Complete

1 atomic commit on branch issue/229-define-agent-failure-taxonomy-with-struc.

Changes: 1 file changed, 384 insertions(+)

Preparing pull request.

[snipcodeit]

MGW · pr-ready · 2026-03-06T06:41:30.348Z
Milestone: v8 — Agent Reliability & Failure Recovery | Phase 44: Agent Failure Taxonomy & Diagnostic Logging

PR Ready

PR #238 — #238

Created lib/agent-errors.cjs with a formal taxonomy of 5 GSD agent failure modes, structured error codes, severity levels, and recovery actions.

Testing procedures posted on the PR.
This issue will auto-close when the PR is merged.

Pipeline Summary

Stage	Status
Triage	done
Planning	done
Execution	done
Verification	done
PR Creation	done